@arjunkhera/atlas 0.3.22 → 0.3.25

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.22",
+  "version": "0.3.25",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/agents/artifact-renderer.md

@@ -47,6 +47,8 @@ are in `${CLAUDE_PLUGIN_ROOT}/skills/sdlc-task/design/README.md`, under
 - A step has a title and one or two sentences. The reader sets the pace.
   The figure prints as stills, and it works with its script removed.
 - Meaning is never by colour alone.
+- A figure for a story walks the story: it draws each step in order, so
+  the reader sees the flow move. The check fails a story with no such figure.
 - Close every tag. `atlas design check <folder>` flags a figure that does
   not.
 

package/door/cli.mjs

@@ -25,6 +25,7 @@ import { install, upgrade, doctor } from './lib/install.mjs';
 import { checkPaths, LIMITS } from './lib/ste.mjs';
 import { checkDesignFolder, designFolderOf, repoRootFrom } from './lib/design.mjs';
 import { writeDesignPage, readTracker } from './lib/design-build.mjs';
+import { writeViewPage, viewCapabilities } from './lib/view.mjs';
 import { loadPrivateTerms } from './lib/privacy.mjs';
 import { checkCommand as testsCheck, writeCommand as testsWrite } from './lib/tests.mjs';
 import { proofCommand as testsProof } from './lib/proof.mjs';
