@carllee1983/dbcli 1.39.1 → 1.41.0

package/assets/SKILL.md

@@ -18,7 +18,16 @@ the CLI package has not been installed globally.
 
 1. `dbcli blacklist list` — confirm sensitive-data boundaries.
 2. `dbcli schema <object> --format json` — confirm real column/field names. **Never guess.**
-3. All writes: `--dry-run` (SQL/Mongo) → run → `query` read-back to confirm.
+3. All writes: `--dry-run` (SQL/Mongo) → run → `query` read-back to confirm. Redis
+   `query` has **no `--dry-run`** (see **Redis**); Elasticsearch is **read-only**.
+
+**`update` / `delete` `--where` is equality-only (SQL).** It accepts **only** `col=val` or
+`col1=v1 AND col2=v2`. A comparison / pattern operator (`>`, `>=`, `<`, `!=`, `LIKE`, `IN`)
+is a **parse error**; worse, `OR` is **silently swallowed into the value** — `a=1 OR b=2`
+parses as `a = "1 OR b=2"` and matches the wrong rows (or none). For a range or compound
+condition, first `query` / `export` the target rows' primary keys, then run one
+`update` / `delete --where "id=<pk>"` per key — or escalate to a human. (MongoDB `--where`
+takes a full JSON filter and is exempt.)
 
 > `report` and `guide` already embed an `inspect` snapshot — you do **not** need to run
 > `dbcli inspect` first. Run `dbcli inspect --for-agent` manually only when you want the
@@ -36,7 +45,7 @@ the CLI package has not been installed globally.
 
 Slow-query diagnosis has three canonical paths (pick by what you already know):
 
-- Known slow SQL → `skill tasks plan diagnose-slow-query --param query="<SQL>"` → `guide missing-index-for "<SQL>"`
+- Known slow SQL → `skill tasks plan diagnose-slow-query --param query="<SQL>"` → `lint "<SQL>"` → `guide missing-index-for "<SQL>"`
 - Known hot table → `skill tasks plan analyze-table-perf --param table=<table>`
 - Whole-environment scan → `report --section perf` → `guide slow-query`
 
@@ -45,7 +54,7 @@ afterwards add only the `@diag/*` it does not cover (`missing-indexes`, `locks`,
 `table-sizes`). Once you have a specific slow statement, `explain --analyze "<SQL>"` shows its plan.
 
 **On failure:** pass `--recovery` to `query` / `q` / `insert` / `update` / `delete` /
-`export` / `schema` / `inspect`. The command emits a `RecoveryEnvelope` to stdout and saves
+`export` / `schema` / `inspect` / `lint` / `diff --against-orm`. The command emits a `RecoveryEnvelope` to stdout and saves
 it to `.dbcli/last-recovery.json`; then `dbcli recover` inspects it and `dbcli recover --apply`
 runs the saved plan under risk gating. Multi-turn `--next`, connection branching, and the
 post-apply verify probe are documented in reference.md §Recovery Cookbook.
@@ -72,12 +81,16 @@ The plan is an ordered list of dbcli commands with rationale and risk labels. Ex
 one at a time — task plans do **not** override blacklist, schema, dry-run, or confirmation
 requirements.
 
