@carllee1983/dbcli 7.0.1 → 8.0.0

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` 的同名旗標不同。見 **查詢工作流程旗標**。 |

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
@@ -1298,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
 {
@@ -1669,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).
@@ -2948,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.
@@ -3003,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`)
-
-**Permission:** query-only+ — read-only; blacklisted objects are never emitted.
+- `--context-version <version>` — explicit agent contract; version `2` supports
+  PostgreSQL, MySQL, MariaDB, Elasticsearch, and Redis. Omit it for byte-compatible v1.
+
+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)
 

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

package/assets/tasks/audit-permissions.md

@@ -2,7 +2,7 @@
 name: audit-permissions
 description: Audit the active permission tier and blacklist coverage before granting an agent write access.
 tags: [security, permissions, readonly]
-engines: [postgres, mysql]
+engines: [postgresql, mysql]
 params:
   table:
     type: string
@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist-list
+    - blacklist.manage
 steps:
   - type: command
     command: status

package/assets/tasks/connection-health.md

@@ -2,7 +2,7 @@
 name: connection-health
 description: Quick read-only health check of the active connection (reachability, config, capacity signals).
 tags: [diagnostics, health, readonly]
-engines: [postgres, mysql]
+engines: [postgresql, mysql]
 params:
   section:
     type: string
@@ -13,7 +13,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist-list
+    - blacklist.manage
 steps:
   - type: command
     command: status

package/assets/tasks/design-review.md

@@ -2,12 +2,12 @@
 name: design-review
 description: Validate and render a version-controlled SQL database design before comparing it with the local schema cache and preparing review-only proposals.
 tags: [design, schema, readonly]
-engines: [postgres, mysql]
+engines: [postgresql, mysql]
 safety:
   mode: plan-only
   requires:
-    - blacklist-list
-    - schema-check
+    - blacklist.manage
+    - schema.read
 steps:
   - type: command
     command: blacklist list

package/assets/tasks/diagnose-slow-query.md

@@ -2,7 +2,7 @@
 name: diagnose-slow-query
 description: Diagnose slow query causes using safe read-only dbcli steps.
 tags: [diagnostics, performance, readonly]
-engines: [postgres, mysql]
+engines: [postgresql, mysql]
 params:
   query:
     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

package/assets/tasks/migration-review.md

@@ -2,7 +2,7 @@
 name: migration-review
 description: Capture pre-change schema evidence and preview a migration's DDL before it is applied.
 tags: [migration, schema, readonly]
-engines: [postgres, mysql]
+engines: [postgresql, mysql]
 params:
   table:
     type: string
@@ -15,8 +15,8 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist-list
-    - schema-check
+    - blacklist.manage
+    - schema.read
 steps:
   - type: command
     command: blacklist list

package/assets/tasks/mongo-safe-backfill.md

@@ -19,8 +19,8 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist-list
-    - schema-check
+    - blacklist.manage
+    - schema.read
 steps:
   - type: command
     command: blacklist list

package/assets/tasks/mongo-schema-drift-review.md

@@ -15,8 +15,8 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist-list
-    - schema-check
+    - blacklist.manage
+    - schema.read
 steps:
   - type: command
     command: blacklist list

package/assets/tasks/orm-drift-review.md

@@ -2,7 +2,7 @@
 name: orm-drift-review
 description: Compare an ORM schema definition (Prisma / DDL / normalized JSON) against the live schema cache and review drift before any corrective migration.
 tags: [diagnostics, schema, orm, readonly]
-engines: [postgres, mysql]
+engines: [postgresql, mysql]
 params:
   orm_path:
     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

package/assets/tasks/pr-database-review.md

@@ -2,7 +2,7 @@
 name: pr-database-review
 description: Review a PR's changed persistence paths, queries and migrations for database risk before merge.
 tags: [review, safety, readonly]
-engines: [postgres, mysql]
+engines: [postgresql, mysql]
 params:
   query:
     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