Setup wizard

The setup wizard is the first screen of a fresh install, in the terminal app and in the desktop app. It connects a model provider and brings over the setup of another agent. It adds connectors and extensions. It also sets the look, the conversation display, the approval mode and the features. You can change every choice later in Settings.

The preview runs on demo data. Every step works in it, and Start begins a new run.

The steps#

The wizard leaves out a step that does not apply. Bring your setup shows only when zidane finds another agent. Connectors, Skills and Extensions show only when installs can run on this computer. Quick start keeps Welcome, Connect, Bring your setup and Ready.

A run writes only what changed. A choice that equals the default writes nothing, so it keeps following future defaults. Imports and installs start when you pass their step, so Back and Skip start nothing.

When it opens#

Each app opens the wizard on the first launch of a fresh install. An install from before the wizard never opens it on its own. When you set up one app first, the other app opens a short run on its first launch: Look, Features and Ready.

The desktop app opens without a provider. If you send a message with no provider, a "Connect a provider" card shows above the composer. The card opens Connect alone (desktop app). The terminal app needs a provider, so Connect has no Skip there. Its keys are on terminal app.

Connectors, skills and extensions#

A connector adds an MCP server to your user mcps.json. Most connectors sign in through your browser from Ready. The full list is on MCP.

Connectors and Skills open with a short tutorial: a scene that plays three steps, beside them. The steps play in turn, and a click on a step shows it. Tutorial renders the tutorial of a topic, such as <Tutorial topic="skills" />.

Skills lists the skills of a repository before you pick any. Type a source, or open a recommended one. Each skill shows its name, its description and its folder, and a pack names the repository each skill comes from. Picks can come from several sources. They install into your user skills folder once you pass the step. The skills page tells how zidane reads a source, and lists the recommended sources.

Repository or package

Browse

Recommended sources

• Matt Pocockmattpocock/skillsEngineering habits for real projects: test-driven development, code review, research and planning.
• Anthony Fu's packantfu/skills-packA hand-picked pack of skills from several authors, in one list.
• Anthony Fuantfu/skillsConventions for Vue, Nuxt, Vite, Vitest, UnoCSS and pnpm projects.
• Cursor pstackcursor/plugins/pstack/skillsPrinciples and workflows from the pstack plugin: design, verification and clear writing.
• Anthropicanthropics/skillsThe official examples: documents, spreadsheets, design, the Claude API and MCP servers.

Repository or package

Browse

All sources

Matt PocockAnthony Fu's packAnthony FuCursor pstackAnthropic

A native extension installs in one click, from the zidane release that you run. An extension that works through a connector brings it. For example, the Linear extension also adds the Linear connector. The full list is on extensions.

Autonomy#

Each choice of the Autonomy step shows what it gives you and what it prevents. The wizard and Settings show the same two sentences.

Features#

The Features step offers these switches. Some apps offer only some of them. Each one shows an example, what it gives you and what it prevents. A feature has one switch, and its parts turn on with it. For example, Browser tab also turns on Agent can use the browser. Settings keeps a switch for each part.

In your app#

zidane-ui/onboarding shows the wizard in any React app. Your app implements OnboardingHost: what the wizard reads, and the actions it asks for. If you leave out a member, the wizard hides its step or its control.

import type { OnboardingHost } from 'zidane-ui/onboarding/headless'
import { OnboardingFlow, OnboardingProvider } from 'zidane-ui/onboarding'

export function Setup({ host, onClose }: { host: OnboardingHost, onClose: () => void }) {
  return (
    <OnboardingProvider host={host} onDone={onClose}>
      <OnboardingFlow />
    </OnboardingProvider>
  )
}

With AppHostProvider, pass the host as onboarding and leave host off OnboardingProvider: it runs on the one in context (OnboardingHostProvider does the same without the rest of the app).

import { createServerClient, createServerOnboardingHost } from 'zidane-ui/adapters'

const client = createServerClient({ url: 'wss://agent.example.com', token: 'zds_…' })
const onboarding = createServerOnboardingHost({ client, mode: 'connect' })

Your own host's tests run the shared suite: describeOnboardingHostContract from zidane-ui/onboarding/testing/contract (vitest). It hands your harness a backend to build the host over, and checks the members you list (the others must be undefined).

import { describeOnboardingHostContract } from 'zidane-ui/onboarding/testing/contract'

describeOnboardingHostContract('my host', backend => ({ host: makeHost(backend) }), ['providers.saveKey', 'providers.test'])

For a demo or a test, createFixtureOnboardingHost answers every member from demo data:

import { createFixtureOnboardingHost } from 'zidane-ui/onboarding/testing'

const host = createFixtureOnboardingHost({ delayMs: 0, onCommit: result => console.log(result.settings) })

To replace a step, pass your component in the steps prop of OnboardingFlow. To run the wizard without React, use createOnboardingRun from zidane/chat/pure. The terminal app runs on it.

Parts for your own pages#

The wizard's parts also work outside it. The desktop app uses them in its Settings.

import { ConversationPresetPreview, Tutorial } from 'zidane-ui/onboarding'

<Tutorial topic="extensions" actions={<button type="button">Build an extension</button>} />
<ConversationPresetPreview settings={settings} onApply={id => applyPreset(id)} />