@zigrivers/scaffold 3.29.0 → 3.31.0

package/content/guides/mmr/index.html

@@ -48,9 +48,13 @@
     --yellow:       #d97706;
     --yellow-bg:    #fffbeb;
     --yellow-border:#fde68a;
+    --red:          #dc2626;
+    --red-bg:       #fef2f2;
+    --red-border:   #fecaca;
     --gray:         #9ca3af;
     --gray-bg:      #f3f4f6;
     --gray-border:  #e5e7eb;
+    --scrim:        rgba(15, 17, 23, 0.45);
 
     /* Semantic: Next Banner */
     --next-bg:      #eef2ff;
@@ -133,9 +137,13 @@
     --yellow:       #fbbf24;
     --yellow-bg:    rgba(120, 53, 15, 0.25);
     --yellow-border:rgba(251, 191, 36, 0.20);
+    --red:          #f87171;
+    --red-bg:       rgba(127, 29, 29, 0.25);
+    --red-border:   rgba(248, 113, 113, 0.22);
     --gray:         #6b7294;
     --gray-bg:      #252940;
     --gray-border:  #363c58;
+    --scrim:        rgba(0, 0, 0, 0.6);
 
     /* Semantic: Next Banner */
     --next-bg:      rgba(30, 27, 75, 0.50);
@@ -1078,17 +1086,290 @@ figure.mermaid svg .marker {
 }
 figure.mermaid svg .edgeLabel,
 figure.mermaid svg .edgeLabel text { fill: var(--text-muted); color: var(--text-muted); }
