fengming 0.3.9 → 0.3.11

package/docs/cli/security.md

@@ -1,136 +0,0 @@
----
-summary: "CLI reference for `fengming security` (audit and fix common security footguns)"
-read_when:
-  - You want to run a quick security audit on config/state
-  - You want to apply safe "fix" suggestions (permissions, tighten defaults)
-title: "Security"
----
-
-# `fengming security`
-
-Security tools (audit + optional fixes).
-
-Related:
-
-- Security guide: [Security](/gateway/security)
-
-## Audit
-
-```bash
-fengming security audit
-fengming security audit --deep
-fengming security audit --deep --password <password>
-fengming security audit --deep --token <token>
-fengming security audit --fix
-fengming security audit --json
-```
-
-Plain `security audit` stays on the cold config/filesystem/read-only path. It does not discover plugin runtime security collectors by default, so routine audits do not load every installed plugin runtime. Use `--deep` to include best-effort live Gateway probes and plugin-owned security audit collectors; explicit internal callers may also opt into those plugin-owned collectors when they already have an appropriate runtime scope.
-
-The audit warns when multiple DM senders share the main session and recommends **secure DM mode**: `session.dmScope="per-channel-peer"` (or `per-account-channel-peer` for multi-account channels) for shared inboxes.
-This is for cooperative/shared inbox hardening. A single Gateway shared by mutually untrusted/adversarial operators is not a recommended setup; split trust boundaries with separate gateways (or separate OS users/hosts).
-It also emits `security.trust_model.multi_user_heuristic` when config suggests likely shared-user ingress (for example open DM/group policy, configured group targets, or wildcard sender rules), and reminds you that FengMing is a personal-assistant trust model by default.
-For intentional shared-user setups, the audit guidance is to sandbox all sessions, keep filesystem access workspace-scoped, and keep personal/private identities or credentials off that runtime.
-It also warns when small models (`<=300B`) are used without sandboxing and with web/browser tools enabled.
-For webhook ingress, it warns when:
-
-- `hooks.token` reuses an active Gateway shared-secret auth value (`gateway.auth.token` / `FENGMING_GATEWAY_TOKEN` or `gateway.auth.password` / `FENGMING_GATEWAY_PASSWORD`)
-- `hooks.token` is short
-- `hooks.path="/"`
-- `hooks.defaultSessionKey` is unset
-- `hooks.allowedAgentIds` is unrestricted
-- request `sessionKey` overrides are enabled
-- overrides are enabled without `hooks.allowedSessionKeyPrefixes`
-
-If Gateway password auth is supplied only at startup, pass the same value to `fengming security audit --auth password --password <password>` so the audit can check it against `hooks.token`.
-Password-mode reuse is an audit finding for compatibility; rotate one of the secrets instead of expecting Gateway startup to reject that configuration.
-
-It also warns when sandbox Docker settings are configured while sandbox mode is off, when `gateway.nodes.denyCommands` uses ineffective pattern-like/unknown entries (exact node command-name matching only, not shell-text filtering), when `gateway.nodes.allowCommands` explicitly enables dangerous node commands, when global `tools.profile="minimal"` is overridden by agent tool profiles, when write/edit tools are disabled but `exec` is still available without a constraining sandbox filesystem boundary, when open groups expose runtime/filesystem tools without sandbox/workspace guards, and when installed plugin tools may be reachable under permissive tool policy.
-It also flags `gateway.allowRealIpFallback=true` (header-spoofing risk if proxies are misconfigured) and `discovery.mdns.mode="full"` (metadata leakage via mDNS TXT records).
-It also warns when sandbox browser uses Docker `bridge` network without `sandbox.browser.cdpSourceRange`.
-It also flags dangerous sandbox Docker network modes (including `host` and `container:*` namespace joins).
-It also warns when existing sandbox browser Docker containers have missing/stale hash labels (for example pre-migration containers missing `fengming.browserConfigEpoch`) and recommends `fengming sandbox recreate --browser --all`.
-It also warns when npm-based plugin/hook install records are unpinned, missing integrity metadata, or drift from currently installed package versions.
-It warns when channel allowlists rely on mutable names/emails/tags instead of stable IDs (Discord, Slack, Google Chat, Microsoft Teams, Mattermost, IRC scopes where applicable).
-It warns when `gateway.auth.mode="none"` leaves Gateway HTTP APIs reachable without a shared secret (`/tools/invoke` plus any enabled `/v1/*` endpoint).
-Settings prefixed with `dangerous`/`dangerously` are explicit break-glass operator overrides; enabling one is not, by itself, a security vulnerability report.
-For the complete dangerous-parameter inventory, see the "Insecure or dangerous flags summary" section in [Security](/gateway/security).
-
-Intentional standing findings can be accepted with `security.audit.suppressions`.
-Each suppression matches an exact `checkId` and can be narrowed with
-`titleIncludes` and/or `detailIncludes` case-insensitive substrings:
-
-```json
-{
-  "security": {
-    "audit": {
-      "suppressions": [
-        {
-          "checkId": "plugins.tools_reachable_permissive_policy",
-          "detailIncludes": "Enabled extension plugins: gbrain",
-          "reason": "trusted local operator plugin"
-        }
-      ]
-    }
-  }
-}
-```
-
-Suppressed findings are removed from the active `summary` and `findings` list.
-JSON output keeps them under `suppressedFindings` for auditability.
-When suppressions are configured, active output also keeps an unsuppressible
-`security.audit.suppressions.active` info finding so readers can tell the audit
-was filtered. Dangerous config flags are emitted one flag per finding, so
-accepting one dangerous flag does not hide other enabled flags that share the
-same `config.insecure_or_dangerous_flags` checkId.
-Because suppressions can hide standing risk, adding or removing them through
-agent-run shell commands requires exec approval unless exec is already running
-with `security="full"` and `ask="off"` for trusted local automation.
-
-SecretRef behavior:
-
-- `security audit` resolves supported SecretRefs in read-only mode for its targeted paths.
-- If a SecretRef is unavailable in the current command path, audit continues and reports `secretDiagnostics` (instead of crashing).
-- `--token` and `--password` only override deep-probe auth for that command invocation; they do not rewrite config or SecretRef mappings.
-
-## JSON output
-
-Use `--json` for CI/policy checks:
-
-```bash
-fengming security audit --json | jq '.summary'
-fengming security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'
-```
-
-If `--fix` and `--json` are combined, output includes both fix actions and final report:
-
-```bash
-fengming security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'
-```
-
-## What `--fix` changes
-
-`--fix` applies safe, deterministic remediations:
-
-- flips common `groupPolicy="open"` to `groupPolicy="allowlist"` (including account variants in supported channels)
-- when WhatsApp group policy flips to `allowlist`, seeds `groupAllowFrom` from
-  the stored `allowFrom` file when that list exists and config does not already
-  define `allowFrom`
-- sets `logging.redactSensitive` from `"off"` to `"tools"`
-- tightens permissions for state/config and common sensitive files
-  (`credentials/*.json`, `auth-profiles.json`, `sessions.json`, session
-  `*.jsonl`)
-- also tightens config include files referenced from `fengming.json`
-- uses `chmod` on POSIX hosts and `icacls` resets on Windows
-
-`--fix` does **not**:
-
-- rotate tokens/passwords/API keys
-- disable tools (`gateway`, `cron`, `exec`, etc.)
-- change gateway bind/auth/network exposure choices
-- remove or rewrite plugins/skills
-
-## Related
-
-- [CLI reference](/cli)
-- [Security audit](/gateway/security)

