@carllee1983/dbcli 7.0.1 → 9.0.0

package/.github/skills/dbcli/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.
@@ -2982,7 +3137,7 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 **Options:**
 - `--install <platform>` — `claude` | `gemini` | `antigravity` | `copilot` | `cursor` | `codex` | `windsurf`. 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`.
-- `--lang <en|zh-TW>` — source language for the emitted SKILL content (default `en`). It selects `assets/SKILL.md` vs `assets/SKILL.zh-TW.md`; the install/output filename stays `SKILL.md` regardless.
+- Skill content is always the canonical English `assets/SKILL.md`; the install/output filename is `SKILL.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.
@@ -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/CHANGELOG.md

@@ -5,6 +5,305 @@ All notable changes to dbcli are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [9.0.0] - 2026-09-06
+
+### Changed
+
+- **AI Skill now has one canonical English source.** `dbcli skill`, `--output`, and every
+  supported platform install emit `assets/SKILL.md`; the user-facing documentation remains
+  bilingual.
+
+### Removed
+
+- **BREAKING:** Removed `dbcli skill --lang <en|zh-TW>`, `assets/SKILL.zh-TW.md`, and the
+  bilingual Skill parity gate. Existing Traditional-Chinese installs are reported as outdated
+  and become the canonical English Skill when reinstalled.
+
+## [8.0.0] - 2026-09-05
+
+ForgeFlow Story DBCLI-001 到 DBCLI-012 全數在 `v7.0.1`（`224ee59d`）之後交付；該 tag
+早於 Story 的合併點 `04a88a44`，因此以下每一條都在 `7.0.1` 之外。DBCLI-013 補上
+採用漂移的檢查與這份紀錄本身。
+
+版本為 **8.0.0**。理由不是變更量，而是三處會拒絕先前被接受的輸入、以及一處會
+改變 JSON 判決值——SemVer 對這四項的答案都是 MAJOR，詳見下方 Breaking。
+
+### Added
+
+- **`dbcli capabilities` 與 `dbcli capabilities check`：外部 Skill 現在問得到「這個
+  工具能做什麼」。** Catalog 是靜態、有自己的 `schemaVersion`、依 id 排序，同一個
+  build 兩次輸出 byte-identical；`check --require <ids>` 只讀本機設定的 engine 與
+  permission。兩者都不建立資料庫連線，也不動檔案系統，這一點由 import graph 的
+  contract test 結構性地保證，不是靠註解宣稱。純型別與純函式從
+  `@carllee1983/dbcli/core` 匯出。
+
+  Capability 描述的是工具的原子能力（`schema.read`、`data.delete`），不是職務或
+  方法——後者屬於組合 dbcli 的 Role Skill 與 Method Skill。每一項 engine 與 risk
+  宣稱都由既有的 `ENGINE_CAPABILITIES` 推導，不另立第二張表；contract test 雙向
+  檢查 catalog 與實際 Commander tree 不會漂移。
+
+  Fail closed 是預設：不認得的 id 回 `unknown` 而不會被解析成長得像的那一個，缺少
+  設定回 `unavailable` + `context-unavailable` 而不是拿 `DEFAULT_CONFIG` 的
+  localhost PostgreSQL 充數。Exit code `0` / `1` / `2`。
+
+  `DBCLI_AGENT_MODE=1` 是 context 的一部分，不是免責聲明能蓋過去的東西。它無條件
+  拒絕所有設定、權限與憑證變更，而且不連線就完全可知——差別在**拒絕是何時決定的**：
+  blacklist 與人類同意在執行當下決定，契約無從代言；agent mode 在這裡就決定了。
+  `connection.select`、`connection.init`、`blacklist.manage` 因此在 agent mode 下
+  回 `unavailable` + `agent-mode`，不管權限寫的是不是 admin。
+
+  「沒有設定」與「有設定但解不開」是兩件事。`{"$env":...}` 密碼指向未設定變數的
+  設定檔是存在且可讀的，回報「找不到設定」是對使用者機器說假話——`context-unresolvable`
+  因此獨立成一個原因，且不外洩錯誤訊息裡的檔案路徑。
+
+  v1 涵蓋 engine capability matrix 管轄的 34 個 command key；另外 16 個指令
+  （`explain`、`plan`、`impact`、`assert`、`verify`、`evidence` 等）不在其中，
+  因為替它們寫 engine 支援度等於憑讀碼捏造未經稽核的宣稱。它們回 `unknown`，
+  擴充 matrix 是後續 Story。（DBCLI-PLAT-001，ADR-0022）
+
+- **Agent output 成為可組合的穩定契約。** `--agent-output` 提供嚴格、限界且遮蔽過的
+  Operation Envelope；`--correlation-id` 能把跨命令結果與 audit metadata 串在一起，
+  同時保留原有 human 與 JSON 輸出。（DBCLI-PLAT-004、005、006）
+
+- **外部 agent workflow 能在執行前驗證能力並留下證據。** `inspect`、`report`、
+  `schema`、`plan`、`lint`、`explain` 與 `impact assess` 可選擇寫出 bounded receipt；
+  Task Pack 的 `safety.requires` 會對 catalog 與本機 context 做 fail-closed preflight。
+  （DBCLI-PLAT-007、008）
+
+- **套件新增 Skill Author Integration Kit 與外部 consumer contracts。** 可複製的
+  Bun/TypeScript fixture 只使用公開 package surface，示範 discovery、schema pin、
+  envelope、correlation 與 evidence；CRUD、CQRS、DBA contract tests 覆蓋成功 preflight
+  與 query-only permission refusal。（DBCLI-PLAT-009、010）
+
+### Added
+
+- **Capability catalog 涵蓋所有公開指令，從 34 條增為 53 條。** PLAT-001 刻意把
+  十六個指令留在 catalog 之外——`explain`、`plan`、`impact`、`assert`、`snapshot`、
+  `verify`、`verification`、`evidence`、`contract`、`semantic`、`design`、`proxy`、
+  `recovery`、`backfill`、`password`，以及 `capabilities` 自己——理由是替沒有稽核過
+  的指令寫 engine 支援度，正是這份契約要防的那種捏造。
+
+  這次每一條宣稱都是從實作讀出來的，證據（`file:line`）逐條寫在 Story 裡。程式碼
+  會直接拒絕非 SQL 連線的六個指令標成 `unsupported`，並指名那道 gate；只有某一個
+  *模式* 需要 SQL 的（`impact assess` 與 `design` 的 `--against-cache`、`semantic`
+  的 `draft validate`）標成 `limited`，因為指令其餘部分照跑；完全不碰資料庫的標成
+  `not-applicable`。判定不了的一律 `unsupported`，不新增第三種狀態——一個「我們沒查」
+  的值，呼叫端拿到也不能做任何事，而且會永遠留在那裡沒人查。
+
+  那三條 `limited` 是第一版寫錯、被第二個讀者抓回來的：grep 到 engine check 就停手，
+  少讀了一層 caller——那道 check 擋的是模式，不是指令。寫成 `unsupported` 會對著
+  MongoDB 上的 agent 說一個它其實跑得動的指令不能用；fail-closed，所以永遠不會看起來
+  像錯的，只會讓契約悄悄比工具本身沒用。
+
+  `capabilities` 自己也在 catalog 裡（`capability.discover`、`capability.check`），
+  決定寫在 ADR-0023：live 讀的時候它確實是個常數，但 catalog 本來就是設計成可以被
+  pin 住的——一個帶著舊 catalog 的 Skill，對著沒有這個指令的 dbcli 問
+  `--require capability.check` 會拿到 `unknown-capability`，那正是它需要的訊號。
+  （DBCLI-PLAT-011）
+
+- **`supportsEvidence` 不再全部是 false。** 它原本是空集合，因為會寫 receipt 的
+  `assert`、`verify`、`evidence` 都不在 v1 catalog 裡。現在由 contract test 從指令層
+  的實際 writer 呼叫雙向推導——「import graph 碰得到 evidence 模組」不等於「會寫」，
+  `insert`、`query` 等十幾個指令只是遞移拉到型別而已。順帶補上 `recover`：它一直在
+  catalog 裡，也一直能用 `--write-verification-artifact` 寫出 artifact。
+  （DBCLI-PLAT-011）
+
+### Changed
+
+- **ORM artifact 的讀取搬進 `src/core/orm-drift/input.ts`。** 這段程式碼的註解本來就
+  寫著「never opens a database connection or reads dbcli configuration」，但它住在
+  `src/commands/diff.ts` 裡，於是 `impact assess` 與 `design` 只要 import 它，就會
+  把 diff 的 adapter import 拖進自己的 static graph——contract test 因此拒絕它們
+  `requiresConnection: false` 的宣稱。行為一個字都沒改，`diff` 原樣 re-export，
+  差別是那兩個指令的離線宣稱現在證明得出來，而不是被豁免。（DBCLI-PLAT-011）
+
+- **contract test 不再假設指令名等於檔名。** `commands/<name>.ts` 對 `password`
+  （`credential.ts`）與 `contract`（`contracts.ts`）都找不到檔案，而找不到時它是
+  「跳過」——於是「這個指令不會寫設定」對著那個專門用來改憑證的指令回了 true。
+  對照表改從 `program-lazy.ts` 的 lazy loader 讀，找不到模組是失敗而不是跳過。
+  （DBCLI-PLAT-011）
+
+### Fixed
+
+- **要求 receipt 的失敗命令現在也會留下 `outcome: failed`。** `inspect`、`report`、
+  `schema`、`plan`、`lint` 與 `explain` 原本會在 Commander `postAction` 前 exit 或 throw，
+  因而跳過 receipt；`schema` 的既有快取／未加 `--force` 成功路徑也會提早 exit。
+  這些路徑現在保留原本的輸出與 exit code，再完成 bounded receipt；任何 receipt 寫入
+  失敗仍只回報 `Failed to write evidence receipt`。（DBCLI-PLAT-007、#157）
+
+- **Schema cache 的寫入不再是一次完整設定的重新發布。** `dbcli schema` 原本透過
+  `configModule.write`（v1）與 `writeV2Config`（v2）存快取，兩者都在
+  `assertConfigMutationApproved()` 後面，所以 `DBCLI_AGENT_MODE=1` 下
+  `capabilities check` 回報 `schema.read` 可用、指令本身卻 exit 1，訊息還說的是
+  「configuration, permission, and credential changes」——只讀 exit code 的 agent
+  只能推論成資料庫讀取失敗，而讀取其實成功了。
+
+  移動時量到一個沒有人記錄過的缺陷：v1 路徑會把 `connection.password` 從
+  `config.json` 刪掉、並整份覆寫 `.env.local`。這件事**在 agent mode 之外也會發生**，
+  也就是每一次 `dbcli schema` 都在搬憑證，而那裡根本沒有任何 guard 會攔。
+
+  新的 `src/core/schema-cache-persistence.ts` 只寫快取欄位，而且**寫不出別的東西**：
+  它的參數只有 schema、connection slot 與兩個時間戳，設定是它自己從磁碟讀的，
+  沒有任何參數能夠承載憑證或權限。窄化在簽章，不在旗標——一個「這次寫入沒問題」的
+  布林參數等於把邊界交給呼叫端的誠實。`assertOnlyCacheFieldsChanged` 把同一句保證
+  講出來，任何擴大寫入範圍的修改會在單元測試指名欄位而失敗。
+
+  `assertConfigMutationApproved()` 一個字都沒改，六個 guarded writer 一個都沒少，
+  並由 `tests/contract/config-mutation-boundary.test.ts` 以名冊釘住。agent mode 下
+  `init`、`use`、`blacklist add` 與憑證指令照樣被拒。（DBCLI-PLAT-012）
+
+- **快取寫入失敗現在說自己是快取寫入失敗。** 訊息明講 schema 已成功讀出、失敗的是
+  存進本機快取那一步，並且是 bounded 的：只有 `SchemaCacheWriteError` 會原樣輸出
+  （它的訊息在建構上就不含路徑），其他成因一律分類而不引用，因為完整性拒絕會帶上
+  它檢查的設定檔路徑。（DBCLI-PLAT-012）
+
+### Breaking
+
+- **query-only 的最後一道界線改由資料庫提供。** PostgreSQL / MySQL / MariaDB 上
+  每一句 caller-controlled SQL 都在該實體連線上開一個原生唯讀交易後才送出，涵蓋
+  `query`、`export`、saved query 及其 verification、`report` 診斷、SQL shell、
+  analyzed explain，以及會把較高權限收斂成 query-only 的多連線 fan-out。語句分類
+  只看得到語句形狀，看不到 `SELECT mutate_accounts()` 背後的函式會不會寫資料——
+  這類先前成功的呼叫現在會被資料庫本身擋下。邊界建立不起來就在送出目標語句前失敗；
+  目標語句跑完但交易收尾失敗時回報結果不確定並丟棄該連線。（DBCLI-002）
+
+- **slow-endpoint-investigation task pack 新增必填的 `table` 參數。** 計畫順序變成
+  blacklist → proxy analyze → schema `<table>` → explain → guide
+  missing-index-for。先前不帶 table 的呼叫現在會在產出任何計畫之前失敗。在沒確認
+  資料表形狀的情況下讀執行計畫或索引候選，那是猜測，不是佐證。（DBCLI-012）
+
+- **儀表板內嵌 payload 改為 allowlist。** `SavedQueryMeta` 先前是整包序列化進獨立
+  HTML 的，把參數預設值與列舉、目標 index / collection、verification 的 query 與
+  expects 一起帶進一個從未渲染它們的檔案。現在只有已顯示的資料列、applied-limit
+  與安全通知、provenance，以及顯示用的 name / description 與引用已顯示欄位的圖表
+  ／KPI 定義會被序列化。讀取那些欄位的下游消費者會發現它們不再存在。（DBCLI-006）
+
+- **語意契約中形式錯誤的 subject 判為 `invalid` 而非 `stale`。** `table:orders`
+  這類形式本身就不合法的 subject 先前與「model 被改名」得到同一個判決，
+  `contract drift --format json` 的消費者因此無法區分兩者。形式檢查移到 parse
+  階段。（DBCLI-011）
+
+- **`init --no-interactive` 從無效變成有效。** 它先前讀的是
+  `options.noInteractive`，而 Commander 存的是 `interactive`，所以那個旗標從來沒
+  擋掉任何提問。依賴舊行為（帶著 `--no-interactive` 卻仍期待被提問）的腳本會改變
+  行為。（DBCLI-004）
+
+- **互動式 `init` 的遮蔽輸入沒有純文字退路。** 沒有 TTY 或載入不到遮蔽實作時，
+  直接在寫出任何設定之前失敗，並指出當下模式支援的替代輸入（`--password`、
+  `.env` / 環境變數、`--use-env-refs`，MongoDB 則是 `--uri`）。先前這些情境會以
+  可見提示收下密碼。（DBCLI-004）
+
+- **`assert` 在 receipt 寫入失敗時的 stdout 形狀改變。** 先前是一行 stderr 且沒有
+  envelope，現在 `--format json` 的呼叫端拿得到完整 envelope，exit code 仍為 1。
+  解析舊有失敗輸出的呼叫端需要跟著改。（DBCLI-009）
+
+### Added
+
+- **`skill context --context-version 2`：給外部 agent 的穩定契約。** 離線、不開
+  連線、不掃 Redis key、不讀文件、不讀專案原始碼。輸出引擎、設定權限、能力、可見
+  資源、snippet metadata、semantic 與 contracts、truncation 與 gaps；不輸出憑證、
+  實際值、預設值與計數、原始 ES mapping、Redis key/value 或專案路徑。Elasticsearch
+  只以快取的扁平欄位呈現，Redis 只接受 repository 自己宣告的
+  `dbcli.redis-context.json`。缺證據時明確回報 gap，不推測名稱與語意。不帶旗標時
+  維持 byte-compatible 的 version 1 輸出。（DBCLI-003）
+
+- **saved-query 儀表板帶上可攜、封閉的執行溯源。** version 1 的 provenance 物件與
+  對應的 Execution Traceability 區塊：邏輯連線名稱與引擎、snippet key 與來源分類、
+  實際生效的權限，以及實際生效的筆數上限——沒有套上限時明講 `not-applied`，而不是
+  留白讓人分不出完整結果與被截斷的結果。applied-limit 與畫面上的截斷警示不一致就
+  在寫檔前拒絕。直接查詢的儀表板行為不變，也不帶溯源區塊。（DBCLI-006）
+
+- **`impact assess` 的不完整性契約寫進兩份 `index.html`。** coverage 永遠是
+  `declared` 或 `partial`、v1 不宣稱 `complete`、`--fail-on` 只在報告寫出後改變
+  exit code。（DBCLI-008）
+
+### Security
+
+- **互動式 `init` 的憑證改走遮蔽輸入。** PostgreSQL / MySQL / MariaDB / Redis /
+  Elasticsearch 的密碼、MongoDB 逐欄模式的密碼，以及貼上的 MongoDB 連線字串（它
+  本身就帶著帳密），先前都停在終端機捲動紀錄、session 錄影與螢幕分享畫面裡。連線
+  測試失敗時 driver 常把密碼或整條 URI 原樣寫回錯誤訊息，現在先經過共用的
+  `redactSecretsForDisplay` 遮蔽並截斷再輸出。（DBCLI-004）
+
+- **safe-backfill 的佐證文物不再外洩敏感字串。** 寫進佐證文物的失敗原因改用固定的
+  安全字串而非 driver 的錯誤訊息；使用者自訂的 subject / summary 與 SQL 佐證會先把
+  憑證、檔案系統路徑與 SQL 註解遮掉再落檔。（DBCLI-005）
+
+- **evidence pack 的失敗輸出不再帶出絕對路徑與原始錯誤。**
+  `evidence compose --receipt <不存在>` 先前會原樣印出
+  `ENOENT: ... lstat '/private/var/.../x.json'`。receipt 的 realpath 失敗改拋有界
+  訊息；`safeMessage` 只放行兩個 validation error 類別；`validateFormat` 換成自己的
+  有界檢查——它先前會把被拒的值原樣引用，而那個位置可以是路徑。（DBCLI-010）
+
+- **語意契約的診斷不再複述產物輸入。** `rejectUnknownKeys` 先前把被拒絕的 JSON
+  property key 內插進診斷路徑，而那個 key 由產物作者控制：`contract validate` 的
+  stderr 與 `contract drift --format json` 會原樣印出帶憑證與絕對路徑的 key。改為
+  列出允許的 property 名稱。`fail()` 與 `collectContractEvidence` 的邊界一併收
+  緊。（DBCLI-011）
+
+### Fixed
+
+- **safe-backfill 的四項防護全數執行。** 先前一失敗就中斷，操作者只看得到第一個
+  擋下來的原因。blacklist、schema、plan、verify-query-readonly 現在都會執行並各自
+  回報結果；after-write 仍只在四項全過時才跑回讀斷言。（DBCLI-005）
+
+- **`assert` 的 receipt 寫入失敗不再吞掉斷言判決。** 先前直接 `process.exit(1)`，
+  `--format json` 的呼叫端拿到的不是 envelope 而是一行 stderr，`--no-fail` 的語意
+  也被推翻。改成錯誤記在結果旁邊、判決照常輸出、exit code 仍為 1——與同一個檔案裡
+  相鄰的 artifact 寫入分支一致。（DBCLI-009）
+
+- **JSON 形態的 ORM 產物改為指名檔案的 fail closed。** Drizzle snapshot 與
+  normalized JSON 先前會把 `JSON.parse` 與 Zod 的原始錯誤直接丟出去，都沒有指出是
+  哪一個檔案壞掉；agent 一次審多份產物時無從得知該修哪一個。（DBCLI-007）
+
+- **`impact assess` 的輸出目標衝突看得出原因。** `impact output already exists`
+  不在 `safeMessage` 的清單裡而被壓成泛用句子，審查者無從得知是報告檔已存在。
+  同時把 prefix 比對改成完全比對——這是雙向的：`design dialect` 這類帶插值後綴的
+  訊息反而不再放行、收斂成泛用句。prefix 的寫法在某個字串日後長出插值後綴時會默默
+  漏資訊，而那正是這個函式存在的理由。（DBCLI-008）
+
+### Documentation
+
+- **`--context-version 2`、儀表板溯源、遮蔽輸入、safe-backfill、slow-endpoint pack
+  的說明同步到四份使用者文件與相關 Pages guide**，中英雙語、Markdown 與 HTML 兩種
+  格式皆同步。（DBCLI-002 到 DBCLI-012）
+
+- **三份長期落在檢查外的 guide 納入涵蓋範圍。** `evidence-packs`、
+  `offline-impact-assessment`、`semantic-contracts` 與 `verification-evidence`
+  併入 `guideSlugs`；該清單本身改由讀目錄的檢查守住，因為手維護的清單擋不住第四
+  份。（DBCLI-008、DBCLI-010、DBCLI-011）
+
+- **receipt 旗標表格不再被一句話切成兩張**，「Flag trio」／「旗標三件組」列了四個
+  旗標，四份文件一併改為「Flags」／「旗標」。（DBCLI-009）
+
+- **`capabilities check --require` 的順序語意現在只有一種說法。** PLAT-001 的
+  Story 與 acceptance 宣告輸出「與 `--require` 參數順序無關」，實作從第一天起就在
+  `required` 與 `results` 保留 first-seen 輸入順序，而且它自己的單元測試逐字斷言
+  這件事。正式語意改為三條分開的話：相同輸入 byte-identical、兩個清單保留
+  first-seen 輸入順序、換順序不改變任何 capability 的判決與整體 `ok`。實作與輸出
+  一個位元都沒有動；`tests/docs/capability-ordering-parity.test.ts` 把八個表面
+  綁在一起，並拒絕被撤回的那句話重新長出來。（DBCLI-PLAT-013）
+
+### Process
+
+- **ForgeFlow 採用版本現在只有一個可檢查的答案。** `specs/.forgeflow-adoption` 是
+  唯一權威，`bun run forgeflow:check` 新增的
+  `scripts/check-forgeflow-adoption.ts` 把 `specs/stories/README.md`、
+  `specs/handoff.md`、Story template 與本地 `story-development` Skill 全部對回它。
+  這條 gate 的起因是它已經失效過一次：marker 與 README 推進到 0.3.2 之後，handoff
+  跨兩個已合併的 PR 仍寫著 0.3.1，沒有任何東西比對過。（DBCLI-013）
+
+- **ForgeFlow delivery gate 不再認 Story ID 的形狀。**
+  `scripts/check-forgeflow-handoff.ts` 原本用 `/^(DBCLI-\d+).*$/` 從目錄名推 ID，
+  `DBCLI-PLAT-001-capability-contract` 不匹配就被鍵在自己的完整目錄名底下——把
+  `DBCLI-PLAT-001` 加進 `completed_stories` 會得到「找不到 Story directory」，
+  指著一個明明存在的目錄。現在 ID 從每份 `story.md` 的 `# Story: <ID>` 標題讀，
+  gate 不認任何形狀，新的 ID family 不需要改它；仍然比對宣告的 ID 是不是目錄名的
+  前綴。規則搬進 `scripts/lib/forgeflow-handoff.ts`，對 fixture 測，而且不 import
+  任何東西——「這個 gate 不碰網路」因此是檔案的性質，不是註解裡的承諾。同時新增
+  一條規則：同一個 Story 不能同時是 `current_story` 與 `completed_stories`。
+  （DBCLI-PLAT-013）
+
 ## [7.0.1] - 2026-09-02 - agent 讀到的黑名單語意還停在 4.0.0
 
 ### Documentation

package/README.zh-TW.md

@@ -1357,8 +1357,7 @@ DML/DDL 指令上的部分覆蓋缺口已於 v1.20.1 結清，完整對照表見
 [`.planning/phases/25-recovery-envelope-bi-directional-linkage/25-J1-COVERAGE-MATRIX.md`](./.planning/phases/25-recovery-envelope-bi-directional-linkage/25-J1-COVERAGE-MATRIX.md)。
 
 進階 agent 工作流程（session handoff、forensics walk-through）詳見
-[`assets/SKILL.md`](./assets/SKILL.md) §Audit Log usage（英文）或
-[`assets/SKILL.zh-TW.md`](./assets/SKILL.zh-TW.md) §Audit Log 使用。
+[`assets/SKILL.md`](./assets/SKILL.md) §Audit Log usage。
 
 ---
 

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**. |