fengming 0.3.9 → 0.3.11

package/docs/cli/daemon.md

@@ -1,67 +0,0 @@
----
-summary: "CLI reference for `fengming daemon` (legacy alias for gateway service management)"
-read_when:
-  - You still use `fengming daemon ...` in scripts
-  - You need service lifecycle commands (install/start/stop/restart/status)
-title: "Daemon"
----
-
-# `fengming daemon`
-
-Legacy alias for Gateway service management commands.
-
-`fengming daemon ...` maps to the same service control surface as `fengming gateway ...` service commands.
-
-## Usage
-
-```bash
-fengming daemon status
-fengming daemon install
-fengming daemon start
-fengming daemon stop
-fengming daemon restart
-fengming daemon uninstall
-```
-
-## Subcommands
-
-- `status`: show service install state and probe Gateway health
-- `install`: install service (`launchd`/`systemd`/`schtasks`)
-- `uninstall`: remove service
-- `start`: start service
-- `stop`: stop service
-- `restart`: restart service
-
-## Common options
-
-- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
-- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
-- `restart`: `--safe`, `--skip-deferral`, `--force`, `--wait <duration>`, `--json`
-- lifecycle (`uninstall|start|stop`): `--json`
-
-Notes:
-
-- `status` resolves configured auth SecretRefs for probe auth when possible.
-- If a required auth SecretRef is unresolved in this command path, `daemon status --json` reports `rpc.authWarning` when probe connectivity/auth fails; pass `--token`/`--password` explicitly or resolve the secret source first.
-- If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
-- `status --deep` adds a best-effort system-level service scan. When it finds other gateway-like services, human output prints cleanup hints and warns that one gateway per machine is still the normal recommendation.
-- `status --deep` also runs config validation in plugin-aware mode and surfaces configured plugin manifest warnings (for example missing channel config metadata) so install and update smoke checks catch them. Default `status` keeps the fast read-only path that skips plugin validation.
-- On Linux systemd installs, `status` token-drift checks include both `Environment=` and `EnvironmentFile=` unit sources.
-- Drift checks resolve `gateway.auth.token` SecretRefs using merged runtime env (service command env first, then process env fallback).
-- If token auth is not effectively active (explicit `gateway.auth.mode` of `password`/`none`/`trusted-proxy`, or mode unset where password can win and no token candidate can win), token-drift checks skip config token resolution.
-- When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `install` validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
-- If token auth requires a token and the configured token SecretRef is unresolved, install fails closed.
-- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, install is blocked until mode is set explicitly.
-- On macOS, `install` keeps LaunchAgent plists owner-only and loads managed service environment values through an owner-only file and wrapper instead of serializing API keys or auth-profile env refs into `EnvironmentVariables`.
-- If you intentionally run multiple gateways on one host, isolate ports, config/state, and workspaces; see [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host).
-- `restart --safe` asks the running Gateway to preflight active work and schedule one coalesced restart after active work drains. Plain `restart` keeps the existing service-manager behavior; `--force` remains the immediate override path.
-- `restart --safe --skip-deferral` runs the FengMing-aware safe restart but bypasses the active-work deferral gate so the Gateway emits the restart immediately even when blockers are reported. Operator escape hatch when a stuck task run pins the safe restart; requires `--safe`.
-
-## Prefer
-
-Use [`fengming gateway`](/cli/gateway) for current docs and examples.
-
-## Related
-
-- [CLI reference](/cli)
-- [Gateway runbook](/gateway)

package/docs/cli/dashboard.md

