@carllee1983/dbcli 1.11.0 → 1.18.0

package/assets/reference.md

@@ -135,9 +135,13 @@ dbcli query "DEL stale:key"                      # requires data-admin+
 # Elasticsearch: DSL body or Lucene q-string
 dbcli query '{"query":{"match":{"status":"active"}}}' --collection orders
 dbcli query 'status:active AND amount:>100' --index orders --limit 50
+
+# Interactive HTML dashboard (see "Interactive HTML dashboard" below)
+dbcli query "SELECT day, dau FROM dau_daily" --ui                # open in browser
+dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdout
 ```
 
-**Options:** `--format <table|json|csv>`, `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`)
+**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`), `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
 > **MongoDB notes:**
@@ -156,6 +160,31 @@ dbcli query 'status:active AND amount:>100' --index orders --limit 50
 > - Hits are flattened: each result row contains `_id` plus dotted-path fields from `_source`. Pass `--format json` to keep nested structures readable.
 > - Query-only mode caps at 1000 hits; `--no-limit` is internally capped at 10 000 (use saved searches / `search_after` for deeper pagination).
 
+### plan
+
+Static SQL risk analyzer. Classifies a statement into the same permission tiers
+used by `query` (`query-only` / `read-write` / `data-admin` / `admin`) and lists
+the underlying signals (DML / DDL / multi-statement / unsafe constructs) without
+ever connecting to the database.
+
+```bash
+dbcli plan "SELECT * FROM users"
+dbcli plan "UPDATE users SET name='x'"           # human-readable text classification
+dbcli plan "DROP TABLE users" --format json      # machine-readable risk report
+```
+
+**Options:** `--format <text|json>` (default `text`).
+**Permission:** n/a (offline analyzer; no connection opened).
+
+Use cases:
+- Agents that want to decide whether to call `query` vs `insert` / `update` /
+  `delete` before sending SQL.
+- Pre-flight safety check before binding parameters into a saved snippet.
+- Lint hook for code review pipelines that store SQL in source.
+
+`plan` does not enforce blacklist or auto-`LIMIT`; those still apply when the
+SQL is actually executed via `query` / `q`.
+
 ### q
 
 Run a saved query snippet by `@name`. Snippets are parameterised SELECT/WITH statements resolved from three layers, with **local > shared > builtin** precedence (a local file always shadows shared and builtin variants of the same key):
@@ -172,15 +201,19 @@ dbcli q @dau --param days=30 --format json    # override a param
 dbcli q @analytics/revenue --param-file params.json
 dbcli q @dau --dry-run                        # show final SQL + bind values
 dbcli q @dau --no-limit                       # disable size guard wrap
+dbcli q @analytics/revenue --param days=30 --ui                       # open dashboard
+dbcli q @analytics/revenue --param days=30 --format html > report.html
 ```
 
 **Options:**
-- `--format <table|json|csv>` — output format (default: `table`)
+- `--format <table|json|csv|html>` — output format (default: `table`)
+- `--ui` — open the rendered HTML dashboard in the system browser (implies `--format html`; writes to a temp file then invokes `open` / `xdg-open` / `start`)
 - `--param <key=value>` — pass a parameter (repeatable)
 - `--param-file <path>` — JSON object whose keys are param names
 - `--no-limit` — skip the `SELECT * FROM (…) AS _dbcli_guard LIMIT 1000` wrap
 - `--dry-run` — print the bound SQL + values without executing
 - `--use <name>` — pick a v2 named connection
+- `--recovery` — emit a `RecoveryEnvelope` on failure (see `recover`)
 
 **Permission:** query-only+
 
