feat(contracts): add one shape and primitive registry

Makefile

@@ -21,6 +21,7 @@ versions:
 
 contracts:
 	node scripts/review-contracts.mjs
+	node scripts/check-contracts.mjs
 
 # Every page under examples/ is a real artifact and faces the full gate, incl.
 # the >=3 HTML-native feature floor. Only examples/primitives/*.html — the

contracts/primitives.json

@@ -0,0 +1,104 @@
+{
+  "primitives": [
+    {
+      "id": "donut",
+      "pickWhen": "2–5 mutually-exclusive categories where proportion-at-a-glance beats absolute counts",
+      "register": "instrument",
+      "requiredFeatures": ["inline_svg"],
+      "example": "examples/primitives/01-donut.html",
+      "href": "primitives/01-donut.html",
+      "reference": "references/primitives/donut.md",
+      "skillHeading": "#### Donut\\b"
+    },
+    {
+      "id": "bar",
+      "pickWhen": "≤12 items where order matters and a single magnitude per item is the signal",
+      "register": "instrument",
+      "requiredFeatures": [],
+      "example": "examples/primitives/02-bar.html",
+      "href": "primitives/02-bar.html",
+      "reference": "references/primitives/bar.md",
+      "skillHeading": "#### Bar\\b"
+    },
+    {
+      "id": "sparkline",
+      "pickWhen": "2–4 hero metrics where each metric is the subject; current value + recent-trend shape is the one-glance read",
+      "register": "instrument",
+      "requiredFeatures": ["inline_svg"],
+      "example": "examples/primitives/03-sparkline.html",
+      "href": "primitives/03-sparkline.html",
+      "reference": "references/primitives/sparkline.md",
+      "skillHeading": "#### Sparkline\\b"
+    },
+    {
+      "id": "stacked-bar",
+      "pickWhen": "categories sum to a meaningful whole each period; 7–30 periods",
+      "register": "instrument",
+      "requiredFeatures": ["cross_highlight"],
+      "example": "examples/primitives/04-stacked-bar.html",
+      "href": "primitives/04-stacked-bar.html",
+      "reference": "references/primitives/stacked-bar.md",
+      "skillHeading": "#### Stacked bar\\b"
+    },
+    {
+      "id": "topology",
+      "pickWhen": "connections are the point and node count is ≤30",
+      "register": "instrument",
+      "requiredFeatures": ["inline_svg"],
+      "example": "examples/primitives/05-topology.html",
+      "href": "primitives/05-topology.html",
+      "reference": "references/primitives/topology.md",
+      "skillHeading": "#### Topology\\b"
+    },
+    {
+      "id": "dense-ops-table",
+      "pickWhen": "flat list of records keyed by an identifier; ≥6 rows; filter/sort is the central interaction",
+      "register": "instrument",
+      "requiredFeatures": ["table"],
+      "example": "examples/primitives/06-table-ops.html",
+      "href": "primitives/06-table-ops.html",
+      "reference": "references/primitives/dense-ops-table.md",
+      "skillHeading": "#### Dense ops table\\b"
+    },
+    {
+      "id": "comparison-matrix",
+      "pickWhen": "X vs Y vs Z decision matrix with shared criteria and live weight tuning",
+      "register": "instrument",
+      "requiredFeatures": ["table"],
+      "example": "examples/primitives/07-table-comparison.html",
+      "href": "primitives/07-table-comparison.html",
+      "reference": "references/primitives/comparison-matrix.md",
+      "skillHeading": "#### Comparison matrix\\b"
+    },
+    {
+      "id": "annotated-diff",
+      "pickWhen": "code changes or line-anchored critique where adjacency to the source beats a side panel",
+      "register": "instrument",
+      "requiredFeatures": ["copy_as_prompt"],
+      "example": "examples/primitives/08-diff.html",
+      "href": "primitives/08-diff.html",
+      "reference": "references/primitives/annotated-diff.md",
+      "skillHeading": "#### Annotated diff\\b"
+    },
+    {
+      "id": "log-stream",
+      "pickWhen": "a tail of timestamped events with a categorical level; newest-first reading",
+      "register": "instrument",
+      "requiredFeatures": ["filtering"],
+      "example": "examples/primitives/09-logs.html",
+      "href": "primitives/09-logs.html",
+      "reference": "references/primitives/log-stream.md",
+      "skillHeading": "#### Log stream\\b"
+    },
+    {
+      "id": "scatter",
+      "pickWhen": "two genuinely independent, well-spread dimensions across ≥10 points where the relationship is the signal",
+      "register": "instrument",
+      "requiredFeatures": ["inline_svg"],
+      "example": "examples/primitives/10-scatter.html",
+      "href": "primitives/10-scatter.html",
+      "reference": "references/primitives/scatter.md",
+      "skillHeading": "#### Scatter\\b"
+    }
+  ]
+}

contracts/shapes.json

