docs: safer-sequences page (the improve path) + post-#50 clarifications

[Kiran01bm]

Summary

Adds docs/safer-sequences.md — a human-first explanation of the improve path: why the planner's substituted sequence is safer than the submitted form, worked through on ADD CONSTRAINT … UNIQUE — and carries two small follow-up clarifications that missed the #50 merge.

Why

The improve path is the product's headline move, but nothing explains why the substitution is safer — the README demos show it happening, the reference doc has the per-operation matrix, and the contracts carry the machine shape, yet a reader who asks "these two forms end in the same catalog state, so what did I gain?" has no page. The answer (blocking risk traded for leftover-state risk, exclusive locks confined to catalog flips) is the argument that wins an evaluator.

What

• docs/safer-sequences.md: the worked ADD CONSTRAINT … UNIQUE comparison — one-statement vs two-step across locking, duplicate-failure behavior, transactionality, and cost; what the engine adds over running the idiom by hand (budgets per step, typed verdicts, visible substitution); the substitution families shipped today; the typed caveats and the USING INDEX structural limits.
• README (Improve paragraph) and docs/README.md index: link the page.
• Follow-ups that missed the docs: add execution-model page (autocommit-each-step, committed prefix) #50 merge: the committed-prefix section gains a per-step table for the four-step SET NOT NULL sequence (purpose, lock profile, budget class), and both design docs disambiguate needs-rewrite — a PostgreSQL table rewrite (copy-and-swap's job), not a rewording of the submitted SQL.

Before / after

before                                      after
┌───────────────────────────────┐           ┌───────────────────────────────┐
│ "why is the substituted       │           │ README Improve ──▶            │
│  sequence safer?"             │           │   docs/safer-sequences.md     │
│                               │           │   one page:                   │
│ improve.gif shows it happens  │           │   - worked UNIQUE example     │
│ reference doc: per-op matrix  │           │   - same end state, different │
│ suggest-report: JSON caveats  │           │     path (comparison table)   │
│                               │           │   - engine vs by-hand         │
│ no page answers "why safer"   │           │   - substitutions today       │
│                               │           │   - typed caveats + limits    │
└───────────────────────────────┘           └───────────────────────────────┘

[chatgpt-codex-connector]

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