fengming 0.3.9 → 0.3.11

package/docs/cli/proxy.md

@@ -1,89 +0,0 @@
----
-summary: "CLI reference for `fengming proxy`, including operator-managed proxy validation and the local debug proxy capture inspector"
-read_when:
-  - You need to validate operator-managed proxy routing before deployment
-  - You need to capture FengMing transport traffic locally for debugging
-  - You want to inspect debug proxy sessions, blobs, or built-in query presets
-title: "Proxy"
----
-
-# `fengming proxy`
-
-Validate operator-managed proxy routing, or run the local explicit debug proxy
-and inspect captured traffic.
-
-Use `validate` to preflight an operator-managed forward proxy before enabling
-FengMing proxy routing. The other commands are debugging tools for
-transport-level investigation: they can start a local proxy, run a child command
-with capture enabled, list capture sessions, query common traffic patterns, read
-captured blobs, and purge local capture data.
-
-## Commands
-
-```bash
-fengming proxy start [--host <host>] [--port <port>]
-fengming proxy run [--host <host>] [--port <port>] -- <cmd...>
-fengming proxy validate [--json] [--proxy-url <url>] [--proxy-ca-file <path>] [--allowed-url <url>] [--denied-url <url>] [--apns-reachable] [--apns-authority <url>] [--timeout-ms <ms>]
-fengming proxy coverage
-fengming proxy sessions [--limit <count>]
-fengming proxy query --preset <name> [--session <id>]
-fengming proxy blob --id <blobId>
-fengming proxy purge
-```
-
-## Validate
-
-`fengming proxy validate` checks the effective operator-managed proxy URL from
-`--proxy-url`, config, or `FENGMING_PROXY_URL`. Managed proxy URLs can use
-`http://` for a plain forward-proxy listener or `https://` when FengMing must
-open TLS to the proxy endpoint before sending proxy requests. It reports a
-config problem when no proxy is enabled and configured; use `--proxy-url` for a
-one-off preflight before changing config. Add `--proxy-ca-file` to trust a
-private CA for the TLS connection to an HTTPS proxy endpoint. By default it
-verifies that a public destination succeeds through the proxy and that the proxy
-cannot reach a temporary loopback canary. Custom denied destinations are
-fail-closed: HTTP responses and ambiguous transport failures both fail unless
-you can verify a deployment-specific denial signal separately. Add
-`--apns-reachable` to also open an APNs HTTP/2 CONNECT tunnel through the proxy
-and confirm sandbox APNs responds; the probe uses an intentionally invalid
-provider token, so an APNs `403 InvalidProviderToken` response is a successful
-reachability signal.
-
-Options:
-
-- `--json`: print machine-readable JSON.
-- `--proxy-url <url>`: validate this `http://` or `https://` proxy URL instead of config or env.
-- `--proxy-ca-file <path>`: trust this PEM CA file for TLS verification of an HTTPS proxy endpoint.
-- `--allowed-url <url>`: add a destination expected to succeed through the proxy. Repeat to check multiple destinations.
-- `--denied-url <url>`: add a destination expected to be blocked by the proxy. Repeat to check multiple destinations.
-- `--apns-reachable`: also verify sandbox APNs HTTP/2 is reachable through the proxy.
-- `--apns-authority <url>`: APNs authority to probe with `--apns-reachable` (`https://api.sandbox.push.apple.com` by default; production is `https://api.push.apple.com`).
-- `--timeout-ms <ms>`: per-request timeout in milliseconds.
-
-See [Network Proxy](/security/network-proxy) for deployment guidance and denial
-semantics.
-
-## Query presets
-
-`fengming proxy query --preset <name>` accepts:
-
-- `double-sends`
-- `retry-storms`
-- `cache-busting`
-- `ws-duplicate-frames`
-- `missing-ack`
-- `error-bursts`
-
-## Notes
-
-- `start` defaults to `127.0.0.1` unless `--host` is set.
-- `run` starts a local debug proxy and then runs the command after `--`.
-- The debug proxy's direct upstream forwarding opens upstream sockets for diagnostics. When FengMing managed proxy mode is active, direct forwarding for proxy requests and CONNECT tunnels is disabled by default; set `FENGMING_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` only for approved local diagnostics.
-- `validate` exits with code 1 when proxy config or destination checks fail.
-- Captures are local debugging data; use `fengming proxy purge` when finished.
-
-## Related
-
-- [CLI reference](/cli)
-- [Network Proxy](/security/network-proxy)
-- [Trusted proxy auth](/gateway/trusted-proxy-auth)

