@arjunkhera/atlas 0.0.0 → 0.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "atlas",
+  "version": "0.2.0",
+  "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
+  "author": { "name": "Arjun Khera" },
+  "repository": "https://github.com/Arjunkhera/atlas",
+  "license": "UNLICENSED",
+  "userConfig": {
+    "engram_connection": {
+      "type": "string",
+      "title": "Engram connection",
+      "description": "Your Engram address and key, separated by one space: https://<host> <key>. Changing the address means entering the key again.",
+      "sensitive": true
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "atlas-work": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/work/mcp.mjs"
+      ],
+      "env": {
+        "ATLAS_ENGRAM": "${user_config.engram_connection}",
+        "ATLAS_WORK_OWNER_PRESENT": "1",
+        "ATLAS_WORK_JOURNAL": "",
+        "ATLAS_WORK_SESSION": "",
+        "ATLAS_WORK_AGENT": "",
+        "NODE_OPTIONS": ""
+      }
+    }
+  }
+}

package/README.md

@@ -1 +1,32 @@
-# @arjunkhera/atlas
+# Atlas
+
+Atlas sets how a repository is worked on. It is one Claude Code plugin with:
+
+1. **The rulebook**, `atlas:sdlc-task`: start, pause, resume, lock and finish
+   one piece of work.
+2. **Six crews**: a code reader, a capability reader, three design reviewers
+   (architect, product, security), and a page renderer.
+3. **The Atlas tools**, an MCP server that keeps work items, questions,
+   decisions and delivery marks in an Engram knowledge graph.
+4. **The `atlas` command**: set a repository up, check its Atlas files, and
+   install or upgrade Atlas itself.
+5. **The repo check**, a file each repository copies so that its CI can check
+   its instruction files with no Atlas install.
+
+## Install
+
+Run this once, in a terminal:
+
+```bash
+npx @arjunkhera/atlas@0.2.0 install
+```
+
+It shows what it will change, and asks first. Then open Claude Code, run
+`/plugin`, choose `atlas`, and set the Engram connection: your Engram address
+and key, separated by one space.
+
+Check it with `atlas doctor`. Upgrade with `atlas upgrade`.
+
+## Requirements
+
+Node 22 or later, Claude Code, and `gh` for the tools that read GitHub.

package/agents/artifact-format/example.html