@@ -59,6 +60,10 @@ const HELP = `atlas — the door into a repo's Atlas files
       --out <file>                     the page; default docs/artifacts/<folder name>.html
       --draft                          build even when the check has findings, and mark the page a draft
 
+  atlas view build --product <id>      build the project view page of one product: the four views, read live from the tracker
+      --name <name>                    the product's name on the page; default the id with a capital
+      --out <file>                     the page; default docs/artifacts/<id>-view.html
+
   atlas tests check --root <area>      run the link check on the tests of an area
       --halves <list>                  static, lint, run; default all three
       --evidence <dir>                 where the evidence files are; default <area>/test/evidence
@@ -120,6 +125,7 @@ export const FLAGS = Object.freeze({
   check: { root: 'optional', repo: 'value', 'fail-on': 'value' },
   ste: { share: 'switch', terms: 'value' },
   design: { tracker: 'value', out: 'value', draft: 'switch', root: 'optional' },
+  view: { product: 'value', name: 'value', out: 'value' },
   tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch' },
   install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch' },
   upgrade: { version: 'optional', yes: 'switch' },
@@ -296,6 +302,16 @@ function designCommand(chosen) {
   return count ? 1 : 0;
 }
 
+function viewCommand(chosen) {
+  if (chosen._[1] !== 'build' || chosen._.length > 2) throw new Error('use atlas view build --product <id>');
+  const product = chosen.product;
+  const out = resolve(chosen.out ?? join('docs', 'artifacts', `${product}-view.html`));
+  const page = writeViewPage(out, { packageRoot: PACKAGE_ROOT, product, name: chosen.name, version: ATLAS_VERSION });
+  line(`Wrote ${out}: the project view of ${page.name} (product ${page.product}). It holds no records; it reads them at open.`);
+  line(`Publish it with this capability, and no other: ${JSON.stringify(viewCapabilities())}`);
+  return 0;
+}
+
 async function testsCommand(chosen) {
   const root = rootOf(chosen);
   const what = chosen._[1];
@@ -343,6 +359,7 @@ export async function main(argv = process.argv.slice(2)) {
     case 'check': return checkCommand(chosen);
     case 'ste': return steCommand(chosen);
     case 'design': return designCommand(chosen);
+    case 'view': return viewCommand(chosen);
     case 'tests': return testsCommand(chosen);
     default: throw new Error(`there is no verb "${command}". Run "atlas help".`);
   }

package/door/lib/design.mjs

@@ -5,12 +5,22 @@
 //
 // The check flags what a script can see: a needed part that is missing or
 // empty, a state line (state lives in the tracker), a code with no row in
-// the Key, a part the registry does not know, and a figure whose tags do not
-// close. It proves the shape, not the quality. It never rewrites a word.
+// the Key, a part the registry does not know, a figure whose tags do not
+// close or that woodcut cannot draw, and a part with no picture where the
+// registry asks for one. It proves the shape, not the quality. It never
+// rewrites a word.
+//
+// Pictures are needed (owner, 21 October 2026): "any user is a visual
+// person, they need to see things flowing to make sense of it." The `picture`
+// key in parts.yaml says which part needs one figure, and that each story
+// needs a walkthrough figure and a worked example.
 import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join, dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseYaml, insideRepo } from '../../shape/check.mjs';
+import { WOODCUT_TYPES, fenceOpens, fenceCloses } from './markdown.mjs';
+
+export { WOODCUT_TYPES };
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 export const PARTS_FILE = join(PACKAGE_ROOT, 'skills', 'sdlc-task', 'design', 'parts.yaml');
@@ -20,6 +30,11 @@ export const NEEDS = Object.freeze(['needed', 'optional', 'none', 'shared']);
 export const DESIGN_KEYS = Object.freeze(['title', 'item', 'product', 'kinds', 'shared', 'look']);
 export const STATE_KEYS = Object.freeze(['status', 'state', 'stage', 'approved', 'locked', 'lock', 'shipped', 'delivered']);
 export const PART_KEYS = Object.freeze(['part', 'title']);
+// What a part's `picture` key may say: `one` means the part holds at least one
+// figure; `each-story` means each story holds a walkthrough figure and a
+// worked example.
+export const PICTURES = Object.freeze(['one', 'each-story']);
+
 
 // A code: capitals then a number, such as M1, A1.7, US-3 or D-6. Common
 // technical names that look like codes are not codes.
@@ -48,6 +63,7 @@ export function loadRegistry(path = PARTS_FILE) {
   const data = parseYaml(readFileSync(path, 'utf8'));
   const kinds = data.kinds.map((one) => one.id);
   for (const part of data.parts) {
+    if (part.picture !== undefined && !PICTURES.includes(part.picture)) throw new Error(`${basename(path)}: part "${part.id}" has picture "${part.picture}"; use ${PICTURES.join(' or ')}`);
     for (const kind of kinds) {
       if (!NEEDS.includes(part[kind])) throw new Error(`${basename(path)}: part "${part.id}" has no valid "${kind}" value; use ${NEEDS.join(', ')}`);
     }
@@ -103,9 +119,9 @@ function scanLines(body, firstLine) {
   let fence = null;
   body.split('\n').forEach((text, index) => {
     const line = firstLine + index;
-    const open = text.match(/^\s*```+\s*(\S*)(?:\s+(\S+))?/);
-    if (open && !fence) { fence = { info: open[1], type: open[2] ?? null, line, lines: [] }; return; }
-    if (fence && /^\s*```+\s*$/.test(text)) { if (fence.info === 'figure' || fence.info === 'woodcut') figures.push(fence); fence = null; return; }
+    if (fence && fenceCloses(text, fence.mark)) { if (fence.info === 'figure' || fence.info === 'woodcut') figures.push(fence); fence = null; return; }
+    const mark = !fence && fenceOpens(text);
+    if (mark) { const [info, type] = text.trim().slice(mark.length).trim().split(/\s+/); fence = { mark, info: info ?? '', type: type ?? null, line, lines: [] }; return; }
     if (fence) { fence.lines.push(text); return; }
     prose.push({ text, line });
   });
@@ -143,6 +159,175 @@ export function figureFault(html) {
   return stack.length ? `<${stack[stack.length - 1]}> does not close` : null;
 }
 
+// Why woodcut cannot draw this figure, or null. It reads the shape the
+// renderer reads: a viewBox, the lists the type draws, the fields each entry
+// needs, and the ids each step names. Any other throw is a finding too: a
+// figure the check cannot read is a figure the page cannot draw.
+export function woodcutFault(type, data) {
+  try { return woodcutShapeFault(type, data); } catch (error) { return `woodcut cannot read the figure data: ${error.message}`; }
+}
+
+const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+// A list the renderer walks: absent is an empty list; anything else must be
+// an array of objects.
+function listOf(v, key) {
+  if (v[key] === undefined) return { list: [] };
+  if (!Array.isArray(v[key])) return { fault: `"${key}" must be a list` };
+  if (!v[key].every(isObject)) return { fault: `each entry of "${key}" must be an object` };
+  return { list: v[key] };
+}
+
+function woodcutShapeFault(type, data) {
+  const shape = WOODCUT_TYPES[type];
+  if (!shape) return `woodcut has no figure "${type}", so the page draws nothing; use ${Object.keys(WOODCUT_TYPES).join(', ')}, or draw your own in a \`figure\` block`;
+  if (!isObject(data)) return 'the woodcut data is not one JSON object';
+  if (data.variants !== undefined && !Array.isArray(data.variants)) return 'the woodcut "variants" must be a list';
+  const variants = data.variants ?? [data];
+  if (!variants.length) return 'the woodcut "variants" list is empty';
+  for (const [n, v] of variants.entries()) {
+    const at = variants.length > 1 ? ` in variant ${n + 1}` : '';
+    if (!isObject(v)) return `variant ${n + 1} is not an object`;
+    if (!Array.isArray(v.viewBox) || v.viewBox.length !== 2 || !v.viewBox.every(Number.isFinite)) return `the woodcut data needs "viewBox": [width, height]${at}`;
+    const lists = {};
+    for (const key of [shape.needs, ...shape.ids, ...(shape.more ?? []), 'scenarios']) {
+      const { list, fault } = listOf(v, key);
+      if (fault) return fault + at;
+      lists[key] = list;
+    }
+    if (!lists[shape.needs].length) return `a ${type} needs a non-empty "${shape.needs}" list${at}`;
+    if (lists[shape.needs].some((one) => one.id === undefined)) return `each entry of "${shape.needs}" needs an "id"${at}`;
+    const fault = elementFault(type, v, lists);
+    if (fault) return fault + at;
+    const ids = new Set(shape.ids.flatMap((key) => lists[key].map((one) => one.id)).filter((id) => id !== undefined));
+    if (type === 'wc-state-machine' && v.start) ids.add('start');
+    for (const sc of lists.scenarios) {
+      if (!Array.isArray(sc.steps)) return `the scenario "${sc.name ?? sc.id ?? '?'}" needs a "steps" list${at}`;
+      for (const step of sc.steps) {
+        if (!isObject(step)) return `each step of the scenario "${sc.name ?? sc.id ?? '?'}" must be an object${at}`;
+        for (const key of ['active', 'denied']) if (step[key] !== undefined && !Array.isArray(step[key])) return `a step's "${key}" must be a list of ids${at}`;
+        for (const id of [...(step.active ?? []), ...(step.denied ?? [])]) {
+          if (!ids.has(id)) return `a step names "${id}", which is not an element of the figure${at}`;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// The fields each element needs, or the renderer throws and the figure stays
+// blank: a place for each box, the points of each line, and a place for each
+// label on a line.
+const num = (value) => Number.isFinite(value);
+const pair = (value) => Array.isArray(value) && value.length === 2 && value.every(num);
+function elementFault(type, v, lists) {
+  const name = (one) => `"${one.id ?? one.label ?? '?'}"`;
+  if (type === 'wc-sequence') {
+    const actors = new Set(lists.actors.map((one) => one.id));
+    for (const a of lists.actors) if (!num(a.x)) return `the actor ${name(a)} needs a number "x"`;
+    for (const m of lists.messages) {
+      if (!num(m.y)) return `the message ${name(m)} needs a number "y"`;
+      if (!actors.has(m.from) || !actors.has(m.to)) return `the message ${name(m)} names an actor that is not in "actors"`;
+    }
+    for (const act of lists.activations) if (!actors.has(act.actor) || !num(act.y1) || !num(act.y2)) return `each activation needs an "actor" from "actors" and numbers "y1" and "y2"`;
+    return null;
+  }
+  if (type === 'wc-state-machine') {
+    for (const st of lists.states) if (![st.x, st.y, st.w, st.h].every(num)) return `the state ${name(st)} needs numbers "x", "y", "w" and "h"`;
+    for (const t of lists.transitions) {
+      if (typeof t.path !== 'string' || !pair(t.tip) || !pair(t.tipDir)) return `the transition ${name(t)} needs "path", "tip": [x, y] and "tipDir": [dx, dy]`;
+      if (t.label && !pair(t.labelAt)) return `the transition ${name(t)} has a label, so it needs "labelAt": [x, y]`;
+    }
+    if (v.start !== undefined && !(isObject(v.start) && pair(v.start.at))) return 'the start needs "at": [x, y]';
+    return null;
+  }
+  for (const n of lists.nodes) {
+    if (n.shape === 'end' ? ![n.x, n.y].every(num) : ![n.x, n.y, n.w, n.h].every(num)) return `the node ${name(n)} needs numbers "x", "y", "w" and "h"`;
+    if (n.shape === 'end' && n.label && !pair(n.labelAt)) return `the end node ${name(n)} has a label, so it needs "labelAt": [x, y]`;
+  }
+  for (const e of lists.edges) {
+    const fewest = e.noTip ? 1 : 2;
+    if (!Array.isArray(e.points) || e.points.length < fewest || !e.points.every(pair)) return `the edge ${name(e)} needs "points": ${fewest === 1 ? 'one or more' : 'two or more'} [x, y] pairs`;
+    if (e.label && !pair(e.labelAt)) return `the edge ${name(e)} has a label, so it needs "labelAt": [x, y]`;
+  }
+  for (const lane of lists.lanes) if (![lane.y1, lane.y2].every(num)) return `the lane "${lane.label ?? '?'}" needs numbers "y1" and "y2"`;
+  for (const g of lists.groups) if (![g.x, g.y, g.w, g.h].every(num)) return `the group "${g.label ?? '?'}" needs numbers "x", "y", "w" and "h"`;
+  return null;
+}
+
+// A woodcut figure walks when one of its scenarios has two or more steps and
+// each step has a title: the reader steps through it, and the panel tells
+// what happens at each step. It runs only on data that woodcutFault passed.
+export function woodcutWalks(data) {
+  const variants = Array.isArray(data?.variants) ? data.variants : [data];
+  return variants.some((v) => (v?.scenarios ?? []).some((sc) => Array.isArray(sc.steps) && sc.steps.length >= 2 && sc.steps.every((step) => step && step.title)));
+}
+
+// A custom figure counts as a picture when it draws: an SVG shape, or HTML
+// with at least three elements. An empty <svg> or a line of text is not one.
+const SHAPE = /<(?:rect|circle|ellipse|path|line|polyline|polygon|text|image)\b/i;
+export function figureDraws(html) {
+  const text = html.replace(/<!--[\s\S]*?-->/g, '');
+  return SHAPE.test(text) || (text.match(/<[a-zA-Z][\w-]*\b/g)?.length ?? 0) >= 3;
+}
+
+// A story heading carries a code, such as "### US-1: a test goes red". The
+// stories are the coded headings at the level of the first one; a deeper
+// heading, or an uncoded heading such as "## Overview", stays inside the story
+// before it. HTML comments and fenced blocks hold no stories.
+const STORY_CODE = /(?<![\w./-])[A-Z]{1,4}-?\d+(?:\.\d+)*(?![\w/-])/;
+function storiesOf(body, firstLine) {
+  const rows = [];
+  let fence = null;
+  let comment = false;
+  body.split('\n').forEach((text, index) => {
+    const line = firstLine + index;
+    if (fence) { if (fenceCloses(text, fence)) fence = null; rows.push({ text, line }); return; }
+    const open = fenceOpens(text);
+    if (open) { fence = open; rows.push({ text, line }); return; }
+    if (comment) { if (text.includes('-->')) comment = false; rows.push({ text, line }); return; }
+    if (/^\s*<!--/.test(text) && !text.includes('-->')) { comment = true; rows.push({ text, line }); return; }
+    const heading = text.match(/^(#{2,6})\s+(.*)$/);
+    rows.push({ text, line, heading: heading && STORY_CODE.test(heading[2].replace(/`[^`]*`/g, '')) ? { level: heading[1].length, name: heading[2].trim() } : null });
+  });
+  const level = rows.find((row) => row.heading)?.heading.level;
+  const stories = [];
+  for (const row of rows) {
+    if (row.heading && row.heading.level === level) stories.push({ name: row.heading.name, line: row.line, lines: [] });
+    else if (stories.length) stories[stories.length - 1].lines.push(row.text);
+  }
+  return stories;
+}
+
+// A worked example: a label that names the input and one that names the
+// output, such as "**Input:** ..." and "**Output:** ...". "Ask" and "Answer",
+// "Given" and "Result" count too, and so does a table with Input and Output
+// columns.
+const LABEL = (words) => new RegExp(`(?:^|[^\\w])(?:\\*\\*|__)?(?:${words})(?:\\*\\*|__)?\\s*(?::|—|–)|(?:\\*\\*|__)(?:${words})[:.](?:\\*\\*|__)|^\\s*\\|.*\\b(?:${words})\\b.*\\|`, 'i');
+const EXAMPLE_INPUT = LABEL('inputs?|ask|given|example input');
+const EXAMPLE_OUTPUT = LABEL('outputs?|answer|result|example output');
+// A part that says "No change" and why needs no picture, as the empty rule allows.
+const NO_CHANGE = /^\s*(?:#{1,6}\s.*\n\s*)*(?:\*\*|__)?no change\b/i;
+
+function pictureFindings(one, rule, figures, finding) {
+  if (NO_CHANGE.test(one.body)) return;
+  const drawn = figures.filter((figure) => !figure.open && !figure.fault && (figure.info !== 'figure' || figureDraws(figure.lines.join('\n'))));
+  if (rule === 'one') {
+    if (!drawn.length) finding(one.file, one.bodyLine, 'picture', `part "${one.part}" needs a figure; a reader must see it, not only read it. Add a \`woodcut\` or a \`figure\` block`);
+    return;
+  }
+  const stories = storiesOf(one.body, one.bodyLine);
+  if (!stories.length) { finding(one.file, one.bodyLine, 'picture', 'write each story under a heading with its code, such as "### US-1: a test goes red", with a walkthrough figure and a worked example'); return; }
+  for (const story of stories) {
+    const inside = drawn.filter((figure) => figure.line > story.line && figure.line <= story.line + story.lines.length);
+    const walks = inside.some((figure) => figure.info === 'figure' || figure.walks);
+    if (!walks) finding(one.file, story.line, 'picture', `the story "${story.name}" needs a walkthrough figure: a woodcut figure with a scenario whose steps each have a title, or a figure of your own`);
+    const words = story.lines;
+    if (!words.some((line) => EXAMPLE_INPUT.test(line)) || !words.some((line) => EXAMPLE_OUTPUT.test(line))) {
+      finding(one.file, story.line, 'picture', `the story "${story.name}" needs a worked example: an "Input:" line and an "Output:" line with real values`);
+    }
+  }
+}
+
 export function checkDesign(design, registry = loadRegistry()) {
   const findings = [];
   const finding = (file, line, rule, why) => findings.push({ file, line, rule, why });
@@ -196,10 +381,17 @@ export function checkDesign(design, registry = loadRegistry()) {
       let fault = figure.open ? 'the figure block does not close' : null;
       if (!fault && figure.info === 'woodcut') {
         if (!/^wc-[a-z-]+$/.test(figure.type ?? '')) fault = 'a woodcut block names its figure type, such as "woodcut wc-flowchart"';
-        else { try { JSON.parse(figure.lines.join('\n')); } catch (error) { fault = `the woodcut data is not JSON: ${error.message}`; } }
+        else {
+          let data;
+          try { data = JSON.parse(figure.lines.join('\n')); } catch (error) { fault = `the woodcut data is not JSON: ${error.message}`; }
+          if (!fault) fault = woodcutFault(figure.type, data);
+          if (!fault) figure.walks = woodcutWalks(data);
+        }
       } else if (!fault) fault = figureFault(figure.lines.join('\n'));
-      if (fault) finding(one.file, figure.line, 'figure', fault);
+      if (fault) { figure.fault = fault; finding(one.file, figure.line, 'figure', fault); }
     }
+    const picture = registry.byId.get(one.part).picture;
+    if (picture && !isEmpty(one.body)) pictureFindings(one, picture, figures, finding);
   }
   for (const [id, { need, by }] of needs) {
     if (need === 'needed' && !seen.has(id)) {

package/door/lib/markdown.mjs

@@ -6,6 +6,31 @@
 //
 // No dependencies. The text is the repo's own; a custom figure is trusted
 // the same way a page in the repo is.
+// The figure types that woodcut 0.4.0 defines (WOODCUT in design-build.mjs), and the list each one cannot
+// draw without. A name outside this map is an element the browser does not
+// know, so it draws nothing. The ids lists name the arrays whose ids a
+// walkthrough step may name.
+export const WOODCUT_TYPES = Object.freeze({
+  'wc-block-diagram': { needs: 'nodes', ids: ['nodes', 'edges', 'groups'], more: ['lanes'] },
+  'wc-flowchart': { needs: 'nodes', ids: ['nodes', 'edges', 'groups'], more: ['lanes'] },
+  'wc-swimlane': { needs: 'nodes', ids: ['nodes', 'edges', 'groups'], more: ['lanes'] },
+  'wc-sequence': { needs: 'actors', ids: ['actors', 'messages'], more: ['activations'] },
+  'wc-state-machine': { needs: 'states', ids: ['states', 'transitions'] },
+});
+
+// One fence rule for every reader of a page (the check, this renderer and
+// atlas ste), as CommonMark has it: a fence opens with three or more of one
+// mark, and closes only on a run of the same mark at least as long, with
+// nothing after it. So a ```` block may hold a ``` block.
+export function fenceOpens(line) {
+  const match = /^\s*(`{3,}|~{3,})/.exec(line);
+  return match ? match[1] : null;
+}
+export function fenceCloses(line, mark) {
+  const match = /^\s*(`{3,}|~{3,})\s*$/.exec(line);
+  return Boolean(match) && match[1][0] === mark[0] && match[1].length >= mark.length;
+}
+
 export const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 export const slug = (text) => String(text).toLowerCase().replace(/<[^>]+>/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
 
@@ -60,16 +85,19 @@ export function render(body, ctx) {
   };
   while (i < lines.length) {
     const line = lines[i];
-    const fence = line.match(/^\s*```+\s*(.*)$/);
-    if (fence) {
+    const mark = fenceOpens(line);
+    if (mark) {
       flush();
-      const info = fence[1].trim();
+      const info = line.trim().slice(mark.length).trim();
       const buf = [];
       i += 1;
-      while (i < lines.length && !/^\s*```+\s*$/.test(lines[i])) buf.push(lines[i++]);
+      while (i < lines.length && !fenceCloses(lines[i], mark)) buf.push(lines[i++]);
       i += 1;
       const woodcut = info.match(/^woodcut\s+(wc-[a-z-]+)/);
-      if (woodcut) {
+      if (woodcut && !WOODCUT_TYPES[woodcut[1]]) {
+        // A draft page shows the fault where the figure should be, never a blank.
+        out.push(`<p class="draft">This figure does not draw: woodcut has no figure "${esc(woodcut[1])}". Run atlas design check.</p>`);
+      } else if (woodcut) {
         let data;
         try { data = JSON.parse(buf.join('\n')); } catch (error) { throw new Error(`${ctx.file}: bad woodcut JSON in ${woodcut[1]}: ${error.message}`); }
         ctx.figures.push(woodcut[1]);

package/door/lib/ste.mjs

@@ -13,6 +13,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, extname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { privacyFindings, loadPrivateTerms } from './privacy.mjs';
+import { fenceOpens, fenceCloses } from './markdown.mjs';
 
 export const LIMITS = Object.freeze({ step: 20, sentence: 25, paragraph: 6 });
 
@@ -64,9 +65,10 @@ export function markdownUnits(text) {
   for (; index < lines.length; index += 1) {
     const line = lines[index];
     const number = index + 1;
-    const fenceMark = /^\s*(```|~~~)/.exec(line);
-    if (fence) { if (fenceMark && fenceMark[1] === fence) fence = null; continue; }
-    if (fenceMark) { close(); fence = fenceMark[1]; continue; }
+    // The fence rule of the design renderer: a ```` block may hold a ``` block.
+    if (fence) { if (fenceCloses(line, fence)) fence = null; continue; }
+    const mark = fenceOpens(line);
+    if (mark) { close(); fence = mark; continue; }
     if (!line.trim()) { close(); continue; }
     if (/^\s*>/.test(line)) { close(); continue; }
     if (comment) { if (line.includes('-->')) comment = false; continue; }

package/door/lib/view.mjs

@@ -0,0 +1,46 @@
+// The project view page builder: `atlas view build`. It puts the view rules
+// (work/lib/view-rules.mjs) and one product id into the page template
+// (view/page.html), and writes one page. The page holds no record data: it
+// reads the tracker at open, through the viewer's Engram connector.
+// Design: docs/design-docs/project-view (tracker item 6dd1761a).
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+// The one connector grant the page needs, for the Artifact publish. Both
+// tools only read.
+export const VIEW_CONNECTOR = Object.freeze({ server: 'Engram', tools: Object.freeze(['entities_list', 'get']) });
+export const viewCapabilities = () => ({ mcp: { servers: [{ server: VIEW_CONNECTOR.server, tools: [...VIEW_CONNECTOR.tools] }] } });
+
+const PRODUCT_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const quoted = (value) => JSON.stringify(String(value)).slice(1, -1).replace(/</g, '\\u003c');
+const plain = (value) => String(value).replace(/[&<>"]/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[ch]);
+
+export function buildViewPage({ packageRoot, product, name, version }) {
+  if (!PRODUCT_ID.test(String(product ?? ''))) throw new Error('give a product id: atlas view build --product <id>, such as atlas');
+  const label = String(name ?? '').trim() || product.charAt(0).toUpperCase() + product.slice(1);
+  if (label.length > 80) throw new Error('--name is at most 80 characters');
+  const template = readFileSync(join(packageRoot, 'view', 'page.html'), 'utf8');
+  const rules = readFileSync(join(packageRoot, 'work', 'lib', 'view-rules.mjs'), 'utf8');
+  if (/<\/script/i.test(rules)) throw new Error('view-rules.mjs holds "</script", so it cannot go into a page');
+  const swaps = {
+    '/*@@VIEW_RULES@@*/': rules,
+    '@@PRODUCT@@': quoted(product),
+    '@@PRODUCT_NAME@@': quoted(label),
+    '@@ATLAS_VERSION@@': quoted(version ?? ''),
+    '@@TITLE@@': plain(`${label} project view`),
+  };
+  let html = template;
+  for (const [mark, value] of Object.entries(swaps)) {
+    if (!html.includes(mark)) throw new Error(`the page template has no ${mark}`);
+    html = html.split(mark).join(value);
+  }
+  if (/@@[A-Z_]+@@/.test(html)) throw new Error('the page template has a mark the builder does not fill');
+  return { html, product, name: label };
+}
+
+export function writeViewPage(out, options) {
+  const page = buildViewPage(options);
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, page.html);
+  return page;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.22",
+  "version": "0.3.25",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",
@@ -21,6 +21,7 @@
     "work/",
     "shape/",
     "tests/",
+    "view/",
     "skills/",
     "agents/",
     ".claude-plugin/",

package/skills/lead/SKILL.md

@@ -102,6 +102,7 @@ set. A test keeps the two lists equal.
 | `atlas ste` | Before each publish; `--share` before a page goes to anyone else |
 | `atlas tests` | `write` puts the test kit in an area. `check` runs before a merge. `proof`, `verdict`, `named`, `covers` and `rerun` read the results of a run. `sweep` and `issues` run the daily sweep |
 | `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page |
+| `atlas view` | `build --product <id>` makes the project view page of one product, when the owner asks for it or after an Atlas release changes it. Publish it with only the grant the command prints |
 
 A person merges every file that `atlas tooling` writes.
 A person merges every file that `atlas tests write` writes.

package/skills/sdlc-task/SKILL.md

@@ -114,7 +114,8 @@ A lock is the owner's approval of a short design.
    shows in bold at the top.
 2. **Show the design's page before you ask.** Run
    `atlas design check <folder>` and `atlas ste` on the folder, and fix each
-   finding by hand. A part that needs a custom figure goes to the
+   finding by hand. The check needs pictures, as `design/README.md`
+   "Figures" says. A part that needs a custom figure goes to the
    `atlas:artifact-renderer` crew first. Run
    `atlas design build <folder> --tracker <item.json>`, with the tracker
    data that `design/README.md` names. Run `atlas ste` on the page and

package/skills/sdlc-task/design/README.md

@@ -90,12 +90,10 @@ gets. The kind sets which parts the design has. The two are separate: an
 initiative-tier piece of work can be a Decide design, and an Initiative
 design holds a family of designs.
 
-At initiative tier, a Decide design goes deep:
-
-1. The Problem today part has a figure of today. The Proposal part has a
-   figure of the target.
-2. At least two options get full depth in Alternatives: their costs, their
-   risks and why each one lost.
+At every tier, the Problem today part has a figure of today and the
+Proposal part has a figure of the target. At initiative tier, a Decide
+design also goes deep. At least two options get full depth in
+Alternatives: their costs, their risks and why each one lost.
 
 At standard tier, one chosen approach and one rejected option are enough.
 
@@ -167,18 +165,48 @@ Without the key, the design folder is `docs/design-docs`.
    An empty part fails the check.
 4. Put every code you use, such as `US-3` or `M1`, in the Key.
 5. Never write a state line, such as "Status: approved". The check flags it.
+6. Draw the parts that the Figures section names. The check fails a part
+   with no figure where one is needed.
 
 ## Figures
 
-1. Use a woodcut figure when a stock figure fits: a flow chart, a sequence,
-   a state machine or swim lanes. Use a fenced block with the info string
-   `woodcut wc-<type>`. It holds the figure data as JSON, in the woodcut
-   shape.
-2. Draw your own figure when the subject has its own shape. Git lanes, a
+A reader must see the design move, not only read it (owner, 21 October
+2026: "any user is a visual person, they need to see things flowing to make
+sense of it"). The check enforces it. The `picture` key in
+[parts.yaml](parts.yaml) says where:
+
+| Part | The check needs |
+|---|---|
+| Summary | One figure. |
+| Problem today | One figure of today. |
+| Proposal | One figure of the target. |
+| States | One state figure. |
+| Stories | For each story: a walkthrough figure, and a worked example with real values. The example has an `Input:` label and an `Output:` label. `Ask` and `Answer`, or a table with Input and Output columns, also count. |
+
+A story starts at a heading that holds its code, such as
+`### US-1: a test goes red`. A deeper heading stays inside the story. A part
+that says "No change" and why needs no figure.
+
+A walkthrough figure is a woodcut figure with a scenario of two or more
+steps, each with a title and one or two sentences. The reader clicks or
+presses the arrow keys, and each step lights up the part that moves. A
+figure of your own also counts.
+
+1. Use a woodcut figure when a stock figure fits. Use a fenced block with
+   the info string `woodcut <type>`. It holds the figure data as JSON.
+   The template for Stories has a full example.
+2. Pick the type by its question. `wc-sequence`: in what order?
+   `wc-swimlane`: who does it? `wc-flowchart`: which way?
+   `wc-state-machine`: what state is it in? `wc-block-diagram`: what are
+   the parts?
+3. Any other type name draws nothing, so the check refuses it. The check
+   also refuses data that the figure cannot draw. Examples are a missing
+   `viewBox`, a box with no place and a line with no points.
+4. Draw your own figure when the subject has its own shape. Git lanes, a
    time line and a data diff are examples. Use a fenced block with the info
    string `figure`. It holds the HTML. Use the page tokens, such as
    `var(--accent)` and `var(--line)`, so the figure works in both themes.
-3. Both kinds follow the same rules. A step has a title and one or two
+5. Both kinds follow the same rules. A step has a title and one or two
    sentences. The reader sets the pace. The figure prints as stills.
    Meaning is never by colour alone.
 

package/skills/sdlc-task/design/parts/problem.md

@@ -8,7 +8,8 @@ Rules:
 
 1. Say what happens today, with one real example.
 2. Cite the source: a pull request, an issue or a log line.
-3. Do not propose a fix here.
+3. Draw today with a figure. The check fails the part with no figure.
+4. Do not propose a fix here.
 
 Example, in a file of its own:
 
@@ -19,4 +20,20 @@ part: problem
 # Problem today
 
 Today the tests run after the merge. On 2 October pull request 88 merged, and its tests went red one hour later.
+
+```woodcut wc-flowchart
+{
+  "label": "Today: the tests run after the merge",
+  "viewBox": [460, 70],
+  "nodes": [
+    { "id": "pr", "x": 10, "y": 18, "w": 110, "h": 34, "label": "Pull request", "shape": "pill" },
+    { "id": "merge", "x": 175, "y": 18, "w": 110, "h": 34, "label": "Merge" },
+    { "id": "tests", "x": 340, "y": 18, "w": 110, "h": 34, "label": "Tests: red", "kind": "accent" }
+  ],
+  "edges": [
+    { "id": "e1", "points": [[120, 35], [173, 35]] },
+    { "id": "e2", "points": [[285, 35], [338, 35]] }
+  ]
+}
+```
 ````

package/skills/sdlc-task/design/parts/proposal.md

@@ -8,7 +8,7 @@ Rules:
 
 1. Name the option we pick, and say how it works in steps.
 2. Give a worked example: the input, the process and the output.
-3. Link the figure that shows it.
+3. Draw the target with a figure. The check fails the part with no figure.
 
 Example, in a file of its own:
 
@@ -18,7 +18,35 @@ part: proposal
 ---
 # Proposal
 
+The tests run before the merge.
+
+```woodcut wc-flowchart
+{
+  "label": "Target: the tests run before the merge",
+  "viewBox": [460, 70],
+  "nodes": [
+    { "id": "pr", "x": 10, "y": 18, "w": 110, "h": 34, "label": "Pull request", "shape": "pill" },
+    { "id": "tests", "x": 175, "y": 18, "w": 110, "h": 34, "label": "Tests", "kind": "accent" },
+    { "id": "merge", "x": 340, "y": 18, "w": 110, "h": 34, "label": "Merge" }
+  ],
+  "edges": [
+    { "id": "e1", "points": [[120, 35], [173, 35]] },
+    { "id": "e2", "points": [[285, 35], [338, 35]], "label": "green only", "labelAt": [311, 12] }
+  ],
+  "scenarios": [{
+    "name": "Pull request 88",
+    "steps": [
+      { "title": "A pull request opens", "body": "Pull request 88 changes src/pay.mjs.", "active": ["pr"] },
+      { "title": "The gate runs the tests", "body": "The test pay rounds down goes red.", "active": ["e1", "tests"] },
+      { "title": "The merge waits", "body": "Only a green run opens the merge.", "active": ["e2", "merge"] }
+    ]
+  }]
+}
+```
+
 1. A pull request opens.
 2. The gate runs the tests on its head.
 3. A red test blocks the merge button.
+
+Input: pull request 88 with one failing test. Output: the merge button stays grey.
 ````