@marver-design/marver 0.20.0 → 0.22.0

package/templates/context/shipped.md

@@ -0,0 +1,28 @@
+---
+kind: record
+audience: team
+---
+
+# Shipped - what runs where, and what is available to whom
+
+The only file that says what is available. Every evidence cell carries its level, and `confirmed`
+and `reported` carry a citation:
+
+- `confirmed` - observed in a system of record: the deploy run whose deploy step succeeded for that
+  service, a ci run that executed the suite. An environment marked "deployed" is not proof on its
+  own - some pipelines mark it when the run stood down.
+- `reported` - a written claim, cited: a changelog line, an ops note.
+- `unknown` - neither, with the reason. An honest unknown is the right answer.
+
+Commit ancestry says a change is inside a revision, not that the revision is running.
+
+## Services × environments
+
+| Service | Environment | Revision | Deployed at | How | Evidence |
+|---|---|---|---|---|---|
+| app | production | - | - | - | `unknown` - nothing recorded yet |
+
+## Capabilities
+
+| Capability | Implemented | Verified | Available | Contract |
+|---|---|---|---|---|

package/templates/instructions/boards.md

@@ -62,23 +62,33 @@ viewport and lays it out:
 
 ## Folders - organising the sidebar
 
-Boards can sit in folders, one level deep (folders hold boards, never folders).
-Files are the truth, and two files carry it:
+Boards can sit in folders, two levels deep: a folder holds boards and folders, a folder
+inside a folder (a **sub-folder**) holds boards only. A board can sit at the root, in a
+folder, or in a sub-folder. Files are the truth, and two files carry it:
 
 - **Membership lives on the board**: `"folder": "research"` in the board file, next
-  to `order`. `order` then ranks the board among its folder siblings (root boards and
-  folders share the root sequence). Same grammar as board names
+  to `order` - always the ONE folder it sits in directly, at either level (a board in a
+  sub-folder names the sub-folder, never a path). `order` then ranks it among its
+  siblings: at every level, the boards and folders there share one sequence (the root's
+  boards and top-level folders; a folder's boards and sub-folders; a sub-folder's boards). Same grammar as board names
   (`^[a-z0-9][a-z0-9-]*$`); an invalid value means top level. `all-scenes` never
   lives in a folder.
 - **Folders live in `design/boards/_folders.json`** - the underscore marks it as
   infrastructure, never a board:
 
   ```json
-  { "version": 1, "folders": [
+  { "version": 2, "folders": [
     { "name": "research", "order": 1, "title": "R&D", "description": "The thinking behind the live boards - specs, flows, references" },
+    { "name": "flows", "parent": "research", "order": 2, "description": "One board per user flow" },
     { "name": "archive", "order": 3, "description": "Retired directions and scene versions, oldest first" } ] }
   ```
 
+  **Nesting lives here only**: a sub-folder's entry carries `"parent": "<folder>"`, and the
+  file says `"version": 2` while any entry has a parent (`"version": 1` when none does - an
+  older Marver can read that, and refuses a version-2 file rather than lose its nesting).
+  A parent must itself be a registered top-level folder; a sub-folder never holds a
+  folder. Folder names are unique across both levels.
+
   A folder's `name` is its slug - the identity its boards point at with `folder`; its
   `title` (optional, free text) is what humans see, exactly as on a board; its
   `description` says what belongs in it - the next session files boards right without
@@ -87,7 +97,8 @@ Files are the truth, and two files carry it:
   It exists so an EMPTY folder can exist and so a folder has a rank at the root.
   A folder a board names but the registry lacks is still real (it sorts after the
   ranked items, by name) - two boards with `"folder": "research"` make a Research
-  folder on their own. A malformed registry is an error the canvas shows, not an
+  folder on their own. Such an implied folder is always top-level: to nest it, register
+  it with its `parent`. A malformed registry is an error the canvas shows, not an
   empty one - fix it, never delete it.
 
 **Look before you organise: `npx marver boards`** prints the sidebar as the files say
@@ -99,39 +110,78 @@ have rearranged things since you last looked, and their arrangement stands.
 The moves, each a file edit, so the files always agree:
 - **Create** a folder: add `{ "name": "<slug>", "order": <n>, "description": "…" }`
   to the registry's `folders` (create the file if absent) - or just point a board at it.
