@marver-design/marver 0.21.0 → 0.22.1

package/CHANGELOG.md

@@ -2,29 +2,148 @@
 
 Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
 
+## 0.22.1 - 2026-10-06
+
+### Changed
+
+- **A project without `context/` hears about it.** The AGENTS contract opens with it: in a
+  repository with no `context/`, every reply in which an agent made, specced or changed a feature or
+  project board ends with one line - every feature board reads Backlog, nothing records what shipped,
+  want me to set it up? - until the human answers; a no stands for the session, and nothing is set up
+  unasked. `instructions/boards.md`, `npx marver boards`, `npx marver boards new` (feature, project),
+  `npx marver init` and `marver dev` at boot point at it. In 0.22.0 a routing row merely pointed at
+  the instruction: Claude Code and Codex, asked to spec a feature, both read it and never mentioned
+  it; with the line, both end their reply with it.
+- `npx marver init` on an existing canvas no longer ends with the first-session hand-off - an
+  upgrade is not a first session.
+
+### Docs
+
+- **"Set up our context" is the whole ask.** `instructions/context.md`'s setup is now the full recipe,
+  in order: the kind (`product` or `knowledge`), the draft from evidence, the canvas reading it -
+  typed folders, feature boards named after their capability, a start board - and the check in ci.
+  After upgrading (`npx marver init`), tell your agent: "Set up our context."
+
+## 0.22.0 - 2026-10-06
+
+### Added
+
+- **Context.** `npx marver context init` gives a repository `context/`: an index any agent reads first,
+  `shipped.md` - the only place availability is written, every claim `confirmed`, `reported` or
+  `unknown` with a citation - one current contract per capability, a map of which code each capability
+  lives in, a feedback inbox, and two playbooks Marver maintains (`reorganize-context`,
+  `publish-canvas`). The root `AGENTS.md` gets one line routing every agent to the index.
+- **`npx marver context check`** keeps it true, in ci or by hand: no availability or status line in a
+  contract, no "section 20 wins", a level and a citation on every evidence cell, links and `path:line`
+  citations that resolve, the index under 800 words and equal to the map, `restricted` files out of
+  git and `team` files off published boards, feedback closed only on a confirmed deploy, no
+  `"status": "done"` on a board - and on a pull request, a contract change with every change to a
+  contracted capability's code, or `no-contract-change: <capability> - <why>` in the body. Exit 0
+  pass, 1 fail, 2 cannot determine. `npx marver context index` regenerates the index's table.
+- **Board types.** Every board wears an icon for what it is for - `start`, `feature`, `surface`,
+  `project`, `feedback`, `context`, `deck`, `archive` - stated on the board or inherited from its
+  folder (`"type"` on a folder's entry in `_folders.json`), then the folder's parent.
+- **Status, read from evidence.** Feature and project boards wear a status in the sidebar - Backlog,
+  To do, In progress (filling by phase: spec, lo-fi, hi-fi), Done, Done reported, Unknown - read from
+  `context/`, or decided on the board: archived, paused, blocked with a reason. Done is never set by
+  hand. The tooltip says what decided it; a change to the files reaches the sidebar without a reload.
+  An open status is an outline in its colour; a settled one is filled - Done green, Archived a box.
+  Right-click a feature or project board, **Change status…**: a Linear-style picker that offers only
+  what a person decides - Blocked (it asks why), Paused, Archived, Back to the evidence - and shows
+  what the evidence says; never Done.
+  `npx marver boards` and the manifest carry types and statuses too.
+- **Starting points.** `npx marver init --kind product|knowledge` gives a fresh canvas the typed
+  folders every canvas shares: Start here, Features and Surfaces or Projects, Feedback, Context,
+  Archive. `npx marver folders add <module>` adds one later. `npx marver boards new <name>` makes a
+  board in its type's starting layout - a feature's spec, lo-fi and hi-fi bands, a start board
+  rendering `context/INDEX.md` and `context/shipped.md`, a deck on its title slide.
+- **`"showStatus": true`** on a `publish.json` row shows a board's status on the published canvas -
+  only Backlog to Done, only when the evidence behind it is publishable (`audience: publishable` under
+  `context/`; a scene brief's phase counts unless the brief says otherwise - it ships with its board),
+  never a blocked reason or the evidence itself, with the date it was read.
+- **Knowledge work.** `npx marver context init --kind knowledge` keeps a delivered record - Project
+  and Delivered columns - and project boards read Done from it. A repository without a canvas gets
+  the conventions as `context/README.md`.
+
+### Changed
+
+- **A published board never carries its `status`, `reason` or `capability`,** and the build fails if
+  one would - or if a published status or meta carries anything beyond what is allowed. A board's type
+  suggests how it publishes (a deck as `slides`, a context board as `refs`, a project as `doc`) as a
+  note in the build; a publish row keeps presenting the way it always has until it names a `type`.
+- **A fresh `npx marver init` creates typed folders** - product ones when an app is detected,
+  knowledge ones otherwise, said out loud. On a canvas that already has boards or folders, init adds
+  them only with `--kind`, and never renames or moves one.
+- The board autosave keeps `type`, `capability`, `status` and `reason` from disk like `title` and
+  `description`, and a folder drag keeps a folder's `type`.
+
+### Fixed
+
+- **Nested sidebar rows line up.** A board or sub-folder's icon now starts exactly where its folder's
+  name starts, at both levels, with one icon-to-name gap throughout - 0.21.0's indent left a folder's
+  boards 2px short of that line and a sub-folder's boards 6px past it. Drop seams follow the rows.
+- **Renaming the open board after an agent edited it works.** The rename retried with the canvas's
+  old copy of the file and failed again; it now reloads the board and retries once - and only when
+  nothing was edited, dragged or switched while the request was out, so a reload never lands over
+  your own change.
+
+### Docs
+
+- A new guide, [docs/context.md](docs/context.md): the files, the evidence levels, the check and its
+  ci step, statuses on the canvas, audiences. [Boards and folders](docs/boards-and-folders.md) gains
+  types, status and starting points; [Sharing](docs/sharing.md) documents `showStatus` and the
+  proposed publish type; the README links it all.
+- A new managed instruction, `instructions/context.md`, routed from the AGENTS contract: what to read
+  at session start, when a contract changes, the setup interview when there is no `context/`.
+  `instructions/boards.md` teaches types, status and the new commands.
+
+### Upgrading
+
+- Run `npx marver init` to take the new instructions (unedited files update in place; edited ones are
+  staged in `design/.local/latest/`). Existing canvases keep their sidebar; `--kind` adds the typed
+  folders when you want them.
+- A board that says `"status": "done"` now fails `marver context check` - remove it; Done comes from
+  `context/shipped.md`.
+- Folder registry writes now take a short lock, `design/boards/.folders.lock`, so the sidebar, `folders
+  add` and `init --kind` never overwrite one another; `npx marver init` adds it to `design/.gitignore`.
+
 ## 0.21.0 - 2026-10-05
 
 ### Added
 
 - **Folders in folders.** A folder can now hold folders, one level down, so the sidebar has two
-  levels: a board sits at the root, in a folder, or in a sub-folder. Every folder move works at
-  both levels, from the sidebar and from the files: **New folder inside** on a top-level folder's
-  menu, **Move to top level** for a sub-folder, boards dragged into a sub-folder or between its
-  boards, a folder without sub-folders dragged into a top-level folder. Deleting a folder moves
-  what it held up one level, into its place - never a board lost. **Move to new folder** now
-  makes the folder at the board's own level: a sub-folder when the board sits in a folder.
-- The files carry it with one new field: a sub-folder's entry in `design/boards/_folders.json`
-  names its `"parent"`. A board's `folder` stays the one folder it sits in directly. `npx marver
-  boards` prints the nested tree, the manifest lists each folder's `parent`, and a published
-  canvas keeps the nesting of its published boards (a folder with nothing published at any depth
-  stays out of the bundle). `instructions/boards.md` teaches agents the moves.
+  levels: a board sits at the root, in a folder, or in a sub-folder. Every folder move works at both
+  levels, from the sidebar and from the files - **New folder inside** on a top-level folder's menu,
+  **Move to top level** on a sub-folder, a board dragged onto a sub-folder or between its boards, a
+  folder with no sub-folders dragged into a top-level folder. At the bottom of a folder, where one
+  gap belongs to several levels, the seam is indented with the level a release lands in and the
+  pointer's indent picks it. Deleting a folder moves what it held up one level, into its place -
+  never a board lost.
+- **One new field carries it.** A sub-folder's entry in `design/boards/_folders.json` names its
+  `"parent"`; a board's `folder` stays the one folder it sits in directly, and a sub-folder keeps its
+  title and agent-facing description like any folder. `npx marver boards` prints the nested tree, the
+  manifest lists each folder's `parent`, and a published canvas keeps the nesting of its published
+  boards - a folder with nothing published at any depth stays out of the bundle.
+
+### Changed
+
+- **Move to new folder** makes the folder at the board's own level: a sub-folder in the board's slot
+  when the board sits in a folder, right after its sub-folder when it sits in one. At the root it
+  behaves as before.
+
+### Docs
+
+- A new guide, [docs/boards-and-folders.md](docs/boards-and-folders.md): the sidebar moves, the two
+  files, descriptions, what publishing shows, mixed-version teams. The README links it and describes
+  two levels. `instructions/boards.md` and the AGENTS contract teach agents the two-level moves,
+  including renaming a folder slug (its sub-folders' `parent` moves with it) and deleting one.
 
 ### Upgrading
 
-- **The registry says `"version": 2` while any folder nests, and 1 when none does.** Marver 0.20
-  and earlier refuse a version-2 registry with an error instead of rewriting it flat, so a
-  teammate on an older version sees a clear message - upgrade the whole team before nesting.
-  A canvas tab opened before the upgrade is refused the same way once folders nest: reload it.
+- **The registry says `"version": 2` while any folder nests, and `1` when none does.** Marver 0.20
+  and earlier refuse a version-2 registry with an error instead of rewriting it flat, so upgrade the
+  whole team before nesting a folder. A browser tab opened before the upgrade is refused the same way
+  once folders nest - reload it.
 - Run `npx marver init` to take the new folders guidance (unedited instruction files update in
   place; edited ones are staged in `design/.local/latest/`).
 

package/README.md

@@ -8,7 +8,7 @@
 
 Screens, prototypes, specs, and now slide decks - all real code, all on one canvas, all shareable with people who sign in as themselves.
 
-[marver.design](https://marver.design) · [Slides](docs/slides.md) · [Sticky notes](docs/sticky-notes.md) · [Live Jam](docs/live-jam.md) · [Deploying a canvas](docs/publish.md) · [Sharing](docs/sharing.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Issues](https://github.com/TNEP4/marver/issues)
+[marver.design](https://marver.design) · [Boards and folders](docs/boards-and-folders.md) · [Context](docs/context.md) · [Slides](docs/slides.md) · [Sticky notes](docs/sticky-notes.md) · [Live Jam](docs/live-jam.md) · [Deploying a canvas](docs/publish.md) · [Sharing](docs/sharing.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Issues](https://github.com/TNEP4/marver/issues)
 
 ## Quickstart
 
@@ -40,7 +40,7 @@ Frames appear on the canvas the moment the files land. That's the loop.
 
 ## The canvas
 
-- **Frames, scenes, boards.** Frames are screens, scenes group them (`design/scenes/<scene>/<frame>.tsx`), boards arrange them. Agents write `design/boards/<name>.json` (a frame list is enough); switch boards at the top of the sidebar. `all-scenes` is auto-managed. Right-click any board, scene, or frame in the sidebar to copy its path - the exact string to paste to your agent - and rename or drag-reorder boards from there too. Boards can live in folders: right-click the Boards header (or its `+`) for a new one, name it inline, drag boards in and out (the seam shows exactly where a release lands) and folders among boards; agents do the same by writing `"folder": "<name>"` on a board and `design/boards/_folders.json` for empty or ranked folders (`npx marver boards` prints the tree). Boards, folders and scenes take a `title` - any name you like, "MVP", "UI", "Checkout (v2) 🛒" - while their file, key and directory stay the slug agents address; Rename in the sidebar edits the title. Every object takes a one-sentence `description` (project in `design/config.ts`, boards and folders in their JSON, a scene's first `_brief.md` line, `meta.description` on a frame) and `design/manifest.json` carries them all - a new agent session orients in one read.
+- **Frames, scenes, boards.** Frames are screens, scenes group them (`design/scenes/<scene>/<frame>.tsx`), boards arrange them. Agents write `design/boards/<name>.json` (a frame list is enough); switch boards at the top of the sidebar. `all-scenes` is auto-managed. Right-click any board, scene, or frame in the sidebar to copy its path - the exact string to paste to your agent - and rename or drag-reorder boards from there too. Boards can live in folders, two levels deep - a folder holds boards and folders, a sub-folder holds boards: right-click the Boards header (or its `+`) for a new folder, a folder for a new one inside it, name it inline, drag boards in and out at either level (the seam shows exactly where a release lands, indented with the level) and folders among boards or into a folder; agents do the same by writing `"folder": "<name>"` on a board and `design/boards/_folders.json` for empty, ranked or nested folders (a sub-folder names its `"parent"`; `npx marver boards` prints the tree). The [boards and folders guide](docs/boards-and-folders.md) has every move. Boards, folders and scenes take a `title` - any name you like, "MVP", "UI", "Checkout (v2) 🛒" - while their file, key and directory stay the slug agents address; Rename in the sidebar edits the title. Every board wears an icon for its type - start, feature, surface, project, feedback, context, deck, archive - its own or its folder's, and feature boards wear a status read from the project's `context/`. Every object takes a one-sentence `description` (project in `design/config.ts`, boards and folders in their JSON, a scene's first `_brief.md` line, `meta.description` on a frame) and `design/manifest.json` carries them all - a new agent session orients in one read.
 - **Devices view.** Hotkeys `1`-`5` (or the Devices menu) size every frame to mobile / tablet / laptop / monitor / tv to sweep your breakpoints; `0` restores your own layout exactly. Widths live in `design/config.ts`.
 - **Prototype links.** `data-goto="scene/frame"` on any element links frames into a walkable prototype - across boards, too.
 - **Five ways to view a board.** The canvas (frames on a plane), the board (the same, tidy), **present** (`p`: a full-screen clickable walkthrough - `data-goto` navigates, arrows step, `[` / `]` cycle variants, laser, comments, theme and device pickers in the toolbar), **focus** (one frame as a document - the reading preset for specs), and **slides** (a deck). A published board names its landing view; a frame deep link opens straight into it.
@@ -50,6 +50,16 @@ Frames appear on the canvas the moment the files land. That's the loop.
 - **Charts and video in any frame.** `Chart` (Apache ECharts, SVG, still at rest) inherits the ink, typeface and accent of whatever frame it sits in - a Tailwind dashboard, a dark spec, a slide - sizes its type to the context and follows the layout on resize. `Video` is poster-first everywhere: click to play wherever the frame is live, `autoplay` for an ambient loop, `ratio` for vertical clips; omit the poster and marver renders one from the clip. A screen with a chart or a clip is still a screen.
 - **Copy as image.** Select a frame, press `i` - a 2x PNG of it lands on the clipboard, rendered by the same headless Chrome that serves `marver shot`; `⇧i` for 4x (a 1280×720 slide is 5120×2880, whatever size its node has). Paste into Slack, a doc, or a chat with your agent.
 
+## Context
+
+Code says what is implemented; `context/` says the rest - what is available and to whom, how each
+capability works, why, what is next - with evidence, in files any agent reads first.
+`npx marver context init` sets it up, `npx marver context check` keeps it true in ci (availability
+only in the shipped record, every claim with a level and a citation, a contract change with every
+behaviour change), and the canvas reads the same files: feature boards wear Backlog, To do, In
+progress, Done - never set by hand. Existing projects with scattered specs get a playbook that
+reorganizes them on a branch and proves it with a blind eval. [The context guide](docs/context.md).
+
 ## Slides
 
 A deck is a scene of `slide: true` frames. On the canvas they are frames like any other - comment on them, laser them, fork variants, drag them to reorder the deck (the board's reading order is the play order). Press `p` on a slides board and you get slides mode: arrows / Space / click to advance, `d` cycles the theme, morphs between slides where the agent named the same element twice.
@@ -90,7 +100,7 @@ The same glow, driven from the terminal. When your agent takes a request, it cre
 
 | Command | What it does |
 |---|---|
-| `npx marver init` | Scaffold `design/` in this repo (safe to re-run; refreshes managed files) |
+| `npx marver init [--kind product\|knowledge]` | Scaffold `design/` in this repo (safe to re-run; refreshes managed files); a fresh canvas gets the kind's typed folders |
 | `npx marver dev` / `canvas` | Start the local canvas - hot reload, comments, Live Jam armed (`--port`, default 5199) |
 | `npx marver build` | Static export → `design/.dist`; what ships comes from `design/publish.json` (default-closed) |
 | `npx marver serve` | Serve the export; `MARVER_ID_ISSUER` or `MARVER_PASSWORD` gates it, `MARVER_DATA_DIR` persists comments + accounts |
@@ -98,7 +108,10 @@ The same glow, driven from the terminal. When your agent takes a request, it cre
 | `npx marver comments …` | The agent's queue: `connect <url>` · `sync` · `list` · `reply` · `resolve` · `invite <email>` · `revoke <email>` |
 | `npx marver work …` | Working glow from the terminal: `start <scene/frame …>` · `done … \| --all` · `list` |
 | `npx marver shot <frame ...> \| --scene <name> \| --all [--scale 1-4] [--json]` | Render frames headless and print the PNG paths (needs `dev` running); a scene is one browser, several frames at a time; 2x by default |
-| `npx marver boards [--json]` | The sidebar as the files say it is: folders, boards in reading order with their title, `order` and description, the landing board |
+| `npx marver boards [--json]` | The sidebar as the files say it is: folders and sub-folders, boards in reading order with their title, type, status, `order` and description, the landing board |
+| `npx marver boards new <name> [--folder f] [--type t]` | A board in its type's starting layout - a feature's spec, lo-fi and hi-fi bands, a start board rendering `context/` |
+| `npx marver folders add <module ...>` | Add a typed folder: `start`, `features`, `surfaces`, `projects`, `feedback`, `context`, `decks`, `archive` |
+| `npx marver context init \| check \| index` | Set up `context/`; check it (exit 0 / 1 / 2; `--base`, `--body-file` for a pull request); regenerate the index's capability table |
 
 ## Shortcuts
 

package/dist/{bake-BID6mo-N.mjs → bake-CvY8QR3L.mjs}

@@ -1,4 +1,4 @@
-import { AREA, SURFACE, pool, shotConcurrency, withBrowser } from "./shot-DswS4iRK.mjs";
+import { AREA, SURFACE, pool, shotConcurrency, withBrowser } from "./shot-BAR8hmU9.mjs";
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
 import { join, sep } from "node:path";
 import { createHash } from "node:crypto";