@carllee1983/dbcli 1.51.1 → 1.52.0

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

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

package/.cursor/rules/dbcli.mdc

@@ -82,6 +82,30 @@ warnings) go to stderr so stdout stays parseable — when piping JSON into a par
 use `2>/dev/null` or leave stderr alone. **Never `2>&1`**: it merges those lines back
 into stdout and the parse fails.
 
+**Intent confirmation:** Treat `auto`, `confirm`, and `guided` as conversational
+preferences for the current request, not as dbcli flags or persistent configuration.
+Do not ask the user a meta-question about whether they want questions.
+
+- `auto` (default): autonomously use governed semantic context and schema discovery.
+  If unresolved ambiguity would materially change the result, ask one compact batch of
+  questions before querying; otherwise state the assumptions and proceed.
+- `confirm`: first state the proposed interpretation and wait for the user's approval
+  before issuing the task's data query.
+- `guided`: resolve the request through short, focused questions, carrying confirmed
+  answers forward rather than asking again.
+
+For business requests, material ambiguity includes the requested result shape or grain,
+metric definition, time boundary and timezone, inclusion/exclusion rules (such as order
+status or refunds), grouping, or selected connection. Example: for “yesterday's sales,”
+do not guess whether the user needs a total or detail, which timezone defines yesterday,
+or whether cancelled and refunded orders count. Summarize the candidate interpretation
+and ask only the unresolved, result-changing questions.
+
+When the user explicitly says to decide without further questions, proceed in `auto`
+mode and disclose the material assumptions. This never bypasses blacklist, schema,
+permission, dry-run, production-selection, or write-confirmation gates; an agent must
+still stop where those gates require human confirmation.
+
 **Business-language discovery:** When a user uses a business alias, metric, recurring
 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
@@ -357,11 +381,11 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `use` | n/a | Show/switch default named connection (v2 only). |
 | `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`. See **Query workflow flags**. |
+| `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`. |
 | `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. |
+| `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`. |

package/.cursor/skills/dbcli/reference.md

@@ -220,9 +220,44 @@ dbcli query "SELECT day, dau FROM dau_daily" --ui                # open in brows
 dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdout
 ```
 
-**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--recovery`
+**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--slow-ms <number>`, `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
+#### Passive slow-query hint (`--slow-ms`)
+
+`query` and `q` read the execution time they already measured for a finished
+query and, at or above the threshold, add a hint. Default `1000`; `--slow-ms 0`
+disables it for that invocation. This is **not** the `proxy` / `proxy analyze`
+flag of the same name — that one flags events in the proxy log; this one only
+annotates a single command's own result.
+
+The hint performs no extra work: it never runs `EXPLAIN`, reads a schema, or
+issues a second request. It is suppressed entirely under `--recovery`, so the
+recovery envelope keeps its exact machine contract.
+
+- `--format table` appends `Performance hint: <recommendation>` to the footer.
+- `--format json` adds `metadata.performanceAdvisory`:
+
+```json
+{
+  "metadata": {
+    "statement": "SELECT",
+    "performanceAdvisory": {
+      "code": "SLOW_QUERY",
+      "executionTimeMs": 1250,
+      "thresholdMs": 1000,
+      "recommendation": "Review safely with: dbcli guide slow-query --format markdown. This hint runs no additional database diagnostics."
+    }
+  }
+}
+```
+
+The recommendation is engine-aware: PostgreSQL, MySQL, MariaDB, and Redis are
+pointed at `dbcli guide slow-query`, because that goal resolves to real
+diagnostic snippets for them. MongoDB and Elasticsearch ship no snippet for its
+intents, so their hint states the timing and says so instead of naming a command
+that would come back empty. `csv` and `html` output are unchanged.
+
 Below `admin`, SQL holding more than one statement is rejected, because only the
 first statement would decide the permission check while a driver on the simple
 query protocol executes them all. Semicolons inside string literals, backtick
@@ -529,6 +564,7 @@ dbcli q @analytics/revenue --param days=30 --format html > report.html
 - `--no-limit` — skip the `SELECT * FROM (…) AS _dbcli_guard LIMIT 1000` wrap
 - `--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)
 
