@carllee1983/dbcli 1.44.1 → 1.45.1

package/README.zh-TW.md

@@ -172,6 +172,18 @@ dbcli init --conn-name staging --env-file .env.staging
 dbcli init --conn-name prod --env-file .env.production --use-env-refs
 ```
 
+若要讓多個專案共用連線，請使用 user-global scope。它會把 v2 registry 儲存在 `~/.config/dbcli/config.json`，且不會修改目前專案的 `.dbcli` binding：
+
+```bash
+dbcli --global init --conn-name shared --system postgresql --host db.example.com \
+  --port 5432 --user app --password '<secret>' --name appdb \
+  --skip-test --no-interactive --force
+dbcli --global use --list --format json
+dbcli --global query "SELECT 1"
+```
+
+Root 層級的 `--global` 必須放在指令之前。未帶它時，指令仍會使用專案設定。
+
 每一條具名連線可以設定不同的 **`--permission`**（例如正式環境只給 `query-only`）。現在專案內的 `.dbcli` 主要扮演**綁定 + 快取層**；真正的連線設定會存到使用者家目錄下的 `~/.config/dbcli/projects/<project-id>/`，避免敏感設定留在工作區。
 
 ### 管理連線（`use` / 移除 / 更名）
@@ -969,6 +981,7 @@ dbcli plan "SELECT id FROM users WHERE id = 1 LIMIT 1" --format json
 | 旗標 | 說明 |
 |------|------|
 | `--config <path>` | `.dbcli` 設定檔路徑（預設：`.dbcli`） |
+| `--global` | 使用 `~/.config/dbcli/config.json` 的 user-global registry |
 | `--use <connection>` | 僅本次指令使用具名的 v2 連線（不變更預設連線） |
 | `-v, --verbose` | 提高詳細度（`-v` 詳細、`-vv` 除錯） |
 | `-q, --quiet` | 抑制非必要輸出 |

package/assets/SKILL.md

@@ -21,6 +21,20 @@ the CLI package has not been installed globally.
 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**.
 
+**Environment and mutation boundary:** In v2, inspect `dbcli use --list --format json`
+before selecting a named connection. A connection labelled `environment: "production"`
+must be explicitly selected; it is never silently used through the saved default. To
+persist a production default, a human must repeat the exact name with
+`--confirm-production`. When `DBCLI_AGENT_MODE=1`, configuration, permission, and
+credential mutations are blocked unconditionally. Run human/admin changes in a separate
+process with agent mode disabled; do not treat a same-process environment variable as
+approval. Trusted config writes maintain an integrity record and secure file modes where
+supported, and agent reads fail closed on missing, replaced, non-regular, or tampered
+records. Agent mode refuses legacy single-file `.dbcli` configs until a human/admin
+migration to V2 home storage. For a same-user hostile process, a host can set
+`DBCLI_CONFIG_INTEGRITY_ANCHOR_DIR` to a protected or read-only directory containing
+detached digests.
+
 **`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`
@@ -238,7 +252,7 @@ dbcli init --system elasticsearch \
 ```bash
 dbcli init --conn-name staging --env-file .env.staging --permission query-only
 dbcli init --conn-name prod    --env-file .env.production --use-env-refs --skip-test
-dbcli use --list                          # show all, * marks default
+dbcli use --list --format json            # safe identity inventory: name/env/permission/server/database
 dbcli use prod                            # switch default (persists — avoid for one-off queries)
 dbcli query --use staging "SELECT 1"      # one-shot override on any subcommand
 DBCLI_CONNECTION=staging dbcli query "SELECT 1"   # one-shot via env; parallel-safe
@@ -247,6 +261,18 @@ dbcli init --rename staging:stg           # rename
 dbcli init --remove stg                   # remove
 ```
 
+For a connection shared across projects, use the explicit root-level `--global` scope. It stores a v2 registry at `~/.config/dbcli/config.json`; it does not create or modify a project binding:
+
+```bash
+dbcli --global init --conn-name shared --system postgresql --host db.example.com \
+  --port 5432 --user app --password '<secret>' --name appdb \
+  --skip-test --no-interactive --force
+dbcli --global use --list --format json
+dbcli --global query "SELECT 1"
+```
+
+`--global` must appear before the command. Without it, commands continue to use the current project's `.dbcli` binding; global and project registries are independent.
+
 Each named connection has its own schema cache at `.dbcli/schemas/<connection>/`. Run
 `dbcli schema --use <name>` once per connection **before** `schema <table>` — otherwise the
 cache may serve another connection's columns. `schema --refresh` / `--reset` manage the cache
@@ -313,6 +339,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `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. |
+| `backfill artifact` | n/a | Build a bounded, reviewable source-to-SQL backfill artifact from JSON. Includes source/target identity, blacklist/schema preflight, read-back verification, and rollback hints; dry-run only and never executes writes. |
 | `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`, `--slow-ms` (default `1000`), `--redact none\|literals`. 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) — errors out if no events exist yet. |
 | `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`. |