-- **Move a board in**: write `"folder": "<slug>"` on the board and give it an `order`
-  among that folder's boards. **Move it out**: delete the `folder` field and give it
-  an `order` among the top-level items.
+  **Create a sub-folder**: the same entry with `"parent": "<top-level folder>"`, its
+  `order` among that folder's boards and sub-folders, and `"version": 2` on the file.
+- **Move a folder in or out**: set its `parent` (only a folder with no sub-folders of its
+  own can move into another - never three levels) or delete it; re-rank the siblings you
+  touch, and set `"version"` to 2 while any parent remains, 1 when none does.
+- **Move a board in**: write `"folder": "<slug>"` on the board - any folder, at either
+  level - and give it an `order` among that folder's boards and sub-folders. **Move it
+  out**: delete the `folder` field and give it an `order` among the top-level items.
 - **Rank** folders and boards: `order` on the board (among its siblings) and on the
   registry entry (among the top-level items). Renumber the siblings you touch.
 - **Retitle** a folder (or a board): set `title` on the registry entry (on the board
   file). **Rename a slug** - a folder's `name`, a board's file name - only when asked,
-  and as one refactor: a folder slug is on every member's `folder` field (rewrite them
-  all, AND the registry entry - a registry rename alone leaves the members in the old,
-  implied folder); a board file name is in `publish.json`, in its comment threads and in
+  and as one refactor: a folder slug is on every member's `folder` field and on
+  every sub-folder's `parent` (rewrite them all, AND the registry entry - a registry rename
+  alone leaves the members in the old, implied folder and the sub-folders pointing at a
+  parent that no longer exists); a board file name is in `publish.json`, in its comment threads and in
   every path anyone copied. A title does what a rename usually wanted.
-- **Delete** a folder: remove `folder` from every member, then its registry entry.
-  Folders organise, never own: deleting one never deletes a board.
-- The **landing board** is the first board in sidebar order, folders included -
-  rank a folder first and its first board opens the canvas.
+- **Delete** a folder: what it holds moves up one level, into its place - a top-level
+  folder's boards lose `folder` and its sub-folders lose `parent` (they become top-level
+  folders, keeping their boards); a sub-folder's boards take its parent as their `folder`.
+  Then remove its registry entry and re-rank the level it emptied into. Folders organise,
+  never own: deleting one never deletes a board.
+- The **landing board** is the first board in sidebar order, reading down through
+  folders and sub-folders - rank a folder first and its first board opens the canvas.
 
 Use folders proactively, the way a tidy studio would: a canvas past six or eight
 boards wants grouping - the live feature boards at the top level, `research` /
 `specs` for the thinking, `decks` for slides, `archive` for history and versions
