@carllee1983/dbcli 1.10.1 → 1.17.0

package/CHANGELOG.md

@@ -5,6 +5,131 @@ All notable changes to dbcli are documented here.
 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.17.0] - 2026-05-10
+
+### Added
+
+- `dbcli recover` top-level command. Without `--apply`, prints the auto-saved last envelope (Markdown by default, JSON with `--format json`); with `--apply`, executes the recovery plan under risk gating.
+- `--apply` runs `tier=readonly` and `tier=dry-run` steps by default (tier is determined by the code-owned allowlist, not the envelope). Open the gate one tier with `--allow-write=readonly-cmd` (local-side writes) or `--allow-write=write-cmd` (database writes).
+- `--from <path>` overrides the auto-saved envelope and accepts either a raw `RecoveryEnvelope` or a `SavedRecoveryEnvelope` wrapper.
+- Auto-write `.dbcli/last-recovery.json` on every `--recovery` failure across `query`, `q`, `insert`, `update`, `delete`, `export`, `schema`, and `inspect`. Atomic write; SQL text and sensitive flag values are redacted in the saved `command` summary.
+- New optional `GuideStep` fields: `interactive`, `dbWrite`, `placeholders` (additive — no `schemaVersion` bump).
+- Per-`error.code` argv allowlist enforced before any child-process execution; hand-authored envelopes cannot escalate beyond the steps dbcli already knows how to run.
+- Strict zod-based schema validation for envelopes from `--from <file>` and `.dbcli/last-recovery.json`. Missing `recovery`, missing `error.code`, malformed step shape, or wrong `schemaVersion` all surface as exit code 2 with a structured reason instead of crashing.
+- Exit-code matrix for `dbcli recover --apply`: `0` ok, `1` failed, `2` envelope missing/malformed, `3` skipped-only.
+- `RecoveryEnvelope.verify?: GuideStep` — optional read-only verifier appended by `classifyError()` per recovery code (additive, no `schemaVersion` bump).
+- `dbcli recover --apply` now runs the verifier after the main plan when `finalStatus === 'ok'`. Output gains `verifyResult` and `verifyStatus` (`passed | failed | indeterminate`). `--no-verify` opts out.
+- `--no-verify` flag on `dbcli recover --apply`.
+- `BLACKLIST_COLUMN_WRITE` allowlist now permits `dbcli inspect --for-agent` (used as the verifier).
+- `dbcli recover --next --after-step <n> --result <json|@file>` — multi-turn protocol that returns one deterministic step at a time, given the result of the previous step. Output is a `NextResult` envelope with `kind: 'step' | 'done'`, `cursor`, `totalSteps`, and (when stepping) the next `GuideStep`.
+- `--next` is mutually exclusive with `--apply`; `--result` accepts inline JSON or `@<path>` (file ≤ 64 KB; `stdoutSummary`/`stderrSummary` ≤ 4 KB each).
+- New `nextStepFromEnvelope` pure function and `StepResultSummary` / `NextResult` types in `src/core/recovery/next-step.ts` + `next-types.ts`. v1 walks the plan linearly; the function signature reserves `prevResult` for future per-code branching without breaking callers.
+
+### Changed
+
+- `dbcli recover --apply` defaults to `--format json` for machine-readability; `dbcli recover` (no `--apply`) keeps `--format markdown` as the default. Either default can be overridden explicitly.
+- `dbcli init` and `dbcli init --force` recovery steps are now marked `interactive: true`; `--apply` skips them with `skipped:interactive`.
+- Recovery steps that fall back to placeholder tokens (`<table>`, `<hint>`, `<snippet>`, `<name>`, `<value>`) now declare those tokens in `placeholders`; `--apply` skips them with `skipped:placeholder`.
+- `dbcli use <connection>` recovery step is now `risk: 'write'` with `dbWrite: false` — selecting a connection rewrites the active-connection field in config.
+
+### Security
+
+- **Trust boundary on `--apply`**: envelope `risk`, `dbWrite`, and `interactive` fields are no longer authoritative for execution decisions. The gate derives the canonical execution tier (`readonly` / `dry-run` / `local-write` / `db-write` / `interactive`) from the per-`error.code` allowlist. A hand-crafted envelope claiming `risk: 'readonly'` for `dbcli delete users --where id=1` is still classified as `db-write` and skipped under the default tier. Falsified `interactive: false` on `dbcli init` is still skipped because the allowlist marks it `interactive`.
+- `insert` / `update` / `delete` / `q` are tier `dry-run` only when argv contains `--dry-run`; otherwise they are tier `db-write`.
+- Auto-saved envelope source now also rejects (exit 2) when `saved.cwd` no longer exists on disk, matching the existing `--from` saved-envelope behavior.
+
+### Internal
+
+- New modules under `src/core/recovery/`: `apply-types`, `apply-shell`, `apply-allowlist`, `apply-gate`, `apply-exec`, `apply`, `apply-render-json`, `apply-render-markdown`, `last-envelope`, `envelope-schema`.
+- `apply-allowlist` exposes `classifyArgvForCode(argv, code)` returning `{ kind, tier }` so the gate can decide tier without trusting envelope hints. `isAllowedForCode` is preserved as a boolean wrapper.
+- Test seam `__setExecutorForTests` allows unit tests to swap the child-process executor without spawning real processes.
+
+## [1.16.0] - 2026-05-09
+
+### Added
+
+- `dbcli insert --recovery`, `dbcli update --recovery`, `dbcli delete --recovery`, `dbcli export --recovery`, `dbcli schema --recovery`, `dbcli inspect --recovery` — same opt-in envelope behavior as v1.15.0's `query --recovery` / `q --recovery`. On failure, a `RecoveryEnvelope` JSON is written to stdout, the human stderr message is suppressed, and the process exits non-zero. Without `--recovery`, the existing per-command error behavior is preserved byte-for-byte.
+- `dbcli inspect --require-schema-cache` — flag that throws `SCHEMA_CACHE_MISSING` (recovery code) when the active SQL connection has no usable schema cache. Combine with `--recovery` to get a structured envelope. Together with the v1.15.0 `recovery` module this gives the `SCHEMA_CACHE_MISSING` classifier path end-to-end coverage from a real CLI surface.
+- New `dry-run` recovery steps prepended to `BLACKLIST_COLUMN_WRITE` and `PERMISSION_DENIED` envelopes when the failing operation was a write (`INSERT` / `UPDATE` / `DELETE`). Agents now get a `dbcli <verb> <table> --dry-run` suggestion as the first step before the existing inventory / inspect / init steps.
+
+### Notes
+
+- `RecoveryEnvelope` shape, `RECOVERY_SCHEMA_VERSION`, and the 14 recovery codes are unchanged from v1.15.0. The new `RecoveryContext.writeOperation` field is optional and additive.
+- Other commands (`q` was already covered in v1.15.0; `report`, `guide`, `recovery`, `doctor`, `migrate`, `init`, `use`, etc.) keep their existing error behavior.
+- No new runtime dependencies. The classifier and step library remain pure functions.
+
+## [1.15.0] - 2026-05-09
+
+### Added
+
+- `dbcli recovery` — machine-readable error envelope with deterministic recovery commands. Standalone lookup mode: `dbcli recovery --code <CODE>` synthesizes an envelope for any of 14 recovery codes (`CONFIG_MISSING`, `CONN_REFUSED`, `CONN_AUTH_FAILED`, `CONN_TIMEOUT`, `CONN_HOST_NOT_FOUND`, `CONN_UNKNOWN`, `PERMISSION_DENIED`, `BLACKLIST_TABLE`, `BLACKLIST_COLUMN_WRITE`, `SNIPPET_NOT_FOUND`, `SNIPPET_AMBIGUOUS`, `SNIPPET_PARAM_MISSING`, `SCHEMA_CACHE_MISSING`, `UNKNOWN`). Supports `--format json|markdown`, `--list`, `--brief`, `--for-agent`, plus placeholder bindings (`--hint`, `--snippet`, `--table`).
+- `dbcli query --recovery` and `dbcli q --recovery` — opt-in flag that, on failure, emits a `RecoveryEnvelope` JSON to stdout (suppressing the usual human stderr message) and exits non-zero. Existing behavior without the flag is unchanged.
+- `RecoveryEnvelope` schema (`schemaVersion: 1`) reuses the v1.14.0 `GuideStep` shape and is the first surface to emit `risk: 'dry-run'` and `risk: 'write'` recovery steps.
+
+### Notes
+
+- v1.15.0 wires `--recovery` into `query` and `q` only. Other commands (`insert`, `update`, `delete`, `export`) preserve their current error behavior; broader integration is planned for v1.16+.
+- Recovery is reactive (responds to a thrown error) while `dbcli guide` is proactive (chooses next steps before any failure). They share the `GuideStep` contract via `src/core/guide/types.ts`.
+- No new runtime dependencies. Classifier and step library are pure functions.
+
+## [1.14.0] - 2026-05-09
+
+### Added
+
+- `dbcli guide <goal>` — deterministic next-command planner for a fixed list of database goals (`slow-query`, `capacity`, `health`, `index-usage`, `permissions`, `schema-overview`). Reuses `dbcli inspect` context cache-first; pass `--probe` to refresh via a live probe. Each step carries `risk: 'readonly'` (forward-compatible with v1.15.0 recovery) plus `rationale` and `expects` (trimmed by `--brief` / `--for-agent`). Supports `--format json|markdown`, `--list`.
+- Goal-list view: `dbcli guide --list` returns all available goals with one-line descriptions.
+
+### Notes
+
+- Guide does not execute any commands; it only plans them. All v1.14.0 plans are read-only by construction.
+- MongoDB connections still produce a useful plan (anchor + `queries suggest` + `doctor`) even though no built-in mongo diagnostic snippets exist yet.
+- Coexists with `dbcli skill tasks plan` (template-driven). Guide is taxonomy-driven from the static goal map.
+
+## [1.13.0] - 2026-05-09
+
+### Added
+
+- `dbcli report` — Markdown / JSON diagnostic report built on top of v1.12.0 inspect collectors. Reuses connection / permission / blacklist / snippet inventory context; runs curated read-only built-in `@diag/*` snippets grouped into `health` / `capacity` / `perf` sections; per-snippet timeout (default 3000 ms) and per-evidence row cap (default 50). Supports `--format json|markdown`, `--section <list>`, `--brief`, `--for-agent`, `--no-connect`.
+
+### Notes
+
+- MongoDB connections emit a context-only report (no built-in mongo snippets in v1.13.0).
+- No new built-in snippets in this release; report uses the v1.11 `@diag/*` inventory.
+
+## [1.12.0] - 2026-05-08
+
+### Added
+
+- `dbcli inspect` — read-only context snapshot for AI agents (`--format json|markdown`, `--brief`, `--for-agent`, `--no-connect`, `--probe-timeout`).
+- `src/core/inspect/` collector layer (connection, permission, blacklist, objects, schema-cache, snippets, version, suggested commands) reused via the orchestrator.
+- `release:check` script — sequences `bun audit`, format check, typecheck, lint, tests, build, and dist smoke.
+
+### Changed
+
+- `assets/SKILL.md` agent workflow now starts with `dbcli inspect --for-agent`.
+- `README.md` quick-start documents the agent first-look command.
+
+### Notes
+
+- Snapshot output is locked at `schemaVersion: 1`. Non-SQL engines emit `objects` and `schemaCache` as `unavailable: true` until later milestones.
+- No new runtime dependencies.
+
+## [1.11.0] - 2026-05-08
+
+### Added
+
+- `dbcli queries search <keywords>` — fuzzy keyword search across saved queries.
+- `dbcli queries suggest <intent>` — intent-prefix suggestion.
+- Optional `intent` frontmatter field on snippets.
+- 9 new diagnostic snippets: ES x4 (hot-threads, index-stats, unassigned-shards, pending-tasks); Redis x4 (slowlog, client-list, memory-usage, cluster-info); SQL x1 (blocking-queries.postgres).
+- "When you don't know which query to run" section in SKILL.md.
+
+### Changed
+
+- All 18 existing built-in diagnostic snippets backfilled with `intent`.
+- `foldVariants` extracted from `src/commands/queries.ts` to `src/core/saved-queries/fold.ts`.
+- Redis read-only allowlist gained `CLIENT`, `INFO`, `CLUSTER`, `SLOWLOG` for diagnostic snippets.
+
 ## [1.10.1] - 2026-05-08
 
 ### Fixed