package/docs/cli/qr.md

@@ -1,56 +0,0 @@
----
-summary: "CLI reference for `fengming qr` (generate mobile pairing QR + setup code)"
-read_when:
-  - You want to pair a mobile node app with a gateway quickly
-  - You need setup-code output for remote/manual sharing
-title: "QR"
----
-
-# `fengming qr`
-
-Generate a mobile pairing QR and setup code from your current Gateway configuration.
-
-## Usage
-
-```bash
-fengming qr
-fengming qr --setup-code-only
-fengming qr --json
-fengming qr --remote
-fengming qr --url wss://gateway.example/ws
-```
-
-## Options
-
-- `--remote`: prefer `gateway.remote.url`; if it is unset, `gateway.tailscale.mode=serve|funnel` can still provide the remote public URL
-- `--url <url>`: override gateway URL used in payload
-- `--public-url <url>`: override public URL used in payload
-- `--token <token>`: override which gateway token the bootstrap flow authenticates against
-- `--password <password>`: override which gateway password the bootstrap flow authenticates against
-- `--setup-code-only`: print only setup code
-- `--no-ascii`: skip ASCII QR rendering
-- `--json`: emit JSON (`setupCode`, `gatewayUrl`, `auth`, `urlSource`)
-
-## Notes
-
-- `--token` and `--password` are mutually exclusive.
-- The setup code itself now carries an opaque short-lived `bootstrapToken`, not the shared gateway token/password.
-- Built-in setup-code bootstrap returns a primary `node` token with `scopes: []` plus a bounded `operator` handoff token for trusted mobile onboarding.
-- The handed-off operator token is limited to `operator.approvals`, `operator.read`, `operator.talk.secrets`, and `operator.write`; `operator.admin` and `operator.pairing` require a separate approved operator pairing or token flow.
-- Mobile pairing fails closed for Tailscale/public `ws://` gateway URLs. Private LAN addresses and `.local` Bonjour hosts remain supported over `ws://`, but Tailscale/public mobile routes should use Tailscale Serve/Funnel or a `wss://` gateway URL.
-- With `--remote`, FengMing requires either `gateway.remote.url` or
-  `gateway.tailscale.mode=serve|funnel`.
-- With `--remote`, if effectively active remote credentials are configured as SecretRefs and you do not pass `--token` or `--password`, the command resolves them from the active gateway snapshot. If gateway is unavailable, the command fails fast.
-- Without `--remote`, local gateway auth SecretRefs are resolved when no CLI auth override is passed:
-  - `gateway.auth.token` resolves when token auth can win (explicit `gateway.auth.mode="token"` or inferred mode where no password source wins).
-  - `gateway.auth.password` resolves when password auth can win (explicit `gateway.auth.mode="password"` or inferred mode with no winning token from auth/env).
-- If both `gateway.auth.token` and `gateway.auth.password` are configured (including SecretRefs) and `gateway.auth.mode` is unset, setup-code resolution fails until mode is set explicitly.
-- Gateway version skew note: this command path requires a gateway that supports `secrets.resolve`; older gateways return an unknown-method error.
-- After scanning, approve device pairing with:
-  - `fengming devices list`
-  - `fengming devices approve <requestId>`
-
-## Related
-
-- [CLI reference](/cli)
-- [Pairing](/cli/pairing)

package/docs/cli/reset.md