+
+/* ============================================================================
+ * guides.css — component + layout styles for `scaffold guides` reference pages.
+ *
+ * Pairs with lib/dashboard-theme.css (the token source) and src/guides/chrome.ts
+ * (the behavior). Styles the guide CHROME (.topbar, .layout, .rail, nav.toc,
+ * .content) and the markdown DIRECTIVES (callouts, sev chips, filter-tables,
+ * charts, tabs, citations) plus base prose typography.
+ *
+ * DESIGN SYSTEM: all COLORS come from dashboard-theme.css tokens, and spacing
+ * uses the --sp-* scale wherever it maps. The few structural layout constants
+ * (topbar height, rail/drawer width, chart label column, card min) are declared
+ * as local custom properties below; a handful of sub-scale UI values (chip/bar
+ * sizing, em-based inline-code padding) and the responsive breakpoint are
+ * literal because no token expresses them. Both themes are covered because every
+ * color is a token.
+ * ==========================================================================*/
+
+:root {
+  --topbar-h: 52px;       /* sticky topbar height; rail sticky offset keys off it */
+  --rail-w: 260px;        /* desktop TOC sidebar column */
+  --drawer-w: 280px;      /* mobile off-canvas TOC drawer */
+  --card-min: 260px;      /* index card min track width */
+  --chart-label-w: 90px;  /* chart row label column min */
+}
+
+/* ── Base / reset on top of the token base in dashboard-theme.css ─────────── */
+.content a { color: var(--accent); text-decoration: none; }
+.content a:hover { text-decoration: underline; }
+.content strong { font-weight: var(--fw-semi); }
+.content hr { border: 0; border-top: 1px solid var(--border-light); margin: var(--sp-6) 0; }
+
+/* Consistent keyboard focus for every interactive control (a11y). */
+.topbar button:focus-visible,
+.copy-btn:focus-visible,
+.tab-btn:focus-visible,
+.filter-input:focus-visible,
+nav.toc a:focus-visible,
+.guide-card:focus-visible,
+.content a:focus-visible {
+  outline: 2px solid var(--accent); outline-offset: 2px; border-radius: var(--radius-sm);
+}
+
+/* ── Topbar ────────────────────────────────────────────────────────────────*/
+.topbar {
+  position: sticky; top: 0; z-index: 60; height: var(--topbar-h);
+  display: flex; align-items: center; gap: var(--sp-3);
+  padding: 0 var(--page-pad);
+  background: var(--bg-card); border-bottom: 1px solid var(--border);
+}
+.topbar h1 {
+  flex: 1; min-width: 0; margin: 0;
+  font-size: var(--text-lg); font-weight: var(--fw-bold);
+  letter-spacing: var(--ls-tight);
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.topbar button {
+  background: var(--bg-card); border: 1px solid var(--border); color: var(--text);
+  border-radius: var(--radius-sm); padding: var(--sp-1) var(--sp-3); font-size: var(--text-base);
+  line-height: 1; cursor: pointer; font-family: inherit;
+}
+.topbar button:hover { background: var(--bg-hover); border-color: var(--accent); }
+.nav-toggle { display: none; }
+
+/* ── Layout: sticky sidebar TOC + reading-width content ──────────────────── */
+.layout {
+  max-width: var(--max-w); margin: 0 auto;
+  display: grid; grid-template-columns: var(--rail-w) minmax(0, 1fr);
+  gap: var(--sp-8); padding: 0 var(--page-pad);
+}
+.rail {
+  position: sticky; top: var(--topbar-h); align-self: start;
+  height: calc(100vh - var(--topbar-h)); overflow-y: auto;
+  padding: var(--sp-5) 0; border-right: 1px solid var(--border-light);
+}
+.content { min-width: 0; padding: var(--sp-6) 0 var(--sp-10); }
+
+/* Backdrop behind the mobile drawer (toggled with the rail via chrome.ts). */
+.rail-backdrop { display: none; }
+/* In-drawer close button — hidden on desktop (the rail is a static sidebar). */
+.rail-close { display: none; }
+
+/* ── Table of contents (scrollspy marks a.active) ────────────────────────── */
+nav.toc ul { list-style: none; margin: 0; padding: 0; }
+nav.toc li { margin: 0; }
+nav.toc a {
+  display: block; padding: var(--sp-1) var(--sp-3); line-height: 1.35;
+  color: var(--text-muted); font-size: var(--text-sm);
+  text-decoration: none; border-left: 2px solid transparent;
+  border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
+}
+nav.toc a:hover { color: var(--text); background: var(--bg-hover); }
+nav.toc a.active {
+  color: var(--accent); border-left-color: var(--accent);
+  background: var(--accent-glow); font-weight: var(--fw-medium);
+}
+nav.toc li.toc-3 a { padding-left: var(--sp-6); font-size: var(--text-xs); }
+
+/* ── Prose typography ──────────────────────────────────────────────────────*/
+.content h2 {
+  font-size: var(--text-xl); letter-spacing: var(--ls-tight);
+  margin: var(--sp-8) 0 var(--sp-3); padding-bottom: var(--sp-2);
+  border-bottom: 1px solid var(--border-light); scroll-margin-top: calc(var(--topbar-h) + var(--sp-3));
+}
+.content h3 {
+  font-size: var(--text-lg); margin: var(--sp-5) 0 var(--sp-2);
+  scroll-margin-top: calc(var(--topbar-h) + var(--sp-3));
+}
+.content p { margin: var(--sp-3) 0; line-height: var(--lh-relaxed); }
+.content ul, .content ol { margin: var(--sp-3) 0; padding-left: var(--sp-6); }
+.content li { margin: var(--sp-1) 0; line-height: var(--lh-relaxed); }
+.content blockquote {
+  margin: var(--sp-3) 0; padding: var(--sp-1) var(--sp-4);
+  border-left: 3px solid var(--border); color: var(--text-muted);
+}
+
+/* ── Inline code + code blocks (chrome.ts wraps <pre> in .code + .copy-btn) ──*/
+.content code {
+  font-family: var(--font-mono); font-size: 0.85em;
+  background: var(--bg-inset); padding: 0.12em 0.4em; border-radius: var(--radius-sm);
+}
+.content .code { position: relative; margin: var(--sp-3) 0; }
+.content .code pre {
+  margin: 0; padding: var(--sp-3) var(--sp-4); overflow-x: auto;
+  background: var(--bg-inset); border: 1px solid var(--border-light);
+  border-radius: var(--radius-sm); font-family: var(--font-mono);
+  font-size: var(--text-sm); line-height: var(--lh-relaxed);
+}
+.content .code pre code { background: none; padding: 0; font-size: inherit; }
+.copy-btn {
+  position: absolute; top: var(--sp-1); right: var(--sp-1);
+  background: var(--bg-card); border: 1px solid var(--border); color: var(--text-muted);
+  border-radius: var(--radius-sm); font-size: var(--text-xs); padding: var(--sp-1) var(--sp-2);
+  cursor: pointer; opacity: 0.85; font-family: inherit;
+}
+.copy-btn:hover { color: var(--accent); border-color: var(--accent); opacity: 1; }
+
+/* ── Callouts ─ (border-color BEFORE border-left-color so the accent wins) ── */
+.callout {
+  margin: var(--sp-4) 0; padding: var(--sp-3) var(--sp-4);
+  border: 1px solid var(--border); border-left-width: 3px;
+  border-radius: var(--radius-sm); background: var(--bg-card);
+}
+.callout > :first-child { margin-top: 0; }
+.callout > :last-child { margin-bottom: 0; }
+.callout-note, .callout-info { background: var(--blue-bg);   border-color: var(--blue-border);   border-left-color: var(--blue); }
+.callout-tip                 { background: var(--green-bg);  border-color: var(--green-border);  border-left-color: var(--green); }
+.callout-warning             { background: var(--yellow-bg); border-color: var(--yellow-border); border-left-color: var(--yellow); }
+.callout-danger              { background: var(--red-bg);    border-color: var(--red-border);    border-left-color: var(--red); }
+
+/* ── Severity chips (:sev) — tight pill, sub-scale vertical padding ───────── */
+.sev {
+  display: inline-block; font-size: var(--text-xs); font-weight: var(--fw-semi);
+  padding: 1px var(--sp-2); border-radius: 999px; line-height: 1.5;
+  border: 1px solid var(--border); background: var(--bg-inset); color: var(--text-muted);
+  white-space: nowrap;
+}
+.sev-p0   { color: var(--sev-p0);   border-color: var(--sev-p0); }
+.sev-p1   { color: var(--sev-p1);   border-color: var(--sev-p1); }
+.sev-p2   { color: var(--sev-p2);   border-color: var(--sev-p2); }
+.sev-p3   { color: var(--sev-p3);   border-color: var(--sev-p3); }
+.sev-pass { color: var(--sev-pass); border-color: var(--sev-pass); }
+
+/* ── Citations (:cite) — inline provenance refs ──────────────────────────── */
+.fp, .cite-advisory {
+  font-family: var(--font-mono); font-size: 0.82em;
+  padding: 0.05em 0.35em; border-radius: var(--radius-sm);
+  background: var(--bg-inset); border: 1px solid var(--border-light);
+}
+.fp { color: var(--accent); }
+.cite-advisory { color: var(--text-faint); border-style: dashed; }
+
+/* ── Tables + filter-tables ──────────────────────────────────────────────── */
+.content table { width: 100%; border-collapse: collapse; margin: var(--sp-3) 0; font-size: var(--text-sm); }
+.content th, .content td { text-align: left; padding: var(--sp-2) var(--sp-3); border-bottom: 1px solid var(--border-light); vertical-align: top; }
+.content th {
+  color: var(--text-muted); font-weight: var(--fw-semi); font-size: var(--text-xs);
+  text-transform: uppercase; letter-spacing: var(--ls-wide); border-bottom-color: var(--border);
+}
+.content tbody tr:hover { background: var(--bg-hover); }
+.content td code { white-space: nowrap; }
+.filter-table { margin: var(--sp-4) 0; }
+.filter-input {
+  width: 100%; max-width: 320px; margin-bottom: var(--sp-2);
+  padding: var(--sp-2) var(--sp-3); font-family: inherit; font-size: var(--text-sm);
+  color: var(--text); background: var(--bg-card);
+  border: 1px solid var(--border); border-radius: var(--radius-sm);
+}
+.filter-input:focus { border-color: var(--accent); }
+
+/* ── Charts (:::chart) — label + proportional bar (fill carries inline width%) */
+.chart-block { margin: var(--sp-4) 0; }
+.chart-row {
+  display: grid; grid-template-columns: minmax(var(--chart-label-w), 24%) 1fr;
+  align-items: center; gap: var(--sp-3); margin: var(--sp-1) 0;
+}
+.chart-label {
+  font-size: var(--text-sm); color: var(--text-muted); text-align: right;
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.chart-row .chart-bar {
+  height: 0.9em; min-width: 2px; background: var(--accent);
+  border-radius: var(--radius-sm);
+}
+
+/* ── Tabs (::::tabs / :::tab) ─────────────────────────────────────────────── */
+.tabs { margin: var(--sp-4) 0; }
+.tablist { display: flex; flex-wrap: wrap; gap: var(--sp-1); border-bottom: 1px solid var(--border); margin-bottom: var(--sp-3); }
+.tab-btn {
+  background: none; border: none; border-bottom: 2px solid transparent; margin-bottom: -1px;
+  padding: var(--sp-2) var(--sp-3); color: var(--text-muted);
+  font-family: inherit; font-size: var(--text-sm); font-weight: var(--fw-medium); cursor: pointer;
+}
+.tab-btn:hover { color: var(--text); }
+.tab-btn.active { color: var(--accent); border-bottom-color: var(--accent); }
+.tabpane { display: none; }
+.tabpane.active { display: block; }
+
+/* ── Mermaid diagrams ────────────────────────────────────────────────────── */
+.content figure { margin: var(--sp-4) 0; text-align: center; }
+.content figure svg, .content > svg, .content .mermaid svg { max-width: 100%; height: auto; }
+
+/* ── Index page: category card grid ──────────────────────────────────────── */
+.content .lead { color: var(--text-muted); font-size: var(--text-base); max-width: 60ch; margin-top: var(--sp-2); }
+.guide-cards {
+  display: grid; grid-template-columns: repeat(auto-fill, minmax(min(var(--card-min), 100%), 1fr));
+  gap: var(--sp-4); margin: var(--sp-4) 0 var(--sp-6);
+}
+.guide-card {
+  display: flex; flex-direction: column; gap: var(--sp-2);
+  padding: var(--sp-4); background: var(--bg-card);
+  border: 1px solid var(--border); border-radius: var(--radius);
+  color: inherit; text-decoration: none;
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+.guide-card:hover { border-color: var(--accent); box-shadow: var(--shadow-md); text-decoration: none; }
+.guide-card-title { font-weight: var(--fw-semi); color: var(--accent); font-size: var(--text-base); }
+.guide-card-desc { color: var(--text-muted); font-size: var(--text-sm); line-height: var(--lh-normal); }
+
+/* ── Responsive: TOC becomes an off-canvas drawer (chrome.ts toggles .open) ──*/
+/* 860px is literal — media queries cannot read custom properties. Revisit it if
+   --topbar-h / --rail-w / --drawer-w change (the drawer sticky offsets key off them). */
+@media (max-width: 860px) {
+  .nav-toggle { display: inline-flex; align-items: center; }
+  .layout { grid-template-columns: 1fr; gap: 0; }
+  .rail {
+    position: fixed; top: var(--topbar-h); left: 0; bottom: 0; width: var(--drawer-w); z-index: 50;
+    height: auto; background: var(--bg-card); border-right: 1px solid var(--border);
+    padding: var(--sp-4); box-shadow: var(--shadow-lg);
+    transform: translateX(-100%); transition: transform 0.2s ease, visibility 0.2s ease;
+    /* Closed drawer is off-screen AND removed from tab order / pointer events. */
+    visibility: hidden; pointer-events: none;
+  }
+  .rail.open { transform: translateX(0); visibility: visible; pointer-events: auto; }
+  .rail-close {
+    display: block; margin-left: auto; margin-bottom: var(--sp-2);
+    background: var(--bg-card); border: 1px solid var(--border); color: var(--text);
+    border-radius: var(--radius-sm); padding: var(--sp-1) var(--sp-3); font-size: var(--text-base);
+    line-height: 1; cursor: pointer; font-family: inherit;
+  }
+  .rail-close:hover { background: var(--bg-hover); border-color: var(--accent); }
+  .rail-close:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+  .rail-backdrop {
+    display: block; position: fixed; inset: var(--topbar-h) 0 0 0;
+    background: var(--scrim); z-index: 49;
+    opacity: 0; pointer-events: none; transition: opacity 0.2s ease;
+  }
+  .rail.open ~ .rail-backdrop { opacity: 1; pointer-events: auto; }
+}
 </style>
 <script>(function(){try{var t=localStorage.getItem('guide-theme');if(!t&&window.matchMedia&&matchMedia('(prefers-color-scheme: dark)').matches)t='dark';if(t)document.documentElement.setAttribute('data-theme',t);}catch(e){}})();</script>
 </head>
 <body>
 <header class="topbar">
-  <button data-action="nav" class="nav-toggle" aria-label="Toggle navigation">☰</button>
+  <button data-action="nav" class="nav-toggle" aria-label="Toggle navigation"
+    aria-expanded="false" aria-controls="guide-toc">☰</button>
   <h1>MMR Reference</h1>
   <button data-action="theme" class="theme-toggle" aria-label="Toggle theme">◐</button>
 </header>
 <div class="layout">
-  <aside class="rail"><nav class="toc" aria-label="Table of contents"><ul><li class="toc-2"><a href="#what-mmr-is">What MMR is</a></li><li class="toc-3"><a href="#the-core-idea-in-five-moves">The core idea in five moves</a></li><li class="toc-2"><a href="#end-to-end-flow">End-to-end flow</a></li><li class="toc-2"><a href="#the-mmr-review-command">The mmr review command</a></li><li class="toc-3"><a href="#copy-paste-commands-by-target">Copy-paste commands by target</a></li><li class="toc-2"><a href="#other-subcommands">Other subcommands</a></li><li class="toc-2"><a href="#channel-architecture">Channel architecture</a></li><li class="toc-3"><a href="#the-channel-config-shape">The channel config shape</a></li><li class="toc-3"><a href="#built-in-channels">Built-in channels</a></li><li class="toc-3"><a href="#the-dispatcher">The dispatcher</a></li><li class="toc-2"><a href="#scaffold-wrappers">Scaffold wrappers</a></li><li class="toc-2"><a href="#findings-reconciliation-verdicts">Findings, reconciliation &amp; verdicts</a></li><li class="toc-3"><a href="#the-finding-shape">The Finding shape</a></li><li class="toc-3"><a href="#stable-identity-finding-key">Stable identity (finding_key)</a></li><li class="toc-3"><a href="#agreement-confidence">Agreement &amp; confidence</a></li><li class="toc-3"><a href="#the-gate-the-four-verdicts">The gate &amp; the four verdicts</a></li><li class="toc-2"><a href="#degraded-mode-compensation-auth">Degraded mode, compensation &amp; auth</a></li><li class="toc-2"><a href="#configuration-mmryaml">Configuration (.mmr.yaml)</a></li></ul></nav></aside>
+  <aside class="rail" id="guide-toc">
+    <button class="rail-close" data-action="nav" aria-label="Close navigation">✕</button>
+    <nav class="toc" aria-label="Table of contents"><ul><li class="toc-2"><a href="#what-mmr-is">What MMR is</a></li><li class="toc-3"><a href="#the-core-idea-in-five-moves">The core idea in five moves</a></li><li class="toc-2"><a href="#end-to-end-flow">End-to-end flow</a></li><li class="toc-2"><a href="#the-mmr-review-command">The mmr review command</a></li><li class="toc-3"><a href="#copy-paste-commands-by-target">Copy-paste commands by target</a></li><li class="toc-2"><a href="#other-subcommands">Other subcommands</a></li><li class="toc-2"><a href="#channel-architecture">Channel architecture</a></li><li class="toc-3"><a href="#the-channel-config-shape">The channel config shape</a></li><li class="toc-3"><a href="#built-in-channels">Built-in channels</a></li><li class="toc-3"><a href="#the-dispatcher">The dispatcher</a></li><li class="toc-2"><a href="#scaffold-wrappers">Scaffold wrappers</a></li><li class="toc-2"><a href="#findings-reconciliation-verdicts">Findings, reconciliation &amp; verdicts</a></li><li class="toc-3"><a href="#the-finding-shape">The Finding shape</a></li><li class="toc-3"><a href="#stable-identity-finding-key">Stable identity (finding_key)</a></li><li class="toc-3"><a href="#agreement-confidence">Agreement &amp; confidence</a></li><li class="toc-3"><a href="#the-gate-the-four-verdicts">The gate &amp; the four verdicts</a></li><li class="toc-2"><a href="#degraded-mode-compensation-auth">Degraded mode, compensation &amp; auth</a></li><li class="toc-2"><a href="#configuration-mmryaml">Configuration (.mmr.yaml)</a></li></ul></nav>
+  </aside>
   <main class="content"><h2 id="what-mmr-is">What MMR is</h2>
 <p>Multi-Model Review runs your changes past several <strong>independent</strong> AI code
 reviewers ("channels"), then <strong>reconciles</strong> their findings into a single
@@ -1099,12 +1380,12 @@ disagreement is what surfaces ambiguity.</p>
 <ol>
 <li><strong>Resolve a diff</strong> — from a PR, staged changes, a branch range, or a piped diff.</li>
 <li><strong>Dispatch channels</strong> — each channel is a separate subprocess given the same
-prompt, run in parallel and isolated.</li>
+prompt, run in parallel and isolated <span class="fp" data-path="packages/mmr/src/commands/review.ts:636">packages/mmr/src/commands/review.ts:636</span>.</li>
 <li><strong>Parse</strong> — each channel's raw output is parsed into a common <code>Finding</code> shape.</li>
 <li><strong>Reconcile</strong> — findings are grouped by a stable key, de-duplicated, and
-scored for agreement and confidence.</li>
+scored for agreement and confidence <span class="fp" data-path="packages/mmr/src/core/reconciler.ts:43">packages/mmr/src/core/reconciler.ts:43</span>.</li>
 <li><strong>Verdict</strong> — a severity gate yields <code>pass</code>, <code>degraded-pass</code>, <code>blocked</code>, or
-<code>needs-user-decision</code>.</li>
+<code>needs-user-decision</code> <span class="fp" data-path="packages/mmr/src/types.ts:25">packages/mmr/src/types.ts:25</span>.</li>
 </ol>
 <div class="callout callout-tip"><p><strong>Two layers, one mental model.</strong> The <code>mmr</code> CLI is the engine that dispatches
 the built-in channels and computes the verdict. The <code>scaffold run review-pr</code> /
@@ -1231,7 +1512,7 @@ table.</p>
 
 
 
-<table><thead><tr><th>Flag</th><th>Group</th><th>Description</th></tr></thead><tbody><tr><td><code>--diff &#x3C;path|-></code></td><td>input</td><td>Read a unified diff from a file, or <code>-</code> for stdin. Highest-priority input mode.</td></tr><tr><td><code>--pr &#x3C;n></code></td><td>input</td><td>Fetch the PR diff via <code>gh pr diff</code>.</td></tr><tr><td><code>--staged</code></td><td>input</td><td>Review staged changes (<code>git diff --cached</code>).</td></tr><tr><td><code>--base &#x3C;ref> [--head &#x3C;ref>]</code></td><td>input</td><td>Review a branch range (<code>git diff base...head</code>, head defaults to HEAD).</td></tr><tr><td><em>(no input flag)</em></td><td>input</td><td>Falls back to unstaged working-tree changes (<code>git diff</code>).</td></tr><tr><td><code>--focus &#x3C;text></code></td><td>control</td><td>Free-text focus areas appended to every channel prompt.</td></tr><tr><td><code>--fix-threshold &#x3C;P0|P1|P2|P3></code></td><td>control</td><td>Severity gate. Findings at or above this block. Default P2 (from <code>.mmr.yaml</code>).</td></tr><tr><td><code>--channels &#x3C;names…></code></td><td>control</td><td>Run only these channels, overriding config defaults. Abstract channels are filtered out.</td></tr><tr><td><code>--timeout &#x3C;seconds></code></td><td>control</td><td>Per-channel timeout override.</td></tr><tr><td><code>--template &#x3C;name></code></td><td>control</td><td>Use a named review-criteria template from config.</td></tr><tr><td><code>--format &#x3C;json|text|markdown></code></td><td>output</td><td>Output format. Default <code>json</code>.</td></tr><tr><td><code>--sync</code></td><td>mode</td><td>Run the full pipeline (dispatch → parse → reconcile → verdict) and return results. Without it, dispatch is fire-and-forget.</td></tr><tr><td><code>--dry-run</code></td><td>mode</td><td>Resolve the diff and assemble the prompt without dispatching any channel.</td></tr><tr><td><code>--session &#x3C;id></code></td><td>rounds</td><td>Link this run into a multi-round session (<code>[A-Za-z0-9_-]</code>).</td></tr><tr><td><code>--round &#x3C;n></code></td><td>rounds</td><td>1-based round counter within a session.</td></tr><tr><td><code>--max-rounds &#x3C;n></code></td><td>rounds</td><td>Hard cap on rounds. Defaults to 5 when <code>--session</code> is set without it.</td></tr><tr><td><code>--accept-new-acks</code></td><td>trust</td><td>Trust acknowledgment files newly introduced by the diff.</td></tr><tr><td><code>--trust-project-acks</code></td><td>trust</td><td>Trust working-tree project acks in non-Git / untrusted modes.</td></tr><tr><td><code>--trust-project-config</code></td><td>trust</td><td>Trust working-tree <code>.mmr.yaml</code> in untrusted modes.</td></tr><tr><td><code>--config-base-ref &#x3C;ref></code></td><td>trust</td><td>Load <code>.mmr.yaml</code> and acks from a trusted Git ref instead of HEAD.</td></tr></tbody></table></div>
+<table><thead><tr><th>Flag</th><th>Group</th><th>Description</th></tr></thead><tbody><tr><td><code>--diff &#x3C;path|-></code></td><td>input</td><td>Read a unified diff from a file, or <code>-</code> for stdin. Highest-priority input mode.</td></tr><tr><td><code>--pr &#x3C;n></code></td><td>input</td><td>Fetch the PR diff via <code>gh pr diff</code>.</td></tr><tr><td><code>--staged</code></td><td>input</td><td>Review staged changes (<code>git diff --cached</code>).</td></tr><tr><td><code>--base &#x3C;ref> [--head &#x3C;ref>]</code></td><td>input</td><td>Review a branch range (<code>git diff base...head</code>, head defaults to HEAD).</td></tr><tr><td><em>(no input flag)</em></td><td>input</td><td>Falls back to unstaged working-tree changes (<code>git diff</code>).</td></tr><tr><td><code>--focus &#x3C;text></code></td><td>control</td><td>Free-text focus areas appended to every channel prompt.</td></tr><tr><td><code>--fix-threshold &#x3C;P0|P1|P2|P3></code></td><td>control</td><td>Severity gate. Findings at or above this block. Default P2 (from <code>.mmr.yaml</code>).</td></tr><tr><td><code>--channels &#x3C;names…></code></td><td>control</td><td>Run only these channels, overriding config defaults. Abstract channels are filtered out.</td></tr><tr><td><code>--timeout &#x3C;seconds></code></td><td>control</td><td>Per-channel timeout override.</td></tr><tr><td><code>--template &#x3C;name></code></td><td>control</td><td>Use a named review-criteria template from config.</td></tr><tr><td><code>--format &#x3C;json|text|markdown></code></td><td>output</td><td>Output format. Default <code>json</code>.</td></tr><tr><td><code>--sync</code></td><td>mode</td><td>Run the full pipeline (dispatch → parse → reconcile → verdict) and return results. Without it, dispatch is fire-and-forget.</td></tr><tr><td><code>--dry-run</code></td><td>mode</td><td>Resolve the diff and assemble the prompt without dispatching any channel.</td></tr><tr><td><code>--session &#x3C;id></code></td><td>rounds</td><td>Link this run into a multi-round session; the id must match <code>^[A-Za-z0-9_-]+$</code> and not be a reserved name <span class="fp" data-path="packages/mmr/src/commands/sessions.ts:15">packages/mmr/src/commands/sessions.ts:15</span>.</td></tr><tr><td><code>--round &#x3C;n></code></td><td>rounds</td><td>1-based round counter within a session.</td></tr><tr><td><code>--max-rounds &#x3C;n></code></td><td>rounds</td><td>Hard cap on rounds. Defaults to 5 when <code>--session</code> is set without it.</td></tr><tr><td><code>--accept-new-acks</code></td><td>trust</td><td>Trust acknowledgment files newly introduced by the diff.</td></tr><tr><td><code>--trust-project-acks</code></td><td>trust</td><td>Trust working-tree project acks in non-Git / untrusted modes.</td></tr><tr><td><code>--trust-project-config</code></td><td>trust</td><td>Trust working-tree <code>.mmr.yaml</code> in untrusted modes.</td></tr><tr><td><code>--config-base-ref &#x3C;ref></code></td><td>trust</td><td>Load <code>.mmr.yaml</code> and acks from a trusted Git ref instead of HEAD.</td></tr></tbody></table></div>
 <h3 id="copy-paste-commands-by-target">Copy-paste commands by target</h3>
 <pre><code class="language-bash"># PR review (full pipeline, JSON out)
 mmr review --pr 123 --sync --format json
@@ -1289,7 +1570,7 @@ mmr review --pr 123 --channels grok claude --sync --format json
 
 
 
-<table><thead><tr><th>Command</th><th>Purpose</th></tr></thead><tbody><tr><td><code>mmr reconcile &#x3C;job-id> --channel &#x3C;name> --input &#x3C;data></code></td><td>Inject an external channel's findings (e.g. the Superpowers agent) into an existing job and re-run the results pipeline. Input is a file, <code>-</code> for stdin, or inline JSON.</td></tr><tr><td><code>mmr status &#x3C;job-id></code></td><td>Per-channel status and elapsed time. Exit 0 = all complete, 1 = running, 2 = a channel failed, 5 = not found.</td></tr><tr><td><code>mmr results &#x3C;job-id> [--raw]</code></td><td>Re-run parse → reconcile → format on a completed job. Exit code reflects the verdict.</td></tr><tr><td><code>mmr jobs &#x3C;list|prune></code></td><td>List jobs, or prune old ones per <code>job_retention_days</code>.</td></tr><tr><td><code>mmr sessions &#x3C;start|list|show|end> &#x3C;id></code></td><td>Manage multi-round review sessions (stored under <code>~/.mmr/sessions/</code>).</td></tr><tr><td><code>mmr config &#x3C;init|show|validate…></code></td><td>Scaffold and inspect <code>.mmr.yaml</code> (including OSS-runtime example blocks).</td></tr><tr><td><code>mmr ack &#x3C;add|list|rm|prune></code></td><td>Sticky acknowledgments — silence a finding by its stable key so it stops blocking across rounds.</td></tr></tbody></table>
+<table><thead><tr><th>Command</th><th>Purpose</th></tr></thead><tbody><tr><td><code>mmr reconcile &#x3C;job-id> --channel &#x3C;name> --input &#x3C;data></code></td><td>Inject an external channel's findings (e.g. the Superpowers agent) into an existing job and re-run the results pipeline. Input is a file, <code>-</code> for stdin, or inline JSON. <span class="fp" data-path="packages/mmr/src/commands/reconcile.ts:17">packages/mmr/src/commands/reconcile.ts:17</span></td></tr><tr><td><code>mmr status &#x3C;job-id></code></td><td>Per-channel status and elapsed time. Exit 0 = all complete, 1 = running, 2 = a channel failed, 5 = not found.</td></tr><tr><td><code>mmr results &#x3C;job-id> [--raw]</code></td><td>Re-run parse → reconcile → format on a completed job. Exit code reflects the verdict.</td></tr><tr><td><code>mmr jobs &#x3C;list|prune></code></td><td>List jobs, or prune old ones per <code>job_retention_days</code>.</td></tr><tr><td><code>mmr sessions &#x3C;start|list|show|end> &#x3C;id></code></td><td>Manage multi-round review sessions (stored under <code>~/.mmr/sessions/</code>).</td></tr><tr><td><code>mmr config &#x3C;init|show|validate…></code></td><td>Scaffold and inspect <code>.mmr.yaml</code> (including OSS-runtime example blocks).</td></tr><tr><td><code>mmr ack &#x3C;add|list|rm|prune></code></td><td>Sticky acknowledgments — silence a finding by its stable key so it stops blocking across rounds.</td></tr></tbody></table>
 <pre><code class="language-bash"># Capture a job_id from a review, then fold in an agent channel:
 mmr reconcile "$JOB_ID" --channel superpowers --input findings.json
 </code></pre>
@@ -1321,7 +1602,7 @@ uses <code>prompt_delivery: prompt-file</code> — the dispatcher writes the pro
 file and passes its path via the <code>{{prompt_file}}</code> placeholder. Grok wraps its
 reply in a JSON <code>.text</code> field, which the parser unwraps before extracting
 findings.</p></div>
-<div class="tabs"><div class="tablist" role="tablist"><button class="tab-btn active" role="tab" data-tab="0">Compare</button><button class="tab-btn" role="tab" data-tab="1">codex</button><button class="tab-btn" role="tab" data-tab="2">gemini</button><button class="tab-btn" role="tab" data-tab="3">claude</button><button class="tab-btn" role="tab" data-tab="4">grok</button><button class="tab-btn" role="tab" data-tab="5">doc-conformance</button></div><div class="tabpane active" data-tab="0">
+<div class="tabs"><div class="tablist" role="tablist"><button id="tab-0-0" class="tab-btn active" role="tab" data-tab="0" aria-controls="tabpane-0-0" aria-selected="true" tabindex="0">Compare</button><button id="tab-0-1" class="tab-btn" role="tab" data-tab="1" aria-controls="tabpane-0-1" aria-selected="false" tabindex="-1">codex</button><button id="tab-0-2" class="tab-btn" role="tab" data-tab="2" aria-controls="tabpane-0-2" aria-selected="false" tabindex="-1">gemini</button><button id="tab-0-3" class="tab-btn" role="tab" data-tab="3" aria-controls="tabpane-0-3" aria-selected="false" tabindex="-1">claude</button><button id="tab-0-4" class="tab-btn" role="tab" data-tab="4" aria-controls="tabpane-0-4" aria-selected="false" tabindex="-1">grok</button><button id="tab-0-5" class="tab-btn" role="tab" data-tab="5" aria-controls="tabpane-0-5" aria-selected="false" tabindex="-1">doc-conformance</button></div><div id="tabpane-0-0" class="tabpane active" role="tabpanel" data-tab="0" aria-labelledby="tab-0-0" tabindex="0"><p>The defaults, commands, and parsers below are the built-in presets <span class="fp" data-path="packages/mmr/src/config/defaults.ts:32">packages/mmr/src/config/defaults.ts:32</span>.</p>
 
 
 
@@ -1368,25 +1649,25 @@ findings.</p></div>
 
 
 
-<table><thead><tr><th>Channel</th><th>Default</th><th>Strength</th><th>Prompt delivery</th><th>Parser</th></tr></thead><tbody><tr><td><code>codex</code></td><td>enabled</td><td>Correctness, security, API contracts</td><td>stdin</td><td><code>default</code></td></tr><tr><td><code>gemini</code></td><td>enabled</td><td>Architecture, broad-context reasoning</td><td>stdin</td><td><code>gemini</code></td></tr><tr><td><code>claude</code></td><td>enabled</td><td>Plan alignment, code quality, testing</td><td>stdin</td><td><code>default</code></td></tr><tr><td><code>grok</code></td><td>enabled</td><td>Independent second opinion (xAI; proprietary)</td><td><strong>prompt-file</strong></td><td><code>unwrap $.text → default</code></td></tr><tr><td><code>doc-conformance</code></td><td>opt-in</td><td>PRD/stories/standards conformance (LLM-graded)</td><td>stdin</td><td><code>doc-conformance</code></td></tr></tbody></table></div><div class="tabpane" data-tab="1"><pre><code class="language-yaml">command: codex exec
+<table><thead><tr><th>Channel</th><th>Default</th><th>Strength</th><th>Prompt delivery</th><th>Parser</th></tr></thead><tbody><tr><td><code>codex</code></td><td>enabled</td><td>Correctness, security, API contracts</td><td>stdin</td><td><code>default</code></td></tr><tr><td><code>gemini</code></td><td>enabled</td><td>Architecture, broad-context reasoning</td><td>stdin</td><td><code>gemini</code></td></tr><tr><td><code>claude</code></td><td>enabled</td><td>Plan alignment, code quality, testing</td><td>stdin</td><td><code>default</code></td></tr><tr><td><code>grok</code></td><td>enabled</td><td>Independent second opinion (xAI; proprietary)</td><td><strong>prompt-file</strong></td><td><code>unwrap $.text → default</code></td></tr><tr><td><code>doc-conformance</code></td><td>opt-in</td><td>PRD/stories/standards conformance (LLM-graded)</td><td>stdin</td><td><code>doc-conformance</code></td></tr></tbody></table></div><div id="tabpane-0-1" class="tabpane" role="tabpanel" data-tab="1" aria-labelledby="tab-0-1" tabindex="0"><pre><code class="language-yaml">command: codex exec
 flags: [--skip-git-repo-check, -s, read-only, --ephemeral]
 auth.check: codex login status        # local file check (fast, 5s)
 recovery: codex login
 output_parser: default
 stderr: suppress
-</code></pre></div><div class="tabpane" data-tab="2"><pre><code class="language-yaml">command: gemini                       # NO -p: gemini reads stdin natively
+</code></pre></div><div id="tabpane-0-2" class="tabpane" role="tabpanel" data-tab="2" aria-labelledby="tab-0-2" tabindex="0"><pre><code class="language-yaml">command: gemini                       # NO -p: gemini reads stdin natively
 flags: [--output-format, json]
 env: { NO_BROWSER: "true" }
 auth.check: NO_BROWSER=true gemini -p "respond with ok" -o json   # LLM round-trip, 20s
 recovery: gemini -p "hello"
 output_parser: gemini                 # unwraps { "response": "…" }
 timeout: 360
-</code></pre></div><div class="tabpane" data-tab="3"><pre><code class="language-yaml">command: claude -p
+</code></pre></div><div id="tabpane-0-3" class="tabpane" role="tabpanel" data-tab="3" aria-labelledby="tab-0-3" tabindex="0"><pre><code class="language-yaml">command: claude -p
 flags: [--output-format, json]
 auth.check: claude -p "respond with ok"   # LLM round-trip, 20s
 recovery: claude login
 output_parser: default
-</code></pre></div><div class="tabpane" data-tab="4"><pre><code class="language-yaml">command: grok
+</code></pre></div><div id="tabpane-0-4" class="tabpane" role="tabpanel" data-tab="4" aria-labelledby="tab-0-4" tabindex="0"><pre><code class="language-yaml">command: grok
 prompt_delivery: prompt-file
 flags: [--prompt-file, "{{prompt_file}}", --output-format, json]
 auth.check: grok models                # lists models / login state (no round-trip)
@@ -1394,7 +1675,7 @@ recovery: grok login
 output_parser: { kind: unwrap-jsonpath, wrap: "$.text", then: default }
 </code></pre><p>Grok is proprietary (xAI), not open-source — it joins the standard set
 mechanically as a 4th CLI channel. Disable it with
-<code>channels_disabled: ["grok"]</code>.</p></div><div class="tabpane" data-tab="5"><pre><code class="language-yaml">enabled: false                         # opt-in: runs up to 3 LLM calls (~3 min)
+<code>channels_disabled: ["grok"]</code>.</p></div><div id="tabpane-0-5" class="tabpane" role="tabpanel" data-tab="5" aria-labelledby="tab-0-5" tabindex="0"><pre><code class="language-yaml">enabled: false                         # opt-in: runs up to 3 LLM calls (~3 min)
 command: scaffold observe audit --profile=full --scope=all --output-mode=mmr-findings
 output_parser: doc-conformance         # expects a JSON array of findings
 timeout: 240
@@ -1405,7 +1686,8 @@ timeout: 240
 to its own output file; channels run in parallel and never share output.</li>
 <li><strong>Prompt delivery.</strong> <code>stdin</code> mode pipes the prompt and closes stdin (avoids
 <code>E2BIG</code> on large diffs). <code>prompt-file</code> mode writes the prompt to
-<code>&#x3C;channel>.prompt.txt</code> and substitutes <code>{{prompt_file}}</code> in the flags.</li>
+<code>&#x3C;channel>.prompt.txt</code> and substitutes <code>{{prompt_file}}</code> in the flags
+<span class="fp" data-path="packages/mmr/src/core/dispatcher.ts:79">packages/mmr/src/core/dispatcher.ts:79</span>.</li>
 <li><strong>Timeout.</strong> A per-channel timer SIGKILLs the whole process group and marks
 the channel <code>timeout</code>.</li>
 <li><strong>Command parsing.</strong> <code>command</code> is split on whitespace and spawned without a
@@ -1417,10 +1699,12 @@ only):</em> a new subprocess channel (<code>command</code> + <code>flags</code>
 <code>output_parser</code>), output reshaping via the <code>unwrap-jsonpath</code> or
 <code>regex-findings</code> parser kinds, disabling/timeout overrides, and pointing the
 compensator at a different channel — all pure <code>.mmr.yaml</code>. <em>Needs code:</em> a
-brand-new <em>named</em> parser must be registered in <code>core/parser.ts</code>; HTTP-endpoint
-channels (<code>kind: http</code>) need the planned http-dispatcher; and the
+brand-new <em>named</em> parser must be registered in <code>core/parser.ts</code>
+<span class="cite-advisory" data-path="packages/mmr/src/core/parser.ts:257">packages/mmr/src/core/parser.ts:257</span>; and the
 <code>COMPENSATING_FOCUS</code> map carries per-channel focus text (falls back gracefully
-if absent).</p>
+if absent). HTTP-endpoint channels (<code>kind: http</code>) are already supported via
+<code>dispatchHttpChannel</code> — pure <code>.mmr.yaml</code>, no extra code
+<span class="fp" data-path="packages/mmr/src/config/schema.ts:144">packages/mmr/src/config/schema.ts:144</span>.</p>
 <h2 id="scaffold-wrappers">Scaffold wrappers</h2>
 <p>Direct <code>mmr review</code> runs the built-in CLI channels. The <code>scaffold run</code> wrappers
 add orchestration on top.</p>
@@ -1455,6 +1739,8 @@ and Grok as foreground Bash calls when the <code>mmr</code> CLI isn't available
 the background. Background execution produces empty output.</p></div>
 <h2 id="findings-reconciliation-verdicts">Findings, reconciliation &#x26; verdicts</h2>
 <h3 id="the-finding-shape">The Finding shape</h3>
+<p>Every channel's output parses into this common shape
+<span class="fp" data-path="packages/mmr/src/types.ts:45">packages/mmr/src/types.ts:45</span>.</p>
 <pre><code class="language-json">{
   "id": "F-001",
   "category": "security",
@@ -1464,16 +1750,23 @@ the background. Background execution produces empty output.</p></div>
   "suggestion": "…"
 }
 </code></pre>
-<p>After reconciliation, each finding also carries <code>confidence</code>, <code>sources[]</code>,
-<code>agreement</code>, a stable <code>finding_key</code>, a <code>description_shingle</code> (for fuzzy
-cross-round matching), and <code>acknowledged</code>.</p>
+<p>The <code>location</code> above (<code>src/auth.ts:42</code>) is illustrative. After reconciliation,
+each finding also carries <code>confidence</code>, <code>sources[]</code>, <code>agreement</code>, a stable
+<code>finding_key</code>, a <code>description_shingle</code> (for fuzzy cross-round matching), and
+<code>acknowledged</code> <span class="fp" data-path="packages/mmr/src/types.ts:54">packages/mmr/src/types.ts:54</span>.</p>
 <h3 id="stable-identity-finding-key">Stable identity (<code>finding_key</code>)</h3>
 <pre><code class="language-text">finding_key = sha1( normLocation | category | sha1(normDescription) | sha1(normSuggestion) )
 </code></pre>
 <p>Line numbers are stripped from the location and severity is <em>excluded</em>, so the
-same issue at P1 vs P2 collapses to one key. A character-5-gram shingle backs a
-Jaccard ≥ 0.7 fuzzy match when wording drifts between rounds.</p>
+same issue at P1 vs P2 collapses to one key
+<span class="fp" data-path="packages/mmr/src/core/stable-id.ts:115">packages/mmr/src/core/stable-id.ts:115</span>. A character-5-gram shingle backs
+a Jaccard ≥ 0.7 fuzzy match. Intra-run, findings group by fuzzy shingle overlap
+<span class="fp" data-path="packages/mmr/src/core/reconciler.ts:83">packages/mmr/src/core/reconciler.ts:83</span>; across rounds, the ack store reuses
+the same threshold so a re-worded finding still matches a prior ack
+<span class="fp" data-path="packages/mmr/src/core/ack-store.ts:8">packages/mmr/src/core/ack-store.ts:8</span>.</p>
 <h3 id="agreement-confidence">Agreement &#x26; confidence</h3>
+<p>Agreement and confidence are derived per group during reconciliation
+<span class="fp" data-path="packages/mmr/src/core/reconciler.ts:114">packages/mmr/src/core/reconciler.ts:114</span>.</p>
 
 
 
@@ -1518,9 +1811,15 @@ Jaccard ≥ 0.7 fuzzy match when wording drifts between rounds.</p>
 <table><thead><tr><th>Sources</th><th>Severity</th><th>Agreement</th><th>Confidence</th></tr></thead><tbody><tr><td>2+</td><td>same</td><td>consensus</td><td>high</td></tr><tr><td>2+</td><td>differ</td><td>majority</td><td>medium</td></tr><tr><td>1</td><td><span class="sev sev-p0">P0</span></td><td>unique</td><td>high</td></tr><tr><td>1</td><td><code>compensating-*</code></td><td>unique</td><td>low</td></tr><tr><td>1</td><td>other</td><td>unique</td><td>medium</td></tr></tbody></table>
 <h3 id="the-gate-the-four-verdicts">The gate &#x26; the four verdicts</h3>
 <p>The gate <strong>passes</strong> when every unacknowledged finding is <em>below</em> the
-<code>fix_threshold</code> (default <span class="sev sev-p2">P2</span>). Severity tiers run
+<code>fix_threshold</code> <span class="fp" data-path="packages/mmr/src/core/reconciler.ts:229">packages/mmr/src/core/reconciler.ts:229</span> (default
+<span class="sev sev-p2">P2</span> <span class="fp" data-path="packages/mmr/src/config/defaults.ts:16">packages/mmr/src/config/defaults.ts:16</span>). Severity tiers run
 <span class="sev sev-p0">P0</span> (highest) → <span class="sev sev-p1">P1</span> → <span class="sev sev-p2">P2</span> →
 <span class="sev sev-p3">P3</span> (lowest).</p>
+<p>The verdict is derived from gate result + channel health, in this branch order:
+<strong>zero channels completed → <code>needs-user-decision</code></strong>; else a failed gate →
+<code>blocked</code>; else some channels incomplete → <code>degraded-pass</code>; else <code>pass</code>
+<span class="fp" data-path="packages/mmr/src/core/reconciler.ts:247">packages/mmr/src/core/reconciler.ts:247</span>. (The no-completed-channels case
+short-circuits first, so it outranks <code>blocked</code>.)</p>
 
 
 
@@ -1622,7 +1921,7 @@ channels:
 when you pass an explicit <code>--channels</code> list).</li>
 <li><code>enabled: false</code> — per-channel off switch (how <code>doc-conformance</code> ships).</li>
 <li><code>extends</code> — inherit from another channel (≤ 4 levels, cycle-checked); child