@@ -1077,6 +1113,139 @@ Both parameters are required. Keep each expansion as one quoted shell argument;
 never use `eval`, and consider `--execute` only after the plan and captured DDL
 have been reviewed.
 
+### design
+
+Author, validate, render, and review a version-controlled SQL database design
+kept beside the code as `dbcli.design.json`. Every subcommand is offline: none
+opens a database connection, executes DDL, or calls an LLM. `design init` is the
+only writer, and it writes only to the explicit `--output` path.
+
+```text
+dbcli design init --output <path> [--dialect <dialect>]
+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]
+```
+
+```bash
+# Writes only to this explicit, missing path; edit the starter before validating.
+dbcli design init --output ./dbcli.design.json --dialect postgresql
+
+dbcli design validate --format json
+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
+```
+
+| Option | Applies to | Default | Meaning |
+|---|---|---|---|
+| `--output <path>` | `init` | required | Destination for the new artifact; refuses to overwrite an existing file. |
+| `--dialect <postgresql\|mysql\|mariadb>` | `init` | `postgresql` | Target SQL dialect recorded in the artifact. |
+| `--file <path>` | all but `init` | `dbcli.design.json` | Design artifact to read. |
+| `--format <format>` | all but `init` | see below | `validate`/`propose`: `json`, `markdown`. `render`: `json`, `markdown`, `mermaid` (default `markdown`). `diff`: `json` (default), `table`, `markdown`. |
+| `--against-cache` | `diff`, `propose` | off | Compare with the local schema cache; requires a configured PostgreSQL/MySQL/MariaDB connection whose system matches the artifact dialect, and a non-empty cache (run `dbcli schema` first). |
+| `--against-orm <paths>` | `diff`, `propose` | none | Compare with local ORM definition(s); repeatable or comma-separated, DDL paths support globs. Needs no config and no connection. |
+| `--orm-format <format>` | `diff`, `propose` | auto-detect | Force `prisma`, `ddl`, `json`, `drizzle`, `typeorm`, or `sequelize`. |
+| `--ignore <globs>` | `diff`, `propose` | none | Comma-separated table globs excluded from drift. |
+
+`diff` and `propose` require **exactly one** comparison target; passing both or
+neither is an error.
+
+#### Artifact shape
+
+```json
+{
+  "version": 1,
+  "dialect": "postgresql",
+  "models": [
+    {
+      "name": "orders",
+      "table": "orders",
+      "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 }
+      ],
+      "indexes": [{ "name": "orders_customer_idx", "columns": ["customer_id"], "unique": false }]
+    }
+  ],
+  "relationships": [
+    {
+      "name": "orders_customer",
+      "from": { "model": "orders", "field": "customer_id" },
+      "to": { "model": "customers", "field": "id" },
+      "cardinality": "many-to-one"
+    }
+  ],
+  "accessPatterns": [{ "model": "orders", "filters": ["customer_id"], "sort": ["created_at"] }],
+  "decisions": [{ "name": "single-currency", "rationale": "Amounts are stored in minor units, USD only." }]
+}
+```
+
+It holds no SQL, credentials, rows, or provider configuration. `design init`
+emits this envelope with empty `models`, `relationships`, `accessPatterns`, and
+`decisions`.
+
+#### Review findings
+
+`validate` is fail-closed: any `error` finding exits `1`, and `render`, `diff`,
+and `propose` refuse to do their work while errors remain.
+
+| 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` |
+| `warn` | `DUPLICATE_INDEX`, `REDUNDANT_PRIMARY_KEY_INDEX`, `PREFIX_REDUNDANT_INDEX`, `ACCESS_PATTERN_INDEX` |
+
+`REVERSE_RELATIONSHIP` fires when the same endpoints are declared again in the
+opposite direction; `PREFIX_REDUNDANT_INDEX` fires when a non-unique index is a
+leading-column prefix of a longer index. `v1` requires exactly one primary-key
+field per model and an explicit bridge model for `many-to-many`.
+
+#### `design propose` (review-only)
+
+`propose` turns drift into a plan a human reviews; it never applies a write. Each
+entry carries a `safety` of `dry-run` (an existing `migrate` command can represent
+the change losslessly) or `migration-review` (everything else), plus `preflight`,
+`rollback`, and `verification` steps:
+
+```json
+{
+  "table": "orders",
+  "object": "total_cents",
+  "safety": "migration-review",
+  "commands": ["..."],
+  "preflight": [
+    "dbcli blacklist list",
+    "Confirm the exact affected table with: dbcli schema <exact-table> --format json"
+  ],
+  "rollback": "Capture the current schema and generated DDL before any approved write; define the inverse migration before execution.",
+  "verification": [
+    "After an approved write, run: dbcli schema <exact-table> --format json",
+    "Re-run this same design diff command and review the remaining drift."
+  ]
+}
+```
+
+**Workflows:**
+
+- **New project** — `design init` → edit the artifact → `design validate` →
+  `design render`. If application models already exist, use the offline
+  `design diff --against-orm <path>` to reconcile the artifact and the ORM before
+  any database exists.
+- **Existing database** — `blacklist list` → refresh the cache with
+  `schema --format json` → `design diff --against-cache` →
+  `design propose --against-cache`. Review the plan, perform any approved
+  migration separately, then refresh the schema and rerun the same diff.
+
+**Exit codes:** `0` when no errors, `1` when the artifact has review errors, an
+invalid target selection, an unreadable file, or reported drift errors.
+
+An external coding agent may draft the artifact, but a human should review it
+before it is relied upon. Do not create or rewrite `dbcli.design.json` without an
+explicit human request.
+
 ### snapshot
 
 Capture a **result fingerprint** of a query (not schema): `rowCount` plus per-column

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "dbcli-agent",
   "displayName": "dbcli Agent",
   "description": "Database CLI skill and command reference for AI agents.",
-  "version": "1.51.1",
+  "version": "1.51.2",
   "author": {
     "name": "Carl Lee",
     "url": "https://github.com/CarlLee1983"

package/.github/skills/dbcli/SKILL.md

@@ -82,6 +82,30 @@ warnings) go to stderr so stdout stays parseable — when piping JSON into a par
 use `2>/dev/null` or leave stderr alone. **Never `2>&1`**: it merges those lines back
 into stdout and the parse fails.
 
+**Intent confirmation:** Treat `auto`, `confirm`, and `guided` as conversational
+preferences for the current request, not as dbcli flags or persistent configuration.
+Do not ask the user a meta-question about whether they want questions.
+
+- `auto` (default): autonomously use governed semantic context and schema discovery.
+  If unresolved ambiguity would materially change the result, ask one compact batch of
+  questions before querying; otherwise state the assumptions and proceed.
+- `confirm`: first state the proposed interpretation and wait for the user's approval
+  before issuing the task's data query.
+- `guided`: resolve the request through short, focused questions, carrying confirmed
+  answers forward rather than asking again.
+
+For business requests, material ambiguity includes the requested result shape or grain,
+metric definition, time boundary and timezone, inclusion/exclusion rules (such as order
+status or refunds), grouping, or selected connection. Example: for “yesterday's sales,”
+do not guess whether the user needs a total or detail, which timezone defines yesterday,
+or whether cancelled and refunded orders count. Summarize the candidate interpretation
+and ask only the unresolved, result-changing questions.
+
+When the user explicitly says to decide without further questions, proceed in `auto`
+mode and disclose the material assumptions. This never bypasses blacklist, schema,
+permission, dry-run, production-selection, or write-confirmation gates; an agent must
+still stop where those gates require human confirmation.
+
 **Business-language discovery:** When a user uses a business alias, metric, recurring
 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
@@ -357,11 +381,11 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `use` | n/a | Show/switch default named connection (v2 only). |
 | `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`. See **Query workflow flags**. |
+| `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`. |
 | `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. |
