@carllee1983/dbcli 1.20.0 → 1.20.2

package/CHANGELOG.md

@@ -6,6 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [1.20.1] - 2026-05-18
+
+### Changed
+
+- **Phase 23-04 follow-up closure — full DML/DDL audit coverage.** `insert / update / delete / export / q / schema` now invoke `writeAuditEntry` on every happy / failure / rejection branch (BlacklistError / PermissionError / ConnectionError / validation all flow through the wired catch block). This closes the v1.20.0 INTEGRATE-01 / INTEGRATE-04 partial gap noted in v1.20.0's Known limitation paragraph.
+- **Bi-directional `audit_ref` ⇄ `recovery_ref` linkage on every `--recovery`-capable command.** When any of the 6 newly-wired commands fails with `--recovery`, the audit entry's `recovery_ref` and the recovery envelope's `audit_ref` carry matching UUIDs — identical in shape to the Phase 25 `query` / `inspect` round-trip wiring. Agents can pivot from `.dbcli/last-recovery.json` to the audit entry via `dbcli audit tail --recovery-ref <id>`.
+- **AI-agent skill docs (`assets/SKILL.md`, `assets/SKILL.zh-TW.md`, `assets/reference.md`)** updated to advertise full 8-command bi-directional coverage; bilingual user docs (`docs/user/en/index.{md,html}`, `docs/user/zh-TW/index.{md,html}`) gained a `--recovery` row noting the cross-command linkage.
+
+### Tests
+
+- `tests/integration/recovery-audit-link.test.ts` — the legacy "J1 asymmetry guard" `describe` block (which asserted `'audit_ref' in envelope === false` for the 6 deferred commands) is replaced with a consolidated **6-command positive bi-directional round-trip** block. For each of `schema / q / export / insert / update / delete`, the test asserts `envelope.audit_ref === audit.id` AND `audit.recovery_ref === envelope.id`, with both refs matching `/^[0-9a-f-]{36}$/`.
+
+### Internal
+
+- `src/commands/{insert,update,delete,export,q,schema}.ts` — adopt the D-J catch-block template from Phase 25: pre-generate `envelopeId = crypto.randomUUID()` only when `options.recovery === true`, call `writeAuditEntry({ success: false, error, recovery_ref: envelopeId })` and capture the returned `auditId`, then call `emitRecoveryEnvelope(err, ctx, { envelopeId, auditRef: auditId ?? undefined })`. Success branches add `await writeAuditEntry(config, '<cmd>', options, { success: true, ... })`.
+- `src/commands/q.ts` — `handleQError` refactored to accept `config` so audit + envelope can be written together inside the same try/catch.
+- `src/adapters/capabilities.ts` — narrow `ExportOptions` / `QCommandOptions` shapes opened so the shared audit helper can read `--recovery` and `--config` without per-command type casts.
+- `.planning/phases/25-recovery-envelope-bi-directional-linkage/25-J1-COVERAGE-MATRIX.md` — coverage table refreshed; all 6 previously-deferred rows flipped to `YES (Phase 23-04 wired)`; Round-Trip Contract section replaces the old Asymmetry Guard section.
+
 ## [1.20.0] - 2026-05-17
 
 ### Added
@@ -26,7 +45,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Default-on, upgrade impact:** `audit.enabled = true` by default. Existing projects will begin creating `.dbcli/audit/<connection>.jsonl` on first command after upgrading. Set `audit.enabled = false` in `.dbcli` to opt out. The audit directory is gitignored by default; entries are metadata-only (D3) — never raw SQL bodies, `--param` values, or result cell contents. (D1)
 - `inspect` / `guide` / `recover` / `recover --apply` agent JSON output adds an `audit_recent` field (additive; shape stable; not a breaking change). v1.19.x consumers ignore the field.
-- _Known limitation (Phase 23-04 follow-up):_ Audit log captures `query`, `inspect`, and diagnostic-surface commands in v1.20.0; coverage for `insert / update / delete / export / q / schema` failure paths is tracked as Phase 23-04 follow-up (see `.planning/phases/25-recovery-envelope-bi-directional-linkage/25-J1-COVERAGE-MATRIX.md`). Recovery envelope linkage from the envelope side is unaffected — those commands continue to emit `.dbcli/last-recovery.json` envelopes; only the `audit_ref` back-pointer is missing in v1.20.0.
+- _Known limitation (Phase 23-04 follow-up):_ Audit log captures `query`, `inspect`, and diagnostic-surface commands in v1.20.0; coverage for `insert / update / delete / export / q / schema` failure paths is tracked as Phase 23-04 follow-up (see `.planning/phases/25-recovery-envelope-bi-directional-linkage/25-J1-COVERAGE-MATRIX.md`). Recovery envelope linkage from the envelope side is unaffected — those commands continue to emit `.dbcli/last-recovery.json` envelopes; only the `audit_ref` back-pointer is missing in v1.20.0. (Closed in v1.20.1 — see entry above.)
 
 ### Internal
 

package/README.md

@@ -1283,12 +1283,17 @@ audit history and recovery envelopes from either direction. The
 `audit_recent: AuditEntryBrief[]` (last 5 entries) so a fresh session has
 immediate context.
 