@@ -320,7 +347,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `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. |
+| `doctor` | n/a | Environment/runtime identity, config, connection, SRV diagnostics (Mongo), schema cache age. `--format json --remediation` emits candidate-only blacklist/schema/bounded-sample plans (SQL: `dbcli plan` → human-confirmed bounded `dbcli query`; MongoDB/Elasticsearch: `dbcli schema` preflight → human-confirmed bounded query); it never applies them. |
 | `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). |
@@ -509,4 +536,4 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 - Blacklisted tables and columns are redacted from query output.
 - `schema` reports `estimatedRowCount` and `sizeCategory` (small / medium / large / huge). For large/huge tables add `WHERE` or `LIMIT` — bands in reference.md.
 - `doctor` on `mongodb+srv://` reports whether SRV resolves natively or through the DoH fallback — useful when the runtime restricts DNS.
-- **Global flags:** `--config <path>`, `--use <name>`, `-v` / `-vv` / `-q`, `--no-color` (also honours `NO_COLOR`).
+- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.

package/assets/SKILL.zh-TW.md

@@ -18,6 +18,16 @@ description: Database CLI for AI agents with permission-based access control. Us
 3. 所有寫入：`--dry-run`（SQL / Mongo）→ 實際執行 → `query` 回讀確認。Redis 的 `query`
    **沒有 `--dry-run`**（見 **Redis** 節）；Elasticsearch 為**唯讀**。
 
+**環境與變更邊界：** 在 v2 中，選取具名連線前先執行 `dbcli use --list --format json`。
+標示 `environment: "production"` 的連線不得透過儲存的預設值靜默選取，必須明確指定；若要
+持久化 production 預設值，人類需以 `--confirm-production` 重複完全相同的名稱。當
+`DBCLI_AGENT_MODE=1` 時，設定、權限與憑證變更一律封鎖。人類／管理員變更必須在關閉 agent
+mode 的獨立 process 執行；不要把同一 process 的環境變數當作核准。受信任設定寫入會維護
+integrity record，並在支援時設定安全檔案權限；agent 讀取遇到缺失、替換、非一般檔案或竄改的
+record 時會 fail closed；agent mode 在完成 human/admin 遷移到 V2 home storage 前也會拒絕
+legacy 單檔 `.dbcli`。若要防護同一 OS 使用者的惡意 process，host 可將
+`DBCLI_CONFIG_INTEGRITY_ANCHOR_DIR` 設為受保護或唯讀掛載的 detached digest 目錄。
+
 **`update` / `delete` 的 `--where` 僅支援等式（SQL）。** 只接受 `col=val` 或
 `col1=v1 AND col2=v2`。比較 / 模式運算子（`>`、`>=`、`<`、`!=`、`LIKE`、`IN`）會直接
 **報錯**；更危險的是，`OR` 會被**靜默當成值的一部分** — `a=1 OR b=2` 會被解析成
@@ -191,7 +201,7 @@ dbcli init --system elasticsearch \
 ```bash
 dbcli init --conn-name staging --env-file .env.staging --permission query-only
 dbcli init --conn-name prod    --env-file .env.production --use-env-refs --skip-test
-dbcli use --list                          # show all, * marks default
+dbcli use --list --format json            # 安全列出 name/env/permission/server/database
 dbcli use prod                            # switch default（會持久化 — 單次查詢別用）
 dbcli query --use staging "SELECT 1"      # one-shot override on any subcommand
 DBCLI_CONNECTION=staging dbcli query "SELECT 1"   # 單次指定，env 版；平行安全
@@ -200,6 +210,18 @@ dbcli init --rename staging:stg           # rename
 dbcli init --remove stg                   # remove
 ```
 
