@carllee1983/dbcli 1.23.1 → 1.28.0

package/CHANGELOG.md

@@ -5,7 +5,49 @@ 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.28.0] - 2026-06-08 - Core Subpath Export
+
+### Added
+
+- **`@carllee1983/dbcli/core` 子路徑匯出。** 新增穩定對外 API barrel（`src/core/public.ts`），透過 `package.json` 的 `exports` map 開出 `./core` 子路徑，並隨套件發布 `dist/core.mjs` 與扁平型別宣告 `dist/core.d.ts`。外部專案（如 `dbcli-gui` 桌面客戶端的 Bun sidecar）可 `import { AdapterFactory, QueryExecutor, SchemaLayeredLoader, listConnections, BlacklistManager } from '@carllee1983/dbcli/core'` 直接重用引擎能力。CLI（`bin`）行為完全不變。
+
+## [1.27.0] - 2026-06-05 - Proxy Analyze
+
+### Added
+
+- **`dbcli proxy analyze` — 離線分析 proxy 事件日誌。** 讀取 `.dbcli/proxy/events.jsonl`(預設含 rotation `.1` 段),聚合成 agent-facing JSON 報告(`summary`、`byFingerprint`、`slowest`、`errors`、`hotTables`、`repetition`)或人類版 text。重用 `redactLiterals` 做 SQL 指紋正規化;對最吃總時間的 SELECT 指紋附上可執行的 `suggestedCommands`(`explain` / `guide missing-index-for`),僅輸出建議指令字串、不自動執行。旗標:`--events`、`--format json|text`、`--top`、`--slow-ms`、`--n-plus-one`、`--no-include-rotated`。不連資料庫。
+
+### Changed
+
+- **`dbcli proxy` — 事件日誌寫入序列化 + 自動輪替。** `EventWriter` 現在將所有寫入(根事件 + 全部 session)序列化到單一 in-process promise 鏈,避免多連線併發時 JSONL 行交錯或 rotation 計數競態;單一寫入失敗只影響該呼叫端(維持 fail-loud),不會卡住後續寫入。新增自動輪替(重用抽出的中性工具 `src/utils/jsonl-rotation.ts`,audit logger 亦改用同一份):當下一行將達 ~50 MiB 或 200,000 筆時,目前檔案改名為 `<events>.1`(覆寫舊段),保留單一滾動段,最壞磁碟用量約為位元組上限的 2 倍。先前 `events.jsonl` 會無限制成長。
+
+### Fixed
+
+- **`dbcli proxy` — `--slow-ms` 現在會在事件中標記 `slow`。** `query_completed` 事件新增 `slow: boolean` 欄位（`durationMs >= --slow-ms` 時為 `true`），與既有的終端警告一致。先前 `--slow-ms` 僅印出終端警告，但 CHANGELOG／使用者文件／reference 卻宣稱事件帶有 `slow` 旗標——此落差已修正。同步修正 `reference.md` 的 JSONL 事件範例(欄位名與實際 `query_completed` 結構對齊)，並更新 en／zh-TW 使用者文件(md + html)中對 `--slow-ms` 的描述。
+
+## [1.26.0] - 2026-06-04 - Observability Proxy
+
+### Added
+
+- **`dbcli proxy` — 本地端開發觀測代理。** 支援 `mysql`、`mariadb`、`postgresql` 子指令。在現有應用程式與真實資料庫之間插入一個中繼層:dbcli 監聽 `--listen` 埠,轉送流量至 `--target`(或 `--use` / config 目標推斷),並把每個查詢的查詢文字、延遲、傳輸位元組、錯誤等事件以 JSONL 格式附加到 `.dbcli/proxy/events.jsonl`(可用 `--events` 覆寫)。僅作觀測使用,不執行任何改寫或封鎖。旗標:`--listen <addr:port>`、`--target <addr:port>`、`--events <path>`(預設 `.dbcli/proxy/events.jsonl`)、`--slow-ms <ms>`(預設 `1000`,超過即在事件中標記 `slow: true`)、`--redact none|literals`(預設 `none`;`literals` 會從事件裡剔除 SQL 字面值)、`--format text|json`(預設 `text`)。TLS 在 v1 僅轉送不解密;prepared / extended 協定為盡力標記。
+
+## [1.25.0] - 2026-05-29 - Data-Layer Verification
+
+### Added
+
+- **`dbcli snapshot <query>` — 結果指紋。** 將任一查詢結果轉成確定性、黑名單安全的 `ResultSnapshot`(`rowCount` + 每欄聚合:null/distinct 計數、min/max/sum、順序無關的 checksum)。預設落檔至 `.dbcli/snapshots/snap-<timestamp>.json`,亦支援 `--out`、`--stdout`、`--rows`(連同遮罩後的列一併存檔)、`--format`、`--no-limit`。
+- **`dbcli assert <query>` — 行內不變量檢查。** 三種模式:`--expect`(`rows > 0`、`value == 5000`、`col:email not null`、`col:id unique`、`col:amount between 0 and 100`、`col:age >= 18`)、`--vs <query> --compare rows|value`(跨查詢對帳)、`--against <snapshot> --tolerance <pct>`(對既有快照基準比對)。預設失敗時 `exit 1`,可用 `--no-fail` 僅報告不改變 exit code。
+- 兩個指令均沿用既有 adapter / QueryExecutor / blacklist / audit 堆疊,黑名單欄位由 QueryExecutor 在源頭遮罩,指紋天生安全。目前支援 SQL 引擎(PostgreSQL / MySQL / MariaDB)。
+
+## [1.24.0] - 2026-05-29 - Antigravity CLI Skill Target
+
+### Added
+
+- **`dbcli skill --install antigravity` 新增 Antigravity CLI 安裝目標。** Antigravity CLI 是 Google Gemini CLI 的後繼者;skill 會寫入 CLI 範疇的全域路徑 `~/.gemini/antigravity-cli/skills/dbcli/SKILL.md`(同目錄附帶 `reference.md`)。`SUPPORTED_PLATFORMS` 一併納入 `antigravity`,故 `dbcli upgrade` 的 skill 過期檢查也會涵蓋此平台。
+
+### Changed
+
+- `gemini`(Gemini CLI)安裝目標暫予保留,但已標示為即將淘汰,建議改用 `antigravity`。README(en/zh-TW)、`assets/SKILL.md`、`assets/SKILL.zh-TW.md`、`assets/reference.md` 與 `docs/user` 的平台清單同步更新。
 
 ## [1.23.1] - 2026-05-29 - Skill Docs Sync
 

