diff --git a/apps/web/app/demo.tsx b/apps/web/app/demo.tsx
index 38b99cf..cd12614 100644
--- a/apps/web/app/demo.tsx
+++ b/apps/web/app/demo.tsx
@@ -1,87 +1,334 @@
 "use client";
 
 import { useMemo, useState } from "react";
-import { buildTestRoutes, rankContextFiles, type RepoFile, type RepoMap } from "@aryam/fixmap-core/browser";
-
-const sampleFiles = [
-  sampleFile("src/auth/reset-password.ts", "password reset token email authentication", "code"),
-  sampleFile("src/auth/session.ts", "login session cookie authentication", "code"),
-  sampleFile("src/billing/create-invoice.ts", "billing payment invoice customer", "code"),
-  sampleFile("src/email/send-reset.ts", "send password reset email template", "code"),
-  sampleFile("test/auth/reset-password.test.ts", "password reset email token test", "code", true),
-  sampleFile(".github/workflows/ci.yml", "workflow test build pull request", "config"),
-  sampleFile("README.md", "installation guide documentation", "documentation")
-];
+import { buildReportFromRepo, explainFile, verifyPlan } from "@aryam/fixmap-core/browser";
+import { sampleRepo, sampleRepoWithChanges, samplePaths } from "./sample-repo";
 
-const sampleRepo: RepoMap = {
-  root: "sample-repository",
-  files: sampleFiles,
-  packageScripts: [{ name: "test", command: "vitest run", packageDir: "" }],
-  changedFiles: [],
-  diffText: "",
-  packageManager: "npm",
-  diagnostics: []
-};
+type Stage = "plan" | "explain" | "verify";
 
 const presets = [
-  "Password reset emails fail",
-  "Invoices are created twice",
-  "Login sessions expire too early",
-  "Update the installation guide"
+  {
+    label: "Password reset emails never arrive",
+    note: "A symptom with no symbol. This is where a lexical ranker is weakest — watch what happens in the next preset."
+  },
+  {
+    label: "sendMail throws and password reset emails never arrive",
+    note: "The same bug with one symbol named. The transport file climbs, and the reason says why: it defines sendMail."
+  },
+  {
+    label: "TOKEN_TTL_MINUTES is ignored, reset links expire immediately",
+    note: "A named constant is the strongest anchor there is. The file that defines it wins outright."
+  },
+  {
+    label: "Invoices are created twice for the same customer",
+    note: "A different subsystem, no overlap with the auth files, no drift into them."
+  },
+  {
+    label: "make it better",
+    note: "No searchable anchor. FixMap reports nothing and says so, instead of ranking something plausible."
+  }
+];
+
+const scenarios = [
+  { label: "Edited the build output", changed: ["dist/auth/reset-password.js"] },
+  { label: "Shipped with no test", changed: ["src/email/transport.ts"] },
+  { label: "Also touched billing", changed: ["src/email/transport.ts", "src/billing/invoice.ts"] },
+  {
+    label: "Source and test together",
+    changed: ["src/auth/reset-password.ts", "test/auth/reset-password.test.ts"]
+  }
 ];
 