@@ -1,33 +0,0 @@
----
-summary: "CLI reference for `fengming dashboard` (open the Control UI)"
-read_when:
-  - You want to open the Control UI with your current token
-  - You want to print the URL without launching a browser
-title: "Dashboard"
----
-
-# `fengming dashboard`
-
-Open the Control UI using your current auth.
-
-```bash
-fengming dashboard
-fengming dashboard --no-open
-```
-
-Notes:
-
-- `dashboard` resolves configured `gateway.auth.token` SecretRefs when possible.
-- `dashboard` follows `gateway.tls.enabled`: TLS-enabled gateways print/open
-  `https://` Control UI URLs and connect over `wss://`.
-- If clipboard/browser delivery fails for a token-authenticated dashboard URL,
-  `dashboard` logs a safe manual-auth hint naming `FENGMING_GATEWAY_TOKEN`,
-  `gateway.auth.token`, and fragment key `token` without printing the token
-  value.
-- For SecretRef-managed tokens (resolved or unresolved), `dashboard` prints/copies/opens a non-tokenized URL to avoid exposing external secrets in terminal output, clipboard history, or browser-launch arguments.
-- If `gateway.auth.token` is SecretRef-managed but unresolved in this command path, the command prints a non-tokenized URL and explicit remediation guidance instead of embedding an invalid token placeholder.
-
-## Related
-
-- [CLI reference](/cli)
-- [Dashboard](/web/dashboard)

package/docs/cli/devices.md