+若要讓多個專案共用連線，請使用明確的 root-level `--global` scope。它會把 v2 registry 儲存在 `~/.config/dbcli/config.json`，不會建立或修改專案 binding：
+
+```bash
+dbcli --global init --conn-name shared --system postgresql --host db.example.com \
+  --port 5432 --user app --password '<secret>' --name appdb \
+  --skip-test --no-interactive --force
+dbcli --global use --list --format json
+dbcli --global query "SELECT 1"
+```
+
+`--global` 必須放在指令之前。未帶它時，指令仍使用目前專案的 `.dbcli` binding；全域與專案 registry 彼此獨立。
+
 每個命名連線的 schema cache 存於 `.dbcli/schemas/<connection>/`。在 `schema <table>` 前，每個連線都先跑一次 `dbcli schema --use <name>` — 否則 cache 可能回傳到別的連線欄位。`schema --refresh` / `--reset` 管理 cache（reference.md）。`--skip-test` 跳過 init 時的 TCP 連線測試；使用 `--use-env-refs` 時會自動隱含（`$env` refs 尚無值可連線）。`--system` 在 v2 中為選填 — 若省略，引擎會從 `--env-file` / `.env`（`DATABASE_URL` scheme）推斷，預設為 `postgresql`。
 
 ### env-refs（把機密排除在 `.dbcli` 之外）
@@ -251,6 +273,7 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 | `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。 |
+| `backfill artifact` | n/a | 將受限 JSON source catalog 產生可檢閱的 source-to-SQL 回填 artifact，包含 source/target identity、blacklist/schema preflight、read-back 驗證與 rollback hint；只產生 dry-run，絕不執行寫入。 |
 | `proxy` | n/a | **(v1.26)** 僅 MySQL/MariaDB/PostgreSQL。本地端開發觀測代理 — 中繼應用程式流量至真實資料庫，並將查詢 / 延遲 / 位元組 / 錯誤事件附加到 `.dbcli/proxy/events.jsonl`。子指令：`mysql` \| `mariadb` \| `postgresql`。`--listen`、`--target`、`--events`、`--slow-ms`（預設 `1000`）、`--redact none\|literals`。僅作觀測。**(v1.27)** `proxy analyze` 離線彙整事件 log 為 JSON / 文字報表（summary、byFingerprint 含 suggestedCommands、slowest、errors、hotTables、N+1）— 若無事件則報錯。 |
 | `status` | query-only+ | 安全 JSON / 文字摘要（不含憑證）。 |
 | `inspect` | query-only+ | 唯讀脈絡快照（連線、權限、blacklist、物件、snippets、建議指令，以及 **(v1.23)** 人類可讀 `hints`）。`--for-agent` / `--brief` / `--no-connect` / `--require-schema-cache`。支援 `--recovery`。 |
@@ -258,7 +281,7 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 | `guide` | query-only+ | 針對固定目標產出確定性下一步指令計畫（`slow-query`、`capacity`、`health`、`index-usage`、`permissions`、`schema-overview`）。`--list` 列舉所有目標。**(v1.23)** `guide missing-index-for <query>` 為單一 SELECT 建議複合索引（`--format yaml\|json\|markdown`、`--min-confidence`）。 |
 | `recovery` | n/a | 對已知錯誤代碼查詢結構化 `RecoveryEnvelope`（`--code <CODE>` 或 `--list`）。獨立合成器；不需真實失敗。 |
 | `recover` | n/a | 檢視（預設）或 `--apply` 執行 `.dbcli/last-recovery.json` 中自動儲存的復原計畫。`--allow-write=readonly-cmd\|write-cmd`、`--no-verify`、`--from <file>`、`--next --after-step <n> --result <json\|@file>` 多輪逐步執行。 |
-| `doctor` | n/a | 環境、設定、連線、SRV 診斷（Mongo）、schema cache 年齡。 |
+| `doctor` | n/a | 環境/runtime identity、設定、連線、SRV 診斷（Mongo）、schema cache 年齡。`--format json --remediation` 僅輸出 blacklist/schema/bounded-sample 候選計畫（SQL：`dbcli plan` → 人工確認後的 bounded `dbcli query`；MongoDB/Elasticsearch：先以 `dbcli schema` 預檢，再由人工確認 bounded query），不會套用。 |
 | `completion` | n/a | bash / zsh / fish 腳本。 |
 | `upgrade` | n/a | 從 npm 自我更新；每個指令都帶 24h 快取的版本提示。 |
 | `shell` | (與 query 同) | 互動式 REPL。SQL 引擎、MongoDB 與 Redis（單行；`.no-limit on/off`）。**(v1.22)** Elasticsearch 開啟 Kibana Dev Tools 風格的 REPL（`<METHOD> /<path>` + 可選 JSON body，空白行送出）。 |
@@ -403,4 +426,4 @@ dbcli export "SELECT * FROM orders" --format html --output orders.html
 - 被 blacklist 的 table / column 會從查詢輸出中遮蔽。
 - `schema` 回報 `estimatedRowCount` 與 `sizeCategory`（small / medium / large / huge）。大 / 巨大表要加 `WHERE` 或 `LIMIT` — 分界值見 reference.md。
 - 對 `mongodb+srv://` 連線，`doctor` 會回報 SRV 是用原生解析或走 DoH fallback — 在執行環境限制 DNS 時很有用。
