@marver-design/marver 0.15.0 → 0.16.0

package/templates/instructions/boards.md

@@ -10,9 +10,14 @@ viewport and lays it out:
 
 ```json
 { "version": 1, "name": "checkout-compare", "order": 1, "auto": false,
+  "description": "Cart step, direction A vs B side by side - B is the current favourite",
   "nodes": [ { "frame": "checkout-a/cart" }, { "frame": "checkout-b/cart" } ] }
 ```
 
+- `description` - one sentence on what the board is for and where it stands. It is
+  how a later session (or the human's next agent) knows this board without opening
+  it; it lands in design/manifest.json. Write it at creation, keep it true.
+
 - The same frame may appear on many boards, or twice on one (add `"w"`/`"h"` on a
   node to pin a size, `"x"`/`"y"` to place it - e.g. a comparison row: same `y`,
   increasing `x`).
@@ -23,8 +28,8 @@ viewport and lays it out:
   orienting board (an overview or the primary flow) - never a giant one. Boards
   without an `order` sort after the ranked ones, by name. Set `order` deliberately on
   every curated board; it is the first impression. The human can also drag-reorder boards
-  in the sidebar (which rewrites `order`) and rename one from its right-click menu - so
-  your ranking is a starting point they may adjust.
+  in the sidebar (which rewrites `order`), rename one from its right-click menu, and file
+  boards into folders (below) - so your ranking is a starting point they may adjust.
 - `auto: false` boards show exactly their list. `all-scenes` is auto-managed (it holds
   EVERY frame, so it is the heavy one) and always sinks to the BOTTOM of the switcher -
   never the landing board, and never write its file.
@@ -44,6 +49,72 @@ viewport and lays it out:
   version, oldest at the top. Winners live on the feature boards; the archive
   answers "what did we try?" and "what did it look like before?".
 
+## 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:
+
+- **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
+  (`^[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": [
+    { "name": "research", "order": 1, "description": "The thinking behind the live boards - specs, flows, references" },
+    { "name": "archive", "order": 3, "description": "Retired directions and scene versions, oldest first" } ] }
+  ```
+
+  A folder's `description` says what belongs in it - the next session files boards
+  right without asking.
+
+  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
+  empty one - fix it, never delete it.
+
+**Look before you organise: `npx marver boards`** prints the sidebar as the files say
+it is - every folder (and whether it is empty or only implied by its boards), every
+board in reading order with its `order`, the landing board, and whether the registry
+exists (`--json` for the tree). Run it before any of the moves below; the human may
+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.
+- **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.
+- **Rename** a folder: rewrite `folder` on every member AND the registry entry - a
+  registry rename alone leaves the members in the old (implied) folder.
+- **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.
+
+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
+plain.
+
+The human does all of this too - from the sidebar: New folder (right-click the Boards
+header, or its `+`), Rename, Delete folder, "Move to …" on a board, and DRAG: boards
+into and out of folders, folders among boards. 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.
+
 ## The default composition: one horizontal band
 
 A board reads like a page: left to right first, down only for a reason. The

package/templates/instructions/craft.md

@@ -144,6 +144,10 @@ app, and the human attributes the fault to your frame, not to a library.
 
 ## Frame law
 
+- Every frame carries `meta.description` - one sentence, what the screen is for and
+  its state when that is not obvious ("Filled state of the orders table, current
+  direction"). It reaches design/manifest.json; the next session reads it instead
+  of the file.
 - Frames are made of the app's real components and tokens. Rebuilding a lookalike of
   an existing component inside a frame is a defect.
 - Repeated and semantic values (colors, type sizes, radii, the spacing rhythm)

package/templates/instructions/discover.md

@@ -40,12 +40,17 @@ to the SURFACE, not the product.
 
 Create `design/scenes/<scene>/_brief.md`: audience + scene, the one job, mode, the
 flow as a numbered list, content sources, out-of-scope. Ten lines, not a document.
+**Its first non-blank line is the scene's one-sentence description** - purpose and state,
+e.g. `# Checkout - the buyer's path from cart to receipt (v2, after the pricing pivot)`.
+That line lands in `design/manifest.json` as the scene's `description`, so a later
+session reads it without opening the brief; keep it true as the scene moves on (a
+scene that only needs a gist - a version snapshot, an archive - gets a one-line brief).
 Show it. Get the nod.
 
 **Unattended?** When the human is away or has said "don't ask", the interview and
 the nod convert to obligations, not blockers: answer the five questions yourself
-from the repo and reasonable product judgment, mark the brief `UNCONFIRMED` at the
-top, proceed - and surface the brief FIRST when the human returns. Never stall on
+from the repo and reasonable product judgment, mark the brief `UNCONFIRMED` in its
+first line (`# Checkout - … (UNCONFIRMED)`), proceed - and surface the brief FIRST when the human returns. Never stall on
 an absent human; never hide that the brief was self-answered.
 
 ## 4. Align on flow with a diagram frame

package/templates/instructions/iterate.md

@@ -113,11 +113,12 @@ The human picks a direction; then, in one pass:
 1. **The winner takes the clean name.** Drop its letter prefix (or promote it
    over the original file); update goto targets pointing at old ids.
 2. **The losers move to `design/scenes/archive/`** - never deleted, RELABELED:
-   filename `<feature>-<direction>.tsx`, meta.title saying exactly what it was
-   and why it retired, e.g.
-   `{ title: "Routines editor - guided steps (retired: sentence canvas won, sharper mental model)" }`.
+   filename `<feature>-<direction>.tsx`, meta.title saying what it was and
+   meta.description saying why it retired, e.g.
+   `{ title: "Routines editor - guided steps", description: "Retired: the sentence canvas won - sharper mental model" }`.
    A one-line comment at the top of the file carries any longer why. That
-   sentence is the learning - write it while the reason is fresh.
+   sentence is the learning - write it while the reason is fresh; it reaches
+   design/manifest.json, so the next session knows without opening the file.
 3. **The `archive` board stays clean and organized:** a curated board over the
    archive scene, tidied with a layout recipe, grouped by feature. Anyone
    opening it should know what every frame was without asking.

package/templates/instructions/review.md

@@ -26,6 +26,10 @@ however late it surfaced.
 6. **States exist**: for each screen with meaningful states, the empty / error /
    loading siblings are present and reachable.
 7. **Craft floor**: one pass over craft.md's Verify list against the RENDERED frames.
+8. **Descriptions true**: read design/manifest.json once more - every board, folder,
+   scene and frame this session touched carries a `description` that is still true
+   (state words above all: retired, winning, superseded). The next session orients
+   from that file; a stale sentence there costs it more than a missing one.
 
 ## Honesty rules
 

package/templates/instructions/shape.md

@@ -60,7 +60,7 @@ detection is lexical), and declare `intent` on every content frame:
 ```tsx
 import { Doc, Row, Col, Md, Diagram, Img, Chart } from '@marver-design/marver/content'
 
-export const meta = { title: 'Checkout - how it works', intent: 'diagram' }
+export const meta = { title: 'Checkout - how it works', intent: 'diagram', description: 'The agreed flow, five screens - the source for the wireframes' }
 
 export default () => (
   <Doc layout="wide">

package/templates/instructions/welcome.md

@@ -61,7 +61,10 @@ without narrating into the void; your next message is the reveal.
    State your understanding of the product in 2-3 sentences, ask "did I get
    that right?" - then STOP: no further tool calls, end your turn, resume when
    the human replies. (Only exception: they explicitly asked for unattended
-   execution - assume, mark UNCONFIRMED, surface it first.)
+   execution - assume, mark UNCONFIRMED, surface it first.) Once they confirm,
+   write that understanding as one sentence into `description` in
+   design/config.ts - the project's line in design/manifest.json, the first
+   thing every later session reads.
 2. **Confirm the stack aloud - what detection ACTUALLY found.** Read AGENTS.md's
    UI line and design/theme.css and narrate the reality, for example: "Tailwind
    + shadcn/ui; brand tokens in <file>; design/theme.css imports them." No

package/templates/instructions/wireframe.md

@@ -14,6 +14,9 @@ lands on what is actually being decided.
 
 ## The rules (strict)
 
+0. **Every frame says what it is.** `meta.title` and `meta.description` (one sentence:
+   the screen's job, and "wireframe" while it is one) - the manifest carries them, so
+   a later session knows the lo-fi from the hi-fi without opening files.
 1. **Throwaway code is correct here.** Plain divs, inline layout, one file per frame.
    Do NOT build proper components for wireframes and do NOT touch the app's
    `components/` directory - lo-fi structure hardening into real components is how

package/dist/{comments-DHB_8BRa.mjs → comments-oYcZ3cE-.mjs}

@@ -4,8 +4,8 @@ import { i as readLog, r as listBoards, t as appendEvents } from "./comments-DZy
 import { a as syncOnce, i as loadCollab, n as connectClaim, r as connectToken, t as connect } from "./sync-BZaCWqK-.mjs";
 import { n as localProfile } from "./profile-BjAPAJSb.mjs";
 import { join } from "node:path";
-import { createInterface } from "node:readline";
 import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline";
 //#region src/cli/comments.ts
 /**
 * `marver comments <action>` - the collaboration CLI.