docs: capabilities.md — canonical tiered support matrix

AGENTS.md

@@ -137,11 +137,13 @@ is a smoke tour of the built binary, not a second test suite.
 
 ## Capability statement
 
-[docs/limitations.md](docs/limitations.md) and the README's "What pg-sprite does not do yet"
-section are the public capability statement. Any PR that adds, removes, or re-scopes a
-capability — a planner route, a refusal, a verdict outcome, a declarative-model boundary —
-updates both in the same PR, and every release sweeps them against the shipped behavior
-before tagging.
+[docs/capabilities.md](docs/capabilities.md) is the canonical support matrix (every
+operation and object type, tiered supported / planned / out of scope, with reasons);
+[docs/limitations.md](docs/limitations.md) explains current refusal mechanics, and the
+README's "What pg-sprite does not do yet" section is the short-form pointer. Any PR that
+adds, removes, or re-scopes a capability — a planner route, a refusal, a verdict outcome,
+a declarative-model boundary — updates all three in the same PR, and every release sweeps
+them against the shipped behavior before tagging.
 
 ## Logging and observability
 

README.md

@@ -35,12 +35,17 @@ same budgets. Changes without an available backend get a structured refusal (exi
 The design docs and the phased
 build plan live in [docs/](docs/) — start with
 [docs/README.md](docs/README.md); the vision — what pg-sprite is and is not —
-is [docs/vision.md](docs/vision.md).
+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).
 
 ## What pg-sprite does not do yet
 
-So expectations are set before you point it at a database — the full list
-with per-item behavior is **[docs/limitations.md](docs/limitations.md)**;
+So expectations are set before you point it at a database — the complete
+support matrix (supported today / planned / out of scope, per operation and
+object type, with reasons) is **[docs/capabilities.md](docs/capabilities.md)**,
+and the mechanics of each current refusal are
+[docs/limitations.md](docs/limitations.md);
 wherever an operation meets a boundary below, it fails closed with a typed
 refusal — never a silently wrong or incomplete result:
 

docs/README.md

@@ -35,6 +35,7 @@ Aurora-only. Why that combination is the product is [vision.md](vision.md); star
 | [plan-report.md](plan-report.md) | The **plan report contract** — the versioned JSON shape both front doors emit for dry-run plans: fields, closed vocabularies, the fingerprint identity, required consumer behavior for unknown versions/values, and one generated example per source (pinned by test). |
 | [cli-output-examples.md](cli-output-examples.md) | **CLI output examples** — one real, captured JSON output per shape the CLI produces: the plan report for every dry-run disposition (execute, safer-sequence substitution, rewrite-required, backend-unavailable, refusal, destructive), the execution verdict, exit codes, the linter, and diff. |
 | [execution-model.md](execution-model.md) | The **execution model** — why safer sequences run autocommit-each-step with no wrapping transaction (PostgreSQL forbids it for the online forms), the **committed prefix** a mid-sequence failure leaves, how the verdict reports the boundary, and the per-sequence partial-failure contracts with their retry paths. Read this to answer "if a multi-step change fails halfway, what state is my table in?" |
+| [capabilities.md](capabilities.md) | The **canonical support matrix** — every operation and object type tiered as supported today / planned (typed refusal now) / out of scope by design, with reasons; how peers draw the same lines differently; why pg-sprite refuses instead of passing through. The one page for "does pg-sprite support X?". |
 | [limitations.md](limitations.md) | The **current limitations** — schema changes pg-sprite refuses today, why they are unsafe or unsupported, and where an operator must act outside the engine. |
 | [lint-report.md](lint-report.md) | The **lint report contract** — the versioned JSON shape `pg-sprite lint` emits for offline CI gating: finding fields (verbatim SQL, line/column), the codes table, severities and exit behavior, the offline-conservatism rules, and how the contract versions relative to the plan report. |
 | [suggest-report.md](suggest-report.md) | The **suggest report contract** — the versioned JSON shape `pg-sprite suggest` emits for offline advice: the typed caveat vocabulary (what changes about how you must run a safer form, and what a failed step leaves behind), the typed guidance codes for rewrites the planner cannot construct, and the operation → safer form → caveats table (pinned by test). |