-- **全域旗標：** `--config <path>`、`--use <name>`、`-v` / `-vv` / `-q`、`--no-color`（也尊重 `NO_COLOR`）。
+- **全域旗標：** `--version`、`--config <path>`、`--global`、`--use <name>`、`-v` / `--verbose` / `-vv`、`-q` / `--quiet`、`--no-color`（也尊重 `NO_COLOR`）。除非指令明確宣告 command-level 選項，否則 root-level 旗標必須放在指令之前。

package/assets/reference.md

@@ -4,6 +4,22 @@ Companion to [SKILL.md](SKILL.md). Exhaustive flags, copy-paste examples, `shell
 
 For cross-engine support status, see `docs/feature-matrix.md` in the repository.
 
+## Global options and placement
+
+These options are available on the root `dbcli` command. Root-level options must
+appear before the command path (for example, `dbcli --use prod status`). A
+command-level option is only valid after the command that declares it.
+
+| Option | Purpose |
+|---|---|
+| `--version` | Print the installed dbcli version. |
+| `--no-color` | Disable colored output. |
+| `-v, --verbose` | Increase logging verbosity; repeat for debug output. |
+| `-q, --quiet` | Suppress non-essential output. |
+| `--config <path>` | Select the `.dbcli` configuration path. |
+| `--global` | Select the user-global registry at `~/.config/dbcli/config.json` instead of the current project's `.dbcli` config. Place it before the command path. |
+| `--use <connection>` | Select a named connection for this invocation; place it before the command path unless that command explicitly lists a command-level `--use`. |
+
 ## Commands
 
 ### init
@@ -34,10 +50,18 @@ dbcli init --conn-name staging --env-file .env.staging   # Named connection with
 dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-test
 dbcli init --remove staging                              # Remove a named connection
 dbcli init --rename staging:production                   # Rename a connection
+
+# User-global registry (shared by projects; --global must precede the command)
+dbcli --global init --conn-name shared --system postgresql --host db.example.com \
+  --port 5432 --user app --password '<secret>' --name appdb \
+  --skip-test --no-interactive --force
+dbcli --global use --list
 ```
 
 **Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
 
+**Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
+
 **MongoDB-specific options:** `--uri <uri>` (full connection URI), `--auth-source <db>` (auth database, default: `admin` when user/password set)
 
 **Elasticsearch-specific options:** `--cloud-id <id>` (Elastic Cloud), `--api-key <key>` (ApiKey auth). Other ES fields (`nodes[]`, `protocol`, `caPath`, `rejectUnauthorized`) can be edited directly in `.dbcli`.
@@ -46,6 +70,8 @@ dbcli init --rename staging:production                   # Rename a connection
 
 **Multi-connection:** Using `--conn-name` or `--env-file` creates a v2 config with named connections. Each connection can have its own env file and permission level. Existing v1 configs are automatically imported as the `default` connection when upgrading.
 
+Use root-level `--global` with `init`, `use`, `status`, `query`, or any other command to read or mutate the user-global v2 registry at `~/.config/dbcli/config.json`. Without it, the current project binding remains the source of truth. The global registry uses the same private file mode and integrity record as project home storage.
+
 > **AI agent note on `--use-env-refs`:** If an existing `.dbcli` config contains `{"$env": "DB_HOST"}` style references, the connection values are read from environment variables at runtime. Do NOT re-run `init` to replace these references with actual values — the env-ref format is intentional for CI/CD and multi-environment setups.
 
 ### use
@@ -56,8 +82,20 @@ Switch or display the default database connection (v2 multi-connection config).
 dbcli use                   # Show current default connection
 dbcli use staging           # Switch default to 'staging'
 dbcli use --list            # List all connections (* marks default)
