@carllee1983/dbcli 1.49.0 → 1.51.0

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.49.0",
+  "version": "1.51.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.49.0",
+  "version": "1.51.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {

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

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

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

@@ -363,7 +363,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `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` (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. 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 | **(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. |
 | `status` | query-only+ | Safe JSON/text summary (no credentials). |
 | `inspect` | query-only+ | Read-only context snapshot (connection, permission, blacklist, objects, snippets, context-aware `suggestedCommands`, and **(v1.23)** human-readable `hints`). `--for-agent` / `--brief` / `--no-connect` / `--require-schema-cache`. Supports `--recovery`. |
 | `report` | query-only+ | Diagnostic report built from `@diag/*` snippets. `--section <health\|capacity\|perf>` (comma-separated to combine), `--brief`, `--for-agent`, `--no-connect`. |
@@ -375,6 +375,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `upgrade` | n/a | Self-update from npm; 24h-cached version hints on every command. |
 | `shell` | (same as query+) | Interactive REPL. SQL engines, MongoDB, and Redis (single-line; `.no-limit on/off`). **(v1.22)** Elasticsearch opens a Kibana Dev Tools-style REPL (`<METHOD> /<path>` + optional JSON body, blank line submits). |
 | `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|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. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,

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

@@ -1180,6 +1180,7 @@ dbcli --use prod proxy postgresql                         # infer target from na
 
 dbcli proxy analyze                               # analyze .dbcli/proxy/events.jsonl (JSON)
 dbcli proxy analyze --format text --top 10        # human-readable top-10 view
+dbcli proxy analyze --format markdown             # QueryLens shareable, redacted Markdown report
 dbcli proxy analyze --slow-ms 200 --n-plus-one 5  # custom thresholds
 ```
 
@@ -1200,7 +1201,7 @@ dbcli proxy analyze --slow-ms 200 --n-plus-one 5  # custom thresholds
 
 **Log rotation:** all writes are serialized through one in-process chain (concurrent sessions never interleave partial lines). The event log auto-rotates to keep one rolling segment — when the next line would reach ~50 MiB or 200,000 entries, the current file is renamed to `<events>.1` (overwriting any prior segment) and a fresh file starts. Worst-case on-disk footprint is ~2× the byte cap.
 
-**`proxy analyze`** — offline aggregation of the event log (no DB). Flags: `--events <path>` (default `.dbcli/proxy/events.jsonl`), `--format json|text` (default `json`), `--top <n>` (default 20; text rows + suggestedCommands depth), `--slow-ms <ms>` (default 1000; recomputes slowCount), `--n-plus-one <n>` (default 10), `--no-include-rotated`. JSON report blocks: `summary`, `byFingerprint` (sorted by total time; SELECT entries in the top-N carry `suggestedCommands` for `explain` / `guide missing-index-for`), `slowest`, `errors`, `hotTables`, `repetition` (N+1 suspects). Reads the current log plus the rotated `.1` segment by default.
+**`proxy analyze`** — offline aggregation of the event log (no DB). Flags: `--events <path>` (default `.dbcli/proxy/events.jsonl`), `--format json|text|markdown` (default `json`), `--top <n>` (default 20; text rows + suggestedCommands depth), `--slow-ms <ms>` (default 1000; recomputes slowCount), `--n-plus-one <n>` (default 10), `--no-include-rotated`. JSON report blocks: `summary`, `byFingerprint` (sorted by total time; SELECT entries in the top-N carry `suggestedCommands` for `explain` / `guide missing-index-for`), `slowest`, `errors`, `hotTables`, `repetition` (N+1 suspects). Reads the current log plus the rotated `.1` segment by default. `markdown` is the QueryLens report: it redacts SQL and error-message literals in an in-memory copy before analysis, while leaving the source log untouched.
 
 Every actionable block carries machine-readable next steps so an agent can move from "what is wrong" to "what to run":
 - `byFingerprint[]` — top-N SELECT entries get `suggestedCommands`: `dbcli explain "<sql>"` and `dbcli guide missing-index-for "<sql>"`.
@@ -2189,6 +2190,124 @@ 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.
 
+### semantic
+
+Validate or print the optional, version-controlled `dbcli.semantic.json` in the
+project root. It supplies business names and descriptions to an agent, but is
+not a query language: these commands are offline, read-only, and never execute
+SQL or contact an LLM.
+
+```bash
+dbcli semantic validate
+dbcli semantic validate --format json
+dbcli semantic context
+dbcli semantic context --format markdown
+dbcli semantic context --file ./analytics.semantic.json
+dbcli semantic drift --format json
+dbcli semantic migrate --to 2 --format json
+dbcli semantic search purchases --kind model --format json
+dbcli semantic draft validate --input ./draft.json --format json
+external-agent | dbcli semantic draft validate --input - --format json
+```
+
+The default file has this compact contract:
+
+```json
+{
+  "version": 2,
+  "models": [
+    {
+      "name": "orders",
+      "table": "orders",
+      "description": "Completed purchases.",
+      "aliases": ["purchases"],
+      "fields": [
+        { "column": "created_at", "aliases": ["order date"] },
+        { "column": "customer_id" }
+      ]
+    },
+    {
+      "name": "customers",
+      "table": "customers",
+      "fields": [{ "column": "id" }]
+    }
+  ],
+  "relationships": [
+    {
+      "name": "order-customer",
+      "from": { "model": "orders", "field": "customer_id" },
+      "to": { "model": "customers", "field": "id" },
+      "cardinality": "many-to-one",
+      "description": "Each order belongs to one customer."
+    }
+  ],
+  "metrics": [
+    { "name": "daily-revenue", "query": "@analytics/revenue" }
+  ]
+}
+```
+
+Version 1 remains supported and is normalized with `relationships: []`.
+Version 2 relationships must reference a declared model and a declared field on
+that model; the field must also be visible in cached schema. Their `cardinality`
+is one of `one-to-one`, `one-to-many`, `many-to-one`, or `many-to-many`.
+`models[].table` and `models[].fields[].column` must name a visible cached
+schema object. Blacklisted tables and columns are not visible and are rejected.
+Each metric `query` must name an available saved query. Validation parses its
+local file through the normal saved-query safety checks, but never executes or
+emits SQL. The semantic file cannot contain SQL, connection data, or
+credentials. `semantic validate` reports a
+deterministic success summary (`--format text|json`); `semantic context` prints
+the validated context (`--format json|markdown`). `semantic drift` returns a
+stable `valid`, `stale`, `invalid`, or `unavailable` report and exits non-zero
+for every status except `valid`; it never connects to a database. `semantic
+migrate --to 2` prints a deterministic v2 JSON document to stdout and never
+writes the input file. An absent default file is allowed for `skill context`
+and simply omits the semantic section; a stale or invalid present file fails
+closed rather than being silently ignored.
+
+`semantic search <terms...>` performs deterministic, case-insensitive matching
+over canonical names, aliases, descriptions, and governed model paths. Results
+are ranked by exact canonical name, exact alias, prefix, then description token;
+kind/name breaks ties. Use `--kind model|field|relationship|metric` and
+`--limit <1-100>` (default `20`). It returns only canonical references, matched
+terms, aliases, descriptions, and necessary model paths—never SQL bodies,
+connection data, or blacklist names. No result is an empty array / text notice
+with exit 0.
+
+`semantic draft validate --input <file|-> [--format text|json]` accepts only an
+explicit untrusted `QueryDraft` JSON document from a file or stdin. First give
+the external agent reviewed `dbcli semantic context --format json` output; its
+provider credentials, prompt, and other agent context remain outside dbcli. The
+agent returns a draft using only the declared models and fields, for example:
+
+```json
+{
+  "version": 1,
+  "questionHash": "<sha256-of-the-original-question>",
+  "candidate": { "kind": "sql", "sql": "<reviewed-read-only-sql>" },
+  "semanticReferences": ["model:<model>", "field:<model>.<field>"]
+}
+```
+
+The command validates the contract, read-only single-statement SQL, canonical
+semantic references, saved-query names, and local filtered schema/blacklist
+compatibility without connecting to a database, reading query results, storing
+the draft, or calling a provider. JSON reports contain only status, hashes,
+canonical references, and safe violation codes; they never echo candidate SQL
+or protected names. Exit `0` means valid, `1` means rejected, and `2` means
+required local semantic evidence is unavailable. A valid report is not execution
+authorization: review the original draft, then separately and explicitly invoke
+`dbcli explain "<reviewed-read-only-sql>"` or `dbcli query
+"<reviewed-read-only-sql>"` when appropriate.
+
+When valid, `dbcli skill context` includes the same bounded data in its JSON,
+XML, and Markdown output. To run a metric, an agent must still invoke the named
+saved query through `dbcli q`; all ordinary permissions, blacklist masking,
+limits, audit, and recovery safeguards remain in force.
+
+**Permission:** n/a (local files only; no database connection).
+
 ### skill
 
 Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or an

package/skills/dbcli/SKILL.md

@@ -363,7 +363,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `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` (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. 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 | **(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. |
 | `status` | query-only+ | Safe JSON/text summary (no credentials). |
 | `inspect` | query-only+ | Read-only context snapshot (connection, permission, blacklist, objects, snippets, context-aware `suggestedCommands`, and **(v1.23)** human-readable `hints`). `--for-agent` / `--brief` / `--no-connect` / `--require-schema-cache`. Supports `--recovery`. |
 | `report` | query-only+ | Diagnostic report built from `@diag/*` snippets. `--section <health\|capacity\|perf>` (comma-separated to combine), `--brief`, `--for-agent`, `--no-connect`. |
@@ -375,6 +375,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `upgrade` | n/a | Self-update from npm; 24h-cached version hints on every command. |
 | `shell` | (same as query+) | Interactive REPL. SQL engines, MongoDB, and Redis (single-line; `.no-limit on/off`). **(v1.22)** Elasticsearch opens a Kibana Dev Tools-style REPL (`<METHOD> /<path>` + optional JSON body, blank line submits). |
 | `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|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. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,

package/skills/dbcli/reference.md

@@ -1180,6 +1180,7 @@ dbcli --use prod proxy postgresql                         # infer target from na
 
 dbcli proxy analyze                               # analyze .dbcli/proxy/events.jsonl (JSON)
 dbcli proxy analyze --format text --top 10        # human-readable top-10 view
+dbcli proxy analyze --format markdown             # QueryLens shareable, redacted Markdown report
 dbcli proxy analyze --slow-ms 200 --n-plus-one 5  # custom thresholds
 ```
 
@@ -1200,7 +1201,7 @@ dbcli proxy analyze --slow-ms 200 --n-plus-one 5  # custom thresholds
 
 **Log rotation:** all writes are serialized through one in-process chain (concurrent sessions never interleave partial lines). The event log auto-rotates to keep one rolling segment — when the next line would reach ~50 MiB or 200,000 entries, the current file is renamed to `<events>.1` (overwriting any prior segment) and a fresh file starts. Worst-case on-disk footprint is ~2× the byte cap.
 
-**`proxy analyze`** — offline aggregation of the event log (no DB). Flags: `--events <path>` (default `.dbcli/proxy/events.jsonl`), `--format json|text` (default `json`), `--top <n>` (default 20; text rows + suggestedCommands depth), `--slow-ms <ms>` (default 1000; recomputes slowCount), `--n-plus-one <n>` (default 10), `--no-include-rotated`. JSON report blocks: `summary`, `byFingerprint` (sorted by total time; SELECT entries in the top-N carry `suggestedCommands` for `explain` / `guide missing-index-for`), `slowest`, `errors`, `hotTables`, `repetition` (N+1 suspects). Reads the current log plus the rotated `.1` segment by default.
+**`proxy analyze`** — offline aggregation of the event log (no DB). Flags: `--events <path>` (default `.dbcli/proxy/events.jsonl`), `--format json|text|markdown` (default `json`), `--top <n>` (default 20; text rows + suggestedCommands depth), `--slow-ms <ms>` (default 1000; recomputes slowCount), `--n-plus-one <n>` (default 10), `--no-include-rotated`. JSON report blocks: `summary`, `byFingerprint` (sorted by total time; SELECT entries in the top-N carry `suggestedCommands` for `explain` / `guide missing-index-for`), `slowest`, `errors`, `hotTables`, `repetition` (N+1 suspects). Reads the current log plus the rotated `.1` segment by default. `markdown` is the QueryLens report: it redacts SQL and error-message literals in an in-memory copy before analysis, while leaving the source log untouched.
 
 Every actionable block carries machine-readable next steps so an agent can move from "what is wrong" to "what to run":
 - `byFingerprint[]` — top-N SELECT entries get `suggestedCommands`: `dbcli explain "<sql>"` and `dbcli guide missing-index-for "<sql>"`.
@@ -2189,6 +2190,124 @@ 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.
 
+### semantic
+
+Validate or print the optional, version-controlled `dbcli.semantic.json` in the
+project root. It supplies business names and descriptions to an agent, but is
+not a query language: these commands are offline, read-only, and never execute
+SQL or contact an LLM.
+
+```bash
+dbcli semantic validate
+dbcli semantic validate --format json
+dbcli semantic context
+dbcli semantic context --format markdown
+dbcli semantic context --file ./analytics.semantic.json
+dbcli semantic drift --format json
+dbcli semantic migrate --to 2 --format json
+dbcli semantic search purchases --kind model --format json
+dbcli semantic draft validate --input ./draft.json --format json
+external-agent | dbcli semantic draft validate --input - --format json
+```
+
+The default file has this compact contract:
+
+```json
+{
+  "version": 2,
+  "models": [
+    {
+      "name": "orders",
+      "table": "orders",
+      "description": "Completed purchases.",
+      "aliases": ["purchases"],
+      "fields": [
+        { "column": "created_at", "aliases": ["order date"] },
+        { "column": "customer_id" }
+      ]
+    },
+    {
+      "name": "customers",
+      "table": "customers",
+      "fields": [{ "column": "id" }]
+    }
+  ],
+  "relationships": [
+    {
+      "name": "order-customer",
+      "from": { "model": "orders", "field": "customer_id" },
+      "to": { "model": "customers", "field": "id" },
+      "cardinality": "many-to-one",
+      "description": "Each order belongs to one customer."
+    }
+  ],
+  "metrics": [
+    { "name": "daily-revenue", "query": "@analytics/revenue" }
+  ]
+}
+```
+
+Version 1 remains supported and is normalized with `relationships: []`.
+Version 2 relationships must reference a declared model and a declared field on
+that model; the field must also be visible in cached schema. Their `cardinality`
+is one of `one-to-one`, `one-to-many`, `many-to-one`, or `many-to-many`.
+`models[].table` and `models[].fields[].column` must name a visible cached
+schema object. Blacklisted tables and columns are not visible and are rejected.
+Each metric `query` must name an available saved query. Validation parses its
+local file through the normal saved-query safety checks, but never executes or
+emits SQL. The semantic file cannot contain SQL, connection data, or
+credentials. `semantic validate` reports a
+deterministic success summary (`--format text|json`); `semantic context` prints
+the validated context (`--format json|markdown`). `semantic drift` returns a
+stable `valid`, `stale`, `invalid`, or `unavailable` report and exits non-zero
+for every status except `valid`; it never connects to a database. `semantic
+migrate --to 2` prints a deterministic v2 JSON document to stdout and never
+writes the input file. An absent default file is allowed for `skill context`
+and simply omits the semantic section; a stale or invalid present file fails
+closed rather than being silently ignored.
+
+`semantic search <terms...>` performs deterministic, case-insensitive matching
+over canonical names, aliases, descriptions, and governed model paths. Results
+are ranked by exact canonical name, exact alias, prefix, then description token;
+kind/name breaks ties. Use `--kind model|field|relationship|metric` and
+`--limit <1-100>` (default `20`). It returns only canonical references, matched
+terms, aliases, descriptions, and necessary model paths—never SQL bodies,
+connection data, or blacklist names. No result is an empty array / text notice
+with exit 0.
+
+`semantic draft validate --input <file|-> [--format text|json]` accepts only an
+explicit untrusted `QueryDraft` JSON document from a file or stdin. First give
+the external agent reviewed `dbcli semantic context --format json` output; its
+provider credentials, prompt, and other agent context remain outside dbcli. The
+agent returns a draft using only the declared models and fields, for example:
+
+```json
+{
+  "version": 1,
+  "questionHash": "<sha256-of-the-original-question>",
+  "candidate": { "kind": "sql", "sql": "<reviewed-read-only-sql>" },
+  "semanticReferences": ["model:<model>", "field:<model>.<field>"]
+}
+```
+
+The command validates the contract, read-only single-statement SQL, canonical
+semantic references, saved-query names, and local filtered schema/blacklist
+compatibility without connecting to a database, reading query results, storing
+the draft, or calling a provider. JSON reports contain only status, hashes,
+canonical references, and safe violation codes; they never echo candidate SQL
+or protected names. Exit `0` means valid, `1` means rejected, and `2` means
+required local semantic evidence is unavailable. A valid report is not execution
+authorization: review the original draft, then separately and explicitly invoke
+`dbcli explain "<reviewed-read-only-sql>"` or `dbcli query
+"<reviewed-read-only-sql>"` when appropriate.
+
+When valid, `dbcli skill context` includes the same bounded data in its JSON,
+XML, and Markdown output. To run a metric, an agent must still invoke the named
+saved query through `dbcli q`; all ordinary permissions, blacklist masking,
+limits, audit, and recovery safeguards remain in force.
+
+**Permission:** n/a (local files only; no database connection).
+
 ### skill
 
 Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or an