@marver-design/marver 0.15.0 → 0.16.1

package/src/shared/board-tree.ts

@@ -0,0 +1,343 @@
+/**
+ * Board folders - the pure tree shared by the sidebar, the dev API, the build and the
+ * tests. Files are the truth: a board says which folder it sits in (`folder` on the
+ * board file, ranked among its siblings by `order`), and `design/boards/_folders.json`
+ * says which folders exist and where they rank at the root. One level only: folders
+ * hold boards, never folders. `all-scenes` never enters the tree - callers pin it last.
+ */
+
+/** The on-disk name grammar shared by boards and folders (a board name is a filename). */
+export const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/
+export const NAME_MAX = 64
+export const isBoardName = (n: unknown): n is string => typeof n === 'string' && n.length >= 1 && n.length <= NAME_MAX && BOARD_NAME.test(n)
+
+/** The folder registry beside the boards - underscore = infrastructure, never a board. */
+export const FOLDERS_FILE = '_folders.json'
+/** Is this basename in design/boards/ a board file? `_folders.json`, temp files and any
+ *  off-grammar name are not - every lister (dev API, build, watcher) shares this rule. */
+export const isBoardFile = (f: string): boolean => f.endsWith('.json') && isBoardName(f.slice(0, -5))
+
+export type Folder = { kind: 'folder'; name: string; boards: string[]; title?: string; description?: string }
+export type TreeItem = { kind: 'board'; name: string } | Folder
+
+export interface BoardRow { name: string; order?: number; folder?: string; title?: string }
+export interface FolderRow { name: string; order?: number; title?: string; description?: string }
+
+/** A description off a file: one sentence, trimmed, capped - absent when empty or not a string. */
+export const DESCRIPTION_MAX = 300
+export const readDescription = (v: unknown): string | undefined => {
+  if (typeof v !== 'string') return undefined
+  const s = v.trim().replace(/\s+/g, ' ').slice(0, DESCRIPTION_MAX)
+  return s || undefined
+}
+
+/** A title off a file - what humans see, free text: any casing, punctuation, emoji. Control
+ *  characters dropped, whitespace collapsed, capped in code points (never half a surrogate
+ *  pair). Absent when empty or not a string; the display then falls back to the slug. */
+export const TITLE_MAX = 120
+export const readTitle = (v: unknown): string | undefined => {
+  if (typeof v !== 'string') return undefined
+  // eslint-disable-next-line no-control-regex
+  const s = Array.from(v.replace(/[\u0000-\u001f\u007f]/g, ' ').trim().replace(/\s+/g, ' ')).slice(0, TITLE_MAX).join('').trim()
+  return s || undefined
+}
+/** Title Case off a slug - the display when no title is set ("old-stuff" → "Old Stuff"). */
+export const humanize = (s: string): string => s.replace(/-/g, ' ').replace(/(^|\s)\S/g, (c) => c.toUpperCase())
+/** What a board, folder or scene is called on screen: its title, else its humanized slug. */
+export const labelOf = (name: string, title?: string): string => title ?? humanize(name)
+
+const rank = (o: number | undefined) => (typeof o === 'number' && Number.isFinite(o) ? o : Infinity)
+/** A folder's title and description, present only when set. */
+const folderExtras = (it: { title?: string; description?: string }) => ({ ...(it.title ? { title: it.title } : {}), ...(it.description ? { description: it.description } : {}) })
+
+/** The registry file's shape. Returns the rows, or a string naming what is wrong - a
+ *  malformed registry is an ERROR the human must fix (silently reading it as empty would
+ *  let the next drag overwrite their folders), while a missing file is simply no folders. */
+export function parseFolders(raw: unknown): FolderRow[] | string {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return 'expected an object'
+  const { version, folders } = raw as { version?: unknown; folders?: unknown }
+  if (version !== undefined && version !== 1) return `unsupported version ${String(version)}`
+  if (!Array.isArray(folders)) return 'expected a "folders" array'
+  const out: FolderRow[] = []
+  const seen = new Set<string>()
+  for (const f of folders) {
+    const name = (f as { name?: unknown })?.name
+    if (!isBoardName(name)) return 'a folder needs a name - lowercase letters, numbers and dashes'
+    if (seen.has(name)) return `folder "${name}" is listed twice`
+    seen.add(name)
+    const o = (f as { order?: unknown }).order
+    const t = readTitle((f as { title?: unknown }).title)
+    const d = readDescription((f as { description?: unknown }).description)
+    out.push({ name, ...(typeof o === 'number' && Number.isFinite(o) ? { order: o } : {}), ...(t ? { title: t } : {}), ...(d ? { description: d } : {}) })
+  }
+  return out
+}
+
+/** Sidebar order from the files. Root: boards with no folder + every folder (registered
+ *  or implied by a board), ranked by `order` then kind (board before folder) then name.
+ *  Inside a folder: its boards by `order` then name. Unranked sorts after ranked. A folder's
+ *  title and description ride on its item (they live in the registry a tree write rewrites);
+ *  a board's title stays with its row - it lives in the board's own file. */
+export function buildTree(boards: BoardRow[], folders: FolderRow[]): TreeItem[] {
+  const folderOrder = new Map<string, number | undefined>()
+  const folderMeta = new Map<string, { title?: string; description?: string }>()
+  for (const f of folders) if (isBoardName(f.name) && !folderOrder.has(f.name)) { folderOrder.set(f.name, f.order); folderMeta.set(f.name, folderExtras(f)) }
+  const members = new Map<string, BoardRow[]>()
+  const rootBoards: BoardRow[] = []
+  for (const b of boards) {
+    if (!isBoardName(b.name) || b.name === 'all-scenes') continue
+    const folder = isBoardName(b.folder) ? b.folder : undefined
+    if (!folder) { rootBoards.push(b); continue }
+    if (!folderOrder.has(folder)) folderOrder.set(folder, undefined)   // implied by the board alone
+    const list = members.get(folder) ?? []
+    list.push(b)
+    members.set(folder, list)
+  }
+  const byRank = (a: BoardRow, b: BoardRow) => rank(a.order) - rank(b.order) || a.name.localeCompare(b.name)
+  type Root = { item: TreeItem; order: number | undefined }
+  const root: Root[] = [
+    ...rootBoards.map((b) => ({ item: { kind: 'board', name: b.name } as TreeItem, order: b.order })),
+    ...[...folderOrder].map(([name, order]) => ({
+      item: { kind: 'folder', name, boards: (members.get(name) ?? []).sort(byRank).map((b) => b.name), ...(folderMeta.get(name) ?? {}) } as TreeItem,
+      order,
+    })),
+  ]
+  root.sort((a, b) => rank(a.order) - rank(b.order) || (a.item.kind === b.item.kind ? 0 : a.item.kind === 'board' ? -1 : 1) || a.item.name.localeCompare(b.item.name))
+  return root.map((r) => r.item)
+}
+
+/** Every board in reading order - the order the switchers and the landing pick use. */
+export function flatten(tree: TreeItem[]): string[] {
+  const out: string[] = []
+  for (const it of tree) { if (it.kind === 'board') out.push(it.name); else out.push(...it.boards) }
+  return out
+}
+
+/** The wire shape of a tree write (`POST boards/reorder`): plain strings for root boards,
+ *  `{ folder, boards }` for folders - what the sidebar posts and what the server validates.
+ *  A folder's title and description ride with it (they live in the registry the write
+ *  rewrites); a board's title lives in its own file and never rides the tree. */
+export type WireItem = string | { folder: string; boards: string[]; title?: string; description?: string }
+export const toWire = (tree: TreeItem[]): WireItem[] =>
+  tree.map((it) => (it.kind === 'board' ? it.name : { folder: it.name, boards: [...it.boards], ...folderExtras(it) }))
+export const fromWire = (wire: WireItem[]): TreeItem[] =>
+  wire.map((w) => (typeof w === 'string' ? { kind: 'board', name: w } : { kind: 'folder', name: w.folder, boards: [...w.boards], ...folderExtras(w) }))
+
+/** Validate a wire tree off the network. Returns the error, or null when it is sound:
+ *  every name on-grammar, `all-scenes` nowhere, no board twice, no folder twice, no
+ *  nesting (a folder's boards are strings), bounded. */
+export const TREE_MAX_BOARDS = 200
+export const TREE_MAX_FOLDERS = 50
+export function validateWire(wire: unknown): string | null {
+  if (!Array.isArray(wire)) return 'invalid tree'
+  const boards = new Set<string>(), folders = new Set<string>()
+  const board = (n: unknown): string | null => {
+    if (!isBoardName(n) || n === 'all-scenes') return 'invalid board name in tree'
+    if (boards.has(n)) return `board "${n}" appears twice`
+    boards.add(n)
+    return null
+  }
+  for (const w of wire) {
+    if (typeof w === 'string') { const e = board(w); if (e) return e; continue }
+    if (!w || typeof w !== 'object' || Array.isArray(w)) return 'invalid tree item'
+    const { folder, boards: kids, title, description } = w as { folder?: unknown; boards?: unknown; title?: unknown; description?: unknown }
+    if (!isBoardName(folder)) return 'invalid folder name in tree'
+    if (title !== undefined && (typeof title !== 'string' || Array.from(title).length > TITLE_MAX)) return 'invalid folder title'
+    if (description !== undefined && (typeof description !== 'string' || description.length > DESCRIPTION_MAX)) return 'invalid folder description'
+    if (folders.has(folder)) return `folder "${folder}" appears twice`
+    folders.add(folder)
+    if (!Array.isArray(kids)) return 'invalid folder in tree'
+    for (const k of kids) { const e = board(k); if (e) return e }
+  }
+  if (boards.size > TREE_MAX_BOARDS || folders.size > TREE_MAX_FOLDERS) return 'tree too large'
+  return null
+}
+
+/** What the human types becomes a slug: "Old stuff" → "old-stuff". Empty when nothing
+ *  survives - the caller keeps the input open and says so. Always on-grammar or empty. */
+export function slugify(raw: string): string {
+  const s = raw.trim().toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-+|-+$/g, '').slice(0, NAME_MAX).replace(/-+$/g, '')
+  return isBoardName(s) ? s : ''
+}
+
+// ---- tree mutations (pure; the sidebar shows the result at once and persists it) ----
+
+export const cloneTree = (t: TreeItem[]): TreeItem[] => t.map((it) => (it.kind === 'board' ? { ...it } : { ...it, boards: [...it.boards] }))   // a folder's description rides along
+export const rootIndex = (t: TreeItem[], kind: TreeItem['kind'], name: string) => t.findIndex((it) => it.kind === kind && it.name === name)
+export const folderIn = (t: TreeItem[], name: string): Folder | undefined => t.find((it): it is Folder => it.kind === 'folder' && it.name === name)
+export const folderOf = (t: TreeItem[], board: string): string | null => t.find((it): it is Folder => it.kind === 'folder' && it.boards.includes(board))?.name ?? null
+export const boardsIn = (t: TreeItem[]): string[] => flatten(t)
+export const foldersIn = (t: TreeItem[]): string[] => t.filter((it) => it.kind === 'folder').map((it) => it.name)
+
+/** Remove a board wherever it sits; returns the list it left (root = null) and its index there. */
+export function takeBoard(t: TreeItem[], board: string): { list: string | null; index: number } | null {
+  const ri = rootIndex(t, 'board', board)
+  if (ri >= 0) { t.splice(ri, 1); return { list: null, index: ri } }
+  for (const it of t) {
+    if (it.kind !== 'folder') continue
+    const i = it.boards.indexOf(board)
+    if (i >= 0) { it.boards.splice(i, 1); return { list: it.name, index: i } }
+  }
+  return null
+}
+
+/** What is being dragged, and where it may land: a slot in a list (root = null) or the
+ *  inside of a folder (appended at its end). */
+export type Drag = { kind: TreeItem['kind']; name: string }
+export type Drop = { list: string | null; index: number } | { into: string }
+
+/** A row the sidebar rendered, measured - the list as the human sees it, top to bottom,
+ *  the pinned `all-scenes` row included (it is the root's end). `open` is the folder's
+ *  disclosure; `left` is the row's left edge, from which the child indent is measured. */
+export interface Row { kind: TreeItem['kind']; name: string; parent: string | null; open?: boolean; top: number; bottom: number; left: number }
+/** Px a board row indents inside a folder; the seams inside draw from there too. */
+export const INDENT = 28
+
+/** The drop target for a pointer at (x, y) over the rendered rows - never null inside the
+ *  list (the ends clamp), so a release anywhere over the sidebar lands somewhere the seam
+ *  showed. Boards: the middle band of a folder header (a closed one: its lower band too) is
+ *  INTO it; otherwise the nearest gap by row midlines, read from the row above it: after a
+ *  root board or a closed folder = root; after an open folder's header, or between two of
+ *  its boards = inside; after a folder's LAST board (or under an open empty folder) the gap
+ *  is shared between the folder and the root, and the row under the pointer decides: still
+ *  over that last board (that header), at or right of the indent the seams draw at = inside;
+ *  over the root row below it, or in the gutter = root, after the folder. Folders: root gaps
+ *  only, each root item one block. */
+export function resolveDrop(t: TreeItem[], d: Drag, rows: Row[], x: number, y: number): Drop | null {
+  const mid = (r: { top: number; bottom: number }) => (r.top + r.bottom) / 2
+  if (d.kind === 'folder') {
+    const blocks: { top: number; bottom: number }[] = []
+    for (const r of rows) {
+      if (r.parent && blocks.length) { blocks[blocks.length - 1]!.bottom = r.bottom; continue }
+      blocks.push({ top: r.top, bottom: r.bottom })
+    }
+    let g = 0
+    for (const b of blocks) if (y >= mid(b)) g++
+    return { list: null, index: Math.min(g, t.length) }
+  }
+  for (const r of rows) {
+    if (r.kind !== 'folder' || y < r.top || y >= r.bottom) continue
+    const f = (y - r.top) / (r.bottom - r.top)
+    if (f >= 0.25 && (f < 0.75 || !r.open)) return { into: r.name }
+  }
+  let g = 0
+  for (const r of rows) if (y >= mid(r)) g++
+  const above = rows[g - 1], below = rows[g]
+  if (!above) return { list: null, index: 0 }
+  if (above.name === 'all-scenes') return { list: null, index: t.length }
+  const inside = (folder: string, index: number, alt: Drop): Drop => (y < above.bottom && x >= above.left + INDENT ? { list: folder, index } : alt)
+  if (above.kind === 'board') {
+    if (!above.parent) { const i = rootIndex(t, 'board', above.name); return i < 0 ? null : { list: null, index: i + 1 } }
+    const fi = rootIndex(t, 'folder', above.parent)
+    const i = folderIn(t, above.parent)?.boards.indexOf(above.name) ?? -1
+    if (fi < 0 || i < 0) return null
+    if (below?.kind === 'board' && below.parent === above.parent) return { list: above.parent, index: i + 1 }
+    return inside(above.parent, i + 1, { list: null, index: fi + 1 })
+  }
+  const fi = rootIndex(t, 'folder', above.name)
+  if (fi < 0) return null
+  if (!above.open) return { list: null, index: fi + 1 }
+  if (below?.kind === 'board' && below.parent === above.name) return { list: above.name, index: 0 }
+  return inside(above.name, 0, { list: null, index: fi + 1 })
+}
+
+/** A target that would leave the item where it is: nothing to show, nothing to drop. Into
+ *  the folder a board already sits in means "to its end" - a no-op only when it is last. */
+export function isOwnSlot(t: TreeItem[], d: Drag, target: Drop): boolean {
+  if ('into' in target) {
+    if (d.kind !== 'board') return true
+    const f = folderIn(t, target.into)
+    return !!f && f.boards[f.boards.length - 1] === d.name
+  }
+  let from = -1
+  if (d.kind === 'folder') from = target.list === null ? rootIndex(t, 'folder', d.name) : -1
+  else if (target.list === null) from = rootIndex(t, 'board', d.name)
+  else from = folderIn(t, target.list)?.boards.indexOf(d.name) ?? -1
+  return from >= 0 && (target.index === from || target.index === from + 1)
+}
+
+/** The tree after a drop, or null when the drop is impossible on this tree. */
+export function applyDrop(tree: TreeItem[], d: Drag, target: Drop): TreeItem[] | null {
+  const next = cloneTree(tree)
+  if (d.kind === 'folder') {
+    if ('into' in target || target.list !== null) return null
+    const from = rootIndex(next, 'folder', d.name)
+    if (from < 0) return null
+    const [it] = next.splice(from, 1)
+    next.splice(target.index > from ? target.index - 1 : target.index, 0, it!)   // removing `from` shifts later slots left
+    return next
+  }
+  const src = takeBoard(next, d.name)
+  if (!src) return null
+  if ('into' in target) {
+    const f = folderIn(next, target.into)
+    if (!f) return null
+    f.boards.push(d.name)
+    return next
+  }
+  const to = src.list === target.list && target.index > src.index ? target.index - 1 : target.index
+  if (target.list === null) { next.splice(Math.min(to, next.length), 0, { kind: 'board', name: d.name }); return next }
+  const f = folderIn(next, target.list)
+  if (!f) return null
+  f.boards.splice(Math.min(to, f.boards.length), 0, d.name)
+  return next
+}
+
+/** Move a board into a folder (at its end) or to the root at `atRoot` (default: the end). */
+export function moveBoard(tree: TreeItem[], board: string, folder: string | null, atRoot?: number): TreeItem[] | null {
+  const next = cloneTree(tree)
+  if (!takeBoard(next, board)) return null
+  if (folder === null) { next.splice(Math.min(atRoot ?? next.length, next.length), 0, { kind: 'board', name: board }); return next }
+  const f = folderIn(next, folder)
+  if (!f) return null
+  f.boards.push(board)
+  return next
+}
+
+/** A new folder at root `index`, holding `board` (pulled from wherever it sat) when given. */
+export function createFolder(tree: TreeItem[], name: string, index: number, board?: string, title?: string): TreeItem[] | null {
+  if (foldersIn(tree).includes(name)) return null
+  const next = cloneTree(tree)
+  const boards: string[] = []
+  if (board) { if (!takeBoard(next, board)) return null; boards.push(board) }
+  next.splice(Math.min(index, next.length), 0, { kind: 'folder', name, boards, ...(title ? { title } : {}) })
+  return next
+}
+
+/** Retitle a folder: what humans see (''= clear, back to the Title-Cased slug). The slug is
+ *  its identity - `folder:` on every member board, the registry key - and never changes here. */
+export function retitleFolder(tree: TreeItem[], name: string, title: string): TreeItem[] | null {
+  const next = cloneTree(tree)
+  const f = folderIn(next, name)
+  if (!f) return null
+  if (title) f.title = title; else delete f.title
+  return next
+}
+
+/** The slug a NEW folder gets from the title the human typed: `slugify(title)`, then `-2`,
+ *  `-3`, ... past a taken one; `fallback` (and `fallback-2`, ...) when nothing survives
+ *  slugifying ("🚀"). Slugs are minted once - a rename changes the title, never the slug. */
+export function slugFor(title: string, taken: string[], fallback = 'folder'): string {
+  const s = slugify(title)
+  if (s && !taken.includes(s)) return s
+  const base = s || fallback
+  if (!s && !taken.includes(base)) return base
+  for (let i = 2; ; i++) { const c = `${base.slice(0, NAME_MAX - 1 - String(i).length)}-${i}`; if (!taken.includes(c)) return c }
+}
+
+/** Folders organise, never own: deleting one puts its boards back at the root, in its slot, in order. */
+export function deleteFolder(tree: TreeItem[], name: string): TreeItem[] | null {
+  const next = cloneTree(tree)
+  const i = rootIndex(next, 'folder', name)
+  if (i < 0) return null
+  const f = next[i] as Folder
+  next.splice(i, 1, ...f.boards.map((b): TreeItem => ({ kind: 'board', name: b })))
+  return next
+}
+
+/** Where "Move to new folder" puts the folder: the board's own root slot, or right after the
+ *  folder it sits in. */
+export const newFolderSlot = (tree: TreeItem[], board: string): number => {
+  const parent = folderOf(tree, board)
+  return parent ? rootIndex(tree, 'folder', parent) + 1 : Math.max(0, rootIndex(tree, 'board', board))
+}