-last. Propose the grouping in one sentence and do it; keep folder names short and
+last. Reach for a sub-folder when a folder itself grows past six or eight boards and
+splits naturally (features by surface, archive by year) - not before; one level reads
+faster than two. Propose the grouping in one sentence and do it; keep folder names short and
 plain.
 
 The human does all of this too - from the sidebar: New folder (right-click the Boards
-header, or its `+`), Rename (the title - slugs never move from the sidebar), Delete
-folder, "Move to …" on a board, and DRAG: boards into and out of folders, folders among
-boards. Each drag rewrites `order` (and
+header, or its `+`), New folder inside (a top-level folder's menu), Rename (the title -
+slugs never move from the sidebar), Delete folder, Move to top level (a board in a folder,
+a sub-folder), Move to new folder (a board), and DRAG: boards into and out of folders at
+either level, folders among boards and - when they hold no sub-folders - into a top-level
+folder. Each drag rewrites `order` (and
 `folder`) on the boards it touches and the registry - the shell owns those fields
 while the canvas is open, exactly as it owns `order`; write membership and new
 folders freely, and never rewrite an arrangement the human just made. The shell
 refuses a write that would overwrite an edit it has not seen (your file write and
 the human's drag can never silently erase each other), so read a board file before
-you rewrite it. Published canvases show the folders of the published boards only; a
-folder with nothing published never reaches the bundle.
+you rewrite it. Published canvases show the folders of the published boards only - a
+sub-folder's parent included; a folder with nothing published at any depth never reaches
+the bundle.
+
+## Types and status - what a board is for, and where it stands
+
+Every canvas shares one sidebar vocabulary. A board's `"type"` - `start`, `feature`, `surface`,
+`project`, `feedback`, `context`, `deck`, `archive` - draws its icon; set it on the board, or on a
+folder's entry in `_folders.json` and every board inside wears it (its own type wins; a sub-folder's
+boards fall back to the parent folder's type). Moving a board changes an inherited type only.
+
+- **Make a board in its starting layout:** `npx marver boards new <name> --folder features` (the
+  folder's type), or `--type <type>`. A feature gets three phase scenes as three bands -
+  `<name>-specs`, `<name>-lofi`, `<name>` - each with a brief; a start board renders
+  `context/INDEX.md` and `context/shipped.md`; a deck starts on a title slide. It never overwrites.
+  The phase scenes start empty: pin each frame you make in one as a node, or the board never shows it.
+- **Add a typed folder:** `npx marver folders add decks` (or `start`, `features`, `surfaces`,
+  `projects`, `feedback`, `context`, `archive`) - appended, never moving one that exists.
+- **Feature and project boards wear a status** read from `context/` (instructions/context.md): the
+  capability is the board's name, or `"capability": "<slug>"`. You may decide only three things on
+  the board: `"status": "archived"`, `"paused"`, or `"blocked"` with `"reason": "<one sentence>"`.
+  **Never write `"status": "done"`** - Done comes from `context/shipped.md`, and the check fails it.
+  Without `context/` a board may also say `"todo"`, `"backlog"` or `"in-progress"` by hand.
+  A person sets the same from the sidebar (right-click, Change status…) - it rewrites only `status`
+  and `reason`, so re-read a board before you edit it.
+- In progress fills by phase: the phase scenes above, or `phase: spec | lofi | hifi` in a scene's
+  `_brief.md` front matter - never by where a row sits.
+- `npx marver boards` prints every board's type and status with what decided it.
 
 ## The default composition: one horizontal band
 
@@ -224,6 +274,12 @@ be ON a published board - unlisted frames are excluded from the bundle at build
 time. Deploying the built canvas - gate password, the collaboration volume,
 accounts and invites - is its own phase: **instructions/publish.md**.
 
+When you add a board to `publish.json`, write the `type` its board type suggests - `slides` for a
+deck, `refs` for a context board, `doc` for a project (`marver build` notes any row that names none).
+A board's status, reason and capability never ship - unless the row says `"showStatus": true`, and
+then only a status drawn from publishable evidence (`audience: publishable` under `context/`; a scene
+brief counts unless it says otherwise), never Blocked, never a reason.
+
 The published gate page shows the app's identity: `design/logo.svg` + the host
 package name (overridable via config `share`). If the app has no logo asset yet,
 create a simple `design/logo.svg`. Leave `share.branding` ON unless the human

package/templates/instructions/context.md

@@ -0,0 +1,114 @@
+# Context - what the product is, kept true
+
+The project's knowledge lives in `context/`, beside `design/`. Code says what is implemented;
+`context/` says what is available, how it works, why, and what is next - with evidence. The canvas
+reads the same files: every feature and project board wears the status they record.
+
+## At the start of a session
+
+Read `context/INDEX.md`, then at most two more files per question. The index routes; it never
+explains. If there is no `context/`, see "Setting up" below before you invent answers.
+
+## The files
+
+| Path | What it holds |
+|---|---|
+| `INDEX.md` | routing only, under 800 words; its capability table is generated from `map.json` |
+| `shipped.md` | **the only place availability is written** - services by environment, capabilities by who has them; for knowledge work, what was delivered to whom |
+| `product/<capability>.md` | one current contract per capability |
+| `map.json` | which code each capability lives in - the pull-request rule reads it |
+| `playbooks/<name>/PLAYBOOK.md` | how we do things - steps with checks, traps, a run log |
+| `feedback/` | the inbox: one row per piece of feedback, with its state |
+| `plans/` | proposals in flight - a plan folds into its contract when it lands |
+
+## Evidence has levels
+
+Every availability claim in `shipped.md` carries one, with a citation:
+- `confirmed` - observed in a system of record: the deploy job that ran for that service and
+  succeeded, a ci run that executed the suite. Not an environment marked "deployed" - some
+  pipelines mark it when the run stood down.
+- `reported` - a written claim, cited: a changelog line, an ops note.
+- `unknown` - neither, with the reason. An honest unknown is a correct answer.
+
+Never upgrade a level because a claim sounds sure. Commit ancestry says a change is inside a
+revision, not that the revision is running.
+
+## A contract
+
+```yaml
+---
+state: current            # current | proposed | historical
+capability: quote-intake  # the same slug as its feature board
+audience: team            # team | publishable | restricted
+reviewed: { revision: 606ad4e, scope: "apps/quote, db schema", method: "read code and tests" }
+---
+```
+
+Then: what it does and its limits; who can use it and when; how it works; what it touches (frontend,
+backend, database, workers, integrations); invariants; code and tests; decisions; its frames
+(`scene/frame` ids - say which are designed but not built); the PRs that built it; what is still
+proposed; and `## Availability` pointing at its row in `shipped.md`.
+
+- **Read the code to write it.** Cite `path:line` for every behaviour; a test file's existence is
+  not a run.
+- **No status line, no availability** ("live", "on production", "since 30 Sep") - that is
+  `shipped.md`'s alone. The check fails on both.
+- **One answer per rule.** When a plan amends a rule, write the amended rule - never "section 20
+  wins where it differs".
+- **When code and an accepted document disagree,** the contract says what the code does and the
+  conflict goes to the human. Never decide what was intended.
+
+## When you change things
+
+- **Behaviour** - update its contract in the same change. A change that leaves behaviour alone says
+  `no-contract-change: <capability> - <why>` in the pull request body.
+- **A deploy** - write its row in `shipped.md` with the run that proves it (`playbooks/` usually
+  has the release recipe).
+- **A decision** - in the project's decision log, numbered, with what it applies to.
+- **Feedback** - one row per item: source, who, when, what they said, theme, state (`new`,
+  `triaged`, `proposed`, `planned`, then `shipped` or `declined`), and what resolved it. An item is
+  `shipped` only when `shipped.md` shows its fix `confirmed` where it was raised; a `reported`
+  deploy leaves it `planned`, saying what is missing. On closing, draft - never send - a note back.
+
+## Status on the canvas
+
+Feature and project boards wear a status read from these files (the first that matches wins):
+the board's own `"status"` - `archived`, `paused`, or `blocked` with a `"reason"`; Unknown when the
+evidence cannot be read; In progress when an open plan in `plans/` names the capability (filling by
+phase: `<cap>-specs`, `<cap>-lofi`, `<cap>`); Done when `shipped.md` shows it `confirmed` in an
+availability clause (one per `;`) with no negation or pending word ("nowhere", "not yet", "rolled
+back", "planned") and no pre-production place (staging, preview, dev, local, testing) unless it also
+names production; Done, reported when only `reported`; To do when its contract is `state: current`; else Backlog.
+**Done is never set by hand** - `"status": "done"` fails the check. A board finds its capability by
+its own name, or `"capability": "<slug>"` in its JSON.
+
+## Audiences
+
+`team` - everyone with the repository (the default); `publishable` - may appear on a published
+canvas; `restricted` - never tracked by git (keep it under a gitignored `context/private/`). A
+frame that renders a `team` file onto a published board fails the check. A digest of restricted
+material is restricted, however it is labelled.
+
+## Setting up - when there is no `context/`
+
+Context starts with people. Ask, in one message:
+1. Who is involved - the team and their roles; clients, users, partners?
+2. Where does each relationship happen - channels, email, recorded meetings, docs, in-product
+   feedback, canvas comments?
+3. What is private, and who may see what?
+4. How is this project named in shared spaces - keywords, tags?
+
+Then `npx marver context init`, record the answers in `context/people.md`, and draft from evidence:
+the shipped record from deploy runs and the changelog (`unknown` where nothing proves it), a map from
+the code, contracts for the capabilities that matter now. **Context that exists but is scattered**
+- specs out of date, nobody sure what is live - is a job for
+`context/playbooks/reorganize-context/PLAYBOOK.md`, not for a rewrite.
+
+## The check
+
+`npx marver context check` - availability only in `shipped.md`, a level and a citation on every
+evidence cell, citations and links that resolve, the index under budget and equal to the map,
+audiences, feedback and contract states, playbook freshness; with `--base <ref>` (or in ci on a pull
+request) a contract change or a stated reason for every mapped change. Exit 0 pass, 1 fail, 2 cannot
+determine (fetch full history - `fetch-depth: 0`). `npx marver context index` rewrites the index's
+generated table after you change the map.

package/templates/playbooks/publish-canvas/PLAYBOOK.md

@@ -0,0 +1,72 @@
+---
+name: publish-canvas
+description: Use this when the canvas should be on a URL - a first publish, a republish after changes, or moving it to a new host. Steps with checks, the traps that have bitten, how to roll back.
+last_success: none
+depends_on:
+  - design/publish.json
+  - design/config.ts
+  - Dockerfile
+  - package.json
+  - "service: the canvas host (Railway or any volume-capable host)"
+  - "account: the host, and Marver Sign In or the canvas password"
+---
+
+# Publish a canvas
+
+The recipe. `design/instructions/publish.md` is the reference - every variable, both gates, the
+host contract; read it when a step here is not enough. Marver maintains this file; record your
+project's values (which account, which domain, which gate) and every run in the log at the end.
+
+## Prerequisites
+
+- `@marver-design/marver` resolves from the registry in `package.json` - a `link:` or `file:`
+  dependency cannot ride to a remote host.
+- The three decisions are made: **which boards ship** (`design/publish.json` - publishing is
+  default-closed), **who gets in** (Marver Sign In by default; the canvas password when nothing
+  external may be in the sign-in path), **collaboration** (a persistent volume for comments, or none).
+- The canvas has a name: `share: { name: "..." }` in `design/config.ts`.
+
+## Steps
+
+1. **Build locally first.** `npx marver build`.
+   *Check:* it lists exactly the boards you meant, `textures:` reports the hi-fi frames asleep, and
+   no warning names a deck with no slide frames.
+2. **Check what ships.** `npx marver context check` when the project has `context/`.
+   *Check:* no `team` or `restricted` file is reachable from a published board; a board's status
+   ships only where its publish row says `"showStatus": true`.
+3. **Commit the host files** - a `Dockerfile` (it gives the build a browser for the glass
+   textures) and a `.dockerignore` with `node_modules`, `design/.dist`, `design/.local`.
+   *Check:* `design/.dist` is gitignored and not in the upload.
+4. **Create the service once:** a persistent volume, `MARVER_DATA_DIR` on it, the gate's variables,
+   `MARVER_TRUSTED_PROXY=1` behind a proxy, `MARVER_CLI_TOKEN` generated (`openssl rand -hex 24`),
+   never chosen. *Check:* the host lists the volume mounted at the path the variable names.
+5. **Deploy** - on Railway, `railway up` from the repository root.
+   *Check:* the deploy succeeds, and the URL answers with the gate.
+6. **Walk it.** Sign in as the owner, open each published board, leave a comment, reload.
+   *Check:* the comment survives the reload, and a second account sees only what its rights allow.
+7. **Write the run** in the log below - date, revision, URL, what was checked.
+
+## Traps
+
+- **The upload is the working tree.** Untracked files and full-resolution images go up with it;
+  `marver build` ships images at full size, and a large `design/assets/` can pass the host's upload
+  cap. Keep heavy originals out of published frames, or out of the upload.
+- **A repository linked to another project uploads there.** Check which project and service the
+  host CLI is linked to before `up` - a canvas deployed onto the app's own service replaces the app.
+- **An ephemeral data directory loses every comment** on the next deploy. The volume is not optional
+  once collaboration is on.
+- **Run one instance.** The comment log is single-writer.
+- **Fonts only on your laptop** render differently in the build container; the glass textures then
+  rest live. Bundle fonts with the project.
+- **A republish never clobbers comments** - the server unions the seeded logs on boot - but tabs
+  already open keep the old textures until they reload.
+
+## Rolling back
+
+Redeploy the previous revision the same way. Comments live on the volume, not in the build, so a
+rollback keeps them; a board removed from `publish.json` hides its threads until it ships again.
+
+## Run log
+
+| Date | Revision | Who | URL | Outcome |
+|---|---|---|---|---|

package/templates/playbooks/reorganize-context/PLAYBOOK.md

@@ -0,0 +1,232 @@
+---
+name: reorganize-context
+description: Reorganize an existing project's accumulated context - specs, changelogs, roadmaps, transcripts, research, boards, agent memory - so a fresh agent can answer what is available to users, how it works, why, and what is next, from the repo alone. Builds a shipped record with evidence levels, writes current contracts for a bounded first batch, adds a checker, reconciles only what that batch covers, and proves the result with a blind before/after eval. Works on a branch and never deletes. Use when specs are out of date, nobody can say what is on production, or context is scattered.
+last_success: none
+depends_on: []
+---
+
+# Reorganize a project's context
+
+`design/instructions/context.md` defines the target - the files under `context/`, what each holds,
+the evidence levels. This is how an agent gets an existing project there. Marver maintains it: it
+was first run on a client project in October 2026 (16 of 16 questions answered before and after,
+with 40% fewer tokens after), and each rule exists because that project, or an earlier draft of this
+playbook, broke it. Record your project's runs in the run log at the end.
+
+**The order matters: truth first, then authority, then files.** Moving documents before you know
+which one is right only relocates the contradiction.
+
+## Done means
+
+A fresh agent with no memory reads `context/INDEX.md` and at most two more files per question, and
+answers correctly - or says "unknown" with the reason - what each production service runs, whether a
+capability is available and to whom, how it works, why, and what is next. Every artifact that
+existed before has a recorded disposition. A blind before/after eval proves it.
+
+## Hard rules
+
+1. **Worktree and branch.** Never main. Never touch the original checkout's uncommitted changes.
+2. **Never delete.** Originals are preserved; superseded ones get a header pointing at their
+   replacement. Delete only proven disposable output, listed in the report.
+3. **Code says what is implemented, not what is intended.** When code and an accepted requirement
+   disagree, record both on the exception list - do not pick a winner silently.
+4. **Evidence has levels.** `confirmed`: observed in a system of record. `reported`: a written claim,
+   cited - a changelog line, an ops note, agent memory. `unknown`: neither. Never upgrade a level
+   because a claim sounds sure. Commit ancestry says a change is inside a revision, not that the
+   revision is running.
+5. **Stable paths stay stable.** Frame ids, board and scene slugs, URLs, comment anchors and asset
+   paths are identities. Do not move them in this pass.
+6. **Read-only outside the repo.** You may read deploy records (`gh`, a provider's status command).
+   You never deploy, migrate, query a production database, or edit agent memory. A read that needs
+   credentials you were not given is an exception-list item, not a workaround.
+7. **No secrets; mind the audience.** Never copy credentials. Record sensitive files by path and
+   hash only.
+8. **History is not rewritten.** Old changelog entries stay as written.
+9. **Bounded scope.** This pass rewrites only what the first batch of capabilities needs. Everything
+   else is inventoried and marked `deferred` - never superseded on a guess.
+
+## Phase 0 - baseline, in this order
+
+1. **The original checkout first.** In `context/reorg/start.md` (written later into the worktree,
+   from notes kept outside it): the revision, every dirty and untracked path with the hash of its
+   **working** file (`shasum`), and the tracked hashes (`git ls-files -s`).
+2. **The worktree.** `git worktree add ../<repo>-context -b context/reorganize <revision>` and work
+   only there from now on. Note that the original's dirty files are not in it.
+3. **Preimages.** Hash every context-bearing file in the worktree. This list is what Phase 9
+   compares against: untouched files must match; edited files must appear on the edit list with
+   their preimage hash and the reason.
+4. **The eval, blind.** Follow `eval.md` (beside this file). The questions go into the evaluated
+   agent's prompt; the **answer key never enters the worktree**. Run the before pass now.
+
+## Phase 1 - inventory, bounded
+
+`context/reorg/inventory.md`:
+- **Every** context-bearing path at file or folder level - docs, plans, changelogs, roadmaps,
+  feedback lists, READMEs inside apps, research, `design/` (boards, briefs, sticky notes, content
+  frames, comments), asset indexes, sync logs, `CLAUDE.md` / `AGENTS.md`, CI and scripts that
+  encode procedure, and the agent's project memory (Claude Code:
+  `~/.claude/projects/<path-slug>/memory/`). Size, last change, one-line role.
+- **Section by section** only for documents that touch the first batch (Phase 4).
+- Everything else gets disposition `deferred`.
+
+Classes: current contract · proposed · historical evidence · decision · release/validation evidence ·
+operational procedure · receipt · generated view · convention · tool state.
+
+Flag, with file and line: status lines in prose; supersession inside a current file ("section 20
+wins"); double homes ("the board is canonical, this file is its digest"); conventions pointing at
+paths that no longer exist; design status phrased as product status; hand-kept counts.
+
+Start `context/reorg/exceptions.md` now and keep adding to it in every phase.
+
+## Phase 2 - the shipped record
+
+`context/shipped.md`, two tables, every cell with an evidence level and a citation.
+
+**Services × environments** - discover the services first (deploy workflow, Dockerfiles, provider
+config), then for each: revision, deployed at, how (pipeline / by hand), evidence level + citation,
+migrations applied.
+- `confirmed` needs the run that deployed **that service** and succeeded - the job inside the deploy
+  workflow, or the provider's own deploy status - not an environment record, which some pipelines
+  mark "deployed" even when the run stood down.
+- Hand deploys leave only prose: `reported`, cite the line.
+- A health endpoint that reports no revision cannot confirm one - note the gap.
+- An API you cannot reach: `unknown`, with the error.
+
+**Capabilities** - implemented (code reference); verified (a test or recorded walk: revision,
+environment, date, scope - a test file's existence is not a run); available (which environment, and
+for which tenants - a flag or setting is separate evidence from the deploy, usually `reported`
+unless someone with access confirms it); contract link.
+
+## Phase 3 - the implementation map
+
+`context/map.json`, machine-readable because the checker reads it:
+
+```json
+{ "capabilities": { "quote-intake": { "paths": ["apps/quote/app/**"], "tests": [] } },
+  "excluded": [{ "path": "apps/run/app/preview/**", "reason": "generated from the canvas" }] }
+```
+
+Enumerate from the code: routes and actions, domain commands, tables and SQL functions, migrations
+(every mechanism - a second app may keep its own schema), queued jobs and schedules, integrations,
+config, tests. Map or exclude each, with a reason. Shared files may map to several capabilities. The
+map is routing, not proof that anything is documented.
+
+## Phase 4 - contracts, the first batch
+
+Pick 5-7 capabilities where the evidence showed contradictions or no contract. For each,
+`context/product/<capability>.md`:
+
+```yaml
+state: current
+capability: quote-intake
+audience: team            # team | publishable | restricted
+reviewed: { revision: 606ad4e, scope: "apps/quote, db schema", method: "read code and tests" }
+```
+
+Then: what it does and its limits; who can use it and when; how it works; what it touches -
+frontend, backend, database, workers, integrations; invariants; code and test references; decisions;
+its lo-fi and hi-fi frames and the PRs that built it; what is still proposed. Read the code to write
+it. Apply the plan's amendments - one answer per rule. Shared rules go once in `context/system/`.
+
+The contracts are independent: one agent each, in parallel, from one shared brief (the rules, the
+format, "no availability, no status lines", and a report back of every code-vs-document conflict and
+the exact sections it now covers, `full` or `part`). Then a second model reviews the batch against
+the code before anything relies on it - on its first run it found 18 overstated or mis-cited claims.
+A shared file maps to every contract whose behaviour it changes, or the pull-request rule misses it.
+
+## Phase 5 - the checker, before reconciling anything
+
+`scripts/context-check.mjs` (or the project's language), wired into existing CI. Inputs: front
+matter, `context/map.json`, `context/shipped.md`, the publish configuration and what it pulls in, and
+on a pull request the changed paths (`git diff --name-only <base>...<head>`, base and head from the
+CI event) and the PR body (from the event payload).
+
+Audiences decide where a file may go: `restricted` is never tracked by git and never published;
+`team` may be committed in a private repo but never published; `publishable` may appear in a
+publish. "Published" means everything a canvas build carries: the boards in its publish config, the
+frames on them, and every markdown import, image, note and asset those frames pull in.
+
+| Rule | Result |
+|---|---|
+| a `state: current` doc has a status line (`^\s*\**status\**\s*:`) - lines, not domain words like a bank account's `verified` | fail |
+| a current doc carries supersession markers ("wins where it differs", "overrides section") | fail |
+| a shipped cell has no evidence level, or `confirmed` / `reported` with no citation | fail |
+| a dead relative link, `?raw` import or asset reference under `context/` or in a frame that renders it | fail |
+| `INDEX.md` over 800 words | fail |
+| a `restricted` file tracked by git, or a `team` or `restricted` file reachable from what a publish carries | fail |
+| a PR changes mapped paths without its contract, and without `no-contract-change: <capability> - <reason>` in the PR body | fail on pull requests |
+| an `unknown` evidence cell | pass - honest unknowns are the right answer |
+| a rule it cannot evaluate (no git history, API unreachable) | exit 2, "cannot determine", printed |
+
+Exit 0 pass, 1 fail, 2 cannot determine. In CI, 2 blocks like 1 - fix the cause (fetch full history,
+grant the read). During this pass, Phase 6 may start on exit 0, or on exit 2 when every
+"cannot determine" is on the exception list with its reason.
+
+## Phase 6 - reconcile, first batch only
+
+For each document that the first batch's contracts now supersede, **only the sections they cover**:
+
+| Material | Action |
+|---|---|
+| amendment-stacked spec | its covered sections get "Superseded by `context/product/x.md`"; the file stays as history; uncovered sections stay `deferred` |
+| mixed spec | covered contract → `product/`; review diary stays; open items → backlog |
+| dated feedback lists | covered items get a resolution: contract + shipped row, or `open` |
+| roadmap in two homes | one editable source; the board renders it (`?raw`) |
+| README with contradictions | fix the covered contradiction; keep run instructions by the app |
+| changelog | untouched; its release lines are cited from `shipped.md` |
+| sync log | keep cursors and pending failures; drop "agent memory" as a target |
+| agent memory | project facts the batch needs land in their repo home; `context/reorg/memory-trim.md` proposes the rest |
+| wrong binding instructions | correct them - an agent will obey them |
+
+Diff duplicate prose before merging; check inbound references after every move.
+
+**Line citations move when you insert.** Every note added to an old document shifts the lines that
+contracts cite. Either reconcile before the contracts cite those documents, or remap every citation
+once, mechanically, from the base revision's lines to the new ones - and verify by content (the cited
+line still says what the citation claims). Never run a remap twice. Prefer line-neutral edits where a
+document is cited heavily.
+
+## Phase 7 - entry point and index
+
+- Root `AGENTS.md` is the shared entry point; tool files route to it. Keep existing binding routes
+  (for example to `design/AGENTS.md`).
+- `context/INDEX.md`, **at most 800 words**, counted by the checker: the product in five lines; the
+  capabilities with their contract and shipped row; where each role lives, including healthy homes
+  left in place; the rules (status only in `shipped.md`; a behaviour change updates its contract or
+  says `no-contract-change`; every deploy writes the record; plans fold into contracts when they
+  land; changelog lines start with kind and capability: `[product:quote]`, `[design:board]`,
+  `[infra]`, `[decision 41]`). Generated parts sit between `<!-- generated -->` fences.
+
+## Phase 8 - the exception list, asked once
+
+Everything collected since Phase 1: `unknown` availability that matters, code-vs-intent conflicts,
+disputed capability boundaries, audience and retention calls, reads that need credentials. Ask in
+one numbered batch now - or immediately, only if an item blocks the next step.
+
+| The human decides | The agent decides from evidence |
+|---|---|
+| intended behaviour where code and an accepted requirement conflict | what the code implements |
+| access, audiences, retention, redaction | inventory, hashes, references |
+| priorities, commitments, pilot scope | what is done vs still proposed |
+| disputed capability boundaries | the initial grouping (reversible) |
+
+## Phase 9 - verify
+
+`context/reorg/report.md`:
+
+| Check | Passing result |
+|---|---|
+| Preservation | untouched files match their preimage; every edited file is on the edit list with preimage and reason |
+| Disposition | every inventoried path is unchanged, edited, superseded (covered sections only) or `deferred` |
+| The checker | exit 0, or exit 2 with each "cannot determine" explained |
+| Release honesty | every availability claim carries a level and a citation, or says `unknown` |
+| Reconciliation | no Phase 1 contradiction inside the first batch survives as competing current text |
+| The eval | the after pass beats the before pass, per `eval.md` |
+
+Then stop. The report lists what moved, what was decided without asking, the open exceptions, what
+was deferred, and the memory-trim proposal. The human reviews the branch; nothing merges on its own.
+
+## Run log
+
+| Date | Revision | Who | Batch | Outcome |
+|---|---|---|---|---|