package/README.md

@@ -630,7 +630,8 @@ Generate or install AI agent skill documentation.
 dbcli skill                           # Output skill to stdout
 dbcli skill --output SKILL.md         # Write to file
 dbcli skill --install claude          # Install to Claude Code config
-dbcli skill --install gemini          # Install to Gemini CLI
+dbcli skill --install gemini          # Install to Gemini CLI (being phased out)
+dbcli skill --install antigravity     # Install to Antigravity CLI (Gemini CLI's successor)
 dbcli skill --install copilot         # Install to GitHub Copilot
 dbcli skill --install cursor          # Install to Cursor IDE
 ```
@@ -654,6 +655,7 @@ dbcli skill
 # Install for all platforms
 dbcli skill --install claude && \
 dbcli skill --install gemini && \
+dbcli skill --install antigravity && \
 dbcli skill --install copilot && \
 dbcli skill --install cursor
 ```
@@ -766,6 +768,73 @@ dbcli diff --against ./schema-before.json --format table
 
 ---
 
+#### `dbcli snapshot`
+
+Capture a **result fingerprint** of a query (distinct from `diff`, which snapshots *schema*): row count plus per-column aggregates (null/distinct counts, min/max/sum) and an order-independent checksum. Blacklisted columns are masked at the source, so the snapshot is safe to store. Use it as a baseline for `dbcli assert --against`. SQL engines only.
+
+**Usage:**
+```bash
+dbcli snapshot "SELECT * FROM orders WHERE created_at >= '2026-05-01'"   # → .dbcli/snapshots/snap-<timestamp>.json
+dbcli snapshot @analytics/daily-revenue --out base.json
+dbcli snapshot "SELECT status, count(*) FROM orders GROUP BY status" --stdout
+```
+
+**Options:**
+- `--out <path>` — Output path (default: `.dbcli/snapshots/snap-<timestamp>.json`)
+- `--rows` — Also store the full (blacklist-masked) rows
+- `--stdout` — Print snapshot JSON to stdout instead of writing a file
+- `--format json|table` — Output format for `--stdout` (default: `json`)
+- `--no-limit` — Disable the automatic query-only LIMIT
+
+---
+
+#### `dbcli assert`
+
+Assert an **invariant** on a query result. Exits `1` on failure (composes in scripts/CI) unless `--no-fail`. SQL engines only.
+
+**Usage:**
+```bash
+dbcli assert "SELECT count(*) FROM orders" --expect "value > 0"
+dbcli assert "SELECT * FROM orders WHERE total < 0" --expect "rows == 0"
+dbcli assert "SELECT email FROM users" --expect "col:email not null"
+dbcli assert "SELECT sum(amount) FROM ledger_a" --vs "SELECT sum(amount) FROM ledger_b" --compare value
+dbcli assert "SELECT * FROM orders" --against base.json --tolerance 0.01
+```
+
+**Options:**
+- `--expect <condition>` — `rows > 0`, `value == 5000`, `col:email not null`, `col:id unique`, `col:amount between 0 and 100`, `col:age >= 18`
+- `--vs <query>` — Reconcile against a second query
+- `--compare rows|value` — Comparison mode for `--vs` (default: `value`)
+- `--against <path>` — Compare the current result fingerprint to a saved snapshot
+- `--tolerance <pct>` — Allowed relative drift for `--against` (e.g. `0.01`; default: `0` = exact checksum match)
+- `--no-fail` — Always exit 0; report pass/fail in output only
+- `--format json|table` — Output format (default: `json`)
+
+---
+
+#### `dbcli proxy` (v1.26)
+
+Local-development **observability proxy** for MySQL, MariaDB, and PostgreSQL. Point an existing app at the proxy port; dbcli relays all TCP frames to the real database and appends one JSONL event per query to `.dbcli/proxy/events.jsonl`. Observe-only — no rewrite or blocking. Not a production gateway.
+
+**Subcommands:** `mysql` · `mariadb` · `postgresql`
+
+```bash
+dbcli proxy mysql      --listen 127.0.0.1:3307 --target 127.0.0.1:3306
+dbcli proxy postgresql --listen 127.0.0.1:5434 --target 127.0.0.1:5432
+dbcli proxy mysql      --slow-ms 500 --redact literals
+dbcli proxy mariadb    --events ./logs/proxy.jsonl
+```
+
+**Options:**
+- `--listen <addr:port>` — Proxy listen address
+- `--target <addr:port>` — Real database address (inferred from config / `--use` if omitted)
+- `--events <path>` — JSONL event log (default: `.dbcli/proxy/events.jsonl`)
+- `--slow-ms <ms>` — Flag events slower than this threshold as `slow: true` (default: `1000`)
+- `--redact none|literals` — Strip SQL literal values from event records (default: `none`)
+- `--format text|json` — Startup output format (default: `text`)
+
+---
+
 #### `dbcli status`
 
 Show non-sensitive configuration summary (permission level, DB system, blacklist counts, config metadata version). Does not print connection credentials — intended for AI agents.