package/templates/AGENTS-embedded.md

@@ -91,7 +91,7 @@ Report where the request came from: chat requests get chat replies; only comment
 ## Frames
 - A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
 - It default-exports a React component. No imports from the tool are needed. Optional:
-  export const meta = { title: "...", viewport: "mobile" }   // literal values only
+  export const meta = { title: "...", viewport: "mobile", description: "..." }   // literal values only
   // viewport names come from design/config.ts (default: mobile, tablet, laptop, monitor;
   // tv available commented-out). Pick the one the screen is designed for - the human can
   // flip the whole board to any device (Devices menu; digit keys - 0 restores each
@@ -131,8 +131,24 @@ Report where the request came from: chat requests get chat replies; only comment
   setTimeout(() => r(orders), 800)) and let the frame render its skeleton while awaiting.
 
 ## Orientation
-- design/manifest.json lists every frame (id, file, scene, title) - read it before
-  exploring. `init` writes the first one; `marver dev` keeps it fresh.
+- design/manifest.json is the canvas with its purpose: the project (name, description),
+  every folder and board in sidebar order, every scene and frame - each with its
+  `description` when one was written, and its `title` when the human (or you) named it.
+  Read it before exploring; `marver dev` keeps it fresh. `npx marver boards` prints the
+  boards part as a tree.
+- **Names vs titles.** A board's file name, a folder's `name`, a scene's directory are
+  IDENTITIES: slugs you address, that publish.json, URLs and comment threads hold, and
+  that never move on a rename. `title` is what humans see - free text (casing,
+  punctuation, emoji) on the board JSON, the `_folders.json` entry, the brief's front
+  matter; frames have `meta.title`. When the human says "the Checkout A/B board", the
+  manifest maps that title to its slug. Rename a slug only when asked, as one refactor.
+- **Descriptions.** Every object takes one optional `description`: one sentence, what it
+  is for and its state when that is not obvious (≤ ~160 chars). Project: `description`
+  in design/config.ts. Board: `"description"` in its JSON. Folder: on its `_folders.json`
+  entry. Scene: the FIRST line of its `_brief.md`. Frame: `meta.description`. Write it
+  when you create the thing; keep it true when the state changes (retired, winning
+  direction, superseded); before a session ends, re-read the manifest and fix any
+  description your session made false. That is how the next session orients in one read.
 - Component galleries: create design/components/<name>/variants.tsx rendering each variant
   and each state (default / hover-styled / focus / disabled / loading) of one ui component.
 
