projscan 4.1.0 → 4.2.0

package/README.md

@@ -33,17 +33,17 @@ The local plugin platform lets teams add project-specific findings and render `d
 npx projscan
 ```
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.1.0/docs/projscan-reporter-plugin.gif" alt="projscan doctor rendered through a local reporter plugin in a macOS-style terminal window" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.2.0/docs/projscan-reporter-plugin.gif" alt="projscan doctor rendered through a local reporter plugin in a macOS-style terminal window" width="700">
 
-## What's New in 4.1.0
+## What's New in 4.2.0
 
-4.1.0 turns projscan into a stronger developer Mission Control layer: tell it the work you are trying to do, and it routes you to the right local proof.
+4.2.0 turns Mission Control into a runnable handoff system: tell projscan the work, then get the next command, MCP call, proof queue, review gate, and saved bundle an agent can resume.
 
-- **Mission Control for real developer goals.** `projscan start --intent "<goal>"` now maps plain-language work to inferred mode, route confidence, ready actions, alternatives, done criteria, proof commands, and a compact handoff prompt.
-- **Much broader intent coverage.** Privacy, repo orientation, local setup, change planning, public contracts, file impact, package importers, ownership, PR evidence, release readiness, coordination, and session handoff questions now route to specific commands instead of generic next steps.
-- **Proof-first verification.** "Which tests should I run?" and "what proves this works?" route to targeted verification proof, while failing/flaky/build questions still route to focused regression planning.
-- **Richer repo and dependency intelligence.** Setup discovery now finds npm scripts, lint/typecheck, e2e, Storybook, Docker Compose, migrations, seed/reset commands, license summaries, package sizes, copyleft risk, and package importer lookups.
-- **More reliable agent plumbing.** Project Memory recording and MCP close handling now await their async writes/teardown so session context is less likely to race with agent shutdown.
+- **Execution plans with a cursor.** `projscan start --intent "<goal>"` now returns ordered phases, blocked inputs, follow-ups, done criteria, and a current cursor so agents know what to run next.
+- **Copyable shortcuts for humans and MCP clients.** Use `--next-command`, `--next-tool-call`, `--proof-commands`, `--checklist`, `--resume-json`, `--handoff-json`, `--task-card`, and `--runbook` when you need one surface instead of the full report.
+- **Saved mission bundles.** `--save-mission <dir>` writes a runnable bundle with `mission.sh`, `status.sh`, `review.sh`, quick commands, manifest metadata, prompts, JSON handoff files, proof logs, run reports, and `summary.json`.
+- **Stop-and-review gates.** Mission Control now carries review policy, worktree evidence, proof queues, done criteria, reviewer decisions, and copyable reply text so agents stop before another slice, release, publish, deploy, push, merge, or version bump.
+- **Safer shell handoffs.** Generated commands and saved mission scripts now escape `$` and backticks in freeform intent text, so copied commands treat developer goals as literal arguments.
 
 <img src="docs/projscan-proof-router.png" alt="projscan intent router and proof workflow showing impact routing, setup discovery, dependency intelligence, and stable-surface guardrails" width="760">
 
