@arjunkhera/atlas 0.3.2 → 0.3.3

package/agents/artifact-renderer.md

@@ -23,6 +23,30 @@ itself carries). Write the finished HTML to the output path the caller names, an
 return only a one-paragraph summary of what you rendered (sections, diagram count,
 any content you had to omit and why).
 
+## Two formats: walkthrough for designs, Organic pages for the rest
+
+**A design doc made from the walkthrough template** (it has `## Part N —`
+and `### Step N —` lines) renders in the **walkthrough format**. The owner
+chose it on 7 October 2026, for designs explained to a new joiner with
+examples and pictures. Its reference file ships with this crew:
+`${CLAUDE_PLUGIN_ROOT}/agents/artifact-format/walkthrough.html`. Copy its
+CSS, script and structure, and swap in the doc's content:
+
+- One tab for each part, then a last "Reference" tab for the rest of the doc.
+- One step block for each step: the picture on the left, and the step text
+  and an example card on the right. The example card holds the doc's
+  `Example:` block, word for word.
+- One hand-built SVG for each part, built from the steps' `Picture:` lines.
+  Each piece carries `data-step` with the step that adds it, so the picture
+  builds up. Never use mermaid on the page.
+- The page works with all scripts removed. Each step block keeps its own
+  copy of the picture, at that step's state. The reference file's comment
+  states the contract.
+- The summary sits in a card at the top of Part 1.
+
+**Every other doc** (an older design, a PRD, a review, a task explainer)
+renders in the Organic page format below.
+
 ## The ratified treatment (the owner's format — do not drift)
 
 **THE RATIFIED FORMAT is the "Organic" quiet-light design-doc format**, from an

package/door/cli.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // The atlas command: install, upgrade, doctor, check, status, the tooling
-// writer, the kind drift report, the code-read resolver and the STE check.
+// writer, the kind drift report, the code-read resolver, the STE check and
+// the design check.
 //
 // Stage 1 of the target design retired `setup`, `change`, `helpers` and
 // `test onboarding`: code that guesses meaning retires (decided 28
@@ -21,6 +22,7 @@ import { scan, toText, verdict, CHECK_VERSION, SPECS } from '../shape/check.mjs'
 import { packagePackageVersion } from './lib/releases.mjs';
 import { install, upgrade, doctor } from './lib/install.mjs';
 import { checkPaths, LIMITS } from './lib/ste.mjs';
