fengming 0.3.9 → 0.3.11

package/docs/cli/node.md

@@ -1,177 +0,0 @@
----
-summary: "CLI reference for `fengming node` (headless node host)"
-read_when:
-  - Running the headless node host
-  - Pairing a non-macOS node for system.run
-title: "Node"
----
-
-# `fengming node`
-
-Run a **headless node host** that connects to the Gateway WebSocket and exposes
-`system.run` / `system.which` on this machine.
-
-## Why use a node host?
-
-Use a node host when you want agents to **run commands on other machines** in your
-network without installing a full macOS companion app there.
-
-Common use cases:
-
-- Run commands on remote Linux/Windows boxes (build servers, lab machines, NAS).
-- Keep exec **sandboxed** on the gateway, but delegate approved runs to other hosts.
-- Provide a lightweight, headless execution target for automation or CI nodes.
-
-Execution is still guarded by **exec approvals** and per-agent allowlists on the
-node host, so you can keep command access scoped and explicit.
-
-## Browser proxy (zero-config)
-
-Node hosts automatically advertise a browser proxy if `browser.enabled` is not
-disabled on the node. This lets the agent use browser automation on that node
-without extra configuration.
-
-By default, the proxy exposes the node's normal browser profile surface. If you
-set `nodeHost.browserProxy.allowProfiles`, the proxy becomes restrictive:
-non-allowlisted profile targeting is rejected, and persistent profile
-create/delete routes are blocked through the proxy.
-
-Disable it on the node if needed:
-
-```json5
-{
-  nodeHost: {
-    browserProxy: {
-      enabled: false,
-    },
-  },
-}
-```
-
-## Run (foreground)
-
-```bash
-fengming node run --host <gateway-host> --port 18789
-```
-
-Options:
-
-- `--host <host>`: Gateway WebSocket host (default: `127.0.0.1`)
-- `--port <port>`: Gateway WebSocket port (default: `18789`)
-- `--tls`: Use TLS for the gateway connection
-- `--tls-fingerprint <sha256>`: Expected TLS certificate fingerprint (sha256)
-- `--node-id <id>`: Override node id (clears pairing token)
-- `--display-name <name>`: Override the node display name
-
-## Gateway auth for node host
-
-`fengming node run` and `fengming node install` resolve gateway auth from config/env (no `--token`/`--password` flags on node commands):
-
-- `FENGMING_GATEWAY_TOKEN` / `FENGMING_GATEWAY_PASSWORD` are checked first.
-- Then local config fallback: `gateway.auth.token` / `gateway.auth.password`.
-- In local mode, node host intentionally does not inherit `gateway.remote.token` / `gateway.remote.password`.
-- If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, node auth resolution fails closed (no remote fallback masking).
-- In `gateway.mode=remote`, remote client fields (`gateway.remote.token` / `gateway.remote.password`) are also eligible per remote precedence rules.
-- Node host auth resolution only honors `FENGMING_GATEWAY_*` env vars.
-
-For a node connecting to a plaintext `ws://` Gateway, loopback, private IP
-literals, `.local`, and Tailnet `*.ts.net` hosts are accepted. For other
-trusted private-DNS names, set `FENGMING_ALLOW_INSECURE_PRIVATE_WS=1`; without
-it, node startup fails closed and asks you to use `wss://`, an SSH tunnel, or
-Tailscale. This is a process-environment opt-in, not an `fengming.json` config
-key.
-`fengming node install` persists it into the supervised node service when it is
-present in the install command environment.
-
-## Service (background)
-
-Install a headless node host as a user service.
-
-```bash
-fengming node install --host <gateway-host> --port 18789
-```
-
-Options:
-
-- `--host <host>`: Gateway WebSocket host (default: `127.0.0.1`)
-- `--port <port>`: Gateway WebSocket port (default: `18789`)
-- `--tls`: Use TLS for the gateway connection
-- `--tls-fingerprint <sha256>`: Expected TLS certificate fingerprint (sha256)
-- `--node-id <id>`: Override node id (clears pairing token)
-- `--display-name <name>`: Override the node display name
-- `--runtime <runtime>`: Service runtime (`node` or `bun`)
-- `--force`: Reinstall/overwrite if already installed
-
-Manage the service:
-
-```bash
-fengming node status
-fengming node start
-fengming node stop
-fengming node restart
-fengming node uninstall
-```
-
-Use `fengming node run` for a foreground node host (no service).
-
-Service commands accept `--json` for machine-readable output.
-
-The node host retries Gateway restart and network closes in-process. If the
-Gateway reports a terminal token/password/bootstrap auth pause, the node host
-logs the close detail and exits non-zero so launchd/systemd can restart it with
-fresh config and credentials. Pairing-required pauses stay in the foreground
-flow so the pending request can be approved.
-
-## Pairing
-
-The first connection creates a pending device pairing request (`role: node`) on the Gateway.
-Approve it via:
-
-```bash
-fengming devices list
-fengming devices approve <requestId>
-```
-
-On tightly controlled node networks, the Gateway operator can explicitly opt in
-to auto-approving first-time node pairing from trusted CIDRs:
-
-```json5
-{
-  gateway: {
-    nodes: {
-      pairing: {
-        autoApproveCidrs: ["192.168.1.0/24"],
-      },
-    },
-  },
-}
-```
-
-This is disabled by default. It only applies to fresh `role: node` pairing with
-no requested scopes. Operator/browser clients, Control UI, WebChat, and role,
-scope, metadata, or public-key upgrades still require manual approval.
-
-If the node retries pairing with changed auth details (role/scopes/public key),
-the previous pending request is superseded and a new `requestId` is created.
-Run `fengming devices list` again before approval.
-
-The node host stores its node id, token, display name, and gateway connection info in
-`~/.fengming/node.json`.
-
-## Exec approvals
-
-`system.run` is gated by local exec approvals:
-
-- `~/.fengming/exec-approvals.json`
-- [Exec approvals](/tools/exec-approvals)
-- `fengming approvals --node <id|name|ip>` (edit from the Gateway)
-
-For approved async node exec, FengMing prepares a canonical `systemRunPlan`
-before prompting. The later approved `system.run` forward reuses that stored
-plan, so edits to command/cwd/session fields after the approval request was
-created are rejected instead of changing what the node executes.
-
-## Related
-
-- [CLI reference](/cli)
-- [Nodes](/nodes)