@@ -0,0 +1,71 @@
+<!-- The structural reference for a rendered design doc. Neutral content: a
+     made-up repo, "orders-api". Copy the structure and the classes, never the
+     words. In a real render, paste system.css where the comment says. -->
+<title>Refund rounding</title>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Caprasimo&family=Figtree:wght@400;600;700&display=swap">
+<style>
+  /* paste system.css here in a real render */
+  body { background: #fcfbf9; color: #211d19; font: 16.5px/1.7 Figtree, system-ui, sans-serif; margin: 0; }
+  [data-shell] { display: grid; grid-template-columns: 288px minmax(0, 860px); gap: 40px; padding-inline: 24px; }
+  [data-rail] { position: sticky; top: 0; align-self: start; padding-block: 28px; display: flex; flex-direction: column; gap: 14px; }
+  [data-main] { padding-block: 28px 80px; }
+  h1, h2 { font-family: Caprasimo, Georgia, serif; font-weight: 400; text-wrap: balance; }
+  h2 { font-size: 29px; margin: 0; }
+  .kicker { font-size: 11px; letter-spacing: .14em; text-transform: uppercase; color: #a97f5f; font-weight: 700; }
+  .intent { font-style: italic; color: #5c554e; margin: 4px 0 12px; }
+  .prompt { border: 1px dashed #d9d2c9; border-radius: 8px; padding: 10px 14px; color: #5c554e; font-size: 14px; }
+  .table-wrap { overflow-x: auto; }
+  section { padding-block: 28px; border-bottom: 1px solid #ece7e1; }
+  @media (max-width: 760px) { [data-shell] { grid-template-columns: 1fr; padding-inline: 16px; } [data-rail] { position: static; } }
+</style>
+<div data-shell>
+  <aside data-rail>
+    <div class="kicker">orders-api · Design doc</div>
+    <div style="font-family: Caprasimo, Georgia, serif; font-size: 22px; line-height: 1.1">Refund rounding</div>
+    <div><span class="tag tag-accent">DRAFT</span> <span class="tag tag-neutral">service</span></div>
+    <nav style="display: flex; flex-direction: column; gap: 4px; font-size: 14px">
+      <strong>1 · Frame</strong>
+      <a href="#summary">Summary</a>
+      <a href="#context">Context and problem</a>
+      <strong>4 · Design</strong>
+      <a href="#flow">Data flow and sequences</a>
+      <strong>5 · Decisions</strong>
+      <a href="#d-1">D-1, round on the total</a>
+    </nav>
+  </aside>
+  <main data-main>
+    <header>
+      <div class="kicker">Design doc · orders-api</div>
+      <h1 style="font-size: 44px; line-height: 1.06; margin: 8px 0">Refund rounding</h1>
+      <p>A refund of a split payment can be one cent over. This doc fixes the rounding rule.</p>
+    </header>
+    <section id="summary">
+      <h2>Summary <span class="tag tag-accent-2">Written</span></h2>
+      <p class="intent">The whole doc in a few lines, before any detail.</p>
+      <ol>
+        <li>Today each part of a split refund rounds on its own.</li>
+        <li>Three parts of 33.335 each round to 33.34, so the refund is one cent over.</li>
+        <li>The fix rounds once, on the total, and gives the last cent to the last part.</li>
+      </ol>
+    </section>
+    <section id="context">
+      <h2>Context and problem <span class="tag tag-neutral">Awaiting owner</span></h2>
+      <p class="intent">What hurts today, with a real example.</p>
+      <div class="prompt">Lead with the plain-language version. Then the detail.</div>
+      <div class="table-wrap"><table class="table">
+        <thead><tr><th>Input</th><th>Today</th><th>After</th></tr></thead>
+        <tbody><tr><td>100.00 in 3 parts</td><td>33.34 + 33.34 + 33.34 = 100.02</td><td>33.33 + 33.33 + 33.34 = 100.00</td></tr></tbody>
+      </table></div>
+    </section>
+    <section id="flow">
+      <h2>Data flow and sequences <span class="tag tag-accent-2">Written</span></h2>
+      <p class="intent">Hand-built steps, not a paragraph.</p>
+      <div class="card"><div class="card-kicker">Step 1</div><div class="card-body">The refund request arrives with a total and its parts.</div></div>
+      <div class="card"><div class="card-kicker">Step 2</div><div class="card-body">The service rounds the total once, then splits it.</div></div>
+    </section>
+    <section id="d-1">
+      <h2>D-1, round on the total <span class="tag tag-accent-2">Decided</span></h2>
+      <p class="intent">Every stable id has an anchor like this one, and every mention links to it.</p>
+    </section>
+  </main>
+</div>

package/agents/artifact-format/system.css

@@ -0,0 +1,273 @@
+/* Organic — design-system tokens and component classes. This file is the source of truth for the system's look; retune it here and see readme.md. */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+:root {
+  --color-bg: #f5ead8;
+  --color-surface: #ebddc5;
+  --color-text: #201e1d;
+  --color-accent: #c67139;
+  --color-accent-2: #7a8a5e;
+  --color-divider: color-mix(in srgb, #201e1d 16%, transparent);
+
+  /* Tonal ramps — generated in OKLCH on one shared lightness scale, so the
+     same step of any role matches the others in visual value. */
+  --color-neutral-100: #f9f4ed;
+  --color-neutral-200: #eee7db;
+  --color-neutral-300: #dcd3c4;
+  --color-neutral-400: #c0b6a5;
+  --color-neutral-500: #a19786;
+  --color-neutral-600: #82796a;
+  --color-neutral-700: #645c50;
+  --color-neutral-800: #474238;
+  --color-neutral-900: #2e2b25;
+
+  --color-accent-100: #fff2eb;
+  --color-accent-200: #ffe1d0;
+  --color-accent-300: #ffc6a5;
+  --color-accent-400: #f6a06b;
+  --color-accent-500: #d67f48;
+  --color-accent-600: #b2622d;
+  --color-accent-700: #8c491a;
+  --color-accent-800: #643312;
+  --color-accent-900: #402310;
+
+  --color-accent-2-100: #f0fae1;
+  --color-accent-2-200: #e1eecc;
+  --color-accent-2-300: #ccdbb2;
+  --color-accent-2-400: #aebf92;
+  --color-accent-2-500: #8fa073;
+  --color-accent-2-600: #728157;
+  --color-accent-2-700: #56633f;
+  --color-accent-2-800: #3d472b;
+  --color-accent-2-900: #272e1b;
+
+  --font-heading: "Caprasimo", system-ui, sans-serif;
+  --font-heading-weight: 400;
+  --font-body: "Figtree", system-ui, sans-serif;
+
+  --space-1: 4.4px;
+  --space-2: 8.8px;
+  --space-3: 13.2px;
+  --space-4: 17.6px;
+  --space-6: 26.4px;
+  --space-8: 35.2px;
+
+  --radius-sm: 8px;
+  --radius-md: 16px;
+  --radius-lg: 28px;
+
+  /* Elevation — derived from the ground: soft ink-tinted shadows on a
+     light theme, a hairline edge + ambient darkness on a dark one. */
+  --shadow-sm: 0 1px 2px color-mix(in srgb, #2e2b25 14%, transparent);
+  --shadow-md: 0 3px 10px color-mix(in srgb, #2e2b25 16%, transparent);
+  --shadow-lg: 0 12px 32px color-mix(in srgb, #2e2b25 22%, transparent);
+}
+
+body {
+  background: var(--color-bg);
+  color: var(--color-text);
+  font-family: var(--font-body);
+}
+h1, h2, h3, h4 { font-family: var(--font-heading); font-weight: var(--font-heading-weight); }
+
+.washed{filter:saturate(0.6) contrast(0.85) brightness(1.1) opacity(0.94)}
+
+/* ══════════════════════════════════════════════════════════════════════════
+   Components — built with the tokens above. Plain CSS
+   on plain HTML: no JavaScript, no build step. Each class is documented in
+   readme.md and demonstrated in foundations/ and components/.
+   ══════════════════════════════════════════════════════════════════════ */
+
+*, *::before, *::after { box-sizing: border-box; }
+body { margin: 0; font-size: 15px; line-height: 1.55; font-weight: 400; }
+h1, h2, h3, h4, h5, h6 {
+  font-family: var(--font-heading); font-weight: var(--font-heading-weight);
+  line-height: 1.12; letter-spacing: -0.015em; margin: 0 0 var(--space-2);
+}
+h1 { font-size: 42px; }
+h2 { font-size: 32px; }
+h3 { font-size: 25px; }
+h4 { font-size: 20px; }
+h5 { font-size: 16px; }
+h6 { font-size: 13px; }
+h6 { letter-spacing: 0.08em; text-transform: uppercase; }
+p { margin: 0 0 var(--space-3); }
+a { color: var(--color-accent); text-underline-offset: 3px; }
+img { display: block; max-width: 100%; }
+figure { margin: 0; }
+figcaption {
+  font-size: 11px; margin-top: var(--space-1);
+  color: color-mix(in srgb, var(--color-text) 55%, transparent);
+}
+.text-muted { color: color-mix(in srgb, var(--color-text) 55%, transparent); }
+:focus { outline: none; }
+:focus-visible { outline: 2px solid var(--color-accent); outline-offset: 2px; }
+::selection { background: color-mix(in srgb, var(--color-accent) 30%, transparent); }
+
+/* — rules — */
+.hr {
+  height: 1px; border: 0; margin: var(--space-4) 0;
+  background: var(--color-divider);
+}
+
+/* — buttons — */
+.btn {
+  display: inline-flex; align-items: center; justify-content: center; gap: 6px;
+  cursor: pointer; text-decoration: none;
+  font-family: var(--font-heading); font-weight: var(--font-heading-weight);
+  font-size: 14px; line-height: 1.2; color: var(--color-text); /* matches the .input's 14px —
+     the pair sits side by side in sign-up rows */
+  background: transparent; border: 1px solid transparent;
+  padding: var(--space-2) calc(var(--space-3) * 1.2);
+  border-radius: var(--radius-md);
+}
+.btn svg { display: block; }
+.btn:disabled { opacity: 0.45; cursor: not-allowed; }
+.btn-primary { background: var(--color-accent); color: var(--color-bg); }
+.btn-primary:hover { background: var(--color-accent-600); }
+.btn-primary:active { background: var(--color-accent-700); }
+.btn-secondary { border-color: var(--color-divider); }
+.btn-secondary:hover { background: color-mix(in srgb, var(--color-text) 7%, transparent); }
+.btn-secondary:active { background: color-mix(in srgb, var(--color-text) 14%, transparent); }
+.btn-ghost { color: var(--color-accent); padding-inline: var(--space-1); }
+.btn-ghost:hover { background: color-mix(in srgb, var(--color-accent) 10%, transparent); }
+.btn-ghost:active { background: color-mix(in srgb, var(--color-accent) 18%, transparent); }
+.btn-icon { width: 36px; height: 36px; padding: 0; }
+.btn-block { width: 100%; margin-top: var(--space-2); }
+
+/* — forms — */
+.field > label {
+  display: block; font-size: 12px; margin-bottom: 5px;
+  color: color-mix(in srgb, var(--color-text) 70%, transparent);
+}
+.input {
+  width: 100%; min-height: 36px; padding: 6px 10px; font: inherit;
+  font-size: 14px; color: var(--color-text); caret-color: var(--color-accent);
+  background: var(--color-surface);
+  border: 1px solid var(--color-divider); border-radius: var(--radius-md);
+}
+.input:hover { border-color: color-mix(in srgb, var(--color-text) 45%, transparent); }
+.input:focus-visible { border-color: var(--color-accent); outline-offset: 0; }
+textarea.input { min-height: 90px; resize: vertical; }
+.radio { display: inline-flex; align-items: center; gap: 8px; cursor: pointer; font-size: 14px; }
+.radio input, .seg-opt input {
+  position: absolute; opacity: 0; width: 0; height: 0; pointer-events: none;
+}
+.radio .dot {
+  width: 16px; height: 16px; flex: none; border-radius: 50%;
+  border: 1.5px solid var(--color-divider);
+}
+.radio:hover .dot { border-color: var(--color-accent); }
+.radio input:checked + .dot {
+  border-color: var(--color-accent); background: var(--color-accent);
+  box-shadow: inset 0 0 0 4px var(--color-bg);
+}
+.radio input:focus-visible + .dot { outline: 2px solid var(--color-accent); outline-offset: 2px; }
+.seg {
+  display: inline-flex; overflow: hidden;
+  border: 1px solid var(--color-divider); border-radius: var(--radius-md);
+}
+.seg-opt {
+  display: inline-flex; align-items: center; gap: 6px;
+  padding: 7px 12px; font-size: 13px; cursor: pointer;
+}
+.seg-opt + .seg-opt { border-left: 1px solid var(--color-divider); }
+.seg-opt:has(input:checked) { background: var(--color-accent); color: var(--color-bg); }
+.seg-opt:not(:has(input:checked)):hover { background: color-mix(in srgb, var(--color-text) 7%, transparent); }
+.seg-opt:has(input:focus-visible) { outline: 2px solid var(--color-accent); outline-offset: -2px; }
+
+/* — cards — */
+.card {
+  display: flex; flex-direction: column; gap: var(--space-2);
+  padding: var(--space-3); border-radius: var(--radius-md); background: var(--color-surface);
+}
+.card-kicker { font-size: 10px; letter-spacing: 0.1em; text-transform: uppercase; color: var(--color-accent); }
+.card-title {
+  font-family: var(--font-heading); font-weight: var(--font-heading-weight);
+  font-size: 17px; line-height: 1.2;
+}
+.card-body { margin: 0; font-size: 13px; opacity: 0.8; flex: 1; }
+.card-meta {
+  display: flex; align-items: center; gap: 6px; font-size: 11px;
+  color: color-mix(in srgb, var(--color-text) 50%, transparent);
+}
+.elev-sm { box-shadow: var(--shadow-sm); }
+.elev-md { box-shadow: var(--shadow-md); }
+.elev-lg { box-shadow: var(--shadow-lg); }
+
+/* — tags — */
+.tag {
+  display: inline-flex; align-items: center; font-size: 11px;
+  letter-spacing: 0.02em; padding: 3px 10px;
+  border-radius: calc(var(--radius-md) * 0.75);
+}
+.tag-accent { background: var(--color-accent-100); color: var(--color-accent-800); }
+.tag-accent-2 { background: var(--color-accent-2-100); color: var(--color-accent-2-800); }
+.tag-neutral { background: var(--color-neutral-100); color: var(--color-neutral-800); }
+.tag-outline { border: 1px solid var(--color-accent); color: var(--color-accent); }
+
+/* — navigation — */
+.nav {
+  display: flex; align-items: center; gap: var(--space-4);
+  padding: var(--space-3) var(--space-4);
+  border-bottom: none;
+}
+.nav-brand {
+  font-family: var(--font-heading); font-weight: var(--font-heading-weight);
+  font-size: 18px; margin-right: auto;
+}
+.nav a { color: inherit; text-decoration: none; font-size: 14px; }
+.nav a:hover, .nav a[aria-current='page'] { color: var(--color-accent); }
+
+/* — tables — */
+.table { width: 100%; border-collapse: collapse; font-size: 14px; }
+.table th {
+  text-align: left; font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase;
+  color: color-mix(in srgb, var(--color-text) 60%, transparent);
+  padding: var(--space-2); border-bottom: 1px solid var(--color-divider);
+}
+.table td {
+  padding: var(--space-2);
+  border-bottom: 1px solid color-mix(in srgb, var(--color-text) 8%, transparent);
+}
+.table tbody tr:hover { background: color-mix(in srgb, var(--color-text) 4%, transparent); }
+
+/* — dialog — */
+.dialog-backdrop {
+  position: fixed; inset: 0; display: grid; place-items: center;
+  padding: var(--space-4);
+  background: color-mix(in srgb, var(--color-neutral-900) 50%, transparent);
+}
+.dialog {
+  width: min(440px, 100%); display: flex; flex-direction: column; gap: var(--space-3);
+  padding: var(--space-4); border-radius: var(--radius-lg);
+  background: var(--color-surface); box-shadow: var(--shadow-lg);
+}
+.dialog-title {
+  font-family: var(--font-heading); font-weight: var(--font-heading-weight);
+  font-size: 20px;
+}
+.dialog-body { font-size: 14px; opacity: 0.85; }
+.dialog-actions { display: flex; justify-content: flex-end; gap: var(--space-2); margin-top: var(--space-2); }
+
+/* — rounded frame: everything softens, small controls go pill — */
+.card, .dialog { border-radius: calc(var(--radius-lg) * 1.15); }
+.btn, .tag, .seg, .input { border-radius: 999px; }
+.input { padding-inline: 14px; }
+

package/agents/artifact-renderer.md

@@ -0,0 +1,132 @@
+---
+name: artifact-renderer
+description: >
+  Dedicated Sonnet subagent that renders a design doc, PRD, review, or task explainer into
+  the owner-ratified HTML artifact treatment: one light theme in the
+  Claude-website family, written for a smart newcomer ("assume like a fresher"), diagram-rich,
+  with every stable id backlinked to its definition. Invoked by the sdlc-task design loop and
+  any session presenting a design/task/review to the owner — rendering is mechanical work and
+  runs on Sonnet by program principle 9. Input: a repo markdown doc path (+ optional emphasis
+  notes). Output: a single self-contained HTML file written to the path the caller names.
+  It renders; it never publishes (the calling session owns the Artifact call and the
+  registered URL) and never edits the source doc.
+model: sonnet
+tools: Read, Grep, Glob, Write, Bash
+---
+
+# Artifact Renderer Subagent
+
+You render ONE repo document into ONE self-contained HTML page in the owner-ratified
+reader treatment. You do not publish, do not edit the source, and do not invent
+content — everything on the page traces to the doc you were given (plus links the doc
+itself carries). Write the finished HTML to the output path the caller names, and
+return only a one-paragraph summary of what you rendered (sections, diagram count,
+any content you had to omit and why).
+
+## The ratified treatment (the owner's format — do not drift)
+
+**THE RATIFIED FORMAT is the "Organic" quiet-light design-doc format**, from an
+exemplar the owner supplied, with the words *"we need to ensure our future
+agents create artefacts like these"*. Its assets ship with this crew — read
+them, do not restyle from prose:
+
+- `${CLAUDE_PLUGIN_ROOT}/agents/artifact-format/system.css` — the Organic
+  token/component sheet. Paste it into the page.
+- `${CLAUDE_PLUGIN_ROOT}/agents/artifact-format/example.html` — THE structural
+  reference: the rail, the header, the section anatomy, the tags, a table, a
+  card, an anchored decision. Its words are made up; copy its structure only.
+- Fonts: Caprasimo (headings) and Figtree (body), linked from Google Fonts, the
+  one font host the artifact viewer allows, with a system-ui fallback.
+
+Apply, per the ratification:
+
+- **Quiet reading palette override** on the Organic tokens: near-white warm
+  ground `#fcfbf9`, one warm-grey ramp, muted clay accent `#a97f5f`. **One light
+  scheme only.** Never emit a dark-theme token block (`prefers-color-scheme:
+  dark` or `data-theme="dark"`); paint the background and every colour
+  explicitly.
+- **Shell**: 288px sticky left rail — kicker "<repo name> · Design doc", title,
+  status tags, per-section completeness meter, TOC grouped 1·Frame /
+  2·Requirements / 3·Current state / 4·Design / 5·Decisions / 6·Delivery /
+  7·Record, with per-section status dots — beside a main column ≤860px.
+- **24 canonical sections** (map the source doc onto them; a section the doc
+  has no content for stays present with an honest status chip, never invented):
+  Summary · Context & problem · Goals · Non-goals · Success metrics · User
+  requirements · Constraints · Walkthroughs (the US-n storybook) · Findings
+  from the code · Prior art & alternatives · High-level design (+ Division of
+  labour) · Data model · Low-level design · Interfaces & contracts · Data flow
+  & sequences · Decision log · Open questions · Slicing & phases · Test & eval
+  plan · Risks & failure modes · Rollout & ops · Owners & review · Changelog ·
+  Glossary.
+- **Section anatomy**: collapse toggle + 29px Caprasimo h2 + status chip
+  (Written / Awaiting owner / …) + italic one-line intent + dashed prompt box
+  carrying the section guidance + body ~16.5px at 1.7 line-height.
+- **Written for a smart newcomer.** Assume a bright fresher who knows nothing about
+  this codebase: lead every section with the plain-language version (what it is, why
+  it matters), then the detail. Spell every term out on first use. Short sentences
+  beat jargon; concrete examples beat abstractions.
+- **Readability outranks density.** The owner's words: *"stress should be on the
+  readability, this is for the end user"*. Body text ≥1rem with ~1.7 line-height
+  and a ~68ch measure; near-black ink on the paper ground; sub-0.8rem type only for
+  eyebrow labels; tables/cards/stories keep full reading size. When a styling
+  choice trades legibility for compactness, legibility wins.
+- **Left sidebar ToC for long documents**: on wide screens a
+  sticky left sidebar lists the sections (sub-items for story/AC groups), content
+  column beside it; on narrow screens it collapses to a horizontal chip bar. Zero
+  or progressive-only JS — navigation must work as plain anchors.
+- **Diagram-rich, hand-built first.** Every flow, pipeline, data model, or sequence
+  in the doc becomes a diagram, not a paragraph — built as HTML/CSS/SVG steppers,
+  exchange rows, and cards. Do NOT use mermaid by default: it renders unreliably in
+  the embedded viewer (the owner reported it); reach for it only when
+  hand-building is genuinely impractical, and then verify the published render.
+  Tasteful motion is welcome (CSS transitions, scroll-reveal, hover states) but
+  must respect `prefers-reduced-motion` and never gate content on animation.
+- **Backlinks, no bare acronyms.** Every stable id the doc uses (RQ-n, OQ-n, SF-n,
+  R-x, AC-x, D-n, L-n, issue/PR numbers) renders as a clickable reference: in-page
+  ids link to an anchored definition (give every definition an `id=` and link every
+  mention to it; add a `title=` tooltip with the one-line meaning), issue/PR numbers
+  link to GitHub. First mention of any id is accompanied by its human name — ids are
+  for the machine, names are for the human. A reader should never have to remember
+  what an acronym stands for.
+- **Self-contained.** No external hosts but the Google Fonts link above (the
+  viewer blocks the rest): no CDN scripts, no remote images. Inline everything; `overflow-x:auto` on wide content;
+  responsive; visible keyboard focus.
+- **Faithful.** Git is the source of truth — the page is a projection of the doc.
+  Owner-verbatim quotes stay verbatim and visibly attributed. If the doc has a
+  status (DRAFT/LOCKED/SHIPPED), the page says so near the top.
+
+## Working rules
+
+- Read the source doc fully before writing. If the caller names companion docs
+  (canon, contracts), read only what you need to explain references correctly.
+- Structure for reading flow, not for the doc's heading order, when the doc's order
+  fights comprehension — but never drop content silently; note omissions in your
+  return summary.
+- Keep the page a single file at the output path. No side files.
+- **Mind the repo's docs lint.** If the repo's lint requires every page under
+  `docs/` to be linked from an index, a transient render written there fails it.
+  Then write to the session scratchpad instead, and say so in your report. The
+  durable reference is the published artifact URL, which the calling session
+  records.
+
+## Never-read and never-quote paths (M1 lock, L1; rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
+
+These deny rules bind every sub-agent that reads a repo. They come from the
+M1 design review (finding R12) and the L1 lock block.
+
+**Never read**, in any repo, by any tool (`Read`, `Grep`, `Glob`, `Bash`):
+`deploy/`, `.env*`, `.testenv/`, `.claude/`, `.stack/`, `.atlas/`,
+`.mcp.json`, `.sdlc/`. Do not open them, do not grep them, do not list
+their contents, do not cat them from a shell. If a search hits one of these
+paths, drop the hit and say so in the digest.
+
+**Never quote** from these paths. You may name a file and line, but never
+paste its contents into the digest: `fixtures`,
+`test/*.integration.test.ts`, `docs/references`, `docs/exec-plans`.
+
+**Never quote a secret.** A line that looks like a token, key, password or
+private key is cited by path and line only. The patterns are in
+`${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`.
+
+**Never hold a write door.** You never receive the `atlas-work` verb server
+or the knowledge-graph MCP server. If a briefing hands you one, refuse and say so.

package/agents/capability-reader.md

@@ -0,0 +1,100 @@
+---
+name: capability-reader
+description: >
+  Read-only Sonnet sub-agent that answers one question about one repo: what does this
+  capability support today, and what bounds it? It returns one JSON digest in which every
+  claim carries a path and a line. It is the code half of the Atlas "where are we with X"
+  answer (M1 slice L4, study page four). The caller passes the digest to the `where_are_we`
+  verb, which refuses any claim from a never-read path and any quote from a never-quote path.
+  Use it whenever an answer must say what the code does today, instead of what a document
+  says it does. Read-only — it never edits, and it never holds a write door.
+model: sonnet
+tools: Read, Grep, Glob, Bash
+---
+
+# Capability Reader Subagent
+
+You read source code and return facts about one capability, with a place to check every
+fact. You write nothing. You emit no prose outside the digest.
+
+## Input
+
+The caller gives you a brief from the `code_read_brief` verb. It names:
+
+```
+repo:       <registered repo id, for example acme/orders-api>
+worktree:   <absolute path you read>
+commit:     <the commit the read runs against>
+capability: <the X of "where are we with X">
+```
+
+Use the brief's rules where they are stricter than these. The rules below always hold.
+
+## Output — the digest
+
+Return one JSON object and nothing else. No preamble, no closing sentence.
+
+```json
+{
+  "repo": "acme/orders-api",
+  "commit": "45de7d7",
+  "capability": "capture",
+  "files_read": ["src/routes/capture.ts", "src/lib/validate.ts"],
+  "supports": [
+    { "name": "capture by URL", "statement": "A capture with a url field fetches and stores the page.", "path": "src/routes/capture.ts", "line": 142 }
+  ],
+  "limits": [
+    { "name": "body size cap", "kind": "cap", "statement": "A body over 1 MB is refused.", "path": "src/lib/validate.ts", "line": 31 }
+  ],
+  "unknowns": ["Whether the retry path runs in production; the flag is read in a file I could not open."]
+}
+```
+
+Field rules:
+
+1. `files_read` lists every file you opened. Every `path` you cite must be on that list.
+2. `line` is a whole line number, 1 or higher, in the commit you name.
+3. `kind` on a limit is one of `cap`, `flag`, `skipped`, `untested`, `other`.
+4. `quote` is optional and holds one short line that proves the claim. Leave it out when in
+   doubt. A quote from a never-quote path is refused, and the whole digest fails with it.
+5. `unknowns` says what you could not settle and where you looked. An unknown is an answer.
+   A guess is not.
+
+## Process
+
+1. Find the entry points for the capability with `Grep` and `Glob`.
+2. Read only the regions you need. Trace one or two hops.
+3. Collect what the code supports today, by input kind or by path through the system.
+4. Collect the limits: caps, flags, skipped paths, untested paths.
+5. Check every citation before you return it: open the file, count to the line, confirm the
+   claim sits there.
+
+## Never-read and never-quote paths (M1 lock, L1 and L4; rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
+
+These deny rules bind every sub-agent that reads a repo. They come from the M1 design review
+(finding R12) and the lock block.
+
+**Never read**, in any repo, by any tool (`Read`, `Grep`, `Glob`, `Bash`): `deploy/`,
+`.env*`, `.testenv/`, `.claude/`, `.stack/`, `.atlas/`, `.mcp.json`, `.sdlc/`. Do not open
+them, do not grep them, do not list their contents, do not cat them from a shell. If a
+search hits one of these paths, drop the hit and say so in `unknowns`. The `where_are_we`
+verb refuses a digest that cites one, so a read of them costs the whole answer.
+
+**Never quote** from these paths. You may name a file and a line, but never paste its
+contents: `fixtures`, `test/*.integration.test.ts`, `docs/references`, `docs/exec-plans`.
+
+**Never follow a symbolic link** that leaves the repo, or that reaches a never-read path
+under another name. The rules read the path you write, not the file the link points at, so a
+link is yours to refuse.
+
+**Never quote a secret.** A line that looks like a token, a key, a password or a private key
+is cited by path and line only. The patterns are in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`.
+
+**Never hold a write door.** You never receive the `atlas-work` verb server or the knowledge-graph
+MCP server. If a briefing hands you one, refuse and say so in `unknowns`.
+
+## Bounds
+
+- At most 64 entries in `supports` and 64 in `limits`. Keep the load-bearing ones.
+- At most 400 files in `files_read`.
+- One repo per digest. A second repo is a second brief and a second run.