@@ -1,39 +0,0 @@
----
-summary: "CLI reference for `fengming reset` (reset local state/config)"
-read_when:
-  - You want to wipe local state while keeping the CLI installed
-  - You want a dry-run of what would be removed
-title: "Reset"
----
-
-# `fengming reset`
-
-Reset local config/state (keeps the CLI installed).
-
-Options:
-
-- `--scope <scope>`: `config`, `config+creds+sessions`, or `full`
-- `--yes`: skip confirmation prompts
-- `--non-interactive`: disable prompts; requires `--scope` and `--yes`
-- `--dry-run`: print actions without removing files
-
-Examples:
-
-```bash
-fengming backup create
-fengming reset
-fengming reset --dry-run
-fengming reset --scope config --yes --non-interactive
-fengming reset --scope config+creds+sessions --yes --non-interactive
-fengming reset --scope full --yes --non-interactive
-```
-
-Notes:
-
-- Run `fengming backup create` first if you want a restorable snapshot before removing local state.
-- If you omit `--scope`, `fengming reset` uses an interactive prompt to choose what to remove.
-- `--non-interactive` is only valid when both `--scope` and `--yes` are set.
-
-## Related
-
-- [CLI reference](/cli)

package/docs/cli/sandbox.md

@@ -1,208 +0,0 @@
----
-summary: "Manage sandbox runtimes and inspect effective sandbox policy"
-title: Sandbox CLI
-read_when: "You are managing sandbox runtimes or debugging sandbox/tool-policy behavior."
-status: active
----
-
-Manage sandbox runtimes for isolated agent execution.
-
-## Overview
-
-FengMing can run agents in isolated sandbox runtimes for security. The `sandbox` commands help you inspect and recreate those runtimes after updates or configuration changes.
-
-Today that usually means:
-
-- Docker sandbox containers
-- SSH sandbox runtimes when `agents.defaults.sandbox.backend = "ssh"`
-- OpenShell sandbox runtimes when `agents.defaults.sandbox.backend = "openshell"`
-
-For `ssh` and OpenShell `remote`, recreate matters more than with Docker:
-
-- the remote workspace is canonical after the initial seed
-- `fengming sandbox recreate` deletes that canonical remote workspace for the selected scope
-- next use seeds it again from the current local workspace
-
-## Commands
-
-### `fengming sandbox explain`
-
-Inspect the **effective** sandbox mode/scope/workspace access, sandbox tool policy, and elevated gates (with fix-it config key paths).
-
-```bash
-fengming sandbox explain
-fengming sandbox explain --session agent:main:main
-fengming sandbox explain --agent work
-fengming sandbox explain --json
-```
-
-### `fengming sandbox list`
-
-List all sandbox runtimes with their status and configuration.
-
-```bash
-fengming sandbox list
-fengming sandbox list --browser  # List only browser containers
-fengming sandbox list --json     # JSON output
-```
-
-**Output includes:**
-
-- Runtime name and status
-- Backend (`docker`, `openshell`, etc.)
-- Config label and whether it matches current config
-- Age (time since creation)
-- Idle time (time since last use)
-- Associated session/agent
-
-### `fengming sandbox recreate`
-
-Remove sandbox runtimes to force recreation with updated config.
-
-```bash
-fengming sandbox recreate --all                # Recreate all containers
-fengming sandbox recreate --session main       # Specific session
-fengming sandbox recreate --agent mybot        # Specific agent
-fengming sandbox recreate --browser            # Only browser containers
-fengming sandbox recreate --all --force        # Skip confirmation
-```
-
-**Options:**
-
-- `--all`: Recreate all sandbox containers
-- `--session <key>`: Recreate container for specific session
-- `--agent <id>`: Recreate containers for specific agent
-- `--browser`: Only recreate browser containers
-- `--force`: Skip confirmation prompt
-
-<Note>
-Runtimes are automatically recreated when the agent is next used.
-</Note>
-
-## Use cases
-
-### After updating a Docker image
-
-```bash
-# Pull new image
-docker pull fengming-sandbox:latest
-docker tag fengming-sandbox:latest fengming-sandbox:bookworm-slim
-
-# Update config to use new image
-# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)
-
-# Recreate containers
-fengming sandbox recreate --all
-```
-
-### After changing sandbox configuration
-
-```bash
-# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)
-
-# Recreate to apply new config
-fengming sandbox recreate --all
-```
-
-### After changing SSH target or SSH auth material
-
-```bash
-# Edit config:
-# - agents.defaults.sandbox.backend
-# - agents.defaults.sandbox.ssh.target
-# - agents.defaults.sandbox.ssh.workspaceRoot
-# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile
-# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData
-
-fengming sandbox recreate --all
-```
-
-For the core `ssh` backend, recreate deletes the per-scope remote workspace root
-on the SSH target. The next run seeds it again from the local workspace.
-
-### After changing OpenShell source, policy, or mode
-
-```bash
-# Edit config:
-# - agents.defaults.sandbox.backend
-# - plugins.entries.openshell.config.from
-# - plugins.entries.openshell.config.mode
-# - plugins.entries.openshell.config.policy
-
-fengming sandbox recreate --all
-```
-
-For OpenShell `remote` mode, recreate deletes the canonical remote workspace
-for that scope. The next run seeds it again from the local workspace.
-
-### After changing setupCommand
-
-```bash
-fengming sandbox recreate --all
-# or just one agent:
-fengming sandbox recreate --agent family
-```
-
-### For a specific agent only
-
-```bash
-# Update only one agent's containers
-fengming sandbox recreate --agent alfred
-```
-
-## Why this is needed
-
-When you update sandbox configuration:
-
-- Existing runtimes continue running with old settings.
-- Runtimes are only pruned after 24h of inactivity.
-- Regularly-used agents keep old runtimes alive indefinitely.
-
-Use `fengming sandbox recreate` to force removal of old runtimes. They are recreated automatically with current settings when next needed.
-
-<Tip>
-Prefer `fengming sandbox recreate` over manual backend-specific cleanup. It uses the Gateway's runtime registry and avoids mismatches when scope or session keys change.
-</Tip>
-
-## Registry migration
-
-FengMing stores sandbox runtime metadata as one JSON shard per container/browser entry under the sandbox state directory. Older installs may still have monolithic legacy files:
-
-- `~/.fengming/sandbox/containers.json`
-- `~/.fengming/sandbox/browsers.json`
-
-Regular sandbox runtime reads do not rewrite those files. Run `fengming doctor --fix` to migrate valid legacy entries into the sharded registry directories. Invalid legacy files are quarantined so one bad old registry cannot hide current runtime entries.
-
-## Configuration
-
-Sandbox settings live in `~/.fengming/fengming.json` under `agents.defaults.sandbox` (per-agent overrides go in `agents.list[].sandbox`):
-
-```jsonc
-{
-  "agents": {
-    "defaults": {
-      "sandbox": {
-        "mode": "all", // off, non-main, all
-        "backend": "docker", // docker, ssh, openshell
-        "scope": "agent", // session, agent, shared
-        "docker": {
-          "image": "fengming-sandbox:bookworm-slim",
-          "containerPrefix": "fengming-sbx-",
-          // ... more Docker options
-        },
-        "prune": {
-          "idleHours": 24, // Auto-prune after 24h idle
-          "maxAgeDays": 7, // Auto-prune after 7 days
-        },
-      },
-    },
-  },
-}
-```
-
-## Related
-
-- [CLI reference](/cli)
-- [Sandboxing](/gateway/sandboxing)
-- [Agent workspace](/concepts/agent-workspace)
-- [Doctor](/gateway/doctor): checks sandbox setup.