@@ -0,0 +1,112 @@
+{
+  "shapes": [
+    {
+      "id": "dashboard",
+      "pickWhen": "Network scans, system reports, device lists, ops data — anything tabular with categories that benefit from filtering",
+      "register": "instrument",
+      "requiredFeatures": ["search", "table", "copy_as_prompt"],
+      "example": "examples/dashboard.html",
+      "href": "dashboard.html",
+      "reference": "references/shapes/dashboard.md"
+    },
+    {
+      "id": "document",
+      "pickWhen": "Plans, specs, briefings, essays, brainstorms, meeting notes — prose-heavy where you'd read paragraph-to-paragraph",
+      "register": "reading",
+      "requiredFeatures": ["table", "copy_as_prompt"],
+      "example": "examples/document.html",
+      "href": "document.html",
+      "reference": "references/shapes/document.md"
+    },
+    {
+      "id": "timeline",
+      "pickWhen": "Dated logs, diaries, retrospectives, project histories, trip journals",
+      "register": "reading",
+      "requiredFeatures": ["filtering"],
+      "example": "examples/timeline.html",
+      "href": "timeline.html",
+      "reference": "references/shapes/timeline.md"
+    },
+    {
+      "id": "runbook",
+      "pickWhen": "Disaster recovery, deploy guides, machine rebuilds — sequential procedure being executed not read",
+      "register": "instrument",
+      "requiredFeatures": ["copy_as_prompt", "toggle"],
+      "example": "examples/runbook.html",
+      "href": "runbook.html",
+      "reference": "references/shapes/runbook.md"
+    },
+    {
+      "id": "comparison",
+      "pickWhen": "X vs Y vs Z decision matrices, model comparisons, vendor pickers",
+      "register": "instrument",
+      "requiredFeatures": ["table", "copy_as_prompt"],
+      "example": "examples/comparison.html",
+      "href": "comparison.html",
+      "reference": "references/shapes/comparison.md"
+    },
+    {
+      "id": "network-map",
+      "pickWhen": "People/relationships, brain backlinks, dependencies — connections matter",
+      "register": "instrument",
+      "requiredFeatures": ["search", "inline_svg"],
+      "example": "examples/network-map.html",
+      "href": "network-map.html",
+      "reference": "references/shapes/network-map.md"
+    },
+    {
+      "id": "triage-board",
+      "pickWhen": "Bucketing items into 3–5 columns (Now/Next/Later/Cut), inbox triage, GTD reorg",
+      "register": "instrument",
+      "requiredFeatures": ["drag", "copy_as_prompt"],
+      "example": "examples/triage-board.html",
+      "href": "triage-board.html",
+      "reference": "references/shapes/triage-board.md"
+    },
+    {
+      "id": "developer",
+      "pickWhen": "PR writeups, code review, explain this code — annotated diff with severity findings",
+      "register": "instrument",
+      "requiredFeatures": ["table", "textarea"],
+      "example": "examples/developer.html",
+      "href": "developer.html",
+      "reference": "references/shapes/developer.md"
+    },
+    {
+      "id": "editorial",
+      "pickWhen": "Argument-driven long-form where the reader absorbs a sustained position",
+      "register": "reading",
+      "requiredFeatures": ["search", "copy_as_prompt"],
+      "example": "examples/editorial.html",
+      "href": "editorial.html",
+      "reference": "references/shapes/editorial.md"
+    },
+    {
+      "id": "execution-log",
+      "pickWhen": "Live or snapshot execution telemetry — branch status, plan progress, event stream, observed state",
+      "register": "instrument",
+      "requiredFeatures": ["search", "table"],
+      "example": "examples/execution-log.html",
+      "href": "execution-log.html",
+      "reference": "references/shapes/execution-log.md"
+    },
+    {
+      "id": "deck-review",
+      "pickWhen": "Slide deck review/approval surfaces — status memo, slide preview, per-slide notes, send-back workflow",
+      "register": "hybrid",
+      "requiredFeatures": ["local_storage", "textarea"],
+      "example": "examples/deck-review.html",
+      "href": "deck-review.html",
+      "reference": "references/shapes/deck-review.md"
+    },
+    {
+      "id": "podcast",
+      "pickWhen": "A podcast episode rendered as a briefing alongside a transcript browser",
+      "register": "hybrid",
+      "requiredFeatures": ["local_storage", "toggle"],
+      "example": "examples/podcast.html",
+      "href": "podcast.html",
+      "reference": "references/shapes/podcast.md"
+    }
+  ]
+}

examples/podcast.html

@@ -593,7 +593,7 @@ <h1>The <span class="a">instrument</span> you keep</h1>
         <span class="dot tool"></span>
         <div>
           <div class="name"><a href="https://github.com/twidtwid/render-as-html" target="_blank" rel="noopener noreferrer">render-as-html<span class="ext">↗</span></a></div>
-          <div class="note">The Claude Code / Codex skill this gallery documents. Nine page shapes, one palette, canonical primitives, copy-as-prompt as the load-bearing pattern. (Real.)</div>
+          <div class="note">The Claude Code / Codex skill this gallery documents. Twelve page shapes, one palette, canonical primitives, copy-as-prompt as the load-bearing pattern. (Real.)</div>
         </div>
       </div>
 
@@ -611,8 +611,8 @@ <h1>The <span class="a">instrument</span> you keep</h1>
       <p class="card-title">Read next</p>
       <ul class="next-list">
         <li><a href="editorial.html"><span class="label">The editorial example<span class="next-note">Sibling artifact making the same argument as a longform essay.</span></span><span class="arrow">→</span></a></li>
-        <li><a href="primitives.html"><span class="label">Canonical primitives<span class="next-note">The nine chart and table primitives the shapes are built from.</span></span><span class="arrow">→</span></a></li>
-        <li><a href="index.html"><span class="label">All eleven shape examples<span class="next-note">Gallery index — one artifact per shape.</span></span><span class="arrow">→</span></a></li>
+        <li><a href="primitives.html"><span class="label">Canonical primitives<span class="next-note">The ten chart and table primitives the shapes are built from.</span></span><span class="arrow">→</span></a></li>
+        <li><a href="index.html"><span class="label">All twelve shape examples<span class="next-note">Gallery index — one artifact per shape.</span></span><span class="arrow">→</span></a></li>
         <li><a href="https://github.com/twidtwid/render-as-html" target="_blank" rel="noopener noreferrer"><span class="label">render-as-html on GitHub<span class="next-note">Source repo for the skill.</span></span><span class="arrow">↗</span></a></li>
       </ul>
     </section>