docs: fixes and refresh architecture map

[Kiran01bm]

Summary

A new-user pass over docs/architecture.md: adds a "Why introspect?" section explaining why pg-sprite derives schema models by execute-and-introspect rather than by transforming parsed DDL into an in-memory model, and brings the surrounding sections (pipeline diagram, stage table, package map) up to date with the code.

What

• New "Why introspect — ask PostgreSQL, don't reimplement it?" subsection: the failure mode of AST transformation (a Go reimplementation of PostgreSQL's DDL semantics that drifts across versions 14 → 18), then the seven concrete steps a declarative diff takes — parse for admission, scratch schema in a transaction, execute the desired DDL, introspect the catalogs, roll back, model-vs-model diff, re-enter parse → classify → lint. Closes with the honest limit (an empty scratch table says nothing about rewrite/lock cost, so the classifier still predicts) and links the recorded decision in low-level-design.md.
• Corrects the pipeline diagram: diff output chains back through the parse boundary before classification, rather than feeding classify directly; the CLI box now lists all six commands.
• Adds a Live DB? column to the five-stage table — only Introspect touches the database — with a note mapping that to the commands (lint/suggest/fmt run fully offline; diff/dry-run connect for facts; migrate for facts and execution).
• Refreshes the package map: adds pkg/suggest, lists the suggest command, and replaces pkg/preflight's stale phase note with the gates that exist today (size guard, tiered privilege checks, partition support).
• Adds a table of contents and phrases the explainer headings as questions.

Why

The INTROSPECT box in the pipeline diagram and the one-line rationale in the stage table state what happens but not why the alternative loses. New readers coming from tools that do AST-based diffing keep asking this; the answer deserves a scannable, step-by-step home in the architecture doc. Whether a command needs a live connection is the first practical question a new user hits, and the package map had fallen behind the code.

[chatgpt-codex-connector]

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