Improve Codebase :: Documentation Drift

[81reap]

I have started on this path with #1382 but I thought it would be worth creating an issue to track all of the changes I'm thinking about that will come after this. This audit was done with the help of Claude.

C1. CONTRIBUTING.md tells contributors to use a parameter type that does not exist

CONTRIBUTING.md:131 and :185 instruct contributors to use 'TEXT|BOOLEAN|NUMBER|JSON|ICON|COLOR' and
'TEXT|BOOLEAN|NUMBER|JSON' when documenting a component parameter.

NUMBER is not a valid type. The parameter_type table is seeded with exactly:

BOOLEAN, COLOR, HTML, ICON, INTEGER, JSON, REAL, TEXT, TIMESTAMP, URL

(examples/official-site/sqlpage/migrations/01_documentation.sql:11-12)

AGENTS.md:134 lists the correct set. CONTRIBUTING.md:130 also omits description_md.

---

C2. CONTRIBUTING.md prescribes checks that are weaker than CI

A contributor who follows CONTRIBUTING.md exactly can pass locally and fail CI.

	CONTRIBUTING.md	CI
Rust lint	cargo clippy (:58-61)	cargo clippy --all-targets --all-features -- -D warnings (ci.yml:48)
Frontend	npx @biomejs/biome check . (:69)	npm test = biome check . && npm run typecheck && node --test ... (package.json:6-7)

Two smaller gaps in the same area:

• AGENTS.md:91-92 requires a CHANGELOG.md entry for user-visible changes. The CONTRIBUTING.md pull-request checklist (:206-211) never mentions the changelog.
• AGENTS.md:131-137 lists six official-site documentation tables but omits blog_posts (12_blog.sql:1-8).

---

C3. Component documentation and templates have drifted apart in both directions

The official site stores component documentation as rows in a parameter table, spread across roughly 50
INSERT INTO parameter(...) statements in 40+ migration files. Nothing links those rows to the .handlebars templates they describe.

Documented but never implemented. text.width — "How wide the paragraph should be, in characters"
(01_documentation.sql:149). There is no width in text.handlebars, and no handling in src/.

Implemented but undocumented. Confirmed by grep:

Property	Template
form.formmethod, form.formnovalidate, form.formtarget	form.handlebars:131-133
form.accept	form.handlebars:136
table.number_format_locale	table.handlebars:27

A broader sweep found roughly 18 divergences in total, including form.validate_shape/validate_size and
form.narrow (documented for login and button respectively, but implemented for form too), and rss.sub_category/rss.funding_text.

Documented at the wrong level. card, tab and big_number each implement id/class at both the
top level and the row level; each is documented at only one.

Structural cause. A shared migration, 99_shared_id_class_attributes.sql, inserts id and class for about 20 components from a single list. Newer migrations bypass it and re-declare the same two properties inline (49_big_number.sql:11-12, 52_foldable.sql:5-8, 60_empty_state.sql:17-18, 63_modal.sql:14-15,
76_toast.sql:17-18).

Suggested approach. Reconcile the current differences first, as a self-contained change. One migration hazard to plan around: parameter has PRIMARY KEY (component, top_level, name), so consolidating rows into 99_shared_id_class_attributes.sql must delete the inline duplicates in the same change, or the migration run aborts. SQLPage's migration runner also does not re-run a file that has already been applied. A CI check that compares templates against the documentation table would prevent recurrence.