fengming 0.3.9 → 0.3.11

package/docs/gateway/secrets.md

@@ -1,805 +0,0 @@
----
-summary: "Secrets management: SecretRef contract, runtime snapshot behavior, and safe one-way scrubbing"
-read_when:
-  - Configuring SecretRefs for provider credentials and `auth-profiles.json` refs
-  - Operating secrets reload, audit, configure, and apply safely in production
-  - Understanding startup fail-fast, inactive-surface filtering, and last-known-good behavior
-title: "Secrets management"
-sidebarTitle: "Secrets management"
----
-
-FengMing supports additive SecretRefs so supported credentials do not need to be stored as plaintext in configuration.
-
-<Note>
-Plaintext still works. SecretRefs are opt-in per credential.
-</Note>
-
-<Warning>
-Plaintext credentials remain agent-readable if they are stored in files the
-agent can inspect, including `fengming.json`, `auth-profiles.json`, `.env`, or
-generated `agents/*/agent/models.json` files. SecretRefs reduce that local blast
-radius only after every supported credential has been migrated and
-`fengming secrets audit --check` reports no plaintext secret residue.
-</Warning>
-
-## Goals and runtime model
-
-Secrets are resolved into an in-memory runtime snapshot.
-
-- Resolution is eager during activation, not lazy on request paths.
-- Startup fails fast when an effectively active SecretRef cannot be resolved.
-- Reload uses atomic swap: full success, or keep the last-known-good snapshot.
-- SecretRef policy violations (for example OAuth-mode auth profiles combined with SecretRef input) fail activation before runtime swap.
-- Runtime requests read from the active in-memory snapshot only.
-- After the first successful config activation/load, runtime code paths keep reading that active in-memory snapshot until a successful reload swaps it.
-- Outbound delivery paths also read from that active snapshot (for example Discord reply/thread delivery and Telegram action sends); they do not re-resolve SecretRefs on each send.
-
-This keeps secret-provider outages off hot request paths.
-
-## Agent-access boundary
-
-SecretRefs protect credentials from being persisted in supported config and
-generated model surfaces, but they are not a process-isolation boundary. If a
-plaintext credential remains on disk in a path the agent can read, the agent can
-bypass API-level redaction by using file or shell tools to inspect that file.
-
-For production deployments where agent-accessible files are in scope, treat
-SecretRef migration as complete only when all of these are true:
-
-- supported credentials use SecretRefs instead of plaintext values
-- legacy plaintext residue has been scrubbed from `fengming.json`,
-  `auth-profiles.json`, `.env`, and generated `models.json` files
-- `fengming secrets audit --check` is clean after the migration
-- any remaining unsupported or rotating credentials are protected by operating
-  system isolation, container isolation, or an external credential proxy
-
-This is why the audit/configure/apply workflow is a security migration gate, not
-just a convenience helper.
-
-<Warning>
-SecretRefs do not make arbitrary readable files safe. Backups, copied configs,
-old generated model catalogs, and unsupported credential classes must be treated
-as production secrets until they are deleted, moved outside the agent trust
-boundary, or protected by a separate isolation layer.
-</Warning>
-
-## Active-surface filtering
-
-SecretRefs are validated only on effectively active surfaces.
-
-- Enabled surfaces: unresolved refs block startup/reload.
-- Inactive surfaces: unresolved refs do not block startup/reload.
-- Inactive refs emit non-fatal diagnostics with code `SECRETS_REF_IGNORED_INACTIVE_SURFACE`.
-
-<AccordionGroup>
-  <Accordion title="Examples of inactive surfaces">
-    - Disabled channel/account entries.
-    - Top-level channel credentials that no enabled account inherits.
-    - Disabled tool/feature surfaces.
-    - Web search provider-specific keys that are not selected by `tools.web.search.provider`. In auto mode (provider unset), keys are consulted by precedence for provider auto-detection until one resolves. After selection, non-selected provider keys are treated as inactive until selected.
-    - Sandbox SSH auth material (`agents.defaults.sandbox.ssh.identityData`, `certificateData`, `knownHostsData`, plus per-agent overrides) is active only when the effective sandbox backend is `ssh` for the default agent or an enabled agent.
-    - `gateway.remote.token` / `gateway.remote.password` SecretRefs are active if one of these is true:
-      - `gateway.mode=remote`
-      - `gateway.remote.url` is configured
-      - `gateway.tailscale.mode` is `serve` or `funnel`
-      - In local mode without those remote surfaces:
-        - `gateway.remote.token` is active when token auth can win and no env/auth token is configured.
-        - `gateway.remote.password` is active only when password auth can win and no env/auth password is configured.
-    - `gateway.auth.token` SecretRef is inactive for startup auth resolution when `FENGMING_GATEWAY_TOKEN` is set, because env token input wins for that runtime.
-
-  </Accordion>
-</AccordionGroup>
-
-## Gateway auth surface diagnostics
-
-When a SecretRef is configured on `gateway.auth.token`, `gateway.auth.password`, `gateway.remote.token`, or `gateway.remote.password`, gateway startup/reload logs the surface state explicitly:
-
-- `active`: the SecretRef is part of the effective auth surface and must resolve.
-- `inactive`: the SecretRef is ignored for this runtime because another auth surface wins, or because remote auth is disabled/not active.
-
-These entries are logged with `SECRETS_GATEWAY_AUTH_SURFACE` and include the reason used by the active-surface policy, so you can see why a credential was treated as active or inactive.
-
-## Onboarding reference preflight
-
-When onboarding runs in interactive mode and you choose SecretRef storage, FengMing runs preflight validation before saving:
-
-- Env refs: validates env var name and confirms a non-empty value is visible during setup.
-- Provider refs (`file` or `exec`): validates provider selection, resolves `id`, and checks resolved value type.
-- Quickstart reuse path: when `gateway.auth.token` is already a SecretRef, onboarding resolves it before probe/dashboard bootstrap (for `env`, `file`, and `exec` refs) using the same fail-fast gate.
-
-If validation fails, onboarding shows the error and lets you retry.
-
-## SecretRef contract
-
-Use one object shape everywhere:
-
-```json5
-{ source: "env" | "file" | "exec", provider: "default", id: "..." }
-```
-
-<Tabs>
-  <Tab title="env">
-    ```json5
-    { source: "env", provider: "default", id: "OPENAI_API_KEY" }
-    ```
-
-    Supported SecretInput fields also accept exact string shorthands:
-
-    ```json5
-    "${OPENAI_API_KEY}"
-    "$OPENAI_API_KEY"
-    ```
-
-    Validation:
-
-    - `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
-    - `id` must match `^[A-Z][A-Z0-9_]{0,127}$`
-
-  </Tab>
-  <Tab title="file">
-    ```json5
-    { source: "file", provider: "filemain", id: "/providers/openai/apiKey" }
-    ```
-
-    Validation:
-
-    - `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
-    - `id` must be an absolute JSON pointer (`/...`)
-    - RFC6901 escaping in segments: `~` => `~0`, `/` => `~1`
-
-  </Tab>
-  <Tab title="exec">
-    ```json5
-    { source: "exec", provider: "vault", id: "providers/openai/apiKey#value" }
-    ```
-
-    Validation:
-
-    - `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
-    - `id` must match `^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$` (supports selectors such as `secret#json_key`)
-    - `id` must not contain `.` or `..` as slash-delimited path segments (for example `a/../b` is rejected)
-
-  </Tab>
-</Tabs>
-
-## Provider config
-
-Define providers under `secrets.providers`:
-
-```json5
-{
-  secrets: {
-    providers: {
-      default: { source: "env" },
-      filemain: {
-        source: "file",
-        path: "~/.fengming/secrets.json",
-        mode: "json", // or "singleValue"
-      },
-      vault: {
-        source: "exec",
-        command: "/usr/local/bin/fengming-vault-resolver",
-        args: ["--profile", "prod"],
-        passEnv: ["PATH", "VAULT_ADDR"],
-        jsonOnly: true,
-      },
-      "team-secrets": {
-        source: "exec",
-        pluginIntegration: {
-          pluginId: "acme-secrets",
-          integrationId: "secret-store",
-        },
-      },
-    },
-    defaults: {
-      env: "default",
-      file: "filemain",
-      exec: "vault",
-    },
-    resolution: {
-      maxProviderConcurrency: 4,
-      maxRefsPerProvider: 512,
-      maxBatchBytes: 262144,
-    },
-  },
-}
-```
-
-<AccordionGroup>
-  <Accordion title="Env provider">
-    - Optional allowlist via `allowlist`.
-    - Missing/empty env values fail resolution.
-
-  </Accordion>
-  <Accordion title="File provider">
-    - Reads local file from `path`.
-    - `mode: "json"` expects JSON object payload and resolves `id` as pointer.
-    - `mode: "singleValue"` expects ref id `"value"` and returns file contents.
-    - Path must pass ownership/permission checks.
-    - Windows fail-closed note: if ACL verification is unavailable for a path, resolution fails. For trusted paths only, set `allowInsecurePath: true` on that provider to bypass path security checks.
-
-  </Accordion>
-  <Accordion title="Exec provider">
-    - Runs configured absolute binary path, no shell.
-    - By default, `command` must point to a regular file (not a symlink).
-    - Set `allowSymlinkCommand: true` to allow symlink command paths (for example Homebrew shims). FengMing validates the resolved target path.
-    - Pair `allowSymlinkCommand` with `trustedDirs` for package-manager paths (for example `["/opt/homebrew"]`).
-    - Supports timeout, no-output timeout, output byte limits, env allowlist, and trusted dirs.
-    - Windows fail-closed note: if ACL verification is unavailable for the command path, resolution fails. For trusted paths only, set `allowInsecurePath: true` on that provider to bypass path security checks.
-    - Plugin-managed exec providers can use `pluginIntegration` instead of
-      copied `command`/`args`. FengMing resolves the current command details
-      from the installed plugin manifest during startup/reload. If the plugin is
-      disabled, removed, untrusted, or no longer declares the integration,
-      active SecretRefs using that provider fail closed.
-
-    Request payload (stdin):
-
-    ```json
-    { "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }
-    ```
-
-    Response payload (stdout):
-
-    ```jsonc
-    { "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret
-    ```
-
-    Optional per-id errors:
-
-    ```json
-    {
-      "protocolVersion": 1,
-      "values": {},
-      "errors": { "providers/openai/apiKey": { "message": "not found" } }
-    }
-    ```
-
-  </Accordion>
-</AccordionGroup>
-
-## File-backed API keys
-
-Do not put `file:...` strings in the config `env` block. The `env` block is
-literal and non-overriding, so `file:...` is not resolved.
-
-Use a file SecretRef on a supported credential field instead:
-
-```json5
-{
-  secrets: {
-    providers: {
-      xai_key_file: {
-        source: "file",
-        path: "~/.fengming/secrets/xai-api-key.txt",
-        mode: "singleValue",
-      },
-    },
-  },
-  models: {
-    providers: {
-      xai: {
-        apiKey: { source: "file", provider: "xai_key_file", id: "value" },
-      },
-    },
-  },
-}
-```
-
-For `mode: "singleValue"`, the SecretRef `id` is `"value"`. For
-`mode: "json"`, use an absolute JSON pointer such as
-`"/providers/xai/apiKey"`.
-
-See [SecretRef credential surface](/reference/secretref-credential-surface) for
-the config fields that accept SecretRefs.
-
-## Exec integration examples
-
-<AccordionGroup>
-  <Accordion title="1Password CLI">
-    ```json5
-    {
-      secrets: {
-        providers: {
-          onepassword_openai: {
-            source: "exec",
-            command: "/opt/homebrew/bin/op",
-            allowSymlinkCommand: true, // required for Homebrew symlinked binaries
-            trustedDirs: ["/opt/homebrew"],
-            args: ["read", "op://Personal/FengMing QA API Key/password"],
-            passEnv: ["HOME"],
-            jsonOnly: false,
-          },
-        },
-      },
-      models: {
-        providers: {
-          openai: {
-            baseUrl: "https://api.openai.com/v1",
-            models: [{ id: "gpt-5", name: "gpt-5" }],
-            apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
-          },
-        },
-      },
-    }
-    ```
-  </Accordion>
-  <Accordion title="Bitwarden Secrets Manager (`bws`)">
-    Use a resolver wrapper when you want SecretRef ids to map to Bitwarden
-    Secrets Manager item keys. The repository includes
-    `scripts/secrets/fengming-bws-resolver.mjs`; install or copy it to an absolute
-    trusted path on the host that runs the Gateway.
-
-    Requirements:
-
-    - Bitwarden Secrets Manager CLI (`bws`) installed on the Gateway host.
-    - `BWS_ACCESS_TOKEN` available to the Gateway service.
-    - `PATH` passed to the resolver, or `BWS_BIN` set to the absolute `bws`
-      binary path.
-
-    ```json5
-    {
-      secrets: {
-        providers: {
-          bws: {
-            source: "exec",
-            command: "/usr/local/bin/fengming-bws-resolver.mjs",
-            passEnv: ["BWS_ACCESS_TOKEN", "PATH", "BWS_BIN"],
-            jsonOnly: true,
-          },
-        },
-      },
-      models: {
-        providers: {
-          openai: {
-            baseUrl: "https://api.openai.com/v1",
-            models: [{ id: "gpt-5", name: "gpt-5" }],
-            apiKey: {
-              source: "exec",
-              provider: "bws",
-              id: "fengming/providers/openai/apiKey",
-            },
-          },
-        },
-      },
-    }
-    ```
-
-    The resolver batches requested ids, runs `bws secret list`, and returns
-    values for matching secret `key` fields. Use keys that satisfy the exec
-    SecretRef id contract, such as `fengming/providers/openai/apiKey`; env-var
-    style keys with underscores are rejected before the resolver runs. If more
-    than one visible Bitwarden secret has the same requested key, the resolver
-    fails that id as ambiguous instead of choosing one. After updating config,
-    verify the resolver path:
-
-    ```bash
-    fengming secrets audit --allow-exec
-    ```
-
-  </Accordion>
-  <Accordion title="HashiCorp Vault CLI">
-    ```json5
-    {
-      secrets: {
-        providers: {
-          vault_openai: {
-            source: "exec",
-            command: "/opt/homebrew/bin/vault",
-            allowSymlinkCommand: true, // required for Homebrew symlinked binaries
-            trustedDirs: ["/opt/homebrew"],
-            args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/fengming"],
-            passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
-            jsonOnly: false,
-          },
-        },
-      },
-      models: {
-        providers: {
-          openai: {
-            baseUrl: "https://api.openai.com/v1",
-            models: [{ id: "gpt-5", name: "gpt-5" }],
-            apiKey: { source: "exec", provider: "vault_openai", id: "value" },
-          },
-        },
-      },
-    }
-    ```
-  </Accordion>
-  <Accordion title="password-store (`pass`)">
-    Use a small resolver wrapper when you want SecretRef ids to map directly to
-    `pass` entries. Save this as an executable in an absolute path that passes
-    your exec-provider path checks, for example
-    `/usr/local/bin/fengming-pass-resolver`. The `#!/usr/bin/env node` shebang
-    resolves `node` from the resolver process `PATH`, so include `PATH` in
-    `passEnv`. If `pass` is not on that `PATH`, set `PASS_BIN` in the parent
-    environment and include it in `passEnv` too:
-
-    ```js
-    #!/usr/bin/env node
-    const { spawnSync } = require("node:child_process");
-
-    let stdin = "";
-    process.stdin.setEncoding("utf8");
-    process.stdin.on("data", (chunk) => {
-      stdin += chunk;
-    });
-    process.stdin.on("error", (err) => {
-      process.stderr.write(`${err.message}\n`);
-      process.exit(1);
-    });
-    process.stdin.on("end", () => {
-      let request;
-      try {
-        request = JSON.parse(stdin || "{}");
-      } catch (err) {
-        process.stderr.write(`Failed to parse request: ${err.message}\n`);
-        process.exit(1);
-      }
-
-      const passBin = process.env.PASS_BIN || "pass";
-      const values = {};
-      const errors = {};
-
-      for (const id of request.ids ?? []) {
-        const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });
-        if (result.status === 0) {
-          values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";
-        } else {
-          errors[id] = { message: (result.stderr || `pass exited ${result.status}`).trim() };
-        }
-      }
-
-      process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));
-    });
-    ```
-
-    Then configure the exec provider and point `apiKey` at the `pass` entry path:
-
-    ```json5
-    {
-      secrets: {
-        providers: {
-          pass_store: {
-            source: "exec",
-            command: "/usr/local/bin/fengming-pass-resolver",
-            passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],
-            jsonOnly: true,
-          },
-        },
-      },
-      models: {
-        providers: {
-          openai: {
-            baseUrl: "https://api.openai.com/v1",
-            models: [{ id: "gpt-5", name: "gpt-5" }],
-            apiKey: {
-              source: "exec",
-              provider: "pass_store",
-              id: "fengming/providers/openai/apiKey",
-            },
-          },
-        },
-      },
-    }
-    ```
-
-    Keep the secret on the first line of the `pass` entry, or customize the
-    wrapper if you want to return the full `pass show` output instead. After
-    updating config, verify both the static audit and the exec resolver path:
-
-    ```bash
-    fengming secrets audit --check
-    fengming secrets audit --allow-exec
-    ```
-
-  </Accordion>
-  <Accordion title="sops">
-    ```json5
-    {
-      secrets: {
-        providers: {
-          sops_openai: {
-            source: "exec",
-            command: "/opt/homebrew/bin/sops",
-            allowSymlinkCommand: true, // required for Homebrew symlinked binaries
-            trustedDirs: ["/opt/homebrew"],
-            args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
-            passEnv: ["SOPS_AGE_KEY_FILE"],
-            jsonOnly: false,
-          },
-        },
-      },
-      models: {
-        providers: {
-          openai: {
-            baseUrl: "https://api.openai.com/v1",
-            models: [{ id: "gpt-5", name: "gpt-5" }],
-            apiKey: { source: "exec", provider: "sops_openai", id: "value" },
-          },
-        },
-      },
-    }
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## MCP server environment variables
-
-MCP server env vars configured via `plugins.entries.acpx.config.mcpServers` support SecretInput. This keeps API keys and tokens out of plaintext config:
-
-```json5
-{
-  plugins: {
-    entries: {
-      acpx: {
-        enabled: true,
-        config: {
-          mcpServers: {
-            github: {
-              command: "npx",
-              args: ["-y", "@modelcontextprotocol/server-github"],
-              env: {
-                GITHUB_PERSONAL_ACCESS_TOKEN: {
-                  source: "env",
-                  provider: "default",
-                  id: "MCP_GITHUB_PAT",
-                },
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-Plaintext string values still work. Env-template refs like `${MCP_SERVER_API_KEY}` and SecretRef objects are resolved during gateway activation before the MCP server process is spawned. As with other SecretRef surfaces, unresolved refs only block activation when the `acpx` plugin is effectively active.
-
-## Sandbox SSH auth material
-
-The core `ssh` sandbox backend also supports SecretRefs for SSH auth material:
-
-```json5
-{
-  agents: {
-    defaults: {
-      sandbox: {
-        mode: "all",
-        backend: "ssh",
-        ssh: {
-          target: "user@gateway-host:22",
-          identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
-          certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
-          knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
-        },
-      },
-    },
-  },
-}
-```
-
-Runtime behavior:
-
-- FengMing resolves these refs during sandbox activation, not lazily during each SSH call.
-- Resolved values are written to temp files with restrictive permissions and used in generated SSH config.
-- If the effective sandbox backend is not `ssh`, these refs stay inactive and do not block startup.
-
-## Supported credential surface
-
-Canonical supported and unsupported credentials are listed in:
-
-- [SecretRef Credential Surface](/reference/secretref-credential-surface)
-
-<Note>
-Runtime-minted or rotating credentials and OAuth refresh material are intentionally excluded from read-only SecretRef resolution.
-</Note>
-
-## Required behavior and precedence
-
-- Field without a ref: unchanged.
-- Field with a ref: required on active surfaces during activation.
-- If both plaintext and ref are present, ref takes precedence on supported precedence paths.
-- The redaction sentinel `__FENGMING_REDACTED__` is reserved for internal config redaction/restore and is rejected as literal submitted config data.
-
-Warning and audit signals:
-
-- `SECRETS_REF_OVERRIDES_PLAINTEXT` (runtime warning)
-- `REF_SHADOWED` (audit finding when `auth-profiles.json` credentials take precedence over `fengming.json` refs)
-
-Google Chat compatibility behavior:
-
-- `serviceAccountRef` takes precedence over plaintext `serviceAccount`.
-- Plaintext value is ignored when sibling ref is set.
-
-## Activation triggers
-
-Secret activation runs on:
-
-- Startup (preflight plus final activation)
-- Config reload hot-apply path
-- Config reload restart-check path
-- Manual reload via `secrets.reload`
-- Gateway config write RPC preflight (`config.set` / `config.apply` / `config.patch`) for active-surface SecretRef resolvability within the submitted config payload before persisting edits
-
-Activation contract:
-
-- Success swaps the snapshot atomically.
-- Startup failure aborts gateway startup.
-- Runtime reload failure keeps the last-known-good snapshot.
-- Write-RPC preflight failure rejects the submitted config and keeps both disk config and active runtime snapshot unchanged.
-- Providing an explicit per-call channel token to an outbound helper/tool call does not trigger SecretRef activation; activation points remain startup, reload, and explicit `secrets.reload`.
-
-## Degraded and recovered signals
-
-When reload-time activation fails after a healthy state, FengMing enters degraded secrets state.
-
-One-shot system event and log codes:
-
-- `SECRETS_RELOADER_DEGRADED`
-- `SECRETS_RELOADER_RECOVERED`
-
-Behavior:
-
-- Degraded: runtime keeps last-known-good snapshot.
-- Recovered: emitted once after the next successful activation.
-- Repeated failures while already degraded log warnings but do not spam events.
-- Startup fail-fast does not emit degraded events because runtime never became active.
-
-## Command-path resolution
-
-Command paths can opt into supported SecretRef resolution via gateway snapshot RPC.
-
-There are two broad behaviors:
-
-<Tabs>
-  <Tab title="Strict command paths">
-    For example `fengming memory` remote-memory paths and `fengming qr --remote` when it needs remote shared-secret refs. They read from the active snapshot and fail fast when a required SecretRef is unavailable.
-  </Tab>
-  <Tab title="Read-only command paths">
-    For example `fengming status`, `fengming status --all`, `fengming channels status`, `fengming channels resolve`, `fengming security audit`, and read-only doctor/config repair flows. They also prefer the active snapshot, but degrade instead of aborting when a targeted SecretRef is unavailable in that command path.
-
-    Read-only behavior:
-
-    - When the gateway is running, these commands read from the active snapshot first.
-    - If gateway resolution is incomplete or the gateway is unavailable, they attempt targeted local fallback for the specific command surface.
-    - If a targeted SecretRef is still unavailable, the command continues with degraded read-only output and explicit diagnostics such as "configured but unavailable in this command path".
-    - This degraded behavior is command-local only. It does not weaken runtime startup, reload, or send/auth paths.
-
-  </Tab>
-</Tabs>
-
-Other notes:
-
-- Snapshot refresh after backend secret rotation is handled by `fengming secrets reload`.
-- Gateway RPC method used by these command paths: `secrets.resolve`.
-
-## Audit and configure workflow
-
-Default operator flow:
-
-<Steps>
-  <Step title="Audit current state">
-    ```bash
-    fengming secrets audit --check
-    ```
-  </Step>
-  <Step title="Configure and apply SecretRefs">
-    ```bash
-    fengming secrets configure --apply
-    ```
-  </Step>
-  <Step title="Re-audit">
-    ```bash
-    fengming secrets audit --check
-    ```
-  </Step>
-</Steps>
-
-Do not treat the migration as complete until the re-audit is clean. If the audit
-still reports plaintext values at rest, the agent-access risk is still present
-even when runtime APIs return redacted values.
-
-If you save a plan instead of applying during `configure`, apply that saved plan
-with `fengming secrets apply --from <plan-path>` before the re-audit.
-
-<AccordionGroup>
-  <Accordion title="secrets audit">
-    Findings include:
-
-    - plaintext values at rest (`fengming.json`, `auth-profiles.json`, `.env`, and generated `agents/*/agent/models.json`)
-    - plaintext sensitive provider header residues in generated `models.json` entries
-    - unresolved refs
-    - precedence shadowing (`auth-profiles.json` taking priority over `fengming.json` refs)
-    - legacy residues (`auth.json`, OAuth reminders)
-
-    Exec note:
-
-    - By default, audit skips exec SecretRef resolvability checks to avoid command side effects.
-    - Use `fengming secrets audit --allow-exec` to execute exec providers during audit.
-
-    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`).
-
-  </Accordion>
-  <Accordion title="secrets configure">
-    Interactive helper that:
-
-    - configures `secrets.providers` first (`env`/`file`/`exec`, add/edit/remove)
-    - lets you select supported secret-bearing fields in `fengming.json` plus `auth-profiles.json` for one agent scope
-    - can create a new `auth-profiles.json` mapping directly in the target picker
-    - captures SecretRef details (`source`, `provider`, `id`)
-    - runs preflight resolution
-    - can apply immediately
-
-    Exec note:
-
-    - Preflight skips exec SecretRef checks unless `--allow-exec` is set.
-    - If you apply directly from `configure --apply` and the plan includes exec refs/providers, keep `--allow-exec` set for the apply step too.
-
-    Helpful modes:
-
-    - `fengming secrets configure --providers-only`
-    - `fengming secrets configure --skip-provider-setup`
-    - `fengming secrets configure --agent <id>`
-
-    `configure` apply defaults:
-
-    - scrub matching static credentials from `auth-profiles.json` for targeted providers
-    - scrub legacy static `api_key` entries from `auth.json`
-    - scrub matching known secret lines from `<config-dir>/.env`
-
-  </Accordion>
-  <Accordion title="secrets apply">
-    Apply a saved plan:
-
-    ```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
-    ```
-
-    Exec note:
-
-    - dry-run skips exec checks unless `--allow-exec` is set.
-    - write mode rejects plans containing exec SecretRefs/providers unless `--allow-exec` is set.
-
-    For strict target/path contract details and exact rejection rules, see [Secrets Apply Plan Contract](/gateway/secrets-plan-contract).
-
-  </Accordion>
-</AccordionGroup>
-
-## One-way safety policy
-
-<Warning>
-FengMing intentionally does not write rollback backups containing historical plaintext secret values.
-</Warning>
-
-Safety model:
-
-- preflight must succeed before write mode
-- runtime activation is validated before commit
-- apply updates files using atomic file replacement and best-effort restore on failure
-
-## Legacy auth compatibility notes
-
-For static credentials, runtime no longer depends on plaintext legacy auth storage.
-
-- Runtime credential source is the resolved in-memory snapshot.
-- Legacy static `api_key` entries are scrubbed when discovered.
-- OAuth-related compatibility behavior remains separate.
-
-## Web UI note
-
-Some SecretInput unions are easier to configure in raw editor mode than in form mode.
-
-## Related
-
-- [Authentication](/gateway/authentication) — auth setup
-- [CLI: secrets](/cli/secrets) — CLI commands
-- [Environment Variables](/help/environment) — environment precedence
-- [SecretRef Credential Surface](/reference/secretref-credential-surface) — credential surface
-- [Secrets Apply Plan Contract](/gateway/secrets-plan-contract) — plan contract details
-- [Security](/gateway/security) — security posture