package/README.md

@@ -97,6 +97,81 @@ dbcli migrate create posts --column "id:serial:pk" --column "title:varchar(200):
 dbcli skill --install claude
 ```
 
+### Agent first-look
+
+```bash
+dbcli inspect --for-agent
+```
+
+A single read-only command that returns a bounded JSON snapshot of the current
+connection, permission level, blacklist size, schema cache freshness, available
+saved-query intents, and the safest next commands to run. No host, no port, no
+credentials — safe to log or pipe to an LLM.
+
+### Diagnostic report
+
+```bash
+dbcli report --format json
+```
+
+Builds on `inspect` to also run curated read-only built-in `@diag/*` snippets
+grouped into `health` / `capacity` / `perf` sections. Bounded by per-snippet
+timeout and per-evidence row cap. Use `--format markdown` for human reading,
+`--section health,capacity` to scope, or `--for-agent` for compact JSON.
+
+### Guide
+
+```bash
+dbcli guide slow-query --format json
+```
+
+Deterministic next-command planner. Pick a goal (`slow-query`, `capacity`,
+`health`, `index-usage`, `permissions`, `schema-overview`) and `dbcli guide`
+emits an ordered plan that combines `dbcli inspect`, engine-appropriate
+`@diag/*` snippets, and `dbcli queries suggest` / `dbcli doctor` follow-ups.
+The planner is cache-first (no network); add `--probe` to refresh the
+underlying inspect context. Use `--list` to see all goals,
+`--format markdown` for human reading, or `--for-agent` for compact JSON.
+
+### Recovery & Guided Remediation
+
+```bash
+# Lookup recovery commands for a code
+dbcli recovery --code CONN_REFUSED --format json
+
+# Execute a failing command with recovery opt-in
+dbcli query "SELECT 1" --recovery
+
+# (v1.17.0+) Inspect or apply the last saved recovery plan
+dbcli recover                       # View last plan (Markdown)
+dbcli recover --apply               # Execute safe steps (readonly/dry-run)
+dbcli recover --apply --allow-write=readonly-cmd  # Allow local writes
+dbcli recover --apply --allow-write=write-cmd     # Allow database writes
+
+# (v1.17.0+) Multi-turn recovery (for AI agents)
+dbcli recover --next --after-step 1 --result '{"status":"ok"}'
+```
+
+Machine-readable error envelope with guided remediation. As of v1.16.0 every
+first-party command accepts the `--recovery` flag. In v1.17.0, the `recover`
+command was added to automate the execution of these plans.
+
+- **Risk Gating:** `--apply` is safe-by-default, running only `readonly` and
+  `dry-run` steps. Elevated tiers require `--allow-write`.
+- **Verification:** After a successful `--apply`, dbcli automatically runs a
+  verification step to confirm the fix actually worked.
+- **Multi-turn Protocol:** The `--next` flag allows agents to advance recovery
+  one step at a time, providing the result of the previous step to enable
+  deterministic branching.
+
+`dbcli inspect --require-schema-cache` throws `SCHEMA_CACHE_MISSING` when the
+active SQL connection has no usable schema cache; combine with `--recovery`
+to receive the structured envelope.
+
+For write commands (`insert` / `update` / `delete`), `BLACKLIST_COLUMN_WRITE`
+and `PERMISSION_DENIED` envelopes lead with a `risk: 'dry-run'` step
+that suggests previewing the SQL with `--dry-run` before re-attempting.
+
 ### MongoDB Atlas / SRV Connections
 
 MongoDB connections are supported via both standard `mongodb://` URIs and Atlas-style `mongodb+srv://` URIs.

package/README.zh-TW.md

@@ -72,30 +72,34 @@ bun run src/cli.ts -- --help
 
 若 `dbcli` 未在 `PATH` 中，請使用 `bun run src/cli.ts <子指令> ...`（與 `bun run dev -- <子指令> ...` 相同）。
 
-### 第一步
+### 復原與引導式修復 (Recovery & Guided Remediation)
 
 ```bash
-# 以資料庫連線初始化專案
-dbcli init
+# 查詢特定代碼的復原指令
+dbcli recovery --code CONN_REFUSED --format json
 
-# 具備自動補全功能的互動式 Shell
-dbcli shell
+# 執行指令並在失敗時啟用復原信封
+dbcli query "SELECT 1" --recovery
 
-# 列出可用資料表
-dbcli list
+# (v1.17.0+) 檢視或執行最後一次儲存的復原計畫
+dbcli recover                       # 檢視最後一個計畫 (Markdown)
+dbcli recover --apply               # 執行安全步驟 (readonly/dry-run)
+dbcli recover --apply --allow-write=readonly-cmd  # 允許本機端寫入
+dbcli recover --apply --allow-write=write-cmd     # 允許資料庫端寫入
 
-# 檢視資料表結構
-dbcli schema users
+# (v1.17.0+) 多輪對話復原協定 (供 AI 代理使用)
+dbcli recover --next --after-step 1 --result '{"status":"ok"}'
+```
 
-# 查詢資料
-dbcli query "SELECT * FROM users"
+具備引導修復能力的機器可讀錯誤信封。自 v1.16.0 起，所有核心指令皆支援 `--recovery` 旗標。在 v1.17.0 中，新增了 `recover` 指令來自動化執行這些計畫。
 
-# 預覽結構變更（DDL，預設 dry-run；實際套用請加 --execute）
-dbcli migrate create posts --column "id:serial:pk" --column "title:varchar(200):not-null"
+- **風險門控 (Risk Gating)：** `--apply` 預設為安全優先，僅執行 `readonly` 與 `dry-run` 步驟。較高風險的操作需透過 `--allow-write` 授權。
+- **自動驗證：** 當 `--apply` 執行成功後，dbcli 會自動執行一個驗證步驟 (verify) 以確認修復是否生效。
+- **多輪對話協定：** `--next` 旗標允許 Agent 逐步執行復原，並提供上一步的執行結果，以實現決定性的分支邏輯。
 
-# 產生 AI 代理 skill
-dbcli skill --install claude
-```
+`dbcli inspect --require-schema-cache` 會在 SQL 連線缺少可用快取時拋出 `SCHEMA_CACHE_MISSING`；配合 `--recovery` 可取得結構化信封。
+
+針對寫入指令 (`insert` / `update` / `delete`)，`BLACKLIST_COLUMN_WRITE` 與 `PERMISSION_DENIED` 信封會優先提供 `risk: 'dry-run'` 步驟，建議在重試前先以 `--dry-run` 預覽 SQL。
 
 ### MongoDB Atlas / SRV 連線
 

package/assets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dbcli
-description: Database CLI for AI agents with permission-based access control. Use to set up new connections, query, inspect schemas, insert/update/delete, export results, and blacklist sensitive columns/tables. Supports MySQL, PostgreSQL, MariaDB, MongoDB, Redis, and Elasticsearch with multiple named connections per project and custom env files. Trigger when configuring a database connection (`.dbcli` / `.env`), choosing between v1 single and v2 multi-connection layouts, picking auth modes (URI, env refs, Cloud ID, API key), running SQL / MongoDB JSON / Redis commands / Elasticsearch DSL, exploring table/collection/key/index structures, switching database environments, or protecting sensitive data from AI access. For exhaustive flags and examples, read the sibling `reference.md`.
+description: Database CLI for AI agents with permission-based access control. Use to set up new connections, query, inspect schemas, insert/update/delete, export results, and blacklist sensitive columns/tables. Supports MySQL, PostgreSQL, MariaDB, MongoDB, Redis, and Elasticsearch with multiple named connections per project and custom env files. Trigger when configuring a database connection (`.dbcli` / `.env`), choosing between v1 single and v2 multi-connection layouts, picking auth modes (URI, env refs, Cloud ID, API key), running SQL / MongoDB JSON / Redis commands / Elasticsearch DSL, exploring table/collection/key/index structures, switching database environments, protecting sensitive data from AI access, or performing automated recovery and guided remediation after command failures. For exhaustive flags and examples, read the sibling `reference.md`.
 ---
 
 # dbcli
@@ -9,11 +9,44 @@ Database CLI for AI agents with permission-based access control.
 
 ## AI agent workflow (follow in order)
 
-1. `dbcli status` — permission level and system summary (no credentials).
-2. `dbcli blacklist list` — sensitive data boundaries.
-3. `dbcli schema <table> --format json` — real column names (SQL/Mongo/ES) or `schema <key>` (Redis). **Never guess.**
-4. Run `query` / `insert` / `update` / `delete` / `export` within permission.
-5. All writes: `--dry-run` (SQL/Mongo) → run → `query` read-back to confirm.
+1. `dbcli inspect --for-agent` — bounded snapshot: connection, permission, blacklist, objects, snippets, suggested next commands.
+2. `dbcli report --format json` — diagnostic report (health/capacity/perf) using built-in snippets.
+3. `dbcli guide <goal> --format json` — deterministic next-command plan for a fixed goal (`slow-query`, `capacity`, `health`, `index-usage`, `permissions`, `schema-overview`). Use `dbcli guide --list` to see goals.
+4. `dbcli recovery --code <CODE>` — look up structured recovery commands for a known error code (e.g. `CONN_REFUSED`, `PERMISSION_DENIED`, `SNIPPET_NOT_FOUND`). Pass `--recovery` to `dbcli query` / `dbcli q` to have failures emit a `RecoveryEnvelope` directly. In v1.16.0 the `--recovery` flag is also accepted by `dbcli insert`, `dbcli update`, `dbcli delete`, `dbcli export`, `dbcli schema`, and `dbcli inspect` (which also gained `--require-schema-cache` for the `SCHEMA_CACHE_MISSING` path).
+   - **v1.17.0** `dbcli recover` reads the auto-saved envelope (`.dbcli/last-recovery.json`) written by any prior `--recovery` failure. Inspect it (Markdown by default) or pass `--apply` to execute the saved plan under risk gating.
+   - **v1.17.0** `dbcli recover --apply` runs `risk=readonly` and `risk=dry-run` steps by default. Open the gate one tier with `--allow-write=readonly-cmd` (run local-side writes such as `blacklist remove`) or `--allow-write=write-cmd` (also run steps that mutate the connected database). Pass `--from <file>` to read an explicit envelope instead of the auto-saved one. Use `--format json` for an aggregated machine-readable result.
+   - Exit codes: `0` ok, `1` step failed, `2` envelope missing/malformed, `3` every step skipped (open `--allow-write` or fix interactive/placeholder).
+   - GuideStep optional fields agents should respect:
+     - `interactive: true` — step requires a TTY (`dbcli init` family). `dbcli recover --apply` skips with `skipped:interactive`.
+     - `dbWrite: true` — step mutates the connected database. Gates the highest risk tier; reserved for future write-side recovery steps.
+     - `placeholders: ['<token>', ...]` — agent must replace these tokens before `--apply` will execute. Skipped with `skipped:placeholder`.
+   - **v1.17.0 P4 Verification.** After `--apply` finishes the main plan, dbcli runs **one extra read-only step** (`envelope.verify`) to probe whether the original failure is gone. The output gains `verifyResult` (the executed step) and `verifyStatus`:
+     - `passed` — verifier exited 0 and (where applicable) the expected JSON shape was found.
+     - `failed` — verifier exited non-zero or timed out.
+     - `indeterminate` — verifier exited 0 but the heuristic could not confirm the fix (JSON parse failure, missing field, gate skip).
+     Verify is **only run when** `finalStatus === 'ok'`. Pass `--no-verify` to skip it. Heuristic is intentionally cheap; agents should still re-run their own check against the original failing operation when correctness matters.
+   - **v1.17.0 P2 Multi-turn `--next`.** When `--apply` is too coarse — interactive blocks it, the plan needs per-step inspection, or the agent wants to drive recovery with its own tools — execute steps one at a time and ask dbcli for the next:
+
+     ```bash
+     # The agent reads step 1 from the envelope, runs it, then asks dbcli for step 2:
+     dbcli recover --next --after-step 1 --result '{"status":"ok","exitCode":0}'
+     # Returns a NextResult envelope:
+     # {
+     #   "schemaVersion": 1,
+     #   "kind": "step",
+     #   "errorCode": "BLACKLIST_TABLE",
+     #   "cursor": 2,
+     #   "totalSteps": 3,
+     #   "step": { "order": 2, "command": "dbcli inspect --for-agent", ... }
+     # }
+     # After the last step, dbcli returns kind: "done".
+     ```
+
+     `--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.
+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.
+8. All writes: `--dry-run` (SQL/Mongo) → run → `query` read-back to confirm.
 
 Prefer `--format json` for agent-friendly output.
 
@@ -154,22 +187,32 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `init` | n/a | Create `.dbcli` (v1 single or v2 multi via `--conn-name` / `--env-file`). **Usually run by the human** — do NOT re-run to strip `{"$env"}` references; that format is intentional. |
 | `use` | n/a | Show/switch default named connection (v2 only). |
 | `list` | query-only+ | Tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch). |
-| `schema` | query-only+ | SQL: per-table or full scan into `.dbcli/schemas/`. MongoDB: sampled. ES: flattened mapping. Redis: per-key only (type/TTL/size). |
-| `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). |
-| `insert` / `update` | read-write+ | SQL or MongoDB only. JSON `--data` / `--set`; `--where` required on `update`; `--dry-run` first. Redis writes go through `query`. |
-| `delete` | data-admin+ | SQL or MongoDB only. `--where` required; `--dry-run` first. |
-| `export` | query-only+ | SQL or MongoDB only. Query → CSV/JSON(L) file or stdout. |
+| `schema` | query-only+ | SQL: per-table or full scan into `.dbcli/schemas/`. MongoDB: sampled. ES: flattened mapping. Redis: per-key only (type/TTL/size). Supports `--recovery`. |
+| `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). Supports `--recovery`. |
+| `plan` | n/a | Static SQL risk analyzer (`--format text\|json`); classifies a statement without connecting to the database. |
+| `q` | query-only+ | Run a saved snippet by `@name` with `--param k=v`. SQL / Elasticsearch DSL / read-only Redis bodies; blacklist enforced. Supports `--recovery`. |
+| `queries` | n/a | Manage saved snippets: `list` / `show` / `search` / `suggest` / `new` / `edit` / `check` / `delete` / `rename` / `copy` / `import` / `export`. |
+| `insert` / `update` | read-write+ | SQL or MongoDB only. JSON `--data` / `--set`; `--where` required on `update`; `--dry-run` first. Redis writes go through `query`. Supports `--recovery`. |
+| `delete` | data-admin+ | SQL or MongoDB only. `--where` required; `--dry-run` first. Supports `--recovery`. |
+| `export` | query-only+ | SQL or MongoDB only. Query → CSV/JSON(L) file or stdout. Supports `--recovery`. |
 | `blacklist` | n/a | `list` / `table` / `column` subcommands redact sensitive data from query results. |
 | `check` | query-only+ | SQL only (best on MySQL/MariaDB). |
 | `diff` | query-only+ | SQL only. Save/compare schema snapshots. |
 | `status` | query-only+ | Safe JSON/text summary (no credentials). |
+| `inspect` | query-only+ | Read-only context snapshot (connection, permission, blacklist, objects, snippets, suggested commands). `--for-agent` / `--no-connect` / `--require-schema-cache`. Supports `--recovery`. |
+| `report` | query-only+ | Diagnostic report (health / capacity / perf) built from `@diag/*` snippets. `--section`, `--brief`, `--for-agent`, `--no-connect`. |
+| `guide` | query-only+ | Deterministic next-command plan for a fixed goal (`slow-query`, `capacity`, `health`, `index-usage`, `permissions`, `schema-overview`). `--list` to enumerate. |
+| `recovery` | n/a | Look up the structured `RecoveryEnvelope` for a known error code (`--code <CODE>` or `--list`). Standalone synthesizer; does not require a real failure. |
+| `recover` | n/a | Inspect (default) or `--apply` the auto-saved recovery plan in `.dbcli/last-recovery.json`. `--allow-write=readonly-cmd\|write-cmd`, `--no-verify`, `--from <file>`, `--next --after-step <n> --result <json\|@file>` for multi-turn step-at-a-time. |
 | `doctor` | n/a | Environment, config, connection, SRV diagnostics (Mongo), schema cache age. |
 | `completion` | n/a | bash / zsh / fish scripts. |
 | `upgrade` | n/a | Self-update from npm; 24h-cached version hints on every command. |
 | `shell` | (same as query+) | Interactive REPL. SQL engines + MongoDB shell only. |
+| `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|copilot\|cursor>`); `skill tasks list/show/plan` for Agent Task Packs. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 `--use <name>` on any subcommand targets a v2 connection without changing the default.
+`--recovery` is honoured by `query`, `q`, `insert`, `update`, `delete`, `export`, `schema`, and `inspect`; on failure these emit a `RecoveryEnvelope` JSON to stdout, suppress the human stderr message, and atomically save the envelope to `.dbcli/last-recovery.json` for `dbcli recover` to consume.
 
 ## Permission levels
 
@@ -224,6 +267,14 @@ Run reusable parameterised SELECT snippets stored in your repo.
 | 2. Inspect | `dbcli queries show @<name>` |
 | 3. Run     | `dbcli q @<name> --param k=v` |
 
+### When you don't know which query to run
+
+1. `dbcli queries search <keywords>` — natural keywords, fuzzy ranked
+2. `dbcli queries suggest <intent>` — browse a category
+   Common intents: perf.slow-query, perf.cache-hit, capacity.size,
+                   safety.connections, monitor.cluster-health
+3. Once you find one: `dbcli q @<name>` (blacklist always enforced)
+
 Snippets resolve from three layers, **local > shared > builtin** (local wins):
 - `builtin` — bundled with dbcli (e.g. `@diag/*`); read-only at runtime
 - `.dbcli-shared/queries/` — committed, team-shared