+dbcli use --list --format json # Credential-free connection identity inventory
 ```
 
+Each v2 named connection may include an optional non-secret `environment` label
+(for example, `"environment": "production"`). JSON output is an object with a
+`connections` array. Each item contains `name`, `environment` (a string or
+`null`),
+`permission`, `system`, `server` (`host` and `port`), `database`, and `isDefault`.
+Environment-backed server and database fields are `null`; URI-only MongoDB and
+Cloud ID-only Elasticsearch connections also return `null` instead of default
+placeholders. It deliberately excludes user names, passwords, URIs, Cloud IDs,
+API keys, and env variable names.
+Misspelled selectors suggest nearby configured connection names.
+
 Any command can also use `--use <name>` to temporarily select a connection without changing the default:
 
 ```bash
@@ -67,6 +105,18 @@ dbcli list --use prod
 
 **Requires v2 config** (created with `dbcli init --conn-name`).
 
+**Options:** `--list`, `--format <text|json>`, `--confirm-production <name>` (required when explicitly selecting a production connection as the default).
+
+### Agent configuration trust boundary
+
+When `DBCLI_AGENT_MODE=1`, configuration, permission, and credential mutations
+are rejected. Agent reads require the V2 directory config and its integrity
+record; missing, replaced, non-regular, or tampered records fail closed. Legacy
+single-file `.dbcli` configs must be migrated by a human/admin process with
+agent mode disabled. A host that needs protection from a same-user hostile
+process can set `DBCLI_CONFIG_INTEGRITY_ANCHOR_DIR` to a protected or read-only
+directory; trusted writes publish detached digests there.
+
 ### list
 
 List all tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch).
@@ -746,6 +796,7 @@ Manage sensitive data blacklist to prevent AI access to restricted tables/column
 
 ```bash
 dbcli blacklist list                        # Show current blacklist
+dbcli blacklist list --format json          # Stable machine-readable result
 dbcli blacklist table add payments          # Block entire table
 dbcli blacklist table remove payments       # Unblock table
 dbcli blacklist column add users.password   # Block specific column
@@ -754,6 +805,11 @@ dbcli blacklist column remove users.password
 
 **Subcommands:** `list`, `table add <name>`, `table remove <name>`, `column add <table.column>`, `column remove <table.column>`
 
+**`list` options:** `--config <path>`, `--format <text|json>` (default: `text`). JSON writes one
+document to stdout: `{ "tables": string[], "columns": Record<string, string[]>, "warnings":
+[{ "collection", "raw", "reason" }] }`. Invalid MongoDB blacklist patterns appear in `warnings`;
+the JSON result is otherwise free of human headings and diagnostics.
+
 ### check
 
 Run data health checks on tables.
@@ -1079,7 +1135,7 @@ 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 --use prod proxy postgresql                         # 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
@@ -1489,6 +1545,7 @@ Audit entries are metadata-only by design — never raw SQL bodies, `--param` va
 | `--all` | Merge entries across all connections; output is an envelope array `[{ connection, entry }, ...]` (D-39). | off (current connection only) |
 | `--for-agent` | Shortcut for `--format json --brief`. Single-connection JSON is a flat array; `--all` JSON is an envelope array. | off |
 | `--brief` | Drop large redaction fields from the entry; keep `ts / command / target / success` (D-33). | off |
+| `--no-brief` | Disable brief mode when a higher-level default enables it. | off |
 | `--format <fmt>` | `table` \| `json`. | `table` |
 
 Reader behavior (D-41): tail merges `<conn>.jsonl.1` (rotated segment, if present) and `<conn>.jsonl`, sorts by `ts` ascending, then takes the last `--n` entries — so `--n 1000` can span a fresh rotation boundary.
@@ -1506,6 +1563,7 @@ Examples:
 | `<id-prefix>` | Positional. UUID or prefix ≥ 4 characters; ambiguous prefix exits 1 with disambiguation hint; prefix < 4 chars exits 1. | — |
 | `--recovery-ref <id>` | Find the audit entry whose `recovery_ref` field matches this id (exact, not prefix). Mutually exclusive with positional `<id-prefix>` (D-38). | — |
 | `--all` | Search across all connections. Output is an envelope `{ connection, entry }` (single-hit also envelope, for shape stability — D-36). | off |
+| `--no-brief` | Disable brief mode when a higher-level default enables it. | off |
 | `--format <fmt>` | `table` \| `json`. | `table` |
 
 Examples:
@@ -1532,6 +1590,7 @@ Examples:
 | Flag | Purpose | Default |
 |---|---|---|
 | `--format <fmt>` | `table` \| `json`. | `table` |
+| `--no-brief` | Disable brief mode when a higher-level default enables it. | off |
 
 Output reports: writer enabled/disabled, last write result, file-lock state, rotation cap usage (`max_bytes` / `max_entries`). When `audit.enabled = false` (D1 opt-out), `tail` / `show` / `health` still exit 0 and print `Audit is disabled (audit.enabled = false in .dbcli). Use 'dbcli audit health' for details.` (E note).
 
@@ -1919,6 +1978,39 @@ includes `storageDir`, `dryRun`, `cutoff`, `criteria`, `protected`, `candidates`
 
 **Permission:** n/a
 
+### backfill
+
+Generate a bounded, reviewable source-to-SQL backfill artifact. The command is
+strictly dry-run: it reads a local JSON source catalog, records non-secret
+source/target connection identity, and never opens a database connection or
+executes generated SQL.
+
+```bash
+dbcli backfill artifact \
+  --source ./backfill.json \
+  --source-use staging \
+  --target-use production
+dbcli backfill artifact --source ./backfill.json \
+  --source-use staging --target-use production --stdout
+dbcli backfill artifact --source ./backfill.json \
+  --source-use staging --target-use production --out .dbcli/backfills/review.json
+```
+
+The source catalog must contain `table`, non-empty `keyColumns`, `rows`, a
+read-only `verifyQuery`, and `expect`; no more than 1,000 rows are accepted.
+Identifiers are validated and row values are limited to JSON scalars. The
+target connection must be PostgreSQL, MySQL, or MariaDB (the source identity
+may describe another engine); target selectors in generated commands are
+shell-quoted. The artifact includes a SHA-256 source fingerprint, generated parameterized
+`UPDATE` statements with per-statement `plan` commands, blacklist/schema
+preflight commands, a `verify safe-backfill` read-back command, identity
+differences, and a rollback hint. `execution.mode` is always `dry-run` and
+`requiresHumanConfirmation` is always true; applying SQL is a separate,
+explicit human-reviewed workflow.
+
+**Options:** `--source <path>` (required), `--source-use <name>` (required),
+`--target-use <name>` (required), `--stdout`, `--out <path>`
+
 ### doctor
 
 Run diagnostic checks on environment, configuration, connection, and data.
@@ -1936,7 +2028,13 @@ dbcli doctor --format json      # JSON output for AI agents
 > **MongoDB SRV diagnostics:** When the active connection uses `mongodb+srv://`, `doctor` reports whether the current runtime can resolve SRV records directly or only through the DNS-over-HTTPS fallback used by dbcli. This helps spot execution-environment DNS restrictions even when Compass can connect.
 
 **Exit code:** 0 if all pass or warnings only, 1 if any error
