@carllee1983/dbcli 7.0.0 → 8.0.0

package/assets/SKILL.md

@@ -127,7 +127,11 @@ 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
+`dbcli skill context --context-version 2 --format json`. This offline, bounded contract
+does not read project source, open a connection, scan Redis, or interpret natural language.
+Read project code only through this agent's own workspace safety checks; never pass source
+paths or contents to dbcli. If `gaps` reports missing evidence, do not guess metadata: inspect
+permitted code or ask for it. If it includes `semantic`, treat that reviewed
 section as the governed vocabulary; use `dbcli semantic search <terms> --format json`
 to look up a specific term. If `contracts` is present, use only its approved terms and
 their descriptive evidence policy; it never authorizes an assertion or query. If no semantic section exists or search returns no result, fall back to `blacklist` → `schema` mapping and tell the user that optional
@@ -135,6 +139,64 @@ their descriptive evidence policy; it never authorizes an assertion or query. If
 migrate that file without an explicit human request; semantic vocabulary never replaces
 schema confirmation or the normal query/write safety gates.
 
+## Capability discovery
+
+Before composing a workflow, ask dbcli what it can do here rather than assuming. The
+catalog is static and the check reads only the local config — **neither opens a database
+connection.**
+
+```bash
+dbcli capabilities --format json                                  # full catalog
+dbcli capabilities --format markdown                              # table for docs
+dbcli capabilities check --require schema.read,query.read         # gate your workflow
+dbcli capabilities check --require data.delete --format json      # machine-readable
+```
+
+For a copyable Bun/TypeScript consumer with strict parsing, schema pins, exit handling,
+Operation Envelope handling, Task Pack `safety.requires`, and correlation/evidence guidance,
+start with `assets/integration-kit/README.md`.
+
+A capability is one atomic dbcli ability (`schema.read`, `data.delete`), never a job or a
+method. `dba.tune-production` and `crud.scaffold` belong to the Role or Method Skill that
+composes dbcli — this Tool Skill only covers operating dbcli safely.
+
+- `schemaVersion` is the capability contract version, **not** the npm package version.
+- Statuses are `available`, `unavailable` (reason `engine`, `agent-mode`, `permission`,
+  `context-unavailable` or `context-unresolvable`) and `unknown`. A misspelled id fails
+  closed and is never guessed.
+- Under `DBCLI_AGENT_MODE=1`, capabilities that change configuration are `unavailable`
+  with reason `agent-mode` whatever the permission level says.
+- Exit codes: `0` all available, `1` any unavailable or unknown, `2` bad input.
+- **`available` is not approval.** Blacklist, write gate, confirmation and audit still run
+  at execution time, and `admin` in a config file is a permission level, not a DBA sign-off.
+- v1 covers the commands the engine capability matrix governs; anything outside it returns
+  `unknown` rather than an unaudited engine claim.
+
+**Agent output v1 (PLAT-005):** use `dbcli --agent-output capabilities` or
+`dbcli --agent-output capabilities check --require <ids>`; the root flag must precede the
+subcommand, and no other operation is supported yet. It writes one compact UTF-8 JSON envelope plus
+newline to stdout, with empty stderr. Its ten keys are `schemaVersion`, `ok`, `operation`, `status`,
+`context`, `data`, `warnings`, `evidence`, `recovery`, and `error`; `schemaVersion` is `1`,
+`operation` is `capabilities.list` or `capabilities.check`, and `status` is `succeeded` or `failed`.
+Do not combine it with explicit `--format` or `--for-agent`: conflicts, invalid placement/input, and
+unsupported operations exit `2`; success exits `0`; unmet requirements and internal failures exit `1`.
+The envelope is capped at 64 KiB including newline, and consumers use field names rather than order.
+The optional root `--correlation-id <id>` must also precede the subcommand. It accepts 1–160 ASCII
+letters, numbers, `.`, `_`, `:`, or `-`; never put secrets or free-form input in it.
+For supported non-static output it appears as `context.correlationId` and existing audit
+`metadata.correlation_id`; command summaries redact it. Static capabilities stays `context: null`.
+It creates no evidence receipt.
+
+Code/message vocabulary is locale-independent English: errors are
+`INVALID_AGENT_OUTPUT_OPTIONS` (invalid/misplaced/conflicting options),
+`INVALID_CORRELATION_ID` (invalid or missing `--correlation-id` value),
+`UNSUPPORTED_AGENT_OUTPUT_OPERATION` (outside PLAT-004), `INVALID_CAPABILITY_REQUIREMENTS`
+(invalid `--require`), `CAPABILITY_REQUIREMENTS_UNMET` (completed negative result),
+`AGENT_OUTPUT_LIMIT_EXCEEDED` (64 KiB limit), and `AGENT_OUTPUT_INTERNAL_ERROR` (unexpected
+safe failure). Warnings are `DUPLICATE_CAPABILITY_REQUIREMENT`,
+`CAPABILITY_CONTEXT_UNAVAILABLE`, `CAPABILITY_CONTEXT_UNRESOLVABLE`, and
+`AGENT_MODE_RESTRICTION_ACTIVE`.
+
 ## Agent Task Packs
 
 When the user asks for a database workflow ("diagnose this slow query", "audit
@@ -418,6 +480,7 @@ Full flags and edge cases: see [reference.md](reference.md#init).
 |---------|-----------------|---------|
 | `init` | n/a | Create `.dbcli` (v1 single or v2 multi via `--conn-name` / `--env-file`). **Usually run by the human** — do NOT re-run to strip `{"$env"}` references; that format is intentional. |
 | `use` | n/a | Show/switch default named connection (v2 only). |
+| `capabilities` | n/a | Static capability catalog + `check --require <ids>` requirement gate. No database connection. `--format text\|json\|markdown` (`check` is `text\|json`). Exit `0`/`1`/`2`. |
 | `list` | query-only+ | Tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch). |
 | `schema` | query-only+ | SQL: per-table or full scan into `.dbcli/schemas/`. MongoDB: sampled. ES: flattened mapping. Redis: per-key only (type/TTL/size). Supports `--recovery`. |
 | `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). `--format table\|json\|csv\|html`, `--ui` to open the interactive dashboard in a browser. `--fields` (projection), `--truncate` (cell width), `-f/--query-file` (read query from file or stdin), `--use a,b` (read-only fan-out). Supports `--recovery`. `--slow-ms <n>` sets the passive slow-query hint threshold (default 1000, `0` off): at or above it, table output gains a `Performance hint` footer and JSON gains `metadata.performanceAdvisory`; it runs no extra diagnostics and is suppressed under `--recovery`. Distinct from the `proxy` flag of the same name. See **Query workflow flags**. |
@@ -639,7 +702,7 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 ## Notes
 
 - Query-only mode auto-appends `LIMIT 1000`; add `--no-limit` for `information_schema` or statements that break with `LIMIT`.
-- Blacklisted tables and columns are redacted from query output.
+- Blacklisted tables and columns are redacted from query output. Every entry in `blacklist.tables` and `blacklist.columns` is a glob (`*`, `?`, `[a-z]`) on every engine, and a rule is compared against the whole dotted path case-insensitively — a rule spelled `password` also covers `Password`, and `profile.ssn` covers `profile.SSN`; a table literally named `report*` has to be written `report\*` to match literally again. `--fields` is unaffected and still matches exactly. A rule that cannot mean anything is rejected when the config loads rather than silently protecting nothing: a column entry qualified with its own table (`{"users": ["users.password"]}`) fails to load, and an unparsable rule makes every `dbcli es` request fail until it is fixed.
 - `schema` reports `estimatedRowCount` and `sizeCategory` (small / medium / large / huge). For large/huge tables add `WHERE` or `LIMIT` — bands in [reference.md](reference.md#schema).
 - `doctor` on `mongodb+srv://` reports whether SRV resolves natively or through the DoH fallback — useful when the runtime restricts DNS.
 - **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `--timeout <ms>`, `--statement-timeout <ms>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.

package/assets/SKILL.zh-TW.md

@@ -99,7 +99,9 @@ blacklist、schema、permission、dry-run、production 選取或寫入確認閘
 確認，agent 仍必須停止。
 
 **業務語言探索：** 當使用者以業務別名、metric、反覆出現的術語或 relationship/join 意圖，
-而非實體 table 或 field 名稱提出需求時，先執行 `dbcli skill context --format json`。若輸出含有
+而非實體 table 或 field 名稱提出需求時，先執行 `dbcli skill context --context-version 2 --format json`。這個離線、受限的 contract
+不會讀取 project source、開啟連線、掃描 Redis 或解讀自然語言。只能在此 agent 自己的 workspace safety check 下讀取 project code；
+絕不可把 source path 或 content 交給 dbcli。若 `gaps` 回報缺少 evidence，不可猜測 metadata：檢查允許的 code 或要求補上證據。若輸出含有
 `semantic`，將該已檢閱的區塊視為受治理詞彙；需查找特定術語時，用
 `dbcli semantic search <terms> --format json`。若有 `contracts` 區塊，只能使用其中 approved 術語
 及描述性的 evidence policy；它絕不授權 assertion 或 query。若沒有 semantic 區塊，或搜尋沒有結果，就退回
@@ -107,6 +109,61 @@ blacklist、schema、permission、dry-run、production 選取或寫入確認閘
 除非人類明確要求，絕不可建立、更新或 migrate 此檔案；語意詞彙不能取代 schema 確認或正常的
 query/write 安全閘門。
 
+## 能力探索 (Capability discovery)
+
+在組合工作流之前，先問 dbcli 在這裡能做什麼，不要用猜的。Catalog 是靜態的，check 只讀本機
+設定——**兩者都不會建立資料庫連線。**
+
+```bash
+dbcli capabilities --format json                                  # full catalog
+dbcli capabilities --format markdown                              # table for docs
+dbcli capabilities check --require schema.read,query.read         # gate your workflow
+dbcli capabilities check --require data.delete --format json      # machine-readable
+```
+
+若要取得可直接複製的 Bun/TypeScript consumer（strict parsing、schema pin、exit handling、
+Operation Envelope、Task Pack `safety.requires` 與 correlation/evidence 指引），請從
+`assets/integration-kit/README.md` 開始。
+
+一個 capability 是 dbcli 的單一原子能力（`schema.read`、`data.delete`），不是職務也不是方法。
+`dba.tune-production` 與 `crud.scaffold` 屬於組合 dbcli 的 Role Skill 或 Method Skill——這份
+Tool Skill 只負責安全地操作 dbcli。
+
+- `schemaVersion` 是 capability contract 的版本，**不是** npm 套件版本。
+- 狀態有 `available`、`unavailable`（原因為 `engine`、`agent-mode`、`permission`、
+  `context-unavailable` 或 `context-unresolvable`）與 `unknown`。拼錯的 id 一律 fail
+  closed，絕不猜測。
+- 在 `DBCLI_AGENT_MODE=1` 之下，會變更設定的能力一律 `unavailable`、原因 `agent-mode`，
+  不管權限等級寫什麼。
+- Exit code：`0` 全部可用、`1` 有任一不可用或未知、`2` 輸入無效。
+- **`available` 不等於已核准。** Blacklist、write gate、確認與 audit 在執行時仍然會跑，
+  設定檔裡的 `admin` 是權限等級，不是 DBA 的簽核。
+- v1 涵蓋 engine capability matrix 管轄的指令；不在其中的一律回 `unknown`，而不是給出未經
+  稽核的引擎宣稱。
+
+**Agent output v1（PLAT-005）：** 使用 `dbcli --agent-output capabilities` 或
+`dbcli --agent-output capabilities check --require <ids>`；root flag 必須放在 subcommand 前，目前沒有
+其他支援的 operation。它會在 stdout 輸出一份 compact UTF-8 JSON envelope 與換行，stderr 保持空白。
+十個 key 是 `schemaVersion`、`ok`、`operation`、`status`、`context`、`data`、`warnings`、`evidence`、
+`recovery` 與 `error`；`schemaVersion` 是 `1`，`operation` 是 `capabilities.list` 或
+`capabilities.check`，`status` 是 `succeeded` 或 `failed`。不可和明確的 `--format` 或 `--for-agent`
+合用：衝突、無效位置/輸入與不支援 operation 以 exit `2` 結束；成功 exit `0`；需求未滿足與 internal failure
+exit `1`。envelope 連同換行上限為 64 KiB，consumer 要依 field name 而非順序讀取。
+可選的 root `--correlation-id <id>` 也必須放在 subcommand 前；它只接受 1–160 個 ASCII 英文字母、數字、
+`.`、`_`、`:` 或 `-`，不可放入 secret 或 free-form input。支援的非 static output 會寫入
+`context.correlationId` 與既有 audit 的 `metadata.correlation_id`，command summary 會遮罩它；static
+capabilities 保持 `context: null`，也不建立 evidence receipt。
+
+code/message vocabulary 永遠是 locale-independent English：error 為
+`INVALID_AGENT_OUTPUT_OPTIONS`（無效/位置錯誤/衝突 option）、
+`INVALID_CORRELATION_ID`（無效或缺少 `--correlation-id` 值）、
+`UNSUPPORTED_AGENT_OUTPUT_OPERATION`（PLAT-004 範圍外）、`INVALID_CAPABILITY_REQUIREMENTS`
+（無效 `--require`）、`CAPABILITY_REQUIREMENTS_UNMET`（已完成的 negative result）、
+`AGENT_OUTPUT_LIMIT_EXCEEDED`（64 KiB 上限）與 `AGENT_OUTPUT_INTERNAL_ERROR`（未預期但安全的
+failure）。warning 為 `DUPLICATE_CAPABILITY_REQUIREMENT`、
+`CAPABILITY_CONTEXT_UNAVAILABLE`、`CAPABILITY_CONTEXT_UNRESOLVABLE` 與
+`AGENT_MODE_RESTRICTION_ACTIVE`。
+
 ## Agent Task Packs
 
 當使用者要求一個資料庫工作流（例如「診斷這個慢查詢」、「審計權限」、「審視長時間執行的操作」），**優先選用已發布的任務模板，而非憑記憶自行組合步驟。**
@@ -327,6 +384,7 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 |---------|-----------------|---------|
 | `init` | n/a | 建立 `.dbcli`（v1 單一或 v2 多連線，透過 `--conn-name` / `--env-file`）。**通常由真人執行** — 不要為了清掉 `{"$env"}` 參照而重跑；該格式是刻意設計。 |
 | `use` | n/a | 顯示 / 切換預設命名連線（僅 v2）。 |
+| `capabilities` | n/a | 靜態 capability catalog 與 `check --require <ids>` 需求閘門。不連線資料庫。`--format text\|json\|markdown`（`check` 為 `text\|json`）。Exit `0`/`1`/`2`。 |
 | `list` | query-only+ | 資料表（SQL）、collections（MongoDB）、keys（Redis）或 indices（Elasticsearch）。 |
 | `schema` | query-only+ | SQL：單表或全掃描存入 `.dbcli/schemas/`。MongoDB：sampled。ES：flattened mapping。Redis：僅單一 key（type / TTL / size）。支援 `--recovery`。 |
 | `query` | query-only+ | SQL、Mongo JSON（`--collection`）、Redis 指令、ES DSL / Lucene（`--collection`）。`--format table\|json\|csv\|html`、`--ui` 開啟瀏覽器互動式 dashboard。`--fields`（欄位投影）、`--truncate`（欄位值寬度）、`-f/--query-file`（從檔案或 stdin 讀查詢）、`--use a,b`（唯讀扇出）。支援 `--recovery`。`--slow-ms <n>` 設定被動慢查詢提示的門檻（預設 1000，`0` 關閉）：達到門檻時 table 輸出多一行 `Performance hint` footer、JSON 多出 `metadata.performanceAdvisory`；它不執行任何額外診斷，且在 `--recovery` 下被抑制。與 `proxy` 的同名旗標不同。見 **查詢工作流程旗標**。 |
@@ -500,7 +558,7 @@ dbcli export "SELECT * FROM orders" --format html --output orders.html
 ## 備註
 
 - Query-only 模式自動補 `LIMIT 1000`；查 `information_schema` 或會被 `LIMIT` 破壞的語句請加 `--no-limit`。
-- 被 blacklist 的 table / column 會從查詢輸出中遮蔽。
+- 被 blacklist 的 table / column 會從查詢輸出中遮蔽。`blacklist.tables` 與 `blacklist.columns` 的每個條目在所有引擎上都是 glob（`*`、`?`、`[a-z]`），規則與名稱比對時整條點分路徑都不分大小寫——寫成 `password` 的規則同時涵蓋 `Password`，`profile.ssn` 也涵蓋 `profile.SSN`；真的叫 `report*` 的表要寫成 `report\*` 才能回到字面比對。`--fields` 不受影響，維持精確比對。讀不出意思的規則會在設定載入時就被拒絕，而不是靜默地什麼都不保護：以自己的表限定的欄位項（`{"users": ["users.password"]}`）會載入失敗，無法解析的規則則會讓每一個 `dbcli es` 請求失敗，直到改掉為止。
 - `schema` 回報 `estimatedRowCount` 與 `sizeCategory`（small / medium / large / huge）。大 / 巨大表要加 `WHERE` 或 `LIMIT` — 分界值見 [reference.md](reference.md#schema)。
 - 對 `mongodb+srv://` 連線，`doctor` 會回報 SRV 是用原生解析或走 DoH fallback — 在執行環境限制 DNS 時很有用。
 - **全域旗標：** `--version`、`--config <path>`、`--global`、`--use <name>`、`--timeout <ms>`、`--statement-timeout <ms>`、`-v` / `--verbose` / `-vv`、`-q` / `--quiet`、`--no-color`（也尊重 `NO_COLOR`）。除非指令明確宣告 command-level 選項，否則 root-level 旗標必須放在指令之前。

package/assets/integration-kit/README.md

@@ -0,0 +1,43 @@
+# Skill Author Integration Kit
+
+Copy `skill-author-consumer.ts` into a Bun/TypeScript Skill that depends on
+`@carllee1983/dbcli`. It uses only the public `@carllee1983/dbcli/core` contract.
+
+```ts
+import { spawn } from 'bun'
+import { discover, preflight } from './skill-author-consumer'
+
+const run = async (args: readonly string[]) => {
+  const child = spawn(['dbcli', ...args], { stdout: 'pipe', stderr: 'pipe' })
+  return {
+    code: await child.exited,
+    stdout: await new Response(child.stdout).text(),
+    stderr: await new Response(child.stderr).text(),
+  }
+}
+
+const catalog = await discover(run) // strict catalog parsing and schema pinning
+const gate = await preflight(run, ['schema.read', 'query.read'], 'STORY-123')
+if (!gate.ok) throw new Error(gate.error?.code ?? 'requirements are unavailable')
+console.log(catalog.capabilities.map(({ id }) => id))
+```
+
+`discover` accepts only exit `0`. `preflight` accepts `0`, `1`, or `2`: each is
+a valid Operation Envelope response. Treat exit `1` as a completed negative
+result and inspect `ok`, `data`, and `error`; exit `2` means invalid invocation.
+Both helpers reject non-JSON output, stderr, unknown fields, and any schema
+version other than the exported constants.
+
+Use [`task-pack.md`](./task-pack.md) as the smallest `safety.requires` example.
+It remains plan-only; do not put a CRUD, CQRS, or DBA workflow into dbcli.
+
+[`external-consumers.ts`](./external-consumers.ts) supplies the requirements for
+the three contract-test consumers: CRUD, CQRS, and DBA. They use this kit's
+public contract only; dbcli neither implements nor approves their workflows.
+
+The optional correlation ID is returned in `context.correlationId` for
+non-static agent output and is recorded as audit metadata. It is not evidence:
+for a supported command, request an evidence receipt with
+`--evidence-receipt <workspace-relative-path>` and retain the returned receipt
+with that correlation ID. Never put secrets, SQL, personal data, or free-form
+input in a correlation ID.

package/assets/integration-kit/external-consumers.ts

@@ -0,0 +1,9 @@
+/**
+ * Example requirements owned by external Skills, not by dbcli.
+ * Each consumer uses discover/preflight from skill-author-consumer.ts.
+ */
+export const EXTERNAL_CONSUMERS = {
+  crud: ['schema.read', 'query.read', 'data.insert', 'data.update', 'data.delete'],
+  cqrs: ['schema.read', 'query.read'],
+  dba: ['connection.diagnose', 'schema.scan', 'audit.show'],
+} as const

package/assets/integration-kit/skill-author-consumer.ts

@@ -0,0 +1,77 @@
+import {
+  CAPABILITY_CONTRACT_SCHEMA_VERSION,
+  OPERATION_ENVELOPE_SCHEMA_VERSION,
+  parseCapabilityCatalog,
+  parseOperationEnvelope,
+  type CapabilityCatalog,
+  type OperationEnvelope,
+} from '@carllee1983/dbcli/core'
+
+export interface CommandResult {
+  readonly code: number
+  readonly stdout: string
+  readonly stderr: string
+}
+
+export type RunDbcli = (args: readonly string[]) => Promise<CommandResult>
+
+export class DbcliIntegrationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'DbcliIntegrationError'
+  }
+}
+
+function json(stdout: string, label: string): unknown {
+  try {
+    return JSON.parse(stdout)
+  } catch {
+    throw new DbcliIntegrationError(`${label} did not emit JSON`)
+  }
+}
+
+/** Discover the static catalog and reject an unpinned or non-strict response. */
+export async function discover(run: RunDbcli): Promise<CapabilityCatalog> {
+  const result = await run(['capabilities', '--format', 'json'])
+  if (result.code !== 0 || result.stderr !== '') {
+    throw new DbcliIntegrationError(`capability discovery failed (exit ${result.code})`)
+  }
+  const catalog = parseCapabilityCatalog(json(result.stdout, 'capability discovery'))
+  if (catalog.schemaVersion !== CAPABILITY_CONTRACT_SCHEMA_VERSION) {
+    throw new DbcliIntegrationError(`unsupported capability schema ${catalog.schemaVersion}`)
+  }
+  return catalog
+}
+
+/**
+ * Run requirement preflight through the agent envelope. Exit 1 is a valid
+ * completed negative result; callers inspect `envelope.ok` and `error`.
+ */
+export async function preflight(
+  run: RunDbcli,
+  required: readonly string[],
+  correlationId: string
+): Promise<OperationEnvelope> {
+  const result = await run([
+    '--agent-output',
+    '--correlation-id',
+    correlationId,
+    'capabilities',
+    'check',
+    '--require',
+    required.join(','),
+  ])
+  if (![0, 1, 2].includes(result.code) || result.stderr !== '') {
+    throw new DbcliIntegrationError(
+      `capability preflight failed outside its contract (exit ${result.code})`
+    )
+  }
+  const parsed = parseOperationEnvelope(json(result.stdout, 'capability preflight'))
+  if (!parsed.ok) throw new DbcliIntegrationError(`invalid Operation Envelope: ${parsed.reason}`)
+  if (parsed.value.schemaVersion !== OPERATION_ENVELOPE_SCHEMA_VERSION) {
+    throw new DbcliIntegrationError(
+      `unsupported Operation Envelope schema ${parsed.value.schemaVersion}`
+    )
+  }
+  return parsed.value
+}

