clawdbot/docs/wizard.md

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

# Onboarding Wizard (CLI)

Goal: interactive wizards for first-run onboarding **and** ongoing reconfiguration.
Uses `@clack/prompts` for arrow-key selection and step UX.

Scope: local gateway setup plus **remote gateway client config** (no remote-side installs).

## Entry points

First run:
- `clawdis onboard` (primary)
- `clawdis setup --wizard` (alias)

Ongoing:
- `clawdis configure` (models/providers/skills/gateway/workspace)
- `clawdis doctor` (health + quick fixes)
- `clawdis update` (audit + modernize config defaults)

## 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 (configure client connection only)

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) **Providers (optional)**
   - WhatsApp: optional `clawdis login` QR flow
   - Telegram: bot token (config or env)
   - Discord: bot token (config or env)
   - Signal: `signal-cli` detection + account config + install option

6) **Daemon install (local only)**
   - macOS: LaunchAgent
   - Linux: systemd user unit
   - Windows: Scheduled Task

7) **Health**
   - Start/restart daemon
   - `clawdis health` summary

8) **Skills (recommended)**
   - Read from `buildWorkspaceSkillStatus`
   - Show eligible vs missing requirements
   - Offer installs via preferred installer
   - Allow skip

9) **Finish**
   - Summary + next steps
   - Reminder: iOS/Android/macOS node apps add canvas/camera/screen/system features.

## Remote mode (client config)

- Optional Bonjour discovery (macOS: `dns-sd`, Linux: `avahi-browse`)
- Save `gateway.remote.url` (+ optional `gateway.remote.token`)
- Token optional; omit for no-auth gateways
- Provide SSH tunnel hint when the gateway is loopback-only
- No remote installs or daemon changes from this machine

## 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)
  - `telegram.botToken`, `discord.token`, `signal.*` (if set in providers step)
  - `wizard.lastRunAt`, `wizard.lastRunVersion`, `wizard.lastRunCommit`, `wizard.lastRunCommand`, `wizard.lastRunMode`
  - `gateway.remote.url`, `gateway.remote.token` (remote mode)

WhatsApp login writes credentials to `~/.clawdis/credentials/creds.json`.

## Configure / Doctor / Update flows

`clawdis configure` offers a menu of sections:
- Model/auth
- Providers (incl Signal install)
- Gateway + daemon
- Workspace + bootstrap files
- Skills
- Health check (optional at end)

`clawdis doctor`:
- Gateway reachability
- Provider probes
- Skills status
- Quick fixes (start gateway, relink WhatsApp, prompt missing tokens)

`clawdis update`:
- Audit config vs defaults
- Suggest upgrades/changes
- Re-run key steps as needed

Each wizard run updates `wizard.*` metadata.

## Signal CLI install (wizard)

Wizard can install signal-cli from GitHub releases:
- Fetch latest release from `https://github.com/AsamK/signal-cli/releases/latest`
- Download platform asset (Linux native preferred)
- Extract under `~/.clawdis/tools/signal-cli/<version>/`
- Set `signal.cliPath` to the detected `signal-cli` binary

Notes:
- signal-cli requires Java 21 for JVM builds.
- Native builds are available for some platforms; fallback to JVM build if native not found.
- Auto-install is not supported on Windows yet.

## Minimax M2.1 (LM Studio) config snippet

```json5
{
  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:

```json5
{
  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).