-**Options:** `--format <text|json>`
+**Options:** `--format <text|json>`, `--remediation`
+
+With `--format json --remediation`, large-table warnings include one bounded
+sample candidate per table. SQL candidates first run `dbcli plan` for a `LIMIT
+100` read; MongoDB and Elasticsearch candidates first run `dbcli schema` as a
+preflight. Each then offers a matching bounded `dbcli query` as the
+human-confirmed apply step; doctor never runs either command automatically.
 
 ### completion
 

package/dist/agent-core.mjs

@@ -57,15 +57,26 @@ function trimAppliedLimit(rows, limit) {
   };
 }
 // src/agent-core/connection-selector.ts
+function normalizeSelector(value, source) {
+  if (value === undefined)
+    return;
+  const normalized = value.trim();
+  if (normalized === "") {
+    throw new Error(`${source} connection selector cannot be empty`);
+  }
+  return normalized;
+}
 function resolveConnectionSelector(inputs) {
-  if (inputs.root !== undefined && inputs.command !== undefined && inputs.root !== inputs.command) {
-    throw new Error(`Conflicting connection selectors: root value '${inputs.root}' does not match command value '${inputs.command}'`);
+  const root = normalizeSelector(inputs.root, "Root");
+  const command = normalizeSelector(inputs.command, "Command");
+  if (root !== undefined && command !== undefined && root !== command) {
+    throw new Error(`Conflicting connection selectors: root value '${root}' does not match command value '${command}'`);
   }
-  const explicit = inputs.command ?? inputs.root;
+  const explicit = command ?? root;
   if (explicit !== undefined)
     return explicit;
   const environment = inputs.environment?.trim();
-  return environment ? environment : undefined;
+  return environment || undefined;
 }
 function parseConnectionNames(selector) {
   const names = selector.split(",").map((name) => name.trim());