package/assets/integration-kit/task-pack.md

@@ -0,0 +1,18 @@
+---
+name: example-read-only-review
+description: Minimal Task Pack requirement declaration for an external Skill.
+engines: [postgresql, mysql]
+safety:
+  mode: plan-only
+  requires: [schema.read, query.read]
+steps:
+  - type: command
+    command: dbcli blacklist list --format json
+    risk: readonly
+  - type: command
+    command: dbcli schema {{table}} --format json
+    risk: readonly
+---
+
+This pack only plans commands. `safety.requires` contains capability IDs, not
+command names; dbcli validates them before emitting a plan.

package/assets/reference.md

@@ -43,6 +43,7 @@ never the right move.
 [snapshot](#snapshot) ·
 [assert](#assert) ·
 [proxy](#proxy) ·
+[capabilities](#capabilities) ·
 [status](#status) ·
 [inspect](#inspect) ·
 [report](#report) ·
@@ -85,6 +86,8 @@ command-level option is only valid after the command that declares it.
 | `--use <connection>` | Select a named connection for this invocation; place it before the command path unless that command explicitly lists a command-level `--use`. |
 | `--timeout <ms>` | Connection timeout in milliseconds (integer, 100–600000), overriding the connection config's `timeout` field for this invocation. Applies to every engine adapter. Without either the flag or the config field, adapters fall back to their built-in 5000ms default. |
 | `--statement-timeout <ms>` | How long a single statement may run, in milliseconds (integer, 0–3600000; `0` removes the limit), overriding the connection config's `statementTimeout` field. Independent of the connection timeout — raising it does not slow down detection of an unreachable host. Falls back to `--timeout` when unset, and to the server's own setting when neither is given. |
+| `--agent-output` | Request the PLAT-005 v1 Operation Envelope. It must precede the subcommand and currently supports `capabilities` and `capabilities check`; it conflicts with explicit `--format` and command-local `--for-agent`. |
+| `--correlation-id <id>` | Associate one invocation with a Story, incident, change request, migration, or backfill. Place it before the subcommand. IDs are 1–160 ASCII letters, numbers, dots, underscores, colons, or hyphens; never use sensitive or free-form data. |
 
 `--timeout` is applied only when the adapter is constructed for this invocation — it is
 never written back to `config.json`. Set the connection's `timeout` field instead for a
@@ -1102,6 +1105,26 @@ dbcli blacklist column remove users.password
 
 **Subcommands:** `list`, `table add <name>`, `table remove <name>`, `column add <table.column>`, `column remove <table.column>`
 
+**Matching semantics (7.0.0):** every entry in `blacklist.tables` and `blacklist.columns` is a
+glob (`*`, `?`, `[abc]`, `[a-z]`) on **every** engine, not only Redis and Elasticsearch — `tables:
+["secrets*"]` blocks the SQL table `secrets_2026` and the MongoDB collection `secrets_2026` alike.
+A table literally named `report*` has to be written `report\*` to match literally again. Rules and
+returned names are compared over the **whole dotted path, case-insensitively**, so `password` also
+covers `Password` and `profile.ssn` covers `profile.SSN`; folding happens at the comparison and the
+config keeps rules as written. The cost is deliberate over-rejection: where PostgreSQL holds both
+`"Password"` and `"password"`, a rule naming either redacts both. `--fields` is unaffected and still
+matches exactly — it names keys in the document in front of the operator, not a protection rule.
+
+Column-level entries are a **display filter, not an access control**: masking matches returned
+names, so `SELECT password_hash AS x` still returns the value. Table-level entries are the
+enforceable half.
+
+A rule that cannot mean anything fails loudly instead of silently protecting nothing: a column entry
+qualified with its own table (`{"users": ["users.password"]}`) fails to load, and a rule the
+Elasticsearch shell cannot parse (`pass[word`, `a.**`) makes every `dbcli es` request fail until the
+config is fixed. Entries are trimmed and unquoted, and a rule filed under `public.users` applies to
+`SELECT * FROM users` and the reverse.
+
 **`list` options:** `--config <path>`, `--format <text|json>` (default: `text`). JSON writes one
 document to stdout: `{ "tables": string[], "columns": Record<string, string[]>, "warnings":
 [{ "collection", "raw", "reason" }] }`. Invalid MongoDB blacklist patterns appear in `warnings`;
@@ -1278,6 +1301,10 @@ The normalized JSON escape hatch is Zod-validated and uses an array of tables
 with explicit exact `identity` objects; optional parsed identifiers must include
 their `quoted` flags, and every normalized JSON `unparsed.reason` must start with
 `blocked:`.
+A Drizzle snapshot or normalized JSON artifact that is not valid JSON, and a
+normalized JSON artifact that violates that contract, fail closed: the error
+names the offending file and lists the fields at fault, bounded with a count of
+the remainder, rather than degrading to `unparsed`.
 
 ```json
 {
@@ -1649,6 +1676,150 @@ Every actionable block carries machine-readable next steps so an agent can move
 **Engines:** MySQL / MariaDB / PostgreSQL
 **Permission:** n/a (acts as a TCP relay; does not use dbcli's SQL permission model)
 
+### capabilities
+
+Discovery. Lists the static dbcli capability catalog — what this tool can do,
+described in a versioned shape an external Skill can parse before it starts
+working. It never opens a database connection and never writes anything.
+
+A **capability** names one atomic dbcli ability (`schema.read`, `data.delete`).
+It is not a job and not a method: `dba.tune-production` or `crud.scaffold`
+belong to the Role or Method Skill that composes dbcli, never to dbcli itself.
+
+```bash
+dbcli capabilities                       # human-readable (default)
+dbcli capabilities --format json         # for agents and Skills
+dbcli capabilities --format markdown     # table, for docs
+```
+
+Each entry carries `id`, `description`, `command`, `risk`, `sideEffect`,
+`engines`, `limitedEngines`, `engineIndependent`, `minimumPermission`,
+`requiresConnection`, `mutatesConfiguration`, `supportsJson` and
+`supportsEvidence`. `limitedEngines` is the subset of `engines` the support
+matrix marks *limited* rather than fully supported. Output is sorted by `id`, so two runs of
+the same build are byte-identical.
+
+`schemaVersion` is the **capability contract** version, not the npm package
+version. Pin `schemaVersion`, never `7.x`.
+
+**Scope:** the catalog covers every public command, including `explain`, `plan`,
+`impact assess`, `assert`, `snapshot`, `verify`, `verification`, `evidence`,
+`contract`, `semantic`, `design`, `proxy`, `recovery`, `backfill artifact`,
+`password`, and `capabilities` itself. An id it does not know is still
+`unknown`, which fails closed.
+
+Every engine claim was read out of the implementation. Where the code refuses a
+non-SQL connection outright — `explain`, `plan`, `assert`, `snapshot`, `verify`,
+`proxy` — the entry is `unsupported` for MongoDB, Redis and Elasticsearch and
+the note names the gate. Where only one *mode* needs SQL — `--against-cache` for
+`impact assess`, `design diff` and `design propose`, and `draft validate` for
+`semantic` — the entry is `limited` there, because the rest of the command runs
+fine. Where a command never opens a connection at all, it is
+engine-independent. Nothing is marked supported on an engine the code does not
+settle.
+
+**Permission:** query-only+ (no connection is made)
+
+#### capabilities check
+
+Asks whether the capabilities you need are available *here* — against this
+machine's local configuration only. It reads engine and permission from the
+config; it does not connect to the database to find out.
+
+```bash
+dbcli capabilities check --require schema.read,query.read
+dbcli capabilities check --require schema.read,data.delete --format json
+dbcli --use staging capabilities check --require schema.read --format json
+dbcli --agent-output capabilities check --require schema.read
+```
+
+For a copyable Bun/TypeScript consumer that strictly parses this contract, pins schema
+versions, handles exit codes and Operation Envelopes, and includes Task Pack and
+correlation/evidence examples, see `assets/integration-kit/README.md`.
+
+#### Agent output v1 (PLAT-005)
+
+`dbcli --agent-output capabilities` and `dbcli --agent-output capabilities check --require <ids>`
+are the supported operations. Either emits one compact UTF-8 JSON document followed by one newline
+on stdout, with stderr empty. The envelope always has, in stable order, `schemaVersion`, `ok`,
+`operation`, `status`, `context`, `data`, `warnings`, `evidence`, `recovery`, and `error`; consumers
+must use the names, not the order. `schemaVersion` is `1`, `operation` is `capabilities.list` or
+`capabilities.check`, and `status` is `succeeded` or `failed`. The full document, including newline,
+is capped at 64 KiB.
+
+The flag must be before the subcommand and conflicts with explicitly supplied `--format` or
+`--for-agent`. Invalid placement/input and unsupported operations exit `2`; success exits `0`;
+unmet requirements and internal failures exit `1`. This output is ephemeral: it is not evidence and
+adds no timestamp. `--correlation-id <id>` is an optional root option. For supported non-static
+agent output, it appears as `context.correlationId` and in the existing audit entry as
+`metadata.correlation_id`; command summaries redact it. Static `capabilities` output remains
+`context: null`, and the option creates or changes no evidence receipt.
+
+Code/message vocabulary is locale-independent English. Stable error codes mean:
+
+| Code | Meaning |
+|---|---|
+| `INVALID_AGENT_OUTPUT_OPTIONS` | The agent-output option is invalid, misplaced, or conflicts with explicit output options. |
+| `UNSUPPORTED_AGENT_OUTPUT_OPERATION` | The requested operation is outside PLAT-005 support. |
+| `INVALID_CAPABILITY_REQUIREMENTS` | `--require` is missing, empty, or malformed. |
+| `CAPABILITY_REQUIREMENTS_UNMET` | A completed check found one or more unavailable or unknown requirements. |
+| `AGENT_OUTPUT_LIMIT_EXCEEDED` | The otherwise valid serialized envelope exceeded 64 KiB. |
+| `AGENT_OUTPUT_INTERNAL_ERROR` | An unexpected failure was replaced with the safe agent-output failure. |
+| `INVALID_CORRELATION_ID` | The root correlation ID is absent or does not match the allowed identifier grammar. |
+
+Stable warning codes mean:
+
+| Code | Meaning |
+|---|---|
+| `DUPLICATE_CAPABILITY_REQUIREMENT` | A repeated required id was de-duplicated in first-seen order. |
+| `CAPABILITY_CONTEXT_UNAVAILABLE` | No local configuration was available to evaluate. |
+| `CAPABILITY_CONTEXT_UNRESOLVABLE` | Configuration exists but cannot yield an engine and permission. |
+| `AGENT_MODE_RESTRICTION_ACTIVE` | `DBCLI_AGENT_MODE=1` refuses configuration, permission, and credential changes. |
+
+| Flag | Purpose |
+|---|---|
+| `--require <ids>` | Comma-separated capability ids. Required; an empty list is refused rather than reported as ok. |
+| `--format <type>` | `text` (default) or `json`. |
+
+Each result is `available`, `unavailable` or `unknown`:
+
+| Status | Reason | Means |
+|---|---|---|
+| `available` | `null` | The configured engine and permission would not refuse it. |
+| `unavailable` | `engine` | The configured engine does not support it. |
+| `unavailable` | `permission` | The configured permission level is below its minimum. |
+| `unavailable` | `agent-mode` | `DBCLI_AGENT_MODE=1` is set and the capability changes configuration, permission or credentials — refused unconditionally. |
+| `unavailable` | `context-unavailable` | No local config here, so there is nothing to evaluate against. |
+| `unavailable` | `context-unresolvable` | A config exists but could not be resolved into an engine and a permission — an `{"$env": "..."}` reference pointing at an unset variable, for instance. Distinct from "no config", because saying there is none would be false. |
+| `unknown` | `unknown-capability` | No such capability id. Never guessed at — a typo is refused, not resolved to a neighbour. |
+
+A duplicate id in `--require` is de-duplicated in first-seen order and reported
+in `warnings`; `required` and `results` each hold it once.
+
+`required` and `results` hold the ids you asked for in first-seen input order,
+so `results[i]` answers `required[i]` and you never have to re-index by id to
+read your own answer. Reordering the arguments therefore reorders the output and
+the two byte streams differ; what reordering never changes is a capability's
+status, its reason, or the overall `ok`. Identical input is byte-identical
+output.
+
+**Exit codes:** `0` every requirement available · `1` any unavailable or
+unknown · `2` invalid input or an unreadable format.
+
+Blockers are reported least-fixable first — engine, then agent mode, then
+permission — so `reason` names the one actually in the way.
+
+**`available` is not approval.** It says the gate would not refuse on engine,
+agent-mode and permission grounds. Blacklist, write gate, confirmation and audit all still run
+at execution time, and no human has agreed to anything. `admin` in a config file
+is a permission level, not a DBA sign-off.
+
+`schema.read` is available under `DBCLI_AGENT_MODE=1`, and `dbcli schema` runs
+there: storing the schema cache is not a configuration change. Agent mode still
+refuses every change to connection identity, permission and credentials.
+
+**Permission:** query-only+ (no connection is made)
+
 ### status
 
 Show current configuration status (safe for AI agents, no credentials exposed).
@@ -2928,14 +3099,18 @@ The strict v1 artifact contains `version` and `contracts`. Each contract has a u
 canonical `name`, `status` (`draft`, `approved`, or `deprecated`), bounded plain-text
 `description` and `owner`, one or more canonical semantic `subjects`, optional aliases,
 and an `evidencePolicy` of `none`, `receipt-required`, or `verification-required`.
-Subjects must remain in the existing visible semantic registry; protected identifiers,
-unknown keys, duplicate names or subjects, SQL-like text, credentials, and stale
-references fail closed without exposing protected names.
+Each subject must use one of the canonical `model:` / `field:` / `relationship:` /
+`metric:` forms and must remain in the existing visible semantic registry; protected
+identifiers, unknown keys, duplicate names or subjects, SQL-like text, credentials, and
+stale references fail closed without exposing protected names. Diagnostics name the
+offending property or subject position, never a rejected key, value, or local path taken
+from the artifact or the local configuration.
 
 `contract validate` requires an explicit valid artifact. `contract context` and
 `contract search` return only valid approved contracts; draft and deprecated contracts
 remain local review artifacts. `contract drift` reports `valid`, `stale`, `invalid`, or
-`unavailable` evidence offline and exits non-zero except for `valid`. A missing default
+`unavailable` evidence offline and exits non-zero except for `valid`; a subject whose form
+is unsupported is `invalid`, while a well-formed subject that no longer exists is `stale`. A missing default
 file is allowed by `skill context` and leaves ordinary semantic context unchanged; a
 present invalid file fails closed. No contract command writes a file, opens a database
 connection, widens a `QueryDraft`, or changes permission/blacklist behavior.
@@ -2983,12 +3158,23 @@ Emit an AI-friendly snapshot of the connected database's schema and saved-query
 dbcli skill context                      # XML (default)
 dbcli skill context --format json
 dbcli skill context --format markdown
+dbcli skill context --context-version 2 --format json
 ```
 
 **Options:**
 - `--format <xml|json|markdown>` — output format (default: `xml`)
+- `--context-version <version>` — explicit agent contract; version `2` supports
+  PostgreSQL, MySQL, MariaDB, Elasticsearch, and Redis. Omit it for byte-compatible v1.
 
-**Permission:** query-only+ — read-only; blacklisted objects are never emitted.
+Version 2 is offline and bounded: it emits only visible cached SQL tables/fields,
+flattened Elasticsearch fields, or declared Redis key families, plus safe capability,
+snippet, semantic, contract, and data-access metadata. It never connects, scans Redis,
+reads documents or project source, or emits values, credentials, query bodies/defaults,
+source paths, counts, or raw mappings. Missing evidence is reported in `gaps`; invalid
+evidence fails with a stable `INVALID_*` code. MongoDB rejects explicit v2.
+
+**Permission:** query-only+ — read-only; blacklisted objects are never emitted outside
+the blacklist policy.
 
 ### skill tasks (Agent Task Packs)
 
@@ -3547,6 +3733,12 @@ dbcli query "KEYS *"                      # → returns only non-blacklisted key
 
 Rejections are written to the audit log with `success: false` and `metadata.rejection_reason: 'blacklist'` + `matched_pattern`.
 
+Enforcement covers `q` and `report` as well (7.0.0). Before that, saved queries and the built-in
+`@diag/redis-key-stats` diagnostic ran on an adapter that carried the connection but none of its
+rules, so `dbcli q @<name>` could read a protected key in plaintext and a report could persist
+protected key names. Both now resolve their key targets before execution, apply the connection's
+blacklist and `redis.mask` rules, and drop protected key names from `SCAN` evidence.
+
 ### Value / hash-field masking (v1.22)
 
 Where the key-glob blacklist *rejects*, masking instead *redacts*: a matched read still

package/assets/tasks/README.md

@@ -21,6 +21,8 @@ Each task is a `.md` file with a YAML frontmatter block:
 - `description`, `tags`, `engines`
 - `params` (map of name → `{ type, required?, default?, description?, enum? }`)
 - `safety.mode` — only `plan-only` is supported in this version
+- `safety.requires` — optional capability IDs; planning checks them against the
+  local engine, permission, and agent-mode context before emitting a plan
 - `steps[]` — each step is `{ type: command, command, reason?, risk? }`
 
 Use block-style YAML (no inline `{ ... }` maps) — the built-in YAML parser does
@@ -28,3 +30,7 @@ not support inline maps.
 
 The markdown body below the frontmatter is `Agent Notes` and is shown in
 `dbcli skill tasks show <name>`.
+
+Use `postgresql` for PostgreSQL. The legacy `postgres` engine spelling is read
+as `postgresql`; legacy requirement names `blacklist-list` and `schema-check`
+are rejected with their replacements, `blacklist.manage` and `schema.read`.

package/assets/tasks/analyze-table-perf.md

@@ -2,7 +2,7 @@
 name: analyze-table-perf
 description: Inspect a single table's structure, indexes and read-only performance signals.
 tags: [diagnostics, performance, readonly]
-engines: [postgres, mysql]
+engines: [postgresql, mysql]
 params:
   table:
     type: string
@@ -11,8 +11,8 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist-list
-    - schema-check
+    - blacklist.manage
+    - schema.read
 steps:
   - type: command
     command: blacklist list