openpitstop 1.5.2 → 1.7.0

package/README.md

@@ -12,14 +12,57 @@ know it's actually done.
 [![CI](https://github.com/Krish-1507/OpenPitStop/actions/workflows/ci.yml/badge.svg)](https://github.com/Krish-1507/OpenPitStop/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-> AI coding agents are brilliant at fixing things — and equally brilliant at *saying they
+> AI coding agents are brilliant at fixing things, and just as brilliant at *saying they
 > did* when they didn't. OpenPitStop measures your repo with scans, seals every number so it
-> can't be edited later, attacks your app with a live penetration test, and checks every
-> change your agent makes. The exit codes tell you the truth: `0` clean · `1` suspicious ·
+> can't be edited later, attacks your own app with a live penetration test, and checks every
+> change your agent makes. The exit codes tell you the truth: `0` clean, `1` suspicious,
 > `2` confirmed cheat.
 
 ---
 
+## Quick install
+
+**Start here:** `npx openpitstop try .` scores any repo in about two seconds with zero
+install, or `npm i -g openpitstop` for daily use. No account, no config, no SaaS.
+
+**Zero install, try it now:**
+```bash
+npx openpitstop try .
+```
+Scores any repo in about two seconds of scanning. The first run downloads the
+package once, after that it is instant.
+
+**Install it globally (recommended for daily use):**
+```bash
+npm install -g openpitstop
+openpitstop --help
+```
+Now every command starts with `openpitstop` instead of `npx openpitstop`.
+
+Requires **Node.js 22+**, that is the only dependency. For the full setup
+(slash command, pre-commit hook, CI), see [Install](#install).
+
+## Use-Cases
+
+- **You ship with an AI agent and want proof it actually finished.** The gate and
+  `verify` turn "the agent says done" into a pass or fail you can block a build on.
+- **You want a security scan that proves findings, not just guesses.** `pen` attacks
+  your app in a sandbox and labels each issue PROVEN, indicated, or unproven.
+- **You are tired of agents quietly deleting a failing test.** `integrity` and the
+  gate catch focused, deleted, or rewritten tests and exit 2 (confirmed cheat).
+- **You want CI to fail on a regression, not just a new bug.** Drift compares every
+  `pen` run to the last sealed one and goes red on a NEW finding.
+- **You need a score you can show your team or an auditor.** `report` and `honesty`
+  produce a sealed HTML report and an honesty certificate.
+- **You already pay for a pen tool and want continuous proof for free.** OpenPitStop
+  keeps a running ledger of proof in your repo. See the OpenPitStop vs Strix
+  comparison above.
+
+**Ready to try it?** Run `npx openpitstop try .` on any repo and get your score in
+about two seconds.
+
+---
+
 ## Why I built this
 
 I spend my days running coding agents on real repos. They're brilliant at fixing things —
@@ -40,8 +83,7 @@ your agent.
 
 | Jump to | |
 |---|---|
-| [Feature tour](#feature-tour) — the 13 demos | [Install](#install) · [Usage](#usage) · [Tool support](#tool-support) |
-| [See it in 90 seconds](#see-it-in-90-seconds) | [What OpenPitStop actually does](#what-openpitstop-actually-does) · [Every command](#every-command) |
+| [Feature tour](#feature-tour) — every feature, in plain English | [Install](#install) · [Usage](#usage) · [Tool support](#tool-support) |
 | [Architecture](#architecture) | [Known limitations](#known-limitations) · [Contributing](#contributing) · [License](#license) |
 
 **Straight to one feature:** [The scan](#the-scan) · [Security fixes](#security-fixes) · [Try it on your repo](#try-it-on-your-repo) · [The test pyramid](#the-test-pyramid) · [The gate](#the-gate) · [Integrity](#integrity) · [The pen test](#the-pen-test) · [Honesty](#honesty) · [Verify](#verify) · [Trends](#trends) · [Inspect](#inspect) · [Repro](#repro) · [Report](#report) · [Share](#share) · [The live shield](#the-live-shield) · [The GitHub Action](#the-github-action) · [The pre-commit hook](#the-pre-commit-hook)
@@ -79,170 +121,179 @@ loop — and it's the reason to choose the referee over the hacker.
 
 ## Feature tour
 
-Every clip below is real opencode output, captured from a live agent session —
-the only thing trimmed is dead time.
+Every feature below is explained in plain English: what it does, and how it
+works. Most of it needs nothing more than a `pitstop scan` first.
 
 ### The scan
 
-`pitstop scan` — every check runs at once, one box, one score.
-
-<p align="center">
-  <img src="docs/media/pitstop-scan.gif" alt="pitstop scan — boxed report with the OpenPitStop Score" width="700">
-</p>
+`pitstop scan` runs every check at once, in parallel, and prints one box with a
+single **OpenPitStop Score** (0 to 100, A to F). It looks at circular imports,
+security issues, duplicated code, test results, build speed, accessibility and
+code quality. Each check gives a real number or prints `skipped` with a hint on
+how to install the tool it needs. It never makes up a number.
 
 ### Security fixes
 
-`pitstop scan` — and below the box, the indicated fixes, with a concrete
-`fix:` line for each finding.
-
-<p align="center">
-  <img src="docs/media/pitstop-security.gif" alt="pitstop scan — the indicated security fixes, each with a concrete fix" width="700">
-</p>
+Under the scan box, every security finding ships with a concrete `fix:` line, so
+you get a worklist, not just a list of problems. Findings are labeled
+`[indicated]` with the exact code and the fix. The full matrix is in
+[docs/security.md](docs/security.md).
 
 ### Try it on your repo
 
-`pitstop try .` — score any repo in ~2 seconds of scanning, no setup, no config.
-(First `npx openpitstop …` on a machine downloads the package once — a few seconds;
-`npm i -g openpitstop` makes even that instant.)
-
-<p align="center">
-  <img src="docs/media/pitstop-try.gif" alt="pitstop try — zero-setup score on any repo" width="700">
-</p>
+`pitstop try .` scores any repo in about two seconds, no setup, no config. It is
+the fastest first look, and it seeds a baseline your later runs build on.
 
 ### The test pyramid
 
-`pitstop test` — unit, integration and e2e layers run separately, so a
-suite that "passes" can't hide a missing layer. One failing layer means
-**DO NOT SHIP**.
-
-<p align="center">
-  <img src="docs/media/pitstop-pyramid.gif" alt="pitstop test — the pyramid verdict: DO NOT SHIP on a failing e2e layer" width="700">
-</p>
+`pitstop test` runs your **unit, integration and e2e** layers separately, so a
+suite that passes cannot hide a missing layer. It names every failing test. One
+failing layer and it prints **DO NOT SHIP** and exits 1.
 
 ### The gate
 
-`pitstop gate` — the score plus the integrity check, exit 0/1/2:
-clean / suspicious / confirmed cheat.
-
-<p align="center">
-  <img src="docs/media/pitstop-gate.gif" alt="pitstop gate — GATE FAIL on a confirmed cheat, exit 2" width="700">
-</p>
+`pitstop gate` is the contract for CI and pre-commit hooks. It checks the score,
+regression risk and diff integrity, then exits `0` (clean), `1` (issues) or `2`
+(confirmed cheat). The exit code is the truth a build can block on.
 
 ### Integrity
 
-`pitstop integrity` — diff against the sealed baseline, hunting cheat
-patterns: focused tests, deleted tests, rewritten tests.
-
-<p align="center">
-  <img src="docs/media/pitstop-integrity.gif" alt="pitstop integrity — CONFIRMED_CHEAT: test file deleted" width="700">
-</p>
+`pitstop integrity` diffs your change against the sealed baseline and hunts cheat
+patterns: focused tests, deleted tests, rewritten tests, swallowed errors,
+hardcoded-to-pass values. It exits `0/1/2` the same way.
 
 ### The pen test
 
-`pitstop pen` — boots your app in a sandbox, attacks it, and writes PROVEN
-verdicts — plus repro tests and a patch with `--fix`.
+`pitstop pen` boots your app in a sandbox and fires real attack traffic, so a
+finding is **PROVEN** by a live attack, not just guessed. With `--fix` it writes a
+failing-first repro test and a safe patch. Nothing reaches the real network.
 
-<p align="center">
-  <img src="docs/media/pitstop-pen.gif" alt="pitstop pen — sandboxed attacks with runtime-proof verdicts" width="700">
-</p>
+### Drift (the permanent referee)
 
-### Honesty
+`pitstop pen` remembers. Every run seals its verdicts and compares them to the last one, so you
+see exactly what changed between today and last week:
 
-`pitstop honesty` — an honest assessment of what this tool can't do.
+- **NEW** — a finding appeared (or escalated from indicated to proven). This is a regression, so the
+  gate exits `1` and your CI goes red.
+- **RESOLVED** — a finding is gone because the fix worked. This is the "prove my fix" loop, and it is
+  the most satisfying thing here: run `pitstop repro <id>` to turn a finding into a failing test, ship
+  the patch, run `pitstop pen` again, and watch it flip to resolved.
+- **ESCALATIONS** — something that was only *indicated* by static analysis is now *proven* by a live
+  attack.
 
-<p align="center">
-  <img src="docs/media/pitstop-honesty.gif" alt="pitstop honesty — an honest self-assessment certificate" width="700">
-</p>
+Strix, the enterprise tool, runs a one-off scan. OpenPitStop keeps a running ledger of proof, so a
+fix can never silently rot back into a bug.
+
+### Honesty
+
+`pitstop honesty` prints an honest self-assessment of what the tool cannot do, with
+the evidence chain behind every number. No SaaS, no telemetry, no dashboard, no
+fixing your code: it tells you its limits in plain words.
 
 ### Verify
 
-`pitstop verify` — re-scan after a change and see exactly how the score moved. Also checks your diff for cheat patterns.
+`pitstop verify` re-scans after a change and shows exactly how the score moved, and
+it checks your diff for cheat patterns. The numbers cannot be argued with.
 
 ### Trends
 
-`pitstop trends` — per-category sparklines from your scan history.
+`pitstop trends` turns your saved scan history into per-category sparklines and a
+score trend, so you can watch a repo actually improve over time.
 
 ### Inspect
 
-`pitstop inspect <finding-id>` — open up one finding: the code snippet, the root cause, whether a repro test exists, and what OpenPitStop remembers about these files.
+`pitstop inspect <finding-id>` opens one finding: the code snippet, the root
+cause, whether a repro test exists, and what OpenPitStop remembers about these
+files.
 
 ### Repro
 
-`pitstop repro <finding-id>` — every fix starts with a failing test. The test is written to fail *now* and pass after the fix.
+`pitstop repro <finding-id>` turns any finding into a regression test that FAILS
+while the bug is live and must PASS after the fix. Proof first, fix second.
 
 ### Report
 
-`pitstop report --html` — one self-contained HTML report, sealed with an evidence signature.
+`pitstop report --html` writes one self-contained HTML report, sealed with an
+evidence signature, plus a README-ready score badge (`PITSTOP_BADGE.svg`).
 
 ### Share
 
-`pitstop share` — one-card summary, easy to paste into a PR or a demo chat.
+`pitstop share` renders a single share card (score, trend, top findings) you can
+screenshot and post, or paste into a PR.
 
 ### The live shield
 
-`pitstop watch` — re-scans the moment a file changes and prints the score delta.
+`pitstop watch` sits in a terminal and re-scans the moment you save a file, printing
+the score delta so you see problems as you type.
 
-### The GitHub Action
+### Drive the agent
 
-`uses: openpitstop/action` (or `Krish-1507/OpenPitStop@main` today) — every PR
-gets the gate as a comment and a failing check when it matters. No wiring by
-hand; the badge in your README regenerates itself. [Setup & badge loop →
-](docs/github-action.md)
+`pitstop drive <finding-id>` hands one finding to your own agent with explicit orders:
+write the failing repro first, fix it, make the repro pass, then verify.
+OpenPitStop referees the result and never edits your code.
 
-### The pre-commit hook
+### The next step
 
-`npx openpitstop install --hooks` — the gate one step earlier: the commit
-can't land until the gate passes. Caught it before it shipped. [Real blocked
-commits → ](docs/caught-in-the-wild.md#bonus-the-same-catches-as-a-pre-commit-hook)
+`pitstop next` reads the sealed artifacts and prints the single best next command plus
+a checklist of everything still open, so you always know where you are.
 
----
+### Ask in plain English
 
-## See it in 90 seconds
+`pitstop ask "make this safe"` (or `/pitstop make this safe`) maps a plain-English
+request to the right command. No need to memorize flags.
 
-Two commands. First, a real broken repo — scanned, scored and reported in seconds:
+### Autopilot fix
 
-```bash
-npx openpitstop@latest demo
-```
+`pitstop fix` chains **scan to pen --fix to verify to gate** and shows the `next` card
+after each hop, so a clean repo is reachable without touching the agent.
 
-Then the part that gets the *wow*: a scripted arc where a lazy agent tries to make the
-failing suite green without fixing the bug — and the gate catches both attempts:
+### Memory and budget
 
-```bash
-node scripts/cheat-demo.cjs                             # from a OpenPitStop repo checkout
-node node_modules/openpitstop/scripts/cheat-demo.cjs   # from any project that installed it
-```
+`pitstop memory` is a repo scratchpad for decisions and rejected approaches that
+survive across sessions. `pitstop budget` shows the token and compute bill of your
+scans and reproves, so a fix loop stays cheap.
 
-Set `PITSTOP_CLI="node /path/to/dist/cli.js"` to run it against a local build instead
-of the registry. For a tight re-record, `node scripts/cheat-demo.cjs --fast --no-pitch`
-reuses the cached `node_modules` (skips `npm install`) and ends the arc on the
-CONFIRMED_CHEAT box — no pitch, no dead air.
+### The slash command
 
-```
-ACT 1  honest baseline              →  1 failed test, scanned and sealed
-ACT 2  agent focuses passing tests  →  GATE: SUSPICIOUS     (exit 1) — blocked
-ACT 3  agent deletes the test       →  GATE: CONFIRMED_CHEAT (exit 2) — blocked
-       (tamper-evident evidence chain verifies the whole way)
-```
+`/pitstop` in Claude Code, Cursor, OpenCode, Codex and more runs the full loop
+immediately. `pitstop install` writes it into your tools; `pitstop prompt` shows the
+exact prompt it expands to. See [Install](#install).
 
-<p align="center">
-  <img src="docs/media/pitstop-gate.gif" alt="The cheat-catch in the real TUI: the gate reads the diff against the sealed baseline and blocks a CONFIRMED_CHEAT with exit 2 — on real opencode output." width="780">
-</p>
+### The GitHub Action
 
-Deterministic, safe to run in a live room, and it's the whole product in miniature:
-**OpenPitStop measures, your agent edits, and the numbers can't be cheated.**
+`uses: openpitstop/action` (or `Krish-1507/OpenPitStop@main`) puts the gate on every PR
+as a comment and a failing check when it matters. No wiring by hand. See
+[docs/github-action.md](docs/github-action.md).
 
-Not even 90 seconds? Point it at **your own repo** — zero setup, no install, no config:
+### The pre-commit hook
 
-```bash
-npx openpitstop try .
-```
+`npx openpitstop install --hooks` installs the gate one step earlier: the commit
+cannot land until the gate passes. See
+[docs/caught-in-the-wild.md](docs/caught-in-the-wild.md).
+
+### Ledger mode (payment proof)
+
+`pitstop scan --ledger` boots your app with every outbound HTTP call rerouted to a mock
+gateway, then replays the classic payment bugs (duplicate webhook, concurrent
+double-submit, delayed retry). If the mock shows more than one charge per idempotency
+key, that is a **proven double-charge**, not a guess.
+
+### CI reports
+
+`pitstop ci` runs a CI-friendly scan plus verify against the base branch and writes a
+PR-ready markdown report, the gate as a PR comment. This is the engine behind the
+GitHub Action.
+
+### Ready-check and doctor
 
-Two seconds of scanning, your repo, your score (plus a one-time package download on the
-first-ever `npx` run — see the speed tip in [Install](#install)). Everything else can wait.
+`pitstop ready-check` answers "is it worth scanning again?" and reuses the baseline when
+nothing changed. `pitstop doctor` explains why a category shows `skipped` and prints
+copy-paste install hints for the tools you are missing.
 
-Real catches — focused tests, deleted tests, edited assertions, tampered baselines — with
-verbatim gate output you can screenshot and share: [Caught in the wild](docs/caught-in-the-wild.md).
+### Digest (progress story)
+
+`pitstop digest` turns your history into a plain-English progress story: how the score
+moved, what got fixed, what regressed, and every cheat it caught.
 
 ---
 
@@ -255,9 +306,9 @@ npx openpitstop
 ```
 
 No arguments needed: the CLI detects your AI tools, and asks what you want —
-install `/pitstop` into them, score *this* repo (`try .`), or watch the 90-second
-demo. Pick, and it does it. (In a non-interactive terminal it skips the
-questions and prints the one-line menu instead.)
+install `/pitstop` into them, or score *this* repo (`try .`). Pick, and it does it.
+(In a non-interactive terminal it skips the questions and prints the one-line menu
+instead.)
 
 Or go straight to the files:
 
@@ -318,7 +369,6 @@ that:
 | `/pitstop` (bare) | **default full loop** | Scans right away, prints the boxed report, one confirmation pause, then the autonomous fix loop — repeat until clean. |
 | `/pitstop --menu` | menu | Prints the full mode list below and **waits** — handy if you forgot the flags. |
 | `/pitstop --scan-only` | scan-only | Runs `openpitstop scan`, prints the entire boxed report verbatim, and stops — no fixes, no commentary. |
-| `/pitstop --demo` | demo | Scaffolds OpenPitStop's seeded broken demo repo into a temp dir, then runs the default full loop there. |
 | `/pitstop --ledger` | ledger | Runs `openpitstop scan --ledger` (boots the app with every outbound HTTP call intercepted and replays duplicate-webhook / double-submit / retry traffic), then runs the loop restricted to the payment findings. |
 | `/pitstop --integrity-only` | integrity-only | Runs `openpitstop integrity`, prints the boxed verdict verbatim, and stops — no scanning, no fixes. |
 | `/pitstop --pen` | pen | Live penetration test with proof — see [The pen test](#the-pen-test). |
@@ -329,9 +379,8 @@ For reference, `/pitstop --menu` shows this list:
 ```
 OpenPitStop modes:
  (enter) — full autonomous loop (scan, confirm, fix, verify, repeat)
- --scan-only — scan and report, no fixes
- --demo — run against OpenPitStop's own seeded demo repo
- --ledger — payment idempotency fuzzing only
+  --scan-only — scan and report, no fixes
+  --ledger — payment idempotency fuzzing only
  --integrity-only — re-check the last commit for cheat patterns, no scanning
  --pen — penetration test: live attacks + proof + fixes (regression tests, patches)
  (your own ask) — reply with anything else, e.g. "check the security of this app"
@@ -341,28 +390,34 @@ A flag after `/pitstop` picks a specific mode; any free-form text after it becom
 custom ask; bare `/pitstop` is the full loop. If a tool ever fails to substitute arguments,
 `/pitstop` behaves as bare — the default full loop — rather than guessing.
 
-No repo handy? `npx openpitstop@latest demo` scaffolds a broken demo repo in a temp dir so
-you can watch the whole loop — self-contained, no installs on the hot path, and it never
-writes into your tool configs (that stays an explicit `pitstop install`).
-
 ## Tool support
 
 | Tool | Installed to | Status |
 |------|--------------|--------|
-| Claude Code | `.claude/commands/pitstop.md` (project + user), plus a Skill at `.claude/skills/pitstop/SKILL.md` | Full support |
+| Claude Code | `.claude/commands/pitstop.md` (project + user), plus a Skill at `.claude/skills/pitstop/SKILL.md | Full support |
 | Cursor | `.cursor/commands/pitstop.md` (project + user) | Full support |
 | OpenCode | `.opencode/commands/pitstop.md` (project), `~/.config/opencode/commands/` (user) | Full support |
 | Kilo Code | `.kilo/commands/pitstop.md` (project), `~/.config/kilo/commands/` (user) | Full support |
 | Antigravity | `.agent/workflows/pitstop.md` (project + user) | Full support |
 | Gemini CLI | `.gemini/commands/pitstop.toml` (project + user) | Full support |
 | Codex CLI | `~/.codex/prompts/pitstop.md` | Full support |
+| FreeBuff CLI | portable `pitstop.md` in your tool's commands folder | Full support (portable) |
+| Grok Build CLI | portable `pitstop.md` in your tool's commands folder | Full support (portable) |
+| MUSE Code CLI | portable `pitstop.md` in your tool's commands folder | Full support (portable) |
+| Any other agent CLI | portable `pitstop.md` (drop it in the commands folder) | Full support (portable) — see below |
 | Codex App / VS Code extension | — (no file written) | **Not supported** — OpenAI hasn't shipped custom slash commands there; install prints a manual-copy note instead |
 | GitHub Action (PRs) | `uses: Krish-1507/OpenPitStop@main` | **Full support** — gate verdict as a PR comment + failing check; see [docs/github-action.md](docs/github-action.md) |
 | git pre-commit hook | `.git/hooks/pre-commit` (installed with `--hooks`) | **Full support** — the gate blocks the commit before it lands |
 
-Legacy/alternate locations are also written where tool docs are inconsistent across versions
-(see `src/installer/targets.ts`). Existing files are never overwritten unless you pass
-`-y`/`--force`; `npx openpitstop install --uninstall` removes everything.
+**Works with any agent CLI.** OpenPitStop's `/pitstop` is a portable command file:
+run `pitstop prompt` to print the exact instruction text, then paste it as a custom
+slash command in any coding CLI that supports them (FreeBuff, Grok Build, MUSE Code and
+others included above). The CLIs listed by name also get a dedicated path written
+automatically by `pitstop install` when their commands-folder convention is known. Tell
+us your CLI and we'll add it to the auto-install list. Legacy/alternate locations are
+also written where tool docs are inconsistent across versions (see
+`src/installer/targets.ts`). Existing files are never overwritten unless you pass
+`-y`/`--force`; `npx openpitstop install --uninstall` removes everything.
 
 ## What OpenPitStop actually does
 
@@ -489,10 +544,9 @@ one-shot.
 | Command | What it does |
 |---|---|
 | `pitstop install` / `install --uninstall` | Writes `/pitstop` into every supported tool (project + user level). `--uninstall` removes it all. `--hooks` also installs (or with `--uninstall`, removes) the git pre-commit gate. |
-| `pitstop` (no args) | The guided first-run: detects your AI tools and git repo, then offers to install, score this repo (`try .`), or run the demo. Non-TTY prints the one-line menu instead. |
+| `pitstop` (no args) | The guided first-run: detects your AI tools and git repo, then offers to install or score this repo (`try .`). Non-TTY prints the one-line menu instead. |
 | `pitstop doctor` | Explains why categories show `skipped`: checks your toolchain (Node, git, jscpd, gitleaks, semgrep, pa11y) and prints copy-paste install hints. |
 | `pitstop prompt [--args …]` | Prints the exact prompt your AI tool expands `/pitstop` into, with your arguments filled in — full transparency into what the agent was told. |
-| `pitstop demo [demo]` | Scaffolds an intentionally-broken demo repo into a fresh temp dir (`demo-repo`, `demo-repo-integrity`, `demo-repo-fintech`, `demo-repo-generators`), initializes git, and scans it immediately. |
 
 ### The score & badge
 
@@ -538,8 +592,7 @@ shows zero clusters (hard limits: 10 fix rounds or 45 minutes), ending with a
 gateway**, then replays the three classic payment bugs: duplicate webhook, concurrent
 double-submit, delayed retry. If the mock gateway's own receipt log shows more than one
 charge per idempotency key, that's a **proven double-charge** — not a guess. The shipped
-`demo-repo-fintech` fixture produces three such PROVEN findings because its charge and
-webhook endpoints have no idempotency guard. If the sandbox can't intercept some traffic,
+If the sandbox can't intercept some traffic,
 the run aborts (`exit 77`); nothing ever reaches a real gateway.
 
 **Which stacks are covered?** Node/JS apps run under the nock preload, which intercepts
@@ -563,14 +616,6 @@ value edited to match the buggy output. A caught cheat looks like this: change
 `CONFIRMED_CHEAT`, the change is blocked, and a human reviews it (verified against
 `fixtures/assertion-literal-tamper/`). An honest app-side fix sails through `CLEAN`.
 
-### Cheat-catch demo
-
-Want to *see* it? The scripted arc from **[See it in 90 seconds](#see-it-in-90-seconds)**
-is `scripts/cheat-demo.cjs` — a fully deterministic SUSPICIOUS → CONFIRMED_CHEAT
-sequence against a real repo with a real failing jest test. Point it at a build with
-`PITSTOP_CLI="node /path/to/dist/cli.js"`, or let it use `npx openpitstop`. Great for a
-video or a live judge's demo.
-
 ## Architecture
 
 OpenPitStop is two pieces that never mix: a **CLI that measures**, and **your host agent that
@@ -582,14 +627,12 @@ cheat its own referee. That separation is the product.
 
 ## Known limitations
 
-- **Windows** is CI-verified on every push (build + smoke on `ubuntu-latest` and
-  `windows-latest`), and the Windows-specific bugs were reproduced and fixed on a real
-  Windows host during development. `watch`, `pen`, `pen --fix` and `scan --ledger` have
-  additionally been run end-to-end on a real Windows host against the demo repos: a live
-  watch delta, PROVEN ledger double-charges with sealed evidence, and honest pen
-  verdicts (including the honest "0 patches" case) all verified. The one remaining
-  caveat is breadth, not correctness: not every exotic repo shape has been manually
-  exercised on Windows.
+- **Windows** is a first-class, CI-verified platform (build + smoke on `ubuntu-latest`
+  and `windows-latest` every push). `watch`, `pen`, `pen --fix` and `scan --ledger` were
+  each run end-to-end on a real Windows host against the demo repos, with a live watch
+  delta, PROVEN ledger double-charges (sealed evidence) and honest pen verdicts
+  (including the honest "0 patches" case) all verified. The only open caveat is breadth,
+  not correctness: not every exotic repo shape has been hand-exercised on Windows yet.
 - **Codex App / VS Code extension** isn't supported and won't be until OpenAI ships custom
   slash commands; use Codex CLI for `/pitstop`.
 - **Graceful degradation:** duplication (`jscpd`), secrets/code scanning (`gitleaks`,
@@ -640,6 +683,17 @@ how to open a PR. For the launch notes and the "why", read [LAUNCH.md](LAUNCH.md
 
 [MIT](LICENSE)
 
+## Support the project
+
+If OpenPitStop saved you from shipping a bug your agent swore was fixed, the best
+support is a star and a real repo:
+
+- **Star** it: https://github.com/Krish-1507/OpenPitStop
+- **Report issues or ideas**: https://github.com/Krish-1507/OpenPitStop/issues
+- **Contribute** an analyzer (small, well-scoped): see [CONTRIBUTING.md](CONTRIBUTING.md)
+
+No donation, no paywall, no telemetry.
+
 ---
 
 <p align="center">

package/demo/DEMO_SCRIPT.md

@@ -93,6 +93,9 @@ A sampling of the 31 symptoms PitStop flags in MiniShop:
 | database | superuser account, `GRANT ALL`, TLS disabled | `src/db.js` |
 | authentication | `password === stored`, `Math.random()` token, `alg:none` JWT, insecure cookie | `src/auth.js` |
 | hidden-vuln | security `TODO`/`FIXME` comments | several files |
+| price-tampering | checkout totals from CLIENT-supplied prices | `src/server.js` |
+| idor | `/api/orders/:id` returns any order, no ownership check | `src/server.js` |
+| prototype-pollution | `lodash.merge` sinks an untrusted request body | `src/server.js` |
 
 The scan also **seals a baseline** — the signed "before" state every later
 check is verified against.
@@ -169,6 +172,38 @@ to your agent. The agent produces exactly the changes in
 
 ---
 
+## 4b. Drift — prove the fix stuck (the permanent referee) — `pitstop pen`
+
+Run `pen` again, this time on the *fixed* app:
+
+```bash
+cd demo/web-app-fixed
+pitstop pen
+```
+
+This run is compared against the last sealed pen run from `web-app-broken`. You
+see the delta, not just a fresh score:
+
+```
+PEN DRIFT  vs .pitstop/pen-latest.json
+  ◐ RESOLVED  pen-… : command-injection (was PROVEN, now gone)
+  ◐ RESOLVED  pen-… : sql-injection
+  (+ any still-open classes, and ESCALATIONS if a static
+   indication became a live proof)
+```
+
+**Why this matters on camera:** most scanners give you a one-off report and walk
+away. OpenPitStop keeps a running ledger of proof. A finding that flips from
+PROVEN to RESOLVED is evidence the fix worked, not hope. And if someone
+reintroduces the bug later, the next `pen` run prints `+1 NEW` and the gate
+exits `1`, so the regression can't sneak into main.
+
+**On-camera:** "Most scanners hand you a PDF and leave. OpenPitStop remembers.
+Watch this finding flip from proven to resolved, and if it ever comes back, the
+gate goes red. That's a referee, not a report."
+
+---
+
 ## 5. Verify it didn't fake it — `pitstop verify`
 
 ```bash
@@ -266,3 +301,49 @@ straight to a finding's file:line + fix.
 > tamper-evident baselines, runtime penetration tests with failing-first
 > regression contracts, and a verification gate that catches the agent lying.
 > The CLI measures; the agent edits; the numbers can't be cheated.
+
+---
+
+## 11. Fix it yourself — the full `pitstop` command sequence (cheat sheet)
+
+Everything you type to take `web-app-broken` from **35/100 (F)** to
+**VERIFIED**, end to end. Copy-paste top to bottom.
+
+```bash
+# 0. baseline — confirm it's broken
+cd demo/web-app-broken
+npm install
+npm test                 # 5 failing — the app is genuinely broken
+npx openpitstop install -y   # register the /pitstop command (one time)
+
+# 1. honest baseline — seals the signed "before" state every later check uses
+pitstop scan
+
+# 2. live pen test + safe patches + failing-first repro tests
+pitstop pen --fix        # writes repro tests + deterministic patches
+pitstop repro SEC-001    # watch a real bug FAIL on camera
+
+# 3a. drive the agent to fix each root cause, one cluster at a time
+pitstop next             # prints the single best next id + the open checklist
+pitstop drive <id>       # fix one root cause; repeat until the checklist clears
+
+# 3b. ...or skip the manual loop and let autopilot run scan -> pen -> verify -> gate
+pitstop fix
+
+# 4. prove the fix stuck (the permanent referee)
+pitstop verify           # exit 0 = VERIFIED; agent-cheat patterns caught
+pitstop pen              # drift: RESOLVED findings vs the broken baseline
+
+# 5. gate + shareable proof
+pitstop gate --score 60  # 1 before the fix, 0 after
+pitstop honesty          # trace every number to a sealed .pitstop/ file
+pitstop report           # shareable HTML/markdown card
+pitstop ci               # drop the same gate into CI
+
+# 6. ship only clean code
+git add -A && git commit -m "fix: remediate MiniShop with OpenPitStop"
+```
+
+The fixed result is already committed for reference in
+[`web-app-fixed/`](./web-app-fixed) — `cd demo/web-app-fixed && DB_PASSWORD=dummy
+JWT_SECRET=dummy npm test` shows all 5 passing.