package/docs/cli/nodes.md

@@ -1,76 +0,0 @@
----
-summary: "CLI reference for `fengming nodes` (status, pairing, invoke, camera/canvas/screen)"
-read_when:
-  - You're managing paired nodes (cameras, screen, canvas)
-  - You need to approve requests or invoke node commands
-title: "Nodes"
----
-
-# `fengming nodes`
-
-Manage paired nodes (devices) and invoke node capabilities.
-
-Related:
-
-- Nodes overview: [Nodes](/nodes)
-- Camera: [Camera nodes](/nodes/camera)
-- Images: [Image nodes](/nodes/images)
-
-Common options:
-
-- `--url`, `--token`, `--timeout`, `--json`
-
-## Common commands
-
-```bash
-fengming nodes list
-fengming nodes list --connected
-fengming nodes list --last-connected 24h
-fengming nodes pending
-fengming nodes approve <requestId>
-fengming nodes reject <requestId>
-fengming nodes remove --node <id|name|ip>
-fengming nodes rename --node <id|name|ip> --name <displayName>
-fengming nodes status
-fengming nodes status --connected
-fengming nodes status --last-connected 24h
-```
-
-`nodes list` prints pending/paired tables. Paired rows include the most recent connect age (Last Connect).
-Use `--connected` to only show currently-connected nodes. Use `--last-connected <duration>` to
-filter to nodes that connected within a duration (e.g. `24h`, `7d`).
-Use `nodes remove --node <id|name|ip>` to delete a stale gateway-owned node pairing record.
-
-Approval note:
-
-- `fengming nodes pending` only needs pairing scope.
-- `gateway.nodes.pairing.autoApproveCidrs` can skip the pending step only for
-  explicitly trusted, first-time `role: node` device pairing. It is off by
-  default and does not approve upgrades.
-- `fengming nodes approve <requestId>` inherits extra scope requirements from the
-  pending request:
-  - commandless request: pairing only
-  - non-exec node commands: pairing + write
-  - `system.run` / `system.run.prepare` / `system.which`: pairing + admin
-
-## Invoke
-
-```bash
-fengming nodes invoke --node <id|name|ip> --command <command> --params <json>
-```
-
-Invoke flags:
-
-- `--params <json>`: JSON object string (default `{}`).
-- `--invoke-timeout <ms>`: node invoke timeout (default `15000`).
-- `--idempotency-key <key>`: optional idempotency key.
-- `system.run` and `system.run.prepare` are blocked here; use the `exec` tool with `host=node` for shell execution.
-
-For shell execution on a node, use the `exec` tool with `host=node` instead of `fengming nodes run`.
-The `nodes` CLI is now capability-focused: direct RPC via `nodes invoke`, plus pairing, camera,
-screen, location, Canvas, and notifications. Canvas commands are implemented by the bundled experimental Canvas plugin; core keeps a compatibility hook so they remain under `fengming nodes canvas`.
-
-## Related
-
-- [CLI reference](/cli)
-- [Nodes](/nodes)