-**Known limitation (v1.20.0):** Bi-directional linkage is wired for `query`,
-`inspect`, and diagnostic surfaces. The DML commands `insert / update / delete /
-export / q / schema` emit single-direction recovery envelopes (no `audit_ref`)
-in v1.20.0; full coverage is tracked as Phase 23-04 follow-up. See
-[`.planning/phases/25-recovery-envelope-bi-directional-linkage/25-J1-COVERAGE-MATRIX.md`](./.planning/phases/25-recovery-envelope-bi-directional-linkage/25-J1-COVERAGE-MATRIX.md)
-for the full matrix.
+**Full bi-directional coverage (v1.20.1+):** Recovery ↔ audit linkage is
+wired on every `--recovery`-capable command — `query`, `inspect`, `insert`,
+`update`, `delete`, `export`, `q`, and `schema`. The audit entry's
+`recovery_ref` and the envelope's `audit_ref` carry matching UUIDs on every
+failure path, so agents can pivot from a saved envelope
+(`.dbcli/last-recovery.json`) to its audit entry via
+`dbcli audit tail --recovery-ref <id>` (and back via
+`dbcli audit show --recovery-ref <id>`). The v1.20.0 partial-coverage gap
+on the 6 DML/DDL commands was closed in v1.20.1. The coverage matrix lives
+in
+[`.planning/phases/25-recovery-envelope-bi-directional-linkage/25-J1-COVERAGE-MATRIX.md`](./.planning/phases/25-recovery-envelope-bi-directional-linkage/25-J1-COVERAGE-MATRIX.md).
 
 For deeper agent workflows (session handoff, forensics walk-through), see
 [`assets/SKILL.md`](./assets/SKILL.md) §Audit Log usage.

package/assets/SKILL.md

@@ -43,6 +43,8 @@ Database CLI for AI agents with permission-based access control.
      ```
 
      `--result` accepts inline JSON `StepResultSummary` or `@<path>` to read from a file. `stdoutSummary` and `stderrSummary` are capped at 4 KB each — pre-truncate to the **last** 4 KB before passing. `--next` is mutually exclusive with `--apply`. Each call is independent (no persisted cursor) — the agent tracks `--after-step` itself.
+
+     **Connection branching.** For `CONN_*` codes, the envelope ships a `branches` map + `branchFork` descriptor. Step 1 (`dbcli doctor --format json`) is the fork point: pass the doctor JSON in `--result.stdoutSummary` and `--next` will pick one of four labeled branches (`doctor-clean` / `doctor-config-missing` / `doctor-auth-error` / `doctor-network-error`). NextResult then carries `branchId` and `branchDescription`; subsequent calls must echo `--branch <id>` to walk that branch. Parse failure / unmatched keywords fall back to linear `recovery`. `--apply` ignores branches entirely.
 5. `dbcli blacklist list` — sensitive data boundaries.
 6. `dbcli schema <table> --format json` — real column names (SQL/Mongo/ES) or `schema <key>` (Redis). **Never guess.**
 7. Run `query` / `insert` / `update` / `delete` / `export` within permission.
@@ -100,15 +102,17 @@ The `inspect` / `guide` / `recover` / `recover --apply` agent JSON output embeds
 history context. The envelope's `audit_ref` and the audit entry's `recovery_ref`
 point at each other; agents can pivot either direction.
 
-**Known limitation (v1.20.0):** Bi-directional linkage is wired for `query`,
-`inspect`, and diagnostic surfaces. The commands `insert / update / delete /
-export / q / schema` emit single-direction recovery envelopes (no `audit_ref`)
-in v1.20.0; full coverage is tracked as Phase 23-04 follow-up. Recovery envelope
-linkage from the envelope side is unaffected.
+Bi-directional `recovery_ref` / `audit_ref` linkage is wired on every command
+that accepts `--recovery`: `query`, `inspect`, `insert`, `update`, `delete`,
+`export`, `q`, and `schema`. Agents can pivot from an envelope to its audit
+entry via `audit tail --recovery-ref <id>`.
 
 Audit entries are written to `.dbcli/audit/<connection>.jsonl` with rotation at
 ~10 MB or 1000 entries. `audit.enabled = false` in `.dbcli` opts out (default ON
 since v1.20.0). For flag reference see [`reference.md`](./reference.md) §audit.
+For end-to-end recovery walkthroughs (per-code scenarios, `--next` multi-turn,
+envelope ⇄ audit pivot, risk-gate cheat sheet) see
+[`reference.md`](./reference.md) §Recovery Cookbook.
 
 ## Quick start
 
@@ -271,9 +275,12 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 ## MongoDB
 
 - JSON filter object (`find`) or JSON array (`aggregate`); SQL is rejected. `--collection <name>` is required on `query`.
-- **Supported:** `init`, `list`, `schema` (sampled), `query`, `insert`, `update`, `delete`, `export`, `status`, `use`, `shell`, `doctor`, `upgrade`, `completion`.
-- **Not supported:** `q` (saved queries), `diff`, `migrate`, `check`.
-- Schema is **sampled** (default 50 docs); types are JS `typeof` strings.
+- **Supported:** `init`, `list`, `schema` (sampled), `query`, `insert`, `update`, `delete`, `export`, `q` (saved queries), `status`, `use`, `shell`, `doctor`, `upgrade`, `completion`.
+- **Not supported:** `diff`, `migrate`, `check`.
+- Schema is **sampled** by `$sample` (default 100 docs, max 1000). Pass `--sample-method natural` to use `find().limit()` instead. Columns surface as dot-paths (e.g. `profile.tokens.access`) with `presence` (0..1) and `redacted: true` flags for blacklist hits.
+- **Write planner tiers:** `$set`/`$unset` → `ALLOW`; `$rename` → `WARN` (informational); `$inc`/`$mul`/`$min`/`$max`/`$currentDate` → `WARN`; `$push`/`$pull`/`$pullAll`/`$pop`/`$addToSet` → `WARN`; `$bit` → `WARN`; `$where` and unknown operators → `BLOCK`.
+- **Nested blacklist:** `blacklist.columns[<collection>]` accepts dotted paths (`profile.email`) and trailing-wildcard prefixes (`profile.tokens.*`); middle wildcards are rejected with a warning at `dbcli blacklist list`. Read paths replace matched values with the literal string `[REDACTED]`.
+- **Saved queries:** snippet file ends in `.mongodb.sql`. Frontmatter requires `engine: mongodb` and `operation: find` or `operation: aggregate`. `target: <collection>` is the default collection (override with `--collection`). Body is JSON (object for `find`, array for `aggregate`); `{{param}}` placeholders are JSON-encoded.
 - See reference.md MongoDB section for full syntax and examples.
 
 ## Redis

package/assets/SKILL.zh-TW.md

@@ -45,6 +45,8 @@ description: 為 AI 代理設計、具權限控管的資料庫 CLI。可用於
      ```
 
      `--result` 接受 inline JSON `StepResultSummary`,或 `@<path>` 從檔案讀取。`stdoutSummary` 與 `stderrSummary` 各上限 4 KB — 請先把結果截到 **最後** 4 KB 再傳入。`--next` 與 `--apply` 互斥。每次呼叫獨立(不持久化 cursor)— 代理自行追蹤 `--after-step`。
