ADR 04: Structured content (CMS v2)

Items are data. Pages are rendered from it.

Status: adopted (2026-07-15), replaces HTML-extraction v1

Context

v1 collections extracted fields positionally from page markup. That capped out: no reorder, no per-item drafts, no references, fragile against redesigns, and column labels were meaningless (“Text 1, 2, 3”).

Decision

Collections store items as JSON in the site repo, and the page section is rendered from that data between anchor comments. Owner-approved choices: structured data over HTML-first, per-item draft/published status over branch drafts, detail pages now, per-site views only (fleet view added later as pure aggregation).

Full spec in Systems: CMS.

Consequences

• Unlocked: typed schema, drafts, reorder, search, sort, bulk select, CSV import/export, image uploads, AI operations on clean JSON, per-item detail pages, field add/remove via agent template edits.
• Existing v1 collections migrate automatically on first open, with byte-equivalent first render.
• Content survives page redesigns because data lives outside markup.
• The live site shows only published items; drafts are invisible until published.
• Concurrent edits are guarded by a revision token; stale writes get a clean 409.