@@ -201,6 +234,13 @@ Each `.sql` file is plain SQL with optional YAML frontmatter inside a leading `-
 --     description: lookback window in days
 --     enum: [7, 30, 90]
 -- tags: [analytics]
+-- intent: perf.slow-query   # optional; consumed by `queries suggest`
+-- visual:                   # optional; consumed by `--ui` / `--format html`
+--   title: Daily Active Users
+--   kpis:
+--     - { label: DAU, value_column: dau, format: number }
+--   charts:
+--     - { type: line, title: DAU trend, x: day, y: [dau] }
 -- ---
 SELECT COUNT(DISTINCT user_id) AS dau
 FROM events
@@ -209,6 +249,8 @@ WHERE created_at > NOW() - (:days || ' days')::interval;
 
 Param placeholders use `:name`. They are rewritten to `$1, $2, …` (Postgres) or `?, ?, …` (MySQL) at execution time and passed as bind values — string interpolation is never used.
 
+The `visual:` block is documented in detail under [Interactive HTML dashboard](#interactive-html-dashboard) below. Unknown / malformed fields are silently dropped at parse time; the snippet still runs and the dashboard falls back to a sortable table.
+
 #### Param type coercion
 
 | Declared `type` | Accepts |
@@ -299,6 +341,10 @@ dbcli queries list --tag analytics --engine postgres --format json
 dbcli queries list --source local       # only personal overrides
 dbcli queries show @dau                 # frontmatter + SQL
 dbcli queries show @dau --format json   # MCP-shaped contract
+dbcli queries search slow query         # fuzzy-ranked keyword search across snippets
+dbcli queries search cache --engine postgres --source builtin --limit 5
+dbcli queries suggest perf              # browse snippets by intent prefix (v1.11+)
+dbcli queries suggest perf.cache-hit --format json
 
 # Authoring
 dbcli queries new @new/sample           # scaffold under .dbcli-shared/queries/
@@ -319,8 +365,10 @@ dbcli queries export @dau --output dau.sql          # write snippet body to a fi
 dbcli queries export @diag/connections --engine postgres  # pick a variant when multiple engines exist
 ```
 
-**`list` options:** `--format <table|json|csv>`, `--tag <tag>`, `--engine <postgres|mysql>`, `--source <local|shared>`
+**`list` options:** `--format <table|json|csv>`, `--tag <tag>`, `--engine <postgres|mysql|redis|elasticsearch|all>`, `--source <local|shared|builtin|all>`
 **`show` options:** `--format <table|json|csv>`
+**`search` options:** `--format <table|json>`, `--engine <postgres|mysql|redis|elasticsearch|all>`, `--source <local|shared|builtin|all>`, `--limit <n>` (default 10), `--include-internal` (show fuzzy ranking score). Keyword(s) are fuzzy-matched against name, description, tags, intent.
+**`suggest` options:** `--format <table|json>`, `--engine <postgres|mysql|redis|elasticsearch|all>`, `--source <local|shared|builtin|all>`. Intent prefix-matched against the snippet's `intent` frontmatter field. Common intents: `perf.slow-query`, `perf.cache-hit`, `capacity.size`, `safety.connections`, `monitor.cluster-health`.
 **`new` options:** `--local`, `--edit`
 **`edit` options:** `--shared`
 **`check` options:** `--strict`, `--format <table|json|csv>`
@@ -378,11 +426,15 @@ Export query results to file or stdout.
 dbcli export "SELECT * FROM users" --format csv --output users.csv
 dbcli export "SELECT * FROM users" --format csv --output users.csv --force  # Skip overwrite confirmation
 dbcli export "SELECT * FROM users" --format json | jq '.[]'
+dbcli export "SELECT * FROM users" --format jsonl --output users.ndjson
+dbcli export "SELECT * FROM orders" --format html --output orders.html      # standalone dashboard
 ```
 
-**Options:** `--format <json|csv>` (required), `--output <path>`, `--force`
+**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`
 **Permission:** query-only+
 
