docs: capabilities.md — canonical tiered support matrix

[Kiran01bm]

Summary

Adds docs/capabilities.md — the canonical, TOC'd support matrix answering the three questions users actually ask: does pg-sprite support this change, what is pg-sprite and why does it exist, and what does it deliberately not do. Every operation and object type lands in exactly one of three tiers, with the reason stated.

What

• The three-tier support model: T1 supported today · T2 planned (a typed refusal today, never a silent fallback) · T3 out of scope by design — with the invariant that every T2 row is a tracked plan and T3 rows deliberately have none.
• The two front doors called out explicitly: imperative (migrate --alter) has the broadest coverage — FK/CHECK via NOT VALID + VALIDATE, PK/UNIQUE via CIC + USING INDEX, SET NOT NULL via the four-step validated-CHECK flow, DROP INDEX/REINDEX via CONCURRENTLY — while the declarative model is deliberately narrower (partitions, FKs both directions, unlogged, collations, non-owned sequence defaults refuse). Every matrix row was verified against pkg/planner and pkg/schemadiff on main, not written from memory.
• Per-family matrices: column changes, constraints, indexes, partitioned tables, the declarative model, types and non-table objects, data and whole-table operations.
• "Peers share these limits — for different reasons": imperative executors never face the question, pgroll's raw-SQL escape hatch is passthrough-not-support, planners have breadth because they don't own execution under load.
• "Why typed refusal, not passthrough": the weighed decision — the exit-code contract (0 = ran through an online-safe path) is the product; the naive bypass stays rejected, and a constrained lock-budgeted variant (explicit flag, refusal analysis still printed, bounded lock budgets, verdict unmistakably marked) is recorded as planned.
• Cross-wiring: AGENTS.md capability statement now names capabilities.md as canonical (and requires updates in the same PR as any capability change), README's "What pg-sprite does not do yet" and docs/README.md index point at it, limitations.md is repositioned as the refusal-mechanics page.

Why

Support questions ("does pg-sprite handle X?") currently route to a scatter of README bullets, limitations.md, and tribal knowledge — and the answer differs by front door, which nothing stated. One canonical page makes the scope legible to external users and gives refusal messages and release notes a stable target. A support question this page cannot answer is a bug in this page.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.