+const explainTargets = samplePaths;
+
 export function Demo() {
-  const [task, setTask] = useState<string>("Password reset emails fail");
-  const result = useMemo(() => {
-    const ranked = rankContextFiles(sampleRepo, { issueText: task }, 4);
-    const routes = buildTestRoutes(sampleRepo, ranked.map((file) => file.path));
-    return { ranked, routes };
-  }, [task]);
+  const [task, setTask] = useState(presets[0]!.label);
+  const [stage, setStage] = useState<Stage>("plan");
+  const [explainTarget, setExplainTarget] = useState("dist/auth/reset-password.js");
+  const [scenario, setScenario] = useState(0);
+
+  const report = useMemo(() => buildReportFromRepo(sampleRepo, { issueText: task }), [task]);
+  const explanation = useMemo(
+    () => explainFile(sampleRepo, { issueText: task }, explainTarget),
+    [task, explainTarget]
+  );
+  const verification = useMemo(
+    () => verifyPlan(report, sampleRepoWithChanges(scenarios[scenario]!.changed)),
+    [report, scenario]
+  );
+
+  const activePreset = presets.find((preset) => preset.label === task);
+  const command = {
+    plan: `fixmap plan --issue "${truncate(task)}"`,
+    explain: `fixmap plan --issue "${truncate(task)}" --explain ${explainTarget}`,
+    verify: `fixmap verify --report plan.json --diff main...HEAD`
+  }[stage];
 
   return (
-    <div className="demo-shell">
-      <div className="demo-input">
-        <label htmlFor="task">Describe the task</label>
-        <textarea id="task" value={task} onChange={(event) => setTask(event.target.value)} rows={4} />
-        <div className="preset-list" aria-label="Example tasks">
-          {presets.map((preset) => (
-            <button key={preset} type="button" aria-pressed={task === preset} onClick={() => setTask(preset)}>{preset}</button>
-          ))}
+    <div className="workbench">
+      <div className="stage-tabs" role="tablist" aria-label="FixMap stages">
+        {(
+          [
+            ["plan", "1 · Plan", "Where do I start?"],
+            ["explain", "2 · Ask why", "Why not this file?"],
+            ["verify", "3 · Verify", "Did the change match?"]
+          ] as const
+        ).map(([value, label, hint]) => (
+          <button
+            key={value}
+            type="button"
+            role="tab"
+            aria-selected={stage === value}
+            className={stage === value ? "stage-tab active" : "stage-tab"}
+            onClick={() => setStage(value)}
+          >
+            <b>{label}</b>
+            <small>{hint}</small>
+          </button>
+        ))}
+      </div>
+
+      <div className="demo-shell">
+        <div className="demo-input">
+          <label htmlFor="task">The task</label>
+          <textarea id="task" value={task} onChange={(event) => setTask(event.target.value)} rows={3} />
+          <div className="preset-list" aria-label="Example tasks">
+            {presets.map((preset) => (
+              <button
+                key={preset.label}
+                type="button"
+                aria-pressed={task === preset.label}
+                onClick={() => setTask(preset.label)}
+              >
+                {preset.label}
+              </button>
+            ))}
+          </div>
+          {activePreset ? <p className="preset-note">{activePreset.note}</p> : null}
+
+          <p className="demo-command">
+            <span>Same result from the CLI</span>
+            <code>{command}</code>
+          </p>
+
+          <div className="privacy-note">
+            <span>●</span>
+            <p>
+              <strong>This is FixMap itself, not a mockup.</strong> The page imports the same
+              ranking, explanation, and verification code the CLI runs, and executes it on a
+              sample repository in your browser. Nothing you type is sent anywhere.
+            </p>
+          </div>
         </div>
-        <div className="privacy-note"><span>●</span><p><strong>Sample data only.</strong> Nothing typed here leaves your browser.</p></div>
+
+        <div className="demo-results" aria-live="polite">
+          {stage === "plan" ? <PlanPanel report={report} /> : null}
+          {stage === "explain" ? (
+            <ExplainPanel
+              explanation={explanation}
+              target={explainTarget}
+              onTargetChange={setExplainTarget}
+            />
+          ) : null}
+          {stage === "verify" ? (
+            <VerifyPanel
+              verification={verification}
+              scenario={scenario}
+              onScenarioChange={setScenario}
+            />
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function PlanPanel({ report }: { report: ReturnType<typeof buildReportFromRepo> }) {
+  return (
+    <>
+      <div className="results-head">
+        <span>Context files</span>
+        <small>{report.contextFiles.length} ranked</small>
       </div>
-      <div className="demo-results" aria-live="polite">
-        <div className="results-head"><span>Context pack</span><small>{result.ranked.length} files</small></div>
-        {result.ranked.length ? result.ranked.map((file, index) => (
+
+      {report.contextFiles.length > 0 ? (
+        report.contextFiles.map((file, index) => (
           <article className="result" key={file.path}>
             <span className="result-number">{String(index + 1).padStart(2, "0")}</span>
-            <div><code>{file.path}</code><p>{file.reasons.join("; ")}</p></div>
-            <span className={`confidence ${file.confidence}`}>{file.confidence}</span>
+            <div>
+              <code>{file.path}</code>
+              <p>{file.reasons.join("; ")}</p>
+            </div>
+            <span className={`confidence ${file.confidence}`}>
+              {file.confidence} · {file.score}
+            </span>
           </article>
-        )) : <div className="empty-result"><strong>No confident match yet.</strong><p>Try mentioning a feature, file, or behavior.</p></div>}
+        ))
+      ) : (
+        <div className="empty-result">
+          <strong>Nothing ranked.</strong>
+          <p>FixMap returns an empty report rather than a plausible guess.</p>
+        </div>
+      )}
+
+      {report.testRoutes.length > 0 ? (
         <div className="route-preview">
-          <span>Suggested check</span>
-          <code>{result.routes[0]?.command ?? "No code test required"}</code>
+          <span>Run this</span>
+          <code>{report.testRoutes[0]!.command}</code>
+        </div>
+      ) : null}
+      {report.testRoutes[0]?.relatedFiles.length ? (
+        <p className="route-related">
+          Nearest test: <code>{report.testRoutes[0]!.relatedFiles[0]}</code>
+        </p>
+      ) : null}
+
+      {report.risks.length > 0 ? (
+        <div className="panel-block">
+          <h4>Risk</h4>
+          {report.risks.map((risk) => (
+            <p key={risk.area}>
+              <span className={`severity ${risk.severity}`}>{risk.severity}</span>
+              {risk.area} — {risk.reason}
+            </p>
+          ))}
         </div>
+      ) : null}
+
+      {report.diagnostics.length > 0 ? (
+        <div className="panel-block">
+          <h4>Diagnostics</h4>
+          {report.diagnostics.map((diagnostic) => (
+            <p key={diagnostic.code}>
+              <span className={`severity ${diagnostic.severity}`}>{diagnostic.severity}</span>
+              {diagnostic.message}
+            </p>
+          ))}
+        </div>
+      ) : null}
+
+      {report.analysis ? <p className="next-action">→ {report.analysis.nextAction}</p> : null}
+    </>
+  );
+}
+
+function ExplainPanel({
+  explanation,
+  target,
+  onTargetChange
+}: {
+  explanation: ReturnType<typeof explainFile>;
+  target: string;
+  onTargetChange: (path: string) => void;
+}) {
+  return (
+    <>
+      <div className="results-head">
+        <span>Why this file</span>
+        <small className={`status-${explanation.status}`}>{explanation.status.replace("-", " ")}</small>
       </div>
-    </div>
+
+      <label className="picker-label" htmlFor="explain-target">
+        Pick any file in the sample repository
+      </label>
+      <select
+        id="explain-target"
+        className="picker"
+        value={target}
+        onChange={(event) => onTargetChange(event.target.value)}
+      >
+        {explainTargets.map((path) => (
+          <option key={path} value={path}>
+            {path}
+          </option>
+        ))}
+      </select>
+
+      <p className="explain-summary">{explanation.summary}</p>
+
+      {explanation.reasons.length > 0 ? (
+        <div className="panel-block">
+          <h4>Scored for</h4>
+          {explanation.reasons.map((reason) => (
+            <p key={reason}>{reason}</p>
+          ))}
+        </div>
+      ) : null}
+
+      <p className="panel-footnote">
+        A ranked list explains what it chose. This answers the question it cannot: why the file
+        you expected is missing. The four answers are genuinely different — it ranked lower than
+        you thought, it scored below the cutoff, it was excluded on purpose, or the scan never
+        saw it.
+      </p>
+    </>
+  );
+}
+
+function VerifyPanel({
+  verification,
+  scenario,
+  onScenarioChange
+}: {
+  verification: ReturnType<typeof verifyPlan>;
+  scenario: number;
+  onScenarioChange: (index: number) => void;
+}) {
+  const hasError = verification.findings.some((finding) => finding.severity === "error");
+
+  return (
+    <>
+      <div className="results-head">
+        <span>Plan vs. diff</span>
+        <small className={hasError ? "status-excluded" : "status-ranked"}>
+          exit {hasError ? 1 : 0}
+        </small>
+      </div>
+
+      <p className="picker-label" id="scenario-label">
+        Pretend the change touched
+      </p>
+      <div className="preset-list" id="scenario" role="group" aria-labelledby="scenario-label">
+        {scenarios.map((option, index) => (
+          <button
+            key={option.label}
+            type="button"
+            aria-pressed={scenario === index}
+            onClick={() => onScenarioChange(index)}
+          >
+            {option.label}
+          </button>
+        ))}
+      </div>
+      <p className="changed-list">
+        {scenarios[scenario]!.changed.map((path) => (
+          <code key={path}>{path}</code>
+        ))}
+      </p>
+
+      <p className="explain-summary">{verification.summary}</p>
+
+      {verification.findings.map((finding) => (
+        <article className="finding" key={finding.code}>
+          <span className={`severity ${finding.severity}`}>{finding.severity}</span>
+          <div>
+            <p>{finding.message}</p>
+            {finding.paths.map((path) => (
+              <code key={path}>{path}</code>
+            ))}
+          </div>
+        </article>
+      ))}
+
+      <p className="panel-footnote">
+        Only the discarded edit exits non-zero, because that one is wrong whatever the task was.
+        Everything else is advisory: a plan can be wrong and a change can still be right, so
+        FixMap reports the gap rather than judging it.
+      </p>
+    </>
   );
 }
 
-function sampleFile(
-  path: string,
-  textSample: string,
-  kind: RepoFile["kind"],
-  isTest = false
-): RepoFile {
-  const extensionIndex = path.lastIndexOf(".");
-  return {
-    path,
-    extension: extensionIndex >= 0 ? path.slice(extensionIndex) : "",
-    sizeBytes: textSample.length,
-    isTest,
-    isSource: true,
-    kind,
-    textSample
-  };
+function truncate(task: string): string {
+  return task.length <= 46 ? task : `${task.slice(0, 43)}...`;
 }
diff --git a/apps/web/app/globals.css b/apps/web/app/globals.css
index 098b89e..6a7a2f0 100644
--- a/apps/web/app/globals.css
+++ b/apps/web/app/globals.css
@@ -235,7 +235,7 @@ h1 em, h2 em {
 .terminal-label { margin-top: 16px !important; color: var(--faint) !important; font-size: 10px; letter-spacing: 0.22em; }
 
 /* Sections */
-.film-section, .demo-section, .evidence, .workflow, .quickstart { max-width: 1200px; margin: auto; padding: 104px 24px; border-top: 1px solid var(--line); }
+.film-section, .demo-section, .evidence, .workflow, .quickstart, .commands, .benefits { max-width: 1200px; margin: auto; padding: 104px 24px; border-top: 1px solid var(--line); }
 .section-heading { max-width: 740px; margin-bottom: 46px; }
 .section-heading.compact { max-width: 560px; }
 h2 { margin-bottom: 18px; font-size: clamp(34px, 4.2vw, 52px); line-height: 1.06; }
@@ -259,6 +259,26 @@ h2 { margin-bottom: 18px; font-size: clamp(34px, 4.2vw, 52px); line-height: 1.06
 .film-frame figcaption { padding: 14px 18px 16px; color: var(--muted); font-size: 11.5px; line-height: 1.5; border-top: 1px solid var(--line); }
 
 /* Demo */
+.stage-tabs { display: flex; gap: 10px; margin-bottom: 18px; flex-wrap: wrap; }
+.stage-tab {
+  flex: 1 1 200px;
+  display: flex;
+  flex-direction: column;
+  gap: 5px;
+  padding: 16px 20px;
+  text-align: left;
+  color: var(--muted);
+  background: rgba(255, 255, 255, 0.02);
+  border: 1px solid var(--line);
+  border-radius: 14px;
+  cursor: pointer;
+  transition: color 0.2s var(--ease), border-color 0.2s var(--ease), background 0.2s var(--ease);
+}
+.stage-tab b { color: var(--text); font-size: 14px; font-weight: 580; letter-spacing: 0.01em; }
+.stage-tab small { font-size: 12px; }
+.stage-tab:hover { border-color: rgba(116, 240, 186, 0.3); }
+.stage-tab.active { border-color: rgba(116, 240, 186, 0.5); background: var(--mint-soft); }
+.stage-tab.active b { color: var(--mint); }
 .demo-shell {
   display: grid;
   grid-template-columns: 0.85fr 1.15fr;
@@ -321,23 +341,149 @@ h2 { margin-bottom: 18px; font-size: clamp(34px, 4.2vw, 52px); line-height: 1.06
 .empty-result { padding: 64px 0; text-align: center; color: var(--muted); }
 .empty-result p { margin: 8px 0; font-size: 12.5px; }
 .empty-result strong { font-family: var(--font-display), Georgia, serif; font-weight: 500; font-size: 17px; color: #c4cfca; }
+.preset-note { margin: 16px 0 0; padding-left: 12px; border-left: 2px solid rgba(116, 240, 186, 0.35); color: var(--muted); font-size: 12.5px; line-height: 1.65; }
+.demo-command { display: flex; flex-direction: column; gap: 8px; margin: 26px 0 0; }
+.demo-command span { color: var(--faint); font-size: 10.5px; text-transform: uppercase; letter-spacing: 0.16em; font-weight: 600; }
+.demo-command code {
+  padding: 12px 14px;
+  overflow-wrap: anywhere;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: rgba(5, 9, 7, 0.72);
+  color: var(--mint);
+  font: 11.5px/1.6 var(--font-mono), ui-monospace, monospace;
+}
+.demo-command code::before { content: "$ "; color: var(--faint); }
+.route-related { margin: 10px 0 0; color: var(--faint); font-size: 11.5px; }
+.route-related code { color: var(--muted); font: 11.5px var(--font-mono), ui-monospace, monospace; }
+.panel-block { margin-top: 22px; padding-top: 18px; border-top: 1px solid var(--line); }
+.panel-block h4 { margin: 0 0 12px; color: var(--faint); font-size: 10.5px; text-transform: uppercase; letter-spacing: 0.2em; font-weight: 600; }
+.panel-block p { display: flex; gap: 10px; align-items: baseline; margin: 0 0 10px; color: #8d9d95; font-size: 12px; line-height: 1.6; }
+.panel-block p:last-child { margin-bottom: 0; }
+.severity { flex: none; padding: 3px 9px; border-radius: 999px; font-size: 9.5px; text-transform: uppercase; letter-spacing: 0.08em; font-weight: 600; border: 1px solid transparent; }
+.severity.high, .severity.error { background: rgba(255, 138, 128, 0.1); color: #ff9d92; border-color: rgba(255, 138, 128, 0.24); }
+.severity.medium, .severity.warning { background: rgba(240, 199, 117, 0.1); color: var(--amber); border-color: rgba(240, 199, 117, 0.22); }
+.severity.low, .severity.info { background: rgba(255, 255, 255, 0.04); color: #9baaa4; border-color: var(--line); }
+.next-action { margin: 20px 0 0; padding: 13px 16px; border: 1px solid rgba(116, 240, 186, 0.2); border-radius: 10px; background: linear-gradient(180deg, rgba(116, 240, 186, 0.07), rgba(116, 240, 186, 0.02)); color: var(--mint); font-size: 12.5px; line-height: 1.6; }
+.picker-label { display: block; margin: 6px 0 10px; color: var(--faint); font-size: 10.5px; text-transform: uppercase; letter-spacing: 0.16em; font-weight: 600; }
+.picker {
+  width: 100%;
+  padding: 12px 14px;
+  color: var(--text);
+  background: rgba(5, 9, 7, 0.75);
+  border: 1px solid var(--line-strong);
+  border-radius: 10px;
+  font: 12.5px var(--font-mono), ui-monospace, monospace;
+  outline: none;
+}
+.picker:focus { border-color: rgba(116, 240, 186, 0.55); }
+.explain-summary { margin: 20px 0 0; color: #dce6e1; font-size: 14px; line-height: 1.68; }
+.panel-footnote { margin: 24px 0 0; padding-top: 18px; border-top: 1px solid var(--line); color: var(--faint); font-size: 11.5px; line-height: 1.7; }
+.changed-list { display: flex; flex-wrap: wrap; gap: 8px; margin: 14px 0 0; }
+.changed-list code { padding: 5px 10px; border: 1px solid var(--line); border-radius: 7px; background: rgba(5, 9, 7, 0.6); color: #b9c7c0; font: 11.5px var(--font-mono), ui-monospace, monospace; }
+.finding { display: grid; grid-template-columns: auto 1fr; gap: 12px; align-items: start; padding: 16px 0; border-top: 1px solid var(--line); }
+.finding p { margin: 0 0 8px; color: #97a79f; font-size: 12.5px; line-height: 1.65; }
+.finding code { display: inline-block; margin: 0 6px 4px 0; padding: 4px 9px; border: 1px solid var(--line); border-radius: 6px; background: rgba(5, 9, 7, 0.6); color: #cfdcd6; font: 11px var(--font-mono), ui-monospace, monospace; }
+.results-head small.status-ranked { background: var(--mint-dark); color: var(--mint); }
+.results-head small.status-excluded { background: rgba(255, 138, 128, 0.12); color: #ff9d92; }
+.results-head small.status-below-cutoff { background: rgba(240, 199, 117, 0.12); color: var(--amber); }
+.results-head small.status-not-scanned { background: rgba(255, 255, 255, 0.05); color: #9baaa4; }
 
-/* Workflow steps */
-.steps { display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px; }
-.steps article {
+/* Anatomy of a report: command in, four outputs out */
+.anatomy { display: grid; grid-template-columns: 0.82fr 1.18fr; gap: 46px; align-items: start; }
+/* Grid children default to min-width:auto, so a wide <pre> pushes the whole page past the
+   viewport instead of scrolling inside its own box. */
+.anatomy > *, .command-grid > *, .benefit-grid > *, .demo-shell > *, .evidence-grid > * { min-width: 0; }
+.anatomy-caption { margin: 0 0 14px; color: var(--muted); font-size: 11px; text-transform: uppercase; letter-spacing: 0.18em; font-weight: 600; }
+.anatomy-input pre {
+  margin: 0;
+  padding: 22px 24px;
+  overflow: auto;
+  border-radius: 14px;
+  background: linear-gradient(rgba(8, 14, 11, 0.92), rgba(8, 14, 11, 0.92)) padding-box,
+    linear-gradient(120deg, rgba(116, 240, 186, 0.35), rgba(148, 187, 168, 0.08)) border-box;
+  border: 1px solid transparent;
+  color: var(--mint);
+  font: 13px/1.7 var(--font-mono), ui-monospace, monospace;
+  box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.04), 0 18px 44px rgba(0, 0, 0, 0.3);
+}
+.anatomy-input pre code::before { content: "$ "; color: var(--faint); }
+.anatomy-note { margin: 20px 0 0; color: var(--faint); font-size: 13.5px; line-height: 1.7; }
+.anatomy-note code { color: var(--muted); font: 12.5px var(--font-mono), ui-monospace, monospace; }
+.anatomy-output { counter-reset: anatomy; margin: 0; padding: 0; list-style: none; display: grid; gap: 4px; }
+.anatomy-output li {
+  counter-increment: anatomy;
   position: relative;
-  min-height: 250px;
-  padding: 30px;
+  padding: 22px 0 22px 52px;
+  border-top: 1px solid var(--line);
+}
+.anatomy-output li:first-child { border-top: 0; padding-top: 0; }
+.anatomy-output li::before {
+  content: counter(anatomy);
+  position: absolute;
+  left: 0;
+  top: 20px;
+  width: 30px;
+  height: 30px;
+  display: grid;
+  place-items: center;
+  border-radius: 50%;
+  border: 1px solid rgba(116, 240, 186, 0.28);
+  background: var(--mint-soft);
+  color: var(--mint);
+  font: 500 12px var(--font-mono), ui-monospace, monospace;
+}
+.anatomy-output li:first-child::before { top: -2px; }
+.anatomy-output h3 { margin-bottom: 8px; font-family: var(--font-display), Georgia, serif; font-weight: 520; font-size: 19px; letter-spacing: -0.01em; }
+.anatomy-output p { margin: 0; color: var(--muted); font-size: 14.5px; line-height: 1.7; }
+.anatomy-output code { color: #cfdcd6; font: 12.5px var(--font-mono), ui-monospace, monospace; overflow-wrap: anywhere; }
+.anatomy-output em { color: var(--mint); font-style: normal; }
+.anatomy-footer { max-width: 780px; margin: 46px 0 0; padding-top: 26px; border-top: 1px solid var(--line); color: var(--faint); font-size: 14px; line-height: 1.7; }
+
+/* Commands */
+.command-grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 20px; }
+.command-card {
+  padding: 28px 28px 30px;
   border-radius: 16px;
   background: linear-gradient(var(--panel), var(--panel)) padding-box,
     linear-gradient(170deg, rgba(148, 187, 168, 0.26), rgba(148, 187, 168, 0.05)) border-box;
   border: 1px solid transparent;
   transition: transform 0.3s var(--ease), box-shadow 0.3s var(--ease);
 }
-.steps article:hover { transform: translateY(-4px); box-shadow: 0 24px 50px rgba(0, 0, 0, 0.35); }
-.steps article > span { display: block; margin-bottom: 52px; color: var(--champagne); font: italic 460 19px var(--font-display), Georgia, serif; opacity: 0.85; }
-.steps h3 { font-family: var(--font-display), Georgia, serif; font-weight: 520; font-size: 21px; letter-spacing: -0.01em; margin-bottom: 10px; }
-.steps p { color: var(--muted); line-height: 1.65; font-size: 14px; }
+.command-card:hover { transform: translateY(-4px); box-shadow: 0 24px 50px rgba(0, 0, 0, 0.35); }
+.command-badge { margin: 0 0 16px; color: var(--champagne); font: 600 10.5px var(--font-mono), ui-monospace, monospace; letter-spacing: 0.14em; text-transform: uppercase; opacity: 0.85; }
+.command-card pre {
+  margin: 0 0 22px;
+  padding: 14px 16px;
+  overflow: auto;
+  border-radius: 10px;
+  border: 1px solid var(--line);
+  background: rgba(5, 9, 7, 0.72);
+  color: var(--mint);
+  font: 12.5px/1.6 var(--font-mono), ui-monospace, monospace;
+}
+.command-card h3 { margin-bottom: 10px; font-family: var(--font-display), Georgia, serif; font-weight: 520; font-size: 20px; letter-spacing: -0.01em; }
+.command-card > p:last-child { margin: 0; color: var(--muted); font-size: 14px; line-height: 1.68; }
+.command-extra {
+  display: flex;
+  gap: 30px;
+  align-items: center;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  margin-top: 22px;
+  padding: 28px 30px;
+  border-radius: 16px;
+  border: 1px solid var(--line);
+  background: var(--panel-2);
+}
+.command-extra h3 { margin-bottom: 8px; font-family: var(--font-display), Georgia, serif; font-weight: 520; font-size: 20px; }
+.command-extra p { margin: 0; max-width: 680px; color: var(--muted); font-size: 14px; line-height: 1.68; }
+
+/* Benefits */
+.benefit-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 34px 40px; }
+.benefit-grid article { padding-top: 22px; border-top: 1px solid var(--line-strong); }
+.benefit-grid h3 { margin-bottom: 10px; font-family: var(--font-display), Georgia, serif; font-weight: 520; font-size: 19px; line-height: 1.28; letter-spacing: -0.01em; }
+.benefit-grid p { margin: 0; color: var(--muted); font-size: 14px; line-height: 1.7; }
 
 /* Quickstart */
 .quickstart { display: grid; grid-template-columns: 1fr; justify-items: start; }
@@ -356,6 +502,8 @@ h2 { margin-bottom: 18px; font-size: clamp(34px, 4.2vw, 52px); line-height: 1.06
   box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.04), 0 18px 44px rgba(0, 0, 0, 0.3);
 }
 .quickstart pre code::before { content: "$ "; color: var(--faint); }
+.quickstart-note { max-width: 680px; margin: 20px 0 0; color: var(--faint); font-size: 13.5px; line-height: 1.7; }
+.quickstart-note code { color: var(--muted); font: 12.5px var(--font-mono), ui-monospace, monospace; }
 
 /* Footer */
 footer { max-width: 1200px; margin: auto; min-height: 124px; padding: 34px 24px; border-top: 1px solid var(--line); display: flex; align-items: center; gap: 26px; color: var(--muted); font-size: 12.5px; }
@@ -368,15 +516,18 @@ footer > a:last-child:hover { color: var(--text); border-color: var(--mint); }
 ::-webkit-scrollbar-thumb { background: #1d2823; border: 3px solid var(--bg); border-radius: 8px; }
 ::-webkit-scrollbar-thumb:hover { background: #2b3a33; }
 
+@media (max-width: 1000px) {
+  .benefit-grid { grid-template-columns: repeat(2, 1fr); }
+}
 @media (max-width: 860px) {
   .hero { grid-template-columns: 1fr; padding-top: 72px; gap: 56px; }
   .hero-terminal { transform: none; animation: none; }
   .film-section { grid-template-columns: 1fr; }
   .demo-shell { grid-template-columns: 1fr; }
   .demo-input { border-right: 0; border-bottom: 1px solid var(--line); }
-  .steps { grid-template-columns: 1fr; }
-  .steps article { min-height: 0; }
-  .steps article > span { margin-bottom: 26px; }
+  .anatomy { grid-template-columns: 1fr; gap: 40px; }
+  .command-grid { grid-template-columns: 1fr; }
+  .benefit-grid { grid-template-columns: 1fr; gap: 26px; }
   .evidence-grid { grid-template-columns: 1fr; }
 }
 @media (max-width: 620px) {
@@ -384,7 +535,9 @@ footer > a:last-child:hover { color: var(--text); border-color: var(--mint); }
   .eyebrow::after, .kicker::after { display: none; }
   h1 { font-size: 40px; }
   .hero { padding-bottom: 72px; }
-  .film-section, .demo-section, .evidence, .workflow, .quickstart { padding-top: 76px; padding-bottom: 76px; }
+  .film-section, .demo-section, .evidence, .workflow, .quickstart, .commands, .benefits { padding-top: 76px; padding-bottom: 76px; }
+  .anatomy-output li { padding-left: 42px; }
+  .stage-tab { padding: 13px 16px; }
   .evidence-detail { gap: 22px; }
   .demo-input, .demo-results { padding-left: 18px; padding-right: 18px; }
   .proof-row { gap: 12px; flex-direction: column; }
@@ -393,6 +546,6 @@ footer > a:last-child:hover { color: var(--text); border-color: var(--mint); }
 }
 @media (prefers-reduced-motion: reduce) {
   html { scroll-behavior: auto; }
-  .button, .steps article, .result, .nav-links a, .preset-list button { transition: none; }
+  .button, .command-card, .result, .nav-links a, .preset-list button, .stage-tab { transition: none; }
   .hero-terminal { animation: none; }
 }
diff --git a/apps/web/app/page.tsx b/apps/web/app/page.tsx
index 2923579..d1fdfce 100644
--- a/apps/web/app/page.tsx
+++ b/apps/web/app/page.tsx
@@ -1,10 +1,12 @@
 import { Demo } from "./demo";
-// Read the recorded evaluations directly so the site cannot drift from the
-// benchmark. Published numbers that are typed by hand go stale silently.
+// Read the recorded evaluations and the published version directly so the site cannot
+// drift from what shipped. Numbers typed by hand go stale silently.
 import heldout from "../../../benchmarks/heldout/results.json";
 import regression from "../../../benchmarks/external/results.json";
 import savings from "../../../benchmarks/external/savings-results.json";
+import cli from "../../../packages/cli/package.json";
 
+const repoUrl = "https://github.com/aryamthecodebreaker/FixMap";
 const installCommand =
   "npx -y @aryam/fixmap plan --issue https://github.com/aryamthecodebreaker/FixMap/issues/59";
 
@@ -23,6 +25,68 @@ const regressionTop5 = hits(regressionCases, "top5Hit");
 const medianSeconds = (savings.performance.medianScanAndRankMs / 1000).toFixed(2);
 const percent = (hitCount: number, total: number) => `${Math.round((hitCount / total) * 100)}%`;
 
+const commands = [
+  {
+    id: "plan",
+    command: "fixmap plan --issue \"reset links expire immediately\"",
+    question: "Where do I start?",
+    answer:
+      "Ranked files with a score, a confidence label, and the reasons behind both. The nearest test command, the risk areas the change touches, and diagnostics for anything uncertain.",
+    badge: "the main one"
+  },
+  {
+    id: "explain",
+    command: "fixmap plan --issue \"…\" --explain src/billing/invoice.ts",
+    question: "Why is my file not in that list?",
+    answer:
+      "The one question a ranked list cannot answer. It separates the cases that actually differ: ranked lower than you thought, scored below the cutoff, excluded on purpose, or never scanned at all.",
+    badge: "new in v0.7.3"
+  },
+  {
+    id: "verify",
+    command: "fixmap verify --report plan.json --diff main...HEAD",
+    question: "Did the change match the plan?",
+    answer:
+      "Compares the saved plan against the real diff. Catches edits a build will discard, files the change needed that the plan never ranked, source moving with no test, and risk nobody flagged.",
+    badge: "new in v0.7.3"
+  },
+  {
+    id: "mcp",
+    command: "claude mcp add fixmap -- npx -y @aryam/fixmap mcp",
+    question: "Can my agent just ask for it?",
+    answer:
+      "One stdio MCP tool. Claude Code, Cursor, Windsurf, and any other MCP client get the same report without a human running anything. Analysis stays on your machine.",
+    badge: "for agents"
+  }
+];
+
+const benefits = [
+  {
+    title: "Your agent stops opening the wrong file first",
+    body: "Agents are fast once they have the right context. The expensive part is the search before the first edit — the plausible file that is not the definition, the test command that does not cover the change."
+  },
+  {
+    title: "Nothing leaves your machine",
+    body: "No account, no API key, no model call, no telemetry. Local repositories are read locally; a public issue URL uses an anonymous throwaway checkout that is deleted when the report is done."
+  },
+  {
+    title: "Same input, same output, every time",
+    body: "There is no model in the loop, so a report is reproducible and reviewable. You can diff two runs, pin it in CI, and argue with the ranking — every score comes with its reasons attached."
+  },
+  {
+    title: "It tells you when it does not know",
+    body: "A vague task returns an empty report and says why. An invented identifier gets named in a diagnostic instead of quietly matching something. Confidence is capped when the evidence is thin."
+  },
+  {
+    title: "It never runs your code",
+    body: "No install, no build, no test execution, no package scripts, no git hooks. FixMap reads and ranks — which is why it is safe to point at a repository you have not read yourself."
+  },
+  {
+    title: "Free, MIT, about two seconds",
+    body: `Median scan and rank across the benchmarked repositories is ${medianSeconds} seconds. The core has zero runtime dependencies, and every benchmark input and output is committed in the repo.`
+  }
+];
+
 export default function HomePage() {
   return (
     <main>
@@ -32,11 +96,11 @@ export default function HomePage() {
           <span>FixMap</span>
         </a>
         <div className="nav-links">
-          <a href="#launch-film">Film</a>
-          <a href="#demo">Demo</a>
-          <a href="#evidence">Evidence</a>
           <a href="#how-it-works">How it works</a>
-          <a className="nav-github" href="https://github.com/aryamthecodebreaker/FixMap">GitHub ↗</a>
+          <a href="#demo">Try it</a>
+          <a href="#commands">Commands</a>
+          <a href="#evidence">Evidence</a>
+          <a className="nav-github" href={repoUrl}>GitHub ↗</a>
         </div>
       </nav>
 
@@ -45,12 +109,14 @@ export default function HomePage() {
           <p className="eyebrow"><span className="status-dot" /> Open source · local first · no API key</p>
           <h1>Give your coding agent a map <em>before</em> it starts editing.</h1>
           <p className="lede">
-            FixMap turns an issue or git diff into the files to inspect, tests to run, and risks a human should review.
+            Describe a bug, paste a GitHub issue, or point at a diff. FixMap returns the files to
+            open first, the test command that covers them, and the risks worth a second look —
+            in about two seconds, with no model call and nothing uploaded.
           </p>
           <div className="hero-actions">
-            <a className="button primary" href="#quickstart">Try the CLI</a>
-            <a className="button secondary" href="#launch-film">Watch the launch film</a>
-            <a className="button github-button" href="https://github.com/aryamthecodebreaker/FixMap">View on GitHub ↗</a>
+            <a className="button primary" href="#quickstart">Run one command</a>
+            <a className="button secondary" href="#demo">Try it in the browser</a>
+            <a className="button github-button" href={repoUrl}>View on GitHub ↗</a>
           </div>
           <div className="proof-row" aria-label="Measured results">
             <span>
@@ -61,58 +127,148 @@ export default function HomePage() {
           </div>
         </div>
         <div className="hero-terminal" aria-label="Example FixMap report">
-          <div className="terminal-bar"><span /><span /><span /><code>fixmap report</code></div>
+          <div className="terminal-bar"><span /><span /><span /><code>fixmap plan</code></div>
           <div className="terminal-body">
-            <p className="terminal-command">fixmap plan --issue &quot;reset emails fail&quot;</p>
+            {/* The listing below is this exact command's real output on the demo's sample
+                repository — including the confidence labels. Change one, re-run the other. */}
+            <p className="terminal-command">
+              fixmap plan --issue &quot;TOKEN_TTL_MINUTES is ignored, reset links expire immediately&quot;
+            </p>
             <p className="terminal-label">CONTEXT</p>
             <p><strong>01</strong> src/auth/reset-password.ts <b>high</b></p>
-            <p><strong>02</strong> src/email/send-reset.ts <i>medium</i></p>
-            <p className="terminal-label">VERIFY</p>
-            <p><strong>→</strong> npm --prefix apps/api run test</p>
+            <p><strong>02</strong> src/email/templates/reset.ts <b>high</b></p>
+            <p><strong>03</strong> src/auth/token-store.ts <i>medium</i></p>
+            <p className="terminal-label">TEST ROUTE</p>
+            <p><strong>→</strong> npm run test</p>
             <p className="terminal-label">RISK</p>
             <p><strong>!</strong> authentication · high severity</p>
           </div>
         </div>
       </section>
 
-      <section className="film-section" id="launch-film">
-        <div className="film-copy">
-          <p className="kicker">24-second product film</p>
-          <h2>See the handoff before the first edit.</h2>
-          <p id="launch-film-description">
-            The film moves from the wrong-file problem to a ranked context file, a test route, and an explicit risk note—the core FixMap workflow in one short pass.
+      <section className="workflow" id="how-it-works">
+        <div className="section-heading">
+          <p className="kicker">What actually happens</p>
+          <h2>One command in. A map out. No model in the middle.</h2>
+          <p>
+            FixMap is a routing step you run <em>before</em> an agent starts searching. It reads the
+            repository, ranks it against your task, and hands back four things you can check.
           </p>
-          <div className="film-links">
-            <a className="button primary" href="https://github.com/aryamthecodebreaker/FixMap">Explore the GitHub repo ↗</a>
-            <a className="button secondary" href="/fixmap-launch.mp4">Open the video</a>
+        </div>
+
+        <div className="anatomy">
+          <div className="anatomy-input">
+            <p className="anatomy-caption">You give it a task</p>
+            <pre><code>fixmap plan --issue &quot;TOKEN_TTL_MINUTES is ignored,
+  reset links expire immediately&quot;</code></pre>
+            <p className="anatomy-note">
+              Or a GitHub issue URL, or <code>--diff main...HEAD</code>. A local repository is never
+              uploaded; a public URL is fetched into a temporary checkout and deleted afterwards.
+            </p>
           </div>
-          <p className="film-note">Original product film · 1280×720 · sound on · current release v0.7.1</p>
+          <ol className="anatomy-output">
+            <li>
+              <h3>Ranked files, with reasons</h3>
+              <p>
+                <code>src/auth/reset-password.ts</code> — score 27, high confidence, because it
+                <em> defines TOKEN_TTL_MINUTES</em>, its path matches the task, and it declares
+                two more symbols the task names. Every point is traceable to a signal you can
+                disagree with.
+              </p>
+            </li>
+            <li>
+              <h3>The test command that covers them</h3>
+              <p>
+                The nearest workspace script — <code>npm --prefix packages/api run test</code>, not a
+                repository-wide guess — plus the specific tests that command can actually reach.
+              </p>
+            </li>
+            <li>
+              <h3>Risk areas the change touches</h3>
+              <p>
+                Authentication, billing, data migrations, public API surface. Derived from real
+                evidence: demo and example directories are ignored, changed files count anywhere.
+              </p>
+            </li>
+            <li>
+              <h3>Diagnostics for what it is unsure about</h3>
+              <p>
+                A vague task, an identifier that does not exist in the repository, a scan that hit
+                its limit, a ranking too flat to call. Said out loud, not hidden behind a score.
+              </p>
+            </li>
+          </ol>
         </div>
-        <figure className="film-frame">
-          <video
-            controls
-            playsInline
-            preload="metadata"
-            poster="/fixmap-launch-poster.jpg"
-            aria-label="FixMap launch film"
-            aria-describedby="launch-film-description"
-          >
-            <source src="/fixmap-launch.mp4" type="video/mp4" />
-            Your browser does not support embedded video. <a href="/fixmap-launch.mp4">Open the MP4 instead.</a>
-          </video>
-          <figcaption>FixMap turns a task into explainable context, verification routes, and reviewable risk.</figcaption>
-        </figure>
+
+        <p className="anatomy-footer">
+          Output is Markdown for a human or JSON for the next tool. Nothing is executed — no
+          install, no build, no test run, no package scripts, no git hooks.
+        </p>
       </section>
 
       <section className="demo-section" id="demo">
         <div className="section-heading">
-          <p className="kicker">Interactive sample</p>
-          <h2>Change the task. Watch the repo map change.</h2>
-          <p>This browser demo ranks a safe sample repository. The CLI applies the same transparent ideas to your real checkout.</p>
+          <p className="kicker">Running here, in this tab</p>
+          <h2>Try all three commands on a sample repository.</h2>
+          <p>
+            This page imports the same ranking, explanation, and verification code the CLI runs,
+            and points it at a small sample repository — build output, examples, lockfile and all.
+            It is the tool, not a recording of it. Start with the first preset: it is the case
+            FixMap handles <em>worst</em>.
+          </p>
         </div>
         <Demo />
       </section>
 
+      <section className="commands" id="commands">
+        <div className="section-heading">
+          <p className="kicker">Four ways in</p>
+          <h2>Three commands and an agent socket.</h2>
+          <p>
+            <code>plan</code> is the one you will use daily. The other three exist because a ranked
+            list on its own leaves obvious questions unanswered.
+          </p>
+        </div>
+        <div className="command-grid">
+          {commands.map((entry) => (
+            <article className="command-card" key={entry.id}>
+              <p className="command-badge">{entry.badge}</p>
+              <pre><code>{entry.command}</code></pre>
+              <h3>{entry.question}</h3>
+              <p>{entry.answer}</p>
+            </article>
+          ))}
+        </div>
+        <div className="command-extra">
+          <div>
+            <h3>Or leave it running on every pull request</h3>
+            <p>
+              The GitHub Action posts one report as a pull-request comment and writes the full
+              version to the step summary. On forked pull requests it warns instead of failing,
+              because GitHub hands it a read-only token.
+            </p>
+          </div>
+          <a className="button secondary" href="https://github.com/marketplace/actions/fixmap">
+            Install from Marketplace ↗
+          </a>
+        </div>
+      </section>
+
+      <section className="benefits" id="benefits">
+        <div className="section-heading">
+          <p className="kicker">Why bother</p>
+          <h2>The point is not speed. It is not guessing.</h2>
+        </div>
+        <div className="benefit-grid">
+          {benefits.map((benefit) => (
+            <article key={benefit.title}>
+              <h3>{benefit.title}</h3>
+              <p>{benefit.body}</p>
+            </article>
+          ))}
+        </div>
+      </section>
+
       <section className="evidence" id="evidence">
         <div className="section-heading">
           <p className="kicker">Measured, not asserted</p>
@@ -165,43 +321,77 @@ export default function HomePage() {
           <strong>What this does not claim:</strong> there is no “tokens saved” or “minutes saved” number here.
           An honest one needs a controlled run of the same tasks with and without FixMap, which has not been done.
           The {heldout.cases - heldoutTop3} held-out misses are published with their real rankings rather than removed.
+          At twelve cases one result flipping moves top-3 by eight points, so read these as “about three quarters”,
+          not as two significant figures.
         </p>
 
         <div className="evidence-links">
-          <a className="button secondary" href="https://github.com/aryamthecodebreaker/FixMap/tree/main/benchmarks/heldout">Held-out cases and results ↗</a>
-          <a className="button secondary" href="https://github.com/aryamthecodebreaker/FixMap/tree/main/benchmarks/external">Regression suite ↗</a>
+          <a className="button secondary" href={`${repoUrl}/tree/main/benchmarks/heldout`}>Held-out cases and results ↗</a>
+          <a className="button secondary" href={`${repoUrl}/tree/main/benchmarks/external`}>Regression suite ↗</a>
+          <a className="button secondary" href={`${repoUrl}/tree/main/benchmarks/adversarial`}>Adversarial suite ↗</a>
         </div>
       </section>
 
-      <section className="workflow" id="how-it-works">
-        <div className="section-heading compact">
-          <p className="kicker">A grounded handoff</p>
-          <h2>Less guessing between task and code.</h2>
-        </div>
-        <div className="steps">
-          <article><span>01</span><h3>Scan locally</h3><p>Read repository shape, workspace scripts, tests, and the requested git diff without uploading source.</p></article>
-          <article><span>02</span><h3>Rank with reasons</h3><p>Combine task terms, changed files, file type, path proximity, and repository structure.</p></article>
-          <article><span>03</span><h3>Explain the route</h3><p>Return context, commands, risks, confidence, and diagnostics as Markdown or machine-readable JSON.</p></article>
+      <section className="film-section" id="launch-film">
+        <div className="film-copy">
+          <p className="kicker">24-second product film</p>
+          <h2>See the handoff before the first edit.</h2>
+          <p id="launch-film-description">
+            The film moves from the wrong-file problem to a ranked context file, a test route, and an explicit risk note—the core FixMap workflow in one short pass.
+          </p>
+          <div className="film-links">
+            <a className="button primary" href={repoUrl}>Explore the GitHub repo ↗</a>
+            <a className="button secondary" href="/fixmap-launch.mp4">Open the video</a>
+          </div>
+          <p className="film-note">Original product film · 1280×720 · sound on · current release v{cli.version}</p>
         </div>
+        <figure className="film-frame">
+          <video
+            controls
+            playsInline
+            preload="metadata"
+            poster="/fixmap-launch-poster.jpg"
+            aria-label="FixMap launch film"
+            aria-describedby="launch-film-description"
+          >
+            <source src="/fixmap-launch.mp4" type="video/mp4" />
+            Your browser does not support embedded video. <a href="/fixmap-launch.mp4">Open the MP4 instead.</a>
+          </video>
+          <figcaption>FixMap turns a task into explainable context, verification routes, and reviewable risk.</figcaption>
+        </figure>
       </section>
 
       <section className="quickstart" id="quickstart">
         <div>
           <p className="kicker">Thirty-second start</p>
           <h2>One command. No account. No API key.</h2>
-          <p>Paste a public GitHub issue URL. FixMap fetches the task, infers the repository, and maps where to start.</p>
+          <p>
+            Paste a public GitHub issue URL. FixMap fetches the task, infers the repository, scans a
+            temporary checkout, and deletes it when the report is done. Run it inside your own
+            repository and it reads that instead — nothing is uploaded either way.
+          </p>
         </div>
         <pre><code>{installCommand}</code></pre>
+        <p className="quickstart-note">
+          Requires Node.js 20.11 or newer. Nothing is installed permanently — <code>npx</code> runs
+          it once. The CLI points you at <code>--explain</code> and <code>verify</code> as they
+          become useful, so you do not have to remember they exist.
+        </p>
         <div className="quick-links">
-          <a className="button primary" href="https://github.com/aryamthecodebreaker/FixMap#readme">Read the docs</a>
-          <a className="button secondary" href="https://github.com/aryamthecodebreaker/FixMap/tree/main/examples">See examples</a>
+          <a className="button primary" href={`${repoUrl}#readme`}>Read the docs</a>
+          <a className="button secondary" href={`${repoUrl}/tree/main/examples`}>See real reports</a>
+          <a className="button secondary" href={`${repoUrl}/issues/new`}>Report a wrong ranking</a>
         </div>
       </section>
 
       <footer>
         <a className="brand" href="#top"><span className="brand-mark">FM</span><span>FixMap</span></a>
-        <p>Open-source repo intelligence for AI-assisted development.</p>
-        <a href="https://github.com/aryamthecodebreaker/FixMap">MIT licensed on GitHub ↗</a>
+        <p>
+          Open-source repo intelligence for AI-assisted development. v{cli.version}, MIT licensed.
+          If FixMap ranks the wrong file on your repository, that case is worth more than any we
+          picked ourselves — open an issue and it becomes a permanent benchmark case.
+        </p>
+        <a href={repoUrl}>MIT licensed on GitHub ↗</a>
       </footer>
     </main>
   );
diff --git a/apps/web/app/sample-repo.ts b/apps/web/app/sample-repo.ts
new file mode 100644
index 0000000..1ee4ff3
--- /dev/null
+++ b/apps/web/app/sample-repo.ts
@@ -0,0 +1,284 @@
+import type { RepoFile, RepoMap } from "@aryam/fixmap-core/browser";
+
+// A small mail-sending API, written the way one actually would be — imports that resolve,
+// symbols that are defined once, and the debris a real checkout carries: a committed
+// build output, an examples folder, a type declaration, a lockfile, docs.
+//
+// The debris is the point. A sample repository containing only the answer would make
+// FixMap look infallible and teach nothing. These files are here so the demo can show
+// what gets deprioritized, what gets excluded outright, and why.
+
+const files: RepoFile[] = [
+  source("src/auth/reset-password.ts", `import { createHash, randomBytes } from "node:crypto";
+import { config } from "../config.js";
+import { resetEmailTemplate } from "../email/templates/reset.js";
+import { sendMail } from "../email/transport.js";
+import { tokenStore } from "./token-store.js";
+
+export const TOKEN_TTL_MINUTES = 30;
+
+export async function createResetToken(email: string): Promise<string> {
+  const token = randomBytes(32).toString("hex");
+  const digest = createHash("sha256").update(token).digest("hex");
+
+  await tokenStore.put(digest, {
+    email,
+    expiresAt: Date.now() + TOKEN_TTL_MINUTES * 60_000
+  });
+
+  await sendMail({
+    to: email,
+    subject: "Reset your password",
+    html: resetEmailTemplate({ token, expiresInMinutes: TOKEN_TTL_MINUTES, origin: config.publicOrigin })
+  });
+
+  return token;
+}
+
+export async function consumeResetToken(token: string): Promise<string> {
+  const digest = createHash("sha256").update(token).digest("hex");
+  const record = await tokenStore.take(digest);
+
+  if (!record || record.expiresAt < Date.now()) {
+    throw new Error("reset token expired");
+  }
+
+  return record.email;
+}`),
+
+  source("src/auth/token-store.ts", `type TokenRecord = { email: string; expiresAt: number };
+
+const records = new Map<string, TokenRecord>();
+
+export const tokenStore = {
+  async put(digest: string, record: TokenRecord): Promise<void> {
+    records.set(digest, record);
+  },
+  async take(digest: string): Promise<TokenRecord | undefined> {
+    const record = records.get(digest);
+    records.delete(digest);
+    return record;
+  }
+};`),
+
+  source("src/auth/session.ts", `import { randomUUID } from "node:crypto";
+
+export const SESSION_TTL_HOURS = 12;
+
+export function createSession(userId: string) {
+  return {
+    id: randomUUID(),
+    userId,
+    expiresAt: Date.now() + SESSION_TTL_HOURS * 3_600_000
+  };
+}
+
+export function isExpired(session: { expiresAt: number }): boolean {
+  return session.expiresAt < Date.now();
+}`),
+
+  source("src/email/transport.ts", `import { createTransport } from "nodemailer";
+import { config } from "../config.js";
+
+const transport = createTransport({
+  host: config.smtpHost,
+  port: config.smtpPort,
+  auth: { user: config.smtpUser, pass: config.smtpPassword }
+});
+
+export async function sendMail(message: { to: string; subject: string; html: string }): Promise<string> {
+  const result = await transport.sendMail({ from: config.mailFrom, ...message });
+
+  if (result.rejected.length > 0) {
+    throw new Error(\`mail rejected for \${result.rejected.join(", ")}\`);
+  }
+
+  return result.messageId;
+}`),
+
+  source("src/email/templates/reset.ts", `export function resetEmailTemplate(input: {
+  token: string;
+  expiresInMinutes: number;
+  origin: string;
+}): string {
+  const link = \`\${input.origin}/reset?token=\${input.token}\`;
+
+  return \`<p>Choose a new password using the link below.</p>
+<p>It expires in \${input.expiresInMinutes} minutes.</p>
+<p><a href="\${link}">Choose a new password</a></p>\`;
+}`),
+
+  source("src/billing/invoice.ts", `import { config } from "../config.js";
+
+export async function createInvoice(customerId: string, amountCents: number) {
+  const response = await fetch(\`\${config.billingApiUrl}/invoices\`, {
+    method: "POST",
+    headers: { authorization: \`Bearer \${config.billingApiKey}\` },
+    body: JSON.stringify({ customerId, amountCents, currency: "usd" })
+  });
+
+  if (!response.ok) {
+    throw new Error(\`invoice creation failed with \${response.status}\`);
+  }
+
+  return response.json();
+}`),
+
+  source("src/http/routes.ts", `import { Router } from "express";
+import { consumeResetToken, createResetToken } from "../auth/reset-password.js";
+import { createSession } from "../auth/session.js";
+import { createInvoice } from "../billing/invoice.js";
+
+export const routes = Router();
+
+routes.post("/auth/forgot", async (request, response) => {
+  await createResetToken(request.body.email);
+  response.status(202).json({ accepted: true });
+});
+
+routes.post("/auth/reset", async (request, response) => {
+  const email = await consumeResetToken(request.body.token);
+  response.json(createSession(email));
+});
+
+routes.post("/billing/invoices", async (request, response) => {
+  response.json(await createInvoice(request.body.customerId, request.body.amountCents));
+});`),
+
+  configFile("src/config.ts", `export const config = {
+  publicOrigin: process.env.PUBLIC_ORIGIN ?? "http://localhost:3000",
+  smtpHost: process.env.SMTP_HOST ?? "localhost",
+  smtpPort: Number(process.env.SMTP_PORT ?? 1025),
+  smtpUser: process.env.SMTP_USER ?? "",
+  smtpPassword: process.env.SMTP_PASSWORD ?? "",
+  mailFrom: process.env.MAIL_FROM ?? "no-reply@example.com",
+  billingApiUrl: process.env.BILLING_API_URL ?? "https://billing.example.com",
+  billingApiKey: process.env.BILLING_API_KEY ?? ""
+};`),
+
+  // Committed build output. `src/auth/reset-password.ts` produces it, so editing it is
+  // always wrong — the next build overwrites the change.
+  source("dist/auth/reset-password.js", `import { createHash, randomBytes } from "node:crypto";
+import { config } from "../config.js";
+import { resetEmailTemplate } from "../email/templates/reset.js";
+import { sendMail } from "../email/transport.js";
+import { tokenStore } from "./token-store.js";
+export const TOKEN_TTL_MINUTES = 30;
+export async function createResetToken(email) {
+  const token = randomBytes(32).toString("hex");
+  const digest = createHash("sha256").update(token).digest("hex");
+  await tokenStore.put(digest, { email, expiresAt: Date.now() + TOKEN_TTL_MINUTES * 60000 });
+  await sendMail({ to: email, subject: "Reset your password", html: resetEmailTemplate({ token, expiresInMinutes: TOKEN_TTL_MINUTES, origin: config.publicOrigin }) });
+  return token;
+}`),
+
+  // Demo code names the same subsystems without implementing them.
+  source("examples/auth/basic-login.js", `// Minimal example: create a session and print its id.
+import { createSession } from "../../src/auth/session.js";
+
+const session = createSession("demo-user");
+console.log("signed in", session.id, "expires", new Date(session.expiresAt));`),
+
+  { ...source("test/auth/reset-password.test.ts", `import { describe, expect, it } from "vitest";
+import { consumeResetToken, createResetToken, TOKEN_TTL_MINUTES } from "../../src/auth/reset-password.js";
+
+describe("password reset", () => {
+  it("round-trips a token", async () => {
+    const token = await createResetToken("user@example.com");
+    expect(await consumeResetToken(token)).toBe("user@example.com");
+  });
+
+  it("rejects a token twice", async () => {
+    const token = await createResetToken("user@example.com");
+    await consumeResetToken(token);
+    await expect(consumeResetToken(token)).rejects.toThrow("reset token expired");
+  });
+
+  it("expires after the configured window", () => {
+    expect(TOKEN_TTL_MINUTES).toBe(30);
+  });
+});`), isTest: true },
+
+  source("types/nodemailer.d.ts", `declare module "nodemailer" {
+  export type SentMessage = { messageId: string; rejected: string[] };
+  export function createTransport(options: unknown): {
+    sendMail(message: unknown): Promise<SentMessage>;
+  };
+}`),
+
+  configFile("package.json", `{
+  "name": "sample-api",
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}`),
+
+  configFile("package-lock.json", `{ "name": "sample-api", "lockfileVersion": 3, "packages": {} }`),
+
+  doc("docs/configuration.md", `# Configuration
+
+Every setting is read from the environment in \`src/config.ts\`.
+
+| Variable | Default | Used by |
+| --- | --- | --- |
+| \`SMTP_HOST\` | \`localhost\` | password reset and receipt email |
+| \`MAIL_FROM\` | \`no-reply@example.com\` | every outbound message |
+| \`BILLING_API_URL\` | \`https://billing.example.com\` | invoice creation |`),
+
+  doc("README.md", `# sample-api
+
+A small Express service with password reset, sessions, and invoicing.
+
+    npm install
+    npm test`)
+];
+
+export const sampleRepo: RepoMap = {
+  root: "sample-api",
+  files,
+  packageScripts: [
+    { name: "test", command: "vitest run", packageDir: "" },
+    { name: "typecheck", command: "tsc --noEmit", packageDir: "" }
+  ],
+  changedFiles: [],
+  diffText: "",
+  packageManager: "npm",
+  diagnostics: []
+};
+
+export const samplePaths: string[] = files.map((file) => file.path);
+
+/** The same repository, with a diff applied — the second input `fixmap verify` needs. */
+export function sampleRepoWithChanges(changedFiles: string[]): RepoMap {
+  return { ...sampleRepo, changedFiles };
+}
+
+function source(path: string, textSample: string): RepoFile {
+  return file(path, textSample, "code");
+}
+
+function configFile(path: string, textSample: string): RepoFile {
+  // `src/config.ts` is code by extension; the scanner classifies by content role, and
+  // treating settings files as config is what makes the demo match a real scan.
+  return file(path, textSample, path.endsWith(".ts") ? "code" : "config");
+}
+
+function doc(path: string, textSample: string): RepoFile {
+  return file(path, textSample, "documentation");
+}
+
+function file(path: string, textSample: string, kind: RepoFile["kind"]): RepoFile {
+  const extensionIndex = path.lastIndexOf(".");
+  return {
+    path,
+    extension: extensionIndex >= 0 ? path.slice(extensionIndex) : "",
+    sizeBytes: textSample.length,
+    isTest: false,
+    isSource: true,
+    kind,
+    textSample,
+    textSampleComplete: true
+  };
+}
diff --git a/packages/action/dist/index.mjs b/packages/action/dist/index.mjs
index 1769078..03f02c8 100644
--- a/packages/action/dist/index.mjs
+++ b/packages/action/dist/index.mjs
@@ -1045,7 +1045,140 @@ function isNearbyChangedFile(path, changedFiles) {
   return changedFiles.some((changedPath) => changedPath !== path && changedPath.startsWith(`${folder}/`));
 }
 
+// packages/core/dist/test-gates.js
+var GATE_PATTERN = /\.(skipIf|runIf)\s*\(/;
+var ENV_NAME_PATTERNS = [/process\.env\.([A-Z][A-Z0-9_]*)/g, /process\.env\[["']([A-Z][A-Z0-9_]*)["']\]/g];
+function findGatedTestDiagnostics(files, routedTestPaths) {
+  const routed = new Set(routedTestPaths);
+  const diagnostics = [];
+  for (const file of files) {
+    if (!file.isTest || !routed.has(file.path) || !GATE_PATTERN.test(file.textSample)) {
+      continue;
+    }
+    diagnostics.push({
+      code: "gated-test-skipped",
+      severity: "warning",
+      message: gateMessage(file.path, extractEnvNames(file.textSample))
+    });
+  }
+  return diagnostics;
+}
+function gateMessage(path, envNames) {
+  if (envNames.length === 0) {
+    return `${path} contains conditionally skipped suites; verify the suggested test command actually exercises it.`;
+  }
+  const condition = envNames.length === 1 ? `${envNames[0]} is set` : `${envNames.join(", ")} are set`;
+  return `${path} is skipped unless ${condition}; the suggested test command will not exercise it by default.`;
+}
+function extractEnvNames(textSample) {
+  const names = /* @__PURE__ */ new Set();
+  for (const pattern of ENV_NAME_PATTERNS) {
+    for (const match of textSample.matchAll(pattern)) {
+      names.add(match[1] ?? "");
+    }
+  }
+  names.delete("");
+  return [...names].sort((a, b) => a.localeCompare(b));
+}
+
 // packages/core/dist/report.js
+var MAX_REPORTED_TERMS = 8;
+function buildReportFromRepo(repo, input) {
+  const contextFiles = rankContextFiles(repo, {
+    issueText: input.issueText,
+    diffText: repo.diffText
+  });
+  const grounding = analyzeTaskGrounding(repo, {
+    issueText: input.issueText,
+    diffText: repo.diffText
+  });
+  const ranking = buildRankingShape(contextFiles);
+  const contextPaths = contextFiles.map((file) => file.path);
+  const testRoutes = buildTestRoutes(repo, contextPaths);
+  const routedTestPaths = [...new Set(testRoutes.flatMap((route) => route.relatedFiles))];
+  return {
+    summary: buildSummary(contextFiles.length, testRoutes.length),
+    contextFiles,
+    testRoutes,
+    risks: buildRiskNotes(contextPaths, repo.changedFiles),
+    changedFiles: repo.changedFiles,
+    diagnostics: [
+      ...repo.diagnostics,
+      ...findGatedTestDiagnostics(repo.files, routedTestPaths),
+      ...findTaskDiagnostics(grounding, ranking),
+      ...findEmptyResultDiagnostics(repo, contextFiles, input.issueText ?? "")
+    ],
+    analysis: {
+      grounding,
+      ranking,
+      nextAction: buildNextAction(grounding, ranking, contextFiles)
+    }
+  };
+}
+function findTaskDiagnostics(grounding, ranking) {
+  const diagnostics = [];
+  if (grounding.unresolvedIdentifiers.length > 0) {
+    diagnostics.push({
+      code: "unresolved-identifier",
+      severity: "warning",
+      message: `Identifier${grounding.unresolvedIdentifiers.length === 1 ? "" : "s"} not found exactly in the scanned repository: ${grounding.unresolvedIdentifiers.join(", ")}. Component words from unresolved identifiers were ignored, and unsupported recommendations were capped at low confidence.`
+    });
+  }
+  if (grounding.partiallyResolvedIdentifiers.length > 0) {
+    diagnostics.push({
+      code: "partially-resolved-identifier",
+      severity: "info",
+      message: `Identifier${grounding.partiallyResolvedIdentifiers.length === 1 ? "" : "s"} matched a longer repository symbol by component terms: ${grounding.partiallyResolvedIdentifiers.join(", ")}. The component terms were retained, but confidence was capped at medium.`
+    });
+  }
+  if (grounding.unverifiedIdentifiers.length > 0) {
+    diagnostics.push({
+      code: "identifier-unverified",
+      severity: "warning",
+      message: `Identifier${grounding.unverifiedIdentifiers.length === 1 ? "" : "s"} could not be verified because one or more source files exceeded the text-sampling limit: ${grounding.unverifiedIdentifiers.join(", ")}. FixMap did not claim that the identifier was absent, and confidence was capped at low without another anchor.`
+    });
+  }
+  if (grounding.specificity === "vague") {
+    diagnostics.push({
+      code: "vague-task",
+      severity: "warning",
+      message: "The task is broad and has no verified symbol, file, or diff anchor. Treat the ranking as subsystem guidance only, or add a failing behavior, error string, command, symbol, or file path."
+    });
+  }
+  if (ranking.clustered && grounding.specificity !== "anchored") {
+    diagnostics.push({
+      code: "flat-ranking",
+      severity: "warning",
+      message: "The leading files have tightly clustered scores, so FixMap cannot identify a decisive edit point. Use them as a starting neighborhood and verify the exact file before editing."
+    });
+  }
+  return diagnostics;
+}
+function findEmptyResultDiagnostics(repo, contextFiles, issueText) {
+  if (contextFiles.length > 0 || repo.files.length === 0) {
+    return [];
+  }
+  const signals = extractTaskSignals({
+    issueText,
+    diffText: repo.diffText,
+    changedFiles: repo.changedFiles
+  });
+  const terms = [...signals.tokens].sort();
+  if (terms.length === 0 && signals.identifiers.size === 0 && signals.fileMentions.size === 0) {
+    return [{
+      code: "no-task-terms",
+      severity: "warning",
+      message: "No context files: the task text contained no searchable term. Every word was a common word, a language keyword, or shorter than three characters. Name the failing behavior, a symbol, or a file path."
+    }];
+  }
+  const preview = terms.slice(0, MAX_REPORTED_TERMS).join(", ");
+  const remainder = terms.length > MAX_REPORTED_TERMS ? ` (+${terms.length - MAX_REPORTED_TERMS} more)` : "";
+  return [{
+    code: "no-context-match",
+    severity: "warning",
+    message: `No context files: no file in the ${repo.files.length} scanned matched the task terms ${preview}${remainder}. The repository may not contain this behavior, or it may name it differently.`
+  }];
+}
 function scopeToPackage(paths, packageDir) {
   if (!packageDir) {
     return paths;
@@ -1473,140 +1606,10 @@ function normalizePath(path) {
   return path.split(sep).join("/");
 }
 
-// packages/core/dist/test-gates.js
-var GATE_PATTERN = /\.(skipIf|runIf)\s*\(/;
-var ENV_NAME_PATTERNS = [/process\.env\.([A-Z][A-Z0-9_]*)/g, /process\.env\[["']([A-Z][A-Z0-9_]*)["']\]/g];
-function findGatedTestDiagnostics(files, routedTestPaths) {
-  const routed = new Set(routedTestPaths);
-  const diagnostics = [];
-  for (const file of files) {
-    if (!file.isTest || !routed.has(file.path) || !GATE_PATTERN.test(file.textSample)) {
-      continue;
-    }
-    diagnostics.push({
-      code: "gated-test-skipped",
-      severity: "warning",
-      message: gateMessage(file.path, extractEnvNames(file.textSample))
-    });
-  }
-  return diagnostics;
-}
-function gateMessage(path, envNames) {
-  if (envNames.length === 0) {
-    return `${path} contains conditionally skipped suites; verify the suggested test command actually exercises it.`;
-  }
-  const condition = envNames.length === 1 ? `${envNames[0]} is set` : `${envNames.join(", ")} are set`;
-  return `${path} is skipped unless ${condition}; the suggested test command will not exercise it by default.`;
-}
-function extractEnvNames(textSample) {
-  const names = /* @__PURE__ */ new Set();
-  for (const pattern of ENV_NAME_PATTERNS) {
-    for (const match of textSample.matchAll(pattern)) {
-      names.add(match[1] ?? "");
-    }
-  }
-  names.delete("");
-  return [...names].sort((a, b) => a.localeCompare(b));
-}
-
 // packages/core/dist/plan.js
-var MAX_REPORTED_TERMS = 8;
 async function buildFixMapReport(input) {
   const repo = await scanRepo(input);
-  const contextFiles = rankContextFiles(repo, {
-    issueText: input.issueText,
-    diffText: repo.diffText
-  });
-  const grounding = analyzeTaskGrounding(repo, {
-    issueText: input.issueText,
-    diffText: repo.diffText
-  });
-  const ranking = buildRankingShape(contextFiles);
-  const contextPaths = contextFiles.map((file) => file.path);
-  const testRoutes = buildTestRoutes(repo, contextPaths);
-  const routedTestPaths = [...new Set(testRoutes.flatMap((route) => route.relatedFiles))];
-  return {
-    summary: buildSummary(contextFiles.length, testRoutes.length),
-    contextFiles,
-    testRoutes,
-    risks: buildRiskNotes(contextPaths, repo.changedFiles),
-    changedFiles: repo.changedFiles,
-    diagnostics: [
-      ...repo.diagnostics,
-      ...findGatedTestDiagnostics(repo.files, routedTestPaths),
-      ...findTaskDiagnostics(grounding, ranking),
-      ...findEmptyResultDiagnostics(repo, contextFiles, input.issueText ?? "")
-    ],
-    analysis: {
-      grounding,
-      ranking,
-      nextAction: buildNextAction(grounding, ranking, contextFiles)
-    }
-  };
-}
-function findTaskDiagnostics(grounding, ranking) {
-  const diagnostics = [];
-  if (grounding.unresolvedIdentifiers.length > 0) {
-    diagnostics.push({
-      code: "unresolved-identifier",
-      severity: "warning",
-      message: `Identifier${grounding.unresolvedIdentifiers.length === 1 ? "" : "s"} not found exactly in the scanned repository: ${grounding.unresolvedIdentifiers.join(", ")}. Component words from unresolved identifiers were ignored, and unsupported recommendations were capped at low confidence.`
-    });
-  }
-  if (grounding.partiallyResolvedIdentifiers.length > 0) {
-    diagnostics.push({
-      code: "partially-resolved-identifier",
-      severity: "info",
-      message: `Identifier${grounding.partiallyResolvedIdentifiers.length === 1 ? "" : "s"} matched a longer repository symbol by component terms: ${grounding.partiallyResolvedIdentifiers.join(", ")}. The component terms were retained, but confidence was capped at medium.`
-    });
-  }
-  if (grounding.unverifiedIdentifiers.length > 0) {
-    diagnostics.push({
-      code: "identifier-unverified",
-      severity: "warning",
-      message: `Identifier${grounding.unverifiedIdentifiers.length === 1 ? "" : "s"} could not be verified because one or more source files exceeded the text-sampling limit: ${grounding.unverifiedIdentifiers.join(", ")}. FixMap did not claim that the identifier was absent, and confidence was capped at low without another anchor.`
-    });
-  }
-  if (grounding.specificity === "vague") {
-    diagnostics.push({
-      code: "vague-task",
-      severity: "warning",
-      message: "The task is broad and has no verified symbol, file, or diff anchor. Treat the ranking as subsystem guidance only, or add a failing behavior, error string, command, symbol, or file path."
-    });
-  }
-  if (ranking.clustered && grounding.specificity !== "anchored") {
-    diagnostics.push({
-      code: "flat-ranking",
-      severity: "warning",
-      message: "The leading files have tightly clustered scores, so FixMap cannot identify a decisive edit point. Use them as a starting neighborhood and verify the exact file before editing."
-    });
-  }
-  return diagnostics;
-}
-function findEmptyResultDiagnostics(repo, contextFiles, issueText) {
-  if (contextFiles.length > 0 || repo.files.length === 0) {
-    return [];
-  }
-  const signals = extractTaskSignals({
-    issueText,
-    diffText: repo.diffText,
-    changedFiles: repo.changedFiles
-  });
-  const terms = [...signals.tokens].sort();
-  if (terms.length === 0 && signals.identifiers.size === 0 && signals.fileMentions.size === 0) {
-    return [{
-      code: "no-task-terms",
-      severity: "warning",
-      message: "No context files: the task text contained no searchable term. Every word was a common word, a language keyword, or shorter than three characters. Name the failing behavior, a symbol, or a file path."
-    }];
-  }
-  const preview = terms.slice(0, MAX_REPORTED_TERMS).join(", ");
-  const remainder = terms.length > MAX_REPORTED_TERMS ? ` (+${terms.length - MAX_REPORTED_TERMS} more)` : "";
-  return [{
-    code: "no-context-match",
-    severity: "warning",
-    message: `No context files: no file in the ${repo.files.length} scanned matched the task terms ${preview}${remainder}. The repository may not contain this behavior, or it may name it differently.`
-  }];
+  return buildReportFromRepo(repo, { issueText: input.issueText });
 }
 
 // packages/action/src/github.ts
diff --git a/packages/core/src/browser.ts b/packages/core/src/browser.ts
index 7ca3331..03e068f 100644
--- a/packages/core/src/browser.ts
+++ b/packages/core/src/browser.ts
@@ -1,6 +1,22 @@
 // Browser-safe entrypoint: these modules are deterministic and do not access
 // the filesystem, child processes, or other Node-only APIs.
+//
+// The website demo imports this. It runs the same ranking, report assembly,
+// explanation, and verification the CLI runs — only the scanner is missing,
+// because a browser has no repository to scan.
+export { explainFile } from "./explain.js";
 export { rankContextFiles } from "./rank.js";
-export { buildTestRoutes } from "./report.js";
+export { buildReportFromRepo, buildRiskNotes, buildTestRoutes, renderMarkdownReport } from "./report.js";
 export { tokenizePath, tokenizeText } from "./signals.js";
-export type { RankedFile, RepoFile, RepoMap, TestRoute } from "./types.js";
+export { renderVerifyMarkdown, verifyPlan } from "./verify.js";
+export type { FileExplanation } from "./explain.js";
+export type {
+  FixMapReport,
+  RankedFile,
+  RepoFile,
+  RepoMap,
+  RiskNote,
+  TestRoute,
+  VerifyFinding,
+  VerifyResult
+} from "./types.js";
diff --git a/packages/core/src/plan.ts b/packages/core/src/plan.ts
index 3532008..d2b9174 100644
--- a/packages/core/src/plan.ts
+++ b/packages/core/src/plan.ts
@@ -1,151 +1,10 @@
-import {
-  analyzeTaskGrounding,
-  buildNextAction,
-  buildRankingShape
-} from "./grounding.js";
-import type { RankingShape, TaskGrounding } from "./grounding.js";
-import { rankContextFiles } from "./rank.js";
-import { buildRiskNotes, buildSummary, buildTestRoutes } from "./report.js";
+import { buildReportFromRepo } from "./report.js";
 import { scanRepo } from "./repo-scan.js";
-import { extractTaskSignals } from "./signals.js";
-import { findGatedTestDiagnostics } from "./test-gates.js";
-import type { FixMapInput, FixMapReport, RankedFile, RepoMap, ScanDiagnostic } from "./types.js";
-
-const MAX_REPORTED_TERMS = 8;
+import type { FixMapInput, FixMapReport } from "./types.js";
 
 export async function buildFixMapReport(
   input: Pick<FixMapInput, "repoRoot" | "issueText" | "diffSpec" | "baseRef" | "headRef">
 ): Promise<FixMapReport> {
   const repo = await scanRepo(input);
-  const contextFiles = rankContextFiles(repo, {
-    issueText: input.issueText,
-    diffText: repo.diffText
-  });
-  const grounding = analyzeTaskGrounding(repo, {
-    issueText: input.issueText,
-    diffText: repo.diffText
-  });
-  const ranking = buildRankingShape(contextFiles);
-  const contextPaths = contextFiles.map((file) => file.path);
-  const testRoutes = buildTestRoutes(repo, contextPaths);
-  const routedTestPaths = [...new Set(testRoutes.flatMap((route) => route.relatedFiles))];
-
-  return {
-    summary: buildSummary(contextFiles.length, testRoutes.length),
-    contextFiles,
-    testRoutes,
-    risks: buildRiskNotes(contextPaths, repo.changedFiles),
-    changedFiles: repo.changedFiles,
-    diagnostics: [
-      ...repo.diagnostics,
-      ...findGatedTestDiagnostics(repo.files, routedTestPaths),
-      ...findTaskDiagnostics(grounding, ranking),
-      ...findEmptyResultDiagnostics(repo, contextFiles, input.issueText ?? "")
-    ],
-    analysis: {
-      grounding,
-      ranking,
-      nextAction: buildNextAction(grounding, ranking, contextFiles)
-    }
-  };
-}
-
-function findTaskDiagnostics(
-  grounding: TaskGrounding,
-  ranking: RankingShape
-): ScanDiagnostic[] {
-  const diagnostics: ScanDiagnostic[] = [];
-
-  if (grounding.unresolvedIdentifiers.length > 0) {
-    diagnostics.push({
-      code: "unresolved-identifier",
-      severity: "warning",
-      message:
-        `Identifier${grounding.unresolvedIdentifiers.length === 1 ? "" : "s"} not found exactly in the scanned repository: ` +
-        `${grounding.unresolvedIdentifiers.join(", ")}. Component words from unresolved identifiers were ignored, ` +
-        "and unsupported recommendations were capped at low confidence."
-    });
-  }
-
-  if (grounding.partiallyResolvedIdentifiers.length > 0) {
-    diagnostics.push({
-      code: "partially-resolved-identifier",
-      severity: "info",
-      message:
-        `Identifier${grounding.partiallyResolvedIdentifiers.length === 1 ? "" : "s"} matched a longer repository symbol by component terms: ` +
-        `${grounding.partiallyResolvedIdentifiers.join(", ")}. The component terms were retained, but confidence was capped at medium.`
-    });
-  }
-
-  if (grounding.unverifiedIdentifiers.length > 0) {
-    diagnostics.push({
-      code: "identifier-unverified",
-      severity: "warning",
-      message:
-        `Identifier${grounding.unverifiedIdentifiers.length === 1 ? "" : "s"} could not be verified because one or more source files exceeded the text-sampling limit: ` +
-        `${grounding.unverifiedIdentifiers.join(", ")}. FixMap did not claim that the identifier was absent, and confidence was capped at low without another anchor.`
-    });
-  }
-
-  if (grounding.specificity === "vague") {
-    diagnostics.push({
-      code: "vague-task",
-      severity: "warning",
-      message:
-        "The task is broad and has no verified symbol, file, or diff anchor. Treat the ranking as subsystem guidance only, " +
-        "or add a failing behavior, error string, command, symbol, or file path."
-    });
-  }
-
-  if (ranking.clustered && grounding.specificity !== "anchored") {
-    diagnostics.push({
-      code: "flat-ranking",
-      severity: "warning",
-      message:
-        "The leading files have tightly clustered scores, so FixMap cannot identify a decisive edit point. " +
-        "Use them as a starting neighborhood and verify the exact file before editing."
-    });
-  }
-
-  return diagnostics;
-}
-
-// An empty report is the one result that explains nothing on its own. Say whether the task
-// text carried no searchable terms or whether the terms simply matched no file, so the
-// reader knows which end to fix.
-function findEmptyResultDiagnostics(
-  repo: RepoMap,
-  contextFiles: RankedFile[],
-  issueText: string
-): ScanDiagnostic[] {
-  if (contextFiles.length > 0 || repo.files.length === 0) {
-    return [];
-  }
-
-  const signals = extractTaskSignals({
-    issueText,
-    diffText: repo.diffText,
-    changedFiles: repo.changedFiles
-  });
-  const terms = [...signals.tokens].sort();
-
-  if (terms.length === 0 && signals.identifiers.size === 0 && signals.fileMentions.size === 0) {
-    return [{
-      code: "no-task-terms",
-      severity: "warning",
-      message:
-        "No context files: the task text contained no searchable term. Every word was a common word, " +
-        "a language keyword, or shorter than three characters. Name the failing behavior, a symbol, or a file path."
-    }];
-  }
-
-  const preview = terms.slice(0, MAX_REPORTED_TERMS).join(", ");
-  const remainder = terms.length > MAX_REPORTED_TERMS ? ` (+${terms.length - MAX_REPORTED_TERMS} more)` : "";
-  return [{
-    code: "no-context-match",
-    severity: "warning",
-    message:
-      `No context files: no file in the ${repo.files.length} scanned matched the task terms ${preview}${remainder}. ` +
-      "The repository may not contain this behavior, or it may name it differently."
-  }];
+  return buildReportFromRepo(repo, { issueText: input.issueText });
 }
diff --git a/packages/core/src/report.ts b/packages/core/src/report.ts
index 9d501c3..fe810f1 100644
--- a/packages/core/src/report.ts
+++ b/packages/core/src/report.ts
@@ -1,5 +1,156 @@
-import { tokenizePath } from "./signals.js";
-import type { FixMapReport, RepoMap, RiskNote, TestRoute } from "./types.js";
+import {
+  analyzeTaskGrounding,
+  buildNextAction,
+  buildRankingShape
+} from "./grounding.js";
+import type { RankingShape, TaskGrounding } from "./grounding.js";
+import { rankContextFiles } from "./rank.js";
+import { extractTaskSignals, tokenizePath } from "./signals.js";
+import { findGatedTestDiagnostics } from "./test-gates.js";
+import type { FixMapReport, RankedFile, RepoMap, RiskNote, ScanDiagnostic, TestRoute } from "./types.js";
+
+const MAX_REPORTED_TERMS = 8;
+
+// Everything between a scanned repository and a finished report. Kept separate from the
+// scan so the same assembly runs in the CLI, the MCP server, the Action, and the browser
+// demo on the website — a demo that reimplemented this would drift from the tool it
+// advertises, and the drift would always favor the demo.
+export function buildReportFromRepo(
+  repo: RepoMap,
+  input: { issueText?: string | undefined }
+): FixMapReport {
+  const contextFiles = rankContextFiles(repo, {
+    issueText: input.issueText,
+    diffText: repo.diffText
+  });
+  const grounding = analyzeTaskGrounding(repo, {
+    issueText: input.issueText,
+    diffText: repo.diffText
+  });
+  const ranking = buildRankingShape(contextFiles);
+  const contextPaths = contextFiles.map((file) => file.path);
+  const testRoutes = buildTestRoutes(repo, contextPaths);
+  const routedTestPaths = [...new Set(testRoutes.flatMap((route) => route.relatedFiles))];
+
+  return {
+    summary: buildSummary(contextFiles.length, testRoutes.length),
+    contextFiles,
+    testRoutes,
+    risks: buildRiskNotes(contextPaths, repo.changedFiles),
+    changedFiles: repo.changedFiles,
+    diagnostics: [
+      ...repo.diagnostics,
+      ...findGatedTestDiagnostics(repo.files, routedTestPaths),
+      ...findTaskDiagnostics(grounding, ranking),
+      ...findEmptyResultDiagnostics(repo, contextFiles, input.issueText ?? "")
+    ],
+    analysis: {
+      grounding,
+      ranking,
+      nextAction: buildNextAction(grounding, ranking, contextFiles)
+    }
+  };
+}
+
+function findTaskDiagnostics(
+  grounding: TaskGrounding,
+  ranking: RankingShape
+): ScanDiagnostic[] {
+  const diagnostics: ScanDiagnostic[] = [];
+
+  if (grounding.unresolvedIdentifiers.length > 0) {
+    diagnostics.push({
+      code: "unresolved-identifier",
+      severity: "warning",
+      message:
+        `Identifier${grounding.unresolvedIdentifiers.length === 1 ? "" : "s"} not found exactly in the scanned repository: ` +
+        `${grounding.unresolvedIdentifiers.join(", ")}. Component words from unresolved identifiers were ignored, ` +
+        "and unsupported recommendations were capped at low confidence."
+    });
+  }
+
+  if (grounding.partiallyResolvedIdentifiers.length > 0) {
+    diagnostics.push({
+      code: "partially-resolved-identifier",
+      severity: "info",
+      message:
+        `Identifier${grounding.partiallyResolvedIdentifiers.length === 1 ? "" : "s"} matched a longer repository symbol by component terms: ` +
+        `${grounding.partiallyResolvedIdentifiers.join(", ")}. The component terms were retained, but confidence was capped at medium.`
+    });
+  }
+
+  if (grounding.unverifiedIdentifiers.length > 0) {
+    diagnostics.push({
+      code: "identifier-unverified",
+      severity: "warning",
+      message:
+        `Identifier${grounding.unverifiedIdentifiers.length === 1 ? "" : "s"} could not be verified because one or more source files exceeded the text-sampling limit: ` +
+        `${grounding.unverifiedIdentifiers.join(", ")}. FixMap did not claim that the identifier was absent, and confidence was capped at low without another anchor.`
+    });
+  }
+
+  if (grounding.specificity === "vague") {
+    diagnostics.push({
+      code: "vague-task",
+      severity: "warning",
+      message:
+        "The task is broad and has no verified symbol, file, or diff anchor. Treat the ranking as subsystem guidance only, " +
+        "or add a failing behavior, error string, command, symbol, or file path."
+    });
+  }
+
+  if (ranking.clustered && grounding.specificity !== "anchored") {
+    diagnostics.push({
+      code: "flat-ranking",
+      severity: "warning",
+      message:
+        "The leading files have tightly clustered scores, so FixMap cannot identify a decisive edit point. " +
+        "Use them as a starting neighborhood and verify the exact file before editing."
+    });
+  }
+
+  return diagnostics;
+}
+
+// An empty report is the one result that explains nothing on its own. Say whether the task
+// text carried no searchable terms or whether the terms simply matched no file, so the
+// reader knows which end to fix.
+function findEmptyResultDiagnostics(
+  repo: RepoMap,
+  contextFiles: RankedFile[],
+  issueText: string
+): ScanDiagnostic[] {
+  if (contextFiles.length > 0 || repo.files.length === 0) {
+    return [];
+  }
+
+  const signals = extractTaskSignals({
+    issueText,
+    diffText: repo.diffText,
+    changedFiles: repo.changedFiles
+  });
+  const terms = [...signals.tokens].sort();
+
+  if (terms.length === 0 && signals.identifiers.size === 0 && signals.fileMentions.size === 0) {
+    return [{
+      code: "no-task-terms",
+      severity: "warning",
+      message:
+        "No context files: the task text contained no searchable term. Every word was a common word, " +
+        "a language keyword, or shorter than three characters. Name the failing behavior, a symbol, or a file path."
+    }];
+  }
+
+  const preview = terms.slice(0, MAX_REPORTED_TERMS).join(", ");
+  const remainder = terms.length > MAX_REPORTED_TERMS ? ` (+${terms.length - MAX_REPORTED_TERMS} more)` : "";
+  return [{
+    code: "no-context-match",
+    severity: "warning",
+    message:
+      `No context files: no file in the ${repo.files.length} scanned matched the task terms ${preview}${remainder}. ` +
+      "The repository may not contain this behavior, or it may name it differently."
+  }];
+}
 
 // A route runs one package's script, so it can only exercise files inside that package.
 // Listing a sibling package's tests beneath it claims something the command cannot do: