@carllee1983/dbcli 7.0.0 → 8.0.0

package/.agents/skills/story-development/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: story-development
+description: Implement an approved ForgeFlow Story when a request names a Story ID or asks to build work from specs/stories, including tests, verification, repair, and delivery reporting.
+---
+
+# Story Development
+
+Treat the approved Story as the intent boundary and repository verification as
+the completion authority.
+
+## Develop the Story
+
+1. Locate `specs/stories/<story-id>/story.md` and
+   `acceptance.md`. Read any optional `task.md` as progress
+   context only. If the Story is missing, ambiguous, or conflicts with another
+   requirement, identify the exact blocker before changing code.
+2. Extract the Goal, in-scope behavior, out-of-scope boundary, inputs, outputs,
+   business rules, expected errors, constraints, and every acceptance item. The
+   implementation contract is complete when each acceptance item maps to an
+   observable behavior or verification check. When the Story is security
+   sensitive, treat every row of its security fixture matrix as a required case
+   with an exact payload and expected persisted output; when it declares
+   superseded behavior, change the named tests deliberately instead of treating
+   the conflict as a defect.
+3. Read the repository agent guide and inspect the relevant architecture, code,
+   tests, dependencies, and documented commands. Project tooling is the source
+   of truth for technology-specific mechanics.
+4. Form a dependency-ordered implementation plan for the smallest coherent
+   end-to-end change. Keep requirement decisions with the human; ask only when a
+   missing decision materially changes behavior or risk.
+5. Implement within the Story boundary. Add or update tests at the lowest useful
+   boundary for changed behavior, including stable regression coverage for
+   repaired defects.
+6. Run useful focused checks while developing, then run `make verify`
+   from the repository root.
+
+## Repair Verification Failures
+
+When verification fails, use its output to find the root cause, repair the
+implementation or valid test defect, and run `make verify` again.
+Preserve the approved Story, acceptance criteria, and required checks throughout
+the loop.
+
+Stop only when:
+
+- `make verify` exits successfully; or
+- a genuine specification blocker requires human intent before safe progress is
+  possible.
+
+Verification failure by itself is not a specification blocker.
+
+## Deliver
+
+After PASS, report:
+
+- changed files
+- implementation summary
+- tests added or changed
+- the exact verification command and result
+- assumptions
+- remaining risks
+
+When the work changes hands, record the handoff lifecycle block: exactly one
+current Story, exactly one next Story or `pending`, completed Story IDs, the
+repository baseline commit and worktree state, and the last verification command
+and result. State that selection is pending rather than implying it by ordering.
+
+If specification-blocked, report the conflicting or missing requirement,
+evidence already inspected, and the smallest human decision needed. Do not
+claim completion.

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "7.0.0",
+  "version": "8.0.0",
   "description": "Database CLI skill and command reference for AI agents.",
   "author": {
     "name": "Carl Lee",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "7.0.0",
+  "version": "8.0.0",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/.cursor/rules/dbcli.mdc

@@ -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](../skills/dbcli/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](../skills/dbcli/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/.cursor/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
@@ -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/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "dbcli-agent",
   "displayName": "dbcli Agent",
   "description": "Database CLI skill and command reference for AI agents.",
-  "version": "7.0.0",
+  "version": "8.0.0",
   "author": {
     "name": "Carl Lee",
     "url": "https://github.com/CarlLee1983"

package/.github/skills/dbcli/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.