+| `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`. |

package/.github/skills/dbcli/reference.md

@@ -220,9 +220,44 @@ dbcli query "SELECT day, dau FROM dau_daily" --ui                # open in brows
 dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdout
 ```
 
-**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--recovery`
+**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--slow-ms <number>`, `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
+#### Passive slow-query hint (`--slow-ms`)
+
+`query` and `q` read the execution time they already measured for a finished
+query and, at or above the threshold, add a hint. Default `1000`; `--slow-ms 0`
+disables it for that invocation. This is **not** the `proxy` / `proxy analyze`
+flag of the same name — that one flags events in the proxy log; this one only
+annotates a single command's own result.
+
+The hint performs no extra work: it never runs `EXPLAIN`, reads a schema, or
+issues a second request. It is suppressed entirely under `--recovery`, so the
+recovery envelope keeps its exact machine contract.
+
+- `--format table` appends `Performance hint: <recommendation>` to the footer.
+- `--format json` adds `metadata.performanceAdvisory`:
+
+```json
+{
+  "metadata": {
+    "statement": "SELECT",
+    "performanceAdvisory": {
+      "code": "SLOW_QUERY",
+      "executionTimeMs": 1250,
+      "thresholdMs": 1000,
+      "recommendation": "Review safely with: dbcli guide slow-query --format markdown. This hint runs no additional database diagnostics."
+    }
+  }
+}
+```
+
+The recommendation is engine-aware: PostgreSQL, MySQL, MariaDB, and Redis are
+pointed at `dbcli guide slow-query`, because that goal resolves to real
+diagnostic snippets for them. MongoDB and Elasticsearch ship no snippet for its
+intents, so their hint states the timing and says so instead of naming a command
+that would come back empty. `csv` and `html` output are unchanged.
+
 Below `admin`, SQL holding more than one statement is rejected, because only the
 first statement would decide the permission check while a driver on the simple
 query protocol executes them all. Semicolons inside string literals, backtick