+
+     **連線錯誤分支。** 針對 `CONN_*` 代碼，envelope 會額外帶 `branches` 與 `branchFork`。步驟 1（`dbcli doctor --format json`）即為分支點：把 doctor JSON 透過 `--result.stdoutSummary` 傳入，`--next` 會挑選四個分支之一（`doctor-clean` / `doctor-config-missing` / `doctor-auth-error` / `doctor-network-error`）。NextResult 會帶 `branchId` 與 `branchDescription`；後續呼叫必須以 `--branch <id>` 走訪該分支。解析失敗或關鍵字不匹配時回落為線性 `recovery`。`--apply` 不使用 `branches`。
 5. `dbcli blacklist list` — 敏感資料邊界。
 6. `dbcli schema <table> --format json` — 取得真實欄位名稱(SQL / Mongo / ES)或 `schema <key>`(Redis)。**禁止猜測。**
 7. 在允許的權限範圍內執行 `query` / `insert` / `update` / `delete` / `export`。
@@ -89,9 +91,9 @@ dbcli audit show --recovery-ref <envelope-id> # 反向找出觸發 envelope 的
 
 `inspect` / `guide` / `recover` / `recover --apply` 的 agent JSON 內嵌 `audit_recent: AuditEntryBrief[]`(最近 5 筆),無須額外呼叫 audit CLI 即可看到歷史脈絡。Envelope 的 `audit_ref` 與 audit entry 的 `recovery_ref` 互為雙向指標。
 
-**已知限制(v1.20.0):** Bi-directional 連結僅在 `query` / `inspect` / diagnostic 表面寫入;`insert` / `update` / `delete` / `export` / `q` / `schema` 失敗路徑暫未含 `audit_ref`,追蹤於 Phase 23-04 follow-up(見 `.planning/phases/25-recovery-envelope-bi-directional-linkage/25-J1-COVERAGE-MATRIX.md`)。Recovery envelope 既有 linkage 不受影響。
+**完整雙向覆蓋(v1.20.1+):** `recovery_ref` / `audit_ref` 雙向連結已在所有支援 `--recovery` 的指令上佈線:`query`、`inspect`、`insert`、`update`、`delete`、`export`、`q`、`schema`。Agent 可透過 `dbcli audit tail --recovery-ref <id>` 從 envelope 反查 audit entry(反方向用 `dbcli audit show --recovery-ref <id>`)。v1.20.0 中 6 個 DML/DDL 指令的部分覆蓋缺口已於 v1.20.1 關閉。
 
-詳細指令參考:[`reference.md`](./reference.md) §audit(英文)。
+詳細指令參考:[`reference.md`](./reference.md) §audit(英文)。完整 agent 復原 walkthrough(各錯誤碼 end-to-end 情境、`--next` 多輪逐步、envelope ⇄ audit pivot、risk gate cheat sheet)見 [`reference.md`](./reference.md) §Recovery Cookbook(英文)。
 
 完整旗標、每個指令的可貼上範例、`migrate` DDL、互動式 `shell` 與 MongoDB / Redis / ES 教學在 [reference.md](reference.md)(安裝時與本檔放在一起)。
 
@@ -239,9 +241,12 @@ dbcli init --use-env-refs \
 ## MongoDB
 
 - 用 JSON filter 物件(`find`)或 JSON 陣列(`aggregate`);SQL 會被拒絕。`query` 必填 `--collection <name>`。