+The `html` format emits the same self-contained dashboard as `query --ui` (see [Interactive HTML dashboard](#interactive-html-dashboard)). Because `export` runs raw SQL (no snippet metadata), the HTML report is always rendered as a sortable / filterable table — no KPIs or charts. Use `dbcli q @<name> --format html` (or `--ui`) for the charted view.
+
 ### blacklist
 
 Manage sensitive data blacklist to prevent AI access to restricted tables/columns.
@@ -439,6 +491,302 @@ dbcli status --format text      # Human-readable text output
 **Output:** `permission`, `system`, `blacklist` summary, `version`
 **Permission:** query-only+
 
+### inspect
+
+Read-only snapshot for AI agents. Never emits credentials or blacklisted values.
+
+| Flag | Purpose |
+|------|---------|
+| `--format <json\|markdown>` | Output format (default `json`) |
+| `--brief` | Drop sample arrays and trim suggested commands to ≤3 |
+| `--for-agent` | Shortcut for `--format json --brief` |
+| `--no-connect` | Skip the cheap version/object probe (no DB traffic) |
+| `--probe-timeout <ms>` | Hard timeout for the version/object probe (default 1500) |
+
+Example:
+
+```bash
+dbcli inspect --for-agent
+```
+
+Output schema is locked at `schemaVersion: 1`. Sections: `connection`, `permission`, `blacklist`, `objects`, `schemaCache`, `snippets`, `suggestedCommands`, `warnings`.
+
+**Permission:** query-only+
+
+### report
+
+Diagnostic report built on top of `inspect`. Reuses inspect context (connection,
+permission, blacklist, snippet inventory) and additionally runs curated built-in
+`@diag/*` snippets grouped into sections.
+
+Flags:
+- `--format json|markdown` (default: json)
+- `--section health,capacity,perf` (default: all three)
+- `--brief` — drop evidence rows; keep counts and statuses
+- `--for-agent` — shortcut for `--format json --brief`
+- `--no-connect` — context-only snapshot (skip diagnostics + inspect probe)
+- `--per-snippet-timeout <ms>` (default 3000)
+- `--max-rows-per-evidence <n>` (default 50)
+- `--probe-timeout <ms>` (default 1500, inherited from inspect)
+
+Examples:
+
+    dbcli report --format json
+    dbcli report --format markdown --section health,capacity
+    dbcli report --for-agent
+    dbcli report --no-connect
+
+Boundaries:
+- Read-only. Skips snippets whose required params have no default value.
+- Never connects in `--no-connect` mode.
+- MongoDB and no-config workspaces emit a context-only snapshot with a warning.
+
+**Permission:** query-only+
+
+### guide
+
+Deterministic next-command planner for a fixed set of database goals. Reuses
+`inspect` context (cache-first) and the workspace's saved-query inventory to
+emit an ordered, read-only plan that an AI agent can follow step-by-step.
+
+Goals (fixed list):
+- `slow-query` — diagnose slow queries (long-running, locks, cache, indexes).
+- `capacity` — audit storage and memory.
+- `health` — connections, locks, cluster status.
+- `index-usage` — index effectiveness audit.
+- `permissions` — review permission level, blacklist, snippet inventory.
+- `schema-overview` — orient in an unfamiliar database.
+
+Flags:
+- `--format json|markdown` (default: json)
+- `--brief` — drop rationale + expects fields
+- `--for-agent` — shortcut for `--format json --brief`
+- `--list` — list available goals and exit
+- `--probe` — refresh inspect context via live probe (default: cache-first)
+- `--probe-timeout <ms>` (default 1500, inherited from inspect)
+
+Examples:
+
+    dbcli guide slow-query
+    dbcli guide capacity --format markdown
+    dbcli guide --list
+    dbcli guide health --for-agent
+    dbcli guide schema-overview --probe
+
+Boundaries:
+- Read-only. Guide plans commands; it does not execute them.
+- Goal vocabulary is fixed in v1.14.0; user-supplied goals are rejected.
+- Each step carries `risk: 'readonly'` in v1.14.0 (forward-compatible with v1.15.0 recovery).
+- Coexists with `dbcli skill tasks plan` (template-driven). Use guide for ad-hoc goals; use task packs for repeatable workflows.
+
+**Permission:** query-only+
+
+### recovery
+
+Machine-readable error envelope. Two surfaces share one `RecoveryEnvelope`
+shape (`schemaVersion: 1`):
+
+1. **Standalone lookup**: `dbcli recovery --code <CODE>` synthesizes an
+   envelope for any known recovery code without needing a real failure.
+2. **Failing-command opt-in**: pass `--recovery` to `dbcli query` or
+   `dbcli q`. On failure, the envelope is written to stdout as JSON, the
+   human stderr message is suppressed, and the process exits non-zero.
+
+Recovery codes (fixed in v1.15.0):
+- `CONFIG_MISSING` — no `.dbcli` config; run `dbcli init`.
+- `CONN_REFUSED` / `CONN_AUTH_FAILED` / `CONN_TIMEOUT` / `CONN_HOST_NOT_FOUND` / `CONN_UNKNOWN` — connection failure variants.
+- `PERMISSION_DENIED` — active permission level forbids the operation.
+- `BLACKLIST_TABLE` / `BLACKLIST_COLUMN_WRITE` — blacklist violations.
+- `SNIPPET_NOT_FOUND` / `SNIPPET_AMBIGUOUS` / `SNIPPET_PARAM_MISSING` — saved-query failures.
+- `SCHEMA_CACHE_MISSING` — local schema cache missing or stale.
+- `UNKNOWN` — fallback for unclassified errors.
+
+Flags (lookup mode):
+- `--code <CODE>` — required unless `--list` is set.
+- `--list` — list all codes and exit.
+- `--format json|markdown` (default: json).
+- `--brief` — drop `rationale` + `expects` from steps.
+- `--for-agent` — shortcut for `--format json --brief`.
+- `--hint <text>` — bind into placeholder steps.
+- `--snippet <name>` — bind snippet placeholder.
+- `--table <name>` — bind table placeholder.
+
+Examples:
+
+    dbcli recovery --code CONN_REFUSED
+    dbcli recovery --code BLACKLIST_TABLE --table users --format markdown
+    dbcli recovery --list --for-agent
+    dbcli query "SELECT * FROM users" --recovery
+    dbcli q @diag/missing --recovery
+
+Boundaries:
+- Recovery only **suggests** commands; agents (or humans) execute them. No automatic remediation in v1.15.0.
+- As of v1.16.0, `--recovery` is honored on `query`, `q`, `insert`, `update`, `delete`, `export`, `schema`, and `inspect`. Other commands (`report`, `guide`, `doctor`, `migrate`, `init`, `use`, `status`, `list`, `check`, `diff`, `plan`, `shell`, `blacklist`, `completion`, `upgrade`, `skill`) keep their existing error behavior.
+- `dbcli inspect --require-schema-cache` throws `SCHEMA_CACHE_MISSING` when the active SQL connection has no usable schema cache. Combine with `--recovery` for the structured envelope.
+- `BLACKLIST_COLUMN_WRITE` and `PERMISSION_DENIED` envelopes prepend a `risk: 'dry-run'` step (e.g. `dbcli insert <table> --dry-run`) when the failing operation was an INSERT / UPDATE / DELETE.
+- Recovery steps reuse the v1.14.0 `GuideStep` shape, including the full `risk` enum (`readonly` / `dry-run` / `write` / `unknown`).
+
+**Permission:** n/a
+
+### recover
+
+(v1.17.0+) Inspect or apply the last recovery plan saved by `--recovery`.
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--apply` | Execute the saved plan under risk gating. | off (inspect only) |
+| `--from <path>` | Read the envelope from this file instead of `.dbcli/last-recovery.json`. Accepts raw `RecoveryEnvelope` or `SavedRecoveryEnvelope`. | — |
+| `--allow-write <tier>` | Open the risk gate. Values: `readonly-cmd` (local-side writes) \| `write-cmd` (database writes). | `none` |
+| `--no-verify` | Skip the verify step appended after a successful `--apply`. | off (verify runs by default) |
+| `--format <format>` | `markdown` \| `json`. | `markdown` for inspect, `json` for `--apply` |
+
+#### Plan source resolution
+
+1. `--from <path>` if provided. The file must be either a raw `RecoveryEnvelope` or a `SavedRecoveryEnvelope` wrapper. When the file is a `SavedRecoveryEnvelope`, its `cwd` is reused for child-process execution. Strict zod validation; malformed → exit 2 with structured reason.
+2. Otherwise, `.dbcli/last-recovery.json` (auto-saved on every recovery emission). Validated with the same schema; missing fields, unknown `error.code`, or `cwd` that no longer exists → exit 2.
+3. Otherwise, exits 2 with `No recovery plan available. Run a command with --recovery to generate one, or pass --from <file>.`
+
+#### Code-owned tier (trust boundary)
+
+`--apply` derives the canonical execution tier from the per-`error.code` allowlist after parsing argv, **not** from the envelope's `risk` / `dbWrite` / `interactive` fields. Envelope hints can only widen safety (skip more steps); they cannot escalate execution.
+
+| Allowlist tier | Meaning | Example commands |
+|---|---|---|
+| `readonly` | local read-only | `dbcli inspect`, `dbcli doctor`, `dbcli blacklist list`, `dbcli schema <table>` |
+| `dry-run` | write subcommand invoked with `--dry-run` | `dbcli update orders --where id=1 --dry-run`, `dbcli q @x --dry-run` |
+| `local-write` | writes local config / cache / blacklist | `dbcli blacklist remove <table>`, `dbcli use <name>`, `dbcli schema --refresh` |
+| `db-write` | mutates the connected database | `dbcli update orders --where id=1 --set …` (no `--dry-run`), `dbcli q @x` (no `--dry-run`) |
+| `interactive` | requires TTY | `dbcli init`, `dbcli init --force` |
+
+`insert` / `update` / `delete` / `q` are tier `dry-run` only when argv contains `--dry-run`; otherwise they are tier `db-write` regardless of envelope `risk` claim.
+
+#### Risk gate matrix
+
+| Allowlist tier | Default | `--allow-write=readonly-cmd` | `--allow-write=write-cmd` |
+|---|---|---|---|
+| `readonly` | run | run | run |
+| `dry-run` | run | run | run |
+| `local-write` | `skipped:risk` | run | run |
+| `db-write` | `skipped:risk` | `skipped:risk` | run |
+| `interactive` | `skipped:interactive` | `skipped:interactive` | `skipped:interactive` |
+| unresolved placeholder in `command` | `skipped:placeholder` | `skipped:placeholder` | `skipped:placeholder` |
+| command fails parse / allowlist | `skipped:unsafe-command` | `skipped:unsafe-command` | `skipped:unsafe-command` |
+
+Precedence: envelope `interactive: true` > `placeholder` > `unsafe-command` > allowlist `interactive` > tier-based gating.
+
+#### Exit codes
+
+| Code | Condition |
+|---|---|
+| 0 | At least one step ran successfully and no step failed. |
+| 1 | A step exited non-zero (fail-fast); see `stoppedAt`. |
+| 2 | Envelope missing or malformed (failed schema validation, or saved `cwd` missing). |
+| 3 | Every step was skipped — open `--allow-write` or fill placeholders. |
+
+#### Auto-saved envelope
+
+Every command that emits a `RecoveryEnvelope` (`query`, `q`, `insert`, `update`, `delete`, `export`, `schema`, `inspect` — all with `--recovery`) atomically writes the envelope to `.dbcli/last-recovery.json`. The wrapper carries `schemaVersion`, `savedAt`, a sanitized `command` summary, the workspace `cwd`, and the envelope itself. SQL text and `--where` / `--set` / `--data` / `--param` values are redacted as `<sql>` or `<redacted>`. `.dbcli/` is gitignored.
+
+#### Verification (P4)
+
+Each `RecoveryEnvelope` now carries an optional `verify: GuideStep` (always
+`risk: 'readonly'`, never carries placeholders). `dbcli recover --apply` runs
+the verify step after the main plan, only when `finalStatus === 'ok'` and
+`--no-verify` is not set.
+
+| Recovery code | Verify command | Heuristic |
+|---|---|---|
+| CONFIG_MISSING | `dbcli inspect --no-connect --format json` | `connection.name` truthy → passed |
+| CONN_REFUSED / CONN_TIMEOUT / CONN_UNKNOWN / CONN_AUTH_FAILED / CONN_HOST_NOT_FOUND | `dbcli doctor --format json` | exit 0 → passed |
+| PERMISSION_DENIED | `dbcli inspect --for-agent` | exit 0 → passed |
+| BLACKLIST_TABLE | `dbcli inspect --for-agent` | exit 0 → passed |
+| BLACKLIST_COLUMN_WRITE | `dbcli inspect --for-agent` | exit 0 → passed |
+| SNIPPET_NOT_FOUND / SNIPPET_AMBIGUOUS / SNIPPET_PARAM_MISSING | `dbcli queries list --format json` | exit 0 → passed |
+| SCHEMA_CACHE_MISSING | `dbcli inspect --format json` | `schemaCache.available === true` → passed |
+| UNKNOWN | `dbcli doctor --format json` | exit 0 → passed |
+
+`verifyStatus` values:
+
+- `passed` — heuristic confirmed.
+- `failed` — verifier exited non-zero or timed out.
+- `indeterminate` — verifier exited 0 but expected shape not present, or the
+  step was gated (placeholder / unsafe-command); agents should re-check.
+
+Exit codes are unchanged — `verifyStatus` is signal, not gate.
+
+**Schema additions.** `RecoveryEnvelope.verify?: GuideStep` is additive (no
+`schemaVersion` bump). v1.16 consumers ignore the field.
+
+#### Multi-turn `--next` (P2)
+
+`dbcli recover --next` returns the single next step in a saved recovery plan,
+given which step the agent just executed and the result of that step. v1 walks
+the plan linearly; future codes may branch on `prevResult.stdoutSummary`
+deterministically.
+
+| Flag | Required | Description |
+|---|---|---|
+| `--next` | yes | Activate the multi-turn lookup. |
+| `--after-step <n>` | yes | 1-based order of the step the agent just executed. Range: `[1, envelope.recovery.length]`. |
+| `--result <value>` | yes | JSON `StepResultSummary` (inline) or `@<path>` to read from a file. |
+| `--from <path>` | no | Override the auto-saved envelope. |
+| `--format <fmt>` | no | `json` (default) or `markdown`. |
+
+`--next` and `--apply` cannot be combined. `--allow-write` and `--no-verify`
+are silently ignored under `--next` (no execution, no verification).
+
+**`StepResultSummary` shape**
+
+```ts
+interface StepResultSummary {
+  status: 'ok' | 'failed' | 'skipped'
+  exitCode?: number
+  stdoutSummary?: string  // last 4 KB; longer rejected
+  stderrSummary?: string  // last 4 KB; longer rejected
+}
+```
+
+`@<path>` resolves relative to the dbcli invocation cwd. File whole-size cap is
+64 KB; per-field 4 KB cap still applies.
+
+**`NextResult` shape (output)**
+
+```ts
+interface NextResult {
+  schemaVersion: 1
+  kind: 'step' | 'done'
+  source: { kind: 'auto' | 'from'; path: string }
+  errorCode: RecoveryCode
+  cursor: number       // step.order when kind='step'; totalSteps when 'done'
+  totalSteps: number
+  step?: GuideStep     // present iff kind='step'
+}
+```
+
+**Exit codes**
+
+| Exit | Condition |
+|---|---|
+| 0 | Returned a step or `done`. |
+| 2 | Envelope missing/malformed; `--after-step` missing/out-of-range; `--result` missing/malformed; `--next` combined with `--apply`. |
+
+**Examples**
+
+```bash
+# Walk a 3-step plan to completion
+dbcli recover --next --after-step 1 --result '{"status":"ok"}'   # → step 2
+dbcli recover --next --after-step 2 --result '{"status":"ok"}'   # → step 3
+dbcli recover --next --after-step 3 --result '{"status":"ok"}'   # → done
+
+# Result read from file (when stdout is large)
+dbcli recover --next --after-step 1 --result @/tmp/r1.json
+
+# Markdown for human inspection
+dbcli recover --next --after-step 1 --result '{"status":"ok"}' --format markdown
+```
+
+**Permission:** n/a (always-allowed lookup; child processes inherit the active permission level).
+
 ### doctor
 
 Run diagnostic checks on environment, configuration, connection, and data.
@@ -554,6 +902,32 @@ 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.
 
+### skill
+
+Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or one of
+four AI-agent platform directories. The skill is the source of truth that lets
+Claude Code / Gemini / Copilot / Cursor know how to drive dbcli safely.
+
+```bash
+dbcli skill                                  # print SKILL.md to stdout
+dbcli skill --output ./SKILL.md              # write to a file (no platform install)
+dbcli skill --install claude                 # install to ~/.claude/skills/dbcli/
+dbcli skill --install gemini                 # install to ~/.gemini/skills/dbcli/
+dbcli skill --install copilot                # install to .github/skills/dbcli/ (repo-local)
+dbcli skill --install cursor                 # install to .cursor/skills/dbcli/ (repo-local)
+```
+
+**Options:**
+- `--install <platform>` — `claude` | `gemini` | `copilot` | `cursor`. Writes `SKILL.md` plus `reference.md` next to it so the agent gets progressive disclosure.
+- `--output <path>` — write `SKILL.md` to a file instead of stdout. Does not install `reference.md`.
+
+**Notes:**
+- Both files come straight from `assets/SKILL.md` + `assets/reference.md` inside the dbcli package — no runtime rendering. Keep these in sync when shipping a release.
+- `claude` / `gemini` install paths are user-global; `copilot` / `cursor` are repo-local under `.github/` / `.cursor/`.
+- Re-running `--install` overwrites the existing skill atomically; no prompt.
+
+**Permission:** n/a.
+
 ### skill tasks (Agent Task Packs)
 
 ```bash
@@ -581,6 +955,108 @@ Task storage layers:
 Higher tiers override lower tiers by task name. Task name is derived from the
 file path under the tier root (e.g. `diag/inspect.md` → `diag/inspect`).
 
+## Interactive HTML dashboard
+
+`query`, `q`, and `export` can render results as a single, fully self-contained
+HTML file backed by a bundled React + Recharts template. The template lives at
+`assets/ui-template.html` and is installed alongside the binary; no external
+network, CDN, or runtime is required to view the report.
+
+### Entry points
+
+| Command form | Behaviour |
+|--------------|-----------|
+| `dbcli query "<sql>" --ui` | Render to a temp file under `$TMPDIR/dbcli-query-<ts>.html` and open with `open` / `xdg-open` / `start`. |
+| `dbcli q @<name> --ui` | Same, with snippet metadata (`name`, `description`, `visual:` block). |
+| `dbcli query "<sql>" --format html` | Print HTML to stdout (pipe, redirect, attach). |
+| `dbcli q @<name> --format html` | Same, snippet-aware. |
+| `dbcli export "<sql>" --format html --output report.html` | Write HTML to an explicit path; respects `--force` / overwrite confirmation. |
+
+`--ui` is a convenience flag — it implies `--format html` and then opens the
+file. `--ui` and `--format` are mutually compatible; passing both is allowed and
+behaves as `--ui`.
+
+### Data injection contract
+
+The template ships with a single placeholder, `/*DBCLI_PAYLOAD*/`, which dbcli
+replaces with:
+
+```js
+window.__DBCLI_PAYLOAD__ = { "meta": {...}, "rows": [...] };
+```
+
+Hardening rules applied before injection:
+
+- Payload is `JSON.stringify(...)`-encoded.
+- Every `<` is replaced with `<` so a malicious row containing `</script>`
+  cannot terminate the inline script tag.
+- Blacklist redaction (`dbcli blacklist`) runs **before** the formatter — masked
+  columns never reach the dashboard.
+- The replacement uses a function callback (`html.replace(..., () => injection)`)
+  so `$&`-style backreferences in the payload are not interpreted.
+
+### `meta` shape
+
+`meta` is the `SavedQueryMeta` object (see `dbcli queries show @<name> --format json`):
+
+```jsonc
+{
+  "name": "Revenue Trend",        // display title
+  "key":  "@analytics/revenue",   // snippet key, or "raw-sql" / "export"
+  "description": "...",           // free text (SQL preview for raw query)
+  "params": [...],                // ParamSpec[]
+  "tags":   ["analytics"],
+  "intent": "perf.slow-query",
+  "visual": { ... }               // optional, see below
+}
+```
+
+For raw `query` / `export` invocations, `meta.params` is `[]` and
+`meta.visual` is absent — the dashboard renders a sortable / filterable table.
+
+### `visual:` block (snippet frontmatter)
+
+```yaml
+visual:
+  title: Revenue (last :days days)   # optional override of meta.name
+  kpis:
+    - label: Total Revenue
+      value_column: total_revenue    # must exist in result rows
+      format: currency               # currency | number | percent (optional)
+    - label: Orders
+      value_column: order_count
+      format: number
+  charts:
+    - type: line                     # line | bar | area | pie | scatter
+      title: Daily Revenue
+      x: day                         # column for X axis
+      y: [revenue]                   # 1..N columns for series
+    - type: bar
+      title: By Channel
+      x: channel
+      y: [revenue, refunds]
+```
+
+Parser behaviour (`src/core/saved-queries/parser.ts::normaliseVisual`):
+
+- The block is **optional**. Missing → table-only render.
+- Items missing required fields (`kpi.label` + `kpi.value_column`, or
+  `chart.type` + `chart.x` + `chart.y[]`) are silently dropped.
+- Unknown `format` / `type` values are forwarded as strings; the dashboard
+  decides how to render them (unknown chart types fall back gracefully).
+- The snippet still executes as a normal SQL/DSL query — `visual:` only affects
+  the HTML renderer.
+
+### Limitations
+
+- The dashboard is read-only; there is no in-page editor or re-run button.
+- Raw `query` / `export` HTML output never shows KPIs or charts (no snippet
+  metadata is available). Use `dbcli q @<name>` for the charted view.
+- Engine support follows the underlying command: SQL, MongoDB (`--collection`),
+  Redis, and Elasticsearch (`--collection`) all render through the same template.
+- Very wide / very long result sets render as a single client-side table; for
+  >10k rows prefer `--format csv` / `--format jsonl` and a downstream tool.
+
 ## MongoDB Support
 
 MongoDB connections use a JSON-based query model instead of SQL. Treat MongoDB support as a narrower document-database path, not as a full SQL feature equivalent.