@@ -529,6 +564,7 @@ dbcli q @analytics/revenue --param days=30 --format html > report.html
 - `--no-limit` — skip the `SELECT * FROM (…) AS _dbcli_guard LIMIT 1000` wrap
 - `--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)
 
@@ -1077,6 +1113,139 @@ Both parameters are required. Keep each expansion as one quoted shell argument;
 never use `eval`, and consider `--execute` only after the plan and captured DDL
 have been reviewed.
 
+### design
+
+Author, validate, render, and review a version-controlled SQL database design
+kept beside the code as `dbcli.design.json`. Every subcommand is offline: none
+opens a database connection, executes DDL, or calls an LLM. `design init` is the
+only writer, and it writes only to the explicit `--output` path.
+
+```text
+dbcli design init --output <path> [--dialect <dialect>]
+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]
+```
+
+```bash
+# Writes only to this explicit, missing path; edit the starter before validating.
+dbcli design init --output ./dbcli.design.json --dialect postgresql
+
+dbcli design validate --format json
+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
+```
+
+| Option | Applies to | Default | Meaning |
+|---|---|---|---|
+| `--output <path>` | `init` | required | Destination for the new artifact; refuses to overwrite an existing file. |
+| `--dialect <postgresql\|mysql\|mariadb>` | `init` | `postgresql` | Target SQL dialect recorded in the artifact. |
+| `--file <path>` | all but `init` | `dbcli.design.json` | Design artifact to read. |
+| `--format <format>` | all but `init` | see below | `validate`/`propose`: `json`, `markdown`. `render`: `json`, `markdown`, `mermaid` (default `markdown`). `diff`: `json` (default), `table`, `markdown`. |
+| `--against-cache` | `diff`, `propose` | off | Compare with the local schema cache; requires a configured PostgreSQL/MySQL/MariaDB connection whose system matches the artifact dialect, and a non-empty cache (run `dbcli schema` first). |
+| `--against-orm <paths>` | `diff`, `propose` | none | Compare with local ORM definition(s); repeatable or comma-separated, DDL paths support globs. Needs no config and no connection. |
+| `--orm-format <format>` | `diff`, `propose` | auto-detect | Force `prisma`, `ddl`, `json`, `drizzle`, `typeorm`, or `sequelize`. |
+| `--ignore <globs>` | `diff`, `propose` | none | Comma-separated table globs excluded from drift. |
+
+`diff` and `propose` require **exactly one** comparison target; passing both or
+neither is an error.
+
+#### Artifact shape
+
+```json
+{
+  "version": 1,
+  "dialect": "postgresql",
+  "models": [
+    {
+      "name": "orders",
+      "table": "orders",
+      "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 }
+      ],
+      "indexes": [{ "name": "orders_customer_idx", "columns": ["customer_id"], "unique": false }]
+    }
+  ],
+  "relationships": [
+    {
+      "name": "orders_customer",
+      "from": { "model": "orders", "field": "customer_id" },
+      "to": { "model": "customers", "field": "id" },
+      "cardinality": "many-to-one"
+    }
+  ],
+  "accessPatterns": [{ "model": "orders", "filters": ["customer_id"], "sort": ["created_at"] }],
+  "decisions": [{ "name": "single-currency", "rationale": "Amounts are stored in minor units, USD only." }]
+}
+```
+
+It holds no SQL, credentials, rows, or provider configuration. `design init`
+emits this envelope with empty `models`, `relationships`, `accessPatterns`, and
+`decisions`.
+
+#### Review findings
+
+`validate` is fail-closed: any `error` finding exits `1`, and `render`, `diff`,
+and `propose` refuse to do their work while errors remain.
+
+| 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` |
+| `warn` | `DUPLICATE_INDEX`, `REDUNDANT_PRIMARY_KEY_INDEX`, `PREFIX_REDUNDANT_INDEX`, `ACCESS_PATTERN_INDEX` |
+
+`REVERSE_RELATIONSHIP` fires when the same endpoints are declared again in the
+opposite direction; `PREFIX_REDUNDANT_INDEX` fires when a non-unique index is a
+leading-column prefix of a longer index. `v1` requires exactly one primary-key
+field per model and an explicit bridge model for `many-to-many`.
+
+#### `design propose` (review-only)
+
+`propose` turns drift into a plan a human reviews; it never applies a write. Each
+entry carries a `safety` of `dry-run` (an existing `migrate` command can represent
+the change losslessly) or `migration-review` (everything else), plus `preflight`,
+`rollback`, and `verification` steps:
+
+```json
+{
+  "table": "orders",
+  "object": "total_cents",
+  "safety": "migration-review",
+  "commands": ["..."],
+  "preflight": [
+    "dbcli blacklist list",
+    "Confirm the exact affected table with: dbcli schema <exact-table> --format json"
+  ],
+  "rollback": "Capture the current schema and generated DDL before any approved write; define the inverse migration before execution.",
+  "verification": [
+    "After an approved write, run: dbcli schema <exact-table> --format json",
+    "Re-run this same design diff command and review the remaining drift."
+  ]
+}
+```
+
+**Workflows:**
+
+- **New project** — `design init` → edit the artifact → `design validate` →
+  `design render`. If application models already exist, use the offline
+  `design diff --against-orm <path>` to reconcile the artifact and the ORM before
+  any database exists.
+- **Existing database** — `blacklist list` → refresh the cache with
+  `schema --format json` → `design diff --against-cache` →
+  `design propose --against-cache`. Review the plan, perform any approved
+  migration separately, then refresh the schema and rerun the same diff.
+
+**Exit codes:** `0` when no errors, `1` when the artifact has review errors, an
+invalid target selection, an unreadable file, or reported drift errors.
+
+An external coding agent may draft the artifact, but a human should review it
+before it is relied upon. Do not create or rewrite `dbcli.design.json` without an
+explicit human request.
+
 ### snapshot
 
 Capture a **result fingerprint** of a query (not schema): `rowCount` plus per-column

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to dbcli are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.52.0] - 2026-08-07 - Offline database design assistant and slow-query hints
+
+### Added
+
+- **Offline database design assistant.** `dbcli design init|validate|render|diff|propose` authors and reviews a version-controlled `dbcli.design.json` beside the code. Every subcommand is offline: none opens a connection, executes DDL, or calls a provider, and `design init` is the only writer — to the explicit `--output` path, refusing to overwrite. `validate` is fail-closed, so `render`, `diff`, and `propose` refuse to work while `error` findings remain; `render` emits `json`, `markdown`, or `mermaid`.
+- **Design drift comparison and review-only proposals.** `design diff` and `design propose` compare the artifact against the local schema cache (`--against-cache`) or local ORM definitions (`--against-orm`, supporting Prisma, DDL, Drizzle, TypeORM, Sequelize, and JSON), with `--orm-format` and `--ignore` for control. `propose` turns drift into a plan a human reviews and never applies a write: each entry carries a `dry-run` or `migration-review` safety level plus `preflight`, `rollback`, and `verification` steps.
+- **Two further design review rules.** `REVERSE_RELATIONSHIP` (error) fires when the same endpoints are declared again in the opposite direction, and `PREFIX_REDUNDANT_INDEX` (warn) fires when a non-unique index is a leading-column prefix of a longer index.
+- **Passive slow-query hint on `query` and `q`.** At or above `--slow-ms` (default 1000, `0` disables), a finished query gains a Performance hint footer and `metadata.performanceAdvisory`. It reuses the execution time already measured — no `EXPLAIN`, no schema read, no second request. The recommendation is engine-aware: PostgreSQL, MySQL, MariaDB, and Redis are pointed at `guide slow-query`; MongoDB and Elasticsearch state the timing instead. `--recovery` suppresses the hint so that envelope keeps its contract.
+
+### Changed
+
+- **Skill reference documents the new surface.** `skills/dbcli/reference.md` gains the `design` section (subcommands, artifact shape, finding codes and severities, the review-only `propose` contract, and workflows) plus the `--slow-ms` flag and the `metadata.performanceAdvisory` shape, disambiguated from the proxy flag of the same name.
+
+### Tests
+
+- Gherkin CLI workflow coverage for workspace inspection, blacklist review, and the verification prune dry run.
+
+## [1.51.2] - 2026-08-07 - Intent confirmation for business requests
+
+### Added
+
+- **Per-request agent intent confirmation.** Installed dbcli skills now support `auto` (default), `confirm`, and `guided` conversational preferences for business-language database requests. Agents ask only result-changing questions, carry confirmed answers forward, and disclose material assumptions when explicitly asked to decide without further questions. These preferences are not persistent CLI configuration and never bypass schema, blacklist, permission, dry-run, production-selection, or write-confirmation gates.
+
 ## [1.51.1] - 2026-08-07 - Proactive semantic context discovery
 
 ### Changed