@@ -159,8 +175,12 @@ edges; a variant-group name is one indivisible atom). **The default composition
 ONE horizontal band**: scenes side by side, frames flowing left to right; a second
 band only when you can say why the eye should move down, and then with generous
 vertical space. Without a recipe the shell stacks every scene as its own row - so
-every curated board carries one. BEFORE creating a board or publishing anything,
-read instructions/boards.md (the layout grammar, file format, publishing rules).
+every curated board carries one. Boards can sit in **folders** (one level): put
+`"folder": "<name>"` on a board file; `design/boards/_folders.json` names empty folders
+and ranks them - the human creates, renames, and drags folders in the sidebar too, so
+run `npx marver boards` (the tree as the files say it is) before you organise. BEFORE
+creating a board, organising boards, or publishing anything, read instructions/boards.md
+(the layout grammar, file format, folders and their moves, publishing rules).
 
 A round of feedback on a scene the human has already reviewed starts with a
 **version snapshot** (`design/scenes/<scene>-v<N>/` on the `archive` board) BEFORE

package/templates/AGENTS-studio.md

@@ -91,7 +91,7 @@ Report where the request came from: chat requests get chat replies; only comment
 ## Frames
 - A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
 - It default-exports a React component. No imports from the tool are needed. Optional:
-  export const meta = { title: "...", viewport: "mobile" }   // literal values only
+  export const meta = { title: "...", viewport: "mobile", description: "..." }   // literal values only
   // viewport names come from design/config.ts (default: mobile, tablet, laptop, monitor;
   // tv available commented-out). Pick the one the screen is designed for - the human can
   // flip the whole board to any device (Devices menu; digit keys - 0 restores each
