@carllee1983/dbcli 1.44.0 → 1.45.0

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.43.0",
+  "version": "1.45.0",
   "description": "Database CLI skill and command reference for AI agents.",
   "contextFileName": "AGENTS.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.44.0",
+  "version": "1.45.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {
@@ -73,6 +73,7 @@
     "test:integration": "bun test tests/integration",
     "test:docker": "docker compose -f docker-compose.test.yml up -d --wait && bun test tests/integration/adapters; docker compose -f docker-compose.test.yml down",
     "docs:check": "bun run scripts/check-user-docs.ts",
+    "contract:check": "bun run scripts/check-cli-contract.ts",
     "skill:check": "bun run scripts/check-skill-parity.ts",
     "platform:check": "bun run scripts/check-platform-parity.ts",
     "agent-core:check": "bun run scripts/check-agent-core-purity.ts",

package/plugins/dbcli-agent/.codex-plugin/plugin.json

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

package/plugins/dbcli-agent/skills/dbcli/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/plugins/dbcli-agent/skills/dbcli/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/skills/dbcli/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/skills/dbcli/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