-- **支援:** `init`、`list`、`schema`(sampled)、`query`、`insert`、`update`、`delete`、`export`、`status`、`use`、`shell`、`doctor`、`upgrade`、`completion`。
-- **不支援:** `q`(saved queries)、`diff`、`migrate`、`check`。
-- Schema 是**取樣**(預設 50 份文件);型別是 JS `typeof` 字串。
+- **支援:** `init`、`list`、`schema`(sampled)、`query`、`insert`、`update`、`delete`、`export`、`q`(saved queries)、`status`、`use`、`shell`、`doctor`、`upgrade`、`completion`。
+- **不支援:** `diff`、`migrate`、`check`。
+- Schema 由 `$sample` **採樣**（預設 100 份文件，上限 1000）。可加 `--sample-method natural` 改用 `find().limit()`。欄位以 dot-path 呈現（如 `profile.tokens.access`），附帶 `presence`（0..1）與命中黑名單時的 `redacted: true`。
+- **寫入規劃器分層：** `$set`/`$unset` → `ALLOW`；`$rename` → `WARN`（資訊提示）；`$inc`/`$mul`/`$min`/`$max`/`$currentDate` → `WARN`；`$push`/`$pull`/`$pullAll`/`$pop`/`$addToSet` → `WARN`；`$bit` → `WARN`；`$where` 與未知運算子 → `BLOCK`。
+- **巢狀黑名單：** `blacklist.columns[<collection>]` 接受點分路徑（`profile.email`）與結尾萬用字元（`profile.tokens.*`）；中間萬用字元會在 `dbcli blacklist list` 警告並略過。讀取路徑會將命中值取代為字串字面值 `[REDACTED]`。
+- **儲存查詢：** snippet 檔名以 `.mongodb.sql` 結尾。Frontmatter 必填 `engine: mongodb` 與 `operation: find` 或 `operation: aggregate`。`target: <collection>` 為預設集合，可由 `--collection` 覆蓋。主體為 JSON（`find` 為物件、`aggregate` 為陣列）；`{{param}}` 佔位符會 JSON 編碼。
 - 完整語法與範例見 reference.md MongoDB 段落。
 
 ## Redis

package/assets/reference.md

@@ -100,13 +100,14 @@ dbcli schema --use staging          # Scan staging DB; saves to .dbcli/schemas/s
 dbcli schema --use prod             # Scan prod DB; saves to .dbcli/schemas/prod/
 ```
 
-**Options:** `--format <table|json>`, `--refresh`, `--reset`, `--force`, `--use <connection>`
+**Options:** `--format <table|json>`, `--refresh`, `--reset`, `--force`, `--use <connection>`, `--sample-size <n>` (mongo only), `--sample-method <random|natural>` (mongo only)
 **Permission:** query-only+
 
 **Schema storage (v1.4+):** Schema is persisted as layered files under `.dbcli/schemas/`. With v2 multi-connection config each connection gets its own subdirectory (`.dbcli/schemas/<connection>/`). Run `dbcli schema --use <connection>` once per connection before querying it — otherwise `schema <table>` may return data from the wrong connection's cache.
 
 > **Redis:** `schema <key>` is required (no full scan). The output exposes `type`, `ttl`, `size`, and a small `sample` (e.g. first 5 hash keys). `--reset` / `--refresh` are rejected — Redis caches no schema.
 > **Elasticsearch:** `schema [index]` flattens the `_mapping` properties (nested `a.b.c`) and emits each `.fields` multi-field as a separate column (e.g. `text` + `text.keyword`). Full scan iterates all non-system indices and stores per-connection caches alongside SQL engines.
+> **MongoDB:** schema is sampled via `$sample` (default 100, max 1000). `--sample-method natural` switches to `find().limit()`; `random` (default) falls back to natural order on driver error. Output columns surface nested dot-paths with `presence` (0..1) and `redacted: true` flags for blacklist-matched paths. The persisted cache records `sampleMethod` and `sampleSize`; `dbcli doctor` reports them via a `sampled: method=…, size=…` line.
 
 ### query
 
@@ -328,6 +329,57 @@ Substitution rules: pure raw text — `:name` becomes the value's `String()` for
 
 Size guard: `LRANGE` / `ZRANGE` stop overridden when `< 0` or `> 1000`; `SCAN` / `HSCAN` / `SSCAN` / `ZSCAN` get `COUNT 1000` injected if absent. `--no-limit` disables.
 
+##### MongoDB snippets
+
+File extension: `.mongodb.sql`. Frontmatter must declare `engine: mongodb` and
+`operation: find` or `operation: aggregate`. `target: <collection>` provides a default
+collection that `dbcli q --collection <name>` can override. The body is JSON: an object
+for `find` and an array for `aggregate`. Each `{{param}}` placeholder is JSON-encoded
+at substitution time — strings are quoted and escaped, so an attacker-supplied string
+cannot escape into operator position.
+
+Find example (`active-users.mongodb.sql`):
+
+    -- ---
+    -- name: active-users
+    -- engine: mongodb
+    -- operation: find
+    -- target: users
+    -- description: Active users matching the given status
+    -- params:
+    --   status:
+    --     type: string
+    --     required: true
+    -- ---
+    {
+      "status": {{status}}
+    }
+
+Aggregate example (`top-orders-by-city.mongodb.sql`):
+
+    -- ---
+    -- name: top-orders-by-city
+    -- engine: mongodb
+    -- operation: aggregate
+    -- target: orders
+    -- description: Top order counts per city for a given status
+    -- params:
+    --   status:
+    --     type: string
+    --     required: true
+    --   limit:
+    --     type: int
+    --     default: 10
+    -- ---
+    [
+      { "$match": { "status": {{status}} } },
+      { "$group": { "_id": "$city", "n": { "$sum": 1 } } },
+      { "$sort": { "n": -1 } },
+      { "$limit": {{limit}} }
+    ]
+
+Run with `dbcli q @active-users -p status=active` or `dbcli q @top-orders-by-city -p status=open -p limit=5`. The `q` command applies the same nested-blacklist redaction to results that `query` and `export` do.
+
 ### queries
 
 Manage saved snippets — discover, inspect, scaffold, and edit local copies. Mutating
@@ -727,8 +779,9 @@ deterministically.
 | Flag | Required | Description |
 |---|---|---|
 | `--next` | yes | Activate the multi-turn lookup. |
-| `--after-step <n>` | yes | 1-based order of the step the agent just executed. Range: `[1, envelope.recovery.length]`. |
+| `--after-step <n>` | yes | 1-based order of the step the agent just executed. Range: `[1, envelope.recovery.length]` (or `[1, branches[id].steps.length]` when `--branch` is set). |
 | `--result <value>` | yes | JSON `StepResultSummary` (inline) or `@<path>` to read from a file. |
+| `--branch <id>` | no | Walk a specific branch by id (required on `--next` calls after a fork). See *Connection branching* below. |
 | `--from <path>` | no | Override the auto-saved envelope. |
 | `--format <fmt>` | no | `json` (default) or `markdown`. |
 
@@ -760,9 +813,24 @@ interface NextResult {
   cursor: number       // step.order when kind='step'; totalSteps when 'done'
   totalSteps: number
   step?: GuideStep     // present iff kind='step'
+  branchId?: string         // set iff agent is currently traversing a branch
+  branchDescription?: string // mirror of branches[branchId].description
 }
 ```
 