package/README.md

@@ -1679,6 +1679,7 @@ bun test                  # full test suite (Bun test runner)
 bun run typecheck         # TypeScript compile-time validation
 bun run test:unit         # unit + core tests only
 bun run test:integration  # integration tests
+bun run test:gherkin      # Gherkin feature tests at the CLI boundary
 bun run test:docker       # integration tests with docker-compose.test.yml (MySQL + PostgreSQL)
 bun run build             # bundle CLI to dist/ (used before publish)
 ```

package/README.zh-TW.md

@@ -1558,6 +1558,7 @@ import {
 bun test                  # 完整測試（Bun test runner）
 bun run test:unit         # 僅單元與 core 測試
 bun run test:integration  # 整合測試
+bun run test:gherkin      # CLI 邊界的 Gherkin feature 測試
 bun run test:docker       # 搭配 docker-compose.test.yml（MySQL + PostgreSQL）
 bun run build             # 建置 CLI 至 dist/（發布前使用）
 ```

package/assets/SKILL.md

@@ -82,6 +82,30 @@ warnings) go to stderr so stdout stays parseable — when piping JSON into a par
 use `2>/dev/null` or leave stderr alone. **Never `2>&1`**: it merges those lines back
 into stdout and the parse fails.
 
+**Intent confirmation:** Treat `auto`, `confirm`, and `guided` as conversational
+preferences for the current request, not as dbcli flags or persistent configuration.
+Do not ask the user a meta-question about whether they want questions.
+
+- `auto` (default): autonomously use governed semantic context and schema discovery.
+  If unresolved ambiguity would materially change the result, ask one compact batch of
+  questions before querying; otherwise state the assumptions and proceed.
+- `confirm`: first state the proposed interpretation and wait for the user's approval
+  before issuing the task's data query.
+- `guided`: resolve the request through short, focused questions, carrying confirmed
+  answers forward rather than asking again.
+
+For business requests, material ambiguity includes the requested result shape or grain,
+metric definition, time boundary and timezone, inclusion/exclusion rules (such as order
+status or refunds), grouping, or selected connection. Example: for “yesterday's sales,”
+do not guess whether the user needs a total or detail, which timezone defines yesterday,
+or whether cancelled and refunded orders count. Summarize the candidate interpretation
+and ask only the unresolved, result-changing questions.
+
+When the user explicitly says to decide without further questions, proceed in `auto`
+mode and disclose the material assumptions. This never bypasses blacklist, schema,
+permission, dry-run, production-selection, or write-confirmation gates; an agent must
+still stop where those gates require human confirmation.
+
 **Business-language discovery:** When a user uses a business alias, metric, recurring
 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
