@marver-design/marver 0.20.0 → 0.22.0

package/dist/{plugin-y4Ch7o_A.mjs → plugin-8XntSCx_.mjs}

@@ -1,8 +1,9 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 import { a as ROUTE, i as PKG, r as NAME } from "./cli.mjs";
-import { a as listBoardFiles, c as BOARD_NAME, g as hash, h as validateWire, i as isRegularFile, l as FOLDERS_FILE, m as readTitle, n as checkBoardsDir, o as nodeExists, p as readDescription, s as readRegistry, t as boardFields } from "./boards-BmxcT3Lc.mjs";
+import { A as isRegularFile, B as folderMap, D as boardFields, F as BOARD_NAME, G as validateWire, I as FOLDERS_FILE, K as wireKids, L as buildTree, M as nodeExists, N as readRegistry, O as checkBoardsDir, P as withRegistryLock, T as AUTHOR_FIELDS, U as readDescription, W as readTitle, Y as HAS_STATUS, at as hash, et as readReason, it as settableStatuses, j as listBoardFiles, n as readContextFacts, nt as readType, rt as resolveType, t as annotateBoards, tt as readStatusWord } from "./board-status-CWGHIdo_.mjs";
 import { n as localProfile, t as isConnected } from "./profile-BjAPAJSb.mjs";
