staysfixed 0.7.1 → 0.8.0

package/README.md

@@ -52,14 +52,22 @@ npx staysfixed check
 No account, no sign-up, no server anywhere, nothing uploaded. It works in any
 project in any language — it only needs to be able to run your product.
 
-Requirements: **Node 22 or newer**. Everything else depends on what you are
-watching, and the tool works out what it has:
+Requirements: **Node 22 or newer**, and **git** — your project has to be a git
+repository. Not for history's sake: git is how an old build is put back on the
+machine to be walked live, and how a difference is measured against the code you
+just changed. A folder with no git in it is refused outright rather than checked
+against a guess. Everything else depends on what you are watching, and the tool
+works out what it has:
 
 ```
 npx staysfixed doctor
 npx staysfixed doctor --json      # the same answer, for an agent
 ```
 
+Everything each kind of product needs — the exact programs, the exact install
+commands, the settings keys and the licences only a person can accept — is in
+[docs/settings.md](docs/settings.md).
+
 `doctor` is the first thing you should run and the first thing an agent should
 call. It says what it can check on this machine, what it cannot, what is missing,
 and the exact command that would fix each gap — and it never suggests setting up
@@ -94,23 +102,27 @@ phone app here to check.
 
 ### What a fresh install downloads, and what it does not
 
-`npm install staysfixed` pulls **two small packages and nothing else** —
-`pixelmatch` and `pngjs`, under a megabyte together. No browser, no runtime,
-nothing that takes minutes.
+`npm install staysfixed` pulls **three packages and no browser** — `pixelmatch`,
+`pngjs` and `playwright-core`, about 13MB together on a Mac. `playwright-core` is
+the part that drives a browser; it is deliberately the version that **downloads
+none**, so nothing here takes minutes and nothing lands in a shared cache behind
+your back.
 
-Checking a **website** needs a browser. Rather than make everybody who only
-wanted to check a command-line tool wait for one, that is a separate step you
-take when you need it:
+Checking a **website** needs an actual browser, and the tool looks for one you
+already have before asking for anything: Chrome for Testing, Chromium, Edge or
+Chrome. If there is none on the machine at all, that is one command:
 
 ```
-npm install --save-dev playwright && npx playwright install chromium
+npx playwright install chromium
 ```
 
-Measured on a Mac in August 2026, that is about **18MB of packages** in your
-project and about **570MB of browser** in a shared cache outside it — 371MB for
-Chrome for Testing and 196MB for its headless shell — downloaded once per
-machine, not once per project. `doctor` tells you when you need it, and it is one
-of the things an agent can simply do without asking you.
+Measured on a Mac in August 2026 that is about **570MB** in a shared cache
+outside your project — 371MB for Chrome for Testing and 196MB for its headless
+shell — downloaded once per machine, not once per project. `doctor` tells you if
+you need it, and it is one of the things an agent can simply do without asking
+you. A project that already drives its own tests with the full `playwright`
+package is used as it is and never asked to install a second copy of the same
+driver.
 
 Checking a **desktop app** needs no browser at all and no download: the app is
 its own Chromium, and the tool drives it over its own debugging port.
