fengming 0.3.9 → 0.3.11

package/docs/cli/agents.md

@@ -1,253 +0,0 @@
----
-summary: "CLI reference for `fengming agents` (list/add/delete/bindings/bind/unbind/set identity)"
-read_when:
-  - You want multiple isolated agents (workspaces + routing + auth)
-title: "Agents"
----
-
-# `fengming agents`
-
-Manage isolated agents (workspaces + auth + routing).
-
-Related:
-
-- [Multi-agent routing](/concepts/multi-agent)
-- [Agent workspace](/concepts/agent-workspace)
-- [Skills config](/tools/skills-config): skill visibility configuration.
-
-## Examples
-
-```bash
-fengming agents list
-fengming agents list --bindings
-fengming agents add work --workspace ~/.fengming/workspace-work
-fengming agents add work --workspace ~/.fengming/workspace-work --bind telegram:*
-fengming agents add ops --workspace ~/.fengming/workspace-ops --bind telegram:ops --non-interactive
-fengming agents bindings
-fengming agents bind --agent work --bind telegram:ops
-fengming agents unbind --agent work --bind telegram:ops
-fengming agents set-identity --workspace ~/.fengming/workspace --from-identity
-fengming agents set-identity --agent main --avatar avatars/fengming.png
-fengming agents delete work
-```
-
-## Routing bindings
-
-Use routing bindings to pin inbound channel traffic to a specific agent.
-
-If you also want different visible skills per agent, configure `agents.defaults.skills` and `agents.list[].skills` in `fengming.json`. See [Skills config](/tools/skills-config) and [Configuration reference](/gateway/config-agents#agents-defaults-skills).
-
-List bindings:
-
-```bash
-fengming agents bindings
-fengming agents bindings --agent work
-fengming agents bindings --json
-```
-
-Add bindings:
-
-```bash
-fengming agents bind --agent work --bind telegram:ops --bind discord:guild-a
-```
-
-You can also add bindings when creating an agent:
-
-```bash
-fengming agents add work --workspace ~/.fengming/workspace-work --bind telegram:* --bind discord:*
-```
-
-If you omit `accountId` (`--bind <channel>`), FengMing resolves it from plugin setup hooks, forced account binding, or the channel's configured account count.
-
-If you omit `--agent` for `bind` or `unbind`, FengMing targets the current default agent.
-
-### `--bind` format
-
-| Format                       | Meaning                                                                                           |
-| ---------------------------- | ------------------------------------------------------------------------------------------------- |
-| `--bind <channel>:*`         | Match all accounts on the channel.                                                                |
-| `--bind <channel>:<account>` | Match one account.                                                                                |
-| `--bind <channel>`           | Match the default account only unless the CLI can safely resolve a plugin-specific account scope. |
-
-### Binding scope behavior
-
-- A stored binding without `accountId` matches the channel default account only.
-- `accountId: "*"` is the channel-wide fallback (all accounts) and is less specific than an explicit account binding.
-- If the same agent already has a matching channel binding without `accountId`, and you later bind with an explicit or resolved `accountId`, FengMing upgrades that existing binding in place instead of adding a duplicate.
-
-Examples:
-
-```bash
-# match all accounts on the channel
-fengming agents bind --agent work --bind telegram:*
-
-# match a specific account
-fengming agents bind --agent work --bind telegram:ops
-
-# initial channel-only binding
-fengming agents bind --agent work --bind telegram
-
-# later upgrade to account-scoped binding
-fengming agents bind --agent work --bind telegram:alerts
-```
-
-After the upgrade, routing for that binding is scoped to `telegram:alerts`. If you also want default-account routing, add it explicitly (for example `--bind telegram:default`).
-
-Remove bindings:
-
-```bash
-fengming agents unbind --agent work --bind telegram:ops
-fengming agents unbind --agent work --all
-```
-
-`unbind` accepts either `--all` or one or more `--bind` values, not both.
-
-## Command surface
-
-### `agents`
-
-Running `fengming agents` with no subcommand is equivalent to `fengming agents list`.
-
-### `agents list`
-
-Options:
-
-- `--json`
-- `--bindings`: include full routing rules, not only per-agent counts/summaries
-
-### `agents add [name]`
-
-Options:
-
-- `--workspace <dir>`
-- `--model <id>`
-- `--agent-dir <dir>`
-- `--bind <channel[:accountId]>` (repeatable)
-- `--non-interactive`
-- `--json`
-
-Notes:
-
-- Passing any explicit add flags switches the command into the non-interactive path.
-- Non-interactive mode requires both an agent name and `--workspace`.
-- `main` is reserved and cannot be used as the new agent id.
-- In interactive mode, auth seeding copies only portable static profiles
-  (`api_key` and static `token` by default). OAuth refresh-token profiles remain
-  available only by read-through inheritance from the real `main` agent store.
-  If the configured default agent is not `main`, sign in separately for OAuth
-  profiles on the new agent.
-
-### `agents bindings`
-
-Options:
-
-- `--agent <id>`
-- `--json`
-
-### `agents bind`
-
-Options:
-
-- `--agent <id>` (defaults to the current default agent)
-- `--bind <channel[:accountId]>` (repeatable)
-- `--json`
-
-### `agents unbind`
-
-Options:
-
-- `--agent <id>` (defaults to the current default agent)
-- `--bind <channel[:accountId]>` (repeatable)
-- `--all`
-- `--json`
-
-### `agents delete <id>`
-
-Options:
-
-- `--force`
-- `--json`
-
-Notes:
-
-- `main` cannot be deleted.
-- Without `--force`, interactive confirmation is required.
-- Workspace, agent state, and session transcript directories are moved to Trash, not hard-deleted.
-- When the Gateway is reachable, deletion is sent through the Gateway so config and session-store cleanup share the same writer as runtime traffic. If the Gateway cannot be reached, the CLI falls back to the offline local path.
-- If another agent's workspace is the same path, inside this workspace, or contains this workspace,
-  the workspace is retained and `--json` reports `workspaceRetained`,
-  `workspaceRetainedReason`, and `workspaceSharedWith`.
-
-## Identity files
-
-Each agent workspace can include an `IDENTITY.md` at the workspace root:
-
-- Example path: `~/.fengming/workspace/IDENTITY.md`
-- `set-identity --from-identity` reads from the workspace root (or an explicit `--identity-file`)
-
-Avatar paths resolve relative to the workspace root.
-
-## Set identity
-
-`set-identity` writes fields into `agents.list[].identity`:
-
-- `name`
-- `theme`
-- `emoji`
-- `avatar` (workspace-relative path, http(s) URL, or data URI)
-
-Options:
-
-- `--agent <id>`
-- `--workspace <dir>`
-- `--identity-file <path>`
-- `--from-identity`
-- `--name <name>`
-- `--theme <theme>`
-- `--emoji <emoji>`
-- `--avatar <value>`
-- `--json`
-
-Notes:
-
-- `--agent` or `--workspace` can be used to select the target agent.
-- If you rely on `--workspace` and multiple agents share that workspace, the command fails and asks you to pass `--agent`.
-- When no explicit identity fields are provided, the command reads identity data from `IDENTITY.md`.
-
-Load from `IDENTITY.md`:
-
-```bash
-fengming agents set-identity --workspace ~/.fengming/workspace --from-identity
-```
-
-Override fields explicitly:
-
-```bash
-fengming agents set-identity --agent main --name "FengMing" --emoji "🦞" --avatar avatars/fengming.png
-```
-
-Config sample:
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "main",
-        identity: {
-          name: "FengMing",
-          theme: "space lobster",
-          emoji: "🦞",
-          avatar: "avatars/fengming.png",
-        },
-      },
-    ],
-  },
-}
-```
-
-## Related
-
-- [CLI reference](/cli)
-- [Multi-agent routing](/concepts/multi-agent)
-- [Agent workspace](/concepts/agent-workspace)

package/docs/cli/approvals.md

@@ -1,190 +0,0 @@
----
-summary: "CLI reference for `fengming approvals` and `fengming exec-policy`"
-read_when:
-  - You want to edit exec approvals from the CLI
-  - You need to manage allowlists on gateway or node hosts
-title: "Approvals"
----
-
-# `fengming approvals`
-
-Manage exec approvals for the **local host**, **gateway host**, or a **node host**.
-By default, commands target the local approvals file on disk. Use `--gateway` to target the gateway, or `--node` to target a specific node.
-
-Alias: `fengming exec-approvals`
-
-Related:
-
-- Exec approvals: [Exec approvals](/tools/exec-approvals)
-- Nodes: [Nodes](/nodes)
-
-## `fengming exec-policy`
-
-`fengming exec-policy` is the local convenience command for keeping the requested
-`tools.exec.*` config and the local host approvals file aligned in one step.
-
-Use it when you want to:
-
-- inspect the local requested policy, host approvals file, and effective merge
-- apply a local preset such as YOLO or deny-all
-- synchronize local `tools.exec.*` and local `~/.fengming/exec-approvals.json`
-
-Examples:
-
-```bash
-fengming exec-policy show
-fengming exec-policy show --json
-
-fengming exec-policy preset yolo
-fengming exec-policy preset cautious --json
-
-fengming exec-policy set --host gateway --security full --ask off --ask-fallback full
-```
-
-Output modes:
-
-- no `--json`: prints the human-readable table view
-- `--json`: prints machine-readable structured output
-
-Current scope:
-
-- `exec-policy` is **local-only**
-- it updates the local config file and the local approvals file together
-- it does **not** push policy to the gateway host or a node host
-- `--host node` is rejected in this command because node exec approvals are fetched from the node at runtime and must be managed through node-targeted approvals commands instead
-- `fengming exec-policy show` marks `host=node` scopes as node-managed at runtime instead of deriving an effective policy from the local approvals file
-
-If you need to edit remote host approvals directly, keep using `fengming approvals set --gateway`
-or `fengming approvals set --node <id|name|ip>`.
-
-## Common commands
-
-```bash
-fengming approvals get
-fengming approvals get --node <id|name|ip>
-fengming approvals get --gateway
-```
-
-`fengming approvals get` now shows the effective exec policy for local, gateway, and node targets:
-
-- requested `tools.exec` policy
-- host approvals-file policy
-- effective result after precedence rules are applied
-
-Precedence is intentional:
-
-- the host approvals file is the enforceable source of truth
-- requested `tools.exec` policy can narrow or broaden intent, but the effective result is still derived from the host rules
-- `--node` combines the node host approvals file with gateway `tools.exec` policy, because both still apply at runtime
-- if gateway config is unavailable, the CLI falls back to the node approvals snapshot and notes that the final runtime policy could not be computed
-
-## Replace approvals from a file
-
-```bash
-fengming approvals set --file ./exec-approvals.json
-fengming approvals set --stdin <<'EOF'
-{ version: 1, defaults: { security: "full", ask: "off" } }
-EOF
-fengming approvals set --node <id|name|ip> --file ./exec-approvals.json
-fengming approvals set --gateway --file ./exec-approvals.json
-```
-
-`set` accepts JSON5, not only strict JSON. Use either `--file` or `--stdin`, not both.
-
-## "Never prompt" / YOLO example
-
-For a host that should never stop on exec approvals, set the host approvals defaults to `full` + `off`:
-
-```bash
-fengming approvals set --stdin <<'EOF'
-{
-  version: 1,
-  defaults: {
-    security: "full",
-    ask: "off",
-    askFallback: "full"
-  }
-}
-EOF
-```
-
-Node variant:
-
-```bash
-fengming approvals set --node <id|name|ip> --stdin <<'EOF'
-{
-  version: 1,
-  defaults: {
-    security: "full",
-    ask: "off",
-    askFallback: "full"
-  }
-}
-EOF
-```
-
-This changes the **host approvals file** only. To keep the requested FengMing policy aligned, also set:
-
-```bash
-fengming config set tools.exec.host gateway
-fengming config set tools.exec.security full
-fengming config set tools.exec.ask off
-```
-
-Why `tools.exec.host=gateway` in this example:
-
-- `host=auto` still means "sandbox when available, otherwise gateway".
-- YOLO is about approvals, not routing.
-- If you want host exec even when a sandbox is configured, make the host choice explicit with `gateway` or `/exec host=gateway`.
-
-This matches the current host-default YOLO behavior. Tighten it if you want approvals.
-
-Local shortcut:
-
-```bash
-fengming exec-policy preset yolo
-```
-
-That local shortcut updates both the requested local `tools.exec.*` config and the
-local approvals defaults together. It is equivalent in intent to the manual two-step
-setup above, but only for the local machine.
-
-## Allowlist helpers
-
-```bash
-fengming approvals allowlist add "~/Projects/**/bin/rg"
-fengming approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
-fengming approvals allowlist add --agent "*" "/usr/bin/uname"
-
-fengming approvals allowlist remove "~/Projects/**/bin/rg"
-```
-
-## Common options
-
-`get`, `set`, and `allowlist add|remove` all support:
-
-- `--node <id|name|ip>`
-- `--gateway`
-- shared node RPC options: `--url`, `--token`, `--timeout`, `--json`
-
-Targeting notes:
-
-- no target flags means the local approvals file on disk
-- `--gateway` targets the gateway host approvals file
-- `--node` targets one node host after resolving id, name, IP, or id prefix
-
-`allowlist add|remove` also supports:
-
-- `--agent <id>` (defaults to `*`)
-
-## Notes
-
-- `--node` uses the same resolver as `fengming nodes` (id, name, ip, or id prefix).
-- `--agent` defaults to `"*"`, which applies to all agents.
-- The node host must advertise `system.execApprovals.get/set` (macOS app or headless node host).
-- Approvals files are stored per host at `~/.fengming/exec-approvals.json`.
-
-## Related
-
-- [CLI reference](/cli)
-- [Exec approvals](/tools/exec-approvals)

package/docs/cli/backup.md

@@ -1,98 +0,0 @@
----
-summary: "CLI reference for `fengming backup` (create local backup archives)"
-read_when:
-  - You want a first-class backup archive for local FengMing state
-  - You want to preview which paths would be included before reset or uninstall
-title: "Backup"
----
-
-# `fengming backup`
-
-Create a local backup archive for FengMing state, config, auth profiles, channel/provider credentials, sessions, and optionally workspaces.
-
-```bash
-fengming backup create
-fengming backup create --output ~/Backups
-fengming backup create --dry-run --json
-fengming backup create --verify
-fengming backup create --no-include-workspace
-fengming backup create --only-config
-fengming backup verify ./2026-03-09T08-00-00.000+08-00-fengming-backup.tar.gz
-```
-
-## Notes
-
-- The archive includes a `manifest.json` file with the resolved source paths and archive layout.
-- Default output is a timestamped `.tar.gz` archive in the current working directory.
-- Timestamped backup filenames use your machine's local timezone and include the UTC offset.
-- If the current working directory is inside a backed-up source tree, FengMing falls back to your home directory for the default archive location.
-- Existing archive files are never overwritten.
-- Output paths inside the source state/workspace trees are rejected to avoid self-inclusion.
-- `fengming backup verify <archive>` validates that the archive contains exactly one root manifest, rejects traversal-style archive paths, and checks that every manifest-declared payload exists in the tarball.
-- `fengming backup create --verify` runs that validation immediately after writing the archive.
-- `fengming backup create --only-config` backs up just the active JSON config file.
-
-## What gets backed up
-
-`fengming backup create` plans backup sources from your local FengMing install:
-
-- The state directory returned by FengMing's local state resolver, usually `~/.fengming`
-- The active config file path
-- The resolved `credentials/` directory when it exists outside the state directory
-- Workspace directories discovered from the current config, unless you pass `--no-include-workspace`
-
-Model auth profiles are already part of the state directory under
-`agents/<agentId>/agent/auth-profiles.json`, so they are normally covered by the
-state backup entry.
-
-If you use `--only-config`, FengMing skips state, credentials-directory, and workspace discovery and archives only the active config file path.
-
-FengMing canonicalizes paths before building the archive. If config, the
-credentials directory, or a workspace already live inside the state directory,
-they are not duplicated as separate top-level backup sources. Missing paths are
-skipped.
-
-The archive payload stores file contents from those source trees, and the embedded `manifest.json` records the resolved absolute source paths plus the archive layout used for each asset.
-
-During archive creation, FengMing skips known live-mutation files that do not have restoration value, including active agent session transcripts, cron run logs, rolling logs, delivery queues, socket/pid/temp files under the state directory, and related durable-queue temp files. The JSON result includes `skippedVolatileCount` so automation can see how many files were intentionally omitted.
-
-Installed plugin source and manifest files under the state directory's
-`extensions/` tree are included, but their nested `node_modules/` dependency
-trees are skipped. Those dependencies are rebuildable install artifacts; after
-restoring an archive, use `fengming plugins update <id>` or reinstall the plugin
-with `fengming plugins install <spec> --force` when a restored plugin reports
-missing dependencies.
-
-## Invalid config behavior
-
-`fengming backup` intentionally bypasses the normal config preflight so it can still help during recovery. Because workspace discovery depends on a valid config, `fengming backup create` now fails fast when the config file exists but is invalid and workspace backup is still enabled.
-
-If you still want a partial backup in that situation, rerun:
-
-```bash
-fengming backup create --no-include-workspace
-```
-
-That keeps state, config, and the external credentials directory in scope while
-skipping workspace discovery entirely.
-
-If you only need a copy of the config file itself, `--only-config` also works when the config is malformed because it does not rely on parsing the config for workspace discovery.
-
-## Size and performance
-
-FengMing does not enforce a built-in maximum backup size or per-file size limit.
-
-Practical limits come from the local machine and destination filesystem:
-
-- Available space for the temporary archive write plus the final archive
-- Time to walk large workspace trees and compress them into a `.tar.gz`
-- Time to rescan the archive if you use `fengming backup create --verify` or run `fengming backup verify`
-- Filesystem behavior at the destination path. FengMing prefers a no-overwrite hard-link publish step and falls back to exclusive copy when hard links are unsupported
-
-Large workspaces are usually the main driver of archive size. If you want a smaller or faster backup, use `--no-include-workspace`.
-
-For the smallest archive, use `--only-config`.
-
-## Related
-
-- [CLI reference](/cli)