@carllee1983/dbcli 1.52.0 → 1.53.0

package/plugins/dbcli-agent/skills/dbcli/reference.md

@@ -4,6 +4,69 @@ 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.
 
+## Index
+
+Jump straight to what you need — this file is long, and reading it end to end is
+never the right move.
+
+| Section | What is in it |
+|---|---|
+| [Global options and placement](#global-options-and-placement) | Flags that must precede the command (`--use`, `--config`), and [redirecting output](#redirecting-output). |
+| [Commands](#commands) | Every command, one `###` each — see the command list below. |
+| [Recovery Cookbook](#recovery-cookbook-agent-walkthroughs) | Failure-to-fix walkthroughs S1–S6, the [scenario index](#scenario-index), [risk gate cheat sheet](#risk-gate-cheat-sheet), and [common pitfalls](#common-pitfalls). |
+| [Interactive HTML dashboard](#interactive-html-dashboard) | `--ui` / `--format html`: [entry points](#entry-points), [data injection contract](#data-injection-contract), [`meta` shape](#meta-shape). |
+| [MongoDB Support](#mongodb-support) | Connection shapes, JSON query bodies, write-stage guard. |
+| [Redis Support](#redis-support) | Command permission tiers, size guards, key masking. |
+| [Elasticsearch Support](#elasticsearch-support) | DSL and Lucene queries, scroll export, mapping flattening. |
+
+**Commands** —
+[init](#init) ·
+[use](#use) ·
+[list](#list) ·
+[schema](#schema) ·
+[query](#query) ·
+[explain](#explain) ·
+[lint](#lint) ·
+[plan](#plan) ·
+[q](#q) ·
+[queries](#queries) ·
+[insert](#insert) ·
+[update](#update) ·
+[delete](#delete) ·
+[export](#export) ·
+[blacklist](#blacklist) ·
+[check](#check) ·
+[diff](#diff) ·
+[design](#design) ·
+[impact assess](#impact-assess) ·
+[snapshot](#snapshot) ·
+[assert](#assert) ·
+[proxy](#proxy) ·
+[status](#status) ·
+[inspect](#inspect) ·
+[report](#report) ·
+[guide](#guide) ·
+[recovery](#recovery) ·
+[recover](#recover) ·
+[audit](#audit) ·
+[verify](#verify) ·
+[verification](#verification) ·
+[backfill](#backfill) ·
+[evidence](#evidence) ·
+[doctor](#doctor) ·
+[completion](#completion) ·
+[upgrade](#upgrade) ·
+[shell](#dbcli-shell) ·
+[migrate](#migrate) ·
+[semantic](#semantic) ·
+[contract](#contract) ·
+[skill](#skill) ·
+[skill context](#skill-context) ·
+[skill tasks](#skill-tasks-agent-task-packs)
+
+Also worth knowing before you connect:
+[Agent configuration trust boundary](#agent-configuration-trust-boundary).
+
 ## Global options and placement
 
 These options are available on the root `dbcli` command. Root-level options must
@@ -561,13 +624,15 @@ dbcli q @analytics/revenue --param days=30 --format html > report.html
 - `--ui` — open the rendered HTML dashboard in the system browser (implies `--format html`; writes to a temp file then invokes `open` / `xdg-open` / `start`)
 - `--param <key=value>` — pass a parameter (repeatable)
 - `--param-file <path>` — JSON object whose keys are param names
-- `--no-limit` — skip the `SELECT * FROM (…) AS _dbcli_guard LIMIT 1000` wrap
+- `--no-limit` — skip the `SELECT * FROM (…) AS _dbcli_guard LIMIT 1001` wrap (the effective cap is 1000; one extra row is fetched to detect truncation)
 - `--dry-run` — print the bound SQL + values without executing
-- `--use <name>` — pick a v2 named connection
 - `--slow-ms <number>` — passive slow-query hint threshold (default `1000`; `0` disables). Same contract as `query` — see "Passive slow-query hint" there
 - `--recovery` — emit a `RecoveryEnvelope` on failure (see `recover`)
 - `--verify` — run the snippet's verification assertions after execution (only if the snippet defines them)
 
+`q` has no command-level `--use`. To run a snippet against a v2 named connection,
+use the global form: `dbcli --use <name> q @<snippet>`.
+
 **Permission:** query-only+
 
 #### Snippet file format
@@ -691,8 +756,9 @@ Size guard: `LRANGE` / `ZRANGE` stop overridden when `< 0` or `> 1000`; `SCAN` /
 ##### MongoDB snippets
 
 File extension: `.mongodb.sql`. Frontmatter must declare `engine: mongodb` and
-`operation: find` or `operation: aggregate`. `target: <collection>` provides a default
-collection that `dbcli q --collection <name>` can override. The body is JSON: an object
+`operation: find` or `operation: aggregate`. `target: <collection>` declares the
+collection the snippet runs against; the CLI has no flag to override it, so a different
+collection means a different snippet. The body is JSON: an object
 for `find` and an array for `aggregate`. Each `{{param}}` placeholder is JSON-encoded
 at substitution time — strings are quoted and escaped, so an attacker-supplied string
 cannot escape into operator position.
@@ -1126,6 +1192,7 @@ dbcli design validate [--file <path>] [--format <format>]
 dbcli design render [--file <path>] [--format <format>]
 dbcli design diff (--against-cache | --against-orm <paths>) [options]
 dbcli design propose (--against-cache | --against-orm <paths>) [options]
+dbcli impact assess --design <path> (--against-cache | --against-orm <paths>) --output <path> [options]
 ```
 
 ```bash
@@ -1137,6 +1204,7 @@ dbcli design render --format mermaid
 dbcli design diff --against-cache --format markdown
 dbcli design diff --against-orm ./prisma/schema.prisma --format markdown
 dbcli design propose --against-orm ./prisma/schema.prisma --format markdown
+dbcli impact assess --design ./dbcli.design.json --against-cache --output ./impact.json --fail-on warn
 ```
 
 | Option | Applies to | Default | Meaning |
@@ -1153,8 +1221,14 @@ dbcli design propose --against-orm ./prisma/schema.prisma --format markdown
 `diff` and `propose` require **exactly one** comparison target; passing both or
 neither is an error.
 
+### impact assess
+
+Writes an offline JSON or Markdown report for the known declared impact of a design change. It requires `--design`, exactly one baseline (`--against-cache` or `--against-orm`), and an explicit workspace-contained `--output`. `--format` is `json` (default) or `markdown`; `--fail-on` is `error`, `warn`, or `never` (default). The threshold changes only the successful command exit code after the report is written. The report is limited to declared/partial coverage and never claims complete coverage. It may join the optional reviewed `dbcli.data-access.json` manifest only after validating its canonical semantic references and existing workspace-relative source paths; it never reads those sources. An optional explicit `--events <path>` is bounded and streamed through a redaction-first projection that retains recent safe table metadata only. It never starts a proxy, reads a rotated log, renders SQL/literals/errors/sessions/paths, or makes the command fail solely because workload evidence is absent or advisory. It reads no database, executes no SQL, and never reads saved-query bodies.
+
 #### Artifact shape
 
+This example validates clean (0 errors, 0 warnings):
+
 ```json
 {
   "version": 1,
@@ -1166,14 +1240,24 @@ neither is an error.
       "description": "Completed purchases.",
       "fields": [
         { "name": "id", "type": "bigint", "nullable": false, "primaryKey": true, "unique": true },
-        { "name": "customer_id", "type": "bigint", "nullable": false, "primaryKey": false, "unique": false }
+        { "name": "customer_id", "type": "bigint", "nullable": false },
+        { "name": "created_at", "type": "timestamptz", "nullable": false }
       ],
-      "indexes": [{ "name": "orders_customer_idx", "columns": ["customer_id"], "unique": false }]
+      "indexes": [
+        { "name": "orders_customer_idx", "columns": ["customer_id", "created_at"], "unique": false }
+      ]
+    },
+    {
+      "name": "customers",
+      "table": "customers",
+      "fields": [
+        { "name": "id", "type": "bigint", "nullable": false, "primaryKey": true, "unique": true }
+      ]
     }
   ],
   "relationships": [
     {
-      "name": "orders_customer",
+      "name": "orders-customer",
       "from": { "model": "orders", "field": "customer_id" },
       "to": { "model": "customers", "field": "id" },
       "cardinality": "many-to-one"
@@ -1188,11 +1272,38 @@ It holds no SQL, credentials, rows, or provider configuration. `design init`
 emits this envelope with empty `models`, `relationships`, `accessPatterns`, and
 `decisions`.
 
+#### Naming and limits
+
+Two different naming rules apply, and mixing them up is the most common way an
+artifact fails before any review rule runs.
+
+| Applies to | Rule |
+|---|---|
+| `models[].name`, `relationships[].name`, `relationships[].from/to.model`, `accessPatterns[].model`, `decisions[].name` | lowercase kebab-case, `^[a-z][a-z0-9-]*$` — underscores are rejected |
+| `models[].table`, `fields[].name`, `indexes[].name`, `indexes[].columns[]`, `filters[]`, `sort[]` | SQL identifier, `^[A-Za-z_][A-Za-z0-9_]*$` |
+
+Relationship endpoints reference a **model name**, not a table name. Every object
+is strict: an unknown key is an error, not ignored. `description` and `rationale`
+are 1–1000 characters and must not contain SQL keywords or a connection string —
+"rows we delete after 30 days" is rejected for the word `delete`. `fields[].type`
+is at most 100 characters with no `;` or newline. `primaryKey`, `unique`,
+`indexes`, `filters`, `sort`, `relationships`, `accessPatterns`, and `decisions`
+may all be omitted.
+
+Limits: file 256 KiB, 100 models, 100 fields per model, 200 relationships,
+200 access patterns, 100 decisions, 1–16 columns per index, ≤16 entries in
+`filters` and `sort`.
+
 #### Review findings
 
 `validate` is fail-closed: any `error` finding exits `1`, and `render`, `diff`,
 and `propose` refuse to do their work while errors remain.
 
+Structural problems — malformed JSON, an unknown key, a naming or type violation,
+a missing file, or a file over 256 KiB — are rejected before review runs and are
+reported as a single `INVALID_ARTIFACT` finding (`error`) whose `path` points at
+the offending JSON location. None of the codes below appear in that case.
+
 | Severity | Codes |
 |---|---|
 | `error` | `NO_MODELS`, `DUPLICATE_MODEL`, `DUPLICATE_TABLE`, `DUPLICATE_FIELD`, `PRIMARY_KEY_COUNT`, `NULLABLE_PRIMARY_KEY`, `UNKNOWN_INDEX_FIELD`, `DUPLICATE_RELATIONSHIP`, `REVERSE_RELATIONSHIP`, `UNKNOWN_RELATIONSHIP_MODEL`, `UNKNOWN_RELATIONSHIP_FIELD`, `RELATIONSHIP_TYPE_MISMATCH`, `MANY_TO_MANY_REQUIRES_BRIDGE`, `ONE_TO_ONE_REQUIRES_UNIQUE_FK`, `UNKNOWN_ACCESS_MODEL`, `UNKNOWN_ACCESS_FIELD` |
@@ -1297,7 +1408,7 @@ Opt-in flag trio that persists a **VerificationArtifact JSON** (schema v1) under
 | Flag | Required | Description |
 | :--- | :--- | :--- |
 | `--write-verification-artifact` | opt-in | Trigger artifact write. No-op when no verdict has been produced. |
-| `--verification-subject <kind:name>` | yes (when flag is set) | Subject identifier. Format: `<kind>:<name>`. Allowed kinds: `recovery`, `task-pack`, `assertion`, `migration`, `backfill`, `manual`. |
+| `--verification-subject <kind:name>` | yes (when flag is set) | Subject identifier. Format: `<kind>:<name>`. Allowed kinds: `recovery`, `task-pack`, `assertion`, `migration`, `backfill`, `table`, `manual`. |
 | `--verification-summary <text>` | no | Free-text summary line stored in the artifact. Default when pass: "Assertion verified the expected state." Default when fail: "Assertion did not verify the expected state." |
 
 **Output contract:**
@@ -1559,7 +1670,7 @@ Examples:
 
 Boundaries:
 - Recovery only **suggests** commands; agents (or humans) execute them. No automatic remediation in v1.15.0.
-- As of v1.16.0, `--recovery` is honored on `query`, `q`, `insert`, `update`, `delete`, `export`, `schema`, and `inspect`. Other commands (`report`, `guide`, `doctor`, `migrate`, `init`, `use`, `status`, `list`, `check`, `diff`, `plan`, `shell`, `blacklist`, `completion`, `upgrade`, `skill`) keep their existing error behavior.
+- `--recovery` is honored on `query`, `q`, `insert`, `update`, `delete`, `export`, `schema`, `inspect`, `lint`, and `diff`. Other commands (`report`, `guide`, `doctor`, `migrate`, `init`, `use`, `status`, `list`, `check`, `plan`, `shell`, `blacklist`, `completion`, `upgrade`, `skill`) keep their existing error behavior.
 - `dbcli inspect --require-schema-cache` throws `SCHEMA_CACHE_MISSING` when the active SQL connection has no usable schema cache. Combine with `--recovery` for the structured envelope.
 - `BLACKLIST_COLUMN_WRITE` and `PERMISSION_DENIED` envelopes prepend a `risk: 'dry-run'` step (e.g. `dbcli insert <table> --dry-run`) when the failing operation was an INSERT / UPDATE / DELETE.
 - Recovery steps reuse the v1.14.0 `GuideStep` shape, including the full `risk` enum (`readonly` / `dry-run` / `write` / `unknown`).
@@ -1593,7 +1704,7 @@ Boundaries:
 |---|---|---|
 | `readonly` | local read-only | `dbcli inspect`, `dbcli doctor`, `dbcli blacklist list`, `dbcli schema <table>` |
 | `dry-run` | write subcommand invoked with `--dry-run` | `dbcli update orders --where id=1 --dry-run`, `dbcli q @x --dry-run` |
-| `local-write` | writes local config / cache / blacklist | `dbcli blacklist remove <table>`, `dbcli use <name>`, `dbcli schema --refresh` |
+| `local-write` | writes local config / cache / blacklist | `dbcli blacklist table remove <table>`, `dbcli use <name>`, `dbcli schema --refresh` |
 | `db-write` | mutates the connected database | `dbcli update orders --where id=1 --set …` (no `--dry-run`), `dbcli q @x` (no `--dry-run`) |
 | `interactive` | requires TTY | `dbcli init`, `dbcli init --force` |
 
@@ -1746,7 +1857,7 @@ dbcli recover --next --after-step 1 --result '{"status":"ok"}' --format markdown
 
 (v1.20.0+) Inspect, query, and manage the per-connection audit log written to `.dbcli/audit/<connection>.jsonl`.
 
-Audit entries are metadata-only by design — never raw SQL bodies, `--param` values, or result cell contents (D3 lock). Redaction is sourced from `tests/helpers/sensitive-output.ts` (same source as `inspect` / `guide` / `recover` agent contracts).
+Audit entries are metadata-only by design — never raw SQL bodies, `--param` values, or result cell contents (D3 lock). Redaction is sourced from `src/utils/redaction.ts` (same source as `inspect` / `guide` / `recover` agent contracts).
 
 #### Subcommands
 
@@ -1783,7 +1894,9 @@ 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 |
+| `--brief` | Trim `metadata` and `redacted_query` from the entry. | off |
+| `--for-agent` | Shortcut for `--format json --brief`. | off |
+| `--no-brief` | Disable brief mode when a higher-level default enables it (e.g. `--for-agent`). | off |
 | `--format <fmt>` | `table` \| `json`. | `table` |
 
 Examples:
@@ -1817,7 +1930,7 @@ Output reports: writer enabled/disabled, last write result, file-lock state, rot
 #### Boundaries
 
 - Entries are append-only JSONL; rotation triggers at `~10 MB` or `~1000` entries (whichever first). Previous segment is preserved as `.jsonl.1`.
-- Bi-directional `recovery_ref` / `audit_ref` linkage is wired on every command that accepts `--recovery`: `query`, `inspect`, `insert`, `update`, `delete`, `export`, `q`, and `schema`. Use `audit tail --recovery-ref <id>` to find the audit entry an envelope was emitted alongside.
+- Bi-directional `recovery_ref` / `audit_ref` linkage is wired on every command that accepts `--recovery`: `query`, `inspect`, `insert`, `update`, `delete`, `export`, `q`, and `schema`. Use `audit show --recovery-ref <id>` to find the audit entry an envelope was emitted alongside.
 - Audit writer failures are non-fatal (D6): main command result and exit code are preserved; a stderr warning is emitted. `audit health` surfaces the failure reason.
 - Reader truncation tolerance: a crash-truncated last line is skipped with a stderr warn `[dbcli audit] skipping truncated last line in <file>`; a mid-file non-JSON line is treated as corruption, exits 1, and points at `dbcli audit clear`.
 
@@ -1835,7 +1948,7 @@ Output reports: writer enabled/disabled, last write result, file-lock state, rot
 ### verify
 
 Run a verification scenario. `verify` **runs** verification scenarios (safe-backfill,
-migration, rollback) and never executes writes/DDL. `verification` **inspects and manages**
+migration, rollback, constraint) and never executes writes/DDL. `verification` **inspects and manages**
 the local result artifacts those scenarios produce under `.dbcli/verification/`.
 
 ```bash
@@ -1847,7 +1960,8 @@ dbcli verify safe-backfill \
   --expect "value == 0"
 
 # After-write: re-run guards, run the read-back assertion, write a v1 artifact.
-dbcli verify safe-backfill ... --after-write
+# An optional receipt is provenance only, never approval to execute a write.
+dbcli verify safe-backfill ... --after-write --evidence-receipt .dbcli/evidence/verify-receipt.json
 
 # JSON for agents.
 dbcli verify safe-backfill ... --format json
@@ -1855,7 +1969,11 @@ dbcli verify safe-backfill ... --format json
 
 Options: `--table` (req), `--query` (req, analyzed not executed), `--verify-query`
 (req, **plain SELECT only**), `--expect` (req), `--after-write`, `--format <table|json>`,
-`--subject-name <name>`, `--summary <text>`.
+`--subject-name <name>`, `--summary <text>`, `--evidence-receipt <workspace-relative-path>`
+(after-write only). A receipt is safe provenance for the already-executed verification,
+not approval to execute a write. Its `succeeded`/`failed` outcome remains distinct from
+the artifact status (`verified`, `not_verified`, `indeterminate`, or `blocked`); task-pack
+`planned` evidence stays plan-only.
 
 Guard constraints (fail closed): `--verify-query` must be a **plain `SELECT`** —
 `EXPLAIN`/`EXPLAIN ANALYZE`, `SHOW`, `DESCRIBE`, and data-modifying CTEs are rejected
@@ -2078,7 +2196,7 @@ dbcli verification list --include-invalid --format json
 | `--format <json\|table>` | Output format. | `json` |
 | `--limit <n>` | Maximum number of entries to return. | `20` |
 | `--status <status>` | Filter by status. One of: `verified`, `not_verified`, `indeterminate`, `blocked`. | all |
-| `--subject <kind[:name]>` | Filter by subject kind or exact `kind:name`. Allowed kinds: `recovery`, `task-pack`, `assertion`, `migration`, `backfill`, `manual`. | all |
+| `--subject <kind[:name]>` | Filter by subject kind or exact `kind:name`. Allowed kinds: `recovery`, `task-pack`, `assertion`, `migration`, `backfill`, `table`, `manual`. | all |
 | `--include-invalid` | Surface malformed artifact files (normally skipped silently). Invalid files are returned as a separate top-level `invalid` array in JSON output, each entry shaped `{ "path": "...", "filename": "...", "error": "..." }`. When off, `invalid` is `[]`. | off |
 
 **Missing directory:** if `.dbcli/verification/` does not exist, exits `0` with an
@@ -2192,6 +2310,7 @@ includes `storageDir`, `dryRun`, `cutoff`, `criteria`, `protected`, `candidates`
 | `assertion` | General-purpose inline assertions. |
 | `migration` | Schema migration pre/post checks. |
 | `backfill` | Data backfill verification assertions. |
+| `table` | `verify constraint` artifacts — the subject name is the table checked. |
 | `manual` | Manually triggered or ad-hoc verification runs. |
 
 **Storage root:** `<cwd>/.dbcli/verification/` (cwd-relative; independent of `--config`).
@@ -2359,6 +2478,66 @@ dbcli migrate drop-enum status --execute --force
 
 **AI agent note:** Always use dry-run first (no `--execute`) to preview generated SQL. Only add `--execute` after confirming the SQL is correct. For DROP operations, both `--execute` and `--force` are required.
 
+### evidence
+
+Compose a canonical, offline **Evidence Pack** from existing verification artifacts
+and audit entries. This command never opens a database connection. A pack retains only
+safe pointers and outcome fields: it excludes SQL, targets, audit metadata, verification
+summaries, result data, and credentials. Claims are external statements, never dbcli
+verification verdicts.
+
+#### `evidence compose`
+
+```bash
+dbcli evidence compose --claims ./claims.json --verification ver_abcd --audit 1a2b \
+  --receipt .dbcli/evidence/verify-receipt.json \
+  --output .dbcli/evidence/review.json --format json
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--claims <file>` | Required JSON file with exactly `subject` and `claims`; every claim has an `id` and plain-language `text`. SQL-shaped text, credentials, error content, and blacklisted identifiers are rejected. | — |
+| `--verification <selector...>` | One or more verification artifact ids, unique prefixes, filenames, or in-bounds paths. | none |
+| `--audit <selector...>` | One or more audit ids or unique prefixes (minimum four characters) from the active connection. | none |
+| `--receipt <path...>` | Explicit workspace-relative receipt path(s). Receipts contribute safe provenance only; they are not execution approval. | none |
+| `--output <path>` | Required new JSON path under the current workspace. Existing files and paths outside the workspace are refused. | — |
+| `--format <json\|markdown>` | Compose receipt format printed to stdout. | `json` |
+
+At least one `--verification`, `--audit`, or `--receipt` reference is required. The resulting pack
+contains a canonical SHA-256 integrity digest and `coverage.completeForDeclaredEvidence:
+true` for its explicitly selected references.
+
+#### `evidence validate`
+
+```bash
+dbcli evidence validate --file .dbcli/evidence/review.json --format json
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--file <path>` | Required evidence-pack JSON file. | — |
+| `--format <json\|markdown>` | Validation report format. | `json` |
+
+Exit `0` when digest and all selected sources are valid. If a referenced audit or
+verification artifact later rotates, is cleared, disappears, or belongs to a different
+active connection, output stays parseable with `integrity: "valid"` and
+`references: "source-expired"`, then exits `1`.
+
+#### `evidence render`
+
+```bash
+dbcli evidence render --file .dbcli/evidence/review.json --format markdown
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--file <path>` | Required evidence-pack JSON file. | — |
+| `--format <json\|markdown>` | Render format. | `markdown` |
+
+`render` validates the pack digest and active blacklist policy but does not resolve its
+original references. It is therefore available for historical review after `validate`
+reports `source-expired`, unless an exposed pack field is now blacklisted.
+
 ### semantic
 
 Validate or print the optional, version-controlled `dbcli.semantic.json` in the
@@ -2485,6 +2664,39 @@ limits, audit, and recovery safeguards remain in force.
 
 **Permission:** n/a (local files only; no database connection).
 
+### contract
+
+Inspect the optional, version-controlled `dbcli.contracts.json` without opening a
+database connection. A contract adds a reviewed owner and descriptive evidence policy
+to canonical semantic references; it is not an executable data contract, assertion,
+query, or verification scenario.
+
+```bash
+dbcli contract validate --format json
+dbcli contract context --format json
+dbcli contract context --format markdown
+dbcli contract search customer --format json
+dbcli contract drift --format json
+```
+
+The strict v1 artifact contains `version` and `contracts`. Each contract has a unique
+canonical `name`, `status` (`draft`, `approved`, or `deprecated`), bounded plain-text
+`description` and `owner`, one or more canonical semantic `subjects`, optional aliases,
+and an `evidencePolicy` of `none`, `receipt-required`, or `verification-required`.
+Subjects must remain in the existing visible semantic registry; protected identifiers,
+unknown keys, duplicate names or subjects, SQL-like text, credentials, and stale
+references fail closed without exposing protected names.
+
+`contract validate` requires an explicit valid artifact. `contract context` and
+`contract search` return only valid approved contracts; draft and deprecated contracts
+remain local review artifacts. `contract drift` reports `valid`, `stale`, `invalid`, or
+`unavailable` evidence offline and exits non-zero except for `valid`. A missing default
+file is allowed by `skill context` and leaves ordinary semantic context unchanged; a
+present invalid file fails closed. No contract command writes a file, opens a database
+connection, widens a `QueryDraft`, or changes permission/blacklist behavior.
+
+**Permission:** n/a (local files only; no database connection).
+
 ### skill
 
 Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or an
@@ -3024,9 +3236,9 @@ Permission is derived from the command's first token (case-insensitive). Unknown
 
 | Tier | Commands |
 |------|----------|
-| `query-only` | `GET`, `MGET`, `STRLEN`, `EXISTS`, `TTL`, `PTTL`, `TYPE`, `SCAN`, `HGET`, `HGETALL`, `HKEYS`, `HVALS`, `HLEN`, `HEXISTS`, `HMGET`, `LRANGE`, `LLEN`, `LINDEX`, `SMEMBERS`, `SCARD`, `SISMEMBER`, `ZRANGE`, `ZREVRANGE`, `ZRANGEBYSCORE`, `ZCARD`, `ZSCORE`, `PING`, `ECHO` |
-| `read-write` | `SET`, `SETEX`, `SETNX`, `PSETEX`, `MSET`, `MSETNX`, `APPEND`, `INCR`/`INCRBY`, `DECR`/`DECRBY`, `HSET`/`HSETNX`/`HMSET`/`HINCRBY`, `LPUSH`/`RPUSH`/`LPOP`/`RPOP`/`LSET`, `SADD`/`SREM`, `ZADD`/`ZREM`, `EXPIRE`/`EXPIREAT`/`PEXPIRE`/`PERSIST`, `RENAME` |
-| `data-admin` | `DEL`, `UNLINK`, `HDEL` |
+| `query-only` | `GET`, `MGET`, `STRLEN`, `EXISTS`, `TTL`, `PTTL`, `TYPE`, `SCAN`, `HGET`, `HGETALL`, `HKEYS`, `HVALS`, `HLEN`, `HEXISTS`, `HMGET`, `LRANGE`, `LLEN`, `LINDEX`, `SMEMBERS`, `SCARD`, `SISMEMBER`, `ZRANGE`, `ZREVRANGE`, `ZRANGEBYSCORE`, `ZCARD`, `ZSCORE`, `XLEN`, `XREAD`, `XRANGE`, `XREVRANGE`, `PING`, `ECHO` |
+| `read-write` | `SET`, `SETEX`, `SETNX`, `PSETEX`, `MSET`, `MSETNX`, `APPEND`, `INCR`/`INCRBY`, `DECR`/`DECRBY`, `HSET`/`HSETNX`/`HMSET`/`HINCRBY`, `LPUSH`/`RPUSH`/`LPOP`/`RPOP`/`LSET`/`LREM`, `SADD`/`SREM`, `ZADD`/`ZREM`, `XADD`, `EXPIRE`/`EXPIREAT`/`PEXPIRE`/`PERSIST`, `RENAME` |
+| `data-admin` | `DEL`, `UNLINK`, `HDEL`, `XDEL` |
 | `admin` | `FLUSHDB`, `FLUSHALL`, `CONFIG`, `INFO`, `CLIENT`, `DEBUG`, `SHUTDOWN`, `KEYS`, `MONITOR`, `SAVE`, `BGSAVE`, `BGREWRITEAOF`, `REPLICAOF`, `SLAVEOF`, `ACL` |
 
 ### Schema inspection
@@ -3237,5 +3449,5 @@ GET /orders/_search
 
 - Writes (`insert`/`update`/`delete`) are not exposed yet — the adapter implements them, but the CLI currently only routes them for SQL and MongoDB. Read-only `export` (v1.22) and the interactive `shell` (v1.22) are available.
 - No `_search/scroll` or PIT pagination at the CLI layer; large pulls need a saved external script.
-- `check`, `diff`, `migrate`, and `q` are SQL-only and exit with errors (or fall through to a generic "unsupported" path).
+- `check`, `diff`, and `migrate` are SQL-only and exit with errors (or fall through to a generic "unsupported" path). `q` **is** supported — Elasticsearch snippets use the `.elasticsearch.sql` extension (see `@diag/es-cluster-health`).
 - Blacklist column rules are applied to flattened hit rows on `query`; table-level blacklist rejects an index up front.

package/skills/dbcli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dbcli
-description: Database CLI for AI agents with permission-based access control. Use to set up new connections, query, inspect schemas, insert/update/delete, export results, generate DB reports or interactive HTML dashboards, and blacklist sensitive columns/tables. Supports MySQL, PostgreSQL, MariaDB, MongoDB, Redis, and Elasticsearch with multiple named connections per project and custom env files. Trigger when configuring a database connection (`.dbcli` / `.env`), choosing between v1 single and v2 multi-connection layouts, picking auth modes (URI, env refs, Cloud ID, API key), running SQL / MongoDB JSON / Redis commands / Elasticsearch DSL, generating a report/dashboard/HTML UI from raw SQL or saved snippets, exploring table/collection/key/index structures, switching database environments, protecting sensitive data from AI access, or performing automated recovery and guided remediation after command failures. For exhaustive flags and examples, read the sibling `reference.md`.
+description: Database CLI for AI agents with permission-gated access to MySQL, PostgreSQL, MariaDB, MongoDB, Redis, and Elasticsearch. Trigger when: wiring up a connection (`.dbcli` / `.env`, v1 single vs v2 multi-connection, auth mode); running SQL / MongoDB JSON / Redis commands / Elasticsearch DSL; inspecting table, collection, key, or index structure; writing rows or exporting results; building a report, dashboard, or HTML UI; authoring or reviewing a schema design; protecting sensitive data with the blacklist; or recovering after a failed command. For exhaustive flags and examples, read the sibling `reference.md`.
 ---
 
 # dbcli
@@ -71,7 +71,7 @@ afterwards add only the `@diag/*` it does not cover (`missing-indexes`, `locks`,
 `export` / `schema` / `inspect` / `lint` / `diff --against-orm`. The command emits a `RecoveryEnvelope` to stdout and saves
 it to `.dbcli/last-recovery.json`; then `dbcli recover` inspects it and `dbcli recover --apply`
 runs the saved plan under risk gating. Multi-turn `--next`, connection branching, and the
-post-apply verify probe are documented in reference.md §Recovery Cookbook.
+post-apply verify probe are documented in [reference.md](reference.md#recovery-cookbook-agent-walkthroughs).
 
 When reporting a check's outcome use the vocabulary `verified` (evidence matched) /
 `not_verified` (check ran and contradicted) / `indeterminate` (ran but ambiguous) /
@@ -110,8 +110,8 @@ still stop where those gates require human confirmation.
 term, or relationship/join intent instead of a physical table or field name, first run
 `dbcli skill context --format json`. If it includes `semantic`, treat that reviewed
 section as the governed vocabulary; use `dbcli semantic search <terms> --format json`
-to look up a specific term. If no semantic section exists or search returns no result,
-fall back to `blacklist` → `schema` mapping and tell the user that optional
+to look up a specific term. If `contracts` is present, use only its approved terms and
+their descriptive evidence policy; it never authorizes an assertion or query. If no semantic section exists or search returns no result, fall back to `blacklist` → `schema` mapping and tell the user that optional
 `dbcli.semantic.json` can make future requests consistent. Never create, update, or
 migrate that file without an explicit human request; semantic vocabulary never replaces
 schema confirmation or the normal query/write safety gates.
@@ -157,6 +157,9 @@ in **How to use dbcli** still applies.
 | DB report / dashboard request | `blacklist list` → `queries search <keywords>` / `queries suggest <intent>` → `queries show @<name>` → `q @<name> --ui` or `--format html` |
 | Application data bug | `audit tail --for-agent --n 10` → `blacklist list` → `schema <object>` → narrow query |
 | ORM or migration work | `schema --format json` → `diff --against-orm <orm-schema>` → review error-level drift → proposals via `migrate` (dry-run) → `migration-review` task pack → `diff --against <snapshot>` after applying. |
+| Schema design, no database yet | `design init --output ./dbcli.design.json` → edit → `design validate` → `design render --format mermaid`. With existing ORM models, reconcile via `design diff --against-orm <path>` first. |
+| Design drift on a live database | `blacklist list` → `schema --format json` → `design diff --against-cache` → `design propose --against-cache`, then hand the plan to a human before any migration. |
+| PR schema-change review | `blacklist list` → `impact assess --design ./dbcli.design.json --against-cache --output ./impact.json --fail-on warn`; optionally add explicit `--events ./.dbcli/proxy/events.jsonl` for advisory redacted workload table evidence (never SQL/log rendering or a blocker), then review declared findings, coverage gaps, and the optional reviewed `dbcli.data-access.json` (declared operations only; never source parsing). |
 | PR database review | Review changed persistence paths, then propose concrete `schema` / `plan` / `dry-run` / `report` / `guide` commands per material claim. |
 | Slow endpoint or query | `report --section perf` → task pack `analyze-table-perf` → `lint "<query>"` → `guide missing-index-for "<query>"`; use `proxy analyze` when logs exist. |
 | Safe data backfill | `blacklist list` → `schema <object>` → count/scope query → `update … --dry-run` → read-back or snippet `--verify`. |
@@ -193,12 +196,16 @@ Guardrails:
 - Separate database facts from application-code inference. Report which dbcli output shaped the conclusion.
 - For writes and backfills, include scope count, dry-run preview, execution command, and read-back.
 - Do not create indexes directly from a performance suggestion; turn them into reviewed migrations.
+- Do not execute the `commands` in a `design propose` plan, and do not create or rewrite
+  `dbcli.design.json` unless a human asked for it.
 - Do not print credentials, copied connection strings, or blacklisted values.
 - Durable evidence: `assert … --write-verification-artifact --verification-subject <kind:name>`;
   inspect with `verification summary` / `list` / `show <id>`. The `verify safe-backfill` /
   `migration` / `rollback --kind <ddl|dml>` / `constraint --check <fk|not-null|unique|custom>`
-  family runs preflight + `--after-write` checks and **never executes the write**. Full flags
-  and the per-command blocks are in reference.md.
+  family runs preflight + `--after-write` checks and **never executes the write**. Add
+  `--evidence-receipt <workspace-relative-path>` only after after-write for a safe provenance
+  receipt; it is never approval to execute a write. Full flags
+  and the per-command blocks are in [reference.md](reference.md#commands).
 
 ## Audit log
 
@@ -215,7 +222,7 @@ The `inspect` / `guide` / `recover` agent JSON embeds `audit_recent` (last 5 ent
 fresh session has immediate history. An envelope's `audit_ref` and an audit entry's
 `recovery_ref` point at each other, so you can pivot either way. Audit is on by default
 (`audit.enabled = false` to opt out); entries are metadata-only (never SQL bodies, `--param`
-values, or result cells) and rotate at ~10 MB / 1000 entries. Full flags: reference.md §audit.
+values, or result cells) and rotate at ~10 MB / 1000 entries. Full flags: [reference.md](reference.md#audit).
 
 ## Quick start
 
@@ -371,7 +378,7 @@ refs have no value to connect with yet.
 - **Re-running `init`** — refuses to overwrite without `--force`; never use
   `--force` to "fix" a config full of `{ "$env": "..." }` refs.
 
-Full flags and edge cases: see [reference.md](reference.md) `init` section.
+Full flags and edge cases: see [reference.md](reference.md#init).
 
 ## Command overview
 
@@ -382,34 +389,36 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `list` | query-only+ | Tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch). |
 | `schema` | query-only+ | SQL: per-table or full scan into `.dbcli/schemas/`. MongoDB: sampled. ES: flattened mapping. Redis: per-key only (type/TTL/size). Supports `--recovery`. |
 | `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). `--format table\|json\|csv\|html`, `--ui` to open the interactive dashboard in a browser. `--fields` (projection), `--truncate` (cell width), `-f/--query-file` (read query from file or stdin), `--use a,b` (read-only fan-out). Supports `--recovery`. `--slow-ms <n>` sets the passive slow-query hint threshold (default 1000, `0` off): at or above it, table output gains a `Performance hint` footer and JSON gains `metadata.performanceAdvisory`; it runs no extra diagnostics and is suppressed under `--recovery`. Distinct from the `proxy` flag of the same name. See **Query workflow flags**. |
-| `explain` | query-only+ | **(v1.23)** Read-only query plan with annotations. SQL only. Single query, `@saved-query`, `@file.sql`, or `--bulk @glob/*`. `--analyze` (EXPLAIN ANALYZE / MariaDB ANALYZE SELECT), `--format markdown\|json\|table`. |
+| `explain` | query-only+ | Read-only query plan with annotations. SQL only. Single query, `@saved-query`, `@file.sql`, or `--bulk @glob/*`. `--analyze` (EXPLAIN ANALYZE / MariaDB ANALYZE SELECT), `--format markdown\|json\|table`. |
 | `lint` | n/a | Static SQL anti-pattern advisor (no DB connection). 9 rules incl. schema-aware implicit-cast / NOT IN-nullable checks via the layered `.dbcli/schemas/` cache; global `--use <conn>` selects a named cache. Findings carry rewrite drafts + guarded `explain` verify commands (`--analyze` only for proven read-only SQL) — report-only, never executes. `--format text\|json\|markdown`, `--min-severity`, `--no-schema`, `--bulk`. Supports `--recovery`. |
 | `plan` | n/a | Static SQL risk analyzer (`--format text\|json`); classifies a statement without connecting to the database. |
 | `q` | query-only+ | Run a saved snippet by `@name` with `--param k=v`. Supports `--verify` to run assertions and `--slow-ms <n>` (same passive slow-query hint as `query`). |
 | `queries` | n/a | Manage saved snippets: `list` / `show` / `search` / `suggest` / `new` / `edit` / `check` / `delete` / `rename` / `copy` / `import` / `export`. |
 | `insert` / `update` | read-write+ | SQL or MongoDB only. JSON `--data` / `--set`; `--where` required on `update`; `--dry-run` first. Redis writes go through `query`. Supports `--recovery`. |
 | `delete` | data-admin+ | SQL or MongoDB; Redis has a basic implementation (see Redis section). `--where` required; `--dry-run` first. Supports `--recovery`. |
-| `export` | query-only+ | SQL, MongoDB, or **(v1.22)** Elasticsearch (DSL `--index` or whole-index scroll). Query → `--format json\|jsonl\|csv\|html` file or stdout. `html` emits a standalone interactive dashboard. **Fails closed rather than truncating silently**: if the auto-limit would drop rows, the export errors out and you must pass `--no-limit` or `--limit N`. Supports `--recovery`. |
+| `export` | query-only+ | SQL, MongoDB, or Elasticsearch (DSL `--index` or whole-index scroll). Query → `--format json\|jsonl\|csv\|html` file or stdout. `html` emits a standalone interactive dashboard. **Fails closed rather than truncating silently**: if the auto-limit would drop rows, the export errors out and you must pass `--no-limit` or `--limit N`. Supports `--recovery`. |
 | `blacklist` | n/a | `list` / `table` / `column` subcommands redact sensitive data from query results. |
 | `check` | query-only+ | SQL only (best on MySQL/MariaDB). |
-| `diff` | query-only+ | SQL only. Save/compare schema snapshots. **(P1b)** `--against-orm <path>` compares a Prisma schema / DDL file / normalized JSON against the local schema cache (no DB connection): categorized drift (`missing_in_db` = error, `missing_in_orm` = warn, `mismatch` per tolerance table, `unmanaged`) with dry-run `migrate` proposals; exit 1 on error-level drift. `--orm-format prisma\|ddl\|json\|drizzle\|typeorm\|sequelize`, `--ignore <globs>`, `--format json\|table\|markdown`. Drizzle: point at `drizzle/meta/<NNNN>_snapshot.json` (run `drizzle-kit generate` first; `.ts` sources are rejected with a hint). TypeORM/Sequelize: feed tool-generated DDL (`schema:log` / a schema-only dump); source files are rejected with the exact generation command to run. |
-| `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>`. |
+| `diff` | query-only+ | SQL only. Save/compare schema snapshots. `--against-orm <path>` compares a Prisma schema / DDL file / normalized JSON against the local schema cache (no DB connection): categorized drift (`missing_in_db` = error, `missing_in_orm` = warn, `mismatch` per tolerance table, `unmanaged`) with dry-run `migrate` proposals; exit 1 on error-level drift. `--orm-format prisma\|ddl\|json\|drizzle\|typeorm\|sequelize`, `--ignore <globs>`, `--format json\|table\|markdown`. Drizzle: point at `drizzle/meta/<NNNN>_snapshot.json` (run `drizzle-kit generate` first; `.ts` sources are rejected with a hint). TypeORM/Sequelize: feed tool-generated DDL (`schema:log` / a schema-only dump); source files are rejected with the exact generation command to run. |
+| `design` | n/a | Offline SQL design assistant over a version-controlled `dbcli.design.json`: never connects, never runs DDL, never calls a provider. `init --output <path>` is the only writer and refuses to overwrite; `validate` is fail-closed, so `render` / `diff` / `propose` refuse to run while `error` findings remain. `diff` / `propose` need exactly one of `--against-cache` or `--against-orm <paths>`. **`propose` is review-only — it plans, it never writes.** Naming rules, finding codes, and the artifact shape are in [reference.md](reference.md#design). |
+| `snapshot` | query-only+ | 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+ | 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` (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, slowest, errors, hotTables, N+1) — `--format`, `--top`, `--slow-ms`, `--n-plus-one`; errors out if no events exist yet. **(v1.50)** `proxy analyze --format markdown` produces the QueryLens report and redacts SQL/error literals in-memory before analysis; use `proxy <engine> --redact literals` to protect the log itself. Actionable blocks carry `suggestedCommands` + `hints` so an agent can act: SELECT hotspots/N+1 → `explain` / `guide missing-index-for`, errors → `schema <table>` (verify names, never guess), N+1 → batch (JOIN / `IN (...)`). After analyzing, run each finding's `suggestedCommands`, read its `hints`, then propose the fix. |
+| `proxy` | n/a | 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`. Observe-only. `proxy analyze` aggregates that log offline (summary, byFingerprint, slowest, errors, hotTables, N+1; `--format markdown` produces the QueryLens report) and errors out if no events exist. Act on it: run each finding's `suggestedCommands`, read its `hints`, then propose the fix — never guess a table name, confirm with `schema`. Protect the log itself with `--redact literals`. [Flags](reference.md#proxy). |
 | `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`. |
+| `inspect` | query-only+ | Read-only context snapshot (connection, permission, blacklist, objects, snippets, context-aware `suggestedCommands`, and human-readable `hints`). `--for-agent` / `--brief` / `--no-connect` / `--require-schema-cache`. Supports `--recovery`. |
 | `report` | query-only+ | Diagnostic report built from `@diag/*` snippets. `--section <health\|capacity\|perf>` (comma-separated to combine), `--brief`, `--for-agent`, `--no-connect`. |
-| `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`). |
+| `guide` | query-only+ | Deterministic next-command plan for a fixed goal (`slow-query`, `capacity`, `health`, `index-usage`, `permissions`, `schema-overview`). `--list` to enumerate. `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/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). |
+| `shell` | (same as query+) | Interactive REPL. SQL engines, MongoDB, and Redis (single-line; `.no-limit on/off`). 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\|antigravity\|copilot\|cursor\|codex\|windsurf>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for an LLM prompt-context payload (for injecting into another LLM, not needed for normal operation). |
 | `semantic` | n/a | Validate, search, inspect drift, migrate to v2, or print the optional project-root `dbcli.semantic.json`. Give its reviewed context to an external agent, but keep provider credentials, prompts, and agent context outside dbcli. `semantic draft validate --input <file|-> [--format text\|json]` validates only the explicit untrusted `QueryDraft` offline against local semantic/schema/saved-query metadata; it returns safe hashes/references/violation codes, never executes or echoes candidate SQL. Review the original draft, then invoke `explain` or `query` separately if intended. |
+| `contract` | n/a | Validate, inspect approved context, search, or inspect drift for optional project-root `dbcli.contracts.json`. Contracts add ownership and a descriptive evidence policy to canonical semantic references; they are offline, never execute SQL, and cannot create verification or query authority. `skill context` includes only valid approved contracts. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,
@@ -475,12 +484,12 @@ truncation from a round number. This applies to `query` and to `q` snippets
   explicit operators (`$set`/`$inc`/`$push`/…) pass through. Nested blacklist accepts dotted
   paths (`profile.email`) and trailing wildcards (`profile.tokens.*`). Saved snippets end in
   `.mongodb.sql` (frontmatter `engine: mongodb`, `operation: find|aggregate`). Full
-  write-planner tiers and syntax: reference.md MongoDB section.
+  write-planner tiers and syntax: [reference.md](reference.md#mongodb-support).
 
 ## Redis
 
 - `query` runs a single **whitelisted** Redis command (e.g. `GET`, `SET`, `HSET`, `DEL`).
-  The full whitelist and the per-command permission tier are defined in reference.md.
+  The full whitelist and the per-command permission tier are defined in [reference.md](reference.md#redis-support).
 - **Supported:** `init`, `list` (keys via SCAN), `schema <key>` (type / TTL / size / sample),
   `query`, `q` (saved snippets — **read-only commands only**), `delete` (basic implementation:
   `DEL` / `HDEL` / `LREM` / `SREM` / `ZREM`, needs `data-admin`; `query "DEL <key>"` also
@@ -493,7 +502,7 @@ truncation from a round number. This applies to `query` and to `q` snippets
   blacklist (matching reads/writes are rejected). To preview a delete, use `delete <key> --dry-run`.
 - `database` is the logical DB index (default `0`). `dbcli blacklist table add 'secrets:*'`
   registers a key glob; an optional `redis.mask` block masks values on read. Size guards
-  (SCAN/HGETALL truncation, `--no-limit` to bypass) and masking details: reference.md Redis section.
+  (SCAN/HGETALL truncation, `--no-limit` to bypass) and masking details: [reference.md](reference.md#redis-support).
 
 ## Elasticsearch
 
@@ -505,12 +514,14 @@ dbcli query '{"query":{"match":{"status":"active"}}}' --collection orders
 
 - `query` takes a DSL (JSON body) or Lucene query string; `--collection <index>` is required.
 - **Supported:** `init`, `list` (indices with doc count), `schema [index]` (flattened mapping),
-  `query`, `export` (v1.22), `shell` (v1.22), `status`, `use`, `doctor`. **Not supported:**
+  `query`, `q` (snippets use the `.elasticsearch.sql` extension), `export`,
+  `shell`, `status`, `use`, `doctor`. **Not supported:**
   `insert`, `update`, `delete`, `check`, `diff`, `migrate`.
 - `export` takes a search DSL with `--index <index>`, or an index name as the query to scroll
-  the whole index via `match_all`. Query-only caps at 1000 hits; `--no-limit` is bounded at 10 000.
+  the whole index via `match_all`. Query-only caps at 1000 hits; `--no-limit` streams the whole
+  index via the scroll API. (The 10 000 bound belongs to `query`, not `export`.)
 - Schema flattens nested fields (`a.b.c`) and surfaces `.fields` multi-fields. `shell` opens a
-  Kibana Dev Tools-style REPL. Full syntax and examples: reference.md Elasticsearch section.
+  Kibana Dev Tools-style REPL. Full syntax and examples: [reference.md](reference.md#elasticsearch-support).
 
 ## Saved queries
 
@@ -575,7 +586,7 @@ dbcli export "SELECT * FROM orders" --format html --output orders.html
 When a saved snippet exists, prefer `q @<name> --ui` / `q @<name> --format html` because snippet
 metadata can drive titles, KPI cards, and charts. Blacklist redaction is applied **before**
 rendering. To get KPIs and charts instead of a plain table, add a `visual:` block (`title`,
-`kpis[]`, `charts[]`) to the snippet frontmatter — see reference.md for the full `visual:`
+`kpis[]`, `charts[]`) to the snippet frontmatter — see [reference.md](reference.md#interactive-html-dashboard) for the full `visual:`
 schema. Raw `query` / `export` invocations render a sortable table only.
 
 ## Common workflows
@@ -592,6 +603,6 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 
 - Query-only mode auto-appends `LIMIT 1000`; add `--no-limit` for `information_schema` or statements that break with `LIMIT`.
 - 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.
+- `schema` reports `estimatedRowCount` and `sizeCategory` (small / medium / large / huge). For large/huge tables add `WHERE` or `LIMIT` — bands in [reference.md](reference.md#schema).
 - `doctor` on `mongodb+srv://` reports whether SRV resolves natively or through the DoH fallback — useful when the runtime restricts DNS.
 - **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `--timeout <ms>`, `-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.