+import { checkDesignFile, MAX_STEP_SENTENCES } from './lib/design.mjs';
 import { loadPrivateTerms } from './lib/privacy.mjs';
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -42,6 +44,7 @@ const HELP = `atlas — the door into a repo's Atlas files
   atlas ste <file or folder> …         measure markdown and HTML against the STE limits
       --share                          also run the privacy filter, quotes included
       --terms <file>                   private terms; default ~/.config/atlas/private-terms.txt
+  atlas design <file> …                check a walkthrough design doc: summary, parts, an example and a picture in each step
 
   atlas install                        install Atlas for every folder on this Mac
   atlas upgrade [--version <v>]        check, show and install a newer release
@@ -168,6 +171,19 @@ function steCommand(chosen) {
   return count ? 1 : 0;
 }
 
+function designCommand(chosen) {
+  const paths = chosen._.slice(1);
+  if (!paths.length) throw new Error('give a design doc: atlas design <file>');
+  let count = 0;
+  for (const path of paths) {
+    for (const finding of checkDesignFile(resolve(path))) { count += 1; line(`${path}:${finding.line}  ${finding.rule}  ${finding.why}`); }
+  }
+  line('');
+  line(`${paths.length} design doc(s) read; ${count} finding(s). Each step needs an Example block and a picture, and at most ${MAX_STEP_SENTENCES} sentences before its example.`);
+  line(count ? 'Fix the doc by hand. This check never rewrites.' : 'GREEN');
+  return count ? 1 : 0;
+}
+
 function checkCommand(chosen) {
   const root = rootOf(chosen);
   const report = scan({ root, repoId: chosen.repo === true ? null : chosen.repo ?? null });
@@ -195,6 +211,7 @@ export async function main(argv = process.argv.slice(2)) {
     case 'kind-drift': return kindDriftCommand(chosen);
     case 'check': return checkCommand(chosen);
     case 'ste': return steCommand(chosen);
+    case 'design': return designCommand(chosen);
     default: throw new Error(`there is no verb "${command}". Run "atlas help".`);
   }
 }

package/door/lib/design.mjs

@@ -0,0 +1,148 @@
+// The design check. It reads one markdown design doc made from the
+// walkthrough template and flags each place where the doc breaks the shape:
+// a summary, four named parts of steps, an example and a picture in every
+// step, a definition of done, the kind of change, and a reference part.
+//
+// It proves the shape, not the quality. A person still judges whether an
+// example is good. It never rewrites a word.
+//
+// Grammar: a part is a line `## Part N — <name>`; a step is a line
+// `### Step N — <title>`. A step's text is the prose between its heading and
+// its `Example:` line. Lists, tables, code and quotes do not count as prose.
+import { readFileSync } from 'node:fs';
+
+export const PARTS = Object.freeze(['What and why', 'How it flows', 'How it works', 'Decisions and done']);
+export const REFERENCE = Object.freeze({ name: 'Reference', sections: ['Approaches considered', 'Risks', 'Test plan'] });
+export const REQUIRED_SECTIONS = Object.freeze(['Definition of done', 'Kind of change, impact and undo']);
+export const MAX_STEP_SENTENCES = 3;
+export const MAX_SUMMARY_PARAGRAPHS = 2;
+
+const PART_LINE = /^## Part (\d+) [—–-] (.+?)\s*$/;
+const STEP_LINE = /^### Step (\d+) [—–-] (.+?)\s*$/;
+const EXAMPLE_LINE = /^Example\b[^:\n]*:/;
+const PICTURE_LINE = /^Picture:\s*(.*)$/;
+const DIAGRAM_FENCE = /^```\s*(mermaid|svg|diagram|dot|graphviz)\b/i;
+
+// Code spans and links go first, so a dot in `atlas.yaml` or a URL never
+// ends a sentence. A sentence ends at . ! or ? before a space and a capital.
+export function sentenceCount(text) {
+  const plain = text
+    .replace(/`[^`]*`/g, ' Code ')
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!plain) return 0;
+  return plain.split(/(?<=[.!?])\s+(?=["“(]?[A-Z])/).filter((one) => /[A-Za-z0-9]/.test(one)).length;
+}
+
+// Prose lines only: not a list item, a table row, a quote or a code block.
+function proseOf(lines) {
+  const out = [];
+  let fenced = false;
+  for (const line of lines) {
+    if (/^```/.test(line.trim())) { fenced = !fenced; continue; }
+    if (fenced) continue;
+    const trimmed = line.trim();
+    if (!trimmed || /^([-*+]|\d+[.)])\s/.test(trimmed) || trimmed.startsWith('|') || trimmed.startsWith('>')) { out.push(''); continue; }
+    if (/^\s{2,}\S/.test(line) && out.length && out[out.length - 1] === '') { out.push(''); continue; }
+    out.push(trimmed);
+  }
+  return out;
+}
+
+function paragraphs(lines) {
+  return proseOf(lines).join('\n').split(/\n\s*\n/).map((one) => one.trim()).filter(Boolean);
+}
+
+// Split the doc into level-2 sections, each with its start line and body.
+function sectionsOf(lines) {
+  const sections = [];
+  let current = null;
+  let fenced = false;
+  lines.forEach((line, index) => {
+    if (/^```/.test(line.trim())) fenced = !fenced;
+    if (!fenced && line.startsWith('## ')) {
+      current = { heading: line.slice(3).trim(), line: index + 1, body: [] };
+      sections.push(current);
+    } else if (current) current.body.push({ text: line, line: index + 1 });
+  });
+  return sections;
+}
+
+function stepsOf(section) {
+  const steps = [];
+  let current = null;
+  let fenced = false;
+  for (const row of section.body) {
+    if (/^```/.test(row.text.trim())) fenced = !fenced;
+    const match = !fenced && row.text.match(STEP_LINE);
+    if (match) { current = { number: Number(match[1]), title: match[2], line: row.line, body: [] }; steps.push(current); continue; }
+    if (!fenced && row.text.startsWith('### ')) { current = null; continue; }
+    if (current) current.body.push(row);
+  }
+  return steps;
+}
+
+function checkStep(step, finding) {
+  const label = `step "${step.title}"`;
+  const exampleIndex = step.body.findIndex((row) => EXAMPLE_LINE.test(row.text.trim()));
+  if (exampleIndex === -1) finding(step.line, 'example', `${label} has no Example block`);
+  const before = (exampleIndex === -1 ? step.body : step.body.slice(0, exampleIndex)).map((row) => row.text);
+  const count = paragraphs(before).reduce((sum, one) => sum + sentenceCount(one), 0);
+  if (count > MAX_STEP_SENTENCES) finding(step.line, 'step-text', `${label} has ${count} sentences before its example; the limit is ${MAX_STEP_SENTENCES}`);
+  const pictures = step.body.filter((row) => PICTURE_LINE.test(row.text.trim()));
+  const sketched = pictures.some((row) => {
+    const sketch = row.text.trim().match(PICTURE_LINE)[1];
+    return /→|->/.test(sketch) && !/\bTBD\b/i.test(sketch);
+  });
+  const drawn = step.body.some((row) => DIAGRAM_FENCE.test(row.text.trim()) || /<svg[\s>]/i.test(row.text) || /!\[[^\]]*\]\([^)]+\)/.test(row.text));
+  if (!sketched && !drawn) {
+    const why = pictures.length ? 'its Picture line has no arrow (→), or says TBD' : 'it has no Picture line and no diagram block';
+    finding(step.line, 'picture', `${label} has no picture: ${why}`);
+  }
+}
+
+export function checkDesign(text) {
+  const findings = [];
+  const finding = (line, rule, why) => findings.push({ line, rule, why });
+  const lines = String(text).split(/\r?\n/);
+  const sections = sectionsOf(lines);
+  const named = (name) => sections.find((section) => section.heading.toLowerCase() === name.toLowerCase());
+
+  const summary = named('Summary');
+  if (!summary) finding(1, 'summary', 'the doc has no "## Summary" section');
+  else {
+    const count = paragraphs(summary.body.map((row) => row.text)).length;
+    if (count === 0) finding(summary.line, 'summary', 'the Summary is empty');
+    if (count > MAX_SUMMARY_PARAGRAPHS) finding(summary.line, 'summary', `the Summary has ${count} paragraphs; the limit is ${MAX_SUMMARY_PARAGRAPHS}`);
+  }
+
+  const parts = sections.map((section) => ({ section, match: section.heading.match(/^Part (\d+) [—–-] (.+?)\s*$/) })).filter((one) => one.match);
+  for (const name of PARTS) {
+    const part = parts.find((one) => one.match[2].toLowerCase() === name.toLowerCase());
+    if (!part) { finding(1, 'part', `the doc has no part "${name}" (a line "## Part N — ${name}")`); continue; }
+    const steps = stepsOf(part.section);
+    if (!steps.length) finding(part.section.line, 'part', `part "${name}" has no "### Step N — <title>" line`);
+    for (const step of steps) checkStep(step, finding);
+  }
+
+  for (const name of REQUIRED_SECTIONS) {
+    if (!named(name)) finding(1, 'section', `the doc has no "## ${name}" section`);
+  }
+
+  const reference = parts.find((one) => one.match[2].toLowerCase() === REFERENCE.name.toLowerCase());
+  if (!reference) finding(1, 'reference', `the doc has no part "${REFERENCE.name}" (a line "## Part N — ${REFERENCE.name}")`);
+  else {
+    const headings = reference.section.body.filter((row) => row.text.startsWith('### ')).map((row) => row.text.slice(4).trim().toLowerCase());
+    for (const name of REFERENCE.sections) {
+      if (!headings.includes(name.toLowerCase())) finding(reference.section.line, 'reference', `the Reference part has no "### ${name}"`);
+    }
+  }
+
+  return findings.sort((a, b) => a.line - b.line);
+}
+
+export function checkDesignFile(path) {
+  return checkDesign(readFileSync(path, 'utf8'));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/skills/lead/SKILL.md

@@ -99,5 +99,6 @@ set. A test keeps the two lists equal.
 | `atlas kind-drift` | When the repo record and `atlas.yaml` may disagree on the kind; this command retires in stage 2, the onboarding stage |
 | `atlas code-read` | To resolve the citations of a code digest |
 | `atlas ste` | Before each publish; `--share` before a page goes to anyone else |
+| `atlas design` | Before you render a design doc made from the walkthrough template |
 
 A person merges every file that `atlas tooling` writes.

package/skills/sdlc-task/SKILL.md

@@ -66,7 +66,7 @@ with the date. (Target design, flow 4: long frozen texts with hashes retire.)
    sessions use `claude/`. The pull request targets that branch.
 4. **Design doc** (standard and above): copy
    [`templates/design-doc.md`](templates/design-doc.md) to
-   `docs/design-docs/<slug>.md`, fill Context and goal, and list it in
+   `docs/design-docs/<slug>.md`, fill the Summary and Part 1, and list it in
    `docs/index.md` in the commit that first lands it. Hotfix tier skips the
    doc: the definition of done lives on the work item, and a resume anchor
    covers pauses.
@@ -105,22 +105,29 @@ A lock is the owner's approval of a short design (target design, flow 4).
    `lifecycle.yaml` `lock.holds` lists: the definition of done, written as checks; the kind of change, its impact and its undo; and
    each existing test it expects to change. A change that cannot be undone
    shows in bold at the top.
-2. **The owner approves it in the owner's own words.** Gate on
+2. **Show it as a walkthrough page before you ask.** Run `atlas design` and
+   `atlas ste` on the design doc, and fix each finding by hand. Render the
+   page with the `atlas:artifact-renderer` crew, in the walkthrough format,
+   and publish it. Call `item_link` twice: kind `design-doc` for the doc, and
+   kind `artifact` for the page. Link the page from the design doc, and
+   rebuild the hub (see "The design hub" below).
+3. **The owner approves it in the owner's own words.** Gate on
    `lifecycle.yaml` `lock.preconditions`. Record the words with
    `decision_record`, and mark the design doc "Approved <date>", with the words.
-3. Call `item_lock` with the definition of done as `scope.text` and the design
+4. Call `item_lock` with the definition of done as `scope.text` and the design
    file as `scope.design_doc`. The verb keeps a fingerprint of that text for
    the tools. No person reads or writes a hash, and no frozen text is copied
    into the doc.
-4. Build against the approved design. **Tripwires** (`lifecycle.yaml`
+   Rebuild the hub, so the design reads "Building".
+5. Build against the approved design. **Tripwires** (`lifecycle.yaml`
    `tripwires`): a discovery that touches the definition of done, security, a
    schema or cost stops the build and goes back to the owner, as a change after
    approval (above).
-5. Test with the repo's own `test` procedure, which `atlas.yaml` names. Open a
+6. Test with the repo's own `test` procedure, which `atlas.yaml` names. Open a
    pull request. Its text holds the definition of done, the kind of change, the
    undo, and the list of existing tests it changes or removes, and it links the
    tracker item.
-6. **Proof before the merge.** Run the `atlas:verifier` agent on the pull
+7. **Proof before the merge.** Run the `atlas:verifier` agent on the pull
    request. It proves each line of the definition of done from a fresh run and
    posts its own proof comment. Never edit that comment. Ask the owner for the
    merge only after the proof is there, and show the proof first.
@@ -158,6 +165,27 @@ next action. One short paragraph.
 2. If anything was a struggle, encode the fix where it stops a repeat — a lint,
    then a tool, then a skill, then a doc — and say which.
 3. Design doc status: `SHIPPED <date>`.
+4. Rebuild the hub, so the design reads "Shipped".
+
+## The design hub
+
+One pinned page, "Design docs", lists every design of every product. The
+tracker holds the data; the hub holds none of its own. Rebuild it after each
+design publish, each lock and each done:
+
+1. Call `design_index`. It returns one row for each item with a `design-doc`
+   link, newest change first, and `design_hub_url`.
+2. Fill [`templates/design-hub.html`](templates/design-hub.html). Give each
+   design one table row. The row holds the date, the product, the title, the
+   state and the design doc. Link the title to the newest page.
+3. Run `atlas ste` on the page.
+4. When `design_hub_url` is set, publish to that link. When it is null, list
+   the owner's pages and look for one named "Design docs". Publish to it when
+   it exists, or publish a new page and pin it. Then call `product_edit` with
+   `design_hub_url` on any product. That call needs the owner. Without the
+   owner, skip it: the next session finds the hub by its name.
+5. When the read lists `design_hub_urls`, the products disagree. Keep the one
+   the owner has pinned, and set it on each product.
 
 ## Model tiering
 

package/skills/sdlc-task/templates/design-doc.md

@@ -1,123 +1,126 @@
-<!-- Living design document — template (sdlc-task skill, "The design loop").
-     Copy to docs/design-docs/<slug>.md at `sdlc-task start` (standard/initiative
-     tiers). Sections may be trimmed at standard tier; never at initiative.
-     The artifact projection republishes on change (D14: git is truth).
-     Structure rules that keep the doc easy to read by machine:
-     sections addressable by heading, decisions/questions as list items with
-     stable ids (D-n / OQ-n / RQ-n), no prose that depends on rendering.
-     Reference rule (the owner's directive): ids are for the machine,
-     names are for the human — every cross-reference to a stable id links to
-     its definition (markdown section link here; anchor + tooltip in the HTML
-     artifact, see the atlas:artifact-renderer crew) and spells out what
-     it is on first mention. Never leave a bare acronym for the reader to
-     decode. -->
-
 # <Feature name> — design
 
-> Status: DRAFT (in design loop) | APPROVED <date> | SHIPPED <date>
-> Work item: <work item id> · Tier: hotfix | standard | initiative
-> Artifact: <claude.ai artifact url once published>
+> Status: DRAFT | APPROVED <date> | SHIPPED <date>
+> Work item: <work item id> · Tier: standard | initiative
+> Page: <artifact url once published>
+
+*Write for a new joiner who knows nothing about this repo. Lead with the
+idea, then show it. Run `atlas design` and `atlas ste` on this file
+before you render it.*
+
+## Summary
+
+*At most two short paragraphs. Say what changes and why, in plain words.
+Use no ids.*
+
+## Part 1 — What and why
+
+### Step 1 — <one idea, in a few words>
+
+*At most three short sentences before the example.*
+
+Example:
 
-## Context & goal
+| Field | Value |
+|---|---|
+| <name> | <a real value> |
 
-<One paragraph: the problem in the owner's words (verbatim where possible),
-and the one-line goal. Agent interpretation kept separate.>
+Picture: <who or what> → <what happens> → <result>
 
-## Goals & non-goals
+### Step 2 — <the problem today>
 
-<!-- From the owner's exemplar PRD shape. Bullets, testable
-     in spirit: what this change is FOR, and what it deliberately is not.
-     Success metrics where they exist — how we'd know it worked. -->
+*Show the problem with a real case.*
 
-- Goals: …
-- Non-goals: …
-- Success metrics: …
+Example: <the real case>
 
-## Flows
+Picture: <today's flow> → <where it breaks>
 
-<The user-visible flows this touches, before → after. Sequence diagrams
-(mermaid) where they earn their keep.>
+## Part 2 — How it flows
 
-## User stories
+### Step 3 — <the first move in the new flow>
 
-<!-- Mandatory at standard/initiative tier (the owner's words: "I need
-     to see how a user would use the product, or like how the flow works").
-     Concrete scenes with stable ids (US-n): who, the moment, what they do,
-     what the system does, what they see — written as narrative the owner can
-     react to, each tagged to the slice that ships it. Illustrative dialogue
-     is fine; mark invented values as illustrative. Draft these BEFORE
-     the definition of done — its checks formalize what the stories show. -->
+*Each step adds one piece to the part's picture.*
 
-- **US-1 — <scene name>** *(slice)*: …
+Example:
 
-## Architecture
+```text
+<a real command and its real output>
+```
 
-<High-level shape: components touched, data model changes, boundaries crossed.
-Initiative tier: current-state diagram + target-state diagram.>
+Picture: <input> → <step> → <output>
 
-## Approaches considered
+## Part 3 — How it works
 
-<A/B with real depth at initiative tier — costs, risks, why the loser lost.
-Standard tier: may collapse to "approach + rejected alternative, one line".>
+### Step 4 — <one component>
 
-- **Approach A — <name>**: …
-- **Approach B — <name>**: …
-- **Chosen**: <A/B> because <reason>.
+*Name the files, the data and the boundaries this step touches.*
 
-## Open questions
+Example: <a real record, call or file>
 
-<!-- The lock precondition: this checklist must be EMPTY (all items moved to
-     Resolved) before the owner is asked to approve the design. -->
+Picture: <component> → <component>
 
-- [ ] OQ-1 —
+## Part 4 — Decisions and done
 
-## Resolved questions
+### Step 5 — Choices we made
 
-- RQ-1 — <question> → <resolution, owner-verbatim where it was an owner call> (<date>)
+*List each decision with its reason. Say what you rejected.*
 
-## Decision log
+Example: <the owner's words, or the evidence>
 
-- D-1 — <decision> — <rationale> (<date>, <who decided>)
+Picture: <choice> → <reason>
 
-## Risks & failure modes
+## Part 5 — Reference
 
-<!-- What breaks, degrades, or bites later; per-risk mitigation or "accepted".
-     From the exemplar PRD shape; trimmable at standard tier. -->
+### Approaches considered
 
-## Test & eval plan
+- **A — <name>**: <cost, risk>. Rejected because <reason>.
+- **B — <name>**: <cost, risk>. Chosen.
 
-<!-- How each slice proves itself: suites, scenarios, eval questions, prod
-     verification. The red spec's table of contents. Trimmable at standard. -->
+### Risks
+
+1. <what breaks or bites later> — <mitigation, or "accepted">
+
+### Test plan
+
+<how each check is proved: suites, scenarios, live checks>
+
+## Questions
+
+*Each open question has an id and a default. Empty this list before you
+ask for approval.*
+
+- Q-1 — <question>? Default: <answer>.
 
 ## Definition of done
 
-<!-- Written as checks, before the build. The verifier proves each line from a
-     fresh run. Name each existing test this work expects to change. -->
+*Numbered checks, written before the build. The verifier proves each one.
+Name each existing test this work changes.*
 
-1. …
+1. <check>
 
 ## Kind of change, impact and undo
 
-<!-- A change that cannot be undone goes in bold at the top of this doc. -->
+*A change that cannot be undone goes in bold at the top of this file.*
 
-- Kind: …
-- Impact: …
-- Undo: …
-- Existing tests changed or removed: …
+- Kind: <what kind of change>
+- Impact: <who or what it touches>
+- Undo: <how to undo it>
+- Existing tests changed: <list, or none>
 
 ## Approval
 
-<!-- The owner's approval of this short design is the lock (target design,
-     flow 4). Record the owner's words here and with decision_record. A change
-     after approval is a new approval, dated, in the same place. -->
+*Record the owner's own words and the date. A change after approval needs
+a new approval, written here with its date.*
 
 Approved: <date>. The owner's words: "<words>".
 
-## Deviation log (post-lock)
+## Changes after approval
+
+| Date | What changed | Why | Owner's words |
+|---|---|---|---|
+
+## Key
 
-<!-- Every post-lock divergence from this document. Review checks this list.
-     A deviation touching a tripwire (definition of done, security, schema, cost) must halt
-     and return to the owner instead of landing here. -->
+*Every id, code and short name used in this file, with its meaning.*
 
-| # | What changed vs the doc | Why | Tripwire? | Reviewed |
-|---|---|---|---|---|
+- **Q-1** — <meaning>

package/skills/sdlc-task/templates/design-hub.html

@@ -0,0 +1,43 @@
+<!doctype html>
+<!--
+The "Design docs" hub. The lead fills it from design_index and publishes it at
+design_hub_url. The hub holds no data of its own: rebuild it whole each time.
+- Copy one <tr> per design, newest first, in the order design_index returns.
+- Title cell: the item title, linked to the newest page (an "artifact" link).
+  With no page, link the design doc.
+- State cell: the state design_index gives. Use the class that matches it:
+  wait (Waiting on the owner), build (Building), ship (Shipped), other.
+- Replace the date in the header with the date of the rebuild.
+- One light scheme only.
+-->
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Design docs</title>
+<style>
+:root { --bg: #faf9f5; --surface: #ffffff; --text: #1f1e1d; --muted: #6b6862; --line: #e6e2d9; --accent: #c6613f; --wait: #b4541a; --build: #2f6f9f; --ship: #3f7a46; }
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--text); font: 16px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+main { max-width: 960px; margin: 0 auto; padding: 32px 16px 48px; }
+h1 { margin: 0 0 4px; font-size: 28px; }
+.lead { margin: 0 0 24px; color: var(--muted); }
+.wrap { overflow-x: auto; background: var(--surface); border: 1px solid var(--line); border-radius: 12px; }
+table { width: 100%; border-collapse: collapse; }
+th, td { padding: 12px 14px; text-align: left; border-bottom: 1px solid var(--line); vertical-align: top; }
+th { font-size: 13px; color: var(--muted); font-weight: 600; }
+tr:last-child td { border-bottom: 0; }
+a { color: var(--accent); }
+.state { display: inline-block; padding: 2px 10px; border-radius: 999px; font-size: 13px; font-weight: 600; white-space: nowrap; background: #f0ede6; }
+.state.wait { color: var(--wait); background: #fbeee4; }
+.state.build { color: var(--build); background: #e8f1f8; }
+.state.ship { color: var(--ship); background: #e9f3ea; }
+.when, .product { white-space: nowrap; color: var(--muted); }
+</style></head>
+<body><main>
+<h1>Design docs</h1>
+<p class="lead">Every design, for every product, newest first. Rebuilt on 2026-10-07 from the tracker.</p>
+<div class="wrap"><table>
+<thead><tr><th>Changed</th><th>Product</th><th>Design</th><th>State</th><th>Source</th></tr></thead>
+<tbody>
+<tr><td class="when">2026-10-07</td><td class="product">atlas</td><td><a href="https://claude.ai/artifact/EXAMPLE">Design docs as walkthroughs, in one place</a></td><td><span class="state build">Building</span></td><td><a href="https://github.com/ACCOUNT/REPO/blob/master/docs/design-docs/EXAMPLE.md">design doc</a></td></tr>
+</tbody>
+</table></div>
+</main></body></html>

package/work/lib/capability.mjs

@@ -19,7 +19,11 @@ import { oneLine, scrubSecrets, ROW_LINE_MAX, priorityOrderOf, byPriority, order
 import { listLine, legacySealOf, marksByItem, movementOf, pullsOfItem, readPullsByRepo, correctionsOf, daysBetween } from './delivery.mjs';
 import { acceptCodeRead, codeReadBrief } from './code-read.mjs';
 
-export const CAPABILITY_READ_VERBS = Object.freeze(['code_read_brief', 'where_are_we', 'built_pending_possible']);
+export const CAPABILITY_READ_VERBS = Object.freeze(['code_read_brief', 'where_are_we', 'built_pending_possible', 'design_index']);
+
+// The hub column for each lifecycle (design "Design docs as walkthroughs, in
+// one place", step 12). An unknown lifecycle reads as itself.
+export const DESIGN_STATES = Object.freeze({ proposed: 'Waiting on the owner', active: 'Building', paused: 'Paused', done: 'Shipped', dropped: 'Dropped' });
 
 const MAX_DIGESTS = 8;
 const MAX_TERMS = 12;
@@ -493,6 +497,49 @@ export function createCapabilityVerbs(core) {
         redactions: redactions + rendered.redactions, text: rendered.text,
       });
     },
+
+    // The source of the design hub: every item that links a design doc, in
+    // any lifecycle, newest change first. The hub page holds no data of its
+    // own, so a lost or raced rebuild is repaired by the next one.
+    async design_index(args = {}) {
+      const reg = await registry();
+      let only = null;
+      if (args.product !== undefined) only = (await requireProduct(args.product, reg)).fields.registry_id;
+      const rows = await allItems();
+      let redactions = 0;
+      const clean = (value, max = 200) => { const out = scrubSecrets(oneLine(value, max)); redactions += out.redactions; return out.text; };
+      const linksOf = (item, kind) => (Array.isArray(item.fields?.links) ? item.fields.links : [])
+        .filter((link) => link?.kind === kind && typeof link.url === 'string')
+        .map((link) => ({ url: clean(link.url, 500), role: clean(link.role ?? '', 200) }));
+      const designs = [];
+      for (const item of rows) {
+        const docs = linksOf(item, 'design-doc');
+        if (!docs.length) continue;
+        const { product, named } = productOf(item, reg);
+        if (only && product !== only) continue;
+        const lifecycle = clean(item.fields?.lifecycle ?? 'unknown', 32);
+        designs.push({
+          item: item.id, title: clean(item.title, 200), product, ...(named ? { product_named: clean(named, 64) } : {}),
+          lifecycle, state: DESIGN_STATES[lifecycle] ?? lifecycle,
+          design_docs: docs, pages: linksOf(item, 'artifact'),
+          updated: day(item.updated_at ?? item.created_at),
+        });
+      }
+      designs.sort((a, b) => b.updated.localeCompare(a.updated) || a.title.localeCompare(b.title));
+      const lines = designs.map((row) => `${row.updated}  ${row.product}  ${row.title}  [${row.state}]\n   ${row.design_docs.map((doc) => doc.url).join('\n   ')}`);
+      const rendered = scrubSecrets([`Design docs (${plural(designs.length, 'design')})`, ...lines].join('\n'));
+      return { verb: 'design_index', read_at: now(), product: only, designs, rows: designs.length, design_hub_url: hubOf(reg).design_hub_url, redactions: redactions + rendered.redactions, text: rendered.text };
+    },
   };
   return verbs;
 }
+
+// The one hub link for the tenant. It lives on product records, set by
+// product_edit. The product type is strict but takes undeclared fields, as
+// check_paths proved on the live tenant. When the products disagree, no
+// link wins:
+// the read returns null and lists each link, so the lead sets one.
+export function hubOf(reg) {
+  const urls = [...new Set([...reg.products.values()].map((row) => row.fields?.design_hub_url).filter((value) => typeof value === 'string' && value))].sort();
+  return { design_hub_url: urls.length === 1 ? urls[0] : null, ...(urls.length > 1 ? { design_hub_urls: urls } : {}) };
+}