package/docs/cli/sessions.md

@@ -1,164 +0,0 @@
----
-summary: "CLI reference for `fengming sessions` (list stored sessions + usage)"
-read_when:
-  - You want to list stored sessions and see recent activity
-title: "Sessions"
----
-
-# `fengming sessions`
-
-List stored conversation sessions.
-
-Session lists are not channel/provider liveness checks. They show persisted
-conversation rows from session stores. A quiet Discord, Slack, Telegram, or
-other channel can reconnect successfully without creating a new session row
-until a message is processed. Use `fengming channels status --probe`,
-`fengming status --deep`, or `fengming health --verbose` when you need live
-channel connectivity.
-
-`fengming sessions` and Gateway `sessions.list` responses are bounded by
-default so large long-lived stores cannot monopolize the CLI process or Gateway
-event loop. The CLI returns the newest 100 sessions by default; pass
-`--limit <n>` for a smaller/larger window or `--limit all` when you intentionally
-need the full store. JSON responses include `totalCount`, `limitApplied`, and
-`hasMore` when callers need to show that more rows exist.
-
-RPC clients can pass `configuredAgentsOnly: true` to keep the broad combined
-discovery source but return only rows for agents currently present in config.
-Control UI uses that mode by default so deleted or disk-only agent stores do
-not reappear in the Sessions view.
-
-```bash
-fengming sessions
-fengming sessions --agent work
-fengming sessions --all-agents
-fengming sessions --active 120
-fengming sessions --limit 25
-fengming sessions --verbose
-fengming sessions --json
-```
-
-Scope selection:
-
-- default: configured default agent store
-- `--verbose`: verbose logging
-- `--agent <id>`: one configured agent store
-- `--all-agents`: aggregate all configured agent stores
-- `--store <path>`: explicit store path (cannot be combined with `--agent` or `--all-agents`)
-- `--limit <n|all>`: max rows to output (default `100`; `all` restores full output)
-
-Export a trajectory bundle for a stored session:
-
-```bash
-fengming sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
-fengming sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
-```
-
-This is the command path used by the `/export-trajectory` slash command after
-the owner approves the exec request. The output directory is always resolved
-inside `.fengming/trajectory-exports/` under the selected workspace.
-
-`fengming sessions --all-agents` reads configured agent stores. Gateway and ACP
-session discovery are broader: they also include disk-only stores found under
-the default `agents/` root or a templated `session.store` root. Those
-discovered stores must resolve to regular `sessions.json` files inside the
-agent root; symlinks and out-of-root paths are skipped.
-
-JSON examples:
-
-`fengming sessions --all-agents --json`:
-
-```json
-{
-  "path": null,
-  "stores": [
-    { "agentId": "main", "path": "/home/user/.fengming/agents/main/sessions/sessions.json" },
-    { "agentId": "work", "path": "/home/user/.fengming/agents/work/sessions/sessions.json" }
-  ],
-  "allAgents": true,
-  "count": 2,
-  "totalCount": 2,
-  "limitApplied": 100,
-  "hasMore": false,
-  "activeMinutes": null,
-  "sessions": [
-    { "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
-    { "agentId": "work", "key": "agent:work:main", "model": "claude-opus-4-6" }
-  ]
-}
-```
-
-## Cleanup maintenance
-
-Run maintenance now (instead of waiting for the next write cycle):
-
-```bash
-fengming sessions cleanup --dry-run
-fengming sessions cleanup --agent work --dry-run
-fengming sessions cleanup --all-agents --dry-run
-fengming sessions cleanup --enforce
-fengming sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"
-fengming sessions cleanup --dry-run --fix-dm-scope
-fengming sessions cleanup --json
-```
-
-`fengming sessions cleanup` uses `session.maintenance` settings from config:
-
-- Scope note: `fengming sessions cleanup` maintains session stores, transcripts, and trajectory sidecars. It does not prune cron run logs (`cron/runs/<jobId>.jsonl`), which are managed by `cron.runLog.maxBytes` and `cron.runLog.keepLines` in [Cron configuration](/automation/cron-jobs#configuration) and explained in [Cron maintenance](/automation/cron-jobs#maintenance).
-- Cleanup also prunes unreferenced primary transcripts, compaction checkpoints, and trajectory sidecars older than `session.maintenance.pruneAfter`; files still referenced by `sessions.json` are preserved.
-
-- `--dry-run`: preview how many entries would be pruned/capped without writing.
-  - In text mode, dry-run prints a per-session action table (`Action`, `Key`, `Age`, `Model`, `Flags`) so you can see what would be kept vs removed.
-- `--enforce`: apply maintenance even when `session.maintenance.mode` is `warn`.
-- `--fix-missing`: remove entries whose transcript files are missing or header-only/empty, even if they would not normally age/count out yet.
-- `--fix-dm-scope`: when `session.dmScope` is `main`, retire stale peer-keyed direct-DM rows left behind by earlier `per-peer`, `per-channel-peer`, or `per-account-channel-peer` routing. Use `--dry-run` first; applying the cleanup removes those rows from `sessions.json` and preserves their transcripts as deleted archives.
-- `--active-key <key>`: protect a specific active key from disk-budget eviction. Durable external conversation pointers, such as group sessions and thread-scoped chat sessions, are also kept by age/count/disk-budget maintenance.
-- `--agent <id>`: run cleanup for one configured agent store.
-- `--all-agents`: run cleanup for all configured agent stores.
-- `--store <path>`: run against a specific `sessions.json` file.
-- `--json`: print a JSON summary. With `--all-agents`, output includes one summary per store.
-
-When a Gateway is reachable, non-dry-run cleanup for configured agent stores is
-sent through the Gateway so it shares the same session-store writer as runtime
-traffic. Use `--store <path>` for explicit offline repair of a store file.
-
-`fengming sessions cleanup --all-agents --dry-run --json`:
-
-```json
-{
-  "allAgents": true,
-  "mode": "warn",
-  "dryRun": true,
-  "stores": [
-    {
-      "agentId": "main",
-      "storePath": "/home/user/.fengming/agents/main/sessions/sessions.json",
-      "beforeCount": 120,
-      "afterCount": 80,
-      "missing": 0,
-      "dmScopeRetired": 0,
-      "pruned": 40,
-      "capped": 0
-    },
-    {
-      "agentId": "work",
-      "storePath": "/home/user/.fengming/agents/work/sessions/sessions.json",
-      "beforeCount": 18,
-      "afterCount": 18,
-      "missing": 0,
-      "dmScopeRetired": 0,
-      "pruned": 0,
-      "capped": 0
-    }
-  ]
-}
-```
-
-Related:
-
-- Session config: [Configuration reference](/gateway/config-agents#session)
-
-## Related
-
-- [CLI reference](/cli)
-- [Session management](/concepts/session)

package/docs/cli/setup.md

@@ -1,59 +0,0 @@
----
-summary: "CLI reference for `fengming setup` (initialize config plus workspace, optionally run onboarding)"
-read_when:
-  - You're doing first-run setup without full CLI onboarding
-  - You want to set the default workspace path
-  - You need every flag and how setup decides between baseline and wizard mode
-title: "Setup"
----
-
-# `fengming setup`
-
-Initialize the baseline config and agent workspace. With any onboarding flag present, also runs the wizard.
-
-<Note>
-`fengming setup` is for mutable config installs. In Nix mode (`FENGMING_NIX_MODE=1`) FengMing refuses setup writes because the config file is managed by Nix. Use the first-party [nix-fengming Quick Start](https://github.com/fengming/nix-fengming#quick-start) or the equivalent source config for another Nix package.
-</Note>
-
-## Options
-
-| Flag                       | Description                                                                                         |
-| -------------------------- | --------------------------------------------------------------------------------------------------- |
-| `--workspace <dir>`        | Agent workspace directory (default `~/.fengming/workspace`; stored as `agents.defaults.workspace`). |
-| `--wizard`                 | Run interactive onboarding.                                                                         |
-| `--non-interactive`        | Run onboarding without prompts.                                                                     |
-| `--mode <mode>`            | Onboarding mode: `local` or `remote`.                                                               |
-| `--import-from <provider>` | Migration provider to run during onboarding.                                                        |
-| `--import-source <path>`   | Source agent home for `--import-from`.                                                              |
-| `--import-secrets`         | Import supported secrets during onboarding migration.                                               |
-| `--remote-url <url>`       | Remote Gateway WebSocket URL.                                                                       |
-| `--remote-token <token>`   | Remote Gateway token (optional).                                                                    |
-
-### Wizard auto-trigger
-
-`fengming setup` runs the wizard when any of these flags are explicitly present, even without `--wizard`:
-
-`--wizard`, `--non-interactive`, `--mode`, `--import-from`, `--import-source`, `--import-secrets`, `--remote-url`, `--remote-token`.
-
-## Examples
-
-```bash
-fengming setup
-fengming setup --workspace ~/.fengming/workspace
-fengming setup --wizard
-fengming setup --wizard --import-from hermes --import-source ~/.hermes
-fengming setup --non-interactive --mode remote --remote-url wss://gateway-host:18789 --remote-token <token>
-```
-
-## Notes
-
-- Plain `fengming setup` initializes config and workspace without running the full onboarding flow.
-- After plain setup, run `fengming onboard` for the full guided journey, `fengming configure` for targeted changes, or `fengming channels add` to add channel accounts.
-- If Hermes state is detected, interactive onboarding can offer migration automatically. Import onboarding requires a fresh setup; use [Migrate](/cli/migrate) for dry-run plans, backups, and overwrite mode outside onboarding.
-
-## Related
-
-- [CLI reference](/cli)
-- [Onboarding (CLI)](/start/wizard)
-- [Getting started](/start/getting-started)
-- [Install overview](/install)

package/docs/cli/skills.md

@@ -1,122 +0,0 @@
----
-summary: "CLI reference for `fengming skills` (search/install/update/verify/list/info/check)"
-read_when:
-  - You want to see which skills are available and ready to run
-  - You want to search ClawHub or install skills from ClawHub, Git, or local directories
-  - You want to verify a ClawHub skill with ClawHub
-  - You want to debug missing binaries/env/config for skills
-title: "Skills"
----
-
-# `fengming skills`
-
-Inspect local skills, search ClawHub, install skills from ClawHub/Git/local
-directories, verify ClawHub skills, and update ClawHub-tracked installs.
-
-Related:
-
-- Skills system: [Skills](/tools/skills)
-- Skills config: [Skills config](/tools/skills-config)
-- ClawHub installs: [ClawHub](/clawhub/cli)
-
-## Commands
-
-```bash
-fengming skills search "calendar"
-fengming skills search --limit 20 --json
-fengming skills install <slug>
-fengming skills install <slug> --version <version>
-fengming skills install git:owner/repo
-fengming skills install git:owner/repo@main
-fengming skills install ./path/to/skill --as custom-name
-fengming skills install <slug> --force
-fengming skills install <slug> --agent <id>
-fengming skills install <slug> --global
-fengming skills update <slug>
-fengming skills update <slug> --global
-fengming skills update --all
-fengming skills update --all --agent <id>
-fengming skills update --all --global
-fengming skills verify <slug>
-fengming skills verify <slug> --version <version>
-fengming skills verify <slug> --tag <tag>
-fengming skills verify <slug> --card
-fengming skills verify <slug> --global
-fengming skills list
-fengming skills list --eligible
-fengming skills list --json
-fengming skills list --verbose
-fengming skills list --agent <id>
-fengming skills info <name>
-fengming skills info <name> --json
-fengming skills info <name> --agent <id>
-fengming skills check
-fengming skills check --agent <id>
-fengming skills check --json
-```
-
-`search`, `update`, and `verify` use ClawHub directly. `install <slug>` installs
-a ClawHub skill, `install git:owner/repo[@ref]` clones a Git skill, and
-`install ./path` copies a local skill directory. By default, `install`, `update`,
-and `verify` target the active workspace `skills/` directory; with `--global`,
-they target the shared managed skills directory. `list`/`info`/`check` still
-inspect the local skills visible to the current workspace and config.
-Workspace-backed commands resolve the target workspace from `--agent <id>`, then
-the current working directory when it is inside a configured agent workspace,
-then the default agent.
-
-Git and local directory installs expect `SKILL.md` at the source root. The
-install slug comes from `SKILL.md` frontmatter `name` when it is valid, then the
-source directory or repository name; use `--as <slug>` to override it. `--version`
-is ClawHub-only. Skill installs do not support npm package specs or zip/archive
-paths, and `fengming skills update` updates ClawHub-tracked installs only.
-
-Gateway-backed skill dependency installs triggered from onboarding or Skills
-settings use the separate `skills.install` request path instead.
-
-Notes:
-
-- `search [query...]` accepts an optional query; omit it to browse the default
-  ClawHub search feed.
-- `search --limit <n>` caps returned results.
-- `install git:owner/repo[@ref]` installs a Git skill. Branch refs may contain
-  slashes, such as `git:owner/repo@feature/foo`.
-- `install ./path/to/skill` installs a local directory whose root contains
-  `SKILL.md`.
-- `install --as <slug>` overrides the inferred slug for Git and local directory
-  installs.
-- `install --version <version>` applies only to ClawHub skill slugs.
-- `install --force` overwrites an existing workspace skill folder for the same
-  slug.
-- `--global` targets the shared managed skills directory and cannot be combined
-  with `--agent <id>`.
-- `--agent <id>` targets one configured agent workspace and overrides current
-  working directory inference.
-- `update <slug>` updates a single tracked skill. Add `--global` to target the
-  shared managed skills directory instead of the workspace.
-- `update --all` updates tracked ClawHub installs in the selected workspace, or
-  in the shared managed skills directory when combined with `--global`.
-- `verify <slug>` prints ClawHub's `clawhub.skill.verify.v1` JSON envelope by
-  default. There is no `--json` flag because JSON is already the default.
-- `verify` uses `.clawhub/origin.json` for installed ClawHub skills, so it
-  verifies the installed version against the registry it came from. `--version`
-  and `--tag` override the version selector but keep that installed registry
-  when origin metadata exists.
-- `verify --card` prints the generated Skill Card Markdown instead of JSON. The
-  command exits non-zero when ClawHub returns `ok: false` or `decision: "fail"`;
-  unsigned signatures are informational unless ClawHub policy changes.
-- Installed ClawHub bundles can include a generated `skill-card.md`. FengMing
-  treats verification as a ClawHub server decision and does not reject an
-  installed skill just because that generated card changes the bundle
-  fingerprint.
-- `check --agent <id>` checks the selected agent's workspace and reports which
-  ready skills are actually visible to that agent's prompt or command surface.
-- `list` is the default action when no subcommand is provided.
-- `list`, `info`, and `check` write their rendered output to stdout. With
-  `--json`, that means the machine-readable payload stays on stdout for pipes
-  and scripts.
-
-## Related
-
-- [CLI reference](/cli)
-- [Skills](/tools/skills)

package/docs/cli/status.md

@@ -1,45 +0,0 @@
----
-summary: "CLI reference for `fengming status` (diagnostics, probes, usage snapshots)"
-read_when:
-  - You want a quick diagnosis of channel health + recent session recipients
-  - You want a pasteable "all" status for debugging
-title: "fengming status"
----
-
-Diagnostics for channels + sessions.
-
-```bash
-fengming status
-fengming status --all
-fengming status --deep
-fengming status --usage
-```
-
-Notes:
-
-- `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal).
-- Plain `fengming status` stays on the fast read-only path and marks memory as `not checked` instead of unavailable when it skips memory inspection. Heavy security audit, plugin compatibility, and memory-vector probes are left to `fengming status --all`, `fengming status --deep`, `fengming security audit`, and `fengming memory status --deep`.
-- `status --json --all` reports memory details from the active memory plugin runtime selected by `plugins.slots.memory`. Custom memory plugins can leave built-in `agents.defaults.memorySearch.enabled` disabled and still report their own files, chunks, vector, and FTS state.
-- `--usage` prints normalized provider usage windows as `X% left`.
-- Session status output separates `Execution:` from `Runtime:`. `Execution` is the sandbox path (`direct`, `docker/*`), while `Runtime` tells you whether the session is using `FengMing Default`, `OpenAI Codex`, a CLI backend, or an ACP backend such as `codex (acp/acpx)`. See [Agent runtimes](/concepts/agent-runtimes) for the provider/model/runtime distinction.
-- MiniMax's raw `usage_percent` / `usagePercent` fields are remaining quota, so FengMing inverts them before display; count-based fields win when present. `model_remains` responses prefer the chat-model entry, derive the window label from timestamps when needed, and include the model name in the plan label.
-- When the current session snapshot is sparse, `/status` can backfill token and cache counters from the most recent transcript usage log. Existing nonzero live values still win over transcript fallback values.
-- `/status` includes compact Gateway process uptime and host system uptime.
-- Transcript fallback can also recover the active runtime model label when the live session entry is missing it. If that transcript model differs from the selected model, status resolves the context window against the recovered runtime model instead of the selected one.
-- When a session is pinned to a model that differs from the configured primary, status prints both values, the reason (`session override`), and the clear hint (`/model <configured-default>` or `/reset`). The configured primary applies to new or unpinned sessions; existing pinned sessions keep their session selection until cleared.
-- For prompt-size accounting, transcript fallback prefers the larger prompt-oriented total when session metadata is missing or smaller, so custom-provider sessions do not collapse to `0` token displays.
-- Output includes per-agent session stores when multiple agents are configured.
-- Overview includes Gateway + node host service install/runtime status when available.
-- Overview includes update channel + git SHA (for source checkouts).
-- Update info surfaces in the Overview; if an update is available, status prints a hint to run `fengming update` (see [Updating](/install/updating)).
-- Model pricing refresh failures are shown as optional pricing warnings. They do
-  not mean the Gateway or channels are unhealthy.
-- Read-only status surfaces (`status`, `status --json`, `status --all`) resolve supported SecretRefs for their targeted config paths when possible.
-- If a supported channel SecretRef is configured but unavailable in the current command path, status stays read-only and reports degraded output instead of crashing. Human output shows warnings such as "configured token unavailable in this command path", and JSON output includes `secretDiagnostics`.
-- When command-local SecretRef resolution succeeds, status prefers the resolved snapshot and clears transient "secret unavailable" channel markers from the final output.
-- `status --all` includes a Secrets overview row and a diagnosis section that summarizes secret diagnostics (truncated for readability) without stopping report generation.
-
-## Related
-
-- [CLI reference](/cli)
-- [Doctor](/gateway/doctor)

package/docs/cli/system.md

@@ -1,89 +0,0 @@
----
-summary: "CLI reference for `fengming system` (system events, heartbeat, presence)"
-read_when:
-  - You want to enqueue a system event without creating a cron job
-  - You need to enable or disable heartbeats
-  - You want to inspect system presence entries
-title: "System"
----
-
-# `fengming system`
-
-System-level helpers for the Gateway: enqueue system events, control heartbeats,
-and view presence.
-
-All `system` subcommands use Gateway RPC and accept the shared client flags:
-
-- `--url <url>`
-- `--token <token>`
-- `--timeout <ms>`
-- `--expect-final`
-
-## Common commands
-
-```bash
-fengming system event --text "Check for urgent follow-ups" --mode now
-fengming system event --text "Check for urgent follow-ups" --url ws://127.0.0.1:18789 --token "$FENGMING_GATEWAY_TOKEN"
-fengming system heartbeat enable
-fengming system heartbeat last
-fengming system presence
-```
-
-## `system event`
-
-Enqueue a system event on the **main** session by default. The next heartbeat
-will inject it as a `System:` line in the prompt. Use `--mode now` to trigger
-the heartbeat immediately; `next-heartbeat` waits for the next scheduled tick.
-
-Pass `--session-key` to target a specific session (for example to relay an
-async-task completion back to the channel that started it).
-
-> **Timing exception with `--session-key`:** when `--session-key` is supplied,
-> `--mode next-heartbeat` collapses to an immediate targeted wake instead of
-> waiting for the next scheduled tick. Targeted wakes use heartbeat intent
-> `immediate` so they bypass the runner's not-due gate that would otherwise
-> defer (and effectively drop) an `event`-intent wake. If you want delayed
-> delivery, omit `--session-key` so the event lands on the main session and
-> rides the next regular heartbeat.
-
-Flags:
-
-- `--text <text>`: required system event text.
-- `--mode <mode>`: `now` or `next-heartbeat` (default).
-- `--session-key <sessionKey>`: optional; target a specific agent session
-  instead of the agent's main session. Keys that do not belong to the
-  resolved agent fall back to the agent's main session.
-- `--json`: machine-readable output.
-- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
-
-## `system heartbeat last|enable|disable`
-
-Heartbeat controls:
-
-- `last`: show the last heartbeat event.
-- `enable`: turn heartbeats back on (use this if they were disabled).
-- `disable`: pause heartbeats.
-
-Flags:
-
-- `--json`: machine-readable output.
-- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
-
-## `system presence`
-
-List the current system presence entries the Gateway knows about (nodes,
-instances, and similar status lines).
-
-Flags:
-
-- `--json`: machine-readable output.
-- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
-
-## Notes
-
-- Requires a running Gateway reachable by your current config (local or remote).
-- System events are ephemeral and not persisted across restarts.
-
-## Related
-
-- [CLI reference](/cli)