@@ -53,13 +53,143 @@ Regenerate the README screenshots with Playwright:
 npm run docs:screenshots
 ```
 
+## Mission Execution Plan + Copyable Handoffs
+
+`projscan start --intent "<goal>"` gives agents an execution plan with ordered phases, ready commands, blocked inputs, follow-ups, proof, and done criteria. The cursor points to the next useful step and includes MCP `tool` / `args` when projscan can call it directly.
+
+Projscan also returns a Markdown runbook, a task card, a review gate, and a resume object. A resumed agent gets the current command, the MCP tool call, placeholder bindings, follow-up templates, the ordered checklist, and the remaining proof queue without walking the full plan. MCP and JSON clients can read `missionControl.taskCard.markdown`, the same Markdown printed by `--task-card` and written to `task-card.md`. They can also read `missionControl.reviewGate.markdown` to know when to stop, report proof, and wait for approval before starting another slice, release, publish, or deploy. `missionControl.reviewGate.worktree` adds the current worktree evidence summary and visible changed files, so review handoffs keep the state projscan computed for the start report. `missionControl.reviewGate.proof` carries the remaining proof queue with commands, MCP calls, and structured proof items for review-only handoffs. `missionControl.reviewGate.doneWhen` mirrors the mission success criteria, so review-only handoffs show the approval target beside proof and worktree evidence. `missionControl.reviewGate.policy` lists the actions blocked until explicit reviewer approval: another slice, release, publish, deploy, push, merge, and version bump. `--review-gate-json` and saved `review-gate.json` expose the full review packet without requiring callers to parse the full handoff. `--review-policy` and saved `review-policy.json` expose only the approval boundary. `missionControl.reviewGate.decisions` gives the reviewer the allowed next choices and copyable reply text: approve another slice, request changes, or review a version candidate without publishing; the same menu appears in default console output, saved bundle README files, task cards, handoff prompts, and runbook Markdown. `--review-replies` and saved `review-replies.txt` print only those reply lines when a reviewer wants the smallest approval surface. The complete handoff object carries the same gate at `missionControl.handoff.reviewGate`, so `--handoff-json` and saved `handoff.json` include the stop boundary.
+
+Use the index when you want the menu, or call one shortcut directly:
+
+```bash
+projscan start --shortcuts --intent "<goal>"         # Show the shortcut menu
+projscan start --shortcuts-json --intent "<goal>"    # Shortcut menu as JSON
+projscan start --next-command --intent "<goal>"      # Current shell command
+projscan start --next-tool-call --intent "<goal>"   # Current MCP call as compact JSON
+projscan start --ready-tool-calls --intent "<goal>" # Current + proof MCP calls
+projscan start --proof-commands --intent "<goal>"   # Remaining proof commands
+projscan start --checklist --intent "<goal>"        # Ordered resume task card
+projscan start --resume-json --intent "<goal>"      # Structured resume object
+projscan start --handoff-json --intent "<goal>"     # Complete handoff object
+projscan start --mission-script --intent "<goal>"   # Shell script: current step + proof
+projscan start --save-mission .projscan/mission --intent "<goal>" # Write bundle + quickstart
+projscan start --task-card --intent "<goal>"        # Paste-ready Markdown task card
+projscan start --review-gate --intent "<goal>"      # Stop-and-review gate
+projscan start --review-gate-json --intent "<goal>" # Review gate JSON
+projscan start --review-policy --intent "<goal>"    # Review policy JSON
+projscan start --review-replies --intent "<goal>"   # Copy-only reviewer replies
+projscan start --runbook --intent "<goal>"          # Markdown mission runbook
+projscan start --handoff-prompt --intent "<goal>"   # One-line handoff prompt
+```
+
+Saved mission bundles include `README.md`, `next-command.txt`, `next-tool-call.json`, `handoff-prompt.txt`, `resume-prompt.txt`, `task-card.md`, `review-gate.md`, `review-gate.json`, `review-policy.json`, `review-replies.txt`, the Markdown runbook, structured handoff/resume JSON, `ready-tool-calls.json`, `shortcuts.json`, `mission.sh`, `status.sh`, `review.sh`, `proof-logs/README.md`, `proof-logs/status.jsonl`, `proof-logs/run-report.md`, `proof-logs/summary.json`, proof commands, and a manifest. The saved bundle README starts with quick commands for `./mission.sh`, `./status.sh`, and `./review.sh`; `manifest.json` exposes the same quick commands under `quickCommands` for agents and JSON clients. Running saved `mission.sh` writes current and proof command output under `proof-logs/`, appends exit codes to `status.jsonl`, refreshes `run-report.md` for review, and writes the latest run state plus next action to `summary.json` for agents. Run `./status.sh` from the bundle to print the latest mission state and next action; it exits `0` for passed, `1` for failed, and `2` for not-run or running states. Run `./review.sh` from the bundle to print the status, review gate, run report, evidence command checklist, and reviewer replies in one terminal view.
+
+Default console output shows the same sections inline: `Run Cursor`, `Resume Checklist`, `Handoff Prompt`, `Ready Proof`, and `Proof Queue`. The proof views use the resume-aware remaining queue, so projscan does not repeat the current cursor command as proof.
+
+Console output shows the same model for humans:
+
+```text
+Execution Plan
+Run 1 ready step, resolve 2 input(s), then gather 4 proof command(s).
+- [ready] Next Action
+  - Find exact target for impact analysis: projscan search "auth token loader" --format json
+- [blocked] Resolve Inputs
+  - symbol: Replace <symbol-from-search> with an exported symbol returned by the search step.
+- [pending] Follow Up
+  - If search returns an exported symbol: projscan impact --symbol <symbol-from-search> --format json
+    blocked by: input-1
+Run Cursor
+next: ready-1 in Ready Commands
+command: projscan search "auth token loader" --format json
+MCP call: projscan_search {"query":"auth token loader"}
+unlocks: input-1, input-2
+Resume Checklist
+- [ready] run_current ready-1: projscan search "auth token loader" --format json (MCP: projscan_search {"query":"auth token loader"})
+- [blocked] resolve_input input-1: <symbol-from-search> -> Replace <symbol-from-search> with an exported symbol returned by the search step.
+- [blocked] run_follow_up follow-up-1: projscan impact --symbol <symbol-from-search> --format json (MCP: projscan_impact {"symbol":"<symbol-from-search>"})
+- [ready] run_proof proof-2: projscan preflight --mode before_edit --format json (MCP: projscan_preflight {"mode":"before_edit"})
+Handoff Prompt
+Resume: Resume at ready-1 in ready_now: run `projscan search "auth token loader" --format json`. This can unlock input-1 (symbol), input-2 (file). Done when: An exact symbol or file path is selected from search results before impact analysis continues.
+Ready Proof
+Ready-to-run proof commands; placeholder follow-ups are excluded until Needs Input is resolved.
+- projscan preflight --mode before_edit --format json
+- projscan understand --view verify --format json
+Proof Queue
+- proof-2: projscan preflight --mode before_edit --format json (MCP: projscan_preflight {"mode":"before_edit"})
+- proof-3: projscan understand --view verify --format json (MCP: projscan_understand {"view":"verify"})
+```
+
+Runbook handoff example:
+
+```text
+Agent Runbook
+# Mission Runbook
+Intent: what breaks if I rename the auth token loader
+Status: needs_attention
+Current phase: ready_now
+
+## Current Cursor
+- Step: ready-1 in ready_now
+- Command: `projscan search "auth token loader" --format json`
+- MCP call: projscan_search {"query":"auth token loader"}
+- Unlocks: input-1, input-2
+
+## Resume
+Run now:
+```sh
+projscan search "auth token loader" --format json
+```
+MCP call: projscan_search {"query":"auth token loader"}
+After running, resolve:
+- input-1 (symbol): Replace <symbol-from-search> with an exported symbol returned by the search step.
+- input-2 (file): Replace <file-from-search> with a file path returned by the search step.
+Template inputs:
+- <symbol-from-search> -> input-1 (symbol): Replace <symbol-from-search> with an exported symbol returned by the search step.
+- <file-from-search> -> input-2 (file): Replace <file-from-search> with a file path returned by the search step.
+Resume checklist:
+- [ready] run_current ready-1: projscan search "auth token loader" --format json (MCP: projscan_search {"query":"auth token loader"})
+- [blocked] resolve_input input-1: <symbol-from-search> -> Replace <symbol-from-search> with an exported symbol returned by the search step.
+- [ready] run_proof proof-2: projscan preflight --mode before_edit --format json (MCP: projscan_preflight {"mode":"before_edit"})
+- [pending] confirm_done criterion-1: An exact symbol or file path is selected from search results before impact analysis continues.
+Proof queue:
+- proof-2: `projscan preflight --mode before_edit --format json` (MCP: projscan_preflight {"mode":"before_edit"})
+- proof-3: `projscan understand --view verify --format json` (MCP: projscan_understand {"view":"verify"})
+Remaining proof:
+- `projscan preflight --mode before_edit --format json`
+- `projscan understand --view verify --format json`
+MCP proof calls:
+- proof-2: projscan_preflight {"mode":"before_edit"}
+- proof-3: projscan_understand {"view":"verify"}
+Then use:
+- follow-up-1 (If search returns an exported symbol): projscan impact --symbol <symbol-from-search> --format json
+- follow-up-2 (If search returns a file path): projscan impact <file-from-search> --format json
+Prompt: Resume at ready-1 in ready_now: run `projscan search "auth token loader" --format json`. This can unlock input-1 (symbol), input-2 (file).
+
+## Handoff Prompt
+Resume: Resume at ready-1 in ready_now: run `projscan search "auth token loader" --format json`. This can unlock input-1 (symbol), input-2 (file). Done when: An exact symbol or file path is selected from search results before impact analysis continues. Needs input: symbol=<symbol-from-search>, file=<file-from-search>. Ready proof: Ready-to-run proof commands; placeholder follow-ups are excluded until Needs Input is resolved. projscan preflight --mode before_edit --format json && projscan understand --view verify --format json.
+
+## Review Gate
+- [ ] Complete this task card and remaining proof.
+- [ ] Capture `git status --short`.
+- [ ] Capture `git diff --stat`.
+- [ ] Stop and ask for approval before starting another slice, release, publish, or deploy.
+
+Review the completed mission, proof output, and working-tree summary before approving another slice, release, publish, or deploy.
+
+## Ready Commands
+- `projscan search "auth token loader" --format json`
+
+## Blocked Inputs
+- symbol: Replace <symbol-from-search> with an exported symbol returned by the search step.
+```
+
 Run `projscan doctor` for a focused health check:
 
 ```bash
 npx projscan doctor
 ```
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.1.0/docs/npx%20projscan%20doctor.gif" alt="npx projscan doctor" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.2.0/docs/npx%20projscan%20doctor.gif" alt="npx projscan doctor" width="700">
 
 ## Install
 
@@ -392,9 +522,9 @@ npm run test:trust-smoke
 
 The full command catalog is below. Most users should start with the five-command path above instead of scanning the catalog.
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.1.0/docs/npx%20projscan%20--help.gif" alt="npx projscan --help" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.2.0/docs/npx%20projscan%20--help.gif" alt="npx projscan --help" width="700">
 
-For a comprehensive walkthrough, see the **[Full Guide](https://github.com/abhiyoheswaran1/projscan/blob/v4.1.0/docs/GUIDE.md)**.
+For a comprehensive walkthrough, see the **[Full Guide](https://github.com/abhiyoheswaran1/projscan/blob/v4.2.0/docs/GUIDE.md)**.
 
 ## Repo Understanding
 
@@ -416,7 +546,7 @@ The report includes file/symbol-backed `claims`, `readFirst` files, entrypoints,
 |---------|-------------|
 | `projscan analyze` | Full analysis - languages, frameworks, dependencies, issues |
 | `projscan route` | Map a plain-language goal to the best projscan tool with weighted confidence and matched keywords |
-| `projscan start` | First-60-seconds workflow orientation with setup diagnostics, Mission Control, top risks, and next commands. Add `--intent "<goal>"` to route a plain-language goal to route confidence, ready actions, done criteria, and proof commands |
+| `projscan start` | First-60-seconds workflow orientation with setup diagnostics, Mission Control, top risks, and next commands. Add `--intent "<goal>"` to route a plain-language goal to route confidence, phased execution plan, ready actions, done criteria, and proof commands |
 | `projscan first-run` | First-run setup diagnostics plus the shared `firstTenMinutes` command path |
 | `projscan init mcp` | Ready-to-paste MCP client configs for popular agent clients |
 | `projscan mcp doctor` | Verify MCP setup and print paste-ready client config with checks |
@@ -475,25 +605,25 @@ projscan --help
 <details>
 <summary><strong>projscan structure</strong> - Directory tree with file counts</summary>
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.1.0/docs/npx%20projscan%20structure.gif" alt="npx projscan structure" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.2.0/docs/npx%20projscan%20structure.gif" alt="npx projscan structure" width="700">
 </details>
 
 <details>
 <summary><strong>projscan diagram</strong> - Architecture visualization</summary>
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.1.0/docs/npx%20projscan%20diagram.gif" alt="npx projscan diagram" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.2.0/docs/npx%20projscan%20diagram.gif" alt="npx projscan diagram" width="700">
 </details>
 
 <details>
 <summary><strong>projscan dependencies</strong> - Dependency analysis</summary>
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.1.0/docs/npx%20projscan%20dependencies.gif" alt="npx projscan dependencies" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.2.0/docs/npx%20projscan%20dependencies.gif" alt="npx projscan dependencies" width="700">
 </details>
 
 <details>
 <summary><strong>projscan badge</strong> - Health badge generation</summary>
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.1.0/docs/npx%20projscan%20badge.gif" alt="npx projscan badge" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.2.0/docs/npx%20projscan%20badge.gif" alt="npx projscan badge" width="700">
 </details>
 
 ### Output Formats
@@ -515,7 +645,7 @@ Run `projscan help` for the generated command-by-command support matrix.
 
 projscan can load local plugins from `.projscan-plugins/` when `PROJSCAN_PLUGINS_PREVIEW=1` is set. The environment flag is kept for explicit local-code opt-in. Analyzer plugins emit normal projscan issues; reporter plugins render supported CLI commands with team-specific output.
 
-**2.0 upgrade notes:** migrating from 1.x or authoring plugins? Start with the [2.0 Migration Guide](https://github.com/abhiyoheswaran1/projscan/blob/v4.1.0/docs/2.0-MIGRATION.md), then use [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v4.1.0/docs/PLUGIN-AUTHORING.md), the [Plugin Gallery](https://github.com/abhiyoheswaran1/projscan/blob/v4.1.0/docs/PLUGIN-GALLERY.md), and the [manifest schema](https://github.com/abhiyoheswaran1/projscan/blob/v4.1.0/docs/plugin.schema.json) as the stable contract.
+**2.0 upgrade notes:** migrating from 1.x or authoring plugins? Start with the [2.0 Migration Guide](https://github.com/abhiyoheswaran1/projscan/blob/v4.2.0/docs/2.0-MIGRATION.md), then use [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v4.2.0/docs/PLUGIN-AUTHORING.md), the [Plugin Gallery](https://github.com/abhiyoheswaran1/projscan/blob/v4.2.0/docs/PLUGIN-GALLERY.md), and the [manifest schema](https://github.com/abhiyoheswaran1/projscan/blob/v4.2.0/docs/plugin.schema.json) as the stable contract.
 
 ```bash
 projscan plugin list