-Builtin packs: `diagnose-slow-query` (targets a specific SQL), `analyze-table-perf` (targets
-a specific table; `dbcli inspect` auto-suggests it for the hottest table in recent audit
-activity), `audit-permissions`, `safe-backfill`, `schema-drift-review`, `connection-health`.
-Review/verify packs: `pr-database-review`, `migration-review`, `safe-backfill-verify`,
-`slow-endpoint-investigation`. All are read-only `plan-only` — pick the pack matching the
-situation, and run any index/DDL proposal through `migration-review` before writing.
+Builtin packs (SQL — postgres/mysql): `diagnose-slow-query` (targets a specific SQL),
+`analyze-table-perf` (targets a specific table; `dbcli inspect` auto-suggests it for the
+hottest table in recent audit activity), `audit-permissions`, `safe-backfill`,
+`schema-drift-review`, `orm-drift-review` (ORM definition vs cached DB schema),
+`connection-health`. Review/verify packs: `pr-database-review`,
+`migration-review`, `safe-backfill-verify`, `slow-endpoint-investigation`. MongoDB packs:
+`mongo-safe-backfill` (dry-run–previewed backfill), `mongo-schema-drift-review` (sampled
+dot-path drift). All are read-only `plan-only` — pick the pack matching the situation, and
+run any index/DDL proposal through `migration-review` before writing. Redis/Elasticsearch
+have no packs yet — lead with `guide` / `report` there.
 
 Tasks live under `assets/tasks/` (builtin), `.dbcli-shared/tasks/` (shared), and
 `.dbcli/tasks/` (local override).
@@ -92,9 +105,9 @@ in **How to use dbcli** still applies.
 | DB-backed feature | `blacklist list` → `schema <object>` → `queries suggest <intent>` |
 | DB report / dashboard request | `blacklist list` → `queries search <keywords>` / `queries suggest <intent>` → `queries show @<name>` → `q @<name> --ui` or `--format html` |
 | Application data bug | `audit tail --for-agent --n 10` → `blacklist list` → `schema <object>` → narrow query |
-| ORM or migration work | `schema --format json` → `diff --snapshot <name>` → `migrate add-index`/`add-column` (preview SQL) → `diff --against <snapshot>` |
+| ORM or migration work | `schema --format json` → `diff --against-orm <orm-schema>` → review error-level drift → proposals via `migrate` (dry-run) → `migration-review` task pack → `diff --against <snapshot>` after applying. |
 | PR database review | Review changed persistence paths, then propose concrete `schema` / `plan` / `dry-run` / `report` / `guide` commands per material claim. |
-| Slow endpoint or query | `report --section perf` → task pack `analyze-table-perf` → `guide missing-index-for "<query>"`; use `proxy analyze` when logs exist. |
+| Slow endpoint or query | `report --section perf` → task pack `analyze-table-perf` → `lint "<query>"` → `guide missing-index-for "<query>"`; use `proxy analyze` when logs exist. |
 | Safe data backfill | `blacklist list` → `schema <object>` → count/scope query → `update … --dry-run` → read-back or snippet `--verify`. |
 | Environment validation | `status --format json` → `doctor --format json` → `inspect --for-agent --no-connect`. |
 
@@ -112,9 +125,13 @@ dbcli q @<name> --param k=v --format html > report.html
 dbcli export "<SQL>" --format html --output report.html
 dbcli audit tail --for-agent --n 10
 dbcli diff --snapshot <name>
+dbcli diff --against-orm prisma/schema.prisma --format json
+dbcli diff --against-orm "migrations/*.sql" --format markdown
+dbcli skill tasks plan orm-drift-review --param orm_path=prisma/schema.prisma --format json
 dbcli report --section perf --format json
 dbcli skill tasks plan analyze-table-perf --param table=<table> --format json
 dbcli guide missing-index-for "<query>" --format json
+dbcli lint "<SQL>" --format json
 dbcli update <object> --where "<bounded predicate>" --set '<json>' --dry-run --format json
 dbcli inspect --for-agent --no-connect --format json
 ```
@@ -281,6 +298,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `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`. |
+| `lint` | n/a | Static SQL anti-pattern advisor (no DB connection). 9 rules incl. schema-aware implicit-cast / NOT IN-nullable checks via the layered `.dbcli/schemas/` cache; global `--use <conn>` selects a named cache. Findings carry rewrite drafts + guarded `explain` verify commands (`--analyze` only for proven read-only SQL) — report-only, never executes. `--format text\|json\|markdown`, `--min-severity`, `--no-schema`, `--bulk`. 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`. Supports `--verify` to run assertions. |
 | `queries` | n/a | Manage saved snippets: `list` / `show` / `search` / `suggest` / `new` / `edit` / `check` / `delete` / `rename` / `copy` / `import` / `export`. |
