fengming 0.3.9 → 0.3.11

package/docs/cli/browser.md

@@ -1,307 +0,0 @@
----
-summary: "CLI reference for `fengming browser` (lifecycle, profiles, tabs, actions, state, and debugging)"
-read_when:
-  - You use `fengming browser` and want examples for common tasks
-  - You want to control a browser running on another machine via a node host
-  - You want to attach to your local signed-in Chrome via Chrome MCP
-title: "Browser"
----
-
-# `fengming browser`
-
-Manage FengMing's browser control surface and run browser actions (lifecycle, profiles, tabs, snapshots, screenshots, navigation, input, state emulation, and debugging).
-
-Related:
-
-- Browser tool + API: [Browser tool](/tools/browser)
-
-## Common flags
-
-- `--url <gatewayWsUrl>`: Gateway WebSocket URL (defaults to config).
-- `--token <token>`: Gateway token (if required).
-- `--timeout <ms>`: request timeout (ms).
-- `--expect-final`: wait for a final Gateway response.
-- `--browser-profile <name>`: choose a browser profile (default from config).
-- `--json`: machine-readable output (where supported).
-
-## Quick start (local)
-
-```bash
-fengming browser profiles
-fengming browser --browser-profile fengming start
-fengming browser --browser-profile fengming open https://example.com
-fengming browser --browser-profile fengming snapshot
-```
-
-Agents can run the same readiness check with `browser({ action: "doctor" })`.
-
-## Quick troubleshooting
-
-If `start` fails with `not reachable after start`, troubleshoot CDP readiness first. If `start` and `tabs` succeed but `open` or `navigate` fails, the browser control plane is healthy and the failure is usually navigation SSRF policy.
-
-Minimal sequence:
-
-```bash
-fengming browser --browser-profile fengming doctor
-fengming browser --browser-profile fengming start
-fengming browser --browser-profile fengming tabs
-fengming browser --browser-profile fengming open https://example.com
-```
-
-Detailed guidance: [Browser troubleshooting](/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block)
-
-## Lifecycle
-
-```bash
-fengming browser status
-fengming browser doctor
-fengming browser doctor --deep
-fengming browser start
-fengming browser start --headless
-fengming browser stop
-fengming browser --browser-profile fengming reset-profile
-```
-
-Notes:
-
-- `doctor --deep` adds a live snapshot probe. It is useful when basic CDP
-  readiness is green but you want proof that the current tab can be inspected.
-- For `attachOnly` and remote CDP profiles, `fengming browser stop` closes the
-  active control session and clears temporary emulation overrides even when
-  FengMing did not launch the browser process itself.
-- For local managed profiles, `fengming browser stop` stops the spawned browser
-  process.
-- `fengming browser start --headless` applies only to that start request and
-  only when FengMing launches a local managed browser. It does not rewrite
-  `browser.headless` or profile config, and it is a no-op for an already-running
-  browser.
-- On Linux hosts without `DISPLAY` or `WAYLAND_DISPLAY`, local managed profiles
-  run headless automatically unless `FENGMING_BROWSER_HEADLESS=0`,
-  `browser.headless=false`, or `browser.profiles.<name>.headless=false`
-  explicitly requests a visible browser.
-
-## If the command is missing
-
-If `fengming browser` is an unknown command, check `plugins.allow` in
-`~/.fengming/fengming.json`.
-
-When `plugins.allow` is present, list the bundled browser plugin explicitly
-unless the config already has a root `browser` block:
-
-```json5
-{
-  plugins: {
-    allow: ["telegram", "browser"],
-  },
-}
-```
-
-An explicit root `browser` block, for example `browser.enabled=true` or
-`browser.profiles.<name>`, also activates the bundled browser plugin under a
-restrictive plugin allowlist.
-
-Related: [Browser tool](/tools/browser#missing-browser-command-or-tool)
-
-## Profiles
-
-Profiles are named browser routing configs. In practice:
-
-- `fengming`: launches or attaches to a dedicated FengMing-managed Chrome instance (isolated user data dir).
-- `user`: controls your existing signed-in Chrome session via Chrome DevTools MCP.
-- custom CDP profiles: point at a local or remote CDP endpoint.
-
-```bash
-fengming browser profiles
-fengming browser create-profile --name work --color "#FF5A36"
-fengming browser create-profile --name chrome-live --driver existing-session
-fengming browser create-profile --name remote --cdp-url https://browser-host.example.com
-fengming browser delete-profile --name work
-```
-
-Use a specific profile:
-
-```bash
-fengming browser --browser-profile work tabs
-```
-
-## Tabs
-
-```bash
-fengming browser tabs
-fengming browser tab new --label docs
-fengming browser tab label t1 docs
-fengming browser tab select 2
-fengming browser tab close 2
-fengming browser open https://docs.fengming.ai --label docs
-fengming browser focus docs
-fengming browser close t1
-```
-
-`tabs` returns `suggestedTargetId` first, then the stable `tabId` such as `t1`,
-the optional label, and the raw `targetId`. Agents should pass
-`suggestedTargetId` back into `focus`, `close`, snapshots, and actions. You can
-assign a label with `open --label`, `tab new --label`, or `tab label`; labels,
-tab ids, raw target ids, and unique target-id prefixes are all accepted.
-When Chromium replaces the underlying raw target during a navigation or form
-submit, FengMing keeps the stable `tabId`/label attached to the replacement tab
-when it can prove the match. Raw target ids remain volatile; prefer
-`suggestedTargetId`.
-
-## Snapshot / screenshot / actions
-
-Snapshot:
-
-```bash
-fengming browser snapshot
-fengming browser snapshot --urls
-```
-
-Screenshot:
-
-```bash
-fengming browser screenshot
-fengming browser screenshot --full-page
-fengming browser screenshot --ref e12
-fengming browser screenshot --labels
-```
-
-Notes:
-
-- `--full-page` is for page captures only; it cannot be combined with `--ref`
-  or `--element`.
-- `existing-session` / `user` profiles support page screenshots and `--ref`
-  screenshots from snapshot output, but not CSS `--element` screenshots.
-- `--labels` overlays current snapshot refs on the screenshot.
-- `snapshot --urls` appends discovered link destinations to AI snapshots so
-  agents can choose direct navigation targets instead of guessing from link
-  text alone.
-
-Navigate/click/type (ref-based UI automation):
-
-```bash
-fengming browser navigate https://example.com
-fengming browser click <ref>
-fengming browser click-coords 120 340
-fengming browser type <ref> "hello"
-fengming browser press Enter
-fengming browser hover <ref>
-fengming browser scrollintoview <ref>
-fengming browser drag <startRef> <endRef>
-fengming browser select <ref> OptionA OptionB
-fengming browser fill --fields '[{"ref":"1","value":"Ada"}]'
-fengming browser wait --text "Done"
-fengming browser evaluate --fn '(el) => el.textContent' --ref <ref>
-fengming browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'
-```
-
-Use `evaluate --timeout-ms <ms>` when the page-side function may need longer
-than the default evaluate timeout.
-
-Action responses return the current raw `targetId` after action-triggered page
-replacement when FengMing can prove the replacement tab. Scripts should still
-store and pass `suggestedTargetId`/labels for long-lived workflows.
-
-File + dialog helpers:
-
-```bash
-fengming browser upload /tmp/fengming/uploads/file.pdf --ref <ref>
-fengming browser waitfordownload
-fengming browser download <ref> report.pdf
-fengming browser dialog --accept
-fengming browser dialog --dismiss --dialog-id d1
-```
-
-Managed Chrome profiles save ordinary click-triggered downloads into the FengMing
-downloads directory (`/tmp/fengming/downloads` by default, or the configured temp
-root). Use `waitfordownload` or `download` when the agent needs to wait for a
-specific file and return its path; those explicit waiters own the next download.
-When an action opens a modal dialog, the action response returns
-`blockedByDialog` with `browserState.dialogs.pending`; pass `--dialog-id` to
-answer it directly. Dialogs handled outside FengMing appear under
-`browserState.dialogs.recent`.
-
-## State and storage
-
-Viewport + emulation:
-
-```bash
-fengming browser resize 1280 720
-fengming browser set viewport 1280 720
-fengming browser set offline on
-fengming browser set media dark
-fengming browser set timezone Europe/London
-fengming browser set locale en-GB
-fengming browser set geo 51.5074 -0.1278 --accuracy 25
-fengming browser set device "iPhone 14"
-fengming browser set headers '{"x-test":"1"}'
-fengming browser set credentials myuser mypass
-```
-
-Cookies + storage:
-
-```bash
-fengming browser cookies
-fengming browser cookies set session abc123 --url https://example.com
-fengming browser cookies clear
-fengming browser storage local get
-fengming browser storage local set token abc123
-fengming browser storage session clear
-```
-
-## Debugging
-
-```bash
-fengming browser console --level error
-fengming browser pdf
-fengming browser responsebody "**/api"
-fengming browser highlight <ref>
-fengming browser errors --clear
-fengming browser requests --filter api
-fengming browser trace start
-fengming browser trace stop --out trace.zip
-```
-
-## Existing Chrome via MCP
-
-Use the built-in `user` profile, or create your own `existing-session` profile:
-
-```bash
-fengming browser --browser-profile user tabs
-fengming browser create-profile --name chrome-live --driver existing-session
-fengming browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
-fengming browser --browser-profile chrome-live tabs
-```
-
-This path is host-only. For Docker, headless servers, Browserless, or other remote setups, use a CDP profile instead.
-
-Current existing-session limits:
-
-- snapshot-driven actions use refs, not CSS selectors
-- `browser.actionTimeoutMs` defaults supported `act` requests to 60000 ms when
-  callers omit `timeoutMs`; per-call `timeoutMs` still wins.
-- `click` is left-click only
-- `type` does not support `slowly=true`
-- `press` does not support `delayMs`
-- `hover`, `scrollintoview`, `drag`, `select`, `fill`, and `evaluate` reject
-  per-call timeout overrides
-- `select` supports one value only
-- `wait --load networkidle` is not supported
-- file uploads require `--ref` / `--input-ref`, do not support CSS
-  `--element`, and currently support one file at a time
-- dialog hooks do not support `--timeout`
-- screenshots support page captures and `--ref`, but not CSS `--element`
-- `responsebody`, download interception, PDF export, and batch actions still
-  require a managed browser or raw CDP profile
-
-## Remote browser control (node host proxy)
-
-If the Gateway runs on a different machine than the browser, run a **node host** on the machine that has Chrome/Brave/Edge/Chromium. The Gateway will proxy browser actions to that node (no separate browser control server required).
-
-Use `gateway.nodes.browser.mode` to control auto-routing and `gateway.nodes.browser.node` to pin a specific node if multiple are connected.
-
-Security + remote setup: [Browser tool](/tools/browser), [Remote access](/gateway/remote), [Tailscale](/gateway/tailscale), [Security](/gateway/security)
-
-## Related
-
-- [CLI reference](/cli)
-- [Browser](/tools/browser)

package/docs/cli/channels.md

@@ -1,154 +0,0 @@
----
-summary: "CLI reference for `fengming channels` (accounts, status, login/logout, logs)"
-read_when:
-  - You want to add/remove channel accounts (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix)
-  - You want to check channel status or tail channel logs
-title: "Channels"
----
-
-# `fengming channels`
-
-Manage chat channel accounts and their runtime status on the Gateway.
-
-Related docs:
-
-- Channel guides: [Channels](/channels)
-- Gateway configuration: [Configuration](/gateway/configuration)
-
-## Common commands
-
-```bash
-fengming channels list
-fengming channels list --all
-fengming channels status
-fengming channels capabilities
-fengming channels capabilities --channel discord --target channel:123
-fengming channels capabilities --channel discord --target channel:<voice-channel-id>
-fengming channels resolve --channel slack "#general" "@jane"
-fengming channels logs --channel all
-```
-
-`channels list` shows chat channels only: configured accounts by default, with `installed`, `configured`, and `enabled` status tags per account. Pass `--all` to also surface bundled channels that have no configured account yet and installable catalog channels that are not yet on disk. Auth providers (OAuth + API keys) and model-provider usage/quota snapshots are no longer printed here; use `fengming models auth list` for provider auth profiles and `fengming status` or `fengming models list` for usage.
-
-## Status / capabilities / resolve / logs
-
-- `channels status`: `--channel <name>`, `--probe`, `--timeout <ms>`, `--json`
-- `channels capabilities`: `--channel <name>`, `--account <id>` (only with `--channel`), `--target <dest>`, `--timeout <ms>`, `--json`
-- `channels resolve`: `<entries...>`, `--channel <name>`, `--account <id>`, `--kind <auto|user|group>`, `--json`
-- `channels logs`: `--channel <name|all>`, `--lines <n>`, `--json`
-
-`channels status --probe` is the live path: on a reachable gateway it runs per-account
-`probeAccount` and optional `auditAccount` checks, so output can include transport
-state plus probe results such as `works`, `probe failed`, `audit ok`, or `audit failed`.
-If the gateway is unreachable, `channels status` falls back to config-only summaries
-instead of live probe output.
-
-Do not use `fengming sessions`, Gateway `sessions.list`, or the agent
-`sessions_list` tool as a channel socket-health signal. Those surfaces report
-stored conversation rows, not provider runtime state. After a Discord provider
-restart, a connected but quiet account may be healthy while no Discord session
-row appears until the next inbound or outbound conversation event.
-
-## Add / remove accounts
-
-```bash
-fengming channels add --channel telegram --token <bot-token>
-fengming channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
-fengming channels remove --channel telegram --delete
-```
-
-<Tip>
-`fengming channels add --help` shows per-channel flags (token, private key, app token, signal-cli paths, etc).
-</Tip>
-
-`channels remove` only operates on installed/configured channel plugins. Use `channels add` first for installable catalog channels.
-For runtime-backed channel plugins, `channels remove` also asks the running Gateway to stop the selected account before it updates config, so disabling or deleting an account does not leave the old listener active until restart.
-
-Common non-interactive add surfaces include:
-
-- bot-token channels: `--token`, `--bot-token`, `--app-token`, `--token-file`
-- Signal/iMessage transport fields: `--signal-number`, `--cli-path`, `--http-url`, `--http-host`, `--http-port`, `--db-path`, `--service`, `--region`
-- Google Chat fields: `--webhook-path`, `--webhook-url`, `--audience-type`, `--audience`
-- Matrix fields: `--homeserver`, `--user-id`, `--access-token`, `--password`, `--device-name`, `--initial-sync-limit`
-- Nostr fields: `--private-key`, `--relay-urls`
-- Tlon fields: `--ship`, `--url`, `--code`, `--group-channels`, `--dm-allowlist`, `--auto-discover-channels`
-- `--use-env` for default-account env-backed auth where supported
-
-If a channel plugin needs to be installed during a flag-driven add command, FengMing uses the channel's default install source without opening the interactive plugin install prompt.
-
-When you run `fengming channels add` without flags, the interactive wizard can prompt:
-
-- account ids per selected channel
-- optional display names for those accounts
-- `Route these channel accounts to agents now?`
-
-If you confirm bind now, the wizard asks which agent should own each configured channel account and writes account-scoped routing bindings.
-
-You can also manage the same routing rules later with `fengming agents bindings`, `fengming agents bind`, and `fengming agents unbind` (see [agents](/cli/agents)).
-
-When you add a non-default account to a channel that is still using single-account top-level settings, FengMing promotes account-scoped top-level values into the channel's account map before writing the new account. Most channels land those values in `channels.<channel>.accounts.default`, but bundled channels can preserve an existing matching promoted account instead. Matrix is the current example: if one named account already exists, or `defaultAccount` points at an existing named account, promotion preserves that account instead of creating a new `accounts.default`.
-
-Routing behavior stays consistent:
-
-- Existing channel-only bindings (no `accountId`) continue to match the default account.
-- `channels add` does not auto-create or rewrite bindings in non-interactive mode.
-- Interactive setup can optionally add account-scoped bindings.
-
-If your config was already in a mixed state (named accounts present and top-level single-account values still set), run `fengming doctor --fix` to move account-scoped values into the promoted account chosen for that channel. Most channels promote into `accounts.default`; Matrix can preserve an existing named/default target instead.
-
-## Login and logout (interactive)
-
-```bash
-fengming channels login --channel whatsapp
-fengming channels logout --channel whatsapp
-```
-
-- `channels login` supports `--verbose`.
-- `channels login` and `logout` can infer the channel when only one supported login target is configured.
-- `channels logout` prefers the live Gateway path when reachable, so logout stops any active listener before clearing channel auth state. If a local Gateway is not reachable, it falls back to local auth cleanup.
-- Run `channels login` from a terminal on the gateway host. Agent `exec` blocks this interactive login flow; channel-native agent login tools, such as `whatsapp_login`, should be used from chat when available.
-
-## Troubleshooting
-
-- Run `fengming status --deep` for a broad probe.
-- Use `fengming doctor` for guided fixes.
-- `fengming channels list` no longer prints model provider usage/quota snapshots. For those, use `fengming status` (overview) or `fengming models list` (per-provider).
-- `fengming channels status` falls back to config-only summaries when the gateway is unreachable. If a supported channel credential is configured via SecretRef but unavailable in the current command path, it reports that account as configured with degraded notes instead of showing it as not configured.
-
-## Capabilities probe
-
-Fetch provider capability hints (intents/scopes where available) plus static feature support:
-
-```bash
-fengming channels capabilities
-fengming channels capabilities --channel discord --target channel:123
-```
-
-Notes:
-
-- `--channel` is optional; omit it to list every channel (including extensions).
-- `--account` is only valid with `--channel`.
-- `--target` accepts `channel:<id>` or a raw numeric channel id and only applies to Discord. For Discord voice channels, the permission check flags missing `ViewChannel`, `Connect`, `Speak`, `SendMessages`, and `ReadMessageHistory`.
-- Probes are provider-specific: Discord intents + optional channel permissions; Slack bot + user scopes; Telegram bot flags + webhook; Signal daemon version; Microsoft Teams app token + Graph roles/scopes (annotated where known). Channels without probes report `Probe: unavailable`.
-
-## Resolve names to IDs
-
-Resolve channel/user names to IDs using the provider directory:
-
-```bash
-fengming channels resolve --channel slack "#general" "@jane"
-fengming channels resolve --channel discord "My Server/#support" "@someone"
-fengming channels resolve --channel matrix "Project Room"
-```
-
-Notes:
-
-- Use `--kind user|group|auto` to force the target type.
-- Resolution prefers active matches when multiple entries share the same name.
-- `channels resolve` is read-only. If a selected account is configured via SecretRef but that credential is unavailable in the current command path, the command returns degraded unresolved results with notes instead of aborting the entire run.
-- `channels resolve` does not install channel plugins. Use `channels add --channel <name>` before resolving names for an installable catalog channel.
-
-## Related
-
-- [CLI reference](/cli)
-- [Channels overview](/channels)

package/docs/cli/clawbot.md

@@ -1,25 +0,0 @@
----
-summary: "CLI reference for `fengming clawbot` (legacy alias namespace)"
-read_when:
-  - You maintain older scripts using `fengming clawbot ...`
-  - You need migration guidance to current commands
-title: "Clawbot"
----
-
-# `fengming clawbot`
-
-Legacy alias namespace kept for backwards compatibility.
-
-Current supported alias:
-
-- `fengming clawbot qr` (same behavior as [`fengming qr`](/cli/qr))
-
-## Migration
-
-Prefer modern top-level commands directly:
-
-- `fengming clawbot qr` -> `fengming qr`
-
-## Related
-
-- [CLI reference](/cli)

package/docs/cli/commitments.md

@@ -1,90 +0,0 @@
----
-summary: "CLI reference for `fengming commitments` (inspect and dismiss inferred follow-ups)"
-read_when:
-  - You want to inspect inferred follow-up commitments
-  - You want to dismiss pending check-ins
-  - You are auditing what heartbeat may deliver
-title: "`fengming commitments`"
----
-
-List and manage inferred follow-up commitments.
-
-Commitments are opt-in, short-lived follow-up memories created from
-conversation context. See [Inferred commitments](/concepts/commitments) for the
-conceptual guide.
-
-With no subcommand, `fengming commitments` lists pending commitments.
-
-## Usage
-
-```bash
-fengming commitments [--all] [--agent <id>] [--status <status>] [--json]
-fengming commitments list [--all] [--agent <id>] [--status <status>] [--json]
-fengming commitments dismiss <id...> [--json]
-```
-
-## Options
-
-- `--all`: show all statuses instead of only pending commitments.
-- `--agent <id>`: filter to one agent id.
-- `--status <status>`: filter by status. Values: `pending`, `sent`,
-  `dismissed`, `snoozed`, or `expired`.
-- `--json`: output machine-readable JSON.
-
-## Examples
-
-List pending commitments:
-
-```bash
-fengming commitments
-```
-
-List every stored commitment:
-
-```bash
-fengming commitments --all
-```
-
-Filter to one agent:
-
-```bash
-fengming commitments --agent main
-```
-
-Find snoozed commitments:
-
-```bash
-fengming commitments --status snoozed
-```
-
-Dismiss one or more commitments:
-
-```bash
-fengming commitments dismiss cm_abc123 cm_def456
-```
-
-Export as JSON:
-
-```bash
-fengming commitments --all --json
-```
-
-## Output
-
-Text output includes:
-
-- commitment id
-- status
-- kind
-- earliest due time
-- scope
-- suggested check-in text
-
-JSON output also includes the commitment store path and full stored records.
-
-## Related
-
-- [Inferred commitments](/concepts/commitments)
-- [Memory overview](/concepts/memory)
-- [Heartbeat](/gateway/heartbeat)
-- [Scheduled tasks](/automation/cron-jobs)

package/docs/cli/completion.md

@@ -1,39 +0,0 @@
----
-summary: "CLI reference for `fengming completion` (generate/install shell completion scripts)"
-read_when:
-  - You want shell completions for zsh/bash/fish/PowerShell
-  - You need to cache completion scripts under FengMing state
-title: "Completion"
----
-
-# `fengming completion`
-
-Generate shell completion scripts and optionally install them into your shell profile.
-
-## Usage
-
-```bash
-fengming completion
-fengming completion --shell zsh
-fengming completion --install
-fengming completion --shell fish --install
-fengming completion --write-state
-fengming completion --shell bash --write-state
-```
-
-## Options
-
-- `-s, --shell <shell>`: shell target (`zsh`, `bash`, `powershell`, `fish`; default: `zsh`)
-- `-i, --install`: install completion by adding a source line to your shell profile
-- `--write-state`: write completion script(s) to `$FENGMING_STATE_DIR/completions` without printing to stdout
-- `-y, --yes`: skip install confirmation prompts
-
-## Notes
-
-- `--install` writes a small "FengMing Completion" block into your shell profile and points it at the cached script.
-- Without `--install` or `--write-state`, the command prints the script to stdout.
-- Completion generation eagerly loads command trees so nested subcommands are included.
-
-## Related
-
-- [CLI reference](/cli)