@carllee1983/dbcli 1.20.1 → 1.23.1

package/CHANGELOG.md

@@ -5,6 +5,108 @@ 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).
 
+## [Unreleased]
+
+## [1.23.1] - 2026-05-29 - Skill Docs Sync
+
+### Changed
+
+- 補齊 `assets/SKILL.md` 與 `assets/reference.md`,涵蓋 v1.22(Redis `redis.mask` 遮罩、Elasticsearch export/shell)與 v1.23(`explain`、`guide missing-index-for`、`inspect` 情境感知 `suggestedCommands` + `hints`、內建 task pack `analyze-table-perf`)的指令與旗標說明,使 `dbcli skill --install` 產出的文件與實際行為一致
+
+## [1.23.0] - 2026-05-29 - Source-Driven Performance Review Tooling
+
+### Added
+
+- **`dbcli explain` 一級指令。** 把 `EXPLAIN` / `ANALYZE SELECT` / `EXPLAIN (ANALYZE, BUFFERS) SELECT` 包成統一介面,單條 query、`@saved-query`、`@file.sql`、`@glob/*` 通吃。輸出統一的 `ExplainRow` schema,附 5 條 actionable annotations(`full-scan` / `temp-table` / `filesort` / `cost-estimate-skew` / `nested-loop-large`)。輸出格式 markdown(預設)/ json / table。支援 `--bulk` 多筆批次。MariaDB + MySQL + PostgreSQL。(v1.23 P2)
+- **`dbcli guide missing-index-for` 單條 query 複合索引顧問。** 解析一條 `SELECT`,結合真實 `EXPLAIN` 計畫與既有索引,輸出帶 `confidence`(high/medium/low)與 `reason` 的索引候選;偵測既有索引碰撞(single-col 可擴成 composite),並把函式/運算式欄位與無法解析的 SQL 列為 `warnings`。輸出格式 yaml(預設)/ json / markdown,支援 `--min-confidence` 過濾。唯讀(僅 EXPLAIN + 索引內省)。(v1.23 P3)
+- **`dbcli inspect` 情境感知 `suggestedCommands` 與新的 `hints` 欄位。** `suggestedCommands` 改為三層加權(bootstrap / context-aware / discovery):collector 讀近 10 條 audit 找出最熱門資料表,有 task pack 時自動建議 `skill tasks plan analyze-table-perf --param table=<table>` 與 `skill tasks list`。新增與 `suggestedCommands` 平行的 `hints` 欄位(JSON 機器可讀 + markdown `## Hints`),提示最熱門資料表、可用 task pack 數量與 schema 快取概況。新增內建 task pack `analyze-table-perf`(唯讀 `plan-only`,吃必填 `table` 參數)。audit 讀取唯讀且永不 throw。(v1.23 P4)
+
+### Fixed
+
+- query-only 模式不再對 `SHOW`/`DESCRIBE`/`EXPLAIN`/`ANALYZE SELECT` 注入 `LIMIT`,避免 server 拒絕(v1.23 P1, issue #1)
+- MariaDB `ANALYZE SELECT` 與 PostgreSQL `EXPLAIN (ANALYZE, BUFFERS) SELECT` 視為 read-only,query-only 模式可執行(v1.23 P1, issue #2)
+- driver 在 execute 階段丟出的 SQL 錯誤(語法錯、table 不存在、column 不存在)不再被誤包成 `Connection failed`;訊息附 actionable hints 與 fuzzy table 候選(v1.23 P1, issue #3)
+- `dbcli schema --refresh` 首次 bootstrap 不再要求 `--force`(v1.23 P1, issue #7)
+- query-only 模式拒絕未知 SQL 時的訊息明確化:加入當前 permission level 與 issue 連結
+
+### Changed
+
+- `ConnectionError.code` union 新增 `SQL_SYNTAX_ERROR` / `TABLE_NOT_FOUND` / `COLUMN_NOT_FOUND`(向後相容;既有 consumer 只匹配 `UNKNOWN` 仍 fallback)
+
+## [1.22.0] - 2026-05-21 - Elasticsearch Shell/Export + Redis Masking
+
+### Added
+
+- **Elasticsearch interactive shell.** `dbcli shell` 對 ES 連線開啟 Kibana Dev Tools 風格 REPL:輸入請求行 `<METHOD> /<path>` 加上可選的多行 JSON body,以空白行送出整個區塊,回應以美化 JSON 呈現。以讀取為主 — index 層級黑名單於前端直接拒絕受保護 index;`_search` 若 body 未指定 `size` 自動上限 1000 筆。(P1)
+- **Elasticsearch export.** `dbcli export` 對 ES 連線支援兩種形式:傳入 search DSL 並以 `--index` 指定索引以匯出命中結果,或直接以 index 名稱當作查詢、透過 `match_all` + scroll 匯出整個索引。輸出 JSON / JSONL / CSV,預設上限 1000 筆(`--no-limit` 匯出全索引,以 scroll 分批串流)。匯出前套用索引層級黑名單檢查,並寫入稽核紀錄。(P2)
+- **Redis value / hash-field 遮罩。** 新增 `.dbcli` `redis.mask` 設定區塊:key 命中 `keyPattern` glob 者,其值(或指定的 hash `fields`)於讀取時(`GET`、`GETRANGE`、`HGETALL`、`HGET`、`HMGET`、`HVALS`)回傳 `[REDACTED]`。遮罩與既有 key-glob 拒絕黑名單並存,且**拒絕一律優先於遮罩**。(P3)
+
+### Fixed
+
+- **Redis shell 單行指令路由。** 在 `dbcli shell` 對 Redis 連線輸入不帶結尾 `;` 的單行指令(`GET mykey`、`SCAN 0`、`HGETALL h`)現可正確執行,修正先前被誤判為未知 dbcli 指令的路由瑕疵。SQL 的分號 / 多行語意不變。(P4)
+
+### Changed
+
+- `src/adapters/capabilities.ts`:ES `export` 由 unsupported 改為 limited(readonly);Redis `blacklist` note 補上 value/hash-field 遮罩;Redis `shell` 單行說明修正。
+
+### Docs
+
+- 雙語 user docs(`docs/user/en` / `docs/user/zh-TW`,md + html)新增 ES shell、ES export、Redis 遮罩段落;`docs/feature-matrix.md` 同步 ES export 與 Redis blacklist 儲存格。
+
+## [1.21.0] - 2026-05-20 - Redis-Parity Pack
+
+### Added
+
+- **Redis shell.** `dbcli shell` 現對 Redis 連線開啟互動式 REPL,具備歷史、readline、tab 補全(指令 + key 前綴)與 `.no-limit on/off` meta 指令。單行語意。
+- **Redis size guard.** `SCAN` / `HSCAN` / `SSCAN` / `ZSCAN` 在缺少時補上 `COUNT 1000`;`LRANGE` / `ZRANGE` / `ZREVRANGE` 夾限 `stop`;`ZRANGEBYSCORE` 補上 `LIMIT 0 1000`。`HGETALL` / `HKEYS` / `HVALS` / `SMEMBERS` / `KEYS` 的無上限回覆在 client 端截斷至 1000 並帶 `REDIS_SIZE_TRUNCATE` 警告。`--no-limit` 略過所有防護。
+- **Redis blacklist 強制。** `dbcli blacklist add 'pattern'` 現會封鎖 key 命中的 Redis 讀寫。採 Redis 原生 glob(`*`、`?`、`[abc]`、`[a-z]`)。與黑名單重疊的 `KEYS` / `SCAN MATCH` 會被拒絕;未重疊的掃描則濾掉黑名單 keys 並帶 `REDIS_BLACKLIST_FILTERED` 警告。稽核記錄含 `metadata.rejection_reason: 'blacklist'` 與 `matched_pattern`。
+
+### Changed
+
+- `ExecutionResult.warnings` 現為公開型別的一部分(optional),目前僅由 Redis 發出。
+- `src/adapters/capabilities.ts` Redis row 更新:`shell` → `interactive`、`query auto-limit` → `limited`、`blacklist` → `limited`。
+
+### Out of scope
+
+- Elasticsearch shell、Redis/ES export、Redis value/hash-field 遮罩 — 延後至 v1.22 或之後。
+
+## [1.20.2] - 2026-05-19
+
+### Added
+
+- **MongoDB MVP 全套支援。** `q` 指令現以 limited-supported 等級納入 MongoDB（`find` / `aggregate` 兩種 snippet body），路由經過專屬分支與 field-masker；`schema` 採 `$sample` + 遞迴 path 偵測（含 BSON 型別），新增 `--sample-method` 旗標；`query` / `export` 套用 `maskMongoRows` 對巢狀結構遞迴遮罩。
+- **MongoDB blacklist 強化。** 新增 path-matcher（exact / dotted / suffix-wildcard）、field-masker 遞迴遮罩、insert / update 在寫入前強制套用 nested-path blacklist；`blacklist list` 對 collection 上的 middle-`*` pattern 發出警告。
+- **MongoDB 安全模型升級。** update operator 從硬性 allowlist 改為分級安全（tiered operator safety）；schema 對 blacklist 欄位直接 redact；`cache` / `doctor` 暴露 `sampleMethod`。
+- **MongoDB snippets 一級公民化。** 內建 reference snippets（find + aggregate）、`queries list/search/suggest` 將 MongoDB snippets 與 SQL 引擎並列；`mongoStrategy` 驗證 body 與 params 並支援 map 形式插值。
+- **Recovery — per-code branching for connection codes (MVP)。** `recover --next` 對 connection 類錯誤碼支援多 branch 派發：新增 `buildConnectionBranches` factory（4 個 connection branch）、`matchConnectionBranch` resolver、`classify` emit `branches` / `branchFork`，並提供 `--branch <id>` 旗標讓 agent 顯式選擇 branch。輸出 `NextResult.branchId` 與 markdown 中的 branchId/description 一併呈現。
+
+### Changed
+
+- **MongoDB `q` 文件升級。** `docs/feature-matrix.md` / 雙語 user docs 將 MongoDB `q` 從 unsupported 改為 limited supported（記載目前支援的 body 形式與限制）。
+- **Recovery schema 新增 `branches` / `branchFork`。** 行為向下相容（無 branch 時與舊版一致）；`GuideStep` / `NextResult` / `NextStepOutput` 全鏈打通 `branchId`；`shellQuote` 抽離為共用模組。
+
+### Security
+
+- **Pin `brace-expansion ^5.0.6`** 修補 GHSA-jxxr-4gwj-5jf2 ReDoS。
+
+### Tests
+
+- `tests/integration/` — MongoDB tier、blacklist、sampling、snippet 整合覆蓋。
+- 新增 mongo plan + schema envelope shape 的 contract test。
+- Recovery: doctor↔resolver keyword coupling contract test、connection envelope 6 變體 snapshot、`recover` E2E branching（fork / walk / fallback / `--apply` 不變）覆蓋。
+
+### Docs
+
+- 雙語 user docs 新增 Agent 修復工作流段落（精簡 walkthrough）與 Recovery Cookbook。
+- `assets/SKILL.md` / `assets/reference.md` 補 `--branch` 旗標與 `NextResult.branchId` 說明、MongoDB tier / operator / blacklist / sampling 行為。
+- 統一 npm 套件名為 `@carllee1983/dbcli`；關閉 v1.20.0 Phase 23-04 已知限制段落。
+- `.planning/PROJECT.md` 同步：`bun test`、已 ship 項目移出 OOS。
+
+### Internal
+
+- `style: [recovery] format with prettier (printWidth 100)` / `style: [mongo] format with prettier (printWidth 100)` — 全面套用 prettier `printWidth 100`。
+- `fix: [test] remove this alias in mongo sampling mock` — 修正 eslint `no-this-alias`。
+- `refactor: [snippets] register mongo as a first-class engine family` / `refactor: [recovery] extract shellQuote to a shared module`。
 
 ## [1.20.1] - 2026-05-18
 
@@ -420,6 +522,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Stable Release
 
 dbcli v1.0.0 is the first stable release. All three milestones are complete:
+
 - **M1 (v0.6.0):** Smart REPL — interactive shell with SQL + dbcli commands
 - **M2 (v0.8.0):** Schema DDL — CREATE/DROP/ALTER TABLE, INDEX, CONSTRAINT, ENUM
 - **M3 (v1.0.0):** Stabilization — documentation, permission matrix, known limitations update
@@ -586,6 +689,7 @@ Added table and column-level blacklisting to protect sensitive data from AI agen
 ### Configuration
 
 Blacklist rules stored in `.dbcli`:
+
 ```json
 {
   "blacklist": {

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/README.zh-TW.md

@@ -1177,11 +1177,14 @@ Redaction 沿用 v1.19.1 agent-facing JSON 合約的同一來源
 `recover --apply` 的 JSON 輸出會內嵌 `audit_recent: AuditEntryBrief[]`（最近 5 筆），
 讓新 session 立即擁有歷史脈絡。
 
-**已知限制（v1.20.0）：** Bi-directional 連結僅在 `query` / `inspect` / diagnostic
-表面寫入；DML 指令 `insert / update / delete / export / q / schema` 失敗時
-emit 的 envelope 暫未含 `audit_ref`，追蹤於 Phase 23-04 follow-up。完整對照表見
+**完整雙向覆蓋（v1.20.1+）：** Recovery ↔ audit linkage 已在每一個
+`--recovery`-capable 指令落地 — `query`、`inspect`、`insert`、`update`、`delete`、
+`export`、`q`、`schema` 皆 wired。失敗路徑上，audit entry 的 `recovery_ref` 與
+envelope 的 `audit_ref` 互帶相同 UUID；agent 可從 envelope（`.dbcli/last-recovery.json`）
+透過 `dbcli audit tail --recovery-ref <id>` 跳到對應的 audit entry，或反向以
+`dbcli audit show --recovery-ref <id>` 從 audit 找回 envelope。v1.20.0 在 6 個
+DML/DDL 指令上的部分覆蓋缺口已於 v1.20.1 結清，完整對照表見
 [`.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)。
-Recovery envelope 自身的 linkage 不受影響。
 
 進階 agent 工作流程（session handoff、forensics walk-through）詳見
 [`assets/SKILL.md`](./assets/SKILL.md) §Audit Log usage（英文）或

package/assets/SKILL.md

@@ -9,6 +9,7 @@ Database CLI for AI agents with permission-based access control.
 
 ## AI agent workflow (follow in order)
 
+0. `dbcli skill context --format xml` — LLM prompt context payload: serializes connection metadata, schema caches, and saved queries into a compressed XML/JSON structure for prompt injection.
 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.
@@ -43,10 +44,13 @@ 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.
 8. All writes: `--dry-run` (SQL/Mongo) → run → `query` read-back to confirm.
+   - **v1.21.0 Self-Verification Loops**: If a snippet defines a `verify` block in its frontmatter, run the snippet with `dbcli q @name --verify` to automatically run primary changes, execute the verification query, and validate assertions.
 
 Prefer `--format json` for agent-friendly output.
 
@@ -66,6 +70,12 @@ The plan output is an ordered list of dbcli commands with rationale and risk
 labels. Execute them one at a time — task plans do **not** override blacklist,
 schema, dry-run, or confirmation requirements.
 
+Builtin packs: `diagnose-slow-query` and **(v1.23)** `analyze-table-perf` — a
+read-only `plan-only` pack taking a required `table` parameter that walks
+`blacklist list` → `schema <table> --format json` → `guide index-usage`. `dbcli
+inspect` suggests `analyze-table-perf` automatically for the hottest table in
+recent audit activity.
+
 Tasks live under `assets/tasks/` (builtin), `.dbcli-shared/tasks/` (shared), and
 `.dbcli/tasks/` (local override).
 
@@ -108,6 +118,9 @@ 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
 
@@ -227,26 +240,27 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `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). Supports `--recovery`. |
 | `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). `--format table\|json\|csv\|html`, `--ui` to open the interactive dashboard in a browser. Supports `--recovery`. |
+| `explain` | query-only+ | **(v1.23)** Read-only query plan with annotations. SQL only. Single query, `@saved-query`, `@file.sql`, or `--bulk @glob/*`. `--analyze` (EXPLAIN ANALYZE / MariaDB ANALYZE SELECT), `--format markdown\|json\|table`. |
 | `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. `--format table\|json\|csv\|html`, `--ui` to open the interactive dashboard. Supports `--recovery`. |
+| `q` | query-only+ | Run a saved snippet by `@name` with `--param k=v`. Supports `--verify` to run assertions. |
 | `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 → `--format json\|jsonl\|csv\|html` file or stdout. `html` emits a standalone interactive dashboard. Supports `--recovery`. |
+| `export` | query-only+ | SQL, MongoDB, or **(v1.22)** Elasticsearch (DSL `--index` or whole-index scroll). Query → `--format json\|jsonl\|csv\|html` file or stdout. `html` emits a standalone interactive dashboard. 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`. |
+| `inspect` | query-only+ | Read-only context snapshot (connection, permission, blacklist, objects, snippets, context-aware `suggestedCommands`, and **(v1.23)** human-readable `hints`). `--for-agent` / `--brief` / `--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. |
+| `guide` | query-only+ | Deterministic next-command plan for a fixed goal (`slow-query`, `capacity`, `health`, `index-usage`, `permissions`, `schema-overview`). `--list` to enumerate. **(v1.23)** `guide missing-index-for <query>` suggests composite indexes for a single SELECT (`--format yaml\|json\|markdown`, `--min-confidence`). |
 | `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. |
+| `shell` | (same as query+) | Interactive REPL. SQL engines, MongoDB, and Redis (single-line; `.no-limit on/off`). **(v1.22)** Elasticsearch opens a Kibana Dev Tools-style REPL (`<METHOD> /<path>` + optional JSON body, blank line submits). |
+| `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|copilot\|cursor>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for LLM prompt context payload. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 `--use <name>` on any subcommand targets a v2 connection without changing the default.
@@ -270,27 +284,36 @@ 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
 
 - Command-style execution; `query` runs a whitelisted Redis command (e.g. `GET`, `HSET`, `DEL`).
-- **Supported:** `init`, `list` (keys via SCAN), `schema <key>` (type / TTL / size / sample), `query`, `status`, `use`, `doctor`, `upgrade`, `completion`.
+- **Supported:** `init`, `list` (keys via SCAN), `schema <key>` (type / TTL / size / sample), `query`, `shell`, `status`, `use`, `doctor`, `upgrade`, `completion`.
 - **Not supported:** `schema` full scan, `insert`, `update`, `delete`, `export`, `check`, `diff`, `migrate`, `q`.
   Use `query "DEL <key>"` etc. for writes — they go through the same permission gate.
 - Permission tiers map to commands: read commands → `query-only`; mutators (`SET`, `HSET`, ...) → `read-write`; `DEL` / `UNLINK` → `data-admin`.
 - `database` field is the logical DB index (default `0`); `list` returns ≤ 100 000 keys via SCAN.
+- **Size guard:** `SCAN`/`HSCAN`/`SSCAN`/`ZSCAN` inject `COUNT 1000`; `LRANGE`/`ZRANGE` clamp `stop`; `ZRANGEBYSCORE` injects `LIMIT 0 1000`; `HGETALL`/`HKEYS`/`HVALS`/`SMEMBERS`/`KEYS` truncate at 1000. Results carry `warnings[]` (`REDIS_SIZE_REWRITE` / `REDIS_SIZE_TRUNCATE`). Pass `--no-limit` (CLI) or `.no-limit on` (shell) to bypass.
+- **Blacklist:** `dbcli blacklist add 'secrets:*'` registers a Redis-native key glob. Reads/writes whose keys match are rejected (`BlacklistRejection`, audited with `metadata.matched_pattern`); `KEYS`/`SCAN MATCH` overlapping a rule are rejected; non-overlapping listings filter blacklisted keys.
+- **Masking (v1.22):** add a `redis.mask` block to `.dbcli` — keys matching a `keyPattern` glob have their value (or named hash `fields`) returned as `[REDACTED]` on reads (`GET`, `GETRANGE`, `HGETALL`, `HGET`, `HMGET`, `HVALS`). Masking coexists with key-glob rejection, and **rejection always wins over masking**.
+- **Shell:** `dbcli shell` on a Redis connection opens a single-line REPL (history, tab completion of commands + key prefixes, `.no-limit on/off`).
 - See reference.md Redis section.
 
 ## Elasticsearch
 
 - DSL (JSON body) or Lucene query string; `--collection <index>` is required on `query`.
-- **Supported:** `init`, `list` (indices with doc count), `schema [index]` (flattened mapping), `query`, `status`, `use`, `doctor`, `upgrade`, `completion`.
-- **Not supported:** `insert`, `update`, `delete`, `export`, `check`, `diff`, `migrate`, `q`.
+- **Supported:** `init`, `list` (indices with doc count), `schema [index]` (flattened mapping), `query`, `export` (v1.22), `shell` (v1.22), `status`, `use`, `doctor`, `upgrade`, `completion`.
+- **Not supported:** `insert`, `update`, `delete`, `check`, `diff`, `migrate`, `q`.
   Writes are not exposed via dedicated subcommands yet — use `query` if the cluster allows or external tools.
+- **Export (v1.22):** `dbcli export` takes a search DSL with `--index <index>` to export hits, or an index name as the query to scroll the whole index via `match_all`. Outputs JSON / JSONL / CSV (default 1000 rows; `--no-limit` scrolls the full index in batches). Index-level blacklist + audit apply.
+- **Shell (v1.22):** `dbcli shell` opens a Kibana Dev Tools-style REPL — request line `<METHOD> /<path>` plus an optional multi-line JSON body, submitted with a blank line; index-level blacklist rejects protected indices and `_search` auto-caps at 1000 when `size` is omitted.
 - Query-only mode caps at 1000 hits; `--no-limit` is bounded at 10 000.
 - Schema flattens nested fields (`a.b.c`) and surfaces `.fields` multi-fields.
 - See reference.md Elasticsearch section.

package/assets/SKILL.zh-TW.md

@@ -11,6 +11,7 @@ description: 為 AI 代理設計、具權限控管的資料庫 CLI。可用於
 
 ## AI 代理工作流程(依序執行)
 
+0. `dbcli skill context --format xml` — LLM 提示詞脈絡載荷：將連線中介資料、Schema 快取和已儲存查詢序列化為高度壓縮的 XML/JSON 結構以進行 Prompt 注入。
 1. `dbcli inspect --for-agent` — 有界快照:連線、權限、blacklist、物件、snippets、建議的下一個指令。
 2. `dbcli report --format json` — 使用內建 snippets 產出診斷報告(health / capacity / perf)。
 3. `dbcli guide <goal> --format json` — 針對固定目標產出確定性的下一步指令計畫(`slow-query`、`capacity`、`health`、`index-usage`、`permissions`、`schema-overview`)。執行 `dbcli guide --list` 查看所有目標。
@@ -45,10 +46,13 @@ 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`。
 8. 所有寫入:`--dry-run`(SQL / Mongo)→ 實際執行 → `query` 回讀確認。
+   - **v1.21.0 自我驗證循環（Self-Verification Loops）**：如果 snippet 在其 frontmatter 中定義了 `verify` 區塊，使用 `dbcli q @name --verify` 來執行該 snippet，即可自動跑完主要變更、執行驗證查詢並驗證斷言。
 
 代理友善的輸出請優先用 `--format json`。
 
@@ -89,9 +93,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)(安裝時與本檔放在一起)。
 
@@ -197,7 +201,7 @@ dbcli init --use-env-refs \
 | `schema` | query-only+ | SQL:單表或全掃描存入 `.dbcli/schemas/`。MongoDB:sampled。ES:flattened mapping。Redis:僅單一 key(type / TTL / size)。支援 `--recovery`。 |
 | `query` | query-only+ | SQL、Mongo JSON(`--collection`)、Redis 指令、ES DSL / Lucene(`--collection`)。`--format table\|json\|csv\|html`、`--ui` 開啟瀏覽器互動式 dashboard。支援 `--recovery`。 |
 | `plan` | n/a | 靜態 SQL 風險分析器(`--format text\|json`);不連線即可分類語句。 |
-| `q` | query-only+ | 以 `@name` 執行已儲存 snippet,搭配 `--param k=v`。支援 SQL / Elasticsearch DSL / 唯讀 Redis 內容;blacklist 強制套用。`--format table\|json\|csv\|html`、`--ui` 開啟互動式 dashboard。支援 `--recovery`。 |
+| `q` | query-only+ | 以 `@name` 執行已儲存 snippet，搭配 `--param k=v`。支援 `--verify` 以執行斷言。 |
 | `queries` | n/a | 管理已儲存 snippet:`list` / `show` / `search` / `suggest` / `new` / `edit` / `check` / `delete` / `rename` / `copy` / `import` / `export`。 |
 | `insert` / `update` | read-write+ | 僅 SQL 與 MongoDB。JSON `--data` / `--set`;`update` 必填 `--where`;先 `--dry-run`。Redis 寫入透過 `query`。支援 `--recovery`。 |
 | `delete` | data-admin+ | 僅 SQL 與 MongoDB。必填 `--where`;先 `--dry-run`。支援 `--recovery`。 |
@@ -214,8 +218,8 @@ dbcli init --use-env-refs \
 | `doctor` | n/a | 環境、設定、連線、SRV 診斷(Mongo)、schema cache 年齡。 |
 | `completion` | n/a | bash / zsh / fish 腳本。 |
 | `upgrade` | n/a | 從 npm 自我更新;每個指令都帶 24h 快取的版本提示。 |
-| `shell` | (與 query 同) | 互動式 REPL。僅支援 SQL 引擎與 MongoDB shell。 |
-| `skill` | n/a | 產出 / 安裝 AI skill 文件(`--install <claude\|gemini\|copilot\|cursor>`);`skill tasks list/show/plan` 提供 Agent Task Packs。 |
+| `shell` | (與 query 同) | 互動式 REPL。支援 SQL 引擎、MongoDB 與 Redis(單行;`.no-limit on/off`)。 |
+| `skill` | n/a | 產出 / 安裝 AI skill 文件（`--install <claude\|gemini\|copilot\|cursor>`）；`skill tasks list/show/plan` 提供 Agent Task Packs；`skill context` 提供 LLM 提示詞脈絡載荷。 |
 | `migrate` | admin | 僅 SQL。**DDL;預設 dry-run** — 需 `--execute` 才會真的執行。 |
 
 任何子指令上的 `--use <name>` 都會把目標切到對應的 v2 連線,但不改變預設值。
@@ -239,19 +243,25 @@ 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
 
 - 指令式執行;`query` 跑白名單內的 Redis 指令(例如 `GET`、`HSET`、`DEL`)。
-- **支援:** `init`、`list`(透過 SCAN 列 keys)、`schema <key>`(type / TTL / size / sample)、`query`、`status`、`use`、`doctor`、`upgrade`、`completion`。
+- **支援:** `init`、`list`(透過 SCAN 列 keys)、`schema <key>`(type / TTL / size / sample)、`query`、`shell`、`status`、`use`、`doctor`、`upgrade`、`completion`。
 - **不支援:** `schema` 全掃描、`insert`、`update`、`delete`、`export`、`check`、`diff`、`migrate`、`q`。
   寫入請走 `query "DEL <key>"` 等 — 同樣經過權限門檻。
 - 權限分層對應指令:讀取類 → `query-only`;mutator(`SET`、`HSET`、...)→ `read-write`;`DEL` / `UNLINK` → `data-admin`。
 - `database` 欄位是 logical DB index(預設 `0`);`list` 透過 SCAN 最多回傳 100 000 個 keys。
+- **大小防護(size guard):** `SCAN`/`HSCAN`/`SSCAN`/`ZSCAN` 自動補上 `COUNT 1000`;`LRANGE`/`ZRANGE` 夾限 `stop`;`ZRANGEBYSCORE` 補上 `LIMIT 0 1000`;`HGETALL`/`HKEYS`/`HVALS`/`SMEMBERS`/`KEYS` 在 1000 筆截斷。結果帶有 `warnings[]`(`REDIS_SIZE_REWRITE` / `REDIS_SIZE_TRUNCATE`)。以 `--no-limit`(CLI)或 `.no-limit on`(shell)略過。
+- **黑名單:** `dbcli blacklist add 'secrets:*'` 註冊 Redis 原生 key glob。命中規則的讀寫會被拒絕(`BlacklistRejection`,稽核記錄含 `metadata.matched_pattern`);與規則重疊的 `KEYS`/`SCAN MATCH` 會被拒絕;未重疊的列舉會濾掉黑名單 keys。
+- **Shell:** Redis 連線執行 `dbcli shell` 會開啟單行 REPL(歷史、指令與 key 前綴 tab 補全、`.no-limit on/off`)。
 - 詳見 reference.md Redis 段落。
 
 ## Elasticsearch