package/docs/cli/secrets.md

@@ -1,202 +0,0 @@
----
-summary: "CLI reference for `fengming secrets` (reload, audit, configure, apply)"
-read_when:
-  - Re-resolving secret refs at runtime
-  - Auditing plaintext residues and unresolved refs
-  - Configuring SecretRefs and applying one-way scrub changes
-title: "Secrets"
----
-
-# `fengming secrets`
-
-Use `fengming secrets` to manage SecretRefs and keep the active runtime snapshot healthy.
-
-Command roles:
-
-- `reload`: gateway RPC (`secrets.reload`) that re-resolves refs and swaps runtime snapshot only on full success (no config writes).
-- `audit`: read-only scan of configuration/auth/generated-model stores and legacy residues for plaintext, unresolved refs, and precedence drift (exec refs are skipped unless `--allow-exec` is set).
-- `configure`: interactive planner for provider setup, target mapping, and preflight (TTY required).
-- `apply`: execute a saved plan (`--dry-run` for validation only; dry-run skips exec checks by default, and write mode rejects exec-containing plans unless `--allow-exec` is set), then scrub targeted plaintext residues.
-
-Recommended operator loop:
-
-```bash
-fengming secrets audit --check
-fengming secrets configure
-fengming secrets apply --from /tmp/fengming-secrets-plan.json --dry-run
-fengming secrets apply --from /tmp/fengming-secrets-plan.json
-fengming secrets audit --check
-fengming secrets reload
-```
-
-If your plan includes `exec` SecretRefs/providers, pass `--allow-exec` on both dry-run and write apply commands.
-
-Exit code note for CI/gates:
-
-- `audit --check` returns `1` on findings.
-- unresolved refs return `2`.
-
-Related:
-
-- Secrets guide: [Secrets Management](/gateway/secrets)
-- Credential surface: [SecretRef Credential Surface](/reference/secretref-credential-surface)
-- Security guide: [Security](/gateway/security)
-
-## Reload runtime snapshot
-
-Re-resolve secret refs and atomically swap runtime snapshot.
-
-```bash
-fengming secrets reload
-fengming secrets reload --json
-fengming secrets reload --url ws://127.0.0.1:18789 --token <token>
-```
-
-Notes:
-
-- Uses gateway RPC method `secrets.reload`.
-- If resolution fails, gateway keeps last-known-good snapshot and returns an error (no partial activation).
-- JSON response includes `warningCount`.
-
-Options:
-
-- `--url <url>`
-- `--token <token>`
-- `--timeout <ms>`
-- `--json`
-
-## Audit
-
-Scan FengMing state for:
-
-- plaintext secret storage
-- unresolved refs
-- precedence drift (`auth-profiles.json` credentials shadowing `fengming.json` refs)
-- generated `agents/*/agent/models.json` residues (provider `apiKey` values and sensitive provider headers)
-- legacy residues (legacy auth store entries, OAuth reminders)
-
-Header residue note:
-
-- Sensitive provider header detection is name-heuristic based (common auth/credential header names and fragments such as `authorization`, `x-api-key`, `token`, `secret`, `password`, and `credential`).
-
-```bash
-fengming secrets audit
-fengming secrets audit --check
-fengming secrets audit --json
-fengming secrets audit --allow-exec
-```
-
-Exit behavior:
-
-- `--check` exits non-zero on findings.
-- unresolved refs exit with higher-priority non-zero code.
-
-Report shape highlights:
-
-- `status`: `clean | findings | unresolved`
-- `resolution`: `refsChecked`, `skippedExecRefs`, `resolvabilityComplete`
-- `summary`: `plaintextCount`, `unresolvedRefCount`, `shadowedRefCount`, `legacyResidueCount`
-- finding codes:
-  - `PLAINTEXT_FOUND`
-  - `REF_UNRESOLVED`
-  - `REF_SHADOWED`
-  - `LEGACY_RESIDUE`
-
-## Configure (interactive helper)
-
-Build provider and SecretRef changes interactively, run preflight, and optionally apply:
-
-```bash
-fengming secrets configure
-fengming secrets configure --plan-out /tmp/fengming-secrets-plan.json
-fengming secrets configure --apply --yes
-fengming secrets configure --providers-only
-fengming secrets configure --skip-provider-setup
-fengming secrets configure --agent ops
-fengming secrets configure --json
-```
-
-Flow:
-
-- Provider setup first (`add/edit/remove` for `secrets.providers` aliases).
-- Credential mapping second (select fields and assign `{source, provider, id}` refs).
-- Preflight and optional apply last.
-
-Flags:
-
-- `--providers-only`: configure `secrets.providers` only, skip credential mapping.
-- `--skip-provider-setup`: skip provider setup and map credentials to existing providers.
-- `--agent <id>`: scope `auth-profiles.json` target discovery and writes to one agent store.
-- `--allow-exec`: allow exec SecretRef checks during preflight/apply (may execute provider commands).
-
-Notes:
-
-- Requires an interactive TTY.
-- You cannot combine `--providers-only` with `--skip-provider-setup`.
-- `configure` targets secret-bearing fields in `fengming.json` plus `auth-profiles.json` for the selected agent scope.
-- `configure` supports creating new `auth-profiles.json` mappings directly in the picker flow.
-- Canonical supported surface: [SecretRef Credential Surface](/reference/secretref-credential-surface).
-- It performs preflight resolution before apply.
-- If preflight/apply includes exec refs, keep `--allow-exec` set for both steps.
-- Generated plans default to scrub options (`scrubEnv`, `scrubAuthProfilesForProviderTargets`, `scrubLegacyAuthJson` all enabled).
-- Apply path is one-way for scrubbed plaintext values.
-- Without `--apply`, CLI still prompts `Apply this plan now?` after preflight.
-- With `--apply` (and no `--yes`), CLI prompts an extra irreversible confirmation.
-- `--json` prints the plan + preflight report, but the command still requires an interactive TTY.
-
-Exec provider safety note:
-
-- Homebrew installs often expose symlinked binaries under `/opt/homebrew/bin/*`.
-- Set `allowSymlinkCommand: true` only when needed for trusted package-manager paths, and pair it with `trustedDirs` (for example `["/opt/homebrew"]`).
-- On Windows, if ACL verification is unavailable for a provider path, FengMing fails closed. For trusted paths only, set `allowInsecurePath: true` on that provider to bypass path security checks.
-
-## Apply a saved plan
-
-Apply or preflight a plan generated previously:
-
-```bash
-fengming secrets apply --from /tmp/fengming-secrets-plan.json
-fengming secrets apply --from /tmp/fengming-secrets-plan.json --allow-exec
-fengming secrets apply --from /tmp/fengming-secrets-plan.json --dry-run
-fengming secrets apply --from /tmp/fengming-secrets-plan.json --dry-run --allow-exec
-fengming secrets apply --from /tmp/fengming-secrets-plan.json --json
-```
-
-Exec behavior:
-
-- `--dry-run` validates preflight without writing files.
-- exec SecretRef checks are skipped by default in dry-run.
-- write mode rejects plans that contain exec SecretRefs/providers unless `--allow-exec` is set.
-- Use `--allow-exec` to opt in to exec provider checks/execution in either mode.
-
-Plan contract details (allowed target paths, validation rules, and failure semantics):
-
-- [Secrets Apply Plan Contract](/gateway/secrets-plan-contract)
-
-What `apply` may update:
-
-- `fengming.json` (SecretRef targets + provider upserts/deletes)
-- `auth-profiles.json` (provider-target scrubbing)
-- legacy `auth.json` residues
-- `~/.fengming/.env` known secret keys whose values were migrated
-
-## Why no rollback backups
-
-`secrets apply` intentionally does not write rollback backups containing old plaintext values.
-
-Safety comes from strict preflight + atomic-ish apply with best-effort in-memory restore on failure.
-
-## Example
-
-```bash
-fengming secrets audit --check
-fengming secrets configure
-fengming secrets audit --check
-```
-
-If `audit --check` still reports plaintext findings, update the remaining reported target paths and rerun audit.
-
-## Related
-
-- [CLI reference](/cli)
-- [Secrets management](/gateway/secrets)