@@ -357,11 +381,11 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `use` | n/a | Show/switch default named connection (v2 only). |
 | `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`. See **Query workflow flags**. |
+| `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`. |
 | `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. |
+| `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`. |

package/assets/SKILL.zh-TW.md

@@ -64,6 +64,23 @@ legacy 單檔 `.dbcli`。若要防護同一 OS 使用者的惡意 process，host
 stdout 保持可解析——把 JSON 導進 parser 時請用 `2>/dev/null` 或不要動 stderr。
 **絕對不要用 `2>&1`**：那會把那些訊息併回 stdout，解析必定失敗。
 
+**意圖確認：**將 `auto`、`confirm` 與 `guided` 視為**當次請求**的對話偏好，而不是 dbcli
+旗標或持久化設定。不要先用後設問題詢問使用者「要不要讓我提問」。
+
+- `auto`（預設）：自主使用受治理的 semantic context 與 schema 探索。若尚未解決的歧義會
+  實質改變結果，先用一小批精簡問題確認；否則說明假設後繼續。
+- `confirm`：先說明預計採用的解讀，等待使用者核准後，才發出該任務的資料查詢。
+- `guided`：以短而聚焦的問題逐步釐清請求；已確認的答案必須延續使用，不可重複詢問。
+
+對業務請求而言，會實質改變結果的歧義包括所需結果的形狀或粒度、指標定義、時間邊界與
+時區、納入／排除規則（例如訂單狀態或退款）、分組方式與選用連線。例如「昨天的銷售資料」
+不能猜測使用者要總額或明細、哪個時區定義昨天，或取消與退款訂單是否計入。先摘要候選解讀，
+只詢問尚未解決且會改變結果的問題。
+
+當使用者明確要求自行判斷、不要再問時，以 `auto` 模式繼續並說明重要假設。這絕不繞過
+blacklist、schema、permission、dry-run、production 選取或寫入確認閘門；只要閘門要求人類
+確認，agent 仍必須停止。
+
 **業務語言探索：** 當使用者以業務別名、metric、反覆出現的術語或 relationship/join 意圖，
 而非實體 table 或 field 名稱提出需求時，先執行 `dbcli skill context --format json`。若輸出含有
 `semantic`，將該已檢閱的區塊視為受治理詞彙；需查找特定術語時，用