prismatica 0.2.0

package/dist/guide.js

@@ -0,0 +1,2038 @@
+/**
+ * The built-in user guide. One source of truth: `prismatica guide [topic]`
+ * prints from here, and docs/USER_GUIDE.md is this same content rendered to a
+ * file (a test keeps the two identical forever).
+ *
+ * Written for a non-expert owner: plain words, copy-paste commands, and one
+ * line on what each command does and why you are running it.
+ */
+export const GUIDE_TOPICS = [
+    {
+        id: 'gettingstarted',
+        title: 'Getting started',
+        body: `Prismatica is a safety layer for software that AI agents write for you.
+The agent builds. Prismatica inspects. Nothing ships until the intent, the
+proof, and you agree.
+
+It is not an AI and never talks to one — it trusts only two things: what Git
+says changed, and what your tests prove. Everything it knows is written as
+plain files inside your repo, under \`.prismatica/\`, so you can read every
+record yourself and nothing is locked in.
+
+Install the command once (from the Prismatica source folder):
+
+    npm install && npm run build   # build the CLI
+    npm link                       # put "prismatica" on your PATH
+
+Now \`prismatica\` works in any repo. (If you edit Prismatica's own source
+later, run \`npm run build\` again.) Set it up once per repo:
+
+    prismatica init
+      # detects the tools your repo already has, writes .prismatica/ and the
+      # merge gate, and shows a table of what is Enforced, Checked, or Missing
+
+    git add .prismatica .github .gitignore && git commit -m "adopt prismatica"
+      # the records live in git, versioned with the code they describe
+
+The shortest normal workflow is one conversation and one command, and it
+STARTS IN YOUR CODING AGENT rather than here:
+
+    1. Open the agent you already use and activate Prismatica Start.
+    2. Describe what you need, and settle the plan with it in conversation.
+    3. It reads your repository and hands you one command.
+    4. You run that command, in your own terminal:
+
+    prismatica start --import <proposal.json>
+      # revalidates that plan strictly here against a FRESH reading, shows you
+      # the whole plan and the exact GitHub issue it will file, and asks once:
+      # "Start this change?" (default No). Nothing at all is
+      # created until you say yes to the second one.
+
+Neither command takes your description. You and the agent agree the wording
+between you, and the plan carries it back in its \`request\` field — so the
+contract, the issue and the reviewer all quote the same agreed sentence
+instead of a one-liner you happened to type twice.
+
+That does by itself what \`frame\` + \`pack\` do by hand, and it works when you
+cannot yet name the files involved. \`frame\` is still there for when you know
+exactly what you want (see "manual frame").
+
+Either way the change then follows the same loop, described under "the loop"
+below: start (or frame) → pack → build → check → review → seal → (accept) →
+ship → verify. You do not need to remember any of that, though — whenever
+you're not sure what to run, ask:
+
+    prismatica next
+      # prints the one command to run right now, and why (see "next" below)`,
+    },
+    {
+        id: 'loop',
+        title: 'The loop — one change, start to finish',
+        body: `The whole shape, in one line:
+
+    describe need → your agent plans it → you confirm → start build →
+    Builder → fresh reviewer → deterministic gate
+
+1. Start it — the usual way. In your coding agent, use Prismatica Start: say
+   what you need, settle the plan with it, and it hands you the one command
+   below to run yourself:
+
+    prismatica start --import <proposal.json>
+      # strict local revalidation against a FRESH snapshot → your own words,
+      # the whole plan and the issue text in full → "Start this change?" →
+      # issue, lane, approved intent, Delta or Planned Flow, and the builder
+      # brief. Nothing is created before that yes.
+
+   Steps 2 and 3 below are already done for you at this point — skip to 4.
+
+   Prefer full manual control, or already know the exact scope? Frame it
+   yourself instead (see "manual frame" for every flag spelled out):
+
+    prismatica frame "Add signup validation" --issue "#12" \\
+      --allow "src/signup/**" --check "rejects empty email | signup.test.ts"
+      # writes the contract and opens a safe lane (a separate working copy)
+      # so the agent cannot touch your main checkout
+
+2. Pack it — build the brief you hand to the agent (\`start\` did this):
+
+    prismatica pack <id>
+      # a scoped, self-contained brief; if the contract changes later,
+      # this brief goes stale and Prismatica refuses to use it
+
+3. Open it — hand the brief over:
+
+    prismatica open claude <id>     # opens Claude Code inside the lane
+    prismatica open --copy <id>     # or copy the brief for any other agent
+
+  A known agent is started in the lane with ONE short pointer at the pack and
+  the contract, both of which are already on disk there — never the brief
+  itself, in argv or anywhere else. \`--copy\` is the exception, and the reason
+  for it: a chat agent has no lane to read from, so it gets the full text.
+
+4. Check it — after the agent commits its work in the lane:
+
+    prismatica check
+      # runs your own tools (typecheck, lint, tests, build, journeys, secret
+      # scan) plus Prismatica's own checks: did the diff stay in scope, does
+      # every acceptance check trace to a passing test, were docs updated
+
+5. Review and seal it — fresh eyes on the exact diff:
+
+    prismatica review --agent claude      # a review brief bound to the diff,
+                                          # then a fresh READ-ONLY session on
+                                          # it in the lane
+    prismatica seal                       # binds an APPROVE verdict to it; if
+                                          # the code moves later, the seal
+                                          # breaks and review redoes
+    prismatica seal --request-changes     # the reviewer said no — this stops
+                                          # the change, it does not merely
+                                          # note an opinion
+
+6. Accept it (heavy changes only) — your signed decision:
+
+    prismatica accept
+      # signs your approval over this exact diff with your private key;
+      # the gate verifies the signature — nobody can fake your sign-off
+
+7. Ship it:
+
+    prismatica ship <id>
+      # pushes the exact committed head and opens the pull request; the gate
+      # re-runs everything on GitHub and blocks the merge unless every
+      # requirement holds — including a signed decision, and the changed
+      # files' own risk-tier floor (touching auth/payments/data always needs
+      # at least the tier that implies)
+
+8. Merge it — once the gate is green:
+
+    prismatica merge <id>
+      # an exact-SHA, owner-guarded merge: refuses a draft, missing, closed,
+      # pending, failed, stale, or ambiguous PR, requires a passing
+      # prismatica-gate check for this EXACT head, then merges (--merge only
+      # — never a silent squash or rebase). Reported as "Checked —
+      # owner-guarded": this command is the guard, not a claim that GitHub
+      # itself enforces it (GitHub Free private repos don't offer that)
+
+9. Close it — remove the lane once GitHub confirms the merge:
+
+    prismatica close <id>
+      # requires the exact registered lane, refuses a dirty one, and only
+      # removes the worktree (+ local branch) once GitHub's own record shows
+      # a merged PR at exactly this lane's HEAD — never a remote branch,
+      # never uncertain, never partial-and-unrecoverable
+
+10. Verify it — after the merge deploys:
+
+    prismatica ship <id> --verify --deploy-result "deployed to prod" \\
+      --rollback "revert the PR, redeploy"
+      # runs one live smoke journey; only if it passes is the passport
+      # written: what shipped, its proof, and a tested way back. This writes
+      # onto your main checkout, not the (already-closed) lane
+
+Run each command from inside the change's lane and you can leave the <id> off —
+Prismatica works out which change you mean from the branch. Lost? \`prismatica
+next\` always tells you exactly which of these to run next, including while
+waiting on the gate or a merged-but-not-yet-closed PR.
+
+**Steps 3 to 5 can be driven for you, up to the point where you decide.** Ask
+your coding agent to get the change ready and it runs build → \`check\` → fresh
+review as a bounded loop of disposable sessions, handing back at your next
+decision — the seal in step 5 included. That is a role any agent can take
+(Prismatica packages it where it can — in Claude Code, \`/prismatica:ready\`),
+and it is a convenience rather than a shortcut: every command above still runs,
+and the gate is unmoved by whether one was typed by you or started for you. See
+"roles" for the one owner-only command a controller may run, and why that one
+cannot advance anything.`,
+    },
+    {
+        id: 'next',
+        title: "next — the one command, when you don't know what to run",
+        body: `You do not need to memorise the loop above. From anywhere in the repo:
+
+    prismatica next
+      # prints exactly one command, one reason, and what to run after —
+      # never a guess, never a placeholder you have to fill in yourself
+
+It reads what is already on record — no Flows yet? it says \`discover\`. A
+draft waiting? \`view\`. An approved delta not yet turned into a change?
+\`frame --from-delta\`. Mid-change? whichever of pack / open / check / review /
+seal / accept / ship / merge / close fits where that change actually is right
+now — never \`git add -A\`, always the exact files that changed. Nothing to
+do? "all quiet."
+
+It never runs your checks itself (that would make asking "what's next" as
+slow as a full proof run) — it only reads the record of what already
+happened. The one exception: once you have actually shipped, it makes a
+single read-only check of the PR and its \`prismatica-gate\` check (never
+writes anything back to GitHub) so it can tell "wait for the gate" apart from
+"ready to merge" apart from "merged — go close it". If GitHub cannot be
+reached, it says so honestly and falls back to a safe, retry-able suggestion
+— never a guess dressed up as certainty. Add \`--copy\` to copy the command
+straight to your clipboard.
+
+**Every git command it prints names the directory it belongs in.** \`next\` runs
+from anywhere — main, a lane, a subdirectory of either — so a bare \`git add\`
+would stage whichever worktree you happened to be standing in. The advice is
+always \`git -C <the exact lane> …\`, quoted, so a paste does the same thing from
+every directory.
+
+**It also tells you when main itself has fallen behind.** That sits second from
+last in the order, below real work in a lane and below stale Flow evidence: a
+behind main is housekeeping, and interrupting the change you asked about to
+report it would bury the answer. It outranks only "all quiet", which is the one
+answer it genuinely contradicts — the next change framed from a stale main
+would take a stale baseline, and \`frame\` refuses outright for that reason.
+
+    git -C /path/to/repo pull --ff-only origin main
+
+Nothing is ever pulled for you, and nothing is fetched to work this out: it
+reports what your last fetch already told this repo. If that cannot be
+established — no remote, no upstream ref — it says nothing at all. "We do not
+know" is never printed as "you are behind".
+
+Between \`prismatica view\` (see everything), \`prismatica delta new\` (say what
+should change about a Flow), and \`prismatica next\` (what do I do now), that
+is the whole owner-facing surface — everything else is what those three
+commands walk you through.
+
+**Every \`prismatica\` command above is location-independent.** Run it from
+main, from a lane, or from a subdirectory of either, and it resolves which
+change you mean from the record — never from your current directory. A
+manually opened agent is the one exception: when \`prismatica open <agent>
+--no-spawn\` (or \`review --agent <agent> --no-spawn\`) prints a command instead
+of launching one, or after \`open --copy\`/\`review --copy\` hand you a brief or
+pointer to paste, what you run yourself is a plain agent process, and that
+process inherits YOUR shell's current directory, not Prismatica's resolved
+one. That is why the printed command always starts with \`cd <lane> &&\` —
+quoted, so a lane path with a space or a quote in it still reaches \`cd\` as one
+argument — and why it carries \`PRISMATICA_EXECUTOR=agent\`: a spawned launch
+always sets that marker, and a hand-run missing it would look, to Prismatica,
+like you at your own terminal rather than the agent it is. Paste the printed
+line as-is; Prismatica never runs it for you, never changes your shell's own
+directory, and never opens a nested shell to do so.
+
+**One special case: Prismatica's own repository — a self-host EXCEPTION, not
+an ordinary application workflow.** If the lane being advised is a checkout of
+Prismatica itself, the \`prismatica\` on your PATH is some other copy, and
+running it would exercise code the lane does not contain. There, \`next\`
+(and \`doctor\`) name the lane's own build instead, in whichever of three
+states that checkout is actually in — never a guess, and never something
+Prismatica installs or builds on your behalf:
+
+    cd <lane> && npm ci           # no node_modules yet — install first
+    cd <lane> && npm run build    # installed, but dist/cli.js is not built
+    cd <lane> && node dist/cli.js …   # ready — runs the lane's own build
+
+Only the third line is ever \`prismatica\`'s advice rewritten to point at code;
+the first two are the ONE exact recovery for that lane's state, never chained
+onto a command that cannot yet run. \`next\` also prints where both copies
+live, without claiming either is newer, because nothing here can know that.
+This is advice and nothing else: no gate, no checksum, no version handshake,
+and — outside this one narrow exception — \`npm ci\`/\`npm run build\` are never
+part of Prismatica's own advice for an ordinary application repository.
+Ordinary repositories, and every \`git\` or \`gh\` command, are untouched.
+
+Every command that acts on a change says the same thing once — one note on
+stderr, the first time, only in Prismatica's own repository and only when you
+are at a terminal. Piped output, CI and every other repository print nothing.
+\`prismatica doctor\` states it plainly too: which checkout holds the build
+that produced the report, and which checkout the report is about. None of it
+changes a single check result.`,
+    },
+    {
+        id: 'understandapp',
+        title: 'Scenario — understand an app you already have',
+        body: `You have an app. You want to know what it actually does today, and how much
+of that is genuinely proven rather than assumed. Start here.
+
+    In your coding agent, use Prismatica Understand: ask it to map this app.
+    It reads the real code and describes it as Flows (routes through your app)
+    and Rules (things that must stay true), saves a json answer, and hands you:
+
+    prismatica discover --import <proposal.json>
+      # materialises that answer as proposals. It proposes; nothing is
+      # accepted automatically.
+
+    prismatica flow list
+      # what the app does, in reading order, grouped by journey when your
+      # records say which journey they belong to
+
+A Flow is one complete route through your app — "log a practice session",
+start to finish. The list leads with a short title and a one-sentence outcome,
+and it stays quiet unless something needs you: a stale step, an unverified
+flow, a pending update, or an open change that touches it.
+
+Read one properly:
+
+    prismatica flow show log-a-practice-session
+      # the story: what it is for, where it starts and ends, what happens in
+      # order, and how solid the evidence is
+
+Then accept what is right and discard what is not:
+
+    prismatica flow approve log-a-practice-session
+    prismatica flow dismiss  guess-at-billing
+
+Same for the app-wide guardrails:
+
+    prismatica rules list             # every rule's complete text, wrapped
+    prismatica rules list --details   # plus which flows cite each one
+    prismatica rules approve offline-first
+
+Prefer to read in a browser? \`prismatica view\` opens the same Flow Map and
+Storyboards, backed by exactly the same data.`,
+    },
+    {
+        id: 'changeflow',
+        title: 'Scenario — change something an existing Flow does',
+        body: `The app already does something, and you want it to do something different.
+Say it in Flow language first — before anyone writes code.
+
+A Delta is one sentence of intent: which flow, what happens today, what should
+happen instead, and what must not change.
+
+    prismatica delta new \\
+      --flow log-a-practice-session \\
+      --today "Saving a session with an empty title succeeds silently" \\
+      --instead "An empty title is rejected with an inline message" \\
+      --keep "Offline saving still queues and syncs later" \\
+      --show-me "A test that saves an empty title and expects a rejection"
+
+    prismatica delta list          # what has been proposed
+    prismatica delta approve <id>  # this is the change you want
+
+Approving a Delta does not touch the Flow — it records the intent. Turn it
+into a contract and a safe lane to build in:
+
+    prismatica frame --from-delta <id>
+
+From there it is the ordinary loop (see "loop"): the agent builds in the lane,
+\`prismatica check\` proves it, \`review\` and \`seal\` bind fresh eyes to the
+exact diff, and the Flow itself only changes when an agent PROPOSES an update
+and you run \`prismatica flow approve\`. No lane can ever write an approved
+Flow directly.
+
+While the change is open, every affected Flow says so on the Flow Map and in
+\`flow list\` — "Directly affected by open change …" — so you are never
+reading a map that quietly went out of date.`,
+    },
+    {
+        id: 'newflow',
+        title: 'Scenario — define and approve a new Planned Flow',
+        body: `Something the app does not do yet, but should. Write it as a Planned Flow so
+it is visible and reviewable before a single line exists.
+
+Ask your agent to draft it (a proposal file under
+\`.prismatica/flows/proposals/\`), with \`status: planned\` and a truth block:
+goal, starts when, needs, steps, ends with. A realistic one:
+
+    id: export-a-practice-log
+    status: planned
+    truth:
+      goal: Export a practice log as a CSV file a coach can open
+      startsWhen: The user taps 'Export' on the history screen
+      needs:
+        - They are signed in
+        - At least one session exists
+      steps:
+        - actor: User
+          action: chooses a date range and taps Export
+          shows: A progress row while the file is built
+        - actor: App
+          action: writes the CSV and hands it to the share sheet
+          shows: The system share sheet with the file attached
+          changes: An export record with the row count and range
+      endsWith: The coach receives a CSV that opens cleanly in a spreadsheet
+
+Then review and accept it exactly like any other proposal:
+
+    prismatica flow show export-a-practice-log    # read it as a story
+    prismatica flow approve export-a-practice-log # sign it as approved truth
+
+Approving records a fingerprint of the truth block and, in a governed repo,
+signs it with your key. A Planned Flow shows as "Planned" everywhere until it
+is real; when it is, flip it in one command — no ceremony, because the honest
+guard is the visible evidence, not a lock:
+
+    prismatica flow status export-a-practice-log works
+    prismatica flow verify export-a-practice-log --step 2`,
+    },
+    {
+        id: 'proof',
+        title: 'Scenario — inspect the proof, and the code behind it',
+        body: `The default story is deliberately short. When you want to interrogate it, open
+one layer at a time — the flags compose, and nothing is hidden that you cannot
+ask for.
+
+    prismatica flow show prove-a-change-with-check
+      # the owner story: outcome, start/end, steps in order, evidence summary
+
+    prismatica flow show prove-a-change-with-check --proof
+      # how EVERY step was verified: manually, by test, inferred from the
+      # code, or not at all. Evidence attaches to the exact step, never to
+      # the whole flow, so one passing test can never read as "it all works".
+
+    prismatica flow show prove-a-change-with-check --details
+      # the assumptions each step relies on. Every guardrail's complete text
+      # is already shown, with no flag needed — never clipped to a label
+
+    prismatica flow show prove-a-change-with-check --code
+      # where it lives: touchpoints, routes, components, entities, tests
+
+    prismatica flow show prove-a-change-with-check --json | jq '.steps[].result'
+      # the same view as stable JSON, for scripts
+
+"Stale" is the word to watch for. A step is stale when the code it depends on
+changed after the last time that step was verified — the record is not wrong,
+it is simply no longer known to be right. Re-confirm it yourself with:
+
+    prismatica flow verify prove-a-change-with-check --step 3
+
+Only real implementation and test changes count. Approving or dismissing a
+Flow/Rule proposal elsewhere in the repo touches files under \`.prismatica/\`,
+and that alone never stales a step's evidence — even for a Flow (like this
+one, or "Map the app with atlas discovery") whose own mechanics legitimately
+live under \`.prismatica/\`. Only a later change to the actual code or test
+files a step is mapped to does.`,
+    },
+    {
+        id: 'mergepath',
+        title: 'Scenario — merge on a private repo with no branch protection',
+        body: `GitHub Free does not offer required status checks on private repositories.
+Prismatica does not pretend otherwise: it gives you an owner-guarded merge
+path and describes it honestly as "Checked — owner-guarded", never as
+"enforced by GitHub".
+
+    prismatica ship 20260728-add-signup-validation-a1b2
+      # pre-flights the gate locally, requires an exact clean lane HEAD,
+      # pushes that exact commit, and opens (or reuses) the pull request
+
+The gate then runs on GitHub for that push, in a clean checkout: scope, tests,
+docs, the sealed review, your signature where the risk tier demands one.
+
+    prismatica merge 20260728-add-signup-validation-a1b2
+      # the guard. It refuses a draft, missing, closed, pending, failed,
+      # stale, or ambiguous PR, and requires a PASSING prismatica-gate check
+      # for this exact head commit before calling gh pr merge --merge —
+      # never a silent squash or rebase, never a merge of a different SHA
+      # than the one that was proven
+
+    prismatica doctor
+      # tells you plainly which level of assurance you actually have:
+      # absent, unexercised, "Checked — owner-guarded", unavailable on this
+      # plan, unknown, or genuinely server-enforced
+
+Know exactly what that compromise buys you, and what it does not.
+\`prismatica merge\` is exact-head and owner-guarded: it will not merge anything
+but the exact commit a passing prismatica-gate check covers. What it cannot do
+is guard a route it never runs on. Without server-side protection, merging the
+pull request in the GitHub browser UI, or pushing straight to main, is still
+possible — Prismatica is the guard you choose to walk through, not a locked door.
+
+On a private GitHub Free repo, doctor says "unavailable on this plan" and
+prints no settings fix, because there is no setting to change. That is not a
+failure of yours, and it does not count against your adoption score.
+
+If GitHub cannot be reached, both commands fail closed and say so. An unknown
+state is never treated as a green one — and, just as importantly, it is never
+reported as an absent one. "We could not ask GitHub" reads as "unknown", never
+as "this branch is unprotected".`,
+    },
+    {
+        id: 'verifyclose',
+        title: 'Scenario — verify the live deploy, then close the change',
+        body: `Merged is not the same as working. Close the loop in that order: merge, close
+the lane, deploy, then prove the deploy.
+
+    prismatica close 20260728-add-signup-validation-a1b2
+      # removes the lane ONLY once GitHub's own record confirms a merged PR
+      # at exactly this lane's HEAD. It refuses any real uncommitted work,
+      # and refuses ignored local files it cannot prove are disposable — a
+      # local .env, a log, an evidence blob, or a hand-edited hook survives.
+      # It never deletes the remote branch.
+
+A successful \`close\` always ends by telling you to catch main up, because the
+merge happened on GitHub and this checkout has not seen it yet:
+
+    git -C /path/to/repo pull --ff-only origin main
+
+That prints every time, not only when something went wrong — an owner told
+nothing discovers the staleness at the next \`frame\`, which refuses. If the
+local branch could not be deleted (git refuses a \`-d\` while the checkout has
+not seen the merge), the safe delete is printed too, and only AFTER the pull
+that makes it possible. It stays \`-d\`, never \`-D\`: if git still refuses
+afterwards, there really is unmerged work there. Nothing is pulled for you.
+
+Deploy however you normally deploy. Then, and only then:
+
+    prismatica ship 20260728-add-signup-validation-a1b2 --verify \\
+      --deploy-result "deployed to production at 14:20 UTC" \\
+      --rollback "revert PR #48 and redeploy image v1.9.3"
+      # runs one live smoke journey against the real app; the passport is
+      # written only if it passes
+
+No passport is written for a broken deploy. The rollback route recorded is one
+you actually described, because the only rollback worth having is one somebody
+has thought through.
+
+\`--verify\` proves the change against the ONE commit that merged, and it stays
+provable however long you leave it. It requires GitHub to confirm the PR merged,
+into your configured main branch, from this contract's own branch; that the
+merged head produces exactly the patch-id your proof covers (the approved sealed
+review above \`light\` tier, the passing check's own commit at \`light\`); and
+that exactly one \`prismatica-gate\` check ran on that head and passed. Missing,
+pending, failed, ambiguous, or unreadable gate evidence all refuse, before the
+smoke journey and before anything is written.
+
+It does NOT re-run the local gate. That question decays: after the merge it
+would compare your baseline against whatever main is today, so every change
+that merged after yours would count as your out-of-scope files. The gate's own
+recorded result on your exact merged head is the honest replacement — and a
+real one, since without GitHub branch protection a PR merged in the browser
+never had to satisfy any check at all.
+
+Unsure where you are in that sequence at any point:
+
+    prismatica next
+      # reads the PR and its checks read-only and names the single next
+      # command — or says the state is unknown, if GitHub cannot be reached`,
+    },
+    {
+        id: 'abandon',
+        title: 'Scenario — stop a change you are not going to finish',
+        body: `Not every change should be finished. The requirement evaporated, the approach
+was wrong, or you started two and only want one. Abandoning is a first-class
+ending, not a failure to clean up after.
+
+    prismatica abandon 20260728-add-signup-validation-a1b2 \\
+      --reason "the customer withdrew the request before we started building"
+
+The reason is required, because it is the only part of an abandoned change that
+stays useful a year later.
+
+What it does, in this order:
+
+1. **Settles the pull request first.** If one is open, it is closed on GitHub
+   before anything else happens — a lane taken away while its PR still passes
+   the gate leaves work anyone can merge, with nobody left who intends to
+   review it. If gh cannot tell whether a PR exists, the command stops and
+   changes nothing: "there is no PR" and "we could not find out" are different
+   facts, and only the first is safe to act on. A PR that already merged is
+   refused outright — that change shipped, so \`close\` is the command, not
+   this one.
+2. **Closes the linked issue**, best effort. If that fails you are told so,
+   with the command to do it yourself. It never fails silently.
+3. **Archives the records to git history** — the contract, the approved plan,
+   the brief, the linked delta and a planned Flow proposal, whichever exist.
+   This is the one place Prismatica commits for you, and it is deliberate: the
+   records of a freshly started change are usually still uncommitted, and
+   removing the lane would destroy the only copy of them. Anything else in the
+   lane refuses the whole command — your own uncommitted code, a conflict, a
+   file that does not parse as the record its name claims, or an ignored local
+   file like a \`.env\` that the removal would delete.
+4. **Removes the lane**, and only then.
+
+**Nothing is deleted.** The local branch is retained, and any remote branch
+that already existed for it is left untouched — abandon never pushes or
+deletes one. The command ends by printing how to bring the lane back:
+
+    git -C /path/to/repo worktree add /path/to/repo-lanes/<id> change/<id>
+
+Everything is exactly where you left it, plus one commit saying why you
+stopped. Changing your mind is a supported outcome.
+
+There is no lifecycle stage for this on purpose: abandoning is leaving the
+sequence, not a step along it.`,
+    },
+    {
+        id: 'startbug',
+        title: 'Scenario — something is broken and you do not know where',
+        body: `You have a bug. You can describe what you see, but you do not know which
+files are involved, whether it touches a Flow, or how risky it is. That is
+exactly the normal case, and it is what \`start\` is for.
+
+Open the agent you are already using, activate Prismatica Start, and describe
+it in your own words — "exporting a session over about 10MB does nothing at
+all, no file, no error". Settle it with them there: that conversation is where
+the questions get asked and answered.
+
+The skill then reads your repository for itself. It does that through
+\`prismatica context start\`, which writes ONE json file to a private temporary
+directory — outside your repository, so it never shows up in \`git status\` and
+never blocks a check. It contains a read-only snapshot of your repo (the exact
+commit, every Flow and its truth hash, every Rule, what is already pending,
+what changes are in flight), plain-language instructions, and the exact schema
+the answer must match. You do not normally run that command yourself; see
+"prismatica guide handoff" for when you would.
+
+Prismatica does not run that agent. It has no adapter to keep working, no
+provider dialect to translate, and no session to leave behind — which is also
+why there is nothing to fall back to when an agent is missing or a version
+changed. Any agent that can read a file and write JSON can answer.
+
+When it saves an answer, you import it:
+
+    prismatica start --import ~/plan.json
+
+The plan carries the wording you both agreed (\`request\`) and who will build it
+(\`builder\`), so neither is retyped here and neither can quietly differ from the
+plan you are about to approve.
+
+What happens then, in order:
+
+1. Prismatica takes a **fresh** reading of the repository and revalidates the
+   plan against it: no unknown fields, no absolute paths, no \`..\`, no secret
+   files, every Flow id it cites must really exist, every acceptance check must
+   name a real test file or \`manual:OWNER\`, and the risk tier is recomputed
+   from the files it proposes to touch. An agent can raise the tier; it can
+   never lower it. Nothing the imported document says is ever taken as fact
+   about your repo — the document is checked against the repo, not the reverse.
+2. The plan also echoes the whole snapshot it was written against. Prismatica
+   recomputes that snapshot's id from its own contents, so an echo nobody
+   actually exported is refused; what it is then used for is one thing only —
+   telling you what moved in your repo since the agent read it.
+3. It shows you your own request first, then the whole plan — scope, risk
+   answers, exclusions, desired rules, the Delta or Planned Flow in full — **and
+   the exact GitHub issue it will file**, assembled from that plan rather than
+   written by the agent. Then it asks once:
+
+       Start this change?     (default: No)
+
+**Nothing is created until you say yes.** No issue, no branch, no lane, no
+record. There is no \`--yes\`: the whole point of the question is that a person
+saw the plan and the issue text before either existed anywhere.
+
+4. When you say yes, Prismatica takes a **second** fresh reading and revalidates
+   against that one, immediately before the first outward-facing write. A
+   confirmation can take minutes, and a plan that was true when it was displayed
+   is not thereby true when it is acted on.
+
+Then, in this order: the issue is created, the lane is framed, your approved
+intent is written into that lane, the Delta or Planned Flow goes in beside it,
+and the builder brief is generated. If any step fails, whatever already
+succeeded is kept and you get one exact command to carry on from there — a real
+GitHub issue is never silently thrown away.
+
+## If something failed after the lane existed
+
+    prismatica start --import ~/plan.json --resume 20260729-fix-the-silent-export-failure-a1b2
+
+\`--resume\` finishes a change whose **lane already exists** — a live lane, on
+that change's own branch; an archived contract sitting on main will not do.
+
+It is the same path, not a shortcut past you: it takes the fresh reading,
+revalidates the plan, shows you the whole preview and asks the same default-No
+question before writing anything. What it changes is only what happens after
+the yes. First it checks that the file you are importing really is the plan
+that lane was framed from — title, scope, non-goals, acceptance checks, docs
+delta and builder, every field the contract was built from — and then it writes
+only the records that are genuinely missing. A record that is already there and
+matches is left exactly as it is, timestamp and all; one that is there and
+DIFFERS is a conflict and it refuses, because the version on disk may be the
+one you edited.
+
+Running it twice is a no-op. If framing never happened — only the issue was
+created — that is not a resume: run \`start\` again with \`--issue <url>\` so it
+links the issue you already have rather than opening a second one.
+
+## Naming the builder
+
+Whoever planned the change is not thereby its builder, so nothing infers one:
+the plan states it outright, agreed with you during planning, and it is shown
+in the preview before you confirm. You can change it later — see
+"prismatica guide roles".
+
+Then it is the ordinary loop:
+
+    prismatica open claude 20260729-fix-the-silent-export-failure-a1b2`,
+    },
+    {
+        id: 'starttechnical',
+        title: 'Scenario — a technical refactor, with no product Flow invented',
+        body: `Not every change is a feature. Splitting a 900-line module, replacing a
+deprecated API, speeding up a build — none of these change what a user can do,
+and inventing a product Flow to make them look like features would be a lie
+your map has to carry forever.
+
+In Prismatica Start, tell your agent: "src/report/builder.ts has grown to 900
+lines and three responsibilities — split it without changing behaviour". Settle
+it, and run what it hands you:
+
+    prismatica start --import ~/plan.json
+
+The plan classifies this as \`technical\`. That kind is checked, not merely
+labelled: a technical proposal that also carries a Planned Flow or a Delta is
+**rejected**. So you get an honest contract — scope, non-goals, acceptance
+checks, risk tier — and your Flow map is left exactly as it was.
+
+The plan will look roughly like:
+
+    What        technical work (no product Flow)
+    Why         three responsibilities in one file make every change risky
+    Instead     one module per responsibility, behaviour identical
+    Risk tier   normal
+    Scope       src/report/**
+    Done when   existing report tests still pass — proven by src/report/builder.test.ts
+                the public export surface is unchanged — proven by src/report/api.test.ts
+
+Confirm it and the loop is identical to any other change. The
+gate does not care that no Flow moved; it cares that the diff stayed in scope,
+every acceptance check traced to a passing test, and the review sealed an
+explicit approval of your exact diff.`,
+    },
+    {
+        id: 'rediscover',
+        title: 'Scenario — the app changed; bring the map back up to date',
+        body: `You mapped the app months ago. Since then five changes shipped. The map is not
+wrong so much as behind. There is no separate command for this: mapping an app
+for the first time and reconciling it afterwards are the same job, and the
+snapshot already says which Flows exist.
+
+    In your coding agent: Prismatica Understand, then run what it hands you:
+
+    prismatica discover --import ~/answer.json
+
+The context the skill reads gives the agent the exact picture: your current git HEAD,
+every Flow's stable id, its title, its goal, its truth hash, every Rule and the
+Rules approval hash, and everything already pending. It must echo the commit it
+read back, or the answer is refused — an answer about a tree that has since
+moved is rejected rather than merged.
+
+Four guarantees are worth stating plainly:
+
+- **Recognised ids become updates, never duplicates.** If the agent returns a
+  Flow whose id you already have, it is written as an update to that Flow — no
+  near-duplicate under a new name. Prismatica decides this from what is on
+  disk, not from what the agent labelled it.
+- **The whole batch is checked before any of it is written.** One unsafe
+  touchpoint fails the import with nothing written, rather than leaving you
+  half a map.
+- **Re-running is safe.** If a write failed partway, run the same command
+  again: a proposal already on disk that is identical to the one being imported
+  is left exactly as it is, keeping its original timestamp, and only the
+  missing ones are written. A proposal that DIFFERS is a conflict and the whole
+  import refuses — it may be a review you have in progress, and overwriting
+  that silently is the one outcome nobody recovers from.
+- **Absence is never deletion.** If the agent cannot find a Flow, it goes in a
+  "did not find" list for you to look at. That list is advisory: it causes no
+  write of any kind, and it cannot fail the run. The code may simply have
+  moved, or the agent may have missed it — either way, that is your call.
+
+Nothing is archived. A run log is not evidence — no gate, approval, signature or
+patch-id ever read one — and its only real effect was an untracked file sitting
+in front of your next \`git status\`. Rediscovery's output is the proposals.
+Archives written by earlier versions are left exactly where they are; nothing
+deletes them.
+
+## Proposing from inside a change
+
+If you notice, while BUILDING, that a Flow's truth no longer matches what the
+code will do, that proposal belongs on the change's own branch rather than on
+main:
+
+    prismatica propose --import ~/answer.json
+
+Same document, same checks, different destination — it writes into the lane, so
+the proposal rides the same pull request as the code that motivated it. Which
+command you run decides where the records land; the document never does.
+
+Then review what came back, and see the next scenario for approving it.`,
+    },
+    {
+        id: 'approvebatch',
+        title: 'Scenario — review and approve a batch safely',
+        body: `Rediscovery can return a dozen proposals at once. Approving them one command at
+a time invites you to stop reading around item four, so there is a batch form —
+and it is deliberately **not** a way to skip reading.
+
+    prismatica flow list
+      # read them first — this is the point
+
+    prismatica flow approve --all --by ehsan
+
+\`--all\` means **one reviewed confirmation, not blind approval**. Before it
+asks anything, it prints every pending item and marks each one NEW or UPDATE —
+decided from what is actually on disk, not from the proposal's own label — and
+it prevalidates the entire batch. If any single item is inconsistent, nothing is
+written and you are told which.
+
+Each item is printed **in full**: the complete truth of a new flow, and for an
+update the complete diff against the flow you already approved, field by field
+and step by step. A one-line summary would make your signature consent to
+something you never read. Only then does it ask once:
+
+    Approve all 7?
+
+There is no \`--yes\`, and \`--all\` refuses to run without a terminal. Owner
+approval is the thing this system exists to make real; a flag that skipped the
+human would hollow out the record it produces.
+
+Rules work the same way, with one difference that matters:
+
+    prismatica rules approve --all --by ehsan
+
+All rules live in one signed file with one approval hash, so a batch of ten
+produces **one** final signed file — not ten chained signatures over
+intermediate states you never actually approved.
+
+If a filesystem error interrupts a batch partway, you are told exactly which
+items completed and which remain, and re-running is safe. Canonical records are
+always written before the proposal is removed, so nothing is lost in between —
+and if the removal is what failed, the next run recognises that canonical truth
+already matches the leftover draft. It lists that item as **already applied**,
+clears the leftover, and signs nothing. Nothing is ever deleted just because it
+was absent from the batch.
+
+One thing a batch will refuse: if a pending proposal is rewritten between the
+preview you read and your confirmation, the whole batch stops and nothing is
+written. Your approval is consent to sign the exact records you were shown, so
+a record that changed after you read it is not one you approved.`,
+    },
+    {
+        id: 'handoff',
+        title: 'The hand-off — how Prismatica talks to your agent',
+        body: `Prismatica runs no agent for planning or mapping. It exports a document, the
+agent you are already using reads it, and you import what it wrote back. That
+is the whole seam, and it has exactly two commands:
+
+    prismatica context start        # → a plan
+    prismatica context discover     # → Flow/Rule proposals
+
+**You do not normally run either.** They are MACHINE-FACING: in the ordinary
+journey the Prismatica Start and Understand skills run them mid-conversation,
+read the file, and hand you back the one import command that is yours. What you
+see is:
+
+    1. Open your coding agent and use Prismatica Start (or Understand).
+    2. Describe what you need and settle it in conversation.
+    3. Run the one \`--import\` command it gives you, and confirm.
+
+They stay published for two real cases: an agent with no Prismatica plugin,
+which you hand the printed file to by hand; and wanting to see exactly what a
+skill was given. Both work — the seam is the same either way, and the import
+validates identically.
+
+Neither takes an argument, and neither takes a destination. What you want is
+settled in the conversation you are already having, and comes back inside the
+answer; the file always lands in a private temporary directory created by your
+operating system — never in your repository, and never at a path a caller
+chooses. A hand-off is scaffolding, not a record: it is read once and is
+meaningless the moment the tree moves. Putting it under \`.prismatica/\` would
+leave untracked scaffolding in front of every \`git status\` the proof path
+reads, and \`check\` refuses an uncommitted file it does not recognise — so a
+repo-local hand-off would block the very change it was written to plan.
+
+## What is in the file
+
+- \`format\` — the protocol this hand-off speaks, as one literal. There are
+  three: \`prismatica/start@1\`, \`prismatica/discover@1\` and
+  \`prismatica/propose@1\`. The answer carries it back, and each import command
+  accepts only its own. A document from a future version, a discovery answer
+  handed to \`start\`, or a lane proposal pasted into \`discover\` all fail the
+  same strict parse that refuses a misspelled field.
+- \`answerFormats\` — which of those literals an answer to THIS file may carry.
+  One for \`start\`; two for \`discover\`, because the same reading of the app is
+  imported by \`discover --import\` (→ main) or \`propose --import\` (→ the lane
+  you are building in), and the document has to say which it was written for.
+- \`snapshot\` — the read-only picture: the exact commit, every Flow with its
+  truth hash and touchpoints, every Rule, everything pending, every change in
+  flight, and which proof tools this repo actually has.
+- \`instructions\` — plain language: what to read, what to decide, what to
+  return. Identical for every agent. There is no per-provider dialect.
+- \`answerSchema\` — the JSON Schema for the answer, **derived from the same
+  strict definition that validates it on the way back in**. What Prismatica asks
+  for and what it accepts cannot drift apart, because they are one thing.
+- \`importCommands\` — the exact commands you run afterwards, so the agent can
+  hand them to you rather than reconstruct them. You run them in your own
+  terminal, not inside the agent's session.
+
+## What importing checks
+
+Everything, and against your repository rather than against the document. Which
+Flows exist, which ids are taken, the tier rules, the default tier — all of it
+is read from a reading taken fresh at import time.
+
+The answer echoes the whole snapshot it was written against, and that echo is a
+**staleness detector and nothing else**. Prismatica recomputes its id from its
+own contents, so an echo that was never exported is refused outright; what a
+genuine one then produces is a list of what moved since — shown to you, not
+used to decide anything. The document supplies no facts about your repo.
+
+Prose, a missing field, an extra field, an absolute path, a \`..\`, a secret
+glob, a Flow id that does not exist, an acceptance check with no test behind it,
+a wrong \`format\`, a fabricated snapshot, and (for Flow/Rule proposals) an
+answer about a different commit are all refused, with nothing written.
+
+## Why an agent may run these itself
+
+\`context start\` and \`context discover\` are on no owner-only list — which is
+exactly what lets a skill run them for you, mid-conversation, without asking.
+They write
+nothing into the repository, reach nowhere, and hand back only what
+\`flow list\` and \`git status\` already show. \`discover --import\` and
+\`propose --import\` are agent-allowed too: writing PROPOSALS is explicitly the
+agent's half of the rule that reserves canonical Flows and Rules to you.
+
+\`start\` is not, and never will be. It invents a contract's scope, files a real
+issue on GitHub, and asks a question only you can answer.
+
+## Choosing the model, and how hard it thinks
+
+\`open\` and \`review\` still take the same two options, because they still start
+a real session:
+
+    prismatica open claude <id> --effort high
+    prismatica review <id> --agent claude --effort max
+
+Prismatica hard-codes no model names. When either option is present, before
+\`open\` or \`review --agent\` writes the lane it runs the installed provider once
+in an empty OS temporary directory and asks it to print its **own usage** — and
+requires two things of it. The usage must document the exact flags this
+selection will travel through: a flag where the provider has one, and for
+Codex's reasoning effort, its strict configuration form. And it must **name the
+value you chose** among the values it lists for that dial.
+
+A value the provider's own usage lists nowhere is **refused**, before the
+routing change or the draft review. It is not quietly accepted, not swapped for
+a default, and not passed through and hoped for: a check that cannot be made is
+reported as one that was not made.
+
+Today that means a model name is refused for both providers — neither
+enumerates its models, so \`prismatica open claude <id> --model <model>\` stops
+there and tells you why — and \`--effort\` is refused for Codex, whose reasoning
+effort travels as a configuration key with no value list. Claude Code
+enumerates its effort levels in its usage, so that is the one selection this
+probe can confirm. Run a specific model in the session **you** start yourself,
+where the provider answers for the name directly.
+
+That probe asks the provider to describe itself and nothing more. **Prismatica
+never sends a prompt and never calls a model** — not to check a launch, not
+anywhere — and it holds no model catalogue. Those are the only two ways a model
+NAME could be checked here, and both are refused on purpose: a catalogue is
+stale the week it is written, and a prompt is a model call. Nor can any help
+output tell you whether you are signed in. An agent Prismatica has no adapter
+for is refused these options outright rather than receiving guessed flags.
+
+\`context\`, \`start\`, \`discover\` and \`propose\` take none of them, and there is
+no time budget to set either. They start no session — the model, the effort and
+how long it may take belong to the session **you** are running.`,
+    },
+    {
+        id: 'roles',
+        title: 'Scenario — who does what: Planner, Builder, Fresh Reviewer, Controller',
+        body: `Four different jobs, deliberately kept apart. All four can be AI agents; none
+of them decides anything.
+
+**Planner** — turns your plain-language need into a scoped, checkable proposal.
+It is a ROLE, not a process Prismatica starts: you hand the exported context to
+the agent you are already using. Whatever it writes is a document you confirm or
+throw away, and it cannot edit a file, create an issue, start a branch, approve
+truth, or lower a risk tier — not because it is sandboxed, but because nothing
+it returns is acted on until you import it and say yes.
+
+    In your coding agent: Prismatica Start, then run what it hands you:
+
+    prismatica start --import ~/plan.json
+
+**Builder** — implements the approved contract inside the lane, and only inside
+it. The scope hook blocks writes outside the contract's globs, and the diff
+check is the backstop that catches every agent equally.
+
+    prismatica open codex 20260729-fix-offline-session-loss-9c3e
+    prismatica check
+
+Which agent builds is YOURS to choose, and to change — and nothing infers it
+from whoever planned the change. Settle it during planning and it is stated in
+the plan's \`builder\` field, shown in the preview before you confirm; otherwise
+\`prismatica frame --builder <agent>\`, or just open that agent. \`next\`, \`pack\`
+and \`start\` all name it from then on. Swap it mid-change by opening the other
+agent; nothing needs unwinding, because this is routing, not a permission.
+
+**Fresh Reviewer** — reads the finished diff against the sealed brief, with no
+memory of having written it. A Fresh Reviewer is a NEW SESSION that did not
+build the current diff; **the same provider is fine**. What must not be reused
+is the session that wrote the code, because it already believes the diff is
+right. Both Claude and Codex map this role to a real reviewer skill, and
+neither is named in the BUILDER's brief — recommending the reviewer role to the
+agent about to write the code would be asking it to review itself. Who reviews
+is yours to choose and to swap; the gate never checks it.
+
+    prismatica review --agent claude
+      # drafts the review, records "claude" as the reviewer, and starts a
+      # fresh session in the lane that cannot change the repository
+      # (--permission-mode plan for Claude, --sandbox read-only for Codex)
+
+    prismatica review --agent codex
+    prismatica review --copy --reviewer "a chat agent"
+      # copies the same short lane pointer, for a reviewer with no CLI
+
+\`--agent\` accepts \`claude\` or \`codex\` and nothing else: the read-only flag is
+that CLI's own, and there is no safe generic guess for a provider Prismatica
+has never been told about. It refuses to be combined with \`--copy\`, or with
+\`--reviewer\` — the agent already IS the reviewer label, and recording one name
+while a different session did the work is exactly the confusion the record
+exists to prevent.
+
+The reviewer is handed ONE short pointer, not the brief: read the review record
+first, then the contract, the pack and the exact \`git diff <baseline>..HEAD\`;
+change nothing; distrust the builder's summary, an earlier review and a green
+test run alike; and end with exactly \`SAFE TO SEAL\` or \`DO NOT SEAL\`.
+
+Nothing is parsed from what the reviewer says. Prismatica never reads that
+session's output, never infers a verdict from it and never seals on its
+behalf — **you** record the outcome, and there are exactly two:
+
+    prismatica seal <id>                     # they said SAFE TO SEAL
+    prismatica seal <id> --request-changes   # they said DO NOT SEAL
+
+If the launch fails, the drafted review still stands and still binds this exact
+diff — start the session by hand, or fall back to \`review <id> --copy\`.
+
+Add \`--no-spawn\` to either \`open <agent>\` or \`review --agent <agent>\` to get
+that same manual command printed instead of run — see "next" for why it starts
+with \`cd <lane> &&\` and carries \`PRISMATICA_EXECUTOR=agent\`: unlike ordinary
+\`prismatica\` commands, the agent process it names inherits YOUR shell's
+current directory, not a resolved one.
+
+**Controller** — runs the loop between the other two, and stops where your
+authority begins. It builds nothing and judges nothing: it starts a Builder,
+runs \`check\`, starts a Fresh Reviewer, and hands you back a card. This job is
+called **Get Change Ready**. The controller remains an agent role, not a process
+Prismatica starts. The narrow \`prismatica ready\` command only appends or reads
+strict run bookkeeping; it launches no agent, calls no LLM, parses no chat,
+infers no verdict and creates no assurance evidence.
+
+    In your coding agent, on a change that already has a lane:
+    ask it to get the change ready — or, where the agent ships Prismatica's
+    packaged capability, invoke that (in Claude Code: /prismatica:ready)
+
+Which agent controls is yours to choose, exactly as Builder and Fresh Reviewer
+are. Prismatica packages the discipline for the agents it has a plugin system to
+package for — today that is Claude Code — and any other agent runs the same loop
+by being given the same rules. Nothing in the gate knows or asks which one it
+was, here or anywhere else.
+
+The run starts with one CLI-generated UUID and boundary in the append-only
+\`.prismatica/ready.jsonl\`: boundary HEAD, ledger length and prior
+Check count, plus the resolved builder and reviewer provider, model and effort.
+
+That is a SEPARATE file from \`.prismatica/ledger.jsonl\`, which keeps Check and
+gate rows and nothing else. A ready event appended into the ledger after a Check
+made the ledger unreadable at exactly the position Prismatica fails closed on —
+so a change would prove itself and then, by its own bookkeeping, become
+unprovable. Existing repositories are partitioned in place the first time a Get
+Change Ready command writes: every recorded event moves across in its original
+order, byte for byte, and nothing is discarded. Commit the move with your next
+records.
+Each later ready event names that run and records one exact Check or review
+attempt, its evidence, checked commit, verdict, findings, stop state and next
+owner action. A restarted controller begins with \`prismatica ready status\`,
+reuses the same plan and counters, and needs no transcript. Checks before the
+boundary remain pre-run history and spend none of the run's three-Check budget;
+restarting cannot reset that budget or the three-review budget.
+
+An attempt is spent by the WORK, not by the bookkeeping. A run event is written
+after its attempt — a record is never written before the thing it records — so a
+controller can die in between, and counting only its own events would hand the
+next one a fourth try. The counters are therefore rebuilt from what each attempt
+itself left behind: the \`check_run\` ledger row \`check\` wrote, and the review
+record \`review\` drafted, including the ones this run committed. An attempt
+nobody recorded still spends its place, and \`ready status\` says so plainly.
+
+**When a run stops, starting another one is yours.** A run that ends at
+\`check_budget_exhausted\`, \`review_budget_exhausted\`, \`blocked\` or
+\`awaiting_owner\` is finished: the controller may append nothing more to it, and
+re-importing its start simply reconstructs it. Deciding that three attempts were
+not enough is a decision, so it is one you make:
+
+    prismatica ready record <id> --import <start.json> --new-run
+
+That appends a second boundary bound to today's HEAD and ledger position, with a
+new run id and its own three Check and three review attempts. It is refused
+while the run is still running, refused when there is no run at all, and refused
+for an agent — the controller cannot hand itself a fourth attempt at the diff it
+just failed three times. Nothing is rewritten: every earlier run and every event
+it recorded stays exactly where it was, \`ready status\` reconstructs the LATEST
+run and lists the earlier ones as history, and the previous run's Checks become
+ordinary pre-run history that spends none of the new budget.
+
+The new run may also carry a corrected plan, which is the one repair for a run
+whose recorded provider, model or effort the launch will refuse — a restart must
+reuse what was recorded, so such a run can otherwise only be stopped. Inside a
+run nothing about the plan may change, and that is unchanged.
+
+A second boundary is only ever read as legitimate when it names the run it
+replaced and that run had genuinely stopped. A line appended any other way is
+still reported as an ambiguous run and still fails closed, so an extra boundary
+cannot quietly reset a budget.
+
+Every real attempt is still a NEW session handed only the contract, pack, Git
+state and relevant failure or findings. Multiline findings enter through a
+strict JSON import file and round-trip as content; they never enter argv, shell
+interpolation, a heredoc or a commit message. Older sealed reviews whose records
+never contained findings are reported honestly as \`findings not recorded\` and
+are never backfilled from memory.
+
+Installed provider help is authoritative. When model or effort is explicit,
+before real \`open\` or \`review\` changes the lane Prismatica runs that provider
+once in an empty OS temporary directory to print its own usage, and requires
+that usage to document the flags the selection needs and to name the selected
+value among the accepted values it enumerates. Provider
+defaults run no probe at all. A provider that will not run, that does not
+document those flags, or that does not name that value, therefore stops the
+command before a builder routing change or a draft review, never after it, and
+never silently uses a default.
+
+The probe is not a conversation: no prompt is sent and no model runs, here or
+anywhere else in Prismatica. Neither provider enumerates its model names in
+usage and Prismatica keeps no catalogue, so explicit model names are refused
+for both providers; Codex effort is refused too, while Claude Code effort is
+the one explicit selection the probe can confirm. Whether you are signed in
+remains the provider's answer when the real session starts.
+
+The controller never invents provider flags. Prismatica prints the exact, correctly
+quoted launch line for each role — \`prismatica open <provider> <id> --no-spawn\`
+for a builder, \`prismatica review <id> --agent <provider> --no-spawn\` for a reviewer
+— and refuses a dial that provider has no transport for rather than silently
+running its default. Both write something: \`open\` records the builder and
+advances the stage, so its contract change rides the builder's own checkpoint
+commit, and \`review\` writes the draft after any requested provider validation.
+
+After \`DO NOT SEAL\`, the controller first appends the validated ready event
+with the exact verdict and findings. It then records the blocking seal, inspects
+dirty paths, stages only the expected review, ledger, Check evidence and
+forward-stage contract outputs, checks the staged names and commits with an
+ordinary content-specific subject before rework. It never uses \`git add -A\`, a
+findings commit message or a fixed heredoc. A later commit containing only the
+review, ledger or this change's Check evidence is lifecycle output and cannot
+unlock another reviewer. Code or a substantive Flow or Rule proposal can.
+
+Exactly one owner-only command is available to it, because that command never
+advances a change:
+
+    PRISMATICA_EXECUTOR=agent prismatica seal <id> --request-changes
+
+\`ready record --new-run\` is the mirror of that exception: an ordinary
+\`ready record\` is the controller's own bookkeeping and stays its to run, while
+the one form that GRANTS something — a second run, with fresh budgets — is
+refused for an agent by the same guard, and names that form rather than the
+command when it refuses.
+
+Get Change Ready stops before review at \`light\`. Above \`light\`, the rejection
+blocks the gate and \`accept\`, while \`next\` returns it to a builder. The
+approving \`prismatica seal\` is the opposite — it is the record the gate accepts
+— so it stays yours, along with \`accept\`, \`ship\`, \`merge\`, \`amend\` and the
+rest. Every Prismatica command the controller runs carries that one-command
+executor marker, so an accidental owner-only command fails closed even when the
+plugin session was opened manually.
+
+Ready events are bookkeeping, not proof — nothing in the assurance path even
+opens \`ready.jsonl\`. Existing Check, gate, stats and
+passport readers ignore them and continue to use only real \`check_run\` or
+\`gate_run\` rows. The scope backstop, Check, merge gate, patch-id seal and your
+signature remain the assurance path with or without a controller.
+
+Why keep them apart: the Planner's reading of your app is **advisory** and is
+labelled that way everywhere it appears. Deterministic code can check that a
+plan is complete, in scope, correctly bound to a snapshot and correctly tiered.
+It cannot check whether the plan is a good idea, and it does not pretend to.
+That judgement is yours, which is why \`start\` shows you the whole plan and the
+exact issue text, asks once with No as the default, and writes nothing at all
+until you say yes.
+
+The builder and reviewer packs both carry the complete approved plan and the
+complete Delta, verbatim — not a summary of them — so no one downstream is
+working from a paraphrase.`,
+    },
+    {
+        id: 'manualframe',
+        title: 'Scenario — frame a change by hand, with full control',
+        body: `\`start\` is the short path. \`frame\` is the long one, for when you already know
+exactly what you want and would rather not have anything proposed to you.
+
+    prismatica frame "Reject empty session titles" \\
+      --issue https://github.com/acme/practice-app/issues/214 \\
+      --allow "src/sessions/**" \\
+      --allow "src/validation/title.ts" \\
+      --forbid "src/billing/**" \\
+      --non-goal "Do not change the offline sync queue" \\
+      --non-goal "Do not touch the session id format" \\
+      --check "an empty title is rejected with an inline message | src/sessions/title.test.ts" \\
+      --check "a whitespace-only title is rejected too | src/sessions/title.test.ts" \\
+      --check "existing sessions with empty titles still load | src/sessions/legacy.test.ts" \\
+      --docs docs/SESSIONS.md \\
+      --data
+
+Every flag, in plain terms:
+
+- \`--issue\` is required. No contract without an issue; no merge without a
+  contract.
+- \`--allow\` is the scope, repeatable. The diff must stay inside it.
+- \`--forbid\` is the explicit never-touch list, repeatable.
+- \`--non-goal\` records what this change deliberately does not do, repeatable.
+  It travels into the builder brief.
+- \`--check\` is \`description | test\`, repeatable. Each one is traced to a real
+  passing test at check and gate time, so \`manual:OWNER\` is the honest form
+  for anything a machine cannot verify.
+- \`--docs\` names a file that must change in this diff, repeatable.
+- \`--auth\`, \`--payments\`, \`--data\`, \`--copy-only\` set the risk tier. Here
+  \`--data\` forces **heavy**: full checks, a sealed review, a signed decision,
+  and a tested rollback route.
+
+The path rules in \`config.json\` are applied on top and can only raise the
+tier, never lower it — so \`--copy-only\` over \`src/auth/**\` still lands on
+heavy.
+
+Then:
+
+    prismatica pack 20260729-reject-empty-session-titles-4d81
+    prismatica open claude 20260729-reject-empty-session-titles-4d81`,
+    },
+    {
+        id: 'terms',
+        title: 'Terms — every word in one plain sentence',
+        body: `repo        your project's folder, tracked by git, with its full history.
+branch      a parallel line of work inside the repo.
+main        the branch that is the real product; everything else merges into it.
+worktree    a second folder checked out from the same repo — Prismatica calls
+            a change's worktree its "lane".
+commit      a saved snapshot of the work, with a message.
+PR          pull request — a proposal to merge one branch into main.
+gate        the check that runs on every PR; if it fails, GitHub blocks merging.
+merge       taking a branch's commits into main.
+deploy      putting the merged code in front of real users.
+diff        the exact lines added and removed by a change.
+hash        a fingerprint of content — change anything and it no longer matches.
+contract    the agreed record of one change: goal, allowed files, checks, tier.
+seal        the proof that the review looked at this exact diff (patch-id maths).
+passport    the record written after a change ships, verifies live, and has a
+            tested rollback route.
+
+Two different levels of "the gate is real", never confused in anything
+Prismatica prints:
+
+    Checked — owner-guarded   \`prismatica merge\` verified the PR itself
+                               (state, head, a passing gate check) before
+                               asking GitHub to merge — the guard is this
+                               command, run by you or your CI. A merge done
+                               in the GitHub browser UI, or a direct push to
+                               main, goes around it.
+    server-enforced            GitHub's own branch protection refuses the
+                               merge outright, even in its own UI, because
+                               "prismatica-gate" is a required status check.
+                               Not available on every plan (notably GitHub
+                               Free private repos) — never claimed unless
+                               \`prismatica doctor\` actually confirms it.
+
+And two answers that are not levels of assurance at all, because they are not
+findings about your repo:
+
+    unavailable                required status checks are not offered on this
+                               repository's plan. No settings fix is printed,
+                               because there is none, and it is left out of
+                               the adoption score rather than counted against
+                               you.
+    unknown                    the question could not be answered — gh missing
+                               or signed out, no GitHub remote, an ambiguous
+                               refusal, an outage, or a probe you skipped.
+                               Never reported as "unprotected", and also left
+                               out of the adoption score. If nothing at all
+                               could be measured, \`doctor\` says "insufficient
+                               information" rather than 0%.
+
+"Unprotected" is only ever printed when GitHub says so twice: the protection
+endpoint finds no rule AND the branch itself reports it is not protected. That
+second read matters, because the first endpoint needs admin permission on the
+repo and answers a plain "not found" to several very different questions. So if
+you are signed in without admin rights, or the branch named in your config does
+not exist on the remote, you will see "unknown" — never "unprotected". Same if
+GitHub reports the branch as protected but will not say which checks it
+requires: that is a repo Prismatica cannot fully read, not a repo with nothing
+guarding it.`,
+    },
+    {
+        id: 'adopt',
+        title: 'Adopt — putting an existing app under Prismatica',
+        body: `Prismatica governs changes from now on. Your old code needs no contracts,
+reviews, or passports — nothing is judged retroactively.
+
+Get the command first. Prismatica is published on npm, and you name the exact
+version every time:
+
+    npm install -g prismatica@0.2.0
+      # or run it without installing anything:
+      #   npx --yes prismatica@0.2.0 doctor
+
+Always name the version. Bare \`prismatica\` resolves to whatever the registry
+serves that minute, and the gate is the one choke point — which reader runs it
+is a decision you make in a diff someone can review, never one a registry makes
+for you between two pushes. Upgrading is the same command with a different
+number; nothing here goes looking for a "latest" on your behalf.
+
+\`npm link\` is NOT part of adopting an app. It is the self-host EXCEPTION for
+working on Prismatica's own source checkout — see "prismatica guide next".
+
+    cd your-app && prismatica init
+      # detects what you already have (tests? Playwright? CI? docs?) and
+      # enables only the checks that can actually run
+
+Read the table it prints: Enforced means the gate blocks on it, Checked means
+it runs, Missing means it cannot run yet — each Missing row shows the exact
+fix. You do not have to fix everything today. Two rows are not about your repo
+at all: Unavailable means the capability cannot exist here (a plan that does
+not offer it), and Unknown means the probe could not establish an answer.
+Neither prints a fix, and neither is counted in the adoption score — a
+question nobody could answer is not a mark against you.
+
+    In your coding agent: Prismatica Understand
+      # ask it to map this app. It READS the repo and DRAFTS flows —
+      # structured, reviewable routes through the app — then hands you
+      # "prismatica discover --import <proposal.json>". You review and approve
+      # each one; Prismatica never writes them itself.
+      # See "prismatica guide flows".
+
+    prismatica doctor
+      # repo health, an adoption score over what could actually be measured,
+      # and the single highest-value next fix
+
+Only want the map, not the gate yet? Use \`prismatica init --map-only\` instead
+— Flows and Rules with no gate, no hooks, no signing key (see
+"prismatica guide flows").
+
+Moving a map-only repo to full governance later works today as a manual
+procedure (a dedicated \`prismatica upgrade\` command is planned, but this
+gets you there now — do NOT just re-run \`prismatica init\` without
+\`--map-only\`; it leaves mode and the owner key half-migrated):
+
+1. Get an owner signing key. If you've run governed \`prismatica init\` on
+   any other repo on this machine, you already have one — it's one key per
+   machine, at \`~/.config/prismatica/owner.key\` (or \`$PRISMATICA_HOME\`).
+   If not, create one now by running \`prismatica init\` in any throwaway
+   git folder; you only ever do this once.
+2. Read out its public half (safe, read-only):
+       node -e "console.log(require('crypto').createPublicKey(require('fs').readFileSync(process.env.PRISMATICA_HOME ? process.env.PRISMATICA_HOME + '/owner.key' : require('os').homedir() + '/.config/prismatica/owner.key', 'utf8')).export({type:'spki',format:'pem'}).toString())"
+3. Edit \`.prismatica/config.json\` by hand: set \`"mode": "govern"\` and
+   \`"owner": { "publicKey": "<paste the PEM from step 2>" }\`.
+4. Add \`.github/workflows/prismatica-gate.yml\` — copy it from any other
+   governed Prismatica repo (the content only varies by main branch name).
+5. Re-sign every already-approved Flow and Rule. This is the one required
+   step, not optional: governed mode requires a verifying signature, so an
+   existing map-only approval (hash only, no signature) will show as
+   "tampered" and fail the gate's truth-integrity check until re-signed.
+   For each: copy the canonical file's \`truth:\` (or the rule text) into a
+   new proposal at \`.prismatica/flows/proposals/<id>.md\` (or
+   \`.prismatica/rules/proposals/<id>.md\`) with \`proposalType: update\` and
+   the truth UNCHANGED, then run \`prismatica flow approve <id>\` (or
+   \`rules approve <id>\`) — same hash, now signed.
+6. Run \`prismatica doctor\` — it tells you what's still missing (hooks,
+   branch protection) and confirms nothing reads as tampered anymore.
+
+Two one-time settings on GitHub make the gate real:
+1. push the repo to GitHub (prismatica ship does this per change), and
+2. Settings → Branches → protect "main" → require the "prismatica-gate" check.
+After that, nothing merges without passing the gate — not even by accident.
+
+Which Prismatica does YOUR CI run? \`init\` writes an exact pin:
+
+    - name: prismatica gate
+      run: npx --yes prismatica@0.2.0 gate
+
+Your app needs no Prismatica dependency of its own — that line fetches one
+published version straight from the registry. The \`npm ci\` step above it
+installs YOUR checks (your typechecker, linter, test runner, build), and it is
+skipped entirely when the repository has no npm lock file at its root, so a
+Python or Go repo adopts exactly as cleanly as a Node one.
+
+Adopted before 0.2.0? Your workflow says \`npx prismatica gate\` with no
+version, so CI runs whatever resolves that minute. \`prismatica doctor\` names
+it under "Runtime", beside the version you are running locally, so any skew
+between the two is visible instead of silent. The repair is one line in
+\`.github/workflows/prismatica-gate.yml\` — change:
+
+    run: npx prismatica gate
+
+to:
+
+    run: npx --yes prismatica@0.2.0 gate
+
+\`init\` will never do this for you: it preserves an existing workflow
+byte-for-byte by design, which is exactly why the pin is yours to move
+deliberately. Move it BEFORE, or in the same change as, the first time a newer
+Prismatica writes a record — a newer runtime reads every record an older one
+wrote, but the promise does not run backwards.`,
+    },
+    {
+        id: 'flows',
+        title: 'Flows — the map of what your app does',
+        body: `A Flow is one complete, real route through your app: where it starts, the
+steps someone takes, what the app shows and changes along the way, and where
+it ends. Not a feature list, not a code walkthrough — an outcome someone
+actually gets, start to finish.
+
+Every Flow splits into two parts, on purpose:
+
+- Truth — the goal, the steps, the ending, the rules. This is what the app
+  PROMISES. An agent may only propose a change to it; you approve it.
+- Mechanics — which files and routes it lives in. This also goes through
+  approval now (the same proposal you review for truth) — a lane can never
+  write the canonical flow file directly, only propose a change to it, so
+  there is exactly one writer of "what's approved": you, via approve.
+
+Fields, each in one plain word:
+
+    Goal          what the user gets done, in a few words
+    Starts when   the moment this flow begins
+    Needs first   conditions that must already be true (optional)
+    Steps         who does what, what the app shows, what data changes
+    Ends with     what is true when it finishes well
+    Variations    other routes through it (optional — a big one deserves its
+                  own flow instead)
+    Rules         things that must stay true, no matter what (optional)
+    Status        Works now / Planned / Idea / Uncertain
+
+See a flow, review what is waiting, and decide:
+
+    prismatica flow list                 # every flow, plus pending drafts
+    prismatica flow show <id>            # one flow as a readable story
+    prismatica flow approve <id>         # accept a draft or proposed update
+    prismatica flow dismiss <id>         # keep what you have; discard it
+    prismatica flow verify <id>          # you personally confirm it still works
+    prismatica flow status <id> works    # flip status directly — no ceremony
+
+\`flow show\` is short on purpose: title, outcome, where it starts and ends,
+the steps in order, and one honest line about the evidence. Ask for more only
+when you want it — the flags compose, and are covered in "proof":
+
+    --details   preconditions each step assumes
+    --proof     how every single step was verified
+    --code      the files, routes, and tests it lives in
+    --json      the same view as stable JSON, for scripts
+
+A step with nothing visible to show reads "Background step" rather than
+pretending there is a screen. Variations appear under "Other paths" as
+alternatives through the WHOLE flow: the record cannot say which step a
+variation branches from, so nothing claims that it can.
+
+Presentation is separate from truth. A Flow may optionally carry a short
+title, a journey name, and a position in that journey — used only for how it
+is displayed and grouped. It sits outside the truth block, so it is not part
+of the fingerprint and editing it never invalidates an approval or signature.
+Records without it are shown with a readable title derived from their id, and
+nothing is ever backfilled or re-signed on your behalf.
+
+Approving writes a fingerprint (a hash) of the truth block. If anyone edits an
+approved flow's truth without going through approve again, that fingerprint no
+longer matches — \`flow list\` shows it as tampered, immediately. Nothing about
+truth changes silently. Status and evidence are excluded from that fingerprint
+on purpose: flipping "planned" to "works now" or marking a step verified
+should never need a ceremony — the honesty comes from what evidence you can
+actually see next to each step, not from a lock on the whole record.`,
+    },
+    {
+        id: 'deltas',
+        title: 'Deltas — saying what should change about a Flow',
+        body: `A Delta is how you propose a change, in your own words, without writing a
+contract yourself: what happens today, what should happen instead, what must
+not change, and how you will know it worked.
+
+    prismatica delta new --flow <id> \\
+      --today "Minutes can be 0" \\
+      --instead "Minutes must be positive" \\
+      --keep "The offline queue behaviour" \\
+      --show-me "Try saving 0 minutes; it should refuse"
+      # writes a delta record — a plan, not governed truth: no hash, no
+      # signature, because it's your intent, not a fact about the app
+
+    prismatica delta approve <id>       # you decide it's worth doing
+    prismatica frame --from-delta <id>  # turns it into a contract:
+      # title from Instead, scope suggested from the Flow's mapped files
+      # (override with --allow), Keep becomes non-goals, Show me becomes
+      # the acceptance check an agent's work is judged against
+
+From there it's the ordinary loop (see "the loop" above) — a Delta is just a
+faster on-ramp into \`frame\`, never a second product decision or a shortcut
+around review.
+
+    prismatica delta list      # every delta and its status
+    prismatica delta show <id> # one delta, readable
+    prismatica delta reject <id>   # not now — discard it`,
+    },
+    {
+        id: 'discover',
+        title: 'Discover — mapping an app you already have',
+        body: `You do not write flows by hand. You ask an agent to read the real code and
+draft them, then you review.
+
+    In your coding agent: Prismatica Understand
+      # it reads your repo — through "prismatica context discover", which it
+      # runs for itself — and drafts 6-12 flows plus a few candidate app
+      # rules, saves a json answer, and hands you the command below.
+
+    prismatica discover --import ~/answer.json
+      # materialises that answer as files under .prismatica/flows/proposals/
+      # and .prismatica/rules/proposals/ — nothing is accepted automatically.
+
+An agent that would rather write those proposal files directly still can: the
+instructions carry both templates, and \`flow list\`, \`rules list\` and the board
+read them exactly the same way. The import route is the one you can prevalidate,
+preview and safely retry.
+
+Then review what it found:
+
+    prismatica flow list      # every draft, in one table
+    prismatica view           # the same review, visually, in Understand
+
+For each draft, either:
+
+    prismatica flow approve <id>     # this is right — make it the record
+    prismatica flow dismiss <id>     # not yet, or not quite — discard it
+
+The agent is told to be honest: it can only mark a step "code inferred"
+(it read the code, it did not run it), never "test verified" or "manually
+verified" — only a passing test or you, running \`prismatica flow verify\`, can
+say that. Run it again any time; the exported context names the Flows you
+already have, so the agent proposes what is still missing or has changed rather
+than re-drafting everything.
+
+## Seeing what a Flow is entangled with
+
+    prismatica flow show <flow-id> --json
+
+Alongside the Flow itself, that reports \`possiblyAffected\`: every other
+canonical Flow sharing a route, component, entity or test with this one. It is
+the same math \`check\` and the gate use to decide who must answer a Flow Report,
+and it states a possibility — sharing a component is a reason to look, never
+evidence that anything broke.`,
+    },
+    {
+        id: 'frame',
+        title: 'Frame — starting a change safely',
+        body: `Framing writes the contract and opens the lane. It refuses to start from a
+bad base, and tells you exactly how to fix it:
+
+- dirty base (uncommitted code): save it first —
+      git switch -c rescue/wip && git add -A && git commit -m "wip"
+- stale base (behind GitHub): catch up first —
+      git switch main && git pull
+- too many open changes: the WIP limit (default 2) keeps work small; finish
+  or ship something before starting more.
+
+The tier is set by what the change touches, and decides how much proof is due:
+- light  — copy, colours, spacing: checks and a screenshot.
+- normal — a feature or bug: full checks plus a sealed review.
+- heavy  — auth, payments, saved data, schema: all of that plus your signed
+  decision and a tested rollback route.
+
+If the scope turns out to be wrong mid-build, never start over — amend it with
+a reason that goes in the audit log:
+
+    prismatica amend <id> --reason "also needs the shared validator" \\
+      --allow "src/shared/**"
+      # widens the scope, refreshes the lane's guard, and marks the old brief
+      # stale so the agent re-packs before continuing
+
+**Some commands are yours, and only yours.** An agent Prismatica launched is
+refused every command that makes a decision rather than does work:
+
+    init  start  frame  amend  accept  seal  ship  merge  close  view
+    forget   flow approve/dismiss   rules approve/dismiss
+    delta approve/reject   flow verify   rules verify   flow status
+
+\`accept\` is the one that matters most — it signs with your Ed25519 key, so an
+agent that could run it would be approving its own diff. \`seal\` binds a review
+to an exact diff, and an agent that could both review and seal is not being
+reviewed by anyone. \`flow verify\`, \`rules verify\` and \`flow status\` are
+there for a quieter reason: they write "verified manually" or "works now" onto
+canonical truth, and manually means a person looked. Nothing may mark its own
+work proven. \`view\` is there because the board is your window only when you
+opened it — it can accept a change and approve a Flow through a browser form,
+so starting it is another way to reach every decision above. \`init\` adopts
+governance: it generates your signing key, writes the CI gate workflow and
+offers the pre-push hook — how this repo is governed is your call, and CI runs
+\`gate\`, never \`init\`. \`forget\` clears the board's list of your repos, which
+lives outside any repo and is not archived anywhere. The rest either invent
+scope or reach GitHub.
+
+Everything the agent actually needs stays open to it: \`check\`, \`review\`
+(a fresh agent reviewing is the design, not a hole), \`pack\`, \`open\`,
+\`discover\`, \`delta new\`, \`flow report\`, and every command that only reads —
+\`flow list\`, \`flow show\`, \`next\`, \`doctor\`, \`stats\`, \`guide\`. \`gate\`
+and \`prepush\` are untouched, because CI and git hooks run them with no
+terminal at all.
+
+**\`amend\` gets a second guard on top.** It moves the boundary every other check
+is measured against, so it refuses to run unless a person is there:
+
+- it shows you the scope you are about to widen — current paths, added paths,
+  the reason, and how many times this contract has already been amended — and
+  asks once. There is deliberately no \`--yes\`.
+- with no terminal attached, it refuses outright rather than assuming a yes.
+- any agent Prismatica launched carries a marker in its environment, and
+  \`amend\` refuses the moment it sees one. An agent that needs more scope must
+  come and ask you for it.
+
+Be clear-eyed about what those last two are: guards against a well-meaning
+agent overstepping, not a cage around a hostile one. An agent with a shell
+could edit the contract file directly and never call \`amend\` at all. What you
+genuinely keep is that the unattended path fails closed, every amendment is in
+the audit log with its reason, and amending invalidates the pack and any seal —
+so a review can never be carried across a scope change.
+
+Three or more amendments on one change is a smell, and Prismatica says so: the
+change was probably two changes.`,
+    },
+    {
+        id: 'check',
+        title: 'Check — proving the work',
+        body: `    prismatica check
+
+runs everything, identically to how the gate will run it later. It never asks
+the agent whether the work is done — it runs your tools and reads the results:
+
+- your repo's own proof: typecheck, lint, unit tests, build, browser journeys
+- secret scan: gitleaks when installed, a built-in fallback otherwise
+- scope: the real git diff must stay inside the contract's allowed files
+- traceability: every acceptance check must point at a passing test
+  (or be marked manual:OWNER, which you attest to at accept)
+- docs delta: the docs the contract promised must actually change
+
+Every run writes an evidence record and one ledger line. A failed run counts a
+"rework loop" — prismatica stats shows the median, which tells you how often
+agents need retries in this repo.
+
+Failing is normal and cheap here. The whole point is that a change fails at
+check, on your machine, in minutes — not at the gate, or worse, in front of
+users.`,
+    },
+    {
+        id: 'review',
+        title: 'Review and seal — fresh eyes, bound by maths',
+        body: `A review is only worth something if it looked at the code that ships. So
+Prismatica binds every review to the diff's fingerprint (its patch-id):
+
+    prismatica review --agent claude
+      # writes a review brief bound to the current committed diff, records
+      # "claude" as the reviewer, and starts a fresh read-only session in the
+      # lane with one short pointer at the record, the contract, the pack and
+      # the exact baseline..HEAD diff
+
+    prismatica review --copy --reviewer "a chat agent"
+      # copies the same short lane pointer — the path for a reviewer with no
+      # CLI, and the fallback if a launch fails
+
+    prismatica review --reviewer fresh-agent
+      # draft only: names a reviewer, launches nothing
+
+    prismatica seal
+      # recomputes the fingerprint; if the code changed since the review,
+      # the seal fails and the review must be redone
+
+    prismatica seal --request-changes
+      # the reviewer said no — never advances the change; above light it blocks
+      # the gate and accept, and next sends the work back to the builder
+
+If anything touches the code after sealing — even one line — the gate notices
+the fingerprints no longer match and blocks the merge. The model thinks; the
+maths checks.
+
+**A Fresh Reviewer is a fresh SESSION, not a different vendor.** The same
+provider is fine; what must not be reused is the session that wrote the code.
+\`--agent\` accepts \`claude\` or \`codex\` — the flag that stops the session
+changing the repository is that CLI's own (\`--permission-mode plan\`,
+\`--sandbox read-only\`) and no flag is ever guessed for a provider Prismatica
+has not been told about. Both block WRITES; neither claims to stop the session
+running commands, and the reviewer only needs the first. It refuses to combine with
+\`--copy\` or with \`--reviewer\`, because the agent already IS the reviewer label.
+
+**The reviewer recommends; you record.** The brief and the pointer both end the
+reviewer on exactly \`SAFE TO SEAL\` or \`DO NOT SEAL\`, and neither ever tells
+them to seal. Prismatica reads none of that session's output, infers no verdict
+from it and seals nothing on its behalf — the two outcomes are yours to type,
+and both are printed for you when the review is drafted.
+
+**The verdict is enforced, not just recorded.** Above \`light\` tier the gate
+requires a sealed review carrying an explicit \`approve\`. A
+\`request_changes\` verdict — or a sealed review with no verdict at all — fails
+closed: the gate refuses, \`accept\` will not sign over it, \`prismatica next\`
+sends the change back to the builder, and the board shows it as back with the
+builder rather than waiting on you. "Sealed" has never meant "approved", and
+now nothing in the tool pretends otherwise.
+
+**Commit before you check, and before you review.** A fingerprint can only
+cover committed work, so both \`check\` and \`review\` refuse while anything is
+uncommitted in the lane and tell you to commit first. Without that refusal a
+check of work-in-progress would be recorded as proof, and a review of it would
+be recorded as a review of the empty diff, with the seal agreeing perfectly.
+
+That includes Prismatica's own records, with narrow exceptions: the ledger line
+and the evidence files \`check\` writes, and a review record still in DRAFT that
+a re-run is about to replace. Those are output, not input. A SEALED review is
+not exempt — a \`request_changes\` verdict must reach Git history before a
+fresh review displaces it, or the rework it asked for would erase the only
+trace that anyone said no. The contract, the pack and a flow report are not
+exempt either: the brief quotes their scope, their acceptance checks and their
+impact account, so they have to be the ones riding the pull request, not a
+newer copy sitting in your working tree. (The one thing tolerated on the
+contract is Prismatica's own stage line moving forward; every other field must
+match what is committed.)
+
+**A rejection has to be worked on before it can be reviewed again.** Once a
+sealed \`request_changes\` is committed, \`review\` refuses a fresh brief until a
+later commit contains substantive rework. The review record, ledger and this
+contract's Check evidence are lifecycle output and do not count, so rerunning
+Check on unchanged work cannot unlock a fresh reviewer. Rework the code, or make
+a substantive Flow or Rule proposal change — either passes. No later commit or
+an empty commit does not: each would put the same work in front of a new
+reviewer, and a change could shop for a yes at no cost. It is deliberately not a fingerprint
+comparison — the patch-id leaves \`.prismatica/\` out, so records-only rework is
+invisible to it — but a question asked of committed history since the rejection
+was written. Commit the rejection and the rework it asked for separately, in that
+order, for the same reason a sealed review is never replaced in place.
+
+    prismatica review 20260729-fix-offline-session-loss-9c3e --reconsider
+      # you have decided to look at this exact, unchanged work again anyway
+
+That escape hatch is yours alone: it needs a real terminal, it refuses an agent,
+and there is deliberately no \`--yes\`. The rejection it steps past stays exactly
+where it is in Git history — nothing here deletes or rewrites a record.
+
+**A check expires when the code moves on.** Every check records the exact
+commit it inspected, and stays current only while the commits since are the
+change's own records — committing the ledger line and evidence \`check\` just
+produced is expected and changes nothing. Commit code, contract terms, the
+pack, a flow report, a delta, a proposal or a canonical record afterwards and
+the check no longer describes this commit, so \`review\` refuses and \`next\`
+sends you back to \`check\`. File your flow report BEFORE the check, not after.
+A check recorded before this binding existed, or a ledger line written after it
+that cannot be read, both fail closed the same way: run \`check\` again.
+
+**Filing that flow report is one command, and it will not lie for you.**
+
+    prismatica flow report --auto
+      # writes one entry per Flow your diff provably touched, naming the
+      # touchpoints that matched and the files that matched them
+
+\`--auto\` records only what a file diff can establish. It never says a test
+passed — it runs before \`check\`, so nothing has run yet — and it never says
+behaviour is unchanged, because no list of filenames can establish that. It
+leaves two things for you, and prints the exact command for each, last, where
+you cannot miss them: a Flow that merely SHARES a mechanic with one you
+touched, and a Flow with no mapped touchpoints at all, which no diff can rule
+in or out. It never overwrites an entry you wrote.
+
+Then answer the rest in your own words:
+
+    prismatica flow report --flow log-a-session \\
+      --status unchanged --reason "only the internal helper moved; the user
+      sees exactly the same screens in the same order"
+
+\`unchanged\` on a Flow your diff touched is a real, accepted answer — that is
+what it is FOR. Prismatica cannot decide whether behaviour changed and does not
+pretend to; it only decides who has to answer. If that Flow's own mapped test
+files also changed in your diff, the report records that fact beside your
+reason so the reviewer weighs both. It is context, never a veto.
+
+For heavy changes, your signed decision follows the seal:
+
+    prismatica accept
+      # Ed25519 signature over the contract id + the exact diff fingerprint,
+      # verified by the gate against the public key committed in config.json
+
+**Feeling like too much ceremony for a small change? Use the tier, not a
+shortcut.** There is deliberately no \`--skip-review\`: a seal you can switch off
+proves nothing, and the switch would be the first thing a tired evening reaches
+for. The dial that exists instead is the risk tier, and it is deterministic —
+\`light\` changes need no sealed review at all (\`gate.ts\` simply does not ask
+for one), while \`normal\` and \`heavy\` do.
+
+    prismatica frame "Fix the footer spacing" --issue "#31" --copy-only
+      # copy/colours/spacing → light → checks, no sealed review
+
+That holds all the way through \`ship --verify\`: a light change's passport
+binds to the exact commit its passing check recorded, not to a review it never
+had. The exact-commit guarantee is the same one a sealed review gives; only the
+proof it is drawn from differs by tier.
+
+If a whole CLASS of change keeps feeling heavier than it deserves — docs,
+tests, fixtures — say so once, in \`.prismatica/config.json\`:
+
+    "tierRules": [
+      { "tier": "light",  "paths": ["docs/**", "**/*.test.ts"] },
+      { "tier": "heavy",  "paths": ["**/auth/**", "**/payments/**"] }
+    ]
+
+That is a decision recorded in the repo, reviewable in a diff, applied the same
+way every time — not a flag someone typed once at 11pm. And it cannot be
+abused: the tier is \`max(what you answered, what the files demand)\`, so an
+agent can raise a tier and never lower one, and the gate re-derives the floor
+from the changed files regardless of what the contract claims.`,
+    },
+    {
+        id: 'ship',
+        title: 'Ship, merge, close, verify — out the door, with a way back',
+        body: `    prismatica ship <id>
+      # pre-flights the gate locally (why push something that will bounce?),
+      # requires an exact clean lane HEAD, pushes it, and opens the pull
+      # request via GitHub's gh — never queries or creates a PR after a
+      # failed push, and reuses an already-open PR instead of duplicating it
+
+The real gate runs on GitHub for every push to the PR. It re-checks everything
+from scratch in a clean checkout: scope, tests, docs, the sealed review, your
+signature (heavy), and the risk tier the changed files themselves demand. The
+gate itself makes zero writes, pass or fail — it only ever reports.
+
+    prismatica merge <id>
+      # once the gate is green: an exact-SHA, owner-guarded merge. Refuses a
+      # draft, missing, closed, pending, failed, stale, or ambiguous PR, and
+      # requires a passing prismatica-gate check for this EXACT head before
+      # calling \`gh pr merge --merge\` — never a silent squash or rebase.
+      # Reported as "Checked — owner-guarded": this command is the guard,
+      # not a claim that GitHub itself enforces it (GitHub Free private
+      # repos don't offer required-status-check protection at all). Without
+      # server-side protection, a merge in the GitHub browser UI or a direct
+      # push to main still bypasses it — see "prismatica guide mergepath"
+
+    prismatica close <id>
+      # removes the lane once GitHub's own record confirms a merged PR at
+      # exactly this lane's HEAD — refuses any real uncommitted work (the
+      # ONE thing it tolerates is ship's own disposable stage-bump, since
+      # ship can never commit for you), refuses any ignored file it can't
+      # prove is disposable (a local .env, log, evidence blob, customized
+      # Claude setting, or hand-edited hook survives; exact generated hook
+      # files and build output don't block it), never a remote branch,
+      # never anything short of certain
+
+After merge, close, and your deploy is out:
+
+    prismatica ship <id> --verify \\
+      --deploy-result "deployed to production" \\
+      --rollback "revert the PR, redeploy previous image"
+      # runs one live smoke journey against the real app; only when it
+      # passes is the passport written — durably, on your main checkout,
+      # never forcing a new commit into an already-closed lane
+
+No passport is ever written for a broken deploy or an empty change. \`--deploy-
+result\` and \`--rollback\` are checked for real content, not just presence:
+punctuation on its own ("...") and angle-bracket template text copied straight
+out of a \`--help\` string ("<a rollback route you actually tested>") are both
+refused before the smoke journey ever runs. A short, real answer ("deployed",
+"revert PR #48") is never mistaken for a placeholder. The rollback route on
+the passport is one you actually tested — because the only rollback that
+counts is one that is known to work.
+
+Lost mid-flow? \`prismatica next\` reads the PR and its checks (read-only,
+never network-writing) and tells you exactly which of ship/merge/close/verify
+comes next — or, if GitHub can't be reached, says so honestly instead of
+guessing. When a merged contract on main is still missing its passport, the
+command it hands you is exactly \`prismatica ship <id> --verify\`, with no
+invented \`--deploy-result\`/\`--rollback\` text tacked on — those are real
+evidence only you have, and \`ship\` asks for it directly rather than accepting
+whatever \`next\` printed. A contract created before this repo started
+tracking release verification (\`releaseTrackingSince\` in config.json, set
+once by \`init\`) is never queued this way at all — see "prismatica guide
+releasetracking".`,
+    },
+    {
+        id: 'releasetracking',
+        title: 'Release tracking — why an old contract is never "awaiting verification"',
+        body: `\`ship --verify\` writes a passport once a merged change actually deploys and
+passes a live check. Until it does, \`next\` and the board both say the
+contract is "awaiting live verification" — but only for a contract this repo
+was actually tracking release proof for when it merged.
+
+\`prismatica init\` writes \`releaseTrackingSince\` into config.json — once, the
+first time it runs, timestamped to that moment:
+
+    "releaseTrackingSince": "2026-08-06T16:41:25.791Z"
+
+A contract created BEFORE that timestamp, with no passport, is legacy: nobody
+was asking it to carry release proof at the time, so \`next\` never queues it
+for \`ship --verify\`, and neither \`next\` nor the board ever describes it as
+shipped or verified. It is shown plainly as legacy release proof that was
+never tracked, distinct from a genuinely pending one.
+
+The boundary decides what a MISSING passport means, never what a present one
+means. An old contract that DOES have a passport is a verified release like
+any other — it merged, deployed and passed a live check, and that record is
+shown as exactly what it is. Nothing is suppressed for being old.
+
+A contract created ON OR AFTER the boundary, with no passport yet, is exactly
+what "awaiting live verification" means — \`next\` surfaces it, and \`ship
+--verify\` will happily write its passport once you give it real evidence.
+
+Re-running \`init\` on a repo that adopted Prismatica before this field existed
+fills the boundary in once, from the moment you re-run it — never earlier,
+and never moved again on any later run. Nothing is ever backfilled, waived,
+deleted or overwritten: this only decides who gets ASKED for verification, and
+a real passport, once written, is never touched by any of this.`,
+    },
+    {
+        id: 'board',
+        title: 'Board — seeing everything at once',
+        body: `    prismatica view
+      # a local page (your machine only) showing every adopted repo
+
+Four areas, in the order they deserve your attention:
+
+- Needs you — every decision waiting on you, across all apps, each in one
+  plain sentence. Each card has "Approve and sign" or "Request changes"; both
+  write a signed record into the repo — the gate reads the record, never the
+  board.
+- Work — every in-flight change as a card in its lifecycle column. Cards move
+  only when records change; there is nothing to drag.
+- Apps — one row per repo: last shipped, open changes, gate health, red
+  flags, and the folded Enforced/Checked/Missing table. Each row has a "Remove"
+  button that forgets the repo's board pointer (the repo and its records stay).
+- Releases — three honestly distinct states, never blurred together. Verified
+  releases are passports (what shipped, with proof and a tested rollback).
+  Awaiting live verification is a merged contract with no passport yet, still
+  eligible for \`ship --verify\`. Legacy (release proof not tracked) is a
+  contract created before this repo adopted release tracking — never queued,
+  never called shipped or verified (see "prismatica guide releasetracking").
+  Below that, the plans you confirmed: an Intent is the plan \`prismatica start\`
+  recorded when you confirmed it, its success checks listed as the outcomes it
+  set out to achieve, never as a progress bar. Nothing in Prismatica advances
+  them, so a count would only ever read zero. Whether a change shipped comes
+  from its passport — the one record that means it merged, deployed and passed
+  a live check.
+
+The board follows your system light/dark theme, with a manual toggle (Auto /
+Light / Dark) and an optional 10-second auto-refresh, both in the sidebar.
+
+A fifth sidebar entry, Understand, is a separate view onto what your apps DO
+rather than what is changing — see the "understand" topic.
+
+To empty the board from the terminal instead:
+
+    prismatica forget           # forget the current repo
+    prismatica forget --gone    # forget repos no longer on disk
+    prismatica forget --all     # clear the board entirely
+
+Everything on the board is a record in a repo. If it is not in the repo, it is
+not on the board. Hover anything to see the real term behind the plain words.`,
+    },
+    {
+        id: 'understand',
+        title: 'Understand — the same Flows and Rules, visually',
+        body: `    prismatica view
+      # then click "Understand" in the sidebar, or go straight to
+      # http://127.0.0.1:<port>/understand
+
+Understand is where you review what \`prismatica discover --import\` (or
+\`prismatica propose --import\`, from inside a change) put there, without
+touching a terminal:
+
+- Pick an app — each card shows how many Flows and Rules it has, and how many
+  are waiting on you.
+- Flow Map — one card per Flow: its goal, status (Works now / Planned / Idea
+  / Uncertain), and how its evidence breaks down (for example "3 steps: 2
+  test verified, 1 code inferred"). New drafts and proposed updates carry a
+  "pending review" badge right on the card. Filter by status.
+- Storyboard — click a Flow to see it step by step: who does what, what the
+  app shows, what changes, and only-if assumptions — plus, collapsed behind
+  "Where it lives in the code", the files an agent already mapped it to.
+- App rules sit alongside the map — the short list of things that must stay
+  true no matter which Flow you are in.
+
+Reviewing a draft or a proposed update shows a side-by-side Current /
+Proposed comparison, then two buttons:
+
+    Approve            # writes it as the app's current truth (or rule)
+    Keep current / dismiss   # discards the proposal; nothing changes
+
+Both buttons call the exact same code as \`prismatica flow approve\` and
+\`prismatica flow dismiss\` — the board is never a second source of truth, only
+a second way to reach the one approval path (signed automatically if the app
+is governed, hash-only if it is map-only).`,
+    },
+];
+export function guideTopicIds() {
+    return GUIDE_TOPICS.map((topic) => topic.id);
+}
+export function renderGuideTopic(id) {
+    const topic = GUIDE_TOPICS.find((entry) => entry.id === id);
+    if (!topic) {
+        return null;
+    }
+    return `## ${topic.title}\n\n${topic.body}\n`;
+}
+/** Topics that answer "I want to do X", listed before the reference material. */
+export const SCENARIO_TOPIC_IDS = [
+    'startbug',
+    'understandapp',
+    'changeflow',
+    'newflow',
+    'starttechnical',
+    'rediscover',
+    'approvebatch',
+    'handoff',
+    'roles',
+    'proof',
+    'mergepath',
+    'verifyclose',
+    'abandon',
+    'manualframe',
+];
+function tocLine(topic) {
+    return `- ${topic.title.toLowerCase().split(' — ')[0]}: prismatica guide ${topic.id}`;
+}
+export function renderFullGuide() {
+    const scenarios = GUIDE_TOPICS.filter((topic) => SCENARIO_TOPIC_IDS.includes(topic.id));
+    const reference = GUIDE_TOPICS.filter((topic) => !SCENARIO_TOPIC_IDS.includes(topic.id));
+    return `# The Prismatica guide
+
+The agent builds. Prismatica inspects. Nothing ships until the intent, the
+proof, and the owner agree.
+
+Start from what you are trying to do:
+
+${scenarios.map(tocLine).join('\n')}
+
+Then the reference, when you want the detail behind a step:
+
+${reference.map(tocLine).join('\n')}
+
+${GUIDE_TOPICS.map((topic) => `## ${topic.title}\n\n${topic.body}`).join('\n\n')}
+`;
+}
+//# sourceMappingURL=guide.js.map