+**Connection branching**
+
+For `CONN_*` recovery codes, the envelope ships an additional `branches` map and a `branchFork` descriptor. Step 1 (`dbcli doctor --format json`) is the fork point: pass the doctor JSON in `--result.stdoutSummary` and `--next` will pick one of four labeled branches:
+
+| Branch id | When chosen |
+|---|---|
+| `doctor-clean` | Doctor reports no errors — likely transient; verify baseline state, then retry. |
+| `doctor-config-missing` | Doctor flagged a config-level failure (missing / invalid config). Re-init before reconnecting. |
+| `doctor-auth-error` | Doctor confirms credentials were rejected. Re-init with `--force` to overwrite credentials. |
+| `doctor-network-error` | Doctor confirms a network-level failure (host / port / DNS / timeout). Inspect and re-init host/port. |
+
+NextResult sets `branchId` and `branchDescription` after the fork; subsequent `--next` calls must echo `--branch <id>` to walk that branch. If the doctor JSON cannot be parsed or no keyword matches, `--next` falls back to the linear `recovery` plan — branching never causes `--next` to fail. `--apply` ignores `branches` entirely (linear walk unchanged).
+
 **Exit codes**
 
 | Exit | Condition |
@@ -859,7 +927,7 @@ Output reports: writer enabled/disabled, last write result, file-lock state, rot
 #### Boundaries
 
 - Entries are append-only JSONL; rotation triggers at `~10 MB` or `~1000` entries (whichever first). Previous segment is preserved as `.jsonl.1`.
-- Bi-directional `recovery_ref` / `audit_ref` linkage is wired on `query` / `inspect` / diagnostic surfaces (Phase 25 J1). The commands `insert / update / delete / export / q / schema` emit single-direction envelopes (no `audit_ref`) in v1.20.0 — tracked as Phase 23-04 follow-up.
+- Bi-directional `recovery_ref` / `audit_ref` linkage is wired on every command that accepts `--recovery`: `query`, `inspect`, `insert`, `update`, `delete`, `export`, `q`, and `schema`. Use `audit tail --recovery-ref <id>` to find the audit entry an envelope was emitted alongside.
 - Audit writer failures are non-fatal (D6): main command result and exit code are preserved; a stderr warning is emitted. `audit health` surfaces the failure reason.
 - Reader truncation tolerance: a crash-truncated last line is skipped with a stderr warn `[dbcli audit] skipping truncated last line in <file>`; a mid-file non-JSON line is treated as corruption, exits 1, and points at `dbcli audit clear`.
 
@@ -1042,6 +1110,270 @@ Task storage layers:
 Higher tiers override lower tiers by task name. Task name is derived from the
 file path under the tier root (e.g. `diag/inspect.md` → `diag/inspect`).
 