@@ -526,9 +656,9 @@ PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor --reporter team-radar
 PROJSCAN_PLUGINS_PREVIEW=1 projscan ci --reporter team-radar --min-score 80
 ```
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.1.0/docs/projscan-reporter-plugin.gif" alt="projscan local reporter plugin rendering a team health report" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.2.0/docs/projscan-reporter-plugin.gif" alt="projscan local reporter plugin rendering a team health report" width="700">
 
-Reporter plugins are intentionally CLI-only. MCP tools keep returning structured JSON-compatible payloads so agents can reason over stable data, while humans can get a polished local report for their team. Custom presentation, team-branded summaries, and white-label reports belong in reporter plugins rather than new core HTML theming flags. See [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v4.1.0/docs/PLUGIN-AUTHORING.md) for manifest shape, `render(context)`, validation, and the trust model.
+Reporter plugins are intentionally CLI-only. MCP tools keep returning structured JSON-compatible payloads so agents can reason over stable data, while humans can get a polished local report for their team. Custom presentation, team-branded summaries, and white-label reports belong in reporter plugins rather than new core HTML theming flags. See [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v4.2.0/docs/PLUGIN-AUTHORING.md) for manifest shape, `render(context)`, validation, and the trust model.
 
 ### Options
 
@@ -539,6 +669,24 @@ Reporter plugins are intentionally CLI-only. MCP tools keep returning structured
 | `--include-ignored` | Explicitly include files hidden by Git ignore rules |
 | `--scan-env-values` | Explicitly read `.env*` contents during secret checks |
 | `--offline` | Block projscan network-capable features for this run |
+| `--shortcuts` | Print the Mission Control shortcut command index (`start`) |
+| `--shortcuts-json` | Print the Mission Control shortcut command index as JSON (`start`) |
+| `--handoff-prompt` | Print only the concise Mission Control handoff prompt (`start`) |
+| `--next-command` | Print only the current Mission Control cursor command (`start`) |
+| `--next-tool-call` | Print only the current Mission Control cursor MCP tool call as JSON (`start`) |
+| `--ready-tool-calls` | Print the current cursor and remaining MCP-callable proof queue as JSON (`start`) |
+| `--proof-commands` | Print only ready Mission Control proof commands (`start`) |
+| `--checklist` | Print only the Mission Control resume checklist (`start`) |
+| `--resume-json` | Print only the Mission Control resume object as JSON (`start`) |
+| `--handoff-json` | Print only the Mission Control handoff object as JSON (`start`) |
+| `--mission-script` | Print the Mission Control shell script (`start`) |
+| `--save-mission <dir>` | Write the Mission Control bundle to a directory (`start`) |
+| `--task-card` | Print only the Mission Control Markdown task card (`start`) |
+| `--review-gate` | Print only the Mission Control stop-and-review gate (`start`) |
+| `--review-gate-json` | Print only the Mission Control review gate as JSON (`start`) |
+| `--review-policy` | Print only the Mission Control review policy as JSON (`start`) |
+| `--review-replies` | Print only copyable Mission Control reviewer replies (`start`) |
+| `--runbook` | Print only the Mission Control Markdown runbook (`start`) |
 | `--changed-only` | Scope to files changed vs base ref (ci/analyze/doctor) |
 | `--base-ref <ref>` | Git base ref for `--changed-only` (default: origin/main) |
 | `--reporter <name>` | Render `doctor`, `analyze`, or `ci` with a local reporter plugin |
@@ -695,7 +843,7 @@ If you read projscan's [Socket report](https://socket.dev/npm/package/projscan),
 ### Audit it yourself
 
 - **Source is open** at [github.com/abhiyoheswaran1/projscan](https://github.com/abhiyoheswaran1/projscan). The npm tarball matches the `dist/` produced by `npm run build` at the matching tag.
-- **Public API surface is locked** by `scripts/check-stability.mjs`, which runs in CI on every PR and fails on any rename or removal of an MCP tool, CLI command, or exit code. See [`docs/STABILITY.md`](https://github.com/abhiyoheswaran1/projscan/blob/v4.1.0/docs/STABILITY.md).
+- **Public API surface is locked** by `scripts/check-stability.mjs`, which runs in CI on every PR and fails on any rename or removal of an MCP tool, CLI command, or exit code. See [`docs/STABILITY.md`](https://github.com/abhiyoheswaran1/projscan/blob/v4.2.0/docs/STABILITY.md).
 - **Run it offline:** `npm install -g projscan` followed by anything except `audit` and `--mode semantic` works without network.
 - **Drop privilege further:** in CI, run projscan in a sandbox that disallows network egress; everything except `audit` will pass.
 
@@ -746,7 +894,7 @@ projscan ci --changed-only                     # Gate only on this PR's diff
 projscan ci --format sarif > projscan.sarif    # SARIF for Code Scanning
 ```
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.1.0/docs/npx%20projscan%20ci%20--min-score%2070.gif" alt="npx projscan ci --min-score 70" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.2.0/docs/npx%20projscan%20ci%20--min-score%2070.gif" alt="npx projscan ci --min-score 70" width="700">
 
 ### GitHub Action (recommended)
 
