clawdbot/docs/wizard.md

summary, read_when

summary	read_when
CLI onboarding wizard spec (gateway + workspace + skills + daemon)	Designing or implementing the onboarding wizard Changing gateway install/setup flow

Onboarding Wizard (CLI)

Goal: single interactive flow to set up Clawdis Gateway + workspace + skills on a new machine. Uses @clack/prompts for arrow-key selection and step UX.

Scope: Local gateway only. Remote mode is info-only (no config writes).

Entry points

• clawdis onboard (primary)
• clawdis setup --wizard (alias)

Non-interactive mode

--non-interactive + flags to skip prompts. --json outputs a machine summary.

Preflight

• Runtime: Node >=22 (reuse runtime-guard).
• Detect existing files:
  • config: ~/.clawdis/clawdis.json
  • creds: ~/.clawdis/credentials/
  • sessions: ~/.clawdis/sessions/
  • workspace: ~/clawd (or configured)
• Detect available package managers: npm, pnpm, bun.
• Detect optional tools: brew, uv, go.

If config exists:

• Prompt: Keep / Modify / Reset

Reset uses trash (never rm).

Flow (interactive)

1. Mode

   • Local (full wizard)
   • Remote (info-only; no config writes)

2. Model/Auth (local only)

   • Anthropic OAuth (recommended)
   • API key
   • Minimax M2.1 (LM Studio; recommended local model)
   • Skip

3. Workspace + config

   • Default workspace: ~/clawd
   • Writes agent.workspace into ~/.clawdis/clawdis.json
   • Ensures sessions dir exists

4. Gateway config

   • Port (default 18789)
   • Bind: loopback | lan | tailnet | auto
   • Auth: token | password | off
   • Tailscale: off | serve | funnel

5. Daemon install (local only)

   • macOS: LaunchAgent
   • Linux: systemd user unit
   • Windows: Scheduled Task

6. Health

   • Start/restart daemon
   • clawdis health summary

7. Skills (recommended)

   • Read from buildWorkspaceSkillStatus
   • Show eligible vs missing requirements
   • Offer installs via preferred installer
   • Allow skip

8. Finish

   • Summary + next steps
   • Reminder: iOS/Android/macOS node apps add canvas/camera/screen/system features.

Remote mode (info-only)

• Explain where gateway runs.
• Show required steps on gateway host:
  • clawdis setup
  • clawdis gateway-daemon ...
  • OAuth file: ~/.clawdis/credentials/oauth.json
  • Workspace: ~/clawd
• No local config changes.

Config writes

Wizard writes:

• ~/.clawdis/clawdis.json
  • agent.workspace
  • agent.model + models.providers (if Minimax selected)
  • skills.install.nodeManager (npm | pnpm | bun)
  • skills.entries.<key>.env / .apiKey (if set in skills step)

Minimax M2.1 (LM Studio) config snippet

{
  agent: {
    model: "Minimax",
    allowedModels: [
      "anthropic/claude-opus-4-5",
      "lmstudio/minimax-m2.1-gs32"
    ],
    modelAliases: {
      Opus: "anthropic/claude-opus-4-5",
      Minimax: "lmstudio/minimax-m2.1-gs32"
    }
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "minimax-m2.1-gs32",
            name: "MiniMax M2.1 GS32",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

Skills install preferences

Prompt for node manager:

• npm
• pnpm
• bun

Writes:

{
  skills: {
    install: {
      nodeManager: "npm" // npm | pnpm | bun
    }
  }
}

Reset scope (decision required)

Options:

• A) Config only (~/.clawdis/clawdis.json)
• B) Config + credentials + sessions
• C) Full reset: config + credentials + sessions + workspace

Wizard should clearly list what will be removed and use trash.

Open questions

• Confirm “Remote = info-only” is final.
• Confirm reset scope default (A/B/C).