172 lines
3.9 KiB
Markdown
172 lines
3.9 KiB
Markdown
---
|
|
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: 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
|
|
|
|
```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).
|