fengming 0.3.9 → 0.3.11

package/docs/cli/config.md

@@ -1,504 +0,0 @@
----
-summary: "CLI reference for `fengming config` (get/set/patch/unset/file/schema/validate)"
-read_when:
-  - You want to read or edit config non-interactively
-title: "Config"
-sidebarTitle: "Config"
----
-
-Config helpers for non-interactive edits in `fengming.json`: get/set/patch/unset/file/schema/validate values by path and print the active config file. Run without a subcommand to open the configure wizard (same as `fengming configure`).
-
-<Note>
-When `FENGMING_NIX_MODE=1`, FengMing treats `fengming.json` as immutable. Read-only commands such as `config get`, `config file`, `config schema`, and `config validate` still work, but config writers refuse. Agents should edit the Nix source for the install instead; for the first-party nix-fengming distribution, use [nix-fengming Quick Start](https://github.com/fengming/nix-fengming#quick-start) and set values under `programs.fengming.config` or `instances.<name>.config`.
-</Note>
-
-## Root options
-
-<ParamField path="--section <section>" type="string">
-  Repeatable guided-setup section filter when you run `fengming config` without a subcommand.
-</ParamField>
-
-Supported guided sections: `workspace`, `model`, `web`, `gateway`, `daemon`, `channels`, `plugins`, `skills`, `health`.
-
-## Examples
-
-```bash
-fengming config file
-fengming config --section model
-fengming config --section gateway --section daemon
-fengming config schema
-fengming config get browser.executablePath
-fengming config set browser.executablePath "/usr/bin/google-chrome"
-fengming config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
-fengming config set agents.defaults.heartbeat.every "2h"
-fengming config set 'agents.list[0].tools.exec.node' "node-id-or-name"
-fengming config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
-fengming config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
-fengming config set secrets.providers.vaultfile --provider-source file --provider-path /etc/fengming/secrets.json --provider-mode json
-fengming config patch --file ./fengming.patch.json5 --dry-run
-fengming config unset plugins.entries.brave.config.webSearch.apiKey
-fengming config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
-fengming config validate
-fengming config validate --json
-```
-
-### `config schema`
-
-Print the generated JSON schema for `fengming.json` to stdout as JSON.
-
-<AccordionGroup>
-  <Accordion title="What it includes">
-    - The current root config schema, plus a root `$schema` string field for editor tooling.
-    - Field `title` and `description` docs metadata used by the Control UI.
-    - Nested object, wildcard (`*`), and array-item (`[]`) nodes inherit the same `title` / `description` metadata when matching field documentation exists.
-    - `anyOf` / `oneOf` / `allOf` branches inherit the same docs metadata too when matching field documentation exists.
-    - Best-effort live plugin + channel schema metadata when runtime manifests can be loaded.
-    - A clean fallback schema even when the current config is invalid.
-
-  </Accordion>
-  <Accordion title="Related runtime RPC">
-    `config.schema.lookup` returns one normalized config path with a shallow schema node (`title`, `description`, `type`, `enum`, `const`, common bounds), matched UI hint metadata, and immediate child summaries. Use it for path-scoped drill-down in Control UI or custom clients.
-  </Accordion>
-</AccordionGroup>
-
-```bash
-fengming config schema
-```
-
-Pipe it into a file when you want to inspect or validate it with other tools:
-
-```bash
-fengming config schema > fengming.schema.json
-```
-
-### Paths
-
-Paths use dot or bracket notation. Quote bracket-notation paths in shell examples so shells such as zsh do not expand `[0]` as a glob before FengMing receives the path:
-
-```bash
-fengming config get agents.defaults.workspace
-fengming config get 'agents.list[0].id'
-```
-
-Use the agent list index to target a specific agent:
-
-```bash
-fengming config get agents.list
-fengming config set 'agents.list[1].tools.exec.node' "node-id-or-name"
-```
-
-## Values
-
-Values are parsed as JSON5 when possible; otherwise they are treated as strings. Use `--strict-json` to require JSON5 parsing. `--json` remains supported as a legacy alias.
-
-```bash
-fengming config set agents.defaults.heartbeat.every "0m"
-fengming config set gateway.port 19001 --strict-json
-fengming config set channels.whatsapp.groups '["*"]' --strict-json
-```
-
-`config get <path> --json` prints the raw value as JSON instead of terminal-formatted text.
-
-<Note>
-Object assignment replaces the target path by default. Protected map/list paths that commonly hold user-added entries, such as `agents.defaults.models`, `models.providers`, `models.providers.<id>.models`, `plugins.entries`, and `auth.profiles`, refuse replacements that would remove existing entries unless you pass `--replace`.
-</Note>
-
-Use `--merge` when adding entries to those maps:
-
-```bash
-fengming config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
-fengming config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge
-```
-
-Use `--replace` only when you intentionally want the provided value to become the complete target value.
-
-## `config set` modes
-
-`fengming config set` supports four assignment styles:
-
-<Tabs>
-  <Tab title="Value mode">
-    ```bash
-    fengming config set <path> <value>
-    ```
-  </Tab>
-  <Tab title="SecretRef builder mode">
-    ```bash
-    fengming config set channels.discord.token \
-      --ref-provider default \
-      --ref-source env \
-      --ref-id DISCORD_BOT_TOKEN
-    ```
-  </Tab>
-  <Tab title="Provider builder mode">
-    Provider builder mode targets `secrets.providers.<alias>` paths only:
-
-    ```bash
-    fengming config set secrets.providers.vault \
-      --provider-source exec \
-      --provider-command /usr/local/bin/fengming-vault \
-      --provider-arg read \
-      --provider-arg openai/api-key \
-      --provider-timeout-ms 5000
-    ```
-
-  </Tab>
-  <Tab title="Batch mode">
-    ```bash
-    fengming config set --batch-json '[
-      {
-        "path": "secrets.providers.default",
-        "provider": { "source": "env" }
-      },
-      {
-        "path": "channels.discord.token",
-        "ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }
-      }
-    ]'
-    ```
-
-    ```bash
-    fengming config set --batch-file ./config-set.batch.json --dry-run
-    ```
-
-  </Tab>
-</Tabs>
-
-<Warning>
-SecretRef assignments are rejected on unsupported runtime-mutable surfaces (for example `hooks.token`, `commands.ownerDisplaySecret`, Discord thread-binding webhook tokens, and WhatsApp creds JSON). See [SecretRef Credential Surface](/reference/secretref-credential-surface).
-</Warning>
-
-Batch parsing always uses the batch payload (`--batch-json`/`--batch-file`) as the source of truth. `--strict-json` / `--json` do not change batch parsing behavior.
-
-## `config patch`
-
-Use `config patch` when you want to paste or pipe a config-shaped patch instead of running many path-based `config set` commands. The input is a JSON5 object. Objects merge recursively, arrays and scalar values replace the target value, and `null` deletes the target path.
-
-```bash
-fengming config patch --file ./fengming.patch.json5 --dry-run
-fengming config patch --file ./fengming.patch.json5
-```
-
-You can also pipe a patch over stdin, which is useful for remote setup scripts:
-
-```bash
-ssh fengming-host 'fengming config patch --stdin --dry-run' < ./fengming.patch.json5
-ssh fengming-host 'fengming config patch --stdin' < ./fengming.patch.json5
-```
-
-Example patch:
-
-```json5
-{
-  channels: {
-    slack: {
-      enabled: true,
-      mode: "socket",
-      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
-      appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
-      groupPolicy: "open",
-      requireMention: false,
-    },
-    discord: {
-      enabled: true,
-      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
-      dmPolicy: "disabled",
-      dm: { enabled: false },
-      groupPolicy: "allowlist",
-    },
-  },
-  agents: {
-    defaults: {
-      model: { primary: "openai/gpt-5.5" },
-      models: {
-        "openai/gpt-5.5": { params: { fastMode: true } },
-      },
-    },
-  },
-}
-```
-
-Use `--replace-path <path>` when one object or array must become exactly the provided value instead of being recursively patched:
-
-```bash
-fengming config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'
-```
-
-`--dry-run` runs schema and SecretRef resolvability checks without writing. Exec-backed SecretRefs are skipped by default during dry-run; add `--allow-exec` when you intentionally want dry-run to execute provider commands.
-
-JSON path/value mode remains supported for both SecretRefs and providers:
-
-```bash
-fengming config set channels.discord.token \
-  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
-  --strict-json
-
-fengming config set secrets.providers.vaultfile \
-  '{"source":"file","path":"/etc/fengming/secrets.json","mode":"json"}' \
-  --strict-json
-```
-
-## Provider builder flags
-
-Provider builder targets must use `secrets.providers.<alias>` as the path.
-
-<AccordionGroup>
-  <Accordion title="Common flags">
-    - `--provider-source <env|file|exec>`
-    - `--provider-timeout-ms <ms>` (`file`, `exec`)
-
-  </Accordion>
-  <Accordion title="Env provider (--provider-source env)">
-    - `--provider-allowlist <ENV_VAR>` (repeatable)
-
-  </Accordion>
-  <Accordion title="File provider (--provider-source file)">
-    - `--provider-path <path>` (required)
-    - `--provider-mode <singleValue|json>`
-    - `--provider-max-bytes <bytes>`
-    - `--provider-allow-insecure-path`
-
-  </Accordion>
-  <Accordion title="Exec provider (--provider-source exec)">
-    - `--provider-command <path>` (required)
-    - `--provider-arg <arg>` (repeatable)
-    - `--provider-no-output-timeout-ms <ms>`
-    - `--provider-max-output-bytes <bytes>`
-    - `--provider-json-only`
-    - `--provider-env <KEY=VALUE>` (repeatable)
-    - `--provider-pass-env <ENV_VAR>` (repeatable)
-    - `--provider-trusted-dir <path>` (repeatable)
-    - `--provider-allow-insecure-path`
-    - `--provider-allow-symlink-command`
-
-  </Accordion>
-</AccordionGroup>
-
-Hardened exec provider example:
-
-```bash
-fengming config set secrets.providers.vault \
-  --provider-source exec \
-  --provider-command /usr/local/bin/fengming-vault \
-  --provider-arg read \
-  --provider-arg openai/api-key \
-  --provider-json-only \
-  --provider-pass-env VAULT_TOKEN \
-  --provider-trusted-dir /usr/local/bin \
-  --provider-timeout-ms 5000
-```
-
-## Dry run
-
-Use `--dry-run` to validate changes without writing `fengming.json`.
-
-```bash
-fengming config set channels.discord.token \
-  --ref-provider default \
-  --ref-source env \
-  --ref-id DISCORD_BOT_TOKEN \
-  --dry-run
-
-fengming config set channels.discord.token \
-  --ref-provider default \
-  --ref-source env \
-  --ref-id DISCORD_BOT_TOKEN \
-  --dry-run \
-  --json
-
-fengming config set channels.discord.token \
-  --ref-provider vault \
-  --ref-source exec \
-  --ref-id discord/token \
-  --dry-run \
-  --allow-exec
-```
-
-<AccordionGroup>
-  <Accordion title="Dry-run behavior">
-    - Builder mode: runs SecretRef resolvability checks for changed refs/providers.
-    - JSON mode (`--strict-json`, `--json`, or batch mode): runs schema validation plus SecretRef resolvability checks.
-    - Policy validation also runs for known unsupported SecretRef target surfaces.
-    - Policy checks evaluate the full post-change config, so parent-object writes (for example setting `hooks` as an object) cannot bypass unsupported-surface validation.
-    - Exec SecretRef checks are skipped by default during dry-run to avoid command side effects.
-    - Use `--allow-exec` with `--dry-run` to opt in to exec SecretRef checks (this may execute provider commands).
-    - `--allow-exec` is dry-run only and errors if used without `--dry-run`.
-
-  </Accordion>
-  <Accordion title="--dry-run --json fields">
-    `--dry-run --json` prints a machine-readable report:
-
-    - `ok`: whether dry-run passed
-    - `operations`: number of assignments evaluated
-    - `checks`: whether schema/resolvability checks ran
-    - `checks.resolvabilityComplete`: whether resolvability checks ran to completion (false when exec refs are skipped)
-    - `refsChecked`: number of refs actually resolved during dry-run
-    - `skippedExecRefs`: number of exec refs skipped because `--allow-exec` was not set
-    - `errors`: structured missing-path, schema, or resolvability failures when `ok=false`
-
-  </Accordion>
-</AccordionGroup>
-
-### JSON output shape
-
-```json5
-{
-  ok: boolean,
-  operations: number,
-  configPath: string,
-  inputModes: ["value" | "json" | "builder" | "unset", ...],
-  checks: {
-    schema: boolean,
-    resolvability: boolean,
-    resolvabilityComplete: boolean,
-  },
-  refsChecked: number,
-  skippedExecRefs: number,
-  errors?: [
-    {
-      kind: "missing-path" | "schema" | "resolvability",
-      message: string,
-      ref?: string, // present for resolvability errors
-    },
-  ],
-}
-```
-
-<Tabs>
-  <Tab title="Success example">
-    ```json
-    {
-      "ok": true,
-      "operations": 1,
-      "configPath": "~/.fengming/fengming.json",
-      "inputModes": ["builder"],
-      "checks": {
-        "schema": false,
-        "resolvability": true,
-        "resolvabilityComplete": true
-      },
-      "refsChecked": 1,
-      "skippedExecRefs": 0
-    }
-    ```
-  </Tab>
-  <Tab title="Failure example">
-    ```json
-    {
-      "ok": false,
-      "operations": 1,
-      "configPath": "~/.fengming/fengming.json",
-      "inputModes": ["builder"],
-      "checks": {
-        "schema": false,
-        "resolvability": true,
-        "resolvabilityComplete": true
-      },
-      "refsChecked": 1,
-      "skippedExecRefs": 0,
-      "errors": [
-        {
-          "kind": "resolvability",
-          "message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
-          "ref": "env:default:MISSING_TEST_SECRET"
-        }
-      ]
-    }
-    ```
-  </Tab>
-</Tabs>
-
-<AccordionGroup>
-  <Accordion title="If dry-run fails">
-    - `config schema validation failed`: your post-change config shape is invalid; fix path/value or provider/ref object shape.
-    - `Config policy validation failed: unsupported SecretRef usage`: move that credential back to plaintext/string input and keep SecretRefs on supported surfaces only.
-    - `SecretRef assignment(s) could not be resolved`: referenced provider/ref currently cannot resolve (missing env var, invalid file pointer, exec provider failure, or provider/source mismatch).
-    - `Dry run note: skipped <n> exec SecretRef resolvability check(s)`: dry-run skipped exec refs; rerun with `--allow-exec` if you need exec resolvability validation.
-    - For batch mode, fix failing entries and rerun `--dry-run` before writing.
-
-  </Accordion>
-</AccordionGroup>
-
-## Write safety
-
-`fengming config set` and other FengMing-owned config writers validate the full post-change config before committing it to disk. If the new payload fails schema validation or looks like a destructive clobber, the active config is left alone and the rejected payload is saved beside it as `fengming.json.rejected.*`.
-
-<Warning>
-The active config path must be a regular file. Symlinked `fengming.json` layouts are unsupported for writes; use `FENGMING_CONFIG_PATH` to point directly at the real file instead.
-</Warning>
-
-Prefer CLI writes for small edits:
-
-```bash
-fengming config set gateway.reload.mode hybrid --dry-run
-fengming config set gateway.reload.mode hybrid
-fengming config validate
-```
-
-If a write is rejected, inspect the saved payload and fix the full config shape:
-
-```bash
-CONFIG="$(fengming config file)"
-ls -lt "$CONFIG".rejected.* 2>/dev/null | head
-fengming config validate
-```
-
-Direct editor writes are still allowed, but the running Gateway treats them as untrusted until they validate. Invalid direct edits fail startup or are skipped by hot reload; Gateway does not rewrite `fengming.json`. Run `fengming doctor --fix` to repair prefixed/clobbered config or restore the last-known-good copy. See [Gateway troubleshooting](/gateway/troubleshooting#gateway-rejected-invalid-config).
-
-Whole-file recovery is reserved for doctor repair. Plugin schema changes or `minHostVersion` skew stay loud instead of rolling back unrelated user settings such as models, providers, auth profiles, channels, gateway exposure, tools, memory, browser, or cron config.
-
-## Subcommands
-
-- `config file`: Print the active config file path (resolved from `FENGMING_CONFIG_PATH` or default location). The path should name a regular file, not a symlink.
-
-Restart the gateway after edits.
-
-## Validate
-
-Validate the current config against the active schema without starting the gateway.
-
-```bash
-fengming config validate
-fengming config validate --json
-```
-
-After `fengming config validate` is passing, you can use the local TUI to have an embedded agent compare the active config against the docs while you validate each change from the same terminal:
-
-<Note>
-If validation is already failing, start with `fengming configure` or `fengming doctor --fix`. `fengming chat` does not bypass the invalid-config guard.
-</Note>
-
-```bash
-fengming chat
-```
-
-Then inside the TUI:
-
-```text
-!fengming config file
-!fengming docs gateway auth token secretref
-!fengming config validate
-!fengming doctor
-```
-
-Typical repair loop:
-
-<Steps>
-  <Step title="Compare with docs">
-    Ask the agent to compare your current config with the relevant docs page and suggest the smallest fix.
-  </Step>
-  <Step title="Apply targeted edits">
-    Apply targeted edits with `fengming config set` or `fengming configure`.
-  </Step>
-  <Step title="Re-validate">
-    Rerun `fengming config validate` after each change.
-  </Step>
-  <Step title="Doctor for runtime issues">
-    If validation passes but the runtime is still unhealthy, run `fengming doctor` or `fengming doctor --fix` for migration and repair help.
-  </Step>
-</Steps>
-
-## Related
-
-- [CLI reference](/cli)
-- [Configuration](/gateway/configuration)

package/docs/cli/configure.md

@@ -1,77 +0,0 @@
----
-summary: "CLI reference for `fengming configure` (interactive configuration prompts)"
-read_when:
-  - You want to tweak credentials, devices, or agent defaults interactively
-title: "Configure"
----
-
-# `fengming configure`
-
-Interactive prompt for targeted changes to an existing setup: credentials, devices, agent defaults, gateway, channels, plugins, skills, and health checks.
-
-Use `fengming onboard` for the full guided first-run journey, `fengming setup` for the baseline config/workspace only, and `fengming channels add` when you only need channel account setup.
-
-<Note>
-The **Model** section includes a multi-select for the `agents.defaults.models` allowlist (what shows up in `/model` and the model picker). Provider-scoped setup choices merge their selected models into the existing allowlist instead of replacing unrelated providers already in the config.
-
-Re-running provider auth from configure preserves an existing `agents.defaults.model.primary`, even when the provider's auth step returns a config patch with its own recommended default model. That means adding or reauthing xAI, OpenRouter, or another provider should make the new model available without taking over from your current primary model. Use `fengming models auth login --provider <id> --set-default` or `fengming models set <model>` when you intentionally want to change the default model.
-</Note>
-
-When configure starts from a provider auth choice, the default-model and allowlist pickers prefer that provider automatically. For paired providers such as Volcengine and BytePlus, the same preference also matches their coding-plan variants (`volcengine-plan/*`, `byteplus-plan/*`). If the preferred-provider filter would produce an empty list, configure falls back to the unfiltered catalog instead of showing a blank picker.
-
-<Tip>
-`fengming config` without a subcommand opens the same wizard. Use `fengming config get|set|unset` for non-interactive edits.
-</Tip>
-
-For web search, `fengming configure --section web` lets you choose a provider
-and configure its credentials. Some providers also show provider-specific
-follow-up prompts:
-
-- **Grok** can offer optional `x_search` setup with the same xAI OAuth profile
-  or API key and let you pick an `x_search` model.
-- **Kimi** can ask for the Moonshot API region (`api.moonshot.ai` vs
-  `api.moonshot.cn`) and the default Kimi web-search model.
-
-Related:
-
-- Gateway configuration reference: [Configuration](/gateway/configuration)
-- Config CLI: [Config](/cli/config)
-
-## Options
-
-- `--section <section>`: repeatable section filter
-
-Available sections:
-
-- `workspace`
-- `model`
-- `web`
-- `gateway`
-- `daemon`
-- `channels`
-- `plugins`
-- `skills`
-- `health`
-
-Notes:
-
-- The full wizard and gateway-related sections ask where the Gateway runs and update `gateway.mode`. Section filters that do not include `gateway`, `daemon`, or `health` go directly to the requested setup.
-- After local config writes, configure installs selected downloadable plugins when the chosen setup path requires them. Remote gateway config does not install local plugin packages.
-- Channel-oriented services (Slack/Discord/Matrix/Microsoft Teams) prompt for channel/room allowlists during setup. You can enter names or IDs; the wizard resolves names to IDs when possible.
-- If you run the daemon install step, token auth requires a token, and `gateway.auth.token` is SecretRef-managed, configure validates the SecretRef but does not persist resolved plaintext token values into supervisor service environment metadata.
-- If token auth requires a token and the configured token SecretRef is unresolved, configure blocks daemon install with actionable remediation guidance.
-- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, configure blocks daemon install until mode is set explicitly.
-
-## Examples
-
-```bash
-fengming configure
-fengming configure --section web
-fengming configure --section model --section channels
-fengming configure --section gateway --section daemon
-```
-
-## Related
-
-- [CLI reference](/cli)
-- [Configuration](/gateway/configuration)