@@ -130,8 +130,24 @@ Report where the request came from: chat requests get chat replies; only comment
   setTimeout(() => r(orders), 800)) and let the frame render its skeleton while awaiting.
 
 ## Orientation
-- design/manifest.json lists every frame (id, file, scene, title) - read it before
-  exploring. `init` writes the first one; `marver dev` keeps it fresh.
+- design/manifest.json is the canvas with its purpose: the project (name, description),
+  every folder and board in sidebar order, every scene and frame - each with its
+  `description` when one was written, and its `title` when the human (or you) named it.
+  Read it before exploring; `marver dev` keeps it fresh. `npx marver boards` prints the
+  boards part as a tree.
+- **Names vs titles.** A board's file name, a folder's `name`, a scene's directory are
+  IDENTITIES: slugs you address, that publish.json, URLs and comment threads hold, and
+  that never move on a rename. `title` is what humans see - free text (casing,
+  punctuation, emoji) on the board JSON, the `_folders.json` entry, the brief's front
+  matter; frames have `meta.title`. When the human says "the Checkout A/B board", the
+  manifest maps that title to its slug. Rename a slug only when asked, as one refactor.
+- **Descriptions.** Every object takes one optional `description`: one sentence, what it
+  is for and its state when that is not obvious (≤ ~160 chars). Project: `description`
+  in design/config.ts. Board: `"description"` in its JSON. Folder: on its `_folders.json`
+  entry. Scene: the FIRST line of its `_brief.md`. Frame: `meta.description`. Write it
+  when you create the thing; keep it true when the state changes (retired, winning
+  direction, superseded); before a session ends, re-read the manifest and fix any
+  description your session made false. That is how the next session orients in one read.
 - Component galleries: create design/components/<name>/variants.tsx rendering each variant
   and each state (default / hover-styled / focus / disabled / loading) of one ui component.
 
