docs(cli): improve secrets command guide

docs/cli/secrets.md

@@ -9,7 +9,29 @@ title: "secrets"
 
 # `openclaw secrets`
 
-Secrets runtime controls.
+Use `openclaw secrets` to migrate credentials from plaintext to SecretRefs and keep the active secrets runtime 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 config + auth stores + legacy residues (`.env`, `auth.json`) for plaintext, unresolved refs, and precedence drift.
+- `configure`: interactive planner for provider setup + target mapping + preflight (TTY required).
+- `apply`: execute a saved plan (`--dry-run` for validation only), then scrub migrated plaintext residues.
+
+Recommended operator loop:
+
+```bash
+openclaw secrets audit --check
+openclaw secrets configure
+openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
+openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
+openclaw secrets audit --check
+openclaw secrets reload
+```
+
+Exit code note for CI/gates:
+
+- `audit --check` returns `1` on findings, `2` when refs are unresolved.
 
 Related:
 
@@ -28,7 +50,7 @@ openclaw secrets reload --json
 Notes:
 
 - Uses gateway RPC method `secrets.reload`.
-- If resolution fails, gateway keeps last-known-good snapshot.
+- If resolution fails, gateway keeps last-known-good snapshot and returns an error (no partial activation).
 - JSON response includes `warningCount`.
 
 ## Audit
@@ -51,6 +73,16 @@ Exit behavior:
 - `--check` exits non-zero on findings.
 - unresolved refs exit with a higher-priority non-zero code.
 
+Report shape highlights:
+
+- `status`: `clean | findings | unresolved`
+- `summary`: `plaintextCount`, `unresolvedRefCount`, `shadowedRefCount`, `legacyResidueCount`
+- finding codes:
+  - `PLAINTEXT_FOUND`
+  - `REF_UNRESOLVED`
+  - `REF_SHADOWED`
+  - `LEGACY_RESIDUE`
+
 ## Configure (interactive helper)
 
 Build provider + SecretRef changes interactively, run preflight, and optionally apply:
@@ -77,10 +109,15 @@ Flags:
 
 Notes:
 
+- Requires an interactive TTY.
+- You cannot combine `--providers-only` with `--skip-provider-setup`.
 - `configure` targets secret-bearing fields in `openclaw.json`.
 - Include all secret-bearing fields you intend to migrate (for example both `models.providers.*.apiKey` and `skills.entries.*.apiKey`) so audit can reach a clean state.
 - It performs preflight resolution before apply.
+- Generated plans default to scrub options (`scrubEnv`, `scrubAuthProfilesForProviderTargets`, `scrubLegacyAuthJson` all enabled).
 - Apply path is one-way for migrated plaintext values.
+- Without `--apply`, CLI still prompts `Apply this plan now?` after preflight.
+- With `--apply` (and no `--yes`), CLI prompts an extra irreversible-migration confirmation.
 
 Exec provider safety note:
 
@@ -101,6 +138,13 @@ Plan contract details (allowed target paths, validation rules, and failure seman
 
 - [Secrets Apply Plan Contract](/gateway/secrets-plan-contract)
 
+What `apply` may update:
+
+- `openclaw.json` (SecretRef targets + provider upserts/deletes)
+- `auth-profiles.json` (provider-target scrubbing)
+- legacy `auth.json` residues
+- `~/.openclaw/.env` known secret keys whose values were migrated
+
 ## Why no rollback backups
 
 `secrets apply` intentionally does not write rollback backups containing old plaintext values.