staysfixed 0.6.2 → 0.7.0

package/docs/running-it-in-ci.md

@@ -0,0 +1,306 @@
+# Running it where merges happen
+
+*A check that only runs on the author's laptop catches what the author was already looking
+for. The same check on every pull request catches what nobody was looking for — which is
+the whole class of thing this tool exists to find.*
+
+---
+
+## What it does
+
+On every pull request it runs your product twice, boots the commit your branch **forked
+from** on the same machine, walks that too, and reports only what behaves differently. If
+something changed that nobody accounted for, the job fails and the pull request cannot be
+merged on a green tick that was never earned.
+
+Three files make that work:
+
+| | |
+| --- | --- |
+| `.github/workflows/staysfixed.yml` | The job. Copy it into your own project as it is. |
+| `src/v2/ci.js` | Works out what to compare against, runs the check, writes the report, exits with the code that decides the job. |
+| This file | What it can and cannot do up there, and why. |
+
+---
+
+## A build server is a *better* machine for this, not a worse one
+
+Everything Stays Fixed concludes rests on one claim: **the difference was caused by the
+change and nothing else.** That claim is only as good as the machine underneath it.
+
+A laptop has your fonts, your other work, your ports in use, your half-finished experiment
+from yesterday afternoon, and a browser that updated itself last Tuesday. A fresh runner has
+the same fonts every time, the same operating system, nothing else competing for memory, and
+no history. For a difference machine that is worth a great deal.
+
+The tool's own rule — **sequential, never simultaneous** — is easier to keep here too. The
+workflow cancels a superseded run of the same branch rather than letting two builds fight
+over one port.
+
+---
+
+## The one line you must not delete
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+```
+
+`actions/checkout` fetches **one commit** by default. Ask a repository with one commit in it
+what your branch forked from and it says: this commit. So the check would compare your build
+against *itself*, find nothing, and go green — the strongest-looking pass the tool can print,
+meaning absolutely nothing.
+
+Stays Fixed catches that case by name and refuses it, so it fails honestly rather than
+passing dishonestly. But a refusal is not a check. Full history is what makes this work, it
+costs a few seconds, and it is the single most important line in the workflow.
+
+On GitLab the same thing is `GIT_DEPTH: 0`.
+
+---
+
+## How the reference is chosen
+
+There is no stored record on a fresh runner — no folder from yesterday, nothing from the last
+time anybody ran anything. So the reference has to be rebuilt out of what a build server does
+have, which is git. That turns out to be enough, because a check can be aimed at a commit and
+`git archive` puts that commit back on the machine without touching your working tree or
+your `.git`.
+
+`referenceForCI()` works down this list and stops at the first one available. **It always says
+which rung it landed on, in the job summary, because they are not equally strong.**
+
+| Mode | How it is found | Worth | When it applies |
+| --- | --- | --- | --- |
+| **named** | Somebody passed `--against v1.2.0` | strong | Whenever you say so |
+| **merge-base** | `git merge-base` between the base branch and yours | strong | Pull requests. The right answer, and the default |
+| **released** | The commit your project's own reference points at — what somebody said *ship* to | strong | Pushes to a main branch |
+| **last-tag** | The most recent tag in this history | fair | No pull request, no reference recorded |
+| **previous-commit** | What the branch was immediately before this push | fair | Nothing else available |
+| **stored-record** | Observations committed in `.staysfixed`, or restored from a cache | weak | No commit could be booted at all |
+| **none** | Nothing | nothing | Reported as a failure, never as a pass |
+
+**Why merge-base is the right one for a pull request.** It compares what *your branch* did.
+Comparing against the last release instead would drag in everything else that landed on the
+base branch while your pull request was open, and hand you a list of differences your branch
+is not responsible for.
+
+Every mode that names a commit runs **paired**: the old build is put back on the runner and
+walked live, minutes after the new one, on the same machine. That is the strongest answer the
+tool has, and CI is the one place where paying for it costs nobody any waiting.
+
+Any candidate that turns out to be the commit under test is thrown away, whichever rung it
+came from. Comparing something against itself proves nothing and reads like a perfect pass.
+
+---
+
+## What comes out
+
+The job summary carries a plain-English table, then what changed, then what it did **not**
+look at — that last part on a clean run as well as a dirty one, because a gap only mentioned
+when something fails is a gap nobody ever sees.
+
+The exit code decides the job:
+
+| Code | Means |
+| --- | --- |
+| **0** | Nothing that already worked has changed. |
+| **1** | Something changed that nobody accounted for. |
+| **2** | The check could not run, or there was nothing to compare against. |
+
+**Two is not a pass.** A run that proved nothing exiting zero is the exact failure this whole
+tool exists to prevent, and it would be an easy and invisible one to ship. So the workflow has
+no `continue-on-error` on the check step, and it should stay that way.
+
+---
+
+## What it cannot do up there, and why
+
+**It never approves anything.** A build server cannot say what "working" means — only a
+person shipping can. CI reports; it does not bless. Nothing in `ci.js` cuts a reference,
+writes a waiver, or records a build in a way that would let one be cut later, and nothing in
+it ever should.
+
+**It never writes your project's record.** Observations from a pull request job were taken on
+a machine nobody will see again, off a branch nobody has merged. Letting them become "what
+the old build did" would move the standard sideways every time a runner changed. So the check
+runs with remembering switched off, and the report says so at the bottom.
+
+**Pictures are tied to the machine that took them.** This is the honest caveat and it is
+worth reading twice. Version 2 puts pixels last on purpose — they are evidence for a finding
+another channel already made, never the accusation. That design decision is what lets this
+run in CI at all. A picture taken on your Mac and a picture taken on an Ubuntu runner differ
+in font rasterisation, in sub-pixel antialiasing, in emoji, in scrollbar width, and in a
+dozen other ways that have nothing whatever to do with your code. Compare those two directly
+and every screen is "different", every run is red, and within a week somebody switches the
+whole thing off.
+
+Two things keep that from happening here. Both builds are walked **on the same runner**, so
+their pictures are taken by the same machine and the comparison is fair. And the first six
+channels — what the interface says a control does, what calls went out, what it complained
+about, what it gave back, what the source declares, and the coarse counts — do not care what
+machine they ran on at all. Those are what a CI run is really made of.
+
+The consequence, said plainly: **never compare a picture taken on a laptop against a picture
+taken on a runner.** That is the `stored-record` mode, and it is marked weak for exactly this
+reason. If the stored record was taken on a machine like this one the report says so; if it
+was taken somewhere else the report says *that*, in those words, at the top.
+
+**There are no pictures in the artifact.** The engine writes its evidence images into a
+scratch folder and clears that folder when the run ends, so nothing is left to collect by the
+time the job packs up. The artifact holds every observation both builds produced as JSONL,
+the verdict, and what it compared against — which is the real evidence and is enough to work
+out what happened after the runner is gone. An empty folder called `evidence` would be worse
+than saying this.
+
+**Anything irreversible is refused, not run twice.** Money, sign-in, a message going out, a
+migration that destroys data — observed at the call boundary, never at the effect, and
+reported as missing coverage. That is the same everywhere; it is only worth repeating here
+because a build server is exactly where somebody would be tempted to point this at a staging
+system with real credentials in it. Do not.
+
+---
+
+## Making a stored record worth something (optional)
+
+The `stored-record` mode is weak mostly because the record usually came from somebody's
+laptop. There is one arrangement that fixes that, and it is the one thing CI can do here that
+a laptop cannot do as cleanly: **take the record on a runner, so every later run compares
+against observations from an identical machine.**
+
+Add a second job that runs on pushes to your main branch, passes `--remember`, and caches the
+result:
+
+```yaml
+  record:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: '22' }
+      - run: npm ci || npm install
+      - run: node node_modules/staysfixed/src/v2/ci.js --remember
+      - uses: actions/cache/save@v4
+        with:
+          path: .staysfixed/v2
+          key: staysfixed-${{ github.sha }}
+```
+
+and restore it in the check job with `actions/cache/restore@v4` before the check step.
+
+`--remember` is a deliberate flag and not a default, because getting it the wrong way round
+would turn every red pull request into the new definition of working. **Only ever pass it on
+a branch that has been merged.**
+
+This is worth setting up only if you cannot get a full history — with `fetch-depth: 0` the
+paired merge-base run is stronger than any stored record, and needs no cache at all.
+
+---
+
+## Not on GitHub?
+
+`ci.js` reads GitLab and CircleCI too, and falls back to plain git when it recognises
+neither. There is nothing GitHub-specific in the check itself — only the job summary page,
+which GitLab and CircleCI do not have, so on those the report goes to the job log and to
+`.staysfixed/ci/summary.md` in the artifact.
+
+**GitLab.** `CI_MERGE_REQUEST_DIFF_BASE_SHA` is the fork point already worked out, so GitLab
+is the one server that gives the strongest mode away for free:
+
+```yaml
+staysfixed:
+  image: node:22
+  variables:
+    GIT_DEPTH: 0            # read the section above before removing this
+  script:
+    - npm ci
+    - node node_modules/staysfixed/src/v2/ci.js
+  artifacts:
+    when: always
+    paths: [.staysfixed/ci, .staysfixed/v2]
+```
+
+**CircleCI** tells a job that a pull request exists and refuses to say which branch it is
+aimed at, so the base is worked out from git — `origin/main` and `origin/master` are tried.
+Pass `--against` if your main branch is called something else.
+
+**Anywhere else, or by hand.** It is one command and nothing about it needs a build server:
+
+```sh
+git fetch --unshallow 2>/dev/null || true      # full history, however you get it
+npm ci
+node node_modules/staysfixed/src/v2/ci.js --against "$(git merge-base origin/main HEAD)"
+echo "exit code: $?"          # 0 nothing changed · 1 something did · 2 no answer at all
+```
+
+The report is printed to the log and written to `.staysfixed/ci/summary.md`. Keep that folder
+and `.staysfixed/v2` if you want to look at what happened afterwards.
+
+---
+
+## Calling it from code
+
+```js
+// A file path, not a package name. Stays Fixed does not publish a subpath yet, so
+// `import ... from 'staysfixed/src/v2/ci.js'` will NOT resolve — this form will.
+import { detectCI, referenceForCI, reportForCI, runCI } from './node_modules/staysfixed/src/v2/ci.js';
+
+const where = detectCI();                       // provider, commit, branch, pull request
+const reference = await referenceForCI();       // mode, commit, how strong, what was ruled out
+const { exitCode, report } = await runCI();     // all of it, plus the job summary
+```
+
+The whole surface: `detectCI`, `referenceForCI`, `reportForCI`, `writeJobSummary`,
+`saveEvidence`, `runCI`, `main`.
+
+`referenceForCI()` hands back everything it *considered*, not just what it chose — each mode,
+whether it was available, why not, and the concrete thing that would unlock it. An agent
+reading a weak run can find out what to do about it without being told.
+
+There is no `staysfixed ci` command yet. The command table lives in another file; when it
+gains one it will be `runCI` and nothing else, and this workflow will not have to change.
+
+---
+
+## What is not proven yet
+
+Written down plainly, because a claim about CI made from a laptop is a claim nobody checked.
+
+**No real GitHub Actions job has ever run this.** It could not be run from where it was
+written. Everything below was proved locally by faking the environment variables and by
+running the whole thing against real git repositories on a Mac.
+
+What *was* proved:
+
+- All four environments detected from faked variables — GitHub (pull request and push),
+  GitLab, CircleCI, and neither. The GitHub event file is read for the branch tip, and a
+  pull request is still recognised when that file is missing.
+- **merge-base found correctly** on a real clone with a real branch forked from `origin/main`.
+- **A depth-1 clone caught and refused.** This was a genuine bug found in the writing: a
+  shallow clone answers the fork-point question with HEAD, and the run would have gone green
+  having compared a build against itself. Every mode now throws away a reference that is the
+  commit under test.
+- The whole chain end to end on a scratch project: reference chosen, old build put back with
+  `git archive`, both builds walked, a broken exit code found and sealed as a crash, exit **1**.
+  The same project with the change reverted: exit **0**. A repository with nothing to compare
+  against: exit **2**.
+- The project's git history byte-identical before and after a run.
+- The workflow's YAML parses, and both branches of its setup step were run in `bash -eo
+  pipefail` against a configured and an unconfigured project. That step had a real bug too —
+  one `ls` over both patterns fails whenever either matches nothing, which would have skipped
+  the check on a properly configured project.
+
+What is **not** proved, and would only be settled by a real run:
+
+- Ubuntu. Every local run was on macOS. Nothing in `ci.js` is platform-specific, but that is
+  an argument, not a measurement.
+- The job summary actually rendering. The markdown is written to the file GitHub names; how
+  it looks on the page is unseen.
+- `actions/upload-artifact` picking up `.staysfixed/ci` and `.staysfixed/v2`.
+- Whether a Chromium install is enough for the web adapter on a runner with no display.
+- How long a paired run takes on a real product. On a two-command scratch project it was
+  about a second; a real project with a browser in it will be minutes, and the 30-minute
+  timeout in the workflow is a guess.

package/docs/watching.md

@@ -0,0 +1,190 @@
+# Watching it work
+
+A check is normally something you start and then look away from. `--watch` opens
+a panel and draws the run as it happens — and puts that panel hard against the
+app it is checking, so the two read as one window: your app, and its side panel
+telling you what it is finding.
+
+```
+staysfixed check --watch
+staysfixed walk --watch
+```
+
+Watching it is most of how anybody comes to trust it. Without `--watch`, a desktop
+app under check is moved off the screen rather than opened in front of you.
+
+---
+
+## What the panel shows
+
+This is a product being proven unchanged, so that is what the panel draws:
+
+- **Every journey, in a list**, with the surface each one walks — a page, a
+  command, a screen, a message channel — moving from waiting, to running, to what
+  it turned out to be.
+- **Which build it is being measured against**, and how that build was chosen: the
+  last one you shipped, a marker you named, or the stored record from the last time
+  the old build ran.
+- **Addresses ticking up as they are watched.** That number is the size of the
+  answer: 601 addresses is a different claim from 15,000.
+- **How much wobble was measured and subtracted.** This is the number that explains
+  why the tool is quiet, and no other tool of this kind has one — it is the
+  difference between "nothing changed" and "nothing was looked at".
+- **The findings that survived**, worst first, and separately anything **newly
+  unpredictable**.
+- **What was NOT checked**, in the same window as the good news.
+- **The one or two things only a person may decide**, if there are any.
+
+The terminal still prints everything it always printed. The panel is a second view
+of one run, not a replacement for the first.
+
+`--pictures --watch` and `--guards --watch` open version 1's panel instead — the
+screens, the thumbnails and the approved-versus-now comparison — because that is
+the run they describe.
+
+---
+
+## It attaches itself to your app
+
+When the run opens your app, the panel pushes that window to one edge of the
+screen and puts itself flush against it, filling the space left over. Nothing is
+resized: your app keeps the size it asked for, the panel keeps the width you
+asked for, and the panel keeps its width and its edge, and if the two together are wider than your display the app is pushed off the far edge rather than resized — resizing the thing being photographed would change every picture.
+
+By default the app goes to the **right** edge with the panel down its left.
+`--watch-side left` is the mirror image.
+
+If there is not enough room for both — an app nearly as wide as the display —
+the panel still opens at its full width rather than shrinking to something you
+cannot read. Move one of them, or ask for a narrower panel.
+
+## You can move it, and it stays moved
+
+It is an ordinary window. Grab its edge and drag it wherever you like. Once you
+have moved it, the panel stops placing itself: it will not jump back, and it will
+not be pushed anywhere else for the rest of the run. Where you put it is where it
+stays.
+
+If you would rather it never moved anything in the first place, use `--no-snap`
+and both windows open exactly where they would have anyway.
+
+---
+
+## The flags
+
+| Flag | What it does |
+| --- | --- |
+| `--watch` | Open the panel. |
+| `--watch-side left` | Push the app to the left edge and put the panel on its right. The default is `right`. |
+| `--watch-width 520` | How wide the panel is, in pixels. The default is 480; anything under 240 or over 900 is brought back to the nearest of the two. |
+| `--no-snap` | Leave both windows exactly where they are. Nothing is moved. |
+| `--no-keep-open` | Close the panel the moment the run ends. By default it stays up so you can look at what changed. |
+| `--watch-front` | Bring the panel to the front. See below for why that is not the default. |
+| `--profile` | Nothing to do with the panel: prints where the seconds went after the run. |
+
+Both `staysfixed check` and `staysfixed walk` take all of them.
+
+`--watch` and `--json` ask for opposite things — a window to look at, and output
+for a script to read. Ask for both and the tool says so in one line and carries
+on without the panel, rather than quietly picking one.
+
+You can set any of them once, in `staysfixed.config.js`, instead of typing them
+every time:
+
+```js
+export default {
+  app: { kind: 'web', url: 'http://localhost:5173' },
+  watch: { enabled: true, side: 'left', width: 520 },
+  screens: [/* ... */],
+};
+```
+
+The command line wins over the settings file, with one deliberate exception:
+`--watch` can only ever turn the panel **on**. Not typing it is not the same as
+saying no to it, so it never switches off a panel your settings file asked for.
+
+---
+
+## It comes up once, and then never takes your screen again
+
+The rule is not "stay hidden". An app the tool opens is *allowed* to appear, and
+should — that first appearance is how you see what is happening. **From the moment
+you pick something else, anything the tool launched loses the argument
+permanently.**
+
+That is enforced rather than asked for, because there is nothing to ask. An
+Electron app calls `focus()` from its own main process while it starts, a
+simulator activates when it boots, a browser activates when a window opens — none
+of it goes through this tool. The only thing that works is watching which
+application you are using and putting it back in front the moment something the
+tool started pushes in. It learns which application is yours by watching what you
+choose, never by being told, and it says nothing at all unless it actually had to
+act.
+
+The panel itself opens *behind* whatever you are using and keeps drawing there.
+Bring it forward when you want to look — click it in your dock or task switcher —
+or start the run with `--watch-front` if you would rather it came forward on its
+own.
+
+---
+
+## What it needs
+
+A Chrome-family browser on the machine: Chrome, Chromium, Edge or Brave. The
+panel is a plain HTML page in an ordinary browser window, with no server, no port
+you have to remember and nothing loaded from the internet.
+
+If there is no such browser, or it will not start, you get one line saying the
+panel could not open and **the run carries on exactly as it would have without
+it**. A panel that failed to appear has never changed a verdict and never will.
+
+`staysfixed doctor` tells you what browsers it can find here.
+
+---
+
+## It cannot affect the pictures
+
+This matters more than the feature does, so it is worth being explicit.
+
+The panel is a **separate browser window of its own**, with a throwaway profile.
+It is not injected into your app, it shares no page and no rendering settings
+with the app being photographed, and it never sends anything into it. It only
+reads: the run publishes small events as it goes — this screen started, here is
+its thumbnail, this one changed by four thousand pixels — and the panel draws
+them.
+
+Snapping moves the app's **window**. It never touches the app's page. What gets
+photographed is the viewport the capture sets for itself, which is fixed by your
+settings and has nothing to do with where the window happens to be sitting on
+your desk — so a run watched and a run unwatched reach the same verdict, and the
+pictures are byte for byte the same either way.
+
+The thumbnails in the panel are shrunk copies made after a picture has already
+been taken and compared. Nothing that appears in the panel is ever the thing that
+gets compared.
+
+---
+
+## Where the time went
+
+`--profile` is the other half of this work and needs no window:
+
+```
+$ staysfixed check --profile
+
+...
+
+Where the time went
+  taking the pictures until two agree      11.5s  36%
+  running the steps                        9.5s   30%
+  waiting for fonts and images             7.7s   24%
+  comparing against the approved pictures  2.7s   9%
+  opening the app                          2.4s   8%
+  running the guards                       900ms  3%
+  everything else                          184ms  1%
+  in total                                 31.9s
+  each screen                              2.9s on average, across 11 screens
+```
+
+It is a pointer at the slow part, not a benchmark — the numbers are rounded to
+what a person would say out loud. Run it twice before believing any one figure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Prove that what already worked still works after an agent changed the code. Picture checks, guards for fixed bugs, a pre-release walkthrough, and known-good markers — as a CLI and as an MCP server.",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,7 @@
     "bin",
     "src",
     "examples",
+    "docs",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -54,8 +55,7 @@
   },
   "dependencies": {
     "pixelmatch": "^7.2.0",
-    "pngjs": "^7.0.0",
-    "playwright": "^1.62.1"
+    "pngjs": "^7.0.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/cli/index.js

@@ -11,6 +11,7 @@ import { StaysFixedError, EXIT } from '../core/errors.js';
 import { setLogLevel } from '../core/log.js';
 import { V2_COMMANDS } from '../v2/cli.js';
 import { SHIP_COMMANDS } from '../v2/ship.js';
+import { INIT_COMMANDS } from '../v2/init.js';
 
 /** @type {{version?: string}} */
 const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
@@ -219,25 +220,35 @@ const COMMANDS = {
   },
   mcp: {
     summary: 'Run as an MCP server so a coding agent can check its own work.',
-    usage: 'staysfixed mcp',
+    usage: 'staysfixed mcp [--v1]',
     describe:
-      'Speaks the Model Context Protocol on standard input and output, so Claude Code,\nCodex, Gemini or Cursor can check the screens right after editing your code.\nApproving still belongs to you: an agent cannot approve its own work.',
-    examples: ['staysfixed mcp'],
-    spec: {},
+      'Speaks the Model Context Protocol on standard input and output, so Claude Code,\nCodex, Gemini or Cursor can check your product right after editing it. It serves\nthe difference engine: ask what can be checked here, seal what you meant to\nchange, check, explain one finding, prove a cause, and record one as intended.\nWhat "working" means is never an agent\'s to move — it is cut by shipping, by you.\n\n--v1 serves the older picture-checking tool set instead, unchanged, for anybody\nwho wired that up and is not ready to move.',
+    options: [['--v1', 'Serve the version 1 picture tools instead of the difference engine.']],
+    examples: ['staysfixed mcp', 'staysfixed mcp --v1'],
+    spec: { booleans: ['v1'] },
   },
 };
 
 /*
- * Version 2 takes over `check` and `doctor`.
+ * Version 2 takes over `check`, `doctor` and `init`, and adds `ship`.
  *
  * It is a takeover rather than a second set of names because the answer to "did I
  * break anything" should be one command, not two — and because everything version 1
  * did is still reachable from it: `--pictures`, `--guards` and `--watch` behave
  * exactly as they always have. Anyone who installed this yesterday types the same
  * thing tomorrow.
+ *
+ * `init` was the last one left out, and leaving it out was not a decision — it was
+ * an omission with a cost. docs/getting-started.md is written entirely around what
+ * version 2's `init --json` returns: `plan.project`, `plan.readiness`,
+ * `plan.needs.person`, `plan.journeys`, `plan.covers.short`. Version 1's init
+ * returns none of that and tells whoever ran it to go and approve pictures. So an
+ * agent following this project's own installation page got an answer with none of
+ * the fields the page told it to read.
  */
 Object.assign(COMMANDS, V2_COMMANDS);
 Object.assign(COMMANDS, SHIP_COMMANDS);
+Object.assign(COMMANDS, INIT_COMMANDS);
 
 /**
  * @param {string[]} argv
@@ -273,10 +284,26 @@ export async function main(argv) {
 
   // An MCP server talks JSON-RPC on stdout. One stray friendly line would break
   // the conversation, so the logger is silenced before the server ever starts.
+  //
+  // `mcp` serves VERSION 2 — the difference engine — because that is what every
+  // document about this tool describes, what `staysfixed_capabilities` explains, and
+  // the only surface where an agent can check without being able to approve. This
+  // line pointed at version 1's picture tools for a day, which meant an agent that
+  // followed the README's own wiring block got a set of tools none of the
+  // documentation mentions, and never reached the engine at all. Version 1's server
+  // is still here behind `--v1` so nobody who wired it up is stranded.
   if (command === 'mcp') {
     setLogLevel({ quiet: true, verbose: false });
-    const { serveMcp } = await import('../mcp/server.js');
-    await serveMcp({ cwd, configFile, version: VERSION });
+    if (parsed.flags.v1 === true) {
+      const { serveMcp } = await import('../mcp/server.js');
+      await serveMcp({ cwd, configFile, version: VERSION });
+      return EXIT.ok;
+    }
+    const { serveMcp } = await import('../v2/mcp/server.js');
+    const { rootForConfig } = await import('../core/paths.js');
+    // A `--config` pointing somewhere else names the project, so it decides the root.
+    // Dropping the flag silently would have the server answer about the wrong folder.
+    await serveMcp({ cwd, root: configFile ? rootForConfig(path.resolve(cwd, configFile)) : undefined, version: VERSION });
     return EXIT.ok;
   }
 

package/src/core/config.js

@@ -127,8 +127,18 @@ export function resolveConfig(raw, file = '(inline)') {
   const c = /** @type {import('../types.js').StaysFixedConfig} */ (raw);
 
   if (!c.app || typeof c.app !== 'object') {
-    throw new StaysFixedError('The config has no `app` — Stays Fixed does not know what to open.', {
-      hint: "Add `app: { kind: 'web', url: 'http://localhost:3000' }` or `app: { kind: 'electron', binary: '...' }`.",
+    // Every command that lands here — status, walk, approve, mark, trace, flake, and
+    // `check --pictures` — works by OPENING something and photographing it. A settings
+    // file with no `app` in it is the normal, correct shape for a command-line tool, a
+    // library or a server: there is nothing to open, and telling somebody to go and add a
+    // web address they do not have sends them off inventing one. So the message says which
+    // half of the tool needs it, and names the half that does not.
+    const anything = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (c));
+    const notVisual = ['process', 'http', 'source', 'android', 'ios', 'windows'].filter((k) => anything[k] && typeof anything[k] === 'object');
+    throw new StaysFixedError('These settings do not name anything to open, and this command works by opening your product and photographing it.', {
+      hint: notVisual.length
+        ? `That is the right shape for what this project is — ${notVisual.join(', ')} settings need nothing to open. Run \`staysfixed check\`, which covers it without a picture. If there IS a screen here too, add \`app: { kind: 'web', url: 'http://localhost:3000' }\` or \`app: { kind: 'electron', binary: '...' }\`.`
+        : "Add `app: { kind: 'web', url: 'http://localhost:3000' }` or `app: { kind: 'electron', binary: '...' }`. If your product has no screen at all, `staysfixed check` covers it without one.",
     });
   }
   const kind = c.app.kind;