package/docs/cli/onboard.md

@@ -1,250 +0,0 @@
----
-summary: "CLI reference for `fengming onboard` (interactive onboarding)"
-read_when:
-  - You want guided setup for gateway, workspace, auth, channels, and skills
-title: "Onboard"
----
-
-# `fengming onboard`
-
-Full guided onboarding for local or remote Gateway setup. Use this when you want FengMing to walk through model auth, workspace, gateway, channels, skills, and health in one flow.
-
-## Related guides
-
-<CardGroup cols={2}>
-  <Card title="CLI onboarding hub" href="/start/wizard" icon="rocket">
-    Walkthrough of the interactive CLI flow.
-  </Card>
-  <Card title="Onboarding overview" href="/start/onboarding-overview" icon="map">
-    How FengMing onboarding fits together.
-  </Card>
-  <Card title="CLI setup reference" href="/start/wizard-cli-reference" icon="book">
-    Outputs, internals, and per-step behavior.
-  </Card>
-  <Card title="CLI automation" href="/start/wizard-cli-automation" icon="terminal">
-    Non-interactive flags and scripted setups.
-  </Card>
-  <Card title="macOS app onboarding" href="/start/onboarding" icon="apple">
-    Onboarding flow for the macOS menu bar app.
-  </Card>
-</CardGroup>
-
-## Examples
-
-```bash
-fengming onboard
-fengming onboard --modern
-fengming onboard --flow quickstart
-fengming onboard --flow manual
-fengming onboard --flow import
-fengming onboard --import-from hermes --import-source ~/.hermes
-fengming onboard --skip-bootstrap
-fengming onboard --mode remote --remote-url wss://gateway-host:18789
-```
-
-`--flow import` uses plugin-owned migration providers such as Hermes. It only runs against a fresh FengMing setup; if existing config, credentials, sessions, or workspace memory/identity files are present, reset or choose a fresh setup before importing.
-
-`--modern` starts the Crestodian conversational onboarding preview. Without
-`--modern`, `fengming onboard` keeps the classic onboarding flow.
-
-On a fresh install where the active config file is missing or has no authored
-settings (empty or metadata-only), bare `fengming` also starts the classic
-onboarding flow. Once a config file has authored settings, bare `fengming`
-opens Crestodian instead.
-
-Plaintext `ws://` is accepted for loopback, private IP literals, `.local`, and
-Tailnet `*.ts.net` gateway URLs. For other trusted private-DNS names, set
-`FENGMING_ALLOW_INSECURE_PRIVATE_WS=1` in the onboarding process environment.
-
-## Locale
-
-Interactive onboarding uses the CLI wizard locale for fixed setup copy. Resolve
-order is:
-
-1. `FENGMING_LOCALE`
-2. `LC_ALL`
-3. `LC_MESSAGES`
-4. `LANG`
-5. English fallback
-
-Supported wizard locales are `en`, `zh-CN`, and `zh-TW`. Locale values may use
-underscore or POSIX suffix forms such as `zh_CN.UTF-8`. Product names, command
-names, config keys, URLs, provider IDs, model IDs, and plugin/channel labels
-remain literal.
-
-Example:
-
-```bash
-FENGMING_LOCALE=zh-CN fengming onboard
-```
-
-Non-interactive custom provider:
-
-```bash
-fengming onboard --non-interactive \
-  --auth-choice custom-api-key \
-  --custom-base-url "https://llm.example.com/v1" \
-  --custom-model-id "foo-large" \
-  --custom-api-key "$CUSTOM_API_KEY" \
-  --secret-input-mode plaintext \
-  --custom-compatibility openai \
-  --custom-image-input
-```
-
-`--custom-api-key` is optional in non-interactive mode. If omitted, onboarding checks `CUSTOM_API_KEY`.
-FengMing marks common vision model IDs as image-capable automatically. Pass `--custom-image-input` for unknown custom vision IDs, or `--custom-text-input` to force text-only metadata.
-
-LM Studio also supports a provider-specific key flag in non-interactive mode:
-
-```bash
-fengming onboard --non-interactive \
-  --auth-choice lmstudio \
-  --custom-base-url "http://localhost:1234/v1" \
-  --custom-model-id "qwen/qwen3.5-9b" \
-  --lmstudio-api-key "$LM_API_TOKEN" \
-  --accept-risk
-```
-
-Non-interactive Ollama:
-
-```bash
-fengming onboard --non-interactive \
-  --auth-choice ollama \
-  --custom-base-url "http://ollama-host:11434" \
-  --custom-model-id "qwen3.5:27b" \
-  --accept-risk
-```
-
-`--custom-base-url` defaults to `http://127.0.0.1:11434`. `--custom-model-id` is optional; if omitted, onboarding uses Ollama's suggested defaults. Cloud model IDs such as `kimi-k2.5:cloud` also work here.
-
-Store provider keys as refs instead of plaintext:
-
-```bash
-fengming onboard --non-interactive \
-  --auth-choice openai-api-key \
-  --secret-input-mode ref \
-  --accept-risk
-```
-
-With `--secret-input-mode ref`, onboarding writes env-backed refs instead of plaintext key values.
-For auth-profile backed providers this writes `keyRef` entries; for custom providers this writes `models.providers.<id>.apiKey` as an env ref (for example `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`).
-
-Non-interactive `ref` mode contract:
-
-- Set the provider env var in the onboarding process environment (for example `OPENAI_API_KEY`).
-- Do not pass inline key flags (for example `--openai-api-key`) unless that env var is also set.
-- If an inline key flag is passed without the required env var, onboarding fails fast with guidance.
-
-Gateway token options in non-interactive mode:
-
-- `--gateway-auth token --gateway-token <token>` stores a plaintext token.
-- `--gateway-auth token --gateway-token-ref-env <name>` stores `gateway.auth.token` as an env SecretRef.
-- `--gateway-token` and `--gateway-token-ref-env` are mutually exclusive.
-- `--gateway-token-ref-env` requires a non-empty env var in the onboarding process environment.
-- With `--install-daemon`, when token auth requires a token, SecretRef-managed gateway tokens are validated but not persisted as resolved plaintext in supervisor service environment metadata.
-- With `--install-daemon`, if token mode requires a token and the configured token SecretRef is unresolved, onboarding fails closed with remediation guidance.
-- With `--install-daemon`, if both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, onboarding blocks install until mode is set explicitly.
-- Local onboarding writes `gateway.mode="local"` into the config. If a later config file is missing `gateway.mode`, treat that as config damage or an incomplete manual edit, not as a valid local-mode shortcut.
-- Local onboarding installs selected downloadable plugins when the chosen setup path requires them.
-- Remote onboarding only writes connection info for the remote Gateway and does not install local plugin packages.
-- `--allow-unconfigured` is a separate gateway runtime escape hatch. It does not mean onboarding may omit `gateway.mode`.
-
-Example:
-
-```bash
-export FENGMING_GATEWAY_TOKEN="your-token"
-fengming onboard --non-interactive \
-  --mode local \
-  --auth-choice skip \
-  --gateway-auth token \
-  --gateway-token-ref-env FENGMING_GATEWAY_TOKEN \
-  --accept-risk
-```
-
-Non-interactive local gateway health:
-
-- Unless you pass `--skip-health`, onboarding waits for a reachable local gateway before it exits successfully.
-- `--install-daemon` starts the managed gateway install path first. Without it, you must already have a local gateway running, for example `fengming gateway run`.
-- If you only want config/workspace/bootstrap writes in automation, use `--skip-health`.
-- If you manage workspace files yourself, pass `--skip-bootstrap` to set `agents.defaults.skipBootstrap: true` and skip creating `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, and `BOOTSTRAP.md`.
-- On native Windows, `--install-daemon` tries Scheduled Tasks first and falls back to a per-user Startup-folder login item if task creation is denied.
-
-Interactive onboarding behavior with reference mode:
-
-- Choose **Use secret reference** when prompted.
-- Then choose either:
-  - Environment variable
-  - Configured secret provider (`file` or `exec`)
-- Onboarding performs a fast preflight validation before saving the ref.
-  - If validation fails, onboarding shows the error and lets you retry.
-
-### Non-interactive Z.AI endpoint choices
-
-<Note>
-`--auth-choice zai-api-key` auto-detects the best Z.AI endpoint for your key (prefers the general API with `zai/glm-5.1`). If you specifically want the GLM Coding Plan endpoints, pick `zai-coding-global` or `zai-coding-cn`.
-</Note>
-
-```bash
-# Promptless endpoint selection
-fengming onboard --non-interactive \
-  --auth-choice zai-coding-global \
-  --zai-api-key "$ZAI_API_KEY"
-
-# Other Z.AI endpoint choices:
-# --auth-choice zai-coding-cn
-# --auth-choice zai-global
-# --auth-choice zai-cn
-```
-
-Non-interactive Mistral example:
-
-```bash
-fengming onboard --non-interactive \
-  --auth-choice mistral-api-key \
-  --mistral-api-key "$MISTRAL_API_KEY"
-```
-
-## Flow notes
-
-<AccordionGroup>
-  <Accordion title="Flow types">
-    - `quickstart`: minimal prompts, auto-generates a gateway token.
-    - `manual`: full prompts for port, bind, and auth (alias of `advanced`).
-    - `import`: runs a detected migration provider, previews the plan, then applies after confirmation.
-
-  </Accordion>
-  <Accordion title="Provider prefiltering">
-    When an auth choice implies a preferred provider, onboarding prefilters the default-model and allowlist pickers to that provider. For Volcengine and BytePlus, this also matches the coding-plan variants (`volcengine-plan/*`, `byteplus-plan/*`).
-
-    If the preferred-provider filter yields no loaded models yet, onboarding falls back to the unfiltered catalog instead of leaving the picker empty.
-
-  </Accordion>
-  <Accordion title="Web-search follow-ups">
-    Some web-search providers trigger provider-specific follow-up prompts:
-
-    - **Grok** can offer optional `x_search` setup with the same xAI OAuth profile or API key and an `x_search` model choice.
-    - **Kimi** can ask for the Moonshot API region (`api.moonshot.ai` vs `api.moonshot.cn`) and the default Kimi web-search model.
-
-  </Accordion>
-  <Accordion title="Other behaviors">
-    - Local onboarding DM scope behavior: [CLI setup reference](/start/wizard-cli-reference#outputs-and-internals).
-    - Fastest first chat: `fengming dashboard` (Control UI, no channel setup).
-    - Custom provider: connect any OpenAI or Anthropic compatible endpoint, including hosted providers not listed. Use Unknown to auto-detect.
-    - If Hermes state is detected, onboarding offers a migration flow. Use [Migrate](/cli/migrate) for dry-run plans, overwrite mode, reports, and exact mappings.
-
-  </Accordion>
-</AccordionGroup>
-
-## Common follow-up commands
-
-```bash
-fengming channels add
-fengming configure
-fengming agents add <name>
-```
-
-Use `fengming setup` instead when you only need the baseline config/workspace. Use `fengming configure` later for targeted changes and `fengming channels add` for channel-only setup.
-
-<Note>
-`--json` does not imply non-interactive mode. Use `--non-interactive` for scripts.
-</Note>

package/docs/cli/pairing.md

@@ -1,77 +0,0 @@
----
-summary: "CLI reference for `fengming pairing` (approve/list pairing requests)"
-read_when:
-  - You're using pairing-mode DMs and need to approve senders
-title: "Pairing"
----
-
-# `fengming pairing`
-
-Approve or inspect DM pairing requests (for channels that support pairing).
-
-Related:
-
-- Pairing flow: [Pairing](/channels/pairing)
-
-## Commands
-
-```bash
-fengming pairing list telegram
-fengming pairing list --channel telegram --account work
-fengming pairing list telegram --json
-
-fengming pairing approve <code>
-fengming pairing approve telegram <code>
-fengming pairing approve --channel telegram --account work <code> --notify
-```
-
-## `pairing list`
-
-List pending pairing requests for one channel.
-
-Options:
-
-- `[channel]`: positional channel id
-- `--channel <channel>`: explicit channel id
-- `--account <accountId>`: account id for multi-account channels
-- `--json`: machine-readable output
-
-Notes:
-
-- If multiple pairing-capable channels are configured, you must provide a channel either positionally or with `--channel`.
-- Extension channels are allowed as long as the channel id is valid.
-
-## `pairing approve`
-
-Approve a pending pairing code and allow that sender.
-
-Usage:
-
-- `fengming pairing approve <channel> <code>`
-- `fengming pairing approve --channel <channel> <code>`
-- `fengming pairing approve <code>` when exactly one pairing-capable channel is configured
-
-Options:
-
-- `--channel <channel>`: explicit channel id
-- `--account <accountId>`: account id for multi-account channels
-- `--notify`: send a confirmation back to the requester on the same channel
-
-Owner bootstrap:
-
-- If `commands.ownerAllowFrom` is empty when you approve a pairing code, FengMing also records the approved sender as the command owner, using a channel-scoped entry such as `telegram:123456789`.
-- This only bootstraps the first owner. Later pairing approvals do not replace or expand `commands.ownerAllowFrom`.
-- The command owner is the human operator account allowed to run owner-only commands and approve dangerous actions such as `/diagnostics`, `/export-trajectory`, `/config`, and exec approvals.
-
-## Notes
-
-- Channel input: pass it positionally (`pairing list telegram`) or with `--channel <channel>`.
-- `pairing list` supports `--account <accountId>` for multi-account channels.
-- `pairing approve` supports `--account <accountId>` and `--notify`.
-- If only one pairing-capable channel is configured, `pairing approve <code>` is allowed.
-- If you approved a sender before this bootstrap existed, run `fengming doctor`; it warns when no command owner is configured and shows the `fengming config set commands.ownerAllowFrom ...` command to fix it.
-
-## Related
-
-- [CLI reference](/cli)
-- [Channel pairing](/channels/pairing)