package/README.zh-TW.md

@@ -528,7 +528,8 @@ dbcli export "SELECT * FROM users WHERE active=true" --format json | jq '.data |
 dbcli skill                           # 輸出至 stdout
 dbcli skill --output SKILL.md         # 寫入檔案
 dbcli skill --install claude          # 安裝至 Claude Code 設定
-dbcli skill --install gemini          # 安裝至 Gemini CLI
+dbcli skill --install gemini          # 安裝至 Gemini CLI（即將淘汰）
+dbcli skill --install antigravity     # 安裝至 Antigravity CLI（Gemini CLI 後繼者）
 dbcli skill --install copilot         # 安裝至 GitHub Copilot
 dbcli skill --install cursor          # 安裝至 Cursor IDE
 ```
@@ -552,6 +553,7 @@ dbcli skill
 # 為多平台安裝
 dbcli skill --install claude && \
 dbcli skill --install gemini && \
+dbcli skill --install antigravity && \
 dbcli skill --install copilot && \
 dbcli skill --install cursor
 ```
@@ -665,6 +667,73 @@ dbcli diff --against ./schema-before.json --format table
 
 ---
 
+#### `dbcli snapshot`
+
+擷取查詢的**結果指紋**(與 `diff` 不同,`diff` 快照的是 *schema*):rowCount 加上每欄聚合(null/distinct 計數、min/max/sum)與順序無關的 checksum。黑名單欄位在源頭遮罩,因此快照可安全保存。作為 `dbcli assert --against` 的基準。僅支援 SQL 引擎。
+
+**用法:**
+```bash
+dbcli snapshot "SELECT * FROM orders WHERE created_at >= '2026-05-01'"   # → .dbcli/snapshots/snap-<timestamp>.json
+dbcli snapshot @analytics/daily-revenue --out base.json
+dbcli snapshot "SELECT status, count(*) FROM orders GROUP BY status" --stdout
+```
+
+**選項:**
+- `--out <path>` — 輸出路徑(預設:`.dbcli/snapshots/snap-<timestamp>.json`)
+- `--rows` — 連同遮罩後的完整列一併存檔
+- `--stdout` — 將快照 JSON 印到 stdout 而非寫檔
+- `--format json|table` — `--stdout` 的輸出格式(預設:`json`)
+- `--no-limit` — 停用查詢限定模式的自動 LIMIT
+
+---
+
+#### `dbcli assert`
+
+對查詢結果驗證**不變量**。失敗時 `exit 1`(可組合進腳本 / CI),除非加上 `--no-fail`。僅支援 SQL 引擎。
+
+**用法:**
+```bash
+dbcli assert "SELECT count(*) FROM orders" --expect "value > 0"
+dbcli assert "SELECT * FROM orders WHERE total < 0" --expect "rows == 0"
+dbcli assert "SELECT email FROM users" --expect "col:email not null"
+dbcli assert "SELECT sum(amount) FROM ledger_a" --vs "SELECT sum(amount) FROM ledger_b" --compare value
+dbcli assert "SELECT * FROM orders" --against base.json --tolerance 0.01
+```
+
+**選項:**
+- `--expect <condition>` — `rows > 0`、`value == 5000`、`col:email not null`、`col:id unique`、`col:amount between 0 and 100`、`col:age >= 18`
+- `--vs <query>` — 與第二個查詢對帳
+- `--compare rows|value` — `--vs` 的比較模式(預設:`value`)
+- `--against <path>` — 將目前結果指紋與已存快照比對
+- `--tolerance <pct>` — `--against` 容許的相對漂移(例如 `0.01`;預設 `0` = 完全相符 checksum)
+- `--no-fail` — 永遠 exit 0;僅在輸出中報告 pass/fail
+- `--format json|table` — 輸出格式(預設:`json`)
+
+---
+
+#### `dbcli proxy`（v1.26）
+
+MySQL、MariaDB、PostgreSQL 的本地端**開發觀測代理**。將現有應用程式指向代理埠；dbcli 會將所有 TCP 訊框中繼至真實資料庫，並把每個查詢的事件（查詢文字、延遲、傳輸位元組、錯誤）附加到 `.dbcli/proxy/events.jsonl`。僅作觀測使用，不執行任何改寫或封鎖。非正式環境閘道。
+
+**子指令：** `mysql` · `mariadb` · `postgresql`
+
+```bash
+dbcli proxy mysql      --listen 127.0.0.1:3307 --target 127.0.0.1:3306
+dbcli proxy postgresql --listen 127.0.0.1:5434 --target 127.0.0.1:5432
+dbcli proxy mysql      --slow-ms 500 --redact literals
+dbcli proxy mariadb    --events ./logs/proxy.jsonl
+```
+
+**選項：**
+- `--listen <addr:port>` — 代理監聽位址
+- `--target <addr:port>` — 真實資料庫位址（若省略則從 config / `--use` 推斷）
+- `--events <path>` — JSONL 事件記錄路徑（預設：`.dbcli/proxy/events.jsonl`）
+- `--slow-ms <ms>` — 超過此門檻的事件標記 `slow: true`（預設：`1000`）
+- `--redact none|literals` — 從事件記錄中剔除 SQL 字面值（預設：`none`）
+- `--format text|json` — 啟動輸出格式（預設：`text`）
+
+---
+
 #### `dbcli status`
 
 顯示不含連線憑證的設定摘要（權限、資料庫系統、黑名單筆數、設定中繼版本），適合提供給 AI 代理。

