@carllee1983/dbcli 1.51.2 → 1.52.0

package/.cursor/rules/dbcli.mdc

@@ -381,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/.github/skills/dbcli/SKILL.md

@@ -381,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,23 @@ 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

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

@@ -381,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`. |