fengming 0.3.10 → 0.3.11

package/docs/start/wizard-cli-automation.md

@@ -1,232 +0,0 @@
----
-summary: "Scripted onboarding and agent setup for the FengMing CLI"
-read_when:
-  - You are automating onboarding in scripts or CI
-  - You need non-interactive examples for specific providers
-title: "CLI automation"
-sidebarTitle: "CLI automation"
----
-
-Use `--non-interactive` to automate `fengming onboard`.
-
-<Note>
-`--json` does not imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
-</Note>
-
-## Baseline non-interactive example
-
-```bash
-fengming onboard --non-interactive \
-  --mode local \
-  --auth-choice apiKey \
-  --anthropic-api-key "$ANTHROPIC_API_KEY" \
-  --secret-input-mode plaintext \
-  --gateway-port 18789 \
-  --gateway-bind loopback \
-  --install-daemon \
-  --daemon-runtime node \
-  --skip-bootstrap \
-  --skip-skills
-```
-
-Add `--json` for a machine-readable summary.
-
-Use `--skip-bootstrap` when your automation pre-seeds workspace files and does not want onboarding to create the default bootstrap files.
-
-Use `--secret-input-mode ref` to store env-backed refs in auth profiles instead of plaintext values.
-Interactive selection between env refs and configured provider refs (`file` or `exec`) is available in the onboarding flow.
-
-In non-interactive `ref` mode, provider env vars must be set in the process environment.
-Passing inline key flags without the matching env var now fails fast.
-
-Example:
-
-```bash
-fengming onboard --non-interactive \
-  --mode local \
-  --auth-choice openai-api-key \
-  --secret-input-mode ref \
-  --accept-risk
-```
-
-## Provider-specific examples
-
-<AccordionGroup>
-  <Accordion title="Anthropic API key example">
-    ```bash
-    fengming onboard --non-interactive \
-      --mode local \
-      --auth-choice apiKey \
-      --anthropic-api-key "$ANTHROPIC_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="Gemini example">
-    ```bash
-    fengming onboard --non-interactive \
-      --mode local \
-      --auth-choice gemini-api-key \
-      --gemini-api-key "$GEMINI_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="Z.AI example">
-    ```bash
-    fengming onboard --non-interactive \
-      --mode local \
-      --auth-choice zai-api-key \
-      --zai-api-key "$ZAI_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="Vercel AI Gateway example">
-    ```bash
-    fengming 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
-    ```
-  </Accordion>
-  <Accordion title="Cloudflare AI Gateway example">
-    ```bash
-    fengming 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
-    ```
-  </Accordion>
-  <Accordion title="Moonshot example">
-    ```bash
-    fengming onboard --non-interactive \
-      --mode local \
-      --auth-choice moonshot-api-key \
-      --moonshot-api-key "$MOONSHOT_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="Mistral example">
-    ```bash
-    fengming onboard --non-interactive \
-      --mode local \
-      --auth-choice mistral-api-key \
-      --mistral-api-key "$MISTRAL_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="Synthetic example">
-    ```bash
-    fengming onboard --non-interactive \
-      --mode local \
-      --auth-choice synthetic-api-key \
-      --synthetic-api-key "$SYNTHETIC_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="OpenCode example">
-    ```bash
-    fengming onboard --non-interactive \
-      --mode local \
-      --auth-choice opencode-zen \
-      --opencode-zen-api-key "$OPENCODE_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-    Swap to `--auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY"` for the Go catalog.
-  </Accordion>
-  <Accordion title="Ollama example">
-    ```bash
-    fengming onboard --non-interactive \
-      --mode local \
-      --auth-choice ollama \
-      --custom-model-id "qwen3.5:27b" \
-      --accept-risk \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="Custom provider example">
-    ```bash
-    fengming onboard --non-interactive \
-      --mode local \
-      --auth-choice custom-api-key \
-      --custom-base-url "https://llm.example.com/v1" \
-      --custom-model-id "foo-large" \
-      --custom-api-key "$CUSTOM_API_KEY" \
-      --custom-provider-id "my-custom" \
-      --custom-compatibility anthropic \
-      --custom-image-input \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-
-    `--custom-api-key` is optional. If omitted, onboarding checks `CUSTOM_API_KEY`.
-    FengMing marks common vision model IDs as image-capable automatically. Add `--custom-image-input` for unknown custom vision IDs, or `--custom-text-input` to force text-only metadata.
-
-    Ref-mode variant:
-
-    ```bash
-    export CUSTOM_API_KEY="your-key"
-    fengming onboard --non-interactive \
-      --mode local \
-      --auth-choice custom-api-key \
-      --custom-base-url "https://llm.example.com/v1" \
-      --custom-model-id "foo-large" \
-      --secret-input-mode ref \
-      --custom-provider-id "my-custom" \
-      --custom-compatibility anthropic \
-      --custom-image-input \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-
-    In this mode, onboarding stores `apiKey` as `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`.
-
-  </Accordion>
-</AccordionGroup>
-
-Anthropic setup-token remains available as a supported onboarding token path, but FengMing now prefers Claude CLI reuse when available.
-For production, prefer an Anthropic API key.
-
-## Add another agent
-
-Use `fengming agents add <name>` to create a separate agent with its own workspace,
-sessions, and auth profiles. Running without `--workspace` launches the wizard.
-
-```bash
-fengming agents add work \
-  --workspace ~/.fengming/workspace-work \
-  --model openai/gpt-5.5 \
-  --bind whatsapp:biz \
-  --non-interactive \
-  --json
-```
-
-What it sets:
-
-- `agents.list[].name`
-- `agents.list[].workspace`
-- `agents.list[].agentDir`
-
-Notes:
-
-- Default workspaces follow `~/.fengming/workspace-<agentId>`.
-- Add `bindings` to route inbound messages (the wizard can do this).
-- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
-
-## Related docs
-
-- Onboarding hub: [Onboarding (CLI)](/start/wizard)
-- Full reference: [CLI Setup Reference](/start/wizard-cli-reference)
-- Command reference: [`fengming onboard`](/cli/onboard)

package/docs/start/wizard-cli-reference.md

@@ -1,331 +0,0 @@
----
-summary: "Complete reference for CLI setup flow, auth/model setup, outputs, and internals"
-read_when:
-  - You need detailed behavior for fengming onboard
-  - You are debugging onboarding results or integrating onboarding clients
-title: "CLI setup reference"
-sidebarTitle: "CLI reference"
----
-
-This page is the full reference for `fengming onboard`.
-For the short guide, see [Onboarding (CLI)](/start/wizard).
-
-## What the wizard does
-
-Local mode (default) walks you through:
-
-- Model and auth setup (OpenAI Code subscription OAuth, Anthropic Claude CLI or API key, plus MiniMax, GLM, Ollama, Moonshot, StepFun, and AI Gateway options)
-- Workspace location and bootstrap files
-- Gateway settings (port, bind, auth, tailscale)
-- Channels and providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, iMessage, and other bundled channel plugins)
-- Daemon install (LaunchAgent, systemd user unit, or native Windows Scheduled Task with Startup-folder fallback)
-- Health check
-- Skills setup
-
-Remote mode configures this machine to connect to a gateway elsewhere.
-It does not install or modify anything on the remote host.
-
-## Local flow details
-
-<Steps>
-  <Step title="Existing config detection">
-    - If `~/.fengming/fengming.json` exists, choose Keep, Modify, or Reset.
-    - Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass `--reset`).
-    - CLI `--reset` defaults to `config+creds+sessions`; use `--reset-scope full` to also remove workspace.
-    - If config is invalid or contains legacy keys, the wizard stops and asks you to run `fengming doctor` before continuing.
-    - Reset uses `trash` and offers scopes:
-      - Config only
-      - Config + credentials + sessions
-      - Full reset (also removes workspace)
-
-  </Step>
-  <Step title="Model and auth">
-    - Full option matrix is in [Auth and model options](#auth-and-model-options).
-
-  </Step>
-  <Step title="Workspace">
-    - Default `~/.fengming/workspace` (configurable).
-    - Seeds workspace files needed for first-run bootstrap ritual.
-    - Workspace layout: [Agent workspace](/concepts/agent-workspace).
-
-  </Step>
-  <Step title="Gateway">
-    - Prompts for port, bind, auth mode, and tailscale exposure.
-    - Recommended: keep token auth enabled even for loopback so local WS clients must authenticate.
-    - In token mode, interactive setup offers:
-      - **Generate/store plaintext token** (default)
-      - **Use SecretRef** (opt-in)
-    - In password mode, interactive setup also supports plaintext or SecretRef storage.
-    - Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
-      - Requires a non-empty env var in the onboarding process environment.
-      - Cannot be combined with `--gateway-token`.
-    - Disable auth only if you fully trust every local process.
-    - Non-loopback binds still require auth.
-
-  </Step>
-  <Step title="Channels">
-    - [WhatsApp](/channels/whatsapp): optional QR login
-    - [Telegram](/channels/telegram): bot token
-    - [Discord](/channels/discord): bot token
-    - [Google Chat](/channels/googlechat): service account JSON + webhook audience
-    - [Mattermost](/channels/mattermost): bot token + base URL
-    - [Signal](/channels/signal): optional `signal-cli` install + account config
-    - [iMessage](/channels/imessage): `imsg` CLI path + Messages DB access; use an SSH wrapper when the Gateway runs off-Mac
-    - DM security: default is pairing. First DM sends a code; approve via
-      `fengming pairing approve <channel> <code>` or use allowlists.
-  </Step>
-  <Step title="Daemon install">
-    - macOS: LaunchAgent
-      - Requires logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
-    - Linux and Windows via WSL2: systemd user unit
-      - Wizard attempts `loginctl enable-linger <user>` so gateway stays up after logout.
-      - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
-    - Native Windows: Scheduled Task first
-      - If task creation is denied, FengMing falls back to a per-user Startup-folder login item and starts the gateway immediately.
-      - Scheduled Tasks remain preferred because they provide better supervisor status.
-    - Runtime selection: Node (recommended; required for WhatsApp and Telegram). Bun is not recommended.
-
-  </Step>
-  <Step title="Health check">
-    - Starts gateway (if needed) and runs `fengming health`.
-    - `fengming status --deep` adds the live gateway health probe to status output, including channel probes when supported.
-
-  </Step>
-  <Step title="Skills">
-    - Reads available skills and checks requirements.
-    - Lets you choose node manager: npm, pnpm, or bun.
-    - Installs optional dependencies (some use Homebrew on macOS).
-
-  </Step>
-  <Step title="Finish">
-    - Summary and next steps, including iOS, Android, and macOS app options.
-
-  </Step>
-</Steps>
-
-<Note>
-If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
-If Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
-</Note>
-
-## Remote mode details
-
-Remote mode configures this machine to connect to a gateway elsewhere.
-
-<Info>
-Remote mode does not install or modify anything on the remote host.
-</Info>
-
-What you set:
-
-- Remote gateway URL (`ws://...`)
-- Token if remote gateway auth is required (recommended)
-
-<Note>
-- If gateway is loopback-only, use SSH tunneling or a tailnet.
-- Discovery hints:
-  - macOS: Bonjour (`dns-sd`)
-  - Linux: Avahi (`avahi-browse`)
-
-</Note>
-
-## Auth and model options
-
-<AccordionGroup>
-  <Accordion title="Anthropic API key">
-    Uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
-  </Accordion>
-  <Accordion title="OpenAI Code subscription (OAuth)">
-    Browser flow; paste `code#state`.
-
-    Sets `agents.defaults.model` to `openai/gpt-5.5` through the Codex runtime when model is unset or already OpenAI-family.
-
-  </Accordion>
-  <Accordion title="OpenAI Code subscription (device pairing)">
-    Browser pairing flow with a short-lived device code.
-
-    Sets `agents.defaults.model` to `openai/gpt-5.5` through the Codex runtime when model is unset or already OpenAI-family.
-
-  </Accordion>
-  <Accordion title="OpenAI API key">
-    Uses `OPENAI_API_KEY` if present or prompts for a key, then stores the credential in auth profiles.
-
-    Sets `agents.defaults.model` to `openai/gpt-5.5` when model is unset, `openai/*`, or `openai-codex/*`.
-
-  </Accordion>
-  <Accordion title="xAI (Grok) OAuth">
-    Browser sign-in for eligible SuperGrok or X Premium accounts. This is the
-    recommended xAI path for most users. FengMing stores the resulting auth
-    profile for Grok models, Grok `web_search`, `x_search`, and `code_execution`.
-  </Accordion>
-  <Accordion title="xAI (Grok) device code">
-    Remote-friendly browser sign-in with a short code instead of a localhost
-    callback. Use this from SSH, Docker, or VPS hosts.
-  </Accordion>
-  <Accordion title="xAI (Grok) API key">
-    Prompts for `XAI_API_KEY` and configures xAI as a model provider. Use this
-    when you want an xAI Console API key instead of subscription OAuth.
-  </Accordion>
-  <Accordion title="OpenCode">
-    Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`) and lets you choose the Zen or Go catalog.
-    Setup URL: [opencode.ai/auth](https://opencode.ai/auth).
-  </Accordion>
-  <Accordion title="API key (generic)">
-    Stores the key for you.
-  </Accordion>
-  <Accordion title="Vercel AI Gateway">
-    Prompts for `AI_GATEWAY_API_KEY`.
-    More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway).
-  </Accordion>
-  <Accordion title="Cloudflare AI Gateway">
-    Prompts for account ID, gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
-    More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway).
-  </Accordion>
-  <Accordion title="MiniMax">
-    Config is auto-written. Hosted default is `MiniMax-M2.7`; API-key setup uses
-    `minimax/...`, and OAuth setup uses `minimax-portal/...`.
-    More detail: [MiniMax](/providers/minimax).
-  </Accordion>
-  <Accordion title="StepFun">
-    Config is auto-written for StepFun standard or Step Plan on China or global endpoints.
-    Standard currently includes `step-3.5-flash`, and Step Plan also includes `step-3.5-flash-2603`.
-    More detail: [StepFun](/providers/stepfun).
-  </Accordion>
-  <Accordion title="Synthetic (Anthropic-compatible)">
-    Prompts for `SYNTHETIC_API_KEY`.
-    More detail: [Synthetic](/providers/synthetic).
-  </Accordion>
-  <Accordion title="Ollama (Cloud and local open models)">
-    Prompts for `Cloud + Local`, `Cloud only`, or `Local only` first.
-    `Cloud only` uses `OLLAMA_API_KEY` with `https://ollama.com`.
-    The host-backed modes prompt for base URL (default `http://127.0.0.1:11434`), discover available models, and suggest defaults.
-    `Cloud + Local` also checks whether that Ollama host is signed in for cloud access.
-    More detail: [Ollama](/providers/ollama).
-  </Accordion>
-  <Accordion title="Moonshot and Kimi Coding">
-    Moonshot (Kimi K2) and Kimi Coding configs are auto-written.
-    More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot).
-  </Accordion>
-  <Accordion title="Custom provider">
-    Works with OpenAI-compatible and Anthropic-compatible endpoints.
-
-    Interactive onboarding supports the same API key storage choices as other provider API key flows:
-    - **Paste API key now** (plaintext)
-    - **Use secret reference** (env ref or configured provider ref, with preflight validation)
-
-    Non-interactive flags:
-    - `--auth-choice custom-api-key`
-    - `--custom-base-url`
-    - `--custom-model-id`
-    - `--custom-api-key` (optional; falls back to `CUSTOM_API_KEY`)
-    - `--custom-provider-id` (optional)
-    - `--custom-compatibility <openai|anthropic>` (optional; default `openai`)
-    - `--custom-image-input` / `--custom-text-input` (optional; override inferred model input capability)
-
-  </Accordion>
-  <Accordion title="Skip">
-    Leaves auth unconfigured.
-  </Accordion>
-</AccordionGroup>
-
-Model behavior:
-
-- Pick default model from detected options, or enter provider and model manually.
-- Custom-provider onboarding infers image support for common model IDs and asks only when the model name is unknown.
-- When onboarding starts from a provider auth choice, the model picker prefers
-  that provider automatically. For Volcengine and BytePlus, the same preference
-  also matches their coding-plan variants (`volcengine-plan/*`,
-  `byteplus-plan/*`).
-- If that preferred-provider filter would be empty, the picker falls back to
-  the full catalog instead of showing no models.
-- Wizard runs a model check and warns if the configured model is unknown or missing auth.
-
-Credential and profile paths:
-
-- Auth profiles (API keys + OAuth): `~/.fengming/agents/<agentId>/agent/auth-profiles.json`
-- Legacy OAuth import: `~/.fengming/credentials/oauth.json`
-
-Credential storage mode:
-
-- Default onboarding behavior persists API keys as plaintext values in auth profiles.
-- `--secret-input-mode ref` enables reference mode instead of plaintext key storage.
-  In interactive setup, you can choose either:
-  - environment variable ref (for example `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`)
-  - configured provider ref (`file` or `exec`) with provider alias + id
-- Interactive reference mode runs a fast preflight validation before saving.
-  - Env refs: validates variable name + non-empty value in the current onboarding environment.
-  - Provider refs: validates provider config and resolves the requested id.
-  - If preflight fails, onboarding shows the error and lets you retry.
-- In non-interactive mode, `--secret-input-mode ref` is env-backed only.
-  - Set the provider env var in the onboarding process environment.
-  - Inline key flags (for example `--openai-api-key`) require that env var to be set; otherwise onboarding fails fast.
-  - For custom providers, non-interactive `ref` mode stores `models.providers.<id>.apiKey` as `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`.
-  - In that custom-provider case, `--custom-api-key` requires `CUSTOM_API_KEY` to be set; otherwise onboarding fails fast.
-- Gateway auth credentials support plaintext and SecretRef choices in interactive setup:
-  - Token mode: **Generate/store plaintext token** (default) or **Use SecretRef**.
-  - Password mode: plaintext or SecretRef.
-- Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
-- Existing plaintext setups continue to work unchanged.
-
-<Note>
-Headless and server tip: complete OAuth on a machine with a browser, then copy
-that agent's `auth-profiles.json` (for example
-`~/.fengming/agents/<agentId>/agent/auth-profiles.json`, or the matching
-`$FENGMING_STATE_DIR/...` path) to the gateway host. `credentials/oauth.json`
-is only a legacy import source.
-</Note>
-
-## Outputs and internals
-
-Typical fields in `~/.fengming/fengming.json`:
-
-- `agents.defaults.workspace`
-- `agents.defaults.skipBootstrap` when `--skip-bootstrap` is passed
-- `agents.defaults.model` / `models.providers` (if Minimax chosen)
-- `tools.profile` (local onboarding defaults to `"coding"` when unset; existing explicit values are preserved)
-- `gateway.*` (mode, bind, auth, tailscale)
-- `session.dmScope` (local onboarding defaults this to `per-channel-peer` when unset; existing explicit values are preserved)
-- `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*`
-- Channel allowlists (Slack, Discord, Matrix, Microsoft Teams) when you opt in during prompts (names resolve to IDs when possible)
-- `skills.install.nodeManager`
-  - The `setup --node-manager` flag accepts `npm`, `pnpm`, or `bun`.
-  - Manual config can still set `skills.install.nodeManager: "yarn"` later.
-- `wizard.lastRunAt`
-- `wizard.lastRunVersion`
-- `wizard.lastRunCommit`
-- `wizard.lastRunCommand`
-- `wizard.lastRunMode`
-
-`fengming agents add` writes `agents.list[]` and optional `bindings`.
-
-WhatsApp credentials go under `~/.fengming/credentials/whatsapp/<accountId>/`.
-Sessions are stored under `~/.fengming/agents/<agentId>/sessions/`.
-
-<Note>
-Some channels are delivered as plugins. When selected during setup, the wizard
-prompts to install the plugin (npm or local path) before channel configuration.
-</Note>
-
-Gateway wizard RPC:
-
-- `wizard.start`
-- `wizard.next`
-- `wizard.cancel`
-- `wizard.status`
-
-Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic.
-
-Signal setup behavior:
-
-- Downloads the appropriate release asset
-- Stores it under `~/.fengming/tools/signal-cli/<version>/`
-- Writes `channels.signal.cliPath` in config
-- JVM builds require Java 21
-- Native builds are used when available
-- Windows uses WSL2 and follows Linux signal-cli flow inside WSL
-
-## Related docs
-
-- Onboarding hub: [Onboarding (CLI)](/start/wizard)
-- Automation and scripts: [CLI Automation](/start/wizard-cli-automation)
-- Command reference: [`fengming onboard`](/cli/onboard)