@@ -159,8 +175,12 @@ edges; a variant-group name is one indivisible atom). **The default composition
 ONE horizontal band**: scenes side by side, frames flowing left to right; a second
 band only when you can say why the eye should move down, and then with generous
 vertical space. Without a recipe the shell stacks every scene as its own row - so
-every curated board carries one. BEFORE creating a board or publishing anything,
-read instructions/boards.md (the layout grammar, file format, publishing rules).
+every curated board carries one. Boards can sit in **folders** (one level): put
+`"folder": "<name>"` on a board file; `design/boards/_folders.json` names empty folders
+and ranks them - the human creates, renames, and drags folders in the sidebar too, so
+run `npx marver boards` (the tree as the files say it is) before you organise. BEFORE
+creating a board, organising boards, or publishing anything, read instructions/boards.md
+(the layout grammar, file format, folders and their moves, publishing rules).
 
 A round of feedback on a scene the human has already reviewed starts with a
 **version snapshot** (`design/scenes/<scene>-v<N>/` on the `archive` board) BEFORE

package/templates/instructions/boards.md

@@ -10,9 +10,24 @@ viewport and lays it out:
 
 ```json
 { "version": 1, "name": "checkout-compare", "order": 1, "auto": false,
+  "title": "Checkout A/B",
+  "description": "Cart step, direction A vs B side by side - B is the current favourite",
   "nodes": [ { "frame": "checkout-a/cart" }, { "frame": "checkout-b/cart" } ] }
 ```
 
