milaidy 1.0.0

package/docs/start/wizard.md

@@ -0,0 +1,418 @@
+---
+summary: "CLI onboarding wizard: guided setup for gateway, workspace, channels, and skills"
+read_when:
+  - Running or configuring the onboarding wizard
+  - Setting up a new machine
+  - Scripting non-interactive onboarding
+title: "Onboarding Wizard"
+---
+
+# Onboarding Wizard (CLI)
+
+The onboarding wizard is the **recommended** way to set up Milaidy on macOS,
+Linux, or Windows (via WSL2). It configures your Gateway, workspace, channels,
+skills, and ElizaOS plugins in one guided flow.
+
+## Quick Start
+
+```bash
+# Primary entrypoint
+milaidy onboard
+
+# Fastest first chat (no channel setup needed)
+milaidy dashboard
+```
+
+## CLI Flags Reference
+
+### Mode Selection
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--mode <local\|remote>` | Gateway mode | `local` |
+| `--quickstart` | Use defaults (minimal prompts) | `false` |
+| `--advanced` | Full control over every step | `false` |
+
+### Non-Interactive Mode
+
+| Flag | Description |
+|------|-------------|
+| `--non-interactive` | Skip all prompts, use flags/defaults |
+| `--json` | Output machine-readable JSON summary |
+| `--reset` | Reset config before onboarding |
+
+### Authentication Flags
+
+| Flag | Description |
+|------|-------------|
+| `--auth-choice <choice>` | Auth method (see below) |
+| `--anthropic-api-key <key>` | Anthropic API key |
+| `--openai-api-key <key>` | OpenAI API key |
+| `--gemini-api-key <key>` | Google Gemini API key |
+| `--groq-api-key <key>` | Groq API key |
+| `--xai-api-key <key>` | XAI (Grok) API key |
+| `--openrouter-api-key <key>` | OpenRouter API key |
+| `--mistral-api-key <key>` | Mistral API key |
+| `--cohere-api-key <key>` | Cohere API key |
+| `--together-api-key <key>` | Together API key |
+| `--fireworks-api-key <key>` | Fireworks API key |
+| `--perplexity-api-key <key>` | Perplexity API key |
+| `--deepseek-api-key <key>` | DeepSeek API key |
+| `--zai-api-key <key>` | Z.AI API key |
+| `--ai-gateway-api-key <key>` | Vercel AI Gateway API key |
+| `--opencode-zen-api-key <key>` | OpenCode Zen API key |
+| `--moonshot-api-key <key>` | Moonshot API key |
+| `--synthetic-api-key <key>` | Synthetic API key |
+
+### Cloudflare AI Gateway Flags
+
+| Flag | Description |
+|------|-------------|
+| `--cloudflare-ai-gateway-account-id <id>` | Cloudflare account ID |
+| `--cloudflare-ai-gateway-gateway-id <id>` | Gateway ID |
+| `--cloudflare-ai-gateway-api-key <key>` | API key |
+
+### Auth Choice Values
+
+| Value | Description |
+|-------|-------------|
+| `apiKey` | Anthropic API key |
+| `oauth` | Anthropic OAuth (Claude Code CLI) |
+| `setup-token` | Paste Anthropic setup token |
+| `openai-api-key` | OpenAI API key |
+| `openai-codex-oauth` | OpenAI Codex OAuth |
+| `gemini-api-key` | Google Gemini API key |
+| `groq-api-key` | Groq API key |
+| `xai-api-key` | XAI API key |
+| `openrouter-api-key` | OpenRouter API key |
+| `zai-api-key` | Z.AI API key |
+| `ai-gateway-api-key` | Vercel AI Gateway |
+| `cloudflare-ai-gateway-api-key` | Cloudflare AI Gateway |
+| `moonshot-api-key` | Moonshot (Kimi) |
+| `synthetic-api-key` | Synthetic provider |
+| `opencode-zen` | OpenCode Zen |
+| `minimax` | MiniMax M2.1 |
+| `skip` | No auth configured |
+
+### Gateway Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--gateway-port <port>` | Gateway port | `18789` |
+| `--gateway-bind <bind>` | Bind address | `loopback` |
+| `--gateway-auth <mode>` | Auth mode (token, none) | `token` |
+| `--gateway-tailscale` | Enable Tailscale exposure | `false` |
+
+### Workspace Flags
+
+| Flag | Description |
+|------|-------------|
+| `--workspace <path>` | Workspace directory |
+| `--agent-dir <path>` | Agent directory |
+
+### Channel Flags
+
+| Flag | Description |
+|------|-------------|
+| `--telegram-bot-token <token>` | Telegram bot token |
+| `--discord-bot-token <token>` | Discord bot token |
+| `--slack-bot-token <token>` | Slack bot token |
+| `--slack-app-token <token>` | Slack app token |
+| `--whatsapp-token <token>` | WhatsApp token |
+| `--signal-cli-path <path>` | Signal CLI path |
+| `--skip-channels` | Skip channel setup |
+
+### Daemon Flags
+
+| Flag | Description |
+|------|-------------|
+| `--install-daemon` | Install daemon (LaunchAgent/systemd) |
+| `--skip-daemon` | Skip daemon installation |
+| `--daemon-runtime <node\|bun>` | Runtime for daemon | `node` |
+
+### Skills Flags
+
+| Flag | Description |
+|------|-------------|
+| `--skip-skills` | Skip skills installation |
+| `--skills-node-manager <npm\|pnpm\|yarn>` | Node package manager |
+
+### Model Flags
+
+| Flag | Description |
+|------|-------------|
+| `--model <provider/model>` | Default model |
+
+## QuickStart vs Advanced
+
+The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control):
+
+**QuickStart** keeps defaults:
+- Local gateway (loopback)
+- Existing or default workspace
+- Gateway port **18789**
+- Gateway auth **Token** (auto-generated)
+- Tailscale exposure **Off**
+- DMs default to **allowlist**
+
+**Advanced** exposes every step (mode, workspace, gateway, channels, daemon, skills).
+
+## Wizard Flow (Local Mode)
+
+### 1. Existing Config Detection
+
+If `~/.milaidy/milaidy.json` exists, choose:
+- **Keep** - Preserve existing config
+- **Modify** - Edit specific sections
+- **Reset** - Start fresh
+
+Reset uses `trash` (never `rm`) with scopes:
+- Config only
+- Config + credentials + sessions
+- Full reset (includes workspace)
+
+### 2. Model/Auth
+
+Provider options:
+- **Anthropic API key** (recommended) - Uses `ANTHROPIC_API_KEY`
+- **Anthropic OAuth** - Reuses `~/.claude/.credentials.json` or Keychain
+- **Anthropic setup-token** - Paste from `claude setup-token`
+- **OpenAI Codex OAuth** - Browser flow with `code#state`
+- **OpenAI API key** - Uses `OPENAI_API_KEY`
+- **OpenCode Zen** - Multi-model proxy
+- **Vercel AI Gateway** - Multi-model proxy
+- **Cloudflare AI Gateway** - Account + Gateway IDs
+- **MiniMax M2.1** - Auto-configured
+- **Moonshot (Kimi K2)** - Auto-configured
+- **Synthetic** - Anthropic-compatible
+- **Skip** - Configure later
+
+Credentials stored in:
+- `~/.milaidy/credentials/oauth.json`
+- `~/.milaidy/agents/<agentId>/agent/auth-profiles.json`
+
+### 3. Workspace
+
+- Default: `~/.milaidy/workspace`
+- Seeds bootstrap files for agent ritual
+- See [Agent Workspace](/concepts/agent-workspace)
+
+### 4. Gateway
+
+- Port, bind, auth mode, Tailscale exposure
+- **Token** recommended even for loopback
+- Non-loopback binds always require auth
+
+### 5. Channels
+
+Configure messaging channels:
+- [WhatsApp](/channels/whatsapp) - QR login
+- [Telegram](/channels/telegram) - Bot token
+- [Discord](/channels/discord) - Bot token
+- [Google Chat](/channels/googlechat) - Service account
+- [Mattermost](/channels/mattermost) - Plugin, bot token
+- [Signal](/channels/signal) - signal-cli install
+- [BlueBubbles](/channels/bluebubbles) - iMessage (recommended)
+- [iMessage](/channels/imessage) - Legacy imsg CLI
+
+DM security: default is pairing. First DM sends a code; approve via
+`milaidy pairing approve <channel> <code>`.
+
+### 6. Daemon Install
+
+- **macOS:** LaunchAgent (requires logged-in session)
+- **Linux/WSL2:** systemd user unit with lingering enabled
+
+**Runtime:** Node (recommended, required for WhatsApp/Telegram)
+
+### 7. Health Check
+
+Starts Gateway and runs `milaidy health`.
+
+Tip: `milaidy status --deep` adds gateway probes.
+
+### 8. Skills (Recommended)
+
+- Reads available skills and requirements
+- Chooses node manager (npm/pnpm)
+- Installs optional dependencies
+
+### 9. Finish
+
+Summary + next steps, including mobile app options.
+
+## Non-Interactive Examples
+
+### Anthropic API Key
+
+```bash
+milaidy onboard --non-interactive \
+  --mode local \
+  --auth-choice apiKey \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback \
+  --install-daemon \
+  --daemon-runtime node \
+  --skip-skills
+```
+
+### Google Gemini
+
+```bash
+milaidy onboard --non-interactive \
+  --mode local \
+  --auth-choice gemini-api-key \
+  --gemini-api-key "$GEMINI_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback
+```
+
+### OpenAI Codex
+
+```bash
+milaidy onboard --non-interactive \
+  --mode local \
+  --auth-choice openai-api-key \
+  --openai-api-key "$OPENAI_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback
+```
+
+### Vercel AI Gateway
+
+```bash
+milaidy onboard --non-interactive \
+  --mode local \
+  --auth-choice ai-gateway-api-key \
+  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback
+```
+
+### Cloudflare AI Gateway
+
+```bash
+milaidy onboard --non-interactive \
+  --mode local \
+  --auth-choice cloudflare-ai-gateway-api-key \
+  --cloudflare-ai-gateway-account-id "your-account-id" \
+  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
+  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback
+```
+
+### OpenCode Zen
+
+```bash
+milaidy onboard --non-interactive \
+  --mode local \
+  --auth-choice opencode-zen \
+  --opencode-zen-api-key "$OPENCODE_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback
+```
+
+## Remote Mode
+
+Remote mode configures a local client to connect to a Gateway elsewhere.
+
+What you set:
+- Remote Gateway URL (`ws://...`)
+- Token if auth is required
+
+Notes:
+- No remote installs or daemon changes
+- Use SSH tunneling for loopback-only Gateways
+- Discovery: Bonjour (macOS), Avahi (Linux)
+
+## Multi-Agent Setup
+
+Add isolated agents with separate workspaces:
+
+```bash
+milaidy agents add <name>
+```
+
+Non-interactive:
+
+```bash
+milaidy agents add work \
+  --workspace ~/.milaidy/workspace-work \
+  --model openai/gpt-5.2 \
+  --bind whatsapp:biz \
+  --non-interactive \
+  --json
+```
+
+Config entries:
+- `agents.list[].name`
+- `agents.list[].workspace`
+- `agents.list[].agentDir`
+
+## Gateway RPC
+
+The wizard is exposed over RPC:
+- `wizard.start`
+- `wizard.next`
+- `wizard.cancel`
+- `wizard.status`
+
+Clients (macOS app, Control UI) can render steps without re-implementing logic.
+
+## Signal Setup
+
+The wizard can install `signal-cli`:
+- Downloads from GitHub releases
+- Stores in `~/.milaidy/tools/signal-cli/<version>/`
+- Writes `channels.signal.cliPath`
+
+Requirements:
+- JVM builds need **Java 21**
+- Native builds preferred when available
+
+## Config Output
+
+Typical fields in `~/.milaidy/milaidy.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.milaidy/workspace",
+      "model": { "primary": "anthropic/claude-opus-4-5" }
+    }
+  },
+  "gateway": {
+    "mode": "local",
+    "bind": "loopback",
+    "port": 18789,
+    "auth": { "mode": "token" }
+  },
+  "channels": {
+    "telegram": { "botToken": "..." },
+    "discord": { "token": "..." }
+  },
+  "skills": {
+    "install": { "nodeManager": "npm" }
+  },
+  "wizard": {
+    "lastRunAt": "2026-01-15T10:30:00Z",
+    "lastRunVersion": "2026.1.15",
+    "lastRunMode": "local"
+  }
+}
+```
+
+Channel credentials:
+- WhatsApp: `~/.milaidy/credentials/whatsapp/<accountId>/`
+- Sessions: `~/.milaidy/agents/<agentId>/sessions/`
+
+## Related Docs
+
+- [Onboarding](/start/onboarding) - Overview of onboarding flow
+- [Secrets](/concepts/secrets) - Secret key names and validation
+- [Plugins](/concepts/plugins) - ElizaOS plugin system
+- [Gateway Configuration](/gateway/configuration) - Config reference
+- [Skills](/tools/skills) - Skills configuration