-import { c as loadConfig, i as setSceneTitle, n as isNoteFile, o as writeManifest, r as scanFrames, t as affectedFrameIds } from "./manifest-B01PSyDc.mjs";
+import { i as setSceneTitle, n as isNoteFile, o as writeManifest, r as scanFrames, t as affectedFrameIds } from "./manifest-BqBcMJcd.mjs";
+import { n as loadConfig } from "./config-DJxMRVD8.mjs";
 import { copyFileSync, existsSync, linkSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -128,11 +129,88 @@ function apiMiddleware(root, opts = {}) {
 				const de = dirError();
 				if (de) return json(res, 422, { error: de });
 				mkdirSync(boardsDir, { recursive: true });
-				return json(res, 200, listBoardFiles(boardsDir).boards.map((b) => ({
+				const files = listBoardFiles(boardsDir).boards;
+				const rows = files.map((b) => ({
 					name: b.name,
-					sha256: b.sha256,
 					...boardFields(b.json, validName)
-				})));
+				}));
+				const reg = readRegistry(boardsDir);
+				const regFolders = reg.state === "ok" ? reg.folders : [];
+				const tree = buildTree(rows, regFolders);
+				const fm = folderMap(tree);
+				const facts = readContextFacts(root);
+				const notes = annotateBoards(root, files, regFolders, (n) => fm.get(n) ?? null, facts);
+				const settable = settableStatuses(facts.present);
+				return json(res, 200, files.map((b, i) => {
+					const n = notes.get(b.name);
+					return {
+						...rows[i],
+						sha256: b.sha256,
+						...n ?? {},
+						...n?.status ? { settable } : {}
+					};
+				}));
+			}
+			if (path === "boards/status" && req.method === "POST") {
+				if (!ownerGated(req)) return json(res, 403, { error: "forbidden" });
+				const raw = await readBody(req);
+				if (raw == null) return json(res, 400, { error: "body too large or unreadable" });
+				let parsed;
+				try {
+					parsed = JSON.parse(raw);
+				} catch {
+					return json(res, 400, { error: "malformed JSON" });
+				}
+				if (!parsed || typeof parsed !== "object") return json(res, 400, { error: "expected an object" });
+				const { name, status: statusRaw, reason: reasonRaw, baseHash } = parsed;
+				if (!validName(name) || name === "all-scenes") return json(res, 400, { error: "invalid board name" });
+				if (baseHash !== void 0 && typeof baseHash !== "string") return json(res, 400, { error: "invalid baseHash" });
+				const status = statusRaw === null ? null : readStatusWord(statusRaw);
+				if (status === void 0) return json(res, 400, { error: "invalid status" });
+				const reason = readReason(reasonRaw);
+				if (status === "blocked" && !reason) return json(res, 400, { error: "a blocked board says why - give a reason" });
+				{
+					const de = dirError();
+					if (de) return json(res, 400, { error: de });
+				}
+				const file = boardPath(name);
+				if (!file) return json(res, 400, { error: "invalid board name" });
+				if (!existsSync(file)) return json(res, 404, { error: `board "${name}" does not exist` });
+				if (!notSymlink(file)) return json(res, 400, { error: "refusing to write a symlinked board file" });
+				const current = readFileSync(file, "utf8");
+				if (baseHash !== void 0 && baseHash !== hash(current)) return json(res, 409, {
+					error: "board changed on disk",
+					sha256: hash(current)
+				});
+				let obj;
+				try {
+					obj = JSON.parse(current);
+				} catch {
+					return json(res, 422, { error: `board "${name}" is not valid JSON - fix the file` });
+				}
+				if (!obj || typeof obj !== "object" || Array.isArray(obj)) return json(res, 422, { error: `board "${name}" is not a JSON object - fix the file` });
+				const reg = readRegistry(boardsDir);
+				const regFolders = reg.state === "ok" ? reg.folders : [];
+				const all = listBoardFiles(boardsDir).boards;
+				const fm = folderMap(buildTree(all.map((b) => ({
+					name: b.name,
+					...boardFields(b.json, validName)
+				})), regFolders));
+				const folder = regFolders.find((f) => f.name === fm.get(name));
+				const parent = folder?.parent ? regFolders.find((f) => f.name === folder.parent) : void 0;
+				const type = resolveType(obj.type, folder?.type, parent?.type);
+				if (!HAS_STATUS.includes(type)) return json(res, 422, { error: `a ${type} board carries no status - only feature and project boards do` });
+				if (status !== null && !settableStatuses(readContextFacts(root).present).includes(status)) return json(res, 422, { error: status === "done" ? "Done is never set by hand - it comes from context/shipped.md" : `with context/, ${status} is read from the evidence - a plan, a contract, the shipped record` });
+				if (status === null) delete obj.status;
+				else obj.status = status;
+				if (status === "blocked") obj.reason = reason;
+				else delete obj.reason;
+				const next = JSON.stringify(obj, null, 2) + "\n";
+				if (next !== current) atomicWrite(file, next);
+				return json(res, 200, {
+					name,
+					sha256: hash(next)
+				});
 			}
 			if (path === "folders" && req.method === "GET") {
 				const de = dirError();
@@ -259,96 +337,144 @@ function apiMiddleware(root, opts = {}) {
 					const de = dirError();
 					if (de) return json(res, 400, { error: de });
 				}
-				const reg = readRegistry(boardsDir);
-				if (reg.state === "malformed") return json(res, 422, { error: reg.error });
-				if (reg.sha256 !== b.folders) return json(res, 409, {
-					error: "folders changed on disk",
-					stale: [FOLDERS_FILE]
+				const reply = (status, body) => ({
+					status,
+					body
 				});
-				const unseen = listBoardFiles(boardsDir).boards.map((x) => x.name).filter((n) => !(n in b.boards));
-				if (unseen.length) return json(res, 409, {
-					error: "boards changed on disk",
-					stale: unseen
-				});
-				const plan = [];
-				const stale = [];
-				const consider = (name, order, folder) => {
-					const p = boardPath(name);
-					if (!p || !isRegularFile(p)) {
-						stale.push(name);
-						return null;
-					}
-					const content = readFileSync(p, "utf8");
-					if (b.boards[name] !== hash(content)) {
-						stale.push(name);
+				mkdirSync(boardsDir, { recursive: true });
+				const locked = withRegistryLock(boardsDir, 0, () => {
+					const reg = readRegistry(boardsDir);
+					if (reg.state === "malformed") return reply(422, { error: reg.error });
+					if (reg.state === "ok" && reg.folders.some((f) => f.parent) && parsed.protocol !== 2) return reply(422, { error: "this tab predates folders in folders - reload the canvas, then try again" });
+					if (reg.sha256 !== b.folders) return reply(409, {
+						error: "folders changed on disk",
+						stale: [FOLDERS_FILE]
+					});
+					const unseen = listBoardFiles(boardsDir).boards.map((x) => x.name).filter((n) => !(n in b.boards));
+					if (unseen.length) return reply(409, {
+						error: "boards changed on disk",
+						stale: unseen
+					});
+					const plan = [];
+					const stale = [];
+					const consider = (name, order, folder) => {
+						const p = boardPath(name);
+						if (!p || !isRegularFile(p)) {
+							stale.push(name);
+							return null;
+						}
+						const content = readFileSync(p, "utf8");
+						if (b.boards[name] !== hash(content)) {
+							stale.push(name);
+							return null;
+						}
+						let obj;
+						try {
+							obj = JSON.parse(content);
+						} catch {
+							return `board "${name}" is not valid JSON - fix the file`;
+						}
+						if (!obj || typeof obj !== "object" || Array.isArray(obj)) return `board "${name}" is not a JSON object - fix the file`;
+						plan.push({
+							name,
+							path: p,
+							obj,
+							order,
+							folder
+						});
 						return null;
-					}
-					let obj;
+					};
+					const onDisk = /* @__PURE__ */ new Map();
 					try {
-						obj = JSON.parse(content);
-					} catch {
-						return `board "${name}" is not valid JSON - fix the file`;
+						const raw = JSON.parse(readFileSync(join(boardsDir, FOLDERS_FILE), "utf8"));
+						if (Array.isArray(raw.folders)) {
+							for (const r of raw.folders) if (r && typeof r === "object" && typeof r.name === "string") onDisk.set(r.name, r);
+						}
+					} catch {}
+					const MANAGED = /* @__PURE__ */ new Set([
+						"name",
+						"order",
+						"parent",
+						"title",
+						"description",
+						"type"
+					]);
+					const folders = [];
+					const walk = (list, parent) => {
+						for (const [i, it] of list.entries()) {
+							if (typeof it === "string") {
+								const e = consider(it, i, parent);
+								if (e) return e;
+								continue;
+							}
+							const title = readTitle(it.title), description = readDescription(it.description);
+							const disk = onDisk.get(it.folder);
+							const type = readType(it.type) ?? readType(disk?.type);
+							const kept = disk ? Object.fromEntries(Object.entries(disk).filter(([k]) => !MANAGED.has(k))) : {};
+							folders.push({
+								...kept,
+								name: it.folder,
+								order: i,
+								...parent ? { parent } : {},
+								...title ? { title } : {},
+								...description ? { description } : {},
+								...type ? { type } : {}
+							});
+							const e = walk(wireKids(it), it.folder);
+							if (e) return e;
+						}
+						return null;
+					};
+					{
+						const e = walk(tree, null);
+						if (e) return reply(422, { error: e });
 					}
-					if (!obj || typeof obj !== "object" || Array.isArray(obj)) return `board "${name}" is not a JSON object - fix the file`;
-					plan.push({
-						name,
-						path: p,
-						obj,
-						order,
-						folder
+					if (stale.length) return reply(409, {
+						error: "boards changed on disk",
+						stale
 					});
-					return null;
-				};
-				const folders = [];
-				for (const [i, it] of tree.entries()) {
-					if (typeof it === "string") {
-						const e = consider(it, i, null);
-						if (e) return json(res, 422, { error: e });
-						continue;
+					const sha256 = {};
+					for (const w of plan) {
+						if (w.obj.order === w.order && (w.folder ? w.obj.folder === w.folder : w.obj.folder === void 0)) continue;
+						if (hash(readFileSync(w.path, "utf8")) !== b.boards[w.name]) return reply(409, {
+							error: "boards changed on disk",
+							stale: [w.name]
+						});
+						w.obj.order = w.order;
+						if (w.folder) w.obj.folder = w.folder;
+						else delete w.obj.folder;
+						const next = JSON.stringify(w.obj, null, 2) + "\n";
+						atomicWrite(w.path, next);
+						sha256[w.name] = hash(next);
 					}
-					const title = readTitle(it.title), description = readDescription(it.description);
-					folders.push({
-						name: it.folder,
-						order: i,
-						...title ? { title } : {},
-						...description ? { description } : {}
+					mkdirSync(boardsDir, { recursive: true });
+					if ((nodeExists(foldersPath) ? hash(readFileSync(foldersPath, "utf8")) : null) !== b.folders) return reply(409, {
+						error: "folders changed on disk",
+						stale: [FOLDERS_FILE]
+					});
+					let foldersSha = null;
+					if (folders.length) {
+						const version = folders.some((f) => f.parent) ? 2 : 1;
+						const next = JSON.stringify({
+							version,
+							folders
+						}, null, 2) + "\n";
+						atomicWrite(foldersPath, next);
+						foldersSha = hash(next);
+					} else rmSync(foldersPath, { force: true });
+					return reply(200, {
+						ok: true,
+						sha256: {
+							boards: sha256,
+							folders: foldersSha
+						}
 					});
-					for (const [j, kid] of it.boards.entries()) {
-						const e = consider(kid, j, it.folder);
-						if (e) return json(res, 422, { error: e });
-					}
-				}
-				if (stale.length) return json(res, 409, {
-					error: "boards changed on disk",
-					stale
 				});
-				const sha256 = {};
-				for (const w of plan) {
-					if (w.obj.order === w.order && (w.folder ? w.obj.folder === w.folder : w.obj.folder === void 0)) continue;
-					w.obj.order = w.order;
-					if (w.folder) w.obj.folder = w.folder;
-					else delete w.obj.folder;
-					const next = JSON.stringify(w.obj, null, 2) + "\n";
-					atomicWrite(w.path, next);
-					sha256[w.name] = hash(next);
-				}
-				mkdirSync(boardsDir, { recursive: true });
-				let foldersSha = null;
-				if (folders.length) {
-					const next = JSON.stringify({
-						version: 1,
-						folders
-					}, null, 2) + "\n";
-					atomicWrite(foldersPath, next);
-					foldersSha = hash(next);
-				} else rmSync(foldersPath, { force: true });
-				return json(res, 200, {
-					ok: true,
-					sha256: {
-						boards: sha256,
-						folders: foldersSha
-					}
+				if (!locked) return json(res, 409, {
+					error: "folders changed on disk",
+					stale: [FOLDERS_FILE]
 				});
+				return json(res, locked.status, locked.body);
 			}
 			const boardMatch = /^boards\/([^/]+)$/.exec(path);
 			if (boardMatch) {
@@ -395,10 +521,8 @@ function apiMiddleware(root, opts = {}) {
 					const incoming = body.board;
 					if (incoming && typeof incoming === "object" && current) try {
 						const disk = JSON.parse(current);
-						if (incoming.order === void 0 && typeof disk.order === "number" && Number.isFinite(disk.order)) incoming.order = disk.order;
-						if (incoming.folder === void 0 && validName(disk.folder)) incoming.folder = disk.folder;
-						if (incoming.title === void 0 && readTitle(disk.title)) incoming.title = disk.title;
-						if (incoming.description === void 0 && readDescription(disk.description)) incoming.description = disk.description;
+						const valid = boardFields(disk, validName);
+						for (const k of AUTHOR_FIELDS) if (incoming[k] === void 0 && valid[k] !== void 0) incoming[k] = disk[k];
 					} catch {}
 					const next2 = JSON.stringify(body.board, null, 2) + "\n";
 					atomicWrite(p, next2);
@@ -422,7 +546,7 @@ function apiMiddleware(root, opts = {}) {
 				};
 				const asPng = url.searchParams.get("format") === "png";
 				const origin = opts.origin?.() ?? `http://${req.headers.host ?? "localhost"}`;
-				const { shootFrame } = await import("./shot-iw3SEcpn.mjs");
+				const { shootFrame } = await import("./shot-C22Ues04.mjs");
 				const r = await shootFrame({
 					root,
 					viewports: opts.viewports ?? {},
@@ -472,7 +596,7 @@ function apiMiddleware(root, opts = {}) {
 				if (typeof theme !== "string" || !/^[a-z0-9-]+$/i.test(theme)) return json(res, 400, { error: "invalid theme" });
 				const scale = body.scale === void 0 ? void 0 : body.scale;
 				if (scale !== void 0 && !(Number.isInteger(scale) && scale >= 1 && scale <= 4)) return json(res, 400, { error: "invalid scale" });
-				const { resolveFrames, shootBatch } = await import("./shot-iw3SEcpn.mjs");
+				const { resolveFrames, shootBatch } = await import("./shot-C22Ues04.mjs");
 				const sel = resolveFrames(root, body);
 				if (!sel.ok) return json(res, sel.status, { error: sel.error });
 				const origin = opts.origin?.() ?? `http://${req.headers.host ?? "localhost"}`;
@@ -500,7 +624,7 @@ function apiMiddleware(root, opts = {}) {
 					return json(res, 400, { error: "malformed JSON" });
 				}
 				if (!body || typeof body !== "object" || !Array.isArray(body.asks) || !body.asks.length || body.asks.length > 200) return json(res, 400, { error: "asks must list 1-200 frames" });
-				const { bakeBatch, ASK_MAX } = await import("./bake-tAb0D6Rc.mjs");
+				const { bakeBatch, ASK_MAX } = await import("./bake-BSX4XR_U.mjs");
 				let manifest = {};
 				try {
 					manifest = JSON.parse(readFileSync(join(root, "design", "manifest.json"), "utf8"));
@@ -544,8 +668,8 @@ function apiMiddleware(root, opts = {}) {
 			if (path === "poster" && req.method === "GET") {
 				if (!ownerGated(req)) return json(res, 403, { error: "forbidden" });
 				const src = url.searchParams.get("src") ?? "";
-				const { ensurePoster, isLocalClip } = await import("./poster-FCv_nXyP.mjs");
-				const { isLocalAssetRef } = await import("./build-DwpNPl6Z.mjs");
+				const { ensurePoster, isLocalClip } = await import("./poster-DRZDszTI.mjs");
+				const { isLocalAssetRef } = await import("./build-Dd2Qm3OG.mjs");
 				if (!isLocalAssetRef(src) || !isLocalClip(src)) return json(res, 400, { error: "src must be a clip under design/assets/" });
 				const r = await ensurePoster(join(root, "design", "assets"), src);
 				if (!r.ok) return json(res, r.error.includes("does not exist") ? 404 : 503, { error: r.error });
@@ -1027,7 +1151,7 @@ function marverPlugin(ctx) {
 			};
 			const prune = () => setTimeout(async () => {
 				try {
-					(await import("./bake-tAb0D6Rc.mjs")).pruneBakes(root, bakeGen);
+					(await import("./bake-BSX4XR_U.mjs")).pruneBakes(root, bakeGen);
 				} catch {}
 			}, 500);
 			prune();
@@ -1046,6 +1170,19 @@ function marverPlugin(ctx) {
 					rescanTheme();
 				}
 			});
+			const contextDir = join(root, "context") + sep;
+			let statusTimer;
+			const restatus = (f) => {
+				if (!f.startsWith(contextDir) && !(inScope(f) && f.endsWith("_brief.md"))) return;
+				clearTimeout(statusTimer);
+				statusTimer = setTimeout(() => {
+					server.ws.send("sh:boards", {});
+					regen();
+				}, 150);
+			};
+			server.watcher.on("add", restatus);
+			server.watcher.on("unlink", restatus);
+			server.watcher.on("change", restatus);
 			server.watcher.on("change", (f) => inScope(f) && (/\.(tsx|jsx)$/.test(f) || f.endsWith("_brief.md") || isNoteFile(f)) && regen());
 			const configFile = join(root, "design", "config.ts");
 			server.watcher.on("change", (f) => {
@@ -1166,7 +1303,7 @@ function marverPlugin(ctx) {
 								});
 								return;
 							}
-							const { shootFrame, shootBatch, resolveFrames } = await import("./shot-iw3SEcpn.mjs");
+							const { shootFrame, shootBatch, resolveFrames } = await import("./shot-C22Ues04.mjs");
 							if (ways[0] === "frame") {
 								if (typeof spec.frame !== "string") {
 									write({

package/dist/{poster-FCv_nXyP.mjs → poster-DRZDszTI.mjs}

@@ -1,4 +1,4 @@
-import { capture, t as findChrome } from "./shot-iw3SEcpn.mjs";
+import { capture, t as findChrome } from "./shot-C22Ues04.mjs";
 import { constants, copyFileSync, existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { pathToFileURL } from "node:url";

package/dist/{publish-bakes-XH6Bac58.mjs → publish-bakes-CCWRV9iX.mjs}

@@ -1,6 +1,6 @@
 import { o as slideSize } from "./cli.mjs";
-import { planShot, t as findChrome } from "./shot-iw3SEcpn.mjs";
-import { ASK_MAX, bakeBatch } from "./bake-tAb0D6Rc.mjs";
+import { planShot, t as findChrome } from "./shot-C22Ues04.mjs";
+import { ASK_MAX, bakeBatch } from "./bake-BSX4XR_U.mjs";
 import { MIME } from "./serve-z5qtj_wJ.mjs";
 import { copyFileSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { extname, isAbsolute, join, relative, resolve } from "node:path";

package/dist/{shot-iw3SEcpn.mjs → shot-C22Ues04.mjs}

@@ -337,8 +337,8 @@ async function shootFrame(opts) {
 	};
 	const plan = planShot(frame, viewports, size);
 	if (frame.kind !== "html") try {
-		const { scanAssetRefs } = await import("./build-DwpNPl6Z.mjs");
-		const { ensurePoster } = await import("./poster-FCv_nXyP.mjs");
+		const { scanAssetRefs } = await import("./build-Dd2Qm3OG.mjs");
+		const { ensurePoster } = await import("./poster-DRZDszTI.mjs");
 		const refs = scanAssetRefs(readFileSync(join(root, frame.file), "utf8"), frame.file);
 		for (const r of refs) if (r.endsWith(".poster.png")) await ensurePoster(join(root, "design", "assets"), r.slice(0, -11));
 	} catch {}

package/docs/boards-and-folders.md

@@ -0,0 +1,161 @@
+# Boards and folders
+
+A board is a saved canvas - a set of frames, arranged. Boards sit at the top of the sidebar, and
+folders keep them tidy: a folder holds boards and folders, a folder inside a folder - a
+**sub-folder** - holds boards. Two levels, so a board sits at the root, in a folder, or in a
+sub-folder.
+
+```
+Start here
+Features
+  Shipper            <- a sub-folder
+    New load
+    Orders
+  Phone
+    Pickup inspection
+  Carrier office     <- a board, straight in Features
+Context
+  Meetings
+Archive
+```
+
+Everything below works the same way at both levels, and the same from the sidebar as from the files
+- so a person arranging boards by hand and an agent arranging them by writing files always agree.
+
+## In the sidebar
+
+- **New folder** - right-click the Boards header, or its `+`. Name it inline: what you type is its
+  title, any casing, punctuation or emoji.
+- **New folder inside** - right-click a top-level folder: a sub-folder, at its end.
+- **Drag** a board into any folder or sub-folder (drop it on the header), or between any two rows -
+  the blue seam shows exactly where a release lands, indented with the level it lands in. Drag a
+  folder among the boards; a folder with no sub-folders can also drop into a top-level folder and
+  become one.
+- **Move to new folder** on a board makes a folder at the board's own level, with the board inside:
+  in its slot at the root, a sub-folder in its slot when it sits in a folder, and right after its
+  sub-folder when it sits in one (a sub-folder holds no folders).
+- **Move to top level** - on a board in a folder, or on a sub-folder.
+- **Rename** changes the title. **Delete folder** never deletes a board: what the folder held moves
+  up one level, into its place.
+
+At the bottom of a folder, one gap belongs to several levels: after the last board of a sub-folder
+you can drop into the sub-folder, after it in its folder, or after the folder at the root. Where you
+hold the pointer decides - over the row above, its indent picks the level; over the row below, the
+seam takes that row's level.
+
+## In the files
+
+Two files carry it, and they are the truth.
+
+**A board names its folder** - the one it sits in directly, at either level - next to its rank:
+
+```json
+{ "version": 1, "name": "new-load", "folder": "shipper", "order": 0, "nodes": [] }
+```
+
+`order` ranks the board among its siblings. At every level the boards and folders there share one
+sequence: the root's boards and folders, a folder's boards and sub-folders, a sub-folder's boards.
+
+**`design/boards/_folders.json` lists the folders**, ranks them, titles and describes them - and
+nests a sub-folder with `parent`:
+
+```json
+{ "version": 2, "folders": [
+  { "name": "features", "order": 1, "title": "Features", "description": "One board per capability, by surface" },
+  { "name": "shipper", "parent": "features", "order": 0, "title": "Shipper" },
+  { "name": "context", "order": 2 } ] }
+```
+
+- A folder's `name` is its slug - what boards point at with `folder`, unique across both levels. Its
+  `title` is what people see; renaming in the sidebar changes the title and never the slug.
+- `parent` names a top-level folder. A sub-folder never holds a folder.
+- The file says `"version": 2` while any folder has a parent, and `1` when none does.
+- A folder a board names but the registry lacks is still real - it shows at the top level. To nest
+  it, register it with its `parent`.
+- A registry that breaks these rules is an error the canvas shows, never read as empty.
+
+`npx marver boards` prints the tree as the files say it is - every folder and sub-folder, every board
+with its rank, the landing board - and `--json` gives the same tree. The landing board is the first
+board in that reading order, down through folders.
+
+## Descriptions
+
+Every folder, board, scene and frame takes one `description`: a sentence for agents - what it is
+for, and its state when that is not obvious. A folder's sits on its entry in `_folders.json`. They
+all land in `design/manifest.json`, the file an agent reads first, so a new session knows what each
+folder is for before it files a single board.
+
+## Types
+
+Every board wears an icon for what it is for, the same on every canvas:
+
+| Type | For |
+|---|---|
+| `start` | the way in: the index, the shipped record, the timeline |
+| `feature` | one capability: its spec, lo-fi and hi-fi |
+| `surface` | the whole product to walk, from frames on feature boards |
+| `project` | a deliverable or a question |
+| `feedback` | one frame per theme |
+| `context` | what came in from outside: meetings, threads, competitors |
+| `deck` | slides |
+| `archive` | snapshots and retired work |
+
+A board states `"type"` in its JSON, or wears the type of the folder it sits in - `"type"` on the
+folder's entry in `_folders.json` - or of that folder's parent; else it is plain. Moving a board
+changes an inherited type, never one the board states. The type never decides how a board publishes,
+but `marver build` suggests a publish type from it - `slides` for a deck, `refs` for a context board,
+`doc` for a project - and the publish row decides.
+
+## Status
+
+Feature and project boards also wear a status, read from the project's `context/` - Backlog, To do,
+In progress (filling by phase), Done, Done reported, Unknown - or decided on the board itself:
+`"status": "archived"`, `"paused"`, or `"blocked"` with a `"reason"`. **Done is never set by hand.**
+The tooltip says what decided it. [Context](context.md) has the rules.
+
+**Set it from the sidebar:** right-click a feature or project board, **Change status…**. The picker
+shows what the evidence says and offers only what a person decides - Blocked (it asks why), Paused,
+Archived, and **Back to the evidence** to undo a decision; without `context/`, Backlog, To do and In
+progress as well. Type to filter, or press a number. It writes `status` and `reason` into the board
+file and nothing else.
+
+One rule draws them: a status still open is an outline in its colour - grey, yellow filling by phase,
+red for blocked - and a settled one is filled: Done a green disc, Archived a solid brown box. Done,
+reported is the green outline - a written claim, not yet confirmed.
+
+## Starting points
+
+- `npx marver init --kind product|knowledge` - on a fresh canvas, the typed folders every canvas
+  shares: Start here, Features and Surfaces (a product) or Projects (knowledge work), Feedback,
+  Context, Archive. Without the flag a fresh canvas gets product folders when an app is detected,
+  knowledge otherwise, and says which. On an existing canvas only `--kind` adds them, and only the
+  missing ones - init never renames or moves a folder.
+- `npx marver folders add decks` - one more typed folder later: `start`, `features`, `surfaces`,
+  `projects`, `feedback`, `context`, `decks`, `archive`.
+- `npx marver boards new <name> --folder features` - a board in its type's starting layout: a
+  feature's three phase scenes as three bands (spec, lo-fi, hi-fi), a start board rendering
+  `context/INDEX.md` and `context/shipped.md`, a deck on its title slide. `--type` overrides the
+  folder's; `--title`, `--description`, `--capability` fill the rest.
+
+## Agents
+
+Agents make the same moves by editing those two files (`npx marver boards` prints the tree with each
+board's type and status); `instructions/boards.md` in your project
+teaches each one - creating a sub-folder, moving a folder in or out, renaming a slug (members'
+`folder` and sub-folders' `parent` move with it), deleting (contents up one level). The sidebar
+refuses a write that would overwrite an edit it has not seen, so an agent's file write and a
+person's drag never silently erase each other.
+
+## Publishing
+
+A published canvas shows the folders of the published boards only - a sub-folder's parent included,
+since the tree needs it. A folder with nothing published at any depth never reaches the bundle, so
+its name and description stay private. Board types ship; statuses do not - a published board loses its
+`status`, `reason` and `capability`, and shows a status only where its publish row says
+`"showStatus": true` and the evidence behind it is `publishable` - never a blocked reason.
+
+## Mixed versions
+
+Marver 0.20 and earlier read one level of folders. They 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.