+- **The file name is the board's identity** - what you, `publish.json`, URLs and
+  comment threads address (`board: checkout-compare`). It is a slug
+  (`^[a-z0-9][a-z0-9-]*$`) and never moves on a rename.
+- `title` - what humans SEE: free text, any casing, punctuation, emoji ("MVP", "UI",
+  "Checkout (v2) 🛒"). Optional: without one the sidebar Title-Cases the slug
+  (`checkout-compare` → "Checkout Compare"), which is fine for most boards. Write a
+  title when the slug would read wrong (`mvp` → "Mvp") or when the human names it.
+  The human's Rename in the sidebar edits the title only; the manifest carries both, so
+  "the Checkout A/B board" resolves to `checkout-compare`.
+- `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 +38,9 @@ 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`), retitle one from its right-click menu (which
+  writes `title`), 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 +60,79 @@ 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, "title": "R&D", "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 `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
+  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.
+- **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
+  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.
+
+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 (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
+`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,29 @@ 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.
-Show it. Get the nod.
+**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).
+A scene's directory is its identity (every frame id starts with it); what humans SEE
+for it is `title` in the brief's YAML front matter - optional, free text - the sidebar
+Title-Cases the directory otherwise (`checkout` → "Checkout", but `mvp` → "Mvp"):
+
+```md
+---
+title: "Checkout (v2)"
+---
+# Checkout - the buyer's path from cart to receipt (v2, after the pricing pivot)
+```
+
+The human's Rename on a scene writes exactly that line; leave the block alone and
+never rename the directory for a title. Show the brief. 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