@@ -1,240 +0,0 @@
----
-summary: "CLI reference for `fengming devices` (device pairing + token rotation/revocation)"
-read_when:
-  - You are approving device pairing requests
-  - You need to rotate or revoke device tokens
-title: "Devices"
----
-
-# `fengming devices`
-
-Manage device pairing requests and device-scoped tokens.
-
-## Commands
-
-### `fengming devices list`
-
-List pending pairing requests and paired devices.
-
-```
-fengming devices list
-fengming devices list --json
-```
-
-Pending request output shows the requested access next to the device's current
-approved access when the device is already paired. This makes scope/role
-upgrades explicit instead of looking like the pairing was lost.
-
-### `fengming devices remove <deviceId>`
-
-Remove one paired device entry.
-
-When you are authenticated with a paired device token, non-admin callers can
-remove only **their own** device entry. Removing some other device requires
-`operator.admin`.
-
-```
-fengming devices remove <deviceId>
-fengming devices remove <deviceId> --json
-```
-
-### `fengming devices clear --yes [--pending]`
-
-Clear paired devices in bulk.
-
-```
-fengming devices clear --yes
-fengming devices clear --yes --pending
-fengming devices clear --yes --pending --json
-```
-
-### `fengming devices approve [requestId] [--latest]`
-
-Approve a pending device pairing request by exact `requestId`. If `requestId`
-is omitted or `--latest` is passed, FengMing only prints the selected pending
-request and exits; rerun approval with the exact request ID after verifying
-the details.
-
-<Note>
-If a device retries pairing with changed auth details (role, scopes, or public key), FengMing supersedes the previous pending entry and issues a new `requestId`. Run `fengming devices list` right before approval to use the current ID.
-</Note>
-
-If the device is already paired and asks for broader scopes or a broader role,
-FengMing keeps the existing approval in place and creates a new pending upgrade
-request. Review the `Requested` vs `Approved` columns in `fengming devices list`
-or use `fengming devices approve --latest` to preview the exact upgrade before
-approving it.
-
-If the Gateway is explicitly configured with
-`gateway.nodes.pairing.autoApproveCidrs`, first-time `role: node` requests from
-matching client IPs can be approved before they appear in this list. That policy
-is disabled by default and never applies to operator/browser clients or upgrade
-requests.
-
-Approving node or other non-operator device roles requires `operator.admin`.
-`operator.pairing` is enough for operator-device approvals only when the
-requested operator scopes stay within the caller's own scopes. See
-[Operator scopes](/gateway/operator-scopes) for the approval-time checks.
-
-```
-fengming devices approve
-fengming devices approve <requestId>
-fengming devices approve --latest
-```
-
-## Paperclip / `fengming_gateway` first-run approval
-
-When a new Paperclip agent connects through the `fengming_gateway` adapter for the first time, the Gateway may require a one-time device pairing approval before runs can succeed. If Paperclip reports `fengming_gateway_pairing_required`, approve the pending device and retry.
-
-For local gateways, preview the latest pending request:
-
-```bash
-fengming devices approve --latest
-```
-
-The preview prints the exact `fengming devices approve <requestId>` command. Verify the request details, then rerun that command with the request ID to approve it.
-
-For remote gateways or explicit credentials, pass the same options while previewing and approving:
-
-```bash
-fengming devices approve --latest --url <gateway-ws-url> --token <gateway-token>
-```
-
-To avoid re-approving after restarts, keep a persistent device key in the Paperclip adapter config instead of generating a new ephemeral identity each run:
-
-```json
-{
-  "adapterConfig": {
-    "devicePrivateKeyPem": "<ed25519-private-key-pkcs8-pem>"
-  }
-}
-```
-
-If approval keeps failing, run `fengming devices list` first to confirm a pending request exists.
-
-### `fengming devices reject <requestId>`
-
-Reject a pending device pairing request.
-
-```
-fengming devices reject <requestId>
-```
-
-### `fengming devices rotate --device <id> --role <role> [--scope <scope...>]`
-
-Rotate a device token for a specific role (optionally updating scopes).
-The target role must already exist in that device's approved pairing contract;
-rotation cannot mint a new unapproved role.
-If you omit `--scope`, later reconnects with the stored rotated token reuse that
-token's cached approved scopes. If you pass explicit `--scope` values, those
-become the stored scope set for future cached-token reconnects.
-Non-admin paired-device callers can rotate only their **own** device token.
-The target token scope set must stay within the caller session's own operator
-scopes; rotation cannot mint or preserve a broader operator token than the
-caller already has.
-
-```
-fengming devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
-```
-
-Returns rotation metadata as JSON. If the caller is rotating its own token while
-authenticated with that device token, the response also includes the replacement
-token so the client can persist it before reconnecting. Shared/admin rotations
-do not echo the bearer token.
-
-### `fengming devices revoke --device <id> --role <role>`
-
-Revoke a device token for a specific role.
-
-Non-admin paired-device callers can revoke only their **own** device token.
-Revoking some other device's token requires `operator.admin`.
-The target token scope set must also fit within the caller session's own
-operator scopes; pairing-only callers cannot revoke admin/write operator tokens.
-
-```
-fengming devices revoke --device <deviceId> --role node
-```
-
-Returns the revoke result as JSON.
-
-## Common options
-
-- `--url <url>`: Gateway WebSocket URL (defaults to `gateway.remote.url` when configured).
-- `--token <token>`: Gateway token (if required).
-- `--password <password>`: Gateway password (password auth).
-- `--timeout <ms>`: RPC timeout.
-- `--json`: JSON output (recommended for scripting).
-
-<Warning>
-When you set `--url`, the CLI does not fall back to config or environment credentials. Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
-</Warning>
-
-## Notes
-
-- Token rotation returns a new token (sensitive). Treat it like a secret.
-- These commands require `operator.pairing` (or `operator.admin`) scope. Some
-  approvals also require the caller to hold the operator scopes that the target
-  device would mint or inherit. Non-operator device roles require
-  `operator.admin`; see [Operator scopes](/gateway/operator-scopes).
-- `gateway.nodes.pairing.autoApproveCidrs` is an opt-in Gateway policy for
-  fresh node device pairing only; it does not change CLI approval authority.
-- Token rotation and revocation stay inside the approved pairing role set and
-  approved scope baseline for that device. A stray cached token entry does not
-  grant a token-management target.
-- For paired-device token sessions, cross-device management is admin-only:
-  `remove`, `rotate`, and `revoke` are self-only unless the caller has
-  `operator.admin`.
-- Token mutation is also caller-scope contained: a pairing-only session cannot
-  rotate or revoke a token that currently carries `operator.admin` or
-  `operator.write`.
-- `devices clear` is intentionally gated by `--yes`.
-- If pairing scope is unavailable on local loopback (and no explicit `--url` is passed), list/approve can use a local pairing fallback.
-- `devices approve` requires an explicit request ID before minting tokens; omitting `requestId` or passing `--latest` only previews the newest pending request.
-
-## Token drift recovery checklist
-
-Use this when Control UI or other clients keep failing with `AUTH_TOKEN_MISMATCH`, `AUTH_DEVICE_TOKEN_MISMATCH`, or `AUTH_SCOPE_MISMATCH`.
-
-1. Confirm current gateway token source:
-
-```bash
-fengming config get gateway.auth.token
-```
-
-2. List paired devices and identify the affected device id:
-
-```bash
-fengming devices list
-```
-
-3. Rotate operator token for the affected device:
-
-```bash
-fengming devices rotate --device <deviceId> --role operator
-```
-
-4. If rotation is not enough, remove stale pairing and approve again:
-
-```bash
-fengming devices remove <deviceId>
-fengming devices list
-fengming devices approve <requestId>
-```
-
-5. Retry client connection with the current shared token/password.
-
-Notes:
-
-- Normal reconnect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token.
-- Trusted `AUTH_TOKEN_MISMATCH` recovery can temporarily send both the shared token and the stored device token together for the one bounded retry.
-- `AUTH_SCOPE_MISMATCH` means the device token was recognized but does not carry the requested scope set; fix the pairing/scope approval contract before changing shared gateway auth.
-
-Related:
-
-- [Dashboard auth troubleshooting](/web/dashboard#if-you-see-unauthorized-1008)
-- [Gateway troubleshooting](/gateway/troubleshooting#dashboard-control-ui-connectivity)
-
-## Related
-
-- [CLI reference](/cli)
-- [Nodes](/nodes)

package/docs/cli/directory.md

@@ -1,68 +0,0 @@
----
-summary: "CLI reference for `fengming directory` (self, peers, groups)"
-read_when:
-  - You want to look up contacts/groups/self ids for a channel
-  - You are developing a channel directory adapter
-title: "Directory"
----
-
-# `fengming directory`
-
-Directory lookups for channels that support it (contacts/peers, groups, and "me").
-
-## Common flags
-
-- `--channel <name>`: channel id/alias (required when multiple channels are configured; auto when only one is configured)
-- `--account <id>`: account id (default: channel default)
-- `--json`: output JSON
-
-## Notes
-
-- `directory` is meant to help you find IDs you can paste into other commands (especially `fengming message send --target ...`).
-- For many channels, results are config-backed (allowlists / configured groups) rather than a live provider directory.
-- Installed channel plugins can still omit directory support; in that case the command reports the unsupported directory operation instead of reinstalling the plugin.
-- Default output is `id` (and sometimes `name`) separated by a tab; use `--json` for scripting.
-
-## Using results with `message send`
-
-```bash
-fengming directory peers list --channel slack --query "U0"
-fengming message send --channel slack --target user:U012ABCDEF --message "hello"
-```
-
-## ID formats (by channel)
-
-- WhatsApp: `+15551234567` (DM), `1234567890-1234567890@g.us` (group), `120363123456789@newsletter` (Channel/Newsletter outbound target)
-- Telegram: `@username` or numeric chat id; groups are numeric ids
-- Slack: `user:U…` and `channel:C…`
-- Discord: `user:<id>` and `channel:<id>`
-- Matrix (plugin): `user:@user:server`, `room:!roomId:server`, or `#alias:server`
-- Microsoft Teams (plugin): `user:<id>` and `conversation:<id>`
-- Zalo (plugin): user id (Bot API)
-- Zalo Personal / `zalouser` (plugin): thread id (DM/group) from `zca` (`me`, `friend list`, `group list`)
-
-## Self ("me")
-
-```bash
-fengming directory self --channel zalouser
-```
-
-## Peers (contacts/users)
-
-```bash
-fengming directory peers list --channel zalouser
-fengming directory peers list --channel zalouser --query "name"
-fengming directory peers list --channel zalouser --limit 50
-```
-
-## Groups
-
-```bash
-fengming directory groups list --channel zalouser
-fengming directory groups list --channel zalouser --query "work"
-fengming directory groups members --channel zalouser --group-id <id>
-```
-
-## Related
-
-- [CLI reference](/cli)

package/docs/cli/dns.md

@@ -1,53 +0,0 @@
----
-summary: "CLI reference for `fengming dns` (wide-area discovery helpers)"
-read_when:
-  - You want wide-area discovery (DNS-SD) via Tailscale + CoreDNS
-  - You're setting up split DNS for a custom discovery domain (example: fengming.internal)
-title: "DNS"
----
-
-# `fengming dns`
-
-DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS.
-
-Related:
-
-- Gateway discovery: [Discovery](/gateway/discovery)
-- Wide-area discovery config: [Configuration](/gateway/configuration)
-
-## Setup
-
-```bash
-fengming dns setup
-fengming dns setup --domain fengming.internal
-fengming dns setup --apply
-```
-
-## `dns setup`
-
-Plan or apply CoreDNS setup for unicast DNS-SD discovery.
-
-Options:
-
-- `--domain <domain>`: wide-area discovery domain (for example `fengming.internal`)
-- `--apply`: install or update CoreDNS config and restart the service (requires sudo; macOS only)
-
-What it shows:
-
-- resolved discovery domain
-- zone file path
-- current tailnet IPs
-- recommended `fengming.json` discovery config
-- the Tailscale Split DNS nameserver/domain values to set
-
-Notes:
-
-- Without `--apply`, the command is a planning helper only and prints the recommended setup.
-- If `--domain` is omitted, FengMing uses `discovery.wideArea.domain` from config.
-- `--apply` currently supports macOS only and expects Homebrew CoreDNS.
-- `--apply` bootstraps the zone file if needed, ensures the CoreDNS import stanza exists, and restarts the `coredns` brew service.
-
-## Related
-
-- [CLI reference](/cli)
-- [Discovery](/gateway/discovery)

package/docs/cli/docs.md

@@ -1,63 +0,0 @@
----
-summary: "CLI reference for `fengming docs` (search the live docs index)"
-read_when:
-  - You want to search the live FengMing docs from the terminal
-  - You need to know which hosted search API the docs CLI calls
-title: "Docs"
----
-
-# `fengming docs`
-
-Search the live FengMing docs index from the terminal. The command calls FengMing's Cloudflare-hosted docs search API and renders the results in your terminal.
-
-## Usage
-
-```bash
-fengming docs                       # print docs entrypoint and example search
-fengming docs <query...>            # search the live docs index
-```
-
-Arguments:
-
-| Argument     | Description                                                                        |
-| ------------ | ---------------------------------------------------------------------------------- |
-| `[query...]` | Free-form search query. Multi-word queries are joined with spaces and sent as one. |
-
-## Examples
-
-```bash
-fengming docs browser existing-session
-fengming docs sandbox allowHostControl
-fengming docs gateway token secretref
-```
-
-With no query, `fengming docs` prints the docs entrypoint URL plus a sample search command instead of running a search.
-
-## How it works
-
-`fengming docs` calls `https://docs.fengming.ai/api/search` and renders the JSON results. The search call uses a fixed 30 second timeout.
-
-## Output
-
-In a rich (TTY) terminal, results render as a heading followed by a bullet list. Each bullet shows the page title, the linked docs URL, and a short snippet on the next line. Empty results print "No results.".
-
-In non-rich output (piped, `--no-color`, scripts), the same data renders as Markdown:
-
-```markdown
-# Docs search: <query>
-
-- [Title](https://docs.fengming.ai/...) - snippet
-- [Title](https://docs.fengming.ai/...) - snippet
-```
-
-## Exit codes
-
-| Code | Meaning                                                           |
-| ---- | ----------------------------------------------------------------- |
-| `0`  | Search succeeded (including zero-result responses).               |
-| `1`  | The hosted docs search API call failed; stderr is printed inline. |
-
-## Related
-
-- [CLI reference](/cli)
-- [Live docs](https://docs.fengming.ai)