dev-loops 0.6.0 → 0.7.1

package/scripts/loop/steer-loop.mjs

@@ -34,6 +34,7 @@ import {
 import { formatCliError } from "../_core-helpers.mjs";
 import { requireTokenValue as readSharedTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const SUBMIT_USAGE = `Usage:
   steer-loop.mjs submit --repo <owner/name> --pr <number>
     --kind stop_at_next_safe_gate --directive <text> --seq <n>
@@ -61,7 +62,9 @@ Optional:
 Output (stdout, JSON):
   { "ok": true, "acknowledgement": { ... }, "result": { ... }, "steeringState": { ... } }
 Error output (stderr, JSON):
-  { "ok": false, "error": "...", "usage": "..." }`.trim();
+  { "ok": false, "error": "...", "usage": "..." }
+
+${JQ_OUTPUT_USAGE}`.trim();
 const STATUS_USAGE = `Usage:
   steer-loop.mjs status --run-id <id> [--state-file <path>]
   steer-loop.mjs status --repo <owner/name> --pr <number> [--state-file <path>]
@@ -75,7 +78,9 @@ Optional:
 Output (stdout, JSON):
   { "ok": true, "status": { ... } }
 Error output (stderr, JSON):
-  { "ok": false, "error": "...", "usage": "..." }`.trim();
+  { "ok": false, "error": "...", "usage": "..." }
+
+${JQ_OUTPUT_USAGE}`.trim();
 const PROMOTE_USAGE = `Usage:
   steer-loop.mjs promote --run-id <id> --loop-state <state> [--state-file <path>]
   steer-loop.mjs promote --repo <owner/name> --pr <number>
@@ -93,7 +98,9 @@ Optional:
 Output (stdout, JSON):
   { "ok": true, "promotedCount": <n>, "promoted": [ ... ], "steeringState": { ... } }
 Error output (stderr, JSON):
-  { "ok": false, "error": "...", "usage": "..." }`.trim();
+  { "ok": false, "error": "...", "usage": "..." }
+
+${JQ_OUTPUT_USAGE}`.trim();
 const TOP_USAGE = `Usage:
   steer-loop.mjs <subcommand> [options]
 Subcommands:
@@ -171,6 +178,7 @@ export function parseSubmitCliArgs(argv) {
       "event-id": { type: "string" },
       "copilot-input": { type: "string" },
       "reviewer-input": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -250,6 +258,7 @@ export function parseSubmitCliArgs(argv) {
       options.reviewerInputPath = readRequiredOptionValue(token, SUBMIT_USAGE);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => readRequiredOptionValue(t, SUBMIT_USAGE))) continue;
     throw usageError(`Unknown argument: ${token.rawName}`, SUBMIT_USAGE);
   }
   if (!options.help) {
@@ -290,6 +299,7 @@ export function parseStatusCliArgs(argv) {
       repo: { type: "string" },
       pr: { type: "string" },
       "state-file": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -324,6 +334,7 @@ export function parseStatusCliArgs(argv) {
       options.stateFile = readRequiredOptionValue(token, STATUS_USAGE);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => readRequiredOptionValue(t, STATUS_USAGE))) continue;
     throw usageError(`Unknown argument: ${token.rawName}`, STATUS_USAGE);
   }
   if (!options.help) {
@@ -357,6 +368,7 @@ export function parsePromoteCliArgs(argv) {
       pr: { type: "string" },
       "state-file": { type: "string" },
       "loop-state": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -399,6 +411,7 @@ export function parsePromoteCliArgs(argv) {
       options.loopState = val;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => readRequiredOptionValue(t, PROMOTE_USAGE))) continue;
     throw usageError(`Unknown argument: ${token.rawName}`, PROMOTE_USAGE);
   }
   if (!options.help) {
@@ -651,7 +664,7 @@ function rejectUnsteerableInspection(inspection, { runId, eventId, seq, directiv
 }
 export async function runSubmit(
   argv = [],
-  { stdout = process.stdout, cwd = process.cwd(), env = process.env, ghCommand = "gh" } = {},
+  { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd(), env = process.env, ghCommand = "gh" } = {},
 ) {
   const options = parseSubmitCliArgs(argv);
   if (options.help) {
@@ -793,12 +806,12 @@ export async function runSubmit(
     } catch {
       steeringState = createSteeringState(runId, target);
     }
-    stdout.write(`${JSON.stringify({
+    process.exitCode = emitResult({
       ok: true,
       acknowledgement: validationRejection.acknowledgement,
       result: validationRejection.result,
       steeringState,
-    })}\n`);
+    }, { jq: options.jq, silent: options.silent, stdout, stderr });
     return;
   }
   const { steeringState: newState, result } = await withStateFileLock(stateFilePath, async () => {
@@ -828,9 +841,9 @@ export async function runSubmit(
     safePointCategory,
     readbackPath,
   });
-  stdout.write(`${JSON.stringify({ ok: true, acknowledgement, result, steeringState: newState })}\n`);
+  process.exitCode = emitResult({ ok: true, acknowledgement, result, steeringState: newState }, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
-export async function runStatus(argv = [], { stdout = process.stdout, cwd = process.cwd() } = {}) {
+export async function runStatus(argv = [], { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd() } = {}) {
   const options = parseStatusCliArgs(argv);
   if (options.help) {
     stdout.write(`${STATUS_USAGE}\n`);
@@ -843,9 +856,9 @@ export async function runStatus(argv = [], { stdout = process.stdout, cwd = proc
   const stateFilePath = options.stateFile ?? (target ? defaultStateFilePathForTarget(target, cwd) : defaultStateFilePath(runId, cwd));
   const steeringState = await loadOrCreateSteeringState(stateFilePath, runId, target);
   const status = getSteeringStatus(steeringState);
-  stdout.write(`${JSON.stringify({ ok: true, status })}\n`);
+  process.exitCode = emitResult({ ok: true, status }, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
-export async function runPromote(argv = [], { stdout = process.stdout, cwd = process.cwd() } = {}) {
+export async function runPromote(argv = [], { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd() } = {}) {
   const options = parsePromoteCliArgs(argv);
   if (options.help) {
     stdout.write(`${PROMOTE_USAGE}\n`);
@@ -864,16 +877,16 @@ export async function runPromote(argv = [], { stdout = process.stdout, cwd = pro
     }
     return nextState;
   });
-  stdout.write(`${JSON.stringify({
+  process.exitCode = emitResult({
     ok: true,
     promotedCount: promotedState.promoted.length,
     promoted: promotedState.promoted,
     steeringState: promotedState.steeringState,
-  })}\n`);
+  }, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 export async function runCli(
   argv = process.argv.slice(2),
-  { stdout = process.stdout, cwd = process.cwd(), env = process.env, ghCommand = "gh" } = {},
+  { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd(), env = process.env, ghCommand = "gh" } = {},
 ) {
   const [subcommand, ...rest] = argv;
   if (!subcommand || subcommand === "--help" || subcommand === "-h") {
@@ -881,13 +894,13 @@ export async function runCli(
     return;
   }
   if (subcommand === "submit") {
-    return runSubmit(rest, { stdout, cwd, env, ghCommand });
+    return runSubmit(rest, { stdout, stderr, cwd, env, ghCommand });
   }
   if (subcommand === "promote") {
-    return runPromote(rest, { stdout, cwd });
+    return runPromote(rest, { stdout, stderr, cwd });
   }
   if (subcommand === "status") {
-    return runStatus(rest, { stdout, cwd });
+    return runStatus(rest, { stdout, stderr, cwd });
   }
   const error = usageError(`Unknown subcommand: ${subcommand}`, TOP_USAGE);
   throw error;

package/scripts/loop/validate-pr-body-spec.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * Validate that a PR body carries the invariants required to serve as the
+ * lightweight spec-of-record (issue #1025): Objective/why, in-scope, explicit
+ * non-goals, testable Acceptance criteria, Definition of done, and Open
+ * questions/risks.
+ *
+ * Thin CLI wrapper (parallel to detect-issue-refinement-artifact.mjs): fetches
+ * the PR body via `gh pr view <n> --json body` and runs the shared pure
+ * validator `validatePrBodySpec` (reuses issue-refinement-artifact markdown
+ * logic — no parallel validator). Fails closed (non-zero + per-section reason)
+ * when any invariant is missing.
+ */
+import { readFile } from "node:fs/promises";
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
+import { validatePrBodySpec } from "@dev-loops/core/loop/issue-refinement-artifact";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+
+const USAGE = `Usage:
+  validate-pr-body-spec.mjs --repo <owner/name> --pr <number> [--expected-issue <n>]
+  validate-pr-body-spec.mjs --input <path> [--expected-issue <n>]
+Validate that a PR body carries the lightweight spec-of-record invariants
+(Objective/why, In scope, Explicit non-goals, testable Acceptance criteria,
+Definition of done, Open questions/risks, and a GitHub closing-keyword issue
+reference such as \`Closes #123\`).
+Required (exactly one):
+  --repo <owner/name> --pr <number>   Fetch the PR body via gh and validate it
+  --input <path>                      Path to a JSON file with { "body": "..." }
+                                      (optional "repo" and "pr" fields are echoed
+                                      back in the result when present)
+Optional:
+  --expected-issue <n>                Positive integer; the referenced closing
+                                      issue(s) must include this number, else
+                                      "closes_wrong_issue".
+Success output (stdout, JSON):
+  {
+    "ok": true | false,
+    "checker": "validate-pr-body-spec",
+    "repo": "owner/name" | null,
+    "pr": 123 | null,
+    "errors": [ { "code": "missing_...", "message": "..." } ],
+    "sections": [...],
+    "acItems": [...],
+    "dodItems": [...],
+    "closesIssues": [...]
+  }
+Exit: 0 when every invariant is present; 1 (fail closed) when any is missing.
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage": "..." }
+${JQ_OUTPUT_USAGE}`.trim();
+
+const parseError = buildParseError(USAGE);
+
+export function parseValidatePrBodySpecCliArgs(argv) {
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    input: undefined,
+    expectedIssue: undefined,
+  };
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      input: { type: "string" },
+      "expected-issue": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
+      continue;
+    }
+    if (token.name === "pr") {
+      const value = requireTokenValue(token, parseError);
+      if (!/^\d+$/.test(value) || Number(value) === 0) {
+        throw parseError("--pr must be a positive integer");
+      }
+      options.pr = Number(value);
+      continue;
+    }
+    if (token.name === "input") {
+      options.input = requireTokenValue(token, parseError).trim();
+      continue;
+    }
+    if (token.name === "expected-issue") {
+      const value = requireTokenValue(token, parseError);
+      if (!/^\d+$/.test(value) || Number(value) === 0) {
+        throw parseError("--expected-issue must be a positive integer");
+      }
+      options.expectedIssue = Number(value);
+      continue;
+    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (options.help) {
+    return options;
+  }
+  const hasInput = typeof options.input === "string" && options.input.length > 0;
+  const hasAnyRemote = (typeof options.repo === "string" && options.repo.length > 0) || Number.isInteger(options.pr);
+  const hasRemotePair = typeof options.repo === "string" && options.repo.length > 0 && Number.isInteger(options.pr);
+  // --input and the remote mode are mutually exclusive input sources: a stray
+  // --repo/--pr alongside --input must fail closed, not be silently ignored.
+  if (hasInput && hasAnyRemote) {
+    throw parseError("--input is mutually exclusive with --repo/--pr; provide exactly one input mode");
+  }
+  if (hasInput === hasRemotePair) {
+    throw parseError("Provide exactly one of --input <path> or --repo <owner/name> --pr <number>");
+  }
+  return options;
+}
+
+async function fetchPrBody({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+  const result = await runChild(
+    ghCommand,
+    ["pr", "view", String(pr), "--repo", repo, "--json", "body"],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh command failed: ${detail}`);
+  }
+  const payload = parseJsonText(result.stdout, { label: "gh pr view" });
+  if (!payload || typeof payload !== "object") {
+    throw new Error("Invalid gh pr view payload: missing body");
+  }
+  return typeof payload.body === "string" ? payload.body : "";
+}
+
+async function loadInputPayload(inputPath) {
+  const text = await readFile(inputPath, "utf8");
+  const payload = parseJsonText(text, { label: `input file ${inputPath}` });
+  if (!payload || typeof payload !== "object") {
+    throw new Error(`Input file ${inputPath} must be a JSON object`);
+  }
+  return payload;
+}
+
+export async function validatePrBodySpecFromOptions(options, { env = process.env, ghCommand = "gh" } = {}) {
+  if (typeof options.input === "string" && options.input.length > 0) {
+    const payload = await loadInputPayload(options.input);
+    const body = typeof payload.body === "string" ? payload.body : "";
+    const repo = typeof payload.repo === "string" ? payload.repo : options.repo ?? null;
+    const pr = Number.isInteger(payload.pr) ? payload.pr : options.pr ?? null;
+    return { ...validatePrBodySpec({ body, expectedIssue: options.expectedIssue ?? null }), repo, pr };
+  }
+  parseRepoSlug(options.repo);
+  const body = await fetchPrBody({ repo: options.repo, pr: options.pr }, { env, ghCommand });
+  return {
+    ...validatePrBodySpec({ body, expectedIssue: options.expectedIssue ?? null }),
+    repo: options.repo,
+    pr: options.pr,
+  };
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh" } = {},
+) {
+  let options;
+  try {
+    options = parseValidatePrBodySpecCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error, { usage: USAGE })}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  try {
+    const result = await validatePrBodySpecFromOptions(options, { env, ghCommand });
+    // Fail closed: a body missing any invariant maps result.ok=false to exit 1.
+    return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  const code = await runCli();
+  if (code !== 0) {
+    process.exitCode = code;
+  }
+}

package/scripts/loop/watch-initial-copilot-pr.mjs

@@ -5,6 +5,7 @@ import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { parseIssueNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 import { detectInitialCopilotPrState, LINKED_PR_STATE } from "./detect-initial-copilot-pr-state.mjs";
 import { enforcePersistentInternalWaitTimeout } from "@dev-loops/core/loop/timeout-policy";
 import {
@@ -45,9 +46,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
     { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success (ready_for_followup, timed_out, and prior_linked_pr_closed_unmerged are all ok:true)
-  1  Argument error or gh failure`.trim();
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 function rejectRemovedFlag(token) {
   throw parseError(
@@ -108,6 +111,7 @@ export function parseWatchInitialCopilotPrCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
       issue: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -135,6 +139,7 @@ export function parseWatchInitialCopilotPrCliArgs(argv) {
       options.issue = parseIssueNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.issue === undefined) {
@@ -251,7 +256,7 @@ export async function watchInitialCopilotPr(
 }
 export async function runCli(
   argv = process.argv.slice(2),
-  { stdout = process.stdout, env = process.env, ghCommand = "gh" } = {},
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh" } = {},
 ) {
   const options = parseWatchInitialCopilotPrCliArgs(argv);
   if (options.help) {
@@ -259,7 +264,7 @@ export async function runCli(
     return;
   }
   const result = await watchInitialCopilotPr(options, { env, ghCommand });
-  stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {

package/scripts/pages/build-site.mjs

@@ -8,6 +8,7 @@
 import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve, parse as parsePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { buildStateAtlasHtml } from './build-state-atlas.mjs';
 
 const REPO_ROOT_DEFAULT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
@@ -46,27 +47,59 @@ export const DECKS = [
 // Resolve a deck's published filename: distinct outFile when set, else file.
 const deckOut = (deck) => deck.outFile ?? deck.file;
 
+// The State atlas: a generated page (site/state-atlas.html) rendering every
+// dev-loops state machine as mermaid diagrams straight from the code's tables.
+export const STATE_ATLAS = { file: 'state-atlas.html', label: 'State atlas' };
+
 // The other resources linked from the navigation, in order.
 export const NAV_LINKS = [
   ...ARTICLES.map((a) => ({ file: a.file, label: a.navLabel })),
   ...DECKS.map((d) => ({ file: deckOut(d), label: d.navLabel })),
+  { file: STATE_ATLAS.file, label: STATE_ATLAS.label },
 ];
 
 // Nav styling, appended to each article page's own <style> block so it reuses
 // the article design-system variables (--heading/--kicker/--accent-soft).
 const NAV_CSS = `
-  .site-nav { display: flex; flex-wrap: wrap; align-items: baseline; gap: 0.5rem 1.1rem; max-width: 64rem; margin: 0 auto; padding: 0.9rem clamp(1.1rem, 5vw, 2rem); border-bottom: 1px solid rgba(148, 163, 184, 0.16); }
+  .site-nav { display: flex; flex-wrap: wrap; align-items: baseline; gap: 0.5rem 1.1rem; max-width: 48rem; margin: 0 auto; padding: 0.9rem clamp(1.1rem, 5vw, 2rem); border-bottom: 1px solid rgba(148, 163, 184, 0.16); }
+  @media (min-width: 900px) { .site-nav { max-width: 56rem; } }
   .site-nav-brand { font-weight: 700; letter-spacing: -0.01em; color: var(--heading); text-decoration: none; border: 0; margin-right: auto; }
   .site-nav-links { display: flex; flex-wrap: wrap; gap: 0.5rem 1.1rem; }
   .site-nav a { color: var(--kicker); text-decoration: none; font-size: 0.9rem; border: 0; }
-  .site-nav a:hover { color: var(--accent-soft); }`;
+  .site-nav a:hover { color: var(--accent-soft); }
+  .site-nav-gh { display: inline-flex; align-items: center; }
+  .site-nav-gh svg { width: 1.125rem; height: 1.125rem; fill: currentColor; display: block; }`;
+
+// The repository the site links to from its nav. Derived from the effective
+// repoRoot's package.json repository.url (single source of truth) so a repo
+// rename/move updates the nav link too, rather than drifting from a hardcoded
+// copy. Resolved inside buildSite from its repoRoot param (not at module load)
+// so --repo-root / buildSite({ repoRoot }) reads the right package.json and no
+// I/O runs merely on import. The '.git' suffix is stripped for the web URL.
+// npm's `repository` field may be a string ("github:owner/repo" or a full URL)
+// or an object { type, url }. Accept both; fail with an explicit, actionable
+// message when neither yields a URL, rather than an implicit TypeError.
+export async function resolveRepoUrl(repoRoot) {
+  const { repository } = JSON.parse(await readFile(join(repoRoot, 'package.json'), 'utf8'));
+  const raw = typeof repository === 'string' ? repository : repository?.url;
+  if (!raw) {
+    throw new Error(`cannot resolve repo URL: package.json at ${repoRoot} has no repository.url`);
+  }
+  return raw
+    .replace(/^github:/, 'https://github.com/')
+    .replace(/\.git$/, '');
+}
+// Inline SVG (GitHub octicon mark) so it renders under the page's strict CSP
+// (img-src is data:-only; no external icon).
+const GITHUB_ICON = '<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg>';
 
-function navMarkup() {
+function navMarkup(repoUrl) {
   const links = NAV_LINKS.map((l) => `        <a href="${l.file}">${l.label}</a>`).join('\n');
   return `<nav class="site-nav" aria-label="dev-loops resources">
       <a class="site-nav-brand" href="index.html">dev-loops</a>
       <div class="site-nav-links">
 ${links}
+        <a class="site-nav-gh" href="${repoUrl}" aria-label="dev-loops on GitHub">${GITHUB_ICON}</a>
       </div>
     </nav>`;
 }
@@ -75,13 +108,13 @@ ${links}
 // markup right after <body>. Idempotent enough for assembly (each source file
 // is read once). Throws if the page lacks the expected anchors so a structural
 // drift fails the build rather than publishing an un-navigable page.
-export function injectNav(html) {
+export function injectNav(html, repoUrl) {
   if (!html.includes('</style>') || !/<body[^>]*>/.test(html)) {
     throw new Error('cannot inject nav: page is missing a <style> block or <body> tag');
   }
   return html
     .replace('</style>', `${NAV_CSS}\n</style>`)
-    .replace(/<body([^>]*)>/, `<body$1>\n    ${navMarkup()}`);
+    .replace(/<body([^>]*)>/, `<body$1>\n    ${navMarkup(repoUrl)}`);
 }
 
 export async function buildSite({ repoRoot = REPO_ROOT_DEFAULT, outDir } = {}) {
@@ -100,14 +133,16 @@ export async function buildSite({ repoRoot = REPO_ROOT_DEFAULT, outDir } = {}) {
   await rm(out, { recursive: true, force: true });
   await mkdir(out, { recursive: true });
 
+  const repoUrl = await resolveRepoUrl(repoRoot);
+
   // Landing page: the intro article, navigable, published as index.html.
   const landingHtml = await readFile(join(articlesDir, LANDING.file), 'utf8');
-  await writeFile(join(out, 'index.html'), injectNav(landingHtml), 'utf8');
+  await writeFile(join(out, 'index.html'), injectNav(landingHtml, repoUrl), 'utf8');
 
   // Deep-dive article: published with the same nav so the set is navigable.
   for (const article of ARTICLES) {
     const html = await readFile(join(articlesDir, article.file), 'utf8');
-    await writeFile(join(out, article.file), injectNav(html), 'utf8');
+    await writeFile(join(out, article.file), injectNav(html, repoUrl), 'utf8');
   }
 
   // Decks: self-contained slide renders, copied as-is (no nav injection).
@@ -115,9 +150,25 @@ export async function buildSite({ repoRoot = REPO_ROOT_DEFAULT, outDir } = {}) {
     await cp(join(decksDir, deck.file), join(out, deckOut(deck)));
   }
 
+  // State atlas: generated from the core state tables at build time, then given
+  // the same shared nav as the article pages so it can never drift from the code.
+  await writeFile(join(out, STATE_ATLAS.file), injectNav(buildStateAtlasHtml(), repoUrl), 'utf8');
+
+  // Vendored mermaid runtime the atlas page references (Pages has no CSP, so we
+  // load it as an external asset rather than inlining ~3MB into the page).
+  const mermaidSrc = join(repoRoot, 'scripts', 'loop', 'inspect-run-viewer', 'vendor', 'mermaid.min.js');
+  await mkdir(join(out, 'assets'), { recursive: true });
+  await cp(mermaidSrc, join(out, 'assets', 'mermaid.min.js'));
+
   return {
     out,
-    files: ['index.html', ...ARTICLES.map((a) => a.file), ...DECKS.map((d) => deckOut(d))],
+    files: [
+      'index.html',
+      ...ARTICLES.map((a) => a.file),
+      ...DECKS.map((d) => deckOut(d)),
+      STATE_ATLAS.file,
+      'assets/mermaid.min.js',
+    ],
   };
 }