+## Recovery Cookbook (agent walkthroughs)
+
+End-to-end recovery sessions for the most common failure codes. All examples
+assume the agent invoked a `--recovery`-capable command and received a
+`RecoveryEnvelope` (or hit the same envelope via `dbcli recovery --code <CODE>`
+lookup). See [§recovery](#recovery) for the envelope shape, [§recover](#recover)
+for `--apply` / `--next` / risk-gate semantics, and [§audit](#audit) for the
+bi-directional `audit_ref` ⇄ `recovery_ref` pivot.
+
+### Scenario index
+
+| Code | Trigger | Primary remediation | Risk tier |
+|------|---------|---------------------|-----------|
+| `CONN_REFUSED` | Database process down or wrong host/port. | `dbcli doctor` → fix host/port → retry. | `readonly` |
+| `CONN_AUTH_FAILED` | Credentials rejected. | Re-check `.dbcli`/env, rotate credentials, `dbcli init --force` only on explicit user nod. | `readonly` → `interactive` |
+| `PERMISSION_DENIED` | Active permission level forbids the verb. | `dbcli inspect` to confirm level → escalate via `dbcli init` (human) or run a `--dry-run` instead. | `readonly` + `dry-run` |
+| `BLACKLIST_TABLE` | Target table is blacklisted. | `dbcli blacklist list` → `blacklist table remove <name>` (local-write tier). | `readonly` + `local-write` |
+| `BLACKLIST_COLUMN_WRITE` | INSERT/UPDATE touches a blacklisted column. | Re-shape payload to drop the column, or `blacklist column remove`. Envelope prepends a `--dry-run` preview step. | `dry-run` + `local-write` |
+| `SCHEMA_CACHE_MISSING` | Fresh checkout / new v2 connection / cache wiped. | `dbcli schema --refresh --force` (or `--use <conn>` per-connection). | `readonly` |
+| `SNIPPET_NOT_FOUND` / `SNIPPET_AMBIGUOUS` | Typo or duplicate snippet name. | `dbcli queries list` → `queries search <kw>` → run correct `@name`. | `readonly` |
+| `SNIPPET_PARAM_MISSING` | `--param k=v` not supplied. | `dbcli queries show @name` lists required params → re-run with full set. | `readonly` |
+| `CONFIG_MISSING` | No `.dbcli` in cwd. | `dbcli init` (human-driven). | `interactive` |
+
+`risk` enum: `readonly` / `dry-run` / `write` / `unknown` (see §recovery boundaries).
+Allowlist tier: `readonly` / `dry-run` / `local-write` / `db-write` / `interactive` (see [§recover Risk gate matrix](#risk-gate-matrix)).
+
+### S1 — CONN_REFUSED end-to-end
+
+```bash
+# 1. Failing call writes envelope to stdout AND .dbcli/last-recovery.json
+$ dbcli query "SELECT 1" --recovery --format json
+{
+  "schemaVersion": 1,
+  "error": { "code": "CONN_REFUSED", "message": "..." },
+  "audit_ref": "1f8e...c4d2",
+  "recovery": [
+    { "order": 1, "command": "dbcli doctor --format json", "risk": "readonly", ... },
+    { "order": 2, "command": "dbcli inspect --for-agent",  "risk": "readonly", ... }
+  ],
+  "verify": { "command": "dbcli doctor --format json", "risk": "readonly", ... }
+}
+
+# 2. One-shot apply (only readonly + dry-run run by default)
+$ dbcli recover --apply --format json
+{ "finalStatus": "ok", "executed": [...], "verifyStatus": "passed" }
+# Exit 0 → root cause cleared (verify probe succeeded).
+
+# 3. If verify reported `failed` / `indeterminate`, drop into --next for control
+$ dbcli recover --next --after-step 1 --result '{"status":"failed","exitCode":1}'
+# → returns a refined step 2 or `kind:"done"` based on the prevResult
+```
+
+### S2 — PERMISSION_DENIED with implicit `--dry-run` preview
+
+```bash
+$ dbcli update orders --where "id=1" --set '{"status":"shipped"}' --recovery --format json
+{
+  "error": { "code": "PERMISSION_DENIED", ... },
+  "audit_ref": "9ab0...e711",
+  "recovery": [
+    { "order": 1, "command": "dbcli update orders --where 'id=1' --set '<redacted>' --dry-run", "risk": "dry-run" },
+    { "order": 2, "command": "dbcli inspect --for-agent", "risk": "readonly" }
+  ]
+}
+
+# Default apply runs both steps (dry-run is in-tier).
+$ dbcli recover --apply
+```
+
+When the failing operation is INSERT/UPDATE/DELETE, the envelope prepends a
+`risk: 'dry-run'` step (the same write subcommand with `--dry-run`). Run it
+before any escalation — it both teaches the agent what the SQL looks like and
+proves the change is well-formed before raising the permission tier.
+
+### S3 — BLACKLIST_TABLE (local-write remediation)
+
+```bash
+$ dbcli query "SELECT * FROM audit_logs" --recovery --format json
+# error.code: BLACKLIST_TABLE
+# recovery[0]: dbcli blacklist list                     (risk: readonly)
+# recovery[1]: dbcli blacklist table remove audit_logs  (risk: write — local-write tier)
+
+# Default --apply: step 1 runs, step 2 skipped:risk → exit 3.
+$ dbcli recover --apply
+# To proceed: open the gate to local-write tier ONLY (does not touch DB).
+$ dbcli recover --apply --allow-write=readonly-cmd
+{ "finalStatus": "ok", "executed": [step1, step2], "verifyStatus": "passed" }
+```
+
+### S4 — BLACKLIST_COLUMN_WRITE (preview-then-drop)
+
+```bash
+$ dbcli insert users --data '{"name":"a","ssn":"123"}' --recovery
+# recovery[0]: dbcli insert users --data '<redacted>' --dry-run  (risk: dry-run)
+# recovery[1]: dbcli blacklist list                              (risk: readonly)
+# recovery[2]: dbcli blacklist column remove users.ssn           (risk: write — local-write)
+
+# Preferred path: don't widen the blacklist — re-shape the agent's payload to drop ssn.
+# Apply only the diagnostic prefix (steps 1+2) to confirm what columns are masked:
+$ dbcli recover --apply
+# Then re-issue insert without `ssn`.
+```
+
+### S5 — SCHEMA_CACHE_MISSING (fresh / multi-conn)
+
+```bash
+$ dbcli inspect --require-schema-cache --recovery --format json
+# error.code: SCHEMA_CACHE_MISSING
+# recovery[0]: dbcli schema --refresh --force      (risk: readonly — populates .dbcli/schemas/)
+# verify:      dbcli inspect --format json         (schemaCache.available === true)
+
+$ dbcli recover --apply
+# Per-connection cache lives at .dbcli/schemas/<connection>/. If the failure was on
+# a v2 named connection, the envelope's command already carries `--use <name>`.
+```
+
+### S6 — SNIPPET_NOT_FOUND with disambiguation
+
+```bash
+$ dbcli q @anaytics/revenue --recovery
+# typo: anaytics → analytics
+# recovery[0]: dbcli queries list --format json
+# recovery[1]: dbcli queries search analytics  (or whatever --hint suggests)
+$ dbcli recover --apply
+# Agent reads stdoutSummary, identifies the correct @name, then re-issues:
+$ dbcli q @analytics/revenue --param days=30
+```
+
+### Multi-turn `--next` walkthrough (3-step plan)
+
+Use `--next` instead of `--apply` when:
+
+- `--apply` is too coarse-grained (the agent wants step-by-step inspection).
+- The plan contains an `interactive` step that `--apply` would skip.
+- The agent uses its own runner / sandbox and just wants dbcli to drive cursoring.
+
+`--next` returns one step at a time, given which step the agent **just executed**
+and a `StepResultSummary` of how it went. dbcli does not persist the cursor —
+the agent owns `--after-step`.
+
+```bash
+# Envelope already saved at .dbcli/last-recovery.json (3-step plan, CONN_REFUSED).
+
+# Round 1 — agent reads step 1 from the envelope, executes it itself, then asks
+# dbcli for the next step.
+$ dbcli recover --next --after-step 1 --result '{"status":"ok","exitCode":0}' --format json
+{
+  "schemaVersion": 1,
+  "kind": "step",
+  "errorCode": "CONN_REFUSED",
+  "cursor": 2,
+  "totalSteps": 3,
+  "step": { "order": 2, "command": "dbcli inspect --for-agent", "risk": "readonly", ... }
+}
+
+# Round 2 — bigger stdout, save to file and reference it.
+$ ./run-step.sh > /tmp/r2.json   # agent's own runner; result is StepResultSummary JSON
+$ dbcli recover --next --after-step 2 --result @/tmp/r2.json
+{ "kind": "step", "cursor": 3, "step": { "order": 3, ... } }
+
+# Round 3 — last step done.
+$ dbcli recover --next --after-step 3 --result '{"status":"ok"}'
+{ "kind": "done", "cursor": 3, "totalSteps": 3 }
+```
+
+`StepResultSummary` contract (recap of [§recover Multi-turn](#multi-turn---next-p2)):
+
+```ts
+interface StepResultSummary {
+  status: 'ok' | 'failed' | 'skipped'
+  exitCode?: number
+  stdoutSummary?: string  // last 4 KB
+  stderrSummary?: string  // last 4 KB
+}
+```
+
+Truncate to the **last** 4 KB before passing — the head of a huge stdout is
+usually not what disambiguates next steps.
+
+Verification is **not** automatic under `--next`. If the agent wants the same
+verify probe `--apply` runs, it must execute the envelope's `verify` step
+itself after the plan completes.
+
+### Bi-directional pivot (envelope ⇄ audit)
+
+Every `--recovery`-capable failure (`query`, `inspect`, `insert`, `update`,
+`delete`, `export`, `q`, `schema`) writes **both** sides of a UUID link:
+
+- `RecoveryEnvelope.audit_ref` → the `audit.id` for the same failure.
+- `AuditEntry.recovery_ref` → the envelope's id (also the auto-saved
+  `.dbcli/last-recovery.json` filename trace).
+
+```bash
+# From envelope → audit (forensics on a saved failure)
+$ ENV_ID=$(jq -r '.id' .dbcli/last-recovery.json)        # or read from stdout
+$ dbcli audit show --recovery-ref "$ENV_ID" --format json
+# Returns the matching audit entry (full, not brief).
+
+# From audit → envelope (you have an audit hit, want the structured plan)
+$ AUDIT_ID=$(dbcli audit tail --for-agent --n 1 | jq -r '.[0].id')
+$ dbcli audit show "$AUDIT_ID" --format json
+# Read `recovery_ref` from the entry, then either re-run --recovery against
+# the original command or load the saved envelope:
+$ jq '.recovery_ref' .dbcli/last-recovery.json | grep -q "$RECOVERY_REF" \
+  && dbcli recover --format markdown            # human inspect
+  || dbcli recover --from /path/to/archived.json --format markdown
+```
+
+Session handoff: a fresh agent that opens `dbcli inspect --for-agent`,
+`dbcli guide`, `dbcli recover`, or `dbcli recover --apply` gets an
+`audit_recent: AuditEntryBrief[]` field (last 5 entries) embedded in the JSON
+output — no extra round-trip to the audit CLI needed for immediate history
+context.
+
+### Risk gate cheat sheet
+
+Quick reference for what `--apply` runs at each `--allow-write` level. The
+canonical matrix lives at [§recover Risk gate matrix](#risk-gate-matrix); this
+table maps it onto common agent intents.
+
+| Agent intent | Recommended flag | What runs | What's skipped |
+|---|---|---|---|
+| Probe-only (read state, learn) | `--apply` (default) | `readonly` + `dry-run` steps | `local-write`, `db-write`, `interactive` |
+| Local config remediation (e.g. `blacklist remove`) | `--apply --allow-write=readonly-cmd` | + `local-write` | `db-write`, `interactive` |
+| Database write recovery (rare; trusted plan) | `--apply --allow-write=write-cmd` | + `db-write` | `interactive` |
+| Interactive step (e.g. `dbcli init`) | Drive manually OR use `--next` | n/a | All interactive steps always skip under `--apply` |
+| Walk plan step-by-step with own runner | `--next --after-step N --result …` | one step per call | n/a — agent owns cursor + execution |
+
+Three rules that always apply regardless of `--allow-write`:
+
+1. **Tier is code-owned, not envelope-claimed.** The risk gate reads the
+   per-error-code allowlist after parsing argv. An envelope cannot escalate
+   itself by setting `risk: 'readonly'` on a write subcommand — argv decides.
+2. **Placeholders block.** A step with unresolved `<token>` placeholders is
+   skipped as `skipped:placeholder` even at `--allow-write=write-cmd`. Bind
+   them at `recovery` lookup time with `--hint` / `--snippet` / `--table`, or
+   ask the user.
+3. **Verify is signal, not gate.** `verifyStatus` ∈ `{passed, failed,
+   indeterminate}` reports whether the original failure looks resolved.
+   `recover --apply` exit code is set by step execution, not verification.
+
+### Common pitfalls
+
+- **Stale `.dbcli/last-recovery.json`.** `recover` (no `--apply`) shows the
+  *saved* plan, which may be hours old. Re-run the original command with
+  `--recovery` to refresh it, or pass `--from <file>` to load an archived one.
+- **`.dbcli/` is gitignored.** Do not check `last-recovery.json` into a repo
+  for "reproducibility"; it contains sanitized command snapshots but the
+  workspace `cwd` only makes sense locally. Use `recover --from <archived.json>`
+  for cross-machine replay.
+- **`--apply` exit 3 means every step skipped.** Not a failure — it means the
+  default gate was too tight. Either widen with `--allow-write`, fill
+  placeholders, or fall back to `--next` and drive steps manually.
+- **`--next` does not run verify.** Re-run the original failing command with
+  `--recovery` once the plan is done; if it now succeeds (no envelope on
+  stdout), recovery is complete. Or invoke `envelope.verify.command` yourself.
+- **Audit writer failures are non-fatal.** If `audit health` reports
+  `lastWriteOk: false`, the main command still completed — but `recovery_ref`
+  ⇄ `audit_ref` linkage is broken for that one call. `audit health` surfaces
+  the underlying error (disk full, EACCES, etc.).
+- **Cross-connection forensics.** `audit tail --all --for-agent` merges all
+  connections; `audit show <id-prefix> --all` returns an envelope `{connection,
+  entry}` so a fresh agent can tell which DB the failure was against.
+
 ## Interactive HTML dashboard
 
 `query`, `q`, and `export` can render results as a single, fully self-contained
@@ -1150,19 +1482,21 @@ MongoDB connections use a JSON-based query model instead of SQL. Treat MongoDB s
 
 Atlas-style `mongodb+srv://` URIs are supported. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
 
-**Supported commands:** `init`, `use`, `list`, `schema`, `query`, `insert`, `update`, `delete`, `status`, `shell`, `doctor`, `upgrade`, `completion`
+**Supported commands:** `init`, `use`, `list`, `schema`, `query`, `q`, `insert`, `update`, `delete`, `export`, `status`, `shell`, `doctor`, `upgrade`, `completion`
 
 **Limited support:**
 
 - `schema` samples collection documents to infer field names/types. It does not provide relational constraints, primary keys, foreign keys, or reliable index metadata.
 - `query` accepts only JSON object filters or aggregation pipeline arrays and always requires `--collection <name>`.
+- `q` saved-query execution accepts JSON `find` / `aggregate` bodies, requires a `collection` frontmatter field (CLI `--collection` overrides), JSON-encodes every `{{param}}` substitution, and enforces table-level blacklist plus document field masking before rendering.
 - `insert` inserts one JSON document into the named collection.
 - `update` accepts a JSON filter in `--where` or simple `key=value` conditions. If `--set` does not use MongoDB update operators such as `$set`, dbcli wraps it in `$set`.
 - `delete` deletes all documents matching the JSON/simple filter.
+- `export` accepts the same JSON filter / aggregation syntax as `query`.
 - MongoDB write paths do not currently provide the same SQL dry-run, relational schema validation, or column-level blacklist filtering guarantees as SQL writes.
 - `shell` blocks raw SQL for MongoDB; use `query <json> --collection <name>` inside the shell.
 
-**Not supported (exit with error):** `q` saved-query execution, `export`, `diff`, `migrate`
+**Not supported (exit with error):** `diff`, `migrate`
 
 **Not a supported MongoDB target:** `check` is designed for relational health checks and emits SQL-style checks.
 

package/assets/snippets/diag/active-users.mongodb.sql

@@ -0,0 +1,14 @@
+-- ---
+-- name: active-users
+-- engine: mongodb
+-- operation: find
+-- target: users
+-- description: Active users matching the given status
+-- params:
+--   status:
+--     type: string
+--     required: true
+-- ---
+{
+  "status": {{status}}
+}

package/assets/snippets/diag/top-orders-by-city.mongodb.sql

@@ -0,0 +1,20 @@
+-- ---
+-- name: top-orders-by-city
+-- engine: mongodb
+-- operation: aggregate
+-- target: orders
+-- description: Top order counts per city for a given status
+-- params:
+--   status:
+--     type: string
+--     required: true
+--   limit:
+--     type: int
+--     default: 10
+-- ---
+[
+  { "$match": { "status": {{status}} } },
+  { "$group": { "_id": "$city", "n": { "$sum": 1 } } },
+  { "$sort": { "n": -1 } },
+  { "$limit": {{limit}} }
+]