@@ -289,7 +307,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `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. |
+| `diff` | query-only+ | SQL only. Save/compare schema snapshots. **(P1b)** `--against-orm <path>` compares a Prisma schema / DDL file / normalized JSON against the local schema cache (no DB connection): categorized drift (`missing_in_db` = error, `missing_in_orm` = warn, `mismatch` per tolerance table, `unmanaged`) with dry-run `migrate` proposals; exit 1 on error-level drift. `--orm-format prisma\|ddl\|json`, `--ignore <globs>`, `--format json\|table\|markdown`. |
 | `snapshot` | query-only+ | **(v1.25)** SQL only. Capture a result fingerprint (`rowCount` + per-column null/distinct/min/max/sum + order-independent checksum). `--out` (default `.dbcli/snapshots/snap-<ts>.json`), `--rows`, `--stdout`, `--format`, `--no-limit`. Baseline for `assert --against`. |
 | `assert` | query-only+ | **(v1.25)** SQL only. Verify an invariant; exit 1 on failure unless `--no-fail`. `--expect "rows>0\|value==X\|col:c not null\|unique\|between a and b\|>= n"`, `--vs <query> --compare rows\|value` (reconcile), `--against <snapshot> --tolerance <pct>`. |
 | `verification` | n/a | Inspect and manage local verification artifacts. `list` / `show <id-or-path>` / `summary` are read-only; `prune` is dry-run by default and deletes only with `--execute --force`. Reads `<cwd>/.dbcli/verification/`; no DB connection, no audit writes. |
@@ -309,7 +327,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 
 `--use <name>` on any subcommand (including `status` / `doctor`) targets a v2 connection
 without changing the default. `--recovery` is honoured by `query`, `q`, `insert`, `update`,
-`delete`, `export`, `schema`, and `inspect` (see **On failure** above).
+`delete`, `export`, `schema`, `inspect`, `lint`, and `diff --against-orm` (see **On failure** above).
 
 **Write & query flag semantics** (SQL/Mongo `insert`/`update`):
 
@@ -364,12 +382,18 @@ without changing the default. `--recovery` is honoured by `query`, `q`, `insert`
   → `data-admin`. A command not in the whitelist is refused.
 - **No `--dry-run` for Redis `query`** — write safety comes from the permission gate and key
   blacklist (matching reads/writes are rejected). To preview a delete, use `delete <key> --dry-run`.
-- `database` is the logical DB index (default `0`). `dbcli blacklist add 'secrets:*'`
+- `database` is the logical DB index (default `0`). `dbcli blacklist table add 'secrets:*'`
   registers a key glob; an optional `redis.mask` block masks values on read. Size guards
   (SCAN/HGETALL truncation, `--no-limit` to bypass) and masking details: reference.md Redis section.
 
 ## Elasticsearch
 
+**dbcli is read-only against Elasticsearch — `insert` / `update` / `delete` are not supported.**
+
+```bash
+dbcli query '{"query":{"match":{"status":"active"}}}' --collection orders
+```
+
 - `query` takes a DSL (JSON body) or Lucene query string; `--collection <index>` is required.
 - **Supported:** `init`, `list` (indices with doc count), `schema [index]` (flattened mapping),
   `query`, `export` (v1.22), `shell` (v1.22), `status`, `use`, `doctor`. **Not supported:**

package/assets/SKILL.zh-TW.md

@@ -15,7 +15,16 @@ description: Database CLI for AI agents with permission-based access control. Us
 
 1. `dbcli blacklist list` — 確認敏感資料邊界。
 2. `dbcli schema <object> --format json` — 確認真實欄位名稱。**禁止猜測。**
-3. 所有寫入：`--dry-run`（SQL / Mongo）→ 實際執行 → `query` 回讀確認。
+3. 所有寫入：`--dry-run`（SQL / Mongo）→ 實際執行 → `query` 回讀確認。Redis 的 `query`
+   **沒有 `--dry-run`**（見 **Redis** 節）；Elasticsearch 為**唯讀**。
+
+**`update` / `delete` 的 `--where` 僅支援等式（SQL）。** 只接受 `col=val` 或
+`col1=v1 AND col2=v2`。比較 / 模式運算子（`>`、`>=`、`<`、`!=`、`LIKE`、`IN`）會直接
+**報錯**；更危險的是，`OR` 會被**靜默當成值的一部分** — `a=1 OR b=2` 會被解析成
+`a = "1 OR b=2"`，比對到錯誤的列（或完全比對不到）。需要範圍或複合條件時，先用
+`query` / `export` 撈出目標列的主鍵，再對每個主鍵執行一次
+`update` / `delete --where "id=<pk>"`（逐一等式）— 或升級交給人類處理。（MongoDB 的
+`--where` 接受完整 JSON filter，不受此限。）
 
 > `report` 與 `guide` 已內嵌 `inspect` 快照 — **不需要**先跑 `dbcli inspect`。只有在需要 audit-recent 脈絡或診斷連線問題時，才手動跑 `dbcli inspect --for-agent`。
 
@@ -31,13 +40,13 @@ description: Database CLI for AI agents with permission-based access control. Us
 
 慢查詢診斷有三條標準路徑（依已掌握的資訊選擇）：
 
-- 已知慢 SQL → `skill tasks plan diagnose-slow-query --param query="<SQL>"` → `guide missing-index-for "<SQL>"`
+- 已知慢 SQL → `skill tasks plan diagnose-slow-query --param query="<SQL>"` → `lint "<SQL>"` → `guide missing-index-for "<SQL>"`
 - 已知熱點資料表 → `skill tasks plan analyze-table-perf --param table=<table>`
 - 全環境掃描 → `report --section perf` → `guide slow-query`
 
 `report --section perf` 已涵蓋 slow-query、index-usage 與 cache-hit 診斷 — 之後只需補上它未涵蓋的 `@diag/*`（`missing-indexes`、`locks`、`connections`、`table-sizes`）。一旦鎖定特定慢語句，`explain --analyze "<SQL>"` 可顯示執行計畫。
 
-**失敗時：** 在 `query` / `q` / `insert` / `update` / `delete` / `export` / `schema` / `inspect` 加上 `--recovery`。指令會把 `RecoveryEnvelope` 輸出到 stdout 並儲存到 `.dbcli/last-recovery.json`；然後用 `dbcli recover` 檢視、`dbcli recover --apply` 在風險門控下執行儲存的計畫。Multi-turn `--next`、連線分支與 post-apply 驗證探針詳見 reference.md §Recovery Cookbook。
+**失敗時：** 在 `query` / `q` / `insert` / `update` / `delete` / `export` / `schema` / `inspect` / `lint` / `diff --against-orm` 加上 `--recovery`。指令會把 `RecoveryEnvelope` 輸出到 stdout 並儲存到 `.dbcli/last-recovery.json`；然後用 `dbcli recover` 檢視、`dbcli recover --apply` 在風險門控下執行儲存的計畫。Multi-turn `--next`、連線分支與 post-apply 驗證探針詳見 reference.md §Recovery Cookbook。
 
 回報驗證結果時使用詞彙：`verified`（證據符合）/ `not_verified`（驗證執行但結果矛盾）/ `indeterminate`（執行但證據不明確）/ `blocked`（因 config、權限、schema、placeholder 或安全閘門導致無法執行）。
 
@@ -55,7 +64,7 @@ dbcli skill tasks plan <task> --param key=value --format json     # generate pla
 
 計畫輸出是一組附帶說明與風險標籤的 dbcli 指令序列。請逐一執行 — 任務計畫**不會**繞過 blacklist、schema、dry-run 或確認等要求。
 
-內建套件：`diagnose-slow-query`（針對特定 SQL）、`analyze-table-perf`（針對特定資料表；`dbcli inspect` 會針對近期 audit 活動中最熱門的資料表自動建議此套件）、`audit-permissions`、`safe-backfill`、`schema-drift-review`、`connection-health`。審查與驗證套件：`pr-database-review`、`migration-review`、`safe-backfill-verify`、`slow-endpoint-investigation`。全部為唯讀 `plan-only` — 選擇符合使用者情境的套件，任何索引 / DDL 提案都應先經 `migration-review` 再寫入。
+內建套件（SQL — postgres/mysql）：`diagnose-slow-query`（針對特定 SQL）、`analyze-table-perf`（針對特定資料表；`dbcli inspect` 會針對近期 audit 活動中最熱門的資料表自動建議此套件）、`audit-permissions`、`safe-backfill`、`schema-drift-review`、`orm-drift-review`（ORM 定義與快取 DB schema 比對）、`connection-health`。審查與驗證套件：`pr-database-review`、`migration-review`、`safe-backfill-verify`、`slow-endpoint-investigation`。MongoDB 套件：`mongo-safe-backfill`（以 dry-run 預覽的回填）、`mongo-schema-drift-review`（抽樣 dot-path 漂移）。全部為唯讀 `plan-only` — 選擇符合使用者情境的套件，任何索引 / DDL 提案都應先經 `migration-review` 再寫入。Redis/Elasticsearch 目前尚無套件——請改以 `guide` / `report` 為主。
 
 任務檔放在 `assets/tasks/`（內建）、`.dbcli-shared/tasks/`（共享）與 `.dbcli/tasks/`（本地覆寫）。
 
@@ -68,9 +77,9 @@ dbcli skill tasks plan <task> --param key=value --format json     # generate pla
 | DB-backed 功能 | `blacklist list` → `schema <object>` → `queries suggest <intent>` |
 | DB report / dashboard request | `blacklist list` → `queries search <keywords>` / `queries suggest <intent>` → `queries show @<name>` → `q @<name> --ui` 或 `--format html` |
 | 應用程式資料錯誤 | `audit tail --for-agent --n 10` → `blacklist list` → `schema <object>` → 最小查詢 |
-| ORM 或 migration | `schema --format json` → `diff --snapshot <name>` → `migrate add-index`/`add-column`（預覽 SQL）→ `diff --against <snapshot>` |
+| ORM 或 migration | `schema --format json` → `diff --against-orm <orm-schema>` → 審查 error-level drift → 透過 `migrate` 取得提案（dry-run）→ `migration-review` task pack → 套用後執行 `diff --against <snapshot>`。 |
 | PR 資料庫風險審查 | 審查變更的 persistence path，並針對每個重要主張提出具體 `schema`、`plan`、`dry-run`、`report` 或 `guide` 指令。 |
-| 慢 endpoint 或查詢 | `report --section perf` → task pack `analyze-table-perf` → `guide missing-index-for "<query>"`；有 proxy log 時使用 `proxy analyze`。 |
+| 慢 endpoint 或查詢 | `report --section perf` → task pack `analyze-table-perf` → `lint "<query>"` → `guide missing-index-for "<query>"`；有 proxy log 時使用 `proxy analyze`。 |
 | 安全資料回填 | `blacklist list` → `schema <object>` → count/scope query → `update … --dry-run` → read-back 或 snippet `--verify`。 |
 | 環境設定驗證 | `status --format json` → `doctor --format json` → `inspect --for-agent --no-connect`。 |
 
@@ -86,9 +95,13 @@ dbcli q @<name> --param k=v --format html > report.html
 dbcli export "<SQL>" --format html --output report.html
 dbcli audit tail --for-agent --n 10
 dbcli diff --snapshot <name>
+dbcli diff --against-orm prisma/schema.prisma --format json
+dbcli diff --against-orm "migrations/*.sql" --format markdown
+dbcli skill tasks plan orm-drift-review --param orm_path=prisma/schema.prisma --format json
 dbcli report --section perf --format json
 dbcli skill tasks plan analyze-table-perf --param table=<table> --format json
 dbcli guide missing-index-for "<query>" --format json
+dbcli lint "<SQL>" --format json
 dbcli update <object> --where "<bounded predicate>" --set '<json>' --dry-run --format json
 dbcli inspect --for-agent --no-connect --format json
 ```
@@ -223,6 +236,7 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 | `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`。 |
 | `explain` | query-only+ | **(v1.23)** 唯讀查詢計畫並附註解。僅 SQL。單一查詢、`@saved-query`、`@file.sql` 或 `--bulk @glob/*`。`--analyze`（EXPLAIN ANALYZE / MariaDB ANALYZE SELECT）、`--format markdown\|json\|table`。 |
+| `lint` | n/a | 靜態 SQL 反模式顧問（不連線 DB）。共 9 條規則，包含透過分層 `.dbcli/schemas/` 快取進行的 schema-aware implicit-cast / NOT IN-nullable 檢查；全域 `--use <conn>` 會選擇命名連線的快取。Finding 可附 rewrite 草稿與受保護的 `explain` 驗證指令；只有已證明唯讀的 SQL 才會加上 `--analyze`，且只回報、絕不執行。`--format text\|json\|markdown`、`--min-severity`、`--no-schema`、`--bulk`。支援 `--recovery`。 |
 | `plan` | n/a | 靜態 SQL 風險分析器（`--format text\|json`）；不連線即可分類語句。 |
 | `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`。 |
@@ -231,7 +245,7 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 | `export` | query-only+ | SQL、MongoDB 或 **(v1.22)** Elasticsearch（DSL `--index` 或全 index scroll）。Query → `--format json\|jsonl\|csv\|html` 檔案或 stdout。`html` 輸出獨立可互動 dashboard。支援 `--recovery`。 |
 | `blacklist` | n/a | `list` / `table` / `column` 子指令，從查詢結果中遮蔽敏感資料。 |
 | `check` | query-only+ | 僅 SQL（在 MySQL / MariaDB 最佳）。 |
-| `diff` | query-only+ | 僅 SQL。儲存 / 比較 schema snapshot。 |
+| `diff` | query-only+ | 僅 SQL。儲存 / 比較 schema snapshot。**(P1b)** `--against-orm <path>` 會將 Prisma schema / DDL 檔 / normalized JSON 與本地 schema cache 比對（不連線 DB）：分類為 `missing_in_db`（error）、`missing_in_orm`（warn）、依 tolerance 表判定的 `mismatch`、以及 `unmanaged`，並提供 dry-run `migrate` 提案；出現 error-level drift 時 exit 1。`--orm-format prisma\|ddl\|json`、`--ignore <globs>`、`--format json\|table\|markdown`。 |
 | `snapshot` | query-only+ | **(v1.25)** 僅 SQL。擷取結果指紋（`rowCount` + 每欄 null/distinct/min/max/sum + 順序無關 checksum）。`--out`（預設 `.dbcli/snapshots/snap-<ts>.json`）、`--rows`、`--stdout`、`--format`、`--no-limit`。作為 `assert --against` 的基準。 |
 | `assert` | query-only+ | **(v1.25)** 僅 SQL。驗證不變量；失敗時 exit 1，除非 `--no-fail`。`--expect "rows>0\|value==X\|col:c not null\|unique\|between a and b\|>= n"`、`--vs <query> --compare rows\|value`（對帳）、`--against <snapshot> --tolerance <pct>`。 |
 | `verification` | n/a | 檢視與管理本機驗證 artifact。`list` / `show <id-or-path>` / `summary` 為唯讀；`prune` 預設 dry-run，僅在 `--execute --force` 時刪除。讀取 `<cwd>/.dbcli/verification/`；不需 DB 連線，不寫入 audit log。 |
@@ -249,7 +263,7 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 | `skill` | n/a | 產出 / 安裝 AI skill 文件（`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`）；`skill tasks list/show/plan` 提供 Agent Task Packs；`skill context` 提供 LLM 提示詞脈絡載荷（用於注入其他 LLM，正常操作不需要）。 |
 | `migrate` | admin | 僅 SQL。**DDL；預設 dry-run** — 需 `--execute`。 |
 
-任何子指令上的 `--use <name>` 可在不改變預設值的情況下，把目標切到 v2 連線。`--recovery` 被 `query`、`q`、`insert`、`update`、`delete`、`export`、`schema` 與 `inspect` 支援（見上方**失敗時**）。
+任何子指令上的 `--use <name>` 可在不改變預設值的情況下，把目標切到 v2 連線。`--recovery` 被 `query`、`q`、`insert`、`update`、`delete`、`export`、`schema`、`inspect`、`lint` 與 `diff --against-orm` 支援（見上方**失敗時**）。
 
 **寫入與查詢旗標語意**（SQL / Mongo `insert`/`update`）：
 
@@ -280,10 +294,16 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 - **支援：** `init`、`list`（透過 SCAN 列 keys）、`schema <key>`（type / TTL / size / sample）、`query`、`q`（saved snippet — **僅唯讀命令**）、`delete`（基本實作：`DEL` / `HDEL` / `LREM` / `SREM` / `ZREM`，需 `data-admin`；`query "DEL <key>"` 亦可）、`shell`、`status`、`use`、`doctor`。**不支援：** `schema` 全掃描、`insert`、`update`、`check`、`diff`、`migrate`。
 - **權限分層：** 讀取類（`GET`/`HGET`/`SCAN`/…）→ `query-only`；mutator（`SET`/`HSET`/`INCR`/`EXPIRE`/`SETEX`/`RENAME`/…）→ `read-write`；`DEL`/`UNLINK`/`HDEL`/`XDEL` → `data-admin`。白名單外的指令一律拒絕。
 - **Redis `query` 無 `--dry-run`** — 寫入安全來自權限門檻與 key 黑名單（命中的讀寫會被拒絕）。如需預覽刪除，請用 `delete <key> --dry-run`。
-- `database` 是 logical DB index（預設 `0`）。`dbcli blacklist add 'secrets:*'` 註冊 key glob；可選的 `redis.mask` 區塊在讀取時遮罩值。大小防護（SCAN/HGETALL 截斷，`--no-limit` 可略過）與遮罩細節：reference.md Redis 段落。
+- `database` 是 logical DB index（預設 `0`）。`dbcli blacklist table add 'secrets:*'` 註冊 key glob；可選的 `redis.mask` 區塊在讀取時遮罩值。大小防護（SCAN/HGETALL 截斷，`--no-limit` 可略過）與遮罩細節：reference.md Redis 段落。
 
 ## Elasticsearch
 
+**dbcli 對 Elasticsearch 為唯讀 — 不支援 `insert` / `update` / `delete`。**
+
+```bash
+dbcli query '{"query":{"match":{"status":"active"}}}' --collection orders
+```
+
 - `query` 接受 DSL（JSON body）或 Lucene query string；`--collection <index>` 為必填。
 - **支援：** `init`、`list`（含文件數的索引清單）、`schema [index]`（flattened mapping）、`query`、`export`（v1.22）、`shell`（v1.22）、`status`、`use`、`doctor`。**不支援：** `insert`、`update`、`delete`、`check`、`diff`、`migrate`。
 - `export` 接受含 `--index <index>` 的 search DSL，或以 index 名稱作為查詢來透過 `match_all` scroll 整個 index。Query-only 上限 1000 hits；`--no-limit` 放寬至 10,000。