@carllee1983/dbcli 1.39.1 → 1.39.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.37.1",
+  "version": "1.39.2",
   "description": "Database CLI skill and command reference for AI agents.",
   "author": {
     "name": "Carl Lee",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.37.1",
+  "version": "1.39.2",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/.cursor/rules/dbcli.mdc

@@ -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
@@ -364,12 +373,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/.cursor/skills/dbcli/reference.md

@@ -249,6 +249,7 @@ dbcli q @analytics/revenue --param days=30 --format html > report.html
 - `--dry-run` — print the bound SQL + values without executing
 - `--use <name>` — pick a v2 named connection
 - `--recovery` — emit a `RecoveryEnvelope` on failure (see `recover`)
+- `--verify` — run the snippet's verification assertions after execution (only if the snippet defines them)
 
 **Permission:** query-only+
 
@@ -474,9 +475,10 @@ Insert data into a table.
 dbcli insert users --data '{"name":"Alice","email":"alice@example.com"}'
 dbcli insert users --data '{"name":"Alice"}' --dry-run
 dbcli insert users --data '{"name":"Alice"}' --force
+dbcli insert users --data '{"name":"Alice"}' --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--data <json>`, `--dry-run`, `--force`
+**Options:** `--data <json>`, `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** read-write+
 
 ### update
@@ -486,11 +488,19 @@ Update existing data.
 ```bash
 dbcli update users --where "id=1" --set '{"name":"Bob"}'
 dbcli update users --where "id=1" --set '{"name":"Bob"}' --dry-run
+dbcli update users --where "id=1" --set '{"name":"Bob"}' --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`
+**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** read-write+
 
+> **`--where` grammar (SQL `update` / `delete`)** — equality only: `col=val` or
+> `col1=v1 AND col2=v2`. Comparison / pattern operators (`>`, `>=`, `<`, `!=`, `LIKE`, `IN`)
+> raise a parse error, and `OR` is **silently folded into the value** (`a=1 OR b=2` parses as
+> `a = "1 OR b=2"`, matching nothing intended). For ranges or compound predicates, select the
+> target primary keys first, then issue one `update` / `delete --where "id=<pk>"` per key.
+> (MongoDB `--where` accepts a full JSON filter and is exempt.)
+
 ### delete
 
 Delete data from a table.
@@ -499,9 +509,10 @@ Delete data from a table.
 dbcli delete users --where "id=1"
 dbcli delete users --where "id=1" --dry-run
 dbcli delete users --where "id=1" --force
+dbcli delete users --where "id=1" --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--where <condition>` (required), `--dry-run`, `--force`
+**Options:** `--where <condition>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** data-admin+
 
 ### export
@@ -521,7 +532,7 @@ dbcli export orders --format csv --output orders.csv      # index name as query
 dbcli export orders --no-limit --format jsonl             # scroll the whole index in batches
 ```
 
-**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--index <name>` (Elasticsearch), `--no-limit` (Elasticsearch full-index scroll)
+**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--collection <name>` (MongoDB collection) / `--index <name>` (Elasticsearch index; alias for `--collection`), `--limit <number>` (overrides auto-limit), `--no-limit` (Elasticsearch full-index scroll)
 **Permission:** query-only+ — SQL, MongoDB, and **(v1.22)** Elasticsearch.
 
 The `html` format emits the same self-contained dashboard as `query --ui` (see [Interactive HTML dashboard](#interactive-html-dashboard)). Because `export` runs raw SQL (no snippet metadata), the HTML report is always rendered as a sortable / filterable table — no KPIs or charts. Use `dbcli q @<name> --format html` (or `--ui`) for the charted view.
@@ -892,6 +903,7 @@ Boundaries:
 | `--from <path>` | Read the envelope from this file instead of `.dbcli/last-recovery.json`. Accepts raw `RecoveryEnvelope` or `SavedRecoveryEnvelope`. | — |
 | `--allow-write <tier>` | Open the risk gate. Values: `readonly-cmd` (local-side writes) \| `write-cmd` (database writes). | `none` |
 | `--no-verify` | Skip the verify step appended after a successful `--apply`. | off (verify runs by default) |
+| `--write-verification-artifact` | After a successful `--apply`, persist a secret-free `VerificationArtifact` JSON under `.dbcli/verification/`. | off |
 | `--format <format>` | `markdown` \| `json`. | `markdown` for inspect, `json` for `--apply` |
 
 #### Plan source resolution
@@ -1650,6 +1662,7 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 **Options:**
 - `--install <platform>` — `claude` | `gemini` | `antigravity` | `copilot` | `cursor` | `codex` | `windsurf`. Writes `SKILL.md` plus `reference.md` next to it so the agent gets progressive disclosure.
 - `--output <path>` — write `SKILL.md` to a file instead of stdout. Does not install `reference.md`.
+- `--lang <en|zh-TW>` — source language for the emitted SKILL content (default `en`). It selects `assets/SKILL.md` vs `assets/SKILL.zh-TW.md`; the install/output filename stays `SKILL.md` regardless.
 
 **Notes:**
 - Both files come straight from `assets/SKILL.md` + `assets/reference.md` inside the dbcli package — no runtime rendering. Keep these in sync when shipping a release.
@@ -1662,6 +1675,21 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 
 **Permission:** n/a.
 
+### skill context
+
+Emit an AI-friendly snapshot of the connected database's schema and saved-query snippets (blacklist-filtered) so an agent can be primed with the current context.
+
+```bash
+dbcli skill context                      # XML (default)
+dbcli skill context --format json
+dbcli skill context --format markdown
+```
+
+**Options:**
+- `--format <xml|json|markdown>` — output format (default: `xml`)
+
+**Permission:** query-only+ — read-only; blacklisted objects are never emitted.
+
 ### skill tasks (Agent Task Packs)
 
 ```bash
@@ -2201,7 +2229,7 @@ Rewrites emit a `REDIS_SIZE_REWRITE` warning; truncations emit `REDIS_SIZE_TRUNC
 Blacklist rules are enforced as **Redis-native key globs** (`*`, `?`, `[abc]`, `[a-z]`):
 
 ```bash
-dbcli blacklist add 'secrets:*'          # register a key-glob rule
+dbcli blacklist table add 'secrets:*'    # register a key-glob rule
 dbcli query "GET secrets:api_key"        # → BlacklistRejection (exit non-zero)
 dbcli query "MGET safe:k secrets:api"    # → rejected (any matching key fails the whole command)
 dbcli query "KEYS secrets:*"             # → rejected (pattern overlaps a rule)

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "dbcli-agent",
   "displayName": "dbcli Agent",
   "description": "Database CLI skill and command reference for AI agents.",
-  "version": "1.37.1",
+  "version": "1.39.2",
   "author": {
     "name": "Carl Lee",
     "url": "https://github.com/CarlLee1983"

package/.github/skills/dbcli/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
@@ -364,12 +373,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/.github/skills/dbcli/reference.md

@@ -249,6 +249,7 @@ dbcli q @analytics/revenue --param days=30 --format html > report.html
 - `--dry-run` — print the bound SQL + values without executing
 - `--use <name>` — pick a v2 named connection
 - `--recovery` — emit a `RecoveryEnvelope` on failure (see `recover`)
+- `--verify` — run the snippet's verification assertions after execution (only if the snippet defines them)
 
 **Permission:** query-only+
 
@@ -474,9 +475,10 @@ Insert data into a table.
 dbcli insert users --data '{"name":"Alice","email":"alice@example.com"}'
 dbcli insert users --data '{"name":"Alice"}' --dry-run
 dbcli insert users --data '{"name":"Alice"}' --force
+dbcli insert users --data '{"name":"Alice"}' --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--data <json>`, `--dry-run`, `--force`
+**Options:** `--data <json>`, `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** read-write+
 
 ### update
@@ -486,11 +488,19 @@ Update existing data.
 ```bash
 dbcli update users --where "id=1" --set '{"name":"Bob"}'
 dbcli update users --where "id=1" --set '{"name":"Bob"}' --dry-run
+dbcli update users --where "id=1" --set '{"name":"Bob"}' --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`
+**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** read-write+
 
+> **`--where` grammar (SQL `update` / `delete`)** — equality only: `col=val` or
+> `col1=v1 AND col2=v2`. Comparison / pattern operators (`>`, `>=`, `<`, `!=`, `LIKE`, `IN`)
+> raise a parse error, and `OR` is **silently folded into the value** (`a=1 OR b=2` parses as
+> `a = "1 OR b=2"`, matching nothing intended). For ranges or compound predicates, select the
+> target primary keys first, then issue one `update` / `delete --where "id=<pk>"` per key.
+> (MongoDB `--where` accepts a full JSON filter and is exempt.)
+
 ### delete
 
 Delete data from a table.
@@ -499,9 +509,10 @@ Delete data from a table.
 dbcli delete users --where "id=1"
 dbcli delete users --where "id=1" --dry-run
 dbcli delete users --where "id=1" --force
+dbcli delete users --where "id=1" --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--where <condition>` (required), `--dry-run`, `--force`
+**Options:** `--where <condition>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** data-admin+
 
 ### export
@@ -521,7 +532,7 @@ dbcli export orders --format csv --output orders.csv      # index name as query
 dbcli export orders --no-limit --format jsonl             # scroll the whole index in batches
 ```
 
-**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--index <name>` (Elasticsearch), `--no-limit` (Elasticsearch full-index scroll)
+**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--collection <name>` (MongoDB collection) / `--index <name>` (Elasticsearch index; alias for `--collection`), `--limit <number>` (overrides auto-limit), `--no-limit` (Elasticsearch full-index scroll)
 **Permission:** query-only+ — SQL, MongoDB, and **(v1.22)** Elasticsearch.
 
 The `html` format emits the same self-contained dashboard as `query --ui` (see [Interactive HTML dashboard](#interactive-html-dashboard)). Because `export` runs raw SQL (no snippet metadata), the HTML report is always rendered as a sortable / filterable table — no KPIs or charts. Use `dbcli q @<name> --format html` (or `--ui`) for the charted view.
@@ -892,6 +903,7 @@ Boundaries:
 | `--from <path>` | Read the envelope from this file instead of `.dbcli/last-recovery.json`. Accepts raw `RecoveryEnvelope` or `SavedRecoveryEnvelope`. | — |
 | `--allow-write <tier>` | Open the risk gate. Values: `readonly-cmd` (local-side writes) \| `write-cmd` (database writes). | `none` |
 | `--no-verify` | Skip the verify step appended after a successful `--apply`. | off (verify runs by default) |
+| `--write-verification-artifact` | After a successful `--apply`, persist a secret-free `VerificationArtifact` JSON under `.dbcli/verification/`. | off |
 | `--format <format>` | `markdown` \| `json`. | `markdown` for inspect, `json` for `--apply` |
 
 #### Plan source resolution
@@ -1650,6 +1662,7 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 **Options:**
 - `--install <platform>` — `claude` | `gemini` | `antigravity` | `copilot` | `cursor` | `codex` | `windsurf`. Writes `SKILL.md` plus `reference.md` next to it so the agent gets progressive disclosure.
 - `--output <path>` — write `SKILL.md` to a file instead of stdout. Does not install `reference.md`.
+- `--lang <en|zh-TW>` — source language for the emitted SKILL content (default `en`). It selects `assets/SKILL.md` vs `assets/SKILL.zh-TW.md`; the install/output filename stays `SKILL.md` regardless.
 
 **Notes:**
 - Both files come straight from `assets/SKILL.md` + `assets/reference.md` inside the dbcli package — no runtime rendering. Keep these in sync when shipping a release.
@@ -1662,6 +1675,21 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 
 **Permission:** n/a.
 
+### skill context
+
+Emit an AI-friendly snapshot of the connected database's schema and saved-query snippets (blacklist-filtered) so an agent can be primed with the current context.
+
+```bash
+dbcli skill context                      # XML (default)
+dbcli skill context --format json
+dbcli skill context --format markdown
+```
+
+**Options:**
+- `--format <xml|json|markdown>` — output format (default: `xml`)
+
+**Permission:** query-only+ — read-only; blacklisted objects are never emitted.
+
 ### skill tasks (Agent Task Packs)
 
 ```bash
@@ -2201,7 +2229,7 @@ Rewrites emit a `REDIS_SIZE_REWRITE` warning; truncations emit `REDIS_SIZE_TRUNC
 Blacklist rules are enforced as **Redis-native key globs** (`*`, `?`, `[abc]`, `[a-z]`):
 
 ```bash
-dbcli blacklist add 'secrets:*'          # register a key-glob rule
+dbcli blacklist table add 'secrets:*'    # register a key-glob rule
 dbcli query "GET secrets:api_key"        # → BlacklistRejection (exit non-zero)
 dbcli query "MGET safe:k secrets:api"    # → rejected (any matching key fails the whole command)
 dbcli query "KEYS secrets:*"             # → rejected (pattern overlaps a rule)

package/CHANGELOG.md

@@ -5,11 +5,35 @@ 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.39.2] - 2026-07-03 - Windows 跨平台、skill 安裝安全與 plugin 版本對齊
+
+> npm `1.39.1` 已於 2026-06-30 發布；本批修復在其後累積於同一版號下（npm 版本不可覆蓋），故獨立為 1.39.2 以便日後發布。
+
+### Fixed
+
+- **Windows 跨平台修復（Windows CI 首次全綠）。** filesystem 操作與 path 檢查改為跨平台實作、修正 `emit` 子行程 import 與殘留的 path assertion，並以 portable `node:fs` 取代僅限 unix 的 coreutils spawns。此前 Windows job 從未通過（fail-fast 總是先取消它）。
+- **Skill 安裝安全強化。** 修正 output / install 旗標衝突、強化安裝安全檢查與 task 過濾條件。
+- **zh-TW skill 安裝不再被誤判為永遠過期。**
+- **Skill 參考修正。** 移除文件中不存在的 `blacklist add`、補回缺漏的 reference flags。
+
+### Changed
+
+- **文件補齊。** 明示 `--where` 僅支援等值比較、補上 Redis / Elasticsearch 寫入模型說明、記錄 home-storage 綁定並重新同步 md/html parity、對齊 config-location-policy 與實作綁定模型。
+- **Plugin manifest 版本對齊。** `.claude-plugin` / `.cursor-plugin` / `.codex-plugin` 及 `plugins/dbcli-agent` 的 `plugin.json` 版本更新為 1.39.2（先前漂移在 1.37.1 / 1.31.0，未跟上主版本；`plugin:sync` / `plugin:check` 只同步 skill 內容不同步版本）。
+
+### Internal
+
+- CI 加入 doc / skill drift guards 並修正 release-gate 說明；新增 `reference.md` 指令覆蓋契約測試；移除失效的 `validate-skill.sh`（testing doc 改指向 `bun test`）；稽核冗餘測試改用 collision-proof token sentinel；zsh 不存在時跳過 rc-eval 測試；每檔還原 leaked spies 以修正順序相依的 CI 失敗；prettier 對齊 `q` / audit `logger` 測試。
+
 ## [1.39.1] - 2026-06-30 - Skill report dashboard routing
 
+### Fixed
+
+- **Dashboard 請求不再落入通用 query 路由。** 先前 dashboard / report 意圖的請求會 fall through 到一般 query 路徑；現已正確導向 dashboard 專用流程。
+
 ### Changed
 
-- **Skill 路由補上 DB report / dashboard / HTML UI 意圖。** `assets/SKILL.md` / `assets/SKILL.zh-TW.md` 的 metadata、任務路由表、開發者速查與 HTML dashboard 範例現在明確導向 `queries search|suggest` → `queries show` → `q @<name> --ui` / `--format html`，並保留 raw SQL `export --format html` 的檔案輸出路徑。已透過 `plugin:sync` 同步到所有受管理平台副本。純文件 / skill 變更，無 CLI 行為更動。
+- **Skill 路由補上 DB report / dashboard / HTML UI 意圖。** `assets/SKILL.md` / `assets/SKILL.zh-TW.md` 的 metadata、任務路由表、開發者速查與 HTML dashboard 範例現在明確導向 `queries search|suggest` → `queries show` → `q @<name> --ui` / `--format html`，並保留 raw SQL `export --format html` 的檔案輸出路徑。已透過 `plugin:sync` 同步到所有受管理平台副本。純文件 / skill 變更。
 
 ## [1.39.0] - 2026-06-24 - Dashboard chart type 解析時邊界驗證
 

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
@@ -364,12 +373,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`。
 
@@ -280,10 +289,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。

package/assets/reference.md

@@ -249,6 +249,7 @@ dbcli q @analytics/revenue --param days=30 --format html > report.html
 - `--dry-run` — print the bound SQL + values without executing
 - `--use <name>` — pick a v2 named connection
 - `--recovery` — emit a `RecoveryEnvelope` on failure (see `recover`)
+- `--verify` — run the snippet's verification assertions after execution (only if the snippet defines them)
 
 **Permission:** query-only+
 
@@ -474,9 +475,10 @@ Insert data into a table.
 dbcli insert users --data '{"name":"Alice","email":"alice@example.com"}'
 dbcli insert users --data '{"name":"Alice"}' --dry-run
 dbcli insert users --data '{"name":"Alice"}' --force
+dbcli insert users --data '{"name":"Alice"}' --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--data <json>`, `--dry-run`, `--force`
+**Options:** `--data <json>`, `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** read-write+
 
 ### update
@@ -486,11 +488,19 @@ Update existing data.
 ```bash
 dbcli update users --where "id=1" --set '{"name":"Bob"}'
 dbcli update users --where "id=1" --set '{"name":"Bob"}' --dry-run
+dbcli update users --where "id=1" --set '{"name":"Bob"}' --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`
+**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** read-write+
 
+> **`--where` grammar (SQL `update` / `delete`)** — equality only: `col=val` or
+> `col1=v1 AND col2=v2`. Comparison / pattern operators (`>`, `>=`, `<`, `!=`, `LIKE`, `IN`)
+> raise a parse error, and `OR` is **silently folded into the value** (`a=1 OR b=2` parses as
+> `a = "1 OR b=2"`, matching nothing intended). For ranges or compound predicates, select the
+> target primary keys first, then issue one `update` / `delete --where "id=<pk>"` per key.
+> (MongoDB `--where` accepts a full JSON filter and is exempt.)
+
 ### delete
 
 Delete data from a table.
@@ -499,9 +509,10 @@ Delete data from a table.
 dbcli delete users --where "id=1"
 dbcli delete users --where "id=1" --dry-run
 dbcli delete users --where "id=1" --force
+dbcli delete users --where "id=1" --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--where <condition>` (required), `--dry-run`, `--force`
+**Options:** `--where <condition>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** data-admin+
 
 ### export
@@ -521,7 +532,7 @@ dbcli export orders --format csv --output orders.csv      # index name as query
 dbcli export orders --no-limit --format jsonl             # scroll the whole index in batches
 ```
 
-**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--index <name>` (Elasticsearch), `--no-limit` (Elasticsearch full-index scroll)
+**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--collection <name>` (MongoDB collection) / `--index <name>` (Elasticsearch index; alias for `--collection`), `--limit <number>` (overrides auto-limit), `--no-limit` (Elasticsearch full-index scroll)
 **Permission:** query-only+ — SQL, MongoDB, and **(v1.22)** Elasticsearch.
 
 The `html` format emits the same self-contained dashboard as `query --ui` (see [Interactive HTML dashboard](#interactive-html-dashboard)). Because `export` runs raw SQL (no snippet metadata), the HTML report is always rendered as a sortable / filterable table — no KPIs or charts. Use `dbcli q @<name> --format html` (or `--ui`) for the charted view.
@@ -892,6 +903,7 @@ Boundaries:
 | `--from <path>` | Read the envelope from this file instead of `.dbcli/last-recovery.json`. Accepts raw `RecoveryEnvelope` or `SavedRecoveryEnvelope`. | — |
 | `--allow-write <tier>` | Open the risk gate. Values: `readonly-cmd` (local-side writes) \| `write-cmd` (database writes). | `none` |
 | `--no-verify` | Skip the verify step appended after a successful `--apply`. | off (verify runs by default) |
+| `--write-verification-artifact` | After a successful `--apply`, persist a secret-free `VerificationArtifact` JSON under `.dbcli/verification/`. | off |
 | `--format <format>` | `markdown` \| `json`. | `markdown` for inspect, `json` for `--apply` |
 
 #### Plan source resolution
@@ -1650,6 +1662,7 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 **Options:**
 - `--install <platform>` — `claude` | `gemini` | `antigravity` | `copilot` | `cursor` | `codex` | `windsurf`. Writes `SKILL.md` plus `reference.md` next to it so the agent gets progressive disclosure.
 - `--output <path>` — write `SKILL.md` to a file instead of stdout. Does not install `reference.md`.
+- `--lang <en|zh-TW>` — source language for the emitted SKILL content (default `en`). It selects `assets/SKILL.md` vs `assets/SKILL.zh-TW.md`; the install/output filename stays `SKILL.md` regardless.
 
 **Notes:**
 - Both files come straight from `assets/SKILL.md` + `assets/reference.md` inside the dbcli package — no runtime rendering. Keep these in sync when shipping a release.
@@ -1662,6 +1675,21 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 
 **Permission:** n/a.
 
+### skill context
+
+Emit an AI-friendly snapshot of the connected database's schema and saved-query snippets (blacklist-filtered) so an agent can be primed with the current context.
+
+```bash
+dbcli skill context                      # XML (default)
+dbcli skill context --format json
+dbcli skill context --format markdown
+```
+
+**Options:**
+- `--format <xml|json|markdown>` — output format (default: `xml`)
+
+**Permission:** query-only+ — read-only; blacklisted objects are never emitted.
+
 ### skill tasks (Agent Task Packs)
 
 ```bash
@@ -2201,7 +2229,7 @@ Rewrites emit a `REDIS_SIZE_REWRITE` warning; truncations emit `REDIS_SIZE_TRUNC
 Blacklist rules are enforced as **Redis-native key globs** (`*`, `?`, `[abc]`, `[a-z]`):
 
 ```bash
-dbcli blacklist add 'secrets:*'          # register a key-glob rule
+dbcli blacklist table add 'secrets:*'    # register a key-glob rule
 dbcli query "GET secrets:api_key"        # → BlacklistRejection (exit non-zero)
 dbcli query "MGET safe:k secrets:api"    # → rejected (any matching key fails the whole command)
 dbcli query "KEYS secrets:*"             # → rejected (pattern overlaps a rule)