@@ -823,7 +971,7 @@ Fields:
 - `hotspots.limit` / `hotspots.since` - defaults for the `hotspots` command
 - `monorepo.importPolicy` - cross-package import allow/deny rules in monorepos *(0.14+)*
 
-See [`docs/GUIDE.md` -> Configuration](https://github.com/abhiyoheswaran1/projscan/blob/v4.1.0/docs/GUIDE.md#configuration-projscanrc) for the full reference (field types, validation behavior, embedding config in `package.json`, monorepo `importPolicy` semantics).
+See [`docs/GUIDE.md` -> Configuration](https://github.com/abhiyoheswaran1/projscan/blob/v4.2.0/docs/GUIDE.md#configuration-projscanrc) for the full reference (field types, validation behavior, embedding config in `package.json`, monorepo `importPolicy` semantics).
 
 ## Tracking Health Over Time
 
@@ -836,7 +984,7 @@ projscan diff                       # Compare against baseline
 projscan diff --format markdown     # Markdown diff for PRs
 ```
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.1.0/docs/npx%20projscan%20diff%20--save-baseline.gif" alt="npx projscan diff --save-baseline" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.2.0/docs/npx%20projscan%20diff%20--save-baseline.gif" alt="npx projscan diff --save-baseline" width="700">
 
 ## Hotspots - Where to Fix First
 
@@ -925,7 +1073,7 @@ Coverage is also automatically joined into `projscan hotspots` when one of those
 
 **This is the primary way to use projscan.** `projscan mcp` starts an [MCP](https://modelcontextprotocol.io) server over stdio so AI coding agents can query your codebase with real structural accuracy - not regex, not grep.
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.1.0/docs/projscan-agent-demo.gif" alt="projscan answering two agent questions: what breaks if I rename buildCodeGraph (impact analysis with definitions, direct callers, transitive reach), and where should I fix first (ranked hotspots with cyclomatic complexity)" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.2.0/docs/projscan-agent-demo.gif" alt="projscan answering two agent questions: what breaks if I rename buildCodeGraph (impact analysis with definitions, direct callers, transitive reach), and where should I fix first (ranked hotspots with cyclomatic complexity)" width="700">
 
 Two questions an agent asks; structural answers in milliseconds. *"What breaks if I rename `buildCodeGraph`?"* → 31 direct callers, 97 files reachable. *"Where should I fix first?"* → ranked hotspots with AST cyclomatic complexity, churn, and ownership signals.
 
@@ -1135,7 +1283,7 @@ Capability is advertised under `experimental.fileChanged` on `initialize` so cli
 - **`projscan_apply_fix`** *(1.6)* - mechanically execute the safe fix templates. Default is dry-run; pass `confirm: true` to write. Atomic writes, per-apply rollback record at `.projscan-cache/rollbacks/<id>.json`. Reverse with `action: "rollback", rollback_id: ...`. Six templates supported at this release: `unused-dependency-*`, `missing-test-framework`, `missing-eslint`, `missing-prettier`, `missing-editorconfig`, `missing-readme`.
 - **`projscan_taint`** *(1.6)* - source-to-sink reachability over the per-function call graph. Built-in defaults cover common JS / Python sources (`process.env`, `req.body`, etc.) and sinks (`exec`, `eval`, `db.query`, etc.). Project-specific names go in `.projscanrc.json` `taint`. `projscan_review` automatically diffs taint flows between base and head and **blocks any PR that introduces a new flow**. In 3.0.2, review surfaces hardened `newDataflowRisks`, compact `graphEvidence`, and graph-readiness gates for safer handoff.
 
-Analyzer plugins can optionally read graph/dataflow context through `check(rootPath, files, context)` while staying on manifest schema v1. The packaged `graph-context` example shows `context.getSemanticGraph()` and `context.getDataflow()` in a real analyzer. For analyzer and reporter plugin authoring, manifest validation, `--reporter <name>`, and the trust model, see [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v4.1.0/docs/PLUGIN-AUTHORING.md).
+Analyzer plugins can optionally read graph/dataflow context through `check(rootPath, files, context)` while staying on manifest schema v1. The packaged `graph-context` example shows `context.getSemanticGraph()` and `context.getDataflow()` in a real analyzer. For analyzer and reporter plugin authoring, manifest validation, `--reporter <name>`, and the trust model, see [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v4.2.0/docs/PLUGIN-AUTHORING.md).
 
 ### Context-window budgeting