docs: add capabilities query recipes

README.md

@@ -51,6 +51,8 @@ build plan live in [docs/](docs/) — start with
 is [docs/vision.md](docs/vision.md); the canonical support matrix — is this
 change supported today, planned, or out of scope — is
 [docs/capabilities.md](docs/capabilities.md).
+The same embedded matrix is queryable for automation with
+`pg-sprite capabilities --json`.
 
 ## What pg-sprite does not do yet
 
@@ -179,6 +181,7 @@ ever commits a change — every other command is read-only or fully offline.
 | `diff` | required | Introspect the live table (read-only) and materialize the desired-state file on a scratch schema inside a transaction that is always rolled back; prints the plan, changes nothing |
 | [`pull`](docs/pull.md) | required | Introspect each supported table in a schema and create one desired-state file per table; existing files are never overwritten, and a zero-change `diff` verifies the baseline |
 | `status` | required | Read-only view over `pg_stat_activity` for live pg-sprite sessions on the connected database |
+| `capabilities` | none | Print the embedded support matrix as a compact table, or as the versioned automation contract with `--json` |
 | `fmt` | none | Canonicalize a schema file — parser only |
 | `lint` | none | Flag patterns the engine would refuse, rewrite, or gate, from the DDL text alone |
 | `suggest` | none | Map risky DDL to the safer native form the engine would run, with typed caveats; advisory, always exits 0 |

docs/capabilities-contract.md

@@ -268,7 +268,7 @@ Implementation order is, with each step marked as it ships:
 2. add `pg-sprite capabilities`, including `--json` and the embedded binary version;
    *(done)*
 3. add the regenerate-and-diff CI gate to the normal pipeline; and *(pending)*
-4. add documentation and `jq` recipes for consumers. *(pending)*
+4. add documentation and `jq` recipes for consumers. *(done)*
 
 The generator is part of the first step rather than a cleanup step: there is never an
 intermediate state in which two hand-maintained matrices are authoritative.

docs/capabilities.md

@@ -12,6 +12,7 @@ refused form would take, what an operator who accepts a maintenance window can d
 
 ## Contents
 
+- [Query the matrix](#query-the-matrix)
 - [What pg-sprite is — and why it exists](#what-pg-sprite-is--and-why-it-exists)
 - [The support model: three tiers](#the-support-model-three-tiers)
   - [The engine path](#the-engine-path)
@@ -28,6 +29,25 @@ refused form would take, what an operator who accepts a maintenance window can d
 - [Why typed refusal, not passthrough](#why-typed-refusal-not-passthrough)
 - [Deliberately operator-owned](#deliberately-operator-owned)
 
+## Query the matrix
+
+This page is generated from the matrix embedded in the pg-sprite binary. Run
+`pg-sprite capabilities` for a compact table, or use `pg-sprite capabilities --json`
+for automation. Both forms read embedded data only and do not connect to PostgreSQL.
+The [machine-readable capabilities contract](capabilities-contract.md) defines the JSON
+schema and versioning rules.
+
+```sh
+# All T2 rows.
+pg-sprite capabilities --json | jq '.capabilities[] | select(.tier == "t2")'
+
+# Everything the declarative door refuses.
+pg-sprite capabilities --json | jq '.capabilities[] | select(.front_doors.diff == "refused")'
+
+# Rows owned by another tool class.
+pg-sprite capabilities --json | jq '.capabilities[] | select(.owning_tool_class != null)'
+```
+
 ## What pg-sprite is — and why it exists
 
 pg-sprite is an **online schema-change engine** for PostgreSQL: it takes one table-shape