package/assets/SKILL.md

@@ -250,6 +250,9 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `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. |
+| `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>`. |
+| `proxy` | n/a | **(v1.26)** MySQL/MariaDB/PostgreSQL only. Local-dev observability proxy — relays app traffic to the real DB and appends query/latency/byte/error events to `.dbcli/proxy/events.jsonl`. Subcommands: `mysql` \| `mariadb` \| `postgresql`. `--listen`, `--target`, `--events` (default `.dbcli/proxy/events.jsonl`), `--slow-ms` (default `1000`), `--redact none\|literals` (default `none`). Observe-only. **(v1.27)** `proxy analyze` aggregates the event log offline into a JSON/text report (summary, byFingerprint with suggestedCommands, slowest, errors, hotTables, N+1) — `--format`, `--top`, `--slow-ms`, `--n-plus-one`. |
 | `status` | query-only+ | Safe JSON/text summary (no credentials). |
 | `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`. |
@@ -260,7 +263,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `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, 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. |
+| `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|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.

package/assets/SKILL.zh-TW.md

@@ -209,6 +209,9 @@ dbcli init --use-env-refs \
 | `blacklist` | n/a | `list` / `table` / `column` 子指令,從查詢結果中遮蔽敏感資料。 |
 | `check` | query-only+ | 僅 SQL(在 MySQL / MariaDB 最佳)。 |
 | `diff` | query-only+ | 僅 SQL。儲存 / 比較 schema snapshot。 |
+| `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>`。 |
+| `proxy` | n/a | **(v1.26)** 僅 MySQL/MariaDB/PostgreSQL。本地端開發觀測代理 — 中繼應用程式流量至真實資料庫,並將查詢 / 延遲 / 位元組 / 錯誤事件附加到 `.dbcli/proxy/events.jsonl`。子指令:`mysql` \| `mariadb` \| `postgresql`。`--listen`、`--target`、`--events`(預設 `.dbcli/proxy/events.jsonl`)、`--slow-ms`(預設 `1000`)、`--redact none\|literals`(預設 `none`)。僅作觀測,不改寫或封鎖。 |
 | `status` | query-only+ | 安全 JSON / 文字摘要(不含憑證)。 |
 | `inspect` | query-only+ | 唯讀脈絡快照(連線、權限、blacklist、物件、snippets、建議指令)。`--for-agent` / `--no-connect` / `--require-schema-cache`。支援 `--recovery`。 |
 | `report` | query-only+ | 以 `@diag/*` snippet 組成的診斷報告(health / capacity / perf)。`--section`、`--brief`、`--for-agent`、`--no-connect`。 |
@@ -219,7 +222,7 @@ dbcli init --use-env-refs \
 | `completion` | n/a | bash / zsh / fish 腳本。 |
 | `upgrade` | n/a | 從 npm 自我更新;每個指令都帶 24h 快取的版本提示。 |
 | `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 提示詞脈絡載荷。 |
+| `skill` | n/a | 產出 / 安裝 AI skill 文件（`--install <claude\|gemini\|antigravity\|copilot\|cursor>`）；`skill tasks list/show/plan` 提供 Agent Task Packs；`skill context` 提供 LLM 提示詞脈絡載荷。 |
 | `migrate` | admin | 僅 SQL。**DDL;預設 dry-run** — 需 `--execute` 才會真的執行。 |
 
 任何子指令上的 `--use <name>` 都會把目標切到對應的 v2 連線,但不改變預設值。

package/assets/reference.md

@@ -572,6 +572,94 @@ dbcli diff --against before.json --format json
 **Options:** `--snapshot <path>`, `--against <path>`, `--format <json|table>`
 **Permission:** query-only+
 
+### snapshot
+
+Capture a **result fingerprint** of a query (not schema): `rowCount` plus per-column
+aggregates (null/distinct counts, min/max/sum, an order-independent checksum) and a
+top-level `resultChecksum`. Blacklisted columns are masked at the source by QueryExecutor,
+so the fingerprint is safe to store and share. Use it as a baseline for `assert --against`.
+
+```bash
+dbcli snapshot "SELECT * FROM orders WHERE created_at >= '2026-05-01'"   # → .dbcli/snapshots/snap-<timestamp>.json
+dbcli snapshot @analytics/daily-revenue --out base.json                  # saved query → explicit path
+dbcli snapshot "SELECT status, count(*) FROM orders GROUP BY status" --stdout
+dbcli snapshot "SELECT * FROM orders" --rows --out full.json             # also store masked rows
+```
+
+**Options:** `--out <path>` (default `.dbcli/snapshots/snap-<timestamp>.json`), `--rows`, `--stdout`, `--format <json|table>`, `--no-limit`
+**Engines:** SQL only (PostgreSQL / MySQL / MariaDB)
+**Permission:** query-only+
+
+### assert
+
+Assert an **invariant** on a query result. Exits `1` on failure (so it composes in
+scripts / CI) unless `--no-fail` is given. Three modes (combinable):
+
+- `--expect <condition>` — inline check against the result:
+  - `rows > 0` / `rows == 1` … (row count vs operators `> >= < <= == !=`)
+  - `value == 5000` / `value == "done"` (single-cell result; project to one column)
+  - `col:email not null` · `col:id unique` · `col:amount between 0 and 100` · `col:age >= 18`
+- `--vs <query> --compare rows|value` — reconcile against a second query (cross-check totals/counts).
+- `--against <snapshot> --tolerance <pct>` — compare the current result fingerprint to a saved snapshot. `tolerance 0` requires an exact (order-independent) checksum match; `tolerance 0.01` allows ±1% drift on rowCount and each numeric column sum.
+
+```bash
+dbcli assert "SELECT count(*) FROM orders" --expect "value > 0"
+dbcli assert "SELECT * FROM orders WHERE total < 0" --expect "rows == 0"     # no negative totals
+dbcli assert "SELECT email FROM users" --expect "col:email not null"
+dbcli assert "SELECT sum(amount) FROM ledger_a" --vs "SELECT sum(amount) FROM ledger_b" --compare value
+dbcli assert "SELECT * FROM orders" --against base.json --tolerance 0.01
+dbcli assert "SELECT count(*) FROM orders" --expect "value > 100" --no-fail   # report only, exit 0
+```
+
+**Options:** `--expect <condition>`, `--vs <query>`, `--compare <rows|value>` (default `value`), `--against <path>`, `--tolerance <pct>` (default `0`), `--no-fail`, `--format <json|table>`
+**Output:** `AssertVerdict` = `{ pass, checks: [{ name, expected, actual, pass }] }`
+**Engines:** SQL only (PostgreSQL / MySQL / MariaDB)
+**Permission:** query-only+
+
+### proxy
+
+Local-development **observability proxy** for MySQL/MariaDB/PostgreSQL. Inserts dbcli
+between an existing application and its real database: it listens on a configurable
+port, relays TCP frames to the real server, and appends one JSONL event per query to
+`.dbcli/proxy/events.jsonl`. Observe-only — no rewrite, blocking, or query modification.
+Not intended as a production gateway.
+
+**Subcommands:** `mysql` · `mariadb` · `postgresql`
+
+```bash
+dbcli proxy mysql       --listen 127.0.0.1:3307 --target 127.0.0.1:3306
+dbcli proxy postgresql  --listen 127.0.0.1:5434 --target 127.0.0.1:5432
+dbcli proxy mysql       --slow-ms 500 --redact literals   # redact SQL literals in events
+dbcli proxy mariadb     --events ./logs/proxy.jsonl        # custom event file
+dbcli proxy postgresql  --use prod                         # infer target from named connection
+
+dbcli proxy analyze                               # analyze .dbcli/proxy/events.jsonl (JSON)
+dbcli proxy analyze --format text --top 10        # human-readable top-10 view
+dbcli proxy analyze --slow-ms 200 --n-plus-one 5  # custom thresholds
+```
+
+**Options:**
+- `--listen <addr:port>` — Address dbcli will listen on (e.g. `127.0.0.1:3307`)
+- `--target <addr:port>` — Address of the real database server to relay to. If omitted, inferred from the active (or `--use`) connection config.
+- `--events <path>` — JSONL event log path (default: `.dbcli/proxy/events.jsonl`)
+- `--slow-ms <ms>` — Threshold in milliseconds above which events are flagged `slow: true` (default: `1000`)
+- `--redact <none|literals>` — Whether to strip SQL literal values from event records (default: `none`; `literals` removes quoted strings and numbers)
+- `--format <text|json>` — Startup / status output format (default: `text`)
+- `--use <name>` — Target a named v2 connection for `--target` inference
+
+**Event schema (JSONL):** each line is one event. `type` is one of `proxy_started`, `session_started`, `query_observed`, `query_completed`, `query_errored`, `session_ended`, `parse_error`. A representative `query_completed` line:
+```json
+{ "version": 1, "type": "query_completed", "timestamp": "<ISO-8601>", "engine": "mysql", "sessionId": "pxy_1", "queryId": "qry_pxy_1_1", "client": "127.0.0.1:54321", "target": "127.0.0.1:3306", "sql": "SELECT * FROM users WHERE id = 1", "statement": "SELECT", "tables": ["users"], "durationMs": 42, "requestBytes": 128, "responseBytes": 512, "rowCount": null, "slow": false, "error": null, "tags": [] }
+```
+`slow` is `true` when `durationMs >= --slow-ms` (also printed as a terminal warning). `rowCount` is best-effort (PostgreSQL command tags; `null` for MySQL). TLS is relayed but not decrypted in v1. Prepared/extended wire protocols are best-effort tagged.
+
+**Log rotation:** all writes are serialized through one in-process chain (concurrent sessions never interleave partial lines). The event log auto-rotates to keep one rolling segment — when the next line would reach ~50 MiB or 200,000 entries, the current file is renamed to `<events>.1` (overwriting any prior segment) and a fresh file starts. Worst-case on-disk footprint is ~2× the byte cap.
+
+**`proxy analyze`** — offline aggregation of the event log (no DB). Flags: `--events <path>` (default `.dbcli/proxy/events.jsonl`), `--format json|text` (default `json`), `--top <n>` (default 20; text rows + suggestedCommands depth), `--slow-ms <ms>` (default 1000; recomputes slowCount), `--n-plus-one <n>` (default 10), `--no-include-rotated`. JSON report blocks: `summary`, `byFingerprint` (sorted by total time; SELECT entries in the top-N carry `suggestedCommands` for `explain` / `guide missing-index-for`), `slowest`, `errors`, `hotTables`, `repetition` (N+1 suspects). Reads the current log plus the rotated `.1` segment by default.
+
+**Engines:** MySQL / MariaDB / PostgreSQL
+**Permission:** n/a (acts as a TCP relay; does not use dbcli's SQL permission model)
+
 ### status
 
 Show current configuration status (safe for AI agents, no credentials exposed).
@@ -1138,26 +1226,28 @@ dbcli migrate drop-enum status --execute --force
 
 ### skill
 
-Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or one of
-four AI-agent platform directories. The skill is the source of truth that lets
-Claude Code / Gemini / Copilot / Cursor know how to drive dbcli safely.
+Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or an
+AI-agent platform directory. The skill is the source of truth that lets
+Claude Code / Gemini / Antigravity / Copilot / Cursor know how to drive dbcli safely.
 
 ```bash
 dbcli skill                                  # print SKILL.md to stdout
 dbcli skill --output ./SKILL.md              # write to a file (no platform install)
 dbcli skill --install claude                 # install to ~/.claude/skills/dbcli/
-dbcli skill --install gemini                 # install to ~/.gemini/skills/dbcli/
+dbcli skill --install gemini                 # install to ~/.gemini/skills/dbcli/ (being phased out)
+dbcli skill --install antigravity            # install to ~/.gemini/antigravity-cli/skills/dbcli/
 dbcli skill --install copilot                # install to .github/skills/dbcli/ (repo-local)
 dbcli skill --install cursor                 # install to .cursor/skills/dbcli/ (repo-local)
 ```
 
 **Options:**
-- `--install <platform>` — `claude` | `gemini` | `copilot` | `cursor`. Writes `SKILL.md` plus `reference.md` next to it so the agent gets progressive disclosure.
+- `--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`.
 
 **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.
-- `claude` / `gemini` install paths are user-global; `copilot` / `cursor` are repo-local under `.github/` / `.cursor/`.
+- `claude` / `gemini` / `antigravity` install paths are user-global; `copilot` / `cursor` are repo-local under `.github/` / `.cursor/`.
+- `gemini` (Gemini CLI) is retained for now but is being phased out in favour of `antigravity` (Antigravity CLI), Google's successor terminal agent.
 - Re-running `--install` overwrites the existing skill atomically; no prompt.
 
 **Permission:** n/a.