From ca029396cd272b5d4b4ecf47be69edc2ac9bc8e0 Mon Sep 17 00:00:00 2001
From: Aryam Goyal <aryamgoyal18@gmail.com>
Date: Sun, 9 Aug 2026 12:46:01 +0530
Subject: [PATCH 01/10] Fix unreleased diagnostics and redesign discovery
 surfaces

---
 README.md                                     |  22 ++-
 .../app/_components/interactive-map-stage.tsx |   4 +-
 apps/web/app/_components/product-map.tsx      |   4 +-
 apps/web/app/_lib/site-data.ts                |   3 +
 apps/web/app/changelog/page.tsx               |   2 +-
 apps/web/app/demo.tsx                         |  10 +-
 apps/web/app/demo/page.tsx                    |  12 +-
 apps/web/app/docs/page.tsx                    |  14 +-
 apps/web/app/evidence/page.tsx                |   2 +-
 apps/web/app/get-started/page.tsx             |  27 ++-
 apps/web/app/globals.css                      | 122 +++++++++++-
 apps/web/app/page.tsx                         | 181 +++++++-----------
 apps/web/app/product/page.tsx                 |   2 +-
 docs/assets/fixmap-cli-demo.svg               |   7 +-
 .../reports/declines-fabricated-identifier.md |   1 +
 examples/reports/declines-unmatched-terms.md  |   1 +
 examples/reports/declines-vague-task.md       |   1 +
 packages/action/dist/index.mjs                | 121 ++++++++++--
 packages/cli/src/agent-setup.ts               |  95 +++++++++
 packages/cli/src/cli-runner.ts                | 152 ++++++++++++++-
 packages/cli/test/cli-runner.test.ts          |  63 +++++-
 packages/core/src/exclude.ts                  |  14 +-
 packages/core/src/plan.ts                     |  54 ++++--
 packages/core/src/repo-scan.ts                |  76 +++++++-
 packages/core/src/types.ts                    |   3 +
 packages/core/test/exclude.test.ts            |  15 +-
 packages/core/test/repo-scan.test.ts          |  67 ++++++-
 27 files changed, 861 insertions(+), 214 deletions(-)
 create mode 100644 packages/cli/src/agent-setup.ts

diff --git a/README.md b/README.md
index a3a7668..a8c7897 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,14 @@ For a one-off trial:
 npx -y @aryam/fixmap@latest plan --issue https://github.com/chalk/chalk/issues/624
 ```
 
+Install a discoverable `/fixmap` command for Claude Code, Cursor, GitHub Copilot, and Agent Skills:
+
+```bash
+fixmap setup
+```
+
+Type `/fixmap` with no task to see the full feature menu, or run `fixmap features` in a terminal. Use `fixmap setup --agent <name>` to install one integration, and `--force` only after reviewing an existing customized command.
+
 FixMap fetches a public task, infers its repository, scans a temporary isolated checkout, and removes it when the report is complete. Local repository analysis never uploads source.
 
 ## Everyday workflow
@@ -61,6 +69,12 @@ Verify the completed diff against the saved plan:
 fixmap verify --report plan.json --diff main...HEAD
 ```
 
+Validate a saved report before another tool consumes it:
+
+```bash
+fixmap validate plan.json
+```
+
 Use `--working-tree` for staged and unstaged tracked edits, `--include-untracked` when new files should count as changes, `--exclude` or `.fixmapignore` to focus the map, and `--no-cache` to force a fresh scan. Run `fixmap --help` for the complete command reference.
 
 ## Complete feature catalog
@@ -71,7 +85,7 @@ Use `--working-tree` for staged and unstaged tracked edits, `--include-untracked
 - Normalizes supported browser and GitHub API issue URLs, including `www`, query strings, and fragments, while rejecting credentials, lookalike hosts, ports, and unsafe encoded paths.
 - Scans the current checkout, another local path, a `file://` URL, or an isolated checkout of a public GitHub repository.
 - Maps `--diff <spec>`, `--base`/`--head`, or the current `--working-tree`; untracked changes remain opt-in with `--include-untracked`.
-- Reuses repository scans only when the repository root, commit, status, and binary diff are identical. `cache-hit` reports reuse, `--no-cache` bypasses it, and `FIXMAP_CACHE_DIR` moves the OS cache.
+- Reuses repository scans only when the repository root, commit, status, and binary diff are identical. `cache-hit` reports reuse and scan age, entries expire after seven days, `--no-cache` reports a fresh bypass, and `FIXMAP_CACHE_DIR` moves the OS cache.
 - Detects npm, pnpm, Yarn, and Bun projects and reads the scripts declared by each workspace package.
 
 ### Plan and ranking
@@ -82,19 +96,21 @@ Use `--working-tree` for staged and unstaged tracked edits, `--include-untracked
 - Routes reachable test commands from real package scripts and pairs them with the nearest related test files.
 - Reports six bounded risk areas: authentication, billing, automation, data, public API, and dependencies.
 - Explains task grounding, ranking shape, unresolved or partially matched identifiers, exclusions, scan limits, unread content, skipped submodules, empty diffs, and Git failures.
-- Supports `--limit`, repeatable `--exclude`, and ordered `.fixmapignore` patterns with negation.
+- Supports `--limit`, repeatable `--exclude`, and ordered `.fixmapignore` patterns with negation. Root-leading patterns are repository-relative, pasted absolute paths inside the repository are normalized, and patterns that match nothing produce a warning.
 - Produces Markdown for people or versioned JSON for tools, writes to `--output`, and gives one grounded next action.
 
-### Explain, Compare, Verify, and Doctor
+### Explain, Compare, Verify, Validate, and Doctor
 
 - **Explain** tells you whether a path ranked, fell below the cutoff, was excluded, resolves through a submodule, or was never scanned—and uses the same task and diff evidence as Plan.
 - **Compare** shows files that entered, left, moved, or changed confidence after the task was refined, plus changes in task grounding.
 - **Verify** compares a saved JSON plan with a diff or working tree and flags generated edits, unmapped changes, an untouched leading file, source changes without tests, newly reached risk areas, and plan/repository mismatches.
+- **Validate** checks any saved JSON report with the structural compatibility validator shared by Compare, Verify, the Action, and MCP.
 - **Doctor** prints the running version and executable path and diagnoses project, global, PATH, and npm-exec version shadows.
 - `FIXMAP_PROGRESS` controls remote clone/scan progress, and `FIXMAP_VERBOSE_USAGE` restores full usage text after argument errors.
 
 ### Agent and automation interfaces
 
+- `fixmap setup` installs `/fixmap` discovery for Claude Code, Cursor, GitHub Copilot prompt files, and the open Agent Skills layout; the no-argument command lists every FixMap workflow before making changes.
 - The MCP server exposes `fixmap_plan`, `fixmap_explain`, `fixmap_compare`, `fixmap_verify`, and `fixmap_doctor` over local stdio and is published in the official MCP Registry.
 - The GitHub Action runs Plan or Verify on pull requests, writes a full job summary, and creates or updates one bounded FixMap comment instead of posting duplicates.
 - The Action accepts explicit task input or pull-request context, uses the same report validator as the CLI and MCP server, and fails clearly when a requested diff cannot be resolved.
diff --git a/apps/web/app/_components/interactive-map-stage.tsx b/apps/web/app/_components/interactive-map-stage.tsx
index 25740ff..def8bf8 100644
--- a/apps/web/app/_components/interactive-map-stage.tsx
+++ b/apps/web/app/_components/interactive-map-stage.tsx
@@ -143,7 +143,7 @@ export function InteractiveMapStage() {
   };
 
   return (
-    <div className="interactive-map-stage" aria-label="Interactive example of a FixMap report">
+    <div className="interactive-map-stage" role="group" aria-label="Interactive example of a FixMap report">
       <div className="stage-toolbar">
         <span className="stage-mini-brand"><ShieldCheck size={19} weight="duotone" aria-hidden /><b>FixMap</b></span>
         <label className="stage-example-select">
@@ -171,7 +171,7 @@ export function InteractiveMapStage() {
         </div>
 
         <div className="stage-output-column">
-          <div className="stage-progress" aria-label="Analysis progress">
+          <div className="stage-progress" role="group" aria-label="Analysis progress">
             {stageMeta.map((stage, index) => {
               const isReady = readyCount > index;
               return (
diff --git a/apps/web/app/_components/product-map.tsx b/apps/web/app/_components/product-map.tsx
index 28157ee..390cbaf 100644
--- a/apps/web/app/_components/product-map.tsx
+++ b/apps/web/app/_components/product-map.tsx
@@ -25,7 +25,7 @@ const outputs = [
 
 export function ProductMap({ compact = false }: { compact?: boolean }) {
   return (
-    <div className={compact ? "product-map compact" : "product-map"} aria-label="How FixMap turns a problem into a focused map">
+    <div className={compact ? "product-map compact" : "product-map"} role="group" aria-label="How FixMap turns a problem into a focused map">
       <div className="map-step map-input">
         <span className="step-number">1</span>
         <div>
@@ -45,7 +45,7 @@ export function ProductMap({ compact = false }: { compact?: boolean }) {
             <article key={title}>
               <Icon size={23} aria-hidden />
               <div>
-                <h3>{title}</h3>
+                <h2>{title}</h2>
                 {items.map((item, index) => <p key={item}><span>{index + 1}</span>{item}</p>)}
               </div>
             </article>
diff --git a/apps/web/app/_lib/site-data.ts b/apps/web/app/_lib/site-data.ts
index 4ec4766..a5cabec 100644
--- a/apps/web/app/_lib/site-data.ts
+++ b/apps/web/app/_lib/site-data.ts
@@ -95,5 +95,8 @@ export const commands = {
   localTask: "fixmap plan --issue \"password reset emails fail\"",
   diff: "fixmap plan --diff main...HEAD",
   verify: "fixmap verify --report plan.json --diff main...HEAD",
+  validate: "fixmap validate plan.json",
+  setup: "fixmap setup",
+  features: "fixmap features",
   mcp: "fixmap mcp"
 };
diff --git a/apps/web/app/changelog/page.tsx b/apps/web/app/changelog/page.tsx
index 9f6b126..08725db 100644
--- a/apps/web/app/changelog/page.tsx
+++ b/apps/web/app/changelog/page.tsx
@@ -242,7 +242,7 @@ export default function ChangelogPage() {
     <main>
       <section className="subpage-hero page-shell changelog-hero">
         <p className="eyebrow">Product changelog</p>
-        <h1>Every improvement.<br /><em>Plainly recorded.</em></h1>
+        <h1>Every improvement.{" "}<br /><em>Plainly recorded.</em></h1>
         <p>New features, important fixes, and the evidence behind each recent FixMap release.</p>
         <div className="changelog-hero-meta">
           <span><CheckCircle size={19} weight="fill" aria-hidden /> Current package: v{siteStats.version}</span>
diff --git a/apps/web/app/demo.tsx b/apps/web/app/demo.tsx
index 52ad303..ce81050 100644
--- a/apps/web/app/demo.tsx
+++ b/apps/web/app/demo.tsx
@@ -135,7 +135,7 @@ export function Demo() {
         <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">
+          <div className="preset-list" role="group" aria-label="Example tasks">
             {presets.map((preset) => (
               <button
                 key={preset.label}
@@ -160,7 +160,7 @@ export function Demo() {
           </p>
 
           <div className="privacy-note">
-            <span>●</span>
+            <span aria-hidden="true">●</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
@@ -234,7 +234,7 @@ function PlanPanel({ report }: { report: ReturnType<typeof buildReportFromRepo>
 
       {report.risks.length > 0 ? (
         <div className="panel-block">
-          <h4>Risk</h4>
+          <p className="panel-heading">Risk</p>
           {report.risks.map((risk) => (
             <p key={risk.area}>
               <span className={`severity ${risk.severity}`}>{risk.severity}</span>
@@ -246,7 +246,7 @@ function PlanPanel({ report }: { report: ReturnType<typeof buildReportFromRepo>
 
       {report.diagnostics.length > 0 ? (
         <div className="panel-block">
-          <h4>Diagnostics</h4>
+          <p className="panel-heading">Diagnostics</p>
           {report.diagnostics.map((diagnostic, index) => (
             <p key={`${diagnostic.code}-${diagnostic.paths?.[0] ?? index}`}>
               <span className={`severity ${diagnostic.severity}`}>{diagnostic.severity}</span>
@@ -297,7 +297,7 @@ function ExplainPanel({
 
       {explanation.reasons.length > 0 ? (
         <div className="panel-block">
-          <h4>Scored for</h4>
+          <p className="panel-heading">Scored for</p>
           {explanation.reasons.map((reason) => (
             <p key={reason}>{reason}</p>
           ))}
diff --git a/apps/web/app/demo/page.tsx b/apps/web/app/demo/page.tsx
index 3e7c539..1bf7913 100644
--- a/apps/web/app/demo/page.tsx
+++ b/apps/web/app/demo/page.tsx
@@ -61,17 +61,17 @@ export default function DemoPage() {
             <h3>Agent</h3>
             <p>I should get a focused map before searching blindly.</p>
             <p><strong>Calls <code>fixmap_plan</code>:</strong></p>
-            <pre><code>{`{
+            <pre tabIndex={0}><code>{`{
   "issue": "${agentTask}",
   "limit": 3
 }`}</code></pre>
 
             <h3>FixMap</h3>
-            <pre><code>{agentPlanOutput}</code></pre>
+            <pre tabIndex={0}><code>{agentPlanOutput}</code></pre>
 
             <h3>Agent edits carefully</h3>
             <p>The agent opens the leading files, confirms the evidence, and adds a bounded SMTP connection timeout:</p>
-            <pre><code>{`// Before
+            <pre tabIndex={0}><code>{`// Before
 const transport = createTransport({ host: config.smtpHost, port: config.smtpPort });
 
 // After
@@ -83,16 +83,16 @@ const transport = createTransport({
             <p>The configuration and related reset-email test are updated too.</p>
 
             <p><strong>Calls <code>fixmap_verify</code>:</strong></p>
-            <pre><code>{`{
+            <pre tabIndex={0}><code>{`{
   "report": { "...": "the previous FixMap JSON plan" },
   "diff": "main...HEAD"
 }`}</code></pre>
 
             <h3>FixMap</h3>
-            <pre><code>{agentVerificationOutput}</code></pre>
+            <pre tabIndex={0}><code>{agentVerificationOutput}</code></pre>
 
             <h3>Agent proves the fix</h3>
-            <pre><code>npm run test</code></pre>
+            <pre tabIndex={0}><code>npm run test</code></pre>
             <p>After the test passes, the agent reports the cause, the code change, and the validation result.</p>
           </article>
 
diff --git a/apps/web/app/docs/page.tsx b/apps/web/app/docs/page.tsx
index 98461c4..6a641c8 100644
--- a/apps/web/app/docs/page.tsx
+++ b/apps/web/app/docs/page.tsx
@@ -4,9 +4,9 @@ import {
   ArrowRight,
   BracketsCurly,
   CheckSquare,
+  Command,
   FileMagnifyingGlass,
   GithubLogo,
-  Robot,
   WarningCircle
 } from "@phosphor-icons/react/ssr";
 import { CopyCommand } from "../_components/copy-command";
@@ -14,7 +14,7 @@ import { commands, repoUrl } from "../_lib/site-data";
 
 export const metadata: Metadata = {
   title: "Documentation",
-  description: "FixMap documentation for planning, explaining, verifying, JSON output, MCP, and GitHub Actions.",
+  description: "FixMap documentation for slash-command discovery, planning, explaining, comparing, verifying, validating, MCP, and GitHub Actions.",
   alternates: { canonical: "/docs" },
   openGraph: {
     title: "FixMap documentation",
@@ -27,7 +27,7 @@ const docLinks = [
   { href: "#plan", icon: FileMagnifyingGlass, title: "Plan", body: "Map a task, issue, or diff." },
   { href: "#explain", icon: BracketsCurly, title: "Explain", body: "Ask why a path is missing." },
   { href: "#verify", icon: CheckSquare, title: "Verify", body: "Compare a plan with a diff." },
-  { href: "#mcp", icon: Robot, title: "MCP", body: "Expose the full loop to agents." }
+  { href: "#slash-command", icon: Command, title: "/fixmap", body: "Discover every workflow in an agent." }
 ];
 
 export default function DocsPage() {
@@ -35,7 +35,7 @@ export default function DocsPage() {
     <main>
       <section className="subpage-hero compact-hero page-shell docs-hero">
         <p className="eyebrow">Documentation</p>
-        <h1>Understand the map.<br /><em>Use it deliberately.</em></h1>
+        <h1>Understand the map.{" "}<br /><em>Use it deliberately.</em></h1>
         <p>Start with the everyday workflow, then go deeper into output formats, verification, automation, and trust boundaries.</p>
         <CopyCommand command={commands.publicIssue} />
       </section>
@@ -43,13 +43,15 @@ export default function DocsPage() {
       <section className="docs-layout page-shell">
         <aside className="docs-sidebar" aria-label="Documentation sections">
           <strong>On this page</strong>
-          <a href="#plan">Plan</a><a href="#explain">Explain</a><a href="#focus">Focus</a><a href="#verify">Verify</a><a href="#output">Output</a><a href="#mcp">MCP</a><a href="#doctor">Doctor</a><a href="#safety">Safety</a>
+          <a href="#slash-command">/fixmap</a><a href="#plan">Plan</a><a href="#explain">Explain</a><a href="#focus">Focus</a><a href="#verify">Verify</a><a href="#output">Output</a><a href="#validate">Validate</a><a href="#mcp">MCP</a><a href="#doctor">Doctor</a><a href="#safety">Safety</a>
         </aside>
         <div className="docs-content">
           <div className="docs-cards">
             {docLinks.map(({ href, icon: Icon, title, body }) => <a href={href} key={href}><Icon size={25} aria-hidden /><strong>{title}</strong><span>{body}</span><ArrowRight size={17} aria-hidden /></a>)}
           </div>
 
+          <section id="slash-command" className="doc-section"><p className="eyebrow">Slash command</p><h2>Open the complete FixMap menu.</h2><p><code>fixmap setup</code> installs project-level discovery for Claude Code, Cursor, GitHub Copilot, and Agent Skills. Invoking <code>/fixmap</code> with no task lists Plan, Explain, Compare, Verify, Validate, Doctor, MCP, focus controls, working-tree mapping, and fresh scans.</p><CopyCommand command={commands.setup} /><CopyCommand command={commands.features} /><p>The installer is idempotent and will not overwrite a customized command unless you explicitly pass <code>--force</code>.</p></section>
+
           <section id="plan" className="doc-section"><p className="eyebrow">Plan</p><h2>Find the right place to start.</h2><p>Give FixMap one task source: plain issue text, a task file, stdin, a public GitHub issue URL, or a git diff.</p><CopyCommand command={commands.localTask} /><h3>Public issue URL</h3><CopyCommand command={commands.publicIssue} /><h3>Working-tree or branch diff</h3><CopyCommand command={commands.diff} /><p>Remote repository mode is issue-only. Clone the repository locally when you need <code>--diff</code>, <code>--base</code>, or <code>--head</code>.</p></section>
 
           <section id="explain" className="doc-section"><p className="eyebrow">Explain</p><h2>Ask the missing-file question.</h2><p>Use <code>--explain</code> when you expected a path and it did not appear. The response distinguishes five different situations:</p><ul><li>The file ranked, just lower than expected.</li><li>It scored below the report cutoff.</li><li>It tied for a reported place but fell outside <code>--limit</code>.</li><li>It was excluded intentionally, such as a generated file whose source ranked instead.</li><li>The scanner never saw it, including a scan limit, a sparse checkout, or an unsupported extension.</li></ul><CopyCommand command={'fixmap plan --issue "reset links fail" --explain src/auth/token.ts'} /></section>
@@ -60,6 +62,8 @@ export default function DocsPage() {
 
           <section id="output" className="doc-section"><p className="eyebrow">Output</p><h2>Readable by people and tools.</h2><p>Markdown is the default handoff. Add <code>--format json</code> for structured output and <code>--output &lt;path&gt;</code> to save it.</p><p>New JSON plans include <code>reportVersion: 1</code>. Within a report version, fields may be added but existing fields will not be removed or change type; consumers should ignore unknown fields. A breaking output change requires a new report version. Compare and Verify still accept legacy plans without a marker, while rejecting marker values they do not understand.</p><div className="definition-list"><div><strong>Context files</strong><p>Ranked paths, scores, confidence labels, and evidence.</p></div><div><strong>Test routes</strong><p>Workspace-aware commands and reachable related tests.</p></div><div><strong>Risks</strong><p>Sensitive areas inferred from paths, symbols, and changes.</p></div><div><strong>Diagnostics</strong><p>Vague tasks, unresolved identifiers, scan limits, and other uncertainty.</p></div></div></section>
 
+          <section id="validate" className="doc-section"><p className="eyebrow">Validate</p><h2>Check a saved report directly.</h2><p>The CLI exposes the same additive structural validator used by Compare, Verify, the GitHub Action, and MCP. It accepts legacy unmarked reports, accepts version 1 with additive fields, and rejects unsupported report versions or malformed context entries.</p><CopyCommand command={commands.validate} /></section>
+
           <section id="mcp" className="doc-section"><p className="eyebrow">MCP</p><h2>Five tools for the agent workflow.</h2><p><code>fixmap_plan</code> maps tasks and working trees. <code>fixmap_explain</code> answers why a file is missing. <code>fixmap_compare</code> measures task refinement. <code>fixmap_verify</code> checks the later diff, and <code>fixmap_doctor</code> diagnoses install shadows. All five run locally over stdio.</p><CopyCommand command={commands.mcp} /><Link className="text-link" href="/get-started#mcp">MCP setup examples <ArrowRight size={17} weight="bold" aria-hidden /></Link></section>
 
           <section id="doctor" className="doc-section"><p className="eyebrow">Doctor</p><h2>Check what actually started.</h2><p><code>doctor</code> reports the running version, resolved path, conflicting global, and Node version. Version 0.8.4 and newer also checks an exact npm-requested version when that newer Doctor starts.</p><CopyCommand command="fixmap doctor" /><p>An older project-local binary can win before newer Doctor code runs, so always check the printed running version. Use the isolated-prefix/direct-shim procedure in the README when the exact version matters.</p></section>
diff --git a/apps/web/app/evidence/page.tsx b/apps/web/app/evidence/page.tsx
index d29d417..2e9234e 100644
--- a/apps/web/app/evidence/page.tsx
+++ b/apps/web/app/evidence/page.tsx
@@ -37,7 +37,7 @@ export default function EvidencePage() {
     <main>
       <section className="subpage-hero page-shell evidence-hero">
         <p className="eyebrow">Evidence</p>
-        <h1>Measured honestly.<br /><em>Misses included.</em></h1>
+        <h1>Measured honestly.{" "}<br /><em>Misses included.</em></h1>
         <p>
           Every benchmark case is a real issue later closed by a merged pull request. FixMap sees
           the repository before the fix and tries to surface the file that actually changed.
diff --git a/apps/web/app/get-started/page.tsx b/apps/web/app/get-started/page.tsx
index b230351..69ee6bd 100644
--- a/apps/web/app/get-started/page.tsx
+++ b/apps/web/app/get-started/page.tsx
@@ -1,16 +1,16 @@
 import type { Metadata } from "next";
 import Link from "next/link";
-import { ArrowRight, GithubLogo, Robot, TerminalWindow } from "@phosphor-icons/react/ssr";
+import { ArrowRight, Command, GithubLogo, Robot, TerminalWindow } from "@phosphor-icons/react/ssr";
 import { CopyCommand } from "../_components/copy-command";
 import { commands, marketplaceUrl, repoUrl, siteStats } from "../_lib/site-data";
 
 export const metadata: Metadata = {
   title: "Get started",
-  description: "Run FixMap from the CLI, connect it through MCP, or add it to pull requests with the GitHub Action.",
+  description: "Install the /fixmap command, run the CLI, connect MCP, or add FixMap to pull requests with the GitHub Action.",
   alternates: { canonical: "/get-started" },
   openGraph: {
     title: "Get started with FixMap",
-    description: "Install the CLI, connect MCP, or add the GitHub Action.",
+    description: "Install /fixmap, use the CLI, connect MCP, or add the GitHub Action.",
     url: "/get-started"
   }
 };
@@ -21,12 +21,23 @@ export default function GetStartedPage() {
       <section className="subpage-hero page-shell">
         <p className="eyebrow">Get started</p>
         <h1>Choose where the map <em>should appear.</em></h1>
-        <p>Install the CLI once and use a short command, let a compatible coding agent request the map, or publish it automatically on pull requests.</p>
-        <div className="jump-links"><a href="#cli">CLI</a><a href="#mcp">MCP</a><a href="#action">GitHub Action</a></div>
+        <p>Install the CLI once, add a discoverable slash command to a coding agent, connect the MCP tools, or publish a map automatically on pull requests.</p>
+        <div className="jump-links"><a href="#slash-command">/fixmap</a><a href="#cli">CLI</a><a href="#mcp">MCP</a><a href="#action">GitHub Action</a></div>
+      </section>
+
+      <section className="setup-section page-shell" id="slash-command">
+        <div className="setup-heading"><span>01</span><Command size={34} aria-hidden /><div><p className="eyebrow">Slash command</p><h2>Type /fixmap. See every workflow.</h2></div></div>
+        <div className="setup-content">
+          <p className="setup-lede">Install project-level discovery for Claude Code, Cursor, GitHub Copilot, and Agent Skills. Invoking <code>/fixmap</code> without a task opens the complete Plan, Explain, Compare, Verify, Validate, Doctor, MCP, focus, working-tree, and fresh-scan menu.</p>
+          <CopyCommand command={commands.setup} />
+          <p>The installer is idempotent and refuses to overwrite an existing customized command. Target one integration with <code>--agent claude</code>, <code>cursor</code>, <code>copilot</code>, or <code>agents</code>. Use <code>--force</code> only after reviewing the file.</p>
+          <h3>See the same menu in a terminal</h3>
+          <CopyCommand command={commands.features} />
+        </div>
       </section>
 
       <section className="setup-section page-shell" id="cli">
-        <div className="setup-heading"><span>01</span><TerminalWindow size={34} aria-hidden /><div><p className="eyebrow">CLI</p><h2>Install once. Keep the command short.</h2></div></div>
+        <div className="setup-heading"><span>02</span><TerminalWindow size={34} aria-hidden /><div><p className="eyebrow">CLI</p><h2>Install once. Keep the command short.</h2></div></div>
         <div className="setup-content">
           <p className="setup-lede">Install FixMap globally, then paste a public GitHub issue URL. FixMap fetches the task, infers the repository, scans a temporary checkout, and removes it when the report is done.</p>
           <CopyCommand command="npm install --global @aryam/fixmap@latest" />
@@ -71,7 +82,7 @@ npx fixmap plan --issue "password reset emails fail"`} />
       </section>
 
       <section className="setup-section page-shell" id="mcp">
-        <div className="setup-heading"><span>02</span><Robot size={34} aria-hidden /><div><p className="eyebrow">MCP</p><h2>Let the agent ask.</h2></div></div>
+        <div className="setup-heading"><span>03</span><Robot size={34} aria-hidden /><div><p className="eyebrow">MCP</p><h2>Let the agent ask.</h2></div></div>
         <div className="setup-content">
           <p className="setup-lede">FixMap exposes five local stdio tools: <code>fixmap_plan</code> before editing, <code>fixmap_explain</code> when a file is missing, <code>fixmap_compare</code> to measure a refined plan, <code>fixmap_verify</code> after the diff exists, and <code>fixmap_doctor</code> to diagnose install shadows.</p>
           <h3>Claude Code</h3>
@@ -90,7 +101,7 @@ npx fixmap plan --issue "password reset emails fail"`} />
       </section>
 
       <section className="setup-section page-shell" id="action">
-        <div className="setup-heading"><span>03</span><GithubLogo size={34} weight="fill" aria-hidden /><div><p className="eyebrow">GitHub Action</p><h2>Map every pull request.</h2></div></div>
+        <div className="setup-heading"><span>04</span><GithubLogo size={34} weight="fill" aria-hidden /><div><p className="eyebrow">GitHub Action</p><h2>Map every pull request.</h2></div></div>
         <div className="setup-content">
           <p className="setup-lede">The Action posts one report as a pull-request comment and writes the complete result to the job summary.</p>
           <pre className="code-block"><code>{`name: FixMap
diff --git a/apps/web/app/globals.css b/apps/web/app/globals.css
index 82fcafe..77b6cb3 100644
--- a/apps/web/app/globals.css
+++ b/apps/web/app/globals.css
@@ -17,9 +17,9 @@
   --focus-ring: #589774;
   --warning: #9b521b;
   --danger: #9f3444;
-  --page: 1360px;
-  --radius: 12px;
-  --shadow: 0 20px 55px rgba(10, 33, 59, 0.09);
+  --page: 1240px;
+  --radius: 8px;
+  --shadow: 0 14px 38px rgba(10, 33, 59, 0.08);
 }
 
 * { box-sizing: border-box; }
@@ -107,7 +107,7 @@ h3 { margin-bottom: 10px; font-size: 21px; line-height: 1.25; letter-spacing: -.
 .map-output-list { display: grid; gap: 12px; }
 .map-output-list article { padding: 16px 18px; display: grid; grid-template-columns: 28px 1fr; gap: 12px; border: 1px solid rgba(10,90,67,.48); border-radius: var(--radius); background: var(--paper-light); }
 .map-output-list article > svg { margin-top: 2px; color: var(--green); }
-.map-output-list h3 { margin: 0 0 8px; font-size: 15px; }
+.map-output-list h2 { margin: 0 0 8px; font-size: 15px; }
 .map-output-list p { margin: 3px 0; display: grid; grid-template-columns: 18px 1fr; gap: 6px; color: var(--ink-soft); font: 11.5px/1.45 var(--font-mono), monospace; }
 .map-output-list p span { color: var(--green); }
 .product-map:not(.compact) { max-width: 1120px; margin: auto; }
@@ -184,12 +184,13 @@ h3 { margin-bottom: 10px; font-size: 21px; line-height: 1.25; letter-spacing: -.
 /* Demo */
 .demo-page-section { padding-top: 30px; }
 .workbench { overflow: hidden; border: 1px solid var(--line-strong); border-radius: 16px; background: var(--paper-light); box-shadow: var(--shadow); }
-.stage-tabs { display: grid; grid-template-columns: repeat(3, 1fr); border-bottom: 1px solid var(--line); }
+.stage-tabs { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); border-bottom: 1px solid var(--line); }
 .stage-tab { min-height: 82px; padding: 16px 24px; display: grid; gap: 3px; text-align: left; border: 0; border-right: 1px solid var(--line); background: var(--paper); color: var(--ink-soft); cursor: pointer; }
 .stage-tab:last-child { border-right: 0; }
 .stage-tab.active { background: var(--navy); color: var(--on-dark); box-shadow: inset 0 4px 0 var(--mint); }
 .stage-tab b { font-size: 15px; }
-.stage-tab small { color: inherit; opacity: .72; }
+.stage-tab small { color: var(--ink); opacity: 1; }
+.stage-tab.active small { color: inherit; }
 .demo-shell { display: grid; grid-template-columns: .9fr 1.1fr; min-height: 650px; }
 .demo-input, .demo-results { padding: 38px; }
 .demo-input { border-right: 1px solid var(--line); background: var(--paper); }
@@ -219,10 +220,10 @@ h3 { margin-bottom: 10px; font-size: 21px; line-height: 1.25; letter-spacing: -.
 .severity.error { background: #f6dfe4; color: var(--danger); }
 .route-preview, .panel-block, .empty-result, .finding { margin-top: 20px; padding: 16px; border: 1px solid var(--line); border-radius: 8px; }
 .route-preview { display: grid; gap: 8px; }
-.route-preview span, .panel-block h4 { color: var(--ink-faint); font-size: 11px; text-transform: uppercase; letter-spacing: .12em; }
+.route-preview span, .panel-heading { color: var(--ink-faint); font-size: 11px; text-transform: uppercase; letter-spacing: .12em; }
 .route-preview code, .route-related code, .finding code { font: 12px var(--font-mono), monospace; overflow-wrap: anywhere; }
 .route-related { color: var(--ink-soft); font-size: 12px; }
-.panel-block h4 { margin: 0 0 10px; }
+.panel-heading { margin: 0 0 10px; }
 .panel-block p { margin: 9px 0; display: flex; align-items: flex-start; gap: 8px; color: var(--ink-soft); font-size: 13px; }
 .next-action, .panel-footnote { margin-top: 22px; color: var(--ink-faint); font-size: 12.5px; }
 .explain-summary { margin: 24px 0; font-size: 19px; line-height: 1.5; }
@@ -452,13 +453,21 @@ h3 { margin-bottom: 10px; font-size: 21px; line-height: 1.25; letter-spacing: -.
   .stage-row ul { grid-column: 1; }
   .principle-grid { grid-template-columns: 1fr; }
   .principle-grid article, .principle-grid article:nth-child(even) { min-height: 0; padding: 28px 0; border-right: 0; }
-  .stage-tabs { grid-template-columns: 1fr; }
-  .stage-tab { min-height: 62px; border-right: 0; border-bottom: 1px solid var(--line); }
+  .stage-tabs { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .stage-tab { min-height: 72px; padding: 13px 14px; border-bottom: 1px solid var(--line); }
+  .stage-tab:nth-child(even) { border-right: 0; }
+  .stage-tab:nth-child(n + 3) { border-bottom: 0; }
   .demo-input, .demo-results { padding: 24px 18px; }
   .result { grid-template-columns: 28px 1fr; }
   .confidence { grid-column: 2; justify-self: start; }
   .method-grid { grid-template-columns: 1fr; }
   .method-grid article, .method-grid article + article, .method-grid article:nth-child(3) { padding: 26px 0; border-right: 0; border-bottom: 1px solid var(--line); }
+  .results-table { min-width: 0; width: 100%; }
+  .results-row { min-height: 84px; padding-block: 12px; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 7px 12px; font-size: 11px; }
+  .results-row > :first-child { grid-column: 1 / -1; font-size: 12px; }
+  .results-row code { font-size: 10px; }
+  .results-row.results-head { min-height: 58px; font-size: 9px; letter-spacing: .04em; }
+  .results-row.results-head > :first-child { font-size: 9px; }
   .setup-heading { grid-template-columns: 42px 34px minmax(0, 1fr); }
   .setup-heading h2 { font-size: 34px; }
   .copy-command { align-items: stretch; flex-direction: column; }
@@ -704,6 +713,99 @@ h3 { margin-bottom: 10px; font-size: 21px; line-height: 1.25; letter-spacing: -.
   .stage-card-rows > span { opacity: 1; transform: none; animation: none; }
 }
 
+/* Professional product surface: compact, evidence-led, and deliberately low on decoration. */
+.site-header { border-bottom: 1px solid var(--line); background: color-mix(in srgb, var(--paper) 94%, transparent); }
+.site-header::after { display: none; }
+.header-inner { min-height: 72px; }
+.site-logo { width: 148px; }
+.desktop-nav { gap: 26px; font-size: 13px; }
+.button { min-height: 44px; padding-inline: 18px; border-radius: 6px; font-size: 14px; }
+.button:hover { transform: none; }
+.section { padding-block: 88px; }
+.subpage-hero { padding-block: 82px 76px; }
+.pro-home { overflow: hidden; }
+.pro-hero { padding-block: 88px 96px; display: grid; grid-template-columns: minmax(0, .9fr) minmax(560px, 1.1fr); align-items: center; gap: clamp(56px, 6vw, 96px); }
+.pro-hero-copy { min-width: 0; }
+.pro-hero-copy h1 { max-width: 680px; margin-bottom: 24px; font-size: clamp(54px, 5.4vw, 76px); line-height: .98; letter-spacing: -.06em; }
+.pro-hero-lede { max-width: 650px; margin-bottom: 30px; color: var(--ink-soft); font-size: 19px; line-height: 1.55; }
+.pro-hero-copy .copy-command { max-width: 610px; border-radius: 7px; box-shadow: none; }
+.pro-hero-copy .button-row { margin-top: 20px; }
+.pro-trust-line { margin-top: 28px; display: flex; flex-wrap: wrap; gap: 10px 22px; color: var(--ink-faint); font-size: 12px; }
+.pro-trust-line span { display: inline-flex; align-items: center; gap: 6px; }
+.pro-trust-line svg { color: var(--green); }
+.pro-hero .interactive-map-stage { width: 100%; border-radius: 10px; box-shadow: 0 18px 50px rgba(10, 33, 59, .08); }
+
+.pro-workflow, .pro-surfaces { padding-block: 96px; }
+.pro-workflow { display: grid; grid-template-columns: minmax(250px, .62fr) minmax(0, 1.38fr); gap: clamp(64px, 8vw, 120px); border-top: 1px solid var(--line); }
+.pro-section-heading { max-width: 520px; }
+.pro-section-heading h2 { font-size: clamp(38px, 4vw, 54px); }
+.pro-section-heading > p:last-child { color: var(--ink-soft); font-size: 17px; }
+.pro-workflow-list { border-top: 1px solid var(--line-strong); }
+.pro-workflow-list > a { min-height: 112px; padding: 23px 10px; display: grid; grid-template-columns: 42px 100px 1fr 24px; align-items: center; gap: 14px; border-bottom: 1px solid var(--line); text-decoration: none; transition: background .18s ease, padding .18s ease; }
+.pro-workflow-list > a:hover { padding-inline: 18px; background: var(--paper-light); }
+.pro-workflow-list > a > span { color: var(--green); font: 600 11px var(--font-mono), monospace; }
+.pro-workflow-list strong { font-size: 18px; }
+.pro-workflow-list p { margin: 0; color: var(--ink-soft); font-size: 14px; }
+.pro-workflow-list svg { color: var(--green); }
+
+.pro-proof { border-block: 1px solid var(--line); background: var(--navy); color: var(--on-dark); }
+.pro-proof-inner { padding-block: 92px; display: grid; grid-template-columns: minmax(0, 1.15fr) minmax(360px, .85fr); align-items: end; gap: clamp(70px, 9vw, 140px); }
+.pro-proof .eyebrow { color: var(--mint); }
+.pro-proof h2 { max-width: 680px; font-size: clamp(40px, 4.2vw, 58px); }
+.pro-proof p { max-width: 680px; color: #bdc7d0; font-size: 17px; }
+.pro-proof .text-link { margin-top: 14px; color: var(--mint); }
+.pro-proof-metrics { margin: 0; border-top: 1px solid rgba(255,255,255,.24); }
+.pro-proof-metrics div { min-height: 96px; display: grid; grid-template-columns: 1fr auto; align-items: center; gap: 24px; border-bottom: 1px solid rgba(255,255,255,.17); }
+.pro-proof-metrics dt { color: #bdc7d0; font-size: 13px; }
+.pro-proof-metrics dd { margin: 0; color: var(--mint); font: 620 34px/1 var(--font-mono), monospace; letter-spacing: -.05em; }
+
+.pro-surfaces { display: grid; grid-template-columns: .58fr 1.42fr; gap: clamp(60px, 8vw, 120px); }
+.pro-surface-grid { display: grid; grid-template-columns: repeat(2, 1fr); border-top: 1px solid var(--line-strong); }
+.pro-surface-grid > a { min-height: 255px; padding: 28px 28px 24px 0; display: flex; flex-direction: column; align-items: flex-start; border-bottom: 1px solid var(--line); border-right: 1px solid var(--line); text-decoration: none; }
+.pro-surface-grid > a:nth-child(even) { padding-left: 28px; border-right: 0; }
+.pro-surface-grid svg { color: var(--green); }
+.pro-surface-grid h3 { margin-top: 58px; font-size: 21px; }
+.pro-surface-grid p { min-height: 66px; color: var(--ink-soft); font-size: 14px; }
+.pro-surface-grid span { margin-top: auto; display: inline-flex; align-items: center; gap: 6px; color: var(--green-dark); font-size: 13px; font-weight: 620; }
+
+.pro-final { margin-bottom: 88px; padding: 30px 34px; display: flex; align-items: center; justify-content: space-between; gap: 36px; border: 1px solid var(--line); border-radius: 8px; background: var(--paper-light); }
+.pro-final > div:first-child { display: grid; grid-template-columns: 26px 1fr; align-items: center; gap: 1px 10px; }
+.pro-final > div:first-child svg { grid-row: 1 / 3; color: var(--green); }
+.pro-final strong { font-size: 17px; }
+.pro-final span { color: var(--ink-faint); font-size: 12px; }
+.pro-final .button-row { flex-wrap: nowrap; margin: 0; }
+
+@media (max-width: 1120px) {
+  .pro-hero { grid-template-columns: 1fr; }
+  .pro-hero-copy { max-width: 760px; }
+  .pro-hero .interactive-map-stage { max-width: 920px; }
+}
+
+@media (max-width: 820px) {
+  .pro-workflow, .pro-surfaces, .pro-proof-inner { grid-template-columns: 1fr; gap: 48px; }
+  .pro-proof-inner { align-items: start; }
+  .pro-proof-metrics { max-width: 620px; }
+}
+
+@media (max-width: 620px) {
+  .pro-hero { padding-block: 54px 70px; gap: 48px; }
+  .pro-hero-copy h1 { font-size: 50px; }
+  .pro-hero-lede { font-size: 17px; }
+  .pro-workflow, .pro-surfaces { padding-block: 72px; }
+  .pro-workflow-list > a { min-height: 128px; grid-template-columns: 34px 1fr 22px; gap: 8px 12px; }
+  .pro-workflow-list p { grid-column: 2 / -1; }
+  .pro-workflow-list > a > svg { grid-column: 3; grid-row: 1; }
+  .pro-proof-inner { padding-block: 72px; }
+  .pro-proof-metrics div { min-height: 82px; }
+  .pro-proof-metrics dd { font-size: 28px; }
+  .pro-surface-grid { grid-template-columns: 1fr; }
+  .pro-surface-grid > a, .pro-surface-grid > a:nth-child(even) { min-height: 215px; padding: 26px 0; border-right: 0; }
+  .pro-surface-grid h3 { margin-top: 34px; }
+  .pro-surface-grid p { min-height: 0; }
+  .pro-final { margin-bottom: 60px; padding: 26px 22px; align-items: stretch; flex-direction: column; }
+  .pro-final .button-row { align-items: stretch; flex-direction: column; }
+}
+
 :root[data-theme="light"] { color-scheme: light; }
 
 :root[data-theme="dark"] {
diff --git a/apps/web/app/page.tsx b/apps/web/app/page.tsx
index 652c87a..8d030b1 100644
--- a/apps/web/app/page.tsx
+++ b/apps/web/app/page.tsx
@@ -1,156 +1,113 @@
-import Image from "next/image";
 import Link from "next/link";
 import {
   ArrowRight,
   CheckCircle,
+  Command,
   GithubLogo,
   Laptop,
   LockKey,
-  MagnifyingGlass,
   Path,
   ShieldCheck
 } from "@phosphor-icons/react/ssr";
 import { CopyCommand } from "./_components/copy-command";
 import { InteractiveMapStage } from "./_components/interactive-map-stage";
-import { PixelSinkSurface } from "./_components/pixel-sink-surface";
 import { commands, repoUrl, siteStats } from "./_lib/site-data";
 
-const answers = [
-  {
-    number: "01",
-    title: "Files to inspect",
-    body: "FixMap ranks the source files most connected to the problem and tells you why each one surfaced.",
-    href: "/product#plan"
-  },
-  {
-    number: "02",
-    title: "Checks to run",
-    body: "It traces the nearest package commands and tests that can prove the change in your environment.",
-    href: "/product#tests"
-  },
-  {
-    number: "03",
-    title: "Risks to review",
-    body: "It calls out sensitive paths and uncertainty before a plausible edit becomes a surprising regression.",
-    href: "/product#risks"
-  }
+const workflow = [
+  { number: "01", name: "Plan", detail: "Rank the files, tests, and risks that matter before the first edit.", href: "/product#plan" },
+  { number: "02", name: "Explain", detail: "Ask why a file ranked, missed the cutoff, was excluded, or was never scanned.", href: "/product#explain" },
+  { number: "03", name: "Compare", detail: "Measure whether a clearer task produced a better context map.", href: "/product#compare" },
+  { number: "04", name: "Verify", detail: "Check the completed diff against the plan that guided the work.", href: "/product#verify" }
 ];
 
-const paths = [
-  { name: "CLI", detail: "Describe a task or point at a diff.", href: "/get-started#cli" },
-  { name: "MCP", detail: "Give coding agents Plan, Explain, Compare, Verify, and Doctor.", href: "/get-started#mcp" },
-  { name: "GitHub Action", detail: "Map every pull request automatically.", href: "/get-started#action" }
+const surfaces = [
+  { icon: Command, name: "Slash command", detail: "Install /fixmap in supported coding agents and open the complete workflow menu.", href: "/get-started#slash-command" },
+  { icon: Laptop, name: "CLI", detail: "Run locally in a terminal with no account or API key.", href: "/get-started#cli" },
+  { icon: ShieldCheck, name: "MCP", detail: "Expose Plan, Explain, Compare, Verify, and Doctor to an agent.", href: "/get-started#mcp" },
+  { icon: GithubLogo, name: "GitHub Action", detail: "Post the map or verify a saved plan on every pull request.", href: "/get-started#action" }
 ];
 
 export default function HomePage() {
   return (
-    <main className="premium-home">
-      <section className="premium-hero-surface pixel-sink-host">
-        <PixelSinkSurface />
-        <div className="premium-hero page-shell">
-          <div className="premium-hero-copy">
-            <p className="eyebrow">Open source · Local first · No API key</p>
-            <h1>Know where<br />to <em>start.</em></h1>
-            <p className="premium-hero-lede">
-              FixMap turns a software problem into a focused map of files, checks, and risks—so
-              you can investigate with confidence before you change anything.
-            </p>
-            <p className="preset-note"><strong>v{siteStats.version} workflow:</strong> Compare plans · focus with exclude/limit · map a working tree · verify the change · diagnose installs.</p>
-            <div className="button-row premium-hero-actions">
-              <Link className="button primary" href="/demo">Try FixMap <ArrowRight size={18} weight="bold" aria-hidden /></Link>
-              <Link className="button secondary" href="/product">See how it works <ArrowRight size={18} weight="bold" aria-hidden /></Link>
-            </div>
-            <div className="premium-trust-facts" aria-label="FixMap trust facts">
-              <span><LockKey size={23} aria-hidden /><b>Open source</b><small>MIT licensed</small></span>
-              <span><Laptop size={23} aria-hidden /><b>Runs locally</b><small>Your code stays with you</small></span>
-              <span><ShieldCheck size={23} aria-hidden /><b>No account</b><small>No signup. No tracking.</small></span>
-              <span><MagnifyingGlass size={23} aria-hidden /><b>No API key</b><small>Bring your own context</small></span>
-            </div>
-          </div>
-          <InteractiveMapStage />
-        </div>
-      </section>
-
-      <section className="premium-story pixel-sink-host">
-        <PixelSinkSurface />
-        <div className="premium-story-inner page-shell">
-          <div className="story-rail" aria-label="How FixMap works">
-            <span className="active"><i>1</i>Understand</span>
-            <span><i>2</i>Validate</span>
-            <span><i>3</i>Investigate</span>
-          </div>
-          <div className="story-title">
-            <p className="eyebrow">How the map forms</p>
-            <h2>From vague issue<br />to clear <em>first move.</em></h2>
+    <main className="pro-home">
+      <section className="pro-hero page-shell">
+        <div className="pro-hero-copy">
+          <p className="eyebrow">FixMap v{siteStats.version} · open source repo intelligence</p>
+          <h1>Start the change with evidence.</h1>
+          <p className="pro-hero-lede">
+            Give FixMap a task, issue, or diff. It returns the files to inspect, the checks to run,
+            and the risks to review—with every recommendation tied to repository evidence.
+          </p>
+          <CopyCommand command={commands.publicIssue} />
+          <div className="button-row">
+            <Link className="button primary" href="/get-started">Install FixMap <ArrowRight size={17} weight="bold" aria-hidden /></Link>
+            <Link className="button secondary" href="/demo">Open the live demo</Link>
           </div>
-          <div className="story-copy">
-            <p>FixMap reads how the repository connects, then surfaces the places that matter, the checks that can prove the change, and the risks worth keeping in mind.</p>
-            <a className="text-link" href="#answers">Scroll to see how it works <ArrowRight size={16} weight="bold" aria-hidden /></a>
+          <div className="pro-trust-line" role="group" aria-label="FixMap trust facts">
+            <span><LockKey size={16} aria-hidden /> Local-first</span>
+            <span><CheckCircle size={16} aria-hidden /> No API key</span>
+            <span><GithubLogo size={16} aria-hidden /> MIT licensed</span>
           </div>
-          <Image className="story-landscape" src="/fixmap-route-landscape.png" alt="A layered route arriving at a green destination marker" width={1536} height={1024} sizes="(max-width: 900px) 100vw, 48vw" loading="eager" unoptimized />
         </div>
+        <InteractiveMapStage />
       </section>
 
-      <section className="premium-answers page-shell" id="answers">
-        <div className="premium-section-intro">
-          <p className="eyebrow">One problem. Three useful answers.</p>
-          <h2>Less searching.<br />More knowing.</h2>
-          <p>Every result is evidence you can inspect—not a mysterious instruction to trust.</p>
+      <section className="pro-workflow page-shell">
+        <div className="pro-section-heading">
+          <p className="eyebrow">One workflow</p>
+          <h2>From task to verified diff.</h2>
+          <p>Four focused steps, each inspectable on its own.</p>
         </div>
-        <div className="premium-answer-list">
-          {answers.map((answer) => (
-            <Link key={answer.number} href={answer.href}>
-              <span>{answer.number}</span>
-              <div><h3>{answer.title}</h3><p>{answer.body}</p></div>
-              <ArrowRight size={24} weight="bold" aria-hidden />
+        <div className="pro-workflow-list">
+          {workflow.map((item) => (
+            <Link href={item.href} key={item.number}>
+              <span>{item.number}</span>
+              <strong>{item.name}</strong>
+              <p>{item.detail}</p>
+              <ArrowRight size={18} weight="bold" aria-hidden />
             </Link>
           ))}
         </div>
       </section>
 
-      <section className="premium-proof">
-        <div className="page-shell premium-proof-inner">
-          <div className="premium-proof-copy">
-            <p className="eyebrow">Measured, not asserted</p>
-            <h2>A useful starting map.<br /><em>Never false certainty.</em></h2>
-            <p>FixMap publishes the misses alongside the wins. It narrows the search, exposes uncertainty, and leaves the final judgment with you.</p>
-            <Link className="button light" href="/evidence">Read the evidence <ArrowRight size={18} weight="bold" aria-hidden /></Link>
-          </div>
-          <div className="premium-proof-metrics">
-            <div><strong>{siteStats.heldout.top3}/{siteStats.heldout.cases}</strong><span>held-out fixes surfaced in the top three</span></div>
-            <div><strong>{siteStats.medianSeconds}s</strong><span>median scan and rank</span></div>
-            <div><strong>{siteStats.adversarial.passed}/{siteStats.adversarial.cases}</strong><span>adversarial cases passed with {Math.round(siteStats.adversarial.falseConfidenceRate * 100)}% false confidence</span></div>
+      <section className="pro-proof">
+        <div className="page-shell pro-proof-inner">
+          <div>
+            <p className="eyebrow">Measured in public</p>
+            <h2>Useful without pretending to be certain.</h2>
+            <p>FixMap publishes the misses, the cohort boundaries, and the baseline comparison. A map narrows the search; it does not replace reading, tests, or review.</p>
+            <Link className="text-link" href="/evidence">Read the benchmark methodology <ArrowRight size={17} weight="bold" aria-hidden /></Link>
           </div>
+          <dl className="pro-proof-metrics">
+            <div><dt>Held-out Top 3</dt><dd>{siteStats.heldout.top3}/{siteStats.heldout.cases}</dd></div>
+            <div><dt>Adversarial gate</dt><dd>{siteStats.adversarial.passed}/{siteStats.adversarial.cases}</dd></div>
+            <div><dt>Median scan</dt><dd>{siteStats.medianSeconds}s</dd></div>
+          </dl>
         </div>
       </section>
 
-      <section className="premium-paths page-shell">
-        <div className="premium-section-intro compact">
-          <p className="eyebrow">Use it where work begins</p>
-          <h2>One map.<br />Three ways in.</h2>
+      <section className="pro-surfaces page-shell">
+        <div className="pro-section-heading">
+          <p className="eyebrow">Use it where work starts</p>
+          <h2>One engine. Four entry points.</h2>
         </div>
-        <div className="premium-path-grid">
-          {paths.map((path, index) => (
-            <Link href={path.href} key={path.name}>
-              <span>0{index + 1}</span><Path size={26} aria-hidden /><h3>{path.name}</h3><p>{path.detail}</p><ArrowRight size={20} weight="bold" aria-hidden />
+        <div className="pro-surface-grid">
+          {surfaces.map(({ icon: Icon, ...surface }) => (
+            <Link href={surface.href} key={surface.name}>
+              <Icon size={21} aria-hidden />
+              <h3>{surface.name}</h3>
+              <p>{surface.detail}</p>
+              <span>Set up <ArrowRight size={15} weight="bold" aria-hidden /></span>
             </Link>
           ))}
         </div>
       </section>
 
-      <section className="premium-final page-shell">
-        <div>
-          <p className="eyebrow">Thirty-second start</p>
-          <h2>Give the next change<br />a clear place to begin.</h2>
-          <p>Install once. Then use one short command. No account or API key.</p>
-        </div>
-        <div className="premium-final-action">
-          <CopyCommand command={commands.publicIssue} />
-          <div className="button-row">
-            <Link className="button primary" href="/get-started">Get started <ArrowRight size={18} weight="bold" aria-hidden /></Link>
-            <a className="text-link" href={repoUrl}><GithubLogo size={18} weight="fill" aria-hidden /> View on GitHub</a>
-          </div>
-          <span><CheckCircle size={18} weight="fill" aria-hidden /> FixMap v{siteStats.version}</span>
+      <section className="pro-final page-shell">
+        <div><Path size={22} aria-hidden /><strong>Ready to map a real task?</strong><span>No signup, cloud upload, or API key.</span></div>
+        <div className="button-row">
+          <Link className="button primary" href="/get-started">Get started <ArrowRight size={17} weight="bold" aria-hidden /></Link>
+          <a className="text-link" href={repoUrl}><GithubLogo size={17} weight="fill" aria-hidden /> View source</a>
         </div>
       </section>
     </main>
diff --git a/apps/web/app/product/page.tsx b/apps/web/app/product/page.tsx
index bc78397..477ca43 100644
--- a/apps/web/app/product/page.tsx
+++ b/apps/web/app/product/page.tsx
@@ -68,7 +68,7 @@ export default function ProductPage() {
     <main>
       <section className="subpage-hero page-shell">
         <p className="eyebrow">The product</p>
-        <h1>One problem.<br /><em>Three useful answers.</em></h1>
+        <h1>One problem.{" "}<br /><em>Three useful answers.</em></h1>
         <p>
           FixMap narrows the first step, explains its reasoning, and checks the work that followed.
           It is a map you can inspect—not a promise that the map is always right.
diff --git a/docs/assets/fixmap-cli-demo.svg b/docs/assets/fixmap-cli-demo.svg
index f67a6e9..f35cd31 100644
--- a/docs/assets/fixmap-cli-demo.svg
+++ b/docs/assets/fixmap-cli-demo.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="860" height="830" viewBox="0 0 860 830" role="img" aria-label="Animated terminal recording: one fixmap plan command produces ranked context files, a test route, an authentication risk note, and empty-state diagnostics.">
+<svg xmlns="http://www.w3.org/2000/svg" width="860" height="851" viewBox="0 0 860 851" role="img" aria-label="Animated terminal recording: one fixmap plan command produces ranked context files, a test route, an authentication risk note, and empty-state diagnostics.">
   <style>
     text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace; font-size: 13.5px; white-space: pre; }
     .l { opacity: 0; animation: fadein 0.45s ease-out forwards; }
@@ -7,7 +7,7 @@
     @keyframes blink { 0%, 100% { opacity: 1; } 50% { opacity: 0; } }
     @media (prefers-reduced-motion: reduce) { .l { animation: none; opacity: 1; } .cursor { animation: none; opacity: 0; } }
   </style>
-  <rect width="860" height="830" rx="10" fill="#0d1117" stroke="#30363d"/>
+  <rect width="860" height="851" rx="10" fill="#0d1117" stroke="#30363d"/>
   <rect width="860" height="44" rx="10" fill="#161b22"/>
   <rect y="32" width="860" height="12" fill="#161b22"/>
   <circle cx="24" cy="22" r="6" fill="#ff5f57"/>
@@ -37,5 +37,6 @@
   <text class="l" style="animation-delay:11.20s" x="22" y="709" fill="#e6edf3"><tspan>- Ranking shape: **separated**</tspan></text>
   <text class="l" style="animation-delay:11.45s" x="22" y="730" fill="#e6edf3"><tspan>- Next action: Inspect src/auth/reset-password.ts and its routed tests before editing.</tspan></text>
   <text class="l" style="animation-delay:12.60s" x="22" y="772" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">## Diagnostics</tspan></text>
-  <text class="l" style="animation-delay:12.85s" x="22" y="814" fill="#8b949e"><tspan>- None found</tspan></text>
+  <text class="l" style="animation-delay:12.85s" x="22" y="814" fill="#e6edf3"><tspan>- **info** Repository scan caching was bypassed by --no-cache; this report used a fresh</tspan></text>
+  <text class="l" style="animation-delay:13.10s" x="22" y="835" fill="#e6edf3"><tspan>    scan.</tspan></text>
 </svg>
diff --git a/examples/reports/declines-fabricated-identifier.md b/examples/reports/declines-fabricated-identifier.md
index 9f582bc..5cc91df 100644
--- a/examples/reports/declines-fabricated-identifier.md
+++ b/examples/reports/declines-fabricated-identifier.md
@@ -35,5 +35,6 @@ FixMap found 0 context files and generated 0 test routes.
 
 ## Diagnostics
 
+- **info** Repository scan caching was bypassed by --no-cache; this report used a fresh scan.
 - **warning** Identifiers not found exactly in the scanned repository: resolveTenantScopedSessionBinding, SessionBindingMismatch. Component words from unresolved identifiers were ignored, and unsupported recommendations were capped at low confidence.
 - **warning** No context files: no file in the 3 scanned matched the task terms bind, close, mismatch, resolve, rotation, scop, session, tenant (+1 more). The repository may not contain this behavior, or it may name it differently.
diff --git a/examples/reports/declines-unmatched-terms.md b/examples/reports/declines-unmatched-terms.md
index e27fd3c..7f27bd6 100644
--- a/examples/reports/declines-unmatched-terms.md
+++ b/examples/reports/declines-unmatched-terms.md
@@ -35,4 +35,5 @@ FixMap found 0 context files and generated 0 test routes.
 
 ## Diagnostics
 
+- **info** Repository scan caching was bypassed by --no-cache; this report used a fresh scan.
 - **warning** No context files: no file in the 3 scanned matched the task terms backpressure, drop, dur, ingestion, pipeline, span, telemetry. The repository may not contain this behavior, or it may name it differently.
diff --git a/examples/reports/declines-vague-task.md b/examples/reports/declines-vague-task.md
index 84488df..74b2792 100644
--- a/examples/reports/declines-vague-task.md
+++ b/examples/reports/declines-vague-task.md
@@ -35,4 +35,5 @@ FixMap found 0 context files and generated 0 test routes.
 
 ## Diagnostics
 
+- **info** Repository scan caching was bypassed by --no-cache; this report used a fresh scan.
 - **warning** 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.
diff --git a/packages/action/dist/index.mjs b/packages/action/dist/index.mjs
index 4c0f8a4..4715af6 100644
--- a/packages/action/dist/index.mjs
+++ b/packages/action/dist/index.mjs
@@ -6,14 +6,15 @@ import { appendFileSync, readFileSync } from "node:fs";
 
 // packages/core/dist/plan.js
 import { readFile as readFile2 } from "node:fs/promises";
-import { join as join2 } from "node:path";
+import { join as join2, resolve as resolve2 } from "node:path";
 
 // packages/core/dist/exclude.js
 var COMMENT = /^\s*#/;
 var NO_EXCLUSIONS = {
   excludes: () => false,
   reasonFor: () => void 0,
-  patterns: []
+  patterns: [],
+  matchedPatterns: /* @__PURE__ */ new Set()
 };
 function buildPathExcluder(patterns) {
   const cleaned = [...new Set(patterns.map((pattern) => normalizeSeparators(pattern.trim())).filter((pattern) => pattern.length > 0 && !COMMENT.test(pattern)))];
@@ -26,14 +27,17 @@ function buildPathExcluder(patterns) {
     return { pattern, negated, test: compile(body) };
   });
   const cache = /* @__PURE__ */ new Map();
+  const matchedPatterns = /* @__PURE__ */ new Set();
   const reasonFor = (path) => {
     if (cache.has(path)) {
       return cache.get(path);
     }
     let hit;
     for (const matcher of matchers) {
-      if (matcher.test(path))
+      if (matcher.test(path)) {
+        matchedPatterns.add(matcher.pattern);
         hit = matcher.negated ? void 0 : matcher.pattern;
+      }
     }
     cache.set(path, hit);
     return hit;
@@ -41,7 +45,8 @@ function buildPathExcluder(patterns) {
   return {
     excludes: (path) => reasonFor(path) !== void 0,
     reasonFor,
-    patterns: cleaned
+    patterns: cleaned,
+    matchedPatterns
   };
 }
 function parseIgnoreFile(contents) {
@@ -1936,7 +1941,9 @@ var MAX_DIFF_TEXT_CHARS = 2e5;
 var MAX_SCANNED_FILES = 25e3;
 var GIT_MAX_BUFFER = 10 * 1024 * 1024;
 var exec = promisify(execFile);
-var SCAN_CACHE_VERSION = 1;
+var SCAN_CACHE_VERSION = 2;
+var SCAN_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+var SCAN_CACHE_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json$/;
 async function scanRepo(input) {
   const repoRoot = resolve(input.repoRoot);
   if (!await isDirectory(repoRoot)) {
@@ -1955,7 +1962,21 @@ async function scanRepo(input) {
     };
   }
   const diagnostics = [];
-  const cacheLocation = input.useCache ? await buildScanCacheLocation(repoRoot) : void 0;
+  const cacheDecision = input.useCache === true ? await buildScanCacheLocation(repoRoot) : void 0;
+  const cacheLocation = cacheDecision?.location;
+  if (input.useCache === false) {
+    diagnostics.push({
+      code: "cache-bypass",
+      severity: "info",
+      message: "Repository scan caching was bypassed by --no-cache; this report used a fresh scan."
+    });
+  } else if (input.useCache === true && cacheDecision?.skipReason) {
+    diagnostics.push({
+      code: "cache-skip",
+      severity: "info",
+      message: cacheDecision.skipReason
+    });
+  }
   const cached = cacheLocation ? await readScanCache(cacheLocation) : void 0;
   let files;
   let trackedFiles;
@@ -1969,7 +1990,7 @@ async function scanRepo(input) {
     diagnostics.push(...cached.diagnostics, {
       code: "cache-hit",
       severity: "info",
-      message: `Reused the repository scan for the exact current git state (${files.length.toLocaleString()} files). Pass --no-cache to rescan.`
+      message: `Reused the repository scan for the exact current git state (${files.length.toLocaleString()} files, ${describeCacheAge(cached.createdAt)}). Pass --no-cache to rescan.`
     });
   } else {
     files = await listFiles(repoRoot, diagnostics);
@@ -1980,6 +2001,7 @@ async function scanRepo(input) {
       await writeScanCache(cacheLocation, {
         version: SCAN_CACHE_VERSION,
         stateKey: cacheLocation.stateKey,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
         files,
         trackedFiles,
         packageScripts,
@@ -2010,8 +2032,11 @@ async function buildScanCacheLocation(root) {
         maxBuffer: GIT_MAX_BUFFER
       })
     ]);
-    if (status.split("\0").some((entry) => entry.startsWith("?? ")))
-      return void 0;
+    if (status.split("\0").some((entry) => entry.startsWith("?? "))) {
+      return {
+        skipReason: "Repository scan caching was skipped because untracked files are scanner inputs and can change without a stable git diff."
+      };
+    }
     const dirtyDiff = status.length > 0 ? (await exec("git", ["diff", "--binary", "--no-ext-diff", "HEAD", "--", "."], {
       cwd: root,
       maxBuffer: GIT_MAX_BUFFER
@@ -2024,18 +2049,20 @@ async function buildScanCacheLocation(root) {
       dirtyDiff
     ].join("\0"));
     const cacheRoot = process.env.FIXMAP_CACHE_DIR ?? join(process.env.LOCALAPPDATA ?? process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "fixmap", "scans");
-    return {
+    return { location: {
       path: join(cacheRoot, `${hashText(resolve(root))}-${stateKey}.json`),
       stateKey
-    };
+    } };
   } catch {
-    return void 0;
+    return {
+      skipReason: "Repository scan caching was skipped because this directory has no exact git state to key safely."
+    };
   }
 }
 async function readScanCache(location) {
   try {
     const cached = JSON.parse(await readFile(location.path, "utf8"));
-    if (cached.version !== SCAN_CACHE_VERSION || cached.stateKey !== location.stateKey || !Array.isArray(cached.files) || !Array.isArray(cached.trackedFiles) || !Array.isArray(cached.packageScripts) || !Array.isArray(cached.diagnostics) || !["npm", "pnpm", "yarn", "bun"].includes(cached.packageManager ?? ""))
+    if (cached.version !== SCAN_CACHE_VERSION || cached.stateKey !== location.stateKey || typeof cached.createdAt !== "string" || !Number.isFinite(Date.parse(cached.createdAt)) || Date.now() - Date.parse(cached.createdAt) > SCAN_CACHE_MAX_AGE_MS || !Array.isArray(cached.files) || !Array.isArray(cached.trackedFiles) || !Array.isArray(cached.packageScripts) || !Array.isArray(cached.diagnostics) || !["npm", "pnpm", "yarn", "bun"].includes(cached.packageManager ?? ""))
       return void 0;
     return cached;
   } catch {
@@ -2045,6 +2072,7 @@ async function readScanCache(location) {
 async function writeScanCache(location, cached) {
   try {
     await mkdir(dirname(location.path), { recursive: true });
+    await pruneExpiredScanCache(dirname(location.path));
     await writeFile(location.path, `${JSON.stringify(cached)}
 `, { encoding: "utf8", flag: "wx" });
   } catch (error) {
@@ -2063,6 +2091,36 @@ async function writeScanCache(location, cached) {
     }
   }
 }
+async function pruneExpiredScanCache(cacheRoot) {
+  try {
+    const entries = await readdir(cacheRoot, { withFileTypes: true });
+    const now = Date.now();
+    await Promise.all(entries.filter((entry) => entry.isFile() && SCAN_CACHE_FILE.test(entry.name)).map(async (entry) => {
+      const path = join(cacheRoot, entry.name);
+      try {
+        const metadata = await stat(path);
+        if (now - metadata.mtimeMs > SCAN_CACHE_MAX_AGE_MS)
+          await unlink(path);
+      } catch {
+      }
+    }));
+  } catch {
+  }
+}
+function describeCacheAge(createdAt) {
+  const ageMs = Math.max(0, Date.now() - Date.parse(createdAt));
+  if (ageMs < 5e3)
+    return "scanned just now";
+  const minutes = Math.floor(ageMs / 6e4);
+  if (minutes < 1)
+    return "scanned less than a minute ago";
+  if (minutes < 60)
+    return `scanned ${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24)
+    return `scanned ${hours}h ago`;
+  return `scanned ${Math.floor(hours / 24)}d ago`;
+}
 function hashText(value) {
   return createHash("sha256").update(value).digest("hex").slice(0, 24);
 }
@@ -2534,20 +2592,41 @@ async function buildFixMapReport(input) {
   });
   if (exclude.patterns.length > 0) {
     const excludedPaths = repo.files.filter((file) => exclude.excludes(file.path)).map((file) => file.path);
-    if (excludedPaths.length === 0)
-      return report;
-    report.diagnostics.push({
-      code: "paths-excluded",
-      severity: report.contextFiles.length === 0 ? "warning" : "info",
-      message: `${exclude.patterns.length} exclusion ${exclude.patterns.length === 1 ? "pattern" : "patterns"} removed ${excludedPaths.length} ${excludedPaths.length === 1 ? "path" : "paths"} from ranking: ${exclude.patterns.join(", ")}. Run --explain on a file you expected to see if this is why it is absent.`
-    });
+    const unmatchedPatterns = exclude.patterns.filter((pattern) => !pattern.startsWith("!") && !exclude.matchedPatterns.has(pattern));
+    if (unmatchedPatterns.length > 0) {
+      const sample = unmatchedPatterns.slice(0, 5).join(", ");
+      report.diagnostics.push({
+        code: "exclusion-no-match",
+        severity: "warning",
+        message: `${unmatchedPatterns.length} exclusion ${unmatchedPatterns.length === 1 ? "pattern matched" : "patterns matched"} no scanned paths: ${sample}${unmatchedPatterns.length > 5 ? ", ..." : ""}. Check that patterns are repository-relative or run --explain on an expected file.`
+      });
+    }
+    if (excludedPaths.length > 0) {
+      report.diagnostics.push({
+        code: "paths-excluded",
+        severity: report.contextFiles.length === 0 ? "warning" : "info",
+        message: `${exclude.patterns.length} exclusion ${exclude.patterns.length === 1 ? "pattern" : "patterns"} removed ${excludedPaths.length} ${excludedPaths.length === 1 ? "path" : "paths"} from ranking: ${exclude.patterns.join(", ")}. Run --explain on a file you expected to see if this is why it is absent.`
+      });
+    }
   }
   return report;
 }
 async function resolveExclusions(repoRoot, patterns) {
-  const combined = [...await readIgnoreFile(repoRoot), ...patterns];
+  const combined = [...await readIgnoreFile(repoRoot), ...patterns].map((pattern) => normalizeAbsolutePattern(repoRoot, pattern));
   return combined.length > 0 ? buildPathExcluder(combined) : NO_EXCLUSIONS;
 }
+function normalizeAbsolutePattern(repoRoot, pattern) {
+  const trimmed = pattern.trim();
+  const negated = trimmed.startsWith("!");
+  const body = (negated ? trimmed.slice(1) : trimmed).replace(/\\/g, "/");
+  const normalizedRoot = resolve2(repoRoot).replace(/\\/g, "/").replace(/\/$/, "");
+  const caseInsensitive = /^[A-Za-z]:\//.test(normalizedRoot);
+  const comparableBody = caseInsensitive ? body.toLowerCase() : body;
+  const comparableRoot = caseInsensitive ? normalizedRoot.toLowerCase() : normalizedRoot;
+  if (!comparableBody.startsWith(`${comparableRoot}/`))
+    return pattern;
+  return `${negated ? "!" : ""}/${body.slice(normalizedRoot.length + 1)}`;
+}
 async function readIgnoreFile(repoRoot) {
   try {
     return parseIgnoreFile(await readFile2(join2(repoRoot, ".fixmapignore"), "utf8"));
diff --git a/packages/cli/src/agent-setup.ts b/packages/cli/src/agent-setup.ts
new file mode 100644
index 0000000..09fd1dd
--- /dev/null
+++ b/packages/cli/src/agent-setup.ts
@@ -0,0 +1,95 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+
+export type AgentTarget = "claude" | "cursor" | "copilot" | "agents";
+
+export const FIXMAP_FEATURES = [
+  { name: "Plan", command: "fixmap plan", detail: "Rank context files, test routes, risks, changed files, and uncertainty from a task, issue URL, diff, or working tree." },
+  { name: "Explain", command: "fixmap plan --explain <path>", detail: "Show whether a path ranked, tied below the limit, was excluded, or was never scanned." },
+  { name: "Compare", command: "fixmap plan --compare <report.json>", detail: "Compare a refined task and current plan with an earlier JSON report." },
+  { name: "Verify", command: "fixmap verify --report <report.json>", detail: "Compare the completed diff or working tree with the saved plan." },
+  { name: "Validate", command: "fixmap validate <report.json>", detail: "Check a saved report against FixMap's structural compatibility contract." },
+  { name: "Doctor", command: "fixmap doctor", detail: "Diagnose stale local, global, PATH, and npx install shadows." },
+  { name: "MCP", command: "fixmap mcp", detail: "Expose Plan, Explain, Compare, Verify, and Doctor over local stdio." },
+  { name: "Focus", command: "--limit, --exclude, .fixmapignore", detail: "Narrow ranking without changing the repository." },
+  { name: "Live changes", command: "--working-tree --include-untracked", detail: "Map staged, unstaged, and optionally untracked work against HEAD." },
+  { name: "Fresh scan", command: "--no-cache", detail: "Bypass the exact git-state scan cache and report that a fresh scan was used." }
+] as const;
+
+export function renderFeatureCatalog(format: "markdown" | "json" = "markdown"): string {
+  if (format === "json") return `${JSON.stringify({ features: FIXMAP_FEATURES }, null, 2)}\n`;
+  return [
+    "# FixMap features",
+    "",
+    ...FIXMAP_FEATURES.flatMap((feature) => [
+      `- **${feature.name}** — \`${feature.command}\``,
+      `  ${feature.detail}`
+    ]),
+    "",
+    "Run `fixmap setup` to install `/fixmap` discovery for supported coding agents.",
+    ""
+  ].join("\n");
+}
+
+const SHARED_INSTRUCTIONS = `You are the FixMap workflow assistant for this repository.
+
+When this command is invoked without a task, run \`fixmap features\` and present every feature in a compact menu. Do not edit files. Ask which workflow the user wants.
+
+When the invocation includes a task, issue URL, diff, file path, or workflow name:
+
+1. Run \`fixmap features\` if the requested capability is ambiguous.
+2. Use the matching local command: Plan, Explain, Compare, Verify, Validate, Doctor, or MCP.
+3. Preserve the user's repository and never imply that FixMap ran tests or proved correctness; it produces a starting map and verification findings.
+4. Report the exact command used and summarize files, checks, risks, and diagnostics.
+
+Prefer \`fixmap plan --issue "$ARGUMENTS" --repo .\` for task text. Use a canonical public GitHub issue URL directly when one is provided.`;
+
+const templates: Record<AgentTarget, { path: string; contents: string }> = {
+  claude: {
+    path: ".claude/skills/fixmap/SKILL.md",
+    contents: `---\nname: fixmap\ndescription: Discover and run every FixMap repository-mapping workflow\ndisable-model-invocation: true\nargument-hint: [task, issue URL, file, diff, or workflow]\n---\n\n${SHARED_INSTRUCTIONS}\n`
+  },
+  cursor: {
+    path: ".cursor/commands/fixmap.md",
+    contents: `---\ndescription: List or run every FixMap repository-mapping workflow\n---\n\n${SHARED_INSTRUCTIONS}\n`
+  },
+  copilot: {
+    path: ".github/prompts/fixmap.prompt.md",
+    contents: `---\nagent: 'agent'\ndescription: 'List or run every FixMap repository-mapping workflow'\n---\n\n${SHARED_INSTRUCTIONS}\n`
+  },
+  agents: {
+    path: ".agents/skills/fixmap/SKILL.md",
+    contents: `---\nname: fixmap\ndescription: Discover and run every FixMap repository-mapping workflow\n---\n\n${SHARED_INSTRUCTIONS}\n`
+  }
+};
+
+export async function installAgentCommands(input: {
+  repoRoot: string;
+  targets: AgentTarget[];
+  force?: boolean;
+}): Promise<Array<{ path: string; status: "created" | "unchanged" | "updated" }>> {
+  const root = resolve(input.repoRoot);
+  try {
+    if (!(await stat(root)).isDirectory()) throw new Error("not a directory");
+  } catch {
+    throw new Error(`Setup repository "${root}" does not exist or is not a directory.`);
+  }
+  const results: Array<{ path: string; status: "created" | "unchanged" | "updated" }> = [];
+  for (const target of input.targets) {
+    const template = templates[target];
+    const path = join(root, template.path);
+    let existing: string | undefined;
+    try { existing = await readFile(path, "utf8"); } catch { /* A missing file is expected. */ }
+    if (existing === template.contents) {
+      results.push({ path: relative(root, path).replace(/\\/g, "/"), status: "unchanged" });
+      continue;
+    }
+    if (existing !== undefined && !input.force) {
+      throw new Error(`Refusing to overwrite existing ${relative(root, path)}. Re-run with --force after reviewing it.`);
+    }
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, template.contents, "utf8");
+    results.push({ path: relative(root, path).replace(/\\/g, "/"), status: existing === undefined ? "created" : "updated" });
+  }
+  return results;
+}
diff --git a/packages/cli/src/cli-runner.ts b/packages/cli/src/cli-runner.ts
index 02a347d..114a9c9 100644
--- a/packages/cli/src/cli-runner.ts
+++ b/packages/cli/src/cli-runner.ts
@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
@@ -17,6 +18,7 @@ import {
   type FixMapReport
 } from "@aryam/fixmap-core";
 import { runDoctorChecks, renderDoctorReport, type DoctorReport } from "./doctor.js";
+import { installAgentCommands, renderFeatureCatalog, type AgentTarget } from "./agent-setup.js";
 import {
   buildReportForRepository,
   parseGitHubIssueSource,
@@ -71,18 +73,25 @@ Usage:
   fixmap plan --issue "Fix login" --repo https://github.com/owner/repository
   fixmap plan --diff main...HEAD
   fixmap plan --working-tree --include-untracked --limit 12 --exclude "docs/**"
+  fixmap plan --no-cache --issue "Fix login" --repo .
   fixmap plan --issue "Fix login" --format json --output plan.json
   fixmap plan --issue "Fix login in auth middleware" --compare plan.json
   fixmap plan --base main --head HEAD --format json
   fixmap verify --report plan.json --diff main...HEAD
   fixmap verify --report plan.json --working-tree
   fixmap doctor --format json
+  fixmap validate plan.json
+  fixmap features
+  fixmap setup [--agent claude|cursor|copilot|agents|all] [--repo <path>]
   fixmap mcp
 
 Commands:
   plan                Generate a FixMap report for a task or diff
   verify              Compare a saved report against the diff that followed it
   doctor              Check the FixMap install for stale global or npx shadows
+  validate            Validate a saved FixMap JSON report
+  features            List every FixMap capability and its command
+  setup               Install a discoverable /fixmap command for coding agents
   mcp                 Run FixMap as an MCP server over stdio for AI coding agents
 
 Options:
@@ -106,12 +115,15 @@ Options:
   --version, -v       Show the FixMap version
 
 A repository may also list exclusion patterns in .fixmapignore, one per line. Supported
-syntax is *, **, ?, root-leading /, directory-trailing /, comments, and ! negation.
+syntax is *, **, ?, repository-root-leading /, directory-trailing /, comments, and ! negation.
+Absolute paths pasted from inside the repository are normalized to repository-relative patterns.
 Set FIXMAP_PROGRESS=1 to print scan and clone phases to stderr.
 `;
 
 const DOCTOR_USAGE = `Usage: fixmap doctor [--format markdown|json]\n\nChecks the running FixMap binary, PATH/global shadows, and known install blind spots.\n`;
 const MCP_USAGE = `Usage: fixmap mcp\n\nRuns the FixMap MCP server over stdio. Configure your MCP client to execute \"fixmap mcp\".\n`;
+const SETUP_USAGE = `Usage: fixmap setup [--agent claude|cursor|copilot|agents|all] [--repo <path>] [--force]\n\nInstalls a /fixmap command that lists and runs FixMap workflows.\n`;
+const VALIDATE_USAGE = `Usage: fixmap validate <report.json> [--format markdown|json]\n\nChecks a saved report against FixMap's structural compatibility contract.\n`;
 
 export async function runCli(args: string[], dependencies: CliDependencies = {}): Promise<number> {
   const stdout = dependencies.stdout ?? ((text: string) => process.stdout.write(text));
@@ -142,6 +154,122 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     return 0;
   }
 
+  if (args[0] === "features") {
+    const featureArgs = args.slice(1);
+    let format: "markdown" | "json" = "markdown";
+    if (featureArgs.length > 0) {
+      const value = featureArgs.length === 2 && featureArgs[0] === "--format"
+        ? featureArgs[1]
+        : featureArgs.length === 1
+          ? featureArgs[0]?.match(/^--format=(.+)$/)?.[1]
+          : undefined;
+      const normalized = value?.trim().toLowerCase();
+      if (normalized !== "markdown" && normalized !== "json") {
+        stderr('features accepts only --format markdown or --format json.\n');
+        return 1;
+      }
+      format = normalized;
+    }
+    stdout(renderFeatureCatalog(format));
+    return 0;
+  }
+
+  if (args[0] === "setup") {
+    if (args[1] === "--help" || args[1] === "-h") { stdout(SETUP_USAGE); return 0; }
+    let repoRoot = process.cwd();
+    let targets: AgentTarget[] = ["claude", "cursor", "copilot", "agents"];
+    let force = false;
+    for (let index = 1; index < args.length; index += 1) {
+      const arg = args[index];
+      if (arg === "--force") { force = true; continue; }
+      if (arg?.startsWith("--repo=")) {
+        const value = arg.slice("--repo=".length).trim();
+        if (!value) { stderr(`--repo requires a directory.\n\n${SETUP_USAGE}`); return 1; }
+        repoRoot = expandHomePath(value);
+        continue;
+      }
+      if (arg === "--repo") {
+        const value = args[index + 1];
+        if (!value?.trim() || value.startsWith("--")) { stderr(`--repo requires a directory.\n\n${SETUP_USAGE}`); return 1; }
+        repoRoot = expandHomePath(value.trim());
+        index += 1;
+        continue;
+      }
+      if (arg?.startsWith("--agent=")) {
+        const value = arg.slice("--agent=".length).trim().toLowerCase();
+        if (!["claude", "cursor", "copilot", "agents", "all"].includes(value)) {
+          stderr(`--agent must be claude, cursor, copilot, agents, or all.\n\n${SETUP_USAGE}`);
+          return 1;
+        }
+        targets = value === "all" ? ["claude", "cursor", "copilot", "agents"] : [value as AgentTarget];
+        continue;
+      }
+      if (arg === "--agent") {
+        const value = args[index + 1]?.trim().toLowerCase();
+        if (!value || !["claude", "cursor", "copilot", "agents", "all"].includes(value)) {
+          stderr(`--agent must be claude, cursor, copilot, agents, or all.\n\n${SETUP_USAGE}`);
+          return 1;
+        }
+        targets = value === "all" ? ["claude", "cursor", "copilot", "agents"] : [value as AgentTarget];
+        index += 1;
+        continue;
+      }
+      stderr(`Unknown setup option: ${arg}\n\n${SETUP_USAGE}`);
+      return 1;
+    }
+    try {
+      const installed = await installAgentCommands({ repoRoot, targets, force });
+      stdout(`${installed.map((entry) => `${entry.status}: ${entry.path}`).join("\n")}\n\nType /fixmap in a supported agent to open the full FixMap feature menu.\n`);
+      return 0;
+    } catch (error) {
+      stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+      return 1;
+    }
+  }
+
+  if (args[0] === "validate") {
+    if (args[1] === "--help" || args[1] === "-h") { stdout(VALIDATE_USAGE); return 0; }
+    let reportPath: string | undefined;
+    let format: "markdown" | "json" = "markdown";
+    for (let index = 1; index < args.length; index += 1) {
+      const arg = args[index]!;
+      if (arg === "--format") {
+        const value = args[index + 1]?.trim().toLowerCase();
+        if (value !== "markdown" && value !== "json") { stderr(`--format must be markdown or json.\n\n${VALIDATE_USAGE}`); return 1; }
+        format = value;
+        index += 1;
+      } else if (arg.startsWith("--format=")) {
+        const value = arg.slice("--format=".length).trim().toLowerCase();
+        if (value !== "markdown" && value !== "json") { stderr(`--format must be markdown or json.\n\n${VALIDATE_USAGE}`); return 1; }
+        format = value;
+      } else if (arg.startsWith("-") || reportPath) {
+        stderr(`Unknown validate argument: ${arg}\n\n${VALIDATE_USAGE}`);
+        return 1;
+      } else {
+        reportPath = expandHomePath(arg);
+      }
+    }
+    if (!reportPath) { stderr(`validate requires a report path.\n\n${VALIDATE_USAGE}`); return 1; }
+    try {
+      const parsed = JSON.parse(readFileSync(reportPath, "utf8")) as unknown;
+      const result = validateFixMapReport(parsed, `"${reportPath}"`);
+      if (!result.success) { stderr(`${result.message}\n`); return 1; }
+      const payload = {
+        valid: true,
+        path: reportPath,
+        reportVersion: result.report.reportVersion ?? "legacy",
+        contextFiles: result.report.contextFiles.length
+      };
+      stdout(format === "json"
+        ? `${JSON.stringify(payload, null, 2)}\n`
+        : `Valid FixMap report: ${reportPath} (${payload.contextFiles} context files, reportVersion ${payload.reportVersion}).\n`);
+      return 0;
+    } catch (error) {
+      stderr(`Could not validate "${reportPath}": ${error instanceof Error ? error.message : String(error)}\n`);
+      return 1;
+    }
+  }
+
   if (args[0] === "doctor") {
     if (args[1] === "--help" || args[1] === "-h") { stdout(DOCTOR_USAGE); return 0; }
     const doctorArgs = args.slice(1);
@@ -149,7 +277,7 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     if (doctorArgs.length > 0) {
       const match = doctorArgs.length === 2 && doctorArgs[0] === "--format" ? doctorArgs[1] :
         doctorArgs.length === 1 ? doctorArgs[0]?.match(/^--format=(.+)$/)?.[1] : undefined;
-      const normalized = match?.toLowerCase();
+      const normalized = match?.trim().toLowerCase();
       if (normalized === "markdown" || normalized === "json") doctorFormat = normalized;
       else { stderr(`Unknown doctor option(s): ${doctorArgs.join(", ")}\n\n${DOCTOR_USAGE}`); return 1; }
     }
@@ -606,7 +734,7 @@ export function parseArgs(args: string[]): CliOptions {
       else invalidValues.push('--issue requires non-empty text or a GitHub issue URL');
     } else if (arg === "--issue-file") {
       consumeValue();
-      if (value?.trim()) issueFile = value.trim();
+      if (value?.trim()) issueFile = expandHomePath(value.trim());
       else invalidValues.push("--issue-file requires a UTF-8 file path or - for stdin");
     } else if (arg === "--diff") {
       consumeValue();
@@ -622,11 +750,11 @@ export function parseArgs(args: string[]): CliOptions {
       else invalidValues.push("--head requires a non-empty git ref");
     } else if (arg === "--repo") {
       consumeValue();
-      if (value?.trim()) repo = value;
+      if (value?.trim()) repo = expandHomePath(value.trim());
       else invalidValues.push("--repo requires a local path or public GitHub repository URL");
     } else if (arg === "--format") {
       consumeValue();
-      const normalized = value?.toLowerCase();
+      const normalized = value?.trim().toLowerCase();
       if (normalized === "markdown" || normalized === "json") {
         format = normalized;
       } else {
@@ -634,7 +762,7 @@ export function parseArgs(args: string[]): CliOptions {
       }
     } else if (arg === "--report") {
       consumeValue();
-      if (value?.trim()) reportPath = value.trim();
+      if (value?.trim()) reportPath = expandHomePath(value.trim());
       else invalidValues.push("--report requires a path to a FixMap JSON report");
     } else if (arg === "--explain") {
       consumeValue();
@@ -642,7 +770,7 @@ export function parseArgs(args: string[]): CliOptions {
       else invalidValues.push("--explain requires a repository-relative file path");
     } else if (arg === "--compare") {
       consumeValue();
-      if (value?.trim()) comparePath = value.trim();
+      if (value?.trim()) comparePath = expandHomePath(value.trim());
       else invalidValues.push("--compare requires a path to an earlier FixMap JSON report");
     } else if (arg === "--exclude") {
       consumeValue();
@@ -672,7 +800,7 @@ export function parseArgs(args: string[]): CliOptions {
       noCache = true;
     } else if (arg === "--output") {
       consumeValue();
-      if (value?.trim()) output = value;
+      if (value?.trim()) output = expandHomePath(value.trim());
       else invalidValues.push("--output requires a non-empty file path");
     } else {
       unknownArgs.push(rawArg);
@@ -702,6 +830,14 @@ export function parseArgs(args: string[]): CliOptions {
   };
 }
 
+function expandHomePath(value: string): string {
+  if (value === "~") return homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return join(homedir(), value.slice(2));
+  }
+  return value;
+}
+
 function loadIssueText(
   options: CliOptions,
   read: (path: string | number) => string | Buffer
diff --git a/packages/cli/test/cli-runner.test.ts b/packages/cli/test/cli-runner.test.ts
index c79d0e5..91f8830 100644
--- a/packages/cli/test/cli-runner.test.ts
+++ b/packages/cli/test/cli-runner.test.ts
@@ -1,5 +1,5 @@
-import { mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it, vi } from "vitest";
 import { parseArgs, runCli } from "../src/cli-runner.js";
@@ -83,6 +83,51 @@ describe("CLI argument handling", () => {
     expect(io.stderr).toEqual([]);
   });
 
+  it("lists the complete feature catalog for slash-command discovery", async () => {
+    const io = capture();
+
+    expect(await runCli(["features"], io.dependencies)).toBe(0);
+    for (const feature of ["Plan", "Explain", "Compare", "Verify", "Validate", "Doctor", "MCP", "Focus", "Live changes", "Fresh scan"]) {
+      expect(io.stdout.join("")).toContain(`**${feature}**`);
+    }
+    expect(io.stdout.join("")).toContain("fixmap setup");
+  });
+
+  it("installs an idempotent /fixmap command for a selected agent", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-"));
+    const first = capture();
+    const second = capture();
+
+    expect(await runCli(["setup", "--repo", root, "--agent", "cursor"], first.dependencies)).toBe(0);
+    const installed = await readFile(join(root, ".cursor", "commands", "fixmap.md"), "utf8");
+    expect(installed).toContain("fixmap features");
+    expect(first.stdout.join("")).toContain("created: .cursor/commands/fixmap.md");
+
+    expect(await runCli(["setup", "--repo", root, "--agent", "cursor"], second.dependencies)).toBe(0);
+    expect(second.stdout.join("")).toContain("unchanged: .cursor/commands/fixmap.md");
+  });
+
+  it("accepts equals syntax for setup and rejects a missing repository value", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-equals-"));
+    const installed = capture();
+    const invalid = capture();
+
+    expect(await runCli(["setup", `--repo=${root}`, "--agent=claude"], installed.dependencies)).toBe(0);
+    expect(await readFile(join(root, ".claude", "skills", "fixmap", "SKILL.md"), "utf8")).toContain("fixmap features");
+    expect(await runCli(["setup", "--repo", "--agent", "cursor"], invalid.dependencies)).toBe(1);
+    expect(invalid.stderr.join("")).toContain("--repo requires a directory");
+  });
+
+  it("validates a saved report without requiring custom JavaScript", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-validate-"));
+    const path = join(root, "report.json");
+    await writeFile(path, JSON.stringify(report));
+    const io = capture();
+
+    expect(await runCli(["validate", path, "--format", "json"], io.dependencies)).toBe(0);
+    expect(JSON.parse(io.stdout.join(""))).toMatchObject({ valid: true, path, contextFiles: 1 });
+  });
+
   it("does not let a nested version flag short-circuit the requested command", async () => {
     const io = capture();
     const exitCode = await runCli(["plan", "--version"], io.dependencies);
@@ -110,6 +155,20 @@ describe("CLI argument handling", () => {
     expect(parsed.unknownArgs).toEqual([]);
   });
 
+  it("trims accidental whitespace around a format value", () => {
+    expect(parseArgs(["plan", "--issue", "x", "--format", " JSON\n"]).format).toBe("json");
+  });
+
+  it("expands the home directory consistently for path options", () => {
+    const parsed = parseArgs([
+      "plan", "--issue", "x", "--repo", "~", "--output", "~/plan.json", "--compare", "~\\before.json"
+    ]);
+
+    expect(parsed.repo).toBe(homedir());
+    expect(parsed.output).toBe(join(homedir(), "plan.json"));
+    expect(parsed.comparePath).toBe(join(homedir(), "before.json"));
+  });
+
   it.each([
     ["plan", "--issue", "reset fails"],
     ["plan", "--issue=reset fails"]
diff --git a/packages/core/src/exclude.ts b/packages/core/src/exclude.ts
index a232521..b5a2832 100644
--- a/packages/core/src/exclude.ts
+++ b/packages/core/src/exclude.ts
@@ -20,12 +20,15 @@ export type PathExcluder = {
   /** The pattern that matched, for `--explain` to quote back. */
   reasonFor: (path: string) => string | undefined;
   patterns: string[];
+  /** Patterns that matched at least one path inspected by this excluder. */
+  matchedPatterns: ReadonlySet<string>;
 };
 
 export const NO_EXCLUSIONS: PathExcluder = {
   excludes: () => false,
   reasonFor: () => undefined,
-  patterns: []
+  patterns: [],
+  matchedPatterns: new Set<string>()
 };
 
 /**
@@ -49,6 +52,7 @@ export function buildPathExcluder(patterns: string[]): PathExcluder {
     return { pattern, negated, test: compile(body) };
   });
   const cache = new Map<string, string | undefined>();
+  const matchedPatterns = new Set<string>();
 
   const reasonFor = (path: string): string | undefined => {
     if (cache.has(path)) {
@@ -56,7 +60,10 @@ export function buildPathExcluder(patterns: string[]): PathExcluder {
     }
     let hit: string | undefined;
     for (const matcher of matchers) {
-      if (matcher.test(path)) hit = matcher.negated ? undefined : matcher.pattern;
+      if (matcher.test(path)) {
+        matchedPatterns.add(matcher.pattern);
+        hit = matcher.negated ? undefined : matcher.pattern;
+      }
     }
     cache.set(path, hit);
     return hit;
@@ -65,7 +72,8 @@ export function buildPathExcluder(patterns: string[]): PathExcluder {
   return {
     excludes: (path: string) => reasonFor(path) !== undefined,
     reasonFor,
-    patterns: cleaned
+    patterns: cleaned,
+    matchedPatterns
   };
 }
 
diff --git a/packages/core/src/plan.ts b/packages/core/src/plan.ts
index 15fe245..f990958 100644
--- a/packages/core/src/plan.ts
+++ b/packages/core/src/plan.ts
@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { buildPathExcluder, parseIgnoreFile, NO_EXCLUSIONS } from "./exclude.js";
 import type { PathExcluder } from "./exclude.js";
 import { buildReportFromRepo } from "./report.js";
@@ -23,15 +23,29 @@ export async function buildFixMapReport(
 
   if (exclude.patterns.length > 0) {
     const excludedPaths = repo.files.filter((file) => exclude.excludes(file.path)).map((file) => file.path);
-    if (excludedPaths.length === 0) return report;
-    report.diagnostics.push({
-      code: "paths-excluded",
-      severity: report.contextFiles.length === 0 ? "warning" : "info",
-      message:
-        `${exclude.patterns.length} exclusion ${exclude.patterns.length === 1 ? "pattern" : "patterns"} ` +
-        `removed ${excludedPaths.length} ${excludedPaths.length === 1 ? "path" : "paths"} from ranking: ${exclude.patterns.join(", ")}. ` +
-        "Run --explain on a file you expected to see if this is why it is absent."
-    });
+    const unmatchedPatterns = exclude.patterns.filter((pattern) =>
+      !pattern.startsWith("!") && !exclude.matchedPatterns.has(pattern)
+    );
+    if (unmatchedPatterns.length > 0) {
+      const sample = unmatchedPatterns.slice(0, 5).join(", ");
+      report.diagnostics.push({
+        code: "exclusion-no-match",
+        severity: "warning",
+        message:
+          `${unmatchedPatterns.length} exclusion ${unmatchedPatterns.length === 1 ? "pattern matched" : "patterns matched"} no scanned paths: ${sample}` +
+          `${unmatchedPatterns.length > 5 ? ", ..." : ""}. Check that patterns are repository-relative or run --explain on an expected file.`
+      });
+    }
+    if (excludedPaths.length > 0) {
+      report.diagnostics.push({
+        code: "paths-excluded",
+        severity: report.contextFiles.length === 0 ? "warning" : "info",
+        message:
+          `${exclude.patterns.length} exclusion ${exclude.patterns.length === 1 ? "pattern" : "patterns"} ` +
+          `removed ${excludedPaths.length} ${excludedPaths.length === 1 ? "path" : "paths"} from ranking: ${exclude.patterns.join(", ")}. ` +
+          "Run --explain on a file you expected to see if this is why it is absent."
+      });
+    }
   }
 
   return report;
@@ -43,10 +57,28 @@ export async function buildFixMapReport(
  * refinement of that, not a replacement for it.
  */
 export async function resolveExclusions(repoRoot: string, patterns: string[]): Promise<PathExcluder> {
-  const combined = [...await readIgnoreFile(repoRoot), ...patterns];
+  const combined = [...await readIgnoreFile(repoRoot), ...patterns]
+    .map((pattern) => normalizeAbsolutePattern(repoRoot, pattern));
   return combined.length > 0 ? buildPathExcluder(combined) : NO_EXCLUSIONS;
 }
 
+/**
+ * A leading slash normally anchors a pattern to the repository root. If a user instead
+ * pastes the repository's full absolute path, strip that known prefix so the intent remains
+ * portable inside the scan. Paths outside the repository keep their normal anchored meaning.
+ */
+function normalizeAbsolutePattern(repoRoot: string, pattern: string): string {
+  const trimmed = pattern.trim();
+  const negated = trimmed.startsWith("!");
+  const body = (negated ? trimmed.slice(1) : trimmed).replace(/\\/g, "/");
+  const normalizedRoot = resolve(repoRoot).replace(/\\/g, "/").replace(/\/$/, "");
+  const caseInsensitive = /^[A-Za-z]:\//.test(normalizedRoot);
+  const comparableBody = caseInsensitive ? body.toLowerCase() : body;
+  const comparableRoot = caseInsensitive ? normalizedRoot.toLowerCase() : normalizedRoot;
+  if (!comparableBody.startsWith(`${comparableRoot}/`)) return pattern;
+  return `${negated ? "!" : ""}/${body.slice(normalizedRoot.length + 1)}`;
+}
+
 async function readIgnoreFile(repoRoot: string): Promise<string[]> {
   try {
     return parseIgnoreFile(await readFile(join(repoRoot, ".fixmapignore"), "utf8"));
diff --git a/packages/core/src/repo-scan.ts b/packages/core/src/repo-scan.ts
index 0197c28..8c6a609 100644
--- a/packages/core/src/repo-scan.ts
+++ b/packages/core/src/repo-scan.ts
@@ -55,11 +55,14 @@ const MAX_SCANNED_FILES = 25_000;
 const GIT_MAX_BUFFER = 10 * 1024 * 1024;
 const exec = promisify(execFile);
 type ScanState = { count: number; limitReported: boolean };
-const SCAN_CACHE_VERSION = 1;
+const SCAN_CACHE_VERSION = 2;
+const SCAN_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const SCAN_CACHE_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json$/;
 
 type CachedScan = {
   version: typeof SCAN_CACHE_VERSION;
   stateKey: string;
+  createdAt: string;
   files: RepoFile[];
   trackedFiles: string[];
   packageScripts: PackageScript[];
@@ -91,7 +94,21 @@ export async function scanRepo(
   }
 
   const diagnostics: RepoMap["diagnostics"] = [];
-  const cacheLocation = input.useCache ? await buildScanCacheLocation(repoRoot) : undefined;
+  const cacheDecision = input.useCache === true ? await buildScanCacheLocation(repoRoot) : undefined;
+  const cacheLocation = cacheDecision?.location;
+  if (input.useCache === false) {
+    diagnostics.push({
+      code: "cache-bypass",
+      severity: "info",
+      message: "Repository scan caching was bypassed by --no-cache; this report used a fresh scan."
+    });
+  } else if (input.useCache === true && cacheDecision?.skipReason) {
+    diagnostics.push({
+      code: "cache-skip",
+      severity: "info",
+      message: cacheDecision.skipReason
+    });
+  }
   const cached = cacheLocation ? await readScanCache(cacheLocation) : undefined;
   let files: RepoFile[];
   let trackedFiles: string[];
@@ -105,7 +122,7 @@ export async function scanRepo(
     diagnostics.push(...cached.diagnostics, {
       code: "cache-hit",
       severity: "info",
-      message: `Reused the repository scan for the exact current git state (${files.length.toLocaleString()} files). Pass --no-cache to rescan.`
+      message: `Reused the repository scan for the exact current git state (${files.length.toLocaleString()} files, ${describeCacheAge(cached.createdAt)}). Pass --no-cache to rescan.`
     });
   } else {
     files = await listFiles(repoRoot, diagnostics);
@@ -116,6 +133,7 @@ export async function scanRepo(
       await writeScanCache(cacheLocation, {
         version: SCAN_CACHE_VERSION,
         stateKey: cacheLocation.stateKey,
+        createdAt: new Date().toISOString(),
         files,
         trackedFiles,
         packageScripts,
@@ -142,8 +160,9 @@ export async function scanRepo(
 }
 
 type ScanCacheLocation = { path: string; stateKey: string };
+type ScanCacheDecision = { location?: ScanCacheLocation; skipReason?: string };
 
-async function buildScanCacheLocation(root: string): Promise<ScanCacheLocation | undefined> {
+async function buildScanCacheLocation(root: string): Promise<ScanCacheDecision> {
   try {
     const [{ stdout: head }, { stdout: status }] = await Promise.all([
       exec("git", ["rev-parse", "HEAD"], { cwd: root, maxBuffer: GIT_MAX_BUFFER }),
@@ -154,7 +173,11 @@ async function buildScanCacheLocation(root: string): Promise<ScanCacheLocation |
     ]);
     // Untracked files are scanner inputs but are absent from `git diff`. Do not cache that
     // state rather than keying it on names alone and serving stale contents after an edit.
-    if (status.split("\0").some((entry) => entry.startsWith("?? "))) return undefined;
+    if (status.split("\0").some((entry) => entry.startsWith("?? "))) {
+      return {
+        skipReason: "Repository scan caching was skipped because untracked files are scanner inputs and can change without a stable git diff."
+      };
+    }
     const dirtyDiff = status.length > 0
       ? (await exec("git", ["diff", "--binary", "--no-ext-diff", "HEAD", "--", "."], {
           cwd: root,
@@ -173,13 +196,15 @@ async function buildScanCacheLocation(root: string): Promise<ScanCacheLocation |
       "fixmap",
       "scans"
     );
-    return {
+    return { location: {
       path: join(cacheRoot, `${hashText(resolve(root))}-${stateKey}.json`),
       stateKey
-    };
+    } };
   } catch {
     // Non-git directories deliberately do not cache: they have no cheap exact invalidation key.
-    return undefined;
+    return {
+      skipReason: "Repository scan caching was skipped because this directory has no exact git state to key safely."
+    };
   }
 }
 
@@ -189,6 +214,9 @@ async function readScanCache(location: ScanCacheLocation): Promise<CachedScan |
     if (
       cached.version !== SCAN_CACHE_VERSION ||
       cached.stateKey !== location.stateKey ||
+      typeof cached.createdAt !== "string" ||
+      !Number.isFinite(Date.parse(cached.createdAt)) ||
+      Date.now() - Date.parse(cached.createdAt) > SCAN_CACHE_MAX_AGE_MS ||
       !Array.isArray(cached.files) ||
       !Array.isArray(cached.trackedFiles) ||
       !Array.isArray(cached.packageScripts) ||
@@ -204,6 +232,7 @@ async function readScanCache(location: ScanCacheLocation): Promise<CachedScan |
 async function writeScanCache(location: ScanCacheLocation, cached: CachedScan): Promise<void> {
   try {
     await mkdir(dirname(location.path), { recursive: true });
+    await pruneExpiredScanCache(dirname(location.path));
     await writeFile(location.path, `${JSON.stringify(cached)}\n`, { encoding: "utf8", flag: "wx" });
   } catch (error) {
     const code = (error as { code?: unknown }).code;
@@ -224,6 +253,37 @@ async function writeScanCache(location: ScanCacheLocation, cached: CachedScan):
   }
 }
 
+async function pruneExpiredScanCache(cacheRoot: string): Promise<void> {
+  try {
+    const entries = await readdir(cacheRoot, { withFileTypes: true });
+    const now = Date.now();
+    await Promise.all(entries
+      .filter((entry) => entry.isFile() && SCAN_CACHE_FILE.test(entry.name))
+      .map(async (entry) => {
+        const path = join(cacheRoot, entry.name);
+        try {
+          const metadata = await stat(path);
+          if (now - metadata.mtimeMs > SCAN_CACHE_MAX_AGE_MS) await unlink(path);
+        } catch {
+          // Cache cleanup is best effort and must never block a report.
+        }
+      }));
+  } catch {
+    // A read-only or concurrently removed cache directory is harmless.
+  }
+}
+
+function describeCacheAge(createdAt: string): string {
+  const ageMs = Math.max(0, Date.now() - Date.parse(createdAt));
+  if (ageMs < 5_000) return "scanned just now";
+  const minutes = Math.floor(ageMs / 60_000);
+  if (minutes < 1) return "scanned less than a minute ago";
+  if (minutes < 60) return `scanned ${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `scanned ${hours}h ago`;
+  return `scanned ${Math.floor(hours / 24)}d ago`;
+}
+
 function hashText(value: string): string {
   return createHash("sha256").update(value).digest("hex").slice(0, 24);
 }
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
index 206e8c7..e384963 100644
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -61,9 +61,12 @@ export type ScanDiagnostic = {
     | "content-unread"
     | "generated-paths-dominant"
     | "paths-excluded"
+    | "exclusion-no-match"
     | "working-tree-diff"
     | "diff-resolved"
     | "cache-hit"
+    | "cache-bypass"
+    | "cache-skip"
     | "task-checklist-filtered";
   message: string;
   severity: "info" | "warning" | "error";
diff --git a/packages/core/test/exclude.test.ts b/packages/core/test/exclude.test.ts
index 3ed7141..85537c5 100644
--- a/packages/core/test/exclude.test.ts
+++ b/packages/core/test/exclude.test.ts
@@ -150,11 +150,24 @@ describe(".fixmapignore", () => {
     expect(report.diagnostics.some((entry) => entry.code === "paths-excluded")).toBe(false);
   });
 
-  it("stays silent when patterns match no scanned path", async () => {
+  it("warns when an exclusion pattern matches no scanned path", async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-nomatch-ignore-"));
     await writeFile(join(root, "reset.ts"), "export function sendResetEmail() { return 1; }\n");
     const report = await buildFixMapReport({ repoRoot: root, issueText: "sendResetEmail fails", exclude: ["missing/**"] });
     expect(report.diagnostics.some((entry) => entry.code === "paths-excluded")).toBe(false);
+    expect(report.diagnostics.find((entry) => entry.code === "exclusion-no-match")?.message)
+      .toContain("missing/**");
+  });
+
+  it("normalizes an absolute pattern inside the repository to a root-relative pattern", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-absolute-ignore-"));
+    await mkdir(join(root, "src"), { recursive: true });
+    await writeFile(join(root, "src", "reset.ts"), "export function sendResetEmail() { return 1; }\n");
+
+    const excluder = await resolveExclusions(root, [join(root, "src", "**")]);
+
+    expect(excluder.patterns).toEqual(["/src/**"]);
+    expect(excluder.excludes("src/reset.ts")).toBe(true);
   });
 });
 
diff --git a/packages/core/test/repo-scan.test.ts b/packages/core/test/repo-scan.test.ts
index 54db167..9a883f3 100644
--- a/packages/core/test/repo-scan.test.ts
+++ b/packages/core/test/repo-scan.test.ts
@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises";
+import { mkdtemp, mkdir, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { promisify } from "node:util";
@@ -513,6 +513,12 @@ describe("scanRepo", () => {
       await scanRepo({ repoRoot: root, useCache: true });
       const cleanHit = await scanRepo({ repoRoot: root, useCache: true });
       expect(cleanHit.diagnostics.map((entry) => entry.code)).toContain("cache-hit");
+      expect(cleanHit.diagnostics.find((entry) => entry.code === "cache-hit")?.message)
+        .toContain("scanned just now");
+
+      const bypassed = await scanRepo({ repoRoot: root, useCache: false });
+      expect(bypassed.diagnostics.find((entry) => entry.code === "cache-bypass")?.message)
+        .toContain("fresh scan");
 
       await writeFile(join(root, "index.ts"), "export const value = 'two';\n");
       const firstDirty = await scanRepo({ repoRoot: root, useCache: true });
@@ -532,6 +538,65 @@ describe("scanRepo", () => {
     }
   });
 
+  it("does not reuse a staged scan after the same edit becomes unstaged", { timeout: 30_000 }, async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-cache-stage-state-"));
+    const cacheRoot = await mkdtemp(join(tmpdir(), "fixmap-cache-stage-store-"));
+    const previousCache = process.env.FIXMAP_CACHE_DIR;
+    process.env.FIXMAP_CACHE_DIR = cacheRoot;
+    try {
+      await writeFile(join(root, "index.ts"), "export const value = 'one';\n");
+      await exec("git", ["init", "-b", "main"], { cwd: root });
+      await exec("git", ["config", "user.email", "test@example.com"], { cwd: root });
+      await exec("git", ["config", "user.name", "Test User"], { cwd: root });
+      await exec("git", ["add", "."], { cwd: root });
+      await exec("git", ["commit", "-m", "initial"], { cwd: root });
+
+      await writeFile(join(root, "index.ts"), "export const value = 'changed';\n");
+      await exec("git", ["add", "index.ts"], { cwd: root });
+      await scanRepo({ repoRoot: root, useCache: true });
+      expect((await scanRepo({ repoRoot: root, useCache: true })).diagnostics.map((entry) => entry.code))
+        .toContain("cache-hit");
+
+      await exec("git", ["reset", "HEAD", "--", "index.ts"], { cwd: root });
+      const unstaged = await scanRepo({ repoRoot: root, useCache: true });
+      expect(unstaged.diagnostics.map((entry) => entry.code)).not.toContain("cache-hit");
+    } finally {
+      if (previousCache === undefined) delete process.env.FIXMAP_CACHE_DIR;
+      else process.env.FIXMAP_CACHE_DIR = previousCache;
+      await rm(cacheRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("expires scan-cache entries older than seven days", { timeout: 30_000 }, async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-cache-expiry-repo-"));
+    const cacheRoot = await mkdtemp(join(tmpdir(), "fixmap-cache-expiry-store-"));
+    const previousCache = process.env.FIXMAP_CACHE_DIR;
+    process.env.FIXMAP_CACHE_DIR = cacheRoot;
+    try {
+      await writeFile(join(root, "index.ts"), "export const value = 1;\n");
+      await exec("git", ["init", "-b", "main"], { cwd: root });
+      await exec("git", ["config", "user.email", "test@example.com"], { cwd: root });
+      await exec("git", ["config", "user.name", "Test User"], { cwd: root });
+      await exec("git", ["add", "."], { cwd: root });
+      await exec("git", ["commit", "-m", "initial"], { cwd: root });
+
+      await scanRepo({ repoRoot: root, useCache: true });
+      const cachePath = join(cacheRoot, (await readdir(cacheRoot))[0]!);
+      const cached = JSON.parse(await readFile(cachePath, "utf8")) as Record<string, unknown>;
+      cached.createdAt = new Date(Date.now() - 8 * 24 * 60 * 60 * 1000).toISOString();
+      await writeFile(cachePath, `${JSON.stringify(cached)}\n`);
+
+      const expired = await scanRepo({ repoRoot: root, useCache: true });
+      expect(expired.diagnostics.map((entry) => entry.code)).not.toContain("cache-hit");
+      expect((await scanRepo({ repoRoot: root, useCache: true })).diagnostics.map((entry) => entry.code))
+        .toContain("cache-hit");
+    } finally {
+      if (previousCache === undefined) delete process.env.FIXMAP_CACHE_DIR;
+      else process.env.FIXMAP_CACHE_DIR = previousCache;
+      await rm(cacheRoot, { recursive: true, force: true });
+    }
+  });
+
   it("names skipped git submodules and leaves their contents to the nested repository", { timeout: 30_000 }, async () => {
     const child = await mkdtemp(join(tmpdir(), "fixmap-submodule-child-"));
     const root = await mkdtemp(join(tmpdir(), "fixmap-submodule-parent-"));

From 9a2083e620816cde1228bd22b20741574664ebe3 Mon Sep 17 00:00:00 2001
From: Aryam Goyal <aryamgoyal18@gmail.com>
Date: Sun, 9 Aug 2026 13:22:34 +0530
Subject: [PATCH 02/10] Harden package, setup, and cache edge cases

---
 apps/web/app/_components/site-header.tsx |  2 +-
 packages/action/dist/index.mjs           | 36 +++++-----
 packages/action/src/runner.ts            |  3 +-
 packages/action/test/runner.test.ts      | 14 ++++
 packages/cli/README.md                   | 31 ++++++++-
 packages/cli/src/agent-setup.ts          | 89 ++++++++++++++++++++----
 packages/cli/src/cli-runner.ts           | 19 ++++-
 packages/cli/src/mcp.ts                  |  3 +-
 packages/cli/test/cli-runner.test.ts     | 58 ++++++++++++++-
 packages/cli/test/mcp.test.ts            |  4 +-
 packages/core/README.md                  |  6 +-
 packages/core/src/index.ts               |  1 +
 packages/core/src/repo-scan.ts           | 30 ++++----
 packages/core/src/text.ts                |  5 ++
 packages/core/test/repo-scan.test.ts     | 57 +++++++++++++++
 15 files changed, 293 insertions(+), 65 deletions(-)

diff --git a/apps/web/app/_components/site-header.tsx b/apps/web/app/_components/site-header.tsx
index 803cdfd..5e2be49 100644
--- a/apps/web/app/_components/site-header.tsx
+++ b/apps/web/app/_components/site-header.tsx
@@ -46,7 +46,7 @@ export function SiteHeader() {
         <div className="header-actions">
           <ThemeToggle />
           <details className="mobile-menu">
-            <summary aria-label="Open navigation"><List size={25} weight="bold" aria-hidden /></summary>
+            <summary><List size={25} weight="bold" aria-hidden /><span className="sr-only">Navigation menu</span></summary>
             <nav aria-label="Mobile navigation"><NavLinks /></nav>
           </details>
         </div>
diff --git a/packages/action/dist/index.mjs b/packages/action/dist/index.mjs
index 4715af6..f694749 100644
--- a/packages/action/dist/index.mjs
+++ b/packages/action/dist/index.mjs
@@ -1,7 +1,7 @@
 import { createRequire as __fixmapCreateRequire } from 'module'; const require = __fixmapCreateRequire(import.meta.url);
 
 // packages/action/src/runner.ts
-import { randomUUID } from "node:crypto";
+import { randomUUID as randomUUID2 } from "node:crypto";
 import { appendFileSync, readFileSync } from "node:fs";
 
 // packages/core/dist/plan.js
@@ -1501,6 +1501,9 @@ function extractEnvNames(textSample) {
 // packages/core/dist/text.js
 var DIAGNOSTIC_TERM_LIMIT = 48;
 var DIAGNOSTIC_SPEC_LIMIT = 80;
+function stripByteOrderMark(value) {
+  return value.replace(/^\uFEFF/, "");
+}
 function truncateForDiagnostic(value, limit) {
   return value.length <= limit ? value : `${value.slice(0, limit)}\u2026`;
 }
@@ -1896,8 +1899,8 @@ function listOrEmpty(lines) {
 
 // packages/core/dist/repo-scan.js
 import { execFile } from "node:child_process";
-import { createHash } from "node:crypto";
-import { mkdir, readdir, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, extname, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
@@ -2070,23 +2073,16 @@ async function readScanCache(location) {
   }
 }
 async function writeScanCache(location, cached) {
+  const temporaryPath = `${location.path}.${process.pid}-${randomUUID()}.tmp`;
   try {
     await mkdir(dirname(location.path), { recursive: true });
     await pruneExpiredScanCache(dirname(location.path));
-    await writeFile(location.path, `${JSON.stringify(cached)}
+    await writeFile(temporaryPath, `${JSON.stringify(cached)}
 `, { encoding: "utf8", flag: "wx" });
-  } catch (error) {
-    const code = error.code;
-    if (code !== "EEXIST") {
-      return;
-    }
-    const existing = await readScanCache(location);
-    if (existing)
-      return;
+    await rename(temporaryPath, location.path);
+  } catch {
     try {
-      await unlink(location.path);
-      await writeFile(location.path, `${JSON.stringify(cached)}
-`, { encoding: "utf8", flag: "wx" });
+      await unlink(temporaryPath);
     } catch {
     }
   }
@@ -3099,7 +3095,7 @@ async function runAction(env = process.env, dependencies = {}) {
     appendFile(env.GITHUB_STEP_SUMMARY, fitStepSummary(format === "json" ? withJsonDetails(markdown, output) : markdown));
   }
   if (env.GITHUB_OUTPUT) {
-    appendFile(env.GITHUB_OUTPUT, renderActionOutputs(output, report, dependencies.uuid ?? randomUUID));
+    appendFile(env.GITHUB_OUTPUT, renderActionOutputs(output, report, dependencies.uuid ?? randomUUID2));
   }
   const token = readInput("github-token", env) || env.GITHUB_TOKEN;
   const commentAuthor = readInput("comment-author", env);
@@ -3144,7 +3140,7 @@ async function runVerifyMode(context) {
   }
   let report;
   try {
-    report = JSON.parse(context.readFile(reportPath));
+    report = JSON.parse(stripByteOrderMark(context.readFile(reportPath)));
   } catch (error) {
     throw new Error(
       `FixMap could not read the plan at "${reportPath}": ${error instanceof Error ? error.message : String(error)}.`
@@ -3177,7 +3173,7 @@ async function runVerifyMode(context) {
   if (context.env.GITHUB_OUTPUT) {
     context.appendFile(
       context.env.GITHUB_OUTPUT,
-      renderVerifyOutputs(output, result, context.dependencies.uuid ?? randomUUID)
+      renderVerifyOutputs(output, result, context.dependencies.uuid ?? randomUUID2)
     );
   }
   if (result.findings.some((finding) => finding.severity === "error")) {
@@ -3186,7 +3182,7 @@ async function runVerifyMode(context) {
     );
   }
 }
-function renderVerifyOutputs(reportText, result, uuid = randomUUID) {
+function renderVerifyOutputs(reportText, result, uuid = randomUUID2) {
   const delimiter = `fixmap_${uuid().replaceAll("-", "")}`;
   const terminated = reportText.endsWith("\n") ? reportText : `${reportText}
 `;
@@ -3224,7 +3220,7 @@ function parseBooleanInput(name, value) {
   if (/^(?:false|0|no)$/i.test(value)) return false;
   throw new Error(`${name} must be true or false.`);
 }
-function renderActionOutputs(reportText, report, uuid = randomUUID) {
+function renderActionOutputs(reportText, report, uuid = randomUUID2) {
   const delimiter = `fixmap_${uuid().replaceAll("-", "")}`;
   const terminatedReport = reportText.endsWith("\n") ? reportText : `${reportText}
 `;
diff --git a/packages/action/src/runner.ts b/packages/action/src/runner.ts
index 2c00af8..7645937 100644
--- a/packages/action/src/runner.ts
+++ b/packages/action/src/runner.ts
@@ -6,6 +6,7 @@ import {
   renderMarkdownReport,
   renderVerifyMarkdown,
   scanRepo,
+  stripByteOrderMark,
   validateFixMapReport,
   verifyPlan,
   type FixMapReport,
@@ -195,7 +196,7 @@ async function runVerifyMode(context: VerifyModeContext): Promise<void> {
 
   let report: FixMapReport;
   try {
-    report = JSON.parse(context.readFile(reportPath)) as FixMapReport;
+    report = JSON.parse(stripByteOrderMark(context.readFile(reportPath))) as FixMapReport;
   } catch (error) {
     throw new Error(
       `FixMap could not read the plan at "${reportPath}": ${error instanceof Error ? error.message : String(error)}.`
diff --git a/packages/action/test/runner.test.ts b/packages/action/test/runner.test.ts
index 8488c51..70edb8a 100644
--- a/packages/action/test/runner.test.ts
+++ b/packages/action/test/runner.test.ts
@@ -149,6 +149,20 @@ describe("GitHub Action runner", () => {
     expect(stdout.mock.calls[0]?.[0]).toContain("# FixMap Verification");
   });
 
+  it("accepts a verify report saved by a Windows editor with a byte-order mark", async () => {
+    const stdout = vi.fn();
+    await expect(runAction({
+      INPUT_MODE: "verify",
+      INPUT_REPORT_PATH: "plan.json",
+      INPUT_DIFF: "main...HEAD"
+    }, {
+      readFile: () => `\uFEFF${JSON.stringify(report)}`,
+      scanRepo: async () => scannedRepo(["src/auth.ts"]),
+      stdout
+    })).resolves.toBeUndefined();
+    expect(stdout.mock.calls[0]?.[0]).toContain("# FixMap Verification");
+  });
+
   it("says what verify mode needs when report-path is missing", async () => {
     await expect(runAction({ INPUT_MODE: "verify", INPUT_DIFF: "main...HEAD" }, { stdout: vi.fn() }))
       .rejects.toThrow("report-path");
diff --git a/packages/cli/README.md b/packages/cli/README.md
index f25b61b..c808a3d 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -27,6 +27,15 @@ For private source or working-tree changes, run from a local JavaScript or TypeS
 fixmap plan --issue "password reset emails fail"
 ```
 
+Install a discoverable `/fixmap` command for supported coding agents, then invoke it without a task to see the complete workflow menu:
+
+```bash
+fixmap setup
+fixmap features
+```
+
+`fixmap setup` supports Claude Code, Cursor, GitHub Copilot prompt files, and the open Agent Skills layout. It preflights every target, is idempotent, and refuses to overwrite customized commands unless you explicitly pass `--force` after reviewing them.
+
 Use a real branch diff:
 
 ```bash
@@ -43,9 +52,25 @@ Public GitHub issue, pull request, and repository URL modes are available in the
 
 For long task text, use `--issue-file task.md` or pipe text to `--issue -`. A leading `@` in `--issue` is ordinary task text; only the explicit file flag reads from disk. A one-off `npx -y @aryam/fixmap@latest ...` run is also available, but npm may choose an existing project-local FixMap first. Run `fixmap doctor`, treat its printed running version as authoritative, and update or remove a stale install. For a reproducible clean test, install the exact version into an isolated npm prefix and invoke that prefix's `fixmap` shim directly; the repository README includes complete PowerShell and POSIX commands.
 
+## Complete feature catalog
+
+- **Plan** — rank context files, related tests, test commands, risks, changed files, diagnostics, grounding, confidence, and a next action from task text, a task file, stdin, a public GitHub issue or pull request, a branch diff, or the working tree.
+- **Explain** — use `--explain <path>` to distinguish ranked, below-cutoff, tie-truncated, excluded, and not-scanned paths.
+- **Compare** — use `--compare <report.json>` to measure how a refined task changed ranks, scores, confidence, and grounding.
+- **Verify** — compare a saved plan with the completed diff or working tree; FixMap reports drift but does not pretend to run tests or prove correctness.
+- **Validate** — run `fixmap validate <report.json>` to check report compatibility without writing custom JavaScript.
+- **Focus controls** — cap output with `--limit`, repeat `--exclude`, or use ordered `.fixmapignore` patterns with negation. Pasted absolute paths inside the repository are normalized, and unmatched patterns produce a warning.
+- **Live changes** — `--working-tree` maps staged and unstaged tracked edits; `--include-untracked` opts new files into the changed-file set.
+- **Exact-state cache** — clean and tracked dirty git states are cached by repository, commit, status, and binary diff. Cache hits report age, entries expire after seven days, and `--no-cache` reports a fresh bypass.
+- **Doctor** — report the running version, resolved binary, global/PATH shadows, Node compatibility, and an optionally requested npm version.
+- **MCP** — expose Plan, Explain, Compare, Verify, and Doctor as five local stdio tools.
+- **Slash-command discovery** — `fixmap setup` installs `/fixmap`; `fixmap features` prints the same complete catalog in Markdown or JSON.
+- **Safe repository handling** — public repositories use isolated temporary checkouts with credentials, hooks, filters, and submodule recursion disabled. Local source is read without installing dependencies or running repository scripts.
+- **Human and machine output** — Markdown is the default; JSON reports carry `reportVersion: 1` and follow the documented additive compatibility policy.
+
 ## MCP server
 
-FixMap ships as a Model Context Protocol server with `fixmap_plan` and `fixmap_verify`, so coding agents can plan first and compare the resulting diff with that plan afterwards.
+FixMap ships five Model Context Protocol tools: `fixmap_plan`, `fixmap_explain`, `fixmap_compare`, `fixmap_verify`, and `fixmap_doctor`.
 
 Claude Code:
 
@@ -72,6 +97,9 @@ Cursor, Windsurf, or any MCP client:
 fixmap plan            Generate a FixMap report for a task or diff
 fixmap verify          Compare a saved plan with the diff that followed
 fixmap doctor          Report the resolved version and any shadowing install
+fixmap validate        Validate a saved FixMap JSON report
+fixmap features        List every FixMap capability in Markdown or JSON
+fixmap setup           Install /fixmap discovery for supported coding agents
 fixmap mcp             Run FixMap as an MCP server over stdio
 
 --issue <text|url>     Issue text, task description, or public GitHub issue or pull request URL
@@ -85,6 +113,7 @@ fixmap mcp             Run FixMap as an MCP server over stdio
 --compare <file>       Diff this plan against a saved JSON plan
 --limit <n>            Cap reported context files, 1 to 20 (default 8)
 --exclude <pattern>    Leave paths out of ranking; repeatable, gitignore-flavored
+--no-cache             Bypass the exact-state repository scan cache
 --repo <source>        Local path, file:// URL, or public GitHub HTTPS/SSH URL
 --format <fmt>         Output format: markdown (default) or json
 --output <file>        Write the report to a file instead of stdout
diff --git a/packages/cli/src/agent-setup.ts b/packages/cli/src/agent-setup.ts
index 09fd1dd..f834e55 100644
--- a/packages/cli/src/agent-setup.ts
+++ b/packages/cli/src/agent-setup.ts
@@ -1,5 +1,5 @@
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve } from "node:path";
+import { lstat, mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
 export type AgentTarget = "claude" | "cursor" | "copilot" | "agents";
 
@@ -68,28 +68,89 @@ export async function installAgentCommands(input: {
   targets: AgentTarget[];
   force?: boolean;
 }): Promise<Array<{ path: string; status: "created" | "unchanged" | "updated" }>> {
-  const root = resolve(input.repoRoot);
+  const requestedRoot = resolve(input.repoRoot);
   try {
-    if (!(await stat(root)).isDirectory()) throw new Error("not a directory");
+    if (!(await stat(requestedRoot)).isDirectory()) throw new Error("not a directory");
   } catch {
-    throw new Error(`Setup repository "${root}" does not exist or is not a directory.`);
+    throw new Error(`Setup repository "${requestedRoot}" does not exist or is not a directory.`);
   }
-  const results: Array<{ path: string; status: "created" | "unchanged" | "updated" }> = [];
+  const root = await realpath(requestedRoot);
+  const prepared: Array<{
+    path: string;
+    displayPath: string;
+    contents: string;
+    existing: string | undefined;
+  }> = [];
+
+  // Preflight every target before writing any of them. A customized command or unsafe link
+  // must not leave a half-installed multi-agent setup behind.
   for (const target of input.targets) {
     const template = templates[target];
     const path = join(root, template.path);
+    const displayPath = relative(root, path).replace(/\\/g, "/");
+    await assertSafeTarget(root, path, displayPath);
     let existing: string | undefined;
-    try { existing = await readFile(path, "utf8"); } catch { /* A missing file is expected. */ }
-    if (existing === template.contents) {
-      results.push({ path: relative(root, path).replace(/\\/g, "/"), status: "unchanged" });
-      continue;
+    try {
+      existing = await readFile(path, "utf8");
+    } catch (error) {
+      if ((error as { code?: unknown }).code !== "ENOENT") {
+        throw new Error(`Could not inspect existing ${displayPath}: ${error instanceof Error ? error.message : String(error)}`);
+      }
     }
     if (existing !== undefined && !input.force) {
-      throw new Error(`Refusing to overwrite existing ${relative(root, path)}. Re-run with --force after reviewing it.`);
+      if (existing !== template.contents) {
+        throw new Error(`Refusing to overwrite existing ${displayPath}. Re-run with --force after reviewing it.`);
+      }
     }
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, template.contents, "utf8");
-    results.push({ path: relative(root, path).replace(/\\/g, "/"), status: existing === undefined ? "created" : "updated" });
+    prepared.push({ path, displayPath, contents: template.contents, existing });
+  }
+
+  const results: Array<{ path: string; status: "created" | "unchanged" | "updated" }> = [];
+  for (const entry of prepared) {
+    if (entry.existing === entry.contents) {
+      results.push({ path: entry.displayPath, status: "unchanged" });
+      continue;
+    }
+    await mkdir(dirname(entry.path), { recursive: true });
+    await writeFile(entry.path, entry.contents, "utf8");
+    results.push({ path: entry.displayPath, status: entry.existing === undefined ? "created" : "updated" });
   }
   return results;
 }
+
+async function assertSafeTarget(root: string, target: string, displayPath: string): Promise<void> {
+  try {
+    const targetMetadata = await lstat(target);
+    if (targetMetadata.isSymbolicLink()) {
+      throw new Error(`Refusing to write ${displayPath} because the target is a symbolic link.`);
+    }
+    if (!targetMetadata.isFile()) {
+      throw new Error(`Refusing to write ${displayPath} because the target is not a regular file.`);
+    }
+  } catch (error) {
+    if ((error as { code?: unknown }).code !== "ENOENT") throw error;
+  }
+
+  let ancestor = dirname(target);
+  while (true) {
+    try {
+      const ancestorMetadata = await lstat(ancestor);
+      if (!ancestorMetadata.isDirectory() && !ancestorMetadata.isSymbolicLink()) {
+        throw new Error(`Refusing to write ${displayPath} because ${ancestor} is not a directory.`);
+      }
+      const resolvedAncestor = await realpath(ancestor);
+      const distance = relative(root, resolvedAncestor);
+      if (distance === ".." || distance.startsWith(`..${sep}`) || isAbsolute(distance)) {
+        throw new Error(`Refusing to write ${displayPath} because its parent resolves outside the setup repository.`);
+      }
+      return;
+    } catch (error) {
+      if ((error as { code?: unknown }).code !== "ENOENT") throw error;
+      const parent = dirname(ancestor);
+      if (parent === ancestor) {
+        throw new Error(`Could not find a safe parent directory for ${displayPath}.`);
+      }
+      ancestor = parent;
+    }
+  }
+}
diff --git a/packages/cli/src/cli-runner.ts b/packages/cli/src/cli-runner.ts
index 114a9c9..3448b7b 100644
--- a/packages/cli/src/cli-runner.ts
+++ b/packages/cli/src/cli-runner.ts
@@ -14,6 +14,7 @@ import {
   verifyPlan,
   renderMarkdownReport,
   scanRepo,
+  stripByteOrderMark,
   validateFixMapReport,
   type FixMapReport
 } from "@aryam/fixmap-core";
@@ -122,6 +123,7 @@ Set FIXMAP_PROGRESS=1 to print scan and clone phases to stderr.
 
 const DOCTOR_USAGE = `Usage: fixmap doctor [--format markdown|json]\n\nChecks the running FixMap binary, PATH/global shadows, and known install blind spots.\n`;
 const MCP_USAGE = `Usage: fixmap mcp\n\nRuns the FixMap MCP server over stdio. Configure your MCP client to execute \"fixmap mcp\".\n`;
+const FEATURES_USAGE = `Usage: fixmap features [--format markdown|json]\n\nLists every FixMap capability and the command that exposes it.\n`;
 const SETUP_USAGE = `Usage: fixmap setup [--agent claude|cursor|copilot|agents|all] [--repo <path>] [--force]\n\nInstalls a /fixmap command that lists and runs FixMap workflows.\n`;
 const VALIDATE_USAGE = `Usage: fixmap validate <report.json> [--format markdown|json]\n\nChecks a saved report against FixMap's structural compatibility contract.\n`;
 
@@ -156,6 +158,7 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
 
   if (args[0] === "features") {
     const featureArgs = args.slice(1);
+    if (featureArgs[0] === "--help" || featureArgs[0] === "-h") { stdout(FEATURES_USAGE); return 0; }
     let format: "markdown" | "json" = "markdown";
     if (featureArgs.length > 0) {
       const value = featureArgs.length === 2 && featureArgs[0] === "--format"
@@ -179,38 +182,48 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     let repoRoot = process.cwd();
     let targets: AgentTarget[] = ["claude", "cursor", "copilot", "agents"];
     let force = false;
+    let repoSeen = false;
+    let agentSeen = false;
     for (let index = 1; index < args.length; index += 1) {
       const arg = args[index];
       if (arg === "--force") { force = true; continue; }
       if (arg?.startsWith("--repo=")) {
+        if (repoSeen) { stderr(`Pass --repo only once.\n\n${SETUP_USAGE}`); return 1; }
         const value = arg.slice("--repo=".length).trim();
         if (!value) { stderr(`--repo requires a directory.\n\n${SETUP_USAGE}`); return 1; }
         repoRoot = expandHomePath(value);
+        repoSeen = true;
         continue;
       }
       if (arg === "--repo") {
+        if (repoSeen) { stderr(`Pass --repo only once.\n\n${SETUP_USAGE}`); return 1; }
         const value = args[index + 1];
         if (!value?.trim() || value.startsWith("--")) { stderr(`--repo requires a directory.\n\n${SETUP_USAGE}`); return 1; }
         repoRoot = expandHomePath(value.trim());
+        repoSeen = true;
         index += 1;
         continue;
       }
       if (arg?.startsWith("--agent=")) {
+        if (agentSeen) { stderr(`Pass --agent only once.\n\n${SETUP_USAGE}`); return 1; }
         const value = arg.slice("--agent=".length).trim().toLowerCase();
         if (!["claude", "cursor", "copilot", "agents", "all"].includes(value)) {
           stderr(`--agent must be claude, cursor, copilot, agents, or all.\n\n${SETUP_USAGE}`);
           return 1;
         }
         targets = value === "all" ? ["claude", "cursor", "copilot", "agents"] : [value as AgentTarget];
+        agentSeen = true;
         continue;
       }
       if (arg === "--agent") {
+        if (agentSeen) { stderr(`Pass --agent only once.\n\n${SETUP_USAGE}`); return 1; }
         const value = args[index + 1]?.trim().toLowerCase();
         if (!value || !["claude", "cursor", "copilot", "agents", "all"].includes(value)) {
           stderr(`--agent must be claude, cursor, copilot, agents, or all.\n\n${SETUP_USAGE}`);
           return 1;
         }
         targets = value === "all" ? ["claude", "cursor", "copilot", "agents"] : [value as AgentTarget];
+        agentSeen = true;
         index += 1;
         continue;
       }
@@ -251,7 +264,7 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     }
     if (!reportPath) { stderr(`validate requires a report path.\n\n${VALIDATE_USAGE}`); return 1; }
     try {
-      const parsed = JSON.parse(readFileSync(reportPath, "utf8")) as unknown;
+      const parsed = JSON.parse(stripByteOrderMark(readFileSync(reportPath, "utf8"))) as unknown;
       const result = validateFixMapReport(parsed, `"${reportPath}"`);
       if (!result.success) { stderr(`${result.message}\n`); return 1; }
       const payload = {
@@ -471,7 +484,7 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     let previous: FixMapReport;
     let previousText: string;
     try {
-      previousText = readFileSync(options.comparePath, "utf8");
+      previousText = stripByteOrderMark(readFileSync(options.comparePath, "utf8"));
     } catch (error) {
       stderr(
         `Could not read comparison file "${options.comparePath}": ${error instanceof Error ? error.message : String(error)}\n` +
@@ -944,7 +957,7 @@ async function runVerify(
 
   let reportText: string;
   try {
-    reportText = readFileSync(options.reportPath, "utf8");
+    reportText = stripByteOrderMark(readFileSync(options.reportPath, "utf8"));
   } catch (error) {
     io.stderr(
       `Could not read "${options.reportPath}": ${error instanceof Error ? error.message : String(error)}\n` +
diff --git a/packages/cli/src/mcp.ts b/packages/cli/src/mcp.ts
index ff985d8..8a9c387 100644
--- a/packages/cli/src/mcp.ts
+++ b/packages/cli/src/mcp.ts
@@ -14,6 +14,7 @@ import {
   renderVerifyMarkdown,
   resolveExclusions,
   scanRepo,
+  stripByteOrderMark,
   validateFixMapReport,
   verifyPlan,
   type FixMapReport
@@ -639,7 +640,7 @@ function loadReportInput(input: unknown, label: string): LoadedReport {
     }
     let contents: string;
     try {
-      contents = readFileSync(path, "utf8");
+      contents = stripByteOrderMark(readFileSync(path, "utf8"));
     } catch (error) {
       return {
         success: false,
diff --git a/packages/cli/test/cli-runner.test.ts b/packages/cli/test/cli-runner.test.ts
index 91f8830..9a08225 100644
--- a/packages/cli/test/cli-runner.test.ts
+++ b/packages/cli/test/cli-runner.test.ts
@@ -1,4 +1,4 @@
-import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, symlink, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it, vi } from "vitest";
@@ -93,6 +93,25 @@ describe("CLI argument handling", () => {
     expect(io.stdout.join("")).toContain("fixmap setup");
   });
 
+  it("documents the features subcommand directly", async () => {
+    const io = capture();
+    expect(await runCli(["features", "--help"], io.dependencies)).toBe(0);
+    expect(io.stdout.join("")).toContain("Usage: fixmap features [--format markdown|json]");
+  });
+
+  it("keeps the npm package README aligned with the complete public feature catalog", async () => {
+    const npmReadme = await readFile(new URL("../README.md", import.meta.url), "utf8");
+    for (const feature of [
+      "Plan", "Explain", "Compare", "Verify", "Validate", "Doctor", "MCP",
+      "Focus controls", "Live changes", "Exact-state cache", "Slash-command discovery"
+    ]) {
+      expect(npmReadme).toContain(`**${feature}**`);
+    }
+    for (const command of ["fixmap setup", "fixmap features", "fixmap validate", "--no-cache"]) {
+      expect(npmReadme).toContain(command);
+    }
+  });
+
   it("installs an idempotent /fixmap command for a selected agent", async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-"));
     const first = capture();
@@ -118,10 +137,43 @@ describe("CLI argument handling", () => {
     expect(invalid.stderr.join("")).toContain("--repo requires a directory");
   });
 
-  it("validates a saved report without requiring custom JavaScript", async () => {
+  it("rejects repeated setup destinations instead of silently choosing the last one", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-repeat-"));
+    const repeatedRepo = capture();
+    const repeatedAgent = capture();
+
+    expect(await runCli(["setup", "--repo", root, `--repo=${root}`], repeatedRepo.dependencies)).toBe(1);
+    expect(repeatedRepo.stderr.join("")).toContain("Pass --repo only once");
+    expect(await runCli(["setup", "--agent", "all", "--agent=cursor"], repeatedAgent.dependencies)).toBe(1);
+    expect(repeatedAgent.stderr.join("")).toContain("Pass --agent only once");
+  });
+
+  it("preflights every setup target before creating files", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-atomic-"));
+    await mkdir(join(root, ".cursor", "commands"), { recursive: true });
+    await writeFile(join(root, ".cursor", "commands", "fixmap.md"), "custom command\n");
+    const io = capture();
+
+    expect(await runCli(["setup", "--repo", root, "--agent", "all"], io.dependencies)).toBe(1);
+    expect(io.stderr.join("")).toContain("Refusing to overwrite existing .cursor/commands/fixmap.md");
+    await expect(readFile(join(root, ".claude", "skills", "fixmap", "SKILL.md"), "utf8")).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("refuses setup paths whose parent link escapes the repository", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-link-"));
+    const outside = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-outside-"));
+    await symlink(outside, join(root, ".claude"), process.platform === "win32" ? "junction" : "dir");
+    const io = capture();
+
+    expect(await runCli(["setup", "--repo", root, "--agent", "claude"], io.dependencies)).toBe(1);
+    expect(io.stderr.join("")).toContain("resolves outside the setup repository");
+    await expect(readFile(join(outside, "skills", "fixmap", "SKILL.md"), "utf8")).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("validates a saved report with a Windows byte-order mark without custom JavaScript", async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-validate-"));
     const path = join(root, "report.json");
-    await writeFile(path, JSON.stringify(report));
+    await writeFile(path, `\uFEFF${JSON.stringify(report)}`);
     const io = capture();
 
     expect(await runCli(["validate", path, "--format", "json"], io.dependencies)).toBe(0);
diff --git a/packages/cli/test/mcp.test.ts b/packages/cli/test/mcp.test.ts
index 758893d..aaf35a9 100644
--- a/packages/cli/test/mcp.test.ts
+++ b/packages/cli/test/mcp.test.ts
@@ -293,7 +293,7 @@ describe("fixmap mcp server", () => {
       "export function sendResetEmail(email: string) { return email.trim(); }\n"
     );
     const planPath = join(root, "plan.json");
-    await writeFile(planPath, JSON.stringify({
+    await writeFile(planPath, `\uFEFF${JSON.stringify({
       summary: "",
       contextFiles: [{
         path: "src/auth/reset-password.ts",
@@ -305,7 +305,7 @@ describe("fixmap mcp server", () => {
       risks: [],
       changedFiles: [],
       diagnostics: []
-    }));
+    })}`);
     const client = await connectClient();
 
     // Agents that used the CLI first pass a path. Requiring the object form also made the
diff --git a/packages/core/README.md b/packages/core/README.md
index 608d588..5dc67d3 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -17,6 +17,10 @@ const report = await buildFixMapReport({
 console.log(renderMarkdownReport(report));
 ```
 
-`buildFixMapReport` runs the full pipeline: scan the repository, rank context files against the task, route to the most relevant test commands, and collect risk notes and diagnostics. Lower-level pieces (`scanRepo`, `rankContextFiles`, `buildTestRoutes`, `buildRiskNotes`, `renderJsonReport`) are exported individually.
+`buildFixMapReport` runs the full pipeline: scan the repository, resolve exclusions, rank context files against the task, route to the most relevant test commands, and collect risk notes and diagnostics. Exact git states can reuse a seven-day scan cache, while `useCache: false` forces a fresh scan and reports the bypass.
+
+The package also exports the lower-level scanner, excluder, ranker, grounding, import-graph, test-routing, risk, comparison, explanation, verification, structural validation, and Markdown/JSON rendering APIs. `@aryam/fixmap-core/browser` exposes the filesystem-free report, Compare, Explain, Verify, validation, and rendering logic for browser applications.
+
+JSON reports use `reportVersion: 1`. Additive fields and diagnostic codes may appear within that version; consumers should ignore unknown fields and use diagnostic severity as the stable fallback.
 
 MIT © FixMap contributors.
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index e74f184..e7157f5 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -21,6 +21,7 @@ export { scanRepo } from "./repo-scan.js";
 export { validateFixMapReport } from "./validate.js";
 export type { ValidatedFixMapReport } from "./validate.js";
 export { findGatedTestDiagnostics } from "./test-gates.js";
+export { stripByteOrderMark } from "./text.js";
 export type {
   FixMapInput,
   FixMapReport,
diff --git a/packages/core/src/repo-scan.ts b/packages/core/src/repo-scan.ts
index 8c6a609..742d5ca 100644
--- a/packages/core/src/repo-scan.ts
+++ b/packages/core/src/repo-scan.ts
@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
-import { createHash } from "node:crypto";
-import { mkdir, readdir, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, extname, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
@@ -230,26 +230,20 @@ async function readScanCache(location: ScanCacheLocation): Promise<CachedScan |
 }
 
 async function writeScanCache(location: ScanCacheLocation, cached: CachedScan): Promise<void> {
+  const temporaryPath = `${location.path}.${process.pid}-${randomUUID()}.tmp`;
   try {
     await mkdir(dirname(location.path), { recursive: true });
     await pruneExpiredScanCache(dirname(location.path));
-    await writeFile(location.path, `${JSON.stringify(cached)}\n`, { encoding: "utf8", flag: "wx" });
-  } catch (error) {
-    const code = (error as { code?: unknown }).code;
-    if (code !== "EEXIST") {
-      // Cache writes are an optimization. A read-only cache directory must not fail a plan.
-      return;
-    }
-    // An interrupted prior write can leave an invalid exact-key file. Replace only that
-    // FixMap-owned cache entry; never touch a repository path.
-    const existing = await readScanCache(location);
-    if (existing) return;
+    // Write beside the destination and rename only after the JSON is complete. Readers never
+    // observe a truncated cache file, and a corrupt/expired exact-key entry heals immediately.
+    await writeFile(temporaryPath, `${JSON.stringify(cached)}\n`, { encoding: "utf8", flag: "wx" });
+    await rename(temporaryPath, location.path);
+  } catch {
+    // Cache writes are an optimization. Read-only directories and concurrent writers must not
+    // fail a report. Remove only this process's uniquely named temporary file.
     try {
-      await unlink(location.path);
-      await writeFile(location.path, `${JSON.stringify(cached)}\n`, { encoding: "utf8", flag: "wx" });
-    } catch {
-      // Another process may have won the replacement race; the current scan is still valid.
-    }
+      await unlink(temporaryPath);
+    } catch { /* The rename may already have consumed it. */ }
   }
 }
 
diff --git a/packages/core/src/text.ts b/packages/core/src/text.ts
index 9674347..b2041b5 100644
--- a/packages/core/src/text.ts
+++ b/packages/core/src/text.ts
@@ -10,6 +10,11 @@
 export const DIAGNOSTIC_TERM_LIMIT = 48;
 export const DIAGNOSTIC_SPEC_LIMIT = 80;
 
+/** JSON.parse rejects a leading byte-order mark even though Windows editors commonly add one. */
+export function stripByteOrderMark(value: string): string {
+  return value.replace(/^\uFEFF/, "");
+}
+
 export function truncateForDiagnostic(value: string, limit: number): string {
   return value.length <= limit ? value : `${value.slice(0, limit)}…`;
 }
diff --git a/packages/core/test/repo-scan.test.ts b/packages/core/test/repo-scan.test.ts
index 9a883f3..5d36113 100644
--- a/packages/core/test/repo-scan.test.ts
+++ b/packages/core/test/repo-scan.test.ts
@@ -597,6 +597,63 @@ describe("scanRepo", () => {
     }
   });
 
+  it("heals a corrupt exact-state cache and never serves partial JSON", { timeout: 30_000 }, async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-cache-corrupt-repo-"));
+    const cacheRoot = await mkdtemp(join(tmpdir(), "fixmap-cache-corrupt-store-"));
+    const previousCache = process.env.FIXMAP_CACHE_DIR;
+    process.env.FIXMAP_CACHE_DIR = cacheRoot;
+    try {
+      await writeFile(join(root, "index.ts"), "export const value = 1;\n");
+      await exec("git", ["init", "-b", "main"], { cwd: root });
+      await exec("git", ["config", "user.email", "test@example.com"], { cwd: root });
+      await exec("git", ["config", "user.name", "Test User"], { cwd: root });
+      await exec("git", ["add", "."], { cwd: root });
+      await exec("git", ["commit", "-m", "initial"], { cwd: root });
+
+      await scanRepo({ repoRoot: root, useCache: true });
+      const cachePath = join(cacheRoot, (await readdir(cacheRoot))[0]!);
+      await writeFile(cachePath, "{truncated");
+
+      const repaired = await scanRepo({ repoRoot: root, useCache: true });
+      expect(repaired.diagnostics.map((entry) => entry.code)).not.toContain("cache-hit");
+      const repairedJson = await readFile(cachePath, "utf8");
+      expect(() => JSON.parse(repairedJson)).not.toThrow();
+      expect((await scanRepo({ repoRoot: root, useCache: true })).diagnostics.map((entry) => entry.code))
+        .toContain("cache-hit");
+    } finally {
+      if (previousCache === undefined) delete process.env.FIXMAP_CACHE_DIR;
+      else process.env.FIXMAP_CACHE_DIR = previousCache;
+      await rm(cacheRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps the exact-state cache valid across concurrent first scans", { timeout: 30_000 }, async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-cache-concurrent-repo-"));
+    const cacheRoot = await mkdtemp(join(tmpdir(), "fixmap-cache-concurrent-store-"));
+    const previousCache = process.env.FIXMAP_CACHE_DIR;
+    process.env.FIXMAP_CACHE_DIR = cacheRoot;
+    try {
+      await writeFile(join(root, "index.ts"), "export const value = 1;\n");
+      await exec("git", ["init", "-b", "main"], { cwd: root });
+      await exec("git", ["config", "user.email", "test@example.com"], { cwd: root });
+      await exec("git", ["config", "user.name", "Test User"], { cwd: root });
+      await exec("git", ["add", "."], { cwd: root });
+      await exec("git", ["commit", "-m", "initial"], { cwd: root });
+
+      await Promise.all(Array.from({ length: 4 }, () => scanRepo({ repoRoot: root, useCache: true })));
+      const entries = (await readdir(cacheRoot)).filter((entry) => entry.endsWith(".json"));
+      expect(entries).toHaveLength(1);
+      const concurrentJson = await readFile(join(cacheRoot, entries[0]!), "utf8");
+      expect(() => JSON.parse(concurrentJson)).not.toThrow();
+      expect((await scanRepo({ repoRoot: root, useCache: true })).diagnostics.map((entry) => entry.code))
+        .toContain("cache-hit");
+    } finally {
+      if (previousCache === undefined) delete process.env.FIXMAP_CACHE_DIR;
+      else process.env.FIXMAP_CACHE_DIR = previousCache;
+      await rm(cacheRoot, { recursive: true, force: true });
+    }
+  });
+
   it("names skipped git submodules and leaves their contents to the nested repository", { timeout: 30_000 }, async () => {
     const child = await mkdtemp(join(tmpdir(), "fixmap-submodule-child-"));
     const root = await mkdtemp(join(tmpdir(), "fixmap-submodule-parent-"));

From 8633367543c3d9ddc28e58fd29957f3cd6478dad Mon Sep 17 00:00:00 2001
From: Aryam Goyal <aryamgoyal18@gmail.com>
Date: Sun, 9 Aug 2026 14:17:25 +0530
Subject: [PATCH 03/10] Prevent FixMap artifacts from polluting scans

---
 README.md                             |   1 +
 apps/web/app/docs/page.tsx            |   2 +-
 packages/action/dist/index.mjs        | 197 ++++++++++++++++++++------
 packages/action/src/runner.ts         |   7 +-
 packages/action/test/runner.test.ts   |  20 ++-
 packages/cli/README.md                |   1 +
 packages/cli/src/agent-setup.ts       |   3 +
 packages/cli/src/cli-runner.ts        |  81 +++++++++--
 packages/cli/src/mcp.ts               |  12 +-
 packages/cli/src/repository-source.ts |   4 +-
 packages/cli/test/cli-runner.test.ts  | 130 ++++++++++++++++-
 packages/cli/test/mcp.test.ts         |  21 ++-
 packages/core/src/plan.ts             |  36 +++--
 packages/core/src/repo-scan.ts        | 169 +++++++++++++++++-----
 packages/core/src/validate.ts         |  83 ++++++++---
 packages/core/test/repo-scan.test.ts  |  80 +++++++++++
 packages/core/test/validate.test.ts   |  26 ++++
 17 files changed, 748 insertions(+), 125 deletions(-)

diff --git a/README.md b/README.md
index a8c7897..1fb1619 100644
--- a/README.md
+++ b/README.md
@@ -86,6 +86,7 @@ Use `--working-tree` for staged and unstaged tracked edits, `--include-untracked
 - Scans the current checkout, another local path, a `file://` URL, or an isolated checkout of a public GitHub repository.
 - Maps `--diff <spec>`, `--base`/`--head`, or the current `--working-tree`; untracked changes remain opt-in with `--include-untracked`.
 - Reuses repository scans only when the repository root, commit, status, and binary diff are identical. `cache-hit` reports reuse and scan age, entries expire after seven days, `--no-cache` reports a fresh bypass, and `FIXMAP_CACHE_DIR` moves the OS cache.
+- Keeps the current `--issue-file`, `--compare`, `--report`, and `--output` artifacts out of repository ranking, change detection, and cache invalidation, so FixMap never recommends its own report as the fix site.
 - Detects npm, pnpm, Yarn, and Bun projects and reads the scripts declared by each workspace package.
 
 ### Plan and ranking
diff --git a/apps/web/app/docs/page.tsx b/apps/web/app/docs/page.tsx
index 6a641c8..3a5d589 100644
--- a/apps/web/app/docs/page.tsx
+++ b/apps/web/app/docs/page.tsx
@@ -60,7 +60,7 @@ export default function DocsPage() {
 
           <section id="verify" className="doc-section"><p className="eyebrow">Verify</p><h2>Compare the plan with the change.</h2><p>Save a JSON plan before editing, then compare it with the real diff afterwards.</p><CopyCommand command={'fixmap plan --issue "reset links fail" --format json --output plan.json'} /><CopyCommand command={commands.verify} /><div className="doc-note"><WarningCircle size={22} aria-hidden /><p>Verify does not run tests or judge correctness. Most findings are advisory because the plan can be wrong and the change can still be right.</p></div></section>
 
-          <section id="output" className="doc-section"><p className="eyebrow">Output</p><h2>Readable by people and tools.</h2><p>Markdown is the default handoff. Add <code>--format json</code> for structured output and <code>--output &lt;path&gt;</code> to save it.</p><p>New JSON plans include <code>reportVersion: 1</code>. Within a report version, fields may be added but existing fields will not be removed or change type; consumers should ignore unknown fields. A breaking output change requires a new report version. Compare and Verify still accept legacy plans without a marker, while rejecting marker values they do not understand.</p><div className="definition-list"><div><strong>Context files</strong><p>Ranked paths, scores, confidence labels, and evidence.</p></div><div><strong>Test routes</strong><p>Workspace-aware commands and reachable related tests.</p></div><div><strong>Risks</strong><p>Sensitive areas inferred from paths, symbols, and changes.</p></div><div><strong>Diagnostics</strong><p>Vague tasks, unresolved identifiers, scan limits, and other uncertainty.</p></div></div></section>
+          <section id="output" className="doc-section"><p className="eyebrow">Output</p><h2>Readable by people and tools.</h2><p>Markdown is the default handoff. Add <code>--format json</code> for structured output and <code>--output &lt;path&gt;</code> to save it. The current issue, comparison, verification, and output files are kept out of ranking, change detection, and cache state, so a saved FixMap report cannot recommend itself.</p><p>New JSON plans include <code>reportVersion: 1</code>. Within a report version, fields may be added but existing fields will not be removed or change type; consumers should ignore unknown fields. A breaking output change requires a new report version. Compare and Verify still accept legacy plans without a marker, while rejecting marker values they do not understand.</p><div className="definition-list"><div><strong>Context files</strong><p>Ranked paths, scores, confidence labels, and evidence.</p></div><div><strong>Test routes</strong><p>Workspace-aware commands and reachable related tests.</p></div><div><strong>Risks</strong><p>Sensitive areas inferred from paths, symbols, and changes.</p></div><div><strong>Diagnostics</strong><p>Vague tasks, unresolved identifiers, scan limits, and other uncertainty.</p></div></div></section>
 
           <section id="validate" className="doc-section"><p className="eyebrow">Validate</p><h2>Check a saved report directly.</h2><p>The CLI exposes the same additive structural validator used by Compare, Verify, the GitHub Action, and MCP. It accepts legacy unmarked reports, accepts version 1 with additive fields, and rejects unsupported report versions or malformed context entries.</p><CopyCommand command={commands.validate} /></section>
 
diff --git a/packages/action/dist/index.mjs b/packages/action/dist/index.mjs
index f694749..e726e03 100644
--- a/packages/action/dist/index.mjs
+++ b/packages/action/dist/index.mjs
@@ -3,6 +3,7 @@ import { createRequire as __fixmapCreateRequire } from 'module'; const require =
 // packages/action/src/runner.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
 import { appendFileSync, readFileSync } from "node:fs";
+import { resolve as resolve3 } from "node:path";
 
 // packages/core/dist/plan.js
 import { readFile as readFile2 } from "node:fs/promises";
@@ -1902,7 +1903,7 @@ import { execFile } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, extname, join, relative, resolve, sep } from "node:path";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 var WALK_IGNORED_DIRS = /* @__PURE__ */ new Set([...ALWAYS_IGNORED_DIRS, ...GENERATED_DIRS]);
 var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
@@ -1965,7 +1966,10 @@ async function scanRepo(input) {
     };
   }
   const diagnostics = [];
-  const cacheDecision = input.useCache === true ? await buildScanCacheLocation(repoRoot) : void 0;
+  const internalPaths = await resolveInternalPaths(repoRoot, input.internalExclude ?? []);
+  const cacheRoot = configuredScanCacheRoot();
+  const internalCacheRoot = sameFilesystemPath(cacheRoot, repoRoot) || containedPath(repoRoot, cacheRoot) !== void 0 ? cacheRoot : void 0;
+  const cacheDecision = input.useCache === true ? await buildScanCacheLocation(repoRoot, cacheRoot, internalPaths) : void 0;
   const cacheLocation = cacheDecision?.location;
   if (input.useCache === false) {
     diagnostics.push({
@@ -1996,8 +2000,8 @@ async function scanRepo(input) {
       message: `Reused the repository scan for the exact current git state (${files.length.toLocaleString()} files, ${describeCacheAge(cached.createdAt)}). Pass --no-cache to rescan.`
     });
   } else {
-    files = await listFiles(repoRoot, diagnostics);
-    trackedFiles = await listTrackedPaths(repoRoot);
+    files = await listFiles(repoRoot, diagnostics, internalCacheRoot, internalPaths);
+    trackedFiles = await listTrackedPaths(repoRoot, internalPaths);
     packageScripts = await readPackageScripts(repoRoot, files, diagnostics);
     packageManager = detectPackageManager(files);
     if (cacheLocation) {
@@ -2014,7 +2018,7 @@ async function scanRepo(input) {
     }
   }
   const diffSpec = resolveDiffSpec(input);
-  const diff = input.workingTree ? await readWorkingTree(repoRoot, input.includeUntracked === true, diagnostics) : await readDiff(repoRoot, diffSpec, diagnostics);
+  const diff = input.workingTree ? await readWorkingTree(repoRoot, input.includeUntracked === true, diagnostics, internalPaths) : await readDiff(repoRoot, diffSpec, diagnostics, internalPaths);
   return {
     root: repoRoot,
     files,
@@ -2026,11 +2030,44 @@ async function scanRepo(input) {
     diagnostics
   };
 }
-async function buildScanCacheLocation(root) {
+function configuredScanCacheRoot() {
+  return resolve(process.env.FIXMAP_CACHE_DIR ?? join(process.env.LOCALAPPDATA ?? process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "fixmap", "scans"));
+}
+function containedPath(root, candidate) {
+  const distance = relative(root, candidate);
+  return distance === "" || distance === ".." || distance.startsWith(`..${sep}`) || isAbsolute(distance) ? void 0 : normalizePath(distance);
+}
+async function resolveInternalPaths(root, paths) {
+  const requested = paths.flatMap((path) => {
+    const relativePath = containedPath(root, resolve(path));
+    return relativePath ? [relativePath] : [];
+  });
+  if (requested.length === 0 || process.platform !== "win32")
+    return new Set(requested);
+  try {
+    const { stdout } = await exec("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], { cwd: root, maxBuffer: GIT_MAX_BUFFER });
+    const repositoryPaths = stdout.split("\0").filter(Boolean).map(normalizePath);
+    return new Set(requested.map((path) => repositoryPaths.find((candidate) => sameFilesystemPath(candidate, path)) ?? path));
+  } catch {
+    return new Set(requested);
+  }
+}
+function hasInternalPath(paths, path) {
+  return [...paths].some((candidate) => sameFilesystemPath(candidate, path));
+}
+function gitPathspec(internalPaths) {
+  return ["--", ".", ...[...internalPaths].sort((a, b) => a.localeCompare(b)).map((path) => `:(exclude,literal)${path}`)];
+}
+async function buildScanCacheLocation(root, cacheRoot, internalPaths) {
+  if (sameFilesystemPath(cacheRoot, root) || containedPath(root, cacheRoot) !== void 0) {
+    return {
+      skipReason: "Repository scan caching was skipped because FIXMAP_CACHE_DIR is inside the scanned repository. Move the cache outside the repository to enable exact-state reuse."
+    };
+  }
   try {
     const [{ stdout: head }, { stdout: status }] = await Promise.all([
       exec("git", ["rev-parse", "HEAD"], { cwd: root, maxBuffer: GIT_MAX_BUFFER }),
-      exec("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--", "."], {
+      exec("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all", ...gitPathspec(internalPaths)], {
         cwd: root,
         maxBuffer: GIT_MAX_BUFFER
       })
@@ -2040,7 +2077,7 @@ async function buildScanCacheLocation(root) {
         skipReason: "Repository scan caching was skipped because untracked files are scanner inputs and can change without a stable git diff."
       };
     }
-    const dirtyDiff = status.length > 0 ? (await exec("git", ["diff", "--binary", "--no-ext-diff", "HEAD", "--", "."], {
+    const dirtyDiff = status.length > 0 ? (await exec("git", ["diff", "--binary", "--no-ext-diff", "HEAD", ...gitPathspec(internalPaths)], {
       cwd: root,
       maxBuffer: GIT_MAX_BUFFER
     })).stdout : "";
@@ -2049,9 +2086,9 @@ async function buildScanCacheLocation(root) {
       resolve(root),
       head.trim(),
       status,
-      dirtyDiff
+      dirtyDiff,
+      ...[...internalPaths].sort((a, b) => a.localeCompare(b))
     ].join("\0"));
-    const cacheRoot = process.env.FIXMAP_CACHE_DIR ?? join(process.env.LOCALAPPDATA ?? process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "fixmap", "scans");
     return { location: {
       path: join(cacheRoot, `${hashText(resolve(root))}-${stateKey}.json`),
       stateKey
@@ -2120,10 +2157,10 @@ function describeCacheAge(createdAt) {
 function hashText(value) {
   return createHash("sha256").update(value).digest("hex").slice(0, 24);
 }
-async function listTrackedPaths(root) {
+async function listTrackedPaths(root, internalPaths) {
   try {
     const { stdout } = await exec("git", ["ls-files", "--cached", "-z"], { cwd: root, maxBuffer: GIT_MAX_BUFFER });
-    return stdout.split("\0").filter(Boolean).map(normalizePath);
+    return stdout.split("\0").filter(Boolean).map(normalizePath).filter((path) => !hasInternalPath(internalPaths, path));
   } catch {
     return [];
   }
@@ -2131,13 +2168,25 @@ async function listTrackedPaths(root) {
 function resolveDiffSpec(input) {
   return input.diffSpec ?? (input.baseRef ? `${input.baseRef}...${input.headRef ?? "HEAD"}` : void 0);
 }
-async function listFiles(root, diagnostics) {
+async function listFiles(root, diagnostics, internalCacheRoot, internalPaths) {
   const gitPaths = await listGitPaths(root);
-  const files = gitPaths ? await buildFilesFromPaths(root, gitPaths.paths, diagnostics, gitPaths.gitLinks) : (await walkFiles(root, root, diagnostics, { count: 0, limitReported: false })).sort((a, b) => a.path.localeCompare(b.path));
+  const visiblePaths = gitPaths?.paths.filter((path) => !hasInternalPath(internalPaths, normalizePath(path)) && !isInternalCachePath(root, path, internalCacheRoot));
+  const files = gitPaths ? await buildFilesFromPaths(root, visiblePaths ?? [], diagnostics, gitPaths.gitLinks) : (await walkFiles(root, root, diagnostics, { count: 0, limitReported: false }, internalCacheRoot, internalPaths)).sort((a, b) => a.path.localeCompare(b.path));
   reportUnreadContent(diagnostics, files);
   reportGeneratedDominance(diagnostics, files);
   return files;
 }
+function isInternalCachePath(root, path, internalCacheRoot) {
+  if (!internalCacheRoot)
+    return false;
+  const relativeCacheRoot = containedPath(root, internalCacheRoot);
+  if (relativeCacheRoot) {
+    const candidate = process.platform === "win32" ? path.toLowerCase() : path;
+    const cachePath = process.platform === "win32" ? relativeCacheRoot.toLowerCase() : relativeCacheRoot;
+    return candidate === cachePath || candidate.startsWith(`${cachePath}/`);
+  }
+  return sameFilesystemPath(internalCacheRoot, root) && (SCAN_CACHE_FILE.test(path) || /^[a-f0-9]{24}-[a-f0-9]{24}\.json\.\d+-[0-9a-f-]+\.tmp$/i.test(path));
+}
 async function listGitPaths(root) {
   try {
     const [{ stdout }, { stdout: staged }] = await Promise.all([
@@ -2278,7 +2327,7 @@ function reportLinkedDuplicates(diagnostics, linked) {
     message: `${linked.length.toLocaleString()} tracked path${linked.length === 1 ? "" : "s"} resolved to a file already scanned under another name and ${linked.length === 1 ? "was" : "were"} ranked once: ${sample}${linked.length > 3 ? ", \u2026" : ""}.`
   });
 }
-async function walkFiles(root, current, diagnostics, state) {
+async function walkFiles(root, current, diagnostics, state, internalCacheRoot, internalPaths) {
   let entries;
   try {
     entries = await readdir(current, { withFileTypes: true });
@@ -2298,14 +2347,20 @@ async function walkFiles(root, current, diagnostics, state) {
       if (WALK_IGNORED_DIRS.has(entry.name)) {
         continue;
       }
-      results.push(...await walkFiles(root, join(current, entry.name), diagnostics, state));
+      const directory = join(current, entry.name);
+      if (internalCacheRoot && sameFilesystemPath(directory, internalCacheRoot))
+        continue;
+      results.push(...await walkFiles(root, directory, diagnostics, state, internalCacheRoot, internalPaths));
       continue;
     }
     if (!entry.isFile()) {
       continue;
     }
     const absolutePath = join(current, entry.name);
-    const scanned = await toRepoFile(absolutePath, normalizePath(relative(root, absolutePath)));
+    const relativePath = normalizePath(relative(root, absolutePath));
+    if (hasInternalPath(internalPaths, relativePath) || isInternalCachePath(root, relativePath, internalCacheRoot))
+      continue;
+    const scanned = await toRepoFile(absolutePath, relativePath);
     if (scanned.status === "ok") {
       results.push(scanned.file);
       state.count += 1;
@@ -2437,17 +2492,17 @@ function decodeManifest(bytes) {
   }
   return { text: bytes.toString("utf8"), encoding: "utf8" };
 }
-async function readDiff(repoRoot, diffSpec, diagnostics) {
+async function readDiff(repoRoot, diffSpec, diagnostics, internalPaths) {
   if (!diffSpec) {
     return { changedFiles: [], diffText: "" };
   }
   try {
     const [{ stdout: names }, { stdout: diffText }] = await Promise.all([
-      exec("git", ["diff", "--relative", "--name-only", diffSpec], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
-      exec("git", ["diff", "--relative", diffSpec], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER })
+      exec("git", ["diff", "--relative", "--name-only", diffSpec, ...gitPathspec(internalPaths)], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
+      exec("git", ["diff", "--relative", diffSpec, ...gitPathspec(internalPaths)], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER })
     ]);
     const tracked = names.split(/\r?\n/).map((path) => path.trim()).filter(Boolean).map(normalizePath);
-    const untracked = diffSpec.includes("..") ? [] : await listUntrackedPaths(repoRoot);
+    const untracked = diffSpec.includes("..") ? [] : await listUntrackedPaths(repoRoot, internalPaths);
     const changedFiles = [.../* @__PURE__ */ new Set([...tracked, ...untracked])].sort((a, b) => a.localeCompare(b));
     diagnostics.push({
       code: "diff-resolved",
@@ -2470,14 +2525,14 @@ async function readDiff(repoRoot, diffSpec, diagnostics) {
     return { changedFiles: [], diffText: "" };
   }
 }
-async function readWorkingTree(repoRoot, includeUntracked, diagnostics) {
+async function readWorkingTree(repoRoot, includeUntracked, diagnostics, internalPaths) {
   try {
     const [{ stdout: names }, { stdout: diffText }] = await Promise.all([
-      exec("git", ["diff", "--relative", "--name-only", "HEAD"], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
-      exec("git", ["diff", "--relative", "HEAD"], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER })
+      exec("git", ["diff", "--relative", "--name-only", "HEAD", ...gitPathspec(internalPaths)], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
+      exec("git", ["diff", "--relative", "HEAD", ...gitPathspec(internalPaths)], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER })
     ]);
     const tracked = names.split(/\r?\n/).map((path) => path.trim()).filter(Boolean).map(normalizePath);
-    const untracked = includeUntracked ? await listUntrackedPaths(repoRoot) : [];
+    const untracked = includeUntracked ? await listUntrackedPaths(repoRoot, internalPaths) : [];
     const changedFiles = [.../* @__PURE__ */ new Set([...tracked, ...untracked])].sort((a, b) => a.localeCompare(b));
     diagnostics.push({
       code: "working-tree-diff",
@@ -2558,10 +2613,10 @@ async function readTextSample(path, sizeBytes) {
     return { text: "", complete: false, skipReason: "unreadable" };
   }
 }
-async function listUntrackedPaths(repoRoot) {
+async function listUntrackedPaths(repoRoot, internalPaths = /* @__PURE__ */ new Set()) {
   try {
     const { stdout } = await exec("git", ["ls-files", "--others", "--exclude-standard", "-z"], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER });
-    return stdout.split("\0").filter(Boolean).map(normalizePath);
+    return stdout.split("\0").filter(Boolean).map(normalizePath).filter((path) => !hasInternalPath(internalPaths, path));
   } catch {
     return [];
   }
@@ -2580,15 +2635,17 @@ function normalizePath(path) {
 // packages/core/dist/plan.js
 async function buildFixMapReport(input) {
   const repo = await scanRepo(input);
-  const exclude = await resolveExclusions(input.repoRoot, input.exclude ?? []);
+  const requestedExclude = await resolveExclusions(input.repoRoot, input.exclude ?? []);
+  const internalExclude = buildPathExcluder((input.internalExclude ?? []).map((pattern) => normalizeAbsolutePattern(input.repoRoot, pattern)));
+  const exclude = combineExclusions(requestedExclude, internalExclude);
   const report = buildReportFromRepo(repo, {
     issueText: input.issueText,
     limit: input.limit,
     exclude
   });
-  if (exclude.patterns.length > 0) {
-    const excludedPaths = repo.files.filter((file) => exclude.excludes(file.path)).map((file) => file.path);
-    const unmatchedPatterns = exclude.patterns.filter((pattern) => !pattern.startsWith("!") && !exclude.matchedPatterns.has(pattern));
+  if (requestedExclude.patterns.length > 0) {
+    const excludedPaths = repo.files.filter((file) => requestedExclude.excludes(file.path)).map((file) => file.path);
+    const unmatchedPatterns = requestedExclude.patterns.filter((pattern) => !pattern.startsWith("!") && !requestedExclude.matchedPatterns.has(pattern));
     if (unmatchedPatterns.length > 0) {
       const sample = unmatchedPatterns.slice(0, 5).join(", ");
       report.diagnostics.push({
@@ -2601,12 +2658,24 @@ async function buildFixMapReport(input) {
       report.diagnostics.push({
         code: "paths-excluded",
         severity: report.contextFiles.length === 0 ? "warning" : "info",
-        message: `${exclude.patterns.length} exclusion ${exclude.patterns.length === 1 ? "pattern" : "patterns"} removed ${excludedPaths.length} ${excludedPaths.length === 1 ? "path" : "paths"} from ranking: ${exclude.patterns.join(", ")}. Run --explain on a file you expected to see if this is why it is absent.`
+        message: `${requestedExclude.patterns.length} exclusion ${requestedExclude.patterns.length === 1 ? "pattern" : "patterns"} removed ${excludedPaths.length} ${excludedPaths.length === 1 ? "path" : "paths"} from ranking: ${requestedExclude.patterns.join(", ")}. Run --explain on a file you expected to see if this is why it is absent.`
       });
     }
   }
   return report;
 }
+function combineExclusions(primary, internal) {
+  if (internal.patterns.length === 0)
+    return primary;
+  if (primary.patterns.length === 0)
+    return internal;
+  return {
+    excludes: (path) => primary.excludes(path) || internal.excludes(path),
+    reasonFor: (path) => primary.reasonFor(path) ?? internal.reasonFor(path),
+    patterns: [...primary.patterns, ...internal.patterns],
+    matchedPatterns: /* @__PURE__ */ new Set([...primary.matchedPatterns, ...internal.matchedPatterns])
+  };
+}
 async function resolveExclusions(repoRoot, patterns) {
   const combined = [...await readIgnoreFile(repoRoot), ...patterns].map((pattern) => normalizeAbsolutePattern(repoRoot, pattern));
   return combined.length > 0 ? buildPathExcluder(combined) : NO_EXCLUSIONS;
@@ -2786,12 +2855,6 @@ function validateFixMapReport(candidate, label) {
       message: `${label} uses unsupported reportVersion ${JSON.stringify(record.reportVersion)}; this FixMap release supports reportVersion 1.`
     };
   }
-  if (contextFiles.length === 0 && !(typeof record.summary === "string" && Array.isArray(record.testRoutes) && Array.isArray(record.risks) && Array.isArray(record.changedFiles) && Array.isArray(record.diagnostics))) {
-    return {
-      success: false,
-      message: `${label} has no context files and is missing the complete FixMap report envelope (summary, testRoutes, risks, changedFiles, and diagnostics).`
-    };
-  }
   const invalid = contextFiles.findIndex((file) => {
     if (typeof file !== "object" || file === null)
       return true;
@@ -2812,6 +2875,58 @@ function validateFixMapReport(candidate, label) {
       message: `${label} has an invalid contextFiles entry at index ${invalid}; each entry needs a non-empty string "path", and optional rank, score, and confidence fields must use their documented types.`
     };
   }
+  const invalidEnvelopeFields = [
+    typeof record.summary === "string" ? void 0 : "summary (string)",
+    Array.isArray(record.testRoutes) ? void 0 : "testRoutes (array)",
+    Array.isArray(record.risks) ? void 0 : "risks (array)",
+    Array.isArray(record.changedFiles) ? void 0 : "changedFiles (array)",
+    Array.isArray(record.diagnostics) ? void 0 : "diagnostics (array)"
+  ].filter((field) => field !== void 0);
+  if (invalidEnvelopeFields.length > 0) {
+    return {
+      success: false,
+      message: `${label} is missing or has invalid fields in the complete FixMap report envelope: ${invalidEnvelopeFields.join(", ")}.`
+    };
+  }
+  const testRoutes = record.testRoutes;
+  const invalidRoute = testRoutes.findIndex((route) => {
+    if (typeof route !== "object" || route === null || Array.isArray(route))
+      return true;
+    const entry = route;
+    return typeof entry.command !== "string" || !Array.isArray(entry.relatedFiles) || !entry.relatedFiles.every((path) => typeof path === "string");
+  });
+  if (invalidRoute !== -1) {
+    return {
+      success: false,
+      message: `${label} has an invalid testRoutes entry at index ${invalidRoute}; each route needs a string "command" and a string array named relatedFiles.`
+    };
+  }
+  const risks = record.risks;
+  const invalidRisk = risks.findIndex((risk) => {
+    if (typeof risk !== "object" || risk === null || Array.isArray(risk))
+      return true;
+    return typeof risk.area !== "string";
+  });
+  if (invalidRisk !== -1) {
+    return {
+      success: false,
+      message: `${label} has an invalid risks entry at index ${invalidRisk}; each risk needs a string "area".`
+    };
+  }
+  if (!record.changedFiles.every((path) => typeof path === "string")) {
+    return { success: false, message: `${label} has invalid changedFiles; every entry must be a string path.` };
+  }
+  if (record.analysis !== void 0) {
+    const analysis = record.analysis;
+    const grounding = typeof analysis === "object" && analysis !== null && !Array.isArray(analysis) ? analysis.grounding : void 0;
+    const specificity = typeof grounding === "object" && grounding !== null && !Array.isArray(grounding) ? grounding.specificity : void 0;
+    if (specificity !== "anchored" && specificity !== "descriptive" && specificity !== "vague") {
+      return {
+        success: false,
+        message: `${label} has invalid analysis.grounding.specificity; expected anchored, descriptive, or vague.`
+      };
+    }
+  }
   return { success: true, report: candidate };
 }
 
@@ -3149,14 +3264,16 @@ async function runVerifyMode(context) {
   const loaded = validateFixMapReport(report, `"${reportPath}"`);
   if (!loaded.success) throw new Error(loaded.message);
   report = loaded.report;
+  const repoRoot = (context.dependencies.cwd ?? process.cwd)();
   const repo = await (context.dependencies.scanRepo ?? scanRepo)({
-    repoRoot: (context.dependencies.cwd ?? process.cwd)(),
+    repoRoot,
     diffSpec: context.diffSpec,
     baseRef: context.baseRef,
     headRef: context.headRef,
     workingTree: context.workingTree,
     includeUntracked: context.includeUntracked,
-    useCache: true
+    useCache: true,
+    internalExclude: [resolve3(repoRoot, reportPath)]
   });
   const diffFailure = repo.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
   if (diffFailure) {
diff --git a/packages/action/src/runner.ts b/packages/action/src/runner.ts
index 7645937..7dff79d 100644
--- a/packages/action/src/runner.ts
+++ b/packages/action/src/runner.ts
@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { appendFileSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import {
   buildFixMapReport,
   renderJsonReport,
@@ -206,14 +207,16 @@ async function runVerifyMode(context: VerifyModeContext): Promise<void> {
   if (!loaded.success) throw new Error(loaded.message);
   report = loaded.report;
 
+  const repoRoot = (context.dependencies.cwd ?? process.cwd)();
   const repo = await (context.dependencies.scanRepo ?? scanRepo)({
-    repoRoot: (context.dependencies.cwd ?? process.cwd)(),
+    repoRoot,
     diffSpec: context.diffSpec,
     baseRef: context.baseRef,
     headRef: context.headRef,
     workingTree: context.workingTree,
     includeUntracked: context.includeUntracked,
-    useCache: true
+    useCache: true,
+    internalExclude: [resolve(repoRoot, reportPath)]
   });
   const diffFailure = repo.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
   if (diffFailure) {
diff --git a/packages/action/test/runner.test.ts b/packages/action/test/runner.test.ts
index 70edb8a..a704f86 100644
--- a/packages/action/test/runner.test.ts
+++ b/packages/action/test/runner.test.ts
@@ -151,16 +151,34 @@ describe("GitHub Action runner", () => {
 
   it("accepts a verify report saved by a Windows editor with a byte-order mark", async () => {
     const stdout = vi.fn();
+    const scanRepo = vi.fn(async () => scannedRepo(["src/auth.ts"]));
     await expect(runAction({
       INPUT_MODE: "verify",
       INPUT_REPORT_PATH: "plan.json",
       INPUT_DIFF: "main...HEAD"
     }, {
       readFile: () => `\uFEFF${JSON.stringify(report)}`,
-      scanRepo: async () => scannedRepo(["src/auth.ts"]),
+      scanRepo,
       stdout
     })).resolves.toBeUndefined();
     expect(stdout.mock.calls[0]?.[0]).toContain("# FixMap Verification");
+    expect(scanRepo).toHaveBeenCalledWith(expect.objectContaining({
+      internalExclude: [expect.stringMatching(/plan\.json$/)]
+    }));
+  });
+
+  it("rejects a truncated non-empty report before scanning or dereferencing missing fields", async () => {
+    const scanRepo = vi.fn(async () => scannedRepo(["src/auth.ts"]));
+    await expect(runAction({
+      INPUT_MODE: "verify",
+      INPUT_REPORT_PATH: "plan.json",
+      INPUT_DIFF: "main...HEAD"
+    }, {
+      readFile: () => JSON.stringify({ reportVersion: 1, contextFiles: [{ path: "src/auth.ts" }] }),
+      scanRepo,
+      stdout: vi.fn()
+    })).rejects.toThrow("complete FixMap report envelope");
+    expect(scanRepo).not.toHaveBeenCalled();
   });
 
   it("says what verify mode needs when report-path is missing", async () => {
diff --git a/packages/cli/README.md b/packages/cli/README.md
index c808a3d..0a5bb4f 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -62,6 +62,7 @@ For long task text, use `--issue-file task.md` or pipe text to `--issue -`. A le
 - **Focus controls** — cap output with `--limit`, repeat `--exclude`, or use ordered `.fixmapignore` patterns with negation. Pasted absolute paths inside the repository are normalized, and unmatched patterns produce a warning.
 - **Live changes** — `--working-tree` maps staged and unstaged tracked edits; `--include-untracked` opts new files into the changed-file set.
 - **Exact-state cache** — clean and tracked dirty git states are cached by repository, commit, status, and binary diff. Cache hits report age, entries expire after seven days, and `--no-cache` reports a fresh bypass.
+- **Artifact isolation** — current issue, comparison, verification, and output files are removed from ranking, change detection, and cache state, so a saved plan cannot recommend or invalidate itself.
 - **Doctor** — report the running version, resolved binary, global/PATH shadows, Node compatibility, and an optionally requested npm version.
 - **MCP** — expose Plan, Explain, Compare, Verify, and Doctor as five local stdio tools.
 - **Slash-command discovery** — `fixmap setup` installs `/fixmap`; `fixmap features` prints the same complete catalog in Markdown or JSON.
diff --git a/packages/cli/src/agent-setup.ts b/packages/cli/src/agent-setup.ts
index f834e55..78d1704 100644
--- a/packages/cli/src/agent-setup.ts
+++ b/packages/cli/src/agent-setup.ts
@@ -127,6 +127,9 @@ async function assertSafeTarget(root: string, target: string, displayPath: strin
     if (!targetMetadata.isFile()) {
       throw new Error(`Refusing to write ${displayPath} because the target is not a regular file.`);
     }
+    if (targetMetadata.nlink > 1) {
+      throw new Error(`Refusing to write ${displayPath} because the target is hard-linked to another file.`);
+    }
   } catch (error) {
     if ((error as { code?: unknown }).code !== "ENOENT") throw error;
   }
diff --git a/packages/cli/src/cli-runner.ts b/packages/cli/src/cli-runner.ts
index 3448b7b..32f0683 100644
--- a/packages/cli/src/cli-runner.ts
+++ b/packages/cli/src/cli-runner.ts
@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   compareReports,
@@ -244,17 +244,22 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     if (args[1] === "--help" || args[1] === "-h") { stdout(VALIDATE_USAGE); return 0; }
     let reportPath: string | undefined;
     let format: "markdown" | "json" = "markdown";
+    let formatSeen = false;
     for (let index = 1; index < args.length; index += 1) {
       const arg = args[index]!;
       if (arg === "--format") {
+        if (formatSeen) { stderr(`Pass --format only once.\n\n${VALIDATE_USAGE}`); return 1; }
         const value = args[index + 1]?.trim().toLowerCase();
         if (value !== "markdown" && value !== "json") { stderr(`--format must be markdown or json.\n\n${VALIDATE_USAGE}`); return 1; }
         format = value;
+        formatSeen = true;
         index += 1;
       } else if (arg.startsWith("--format=")) {
+        if (formatSeen) { stderr(`Pass --format only once.\n\n${VALIDATE_USAGE}`); return 1; }
         const value = arg.slice("--format=".length).trim().toLowerCase();
         if (value !== "markdown" && value !== "json") { stderr(`--format must be markdown or json.\n\n${VALIDATE_USAGE}`); return 1; }
         format = value;
+        formatSeen = true;
       } else if (arg.startsWith("-") || reportPath) {
         stderr(`Unknown validate argument: ${arg}\n\n${VALIDATE_USAGE}`);
         return 1;
@@ -395,7 +400,16 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     }
     try {
       const repoRoot = options.repo ?? process.cwd();
-      const repo = await scanRepo({ repoRoot, diffSpec: options.diffSpec, baseRef: options.baseRef, headRef: options.headRef, workingTree: options.workingTree, includeUntracked: options.includeUntracked, useCache: !options.noCache });
+      const repo = await scanRepo({
+        repoRoot,
+        diffSpec: options.diffSpec,
+        baseRef: options.baseRef,
+        headRef: options.headRef,
+        workingTree: options.workingTree,
+        includeUntracked: options.includeUntracked,
+        useCache: !options.noCache,
+        internalExclude: localPlanArtifactExclusions(options)
+      });
       const explanation = explainFile(
         repo,
         {
@@ -404,16 +418,30 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
           // Without this, a file left out by .fixmapignore would be reported as having
           // scored below the cutoff — a false answer to the exact question --explain exists
           // to answer.
-          exclude: await resolveExclusions(repoRoot, options.exclude),
+          exclude: await resolveExclusions(repoRoot, [
+            ...options.exclude,
+            ...localPlanArtifactExclusions(options)
+          ]),
           limit: options.limit
         },
         options.explainPath
       );
-      stdout(
-        options.format === "json"
-          ? `${JSON.stringify(explanation, null, 2)}\n`
-          : renderExplanationMarkdown(explanation)
-      );
+      const renderedExplanation = options.format === "json"
+        ? `${JSON.stringify(explanation, null, 2)}\n`
+        : renderExplanationMarkdown(explanation);
+      if (options.output) {
+        try {
+          await (dependencies.writeReport ?? ((path, contents) => writeFile(path, contents, "utf8")))(
+            options.output,
+            renderedExplanation
+          );
+        } catch (error) {
+          stderr(formatOutputError(options.output, error, "explanation"));
+          return 1;
+        }
+      } else {
+        stdout(renderedExplanation);
+      }
       return 0;
     } catch (error) {
       stderr(`${error instanceof Error ? error.message : String(error)}\n`);
@@ -433,7 +461,8 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
       includeUntracked: options.includeUntracked,
       useCache: !options.noCache,
       limit: options.limit,
-      exclude: options.exclude
+      exclude: options.exclude,
+      internalExclude: localPlanArtifactExclusions(options)
     });
   } catch (error) {
     stderr(`${error instanceof Error ? error.message : String(error)}\n`);
@@ -751,15 +780,15 @@ export function parseArgs(args: string[]): CliOptions {
       else invalidValues.push("--issue-file requires a UTF-8 file path or - for stdin");
     } else if (arg === "--diff") {
       consumeValue();
-      if (value?.trim()) diffSpec = value;
+      if (value?.trim()) diffSpec = value.trim();
       else invalidValues.push("--diff requires a non-empty git diff spec");
     } else if (arg === "--base") {
       consumeValue();
-      if (value?.trim()) baseRef = value;
+      if (value?.trim()) baseRef = value.trim();
       else invalidValues.push("--base requires a non-empty git ref");
     } else if (arg === "--head") {
       consumeValue();
-      if (value?.trim()) headRef = value;
+      if (value?.trim()) headRef = value.trim();
       else invalidValues.push("--head requires a non-empty git ref");
     } else if (arg === "--repo") {
       consumeValue();
@@ -851,6 +880,31 @@ function expandHomePath(value: string): string {
   return value;
 }
 
+/**
+ * Inputs and outputs generated by the current FixMap workflow are rich in the task's own
+ * vocabulary. If they live inside the scanned checkout, ranking them as repository context
+ * creates a self-fulfilling result (`plan.json` explaining why `plan.json` is relevant).
+ */
+function localPlanArtifactExclusions(options: CliOptions): string[] {
+  const remoteIssue = options.issueText ? parseGitHubIssueSource(options.issueText) : undefined;
+  const remoteRepository = /^https?:\/\//i.test(options.repo ?? "") || (remoteIssue && !options.repo);
+  if (remoteRepository) return [];
+
+  const root = resolve(options.repo ?? process.cwd());
+  return [
+    options.output,
+    options.comparePath,
+    options.reportPath,
+    options.issueFile === "-" ? undefined : options.issueFile
+  ]
+    .filter((path): path is string => path !== undefined)
+    .map((path) => resolve(path))
+    .filter((path) => {
+      const distance = relative(root, path);
+      return distance !== "" && distance !== ".." && !distance.startsWith(`..${sep}`) && !isAbsolute(distance);
+    });
+}
+
 function loadIssueText(
   options: CliOptions,
   read: (path: string | number) => string | Buffer
@@ -1012,7 +1066,8 @@ async function runVerify(
       headRef: options.headRef,
       workingTree: options.workingTree,
       includeUntracked: options.includeUntracked,
-      useCache: !options.noCache
+      useCache: !options.noCache,
+      internalExclude: localPlanArtifactExclusions(options)
     });
     const unresolvedDiff = repo.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
     if (unresolvedDiff) {
diff --git a/packages/cli/src/mcp.ts b/packages/cli/src/mcp.ts
index 8a9c387..7adc48a 100644
--- a/packages/cli/src/mcp.ts
+++ b/packages/cli/src/mcp.ts
@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -61,6 +61,7 @@ type PlanArgumentsValidation =
 
 type VerifyArguments = {
   report: FixMapReport;
+  reportPath?: string;
   diff?: string;
   base?: string;
   head?: string;
@@ -293,7 +294,8 @@ export function createFixMapMcpServer(
           headRef: args.head,
           workingTree: args.workingTree,
           includeUntracked: args.includeUntracked,
-          useCache: true
+          useCache: true,
+          internalExclude: args.reportPath ? [resolve(args.reportPath)] : undefined
         });
         const diffFailure = repo.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
         if (diffFailure) {
@@ -604,6 +606,7 @@ export function parseVerifyArguments(input: unknown): VerifyArgumentsValidation
     success: true,
     value: {
       report,
+      ...(loaded.sourcePath ? { reportPath: loaded.sourcePath } : {}),
       ...(typeof record.diff === "string" ? { diff: record.diff.trim() } : {}),
       ...(typeof record.base === "string" ? { base: record.base.trim() } : {}),
       ...(typeof record.head === "string" ? { head: record.head.trim() } : {}),
@@ -623,7 +626,7 @@ function normalizeFormat(candidate: unknown): { success: true; value: "markdown"
 }
 
 type LoadedReport =
-  | { success: true; report: FixMapReport }
+  | { success: true; report: FixMapReport; sourcePath?: string }
   | { success: false; message: string };
 
 /**
@@ -656,7 +659,8 @@ function loadReportInput(input: unknown, label: string): LoadedReport {
         message: `${label} pointed at ${path}, which is not valid JSON: ${error instanceof Error ? error.message : String(error)}.`
       };
     }
-    return asFixMapReport(parsed, `the JSON in ${path}`);
+    const loaded = asFixMapReport(parsed, `the JSON in ${path}`);
+    return loaded.success ? { ...loaded, sourcePath: resolve(path) } : loaded;
   }
   return asFixMapReport(input, label);
 }
diff --git a/packages/cli/src/repository-source.ts b/packages/cli/src/repository-source.ts
index 277d751..553db71 100644
--- a/packages/cli/src/repository-source.ts
+++ b/packages/cli/src/repository-source.ts
@@ -31,6 +31,7 @@ export type RepositoryPlanInput = {
   useCache?: boolean | undefined;
   limit?: number | undefined;
   exclude?: string[] | undefined;
+  internalExclude?: string[] | undefined;
 };
 
 export type ClonedRepository = {
@@ -539,7 +540,8 @@ export async function buildReportForRepository(
         includeUntracked: input.includeUntracked,
         useCache: input.useCache,
         limit: input.limit,
-        exclude: input.exclude
+        exclude: input.exclude,
+        internalExclude: input.internalExclude
       });
       reportProgress(`ranked ${report.contextFiles.length} context files`);
       const sourceDiagnostics = [issueDiagnostic, resolvedSource.diagnostic].filter(
diff --git a/packages/cli/test/cli-runner.test.ts b/packages/cli/test/cli-runner.test.ts
index 9a08225..9ef38b2 100644
--- a/packages/cli/test/cli-runner.test.ts
+++ b/packages/cli/test/cli-runner.test.ts
@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, readFile, symlink, writeFile } from "node:fs/promises";
+import { link, mkdir, mkdtemp, readFile, symlink, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it, vi } from "vitest";
@@ -170,6 +170,20 @@ describe("CLI argument handling", () => {
     await expect(readFile(join(outside, "skills", "fixmap", "SKILL.md"), "utf8")).rejects.toMatchObject({ code: "ENOENT" });
   });
 
+  it("refuses to overwrite a hard-linked setup target", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-hardlink-"));
+    const outside = join(root, "outside-command.md");
+    const target = join(root, ".cursor", "commands", "fixmap.md");
+    await mkdir(join(root, ".cursor", "commands"), { recursive: true });
+    await writeFile(outside, "custom command\n");
+    await link(outside, target);
+    const io = capture();
+
+    expect(await runCli(["setup", "--repo", root, "--agent", "cursor", "--force"], io.dependencies)).toBe(1);
+    expect(io.stderr.join("")).toContain("hard-linked");
+    expect(await readFile(outside, "utf8")).toBe("custom command\n");
+  });
+
   it("validates a saved report with a Windows byte-order mark without custom JavaScript", async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-validate-"));
     const path = join(root, "report.json");
@@ -180,6 +194,33 @@ describe("CLI argument handling", () => {
     expect(JSON.parse(io.stdout.join(""))).toMatchObject({ valid: true, path, contextFiles: 1 });
   });
 
+  it("rejects duplicate validate formats instead of silently choosing the last one", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-validate-format-"));
+    const path = join(root, "report.json");
+    await writeFile(path, JSON.stringify(report));
+    const io = capture();
+
+    expect(await runCli(["validate", path, "--format", "json", "--format=markdown"], io.dependencies)).toBe(1);
+    expect(io.stderr.join("")).toContain("Pass --format only once");
+  });
+
+  it("rejects a truncated non-empty report before validate or verify can crash", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-truncated-report-"));
+    const path = join(root, "report.json");
+    await writeFile(path, JSON.stringify({
+      reportVersion: 1,
+      contextFiles: [{ path: "src/reset.ts" }]
+    }));
+    const validateIo = capture();
+    const verifyIo = capture();
+
+    expect(await runCli(["validate", path], validateIo.dependencies)).toBe(1);
+    expect(validateIo.stderr.join("")).toContain("complete FixMap report envelope");
+    expect(await runCli(["verify", "--report", path, "--working-tree"], verifyIo.dependencies)).toBe(1);
+    expect(verifyIo.stderr.join("")).toContain("complete FixMap report envelope");
+    expect(verifyIo.stderr.join("")).not.toContain("Cannot read properties");
+  });
+
   it("does not let a nested version flag short-circuit the requested command", async () => {
     const io = capture();
     const exitCode = await runCli(["plan", "--version"], io.dependencies);
@@ -211,6 +252,15 @@ describe("CLI argument handling", () => {
     expect(parseArgs(["plan", "--issue", "x", "--format", " JSON\n"]).format).toBe("json");
   });
 
+  it("trims accidental whitespace around git refs", () => {
+    const parsed = parseArgs([
+      "plan", "--issue", "x", "--diff", " HEAD~1...HEAD\n", "--base", " main ", "--head", " feature "
+    ]);
+    expect(parsed.diffSpec).toBe("HEAD~1...HEAD");
+    expect(parsed.baseRef).toBe("main");
+    expect(parsed.headRef).toBe("feature");
+  });
+
   it("expands the home directory consistently for path options", () => {
     const parsed = parseArgs([
       "plan", "--issue", "x", "--repo", "~", "--output", "~/plan.json", "--compare", "~\\before.json"
@@ -328,6 +378,84 @@ describe("CLI argument handling", () => {
     expect(buildReport).toHaveBeenCalledWith(expect.objectContaining({ useCache: false }));
   });
 
+  it("applies --no-cache to the current scan in compare mode", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-compare-no-cache-"));
+    const previousPath = join(root, "previous.json");
+    await writeFile(previousPath, JSON.stringify(report));
+    const buildReport = vi.fn(async () => report);
+    const io = capture();
+
+    expect(await runCli([
+      "plan", "--issue", "reset fails", "--compare", previousPath, "--no-cache"
+    ], { ...io.dependencies, buildReport })).toBe(0);
+    expect(buildReport).toHaveBeenCalledWith(expect.objectContaining({ useCache: false }));
+  });
+
+  it("keeps its issue input and output report from ranking themselves", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-artifact-ranking-"));
+    await mkdir(join(root, "src"), { recursive: true });
+    const issuePath = join(root, "task.md");
+    const outputPath = join(root, "plan.json");
+    await writeFile(join(root, "src", "reset.ts"), "export function artifactShieldSignal() { return true; }\n");
+    await writeFile(issuePath, "artifactShieldSignal fails during password reset\n");
+    await writeFile(outputPath, JSON.stringify({ repeated: "artifactShieldSignal ".repeat(20) }));
+    const writes: string[] = [];
+    const io = capture();
+
+    expect(await runCli([
+      "plan", "--issue-file", issuePath, "--repo", root, "--format", "json", "--output", outputPath
+    ], {
+      ...io.dependencies,
+      writeReport: async (_path, contents) => { writes.push(contents); }
+    })).toBe(0);
+
+    const rendered = JSON.parse(writes[0]!) as FixMapReport;
+    expect(rendered.contextFiles.map((file) => file.path)).toContain("src/reset.ts");
+    expect(rendered.contextFiles.map((file) => file.path)).not.toContain("task.md");
+    expect(rendered.contextFiles.map((file) => file.path)).not.toContain("plan.json");
+    expect(rendered.diagnostics.map((entry) => entry.code)).not.toContain("paths-excluded");
+  });
+
+  it("passes every in-repository workflow artifact as an internal exclusion", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-artifact-inputs-"));
+    const issuePath = join(root, "task.md");
+    const baselinePath = join(root, "baseline.json");
+    const outputPath = join(root, "comparison.json");
+    await writeFile(issuePath, "reset fails\n");
+    await writeFile(baselinePath, JSON.stringify(report));
+    const buildReport = vi.fn(async () => report);
+    const io = capture();
+
+    expect(await runCli([
+      "plan", "--issue-file", issuePath, "--repo", root,
+      "--compare", baselinePath, "--format", "json", "--output", outputPath
+    ], {
+      ...io.dependencies,
+      buildReport,
+      writeReport: vi.fn(async () => undefined)
+    })).toBe(0);
+
+    expect(buildReport).toHaveBeenCalledWith(expect.objectContaining({
+      internalExclude: expect.arrayContaining([issuePath, baselinePath, outputPath])
+    }));
+  });
+
+  it("writes an explanation to --output instead of silently printing it", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-explain-output-"));
+    const outputPath = join(root, "explanation.json");
+    await writeFile(join(root, "reset.ts"), "export function sendPasswordReset() { return true; }\n");
+    const writeReport = vi.fn(async () => undefined);
+    const io = capture();
+
+    expect(await runCli([
+      "plan", "--issue", "password reset fails", "--repo", root,
+      "--explain", "reset.ts", "--format", "json", "--output", outputPath
+    ], { ...io.dependencies, writeReport })).toBe(0);
+
+    expect(io.stdout).toEqual([]);
+    expect(writeReport).toHaveBeenCalledWith(outputPath, expect.stringContaining('"status": "ranked"'));
+  });
+
   it.each([
     ["--repo", ["plan", "--issue", "x", "--repo", ".", "--repo", "examples/tiny-auth-app"]],
     ["--format", ["plan", "--issue", "x", "--format", "markdown", "--format", "json"]],
diff --git a/packages/cli/test/mcp.test.ts b/packages/cli/test/mcp.test.ts
index aaf35a9..94f5d15 100644
--- a/packages/cli/test/mcp.test.ts
+++ b/packages/cli/test/mcp.test.ts
@@ -317,8 +317,25 @@ describe("fixmap mcp server", () => {
 
     expect(result.isError).toBeFalsy();
     const text = (result.content as Array<{ type: string; text: string }>)[0]?.text ?? "";
-    expect((JSON.parse(text) as { changedFiles: string[] }).changedFiles)
-      .toContain("src/auth/reset-password.ts");
+    const changedFiles = (JSON.parse(text) as { changedFiles: string[] }).changedFiles;
+    expect(changedFiles).toContain("src/auth/reset-password.ts");
+    expect(changedFiles).not.toContain("plan.json");
+  });
+
+  it("rejects a truncated non-empty verify report with a structural error", async () => {
+    const client = await connectClient();
+    const result = await client.callTool({
+      name: "fixmap_verify",
+      arguments: {
+        report: { reportVersion: 1, contextFiles: [{ path: "src/auth/reset-password.ts" }] },
+        diff: "HEAD"
+      }
+    });
+
+    expect(result.isError).toBe(true);
+    const text = (result.content as Array<{ text: string }>)[0]?.text ?? "";
+    expect(text).toContain("complete FixMap report envelope");
+    expect(text).not.toContain("Cannot read properties");
   });
 
   it("says why a report path did not work instead of only naming the object shape", async () => {
diff --git a/packages/core/src/plan.ts b/packages/core/src/plan.ts
index f990958..6a98a6b 100644
--- a/packages/core/src/plan.ts
+++ b/packages/core/src/plan.ts
@@ -10,10 +10,19 @@ export async function buildFixMapReport(
   input: Pick<
     FixMapInput,
     "repoRoot" | "issueText" | "diffSpec" | "baseRef" | "headRef" | "workingTree" | "includeUntracked" | "useCache"
-  > & { limit?: number | undefined; exclude?: string[] | undefined }
+  > & {
+    limit?: number | undefined;
+    exclude?: string[] | undefined;
+    /** Known command artifacts that must not compete with repository files in ranking. */
+    internalExclude?: string[] | undefined;
+  }
 ): Promise<FixMapReport> {
   const repo = await scanRepo(input);
-  const exclude = await resolveExclusions(input.repoRoot, input.exclude ?? []);
+  const requestedExclude = await resolveExclusions(input.repoRoot, input.exclude ?? []);
+  const internalExclude = buildPathExcluder(
+    (input.internalExclude ?? []).map((pattern) => normalizeAbsolutePattern(input.repoRoot, pattern))
+  );
+  const exclude = combineExclusions(requestedExclude, internalExclude);
 
   const report = buildReportFromRepo(repo, {
     issueText: input.issueText,
@@ -21,10 +30,10 @@ export async function buildFixMapReport(
     exclude
   });
 
-  if (exclude.patterns.length > 0) {
-    const excludedPaths = repo.files.filter((file) => exclude.excludes(file.path)).map((file) => file.path);
-    const unmatchedPatterns = exclude.patterns.filter((pattern) =>
-      !pattern.startsWith("!") && !exclude.matchedPatterns.has(pattern)
+  if (requestedExclude.patterns.length > 0) {
+    const excludedPaths = repo.files.filter((file) => requestedExclude.excludes(file.path)).map((file) => file.path);
+    const unmatchedPatterns = requestedExclude.patterns.filter((pattern) =>
+      !pattern.startsWith("!") && !requestedExclude.matchedPatterns.has(pattern)
     );
     if (unmatchedPatterns.length > 0) {
       const sample = unmatchedPatterns.slice(0, 5).join(", ");
@@ -41,8 +50,8 @@ export async function buildFixMapReport(
         code: "paths-excluded",
         severity: report.contextFiles.length === 0 ? "warning" : "info",
         message:
-          `${exclude.patterns.length} exclusion ${exclude.patterns.length === 1 ? "pattern" : "patterns"} ` +
-          `removed ${excludedPaths.length} ${excludedPaths.length === 1 ? "path" : "paths"} from ranking: ${exclude.patterns.join(", ")}. ` +
+          `${requestedExclude.patterns.length} exclusion ${requestedExclude.patterns.length === 1 ? "pattern" : "patterns"} ` +
+          `removed ${excludedPaths.length} ${excludedPaths.length === 1 ? "path" : "paths"} from ranking: ${requestedExclude.patterns.join(", ")}. ` +
           "Run --explain on a file you expected to see if this is why it is absent."
       });
     }
@@ -51,6 +60,17 @@ export async function buildFixMapReport(
   return report;
 }
 
+function combineExclusions(primary: PathExcluder, internal: PathExcluder): PathExcluder {
+  if (internal.patterns.length === 0) return primary;
+  if (primary.patterns.length === 0) return internal;
+  return {
+    excludes: (path) => primary.excludes(path) || internal.excludes(path),
+    reasonFor: (path) => primary.reasonFor(path) ?? internal.reasonFor(path),
+    patterns: [...primary.patterns, ...internal.patterns],
+    matchedPatterns: new Set([...primary.matchedPatterns, ...internal.matchedPatterns])
+  };
+}
+
 /**
  * Command-line exclusions and `.fixmapignore` combine rather than override. A repository
  * that ships an ignore file has said something durable about itself; a flag is one run's
diff --git a/packages/core/src/repo-scan.ts b/packages/core/src/repo-scan.ts
index 742d5ca..733ac4e 100644
--- a/packages/core/src/repo-scan.ts
+++ b/packages/core/src/repo-scan.ts
@@ -2,7 +2,7 @@ import { execFile } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, extname, join, relative, resolve, sep } from "node:path";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { ALWAYS_IGNORED_DIRS, GENERATED_DIRS, isGeneratedPath } from "./paths.js";
 import { DIAGNOSTIC_SPEC_LIMIT, truncateForDiagnostic } from "./text.js";
@@ -74,7 +74,7 @@ export async function scanRepo(
   input: Pick<
     FixMapInput,
     "repoRoot" | "baseRef" | "headRef" | "diffSpec" | "workingTree" | "includeUntracked" | "useCache"
-  >
+  > & { internalExclude?: string[] | undefined }
 ): Promise<RepoMap> {
   const repoRoot = resolve(input.repoRoot);
   if (!(await isDirectory(repoRoot))) {
@@ -94,7 +94,14 @@ export async function scanRepo(
   }
 
   const diagnostics: RepoMap["diagnostics"] = [];
-  const cacheDecision = input.useCache === true ? await buildScanCacheLocation(repoRoot) : undefined;
+  const internalPaths = await resolveInternalPaths(repoRoot, input.internalExclude ?? []);
+  const cacheRoot = configuredScanCacheRoot();
+  const internalCacheRoot = sameFilesystemPath(cacheRoot, repoRoot) || containedPath(repoRoot, cacheRoot) !== undefined
+    ? cacheRoot
+    : undefined;
+  const cacheDecision = input.useCache === true
+    ? await buildScanCacheLocation(repoRoot, cacheRoot, internalPaths)
+    : undefined;
   const cacheLocation = cacheDecision?.location;
   if (input.useCache === false) {
     diagnostics.push({
@@ -125,8 +132,8 @@ export async function scanRepo(
       message: `Reused the repository scan for the exact current git state (${files.length.toLocaleString()} files, ${describeCacheAge(cached.createdAt)}). Pass --no-cache to rescan.`
     });
   } else {
-    files = await listFiles(repoRoot, diagnostics);
-    trackedFiles = await listTrackedPaths(repoRoot);
+    files = await listFiles(repoRoot, diagnostics, internalCacheRoot, internalPaths);
+    trackedFiles = await listTrackedPaths(repoRoot, internalPaths);
     packageScripts = await readPackageScripts(repoRoot, files, diagnostics);
     packageManager = detectPackageManager(files);
     if (cacheLocation) {
@@ -144,8 +151,8 @@ export async function scanRepo(
   }
   const diffSpec = resolveDiffSpec(input);
   const diff = input.workingTree
-    ? await readWorkingTree(repoRoot, input.includeUntracked === true, diagnostics)
-    : await readDiff(repoRoot, diffSpec, diagnostics);
+    ? await readWorkingTree(repoRoot, input.includeUntracked === true, diagnostics, internalPaths)
+    : await readDiff(repoRoot, diffSpec, diagnostics, internalPaths);
 
   return {
     root: repoRoot,
@@ -162,11 +169,72 @@ export async function scanRepo(
 type ScanCacheLocation = { path: string; stateKey: string };
 type ScanCacheDecision = { location?: ScanCacheLocation; skipReason?: string };
 
-async function buildScanCacheLocation(root: string): Promise<ScanCacheDecision> {
+function configuredScanCacheRoot(): string {
+  return resolve(process.env.FIXMAP_CACHE_DIR ?? join(
+    process.env.LOCALAPPDATA ?? process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"),
+    "fixmap",
+    "scans"
+  ));
+}
+
+function containedPath(root: string, candidate: string): string | undefined {
+  const distance = relative(root, candidate);
+  return distance === "" || distance === ".." || distance.startsWith(`..${sep}`) || isAbsolute(distance)
+    ? undefined
+    : normalizePath(distance);
+}
+
+async function resolveInternalPaths(root: string, paths: string[]): Promise<Set<string>> {
+  const requested = paths.flatMap((path) => {
+    const relativePath = containedPath(root, resolve(path));
+    return relativePath ? [relativePath] : [];
+  });
+  if (requested.length === 0 || process.platform !== "win32") return new Set(requested);
+
+  // Git pathspecs remain case-sensitive even on a case-insensitive Windows worktree. A
+  // caller can open PLAN.JSON when the directory entry is plan.json, so recover Git's
+  // canonical spelling before using exact exclusions in status and diff commands.
+  try {
+    const { stdout } = await exec(
+      "git",
+      ["ls-files", "--cached", "--others", "--exclude-standard", "-z"],
+      { cwd: root, maxBuffer: GIT_MAX_BUFFER }
+    );
+    const repositoryPaths = stdout.split("\0").filter(Boolean).map(normalizePath);
+    return new Set(requested.map((path) =>
+      repositoryPaths.find((candidate) => sameFilesystemPath(candidate, path)) ?? path
+    ));
+  } catch {
+    return new Set(requested);
+  }
+}
+
+function hasInternalPath(paths: ReadonlySet<string>, path: string): boolean {
+  return [...paths].some((candidate) => sameFilesystemPath(candidate, path));
+}
+
+function gitPathspec(internalPaths: ReadonlySet<string>): string[] {
+  return ["--", ".", ...[...internalPaths]
+    .sort((a, b) => a.localeCompare(b))
+    .map((path) => `:(exclude,literal)${path}`)];
+}
+
+async function buildScanCacheLocation(
+  root: string,
+  cacheRoot: string,
+  internalPaths: ReadonlySet<string>
+): Promise<ScanCacheDecision> {
+  if (sameFilesystemPath(cacheRoot, root) || containedPath(root, cacheRoot) !== undefined) {
+    return {
+      skipReason:
+        "Repository scan caching was skipped because FIXMAP_CACHE_DIR is inside the scanned repository. " +
+        "Move the cache outside the repository to enable exact-state reuse."
+    };
+  }
   try {
     const [{ stdout: head }, { stdout: status }] = await Promise.all([
       exec("git", ["rev-parse", "HEAD"], { cwd: root, maxBuffer: GIT_MAX_BUFFER }),
-      exec("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--", "."], {
+      exec("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all", ...gitPathspec(internalPaths)], {
         cwd: root,
         maxBuffer: GIT_MAX_BUFFER
       })
@@ -179,7 +247,7 @@ async function buildScanCacheLocation(root: string): Promise<ScanCacheDecision>
       };
     }
     const dirtyDiff = status.length > 0
-      ? (await exec("git", ["diff", "--binary", "--no-ext-diff", "HEAD", "--", "."], {
+      ? (await exec("git", ["diff", "--binary", "--no-ext-diff", "HEAD", ...gitPathspec(internalPaths)], {
           cwd: root,
           maxBuffer: GIT_MAX_BUFFER
         })).stdout
@@ -189,13 +257,9 @@ async function buildScanCacheLocation(root: string): Promise<ScanCacheDecision>
       resolve(root),
       head.trim(),
       status,
-      dirtyDiff
+      dirtyDiff,
+      ...[...internalPaths].sort((a, b) => a.localeCompare(b))
     ].join("\0"));
-    const cacheRoot = process.env.FIXMAP_CACHE_DIR ?? join(
-      process.env.LOCALAPPDATA ?? process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"),
-      "fixmap",
-      "scans"
-    );
     return { location: {
       path: join(cacheRoot, `${hashText(resolve(root))}-${stateKey}.json`),
       stateKey
@@ -282,14 +346,15 @@ function hashText(value: string): string {
   return createHash("sha256").update(value).digest("hex").slice(0, 24);
 }
 
-async function listTrackedPaths(root: string): Promise<string[]> {
+async function listTrackedPaths(root: string, internalPaths: ReadonlySet<string>): Promise<string[]> {
   try {
     const { stdout } = await exec(
       "git",
       ["ls-files", "--cached", "-z"],
       { cwd: root, maxBuffer: GIT_MAX_BUFFER }
     );
-    return stdout.split("\0").filter(Boolean).map(normalizePath);
+    return stdout.split("\0").filter(Boolean).map(normalizePath)
+      .filter((path) => !hasInternalPath(internalPaths, path));
   } catch {
     return [];
   }
@@ -299,11 +364,19 @@ function resolveDiffSpec(input: Pick<FixMapInput, "baseRef" | "headRef" | "diffS
   return input.diffSpec ?? (input.baseRef ? `${input.baseRef}...${input.headRef ?? "HEAD"}` : undefined);
 }
 
-async function listFiles(root: string, diagnostics: RepoMap["diagnostics"]): Promise<RepoFile[]> {
+async function listFiles(
+  root: string,
+  diagnostics: RepoMap["diagnostics"],
+  internalCacheRoot: string | undefined,
+  internalPaths: ReadonlySet<string>
+): Promise<RepoFile[]> {
   const gitPaths = await listGitPaths(root);
+  const visiblePaths = gitPaths?.paths.filter((path) =>
+    !hasInternalPath(internalPaths, normalizePath(path)) && !isInternalCachePath(root, path, internalCacheRoot)
+  );
   const files = gitPaths
-    ? await buildFilesFromPaths(root, gitPaths.paths, diagnostics, gitPaths.gitLinks)
-    : (await walkFiles(root, root, diagnostics, { count: 0, limitReported: false }))
+    ? await buildFilesFromPaths(root, visiblePaths ?? [], diagnostics, gitPaths.gitLinks)
+    : (await walkFiles(root, root, diagnostics, { count: 0, limitReported: false }, internalCacheRoot, internalPaths))
       .sort((a, b) => a.path.localeCompare(b.path));
 
   // These are properties of the scanned files, not of git. Keeping them here makes an
@@ -313,6 +386,22 @@ async function listFiles(root: string, diagnostics: RepoMap["diagnostics"]): Pro
   return files;
 }
 
+function isInternalCachePath(root: string, path: string, internalCacheRoot?: string): boolean {
+  if (!internalCacheRoot) return false;
+  const relativeCacheRoot = containedPath(root, internalCacheRoot);
+  if (relativeCacheRoot) {
+    const candidate = process.platform === "win32" ? path.toLowerCase() : path;
+    const cachePath = process.platform === "win32" ? relativeCacheRoot.toLowerCase() : relativeCacheRoot;
+    return candidate === cachePath || candidate.startsWith(`${cachePath}/`);
+  }
+  // If someone points FIXMAP_CACHE_DIR at the repository root itself, do not hide the
+  // repository. Hide only filenames owned by FixMap's cache format.
+  return sameFilesystemPath(internalCacheRoot, root) && (
+    SCAN_CACHE_FILE.test(path) ||
+    /^[a-f0-9]{24}-[a-f0-9]{24}\.json\.\d+-[0-9a-f-]+\.tmp$/i.test(path)
+  );
+}
+
 async function listGitPaths(root: string): Promise<{ paths: string[]; gitLinks: Set<string> } | undefined> {
   try {
     const [{ stdout }, { stdout: staged }] = await Promise.all([
@@ -548,7 +637,9 @@ async function walkFiles(
   root: string,
   current: string,
   diagnostics: RepoMap["diagnostics"],
-  state: ScanState
+  state: ScanState,
+  internalCacheRoot: string | undefined,
+  internalPaths: ReadonlySet<string>
 ): Promise<RepoFile[]> {
   let entries;
   try {
@@ -570,7 +661,9 @@ async function walkFiles(
       if (WALK_IGNORED_DIRS.has(entry.name)) {
         continue;
       }
-      results.push(...await walkFiles(root, join(current, entry.name), diagnostics, state));
+      const directory = join(current, entry.name);
+      if (internalCacheRoot && sameFilesystemPath(directory, internalCacheRoot)) continue;
+      results.push(...await walkFiles(root, directory, diagnostics, state, internalCacheRoot, internalPaths));
       continue;
     }
 
@@ -579,7 +672,9 @@ async function walkFiles(
     }
 
     const absolutePath = join(current, entry.name);
-    const scanned = await toRepoFile(absolutePath, normalizePath(relative(root, absolutePath)));
+    const relativePath = normalizePath(relative(root, absolutePath));
+    if (hasInternalPath(internalPaths, relativePath) || isInternalCachePath(root, relativePath, internalCacheRoot)) continue;
+    const scanned = await toRepoFile(absolutePath, relativePath);
     if (scanned.status === "ok") {
       results.push(scanned.file);
       state.count += 1;
@@ -769,7 +864,8 @@ function decodeManifest(bytes: Buffer): { text: string; encoding: string } {
 async function readDiff(
   repoRoot: string,
   diffSpec: string | undefined,
-  diagnostics: RepoMap["diagnostics"]
+  diagnostics: RepoMap["diagnostics"],
+  internalPaths: ReadonlySet<string>
 ): Promise<{ changedFiles: string[]; diffText: string }> {
   if (!diffSpec) {
     return { changedFiles: [], diffText: "" };
@@ -777,15 +873,15 @@ async function readDiff(
 
   try {
     const [{ stdout: names }, { stdout: diffText }] = await Promise.all([
-      exec("git", ["diff", "--relative", "--name-only", diffSpec], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
-      exec("git", ["diff", "--relative", diffSpec], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER })
+      exec("git", ["diff", "--relative", "--name-only", diffSpec, ...gitPathspec(internalPaths)], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
+      exec("git", ["diff", "--relative", diffSpec, ...gitPathspec(internalPaths)], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER })
     ]);
     const tracked = names
       .split(/\r?\n/)
       .map((path) => path.trim())
       .filter(Boolean)
       .map(normalizePath);
-    const untracked = diffSpec.includes("..") ? [] : await listUntrackedPaths(repoRoot);
+    const untracked = diffSpec.includes("..") ? [] : await listUntrackedPaths(repoRoot, internalPaths);
     const changedFiles = [...new Set([...tracked, ...untracked])].sort((a, b) => a.localeCompare(b));
     diagnostics.push({
       code: "diff-resolved",
@@ -827,19 +923,20 @@ async function readDiff(
 async function readWorkingTree(
   repoRoot: string,
   includeUntracked: boolean,
-  diagnostics: RepoMap["diagnostics"]
+  diagnostics: RepoMap["diagnostics"],
+  internalPaths: ReadonlySet<string>
 ): Promise<{ changedFiles: string[]; diffText: string }> {
   try {
     const [{ stdout: names }, { stdout: diffText }] = await Promise.all([
-      exec("git", ["diff", "--relative", "--name-only", "HEAD"], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
-      exec("git", ["diff", "--relative", "HEAD"], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER })
+      exec("git", ["diff", "--relative", "--name-only", "HEAD", ...gitPathspec(internalPaths)], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
+      exec("git", ["diff", "--relative", "HEAD", ...gitPathspec(internalPaths)], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER })
     ]);
     const tracked = names
       .split(/\r?\n/)
       .map((path) => path.trim())
       .filter(Boolean)
       .map(normalizePath);
-    const untracked = includeUntracked ? await listUntrackedPaths(repoRoot) : [];
+    const untracked = includeUntracked ? await listUntrackedPaths(repoRoot, internalPaths) : [];
     const changedFiles = [...new Set([...tracked, ...untracked])].sort((a, b) => a.localeCompare(b));
 
     diagnostics.push({
@@ -960,14 +1057,18 @@ async function readTextSample(
   }
 }
 
-async function listUntrackedPaths(repoRoot: string): Promise<string[]> {
+async function listUntrackedPaths(
+  repoRoot: string,
+  internalPaths: ReadonlySet<string> = new Set<string>()
+): Promise<string[]> {
   try {
     const { stdout } = await exec(
       "git",
       ["ls-files", "--others", "--exclude-standard", "-z"],
       { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }
     );
-    return stdout.split("\0").filter(Boolean).map(normalizePath);
+    return stdout.split("\0").filter(Boolean).map(normalizePath)
+      .filter((path) => !hasInternalPath(internalPaths, path));
   } catch {
     return [];
   }
diff --git a/packages/core/src/validate.ts b/packages/core/src/validate.ts
index 13a3ced..9a4d9d8 100644
--- a/packages/core/src/validate.ts
+++ b/packages/core/src/validate.ts
@@ -26,24 +26,6 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
       message: `${label} uses unsupported reportVersion ${JSON.stringify(record.reportVersion)}; this FixMap release supports reportVersion 1.`
     };
   }
-  if (
-    contextFiles.length === 0 &&
-    !(
-      typeof record.summary === "string" &&
-      Array.isArray(record.testRoutes) &&
-      Array.isArray(record.risks) &&
-      Array.isArray(record.changedFiles) &&
-      Array.isArray(record.diagnostics)
-    )
-  ) {
-    return {
-      success: false,
-      message:
-        `${label} has no context files and is missing the complete FixMap report envelope ` +
-        "(summary, testRoutes, risks, changedFiles, and diagnostics)."
-    };
-  }
-
   const invalid = contextFiles.findIndex((file) => {
     if (typeof file !== "object" || file === null) return true;
     const ranked = file as unknown as Record<string, unknown>;
@@ -65,5 +47,70 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
     };
   }
 
+  const invalidEnvelopeFields = [
+    typeof record.summary === "string" ? undefined : "summary (string)",
+    Array.isArray(record.testRoutes) ? undefined : "testRoutes (array)",
+    Array.isArray(record.risks) ? undefined : "risks (array)",
+    Array.isArray(record.changedFiles) ? undefined : "changedFiles (array)",
+    Array.isArray(record.diagnostics) ? undefined : "diagnostics (array)"
+  ].filter((field): field is string => field !== undefined);
+  if (invalidEnvelopeFields.length > 0) {
+    return {
+      success: false,
+      message:
+        `${label} is missing or has invalid fields in the complete FixMap report envelope: ` +
+        `${invalidEnvelopeFields.join(", ")}.`
+    };
+  }
+
+  const testRoutes = record.testRoutes as unknown[];
+  const invalidRoute = testRoutes.findIndex((route) => {
+    if (typeof route !== "object" || route === null || Array.isArray(route)) return true;
+    const entry = route as Record<string, unknown>;
+    return typeof entry.command !== "string" ||
+      !Array.isArray(entry.relatedFiles) ||
+      !entry.relatedFiles.every((path) => typeof path === "string");
+  });
+  if (invalidRoute !== -1) {
+    return {
+      success: false,
+      message:
+        `${label} has an invalid testRoutes entry at index ${invalidRoute}; each route needs a string "command" ` +
+        "and a string array named relatedFiles."
+    };
+  }
+
+  const risks = record.risks as unknown[];
+  const invalidRisk = risks.findIndex((risk) => {
+    if (typeof risk !== "object" || risk === null || Array.isArray(risk)) return true;
+    return typeof (risk as Record<string, unknown>).area !== "string";
+  });
+  if (invalidRisk !== -1) {
+    return {
+      success: false,
+      message: `${label} has an invalid risks entry at index ${invalidRisk}; each risk needs a string "area".`
+    };
+  }
+
+  if (!(record.changedFiles as unknown[]).every((path) => typeof path === "string")) {
+    return { success: false, message: `${label} has invalid changedFiles; every entry must be a string path.` };
+  }
+
+  if (record.analysis !== undefined) {
+    const analysis = record.analysis;
+    const grounding = typeof analysis === "object" && analysis !== null && !Array.isArray(analysis)
+      ? (analysis as Record<string, unknown>).grounding
+      : undefined;
+    const specificity = typeof grounding === "object" && grounding !== null && !Array.isArray(grounding)
+      ? (grounding as Record<string, unknown>).specificity
+      : undefined;
+    if (specificity !== "anchored" && specificity !== "descriptive" && specificity !== "vague") {
+      return {
+        success: false,
+        message: `${label} has invalid analysis.grounding.specificity; expected anchored, descriptive, or vague.`
+      };
+    }
+  }
+
   return { success: true, report: candidate as FixMapReport };
 }
diff --git a/packages/core/test/repo-scan.test.ts b/packages/core/test/repo-scan.test.ts
index 5d36113..eb897e3 100644
--- a/packages/core/test/repo-scan.test.ts
+++ b/packages/core/test/repo-scan.test.ts
@@ -538,6 +538,86 @@ describe("scanRepo", () => {
     }
   });
 
+  it("never scans a configured cache directory inside the repository", { timeout: 30_000 }, async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-cache-inside-repo-"));
+    const cacheRoot = join(root, ".fixmap-cache");
+    const previousCache = process.env.FIXMAP_CACHE_DIR;
+    process.env.FIXMAP_CACHE_DIR = cacheRoot;
+    try {
+      await mkdir(cacheRoot, { recursive: true });
+      await writeFile(join(root, "index.ts"), "export const passwordReset = true;\n");
+      await writeFile(
+        join(cacheRoot, "aaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbbbbbbbbbb.json"),
+        JSON.stringify({ repeated: "password reset password reset password reset" })
+      );
+      await exec("git", ["init", "-b", "main"], { cwd: root });
+      await exec("git", ["config", "user.email", "test@example.com"], { cwd: root });
+      await exec("git", ["config", "user.name", "Test User"], { cwd: root });
+      await exec("git", ["add", "index.ts"], { cwd: root });
+      await exec("git", ["commit", "-m", "initial"], { cwd: root });
+
+      const cached = await scanRepo({ repoRoot: root, useCache: true });
+      expect(cached.files.map((file) => file.path)).toEqual(["index.ts"]);
+      expect(cached.diagnostics.find((entry) => entry.code === "cache-skip")?.message)
+        .toContain("FIXMAP_CACHE_DIR is inside");
+
+      const bypassed = await scanRepo({ repoRoot: root, useCache: false });
+      expect(bypassed.files.map((file) => file.path)).toEqual(["index.ts"]);
+      expect(bypassed.diagnostics.map((entry) => entry.code)).toContain("cache-bypass");
+    } finally {
+      if (previousCache === undefined) delete process.env.FIXMAP_CACHE_DIR;
+      else process.env.FIXMAP_CACHE_DIR = previousCache;
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps exact workflow artifacts out of files, diffs, and cache invalidation", { timeout: 30_000 }, async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-internal-artifacts-"));
+    const cacheRoot = await mkdtemp(join(tmpdir(), "fixmap-internal-artifact-cache-"));
+    const previousCache = process.env.FIXMAP_CACHE_DIR;
+    process.env.FIXMAP_CACHE_DIR = cacheRoot;
+    try {
+      const sourcePath = join(root, "index.ts");
+      const issuePath = join(root, "task.md");
+      const reportPath = join(root, "plan.json");
+      await writeFile(sourcePath, "export const passwordReset = 'one';\n");
+      await exec("git", ["init", "-b", "main"], { cwd: root });
+      await exec("git", ["config", "user.email", "test@example.com"], { cwd: root });
+      await exec("git", ["config", "user.name", "Test User"], { cwd: root });
+      await exec("git", ["add", "index.ts"], { cwd: root });
+      await exec("git", ["commit", "-m", "initial"], { cwd: root });
+      await writeFile(issuePath, "password reset password reset\n");
+      await writeFile(reportPath, JSON.stringify({ repeated: "password reset password reset" }));
+
+      const internalExclude = process.platform === "win32"
+        ? [issuePath, reportPath].map((path) => path.toUpperCase())
+        : [issuePath, reportPath];
+      const first = await scanRepo({ repoRoot: root, useCache: true, internalExclude });
+      expect(first.files.map((file) => file.path)).toEqual(["index.ts"]);
+      expect(first.diagnostics.map((entry) => entry.code)).not.toContain("cache-skip");
+      expect((await scanRepo({ repoRoot: root, useCache: true, internalExclude })).diagnostics.map((entry) => entry.code))
+        .toContain("cache-hit");
+
+      await writeFile(sourcePath, "export const passwordReset = 'two';\n");
+      await writeFile(reportPath, JSON.stringify({ repeated: "changed report contents" }));
+      const working = await scanRepo({
+        repoRoot: root,
+        workingTree: true,
+        includeUntracked: true,
+        useCache: true,
+        internalExclude
+      });
+      expect(working.files.map((file) => file.path)).toEqual(["index.ts"]);
+      expect(working.changedFiles).toEqual(["index.ts"]);
+      expect(working.diffText).not.toContain("changed report contents");
+    } finally {
+      if (previousCache === undefined) delete process.env.FIXMAP_CACHE_DIR;
+      else process.env.FIXMAP_CACHE_DIR = previousCache;
+      await rm(cacheRoot, { recursive: true, force: true });
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
   it("does not reuse a staged scan after the same edit becomes unstaged", { timeout: 30_000 }, async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-cache-stage-state-"));
     const cacheRoot = await mkdtemp(join(tmpdir(), "fixmap-cache-stage-store-"));
diff --git a/packages/core/test/validate.test.ts b/packages/core/test/validate.test.ts
index 196bbe9..0edeff5 100644
--- a/packages/core/test/validate.test.ts
+++ b/packages/core/test/validate.test.ts
@@ -33,4 +33,30 @@ describe("validateFixMapReport", () => {
     expect(result.success).toBe(false);
     if (!result.success) expect(result.message).toContain("complete FixMap report envelope");
   });
+
+  it("rejects a non-empty context list when the rest of the report envelope is truncated", () => {
+    const result = validateFixMapReport({
+      reportVersion: 1,
+      contextFiles: [{ path: "src/reset.ts" }]
+    }, "report");
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.message).toContain("complete FixMap report envelope");
+      expect(result.message).toContain("testRoutes");
+      expect(result.message).toContain("risks");
+    }
+  });
+
+  it.each([
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], testRoutes: [null] }, "testRoutes entry"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], testRoutes: [{ command: "npm test" }] }, "relatedFiles"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], risks: [null] }, "risks entry"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], changedFiles: [42] }, "changedFiles"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], analysis: {} }, "analysis.grounding.specificity"]
+  ])("rejects consumer-unsafe nested report data: %s", (candidate, message) => {
+    const result = validateFixMapReport(candidate, "report");
+    expect(result.success).toBe(false);
+    if (!result.success) expect(result.message).toContain(message);
+  });
 });

From af732e3600f62b60b8981d06959f5a2c22e2a4f0 Mon Sep 17 00:00:00 2001
From: Aryam Goyal <aryamgoyal18@gmail.com>
Date: Sun, 9 Aug 2026 15:27:16 +0530
Subject: [PATCH 04/10] Harden unreleased cross-surface workflows

---
 README.md                                     |   4 +-
 action.yml                                    |   4 +
 .../app/_components/interactive-map-stage.tsx |  50 ++++++++-
 apps/web/app/demo.tsx                         |  17 ++-
 apps/web/app/get-started/page.tsx             |   8 +-
 apps/web/app/globals.css                      |   1 +
 packages/action/action.yml                    |   4 +
 packages/action/dist/index.mjs                |  96 ++++++++++++----
 packages/action/src/runner.ts                 |   8 +-
 packages/action/test/runner.test.ts           |  24 ++++
 packages/cli/README.md                        |   2 +-
 packages/cli/src/agent-setup.ts               |   2 +-
 packages/cli/src/cli-runner.ts                |   9 +-
 packages/cli/src/mcp.ts                       |  55 +++++++---
 packages/cli/test/cli-runner.test.ts          |  11 ++
 packages/cli/test/mcp.test.ts                 |  60 +++++++++-
 packages/core/src/compare.ts                  |  30 +++--
 packages/core/src/repo-scan.ts                |  49 ++++++++-
 packages/core/src/validate.ts                 | 103 ++++++++++++++----
 packages/core/test/compare.test.ts            |  19 ++++
 packages/core/test/repo-scan.test.ts          |  67 +++++++++++-
 packages/core/test/validate.test.ts           |  32 +++++-
 22 files changed, 562 insertions(+), 93 deletions(-)

diff --git a/README.md b/README.md
index 1fb1619..b0d7423 100644
--- a/README.md
+++ b/README.md
@@ -85,7 +85,7 @@ Use `--working-tree` for staged and unstaged tracked edits, `--include-untracked
 - Normalizes supported browser and GitHub API issue URLs, including `www`, query strings, and fragments, while rejecting credentials, lookalike hosts, ports, and unsafe encoded paths.
 - Scans the current checkout, another local path, a `file://` URL, or an isolated checkout of a public GitHub repository.
 - Maps `--diff <spec>`, `--base`/`--head`, or the current `--working-tree`; untracked changes remain opt-in with `--include-untracked`.
-- Reuses repository scans only when the repository root, commit, status, and binary diff are identical. `cache-hit` reports reuse and scan age, entries expire after seven days, `--no-cache` reports a fresh bypass, and `FIXMAP_CACHE_DIR` moves the OS cache.
+- Reuses repository scans only when the repository root, commit, status, and binary diff are identical. `cache-hit` reports reuse and scan age, entries expire after seven days, and `FIXMAP_CACHE_DIR` moves the OS cache. Force a fresh scan with CLI `--no-cache`, MCP `noCache: true`, or Action `no-cache: true`.
 - Keeps the current `--issue-file`, `--compare`, `--report`, and `--output` artifacts out of repository ranking, change detection, and cache invalidation, so FixMap never recommends its own report as the fix site.
 - Detects npm, pnpm, Yarn, and Bun projects and reads the scripts declared by each workspace package.
 
@@ -187,7 +187,7 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-The Action writes the complete report to the job summary and maintains one pull-request comment. Its checked-in bundle and metadata are release-gated.
+The Action writes the complete report to the job summary and maintains one pull-request comment. Set `no-cache: true` when a workflow must bypass the exact-state scan cache. Its checked-in bundle and metadata are release-gated.
 
 ## JSON compatibility
 
diff --git a/action.yml b/action.yml
index eb771cb..7fa9ac9 100644
--- a/action.yml
+++ b/action.yml
@@ -46,6 +46,10 @@ inputs:
     description: With working-tree, include untracked files.
     required: false
     default: "false"
+  no-cache:
+    description: Bypass the exact-state repository scan cache and perform a fresh scan.
+    required: false
+    default: "false"
   format:
     description: >-
       Output format. JSON is posted as a fenced JSON pull-request comment, and the step
diff --git a/apps/web/app/_components/interactive-map-stage.tsx b/apps/web/app/_components/interactive-map-stage.tsx
index def8bf8..0b7240a 100644
--- a/apps/web/app/_components/interactive-map-stage.tsx
+++ b/apps/web/app/_components/interactive-map-stage.tsx
@@ -15,6 +15,7 @@ type StageKey = "files" | "checks" | "risks";
 type Example = {
   label: string;
   issue: string;
+  keywords: string[];
   files: [string, string, string];
   checks: [string, string, string];
   risks: [string, string, string];
@@ -24,6 +25,7 @@ const examples: Example[] = [
   {
     label: "Expiring reset links",
     issue: "Password reset links expire too early",
+    keywords: ["auth", "email", "expire", "link", "password", "reset", "token"],
     files: ["src/features/auth/reset/request.ts", "src/features/auth/reset/token-service.ts", "src/lib/email/templates/reset.ts"],
     checks: ["Token expiration logic", "Reset token integration tests", "Email link TTL configuration"],
     risks: ["Clock and timezone boundary", "Cached authentication config", "Email client link prefetch"]
@@ -31,6 +33,7 @@ const examples: Example[] = [
   {
     label: "Wrong invoice time zone",
     issue: "Invoices show the wrong time after daylight saving changes",
+    keywords: ["date", "daylight", "dst", "invoice", "time", "timezone"],
     files: ["src/timezone/resolve.ts", "src/invoices/summary.ts", "src/timezone/index.ts"],
     checks: ["Timezone conversion tests", "DST boundary cases", "Invoice rendering path"],
     risks: ["Cached timezone offsets", "External API assumptions", "Off-by-one date handling"]
@@ -38,6 +41,7 @@ const examples: Example[] = [
   {
     label: "Duplicate webhook event",
     issue: "Payment webhooks sometimes create duplicate orders",
+    keywords: ["duplicate", "idempotency", "order", "payment", "retry", "webhook"],
     files: ["src/payments/webhook.ts", "src/orders/create-order.ts", "src/payments/idempotency.ts"],
     checks: ["Webhook replay test", "Order idempotency suite", "Concurrent insert handling"],
     risks: ["Retry timing window", "Missing unique constraint", "Out-of-order delivery"]
@@ -45,6 +49,39 @@ const examples: Example[] = [
 ];
 
 const firstExample = examples[0]!;
+const genericWords = new Set([
+  "a", "an", "and", "are", "be", "because", "broken", "bug", "create", "does", "error", "failed", "fails", "failure",
+  "fix", "for", "from", "in", "is", "issue", "it", "of", "on", "or", "problem", "sometimes", "the", "to", "when", "with", "wrong"
+]);
+
+function issueWords(issue: string): string[] {
+  return [...new Set(issue.toLowerCase().match(/[a-z0-9]+/g) ?? [])]
+    .filter((word) => word.length > 2 && !genericWords.has(word));
+}
+
+function customResult(issue: string): Example {
+  const words = issueWords(issue);
+  const area = words[0]?.slice(0, 32) ?? "feature";
+  const behavior = words[1]?.slice(0, 32) ?? "behavior";
+  const title = `${area} ${behavior}`;
+  return {
+    label: "Custom issue preview",
+    issue,
+    keywords: words,
+    files: [`src/${area}/${behavior}.ts`, `src/${area}/index.ts`, `test/${area}/${behavior}.test.ts`],
+    checks: [`${title} behavior`, `${area} integration path`, `Regression for the reported issue`],
+    risks: ["Existing behavior compatibility", "Uncovered input boundary", "Related integration assumptions"]
+  };
+}
+
+function resultForIssue(issue: string): { example: Example; index: number } {
+  const words = new Set(issueWords(issue));
+  const ranked = examples
+    .map((example, index) => ({ example, index, score: example.keywords.filter((keyword) => words.has(keyword)).length }))
+    .sort((left, right) => right.score - left.score);
+  const match = ranked[0];
+  return match && match.score > 0 ? match : { example: customResult(issue), index: -1 };
+}
 
 const stageMeta: Array<{ key: StageKey; label: string; hint: string }> = [
   { key: "files", label: "Files", hint: "Finding relevant code" },
@@ -100,11 +137,11 @@ function OutputCard({
 export function InteractiveMapStage() {
   const [exampleIndex, setExampleIndex] = useState(0);
   const [issue, setIssue] = useState(firstExample.issue);
+  const [result, setResult] = useState(firstExample);
   const [activeStage, setActiveStage] = useState<StageKey>("files");
   const [readyCount, setReadyCount] = useState(3);
   const [isRunning, setIsRunning] = useState(false);
   const timers = useRef<number[]>([]);
-  const example = examples[exampleIndex] ?? firstExample;
 
   const clearTimers = () => {
     timers.current.forEach(window.clearTimeout);
@@ -114,12 +151,15 @@ export function InteractiveMapStage() {
   useEffect(() => clearTimers, []);
 
   const stageItems = useMemo(
-    () => ({ files: example.files, checks: example.checks, risks: example.risks }),
-    [example]
+    () => ({ files: result.files, checks: result.checks, risks: result.risks }),
+    [result]
   );
 
   const runMap = () => {
     clearTimers();
+    const next = resultForIssue(issue);
+    setExampleIndex(next.index);
+    setResult(next.example);
     setIsRunning(true);
     setReadyCount(0);
     setActiveStage("files");
@@ -137,6 +177,7 @@ export function InteractiveMapStage() {
     clearTimers();
     setExampleIndex(index);
     setIssue(nextExample.issue);
+    setResult(nextExample);
     setReadyCount(3);
     setActiveStage("files");
     setIsRunning(false);
@@ -149,11 +190,12 @@ export function InteractiveMapStage() {
         <label className="stage-example-select">
           <span className="sr-only">Choose an example issue</span>
           <select value={exampleIndex} onChange={(event) => chooseExample(Number(event.target.value))}>
+            {exampleIndex === -1 ? <option value={-1}>Custom issue preview</option> : null}
             {examples.map((item, index) => <option value={index} key={item.label}>Example: {item.label}</option>)}
           </select>
           <CaretDown size={14} weight="bold" aria-hidden />
         </label>
-        <span className="stage-local-status"><i /> Local analysis</span>
+        <span className="stage-local-status"><i /> Local demo</span>
       </div>
 
       <div className="stage-body">
diff --git a/apps/web/app/demo.tsx b/apps/web/app/demo.tsx
index ce81050..c67d540 100644
--- a/apps/web/app/demo.tsx
+++ b/apps/web/app/demo.tsx
@@ -315,7 +315,14 @@ function ExplainPanel({
 }
 
 function ComparePanel({ comparison }: { comparison: ReturnType<typeof compareReports> }) {
-  const changes = [...comparison.entered, ...comparison.moved, ...comparison.confidenceChanged];
+  // Leaving the plan is a change too. Omitting it made the counter say "0 changed" beside
+  // summaries such as "7 left", and hid the paths that explained the delta.
+  const changes = [
+    ...comparison.entered,
+    ...comparison.left,
+    ...comparison.moved,
+    ...comparison.confidenceChanged
+  ];
   return (
     <>
       <div className="results-head"><span>Earlier plan vs. current task</span><small>{changes.length} changed</small></div>
@@ -379,9 +386,11 @@ function VerifyPanel({
           <span className={`severity ${finding.severity}`}>{finding.severity}</span>
           <div>
             <p>{finding.message}</p>
-            {finding.paths.map((path) => (
-              <code key={path}>{path}</code>
-            ))}
+            <span className="finding-paths">
+              {finding.paths.map((path) => (
+                <code key={path}>{path}</code>
+              ))}
+            </span>
           </div>
         </article>
       ))}
diff --git a/apps/web/app/get-started/page.tsx b/apps/web/app/get-started/page.tsx
index 69ee6bd..296b188 100644
--- a/apps/web/app/get-started/page.tsx
+++ b/apps/web/app/get-started/page.tsx
@@ -88,7 +88,7 @@ npx fixmap plan --issue "password reset emails fail"`} />
           <h3>Claude Code</h3>
           <CopyCommand command="claude mcp add fixmap -- fixmap mcp" />
           <h3>Cursor, Windsurf, and other MCP clients</h3>
-          <pre className="code-block"><code>{`{
+          <pre className="code-block" tabIndex={0}><code>{`{
   "mcpServers": {
     "fixmap": {
       "command": "fixmap",
@@ -96,15 +96,15 @@ npx fixmap plan --issue "password reset emails fail"`} />
     }
   }
 }`}</code></pre>
-          <p className="small-note">Analysis runs locally over stdio. FixMap does not send repository source to a hosted model or service.</p>
+          <p className="small-note">Analysis runs locally over stdio. FixMap does not send repository source to a hosted model or service. Plan, Explain, and Verify accept <code>noCache: true</code> for an explicit fresh scan.</p>
         </div>
       </section>
 
       <section className="setup-section page-shell" id="action">
         <div className="setup-heading"><span>04</span><GithubLogo size={34} weight="fill" aria-hidden /><div><p className="eyebrow">GitHub Action</p><h2>Map every pull request.</h2></div></div>
         <div className="setup-content">
-          <p className="setup-lede">The Action posts one report as a pull-request comment and writes the complete result to the job summary.</p>
-          <pre className="code-block"><code>{`name: FixMap
+          <p className="setup-lede">The Action posts one report as a pull-request comment and writes the complete result to the job summary. Set <code>no-cache: true</code> when a workflow needs an explicit fresh scan.</p>
+          <pre className="code-block" tabIndex={0}><code>{`name: FixMap
 on:
   pull_request:
 
diff --git a/apps/web/app/globals.css b/apps/web/app/globals.css
index 77b6cb3..ff49baa 100644
--- a/apps/web/app/globals.css
+++ b/apps/web/app/globals.css
@@ -232,6 +232,7 @@ h3 { margin-bottom: 10px; font-size: 21px; line-height: 1.25; letter-spacing: -.
 .changed-list { display: flex; flex-wrap: wrap; gap: 8px; }
 .finding { display: grid; grid-template-columns: auto 1fr; gap: 12px; }
 .finding p { margin: 0 0 8px; color: var(--ink-soft); }
+.finding-paths { display: flex; flex-wrap: wrap; gap: 6px 10px; }
 .empty-result strong { display: block; margin-bottom: 7px; }
 .empty-result p { margin: 0; color: var(--ink-soft); }
 .demo-next { display: grid; grid-template-columns: 1fr 1fr; gap: 90px; border-top: 1px solid var(--line); }
diff --git a/packages/action/action.yml b/packages/action/action.yml
index a0224e1..f7b9aeb 100644
--- a/packages/action/action.yml
+++ b/packages/action/action.yml
@@ -46,6 +46,10 @@ inputs:
     description: With working-tree, include untracked files.
     required: false
     default: "false"
+  no-cache:
+    description: Bypass the exact-state repository scan cache and perform a fresh scan.
+    required: false
+    default: "false"
   format:
     description: >-
       Output format. JSON is posted as a fenced JSON pull-request comment, and the step
diff --git a/packages/action/dist/index.mjs b/packages/action/dist/index.mjs
index e726e03..13acd7f 100644
--- a/packages/action/dist/index.mjs
+++ b/packages/action/dist/index.mjs
@@ -1948,6 +1948,7 @@ var exec = promisify(execFile);
 var SCAN_CACHE_VERSION = 2;
 var SCAN_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
 var SCAN_CACHE_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json$/;
+var SCAN_CACHE_TEMP_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json\.\d+-[0-9a-f-]+\.tmp$/i;
 async function scanRepo(input) {
   const repoRoot = resolve(input.repoRoot);
   if (!await isDirectory(repoRoot)) {
@@ -2102,13 +2103,31 @@ async function buildScanCacheLocation(root, cacheRoot, internalPaths) {
 async function readScanCache(location) {
   try {
     const cached = JSON.parse(await readFile(location.path, "utf8"));
-    if (cached.version !== SCAN_CACHE_VERSION || cached.stateKey !== location.stateKey || typeof cached.createdAt !== "string" || !Number.isFinite(Date.parse(cached.createdAt)) || Date.now() - Date.parse(cached.createdAt) > SCAN_CACHE_MAX_AGE_MS || !Array.isArray(cached.files) || !Array.isArray(cached.trackedFiles) || !Array.isArray(cached.packageScripts) || !Array.isArray(cached.diagnostics) || !["npm", "pnpm", "yarn", "bun"].includes(cached.packageManager ?? ""))
+    if (cached.version !== SCAN_CACHE_VERSION || cached.stateKey !== location.stateKey || typeof cached.createdAt !== "string" || !Number.isFinite(Date.parse(cached.createdAt)) || Date.now() - Date.parse(cached.createdAt) > SCAN_CACHE_MAX_AGE_MS || !Array.isArray(cached.files) || !cached.files.every(isCachedRepoFile) || !Array.isArray(cached.trackedFiles) || !cached.trackedFiles.every((path) => typeof path === "string") || !Array.isArray(cached.packageScripts) || !cached.packageScripts.every(isCachedPackageScript) || !Array.isArray(cached.diagnostics) || !cached.diagnostics.every(isCachedDiagnostic) || !["npm", "pnpm", "yarn", "bun"].includes(cached.packageManager ?? ""))
       return void 0;
     return cached;
   } catch {
     return void 0;
   }
 }
+function isCachedRepoFile(candidate) {
+  if (!isRecord(candidate))
+    return false;
+  return typeof candidate.path === "string" && candidate.path.trim().length > 0 && typeof candidate.extension === "string" && typeof candidate.sizeBytes === "number" && Number.isFinite(candidate.sizeBytes) && candidate.sizeBytes >= 0 && typeof candidate.isTest === "boolean" && typeof candidate.isSource === "boolean" && (candidate.kind === "code" || candidate.kind === "config" || candidate.kind === "documentation" || candidate.kind === "other") && typeof candidate.textSample === "string" && (candidate.textSampleComplete === void 0 || typeof candidate.textSampleComplete === "boolean") && (candidate.textSampleSkipReason === void 0 || candidate.textSampleSkipReason === "too-large" || candidate.textSampleSkipReason === "not-text" || candidate.textSampleSkipReason === "unreadable");
+}
+function isCachedPackageScript(candidate) {
+  if (!isRecord(candidate))
+    return false;
+  return typeof candidate.name === "string" && typeof candidate.command === "string" && typeof candidate.packageDir === "string" && (candidate.packageName === void 0 || typeof candidate.packageName === "string");
+}
+function isCachedDiagnostic(candidate) {
+  if (!isRecord(candidate))
+    return false;
+  return typeof candidate.code === "string" && typeof candidate.message === "string" && (candidate.severity === "info" || candidate.severity === "warning" || candidate.severity === "error") && (candidate.paths === void 0 || Array.isArray(candidate.paths) && candidate.paths.every((path) => typeof path === "string"));
+}
+function isRecord(candidate) {
+  return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
+}
 async function writeScanCache(location, cached) {
   const temporaryPath = `${location.path}.${process.pid}-${randomUUID()}.tmp`;
   try {
@@ -2128,7 +2147,7 @@ async function pruneExpiredScanCache(cacheRoot) {
   try {
     const entries = await readdir(cacheRoot, { withFileTypes: true });
     const now = Date.now();
-    await Promise.all(entries.filter((entry) => entry.isFile() && SCAN_CACHE_FILE.test(entry.name)).map(async (entry) => {
+    await Promise.all(entries.filter((entry) => entry.isFile() && (SCAN_CACHE_FILE.test(entry.name) || SCAN_CACHE_TEMP_FILE.test(entry.name))).map(async (entry) => {
       const path = join(cacheRoot, entry.name);
       try {
         const metadata = await stat(path);
@@ -2185,7 +2204,7 @@ function isInternalCachePath(root, path, internalCacheRoot) {
     const cachePath = process.platform === "win32" ? relativeCacheRoot.toLowerCase() : relativeCacheRoot;
     return candidate === cachePath || candidate.startsWith(`${cachePath}/`);
   }
-  return sameFilesystemPath(internalCacheRoot, root) && (SCAN_CACHE_FILE.test(path) || /^[a-f0-9]{24}-[a-f0-9]{24}\.json\.\d+-[0-9a-f-]+\.tmp$/i.test(path));
+  return sameFilesystemPath(internalCacheRoot, root) && (SCAN_CACHE_FILE.test(path) || SCAN_CACHE_TEMP_FILE.test(path));
 }
 async function listGitPaths(root) {
   try {
@@ -2856,7 +2875,7 @@ function validateFixMapReport(candidate, label) {
     };
   }
   const invalid = contextFiles.findIndex((file) => {
-    if (typeof file !== "object" || file === null)
+    if (!isRecord2(file))
       return true;
     const ranked = file;
     if (typeof ranked.path !== "string" || ranked.path.trim().length === 0)
@@ -2867,12 +2886,14 @@ function validateFixMapReport(candidate, label) {
       return true;
     if (ranked.confidence !== void 0 && ranked.confidence !== "high" && ranked.confidence !== "medium" && ranked.confidence !== "low")
       return true;
+    if (ranked.reasons !== void 0 && !isStringArray(ranked.reasons))
+      return true;
     return false;
   });
   if (invalid !== -1) {
     return {
       success: false,
-      message: `${label} has an invalid contextFiles entry at index ${invalid}; each entry needs a non-empty string "path", and optional rank, score, and confidence fields must use their documented types.`
+      message: `${label} has an invalid contextFiles entry at index ${invalid}; each entry needs a non-empty string "path", and optional rank, score, confidence, and reasons fields must use their documented types.`
     };
   }
   const invalidEnvelopeFields = [
@@ -2890,45 +2911,81 @@ function validateFixMapReport(candidate, label) {
   }
   const testRoutes = record.testRoutes;
   const invalidRoute = testRoutes.findIndex((route) => {
-    if (typeof route !== "object" || route === null || Array.isArray(route))
+    if (!isRecord2(route))
       return true;
-    const entry = route;
-    return typeof entry.command !== "string" || !Array.isArray(entry.relatedFiles) || !entry.relatedFiles.every((path) => typeof path === "string");
+    return typeof route.command !== "string" || !route.command.trim() || !isNonBlankStringArray(route.relatedFiles) || route.kind !== void 0 && route.kind !== "test" && route.kind !== "validation" || route.reason !== void 0 && typeof route.reason !== "string";
   });
   if (invalidRoute !== -1) {
     return {
       success: false,
-      message: `${label} has an invalid testRoutes entry at index ${invalidRoute}; each route needs a string "command" and a string array named relatedFiles.`
+      message: `${label} has an invalid testRoutes entry at index ${invalidRoute}; each route needs a string "command" and an array of non-empty string paths named relatedFiles; optional kind and reason fields must use their documented types.`
     };
   }
   const risks = record.risks;
   const invalidRisk = risks.findIndex((risk) => {
-    if (typeof risk !== "object" || risk === null || Array.isArray(risk))
+    if (!isRecord2(risk))
       return true;
-    return typeof risk.area !== "string";
+    return typeof risk.area !== "string" || !risk.area.trim() || risk.reason !== void 0 && typeof risk.reason !== "string" || risk.severity !== void 0 && risk.severity !== "low" && risk.severity !== "medium" && risk.severity !== "high";
   });
   if (invalidRisk !== -1) {
     return {
       success: false,
-      message: `${label} has an invalid risks entry at index ${invalidRisk}; each risk needs a string "area".`
+      message: `${label} has an invalid risks entry at index ${invalidRisk}; each risk needs a non-empty string "area", and optional reason and severity fields must use their documented types.`
     };
   }
-  if (!record.changedFiles.every((path) => typeof path === "string")) {
-    return { success: false, message: `${label} has invalid changedFiles; every entry must be a string path.` };
+  if (!isNonBlankStringArray(record.changedFiles)) {
+    return { success: false, message: `${label} has invalid changedFiles; every entry must be a non-empty string path.` };
+  }
+  const diagnostics = record.diagnostics;
+  const invalidDiagnostic = diagnostics.findIndex((diagnostic) => {
+    if (!isRecord2(diagnostic))
+      return true;
+    return typeof diagnostic.code !== "string" || !diagnostic.code.trim() || typeof diagnostic.message !== "string" || diagnostic.severity !== "info" && diagnostic.severity !== "warning" && diagnostic.severity !== "error" || diagnostic.paths !== void 0 && !isNonBlankStringArray(diagnostic.paths);
+  });
+  if (invalidDiagnostic !== -1) {
+    return {
+      success: false,
+      message: `${label} has an invalid diagnostics entry at index ${invalidDiagnostic}; each diagnostic needs string code and message fields, an info, warning, or error severity, and optional non-empty string paths.`
+    };
   }
   if (record.analysis !== void 0) {
     const analysis = record.analysis;
-    const grounding = typeof analysis === "object" && analysis !== null && !Array.isArray(analysis) ? analysis.grounding : void 0;
-    const specificity = typeof grounding === "object" && grounding !== null && !Array.isArray(grounding) ? grounding.specificity : void 0;
+    const grounding = isRecord2(analysis) ? analysis.grounding : void 0;
+    const specificity = isRecord2(grounding) ? grounding.specificity : void 0;
     if (specificity !== "anchored" && specificity !== "descriptive" && specificity !== "vague") {
       return {
         success: false,
         message: `${label} has invalid analysis.grounding.specificity; expected anchored, descriptive, or vague.`
       };
     }
+    if (!isRecord2(analysis) || !isRecord2(grounding) || !Array.isArray(grounding.identifiers) || !isStringArray(grounding.unresolvedIdentifiers) || !isStringArray(grounding.partiallyResolvedIdentifiers) || !isStringArray(grounding.unverifiedIdentifiers) || typeof grounding.scanComplete !== "boolean" || !isRecord2(analysis.ranking) || !isNullableFiniteNumber(analysis.ranking.topScore) || !isNullableFiniteNumber(analysis.ranking.runnerUpScore) || !isNullableFiniteNumber(analysis.ranking.topGap) || typeof analysis.ranking.clustered !== "boolean" || typeof analysis.nextAction !== "string") {
+      return {
+        success: false,
+        message: `${label} has incomplete or invalid analysis grounding, ranking, or nextAction fields.`
+      };
+    }
+    const invalidIdentifier = grounding.identifiers.findIndex((identifier) => !isRecord2(identifier) || typeof identifier.identifier !== "string" || !identifier.identifier.trim() || typeof identifier.status !== "string" || !identifier.status.trim() || !isNonBlankStringArray(identifier.matchedFiles));
+    if (invalidIdentifier !== -1) {
+      return {
+        success: false,
+        message: `${label} has an invalid analysis.grounding.identifiers entry at index ${invalidIdentifier}.`
+      };
+    }
   }
   return { success: true, report: candidate };
 }
+function isRecord2(candidate) {
+  return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
+}
+function isStringArray(candidate) {
+  return Array.isArray(candidate) && candidate.every((entry) => typeof entry === "string");
+}
+function isNonBlankStringArray(candidate) {
+  return isStringArray(candidate) && candidate.every((entry) => entry.trim().length > 0);
+}
+function isNullableFiniteNumber(candidate) {
+  return candidate === null || typeof candidate === "number" && Number.isFinite(candidate);
+}
 
 // packages/action/src/github.ts
 var FIXMAP_REPORT_MARKER = "<!-- fixmap-report -->";
@@ -3151,6 +3208,7 @@ async function runAction(env = process.env, dependencies = {}) {
   const diffSpec = readInput("diff", env);
   const workingTree = parseBooleanInput("working-tree", readInput("working-tree", env));
   const includeUntracked = parseBooleanInput("include-untracked", readInput("include-untracked", env));
+  const noCache = parseBooleanInput("no-cache", readInput("no-cache", env));
   const baseRef = readInput("base", env) || (!workingTree && env.GITHUB_BASE_REF ? `origin/${env.GITHUB_BASE_REF}` : void 0);
   const headRef = readInput("head", env) || (!workingTree && env.GITHUB_HEAD_REF ? "HEAD" : void 0);
   const format = parseFormat(readInput("format", env));
@@ -3171,7 +3229,7 @@ async function runAction(env = process.env, dependencies = {}) {
         `FixMap verify mode does not use plan-only input${planOnly.length === 1 ? "" : "s"}: ${planOnly.join(", ")}. Remove them, or set mode: plan.`
       );
     }
-    return runVerifyMode({ env, dependencies, readFile: readFile3, appendFile, stdout, format, diffSpec, baseRef, headRef, workingTree, includeUntracked });
+    return runVerifyMode({ env, dependencies, readFile: readFile3, appendFile, stdout, format, diffSpec, baseRef, headRef, workingTree, includeUntracked, noCache });
   }
   const issueSource = rawIssue ? parseActionIssueSource(rawIssue) : void 0;
   if (issueSource && env.GITHUB_REPOSITORY && env.GITHUB_REPOSITORY.toLowerCase() !== `${issueSource.owner}/${issueSource.repository}`.toLowerCase()) {
@@ -3192,7 +3250,7 @@ async function runAction(env = process.env, dependencies = {}) {
     headRef,
     workingTree,
     includeUntracked,
-    useCache: true,
+    useCache: !noCache,
     limit,
     exclude
   });
@@ -3272,7 +3330,7 @@ async function runVerifyMode(context) {
     headRef: context.headRef,
     workingTree: context.workingTree,
     includeUntracked: context.includeUntracked,
-    useCache: true,
+    useCache: !context.noCache,
     internalExclude: [resolve3(repoRoot, reportPath)]
   });
   const diffFailure = repo.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
diff --git a/packages/action/src/runner.ts b/packages/action/src/runner.ts
index 7dff79d..9c8dafb 100644
--- a/packages/action/src/runner.ts
+++ b/packages/action/src/runner.ts
@@ -54,6 +54,7 @@ export async function runAction(
   const diffSpec = readInput("diff", env);
   const workingTree = parseBooleanInput("working-tree", readInput("working-tree", env));
   const includeUntracked = parseBooleanInput("include-untracked", readInput("include-untracked", env));
+  const noCache = parseBooleanInput("no-cache", readInput("no-cache", env));
   const baseRef = readInput("base", env) || (!workingTree && env.GITHUB_BASE_REF ? `origin/${env.GITHUB_BASE_REF}` : undefined);
   const headRef = readInput("head", env) || (!workingTree && env.GITHUB_HEAD_REF ? "HEAD" : undefined);
   const format = parseFormat(readInput("format", env));
@@ -81,7 +82,7 @@ export async function runAction(
         "Remove them, or set mode: plan."
       );
     }
-    return runVerifyMode({ env, dependencies, readFile, appendFile, stdout, format, diffSpec, baseRef, headRef, workingTree, includeUntracked });
+    return runVerifyMode({ env, dependencies, readFile, appendFile, stdout, format, diffSpec, baseRef, headRef, workingTree, includeUntracked, noCache });
   }
 
   const issueSource = rawIssue ? parseActionIssueSource(rawIssue) : undefined;
@@ -111,7 +112,7 @@ export async function runAction(
     headRef,
     workingTree,
     includeUntracked,
-    useCache: true,
+    useCache: !noCache,
     limit,
     exclude
   });
@@ -181,6 +182,7 @@ type VerifyModeContext = {
   headRef: string | undefined;
   workingTree: boolean;
   includeUntracked: boolean;
+  noCache: boolean;
 };
 
 async function runVerifyMode(context: VerifyModeContext): Promise<void> {
@@ -215,7 +217,7 @@ async function runVerifyMode(context: VerifyModeContext): Promise<void> {
     headRef: context.headRef,
     workingTree: context.workingTree,
     includeUntracked: context.includeUntracked,
-    useCache: true,
+    useCache: !context.noCache,
     internalExclude: [resolve(repoRoot, reportPath)]
   });
   const diffFailure = repo.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
diff --git a/packages/action/test/runner.test.ts b/packages/action/test/runner.test.ts
index a704f86..2e8cf52 100644
--- a/packages/action/test/runner.test.ts
+++ b/packages/action/test/runner.test.ts
@@ -76,6 +76,15 @@ describe("GitHub Action runner", () => {
     expect(stdout.mock.calls[0]?.[0]).toContain('"contextFiles"');
   });
 
+  it("passes no-cache through to a fresh plan scan", async () => {
+    const buildReport = vi.fn(async () => structuredClone(report));
+    await runAction({ INPUT_ISSUE: "password reset", INPUT_NO_CACHE: "true" }, {
+      buildReport,
+      stdout: vi.fn()
+    });
+    expect(buildReport).toHaveBeenCalledWith(expect.objectContaining({ useCache: false }));
+  });
+
   it("fetches same-repository GitHub issue URLs before ranking", async () => {
     const buildReport = vi.fn(async () => structuredClone(report));
     await runAction({
@@ -167,6 +176,21 @@ describe("GitHub Action runner", () => {
     }));
   });
 
+  it("passes no-cache through to a fresh verify scan", async () => {
+    const scanRepo = vi.fn(async () => scannedRepo(["src/auth.ts"]));
+    await runAction({
+      INPUT_MODE: "verify",
+      INPUT_REPORT_PATH: "plan.json",
+      INPUT_DIFF: "main...HEAD",
+      INPUT_NO_CACHE: "true"
+    }, {
+      readFile: () => JSON.stringify(report),
+      scanRepo,
+      stdout: vi.fn()
+    });
+    expect(scanRepo).toHaveBeenCalledWith(expect.objectContaining({ useCache: false }));
+  });
+
   it("rejects a truncated non-empty report before scanning or dereferencing missing fields", async () => {
     const scanRepo = vi.fn(async () => scannedRepo(["src/auth.ts"]));
     await expect(runAction({
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 0a5bb4f..19b697e 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -71,7 +71,7 @@ For long task text, use `--issue-file task.md` or pipe text to `--issue -`. A le
 
 ## MCP server
 
-FixMap ships five Model Context Protocol tools: `fixmap_plan`, `fixmap_explain`, `fixmap_compare`, `fixmap_verify`, and `fixmap_doctor`.
+FixMap ships five Model Context Protocol tools: `fixmap_plan`, `fixmap_explain`, `fixmap_compare`, `fixmap_verify`, and `fixmap_doctor`. Plan, Explain, and Verify accept `noCache: true` when an agent needs a fresh repository scan rather than an exact-state cache hit.
 
 Claude Code:
 
diff --git a/packages/cli/src/agent-setup.ts b/packages/cli/src/agent-setup.ts
index 78d1704..a986853 100644
--- a/packages/cli/src/agent-setup.ts
+++ b/packages/cli/src/agent-setup.ts
@@ -13,7 +13,7 @@ export const FIXMAP_FEATURES = [
   { name: "MCP", command: "fixmap mcp", detail: "Expose Plan, Explain, Compare, Verify, and Doctor over local stdio." },
   { name: "Focus", command: "--limit, --exclude, .fixmapignore", detail: "Narrow ranking without changing the repository." },
   { name: "Live changes", command: "--working-tree --include-untracked", detail: "Map staged, unstaged, and optionally untracked work against HEAD." },
-  { name: "Fresh scan", command: "--no-cache", detail: "Bypass the exact git-state scan cache and report that a fresh scan was used." }
+  { name: "Fresh scan", command: "--no-cache", detail: "Bypass the exact git-state cache with CLI --no-cache, MCP noCache: true, or Action no-cache: true, and report that a fresh scan was used." }
 ] as const;
 
 export function renderFeatureCatalog(format: "markdown" | "json" = "markdown"): string {
diff --git a/packages/cli/src/cli-runner.ts b/packages/cli/src/cli-runner.ts
index 32f0683..9ab6a95 100644
--- a/packages/cli/src/cli-runner.ts
+++ b/packages/cli/src/cli-runner.ts
@@ -831,15 +831,18 @@ export function parseArgs(args: string[]): CliOptions {
     } else if (arg === "--working-tree") {
       if (flagCounts.has(arg)) invalidValues.push(`pass ${arg} only once`);
       flagCounts.set(arg, 1);
-      workingTree = true;
+      if (inlineValue !== undefined) invalidValues.push(`${arg} does not accept a value; pass ${arg} by itself`);
+      else workingTree = true;
     } else if (arg === "--include-untracked") {
       if (flagCounts.has(arg)) invalidValues.push(`pass ${arg} only once`);
       flagCounts.set(arg, 1);
-      includeUntracked = true;
+      if (inlineValue !== undefined) invalidValues.push(`${arg} does not accept a value; pass ${arg} by itself`);
+      else includeUntracked = true;
     } else if (arg === "--no-cache") {
       if (flagCounts.has(arg)) invalidValues.push(`pass ${arg} only once`);
       flagCounts.set(arg, 1);
-      noCache = true;
+      if (inlineValue !== undefined) invalidValues.push(`${arg} does not accept a value; pass ${arg} by itself`);
+      else noCache = true;
     } else if (arg === "--output") {
       consumeValue();
       if (value?.trim()) output = expandHomePath(value.trim());
diff --git a/packages/cli/src/mcp.ts b/packages/cli/src/mcp.ts
index 7adc48a..3b88bc8 100644
--- a/packages/cli/src/mcp.ts
+++ b/packages/cli/src/mcp.ts
@@ -39,6 +39,7 @@ type PlanArguments = {
   exclude?: string[];
   workingTree?: boolean;
   includeUntracked?: boolean;
+  noCache?: boolean;
 };
 
 type ExplainArguments = {
@@ -53,6 +54,7 @@ type ExplainArguments = {
   format?: "markdown" | "json";
   workingTree?: boolean;
   includeUntracked?: boolean;
+  noCache?: boolean;
 };
 
 type PlanArgumentsValidation =
@@ -69,6 +71,7 @@ type VerifyArguments = {
   format?: "markdown" | "json";
   workingTree?: boolean;
   includeUntracked?: boolean;
+  noCache?: boolean;
 };
 
 const PLAN_TOOL = {
@@ -125,7 +128,8 @@ const PLAN_TOOL = {
           "A .fixmapignore file in the repository is applied as well."
       },
       workingTree: { type: "boolean", description: "Map staged and unstaged tracked changes against HEAD" },
-      includeUntracked: { type: "boolean", description: "With workingTree, include untracked files" }
+      includeUntracked: { type: "boolean", description: "With workingTree, include untracked files" },
+      noCache: { type: "boolean", description: "Bypass the exact-state repository scan cache" }
     },
     additionalProperties: false
   }
@@ -166,7 +170,8 @@ const EXPLAIN_TOOL = {
         description: "The same exclusion patterns used for the plan"
       },
       limit: { type: "number", description: `Maximum reported context files, 1 to ${MAX_MCP_LIMIT}` },
-      format: { type: "string", description: "Output format: markdown (default) or json, case-insensitive" }
+      format: { type: "string", description: "Output format: markdown (default) or json, case-insensitive" },
+      noCache: { type: "boolean", description: "Bypass the exact-state repository scan cache" }
     },
     required: ["path"],
     additionalProperties: false
@@ -196,7 +201,8 @@ const VERIFY_TOOL = {
       repo: { type: "string", description: "Local repository path, defaults to the server working directory" },
       workingTree: { type: "boolean", description: "Verify staged and unstaged tracked changes against HEAD" },
       includeUntracked: { type: "boolean", description: "With workingTree, include untracked files" },
-      format: { type: "string", description: "Output format: markdown (default) or json, case-insensitive" }
+      format: { type: "string", description: "Output format: markdown (default) or json, case-insensitive" },
+      noCache: { type: "boolean", description: "Bypass the exact-state repository scan cache" }
     },
     required: ["report"],
     additionalProperties: false
@@ -246,6 +252,13 @@ export function createFixMapMcpServer(
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (request.params.name === COMPARE_TOOL.name) {
       const record = request.params.arguments as Record<string, unknown> | undefined;
+      const unknown = Object.keys(record ?? {}).filter((key) => !["previous", "current", "format"].includes(key));
+      if (unknown.length > 0) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `Invalid arguments: unknown argument${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}.` }]
+        };
+      }
       const previous = loadReportInput(record?.previous, '"previous"');
       if (!previous.success) return { isError: true, content: [{ type: "text", text: `Invalid arguments: ${previous.message}` }] };
       const current = loadReportInput(record?.current, '"current"');
@@ -294,7 +307,7 @@ export function createFixMapMcpServer(
           headRef: args.head,
           workingTree: args.workingTree,
           includeUntracked: args.includeUntracked,
-          useCache: true,
+          useCache: !args.noCache,
           internalExclude: args.reportPath ? [resolve(args.reportPath)] : undefined
         });
         const diffFailure = repo.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
@@ -340,7 +353,7 @@ export function createFixMapMcpServer(
           headRef: args.head,
           workingTree: args.workingTree,
           includeUntracked: args.includeUntracked,
-          useCache: true
+          useCache: !args.noCache
         });
         const explanation = explainFile(
           repo,
@@ -396,7 +409,7 @@ export function createFixMapMcpServer(
         headRef: args.head,
         workingTree: args.workingTree,
         includeUntracked: args.includeUntracked,
-        useCache: true,
+        useCache: !args.noCache,
         limit: args.limit,
         exclude: args.exclude
       }, repositorySourceDependencies);
@@ -436,7 +449,7 @@ export function parsePlanArguments(input: unknown): PlanArgumentsValidation {
   }
 
   const record = input as Record<string, unknown>;
-  const allowed = new Set(["issue", "diff", "base", "head", "repo", "format", "limit", "exclude", "workingTree", "includeUntracked"]);
+  const allowed = new Set(["issue", "diff", "base", "head", "repo", "format", "limit", "exclude", "workingTree", "includeUntracked", "noCache"]);
   const unknown = Object.keys(record).filter((key) => !allowed.has(key));
   if (unknown.length > 0) {
     return {
@@ -451,8 +464,10 @@ export function parsePlanArguments(input: unknown): PlanArgumentsValidation {
       return { success: false, message: `"${name}" must be a string.` };
     }
   }
-  if (record.issue !== undefined && typeof record.issue === "string" && !record.issue.trim()) return { success: false, message: '"issue" must not be blank.' };
-  for (const name of ["workingTree", "includeUntracked"] as const) if (record[name] !== undefined && typeof record[name] !== "boolean") return { success: false, message: `"${name}" must be a boolean.` };
+  for (const name of ["issue", "diff", "base", "head", "repo"] as const) {
+    if (typeof record[name] === "string" && !record[name].trim()) return { success: false, message: `"${name}" must not be blank.` };
+  }
+  for (const name of ["workingTree", "includeUntracked", "noCache"] as const) if (record[name] !== undefined && typeof record[name] !== "boolean") return { success: false, message: `"${name}" must be a boolean.` };
   if (record.includeUntracked === true && record.workingTree !== true) return { success: false, message: '"includeUntracked" requires "workingTree".' };
   if (record.workingTree === true && (record.diff || record.base || record.head)) return { success: false, message: 'use either "workingTree" or diff/base/head, not both.' };
   if (record.diff && (record.base || record.head)) return { success: false, message: 'use either "diff" or base/head, not both.' };
@@ -483,6 +498,7 @@ export function parsePlanArguments(input: unknown): PlanArgumentsValidation {
   }
   if (record.workingTree === true) value.workingTree = true;
   if (record.includeUntracked === true) value.includeUntracked = true;
+  if (record.noCache === true) value.noCache = true;
   if (value.issue && /^https?:\/\/\S+$/i.test(value.issue) && !tryParseGitHubIssueSource(value.issue)) return { success: false, message: '"issue" URL must be a canonical public GitHub issue or pull request URL.' };
   return { success: true, value };
 }
@@ -523,7 +539,7 @@ export function parseExplainArguments(
     return { success: false, message: "tool arguments must be an object." };
   }
   const record = input as Record<string, unknown>;
-  const allowed = new Set(["path", "issue", "diff", "base", "head", "repo", "exclude", "format", "limit", "workingTree", "includeUntracked"]);
+  const allowed = new Set(["path", "issue", "diff", "base", "head", "repo", "exclude", "format", "limit", "workingTree", "includeUntracked", "noCache"]);
   const unknown = Object.keys(record).filter((key) => !allowed.has(key));
   if (unknown.length > 0) {
     return { success: false, message: `unknown argument${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}.` };
@@ -534,7 +550,12 @@ export function parseExplainArguments(
       return { success: false, message: `"${name}" must be a string.` };
     }
   }
-  for (const name of ["workingTree", "includeUntracked"] as const) {
+  for (const name of ["issue", "diff", "base", "head", "repo"] as const) {
+    if (typeof record[name] === "string" && !record[name].trim()) {
+      return { success: false, message: `"${name}" must not be blank.` };
+    }
+  }
+  for (const name of ["workingTree", "includeUntracked", "noCache"] as const) {
     if (record[name] !== undefined && typeof record[name] !== "boolean") {
       return { success: false, message: `"${name}" must be a boolean.` };
     }
@@ -543,6 +564,10 @@ export function parseExplainArguments(
   if (!path) {
     return { success: false, message: '"path" is required and must be a repository-relative file path.' };
   }
+  if (record.includeUntracked === true && record.workingTree !== true) return { success: false, message: '"includeUntracked" requires "workingTree".' };
+  if (record.workingTree === true && (record.diff || record.base || record.head)) return { success: false, message: 'use either "workingTree" or diff/base/head, not both.' };
+  if (record.diff && (record.base || record.head)) return { success: false, message: 'use either "diff" or base/head, not both.' };
+  if (record.head && !record.base) return { success: false, message: '"head" requires "base".' };
   const format = normalizeFormat(record.format); if (!format.success) return format;
   const limit = validateLimit(record.limit); if (!limit.success) return limit;
   const exclude = validateExclude(record.exclude);
@@ -560,6 +585,7 @@ export function parseExplainArguments(
       ...(typeof record.head === "string" && record.head.trim() ? { head: record.head.trim() } : {}),
       ...(record.workingTree === true ? { workingTree: true } : {}),
       ...(record.includeUntracked === true ? { includeUntracked: true } : {}),
+      ...(record.noCache === true ? { noCache: true } : {}),
       ...(typeof record.repo === "string" && record.repo.trim() ? { repo: record.repo.trim() } : {}),
       ...(exclude.value.length > 0 ? { exclude: exclude.value } : {}),
       ...(limit.value !== undefined ? { limit: limit.value } : {}),
@@ -577,7 +603,7 @@ export function parseVerifyArguments(input: unknown): VerifyArgumentsValidation
     return { success: false, message: "tool arguments must be an object." };
   }
   const record = input as Record<string, unknown>;
-  const allowed = new Set(["report", "diff", "base", "head", "repo", "format", "workingTree", "includeUntracked"]);
+  const allowed = new Set(["report", "diff", "base", "head", "repo", "format", "workingTree", "includeUntracked", "noCache"]);
   const unknown = Object.keys(record).filter((key) => !allowed.has(key));
   if (unknown.length > 0) {
     return { success: false, message: `unknown argument${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}.` };
@@ -596,7 +622,7 @@ export function parseVerifyArguments(input: unknown): VerifyArgumentsValidation
   if (!record.diff && !record.base && record.workingTree !== true) {
     return { success: false, message: 'provide "diff", "base"/"head", or "workingTree" so FixMap can see what changed.' };
   }
-  for (const name of ["workingTree", "includeUntracked"] as const) if (record[name] !== undefined && typeof record[name] !== "boolean") return { success: false, message: `"${name}" must be a boolean.` };
+  for (const name of ["workingTree", "includeUntracked", "noCache"] as const) if (record[name] !== undefined && typeof record[name] !== "boolean") return { success: false, message: `"${name}" must be a boolean.` };
   if (record.includeUntracked === true && record.workingTree !== true) return { success: false, message: '"includeUntracked" requires "workingTree".' };
   if (record.workingTree === true && (record.diff || record.base || record.head)) return { success: false, message: 'use either "workingTree" or diff/base/head, not both.' };
   if (record.diff && (record.base || record.head)) return { success: false, message: 'use either "diff" or base/head, not both.' };
@@ -613,6 +639,7 @@ export function parseVerifyArguments(input: unknown): VerifyArgumentsValidation
       ...(typeof record.repo === "string" ? { repo: record.repo.trim() } : {}),
       ...(record.workingTree === true ? { workingTree: true } : {}),
       ...(record.includeUntracked === true ? { includeUntracked: true } : {}),
+      ...(record.noCache === true ? { noCache: true } : {}),
       ...(format.value ? { format: format.value } : {})
     }
   };
@@ -621,7 +648,7 @@ export function parseVerifyArguments(input: unknown): VerifyArgumentsValidation
 function normalizeFormat(candidate: unknown): { success: true; value: "markdown" | "json" | undefined } | { success: false; message: string } {
   if (candidate === undefined) return { success: true, value: undefined };
   if (typeof candidate !== "string") return { success: false, message: '"format" must be either "markdown" or "json".' };
-  const value = candidate.toLowerCase();
+  const value = candidate.trim().toLowerCase();
   return value === "markdown" || value === "json" ? { success: true, value } : { success: false, message: '"format" must be either "markdown" or "json".' };
 }
 
diff --git a/packages/cli/test/cli-runner.test.ts b/packages/cli/test/cli-runner.test.ts
index 9ef38b2..47f6075 100644
--- a/packages/cli/test/cli-runner.test.ts
+++ b/packages/cli/test/cli-runner.test.ts
@@ -252,6 +252,17 @@ describe("CLI argument handling", () => {
     expect(parseArgs(["plan", "--issue", "x", "--format", " JSON\n"]).format).toBe("json");
   });
 
+  it.each(["--working-tree", "--include-untracked", "--no-cache"])(
+    "rejects an inline value on boolean flag %s instead of silently treating false as true",
+    (flag) => {
+      const parsed = parseArgs(["plan", "--issue", "x", `${flag}=false`]);
+      expect(parsed.invalidValues).toContain(`${flag} does not accept a value; pass ${flag} by itself`);
+      expect(parsed.workingTree).toBe(false);
+      expect(parsed.includeUntracked).toBe(false);
+      expect(parsed.noCache).toBe(false);
+    }
+  );
+
   it("trims accidental whitespace around git refs", () => {
     const parsed = parseArgs([
       "plan", "--issue", "x", "--diff", " HEAD~1...HEAD\n", "--base", " main ", "--head", " feature "
diff --git a/packages/cli/test/mcp.test.ts b/packages/cli/test/mcp.test.ts
index 94f5d15..9081261 100644
--- a/packages/cli/test/mcp.test.ts
+++ b/packages/cli/test/mcp.test.ts
@@ -6,7 +6,7 @@ import { promisify } from "node:util";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { describe, expect, it } from "vitest";
-import { createFixMapMcpServer, parseExplainArguments, parsePlanArguments } from "../src/mcp.js";
+import { createFixMapMcpServer, parseExplainArguments, parsePlanArguments, parseVerifyArguments } from "../src/mcp.js";
 import type { RepositorySourceDependencies } from "../src/repository-source.js";
 
 const exec = promisify(execFile);
@@ -118,6 +118,22 @@ describe("fixmap mcp server", () => {
     });
   });
 
+  it("bypasses the repository cache when an MCP caller requests a fresh scan", async () => {
+    const root = await createAuthFixture();
+    const client = await connectClient();
+
+    const result = await client.callTool({
+      name: "fixmap_plan",
+      arguments: { issue: "password reset fails", repo: root, noCache: true, format: "json" }
+    });
+
+    expect(result.isError).toBeFalsy();
+    const report = JSON.parse((result.content as Array<{ text: string }>)[0]!.text) as {
+      diagnostics: Array<{ code: string }>;
+    };
+    expect(report.diagnostics.map((diagnostic) => diagnostic.code)).toContain("cache-bypass");
+  });
+
   it("caps the reported context files through MCP", async () => {
     const root = await createAuthFixture();
     const client = await connectClient();
@@ -143,15 +159,15 @@ describe("fixmap mcp server", () => {
     expect(plan).toBeDefined();
     expect(plan?.description).toContain("test commands");
     expect(Object.keys(plan?.inputSchema.properties ?? {})).toEqual(
-      expect.arrayContaining(["issue", "diff", "base", "head", "repo", "format"])
+      expect.arrayContaining(["issue", "diff", "base", "head", "repo", "format", "noCache"])
     );
     expect(plan?.inputSchema.properties?.repo?.description).toContain("public GitHub HTTPS");
     expect(plan?.inputSchema.properties?.issue?.description).toContain("GitHub issue URL");
     expect(verify).toBeDefined();
-    expect(Object.keys(verify?.inputSchema.properties ?? {})).toContain("report");
+    expect(Object.keys(verify?.inputSchema.properties ?? {})).toEqual(expect.arrayContaining(["report", "noCache"]));
     const explain = tools.tools.find((tool) => tool.name === "fixmap_explain");
     expect(explain).toBeDefined();
-    expect(Object.keys(explain?.inputSchema.properties ?? {})).toContain("path");
+    expect(Object.keys(explain?.inputSchema.properties ?? {})).toEqual(expect.arrayContaining(["path", "noCache"]));
     expect(explain?.inputSchema.required).toContain("path");
     expect(tools.tools.find((tool) => tool.name === "fixmap_compare")).toBeDefined();
     expect(tools.tools.find((tool) => tool.name === "fixmap_doctor")).toBeDefined();
@@ -561,11 +577,45 @@ describe("MCP surface parity", () => {
     expect(wrong.success === false && wrong.message).toContain('"workingTree" must be a boolean');
   });
 
+  it("rejects contradictory explain scan options instead of silently changing their meaning", () => {
+    expect(parseExplainArguments({ path: "a.ts", includeUntracked: true }).success).toBe(false);
+    expect(parseExplainArguments({ path: "a.ts", workingTree: true, diff: "HEAD" }).success).toBe(false);
+    expect(parseExplainArguments({ path: "a.ts", diff: "main...HEAD", base: "main" }).success).toBe(false);
+    expect(parseExplainArguments({ path: "a.ts", head: "HEAD" }).success).toBe(false);
+  });
+
   // #278: a four-literal enum rejected `Markdown` in strict clients before normalization ran.
-  it.each(["markdown", "JSON", "Markdown", "JsOn"])("accepts %j as a format", (format) => {
+  it.each(["markdown", "JSON", "Markdown", "JsOn", " JSON\n"])("accepts %j as a format", (format) => {
     expect(parsePlanArguments({ issue: "x", format }).success).toBe(true);
   });
 
+  it("normalizes fresh-scan and whitespace inputs consistently across MCP tools", () => {
+    const report = { summary: "No matches", contextFiles: [], testRoutes: [], risks: [], changedFiles: [], diagnostics: [] };
+    expect(parsePlanArguments({ issue: " x ", format: " JSON ", noCache: true })).toEqual({
+      success: true,
+      value: { issue: "x", format: "json", noCache: true }
+    });
+    expect(parseExplainArguments({ path: " a.ts ", issue: " x ", format: " Markdown ", noCache: true })).toEqual({
+      success: true,
+      value: { path: "a.ts", issue: "x", noCache: true, format: "markdown" }
+    });
+    expect(parseVerifyArguments({ report, diff: " HEAD ", format: " JSON ", noCache: true })).toEqual({
+      success: true,
+      value: { report, diff: "HEAD", noCache: true, format: "json" }
+    });
+  });
+
+  it("rejects unknown compare arguments at the request handler", async () => {
+    const client = await connectClient();
+    const report = { summary: "No matches", contextFiles: [], testRoutes: [], risks: [], changedFiles: [], diagnostics: [] };
+    const result = await client.callTool({
+      name: "fixmap_compare",
+      arguments: { previous: report, current: report, surprise: true }
+    });
+    expect(result.isError).toBe(true);
+    expect((result.content as Array<{ text: string }>)[0]?.text).toContain("unknown argument: surprise");
+  });
+
   // #369: the throwing parser surfaced an uncaught exception instead of Invalid arguments.
   it("reports a non-canonical issue URL as invalid rather than throwing", () => {
     expect(() => parsePlanArguments({ issue: "https://github.com/o/r/issues/274?plain=1" })).not.toThrow();
diff --git a/packages/core/src/compare.ts b/packages/core/src/compare.ts
index 5fc53bf..898506d 100644
--- a/packages/core/src/compare.ts
+++ b/packages/core/src/compare.ts
@@ -151,13 +151,15 @@ export function renderComparisonMarkdown(comparison: ReportComparison): string {
   }
 
   appendSection(lines, "Entered", comparison.entered, (delta) =>
-    `\`${delta.path}\` at rank ${delta.currentRank} (${delta.currentConfidence}, score ${delta.currentScore})`);
+    `\`${delta.path}\` at rank ${delta.currentRank}${formatMetrics(delta.currentConfidence, delta.currentScore)}`);
   appendSection(lines, "Left", comparison.left, (delta) =>
-    `\`${delta.path}\` was rank ${delta.previousRank} (${delta.previousConfidence}, score ${delta.previousScore})`);
+    `\`${delta.path}\` was rank ${delta.previousRank}${formatMetrics(delta.previousConfidence, delta.previousScore)}`);
   appendSection(lines, "Moved", comparison.moved, (delta) =>
     `\`${delta.path}\` ${describeMove(delta)}`);
   appendSection(lines, "Confidence changed", comparison.confidenceChanged, (delta) =>
-    `\`${delta.path}\` stayed at rank ${delta.currentRank} and score ${delta.currentScore}; confidence changed from ${delta.previousConfidence} to ${delta.currentConfidence}`);
+    `\`${delta.path}\` stayed at rank ${delta.currentRank}` +
+    `${delta.currentScore === undefined ? "" : ` and score ${delta.currentScore}`}; confidence changed from ` +
+    `${delta.previousConfidence ?? "unknown"} to ${delta.currentConfidence ?? "unknown"}`);
 
   if (comparison.unchanged.length > 0) {
     lines.push(`## Unchanged`, "", `${comparison.unchanged.length} file(s) held their rank, score, and confidence.`, "");
@@ -173,11 +175,23 @@ function describeMove(delta: RankDelta): string {
   const rank = direction === "held"
     ? `stayed at rank ${delta.currentRank}`
     : `${direction} from rank ${delta.previousRank} to ${delta.currentRank}`;
-  const score = `score ${delta.previousScore} to ${delta.currentScore}`;
-  const confidence = delta.previousConfidence === delta.currentConfidence
-    ? `${delta.currentConfidence} confidence`
-    : `confidence ${delta.previousConfidence} to ${delta.currentConfidence}`;
-  return `${rank}, ${score}, ${confidence}`;
+  const score = delta.previousScore === undefined && delta.currentScore === undefined
+    ? ""
+    : `score ${delta.previousScore ?? "unknown"} to ${delta.currentScore ?? "unknown"}`;
+  const confidence = delta.previousConfidence === undefined && delta.currentConfidence === undefined
+    ? ""
+    : delta.previousConfidence === delta.currentConfidence
+      ? `${delta.currentConfidence} confidence`
+      : `confidence ${delta.previousConfidence ?? "unknown"} to ${delta.currentConfidence ?? "unknown"}`;
+  return [rank, score, confidence].filter(Boolean).join(", ");
+}
+
+function formatMetrics(confidence: RankedFile["confidence"] | undefined, score: number | undefined): string {
+  const metrics = [
+    confidence ? `${confidence} confidence` : "",
+    score === undefined ? "" : `score ${score}`
+  ].filter(Boolean);
+  return metrics.length > 0 ? ` (${metrics.join(", ")})` : "";
 }
 
 function appendSection(
diff --git a/packages/core/src/repo-scan.ts b/packages/core/src/repo-scan.ts
index 733ac4e..1700dd9 100644
--- a/packages/core/src/repo-scan.ts
+++ b/packages/core/src/repo-scan.ts
@@ -58,6 +58,7 @@ type ScanState = { count: number; limitReported: boolean };
 const SCAN_CACHE_VERSION = 2;
 const SCAN_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 const SCAN_CACHE_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json$/;
+const SCAN_CACHE_TEMP_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json\.\d+-[0-9a-f-]+\.tmp$/i;
 
 type CachedScan = {
   version: typeof SCAN_CACHE_VERSION;
@@ -282,9 +283,13 @@ async function readScanCache(location: ScanCacheLocation): Promise<CachedScan |
       !Number.isFinite(Date.parse(cached.createdAt)) ||
       Date.now() - Date.parse(cached.createdAt) > SCAN_CACHE_MAX_AGE_MS ||
       !Array.isArray(cached.files) ||
+      !cached.files.every(isCachedRepoFile) ||
       !Array.isArray(cached.trackedFiles) ||
+      !cached.trackedFiles.every((path) => typeof path === "string") ||
       !Array.isArray(cached.packageScripts) ||
+      !cached.packageScripts.every(isCachedPackageScript) ||
       !Array.isArray(cached.diagnostics) ||
+      !cached.diagnostics.every(isCachedDiagnostic) ||
       !["npm", "pnpm", "yarn", "bun"].includes(cached.packageManager ?? "")
     ) return undefined;
     return cached as CachedScan;
@@ -293,6 +298,43 @@ async function readScanCache(location: ScanCacheLocation): Promise<CachedScan |
   }
 }
 
+function isCachedRepoFile(candidate: unknown): candidate is RepoFile {
+  if (!isRecord(candidate)) return false;
+  return typeof candidate.path === "string" && candidate.path.trim().length > 0 &&
+    typeof candidate.extension === "string" &&
+    typeof candidate.sizeBytes === "number" && Number.isFinite(candidate.sizeBytes) && candidate.sizeBytes >= 0 &&
+    typeof candidate.isTest === "boolean" &&
+    typeof candidate.isSource === "boolean" &&
+    (candidate.kind === "code" || candidate.kind === "config" || candidate.kind === "documentation" || candidate.kind === "other") &&
+    typeof candidate.textSample === "string" &&
+    (candidate.textSampleComplete === undefined || typeof candidate.textSampleComplete === "boolean") &&
+    (candidate.textSampleSkipReason === undefined ||
+      candidate.textSampleSkipReason === "too-large" ||
+      candidate.textSampleSkipReason === "not-text" ||
+      candidate.textSampleSkipReason === "unreadable");
+}
+
+function isCachedPackageScript(candidate: unknown): candidate is PackageScript {
+  if (!isRecord(candidate)) return false;
+  return typeof candidate.name === "string" &&
+    typeof candidate.command === "string" &&
+    typeof candidate.packageDir === "string" &&
+    (candidate.packageName === undefined || typeof candidate.packageName === "string");
+}
+
+function isCachedDiagnostic(candidate: unknown): candidate is RepoMap["diagnostics"][number] {
+  if (!isRecord(candidate)) return false;
+  return typeof candidate.code === "string" &&
+    typeof candidate.message === "string" &&
+    (candidate.severity === "info" || candidate.severity === "warning" || candidate.severity === "error") &&
+    (candidate.paths === undefined ||
+      (Array.isArray(candidate.paths) && candidate.paths.every((path) => typeof path === "string")));
+}
+
+function isRecord(candidate: unknown): candidate is Record<string, unknown> {
+  return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
+}
+
 async function writeScanCache(location: ScanCacheLocation, cached: CachedScan): Promise<void> {
   const temporaryPath = `${location.path}.${process.pid}-${randomUUID()}.tmp`;
   try {
@@ -316,7 +358,10 @@ async function pruneExpiredScanCache(cacheRoot: string): Promise<void> {
     const entries = await readdir(cacheRoot, { withFileTypes: true });
     const now = Date.now();
     await Promise.all(entries
-      .filter((entry) => entry.isFile() && SCAN_CACHE_FILE.test(entry.name))
+      // A killed process can leave its uniquely named atomic-write file behind. It is not
+      // readable as a cache entry, but without pruning it the cache directory grows forever.
+      // The same seven-day horizon preserves any plausible active writer.
+      .filter((entry) => entry.isFile() && (SCAN_CACHE_FILE.test(entry.name) || SCAN_CACHE_TEMP_FILE.test(entry.name)))
       .map(async (entry) => {
         const path = join(cacheRoot, entry.name);
         try {
@@ -398,7 +443,7 @@ function isInternalCachePath(root: string, path: string, internalCacheRoot?: str
   // repository. Hide only filenames owned by FixMap's cache format.
   return sameFilesystemPath(internalCacheRoot, root) && (
     SCAN_CACHE_FILE.test(path) ||
-    /^[a-f0-9]{24}-[a-f0-9]{24}\.json\.\d+-[0-9a-f-]+\.tmp$/i.test(path)
+    SCAN_CACHE_TEMP_FILE.test(path)
   );
 }
 
diff --git a/packages/core/src/validate.ts b/packages/core/src/validate.ts
index 9a4d9d8..2872be6 100644
--- a/packages/core/src/validate.ts
+++ b/packages/core/src/validate.ts
@@ -4,7 +4,7 @@ export type ValidatedFixMapReport =
   | { success: true; report: FixMapReport }
   | { success: false; message: string };
 
-/** Validate the report fields read by compare and verify without rejecting additive fields. */
+/** Validate the documented report structure without rejecting additive fields. */
 export function validateFixMapReport(candidate: unknown, label: string): ValidatedFixMapReport {
   if (
     typeof candidate !== "object" ||
@@ -27,8 +27,8 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
     };
   }
   const invalid = contextFiles.findIndex((file) => {
-    if (typeof file !== "object" || file === null) return true;
-    const ranked = file as unknown as Record<string, unknown>;
+    if (!isRecord(file)) return true;
+    const ranked = file;
     if (typeof ranked.path !== "string" || ranked.path.trim().length === 0) return true;
     if (ranked.rank !== undefined && (!Number.isSafeInteger(ranked.rank) || (ranked.rank as number) < 1)) return true;
     if (ranked.score !== undefined && (typeof ranked.score !== "number" || !Number.isFinite(ranked.score))) return true;
@@ -36,6 +36,7 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
       ranked.confidence !== undefined &&
       ranked.confidence !== "high" && ranked.confidence !== "medium" && ranked.confidence !== "low"
     ) return true;
+    if (ranked.reasons !== undefined && !isStringArray(ranked.reasons)) return true;
     return false;
   });
   if (invalid !== -1) {
@@ -43,7 +44,7 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
       success: false,
       message:
         `${label} has an invalid contextFiles entry at index ${invalid}; each entry needs a non-empty string "path", ` +
-        "and optional rank, score, and confidence fields must use their documented types."
+        "and optional rank, score, confidence, and reasons fields must use their documented types."
     };
   }
 
@@ -65,52 +66,112 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
 
   const testRoutes = record.testRoutes as unknown[];
   const invalidRoute = testRoutes.findIndex((route) => {
-    if (typeof route !== "object" || route === null || Array.isArray(route)) return true;
-    const entry = route as Record<string, unknown>;
-    return typeof entry.command !== "string" ||
-      !Array.isArray(entry.relatedFiles) ||
-      !entry.relatedFiles.every((path) => typeof path === "string");
+    if (!isRecord(route)) return true;
+    return typeof route.command !== "string" || !route.command.trim() ||
+      !isNonBlankStringArray(route.relatedFiles) ||
+      (route.kind !== undefined && route.kind !== "test" && route.kind !== "validation") ||
+      (route.reason !== undefined && typeof route.reason !== "string");
   });
   if (invalidRoute !== -1) {
     return {
       success: false,
       message:
         `${label} has an invalid testRoutes entry at index ${invalidRoute}; each route needs a string "command" ` +
-        "and a string array named relatedFiles."
+        "and an array of non-empty string paths named relatedFiles; optional kind and reason fields must use their documented types."
     };
   }
 
   const risks = record.risks as unknown[];
   const invalidRisk = risks.findIndex((risk) => {
-    if (typeof risk !== "object" || risk === null || Array.isArray(risk)) return true;
-    return typeof (risk as Record<string, unknown>).area !== "string";
+    if (!isRecord(risk)) return true;
+    return typeof risk.area !== "string" || !risk.area.trim() ||
+      (risk.reason !== undefined && typeof risk.reason !== "string") ||
+      (risk.severity !== undefined && risk.severity !== "low" && risk.severity !== "medium" && risk.severity !== "high");
   });
   if (invalidRisk !== -1) {
     return {
       success: false,
-      message: `${label} has an invalid risks entry at index ${invalidRisk}; each risk needs a string "area".`
+      message: `${label} has an invalid risks entry at index ${invalidRisk}; each risk needs a non-empty string "area", and optional reason and severity fields must use their documented types.`
     };
   }
 
-  if (!(record.changedFiles as unknown[]).every((path) => typeof path === "string")) {
-    return { success: false, message: `${label} has invalid changedFiles; every entry must be a string path.` };
+  if (!isNonBlankStringArray(record.changedFiles)) {
+    return { success: false, message: `${label} has invalid changedFiles; every entry must be a non-empty string path.` };
+  }
+
+  const diagnostics = record.diagnostics as unknown[];
+  const invalidDiagnostic = diagnostics.findIndex((diagnostic) => {
+    if (!isRecord(diagnostic)) return true;
+    return typeof diagnostic.code !== "string" || !diagnostic.code.trim() ||
+      typeof diagnostic.message !== "string" ||
+      (diagnostic.severity !== "info" && diagnostic.severity !== "warning" && diagnostic.severity !== "error") ||
+      (diagnostic.paths !== undefined && !isNonBlankStringArray(diagnostic.paths));
+  });
+  if (invalidDiagnostic !== -1) {
+    return {
+      success: false,
+      message:
+        `${label} has an invalid diagnostics entry at index ${invalidDiagnostic}; each diagnostic needs string code and message fields, ` +
+        "an info, warning, or error severity, and optional non-empty string paths."
+    };
   }
 
   if (record.analysis !== undefined) {
     const analysis = record.analysis;
-    const grounding = typeof analysis === "object" && analysis !== null && !Array.isArray(analysis)
-      ? (analysis as Record<string, unknown>).grounding
-      : undefined;
-    const specificity = typeof grounding === "object" && grounding !== null && !Array.isArray(grounding)
-      ? (grounding as Record<string, unknown>).specificity
-      : undefined;
+    const grounding = isRecord(analysis) ? analysis.grounding : undefined;
+    const specificity = isRecord(grounding) ? grounding.specificity : undefined;
     if (specificity !== "anchored" && specificity !== "descriptive" && specificity !== "vague") {
       return {
         success: false,
         message: `${label} has invalid analysis.grounding.specificity; expected anchored, descriptive, or vague.`
       };
     }
+    if (!isRecord(analysis) || !isRecord(grounding) ||
+      !Array.isArray(grounding.identifiers) ||
+      !isStringArray(grounding.unresolvedIdentifiers) ||
+      !isStringArray(grounding.partiallyResolvedIdentifiers) ||
+      !isStringArray(grounding.unverifiedIdentifiers) ||
+      typeof grounding.scanComplete !== "boolean" ||
+      !isRecord(analysis.ranking) ||
+      !isNullableFiniteNumber(analysis.ranking.topScore) ||
+      !isNullableFiniteNumber(analysis.ranking.runnerUpScore) ||
+      !isNullableFiniteNumber(analysis.ranking.topGap) ||
+      typeof analysis.ranking.clustered !== "boolean" ||
+      typeof analysis.nextAction !== "string") {
+      return {
+        success: false,
+        message: `${label} has incomplete or invalid analysis grounding, ranking, or nextAction fields.`
+      };
+    }
+    const invalidIdentifier = grounding.identifiers.findIndex((identifier) =>
+      !isRecord(identifier) ||
+      typeof identifier.identifier !== "string" || !identifier.identifier.trim() ||
+      typeof identifier.status !== "string" || !identifier.status.trim() ||
+      !isNonBlankStringArray(identifier.matchedFiles)
+    );
+    if (invalidIdentifier !== -1) {
+      return {
+        success: false,
+        message: `${label} has an invalid analysis.grounding.identifiers entry at index ${invalidIdentifier}.`
+      };
+    }
   }
 
   return { success: true, report: candidate as FixMapReport };
 }
+
+function isRecord(candidate: unknown): candidate is Record<string, unknown> {
+  return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
+}
+
+function isStringArray(candidate: unknown): candidate is string[] {
+  return Array.isArray(candidate) && candidate.every((entry) => typeof entry === "string");
+}
+
+function isNonBlankStringArray(candidate: unknown): candidate is string[] {
+  return isStringArray(candidate) && candidate.every((entry) => entry.trim().length > 0);
+}
+
+function isNullableFiniteNumber(candidate: unknown): boolean {
+  return candidate === null || (typeof candidate === "number" && Number.isFinite(candidate));
+}
diff --git a/packages/core/test/compare.test.ts b/packages/core/test/compare.test.ts
index b800290..46b55fb 100644
--- a/packages/core/test/compare.test.ts
+++ b/packages/core/test/compare.test.ts
@@ -128,4 +128,23 @@ describe("compareReports", () => {
     expect(markdown).toContain("`b.ts`");
     expect(markdown).toContain("confidence medium to high");
   });
+
+  it("renders compatible legacy entries without leaking undefined values", () => {
+    const legacy = (paths: string[]) => ({
+      summary: "",
+      contextFiles: paths.map((path) => ({ path })),
+      testRoutes: [],
+      risks: [],
+      changedFiles: [],
+      diagnostics: []
+    }) as unknown as FixMapReport;
+
+    const entered = renderComparisonMarkdown(compareReports(legacy(["a.ts"]), legacy(["a.ts", "b.ts"])));
+    const moved = renderComparisonMarkdown(compareReports(legacy(["a.ts", "b.ts"]), legacy(["b.ts", "a.ts"])));
+
+    expect(entered).toContain("`b.ts` at rank 2");
+    expect(moved).toContain("rose from rank 2 to 1");
+    expect(entered).not.toContain("undefined");
+    expect(moved).not.toContain("undefined");
+  });
 });
diff --git a/packages/core/test/repo-scan.test.ts b/packages/core/test/repo-scan.test.ts
index eb897e3..13008f3 100644
--- a/packages/core/test/repo-scan.test.ts
+++ b/packages/core/test/repo-scan.test.ts
@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { mkdtemp, mkdir, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
+import { mkdtemp, mkdir, readFile, readdir, rm, symlink, utimes, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { promisify } from "node:util";
@@ -677,6 +677,39 @@ describe("scanRepo", () => {
     }
   });
 
+  it("prunes abandoned atomic cache writes but preserves recent writers", { timeout: 30_000 }, async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-cache-temp-repo-"));
+    const cacheRoot = await mkdtemp(join(tmpdir(), "fixmap-cache-temp-store-"));
+    const previousCache = process.env.FIXMAP_CACHE_DIR;
+    process.env.FIXMAP_CACHE_DIR = cacheRoot;
+    try {
+      await writeFile(join(root, "index.ts"), "export const value = 1;\n");
+      await exec("git", ["init", "-b", "main"], { cwd: root });
+      await exec("git", ["config", "user.email", "test@example.com"], { cwd: root });
+      await exec("git", ["config", "user.name", "Test User"], { cwd: root });
+      await exec("git", ["add", "."], { cwd: root });
+      await exec("git", ["commit", "-m", "initial"], { cwd: root });
+
+      const prefix = "aaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbbbbbbbbbb.json";
+      const stale = `${prefix}.123-00000000-0000-4000-8000-000000000001.tmp`;
+      const recent = `${prefix}.124-00000000-0000-4000-8000-000000000002.tmp`;
+      await writeFile(join(cacheRoot, stale), "partial");
+      await writeFile(join(cacheRoot, recent), "partial");
+      const old = new Date(Date.now() - 8 * 24 * 60 * 60 * 1000);
+      await utimes(join(cacheRoot, stale), old, old);
+
+      await scanRepo({ repoRoot: root, useCache: true });
+      const entries = await readdir(cacheRoot);
+      expect(entries).not.toContain(stale);
+      expect(entries).toContain(recent);
+    } finally {
+      if (previousCache === undefined) delete process.env.FIXMAP_CACHE_DIR;
+      else process.env.FIXMAP_CACHE_DIR = previousCache;
+      await rm(cacheRoot, { recursive: true, force: true });
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
   it("heals a corrupt exact-state cache and never serves partial JSON", { timeout: 30_000 }, async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-cache-corrupt-repo-"));
     const cacheRoot = await mkdtemp(join(tmpdir(), "fixmap-cache-corrupt-store-"));
@@ -707,6 +740,38 @@ describe("scanRepo", () => {
     }
   });
 
+  it("heals a parseable cache whose nested scan data is structurally damaged", { timeout: 30_000 }, async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-cache-shape-repo-"));
+    const cacheRoot = await mkdtemp(join(tmpdir(), "fixmap-cache-shape-store-"));
+    const previousCache = process.env.FIXMAP_CACHE_DIR;
+    process.env.FIXMAP_CACHE_DIR = cacheRoot;
+    try {
+      await writeFile(join(root, "index.ts"), "export const value = 1;\n");
+      await exec("git", ["init", "-b", "main"], { cwd: root });
+      await exec("git", ["config", "user.email", "test@example.com"], { cwd: root });
+      await exec("git", ["config", "user.name", "Test User"], { cwd: root });
+      await exec("git", ["add", "."], { cwd: root });
+      await exec("git", ["commit", "-m", "initial"], { cwd: root });
+
+      await scanRepo({ repoRoot: root, useCache: true });
+      const cachePath = join(cacheRoot, (await readdir(cacheRoot))[0]!);
+      const cached = JSON.parse(await readFile(cachePath, "utf8")) as Record<string, unknown>;
+      cached.files = [null];
+      await writeFile(cachePath, `${JSON.stringify(cached)}\n`);
+
+      const repaired = await scanRepo({ repoRoot: root, useCache: true });
+      expect(repaired.diagnostics.map((entry) => entry.code)).not.toContain("cache-hit");
+      expect(repaired.files.map((file) => file.path)).toEqual(["index.ts"]);
+      expect((await scanRepo({ repoRoot: root, useCache: true })).diagnostics.map((entry) => entry.code))
+        .toContain("cache-hit");
+    } finally {
+      if (previousCache === undefined) delete process.env.FIXMAP_CACHE_DIR;
+      else process.env.FIXMAP_CACHE_DIR = previousCache;
+      await rm(cacheRoot, { recursive: true, force: true });
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
   it("keeps the exact-state cache valid across concurrent first scans", { timeout: 30_000 }, async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-cache-concurrent-repo-"));
     const cacheRoot = await mkdtemp(join(tmpdir(), "fixmap-cache-concurrent-store-"));
diff --git a/packages/core/test/validate.test.ts b/packages/core/test/validate.test.ts
index 0edeff5..6664fd5 100644
--- a/packages/core/test/validate.test.ts
+++ b/packages/core/test/validate.test.ts
@@ -51,12 +51,42 @@ describe("validateFixMapReport", () => {
   it.each([
     [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], testRoutes: [null] }, "testRoutes entry"],
     [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], testRoutes: [{ command: "npm test" }] }, "relatedFiles"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts", reasons: [42] }] }, "contextFiles entry"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], testRoutes: [{ command: " ", relatedFiles: [] }] }, "testRoutes entry"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], testRoutes: [{ command: "npm test", relatedFiles: [], kind: "check" }] }, "testRoutes entry"],
     [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], risks: [null] }, "risks entry"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], risks: [{ area: " ", severity: "low" }] }, "risks entry"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], risks: [{ area: "auth", severity: "critical" }] }, "risks entry"],
     [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], changedFiles: [42] }, "changedFiles"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], analysis: {} }, "analysis.grounding.specificity"]
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], changedFiles: [" "] }, "changedFiles"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], diagnostics: [null] }, "diagnostics entry"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], diagnostics: [{ code: "x", message: "x", severity: "warning", paths: [""] }] }, "diagnostics entry"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], analysis: {} }, "analysis.grounding.specificity"],
+    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], analysis: { grounding: { specificity: "anchored" } } }, "incomplete or invalid analysis"]
   ])("rejects consumer-unsafe nested report data: %s", (candidate, message) => {
     const result = validateFixMapReport(candidate, "report");
     expect(result.success).toBe(false);
     if (!result.success) expect(result.message).toContain(message);
   });
+
+  it("accepts a complete analysis while leaving additive fields alone", () => {
+    const result = validateFixMapReport({
+      ...envelope,
+      futureField: { remains: "allowed" },
+      analysis: {
+        grounding: {
+          specificity: "anchored",
+          identifiers: [{ identifier: "sendMail", status: "exact-definition", matchedFiles: ["src/mail.ts"] }],
+          unresolvedIdentifiers: [],
+          partiallyResolvedIdentifiers: [],
+          unverifiedIdentifiers: [],
+          scanComplete: true
+        },
+        ranking: { topScore: 20, runnerUpScore: null, topGap: null, clustered: false },
+        nextAction: "Inspect src/mail.ts."
+      }
+    }, "report");
+
+    expect(result.success).toBe(true);
+  });
 });

From b50c49bcd516f715ed39ee0b87656d7dcd8dea12 Mon Sep 17 00:00:00 2001
From: Aryam Goyal <aryamgoyal18@gmail.com>
Date: Sun, 9 Aug 2026 16:00:04 +0530
Subject: [PATCH 05/10] Reject malformed versioned reports and caches

---
 packages/action/dist/index.mjs       | 74 ++++++++++++++-------
 packages/action/test/runner.test.ts  | 14 ++++
 packages/cli/test/cli-runner.test.ts | 16 +++++
 packages/cli/test/mcp.test.ts        | 27 +++++++-
 packages/core/src/repo-scan.ts       | 43 ++++++++-----
 packages/core/src/validate.ts        | 71 +++++++++++++-------
 packages/core/test/repo-scan.test.ts | 53 +++++++++++++++
 packages/core/test/validate.test.ts  | 96 +++++++++++++++++++++++-----
 8 files changed, 315 insertions(+), 79 deletions(-)

diff --git a/packages/action/dist/index.mjs b/packages/action/dist/index.mjs
index 13acd7f..c579d06 100644
--- a/packages/action/dist/index.mjs
+++ b/packages/action/dist/index.mjs
@@ -1947,6 +1947,7 @@ var GIT_MAX_BUFFER = 10 * 1024 * 1024;
 var exec = promisify(execFile);
 var SCAN_CACHE_VERSION = 2;
 var SCAN_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+var SCAN_CACHE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
 var SCAN_CACHE_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json$/;
 var SCAN_CACHE_TEMP_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json\.\d+-[0-9a-f-]+\.tmp$/i;
 async function scanRepo(input) {
@@ -2103,7 +2104,8 @@ async function buildScanCacheLocation(root, cacheRoot, internalPaths) {
 async function readScanCache(location) {
   try {
     const cached = JSON.parse(await readFile(location.path, "utf8"));
-    if (cached.version !== SCAN_CACHE_VERSION || cached.stateKey !== location.stateKey || typeof cached.createdAt !== "string" || !Number.isFinite(Date.parse(cached.createdAt)) || Date.now() - Date.parse(cached.createdAt) > SCAN_CACHE_MAX_AGE_MS || !Array.isArray(cached.files) || !cached.files.every(isCachedRepoFile) || !Array.isArray(cached.trackedFiles) || !cached.trackedFiles.every((path) => typeof path === "string") || !Array.isArray(cached.packageScripts) || !cached.packageScripts.every(isCachedPackageScript) || !Array.isArray(cached.diagnostics) || !cached.diagnostics.every(isCachedDiagnostic) || !["npm", "pnpm", "yarn", "bun"].includes(cached.packageManager ?? ""))
+    const createdAt = typeof cached.createdAt === "string" ? Date.parse(cached.createdAt) : Number.NaN;
+    if (cached.version !== SCAN_CACHE_VERSION || cached.stateKey !== location.stateKey || typeof cached.createdAt !== "string" || !Number.isFinite(createdAt) || Date.now() - createdAt > SCAN_CACHE_MAX_AGE_MS || createdAt - Date.now() > SCAN_CACHE_MAX_FUTURE_SKEW_MS || !Array.isArray(cached.files) || !cached.files.every(isCachedRepoFile) || !Array.isArray(cached.trackedFiles) || !cached.trackedFiles.every(isCachedRelativePath) || !Array.isArray(cached.packageScripts) || !cached.packageScripts.every(isCachedPackageScript) || !Array.isArray(cached.diagnostics) || !cached.diagnostics.every(isCachedDiagnostic) || !["npm", "pnpm", "yarn", "bun"].includes(cached.packageManager ?? ""))
       return void 0;
     return cached;
   } catch {
@@ -2113,21 +2115,29 @@ async function readScanCache(location) {
 function isCachedRepoFile(candidate) {
   if (!isRecord(candidate))
     return false;
-  return typeof candidate.path === "string" && candidate.path.trim().length > 0 && typeof candidate.extension === "string" && typeof candidate.sizeBytes === "number" && Number.isFinite(candidate.sizeBytes) && candidate.sizeBytes >= 0 && typeof candidate.isTest === "boolean" && typeof candidate.isSource === "boolean" && (candidate.kind === "code" || candidate.kind === "config" || candidate.kind === "documentation" || candidate.kind === "other") && typeof candidate.textSample === "string" && (candidate.textSampleComplete === void 0 || typeof candidate.textSampleComplete === "boolean") && (candidate.textSampleSkipReason === void 0 || candidate.textSampleSkipReason === "too-large" || candidate.textSampleSkipReason === "not-text" || candidate.textSampleSkipReason === "unreadable");
+  const validSkipReason = candidate.textSampleSkipReason === "too-large" || candidate.textSampleSkipReason === "not-text" || candidate.textSampleSkipReason === "unreadable";
+  return isCachedRelativePath(candidate.path) && typeof candidate.extension === "string" && typeof candidate.sizeBytes === "number" && Number.isFinite(candidate.sizeBytes) && candidate.sizeBytes >= 0 && typeof candidate.isTest === "boolean" && typeof candidate.isSource === "boolean" && (candidate.kind === "code" || candidate.kind === "config" || candidate.kind === "documentation" || candidate.kind === "other") && typeof candidate.textSample === "string" && typeof candidate.textSampleComplete === "boolean" && (candidate.textSampleComplete && candidate.textSampleSkipReason === void 0 || !candidate.textSampleComplete && validSkipReason);
 }
 function isCachedPackageScript(candidate) {
   if (!isRecord(candidate))
     return false;
-  return typeof candidate.name === "string" && typeof candidate.command === "string" && typeof candidate.packageDir === "string" && (candidate.packageName === void 0 || typeof candidate.packageName === "string");
+  return typeof candidate.name === "string" && candidate.name.trim().length > 0 && typeof candidate.command === "string" && (candidate.packageDir === "" || isCachedRelativePath(candidate.packageDir)) && (candidate.packageName === void 0 || typeof candidate.packageName === "string" && candidate.packageName.trim().length > 0);
 }
 function isCachedDiagnostic(candidate) {
   if (!isRecord(candidate))
     return false;
-  return typeof candidate.code === "string" && typeof candidate.message === "string" && (candidate.severity === "info" || candidate.severity === "warning" || candidate.severity === "error") && (candidate.paths === void 0 || Array.isArray(candidate.paths) && candidate.paths.every((path) => typeof path === "string"));
+  return typeof candidate.code === "string" && candidate.code.trim().length > 0 && typeof candidate.message === "string" && candidate.message.trim().length > 0 && (candidate.severity === "info" || candidate.severity === "warning" || candidate.severity === "error") && (candidate.paths === void 0 || Array.isArray(candidate.paths) && candidate.paths.every(isCachedRelativePath));
 }
 function isRecord(candidate) {
   return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
 }
+function isCachedRelativePath(candidate) {
+  if (typeof candidate !== "string" || candidate.trim().length === 0 || candidate.includes("\0") || isAbsolute(candidate) || /^[A-Za-z]:[\\/]/.test(candidate)) {
+    return false;
+  }
+  const segments = normalizePath(candidate).split("/");
+  return segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
 async function writeScanCache(location, cached) {
   const temporaryPath = `${location.path}.${process.pid}-${randomUUID()}.tmp`;
   try {
@@ -2866,7 +2876,6 @@ function validateFixMapReport(candidate, label) {
       message: `${label} is not a FixMap JSON report: no contextFiles array.`
     };
   }
-  const contextFiles = candidate.contextFiles;
   const record = candidate;
   if (record.reportVersion !== void 0 && record.reportVersion !== 1) {
     return {
@@ -2874,46 +2883,64 @@ function validateFixMapReport(candidate, label) {
       message: `${label} uses unsupported reportVersion ${JSON.stringify(record.reportVersion)}; this FixMap release supports reportVersion 1.`
     };
   }
+  const invalidEnvelopeFields = [
+    typeof record.summary === "string" ? void 0 : "summary (string)",
+    Array.isArray(record.testRoutes) ? void 0 : "testRoutes (array)",
+    Array.isArray(record.risks) ? void 0 : "risks (array)",
+    Array.isArray(record.changedFiles) ? void 0 : "changedFiles (array)",
+    Array.isArray(record.diagnostics) ? void 0 : "diagnostics (array)"
+  ].filter((field) => field !== void 0);
+  if (invalidEnvelopeFields.length > 0) {
+    return {
+      success: false,
+      message: `${label} is missing or has invalid fields in the complete FixMap report envelope: ${invalidEnvelopeFields.join(", ")}.`
+    };
+  }
+  const versioned = record.reportVersion === 1;
+  const contextFiles = candidate.contextFiles;
   const invalid = contextFiles.findIndex((file) => {
     if (!isRecord2(file))
       return true;
     const ranked = file;
     if (typeof ranked.path !== "string" || ranked.path.trim().length === 0)
       return true;
-    if (ranked.rank !== void 0 && (!Number.isSafeInteger(ranked.rank) || ranked.rank < 1))
+    if ((versioned || ranked.rank !== void 0) && (!Number.isSafeInteger(ranked.rank) || ranked.rank < 1))
       return true;
-    if (ranked.score !== void 0 && (typeof ranked.score !== "number" || !Number.isFinite(ranked.score)))
+    if ((versioned || ranked.score !== void 0) && (typeof ranked.score !== "number" || !Number.isFinite(ranked.score)))
       return true;
-    if (ranked.confidence !== void 0 && ranked.confidence !== "high" && ranked.confidence !== "medium" && ranked.confidence !== "low")
+    if ((versioned || ranked.confidence !== void 0) && ranked.confidence !== "high" && ranked.confidence !== "medium" && ranked.confidence !== "low")
       return true;
-    if (ranked.reasons !== void 0 && !isStringArray(ranked.reasons))
+    if ((versioned || ranked.reasons !== void 0) && !isStringArray(ranked.reasons))
       return true;
     return false;
   });
   if (invalid !== -1) {
     return {
       success: false,
-      message: `${label} has an invalid contextFiles entry at index ${invalid}; each entry needs a non-empty string "path", and optional rank, score, confidence, and reasons fields must use their documented types.`
+      message: `${label} has an invalid contextFiles entry at index ${invalid}; each entry needs a non-empty string "path", ${versioned ? "and version 1 requires" : "and optional"} rank, score, confidence, and reasons fields with their documented types.`
     };
   }
-  const invalidEnvelopeFields = [
-    typeof record.summary === "string" ? void 0 : "summary (string)",
-    Array.isArray(record.testRoutes) ? void 0 : "testRoutes (array)",
-    Array.isArray(record.risks) ? void 0 : "risks (array)",
-    Array.isArray(record.changedFiles) ? void 0 : "changedFiles (array)",
-    Array.isArray(record.diagnostics) ? void 0 : "diagnostics (array)"
-  ].filter((field) => field !== void 0);
-  if (invalidEnvelopeFields.length > 0) {
+  const duplicatePath = contextFiles.findIndex((file, index) => contextFiles.findIndex((candidate2) => candidate2.path === file.path) !== index);
+  if (duplicatePath !== -1) {
     return {
       success: false,
-      message: `${label} is missing or has invalid fields in the complete FixMap report envelope: ${invalidEnvelopeFields.join(", ")}.`
+      message: `${label} has a duplicate contextFiles path at index ${duplicatePath}; each ranked path must appear once.`
     };
   }
+  if (versioned) {
+    const outOfOrderRank = contextFiles.findIndex((file, index) => file.rank !== index + 1);
+    if (outOfOrderRank !== -1) {
+      return {
+        success: false,
+        message: `${label} has an out-of-order contextFiles rank at index ${outOfOrderRank}; version 1 ranks must be sequential and match array order.`
+      };
+    }
+  }
   const testRoutes = record.testRoutes;
   const invalidRoute = testRoutes.findIndex((route) => {
     if (!isRecord2(route))
       return true;
-    return typeof route.command !== "string" || !route.command.trim() || !isNonBlankStringArray(route.relatedFiles) || route.kind !== void 0 && route.kind !== "test" && route.kind !== "validation" || route.reason !== void 0 && typeof route.reason !== "string";
+    return typeof route.command !== "string" || !route.command.trim() || !isNonBlankStringArray(route.relatedFiles) || (versioned || route.kind !== void 0) && route.kind !== "test" && route.kind !== "validation" || (versioned || route.reason !== void 0) && typeof route.reason !== "string";
   });
   if (invalidRoute !== -1) {
     return {
@@ -2925,7 +2952,7 @@ function validateFixMapReport(candidate, label) {
   const invalidRisk = risks.findIndex((risk) => {
     if (!isRecord2(risk))
       return true;
-    return typeof risk.area !== "string" || !risk.area.trim() || risk.reason !== void 0 && typeof risk.reason !== "string" || risk.severity !== void 0 && risk.severity !== "low" && risk.severity !== "medium" && risk.severity !== "high";
+    return typeof risk.area !== "string" || !risk.area.trim() || (versioned || risk.reason !== void 0) && typeof risk.reason !== "string" || (versioned || risk.severity !== void 0) && risk.severity !== "low" && risk.severity !== "medium" && risk.severity !== "high";
   });
   if (invalidRisk !== -1) {
     return {
@@ -2964,7 +2991,7 @@ function validateFixMapReport(candidate, label) {
         message: `${label} has incomplete or invalid analysis grounding, ranking, or nextAction fields.`
       };
     }
-    const invalidIdentifier = grounding.identifiers.findIndex((identifier) => !isRecord2(identifier) || typeof identifier.identifier !== "string" || !identifier.identifier.trim() || typeof identifier.status !== "string" || !identifier.status.trim() || !isNonBlankStringArray(identifier.matchedFiles));
+    const invalidIdentifier = grounding.identifiers.findIndex((identifier) => !isRecord2(identifier) || typeof identifier.identifier !== "string" || !identifier.identifier.trim() || !isIdentifierStatus(identifier.status) || !isNonBlankStringArray(identifier.matchedFiles));
     if (invalidIdentifier !== -1) {
       return {
         success: false,
@@ -2986,6 +3013,9 @@ function isNonBlankStringArray(candidate) {
 function isNullableFiniteNumber(candidate) {
   return candidate === null || typeof candidate === "number" && Number.isFinite(candidate);
 }
+function isIdentifierStatus(candidate) {
+  return candidate === "exact-definition" || candidate === "exact-text" || candidate === "partial-definition" || candidate === "not-found" || candidate === "unverified";
+}
 
 // packages/action/src/github.ts
 var FIXMAP_REPORT_MARKER = "<!-- fixmap-report -->";
diff --git a/packages/action/test/runner.test.ts b/packages/action/test/runner.test.ts
index 2e8cf52..044f4c9 100644
--- a/packages/action/test/runner.test.ts
+++ b/packages/action/test/runner.test.ts
@@ -205,6 +205,20 @@ describe("GitHub Action runner", () => {
     expect(scanRepo).not.toHaveBeenCalled();
   });
 
+  it("rejects an incomplete marked version 1 entry before scanning", async () => {
+    const scanRepo = vi.fn(async () => scannedRepo(["src/auth.ts"]));
+    await expect(runAction({
+      INPUT_MODE: "verify",
+      INPUT_REPORT_PATH: "plan.json",
+      INPUT_DIFF: "main...HEAD"
+    }, {
+      readFile: () => JSON.stringify({ ...report, reportVersion: 1, contextFiles: [{ path: "src/auth.ts" }] }),
+      scanRepo,
+      stdout: vi.fn()
+    })).rejects.toThrow("version 1 requires");
+    expect(scanRepo).not.toHaveBeenCalled();
+  });
+
   it("says what verify mode needs when report-path is missing", async () => {
     await expect(runAction({ INPUT_MODE: "verify", INPUT_DIFF: "main...HEAD" }, { stdout: vi.fn() }))
       .rejects.toThrow("report-path");
diff --git a/packages/cli/test/cli-runner.test.ts b/packages/cli/test/cli-runner.test.ts
index 47f6075..7392d0e 100644
--- a/packages/cli/test/cli-runner.test.ts
+++ b/packages/cli/test/cli-runner.test.ts
@@ -221,6 +221,22 @@ describe("CLI argument handling", () => {
     expect(verifyIo.stderr.join("")).not.toContain("Cannot read properties");
   });
 
+  it("rejects incomplete marked version 1 entries while accepting legacy partial entries", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-versioned-report-"));
+    const versionedPath = join(root, "versioned.json");
+    const legacyPath = join(root, "legacy.json");
+    const partial = { ...report, contextFiles: [{ path: "src/reset.ts" }] };
+    await writeFile(versionedPath, JSON.stringify({ ...partial, reportVersion: 1 }));
+    await writeFile(legacyPath, JSON.stringify({ ...partial, reportVersion: undefined }));
+    const versionedIo = capture();
+    const legacyIo = capture();
+
+    expect(await runCli(["validate", versionedPath], versionedIo.dependencies)).toBe(1);
+    expect(versionedIo.stderr.join("")).toContain("version 1 requires");
+    expect(await runCli(["validate", legacyPath, "--format", "json"], legacyIo.dependencies)).toBe(0);
+    expect(JSON.parse(legacyIo.stdout.join(""))).toMatchObject({ valid: true, reportVersion: "legacy" });
+  });
+
   it("does not let a nested version flag short-circuit the requested command", async () => {
     const io = capture();
     const exitCode = await runCli(["plan", "--version"], io.dependencies);
diff --git a/packages/cli/test/mcp.test.ts b/packages/cli/test/mcp.test.ts
index 9081261..0ebbdfe 100644
--- a/packages/cli/test/mcp.test.ts
+++ b/packages/cli/test/mcp.test.ts
@@ -223,11 +223,12 @@ describe("fixmap mcp server", () => {
     [{ path: "a.ts", confidence: "certain" }, "confidence"]
   ])("rejects malformed optional comparison fields in %j", async (entry, expectedField) => {
     const client = await connectClient();
+    const envelope = { summary: "", testRoutes: [], risks: [], changedFiles: [], diagnostics: [] };
     const result = await client.callTool({
       name: "fixmap_compare",
       arguments: {
-        previous: { contextFiles: [entry] },
-        current: { contextFiles: [{ path: "a.ts" }] }
+        previous: { ...envelope, contextFiles: [entry] },
+        current: { ...envelope, contextFiles: [{ path: "a.ts" }] }
       }
     });
 
@@ -354,6 +355,28 @@ describe("fixmap mcp server", () => {
     expect(text).not.toContain("Cannot read properties");
   });
 
+  it("rejects incomplete marked version 1 entries before verify scans", async () => {
+    const client = await connectClient();
+    const result = await client.callTool({
+      name: "fixmap_verify",
+      arguments: {
+        report: {
+          reportVersion: 1,
+          summary: "Incomplete versioned report",
+          contextFiles: [{ path: "src/auth/reset-password.ts" }],
+          testRoutes: [],
+          risks: [],
+          changedFiles: [],
+          diagnostics: []
+        },
+        diff: "HEAD"
+      }
+    });
+
+    expect(result.isError).toBe(true);
+    expect((result.content as Array<{ text: string }>)[0]?.text).toContain("version 1 requires");
+  });
+
   it("says why a report path did not work instead of only naming the object shape", async () => {
     const client = await connectClient();
 
diff --git a/packages/core/src/repo-scan.ts b/packages/core/src/repo-scan.ts
index 1700dd9..97f9a36 100644
--- a/packages/core/src/repo-scan.ts
+++ b/packages/core/src/repo-scan.ts
@@ -57,6 +57,7 @@ const exec = promisify(execFile);
 type ScanState = { count: number; limitReported: boolean };
 const SCAN_CACHE_VERSION = 2;
 const SCAN_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const SCAN_CACHE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1000;
 const SCAN_CACHE_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json$/;
 const SCAN_CACHE_TEMP_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json\.\d+-[0-9a-f-]+\.tmp$/i;
 
@@ -276,16 +277,18 @@ async function buildScanCacheLocation(
 async function readScanCache(location: ScanCacheLocation): Promise<CachedScan | undefined> {
   try {
     const cached = JSON.parse(await readFile(location.path, "utf8")) as Partial<CachedScan>;
+    const createdAt = typeof cached.createdAt === "string" ? Date.parse(cached.createdAt) : Number.NaN;
     if (
       cached.version !== SCAN_CACHE_VERSION ||
       cached.stateKey !== location.stateKey ||
       typeof cached.createdAt !== "string" ||
-      !Number.isFinite(Date.parse(cached.createdAt)) ||
-      Date.now() - Date.parse(cached.createdAt) > SCAN_CACHE_MAX_AGE_MS ||
+      !Number.isFinite(createdAt) ||
+      Date.now() - createdAt > SCAN_CACHE_MAX_AGE_MS ||
+      createdAt - Date.now() > SCAN_CACHE_MAX_FUTURE_SKEW_MS ||
       !Array.isArray(cached.files) ||
       !cached.files.every(isCachedRepoFile) ||
       !Array.isArray(cached.trackedFiles) ||
-      !cached.trackedFiles.every((path) => typeof path === "string") ||
+      !cached.trackedFiles.every(isCachedRelativePath) ||
       !Array.isArray(cached.packageScripts) ||
       !cached.packageScripts.every(isCachedPackageScript) ||
       !Array.isArray(cached.diagnostics) ||
@@ -300,41 +303,51 @@ async function readScanCache(location: ScanCacheLocation): Promise<CachedScan |
 
 function isCachedRepoFile(candidate: unknown): candidate is RepoFile {
   if (!isRecord(candidate)) return false;
-  return typeof candidate.path === "string" && candidate.path.trim().length > 0 &&
+  const validSkipReason = candidate.textSampleSkipReason === "too-large" ||
+    candidate.textSampleSkipReason === "not-text" || candidate.textSampleSkipReason === "unreadable";
+  return isCachedRelativePath(candidate.path) &&
     typeof candidate.extension === "string" &&
     typeof candidate.sizeBytes === "number" && Number.isFinite(candidate.sizeBytes) && candidate.sizeBytes >= 0 &&
     typeof candidate.isTest === "boolean" &&
     typeof candidate.isSource === "boolean" &&
     (candidate.kind === "code" || candidate.kind === "config" || candidate.kind === "documentation" || candidate.kind === "other") &&
     typeof candidate.textSample === "string" &&
-    (candidate.textSampleComplete === undefined || typeof candidate.textSampleComplete === "boolean") &&
-    (candidate.textSampleSkipReason === undefined ||
-      candidate.textSampleSkipReason === "too-large" ||
-      candidate.textSampleSkipReason === "not-text" ||
-      candidate.textSampleSkipReason === "unreadable");
+    typeof candidate.textSampleComplete === "boolean" &&
+    ((candidate.textSampleComplete && candidate.textSampleSkipReason === undefined) ||
+      (!candidate.textSampleComplete && validSkipReason));
 }
 
 function isCachedPackageScript(candidate: unknown): candidate is PackageScript {
   if (!isRecord(candidate)) return false;
-  return typeof candidate.name === "string" &&
+  return typeof candidate.name === "string" && candidate.name.trim().length > 0 &&
     typeof candidate.command === "string" &&
-    typeof candidate.packageDir === "string" &&
-    (candidate.packageName === undefined || typeof candidate.packageName === "string");
+    (candidate.packageDir === "" || isCachedRelativePath(candidate.packageDir)) &&
+    (candidate.packageName === undefined ||
+      (typeof candidate.packageName === "string" && candidate.packageName.trim().length > 0));
 }
 
 function isCachedDiagnostic(candidate: unknown): candidate is RepoMap["diagnostics"][number] {
   if (!isRecord(candidate)) return false;
-  return typeof candidate.code === "string" &&
-    typeof candidate.message === "string" &&
+  return typeof candidate.code === "string" && candidate.code.trim().length > 0 &&
+    typeof candidate.message === "string" && candidate.message.trim().length > 0 &&
     (candidate.severity === "info" || candidate.severity === "warning" || candidate.severity === "error") &&
     (candidate.paths === undefined ||
-      (Array.isArray(candidate.paths) && candidate.paths.every((path) => typeof path === "string")));
+      (Array.isArray(candidate.paths) && candidate.paths.every(isCachedRelativePath)));
 }
 
 function isRecord(candidate: unknown): candidate is Record<string, unknown> {
   return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
 }
 
+function isCachedRelativePath(candidate: unknown): candidate is string {
+  if (typeof candidate !== "string" || candidate.trim().length === 0 || candidate.includes("\0") ||
+    isAbsolute(candidate) || /^[A-Za-z]:[\\/]/.test(candidate)) {
+    return false;
+  }
+  const segments = normalizePath(candidate).split("/");
+  return segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
+
 async function writeScanCache(location: ScanCacheLocation, cached: CachedScan): Promise<void> {
   const temporaryPath = `${location.path}.${process.pid}-${randomUUID()}.tmp`;
   try {
diff --git a/packages/core/src/validate.ts b/packages/core/src/validate.ts
index 2872be6..f6f1274 100644
--- a/packages/core/src/validate.ts
+++ b/packages/core/src/validate.ts
@@ -18,7 +18,6 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
     };
   }
 
-  const contextFiles = (candidate as FixMapReport).contextFiles;
   const record = candidate as Record<string, unknown>;
   if (record.reportVersion !== undefined && record.reportVersion !== 1) {
     return {
@@ -26,17 +25,36 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
       message: `${label} uses unsupported reportVersion ${JSON.stringify(record.reportVersion)}; this FixMap release supports reportVersion 1.`
     };
   }
+
+  const invalidEnvelopeFields = [
+    typeof record.summary === "string" ? undefined : "summary (string)",
+    Array.isArray(record.testRoutes) ? undefined : "testRoutes (array)",
+    Array.isArray(record.risks) ? undefined : "risks (array)",
+    Array.isArray(record.changedFiles) ? undefined : "changedFiles (array)",
+    Array.isArray(record.diagnostics) ? undefined : "diagnostics (array)"
+  ].filter((field): field is string => field !== undefined);
+  if (invalidEnvelopeFields.length > 0) {
+    return {
+      success: false,
+      message:
+        `${label} is missing or has invalid fields in the complete FixMap report envelope: ` +
+        `${invalidEnvelopeFields.join(", ")}.`
+    };
+  }
+
+  const versioned = record.reportVersion === 1;
+  const contextFiles = (candidate as FixMapReport).contextFiles;
   const invalid = contextFiles.findIndex((file) => {
     if (!isRecord(file)) return true;
     const ranked = file;
     if (typeof ranked.path !== "string" || ranked.path.trim().length === 0) return true;
-    if (ranked.rank !== undefined && (!Number.isSafeInteger(ranked.rank) || (ranked.rank as number) < 1)) return true;
-    if (ranked.score !== undefined && (typeof ranked.score !== "number" || !Number.isFinite(ranked.score))) return true;
+    if ((versioned || ranked.rank !== undefined) && (!Number.isSafeInteger(ranked.rank) || (ranked.rank as number) < 1)) return true;
+    if ((versioned || ranked.score !== undefined) && (typeof ranked.score !== "number" || !Number.isFinite(ranked.score))) return true;
     if (
-      ranked.confidence !== undefined &&
+      (versioned || ranked.confidence !== undefined) &&
       ranked.confidence !== "high" && ranked.confidence !== "medium" && ranked.confidence !== "low"
     ) return true;
-    if (ranked.reasons !== undefined && !isStringArray(ranked.reasons)) return true;
+    if ((versioned || ranked.reasons !== undefined) && !isStringArray(ranked.reasons)) return true;
     return false;
   });
   if (invalid !== -1) {
@@ -44,33 +62,35 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
       success: false,
       message:
         `${label} has an invalid contextFiles entry at index ${invalid}; each entry needs a non-empty string "path", ` +
-        "and optional rank, score, confidence, and reasons fields must use their documented types."
+        `${versioned ? "and version 1 requires" : "and optional"} rank, score, confidence, and reasons fields with their documented types.`
     };
   }
-
-  const invalidEnvelopeFields = [
-    typeof record.summary === "string" ? undefined : "summary (string)",
-    Array.isArray(record.testRoutes) ? undefined : "testRoutes (array)",
-    Array.isArray(record.risks) ? undefined : "risks (array)",
-    Array.isArray(record.changedFiles) ? undefined : "changedFiles (array)",
-    Array.isArray(record.diagnostics) ? undefined : "diagnostics (array)"
-  ].filter((field): field is string => field !== undefined);
-  if (invalidEnvelopeFields.length > 0) {
+  const duplicatePath = contextFiles.findIndex((file, index) =>
+    contextFiles.findIndex((candidate) => candidate.path === file.path) !== index
+  );
+  if (duplicatePath !== -1) {
     return {
       success: false,
-      message:
-        `${label} is missing or has invalid fields in the complete FixMap report envelope: ` +
-        `${invalidEnvelopeFields.join(", ")}.`
+      message: `${label} has a duplicate contextFiles path at index ${duplicatePath}; each ranked path must appear once.`
     };
   }
+  if (versioned) {
+    const outOfOrderRank = contextFiles.findIndex((file, index) => file.rank !== index + 1);
+    if (outOfOrderRank !== -1) {
+      return {
+        success: false,
+        message: `${label} has an out-of-order contextFiles rank at index ${outOfOrderRank}; version 1 ranks must be sequential and match array order.`
+      };
+    }
+  }
 
   const testRoutes = record.testRoutes as unknown[];
   const invalidRoute = testRoutes.findIndex((route) => {
     if (!isRecord(route)) return true;
     return typeof route.command !== "string" || !route.command.trim() ||
       !isNonBlankStringArray(route.relatedFiles) ||
-      (route.kind !== undefined && route.kind !== "test" && route.kind !== "validation") ||
-      (route.reason !== undefined && typeof route.reason !== "string");
+      ((versioned || route.kind !== undefined) && route.kind !== "test" && route.kind !== "validation") ||
+      ((versioned || route.reason !== undefined) && typeof route.reason !== "string");
   });
   if (invalidRoute !== -1) {
     return {
@@ -85,8 +105,8 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
   const invalidRisk = risks.findIndex((risk) => {
     if (!isRecord(risk)) return true;
     return typeof risk.area !== "string" || !risk.area.trim() ||
-      (risk.reason !== undefined && typeof risk.reason !== "string") ||
-      (risk.severity !== undefined && risk.severity !== "low" && risk.severity !== "medium" && risk.severity !== "high");
+      ((versioned || risk.reason !== undefined) && typeof risk.reason !== "string") ||
+      ((versioned || risk.severity !== undefined) && risk.severity !== "low" && risk.severity !== "medium" && risk.severity !== "high");
   });
   if (invalidRisk !== -1) {
     return {
@@ -146,7 +166,7 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
     const invalidIdentifier = grounding.identifiers.findIndex((identifier) =>
       !isRecord(identifier) ||
       typeof identifier.identifier !== "string" || !identifier.identifier.trim() ||
-      typeof identifier.status !== "string" || !identifier.status.trim() ||
+      !isIdentifierStatus(identifier.status) ||
       !isNonBlankStringArray(identifier.matchedFiles)
     );
     if (invalidIdentifier !== -1) {
@@ -175,3 +195,8 @@ function isNonBlankStringArray(candidate: unknown): candidate is string[] {
 function isNullableFiniteNumber(candidate: unknown): boolean {
   return candidate === null || (typeof candidate === "number" && Number.isFinite(candidate));
 }
+
+function isIdentifierStatus(candidate: unknown): boolean {
+  return candidate === "exact-definition" || candidate === "exact-text" ||
+    candidate === "partial-definition" || candidate === "not-found" || candidate === "unverified";
+}
diff --git a/packages/core/test/repo-scan.test.ts b/packages/core/test/repo-scan.test.ts
index 13008f3..50b47b8 100644
--- a/packages/core/test/repo-scan.test.ts
+++ b/packages/core/test/repo-scan.test.ts
@@ -772,6 +772,59 @@ describe("scanRepo", () => {
     }
   });
 
+  it("rebuilds typed cache data with unsafe paths, impossible sampling state, or a future timestamp", { timeout: 30_000 }, async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-cache-integrity-repo-"));
+    const cacheRoot = await mkdtemp(join(tmpdir(), "fixmap-cache-integrity-store-"));
+    const previousCache = process.env.FIXMAP_CACHE_DIR;
+    process.env.FIXMAP_CACHE_DIR = cacheRoot;
+    try {
+      await writeFile(join(root, "index.ts"), "export const value = 1;\n");
+      await exec("git", ["init", "-b", "main"], { cwd: root });
+      await exec("git", ["config", "user.email", "test@example.com"], { cwd: root });
+      await exec("git", ["config", "user.name", "Test User"], { cwd: root });
+      await exec("git", ["add", "."], { cwd: root });
+      await exec("git", ["commit", "-m", "initial"], { cwd: root });
+
+      await scanRepo({ repoRoot: root, useCache: true });
+      const cachePath = join(cacheRoot, (await readdir(cacheRoot))[0]!);
+      type MutableCachedScan = Record<string, unknown> & {
+        createdAt: string;
+        files: Array<{ path: string; textSampleComplete: boolean; textSampleSkipReason?: string }>;
+        trackedFiles: string[];
+      };
+      const mutations: Array<(cached: MutableCachedScan) => void> = [
+        (cached) => { cached.files[0].path = "../outside.ts"; },
+        (cached) => { cached.trackedFiles = ["C:/outside.ts"]; },
+        (cached) => {
+          cached.packageScripts = [{ name: "test", command: "npm test", packageDir: "../outside" }];
+        },
+        (cached) => {
+          cached.diagnostics = [{ code: "content-unread", message: "Unread", severity: "warning", paths: ["../outside.ts"] }];
+        },
+        (cached) => {
+          cached.files[0].textSampleComplete = true;
+          cached.files[0].textSampleSkipReason = "too-large";
+        },
+        (cached) => { cached.createdAt = new Date(Date.now() + 8 * 24 * 60 * 60 * 1000).toISOString(); }
+      ];
+
+      for (const mutate of mutations) {
+        const cached = JSON.parse(await readFile(cachePath, "utf8")) as MutableCachedScan;
+        mutate(cached);
+        await writeFile(cachePath, `${JSON.stringify(cached)}\n`);
+
+        const repaired = await scanRepo({ repoRoot: root, useCache: true });
+        expect(repaired.diagnostics.map((entry) => entry.code)).not.toContain("cache-hit");
+        expect(repaired.files.map((file) => file.path)).toEqual(["index.ts"]);
+      }
+    } finally {
+      if (previousCache === undefined) delete process.env.FIXMAP_CACHE_DIR;
+      else process.env.FIXMAP_CACHE_DIR = previousCache;
+      await rm(cacheRoot, { recursive: true, force: true });
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
   it("keeps the exact-state cache valid across concurrent first scans", { timeout: 30_000 }, async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-cache-concurrent-repo-"));
     const cacheRoot = await mkdtemp(join(tmpdir(), "fixmap-cache-concurrent-store-"));
diff --git a/packages/core/test/validate.test.ts b/packages/core/test/validate.test.ts
index 6664fd5..c3be64d 100644
--- a/packages/core/test/validate.test.ts
+++ b/packages/core/test/validate.test.ts
@@ -11,15 +11,54 @@ const envelope = {
   diagnostics: []
 };
 
+const rankedContext = {
+  rank: 1,
+  path: "src/reset.ts",
+  score: 12,
+  confidence: "high",
+  reasons: ["path matches task terms: reset"]
+} as const;
+
 describe("validateFixMapReport", () => {
   it("accepts a complete empty report and legacy reports without a marker", () => {
     expect(validateFixMapReport(envelope, "report").success).toBe(true);
-    const legacy = Object.fromEntries(
-      Object.entries(envelope).filter(([key]) => key !== "reportVersion")
-    );
+    const legacy = {
+      ...Object.fromEntries(Object.entries(envelope).filter(([key]) => key !== "reportVersion")),
+      contextFiles: [{ path: "src/reset.ts" }],
+      testRoutes: [{ command: "npm test", relatedFiles: [] }],
+      risks: [{ area: "authentication" }]
+    };
     expect(validateFixMapReport(legacy, "report").success).toBe(true);
   });
 
+  it("requires all existing version 1 entry fields while leaving legacy entries compatible", () => {
+    const result = validateFixMapReport({
+      ...envelope,
+      contextFiles: [{ path: "src/reset.ts" }],
+      testRoutes: [{ command: "npm test", relatedFiles: [] }],
+      risks: [{ area: "authentication" }]
+    }, "report");
+
+    expect(result.success).toBe(false);
+    if (!result.success) expect(result.message).toContain("version 1 requires");
+  });
+
+  it("rejects duplicate paths and version 1 ranks that disagree with array order", () => {
+    const duplicate = validateFixMapReport({
+      ...envelope,
+      contextFiles: [rankedContext, { ...rankedContext, rank: 2 }]
+    }, "report");
+    const outOfOrder = validateFixMapReport({
+      ...envelope,
+      contextFiles: [{ ...rankedContext, rank: 2 }]
+    }, "report");
+
+    expect(duplicate.success).toBe(false);
+    if (!duplicate.success) expect(duplicate.message).toContain("duplicate contextFiles path");
+    expect(outOfOrder.success).toBe(false);
+    if (!outOfOrder.success) expect(outOfOrder.message).toContain("out-of-order contextFiles rank");
+  });
+
   it("rejects unsupported report versions", () => {
     const result = validateFixMapReport({ ...envelope, reportVersion: 2 }, "report");
 
@@ -49,20 +88,22 @@ describe("validateFixMapReport", () => {
   });
 
   it.each([
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], testRoutes: [null] }, "testRoutes entry"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], testRoutes: [{ command: "npm test" }] }, "relatedFiles"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts", reasons: [42] }] }, "contextFiles entry"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], testRoutes: [{ command: " ", relatedFiles: [] }] }, "testRoutes entry"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], testRoutes: [{ command: "npm test", relatedFiles: [], kind: "check" }] }, "testRoutes entry"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], risks: [null] }, "risks entry"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], risks: [{ area: " ", severity: "low" }] }, "risks entry"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], risks: [{ area: "auth", severity: "critical" }] }, "risks entry"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], changedFiles: [42] }, "changedFiles"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], changedFiles: [" "] }, "changedFiles"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], diagnostics: [null] }, "diagnostics entry"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], diagnostics: [{ code: "x", message: "x", severity: "warning", paths: [""] }] }, "diagnostics entry"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], analysis: {} }, "analysis.grounding.specificity"],
-    [{ ...envelope, contextFiles: [{ path: "src/reset.ts" }], analysis: { grounding: { specificity: "anchored" } } }, "incomplete or invalid analysis"]
+    [{ ...envelope, contextFiles: [rankedContext], testRoutes: [null] }, "testRoutes entry"],
+    [{ ...envelope, contextFiles: [rankedContext], testRoutes: [{ command: "npm test" }] }, "relatedFiles"],
+    [{ ...envelope, contextFiles: [{ ...rankedContext, reasons: [42] }] }, "contextFiles entry"],
+    [{ ...envelope, contextFiles: [rankedContext], testRoutes: [{ command: " ", kind: "test", reason: "tests", relatedFiles: [] }] }, "testRoutes entry"],
+    [{ ...envelope, contextFiles: [rankedContext], testRoutes: [{ command: "npm test", kind: "check", reason: "tests", relatedFiles: [] }] }, "testRoutes entry"],
+    [{ ...envelope, contextFiles: [rankedContext], testRoutes: [{ command: "npm test", relatedFiles: [] }] }, "testRoutes entry"],
+    [{ ...envelope, contextFiles: [rankedContext], risks: [null] }, "risks entry"],
+    [{ ...envelope, contextFiles: [rankedContext], risks: [{ area: " ", reason: "risk", severity: "low" }] }, "risks entry"],
+    [{ ...envelope, contextFiles: [rankedContext], risks: [{ area: "auth", reason: "risk", severity: "critical" }] }, "risks entry"],
+    [{ ...envelope, contextFiles: [rankedContext], risks: [{ area: "auth" }] }, "risks entry"],
+    [{ ...envelope, contextFiles: [rankedContext], changedFiles: [42] }, "changedFiles"],
+    [{ ...envelope, contextFiles: [rankedContext], changedFiles: [" "] }, "changedFiles"],
+    [{ ...envelope, contextFiles: [rankedContext], diagnostics: [null] }, "diagnostics entry"],
+    [{ ...envelope, contextFiles: [rankedContext], diagnostics: [{ code: "x", message: "x", severity: "warning", paths: [""] }] }, "diagnostics entry"],
+    [{ ...envelope, contextFiles: [rankedContext], analysis: {} }, "analysis.grounding.specificity"],
+    [{ ...envelope, contextFiles: [rankedContext], analysis: { grounding: { specificity: "anchored" } } }, "incomplete or invalid analysis"]
   ])("rejects consumer-unsafe nested report data: %s", (candidate, message) => {
     const result = validateFixMapReport(candidate, "report");
     expect(result.success).toBe(false);
@@ -89,4 +130,25 @@ describe("validateFixMapReport", () => {
 
     expect(result.success).toBe(true);
   });
+
+  it("rejects an unknown identifier grounding status", () => {
+    const result = validateFixMapReport({
+      ...envelope,
+      analysis: {
+        grounding: {
+          specificity: "anchored",
+          identifiers: [{ identifier: "sendMail", status: "future-status", matchedFiles: ["src/mail.ts"] }],
+          unresolvedIdentifiers: [],
+          partiallyResolvedIdentifiers: [],
+          unverifiedIdentifiers: [],
+          scanComplete: true
+        },
+        ranking: { topScore: 20, runnerUpScore: null, topGap: null, clustered: false },
+        nextAction: "Inspect src/mail.ts."
+      }
+    }, "report");
+
+    expect(result.success).toBe(false);
+    if (!result.success) expect(result.message).toContain("analysis.grounding.identifiers entry");
+  });
 });

From 04af625ada9890bd0c1d30a6833165aad6b93eff Mon Sep 17 00:00:00 2001
From: Aryam Goyal <aryamgoyal18@gmail.com>
Date: Sun, 9 Aug 2026 17:06:28 +0530
Subject: [PATCH 06/10] Harden unreleased setup paths and ranking

---
 apps/web/app/layout.tsx              |   2 +-
 packages/action/dist/index.mjs       |  89 +++++++++--
 packages/cli/src/agent-setup.ts      | 220 +++++++++++++++++++++++++--
 packages/cli/src/cli-runner.ts       |  69 ++++++++-
 packages/cli/test/cli-runner.test.ts | 157 ++++++++++++++++++-
 packages/core/src/rank.ts            |  20 ++-
 packages/core/src/repo-scan.ts       |  28 +++-
 packages/core/src/signals.ts         |   5 +
 packages/core/src/validate.ts        |  25 ++-
 packages/core/test/plan.test.ts      |   4 +-
 packages/core/test/rank.test.ts      |  41 +++++
 packages/core/test/repo-scan.test.ts |  18 +++
 packages/core/test/signals.test.ts   |   9 ++
 packages/core/test/validate.test.ts  |  17 +++
 14 files changed, 658 insertions(+), 46 deletions(-)

diff --git a/apps/web/app/layout.tsx b/apps/web/app/layout.tsx
index 3b8eddc..eb5cd78 100644
--- a/apps/web/app/layout.tsx
+++ b/apps/web/app/layout.tsx
@@ -50,7 +50,7 @@ export const viewport: Viewport = {
 
 export default function RootLayout({ children }: { children: ReactNode }) {
   return (
-    <html lang="en" className={`${body.variable} ${mono.variable}`} suppressHydrationWarning>
+    <html lang="en" className={`${body.variable} ${mono.variable}`} data-scroll-behavior="smooth" suppressHydrationWarning>
       <body>
         <Script id="fixmap-theme-init" strategy="beforeInteractive">{`try{const t=localStorage.getItem("fixmap-theme");if(t==="light"||t==="dark")document.documentElement.dataset.theme=t}catch{}`}</Script>
         <a className="skip-link" href="#main-content">Skip to main content</a>
diff --git a/packages/action/dist/index.mjs b/packages/action/dist/index.mjs
index c579d06..c805700 100644
--- a/packages/action/dist/index.mjs
+++ b/packages/action/dist/index.mjs
@@ -235,6 +235,7 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
 ]);
 var MAX_FILE_MENTION_LENGTH = 200;
 var FILE_MENTION_PATTERN = new RegExp(`[A-Za-z0-9_@$][A-Za-z0-9_.$/\\\\-]{0,${MAX_FILE_MENTION_LENGTH}}\\.(?:[cm]?[jt]sx?|json|ya?ml|mdx?|css|scss|less|html|py|rb|rs|go|java|kt|c|cc|cpp|h|hpp|d\\.ts)\\b`, "g");
+var CONVENTIONAL_FILE_MENTION_PATTERN = /\b(?:AUTHORS|CHANGELOG|CODE_OF_CONDUCT|CONTRIBUTING|LICENSE|NOTICE|README|SECURITY|CODEOWNERS|Dockerfile|Gemfile|Jenkinsfile|Makefile|Procfile|Rakefile|Vagrantfile)\b/gi;
 var MEMBER_MENTION_PATTERN = /\b(?:window|globalThis|process|request|response|req|res|this)\.([$A-Za-z_][$A-Za-z0-9_$]*)\b/g;
 var FILE_EXTENSIONS = /* @__PURE__ */ new Set([
   "c",
@@ -402,6 +403,10 @@ function isEscaped(text, index) {
 }
 function extractFileMentions(text) {
   const mentions = /* @__PURE__ */ new Set();
+  for (const match of text.matchAll(CONVENTIONAL_FILE_MENTION_PATTERN)) {
+    if (match[0])
+      mentions.add(match[0]);
+  }
   for (const match of text.matchAll(
     // blob, tree and blame all address a path in the repository; only the view differs, and
     // a tree or blame link is the same deliberate "the code is here" gesture as a blob one.
@@ -1312,7 +1317,16 @@ function matchMentionedPaths(mentions, repoPaths) {
   return matched;
 }
 function pathMatchesMention2(path, mention) {
-  return path === mention || path.endsWith(`/${mention}`) || mention.endsWith(`/${path}`);
+  const normalizedPath = path.toLowerCase();
+  const normalizedMention = mention.toLowerCase();
+  if (normalizedPath === normalizedMention || normalizedPath.endsWith(`/${normalizedMention}`) || normalizedMention.endsWith(`/${normalizedPath}`)) {
+    return true;
+  }
+  if (!normalizedMention.includes("/") && !normalizedMention.includes(".")) {
+    const fileName = normalizedPath.split("/").at(-1) ?? "";
+    return fileName.replace(/\.[^.]+$/, "") === normalizedMention;
+  }
+  return false;
 }
 function compiledSourcePathVariants(path) {
   const lowerPath = path.toLowerCase();
@@ -1386,8 +1400,9 @@ function isTypeDeclarationPath(path) {
 }
 function targetsDocumentation(taskText) {
   const documentation = "(?:docs?|documentation|readme|guide|copy)";
-  const action = "(?:add|edit|update|write|rewrite|revise|remove|correct|document|improve)";
-  return new RegExp(`\\b${action}\\b[^\\n.]{0,60}\\b${documentation}\\b`, "i").test(taskText) || new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${action}\\b`, "i").test(taskText);
+  const action = "(?:add|change|correct|document|edit|fix|improve|remove|revise|rewrite|update|write)";
+  const defect = "(?:typos?|spelling|grammar|wording|broken links?)";
+  return new RegExp(`\\b${action}\\b[^\\n.]{0,60}\\b${documentation}\\b`, "i").test(taskText) || new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${action}\\b`, "i").test(taskText) || new RegExp(`\\b${defect}\\b[^\\n.]{0,60}\\b${documentation}\\b`, "i").test(taskText) || new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${defect}\\b`, "i").test(taskText);
 }
 function buildDefinitionSignals(identifiers) {
   return [...identifiers].sort((a, b) => a.localeCompare(b)).map((identifier) => ({
@@ -1930,6 +1945,31 @@ var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
   ".yaml",
   ".yml"
 ]);
+var CONVENTIONAL_DOCUMENT_NAMES = /* @__PURE__ */ new Set([
+  "authors",
+  "changelog",
+  "code_of_conduct",
+  "contributing",
+  "license",
+  "notice",
+  "readme",
+  "security"
+]);
+var CONVENTIONAL_CONFIG_NAMES = /* @__PURE__ */ new Set([
+  ".dockerignore",
+  ".editorconfig",
+  ".gitattributes",
+  ".gitignore",
+  ".npmignore",
+  "codeowners",
+  "dockerfile",
+  "gemfile",
+  "jenkinsfile",
+  "makefile",
+  "procfile",
+  "rakefile",
+  "vagrantfile"
+]);
 var SFC_EXTENSIONS = /* @__PURE__ */ new Set([".vue", ".svelte"]);
 var SFC_SCRIPT_BLOCK = /<script\b[^>]*>([\s\S]*?)<\/script>/gi;
 var TEST_PATTERNS = [
@@ -2132,10 +2172,10 @@ function isRecord(candidate) {
   return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
 }
 function isCachedRelativePath(candidate) {
-  if (typeof candidate !== "string" || candidate.trim().length === 0 || candidate.includes("\0") || isAbsolute(candidate) || /^[A-Za-z]:[\\/]/.test(candidate)) {
+  if (typeof candidate !== "string" || candidate.trim().length === 0 || candidate.includes("\0") || isAbsolute(candidate) || /^[\\/]/.test(candidate) || /^[A-Za-z]:/.test(candidate)) {
     return false;
   }
-  const segments = normalizePath(candidate).split("/");
+  const segments = candidate.replace(/\\/g, "/").split("/");
   return segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 }
 async function writeScanCache(location, cached) {
@@ -2408,7 +2448,8 @@ async function toRepoFile(absolutePath, relativePath) {
     return { status: "not-a-file" };
   }
   const extension = extname(relativePath);
-  const isSource = SOURCE_EXTENSIONS.has(extension);
+  const conventionalKind = classifyConventionalTextFile(relativePath);
+  const isSource = SOURCE_EXTENSIONS.has(extension) || conventionalKind !== void 0;
   const sample = isSource ? await readTextSample(absolutePath, fileStat.size) : { text: "", complete: true };
   if (SFC_EXTENSIONS.has(extension) && sample.text) {
     sample.text = extractScriptBlocks(sample.text);
@@ -2620,7 +2661,10 @@ function detectPackageManager(files) {
 }
 function classifyFile(path, extension) {
   const lower = path.toLowerCase();
-  if (extension === ".md" || lower.startsWith("docs/") || lower === "license")
+  const conventionalKind = classifyConventionalTextFile(path);
+  if (conventionalKind)
+    return conventionalKind;
+  if (extension === ".md" || lower.startsWith("docs/"))
     return "documentation";
   if (lower.startsWith(".github/") || [".json", ".yaml", ".yml"].includes(extension) || /(^|\/)([^/]+\.)?(config|rc)\.[^/]+$/.test(lower))
     return "config";
@@ -2628,6 +2672,14 @@ function classifyFile(path, extension) {
     return "code";
   return "other";
 }
+function classifyConventionalTextFile(path) {
+  const name = path.replace(/\\/g, "/").split("/").at(-1)?.toLowerCase() ?? "";
+  if (CONVENTIONAL_DOCUMENT_NAMES.has(name))
+    return "documentation";
+  if (CONVENTIONAL_CONFIG_NAMES.has(name))
+    return "config";
+  return void 0;
+}
 async function readTextSample(path, sizeBytes) {
   if (sizeBytes > MAX_TEXT_SAMPLE_BYTES) {
     return { text: "", complete: false, skipReason: "too-large" };
@@ -2902,7 +2954,7 @@ function validateFixMapReport(candidate, label) {
     if (!isRecord2(file))
       return true;
     const ranked = file;
-    if (typeof ranked.path !== "string" || ranked.path.trim().length === 0)
+    if (!isRepositoryRelativePath(ranked.path))
       return true;
     if ((versioned || ranked.rank !== void 0) && (!Number.isSafeInteger(ranked.rank) || ranked.rank < 1))
       return true;
@@ -2940,7 +2992,7 @@ function validateFixMapReport(candidate, label) {
   const invalidRoute = testRoutes.findIndex((route) => {
     if (!isRecord2(route))
       return true;
-    return typeof route.command !== "string" || !route.command.trim() || !isNonBlankStringArray(route.relatedFiles) || (versioned || route.kind !== void 0) && route.kind !== "test" && route.kind !== "validation" || (versioned || route.reason !== void 0) && typeof route.reason !== "string";
+    return typeof route.command !== "string" || !route.command.trim() || !isRepositoryRelativePathArray(route.relatedFiles) || (versioned || route.kind !== void 0) && route.kind !== "test" && route.kind !== "validation" || (versioned || route.reason !== void 0) && typeof route.reason !== "string";
   });
   if (invalidRoute !== -1) {
     return {
@@ -2960,14 +3012,14 @@ function validateFixMapReport(candidate, label) {
       message: `${label} has an invalid risks entry at index ${invalidRisk}; each risk needs a non-empty string "area", and optional reason and severity fields must use their documented types.`
     };
   }
-  if (!isNonBlankStringArray(record.changedFiles)) {
-    return { success: false, message: `${label} has invalid changedFiles; every entry must be a non-empty string path.` };
+  if (!isRepositoryRelativePathArray(record.changedFiles)) {
+    return { success: false, message: `${label} has invalid changedFiles; every entry must be a safe repository-relative path.` };
   }
   const diagnostics = record.diagnostics;
   const invalidDiagnostic = diagnostics.findIndex((diagnostic) => {
     if (!isRecord2(diagnostic))
       return true;
-    return typeof diagnostic.code !== "string" || !diagnostic.code.trim() || typeof diagnostic.message !== "string" || diagnostic.severity !== "info" && diagnostic.severity !== "warning" && diagnostic.severity !== "error" || diagnostic.paths !== void 0 && !isNonBlankStringArray(diagnostic.paths);
+    return typeof diagnostic.code !== "string" || !diagnostic.code.trim() || typeof diagnostic.message !== "string" || diagnostic.severity !== "info" && diagnostic.severity !== "warning" && diagnostic.severity !== "error" || diagnostic.paths !== void 0 && !isRepositoryRelativePathArray(diagnostic.paths);
   });
   if (invalidDiagnostic !== -1) {
     return {
@@ -2991,7 +3043,7 @@ function validateFixMapReport(candidate, label) {
         message: `${label} has incomplete or invalid analysis grounding, ranking, or nextAction fields.`
       };
     }
-    const invalidIdentifier = grounding.identifiers.findIndex((identifier) => !isRecord2(identifier) || typeof identifier.identifier !== "string" || !identifier.identifier.trim() || !isIdentifierStatus(identifier.status) || !isNonBlankStringArray(identifier.matchedFiles));
+    const invalidIdentifier = grounding.identifiers.findIndex((identifier) => !isRecord2(identifier) || typeof identifier.identifier !== "string" || !identifier.identifier.trim() || !isIdentifierStatus(identifier.status) || !isRepositoryRelativePathArray(identifier.matchedFiles));
     if (invalidIdentifier !== -1) {
       return {
         success: false,
@@ -3007,8 +3059,15 @@ function isRecord2(candidate) {
 function isStringArray(candidate) {
   return Array.isArray(candidate) && candidate.every((entry) => typeof entry === "string");
 }
-function isNonBlankStringArray(candidate) {
-  return isStringArray(candidate) && candidate.every((entry) => entry.trim().length > 0);
+function isRepositoryRelativePathArray(candidate) {
+  return Array.isArray(candidate) && candidate.every(isRepositoryRelativePath);
+}
+function isRepositoryRelativePath(candidate) {
+  if (typeof candidate !== "string" || !candidate.trim() || candidate.includes("\0") || /^[\\/]/.test(candidate) || /^[A-Za-z]:/.test(candidate)) {
+    return false;
+  }
+  const segments = candidate.replace(/\\/g, "/").split("/");
+  return segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 }
 function isNullableFiniteNumber(candidate) {
   return candidate === null || typeof candidate === "number" && Number.isFinite(candidate);
diff --git a/packages/cli/src/agent-setup.ts b/packages/cli/src/agent-setup.ts
index a986853..cc33c1f 100644
--- a/packages/cli/src/agent-setup.ts
+++ b/packages/cli/src/agent-setup.ts
@@ -1,5 +1,7 @@
-import { lstat, mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, realpath, rename, rmdir, stat, unlink, writeFile, type FileHandle } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 
 export type AgentTarget = "claude" | "cursor" | "copilot" | "agents";
 
@@ -67,7 +69,10 @@ export async function installAgentCommands(input: {
   repoRoot: string;
   targets: AgentTarget[];
   force?: boolean;
-}): Promise<Array<{ path: string; status: "created" | "unchanged" | "updated" }>> {
+}, dependencies: {
+  /** Internal seam for deterministic race/failure tests; production setup never supplies it. */
+  beforeCommit?: (entry: { path: string; displayPath: string }, index: number) => Promise<void>;
+} = {}): Promise<Array<{ path: string; status: "created" | "unchanged" | "updated" }>> {
   const requestedRoot = resolve(input.repoRoot);
   try {
     if (!(await stat(requestedRoot)).isDirectory()) throw new Error("not a directory");
@@ -75,6 +80,8 @@ export async function installAgentCommands(input: {
     throw new Error(`Setup repository "${requestedRoot}" does not exist or is not a directory.`);
   }
   const root = await realpath(requestedRoot);
+  const setupLock = await acquireSetupLock(root);
+  try {
   const prepared: Array<{
     path: string;
     displayPath: string;
@@ -105,17 +112,96 @@ export async function installAgentCommands(input: {
     prepared.push({ path, displayPath, contents: template.contents, existing });
   }
 
-  const results: Array<{ path: string; status: "created" | "unchanged" | "updated" }> = [];
-  for (const entry of prepared) {
-    if (entry.existing === entry.contents) {
-      results.push({ path: entry.displayPath, status: "unchanged" });
-      continue;
+  const changed = prepared.filter((entry) => entry.existing !== entry.contents);
+  const staged: Array<(typeof changed)[number] & { stagedPath: string }> = [];
+  const committed: Array<(typeof changed)[number]> = [];
+  const createdDirectories = new Set<string>();
+
+  try {
+    // Stage every new command beside its destination before mutating any destination. The
+    // random sibling name means a parent link swapped after preflight cannot redirect the
+    // final rename: that name will not exist in the attacker's directory, so rename fails.
+    for (const entry of changed) {
+      const parent = dirname(entry.path);
+      const firstCreated = await mkdir(parent, { recursive: true });
+      if (firstCreated) rememberCreatedDirectories(createdDirectories, firstCreated, parent);
+      await assertSafeTarget(root, entry.path, entry.displayPath);
+      const stagedPath = join(parent, `.${basename(entry.path)}.fixmap-${randomUUID()}.tmp`);
+      await writeFile(stagedPath, entry.contents, { encoding: "utf8", flag: "wx" });
+      await assertSafeTarget(root, stagedPath, `${entry.displayPath} staging file`);
+      staged.push({ ...entry, stagedPath });
+    }
+
+    for (let index = 0; index < staged.length; index += 1) {
+      const entry = staged[index]!;
+      await dependencies.beforeCommit?.({ path: entry.path, displayPath: entry.displayPath }, index);
+      // Close the original check-then-write window. rename replaces a final symlink or
+      // hardlink directory entry rather than following it, but rejecting one is clearer and
+      // preserves an unexpected concurrent change instead of silently replacing it.
+      await assertTargetUnchanged(root, entry.path, entry.displayPath, entry.existing);
+      await assertSafeTarget(root, entry.stagedPath, `${entry.displayPath} staging file`);
+      await rename(entry.stagedPath, entry.path);
+      committed.push(entry);
+    }
+  } catch (error) {
+    const rollbackErrors: string[] = [];
+    for (const entry of committed.reverse()) {
+      try {
+        if (entry.existing === undefined) {
+          await assertSafeTarget(root, entry.path, entry.displayPath);
+          const current = await readFile(entry.path, "utf8");
+          if (current !== entry.contents) {
+            throw new Error("the installed file changed before rollback");
+          }
+          await unlink(entry.path);
+        } else {
+          await replaceWithContents(root, entry.path, entry.displayPath, entry.existing);
+        }
+      } catch (rollbackError) {
+        rollbackErrors.push(`${entry.displayPath}: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+      }
     }
-    await mkdir(dirname(entry.path), { recursive: true });
-    await writeFile(entry.path, entry.contents, "utf8");
-    results.push({ path: entry.displayPath, status: entry.existing === undefined ? "created" : "updated" });
+    await cleanupStagingFiles(staged);
+    await cleanupCreatedDirectories(createdDirectories);
+    const detail = error instanceof Error ? error.message : String(error);
+    if (rollbackErrors.length > 0) {
+      throw new Error(`${detail} Setup rollback also failed for ${rollbackErrors.join("; ")}.`);
+    }
+    throw error;
   }
+
+  const results = prepared.map((entry) => ({
+    path: entry.displayPath,
+    status: entry.existing === entry.contents
+      ? "unchanged" as const
+      : entry.existing === undefined
+        ? "created" as const
+        : "updated" as const
+  }));
   return results;
+  } finally {
+    await releaseSetupLock(setupLock);
+  }
+}
+
+async function assertTargetUnchanged(
+  root: string,
+  target: string,
+  displayPath: string,
+  expectedContents: string | undefined
+): Promise<void> {
+  await assertSafeTarget(root, target, displayPath);
+  try {
+    const currentContents = await readFile(target, "utf8");
+    if (expectedContents === undefined || currentContents !== expectedContents) {
+      throw new Error(`Refusing to write ${displayPath} because it changed while setup was running.`);
+    }
+  } catch (error) {
+    if ((error as { code?: unknown }).code !== "ENOENT") throw error;
+    if (expectedContents !== undefined) {
+      throw new Error(`Refusing to write ${displayPath} because it changed while setup was running.`);
+    }
+  }
 }
 
 async function assertSafeTarget(root: string, target: string, displayPath: string): Promise<void> {
@@ -146,6 +232,9 @@ async function assertSafeTarget(root: string, target: string, displayPath: strin
       if (distance === ".." || distance.startsWith(`..${sep}`) || isAbsolute(distance)) {
         throw new Error(`Refusing to write ${displayPath} because its parent resolves outside the setup repository.`);
       }
+      if (ancestorMetadata.isSymbolicLink()) {
+        throw new Error(`Refusing to write ${displayPath} because parent ${ancestor} is a symbolic link.`);
+      }
       return;
     } catch (error) {
       if ((error as { code?: unknown }).code !== "ENOENT") throw error;
@@ -157,3 +246,112 @@ async function assertSafeTarget(root: string, target: string, displayPath: strin
     }
   }
 }
+
+async function replaceWithContents(root: string, target: string, displayPath: string, contents: string): Promise<void> {
+  const parent = dirname(target);
+  await assertSafeTarget(root, target, displayPath);
+  const stagedPath = join(parent, `.${basename(target)}.fixmap-rollback-${randomUUID()}.tmp`);
+  try {
+    await writeFile(stagedPath, contents, { encoding: "utf8", flag: "wx" });
+    await assertSafeTarget(root, stagedPath, `${displayPath} rollback file`);
+    await assertSafeTarget(root, target, displayPath);
+    await rename(stagedPath, target);
+  } finally {
+    try { await unlink(stagedPath); } catch (error) {
+      if ((error as { code?: unknown }).code !== "ENOENT") throw error;
+    }
+  }
+}
+
+async function cleanupStagingFiles(entries: Array<{ stagedPath: string }>): Promise<void> {
+  for (const entry of entries) {
+    try { await unlink(entry.stagedPath); } catch (error) {
+      if ((error as { code?: unknown }).code !== "ENOENT") {
+        // Cleanup cannot make the original installation failure safer or more actionable.
+        // A unique .tmp file may remain, but no /fixmap command points at it.
+      }
+    }
+  }
+}
+
+function rememberCreatedDirectories(paths: Set<string>, firstCreated: string, leaf: string): void {
+  const boundary = dirname(resolve(firstCreated));
+  let current = resolve(leaf);
+  while (current !== boundary) {
+    paths.add(current);
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+}
+
+async function cleanupCreatedDirectories(paths: Set<string>): Promise<void> {
+  const deepestFirst = [...paths].sort((left, right) => right.length - left.length);
+  for (const path of deepestFirst) {
+    try { await rmdir(path); } catch (error) {
+      if (!new Set(["ENOENT", "ENOTEMPTY", "EEXIST"]).has(String((error as { code?: unknown }).code))) {
+        // Never turn cleanup of an empty setup directory into a broader deletion.
+      }
+    }
+  }
+}
+
+type SetupLock = { handle: FileHandle; path: string; token: string };
+
+async function acquireSetupLock(root: string): Promise<SetupLock> {
+  const path = join(root, ".fixmap-setup.lock");
+  const deadline = Date.now() + 10_000;
+  while (true) {
+    const token = `${process.pid}:${Date.now()}:${randomUUID()}`;
+    try {
+      const handle = await open(path, "wx", 0o600);
+      try {
+        await handle.writeFile(token, "utf8");
+        return { handle, path, token };
+      } catch (error) {
+        await handle.close();
+        try { await unlink(path); } catch { /* preserve the original lock creation error */ }
+        throw error;
+      }
+    } catch (error) {
+      const code = String((error as { code?: unknown }).code ?? "");
+      if (!new Set(["EEXIST", "EPERM", "EACCES"]).has(code)) throw error;
+
+      // Windows can briefly report EPERM while another setup closes and removes the lock.
+      // Retry that directory-entry transition, but preserve a persistent permission error
+      // when no lock file actually exists instead of misreporting it as another setup.
+      let lockPresent = code === "EEXIST";
+      if (!lockPresent) {
+        try {
+          await lstat(path);
+          lockPresent = true;
+        } catch (inspectionError) {
+          if ((inspectionError as { code?: unknown }).code !== "ENOENT") lockPresent = true;
+        }
+      }
+      if (Date.now() >= deadline) {
+        if (!lockPresent && code !== "EEXIST") throw error;
+        throw new Error(
+          `Another FixMap setup is still using "${path}". Wait for it to finish, or remove the lock only after confirming no setup process is running.`
+        );
+      }
+      await delay(25);
+    }
+  }
+}
+
+async function releaseSetupLock(lock: SetupLock): Promise<void> {
+  await lock.handle.close();
+  try {
+    const [contents, metadata] = await Promise.all([
+      readFile(lock.path, "utf8"),
+      lstat(lock.path)
+    ]);
+    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink > 1 || contents !== lock.token) {
+      throw new Error(`FixMap setup lock "${lock.path}" changed while setup was running; it was left in place for review.`);
+    }
+    await unlink(lock.path);
+  } catch (error) {
+    if ((error as { code?: unknown }).code !== "ENOENT") throw error;
+  }
+}
diff --git a/packages/cli/src/cli-runner.ts b/packages/cli/src/cli-runner.ts
index 9ab6a95..0b04417 100644
--- a/packages/cli/src/cli-runner.ts
+++ b/packages/cli/src/cli-runner.ts
@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { writeFile } from "node:fs/promises";
+import { realpath, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -336,6 +336,8 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
   if (options.command === "verify") {
     const planOnly = [options.issueText && "--issue", options.issueFile && "--issue-file", options.comparePath && "--compare", options.limit !== undefined && "--limit", options.exclude.length > 0 && "--exclude", options.explainPath && "--explain"].filter(Boolean);
     if (planOnly.length > 0) { stderr(`verify does not accept plan-only option(s): ${planOnly.join(", ")}.\n`); return 1; }
+    const outputCollision = await describeOutputInputCollision(options);
+    if (outputCollision) { stderr(`${outputCollision}\n`); return 1; }
     return runVerify(options, {
       stdout,
       stderr,
@@ -347,6 +349,9 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     return 1;
   }
 
+  const outputCollision = await describeOutputInputCollision(options);
+  if (outputCollision) { stderr(`${outputCollision}\n`); return 1; }
+
   try {
     options.issueText = loadIssueText(options, dependencies.readIssueFile ?? defaultReadIssueFile);
   } catch (error) {
@@ -908,6 +913,68 @@ function localPlanArtifactExclusions(options: CliOptions): string[] {
     });
 }
 
+/**
+ * A workflow input must remain usable after the command finishes. Reading a plan, task, or
+ * source file and then writing the result back through the same path silently destroyed the
+ * only copy while still exiting zero. Compare both path spelling and filesystem identity so
+ * relative aliases, symlinks, and hardlinks receive the same protection.
+ */
+async function describeOutputInputCollision(options: CliOptions): Promise<string | undefined> {
+  if (!options.output) return undefined;
+
+  const inputs: Array<{ flag: string; path: string }> = [];
+  if (options.command === "verify" && options.reportPath) {
+    inputs.push({ flag: "--report", path: options.reportPath });
+  } else {
+    if (options.issueFile && options.issueFile !== "-") {
+      inputs.push({ flag: "--issue-file", path: options.issueFile });
+    }
+    if (options.comparePath) {
+      inputs.push({ flag: "--compare", path: options.comparePath });
+    }
+    if (options.explainPath) {
+      inputs.push({
+        flag: "--explain",
+        path: isAbsolute(options.explainPath)
+          ? options.explainPath
+          : resolve(options.repo ?? process.cwd(), options.explainPath)
+      });
+    }
+  }
+
+  for (const input of inputs) {
+    if (await pathsReferToSameFile(options.output, input.path)) {
+      return `Refusing to write --output "${options.output}" because it is the same file as ${input.flag} "${input.path}". ` +
+        "Choose a different --output path so FixMap does not overwrite its input.";
+    }
+  }
+  return undefined;
+}
+
+async function pathsReferToSameFile(leftPath: string, rightPath: string): Promise<boolean> {
+  const left = resolve(leftPath);
+  const right = resolve(rightPath);
+  const normalize = process.platform === "win32"
+    ? (path: string) => path.toLowerCase()
+    : (path: string) => path;
+  if (normalize(left) === normalize(right)) return true;
+
+  try {
+    const [leftReal, rightReal] = await Promise.all([realpath(left), realpath(right)]);
+    if (normalize(leftReal) === normalize(rightReal)) return true;
+  } catch {
+    // A missing path cannot already alias an existing input. The command that consumes it
+    // will produce the more useful read/write error later.
+  }
+
+  try {
+    const [leftStat, rightStat] = await Promise.all([stat(left), stat(right)]);
+    return leftStat.ino !== 0 && leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+  } catch {
+    return false;
+  }
+}
+
 function loadIssueText(
   options: CliOptions,
   read: (path: string | number) => string | Buffer
diff --git a/packages/cli/test/cli-runner.test.ts b/packages/cli/test/cli-runner.test.ts
index 7392d0e..7d42795 100644
--- a/packages/cli/test/cli-runner.test.ts
+++ b/packages/cli/test/cli-runner.test.ts
@@ -1,8 +1,9 @@
 import { link, mkdir, mkdtemp, readFile, symlink, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { describe, expect, it, vi } from "vitest";
 import { parseArgs, runCli } from "../src/cli-runner.js";
+import { installAgentCommands } from "../src/agent-setup.js";
 import type { FixMapReport } from "@aryam/fixmap-core";
 
 const report: FixMapReport = {
@@ -184,6 +185,104 @@ describe("CLI argument handling", () => {
     expect(await readFile(outside, "utf8")).toBe("custom command\n");
   });
 
+  it("rolls back earlier agent commands when a later setup commit fails", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-rollback-"));
+
+    await expect(installAgentCommands({
+      repoRoot: root,
+      targets: ["claude", "cursor"]
+    }, {
+      beforeCommit: async (_entry, index) => {
+        if (index === 1) throw new Error("simulated second-target failure");
+      }
+    })).rejects.toThrow("simulated second-target failure");
+
+    await expect(readFile(join(root, ".claude", "skills", "fixmap", "SKILL.md"), "utf8"))
+      .rejects.toMatchObject({ code: "ENOENT" });
+    await expect(readFile(join(root, ".cursor", "commands", "fixmap.md"), "utf8"))
+      .rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("rejects a target hard link inserted after setup preflight without touching its destination", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-race-"));
+    const outside = join(root, "outside-command.md");
+    const target = join(root, ".cursor", "commands", "fixmap.md");
+    await writeFile(outside, "outside stays unchanged\n", "utf8");
+
+    await expect(installAgentCommands({
+      repoRoot: root,
+      targets: ["claude", "cursor"]
+    }, {
+      beforeCommit: async (_entry, index) => {
+        if (index === 1) await link(outside, target);
+      }
+    })).rejects.toThrow("hard-linked");
+
+    expect(await readFile(outside, "utf8")).toBe("outside stays unchanged\n");
+    await expect(readFile(join(root, ".claude", "skills", "fixmap", "SKILL.md"), "utf8"))
+      .rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("rejects a regular target inserted after setup preflight without overwriting it", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-created-race-"));
+    const target = join(root, ".cursor", "commands", "fixmap.md");
+
+    await expect(installAgentCommands({
+      repoRoot: root,
+      targets: ["claude", "cursor"]
+    }, {
+      beforeCommit: async (_entry, index) => {
+        if (index === 1) await writeFile(target, "concurrent custom command\n", "utf8");
+      }
+    })).rejects.toThrow("changed while setup was running");
+
+    expect(await readFile(target, "utf8")).toBe("concurrent custom command\n");
+    await expect(readFile(join(root, ".claude", "skills", "fixmap", "SKILL.md"), "utf8"))
+      .rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("rejects an existing target modified after setup preflight without overwriting it", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-modified-race-"));
+    const target = join(root, ".cursor", "commands", "fixmap.md");
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, "original custom command\n", "utf8");
+
+    await expect(installAgentCommands({
+      repoRoot: root,
+      targets: ["cursor"],
+      force: true
+    }, {
+      beforeCommit: async () => {
+        await writeFile(target, "concurrent replacement\n", "utf8");
+      }
+    })).rejects.toThrow("changed while setup was running");
+
+    expect(await readFile(target, "utf8")).toBe("concurrent replacement\n");
+  });
+
+  it("serializes concurrent setup calls without partial files or Windows rename collisions", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-agent-setup-concurrent-"));
+    const targets = ["claude", "cursor", "copilot", "agents"] as const;
+
+    const runs = await Promise.all(Array.from(
+      { length: 20 },
+      () => installAgentCommands({ repoRoot: root, targets: [...targets] })
+    ));
+
+    expect(runs).toHaveLength(20);
+    expect(runs.every((entries) => entries.length === 4)).toBe(true);
+    for (const path of [
+      [".claude", "skills", "fixmap", "SKILL.md"],
+      [".cursor", "commands", "fixmap.md"],
+      [".github", "prompts", "fixmap.prompt.md"],
+      [".agents", "skills", "fixmap", "SKILL.md"]
+    ]) {
+      expect(await readFile(join(root, ...path), "utf8")).toContain("fixmap features");
+    }
+    await expect(readFile(join(root, ".fixmap-setup.lock"), "utf8"))
+      .rejects.toMatchObject({ code: "ENOENT" });
+  });
+
   it("validates a saved report with a Windows byte-order mark without custom JavaScript", async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-validate-"));
     const path = join(root, "report.json");
@@ -467,6 +566,62 @@ describe("CLI argument handling", () => {
     }));
   });
 
+  it.each([
+    ["--compare", (root: string, input: string) => [
+      "plan", "--issue", "reset fails", "--repo", root,
+      "--compare", input, "--format", "json", "--output", input
+    ]],
+    ["--report", (root: string, input: string) => [
+      "verify", "--report", input, "--repo", root,
+      "--working-tree", "--format", "json", "--output", input
+    ]],
+    ["--issue-file", (root: string, input: string) => [
+      "plan", "--issue-file", input, "--repo", root,
+      "--format", "json", "--output", input
+    ]],
+    ["--explain", (root: string, input: string) => [
+      "plan", "--issue", "reset fails", "--repo", root,
+      "--explain", "source.ts", "--format", "json", "--output", input
+    ]]
+  ])("refuses to overwrite its %s input", async (flag, makeArgs) => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-output-input-collision-"));
+    const input = join(root, flag === "--explain" ? "source.ts" : flag === "--issue-file" ? "task.md" : "plan.json");
+    const contents = flag === "--issue-file" || flag === "--explain"
+      ? "reset fails\n"
+      : JSON.stringify(report);
+    await writeFile(input, contents, "utf8");
+    const io = capture();
+    const buildReport = vi.fn(async () => report);
+
+    expect(await runCli(makeArgs(root, input), { ...io.dependencies, buildReport })).toBe(1);
+    expect(await readFile(input, "utf8")).toBe(contents);
+    expect(buildReport).not.toHaveBeenCalled();
+    expect(io.stderr.join("")).toContain(`same file as ${flag}`);
+    expect(io.stderr.join("")).toContain("does not overwrite its input");
+  });
+
+  it.each([
+    ["symbolic link", async (target: string, alias: string) => symlink(target, alias)],
+    ["hard link", async (target: string, alias: string) => link(target, alias)]
+  ])("detects a comparison input reached through a %s alias", async (_label, makeAlias) => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-output-alias-collision-"));
+    const planPath = join(root, "plan.json");
+    const outputAlias = join(root, "result.json");
+    const contents = JSON.stringify(report);
+    await writeFile(planPath, contents, "utf8");
+    await makeAlias(planPath, outputAlias);
+    const io = capture();
+    const buildReport = vi.fn(async () => report);
+
+    expect(await runCli([
+      "plan", "--issue", "reset fails", "--repo", root,
+      "--compare", planPath, "--format", "json", "--output", outputAlias
+    ], { ...io.dependencies, buildReport })).toBe(1);
+    expect(await readFile(planPath, "utf8")).toBe(contents);
+    expect(buildReport).not.toHaveBeenCalled();
+    expect(io.stderr.join("")).toContain("same file as --compare");
+  });
+
   it("writes an explanation to --output instead of silently printing it", async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-explain-output-"));
     const outputPath = join(root, "explanation.json");
diff --git a/packages/core/src/rank.ts b/packages/core/src/rank.ts
index 05ba2c2..7709c95 100644
--- a/packages/core/src/rank.ts
+++ b/packages/core/src/rank.ts
@@ -537,7 +537,18 @@ function matchMentionedPaths(mentions: Set<string>, repoPaths: string[]): Set<st
 }
 
 function pathMatchesMention(path: string, mention: string): boolean {
-  return path === mention || path.endsWith(`/${mention}`) || mention.endsWith(`/${path}`);
+  const normalizedPath = path.toLowerCase();
+  const normalizedMention = mention.toLowerCase();
+  if (normalizedPath === normalizedMention ||
+    normalizedPath.endsWith(`/${normalizedMention}`) ||
+    normalizedMention.endsWith(`/${normalizedPath}`)) {
+    return true;
+  }
+  if (!normalizedMention.includes("/") && !normalizedMention.includes(".")) {
+    const fileName = normalizedPath.split("/").at(-1) ?? "";
+    return fileName.replace(/\.[^.]+$/, "") === normalizedMention;
+  }
+  return false;
 }
 
 function compiledSourcePathVariants(path: string): string[] {
@@ -631,10 +642,13 @@ function isTypeDeclarationPath(path: string): boolean {
 
 function targetsDocumentation(taskText: string): boolean {
   const documentation = "(?:docs?|documentation|readme|guide|copy)";
-  const action = "(?:add|edit|update|write|rewrite|revise|remove|correct|document|improve)";
+  const action = "(?:add|change|correct|document|edit|fix|improve|remove|revise|rewrite|update|write)";
+  const defect = "(?:typos?|spelling|grammar|wording|broken links?)";
   return (
     new RegExp(`\\b${action}\\b[^\\n.]{0,60}\\b${documentation}\\b`, "i").test(taskText) ||
-    new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${action}\\b`, "i").test(taskText)
+    new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${action}\\b`, "i").test(taskText) ||
+    new RegExp(`\\b${defect}\\b[^\\n.]{0,60}\\b${documentation}\\b`, "i").test(taskText) ||
+    new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${defect}\\b`, "i").test(taskText)
   );
 }
 
diff --git a/packages/core/src/repo-scan.ts b/packages/core/src/repo-scan.ts
index 97f9a36..83fc89e 100644
--- a/packages/core/src/repo-scan.ts
+++ b/packages/core/src/repo-scan.ts
@@ -33,6 +33,13 @@ const SOURCE_EXTENSIONS = new Set([
   ".yaml",
   ".yml"
 ]);
+const CONVENTIONAL_DOCUMENT_NAMES = new Set([
+  "authors", "changelog", "code_of_conduct", "contributing", "license", "notice", "readme", "security"
+]);
+const CONVENTIONAL_CONFIG_NAMES = new Set([
+  ".dockerignore", ".editorconfig", ".gitattributes", ".gitignore", ".npmignore",
+  "codeowners", "dockerfile", "gemfile", "jenkinsfile", "makefile", "procfile", "rakefile", "vagrantfile"
+]);
 
 /**
  * A single-file component is mostly template and style. Sampling the whole file let markup
@@ -341,10 +348,13 @@ function isRecord(candidate: unknown): candidate is Record<string, unknown> {
 
 function isCachedRelativePath(candidate: unknown): candidate is string {
   if (typeof candidate !== "string" || candidate.trim().length === 0 || candidate.includes("\0") ||
-    isAbsolute(candidate) || /^[A-Za-z]:[\\/]/.test(candidate)) {
+    isAbsolute(candidate) || /^[\\/]/.test(candidate) || /^[A-Za-z]:/.test(candidate)) {
     return false;
   }
-  const segments = normalizePath(candidate).split("/");
+  // Cache files may move between Windows and POSIX. Normalize both separators regardless
+  // of the current host so `..\secret`, UNC paths, and drive-relative paths cannot become
+  // trusted repository paths merely because they were read on Linux.
+  const segments = candidate.replace(/\\/g, "/").split("/");
   return segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 }
 
@@ -760,7 +770,8 @@ async function toRepoFile(absolutePath: string, relativePath: string): Promise<S
   }
 
   const extension = extname(relativePath);
-  const isSource = SOURCE_EXTENSIONS.has(extension);
+  const conventionalKind = classifyConventionalTextFile(relativePath);
+  const isSource = SOURCE_EXTENSIONS.has(extension) || conventionalKind !== undefined;
   const sample = isSource
     ? await readTextSample(absolutePath, fileStat.size)
     : { text: "", complete: true };
@@ -1081,7 +1092,9 @@ function detectPackageManager(files: RepoFile[]): RepoMap["packageManager"] {
 
 function classifyFile(path: string, extension: string): RepoFile["kind"] {
   const lower = path.toLowerCase();
-  if (extension === ".md" || lower.startsWith("docs/") || lower === "license") return "documentation";
+  const conventionalKind = classifyConventionalTextFile(path);
+  if (conventionalKind) return conventionalKind;
+  if (extension === ".md" || lower.startsWith("docs/")) return "documentation";
   if (
     lower.startsWith(".github/") ||
     [".json", ".yaml", ".yml"].includes(extension) ||
@@ -1091,6 +1104,13 @@ function classifyFile(path: string, extension: string): RepoFile["kind"] {
   return "other";
 }
 
+function classifyConventionalTextFile(path: string): "documentation" | "config" | undefined {
+  const name = path.replace(/\\/g, "/").split("/").at(-1)?.toLowerCase() ?? "";
+  if (CONVENTIONAL_DOCUMENT_NAMES.has(name)) return "documentation";
+  if (CONVENTIONAL_CONFIG_NAMES.has(name)) return "config";
+  return undefined;
+}
+
 async function readTextSample(
   path: string,
   sizeBytes: number
diff --git a/packages/core/src/signals.ts b/packages/core/src/signals.ts
index 233c307..7dcebb1 100644
--- a/packages/core/src/signals.ts
+++ b/packages/core/src/signals.ts
@@ -159,6 +159,8 @@ const FILE_MENTION_PATTERN =
     "\\.(?:[cm]?[jt]sx?|json|ya?ml|mdx?|css|scss|less|html|py|rb|rs|go|java|kt|c|cc|cpp|h|hpp|d\\.ts)\\b",
     "g"
   );
+const CONVENTIONAL_FILE_MENTION_PATTERN =
+  /\b(?:AUTHORS|CHANGELOG|CODE_OF_CONDUCT|CONTRIBUTING|LICENSE|NOTICE|README|SECURITY|CODEOWNERS|Dockerfile|Gemfile|Jenkinsfile|Makefile|Procfile|Rakefile|Vagrantfile)\b/gi;
 const MEMBER_MENTION_PATTERN =
   /\b(?:window|globalThis|process|request|response|req|res|this)\.([$A-Za-z_][$A-Za-z0-9_$]*)\b/g;
 const FILE_EXTENSIONS = new Set([
@@ -327,6 +329,9 @@ function isEscaped(text: string, index: number): boolean {
 
 export function extractFileMentions(text: string): Set<string> {
   const mentions = new Set<string>();
+  for (const match of text.matchAll(CONVENTIONAL_FILE_MENTION_PATTERN)) {
+    if (match[0]) mentions.add(match[0]);
+  }
   // A blob permalink with an immutable commit is stronger than a prose path mention: it
   // is a deliberate pointer to code. Preserve only its repository-relative path before
   // stripping URLs generally. This avoids turning badges, issue links and external docs
diff --git a/packages/core/src/validate.ts b/packages/core/src/validate.ts
index f6f1274..8c23ecc 100644
--- a/packages/core/src/validate.ts
+++ b/packages/core/src/validate.ts
@@ -47,7 +47,7 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
   const invalid = contextFiles.findIndex((file) => {
     if (!isRecord(file)) return true;
     const ranked = file;
-    if (typeof ranked.path !== "string" || ranked.path.trim().length === 0) return true;
+    if (!isRepositoryRelativePath(ranked.path)) return true;
     if ((versioned || ranked.rank !== undefined) && (!Number.isSafeInteger(ranked.rank) || (ranked.rank as number) < 1)) return true;
     if ((versioned || ranked.score !== undefined) && (typeof ranked.score !== "number" || !Number.isFinite(ranked.score))) return true;
     if (
@@ -88,7 +88,7 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
   const invalidRoute = testRoutes.findIndex((route) => {
     if (!isRecord(route)) return true;
     return typeof route.command !== "string" || !route.command.trim() ||
-      !isNonBlankStringArray(route.relatedFiles) ||
+      !isRepositoryRelativePathArray(route.relatedFiles) ||
       ((versioned || route.kind !== undefined) && route.kind !== "test" && route.kind !== "validation") ||
       ((versioned || route.reason !== undefined) && typeof route.reason !== "string");
   });
@@ -115,8 +115,8 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
     };
   }
 
-  if (!isNonBlankStringArray(record.changedFiles)) {
-    return { success: false, message: `${label} has invalid changedFiles; every entry must be a non-empty string path.` };
+  if (!isRepositoryRelativePathArray(record.changedFiles)) {
+    return { success: false, message: `${label} has invalid changedFiles; every entry must be a safe repository-relative path.` };
   }
 
   const diagnostics = record.diagnostics as unknown[];
@@ -125,7 +125,7 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
     return typeof diagnostic.code !== "string" || !diagnostic.code.trim() ||
       typeof diagnostic.message !== "string" ||
       (diagnostic.severity !== "info" && diagnostic.severity !== "warning" && diagnostic.severity !== "error") ||
-      (diagnostic.paths !== undefined && !isNonBlankStringArray(diagnostic.paths));
+      (diagnostic.paths !== undefined && !isRepositoryRelativePathArray(diagnostic.paths));
   });
   if (invalidDiagnostic !== -1) {
     return {
@@ -167,7 +167,7 @@ export function validateFixMapReport(candidate: unknown, label: string): Validat
       !isRecord(identifier) ||
       typeof identifier.identifier !== "string" || !identifier.identifier.trim() ||
       !isIdentifierStatus(identifier.status) ||
-      !isNonBlankStringArray(identifier.matchedFiles)
+      !isRepositoryRelativePathArray(identifier.matchedFiles)
     );
     if (invalidIdentifier !== -1) {
       return {
@@ -188,8 +188,17 @@ function isStringArray(candidate: unknown): candidate is string[] {
   return Array.isArray(candidate) && candidate.every((entry) => typeof entry === "string");
 }
 
-function isNonBlankStringArray(candidate: unknown): candidate is string[] {
-  return isStringArray(candidate) && candidate.every((entry) => entry.trim().length > 0);
+function isRepositoryRelativePathArray(candidate: unknown): candidate is string[] {
+  return Array.isArray(candidate) && candidate.every(isRepositoryRelativePath);
+}
+
+function isRepositoryRelativePath(candidate: unknown): candidate is string {
+  if (typeof candidate !== "string" || !candidate.trim() || candidate.includes("\0") ||
+    /^[\\/]/.test(candidate) || /^[A-Za-z]:/.test(candidate)) {
+    return false;
+  }
+  const segments = candidate.replace(/\\/g, "/").split("/");
+  return segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 }
 
 function isNullableFiniteNumber(candidate: unknown): boolean {
diff --git a/packages/core/test/plan.test.ts b/packages/core/test/plan.test.ts
index f718c4f..33849a2 100644
--- a/packages/core/test/plan.test.ts
+++ b/packages/core/test/plan.test.ts
@@ -91,7 +91,7 @@ describe("buildFixMapReport", () => {
     expect(diagnostic!.message).not.toContain("z".repeat(100));
     // The terms a reader can act on survive.
     expect(diagnostic!.message).toContain("flurbulator");
-  });
+  }, 15_000);
 
   it("does not let a giant diff spec become a giant diagnostic", async () => {
     const root = await createAuthFixture();
@@ -106,7 +106,7 @@ describe("buildFixMapReport", () => {
     // and once inside git's own error text.
     expect(diagnostic!.message).not.toContain("Y".repeat(200));
     expect(diagnostic!.message).toContain("notadiff");
-  });
+  }, 15_000);
 
   it("does not report a term diagnostic when context files are found", async () => {
     const root = await createAuthFixture();
diff --git a/packages/core/test/rank.test.ts b/packages/core/test/rank.test.ts
index a6c2efb..af2fd42 100644
--- a/packages/core/test/rank.test.ts
+++ b/packages/core/test/rank.test.ts
@@ -298,6 +298,47 @@ describe("rankContextFiles", () => {
     expect(ranked[0]?.reasons).toContain("explicitly named in the task");
   });
 
+  it.each(["README", "README.md"])("ranks %s for a terse README typo task", (path) => {
+    const repo: RepoMap = {
+      root: "/repo",
+      packageScripts: [],
+      changedFiles: [],
+      diffText: "",
+      packageManager: "npm",
+      diagnostics: [],
+      files: [
+        { path, extension: path.endsWith(".md") ? ".md" : "", sizeBytes: 100, isSource: true, isTest: false, kind: "documentation", textSample: "Hello World" },
+        { path: "src/server.ts", extension: ".ts", sizeBytes: 100, isSource: true, isTest: false, kind: "code", textSample: "export const server = true;" }
+      ]
+    };
+
+    const ranked = rankContextFiles(repo, { issueText: "README typo" });
+
+    expect(ranked[0]?.path).toBe(path);
+    expect(ranked[0]?.reasons).toContain("explicitly named in the task");
+    expect(ranked[0]?.reasons).toContain("documentation-focused task");
+  });
+
+  it("treats changing README copy as documentation work", () => {
+    const repo: RepoMap = {
+      root: "/repo",
+      packageScripts: [],
+      changedFiles: [],
+      diffText: "",
+      packageManager: "npm",
+      diagnostics: [],
+      files: [
+        { path: "README", extension: "", sizeBytes: 100, isSource: true, isTest: false, kind: "documentation", textSample: "Hello World" }
+      ]
+    };
+
+    const ranked = rankContextFiles(repo, { issueText: "change README.md greeting" });
+
+    expect(ranked[0]?.path).toBe("README");
+    expect(ranked[0]?.reasons).toContain("documentation-focused task");
+    expect(ranked[0]?.reasons).not.toContain("documentation deprioritized for an implementation task");
+  });
+
   it("matches a compiled JavaScript path mention to its TypeScript source file", () => {
     const repo: RepoMap = {
       root: "/repo",
diff --git a/packages/core/test/repo-scan.test.ts b/packages/core/test/repo-scan.test.ts
index 50b47b8..609b25a 100644
--- a/packages/core/test/repo-scan.test.ts
+++ b/packages/core/test/repo-scan.test.ts
@@ -75,6 +75,21 @@ describe("scanRepo", () => {
     ]);
   });
 
+  it("samples and classifies conventional extensionless documents and build files", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-conventional-text-"));
+    await writeFile(join(root, "README"), "Hello from the project documentation\n");
+    await writeFile(join(root, "Dockerfile"), "FROM node:24\n");
+
+    const repo = await scanRepo({ repoRoot: root });
+    const readme = repo.files.find((file) => file.path === "README");
+    const dockerfile = repo.files.find((file) => file.path === "Dockerfile");
+
+    expect(readme).toMatchObject({ isSource: true, kind: "documentation" });
+    expect(readme?.textSample).toContain("project documentation");
+    expect(dockerfile).toMatchObject({ isSource: true, kind: "config" });
+    expect(dockerfile?.textSample).toContain("FROM node:24");
+  });
+
   it("recognizes Go, Python, and TypeScript declaration test naming conventions", async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-test-patterns-"));
     for (const path of ["handler_test.go", "test_reset.py", "reset_test.py", "types.test-d.ts"]) {
@@ -794,7 +809,10 @@ describe("scanRepo", () => {
       };
       const mutations: Array<(cached: MutableCachedScan) => void> = [
         (cached) => { cached.files[0].path = "../outside.ts"; },
+        (cached) => { cached.files[0].path = "..\\outside.ts"; },
+        (cached) => { cached.files[0].path = "\\\\server\\share\\outside.ts"; },
         (cached) => { cached.trackedFiles = ["C:/outside.ts"]; },
+        (cached) => { cached.trackedFiles = ["C:outside.ts"]; },
         (cached) => {
           cached.packageScripts = [{ name: "test", command: "npm test", packageDir: "../outside" }];
         },
diff --git a/packages/core/test/signals.test.ts b/packages/core/test/signals.test.ts
index 7d6939a..0277438 100644
--- a/packages/core/test/signals.test.ts
+++ b/packages/core/test/signals.test.ts
@@ -2,6 +2,15 @@ import { describe, expect, it } from "vitest";
 import { extractTaskSignals, tokenizeText } from "../src/signals.js";
 
 describe("extractTaskSignals", () => {
+  it.each([
+    ["README typo", "readme"],
+    ["fix dockerfile", "dockerfile"],
+    ["update CODEOWNERS", "codeowners"]
+  ])("recognizes conventional extensionless file mentions in %j", (issueText, expected) => {
+    const signals = extractTaskSignals({ issueText });
+    expect([...signals.fileMentions].map((mention) => mention.toLowerCase())).toContain(expected);
+  });
+
   it("tokenizes only added and removed diff lines, not diff metadata", () => {
     const diffText = [
       "diff --git a/src/auth/reset-password.ts b/src/auth/reset-password.ts",
diff --git a/packages/core/test/validate.test.ts b/packages/core/test/validate.test.ts
index c3be64d..48bfaa8 100644
--- a/packages/core/test/validate.test.ts
+++ b/packages/core/test/validate.test.ts
@@ -59,6 +59,23 @@ describe("validateFixMapReport", () => {
     if (!outOfOrder.success) expect(outOfOrder.message).toContain("out-of-order contextFiles rank");
   });
 
+  it.each([
+    ["POSIX traversal", "../outside.ts"],
+    ["Windows traversal", "..\\outside.ts"],
+    ["POSIX absolute", "/etc/passwd"],
+    ["Windows absolute", "C:\\outside.ts"],
+    ["Windows drive-relative", "C:outside.ts"],
+    ["UNC", "\\\\server\\share\\outside.ts"]
+  ])("rejects %s report paths on every host", (_label, path) => {
+    const result = validateFixMapReport({
+      ...envelope,
+      contextFiles: [{ ...rankedContext, path }]
+    }, "report");
+
+    expect(result.success).toBe(false);
+    if (!result.success) expect(result.message).toContain("invalid contextFiles entry");
+  });
+
   it("rejects unsupported report versions", () => {
     const result = validateFixMapReport({ ...envelope, reportVersion: 2 }, "report");
 

From c637c5eee57323fc9dcb7d831e259490284b99be Mon Sep 17 00:00:00 2001
From: Aryam Goyal <aryamgoyal18@gmail.com>
Date: Tue, 11 Aug 2026 13:50:55 +0530
Subject: [PATCH 07/10] Release FixMap 0.8.9 reliability sweep

---
 .github/ISSUE_TEMPLATE/config.yml             |    3 +
 .github/workflows/ci.yml                      |   41 +-
 .github/workflows/external-eval.yml           |    5 +-
 .github/workflows/publish.yml                 |   10 +-
 CHANGELOG.md                                  |   41 +
 README.md                                     |   29 +-
 action.yml                                    |    8 +-
 apps/web/app/_components/copy-command.tsx     |   30 +-
 .../app/_components/pixel-sink-surface.tsx    |   10 +-
 apps/web/app/_lib/site-data.ts                |   20 +-
 apps/web/app/changelog/page.tsx               |   39 +-
 apps/web/app/demo.tsx                         |   26 +-
 apps/web/app/docs/page.tsx                    |    2 +-
 apps/web/app/evidence/page.tsx                |   17 +-
 apps/web/app/globals.css                      |   12 +-
 apps/web/app/sitemap.ts                       |   12 +-
 apps/web/package.json                         |    4 +-
 benchmarks/adversarial/results.json           |   38 +-
 benchmarks/external/baseline-results.json     | 1216 ++++++++--------
 benchmarks/external/results.json              |  284 ++--
 benchmarks/external/savings-results.json      |  367 ++---
 benchmarks/heldout/baseline-results.json      |  906 ++++++------
 benchmarks/heldout/results.json               |  203 +--
 docs/BENCHMARKS.md                            |    2 +-
 docs/assets/fixmap-benchmark.svg              |    6 +-
 docs/assets/fixmap-cli-demo.svg               |   47 +-
 docs/releases/v0.8.9-issue-verification.md    |  187 +++
 .../releases/v0.8.9-post-release-checklist.md |   17 +
 docs/releases/v0.8.9-release-notes-draft.md   |   28 +
 docs/releases/v0.8.9-social-posts.md          |   41 +
 .../reports/declines-fabricated-identifier.md |    2 +-
 examples/reports/declines-unmatched-terms.md  |    2 +-
 examples/reports/declines-vague-task.md       |    1 +
 examples/reports/workspace-api-discount.md    |    4 +-
 examples/reports/workspace-utils-rounding.md  |    5 +-
 package-lock.json                             | 1293 ++++++++++-------
 package.json                                  |   15 +-
 packages/action/action.yml                    |    8 +-
 packages/action/dist/index.mjs                | 1134 ++++++++++-----
 packages/action/package.json                  |    4 +-
 packages/action/src/github.ts                 |   47 +-
 packages/action/src/issue-source.ts           |    2 +-
 packages/action/src/runner.ts                 |   71 +-
 packages/action/test/github.test.ts           |   58 +-
 packages/action/test/issue-source.test.ts     |    1 +
 packages/action/test/runner.test.ts           |   52 +-
 packages/cli/README.md                        |    5 +-
 packages/cli/package.json                     |    4 +-
 packages/cli/src/agent-setup.ts               |   12 +-
 packages/cli/src/cli-runner.ts                |  153 +-
 packages/cli/src/doctor.ts                    |   63 +-
 packages/cli/src/explain-path.ts              |   31 +
 packages/cli/src/mcp.ts                       |   36 +-
 packages/cli/src/repository-source.ts         |   51 +-
 packages/cli/test/cli-runner.test.ts          |  138 +-
 packages/cli/test/doctor.test.ts              |   39 +
 packages/cli/test/explain-path.test.ts        |   53 +
 packages/cli/test/mcp.test.ts                 |   47 +-
 packages/core/package.json                    |    2 +-
 packages/core/src/browser.ts                  |    6 +-
 packages/core/src/cli-quote.ts                |    9 +
 packages/core/src/compare.ts                  |   50 +-
 packages/core/src/explain.ts                  |   34 +-
 packages/core/src/grounding.ts                |   43 +-
 packages/core/src/import-graph.ts             |   98 +-
 packages/core/src/index.ts                    |    4 +-
 packages/core/src/languages.ts                |   73 +-
 packages/core/src/markdown.ts                 |    7 +
 packages/core/src/paths.ts                    |   48 +-
 packages/core/src/plan.ts                     |    8 +-
 packages/core/src/rank.ts                     |  288 ++--
 packages/core/src/repo-scan.ts                |  159 +-
 packages/core/src/report.ts                   |  104 +-
 packages/core/src/signals.ts                  |  170 ++-
 packages/core/src/test-gates.ts               |   18 +-
 packages/core/src/types.ts                    |   11 +-
 packages/core/src/verify.ts                   |   32 +-
 packages/core/test/compare.test.ts            |   32 +
 packages/core/test/entrypoints.test.ts        |   21 +
 packages/core/test/exclude.test.ts            |    9 +
 .../core/test/github-issues-600-627.test.ts   |  173 +++
 packages/core/test/grounding.test.ts          |   11 +
 packages/core/test/import-graph.test.ts       |   34 +
 packages/core/test/languages.test.ts          |   34 +-
 packages/core/test/plan.test.ts               |   18 +-
 packages/core/test/rank.test.ts               |  247 +++-
 packages/core/test/render-demo-wrap.test.mjs  |    7 +
 packages/core/test/repo-scan.test.ts          |   58 +-
 packages/core/test/report.test.ts             |   29 +-
 packages/core/test/signals.test.ts            |   98 +-
 packages/core/test/test-gates.test.ts         |   13 +
 packages/core/test/verify.test.ts             |   43 +
 scripts/benchmark-savings.mjs                 |   10 +-
 scripts/check-action-metadata.mjs             |   13 +-
 scripts/check-generated.mjs                   |   76 +
 scripts/check-server-manifest.mjs             |   12 +
 scripts/evaluate-baseline.mjs                 |   18 +-
 scripts/evaluate-external.mjs                 |   45 +-
 scripts/evaluate.mjs                          |   20 +-
 scripts/lib/wrap.mjs                          |   23 +-
 scripts/render-benchmark-card.mjs             |    8 +-
 scripts/smoke-workspace.mjs                   |    5 +-
 server.json                                   |    4 +-
 103 files changed, 6244 insertions(+), 2963 deletions(-)
 create mode 100644 docs/releases/v0.8.9-issue-verification.md
 create mode 100644 docs/releases/v0.8.9-post-release-checklist.md
 create mode 100644 docs/releases/v0.8.9-release-notes-draft.md
 create mode 100644 docs/releases/v0.8.9-social-posts.md
 create mode 100644 packages/cli/src/explain-path.ts
 create mode 100644 packages/cli/test/explain-path.test.ts
 create mode 100644 packages/core/src/cli-quote.ts
 create mode 100644 packages/core/src/markdown.ts
 create mode 100644 packages/core/test/entrypoints.test.ts
 create mode 100644 packages/core/test/github-issues-600-627.test.ts
 create mode 100644 scripts/check-generated.mjs

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index f950ebe..8c06e85 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Question or workflow idea
+    url: https://github.com/aryamthecodebreaker/FixMap/discussions
+    about: Ask usage questions, share examples, or discuss workflow ideas.
   - name: Security vulnerability
     url: https://github.com/aryamthecodebreaker/FixMap/security/advisories/new
     about: Report security-sensitive issues privately.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2e532a7..730a69f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,18 +2,55 @@ name: CI
 
 on:
   push:
+    branches: [main]
   pull_request:
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     runs-on: ubuntu-latest
+    timeout-minutes: 45
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
         with:
           node-version: 24
           cache: npm
       - run: npm ci
       - run: npm run ci
+
+  compatibility:
+    name: Node ${{ matrix.node }} on ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            node: "20.11"
+          - os: ubuntu-latest
+            node: "22"
+          - os: windows-latest
+            node: "24"
+          - os: macos-latest
+            node: "24"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm test
diff --git a/.github/workflows/external-eval.yml b/.github/workflows/external-eval.yml
index 8d1ec67..ba2bd7f 100644
--- a/.github/workflows/external-eval.yml
+++ b/.github/workflows/external-eval.yml
@@ -10,11 +10,12 @@ permissions:
 
 jobs:
   evaluate:
+    if: github.event_name != 'schedule' || github.repository == 'aryamthecodebreaker/FixMap'
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps:
-      - uses: actions/checkout@v7
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
         with:
           node-version: 24
           cache: npm
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 459f163..cb83db7 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -14,8 +14,7 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: write
-  id-token: write
+  contents: read
 
 concurrency:
   group: fixmap-release
@@ -28,6 +27,9 @@ env:
 
 jobs:
   publish:
+    permissions:
+      contents: write
+      id-token: write
     runs-on: ubuntu-latest
     timeout-minutes: 45
     steps:
@@ -42,7 +44,7 @@ jobs:
           fi
           echo "VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_ENV"
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
 
@@ -176,7 +178,7 @@ jobs:
             exit "$STATUS"
           fi
 
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
         with:
           node-version: 24
           cache: npm
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3e303e4..82299d3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,47 @@ Accuracy figures inside a released entry are the numbers measured **at that rele
 left as written. The current numbers live on the [evidence page](https://usefixmap.vercel.app/evidence),
 which is generated from the recorded results rather than transcribed by hand.
 
+## 0.8.9 - 2026-08-11
+
+### Added
+
+- `fixmap setup` installs a discoverable `/fixmap` command for Claude Code, Cursor, GitHub Copilot, and Agent Skills; invoking it without a task opens the complete feature catalog. `fixmap features` exposes the same catalog directly.
+- `fixmap validate <report.json>` checks the versioned report contract, while `--fail-on warning` and the Action's `fail-on: warning` provide an opt-in strict Verify gate.
+- Plan, Explain, MCP, and the Action expose a visible fresh-scan path with `--no-cache`/`noCache`, and cache hits now report age with bounded expiry and eviction.
+
+### Fixed
+
+- Ranking, grounding, file mentions, definition detection, import proximity, clustering, confidence, risk vocabulary, diff evidence, exact literals, Unicode text, inflections, typographic quotes, and generated/backup/configuration heuristics were corrected across the complete #500-#627 issue sweep.
+- Repository mapping now handles nested package-manager lockfiles, conflicting roots, Windows and absolute exclusion paths, large ignore lists, tracked dirty cache states, BOM-less UTF-16 task files, oversized diffs, more source extensions, and language/test routing for C#, Java, PHP, Ruby, Go, Rust, Python, and JavaScript ecosystems.
+- Explain, Compare, Verify, Validate, Doctor, remote repository acquisition, CLI parsing/output, MCP schemas, and copy-paste commands now fail clearly and preserve safe paths instead of silently accepting ambiguous or malformed state.
+- GitHub Action comments, outputs, and job summaries stay within platform limits; API errors, pagination, permissions, credentials, Markdown, temporary clones, and generated bundle/metadata drift are handled defensively.
+
+### Security and release engineering
+
+- CI is least-privilege, timeout-bounded, non-duplicating, immutable-action pinned, full-tree audited, non-mutating, and configured for Node 20.11/22 plus Windows and macOS compatibility coverage.
+- The publish workflow scopes write/OIDC permission to the release job and verifies the exact main commit, version metadata, npm packages, clean global install, MCP Registry entry, and GitHub Release before succeeding.
+
+### Website and documentation
+
+- The website uses a restrained editorial product system with clearer navigation, evidence, metadata, copy feedback, visibility-safe motion, and an honest interactive demo instead of synthetic marketing presentation.
+- README and the npm package documentation now contain the full FixMap feature catalog, `/fixmap` setup, exclusion syntax, cache/report compatibility, Action controls, and public evidence boundaries.
+
+### Evidence
+
+- The release ledger maps all 126 open GitHub issues in #500-#627 (excluding already-closed #542 and #599) plus every item in the attached 30-finding review to a resolution and verification source.
+- External, held-out, adversarial, BM25/lexical/path baselines, savings, rendered examples, package smoke tests, and the 1,000-file scan gate were regenerated and checked. The held-out evidence continues to state plainly where BM25 leads FixMap.
+
+### Installation
+
+```bash
+npm install --global @aryam/fixmap@0.8.9
+fixmap doctor
+fixmap setup
+fixmap features
+```
+
+The release is complete only when the exact main commit is tagged `v0.8.9`, npm and MCP Registry serve 0.8.9, the GitHub release and Action tag resolve to that commit, production serves the matching website, and every public smoke check passes.
+
 ## 0.8.8 - 2026-08-08
 
 ### Added
diff --git a/README.md b/README.md
index b0d7423..c8ac781 100644
--- a/README.md
+++ b/README.md
@@ -75,36 +75,41 @@ Validate a saved report before another tool consumes it:
 fixmap validate plan.json
 ```
 
-Use `--working-tree` for staged and unstaged tracked edits, `--include-untracked` when new files should count as changes, `--exclude` or `.fixmapignore` to focus the map, and `--no-cache` to force a fresh scan. Run `fixmap --help` for the complete command reference.
+Use `--working-tree` for staged and unstaged tracked edits, `--include-untracked` when new files should count as changes, `--exclude` or `.fixmapignore` to focus the map, and `--no-cache` to force a fresh scan. Add `--fail-on warning` to Verify when advisory findings must fail CI. Run `fixmap --help` for the complete command reference.
 
 ## Complete feature catalog
 
 ### Inputs and repository mapping
 
-- Accepts a public GitHub issue or pull-request URL, plain task text, a UTF-8 `--issue-file`, or task text from stdin.
+- Accepts a public GitHub issue or pull-request URL, plain task text, a UTF-8 or UTF-16 `--issue-file` (including common BOM-less Windows UTF-16 files), or task text from stdin.
 - Normalizes supported browser and GitHub API issue URLs, including `www`, query strings, and fragments, while rejecting credentials, lookalike hosts, ports, and unsafe encoded paths.
 - Scans the current checkout, another local path, a `file://` URL, or an isolated checkout of a public GitHub repository.
 - Maps `--diff <spec>`, `--base`/`--head`, or the current `--working-tree`; untracked changes remain opt-in with `--include-untracked`.
-- Reuses repository scans only when the repository root, commit, status, and binary diff are identical. `cache-hit` reports reuse and scan age, entries expire after seven days, and `FIXMAP_CACHE_DIR` moves the OS cache. Force a fresh scan with CLI `--no-cache`, MCP `noCache: true`, or Action `no-cache: true`.
+- Reuses raw repository scans only when the repository root, commit, status, and binary diff are identical. Task text, `--limit`, and exclusion rules are applied after that scan, so changing them can safely reuse the same cached files while still producing a newly ranked and filtered report; Compare scans the current plan, while Verify validates its supplied report against a fresh or exact-state repository map. `cache-hit` reports reuse and scan age, entries expire after seven days, and `FIXMAP_CACHE_DIR` moves the OS cache. Force a fresh scan with CLI `--no-cache`, MCP `noCache: true`, or Action `no-cache: true`.
 - Keeps the current `--issue-file`, `--compare`, `--report`, and `--output` artifacts out of repository ranking, change detection, and cache invalidation, so FixMap never recommends its own report as the fix site.
-- Detects npm, pnpm, Yarn, and Bun projects and reads the scripts declared by each workspace package.
+- Detects npm, pnpm, Yarn, and Bun projects and reads the scripts declared by each workspace package. When the root is silent it can infer an agreed nested lockfile, while conflicting root declarations produce a diagnostic instead of silently choosing.
 
 ### Plan and ranking
 
-- Ranks source, test, configuration, documentation, and other files from path terms, source content, identifiers, quoted fragments, file mentions, and real diff content.
+- Ranks source, test, configuration, documentation, and other files from path terms, source content, identifiers, quoted fragments (including smart quotes and guillemets), file mentions, and real diff content.
 - Recognizes JavaScript/TypeScript declaration tests, Go `_test.go`, Python `test_*.py` and `*_test.py`, common test directories, and framework single-file components.
-- Deprioritizes lockfiles, backups, bundled output, examples, and generated counterparts when maintained source exists.
-- Routes reachable test commands from real package scripts and pairs them with the nearest related test files.
+- Deprioritizes lockfiles, sync-client backups, bundled output, examples, and generated counterparts when maintained source exists, while keeping ordinary modules such as `deep-copy.ts` and tracked first-party `vendor/` source rankable.
+- Routes reachable test commands from real package scripts and pairs them with the nearest related test files. It warns when routed JavaScript, Python, Go, or Rust tests are skipped, ignored, conditional, or gated.
 - Reports six bounded risk areas: authentication, billing, automation, data, public API, and dependencies.
 - Explains task grounding, ranking shape, unresolved or partially matched identifiers, exclusions, scan limits, unread content, skipped submodules, empty diffs, and Git failures.
-- Supports `--limit`, repeatable `--exclude`, and ordered `.fixmapignore` patterns with negation. Root-leading patterns are repository-relative, pasted absolute paths inside the repository are normalized, and patterns that match nothing produce a warning.
+- Supports a strict decimal `--limit`, repeatable `--exclude`, and ordered `.fixmapignore` patterns with negation. Root-leading patterns are repository-relative, pasted absolute paths inside the repository are normalized, and patterns that match nothing produce a warning. Limits change only how many rows are shown, never confidence or ranking-shape analysis.
+
+### Exclusion pattern syntax
+
+`--exclude` and `.fixmapignore` use repository-relative gitignore-style patterns. `/docs/**` anchors at the repository root, `docs/**` matches the same root directory and nested occurrences, `!docs/keep.md` re-includes a path after an earlier exclusion, and trailing `/` targets a directory. `*`, `?`, and `**` are supported; brace groups such as `{src,test}` are literal text, not alternation. Pass repeated `--exclude` flags or put one pattern per `.fixmapignore` line so commas in literal names stay unambiguous.
+
 - Produces Markdown for people or versioned JSON for tools, writes to `--output`, and gives one grounded next action.
 
 ### Explain, Compare, Verify, Validate, and Doctor
 
 - **Explain** tells you whether a path ranked, fell below the cutoff, was excluded, resolves through a submodule, or was never scanned—and uses the same task and diff evidence as Plan.
 - **Compare** shows files that entered, left, moved, or changed confidence after the task was refined, plus changes in task grounding.
-- **Verify** compares a saved JSON plan with a diff or working tree and flags generated edits, unmapped changes, an untouched leading file, source changes without tests, newly reached risk areas, and plan/repository mismatches.
+- **Verify** compares a saved JSON plan with a diff or working tree and flags generated edits, unmapped changes, an untouched leading file, source changes without tests, newly reached risk areas, and plan/repository mismatches. It fails on errors by default; `--fail-on warning` and the Action's `fail-on: warning` turn advisory findings into an opt-in CI gate.
 - **Validate** checks any saved JSON report with the structural compatibility validator shared by Compare, Verify, the Action, and MCP.
 - **Doctor** prints the running version and executable path and diagnoses project, global, PATH, and npm-exec version shadows.
 - `FIXMAP_PROGRESS` controls remote clone/scan progress, and `FIXMAP_VERBOSE_USAGE` restores full usage text after argument errors.
@@ -113,7 +118,7 @@ Use `--working-tree` for staged and unstaged tracked edits, `--include-untracked
 
 - `fixmap setup` installs `/fixmap` discovery for Claude Code, Cursor, GitHub Copilot prompt files, and the open Agent Skills layout; the no-argument command lists every FixMap workflow before making changes.
 - The MCP server exposes `fixmap_plan`, `fixmap_explain`, `fixmap_compare`, `fixmap_verify`, and `fixmap_doctor` over local stdio and is published in the official MCP Registry.
-- The GitHub Action runs Plan or Verify on pull requests, writes a full job summary, and creates or updates one bounded FixMap comment instead of posting duplicates.
+- The GitHub Action runs Plan or Verify on pull requests, appends within the job summary's remaining 1 MiB budget, bounds its report output and comment, and creates or updates one FixMap comment instead of posting duplicates.
 - The Action accepts explicit task input or pull-request context, uses the same report validator as the CLI and MCP server, and fails clearly when a requested diff cannot be resolved.
 - The browser demo runs the real core Plan, Explain, Compare, and Verify logic against a sample repository without uploading the task.
 
@@ -182,12 +187,12 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - uses: aryamthecodebreaker/FixMap@v0.8.8
+      - uses: aryamthecodebreaker/FixMap@v0.8.9
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-The Action writes the complete report to the job summary and maintains one pull-request comment. Set `no-cache: true` when a workflow must bypass the exact-state scan cache. Its checked-in bundle and metadata are release-gated.
+The Action writes a bounded report to the job summary and maintains one pull-request comment. If GitHub's limits require truncation, the notice points to a local `--output` plus artifact upload for the complete report. Set `no-cache: true` when a workflow must bypass the exact-state scan cache, or `fail-on: warning` when advisory Verify findings must fail the job. Its checked-in bundle and metadata are release-gated.
 
 ## JSON compatibility
 
diff --git a/action.yml b/action.yml
index 7fa9ac9..93228f2 100644
--- a/action.yml
+++ b/action.yml
@@ -13,6 +13,12 @@ inputs:
       Verify mode only. Path to the JSON plan this change was made from, usually restored
       from an artifact saved by an earlier plan step.
     required: false
+  fail-on:
+    description: >-
+      Verify mode only. error (default) fails only on error findings; warning also fails
+      when verification raises advisory warnings such as no-test-changed.
+    required: false
+    default: error
   issue:
     description: >-
       Issue, prompt, or review context for FixMap. Accepts a public GitHub issue or pull
@@ -64,7 +70,7 @@ inputs:
     required: false
 outputs:
   report:
-    description: The complete FixMap report, or verification, in the selected format.
+    description: The bounded FixMap report, or verification, in the selected format.
   context-count:
     description: Number of context files returned. Plan mode only.
   test-route-count:
diff --git a/apps/web/app/_components/copy-command.tsx b/apps/web/app/_components/copy-command.tsx
index 78c791c..6ac0c3e 100644
--- a/apps/web/app/_components/copy-command.tsx
+++ b/apps/web/app/_components/copy-command.tsx
@@ -1,23 +1,37 @@
 "use client";
 
 import { Check, Copy } from "@phosphor-icons/react";
-import { useState } from "react";
+import { useRef, useState } from "react";
 
 export function CopyCommand({ command, label = "Copy command" }: { command: string; label?: string }) {
-  const [copied, setCopied] = useState(false);
+  const [state, setState] = useState<"idle" | "copied" | "manual">("idle");
+  const codeRef = useRef<HTMLElement>(null);
 
   async function copy() {
-    await navigator.clipboard.writeText(command);
-    setCopied(true);
-    window.setTimeout(() => setCopied(false), 1800);
+    try {
+      if (!navigator.clipboard?.writeText) throw new Error("Clipboard API unavailable");
+      await navigator.clipboard.writeText(command);
+      setState("copied");
+    } catch {
+      const code = codeRef.current;
+      if (code) {
+        const selection = window.getSelection();
+        const range = document.createRange();
+        range.selectNodeContents(code);
+        selection?.removeAllRanges();
+        selection?.addRange(range);
+      }
+      setState("manual");
+    }
+    window.setTimeout(() => setState("idle"), 2400);
   }
 
   return (
     <div className="copy-command">
-      <code>{command}</code>
+      <code ref={codeRef}>{command}</code>
       <button type="button" onClick={copy} aria-label={label}>
-        {copied ? <Check size={18} weight="bold" aria-hidden /> : <Copy size={18} aria-hidden />}
-        <span>{copied ? "Copied" : "Copy"}</span>
+        {state === "copied" ? <Check size={18} weight="bold" aria-hidden /> : <Copy size={18} aria-hidden />}
+        <span aria-live="polite">{state === "copied" ? "Copied" : state === "manual" ? "Press Ctrl+C" : "Copy"}</span>
       </button>
     </div>
   );
diff --git a/apps/web/app/_components/pixel-sink-surface.tsx b/apps/web/app/_components/pixel-sink-surface.tsx
index b50ebb9..0912cf7 100644
--- a/apps/web/app/_components/pixel-sink-surface.tsx
+++ b/apps/web/app/_components/pixel-sink-surface.tsx
@@ -176,7 +176,10 @@ export function PixelSinkSurface() {
 
     const onVisibility = () => {
       if (document.visibilityState === "visible") schedule();
-      else if (frame) cancelAnimationFrame(frame);
+      else if (frame) {
+        cancelAnimationFrame(frame);
+        frame = 0;
+      }
     };
 
     const observer = new ResizeObserver(resize);
@@ -187,7 +190,10 @@ export function PixelSinkSurface() {
     resize();
 
     return () => {
-      if (frame) cancelAnimationFrame(frame);
+      if (frame) {
+        cancelAnimationFrame(frame);
+        frame = 0;
+      }
       observer.disconnect();
       host.removeEventListener("pointermove", onPointerMove);
       host.removeEventListener("pointerleave", onPointerLeave);
diff --git a/apps/web/app/_lib/site-data.ts b/apps/web/app/_lib/site-data.ts
index a5cabec..0b90268 100644
--- a/apps/web/app/_lib/site-data.ts
+++ b/apps/web/app/_lib/site-data.ts
@@ -7,9 +7,10 @@ import adversarial from "../../../../benchmarks/adversarial/results.json";
 import cli from "../../../../packages/cli/package.json";
 
 type EvaluationCase = {
-  top1: boolean;
-  top3: boolean;
+  top1Hit: boolean;
+  top3Hit: boolean;
   top5Hit: boolean;
+  top5Paths: string[];
 };
 
 const hits = (results: EvaluationCase[], key: keyof EvaluationCase) =>
@@ -17,6 +18,12 @@ const hits = (results: EvaluationCase[], key: keyof EvaluationCase) =>
 
 const heldoutResults = heldout.results as EvaluationCase[];
 const regressionResults = regression.results as EvaluationCase[];
+const confidenceCalibration = (["high", "medium", "low"] as const).map((confidence) => {
+  const bands = [heldout, regression].flatMap((suite) => suite.calibration.filter((entry) => entry.confidence === confidence));
+  const cases = bands.reduce((total, band) => total + band.cases, 0);
+  const correct = bands.reduce((total, band) => total + band.top1Correct, 0);
+  return { confidence, cases, correct, accuracy: cases === 0 ? null : correct / cases };
+});
 
 export const repoUrl = "https://github.com/aryamthecodebreaker/FixMap";
 export const npmUrl = "https://www.npmjs.com/package/@aryam/fixmap";
@@ -59,10 +66,11 @@ const baselineOf = (suite: BaselineSuite) => ({
 export const siteStats = {
   version: cli.version,
   medianSeconds: (savings.performance.medianScanAndRankMs / 1000).toFixed(2),
+  confidenceCalibration,
   heldout: {
     cases: heldout.cases,
-    top1: hits(heldoutResults, "top1"),
-    top3: hits(heldoutResults, "top3"),
+    top1: hits(heldoutResults, "top1Hit"),
+    top3: hits(heldoutResults, "top3Hit"),
     top5: hits(heldoutResults, "top5Hit"),
     intervals95: heldout.intervals95,
     cohorts: cohortOf(heldout),
@@ -70,8 +78,8 @@ export const siteStats = {
   },
   regression: {
     cases: regression.cases,
-    top1: hits(regressionResults, "top1"),
-    top3: hits(regressionResults, "top3"),
+    top1: hits(regressionResults, "top1Hit"),
+    top3: hits(regressionResults, "top3Hit"),
     top5: hits(regressionResults, "top5Hit"),
     intervals95: regression.intervals95,
     cohorts: cohortOf(regression),
diff --git a/apps/web/app/changelog/page.tsx b/apps/web/app/changelog/page.tsx
index 08725db..483d984 100644
--- a/apps/web/app/changelog/page.tsx
+++ b/apps/web/app/changelog/page.tsx
@@ -43,10 +43,47 @@ type Release = {
 };
 
 const releases: Release[] = [
+  {
+    version: "0.8.9",
+    date: "August 11, 2026",
+    label: "Latest release",
+    summary: "A complete reliability sweep across ranking, verification, agent discovery, workflows, evidence, and the public product surface.",
+    groups: [
+      {
+        label: "Added",
+        items: [
+          "Install /fixmap for supported coding agents and open the complete feature catalog without supplying a task.",
+          "Validate saved reports from the CLI and opt into warning-level Verify failures in the CLI or GitHub Action.",
+          "Control fresh scans consistently across CLI, MCP, and Action interfaces with visible cache diagnostics."
+        ]
+      },
+      {
+        label: "Fixed",
+        items: [
+          "Ranking, grounding, definitions, file mentions, diffs, Unicode text, workspace routing, exclusions, caching, and cross-language test detection now cover the full reviewed issue set.",
+          "Explain, Compare, Verify, Doctor, MCP, remote repositories, and the Action reject malformed or ambiguous state with actionable diagnostics.",
+          "GitHub output limits, permissions, API failures, credentials, temporary repositories, and generated metadata are handled defensively."
+        ]
+      },
+      {
+        label: "Improved",
+        items: [
+          "The website now uses a calmer editorial design, clearer product navigation, reliable copy feedback, visibility-safe motion, and complete metadata.",
+          "README, npm documentation, slash-command setup, release notes, and the post-release checklist cover every supported workflow."
+        ]
+      },
+      {
+        label: "Evidence",
+        items: [
+          "The release ledger maps 126 GitHub issues plus the complete attached 30-finding review to fixes and verification.",
+          "External, held-out, adversarial, baseline, savings, package, generated-output, and 1,000-file scan gates are recorded and reproducible."
+        ]
+      }
+    ]
+  },
   {
     version: "0.8.8",
     date: "August 8, 2026",
-    label: "Latest release",
     summary: "Forty-six issues closed across scan correctness, workflow honesty, the Action, documentation, accessibility, and release proof.",
     groups: [
       {
diff --git a/apps/web/app/demo.tsx b/apps/web/app/demo.tsx
index c67d540..f587dcd 100644
--- a/apps/web/app/demo.tsx
+++ b/apps/web/app/demo.tsx
@@ -1,7 +1,8 @@
 "use client";
 
-import { useEffect, useMemo, useRef, useState } from "react";
-import { buildPathExcluder, buildReportFromRepo, compareReports, explainFile, verifyPlan } from "@aryam/fixmap-core/browser";
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { buildPathExcluder, buildReportFromRepo, compareReports, explainFile, quoteCliValue, verifyPlan } from "@aryam/fixmap-core/browser";
+import type { CliShell } from "@aryam/fixmap-core/browser";
 import { sampleRepo, sampleRepoWithChanges, samplePaths } from "./sample-repo";
 
 type Stage = "plan" | "explain" | "compare" | "verify";
@@ -41,6 +42,18 @@ const scenarios = [
 
 const explainTargets = samplePaths;
 
+function subscribeToShell(): () => void {
+  return () => undefined;
+}
+
+function browserShell(): CliShell {
+  return /Windows/i.test(navigator.userAgent) ? "powershell" : "posix";
+}
+
+function serverShell(): CliShell {
+  return "posix";
+}
+
 export function Demo() {
   const [task, setTask] = useState(presets[0]!.label);
   const [stage, setStage] = useState<Stage>("plan");
@@ -99,10 +112,11 @@ export function Demo() {
     `${limit === 8 ? "" : ` --limit ${limit}`}` +
     `${excludeBuild ? ' --exclude "dist/**"' : ""}` +
     `${workingTree ? " --working-tree" : ""}`;
-  const quotedTask = quoteCliValue(task);
+  const shell = useSyncExternalStore(subscribeToShell, browserShell, serverShell);
+  const quotedTask = quoteCliValue(task, shell);
   const command = {
     plan: `fixmap plan --issue ${quotedTask}${scanFlags} --format json --output plan.json`,
-    explain: `fixmap plan --issue ${quotedTask} --explain ${quoteCliValue(explainTarget)}${scanFlags}`,
+    explain: `fixmap plan --issue ${quotedTask} --explain ${quoteCliValue(explainTarget, shell)}${scanFlags}`,
     compare: `fixmap plan --issue ${quotedTask} --compare plan.json${scanFlags}`,
     verify: `fixmap verify --report plan.json ${workingTree ? "--working-tree" : "--diff main...HEAD"}`
   }[stage];
@@ -403,7 +417,3 @@ function VerifyPanel({
     </>
   );
 }
-
-function quoteCliValue(value: string): string {
-  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
-}
diff --git a/apps/web/app/docs/page.tsx b/apps/web/app/docs/page.tsx
index 3a5d589..5e88d15 100644
--- a/apps/web/app/docs/page.tsx
+++ b/apps/web/app/docs/page.tsx
@@ -58,7 +58,7 @@ export default function DocsPage() {
 
           <section id="focus" className="doc-section"><p className="eyebrow">Focus</p><h2>Narrow the map to what matters.</h2><p>Demo pages, marketing copy, and documentation often contain every symptom word a product documents, so they compete with the implementation. FixMap knows about conventions like <code>examples/</code>; it cannot know your repository&rsquo;s own layout.</p><CopyCommand command={'fixmap plan --issue "reset links fail" --exclude apps/web --limit 3'} /><p>Patterns can also live in a <code>.fixmapignore</code> file at the repository root, one per line. The two combine, and <code>--explain</code> reports an excluded file as excluded, naming the pattern that matched.</p><h3>Map what you are editing now</h3><CopyCommand command={'fixmap plan --working-tree --issue "reset flow"'} /><p>That means staged and unstaged tracked changes against <code>HEAD</code>. Untracked files stay out of the <em>change set</em> unless you add <code>--include-untracked</code>, so scratch metadata is not reported as an edit. They remain ranking candidates either way — a file an agent just wrote is usually the most relevant thing in the repository.</p><h3>Measure a better task</h3><p>Refine the wording, re-plan, and see whether the real file moved up:</p><CopyCommand command={'fixmap plan --issue "TOKEN_TTL_MINUTES is ignored" --compare before.json'} /></section>
 
-          <section id="verify" className="doc-section"><p className="eyebrow">Verify</p><h2>Compare the plan with the change.</h2><p>Save a JSON plan before editing, then compare it with the real diff afterwards.</p><CopyCommand command={'fixmap plan --issue "reset links fail" --format json --output plan.json'} /><CopyCommand command={commands.verify} /><div className="doc-note"><WarningCircle size={22} aria-hidden /><p>Verify does not run tests or judge correctness. Most findings are advisory because the plan can be wrong and the change can still be right.</p></div></section>
+          <section id="verify" className="doc-section"><p className="eyebrow">Verify</p><h2>Compare the plan with the change.</h2><p>Save a JSON plan before editing, then compare it with the real diff afterwards.</p><CopyCommand command={'fixmap plan --issue "reset links fail" --format json --output plan.json'} /><CopyCommand command={commands.verify} /><CopyCommand command={'fixmap verify --report plan.json --working-tree --fail-on warning'} /><div className="doc-note"><WarningCircle size={22} aria-hidden /><p>Verify does not run tests or judge correctness. Errors fail by default. Add <code>--fail-on warning</code> when advisory findings, such as a source change without a test change, must also block CI.</p></div></section>
 
           <section id="output" className="doc-section"><p className="eyebrow">Output</p><h2>Readable by people and tools.</h2><p>Markdown is the default handoff. Add <code>--format json</code> for structured output and <code>--output &lt;path&gt;</code> to save it. The current issue, comparison, verification, and output files are kept out of ranking, change detection, and cache state, so a saved FixMap report cannot recommend itself.</p><p>New JSON plans include <code>reportVersion: 1</code>. Within a report version, fields may be added but existing fields will not be removed or change type; consumers should ignore unknown fields. A breaking output change requires a new report version. Compare and Verify still accept legacy plans without a marker, while rejecting marker values they do not understand.</p><div className="definition-list"><div><strong>Context files</strong><p>Ranked paths, scores, confidence labels, and evidence.</p></div><div><strong>Test routes</strong><p>Workspace-aware commands and reachable related tests.</p></div><div><strong>Risks</strong><p>Sensitive areas inferred from paths, symbols, and changes.</p></div><div><strong>Diagnostics</strong><p>Vague tasks, unresolved identifiers, scan limits, and other uncertainty.</p></div></div></section>
 
diff --git a/apps/web/app/evidence/page.tsx b/apps/web/app/evidence/page.tsx
index 2e9234e..1de4366 100644
--- a/apps/web/app/evidence/page.tsx
+++ b/apps/web/app/evidence/page.tsx
@@ -45,6 +45,19 @@ export default function EvidencePage() {
         <div className="button-row"><a className="button primary" href={`${repoUrl}/tree/main/benchmarks`}>Open benchmark data <ArrowRight size={18} weight="bold" aria-hidden /></a></div>
       </section>
 
+      <section className="section page-shell">
+        <div className="section-heading split-heading">
+          <div><p className="eyebrow">Confidence calibration</p><h2>Labels are evidence bands, not probabilities.</h2></div>
+          <p>Across the held-out and external suites, high confidence is not more accurate than medium in this small sample. The counts are published so readers can see that limitation instead of treating a label as a calibrated chance of correctness.</p>
+        </div>
+        <div className="results-table" role="table" aria-label="Top-result accuracy by FixMap confidence label">
+          <div className="results-row results-head" role="row"><span role="columnheader">Top label</span><span role="columnheader">Cases</span><span role="columnheader">Correct</span><span role="columnheader">Accuracy</span></div>
+          {siteStats.confidenceCalibration.map((band) => (
+            <div className="results-row" role="row" key={band.confidence}><span role="cell">{band.confidence}</span><span role="cell">{band.cases}</span><span role="cell">{band.correct}</span><span role="cell">{rate(band.accuracy)}</span></div>
+          ))}
+        </div>
+      </section>
+
       <section className="section page-shell">
         <div className="section-heading split-heading">
           <div><p className="eyebrow">Adversarial gate</p><h2>{siteStats.adversarial.passed}/{siteStats.adversarial.cases} cases pass.</h2></div>
@@ -122,8 +135,8 @@ export default function EvidencePage() {
               <div className="results-row" role="row" key={result.slug}>
                 <span role="cell"><a href={`https://github.com/${result.slug}/issues/${result.issue}`}>{result.slug} #{result.issue}</a></span>
                 <code role="cell">{result.expected[0]}</code>
-                <code role="cell">{result.top5[0]}</code>
-                <span role="cell" className={result.top3 ? "result-hit" : "result-miss"}>{result.top3 ? <Check size={18} weight="bold" aria-hidden /> : <Minus size={18} weight="bold" aria-hidden />}{result.top3 ? "Hit" : "Miss"}</span>
+                <code role="cell">{result.top5Paths[0]}</code>
+                <span role="cell" className={result.top3Hit ? "result-hit" : "result-miss"}>{result.top3Hit ? <Check size={18} weight="bold" aria-hidden /> : <Minus size={18} weight="bold" aria-hidden />}{result.top3Hit ? "Hit" : "Miss"}</span>
               </div>
             ))}
           </div>
diff --git a/apps/web/app/globals.css b/apps/web/app/globals.css
index ff49baa..f49f1d0 100644
--- a/apps/web/app/globals.css
+++ b/apps/web/app/globals.css
@@ -141,8 +141,8 @@ h3 { margin-bottom: 10px; font-size: 21px; line-height: 1.25; letter-spacing: -.
 .before-after strong { display: block; margin-bottom: 14px; font-size: 23px; line-height: 1.25; }
 .before-after p { color: #b7c2cc; }
 .path-list { border-top: 1px solid var(--line-strong); }
-.path-list > a { min-height: 128px; display: grid; grid-template-columns: 230px 1fr 28px; align-items: center; gap: 26px; border-bottom: 1px solid var(--line); text-decoration: none; transition: color .18s ease, padding .18s ease; }
-.path-list > a:hover { padding-inline: 16px; color: var(--green); }
+.path-list > a { min-height: 128px; display: grid; grid-template-columns: 230px 1fr 28px; align-items: center; gap: 26px; border-bottom: 1px solid var(--line); text-decoration: none; transition: color .18s ease, transform .18s ease; }
+.path-list > a:hover { color: var(--green); transform: translateX(8px); }
 .path-list span { display: flex; align-items: center; gap: 14px; font-size: 22px; }
 .path-list p { margin: 0; color: var(--ink-soft); }
 .evidence-teaser { display: grid; grid-template-columns: 1.2fr .8fr; gap: 90px; align-items: center; border-top: 1px solid var(--line); }
@@ -594,8 +594,8 @@ h3 { margin-bottom: 10px; font-size: 21px; line-height: 1.25; letter-spacing: -.
 .premium-section-intro h2 { font-size: clamp(50px, 5vw, 76px); }
 .premium-section-intro > p:last-child { max-width: 430px; color: var(--ink-soft); font-size: 18px; }
 .premium-answer-list { border-top: 1px solid var(--line-strong); }
-.premium-answer-list > a { min-height: 180px; padding: 34px 10px 34px 0; display: grid; grid-template-columns: 58px 1fr 30px; gap: 22px; align-items: start; border-bottom: 1px solid var(--line); text-decoration: none; transition: padding .22s ease, background .22s ease; }
-.premium-answer-list > a:hover { padding-left: 18px; background: rgba(255,253,248,.46); }
+.premium-answer-list > a { min-height: 180px; padding: 34px 10px 34px 0; display: grid; grid-template-columns: 58px 1fr 30px; gap: 22px; align-items: start; border-bottom: 1px solid var(--line); text-decoration: none; transition: background .22s ease, transform .22s ease; }
+.premium-answer-list > a:hover { background: rgba(255,253,248,.46); transform: translateX(8px); }
 .premium-answer-list > a > span { padding-top: 6px; color: var(--green); font: 600 12px var(--font-mono), monospace; }
 .premium-answer-list h3 { font-size: 26px; }
 .premium-answer-list p { max-width: 610px; margin: 0; color: var(--ink-soft); font-size: 16px; }
@@ -742,8 +742,8 @@ h3 { margin-bottom: 10px; font-size: 21px; line-height: 1.25; letter-spacing: -.
 .pro-section-heading h2 { font-size: clamp(38px, 4vw, 54px); }
 .pro-section-heading > p:last-child { color: var(--ink-soft); font-size: 17px; }
 .pro-workflow-list { border-top: 1px solid var(--line-strong); }
-.pro-workflow-list > a { min-height: 112px; padding: 23px 10px; display: grid; grid-template-columns: 42px 100px 1fr 24px; align-items: center; gap: 14px; border-bottom: 1px solid var(--line); text-decoration: none; transition: background .18s ease, padding .18s ease; }
-.pro-workflow-list > a:hover { padding-inline: 18px; background: var(--paper-light); }
+.pro-workflow-list > a { min-height: 112px; padding: 23px 10px; display: grid; grid-template-columns: 42px 100px 1fr 24px; align-items: center; gap: 14px; border-bottom: 1px solid var(--line); text-decoration: none; transition: background .18s ease, transform .18s ease; }
+.pro-workflow-list > a:hover { background: var(--paper-light); transform: translateX(8px); }
 .pro-workflow-list > a > span { color: var(--green); font: 600 11px var(--font-mono), monospace; }
 .pro-workflow-list strong { font-size: 18px; }
 .pro-workflow-list p { margin: 0; color: var(--ink-soft); font-size: 14px; }
diff --git a/apps/web/app/sitemap.ts b/apps/web/app/sitemap.ts
index 4a93a4b..5505ac3 100644
--- a/apps/web/app/sitemap.ts
+++ b/apps/web/app/sitemap.ts
@@ -3,9 +3,17 @@ import type { MetadataRoute } from "next";
 const base = "https://usefixmap.vercel.app";
 
 export default function sitemap(): MetadataRoute.Sitemap {
+  const lastModifiedByPath: Record<string, Date> = {
+    "": new Date("2026-08-09T00:00:00.000Z"),
+    "/product": new Date("2026-08-09T00:00:00.000Z"),
+    "/demo": new Date("2026-08-09T00:00:00.000Z"),
+    "/evidence": new Date("2026-08-09T00:00:00.000Z"),
+    "/changelog": new Date("2026-08-09T00:00:00.000Z"),
+    "/get-started": new Date("2026-08-09T00:00:00.000Z"),
+    "/docs": new Date("2026-08-09T00:00:00.000Z")
+  };
   return ["", "/product", "/demo", "/evidence", "/changelog", "/get-started", "/docs"].map((path) => ({
     url: `${base}${path}`,
-    changeFrequency: path === "" ? "weekly" : "monthly",
-    priority: path === "" ? 1 : path === "/demo" || path === "/get-started" ? 0.9 : 0.8
+    lastModified: lastModifiedByPath[path]
   }));
 }
diff --git a/apps/web/package.json b/apps/web/package.json
index eab520a..5bedc7d 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -11,11 +11,11 @@
   "scripts": {
     "build": "next build",
     "dev": "next dev",
-    "lint": "eslint .",
+    "lint": "eslint . --max-warnings=0",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@aryam/fixmap-core": "0.8.8",
+    "@aryam/fixmap-core": "0.8.9",
     "@phosphor-icons/react": "^2.1.10",
     "next": "16.2.11",
     "react": "19.2.7",
diff --git a/benchmarks/adversarial/results.json b/benchmarks/adversarial/results.json
index cefb480..073b1b3 100644
--- a/benchmarks/adversarial/results.json
+++ b/benchmarks/adversarial/results.json
@@ -12,7 +12,7 @@
       "grounding": "descriptive",
       "diagnostics": [
         "submodules-skipped",
-        "content-unread",
+        "content-too-large",
         "identifier-unverified",
         "flat-ranking"
       ],
@@ -30,8 +30,9 @@
       "topConfidence": "low",
       "grounding": "descriptive",
       "diagnostics": [
-        "content-unread",
-        "identifier-unverified"
+        "content-too-large",
+        "identifier-unverified",
+        "flat-ranking"
       ],
       "contextFileCount": 8,
       "overconfident": false,
@@ -47,10 +48,10 @@
       "topConfidence": "low",
       "grounding": "descriptive",
       "diagnostics": [
-        "content-unread",
+        "content-too-large",
         "identifier-unverified"
       ],
-      "contextFileCount": 5,
+      "contextFileCount": 7,
       "overconfident": false,
       "groundingOk": true,
       "diagnosticOk": true,
@@ -61,13 +62,15 @@
       "kind": "vague-task",
       "slug": "vitest-dev/vitest",
       "maxConfidence": "low",
-      "topConfidence": null,
+      "topConfidence": "low",
       "grounding": "vague",
       "diagnostics": [
-        "content-unread",
-        "vague-task"
+        "content-too-large",
+        "gated-test-skipped",
+        "vague-task",
+        "flat-ranking"
       ],
-      "contextFileCount": 0,
+      "contextFileCount": 8,
       "overconfident": false,
       "groundingOk": true,
       "diagnosticOk": true,
@@ -81,7 +84,8 @@
       "topConfidence": null,
       "grounding": "vague",
       "diagnostics": [
-        "vague-task"
+        "vague-task",
+        "no-context-match"
       ],
       "contextFileCount": 0,
       "overconfident": false,
@@ -97,7 +101,7 @@
       "topConfidence": "medium",
       "grounding": "descriptive",
       "diagnostics": [],
-      "contextFileCount": 6,
+      "contextFileCount": 7,
       "overconfident": false,
       "groundingOk": true,
       "diagnosticOk": true,
@@ -110,8 +114,10 @@
       "maxConfidence": "medium",
       "topConfidence": "medium",
       "grounding": "descriptive",
-      "diagnostics": [],
-      "contextFileCount": 6,
+      "diagnostics": [
+        "flat-ranking"
+      ],
+      "contextFileCount": 8,
       "overconfident": false,
       "groundingOk": true,
       "diagnosticOk": true,
@@ -126,9 +132,9 @@
       "grounding": "descriptive",
       "diagnostics": [
         "submodules-skipped",
-        "content-unread",
-        "content-unread",
-        "flat-ranking"
+        "content-not-utf8",
+        "content-too-large",
+        "import-graph-truncated"
       ],
       "contextFileCount": 8,
       "overconfident": false,
diff --git a/benchmarks/external/baseline-results.json b/benchmarks/external/baseline-results.json
index 20ab2c6..8f48123 100644
--- a/benchmarks/external/baseline-results.json
+++ b/benchmarks/external/baseline-results.json
@@ -593,52 +593,52 @@
       "all": {
         "cases": 16,
         "top1HitRate": 0.688,
-        "top3HitRate": 1,
-        "top5HitRate": 1,
+        "top3HitRate": 0.938,
+        "top5HitRate": 0.938,
         "intervals95": {
           "top1": [
             0.444,
             0.858
           ],
           "top3": [
-            0.806,
-            1
+            0.717,
+            0.989
           ],
           "top5": [
-            0.806,
-            1
+            0.717,
+            0.989
           ]
         }
       },
       "unmentioned": {
         "cases": 13,
-        "top1HitRate": 0.692,
-        "top3HitRate": 1,
-        "top5HitRate": 1,
+        "top1HitRate": 0.615,
+        "top3HitRate": 0.923,
+        "top5HitRate": 0.923,
         "intervals95": {
           "top1": [
-            0.424,
-            0.873
+            0.355,
+            0.823
           ],
           "top3": [
-            0.772,
-            1
+            0.667,
+            0.986
           ],
           "top5": [
-            0.772,
-            1
+            0.667,
+            0.986
           ]
         }
       },
       "mentioned": {
         "cases": 3,
-        "top1HitRate": 0.667,
+        "top1HitRate": 1,
         "top3HitRate": 1,
         "top5HitRate": 1,
         "intervals95": {
           "top1": [
-            0.208,
-            0.939
+            0.438,
+            1
           ],
           "top3": [
             0.438,
@@ -656,124 +656,124 @@
     "all": {
       "path-extraction:raw": {
         "top1": {
-          "aWins": 9,
-          "bWins": 1,
-          "discordant": 10,
-          "pValue": 0.0215
+          "aWins": 8,
+          "bWins": 0,
+          "discordant": 8,
+          "pValue": 0.0078
         },
         "top3": {
-          "aWins": 13,
+          "aWins": 12,
           "bWins": 0,
-          "discordant": 13,
-          "pValue": 0.0002
+          "discordant": 12,
+          "pValue": 0.0005
         },
         "top5": {
-          "aWins": 13,
+          "aWins": 12,
           "bWins": 0,
-          "discordant": 13,
-          "pValue": 0.0002
+          "discordant": 12,
+          "pValue": 0.0005
         }
       },
       "lexical-literal:code": {
         "top1": {
-          "aWins": 6,
-          "bWins": 0,
-          "discordant": 6,
-          "pValue": 0.0313
+          "aWins": 8,
+          "bWins": 2,
+          "discordant": 10,
+          "pValue": 0.1094
         },
         "top3": {
           "aWins": 11,
-          "bWins": 0,
-          "discordant": 11,
-          "pValue": 0.001
+          "bWins": 1,
+          "discordant": 12,
+          "pValue": 0.0063
         },
         "top5": {
           "aWins": 11,
-          "bWins": 0,
-          "discordant": 11,
-          "pValue": 0.001
+          "bWins": 1,
+          "discordant": 12,
+          "pValue": 0.0063
         }
       },
       "bm25:code": {
         "top1": {
-          "aWins": 5,
-          "bWins": 0,
-          "discordant": 5,
-          "pValue": 0.0625
+          "aWins": 7,
+          "bWins": 2,
+          "discordant": 9,
+          "pValue": 0.1797
         },
         "top3": {
           "aWins": 7,
-          "bWins": 0,
-          "discordant": 7,
-          "pValue": 0.0156
+          "bWins": 1,
+          "discordant": 8,
+          "pValue": 0.0703
         },
         "top5": {
           "aWins": 7,
-          "bWins": 0,
-          "discordant": 7,
-          "pValue": 0.0156
+          "bWins": 1,
+          "discordant": 8,
+          "pValue": 0.0703
         }
       }
     },
     "unmentioned": {
       "path-extraction:raw": {
         "top1": {
-          "aWins": 9,
+          "aWins": 8,
           "bWins": 0,
-          "discordant": 9,
-          "pValue": 0.0039
+          "discordant": 8,
+          "pValue": 0.0078
         },
         "top3": {
-          "aWins": 13,
+          "aWins": 12,
           "bWins": 0,
-          "discordant": 13,
-          "pValue": 0.0002
+          "discordant": 12,
+          "pValue": 0.0005
         },
         "top5": {
-          "aWins": 13,
+          "aWins": 12,
           "bWins": 0,
-          "discordant": 13,
-          "pValue": 0.0002
+          "discordant": 12,
+          "pValue": 0.0005
         }
       },
       "lexical-literal:code": {
         "top1": {
-          "aWins": 5,
-          "bWins": 0,
-          "discordant": 5,
-          "pValue": 0.0625
+          "aWins": 6,
+          "bWins": 2,
+          "discordant": 8,
+          "pValue": 0.2891
         },
         "top3": {
           "aWins": 9,
-          "bWins": 0,
-          "discordant": 9,
-          "pValue": 0.0039
+          "bWins": 1,
+          "discordant": 10,
+          "pValue": 0.0215
         },
         "top5": {
           "aWins": 9,
-          "bWins": 0,
-          "discordant": 9,
-          "pValue": 0.0039
+          "bWins": 1,
+          "discordant": 10,
+          "pValue": 0.0215
         }
       },
       "bm25:code": {
         "top1": {
-          "aWins": 4,
-          "bWins": 0,
-          "discordant": 4,
-          "pValue": 0.125
+          "aWins": 5,
+          "bWins": 2,
+          "discordant": 7,
+          "pValue": 0.4531
         },
         "top3": {
           "aWins": 5,
-          "bWins": 0,
-          "discordant": 5,
-          "pValue": 0.0625
+          "bWins": 1,
+          "discordant": 6,
+          "pValue": 0.2188
         },
         "top5": {
           "aWins": 5,
-          "bWins": 0,
-          "discordant": 5,
-          "pValue": 0.0625
+          "bWins": 1,
+          "discordant": 6,
+          "pValue": 0.2188
         }
       }
     }
@@ -789,111 +789,111 @@
       "mentionTier": "full-path",
       "arms": {
         "path-extraction:raw": {
-          "top5": [
+          "top5Paths": [
             "lib/request.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "path-extraction:source": {
-          "top5": [
+          "top5Paths": [
             "lib/request.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "path-extraction:code": {
-          "top5": [
+          "top5Paths": [
             "lib/request.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "lib/request.js",
             "lib/response.js",
             "test/res.send.js",
             "lib/application.js",
             "test/app.router.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "lib/request.js",
             "lib/response.js",
             "lib/application.js",
             "Readme.md",
             "examples/auth/index.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "lib/request.js",
             "lib/response.js",
             "lib/application.js",
             "examples/auth/index.js",
             "examples/web-service/index.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "lib/request.js",
             "test/req.fresh.js",
             "test/res.send.js",
             "test/req.stale.js",
             "lib/response.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "lib/request.js",
             "lib/response.js",
             "lib/application.js",
             "lib/express.js",
             "examples/mvc/index.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "lib/request.js",
             "lib/response.js",
             "lib/application.js",
             "lib/express.js",
             "examples/search/public/client.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "lib/request.js",
             "lib/response.js",
-            "package.json",
             "examples/auth/index.js",
-            "examples/route-middleware/index.js"
+            "examples/route-middleware/index.js",
+            "examples/web-service/index.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -908,105 +908,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "tests/unit/prototypePollution.test.js",
             "lib/adapters/http.js",
             "tests/unit/core/AxiosError.test.js",
             "docs/pages/advanced/request-config.md",
             "tests/unit/adapters/fetch.test.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "lib/adapters/http.js",
             "docs/pages/advanced/request-config.md",
             "MIGRATION_GUIDE.md",
             "AGENTS.md",
             "docs/pages/advanced/api-reference.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "lib/adapters/http.js",
             "index.d.cts",
             "index.d.ts",
             "lib/utils.js",
             "lib/adapters/xhr.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "MIGRATION_GUIDE.md",
             "docs/pages/getting-started/first-steps.md",
             "tests/unit/toFormData.test.js",
             "docs/pages/advanced/create-an-instance.md",
             "docs/pages/advanced/testing.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "MIGRATION_GUIDE.md",
             "docs/pages/advanced/testing.md",
             "docs/pages/getting-started/first-steps.md",
             "docs/zh/pages/advanced/testing.md",
             "docs/pages/advanced/x-www-form-urlencoded-format.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "lib/core/AxiosError.js",
             "lib/core/InterceptorManager.js",
             "gulpfile.js",
             "lib/adapters/xhr.js",
             "index.d.cts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "lib/core/AxiosError.js",
             "lib/adapters/http.js",
             "lib/helpers/HttpStatusCode.js",
-            "index.d.cts",
-            "index.d.ts"
+            "lib/core/Axios.js",
+            "lib/core/AxiosHeaders.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1021,105 +1021,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "README.md",
             "src/node.js",
             "src/common.js",
             "src/browser.js",
             ".github/PULL_REQUEST_TEMPLATE.md"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "README.md",
             "src/node.js",
             "src/common.js",
             "src/browser.js",
             ".github/PULL_REQUEST_TEMPLATE.md"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "src/node.js",
             "src/common.js",
             "src/browser.js",
             "test.js",
             "karma.conf.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "src/node.js",
             "README.md",
             "src/common.js",
             "src/browser.js",
             ".github/PULL_REQUEST_TEMPLATE.md"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "src/node.js",
             "README.md",
             "src/common.js",
             "src/browser.js",
             ".github/PULL_REQUEST_TEMPLATE.md"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "src/node.js",
             "src/browser.js",
             "src/common.js",
             "karma.conf.js",
             "test.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
-            "src/node.js",
-            "src/browser.js",
+          "top5Paths": [
             "src/common.js",
             "test.js",
-            "karma.conf.js"
+            "src/node.js",
+            "README.md",
+            "src/browser.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1134,105 +1134,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "readme.md",
             "source/core/Ky.ts",
             "source/types/options.ts",
             "source/types/hooks.ts",
             "test/main.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "readme.md",
             "source/core/Ky.ts",
             "source/types/options.ts",
             "source/types/hooks.ts",
             "source/core/constants.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "source/core/Ky.ts",
             "source/types/options.ts",
             "source/types/hooks.ts",
             "source/core/constants.ts",
             "source/utils/merge.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "readme.md",
             "source/core/Ky.ts",
             "source/core/constants.ts",
             "source/types/options.ts",
             "test/http-error.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "readme.md",
             "source/core/Ky.ts",
             "source/core/constants.ts",
             "source/types/options.ts",
             "source/errors/HTTPError.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "source/core/Ky.ts",
             "source/core/constants.ts",
             "source/types/options.ts",
             "source/errors/HTTPError.ts",
             "source/utils/merge.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "source/core/Ky.ts",
             "source/errors/HTTPError.ts",
             "source/types/hooks.ts",
             "source/types/options.ts",
-            "source/errors/SchemaValidationError.ts"
+            "source/core/constants.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1247,105 +1247,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "packages/docs-v3/README_ZH.md",
             "packages/zod/src/v4/mini/schemas.ts",
             "packages/zod/src/v4/mini/tests/index.test.ts",
             "packages/zod/src/v4/classic/from-json-schema.ts",
             "packages/docs-v3/ERROR_HANDLING.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "packages/docs-v3/README_ZH.md",
             "packages/zod/src/v4/mini/schemas.ts",
             "packages/zod/src/v4/classic/from-json-schema.ts",
             "packages/docs-v3/ERROR_HANDLING.md",
             "packages/zod/src/v4/core/checks.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "packages/zod/src/v4/mini/schemas.ts",
             "packages/zod/src/v4/classic/from-json-schema.ts",
             "packages/zod/src/v4/core/checks.ts",
             "packages/zod/src/v4/core/json-schema-processors.ts",
             "packages/zod/src/v4/core/api.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "packages/zod/src/v4/mini/tests/string.test.ts",
             "packages/zod/src/v4/classic/tests/detached-methods.test.ts",
             "packages/zod/src/v4/classic/tests/refine.test.ts",
             "packages/zod/src/v4/classic/tests/tuple.test.ts",
             "packages/zod/src/v4/mini/tests/codec.test.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "packages/docs-v3/README_ZH.md",
             "packages/zod/README.md",
-            "wiki/optionality.md",
             "packages/resolution/src/index.mts",
-            "packages/resolution/src/index.cts"
+            "packages/resolution/src/index.cts",
+            "packages/resolution/src/index.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "packages/resolution/src/index.mts",
             "packages/resolution/src/index.cts",
             "packages/resolution/src/index.ts",
             "packages/zod/src/v4/core/to-json-schema.ts",
             "packages/docs/components/ecosystem.tsx"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "fixmap": {
-          "top5": [
-            "packages/zod/src/v4/core/regexes.ts",
-            "packages/zod/src/v4/classic/from-json-schema.ts",
+          "top5Paths": [
             "packages/zod/src/v4/core/json-schema-processors.ts",
+            "packages/zod/src/v4/core/regexes.ts",
             "packages/zod/src/v4/mini/schemas.ts",
-            "packages/zod/src/v4/core/parse.ts"
+            "packages/zod/src/v4/classic/from-json-schema.ts",
+            "packages/zod/src/v4/core/checks.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1361,105 +1361,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "docs/transports.md",
             "docs/api.md",
             "pino.d.ts",
             "docs/help.md",
             "test/transport/core.test.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "docs/transports.md",
             "docs/api.md",
             "pino.d.ts",
             "docs/help.md",
             "pino.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "pino.d.ts",
             "pino.js",
             "lib/tools.js",
             "examples/transport.js",
             "browser.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "docs/api.md",
             "test/transport/core.test.js",
             "docs/transports.md",
             "test/types/pino-transport.tst.ts",
             "docs/help.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "docs/api.md",
             "docs/transports.md",
             "docs/help.md",
             "examples/transport.js",
             "pino.d.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "examples/transport.js",
             "pino.d.ts",
             "lib/transport.js",
             "pino.js",
             "lib/tools.js"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
+            "lib/worker.js",
+            "benchmarks/basic.bench.js",
+            "examples/transport.js",
             "pino.d.ts",
-            "lib/multistream.js",
-            "lib/transport.js",
-            "pino.js",
-            "lib/levels.js"
+            "browser.js"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1474,105 +1474,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "docs/Reference/Errors.md",
             "docs/Reference/Routes.md",
             "SECURITY.md",
             "docs/Reference/TypeScript.md",
             "docs/Guides/Migration-Guide-V5.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "docs/Reference/Errors.md",
             "docs/Reference/Routes.md",
             "SECURITY.md",
             "docs/Reference/TypeScript.md",
             "docs/Guides/Migration-Guide-V5.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "lib/handle-request.js",
             "scripts/validate-ecosystem-links.js",
             "fastify.js",
             "lib/reply.js",
             "lib/server.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "SECURITY.md",
             "docs/Reference/Errors.md",
             ".github/workflows/links-check.yml",
             "CONTRIBUTING.md",
             "docs/Guides/Serverless.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "SECURITY.md",
             "docs/Reference/Errors.md",
             ".github/workflows/links-check.yml",
             "docs/Reference/Routes.md",
             "docs/Guides/Serverless.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "scripts/validate-ecosystem-links.js",
             "lib/handle-request.js",
             "types/schema.d.ts",
             "lib/logger-pino.js",
             "lib/server.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "lib/request.js",
-            "lib/server.js",
             "fastify.js",
-            "integration/server.js",
-            "types/request.d.ts"
+            "types/request.d.ts",
+            "lib/server.js",
+            "lib/route.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1587,105 +1587,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "readme.md",
             "source/vendor/supports-color/index.js",
             "source/vendor/supports-color/index.d.ts",
             "test/chalk.js",
             "source/index.d.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "readme.md",
             "source/vendor/supports-color/index.js",
             "source/vendor/supports-color/index.d.ts",
             "source/index.d.ts",
             "source/vendor/supports-color/browser.js"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "source/vendor/supports-color/index.js",
             "source/vendor/supports-color/index.d.ts",
             "source/index.d.ts",
             "source/vendor/supports-color/browser.js",
             "source/index.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "source/vendor/supports-color/index.js",
             "test/no-color-support.js",
             "source/vendor/supports-color/index.d.ts",
             "readme.md",
             "source/vendor/supports-color/browser.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "source/vendor/supports-color/index.js",
             "readme.md",
             "source/vendor/supports-color/index.d.ts",
             "source/vendor/supports-color/browser.js",
             "source/index.d.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "source/vendor/supports-color/index.js",
             "source/vendor/supports-color/index.d.ts",
             "source/vendor/supports-color/browser.js",
             "examples/rainbow.js",
             "source/index.d.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "source/vendor/supports-color/index.js",
             "source/vendor/supports-color/browser.js",
             "source/vendor/supports-color/index.d.ts",
             "source/index.d.ts",
-            "source/index.js"
+            "package.json"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1700,105 +1700,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "docs/guide/browser/visual-regression-testing.md",
             "docs/api/vi.md",
             "docs/guide/migration.md",
             "docs/guide/learn/debugging-tests.md",
             "docs/blog/vitest-4-1.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "docs/guide/browser/visual-regression-testing.md",
             "docs/api/vi.md",
             "docs/guide/migration.md",
             "docs/guide/learn/debugging-tests.md",
             "docs/blog/vitest-4-1.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
+            "packages/vitest/src/node/types/config.ts",
             "packages/vitest/src/node/types/browser.ts",
             "packages/browser/src/client/orchestrator.ts",
             "packages/vitest/src/node/cli/cli-config.ts",
-            "packages/vitest/src/integrations/vi.ts",
-            "packages/browser/context.d.ts"
+            "packages/vitest/src/integrations/vi.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             ".github/ISSUE_TEMPLATE/feature_request.yml",
             "docs/guide/browser/index.md",
             "docs/blog/vitest-4-1.md",
             "docs/guide/learn/debugging-tests.md",
             "docs/guide/features.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             ".github/ISSUE_TEMPLATE/feature_request.yml",
             "docs/guide/learn/debugging-tests.md",
             "docs/guide/browser/index.md",
             "docs/blog/vitest-4-1.md",
             "docs/api/vi.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "packages/vitest/src/integrations/vi.ts",
             "packages/browser/src/client/tester/dialog.ts",
+            "packages/vitest/src/node/types/config.ts",
             "packages/vitest/src/node/cli/cli-config.ts",
-            "packages/spy/src/types.ts",
-            "packages/spy/src/index.ts"
+            "packages/spy/src/types.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "packages/vitest/src/integrations/env/jsdom-keys.ts",
             "packages/browser/src/client/tester/dialog.ts",
-            "packages/vitest/src/node/printError.ts",
-            "packages/vitest/src/runtime/runner/suite.ts",
-            "packages/pretty-format/src/index.ts"
+            "packages/vitest/src/runtime/runners/test.ts",
+            "packages/browser/src/client/tester/runner.ts",
+            "packages/vitest/src/create/browser/creator.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1813,105 +1813,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "docs/src/extend/custom-rules.md",
             "lib/linter/linter.js",
             "docs/src/use/migrate-to-9.0.0.md",
             "lib/types/index.d.ts",
             "docs/src/use/configure/migration-guide.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "docs/src/extend/custom-rules.md",
             "lib/linter/linter.js",
             "docs/src/use/migrate-to-9.0.0.md",
             "lib/types/index.d.ts",
             "docs/src/use/configure/migration-guide.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "lib/linter/linter.js",
             "lib/types/index.d.ts",
             "lib/eslint/eslint.js",
             "lib/languages/js/source-code/source-code.js",
-            "lib/eslint/eslint-helpers.js"
+            "lib/config/config.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "docs/src/use/configure/migration-guide.md",
             "docs/src/extend/plugin-migration-flat-config.md",
             "docs/src/use/migrate-to-9.0.0.md",
             "docs/src/extend/custom-rule-tutorial.md",
             "docs/src/use/configure/configuration-files.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "docs/src/use/configure/migration-guide.md",
             "docs/src/use/migrate-to-9.0.0.md",
             "docs/src/extend/plugin-migration-flat-config.md",
             "docs/src/use/migrate-to-10.0.0.md",
             "docs/src/extend/custom-rule-tutorial.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "lib/options.js",
             "lib/linter/linter.js",
             "lib/types/index.d.ts",
             "lib/languages/js/source-code/source-code.js",
             "messages/all-matched-files-ignored.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "lib/types/config-api.d.ts",
-            "package.json",
-            "lib/config-api.js",
+            "lib/config/config.js",
             "lib/types/index.d.ts",
-            "lib/config/config.js"
+            "package.json",
+            "lib/rules/space-before-function-paren.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1926,105 +1926,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "AGENTS.md",
             "lib/Module.js",
             "CONTRIBUTING.md",
             "lib/SourceMapDevToolPlugin.js",
             "examples/css/README.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "AGENTS.md",
             "lib/Module.js",
             "CONTRIBUTING.md",
             "lib/SourceMapDevToolPlugin.js",
             "examples/css/README.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "lib/Module.js",
             "lib/SourceMapDevToolPlugin.js",
             "lib/dependencies/HtmlEntryDependency.js",
             "lib/WebpackOptionsApply.js",
             "lib/RuntimeTemplate.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "CONTRIBUTING.md",
             ".changeset/README.md",
             "WORKING_GROUP.md",
             ".github/workflows/release.yml",
             "AGENTS.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "CONTRIBUTING.md",
             "AGENTS.md",
             "open-bot.yaml",
             "lib/DotenvPlugin.js",
             ".github/workflows/test.yml"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "lib/DotenvPlugin.js",
             "lib/WebpackOptionsApply.js",
             "lib/config/target.js",
             "lib/CleanPlugin.js",
             "bin/webpack.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
+            "lib/DefinePlugin.js",
             "lib/dependencies/ImportMetaPlugin.js",
             "lib/WebpackOptionsApply.js",
-            "lib/DefinePlugin.js",
             "lib/EnvironmentPlugin.js",
-            "lib/dependencies/CreateRequireParserPlugin.js"
+            "lib/url/URLParserPlugin.js"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -2039,106 +2039,106 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "lib/dispatcher/client-h2.js",
             "test/http2-dispatcher.js",
             "docs/docs/index.md",
             "README.md",
             "lib/dispatcher/client-h1.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "lib/dispatcher/client-h2.js",
             "docs/docs/index.md",
             "README.md",
             "lib/dispatcher/client-h1.js",
             "lib/web/fetch/request.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "lib/dispatcher/client-h2.js",
             "lib/dispatcher/client-h1.js",
             "lib/web/fetch/request.js",
             "types/dispatcher.d.ts",
             "lib/web/fetch/util.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "test/http2-late-data.js",
             "lib/dispatcher/client-h2.js",
             "test/http2-dispatcher.js",
             "lib/api/api-stream.js",
             "test/fetch/issue-4058.js"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "lib/dispatcher/client-h2.js",
             "lib/api/api-stream.js",
             "types/dispatcher.d.ts",
             "lib/dispatcher/client-h1.js",
             "lib/web/eventsource/eventsource.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "lib/dispatcher/client-h2.js",
             "lib/api/api-stream.js",
             "lib/dispatcher/client-h1.js",
             "types/dispatcher.d.ts",
             "lib/web/eventsource/eventsource.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
-            "lib/dispatcher/client-h2.js",
-            "lib/web/fetch/body.js",
+          "top5Paths": [
             "lib/web/fetch/request.js",
-            "lib/web/fetch/response.js",
-            "lib/api/api-request.js"
+            "lib/core/request.js",
+            "lib/dispatcher/client-h1.js",
+            "lib/dispatcher/client.js",
+            "lib/web/fetch/body.js"
           ],
-          "top1": true,
-          "top3": true,
-          "top5Hit": true
+          "top1Hit": false,
+          "top3Hit": false,
+          "top5Hit": false
         }
       }
     },
@@ -2152,111 +2152,111 @@
       "mentionTier": "path-suffix",
       "arms": {
         "path-extraction:raw": {
-          "top5": [
+          "top5Paths": [
             "packages/toolkit/src/query/react/buildHooks.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "path-extraction:source": {
-          "top5": [
+          "top5Paths": [
             "packages/toolkit/src/query/react/buildHooks.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "path-extraction:code": {
-          "top5": [
+          "top5Paths": [
             "packages/toolkit/src/query/react/buildHooks.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "packages/toolkit/src/query/core/buildThunks.ts",
             "packages/toolkit/src/query/core/module.ts",
             "packages/toolkit/src/query/core/apiState.ts",
             "packages/toolkit/src/query/tests/buildThunks.test.tsx",
             "_artifacts/domain_map.yaml"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "packages/toolkit/src/query/core/buildThunks.ts",
             "packages/toolkit/src/query/core/module.ts",
             "packages/toolkit/src/query/core/apiState.ts",
             "_artifacts/domain_map.yaml",
             "packages/toolkit/src/query/endpointDefinitions.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "packages/toolkit/src/query/core/buildThunks.ts",
             "packages/toolkit/src/query/core/module.ts",
             "packages/toolkit/src/query/core/apiState.ts",
             "packages/toolkit/src/query/endpointDefinitions.ts",
             "packages/toolkit/src/query/core/buildSlice.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "packages/toolkit/src/query/core/apiState.ts",
             "packages/toolkit/src/query/core/buildSlice.ts",
             "packages/toolkit/src/query/tests/queryLifecycle.test.tsx",
             "packages/toolkit/src/query/core/buildThunks.ts",
             "packages/toolkit/src/query/tests/cacheLifecycle.test.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "packages/toolkit/src/query/core/apiState.ts",
             "packages/toolkit/src/query/core/buildSlice.ts",
             "packages/toolkit/src/query/core/buildThunks.ts",
             "packages/toolkit/src/query/core/buildSelectors.ts",
             "packages/toolkit/src/query/core/buildMiddleware/cacheLifecycle.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "packages/toolkit/src/query/core/apiState.ts",
             "packages/toolkit/src/query/core/buildSlice.ts",
             "packages/toolkit/src/query/core/buildThunks.ts",
             "packages/toolkit/src/query/core/buildSelectors.ts",
             "packages/toolkit/src/query/core/buildMiddleware/queryLifecycle.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
+            "packages/toolkit/src/query/react/buildHooks.ts",
             "packages/toolkit/src/query/core/apiState.ts",
             "packages/toolkit/src/query/core/buildThunks.ts",
-            "packages/toolkit/src/query/react/buildHooks.ts",
-            "packages/toolkit/src/listenerMiddleware/index.ts",
-            "examples/query/react/authentication-with-extrareducers/public/mockServiceWorker.js"
+            "packages/toolkit/src/query/core/buildMiddleware/types.ts",
+            "packages/toolkit/src/createAsyncThunk.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -2271,105 +2271,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "website/blog/2021-05-09-2.3.0.md",
             "tests/format/markdown/markdown/real-world-case.md",
             "website/blog/2018-04-11-1.12.0.md",
             "website/blog/2017-11-07-1.8.0.md",
             "website/blog/2020-03-21-2.0.0.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "website/blog/2021-05-09-2.3.0.md",
             "website/blog/2018-04-11-1.12.0.md",
             "website/blog/2017-11-07-1.8.0.md",
             "website/blog/2020-03-21-2.0.0.md",
             "website/blog/2018-05-27-1.13.0.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "src/index.d.ts",
             "src/language-js/parentheses/needs-parentheses.js",
             "src/language-js/types/flow-estree.d.ts",
             "src/language-js/print/binaryish.js",
             "src/language-css/parser-postcss.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "website/blog/2017-04-20-1.2.0.md",
             "README.md",
             "website/blog/2023-11-13-curious-ternaries.md",
             "website/blog/2018-04-09-plugin-php-0.1.md",
             ".vscode/settings.example.json"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "website/blog/2017-04-20-1.2.0.md",
             "website/blog/2023-11-13-curious-ternaries.md",
             "website/blog/2017-11-07-1.8.0.md",
             "website/blog/2023-11-30-cli-deep-dive.md",
             "docs/rationale.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "scripts/utilities/changelog.js",
             "website/playground/utilities.js",
             "src/main/core-options.evaluate.js",
             "website/src/pages/index.jsx",
             "src/language-css/parser-postcss.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "fixmap": {
-          "top5": [
-            "src/language-css/print/comma-separated-value-group.js",
-            "src/language-js/print/member-chain.js",
+          "top5Paths": [
             "scripts/build/builders/javascript-module.js",
+            "src/language-css/print/comma-separated-value-group.js",
             "website/playground/Playground.jsx",
-            "src/language-js/print/binaryish.js"
+            "src/language-css/parser-postcss.js",
+            "src/language-css/utilities/index.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -2384,105 +2384,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "runtime-tests/lambda/index.test.ts",
             "src/adapter/aws-lambda/handler.ts",
             "runtime-tests/lambda/stream.test.ts",
             "src/adapter/aws-lambda/handler.test.ts",
             "docs/MIGRATION.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "src/adapter/aws-lambda/handler.ts",
             "docs/MIGRATION.md",
             "src/jsx/dom/render.ts",
             "src/context.ts",
             "src/hono-base.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "src/adapter/aws-lambda/handler.ts",
             "src/jsx/dom/render.ts",
             "src/context.ts",
             "src/hono-base.ts",
             "src/adapter/lambda-edge/handler.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "runtime-tests/lambda/stream.test.ts",
             "runtime-tests/lambda/index.test.ts",
             "src/adapter/aws-lambda/handler.ts",
             "src/adapter/aws-lambda/handler.test.ts",
             "src/adapter/aws-lambda/types.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "src/adapter/aws-lambda/handler.ts",
             "src/adapter/aws-lambda/types.ts",
             "src/adapter/aws-lambda/index.ts",
             "src/adapter/lambda-edge/handler.ts",
             "runtime-tests/lambda/stream-mock.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "src/adapter/aws-lambda/handler.ts",
             "src/adapter/aws-lambda/types.ts",
             "src/adapter/aws-lambda/index.ts",
             "runtime-tests/lambda/stream-mock.ts",
             "runtime-tests/lambda/mock.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
-            "src/adapter/aws-lambda/handler.ts",
+          "top5Paths": [
             "src/adapter/aws-lambda/types.ts",
+            "src/adapter/aws-lambda/handler.ts",
             "src/adapter/aws-lambda/conninfo.ts",
-            "src/adapter/lambda-edge/handler.ts",
-            "src/jsx/context.ts"
+            "src/middleware/basic-auth/index.ts",
+            "src/middleware/bearer-auth/index.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -2497,111 +2497,111 @@
       "mentionTier": "full-path",
       "arms": {
         "path-extraction:raw": {
-          "top5": [
+          "top5Paths": [
             "source/core/index.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "path-extraction:source": {
-          "top5": [
+          "top5Paths": [
             "source/core/index.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "path-extraction:code": {
-          "top5": [
+          "top5Paths": [
             "source/core/index.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "documentation/2-options.md",
             "documentation/3-streams.md",
             "documentation/tips.md",
             "documentation/migration-guides/request.md",
             "documentation/4-pagination.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "documentation/2-options.md",
             "documentation/3-streams.md",
             "documentation/tips.md",
             "documentation/migration-guides/request.md",
             "documentation/4-pagination.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "source/core/response.ts",
             "source/types.ts",
             "source/as-promise/index.ts",
             "source/core/errors.ts",
             "source/as-promise/types.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "documentation/2-options.md",
             "documentation/4-pagination.md",
             "source/core/response.ts",
             "documentation/migration-guides/request.md",
             "documentation/tips.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "documentation/2-options.md",
             "source/core/response.ts",
             "documentation/4-pagination.md",
             "documentation/migration-guides/request.md",
             "documentation/tips.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "source/core/response.ts",
             "source/as-promise/types.ts",
             "source/as-promise/index.ts",
             "source/types.ts",
             "source/core/errors.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "source/core/index.ts",
-            "source/core/diagnostics-channel.ts",
-            "source/core/response.ts",
             "source/as-promise/index.ts",
-            "source/core/errors.ts"
+            "source/core/errors.ts",
+            "source/core/response.ts",
+            "source/core/diagnostics-channel.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
diff --git a/benchmarks/external/results.json b/benchmarks/external/results.json
index 3bfbb56..890fe2b 100644
--- a/benchmarks/external/results.json
+++ b/benchmarks/external/results.json
@@ -1,63 +1,62 @@
 {
   "cases": 16,
   "top1HitRate": 0.688,
-  "top3HitRate": 1,
-  "top5HitRate": 1,
+  "top3HitRate": 0.938,
+  "top5HitRate": 0.938,
   "intervals95": {
     "top1": [
       0.444,
       0.858
     ],
     "top3": [
-      0.806,
-      1
+      0.717,
+      0.989
     ],
     "top5": [
-      0.806,
-      1
+      0.717,
+      0.989
     ]
   },
   "misleadingTopResult": {
-    "cases": 5,
+    "cases": 4,
     "of": 16,
-    "rate": 0.313,
+    "rate": 0.25,
     "slugs": [
-      "pinojs/pino",
+      "debug-js/debug",
+      "colinhacks/zod",
       "vitest-dev/vitest",
-      "webpack/webpack",
-      "reduxjs/redux-toolkit",
-      "honojs/hono"
+      "prettier/prettier"
     ]
   },
   "calibration": [
     {
       "confidence": "high",
       "cases": 3,
-      "top1Correct": 2,
-      "top1Accuracy": 0.667,
+      "top1Correct": 3,
+      "top1Accuracy": 1,
       "interval95": [
-        0.208,
-        0.939
+        0.438,
+        1
       ]
     },
     {
       "confidence": "medium",
-      "cases": 11,
+      "cases": 12,
       "top1Correct": 8,
-      "top1Accuracy": 0.727,
+      "top1Accuracy": 0.667,
       "interval95": [
-        0.434,
-        0.903
+        0.391,
+        0.862
       ]
     },
     {
       "confidence": "low",
-      "cases": 2,
-      "top1Correct": 1,
-      "top1Accuracy": 0.5,
+      "cases": 1,
+      "top1Correct": 0,
+      "top1Accuracy": 0,
       "interval95": [
-        0.095,
-        0.905
+        0,
+        0.793
       ]
     }
   ],
@@ -65,20 +64,20 @@
     "all": {
       "cases": 16,
       "top1HitRate": 0.688,
-      "top3HitRate": 1,
-      "top5HitRate": 1,
+      "top3HitRate": 0.938,
+      "top5HitRate": 0.938,
       "intervals95": {
         "top1": [
           0.444,
           0.858
         ],
         "top3": [
-          0.806,
-          1
+          0.717,
+          0.989
         ],
         "top5": [
-          0.806,
-          1
+          0.717,
+          0.989
         ]
       },
       "slugs": [
@@ -102,21 +101,21 @@
     },
     "unmentioned": {
       "cases": 13,
-      "top1HitRate": 0.692,
-      "top3HitRate": 1,
-      "top5HitRate": 1,
+      "top1HitRate": 0.615,
+      "top3HitRate": 0.923,
+      "top5HitRate": 0.923,
       "intervals95": {
         "top1": [
-          0.424,
-          0.873
+          0.355,
+          0.823
         ],
         "top3": [
-          0.772,
-          1
+          0.667,
+          0.986
         ],
         "top5": [
-          0.772,
-          1
+          0.667,
+          0.986
         ]
       },
       "slugs": [
@@ -137,13 +136,13 @@
     },
     "mentioned": {
       "cases": 3,
-      "top1HitRate": 0.667,
+      "top1HitRate": 1,
       "top3HitRate": 1,
       "top5HitRate": 1,
       "intervals95": {
         "top1": [
-          0.208,
-          0.939
+          0.438,
+          1
         ],
         "top3": [
           0.438,
@@ -162,9 +161,16 @@
     }
   },
   "floors": {
-    "top1": 0.3,
-    "top3": 0.5,
-    "top5": 0.5
+    "all": {
+      "top1": 0.625,
+      "top3": 0.937,
+      "top5": 0.937
+    },
+    "unmentioned": {
+      "top1": 0.615,
+      "top3": 0.923,
+      "top5": 0.923
+    }
   },
   "results": [
     {
@@ -173,16 +179,16 @@
       "expected": [
         "lib/request.js"
       ],
-      "top5": [
+      "top5Paths": [
         "lib/request.js",
         "lib/response.js",
-        "package.json",
         "examples/auth/index.js",
-        "examples/route-middleware/index.js"
+        "examples/route-middleware/index.js",
+        "examples/web-service/index.js"
       ],
       "topConfidence": "high",
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": true,
       "mentionTier": "full-path",
@@ -201,16 +207,16 @@
       "expected": [
         "lib/core/AxiosError.js"
       ],
-      "top5": [
+      "top5Paths": [
         "lib/core/AxiosError.js",
         "lib/adapters/http.js",
         "lib/helpers/HttpStatusCode.js",
-        "index.d.cts",
-        "index.d.ts"
+        "lib/core/Axios.js",
+        "lib/core/AxiosHeaders.js"
       ],
       "topConfidence": "medium",
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -222,16 +228,16 @@
       "expected": [
         "src/node.js"
       ],
-      "top5": [
-        "src/node.js",
-        "src/browser.js",
+      "top5Paths": [
         "src/common.js",
         "test.js",
-        "karma.conf.js"
+        "src/node.js",
+        "README.md",
+        "src/browser.js"
       ],
       "topConfidence": "medium",
-      "top1": true,
-      "top3": true,
+      "top1Hit": false,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -243,16 +249,16 @@
       "expected": [
         "source/core/Ky.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "source/core/Ky.ts",
         "source/errors/HTTPError.ts",
         "source/types/hooks.ts",
         "source/types/options.ts",
-        "source/errors/SchemaValidationError.ts"
+        "source/core/constants.ts"
       ],
       "topConfidence": "medium",
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -264,16 +270,16 @@
       "expected": [
         "packages/zod/src/v4/core/regexes.ts"
       ],
-      "top5": [
-        "packages/zod/src/v4/core/regexes.ts",
-        "packages/zod/src/v4/classic/from-json-schema.ts",
+      "top5Paths": [
         "packages/zod/src/v4/core/json-schema-processors.ts",
+        "packages/zod/src/v4/core/regexes.ts",
         "packages/zod/src/v4/mini/schemas.ts",
-        "packages/zod/src/v4/core/parse.ts"
+        "packages/zod/src/v4/classic/from-json-schema.ts",
+        "packages/zod/src/v4/core/checks.ts"
       ],
       "topConfidence": "medium",
-      "top1": true,
-      "top3": true,
+      "top1Hit": false,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -286,16 +292,16 @@
         "lib/transport.js",
         "lib/worker.js"
       ],
-      "top5": [
+      "top5Paths": [
+        "lib/worker.js",
+        "benchmarks/basic.bench.js",
+        "examples/transport.js",
         "pino.d.ts",
-        "lib/multistream.js",
-        "lib/transport.js",
-        "pino.js",
-        "lib/levels.js"
+        "browser.js"
       ],
       "topConfidence": "high",
-      "top1": false,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -307,16 +313,16 @@
       "expected": [
         "lib/request.js"
       ],
-      "top5": [
+      "top5Paths": [
         "lib/request.js",
-        "lib/server.js",
         "fastify.js",
-        "integration/server.js",
-        "types/request.d.ts"
+        "types/request.d.ts",
+        "lib/server.js",
+        "lib/route.js"
       ],
       "topConfidence": "medium",
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -328,16 +334,16 @@
       "expected": [
         "source/vendor/supports-color/index.js"
       ],
-      "top5": [
+      "top5Paths": [
         "source/vendor/supports-color/index.js",
         "source/vendor/supports-color/browser.js",
         "source/vendor/supports-color/index.d.ts",
         "source/index.d.ts",
-        "source/index.js"
+        "package.json"
       ],
       "topConfidence": "medium",
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -349,16 +355,16 @@
       "expected": [
         "packages/browser/src/client/tester/dialog.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "packages/vitest/src/integrations/env/jsdom-keys.ts",
         "packages/browser/src/client/tester/dialog.ts",
-        "packages/vitest/src/node/printError.ts",
-        "packages/vitest/src/runtime/runner/suite.ts",
-        "packages/pretty-format/src/index.ts"
+        "packages/vitest/src/runtime/runners/test.ts",
+        "packages/browser/src/client/tester/runner.ts",
+        "packages/vitest/src/create/browser/creator.ts"
       ],
       "topConfidence": "low",
-      "top1": false,
-      "top3": true,
+      "top1Hit": false,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -370,16 +376,16 @@
       "expected": [
         "lib/types/config-api.d.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "lib/types/config-api.d.ts",
-        "package.json",
-        "lib/config-api.js",
+        "lib/config/config.js",
         "lib/types/index.d.ts",
-        "lib/config/config.js"
+        "package.json",
+        "lib/rules/space-before-function-paren.js"
       ],
       "topConfidence": "medium",
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -391,16 +397,16 @@
       "expected": [
         "lib/DefinePlugin.js"
       ],
-      "top5": [
+      "top5Paths": [
+        "lib/DefinePlugin.js",
         "lib/dependencies/ImportMetaPlugin.js",
         "lib/WebpackOptionsApply.js",
-        "lib/DefinePlugin.js",
         "lib/EnvironmentPlugin.js",
-        "lib/dependencies/CreateRequireParserPlugin.js"
+        "lib/url/URLParserPlugin.js"
       ],
       "topConfidence": "medium",
-      "top1": false,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -412,17 +418,17 @@
       "expected": [
         "lib/dispatcher/client-h2.js"
       ],
-      "top5": [
-        "lib/dispatcher/client-h2.js",
-        "lib/web/fetch/body.js",
+      "top5Paths": [
         "lib/web/fetch/request.js",
-        "lib/web/fetch/response.js",
-        "lib/api/api-request.js"
+        "lib/core/request.js",
+        "lib/dispatcher/client-h1.js",
+        "lib/dispatcher/client.js",
+        "lib/web/fetch/body.js"
       ],
       "topConfidence": "medium",
-      "top1": true,
-      "top3": true,
-      "top5Hit": true,
+      "top1Hit": false,
+      "top3Hit": false,
+      "top5Hit": false,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
       "mentionEvidence": []
@@ -433,16 +439,16 @@
       "expected": [
         "packages/toolkit/src/query/react/buildHooks.ts"
       ],
-      "top5": [
+      "top5Paths": [
+        "packages/toolkit/src/query/react/buildHooks.ts",
         "packages/toolkit/src/query/core/apiState.ts",
         "packages/toolkit/src/query/core/buildThunks.ts",
-        "packages/toolkit/src/query/react/buildHooks.ts",
-        "packages/toolkit/src/listenerMiddleware/index.ts",
-        "examples/query/react/authentication-with-extrareducers/public/mockServiceWorker.js"
+        "packages/toolkit/src/query/core/buildMiddleware/types.ts",
+        "packages/toolkit/src/createAsyncThunk.ts"
       ],
       "topConfidence": "medium",
-      "top1": false,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": true,
       "mentionTier": "path-suffix",
@@ -461,16 +467,16 @@
       "expected": [
         "src/language-css/print/comma-separated-value-group.js"
       ],
-      "top5": [
-        "src/language-css/print/comma-separated-value-group.js",
-        "src/language-js/print/member-chain.js",
+      "top5Paths": [
         "scripts/build/builders/javascript-module.js",
+        "src/language-css/print/comma-separated-value-group.js",
         "website/playground/Playground.jsx",
-        "src/language-js/print/binaryish.js"
+        "src/language-css/parser-postcss.js",
+        "src/language-css/utilities/index.js"
       ],
-      "topConfidence": "low",
-      "top1": true,
-      "top3": true,
+      "topConfidence": "medium",
+      "top1Hit": false,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -482,16 +488,16 @@
       "expected": [
         "src/adapter/aws-lambda/types.ts"
       ],
-      "top5": [
-        "src/adapter/aws-lambda/handler.ts",
+      "top5Paths": [
         "src/adapter/aws-lambda/types.ts",
+        "src/adapter/aws-lambda/handler.ts",
         "src/adapter/aws-lambda/conninfo.ts",
-        "src/adapter/lambda-edge/handler.ts",
-        "src/jsx/context.ts"
+        "src/middleware/basic-auth/index.ts",
+        "src/middleware/bearer-auth/index.ts"
       ],
       "topConfidence": "medium",
-      "top1": false,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -503,16 +509,16 @@
       "expected": [
         "source/core/index.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "source/core/index.ts",
-        "source/core/diagnostics-channel.ts",
-        "source/core/response.ts",
         "source/as-promise/index.ts",
-        "source/core/errors.ts"
+        "source/core/errors.ts",
+        "source/core/response.ts",
+        "source/core/diagnostics-channel.ts"
       ],
       "topConfidence": "high",
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": true,
       "mentionTier": "full-path",
diff --git a/benchmarks/external/savings-results.json b/benchmarks/external/savings-results.json
index 5bd353e..65f84b3 100644
--- a/benchmarks/external/savings-results.json
+++ b/benchmarks/external/savings-results.json
@@ -1,5 +1,5 @@
 {
-  "measuredAt": "2026-07-26T05:40:14.104Z",
+  "measuredAt": "2026-08-11T05:31:21.470Z",
   "environment": {
     "node": "v24.13.0",
     "platform": "win32 10.0.26200",
@@ -7,377 +7,400 @@
     "runsPerRepository": 3,
     "repositoryCache": "warm after pinned checkout materialization"
   },
-  "cases": 15,
+  "cases": 16,
   "accuracy": {
-    "top1HitRate": 0.6,
-    "top3HitRate": 1,
-    "top5HitRate": 1
+    "top1HitRate": 0.688,
+    "top3HitRate": 0.938,
+    "top5HitRate": 0.938
   },
   "performance": {
-    "medianScanAndRankMs": 1747.7
+    "medianScanAndRankMs": 1300
   },
   "contextProxy": {
     "baseline": "Assumed: every scanned text-bearing file in FixMap's supported extension set is sent as context.",
     "comparison": "Estimated: only FixMap's top-five ranked files are sent as context.",
     "tokenEstimator": "UTF-8 file bytes divided by 4; this is not tokenizer output.",
-    "assumedAllSourceTokens": 22058578,
-    "estimatedTop5Tokens": 318546,
-    "estimatedTokenReduction": 0.9856
+    "assumedAllSourceTokens": 22440777,
+    "estimatedTop5Tokens": 330646,
+    "estimatedTokenReduction": 0.9853
   },
   "timeComparison": {
     "baseline": "Assumed manual repository triage: 15 minutes per task.",
     "warning": "The manual baseline was not measured in a controlled with/without agent experiment.",
     "assumedManualMinutes": 15,
-    "measuredFixMapMinutes": 0.0291,
-    "impliedMinutesSaved": 14.97,
-    "impliedTimeReduction": 0.9981
+    "measuredFixMapMinutes": 0.0217,
+    "impliedMinutesSaved": 14.98,
+    "impliedTimeReduction": 0.9986
   },
   "results": [
     {
       "slug": "expressjs/express",
       "issue": 7365,
       "scannedFiles": 213,
-      "medianRuntimeMs": 734.3,
+      "medianRuntimeMs": 510.8,
       "expected": [
         "lib/request.js"
       ],
-      "top5": [
+      "top5Paths": [
         "lib/request.js",
         "lib/response.js",
-        "package.json",
-        "examples/error-pages/index.js",
-        "examples/route-middleware/index.js"
+        "examples/auth/index.js",
+        "examples/route-middleware/index.js",
+        "examples/web-service/index.js"
       ],
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 727851,
-      "rankedBytes": 47062,
-      "assumedAllSourceTokens": 181963,
-      "estimatedTop5Tokens": 11766
+      "sourceBytes": 729592,
+      "rankedBytes": 48329,
+      "assumedAllSourceTokens": 182398,
+      "estimatedTop5Tokens": 12083
     },
     {
       "slug": "axios/axios",
       "issue": 6721,
       "scannedFiles": 454,
-      "medianRuntimeMs": 5941.7,
+      "medianRuntimeMs": 1231.1,
       "expected": [
         "lib/core/AxiosError.js"
       ],
-      "top5": [
+      "top5Paths": [
         "lib/core/AxiosError.js",
         "lib/adapters/http.js",
         "lib/helpers/HttpStatusCode.js",
-        "index.d.ts",
-        "lib/adapters/xhr.js"
+        "lib/core/Axios.js",
+        "lib/core/AxiosHeaders.js"
       ],
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 3056385,
-      "rankedBytes": 90899,
-      "assumedAllSourceTokens": 764097,
-      "estimatedTop5Tokens": 22725
+      "sourceBytes": 3097580,
+      "rankedBytes": 79905,
+      "assumedAllSourceTokens": 774395,
+      "estimatedTop5Tokens": 19977
     },
     {
       "slug": "debug-js/debug",
       "issue": 746,
       "scannedFiles": 14,
-      "medianRuntimeMs": 241.6,
+      "medianRuntimeMs": 172.3,
       "expected": [
         "src/node.js"
       ],
-      "top5": [
-        "src/browser.js",
-        "src/node.js",
+      "top5Paths": [
         "src/common.js",
+        "test.js",
+        "src/node.js",
         "README.md",
-        "test.js"
+        "src/browser.js"
       ],
-      "top1": false,
-      "top3": true,
+      "top1Hit": false,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 50170,
+      "sourceBytes": 52209,
       "rankedBytes": 44787,
-      "assumedAllSourceTokens": 12543,
+      "assumedAllSourceTokens": 13053,
       "estimatedTop5Tokens": 11197
     },
     {
       "slug": "sindresorhus/ky",
       "issue": 857,
       "scannedFiles": 67,
-      "medianRuntimeMs": 442.2,
+      "medianRuntimeMs": 346.1,
       "expected": [
         "source/core/Ky.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "source/core/Ky.ts",
-        "source/types/hooks.ts",
         "source/errors/HTTPError.ts",
+        "source/types/hooks.ts",
         "source/types/options.ts",
-        "source/errors/SchemaValidationError.ts"
+        "source/core/constants.ts"
       ],
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 515493,
-      "rankedBytes": 66339,
-      "assumedAllSourceTokens": 128874,
-      "estimatedTop5Tokens": 16585
+      "sourceBytes": 516872,
+      "rankedBytes": 73509,
+      "assumedAllSourceTokens": 129218,
+      "estimatedTop5Tokens": 18378
     },
     {
       "slug": "colinhacks/zod",
       "issue": 5944,
       "scannedFiles": 582,
-      "medianRuntimeMs": 3161.2,
+      "medianRuntimeMs": 1553.9,
       "expected": [
         "packages/zod/src/v4/core/regexes.ts"
       ],
-      "top5": [
+      "top5Paths": [
+        "packages/zod/src/v4/core/json-schema-processors.ts",
         "packages/zod/src/v4/core/regexes.ts",
+        "packages/zod/src/v4/mini/schemas.ts",
         "packages/zod/src/v4/classic/from-json-schema.ts",
-        "packages/zod/src/v4/core/json-schema-processors.ts",
-        "packages/zod/src/v4/core/to-json-schema.ts",
-        "packages/zod/src/v4/mini/schemas.ts"
+        "packages/zod/src/v4/core/checks.ts"
       ],
-      "top1": true,
-      "top3": true,
+      "top1Hit": false,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 3503802,
-      "rankedBytes": 141032,
-      "assumedAllSourceTokens": 875951,
-      "estimatedTop5Tokens": 35258
+      "sourceBytes": 3512790,
+      "rankedBytes": 158879,
+      "assumedAllSourceTokens": 878198,
+      "estimatedTop5Tokens": 39720
     },
     {
       "slug": "pinojs/pino",
       "issue": 1996,
       "scannedFiles": 200,
-      "medianRuntimeMs": 1205.2,
+      "medianRuntimeMs": 498.6,
       "expected": [
         "lib/transport.js",
         "lib/worker.js"
       ],
-      "top5": [
+      "top5Paths": [
+        "lib/worker.js",
+        "benchmarks/basic.bench.js",
+        "examples/transport.js",
         "pino.d.ts",
-        "lib/multistream.js",
-        "lib/transport.js",
-        "pino.js",
-        "examples/transport.js"
+        "browser.js"
       ],
-      "top1": false,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 686991,
-      "rankedBytes": 60825,
-      "assumedAllSourceTokens": 171748,
-      "estimatedTop5Tokens": 15207
+      "sourceBytes": 692500,
+      "rankedBytes": 69383,
+      "assumedAllSourceTokens": 173125,
+      "estimatedTop5Tokens": 17346
     },
     {
       "slug": "fastify/fastify",
       "issue": 6671,
       "scannedFiles": 393,
-      "medianRuntimeMs": 2057.2,
+      "medianRuntimeMs": 840.5,
       "expected": [
         "lib/request.js"
       ],
-      "top5": [
+      "top5Paths": [
+        "lib/request.js",
         "fastify.js",
+        "types/request.d.ts",
         "lib/server.js",
-        "lib/request.js",
-        "docs/Reference/TypeScript.md",
-        "types/request.d.ts"
+        "lib/route.js"
       ],
-      "top1": false,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 2898149,
-      "rankedBytes": 127634,
-      "assumedAllSourceTokens": 724538,
-      "estimatedTop5Tokens": 31909
+      "sourceBytes": 2902587,
+      "rankedBytes": 87514,
+      "assumedAllSourceTokens": 725647,
+      "estimatedTop5Tokens": 21879
     },
     {
       "slug": "chalk/chalk",
       "issue": 624,
       "scannedFiles": 33,
-      "medianRuntimeMs": 585.2,
+      "medianRuntimeMs": 204.8,
       "expected": [
         "source/vendor/supports-color/index.js"
       ],
-      "top5": [
+      "top5Paths": [
         "source/vendor/supports-color/index.js",
         "source/vendor/supports-color/browser.js",
         "source/vendor/supports-color/index.d.ts",
         "source/index.d.ts",
-        "source/index.js"
+        "package.json"
       ],
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 61363,
-      "rankedBytes": 19494,
-      "assumedAllSourceTokens": 15341,
-      "estimatedTop5Tokens": 4874
+      "sourceBytes": 62718,
+      "rankedBytes": 14587,
+      "assumedAllSourceTokens": 15680,
+      "estimatedTop5Tokens": 3647
     },
     {
       "slug": "vitest-dev/vitest",
       "issue": 7375,
       "scannedFiles": 3050,
-      "medianRuntimeMs": 7201.2,
+      "medianRuntimeMs": 6341,
       "expected": [
         "packages/browser/src/client/tester/dialog.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "packages/vitest/src/integrations/env/jsdom-keys.ts",
-        "packages/vitest/src/node/printError.ts",
         "packages/browser/src/client/tester/dialog.ts",
-        "packages/vitest/src/node/reporters/base.ts",
-        "packages/vitest/src/runtime/moduleRunner/moduleEvaluator.ts"
+        "packages/vitest/src/runtime/runners/test.ts",
+        "packages/browser/src/client/tester/runner.ts",
+        "packages/vitest/src/create/browser/creator.ts"
       ],
-      "top1": false,
-      "top3": true,
+      "top1Hit": false,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 8007670,
-      "rankedBytes": 74225,
-      "assumedAllSourceTokens": 2001918,
-      "estimatedTop5Tokens": 18557
+      "sourceBytes": 8185503,
+      "rankedBytes": 44635,
+      "assumedAllSourceTokens": 2046376,
+      "estimatedTop5Tokens": 11159
     },
     {
       "slug": "eslint/eslint",
       "issue": 478,
       "scannedFiles": 2297,
-      "medianRuntimeMs": 3244.5,
+      "medianRuntimeMs": 3750.9,
       "expected": [
         "lib/types/config-api.d.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "lib/types/config-api.d.ts",
+        "lib/config/config.js",
         "lib/types/index.d.ts",
         "package.json",
-        "docs/src/use/configure/migration-guide.md",
-        "lib/config-api.js"
+        "lib/rules/space-before-function-paren.js"
       ],
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 17155140,
-      "rankedBytes": 75779,
-      "assumedAllSourceTokens": 4288785,
-      "estimatedTop5Tokens": 18945
+      "sourceBytes": 17229912,
+      "rankedBytes": 78785,
+      "assumedAllSourceTokens": 4307478,
+      "estimatedTop5Tokens": 19697
     },
     {
       "slug": "webpack/webpack",
       "issue": 15371,
       "scannedFiles": 13454,
-      "medianRuntimeMs": 16661.6,
+      "medianRuntimeMs": 20994.1,
       "expected": [
         "lib/DefinePlugin.js"
       ],
-      "top5": [
+      "top5Paths": [
+        "lib/DefinePlugin.js",
         "lib/dependencies/ImportMetaPlugin.js",
         "lib/WebpackOptionsApply.js",
-        "lib/DefinePlugin.js",
-        "lib/dependencies/CreateRequireParserPlugin.js",
-        "lib/dependencies/LoaderPlugin.js"
+        "lib/EnvironmentPlugin.js",
+        "lib/url/URLParserPlugin.js"
       ],
-      "top1": false,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 26898376,
-      "rankedBytes": 126489,
-      "assumedAllSourceTokens": 6724594,
-      "estimatedTop5Tokens": 31623
+      "sourceBytes": 26903341,
+      "rankedBytes": 118506,
+      "assumedAllSourceTokens": 6725836,
+      "estimatedTop5Tokens": 29627
     },
     {
       "slug": "nodejs/undici",
       "issue": 5566,
       "scannedFiles": 786,
-      "medianRuntimeMs": 1225.5,
+      "medianRuntimeMs": 2199.2,
       "expected": [
         "lib/dispatcher/client-h2.js"
       ],
-      "top5": [
-        "lib/dispatcher/client-h2.js",
-        "lib/web/fetch/body.js",
+      "top5Paths": [
         "lib/web/fetch/request.js",
-        "lib/web/fetch/response.js",
-        "lib/api/api-request.js"
+        "lib/core/request.js",
+        "lib/dispatcher/client-h1.js",
+        "lib/dispatcher/client.js",
+        "lib/web/fetch/body.js"
       ],
-      "top1": true,
-      "top3": true,
-      "top5Hit": true,
-      "sourceBytes": 6873700,
-      "rankedBytes": 128985,
-      "assumedAllSourceTokens": 1718425,
-      "estimatedTop5Tokens": 32247
+      "top1Hit": false,
+      "top3Hit": false,
+      "top5Hit": false,
+      "sourceBytes": 6880537,
+      "rankedBytes": 141399,
+      "assumedAllSourceTokens": 1720135,
+      "estimatedTop5Tokens": 35350
     },
     {
       "slug": "reduxjs/redux-toolkit",
       "issue": 5156,
       "scannedFiles": 1152,
-      "medianRuntimeMs": 1747.7,
+      "medianRuntimeMs": 2834.1,
       "expected": [
         "packages/toolkit/src/query/react/buildHooks.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "packages/toolkit/src/query/react/buildHooks.ts",
         "packages/toolkit/src/query/core/apiState.ts",
         "packages/toolkit/src/query/core/buildThunks.ts",
-        "packages/toolkit/src/query/react/module.ts",
-        "packages/toolkit/src/query/core/buildInitiate.ts"
+        "packages/toolkit/src/query/core/buildMiddleware/types.ts",
+        "packages/toolkit/src/createAsyncThunk.ts"
       ],
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 6277414,
-      "rankedBytes": 147148,
-      "assumedAllSourceTokens": 1569354,
-      "estimatedTop5Tokens": 36787
+      "sourceBytes": 6315820,
+      "rankedBytes": 149008,
+      "assumedAllSourceTokens": 1578955,
+      "estimatedTop5Tokens": 37252
     },
     {
       "slug": "prettier/prettier",
       "issue": 5738,
       "scannedFiles": 9319,
-      "medianRuntimeMs": 10195.7,
+      "medianRuntimeMs": 12715.8,
       "expected": [
         "src/language-css/print/comma-separated-value-group.js"
       ],
-      "top5": [
-        "src/cli/format.js",
-        "src/language-css/print/comma-separated-value-group.js",
-        "src/language-js/print/member-chain.js",
+      "top5Paths": [
         "scripts/build/builders/javascript-module.js",
-        "scripts/build/packages/prettier.js"
+        "src/language-css/print/comma-separated-value-group.js",
+        "website/playground/Playground.jsx",
+        "src/language-css/parser-postcss.js",
+        "src/language-css/utilities/index.js"
       ],
-      "top1": false,
-      "top3": true,
+      "top1Hit": false,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 8832175,
-      "rankedBytes": 81223,
-      "assumedAllSourceTokens": 2208044,
-      "estimatedTop5Tokens": 20306
+      "sourceBytes": 8875617,
+      "rankedBytes": 68738,
+      "assumedAllSourceTokens": 2218905,
+      "estimatedTop5Tokens": 17185
     },
     {
       "slug": "honojs/hono",
       "issue": 3281,
       "scannedFiles": 482,
-      "medianRuntimeMs": 701.9,
+      "medianRuntimeMs": 1368.9,
       "expected": [
         "src/adapter/aws-lambda/types.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "src/adapter/aws-lambda/types.ts",
         "src/adapter/aws-lambda/handler.ts",
         "src/adapter/aws-lambda/conninfo.ts",
-        "src/adapter/lambda-edge/handler.ts",
-        "src/jsx/context.ts"
+        "src/middleware/basic-auth/index.ts",
+        "src/middleware/bearer-auth/index.ts"
+      ],
+      "top1Hit": true,
+      "top3Hit": true,
+      "top5Hit": true,
+      "sourceBytes": 2718972,
+      "rankedBytes": 40898,
+      "assumedAllSourceTokens": 679743,
+      "estimatedTop5Tokens": 10225
+    },
+    {
+      "slug": "sindresorhus/got",
+      "issue": 2459,
+      "scannedFiles": 120,
+      "medianRuntimeMs": 540.7,
+      "expected": [
+        "source/core/index.ts"
+      ],
+      "top5Paths": [
+        "source/core/index.ts",
+        "source/as-promise/index.ts",
+        "source/core/errors.ts",
+        "source/core/response.ts",
+        "source/core/diagnostics-channel.ts"
       ],
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
-      "sourceBytes": 2689631,
-      "rankedBytes": 42261,
-      "assumedAllSourceTokens": 672408,
-      "estimatedTop5Tokens": 10566
+      "sourceBytes": 1086555,
+      "rankedBytes": 103719,
+      "assumedAllSourceTokens": 271639,
+      "estimatedTop5Tokens": 25930
     }
   ]
 }
diff --git a/benchmarks/heldout/baseline-results.json b/benchmarks/heldout/baseline-results.json
index 6913ed5..3e775e9 100644
--- a/benchmarks/heldout/baseline-results.json
+++ b/benchmarks/heldout/baseline-results.json
@@ -346,7 +346,7 @@
         "cases": 12,
         "top1HitRate": 0.25,
         "top3HitRate": 0.417,
-        "top5HitRate": 0.667,
+        "top5HitRate": 0.75,
         "intervals95": {
           "top1": [
             0.089,
@@ -357,8 +357,8 @@
             0.68
           ],
           "top5": [
-            0.391,
-            0.862
+            0.468,
+            0.911
           ]
         }
       },
@@ -366,7 +366,7 @@
         "cases": 9,
         "top1HitRate": 0.222,
         "top3HitRate": 0.444,
-        "top5HitRate": 0.667,
+        "top5HitRate": 0.778,
         "intervals95": {
           "top1": [
             0.063,
@@ -377,8 +377,8 @@
             0.733
           ],
           "top5": [
-            0.354,
-            0.879
+            0.453,
+            0.937
           ]
         }
       },
@@ -592,41 +592,41 @@
     "fixmap": {
       "all": {
         "cases": 12,
-        "top1HitRate": 0.583,
+        "top1HitRate": 0.5,
         "top3HitRate": 0.667,
-        "top5HitRate": 0.75,
+        "top5HitRate": 0.667,
         "intervals95": {
           "top1": [
-            0.32,
-            0.807
+            0.254,
+            0.746
           ],
           "top3": [
             0.391,
             0.862
           ],
           "top5": [
-            0.468,
-            0.911
+            0.391,
+            0.862
           ]
         }
       },
       "unmentioned": {
         "cases": 9,
-        "top1HitRate": 0.444,
+        "top1HitRate": 0.333,
         "top3HitRate": 0.556,
-        "top5HitRate": 0.667,
+        "top5HitRate": 0.556,
         "intervals95": {
           "top1": [
-            0.189,
-            0.733
+            0.121,
+            0.646
           ],
           "top3": [
             0.267,
             0.811
           ],
           "top5": [
-            0.354,
-            0.879
+            0.267,
+            0.811
           ]
         }
       },
@@ -656,10 +656,10 @@
     "all": {
       "path-extraction:raw": {
         "top1": {
-          "aWins": 4,
+          "aWins": 3,
           "bWins": 0,
-          "discordant": 4,
-          "pValue": 0.125
+          "discordant": 3,
+          "pValue": 0.25
         },
         "top3": {
           "aWins": 5,
@@ -668,18 +668,18 @@
           "pValue": 0.0625
         },
         "top5": {
-          "aWins": 6,
+          "aWins": 5,
           "bWins": 0,
-          "discordant": 6,
-          "pValue": 0.0313
+          "discordant": 5,
+          "pValue": 0.0625
         }
       },
       "lexical-literal:code": {
         "top1": {
           "aWins": 5,
-          "bWins": 1,
-          "discordant": 6,
-          "pValue": 0.2188
+          "bWins": 2,
+          "discordant": 7,
+          "pValue": 0.4531
         },
         "top3": {
           "aWins": 4,
@@ -689,16 +689,16 @@
         },
         "top5": {
           "aWins": 2,
-          "bWins": 1,
-          "discordant": 3,
+          "bWins": 3,
+          "discordant": 5,
           "pValue": 1
         }
       },
       "bm25:code": {
         "top1": {
-          "aWins": 3,
-          "bWins": 2,
-          "discordant": 5,
+          "aWins": 4,
+          "bWins": 4,
+          "discordant": 8,
           "pValue": 1
         },
         "top3": {
@@ -709,19 +709,19 @@
         },
         "top5": {
           "aWins": 1,
-          "bWins": 3,
-          "discordant": 4,
-          "pValue": 0.625
+          "bWins": 4,
+          "discordant": 5,
+          "pValue": 0.375
         }
       }
     },
     "unmentioned": {
       "path-extraction:raw": {
         "top1": {
-          "aWins": 4,
+          "aWins": 3,
           "bWins": 0,
-          "discordant": 4,
-          "pValue": 0.125
+          "discordant": 3,
+          "pValue": 0.25
         },
         "top3": {
           "aWins": 5,
@@ -730,18 +730,18 @@
           "pValue": 0.0625
         },
         "top5": {
-          "aWins": 6,
+          "aWins": 5,
           "bWins": 0,
-          "discordant": 6,
-          "pValue": 0.0313
+          "discordant": 5,
+          "pValue": 0.0625
         }
       },
       "lexical-literal:code": {
         "top1": {
           "aWins": 3,
-          "bWins": 1,
-          "discordant": 4,
-          "pValue": 0.625
+          "bWins": 2,
+          "discordant": 5,
+          "pValue": 1
         },
         "top3": {
           "aWins": 2,
@@ -751,16 +751,16 @@
         },
         "top5": {
           "aWins": 1,
-          "bWins": 1,
-          "discordant": 2,
-          "pValue": 1
+          "bWins": 3,
+          "discordant": 4,
+          "pValue": 0.625
         }
       },
       "bm25:code": {
         "top1": {
-          "aWins": 2,
-          "bWins": 2,
-          "discordant": 4,
+          "aWins": 3,
+          "bWins": 4,
+          "discordant": 7,
           "pValue": 1
         },
         "top3": {
@@ -771,9 +771,9 @@
         },
         "top5": {
           "aWins": 0,
-          "bWins": 3,
-          "discordant": 3,
-          "pValue": 0.25
+          "bWins": 4,
+          "discordant": 4,
+          "pValue": 0.125
         }
       }
     }
@@ -789,111 +789,111 @@
       "mentionTier": "full-path",
       "arms": {
         "path-extraction:raw": {
-          "top5": [
+          "top5Paths": [
             "lib/document.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "path-extraction:source": {
-          "top5": [
+          "top5Paths": [
             "lib/document.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "path-extraction:code": {
-          "top5": [
+          "top5Paths": [
             "lib/document.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "lib/connection.js",
             "docs/schematypes.md",
             "lib/schemaType.js",
             "types/document.d.ts",
             "lib/types/subdocument.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "lib/connection.js",
             "docs/schematypes.md",
             "lib/schemaType.js",
             "types/document.d.ts",
             "lib/types/subdocument.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "lib/connection.js",
             "lib/schemaType.js",
             "types/document.d.ts",
             "lib/types/subdocument.js",
             "lib/mongoose.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "lib/types/subdocument.js",
             "types/document.d.ts",
             "docs/documents.md",
             "test/types.documentarray.test.js",
             "lib/helpers/symbols.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "lib/types/subdocument.js",
             "types/document.d.ts",
             "docs/documents.md",
             "lib/helpers/symbols.js",
             "docs/middleware.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "lib/types/subdocument.js",
             "types/document.d.ts",
             "lib/helpers/symbols.js",
             "lib/helpers/model/discriminator.js",
             "lib/schemaType.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "lib/document.js",
             "lib/helpers/setDefaultsOnInsert.js",
             "lib/helpers/update/modifiedPaths.js",
-            "lib/helpers/common.js",
-            "lib/helpers/update/updatedPathsByArrayFilter.js"
+            "lib/types/array/methods/index.js",
+            "lib/types/subdocument.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -908,105 +908,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "src/types/types-external.ts",
             "src/immer.ts",
             "src/plugins/arrayMethods.ts",
             "src/core/immerClass.ts",
             "website/docs/pitfalls.md"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "src/types/types-external.ts",
             "src/immer.ts",
             "src/plugins/arrayMethods.ts",
             "src/core/immerClass.ts",
             "website/docs/pitfalls.md"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "src/types/types-external.ts",
             "src/immer.ts",
             "src/plugins/arrayMethods.ts",
             "src/core/immerClass.ts",
             "src/core/proxy.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "src/types/types-external.ts",
             ".github/ISSUE_TEMPLATE/bug.md",
             "src/immer.ts",
             "src/core/immerClass.ts",
             "__tests__/produce.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "src/types/types-external.ts",
             ".github/ISSUE_TEMPLATE/bug.md",
             "src/immer.ts",
             "src/core/immerClass.ts",
             "website/docs/pitfalls.md"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "src/types/types-external.ts",
             "src/immer.ts",
             "src/core/immerClass.ts",
             "src/utils/errors.ts",
             "src/utils/common.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
-            "src/types/types-external.ts",
+          "top5Paths": [
             "src/immer.ts",
+            "src/types/types-external.ts",
             "src/plugins/patches.ts",
             "src/core/immerClass.ts",
             "src/core/proxy.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1021,106 +1021,106 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "docs/MockFunctionAPI.md",
             "website/versioned_docs/version-30.4/MockFunctionAPI.md",
             "website/versioned_docs/version-29.7/MockFunctionAPI.md",
             "website/versioned_docs/version-30.0/MockFunctionAPI.md",
             "packages/jest-mock/src/index.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "docs/MockFunctionAPI.md",
             "website/versioned_docs/version-30.4/MockFunctionAPI.md",
             "website/versioned_docs/version-29.7/MockFunctionAPI.md",
             "website/versioned_docs/version-30.0/MockFunctionAPI.md",
             "packages/jest-mock/src/index.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "packages/jest-mock/src/index.ts",
             "packages/jest-runtime/src/internals/EsmLoader.ts",
             "packages/jest-environment/src/index.ts",
             "packages/jest-config/src/normalize.ts",
             "packages/jest-resolve/src/resolver.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "website/versioned_docs/version-29.7/MockFunctionAPI.md",
             "website/versioned_docs/version-30.0/MockFunctionAPI.md",
             "website/versioned_docs/version-30.4/MockFunctionAPI.md",
             "docs/MockFunctionAPI.md",
             "packages/expect/src/types.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "website/versioned_docs/version-29.7/MockFunctionAPI.md",
             "website/versioned_docs/version-30.0/MockFunctionAPI.md",
             "website/versioned_docs/version-30.4/MockFunctionAPI.md",
             "docs/MockFunctionAPI.md",
             "packages/expect/src/types.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "packages/jest-mock/src/index.ts",
             "packages/expect/src/types.ts",
             "packages/jest-environment/src/index.ts",
             "packages/jest-haste-map/src/watchers/index.ts",
             "packages/jest-runtime/src/internals/EsmLoader.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
-            "packages/jest-config/src/readConfigFileAndSetRootDir.ts",
-            "packages/jest-config/src/resolveConfigPath.ts",
+          "top5Paths": [
             "packages/jest-core/src/TestScheduler.ts",
-            "packages/jest-mock/src/index.ts",
-            "packages/jest-resolve/src/resolver.ts"
+            "packages/jest-runner/src/runTest.ts",
+            "packages/jest-test-sequencer/src/index.ts",
+            "packages/jest-worker/src/workers/processChild.ts",
+            "packages/jest-worker/src/workers/threadChild.ts"
           ],
-          "top1": false,
-          "top3": false,
-          "top5Hit": true
+          "top1Hit": false,
+          "top3Hit": false,
+          "top5Hit": false
         }
       }
     },
@@ -1134,106 +1134,106 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "docs/src/guide/schema-builder.md",
             "docs/src/guide/index.md",
             "test/integration2/query/select/selects.spec.js",
             "test/unit/schema-builder/mysql.js",
             "docs/src/guide/migrations.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "docs/src/guide/schema-builder.md",
             "docs/src/guide/index.md",
             "docs/src/guide/migrations.md",
             "UPGRADING.md",
             "lib/query/querycompiler.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "lib/query/querycompiler.js",
             "lib/query/querybuilder.js",
             "lib/dialects/mssql/query/mssql-querycompiler.js",
             "lib/dialects/postgres/query/pg-querycompiler.js",
             "lib/schema/tablebuilder.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "docs/src/guide/schema-builder.md",
             "docs/src/guide/index.md",
             "lib/dialects/postgres/query/pg-querycompiler.js",
             "docs/src/faq/recipes.md",
             "lib/dialects/mssql/query/mssql-querycompiler.js"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "docs/src/guide/schema-builder.md",
             "docs/src/guide/index.md",
             "lib/dialects/postgres/query/pg-querycompiler.js",
             "docs/src/faq/recipes.md",
-            "UPGRADING.md"
+            "docs/src/guide/raw.md"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "lib/dialects/postgres/query/pg-querycompiler.js",
             "lib/dialects/mssql/query/mssql-querycompiler.js",
-            "lib/schema/tablecompiler.js",
             "lib/query/querycompiler.js",
+            "lib/schema/tablecompiler.js",
             "lib/dialects/postgres/index.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
-            "lib/dialects/postgres/query/pg-querycompiler.js",
-            "lib/dialects/mysql/query/mysql-querycompiler.js",
-            "lib/dialects/mysql/schema/mysql-tablecompiler.js",
-            "lib/schema/compiler.js",
-            "lib/dialects/postgres/schema/pg-columncompiler.js"
+          "top5Paths": [
+            "lib/dialects/postgres/index.js",
+            "lib/knex-builder/make-knex.js",
+            "lib/dialects/oracledb/index.js",
+            "lib/knex-builder/Knex.js",
+            "bin/cli.js"
           ],
-          "top1": true,
-          "top3": true,
-          "top5Hit": true
+          "top1Hit": false,
+          "top3Hit": false,
+          "top5Hit": false
         }
       }
     },
@@ -1247,109 +1247,109 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [
+          "top5Paths": [
             ".github/CODE_OF_CONDUCT.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [
+          "top5Paths": [
             ".github/CODE_OF_CONDUCT.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             ".github/CONTRIBUTING.md",
             "MAINTAINERS.md",
             ".github/ISSUE_TEMPLATE/01-bug.yml",
             "README.md",
             "PROJECT_CHARTER.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             ".github/CONTRIBUTING.md",
             "MAINTAINERS.md",
             ".github/ISSUE_TEMPLATE/01-bug.yml",
             "README.md",
             "PROJECT_CHARTER.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "lib/utils.cjs",
             "lib/mocha.cjs",
             "lib/cli/watch-run.cjs",
             "lib/cli/lookup-files.js",
             "lib/runner.cjs"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             ".github/ISSUE_TEMPLATE/01-bug.yml",
             "README.md",
             ".github/CONTRIBUTING.md",
             ".github/ISSUE_TEMPLATE/03-feature-request.yml",
             "PROJECT_CHARTER.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             ".github/ISSUE_TEMPLATE/01-bug.yml",
             ".github/CONTRIBUTING.md",
             "README.md",
-            "PROJECT_CHARTER.md",
-            "MAINTAINERS.md"
+            "MAINTAINERS.md",
+            "PROJECT_CHARTER.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "scripts/update-authors.cjs",
             "lib/cli/cli.js",
             "lib/nodejs/esm-utils.cjs",
             "lib/reporters/xunit.js",
             "lib/utils.cjs"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
-            "lib/errors.js",
+          "top5Paths": [
             "lib/reporters/xunit.js",
             "lib/mocha.cjs",
+            "lib/reporters/html.js",
             "lib/reporters/base.js",
-            "lib/reporters/html.js"
+            "lib/errors.js"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1364,105 +1364,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "CHANGELOG.md",
             "src/types/form.ts",
             "src/logic/createFormControl.ts",
             "reports/api-extractor.md.api.md",
             "reports/api-extractor.md"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "CHANGELOG.md",
             "src/types/form.ts",
             "src/logic/createFormControl.ts",
             "reports/api-extractor.md.api.md",
             "reports/api-extractor.md"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "src/types/form.ts",
             "src/logic/createFormControl.ts",
             "scripts/bench.ts",
             "src/useFieldArray.ts",
             "src/useForm.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "CHANGELOG.md",
             "scripts/bench.ts",
             "src/__tests__/useForm/setValue.test.tsx",
             "src/types/form.ts",
             "src/__tests__/useForm/subscribe.test.tsx"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "CHANGELOG.md",
             "scripts/bench.ts",
             "src/types/form.ts",
             "examples/README.md",
             "src/logic/createFormControl.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "scripts/bench.ts",
             "src/types/form.ts",
             "src/useForm.ts",
             "src/logic/createFormControl.ts",
             "src/useFormState.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "src/logic/createFormControl.ts",
-            "src/types/form.ts",
             "src/useController.ts",
-            "src/__typetest__/form-state-subscribe.test-d.ts",
+            "src/types/form.ts",
+            "app/src/useFormState.tsx",
             "src/useFormState.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1477,106 +1477,106 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "packages/engine.io/lib/server.ts",
             "packages/socket.io-client/dist/socket.io.esm.min.js",
             "packages/socket.io/client-dist/socket.io.esm.min.js",
             "packages/engine.io-client/dist/engine.io.esm.min.js",
             "packages/socket.io-client/CHANGELOG.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "packages/engine.io/lib/server.ts",
             "packages/socket.io-client/dist/socket.io.esm.min.js",
             "packages/socket.io/client-dist/socket.io.esm.min.js",
             "packages/engine.io-client/dist/engine.io.esm.min.js",
             "packages/socket.io-client/CHANGELOG.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "packages/engine.io/lib/server.ts",
             "packages/socket.io-client/dist/socket.io.esm.min.js",
             "packages/socket.io/client-dist/socket.io.esm.min.js",
             "packages/engine.io-client/dist/engine.io.esm.min.js",
             "packages/engine.io-client/lib/socket.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "packages/engine.io-client/README.md",
             "packages/engine.io/README.md",
             "packages/engine.io/lib/server.ts",
             "packages/engine.io-client/lib/transports/polling-xhr.ts",
             "packages/engine.io-client/lib/socket.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "bm25:source": {
-          "top5": [
-            "packages/engine.io/lib/server.ts",
+          "top5Paths": [
             "packages/engine.io-client/README.md",
+            "packages/engine.io/lib/server.ts",
             "packages/engine.io/README.md",
             "packages/engine.io-client/lib/socket.ts",
             "packages/engine.io-client/dist/engine.io.esm.min.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "packages/engine.io/lib/server.ts",
             "packages/engine.io-client/lib/socket.ts",
             "packages/engine.io-client/dist/engine.io.esm.min.js",
             "packages/engine.io-client/lib/transports/polling-xhr.ts",
             "packages/socket.io-client/dist/socket.io.esm.min.js"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "packages/engine.io-client/lib/transports/polling-xhr.ts",
-            "packages/engine.io-client/lib/transports/websocket.ts",
-            "packages/engine.io-client/lib/transports/polling-xhr.node.ts",
+            "packages/engine.io-client/lib/socket.ts",
+            "packages/engine.io-client/lib/transport.ts",
             "packages/engine.io-client/lib/transports/polling.ts",
-            "packages/socket.io-client/lib/url.ts"
+            "packages/engine.io-client/lib/transports/websocket.ts"
           ],
-          "top1": false,
-          "top3": false,
-          "top5Hit": false
+          "top1Hit": false,
+          "top3Hit": true,
+          "top5Hit": true
         }
       }
     },
@@ -1590,111 +1590,111 @@
       "mentionTier": "full-path",
       "arms": {
         "path-extraction:raw": {
-          "top5": [
+          "top5Paths": [
             "packages/svelte/src/internal/client/dom/blocks/boundary.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "path-extraction:source": {
-          "top5": [
+          "top5Paths": [
             "packages/svelte/src/internal/client/dom/blocks/boundary.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "path-extraction:code": {
-          "top5": [
+          "top5Paths": [
             "packages/svelte/src/internal/client/dom/blocks/boundary.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "documentation/docs/07-misc/07-v5-migration-guide.md",
             "packages/svelte/src/internal/server/renderer.js",
             "packages/svelte/messages/client-warnings/warnings.md",
             "documentation/docs/98-reference/.generated/client-warnings.md",
             "packages/svelte/src/internal/client/reactivity/batch.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "documentation/docs/07-misc/07-v5-migration-guide.md",
             "packages/svelte/src/internal/server/renderer.js",
             "packages/svelte/messages/client-warnings/warnings.md",
             "documentation/docs/98-reference/.generated/client-warnings.md",
             "packages/svelte/src/internal/client/reactivity/batch.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "packages/svelte/src/internal/server/renderer.js",
             "packages/svelte/src/internal/client/reactivity/batch.js",
             "packages/svelte/src/internal/client/errors.js",
             "packages/svelte/src/internal/client/dom/blocks/boundary.js",
             "packages/svelte/src/internal/client/reactivity/deriveds.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "documentation/docs/05-special-elements/01-svelte-boundary.md",
             "packages/svelte/src/internal/shared/errors.js",
             "CODE_OF_CONDUCT.md",
             "packages/svelte/tests/hydration/samples/raw-mismatch-static/_config.js",
             "packages/svelte/messages/client-errors/errors.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "packages/svelte/messages/client-errors/errors.md",
             "documentation/docs/98-reference/.generated/client-errors.md",
             "packages/svelte/messages/client-warnings/warnings.md",
             "documentation/docs/98-reference/.generated/client-warnings.md",
             "packages/svelte/src/internal/client/dom/blocks/boundary.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "packages/svelte/src/internal/client/dom/blocks/boundary.js",
             "packages/svelte/src/internal/client/errors.js",
             "packages/svelte/src/internal/server/renderer.js",
             "packages/svelte/src/internal/client/warnings.js",
             "packages/svelte/src/internal/shared/errors.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "packages/svelte/src/internal/client/dom/blocks/boundary.js",
+            "packages/svelte/scripts/check-treeshakeability.js",
             "packages/svelte/src/internal/client/dom/operations.js",
             "packages/svelte/src/internal/client/errors.js",
-            "packages/svelte/src/internal/client/warnings.js",
-            "packages/svelte/src/internal/client/dom/hydration.js"
+            "packages/svelte/src/internal/client/render.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -1709,105 +1709,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "docs/config/shared-options.md",
             "CONTRIBUTING.md",
             "packages/vite/src/node/utils.ts",
             "docs/guide/features.md",
             "packages/vite/src/node/build.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "docs/config/shared-options.md",
             "CONTRIBUTING.md",
             "packages/vite/src/node/utils.ts",
             "docs/guide/features.md",
             "packages/vite/src/node/build.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "packages/vite/src/node/utils.ts",
             "packages/vite/src/node/build.ts",
             "packages/vite/src/node/optimizer/index.ts",
             "packages/vite/src/node/server/index.ts",
             "packages/create-vite/src/index.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "CONTRIBUTING.md",
             "docs/guide/static-deploy.md",
             "docs/guide/index.md",
             ".github/ISSUE_TEMPLATE/bug_report.yml",
             "packages/create-vite/README.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "CONTRIBUTING.md",
             "docs/guide/static-deploy.md",
             "docs/guide/index.md",
             ".github/ISSUE_TEMPLATE/bug_report.yml",
             "packages/create-vite/README.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "packages/create-vite/src/index.ts",
             "packages/vite/src/node/utils.ts",
             "packages/vite/src/node/build.ts",
             "packages/vite/src/node/server/bundledDev.ts",
             "packages/vite/src/node/server/transformRequest.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
-            "packages/vite/src/types/commonjs.d.ts",
-            ".github/ISSUE_TEMPLATE/bug_report.yml",
+          "top5Paths": [
+            "packages/create-vite/template-vue-ts/src/App.vue",
+            "packages/create-vite/template-vue/src/App.vue",
+            "packages/vite/types/metadata.d.ts",
             "packages/vite/src/node/optimizer/rolldownDepPlugin.ts",
-            "packages/vite/src/node/plugins/worker.ts",
             "packages/vite/src/node/plugins/workerImportMetaUrl.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         }
       }
@@ -1822,105 +1822,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             ".github/contributing.md",
             "packages/compiler-sfc/src/script/resolveType.ts",
             "packages/runtime-core/src/component.ts",
             "packages/compiler-sfc/src/compileScript.ts",
             "changelogs/CHANGELOG-3.1.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             ".github/contributing.md",
             "packages/compiler-sfc/src/script/resolveType.ts",
             "packages/runtime-core/src/component.ts",
             "packages/compiler-sfc/src/compileScript.ts",
             "changelogs/CHANGELOG-3.1.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "packages/compiler-sfc/src/script/resolveType.ts",
             "packages/runtime-core/src/component.ts",
             "packages/compiler-sfc/src/compileScript.ts",
             "packages/runtime-dom/src/jsx.ts",
-            "packages-private/dts-test/defineComponent.test-d.tsx"
+            "packages/runtime-dom/src/index.ts"
           ],
-          "top1": false,
-          "top3": false,
-          "top5Hit": false
+          "top1Hit": false,
+          "top3Hit": false,
+          "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             ".github/ISSUE_TEMPLATE/bug_report.yml",
             ".github/contributing.md",
             "packages/compiler-sfc/README.md",
             "changelogs/CHANGELOG-3.1.md",
             "packages/vue-compat/README.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             ".github/ISSUE_TEMPLATE/bug_report.yml",
             ".github/contributing.md",
             "packages/compiler-sfc/README.md",
             "changelogs/CHANGELOG-3.1.md",
             "packages/vue-compat/README.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "packages/runtime-dom/src/index.ts",
             "scripts/release.js",
             "packages/runtime-core/src/apiSetupHelpers.ts",
             "packages/runtime-dom/src/jsx.ts",
             "packages/reactivity/src/reactive.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "tsconfig.json",
-            "packages-private/dts-built-test/tsconfig.json",
             "packages-private/tsconfig.json",
+            "packages-private/dts-built-test/tsconfig.json",
             "packages-private/vite-debug/tsconfig.json",
-            "packages-private/dts-test/ref.test-d.ts"
+            "packages/reactivity/src/ref.ts"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         }
       }
@@ -1935,105 +1935,105 @@
       "mentionTier": "none",
       "arms": {
         "path-extraction:raw": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:source": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "path-extraction:code": {
-          "top5": [],
-          "top1": false,
-          "top3": false,
+          "top5Paths": [],
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "docs/transports.md",
             "README.md",
             "CHANGELOG.md",
             "UPGRADE-3.0.md",
             "lib/winston/logger.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "docs/transports.md",
             "README.md",
             "CHANGELOG.md",
             "UPGRADE-3.0.md",
             "lib/winston/logger.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "lib/winston/logger.js",
             "lib/winston/transports/file.js",
             "lib/winston.js",
             "index.d.ts",
             "lib/winston/exception-handler.js"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             ".github/ISSUE_TEMPLATE/bug_report.yml",
             "lib/winston/common.js",
             "docs/transports.md",
             "test/unit/winston/logger-legacy.test.js",
             "UPGRADE-3.0.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             ".github/ISSUE_TEMPLATE/bug_report.yml",
             "lib/winston/common.js",
             "docs/transports.md",
             "README.md",
             "UPGRADE-3.0.md"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": false
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "lib/winston/common.js",
             "lib/winston.js",
             "lib/winston/logger.js",
             "lib/winston/transports/file.js",
             "lib/winston/exception-handler.js"
           ],
-          "top1": false,
-          "top3": false,
+          "top1Hit": false,
+          "top3Hit": false,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "lib/winston/transports/file.js",
+            "lib/winston/transports/http.js",
             "lib/winston/tail-file.js",
             "lib/winston/transports/console.js",
-            "lib/winston/transports/http.js",
-            "lib/winston.js"
+            "lib/winston/logger.js"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
@@ -2048,111 +2048,111 @@
       "mentionTier": "full-path",
       "arms": {
         "path-extraction:raw": {
-          "top5": [
+          "top5Paths": [
             "lib/utils/apply-extends.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "path-extraction:source": {
-          "top5": [
+          "top5Paths": [
             "lib/utils/apply-extends.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "path-extraction:code": {
-          "top5": [
+          "top5Paths": [
             "lib/utils/apply-extends.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:raw": {
-          "top5": [
+          "top5Paths": [
             "docs/api.md",
             "docs/advanced.md",
             "lib/utils/apply-extends.ts",
             "test/validation.mjs",
             "lib/command.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:source": {
-          "top5": [
+          "top5Paths": [
             "docs/api.md",
             "docs/advanced.md",
             "lib/utils/apply-extends.ts",
             "lib/command.ts",
             "lib/typings/yargs-parser-types.ts"
           ],
-          "top1": false,
-          "top3": true,
+          "top1Hit": false,
+          "top3Hit": true,
           "top5Hit": true
         },
         "lexical-literal:code": {
-          "top5": [
+          "top5Paths": [
             "lib/utils/apply-extends.ts",
             "lib/command.ts",
             "lib/typings/yargs-parser-types.ts",
             "lib/validation.ts",
             "lib/completion.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:raw": {
-          "top5": [
+          "top5Paths": [
             "lib/utils/apply-extends.ts",
             "lib/typings/yargs-parser-types.ts",
             "lib/utils/levenshtein.ts",
             "docs/api.md",
             "helpers/helpers.mjs"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:source": {
-          "top5": [
+          "top5Paths": [
             "lib/utils/apply-extends.ts",
             "lib/typings/yargs-parser-types.ts",
             "docs/api.md",
             "lib/utils/levenshtein.ts",
             "docs/advanced.md"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "bm25:code": {
-          "top5": [
+          "top5Paths": [
             "lib/utils/apply-extends.ts",
             "lib/typings/yargs-parser-types.ts",
             "lib/utils/levenshtein.ts",
             "helpers/helpers.mjs",
             "lib/command.ts"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         },
         "fixmap": {
-          "top5": [
+          "top5Paths": [
             "lib/utils/apply-extends.ts",
             "lib/command.ts",
             "lib/completion.ts",
-            "lib/typings/yargs-parser-types.ts",
-            "lib/usage.ts"
+            "lib/validation.ts",
+            "helpers/helpers.mjs"
           ],
-          "top1": true,
-          "top3": true,
+          "top1Hit": true,
+          "top3Hit": true,
           "top5Hit": true
         }
       }
diff --git a/benchmarks/heldout/results.json b/benchmarks/heldout/results.json
index 6c704a4..ae8f803 100644
--- a/benchmarks/heldout/results.json
+++ b/benchmarks/heldout/results.json
@@ -1,20 +1,20 @@
 {
   "cases": 12,
-  "top1HitRate": 0.583,
+  "top1HitRate": 0.5,
   "top3HitRate": 0.667,
-  "top5HitRate": 0.75,
+  "top5HitRate": 0.667,
   "intervals95": {
     "top1": [
-      0.32,
-      0.807
+      0.254,
+      0.746
     ],
     "top3": [
       0.391,
       0.862
     ],
     "top5": [
-      0.468,
-      0.911
+      0.391,
+      0.862
     ]
   },
   "misleadingTopResult": {
@@ -22,8 +22,8 @@
     "of": 12,
     "rate": 0.167,
     "slugs": [
-      "jestjs/jest",
-      "mochajs/mocha"
+      "immerjs/immer",
+      "socketio/socket.io"
     ]
   },
   "calibration": [
@@ -40,11 +40,11 @@
     {
       "confidence": "medium",
       "cases": 7,
-      "top1Correct": 4,
-      "top1Accuracy": 0.571,
+      "top1Correct": 3,
+      "top1Accuracy": 0.429,
       "interval95": [
-        0.25,
-        0.842
+        0.158,
+        0.75
       ]
     },
     {
@@ -61,21 +61,21 @@
   "cohorts": {
     "all": {
       "cases": 12,
-      "top1HitRate": 0.583,
+      "top1HitRate": 0.5,
       "top3HitRate": 0.667,
-      "top5HitRate": 0.75,
+      "top5HitRate": 0.667,
       "intervals95": {
         "top1": [
-          0.32,
-          0.807
+          0.254,
+          0.746
         ],
         "top3": [
           0.391,
           0.862
         ],
         "top5": [
-          0.468,
-          0.911
+          0.391,
+          0.862
         ]
       },
       "slugs": [
@@ -95,21 +95,21 @@
     },
     "unmentioned": {
       "cases": 9,
-      "top1HitRate": 0.444,
+      "top1HitRate": 0.333,
       "top3HitRate": 0.556,
-      "top5HitRate": 0.667,
+      "top5HitRate": 0.556,
       "intervals95": {
         "top1": [
-          0.189,
-          0.733
+          0.121,
+          0.646
         ],
         "top3": [
           0.267,
           0.811
         ],
         "top5": [
-          0.354,
-          0.879
+          0.267,
+          0.811
         ]
       },
       "slugs": [
@@ -151,9 +151,16 @@
     }
   },
   "floors": {
-    "top1": 0.3,
-    "top3": 0.5,
-    "top5": 0.5
+    "all": {
+      "top1": 0.5,
+      "top3": 0.583,
+      "top5": 0.667
+    },
+    "unmentioned": {
+      "top1": 0.333,
+      "top3": 0.444,
+      "top5": 0.556
+    }
   },
   "results": [
     {
@@ -162,16 +169,16 @@
       "expected": [
         "lib/document.js"
       ],
-      "top5": [
+      "top5Paths": [
         "lib/document.js",
         "lib/helpers/setDefaultsOnInsert.js",
         "lib/helpers/update/modifiedPaths.js",
-        "lib/helpers/common.js",
-        "lib/helpers/update/updatedPathsByArrayFilter.js"
+        "lib/types/array/methods/index.js",
+        "lib/types/subdocument.js"
       ],
       "topConfidence": "medium",
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": true,
       "mentionTier": "full-path",
@@ -190,16 +197,16 @@
       "expected": [
         "src/types/types-external.ts"
       ],
-      "top5": [
-        "src/types/types-external.ts",
+      "top5Paths": [
         "src/immer.ts",
+        "src/types/types-external.ts",
         "src/plugins/patches.ts",
         "src/core/immerClass.ts",
         "src/core/proxy.ts"
       ],
       "topConfidence": "medium",
-      "top1": true,
-      "top3": true,
+      "top1Hit": false,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -211,17 +218,17 @@
       "expected": [
         "packages/jest-mock/src/index.ts"
       ],
-      "top5": [
-        "packages/jest-config/src/readConfigFileAndSetRootDir.ts",
-        "packages/jest-config/src/resolveConfigPath.ts",
+      "top5Paths": [
         "packages/jest-core/src/TestScheduler.ts",
-        "packages/jest-mock/src/index.ts",
-        "packages/jest-resolve/src/resolver.ts"
+        "packages/jest-runner/src/runTest.ts",
+        "packages/jest-test-sequencer/src/index.ts",
+        "packages/jest-worker/src/workers/processChild.ts",
+        "packages/jest-worker/src/workers/threadChild.ts"
       ],
       "topConfidence": "medium",
-      "top1": false,
-      "top3": false,
-      "top5Hit": true,
+      "top1Hit": false,
+      "top3Hit": false,
+      "top5Hit": false,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
       "mentionEvidence": []
@@ -232,17 +239,17 @@
       "expected": [
         "lib/dialects/postgres/query/pg-querycompiler.js"
       ],
-      "top5": [
-        "lib/dialects/postgres/query/pg-querycompiler.js",
-        "lib/dialects/mysql/query/mysql-querycompiler.js",
-        "lib/dialects/mysql/schema/mysql-tablecompiler.js",
-        "lib/schema/compiler.js",
-        "lib/dialects/postgres/schema/pg-columncompiler.js"
+      "top5Paths": [
+        "lib/dialects/postgres/index.js",
+        "lib/knex-builder/make-knex.js",
+        "lib/dialects/oracledb/index.js",
+        "lib/knex-builder/Knex.js",
+        "bin/cli.js"
       ],
       "topConfidence": "medium",
-      "top1": true,
-      "top3": true,
-      "top5Hit": true,
+      "top1Hit": false,
+      "top3Hit": false,
+      "top5Hit": false,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
       "mentionEvidence": []
@@ -253,16 +260,16 @@
       "expected": [
         "lib/reporters/xunit.js"
       ],
-      "top5": [
-        "lib/errors.js",
+      "top5Paths": [
         "lib/reporters/xunit.js",
         "lib/mocha.cjs",
+        "lib/reporters/html.js",
         "lib/reporters/base.js",
-        "lib/reporters/html.js"
+        "lib/errors.js"
       ],
       "topConfidence": "medium",
-      "top1": false,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -274,16 +281,16 @@
       "expected": [
         "src/logic/createFormControl.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "src/logic/createFormControl.ts",
-        "src/types/form.ts",
         "src/useController.ts",
-        "src/useFormState.ts",
-        "src/useForm.ts"
+        "src/types/form.ts",
+        "app/src/useFormState.tsx",
+        "src/useFormState.ts"
       ],
       "topConfidence": "medium",
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -295,17 +302,17 @@
       "expected": [
         "packages/engine.io-client/lib/socket.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "packages/engine.io-client/lib/transports/polling-xhr.ts",
-        "packages/engine.io-client/lib/transports/websocket.ts",
-        "packages/engine.io-client/lib/transports/polling-xhr.node.ts",
+        "packages/engine.io-client/lib/socket.ts",
+        "packages/engine.io-client/lib/transport.ts",
         "packages/engine.io-client/lib/transports/polling.ts",
-        "packages/socket.io-client/lib/url.ts"
+        "packages/engine.io-client/lib/transports/websocket.ts"
       ],
       "topConfidence": "medium",
-      "top1": false,
-      "top3": false,
-      "top5Hit": false,
+      "top1Hit": false,
+      "top3Hit": true,
+      "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
       "mentionEvidence": []
@@ -316,16 +323,16 @@
       "expected": [
         "packages/svelte/src/internal/client/dom/blocks/boundary.js"
       ],
-      "top5": [
+      "top5Paths": [
         "packages/svelte/src/internal/client/dom/blocks/boundary.js",
+        "packages/svelte/scripts/check-treeshakeability.js",
         "packages/svelte/src/internal/client/dom/operations.js",
         "packages/svelte/src/internal/client/errors.js",
-        "packages/svelte/src/internal/client/warnings.js",
-        "packages/svelte/src/internal/client/dom/hydration.js"
+        "packages/svelte/src/internal/client/render.js"
       ],
       "topConfidence": "high",
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": true,
       "mentionTier": "full-path",
@@ -344,16 +351,16 @@
       "expected": [
         "packages/vite/src/node/server/bundledDev.ts"
       ],
-      "top5": [
-        "packages/vite/src/types/commonjs.d.ts",
-        ".github/ISSUE_TEMPLATE/bug_report.yml",
+      "top5Paths": [
+        "packages/create-vite/template-vue-ts/src/App.vue",
+        "packages/create-vite/template-vue/src/App.vue",
+        "packages/vite/types/metadata.d.ts",
         "packages/vite/src/node/optimizer/rolldownDepPlugin.ts",
-        "packages/vite/src/node/plugins/worker.ts",
         "packages/vite/src/node/plugins/workerImportMetaUrl.ts"
       ],
-      "topConfidence": "low",
-      "top1": false,
-      "top3": false,
+      "topConfidence": "high",
+      "top1Hit": false,
+      "top3Hit": false,
       "top5Hit": false,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -365,16 +372,16 @@
       "expected": [
         "packages/runtime-dom/src/index.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "tsconfig.json",
-        "packages-private/dts-built-test/tsconfig.json",
         "packages-private/tsconfig.json",
+        "packages-private/dts-built-test/tsconfig.json",
         "packages-private/vite-debug/tsconfig.json",
         "packages/reactivity/src/ref.ts"
       ],
-      "topConfidence": "high",
-      "top1": false,
-      "top3": false,
+      "topConfidence": "low",
+      "top1Hit": false,
+      "top3Hit": false,
       "top5Hit": false,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -386,16 +393,16 @@
       "expected": [
         "lib/winston/transports/file.js"
       ],
-      "top5": [
+      "top5Paths": [
         "lib/winston/transports/file.js",
+        "lib/winston/transports/http.js",
         "lib/winston/tail-file.js",
         "lib/winston/transports/console.js",
-        "lib/winston/transports/http.js",
-        "lib/winston.js"
+        "lib/winston/logger.js"
       ],
       "topConfidence": "low",
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": false,
       "mentionTier": "none",
@@ -407,16 +414,16 @@
       "expected": [
         "lib/utils/apply-extends.ts"
       ],
-      "top5": [
+      "top5Paths": [
         "lib/utils/apply-extends.ts",
         "lib/command.ts",
         "lib/completion.ts",
-        "lib/typings/yargs-parser-types.ts",
-        "lib/usage.ts"
+        "lib/validation.ts",
+        "helpers/helpers.mjs"
       ],
       "topConfidence": "high",
-      "top1": true,
-      "top3": true,
+      "top1Hit": true,
+      "top3Hit": true,
       "top5Hit": true,
       "mentionsExpectedPath": true,
       "mentionTier": "full-path",
diff --git a/docs/BENCHMARKS.md b/docs/BENCHMARKS.md
index a3d82d5..c421be8 100644
--- a/docs/BENCHMARKS.md
+++ b/docs/BENCHMARKS.md
@@ -89,7 +89,7 @@ Both keyword arms are case-insensitive and expand camelCase, which favours the b
 | --- | ---: | ---: | ---: |
 | `path-extraction` (any policy) | 0.0% | 0.0% | 0.0% |
 | `lexical-literal:raw` | 11.1% | 22.2% | 33.3% |
-| `lexical-literal:code` | 22.2% | 44.4% | 66.7% |
+| `lexical-literal:code` | 22.2% | 44.4% | 77.8% |
 | `bm25:raw` | 11.1% | 22.2% | 33.3% |
 | `bm25:source` | 11.1% | 22.2% | 44.4% |
 | **`bm25:code`** | **44.4%** | **55.6%** | **100%** |
diff --git a/docs/assets/fixmap-benchmark.svg b/docs/assets/fixmap-benchmark.svg
index ec44dc7..641764a 100644
--- a/docs/assets/fixmap-benchmark.svg
+++ b/docs/assets/fixmap-benchmark.svg
@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630" role="img" aria-labelledby="title description">
   <title id="title">FixMap benchmark</title>
-  <desc id="description">On 9 held-out tasks that did not name the fixing file, FixMap and BM25 both ranked it in the top three for 5 cases. BM25 ranked it in the top five for 9, compared with 6 for FixMap.</desc>
+  <desc id="description">On 9 held-out tasks that did not name the fixing file, FixMap and BM25 both ranked it in the top three for 5 cases. BM25 ranked it in the top five for 9, compared with 5 for FixMap.</desc>
   <defs>
     <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
       <stop offset="0" stop-color="#07120f"/>
@@ -20,7 +20,7 @@
   <text x="108" y="232" fill="#72f0b8" font-family="Segoe UI, Arial, sans-serif" font-size="16" font-weight="700">FIXMAP · UNMENTIONED</text>
   <text x="108" y="287" fill="#f2f7f5" font-family="Segoe UI, Arial, sans-serif" font-size="48" font-weight="750">5/9</text>
   <text x="108" y="319" fill="#b8cdc5" font-family="Segoe UI, Arial, sans-serif" font-size="17">top-3 on held-out tasks</text>
-  <text x="108" y="349" fill="#72f0b8" font-family="Segoe UI, Arial, sans-serif" font-size="15">Top-1 4/9 · Top-5 6/9</text>
+  <text x="108" y="349" fill="#72f0b8" font-family="Segoe UI, Arial, sans-serif" font-size="15">Top-1 3/9 · Top-5 5/9</text>
 
   <rect x="422" y="194" width="316" height="176" rx="22" fill="#132a23" stroke="#2d574a"/>
   <text x="448" y="232" fill="#9db9af" font-family="Segoe UI, Arial, sans-serif" font-size="16">BM25 · SAME CORPUS</text>
@@ -30,7 +30,7 @@
 
   <rect x="762" y="194" width="316" height="176" rx="22" fill="#132a23" stroke="#2d574a"/>
   <text x="788" y="232" fill="#9db9af" font-family="Segoe UI, Arial, sans-serif" font-size="16">MEASURED RUNTIME</text>
-  <text x="788" y="287" fill="#f2f7f5" font-family="Segoe UI, Arial, sans-serif" font-size="48" font-weight="750">1.75s</text>
+  <text x="788" y="287" fill="#f2f7f5" font-family="Segoe UI, Arial, sans-serif" font-size="48" font-weight="750">1.30s</text>
   <text x="788" y="319" fill="#b8cdc5" font-family="Segoe UI, Arial, sans-serif" font-size="17">median scan + rank</text>
   <text x="788" y="349" fill="#9db9af" font-family="Segoe UI, Arial, sans-serif" font-size="15">3 warm runs per pinned repository</text>
 
diff --git a/docs/assets/fixmap-cli-demo.svg b/docs/assets/fixmap-cli-demo.svg
index f35cd31..ebbf4d0 100644
--- a/docs/assets/fixmap-cli-demo.svg
+++ b/docs/assets/fixmap-cli-demo.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="860" height="851" viewBox="0 0 860 851" role="img" aria-label="Animated terminal recording: one fixmap plan command produces ranked context files, a test route, an authentication risk note, and empty-state diagnostics.">
+<svg xmlns="http://www.w3.org/2000/svg" width="860" height="830" viewBox="0 0 860 830" role="img" aria-label="Animated terminal recording: one fixmap plan command produces ranked context files, a test route, an authentication risk note, and empty-state diagnostics.">
   <style>
     text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace; font-size: 13.5px; white-space: pre; }
     .l { opacity: 0; animation: fadein 0.45s ease-out forwards; }
@@ -7,7 +7,7 @@
     @keyframes blink { 0%, 100% { opacity: 1; } 50% { opacity: 0; } }
     @media (prefers-reduced-motion: reduce) { .l { animation: none; opacity: 1; } .cursor { animation: none; opacity: 0; } }
   </style>
-  <rect width="860" height="851" rx="10" fill="#0d1117" stroke="#30363d"/>
+  <rect width="860" height="830" rx="10" fill="#0d1117" stroke="#30363d"/>
   <rect width="860" height="44" rx="10" fill="#161b22"/>
   <rect y="32" width="860" height="12" fill="#161b22"/>
   <circle cx="24" cy="22" r="6" fill="#ff5f57"/>
@@ -16,27 +16,26 @@
   <text x="430" y="26.5" text-anchor="middle" fill="#8b949e">fixmap plan — examples/tiny-auth-app</text>
   <rect class="cursor" x="526.1999999999999" y="67" width="8" height="15" fill="#74f0ba"/>
   <text class="l" style="animation-delay:0.40s" x="22" y="79" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">$ </tspan><tspan>npx @aryam/fixmap plan --issue "password reset emails fail"</tspan></text>
-  <text class="l" style="animation-delay:2.20s" x="22" y="121" fill="#e6edf3"><tspan>FixMap found 1 context file and generated 2 test routes.</tspan></text>
+  <text class="l" style="animation-delay:2.20s" x="22" y="121" fill="#e6edf3"><tspan>FixMap found 1 context file and generated 1 test route.</tspan></text>
   <text class="l" style="animation-delay:3.35s" x="22" y="163" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">## Context Files</tspan></text>
-  <text class="l" style="animation-delay:3.60s" x="22" y="205" fill="#e6edf3"><tspan>- </tspan><tspan fill="#79c0ff">src/auth/reset-password.ts</tspan><tspan> (high confidence, score 24): path matches task terms: reset,</tspan></text>
-  <text class="l" style="animation-delay:3.85s" x="22" y="226" fill="#e6edf3"><tspan>    password; content matches task terms: reset, password, email; defines symbols matching</tspan></text>
-  <text class="l" style="animation-delay:4.10s" x="22" y="247" fill="#e6edf3"><tspan>    task terms: ResetPasswordRequest, buildResetPasswordEmail; auth-related task signal</tspan></text>
-  <text class="l" style="animation-delay:5.25s" x="22" y="289" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">## Test Routes</tspan></text>
-  <text class="l" style="animation-delay:5.50s" x="22" y="331" fill="#e6edf3"><tspan>- </tspan><tspan fill="#79c0ff">npm run test</tspan><tspan>: repository root script named test. Related:</tspan></text>
-  <text class="l" style="animation-delay:5.75s" x="22" y="352" fill="#e6edf3"><tspan>    </tspan><tspan fill="#79c0ff">test/auth/reset-password.test.ts</tspan><tspan>.</tspan></text>
-  <text class="l" style="animation-delay:6.00s" x="22" y="373" fill="#e6edf3"><tspan>- </tspan><tspan fill="#79c0ff">npm run typecheck</tspan><tspan>: repository root script named typecheck. Related:</tspan></text>
-  <text class="l" style="animation-delay:6.25s" x="22" y="394" fill="#e6edf3"><tspan>    </tspan><tspan fill="#79c0ff">src/auth/reset-password.ts</tspan><tspan>.</tspan></text>
-  <text class="l" style="animation-delay:7.40s" x="22" y="436" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">## Risk Map</tspan></text>
-  <text class="l" style="animation-delay:7.65s" x="22" y="478" fill="#e6edf3"><tspan>- </tspan><tspan fill="#8b949e" font-weight="bold">low</tspan><tspan> authentication: ranked files touch authentication; review this area before</tspan></text>
-  <text class="l" style="animation-delay:7.90s" x="22" y="499" fill="#e6edf3"><tspan>    editing, but no diff evidence is available yet</tspan></text>
-  <text class="l" style="animation-delay:9.05s" x="22" y="541" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">## Changed Files</tspan></text>
-  <text class="l" style="animation-delay:9.30s" x="22" y="583" fill="#8b949e"><tspan>- None found</tspan></text>
-  <text class="l" style="animation-delay:10.45s" x="22" y="625" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">## Analysis</tspan></text>
-  <text class="l" style="animation-delay:10.70s" x="22" y="667" fill="#e6edf3"><tspan>- Task grounding: **descriptive**</tspan></text>
-  <text class="l" style="animation-delay:10.95s" x="22" y="688" fill="#e6edf3"><tspan>- Repository scan: **complete**</tspan></text>
-  <text class="l" style="animation-delay:11.20s" x="22" y="709" fill="#e6edf3"><tspan>- Ranking shape: **separated**</tspan></text>
-  <text class="l" style="animation-delay:11.45s" x="22" y="730" fill="#e6edf3"><tspan>- Next action: Inspect src/auth/reset-password.ts and its routed tests before editing.</tspan></text>
-  <text class="l" style="animation-delay:12.60s" x="22" y="772" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">## Diagnostics</tspan></text>
-  <text class="l" style="animation-delay:12.85s" x="22" y="814" fill="#e6edf3"><tspan>- **info** Repository scan caching was bypassed by --no-cache; this report used a fresh</tspan></text>
-  <text class="l" style="animation-delay:13.10s" x="22" y="835" fill="#e6edf3"><tspan>    scan.</tspan></text>
+  <text class="l" style="animation-delay:3.60s" x="22" y="205" fill="#e6edf3"><tspan>- </tspan><tspan fill="#79c0ff">src/auth/reset-password.ts</tspan><tspan> (medium confidence, score 28): path matches task terms:</tspan></text>
+  <text class="l" style="animation-delay:3.85s" x="22" y="226" fill="#e6edf3"><tspan>    reset, password; multiple task terms converge in the file path; content matches task</tspan></text>
+  <text class="l" style="animation-delay:4.10s" x="22" y="247" fill="#e6edf3"><tspan>    terms: reset, password, email; defines symbols matching task terms:</tspan></text>
+  <text class="l" style="animation-delay:4.35s" x="22" y="268" fill="#e6edf3"><tspan>    ResetPasswordRequest, buildResetPasswordEmail; auth-related task signal</tspan></text>
+  <text class="l" style="animation-delay:5.50s" x="22" y="310" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">## Test Routes</tspan></text>
+  <text class="l" style="animation-delay:5.75s" x="22" y="352" fill="#e6edf3"><tspan>- </tspan><tspan fill="#79c0ff">npm run test</tspan><tspan>: repository root script named test. Related:</tspan></text>
+  <text class="l" style="animation-delay:6.00s" x="22" y="373" fill="#e6edf3"><tspan>    </tspan><tspan fill="#79c0ff">test/auth/reset-password.test.ts</tspan><tspan>.</tspan></text>
+  <text class="l" style="animation-delay:7.15s" x="22" y="415" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">## Risk Map</tspan></text>
+  <text class="l" style="animation-delay:7.40s" x="22" y="457" fill="#e6edf3"><tspan>- </tspan><tspan fill="#8b949e" font-weight="bold">low</tspan><tspan> authentication: ranked files touch authentication; review this area before</tspan></text>
+  <text class="l" style="animation-delay:7.65s" x="22" y="478" fill="#e6edf3"><tspan>    editing, but no diff evidence is available yet</tspan></text>
+  <text class="l" style="animation-delay:8.80s" x="22" y="520" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">## Changed Files</tspan></text>
+  <text class="l" style="animation-delay:9.05s" x="22" y="562" fill="#8b949e"><tspan>- None found</tspan></text>
+  <text class="l" style="animation-delay:10.20s" x="22" y="604" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">## Analysis</tspan></text>
+  <text class="l" style="animation-delay:10.45s" x="22" y="646" fill="#e6edf3"><tspan>- Task grounding: **descriptive**</tspan></text>
+  <text class="l" style="animation-delay:10.70s" x="22" y="667" fill="#e6edf3"><tspan>- Repository scan: **complete**</tspan></text>
+  <text class="l" style="animation-delay:10.95s" x="22" y="688" fill="#e6edf3"><tspan>- Ranking shape: **separated**</tspan></text>
+  <text class="l" style="animation-delay:11.20s" x="22" y="709" fill="#e6edf3"><tspan>- Next action: Inspect src/auth/reset-password.ts and its routed tests before editing.</tspan></text>
+  <text class="l" style="animation-delay:12.35s" x="22" y="751" fill="#e6edf3"><tspan fill="#74f0ba" font-weight="bold">## Diagnostics</tspan></text>
+  <text class="l" style="animation-delay:12.60s" x="22" y="793" fill="#e6edf3"><tspan>- **info** Repository scan caching was bypassed by --no-cache; this report used a fresh</tspan></text>
+  <text class="l" style="animation-delay:12.85s" x="22" y="814" fill="#e6edf3"><tspan>    scan.</tspan></text>
 </svg>
diff --git a/docs/releases/v0.8.9-issue-verification.md b/docs/releases/v0.8.9-issue-verification.md
new file mode 100644
index 0000000..fbfd1d7
--- /dev/null
+++ b/docs/releases/v0.8.9-issue-verification.md
@@ -0,0 +1,187 @@
+# FixMap v0.8.9 issue verification
+
+This release ledger maps every open implementation issue in the reviewed range to its fix and proof. Issue #542 and #599 were not open during the final refresh. An issue is closed only after the released public artifacts are verified.
+
+## Ranking, signal extraction, and CLI correctness sweep (#500–#525)
+
+| Issue | Local resolution | Verification |
+| --- | --- | --- |
+| #500 | Go/Swift `func` and Kotlin `fun` declarations receive definition-site evidence. | Numbered regression in `rank.test.ts`. |
+| #501 | Changed files keep their score boost but no longer bypass vague, unresolved, incomplete-scan, or clustering confidence caps. | Numbered vague-task regression in `rank.test.ts`. |
+| #502 | Absolute file mentions are accepted only when they resolve beneath the scanned repository root. | Numbered inside/outside-root regressions in `rank.test.ts`. |
+| #503 | Bare “copy” no longer reclassifies clipboard or implementation work as documentation. | Numbered clipboard regression in `rank.test.ts`. |
+| #504 | Maintained source under `benchmarks/` remains rankable without benchmark wording. | Numbered regression in `rank.test.ts`. |
+| #505 | `sample-repo` is no longer a repository-global presentation filename heuristic. | Numbered score-parity regression in `rank.test.ts`. |
+| #506 | Descriptive prose can seed bounded import proximity from its strongest semantic matches. | Numbered prose-only regression in `rank.test.ts`. |
+| #507 | UI vocabulary no longer suppresses task-matched definition evidence. | Numbered form-validation regression in `rank.test.ts`. |
+| #508 | Exact-fragment occurrence counts are computed once per fragment before any per-file sort. | Numbered call-count regression in `rank.test.ts`. |
+| #509 | Member patterns are precompiled once and regex-token expansion runs once per candidate file. | Numbered construction/scan-count regression in `rank.test.ts`. |
+| #510 | Quoted multiword errors and screaming-snake error codes are exact-literal evidence. | Numbered regression in `signals.test.ts`. |
+| #511 | Silent-e inflections converge without a narrow closed verb list deciding searchability. | Numbered inflection matrix in `signals.test.ts`. |
+| #512 | Plain lowercase function names can gain definition evidence when the definition disambiguates them. | Numbered regression in `rank.test.ts`. |
+| #513 | Meaningful task verbs and nouns remain searchable even when common in source syntax. | Numbered task-word matrix in `signals.test.ts`. |
+| #514 | Dotted member mentions work with arbitrary receiver names while extension noise is filtered separately. | Numbered regression in `signals.test.ts`. |
+| #515 | Diff task signals use additions, not deleted code or patch metadata. | Numbered regression in `signals.test.ts`. |
+| #516 | Apostrophes inside contractions cannot swallow a later quoted literal. | Numbered regression in `signals.test.ts`. |
+| #517 | Base, plural, past-tense, and progressive forms converge on consistent searchable tokens. | Numbered inflection matrix in `signals.test.ts`. |
+| #518 | `--explain --output` writes the explanation and leaves stdout clean. | Numbered CLI regression in `cli-runner.test.ts`. |
+| #519 | An unresolved requested diff makes `--explain` print an actionable error and exit non-zero. | Numbered CLI regression in `cli-runner.test.ts`. |
+| #520 | `--issue` accepts task text beginning with a hyphen unless it is a recognized option token. | Numbered argument-parser matrix in `cli-runner.test.ts`. |
+| #521 | A help token in a missing value slot is an option error, not a successful global help request. | Numbered CLI regression in `cli-runner.test.ts`. |
+| #522 | `--output` trims and expands its path consistently with other path-valued options. | Numbered parser regression in `cli-runner.test.ts`. |
+| #523 | Working-tree/head conflicts are reported before the standalone head/base requirement. | Numbered CLI regression in `cli-runner.test.ts`. |
+| #524 | Missing or malformed package metadata produces a controlled installation error and exit code 1. | Numbered injected-failure regression in `cli-runner.test.ts`. |
+| #525 | Copy-paste hints use shell-aware quoting for whitespace and metacharacters. | Numbered Windows CLI hint regression plus shared core/browser quote export checks. |
+
+## Workflow, evaluation, CLI, core, Action, and website sweep (#526–#598)
+
+| Issue | Local resolution | Verification |
+| --- | --- | --- |
+| #526 | CI covers supported Node 20.11 and current Node 22. | Workflow inspection; full CI-equivalent run. |
+| #527 | CI includes Ubuntu, Windows, and macOS jobs for platform-sensitive paths. | Workflow inspection; GitHub checks required after review. |
+| #528 | CI declares read-only `contents` permission. | Workflow metadata gate. |
+| #529 | Push CI is restricted to `main`; pull requests use the PR trigger. | Workflow trigger inspection. |
+| #530 | Third-party workflow actions are pinned to immutable SHAs. | Workflow inspection. |
+| #531 | Publish permissions are job-scoped. | Workflow inspection. |
+| #532 | README documents the supported exclusion syntax linked by Action metadata. | README/action metadata check. |
+| #533 | Root CI runs the full dependency audit, including website/build dependencies. | `npm run audit:all`. |
+| #534 | CI jobs have bounded timeouts. | Workflow inspection. |
+| #535 | Scheduled external evaluation runs only in the canonical repository. | Workflow guard inspection. |
+| #536 | Generated-output checks compare without rewriting the worktree. | `npm run check:rendered`; clean status comparison. |
+| #537 | Calibration by confidence is published on the evidence page. | Web build and evidence-data review. |
+| #538 | Evaluation floors target the documented cohorts and recorded data. | External and held-out gates. |
+| #539 | CLI help documents `FIXMAP_CACHE_DIR` and `FIXMAP_VERBOSE_USAGE`. | CLI help snapshot/tests. |
+| #540 | Explain and Rank share one lockfile definition. | Core tests and typecheck. |
+| #541 | MCP Plan/Explain accept `noCache`. | MCP schema and invocation tests. |
+| #543 | `fixmap mcp` accepts a default `--repo`. | CLI/MCP argument tests. |
+| #544 | Markdown code spans safely render paths containing backticks. | Report rendering tests. |
+| #545 | Exclusion patterns are escaped instead of becoming live Markdown. | Report rendering tests. |
+| #546 | `paths-excluded` exposes structured paths. | Explain/report tests. |
+| #547 | Missing-path explanations distinguish unseen and unsupported cases without duplication. | Explain-path tests. |
+| #548 | Import proximity resolves workspace packages and configured path aliases. | Import-graph tests. |
+| #549 | Doctor reports every resolved FixMap shim that can shadow another. | Doctor tests. |
+| #550 | Doctor performs and documents the project-local shadow check. | Doctor tests and README review. |
+| #551 | Import-graph truncation emits an explicit diagnostic. | Import-graph/report tests. |
+| #552 | Doctor always prints the PATH status, including not found. | Doctor tests. |
+| #553 | RSpec `spec/` and `_spec.rb` files are tests. | Cross-language tests. |
+| #554 | C#, Java, PHP, and Ruby receive explicit language/test routing. | Language and repository-scan tests. |
+| #555 | `tox.ini` is scoped to its owning Python workspace. | Test-route tests. |
+| #556 | Rust and Go manifest commands derive their own package directory. | Test-route tests. |
+| #557 | Remote operations sweep stale temporary repositories and clean current clones. | Repository-source tests and code path review. |
+| #558 | Remote repositories accept an explicit branch or tag ref. | Repository-source/CLI tests. |
+| #559 | GitHub URLs normalize a `.git` repository suffix. | Issue-source tests. |
+| #560 | Rejected HTTP GitHub URLs explain the HTTPS requirement. | Issue-source tests. |
+| #561 | Action distinguishes rate limiting from genuine read-only permission failures. | GitHub API error tests. |
+| #562 | Comment lookup uses only supported endpoint parameters. | GitHub comment tests. |
+| #563 | Permission errors use structured status/codes, not self-authored message text. | GitHub API error tests. |
+| #564 | Comment pagination fails safely at its bound instead of posting a duplicate. | Pagination-cap tests. |
+| #565 | Report validation rejects malformed legacy shapes before render/verify. | Entry-point, report, and verify tests. |
+| #566 | Verify detects partial plan/repository mismatches after rebase or rename. | Verify tests. |
+| #567 | Verification Markdown uses the shared safe code-span renderer. | Verify rendering tests. |
+| #568 | The hero resumes rendering after document visibility returns. | Component logic plus browser QA gate. |
+| #569 | Copy controls provide success/failure feedback and handle missing clipboard APIs. | Component tests/build plus browser QA gate. |
+| #570 | Sitemap entries include `lastModified` and omit ignored priority/frequency hints. | Sitemap build/output inspection. |
+| #571 | Compare does not claim nothing changed when grounding changed. | Compare tests. |
+| #572 | Legacy unknown grounding is not reported as a spurious change. | Compare tests. |
+| #573 | Compare validates duplicate context paths instead of silently collapsing them. | Compare/validator tests. |
+| #574 | Server-manifest gate proves the registry command launches `mcp`. | `npm run check:server-manifest`. |
+| #575 | MCP tests assert complete schemas and reject invalid arguments. | MCP tests. |
+| #576 | Workspace smoke requires the expected file to rank within the target position. | `npm run smoke`. |
+| #577 | Cache eligibility ignores its own cache directory and handles untracked state deliberately. | Repository-scan cache tests. |
+| #578 | Cache entries have bounded eviction. | Repository-scan cache tests. |
+| #579 | Bug vocabulary such as errors, performance, and reliability is descriptive, not automatically vague. | Grounding tests. |
+| #580 | Action comments, summaries, and `report` output are all bounded with accurate notices. | Action runner tests. |
+| #581 | Polite grammar does not make an otherwise actionable task empty. | Grounding/ranking tests. |
+| #582 | Vague tasks return low-confidence guidance instead of suppressing every candidate. | Plan/ranking tests. |
+| #583 | Empty evaluation cohorts fail rather than producing a passing NaN comparison. | Evaluation script gate. |
+| #584 | File extensions are matched case-insensitively. | Repository-scan tests. |
+| #585 | Binary, oversized, encoding, and general read failures have distinct diagnostics. | Repository-scan tests. |
+| #586 | Deleting a planned file yields an advisory deletion finding, not a wrong-repository error. | Verify tests. |
+| #587 | Billing and package risk triggers remain tokenizer-reachable. | Ranking/risk literal guard. |
+| #588 | Lint commands are not routed as tests. | Test-route tests. |
+| #589 | Kubernetes, hosting, CI, UI, and public targeting literals remain reachable. | Ranking/risk literal guard. |
+| #590 | Credentialed non-GitHub URLs are rejected/redacted before reports or comments. | CLI/Action issue-source tests. |
+| #591 | URL secrets cannot become identifiers or appear in diagnostics/output. | Signal/redaction tests. |
+| #592 | CLI and browser use one shell-aware command-quoting implementation. | Core quote tests, web typecheck/build. |
+| #593 | Evaluation rows use unambiguous Top-1/3/5 booleans and validate their shape. | Evaluation record/gate. |
+| #594 | Generated SVG wrapping iterates Unicode code points without splitting emoji. | Render wrap test and rendered-output gate. |
+| #595 | Unicode scripts tokenize and rank rather than returning an empty report. | Signal/ranking tests. |
+| #596 | Action metadata gate proves the expected `main`, not merely equality between two wrong files. | `npm run check:action-metadata`. |
+| #597 | Oversized diffs truncate at a line boundary and emit a diagnostic. | Plan/report tests. |
+| #598 | Node and browser entry points expose the same filesystem-free report/validation surface. | Entry-point parity test and browser build. |
+
+## Newly refreshed GitHub issues (#600–#627)
+
+| Issue | Local resolution | Verification |
+| --- | --- | --- |
+| #600 | A diff no longer upgrades a vague task to anchored grounding. | `github-issues-600-627.test.ts`. |
+| #601 | Gated-test detection covers JS/TS skip/todo forms plus Python, Go, and Rust skip markers. | `test-gates.test.ts`. |
+| #602 | CLI and Action `limit` accept decimal digits only. | CLI and Action runner tests. |
+| #603 | Ranking and grounding share `CLUSTERED_RANKING_MARGIN`. | Typecheck and core regression tests. |
+| #604 | Recorded held-out baselines and the documented literal Top-5 rate are refreshed. | Held-out FixMap/baseline record and gates. |
+| #605 | No code change can enable repository security settings. This remains a deliberate post-review public action. | Live GitHub API re-query must prove Dependabot updates, secret scanning, push protection, and validity checks are enabled. |
+| #606 | The issue chooser links questions to Discussions. | Issue-template YAML inspection. |
+| #607 | Exported ranking and risk rule tables are guarded against tokenizer-dead literals. | `github-issues-600-627.test.ts`. |
+| #608 | Website lint fails on warnings. | `npm run lint -w @fixmap/web`. |
+| #609 | Step-summary writes measure existing file bytes and consume only the remaining 1 MiB budget. | Action runner tests. |
+| #610 | Ranking clustering is computed before display-limit slicing. | `github-issues-600-627.test.ts`. |
+| #611 | Contested-lead confidence sees the full candidate list even with `--limit 1`. | `github-issues-600-627.test.ts`. |
+| #612 | Explain reports the real score cutoff when the report has unused slots. | `github-issues-600-627.test.ts`. |
+| #613 | The CLI verify-output test creates its own two-commit repository instead of using ambient history. | CLI tests in a shallow-compatible fixture. |
+| #614 | BOM-less UTF-16 LE/BE issue files are detected heuristically. | CLI runner tests. |
+| #615 | Website lint warnings are fatal in the workspace script. | Root lint gate. |
+| #616 | Every scanned source extension can be extracted as a file mention. | Parameterized mention tests. |
+| #617 | Non-Git directory scans include and deprioritize `vendor/` consistently. | Repository-scan regression test. |
+| #618 | Module stems remove only one leading layout segment, avoiding unrelated collisions. | `github-issues-600-627.test.ts`. |
+| #619 | Numeric slash/hash text remains local task text and never becomes a GitHub request. | CLI issue-source test. |
+| #620 | Verify and Action expose an opt-in warning failure threshold. | CLI and Action fail-on tests. |
+| #621 | Curly, low, single, and guillemet quote pairs yield exact fragments. | `github-issues-600-627.test.ts`. |
+| #622 | A nested full-path mention cannot boost an unrelated root basename. | `github-issues-600-627.test.ts`. |
+| #623 | Stop-word-prefixed identifiers retain complete symbol tokens for partial grounding. | `github-issues-600-627.test.ts`. |
+| #624 | `function* name` declarations count as generator definition sites. | `github-issues-600-627.test.ts`. |
+| #625 | Plain `src/config.ts` is code; only conventional config filenames are configuration. | Repository-scan regression test. |
+| #626 | Copy utilities are not backup files; sync-style `name copy (2)` files still are. | `github-issues-600-627.test.ts`. |
+| #627 | Nested lockfiles select the workspace package manager and conflicting roots emit a diagnostic. | Repository-scan regression tests. |
+
+## Attached 30-finding v0.8.8 report (A1-A30)
+
+The attached review mixed confirmed defects, documentation gaps, speculative questions, and positive checks. The table preserves all 30 items without turning safe or already-correct behavior into a regression.
+
+| Finding | Resolution | Verification |
+| --- | --- | --- |
+| A1 | Added the `plan --no-cache` example to the primary usage banner. | CLI help test. |
+| A2 | GitHub issue text is fetched directly rather than stored in the repository-scan cache; `--no-cache` still forces and reports a fresh repository scan. | CLI no-cache pass-through and repository cache-bypass tests. |
+| A3 | Cache identity includes commit, porcelain status, and binary diff, distinguishing staged and unstaged tracked states. | Exact dirty-state cache tests. |
+| A4 | Format values are trimmed before case-insensitive validation. | CLI whitespace regression test. |
+| A5 | `~` expands consistently for `--repo`, `--output`, report, compare, and issue-file paths. | CLI home-expansion matrix. |
+| A6 | `--no-cache`, including working-tree use, emits a fresh-scan bypass diagnostic. | Repository cache-bypass tests. |
+| A7 | Cache-hit diagnostics include a human-readable scan age. | Cache-age and expiry tests. |
+| A8 | No defect: OS null devices are valid explicit output sinks and are intentionally not rejected. | Output remains a caller-selected path; no special-case ambiguity is introduced. |
+| A9 | Stdin is synchronously read and validated before report construction or cache work begins. | Dedicated stdin/no-cache ordering regression. |
+| A10 | The cache deliberately stores the raw exact-state scan; exclusions are reapplied for every plan, so reuse cannot leak excluded paths. This architecture is now explicit in README. | Exclusion ranking tests and cache documentation. |
+| A11 | Added `fixmap validate <report.json>`. | Validator CLI and malformed/legacy/versioned report tests. |
+| A12 | Same resolved premise as A2: the issue fetch is not cached, and the repository scan visibly reports the bypass. | CLI and core no-cache tests. |
+| A13 | No defect: a rename safely invalidates the exact-state cache because paths are part of repository state. | Conservative identity contract documented in README. |
+| A14 | Positive/untested note, not a defect; different filenames intentionally represent different repository states. | Exact-state cache contract. |
+| A15 | No defect: `--limit` is presentation slicing after ranking and should reuse the underlying scan. | Context-limit invariance tests and README clarification. |
+| A16 | No defect: cache scope is repository scanning; Verify consumes and validates a supplied plan rather than caching edited report JSON. | Verify validator tests and README clarification. |
+| A17 | No defect: task or diff evidence is applied after the reusable exact-state file scan; adding task text must not force file rereads. | Report construction and cache contract tests. |
+| A18 | Working-tree scans use the tracked status and binary diff in their identity; untracked-inclusive scans remain deliberately uncached. | Clean, tracked-dirty, staged/unstaged, and untracked cache tests. |
+| A19 | Incorrect premise: Compare builds a current plan and therefore can reuse or bypass its repository scan. | Compare `--no-cache` regression. |
+| A20 | Cache entries expire after seven days and bounded eviction removes stale/excess entries. | Cache TTL/eviction tests. |
+| A21 | Absolute exclusion patterns beneath the repository normalize to root-relative patterns; outside paths remain non-matching and diagnosable. | Absolute-pattern and unmatched-pattern tests. |
+| A22 | The reported 1,000-pattern run was already successful; FixMap keeps no arbitrary cap and now guards the large-list behavior. | Dedicated 1,000-pattern regression. |
+| A23 | Positive check, not a defect: equivalent local path spellings resolve consistently. | Repository resolution behavior. |
+| A24 | The additive `reportVersion: 1` policy is documented; legacy unmarked reports are accepted and unsupported future versions fail clearly. | Core and CLI validator tests. |
+| A25 | Unmatched exclusions emit `exclusion-no-match` with the pattern. | Exclusion diagnostic test. |
+| A26 | Excluding every candidate produces warning diagnostics and an explicit no-context explanation. | Plan/report all-excluded tests. |
+| A27 | Positive check: Verify rejects a plan/repository mismatch. | Full and partial mismatch tests. |
+| A28 | Positive check: same-repository version-1 plans validate and verify. | Versioned report tests. |
+| A29 | Positive check: a structurally complete empty-context plan remains legitimate. | Validator and Verify empty-plan tests. |
+| A30 | Incorrect premise: Compare constructs a current plan, so `--no-cache` meaningfully forces that scan fresh. | Dedicated compare/no-cache regression. |
+
+## Review and release gates
+
+Before approval, run generated-output regeneration/checks, the full local CI-equivalent suite, evaluation gates, package dry-runs, fresh packed-package smoke, and website browser QA. Re-query GitHub immediately before handoff so issues created during this work are not missed.
+
+After approval, the public settings and release surfaces are tracked in `v0.8.9-post-release-checklist.md`.
diff --git a/docs/releases/v0.8.9-post-release-checklist.md b/docs/releases/v0.8.9-post-release-checklist.md
new file mode 100644
index 0000000..67da373
--- /dev/null
+++ b/docs/releases/v0.8.9-post-release-checklist.md
@@ -0,0 +1,17 @@
+# FixMap v0.8.9 release checklist
+
+Release authorization was granted on 2026-08-11. Mark an item complete only after its public evidence has been checked against the exact release commit.
+
+- [ ] Merge the approved commit and confirm required GitHub checks pass on that exact SHA.
+- [ ] Tag `v0.8.9`; verify the immutable tag and GitHub release resolve to the approved SHA.
+- [ ] Verify `@aryam/fixmap-core@0.8.9` and `@aryam/fixmap@0.8.9` on npm, including provenance and the `latest` dist-tag.
+- [ ] Install the CLI globally from a fresh npm cache and prove `fixmap --version`, Plan, Explain, Compare, Verify, Validate, Doctor, `/fixmap` setup, and MCP startup.
+- [ ] Verify `io.github.aryamthecodebreaker/fixmap@0.8.9` in the MCP Registry and run a real MCP tool call from the public package.
+- [ ] Move the GitHub Action major/release tag to the approved commit, verify Marketplace metadata, and run Plan and Verify in a disposable consumer repository.
+- [ ] Promote the production Vercel deployment built from the same commit; smoke every route, canonical/OG metadata, sitemap, theme, copy feedback, demo state, and mobile layout.
+- [ ] Update the website changelog/version/install examples and README release references only where the published version must be explicit.
+- [ ] Publish the reviewed X and LinkedIn posts with the real release URL.
+- [ ] Close only issues proven by the released commit; leave #605 open until repository security settings are enabled and re-read successfully.
+- [ ] Enable Dependabot security updates, secret scanning, push protection, and validity checks; independently re-query all four repository settings.
+- [ ] Re-query GitHub issues after publication and triage any issue created during the release window.
+- [ ] Confirm the original maintainer checkout remains untouched and archive the isolated release worktree only after acceptance.
diff --git a/docs/releases/v0.8.9-release-notes-draft.md b/docs/releases/v0.8.9-release-notes-draft.md
new file mode 100644
index 0000000..1e358a1
--- /dev/null
+++ b/docs/releases/v0.8.9-release-notes-draft.md
@@ -0,0 +1,28 @@
+# FixMap v0.8.9 release notes
+
+FixMap v0.8.9 is a reliability release for the CLI, scanner, ranking engine, MCP server, GitHub Action, evaluation harness, release workflows, documentation, and website.
+
+## Highlights
+
+- Type `/fixmap` with no task to open a complete, installed feature catalog covering Plan, Explain, Compare, Verify, Validate, Doctor, MCP, public issues, repository sources, task files, focus controls, working-tree mapping, cache control, outputs, test routing, risks, the GitHub Action, and setup.
+- Use `--fail-on warning` in Verify or `fail-on: warning` in the Action when advisory findings must block CI.
+- Scan and mention more source formats consistently, including PHP, Vue, Svelte, C#, CJS, and MTS; recognize C#, Java, PHP, and Ruby language/test conventions.
+- Preserve ranking confidence when `--limit` changes by measuring clustering and contested leads over the full candidate list.
+- Detect nested workspace lockfiles, diagnose conflicting root package managers, and route test commands to the correct tool.
+- Read BOM-less UTF-16 task files, typographic quote pairs, Unicode task text, generator declarations, and stop-word-prefixed identifiers correctly.
+- Keep the Action's comment, output, and step summary within GitHub size limits, including space already consumed by earlier steps.
+- Harden validation, Markdown escaping, credential redaction, remote repository cleanup/ref selection, cache eviction, import-graph diagnostics, and package/server metadata gates.
+- Make CI cross-platform, least-privilege, timeout-bounded, immutable-action pinned, non-mutating, and strict about all dependency audits and website lint warnings.
+- Refresh external, held-out, adversarial, baseline, and savings evidence from the corrected scanner corpus.
+- Replace the synthetic-looking website presentation with a restrained editorial product system, clearer proof, robust copy feedback, visibility-safe motion, complete metadata, and an honest interactive demo.
+
+## Compatibility
+
+- Node.js 20.11 or newer remains required.
+- Existing `reportVersion: 1` consumers remain supported; additive fields can be ignored.
+- Errors remain the default Verify failure threshold. Warning-level failure is opt-in.
+- No hosted model, source upload, dependency installation, test execution, or package-script execution was added.
+
+## Release evidence
+
+The exact approved release commit must pass a clean `npm ci`, the complete local CI command, all recorded evaluation gates, both package dry-runs, fresh packed-package CLI/MCP/Core/Action smoke tests, and desktop/mobile website browser checks. After publishing, every public surface in the companion checklist must be verified against the same commit.
diff --git a/docs/releases/v0.8.9-social-posts.md b/docs/releases/v0.8.9-social-posts.md
new file mode 100644
index 0000000..9a6dbe2
--- /dev/null
+++ b/docs/releases/v0.8.9-social-posts.md
@@ -0,0 +1,41 @@
+# FixMap v0.8.9 social posts — draft
+
+Approved release copy. Publish only after the release URL and public artifacts resolve.
+
+## X
+
+FixMap v0.8.9 is live.
+
+This release hardens the whole path from task to verified change: more accurate ranking, strict CI verification, safer GitHub Action output, broader language support, a complete `/fixmap` menu, reproducible evidence, and a sharper website.
+
+https://github.com/aryamthecodebreaker/FixMap/releases/tag/v0.8.9
+
+## LinkedIn
+
+FixMap v0.8.9 is live.
+
+FixMap is a deterministic, local-first context mapper for coding agents. Give it a task, GitHub issue, or diff and it ranks the files to inspect, routes relevant tests, highlights risk, and explains uncertainty before the first edit.
+
+This release focuses on trust and finish:
+
+- ranking confidence is now independent of the display limit
+- Verify and the GitHub Action can fail on advisory warnings when CI needs a stricter gate
+- nested workspaces, package-manager conflicts, BOM-less UTF-16, Unicode text, typographic quotes, more languages, and more test conventions are handled correctly
+- credentials, Markdown paths, temporary clones, caches, large diffs, comments, outputs, and job summaries are safer
+- `/fixmap` without a task lists the complete feature set inside supported coding agents
+- CI, publishing metadata, generated artifacts, and recorded evaluations have stronger drift guards
+- the website has a calmer, more professional visual system and clearer proof of what FixMap can and cannot do
+
+The release evidence includes full automated tests, cross-platform CI configuration, external and held-out retrieval evaluations, adversarial false-confidence checks, a 1,000-file scan benchmark, packed-package smoke tests, and desktop/mobile browser verification.
+
+Install:
+
+`npm install --global @aryam/fixmap@0.8.9`
+
+Demo: https://usefixmap.vercel.app/demo
+
+Evidence: https://usefixmap.vercel.app/evidence
+
+Release notes: https://github.com/aryamthecodebreaker/FixMap/releases/tag/v0.8.9
+
+#opensource #developerTools #AIagents #MCP #GitHubActions
diff --git a/examples/reports/declines-fabricated-identifier.md b/examples/reports/declines-fabricated-identifier.md
index 5cc91df..1802212 100644
--- a/examples/reports/declines-fabricated-identifier.md
+++ b/examples/reports/declines-fabricated-identifier.md
@@ -37,4 +37,4 @@ FixMap found 0 context files and generated 0 test routes.
 
 - **info** Repository scan caching was bypassed by --no-cache; this report used a fresh scan.
 - **warning** Identifiers not found exactly in the scanned repository: resolveTenantScopedSessionBinding, SessionBindingMismatch. Component words from unresolved identifiers were ignored, and unsupported recommendations were capped at low confidence.
-- **warning** No context files: no file in the 3 scanned matched the task terms bind, close, mismatch, resolve, rotation, scop, session, tenant (+1 more). The repository may not contain this behavior, or it may name it differently.
+- **warning** No context files: no file in the 3 scanned matched the task terms bind, close, mismatch, resolve, rotation, scope, session, tenant (+1 more). The repository may not contain this behavior, or it may name it differently.
diff --git a/examples/reports/declines-unmatched-terms.md b/examples/reports/declines-unmatched-terms.md
index 7f27bd6..bc3bbc6 100644
--- a/examples/reports/declines-unmatched-terms.md
+++ b/examples/reports/declines-unmatched-terms.md
@@ -36,4 +36,4 @@ FixMap found 0 context files and generated 0 test routes.
 ## Diagnostics
 
 - **info** Repository scan caching was bypassed by --no-cache; this report used a fresh scan.
-- **warning** No context files: no file in the 3 scanned matched the task terms backpressure, drop, dur, ingestion, pipeline, span, telemetry. The repository may not contain this behavior, or it may name it differently.
+- **warning** No context files: no file in the 3 scanned matched the task terms backpressure, drop, dure, ingestion, pipeline, span, telemetry. The repository may not contain this behavior, or it may name it differently.
diff --git a/examples/reports/declines-vague-task.md b/examples/reports/declines-vague-task.md
index 74b2792..d47753b 100644
--- a/examples/reports/declines-vague-task.md
+++ b/examples/reports/declines-vague-task.md
@@ -37,3 +37,4 @@ FixMap found 0 context files and generated 0 test routes.
 
 - **info** Repository scan caching was bypassed by --no-cache; this report used a fresh scan.
 - **warning** 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.
+- **warning** No context files: no file in the 3 scanned matched the task terms better, clean, general, overall, performance. The repository may not contain this behavior, or it may name it differently.
diff --git a/examples/reports/workspace-api-discount.md b/examples/reports/workspace-api-discount.md
index 7d614fc..83b40f7 100644
--- a/examples/reports/workspace-api-discount.md
+++ b/examples/reports/workspace-api-discount.md
@@ -4,8 +4,8 @@ FixMap found 2 context files and generated 3 test routes.
 
 ## Context Files
 
-- `apps/api/src/orders.ts` (high confidence, score 37): path matches task terms: order; content matches task terms: discount, order, total, code; defines task identifiers: orderTotal
-- `packages/utils/src/currency.ts` (low confidence, score 6): content matches task terms: discount, total
+- `apps/api/src/orders.ts` (high confidence, score 41): path matches task terms: order; content matches task terms: discount, order, total, code; defines task identifiers: orderTotal; task identifier is defined in maintained implementation source
+- `packages/utils/src/currency.ts` (medium confidence, score 14): content matches task terms: discount, total; defines symbols matching task terms: applyDiscount, discounted
 
 ## Test Routes
 
diff --git a/examples/reports/workspace-utils-rounding.md b/examples/reports/workspace-utils-rounding.md
index 36546a2..18f8338 100644
--- a/examples/reports/workspace-utils-rounding.md
+++ b/examples/reports/workspace-utils-rounding.md
@@ -1,16 +1,15 @@
 # FixMap Report
 
-FixMap found 1 context file and generated 3 test routes.
+FixMap found 1 context file and generated 2 test routes.
 
 ## Context Files
 
-- `packages/utils/src/currency.ts` (high confidence, score 33): path matches task terms: currency; content matches task terms: round, cent; defines task identifiers: roundToCents
+- `packages/utils/src/currency.ts` (high confidence, score 37): path matches task terms: currency; content matches task terms: round, cent; defines task identifiers: roundToCents; task identifier is defined in maintained implementation source
 
 ## Test Routes
 
 - `pnpm --dir packages/utils run test`: nearest package (packages/utils) script named test. Related: `packages/utils/test/currency.test.ts`.
 - `pnpm run test`: repository root script named test. Related: `packages/utils/test/currency.test.ts`.
-- `pnpm --dir packages/utils run typecheck`: nearest package (packages/utils) script named typecheck. Related: `packages/utils/src/currency.ts`.
 
 ## Risk Map
 
diff --git a/package-lock.json b/package-lock.json
index 3b1774f..ce9f169 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "fixmap-workspace",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "fixmap-workspace",
-      "version": "0.8.8",
+      "version": "0.8.9",
       "license": "MIT",
       "workspaces": [
         "packages/*",
@@ -23,14 +23,14 @@
         "vitest": "^4.1.9"
       },
       "engines": {
-        "node": "24.x"
+        "node": ">=20.11"
       }
     },
     "apps/web": {
       "name": "@fixmap/web",
       "version": "0.0.0",
       "dependencies": {
-        "@aryam/fixmap-core": "0.8.8",
+        "@aryam/fixmap-core": "0.8.9",
         "@phosphor-icons/react": "^2.1.10",
         "next": "16.2.11",
         "react": "19.2.7",
@@ -336,28 +336,6 @@
         "tslib": "^2.4.0"
       }
     },
-    "node_modules/@emnapi/runtime": {
-      "version": "1.11.3",
-      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz",
-      "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==",
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "tslib": "^2.4.0"
-      }
-    },
-    "node_modules/@emnapi/wasi-threads": {
-      "version": "1.2.2",
-      "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.2.tgz",
-      "integrity": "sha512-c95qOXkHdydNKhscBTebqEC1CVAZpyqOfVfBzQ1qgzyl3gfeldUjIggDbIZgDKsHLgnsM+igH7TJ/eAasaVuMA==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "tslib": "^2.4.0"
-      }
-    },
     "node_modules/@esbuild/aix-ppc64": {
       "version": "0.28.1",
       "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.1.tgz",
@@ -1643,6 +1621,23 @@
       "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
       "license": "MIT"
     },
+    "node_modules/@napi-rs/lzma-linux-x64-gnu": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/@napi-rs/lzma-linux-x64-gnu/-/lzma-linux-x64-gnu-1.5.1.tgz",
+      "integrity": "sha512-oTXEIha4SsuXdTA4Iyskj0kpdx2yVXdhd75c2v3xGrHFfVMsbhTPZU/nMPL4sWKo4pBHm3aucLaqGlF696dTyQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^22.20 || ^24.12 || >=25"
+      }
+    },
     "node_modules/@napi-rs/wasm-runtime": {
       "version": "1.1.6",
       "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.6.tgz",
@@ -1854,16 +1849,6 @@
         "node": ">=12.4.0"
       }
     },
-    "node_modules/@oxc-project/types": {
-      "version": "0.139.0",
-      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.139.0.tgz",
-      "integrity": "sha512-r9gHphtCs+1M7J0pw6Sn/hh/Wpa/iQrOOkrNAlVLF/gHq+/CJmHIWKKUUhdWjcD6CIa8idarspCsASiXCXvFUw==",
-      "dev": true,
-      "license": "MIT",
-      "funding": {
-        "url": "https://github.com/sponsors/Boshen"
-      }
-    },
     "node_modules/@phosphor-icons/react": {
       "version": "2.1.10",
       "resolved": "https://registry.npmjs.org/@phosphor-icons/react/-/react-2.1.10.tgz",
@@ -1877,27 +1862,38 @@
         "react-dom": ">= 16.8"
       }
     },
-    "node_modules/@rolldown/binding-android-arm64": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.1.5.tgz",
-      "integrity": "sha512-lZg8fqIv2v7FF237bwMgzGZEJvGL79/s5knJ/i6FmsGF4XXlzccZ4jb+TrFIxtSSxFtIpdsgrPZeMk1I9AFcyQ==",
+    "node_modules/@rollup/rollup-android-arm-eabi": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.62.4.tgz",
+      "integrity": "sha512-RrPokAb7dmbxFoeO3TloqHyOjgye8RkBhSqmp4aJMIex4c9r46ZstPnleDQOq1t46VOVjwIuwNogIqbodV1Vvg==",
       "cpu": [
-        "arm64"
+        "arm"
       ],
       "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
         "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-android-arm64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.62.4.tgz",
+      "integrity": "sha512-JKuJc+pnpks2pjy7L/N3v/cAkZxYlnmuZoD840ldbMI5KDbC4iO9NKwPKYdjYFCMAIIlBzYSFHxIJVYzRo2/8A==",
+      "cpu": [
+        "arm64"
       ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
     },
-    "node_modules/@rolldown/binding-darwin-arm64": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.1.5.tgz",
-      "integrity": "sha512-51Bnx9pNiMRKSUNtBfySkNJ9vMU9Hh3I1ozDd6gyPPYzaXCfnptUcEZxXGYFn+ul2dtcMUiqGR1Yai2K10uoTw==",
+    "node_modules/@rollup/rollup-darwin-arm64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.62.4.tgz",
+      "integrity": "sha512-krw5uS2STmvJ02x0uTXHbqQNuz+9eZ1iw+qXk9dmW2gvV4jV7O2hEoOnuhFrpOPiel1mBFtqbxYZZtC46hXLOw==",
       "cpu": [
         "arm64"
       ],
@@ -1906,15 +1902,12 @@
       "optional": true,
       "os": [
         "darwin"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      ]
     },
-    "node_modules/@rolldown/binding-darwin-x64": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.1.5.tgz",
-      "integrity": "sha512-Tm+gbfC0aHu1tBA/JvKQh32S0K6YgCHkiAF4/W6xX0K0RmNuc94VeK419dJoE65R5aRxmo+noZQSWrAMF6yb6g==",
+    "node_modules/@rollup/rollup-darwin-x64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.62.4.tgz",
+      "integrity": "sha512-wsTxtgApb4PrOsNJIm0FZ1h3WvCC+k9uxLJ4ad75hgoS4NiRes2SoJFlDAyMwiUY8IssDqGcHbXuN0sx1tfF1A==",
       "cpu": [
         "x64"
       ],
@@ -1923,15 +1916,26 @@
       "optional": true,
       "os": [
         "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-arm64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.62.4.tgz",
+      "integrity": "sha512-GUOnQlyZe3yAXhWOtOMsn5Qkrv5E5mZXa0thbARWi5Ei2szlVXJFQhddZ4HbAzh8q92w5twp+CQvs/eFanz9YQ==",
+      "cpu": [
+        "arm64"
       ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
     },
-    "node_modules/@rolldown/binding-freebsd-x64": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.1.5.tgz",
-      "integrity": "sha512-JMzDKCCXq93YccG5gz3hvOs1oXRKAf0XYpfOS88e+wZrC8Iugj6j68867vrYZkvpDDpKn/KoKORThmchMpF6TA==",
+    "node_modules/@rollup/rollup-freebsd-x64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.62.4.tgz",
+      "integrity": "sha512-/Y7f3QuxjzPKsjA/rfEDa3+0vXqyjmJ50Ln8dPpCmWkKTrUoWHG1cWhTqaAMLob2m2nESWuC7yGrREz019Ztqg==",
       "cpu": [
         "x64"
       ],
@@ -1940,15 +1944,12 @@
       "optional": true,
       "os": [
         "freebsd"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      ]
     },
-    "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.1.5.tgz",
-      "integrity": "sha512-uML21j2K5TfPGutKxub+M+nLjZIrWjXQ5Grx4lCe/nimTj9B4L63zHpjXLl4y0L3mcm2htEQIb06oCG/szerNw==",
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.62.4.tgz",
+      "integrity": "sha512-81wiiX3v7aqy+T+bT61TJ78yJjRquqFFTTbAPt08imfQQzkPIW8t6aJbkTagtCCrXMNc9D66+geqlK7ydLPNqA==",
       "cpu": [
         "arm"
       ],
@@ -1957,15 +1958,26 @@
       "optional": true,
       "os": [
         "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.62.4.tgz",
+      "integrity": "sha512-9kmDIvNZqdoHOBZgNtpTBeLWYO/LVipM3H/j62P8848/l/VPEQL6N3uxU9pvP1oZAsXyC2MEnFP3ovRjo7WYNQ==",
+      "cpu": [
+        "arm"
       ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
     },
-    "node_modules/@rolldown/binding-linux-arm64-gnu": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.1.5.tgz",
-      "integrity": "sha512-navSiuTMogvnQoZoM/v+l3ZWo50/NTwSHSzheABx/RCnmUPaKwq9qSo4Br2OYRs21+Fz8uFqITZM3H4opOB0/Q==",
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.62.4.tgz",
+      "integrity": "sha512-CcnXHWnXg69g+DX5VWL3FHts3qMRN2uVEHX+BZvGLdd07/gXkn3ePjYtO1LDJvxkGKVHMclKBRa1QUTH+6toYQ==",
       "cpu": [
         "arm64"
       ],
@@ -1974,15 +1986,12 @@
       "optional": true,
       "os": [
         "linux"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      ]
     },
-    "node_modules/@rolldown/binding-linux-arm64-musl": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.1.5.tgz",
-      "integrity": "sha512-lAryqH7IteztmCXQXk0etKj4wBQ7Gx5S6LjKhsgp9zb8I5bsuvU/2llH1hDQcjsFeqIsovMVN339/8pUDDBXxA==",
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.62.4.tgz",
+      "integrity": "sha512-iFOibiHnTRuhrWLlRsOQFdZJJIa7S8OwkneJr4ocALP16u5yk6lWLINFwhHaEqBFMsKDUZofLkGos7+CPzGB3g==",
       "cpu": [
         "arm64"
       ],
@@ -1991,142 +2000,166 @@
       "optional": true,
       "os": [
         "linux"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      ]
     },
-    "node_modules/@rolldown/binding-linux-ppc64-gnu": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.1.5.tgz",
-      "integrity": "sha512-fsK/sNBnxzBlL4O1JNrZakVQxPspqpED5dLtNsZS9oOKmtSpdNIzxH2kkol5HYTWJN47sE20ztMJPxfZ89qGOg==",
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.62.4.tgz",
+      "integrity": "sha512-XnWYMI7euHlb5a871xPja+Gm7DRCFU+FGRrtS2sMq9N8FvqtpagUy6gD4YOemC5MRk9xbh8+jYMEJbigFQwsgA==",
       "cpu": [
-        "ppc64"
+        "loong64"
       ],
       "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
         "linux"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      ]
     },
-    "node_modules/@rolldown/binding-linux-s390x-gnu": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.1.5.tgz",
-      "integrity": "sha512-gLYb4BIadlfTOYT5gO503n8zQjXflgzpD0FcyKh0Mzx3rqCZKnHoJWV9xe1KXUJ5lx2JfcSHr/mhzS0PC/McAA==",
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.62.4.tgz",
+      "integrity": "sha512-qGDAlO0U8xedCcsdRm9oaoQY8DAx/QT7uIxJWhCdx0ceIWX783UC9QSYkdpzAe29wNiVfp24+bZdQmn49o45SQ==",
       "cpu": [
-        "s390x"
+        "loong64"
       ],
       "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
         "linux"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      ]
     },
-    "node_modules/@rolldown/binding-linux-x64-gnu": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.1.5.tgz",
-      "integrity": "sha512-FjcpEKUyJygHgs1o50VYNvkt5+7Le/VEdYt0AkRpkL33MnyQfwr8l5mXwMmfmTbyMPr5vJLC+8/Gd9gXnwU1QQ==",
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.62.4.tgz",
+      "integrity": "sha512-ru4H6ezD7ysA5EiEK6qkkaEb4modH8CTej6kUy/gQi20u3kB3G7Zn8snXXkeJSCOFKG/rbPPtM/+9Wgas1961w==",
       "cpu": [
-        "x64"
+        "ppc64"
       ],
       "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
         "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.62.4.tgz",
+      "integrity": "sha512-2W4MO5WQVJnbJaZdvDb9rhBDuFU1nKIepPFpJUBsTh2k1YY2g+ODViaWuyOAjQ5cOP7NvrvLzt3wvHOoiAvc7w==",
+      "cpu": [
+        "ppc64"
       ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
     },
-    "node_modules/@rolldown/binding-linux-x64-musl": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.1.5.tgz",
-      "integrity": "sha512-Me+PfPI2TMeOQk0gYWfLQZtTktrmzbr8cDboqX83XKc7UrgAi55gF+2dUkWdxd19n55Essp2yeca+O9N5rBxHg==",
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.62.4.tgz",
+      "integrity": "sha512-+fxjfuoAmVMCYV5QyjoIpu0cp5DOiOTeqYFk1AVaxGr+/ravWLX89XfQmptsoWcaVy/TGf2hexzbUOrCQIL1CQ==",
       "cpu": [
-        "x64"
+        "riscv64"
       ],
       "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
         "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.62.4.tgz",
+      "integrity": "sha512-jTn8JfHGL4djjFxPuM06LmNUJDsst2jeVlsd9OmIH6zc5sC9K6rIuO4YajXatLUpBmBKl6b35ro1QZocLi+tcA==",
+      "cpu": [
+        "riscv64"
       ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
     },
-    "node_modules/@rolldown/binding-openharmony-arm64": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.1.5.tgz",
-      "integrity": "sha512-yc5WrLzXks6zCQfn9Oxr8pORKyl/pF+QjHmW/Qx3qu0oyrrNC+y2JLTU1E2rcWYAmzlnqngWXHQjy51VzW70Vw==",
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.62.4.tgz",
+      "integrity": "sha512-oCJCJL4pXsoDcP2QZ+JVlPTIRc6266zsIaeJJsWImmF7HO0W8nb6HuSgZlMWxJwaPf8ehbSw8yo0EUw925hKsA==",
       "cpu": [
-        "arm64"
+        "s390x"
       ],
       "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
-        "openharmony"
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.62.4.tgz",
+      "integrity": "sha512-W69hukhZ3KKNRCaMIEzKvcFye42hh0FE1+YoYaf5+Ikacuftoco6yO/xouz0hc5d5W/s3yBro5jRiuEE/Q5vUw==",
+      "cpu": [
+        "x64"
       ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
     },
-    "node_modules/@rolldown/binding-wasm32-wasi": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.1.5.tgz",
-      "integrity": "sha512-VbQGPX2b4r48TAMIM2cjgluIM1HYutm4pcTEJsle7iEP7sB1dFqtPLBVbdLAZCxy1txCcPxf4QFf4v8uvltPqA==",
+    "node_modules/@rollup/rollup-linux-x64-musl": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.62.4.tgz",
+      "integrity": "sha512-qiXbGG2jkjXhzXpsFZSR2Xpb8DN/UaxYsbb/STbuR/6fpaDgRmmaq1B/LmtF2wQFOFOSsK2jdE0RZ3a0zHn4QA==",
       "cpu": [
-        "wasm32"
+        "x64"
       ],
       "dev": true,
       "license": "MIT",
       "optional": true,
-      "dependencies": {
-        "@emnapi/core": "1.11.1",
-        "@emnapi/runtime": "1.11.1",
-        "@napi-rs/wasm-runtime": "^1.1.6"
-      },
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      "os": [
+        "linux"
+      ]
     },
-    "node_modules/@rolldown/binding-wasm32-wasi/node_modules/@emnapi/core": {
-      "version": "1.11.1",
-      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.1.tgz",
-      "integrity": "sha512-RSvbQmHzdKzNsLYa/wHrbc3KN4sYLKAdPZxqiM2HATqv/SBk2/ENSHpvXGaLOMcsAyz0poEGqkmmKYG3OWiJEQ==",
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.62.4.tgz",
+      "integrity": "sha512-nWeM//hxv8mIo6jD7Hu4o48DVmV9pbV6gsKaWU+4NFyqHoPKwrkRiZGLKUhOBk8qNmDmpwFtPKg80Bo/Tn4xiQ==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
       "license": "MIT",
       "optional": true,
-      "dependencies": {
-        "@emnapi/wasi-threads": "1.2.2",
-        "tslib": "^2.4.0"
-      }
+      "os": [
+        "openbsd"
+      ]
     },
-    "node_modules/@rolldown/binding-wasm32-wasi/node_modules/@emnapi/runtime": {
-      "version": "1.11.1",
-      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.1.tgz",
-      "integrity": "sha512-vgj7R3y3Wgx24IQaGPA/R6YFXLHVMOZ0uVEyIQPaWs+rd1AzfEMXlAC22FYwO1XkKR6NPsq7mUandH8oIRdZFw==",
+    "node_modules/@rollup/rollup-openharmony-arm64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.62.4.tgz",
+      "integrity": "sha512-s62SQ/vgsRSvMwDkOEfTqfgASF0f26ZNaQuTA6Aok5lrikf89yI2W0gFHvZb2Jpgc6N8JnOKZgCK2iciO3CsxQ==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
       "optional": true,
-      "dependencies": {
-        "tslib": "^2.4.0"
-      }
+      "os": [
+        "openharmony"
+      ]
     },
-    "node_modules/@rolldown/binding-win32-arm64-msvc": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.1.5.tgz",
-      "integrity": "sha512-gHv82k63z4qpV5+Q1y/12KrK0ltWBukVDI8nZcbT7Tt/ZlOIVwppazneq0F93oDxTo3IgAMEDIoQh3E2n6mVsw==",
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.62.4.tgz",
+      "integrity": "sha512-J6wGf8TVGbXJq+HH+ttTvrcfNKPbuZecV6KT1B8I18BC5IURUh5kl4Yl5OEP5eFIUoI5BWxCsyYMhFsDx8kekw==",
       "cpu": [
         "arm64"
       ],
@@ -2135,15 +2168,26 @@
       "optional": true,
       "os": [
         "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.62.4.tgz",
+      "integrity": "sha512-zmfrQd/0wu6oJs8Vq8KwY/YtsKSsLtKe/HwAP4Wqy8LhWjeT55fHRAkOhYQ12wI3ayS4Tt12d5CDRD7N96SAYQ==",
+      "cpu": [
+        "ia32"
       ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
     },
-    "node_modules/@rolldown/binding-win32-x64-msvc": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.1.5.tgz",
-      "integrity": "sha512-tTZuDBPw85tEN5PQi1pnEBzDy0Z49HtScLAbD5t6hyeU92A95pRWaSMw1GZZi/RwgSgUIl0xrSlXIT/9QzvYSA==",
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.62.4.tgz",
+      "integrity": "sha512-qPzHqdj9rfUD+w79dtE07zi/kFwKyCJqplp5K5ygeLTp7jLpAoc16OAH39HSmRC9UpozaecsleI8uAdEj6v2yw==",
       "cpu": [
         "x64"
       ],
@@ -2152,17 +2196,21 @@
       "optional": true,
       "os": [
         "win32"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
+      ]
     },
-    "node_modules/@rolldown/pluginutils": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.1.tgz",
-      "integrity": "sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==",
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.62.4.tgz",
+      "integrity": "sha512-zD6NdeWEByGE9QF9vCrlJ5YQB4oq9q91kPZS37Jwj5hOkvR1lTBSpsKhKDw4IJtbQ35LsTS1HD9DZYGKIshU1Q==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
     },
     "node_modules/@rtsao/scc": {
       "version": "1.1.0",
@@ -3841,8 +3889,8 @@
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
       "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
-      "devOptional": true,
       "license": "Apache-2.0",
+      "optional": true,
       "engines": {
         "node": ">=8"
       }
@@ -4113,7 +4161,6 @@
       "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "esbuild": "bin/esbuild"
       },
@@ -5971,287 +6018,26 @@
         "node": ">= 0.8.0"
       }
     },
-    "node_modules/lightningcss": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.32.0.tgz",
-      "integrity": "sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==",
+    "node_modules/locate-path": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz",
+      "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==",
       "dev": true,
-      "license": "MPL-2.0",
+      "license": "MIT",
       "dependencies": {
-        "detect-libc": "^2.0.3"
-      },
-      "engines": {
-        "node": ">= 12.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/parcel"
+        "p-locate": "^5.0.0"
       },
-      "optionalDependencies": {
-        "lightningcss-android-arm64": "1.32.0",
-        "lightningcss-darwin-arm64": "1.32.0",
-        "lightningcss-darwin-x64": "1.32.0",
-        "lightningcss-freebsd-x64": "1.32.0",
-        "lightningcss-linux-arm-gnueabihf": "1.32.0",
-        "lightningcss-linux-arm64-gnu": "1.32.0",
-        "lightningcss-linux-arm64-musl": "1.32.0",
-        "lightningcss-linux-x64-gnu": "1.32.0",
-        "lightningcss-linux-x64-musl": "1.32.0",
-        "lightningcss-win32-arm64-msvc": "1.32.0",
-        "lightningcss-win32-x64-msvc": "1.32.0"
-      }
-    },
-    "node_modules/lightningcss-android-arm64": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/lightningcss-android-arm64/-/lightningcss-android-arm64-1.32.0.tgz",
-      "integrity": "sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MPL-2.0",
-      "optional": true,
-      "os": [
-        "android"
-      ],
       "engines": {
-        "node": ">= 12.0.0"
+        "node": ">=10"
       },
       "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/parcel"
+        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/lightningcss-darwin-arm64": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.32.0.tgz",
-      "integrity": "sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MPL-2.0",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": ">= 12.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/parcel"
-      }
-    },
-    "node_modules/lightningcss-darwin-x64": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.32.0.tgz",
-      "integrity": "sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MPL-2.0",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": ">= 12.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/parcel"
-      }
-    },
-    "node_modules/lightningcss-freebsd-x64": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.32.0.tgz",
-      "integrity": "sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MPL-2.0",
-      "optional": true,
-      "os": [
-        "freebsd"
-      ],
-      "engines": {
-        "node": ">= 12.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/parcel"
-      }
-    },
-    "node_modules/lightningcss-linux-arm-gnueabihf": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.32.0.tgz",
-      "integrity": "sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==",
-      "cpu": [
-        "arm"
-      ],
-      "dev": true,
-      "license": "MPL-2.0",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">= 12.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/parcel"
-      }
-    },
-    "node_modules/lightningcss-linux-arm64-gnu": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.32.0.tgz",
-      "integrity": "sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MPL-2.0",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">= 12.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/parcel"
-      }
-    },
-    "node_modules/lightningcss-linux-arm64-musl": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.32.0.tgz",
-      "integrity": "sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MPL-2.0",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">= 12.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/parcel"
-      }
-    },
-    "node_modules/lightningcss-linux-x64-gnu": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.32.0.tgz",
-      "integrity": "sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MPL-2.0",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">= 12.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/parcel"
-      }
-    },
-    "node_modules/lightningcss-linux-x64-musl": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.32.0.tgz",
-      "integrity": "sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MPL-2.0",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">= 12.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/parcel"
-      }
-    },
-    "node_modules/lightningcss-win32-arm64-msvc": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.32.0.tgz",
-      "integrity": "sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MPL-2.0",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">= 12.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/parcel"
-      }
-    },
-    "node_modules/lightningcss-win32-x64-msvc": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.32.0.tgz",
-      "integrity": "sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MPL-2.0",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">= 12.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/parcel"
-      }
-    },
-    "node_modules/locate-path": {
-      "version": "6.0.0",
-      "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz",
-      "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "p-locate": "^5.0.0"
-      },
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
-    "node_modules/lodash.merge": {
-      "version": "4.6.2",
-      "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz",
-      "integrity": "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==",
+    "node_modules/lodash.merge": {
+      "version": "4.6.2",
+      "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz",
+      "integrity": "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==",
       "dev": true,
       "license": "MIT"
     },
@@ -7155,38 +6941,50 @@
         "node": ">=0.10.0"
       }
     },
-    "node_modules/rolldown": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.1.5.tgz",
-      "integrity": "sha512-t9z29cJjXf/vxQ8dyhCSpt6H6aSwHTk8cT5I3iy6SMXuFpk5mB6PL6XfC8PCwrPTx93udwKUm9HRteAlTGBLiA==",
+    "node_modules/rollup": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.62.4.tgz",
+      "integrity": "sha512-RXOqwaPsBGjMNMa4sQjDjHieHEZDFoj/Rdr46l2MU5DfEs16wHJPC2RPTPHWhNl+M3aI472LLqFkFKut4SblOg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@oxc-project/types": "=0.139.0",
-        "@rolldown/pluginutils": "^1.0.0"
+        "@types/estree": "1.0.9"
       },
       "bin": {
-        "rolldown": "bin/cli.mjs"
+        "rollup": "dist/bin/rollup"
       },
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": ">=18.0.0",
+        "npm": ">=8.0.0"
       },
       "optionalDependencies": {
-        "@rolldown/binding-android-arm64": "1.1.5",
-        "@rolldown/binding-darwin-arm64": "1.1.5",
-        "@rolldown/binding-darwin-x64": "1.1.5",
-        "@rolldown/binding-freebsd-x64": "1.1.5",
-        "@rolldown/binding-linux-arm-gnueabihf": "1.1.5",
-        "@rolldown/binding-linux-arm64-gnu": "1.1.5",
-        "@rolldown/binding-linux-arm64-musl": "1.1.5",
-        "@rolldown/binding-linux-ppc64-gnu": "1.1.5",
-        "@rolldown/binding-linux-s390x-gnu": "1.1.5",
-        "@rolldown/binding-linux-x64-gnu": "1.1.5",
-        "@rolldown/binding-linux-x64-musl": "1.1.5",
-        "@rolldown/binding-openharmony-arm64": "1.1.5",
-        "@rolldown/binding-wasm32-wasi": "1.1.5",
-        "@rolldown/binding-win32-arm64-msvc": "1.1.5",
-        "@rolldown/binding-win32-x64-msvc": "1.1.5"
+        "@napi-rs/lzma-linux-x64-gnu": "1.5.1",
+        "@rollup/rollup-android-arm-eabi": "4.62.4",
+        "@rollup/rollup-android-arm64": "4.62.4",
+        "@rollup/rollup-darwin-arm64": "4.62.4",
+        "@rollup/rollup-darwin-x64": "4.62.4",
+        "@rollup/rollup-freebsd-arm64": "4.62.4",
+        "@rollup/rollup-freebsd-x64": "4.62.4",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.62.4",
+        "@rollup/rollup-linux-arm-musleabihf": "4.62.4",
+        "@rollup/rollup-linux-arm64-gnu": "4.62.4",
+        "@rollup/rollup-linux-arm64-musl": "4.62.4",
+        "@rollup/rollup-linux-loong64-gnu": "4.62.4",
+        "@rollup/rollup-linux-loong64-musl": "4.62.4",
+        "@rollup/rollup-linux-ppc64-gnu": "4.62.4",
+        "@rollup/rollup-linux-ppc64-musl": "4.62.4",
+        "@rollup/rollup-linux-riscv64-gnu": "4.62.4",
+        "@rollup/rollup-linux-riscv64-musl": "4.62.4",
+        "@rollup/rollup-linux-s390x-gnu": "4.62.4",
+        "@rollup/rollup-linux-x64-gnu": "4.62.4",
+        "@rollup/rollup-linux-x64-musl": "4.62.4",
+        "@rollup/rollup-openbsd-x64": "4.62.4",
+        "@rollup/rollup-openharmony-arm64": "4.62.4",
+        "@rollup/rollup-win32-arm64-msvc": "4.62.4",
+        "@rollup/rollup-win32-ia32-msvc": "4.62.4",
+        "@rollup/rollup-win32-x64-gnu": "4.62.4",
+        "@rollup/rollup-win32-x64-msvc": "4.62.4",
+        "fsevents": "~2.3.2"
       }
     },
     "node_modules/router": {
@@ -8194,24 +7992,25 @@
       }
     },
     "node_modules/vite": {
-      "version": "8.1.4",
-      "resolved": "https://registry.npmjs.org/vite/-/vite-8.1.4.tgz",
-      "integrity": "sha512-bTT9PsdWO+MQMNG9ZXIP/qM9wGh37DFxTV/sPq9cFpHr3w4jkgef032PkAL9jAqhk3Nz8NQw3O8n6/xFkqO4QQ==",
+      "version": "6.4.3",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.3.tgz",
+      "integrity": "sha512-NTKlcQjlAK7MlQoyb6LgaqHc8sso/pVyUJYWMws3jg21uTJw/LddqIFPcPqP6PzpgbIcZyKI85sFE4HBrQDA8A==",
       "dev": true,
       "license": "MIT",
       "peer": true,
       "dependencies": {
-        "lightningcss": "^1.32.0",
-        "picomatch": "^4.0.5",
-        "postcss": "^8.5.16",
-        "rolldown": "~1.1.4",
-        "tinyglobby": "^0.2.17"
+        "esbuild": "^0.25.0",
+        "fdir": "^6.4.4",
+        "picomatch": "^4.0.2",
+        "postcss": "^8.5.3",
+        "rollup": "^4.34.9",
+        "tinyglobby": "^0.2.13"
       },
       "bin": {
         "vite": "bin/vite.js"
       },
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": "^18.0.0 || ^20.0.0 || >=22.0.0"
       },
       "funding": {
         "url": "https://github.com/vitejs/vite?sponsor=1"
@@ -8220,15 +8019,14 @@
         "fsevents": "~2.3.3"
       },
       "peerDependencies": {
-        "@types/node": "^20.19.0 || >=22.12.0",
-        "@vitejs/devtools": "^0.3.0",
-        "esbuild": "^0.27.0 || ^0.28.0",
+        "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0",
         "jiti": ">=1.21.0",
-        "less": "^4.0.0",
-        "sass": "^1.70.0",
-        "sass-embedded": "^1.70.0",
-        "stylus": ">=0.54.8",
-        "sugarss": "^5.0.0",
+        "less": "*",
+        "lightningcss": "^1.21.0",
+        "sass": "*",
+        "sass-embedded": "*",
+        "stylus": "*",
+        "sugarss": "*",
         "terser": "^5.16.0",
         "tsx": "^4.8.1",
         "yaml": "^2.4.2"
@@ -8237,18 +8035,15 @@
         "@types/node": {
           "optional": true
         },
-        "@vitejs/devtools": {
-          "optional": true
-        },
-        "esbuild": {
-          "optional": true
-        },
         "jiti": {
           "optional": true
         },
         "less": {
           "optional": true
         },
+        "lightningcss": {
+          "optional": true
+        },
         "sass": {
           "optional": true
         },
@@ -8272,6 +8067,490 @@
         }
       }
     },
+    "node_modules/vite/node_modules/@esbuild/aix-ppc64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz",
+      "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/android-arm": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.12.tgz",
+      "integrity": "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/android-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz",
+      "integrity": "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/android-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.12.tgz",
+      "integrity": "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/darwin-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz",
+      "integrity": "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/darwin-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz",
+      "integrity": "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/freebsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz",
+      "integrity": "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-arm": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz",
+      "integrity": "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz",
+      "integrity": "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-ia32": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz",
+      "integrity": "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-loong64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz",
+      "integrity": "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-mips64el": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz",
+      "integrity": "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-ppc64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz",
+      "integrity": "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-riscv64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz",
+      "integrity": "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-s390x": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz",
+      "integrity": "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz",
+      "integrity": "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/netbsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz",
+      "integrity": "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/openbsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz",
+      "integrity": "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz",
+      "integrity": "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/sunos-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz",
+      "integrity": "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/win32-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz",
+      "integrity": "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/win32-ia32": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz",
+      "integrity": "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/win32-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz",
+      "integrity": "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/esbuild": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz",
+      "integrity": "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.25.12",
+        "@esbuild/android-arm": "0.25.12",
+        "@esbuild/android-arm64": "0.25.12",
+        "@esbuild/android-x64": "0.25.12",
+        "@esbuild/darwin-arm64": "0.25.12",
+        "@esbuild/darwin-x64": "0.25.12",
+        "@esbuild/freebsd-arm64": "0.25.12",
+        "@esbuild/freebsd-x64": "0.25.12",
+        "@esbuild/linux-arm": "0.25.12",
+        "@esbuild/linux-arm64": "0.25.12",
+        "@esbuild/linux-ia32": "0.25.12",
+        "@esbuild/linux-loong64": "0.25.12",
+        "@esbuild/linux-mips64el": "0.25.12",
+        "@esbuild/linux-ppc64": "0.25.12",
+        "@esbuild/linux-riscv64": "0.25.12",
+        "@esbuild/linux-s390x": "0.25.12",
+        "@esbuild/linux-x64": "0.25.12",
+        "@esbuild/netbsd-arm64": "0.25.12",
+        "@esbuild/netbsd-x64": "0.25.12",
+        "@esbuild/openbsd-arm64": "0.25.12",
+        "@esbuild/openbsd-x64": "0.25.12",
+        "@esbuild/openharmony-arm64": "0.25.12",
+        "@esbuild/sunos-x64": "0.25.12",
+        "@esbuild/win32-arm64": "0.25.12",
+        "@esbuild/win32-ia32": "0.25.12",
+        "@esbuild/win32-x64": "0.25.12"
+      }
+    },
     "node_modules/vitest": {
       "version": "4.1.10",
       "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.10.tgz",
@@ -8553,18 +8832,18 @@
     },
     "packages/action": {
       "name": "@fixmap/action",
-      "version": "0.8.8",
+      "version": "0.8.9",
       "license": "MIT",
       "dependencies": {
-        "@aryam/fixmap-core": "0.8.8"
+        "@aryam/fixmap-core": "0.8.9"
       }
     },
     "packages/cli": {
       "name": "@aryam/fixmap",
-      "version": "0.8.8",
+      "version": "0.8.9",
       "license": "MIT",
       "dependencies": {
-        "@aryam/fixmap-core": "0.8.8",
+        "@aryam/fixmap-core": "0.8.9",
         "@modelcontextprotocol/sdk": "1.30.0"
       },
       "bin": {
@@ -8576,7 +8855,7 @@
     },
     "packages/core": {
       "name": "@aryam/fixmap-core",
-      "version": "0.8.8",
+      "version": "0.8.9",
       "license": "MIT",
       "devDependencies": {},
       "engines": {
diff --git a/package.json b/package.json
index 5dbbad9..6cab516 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "fixmap-workspace",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "private": true,
   "description": "Local-first repo context for coding agents: paste a GitHub issue URL to get ranked files, test routes, and risks.",
   "license": "MIT",
@@ -37,19 +37,21 @@
   ],
   "scripts": {
     "build": "npm run build:core && npm run build:cli && npm run build:action && npm run build:web",
+    "build:ci": "npm run build:core && npm run build:cli && npm run build:web",
     "build:core": "npm run build -w @aryam/fixmap-core",
     "build:cli": "npm run build -w @aryam/fixmap",
     "build:action": "npm run build:core && esbuild packages/action/src/index.ts --bundle --platform=node --target=node24 --format=esm --outfile=packages/action/dist/index.mjs --banner:js=\"import { createRequire as __fixmapCreateRequire } from 'module'; const require = __fixmapCreateRequire(import.meta.url);\"",
     "build:web": "npm run build:core && npm run build -w @fixmap/web",
-    "check:action-bundle": "npm run build:action && git diff --exit-code packages/action/dist/index.mjs",
+    "check:action-bundle": "node scripts/check-generated.mjs action",
     "check:action-metadata": "node scripts/check-action-metadata.mjs",
     "check:server-manifest": "node scripts/check-server-manifest.mjs",
     "audit:production": "npm audit --omit=dev --audit-level=high",
+    "audit:all": "npm audit --audit-level=high",
     "benchmark:scan": "npm run build:core && node scripts/benchmark-scan.mjs",
     "benchmark:check": "npm run build:core && node scripts/benchmark-scan.mjs --tier 1000 --check",
     "benchmark:savings": "npm run build:core && node scripts/benchmark-savings.mjs",
     "benchmark:savings:record": "npm run build:core && node scripts/benchmark-savings.mjs --record",
-    "ci": "npm run typecheck && npm test && npm run audit:production && npm run lint && npm run build && npm run check:action-metadata && npm run check:server-manifest && npm run check:action-bundle && npm run check:rendered && npm run smoke && npm run evaluate && npm run evaluate:adversarial:gate && npm run benchmark:check",
+    "ci": "npm run typecheck && npm test && npm run audit:all && npm run lint && npm run build:ci && npm run check:action-metadata && npm run check:server-manifest && npm run check:action-bundle && npm run check:rendered && npm run smoke && npm run evaluate && npm run evaluate:adversarial:gate && npm run benchmark:check",
     "evaluate": "npm run build:core && node scripts/evaluate.mjs",
     "evaluate:external": "npm run build:core && node scripts/evaluate-external.mjs",
     "evaluate:external:record": "npm run build:core && node scripts/evaluate-external.mjs --record",
@@ -65,10 +67,10 @@
     "evaluate:adversarial:gate": "npm run build:core && node scripts/evaluate-adversarial.mjs --gate --check-recorded",
     "evaluate:adversarial:record": "npm run build:core && node scripts/evaluate-adversarial.mjs --record",
     "render:examples": "npm run build:core && node scripts/render-honest-examples.mjs",
-    "check:rendered": "npm run render:examples && npm run build:cli && node scripts/render-demo.mjs && npm run render:benchmark-card && git diff --exit-code docs/assets examples/reports"
+    "check:rendered": "node scripts/check-generated.mjs rendered"
   },
   "engines": {
-    "node": "24.x"
+    "node": ">=20.11"
   },
   "overrides": {
     "next@16.2.11": {
@@ -77,7 +79,8 @@
     "fast-uri": "3.1.4",
     "js-yaml": "4.3.1",
     "nanoid": "3.3.17",
-    "sharp": "0.35.3"
+    "sharp": "0.35.3",
+    "vite": "6.4.3"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
diff --git a/packages/action/action.yml b/packages/action/action.yml
index f7b9aeb..e27b6e4 100644
--- a/packages/action/action.yml
+++ b/packages/action/action.yml
@@ -13,6 +13,12 @@ inputs:
       Verify mode only. Path to the JSON plan this change was made from, usually restored
       from an artifact saved by an earlier plan step.
     required: false
+  fail-on:
+    description: >-
+      Verify mode only. error (default) fails only on error findings; warning also fails
+      when verification raises advisory warnings such as no-test-changed.
+    required: false
+    default: error
   issue:
     description: >-
       Issue, prompt, or review context for FixMap. Accepts a public GitHub issue or pull
@@ -64,7 +70,7 @@ inputs:
     required: false
 outputs:
   report:
-    description: The complete FixMap report, or verification, in the selected format.
+    description: The bounded FixMap report, or verification, in the selected format.
   context-count:
     description: Number of context files returned. Plan mode only.
   test-route-count:
diff --git a/packages/action/dist/index.mjs b/packages/action/dist/index.mjs
index c805700..4ab1ecd 100644
--- a/packages/action/dist/index.mjs
+++ b/packages/action/dist/index.mjs
@@ -2,7 +2,7 @@ import { createRequire as __fixmapCreateRequire } from 'module'; const require =
 
 // packages/action/src/runner.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
-import { appendFileSync, readFileSync } from "node:fs";
+import { appendFileSync, readFileSync, statSync } from "node:fs";
 import { resolve as resolve3 } from "node:path";
 
 // packages/core/dist/plan.js
@@ -92,8 +92,131 @@ function globToRegExp(glob) {
   return source;
 }
 
+// packages/core/dist/markdown.js
+function markdownCode(value) {
+  const longestRun = Math.max(0, ...[...value.matchAll(/`+/g)].map((match) => match[0].length));
+  const fence = "`".repeat(longestRun + 1);
+  const needsPadding = value.startsWith("`") || value.endsWith("`") || value.startsWith(" ") || value.endsWith(" ");
+  return `${fence}${needsPadding ? " " : ""}${value}${needsPadding ? " " : ""}${fence}`;
+}
+
+// packages/core/dist/paths.js
+var ALWAYS_IGNORED_DIRS = /* @__PURE__ */ new Set([".cache", ".git", ".venv", "node_modules"]);
+var LOCKFILE_NAMES = /* @__PURE__ */ new Set([
+  "package-lock.json",
+  "npm-shrinkwrap.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lock",
+  "bun.lockb"
+]);
+var GENERATED_DIRS = /* @__PURE__ */ new Set([
+  ".idea",
+  ".netlify",
+  ".next",
+  ".nuxt",
+  ".output",
+  ".turbo",
+  ".vercel",
+  ".vscode",
+  "build",
+  "coverage",
+  "dist",
+  "target",
+  "vendor"
+]);
+var SOURCE_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".cjs",
+  ".cs",
+  ".css",
+  ".cts",
+  ".go",
+  ".gradle",
+  ".java",
+  ".js",
+  ".json",
+  ".jsx",
+  ".md",
+  ".mjs",
+  ".mts",
+  ".php",
+  ".py",
+  ".rb",
+  ".rs",
+  ".svelte",
+  ".ts",
+  ".tsx",
+  ".vue",
+  ".yaml",
+  ".yml"
+]);
+var BACKUP_SEGMENT_WORDS = /* @__PURE__ */ new Set([
+  "archive",
+  "archived",
+  "archives",
+  "backup",
+  "backups",
+  "bak",
+  "deprecated",
+  "legacy",
+  "old",
+  "quarantine"
+]);
+var BACKUP_FILE_PATTERNS = [
+  /\.(?:bak|orig|rej|old|save|swp)$/i,
+  /~$/,
+  /\bconflicted copy\b/i,
+  /\bconflict(?:ed)?[-_ ]copy\b/i,
+  // A bare `-copy`/`_copy` is an ordinary module name (`deep-copy.ts`). Sync clients use
+  // a space before "copy", or add a numbered suffix to the hyphen/underscore form.
+  /(?: copy|[-_]copy\s*\(\d+\))\.[^.]+$/i,
+  /\s\(\d+\)\.[^.]+$/
+];
+function segmentWords(segment) {
+  return segment.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+function directorySegments(path) {
+  return path.split("/").slice(0, -1);
+}
+function isGeneratedPath(path) {
+  return directorySegments(path).some((segment) => GENERATED_DIRS.has(segment.toLowerCase())) || isRecordedEvaluationOutput(path);
+}
+function isRecordedEvaluationOutput(path) {
+  return /^benchmarks\/[^/]+\/(?:results|savings-results)\.json$/i.test(path);
+}
+var SOURCE_ROOT_DIRS = /* @__PURE__ */ new Set(["lib", "source", "src"]);
+function moduleStem(path) {
+  const segments = path.replace(/\.[^./]+$/, "").split("/");
+  const rootIndex = segments.findIndex((segment) => {
+    const normalized = segment.toLowerCase();
+    return GENERATED_DIRS.has(normalized) || SOURCE_ROOT_DIRS.has(normalized);
+  });
+  if (rootIndex !== -1)
+    segments.splice(rootIndex, 1);
+  return segments.join("/");
+}
+function pathMatchesMention(path, mention) {
+  const normalizedPath = path.replace(/\\/g, "/").toLowerCase();
+  const normalizedMention = mention.replace(/\\/g, "/").toLowerCase();
+  if (normalizedPath === normalizedMention || normalizedPath.endsWith(`/${normalizedMention}`) || normalizedPath.includes("/") && normalizedMention.endsWith(`/${normalizedPath}`))
+    return true;
+  if (!normalizedMention.includes("/") && !normalizedMention.includes(".")) {
+    const fileName = normalizedPath.split("/").at(-1) ?? "";
+    return fileName.replace(/\.[^.]+$/, "") === normalizedMention;
+  }
+  return false;
+}
+function isBackupPath(path) {
+  const inBackupDirectory = directorySegments(path).some((segment) => segmentWords(segment).some((word) => BACKUP_SEGMENT_WORDS.has(word)));
+  if (inBackupDirectory) {
+    return true;
+  }
+  const fileName = path.split("/").pop() ?? "";
+  return BACKUP_FILE_PATTERNS.some((pattern) => pattern.test(fileName));
+}
+
 // packages/core/dist/signals.js
-var TOKEN_SPLIT = /[^a-zA-Z0-9]+/g;
+var TOKEN_SPLIT = /[^\p{L}\p{N}]+/gu;
 var STOP_WORDS = /* @__PURE__ */ new Set([
   "add",
   "all",
@@ -110,7 +233,6 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "but",
   "can",
   "cannot",
-  "case",
   "catch",
   "class",
   "const",
@@ -118,8 +240,6 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "codebase",
   "could",
   "debugger",
-  "default",
-  "delete",
   "did",
   "doe",
   "does",
@@ -135,7 +255,6 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "for",
   "from",
   "function",
-  "get",
   "github",
   "got",
   "had",
@@ -162,7 +281,6 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "more",
   "most",
   "must",
-  "name",
   "namespace",
   "new",
   "node",
@@ -175,15 +293,12 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "our",
   "out",
   "over",
-  "package",
   "packages",
   "private",
   "quality",
   "protected",
-  "public",
   "readonly",
   "return",
-  "run",
   "same",
   "she",
   "should",
@@ -209,7 +324,6 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "throw",
   "true",
   "try",
-  "type",
   "typeof",
   "under",
   "undefined",
@@ -234,9 +348,10 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "your"
 ]);
 var MAX_FILE_MENTION_LENGTH = 200;
-var FILE_MENTION_PATTERN = new RegExp(`[A-Za-z0-9_@$][A-Za-z0-9_.$/\\\\-]{0,${MAX_FILE_MENTION_LENGTH}}\\.(?:[cm]?[jt]sx?|json|ya?ml|mdx?|css|scss|less|html|py|rb|rs|go|java|kt|c|cc|cpp|h|hpp|d\\.ts)\\b`, "g");
+var FILE_MENTION_EXTENSIONS = [...SOURCE_FILE_EXTENSIONS].map((extension) => extension.slice(1).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).sort((left, right) => right.length - left.length).join("|");
+var FILE_MENTION_PATTERN = new RegExp(`(?:[A-Za-z]:[\\\\/]|[\\\\/])?[A-Za-z0-9_@$][A-Za-z0-9_.$/\\\\-]{0,${MAX_FILE_MENTION_LENGTH}}\\.(?:${FILE_MENTION_EXTENSIONS}|d\\.ts)\\b`, "g");
 var CONVENTIONAL_FILE_MENTION_PATTERN = /\b(?:AUTHORS|CHANGELOG|CODE_OF_CONDUCT|CONTRIBUTING|LICENSE|NOTICE|README|SECURITY|CODEOWNERS|Dockerfile|Gemfile|Jenkinsfile|Makefile|Procfile|Rakefile|Vagrantfile)\b/gi;
-var MEMBER_MENTION_PATTERN = /\b(?:window|globalThis|process|request|response|req|res|this)\.([$A-Za-z_][$A-Za-z0-9_$]*)\b/g;
+var MEMBER_MENTION_PATTERN = /(?<![\p{L}\p{N}_$])[\p{L}_$][\p{L}\p{N}_$]*\.([\p{L}_$][\p{L}\p{N}_$]*)(?![\p{L}\p{N}_$])/gu;
 var FILE_EXTENSIONS = /* @__PURE__ */ new Set([
   "c",
   "cc",
@@ -265,39 +380,22 @@ var FILE_EXTENSIONS = /* @__PURE__ */ new Set([
   "yaml",
   "yml"
 ]);
-var IDENTIFIER_PATTERN = /[A-Za-z_$][A-Za-z0-9_$]{4,}/g;
+var IDENTIFIER_PATTERN = /[\p{L}_$][\p{L}\p{N}_$]{4,}/gu;
 var MAX_EXACT_FRAGMENTS = 8;
 var MAX_IDENTIFIERS = 24;
-var TRAILING_E_VERB_STEMS = /* @__PURE__ */ new Set([
-  "bas",
-  "cach",
-  "chang",
-  "cod",
-  "contribut",
-  "creat",
-  "dat",
-  "fil",
-  "improv",
-  "invoic",
-  "mak",
-  "pars",
-  "remov",
-  "resolv",
-  "rout",
-  "siz",
-  "tim",
-  "updat"
-]);
 function extractTaskSignals(input) {
-  const prepared = prepareChecklistText(input.issueText ?? "");
+  const prepared = prepareChecklistText(redactSensitiveTaskText(input.issueText ?? ""));
   const issueText = prepared.text;
-  const taskText = [issueText, extractDiffContentLines(input.diffText ?? "")].join("\n");
+  const visibleIssueText = stripHtmlComments(issueText);
+  const issueSignalText = stripHttpUrls(visibleIssueText);
+  const diffSignalText = stripHttpUrls(redactSensitiveTaskText(extractDiffContentLines(input.diffText ?? "")));
+  const taskText = [issueSignalText, diffSignalText].join("\n");
   const tokens = tokenizeText(taskText);
   return {
     tokens,
     changedFiles: new Set(input.changedFiles ?? []),
-    fileMentions: extractFileMentions(issueText),
-    memberMentions: extractMemberMentions(issueText),
+    fileMentions: extractFileMentions(visibleIssueText),
+    memberMentions: extractMemberMentions(issueSignalText),
     exactFragments: extractExactFragments(taskText),
     identifiers: extractIdentifiers(taskText),
     uncheckedChecklistLinesRemoved: prepared.removed,
@@ -343,16 +441,20 @@ function extractIdentifiers(text) {
       continue;
     }
     const fragment = quoted.value.trim();
-    if (!/^[$A-Za-z_][$A-Za-z0-9_]*$/.test(fragment.trim())) {
+    if (!/^[\p{L}_$][\p{L}\p{N}_$]*$/u.test(fragment.trim())) {
       continue;
     }
-    if (!isDistinctiveIdentifier(fragment) && fragment.length < 8) {
+    if (!isDistinctiveIdentifier(fragment) && fragment.length < 6) {
       continue;
     }
     for (const match of fragment.matchAll(IDENTIFIER_PATTERN)) {
       addIdentifier(identifiers, match[0]);
     }
   }
+  for (const match of text.matchAll(/(?<![\p{L}\p{N}_$])([\p{L}_$][\p{L}\p{N}_$]{2,})\(/gu)) {
+    if (match[1])
+      addIdentifier(identifiers, match[1]);
+  }
   return identifiers;
 }
 function addIdentifier(identifiers, identifier) {
@@ -362,14 +464,26 @@ function addIdentifier(identifiers, identifier) {
   identifiers.add(identifier);
 }
 function isDistinctiveIdentifier(identifier) {
-  return /[0-9_$]/.test(identifier) || /[a-z][A-Z]/.test(identifier);
+  return /[0-9_$]/.test(identifier) || /[\p{Ll}][\p{Lu}]/u.test(identifier) || !/^[\x00-\x7F]+$/.test(identifier);
 }
 function isDistinctiveFragment(fragment) {
-  if (fragment.length < 6 || fragment.length > 96 || /\s/.test(fragment)) {
+  if (fragment.length < 6 || fragment.length > 160) {
     return false;
   }
-  const punctuationCount = [...fragment].filter((character) => /[^A-Za-z0-9_$]/.test(character)).length;
-  return punctuationCount >= 2 && /[A-Za-z0-9]/.test(fragment);
+  if (/\s/.test(fragment)) {
+    return fragment.trim().split(/\s+/).length >= 2 && /[\p{L}\p{N}]/u.test(fragment);
+  }
+  const punctuationCount = [...fragment].filter((character) => /[^\p{L}\p{N}$]/u.test(character)).length;
+  return punctuationCount >= 1 && /[\p{L}\p{N}]/u.test(fragment);
+}
+function redactSensitiveTaskText(text) {
+  return text.replace(/(https?:\/\/)[^/\s@]+@/gi, "$1").replace(/\b(?:ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{8,}\b/g, "[redacted]").replace(/\bAKIA[0-9A-Z]{16}\b/g, "[redacted]").replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, "[redacted]");
+}
+function stripHttpUrls(text) {
+  return text.includes("://") ? text.replace(/https?:\/\/[^\s<>()\[\]{}]+/gi, " [url] ") : text;
+}
+function stripHtmlComments(text) {
+  return text.includes("<!--") ? text.replace(/<!--[\s\S]*?-->/g, " ") : text;
 }
 function scanQuotedFragments(text) {
   const fragments = [];
@@ -377,19 +491,30 @@ function scanQuotedFragments(text) {
     let cursor = 0;
     while (cursor < line.length) {
       const delimiter = line[cursor];
-      if (delimiter !== '"' && delimiter !== "'" && delimiter !== "`") {
+      const closingDelimiter = delimiter === "\u201C" || delimiter === "\u201E" ? "\u201D" : delimiter === "\u2018" ? "\u2019" : delimiter === "\xAB" ? "\xBB" : delimiter;
+      if (!['"', "'", "`", "\u201C", "\u201E", "\u2018", "\xAB"].includes(delimiter ?? "")) {
+        cursor += 1;
+        continue;
+      }
+      if (delimiter === "'" && cursor > 0 && /[A-Za-z0-9]/.test(line[cursor - 1] ?? "")) {
         cursor += 1;
         continue;
       }
       let end = cursor + 1;
       while (end < line.length) {
-        if (line[end] === delimiter && !isEscaped(line, end)) {
+        if (line[end] === closingDelimiter && !isEscaped(line, end)) {
           break;
         }
         end += 1;
       }
-      fragments.push({ delimiter, value: line.slice(cursor + 1, end) });
-      cursor = end < line.length ? end + 1 : line.length;
+      if (end < line.length) {
+        fragments.push({ delimiter, value: line.slice(cursor + 1, end) });
+        cursor = end + 1;
+      } else {
+        if (delimiter !== "'")
+          fragments.push({ delimiter, value: line.slice(cursor + 1) });
+        cursor += 1;
+      }
     }
   }
   return fragments;
@@ -442,37 +567,75 @@ function extractDiffContentLines(diffText) {
   if (!diffText) {
     return "";
   }
-  return diffText.split(/\r?\n/).filter((line) => (line.startsWith("+") || line.startsWith("-")) && !line.startsWith("+++") && !line.startsWith("---")).join("\n");
+  return diffText.split(/\r?\n/).filter((line) => line.startsWith("+") && !line.startsWith("+++")).join("\n");
 }
 function tokenizeText(text) {
   return new Set(text.replace(/\bhttp\s*\/\s*([123])\b/gi, "http h$1").replace(/https?:\/\/[^\s<>()\[\]{}]+/gi, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(TOKEN_SPLIT).map((token) => token.trim()).filter((token) => isSearchableToken(token) && !STOP_WORDS.has(token)).map((token) => normalizeToken(token)).filter((token) => isSearchableToken(token) && !STOP_WORDS.has(token)));
 }
+function tokenizeIdentifier(identifier) {
+  return new Set(identifier.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(TOKEN_SPLIT).map((token) => normalizeToken(token.trim())).filter((token) => isSearchableToken(token)));
+}
 var MAX_SEARCHABLE_TOKEN_LENGTH = 64;
+var SHORT_SEARCHABLE_TOKENS = /* @__PURE__ */ new Set(["ci", "ui"]);
 function isSearchableToken(token) {
   if (token.length > MAX_SEARCHABLE_TOKEN_LENGTH) {
     return false;
   }
-  return token.length >= 3 || /^[a-z]\d$/i.test(token);
+  return token.length >= 3 || SHORT_SEARCHABLE_TOKENS.has(token.toLowerCase()) || /^[a-z]\d$/i.test(token);
 }
 function normalizeToken(token) {
+  if (token === "kubernetes")
+    return token;
+  if (token === "scss" || token === "sass" || token === "less")
+    return "css";
   if (token === "contributor" || token === "contributors")
     return "contribute";
   if (token.length > 5 && token.endsWith("ies"))
     return `${token.slice(0, -3)}y`;
+  if (token.length > 4 && token.endsWith("ied"))
+    return `${token.slice(0, -3)}y`;
   if (token.length > 5 && token.endsWith("ing"))
     return normalizeVerbStem(token.slice(0, -3));
-  if (token.length > 4 && token.endsWith("ed"))
+  if (token.length > 3 && token.endsWith("ed"))
     return normalizeVerbStem(token.slice(0, -2));
-  if (token.length > 4 && /(?:sses|shes|ches|xes|zes)$/.test(token))
+  if (token.length > 4 && /(?:sses|shes|ches|xes|zes)$/.test(token)) {
     return token.slice(0, -2);
+  }
   if (token.length > 3 && token.endsWith("s") && !/(?:ss|us|is)$/.test(token)) {
     return token.slice(0, -1);
   }
   return token;
 }
 function normalizeVerbStem(stem) {
-  const deduplicated = /([a-z])\1$/.test(stem) && !stem.endsWith("ss") ? stem.slice(0, -1) : stem;
-  return TRAILING_E_VERB_STEMS.has(deduplicated) ? `${deduplicated}e` : deduplicated;
+  const wasDoubled = /([a-z])\1$/.test(stem) && !stem.endsWith("ss");
+  if (wasDoubled) {
+    return stem.slice(0, -1);
+  }
+  const silentEStem = /(?:at|bl|iz|ap|ud|ac|ut|ov|et|dl|rg|ng|ic|out|rs|ch|lv)$/;
+  return silentEStem.test(stem) || stemMeasure(stem) === 1 && endsConsonantVowelConsonant(stem) ? `${stem}e` : stem;
+}
+function stemMeasure(word) {
+  let measure = 0;
+  let previousWasVowel = false;
+  for (let index = 0; index < word.length; index += 1) {
+    const vowel = isStemVowel(word, index);
+    if (previousWasVowel && !vowel)
+      measure += 1;
+    previousWasVowel = vowel;
+  }
+  return measure;
+}
+function endsConsonantVowelConsonant(word) {
+  if (word.length < 3)
+    return false;
+  const last = word.length - 1;
+  return !isStemVowel(word, last - 2) && isStemVowel(word, last - 1) && !isStemVowel(word, last) && !/[wxy]/.test(word[last] ?? "");
+}
+function isStemVowel(word, index) {
+  const character = word[index] ?? "";
+  if (/[aeiou]/.test(character))
+    return true;
+  return character === "y" && index > 0 && !isStemVowel(word, index - 1);
 }
 function tokenizePath(path) {
   return tokenizeText(path);
@@ -480,8 +643,9 @@ function tokenizePath(path) {
 
 // packages/core/dist/grounding.js
 var MAX_IDENTIFIER_MATCHED_FILES = 5;
-var VAGUE_TASK_PATTERN = /\b(?:improve|better|clean\s+up|cleanup|refactor|developer\s+experience|dx|general|overall|errors?|reliability|performance|codebase|quality|make|things?|please)\b/i;
-var VAGUE_TASK_TERMS = new RegExp(VAGUE_TASK_PATTERN.source, "gi");
+var VAGUE_TASK_PATTERN = /^\s*(?:please\s+)?(?:improve|make|clean(?:\s+(?:this|it|things?))?\s+up|cleanup|refactor)\b/i;
+var VAGUE_TASK_TERMS = /\b(?:please|improve|better|clean(?:\s+(?:this|it|things?))?\s+up|cleanup|refactor|developer\s+experience|dx|general|overall|codebase|quality|make|things?)\b/gi;
+var CLUSTERED_RANKING_MARGIN = 2;
 function analyzeTaskGrounding(repo, input) {
   const issueText = input.issueText ?? "";
   const signals = extractTaskSignals({
@@ -496,14 +660,14 @@ function analyzeTaskGrounding(repo, input) {
   const unverifiedIdentifiers = identifiers.filter((entry) => entry.status === "unverified").map((entry) => entry.identifier);
   const resolvedIdentifierCount = identifiers.filter((entry) => entry.status === "exact-definition" || entry.status === "exact-text").length;
   const hasMatchedFileMention = [...signals.fileMentions].some((mention) => repo.files.some((file) => pathMatchesMention(file.path, mention)));
-  const hasDirectAnchor = repo.changedFiles.length > 0 || hasMatchedFileMention || resolvedIdentifierCount > 0 || partiallyResolvedIdentifiers.length > 0;
+  const hasDirectAnchor = hasMatchedFileMention || resolvedIdentifierCount > 0 || partiallyResolvedIdentifiers.length > 0;
   const issueTokens = tokenizeText(issueText);
   const singleTokenHasRepoMatch = issueTokens.size === 1 && repo.files.some((file) => {
     const token = [...issueTokens][0];
     return tokenizeText(file.path).has(token) || tokenizeText(file.textSample).has(token);
   });
   const singleUnmatchedToken = issueTokens.size === 1 && !singleTokenHasRepoMatch;
-  const vague = !hasDirectAnchor && (isVagueTask(issueText) || singleUnmatchedToken);
+  const vague = !hasDirectAnchor && (isVagueTaskText(issueText) || singleUnmatchedToken);
   return {
     specificity: hasDirectAnchor ? "anchored" : vague ? "vague" : "descriptive",
     identifiers,
@@ -539,7 +703,7 @@ function buildRankingShape(contextFiles) {
   const runnerUpScore = sortedScores[1] ?? null;
   const topGap = topScore === null || runnerUpScore === null ? null : topScore - runnerUpScore;
   const thirdScore = sortedScores[2];
-  const clustered = topScore !== null && thirdScore !== void 0 && topScore - thirdScore <= 2;
+  const clustered = topScore !== null && thirdScore !== void 0 && topScore - thirdScore <= CLUSTERED_RANKING_MARGIN;
   return { topScore, runnerUpScore, topGap, clustered };
 }
 function buildNextAction(grounding, ranking, contextFiles, hasRoutedTests = true) {
@@ -547,7 +711,7 @@ function buildNextAction(grounding, ranking, contextFiles, hasRoutedTests = true
     return "Verify or correct the unresolved identifiers before editing ranked files.";
   }
   if (grounding.unverifiedIdentifiers.length > 0) {
-    return "Inspect the content-unread diagnostics and make those source files readable before trusting identifier-based recommendations.";
+    return "Inspect the content diagnostics and make those source files readable before trusting identifier-based recommendations.";
   }
   if (grounding.partiallyResolvedIdentifiers.length > 0) {
     return "Verify the partially matched symbol name in the leading file before editing.";
@@ -568,8 +732,8 @@ function buildNextAction(grounding, ranking, contextFiles, hasRoutedTests = true
   return "Add a concrete repository anchor and rerun FixMap.";
 }
 function groundIdentifier(repo, identifier) {
-  const definitionPattern = new RegExp(`\\b(?:export\\s+)?(?:async\\s+)?(?:const|let|var|function|class|interface|type|enum|def|fn|struct|trait)\\s+${escapeRegExp(identifier)}\\b`);
-  const exactPattern = new RegExp(`(^|[^$A-Za-z0-9_])${escapeRegExp(identifier)}(?=$|[^$A-Za-z0-9_])`);
+  const definitionPattern = new RegExp(`(?<![\\p{L}\\p{N}_$])(?:export\\s+)?(?:async\\s+)?(?:function\\s*\\*?\\s*|(?:const|let|var|class|interface|type|enum|def|fn|func|fun|struct|trait)\\s+)${escapeRegExp(identifier)}(?![\\p{L}\\p{N}_$])`, "u");
+  const exactPattern = new RegExp(`(?<![\\p{L}\\p{N}_$])${escapeRegExp(identifier)}(?![\\p{L}\\p{N}_$])`, "u");
   const definitionFiles = repo.files.filter((file) => definitionPattern.test(file.textSample)).map((file) => file.path).slice(0, MAX_IDENTIFIER_MATCHED_FILES);
   if (definitionFiles.length > 0) {
     return {
@@ -582,7 +746,7 @@ function groundIdentifier(repo, identifier) {
   return textFiles.length > 0 ? { identifier, status: "exact-text", matchedFiles: textFiles } : groundPartialOrUnverifiedIdentifier(repo, identifier);
 }
 function groundPartialOrUnverifiedIdentifier(repo, identifier) {
-  const identifierParts = tokenizeText(identifier);
+  const identifierParts = tokenizeIdentifier(identifier);
   const partialFiles = repo.files.filter((file) => hasDefinitionContainingTokens(file.textSample, identifierParts)).map((file) => file.path).slice(0, MAX_IDENTIFIER_MATCHED_FILES);
   if (identifierParts.size >= 2 && partialFiles.length > 0) {
     return {
@@ -600,13 +764,13 @@ function hasDefinitionContainingTokens(text, expectedTokens) {
   if (expectedTokens.size < 2) {
     return false;
   }
-  const definitionPattern = /\b(?:export\s+)?(?:async\s+)?(?:const|let|var|function|class|interface|type|enum|def|fn|struct|trait)\s+([$A-Za-z_][$A-Za-z0-9_]*)\b/g;
+  const definitionPattern = /(?<![\p{L}\p{N}_$])(?:export\s+)?(?:async\s+)?(?:function\s*\*?\s*|(?:const|let|var|class|interface|type|enum|def|fn|func|fun|struct|trait)\s+)([\p{L}_$][\p{L}\p{N}_$]*)(?![\p{L}\p{N}_$])/gu;
   for (const match of text.matchAll(definitionPattern)) {
     const name = match[1];
     if (!name) {
       continue;
     }
-    const candidateTokens = tokenizeText(name);
+    const candidateTokens = tokenizeIdentifier(name);
     if ([...expectedTokens].every((token) => candidateTokens.has(token))) {
       return true;
     }
@@ -620,25 +784,28 @@ function isAnchorIdentifier(identifier, issueText) {
   if (/[_$0-9]/.test(identifier)) {
     return true;
   }
+  if (!/^[\x00-\x7F]+$/.test(identifier)) {
+    return true;
+  }
   if (/^[a-z][A-Za-z0-9_$]*[A-Z]/.test(identifier)) {
     return true;
   }
   return [...identifier].filter((character) => /[A-Z]/.test(character)).length >= 3;
 }
 var MAX_RESIDUAL_TOKENS_FOR_VAGUE = 3;
-function isVagueTask(issueText) {
+function isVagueTaskText(issueText) {
   if (issueText.trim().length === 0 || !VAGUE_TASK_PATTERN.test(issueText)) {
     return false;
   }
+  if (/^\s*(?:please\s+)?(?:refactor|cleanup|clean\s+up)\s+(?:broke|breaks?|caused|causes|deleted?|deletes?|fails?|failed)\b/i.test(issueText)) {
+    return false;
+  }
   const residual = tokenizeText(issueText.replace(VAGUE_TASK_TERMS, " "));
   return residual.size <= MAX_RESIDUAL_TOKENS_FOR_VAGUE;
 }
 function removeIdentifiers(text, identifiers) {
   return identifiers.reduce((current, identifier) => current.replace(new RegExp(escapeRegExp(identifier), "g"), " "), text);
 }
-function pathMatchesMention(path, mention) {
-  return path === mention || path.endsWith(`/${mention}`) || mention.endsWith(`/${path}`);
-}
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -655,7 +822,12 @@ var ROOT_MANIFESTS = {
   // reads as a guess when the root was in fact explicit.
   "requirements.txt": "python",
   "pipfile": "python",
-  "package.json": "node"
+  "package.json": "node",
+  "gemfile": "ruby",
+  "composer.json": "php",
+  "pom.xml": "java",
+  "build.gradle": "java",
+  "build.gradle.kts": "java"
 };
 var EXTENSION_LANGUAGES = {
   ".py": "python",
@@ -666,7 +838,11 @@ var EXTENSION_LANGUAGES = {
   ".js": "node",
   ".jsx": "node",
   ".mjs": "node",
-  ".cjs": "node"
+  ".cjs": "node",
+  ".rb": "ruby",
+  ".php": "php",
+  ".java": "java",
+  ".cs": "dotnet"
 };
 function detectPrimaryLanguage(repo) {
   const manifests = rootManifestLanguages(repo.files);
@@ -699,7 +875,7 @@ function rootManifestLanguages(files) {
     if (file.path.includes("/")) {
       continue;
     }
-    const language = ROOT_MANIFESTS[file.path.toLowerCase()];
+    const language = languageForManifest(file.path.toLowerCase());
     if (language && !found.has(language)) {
       found.set(language, file.path);
     }
@@ -709,7 +885,7 @@ function rootManifestLanguages(files) {
 function nearestManifest(files, language) {
   const candidates = files.filter((file) => {
     const name = file.path.split("/").pop()?.toLowerCase() ?? "";
-    return ROOT_MANIFESTS[name] === language;
+    return languageForManifest(name) === language;
   }).sort((a, b) => a.path.split("/").length - b.path.split("/").length || a.path.localeCompare(b.path));
   const nearest = candidates[0];
   if (!nearest)
@@ -733,33 +909,48 @@ function countCodeFiles(files) {
 }
 function manifestTestCommand(language, packageDir, files = []) {
   if (language === "go") {
-    const manifest = nearestManifest(files, "go");
-    if (!manifest) {
+    const manifest2 = nearestManifest(files, "go");
+    if (!manifest2) {
       return { command: "go test ./...", reason: "Go source files; no go.mod was found" };
     }
-    if (manifest.packageDir) {
+    if (manifest2.packageDir) {
       return {
-        command: `go test -C ${manifest.packageDir} ./...`,
-        reason: `nearest module (${manifest.packageDir}) declared by ${manifest.path}`
+        command: `go test -C ${manifest2.packageDir} ./...`,
+        reason: `nearest module (${manifest2.packageDir}) declared by ${manifest2.path}`
       };
     }
     return { command: "go test ./...", reason: "go.mod at the repository root" };
   }
   if (language === "rust") {
-    return packageDir ? {
-      command: `cargo test --manifest-path ${packageDir}/Cargo.toml`,
-      reason: `nearest crate (${packageDir}) declared by Cargo.toml`
-    } : { command: "cargo test", reason: "Cargo.toml at the repository root" };
+    const requestedManifest = packageDir ? files.find((file) => file.path.toLowerCase() === `${packageDir}/cargo.toml`.toLowerCase()) : void 0;
+    const manifest2 = requestedManifest ? { path: requestedManifest.path, packageDir } : nearestManifest(files, "rust");
+    if (!manifest2)
+      return { command: "cargo test", reason: "Rust source files; no Cargo.toml was found" };
+    return manifest2.packageDir ? { command: `cargo test --manifest-path ${manifest2.path}`, reason: `nearest crate (${manifest2.packageDir}) declared by ${manifest2.path}` } : { command: "cargo test", reason: "Cargo.toml at the repository root" };
+  }
+  const manifest = nearestManifest(files, language);
+  if (language === "ruby" && manifest) {
+    return { command: "bundle exec rspec", reason: `${manifest.path} declares the Ruby bundle` };
+  }
+  if (language === "php" && manifest) {
+    return { command: "composer test", reason: `${manifest.path} declares Composer scripts` };
+  }
+  if (language === "java" && manifest) {
+    return manifest.path.toLowerCase().endsWith("pom.xml") ? { command: "mvn test", reason: `${manifest.path} declares a Maven project` } : { command: "./gradlew test", reason: `${manifest.path} declares a Gradle project` };
+  }
+  if (language === "dotnet") {
+    return manifest ? { command: `dotnet test${manifest.packageDir ? ` ${manifest.path}` : ""}`, reason: `${manifest.path} declares a .NET project` } : { command: "dotnet test", reason: ".NET source files; no project file was found" };
   }
   return void 0;
 }
 function suggestedRunner(language, files) {
   if (language === "python") {
-    const names = new Set(files.map((file) => file.path.split("/").pop()?.toLowerCase() ?? ""));
-    if (names.has("tox.ini")) {
+    const configs = files.filter((file) => ["tox.ini", "pytest.ini", "pyproject.toml", "setup.cfg"].includes(file.path.split("/").pop()?.toLowerCase() ?? "")).sort((a, b) => a.path.split("/").length - b.path.split("/").length || Number((b.path.split("/").pop()?.toLowerCase() ?? "") === "tox.ini") - Number((a.path.split("/").pop()?.toLowerCase() ?? "") === "tox.ini") || a.path.localeCompare(b.path));
+    const nearest = configs[0]?.path.split("/").pop()?.toLowerCase();
+    if (nearest === "tox.ini") {
       return "tox";
     }
-    if (names.has("pytest.ini") || names.has("pyproject.toml") || names.has("setup.cfg")) {
+    if (nearest) {
       return "pytest";
     }
     return "pytest or unittest";
@@ -770,8 +961,20 @@ function suggestedRunner(language, files) {
   if (language === "rust") {
     return "cargo test";
   }
+  if (language === "ruby")
+    return "bundle exec rspec";
+  if (language === "php")
+    return "composer test or vendor/bin/phpunit";
+  if (language === "java")
+    return "mvn test or ./gradlew test";
+  if (language === "dotnet")
+    return "dotnet test";
   return void 0;
 }
+function languageForManifest(path) {
+  const name = path.split("/").pop()?.toLowerCase() ?? path.toLowerCase();
+  return ROOT_MANIFESTS[name] ?? (/\.(?:csproj|fsproj|vbproj)$/.test(name) ? "dotnet" : void 0);
+}
 
 // packages/core/dist/import-graph.js
 var JS_EXTENSIONS = /* @__PURE__ */ new Set([".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".svelte", ".ts", ".tsx", ".vue"]);
@@ -791,17 +994,22 @@ var SPECIFIER_PATTERNS = [
 var MAX_GRAPH_FILES = 5e3;
 var MAX_EDGES_PER_FILE = 200;
 function buildImportGraph(files) {
-  const parseable = files.filter((file) => JS_EXTENSIONS.has(file.extension) && file.textSample.length > 0).slice(0, MAX_GRAPH_FILES);
+  const allParseable = files.filter((file) => JS_EXTENSIONS.has(file.extension) && file.textSample.length > 0);
+  const parseable = allParseable.slice(0, MAX_GRAPH_FILES);
   const repoPaths = new Set(files.map((file) => file.path));
+  const aliases = buildAliases(files);
+  const workspacePackages = buildWorkspacePackages(files);
   const imports = /* @__PURE__ */ new Map();
   const importedBy = /* @__PURE__ */ new Map();
+  let truncatedEdges = 0;
   for (const file of parseable) {
     let edges = 0;
     for (const specifier of extractSpecifiers(file.textSample)) {
       if (edges >= MAX_EDGES_PER_FILE) {
+        truncatedEdges += 1;
         break;
       }
-      const target = resolveSpecifier(file.path, specifier, repoPaths);
+      const target = resolveSpecifier(file.path, specifier, repoPaths, aliases, workspacePackages);
       if (!target || target === file.path) {
         continue;
       }
@@ -810,7 +1018,12 @@ function buildImportGraph(files) {
       edges += 1;
     }
   }
-  return { imports, importedBy };
+  return {
+    imports,
+    importedBy,
+    truncatedFiles: Math.max(0, allParseable.length - parseable.length),
+    truncatedEdges
+  };
 }
 function findImportProximity(graph, seedPaths) {
   const seeds = new Set(seedPaths);
@@ -849,19 +1062,37 @@ function extractSpecifiers(textSample) {
   for (const pattern of SPECIFIER_PATTERNS) {
     for (const match of textSample.matchAll(pattern)) {
       const specifier = match[1];
-      if (specifier && specifier.startsWith(".")) {
+      if (specifier) {
         specifiers.add(specifier);
       }
     }
   }
   return specifiers;
 }
-function resolveSpecifier(fromPath, specifier, repoPaths) {
+function resolveSpecifier(fromPath, specifier, repoPaths, aliases, workspacePackages) {
   const baseDir = fromPath.split("/").slice(0, -1).join("/");
-  const joined = normalizeSegments(baseDir ? `${baseDir}/${specifier}` : specifier);
-  if (joined === void 0 || joined === "") {
-    return void 0;
+  const roots = [];
+  if (specifier.startsWith(".")) {
+    const joined = normalizeSegments(baseDir ? `${baseDir}/${specifier}` : specifier);
+    if (joined)
+      roots.push(joined);
+  } else {
+    roots.push(...workspacePackages.get(specifier) ?? []);
+    for (const alias of aliases) {
+      if (!specifier.startsWith(alias.prefix) || !specifier.endsWith(alias.suffix))
+        continue;
+      const middle = specifier.slice(alias.prefix.length, specifier.length - alias.suffix.length || void 0);
+      roots.push(...alias.targets.map((target) => target.replace("*", middle)));
+    }
   }
+  for (const root of roots) {
+    const resolved = resolveCandidate(root, repoPaths);
+    if (resolved)
+      return resolved;
+  }
+  return void 0;
+}
+function resolveCandidate(joined, repoPaths) {
   const candidates = [joined];
   const lastSegment = joined.split("/").pop() ?? "";
   const dot = lastSegment.lastIndexOf(".");
@@ -879,6 +1110,50 @@ function resolveSpecifier(fromPath, specifier, repoPaths) {
   }
   return candidates.find((candidate) => repoPaths.has(candidate));
 }
+function buildWorkspacePackages(files) {
+  const packages = /* @__PURE__ */ new Map();
+  for (const file of files.filter((entry) => entry.path === "package.json" || entry.path.endsWith("/package.json"))) {
+    try {
+      const manifest = JSON.parse(file.textSample);
+      if (typeof manifest.name !== "string" || !manifest.name.trim())
+        continue;
+      const dir = file.path.split("/").slice(0, -1).join("/");
+      const declared = [manifest.source, manifest.module, manifest.main, manifest.types].filter((entry) => typeof entry === "string").map((entry) => normalizeSegments(dir ? `${dir}/${entry}` : entry)).filter((entry) => Boolean(entry));
+      packages.set(manifest.name, [
+        ...declared,
+        ...dir ? [`${dir}/src/index`, `${dir}/index`] : ["src/index", "index"]
+      ]);
+    } catch {
+    }
+  }
+  return packages;
+}
+function buildAliases(files) {
+  const aliases = [];
+  for (const file of files.filter((entry) => /(^|\/)(?:tsconfig|jsconfig)(?:\.[^/]*)?\.json$/i.test(entry.path))) {
+    try {
+      const config = JSON.parse(file.textSample);
+      const paths = config.compilerOptions?.paths;
+      if (!paths || typeof paths !== "object" || Array.isArray(paths))
+        continue;
+      const dir = file.path.split("/").slice(0, -1).join("/");
+      const baseUrl = typeof config.compilerOptions?.baseUrl === "string" ? config.compilerOptions.baseUrl : ".";
+      const base = normalizeSegments(dir ? `${dir}/${baseUrl}` : baseUrl) ?? "";
+      for (const [pattern, rawTargets] of Object.entries(paths)) {
+        if (!Array.isArray(rawTargets) || !rawTargets.every((entry) => typeof entry === "string"))
+          continue;
+        const star = pattern.indexOf("*");
+        aliases.push({
+          prefix: star === -1 ? pattern : pattern.slice(0, star),
+          suffix: star === -1 ? "" : pattern.slice(star + 1),
+          targets: rawTargets.map((target) => normalizeSegments(base ? `${base}/${target}` : target)).filter((target) => Boolean(target))
+        });
+      }
+    } catch {
+    }
+  }
+  return aliases;
+}
 function normalizeSegments(path) {
   const segments = [];
   for (const segment of path.split("/")) {
@@ -905,71 +1180,6 @@ function addEdge(edges, from, to) {
   }
 }
 
-// packages/core/dist/paths.js
-var ALWAYS_IGNORED_DIRS = /* @__PURE__ */ new Set([".cache", ".git", ".venv", "node_modules"]);
-var GENERATED_DIRS = /* @__PURE__ */ new Set([
-  ".idea",
-  ".netlify",
-  ".next",
-  ".nuxt",
-  ".output",
-  ".turbo",
-  ".vercel",
-  ".vscode",
-  "build",
-  "coverage",
-  "dist",
-  "target",
-  "vendor"
-]);
-var BACKUP_SEGMENT_WORDS = /* @__PURE__ */ new Set([
-  "archive",
-  "archived",
-  "archives",
-  "backup",
-  "backups",
-  "bak",
-  "deprecated",
-  "legacy",
-  "old",
-  "quarantine"
-]);
-var BACKUP_FILE_PATTERNS = [
-  /\.(?:bak|orig|rej|old|save|swp)$/i,
-  /~$/,
-  /\bconflicted copy\b/i,
-  /\bconflict(?:ed)?[-_ ]copy\b/i,
-  /[-_ ]copy(?:\s*\(\d+\))?\.[^.]+$/i,
-  /\s\(\d+\)\.[^.]+$/
-];
-function segmentWords(segment) {
-  return segment.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
-}
-function directorySegments(path) {
-  return path.split("/").slice(0, -1);
-}
-function isGeneratedPath(path) {
-  return directorySegments(path).some((segment) => GENERATED_DIRS.has(segment.toLowerCase())) || isRecordedEvaluationOutput(path);
-}
-function isRecordedEvaluationOutput(path) {
-  return /^benchmarks\/[^/]+\/(?:results|savings-results)\.json$/i.test(path);
-}
-var SOURCE_ROOT_DIRS = /* @__PURE__ */ new Set(["lib", "source", "src"]);
-function moduleStem(path) {
-  return path.replace(/\.[^./]+$/, "").split("/").filter((segment) => {
-    const normalized = segment.toLowerCase();
-    return !GENERATED_DIRS.has(normalized) && !SOURCE_ROOT_DIRS.has(normalized);
-  }).join("/");
-}
-function isBackupPath(path) {
-  const inBackupDirectory = directorySegments(path).some((segment) => segmentWords(segment).some((word) => BACKUP_SEGMENT_WORDS.has(word)));
-  if (inBackupDirectory) {
-    return true;
-  }
-  const fileName = path.split("/").pop() ?? "";
-  return BACKUP_FILE_PATTERNS.some((pattern) => pattern.test(fileName));
-}
-
 // packages/core/dist/rank.js
 var DEPLOYMENT_TERMS = [
   "deploy",
@@ -982,7 +1192,23 @@ var DEPLOYMENT_TERMS = [
   "serverless",
   "production"
 ];
-var LOCKFILES = /* @__PURE__ */ new Set(["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"]);
+var CONFIGURATION_TERMS = ["config", "configuration", "workflow", "action", "ci", "yaml"];
+var PRESENTATION_TERMS = [
+  "browser",
+  "button",
+  "client",
+  "display",
+  "form",
+  "frontend",
+  "layout",
+  "page",
+  "screen",
+  "ui",
+  "visitor",
+  "web",
+  "website"
+];
+var RANKING_SIGNAL_TERMS = [...DEPLOYMENT_TERMS, ...CONFIGURATION_TERMS, ...PRESENTATION_TERMS];
 var AUXILIARY_CODE_DIRS = /* @__PURE__ */ new Set(["demo", "demos", "example", "examples", "sample", "samples"]);
 var COMPILED_TO_SOURCE_MENTION_EXTENSIONS = {
   ".js": [".ts", ".tsx"],
@@ -994,10 +1220,13 @@ var MAX_FILES_PER_MENTION = 5;
 var MAX_PROXIMITY_SEEDS = 5;
 var IMPORT_PROXIMITY_BOOSTS = { 1: 4, 2: 2 };
 var EXAMPLE_CODE_PENALTY = 8;
+var AUXILIARY_REPRODUCTION_PENALTY = 20;
 var PRESENTATION_CODE_PENALTY = 8;
+var INTERACTIVE_PRESENTATION_BOOST = 4;
 var TYPE_DECLARATION_PENALTY = 4;
+var TYPE_DECLARATION_DIRECT_PENALTY = 8;
 var BACKUP_COPY_PENALTY = 10;
-var BUNDLED_OUTPUT_PENALTY = 12;
+var BUNDLED_OUTPUT_PENALTY = 16;
 var GENERATED_TWIN_PENALTY = 21;
 var GENERATED_TWIN_REASON = "generated build artifact; maintained source counterpart exists";
 var BUNDLED_LINE_LENGTH = 400;
@@ -1012,7 +1241,7 @@ var BUNDLE_MARKERS = [
   /\b__defProp\s*=/,
   /\/\/# sourceMappingURL=/
 ];
-var EXPLICIT_PATH_BOOST = 40;
+var EXPLICIT_PATH_BOOST = 60;
 var EXACT_LITERAL_BOOST = 8;
 var MEMBER_MENTION_BOOST = 8;
 var WIDESPREAD_TOKEN_SHARE = 0.85;
@@ -1020,10 +1249,13 @@ var DEFINITION_IDENTIFIER_BOOST = 24;
 var DEFINITION_LITERAL_BOOST = 8;
 var MAX_DEFINITION_IDENTIFIERS = 2;
 var TASK_MATCHED_DEFINITION_BOOST = 4;
-var HIGH_CONFIDENCE_MARGIN = 2;
+var HIGH_CONFIDENCE_MARGIN = CLUSTERED_RANKING_MARGIN;
 var REPORT_SCORE_CUTOFF = 4;
 var DEFAULT_CONTEXT_FILE_LIMIT = 8;
 function rankContextFiles(repo, input, limit = DEFAULT_CONTEXT_FILE_LIMIT, minScore = REPORT_SCORE_CUTOFF) {
+  return rankContextFilesDetailed(repo, input, limit, minScore).contextFiles;
+}
+function rankContextFilesDetailed(repo, input, limit = DEFAULT_CONTEXT_FILE_LIMIT, minScore = REPORT_SCORE_CUTOFF) {
   const exclude = input.exclude ?? NO_EXCLUSIONS;
   const signals = extractTaskSignals({
     issueText: input.issueText ?? "",
@@ -1036,37 +1268,31 @@ function rankContextFiles(repo, input, limit = DEFAULT_CONTEXT_FILE_LIMIT, minSc
     diffText: input.diffText ?? "",
     changedFiles: repo.changedFiles
   });
-  const mentionedPaths = matchMentionedPaths(signals.fileMentions, repo.files.map((file) => file.path));
-  const taskTargetsEvaluation = hasAny(taskTokens, ["benchmark", "benchmarks", "evaluation", "evaluate"]);
-  const scannable = repo.files.filter((file) => !exclude.excludes(file.path) && (mentionedPaths.has(file.path) || file.isSource && !file.isTest && !LOCKFILES.has(file.path.split("/").pop() ?? "") && (!file.path.startsWith("benchmarks/") || taskTargetsEvaluation)));
+  const mentionedPaths = matchMentionedPaths(signals.fileMentions, repo.files.map((file) => file.path), repo.root);
+  const scannable = repo.files.filter((file) => !exclude.excludes(file.path) && (mentionedPaths.has(file.path) || file.isSource && !file.isTest && !LOCKFILE_NAMES.has(file.path.split("/").pop() ?? "")));
   const maintainedStems = new Set(scannable.filter((file) => !isGeneratedPath(file.path) && !isBackupPath(file.path)).map((file) => moduleStem(file.path)));
-  const candidates = scannable.filter((file) => !isRecordedEvaluationOutput(file.path) && (mentionedPaths.has(file.path) || signals.changedFiles.has(file.path) || !isGeneratedPath(file.path) || !maintainedStems.has(moduleStem(file.path))));
-  const contentTokensByPath = new Map(candidates.map((file) => [file.path, tokenizeFileContent(file.textSample)]));
+  const candidateFiles = scannable.filter((file) => !isRecordedEvaluationOutput(file.path) && (mentionedPaths.has(file.path) || signals.changedFiles.has(file.path) || !isGeneratedPath(file.path) || !maintainedStems.has(moduleStem(file.path))));
+  const regexTokensByPath = new Map(candidateFiles.map((file) => [file.path, extractRegexTokens(file.textSample)]));
+  const contentTokensByPath = new Map(candidateFiles.map((file) => [
+    file.path,
+    tokenizeFileContent(file.textSample, regexTokensByPath.get(file.path) ?? /* @__PURE__ */ new Set())
+  ]));
   const commonTokens = findCommonTokens(contentTokensByPath);
   const allTaskTermsAreWidespread = taskTokens.size > 0 && [...taskTokens].every((token) => commonTokens.has(token));
   const definitionSignals = buildDefinitionSignals(signals.identifiers);
+  const memberSignals = [...signals.memberMentions].map((member) => ({
+    member,
+    pattern: exactIdentifierPattern(member)
+  }));
   const taskText = [input.issueText ?? "", input.diffText ?? ""].join("\n");
+  const exactFragmentOccurrences = new Map(signals.exactFragments.map((fragment) => [fragment, countOccurrences(taskText, fragment)]));
   const taskTargetsDocumentation = targetsDocumentation(taskText);
-  const taskTargetsConfiguration = hasAny(taskTokens, ["config", "configuration", "workflow", "action", "ci", "yaml"]);
-  const taskTargetsDeployment = hasAny(taskTokens, DEPLOYMENT_TERMS);
+  const taskTargetsConfiguration = hasAnyNormalized(taskTokens, taskText, CONFIGURATION_TERMS);
+  const taskTargetsDeployment = hasAnyNormalized(taskTokens, taskText, DEPLOYMENT_TERMS);
   const taskTargetsExamples = /\b(?:demos?|examples?|samples?)\b/i.test(taskText.replace(/\bfor example\b/gi, ""));
-  const taskTargetsPresentation = hasAny(taskTokens, [
-    "browser",
-    "button",
-    "client",
-    "display",
-    "form",
-    "frontend",
-    "layout",
-    "page",
-    "screen",
-    "ui",
-    "visitor",
-    "web",
-    "website"
-  ]);
+  const taskTargetsPresentation = hasAnyNormalized(taskTokens, taskText, PRESENTATION_TERMS);
   const taskTargetsTypeDeclarations = /\b(?:typescript|types?|type definitions?|declarations?|typings?|\.d\.(?:ts|mts|cts))\b/i.test(taskText);
-  const scored = candidates.map((file) => {
+  const scored = candidateFiles.map((file) => {
     const reasons = [];
     let score = 0;
     const isChanged = signals.changedFiles.has(file.path);
@@ -1088,6 +1314,16 @@ function rankContextFiles(repo, input, limit = DEFAULT_CONTEXT_FILE_LIMIT, minSc
     if (pathOverlap.length > 0) {
       score += pathOverlap.length * 3;
       reasons.push(`path matches task terms: ${pathOverlap.join(", ")}`);
+      if (pathOverlap.length >= 2) {
+        score += 4;
+        reasons.push("multiple task terms converge in the file path");
+        const fileName = file.path.split("/").at(-1)?.replace(/\.[^.]+$/, "") ?? "";
+        const fileNameTokens = tokenizeText(fileName);
+        if (fileNameTokens.size === 1 && [...fileNameTokens].some((token) => taskTokens.has(token))) {
+          score += 5;
+          reasons.push("file module name exactly matches a task term");
+        }
+      }
     }
     const contentTokens = contentTokensByPath.get(file.path) ?? /* @__PURE__ */ new Set();
     const contentOverlap = [...contentTokens].filter((token) => taskTokens.has(token) && (allTaskTermsAreWidespread || !commonTokens.has(token)));
@@ -1095,27 +1331,31 @@ function rankContextFiles(repo, input, limit = DEFAULT_CONTEXT_FILE_LIMIT, minSc
       score += Math.min(contentOverlap.length, 8) * 2;
       reasons.push(`content matches task terms: ${contentOverlap.slice(0, 8).join(", ")}`);
     }
-    const regexTokenOverlap = findRegexTokenOverlap(file.textSample, taskTokens);
+    const regexTokenOverlap = [...regexTokensByPath.get(file.path) ?? []].filter((token) => taskTokens.has(token)).slice(0, 2);
     if (regexTokenOverlap.length > 0) {
       score += Math.min(regexTokenOverlap.length, 2) * 12;
       reasons.push(`regex literal matches task tokens: ${regexTokenOverlap.join(", ")}`);
     }
-    const matchedMembers = [...signals.memberMentions].filter((member) => hasExactIdentifier(file.textSample, member)).slice(0, 3);
+    const matchedMembers = memberSignals.filter((signal) => signal.pattern.test(file.textSample)).map((signal) => signal.member).slice(0, 3);
     if (matchedMembers.length > 0) {
       score += matchedMembers.length * MEMBER_MENTION_BOOST;
       reasons.push(`contains task member names: ${matchedMembers.join(", ")}`);
     }
-    const exactLiteral = signals.exactFragments.filter((fragment) => file.textSample.includes(fragment)).sort((a, b) => countOccurrences(taskText, b) - countOccurrences(taskText, a) || b.length - a.length)[0];
+    const exactLiteral = signals.exactFragments.filter((fragment) => file.textSample.includes(fragment)).sort((a, b) => (exactFragmentOccurrences.get(b) ?? 0) - (exactFragmentOccurrences.get(a) ?? 0) || b.length - a.length)[0];
     if (exactLiteral) {
-      score += EXACT_LITERAL_BOOST * Math.min(3, countOccurrences(taskText, exactLiteral));
+      score += EXACT_LITERAL_BOOST * Math.min(3, exactFragmentOccurrences.get(exactLiteral) ?? 0);
       reasons.push(`contains exact task literal: ${previewFragment(exactLiteral)}`);
     }
     const definedIdentifiers = (file.kind === "documentation" ? [] : findDefinedIdentifiers(file.textSample, definitionSignals)).slice(0, MAX_DEFINITION_IDENTIFIERS);
     if (definedIdentifiers.length > 0) {
       score += definedIdentifiers.length * DEFINITION_IDENTIFIER_BOOST;
       reasons.push(`defines task identifiers: ${definedIdentifiers.join(", ")}`);
+      if (file.kind === "code" && !file.isTest && !isAuxiliaryCodePath(file.path) && !isTypeDeclarationPath(file.path) && !file.path.toLowerCase().startsWith("benchmarks/")) {
+        score += 4;
+        reasons.push("task identifier is defined in maintained implementation source");
+      }
     }
-    const taskMatchedDefinitions = signals.exactFragments.length === 0 && !taskTargetsDocumentation && !taskTargetsPresentation ? (file.kind === "documentation" ? [] : findTaskMatchedDefinitions(file.textSample, taskTokens)).filter((identifier) => !definedIdentifiers.includes(identifier)).slice(0, MAX_DEFINITION_IDENTIFIERS) : [];
+    const taskMatchedDefinitions = signals.exactFragments.length === 0 && !taskTargetsDocumentation ? (file.kind === "documentation" ? [] : findTaskMatchedDefinitions(file.textSample, taskTokens)).filter((identifier) => !definedIdentifiers.includes(identifier)).slice(0, MAX_DEFINITION_IDENTIFIERS) : [];
     if (taskMatchedDefinitions.length > 0) {
       score += taskMatchedDefinitions.length * TASK_MATCHED_DEFINITION_BOOST;
       reasons.push(`defines symbols matching task terms: ${taskMatchedDefinitions.join(", ")}`);
@@ -1143,7 +1383,7 @@ function rankContextFiles(repo, input, limit = DEFAULT_CONTEXT_FILE_LIMIT, minSc
     } else if (file.kind === "config" && !isChanged) {
       score -= 4;
     }
-    const isDeploymentConfig = file.path === "package.json" || DEPLOYMENT_TERMS.some((term) => pathTokens.has(term));
+    const isDeploymentConfig = file.path === "package.json" || DEPLOYMENT_TERMS.some((term) => [...tokenizeText(term)].some((token) => pathTokens.has(token)));
     if (taskTargetsDeployment && file.kind === "config" && !file.path.includes("/") && isDeploymentConfig) {
       score += 5;
       reasons.push("root configuration for a deployment-related task");
@@ -1151,14 +1391,31 @@ function rankContextFiles(repo, input, limit = DEFAULT_CONTEXT_FILE_LIMIT, minSc
     if (file.kind === "code" && isAuxiliaryCodePath(file.path) && !taskTargetsExamples && !taskTargetsPresentation && !isChanged && !mentionedPaths.has(file.path)) {
       score -= EXAMPLE_CODE_PENALTY;
       reasons.push("example or demo code deprioritized for an implementation task");
+      if (exactLiteral && definedIdentifiers.length > 0) {
+        score -= AUXILIARY_REPRODUCTION_PENALTY;
+        reasons.push("task reproduction evidence is weaker in auxiliary example code");
+      }
     }
-    if (isPresentationSurfacePath(file.path) && !taskTargetsPresentation && !taskTargetsExamples && !isChanged && !mentionedPaths.has(file.path)) {
-      score -= PRESENTATION_CODE_PENALTY;
-      reasons.push("presentation or demo surface deprioritized for a non-UI implementation task");
+    if (isPresentationSurfacePath(file.path)) {
+      if (taskTargetsPresentation) {
+        score += PRESENTATION_CODE_PENALTY;
+        reasons.push("presentation surface matches a UI-focused task");
+        if (isInteractivePresentation(file.textSample)) {
+          score += INTERACTIVE_PRESENTATION_BOOST;
+          reasons.push("interactive presentation surface matches the requested user flow");
+        }
+      } else if (!taskTargetsExamples && !isChanged && !mentionedPaths.has(file.path)) {
+        score -= PRESENTATION_CODE_PENALTY;
+        reasons.push("presentation or demo surface deprioritized for a non-UI implementation task");
+      }
     }
     if (isTypeDeclarationPath(file.path) && !taskTargetsTypeDeclarations && !isChanged && !mentionedPaths.has(file.path)) {
       score -= TYPE_DECLARATION_PENALTY;
       reasons.push("type declaration deprioritized for a runtime task");
+      if (definedIdentifiers.length > 0) {
+        score -= TYPE_DECLARATION_DIRECT_PENALTY;
+        reasons.push("runtime implementation preferred over a matching declaration");
+      }
     } else if (isTypeDeclarationPath(file.path) && taskTargetsTypeDeclarations && !isChanged) {
       score += TYPE_DECLARATION_PENALTY;
       reasons.push("type declaration matches a type-focused task");
@@ -1180,20 +1437,24 @@ function rankContextFiles(repo, input, limit = DEFAULT_CONTEXT_FILE_LIMIT, minSc
     return { path: file.path, score, isChanged, reasons };
   });
   applyImportProximity(scored, repo);
-  const ranked = scored.filter((file) => file.score >= minScore).sort((a, b) => b.score - a.score || a.path.localeCompare(b.path)).slice(0, limit);
-  const clustered = isClusteredRanking(ranked);
-  const leadIsContested = hasContestedLead(ranked);
-  return ranked.map((entry, position) => ({
+  const candidates = scored.filter((file) => file.score >= minScore).sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+  const ranking = buildRankingShape(candidates);
+  const clustered = ranking.clustered;
+  const leadIsContested = hasContestedLead(candidates);
+  const ranked = candidates.slice(0, limit);
+  const contextFiles = ranked.map((entry, position) => ({
     rank: position + 1,
     path: entry.path,
     score: entry.score,
     confidence: confidenceForEntry(entry, grounding, clustered, {
       position,
-      topScore: ranked[0]?.score ?? entry.score,
-      leadIsContested
+      topScore: candidates[0]?.score ?? entry.score,
+      leadIsContested,
+      issueIsVague: isVagueTaskText(input.issueText ?? "")
     }),
     reasons: entry.reasons.length > 0 ? entry.reasons : ["source file baseline"]
   }));
+  return { contextFiles, ranking };
 }
 function hasContestedLead(ranked) {
   const leader = ranked[0];
@@ -1206,13 +1467,22 @@ function hasDefinitionEvidence(entry) {
   return entry.reasons.some((reason) => reason.startsWith("defines task identifiers:") || reason.startsWith("exact task literal at definition:"));
 }
 function applyImportProximity(scored, repo) {
-  const seedEntries = scored.filter((entry) => entry.score >= 8 && hasDirectEvidence(entry)).sort((a, b) => b.score - a.score || a.path.localeCompare(b.path)).slice(0, MAX_PROXIMITY_SEEDS);
+  const directSeeds = scored.filter((entry) => entry.score >= 8 && hasDirectEvidence(entry)).sort((a, b) => b.score - a.score || a.path.localeCompare(b.path)).slice(0, MAX_PROXIMITY_SEEDS);
+  const seedEntries = directSeeds.length > 0 ? directSeeds : scored.filter((entry) => entry.score >= 8).sort((a, b) => b.score - a.score || a.path.localeCompare(b.path)).slice(0, 2);
   if (seedEntries.length === 0) {
     return;
   }
   const seeds = seedEntries.map((entry) => entry.path);
   const seedScores = new Map(seedEntries.map((entry) => [entry.path, entry.score]));
-  const proximity = findImportProximity(buildImportGraph(repo.files), seeds);
+  const graph = buildImportGraph(repo.files);
+  if ((graph.truncatedFiles > 0 || graph.truncatedEdges > 0) && !repo.diagnostics.some((entry) => entry.code === "import-graph-truncated")) {
+    repo.diagnostics.push({
+      code: "import-graph-truncated",
+      severity: "info",
+      message: `Import proximity was bounded: ${graph.truncatedFiles.toLocaleString()} parseable files and ${graph.truncatedEdges.toLocaleString()} high-fanout files were not fully traversed. Ranking still uses path and content evidence.`
+    });
+  }
+  const proximity = findImportProximity(graph, seeds);
   for (const entry of scored) {
     const hit = proximity.get(entry.path);
     if (hit) {
@@ -1234,9 +1504,6 @@ function proximityReason(hit) {
   return hit.direction === "imported-by" ? `imported by ranked file ${hit.seed}` : `imports ranked file ${hit.seed}`;
 }
 function confidenceForEntry(entry, grounding, clustered, shape) {
-  if (entry.isChanged) {
-    return "high";
-  }
   const hasMaintainedSourceTwin = entry.reasons.includes(GENERATED_TWIN_REASON);
   if (entry.reasons.includes("explicitly named in the task") && shape.position === 0 && !shape.leadIsContested && !hasMaintainedSourceTwin) {
     return "high";
@@ -1252,6 +1519,9 @@ function confidenceForEntry(entry, grounding, clustered, shape) {
   if (hasMaintainedSourceTwin) {
     confidence = capConfidence(confidence, "medium");
   }
+  if (!hasDirectEvidence(entry)) {
+    confidence = capConfidence(confidence, "medium");
+  }
   const supportedIdentifierCount = grounding.identifiers.filter((identifier) => identifier.status === "exact-definition" || identifier.status === "exact-text" || identifier.status === "partial-definition").length;
   if (grounding.unresolvedIdentifiers.length > 0) {
     if (supportedIdentifierCount === 0) {
@@ -1268,7 +1538,7 @@ function confidenceForEntry(entry, grounding, clustered, shape) {
   if (grounding.partiallyResolvedIdentifiers.length > 0) {
     confidence = capConfidence(confidence, "medium");
   }
-  if (grounding.specificity === "vague") {
+  if (grounding.specificity === "vague" || shape.issueIsVague) {
     return "low";
   }
   if (!grounding.scanComplete) {
@@ -1286,18 +1556,21 @@ function capConfidence(confidence, maximum) {
 function hasDirectEvidence(entry) {
   return entry.isChanged || entry.reasons.some((reason) => reason === "explicitly named in the task" || reason.startsWith("defines task identifiers:") || reason.startsWith("exact task literal at definition:"));
 }
-function isClusteredRanking(entries) {
-  const top = entries[0]?.score;
-  const third = entries[2]?.score;
-  return top !== void 0 && third !== void 0 && top - third <= 2;
-}
-function hasAny(tokens, values) {
-  return values.some((value) => tokens.has(value));
+function hasAnyNormalized(tokens, rawText, values) {
+  return values.some((value) => {
+    const normalized = tokenizeText(value);
+    if (normalized.size > 0 && [...normalized].every((token) => tokens.has(token)))
+      return true;
+    return new RegExp(`(^|[^\\p{L}\\p{N}_])${escapeRegExp2(value)}(?=$|[^\\p{L}\\p{N}_])`, "iu").test(rawText);
+  });
 }
-function matchMentionedPaths(mentions, repoPaths) {
+function matchMentionedPaths(mentions, repoPaths, repoRoot) {
   const matched = /* @__PURE__ */ new Set();
-  for (const mention of mentions) {
-    const exactMatches = repoPaths.filter((path) => pathMatchesMention2(path, mention));
+  for (const rawMention of mentions) {
+    const mention = repositoryRelativeMention(rawMention, repoRoot);
+    if (!mention)
+      continue;
+    const exactMatches = repoPaths.filter((path) => pathMatchesMention(path, mention));
     if (exactMatches.length > 0) {
       if (exactMatches.length <= MAX_FILES_PER_MENTION) {
         for (const path of exactMatches) {
@@ -1307,7 +1580,7 @@ function matchMentionedPaths(mentions, repoPaths) {
       continue;
     }
     const fallbackVariants = compiledSourcePathVariants(mention);
-    const fallbackMatches = repoPaths.filter((path) => fallbackVariants.some((variant) => pathMatchesMention2(path, variant)));
+    const fallbackMatches = repoPaths.filter((path) => fallbackVariants.some((variant) => pathMatchesMention(path, variant)));
     if (fallbackMatches.length > 0 && fallbackMatches.length <= MAX_FILES_PER_MENTION) {
       for (const path of fallbackMatches) {
         matched.add(path);
@@ -1316,17 +1589,13 @@ function matchMentionedPaths(mentions, repoPaths) {
   }
   return matched;
 }
-function pathMatchesMention2(path, mention) {
-  const normalizedPath = path.toLowerCase();
-  const normalizedMention = mention.toLowerCase();
-  if (normalizedPath === normalizedMention || normalizedPath.endsWith(`/${normalizedMention}`) || normalizedMention.endsWith(`/${normalizedPath}`)) {
-    return true;
-  }
-  if (!normalizedMention.includes("/") && !normalizedMention.includes(".")) {
-    const fileName = normalizedPath.split("/").at(-1) ?? "";
-    return fileName.replace(/\.[^.]+$/, "") === normalizedMention;
-  }
-  return false;
+function repositoryRelativeMention(mention, repoRoot) {
+  const normalizedMention = mention.replace(/\\/g, "/");
+  if (!/^(?:[A-Za-z]:\/|\/)/.test(normalizedMention))
+    return normalizedMention;
+  const normalizedRoot = repoRoot.replace(/\\/g, "/").replace(/\/$/, "");
+  const prefix = `${normalizedRoot}/`;
+  return normalizedMention.toLowerCase().startsWith(prefix.toLowerCase()) ? normalizedMention.slice(prefix.length) : void 0;
 }
 function compiledSourcePathVariants(path) {
   const lowerPath = path.toLowerCase();
@@ -1342,29 +1611,24 @@ function compiledSourcePathVariants(path) {
 function isAuxiliaryCodePath(path) {
   const parts = path.split("/");
   const stem = (parts.at(-1) ?? "").replace(/\.[^.]+$/, "").toLowerCase();
-  return parts.slice(0, -1).some((segment) => AUXILIARY_CODE_DIRS.has(segment.toLowerCase())) || /^(?:demo|example|sample)(?:[-_.]|$)/.test(stem);
+  const parentSegments = parts.slice(0, -1).map((segment) => segment.toLowerCase());
+  return parentSegments.some((segment) => AUXILIARY_CODE_DIRS.has(segment)) || stem === "sample-repo" && parentSegments.some((segment) => segment === "web" || segment === "website");
 }
 function isPresentationSurfacePath(path) {
   const name = path.split("/").at(-1)?.toLowerCase() ?? "";
-  return /^(?:page|layout|demo|sample-repo)\.[cm]?[jt]sx?$/.test(name) || /\.(?:css|less|sass|scss)$/.test(name);
+  return /^(?:page|layout|demo)\.[cm]?[jt]sx?$/.test(name) || /\.(?:css|less|sass|scss)$/.test(name);
 }
-function tokenizeFileContent(text) {
+function isInteractivePresentation(text) {
+  return /<(?:button|form|input|select|textarea)\b|\bon(?:Change|Click|Input|Submit)\s*=|\buseState\s*\(/.test(text);
+}
+function tokenizeFileContent(text, regexTokens) {
   const tokens = tokenizeText(text);
-  for (const match of text.matchAll(/\b([A-Za-z])\{(\d+),(\d+)\}/g)) {
-    const character = match[1]?.toLowerCase();
-    const minimum = Number(match[2]);
-    const maximum = Math.min(Number(match[3]), 8);
-    if (!character || !Number.isSafeInteger(minimum) || !Number.isSafeInteger(maximum)) {
-      continue;
-    }
-    for (let length = Math.max(3, minimum); length <= maximum; length += 1) {
-      tokens.add(character.repeat(length));
-    }
-  }
+  for (const token of regexTokens)
+    tokens.add(token);
   return tokens;
 }
-function findRegexTokenOverlap(text, taskTokens) {
-  const overlap = /* @__PURE__ */ new Set();
+function extractRegexTokens(text) {
+  const tokens = /* @__PURE__ */ new Set();
   for (const match of text.matchAll(/\b([A-Za-z])\{(\d+),(\d+)\}/g)) {
     const character = match[1]?.toLowerCase();
     const minimum = Number(match[2]);
@@ -1373,13 +1637,10 @@ function findRegexTokenOverlap(text, taskTokens) {
       continue;
     }
     for (let length = Math.max(3, minimum); length <= maximum; length += 1) {
-      const token = character.repeat(length);
-      if (taskTokens.has(token)) {
-        overlap.add(token);
-      }
+      tokens.add(character.repeat(length));
     }
   }
-  return [...overlap].slice(0, 2);
+  return tokens;
 }
 function isBundledOutput(textSample, path) {
   if (textSample.length < MIN_BUNDLE_SAMPLE_BYTES) {
@@ -1399,33 +1660,33 @@ function isTypeDeclarationPath(path) {
   return /\.d\.(?:ts|mts|cts)$/i.test(path);
 }
 function targetsDocumentation(taskText) {
-  const documentation = "(?:docs?|documentation|readme|guide|copy)";
+  const documentation = "(?:docs?|documentation|readme|guide)";
   const action = "(?:add|change|correct|document|edit|fix|improve|remove|revise|rewrite|update|write)";
   const defect = "(?:typos?|spelling|grammar|wording|broken links?)";
-  return new RegExp(`\\b${action}\\b[^\\n.]{0,60}\\b${documentation}\\b`, "i").test(taskText) || new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${action}\\b`, "i").test(taskText) || new RegExp(`\\b${defect}\\b[^\\n.]{0,60}\\b${documentation}\\b`, "i").test(taskText) || new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${defect}\\b`, "i").test(taskText);
+  return new RegExp(`\\b${action}\\b[^\\n.]{0,60}\\b${documentation}\\b`, "i").test(taskText) || new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${action}\\b`, "i").test(taskText) || new RegExp(`\\b${defect}\\b[^\\n.]{0,60}\\b${documentation}\\b`, "i").test(taskText) || new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${defect}\\b`, "i").test(taskText) || /\b(?:marketing|landing|website|page|button|label|headline|cta)\s+copy\b/i.test(taskText);
 }
 function buildDefinitionSignals(identifiers) {
   return [...identifiers].sort((a, b) => a.localeCompare(b)).map((identifier) => ({
     identifier,
-    pattern: new RegExp(`\\b(?:export\\s+)?(?:async\\s+)?(?:const|let|var|function|class|interface|type|enum|def|fn|struct|trait)\\s+${escapeRegExp2(identifier)}\\b`)
+    pattern: new RegExp(`(?<![\\p{L}\\p{N}_$])(?:export\\s+)?(?:async\\s+)?(?:function\\s*\\*?\\s*|(?:const|let|var|class|interface|type|enum|def|fn|func|fun|struct|trait)\\s+)${escapeRegExp2(identifier)}(?![\\p{L}\\p{N}_$])`, "u")
   }));
 }
 function findDefinedIdentifiers(text, signals) {
   return signals.filter((signal) => signal.pattern.test(text)).map((signal) => signal.identifier);
 }
-function hasExactIdentifier(text, identifier) {
-  return new RegExp(`(^|[^$A-Za-z0-9_])${escapeRegExp2(identifier)}(?=$|[^$A-Za-z0-9_])`).test(text);
+function exactIdentifierPattern(identifier) {
+  return new RegExp(`(?<![\\p{L}\\p{N}_$])${escapeRegExp2(identifier)}(?![\\p{L}\\p{N}_$])`, "u");
 }
 function findTaskMatchedDefinitions(text, taskTokens) {
   const definitions = /* @__PURE__ */ new Set();
-  const pattern = /\b(?:export\s+)?(?:async\s+)?(?:const|let|var|function|class|interface|type|enum|def|fn|struct|trait)\s+([$A-Za-z_][$A-Za-z0-9_]*)\b/g;
+  const pattern = /(?<![\p{L}\p{N}_$])(?:export\s+)?(?:async\s+)?(?:function\s*\*?\s*|(?:const|let|var|class|interface|type|enum|def|fn|func|fun|struct|trait)\s+)([\p{L}_$][\p{L}\p{N}_$]*)(?![\p{L}\p{N}_$])/gu;
   for (const match of text.matchAll(pattern)) {
     const identifier = match[1];
     if (!identifier) {
       continue;
     }
     const overlap = [...tokenizeText(identifier)].filter((token) => taskTokens.has(token));
-    if (overlap.length >= 2) {
+    if (overlap.length >= 2 || overlap.length === 1 && identifier.length >= 6) {
       definitions.add(identifier);
     }
   }
@@ -1479,19 +1740,29 @@ function isNearbyChangedFile(path, changedFiles) {
 }
 
 // packages/core/dist/test-gates.js
-var GATE_PATTERN = /\.(skipIf|runIf)\s*\(/;
+var CONDITIONAL_GATE_PATTERN = /\.(?:skipIf|runIf)\s*\(/;
+var UNCONDITIONAL_GATE_PATTERNS = [
+  /\b(?:it|test|describe|context)\.(?:skip|todo)\s*\(/,
+  /\b(?:xit|xtest|xdescribe|xcontext)\s*\(/,
+  /\bthis\.skip\s*\(/,
+  /@(?:pytest\.mark\.(?:skip|skipif)|unittest\.skip(?:If|Unless)?)\b/,
+  /\bt\.Skip(?:f|Now)?\s*\(/,
+  /#\[ignore(?:\s*=|\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)) {
+    const conditional = CONDITIONAL_GATE_PATTERN.test(file.textSample);
+    const unconditional = UNCONDITIONAL_GATE_PATTERNS.some((pattern) => pattern.test(file.textSample));
+    if (!file.isTest || !routed.has(file.path) || !conditional && !unconditional) {
       continue;
     }
     diagnostics.push({
       code: "gated-test-skipped",
       severity: "warning",
-      message: gateMessage(file.path, extractEnvNames(file.textSample))
+      message: unconditional ? `${file.path} contains skipped or ignored tests; the suggested test command will not exercise them until the skip is removed.` : gateMessage(file.path, extractEnvNames(file.textSample))
     });
   }
   return diagnostics;
@@ -1531,12 +1802,13 @@ function buildReportFromRepo(repo, input) {
     issueText: input.issueText,
     diffText: repo.diffText
   });
-  const contextFiles = grounding.specificity === "vague" ? [] : rankContextFiles(repo, {
+  const ranked = rankContextFilesDetailed(repo, {
     issueText: input.issueText,
     diffText: repo.diffText,
     exclude: input.exclude
   }, input.limit ?? DEFAULT_CONTEXT_FILE_LIMIT);
-  const ranking = buildRankingShape(contextFiles);
+  const contextFiles = ranked.contextFiles;
+  const ranking = ranked.ranking;
   const contextPaths = contextFiles.map((file) => file.path);
   const testRoutes = buildTestRoutes(repo, contextPaths);
   const routedTestPaths = [...new Set(testRoutes.flatMap((route) => route.relatedFiles))];
@@ -1553,7 +1825,7 @@ function buildReportFromRepo(repo, input) {
       ...findMissingTestRouteDiagnostics(repo, contextFiles, testRoutes),
       ...findTaskDiagnostics(repo, grounding, ranking),
       ...findTaskPreprocessingDiagnostics(input.issueText ?? ""),
-      ...grounding.specificity === "vague" ? [] : findEmptyResultDiagnostics(repo, contextFiles, input.issueText ?? "", input.exclude)
+      ...findEmptyResultDiagnostics(repo, contextFiles, input.issueText ?? "", input.exclude)
     ],
     analysis: {
       grounding,
@@ -1706,16 +1978,12 @@ function configuredJsRunner(files) {
   }
   return void 0;
 }
-var SCRIPT_PRIORITY = { test: 0, validation: 10 };
-var VALIDATION_SCRIPTS = /* @__PURE__ */ new Set(["typecheck", "check", "lint"]);
 function classifyScript(name) {
   const lower = name.toLowerCase();
   if (lower === "test" || lower === "tests")
     return { category: "test", exact: true };
   if (/^tests?:[a-z0-9:_-]+$/.test(lower))
     return { category: "test", exact: false };
-  if (VALIDATION_SCRIPTS.has(lower))
-    return { category: "validation", exact: true };
   return void 0;
 }
 function buildTestRoutes(repo, contextPaths) {
@@ -1728,28 +1996,20 @@ function buildTestRoutes(repo, contextPaths) {
     script,
     kind,
     proximity: packageProximity(script.packageDir, codeContextPaths),
-    priority: SCRIPT_PRIORITY[kind.category] + (kind.exact ? 0 : 1)
+    priority: kind.exact ? 0 : 1
   })).filter((candidate) => candidate.proximity >= 0).sort((a, b) => b.proximity - a.proximity || a.priority - b.priority || a.script.packageDir.localeCompare(b.script.packageDir));
-  const ordered = [
-    ...candidates.filter((candidate) => candidate.kind.category === "test"),
-    ...candidates.filter((candidate) => candidate.kind.category !== "test")
-  ];
   const commands = /* @__PURE__ */ new Set();
   const routes = [];
-  for (const { script, kind } of ordered) {
+  for (const { script } of candidates) {
     const command = formatScriptCommand(repo.packageManager, script.packageDir, script.name, script.packageName);
     if (commands.has(command))
       continue;
     commands.add(command);
-    const isTest = kind.category === "test";
     routes.push({
       command,
-      kind: isTest ? "test" : "validation",
+      kind: "test",
       reason: `${script.packageDir ? `nearest package (${script.packageDir})` : "repository root"} script named ${script.name}`,
-      // A lint route's related paths are the implementation it would check, never tests, so
-      // labeling them the same way let `no-test-changed` cite an implementation file as the
-      // test the plan had routed.
-      relatedFiles: scopeToPackage(isTest ? relatedTests : codeContextPaths, script.packageDir)
+      relatedFiles: scopeToPackage(relatedTests, script.packageDir)
     });
     if (routes.length === 3)
       break;
@@ -1783,25 +2043,26 @@ function nearestManifestDir(repo, contextPaths, manifest) {
   return manifestDirs.filter((dir) => contextPaths.some((path) => path.startsWith(`${dir}/`))).sort((a, b) => b.split("/").length - a.split("/").length || a.localeCompare(b))[0] ?? "";
 }
 var RISK_RULES = [
-  { area: "authentication", severity: "high", tokens: ["auth", "login", "password"], reason: "authentication-related files are affected" },
-  { area: "billing", severity: "high", tokens: ["billing", "payment", "invoice"], reason: "billing or payment-related files are affected" },
-  { area: "automation", severity: "medium", tokens: ["config", "workflow", "action"], reason: "configuration or CI automation files may affect developer workflows" },
-  { area: "data", severity: "high", tokens: ["migration", "schema", "database", "sql"], reason: "database or schema-related files may affect stored data" },
-  { area: "public-api", severity: "medium", tokens: ["api", "route", "public"], reason: "public interfaces or request handling may change" },
-  { area: "dependencies", severity: "medium", tokens: ["dependency", "lock", "package"], reason: "dependency changes can affect build and supply-chain behavior" }
+  { area: "authentication", severity: "high", terms: ["auth", "login", "password"], reason: "authentication-related files are affected" },
+  { area: "billing", severity: "high", terms: ["billing", "payment", "invoice"], reason: "billing or payment-related files are affected" },
+  { area: "automation", severity: "medium", terms: ["config", "workflow", "action", "ci"], reason: "configuration or CI automation files may affect developer workflows" },
+  { area: "data", severity: "high", terms: ["migration", "schema", "database", "sql"], reason: "database or schema-related files may affect stored data" },
+  { area: "public-api", severity: "medium", terms: ["api", "route", "public"], reason: "public interfaces or request handling may change" },
+  { area: "dependencies", severity: "medium", terms: ["dependency", "lock", "package"], reason: "dependency changes can affect build and supply-chain behavior" }
 ];
 var AUXILIARY_RISK_DIRS = /* @__PURE__ */ new Set(["demo", "demos", "example", "examples", "sample", "samples", "fixture", "fixtures"]);
 function carriesRiskEvidence(path) {
   return !path.split("/").slice(0, -1).some((segment) => AUXILIARY_RISK_DIRS.has(segment.toLowerCase()));
 }
 function buildRiskNotes(contextPaths, changedFiles = []) {
-  const contextTokens = new Set(contextPaths.filter(carriesRiskEvidence).flatMap((path) => [...tokenizePath(path)]));
-  const changedTokens = new Set(changedFiles.flatMap((path) => [...tokenizePath(path)]));
+  const contextTokens = new Set(contextPaths.filter(carriesRiskEvidence).flatMap((path) => [...riskTokens(path)]));
+  const changedTokens = new Set(changedFiles.flatMap((path) => [...riskTokens(path)]));
   const diffPresent = changedFiles.length > 0;
   const risks = [];
   for (const rule of RISK_RULES) {
-    const inChanged = rule.tokens.some((token) => changedTokens.has(token));
-    const inContext = rule.tokens.some((token) => contextTokens.has(token));
+    const terms = rule.terms.flatMap((term) => [...riskTokens(term)]);
+    const inChanged = terms.some((token) => changedTokens.has(token));
+    const inContext = terms.some((token) => contextTokens.has(token));
     if (!inChanged && !inContext) {
       continue;
     }
@@ -1822,10 +2083,16 @@ function pathsForRiskArea(area, paths) {
   if (!rule)
     return [];
   return paths.filter((path) => {
-    const tokens = tokenizePath(path);
-    return rule.tokens.some((token) => tokens.has(token));
+    const tokens = riskTokens(path);
+    return rule.terms.flatMap((term) => [...riskTokens(term)]).some((token) => tokens.has(token));
   });
 }
+function riskTokens(value) {
+  return /* @__PURE__ */ new Set([
+    ...tokenizePath(value),
+    ...value.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+  ]);
+}
 function packageProximity(packageDir, contextPaths) {
   if (!packageDir)
     return 1;
@@ -1869,13 +2136,13 @@ function renderMarkdownReport(report) {
     "",
     "## Context Files",
     "",
-    ...listOrEmpty(report.contextFiles.map((file) => `- \`${file.path}\` (${file.confidence} confidence, score ${file.score}): ${file.reasons.join("; ")}`)),
+    ...listOrEmpty(report.contextFiles.map((file) => `- ${markdownCode(file.path)} (${file.confidence} confidence, score ${file.score}): ${file.reasons.join("; ")}`)),
     "",
     "## Test Routes",
     "",
     ...listOrEmpty(report.testRoutes.map((route) => {
-      const related = route.relatedFiles.length > 0 ? ` Related: ${route.relatedFiles.map((path) => `\`${path}\``).join(", ")}.` : "";
-      return `- \`${route.command}\`: ${route.reason}.${related}`;
+      const related = route.relatedFiles.length > 0 ? ` Related: ${route.relatedFiles.map(markdownCode).join(", ")}.` : "";
+      return `- ${markdownCode(route.command)}: ${route.reason}.${related}`;
     })),
     "",
     "## Risk Map",
@@ -1884,7 +2151,7 @@ function renderMarkdownReport(report) {
     "",
     "## Changed Files",
     "",
-    ...listOrEmpty(report.changedFiles.map((path) => `- \`${path}\``)),
+    ...listOrEmpty(report.changedFiles.map((path) => `- ${markdownCode(path)}`)),
     ...report.analysis ? [
       "",
       "## Analysis",
@@ -1899,7 +2166,7 @@ function renderMarkdownReport(report) {
     "",
     ...listOrEmpty(report.diagnostics.flatMap((diagnostic) => [
       `- **${diagnostic.severity}** ${diagnostic.message}`,
-      ...(diagnostic.paths ?? []).slice(0, 8).map((path) => `  - \`${path}\``)
+      ...(diagnostic.paths ?? []).slice(0, 8).map((path) => `  - ${markdownCode(path)}`)
     ]))
   ];
   return `${lines.join("\n")}
@@ -1920,31 +2187,11 @@ import { mkdir, readdir, readFile, realpath, rename, stat, unlink, writeFile } f
 import { homedir } from "node:os";
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
-var WALK_IGNORED_DIRS = /* @__PURE__ */ new Set([...ALWAYS_IGNORED_DIRS, ...GENERATED_DIRS]);
-var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".cjs",
-  ".cs",
-  ".css",
-  ".cts",
-  ".go",
-  ".java",
-  ".js",
-  ".json",
-  ".jsx",
-  ".md",
-  ".mjs",
-  ".mts",
-  ".php",
-  ".py",
-  ".rb",
-  ".rs",
-  ".svelte",
-  ".ts",
-  ".tsx",
-  ".vue",
-  ".yaml",
-  ".yml"
+var WALK_IGNORED_DIRS = /* @__PURE__ */ new Set([
+  ...ALWAYS_IGNORED_DIRS,
+  ...[...GENERATED_DIRS].filter((directory) => directory !== "vendor")
 ]);
+var SOURCE_EXTENSIONS = SOURCE_FILE_EXTENSIONS;
 var CONVENTIONAL_DOCUMENT_NAMES = /* @__PURE__ */ new Set([
   "authors",
   "changelog",
@@ -1968,7 +2215,10 @@ var CONVENTIONAL_CONFIG_NAMES = /* @__PURE__ */ new Set([
   "makefile",
   "procfile",
   "rakefile",
-  "vagrantfile"
+  "vagrantfile",
+  "pom.xml",
+  "build.gradle",
+  "settings.gradle"
 ]);
 var SFC_EXTENSIONS = /* @__PURE__ */ new Set([".vue", ".svelte"]);
 var SFC_SCRIPT_BLOCK = /<script\b[^>]*>([\s\S]*?)<\/script>/gi;
@@ -1977,6 +2227,9 @@ var TEST_PATTERNS = [
   /\.spec\./,
   /(^|\/|\\)__tests__(\/|\\)/,
   /(^|\/|\\)tests?(\/|\\)/,
+  /(^|\/|\\)spec(\/|\\)/,
+  /_spec\.rb$/i,
+  /(?:Test\.java|Tests?\.cs|Test\.php)$/i,
   /_test\.go$/,
   /(^|\/|\\)(?:test_[^/\\]+|[^/\\]+_test)\.py$/
 ];
@@ -1985,7 +2238,7 @@ var MAX_DIFF_TEXT_CHARS = 2e5;
 var MAX_SCANNED_FILES = 25e3;
 var GIT_MAX_BUFFER = 10 * 1024 * 1024;
 var exec = promisify(execFile);
-var SCAN_CACHE_VERSION = 2;
+var SCAN_CACHE_VERSION = 3;
 var SCAN_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
 var SCAN_CACHE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
 var SCAN_CACHE_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json$/;
@@ -2045,7 +2298,7 @@ async function scanRepo(input) {
     files = await listFiles(repoRoot, diagnostics, internalCacheRoot, internalPaths);
     trackedFiles = await listTrackedPaths(repoRoot, internalPaths);
     packageScripts = await readPackageScripts(repoRoot, files, diagnostics);
-    packageManager = detectPackageManager(files);
+    packageManager = detectPackageManager(files, diagnostics);
     if (cacheLocation) {
       await writeScanCache(cacheLocation, {
         version: SCAN_CACHE_VERSION,
@@ -2344,7 +2597,7 @@ function reportUnreadContent(diagnostics, files) {
     const sample2 = affected.slice(0, 3).map((file) => file.path).join(", ");
     const prefix = `${affected.length.toLocaleString()} source file${affected.length === 1 ? "" : "s"}`;
     diagnostics.push({
-      code: "content-unread",
+      code: reason === "not-text" ? "content-not-utf8" : "content-unreadable",
       severity: "warning",
       message: reason === "not-text" ? `${prefix} ${affected.length === 1 ? "is" : "are"} not UTF-8 text (for example UTF-16 or binary) and rank${affected.length === 1 ? "s" : ""} on path alone: ${sample2}${affected.length > 3 ? ", ..." : ""}. Re-save source as UTF-8 to rank its contents.` : `${prefix} could not be read and rank${affected.length === 1 ? "s" : ""} on path alone: ${sample2}${affected.length > 3 ? ", ..." : ""}. Check file permissions and retry.`,
       paths: affected.slice(0, 8).map((file) => file.path)
@@ -2355,7 +2608,7 @@ function reportUnreadContent(diagnostics, files) {
     return;
   const sample = unread.slice().sort((a, b) => b.sizeBytes - a.sizeBytes).slice(0, 3).map((file) => `${file.path} (${Math.ceil(file.sizeBytes / 1e3).toLocaleString()} kB)`).join(", ");
   diagnostics.push({
-    code: "content-unread",
+    code: "content-too-large",
     severity: "warning",
     message: `${unread.length.toLocaleString()} source file${unread.length === 1 ? "" : "s"} could not be read as text and rank${unread.length === 1 ? "s" : ""} on path alone \u2014 largest: ${sample}${unread.length > 3 ? ", \u2026" : ""}. Files over ${(MAX_TEXT_SAMPLE_BYTES / 1e3).toLocaleString()} kB are not sampled.`,
     paths: unread.slice(0, 8).map((file) => file.path)
@@ -2447,7 +2700,7 @@ async function toRepoFile(absolutePath, relativePath) {
   if (!fileStat.isFile()) {
     return { status: "not-a-file" };
   }
-  const extension = extname(relativePath);
+  const extension = extname(relativePath).toLowerCase();
   const conventionalKind = classifyConventionalTextFile(relativePath);
   const isSource = SOURCE_EXTENSIONS.has(extension) || conventionalKind !== void 0;
   const sample = isSource ? await readTextSample(absolutePath, fileStat.size) : { text: "", complete: true };
@@ -2580,10 +2833,7 @@ async function readDiff(repoRoot, diffSpec, diagnostics, internalPaths) {
       message: changedFiles.length === 0 ? `The diff "${truncateForDiagnostic(diffSpec, DIAGNOSTIC_SPEC_LIMIT)}" resolved to zero changed files, so results use the task text only. Paths are relative to the working directory; run from the repository root to include changes outside it.` : `Diff "${truncateForDiagnostic(diffSpec, DIAGNOSTIC_SPEC_LIMIT)}" resolved ${changedFiles.length} changed ${changedFiles.length === 1 ? "path" : "paths"}.`,
       paths: changedFiles.slice(0, 8)
     });
-    return {
-      changedFiles,
-      diffText: diffText.slice(0, MAX_DIFF_TEXT_CHARS)
-    };
+    return { changedFiles, diffText: sampleDiffText(diffText, diagnostics) };
   } catch (error) {
     const checkoutState = isMissingGit(error) ? void 0 : await describeGitCheckout(repoRoot);
     const detail = truncateForDiagnostic(gitErrorDetail(error), DIAGNOSTIC_SPEC_LIMIT * 2);
@@ -2595,6 +2845,55 @@ async function readDiff(repoRoot, diffSpec, diagnostics, internalPaths) {
     return { changedFiles: [], diffText: "" };
   }
 }
+function sampleDiffText(diffText, diagnostics) {
+  if (diffText.length <= MAX_DIFF_TEXT_CHARS)
+    return diffText;
+  const groups = [];
+  let current;
+  for (const line of diffText.split(/\r?\n/)) {
+    if (line.startsWith("diff --git ")) {
+      current = [];
+      groups.push(current);
+      continue;
+    }
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      if (!current) {
+        current = [];
+        groups.push(current);
+      }
+      current.push(line);
+    }
+  }
+  const queues = groups.filter((group) => group.length > 0);
+  const selected = [];
+  let selectedChars = 0;
+  let selectedLines = 0;
+  const totalLines = queues.reduce((total, group) => total + group.length, 0);
+  let cursor = 0;
+  let madeProgress = true;
+  while (madeProgress && selectedChars < MAX_DIFF_TEXT_CHARS) {
+    madeProgress = false;
+    for (const group of queues) {
+      const line = group[cursor];
+      if (line === void 0)
+        continue;
+      madeProgress = true;
+      const separator = selected.length === 0 ? 0 : 1;
+      if (selectedChars + separator + line.length <= MAX_DIFF_TEXT_CHARS) {
+        selected.push(line);
+        selectedChars += separator + line.length;
+        selectedLines += 1;
+      }
+    }
+    cursor += 1;
+  }
+  diagnostics.push({
+    code: "diff-text-truncated",
+    severity: "warning",
+    message: `The git diff was ${diffText.length.toLocaleString()} characters, above FixMap's ${MAX_DIFF_TEXT_CHARS.toLocaleString()}-character signal budget. FixMap sampled ${selectedLines.toLocaleString()} of ${totalLines.toLocaleString()} complete added lines across ${queues.length.toLocaleString()} changed ${queues.length === 1 ? "file" : "files"}; changed-file paths remain complete, but omitted diff content could reduce ranking precision.`
+  });
+  return selected.join("\n");
+}
 async function readWorkingTree(repoRoot, includeUntracked, diagnostics, internalPaths) {
   try {
     const [{ stdout: names }, { stdout: diffText }] = await Promise.all([
@@ -2610,7 +2909,7 @@ async function readWorkingTree(repoRoot, includeUntracked, diagnostics, internal
       message: changedFiles.length === 0 ? "Working-tree mode found no changes against HEAD; results use the task text only." : `Working-tree mode used ${changedFiles.length} changed ${changedFiles.length === 1 ? "path" : "paths"} against HEAD${includeUntracked ? ", including untracked files" : " (untracked files are not counted as changed, though they still rank; pass --include-untracked to count them)"}.`,
       paths: changedFiles.slice(0, 8)
     });
-    return { changedFiles, diffText: diffText.slice(0, MAX_DIFF_TEXT_CHARS) };
+    return { changedFiles, diffText: sampleDiffText(diffText, diagnostics) };
   } catch (error) {
     const checkoutState = isMissingGit(error) ? void 0 : await describeGitCheckout(repoRoot);
     diagnostics.push({
@@ -2649,16 +2948,42 @@ function gitErrorDetail(error) {
 function isMissingGit(error) {
   return error?.code === "ENOENT";
 }
-function detectPackageManager(files) {
-  const paths = new Set(files.map((file) => file.path));
-  if (paths.has("pnpm-lock.yaml") || paths.has("pnpm-workspace.yaml"))
-    return "pnpm";
-  if (paths.has("yarn.lock") || paths.has(".yarnrc.yml"))
-    return "yarn";
-  if (paths.has("bun.lock") || paths.has("bun.lockb"))
-    return "bun";
+function detectPackageManager(files, diagnostics) {
+  const rootManagers = packageManagersForPaths(files.map((file) => file.path).filter((path) => !path.includes("/")));
+  if (rootManagers.length > 1) {
+    diagnostics.push({
+      code: "package-manager-conflict",
+      severity: "warning",
+      message: `Conflicting root package-manager files were found (${rootManagers.join(", ")}); using ${rootManagers[0]} deterministically. Remove the stale lockfile so routed commands are unambiguous.`
+    });
+  }
+  if (rootManagers[0])
+    return rootManagers[0];
+  const nestedManagers = packageManagersForPaths(files.map((file) => file.path));
+  if (nestedManagers.length === 1)
+    return nestedManagers[0];
+  if (nestedManagers.length > 1) {
+    diagnostics.push({
+      code: "package-manager-conflict",
+      severity: "warning",
+      message: `Nested package-manager files disagree (${nestedManagers.join(", ")}); defaulting to npm for root routes. Point --repo at one workspace to get an unambiguous command.`
+    });
+  }
   return "npm";
 }
+function packageManagersForPaths(paths) {
+  const names = new Set(paths.map((path) => path.split("/").at(-1) ?? path));
+  const managers = [];
+  if (names.has("pnpm-lock.yaml") || names.has("pnpm-workspace.yaml"))
+    managers.push("pnpm");
+  if (names.has("yarn.lock") || names.has(".yarnrc.yml"))
+    managers.push("yarn");
+  if (names.has("bun.lock") || names.has("bun.lockb"))
+    managers.push("bun");
+  if (names.has("package-lock.json") || names.has("npm-shrinkwrap.json"))
+    managers.push("npm");
+  return managers;
+}
 function classifyFile(path, extension) {
   const lower = path.toLowerCase();
   const conventionalKind = classifyConventionalTextFile(path);
@@ -2666,7 +2991,7 @@ function classifyFile(path, extension) {
     return conventionalKind;
   if (extension === ".md" || lower.startsWith("docs/"))
     return "documentation";
-  if (lower.startsWith(".github/") || [".json", ".yaml", ".yml"].includes(extension) || /(^|\/)([^/]+\.)?(config|rc)\.[^/]+$/.test(lower))
+  if (lower.startsWith(".github/") || [".json", ".yaml", ".yml"].includes(extension) || /(^|\/)(?:[^/]+\.config|\.[^/]*rc)\.[^/]+$/.test(lower))
     return "config";
   if (SOURCE_EXTENSIONS.has(extension))
     return "code";
@@ -2678,6 +3003,8 @@ function classifyConventionalTextFile(path) {
     return "documentation";
   if (CONVENTIONAL_CONFIG_NAMES.has(name))
     return "config";
+  if (/\.(?:csproj|fsproj|vbproj)$/.test(name))
+    return "config";
   return void 0;
 }
 async function readTextSample(path, sizeBytes) {
@@ -2728,7 +3055,7 @@ async function buildFixMapReport(input) {
     const excludedPaths = repo.files.filter((file) => requestedExclude.excludes(file.path)).map((file) => file.path);
     const unmatchedPatterns = requestedExclude.patterns.filter((pattern) => !pattern.startsWith("!") && !requestedExclude.matchedPatterns.has(pattern));
     if (unmatchedPatterns.length > 0) {
-      const sample = unmatchedPatterns.slice(0, 5).join(", ");
+      const sample = unmatchedPatterns.slice(0, 5).map(markdownCode).join(", ");
       report.diagnostics.push({
         code: "exclusion-no-match",
         severity: "warning",
@@ -2739,7 +3066,8 @@ async function buildFixMapReport(input) {
       report.diagnostics.push({
         code: "paths-excluded",
         severity: report.contextFiles.length === 0 ? "warning" : "info",
-        message: `${requestedExclude.patterns.length} exclusion ${requestedExclude.patterns.length === 1 ? "pattern" : "patterns"} removed ${excludedPaths.length} ${excludedPaths.length === 1 ? "path" : "paths"} from ranking: ${requestedExclude.patterns.join(", ")}. Run --explain on a file you expected to see if this is why it is absent.`
+        message: `${requestedExclude.patterns.length} exclusion ${requestedExclude.patterns.length === 1 ? "pattern" : "patterns"} removed ${excludedPaths.length} ${excludedPaths.length === 1 ? "path" : "paths"} from ranking: ${requestedExclude.patterns.map(markdownCode).join(", ")}. Run --explain on a file you expected to see if this is why it is absent.`,
+        paths: excludedPaths.slice(0, 8)
       });
     }
   }
@@ -2787,7 +3115,10 @@ function verifyPlan(report, repo) {
   const findings = [];
   const fileByPath = new Map(repo.files.map((file) => [file.path, file]));
   const plannedPaths = report.contextFiles.map((file) => file.path);
-  if (plannedPaths.length > 0 && !plannedPaths.some((path) => fileByPath.has(path))) {
+  const missingPlanned = plannedPaths.filter((path) => !fileByPath.has(path));
+  const changedMissingPlanned = missingPlanned.filter((path) => changed.includes(path));
+  const unexplainedMissingPlanned = missingPlanned.filter((path) => !changed.includes(path));
+  if (plannedPaths.length > 0 && unexplainedMissingPlanned.length === plannedPaths.length) {
     const mismatch = {
       code: "plan-repository-mismatch",
       severity: "error",
@@ -2801,6 +3132,22 @@ function verifyPlan(report, repo) {
       diagnostics: repo.diagnostics
     };
   }
+  if (unexplainedMissingPlanned.length > 0) {
+    findings.push({
+      code: "plan-partially-stale",
+      severity: "warning",
+      paths: unexplainedMissingPlanned.slice(0, 8),
+      message: `${unexplainedMissingPlanned.length} of ${plannedPaths.length} planned paths no longer exist and are not explained by this diff. The plan may predate a rebase or rename; regenerate it before relying on the missing entries.`
+    });
+  }
+  if (changedMissingPlanned.length > 0) {
+    findings.push({
+      code: "planned-file-deleted",
+      severity: "info",
+      paths: changedMissingPlanned.slice(0, 8),
+      message: `${changedMissingPlanned.length === 1 ? "A planned file was" : `${changedMissingPlanned.length} planned files were`} removed by this diff. The deletion accounts for the missing path, so verification continued.`
+    });
+  }
   if (changed.length === 0) {
     return {
       summary: "No changes to verify: the diff resolved to zero files.",
@@ -2910,12 +3257,12 @@ function renderVerifyMarkdown(result) {
     for (const finding of result.findings) {
       lines.push(`- **${finding.severity}** ${finding.message}`);
       for (const path of finding.paths.slice(0, 8)) {
-        lines.push(`  - \`${path}\``);
+        lines.push(`  - ${markdownCode(path)}`);
       }
     }
   }
   lines.push("", "## Changed Files", "");
-  lines.push(...result.changedFiles.length > 0 ? result.changedFiles.map((path) => `- \`${path}\``) : ["- None found"]);
+  lines.push(...result.changedFiles.length > 0 ? result.changedFiles.map((path) => `- ${markdownCode(path)}`) : ["- None found"]);
   return `${lines.join("\n")}
 `;
 }
@@ -3079,7 +3426,7 @@ function isIdentifierStatus(candidate) {
 // packages/action/src/github.ts
 var FIXMAP_REPORT_MARKER = "<!-- fixmap-report -->";
 var MAX_COMMENT_BODY_CHARS = 65536;
-var COMMENT_TRUNCATION_FOOTER = "\n\n> Report truncated to fit GitHub's comment size limit. The complete report is in the step summary and the `report` output.\n";
+var COMMENT_TRUNCATION_FOOTER = "\n\n> Report truncated to fit GitHub's comment size limit. Run FixMap locally with `--output` to retain a complete report.\n";
 function fitCommentBody(body, limit = MAX_COMMENT_BODY_CHARS) {
   if (body.length <= limit) return body;
   const keep = Math.max(0, limit - COMMENT_TRUNCATION_FOOTER.length - "\n```".length);
@@ -3135,10 +3482,11 @@ ${input.markdown}`);
 }
 async function findExistingComment(fetchImpl, commentsUrl, headers, commentAuthor) {
   const maxPages = 50;
+  let latest;
   for (let page = 1; page <= maxPages; page += 1) {
     const comments = await requestJson(
       fetchImpl,
-      `${commentsUrl}?per_page=100&page=${page}&sort=created&direction=desc`,
+      `${commentsUrl}?per_page=100&page=${page}`,
       { headers },
       "list pull request comments"
     );
@@ -3148,22 +3496,43 @@ async function findExistingComment(fetchImpl, commentsUrl, headers, commentAutho
       // second comment beside the one it meant to update.
       (!commentAuthor || comment.user?.login?.toLowerCase() === commentAuthor.toLowerCase())
     ).sort((left, right) => right.id - left.id)[0];
-    if (match) return match;
+    if (match && (!latest || match.id > latest.id)) latest = match;
     if (comments.length < 100) {
-      return void 0;
+      return latest;
     }
   }
-  return void 0;
+  if (latest) return latest;
+  throw new Error(
+    "FixMap stopped after searching 5,000 pull request comments without finding its marker; it refused to create a duplicate comment. Remove old comments or set comment-author to narrow the search."
+  );
 }
 function isPermissionDeniedError(error) {
-  return error instanceof Error && /GitHub returned (401|403|404)\b/.test(error.message);
-}
+  return error instanceof GitHubRequestError && (error.status === 401 || error.status === 404 || error.status === 403 && !error.rateLimited && /resource not accessible|insufficient permission|forbidden|write access/i.test(error.detail));
+}
+var GitHubRequestError = class extends Error {
+  constructor(message, status, detail, rateLimited) {
+    super(message);
+    this.status = status;
+    this.detail = detail;
+    this.rateLimited = rateLimited;
+    this.name = "GitHubRequestError";
+  }
+  status;
+  detail;
+  rateLimited;
+};
 async function requestJson(fetchImpl, url, init, action) {
   const response = await fetchImpl(url, init);
   if (!response.ok) {
     const detail = (await response.text()).replace(/\s+/g, " ").slice(0, 500);
     const suffix = detail ? `: ${detail}` : "";
-    throw new Error(`FixMap could not ${action}; GitHub returned ${response.status} ${response.statusText}${suffix}`);
+    const rateLimited = response.status === 429 || response.headers.get("x-ratelimit-remaining") === "0" || /secondary rate limit|rate limit exceeded/i.test(detail);
+    throw new GitHubRequestError(
+      `FixMap could not ${action}; GitHub returned ${response.status} ${response.statusText}${suffix}`,
+      response.status,
+      detail,
+      rateLimited
+    );
   }
   return response.json();
 }
@@ -3173,7 +3542,7 @@ var MAX_API_RESPONSE_CHARS = 1e6;
 var MAX_ISSUE_BODY_CHARS = 2e4;
 function parseActionIssueSource(input) {
   let trimmed = input.trim();
-  if (/^https?:\/\/[^/\s]*@(?:www\.|api\.)?github\.com\//i.test(trimmed)) {
+  if (/^https?:\/\/[^/\s@]+@/i.test(trimmed)) {
     throw new Error(
       "The issue URL contains credentials. Remove the user:token@ prefix and pass the public https://github.com/owner/repository/issues/123 URL; the Action reads public issues anonymously."
     );
@@ -3287,7 +3656,9 @@ async function fetchActionIssue(source) {
 
 // packages/action/src/runner.ts
 var STEP_SUMMARY_LIMIT_BYTES = 1024 * 1024;
-var TRUNCATION_FOOTER = "\n\n> FixMap report truncated to fit GitHub's 1 MiB step-summary limit. The complete report remains available through the `report` output.\n";
+var TRUNCATION_FOOTER = "\n\n> FixMap report truncated to fit GitHub's 1 MiB step-summary limit. Run FixMap locally with `--output` to retain a complete report.\n";
+var ACTION_OUTPUT_REPORT_LIMIT_BYTES = 900 * 1024;
+var OUTPUT_TRUNCATION_FOOTER = "\n\n[FixMap report truncated to fit the GitHub Actions output limit. Run FixMap locally with --output for a complete report.]\n";
 async function runAction(env = process.env, dependencies = {}) {
   const appendFile = dependencies.appendFile ?? ((path, contents) => appendFileSync(path, contents));
   const readFile3 = dependencies.readFile ?? ((path) => readFileSync(path, "utf8"));
@@ -3302,6 +3673,7 @@ async function runAction(env = process.env, dependencies = {}) {
   const headRef = readInput("head", env) || (!workingTree && env.GITHUB_HEAD_REF ? "HEAD" : void 0);
   const format = parseFormat(readInput("format", env));
   const mode = parseMode(readInput("mode", env));
+  const failOn = parseFailOn(readInput("fail-on", env));
   const exclude = splitExcludeInput(readInput("exclude", env) ?? "");
   const limit = parseLimit(readInput("limit", env));
   if (includeUntracked && !workingTree) throw new Error("include-untracked requires working-tree.");
@@ -3318,8 +3690,9 @@ async function runAction(env = process.env, dependencies = {}) {
         `FixMap verify mode does not use plan-only input${planOnly.length === 1 ? "" : "s"}: ${planOnly.join(", ")}. Remove them, or set mode: plan.`
       );
     }
-    return runVerifyMode({ env, dependencies, readFile: readFile3, appendFile, stdout, format, diffSpec, baseRef, headRef, workingTree, includeUntracked, noCache });
+    return runVerifyMode({ env, dependencies, readFile: readFile3, appendFile, stdout, format, failOn, diffSpec, baseRef, headRef, workingTree, includeUntracked, noCache });
   }
+  if (failOn === "warning") throw new Error("fail-on: warning is a verify-mode input; remove it or set mode: verify.");
   const issueSource = rawIssue ? parseActionIssueSource(rawIssue) : void 0;
   if (issueSource && env.GITHUB_REPOSITORY && env.GITHUB_REPOSITORY.toLowerCase() !== `${issueSource.owner}/${issueSource.repository}`.toLowerCase()) {
     throw new Error(
@@ -3354,7 +3727,7 @@ async function runAction(env = process.env, dependencies = {}) {
   const output = format === "json" ? renderJsonReport(report) : markdown;
   stdout(output);
   if (env.GITHUB_STEP_SUMMARY) {
-    appendFile(env.GITHUB_STEP_SUMMARY, fitStepSummary(format === "json" ? withJsonDetails(markdown, output) : markdown));
+    appendBoundedStepSummary(env.GITHUB_STEP_SUMMARY, format === "json" ? withJsonDetails(markdown, output) : markdown, dependencies, appendFile, stdout);
   }
   if (env.GITHUB_OUTPUT) {
     appendFile(env.GITHUB_OUTPUT, renderActionOutputs(output, report, dependencies.uuid ?? randomUUID2));
@@ -3374,7 +3747,7 @@ ${output.trimEnd()}
       }
       const detail = error instanceof Error ? error.message : String(error);
       stdout(
-        `::warning::FixMap could not comment on the pull request, which is expected when the token is read-only (for example on forked pull requests). The full report is in the step summary and the report output. ${detail}
+        `::warning::FixMap could not comment on the pull request, which is expected when the token is read-only (for example on forked pull requests). The bounded report remains in the step summary and report output; run FixMap locally with --output if either surface reports truncation. ${detail}
 `
       );
     }
@@ -3432,7 +3805,7 @@ async function runVerifyMode(context) {
 ` : markdown;
   context.stdout(output);
   if (context.env.GITHUB_STEP_SUMMARY) {
-    context.appendFile(context.env.GITHUB_STEP_SUMMARY, fitStepSummary(markdown));
+    appendBoundedStepSummary(context.env.GITHUB_STEP_SUMMARY, markdown, context.dependencies, context.appendFile, context.stdout);
   }
   if (context.env.GITHUB_OUTPUT) {
     context.appendFile(
@@ -3440,15 +3813,18 @@ async function runVerifyMode(context) {
       renderVerifyOutputs(output, result, context.dependencies.uuid ?? randomUUID2)
     );
   }
-  if (result.findings.some((finding) => finding.severity === "error")) {
+  if (result.findings.some(
+    (finding) => finding.severity === "error" || context.failOn === "warning" && finding.severity === "warning"
+  )) {
     throw new Error(
-      "FixMap verification found an edit in a generated or retired location, which the next build discards."
+      context.failOn === "warning" ? "FixMap verification found findings at or above the configured warning threshold." : "FixMap verification found an edit in a generated or retired location, which the next build discards."
     );
   }
 }
 function renderVerifyOutputs(reportText, result, uuid = randomUUID2) {
   const delimiter = `fixmap_${uuid().replaceAll("-", "")}`;
-  const terminated = reportText.endsWith("\n") ? reportText : `${reportText}
+  const fittedReport = fitOutputReport(reportText);
+  const terminated = fittedReport.endsWith("\n") ? fittedReport : `${fittedReport}
 `;
   return [
     `report<<${delimiter}
@@ -3474,10 +3850,16 @@ function parseFormat(value) {
 }
 function parseLimit(value) {
   if (!value) return void 0;
-  const parsed = Number(value);
-  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 20) throw new Error("limit must be a whole number from 1 to 20.");
+  const normalized = value.trim();
+  const parsed = Number(normalized);
+  if (!/^\d+$/.test(normalized) || !Number.isSafeInteger(parsed) || parsed < 1 || parsed > 20) throw new Error("limit must be a whole number from 1 to 20.");
   return parsed;
 }
+function parseFailOn(value) {
+  const normalized = value?.trim().toLowerCase() ?? "error";
+  if (normalized === "error" || normalized === "warning") return normalized;
+  throw new Error("fail-on must be error or warning.");
+}
 function parseBooleanInput(name, value) {
   if (!value) return false;
   if (/^(?:true|1|yes)$/i.test(value)) return true;
@@ -3486,7 +3868,8 @@ function parseBooleanInput(name, value) {
 }
 function renderActionOutputs(reportText, report, uuid = randomUUID2) {
   const delimiter = `fixmap_${uuid().replaceAll("-", "")}`;
-  const terminatedReport = reportText.endsWith("\n") ? reportText : `${reportText}
+  const fittedReport = fitOutputReport(reportText);
+  const terminatedReport = fittedReport.endsWith("\n") ? fittedReport : `${fittedReport}
 `;
   return [
     `report<<${delimiter}
@@ -3500,6 +3883,14 @@ function renderActionOutputs(reportText, report, uuid = randomUUID2) {
 `
   ].join("");
 }
+function fitOutputReport(reportText) {
+  const bytes = Buffer.from(reportText);
+  if (bytes.length <= ACTION_OUTPUT_REPORT_LIMIT_BYTES) return reportText;
+  const footer = Buffer.from(OUTPUT_TRUNCATION_FOOTER);
+  let end = ACTION_OUTPUT_REPORT_LIMIT_BYTES - footer.length;
+  while (end > 0 && (bytes[end] & 192) === 128) end -= 1;
+  return `${bytes.subarray(0, end).toString("utf8")}${OUTPUT_TRUNCATION_FOOTER}`;
+}
 function withJsonDetails(markdown, json) {
   return `${markdown}
 
@@ -3552,6 +3943,21 @@ function fitStepSummary(markdown, limitBytes = STEP_SUMMARY_LIMIT_BYTES) {
   }
   return `${trimToBoundary(bytes.subarray(0, end).toString("utf8"))}${TRUNCATION_FOOTER}`;
 }
+function appendBoundedStepSummary(path, markdown, dependencies, appendFile, stdout) {
+  const fileSize = dependencies.fileSize ?? ((summaryPath) => {
+    try {
+      return statSync(summaryPath).size;
+    } catch {
+      return 0;
+    }
+  });
+  const remaining = Math.max(0, STEP_SUMMARY_LIMIT_BYTES - fileSize(path));
+  if (remaining <= Buffer.byteLength(TRUNCATION_FOOTER)) {
+    stdout("::warning::FixMap skipped its step summary because earlier steps already consumed GitHub's 1 MiB summary budget. The bounded report remains available through the report output.\n");
+    return;
+  }
+  appendFile(path, fitStepSummary(markdown, remaining));
+}
 function readInput(name, env) {
   const githubName = `INPUT_${name.replace(/ /g, "_").toUpperCase()}`;
   const shellSafeName = `INPUT_${name.replace(/[- ]/g, "_").toUpperCase()}`;
diff --git a/packages/action/package.json b/packages/action/package.json
index 3be212b..a94c9bd 100644
--- a/packages/action/package.json
+++ b/packages/action/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@fixmap/action",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "description": "GitHub Action wrapper for FixMap pull request reports.",
   "private": true,
   "license": "MIT",
@@ -11,6 +11,6 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@aryam/fixmap-core": "0.8.8"
+    "@aryam/fixmap-core": "0.8.9"
   }
 }
diff --git a/packages/action/src/github.ts b/packages/action/src/github.ts
index d86f5bb..10971fd 100644
--- a/packages/action/src/github.ts
+++ b/packages/action/src/github.ts
@@ -4,14 +4,14 @@ export const FIXMAP_REPORT_MARKER = "<!-- fixmap-report -->";
  * GitHub rejects an issue comment over 65,536 characters with a 422, and the marker was
  * concatenated onto the report and posted without any check — so on a large monorepo the run
  * completed, ranked everything, and then failed at the final API call, losing the report.
- * Truncating keeps the comment; the complete report is still on the `report` output and in
- * the step summary, which the footer says.
+ * Truncating keeps the comment and points readers to a local `--output` run for the complete
+ * artifact; no bounded GitHub surface is described as complete.
  */
 export const MAX_COMMENT_BODY_CHARS = 65_536;
 
 const COMMENT_TRUNCATION_FOOTER =
   "\n\n> Report truncated to fit GitHub's comment size limit. " +
-  "The complete report is in the step summary and the `report` output.\n";
+  "Run FixMap locally with `--output` to retain a complete report.\n";
 
 export function fitCommentBody(body: string, limit = MAX_COMMENT_BODY_CHARS): string {
   if (body.length <= limit) return body;
@@ -110,10 +110,11 @@ async function findExistingComment(
   commentAuthor: string | undefined
 ): Promise<GitHubComment | undefined> {
   const maxPages = 50;
+  let latest: GitHubComment | undefined;
   for (let page = 1; page <= maxPages; page += 1) {
     const comments = await requestJson<GitHubComment[]>(
       fetchImpl,
-      `${commentsUrl}?per_page=100&page=${page}&sort=created&direction=desc`,
+      `${commentsUrl}?per_page=100&page=${page}`,
       { headers },
       "list pull request comments"
     );
@@ -125,17 +126,37 @@ async function findExistingComment(
         // second comment beside the one it meant to update.
         (!commentAuthor || comment.user?.login?.toLowerCase() === commentAuthor.toLowerCase())
     ).sort((left, right) => right.id - left.id)[0];
-    if (match) return match;
+    if (match && (!latest || match.id > latest.id)) latest = match;
 
     if (comments.length < 100) {
-      return undefined;
+      return latest;
     }
   }
-  return undefined;
+  if (latest) return latest;
+  throw new Error(
+    "FixMap stopped after searching 5,000 pull request comments without finding its marker; " +
+    "it refused to create a duplicate comment. Remove old comments or set comment-author to narrow the search."
+  );
 }
 
 export function isPermissionDeniedError(error: unknown): boolean {
-  return error instanceof Error && /GitHub returned (401|403|404)\b/.test(error.message);
+  return error instanceof GitHubRequestError && (
+    error.status === 401 ||
+    error.status === 404 ||
+    (error.status === 403 && !error.rateLimited && /resource not accessible|insufficient permission|forbidden|write access/i.test(error.detail))
+  );
+}
+
+export class GitHubRequestError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly detail: string,
+    readonly rateLimited: boolean
+  ) {
+    super(message);
+    this.name = "GitHubRequestError";
+  }
 }
 
 async function requestJson<T>(
@@ -148,7 +169,15 @@ async function requestJson<T>(
   if (!response.ok) {
     const detail = (await response.text()).replace(/\s+/g, " ").slice(0, 500);
     const suffix = detail ? `: ${detail}` : "";
-    throw new Error(`FixMap could not ${action}; GitHub returned ${response.status} ${response.statusText}${suffix}`);
+    const rateLimited = response.status === 429 ||
+      response.headers.get("x-ratelimit-remaining") === "0" ||
+      /secondary rate limit|rate limit exceeded/i.test(detail);
+    throw new GitHubRequestError(
+      `FixMap could not ${action}; GitHub returned ${response.status} ${response.statusText}${suffix}`,
+      response.status,
+      detail,
+      rateLimited
+    );
   }
 
   return response.json() as Promise<T>;
diff --git a/packages/action/src/issue-source.ts b/packages/action/src/issue-source.ts
index 0a5e9e4..219fe96 100644
--- a/packages/action/src/issue-source.ts
+++ b/packages/action/src/issue-source.ts
@@ -14,7 +14,7 @@ const MAX_ISSUE_BODY_CHARS = 20_000;
 
 export function parseActionIssueSource(input: string): ActionIssueSource | undefined {
   let trimmed = input.trim();
-  if (/^https?:\/\/[^/\s]*@(?:www\.|api\.)?github\.com\//i.test(trimmed)) {
+  if (/^https?:\/\/[^/\s@]+@/i.test(trimmed)) {
     throw new Error(
       "The issue URL contains credentials. Remove the user:token@ prefix and pass the public " +
       "https://github.com/owner/repository/issues/123 URL; the Action reads public issues anonymously."
diff --git a/packages/action/src/runner.ts b/packages/action/src/runner.ts
index 9c8dafb..da95288 100644
--- a/packages/action/src/runner.ts
+++ b/packages/action/src/runner.ts
@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { appendFileSync, readFileSync } from "node:fs";
+import { appendFileSync, readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import {
   buildFixMapReport,
@@ -28,7 +28,10 @@ import {
 
 const STEP_SUMMARY_LIMIT_BYTES = 1024 * 1024;
 const TRUNCATION_FOOTER =
-  "\n\n> FixMap report truncated to fit GitHub's 1 MiB step-summary limit. The complete report remains available through the `report` output.\n";
+  "\n\n> FixMap report truncated to fit GitHub's 1 MiB step-summary limit. Run FixMap locally with `--output` to retain a complete report.\n";
+const ACTION_OUTPUT_REPORT_LIMIT_BYTES = 900 * 1024;
+const OUTPUT_TRUNCATION_FOOTER =
+  "\n\n[FixMap report truncated to fit the GitHub Actions output limit. Run FixMap locally with --output for a complete report.]\n";
 
 export type ActionDependencies = {
   appendFile?: (path: string, contents: string) => void;
@@ -36,6 +39,7 @@ export type ActionDependencies = {
   createClient?: typeof createGitHubClient;
   cwd?: () => string;
   readFile?: (path: string) => string;
+  fileSize?: (path: string) => number;
   stdout?: (text: string) => void;
   uuid?: () => string;
   fetchIssue?: (source: ActionIssueSource) => Promise<ActionIssue>;
@@ -59,6 +63,7 @@ export async function runAction(
   const headRef = readInput("head", env) || (!workingTree && env.GITHUB_HEAD_REF ? "HEAD" : undefined);
   const format = parseFormat(readInput("format", env));
   const mode = parseMode(readInput("mode", env));
+  const failOn = parseFailOn(readInput("fail-on", env));
   const exclude = splitExcludeInput(readInput("exclude", env) ?? "");
   const limit = parseLimit(readInput("limit", env));
   if (includeUntracked && !workingTree) throw new Error("include-untracked requires working-tree.");
@@ -82,8 +87,9 @@ export async function runAction(
         "Remove them, or set mode: plan."
       );
     }
-    return runVerifyMode({ env, dependencies, readFile, appendFile, stdout, format, diffSpec, baseRef, headRef, workingTree, includeUntracked, noCache });
+    return runVerifyMode({ env, dependencies, readFile, appendFile, stdout, format, failOn, diffSpec, baseRef, headRef, workingTree, includeUntracked, noCache });
   }
+  if (failOn === "warning") throw new Error("fail-on: warning is a verify-mode input; remove it or set mode: verify.");
 
   const issueSource = rawIssue ? parseActionIssueSource(rawIssue) : undefined;
   if (issueSource && env.GITHUB_REPOSITORY &&
@@ -134,7 +140,7 @@ export async function runAction(
     // A json workflow got a markdown-only summary, so the tab an operator actually opens
     // never showed the shape their pipeline consumes. The readable report still leads; the
     // JSON follows in a collapsed block so the summary stays scannable.
-    appendFile(env.GITHUB_STEP_SUMMARY, fitStepSummary(format === "json" ? withJsonDetails(markdown, output) : markdown));
+    appendBoundedStepSummary(env.GITHUB_STEP_SUMMARY, format === "json" ? withJsonDetails(markdown, output) : markdown, dependencies, appendFile, stdout);
   }
 
   if (env.GITHUB_OUTPUT) {
@@ -153,7 +159,7 @@ export async function runAction(
       }
       const detail = error instanceof Error ? error.message : String(error);
       stdout(
-        `::warning::FixMap could not comment on the pull request, which is expected when the token is read-only (for example on forked pull requests). The full report is in the step summary and the report output. ${detail}\n`
+        `::warning::FixMap could not comment on the pull request, which is expected when the token is read-only (for example on forked pull requests). The bounded report remains in the step summary and report output; run FixMap locally with --output if either surface reports truncation. ${detail}\n`
       );
     }
   }
@@ -177,6 +183,7 @@ type VerifyModeContext = {
   appendFile: (path: string, contents: string) => void;
   stdout: (text: string) => void;
   format: "markdown" | "json";
+  failOn: "error" | "warning";
   diffSpec: string | undefined;
   baseRef: string | undefined;
   headRef: string | undefined;
@@ -232,7 +239,7 @@ async function runVerifyMode(context: VerifyModeContext): Promise<void> {
   context.stdout(output);
 
   if (context.env.GITHUB_STEP_SUMMARY) {
-    context.appendFile(context.env.GITHUB_STEP_SUMMARY, fitStepSummary(markdown));
+    appendBoundedStepSummary(context.env.GITHUB_STEP_SUMMARY, markdown, context.dependencies, context.appendFile, context.stdout);
   }
   if (context.env.GITHUB_OUTPUT) {
     context.appendFile(
@@ -243,9 +250,13 @@ async function runVerifyMode(context: VerifyModeContext): Promise<void> {
 
   // A generated-location edit is discarded by the next build, so it fails the step rather
   // than being reported and scrolled past. Everything else stays advisory.
-  if (result.findings.some((finding) => finding.severity === "error")) {
+  if (result.findings.some((finding) =>
+    finding.severity === "error" || (context.failOn === "warning" && finding.severity === "warning")
+  )) {
     throw new Error(
-      "FixMap verification found an edit in a generated or retired location, which the next build discards."
+      context.failOn === "warning"
+        ? "FixMap verification found findings at or above the configured warning threshold."
+        : "FixMap verification found an edit in a generated or retired location, which the next build discards."
     );
   }
 }
@@ -256,7 +267,8 @@ export function renderVerifyOutputs(
   uuid: () => string = randomUUID
 ): string {
   const delimiter = `fixmap_${uuid().replaceAll("-", "")}`;
-  const terminated = reportText.endsWith("\n") ? reportText : `${reportText}\n`;
+  const fittedReport = fitOutputReport(reportText);
+  const terminated = fittedReport.endsWith("\n") ? fittedReport : `${fittedReport}\n`;
   return [
     `report<<${delimiter}\n`,
     terminated,
@@ -279,11 +291,18 @@ function parseFormat(value: string | undefined): "markdown" | "json" {
 
 function parseLimit(value: string | undefined): number | undefined {
   if (!value) return undefined;
-  const parsed = Number(value);
-  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 20) throw new Error("limit must be a whole number from 1 to 20.");
+  const normalized = value.trim();
+  const parsed = Number(normalized);
+  if (!/^\d+$/.test(normalized) || !Number.isSafeInteger(parsed) || parsed < 1 || parsed > 20) throw new Error("limit must be a whole number from 1 to 20.");
   return parsed;
 }
 
+function parseFailOn(value: string | undefined): "error" | "warning" {
+  const normalized = value?.trim().toLowerCase() ?? "error";
+  if (normalized === "error" || normalized === "warning") return normalized;
+  throw new Error("fail-on must be error or warning.");
+}
+
 function parseBooleanInput(name: string, value: string | undefined): boolean {
   if (!value) return false;
   if (/^(?:true|1|yes)$/i.test(value)) return true;
@@ -297,7 +316,8 @@ export function renderActionOutputs(
   uuid: () => string = randomUUID
 ): string {
   const delimiter = `fixmap_${uuid().replaceAll("-", "")}`;
-  const terminatedReport = reportText.endsWith("\n") ? reportText : `${reportText}\n`;
+  const fittedReport = fitOutputReport(reportText);
+  const terminatedReport = fittedReport.endsWith("\n") ? fittedReport : `${fittedReport}\n`;
   return [
     `report<<${delimiter}\n`,
     terminatedReport,
@@ -307,6 +327,15 @@ export function renderActionOutputs(
   ].join("");
 }
 
+function fitOutputReport(reportText: string): string {
+  const bytes = Buffer.from(reportText);
+  if (bytes.length <= ACTION_OUTPUT_REPORT_LIMIT_BYTES) return reportText;
+  const footer = Buffer.from(OUTPUT_TRUNCATION_FOOTER);
+  let end = ACTION_OUTPUT_REPORT_LIMIT_BYTES - footer.length;
+  while (end > 0 && (bytes[end]! & 0xc0) === 0x80) end -= 1;
+  return `${bytes.subarray(0, end).toString("utf8")}${OUTPUT_TRUNCATION_FOOTER}`;
+}
+
 /**
  * Splitting on every comma tore `src/{auth,billing}/**` into `src/{auth` and `billing}/**`,
  * so a brace pattern was not merely unsupported — it was corrupted into two patterns that
@@ -370,6 +399,24 @@ export function fitStepSummary(markdown: string, limitBytes = STEP_SUMMARY_LIMIT
   return `${trimToBoundary(bytes.subarray(0, end).toString("utf8"))}${TRUNCATION_FOOTER}`;
 }
 
+function appendBoundedStepSummary(
+  path: string,
+  markdown: string,
+  dependencies: ActionDependencies,
+  appendFile: (path: string, contents: string) => void,
+  stdout: (text: string) => void
+): void {
+  const fileSize = dependencies.fileSize ?? ((summaryPath: string) => {
+    try { return statSync(summaryPath).size; } catch { return 0; }
+  });
+  const remaining = Math.max(0, STEP_SUMMARY_LIMIT_BYTES - fileSize(path));
+  if (remaining <= Buffer.byteLength(TRUNCATION_FOOTER)) {
+    stdout("::warning::FixMap skipped its step summary because earlier steps already consumed GitHub's 1 MiB summary budget. The bounded report remains available through the report output.\n");
+    return;
+  }
+  appendFile(path, fitStepSummary(markdown, remaining));
+}
+
 function readInput(name: string, env: NodeJS.ProcessEnv): string | undefined {
   const githubName = `INPUT_${name.replace(/ /g, "_").toUpperCase()}`;
   const shellSafeName = `INPUT_${name.replace(/[- ]/g, "_").toUpperCase()}`;
diff --git a/packages/action/test/github.test.ts b/packages/action/test/github.test.ts
index 8800131..1b0a656 100644
--- a/packages/action/test/github.test.ts
+++ b/packages/action/test/github.test.ts
@@ -110,9 +110,43 @@ describe("GitHub Action helpers", () => {
 
     expect(result).toBe("updated");
     expect(calls.some((url) => url.includes("page=11"))).toBe(true);
+    expect(calls.every((url) => !url.includes("sort=") && !url.includes("direction="))).toBe(true);
   });
 
-  it("stops after fifty pages when a proxy repeats full pages", async () => {
+  it("updates the highest-id marked comment found on later pages", async () => {
+    const calls: Array<{ url: string; method: string }> = [];
+    const fetchImpl: typeof fetch = async (input, init) => {
+      const url = String(input);
+      calls.push({ url, method: init?.method ?? "GET" });
+      if (url.includes("/comments?")) {
+        const page = Number(new URL(url).searchParams.get("page"));
+        if (page === 1) {
+          return jsonResponse([
+            { id: 10, body: FIXMAP_REPORT_MARKER, user: { login: "github-actions[bot]" } },
+            ...Array.from({ length: 99 }, (_, index) => ({ id: 100 + index, body: "ordinary" }))
+          ]);
+        }
+        return jsonResponse([{ id: 999, body: FIXMAP_REPORT_MARKER, user: { login: "github-actions[bot]" } }]);
+      }
+      return jsonResponse({ id: 999 });
+    };
+
+    const result = await createGitHubClient({ fetchImpl }).upsertPullRequestComment({
+      token: "test-token",
+      owner: "octo",
+      repo: "demo",
+      issueNumber: 42,
+      markdown: "# FixMap Report"
+    });
+
+    expect(result).toBe("updated");
+    expect(calls).toContainEqual({
+      url: "https://api.github.com/repos/octo/demo/issues/comments/999",
+      method: "PATCH"
+    });
+  });
+
+  it("refuses to create a duplicate after fifty full pages", async () => {
     const calls: string[] = [];
     const fetchImpl: typeof fetch = async (input, init) => {
       const url = String(input);
@@ -128,17 +162,16 @@ describe("GitHub Action helpers", () => {
       return jsonResponse({ id: 9001 }, 201);
     };
 
-    const result = await createGitHubClient({ fetchImpl }).upsertPullRequestComment({
+    await expect(createGitHubClient({ fetchImpl }).upsertPullRequestComment({
       token: "test-token",
       owner: "octo",
       repo: "demo",
       issueNumber: 42,
       markdown: "# FixMap Report"
-    });
-
-    expect(result).toBe("created");
+    })).rejects.toThrow("refused to create a duplicate comment");
     expect(calls.filter((url) => url.includes("/comments?")).length).toBe(50);
     expect(calls.some((url) => url.includes("page=51"))).toBe(false);
+    expect(calls.some((url) => !url.includes("/comments?"))).toBe(false);
   });
 
   it("reports a useful error when GitHub rejects comment lookup", async () => {
@@ -165,4 +198,19 @@ describe("GitHub Action helpers", () => {
     expect(isPermissionDeniedError(new Error("FixMap could not create the FixMap comment; GitHub returned 500 Server Error"))).toBe(false);
     expect(isPermissionDeniedError(new Error("network down"))).toBe(false);
   });
+
+  it("does not disguise a rate-limited 403 as a read-only token", async () => {
+    const fetchImpl: typeof fetch = async () => new Response("API rate limit exceeded", {
+      status: 403,
+      statusText: "Forbidden",
+      headers: { "x-ratelimit-remaining": "0" }
+    });
+
+    const failure = await createGitHubClient({ fetchImpl })
+      .upsertPullRequestComment({ token: "t", owner: "octo", repo: "demo", issueNumber: 42, markdown: "# r" })
+      .catch((error: unknown) => error);
+
+    expect(isPermissionDeniedError(failure)).toBe(false);
+    expect(failure).toMatchObject({ status: 403, rateLimited: true });
+  });
 });
diff --git a/packages/action/test/issue-source.test.ts b/packages/action/test/issue-source.test.ts
index 2920a40..ce4a0d7 100644
--- a/packages/action/test/issue-source.test.ts
+++ b/packages/action/test/issue-source.test.ts
@@ -17,6 +17,7 @@ describe("Action GitHub issue URL normalization", () => {
   it("still rejects insecure, credentialed, and encoded-separator variants", () => {
     expect(() => parseActionIssueSource("http://www.github.com/o/r/issues/1")).toThrow("must use https");
     expect(() => parseActionIssueSource("https://token@api.github.com/repos/o/r/issues/1")).toThrow("credentials");
+    expect(() => parseActionIssueSource("https://user:secret@example.com/task/1")).toThrow("credentials");
     expect(() => parseActionIssueSource("https://www.github.com/o%2fr/issues/1")).toThrow("encoded separators");
   });
 });
diff --git a/packages/action/test/runner.test.ts b/packages/action/test/runner.test.ts
index 044f4c9..6974b34 100644
--- a/packages/action/test/runner.test.ts
+++ b/packages/action/test/runner.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import type { FixMapReport } from "@aryam/fixmap-core";
-import { fitStepSummary, renderActionOutputs, runAction, splitExcludeInput, trimToBoundary, withJsonDetails } from "../src/runner.js";
+import { fitStepSummary, renderActionOutputs, renderVerifyOutputs, runAction, splitExcludeInput, trimToBoundary, withJsonDetails } from "../src/runner.js";
 import { FIXMAP_REPORT_MARKER, fitCommentBody, MAX_COMMENT_BODY_CHARS } from "../src/github.js";
 
 const report: FixMapReport = {
@@ -29,6 +29,23 @@ describe("GitHub Action runner", () => {
     );
   });
 
+  it("bounds both plan and verify report outputs and points to a real complete-artifact path", () => {
+    const oversized = "🙂".repeat(500_000);
+    const planOutput = renderActionOutputs(oversized, report, () => "stable");
+    const verifyOutput = renderVerifyOutputs(oversized, {
+      summary: "",
+      changedFiles: [],
+      findings: [],
+      diagnostics: []
+    }, () => "stable");
+
+    for (const output of [planOutput, verifyOutput]) {
+      expect(output).toContain("Run FixMap locally with --output for a complete report");
+      expect(output).not.toContain("�");
+      expect(Buffer.byteLength(output)).toBeLessThan(925 * 1024);
+    }
+  });
+
   it("truncates oversized summaries by bytes and retains an explicit notice", () => {
     const summary = fitStepSummary("🙂".repeat(100), 180);
     expect(Buffer.byteLength(summary)).toBeLessThanOrEqual(180);
@@ -66,6 +83,20 @@ describe("GitHub Action runner", () => {
     expect(stdout).toHaveBeenCalledOnce();
   });
 
+  it("fits its appended summary into the bytes earlier steps left available", async () => {
+    const writes: Array<{ path: string; contents: string }> = [];
+    const large = structuredClone(report);
+    large.summary = "x".repeat(20_000);
+    await runAction({ INPUT_ISSUE: "x", GITHUB_STEP_SUMMARY: "summary.md" }, {
+      appendFile: (path, contents) => writes.push({ path, contents }),
+      buildReport: vi.fn(async () => large),
+      fileSize: () => 1024 * 1024 - 500,
+      stdout: vi.fn()
+    });
+    expect(Buffer.byteLength(writes[0]?.contents ?? "")).toBeLessThanOrEqual(500);
+    expect(writes[0]?.contents).toContain("report truncated");
+  });
+
   it("accepts case-insensitive format input", async () => {
     const stdout = vi.fn();
     await runAction({ INPUT_ISSUE: "password reset", INPUT_FORMAT: "JSON" }, {
@@ -241,6 +272,25 @@ describe("GitHub Action runner", () => {
       stdout: vi.fn()
     })).rejects.toThrow("generated or retired location");
   });
+
+  it("opts into failing verify mode on advisory warnings", async () => {
+    const dependencies = {
+      readFile: () => JSON.stringify(report),
+      scanRepo: async () => scannedRepo(["src/auth.ts"]),
+      stdout: vi.fn()
+    };
+    await expect(runAction({
+      INPUT_MODE: "verify", INPUT_REPORT_PATH: "plan.json", INPUT_DIFF: "main...HEAD"
+    }, dependencies)).resolves.toBeUndefined();
+    await expect(runAction({
+      INPUT_MODE: "verify", INPUT_REPORT_PATH: "plan.json", INPUT_DIFF: "main...HEAD", INPUT_FAIL_ON: "warning"
+    }, dependencies)).rejects.toThrow("configured warning threshold");
+  });
+
+  it.each(["0xA", "0b101", "1e1", "+5", "5.0"])("rejects non-decimal limit spelling %s", async (limit) => {
+    await expect(runAction({ INPUT_ISSUE: "x", INPUT_LIMIT: limit }, { stdout: vi.fn() }))
+      .rejects.toThrow("whole number from 1 to 20");
+  });
 });
 
 function scannedRepo(changedFiles: string[]) {
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 19b697e..bdecdf1 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -57,7 +57,7 @@ For long task text, use `--issue-file task.md` or pipe text to `--issue -`. A le
 - **Plan** — rank context files, related tests, test commands, risks, changed files, diagnostics, grounding, confidence, and a next action from task text, a task file, stdin, a public GitHub issue or pull request, a branch diff, or the working tree.
 - **Explain** — use `--explain <path>` to distinguish ranked, below-cutoff, tie-truncated, excluded, and not-scanned paths.
 - **Compare** — use `--compare <report.json>` to measure how a refined task changed ranks, scores, confidence, and grounding.
-- **Verify** — compare a saved plan with the completed diff or working tree; FixMap reports drift but does not pretend to run tests or prove correctness.
+- **Verify** — compare a saved plan with the completed diff or working tree; errors fail by default and `--fail-on warning` provides an opt-in strict CI gate without pretending FixMap ran tests or proved correctness.
 - **Validate** — run `fixmap validate <report.json>` to check report compatibility without writing custom JavaScript.
 - **Focus controls** — cap output with `--limit`, repeat `--exclude`, or use ordered `.fixmapignore` patterns with negation. Pasted absolute paths inside the repository are normalized, and unmatched patterns produce a warning.
 - **Live changes** — `--working-tree` maps staged and unstaged tracked edits; `--include-untracked` opts new files into the changed-file set.
@@ -104,7 +104,7 @@ fixmap setup           Install /fixmap discovery for supported coding agents
 fixmap mcp             Run FixMap as an MCP server over stdio
 
 --issue <text|url>     Issue text, task description, or public GitHub issue or pull request URL
---issue-file <file>    Read task text from a UTF-8 or UTF-16 file, or - for stdin
+--issue-file <file>    Read UTF-8/UTF-16 task text (including BOM-less UTF-16), or - for stdin
 --diff <spec>          Git diff spec, such as main...HEAD
 --base <ref>           Base ref for diffing when --diff is not given
 --head <ref>           Head ref for diffing (defaults to HEAD)
@@ -118,6 +118,7 @@ fixmap mcp             Run FixMap as an MCP server over stdio
 --repo <source>        Local path, file:// URL, or public GitHub HTTPS/SSH URL
 --format <fmt>         Output format: markdown (default) or json
 --output <file>        Write the report to a file instead of stdout
+--fail-on <level>      Verify exit policy: error (default) or warning
 ```
 
 ## Example output
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 0f7936c..8418bf5 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@aryam/fixmap",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "mcpName": "io.github.aryamthecodebreaker/fixmap",
   "description": "Local-first CLI and MCP server mapping GitHub issue URLs, tasks, and diffs to ranked files, tests, and risks.",
   "license": "MIT",
@@ -46,7 +46,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@aryam/fixmap-core": "0.8.8",
+    "@aryam/fixmap-core": "0.8.9",
     "@modelcontextprotocol/sdk": "1.30.0"
   },
   "engines": {
diff --git a/packages/cli/src/agent-setup.ts b/packages/cli/src/agent-setup.ts
index cc33c1f..0727695 100644
--- a/packages/cli/src/agent-setup.ts
+++ b/packages/cli/src/agent-setup.ts
@@ -9,13 +9,21 @@ export const FIXMAP_FEATURES = [
   { name: "Plan", command: "fixmap plan", detail: "Rank context files, test routes, risks, changed files, and uncertainty from a task, issue URL, diff, or working tree." },
   { name: "Explain", command: "fixmap plan --explain <path>", detail: "Show whether a path ranked, tied below the limit, was excluded, or was never scanned." },
   { name: "Compare", command: "fixmap plan --compare <report.json>", detail: "Compare a refined task and current plan with an earlier JSON report." },
-  { name: "Verify", command: "fixmap verify --report <report.json>", detail: "Compare the completed diff or working tree with the saved plan." },
+  { name: "Verify", command: "fixmap verify --report <report.json>", detail: "Compare the completed diff or working tree with the saved plan; add --fail-on warning for a strict CI gate." },
   { name: "Validate", command: "fixmap validate <report.json>", detail: "Check a saved report against FixMap's structural compatibility contract." },
   { name: "Doctor", command: "fixmap doctor", detail: "Diagnose stale local, global, PATH, and npx install shadows." },
   { name: "MCP", command: "fixmap mcp", detail: "Expose Plan, Explain, Compare, Verify, and Doctor over local stdio." },
+  { name: "Public tasks", command: "fixmap owner/repository#123", detail: "Fetch public GitHub issue or pull-request text anonymously and scan its repository in an isolated checkout." },
+  { name: "Repository sources", command: "--repo <path|url> --ref <branch|tag>", detail: "Map a local checkout, file URL, directory archive, or a named branch or tag from a public GitHub repository." },
+  { name: "Task files", command: "--issue-file <file|->", detail: "Read long task text from UTF-8, UTF-16, or stdin, including BOM-less UTF-16 from common Windows tools." },
   { name: "Focus", command: "--limit, --exclude, .fixmapignore", detail: "Narrow ranking without changing the repository." },
   { name: "Live changes", command: "--working-tree --include-untracked", detail: "Map staged, unstaged, and optionally untracked work against HEAD." },
-  { name: "Fresh scan", command: "--no-cache", detail: "Bypass the exact git-state cache with CLI --no-cache, MCP noCache: true, or Action no-cache: true, and report that a fresh scan was used." }
+  { name: "Fresh scan", command: "--no-cache", detail: "Bypass the exact git-state cache with CLI --no-cache, MCP noCache: true, or Action no-cache: true, and report that a fresh scan was used." },
+  { name: "Machine output", command: "--format json --output <file>", detail: "Emit a versioned JSON contract or readable Markdown without executing repository code." },
+  { name: "Test routing", command: "fixmap plan", detail: "Detect package, workspace, and language test commands, related tests, and skipped or gated suites." },
+  { name: "Risk and diagnostics", command: "fixmap plan", detail: "Report bounded risk areas, grounding quality, unread content, scan limits, package-manager conflicts, and unresolved diffs." },
+  { name: "GitHub Action", command: "uses: aryamthecodebreaker/FixMap@<version>", detail: "Plan or verify pull requests with bounded summaries, outputs, and one updated comment." },
+  { name: "Agent setup", command: "fixmap setup", detail: "Install the discoverable /fixmap command for Claude Code, Cursor, GitHub Copilot, or Agent Skills." }
 ] as const;
 
 export function renderFeatureCatalog(format: "markdown" | "json" = "markdown"): string {
diff --git a/packages/cli/src/cli-runner.ts b/packages/cli/src/cli-runner.ts
index 0b04417..06bd102 100644
--- a/packages/cli/src/cli-runner.ts
+++ b/packages/cli/src/cli-runner.ts
@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import {
   compareReports,
   explainFile,
+  quoteCliValue as formatCliValue,
   renderComparisonMarkdown,
   renderExplanationMarkdown,
   renderJsonReport,
@@ -20,8 +21,10 @@ import {
 } from "@aryam/fixmap-core";
 import { runDoctorChecks, renderDoctorReport, type DoctorReport } from "./doctor.js";
 import { installAgentCommands, renderFeatureCatalog, type AgentTarget } from "./agent-setup.js";
+import { clarifyMissingPath } from "./explain-path.js";
 import {
   buildReportForRepository,
+  isSafeGitRefName,
   parseGitHubIssueSource,
   progressRequested,
   tryParseGitHubIssueSource,
@@ -36,12 +39,14 @@ export type CliOptions = {
   diffSpec?: string | undefined;
   baseRef?: string | undefined;
   headRef?: string | undefined;
+  checkoutRef?: string | undefined;
   format: "markdown" | "json";
   output?: string | undefined;
   explainPath?: string | undefined;
   reportPath?: string | undefined;
   comparePath?: string | undefined;
   limit?: number | undefined;
+  failOn?: "error" | "warning" | undefined;
   exclude: string[];
   workingTree: boolean;
   includeUntracked: boolean;
@@ -53,7 +58,7 @@ export type CliOptions = {
 export type CliDependencies = {
   buildReport?: (input: RepositoryPlanInput) => Promise<FixMapReport>;
   readVersion?: () => string;
-  runMcpServer?: () => Promise<void>;
+  runMcpServer?: (defaultRepo?: string) => Promise<void>;
   runDoctor?: () => Promise<DoctorReport>;
   stderr?: (text: string) => void;
   stdout?: (text: string) => void;
@@ -72,6 +77,7 @@ Usage:
   fixmap plan --issue-file task.md
   fixmap plan --issue -
   fixmap plan --issue "Fix login" --repo https://github.com/owner/repository
+  fixmap plan --issue "Fix login" --repo https://github.com/owner/repository --ref release-2.x
   fixmap plan --diff main...HEAD
   fixmap plan --working-tree --include-untracked --limit 12 --exclude "docs/**"
   fixmap plan --no-cache --issue "Fix login" --repo .
@@ -80,11 +86,12 @@ Usage:
   fixmap plan --base main --head HEAD --format json
   fixmap verify --report plan.json --diff main...HEAD
   fixmap verify --report plan.json --working-tree
+  fixmap verify --report plan.json --working-tree --fail-on warning
   fixmap doctor --format json
   fixmap validate plan.json
   fixmap features
   fixmap setup [--agent claude|cursor|copilot|agents|all] [--repo <path>]
-  fixmap mcp
+  fixmap mcp [--repo <path>]
 
 Commands:
   plan                Generate a FixMap report for a task or diff
@@ -105,6 +112,7 @@ Options:
   --include-untracked With --working-tree, also include untracked files
   --no-cache          Bypass the exact git-state repository scan cache
   --repo <source>     Local path or public GitHub HTTPS URL (defaults to current directory)
+  --ref <branch|tag>  Branch or tag to scan when --repo is a remote GitHub URL
   --limit <n>         Maximum context files to report (default 8, max 20)
   --exclude <glob>    Path pattern to leave out of ranking (repeatable)
   --format <fmt>      Output format: markdown (default) or json
@@ -112,6 +120,7 @@ Options:
   --explain <path>    Explain why one file was ranked where it was, or left out
   --compare <file>    Compare this plan against an earlier JSON report
   --report <file>     Verify command only: the JSON report the change was planned from
+  --fail-on <level>   Verify exit policy: error (default) or warning
   --help, -h          Show this help
   --version, -v       Show the FixMap version
 
@@ -119,10 +128,11 @@ A repository may also list exclusion patterns in .fixmapignore, one per line. Su
 syntax is *, **, ?, repository-root-leading /, directory-trailing /, comments, and ! negation.
 Absolute paths pasted from inside the repository are normalized to repository-relative patterns.
 Set FIXMAP_PROGRESS=1 to print scan and clone phases to stderr.
+Set FIXMAP_CACHE_DIR to move the OS scan cache, and FIXMAP_VERBOSE_USAGE=1 to include this full help after argument errors.
 `;
 
 const DOCTOR_USAGE = `Usage: fixmap doctor [--format markdown|json]\n\nChecks the running FixMap binary, PATH/global shadows, and known install blind spots.\n`;
-const MCP_USAGE = `Usage: fixmap mcp\n\nRuns the FixMap MCP server over stdio. Configure your MCP client to execute \"fixmap mcp\".\n`;
+const MCP_USAGE = `Usage: fixmap mcp [--repo <path>]\n\nRuns the FixMap MCP server over stdio. --repo sets the default local repository for tool calls that omit repo.\n`;
 const FEATURES_USAGE = `Usage: fixmap features [--format markdown|json]\n\nLists every FixMap capability and the command that exposes it.\n`;
 const SETUP_USAGE = `Usage: fixmap setup [--agent claude|cursor|copilot|agents|all] [--repo <path>] [--force]\n\nInstalls a /fixmap command that lists and runs FixMap workflows.\n`;
 const VALIDATE_USAGE = `Usage: fixmap validate <report.json> [--format markdown|json]\n\nChecks a saved report against FixMap's structural compatibility contract.\n`;
@@ -142,17 +152,39 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     return 0;
   }
   if (args[0] === "version" || args[0] === "--version" || args[0] === "-v") {
-    stdout(`${(dependencies.readVersion ?? readVersion)()}\n`);
-    return 0;
+    try {
+      stdout(`${(dependencies.readVersion ?? readVersion)()}\n`);
+      return 0;
+    } catch (error) {
+      stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+      return 1;
+    }
   }
   if (args[0] === "mcp") {
     if (args[1] === "--help" || args[1] === "-h") { stdout(MCP_USAGE); return 0; }
-    if (args.length > 1) { stderr(`mcp takes no options.\n\n${MCP_USAGE}`); return 1; }
+    const mcpArgs = args.slice(1);
+    let defaultRepo: string | undefined;
+    if (mcpArgs.length === 1 && mcpArgs[0]?.startsWith("--repo=")) {
+      defaultRepo = mcpArgs[0].slice("--repo=".length).trim();
+    } else if (mcpArgs.length === 2 && mcpArgs[0] === "--repo") {
+      defaultRepo = mcpArgs[1]?.trim();
+    } else if (mcpArgs.length > 0) {
+      stderr(`mcp accepts only --repo <path>.\n\n${MCP_USAGE}`);
+      return 1;
+    }
+    if (defaultRepo !== undefined && !defaultRepo) {
+      stderr(`--repo needs a non-blank local path.\n\n${MCP_USAGE}`);
+      return 1;
+    }
+    if (defaultRepo && /^https?:\/\//i.test(defaultRepo)) {
+      stderr(`mcp --repo needs a local checkout, not a remote URL.\n\n${MCP_USAGE}`);
+      return 1;
+    }
     const runMcpServer = dependencies.runMcpServer ?? (async () => {
       const module = await import("./mcp.js");
-      await module.runMcpServer();
+      await module.runMcpServer(defaultRepo);
     });
-    await runMcpServer();
+    await runMcpServer(defaultRepo);
     return 0;
   }
 
@@ -306,7 +338,7 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     return report.healthy ? 0 : 1;
   }
 
-  if ((args[0] === "plan" || args[0] === "verify") && args.slice(1).some((arg) => arg === "--help" || arg === "-h")) {
+  if ((args[0] === "plan" || args[0] === "verify") && hasStandaloneHelpFlag(args)) {
     stdout(USAGE);
     return 0;
   }
@@ -348,6 +380,10 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     stderr(withUsageHint("--report is a verify option. Did you mean --output to write this plan to a file?"));
     return 1;
   }
+  if (options.failOn) {
+    stderr(withUsageHint("--fail-on is a verify option. Use it with fixmap verify."));
+    return 1;
+  }
 
   const outputCollision = await describeOutputInputCollision(options);
   if (outputCollision) { stderr(`${outputCollision}\n`); return 1; }
@@ -372,7 +408,7 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     stderr("--include-untracked only applies with --working-tree.\n");
     return 1;
   }
-  if (options.workingTree && (options.diffSpec || options.baseRef)) {
+  if (options.workingTree && (options.diffSpec || options.baseRef || options.headRef)) {
     stderr("Use either --working-tree or --diff/--base, not both: they name different sets of changes.\n");
     return 1;
   }
@@ -392,6 +428,12 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
     stderr("--working-tree and --include-untracked need a local checkout; remote URL checkouts are always clean.\n");
     return 1;
   }
+  const remoteIssueSource = options.issueText ? tryParseGitHubIssueSource(options.issueText) : undefined;
+  const remoteRepository = /^https?:\/\//i.test(options.repo ?? "") || (!options.repo && remoteIssueSource !== undefined);
+  if (options.checkoutRef && !remoteRepository) {
+    stderr("--ref only applies when --repo is a remote GitHub URL or the issue URL infers one.\n");
+    return 1;
+  }
   const unsupportedTaskUrl = describeUnsupportedTaskUrl(options.issueText);
   if (unsupportedTaskUrl) { stderr(`${unsupportedTaskUrl}\n`); return 1; }
 
@@ -415,7 +457,12 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
         useCache: !options.noCache,
         internalExclude: localPlanArtifactExclusions(options)
       });
-      const explanation = explainFile(
+      const unresolvedDiff = repo.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
+      if (unresolvedDiff && (options.diffSpec || options.baseRef || options.headRef || options.workingTree)) {
+        stderr(`${unresolvedDiff.message}\nExplanation needs a resolvable diff to include change evidence.\n`);
+        return 1;
+      }
+      const explanation = await clarifyMissingPath(explainFile(
         repo,
         {
           issueText: options.issueText,
@@ -430,7 +477,7 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
           limit: options.limit
         },
         options.explainPath
-      );
+      ), repo, options.explainPath);
       const renderedExplanation = options.format === "json"
         ? `${JSON.stringify(explanation, null, 2)}\n`
         : renderExplanationMarkdown(explanation);
@@ -462,6 +509,7 @@ export async function runCli(args: string[], dependencies: CliDependencies = {})
       diffSpec: options.diffSpec,
       baseRef: options.baseRef,
       headRef: options.headRef,
+      checkoutRef: options.checkoutRef,
       workingTree: options.workingTree,
       includeUntracked: options.includeUntracked,
       useCache: !options.noCache,
@@ -694,6 +742,7 @@ export function expandIssueShorthand(args: string[]): string[] {
   if (!shorthand) return args;
 
   const [, owner, repository, number] = shorthand;
+  if (!/[A-Za-z]/.test(owner ?? "")) return ["plan", "--issue", first, ...args.slice(1)];
   return ["plan", "--issue", `https://github.com/${owner}/${repository}/issues/${number}`, ...args.slice(1)];
 }
 
@@ -705,14 +754,34 @@ const SINGLE_VALUE_FLAGS = new Set([
   "--diff",
   "--base",
   "--head",
+  "--ref",
   "--repo",
   "--format",
   "--report",
   "--explain",
   "--compare",
   "--limit",
+  "--fail-on",
   "--output"
 ]);
+const BOOLEAN_FLAGS = new Set(["--working-tree", "--include-untracked", "--no-cache"]);
+
+function hasStandaloneHelpFlag(args: string[]): boolean {
+  for (let index = 1; index < args.length; index += 1) {
+    const raw = args[index] ?? "";
+    if (raw === "--help" || raw === "-h") return true;
+    const separator = raw.indexOf("=");
+    const flag = separator === -1 ? raw : raw.slice(0, separator);
+    if (separator === -1 && (SINGLE_VALUE_FLAGS.has(flag) || flag === "--exclude")) index += 1;
+  }
+  return false;
+}
+
+function isKnownOptionToken(value: string): boolean {
+  const separator = value.indexOf("=");
+  const flag = separator === -1 ? value : value.slice(0, separator);
+  return SINGLE_VALUE_FLAGS.has(flag) || BOOLEAN_FLAGS.has(flag) || flag === "--exclude" || flag === "--help" || flag === "-h";
+}
 
 export const MAX_CONTEXT_FILE_LIMIT = 20;
 
@@ -724,12 +793,14 @@ export function parseArgs(args: string[]): CliOptions {
   let diffSpec: string | undefined;
   let baseRef: string | undefined;
   let headRef: string | undefined;
+  let checkoutRef: string | undefined;
   let format: "markdown" | "json" = "markdown";
   let output: string | undefined;
   let explainPath: string | undefined;
   let reportPath: string | undefined;
   let comparePath: string | undefined;
   let limit: number | undefined;
+  let failOn: "error" | "warning" | undefined;
   let workingTree = false;
   let includeUntracked = false;
   let noCache = false;
@@ -752,6 +823,7 @@ export function parseArgs(args: string[]): CliOptions {
       inlineValue === undefined &&
       followingValue !== undefined &&
       (!followingValue.startsWith("-") ||
+        (arg === "--issue" && !isKnownOptionToken(followingValue)) ||
         (arg === "--limit" && /^-\d/.test(followingValue)) ||
         ((arg === "--issue" || arg === "--issue-file") && followingValue === "-"));
     const value = inlineValue ?? (canConsumeFollowing ? followingValue : undefined);
@@ -795,6 +867,13 @@ export function parseArgs(args: string[]): CliOptions {
       consumeValue();
       if (value?.trim()) headRef = value.trim();
       else invalidValues.push("--head requires a non-empty git ref");
+    } else if (arg === "--ref") {
+      consumeValue();
+      if (value?.trim() && isSafeGitRefName(value.trim())) {
+        checkoutRef = value.trim();
+      } else {
+        invalidValues.push("--ref requires a safe branch or tag name");
+      }
     } else if (arg === "--repo") {
       consumeValue();
       if (value?.trim()) repo = expandHomePath(value.trim());
@@ -825,14 +904,20 @@ export function parseArgs(args: string[]): CliOptions {
       else invalidValues.push("--exclude requires a path or glob pattern");
     } else if (arg === "--limit") {
       consumeValue();
-      const parsed = Number(value);
-      if (value?.trim() && Number.isSafeInteger(parsed) && parsed >= 1 && parsed <= MAX_CONTEXT_FILE_LIMIT) {
+      const normalized = value?.trim() ?? "";
+      const parsed = Number(normalized);
+      if (/^\d+$/.test(normalized) && Number.isSafeInteger(parsed) && parsed >= 1 && parsed <= MAX_CONTEXT_FILE_LIMIT) {
         limit = parsed;
       } else {
         invalidValues.push(
           `--limit received ${JSON.stringify(value ?? "(missing)")}; expected a whole number from 1 to ${MAX_CONTEXT_FILE_LIMIT}`
         );
       }
+    } else if (arg === "--fail-on") {
+      consumeValue();
+      const normalized = value?.trim().toLowerCase();
+      if (normalized === "error" || normalized === "warning") failOn = normalized;
+      else invalidValues.push(`--fail-on received ${JSON.stringify(value ?? "(missing)")}; expected "error" or "warning"`);
     } else if (arg === "--working-tree") {
       if (flagCounts.has(arg)) invalidValues.push(`pass ${arg} only once`);
       flagCounts.set(arg, 1);
@@ -865,12 +950,14 @@ export function parseArgs(args: string[]): CliOptions {
     diffSpec,
     baseRef,
     headRef,
+    checkoutRef,
     format,
     output,
     explainPath,
     reportPath,
     comparePath,
     limit,
+    failOn,
     exclude,
     workingTree,
     includeUntracked,
@@ -1021,18 +1108,38 @@ function decodeIssueText(raw: string | Buffer): string {
     }
     return swapped.toString("utf16le").replace(/^\uFEFF/, "");
   }
+  if (raw.length >= 4 && raw.length % 2 === 0) {
+    let evenNuls = 0;
+    let oddNuls = 0;
+    for (let index = 0; index < raw.length; index += 2) {
+      if (raw[index] === 0) evenNuls += 1;
+      if (raw[index + 1] === 0) oddNuls += 1;
+    }
+    const pairs = raw.length / 2;
+    if (oddNuls / pairs >= 0.3 && evenNuls / pairs < 0.1) return raw.toString("utf16le");
+    if (evenNuls / pairs >= 0.3 && oddNuls / pairs < 0.1) return Buffer.from(raw).swap16().toString("utf16le");
+  }
   return raw.toString("utf8").replace(/^\uFEFF/, "");
 }
 
 function quoteCliValue(value: string): string {
-  return /\s/.test(value) ? `"${value.replaceAll('"', '\\"')}"` : value;
+  return formatCliValue(value, process.platform === "win32" ? "powershell" : "posix");
 }
 
 function readVersion(): string {
-  const packageJson = JSON.parse(
-    readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")
-  ) as { version: string };
-  return packageJson.version;
+  const path = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+  try {
+    const packageJson = JSON.parse(readFileSync(path, "utf8")) as { version?: unknown };
+    if (typeof packageJson.version !== "string" || !packageJson.version.trim()) {
+      throw new Error("the version field is missing or invalid");
+    }
+    return packageJson.version;
+  } catch (error) {
+    throw new Error(
+      `FixMap could not read its version from "${path}"; the installation looks incomplete: ` +
+      `${error instanceof Error ? error.message : String(error)}`
+    );
+  }
 }
 
 /**
@@ -1163,7 +1270,10 @@ async function runVerify(
     }
     // A generated-location edit is discarded by the next build, so it fails the command
     // rather than being reported and ignored. Everything else is advisory.
-    return result.findings.some((finding) => finding.severity === "error") ? 1 : 0;
+    const failOn = options.failOn ?? "error";
+    return result.findings.some((finding) =>
+      finding.severity === "error" || (failOn === "warning" && finding.severity === "warning")
+    ) ? 1 : 0;
   } catch (error) {
     io.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
     return 1;
@@ -1184,7 +1294,8 @@ function describeUnsupportedTaskUrl(issueText: string): string | undefined {
   if (!/^https?:\/\/\S+$/i.test(value) || tryParseGitHubIssueSource(value)) return undefined;
   return "Unsupported task URL. Use a public GitHub issue or pull request URL such as " +
     "https://github.com/owner/repository/issues/123 or /pull/123, or pass descriptive task text. " +
-    "A ?query, #fragment, and a www. or api. host are accepted and normalized; other hosts, credentials and ports are not.";
+    "The URL must use https. A ?query, #fragment, and a www. or api. host are accepted and normalized; " +
+    "other hosts, credentials and ports are not.";
 }
 
 function formatOutputError(path: string, error: unknown, kind: string): string {
diff --git a/packages/cli/src/doctor.ts b/packages/cli/src/doctor.ts
index 5d26b5e..287e647 100644
--- a/packages/cli/src/doctor.ts
+++ b/packages/cli/src/doctor.ts
@@ -8,7 +8,7 @@
 
 import { exec as execWithShell, execFile } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, parse, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
@@ -30,7 +30,9 @@ export type DoctorReport = {
 export type DoctorDependencies = {
   readVersion?: () => string;
   resolveBinary?: (name: string) => Promise<string | undefined>;
+  resolveBinaries?: (name: string) => Promise<string[]>;
   globalVersion?: () => Promise<string | undefined>;
+  projectVersion?: () => Promise<{ version: string; path: string } | undefined>;
   nodeVersion?: () => string;
   modulePath?: () => string;
   requestedPackage?: () => string | undefined;
@@ -63,11 +65,41 @@ export async function runDoctorChecks(dependencies: DoctorDependencies = {}): Pr
     findings.push({ label: "Requested package", value: `${requestedVersion} (matches)`, ok: true });
   }
 
-  const binary = await (dependencies.resolveBinary ?? resolveBinary)("fixmap");
+  const binaries = dependencies.resolveBinaries
+    ? await dependencies.resolveBinaries("fixmap")
+    : dependencies.resolveBinary
+      ? [await dependencies.resolveBinary("fixmap")].filter((entry): entry is string => Boolean(entry))
+      : await resolveBinaries("fixmap");
   const globalVersion = await (dependencies.globalVersion ?? readGlobalVersion)();
 
-  if (binary) {
-    findings.push({ label: "fixmap on PATH", value: binary, ok: true });
+  findings.push(binaries.length === 0
+    ? {
+      label: "fixmap on PATH",
+      value: "not on PATH",
+      ok: true,
+      advice: "This npx-only setup is valid. Run `npm install --global @aryam/fixmap` only if you want a persistent fixmap command."
+    }
+    : binaries.length === 1
+      ? { label: "fixmap on PATH", value: binaries[0]!, ok: true }
+      : {
+        label: "fixmap on PATH",
+        value: binaries.join("; "),
+        ok: false,
+        advice: "Multiple FixMap binaries are on PATH. Remove or reorder stale entries so one installation wins consistently."
+      });
+
+  const project = await (dependencies.projectVersion ?? (() => readProjectVersion(process.cwd())))();
+  if (project && project.version !== runningVersion) {
+    findings.push({
+      label: "Project install",
+      value: `${project.version} at ${project.path} (this process is ${runningVersion})`,
+      ok: false,
+      advice: "Update or remove the project-local @aryam/fixmap dependency so it cannot shadow the requested version."
+    });
+  } else if (project) {
+    findings.push({ label: "Project install", value: `${project.version} at ${project.path} (matches)`, ok: true });
+  } else {
+    findings.push({ label: "Project install", value: "none", ok: true });
   }
 
   // The finding that matters. A global install at a different version than the one this
@@ -133,13 +165,28 @@ function satisfiesEngine(version: string): boolean {
   return major > 20 || (major === 20 && minor >= 11);
 }
 
-async function resolveBinary(name: string): Promise<string | undefined> {
+async function resolveBinaries(name: string): Promise<string[]> {
   const command = process.platform === "win32" ? "where" : "which";
+  const args = process.platform === "win32" ? [name] : ["-a", name];
   try {
-    const { stdout } = await exec(command, [name]);
-    return stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)[0];
+    const { stdout } = await exec(command, args);
+    return [...new Set(stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean))];
   } catch {
-    return undefined;
+    return [];
+  }
+}
+
+async function readProjectVersion(start: string): Promise<{ version: string; path: string } | undefined> {
+  let current = resolve(start);
+  const root = parse(current).root;
+  while (true) {
+    const path = join(current, "node_modules", "@aryam", "fixmap", "package.json");
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf8")) as { version?: unknown };
+      if (typeof parsed.version === "string" && parsed.version.trim()) return { version: parsed.version, path };
+    } catch { /* Walk to the parent. */ }
+    if (current === root) return undefined;
+    current = dirname(current);
   }
 }
 
diff --git a/packages/cli/src/explain-path.ts b/packages/cli/src/explain-path.ts
new file mode 100644
index 0000000..f3de2ef
--- /dev/null
+++ b/packages/cli/src/explain-path.ts
@@ -0,0 +1,31 @@
+import { stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import type { FileExplanation, RepoMap } from "@aryam/fixmap-core";
+
+/** Resolve the two filesystem causes the pure core explainer cannot inspect. */
+export async function clarifyMissingPath(
+  explanation: FileExplanation,
+  repo: RepoMap,
+  requestedPath: string
+): Promise<FileExplanation> {
+  if (explanation.status !== "not-scanned" || !explanation.summary.includes("no such path")) return explanation;
+  const target = resolve(repo.root, requestedPath);
+  const distance = relative(repo.root, target);
+  if (distance === ".." || distance.startsWith(`..${sep}`) || isAbsolute(distance)) {
+    return { ...explanation, reasons: [], summary: "Not scanned: the path is outside this repository." };
+  }
+  try {
+    const metadata = await stat(target);
+    if (metadata.isFile()) {
+      const scanLimited = repo.diagnostics.some((entry) => entry.code === "scan-limit-reached");
+      return {
+        ...explanation,
+        reasons: [],
+        summary: scanLimited
+          ? "Not scanned: the file exists, but the repository scan reached its file limit before including it."
+          : "Not scanned: the file exists on disk but is ignored by Git."
+      };
+    }
+  } catch { /* The specific answer is the missing path below. */ }
+  return { ...explanation, reasons: [], summary: "Not scanned: no such path exists in this repository." };
+}
diff --git a/packages/cli/src/mcp.ts b/packages/cli/src/mcp.ts
index 3b88bc8..ce2eac9 100644
--- a/packages/cli/src/mcp.ts
+++ b/packages/cli/src/mcp.ts
@@ -20,8 +20,10 @@ import {
   type FixMapReport
 } from "@aryam/fixmap-core";
 import { renderDoctorReport, runDoctorChecks } from "./doctor.js";
+import { clarifyMissingPath } from "./explain-path.js";
 import {
   buildReportForRepository,
+  isSafeGitRefName,
   tryParseGitHubIssueSource,
   type RepositorySourceDependencies
 } from "./repository-source.js";
@@ -34,6 +36,7 @@ type PlanArguments = {
   base?: string;
   head?: string;
   repo?: string;
+  ref?: string;
   format?: "markdown" | "json";
   limit?: number;
   exclude?: string[];
@@ -110,6 +113,7 @@ const PLAN_TOOL = {
           "Local path or public GitHub HTTPS repository URL, defaults to the server working directory. " +
           "GitHub URLs support issue-only analysis and are removed after scanning."
       },
+      ref: { type: "string", description: "Branch or tag to scan when repo is a remote GitHub URL" },
       format: {
         type: "string",
         description: "Output format: markdown (default) or json, case-insensitive"
@@ -241,7 +245,8 @@ const DOCTOR_TOOL = {
 };
 
 export function createFixMapMcpServer(
-  repositorySourceDependencies: RepositorySourceDependencies = {}
+  repositorySourceDependencies: RepositorySourceDependencies = {},
+  defaultRepo = process.cwd()
 ): Server {
   const server = new Server({ name: "fixmap", version: readVersion() }, { capabilities: { tools: {} } });
 
@@ -301,7 +306,7 @@ export function createFixMapMcpServer(
       const args = parsed.value;
       try {
         const repo = await scanRepo({
-          repoRoot: args.repo ?? process.cwd(),
+          repoRoot: args.repo ?? defaultRepo,
           diffSpec: args.diff,
           baseRef: args.base,
           headRef: args.head,
@@ -345,7 +350,7 @@ export function createFixMapMcpServer(
         };
       }
       try {
-        const repoRoot = args.repo ?? process.cwd();
+        const repoRoot = args.repo ?? defaultRepo;
         const repo = await scanRepo({
           repoRoot,
           diffSpec: args.diff,
@@ -355,7 +360,7 @@ export function createFixMapMcpServer(
           includeUntracked: args.includeUntracked,
           useCache: !args.noCache
         });
-        const explanation = explainFile(
+        const explanation = await clarifyMissingPath(explainFile(
           repo,
           {
             issueText: args.issue,
@@ -364,7 +369,7 @@ export function createFixMapMcpServer(
             limit: args.limit
           },
           args.path
-        );
+        ), repo, args.path);
         const text = args.format === "json"
           ? `${JSON.stringify(explanation, null, 2)}\n`
           : renderExplanationMarkdown(explanation);
@@ -402,7 +407,8 @@ export function createFixMapMcpServer(
     let report: FixMapReport;
     try {
       report = await buildReportForRepository({
-        repo: args.repo,
+        repo: args.repo ?? (tryParseGitHubIssueSource(args.issue ?? "") ? undefined : defaultRepo),
+        checkoutRef: args.ref,
         issueText: args.issue,
         diffSpec: args.diff,
         baseRef: args.base,
@@ -449,7 +455,7 @@ export function parsePlanArguments(input: unknown): PlanArgumentsValidation {
   }
 
   const record = input as Record<string, unknown>;
-  const allowed = new Set(["issue", "diff", "base", "head", "repo", "format", "limit", "exclude", "workingTree", "includeUntracked", "noCache"]);
+  const allowed = new Set(["issue", "diff", "base", "head", "repo", "ref", "format", "limit", "exclude", "workingTree", "includeUntracked", "noCache"]);
   const unknown = Object.keys(record).filter((key) => !allowed.has(key));
   if (unknown.length > 0) {
     return {
@@ -458,13 +464,13 @@ export function parsePlanArguments(input: unknown): PlanArgumentsValidation {
     };
   }
 
-  for (const name of ["issue", "diff", "base", "head", "repo"] as const) {
+  for (const name of ["issue", "diff", "base", "head", "repo", "ref"] as const) {
     const value = record[name];
     if (value !== undefined && typeof value !== "string") {
       return { success: false, message: `"${name}" must be a string.` };
     }
   }
-  for (const name of ["issue", "diff", "base", "head", "repo"] as const) {
+  for (const name of ["issue", "diff", "base", "head", "repo", "ref"] as const) {
     if (typeof record[name] === "string" && !record[name].trim()) return { success: false, message: `"${name}" must not be blank.` };
   }
   for (const name of ["workingTree", "includeUntracked", "noCache"] as const) if (record[name] !== undefined && typeof record[name] !== "boolean") return { success: false, message: `"${name}" must be a boolean.` };
@@ -483,7 +489,7 @@ export function parsePlanArguments(input: unknown): PlanArgumentsValidation {
   }
 
   const value: PlanArguments = {};
-  for (const name of ["issue", "diff", "base", "head", "repo"] as const) {
+  for (const name of ["issue", "diff", "base", "head", "repo", "ref"] as const) {
     const candidate = record[name];
     if (typeof candidate === "string" && candidate.trim()) {
       value[name] = candidate.trim();
@@ -499,6 +505,12 @@ export function parsePlanArguments(input: unknown): PlanArgumentsValidation {
   if (record.workingTree === true) value.workingTree = true;
   if (record.includeUntracked === true) value.includeUntracked = true;
   if (record.noCache === true) value.noCache = true;
+  if (value.ref && !/^https?:\/\//i.test(value.repo ?? "") && !tryParseGitHubIssueSource(value.issue ?? "")) {
+    return { success: false, message: '"ref" requires a remote GitHub "repo" or issue URL.' };
+  }
+  if (value.ref && !isSafeGitRefName(value.ref)) {
+    return { success: false, message: '"ref" must be a safe branch or tag name.' };
+  }
   if (value.issue && /^https?:\/\/\S+$/i.test(value.issue) && !tryParseGitHubIssueSource(value.issue)) return { success: false, message: '"issue" URL must be a canonical public GitHub issue or pull request URL.' };
   return { success: true, value };
 }
@@ -696,8 +708,8 @@ function asFixMapReport(candidate: unknown, label: string): LoadedReport {
   return validateFixMapReport(candidate, label);
 }
 
-export async function runMcpServer(): Promise<void> {
-  await createFixMapMcpServer().connect(new StdioServerTransport());
+export async function runMcpServer(defaultRepo = process.cwd()): Promise<void> {
+  await createFixMapMcpServer({}, defaultRepo).connect(new StdioServerTransport());
 }
 
 function readVersion(): string {
diff --git a/packages/cli/src/repository-source.ts b/packages/cli/src/repository-source.ts
index 553db71..5f9e740 100644
--- a/packages/cli/src/repository-source.ts
+++ b/packages/cli/src/repository-source.ts
@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { mkdir, mkdtemp, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -26,6 +26,7 @@ export type RepositoryPlanInput = {
   diffSpec?: string | undefined;
   baseRef?: string | undefined;
   headRef?: string | undefined;
+  checkoutRef?: string | undefined;
   workingTree?: boolean | undefined;
   includeUntracked?: boolean | undefined;
   useCache?: boolean | undefined;
@@ -71,7 +72,8 @@ export type RepositorySourceDependencies = {
   clonePublicRepository?: (
     url: string,
     destination: string,
-    hooksDirectory: string
+    hooksDirectory: string,
+    ref?: string
   ) => Promise<ClonedRepository>;
   fetchPublicIssue?: (source: ParsedGitHubIssueSource) => Promise<PublicGitHubIssue>;
   makeTemporaryDirectory?: (prefix: string) => Promise<string>;
@@ -92,6 +94,14 @@ export type ParsedGitHubIssueSource = {
   isPullRequest?: boolean;
 };
 
+/** Conservative synchronous validation for a branch or tag passed to `git clone --branch`.
+ * It mirrors Git's forbidden refname forms without invoking a repository or a shell. */
+export function isSafeGitRefName(value: string): boolean {
+  return value.length > 0 && value.length <= 255 &&
+    value !== "@" &&
+    !/^[.-]|[./]$|[\s\u0000-\u001f\u007f~^:?*\[\\]|\.\.|\/\/|@\{|(?:^|\/)\.|(?:^|\/)[^/]*\.lock(?:\/|$)/i.test(value);
+}
+
 export type PublicGitHubIssue = {
   title: string;
   body: string;
@@ -206,7 +216,8 @@ export function parseGitHubIssueSource(input: string): ParsedGitHubIssueSource |
 
   const segments = url.pathname.split("/").filter(Boolean);
   const owner = segments[0] ?? "";
-  const repository = segments[1] ?? "";
+  const rawRepository = segments[1] ?? "";
+  const repository = rawRepository.toLowerCase().endsWith(".git") ? rawRepository.slice(0, -4) : rawRepository;
   const kindSegment = (segments[2] ?? "").toLowerCase();
   const rawNumber = segments[3] ?? "";
   const number = Number(rawNumber);
@@ -559,7 +570,8 @@ export async function buildReportForRepository(
           `The report completed, but FixMap could not remove temporary checkout "${temporaryRoot}": ` +
           `${errorDetail(cleanupError)}. Delete that directory manually when it is no longer locked.`
       });
-    }
+    },
+    input.checkoutRef
   );
 }
 
@@ -584,7 +596,8 @@ export async function withRepositorySource<T>(
   source: ParsedRepositorySource,
   work: (source: ResolvedRepositorySource) => Promise<T>,
   dependencies: RepositorySourceDependencies = {},
-  onCleanupFailure?: (result: T, cleanupError: unknown, temporaryRoot: string) => void
+  onCleanupFailure?: (result: T, cleanupError: unknown, temporaryRoot: string) => void,
+  checkoutRef?: string
 ): Promise<T> {
   if (source.kind === "local") {
     if (!(await isDirectory(source.repoRoot))) {
@@ -599,6 +612,7 @@ export async function withRepositorySource<T>(
   const removeTemporaryDirectory = dependencies.removeTemporaryDirectory ??
     ((path: string) => rm(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }));
   const clonePublicRepository = dependencies.clonePublicRepository ?? defaultClonePublicRepository;
+  await sweepStaleTemporaryRepositories();
   const temporaryRoot = await makeTemporaryDirectory(join(tmpdir(), "fixmap-github-"));
   const checkoutRoot = join(temporaryRoot, "repository");
   const hooksDirectory = join(temporaryRoot, "disabled-hooks");
@@ -612,7 +626,7 @@ export async function withRepositorySource<T>(
     let cloned: ClonedRepository;
     try {
       reportProgress(`cloning ${source.displayUrl}`);
-      cloned = await clonePublicRepository(source.cloneUrl, checkoutRoot, hooksDirectory);
+      cloned = await clonePublicRepository(source.cloneUrl, checkoutRoot, hooksDirectory, checkoutRef);
       reportProgress(`cloned ${cloned.ref}@${cloned.revision}`);
     } catch (error) {
       throw new RepositorySourceError(
@@ -669,7 +683,8 @@ function attachCleanupCause(primaryError: Error, cleanupError: unknown): void {
 async function defaultClonePublicRepository(
   url: string,
   destination: string,
-  hooksDirectory: string
+  hooksDirectory: string,
+  checkoutRef?: string
 ): Promise<ClonedRepository> {
   const isolationRoot = dirname(hooksDirectory);
   const homeDirectory = join(isolationRoot, "isolated-home");
@@ -706,6 +721,7 @@ async function defaultClonePublicRepository(
       "--quiet",
       "--depth", "1",
       "--single-branch",
+      ...(checkoutRef ? ["--branch", checkoutRef] : []),
       "--no-tags",
       "--no-recurse-submodules",
       `--template=${templateDirectory}`,
@@ -746,6 +762,27 @@ async function defaultClonePublicRepository(
   };
 }
 
+const STALE_TEMPORARY_REPOSITORY_MS = 24 * 60 * 60 * 1000;
+
+async function sweepStaleTemporaryRepositories(): Promise<void> {
+  const temporaryDirectory = resolve(tmpdir());
+  try {
+    const entries = await readdir(temporaryDirectory, { withFileTypes: true });
+    await Promise.all(entries
+      .filter((entry) => entry.isDirectory() && /^fixmap-github-[A-Za-z0-9_-]+$/.test(entry.name))
+      .map(async (entry) => {
+        const target = resolve(temporaryDirectory, entry.name);
+        if (dirname(target) !== temporaryDirectory) return;
+        try {
+          const metadata = await stat(target);
+          if (Date.now() - metadata.mtimeMs > STALE_TEMPORARY_REPOSITORY_MS) {
+            await rm(target, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+          }
+        } catch { /* Cleanup is best effort. */ }
+      }));
+  } catch { /* A locked temp directory must not block a report. */ }
+}
+
 async function isDirectory(path: string): Promise<boolean> {
   try {
     return (await stat(path)).isDirectory();
diff --git a/packages/cli/test/cli-runner.test.ts b/packages/cli/test/cli-runner.test.ts
index 7d42795..126abf2 100644
--- a/packages/cli/test/cli-runner.test.ts
+++ b/packages/cli/test/cli-runner.test.ts
@@ -1,11 +1,15 @@
+import { execFile } from "node:child_process";
 import { link, mkdir, mkdtemp, readFile, symlink, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { promisify } from "node:util";
 import { describe, expect, it, vi } from "vitest";
 import { parseArgs, runCli } from "../src/cli-runner.js";
 import { installAgentCommands } from "../src/agent-setup.js";
 import type { FixMapReport } from "@aryam/fixmap-core";
 
+const exec = promisify(execFile);
+
 const report: FixMapReport = {
   summary: "Found one context file.",
   contextFiles: [{ rank: 1, path: "README.md", score: 10, confidence: "medium", reasons: ["path matches task terms"] }],
@@ -29,6 +33,22 @@ function capture() {
 }
 
 describe("CLI argument handling", () => {
+  it("passes mcp --repo through as the server's default local checkout", async () => {
+    const runMcpServer = vi.fn(async () => undefined);
+
+    await expect(runCli(["mcp", "--repo", " C:/repo "], { runMcpServer })).resolves.toBe(0);
+
+    expect(runMcpServer).toHaveBeenCalledWith("C:/repo");
+  });
+
+  it("rejects unsupported and remote mcp server arguments", async () => {
+    const stderr = vi.fn();
+    const runMcpServer = vi.fn(async () => undefined);
+
+    expect(await runCli(["mcp", "--repo", "https://github.com/o/r"], { stderr, runMcpServer })).toBe(1);
+    expect(await runCli(["mcp", "--surprise"], { stderr, runMcpServer })).toBe(1);
+    expect(runMcpServer).not.toHaveBeenCalled();
+  });
   it.each(["--help", "-h"])("shows command help for plan %s", async (flag) => {
     const io = capture();
     const exitCode = await runCli(["plan", flag], io.dependencies);
@@ -59,6 +79,13 @@ describe("CLI argument handling", () => {
     }));
   });
 
+  it("treats all-numeric issue-like shorthand as local task text", async () => {
+    const io = capture();
+    const buildReport = vi.fn(async () => report);
+    expect(await runCli(["123/456#7"], { ...io.dependencies, buildReport })).toBe(0);
+    expect(buildReport).toHaveBeenCalledWith(expect.objectContaining({ issueText: "123/456#7" }));
+  });
+
   it("accepts a canonical GitHub issue URL without plan --issue", async () => {
     const io = capture();
     const buildReport = vi.fn(async () => report);
@@ -84,6 +111,17 @@ describe("CLI argument handling", () => {
     expect(io.stderr).toEqual([]);
   });
 
+  it("#524 reports an incomplete installation instead of throwing from --version", async () => {
+    const io = capture();
+
+    expect(await runCli(["--version"], {
+      ...io.dependencies,
+      readVersion: () => { throw new Error("package.json is missing"); }
+    })).toBe(1);
+    expect(io.stdout).toEqual([]);
+    expect(io.stderr.join("")).toContain("package.json is missing");
+  });
+
   it("lists the complete feature catalog for slash-command discovery", async () => {
     const io = capture();
 
@@ -367,6 +405,23 @@ describe("CLI argument handling", () => {
     expect(parseArgs(["plan", "--issue", "x", "--format", " JSON\n"]).format).toBe("json");
   });
 
+  it("#522 trims accidental whitespace around an output path", () => {
+    expect(parseArgs(["plan", "--issue", "x", "--output", "  plan.json  "]).output).toBe("plan.json");
+  });
+
+  it.each(["-5 offset is wrong", "--verbose has no effect"])(
+    "#520 accepts task text beginning with a hyphen: %j",
+    (issue) => expect(parseArgs(["plan", "--issue", issue]).issueText).toBe(issue)
+  );
+
+  it("#521 does not mistake --help for the missing value of --issue", async () => {
+    const io = capture();
+
+    expect(await runCli(["plan", "--issue", "--help"], io.dependencies)).toBe(1);
+    expect(io.stdout).toEqual([]);
+    expect(io.stderr.join("")).toContain("--issue requires non-empty text");
+  });
+
   it.each(["--working-tree", "--include-untracked", "--no-cache"])(
     "rejects an inline value on boolean flag %s instead of silently treating false as true",
     (flag) => {
@@ -427,6 +482,26 @@ describe("CLI argument handling", () => {
     }));
   });
 
+  it("agent report #9 reads stdin before starting a no-cache scan", async () => {
+    const io = capture();
+    const events: string[] = [];
+    const buildReport = vi.fn(async (options: { issueText?: string; useCache?: boolean }) => {
+      events.push("scan");
+      expect(options).toMatchObject({ issueText: "password reset from stdin", useCache: false });
+      return report;
+    });
+
+    expect(await runCli(["plan", "--issue-file", "-", "--no-cache"], {
+      ...io.dependencies,
+      readIssueFile: () => {
+        events.push("stdin");
+        return "password reset from stdin";
+      },
+      buildReport
+    })).toBe(0);
+    expect(events).toEqual(["stdin", "scan"]);
+  });
+
   it("treats a leading @ as literal issue text unless --issue-file is explicit", async () => {
     const io = capture();
     const buildReport = vi.fn(async () => report);
@@ -446,7 +521,9 @@ describe("CLI argument handling", () => {
   it.each([
     ["UTF-8 BOM", Buffer.from([0xef, 0xbb, 0xbf, ...Buffer.from("password reset")])],
     ["UTF-16 LE", Buffer.from([0xff, 0xfe, ...Buffer.from("password reset", "utf16le")])],
-    ["UTF-16 BE", Buffer.from([0xfe, 0xff, 0x00, 0x70, 0x00, 0x61, 0x00, 0x73, 0x00, 0x73])]
+    ["UTF-16 BE", Buffer.from([0xfe, 0xff, 0x00, 0x70, 0x00, 0x61, 0x00, 0x73, 0x00, 0x73])],
+    ["BOM-less UTF-16 LE", Buffer.from("password reset", "utf16le")],
+    ["BOM-less UTF-16 BE", Buffer.from(Buffer.from("password reset", "utf16le")).swap16()]
   ])("decodes %s issue files", async (_label, contents) => {
     const io = capture();
     const buildReport = vi.fn(async () => report);
@@ -622,7 +699,7 @@ describe("CLI argument handling", () => {
     expect(io.stderr.join("")).toContain("same file as --compare");
   });
 
-  it("writes an explanation to --output instead of silently printing it", async () => {
+  it("#518 writes an explanation to --output instead of silently printing it", async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-explain-output-"));
     const outputPath = join(root, "explanation.json");
     await writeFile(join(root, "reset.ts"), "export function sendPasswordReset() { return true; }\n");
@@ -638,6 +715,29 @@ describe("CLI argument handling", () => {
     expect(writeReport).toHaveBeenCalledWith(outputPath, expect.stringContaining('"status": "ranked"'));
   });
 
+  it("#519 fails --explain when its requested diff cannot be resolved", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-explain-diff-failure-"));
+    await writeFile(join(root, "reset.ts"), "export function sendPasswordReset() { return true; }\n");
+    const io = capture();
+
+    expect(await runCli([
+      "plan", "--issue", "password reset fails", "--repo", root,
+      "--explain", "reset.ts", "--diff", "missing...HEAD"
+    ], io.dependencies)).toBe(1);
+    expect(io.stdout).toEqual([]);
+    expect(io.stderr.join("")).toContain("Explanation needs a resolvable diff");
+  });
+
+  it("#523 reports the working-tree/head mode conflict before suggesting --base", async () => {
+    const io = capture();
+
+    expect(await runCli([
+      "plan", "--issue", "x", "--working-tree", "--head", "HEAD~1"
+    ], io.dependencies)).toBe(1);
+    expect(io.stderr.join("")).toContain("Use either --working-tree or --diff/--base");
+    expect(io.stderr.join("")).not.toContain("--head requires --base");
+  });
+
   it.each([
     ["--repo", ["plan", "--issue", "x", "--repo", ".", "--repo", "examples/tiny-auth-app"]],
     ["--format", ["plan", "--issue", "x", "--format", "markdown", "--format", "json"]],
@@ -659,11 +759,17 @@ describe("CLI argument handling", () => {
     const io = capture();
     const writeReport = vi.fn(async () => undefined);
     const directory = await mkdtemp(join(tmpdir(), "fixmap-verify-"));
+    await writeFile(join(directory, "README.md"), "first\n");
+    await exec("git", ["init", "-b", "main"], { cwd: directory });
+    await exec("git", ["-c", "user.name=FixMap Test", "-c", "user.email=fixmap@example.test", "add", "README.md"], { cwd: directory });
+    await exec("git", ["-c", "user.name=FixMap Test", "-c", "user.email=fixmap@example.test", "commit", "-m", "first"], { cwd: directory });
+    await writeFile(join(directory, "README.md"), "second\n");
+    await exec("git", ["-c", "user.name=FixMap Test", "-c", "user.email=fixmap@example.test", "commit", "-am", "second"], { cwd: directory });
     const planPath = join(directory, "plan.json");
     await writeFile(planPath, JSON.stringify(report), "utf8");
 
     const exitCode = await runCli(
-      ["verify", "--report", planPath, "--diff", "HEAD~1...HEAD", "--output", "verify.json"],
+      ["verify", "--report", planPath, "--repo", directory, "--diff", "HEAD~1...HEAD", "--output", "verify.json"],
       { ...io.dependencies, writeReport }
     );
 
@@ -691,6 +797,18 @@ describe("CLI argument handling", () => {
     expect(hint).toContain("Add --diff");
   });
 
+  it("#525 quotes shell-sensitive report paths in the copy-paste verification hint", async () => {
+    const io = capture();
+    const buildReport = vi.fn(async () => report);
+    const writeReport = vi.fn(async () => undefined);
+
+    expect(await runCli([
+      "plan", "--issue", "reset fails", "--format", "json", "--output", "my report(1).json"
+    ], { ...io.dependencies, buildReport, writeReport })).toBe(0);
+
+    expect(io.stderr.join("")).toContain("fixmap verify --report 'my report(1).json'");
+  });
+
   it("names the real diff in the verify hint when the plan had one", async () => {
     const io = capture();
     const buildReport = vi.fn(async () => report);
@@ -746,11 +864,23 @@ describe("CLI argument handling", () => {
   it.each([
     ["--limit", ["plan", "--issue", "x", "--limit", "0"]],
     ["--limit", ["plan", "--issue", "x", "--limit", "21"]],
-    ["--limit", ["plan", "--issue", "x", "--limit", "three"]]
+    ["--limit", ["plan", "--issue", "x", "--limit", "three"]],
+    ["--limit", ["plan", "--issue", "x", "--limit", "0xA"]],
+    ["--limit", ["plan", "--issue", "x", "--limit", "0b101"]],
+    ["--limit", ["plan", "--issue", "x", "--limit", "1e1"]],
+    ["--limit", ["plan", "--issue", "x", "--limit", "+5"]],
+    ["--limit", ["plan", "--issue", "x", "--limit", "5.0"]]
   ])("rejects an out-of-range %s", (_flag, args) => {
     expect(parseArgs(args).invalidValues.join(" ")).toContain("--limit received");
   });
 
+  it("parses the opt-in verify warning threshold and rejects it in plan mode", async () => {
+    expect(parseArgs(["verify", "--report", "plan.json", "--fail-on", "warning"]).failOn).toBe("warning");
+    const io = capture();
+    expect(await runCli(["plan", "--issue", "x", "--fail-on", "warning"], io.dependencies)).toBe(1);
+    expect(io.stderr.join("")).toContain("--fail-on is a verify option");
+  });
+
   it("accumulates --exclude rather than rejecting the second one", () => {
     // The one repeatable flag: naming several directories to leave out is the normal use.
     const parsed = parseArgs(["plan", "--issue", "x", "--exclude", "apps/web", "--exclude", "docs/**"]);
diff --git a/packages/cli/test/doctor.test.ts b/packages/cli/test/doctor.test.ts
index 90a68cc..2570aca 100644
--- a/packages/cli/test/doctor.test.ts
+++ b/packages/cli/test/doctor.test.ts
@@ -8,6 +8,7 @@ function dependencies(runningVersion: string, requestedPackage: string | undefin
     requestedPackage: () => requestedPackage,
     resolveBinary: async () => undefined,
     globalVersion: async () => undefined,
+    projectVersion: async () => undefined,
     nodeVersion: () => "24.13.0",
     modulePath: () => "C:/clean-prefix/node_modules/@aryam/fixmap/dist/doctor.js"
   };
@@ -44,4 +45,42 @@ describe("runDoctorChecks", () => {
     expect(report.healthy).toBe(true);
     expect(report.findings.some((finding) => finding.label === "Requested package")).toBe(false);
   });
+
+  it("always reports the PATH state when no fixmap binary is installed", async () => {
+    const report = await runDoctorChecks(dependencies("0.8.8", undefined));
+
+    expect(report.findings).toContainEqual(expect.objectContaining({
+      label: "fixmap on PATH",
+      value: "not on PATH",
+      ok: true
+    }));
+  });
+
+  it("reports every PATH binary so duplicate installs cannot hide", async () => {
+    const report = await runDoctorChecks({
+      ...dependencies("0.8.8", undefined),
+      resolveBinaries: async () => ["C:/npm/fixmap.cmd", "D:/tools/fixmap.cmd"]
+    });
+
+    expect(report.healthy).toBe(false);
+    expect(report.findings).toContainEqual(expect.objectContaining({
+      label: "fixmap on PATH",
+      value: "C:/npm/fixmap.cmd; D:/tools/fixmap.cmd",
+      ok: false
+    }));
+  });
+
+  it("flags a stale project-local package that can shadow the running version", async () => {
+    const report = await runDoctorChecks({
+      ...dependencies("0.8.8", undefined),
+      projectVersion: async () => ({ version: "0.8.7", path: "C:/repo/node_modules/@aryam/fixmap/package.json" })
+    });
+
+    expect(report.healthy).toBe(false);
+    expect(report.findings).toContainEqual(expect.objectContaining({
+      label: "Project install",
+      value: expect.stringContaining("0.8.7"),
+      ok: false
+    }));
+  });
 });
diff --git a/packages/cli/test/explain-path.test.ts b/packages/cli/test/explain-path.test.ts
new file mode 100644
index 0000000..69df21a
--- /dev/null
+++ b/packages/cli/test/explain-path.test.ts
@@ -0,0 +1,53 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import type { FileExplanation, RepoMap } from "@aryam/fixmap-core";
+import { clarifyMissingPath } from "../src/explain-path.js";
+
+function repo(root: string, diagnostics: RepoMap["diagnostics"] = []): RepoMap {
+  return {
+    root,
+    files: [],
+    packageScripts: [],
+    changedFiles: [],
+    diffText: "",
+    packageManager: "npm",
+    diagnostics
+  };
+}
+
+const missing: FileExplanation = {
+  path: "ignored.ts",
+  status: "not-scanned",
+  score: 0,
+  confidence: "low",
+  reasons: [],
+  summary: "Not scanned: no such path was present in the repository scan."
+};
+
+describe("clarifyMissingPath", () => {
+  it("distinguishes an ignored file that exists from a nonexistent path", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-explain-cause-"));
+    await writeFile(join(root, "ignored.ts"), "export const ignored = true;\n");
+
+    const ignored = await clarifyMissingPath(missing, repo(root), "ignored.ts");
+    const nonexistent = await clarifyMissingPath({ ...missing, path: "absent.ts" }, repo(root), "absent.ts");
+
+    expect(ignored.summary).toBe("Not scanned: the file exists on disk but is ignored by Git.");
+    expect(nonexistent.summary).toBe("Not scanned: no such path exists in this repository.");
+  });
+
+  it("names the scan limit when it is the observable cause", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-explain-limit-"));
+    await writeFile(join(root, "ignored.ts"), "export const late = true;\n");
+
+    const explanation = await clarifyMissingPath(missing, repo(root, [{
+      code: "scan-limit-reached",
+      severity: "warning",
+      message: "Stopped scanning."
+    }]), "ignored.ts");
+
+    expect(explanation.summary).toContain("scan reached its file limit");
+  });
+});
diff --git a/packages/cli/test/mcp.test.ts b/packages/cli/test/mcp.test.ts
index 0ebbdfe..4c32404 100644
--- a/packages/cli/test/mcp.test.ts
+++ b/packages/cli/test/mcp.test.ts
@@ -154,23 +154,39 @@ describe("fixmap mcp server", () => {
 
     const tools = await client.listTools();
 
+    expect(tools.tools.map((tool) => tool.name)).toEqual([
+      "fixmap_plan", "fixmap_verify", "fixmap_explain", "fixmap_compare", "fixmap_doctor"
+    ]);
     const plan = tools.tools.find((tool) => tool.name === "fixmap_plan");
     const verify = tools.tools.find((tool) => tool.name === "fixmap_verify");
     expect(plan).toBeDefined();
     expect(plan?.description).toContain("test commands");
-    expect(Object.keys(plan?.inputSchema.properties ?? {})).toEqual(
-      expect.arrayContaining(["issue", "diff", "base", "head", "repo", "format", "noCache"])
+    expect(Object.keys(plan?.inputSchema.properties ?? {}).sort()).toEqual(
+      ["issue", "diff", "base", "head", "repo", "ref", "format", "limit", "exclude", "workingTree", "includeUntracked", "noCache"].sort()
     );
+    expect(plan?.inputSchema.additionalProperties).toBe(false);
     expect(plan?.inputSchema.properties?.repo?.description).toContain("public GitHub HTTPS");
     expect(plan?.inputSchema.properties?.issue?.description).toContain("GitHub issue URL");
     expect(verify).toBeDefined();
-    expect(Object.keys(verify?.inputSchema.properties ?? {})).toEqual(expect.arrayContaining(["report", "noCache"]));
+    expect(Object.keys(verify?.inputSchema.properties ?? {}).sort()).toEqual(
+      ["report", "diff", "base", "head", "repo", "workingTree", "includeUntracked", "format", "noCache"].sort()
+    );
+    expect(verify?.inputSchema.required).toEqual(["report"]);
+    expect(verify?.inputSchema.additionalProperties).toBe(false);
     const explain = tools.tools.find((tool) => tool.name === "fixmap_explain");
     expect(explain).toBeDefined();
-    expect(Object.keys(explain?.inputSchema.properties ?? {})).toEqual(expect.arrayContaining(["path", "noCache"]));
-    expect(explain?.inputSchema.required).toContain("path");
-    expect(tools.tools.find((tool) => tool.name === "fixmap_compare")).toBeDefined();
-    expect(tools.tools.find((tool) => tool.name === "fixmap_doctor")).toBeDefined();
+    expect(Object.keys(explain?.inputSchema.properties ?? {}).sort()).toEqual(
+      ["path", "issue", "diff", "base", "head", "workingTree", "includeUntracked", "repo", "exclude", "limit", "format", "noCache"].sort()
+    );
+    expect(explain?.inputSchema.required).toEqual(["path"]);
+    expect(explain?.inputSchema.additionalProperties).toBe(false);
+    const compare = tools.tools.find((tool) => tool.name === "fixmap_compare");
+    expect(Object.keys(compare?.inputSchema.properties ?? {}).sort()).toEqual(["previous", "current", "format"].sort());
+    expect(compare?.inputSchema.required).toEqual(["previous", "current"]);
+    expect(compare?.inputSchema.additionalProperties).toBe(false);
+    const doctor = tools.tools.find((tool) => tool.name === "fixmap_doctor");
+    expect(Object.keys(doctor?.inputSchema.properties ?? {})).toEqual(["format"]);
+    expect(doctor?.inputSchema.additionalProperties).toBe(false);
   });
 
   it("compares two reports through MCP", async () => {
@@ -337,7 +353,7 @@ describe("fixmap mcp server", () => {
     const changedFiles = (JSON.parse(text) as { changedFiles: string[] }).changedFiles;
     expect(changedFiles).toContain("src/auth/reset-password.ts");
     expect(changedFiles).not.toContain("plan.json");
-  });
+  }, 15_000);
 
   it("rejects a truncated non-empty verify report with a structural error", async () => {
     const client = await connectClient();
@@ -421,7 +437,8 @@ describe("fixmap mcp server", () => {
 
   it("analyzes a public GitHub URL through an isolated temporary checkout", async () => {
     const client = await connectClient({
-      clonePublicRepository: async (_url, destination) => {
+      clonePublicRepository: async (_url, destination, _hooks, ref) => {
+        expect(ref).toBe("release-2.x");
         await mkdir(join(destination, "src", "auth"), { recursive: true });
         await writeFile(
           join(destination, "package.json"),
@@ -443,6 +460,7 @@ describe("fixmap mcp server", () => {
       arguments: {
         issue: "password reset emails fail",
         repo: "https://github.com/owner/repository",
+        ref: "release-2.x",
         format: "json"
       }
     });
@@ -628,6 +646,17 @@ describe("MCP surface parity", () => {
     });
   });
 
+  it("rejects unsafe remote refs before cloning", () => {
+    expect(parsePlanArguments({ issue: "x", repo: "https://github.com/o/r", ref: "feature//oops" })).toEqual({
+      success: false,
+      message: '"ref" must be a safe branch or tag name.'
+    });
+    expect(parsePlanArguments({ issue: "x", repo: "https://github.com/o/r", ref: "release-2.x" })).toEqual({
+      success: true,
+      value: { issue: "x", repo: "https://github.com/o/r", ref: "release-2.x" }
+    });
+  });
+
   it("rejects unknown compare arguments at the request handler", async () => {
     const client = await connectClient();
     const report = { summary: "No matches", contextFiles: [], testRoutes: [], risks: [], changedFiles: [], diagnostics: [] };
diff --git a/packages/core/package.json b/packages/core/package.json
index f818bc8..ff9e435 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@aryam/fixmap-core",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "description": "Deterministic local-first repository scanner, context ranker, and report renderer for coding agents.",
   "license": "MIT",
   "repository": {
diff --git a/packages/core/src/browser.ts b/packages/core/src/browser.ts
index e450b0c..0519e1e 100644
--- a/packages/core/src/browser.ts
+++ b/packages/core/src/browser.ts
@@ -7,10 +7,14 @@
 export { explainFile } from "./explain.js";
 export { buildPathExcluder, NO_EXCLUSIONS, parseIgnoreFile } from "./exclude.js";
 export { compareReports, renderComparisonMarkdown } from "./compare.js";
+export { quoteCliValue } from "./cli-quote.js";
+export type { CliShell } from "./cli-quote.js";
 export { rankContextFiles } from "./rank.js";
-export { buildReportFromRepo, buildRiskNotes, buildTestRoutes, renderMarkdownReport } from "./report.js";
+export { buildReportFromRepo, buildRiskNotes, buildTestRoutes, renderJsonReport, renderMarkdownReport } from "./report.js";
 export { tokenizePath, tokenizeText } from "./signals.js";
 export { renderVerifyMarkdown, verifyPlan } from "./verify.js";
+export { validateFixMapReport } from "./validate.js";
+export type { ValidatedFixMapReport } from "./validate.js";
 export type { FileExplanation } from "./explain.js";
 export type { PathExcluder } from "./exclude.js";
 export type { ReportComparison } from "./compare.js";
diff --git a/packages/core/src/cli-quote.ts b/packages/core/src/cli-quote.ts
new file mode 100644
index 0000000..aa28083
--- /dev/null
+++ b/packages/core/src/cli-quote.ts
@@ -0,0 +1,9 @@
+export type CliShell = "powershell" | "posix";
+
+/** Quote one command-line value for the shell the user will paste it into. */
+export function quoteCliValue(value: string, shell: CliShell = "posix"): string {
+  if (/^[\p{L}\p{N}._/\\:@+-]+$/u.test(value)) return value;
+  return shell === "powershell"
+    ? `'${value.replaceAll("'", "''")}'`
+    : `'${value.replaceAll("'", `'\\''`)}'`;
+}
diff --git a/packages/core/src/compare.ts b/packages/core/src/compare.ts
index 898506d..b8b2895 100644
--- a/packages/core/src/compare.ts
+++ b/packages/core/src/compare.ts
@@ -7,6 +7,7 @@
 // comparison can be run long after the plans were made.
 
 import type { FixMapReport, RankedFile } from "./types.js";
+import { markdownCode } from "./markdown.js";
 
 export type RankDelta = {
   path: string;
@@ -33,6 +34,8 @@ export type ReportComparison = {
 };
 
 export function compareReports(previous: FixMapReport, current: FixMapReport): ReportComparison {
+  assertUniquePaths(previous.contextFiles, "Previous report");
+  assertUniquePaths(current.contextFiles, "Current report");
   const previousByPath = indexByPath(previous.contextFiles);
   const currentByPath = indexByPath(current.contextFiles);
 
@@ -91,20 +94,43 @@ export function compareReports(previous: FixMapReport, current: FixMapReport): R
 
   const previousGrounding = previous.analysis?.grounding.specificity;
   const currentGrounding = current.analysis?.grounding.specificity;
+  const groundingComparable = previousGrounding !== undefined && currentGrounding !== undefined;
+  const groundingChanged = groundingComparable && previousGrounding !== currentGrounding;
 
   return {
-    summary: buildSummary(entered, left, moved, confidenceChanged, previous.contextFiles[0], current.contextFiles[0]),
+    summary: buildSummary(
+      entered,
+      left,
+      moved,
+      confidenceChanged,
+      previous.contextFiles[0],
+      current.contextFiles[0],
+      groundingChanged,
+      previousGrounding,
+      currentGrounding,
+      groundingComparable
+    ),
     entered,
     left,
     moved,
     confidenceChanged,
     unchanged,
-    groundingChanged: previousGrounding !== currentGrounding,
+    groundingChanged,
     ...(previousGrounding ? { previousGrounding } : {}),
     ...(currentGrounding ? { currentGrounding } : {})
   };
 }
 
+function assertUniquePaths(files: RankedFile[], label: string): void {
+  const seen = new Set<string>();
+  for (const file of files) {
+    if (seen.has(file.path)) {
+      throw new Error(`${label} has a duplicate contextFiles path: ${file.path}`);
+    }
+    seen.add(file.path);
+  }
+}
+
 function indexByPath(files: RankedFile[]): Map<string, { rank: number; file: RankedFile }> {
   return new Map(files.map((file, index) => [
     file.path,
@@ -118,9 +144,19 @@ function buildSummary(
   moved: RankDelta[],
   confidenceChanged: RankDelta[],
   previousLeader: RankedFile | undefined,
-  currentLeader: RankedFile | undefined
+  currentLeader: RankedFile | undefined,
+  groundingChanged: boolean,
+  previousGrounding: string | undefined,
+  currentGrounding: string | undefined,
+  groundingComparable: boolean
 ): string {
   if (entered.length === 0 && left.length === 0 && moved.length === 0 && confidenceChanged.length === 0) {
+    if (groundingChanged) {
+      return `The ranking is unchanged, but task grounding changed from ${previousGrounding} to ${currentGrounding}.`;
+    }
+    if (!groundingComparable && previousGrounding !== currentGrounding) {
+      return "Both plans rank the same files in the same order. One plan predates grounding analysis, so that dimension was not compared.";
+    }
     return "Both plans rank the same files in the same order. Refining the task changed nothing.";
   }
 
@@ -151,13 +187,13 @@ export function renderComparisonMarkdown(comparison: ReportComparison): string {
   }
 
   appendSection(lines, "Entered", comparison.entered, (delta) =>
-    `\`${delta.path}\` at rank ${delta.currentRank}${formatMetrics(delta.currentConfidence, delta.currentScore)}`);
+    `${markdownCode(delta.path)} at rank ${delta.currentRank}${formatMetrics(delta.currentConfidence, delta.currentScore)}`);
   appendSection(lines, "Left", comparison.left, (delta) =>
-    `\`${delta.path}\` was rank ${delta.previousRank}${formatMetrics(delta.previousConfidence, delta.previousScore)}`);
+    `${markdownCode(delta.path)} was rank ${delta.previousRank}${formatMetrics(delta.previousConfidence, delta.previousScore)}`);
   appendSection(lines, "Moved", comparison.moved, (delta) =>
-    `\`${delta.path}\` ${describeMove(delta)}`);
+    `${markdownCode(delta.path)} ${describeMove(delta)}`);
   appendSection(lines, "Confidence changed", comparison.confidenceChanged, (delta) =>
-    `\`${delta.path}\` stayed at rank ${delta.currentRank}` +
+    `${markdownCode(delta.path)} stayed at rank ${delta.currentRank}` +
     `${delta.currentScore === undefined ? "" : ` and score ${delta.currentScore}`}; confidence changed from ` +
     `${delta.previousConfidence ?? "unknown"} to ${delta.currentConfidence ?? "unknown"}`);
 
diff --git a/packages/core/src/explain.ts b/packages/core/src/explain.ts
index 50b26c8..af6aa05 100644
--- a/packages/core/src/explain.ts
+++ b/packages/core/src/explain.ts
@@ -6,7 +6,8 @@
 // checkable cause rather than a score.
 
 import type { PathExcluder } from "./exclude.js";
-import { isBackupPath, isGeneratedPath, isRecordedEvaluationOutput, moduleStem } from "./paths.js";
+import { isBackupPath, isGeneratedPath, isRecordedEvaluationOutput, LOCKFILE_NAMES, moduleStem, pathMatchesMention } from "./paths.js";
+import { markdownCode } from "./markdown.js";
 import { REPORT_SCORE_CUTOFF, rankContextFiles } from "./rank.js";
 import { extractFileMentions } from "./signals.js";
 import type { RankedFile, RepoMap } from "./types.js";
@@ -90,7 +91,9 @@ export function explainFile(
     return {
       path,
       status: exclusion.status,
-      reasons: [exclusion.summary.replace(/^(?:Excluded|Not scanned):\s*/, "")],
+      reasons: exclusion.status === "not-scanned"
+        ? []
+        : [exclusion.summary.replace(/^(?:Excluded|Not scanned):\s*/, "")],
       summary: exclusion.summary
     };
   }
@@ -100,24 +103,27 @@ export function explainFile(
   const everything = rankContextFiles(repo, input, Number.MAX_SAFE_INTEGER, Number.NEGATIVE_INFINITY);
   const scored = everything.find((file) => file.path === path);
   const lowestReported = reported[reported.length - 1]?.score;
-  const outsideLimit = scored !== undefined && lowestReported !== undefined && scored.score >= lowestReported;
+  const limit = input.limit ?? 8;
+  const reportIsFull = reported.length >= limit;
+  const cutoff = reportIsFull && lowestReported !== undefined ? lowestReported : REPORT_SCORE_CUTOFF;
+  const outsideLimit = reportIsFull && scored !== undefined && lowestReported !== undefined && scored.score >= lowestReported;
 
   return {
     path,
     status: outsideLimit ? "outside-limit" : "below-cutoff",
     score: scored?.score ?? 0,
-    cutoff: lowestReported ?? REPORT_SCORE_CUTOFF,
+    cutoff,
     reasons: scored?.reasons ?? [],
     summary: outsideLimit
       ? `Scored ${scored.score}, tied with or above the lowest reported score of ${lowestReported}, but fell outside the top ${reported.length} after score and path tie-breaking.`
-      : `Scored ${scored?.score ?? 0}, below the ${reported.length > 0 ? `lowest reported score of ${lowestReported}` : `reporting cutoff of ${REPORT_SCORE_CUTOFF}`}. ` +
+      : `Scored ${scored?.score ?? 0}, below the reporting cutoff of ${REPORT_SCORE_CUTOFF}. ` +
         "Name a symbol, error string, or path from this file in the task to raise it."
   };
 }
 
 /** Renders one file's explanation. The summary carries the answer; reasons show the working. */
 export function renderExplanationMarkdown(explanation: FileExplanation): string {
-  const lines = [`# Why ${explanation.path}`, "", explanation.summary];
+  const lines = [`# Why ${markdownCode(explanation.path)}`, "", explanation.summary];
   if (explanation.reasons.length > 0) {
     lines.push("", "## Signals", "");
     for (const reason of explanation.reasons) {
@@ -169,7 +175,7 @@ function describeExclusion(
   }
 
   const mentioned = [...extractFileMentions(input.issueText ?? "")]
-    .some((mention) => path === mention || path.endsWith(`/${mention}`) || mention.endsWith(`/${path}`));
+    .some((mention) => pathMatchesMention(path, mention));
   if (mentioned) {
     return null;
   }
@@ -186,17 +192,11 @@ function describeExclusion(
       summary: `Not scanned: ${file.extension || "this file type"} is outside the supported source extensions.`
     };
   }
-  if (LOCKFILES.has(path.split("/").pop() ?? "")) {
+  if (LOCKFILE_NAMES.has(path.split("/").pop() ?? "")) {
     return { status: "excluded", summary: "Excluded: lockfiles are never edit targets." };
   }
-  if (path.startsWith("benchmarks/")) {
-    if (isRecordedEvaluationOutput(path)) {
-      return { status: "excluded", summary: "Excluded: recorded evaluation output is regenerated by the evaluation record command, not edited by hand." };
-    }
-    return {
-      status: "excluded",
-      summary: "Excluded: benchmark fixtures are ranked only when the task is about evaluation."
-    };
+  if (isRecordedEvaluationOutput(path)) {
+    return { status: "excluded", summary: "Excluded: recorded evaluation output is regenerated by the evaluation record command, not edited by hand." };
   }
 
   if (isGeneratedPath(path) && !repo.changedFiles.includes(path)) {
@@ -218,5 +218,3 @@ function describeExclusion(
 
   return null;
 }
-
-const LOCKFILES = new Set(["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"]);
diff --git a/packages/core/src/grounding.ts b/packages/core/src/grounding.ts
index 35f963e..251c552 100644
--- a/packages/core/src/grounding.ts
+++ b/packages/core/src/grounding.ts
@@ -1,4 +1,5 @@
-import { extractTaskSignals, tokenizeText } from "./signals.js";
+import { pathMatchesMention } from "./paths.js";
+import { extractTaskSignals, tokenizeIdentifier, tokenizeText } from "./signals.js";
 import type {
   IdentifierGrounding,
   RankedFile,
@@ -7,14 +8,15 @@ import type {
 } from "./types.js";
 
 const MAX_IDENTIFIER_MATCHED_FILES = 5;
-const VAGUE_TASK_PATTERN =
-  /\b(?:improve|better|clean\s+up|cleanup|refactor|developer\s+experience|dx|general|overall|errors?|reliability|performance|codebase|quality|make|things?|please)\b/i;
+const VAGUE_TASK_PATTERN = /^\s*(?:please\s+)?(?:improve|make|clean(?:\s+(?:this|it|things?))?\s+up|cleanup|refactor)\b/i;
 // Same vocabulary, global, for stripping rather than detecting. A `g` regex carries
 // lastIndex between calls, so detection keeps its own non-global copy.
-const VAGUE_TASK_TERMS = new RegExp(VAGUE_TASK_PATTERN.source, "gi");
+const VAGUE_TASK_TERMS =
+  /\b(?:please|improve|better|clean(?:\s+(?:this|it|things?))?\s+up|cleanup|refactor|developer\s+experience|dx|general|overall|codebase|quality|make|things?)\b/gi;
 
 export type TaskGrounding = TaskAnalysis["grounding"];
 export type RankingShape = TaskAnalysis["ranking"];
+export const CLUSTERED_RANKING_MARGIN = 2;
 
 export function analyzeTaskGrounding(
   repo: RepoMap,
@@ -45,7 +47,6 @@ export function analyzeTaskGrounding(
     repo.files.some((file) => pathMatchesMention(file.path, mention))
   );
   const hasDirectAnchor =
-    repo.changedFiles.length > 0 ||
     hasMatchedFileMention ||
     resolvedIdentifierCount > 0 ||
     partiallyResolvedIdentifiers.length > 0;
@@ -55,7 +56,7 @@ export function analyzeTaskGrounding(
     return tokenizeText(file.path).has(token) || tokenizeText(file.textSample).has(token);
   });
   const singleUnmatchedToken = issueTokens.size === 1 && !singleTokenHasRepoMatch;
-  const vague = !hasDirectAnchor && (isVagueTask(issueText) || singleUnmatchedToken);
+  const vague = !hasDirectAnchor && (isVagueTaskText(issueText) || singleUnmatchedToken);
 
   return {
     specificity: hasDirectAnchor ? "anchored" : vague ? "vague" : "descriptive",
@@ -107,7 +108,7 @@ export function buildGroundedTaskTokens(
   }).tokens;
 }
 
-export function buildRankingShape(contextFiles: RankedFile[]): RankingShape {
+export function buildRankingShape(contextFiles: Array<Pick<RankedFile, "score">>): RankingShape {
   const sortedScores = contextFiles
     .map((file) => file.score)
     .sort((a, b) => b - a);
@@ -121,7 +122,7 @@ export function buildRankingShape(contextFiles: RankedFile[]): RankingShape {
   const clustered =
     topScore !== null &&
     thirdScore !== undefined &&
-    topScore - thirdScore <= 2;
+    topScore - thirdScore <= CLUSTERED_RANKING_MARGIN;
 
   return { topScore, runnerUpScore, topGap, clustered };
 }
@@ -136,7 +137,7 @@ export function buildNextAction(
     return "Verify or correct the unresolved identifiers before editing ranked files.";
   }
   if (grounding.unverifiedIdentifiers.length > 0) {
-    return "Inspect the content-unread diagnostics and make those source files readable before trusting identifier-based recommendations.";
+    return "Inspect the content diagnostics and make those source files readable before trusting identifier-based recommendations.";
   }
   if (grounding.partiallyResolvedIdentifiers.length > 0) {
     return "Verify the partially matched symbol name in the leading file before editing.";
@@ -163,10 +164,12 @@ export function buildNextAction(
 
 function groundIdentifier(repo: RepoMap, identifier: string): IdentifierGrounding {
   const definitionPattern = new RegExp(
-    `\\b(?:export\\s+)?(?:async\\s+)?(?:const|let|var|function|class|interface|type|enum|def|fn|struct|trait)\\s+${escapeRegExp(identifier)}\\b`
+    `(?<![\\p{L}\\p{N}_$])(?:export\\s+)?(?:async\\s+)?(?:function\\s*\\*?\\s*|(?:const|let|var|class|interface|type|enum|def|fn|func|fun|struct|trait)\\s+)${escapeRegExp(identifier)}(?![\\p{L}\\p{N}_$])`,
+    "u"
   );
   const exactPattern = new RegExp(
-    `(^|[^$A-Za-z0-9_])${escapeRegExp(identifier)}(?=$|[^$A-Za-z0-9_])`
+    `(?<![\\p{L}\\p{N}_$])${escapeRegExp(identifier)}(?![\\p{L}\\p{N}_$])`,
+    "u"
   );
   const definitionFiles = repo.files
     .filter((file) => definitionPattern.test(file.textSample))
@@ -195,7 +198,7 @@ function groundPartialOrUnverifiedIdentifier(
   repo: RepoMap,
   identifier: string
 ): IdentifierGrounding {
-  const identifierParts = tokenizeText(identifier);
+  const identifierParts = tokenizeIdentifier(identifier);
   const partialFiles = repo.files
     .filter((file) => hasDefinitionContainingTokens(file.textSample, identifierParts))
     .map((file) => file.path)
@@ -221,14 +224,14 @@ function hasDefinitionContainingTokens(text: string, expectedTokens: Set<string>
     return false;
   }
   const definitionPattern =
-    /\b(?:export\s+)?(?:async\s+)?(?:const|let|var|function|class|interface|type|enum|def|fn|struct|trait)\s+([$A-Za-z_][$A-Za-z0-9_]*)\b/g;
+    /(?<![\p{L}\p{N}_$])(?:export\s+)?(?:async\s+)?(?:function\s*\*?\s*|(?:const|let|var|class|interface|type|enum|def|fn|func|fun|struct|trait)\s+)([\p{L}_$][\p{L}\p{N}_$]*)(?![\p{L}\p{N}_$])/gu;
 
   for (const match of text.matchAll(definitionPattern)) {
     const name = match[1];
     if (!name) {
       continue;
     }
-    const candidateTokens = tokenizeText(name);
+    const candidateTokens = tokenizeIdentifier(name);
     if ([...expectedTokens].every((token) => candidateTokens.has(token))) {
       return true;
     }
@@ -243,6 +246,9 @@ function isAnchorIdentifier(identifier: string, issueText: string): boolean {
   if (/[_$0-9]/.test(identifier)) {
     return true;
   }
+  if (!/^[\x00-\x7F]+$/.test(identifier)) {
+    return true;
+  }
   if (/^[a-z][A-Za-z0-9_$]*[A-Z]/.test(identifier)) {
     return true;
   }
@@ -257,10 +263,13 @@ function isAnchorIdentifier(identifier: string, issueText: string): boolean {
 // upstream host" — out of the vague bucket.
 const MAX_RESIDUAL_TOKENS_FOR_VAGUE = 3;
 
-function isVagueTask(issueText: string): boolean {
+export function isVagueTaskText(issueText: string): boolean {
   if (issueText.trim().length === 0 || !VAGUE_TASK_PATTERN.test(issueText)) {
     return false;
   }
+  if (/^\s*(?:please\s+)?(?:refactor|cleanup|clean\s+up)\s+(?:broke|breaks?|caused|causes|deleted?|deletes?|fails?|failed)\b/i.test(issueText)) {
+    return false;
+  }
   const residual = tokenizeText(issueText.replace(VAGUE_TASK_TERMS, " "));
   return residual.size <= MAX_RESIDUAL_TOKENS_FOR_VAGUE;
 }
@@ -273,10 +282,6 @@ function removeIdentifiers(text: string, identifiers: string[]): string {
   );
 }
 
-function pathMatchesMention(path: string, mention: string): boolean {
-  return path === mention || path.endsWith(`/${mention}`) || mention.endsWith(`/${path}`);
-}
-
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
diff --git a/packages/core/src/import-graph.ts b/packages/core/src/import-graph.ts
index 5919ab7..b76de5f 100644
--- a/packages/core/src/import-graph.ts
+++ b/packages/core/src/import-graph.ts
@@ -23,6 +23,8 @@ const MAX_EDGES_PER_FILE = 200;
 export type ImportGraph = {
   imports: Map<string, Set<string>>;
   importedBy: Map<string, Set<string>>;
+  truncatedFiles: number;
+  truncatedEdges: number;
 };
 
 export type ImportProximity = {
@@ -32,20 +34,23 @@ export type ImportProximity = {
 };
 
 export function buildImportGraph(files: RepoFile[]): ImportGraph {
-  const parseable = files
-    .filter((file) => JS_EXTENSIONS.has(file.extension) && file.textSample.length > 0)
-    .slice(0, MAX_GRAPH_FILES);
+  const allParseable = files.filter((file) => JS_EXTENSIONS.has(file.extension) && file.textSample.length > 0);
+  const parseable = allParseable.slice(0, MAX_GRAPH_FILES);
   const repoPaths = new Set(files.map((file) => file.path));
+  const aliases = buildAliases(files);
+  const workspacePackages = buildWorkspacePackages(files);
   const imports = new Map<string, Set<string>>();
   const importedBy = new Map<string, Set<string>>();
+  let truncatedEdges = 0;
 
   for (const file of parseable) {
     let edges = 0;
     for (const specifier of extractSpecifiers(file.textSample)) {
       if (edges >= MAX_EDGES_PER_FILE) {
+        truncatedEdges += 1;
         break;
       }
-      const target = resolveSpecifier(file.path, specifier, repoPaths);
+      const target = resolveSpecifier(file.path, specifier, repoPaths, aliases, workspacePackages);
       if (!target || target === file.path) {
         continue;
       }
@@ -55,7 +60,12 @@ export function buildImportGraph(files: RepoFile[]): ImportGraph {
     }
   }
 
-  return { imports, importedBy };
+  return {
+    imports,
+    importedBy,
+    truncatedFiles: Math.max(0, allParseable.length - parseable.length),
+    truncatedEdges
+  };
 }
 
 export function findImportProximity(graph: ImportGraph, seedPaths: string[]): Map<string, ImportProximity> {
@@ -100,7 +110,7 @@ function extractSpecifiers(textSample: string): Set<string> {
   for (const pattern of SPECIFIER_PATTERNS) {
     for (const match of textSample.matchAll(pattern)) {
       const specifier = match[1];
-      if (specifier && specifier.startsWith(".")) {
+      if (specifier) {
         specifiers.add(specifier);
       }
     }
@@ -108,12 +118,36 @@ function extractSpecifiers(textSample: string): Set<string> {
   return specifiers;
 }
 
-function resolveSpecifier(fromPath: string, specifier: string, repoPaths: Set<string>): string | undefined {
+type Alias = { prefix: string; suffix: string; targets: string[] };
+
+function resolveSpecifier(
+  fromPath: string,
+  specifier: string,
+  repoPaths: Set<string>,
+  aliases: Alias[],
+  workspacePackages: Map<string, string[]>
+): string | undefined {
   const baseDir = fromPath.split("/").slice(0, -1).join("/");
-  const joined = normalizeSegments(baseDir ? `${baseDir}/${specifier}` : specifier);
-  if (joined === undefined || joined === "") {
-    return undefined;
+  const roots: string[] = [];
+  if (specifier.startsWith(".")) {
+    const joined = normalizeSegments(baseDir ? `${baseDir}/${specifier}` : specifier);
+    if (joined) roots.push(joined);
+  } else {
+    roots.push(...(workspacePackages.get(specifier) ?? []));
+    for (const alias of aliases) {
+      if (!specifier.startsWith(alias.prefix) || !specifier.endsWith(alias.suffix)) continue;
+      const middle = specifier.slice(alias.prefix.length, specifier.length - alias.suffix.length || undefined);
+      roots.push(...alias.targets.map((target) => target.replace("*", middle)));
+    }
+  }
+  for (const root of roots) {
+    const resolved = resolveCandidate(root, repoPaths);
+    if (resolved) return resolved;
   }
+  return undefined;
+}
+
+function resolveCandidate(joined: string, repoPaths: Set<string>): string | undefined {
 
   const candidates = [joined];
   const lastSegment = joined.split("/").pop() ?? "";
@@ -135,6 +169,50 @@ function resolveSpecifier(fromPath: string, specifier: string, repoPaths: Set<st
   return candidates.find((candidate) => repoPaths.has(candidate));
 }
 
+function buildWorkspacePackages(files: RepoFile[]): Map<string, string[]> {
+  const packages = new Map<string, string[]>();
+  for (const file of files.filter((entry) => entry.path === "package.json" || entry.path.endsWith("/package.json"))) {
+    try {
+      const manifest = JSON.parse(file.textSample) as { name?: unknown; source?: unknown; module?: unknown; main?: unknown; types?: unknown };
+      if (typeof manifest.name !== "string" || !manifest.name.trim()) continue;
+      const dir = file.path.split("/").slice(0, -1).join("/");
+      const declared = [manifest.source, manifest.module, manifest.main, manifest.types]
+        .filter((entry): entry is string => typeof entry === "string")
+        .map((entry) => normalizeSegments(dir ? `${dir}/${entry}` : entry))
+        .filter((entry): entry is string => Boolean(entry));
+      packages.set(manifest.name, [
+        ...declared,
+        ...(dir ? [`${dir}/src/index`, `${dir}/index`] : ["src/index", "index"])
+      ]);
+    } catch { /* A malformed manifest is reported by the scanner, not the graph. */ }
+  }
+  return packages;
+}
+
+function buildAliases(files: RepoFile[]): Alias[] {
+  const aliases: Alias[] = [];
+  for (const file of files.filter((entry) => /(^|\/)(?:tsconfig|jsconfig)(?:\.[^/]*)?\.json$/i.test(entry.path))) {
+    try {
+      const config = JSON.parse(file.textSample) as { compilerOptions?: { baseUrl?: unknown; paths?: unknown } };
+      const paths = config.compilerOptions?.paths;
+      if (!paths || typeof paths !== "object" || Array.isArray(paths)) continue;
+      const dir = file.path.split("/").slice(0, -1).join("/");
+      const baseUrl = typeof config.compilerOptions?.baseUrl === "string" ? config.compilerOptions.baseUrl : ".";
+      const base = normalizeSegments(dir ? `${dir}/${baseUrl}` : baseUrl) ?? "";
+      for (const [pattern, rawTargets] of Object.entries(paths)) {
+        if (!Array.isArray(rawTargets) || !rawTargets.every((entry) => typeof entry === "string")) continue;
+        const star = pattern.indexOf("*");
+        aliases.push({
+          prefix: star === -1 ? pattern : pattern.slice(0, star),
+          suffix: star === -1 ? "" : pattern.slice(star + 1),
+          targets: rawTargets.map((target) => normalizeSegments(base ? `${base}/${target}` : target)).filter((target): target is string => Boolean(target))
+        });
+      }
+    } catch { /* Ignore configs that are not strict JSON. */ }
+  }
+  return aliases;
+}
+
 function normalizeSegments(path: string): string | undefined {
   const segments: string[] = [];
   for (const segment of path.split("/")) {
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index e7157f5..b1f6559 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -2,6 +2,8 @@ export { buildFixMapReport, resolveExclusions } from "./plan.js";
 export { buildPathExcluder, NO_EXCLUSIONS } from "./exclude.js";
 export type { PathExcluder } from "./exclude.js";
 export { compareReports, renderComparisonMarkdown } from "./compare.js";
+export { quoteCliValue } from "./cli-quote.js";
+export type { CliShell } from "./cli-quote.js";
 export type { ReportComparison } from "./compare.js";
 export { renderVerifyMarkdown, verifyPlan } from "./verify.js";
 export { explainFile, renderExplanationMarkdown } from "./explain.js";
@@ -16,7 +18,7 @@ export { buildImportGraph, findImportProximity } from "./import-graph.js";
 export { detectPrimaryLanguage } from "./languages.js";
 export type { LanguageDetection, PrimaryLanguage } from "./languages.js";
 export { rankContextFiles } from "./rank.js";
-export { buildRiskNotes, buildSummary, buildTestRoutes, pathsForRiskArea, renderJsonReport, renderMarkdownReport } from "./report.js";
+export { buildReportFromRepo, buildRiskNotes, buildSummary, buildTestRoutes, pathsForRiskArea, renderJsonReport, renderMarkdownReport } from "./report.js";
 export { scanRepo } from "./repo-scan.js";
 export { validateFixMapReport } from "./validate.js";
 export type { ValidatedFixMapReport } from "./validate.js";
diff --git a/packages/core/src/languages.ts b/packages/core/src/languages.ts
index 27ffb11..7d844f9 100644
--- a/packages/core/src/languages.ts
+++ b/packages/core/src/languages.ts
@@ -12,7 +12,7 @@
 
 import type { RepoFile, RepoMap } from "./types.js";
 
-export type PrimaryLanguage = "node" | "python" | "go" | "rust" | "unknown";
+export type PrimaryLanguage = "node" | "python" | "go" | "rust" | "ruby" | "php" | "java" | "dotnet" | "unknown";
 
 /** Root manifests, in the sense of "the file this toolchain requires at the top level". */
 const ROOT_MANIFESTS: Readonly<Record<string, PrimaryLanguage>> = {
@@ -26,7 +26,12 @@ const ROOT_MANIFESTS: Readonly<Record<string, PrimaryLanguage>> = {
   // reads as a guess when the root was in fact explicit.
   "requirements.txt": "python",
   "pipfile": "python",
-  "package.json": "node"
+  "package.json": "node",
+  "gemfile": "ruby",
+  "composer.json": "php",
+  "pom.xml": "java",
+  "build.gradle": "java",
+  "build.gradle.kts": "java"
 };
 
 const EXTENSION_LANGUAGES: Readonly<Record<string, PrimaryLanguage>> = {
@@ -38,7 +43,11 @@ const EXTENSION_LANGUAGES: Readonly<Record<string, PrimaryLanguage>> = {
   ".js": "node",
   ".jsx": "node",
   ".mjs": "node",
-  ".cjs": "node"
+  ".cjs": "node",
+  ".rb": "ruby",
+  ".php": "php",
+  ".java": "java",
+  ".cs": "dotnet"
 };
 
 export type LanguageDetection = {
@@ -95,7 +104,7 @@ function rootManifestLanguages(files: RepoFile[]): Map<PrimaryLanguage, string>
     if (file.path.includes("/")) {
       continue;
     }
-    const language = ROOT_MANIFESTS[file.path.toLowerCase()];
+    const language = languageForManifest(file.path.toLowerCase());
     if (language && !found.has(language)) {
       found.set(language, file.path);
     }
@@ -121,7 +130,7 @@ export function nearestManifest(
   const candidates = files
     .filter((file) => {
       const name = file.path.split("/").pop()?.toLowerCase() ?? "";
-      return ROOT_MANIFESTS[name] === language;
+      return languageForManifest(name) === language;
     })
     .sort((a, b) =>
       a.path.split("/").length - b.path.split("/").length || a.path.localeCompare(b.path)
@@ -186,13 +195,34 @@ export function manifestTestCommand(
     return { command: "go test ./...", reason: "go.mod at the repository root" };
   }
   if (language === "rust") {
-    return packageDir
-      ? {
-        command: `cargo test --manifest-path ${packageDir}/Cargo.toml`,
-        reason: `nearest crate (${packageDir}) declared by Cargo.toml`
-      }
+    const requestedManifest = packageDir
+      ? files.find((file) => file.path.toLowerCase() === `${packageDir}/cargo.toml`.toLowerCase())
+      : undefined;
+    const manifest = requestedManifest
+      ? { path: requestedManifest.path, packageDir }
+      : nearestManifest(files, "rust");
+    if (!manifest) return { command: "cargo test", reason: "Rust source files; no Cargo.toml was found" };
+    return manifest.packageDir
+      ? { command: `cargo test --manifest-path ${manifest.path}`, reason: `nearest crate (${manifest.packageDir}) declared by ${manifest.path}` }
       : { command: "cargo test", reason: "Cargo.toml at the repository root" };
   }
+  const manifest = nearestManifest(files, language);
+  if (language === "ruby" && manifest) {
+    return { command: "bundle exec rspec", reason: `${manifest.path} declares the Ruby bundle` };
+  }
+  if (language === "php" && manifest) {
+    return { command: "composer test", reason: `${manifest.path} declares Composer scripts` };
+  }
+  if (language === "java" && manifest) {
+    return manifest.path.toLowerCase().endsWith("pom.xml")
+      ? { command: "mvn test", reason: `${manifest.path} declares a Maven project` }
+      : { command: "./gradlew test", reason: `${manifest.path} declares a Gradle project` };
+  }
+  if (language === "dotnet") {
+    return manifest
+      ? { command: `dotnet test${manifest.packageDir ? ` ${manifest.path}` : ""}`, reason: `${manifest.path} declares a .NET project` }
+      : { command: "dotnet test", reason: ".NET source files; no project file was found" };
+  }
   return undefined;
 }
 
@@ -202,13 +232,17 @@ export function suggestedRunner(language: PrimaryLanguage, files: RepoFile[]): s
     // Matching on the basename rather than the full path: a repository whose only manifest
     // is `svc/pyproject.toml` configures pytest exactly as much as one that keeps it at the
     // root, and the vaguer "pytest or unittest" was hedging against nothing.
-    const names = new Set(
-      files.map((file) => file.path.split("/").pop()?.toLowerCase() ?? "")
-    );
-    if (names.has("tox.ini")) {
+    const configs = files
+      .filter((file) => ["tox.ini", "pytest.ini", "pyproject.toml", "setup.cfg"].includes(file.path.split("/").pop()?.toLowerCase() ?? ""))
+      .sort((a, b) =>
+        a.path.split("/").length - b.path.split("/").length ||
+        Number((b.path.split("/").pop()?.toLowerCase() ?? "") === "tox.ini") - Number((a.path.split("/").pop()?.toLowerCase() ?? "") === "tox.ini") ||
+        a.path.localeCompare(b.path));
+    const nearest = configs[0]?.path.split("/").pop()?.toLowerCase();
+    if (nearest === "tox.ini") {
       return "tox";
     }
-    if (names.has("pytest.ini") || names.has("pyproject.toml") || names.has("setup.cfg")) {
+    if (nearest) {
       return "pytest";
     }
     return "pytest or unittest";
@@ -219,5 +253,14 @@ export function suggestedRunner(language: PrimaryLanguage, files: RepoFile[]): s
   if (language === "rust") {
     return "cargo test";
   }
+  if (language === "ruby") return "bundle exec rspec";
+  if (language === "php") return "composer test or vendor/bin/phpunit";
+  if (language === "java") return "mvn test or ./gradlew test";
+  if (language === "dotnet") return "dotnet test";
   return undefined;
 }
+
+function languageForManifest(path: string): PrimaryLanguage | undefined {
+  const name = path.split("/").pop()?.toLowerCase() ?? path.toLowerCase();
+  return ROOT_MANIFESTS[name] ?? (/\.(?:csproj|fsproj|vbproj)$/.test(name) ? "dotnet" : undefined);
+}
diff --git a/packages/core/src/markdown.ts b/packages/core/src/markdown.ts
new file mode 100644
index 0000000..bcf66b8
--- /dev/null
+++ b/packages/core/src/markdown.ts
@@ -0,0 +1,7 @@
+/** Render arbitrary repository text as a CommonMark code span without breaking on backticks. */
+export function markdownCode(value: string): string {
+  const longestRun = Math.max(0, ...[...value.matchAll(/`+/g)].map((match) => match[0].length));
+  const fence = "`".repeat(longestRun + 1);
+  const needsPadding = value.startsWith("`") || value.endsWith("`") || value.startsWith(" ") || value.endsWith(" ");
+  return `${fence}${needsPadding ? " " : ""}${value}${needsPadding ? " " : ""}${fence}`;
+}
diff --git a/packages/core/src/paths.ts b/packages/core/src/paths.ts
index 808bb2a..1b34533 100644
--- a/packages/core/src/paths.ts
+++ b/packages/core/src/paths.ts
@@ -1,6 +1,9 @@
 // Directories that never hold first-party source and can be large enough to exhaust the
 // scan budget on their own. These are skipped in every scan mode.
 export const ALWAYS_IGNORED_DIRS = new Set([".cache", ".git", ".venv", "node_modules"]);
+export const LOCKFILE_NAMES = new Set([
+  "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"
+]);
 
 // Conventionally generated output. `git ls-files --exclude-standard` already drops these
 // through .gitignore, so a file git still reports from one of them was committed on
@@ -23,6 +26,14 @@ export const GENERATED_DIRS = new Set([
   "vendor"
 ]);
 
+/** Extensions FixMap reads as source. Shared with task-path extraction so a file cannot
+ * be scannable while remaining impossible to name explicitly in an issue. */
+export const SOURCE_FILE_EXTENSIONS = new Set([
+  ".cjs", ".cs", ".css", ".cts", ".go", ".gradle", ".java", ".js", ".json",
+  ".jsx", ".md", ".mjs", ".mts", ".php", ".py", ".rb", ".rs", ".svelte",
+  ".ts", ".tsx", ".vue", ".yaml", ".yml"
+]);
+
 // Words that mark a directory as a retired copy rather than maintained source. Matched
 // per word inside a path segment, so "untracked quarantine" and "src/legacy" both count
 // while "archiver" and "bold" do not.
@@ -45,7 +56,9 @@ const BACKUP_FILE_PATTERNS = [
   /~$/,
   /\bconflicted copy\b/i,
   /\bconflict(?:ed)?[-_ ]copy\b/i,
-  /[-_ ]copy(?:\s*\(\d+\))?\.[^.]+$/i,
+  // A bare `-copy`/`_copy` is an ordinary module name (`deep-copy.ts`). Sync clients use
+  // a space before "copy", or add a numbered suffix to the hyphen/underscore form.
+  /(?: copy|[-_]copy\s*\(\d+\))\.[^.]+$/i,
   /\s\(\d+\)\.[^.]+$/
 ];
 
@@ -79,14 +92,31 @@ const SOURCE_ROOT_DIRS = new Set(["lib", "source", "src"]);
  * index.js` (stem `supports-color/index`) stays distinct from `source/index.js` (`index`).
  */
 export function moduleStem(path: string): string {
-  return path
-    .replace(/\.[^./]+$/, "")
-    .split("/")
-    .filter((segment) => {
-      const normalized = segment.toLowerCase();
-      return !GENERATED_DIRS.has(normalized) && !SOURCE_ROOT_DIRS.has(normalized);
-    })
-    .join("/");
+  const segments = path.replace(/\.[^./]+$/, "").split("/");
+  const rootIndex = segments.findIndex((segment) => {
+    const normalized = segment.toLowerCase();
+    return GENERATED_DIRS.has(normalized) || SOURCE_ROOT_DIRS.has(normalized);
+  });
+  // Strip exactly one layout root. Removing every `lib`, `src`, or `dist` segment made
+  // `src/foo/lib/index.ts` collide with the unrelated `src/lib/foo/index.ts`.
+  if (rootIndex !== -1) segments.splice(rootIndex, 1);
+  return segments.join("/");
+}
+
+/** Match an explicit task path without letting a nested mention boost a root-level file
+ * that merely shares its basename. A longer mention may omit the repository/package
+ * prefix only when the scanned path itself still contains directory context. */
+export function pathMatchesMention(path: string, mention: string): boolean {
+  const normalizedPath = path.replace(/\\/g, "/").toLowerCase();
+  const normalizedMention = mention.replace(/\\/g, "/").toLowerCase();
+  if (normalizedPath === normalizedMention ||
+    normalizedPath.endsWith(`/${normalizedMention}`) ||
+    (normalizedPath.includes("/") && normalizedMention.endsWith(`/${normalizedPath}`))) return true;
+  if (!normalizedMention.includes("/") && !normalizedMention.includes(".")) {
+    const fileName = normalizedPath.split("/").at(-1) ?? "";
+    return fileName.replace(/\.[^.]+$/, "") === normalizedMention;
+  }
+  return false;
 }
 
 /** True when the path looks like a retired copy: a backup directory, or a tool-left duplicate filename. */
diff --git a/packages/core/src/plan.ts b/packages/core/src/plan.ts
index 6a98a6b..61527e7 100644
--- a/packages/core/src/plan.ts
+++ b/packages/core/src/plan.ts
@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { buildPathExcluder, parseIgnoreFile, NO_EXCLUSIONS } from "./exclude.js";
+import { markdownCode } from "./markdown.js";
 import type { PathExcluder } from "./exclude.js";
 import { buildReportFromRepo } from "./report.js";
 import { scanRepo } from "./repo-scan.js";
@@ -36,7 +37,7 @@ export async function buildFixMapReport(
       !pattern.startsWith("!") && !requestedExclude.matchedPatterns.has(pattern)
     );
     if (unmatchedPatterns.length > 0) {
-      const sample = unmatchedPatterns.slice(0, 5).join(", ");
+      const sample = unmatchedPatterns.slice(0, 5).map(markdownCode).join(", ");
       report.diagnostics.push({
         code: "exclusion-no-match",
         severity: "warning",
@@ -51,8 +52,9 @@ export async function buildFixMapReport(
         severity: report.contextFiles.length === 0 ? "warning" : "info",
         message:
           `${requestedExclude.patterns.length} exclusion ${requestedExclude.patterns.length === 1 ? "pattern" : "patterns"} ` +
-          `removed ${excludedPaths.length} ${excludedPaths.length === 1 ? "path" : "paths"} from ranking: ${requestedExclude.patterns.join(", ")}. ` +
-          "Run --explain on a file you expected to see if this is why it is absent."
+          `removed ${excludedPaths.length} ${excludedPaths.length === 1 ? "path" : "paths"} from ranking: ${requestedExclude.patterns.map(markdownCode).join(", ")}. ` +
+          "Run --explain on a file you expected to see if this is why it is absent.",
+        paths: excludedPaths.slice(0, 8)
       });
     }
   }
diff --git a/packages/core/src/rank.ts b/packages/core/src/rank.ts
index 7709c95..f2d1b78 100644
--- a/packages/core/src/rank.ts
+++ b/packages/core/src/rank.ts
@@ -4,17 +4,24 @@ import { buildImportGraph, findImportProximity } from "./import-graph.js";
 import type { ImportProximity } from "./import-graph.js";
 import {
   analyzeTaskGrounding,
-  buildGroundedTaskTokens
+  buildRankingShape,
+  buildGroundedTaskTokens,
+  CLUSTERED_RANKING_MARGIN,
+  isVagueTaskText
 } from "./grounding.js";
 import type { TaskGrounding } from "./grounding.js";
-import { isBackupPath, isGeneratedPath, isRecordedEvaluationOutput, moduleStem } from "./paths.js";
+import { isBackupPath, isGeneratedPath, isRecordedEvaluationOutput, LOCKFILE_NAMES, moduleStem, pathMatchesMention } from "./paths.js";
 import { extractTaskSignals, tokenizePath, tokenizeText } from "./signals.js";
 import type { RankedFile, RepoMap } from "./types.js";
 
 const DEPLOYMENT_TERMS = [
   "deploy", "deployment", "vercel", "netlify", "docker", "kubernetes", "hosting", "serverless", "production"
 ];
-const LOCKFILES = new Set(["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"]);
+const CONFIGURATION_TERMS = ["config", "configuration", "workflow", "action", "ci", "yaml"];
+const PRESENTATION_TERMS = [
+  "browser", "button", "client", "display", "form", "frontend", "layout", "page", "screen", "ui", "visitor", "web", "website"
+];
+export const RANKING_SIGNAL_TERMS = [...DEPLOYMENT_TERMS, ...CONFIGURATION_TERMS, ...PRESENTATION_TERMS];
 const AUXILIARY_CODE_DIRS = new Set(["demo", "demos", "example", "examples", "sample", "samples"]);
 const COMPILED_TO_SOURCE_MENTION_EXTENSIONS: Readonly<Record<string, readonly string[]>> = {
   ".js": [".ts", ".tsx"],
@@ -26,10 +33,13 @@ const MAX_FILES_PER_MENTION = 5;
 const MAX_PROXIMITY_SEEDS = 5;
 const IMPORT_PROXIMITY_BOOSTS: Record<ImportProximity["distance"], number> = { 1: 4, 2: 2 };
 const EXAMPLE_CODE_PENALTY = 8;
+const AUXILIARY_REPRODUCTION_PENALTY = 20;
 const PRESENTATION_CODE_PENALTY = 8;
+const INTERACTIVE_PRESENTATION_BOOST = 4;
 const TYPE_DECLARATION_PENALTY = 4;
+const TYPE_DECLARATION_DIRECT_PENALTY = 8;
 const BACKUP_COPY_PENALTY = 10;
-const BUNDLED_OUTPUT_PENALTY = 12;
+const BUNDLED_OUTPUT_PENALTY = 16;
 const GENERATED_TWIN_PENALTY = 21;
 const GENERATED_TWIN_REASON = "generated build artifact; maintained source counterpart exists";
 // Bundlers strip newlines; people do not. A file averaging hundreds of characters per
@@ -52,7 +62,7 @@ const BUNDLE_MARKERS = [
   /\b__defProp\s*=/,
   /\/\/# sourceMappingURL=/
 ] as const;
-const EXPLICIT_PATH_BOOST = 40;
+const EXPLICIT_PATH_BOOST = 60;
 const EXACT_LITERAL_BOOST = 8;
 const MEMBER_MENTION_BOOST = 8;
 // A term counts as repository-wide boilerplate only when nearly every file carries it.
@@ -66,7 +76,7 @@ const MAX_DEFINITION_IDENTIFIERS = 2;
 const TASK_MATCHED_DEFINITION_BOOST = 4;
 // How close to the leader a file must score to share its "high" label. Two points matches
 // the window `isClusteredRanking` already treats as indistinguishable.
-const HIGH_CONFIDENCE_MARGIN = 2;
+const HIGH_CONFIDENCE_MARGIN = CLUSTERED_RANKING_MARGIN;
 
 type ScoredFile = { path: string; score: number; isChanged: boolean; reasons: string[] };
 type DefinitionSignal = { identifier: string; pattern: RegExp };
@@ -76,6 +86,19 @@ export const REPORT_SCORE_CUTOFF = 4;
 export const DEFAULT_CONTEXT_FILE_LIMIT = 8;
 
 export function rankContextFiles(
+  repo: RepoMap,
+  input: {
+    issueText?: string | undefined;
+    diffText?: string | undefined;
+    exclude?: PathExcluder | undefined;
+  },
+  limit = DEFAULT_CONTEXT_FILE_LIMIT,
+  minScore = REPORT_SCORE_CUTOFF
+): RankedFile[] {
+  return rankContextFilesDetailed(repo, input, limit, minScore).contextFiles;
+}
+
+export function rankContextFilesDetailed(
   repo: RepoMap,
   input: {
     issueText?: string | undefined;
@@ -86,7 +109,7 @@ export function rankContextFiles(
   // `explainFile` lowers this to see what a file scored below the reporting cutoff.
   // Ranking never calls it with anything but the default.
   minScore = REPORT_SCORE_CUTOFF
-): RankedFile[] {
+): { contextFiles: RankedFile[]; ranking: import("./grounding.js").RankingShape } {
   const exclude = input.exclude ?? NO_EXCLUSIONS;
   const signals = extractTaskSignals({
     issueText: input.issueText ?? "",
@@ -100,8 +123,7 @@ export function rankContextFiles(
     changedFiles: repo.changedFiles
   });
 
-  const mentionedPaths = matchMentionedPaths(signals.fileMentions, repo.files.map((file) => file.path));
-  const taskTargetsEvaluation = hasAny(taskTokens, ["benchmark", "benchmarks", "evaluation", "evaluate"]);
+  const mentionedPaths = matchMentionedPaths(signals.fileMentions, repo.files.map((file) => file.path), repo.root);
   // Excluded before anything else reads the candidate set. The boilerplate threshold below
   // is a share of that set, so removing files later would leave scoring computed against a
   // population that no longer exists.
@@ -110,8 +132,7 @@ export function rankContextFiles(
     (mentionedPaths.has(file.path) ||
     (file.isSource &&
       !file.isTest &&
-      !LOCKFILES.has(file.path.split("/").pop() ?? "") &&
-      (!file.path.startsWith("benchmarks/") || taskTargetsEvaluation)))
+      !LOCKFILE_NAMES.has(file.path.split("/").pop() ?? "")))
   );
   // Generated output is kept only when the source it came from is absent. chalk's sole
   // color-detection implementation lives in `source/vendor/`, so it stays; a committed
@@ -122,7 +143,7 @@ export function rankContextFiles(
       .filter((file) => !isGeneratedPath(file.path) && !isBackupPath(file.path))
       .map((file) => moduleStem(file.path))
   );
-  const candidates = scannable.filter((file) =>
+  const candidateFiles = scannable.filter((file) =>
     !isRecordedEvaluationOutput(file.path) && (
       mentionedPaths.has(file.path) ||
       signals.changedFiles.has(file.path) ||
@@ -130,25 +151,34 @@ export function rankContextFiles(
       !maintainedStems.has(moduleStem(file.path))
     )
   );
-  const contentTokensByPath = new Map(candidates.map((file) => [file.path, tokenizeFileContent(file.textSample)]));
+  const regexTokensByPath = new Map(candidateFiles.map((file) => [file.path, extractRegexTokens(file.textSample)]));
+  const contentTokensByPath = new Map(candidateFiles.map((file) => [
+    file.path,
+    tokenizeFileContent(file.textSample, regexTokensByPath.get(file.path) ?? new Set<string>())
+  ]));
   const commonTokens = findCommonTokens(contentTokensByPath);
   const allTaskTermsAreWidespread = taskTokens.size > 0 &&
     [...taskTokens].every((token) => commonTokens.has(token));
   const definitionSignals = buildDefinitionSignals(signals.identifiers);
+  const memberSignals = [...signals.memberMentions].map((member) => ({
+    member,
+    pattern: exactIdentifierPattern(member)
+  }));
   const taskText = [input.issueText ?? "", input.diffText ?? ""].join("\n");
+  const exactFragmentOccurrences = new Map(
+    signals.exactFragments.map((fragment) => [fragment, countOccurrences(taskText, fragment)])
+  );
   const taskTargetsDocumentation = targetsDocumentation(taskText);
-  const taskTargetsConfiguration = hasAny(taskTokens, ["config", "configuration", "workflow", "action", "ci", "yaml"]);
-  const taskTargetsDeployment = hasAny(taskTokens, DEPLOYMENT_TERMS);
+  const taskTargetsConfiguration = hasAnyNormalized(taskTokens, taskText, CONFIGURATION_TERMS);
+  const taskTargetsDeployment = hasAnyNormalized(taskTokens, taskText, DEPLOYMENT_TERMS);
   const taskTargetsExamples = /\b(?:demos?|examples?|samples?)\b/i.test(
     taskText.replace(/\bfor example\b/gi, "")
   );
-  const taskTargetsPresentation = hasAny(taskTokens, [
-    "browser", "button", "client", "display", "form", "frontend", "layout", "page", "screen", "ui", "visitor", "web", "website"
-  ]);
+  const taskTargetsPresentation = hasAnyNormalized(taskTokens, taskText, PRESENTATION_TERMS);
   const taskTargetsTypeDeclarations =
     /\b(?:typescript|types?|type definitions?|declarations?|typings?|\.d\.(?:ts|mts|cts))\b/i.test(taskText);
 
-  const scored: ScoredFile[] = candidates
+  const scored: ScoredFile[] = candidateFiles
     .map((file) => {
       const reasons: string[] = [];
       let score = 0;
@@ -175,6 +205,16 @@ export function rankContextFiles(
       if (pathOverlap.length > 0) {
         score += pathOverlap.length * 3;
         reasons.push(`path matches task terms: ${pathOverlap.join(", ")}`);
+        if (pathOverlap.length >= 2) {
+          score += 4;
+          reasons.push("multiple task terms converge in the file path");
+          const fileName = file.path.split("/").at(-1)?.replace(/\.[^.]+$/, "") ?? "";
+          const fileNameTokens = tokenizeText(fileName);
+          if (fileNameTokens.size === 1 && [...fileNameTokens].some((token) => taskTokens.has(token))) {
+            score += 5;
+            reasons.push("file module name exactly matches a task term");
+          }
+        }
       }
 
       const contentTokens = contentTokensByPath.get(file.path) ?? new Set<string>();
@@ -186,14 +226,17 @@ export function rankContextFiles(
         reasons.push(`content matches task terms: ${contentOverlap.slice(0, 8).join(", ")}`);
       }
 
-      const regexTokenOverlap = findRegexTokenOverlap(file.textSample, taskTokens);
+      const regexTokenOverlap = [...(regexTokensByPath.get(file.path) ?? [])]
+        .filter((token) => taskTokens.has(token))
+        .slice(0, 2);
       if (regexTokenOverlap.length > 0) {
         score += Math.min(regexTokenOverlap.length, 2) * 12;
         reasons.push(`regex literal matches task tokens: ${regexTokenOverlap.join(", ")}`);
       }
 
-      const matchedMembers = [...signals.memberMentions]
-        .filter((member) => hasExactIdentifier(file.textSample, member))
+      const matchedMembers = memberSignals
+        .filter((signal) => signal.pattern.test(file.textSample))
+        .map((signal) => signal.member)
         .slice(0, 3);
       if (matchedMembers.length > 0) {
         score += matchedMembers.length * MEMBER_MENTION_BOOST;
@@ -203,11 +246,11 @@ export function rankContextFiles(
       const exactLiteral = signals.exactFragments
         .filter((fragment) => file.textSample.includes(fragment))
         .sort((a, b) =>
-          countOccurrences(taskText, b) - countOccurrences(taskText, a) ||
+          (exactFragmentOccurrences.get(b) ?? 0) - (exactFragmentOccurrences.get(a) ?? 0) ||
           b.length - a.length
         )[0];
       if (exactLiteral) {
-        score += EXACT_LITERAL_BOOST * Math.min(3, countOccurrences(taskText, exactLiteral));
+        score += EXACT_LITERAL_BOOST * Math.min(3, exactFragmentOccurrences.get(exactLiteral) ?? 0);
         reasons.push(`contains exact task literal: ${previewFragment(exactLiteral)}`);
       }
 
@@ -216,11 +259,20 @@ export function rankContextFiles(
       if (definedIdentifiers.length > 0) {
         score += definedIdentifiers.length * DEFINITION_IDENTIFIER_BOOST;
         reasons.push(`defines task identifiers: ${definedIdentifiers.join(", ")}`);
+        if (
+          file.kind === "code" &&
+          !file.isTest &&
+          !isAuxiliaryCodePath(file.path) &&
+          !isTypeDeclarationPath(file.path) &&
+          !file.path.toLowerCase().startsWith("benchmarks/")
+        ) {
+          score += 4;
+          reasons.push("task identifier is defined in maintained implementation source");
+        }
       }
 
       const taskMatchedDefinitions = signals.exactFragments.length === 0 &&
-        !taskTargetsDocumentation &&
-        !taskTargetsPresentation
+        !taskTargetsDocumentation
         ? (file.kind === "documentation" ? [] : findTaskMatchedDefinitions(file.textSample, taskTokens))
           .filter((identifier) => !definedIdentifiers.includes(identifier))
           .slice(0, MAX_DEFINITION_IDENTIFIERS)
@@ -259,7 +311,9 @@ export function rankContextFiles(
       }
 
       const isDeploymentConfig =
-        file.path === "package.json" || DEPLOYMENT_TERMS.some((term) => pathTokens.has(term));
+        file.path === "package.json" || DEPLOYMENT_TERMS.some((term) =>
+          [...tokenizeText(term)].some((token) => pathTokens.has(token))
+        );
       if (taskTargetsDeployment && file.kind === "config" && !file.path.includes("/") && isDeploymentConfig) {
         score += 5;
         reasons.push("root configuration for a deployment-related task");
@@ -275,17 +329,24 @@ export function rankContextFiles(
       ) {
         score -= EXAMPLE_CODE_PENALTY;
         reasons.push("example or demo code deprioritized for an implementation task");
+        if (exactLiteral && definedIdentifiers.length > 0) {
+          score -= AUXILIARY_REPRODUCTION_PENALTY;
+          reasons.push("task reproduction evidence is weaker in auxiliary example code");
+        }
       }
 
-      if (
-        isPresentationSurfacePath(file.path) &&
-        !taskTargetsPresentation &&
-        !taskTargetsExamples &&
-        !isChanged &&
-        !mentionedPaths.has(file.path)
-      ) {
-        score -= PRESENTATION_CODE_PENALTY;
-        reasons.push("presentation or demo surface deprioritized for a non-UI implementation task");
+      if (isPresentationSurfacePath(file.path)) {
+        if (taskTargetsPresentation) {
+          score += PRESENTATION_CODE_PENALTY;
+          reasons.push("presentation surface matches a UI-focused task");
+          if (isInteractivePresentation(file.textSample)) {
+            score += INTERACTIVE_PRESENTATION_BOOST;
+            reasons.push("interactive presentation surface matches the requested user flow");
+          }
+        } else if (!taskTargetsExamples && !isChanged && !mentionedPaths.has(file.path)) {
+          score -= PRESENTATION_CODE_PENALTY;
+          reasons.push("presentation or demo surface deprioritized for a non-UI implementation task");
+        }
       }
 
       if (
@@ -296,6 +357,10 @@ export function rankContextFiles(
       ) {
         score -= TYPE_DECLARATION_PENALTY;
         reasons.push("type declaration deprioritized for a runtime task");
+        if (definedIdentifiers.length > 0) {
+          score -= TYPE_DECLARATION_DIRECT_PENALTY;
+          reasons.push("runtime implementation preferred over a matching declaration");
+        }
       } else if (
         isTypeDeclarationPath(file.path) &&
         taskTargetsTypeDeclarations &&
@@ -327,25 +392,28 @@ export function rankContextFiles(
 
   applyImportProximity(scored, repo);
 
-  const ranked = scored
+  const candidates = scored
     .filter((file) => file.score >= minScore)
-    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
-    .slice(0, limit);
-  const clustered = isClusteredRanking(ranked);
-  const leadIsContested = hasContestedLead(ranked);
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+  const ranking = buildRankingShape(candidates);
+  const clustered = ranking.clustered;
+  const leadIsContested = hasContestedLead(candidates);
+  const ranked = candidates.slice(0, limit);
 
-  return ranked
+  const contextFiles = ranked
     .map((entry, position) => ({
       rank: position + 1,
       path: entry.path,
       score: entry.score,
       confidence: confidenceForEntry(entry, grounding, clustered, {
         position,
-        topScore: ranked[0]?.score ?? entry.score,
-        leadIsContested
+        topScore: candidates[0]?.score ?? entry.score,
+        leadIsContested,
+        issueIsVague: isVagueTaskText(input.issueText ?? "")
       }),
       reasons: entry.reasons.length > 0 ? entry.reasons : ["source file baseline"]
     }));
+  return { contextFiles, ranking };
 }
 
 /**
@@ -378,17 +446,33 @@ function hasDefinitionEvidence(entry: ScoredFile): boolean {
 }
 
 function applyImportProximity(scored: ScoredFile[], repo: RepoMap): void {
-  const seedEntries = scored
+  const directSeeds = scored
     .filter((entry) => entry.score >= 8 && hasDirectEvidence(entry))
     .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
     .slice(0, MAX_PROXIMITY_SEEDS);
+  const seedEntries = directSeeds.length > 0
+    ? directSeeds
+    : scored
+      .filter((entry) => entry.score >= 8)
+      .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+      .slice(0, 2);
   if (seedEntries.length === 0) {
     return;
   }
 
   const seeds = seedEntries.map((entry) => entry.path);
   const seedScores = new Map(seedEntries.map((entry) => [entry.path, entry.score]));
-  const proximity = findImportProximity(buildImportGraph(repo.files), seeds);
+  const graph = buildImportGraph(repo.files);
+  if ((graph.truncatedFiles > 0 || graph.truncatedEdges > 0) && !repo.diagnostics.some((entry) => entry.code === "import-graph-truncated")) {
+    repo.diagnostics.push({
+      code: "import-graph-truncated",
+      severity: "info",
+      message:
+        `Import proximity was bounded: ${graph.truncatedFiles.toLocaleString()} parseable files and ` +
+        `${graph.truncatedEdges.toLocaleString()} high-fanout files were not fully traversed. Ranking still uses path and content evidence.`
+    });
+  }
+  const proximity = findImportProximity(graph, seeds);
   for (const entry of scored) {
     const hit = proximity.get(entry.path);
     if (hit) {
@@ -415,11 +499,8 @@ function confidenceForEntry(
   entry: ScoredFile,
   grounding: TaskGrounding,
   clustered: boolean,
-  shape: { position: number; topScore: number; leadIsContested: boolean }
+  shape: { position: number; topScore: number; leadIsContested: boolean; issueIsVague: boolean }
 ): RankedFile["confidence"] {
-  if (entry.isChanged) {
-    return "high";
-  }
   const hasMaintainedSourceTwin = entry.reasons.includes(GENERATED_TWIN_REASON);
   if (
     entry.reasons.includes("explicitly named in the task") &&
@@ -449,6 +530,14 @@ function confidenceForEntry(
   if (hasMaintainedSourceTwin) {
     confidence = capConfidence(confidence, "medium");
   }
+  // A large lexical score and a wide lead can still be a convincing match to an absent
+  // feature (for example, a generic `hasFlag` helper in a repository with no CLI). Reserve
+  // high confidence for a changed file, an explicit path, or an exact identifier/literal
+  // definition. Vocabulary-only leaders remain useful, but are honest medium-confidence
+  // investigation targets.
+  if (!hasDirectEvidence(entry)) {
+    confidence = capConfidence(confidence, "medium");
+  }
   const supportedIdentifierCount = grounding.identifiers.filter((identifier) =>
     identifier.status === "exact-definition" ||
     identifier.status === "exact-text" ||
@@ -470,7 +559,7 @@ function confidenceForEntry(
   if (grounding.partiallyResolvedIdentifiers.length > 0) {
     confidence = capConfidence(confidence, "medium");
   }
-  if (grounding.specificity === "vague") {
+  if (grounding.specificity === "vague" || shape.issueIsVague) {
     return "low";
   }
   if (!grounding.scanComplete) {
@@ -498,20 +587,20 @@ function hasDirectEvidence(entry: ScoredFile): boolean {
   );
 }
 
-function isClusteredRanking(entries: ScoredFile[]): boolean {
-  const top = entries[0]?.score;
-  const third = entries[2]?.score;
-  return top !== undefined && third !== undefined && top - third <= 2;
-}
-
-function hasAny(tokens: Set<string>, values: string[]): boolean {
-  return values.some((value) => tokens.has(value));
+function hasAnyNormalized(tokens: Set<string>, rawText: string, values: string[]): boolean {
+  return values.some((value) => {
+    const normalized = tokenizeText(value);
+    if (normalized.size > 0 && [...normalized].every((token) => tokens.has(token))) return true;
+    return new RegExp(`(^|[^\\p{L}\\p{N}_])${escapeRegExp(value)}(?=$|[^\\p{L}\\p{N}_])`, "iu").test(rawText);
+  });
 }
 
-function matchMentionedPaths(mentions: Set<string>, repoPaths: string[]): Set<string> {
+function matchMentionedPaths(mentions: Set<string>, repoPaths: string[], repoRoot: string): Set<string> {
   const matched = new Set<string>();
 
-  for (const mention of mentions) {
+  for (const rawMention of mentions) {
+    const mention = repositoryRelativeMention(rawMention, repoRoot);
+    if (!mention) continue;
     const exactMatches = repoPaths.filter((path) => pathMatchesMention(path, mention));
     if (exactMatches.length > 0) {
       if (exactMatches.length <= MAX_FILES_PER_MENTION) {
@@ -536,19 +625,15 @@ function matchMentionedPaths(mentions: Set<string>, repoPaths: string[]): Set<st
   return matched;
 }
 
-function pathMatchesMention(path: string, mention: string): boolean {
-  const normalizedPath = path.toLowerCase();
-  const normalizedMention = mention.toLowerCase();
-  if (normalizedPath === normalizedMention ||
-    normalizedPath.endsWith(`/${normalizedMention}`) ||
-    normalizedMention.endsWith(`/${normalizedPath}`)) {
-    return true;
-  }
-  if (!normalizedMention.includes("/") && !normalizedMention.includes(".")) {
-    const fileName = normalizedPath.split("/").at(-1) ?? "";
-    return fileName.replace(/\.[^.]+$/, "") === normalizedMention;
-  }
-  return false;
+function repositoryRelativeMention(mention: string, repoRoot: string): string | undefined {
+  const normalizedMention = mention.replace(/\\/g, "/");
+  if (!/^(?:[A-Za-z]:\/|\/)/.test(normalizedMention)) return normalizedMention;
+
+  const normalizedRoot = repoRoot.replace(/\\/g, "/").replace(/\/$/, "");
+  const prefix = `${normalizedRoot}/`;
+  return normalizedMention.toLowerCase().startsWith(prefix.toLowerCase())
+    ? normalizedMention.slice(prefix.length)
+    : undefined;
 }
 
 function compiledSourcePathVariants(path: string): string[] {
@@ -568,34 +653,29 @@ function compiledSourcePathVariants(path: string): string[] {
 function isAuxiliaryCodePath(path: string): boolean {
   const parts = path.split("/");
   const stem = (parts.at(-1) ?? "").replace(/\.[^.]+$/, "").toLowerCase();
-  return parts.slice(0, -1).some((segment) => AUXILIARY_CODE_DIRS.has(segment.toLowerCase())) ||
-    /^(?:demo|example|sample)(?:[-_.]|$)/.test(stem);
+  const parentSegments = parts.slice(0, -1).map((segment) => segment.toLowerCase());
+  return parentSegments.some((segment) => AUXILIARY_CODE_DIRS.has(segment)) ||
+    (stem === "sample-repo" && parentSegments.some((segment) => segment === "web" || segment === "website"));
 }
 
 function isPresentationSurfacePath(path: string): boolean {
   const name = path.split("/").at(-1)?.toLowerCase() ?? "";
-  return /^(?:page|layout|demo|sample-repo)\.[cm]?[jt]sx?$/.test(name) ||
+  return /^(?:page|layout|demo)\.[cm]?[jt]sx?$/.test(name) ||
     /\.(?:css|less|sass|scss)$/.test(name);
 }
 
-function tokenizeFileContent(text: string): Set<string> {
+function isInteractivePresentation(text: string): boolean {
+  return /<(?:button|form|input|select|textarea)\b|\bon(?:Change|Click|Input|Submit)\s*=|\buseState\s*\(/.test(text);
+}
+
+function tokenizeFileContent(text: string, regexTokens: Set<string>): Set<string> {
   const tokens = tokenizeText(text);
-  for (const match of text.matchAll(/\b([A-Za-z])\{(\d+),(\d+)\}/g)) {
-    const character = match[1]?.toLowerCase();
-    const minimum = Number(match[2]);
-    const maximum = Math.min(Number(match[3]), 8);
-    if (!character || !Number.isSafeInteger(minimum) || !Number.isSafeInteger(maximum)) {
-      continue;
-    }
-    for (let length = Math.max(3, minimum); length <= maximum; length += 1) {
-      tokens.add(character.repeat(length));
-    }
-  }
+  for (const token of regexTokens) tokens.add(token);
   return tokens;
 }
 
-function findRegexTokenOverlap(text: string, taskTokens: Set<string>): string[] {
-  const overlap = new Set<string>();
+function extractRegexTokens(text: string): Set<string> {
+  const tokens = new Set<string>();
   for (const match of text.matchAll(/\b([A-Za-z])\{(\d+),(\d+)\}/g)) {
     const character = match[1]?.toLowerCase();
     const minimum = Number(match[2]);
@@ -604,13 +684,10 @@ function findRegexTokenOverlap(text: string, taskTokens: Set<string>): string[]
       continue;
     }
     for (let length = Math.max(3, minimum); length <= maximum; length += 1) {
-      const token = character.repeat(length);
-      if (taskTokens.has(token)) {
-        overlap.add(token);
-      }
+      tokens.add(character.repeat(length));
     }
   }
-  return [...overlap].slice(0, 2);
+  return tokens;
 }
 
 function isBundledOutput(textSample: string, path: string): boolean {
@@ -641,14 +718,15 @@ function isTypeDeclarationPath(path: string): boolean {
 }
 
 function targetsDocumentation(taskText: string): boolean {
-  const documentation = "(?:docs?|documentation|readme|guide|copy)";
+  const documentation = "(?:docs?|documentation|readme|guide)";
   const action = "(?:add|change|correct|document|edit|fix|improve|remove|revise|rewrite|update|write)";
   const defect = "(?:typos?|spelling|grammar|wording|broken links?)";
   return (
     new RegExp(`\\b${action}\\b[^\\n.]{0,60}\\b${documentation}\\b`, "i").test(taskText) ||
     new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${action}\\b`, "i").test(taskText) ||
     new RegExp(`\\b${defect}\\b[^\\n.]{0,60}\\b${documentation}\\b`, "i").test(taskText) ||
-    new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${defect}\\b`, "i").test(taskText)
+    new RegExp(`\\b${documentation}\\b[^\\n.]{0,60}\\b${defect}\\b`, "i").test(taskText) ||
+    /\b(?:marketing|landing|website|page|button|label|headline|cta)\s+copy\b/i.test(taskText)
   );
 }
 
@@ -658,7 +736,8 @@ function buildDefinitionSignals(identifiers: Set<string>): DefinitionSignal[] {
     .map((identifier) => ({
       identifier,
       pattern: new RegExp(
-        `\\b(?:export\\s+)?(?:async\\s+)?(?:const|let|var|function|class|interface|type|enum|def|fn|struct|trait)\\s+${escapeRegExp(identifier)}\\b`
+        `(?<![\\p{L}\\p{N}_$])(?:export\\s+)?(?:async\\s+)?(?:function\\s*\\*?\\s*|(?:const|let|var|class|interface|type|enum|def|fn|func|fun|struct|trait)\\s+)${escapeRegExp(identifier)}(?![\\p{L}\\p{N}_$])`,
+        "u"
       )
     }));
 }
@@ -667,16 +746,17 @@ function findDefinedIdentifiers(text: string, signals: DefinitionSignal[]): stri
   return signals.filter((signal) => signal.pattern.test(text)).map((signal) => signal.identifier);
 }
 
-function hasExactIdentifier(text: string, identifier: string): boolean {
+function exactIdentifierPattern(identifier: string): RegExp {
   return new RegExp(
-    `(^|[^$A-Za-z0-9_])${escapeRegExp(identifier)}(?=$|[^$A-Za-z0-9_])`
-  ).test(text);
+    `(?<![\\p{L}\\p{N}_$])${escapeRegExp(identifier)}(?![\\p{L}\\p{N}_$])`,
+    "u"
+  );
 }
 
 function findTaskMatchedDefinitions(text: string, taskTokens: Set<string>): string[] {
   const definitions = new Set<string>();
   const pattern =
-    /\b(?:export\s+)?(?:async\s+)?(?:const|let|var|function|class|interface|type|enum|def|fn|struct|trait)\s+([$A-Za-z_][$A-Za-z0-9_]*)\b/g;
+    /(?<![\p{L}\p{N}_$])(?:export\s+)?(?:async\s+)?(?:function\s*\*?\s*|(?:const|let|var|class|interface|type|enum|def|fn|func|fun|struct|trait)\s+)([\p{L}_$][\p{L}\p{N}_$]*)(?![\p{L}\p{N}_$])/gu;
 
   for (const match of text.matchAll(pattern)) {
     const identifier = match[1];
@@ -684,7 +764,7 @@ function findTaskMatchedDefinitions(text: string, taskTokens: Set<string>): stri
       continue;
     }
     const overlap = [...tokenizeText(identifier)].filter((token) => taskTokens.has(token));
-    if (overlap.length >= 2) {
+    if (overlap.length >= 2 || (overlap.length === 1 && identifier.length >= 6)) {
       definitions.add(identifier);
     }
   }
diff --git a/packages/core/src/repo-scan.ts b/packages/core/src/repo-scan.ts
index 83fc89e..d3fa60b 100644
--- a/packages/core/src/repo-scan.ts
+++ b/packages/core/src/repo-scan.ts
@@ -4,41 +4,24 @@ import { mkdir, readdir, readFile, realpath, rename, stat, unlink, writeFile } f
 import { homedir } from "node:os";
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
-import { ALWAYS_IGNORED_DIRS, GENERATED_DIRS, isGeneratedPath } from "./paths.js";
+import { ALWAYS_IGNORED_DIRS, GENERATED_DIRS, SOURCE_FILE_EXTENSIONS, isGeneratedPath } from "./paths.js";
 import { DIAGNOSTIC_SPEC_LIMIT, truncateForDiagnostic } from "./text.js";
 import type { FixMapInput, PackageScript, RepoFile, RepoMap } from "./types.js";
 
-const WALK_IGNORED_DIRS = new Set([...ALWAYS_IGNORED_DIRS, ...GENERATED_DIRS]);
-const SOURCE_EXTENSIONS = new Set([
-  ".cjs",
-  ".cs",
-  ".css",
-  ".cts",
-  ".go",
-  ".java",
-  ".js",
-  ".json",
-  ".jsx",
-  ".md",
-  ".mjs",
-  ".mts",
-  ".php",
-  ".py",
-  ".rb",
-  ".rs",
-  ".svelte",
-  ".ts",
-  ".tsx",
-  ".vue",
-  ".yaml",
-  ".yml"
+// Vendored source is intentionally scannable and receives a ranking penalty. Git mode has
+// always kept tracked vendor/ files; walk mode must not silently use a smaller corpus.
+const WALK_IGNORED_DIRS = new Set([
+  ...ALWAYS_IGNORED_DIRS,
+  ...[...GENERATED_DIRS].filter((directory) => directory !== "vendor")
 ]);
+const SOURCE_EXTENSIONS = SOURCE_FILE_EXTENSIONS;
 const CONVENTIONAL_DOCUMENT_NAMES = new Set([
   "authors", "changelog", "code_of_conduct", "contributing", "license", "notice", "readme", "security"
 ]);
 const CONVENTIONAL_CONFIG_NAMES = new Set([
   ".dockerignore", ".editorconfig", ".gitattributes", ".gitignore", ".npmignore",
-  "codeowners", "dockerfile", "gemfile", "jenkinsfile", "makefile", "procfile", "rakefile", "vagrantfile"
+  "codeowners", "dockerfile", "gemfile", "jenkinsfile", "makefile", "procfile", "rakefile", "vagrantfile",
+  "pom.xml", "build.gradle", "settings.gradle"
 ]);
 
 /**
@@ -53,6 +36,9 @@ const TEST_PATTERNS = [
   /\.spec\./,
   /(^|\/|\\)__tests__(\/|\\)/,
   /(^|\/|\\)tests?(\/|\\)/,
+  /(^|\/|\\)spec(\/|\\)/,
+  /_spec\.rb$/i,
+  /(?:Test\.java|Tests?\.cs|Test\.php)$/i,
   /_test\.go$/,
   /(^|\/|\\)(?:test_[^/\\]+|[^/\\]+_test)\.py$/
 ];
@@ -62,7 +48,7 @@ const MAX_SCANNED_FILES = 25_000;
 const GIT_MAX_BUFFER = 10 * 1024 * 1024;
 const exec = promisify(execFile);
 type ScanState = { count: number; limitReported: boolean };
-const SCAN_CACHE_VERSION = 2;
+const SCAN_CACHE_VERSION = 3;
 const SCAN_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 const SCAN_CACHE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1000;
 const SCAN_CACHE_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json$/;
@@ -144,7 +130,7 @@ export async function scanRepo(
     files = await listFiles(repoRoot, diagnostics, internalCacheRoot, internalPaths);
     trackedFiles = await listTrackedPaths(repoRoot, internalPaths);
     packageScripts = await readPackageScripts(repoRoot, files, diagnostics);
-    packageManager = detectPackageManager(files);
+    packageManager = detectPackageManager(files, diagnostics);
     if (cacheLocation) {
       await writeScanCache(cacheLocation, {
         version: SCAN_CACHE_VERSION,
@@ -607,7 +593,7 @@ function reportUnreadContent(diagnostics: RepoMap["diagnostics"], files: RepoFil
     const sample = affected.slice(0, 3).map((file) => file.path).join(", ");
     const prefix = `${affected.length.toLocaleString()} source file${affected.length === 1 ? "" : "s"}`;
     diagnostics.push({
-      code: "content-unread",
+      code: reason === "not-text" ? "content-not-utf8" : "content-unreadable",
       severity: "warning",
       message: reason === "not-text"
         ? `${prefix} ${affected.length === 1 ? "is" : "are"} not UTF-8 text (for example UTF-16 or binary) and ` +
@@ -632,7 +618,7 @@ function reportUnreadContent(diagnostics: RepoMap["diagnostics"], files: RepoFil
     .join(", ");
 
   diagnostics.push({
-    code: "content-unread",
+    code: "content-too-large",
     severity: "warning",
     message:
       `${unread.length.toLocaleString()} source file${unread.length === 1 ? "" : "s"} could not be read as text and ` +
@@ -769,7 +755,7 @@ async function toRepoFile(absolutePath: string, relativePath: string): Promise<S
     return { status: "not-a-file" };
   }
 
-  const extension = extname(relativePath);
+  const extension = extname(relativePath).toLowerCase();
   const conventionalKind = classifyConventionalTextFile(relativePath);
   const isSource = SOURCE_EXTENSIONS.has(extension) || conventionalKind !== undefined;
   const sample = isSource
@@ -960,10 +946,7 @@ async function readDiff(
         : `Diff "${truncateForDiagnostic(diffSpec, DIAGNOSTIC_SPEC_LIMIT)}" resolved ${changedFiles.length} changed ${changedFiles.length === 1 ? "path" : "paths"}.`,
       paths: changedFiles.slice(0, 8)
     });
-    return {
-      changedFiles,
-      diffText: diffText.slice(0, MAX_DIFF_TEXT_CHARS)
-    };
+    return { changedFiles, diffText: sampleDiffText(diffText, diagnostics) };
   } catch (error) {
     const checkoutState = isMissingGit(error) ? undefined : await describeGitCheckout(repoRoot);
     const detail = truncateForDiagnostic(gitErrorDetail(error), DIAGNOSTIC_SPEC_LIMIT * 2);
@@ -981,6 +964,70 @@ async function readDiff(
   }
 }
 
+/**
+ * Large diffs used to be cut at an arbitrary UTF-16 offset. That could split a line and,
+ * because git orders files, erase every content signal from files later in the diff. For an
+ * oversized diff the ranker only needs added lines, so sample complete added lines from every
+ * file in round-robin order and say exactly what was omitted.
+ */
+function sampleDiffText(diffText: string, diagnostics: RepoMap["diagnostics"]): string {
+  if (diffText.length <= MAX_DIFF_TEXT_CHARS) return diffText;
+
+  const groups: string[][] = [];
+  let current: string[] | undefined;
+  for (const line of diffText.split(/\r?\n/)) {
+    if (line.startsWith("diff --git ")) {
+      current = [];
+      groups.push(current);
+      continue;
+    }
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      if (!current) {
+        current = [];
+        groups.push(current);
+      }
+      current.push(line);
+    }
+  }
+
+  const queues = groups.filter((group) => group.length > 0);
+  const selected: string[] = [];
+  let selectedChars = 0;
+  let selectedLines = 0;
+  const totalLines = queues.reduce((total, group) => total + group.length, 0);
+  let cursor = 0;
+  let madeProgress = true;
+
+  while (madeProgress && selectedChars < MAX_DIFF_TEXT_CHARS) {
+    madeProgress = false;
+    for (const group of queues) {
+      const line = group[cursor];
+      if (line === undefined) continue;
+      madeProgress = true;
+      const separator = selected.length === 0 ? 0 : 1;
+      if (selectedChars + separator + line.length <= MAX_DIFF_TEXT_CHARS) {
+        selected.push(line);
+        selectedChars += separator + line.length;
+        selectedLines += 1;
+      }
+    }
+    cursor += 1;
+  }
+
+  diagnostics.push({
+    code: "diff-text-truncated",
+    severity: "warning",
+    message:
+      `The git diff was ${diffText.length.toLocaleString()} characters, above FixMap's ` +
+      `${MAX_DIFF_TEXT_CHARS.toLocaleString()}-character signal budget. FixMap sampled ` +
+      `${selectedLines.toLocaleString()} of ${totalLines.toLocaleString()} complete added lines ` +
+      `across ${queues.length.toLocaleString()} changed ${queues.length === 1 ? "file" : "files"}; ` +
+      "changed-file paths remain complete, but omitted diff content could reduce ranking precision."
+  });
+
+  return selected.join("\n");
+}
+
 /**
  * "Map what I am touching right now."
  *
@@ -1020,7 +1067,7 @@ async function readWorkingTree(
       paths: changedFiles.slice(0, 8)
     });
 
-    return { changedFiles, diffText: diffText.slice(0, MAX_DIFF_TEXT_CHARS) };
+    return { changedFiles, diffText: sampleDiffText(diffText, diagnostics) };
   } catch (error) {
     const checkoutState = isMissingGit(error) ? undefined : await describeGitCheckout(repoRoot);
     diagnostics.push({
@@ -1082,14 +1129,41 @@ function isMissingGit(error: unknown): boolean {
   return (error as { code?: unknown })?.code === "ENOENT";
 }
 
-function detectPackageManager(files: RepoFile[]): RepoMap["packageManager"] {
-  const paths = new Set(files.map((file) => file.path));
-  if (paths.has("pnpm-lock.yaml") || paths.has("pnpm-workspace.yaml")) return "pnpm";
-  if (paths.has("yarn.lock") || paths.has(".yarnrc.yml")) return "yarn";
-  if (paths.has("bun.lock") || paths.has("bun.lockb")) return "bun";
+function detectPackageManager(files: RepoFile[], diagnostics: RepoMap["diagnostics"]): RepoMap["packageManager"] {
+  const rootManagers = packageManagersForPaths(files.map((file) => file.path).filter((path) => !path.includes("/")));
+  if (rootManagers.length > 1) {
+    diagnostics.push({
+      code: "package-manager-conflict",
+      severity: "warning",
+      message: `Conflicting root package-manager files were found (${rootManagers.join(", ")}); using ${rootManagers[0]} deterministically. Remove the stale lockfile so routed commands are unambiguous.`
+    });
+  }
+  if (rootManagers[0]) return rootManagers[0];
+
+  // Archives and workspace extracts do not always carry a root lockfile. When every nested
+  // declaration agrees, use that manager rather than printing npm commands that cannot run.
+  const nestedManagers = packageManagersForPaths(files.map((file) => file.path));
+  if (nestedManagers.length === 1) return nestedManagers[0]!;
+  if (nestedManagers.length > 1) {
+    diagnostics.push({
+      code: "package-manager-conflict",
+      severity: "warning",
+      message: `Nested package-manager files disagree (${nestedManagers.join(", ")}); defaulting to npm for root routes. Point --repo at one workspace to get an unambiguous command.`
+    });
+  }
   return "npm";
 }
 
+function packageManagersForPaths(paths: string[]): RepoMap["packageManager"][] {
+  const names = new Set(paths.map((path) => path.split("/").at(-1) ?? path));
+  const managers: RepoMap["packageManager"][] = [];
+  if (names.has("pnpm-lock.yaml") || names.has("pnpm-workspace.yaml")) managers.push("pnpm");
+  if (names.has("yarn.lock") || names.has(".yarnrc.yml")) managers.push("yarn");
+  if (names.has("bun.lock") || names.has("bun.lockb")) managers.push("bun");
+  if (names.has("package-lock.json") || names.has("npm-shrinkwrap.json")) managers.push("npm");
+  return managers;
+}
+
 function classifyFile(path: string, extension: string): RepoFile["kind"] {
   const lower = path.toLowerCase();
   const conventionalKind = classifyConventionalTextFile(path);
@@ -1098,7 +1172,7 @@ function classifyFile(path: string, extension: string): RepoFile["kind"] {
   if (
     lower.startsWith(".github/") ||
     [".json", ".yaml", ".yml"].includes(extension) ||
-    /(^|\/)([^/]+\.)?(config|rc)\.[^/]+$/.test(lower)
+    /(^|\/)(?:[^/]+\.config|\.[^/]*rc)\.[^/]+$/.test(lower)
   ) return "config";
   if (SOURCE_EXTENSIONS.has(extension)) return "code";
   return "other";
@@ -1108,6 +1182,7 @@ function classifyConventionalTextFile(path: string): "documentation" | "config"
   const name = path.replace(/\\/g, "/").split("/").at(-1)?.toLowerCase() ?? "";
   if (CONVENTIONAL_DOCUMENT_NAMES.has(name)) return "documentation";
   if (CONVENTIONAL_CONFIG_NAMES.has(name)) return "config";
+  if (/\.(?:csproj|fsproj|vbproj)$/.test(name)) return "config";
   return undefined;
 }
 
diff --git a/packages/core/src/report.ts b/packages/core/src/report.ts
index 596a4d3..3c4fd8a 100644
--- a/packages/core/src/report.ts
+++ b/packages/core/src/report.ts
@@ -1,14 +1,14 @@
 import {
   analyzeTaskGrounding,
-  buildNextAction,
-  buildRankingShape
+  buildNextAction
 } from "./grounding.js";
 import type { RankingShape, TaskGrounding } from "./grounding.js";
 import type { PathExcluder } from "./exclude.js";
 import { detectPrimaryLanguage, manifestTestCommand, suggestedRunner } from "./languages.js";
-import { DEFAULT_CONTEXT_FILE_LIMIT, rankContextFiles } from "./rank.js";
+import { DEFAULT_CONTEXT_FILE_LIMIT, rankContextFiles, rankContextFilesDetailed } from "./rank.js";
 import { extractTaskSignals, tokenizePath } from "./signals.js";
 import { findGatedTestDiagnostics } from "./test-gates.js";
+import { markdownCode } from "./markdown.js";
 import { DIAGNOSTIC_TERM_LIMIT, truncateForDiagnostic } from "./text.js";
 import type { FixMapReport, PackageScript, RankedFile, RepoFile, RepoMap, RiskNote, ScanDiagnostic, TestRoute } from "./types.js";
 
@@ -30,18 +30,17 @@ export function buildReportFromRepo(
     issueText: input.issueText,
     diffText: repo.diffText
   });
-  const contextFiles = grounding.specificity === "vague"
-    ? []
-    : rankContextFiles(
-      repo,
-      {
-        issueText: input.issueText,
-        diffText: repo.diffText,
-        exclude: input.exclude
-      },
-      input.limit ?? DEFAULT_CONTEXT_FILE_LIMIT
-    );
-  const ranking = buildRankingShape(contextFiles);
+  const ranked = rankContextFilesDetailed(
+    repo,
+    {
+      issueText: input.issueText,
+      diffText: repo.diffText,
+      exclude: input.exclude
+    },
+    input.limit ?? DEFAULT_CONTEXT_FILE_LIMIT
+  );
+  const contextFiles = ranked.contextFiles;
+  const ranking = ranked.ranking;
   const contextPaths = contextFiles.map((file) => file.path);
   const testRoutes = buildTestRoutes(repo, contextPaths);
   const routedTestPaths = [...new Set(testRoutes.flatMap((route) => route.relatedFiles))];
@@ -59,9 +58,7 @@ export function buildReportFromRepo(
       ...findMissingTestRouteDiagnostics(repo, contextFiles, testRoutes),
       ...findTaskDiagnostics(repo, grounding, ranking),
       ...findTaskPreprocessingDiagnostics(input.issueText ?? ""),
-      ...(grounding.specificity === "vague"
-        ? []
-        : findEmptyResultDiagnostics(repo, contextFiles, input.issueText ?? "", input.exclude))
+      ...findEmptyResultDiagnostics(repo, contextFiles, input.issueText ?? "", input.exclude)
     ],
     analysis: {
       grounding,
@@ -311,10 +308,7 @@ function configuredJsRunner(files: RepoFile[]): string | undefined {
   return undefined;
 }
 
-type ScriptKind = { category: "test" | "validation"; exact: boolean };
-
-const SCRIPT_PRIORITY: Record<ScriptKind["category"], number> = { test: 0, validation: 10 };
-const VALIDATION_SCRIPTS = new Set(["typecheck", "check", "lint"]);
+type ScriptKind = { category: "test"; exact: boolean };
 
 /**
  * `test:unit` and `test:ci` are test scripts by every convention that matters, and matching
@@ -326,7 +320,6 @@ function classifyScript(name: string): ScriptKind | undefined {
   const lower = name.toLowerCase();
   if (lower === "test" || lower === "tests") return { category: "test", exact: true };
   if (/^tests?:[a-z0-9:_-]+$/.test(lower)) return { category: "test", exact: false };
-  if (VALIDATION_SCRIPTS.has(lower)) return { category: "validation", exact: true };
   return undefined;
 }
 
@@ -344,35 +337,22 @@ export function buildTestRoutes(repo: RepoMap, contextPaths: string[]): TestRout
       script,
       kind,
       proximity: packageProximity(script.packageDir, codeContextPaths),
-      priority: SCRIPT_PRIORITY[kind.category] + (kind.exact ? 0 : 1)
+      priority: kind.exact ? 0 : 1
     }))
     .filter((candidate) => candidate.proximity >= 0)
     .sort((a, b) => b.proximity - a.proximity || a.priority - b.priority || a.script.packageDir.localeCompare(b.script.packageDir));
 
-  // A `lint` command under a heading that says "Test Routes" invites an agent to run it as
-  // the validation step for a logic bug. With a cap of three, a monorepo could also fill the
-  // list with checks and leave no room for the command that actually runs the tests. Tests
-  // are therefore taken first, and validation only fills what is left over.
-  const ordered = [
-    ...candidates.filter((candidate) => candidate.kind.category === "test"),
-    ...candidates.filter((candidate) => candidate.kind.category !== "test")
-  ];
-
   const commands = new Set<string>();
   const routes: TestRoute[] = [];
-  for (const { script, kind } of ordered) {
+  for (const { script } of candidates) {
     const command = formatScriptCommand(repo.packageManager, script.packageDir, script.name, script.packageName);
     if (commands.has(command)) continue;
     commands.add(command);
-    const isTest = kind.category === "test";
     routes.push({
       command,
-      kind: isTest ? "test" : "validation",
+      kind: "test",
       reason: `${script.packageDir ? `nearest package (${script.packageDir})` : "repository root"} script named ${script.name}`,
-      // A lint route's related paths are the implementation it would check, never tests, so
-      // labeling them the same way let `no-test-changed` cite an implementation file as the
-      // test the plan had routed.
-      relatedFiles: scopeToPackage(isTest ? relatedTests : codeContextPaths, script.packageDir)
+      relatedFiles: scopeToPackage(relatedTests, script.packageDir)
     });
     if (routes.length === 3) break;
   }
@@ -430,13 +410,13 @@ function nearestManifestDir(repo: RepoMap, contextPaths: string[], manifest: str
     .sort((a, b) => b.split("/").length - a.split("/").length || a.localeCompare(b))[0] ?? "";
 }
 
-const RISK_RULES: { area: string; severity: RiskNote["severity"]; tokens: string[]; reason: string }[] = [
-  { area: "authentication", severity: "high", tokens: ["auth", "login", "password"], reason: "authentication-related files are affected" },
-  { area: "billing", severity: "high", tokens: ["billing", "payment", "invoice"], reason: "billing or payment-related files are affected" },
-  { area: "automation", severity: "medium", tokens: ["config", "workflow", "action"], reason: "configuration or CI automation files may affect developer workflows" },
-  { area: "data", severity: "high", tokens: ["migration", "schema", "database", "sql"], reason: "database or schema-related files may affect stored data" },
-  { area: "public-api", severity: "medium", tokens: ["api", "route", "public"], reason: "public interfaces or request handling may change" },
-  { area: "dependencies", severity: "medium", tokens: ["dependency", "lock", "package"], reason: "dependency changes can affect build and supply-chain behavior" }
+export const RISK_RULES: { area: string; severity: RiskNote["severity"]; terms: string[]; reason: string }[] = [
+  { area: "authentication", severity: "high", terms: ["auth", "login", "password"], reason: "authentication-related files are affected" },
+  { area: "billing", severity: "high", terms: ["billing", "payment", "invoice"], reason: "billing or payment-related files are affected" },
+  { area: "automation", severity: "medium", terms: ["config", "workflow", "action", "ci"], reason: "configuration or CI automation files may affect developer workflows" },
+  { area: "data", severity: "high", terms: ["migration", "schema", "database", "sql"], reason: "database or schema-related files may affect stored data" },
+  { area: "public-api", severity: "medium", terms: ["api", "route", "public"], reason: "public interfaces or request handling may change" },
+  { area: "dependencies", severity: "medium", terms: ["dependency", "lock", "package"], reason: "dependency changes can affect build and supply-chain behavior" }
 ];
 
 // Demo code names sensitive areas without touching them. Express ships examples/auth/,
@@ -464,15 +444,16 @@ function carriesRiskEvidence(path: string): boolean {
 
 export function buildRiskNotes(contextPaths: string[], changedFiles: string[] = []): RiskNote[] {
   const contextTokens = new Set(
-    contextPaths.filter(carriesRiskEvidence).flatMap((path) => [...tokenizePath(path)])
+    contextPaths.filter(carriesRiskEvidence).flatMap((path) => [...riskTokens(path)])
   );
-  const changedTokens = new Set(changedFiles.flatMap((path) => [...tokenizePath(path)]));
+  const changedTokens = new Set(changedFiles.flatMap((path) => [...riskTokens(path)]));
   const diffPresent = changedFiles.length > 0;
   const risks: RiskNote[] = [];
 
   for (const rule of RISK_RULES) {
-    const inChanged = rule.tokens.some((token) => changedTokens.has(token));
-    const inContext = rule.tokens.some((token) => contextTokens.has(token));
+    const terms = rule.terms.flatMap((term) => [...riskTokens(term)]);
+    const inChanged = terms.some((token) => changedTokens.has(token));
+    const inContext = terms.some((token) => contextTokens.has(token));
     if (!inChanged && !inContext) {
       continue;
     }
@@ -499,11 +480,18 @@ export function pathsForRiskArea(area: string, paths: string[]): string[] {
   const rule = RISK_RULES.find((candidate) => candidate.area === area);
   if (!rule) return [];
   return paths.filter((path) => {
-    const tokens = tokenizePath(path);
-    return rule.tokens.some((token) => tokens.has(token));
+    const tokens = riskTokens(path);
+    return rule.terms.flatMap((term) => [...riskTokens(term)]).some((token) => tokens.has(token));
   });
 }
 
+function riskTokens(value: string): Set<string> {
+  return new Set([
+    ...tokenizePath(value),
+    ...value.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+  ]);
+}
+
 function packageProximity(packageDir: string, contextPaths: string[]): number {
   if (!packageDir) return 1;
   const matches = contextPaths.filter((path) => path === packageDir || path.startsWith(`${packageDir}/`));
@@ -566,13 +554,13 @@ export function renderMarkdownReport(report: FixMapReport): string {
     "",
     "## Context Files",
     "",
-    ...listOrEmpty(report.contextFiles.map((file) => `- \`${file.path}\` (${file.confidence} confidence, score ${file.score}): ${file.reasons.join("; ")}`)),
+    ...listOrEmpty(report.contextFiles.map((file) => `- ${markdownCode(file.path)} (${file.confidence} confidence, score ${file.score}): ${file.reasons.join("; ")}`)),
     "",
     "## Test Routes",
     "",
     ...listOrEmpty(report.testRoutes.map((route) => {
-      const related = route.relatedFiles.length > 0 ? ` Related: ${route.relatedFiles.map((path) => `\`${path}\``).join(", ")}.` : "";
-      return `- \`${route.command}\`: ${route.reason}.${related}`;
+      const related = route.relatedFiles.length > 0 ? ` Related: ${route.relatedFiles.map(markdownCode).join(", ")}.` : "";
+      return `- ${markdownCode(route.command)}: ${route.reason}.${related}`;
     })),
     "",
     "## Risk Map",
@@ -581,7 +569,7 @@ export function renderMarkdownReport(report: FixMapReport): string {
     "",
     "## Changed Files",
     "",
-    ...listOrEmpty(report.changedFiles.map((path) => `- \`${path}\``)),
+    ...listOrEmpty(report.changedFiles.map((path) => `- ${markdownCode(path)}`)),
     ...(report.analysis ? [
       "",
       "## Analysis",
@@ -596,7 +584,7 @@ export function renderMarkdownReport(report: FixMapReport): string {
     "",
     ...listOrEmpty(report.diagnostics.flatMap((diagnostic) => [
       `- **${diagnostic.severity}** ${diagnostic.message}`,
-      ...(diagnostic.paths ?? []).slice(0, 8).map((path) => `  - \`${path}\``)
+      ...(diagnostic.paths ?? []).slice(0, 8).map((path) => `  - ${markdownCode(path)}`)
     ]))
   ];
 
diff --git a/packages/core/src/signals.ts b/packages/core/src/signals.ts
index 7dcebb1..02bf7e2 100644
--- a/packages/core/src/signals.ts
+++ b/packages/core/src/signals.ts
@@ -1,4 +1,4 @@
-const TOKEN_SPLIT = /[^a-zA-Z0-9]+/g;
+const TOKEN_SPLIT = /[^\p{L}\p{N}]+/gu;
 
 // Path-segment words like src, main, index, package and packages are in here on purpose.
 // They appear in nearly every path, so as task terms they match everything and rank nothing —
@@ -23,7 +23,6 @@ const STOP_WORDS = new Set([
   "but",
   "can",
   "cannot",
-  "case",
   "catch",
   "class",
   "const",
@@ -31,8 +30,6 @@ const STOP_WORDS = new Set([
   "codebase",
   "could",
   "debugger",
-  "default",
-  "delete",
   "did",
   "doe",
   "does",
@@ -48,7 +45,6 @@ const STOP_WORDS = new Set([
   "for",
   "from",
   "function",
-  "get",
   "github",
   "got",
   "had",
@@ -75,7 +71,6 @@ const STOP_WORDS = new Set([
   "more",
   "most",
   "must",
-  "name",
   "namespace",
   "new",
   "node",
@@ -88,15 +83,12 @@ const STOP_WORDS = new Set([
   "our",
   "out",
   "over",
-  "package",
   "packages",
   "private",
   "quality",
   "protected",
-  "public",
   "readonly",
   "return",
-  "run",
   "same",
   "she",
   "should",
@@ -122,7 +114,6 @@ const STOP_WORDS = new Set([
   "throw",
   "true",
   "try",
-  "type",
   "typeof",
   "under",
   "undefined",
@@ -153,29 +144,30 @@ const STOP_WORDS = new Set([
 // A 30,000-character paste took 2.4 seconds here, and the Action feeds this pattern issue
 // text from public pull requests. No real path mention is longer than this bound.
 const MAX_FILE_MENTION_LENGTH = 200;
+import { SOURCE_FILE_EXTENSIONS } from "./paths.js";
+
+const FILE_MENTION_EXTENSIONS = [...SOURCE_FILE_EXTENSIONS]
+  .map((extension) => extension.slice(1).replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+  .sort((left, right) => right.length - left.length)
+  .join("|");
 const FILE_MENTION_PATTERN =
   new RegExp(
-    `[A-Za-z0-9_@$][A-Za-z0-9_.$/\\\\-]{0,${MAX_FILE_MENTION_LENGTH}}` +
-    "\\.(?:[cm]?[jt]sx?|json|ya?ml|mdx?|css|scss|less|html|py|rb|rs|go|java|kt|c|cc|cpp|h|hpp|d\\.ts)\\b",
+    `(?:[A-Za-z]:[\\\\/]|[\\\\/])?[A-Za-z0-9_@$][A-Za-z0-9_.$/\\\\-]{0,${MAX_FILE_MENTION_LENGTH}}` +
+    `\\.(?:${FILE_MENTION_EXTENSIONS}|d\\.ts)\\b`,
     "g"
   );
 const CONVENTIONAL_FILE_MENTION_PATTERN =
   /\b(?:AUTHORS|CHANGELOG|CODE_OF_CONDUCT|CONTRIBUTING|LICENSE|NOTICE|README|SECURITY|CODEOWNERS|Dockerfile|Gemfile|Jenkinsfile|Makefile|Procfile|Rakefile|Vagrantfile)\b/gi;
 const MEMBER_MENTION_PATTERN =
-  /\b(?:window|globalThis|process|request|response|req|res|this)\.([$A-Za-z_][$A-Za-z0-9_$]*)\b/g;
+  /(?<![\p{L}\p{N}_$])[\p{L}_$][\p{L}\p{N}_$]*\.([\p{L}_$][\p{L}\p{N}_$]*)(?![\p{L}\p{N}_$])/gu;
 const FILE_EXTENSIONS = new Set([
   "c", "cc", "cjs", "cpp", "css", "go", "h", "hpp", "html", "java", "js", "json",
   "jsx", "kt", "less", "md", "mdx", "mjs", "py", "rb", "rs", "scss", "ts", "tsx",
   "yaml", "yml"
 ]);
-const IDENTIFIER_PATTERN = /[A-Za-z_$][A-Za-z0-9_$]{4,}/g;
+const IDENTIFIER_PATTERN = /[\p{L}_$][\p{L}\p{N}_$]{4,}/gu;
 const MAX_EXACT_FRAGMENTS = 8;
 const MAX_IDENTIFIERS = 24;
-const TRAILING_E_VERB_STEMS = new Set([
-  "bas", "cach", "chang", "cod", "contribut", "creat", "dat", "fil", "improv", "invoic",
-  "mak", "pars", "remov", "resolv", "rout", "siz", "tim", "updat"
-]);
-
 export type TaskSignals = {
   tokens: Set<string>;
   changedFiles: Set<string>;
@@ -192,16 +184,19 @@ export function extractTaskSignals(input: {
   diffText?: string | undefined;
   changedFiles?: string[];
 }): TaskSignals {
-  const prepared = prepareChecklistText(input.issueText ?? "");
+  const prepared = prepareChecklistText(redactSensitiveTaskText(input.issueText ?? ""));
   const issueText = prepared.text;
-  const taskText = [issueText, extractDiffContentLines(input.diffText ?? "")].join("\n");
+  const visibleIssueText = stripHtmlComments(issueText);
+  const issueSignalText = stripHttpUrls(visibleIssueText);
+  const diffSignalText = stripHttpUrls(redactSensitiveTaskText(extractDiffContentLines(input.diffText ?? "")));
+  const taskText = [issueSignalText, diffSignalText].join("\n");
   const tokens = tokenizeText(taskText);
 
   return {
     tokens,
     changedFiles: new Set(input.changedFiles ?? []),
-    fileMentions: extractFileMentions(issueText),
-    memberMentions: extractMemberMentions(issueText),
+    fileMentions: extractFileMentions(visibleIssueText),
+    memberMentions: extractMemberMentions(issueSignalText),
     exactFragments: extractExactFragments(taskText),
     identifiers: extractIdentifiers(taskText),
     uncheckedChecklistLinesRemoved: prepared.removed,
@@ -258,10 +253,10 @@ export function extractIdentifiers(text: string): Set<string> {
       continue;
     }
     const fragment = quoted.value.trim();
-    if (!/^[$A-Za-z_][$A-Za-z0-9_]*$/.test(fragment.trim())) {
+    if (!/^[\p{L}_$][\p{L}\p{N}_$]*$/u.test(fragment.trim())) {
       continue;
     }
-    if (!isDistinctiveIdentifier(fragment) && fragment.length < 8) {
+    if (!isDistinctiveIdentifier(fragment) && fragment.length < 6) {
       continue;
     }
     for (const match of fragment.matchAll(IDENTIFIER_PATTERN)) {
@@ -269,6 +264,10 @@ export function extractIdentifiers(text: string): Set<string> {
     }
   }
 
+  for (const match of text.matchAll(/(?<![\p{L}\p{N}_$])([\p{L}_$][\p{L}\p{N}_$]{2,})\(/gu)) {
+    if (match[1]) addIdentifier(identifiers, match[1]);
+  }
+
   return identifiers;
 }
 
@@ -280,15 +279,37 @@ function addIdentifier(identifiers: Set<string>, identifier: string): void {
 }
 
 function isDistinctiveIdentifier(identifier: string): boolean {
-  return /[0-9_$]/.test(identifier) || /[a-z][A-Z]/.test(identifier);
+  return /[0-9_$]/.test(identifier) || /[\p{Ll}][\p{Lu}]/u.test(identifier) || !/^[\x00-\x7F]+$/.test(identifier);
 }
 
 function isDistinctiveFragment(fragment: string): boolean {
-  if (fragment.length < 6 || fragment.length > 96 || /\s/.test(fragment)) {
+  if (fragment.length < 6 || fragment.length > 160) {
     return false;
   }
-  const punctuationCount = [...fragment].filter((character) => /[^A-Za-z0-9_$]/.test(character)).length;
-  return punctuationCount >= 2 && /[A-Za-z0-9]/.test(fragment);
+  if (/\s/.test(fragment)) {
+    return fragment.trim().split(/\s+/).length >= 2 && /[\p{L}\p{N}]/u.test(fragment);
+  }
+  const punctuationCount = [...fragment].filter((character) => /[^\p{L}\p{N}$]/u.test(character)).length;
+  return punctuationCount >= 1 && /[\p{L}\p{N}]/u.test(fragment);
+}
+
+export function redactSensitiveTaskText(text: string): string {
+  return text
+    .replace(/(https?:\/\/)[^/\s@]+@/gi, "$1")
+    .replace(/\b(?:ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{8,}\b/g, "[redacted]")
+    .replace(/\bAKIA[0-9A-Z]{16}\b/g, "[redacted]")
+    .replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, "[redacted]");
+}
+
+/** URLs are never identifier evidence. Removing them before exact-fragment and identifier
+ * extraction also prevents an unfamiliar token shape in a URL from being repeated in a
+ * diagnostic. File mentions from GitHub blob URLs are extracted separately, before this. */
+function stripHttpUrls(text: string): string {
+  return text.includes("://") ? text.replace(/https?:\/\/[^\s<>()\[\]{}]+/gi, " [url] ") : text;
+}
+
+function stripHtmlComments(text: string): string {
+  return text.includes("<!--") ? text.replace(/<!--[\s\S]*?-->/g, " ") : text;
 }
 
 function scanQuotedFragments(text: string): Array<{ delimiter: string; value: string }> {
@@ -297,22 +318,33 @@ function scanQuotedFragments(text: string): Array<{ delimiter: string; value: st
   for (const line of text.split(/\r?\n/)) {
     let cursor = 0;
     while (cursor < line.length) {
-      const delimiter = line[cursor];
-      if (delimiter !== '"' && delimiter !== "'" && delimiter !== "`") {
+      const delimiter = line[cursor]!;
+      const closingDelimiter = delimiter === "“" || delimiter === "„" ? "”" :
+        delimiter === "‘" ? "’" : delimiter === "«" ? "»" : delimiter;
+      if (!["\"", "'", "`", "“", "„", "‘", "«"].includes(delimiter ?? "")) {
+        cursor += 1;
+        continue;
+      }
+      if (delimiter === "'" && cursor > 0 && /[A-Za-z0-9]/.test(line[cursor - 1] ?? "")) {
         cursor += 1;
         continue;
       }
 
       let end = cursor + 1;
       while (end < line.length) {
-        if (line[end] === delimiter && !isEscaped(line, end)) {
+        if (line[end] === closingDelimiter && !isEscaped(line, end)) {
           break;
         }
         end += 1;
       }
 
-      fragments.push({ delimiter, value: line.slice(cursor + 1, end) });
-      cursor = end < line.length ? end + 1 : line.length;
+      if (end < line.length) {
+        fragments.push({ delimiter, value: line.slice(cursor + 1, end) });
+        cursor = end + 1;
+      } else {
+        if (delimiter !== "'") fragments.push({ delimiter, value: line.slice(cursor + 1) });
+        cursor += 1;
+      }
     }
   }
 
@@ -383,7 +415,7 @@ function extractDiffContentLines(diffText: string): string {
 
   return diffText
     .split(/\r?\n/)
-    .filter((line) => (line.startsWith("+") || line.startsWith("-")) && !line.startsWith("+++") && !line.startsWith("---"))
+    .filter((line) => line.startsWith("+") && !line.startsWith("+++"))
     .join("\n");
 }
 
@@ -402,24 +434,44 @@ export function tokenizeText(text: string): Set<string> {
   );
 }
 
+/** Tokenize a symbol name without prose stop-word filtering. `getUser` and `runJob` need
+ * both camel-case segments for partial-definition grounding even though `get` and `run`
+ * are intentionally ignored in ordinary issue prose. */
+export function tokenizeIdentifier(identifier: string): Set<string> {
+  return new Set(
+    identifier
+      .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+      .toLowerCase()
+      .split(TOKEN_SPLIT)
+      .map((token) => normalizeToken(token.trim()))
+      .filter((token) => isSearchableToken(token))
+  );
+}
+
 // An unbroken alphanumeric run this long is a hash, a base64 blob, or a paste artifact,
 // never a term someone is searching for. Dropping it here rather than at the point of
 // display means it can neither pollute a diagnostic nor score a file for matching noise.
 const MAX_SEARCHABLE_TOKEN_LENGTH = 64;
+const SHORT_SEARCHABLE_TOKENS = new Set(["ci", "ui"]);
 
 function isSearchableToken(token: string): boolean {
   if (token.length > MAX_SEARCHABLE_TOKEN_LENGTH) {
     return false;
   }
-  return token.length >= 3 || /^[a-z]\d$/i.test(token);
+  return token.length >= 3 || SHORT_SEARCHABLE_TOKENS.has(token.toLowerCase()) || /^[a-z]\d$/i.test(token);
 }
 
 function normalizeToken(token: string): string {
+  if (token === "kubernetes") return token;
+  if (token === "scss" || token === "sass" || token === "less") return "css";
   if (token === "contributor" || token === "contributors") return "contribute";
   if (token.length > 5 && token.endsWith("ies")) return `${token.slice(0, -3)}y`;
+  if (token.length > 4 && token.endsWith("ied")) return `${token.slice(0, -3)}y`;
   if (token.length > 5 && token.endsWith("ing")) return normalizeVerbStem(token.slice(0, -3));
-  if (token.length > 4 && token.endsWith("ed")) return normalizeVerbStem(token.slice(0, -2));
-  if (token.length > 4 && /(?:sses|shes|ches|xes|zes)$/.test(token)) return token.slice(0, -2);
+  if (token.length > 3 && token.endsWith("ed")) return normalizeVerbStem(token.slice(0, -2));
+  if (token.length > 4 && /(?:sses|shes|ches|xes|zes)$/.test(token)) {
+    return token.slice(0, -2);
+  }
   // A trailing `s` is a plural only when it is not part of the word itself. `pass`, `class`
   // and `process` end in `ss`; `status` and `bus` in `us`; `analysis` and `basis` in `is`.
   // Stripping it produced `pas`, `clas`, `proces`, `statu` — stems that match nothing, and
@@ -435,8 +487,46 @@ function normalizeVerbStem(stem: string): string {
   // doubles a *single* final consonant to inflect, so a base already ending in `ss` never
   // got there that way: `passed` and `processed` strip to `pass` and `process`, and
   // deduplicating those produced `pas` and `proces` — stems that match nothing at all.
-  const deduplicated = /([a-z])\1$/.test(stem) && !stem.endsWith("ss") ? stem.slice(0, -1) : stem;
-  return TRAILING_E_VERB_STEMS.has(deduplicated) ? `${deduplicated}e` : deduplicated;
+  const wasDoubled = /([a-z])\1$/.test(stem) && !stem.endsWith("ss");
+  if (wasDoubled) {
+    return stem.slice(0, -1);
+  }
+
+  // Porter-style spelling rules handle an open vocabulary. The previous implementation
+  // restored a trailing e from a growing word allowlist, so every unlisted verb repeated
+  // the same bug. These rules make the surface forms take the same path instead:
+  // validate/validated -> validate, file/files/filed -> file, store/stored -> store.
+  const silentEStem = /(?:at|bl|iz|ap|ud|ac|ut|ov|et|dl|rg|ng|ic|out|rs|ch|lv)$/;
+  return silentEStem.test(stem) || (stemMeasure(stem) === 1 && endsConsonantVowelConsonant(stem))
+    ? `${stem}e`
+    : stem;
+}
+
+/** Number of vowel-to-consonant groups in a lowercase ASCII word (Porter's `m`). */
+function stemMeasure(word: string): number {
+  let measure = 0;
+  let previousWasVowel = false;
+  for (let index = 0; index < word.length; index += 1) {
+    const vowel = isStemVowel(word, index);
+    if (previousWasVowel && !vowel) measure += 1;
+    previousWasVowel = vowel;
+  }
+  return measure;
+}
+
+function endsConsonantVowelConsonant(word: string): boolean {
+  if (word.length < 3) return false;
+  const last = word.length - 1;
+  return !isStemVowel(word, last - 2) &&
+    isStemVowel(word, last - 1) &&
+    !isStemVowel(word, last) &&
+    !/[wxy]/.test(word[last] ?? "");
+}
+
+function isStemVowel(word: string, index: number): boolean {
+  const character = word[index] ?? "";
+  if (/[aeiou]/.test(character)) return true;
+  return character === "y" && index > 0 && !isStemVowel(word, index - 1);
 }
 
 export function tokenizePath(path: string): Set<string> {
diff --git a/packages/core/src/test-gates.ts b/packages/core/src/test-gates.ts
index 7576533..370731d 100644
--- a/packages/core/src/test-gates.ts
+++ b/packages/core/src/test-gates.ts
@@ -1,6 +1,14 @@
 import type { RepoFile, ScanDiagnostic } from "./types.js";
 
-const GATE_PATTERN = /\.(skipIf|runIf)\s*\(/;
+const CONDITIONAL_GATE_PATTERN = /\.(?:skipIf|runIf)\s*\(/;
+const UNCONDITIONAL_GATE_PATTERNS = [
+  /\b(?:it|test|describe|context)\.(?:skip|todo)\s*\(/,
+  /\b(?:xit|xtest|xdescribe|xcontext)\s*\(/,
+  /\bthis\.skip\s*\(/,
+  /@(?:pytest\.mark\.(?:skip|skipif)|unittest\.skip(?:If|Unless)?)\b/,
+  /\bt\.Skip(?:f|Now)?\s*\(/,
+  /#\[ignore(?:\s*=|\s*\])/
+];
 const ENV_NAME_PATTERNS = [/process\.env\.([A-Z][A-Z0-9_]*)/g, /process\.env\[["']([A-Z][A-Z0-9_]*)["']\]/g];
 
 export function findGatedTestDiagnostics(files: RepoFile[], routedTestPaths: string[]): ScanDiagnostic[] {
@@ -8,14 +16,18 @@ export function findGatedTestDiagnostics(files: RepoFile[], routedTestPaths: str
   const diagnostics: ScanDiagnostic[] = [];
 
   for (const file of files) {
-    if (!file.isTest || !routed.has(file.path) || !GATE_PATTERN.test(file.textSample)) {
+    const conditional = CONDITIONAL_GATE_PATTERN.test(file.textSample);
+    const unconditional = UNCONDITIONAL_GATE_PATTERNS.some((pattern) => pattern.test(file.textSample));
+    if (!file.isTest || !routed.has(file.path) || (!conditional && !unconditional)) {
       continue;
     }
 
     diagnostics.push({
       code: "gated-test-skipped",
       severity: "warning",
-      message: gateMessage(file.path, extractEnvNames(file.textSample))
+      message: unconditional
+        ? `${file.path} contains skipped or ignored tests; the suggested test command will not exercise them until the skip is removed.`
+        : gateMessage(file.path, extractEnvNames(file.textSample))
     });
   }
 
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
index e384963..2a51c5d 100644
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -58,16 +58,21 @@ export type ScanDiagnostic = {
     | "flat-ranking"
     | "no-test-route"
     | "no-related-tests"
-    | "content-unread"
+    | "content-not-utf8"
+    | "content-unreadable"
+    | "content-too-large"
     | "generated-paths-dominant"
+    | "import-graph-truncated"
     | "paths-excluded"
     | "exclusion-no-match"
     | "working-tree-diff"
     | "diff-resolved"
+    | "diff-text-truncated"
     | "cache-hit"
     | "cache-bypass"
     | "cache-skip"
-    | "task-checklist-filtered";
+    | "task-checklist-filtered"
+    | "package-manager-conflict";
   message: string;
   severity: "info" | "warning" | "error";
   /**
@@ -167,6 +172,8 @@ export type VerifyFinding = {
     | "leading-file-untouched"
     | "no-test-changed"
     | "new-risk-area"
+    | "plan-partially-stale"
+    | "planned-file-deleted"
     | "plan-repository-mismatch";
   severity: "info" | "warning" | "error";
   paths: string[];
diff --git a/packages/core/src/verify.ts b/packages/core/src/verify.ts
index c2e0775..acfa057 100644
--- a/packages/core/src/verify.ts
+++ b/packages/core/src/verify.ts
@@ -10,6 +10,7 @@
 import { isBackupPath, isGeneratedPath, moduleStem } from "./paths.js";
 import { buildRiskNotes, pathsForRiskArea } from "./report.js";
 import type { FixMapReport, RepoMap, VerifyFinding, VerifyResult } from "./types.js";
+import { markdownCode } from "./markdown.js";
 
 export function verifyPlan(report: FixMapReport, repo: RepoMap): VerifyResult {
   const changed = repo.changedFiles;
@@ -17,7 +18,11 @@ export function verifyPlan(report: FixMapReport, repo: RepoMap): VerifyResult {
   const fileByPath = new Map(repo.files.map((file) => [file.path, file]));
   const plannedPaths = report.contextFiles.map((file) => file.path);
 
-  if (plannedPaths.length > 0 && !plannedPaths.some((path) => fileByPath.has(path))) {
+  const missingPlanned = plannedPaths.filter((path) => !fileByPath.has(path));
+  const changedMissingPlanned = missingPlanned.filter((path) => changed.includes(path));
+  const unexplainedMissingPlanned = missingPlanned.filter((path) => !changed.includes(path));
+
+  if (plannedPaths.length > 0 && unexplainedMissingPlanned.length === plannedPaths.length) {
     const mismatch: VerifyFinding = {
       code: "plan-repository-mismatch",
       severity: "error",
@@ -34,6 +39,27 @@ export function verifyPlan(report: FixMapReport, repo: RepoMap): VerifyResult {
     };
   }
 
+  if (unexplainedMissingPlanned.length > 0) {
+    findings.push({
+      code: "plan-partially-stale",
+      severity: "warning",
+      paths: unexplainedMissingPlanned.slice(0, 8),
+      message:
+        `${unexplainedMissingPlanned.length} of ${plannedPaths.length} planned paths no longer exist and are not explained by this diff. ` +
+        "The plan may predate a rebase or rename; regenerate it before relying on the missing entries."
+    });
+  }
+  if (changedMissingPlanned.length > 0) {
+    findings.push({
+      code: "planned-file-deleted",
+      severity: "info",
+      paths: changedMissingPlanned.slice(0, 8),
+      message:
+        `${changedMissingPlanned.length === 1 ? "A planned file was" : `${changedMissingPlanned.length} planned files were`} removed by this diff. ` +
+        "The deletion accounts for the missing path, so verification continued."
+    });
+  }
+
   if (changed.length === 0) {
     return {
       summary: "No changes to verify: the diff resolved to zero files.",
@@ -202,11 +228,11 @@ export function renderVerifyMarkdown(result: VerifyResult): string {
     for (const finding of result.findings) {
       lines.push(`- **${finding.severity}** ${finding.message}`);
       for (const path of finding.paths.slice(0, 8)) {
-        lines.push(`  - \`${path}\``);
+        lines.push(`  - ${markdownCode(path)}`);
       }
     }
   }
   lines.push("", "## Changed Files", "");
-  lines.push(...(result.changedFiles.length > 0 ? result.changedFiles.map((path) => `- \`${path}\``) : ["- None found"]));
+  lines.push(...(result.changedFiles.length > 0 ? result.changedFiles.map((path) => `- ${markdownCode(path)}`) : ["- None found"]));
   return `${lines.join("\n")}\n`;
 }
diff --git a/packages/core/test/compare.test.ts b/packages/core/test/compare.test.ts
index 46b55fb..0e23dbf 100644
--- a/packages/core/test/compare.test.ts
+++ b/packages/core/test/compare.test.ts
@@ -113,6 +113,8 @@ describe("compareReports", () => {
     const comparison = compareReports(previous, current);
 
     expect(comparison.groundingChanged).toBe(true);
+    expect(comparison.summary).toBe("The ranking is unchanged, but task grounding changed from vague to anchored.");
+    expect(comparison.summary).not.toContain("changed nothing");
     expect(renderComparisonMarkdown(comparison)).toContain("vague");
     expect(renderComparisonMarkdown(comparison)).toContain("anchored");
   });
@@ -147,4 +149,34 @@ describe("compareReports", () => {
     expect(entered).not.toContain("undefined");
     expect(moved).not.toContain("undefined");
   });
+
+  it("does not invent a grounding delta when only one report has grounding metadata", () => {
+    const legacy = reportOf([{ path: "a.ts" }]);
+    const current = reportOf([{ path: "a.ts" }]);
+    current.analysis = {
+      grounding: {
+        specificity: "descriptive",
+        identifiers: [],
+        unresolvedIdentifiers: [],
+        partiallyResolvedIdentifiers: [],
+        unverifiedIdentifiers: [],
+        scanComplete: true
+      },
+      ranking: { topScore: 10, runnerUpScore: null, topGap: null, clustered: false },
+      nextAction: ""
+    };
+
+    const comparison = compareReports(legacy, current);
+
+    expect(comparison.groundingChanged).toBe(false);
+    expect(comparison.summary).toContain("predates grounding analysis");
+  });
+
+  it("rejects duplicate ranked paths instead of silently collapsing buckets", () => {
+    const duplicate = reportOf([{ path: "a.ts" }, { path: "a.ts" }]);
+
+    expect(() => compareReports(duplicate, reportOf([{ path: "a.ts" }]))).toThrow(
+      "Previous report has a duplicate contextFiles path: a.ts"
+    );
+  });
 });
diff --git a/packages/core/test/entrypoints.test.ts b/packages/core/test/entrypoints.test.ts
new file mode 100644
index 0000000..7ba1f83
--- /dev/null
+++ b/packages/core/test/entrypoints.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import * as browserEntry from "../src/browser.js";
+import * as nodeEntry from "../src/index.js";
+
+describe("public entrypoint parity", () => {
+  it.each([
+    "buildReportFromRepo",
+    "renderJsonReport",
+    "renderMarkdownReport",
+    "validateFixMapReport",
+    "quoteCliValue"
+  ])("exports deterministic API %s from both node and browser entries", (name) => {
+    expect(nodeEntry).toHaveProperty(name);
+    expect(browserEntry).toHaveProperty(name);
+  });
+
+  it("keeps filesystem scanning node-only", () => {
+    expect(nodeEntry).toHaveProperty("scanRepo");
+    expect(browserEntry).not.toHaveProperty("scanRepo");
+  });
+});
diff --git a/packages/core/test/exclude.test.ts b/packages/core/test/exclude.test.ts
index 85537c5..7b5db1b 100644
--- a/packages/core/test/exclude.test.ts
+++ b/packages/core/test/exclude.test.ts
@@ -88,6 +88,15 @@ describe("buildPathExcluder", () => {
     expect(excluder.patterns).toEqual(["apps/web"]);
     expect(excluder.reasonFor("apps/web/app/reset-copy.ts")).toBe("apps/web");
   });
+
+  it("agent report #22 handles a large ignore list without an arbitrary pattern cap", () => {
+    const patterns = Array.from({ length: 1_000 }, (_, index) => `generated/${index}/**`);
+    const excluder = buildPathExcluder(patterns);
+
+    expect(excluder.patterns).toHaveLength(1_000);
+    expect(excluder.excludes("generated/999/result.ts")).toBe(true);
+    expect(excluder.excludes("src/result.ts")).toBe(false);
+  });
 });
 
 describe("exclusions in ranking", () => {
diff --git a/packages/core/test/github-issues-600-627.test.ts b/packages/core/test/github-issues-600-627.test.ts
new file mode 100644
index 0000000..eb05339
--- /dev/null
+++ b/packages/core/test/github-issues-600-627.test.ts
@@ -0,0 +1,173 @@
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { explainFile } from "../src/explain.js";
+import { analyzeTaskGrounding } from "../src/grounding.js";
+import { isBackupPath, moduleStem } from "../src/paths.js";
+import { buildReportFromRepo, buildTestRoutes, RISK_RULES } from "../src/report.js";
+import { rankContextFiles, RANKING_SIGNAL_TERMS, REPORT_SCORE_CUTOFF } from "../src/rank.js";
+import { scanRepo } from "../src/repo-scan.js";
+import { extractFileMentions, extractTaskSignals, tokenizeText } from "../src/signals.js";
+import type { RepoFile, RepoMap } from "../src/types.js";
+
+function code(path: string, textSample: string, kind: RepoFile["kind"] = "code"): RepoFile {
+  return {
+    path,
+    extension: /\.[^.]+$/.exec(path)?.[0]?.toLowerCase() ?? "",
+    sizeBytes: textSample.length,
+    isSource: true,
+    isTest: false,
+    kind,
+    textSample
+  };
+}
+
+function repo(files: RepoFile[], changedFiles: string[] = []): RepoMap {
+  return {
+    root: "/repo",
+    files,
+    packageScripts: [],
+    changedFiles,
+    diffText: "",
+    packageManager: "npm",
+    diagnostics: []
+  };
+}
+
+describe("GitHub issues #600-#627", () => {
+  it("#600 keeps vague task specificity vague when a diff is present", () => {
+    const map = repo([code("src/index.ts", "export const value = 1")], ["src/index.ts"]);
+    expect(analyzeTaskGrounding(map, { issueText: "improve the codebase", diffText: "+value" }).specificity).toBe("vague");
+  });
+
+  it("#607 keeps every ranking literal searchable and every risk literal effective", () => {
+    for (const term of RANKING_SIGNAL_TERMS) expect(tokenizeText(term).size, term).toBeGreaterThan(0);
+    for (const rule of RISK_RULES) {
+      for (const term of rule.terms) {
+        expect(buildReportFromRepo(repo([code(`src/${term}.ts`, "export const value = 1")]), { issueText: term }).risks.map((risk) => risk.area), `${rule.area}:${term}`).toContain(rule.area);
+      }
+    }
+  });
+
+  it("#610 derives clustering from the full ranking before --limit truncation", () => {
+    const map = repo(["a", "b", "c", "d"].map((name) =>
+      code(`src/${name}.ts`, "alpha bravo charlie delta echo foxtrot golf hotel india juliet")
+    ));
+    const full = buildReportFromRepo(map, { issueText: "alpha bravo charlie delta echo foxtrot golf hotel india juliet", limit: 8 });
+    const one = buildReportFromRepo(map, { issueText: "alpha bravo charlie delta echo foxtrot golf hotel india juliet", limit: 1 });
+    expect(full.analysis?.ranking.clustered).toBe(true);
+    expect(one.analysis?.ranking).toEqual(full.analysis?.ranking);
+    expect(one.contextFiles[0]?.confidence).toBe(full.contextFiles[0]?.confidence);
+  });
+
+  it("#611 keeps a vocabulary leader contested when --limit hides the definition site", () => {
+    const map = repo([
+      code("src/consumer.ts", "resolveToken resolveToken resolveToken is called here"),
+      code("src/definition.ts", "export function resolveToken(){ return 1; }")
+    ]);
+    const issueText = "resolveToken is broken, see src/consumer.ts";
+    expect(rankContextFiles(map, { issueText }, 8)[0]?.confidence).toBe("medium");
+    expect(rankContextFiles(map, { issueText }, 1)[0]?.confidence).toBe("medium");
+  });
+
+  it("#612 reports the actual cutoff when the report has unused slots", () => {
+    const map = repo([
+      code("src/hit.ts", "resolveToken resolveToken export function resolveToken(){}"),
+      code("src/barely.ts", "unrelated words only here")
+    ]);
+    const explanation = explainFile(map, { issueText: "resolveToken is broken" }, "src/barely.ts");
+    expect(explanation.status).toBe("below-cutoff");
+    expect(explanation.cutoff).toBe(REPORT_SCORE_CUTOFF);
+    expect(explanation.summary).toContain(`reporting cutoff of ${REPORT_SCORE_CUTOFF}`);
+  });
+
+  it.each(["foo.php", "foo.vue", "foo.svelte", "foo.cs", "foo.cjs", "foo.mts"])(
+    "#616 extracts the scannable file mention %s",
+    (path) => expect(extractFileMentions(`fix src/${path}`)).toContain(`src/${path}`)
+  );
+
+  it("#618 strips only one source/generated layout segment from module stems", () => {
+    expect(moduleStem("src/foo/lib/index.ts")).toBe("foo/lib/index");
+    expect(moduleStem("src/lib/foo/index.ts")).toBe("lib/foo/index");
+    expect(moduleStem("packages/api/dist/index.js")).toBe("packages/api/index");
+    expect(moduleStem("packages/api/src/index.ts")).toBe("packages/api/index");
+  });
+
+  it("#621 recognizes typographic quote pairs as exact fragments", () => {
+    for (const issueText of ["error “reset-token.ts” here", "error ‘reset-token.ts’ here", "error «reset-token.ts» here", "error „reset-token.ts” here"]) {
+      expect(extractTaskSignals({ issueText }).exactFragments, issueText).toContain("reset-token.ts");
+    }
+  });
+
+  it("#622 does not boost a root basename when a nested path was named", () => {
+    const ranked = rankContextFiles(repo([
+      code("foo.ts", "export const unrelated = 1"),
+      code("src/foo.ts", "export const target = 1")
+    ]), { issueText: "bug in src/foo.ts" });
+    expect(ranked.find((entry) => entry.path === "src/foo.ts")?.reasons).toContain("explicitly named in the task");
+    expect(ranked.find((entry) => entry.path === "foo.ts")?.reasons).not.toContain("explicitly named in the task");
+  });
+
+  it("#623 grounds stop-word-prefixed identifiers through their complete symbol tokens", () => {
+    const grounding = analyzeTaskGrounding(
+      repo([code("src/user.ts", "export function getCurrentUser(){ return null; }")]),
+      { issueText: "getUser returns the wrong value" }
+    );
+    expect(grounding.identifiers).toContainEqual({
+      identifier: "getUser",
+      status: "partial-definition",
+      matchedFiles: ["src/user.ts"]
+    });
+  });
+
+  it("#624 recognizes generator functions as definition sites", () => {
+    const ranked = rankContextFiles(repo([
+      code("src/saga.ts", "export async function* fetchUser(){ yield 1; }")
+    ]), { issueText: "fetchUser saga is broken" });
+    expect(ranked[0]?.reasons).toContain("defines task identifiers: fetchUser");
+  });
+
+  it("#626 distinguishes copy utilities from sync-client backup copies", () => {
+    expect(isBackupPath("src/deep-copy.ts")).toBe(false);
+    expect(isBackupPath("src/shallow-copy.ts")).toBe(false);
+    expect(isBackupPath("src/user_copy.ts")).toBe(false);
+    expect(isBackupPath("src/foo copy.ts")).toBe(true);
+    expect(isBackupPath("src/foo-copy (2).ts")).toBe(true);
+  });
+
+  it("#625, #617, and #627 keep source config files, vendored source, and nested Yarn routing", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-issues-625-627-"));
+    try {
+      await mkdir(join(root, "apps", "api", "src"), { recursive: true });
+      await mkdir(join(root, "vendor", "first-party"), { recursive: true });
+      await writeFile(join(root, "package.json"), JSON.stringify({ scripts: { test: "vitest run" } }));
+      await writeFile(join(root, "apps", "api", "package.json"), JSON.stringify({ name: "@app/api", scripts: { test: "vitest run" } }));
+      await writeFile(join(root, "apps", "api", "yarn.lock"), "# yarn lockfile\n");
+      await writeFile(join(root, "apps", "api", "src", "config.ts"), "export function resolveToken(){ return 1; }\n");
+      await writeFile(join(root, "vendor", "first-party", "copy.php"), "<?php function copiedValue() { return 1; }\n");
+
+      const scanned = await scanRepo({ repoRoot: root, useCache: false });
+      expect(scanned.packageManager).toBe("yarn");
+      expect(scanned.files.find((file) => file.path === "apps/api/src/config.ts")?.kind).toBe("code");
+      expect(scanned.files.map((file) => file.path)).toContain("vendor/first-party/copy.php");
+      expect(buildTestRoutes(scanned, ["apps/api/src/config.ts"])[0]?.command).toBe("yarn workspace @app/api run test");
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("#627 diagnoses conflicting root package-manager declarations", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-package-conflict-"));
+    try {
+      await writeFile(join(root, "package.json"), "{}");
+      await writeFile(join(root, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+      await writeFile(join(root, "yarn.lock"), "# yarn\n");
+      const scanned = await scanRepo({ repoRoot: root, useCache: false });
+      expect(scanned.packageManager).toBe("pnpm");
+      expect(scanned.diagnostics).toContainEqual(expect.objectContaining({ code: "package-manager-conflict" }));
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/core/test/grounding.test.ts b/packages/core/test/grounding.test.ts
index fd07d8b..c251934 100644
--- a/packages/core/test/grounding.test.ts
+++ b/packages/core/test/grounding.test.ts
@@ -100,6 +100,17 @@ describe("task grounding", () => {
     expect(grounding.specificity).not.toBe("vague");
   });
 
+  it.each([
+    "please fix CSV export failures",
+    "fix performance regression in cache state transitions",
+    "repair reliability errors in the retry scheduler",
+    "refactor broke cache state transitions"
+  ])("keeps an ordinary concrete bug report descriptive: %s", (issueText) => {
+    const grounding = analyzeTaskGrounding(createRepo(), { issueText });
+
+    expect(grounding.specificity).toBe("descriptive");
+  });
+
   it("leaves a specific symptom descriptive when it carries no improvement language", () => {
     const grounding = analyzeTaskGrounding(createRepo(), {
       issueText:
diff --git a/packages/core/test/import-graph.test.ts b/packages/core/test/import-graph.test.ts
index bb0c5e5..2d1d0ca 100644
--- a/packages/core/test/import-graph.test.ts
+++ b/packages/core/test/import-graph.test.ts
@@ -42,6 +42,40 @@ describe("buildImportGraph", () => {
 
     expect(graph.imports.get("src/a.ts")).toBeUndefined();
   });
+
+  it("resolves imports through workspace package names", () => {
+    const files = [
+      codeFile("apps/web/page.ts", 'import { reset } from "@demo/auth";'),
+      codeFile("packages/auth/package.json", JSON.stringify({ name: "@demo/auth", source: "src/index.ts" })),
+      codeFile("packages/auth/src/index.ts", "export const reset = true;")
+    ];
+
+    const graph = buildImportGraph(files);
+
+    expect([...(graph.imports.get("apps/web/page.ts") ?? [])]).toEqual(["packages/auth/src/index.ts"]);
+  });
+
+  it("resolves strict-JSON tsconfig path aliases", () => {
+    const files = [
+      codeFile("apps/web/page.ts", 'import { reset } from "@auth/reset";'),
+      codeFile("tsconfig.json", JSON.stringify({ compilerOptions: { baseUrl: ".", paths: { "@auth/*": ["packages/auth/src/*"] } } })),
+      codeFile("packages/auth/src/reset.ts", "export const reset = true;")
+    ];
+
+    const graph = buildImportGraph(files);
+
+    expect([...(graph.imports.get("apps/web/page.ts") ?? [])]).toEqual(["packages/auth/src/reset.ts"]);
+  });
+
+  it("reports when the graph file budget truncates parseable modules", () => {
+    const files = Array.from({ length: 5_001 }, (_, index) =>
+      codeFile(`src/module-${index}.ts`, `export const module${index} = ${index};`)
+    );
+
+    const graph = buildImportGraph(files);
+
+    expect(graph.truncatedFiles).toBe(1);
+  });
 });
 
 describe("findImportProximity", () => {
diff --git a/packages/core/test/languages.test.ts b/packages/core/test/languages.test.ts
index f02b5d5..dbbc986 100644
--- a/packages/core/test/languages.test.ts
+++ b/packages/core/test/languages.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { detectPrimaryLanguage } from "../src/languages.js";
+import { detectPrimaryLanguage, manifestTestCommand } from "../src/languages.js";
 import { buildReportFromRepo, buildTestRoutes } from "../src/report.js";
 import type { RepoFile, RepoMap } from "../src/types.js";
 
@@ -50,7 +50,11 @@ describe("detectPrimaryLanguage", () => {
     ["Cargo.toml", "src/lib.rs", "rust"],
     ["pyproject.toml", "src/app.py", "python"],
     ["setup.py", "src/app.py", "python"],
-    ["package.json", "src/index.ts", "node"]
+    ["package.json", "src/index.ts", "node"],
+    ["Gemfile", "lib/app.rb", "ruby"],
+    ["composer.json", "src/App.php", "php"],
+    ["pom.xml", "src/App.java", "java"],
+    ["App.csproj", "src/App.cs", "dotnet"]
   ])("reads %s as declaring the language", (manifest, source, expected) => {
     const repo = repoOf([file(manifest, { isSource: false, kind: "config" }), file(source)]);
 
@@ -156,6 +160,32 @@ describe("test routing beyond package scripts", () => {
     expect(report.diagnostics.find((entry) => entry.code === "no-test-route")?.message).toContain("tox");
   });
 
+  it("does not let a nested tox.ini override a shallower Python configuration", () => {
+    const repo = repoOf([
+      file("pyproject.toml", { isSource: false, kind: "config" }),
+      file("tools/legacy/tox.ini", { isSource: false, kind: "config" }),
+      file("src/app.py")
+    ]);
+
+    const report = buildReportFromRepo(repo, { issueText: "app fails to start" });
+
+    expect(report.diagnostics.find((entry) => entry.code === "no-test-route")?.message).toContain("pytest");
+    expect(report.diagnostics.find((entry) => entry.code === "no-test-route")?.message).not.toContain("`tox`");
+  });
+
+  it("recomputes the Rust manifest instead of trusting a stale package directory", () => {
+    const files = [
+      file("Cargo.toml", { isSource: false, kind: "config" }),
+      file("crates/parser/Cargo.toml", { isSource: false, kind: "config" }),
+      file("crates/parser/src/lib.rs")
+    ];
+
+    expect(manifestTestCommand("rust", "crates/missing", files)).toEqual({
+      command: "cargo test",
+      reason: "Cargo.toml at the repository root"
+    });
+  });
+
   it("does not call a Rust repository Python in the no-test-route warning", () => {
     // The wording bug, asserted at the level a reader would hit it. This repository has
     // no Cargo.toml-based route because no context file is ranked under a crate.
diff --git a/packages/core/test/plan.test.ts b/packages/core/test/plan.test.ts
index 33849a2..6721b7a 100644
--- a/packages/core/test/plan.test.ts
+++ b/packages/core/test/plan.test.ts
@@ -3,6 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { buildFixMapReport } from "../src/plan.js";
+import { renderMarkdownReport } from "../src/report.js";
 
 async function createAuthFixture(): Promise<string> {
   const root = await mkdtemp(join(tmpdir(), "fixmap-plan-"));
@@ -77,6 +78,20 @@ describe("buildFixMapReport", () => {
     expect(report.diagnostics.find((entry) => entry.code === "paths-excluded")?.severity).toBe("warning");
   });
 
+  it("renders exclusion globs as code instead of live markdown", async () => {
+    const root = await createAuthFixture();
+
+    const report = await buildFixMapReport({
+      repoRoot: root,
+      issueText: "password reset emails fail",
+      exclude: ["**/_x_/**"]
+    });
+    const markdown = renderMarkdownReport(report);
+
+    expect(markdown).toContain("`**/_x_/**`");
+    expect(markdown).not.toContain("paths: **/_x_/**");
+  });
+
   it("does not let a giant task token become a giant diagnostic", async () => {
     const root = await createAuthFixture();
     // A pasted blob with no spaces, which used to travel verbatim into the message and
@@ -154,7 +169,8 @@ describe("buildFixMapReport", () => {
       issueText: "improve error handling"
     });
 
-    expect(report.contextFiles).toEqual([]);
+    expect(report.contextFiles).toHaveLength(3);
+    expect(report.contextFiles.every((file) => file.confidence === "low")).toBe(true);
     expect(report.diagnostics.map((entry) => entry.code)).toContain("vague-task");
     expect(report.analysis?.nextAction).toContain("Add a concrete");
   });
diff --git a/packages/core/test/rank.test.ts b/packages/core/test/rank.test.ts
index af2fd42..0789d3f 100644
--- a/packages/core/test/rank.test.ts
+++ b/packages/core/test/rank.test.ts
@@ -1,7 +1,29 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { rankContextFiles, REPORT_SCORE_CUTOFF } from "../src/rank.js";
 import type { RepoMap } from "../src/types.js";
 
+function codeFile(path: string, textSample: string): RepoMap["files"][number] {
+  const extension = /\.[^.]+$/.exec(path)?.[0] ?? "";
+  return { path, extension, sizeBytes: textSample.length, isSource: true, isTest: false, kind: "code", textSample };
+}
+
+function documentationFile(path: string, textSample: string): RepoMap["files"][number] {
+  const extension = /\.[^.]+$/.exec(path)?.[0] ?? "";
+  return { path, extension, sizeBytes: textSample.length, isSource: true, isTest: false, kind: "documentation", textSample };
+}
+
+function repoWith(files: RepoMap["files"], options: { root?: string; changedFiles?: string[] } = {}): RepoMap {
+  return {
+    root: options.root ?? "/repo",
+    packageScripts: [],
+    changedFiles: options.changedFiles ?? [],
+    diffText: "",
+    packageManager: "npm",
+    diagnostics: [],
+    files
+  };
+}
+
 describe("rankContextFiles", () => {
   it("lets an exact definition site beat vocabulary-dense consumers", () => {
     const repo: RepoMap = {
@@ -87,6 +109,17 @@ describe("rankContextFiles", () => {
     expect(ranked[0]?.reasons).toContain("defines symbols matching task terms: buildTestRoutes");
   });
 
+  it("prefers a path where multiple task terms converge over a generic sibling", () => {
+    const ranked = rankContextFiles(repoWith([
+      codeFile("lib/reporters/html.js", "export function escape() { return 'reporter escape'; }"),
+      codeFile("lib/reporters/xunit.js", "export function escape() { return 'xunit reporter xml'; }")
+    ]), { issueText: "xunit reporter emits invalid XML" });
+
+    expect(ranked[0]?.path).toBe("lib/reporters/xunit.js");
+    expect(ranked[0]?.reasons).toContain("multiple task terms converge in the file path");
+    expect(ranked[0]?.reasons).toContain("file module name exactly matches a task term");
+  });
+
   it("prioritizes files whose paths overlap the issue text and changed files", () => {
     const repo: RepoMap = {
       root: "/repo",
@@ -659,6 +692,7 @@ describe("rankContextFiles", () => {
     expect(presentationTask[0]?.path).toBe("styles/discount.css");
     expect(presentationTask[0]?.reasons)
       .not.toContain("presentation or demo surface deprioritized for a non-UI implementation task");
+    expect(presentationTask[0]?.reasons).toContain("presentation surface matches a UI-focused task");
   });
 
   it("keeps documentation noise below matching code unless the task targets docs", () => {
@@ -1455,6 +1489,16 @@ describe("rankContextFiles", () => {
     expect(ranked[1]?.confidence).toBe(ranked[0]?.confidence);
   });
 
+  it("caps a vocabulary-only leader at medium even when it has a wide score lead", () => {
+    const ranked = rankContextFiles(repoWith([
+      codeFile("src/flags.ts", "export function hasFlag() { return 'flag release build test flag'; }"),
+      codeFile("src/other.ts", "export function unrelated() { return false; }")
+    ]), { issueText: "add a skip-tests flag for release builds" });
+
+    expect(ranked[0]?.path).toBe("src/flags.ts");
+    expect(ranked[0]?.confidence).toBe("medium");
+  });
+
   it("caps a vocabulary-dense lead that a definition site disputes", () => {
     const repo: RepoMap = {
       root: "/repo",
@@ -1502,4 +1546,205 @@ describe("rankContextFiles", () => {
     // The definition site keeps its own standing: that evidence is why it is here.
     expect(ranked.find((file) => file.path === "src/constant.js")?.confidence).toBe("high");
   });
+
+  it.each([
+    ["internal/auth/token.go", "func"],
+    ["Sources/Auth/Token.swift", "func"],
+    ["src/main/kotlin/Token.kt", "fun"]
+  ])("#500 recognizes %s %s declarations as definition sites", (path, keyword) => {
+    const ranked = rankContextFiles(
+      repoWith([codeFile(path, `${keyword} resolveToken(id string) string { return id }`)]),
+      { issueText: "resolveToken returns the wrong value" }
+    );
+
+    expect(ranked[0]?.reasons).toContain("defines task identifiers: resolveToken");
+  });
+
+  it("#501 caps changed-file confidence when the task is vague", () => {
+    const ranked = rankContextFiles(
+      repoWith([codeFile("src/a.ts", "export const value = 1")], { changedFiles: ["src/a.ts"] }),
+      { issueText: "improve the codebase" }
+    );
+
+    expect(ranked[0]?.confidence).toBe("low");
+  });
+
+  it("#502 rejects absolute file mentions from another repository", () => {
+    const ranked = rankContextFiles(
+      repoWith([
+        codeFile("index.js", "export const unrelated = 1"),
+        codeFile("src/real.js", "export function resolveCrash() { return true }")
+      ], { root: "/home/me/current-project" }),
+      { issueText: "resolveCrash fails in /home/other/different-project/index.js" }
+    );
+
+    expect(ranked.find((entry) => entry.path === "index.js")?.reasons ?? [])
+      .not.toContain("explicitly named in the task");
+    expect(ranked[0]?.path).toBe("src/real.js");
+  });
+
+  it("still recognizes an absolute file mention inside the scanned repository", () => {
+    const ranked = rankContextFiles(
+      repoWith([codeFile("src/auth.ts", "export const value = 1")], { root: "/home/me/current-project" }),
+      { issueText: "inspect /home/me/current-project/src/auth.ts" }
+    );
+
+    expect(ranked[0]?.reasons).toContain("explicitly named in the task");
+  });
+
+  it("#503 does not treat a clipboard copy button as documentation work", () => {
+    const ranked = rankContextFiles(repoWith([
+      codeFile("src/copy-command.ts", "export function updateCopyButtonHandler() {}"),
+      documentationFile("README.md", "update the copy button handler")
+    ]), { issueText: "update the copy button handler" });
+
+    expect(ranked.find((entry) => entry.path === "README.md")?.reasons ?? [])
+      .not.toContain("documentation-focused task");
+    expect(ranked[0]?.path).toBe("src/copy-command.ts");
+  });
+
+  it("#504 keeps maintained benchmark source rankable without a benchmark keyword", () => {
+    const ranked = rankContextFiles(
+      repoWith([codeFile("benchmarks/runner.ts", "export function resolveToken() { return true }")]),
+      { issueText: "resolveToken is broken" }
+    );
+
+    expect(ranked[0]?.path).toBe("benchmarks/runner.ts");
+  });
+
+  it("#505 does not penalize a project file merely because it is named sample-repo", () => {
+    const ranked = rankContextFiles(repoWith([
+      codeFile("src/sample-repo.ts", "export function resolveToken() { return true }"),
+      codeFile("src/other-name.ts", "export function resolveToken() { return true }")
+    ]), { issueText: "resolveToken is broken" });
+
+    expect(ranked[0]?.score).toBe(ranked[1]?.score);
+    expect(ranked.find((entry) => entry.path === "src/sample-repo.ts")?.reasons)
+      .not.toContain("presentation or demo surface deprioritized for a non-UI task");
+  });
+
+  it("#506 uses import proximity for a descriptive prose task without a code identifier", () => {
+    const ranked = rankContextFiles(repoWith([
+      codeFile("src/reset.ts", "export const passwordResetEmail = 'delivered';"),
+      codeFile("src/transport.ts", "import './reset'; export const transport = true;")
+    ]), { issueText: "password reset emails are never delivered" });
+
+    expect(ranked.find((entry) => entry.path === "src/transport.ts")?.reasons.some((reason) =>
+      reason.includes("ranked file src/reset.ts")
+    )).toBe(true);
+  });
+
+  it("#507 keeps task-matched definition evidence when the task includes presentation vocabulary", () => {
+    const ranked = rankContextFiles(
+      repoWith([codeFile("src/validation.ts", "export function validateForm() { return true }")]),
+      { issueText: "form validation rejects the right payload" }
+    );
+
+    expect(ranked[0]?.reasons).toContain("defines symbols matching task terms: validateForm");
+  });
+
+  it("#508 counts each exact task literal once instead of once per file and sort comparison", () => {
+    const fragments = ["FIRST_EXACT_FAILURE", "SECOND_EXACT_FAILURE"];
+    const originalSplit = String.prototype.split;
+    let occurrenceScans = 0;
+    const splitSpy = vi.spyOn(String.prototype, "split").mockImplementation(function (
+      this: string,
+      separator: string | RegExp,
+      limit?: number
+    ) {
+      if (typeof separator === "string" && fragments.includes(separator)) occurrenceScans += 1;
+      return originalSplit.call(this, separator, limit);
+    });
+
+    try {
+      rankContextFiles(
+        repoWith(Array.from({ length: 20 }, (_, index) => codeFile(
+          `src/file-${index}.ts`,
+          `export const value${index} = '${fragments[index % fragments.length]}';`
+        ))),
+        { issueText: `failure contains \`${fragments[0]}\` and \`${fragments[1]}\`` }
+      );
+      expect(occurrenceScans).toBe(fragments.length);
+    } finally {
+      splitSpy.mockRestore();
+    }
+  });
+
+  it("#509 precompiles member patterns and expands regex tokens once per candidate file", () => {
+    const NativeRegExp = RegExp;
+    const constructedPatterns: string[] = [];
+    const proxiedRegExp = new Proxy(NativeRegExp, {
+      construct(target, args) {
+        constructedPatterns.push(String(args[0]));
+        return Reflect.construct(target, args);
+      }
+    });
+    const originalMatchAll = String.prototype.matchAll;
+    let regexTokenScans = 0;
+    const matchAllSpy = vi.spyOn(String.prototype, "matchAll").mockImplementation(function (
+      this: string,
+      regexp: RegExp
+    ) {
+      if (regexp.source === "\\b([A-Za-z])\\{(\\d+),(\\d+)\\}") regexTokenScans += 1;
+      return originalMatchAll.call(this, regexp);
+    });
+    vi.stubGlobal("RegExp", proxiedRegExp);
+
+    try {
+      const files = Array.from({ length: 20 }, (_, index) => codeFile(
+        `src/file-${index}.ts`,
+        `export const pattern${index} = /a{3,5}/; config.timeout = user.email;`
+      ));
+      rankContextFiles(repoWith(files), { issueText: "config.timeout and user.email are wrong" });
+
+      expect(constructedPatterns.filter((pattern) => pattern.includes("timeout") || pattern.includes("email")))
+        .toHaveLength(2);
+      expect(regexTokenScans).toBe(files.length);
+    } finally {
+      vi.unstubAllGlobals();
+      matchAllSpy.mockRestore();
+    }
+  });
+
+  it("prefers the interactive surface for a user-flow task over a metadata wrapper", () => {
+    const ranked = rankContextFiles(repoWith([
+      codeFile("app/demo/page.tsx", "export function DemoPage() { return <Demo />; }"),
+      codeFile("app/demo.tsx", "export function Demo() { const [task] = useState(''); return <input onChange={() => task} />; }")
+    ]), { issueText: "the website demo should let visitors enter a task" });
+
+    expect(ranked[0]?.path).toBe("app/demo.tsx");
+    expect(ranked[0]?.reasons).toContain("interactive presentation surface matches the requested user flow");
+  });
+
+  it("#512 boosts a lowercase definition named plainly in the task", () => {
+    const ranked = rankContextFiles(
+      repoWith([codeFile("src/validation.ts", "export function validate() { return true }")]),
+      { issueText: "validate rejects the right payload" }
+    );
+
+    expect(ranked[0]?.reasons).toContain("defines symbols matching task terms: validate");
+  });
+
+  it("uses an exact quoted error message as ranking evidence", () => {
+    const ranked = rankContextFiles(repoWith([
+      codeFile("src/error.ts", "throw new Error('Cannot read properties of undefined')"),
+      codeFile("src/other.ts", "export const login = true")
+    ]), { issueText: 'login throws "Cannot read properties of undefined"' });
+
+    expect(ranked[0]?.path).toBe("src/error.ts");
+    expect(ranked[0]?.reasons.some((reason) => reason.startsWith("contains exact task literal:"))).toBe(true);
+  });
+
+  it("ranks Unicode identifiers and task vocabulary instead of returning an empty map", () => {
+    const ranked = rankContextFiles(
+      repoWith([
+        codeFile("src/login.ts", "export function 修复登录错误() { return true; }"),
+        codeFile("src/other.ts", "export function unrelated() { return false; }")
+      ]),
+      { issueText: "修复登录错误() 失败" }
+    );
+
+    expect(ranked[0]?.path).toBe("src/login.ts");
+    expect(ranked[0]?.reasons).toContain("defines task identifiers: 修复登录错误");
+  });
 });
diff --git a/packages/core/test/render-demo-wrap.test.mjs b/packages/core/test/render-demo-wrap.test.mjs
index 905e196..1166cbe 100644
--- a/packages/core/test/render-demo-wrap.test.mjs
+++ b/packages/core/test/render-demo-wrap.test.mjs
@@ -14,4 +14,11 @@ describe("render-demo line wrapping", () => {
   it("prefers whitespace boundaries for ordinary prose", () => {
     expect(wrapLine("alpha beta gamma", 10)).toEqual(["alpha beta", "    gamma"]);
   });
+
+  it("keeps emoji graphemes intact and rejects invalid widths", () => {
+    const rows = wrapLine("🔒🔑🧪 secure", 4);
+    expect(rows.some((row) => /(?:[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF])/.test(row))).toBe(false);
+    expect(rows.flatMap((row) => [...row]).filter((character) => character === "🧪")).toHaveLength(1);
+    expect(() => wrapLine("text", 0)).toThrow("positive whole number");
+  });
 });
diff --git a/packages/core/test/repo-scan.test.ts b/packages/core/test/repo-scan.test.ts
index 609b25a..203e9a9 100644
--- a/packages/core/test/repo-scan.test.ts
+++ b/packages/core/test/repo-scan.test.ts
@@ -90,9 +90,13 @@ describe("scanRepo", () => {
     expect(dockerfile?.textSample).toContain("FROM node:24");
   });
 
-  it("recognizes Go, Python, and TypeScript declaration test naming conventions", async () => {
+  it("recognizes Go, Python, Ruby, Java, C#, PHP, and TypeScript test naming conventions", async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-test-patterns-"));
-    for (const path of ["handler_test.go", "test_reset.py", "reset_test.py", "types.test-d.ts"]) {
+    await mkdir(join(root, "spec"), { recursive: true });
+    for (const path of [
+      "handler_test.go", "test_reset.py", "reset_test.py", "types.test-d.ts",
+      "account_spec.rb", "spec/session.rb", "AccountTest.java", "AccountTests.cs", "AccountTest.php"
+    ]) {
       await writeFile(join(root, path), "test reset handler\n");
     }
 
@@ -100,10 +104,26 @@ describe("scanRepo", () => {
 
     expect(repo.files.filter((file) => file.isTest).map((file) => file.path).sort()).toEqual([
       "handler_test.go",
+      "AccountTest.java",
+      "AccountTest.php",
+      "AccountTests.cs",
+      "account_spec.rb",
       "reset_test.py",
+      "spec/session.rb",
       "test_reset.py",
       "types.test-d.ts"
-    ]);
+    ].sort());
+  });
+
+  it("normalizes uppercase extensions before source classification", async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-uppercase-extension-"));
+    await writeFile(join(root, "B.TS"), "export const uppercaseSource = true;\n");
+    await writeFile(join(root, "README.MD"), "Uppercase documentation\n");
+
+    const repo = await scanRepo({ repoRoot: root });
+
+    expect(repo.files.find((file) => file.path === "B.TS")).toMatchObject({ extension: ".ts", isSource: true, kind: "code" });
+    expect(repo.files.find((file) => file.path === "README.MD")).toMatchObject({ extension: ".md", isSource: true, kind: "documentation" });
   });
 
   it("discovers workspace scripts and the package manager", async () => {
@@ -243,6 +263,34 @@ describe("scanRepo", () => {
     expect(repo.diffText).toContain("login = () => false");
   });
 
+  it("samples complete added lines from every file when a diff exceeds the signal budget", { timeout: 30_000 }, async () => {
+    const root = await mkdtemp(join(tmpdir(), "fixmap-large-diff-"));
+    await mkdir(join(root, "src"), { recursive: true });
+    for (const name of ["alpha.ts", "middle.ts", "omega.ts"]) {
+      await writeFile(join(root, "src", name), "export const original = true;\n");
+    }
+    await exec("git", ["init", "-b", "main"], { cwd: root });
+    await exec("git", ["config", "user.email", "test@example.com"], { cwd: root });
+    await exec("git", ["config", "user.name", "Test User"], { cwd: root });
+    await exec("git", ["add", "."], { cwd: root });
+    await exec("git", ["commit", "-m", "initial"], { cwd: root });
+
+    for (const name of ["alpha.ts", "middle.ts", "omega.ts"]) {
+      const marker = name.replace(".ts", "Signal");
+      const body = [`export const ${marker} = true;`, ...Array.from({ length: 5_000 }, (_, index) => `export const ${marker}${index} = ${index};`)].join("\n");
+      await writeFile(join(root, "src", name), `${body}\n`);
+    }
+
+    const repo = await scanRepo({ repoRoot: root, diffSpec: "HEAD" });
+
+    expect(repo.diagnostics).toContainEqual(expect.objectContaining({ code: "diff-text-truncated", severity: "warning" }));
+    expect(repo.diffText.length).toBeLessThanOrEqual(200_000);
+    expect(repo.diffText).toContain("alphaSignal");
+    expect(repo.diffText).toContain("middleSignal");
+    expect(repo.diffText).toContain("omegaSignal");
+    expect(repo.diffText.split("\n").every((line) => line.startsWith("+"))).toBe(true);
+  });
+
   it("uses the scanned subdirectory as the path base for diff results", { timeout: 30_000 }, async () => {
     const root = await mkdtemp(join(tmpdir(), "fixmap-subdirectory-diff-"));
     const packageRoot = join(root, "packages", "core");
@@ -375,7 +423,7 @@ describe("scanRepo", () => {
     expect(weird?.textSample).toBe("");
     expect(weird?.textSampleComplete).toBe(false);
     expect(weird?.textSampleSkipReason).toBe("not-text");
-    const diagnostic = repo.diagnostics.find((entry) => entry.code === "content-unread");
+    const diagnostic = repo.diagnostics.find((entry) => entry.code === "content-not-utf8");
     expect(diagnostic?.message).toContain("not UTF-8 text");
     expect(diagnostic?.message).not.toContain("Files over");
     expect(diagnostic?.paths).toContain("src/weird.ts");
@@ -386,7 +434,7 @@ describe("scanRepo", () => {
     await writeFile(join(root, "history.ts"), "x".repeat(64_001));
 
     const repo = await scanRepo({ repoRoot: root });
-    const diagnostic = repo.diagnostics.find((entry) => entry.code === "content-unread");
+    const diagnostic = repo.diagnostics.find((entry) => entry.code === "content-too-large");
 
     expect(diagnostic?.message).toContain("history.ts (65 kB)");
     expect(diagnostic?.message).toContain("Files over 64 kB");
diff --git a/packages/core/test/report.test.ts b/packages/core/test/report.test.ts
index 2af5643..da82d71 100644
--- a/packages/core/test/report.test.ts
+++ b/packages/core/test/report.test.ts
@@ -94,7 +94,7 @@ describe("report rendering", () => {
     const risks = buildRiskNotes(["src/auth/reset-password.ts"]);
 
     expect(routes[0]?.relatedFiles).toEqual(["test/auth/reset-password.test.ts"]);
-    expect(routes.map((route) => route.command)).toEqual(["npm run test", "npm run typecheck"]);
+    expect(routes.map((route) => route.command)).toEqual(["npm run test"]);
     expect(risks[0]?.area).toBe("authentication");
     expect(risks[0]?.severity).toBe("low");
     expect(risks[0]?.reason).toContain("no diff evidence");
@@ -239,7 +239,32 @@ describe("report rendering", () => {
     expect(routes[0]?.command).toBe("npm run test");
     expect(routes[0]?.relatedFiles).toContain("packages/core/test/rank.test.ts");
   });
-it("ignores demo code when deriving risk, but trusts a changed file anywhere", () => {
+  it("does not route lint or typecheck scripts as tests", () => {
+    const repo: RepoMap = {
+      root: "/repo",
+      packageManager: "npm",
+      changedFiles: [],
+      diffText: "",
+      diagnostics: [],
+      packageScripts: [
+        { name: "lint", command: "eslint .", packageDir: "" },
+        { name: "typecheck", command: "tsc --noEmit", packageDir: "" }
+      ],
+      files: [
+        { path: "src/auth.ts", extension: ".ts", sizeBytes: 10, isSource: true, isTest: false, kind: "code", textSample: "" }
+      ]
+    };
+
+    expect(buildTestRoutes(repo, ["src/auth.ts"])).toEqual([]);
+  });
+
+  it("keeps billing, package, and public API risk triggers reachable", () => {
+    expect(buildRiskNotes(["src/billing/invoice.ts"])).toContainEqual(expect.objectContaining({ area: "billing" }));
+    expect(buildRiskNotes(["package.json"])).toContainEqual(expect.objectContaining({ area: "dependencies" }));
+    expect(buildRiskNotes(["src/public/api.ts"])).toContainEqual(expect.objectContaining({ area: "public-api" }));
+  });
+
+  it("ignores demo code when deriving risk, but trusts a changed file anywhere", () => {
     // Express ships examples/auth/. Reading it for risk turned a deprioritized demo
     // file into a high-severity authentication note on a request-parsing task.
     expect(buildRiskNotes(["examples/auth/index.js"], [])).toEqual([]);
diff --git a/packages/core/test/signals.test.ts b/packages/core/test/signals.test.ts
index 0277438..157815a 100644
--- a/packages/core/test/signals.test.ts
+++ b/packages/core/test/signals.test.ts
@@ -11,7 +11,7 @@ describe("extractTaskSignals", () => {
     expect([...signals.fileMentions].map((mention) => mention.toLowerCase())).toContain(expected);
   });
 
-  it("tokenizes only added and removed diff lines, not diff metadata", () => {
+  it("#515 tokenizes only added diff lines, not removed content or diff metadata", () => {
     const diffText = [
       "diff --git a/src/auth/reset-password.ts b/src/auth/reset-password.ts",
       "index 1234567..89abcde 100644",
@@ -27,6 +27,7 @@ describe("extractTaskSignals", () => {
 
     expect(signals.tokens.has("token")).toBe(true);
     expect(signals.tokens.has("expiry")).toBe(true);
+    expect(signals.tokens.has("old")).toBe(false);
     expect(signals.tokens.has("index")).toBe(false);
     expect(signals.tokens.has("diff")).toBe(false);
     expect(signals.tokens.has("git")).toBe(false);
@@ -43,6 +44,69 @@ describe("extractTaskSignals", () => {
     expect(signals.tokens.has("email")).toBe(true);
   });
 
+  it("#514 recognizes member names on arbitrary receivers", () => {
+    const signals = extractTaskSignals({ issueText: "config.timeout and user.email are wrong" });
+
+    expect(signals.memberMentions).toEqual(new Set(["timeout", "email"]));
+  });
+
+  it("#510 keeps exact quoted error messages and screaming-snake error codes", () => {
+    const signals = extractTaskSignals({
+      issueText: 'login throws "Cannot read properties of undefined" and `ERR_INVALID_ARG_TYPE`'
+    });
+
+    expect(signals.exactFragments).toContain("Cannot read properties of undefined");
+    expect(signals.exactFragments).toContain("ERR_INVALID_ARG_TYPE");
+  });
+
+  it("#516 does not let contractions swallow a later quoted fragment", () => {
+    const signals = extractTaskSignals({ issueText: "it isn't reading `reset-token.ts` correctly" });
+
+    expect(signals.exactFragments).toContain("reset-token.ts");
+  });
+
+  it("extracts explicitly called lowercase function names", () => {
+    const signals = extractTaskSignals({ issueText: "validate() rejects the correct payload" });
+
+    expect(signals.identifiers).toContain("validate");
+  });
+
+  it("does not mistake an ordinary prose word before a spaced parenthesis for a function call", () => {
+    const signals = extractTaskSignals({ issueText: "the status code (as logged by the service) is wrong" });
+
+    expect(signals.identifiers).not.toContain("code");
+  });
+
+  it.each(["delete", "get", "run", "default", "name", "type", "case"])(
+    "#513 keeps ordinary task word %j searchable",
+    (word) => expect(tokenizeText(word)).toContain(word)
+  );
+
+  it.each(["ci", "ui", "public", "package", "kubernetes"])(
+    "keeps product and risk vocabulary %j searchable",
+    (word) => expect(tokenizeText(word)).toContain(word)
+  );
+
+  it("normalizes hosting to the same searchable deployment token as hosted", () => {
+    expect(tokenizeText("hosting")).toEqual(tokenizeText("hosted"));
+    expect(tokenizeText("hosting")).toContain("host");
+  });
+
+  it.each(["SCSS", "Sass", "Less"])("normalizes %s tasks to CSS paths", (word) => {
+    expect(tokenizeText(word)).toContain("css");
+  });
+
+  it("tokenizes non-ASCII task text and recognizes a Unicode function name", () => {
+    const signals = extractTaskSignals({
+      issueText: "修复登录错误 обновитьПрофиль() αποτυγχάνει"
+    });
+
+    expect(signals.tokens.size).toBeGreaterThan(0);
+    expect(signals.tokens).toContain("修复登录错误");
+    expect(signals.identifiers).toContain("обновитьПрофиль");
+    expect(signals.tokens).toContain("αποτυγχάνει");
+  });
+
   it("normalizes simple plural and verb forms", () => {
     const signals = extractTaskSignals({ issueText: "Invoices are created for users" });
 
@@ -75,7 +139,7 @@ describe("extractTaskSignals", () => {
     ["contributor", "contribute"],
     ["invoices", "invoice"],
     ["resolved", "resolve"]
-  ])("normalizes %s to the same token as %s", (inflected, base) => {
+  ])("#511/#517 normalizes %s to the same token as %s", (inflected, base) => {
     const inflectedSignals = extractTaskSignals({ issueText: inflected });
     const baseSignals = extractTaskSignals({ issueText: base });
 
@@ -108,6 +172,27 @@ describe("extractTaskSignals", () => {
     expect(signals.tokens).toContain("window");
   });
 
+  it("never extracts URL credentials or path secrets as reportable identifiers", () => {
+    const secret = "superSecretCredentialXYZ";
+    const signals = extractTaskSignals({
+      issueText: `request fails at "https://user:${secret}@api.example.test/${secret}?token=${secret}"`
+    });
+
+    expect([...signals.identifiers].join(" ")).not.toContain(secret);
+    expect(signals.exactFragments.join(" ")).not.toContain(secret);
+    expect([...signals.tokens].join(" ")).not.toContain(secret.toLowerCase());
+  });
+
+  it("ignores issue-template instructions hidden in HTML comments", () => {
+    const signals = extractTaskSignals({
+      issueText: "xunit output is invalid XML\n<!-- Read .github/CODE_OF_CONDUCT.md before filing -->"
+    });
+
+    expect(signals.fileMentions).not.toContain(".github/CODE_OF_CONDUCT.md");
+    expect(signals.tokens).not.toContain("conduct");
+    expect(signals.tokens).toContain("xunit");
+  });
+
   it("preserves file paths from immutable GitHub blob permalinks", () => {
     const signals = extractTaskSignals({
       issueText:
@@ -239,4 +324,13 @@ describe("plural and verb stems that are part of the word", () => {
   ])("converges %j and %j on one stem", (base, inflected) => {
     expect([...tokenizeText(inflected)]).toEqual([...tokenizeText(base)]);
   });
+
+  it.each([
+    ["validate", "validated"], ["generate", "generated"], ["migrate", "migrated"],
+    ["escape", "escaped"], ["merge", "merged"], ["include", "included"],
+    ["replace", "replaced"], ["compute", "computed"], ["handle", "handled"],
+    ["store", "stored"], ["close", "closed"], ["query", "queried"]
+  ])("converges silent-e or -ied forms %j and %j", (base, inflected) => {
+    expect([...tokenizeText(inflected)]).toEqual([...tokenizeText(base)]);
+  });
 });
diff --git a/packages/core/test/test-gates.test.ts b/packages/core/test/test-gates.test.ts
index 11e72b3..ee19865 100644
--- a/packages/core/test/test-gates.test.ts
+++ b/packages/core/test/test-gates.test.ts
@@ -48,6 +48,19 @@ describe("findGatedTestDiagnostics", () => {
     expect(findGatedTestDiagnostics([plain], ["tests/auth.test.ts"])).toEqual([]);
     expect(findGatedTestDiagnostics([gatedButUnrouted], ["tests/auth.test.ts"])).toEqual([]);
   });
+
+  it.each([
+    ["it.skip('disabled', () => {})", "JavaScript it.skip"],
+    ["xdescribe('disabled', () => {})", "JavaScript xdescribe"],
+    ["@pytest.mark.skip\ndef test_disabled(): pass", "pytest marker"],
+    ["func TestX(t *testing.T) { t.Skip() }", "Go t.Skip"],
+    ["#[ignore]\nfn disabled() {}", "Rust ignore"]
+  ])("reports unconditional %s gates (%s)", (textSample) => {
+    const gated = testFile("tests/disabled.test.ts", textSample);
+    const diagnostics = findGatedTestDiagnostics([gated], [gated.path]);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.message).toContain("skipped or ignored tests");
+  });
 });
 
 describe("script classification and route ordering", () => {
diff --git a/packages/core/test/verify.test.ts b/packages/core/test/verify.test.ts
index b1b1d3e..c77fd11 100644
--- a/packages/core/test/verify.test.ts
+++ b/packages/core/test/verify.test.ts
@@ -90,6 +90,40 @@ describe("verifyPlan", () => {
     expect(result.summary).toContain("plan and repository do not match");
   });
 
+  it("treats a changed missing path as a planned deletion, not a wrong repository", () => {
+    const repo = repoWith(["src/auth/reset-password.ts"]);
+    repo.files = files.filter((file) => file.path !== "src/auth/reset-password.ts");
+
+    const result = verifyPlan(planFor("src/auth/reset-password.ts"), repo);
+
+    expect(result.findings).toContainEqual(expect.objectContaining({
+      code: "planned-file-deleted",
+      severity: "info",
+      paths: ["src/auth/reset-password.ts"]
+    }));
+    expect(result.findings.map((finding) => finding.code)).not.toContain("plan-repository-mismatch");
+  });
+
+  it("warns when only part of a plan is stale after a rebase or rename", () => {
+    const plan = planFor("src/auth/reset-password.ts");
+    plan.contextFiles.push({
+      rank: 2,
+      path: "src/auth/renamed-away.ts",
+      score: 10,
+      confidence: "medium",
+      reasons: []
+    });
+
+    const result = verifyPlan(plan, repoWith(["src/auth/reset-password.ts"]));
+
+    expect(result.findings).toContainEqual(expect.objectContaining({
+      code: "plan-partially-stale",
+      severity: "warning",
+      paths: ["src/auth/renamed-away.ts"]
+    }));
+    expect(result.findings.map((finding) => finding.code)).not.toContain("plan-repository-mismatch");
+  });
+
   it("names files the change needed that the plan never ranked", () => {
     const result = verifyPlan(
       planFor("src/auth/reset-password.ts"),
@@ -183,6 +217,15 @@ describe("verifyPlan", () => {
     expect(markdown).toContain("`dist/auth/reset-password.js`");
   });
 
+  it("uses a longer code fence for paths containing backticks", () => {
+    const result = verifyPlan(planFor("src/auth/reset-password.ts"), repoWith(["src/odd`name.ts"]));
+    const markdown = renderVerifyMarkdown(result);
+
+    expect(markdown).toContain("``src/odd`name.ts``");
+    expect(markdown.split("\n")).not.toContain("- `src/odd`name.ts`");
+    expect(markdown.split("\n")).not.toContain("  - `src/odd`name.ts`");
+  });
+
   it("explains an empty diff instead of rendering empty sections", () => {
     const markdown = renderVerifyMarkdown(verifyPlan(planFor("src/auth/reset-password.ts"), repoWith([])));
 
diff --git a/scripts/benchmark-savings.mjs b/scripts/benchmark-savings.mjs
index fac605e..e5b6e47 100644
--- a/scripts/benchmark-savings.mjs
+++ b/scripts/benchmark-savings.mjs
@@ -76,9 +76,9 @@ for (const benchmark of dataset.cases) {
     scannedFiles: repo.files.length,
     medianRuntimeMs: round(median(timings)),
     expected: benchmark.expected,
-    top5: paths,
-    top1: benchmark.expected.includes(paths[0]),
-    top3: benchmark.expected.some((path) => paths.slice(0, 3).includes(path)),
+    top5Paths: paths,
+    top1Hit: benchmark.expected.includes(paths[0]),
+    top3Hit: benchmark.expected.some((path) => paths.slice(0, 3).includes(path)),
     top5Hit: benchmark.expected.some((path) => paths.includes(path)),
     sourceBytes,
     rankedBytes,
@@ -104,8 +104,8 @@ const summary = {
   },
   cases: results.length,
   accuracy: {
-    top1HitRate: hitRate("top1"),
-    top3HitRate: hitRate("top3"),
+    top1HitRate: hitRate("top1Hit"),
+    top3HitRate: hitRate("top3Hit"),
     top5HitRate: hitRate("top5Hit")
   },
   performance: {
diff --git a/scripts/check-action-metadata.mjs b/scripts/check-action-metadata.mjs
index 4e578d2..3b3c26d 100644
--- a/scripts/check-action-metadata.mjs
+++ b/scripts/check-action-metadata.mjs
@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
 
@@ -11,6 +11,10 @@ const expectedRootMetadata = packageMetadata.replace(
   "  main: dist/index.mjs",
   "  main: packages/action/dist/index.mjs"
 );
+if (expectedRootMetadata === packageMetadata) {
+  process.stderr.write('Package Action metadata is missing the exact "  main: dist/index.mjs" entrypoint.\n');
+  process.exit(1);
+}
 
 if (rootMetadata !== expectedRootMetadata) {
   process.stderr.write(
@@ -19,4 +23,11 @@ if (rootMetadata !== expectedRootMetadata) {
   process.exit(1);
 }
 
+const entrypoint = join(repoRoot, "packages", "action", "dist", "index.mjs");
+const metadata = await stat(entrypoint).catch(() => undefined);
+if (!metadata?.isFile()) {
+  process.stderr.write(`Action metadata entrypoint does not resolve to a file: ${entrypoint}\n`);
+  process.exit(1);
+}
+
 process.stdout.write("Root and package Action metadata are synchronized.\n");
diff --git a/scripts/check-generated.mjs b/scripts/check-generated.mjs
new file mode 100644
index 0000000..5326b1c
--- /dev/null
+++ b/scripts/check-generated.mjs
@@ -0,0 +1,76 @@
+import { spawnSync } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+const modes = {
+  action: {
+    paths: ["packages/action/dist/index.mjs"],
+    commands: [["npm", "run", "build:action"]]
+  },
+  rendered: {
+    paths: [
+      "docs/assets/fixmap-cli-demo.svg",
+      "docs/assets/fixmap-benchmark.svg",
+      "examples/reports/declines-fabricated-identifier.md",
+      "examples/reports/declines-vague-task.md",
+      "examples/reports/declines-unmatched-terms.md"
+    ],
+    commands: [
+      ["npm", "run", "render:examples"],
+      ["npm", "run", "build:cli"],
+      [process.execPath, "scripts/render-demo.mjs"],
+      ["npm", "run", "render:benchmark-card"]
+    ]
+  }
+};
+
+const modeName = process.argv[2];
+const mode = modes[modeName];
+if (!mode) {
+  console.error(`Usage: node scripts/check-generated.mjs ${Object.keys(modes).join("|")}`);
+  process.exit(1);
+}
+
+const originals = new Map();
+for (const path of mode.paths) originals.set(path, await readFile(path));
+
+let commandFailure = 0;
+let changed = [];
+try {
+  for (const [command, ...args] of mode.commands) {
+    // Windows cannot execute npm.cmd directly through spawnSync on every supported
+    // Node release. When npm launched this gate, reuse its JavaScript entrypoint
+    // through the current Node executable instead of starting a command shell.
+    const npmEntrypoint = command === "npm" ? process.env.npm_execpath : undefined;
+    const executable = npmEntrypoint ? process.execPath : command;
+    const commandArgs = npmEntrypoint ? [npmEntrypoint, ...args] : args;
+    const result = spawnSync(executable, commandArgs, {
+      stdio: "inherit",
+      shell: !npmEntrypoint && process.platform === "win32" && command === "npm"
+    });
+    if (result.error) throw result.error;
+    if (result.status !== 0) {
+      commandFailure = result.status ?? 1;
+      break;
+    }
+  }
+
+  if (commandFailure === 0) {
+    for (const path of mode.paths) {
+      const generated = await readFile(path);
+      if (!generated.equals(originals.get(path))) changed.push(path);
+    }
+  }
+} finally {
+  for (const [path, contents] of originals) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, contents);
+  }
+}
+
+if (commandFailure !== 0) process.exit(commandFailure);
+if (changed.length > 0) {
+  console.error(`Generated artifacts are stale:\n${changed.map((path) => `- ${path}`).join("\n")}`);
+  process.exit(1);
+}
+console.log(`Generated ${modeName} artifacts match the checked-in files; the worktree was restored.`);
diff --git a/scripts/check-server-manifest.mjs b/scripts/check-server-manifest.mjs
index 685f273..9c2c3ff 100644
--- a/scripts/check-server-manifest.mjs
+++ b/scripts/check-server-manifest.mjs
@@ -37,6 +37,18 @@ if (!npmPackage) {
     `server npm package version ${npmPackage.version} must match CLI version ${cli.version}`
   );
 }
+if (npmPackage) {
+  if (npmPackage.transport?.type !== "stdio") {
+    errors.push("server npm package transport.type must be stdio");
+  }
+  const positional = npmPackage.packageArguments?.filter((argument) => argument?.type === "positional");
+  if (!Array.isArray(positional) || positional.length !== 1 || positional[0]?.value !== "mcp") {
+    errors.push('server npm package must launch the positional "mcp" command');
+  }
+}
+if (typeof server.repository?.url !== "string" || !/^https:\/\/github\.com\/[^/]+\/[^/]+\/?$/i.test(server.repository.url)) {
+  errors.push("server repository.url must be a canonical non-empty GitHub HTTPS URL");
+}
 
 if (errors.length > 0) {
   for (const error of errors) {
diff --git a/scripts/evaluate-baseline.mjs b/scripts/evaluate-baseline.mjs
index bc6e5b2..a3f39e1 100644
--- a/scripts/evaluate-baseline.mjs
+++ b/scripts/evaluate-baseline.mjs
@@ -277,13 +277,13 @@ for (const benchmark of dataset.cases) {
     const row = {
       slug: benchmark.slug,
       mentionsExpectedPath: mention.mentionsExpectedPath,
-      top5: paths,
-      top1: benchmark.expected.includes(paths[0]),
-      top3: benchmark.expected.some((path) => paths.slice(0, 3).includes(path)),
+      top5Paths: paths,
+      top1Hit: benchmark.expected.includes(paths[0]),
+      top3Hit: benchmark.expected.some((path) => paths.slice(0, 3).includes(path)),
       top5Hit: benchmark.expected.some((path) => paths.includes(path))
     };
     perArmResults[arm].push(row);
-    caseRow.arms[arm] = { top5: paths, top1: row.top1, top3: row.top3, top5Hit: row.top5Hit };
+    caseRow.arms[arm] = { top5Paths: paths, top1Hit: row.top1Hit, top3Hit: row.top3Hit, top5Hit: row.top5Hit };
   }
   perCase.push(caseRow);
 }
@@ -294,10 +294,10 @@ function scoreCohort(cohort) {
   const interval = (key) => wilsonInterval(cohort.filter((result) => result[key]).length, cohort.length);
   return {
     cases: cohort.length,
-    top1HitRate: hitRate("top1"),
-    top3HitRate: hitRate("top3"),
+    top1HitRate: hitRate("top1Hit"),
+    top3HitRate: hitRate("top3Hit"),
     top5HitRate: hitRate("top5Hit"),
-    intervals95: { top1: interval("top1"), top3: interval("top3"), top5: interval("top5Hit") }
+    intervals95: { top1: interval("top1Hit"), top3: interval("top3Hit"), top5: interval("top5Hit") }
   };
 }
 
@@ -376,8 +376,8 @@ for (const cohortName of ["all", "unmentioned"]) {
       return [
         arm,
         {
-          top1: mcnemarExact(fixmapRows, pick(arm), "top1"),
-          top3: mcnemarExact(fixmapRows, pick(arm), "top3"),
+          top1: mcnemarExact(fixmapRows, pick(arm), "top1Hit"),
+          top3: mcnemarExact(fixmapRows, pick(arm), "top3Hit"),
           top5: mcnemarExact(fixmapRows, pick(arm), "top5Hit")
         }
       ];
diff --git a/scripts/evaluate-external.mjs b/scripts/evaluate-external.mjs
index d00ad34..faa7c20 100644
--- a/scripts/evaluate-external.mjs
+++ b/scripts/evaluate-external.mjs
@@ -40,7 +40,9 @@ const dataset = JSON.parse(await readFile(join(suiteDir, "dataset.json"), "utf8"
 
 // Floors exist to catch ranking collapses in the scheduled run; they are
 // deliberately below measured performance and must not be treated as targets.
-const FLOORS = { top1: 0.3, top3: 0.5, top5: 0.5 };
+const FLOORS = suite === "heldout"
+  ? { all: { top1: 0.5, top3: 0.583, top5: 0.667 }, unmentioned: { top1: 0.333, top3: 0.444, top5: 0.556 } }
+  : { all: { top1: 0.625, top3: 0.937, top5: 0.937 }, unmentioned: { top1: 0.615, top3: 0.923, top5: 0.923 } };
 
 const results = [];
 for (const benchmark of dataset.cases) {
@@ -56,10 +58,10 @@ for (const benchmark of dataset.cases) {
     slug: benchmark.slug,
     issue: benchmark.issue,
     expected: benchmark.expected,
-    top5: paths,
+    top5Paths: paths,
     topConfidence: ranked[0]?.confidence ?? null,
-    top1: benchmark.expected.includes(paths[0]),
-    top3: benchmark.expected.some((path) => paths.slice(0, 3).includes(path)),
+    top1Hit: benchmark.expected.includes(paths[0]),
+    top3Hit: benchmark.expected.some((path) => paths.slice(0, 3).includes(path)),
     top5Hit: benchmark.expected.some((path) => paths.includes(path)),
     // Derived every run from the same task text the ranker reads, never stored in the
     // dataset, so the cohort split cannot drift away from the case it describes.
@@ -83,7 +85,7 @@ const band = (key) => {
 // A top-3 hit still wastes an agent's first move when something wrong ranks above the
 // answer. Counting those separately keeps the headline rates from hiding the case where
 // FixMap had the right file and buried it.
-const misleadingCases = results.filter((result) => result.top5Hit && !result.top1);
+const misleadingCases = results.filter((result) => result.top5Hit && !result.top1Hit);
 
 // Calibration answers the question a confidence label is supposed to answer:
 // when FixMap says it is confident about the leading file, is that file the one
@@ -96,11 +98,11 @@ const calibration = ["high", "medium", "low"].map((confidence) => {
   return {
     confidence,
     cases: band.length,
-    top1Correct: band.filter((result) => result.top1).length,
+    top1Correct: band.filter((result) => result.top1Hit).length,
     top1Accuracy: band.length === 0
       ? null
-      : Number((band.filter((result) => result.top1).length / band.length).toFixed(3)),
-    interval95: wilsonInterval(band.filter((result) => result.top1).length, band.length)
+      : Number((band.filter((result) => result.top1Hit).length / band.length).toFixed(3)),
+    interval95: wilsonInterval(band.filter((result) => result.top1Hit).length, band.length)
   };
 });
 
@@ -115,10 +117,10 @@ function scoreCohort(cohort) {
   const interval = (key) => wilsonInterval(cohort.filter((result) => result[key]).length, cohort.length);
   return {
     cases: cohort.length,
-    top1HitRate: hitRate("top1"),
-    top3HitRate: hitRate("top3"),
+    top1HitRate: hitRate("top1Hit"),
+    top3HitRate: hitRate("top3Hit"),
     top5HitRate: hitRate("top5Hit"),
-    intervals95: { top1: interval("top1"), top3: interval("top3"), top5: interval("top5Hit") },
+    intervals95: { top1: interval("top1Hit"), top3: interval("top3Hit"), top5: interval("top5Hit") },
     slugs: cohort.map((result) => result.slug)
   };
 }
@@ -132,12 +134,12 @@ const cohorts = {
 
 const summary = {
   cases: results.length,
-  top1HitRate: Number(rate("top1").toFixed(3)),
-  top3HitRate: Number(rate("top3").toFixed(3)),
+  top1HitRate: Number(rate("top1Hit").toFixed(3)),
+  top3HitRate: Number(rate("top3Hit").toFixed(3)),
   top5HitRate: Number(rate("top5Hit").toFixed(3)),
   intervals95: {
-    top1: band("top1").interval95,
-    top3: band("top3").interval95,
+    top1: band("top1Hit").interval95,
+    top3: band("top3Hit").interval95,
     top5: band("top5Hit").interval95
   },
   misleadingTopResult: {
@@ -177,12 +179,17 @@ if (process.argv.includes("--check-recorded")) {
 
 if (
   process.argv.includes("--gate") &&
-  (summary.top1HitRate < FLOORS.top1 ||
-    summary.top3HitRate < FLOORS.top3 ||
-    summary.top5HitRate < FLOORS.top5)
+  (summary.top1HitRate < FLOORS.all.top1 ||
+    summary.top3HitRate < FLOORS.all.top3 ||
+    summary.top5HitRate < FLOORS.all.top5 ||
+    (summary.cohorts.unmentioned.top1HitRate ?? 0) < FLOORS.unmentioned.top1 ||
+    (summary.cohorts.unmentioned.top3HitRate ?? 0) < FLOORS.unmentioned.top3 ||
+    (summary.cohorts.unmentioned.top5HitRate ?? 0) < FLOORS.unmentioned.top5)
 ) {
   process.stderr.write(
-    `${suiteLabel} fell below regression floors: measured top-1=${summary.top1HitRate}, top-3=${summary.top3HitRate}, top-5=${summary.top5HitRate}; required top-1>=${FLOORS.top1}, top-3>=${FLOORS.top3}, top-5>=${FLOORS.top5}.\n`
+    `${suiteLabel} fell below regression floors in the pooled or unmentioned cohort: ` +
+    `pooled top-1=${summary.top1HitRate}, top-3=${summary.top3HitRate}, top-5=${summary.top5HitRate}; ` +
+    `unmentioned top-1=${summary.cohorts.unmentioned.top1HitRate}, top-3=${summary.cohorts.unmentioned.top3HitRate}, top-5=${summary.cohorts.unmentioned.top5HitRate}.\n`
   );
   failed = true;
 }
diff --git a/scripts/evaluate.mjs b/scripts/evaluate.mjs
index 6521fb8..ff9b64e 100644
--- a/scripts/evaluate.mjs
+++ b/scripts/evaluate.mjs
@@ -28,9 +28,9 @@ const results = cases.map((benchmark) => {
     issue: benchmark.issue ?? null,
     task: benchmark.task,
     expected: benchmark.expected,
-    top5: paths,
-    top1: benchmark.expected.includes(paths[0]),
-    top3: benchmark.expected.some((expected) => paths.slice(0, 3).includes(expected)),
+    top5Paths: paths,
+    top1Hit: benchmark.expected.includes(paths[0]),
+    top3Hit: benchmark.expected.some((expected) => paths.slice(0, 3).includes(expected)),
     top5Hit: benchmark.expected.some((expected) => paths.includes(expected))
   };
 });
@@ -50,18 +50,18 @@ function scoreCohort(cohort, floors) {
   };
   return {
     cases: cohort.length,
-    top1: score("top1"),
-    top3: score("top3"),
+    top1: score("top1Hit"),
+    top3: score("top3Hit"),
     top5: score("top5Hit"),
     floors
   };
 }
 
-const legacyFloors = { top1: 0.5, top3: 0.8, top5: 0.8 };
+const legacyFloors = { top1: 0.625, top3: 0.875, top5: 0.875 };
 // These 23 title-only, path-unmentioned cases are a distinct single-repository
 // regression cohort. Their v0.8.7 measurement was much harder than the original
 // eight cases, so report and gate them separately instead of pooling the rates.
-const fixMapIssueFloors = { top1: 0.3, top3: 0.75, top5: 0.85 };
+const fixMapIssueFloors = { top1: 0.34, top3: 0.75, top5: 0.86 };
 const baseline = scoreCohort(results.filter((result) => result.issue === null), legacyFloors);
 const fixMapIssues = scoreCohort(results.filter((result) => result.issue !== null), fixMapIssueFloors);
 const summary = {
@@ -72,9 +72,9 @@ const summary = {
 
 process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
 const failedCohorts = Object.entries(summary.cohorts).filter(([, cohort]) =>
-  cohort.top1.rate < cohort.floors.top1 ||
-  cohort.top3.rate < cohort.floors.top3 ||
-  cohort.top5.rate < cohort.floors.top5
+  cohort.top1.hits / cohort.top1.of < cohort.floors.top1 ||
+  cohort.top3.hits / cohort.top3.of < cohort.floors.top3 ||
+  cohort.top5.hits / cohort.top5.of < cohort.floors.top5
 );
 if (failedCohorts.length > 0) {
   process.stderr.write(
diff --git a/scripts/lib/wrap.mjs b/scripts/lib/wrap.mjs
index 118d159..dac443f 100644
--- a/scripts/lib/wrap.mjs
+++ b/scripts/lib/wrap.mjs
@@ -1,17 +1,26 @@
 export function wrapLine(line, columns, continuationIndent = "    ") {
-  if (line.length <= columns) {
+  if (!Number.isSafeInteger(columns) || columns < 1) {
+    throw new RangeError("columns must be a positive whole number");
+  }
+  const graphemes = (value) => typeof Intl.Segmenter === "function"
+    ? [...new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(value)].map((part) => part.segment)
+    : [...value];
+  if (graphemes(line).length <= columns) {
     return [line];
   }
 
   const rows = [];
   let rest = line;
   let indent = "";
-  while (rest.length > columns - indent.length) {
-    const available = Math.max(1, columns - indent.length);
-    const whitespaceBreak = rest.lastIndexOf(" ", available);
-    const breakAt = whitespaceBreak > 0 ? whitespaceBreak : available;
-    rows.push(indent + rest.slice(0, breakAt).trimEnd());
-    rest = rest.slice(whitespaceBreak > 0 ? breakAt + 1 : breakAt);
+  while (graphemes(rest).length > columns - graphemes(indent).length) {
+    const available = Math.max(1, columns - graphemes(indent).length);
+    const units = graphemes(rest);
+    const candidate = units.slice(0, available).join("");
+    const boundaryWhitespace = units[available] === " ";
+    const whitespaceBreak = boundaryWhitespace ? available : candidate.lastIndexOf(" ");
+    const breakAt = whitespaceBreak > 0 ? graphemes(candidate.slice(0, whitespaceBreak)).length : available;
+    rows.push(indent + units.slice(0, breakAt).join("").trimEnd());
+    rest = units.slice(whitespaceBreak > 0 ? breakAt + 1 : breakAt).join("");
     indent = continuationIndent.slice(0, Math.max(0, columns - 1));
   }
   rows.push(indent + rest);
diff --git a/scripts/render-benchmark-card.mjs b/scripts/render-benchmark-card.mjs
index fac80af..66e4162 100644
--- a/scripts/render-benchmark-card.mjs
+++ b/scripts/render-benchmark-card.mjs
@@ -30,14 +30,14 @@ const runtimeLabel = runtime >= 1000
   : `${Math.round(runtime)}ms`;
 
 const unmentioned = heldout.results.filter((result) => !result.mentionsExpectedPath);
-const fixmapTop1 = unmentioned.filter((result) => result.top1).length;
-const fixmapTop3 = unmentioned.filter((result) => result.top3).length;
+const fixmapTop1 = unmentioned.filter((result) => result.top1Hit).length;
+const fixmapTop3 = unmentioned.filter((result) => result.top3Hit).length;
 const fixmapTop5 = unmentioned.filter((result) => result.top5Hit).length;
 const bm25Policy = baseline.configuration.bestPolicyPerFamily.bm25;
 const bm25Arm = `bm25:${bm25Policy}`;
 const baselineUnmentioned = baseline.results.filter((result) => !result.mentionsExpectedPath);
-const bm25Top1 = baselineUnmentioned.filter((result) => result.arms[bm25Arm].top1).length;
-const bm25Top3 = baselineUnmentioned.filter((result) => result.arms[bm25Arm].top3).length;
+const bm25Top1 = baselineUnmentioned.filter((result) => result.arms[bm25Arm].top1Hit).length;
+const bm25Top3 = baselineUnmentioned.filter((result) => result.arms[bm25Arm].top3Hit).length;
 const bm25Top5 = baselineUnmentioned.filter((result) => result.arms[bm25Arm].top5Hit).length;
 const cohortSize = unmentioned.length;
 const namedCases = heldout.results.length - cohortSize;
diff --git a/scripts/smoke-workspace.mjs b/scripts/smoke-workspace.mjs
index 674cd6d..967d55e 100644
--- a/scripts/smoke-workspace.mjs
+++ b/scripts/smoke-workspace.mjs
@@ -34,8 +34,9 @@ for (const benchmark of cases) {
     console.error(`Workspace smoke failed: "${benchmark.task}" routed to "${firstRoute}" instead of "${benchmark.expectedFirstRoute}".`);
     failed = true;
   }
-  if (!contextPaths.includes(benchmark.expectedContext)) {
-    console.error(`Workspace smoke failed: "${benchmark.task}" did not rank ${benchmark.expectedContext}.`);
+  if (contextPaths[0] !== benchmark.expectedContext) {
+    const position = contextPaths.indexOf(benchmark.expectedContext);
+    console.error(`Workspace smoke failed: "${benchmark.task}" ranked ${benchmark.expectedContext} ${position === -1 ? "nowhere" : `at position ${position + 1}`}, not first.`);
     failed = true;
   }
 
diff --git a/server.json b/server.json
index 955c4c1..4e07472 100644
--- a/server.json
+++ b/server.json
@@ -6,12 +6,12 @@
     "url": "https://github.com/aryamthecodebreaker/FixMap",
     "source": "github"
   },
-  "version": "0.8.8",
+  "version": "0.8.9",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@aryam/fixmap",
-      "version": "0.8.8",
+      "version": "0.8.9",
       "transport": {
         "type": "stdio"
       },

From bba3c79e35a65a224bb0701e88c49126831120ab Mon Sep 17 00:00:00 2001
From: Aryam Goyal <aryamgoyal18@gmail.com>
Date: Tue, 11 Aug 2026 14:09:14 +0530
Subject: [PATCH 08/10] Fix cross-platform clean installs

---
 package-lock.json | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/package-lock.json b/package-lock.json
index ce9f169..b762d57 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -336,6 +336,17 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@emnapi/runtime": {
+      "version": "1.11.3",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz",
+      "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==",
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
     "node_modules/@esbuild/aix-ppc64": {
       "version": "0.28.1",
       "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.1.tgz",

From fe1744bb38450c08907f1e1e80ab478b11fb4a59 Mon Sep 17 00:00:00 2001
From: Aryam Goyal <aryamgoyal18@gmail.com>
Date: Tue, 11 Aug 2026 14:15:00 +0530
Subject: [PATCH 09/10] Fix cross-platform path and lint checks

---
 apps/web/app/opengraph-image.tsx | 1 -
 apps/web/eslint.config.mjs       | 5 +++++
 packages/core/src/repo-scan.ts   | 8 ++++++--
 3 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/apps/web/app/opengraph-image.tsx b/apps/web/app/opengraph-image.tsx
index 9dcefc8..7b4c47e 100644
--- a/apps/web/app/opengraph-image.tsx
+++ b/apps/web/app/opengraph-image.tsx
@@ -1,4 +1,3 @@
-/* eslint-disable @next/next/no-img-element -- next/image is not supported inside ImageResponse. */
 import { ImageResponse } from "next/og";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
diff --git a/apps/web/eslint.config.mjs b/apps/web/eslint.config.mjs
index be9af84..c312272 100644
--- a/apps/web/eslint.config.mjs
+++ b/apps/web/eslint.config.mjs
@@ -5,5 +5,10 @@ import nextTypeScript from "eslint-config-next/typescript";
 export default defineConfig([
   ...nextCoreWebVitals,
   ...nextTypeScript,
+  {
+    files: ["app/opengraph-image.tsx"],
+    // ImageResponse renders its own image tree and cannot use next/image.
+    rules: { "@next/next/no-img-element": "off" }
+  },
   globalIgnores([".next/**", "next-env.d.ts"])
 ]);
diff --git a/packages/core/src/repo-scan.ts b/packages/core/src/repo-scan.ts
index d3fa60b..248641c 100644
--- a/packages/core/src/repo-scan.ts
+++ b/packages/core/src/repo-scan.ts
@@ -493,6 +493,10 @@ async function buildFilesFromPaths(
   // git listed first would have made that an alphabetical accident.
   const seenRealPaths = new Map<string, number>();
   const linked: Array<{ path: string; target: string }> = [];
+  // macOS temporary directories commonly enter through /var while realpath returns
+  // /private/var. Resolve the repository root once so that prefix alias does not make
+  // every ordinary file look like a symlink.
+  const realRoot = await resolveRealPath(root);
 
   for (const [index, rawPath] of paths.entries()) {
     if (results.length >= MAX_SCANNED_FILES) {
@@ -530,8 +534,8 @@ async function buildFilesFromPaths(
       const seenFile = results[seenIndex]!;
       // Looking only at the leaf with lstat misses Windows junctions, where the linked
       // object is an ancestor directory. Comparing literal and resolved paths covers both.
-      const seenIsAlias = !sameFilesystemPath(resolve(root, seenFile.path), scanned.realPath);
-      const currentIsAlias = !sameFilesystemPath(resolve(root, relativePath), scanned.realPath);
+      const seenIsAlias = !sameFilesystemPath(resolve(realRoot, seenFile.path), scanned.realPath);
+      const currentIsAlias = !sameFilesystemPath(resolve(realRoot, relativePath), scanned.realPath);
       if (seenIsAlias && !currentIsAlias) {
         linked.push({ path: seenFile.path, target: relativePath });
         results[seenIndex] = scanned.file;

From 3d0cace53e0b032dc7d4fcae32f9933d69516886 Mon Sep 17 00:00:00 2001
From: Aryam Goyal <aryamgoyal18@gmail.com>
Date: Tue, 11 Aug 2026 14:18:10 +0530
Subject: [PATCH 10/10] Rebuild Action bundle

---
 packages/action/dist/index.mjs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/action/dist/index.mjs b/packages/action/dist/index.mjs
index 4ab1ecd..6fe4e76 100644
--- a/packages/action/dist/index.mjs
+++ b/packages/action/dist/index.mjs
@@ -2533,6 +2533,7 @@ async function buildFilesFromPaths(root, paths, diagnostics, knownGitLinks = /*
   const gitLinks = [];
   const seenRealPaths = /* @__PURE__ */ new Map();
   const linked = [];
+  const realRoot = await resolveRealPath(root);
   for (const [index, rawPath] of paths.entries()) {
     if (results.length >= MAX_SCANNED_FILES) {
       reportScanLimit(diagnostics, paths.slice(index).map(normalizePath));
@@ -2561,8 +2562,8 @@ async function buildFilesFromPaths(root, paths, diagnostics, knownGitLinks = /*
     const seenIndex = seenRealPaths.get(scanned.realPath);
     if (seenIndex !== void 0) {
       const seenFile = results[seenIndex];
-      const seenIsAlias = !sameFilesystemPath(resolve(root, seenFile.path), scanned.realPath);
-      const currentIsAlias = !sameFilesystemPath(resolve(root, relativePath), scanned.realPath);
+      const seenIsAlias = !sameFilesystemPath(resolve(realRoot, seenFile.path), scanned.realPath);
+      const currentIsAlias = !sameFilesystemPath(resolve(realRoot, relativePath), scanned.realPath);
       if (seenIsAlias && !currentIsAlias) {
         linked.push({ path: seenFile.path, target: relativePath });
         results[seenIndex] = scanned.file;