-fields override the parent.</li>
+fields override the parent <span class="fp" data-path="packages/mmr/src/config/loader.ts:145">packages/mmr/src/config/loader.ts:145</span>.</li>
 <li><code>fix_threshold</code> — project gate; override per-run with <code>--fix-threshold</code>.</li>
 </ul>
 <div class="callout callout-danger"><p><strong>Trust boundary.</strong> When reviewing a diff, project <code>.mmr.yaml</code> and acks should
@@ -1630,6 +1929,7 @@ be read from the diff's <em>base ref</em>, not the working tree — otherwise a
 add a channel that exfiltrates secrets or self-acknowledge its own findings. Use
 <code>--config-base-ref</code> / the <code>--trust-project-*</code> flags to control this in untrusted
 (e.g. CI) contexts.</p></div></main>
+  <div class="rail-backdrop" data-action="nav" aria-hidden="true"></div>
 </div>
 <script>(function(){
   var LS_KEY = 'guide-theme';
@@ -1648,12 +1948,69 @@ add a channel that exfiltrates secrets or self-acknowledge its own findings. Use
       });
     });
 
-    // ─── Mobile nav ──────────────────────────────────────────────────────────
+    // ─── Mobile nav (drawer + backdrop; aria-expanded + Escape-to-close) ──────
+    function setNav(open) {
+      var rail = document.querySelector('.rail');
+      if (rail) rail.classList.toggle('open', open);
+      var toggle = document.querySelector('.nav-toggle');
+      if (toggle) toggle.setAttribute('aria-expanded', open ? 'true' : 'false');
+      // Modal-drawer focus containment: while open, make the page content inert
+      // (out of tab order + a11y tree) and move focus into the drawer; on close,
+      // restore content and return focus to the toggle.
+      var main = document.querySelector('.content');
+      if (main) main.inert = open;
+      if (open) {
+        var first = rail && rail.querySelector('a, button, [tabindex]:not([tabindex="-1"])');
+        if (first) first.focus();
+        else if (rail) { rail.setAttribute('tabindex', '-1'); rail.focus(); }
+      } else if (toggle) {
+        toggle.focus();
+      }
+    }
+    // If the viewport grows past the mobile breakpoint while the drawer is open,
+    // the rail becomes the desktop sidebar and the toggle hides — clear the open
+    // state so .content doesn't stay inert with no way to close it.
+    if (window.matchMedia) {
+      var mq = window.matchMedia('(max-width: 860px)');
+      var onMq = function() {
+        if (mq.matches) return;
+        var rail = document.querySelector('.rail');
+        if (rail) rail.classList.remove('open');
+        var toggle = document.querySelector('.nav-toggle');
+        if (toggle) toggle.setAttribute('aria-expanded', 'false');
+        var main = document.querySelector('.content');
+        if (main) main.inert = false;
+      };
+      if (mq.addEventListener) mq.addEventListener('change', onMq);
+      else if (mq.addListener) mq.addListener(onMq);
+    }
     document.querySelectorAll('[data-action="nav"]').forEach(function(btn) {
       btn.addEventListener('click', function() {
         var rail = document.querySelector('.rail');
-        if (rail) rail.classList.toggle('open');
+        setNav(!(rail && rail.classList.contains('open')));
+      });
+    });
+    // Selecting a TOC link closes the drawer (so the now-active content isn't
+    // left inert behind the panel) before the anchor navigation scrolls.
+    var drawerRail = document.querySelector('.rail');
+    if (drawerRail) {
+      drawerRail.querySelectorAll('a').forEach(function(a) {
+        a.addEventListener('click', function() {
+          if (drawerRail.classList.contains('open')) setNav(false);
+        });
       });
+    }
+    document.addEventListener('keydown', function(e) {
+      var rail = document.querySelector('.rail');
+      if (!rail || !rail.classList.contains('open')) return;
+      if (e.key === 'Escape') { setNav(false); return; } // setNav restores focus to the toggle
+      // Trap Tab within the open drawer (modal pattern).
+      if (e.key !== 'Tab') return;
+      var f = rail.querySelectorAll('a[href], button, [tabindex]:not([tabindex="-1"])');
+      if (!f.length) return;
+      var first = f[0], last = f[f.length - 1];
+      if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+      else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
     });
 
     // ─── Copy buttons ─────────────────────────────────────────────────────────
