@arjunkhera/atlas 0.4.46 → 0.4.48

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -24,6 +24,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 { writePage } from './lib/page.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';
@@ -60,6 +61,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
+                                       an HTML page also needs a woodcut figure and only Atlas theme colours
       --terms <file>                   private terms; default ~/.config/atlas/private-terms.txt
   atlas design check <folder> …        check a design folder: each needed part, no state line, every code in the Key
   atlas design folder                  print where this repo keeps its designs: design.folder in atlas.yaml, or docs/design-docs
@@ -69,6 +71,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 page build <file or folder>    build an explainer page from markdown: woodcut figures, the Atlas theme, light and dark
+      --out <file>                     the page; default <file or folder>.html beside it
+      --title <text>                   the page title; default the title of the first part
+
   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
@@ -211,6 +217,7 @@ export const FLAGS = Object.freeze({
   check: { root: 'optional', repo: 'value', 'fail-on': 'value', json: 'switch' },
   ste: { share: 'switch', terms: 'value' },
   design: { tracker: 'value', out: 'value', draft: 'switch', root: 'optional' },
+  page: { out: 'value', title: 'value' },
   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', head: 'value', list: 'value', side: 'value', old: 'value', new: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value', language: 'value' },
   jobs: { root: 'optional', repo: 'value', branch: 'value', out: 'value', findings: 'value', max: 'value', 'dry-run': 'switch' },
@@ -391,6 +398,26 @@ function designCommand(chosen) {
   return count ? 1 : 0;
 }
 
+function pageCommand(chosen) {
+  const sources = chosen._.slice(2);
+  if (chosen._[1] !== 'build') throw new Error('use atlas page build <file or folder>');
+  if (sources.length !== 1) throw new Error('give one markdown file or one folder: atlas page build <file or folder>');
+  const source = resolve(sources[0]);
+  const out = resolve(chosen.out ?? `${source.replace(/\.md$/, '').replace(/\/+$/, '')}.html`);
+  const result = writePage(source, out, { title: chosen.title ?? null });
+  if (!result.html) {
+    for (const finding of result.findings) line(`${finding.file}:${finding.line}  page  ${finding.why}`);
+    line('');
+    line(`No page written: ${result.findings.length} finding(s). Fix the markdown by hand.`);
+    return 1;
+  }
+  line(`Wrote ${out}: ${result.parts} part(s), ${result.figures} woodcut figure(s), ${result.walks} that walk.`);
+  const findings = checkPaths([out]).flatMap((one) => one.findings);
+  for (const finding of findings) line(`${out}:${finding.line}  ${finding.rule}  ${finding.why}`);
+  line(findings.length ? `atlas ste: ${findings.length} finding(s) on the page. Fix the markdown by hand and build again.` : 'atlas ste: GREEN. Publish the page.');
+  return findings.length ? 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;
@@ -481,6 +508,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 'page': return pageCommand(chosen);
     case 'view': return viewCommand(chosen);
     case 'tests': return testsCommand(chosen);
     case 'jobs': return jobsVerb(chosen);

package/door/lib/approve.mjs

@@ -14,6 +14,10 @@
 //                                  for each with one touch, post the block on
 //                                  each pull request, close each audit issue,
 //                                  and print the one message for the lead
+//   atlas approve audit-code <pr>  show the audit-code diff of one merged
+//                                  pull request and its red audit check,
+//                                  sign one accept-code act with one touch,
+//                                  post the block, and print the message
 //   atlas approve verify --file f  verify the blocks of a file against the
 //                                  key file of a repo
 //   atlas approve key-check        sign a test text and verify it with the
@@ -30,10 +34,10 @@ import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { childEnvironment } from '../../work/lib/child-env.mjs';
 import { parseYaml } from '../../shape/check.mjs';
-import { ghApi, pinnedRuns } from './gate.mjs';
+import { ghApi, pinnedRuns, commitAudit } from './gate.mjs';
 import { GATE_CHECK } from './gate-check.mjs';
 import {
-  ACTS, MAX_ACTS, AUDIT_CHECK, AUDIT_TEST, NAMESPACE, SIGNERS_FILE, payloadText, blockText, parseSigners, verifyBlock, verifyTexts, fingerprint, wordsFingerprint, SignedActError,
+  ACTS, MAX_ACTS, AUDIT_CHECK, AUDIT_CHECKS, AUDIT_TEST, AUDIT_CODE, AUDIT_CODE_TEST, AUDIT_WORKFLOW, auditCodeDiff, NAMESPACE, SIGNERS_FILE, payloadText, blockText, parseSigners, verifyBlock, verifyTexts, fingerprint, wordsFingerprint, SignedActError,
   preKeyKeys,
 } from './signed-act.mjs';
 
@@ -241,9 +245,8 @@ export async function approvePulls({ prs, repo, root, key, provider, yes = false
 // (R14 line 3), and its filing job then ends red on the merge commit. That red
 // job is the check the owner accepts; the test that his words quote is the
 // kind of the finding (item 0ca9fced, design docs/design-docs/audit-red-sign-off/).
-export { AUDIT_CHECK, AUDIT_TEST };
+export { AUDIT_CHECK, AUDIT_TEST, AUDIT_CODE, AUDIT_WORKFLOW };
 export const AUDIT_ISSUE = /^atlas-job: gate-audit owner-unsigned:([0-9a-f]{40})$/;
-export const AUDIT_WORKFLOW = '.github/workflows/atlas-gate-audit.yml';
 // The label on an audit issue whose red the owner accepted. The lead closes
 // the issue after the done tool records the acceptance (security review S3).
 export const ACCEPTED_LABEL = 'atlas-accepted';
@@ -257,10 +260,6 @@ export function auditWords(prs, at) {
   return `I accept the ${AUDIT_TEST} audit reds of ${prs.map((pr) => `#${pr}`).join(', ')}, listed at ${new Date(at).toISOString().slice(0, 16)}Z. These pull requests merged without my touch, under my standing approval.`;
 }
 
-// The files whose change lets a merge write its own audit: the audit
-// workflow, the audit and the filer. A merge that changed one is never
-// signed (security review 2, S3).
-export const AUDIT_CODE = Object.freeze([AUDIT_WORKFLOW, 'packages/atlas/door/lib/gate-audit.mjs', 'packages/atlas/door/lib/gate.mjs', 'packages/atlas/door/lib/jobs.mjs', 'packages/atlas/bin/atlas']);
 const AUDIT_ANY = /^atlas-job: gate-audit ([a-z-]+):([0-9a-f]{40})$/;
 
 // The owner keys that the done tool reads for one merge: the keys on its
@@ -274,6 +273,46 @@ function mergeKeys(deps, repo, parent, head) {
   return atParent.filter((key) => atFork.has(key.fingerprint));
 }
 
+// The owner keys for the act of one merge: the keys of mergeKeys, or, for a
+// merge made before the first owner key, the keys at the tip of the default
+// branch within the limits of preKeyKeys (item 65c6c907).
+async function ownerKeys(deps, repo, { parent, head, main }) {
+  const keys = mergeKeys(deps, repo, parent, head);
+  if (keys.length) return { keys };
+  const read = (path) => { try { return deps.gh('GET', path); } catch (error) { if (error?.status === 404 || /HTTP 404|Not Found/i.test(String(error?.message ?? ''))) return null; throw error; } };
+  let first;
+  try { first = await preKeyKeys(read, repo, { parent, branch: main }); } catch (error) { first = { why: `GitHub refused a read of the key file history (${plainText(error?.message ?? error).slice(0, 120)})` }; }
+  return first.keys ? { keys: first.keys, first_key: first.from } : { keys: [], why: first.why };
+}
+
+// Every audit issue of each merge, open or closed, by the kinds of its
+// findings.
+function auditKinds(deps, repo) {
+  const kinds = new Map();
+  for (let page = 1; page <= 10; page += 1) {
+    const rows = deps.gh('GET', `repos/${repo}/issues?state=all&labels=job:gate-audit&per_page=100&page=${page}`) ?? [];
+    for (const one of Array.isArray(rows) ? rows : []) {
+      const hit = AUDIT_ANY.exec(String(one?.title ?? ''));
+      if (hit) kinds.set(hit[2], new Set([...(kinds.get(hit[2]) ?? []), hit[1]]));
+    }
+    if (!Array.isArray(rows) || rows.length < 100) break;
+  }
+  return kinds;
+}
+
+// Why the audit run of a check is not a push run of the audit workflow on
+// the default branch at this merge commit, or null when it is (S3). It
+// answers the job too.
+function auditRunCause(deps, repo, { run, sha, main }) {
+  const job = deps.gh('GET', `repos/${repo}/actions/jobs/${run.id}`);
+  const workflow = job?.run_id ? deps.gh('GET', `repos/${repo}/actions/runs/${job.run_id}`) : null;
+  if (!workflow) return { cause: 'GitHub gave no workflow run for the audit check' };
+  if (workflow.path !== AUDIT_WORKFLOW || workflow.event !== 'push' || workflow.head_branch !== main || workflow.head_sha !== sha) {
+    return { cause: `the audit check is not from a push run of ${AUDIT_WORKFLOW} on ${main} at this merge` };
+  }
+  return { cause: null, job };
+}
+
 // Why the red audit run of one merge is not only "owner-unsigned" for this
 // pull request, or null when it is (security review S1). The run must be a
 // push run of the audit workflow on the default branch at this merge commit
@@ -281,12 +320,8 @@ function mergeKeys(deps, repo, parent, head) {
 // FINDINGS line: the state must be "found", not "broken", and each finding
 // must be owner-unsigned for this merge and this pull request.
 export function auditCause(deps, repo, { run, sha, pr, main }) {
-  const job = deps.gh('GET', `repos/${repo}/actions/jobs/${run.id}`);
-  const workflow = job?.run_id ? deps.gh('GET', `repos/${repo}/actions/runs/${job.run_id}`) : null;
-  if (!workflow) return 'GitHub gave no workflow run for the audit check';
-  if (workflow.path !== AUDIT_WORKFLOW || workflow.event !== 'push' || workflow.head_branch !== main || workflow.head_sha !== sha) {
-    return `the audit check is not from a push run of ${AUDIT_WORKFLOW} on ${main} at this merge`;
-  }
+  const { cause } = auditRunCause(deps, repo, { run, sha, main });
+  if (cause) return cause;
   let log = '';
   try { log = deps.text(`repos/${repo}/actions/jobs/${run.id}/logs`); } catch { return 'the log of the audit check cannot be read'; }
   const lines = String(log ?? '').split('\n').map((one) => one.replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z ?/, '').replace(/\r$/, ''));
@@ -324,21 +359,16 @@ export async function auditRow(deps, repo, issue, main, kinds = new Map()) {
   const commit = deps.gh('GET', `repos/${repo}/commits/${sha}`);
   const files = Array.isArray(commit?.files) ? commit.files.map((one) => String(one?.filename ?? '')) : null;
   if (!files) return { ...row, skip: 'GitHub gave no file list of the merge commit' };
-  const own = files.find((path) => AUDIT_CODE.includes(path));
-  if (own) return { ...row, skip: `the merge changed ${own}, so its audit ran its own code: sign it by hand` };
+  const code = auditCodeDiff(commit.files);
+  if (code.unknown) return { ...row, skip: 'GitHub gave no full file list of the merge commit' };
+  if (code.files.length) return { ...row, skip: `the merge changed ${code.files[0]}, so its audit ran its own code: read that diff and sign it with atlas approve audit-code ${row.pr}` };
   const parent = String(commit?.parents?.[0]?.sha ?? '');
   if (!/^[0-9a-f]{40}$/.test(parent)) return { ...row, skip: 'GitHub gave no parent of the merge commit' };
-  let keys = mergeKeys(deps, repo, parent, head);
   // Item 65c6c907: a merge made before the first owner key takes the keys
   // at the tip of the default branch, within the limits of preKeyKeys.
-  let first = null;
-  if (!keys.length) {
-    const read = (path) => { try { return deps.gh('GET', path); } catch (error) { if (error?.status === 404 || /HTTP 404|Not Found/i.test(String(error?.message ?? ''))) return null; throw error; } };
-    try { first = await preKeyKeys(read, repo, { parent, branch: main }); } catch (error) { first = { why: `GitHub refused a read of the key file history (${plainText(error?.message ?? error).slice(0, 120)})` }; }
-    if (first.keys) keys = first.keys;
-  }
-  if (!keys.length) return { ...row, skip: `${SIGNERS_FILE} on the base of this merge holds no owner key, so no act can count: close the issue by hand. No first key counts: ${first?.why ?? 'no reason'}` };
-  return { ...row, run: String(run.id), keys, ...(first?.from ? { first_key: first.from } : {}) };
+  const owner = await ownerKeys(deps, repo, { parent, head, main });
+  if (!owner.keys.length) return { ...row, skip: `${SIGNERS_FILE} on the base of this merge holds no owner key, so no act can count: close the issue by hand. No first key counts: ${owner.why ?? 'no reason'}` };
+  return { ...row, run: String(run.id), keys: owner.keys, ...(owner.first_key ? { first_key: owner.first_key } : {}) };
 }
 
 // `atlas approve audit [<pr>...]`. Exit 0 when each listed red got its act.
@@ -366,15 +396,7 @@ export async function approveAudit({ prs = [], repo, root, key, provider, yes =
   issues.sort((a, b) => Number(a.number) - Number(b.number));
   // Every audit issue of each merge, open or closed: an issue for another
   // finding of the same merge stops its row.
-  const kinds = new Map();
-  for (let page = 1; page <= 10; page += 1) {
-    const rows = deps.gh('GET', `repos/${name}/issues?state=all&labels=job:gate-audit&per_page=100&page=${page}`) ?? [];
-    for (const one of Array.isArray(rows) ? rows : []) {
-      const hit = AUDIT_ANY.exec(String(one?.title ?? ''));
-      if (hit) kinds.set(hit[2], new Set([...(kinds.get(hit[2]) ?? []), hit[1]]));
-    }
-    if (!Array.isArray(rows) || rows.length < 100) break;
-  }
+  const kinds = auditKinds(deps, name);
   line(`  ${issues.length} open audit issue(s) of an owner merge with no touch. Each one can take about 5 seconds.`);
   const rows = [];
   for (const issue of issues) {
@@ -437,11 +459,146 @@ export async function approveAudit({ prs = [], repo, root, key, provider, yes =
   return failed ? 1 : 0;
 }
 
+// ------------------------------------------------------- atlas approve audit-code
+
+// The owner's words for the audit-code red of one merge. The lead records
+// them, word for word, as one decision. They name the pull request as #N,
+// quote the test, and hold the time, as the words of approveAudit do.
+export function auditCodeWords({ pr, sha, files, check }, at) {
+  return `I read the ${AUDIT_CODE_TEST} diff of #${pr} (merge ${sha.slice(0, 7)}): ${files.join(', ')}. I accept its ${AUDIT_CODE_TEST} red of "${check}", listed at ${new Date(at).toISOString().slice(0, 16)}Z.`;
+}
+
+const PASSING = ['success', 'skipped', 'neutral'];
+const RED = ['failure', 'timed_out', 'cancelled', 'action_required', 'startup_failure'];
+
+// The audit of one merge commit with the code of this Mac's Atlas, not the
+// code of the merge. It needs the merge, its head and its parent in the clone
+// at `root`. Returns the findings.
+export function macAudit({ repo, root, sha }) {
+  // The clone must be a clone of this repo, or every commit reads as unread
+  // (security review 2, S2).
+  let origin = '';
+  try { origin = execFileSync('git', ['-C', root, 'remote', 'get-url', 'origin'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { origin = ''; }
+  if (!new RegExp(`^(https://|ssh://git@|git@)github\\.com[:/]${repo.replace(/[.]/g, '\\.')}(\\.git)?$`, 'i').test(origin)) throw new ApproveError(`${root} is not a clone of ${repo}; run the command in the clone`);
+  const found = [];
+  commitAudit({ repo, root, commit: sha, found }, () => {}, ghApi);
+  return found;
+}
+
+// `atlas approve audit-code <pr>` (item f36c6b0f). A merge that changed the
+// audit code ran its own audit, so the batch never signs it. The owner reads
+// the audit-code diff of that one merge here, and one touch signs one
+// accept-code act for its one red audit check. Exit 0 when the act is posted.
+export async function approveAuditCode({ prs = [], repo, root, key, provider, yes = false }, line, deps = DEPS) {
+  if (prs.length !== 1 || !/^[1-9][0-9]{0,8}$/.test(String(prs[0]))) throw new ApproveError('atlas approve audit-code takes one pull request number.');
+  const pr = Number(prs[0]);
+  const name = repoOf({ repo, root });
+  const main = String(deps.gh('GET', `repos/${name}`)?.default_branch ?? '');
+  if (!main) throw new ApproveError(`GitHub gave no default branch of ${name}.`);
+  const pull = deps.gh('GET', `repos/${name}/pulls/${pr}`);
+  const sha = String(pull?.merge_commit_sha ?? '');
+  const head = String(pull?.head?.sha ?? '');
+  if (!pull?.merged_at || !/^[0-9a-f]{40}$/.test(sha) || !/^[0-9a-f]{40}$/.test(head)) throw new ApproveError(`#${pr} is not a merged pull request with a merge commit.`);
+  if (pull.base?.ref !== main) throw new ApproveError(`#${pr} did not merge into ${main}; the push audit runs only there.`);
+  const commit = deps.gh('GET', `repos/${name}/commits/${sha}`);
+  const parent = String(commit?.parents?.[0]?.sha ?? '');
+  if (!/^[0-9a-f]{40}$/.test(parent)) throw new ApproveError('GitHub gave no parent of the merge commit.');
+  // Only a merge commit with two parents lists the whole change of the pull
+  // request against the main branch. A rebase merge lists only its last
+  // commit, so the diff could hide audit code (security review 2, S1).
+  if (!Array.isArray(commit.parents) || commit.parents.length !== 2) throw new ApproveError(`#${pr} did not merge with a merge commit, so its whole diff cannot be shown. Nothing was signed.`);
+  const code = auditCodeDiff(commit?.files);
+  if (code.unknown) throw new ApproveError('GitHub gave no full file list of the merge commit.');
+  if (!code.files.length) throw new ApproveError(`#${pr} changed no audit code. Use atlas approve audit.`);
+  const changed = commit.files.filter((one) => AUDIT_CODE.includes(String(one?.filename ?? '')) || AUDIT_CODE.includes(String(one?.previous_filename ?? '')));
+  const cut = changed.find((one) => typeof one.patch !== 'string' && one.status !== 'removed');
+  if (cut) throw new ApproveError(`GitHub gave no diff of ${plainText(cut.filename)}, so you cannot read it here. Nothing was signed.`);
+  // An audit issue for another finding of this merge stops the act: the
+  // touch accepts the audit-code red only (security review S3 of 0ca9fced).
+  const more = [...(auditKinds(deps, name).get(sha) ?? [])].filter((kind) => kind !== AUDIT_TEST);
+  if (more.length) throw new ApproveError(`another audit issue names this merge: ${more.join(', ')}. Nothing was signed.`);
+  // Every run of each audit check, not only the newest attempt.
+  const all = (deps.gh('GET', `repos/${name}/commits/${sha}/check-runs?filter=all&per_page=100`)?.check_runs ?? []).filter((run) => AUDIT_CHECKS.includes(run?.name));
+  const newest = AUDIT_CHECKS.map((check) => all.filter((run) => run.name === check).sort((a, b) => String(b.started_at ?? '').localeCompare(String(a.started_at ?? '')))[0]).filter(Boolean);
+  const open = newest.find((run) => run.status !== 'completed');
+  if (open) throw new ApproveError(`"${plainText(open.name)}" has not completed on the merge commit. Nothing was signed.`);
+  const red = newest.filter((run) => RED.includes(run.conclusion));
+  const odd = newest.find((run) => !RED.includes(run.conclusion) && !PASSING.includes(run.conclusion));
+  if (odd) throw new ApproveError(`"${plainText(odd.name)}" ended ${plainText(odd.conclusion)}. Nothing was signed.`);
+  if (red.length !== 1) throw new ApproveError(`the merge commit has ${red.length} red audit checks; this command accepts exactly one. Nothing was signed.`);
+  const run = red[0];
+  if (run.app?.id !== ACTIONS_APP_ID || !/^[1-9][0-9]{0,15}$/.test(String(run.id))) throw new ApproveError(`the red "${plainText(run.name)}" is not a GitHub Actions run.`);
+  const pinned = auditRunCause(deps, name, { run, sha, main });
+  if (pinned.cause) throw new ApproveError(`${pinned.cause}. Nothing was signed.`);
+  // The first parent was a main tip of its own push: its push audit ran at
+  // it. So the push of this merge brought this merge commit only, and no
+  // commit past the gate hides under it (security review 2, S1).
+  const before = (deps.gh('GET', `repos/${name}/commits/${parent}/check-runs?filter=all&per_page=100`)?.check_runs ?? [])
+    .filter((one) => AUDIT_CHECKS.includes(one?.name) && one.app?.id === ACTIONS_APP_ID && /^[1-9][0-9]{0,15}$/.test(String(one.id)));
+  if (!before.some((one) => !auditRunCause(deps, name, { run: one, sha: parent, main }).cause)) throw new ApproveError(`the parent ${parent.slice(0, 7)} has no push audit run of its own, so the push of #${pr} may hold more than its merge. Nothing was signed.`);
+  // A force push can put this merge on a parent that drops a later commit
+  // of the main branch. The repo may enforce no branch rule, so the command
+  // reads the force pushes of the branch (security review 3, S2).
+  const forced = deps.gh('GET', `repos/${name}/activity?ref=${encodeURIComponent(`refs/heads/${main}`)}&activity_type=force_push&per_page=100`);
+  if (!Array.isArray(forced)) throw new ApproveError(`GitHub gave no list of the force pushes to ${main}. Nothing was signed.`);
+  if (forced.some((one) => String(one?.after ?? '').toLowerCase() === sha)) throw new ApproveError(`a force push put the merge of #${pr} on ${main}. Nothing was signed.`);
+  // The audit of that run ran the code of this merge, or never ran. So the
+  // Atlas on this Mac audits the merge again with its own code (security
+  // review S2): it must find this owner merge and nothing else.
+  let found;
+  try { found = await (deps.audit ?? macAudit)({ repo: name, root: resolve(root ?? '.'), sha }); }
+  catch (error) { throw new ApproveError(`the audit on this Mac stopped: ${plainText(error?.message ?? error).slice(0, 200)}. Nothing was signed.`); }
+  if (Array.isArray(found) && found.some((one) => one?.pin === 'unread')) throw new ApproveError(`the audit on this Mac could not read the head or the base of #${pr} in this clone. Run git fetch origin pull/${pr}/head, then the command again. Nothing was signed.`);
+  const only = Array.isArray(found) && found.length === 1 && found[0]?.kind === AUDIT_TEST && found[0].sha === sha && Number(found[0].pr) === pr && found[0].key === `${AUDIT_TEST}:${sha}` && found[0].pin === undefined;
+  if (!only) throw new ApproveError(`the audit on this Mac found ${Array.isArray(found) && found.length ? found.map((one) => plainText(one?.key ?? one?.kind)).join(', ') : 'nothing to accept'}, not only ${AUDIT_TEST} for #${pr}. Nothing was signed.`);
+  const owner = await ownerKeys(deps, name, { parent, head, main });
+  if (!owner.keys.length) throw new ApproveError(`${SIGNERS_FILE} holds no owner key that counts for this merge: ${owner.why ?? 'no reason'}.`);
+  line(`atlas approve audit-code: ${name} #${pr} ${plainText(pull.title).slice(0, 120)}`);
+  line(`  merged ${plainText(pull.merged_at)} as ${sha}, head ${head.slice(0, 7)}`);
+  line(`  red: "${plainText(run.name)}" ${plainText(run.conclusion)}, run ${run.id}.`);
+  line(`  The audit on this Mac, with its own code, found only ${AUDIT_TEST} for #${pr}.`);
+  line(`  The merge changed ${commit.files.length} file(s): ${commit.files.map((one) => plainText(one?.filename)).join(', ')}`);
+  if (owner.first_key) line(`  merged before the first owner key: the act counts against the keys at the tip of ${main}, ${owner.first_key.slice(0, 7)}`);
+  line(`Read the audit-code diff of this merge before you touch (${changed.length} file(s)):`);
+  for (const one of changed) {
+    line(`--- ${plainText(one.previous_filename ? `${one.previous_filename} -> ` : '')}${plainText(one.filename)} (${plainText(one.status)})`);
+    for (const each of String(one.patch ?? '').split('\n')) line(`  ${plainText(each)}`);
+  }
+  const words = auditCodeWords({ pr, sha, files: code.files, check: run.name }, deps.now());
+  line('Your words, which the lead records as one decision:');
+  line(`  ${words}`);
+  if (!yes && !(await deps.ask(`You read this diff. Accept the ${AUDIT_CODE_TEST} red of #${pr} with one touch?`))) { line('Nothing signed.'); return 1; }
+  const setup = (deps.setup ?? signingSetup)({ key, provider });
+  const trusted = (deps.trusted ?? trustedKeys)(setup);
+  const strange = owner.keys.filter((one) => !trusted.has(one.fingerprint)).map((one) => one.fingerprint);
+  if (strange.length) {
+    line(`STOP: ${SIGNERS_FILE} holds a key that is not yours: ${strange.join(', ')}.`);
+    line('Nothing was signed. Remove that key in a pull request, or pin it in ~/.config/atlas/signing.json if it is yours.');
+    return 1;
+  }
+  const act = { kind: 'accept-code', repo: name, pr, head, merge: sha, run: String(run.id), diff: code.print, words: wordsFingerprint(words), check: run.name };
+  const payload = payloadText([act], deps.now());
+  line(`Touch the key now (${setup.key}${setup.provider ? `, provider ${setup.provider}` : ''}).`);
+  const signature = deps.sign(payload, setup);
+  const proof = verifyBlock({ payload, signature }, owner.keys);
+  if (proof.error) { line(`The signature does not count for #${pr}: ${proof.error}`); line('Nothing was posted.'); return 1; }
+  const text = `${blockText(payload, signature)}\nThe owner read the ${AUDIT_CODE_TEST} diff of #${pr} and accepts its red with \`atlas approve audit-code\`. His words:\n\n> ${words}\n`;
+  try { deps.gh('POST', `repos/${name}/issues/${pr}/comments`, { body: text }); }
+  catch (error) { line(`#${pr}: GitHub refused the write (${plainText(error?.message ?? error).slice(0, 200)}). Run the command again.`); return 1; }
+  line(`  posted on #${pr}`);
+  line('Now send this one message to the lead, word for word:');
+  line('');
+  line(words);
+  line('');
+  return 0;
+}
+
 // The act that `atlas approve act <kind>` builds from its flags.
 export function actFrom(kind, flags, read = (path) => readFileSync(resolve(path), 'utf8')) {
-  if (!Object.hasOwn(ACTS, kind ?? '')) throw new ApproveError(`there is no act "${kind ?? ''}". Use ${Object.keys(ACTS).filter((each) => each !== 'merge' && each !== 'accept').join(', ')}; a pull request takes atlas approve <pr>.`);
+  if (!Object.hasOwn(ACTS, kind ?? '')) throw new ApproveError(`there is no act "${kind ?? ''}". Use ${Object.keys(ACTS).filter((each) => !['merge', 'accept', 'accept-code'].includes(each)).join(', ')}; a pull request takes atlas approve <pr>.`);
   if (kind === 'merge') throw new ApproveError('a pull request takes atlas approve <pr>, which reads its gate first.');
   if (kind === 'accept') throw new ApproveError('an audit red takes atlas approve audit, which reads the audit issues first.');
+  if (kind === 'accept-code') throw new ApproveError('the audit red of an audit-code merge takes atlas approve audit-code <pr>, which shows its diff first.');
   const need = (flag) => {
     const value = flags[flag];
     if (value === undefined || value === true || value === '') throw new ApproveError(`atlas approve act ${kind} needs --${flag}.`);
@@ -513,6 +670,7 @@ export async function approveCommand({ words = [], repo, root, key, provider, ye
   const common = { key, provider, yes };
   try {
     if (words[0] === 'act') return await approveAct({ ...common, kind: words[1], flags, out }, line, deps);
+    if (words[0] === 'audit-code') return await approveAuditCode({ ...common, prs: words.slice(1), repo, root }, line, deps);
     if (words[0] === 'audit') return await approveAudit({ ...common, prs: words.slice(1), repo, root }, line, deps);
     if (words[0] === 'verify') return approveVerify({ file, signers, root }, line);
     if (words[0] === 'key-check') return await keyCheck(common, line, deps);

package/door/lib/design-build.mjs

@@ -40,7 +40,7 @@ export const TOKENS = Object.freeze({
 
 const tokenBlock = (index) => Object.entries(TOKENS).map(([name, pair]) => `--${name}:${pair[index]}`).join(';');
 
-const CSS = `
+export const CSS = `
 :root{${tokenBlock(0)};color-scheme:light;
 --wc-paper:var(--paper);--wc-ink:var(--ink);--wc-body:var(--body);--wc-muted:var(--muted);--wc-faint:var(--quiet);--wc-line:var(--line);--wc-line-strong:var(--line-strong);--wc-accent:var(--accent);--wc-accent-soft:var(--accent-bg);--wc-panel:var(--rail);--wc-card:var(--card);--wc-danger:var(--no);--wc-danger-soft:var(--accent-bg);
 --wc-serif:Lora,Georgia,serif;--wc-mono:'IBM Plex Mono',ui-monospace,Menlo,monospace;--wc-dur-fast:150ms;--wc-dur-base:220ms;--wc-dur-step:450ms;--wc-dur-draw:700ms;
@@ -138,7 +138,7 @@ kbd{border:1px solid var(--line-strong);border-radius:4px;padding:0 5px;font-fam
 @media print{body{overflow:visible}.app{display:block;height:auto}.rail,.bar.foot{display:none}#scroll{overflow:visible}.part[hidden]{display:flex}}
 `;
 
-const SCRIPT = `
+export const SCRIPT = `
 (function () {
   var data = JSON.parse(document.getElementById('design-data').textContent);
   var flat = [];
@@ -356,6 +356,7 @@ export function buildDesign(folder, { tracker = null, draft = false, registry =
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="atlas design build">
 <title>${esc(title)}</title>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Lora:ital,wght@0,500;0,600;1,500&family=Poppins:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap">
 <style>${CSS}</style>

package/door/lib/page.mjs

@@ -0,0 +1,242 @@
+// The explainer page builder, and the page rules of `atlas ste`.
+//
+// An explainer tells the owner how a technical flow works or where it
+// stands. Owner, 30 October 2026: "I would expect things to be explained
+// visually, the results are very disappointing, there is no theme in
+// pages" (lesson 8678a27b, item 99ccaa71). So one builder makes every
+// explainer, and the STE check refuses a page that skips it.
+//
+// `atlas page build <file or folder>` reads markdown: one file is one part,
+// a folder is one part for each .md file, in name order. The parts use the
+// blocks of the design renderer (markdown.mjs), with woodcut figures. The
+// page is the design page frame: a left rail, Back and Next, the arrow keys,
+// and a light and a dark theme from the design token set. The build refuses
+// a source with no woodcut figure, a figure woodcut cannot draw, or no
+// figure that walks: a scenario with two or more titled steps.
+//
+// The page rules read each HTML page that `atlas ste` reads:
+//   page-figure  the page draws no woodcut figure. A design page (its own
+//                check gates its pictures) and a project view page (a data
+//                view, not an explainer) are exempt, by their generator line.
+//   page-theme   a colour that is in no Atlas theme, or no dark theme.
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, readdirSync } from 'node:fs';
+import { join, dirname, basename, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CSS, SCRIPT, TOKENS, WOODCUT } from './design-build.mjs';
+import { frontMatter, woodcutFault, woodcutWalks } from './design.mjs';
+import { render, esc, slug, fenceOpens, fenceCloses, WOODCUT_TYPES } from './markdown.mjs';
+
+export const GENERATOR = 'atlas page build';
+// Builders whose pages answer to their own check, not to page-figure.
+export const FIGURE_EXEMPT = Object.freeze(['atlas design build', 'atlas view build']);
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// ------------------------------------------------------------- the build
+
+// The woodcut fences of one markdown body, with their line numbers.
+function woodcutFences(body, firstLine) {
+  const out = [];
+  let fence = null;
+  body.replace(/\r\n?/g, '\n').split('\n').forEach((text, index) => {
+    const line = firstLine + index;
+    if (fence) {
+      if (fenceCloses(text, fence.mark)) { if (fence.woodcut) out.push(fence); fence = null; } else fence.lines.push(text);
+      return;
+    }
+    const mark = fenceOpens(text);
+    if (!mark) return;
+    const [info, type] = text.trim().slice(mark.length).trim().split(/\s+/);
+    fence = { mark, woodcut: info === 'woodcut', type: type ?? null, line, lines: [] };
+  });
+  if (fence?.woodcut) out.push({ ...fence, open: true });
+  return out;
+}
+
+export function readSource(source) {
+  const root = resolve(source);
+  if (!existsSync(root)) throw new Error(`${source} does not exist`);
+  const folder = statSync(root).isDirectory();
+  const names = folder ? readdirSync(root).filter((name) => name.endsWith('.md')).sort() : [basename(root)];
+  if (!names.length) throw new Error(`${source} holds no .md file`);
+  const base = folder ? root : dirname(root);
+  return {
+    root,
+    name: basename(root).replace(/\.md$/, ''),
+    parts: names.map((file) => {
+      const { meta, body, bodyLine } = frontMatter(readFileSync(join(base, file), 'utf8'));
+      return { file, id: slug(file.replace(/\.md$/, '')) || 'part', title: typeof meta.title === 'string' ? meta.title : null, body, bodyLine };
+    }),
+  };
+}
+
+// The findings that stop a build. Each one names a file and a line.
+export function checkSource(source) {
+  const findings = [];
+  let figures = 0;
+  let walks = 0;
+  for (const part of source.parts) {
+    for (const fence of woodcutFences(part.body, part.bodyLine)) {
+      const at = { file: part.file, line: fence.line };
+      if (fence.open) { findings.push({ ...at, why: 'the woodcut block does not close' }); continue; }
+      if (!WOODCUT_TYPES[fence.type]) { findings.push({ ...at, why: `woodcut has no figure "${fence.type ?? ''}"; use ${Object.keys(WOODCUT_TYPES).join(', ')}` }); continue; }
+      let data;
+      try { data = JSON.parse(fence.lines.join('\n')); } catch (error) { findings.push({ ...at, why: `the woodcut data is not JSON: ${error.message}` }); continue; }
+      const fault = woodcutFault(fence.type, data);
+      if (fault) { findings.push({ ...at, why: fault }); continue; }
+      figures += 1;
+      if (woodcutWalks(data)) walks += 1;
+    }
+  }
+  const first = source.parts[0].file;
+  if (!figures && !findings.length) findings.push({ file: first, line: 1, why: 'the page has no woodcut figure. Explain the flow with a `woodcut wc-swimlane` (or another woodcut type) block, not prose alone' });
+  else if (!walks && !findings.length) findings.push({ file: first, line: 1, why: 'no figure walks the flow. Give one woodcut figure a scenario with two or more steps, each with a title' });
+  return { findings, figures, walks };
+}
+
+export function buildPage(path, { title = null } = {}) {
+  const source = readSource(path);
+  const { findings, figures, walks } = checkSource(source);
+  if (findings.length) return { html: null, findings, parts: source.parts.length, figures, walks };
+  const ids = new Set();
+  const byFile = new Map();
+  for (const part of source.parts) {
+    let id = part.id;
+    for (let n = 2; ids.has(id); n += 1) id = `${part.id}-${n}`;
+    ids.add(id);
+    part.id = id;
+    byFile.set(part.file, id);
+  }
+  const drawn = [];
+  const items = [];
+  const sections = source.parts.map((part) => {
+    const ctx = { file: part.file, page: part.id, figures: drawn, partOf: (href) => byFile.get(href.split('#')[0]) ?? null };
+    const out = render(part.body, ctx);
+    const heading = part.title ?? out.title ?? part.file.replace(/\.md$/, '');
+    items.push({ id: part.id, name: heading, ro: false });
+    return `<section class="part" data-part="${part.id}" id="part-${part.id}" hidden><h2>${esc(heading)}</h2>\n${out.html}\n</section>`;
+  });
+  const name = title ?? items[0].name;
+  const data = { groups: [{ id: 'pages', items }] };
+  const rail = `<div class="group"><button type="button" class="ghead" aria-expanded="true"><span class="chev">▾</span><span>Pages</span><span class="n">${items.length}</span></button>${items.map((item, index) => `<button type="button" class="item" data-go="${item.id}"><span class="n">${index + 1}</span><span>${esc(item.name)}</span></button>`).join('')}</div>`;
+  const mini = items.map((item, index) => `<button type="button" class="mini-item" data-go="${item.id}" title="${esc(item.name)}">${index + 1}</button>`).join('');
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="${GENERATOR}">
+<title>${esc(name)}</title>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Lora:ital,wght@0,500;0,600;1,500&family=Poppins:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap">
+<style>${CSS}</style>
+<noscript><style>body{overflow:auto}.app{display:block;height:auto}.rail,.bar.foot,.pos{display:none}#scroll{overflow:visible}.part[hidden]{display:flex;margin-bottom:40px}</style></noscript>
+</head>
+<body>
+<div class="app">
+<aside class="rail" id="rail" aria-label="Pages">
+<div class="full">
+<div class="railhead"><div class="kv"><span class="lbl">Explainer</span><b>${esc(name)}</b></div><button type="button" class="sq" data-rail aria-label="Fold the side rail" title="Fold">«</button></div>
+<div class="row"><button type="button" class="pill" id="open-all">Expand all</button><button type="button" class="pill" id="close-all">Collapse all</button></div>
+${rail}
+</div>
+<div class="strip"><button type="button" class="sq" data-rail aria-label="Open the side rail" title="Open" style="margin-bottom:10px">»</button>${mini}</div>
+</aside>
+<main>
+<div class="bar top"><nav class="inner"><b style="font-weight:500">${esc(name)}</b><span class="tag">EXPLAINER</span><button type="button" class="pill" id="theme" aria-label="Switch light or dark">☾ Dark</button></nav></div>
+<div id="scroll"><div class="inner">
+${name === items[0].name ? '' : `<header><h1>${esc(name)}</h1></header>\n`}<div class="pos" id="pos"></div>
+${sections.join('\n')}
+</div></div>
+<div class="bar foot"><div class="inner"><button type="button" class="nav" id="prev" aria-label="Previous page"></button><span class="mid"><span id="count"></span><span class="keys"> · <kbd>←</kbd> <kbd>→</kbd> to move</span></span><button type="button" class="nav" id="next" aria-label="Next page"></button></div></div>
+</main>
+</div>
+<script type="application/json" id="design-data">${JSON.stringify(data).replace(/<\//g, '<\\/')}</script>
+<script type="module" src="${WOODCUT}"></script>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`;
+  return { html, findings: [], parts: items.length, figures, walks };
+}
+
+export function writePage(path, out, options = {}) {
+  const result = buildPage(path, options);
+  if (!result.html) return result;
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, result.html);
+  return result;
+}
+
+// ------------------------------------------------------------- the page rules
+
+// One spelling for each colour: lower case, no spaces, #abc as #aabbcc.
+export function normalColour(value) {
+  const text = String(value).toLowerCase().replace(/\s+/g, '');
+  const short = /^#([0-9a-f])([0-9a-f])([0-9a-f])([0-9a-f])?$/.exec(text);
+  if (short) return `#${short.slice(1).filter(Boolean).map((one) => one + one).join('')}`;
+  return text;
+}
+
+const COLOUR = /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?)\([^)]*\)/g;
+// Named colours that a hand-made page uses most. A name is in no theme.
+const NAMED = /(?<![\w-])(red|green|blue|black|white|gray|grey|orange|yellow|purple|pink|brown|navy|teal|silver|gold|maroon|olive|lime|aqua|cyan|magenta|crimson|coral|salmon|tomato|indigo|violet|beige|ivory|khaki|lavender|tan|wheat)(?![\w-])/gi;
+// Black and white with an alpha only darken or lighten: a shadow, a scrim.
+const NEUTRAL = /^rgba\((0,0,0|255,255,255),[\d.]+\)$/;
+
+let palette = null;
+// The colours of the Atlas themes: the design token set (design and
+// explainer pages), the crew's page format, and the project view page.
+export function themePalette() {
+  if (palette) return palette;
+  const set = new Set(Object.values(TOKENS).flat().map(normalColour));
+  for (const file of [join(PACKAGE_ROOT, 'agents', 'artifact-format', 'system.css'), join(PACKAGE_ROOT, 'view', 'page.html')]) {
+    if (!existsSync(file)) continue;
+    for (const match of readFileSync(file, 'utf8').matchAll(COLOUR)) set.add(normalColour(match[0]));
+  }
+  palette = set;
+  return set;
+}
+
+const lineAt = (text, offset) => text.slice(0, offset).split('\n').length;
+
+// The places a page paints a colour: the values of its style blocks, its
+// style attributes, and its colour attributes. Each comes with its offset.
+function paintSpots(text) {
+  const spots = [];
+  for (const block of text.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)) {
+    const start = block.index + block[0].indexOf(block[1]);
+    for (const value of block[1].matchAll(/:([^;{}]+)/g)) spots.push({ at: start + value.index + 1, text: value[1] });
+  }
+  for (const attr of text.matchAll(/\s(style|fill|stroke|color|bgcolor|stop-color|flood-color)\s*=\s*("[^"]*"|'[^']*')/gi)) {
+    spots.push({ at: attr.index + attr[0].indexOf(attr[2]) + 1, text: attr[2].slice(1, -1) });
+  }
+  return spots;
+}
+
+const generatorOf = (text) => /<meta\s+name=["']generator["']\s+content=["']([^"']*)["']/i.exec(text)?.[1] ?? null;
+const DARK = /\[data-theme=["']?dark["']?\]|prefers-color-scheme:\s*dark/i;
+
+export function pageFindings(text) {
+  const findings = [];
+  const generator = generatorOf(text);
+  const types = Object.keys(WOODCUT_TYPES).join('|');
+  const element = new RegExp(`<(${types})\\b`, 'i').exec(text);
+  const loader = /<script\b[^>]*\bsrc=["'][^"']*woodcut[^"']*["']/i.test(text);
+  if (!FIGURE_EXEMPT.includes(generator)) {
+    if (!element) findings.push({ line: 1, rule: 'page-figure', why: 'the page draws no woodcut figure. Build an explainer with atlas page build, and walk the flow in a woodcut figure' });
+    else if (!loader) findings.push({ line: lineAt(text, element.index), rule: 'page-figure', why: `the page has a <${element[1]}> figure but loads no woodcut script, so it draws nothing` });
+  }
+  const spots = paintSpots(text);
+  if (spots.length && !DARK.test(text)) findings.push({ line: 1, rule: 'page-theme', why: 'the page has no dark theme. Build it with atlas page build, which carries both themes' });
+  const known = themePalette();
+  const seen = new Set();
+  for (const spot of spots) {
+    for (const match of [...spot.text.matchAll(COLOUR), ...spot.text.matchAll(NAMED)]) {
+      const colour = normalColour(match[0]);
+      if (known.has(colour) || NEUTRAL.test(colour) || seen.has(colour)) continue;
+      seen.add(colour);
+      findings.push({ line: lineAt(text, spot.at + match.index), rule: 'page-theme', why: `the colour ${match[0]} is in no Atlas theme. Paint with a theme token, such as var(--accent)` });
+    }
+  }
+  return findings;
+}

package/door/lib/signed-act.mjs

@@ -89,6 +89,11 @@ export const ACTS = Object.freeze({
   // S1). It names the fingerprint of the owner's words, not a decision id, so
   // one touch comes before the one message that the lead records.
   accept: { fields: ['repo', 'pr', 'head', 'run', 'words', 'check'], form: `(${REPO}) (${NUMBER}) (${SHA}) ([1-9][0-9]{0,15}) (${HASH}) ([^\\s].{0,99})` },
+  // The acceptance of the red audit check of one merge that changed the
+  // audit code, made with `atlas approve audit-code` after the owner read
+  // that diff (item f36c6b0f). It names the merge commit and the fingerprint
+  // of its audit-code change, so the touch covers only the diff he read.
+  'accept-code': { fields: ['repo', 'pr', 'head', 'merge', 'run', 'diff', 'words', 'check'], form: `(${REPO}) (${NUMBER}) (${SHA}) (${SHA}) ([1-9][0-9]{0,15}) (${HASH}) (${HASH}) ([^\\s].{0,99})` },
 });
 
 // The fingerprint that a lock or a decision act names: sha256 of the text,
@@ -105,6 +110,40 @@ export const AUDIT_TEST = 'owner-unsigned';
 // tests, so a release never turns it into a warning (item 9348568f).
 export const AUDIT_CHECKS = Object.freeze(['gate · push audit', AUDIT_CHECK]);
 
+// The files whose change lets a merge write its own audit: every repo file
+// of the gate and audit groups of GATE_FILE_GROUPS in gate-audit.mjs (a test
+// keeps this list a superset), the signed act that the gate reads, and the
+// job file of the audit. `atlas approve audit` never signs a merge that
+// changed one (security review 2 of item 0ca9fced, S3). Such a merge takes
+// an accept-code act instead, and its words quote the test AUDIT_CODE_TEST
+// (item f36c6b0f).
+export const AUDIT_WORKFLOW = '.github/workflows/atlas-gate-audit.yml';
+export const AUDIT_CODE = Object.freeze([
+  AUDIT_WORKFLOW, '.github/workflows/atlas-gate.yml', '.github/workflows/atlas-jobs.yml',
+  'packages/atlas/bin/atlas', 'packages/atlas/door/cli.mjs', 'packages/atlas/owner-only.yaml', 'packages/atlas/door/jobs/gate-audit.yaml',
+  ...['gate.mjs', 'gate-audit.mjs', 'gate-check.mjs', 'owner-only.mjs', 'jobs.mjs', 'issues.mjs', 'signed-act.mjs'].map((name) => `packages/atlas/door/lib/${name}`),
+  'packages/atlas/shape/check.mjs', 'packages/atlas/work/lib/child-env.mjs',
+]);
+export const AUDIT_CODE_TEST = 'audit-code';
+// GitHub lists at most 300 files of one commit.
+const COMMIT_FILES = 300;
+
+// The audit-code change of one merge commit, from GitHub's file list of that
+// commit: { files, print }, where print is the fingerprint of each changed
+// audit-code file with its state and its blob, or { files: [] } for none. A
+// rename counts by its old name too. A list that is missing or may be cut
+// gives { unknown: true }.
+export function auditCodeDiff(files) {
+  if (!Array.isArray(files) || files.length >= COMMIT_FILES) return { unknown: true };
+  const hits = files.filter((one) => AUDIT_CODE.includes(String(one?.filename ?? '')) || AUDIT_CODE.includes(String(one?.previous_filename ?? '')));
+  if (!hits.length) return { files: [] };
+  const rows = hits.map((one) => `${one.previous_filename ? `${one.previous_filename}>` : ''}${one.filename} ${one.status} ${one.sha ?? '-'}`).sort();
+  // Each file by its name in AUDIT_CODE, never by a new name that a rename
+  // chose, so the words and the refusals hold only names of the list.
+  const named = hits.map((one) => (AUDIT_CODE.includes(String(one.filename)) ? String(one.filename) : String(one.previous_filename)));
+  return { files: [...new Set(named)].sort(), print: fingerprint(rows.join('\n')) };
+}
+
 // The fingerprint that an accept act names: the owner's words with each run
 // of white space made one space, and no space at the ends. A chat can wrap a
 // line or drop a last line end; that does not change the words.

package/door/lib/ste.mjs

@@ -9,11 +9,15 @@
 //
 // `--share` adds the privacy filter, with no exemption for quotes: a quoted
 // email address still leaves with the page.
+//
+// An HTML page also meets the page rules of page.mjs: it draws a woodcut
+// figure, and it paints only with the colours of an Atlas theme.
 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';
+import { pageFindings } from './page.mjs';
 
 export const LIMITS = Object.freeze({ step: 20, sentence: 25, paragraph: 6 });
 
@@ -181,8 +185,9 @@ export function pagesUnder(path) {
   return out;
 }
 
-export function checkText(text, { html = false, share = false, terms = [] } = {}) {
+export function checkText(text, { html = false, page = false, share = false, terms = [] } = {}) {
   const findings = measure(html ? htmlUnits(text) : markdownUnits(text));
+  if (page) findings.push(...pageFindings(text));
   if (share) findings.push(...privacyFindings(text, { terms }).map((finding) => ({ ...finding, rule: `privacy:${finding.rule}` })));
   return findings.sort((a, b) => a.line - b.line);
 }
@@ -193,7 +198,7 @@ export function checkPaths(paths, { share = false, terms = null, base = process.
   for (const path of paths) {
     for (const file of pagesUnder(path)) {
       const html = /\.html?$/i.test(file);
-      const findings = checkText(readFileSync(file, 'utf8'), { html, share, terms: own });
+      const findings = checkText(readFileSync(file, 'utf8'), { html, page: html, share, terms: own });
       results.push({ file: relative(base, file) || file, findings });
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.46",
+  "version": "0.4.48",
   "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

@@ -33,9 +33,20 @@ Follow all eleven in every reply, page and question.
 9. Link every explainer page from the document it explains.
 10. Pick the form that is easiest to understand. Put a diagram before
     prose, and a page before long chat text. Where motion explains a
-    sequence, animate the diagram in the page.
+    sequence, animate the diagram in the page. Explain each technical
+    flow on a page from `atlas page build <file or folder>`:
+    - A flow is how a thing works, the steps of a process, or where a
+      product stands.
+    - The page holds markdown and a woodcut figure that the owner steps
+      through, such as a `woodcut wc-swimlane` block.
+    - Never make an explainer page by hand. Never explain a flow in chat
+      text alone.
+    - The owner, 30 October 2026: "I would expect things to be explained
+      visually".
 11. Write in ASD-STE100. Run `atlas ste` on each page before you publish
-    it, and fix what it flags by hand. Quoted words are exempt.
+    it, and fix what it flags by hand. Quoted words are exempt. On an
+    HTML page, it also flags no woodcut figure, no dark theme, and a
+    colour in no Atlas theme.
 
 Before a page or an issue goes to anyone other than the owner, run
 `atlas ste --share` on it. That adds the privacy filter. It reads the
@@ -55,7 +66,8 @@ say that when you hand over a page.
 | Where a capability stands in the code | The `atlas:capability-reader` crew |
 | Review a design or a diff | The three reviewer crews, as sdlc-task says |
 | Prove a pull request against its definition of done | The `atlas:verifier` crew |
-| Render a page for the owner | The `atlas:artifact-renderer` crew |
+| Explain a technical flow or a status to the owner | The lead, with `atlas page build <file or folder>` (talk rule 10) |
+| Render a design, a PRD or a review page for the owner | The `atlas:artifact-renderer` crew |
 | Run the fresh-agent test at the end of onboarding: pick, run and grade three tasks | The `atlas:fresh-agent-test` skill, which sends the `atlas:judge` crew |
 | Onboard an area to tests, review scenario words, write or convert a test, sort a red test, plant faults | The `atlas:tests` skill |
 
@@ -110,11 +122,12 @@ 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. `kept` runs the kept tests of a path 1 area and writes their evidence. `proof`, `verdict`, `named`, `covers` and `rerun` read the results of a run. `changed`, `before` and `after` run the test checks of the gate: changed tests, new cases fail on old code, old cases pass on new code. `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 page` | `build <file or folder>` makes an explainer page, as talk rule 10 says. It refuses markdown with no woodcut figure that walks. Run `atlas ste` on the page, then publish it |
 | `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 |
 | `atlas jobs` | The `atlas-jobs` workflow calls `check`, then `file`, once a day. A session calls it only to see what the watcher would file: `check`, then `file --dry-run` |
 | `atlas upkeep` | `check` before you ask for a merge. It reads the docs index, dead doc links, the code each doc names and stale pages. In a pull request it also reads the tracker item, the changed designs, and STE on the changed lines. The daily upkeep run calls it on the main branch. `replay` before the doc-sources rule changes how it gates. `procedures` runs the procedure steps tagged `atlas-run`; CI runs it with `--base` on each pull request |
 | `atlas gate` | `apply` once per repo, by the owner on his Mac, after the repo's `required_checks` exist. `--dry-run` first. `--off` and `--on` are the break glass. On a plan with no rulesets it reports advisory mode. `ready` before each merge, `check` in the `atlas-gate` workflow, `replay` before a change to the owner-only list. `audit` in the daily upkeep run, and with `--commit` in the push job of a repo that has one |
-| `atlas approve` | Never from a session. Only the owner runs it, on his Mac, with his key's touch. When the gate says "owner" for a pull request, ask him once for the signed act: name each pull request, its class and its cause. Put the owner pull requests of one day in one ask, so one touch signs them. `act`, `verify` and `key-check` work the same way. Each morning with open audit issues, ask him for `audit`; record its printed words as one decision for `item_done`, then close each issue |
+| `atlas approve` | Never from a session. Only the owner runs it, on his Mac, with his key's touch. When the gate says "owner" for a pull request, ask him once for the signed act: name each pull request, its class and its cause. Put the owner pull requests of one day in one ask, so one touch signs them. `act`, `verify` and `key-check` work the same way. Each morning with open audit issues, ask him for `audit`, and `audit-code <pr>` per audit-code merge; record its words as one decision, then close each issue |
 | `atlas judge` | In the fresh-agent test only, as the `atlas:fresh-agent-test` skill says. `seal` after the pick, `brief` to read a sealed ask, `run` for each sealed task, `check` after the grade |
 
 A person merges every file that `atlas tooling` writes.

package/view/page.html

@@ -3,6 +3,7 @@
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="generator" content="atlas view build">
 <title>@@TITLE@@</title>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600&amp;family=IBM+Plex+Mono:wght@400;500&amp;family=Source+Serif+4:opsz,wght@8..60,600&amp;display=swap">
 <style>

package/work/lib/delivery.mjs

@@ -16,7 +16,7 @@ import { refuse, text, isoDate, url, stringList, sha256, repoKinds, LIVE_KINDS }
 import { oneLine, ROW_LINE_MAX, priorityOrderOf, byPriority, orderNote, waitsOnLine, blockersOf, blocksOf, blockedPhrase, waitsShown } from './questions.mjs';
 import { parseYaml } from '../../shape/check.mjs';
 import { ACTIONS_APP_ID } from '../../door/lib/gate.mjs';
-import { MARKER as SIGNED_MARKER, SIGNERS_FILE, parseSigners, verifyTexts, findAct, wordsFingerprint, AUDIT_CHECK, AUDIT_CHECKS, AUDIT_TEST, preKeyKeys } from '../../door/lib/signed-act.mjs';
+import { MARKER as SIGNED_MARKER, SIGNERS_FILE, parseSigners, verifyTexts, findAct, wordsFingerprint, AUDIT_CHECK, AUDIT_CHECKS, AUDIT_TEST, AUDIT_CODE_TEST, auditCodeDiff, preKeyKeys } from '../../door/lib/signed-act.mjs';
 
 export const DELIVERY_WRITE_VERBS = Object.freeze(['item_done', 'item_reopen']);
 export const DELIVERY_READ_VERBS = Object.freeze(['in_flight']);
@@ -467,8 +467,22 @@ export function createDeliveryVerbs(core) {
     // act for the push audit red may count, against the keys at the tip of
     // the default branch (preKeyKeys in signed-act.mjs holds the limits). The
     // audit runs only on the default branch, so the merge must be into it.
+    // Item f36c6b0f: the red audit check of a merge that changed the audit
+    // code takes only an accept-code act, which names the merge and the
+    // fingerprint of its audit-code change. An accept act never takes such
+    // a merge: the batch of atlas approve audit does not show its diff.
+    const auditRed = check === AUDIT_CHECK && testName === AUDIT_TEST;
+    const codeRed = AUDIT_CHECKS.includes(check) && testName === AUDIT_CODE_TEST;
+    let code = null;
+    if (auditRed || codeRed) {
+      code = auditCodeDiff(commit?.files);
+      if (code.unknown) refuse(`GitHub gave no full file list of the merge commit of ${pull.url}, so no accept act can be checked`);
+      if (auditRed && code.files.length) refuse(`${pull.url} changed the audit code (${code.files.join(', ')}), so an accept act does not count; the owner reads that diff and signs with atlas approve audit-code ${pull.number}, and the test is "${AUDIT_CODE_TEST}"`);
+      if (codeRed && (!Array.isArray(commit?.parents) || commit.parents.length !== 2)) refuse(`${pull.url} did not merge with a merge commit, so its audit-code diff is not its whole change; an accept-code act does not count`);
+      if (codeRed && !code.files.length) refuse(`${pull.url} changed no audit code, so the test "${AUDIT_CODE_TEST}" does not apply; the owner signs with atlas approve audit`);
+    }
     let prekey = null;
-    if (!keys.length && check === AUDIT_CHECK && testName === AUDIT_TEST) {
+    if (!keys.length && (auditRed || codeRed)) {
       const main = (await github(`repos/${pull.repo}`))?.default_branch;
       prekey = typeof main === 'string' && main === pull.base
         ? await preKeyKeys(githubOrNull, pull.repo, { parent, branch: main })
@@ -491,9 +505,11 @@ export function createDeliveryVerbs(core) {
     // cannot carry the touch to items the owner never named (review S2). The
     // words hold the time of the list, and a decision in any state counts,
     // so a replaced decision cannot hand the touch on (review 2, S3).
-    if (!found && words.trim() && check === AUDIT_CHECK && testName === AUDIT_TEST) {
+    if (!found && words.trim() && (auditRed || codeRed)) {
       const print = wordsFingerprint(words);
-      found = findAct(verified, { kind: 'accept', repo: pull.repo, pr: pull.number, head, words: print, check });
+      found = auditRed
+        ? findAct(verified, { kind: 'accept', repo: pull.repo, pr: pull.number, head, words: print, check })
+        : findAct(verified, { kind: 'accept-code', repo: pull.repo, pr: pull.number, head, merge: String(pull.merge_commit_sha).toLowerCase(), diff: code.print, words: print, check });
       if (found) {
         const same = decisions.filter((row) => typeof row.fields?.text === 'string' && wordsFingerprint(row.fields.text) === print);
         if (same.length !== 1 || same[0].id !== decisionId) refuse(`the accept act on ${pull.url} matches the words of ${same.length} decisions; exactly one decision, in any state, may hold the words the owner signed`);
@@ -501,9 +517,9 @@ export function createDeliveryVerbs(core) {
     }
     if (!found) {
       const why = verified.find((row) => row.error)?.error;
-      refuse(`accepted_red needs the owner's signed waiver on ${pull.url} for check ${check}, head ${head.slice(0, 12)} and decision ${decisionId}; none counts${why ? ` (a block was refused: ${why})` : ''}. The owner runs: atlas approve act waiver, and posts the block on the pull request; or, for an audit red, atlas approve audit, and the decision holds the words it printed`);
+      refuse(`accepted_red needs the owner's signed waiver on ${pull.url} for check ${check}, head ${head.slice(0, 12)} and decision ${decisionId}; none counts${why ? ` (a block was refused: ${why})` : ''}. The owner runs: atlas approve act waiver, and posts the block on the pull request; or, for an audit red, atlas approve audit (atlas approve audit-code <pr> for a merge that changed the audit code), and the decision holds the words it printed`);
     }
-    return { key: found.key, signed_at: found.signed_at, act: found.act.kind, ...(found.act.kind === 'accept' ? { run: String(found.act.run) } : {}), ...(prekey?.from ? { first_key: prekey.from } : {}) };
+    return { key: found.key, signed_at: found.signed_at, act: found.act.kind, ...(['accept', 'accept-code'].includes(found.act.kind) ? { run: String(found.act.run) } : {}), ...(prekey?.from ? { first_key: prekey.from } : {}) };
   }
 
   async function acceptedRed(value, pulls, item) {