altitude-design 0.3.2 → 0.4.1

package/README.md

@@ -3,6 +3,7 @@
 A design and HCI framework for agent-built React web applications, with a component foundation where **height is the interface**. Its one idea: the ground is the record. Settled content sits on the ground; anything live rises above it; anything waiting to receive sinks below it.
 
 - **Site:** https://richlaconte.github.io/altitude/
+- **For agents:** https://richlaconte.github.io/altitude/llms.txt, an index of the guides, task patterns and every component's guide as plain Markdown ([llmstxt.org](https://llmstxt.org)), and `llms-full.txt` beside it with every guide in one file
 - **Storybook:** every component, with its guidelines and a live preview in both schemes: https://richlaconte.github.io/altitude/storybook/
 - **The design guide:** [`project/README.md`](https://github.com/richlaconte/altitude/blob/main/project/README.md), then [Elevation](https://github.com/richlaconte/altitude/blob/main/project/Elevation.md), [Motion](https://github.com/richlaconte/altitude/blob/main/project/Motion.md), [Charts](https://github.com/richlaconte/altitude/blob/main/project/Charts.md), [Theming](https://github.com/richlaconte/altitude/blob/main/project/Theming.md), [Fundamentals](https://github.com/richlaconte/altitude/blob/main/project/Fundamentals.md), [Distinctiveness](https://github.com/richlaconte/altitude/blob/main/project/Distinctiveness.md) and [Research](https://github.com/richlaconte/altitude/blob/main/project/Research.md)
 
@@ -117,6 +118,7 @@ npx altitude init --client codex          # preview exact changes
 npx altitude init --client codex --apply   # apply after reviewing the preview
 # Claude Code: --client claude. Both: --client all.
 npx altitude doctor --json
+npx altitude check                         # Altitude's rules that are certain from your source
 ```
 
 Setup preserves existing instructions and adds a small versioned pointer to the installed guidance. It never runs on package installation. Preview removal with `npx altitude init --client codex --remove`, then add `--apply` to remove only its managed content. Edited blocks are preserved and require reconciliation. Codex uses a nonempty root `AGENTS.override.md` when present; otherwise `AGENTS.md`. Claude Code uses `CLAUDE.md`. Restart the client after setup. See [setup details](docs/framework/AGENT-SETUP.md).

package/dist/cli/altitude.mjs

@@ -1,10 +1,85 @@
 #!/usr/bin/env node
 
 // scripts/altitude-cli.mjs
-import { existsSync, lstatSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync as readFileSync2, writeFileSync, unlinkSync } from "node:fs";
 import { createRequire } from "node:module";
 import { createHash } from "node:crypto";
-import { resolve, dirname, relative, basename } from "node:path";
+import { resolve, dirname, relative as relative2, basename } from "node:path";
+
+// scripts/source-check.mjs
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join, relative } from "node:path";
+var SOURCE = /* @__PURE__ */ new Set([".tsx", ".jsx", ".ts", ".js", ".mjs", ".css", ".scss", ".html"]);
+var SKIP = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "out", ".next", ".git", "coverage", "storybook-static"]);
+var COLOUR = /#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\(/;
+var TAILWIND_COLOUR = /(?:^|[\s"'`:])(?:text|bg|border|ring|outline|fill|stroke|from|via|to|divide|placeholder|decoration|caret|accent)-(?:(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(?:50|[1-9]00|950)|white|black|\[(?:#|rgb|hsl|oklch))/;
+function files(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP.has(entry.name) || entry.name.startsWith(".")) continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...files(path));
+    else if (SOURCE.has(extname(entry.name)) && !/\.(test|spec|stories)\.[jt]sx?$|\.d\.ts$/.test(entry.name) && statSync(path).size < 1e6) out.push(path);
+  }
+  return out;
+}
+var ignored = (lines, i, id) => [lines[i], lines[i - 1] || ""].some((l) => new RegExp(`altitude-ignore:\\s*${id}\\b`).test(l));
+var uncomment = (text) => text.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " ")).replace(/(^|[^:'"`])\/\/.*$/gm, "$1");
+var RULES = {
+  "ALT-TOKEN-001": { kind: "deterministic", title: "Colours come from the tokens, not literals" },
+  "ALT-SETUP-002": { kind: "deterministic", title: "Altitude's stylesheet is imported" },
+  "ALT-SETUP-003": { kind: "deterministic", title: "The app is wrapped in AltitudeProvider" },
+  "ALT-CHART-001": { kind: "deterministic", title: "No pie or donut charts" },
+  "ALT-COPY-001": { kind: "deterministic", title: "Buttons name their outcome, never OK or Submit" },
+  "ALT-PRIMARY-001": { kind: "contextual-review", title: "One primary action per view" },
+  "ALT-VISUAL-004": { kind: "contextual-review", title: "Controls keep Altitude's elevation" }
+};
+function scan(root, { tokenNames = /* @__PURE__ */ new Set() } = {}) {
+  const findings = [];
+  const add = (id, file, line, observed, repair) => findings.push({ ruleId: id, kind: RULES[id].kind, status: RULES[id].kind === "deterministic" ? "fail" : "review", file: file && relative(root, file), line, observed, expected: RULES[id].title, repair, verification: `altitude explain ${id}` });
+  const sources = files(root);
+  let usesAltitude = false, stylesheet = false, providers = [];
+  for (const file of sources) {
+    const raw = readFileSync(file, "utf8");
+    const text = uncomment(raw);
+    const lines = text.split("\n"), rawLines = raw.split("\n");
+    const css = /\.(s?css|html)$/.test(file);
+    if (/from\s+['"]altitude-design['"]|require\(\s*['"]altitude-design['"]\s*\)/.test(text)) usesAltitude = true;
+    if (/['"]altitude-design\/altitude(\.no-fonts)?\.css['"]/.test(text)) stylesheet = true;
+    lines.forEach((line, i) => {
+      const at = i + 1;
+      const skip = (id) => ignored(rawLines, i, id);
+      if (COLOUR.test(line) && !skip("ALT-TOKEN-001")) {
+        const definesToken = /^\s*--[\w-]+\s*:/.test(line) || [...line.matchAll(/['"]?([a-z][\w-]*)['"]?\s*:\s*['"`]?(?:#|rgb|hsl|oklch)/g)].some((m) => tokenNames.has(m[1]));
+        const accent = /\baccent\s*=\s*\{?\s*['"`]#/.test(line);
+        const inStyle = css ? [...line.matchAll(/(?:^|[{;"'])\s*([a-z-]+)\s*:\s*([^;{}"']+)/g)].some((m) => !m[1].startsWith("--") && COLOUR.test(m[2])) : /\bstyle=\{\{|(?:color|background|backgroundColor|borderColor|fill|stroke|boxShadow|outlineColor)\s*[:=]/.test(line);
+        if (!definesToken && !accent && inStyle) add("ALT-TOKEN-001", file, at, line.trim().slice(0, 160), "Use a token instead: var(--ink-muted), var(--accent), var(--surface-raised) and the rest of tokens.css. A brand colour goes to AltitudeProvider accent, and a full palette to a custom scheme.");
+      } else if (!css && TAILWIND_COLOUR.test(line) && /\bclass(Name)?=/.test(line) && !skip("ALT-TOKEN-001")) {
+        add("ALT-TOKEN-001", file, at, line.trim().slice(0, 160), 'Use a token instead of a palette class: style={{ color: "var(--ink-muted)" }} or a class whose CSS uses the tokens.');
+      }
+      if (css) return;
+      if (!skip("ALT-CHART-001") && (/import\s*\{[^}]*\b(PieChart|Pie|Doughnut|RadialBarChart)\b[^}]*\}\s*from\s*['"](recharts|react-chartjs-2)['"]/.test(line) || /from\s*['"]@nivo\/pie['"]/.test(line) || /\btype\s*:\s*['"](pie|doughnut)['"]/.test(line)))
+        add("ALT-CHART-001", file, at, line.trim().slice(0, 160), 'Show a part of a whole as a stacked BarChart or a segmented Meter: angle and area are read less accurately than length (Charts.md, "Choosing a form").');
+      const copy = line.match(/<(?:\w+\.)?Button\b[^>]*>\s*(OK|Ok|Okay|Submit)\s*<\/(?:\w+\.)?Button>/);
+      if (copy && !skip("ALT-COPY-001")) add("ALT-COPY-001", file, at, copy[0].slice(0, 160), `Start with a verb and name the outcome: "Save changes", "Send invite", "Create project", not "${copy[1]}".`);
+      const lift = line.match(/<(?:\w+\.)?(Input|Textarea|Select|Combobox|Button|Switch|Checkbox)\b[^>]*(boxShadow|box-shadow|\bshadow-(?!none)[\w-]+|\btranslate-y-|\btransform\s*:)/);
+      if (lift && !skip("ALT-VISUAL-004")) add("ALT-VISUAL-004", file, at, line.trim().slice(0, 160), `Remove the override: a ${lift[1]}'s height is how it says whether you press it or fill it. Use the component's variant or size props instead.`);
+    });
+    if (!css) {
+      const n = (text.match(/<(?:\w+\.)?AltitudeProvider\b/g) || []).length;
+      if (n) providers.push(...Array(n).fill(relative(root, file)));
+      const primaries = [...text.matchAll(/<(?:\w+\.)?Button\b[^>]*\bvariant=["']primary["']/g)];
+      if (primaries.length > 1 && !ignored(rawLines, text.slice(0, primaries[1].index).split("\n").length - 1, "ALT-PRIMARY-001"))
+        add("ALT-PRIMARY-001", file, text.slice(0, primaries[1].index).split("\n").length, `${primaries.length} primary buttons in this file`, "If they can be on screen together, keep one primary (the one action the task leads to) and make the others secondary or ghost.");
+    }
+  }
+  if (usesAltitude && !stylesheet) add("ALT-SETUP-002", null, null, "No file imports altitude-design/altitude.css or altitude-design/altitude.no-fonts.css", "Import one of them once, at the app's entry: import 'altitude-design/altitude.css';");
+  if (usesAltitude && !providers.length) add("ALT-SETUP-003", null, null, "Components from altitude-design are used, but nothing renders <AltitudeProvider>", "Render one AltitudeProvider around the whole app. It sets the scheme and hosts dialogs and toasts.");
+  if (providers.length > 1) findings.push({ ruleId: "ALT-SETUP-003", kind: "contextual-review", status: "review", file: null, line: null, observed: `<AltitudeProvider> is rendered in ${providers.length} places (${[...new Set(providers)].join(", ")})`, expected: "One AltitudeProvider around the app", repair: "Keep one around the app unless the others are deliberate (separate roots, previews).", verification: "altitude explain ALT-SETUP-003" });
+  return { files: sources.length, findings };
+}
+
+// scripts/altitude-cli.mjs
 var sha = (value2) => createHash("sha256").update(value2).digest("hex");
 var args = process.argv.slice(2);
 var command = args.shift() || "help";
@@ -17,9 +92,9 @@ var json = args.includes("--json");
 var emit = (result) => console.log(JSON.stringify(result, null, 2));
 function installed() {
   const path = createRequire(resolve(cwd, "package.json")).resolve("altitude-design/package.json");
-  const pkg = JSON.parse(readFileSync(path, "utf8"));
+  const pkg = JSON.parse(readFileSync2(path, "utf8"));
   const guidance = resolve(dirname(path), "dist/guidance");
-  const index = JSON.parse(readFileSync(resolve(guidance, "index.json"), "utf8"));
+  const index = JSON.parse(readFileSync2(resolve(guidance, "index.json"), "utf8"));
   return { pkg, guidance, index };
 }
 function managed(text) {
@@ -31,15 +106,23 @@ function managed(text) {
   if (!m || sha(m[3]) !== m[2]) throw new Error("The managed Altitude block was edited; preserve your edits and reconcile it manually.");
   return { start: m.index, end: m.index + m[0].length, created: m[1] === "true", body: m[3] };
 }
-function block(version, guidance, created) {
-  const path = relative(cwd, guidance).replaceAll("\\", "/");
-  const body = `## Altitude framework (${version})
-For UI tasks using altitude-design, first read ${path}/README.md, then only the matching pattern document.
+function block({ pkg, guidance, index }, created) {
+  const path = relative2(cwd, guidance).replaceAll("\\", "/");
+  const declarations = relative2(cwd, resolve(guidance, "..", "types")).replaceAll("\\", "/") + "/";
+  const groups = /* @__PURE__ */ new Map();
+  for (const c of index.components || []) groups.set(c.group, [...groups.get(c.group) || [], c.name]);
+  const components = groups.size ? `Component guides: ${path}/components/<Name>/README.md. Read one before using that component.
+` + [...groups].map(([g, names]) => `${g}|${names.join(",")}`).join("\n") + "\n" : "";
+  const body = `## Altitude framework (${pkg.version})
+Altitude postdates your training data, and its props only look like shadcn's. Prefer these installed docs to what you remember, and check a component's props in its declaration under ${declarations} before using them.
+For UI tasks using altitude-design, first read ${path}/README.md, then only the matching pattern document. Read ${path}/visual/README.md before composing a screen and ${path}/visual/Charts.md before any chart, stat or meter.
+On every screen: one AltitudeProvider around the app and altitude-design/altitude.css imported once; inputs sunk and buttons raised, never the reverse; one primary action per view; no amount carried by height (charts are flat ink on a ground line: no shadows, 3D, pie or donut); status never colour alone (a word and an icon too); colours, shadows and radii from the tokens, never hard-coded.
 Discover tasks with npm exec -- altitude patterns "your intent"; explain a rule with npm exec -- altitude explain RULE-ID.
-Use the installed public declarations and examples. Record applicable states and application-owned persistence, permissions and navigation.
+Record applicable states and application-owned persistence, permissions and navigation.
+After changing UI, run npm exec -- altitude check and fix its errors; it reports Altitude's rules that are certain from source (hard-coded colours, the stylesheet and provider, pie charts, OK and Submit labels) and lists likely problems for review.
 Run the pattern checks and application service fixtures; distinguish deterministic defects, integration obligations and contextual review.
 Use npm exec -- altitude doctor --json after package upgrades, and rerun npm exec -- altitude init to refresh this versioned pointer.
-`;
+` + components;
   return `
 <!-- altitude:start created=${created} hash=${sha(body)} -->
 ${body}<!-- altitude:end -->
@@ -47,7 +130,7 @@ ${body}<!-- altitude:end -->
 }
 function instructionPath(client) {
   const override = resolve(cwd, "AGENTS.override.md");
-  if (client === "codex" && existsSync(override) && readFileSync(override, "utf8").trim()) return override;
+  if (client === "codex" && existsSync(override) && readFileSync2(override, "utf8").trim()) return override;
   return resolve(cwd, client === "codex" ? "AGENTS.md" : "CLAUDE.md");
 }
 function isSymlink(path) {
@@ -67,9 +150,9 @@ function init(context) {
   const targets = clients.flatMap((client2) => (remove && client2 === "codex" ? [resolve(cwd, "AGENTS.md"), resolve(cwd, "AGENTS.override.md")] : [instructionPath(client2)]).map((path) => ({ client: client2, path })));
   const changes = targets.map(({ client: c, path }) => {
     if (isSymlink(path)) throw new Error(`Refusing instruction symlink: ${path}`);
-    const existed = existsSync(path), before = existed ? readFileSync(path, "utf8") : "";
+    const existed = existsSync(path), before = existed ? readFileSync2(path, "utf8") : "";
     const old = managed(before);
-    const replacement = remove ? "" : block(context.pkg.version, context.guidance, old?.created ?? !existed);
+    const replacement = remove ? "" : block(context, old?.created ?? !existed);
     const after = old ? before.slice(0, old.start) + replacement + before.slice(old.end) : before + (remove ? "" : replacement);
     const deleteFile = remove && old?.created && after === "";
     return { client: c, path, before, after, action: deleteFile ? "delete" : before === after ? "unchanged" : existed ? "update" : "create" };
@@ -86,35 +169,52 @@ function finding(ruleId, kind, status, observed, expected, repair, verification)
 function doctor(context) {
   const findings = [];
   if (context.pkg.version !== context.index.version) findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `Package ${context.pkg.version}; guidance ${context.index.version}`, "Matching versions", "Reinstall a coherent package.", "altitude doctor --json"));
-  const manifest = JSON.parse(readFileSync(resolve(context.guidance, "manifest.json"), "utf8"));
+  const manifest = JSON.parse(readFileSync2(resolve(context.guidance, "manifest.json"), "utf8"));
   if (manifest.version !== context.pkg.version) findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `Manifest ${manifest.version}`, "Manifest matches installed package", "Reinstall the package.", "altitude doctor --json"));
   for (const [file, digest] of Object.entries(manifest.files)) {
     const path = resolve(context.guidance, file);
-    if (!path.startsWith(context.guidance + "/") || !existsSync(path) || sha(readFileSync(path)) !== digest) findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `Missing or modified guidance: ${file}`, "Unmodified version-matched guidance", "Reinstall the package.", "altitude doctor --json"));
+    if (!path.startsWith(context.guidance + "/") || !existsSync(path) || sha(readFileSync2(path)) !== digest) findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `Missing or modified guidance: ${file}`, "Unmodified version-matched guidance", "Reinstall the package.", "altitude doctor --json"));
   }
   for (const client of ["codex", "claude"]) {
     const path = instructionPath(client), file = basename(path);
     try {
-      const text = existsSync(path) ? readFileSync(path, "utf8") : "";
+      const text = existsSync(path) ? readFileSync2(path, "utf8") : "";
       const current = managed(text);
-      if (current && text.slice(current.start, current.end) !== block(context.pkg.version, context.guidance, current.created)) findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `${file} points to different guidance`, "Setup matches installed version and location", `altitude init --client ${client} --apply`, "altitude doctor --json"));
+      if (current && text.slice(current.start, current.end) !== block(context, current.created)) findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `${file} points to different guidance`, "Setup matches installed version and location", `altitude init --client ${client} --apply`, "altitude doctor --json"));
       else findings.push(finding("ALT-SETUP-001", "deterministic", current ? "pass" : "not-configured", `${client}: ${current ? "managed pointer matches" : "no managed pointer"}`, "Explicit setup when agent integration is desired", `altitude init --client ${client}`, "Restart client and inspect loaded instructions."));
     } catch (e) {
       findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `${file}: ${e.message}`, "One intact managed block", "Reconcile edited/duplicate markers manually.", "altitude doctor --json"));
     }
   }
-  const rules = JSON.parse(readFileSync(resolve(context.guidance, "rules.json"), "utf8")).rules;
+  const rules = JSON.parse(readFileSync2(resolve(context.guidance, "rules.json"), "utf8")).rules;
   for (const r of rules.filter((r2) => r2.diagnosticClass !== "deterministic")) findings.push(finding(r.id, r.diagnosticClass, "unverified", "CLI has not exercised application behavior or conducted human review.", r.title, r.repair, r.verification));
   const ok = !findings.some((f) => f.kind === "deterministic" && f.status === "fail");
   emit({ command: "doctor", packageVersion: context.pkg.version, guidanceVersion: context.index.version, ok, scope: "Installation and managed pointers only; not accessibility or usability certification.", findings });
   if (!ok) process.exitCode = 1;
 }
+function check(context) {
+  const target = resolve(cwd, args.find((v, i) => !v.startsWith("--") && args[i - 1] !== "--cwd") || (existsSync(resolve(cwd, "src")) ? "src" : "."));
+  if (!existsSync(target)) throw new Error(`No such directory: ${target}`);
+  const tokensCss = resolve(context.guidance, "..", "tokens.css");
+  const tokenNames = new Set(existsSync(tokensCss) ? [...readFileSync2(tokensCss, "utf8").matchAll(/--([\w-]+)\s*:/g)].map((m) => m[1]) : []);
+  const { files: files2, findings } = scan(target, { tokenNames });
+  const ok = !findings.some((f) => f.kind === "deterministic");
+  const scope = "Altitude rules certain from source text only. Not checked: anything that needs the page rendered (contrast, overflow, focus) or a person (accessibility, usability).";
+  if (json) emit({ command: "check", version: context.pkg.version, target: relative2(cwd, target) || ".", files: files2, ok, scope, findings });
+  else {
+    for (const f of findings) console.log(`${f.ruleId} ${f.kind === "deterministic" ? "error " : "review"} ${f.file ? `${f.file}${f.line ? ":" + f.line : ""}` : "(project)"}  ${f.observed}
+  ${f.repair}`);
+    console.log(`${findings.filter((f) => f.kind === "deterministic").length} errors, ${findings.filter((f) => f.kind !== "deterministic").length} to review in ${files2} files. ${scope} Explain a rule: npm exec -- altitude explain RULE-ID`);
+  }
+  if (!ok) process.exitCode = 1;
+}
 try {
-  if (command === "help" || command === "--help") console.log("altitude init --client codex|claude|all [--apply] [--remove]\naltitude patterns [intent] [--json]\naltitude explain RULE-ID [--json]\naltitude doctor [--json]\nAll commands resolve the installed package from --cwd PATH (default current directory).");
+  if (command === "help" || command === "--help") console.log("altitude init --client codex|claude|all [--apply] [--remove]\naltitude patterns [intent] [--json]\naltitude explain RULE-ID [--json]\naltitude doctor [--json]\naltitude check [dir] [--json]\nAll commands resolve the installed package from --cwd PATH (default current directory).");
   else {
     const context = installed();
     if (command === "init") init(context);
     else if (command === "doctor") doctor(context);
+    else if (command === "check") check(context);
     else if (command === "patterns") {
       const words = args.filter((v, i) => !v.startsWith("--") && args[i - 1] !== "--cwd").join(" ").toLowerCase().split(/\W+/).filter(Boolean);
       const patterns = context.index.patterns.map((p) => ({ ...p, score: words.reduce((n, w) => n + (p.intents.some((i) => i === w || i.startsWith(w)) ? 1 : 0), 0) })).filter((p) => !words.length || p.score).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
@@ -123,7 +223,7 @@ try {
   ${resolve(context.guidance, p.document)}`).join("\n") : "No pattern matched. Run altitude patterns to browse the catalog.");
     } else if (command === "explain") {
       const id = args[0];
-      const rule = JSON.parse(readFileSync(resolve(context.guidance, "rules.json"), "utf8")).rules.find((r) => r.id === id);
+      const rule = JSON.parse(readFileSync2(resolve(context.guidance, "rules.json"), "utf8")).rules.find((r) => r.id === id);
       if (!rule) throw new Error(`Unknown rule: ${id}`);
       emit({ version: context.pkg.version, ...rule });
     } else throw new Error(`Unknown command: ${command}`);

package/dist/guidance/README.md

@@ -2,6 +2,8 @@
 
 Start from the person's task. Read only the relevant pattern below, its linked rules, and the public declarations. The installed copy matches the package version; `altitude doctor --json` checks that connection. Guidance supports judgment; it does not certify an application.
 
+Every screen also follows the visual rules. Read the [design guide](visual/README.md) before composing one, [Elevation](visual/Elevation.md) for what height means, [Charts](visual/Charts.md) before drawing any chart, stat or meter, and [Motion](visual/Motion.md) before animating. Each component has its own guide (what it's for, how it uses height, what you provide); read it before using the component: for example [Button](components/Button/README.md) or [Select](components/Select/README.md). The `components` list in `index.json` has every component with its group, a one-line summary and its guide.
+
 Composing a new screen? Choose its frame from the task with [screen layout](patterns/screen-layout.md) first: name the task, the one thing that leads and the one primary action. The [app skeleton](app-skeleton.md) is one of its frames, for working through many similar records: shell, page header, a filtered and paged table, a record in a sheet, and settings, composed correctly.
 
 | Intent | Focused contract |
@@ -29,4 +31,6 @@ Use `altitude patterns "edit settings" --json` to discover contracts and `altitu
 
 Compose existing primitives and small workflow hooks from the main `altitude-design` export inside one `AltitudeProvider`. Import a package stylesheet. The application supplies routes, business validation and services. Verify delayed operations, rejection, retry, cancellation and stale responses where applicable; include keyboard and manual assistive-technology review. Automated checks cannot establish complete accessibility or task suitability.
 
+After changing UI, run `npm exec -- altitude check` (or `altitude check src --json`). It reports Altitude's rules that are certain from source text as errors (hard-coded colours instead of tokens, a missing stylesheet or `AltitudeProvider`, pie and donut charts, buttons labelled OK or Submit) and likely problems for review (several primary buttons in one file, elevation overrides on controls). Fix the errors; decide on the reviews. Each finding names a rule `altitude explain` describes. It doesn't check anything that needs the page rendered or a person.
+
 For explicit agent setup, preview `npm exec -- altitude init --client codex` (or `claude`), then use `--apply`. Full setup and removal instructions are shipped as `agent-setup.md`, generated from the repository’s `docs/framework/AGENT-SETUP.md`. No installation hook writes project instructions.

package/dist/guidance/agent-setup.md

@@ -9,14 +9,15 @@ npm exec -- altitude init --client claude --apply
 npm exec -- altitude patterns "edit settings" --json
 npm exec -- altitude explain ALT-EDIT-001
 npm exec -- altitude doctor --json
+npm exec -- altitude check --json
 npm exec -- altitude init --client codex --remove
 npm exec -- altitude init --client codex --remove --apply
 ```
 
 `init` defaults to a preview, including the exact before/after text. `--apply` applies that preview. `--client all` targets both clients. Repeating setup makes no change. Removal removes only the managed block, restoring surrounding bytes; a file created by setup is removed only if nothing else remains. User-edited managed blocks, malformed markers and symlinks are rejected for manual reconciliation. Existing instructions outside the block are preserved. Run setup again after upgrading the installed package. Use `--cwd PATH` to target an explicit project directory. Resolution uses that directory's installed `altitude-design/package.json`, never the version fetched by a different CLI invocation.
 
-The Codex adapter writes a compact routing block to project `AGENTS.md` (or an existing nonempty `AGENTS.override.md`, which Codex gives precedence); the Claude Code adapter writes it to project `CLAUDE.md`. Neither assumes instruction files under `node_modules` are automatically discovered. The routing block points at version-matched local focused documents rather than importing the complete manual. Restart the agent session after setup. Confirm Codex reports the project instruction file and Claude Code's `/context` lists it under Memory files; then ask an ordinary product question and check that the relevant pattern is read. Instructions are context, not enforcement, and broader or more specific instructions may affect discovery.
+The Codex adapter writes a compact routing block to project `AGENTS.md` (or an existing nonempty `AGENTS.override.md`, which Codex gives precedence); the Claude Code adapter writes it to project `CLAUDE.md`. Neither assumes instruction files under `node_modules` are automatically discovered. The routing block points at version-matched local focused documents rather than importing the complete manual. Because it's read on every turn, it carries only what an agent can't work out for itself: a reminder to prefer the installed docs and declarations to its memory, the rules that hold on every screen, and a compact index of every component (by group, with the path pattern of each component's guide), read on demand. The `agent-setup` check keeps it under 8 KB and verifies that every path it names is installed. Restart the agent session after setup. Confirm Codex reports the project instruction file and Claude Code's `/context` lists it under Memory files; then ask an ordinary product question and check that the relevant pattern is read. Instructions are context, not enforcement, and broader or more specific instructions may affect discovery.
 
 Mechanisms verified against official documentation on 2026-10-23: [Codex AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) describes root-to-working-directory instruction discovery, override precedence and size limits; [Claude Code memory](https://code.claude.com/docs/en/memory) documents project `CLAUDE.md` loading and `/context` inspection. The adapter tests verify files and round trips, not successful behavior of every client release. Claude Code also documents AGENTS.md support; CLAUDE.md remains the explicit adapter target.
 
-`doctor` reports stable rule IDs, observed evidence, expected behavior, repairs and verification. It returns a failing exit code only for deterministic installation/setup defects; service integration and contextual obligations remain visibly unverified. It does not inspect an application's service behavior or certify accessibility. Guidance remains usable offline through `altitude-design/guidance`, `altitude-design/guidance/*`, and physical `node_modules/altitude-design/dist/guidance` files. Tooling stays outside browser imports.
+`doctor` reports stable rule IDs, observed evidence, expected behavior, repairs and verification. It returns a failing exit code only for deterministic installation/setup defects; service integration and contextual obligations remain visibly unverified. It does not inspect an application's service behavior or certify accessibility. `check [dir]` (default `src`, else the project) scans an application's own source for Altitude's rules that are certain from text: hard-coded colours instead of tokens (`ALT-TOKEN-001`), the stylesheet and `AltitudeProvider` (`ALT-SETUP-002`, `ALT-SETUP-003`), pie and donut charts (`ALT-CHART-001`) and buttons labelled OK or Submit (`ALT-COPY-001`). Those fail the run. Several primary buttons in one file (`ALT-PRIMARY-001`) and elevation overrides on controls (`ALT-VISUAL-004`) are listed for review and never fail. A finding a team keeps is marked `altitude-ignore: <ID> <reason>` on its line or the line above. It reads text only: nothing that needs the page rendered or a person is checked. Guidance remains usable offline through `altitude-design/guidance`, `altitude-design/guidance/*`, and physical `node_modules/altitude-design/dist/guidance` files. Tooling stays outside browser imports.

package/dist/guidance/components/AILabel/README.md

@@ -0,0 +1,60 @@
+# AILabel
+
+Says when content was generated or changed by AI, and explains how when asked: for trust, and under transparency rules such as the EU AI Act. Carbon for AI made its label the entry point to explainability; this follows that, without the gradient.
+
+**Elevation: a label is part of the record.** It's a flush `Badge` plate, a small static icon and a word: "AI", or **"Drafted with AI"** once a person has reviewed it.
+- **No gradient, no glow, no shimmer.** A glow is light from below, and the light never moves. A gradient rim is also easily mistaken for focus.
+- **It acts**, so it lifts one level when pointed at, like any plate that acts.
+- **The explanation** is a `Popover` at level 3, "About this content": the model, when it was generated (`RelativeTime`), confidence in words, who reviewed or edited it, and the sources it was based on.
+- **Provenance stays.** Accepting AI content doesn't remove its label; the plate changes to "Drafted with AI" and the explanation says who reviewed it.
+
+**Accessibility.** A button with `aria-haspopup="dialog"` opening a non-modal popover. Its name says what it marks ("Summary generated with AI. Show details", or "drafted with AI and reviewed"). Tab, Enter and Escape. Under forced colours the plate has a border, and the icon and word carry the meaning. Under `contrast="more"` the plate's border is `line-control`.
+
+**Props:** `subject` (what it marks, default "Content"); `model`; `generatedAt`; `sources` (`{ title, url? }[]`); `confidence`; `reviewedBy`; `editedBy`; `children` (anything else about how it was made).
+
+**You provide:** the provenance. Place the label beside what it marks, such as a heading or a field label.
+
+```tsx
+<h3>Summary <AILabel subject="Summary" model="Opus 5.5" generatedAt={summary.at}
+  sources={summary.sources} reviewedBy={summary.reviewer} confidence="Medium: two sources disagreed" /></h3>
+```
+
+- Do keep the label once a person accepts the content.
+- Do say confidence in words.
+- Don't decorate AI content with gradients, glows or shimmer.
+- Don't use the label as the only place AI involvement is disclosed when your rules require more.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`AILabel` as first used in its preview:
+
+```tsx
+import { AILabel } from 'altitude-design';
+
+<AILabel subject="Summary" model="Opus 5.5" generatedAt={new Date(Date.now() - 4 * 60000)} confidence="Medium: two sources disagreed about the renewal date"
+sources={[{ title: 'Call with Jamie Lee, 28 Oct', url: '#/calls/28' }, { title: 'Contract v3.pdf', url: '#/files/contract' }]} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `al`, `ttl` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { AILabel } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="col al">
+      <div>
+        <h3 className="ttl">Summary <AILabel subject="Summary" model="Opus 5.5" generatedAt={new Date(Date.now() - 4 * 60000)} confidence="Medium: two sources disagreed about the renewal date"
+          sources={[{ title: 'Call with Jamie Lee, 28 Oct', url: '#/calls/28' }, { title: 'Contract v3.pdf', url: '#/files/contract' }]} /></h3>
+        <p>Jamie wants to move to annual billing in November and asked whether the 30-day refund applies to the remaining monthly period.</p>
+      </div>
+      <div>
+        <h3 className="ttl">Reply <AILabel subject="Reply" model="Opus 5.5" generatedAt={new Date(Date.now() - 3 * 3600000)} reviewedBy="Maya Chen" editedBy="Maya Chen" /></h3>
+        <p>Hi Jamie, thanks for getting in touch. Your full refund of €240 is on its way.</p>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/Accordion/README.md

@@ -0,0 +1,32 @@
+# Accordion
+
+Reveals sections one at a time. Closed items are **lids** lying flush on the page; opening one lifts its lid into a raised card and opens the **compartment** underneath, where the content sits.
+
+Closed rows sit on the ground divided by `line` hairlines. Hovering one raises a ghost of its lid (a faint raised tint with a hairline), so you can see what will open. Opening raises the item to level 2 (`surface-raised`, `elev-2`), opens a gap around it and hides the neighbouring dividers. Inside, the content sits in a compartment: an opening sunk into the lid (`surface-well`) with its back wall showing just below the rim, the same camera as an empty `Input`. The panel grows on `ease-glide`, the content emerges 60ms later, and the chevron turns on `ease-settle`. Closed panels are inert to keyboard and assistive tech.
+
+**You provide:** `items` (`value`, `title`, `content`), `type` (`single` closes the others; `multiple` doesn't), `defaultValue` as an array of open values.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Accordion` as first used in its preview:
+
+```tsx
+import { Accordion } from 'altitude-design';
+
+<Accordion items={items} defaultValue={['b']} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`wrap` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { Accordion } from 'altitude-design';
+
+const items = [
+  { value: 'a', title: 'What does elevation mean here?', content: 'Height says how much something matters right now and what you can do with it: raised things are pushed, sunk things are filled.' },
+  { value: 'b', title: 'Can I bring my own colour?', content: 'Pass any hex as accent to AltitudeProvider. The accent text and soft tints are derived to stay legible on every surface.' },
+  { value: 'c', title: 'Does it respect reduced motion?', content: 'Yes. Surfaces still change level, tint and shadow, but nothing travels or scales.' },
+];
+export default function App() { return <div className="wrap"><Accordion items={items} defaultValue={['b']} /></div>; }
+```
+<!-- /example -->

package/dist/guidance/components/AgentFleet/README.md

@@ -0,0 +1,81 @@
+# AgentFleet
+
+Every agent working on one job, as a roster: grouped by what they need from you (needs you, working, done), each row saying the agent's state in words, what it's doing in one line, how long it has waited or run, where it is in its plan and what it has spent, with warnings for trouble that's coming (two agents changing one file, an agent making no progress). For supervising several agents at once; see [the research](https://github.com/richlaconte/altitude/blob/v0.4.1/docs/research/agent-orchestration/README.md).
+
+**Elevation: a record of agents, with live rows.**
+- **Rows** are the record: flush at rest, lifting one level when pointed at because selecting one opens it. The open agent is selected, as a table's row is: `accent-soft`, raised one level, `aria-current`.
+- **Working** isn't pending (nothing you sent is in flight), so it never hovers: a plate with a steady accent lamp says "Working". No spinner.
+- **Needs you** ("Needs approval", "Has a question", "Ready for review") is a caution plate with a lamp, and "waiting 6 min". It doesn't rise: a row can't lift into a card inside a list, and `AgentRequests` holds the raised card.
+- **Stalled** ("No progress for 7 min", "Retried the same step 3 times") is a caution plate and a clock mark, in the working group: a suspicion, not a request.
+- **Blocked** says on what ("Waiting on Billing API"); **queued** is a neutral plate. **Failed** is a critical plate and leads with the agents that need you, since nothing happens until someone retries or stops it.
+- **Done** is stamped: a check, the name in muted ink, "took 9 min". The done group folds away.
+- **A conflict** is a flush `caution-soft` strip under the row naming the file and the other agent: never colour alone.
+- **Agents an agent started** hang under it in a 1px `line-control` bracket, as `TraceParallel` draws subagents.
+
+**Accessibility.** A region named by `aria-label` ("Agents"). Each group is a list named with its count ("Needs you, 2"); a collapsible group's heading is a button with `aria-expanded`. Each row is a button whose name says everything in order: "Billing API, waiting 6 min, Wants to run the migration on staging, Needs approval, Step 3 of 4, spent $0.38". Up and Down move between rows across groups; Home and End go to the first and last. An agent that starts needing you (or fails) is announced politely once; starting, progress, stalling and finishing aren't.
+
+**Parts:** `AgentFleet` (`aria-label`, `now`, `summary`); `AgentFleetGroup` (`label`, `count`, `collapsible`, `defaultOpen`, `empty`); `AgentFleetItem` (`name`, `state`: `'queued' | 'working' | 'needs-input' | 'blocked' | 'stalled' | 'failed' | 'done' | 'stopped'`, `needs`: `'approval' | 'question' | 'review'`, `activity`, `since`, `startedAt`, `endedAt`, `step`, `blockedBy`, `conflict`, `stalledReason`, `cost`, `output`, `selected`, `onSelect`, `children`). Helpers: `groupAgents(agents, get)` sorts into needs you (longest wait first), working (stalled first) and finished (newest first); `summarizeFleet(states)` writes "2 need you · 3 working · 4 done"; `formatSpan(ms)` writes "6 min".
+
+**You provide:** the agents and their states, a one-line `activity` for each (the agent's last status, or a summary from a small model), when each entered its state, and what selecting does (open it beside the fleet). Detecting a stall or a conflict is yours too: pass `state="stalled"` when an agent has made no progress for a while or repeats a step, and `conflict` when two agents change the same file.
+
+```tsx
+const g = groupAgents(agents, (a) => a);
+const row = (a) => <AgentFleetItem key={a.id} {...a} selected={a.id === open} onSelect={() => setOpen(a.id)} />;
+<AgentFleet summary={summarizeFleet(agents.map((a) => a.state))}>
+  <AgentFleetGroup label="Needs you" empty="Nothing needs you.">{g.needsYou.map(row)}</AgentFleetGroup>
+  <AgentFleetGroup label="Working">{g.working.map(row)}</AgentFleetGroup>
+  <AgentFleetGroup label="Done" collapsible defaultOpen={false}>{g.finished.map(row)}</AgentFleetGroup>
+</AgentFleet>
+```
+
+- Do sort by need: the agent waiting longest on you goes first.
+- Do say every state in words; the lamp and mark only repeat it.
+- Don't show a spinner, a ticking counter or make a working row hover.
+- Don't lay agents out as a grid of equal cards: the one that needs you gets lost among the ones that don't.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`AgentFleet` as first used in its preview:
+
+```tsx
+import { AgentFleet, AgentFleetGroup, summarizeFleet } from 'altitude-design';
+
+<AgentFleet now={now} summary={summarizeFleet(seed.map((a) => a.state))}>
+  <AgentFleetGroup label="Needs you" empty="Nothing needs you.">{g.needsYou.map(row)}</AgentFleetGroup>
+  <AgentFleetGroup label="Working">{g.working.map(row)}</AgentFleetGroup>
+  <AgentFleetGroup label="Done" collapsible>{g.finished.map(row)}</AgentFleetGroup>
+</AgentFleet>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`af` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AgentFleet, AgentFleetGroup, AgentFleetItem, groupAgents, summarizeFleet } from 'altitude-design';
+
+const now = Date.UTC(2026, 9, 31, 14, 20), min = 60000;
+const seed = [
+  { id: 'api', name: 'Billing API', state: 'needs-input', needs: 'approval', activity: 'Wants to run the migration on staging', since: now - 6 * min, startedAt: now - 17 * min, step: { current: 3, total: 4 }, cost: '$0.38' },
+  { id: 'qa', name: 'QA', state: 'failed', activity: '2 of 14 checkout tests failed', since: now - 2 * min, startedAt: now - 5 * min, cost: '$0.11' },
+  { id: 'docs', name: 'Docs', state: 'stalled', stalledReason: 'Retried the same step 3 times', activity: 'Link check timed out on /enterprise; retrying', since: now - 5 * min, startedAt: now - 17 * min, step: { current: 3, total: 3 }, cost: '$0.31' },
+  { id: 'pricing', name: 'Pricing page', state: 'working', activity: 'Writing the annual toggle in Pricing.tsx', startedAt: now - 17 * min, step: { current: 2, total: 4 }, cost: '$0.41', conflict: { file: 'src/content/pricing.ts', with: 'Docs' } },
+  { id: 'changelog', name: 'Changelog', state: 'blocked', blockedBy: 'Pricing page' },
+  { id: 'emails', name: 'Renewal emails', state: 'done', activity: 'Scheduled for Tuesday 9:00 to 1,240 customers', startedAt: now - 17 * min, endedAt: now - 3 * min, cost: '$0.29' },
+];
+export default function App() {
+  const [open, setOpen] = React.useState('pricing');
+  const g = groupAgents(seed, (a) => a);
+  const row = (a) => <AgentFleetItem key={a.id} {...a} selected={a.id === open} onSelect={() => setOpen(a.id)} />;
+  return (
+    <div className="af">
+      <AgentFleet now={now} summary={summarizeFleet(seed.map((a) => a.state))}>
+        <AgentFleetGroup label="Needs you" empty="Nothing needs you.">{g.needsYou.map(row)}</AgentFleetGroup>
+        <AgentFleetGroup label="Working">{g.working.map(row)}</AgentFleetGroup>
+        <AgentFleetGroup label="Done" collapsible>{g.finished.map(row)}</AgentFleetGroup>
+      </AgentFleet>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/AgentLanes/README.md

@@ -0,0 +1,53 @@
+# AgentLanes
+
+Where each agent's time went, one lane per agent on a shared clock: working, waiting on you, waiting on another agent, failed. Its takeaway leads with how long agents have waited on you, the bottleneck a fleet of agents hides: once several run, the person is usually the slowest part.
+
+**Elevation: a chart, so nothing has height** (see [Charts](../../visual/Charts.md)).
+- **Stretches** are equal-height flat bars lying on each lane's ground line: working is `data-1`; waiting on you is `caution` hatched at 45°; waiting on another agent is a 1px dashed outline; failed is `critical`. A gap is time the agent wasn't running.
+- **Every fill is named** in the key, in words, and each bar's title says its agent, state and span.
+- **"Now"** is a 1px `line-control` rule at the end of the record; the axis says "31 min ago", "15 min ago", "Now".
+- **The selected lane** is its name in `accent-ink` and 650, with `aria-pressed`; lanes never lift.
+- **Forced colours**: working solid, waiting hatched, blocked dashed, failed cross-hatched with a thick border.
+
+**Accessibility.** A `figure` captioned by its takeaway. The lane names are buttons when `onSelect` is set; the bars and axis are hidden from assistive technology and a table gives the same data (agent; time working, waiting on you, waiting on another agent, failed).
+
+**Props:** `lanes` (`{ id, name, segments: { from, to?, state }[] }[]`; a segment without `to` runs to now), `start` (default the earliest segment), `now`, `takeaway` (default "Agents have waited on you for 15 min in all; the longest wait was Pricing page, 5 min."), `aria-label`, `selected`, `onSelect`. Time spent failed counts as waiting on you in the takeaway, since a failed agent waits for a retry.
+
+```tsx
+<AgentLanes start={job.startedAt} lanes={agents.map((a) => ({ id: a.id, name: a.name, segments: a.history }))} selected={open} onSelect={setOpen} />
+```
+
+- Do keep it below the roster: it explains the past, the roster and requests are for now.
+- Don't draw dependencies as arrows between lanes; say them on the waiting agent ("Waiting on Billing API").
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`AgentLanes` as first used in its preview:
+
+```tsx
+import { AgentLanes } from 'altitude-design';
+
+<AgentLanes lanes={lanes} start={t0} now={m(31)} selected={sel} onSelect={setSel} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`al` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AgentLanes } from 'altitude-design';
+
+const t0 = Date.UTC(2026, 9, 31, 14, 0), m = (n) => t0 + n * 60000;
+const lanes = [
+  { id: 'pricing', name: 'Pricing page', segments: [{ from: m(3), to: m(20), state: 'working' }, { from: m(20), to: m(25), state: 'waiting' }] },
+  { id: 'api', name: 'Billing API', segments: [{ from: m(3), to: m(7), state: 'working' }, { from: m(7), to: m(10), state: 'waiting' }, { from: m(10), to: m(19), state: 'working' }] },
+  { id: 'emails', name: 'Renewal emails', segments: [{ from: m(3), to: m(8), state: 'working' }, { from: m(8), to: m(13), state: 'waiting' }, { from: m(13), to: m(25), state: 'working' }] },
+  { id: 'qa', name: 'QA', segments: [{ from: m(3), to: m(19), state: 'blocked' }, { from: m(19), to: m(21), state: 'working' }, { from: m(21), to: m(23), state: 'failed' }, { from: m(23), to: m(29), state: 'working' }] },
+  { id: 'changelog', name: 'Changelog', segments: [{ from: m(27), to: m(30), state: 'working' }] },
+];
+export default function App() {
+  const [sel, setSel] = React.useState('qa');
+  return <div className="al"><AgentLanes lanes={lanes} start={t0} now={m(31)} selected={sel} onSelect={setSel} /></div>;
+}
+```
+<!-- /example -->

package/dist/guidance/components/AgentRequests/README.md

@@ -0,0 +1,76 @@
+# AgentRequests
+
+Every decision your agents are waiting on, in one queue: approvals, questions, reviews and failures, oldest first, each answerable where it is. Beside an `AgentFleet`, it lets a person supervising several agents clear what's waiting in a row, without opening each agent.
+
+**Elevation: status that asks for action.**
+- **A request** is a raised card (level 1), because it asks for action; it arrives lifted and settles with the afterglow. It isn't pending: nothing has been dispatched until it's answered.
+- **Its kind** is a plate in words: "Needs approval", "Has a question", "Ready for review" (caution, with a lamp) or "Couldn't finish" (critical). Who's asking and "waiting 6 min" sit beside it.
+- **Its answers** are secondary and ghost buttons: the view keeps its one primary. Open is a ghost at the end.
+- **Nothing waiting** is said flush with a check ("Nothing needs you"): an all-clear is settled, not an opening.
+- **The count** beside the heading is the one part that floats, as any count that wants you does.
+
+**Accessibility.** A section named by its heading ("Needs you"). Requests are an ordered list, longest wait first; each is an `article` named by its ask and described by its kind, agent and wait. Open is named for the agent ("Open Billing API"). A request that arrives is announced politely once ("Billing API: Run the migration on staging?").
+
+**Parts:** `AgentRequests` (`title`, `now`, `empty`); `AgentRequest` (`agent`, `kind`: `'approval' | 'question' | 'review' | 'failed'`, `title`, `detail`, `since`, `actions`, `onOpen`).
+
+**You provide:** the requests (give each a stable `key`), what each answer does, and removing a request once it's answered. For a question with many options or your own answer, or an approval with scopes or edits, use Open and answer in the agent's own `Question` or `Confirmation`.
+
+```tsx
+<AgentRequests>
+  {waiting.map((r) => (
+    <AgentRequest key={r.id} agent={r.agent} kind={r.kind} since={r.since} title={r.title} detail={r.consequence} onOpen={() => open(r.agentId)}
+      actions={<><Button size="sm" variant="secondary" onClick={() => approve(r)}>Run migration</Button><Button size="sm" variant="ghost" onClick={() => reject(r)}>Don't run</Button></>} />
+  ))}
+</AgentRequests>
+```
+
+- Do say the consequence of an approval in `detail`.
+- Don't offer "approve all": answer each with its consequence in view.
+- Don't make an answer primary; the view's one primary stays where it is.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`AgentRequests` as first used in its preview:
+
+```tsx
+import { AgentRequest, AgentRequests, Button } from 'altitude-design';
+
+<AgentRequests now={now}>
+  {left.map((r) => (
+    <AgentRequest key={r.id} agent={r.agent} kind={r.kind} since={r.since} title={r.title} detail={r.detail} onOpen={() => {}}
+      actions={<>{r.answers.map((a) => <Button key={a} size="sm" variant="secondary" onClick={() => done(r.id)}>{a}</Button>)}
+        {r.decline && <Button size="sm" variant="ghost" onClick={() => done(r.id)}>{r.decline}</Button>}</>} />
+  ))}
+</AgentRequests>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`ar` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AgentRequest, AgentRequests, Button } from 'altitude-design';
+
+const now = Date.UTC(2026, 9, 31, 14, 20), min = 60000;
+const seed = [
+  { id: 'emails', agent: 'Renewal emails', kind: 'question', since: now - 4 * min, title: 'Send the offer to every monthly customer, or only the active ones?', answers: ['Active only', 'Everyone'] },
+  { id: 'api', agent: 'Billing API', kind: 'approval', since: now - 9 * min, title: 'Run the plans-table migration on staging?', detail: 'Adds annual price columns to 4 plans on staging. Production isn\'t touched.', answers: ['Run migration'], decline: "Don't run" },
+  { id: 'qa', agent: 'QA', kind: 'failed', since: now - 1 * min, title: 'Checkout tests failed', detail: '2 of 14 failed: the annual total shows $290/yr, expected $290/year.', answers: ['Retry'] },
+];
+export default function App() {
+  const [left, setLeft] = React.useState(seed);
+  const done = (id) => setLeft((l) => l.filter((r) => r.id !== id));
+  return (
+    <div className="ar">
+      <AgentRequests now={now}>
+        {left.map((r) => (
+          <AgentRequest key={r.id} agent={r.agent} kind={r.kind} since={r.since} title={r.title} detail={r.detail} onOpen={() => {}}
+            actions={<>{r.answers.map((a) => <Button key={a} size="sm" variant="secondary" onClick={() => done(r.id)}>{a}</Button>)}
+              {r.decline && <Button size="sm" variant="ghost" onClick={() => done(r.id)}>{r.decline}</Button>}</>} />
+        ))}
+      </AgentRequests>
+    </div>
+  );
+}
+```
+<!-- /example -->