@@ -1680,17 +2037,31 @@ add a channel that exfiltrates secrets or self-acknowledge its own findings. Use
       wrapper.insertBefore(btn, pre);
     });
 
-    // ─── Tabs ─────────────────────────────────────────────────────────────────
+    // ─── Tabs (ARIA pattern: aria-selected + roving tabindex + arrow keys) ────
+    function activateTab(group, btn, focus) {
+      var idx = btn.getAttribute('data-tab');
+      group.querySelectorAll('.tab-btn').forEach(function(b) {
+        var on = b === btn;
+        b.classList.toggle('active', on);
+        b.setAttribute('aria-selected', on ? 'true' : 'false');
+        b.setAttribute('tabindex', on ? '0' : '-1');
+      });
+      group.querySelectorAll('.tabpane').forEach(function(pane) {
+        pane.classList.toggle('active', pane.getAttribute('data-tab') === idx);
+      });
+      if (focus) btn.focus();
+    }
     document.querySelectorAll('.tabs').forEach(function(group) {
-      group.querySelectorAll('.tab-btn').forEach(function(btn) {
-        btn.addEventListener('click', function() {
-          var idx = btn.getAttribute('data-tab');
-          group.querySelectorAll('.tab-btn').forEach(function(b) {
-            b.classList.toggle('active', b === btn);
-          });
-          group.querySelectorAll('.tabpane').forEach(function(pane) {
-            pane.classList.toggle('active', pane.getAttribute('data-tab') === idx);
-          });
+      var btns = [].slice.call(group.querySelectorAll('.tab-btn'));
+      btns.forEach(function(btn, i) {
+        btn.addEventListener('click', function() { activateTab(group, btn, false); });
+        btn.addEventListener('keydown', function(e) {
+          var ni = -1;
+          if (e.key === 'ArrowRight' || e.key === 'ArrowDown') ni = (i + 1) % btns.length;
+          else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') ni = (i - 1 + btns.length) % btns.length;
+          else if (e.key === 'Home') ni = 0;
+          else if (e.key === 'End') ni = btns.length - 1;
+          if (ni >= 0) { e.preventDefault(); activateTab(group, btns[ni], true); }
         });
       });
     });