@@ -150,21 +162,33 @@ pretend otherwise.
 | The reference cut when you ship, sealed intents, the waiver budget, and escalations in your closing summary | **Works.** This page describes what it actually does. |
 | The coverage ledger — every door counted, the unopened ones named, and the sentence saying so on every reply | **Works.** See [what it did not check](#what-it-did-not-check). |
 | Aiming a check at one kind of product, and refusing by name rather than checking something else | **Works.** |
-| Steps taken from your own test suite, from a recorded session, or rejected at birth for not repeating twice | **Written, not wired.** The code is in `src/v2/journeys/` with tests around it, and nothing on the check path calls it yet. Journeys today come from what each adapter reads out of your source, plus any `--journeys` file you name. |
+| Steps taken from your own test suite | **Works.** `--journeys suite` runs each test file twice inside the scratch copy, reports every check by name and why each failure failed, and stops after 90 seconds naming every file it did not reach. It is opt-in: running a stranger's whole suite twice on every check is not a thing to do by default. It catches what nothing else can — remove the penny-rounding from a `total()` and the product's own output does not move by one character, the discovered journeys say "nothing has changed", and the harvest names the check that turned red. |
+| Steps taken from a recorded session, or rejected at birth for not repeating twice | **Written, not wired.** The code is in `src/v2/journeys/` with tests around it, and nothing on the check path calls it yet. Ask for `--journeys recorded` and you are told so by name. |
 | Android APKs on an emulator | **The adapter is here.** It reads everything the APK declares with nothing installed and no Java, and where there is an emulator it installs one build at a time and walks it. Whether *this* machine can run one is a separate question, and `doctor` asks the adapter itself rather than keeping a second opinion — most of what it wants installs with a command; accepting Google's licence, once, needs a person. Two emulator snapshots restoring byte-identically is unproven, so Android compares against the stored record and says which mode it used. |
 | The iOS simulator | **The adapter is here.** It reads what the app bundle declares with nothing running, and where Xcode and a simulator runtime are present it installs one build at a time, boots it and reads what is on the screen. It is new. Paired running costs two `xcodebuild` passes, so it is for before a release rather than for every edit, and like Android it compares against the stored record and says which mode it used. Ask `doctor` what it is actually covering on your machine before trusting a clean run. |
 | Native Windows GUI (a real Win32 app, not an Electron one) | **The probe is here**, driven over ssh to any machine that reaches a Windows desktop — a WSL shell on one counts, and nothing is installed on it. Windows shows one desktop, so two builds can never run at once: the comparison is genuinely weaker here than anywhere else. |
 
 `staysfixed check` is the front door for both. Version 1's flags still mean
-exactly what they meant yesterday — `--pictures`, `--guards`, `--watch` and
-`--only` reach the same code they always did, on the settings you already have,
-and `staysfixed mcp --v1` still serves the picture tools. Nobody who installed
-this last week has to change anything.
-
-The one thing that did change: `staysfixed init` now writes settings for the
-difference engine. On a product with no screen those settings have no `app` block
-in them, and the picture commands say so plainly rather than telling you to invent
-a web address. Add an `app` block yourself if you want picture checks too.
+exactly what they meant yesterday — `--pictures`, `--guards` and `--only` reach
+the same code they always did, on the settings you already have, and `staysfixed
+mcp --v1` still serves the picture tools. Nobody who installed this last week has
+to change anything.
+
+**Two things did change, and they are worth reading if you installed this before
+today.**
+
+`--watch` moved. `staysfixed check --watch` opens **version 2's** panel — the one
+built for a difference engine, which draws journeys, wobble, findings and a
+verdict. Version 1's panel drew approved pictures side by side, which this tool no
+longer has. `--pictures --watch` and `--guards --watch` still open version 1's
+panel over version 1's run, so the only person whose command changed meaning is
+the one who typed `--watch` on its own and got a picture check they did not ask
+for. Everything about the panel is in [docs/watching.md](docs/watching.md).
+
+`staysfixed init` now writes settings for the difference engine. On a product with
+no screen those settings have no `app` block in them, and the picture commands say
+so plainly rather than telling you to invent a web address. Add an `app` block
+yourself if you want picture checks too.
 
 ## How it proves nothing changed
 
@@ -181,6 +205,18 @@ There is no tolerance setting in version 2 and there is not going to be one.
 Tolerance knobs are how tools like this die — too loose to catch the real thing,
 too tight to leave switched on.
 
+Version 1's picture check is the proof, and it was caught doing exactly that.
+Its default allowed 0.05% of a picture through, with a comment saying that was
+"enough for font hinting noise, nowhere near enough to hide a missing
+stylesheet". On a 2880×1800 screenshot, 0.05% is **2,592 pixels**. Taking one
+letter out of a page's main heading moves **593** — so the check reported
+"Everything that worked still works" over a page anybody could see was wrong.
+Ten fresh takes of that same build differ by **zero** pixels, because the freeze
+layer underneath is thorough enough to make that true. So version 1's default is
+now zero as well: a project whose product genuinely wobbles can set
+`tolerance.pixels`, and every run then says in words how many pixels that
+setting just swallowed.
+
 It also catches a bug class no screenshot tool has ever caught. A path that was
 **steady** in the old build and **wobbles** in the new one means the change made
 something unpredictable. That is a finding, even though no single value can be
@@ -241,13 +277,15 @@ under instrumentation → recorded real sessions → the agent exploring one nam
 gap and freezing it into a replayable file → never a person clicking through an
 app.
 
-What is actually wired into `staysfixed check` today is the first of those and a
-journeys file you point it at: each adapter reads your source and offers the
-journeys it can walk — routes, commands, screens, message channels — and
-`--journeys <file>` names steps by hand. The suite harvest, recorded sessions and
-the flake register are written and tested in `src/v2/journeys/`, and **nothing on
-the check path calls them yet**. Saying so is the point: a feature that exists in
-the repository and not in the run is not a feature you have.
+What is wired into `staysfixed check` today is the first of those, a journeys file
+you point it at, and — when you ask for it — the project's own test suite. Each
+adapter reads your source and offers the journeys it can walk: routes, commands,
+screens, message channels. `--journeys <file>` names steps by hand. `--journeys
+suite` runs each test file twice inside the scratch copy, reports every check by
+name, and stops after 90 seconds naming every file it did not reach. Recorded
+sessions and the flake register are written and tested in `src/v2/journeys/`, and
+**nothing on the check path calls them yet**. Saying so is the point: a feature
+that exists in the repository and not in the run is not a feature you have.
 
 ## Keeping it quiet
 
@@ -338,6 +376,18 @@ verdict reading *nothing that worked has changed*. It is arithmetically true and
 it would let a real regression through. That run comes back as **`NOTHING WAS
 ACTUALLY COMPARED`**, it is not a pass, and it exits non-zero.
 
+**The cold start is the same thing, and it is now marked the same way.** The very
+first run on a project — before anybody has shipped once with the hook in place —
+has no reference at all, rather than a reference with nothing in it. For a while
+only the command line caught that: it said *"Nothing to compare against yet… this
+run proves nothing about what still works"* and exited 2, while `--json` and
+`staysfixed_check` over MCP both carried `ok: true` with none of those words. An
+agent reads the fields, not the sentence, so the two interfaces that matter most
+reported a pass over a run that compared nothing — the exact failure this tool
+exists to prevent, produced by the tool itself. Both now answer `ok: false` with
+**`NOTHING WAS ACTUALLY COMPARED`**. `reference.id` is still worth reading — an
+empty string means nothing was compared, whatever else a reply says.
+
 ### The silences that were found and closed
 
 Every one of these left something invisible while the answer looked complete —
@@ -364,6 +414,35 @@ to ask the question a different way.
 | Ask a machine `command -v powershell.exe` over ssh to find out whether Windows sits behind it — a question that answers "no" on a machine with Windows right there, because that path is added by an interactive login shell and ssh does not run one. It also read a **refusal** as an answer, so `github.com` was listed as a machine to run checks on, and as a Windows desktop | Asks the filesystem for the three places PowerShell actually lives, using the one list the code that later drives it uses. Reads standard output only, and matches the whole line, so a host that quotes your command back cannot answer for itself |
 | Name only the first eight machines in an ssh config and drop the rest without a word | Dials sixteen, and anything past that is named as not dialled rather than left out |
 | Report Docker as present because the command is on the path, on a Mac where Docker Desktop is shut and nothing it promises would work | Asks the engine for its version, and says "installed but not answering" when that is the truth |
+| Read the **commented-out examples** in a settings file as settings. `staysfixed init` comments out every option that does not apply to your project, so nothing is hidden from you — and doctor searched the raw text. On a folder holding one script it announced "Electron desktop apps: **Covered.** It opens release/mac-arm64/Your App.app", and an Android app beside it. A surface called covered when nothing will ever be walked on it is the worst answer this tool can give | Comments are taken away before anything is read out of the file, with strings respected so an address keeps its two slashes. The file is still never loaded — doctor must not run your code to answer a question about your machine |
+| Ask for a build step on a plain command-line tool. A script that runs from source is recorded as "not built", because there is nothing to build, and that was read as "it has not been built yet" — so a fresh install told its owner to name the command that builds a file sitting right there, in the same breath as offering to run it | Nothing is asked for when there is nothing to build, or when a command to run it has already been worked out |
+
+### The silences that are still open
+
+The table above is the honest half of a habit, and it would be a dishonest half
+on its own: it lists what was found and closed, which reads as though nothing is
+left. These are the ones that are **still open today**, found the same way, by
+reading the code rather than the documentation. Every one of them can end in a
+clean-looking answer, and the file that would close each one is named so nobody
+has to take this on trust.
+
+Seven rows left this table in one night. They are in the closed table above now:
+a wobble storm that needed twelve addresses before it counted, so ten of eleven
+wobbling passed; a desktop control compared to its first 200 characters; an
+unreadable folder losing every page of a website behind it; two screens with one
+name collapsing into one walk; a waiver pinned to the first 40 differences of a
+finding rather than all of them; and three iOS ceilings that stopped counting
+without saying so. What is below is what is genuinely left.
+
+| What is invisible | Where |
+| --- | --- |
+| **What the scratch copy leaves out is left out of *both* builds.** A product that actually needs one of the folders named under `process.skip` fails the same way twice, so the difference engine sees no difference and the run reads clean. The defaults are only caches and reports, and the bar is written down — but a project that adds to that list can hide a real break from itself. | `src/v2/adapters/process.js` — `SKIP_BY_DEFAULT` |
+| **Working out what a repository makes reads at most 300 files, four folders deep, and skips any file over 2MB.** A product it never notices is never configured and never walked, so it is missing from the coverage ledger rather than named in it — the one kind of gap the ledger cannot show you. | `src/v2/detect.js` |
+| **Values nested more than 64 levels deep are compared as "too deep" rather than by their contents.** It will never go quiet about one, but it cannot say what inside it moved. This only ever applies to a value read back off the disk; observations made in this run refuse that depth at the door. | `src/v2/observation.js` |
+| **A change buried in the middle of an output larger than 64KB can be missed.** Both ends are kept and compared along with the exact number of bytes dropped, so a middle that grew or shrank shows up. One that changed without changing length does not. | `src/v2/adapters/contract.js` — `trimForStorage` |
+| **How long anything took is recorded and never compared.** A build that got twice as slow is not a finding. This one is deliberate and permanent — a stopwatch on a shared machine measures the machine at least as much as the product — and a build that *hangs* is still caught, because it is stopped for taking too long and how it finished is compared exactly. | by design |
+| **On Windows and as root, one self-check case cannot run.** It takes away the permission to write, to prove the tool still answers when the disk gives out; neither honours that. The case reports itself as untested rather than as a pass, and the closing line counts it separately. | `src/v2/selfcheck.js` |
+| **The distance from a finding to your edit has three ceilings: 4,000 source files, 8 imports out, and 400KB per file.** Past any of them the ranking for that finding is a guess. It is not silent — a run that hit a ceiling says so and names the files it could not read — but the order is worth less than the rest of the list. | `src/v2/rank.js` |
 
 ---
 
@@ -422,9 +501,12 @@ An agent's only door is a waiver, and it passes four machine-checked gates:
 3. **Five waivers between one ship and the next.** Past five it is not a change
    with side effects, it is a rewrite, and a person looks at a rewrite. Sealing
    another intent does not buy five more.
-4. **Every waiver is fingerprinted to one exact difference** and dies the moment
-   the reference moves. Change the value it was written about and it stops
-   covering anything.
+4. **Every waiver is fingerprinted to the difference it was written about** and
+   dies the moment the reference moves. Change that value and it stops covering
+   anything. The pin is the finding's title, up to twenty of its addresses and up
+   to forty of its differences — see [the silences that are still
+   open](#the-silences-that-are-still-open) for what that means on a very large
+   finding.
 
 Every waiver is counted out loud in the reply. "Nothing changed", "nothing ran"
 and "everything was waived" read identically otherwise, and two of those three
@@ -654,18 +736,69 @@ that is correct**: the picture commands (`status`, `walk`, `approve`, `mark`,
 they need an `app` and say so plainly if there is not one. `staysfixed check`
 needs no `app` at all.
 
-A `staysfixed.config.json` works too, with a declarative `steps` form and no
-functions — so a Rust, Python or Go project can use the tool without anybody
-writing JavaScript.
+### `process.skip` — what to leave out of the scratch copy
+
+Every run works in a **throwaway copy of your project**, so a build can write
+wherever it likes without touching the folder you are working in. That copy is
+cloned rather than copied: on a Mac and on most Linux filesystems it is one call
+per file that moves no bytes at all and shares the blocks until something writes
+to them. Measured on a twelve-gigabyte project, most of it an iOS build folder:
+**41.5 seconds and no disk used.** Where the filesystem cannot clone, it falls
+back to a real copy — slower, never wrong.
+
+If that copy still takes over twenty seconds the run says so and points you here.
+You can name folders to leave behind:
 
-Three fully commented examples are in [`examples/`](examples/):
-[a web app](examples/staysfixed.config.web.js),
-[an Electron app](examples/staysfixed.config.electron.js), and
-[a guard](examples/guards/the-sidebar-still-collapses.js). All three are written
-for the picture check, which is the half that needs an `app`.
+```js
+export default {
+  product: 'your-app',
+  process: {
+    // Folders not worth copying into the scratch build.
+    skip: ['DerivedData', '.gradle'],
+  },
+};
+```
 
-The full reference lives with the code it configures, and the design behind all
-of it is in [docs/how-v2-works.md](docs/how-v2-works.md).
+**The bar for putting something on that list is deliberately high: only things
+that are regenerated on demand and read by nothing.** Caches, coverage reports,
+scratch output. Anything you skip that turns out to matter makes a run pass for
+the wrong reason — and a run that passes for the wrong reason is the single
+failure this whole tool exists to prevent. Build output, `node_modules`,
+lockfiles, fixtures and configuration are all copied, every time, because a check
+that runs against a different set of files than the real product is not checking
+the real product. If you are not sure, leave it in and let the run be slower.
+
+`skip` can only ever **add** to what is already left behind — `.git`,
+`.staysfixed`, `.turbo`, `.nyc_output`, `coverage`, `.pytest_cache`,
+`__pycache__` and `.DS_Store`. There is no way to switch one of those back on,
+because doing so would only ever make runs slower.
+
+A `staysfixed.config.json` works too, with a declarative `steps` form and no
+functions — so a Rust, Python or Go project can use the tool without anybody
+writing JavaScript. It may also live at `.staysfixed/config.js` (or `.mjs`, or
+`.json`) if you would rather not have another file in the root.
+
+**Every option, and what each kind of product needs on the machine**, is in
+[docs/settings.md](docs/settings.md) — every settings key per block, and for each
+surface the exact programs, environment variables, install commands and
+permissions, rather than "you may need Xcode".
+
+**Do not copy an example to set the difference engine up.** Run `staysfixed
+init`: it reads what is actually in your project and writes a settings file with
+every option in it — the ones that do not apply commented out rather than left
+out — filled in from your own code. That is better than any example, because it
+is about your project rather than somebody else's.
+
+The three fully commented examples in [`examples/`](examples/) — [a web
+app](examples/staysfixed.config.web.js), [an Electron
+app](examples/staysfixed.config.electron.js) and [a
+guard](examples/guards/the-sidebar-still-collapses.js) — are all **version 1's
+shape**, for the picture check, which is the half that needs an `app`. Each file
+says so at the top now. Copy one into a project and a plain `staysfixed check`
+will tell you the settings do not name anything to open, which is correct and
+confusing if you were not expecting it.
+
+The design behind all of it is in [docs/how-v2-works.md](docs/how-v2-works.md).
 
 ---
 
@@ -764,10 +897,11 @@ Honestly, so you know before you invest an afternoon.
   normalisation rule for whatever is moving, not by trusting the clean-looking run
   underneath it.
 - **What normalisation rubbed out is not itemised on every run.** The rules are in
-  your repository, they are listed by `staysfixed rules`, and the capture is
-  stamped with which set was used — a run comparing against a record tidied by a
-  different set says so. What it does not yet do is print, per run, every value a
-  rule rewrote. Anything a rule covers is not being watched, and that is the point
+  your repository — one file, `.staysfixed/rules.json`, which you read like any
+  other file in a pull request — and the capture is stamped with which set was
+  used, so a run comparing against a record tidied by a different set says so.
+  There is no command that lists them and no per-run report of what each one
+  rewrote. Anything a rule covers is not being watched, and that is the point
   of the rule; just know that adding a broad one is how you go blind on purpose.
 - **Ranking reads your source, and it gives up on very large trees.** Distance
   from the code you just changed is what sorts the list, and it reads up to 4,000
@@ -798,13 +932,17 @@ Honestly, so you know before you invest an afternoon.
   every journey it was given. Nothing can enumerate every state, and any tool
   claiming otherwise is lying. The coverage ledger names the doors it has never
   opened, so the hole is visible instead of pretended away.
-- **Your own test suite is not walked for you yet.** The code that harvests a
-  project's existing tests as journeys is written and tested in
-  `src/v2/journeys/`, and nothing on the check path calls it. Ask for it —
-  `--journeys suite`, or `journeys: "suite"` over MCP — and you are told that, by
-  name, rather than being given a clean result about steps it silently chose
-  instead. Today the steps come from what each adapter reads out of your source
-  and from a journeys file you point it at.
+- **Your own test suite is walked only when you ask.** `--journeys suite`, or
+  `journeys: "suite"` over MCP, runs each test file twice inside the scratch copy
+  and reports every check by name, why each failure failed, and a fingerprint of
+  the test file itself — so an edited test says plainly that the change is yours.
+  It is off by default because running a stranger's whole suite twice on every
+  check would make this too slow to leave switched on, and a check nobody can
+  afford to run is a check nobody runs. It is held to 90 seconds and **every
+  file it did not reach is named**, one by one, never "some tests were skipped".
+  It earns the ask: take the penny-rounding out of a `total()` and the product's
+  own output does not move by one character — the discovered journeys say nothing
+  has changed, and the harvest names the check that turned red.
 - **No hosted service, no dashboard, no accounts, no teams, nothing paid.** It is
   a command and a folder of files in your repository.
 - **Pictures still do not travel between operating systems.** Text is drawn

package/docs/design-v2.md

@@ -17,10 +17,12 @@
 > servers, source reading, the web, Electron, Android, iOS and native Windows over ssh. The
 > MCP surface is seven tools and it is what `staysfixed mcp` serves.
 >
-> **What is written and not wired:** harvesting a project's own test suite as journeys, and
-> replaying a recorded session. The code is in `src/v2/journeys/` with tests around it and
-> nothing on the check path calls it. Asking for either is refused by name. Journeys today
-> come from what each adapter reads out of your source, plus a journeys file you point it at.
+> **What is written and not wired:** replaying a recorded session. The code is in
+> `src/v2/journeys/` with tests around it and nothing on the check path calls it; asking for
+> it is refused by name. Harvesting a project's own test suite was in this list and is now
+> wired — `--journeys suite`, opt-in, held to a 90-second budget, every file it did not reach
+> named. Journeys otherwise come from what each adapter reads out of your source, plus a
+> journeys file you point it at.
 >
 > **What is permanent and will not change:** nothing irreversible is ever run — it is watched
 > at the call and refused at the effect, and the refusal is reported as missing coverage;
@@ -91,6 +93,13 @@ Where I rejected the alternative: the differential design would let the agent de
 
 ## Platforms, in build order
 
+> **Do not install anything off this section.** These were the *plans* for driving each
+> platform, and four of them were replaced during the build — Appium, UiAutomator2,
+> WebDriverAgent, FlaUI and a Java runtime are named below and **none of them is used**. What
+> each surface actually needs, with the exact command, is in
+> [settings.md](settings.md); what this machine actually has is
+> `staysfixed doctor`. See [what the plan got wrong](#what-the-plan-got-wrong-2026-08-30).
+
 ### 1. CLI tools and libraries
 
 - **Driven by:** Plain child-process I/O: stdout, stderr, exit code, files touched, processes spawned, plus the exported API surface read from the source.
@@ -267,6 +276,17 @@ the README's list of silences. The rule that came out of it is worth more than t
 and match the whole line, because a host that quotes your command back can otherwise answer
 for itself.**
 
+**Four of the tools named for driving the phones and Windows were never used.** The plan
+said Appium 3 with UiAutomator2 for Android, WebDriverAgent for the iOS meaning tree, a Java
+runtime for both, and a .NET probe built on FlaUI for Windows. What shipped needs none of
+them. Android reads the APK directly — **no Java at all** — and drives the emulator through
+`adb`. iOS uses `xcrun simctl` and a small reader compiled at run time with `clang` from the
+Xcode command line tools. Windows sends a PowerShell script down an ssh connection each run
+and installs nothing on the far machine. Every one of those replacements removed a
+dependency rather than adding one, which is why they happened; the cost is that this page,
+left alone, would have an agent installing four things nobody needs. The list that is kept
+current is [settings.md](settings.md).
+
 **The self-check corpus was the best decision in the whole design,** and the reason is not
 the one given here. It was justified as proving the engine catches things. What it actually
 did was catch the engine being *perturbable*: it came back "1 of 9 wrong" with the test suite

package/docs/getting-started.md

@@ -86,10 +86,11 @@ What comes back:
 
 **Where the steps come from, today.** Each adapter reads their source and offers what it
 finds there — routes, commands, screens, message channels — and `--journeys <file>` names
-steps by hand. Harvesting their own test suite and replaying a recorded session are written
-in `src/v2/journeys/` and are **not wired into a run**: ask for `--journeys suite` or
-`--journeys recorded` and you are told so by name. Nothing quietly substitutes different
-steps and hands you a clean answer about them.
+steps by hand. `--journeys suite` adds their own test suite: each test file runs twice inside
+the scratch copy, every check is reported by name, and it stops after 90 seconds naming every
+file it did not reach. Replaying a recorded session is written in `src/v2/journeys/` and is
+**not wired into a run**: ask for `--journeys recorded` and you are told so by name. Nothing
+quietly substitutes different steps and hands you a clean answer about them.
 
 ### 3. Take the first reading
 
@@ -135,6 +136,11 @@ Every check answers with one object. The fields that decide what you do:
   something that used to give the same answer every time stopped doing so.
 - **`blocked`** — the run could not happen. This is neither a pass nor a failure. Never
   report a blocked run as "nothing changed".
+- **`reference.id`** — check this before you believe `ok`. An **empty string** means there was
+  nothing on record to compare this build against, so the run proved nothing at all. It comes
+  back with `ok: true`, because arithmetically nothing came back different — and it is not a
+  pass. It happens on every project until somebody has run `staysfixed ship` once. The command
+  line exits 2 on it; the JSON does not say so in a field yet, so read this one.
 - **`mode`** — `paired` means the old build was booted and walked here, in this minute.
   `stored-record` means it was compared against what the old build wrote down last time,
   which is genuinely weaker. When it is `stored-record`, `modeWarning` holds the sentence to
@@ -209,7 +215,9 @@ Four checks, in order, and they take about a minute:
 2. `staysfixed init --json` returns `ok: true`, and `plan.readiness` has at least one product
    whose state is `ready`.
 3. `staysfixed check --paired` finishes with `blocked` absent and `coverage.paths` above zero.
-   Zero addresses observed means it walked nothing, whatever else it says.
+   Zero addresses observed means it walked nothing, whatever else it says. On a project that
+   has never shipped, `reference.id` will be empty and that run proves nothing — expected, and
+   over as soon as they ship once.
 4. Break something on purpose — change a line of printed text, delete a route — run
    `staysfixed check`, and confirm it names it. Then put it back.
 
@@ -290,6 +298,11 @@ Say these once, when someone asks how much it covers. They are permanent, they a
 | `staysfixed check --selfcheck` | Prove the engine still catches deliberate breakage. |
 | `staysfixed ship` | The build that went out is now what "working" means. |
 
+If you have to write a settings block by hand — something `init` could not know, a second
+product, a journey through a screen — every option is in
+[settings.md](settings.md), together with what each kind of product needs installed on the
+machine and the exact command that installs it.
+
 And the three files, if you ever need to look: `src/v2/detect.js` works out what the project
 is, `src/v2/doctor.js` works out what the machine can do, `src/v2/init.js` turns both into
 settings and a list of what is left.

package/docs/guards.md

@@ -34,8 +34,8 @@ export default {
 ```
 
 They run inside `staysfixed check`, in the same real app the pictures are taken
-from. `staysfixed check --guards-only` runs just the guards, which is much faster
-and is what you want when your edit could not possibly change how anything looks.
+from. `staysfixed check --guards` runs just the guards, which is much faster and
+is what you want when your edit could not possibly change how anything looks.
 
 ---
 

package/docs/how-v2-works.md

@@ -126,15 +126,16 @@ Ranked, because this is the real workload question:
 4. **The agent exploring one named gap** and freezing it into a replayable file.
 5. Never a person clicking through an app.
 
-`--journeys <source>` picks between them — and **two of those five are written and
-not wired.** What a run actually walks today is (1), plus a journeys file you name:
-each adapter reads your source and offers what it finds there, and `--journeys
-<file>` names steps by hand. The suite harvest and session replay live in
-`src/v2/journeys/` with tests around them, and nothing on the check path calls
-them; ask for `--journeys suite` or `--journeys recorded` and you are told that by
-name rather than handed a clean result about steps something else chose. Saying so
-is the point: a feature that exists in the repository and not in the run is not a
-feature you have.
+`--journeys <source>` picks between them — and **one of those five is written and
+not wired.** A run walks (1) by default: each adapter reads your source and offers
+what it finds there. `--journeys <file>` names steps by hand, and `--journeys
+suite` adds (2), the project's own test suite — each file run twice inside the
+scratch copy, every check reported by name, held to a 90-second budget with every
+file it did not reach named. Session replay lives in `src/v2/journeys/` with tests
+around it and nothing on the check path calls it; ask for `--journeys recorded` and
+you are told that by name rather than handed a clean result about steps something
+else chose. Saying so is the point: a feature that exists in the repository and not
+in the run is not a feature you have.
 
 ---
 
@@ -343,12 +344,12 @@ release through on the strength of it.
 | `src/v2/observation.js` | The address space, the channels, `diffCaptures`, `measureWobble`, `subtractWobble`. |
 | `src/v2/normalise.js` | The rules, as data, each carrying `wouldHide` in plain English, and `explain()` so a normalisation can be answered for. |
 | `src/v2/cluster.js` | Many differences, one cause, one finding. |
-| `src/v2/rank.js` | `rankFindings` — furthest from the edit first, sealed classes above everything — plus `sealOf`, `whatChanged`, `importGraph`. |
+| `src/v2/rank.js` | `rankFindings` — furthest from the edit first, sealed classes above everything — plus `classOf`, `whatChanged`, `importGraph`. Which classes are sealed, and the words used to refuse one, live in `src/v2/sealed.js`. |
 | `src/v2/cause.js` | `proveCause` — revert the suspect hunk, run again, and find out. |
 | `src/v2/store.js` | The append-only capture files, build records, references, and reading a torn file without losing the rest. |
 | `src/v2/run.js` | `runCheck` — the loop, over any `CheckEngine`. |
 | `src/v2/check.js` | `check` — the assembled front door. The command line, the MCP server and the self-check corpus all look for it here, on purpose: if they found the engine in different places they would be checking different things and reporting it as one. |
-| `src/v2/selfcheck.js` | The corpus of deliberately broken builds, and `runSelfcheck`. |
+| `src/v2/selfcheck.js` | The corpus of deliberately broken builds — `CASES` — and `selfcheck`. |
 | `src/v2/adapters/` | One per surface. The only place that knows what a browser or a child process is. |
 | `src/v2/mcp/` | The tools an agent calls. |
 | `src/v2/cli.js` | `V2_COMMANDS`, `run`, `doctorRun`, `checkOptions`, `report`. |

package/docs/mcp.md

@@ -91,9 +91,14 @@ Every client that speaks MCP over stdio wants the same three things — a comman
 its arguments, and somewhere to run it. The JSON block above is the shape almost
 all of them use; translate it into whatever your client's config file looks like.
 
-`staysfixed doctor --json` returns that block already filled in, under
-`wiring.mcp`, and so does `staysfixed_capabilities` with `detail: "full"` — so an
-agent setting this up for somebody never has to copy it out of this page.
+`staysfixed init --json` returns that block **with the project path already filled
+in**, under `plan.wiring.mcp` — so an agent setting this up for somebody can paste
+it straight into the client's config without copying anything out of this page.
+
+`staysfixed doctor --json` carries the same block under `wiring.mcp`, but its
+`cwd` is still the placeholder `"/absolute/path/to/your/project"`: `doctor`
+describes the machine rather than the project, so put the project's real path in
+yourself, or take the block from `init --json` instead.
 
 ### If you have it installed locally
 
@@ -168,11 +173,15 @@ stronger, and the right thing before a release), `against` (compare with a named
 marker or commit), `only` (a list of journey names), `limit` and `offset` (paging
 through the *last* run without running anything again), and `format: "json"`.
 
-`journeys` names where the steps come from. Today that is the default — what each
-adapter reads out of your source — or a path to a journeys file. `"suite"` and
-`"recorded"` are written in `src/v2/journeys/` and not yet wired into a run: ask
-for either and you are told so by name, rather than given a clean result about
-steps something quietly chose instead.
+`journeys` names where the steps come from. The default is what each adapter reads
+out of your source. `"suite"` walks the project's own test suite as well — each
+test file run twice inside the scratch copy, every check reported by name and why
+each failure failed, stopping after 90 seconds with every file it did not reach
+named. It is worth asking for when a change could break behaviour the product's own
+output would never show. You can also pass a path to a journeys file. `"recorded"`
+is written in `src/v2/journeys/` and not yet wired into a run: ask for it and you
+are told so by name, rather than given a clean result about steps something quietly
+chose instead.
 
 ---