@marver-design/marver 0.20.0 → 0.22.0

package/dist/boards-BTGNPVMx.mjs

@@ -0,0 +1,187 @@
+import { r as NAME } from "./cli.mjs";
+import { $ as readCapability, B as folderMap, D as boardFields, E as addFolders, H as isBoardName, J as FOLDER_MODULES, L as buildTree, N as readRegistry, O as checkBoardsDir, Q as knownType, R as flatten, V as humanize, a as STATUS_LABEL, j as listBoardFiles, k as checkRealDirs, q as BOARD_TYPES, r as PHASE_LABEL, rt as resolveType, t as annotateBoards } from "./board-status-CWGHIdo_.mjs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/cli/boards.ts
+/**
+* `marver boards` - the sidebar as the agent sees it: every folder and board in reading
+* order - sub-folders indented under their parent - from the files (no dev server needed). One
+* call answers "what folders exist, what is in them, what ranks where" before the agent writes `folder` on a board or edits
+* `design/boards/_folders.json`. `--json` gives the tree shape the shell uses.
+*/
+function boardsCommand(root, opts) {
+	const dir = join(root, "design", "boards");
+	const de = checkBoardsDir(root, dir);
+	if (de) throw new Error(de);
+	const { boards, skipped } = listBoardFiles(dir);
+	const reg = readRegistry(dir);
+	if (reg.state === "malformed") throw new Error(reg.error);
+	const rows = boards.map((b) => ({
+		name: b.name,
+		...boardFields(b.json, isBoardName)
+	}));
+	const tree = buildTree(rows, reg.folders);
+	const hasAll = boards.some((b) => b.name === "all-scenes");
+	const fm = folderMap(tree);
+	const notes = annotateBoards(root, boards.filter((b) => b.name !== "all-scenes"), reg.folders, (n) => fm.get(n) ?? null);
+	if (opts.json) {
+		const out = rows.filter((r) => r.name !== "all-scenes").map((r) => ({
+			...r,
+			...notes.get(r.name) ?? {}
+		}));
+		console.log(JSON.stringify({
+			tree,
+			boards: out,
+			landing: flatten(tree)[0] ?? (hasAll ? "all-scenes" : null),
+			registry: reg.state === "ok" ? "design/boards/_folders.json" : null
+		}, null, 2));
+		return;
+	}
+	if (!tree.length && !hasAll) {
+		console.log("no boards yet - design/boards/ is empty");
+		return;
+	}
+	const order = (n) => {
+		const o = rows.find((r) => r.name === n)?.order;
+		return o === void 0 ? "" : `  order ${o}`;
+	};
+	const title = (t) => t ? `  "${t}"` : "";
+	const desc = (d) => d ? `  - ${d}` : "";
+	const kind = (n) => {
+		const a = notes.get(n);
+		if (!a) return "";
+		const st = a.status ? ` · ${STATUS_LABEL[a.status.status]}${a.status.fill ? ` (${PHASE_LABEL[a.status.fill]})` : ""}${a.status.reason ? `: ${a.status.reason}` : ""}` : "";
+		return a.type === "plain" && !st ? "" : `  [${a.type}${st}]`;
+	};
+	const boardLine = (n) => {
+		const r = rows.find((x) => x.name === n);
+		return `${n}${title(r?.title)}${kind(n)}${order(n)}${desc(r?.description)}`;
+	};
+	const count = (f) => {
+		const boards = f.items.filter((k) => k.kind === "board").length, subs = f.items.length - boards;
+		return `${boards} board${boards === 1 ? "" : "s"}${subs ? `, ${subs} folder${subs === 1 ? "" : "s"}` : ""}`;
+	};
+	const print = (items, pad, parent) => {
+		for (const it of items) {
+			if (it.kind === "board") {
+				console.log(`${pad}${boardLine(it.name)}`);
+				continue;
+			}
+			const where = parent ? `sub-folder of ${parent}` : "folder";
+			const implied = reg.folders.some((f) => f.name === it.name) ? "" : ", implied by its boards - not in _folders.json";
+			console.log(`${pad}${it.name}/${title(it.title)}  (${where}${it.type ? `, ${it.type}` : ""}, ${count(it)}${implied})${desc(it.description)}`);
+			print(it.items, `${pad}  `, it.name);
+			if (!it.items.length) console.log(`${pad}  (empty)`);
+		}
+	};
+	print(tree, "", null);
+	if (hasAll) console.log("all-scenes  (auto, always last)");
+	const landing = flatten(tree)[0];
+	if (landing) console.log(`\nlanding board: ${landing}`);
+	console.log(`registry: ${reg.state === "ok" ? "design/boards/_folders.json" : "none (no empty or ranked folders yet)"}`);
+	if (skipped.length) console.log(`skipped (not regular files): ${skipped.join(", ")}`);
+}
+/** `marver boards new <name>` - a board in its type's starting layout (spec 20): a feature's three
+*  phase scenes (spec, lo-fi, hi-fi) as three bands, a start board rendering context/INDEX.md and
+*  context/shipped.md, a deck's title slide. The type is `--type`, else the folder's. Never
+*  overwrites a board, a scene brief or a frame that exists. */
+function boardsNew(root, name, opts) {
+	if (!isBoardName(name) || name === "all-scenes") throw new Error(`"${name}" is not a board name - lowercase letters, numbers and dashes`);
+	const dir = join(root, "design", "boards");
+	const de = checkBoardsDir(root, dir);
+	if (de) throw new Error(de);
+	const file = join(dir, `${name}.json`);
+	if (existsSync(file)) throw new Error(`design/boards/${name}.json exists - a board is never overwritten`);
+	if (opts.type !== void 0 && !knownType(opts.type)) throw new Error(`--type ${opts.type}: use ${BOARD_TYPES.join(", ")}`);
+	if (opts.folder !== void 0 && !isBoardName(opts.folder)) throw new Error(`--folder ${opts.folder} is not a folder name`);
+	if (opts.capability !== void 0 && !readCapability(opts.capability)) throw new Error(`--capability ${opts.capability} is not a capability slug`);
+	const reg = readRegistry(dir);
+	if (reg.state === "malformed") throw new Error(reg.error);
+	const folder = opts.folder ? reg.state === "ok" ? reg.folders.find((f) => f.name === opts.folder) : void 0 : void 0;
+	const parent = folder?.parent && reg.state === "ok" ? reg.folders.find((f) => f.name === folder.parent) : void 0;
+	const type = resolveType(opts.type, folder?.type, parent?.type);
+	const label = opts.title ?? humanize(name);
+	const created = [];
+	const put = (rel, body) => {
+		const f = join(root, rel);
+		const scene = rel.split("/")[2];
+		const bad = checkRealDirs(root, [
+			[join(root, "design"), "design"],
+			[join(root, "design", "scenes"), "design/scenes"],
+			[join(root, "design", "scenes", scene), `design/scenes/${scene}`]
+		]);
+		if (bad) throw new Error(bad);
+		mkdirSync(join(f, ".."), { recursive: true });
+		try {
+			writeFileSync(f, body, { flag: "wx" });
+			created.push(rel);
+		} catch (e) {
+			if (e.code !== "EEXIST") throw e;
+		}
+	};
+	const brief = (scene, title, body, phase) => put(`design/scenes/${scene}/_brief.md`, `---\ntitle: ${title}\n${phase ? `phase: ${phase}\n` : ""}---\n${body}\n`);
+	let nodes = [];
+	let layout;
+	if (type === "feature") {
+		const cap = opts.capability ?? name;
+		const [specs, lofi, hifi] = [
+			`${name}-specs`,
+			`${name}-lofi`,
+			name
+		];
+		brief(specs, `${label} - spec`, `${label}: what it does, for whom, and its limits - the thinking before the screens. Its contract is context/product/${cap}.md once accepted.`, "spec");
+		brief(lofi, `${label} - lo-fi`, `${label} in throwaway wireframes: structure and copy, no styling.`, "lofi");
+		brief(hifi, label, `${label} in hi-fi, from the product's real components.`, "hifi");
+		layout = { rows: [
+			[specs],
+			{ space: 3 },
+			[lofi],
+			{ space: 4 },
+			[hifi]
+		] };
+	} else if (type === "start") {
+		const strip = "(md: string) => md.replace(/^<!--[^\\n]*-->\\n/, '').replace(/^---\\n[\\s\\S]*?\\n---\\n/, '')";
+		const frame = (file, title, src, desc) => put(`design/scenes/${name}/${file}.tsx`, `// Renders ${src} - the file is the truth; this frame only shows it.\nimport { Doc, Md } from '@marver-design/marver/content'\nimport text from '../../../${src}?raw'\n\nexport const meta = { title: '${title}', intent: 'spec', description: '${desc}' }\n\nconst body = ${strip}\n\nexport default () => (\n  <Doc>\n    <Md>{body(text)}</Md>\n  </Doc>\n)\n`);
+		brief(name, label, "The way in: the index and the shipped record, rendered from context/.");
+		frame("index", "The index", "context/INDEX.md", "context/INDEX.md, rendered - where every question is answered");
+		frame("shipped", "Shipped", "context/shipped.md", "context/shipped.md, rendered - what runs where, with its evidence");
+		nodes = [{ frame: `${name}/index` }, { frame: `${name}/shipped` }];
+		layout = { rows: [[name]] };
+	} else if (type === "deck") {
+		brief(name, label, `${label}: the deck. Read design/instructions/slides.md before the first slide.`);
+		put(`design/scenes/${name}/01-title.tsx`, `export const meta = { title: '${label.replace(/'/g, "\\'")}', slide: true }\n\nexport default function Frame() {\n  return (\n    <main style={{ minHeight: '100vh', display: 'grid', placeItems: 'center', padding: 96 }}>\n      <h1 style={{ fontSize: 72, margin: 0 }}>${label.replace(/[<>{}]/g, "")}</h1>\n    </main>\n  )\n}\n`);
+		nodes = [{ frame: `${name}/01-title` }];
+		layout = { rows: [[name]] };
+	}
+	const board = {
+		version: 1,
+		name,
+		auto: false,
+		...opts.type ? { type: opts.type } : {},
+		...opts.folder ? { folder: opts.folder } : {},
+		...opts.title ? { title: opts.title } : {},
+		...opts.description ? { description: opts.description } : {},
+		...opts.capability ? { capability: opts.capability } : {},
+		nodes,
+		...layout ? { layout } : {}
+	};
+	mkdirSync(dir, { recursive: true });
+	try {
+		writeFileSync(file, JSON.stringify(board, null, 2) + "\n", { flag: "wx" });
+	} catch (e) {
+		if (e.code === "EEXIST") throw new Error(`design/boards/${name}.json exists - a board is never overwritten`);
+		throw e;
+	}
+	created.unshift(`design/boards/${name}.json (${type}${opts.type ? "" : type === "plain" ? "" : `, from ${opts.folder}`})`);
+	return created;
+}
+/** `marver folders add <module...>` - the shared sidebar's typed folders (spec 20): start, features,
+*  surfaces, projects, feedback, context, decks, archive. Appended; never renames or moves one. */
+function foldersAdd(root, modules) {
+	const unknown = modules.filter((m) => !FOLDER_MODULES[m]);
+	if (unknown.length) throw new Error(`unknown folder module: ${unknown.join(", ")} - use ${Object.keys(FOLDER_MODULES).join(", ")}`);
+	if (!modules.length) throw new Error(`name a module: ${Object.keys(FOLDER_MODULES).join(", ")} (e.g. \`npx ${NAME} folders add decks\`)`);
+	return addFolders(root, modules.map((m) => FOLDER_MODULES[m]));
+}
+//#endregion
+export { boardsCommand, boardsNew, foldersAdd };

package/dist/{build-DwpNPl6Z.mjs → build-Dd2Qm3OG.mjs}

@@ -1,7 +1,8 @@
 import { a as ROUTE, r as NAME } from "./cli.mjs";
-import { a as listBoardFiles, d as flatten, f as isBoardName, n as checkBoardsDir, s as readRegistry, t as boardFields, u as buildTree } from "./boards-BmxcT3Lc.mjs";
-import { c as loadConfig, r as scanFrames, u as detectHost } from "./manifest-B01PSyDc.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-y4Ch7o_A.mjs";
+import { D as boardFields, H as isBoardName, L as buildTree, N as readRegistry, O as checkBoardsDir, R as flatten, Z as PROPOSED_PUBLISH, i as PUBLISHABLE, j as listBoardFiles, o as publishableStatus } from "./board-status-CWGHIdo_.mjs";
+import { r as scanFrames } from "./manifest-BqBcMJcd.mjs";
+import { i as detectHost, n as loadConfig } from "./config-DJxMRVD8.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-8XntSCx_.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -258,7 +259,7 @@ function resolvePolicy(root, allBoards, boardsFlag, allBoardsFlag) {
 		structure: true,
 		source: false
 	};
-	const row = (max) => ({
+	const row = (max, _n) => ({
 		max,
 		type: "mix"
 	});
@@ -268,12 +269,12 @@ function resolvePolicy(root, allBoards, boardsFlag, allBoardsFlag) {
 		const missing = names.filter((n) => !known(n));
 		if (missing.length) throw new Error(`--boards names not found in design/boards/: ${missing.join(", ")}`);
 		return {
-			boards: Object.fromEntries(names.map((n) => [n, row("comment")])),
+			boards: Object.fromEntries(names.map((n) => [n, row("comment", n)])),
 			reveal
 		};
 	}
 	if (allBoardsFlag) return {
-		boards: Object.fromEntries(["all-scenes", ...Object.keys(allBoards).filter((n) => n !== "all-scenes")].map((n) => [n, row("comment")])),
+		boards: Object.fromEntries(["all-scenes", ...Object.keys(allBoards).filter((n) => n !== "all-scenes")].map((n) => [n, row("comment", n)])),
 		reveal
 	};
 	const policyFile = join(root, "design", "publish.json");
@@ -290,13 +291,14 @@ function resolvePolicy(root, allBoards, boardsFlag, allBoardsFlag) {
 	for (const [n, level] of entries) {
 		if (!known(n)) throw new Error(`design/publish.json names an unknown board: ${n}`);
 		if (level === "read" || level === "comment") {
-			out[n] = row(level);
+			out[n] = row(level, n);
 			continue;
 		}
 		if (typeof level !== "object" || level === null) throw new Error(`design/publish.json: board "${n}" has level "${level}" - use "read" or "comment", or a v2 object`);
 		const p = level;
 		if (p.max !== "read" && p.max !== "comment") throw new Error(`design/publish.json: board "${n}" needs "max": "read" | "comment"`);
 		const type = p.type ?? "mix";
+		if (p.showStatus !== void 0 && typeof p.showStatus !== "boolean") throw new Error(`design/publish.json: board "${n}" has showStatus "${p.showStatus}" - use true or false`);
 		if (!ARTIFACT_TYPES.includes(type)) throw new Error(`design/publish.json: board "${n}" has type "${type}" - use ${ARTIFACT_TYPES.join(" | ")}`);
 		if (p.open !== void 0 && !VIEW_MODES.includes(p.open)) throw new Error(`design/publish.json: board "${n}" has open "${p.open}" - use ${VIEW_MODES.join(" | ")}`);
 		if (p.transition !== void 0 && !DECK_TRANSITIONS.includes(p.transition)) throw new Error(`design/publish.json: board "${n}" has transition "${p.transition}" - use ${DECK_TRANSITIONS.join(" | ")}`);
@@ -306,6 +308,7 @@ function resolvePolicy(root, allBoards, boardsFlag, allBoardsFlag) {
 		out[n] = {
 			max: p.max,
 			type,
+			...p.showStatus === true ? { showStatus: true } : {},
 			...p.open ? { open: p.open } : {},
 			...p.lock ? { lock: true } : {},
 			...p.transition ? { transition: p.transition } : {},
@@ -339,15 +342,24 @@ function readBoards(root) {
 	return out;
 }
 /** Switcher order = the sidebar's reading order: the folder tree over the PUBLISHED boards only
-*  (a folder left with no published board drops out - its name never reaches the bundle),
+*  (a folder left with no published board at any depth drops out - its name never reaches the bundle),
 *  flattened depth-first; all-scenes always LAST (it is the expensive everything-board, never
 *  the landing). `names[0]` is where `/` opens. Folder names of published boards are structure,
 *  like board names: they ship. */
 function publishedTree(published, allBoards, folders) {
-	const tree = buildTree(published.filter((n) => n !== "all-scenes").map((n) => ({
+	const built = buildTree(published.filter((n) => n !== "all-scenes").map((n) => ({
 		name: n,
 		...boardFields(allBoards[n], isBoardName)
-	})), folders).filter((it) => it.kind === "board" || it.boards.length > 0);
+	})), folders);
+	const prune = (items) => items.flatMap((it) => {
+		if (it.kind === "board") return [it];
+		const kids = prune(it.items);
+		return kids.length ? [{
+			...it,
+			items: kids
+		}] : [];
+	});
+	const tree = prune(built);
 	return {
 		tree,
 		names: [...flatten(tree), ...published.includes("all-scenes") ? ["all-scenes"] : []]
@@ -356,11 +368,18 @@ function publishedTree(published, allBoards, folders) {
 /** The bundle's manifest: the published frames, and descriptions of published things ONLY -
 *  the project's, the published scenes' (their brief path only when source is revealed),
 *  the published boards' and the folders those sit in. No unpublished name or sentence. */
-function publishedManifest(manifest, pubFrames, publishedNames, strip) {
+function publishedManifest(manifest, pubFrames, publishedNames, strip, showStatus = /* @__PURE__ */ new Set()) {
 	const pubScenes = new Set(pubFrames.map((f) => f.scene));
 	const pubBoardSet = new Set(publishedNames);
-	const pubBoards = (manifest.boards ?? []).filter((b) => pubBoardSet.has(b.name));
+	const pubBoards = (manifest.boards ?? []).filter((b) => pubBoardSet.has(b.name)).map(({ status, ...b }) => {
+		const shown = showStatus.has(b.name) ? publishableStatus(status) : null;
+		return shown ? {
+			...b,
+			status: shown
+		} : b;
+	});
 	const pubFolderSet = new Set(pubBoards.map((b) => b.folder).filter(Boolean));
+	for (const f of manifest.folders ?? []) if (f.parent && pubFolderSet.has(f.name)) pubFolderSet.add(f.parent);
 	const pubFolders = (manifest.folders ?? []).filter((f) => pubFolderSet.has(f.name));
 	return {
 		...manifest.project ? { project: manifest.project } : {},
@@ -377,6 +396,39 @@ function publishedManifest(manifest, pubFrames, publishedNames, strip) {
 		frames: pubFrames
 	};
 }
+/** What a published status may carry, and a published board's meta - nothing else (spec 20). */
+const STATUS_KEYS = /* @__PURE__ */ new Set(["status", "fill"]);
+const META_KEYS = /* @__PURE__ */ new Set(["type", "status"]);
+/** The fields of a board file that point into context/ - stripped from every published board. */
+const EVIDENCE_FIELDS = [
+	"status",
+	"reason",
+	"capability"
+];
+function withoutEvidence(board) {
+	if (!board || typeof board !== "object" || Array.isArray(board)) return board;
+	const out = { ...board };
+	for (const k of EVIDENCE_FIELDS) delete out[k];
+	return out;
+}
+/** The build's own check of the projection: if a stripped field survives into the bundle, the
+*  build fails - a later edit to the assembly must never quietly ship the evidence trail. */
+function assertProjected(data, showStatus) {
+	const statusOk = (n, st) => {
+		if (!st || typeof st !== "object" || Array.isArray(st)) return false;
+		const o = st;
+		return showStatus.has(n) && PUBLISHABLE.has(o.status) && Object.keys(o).every((k) => STATUS_KEYS.has(k));
+	};
+	for (const [n, b] of Object.entries(data.boards)) for (const k of EVIDENCE_FIELDS) if (b && typeof b === "object" && k in b) throw new Error(`build: board "${n}" would ship its "${k}" - the publication projection failed`);
+	for (const b of data.manifest.boards ?? []) {
+		const st = b.status;
+		if (st !== void 0 && !statusOk(b.name, st)) throw new Error(`build: board "${b.name}" would ship a status its publish row did not allow`);
+	}
+	for (const [n, m] of Object.entries(data.meta ?? {})) {
+		if (Object.keys(m).some((k) => !META_KEYS.has(k))) throw new Error(`build: board "${n}" would ship meta beyond its type and status`);
+		if (m.status !== void 0 && !statusOk(n, m.status)) throw new Error(`build: board "${n}" would ship a status its publish row did not allow`);
+	}
+}
 /** The folder registry: absent = no folders (boards still imply theirs); malformed fails the build. */
 function readFolders(root) {
 	const reg = readRegistry(join(root, "design", "boards"));
@@ -492,6 +544,17 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds, textures =
 	});
 	const allBoards = readBoards(root);
 	const policy = resolvePolicy(root, allBoards, boardsFlag, allBoardsFlag);
+	let named = {};
+	try {
+		named = JSON.parse(readFileSync(join(root, "design", "publish.json"), "utf8")).boards ?? {};
+	} catch {}
+	for (const [n, pb] of Object.entries(policy.boards)) {
+		const row = named[n];
+		if (row && typeof row === "object" && row.type !== void 0) continue;
+		const bt = manifest.boards?.find((b) => b.name === n)?.type;
+		const suggested = bt ? PROPOSED_PUBLISH[bt] : void 0;
+		if (suggested && suggested !== pb.type) console.log(`  note: board "${n}" is a ${bt} board - its publish row could say "type": "${suggested}" (it publishes as "${pb.type}" until it does)`);
+	}
 	const rights = Object.fromEntries(Object.entries(policy.boards).map(([n, p]) => [n, p.max]));
 	const strip = !policy.reveal.source;
 	const buildSalt = randomBytes(16).toString("hex");
@@ -499,7 +562,7 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds, textures =
 	const { tree, names: publishedNames } = publishedTree(Object.keys(rights), allBoards, readFolders(root));
 	const includeAll = publishedNames.includes("all-scenes");
 	const boards = {};
-	for (const n of publishedNames) if (allBoards[n]) boards[n] = allBoards[n];
+	for (const n of publishedNames) if (allBoards[n]) boards[n] = withoutEvidence(allBoards[n]);
 	let frames = manifest.frames;
 	if (!includeAll) {
 		const wanted = /* @__PURE__ */ new Set();
@@ -510,7 +573,8 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds, textures =
 		...f,
 		file: opaquePath(f.id, f.kind === "html" ? ".html" : "")
 	})) : frames;
-	const pubManifest = publishedManifest(manifest, pubFrames, publishedNames, strip);
+	const showStatus = new Set(publishedNames.filter((n) => policy.boards[n]?.showStatus));
+	const pubManifest = publishedManifest(manifest, pubFrames, publishedNames, strip, showStatus);
 	for (const n of publishedNames) {
 		const pb = policy.boards[n];
 		if (pb?.type !== "slides" && pb?.open !== "slides") continue;
@@ -542,6 +606,10 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds, textures =
 		const t = boardFields(allBoards[n], isBoardName).title;
 		return t ? [[n, t]] : [];
 	}));
+	const meta = Object.fromEntries((pubManifest.boards ?? []).flatMap((b) => b.type || b.status ? [[b.name, {
+		...b.type ? { type: b.type } : {},
+		...b.status ? { status: b.status } : {}
+	}]] : []));
 	const bakeGen = textures ? Date.now() : void 0;
 	const data = {
 		bakes: bakeGen,
@@ -550,6 +618,8 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds, textures =
 		names: publishedNames,
 		tree,
 		...Object.keys(titles).length ? { titles } : {},
+		...Object.keys(meta).length ? { meta } : {},
+		...Object.values(meta).some((m) => m.status) ? { statusAsOf: (/* @__PURE__ */ new Date()).toISOString() } : {},
 		default: publishedNames.find((n) => n !== "all-scenes") ?? publishedNames[0],
 		rights,
 		policy: {
@@ -558,6 +628,7 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds, textures =
 			...lockedShell ? { lockedShell: true } : {}
 		}
 	};
+	assertProjected(data, showStatus);
 	const registryFile = posix(join(clientDir, "frame-host", "registry.ts"));
 	const lockedFile = posix(join(clientDir, "shell", "LockedApp.tsx"));
 	const tsxFrames = frames.filter((f) => f.kind === "tsx");
@@ -683,7 +754,7 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds, textures =
 	const realAssets = existsSync(assetsDir) ? realpathSync(assetsDir) : null;
 	for (const r of refs) {
 		if (!isLocalAssetRef(r) || !r.endsWith(".poster.png") || existsSync(join(assetsDir, r))) continue;
-		const { ensurePoster } = await import("./poster-FCv_nXyP.mjs");
+		const { ensurePoster } = await import("./poster-DRZDszTI.mjs");
 		const g = await ensurePoster(assetsDir, r.slice(0, -11));
 		if (!g.ok) throw new Error(`design/assets/${r}: ${g.error}`);
 		console.log(`  poster: rendered design/assets/${r} (${g.width}×${g.height})`);
@@ -750,7 +821,7 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds, textures =
 	}));
 	let textureLine = "  textures: skipped (--no-textures)";
 	if (textures && bakeGen) {
-		const { bakePublished } = await import("./publish-bakes-XH6Bac58.mjs");
+		const { bakePublished } = await import("./publish-bakes-CCWRV9iX.mjs");
 		const pubFrameFile = new Map(pubFrames.map((f) => [f.id, f]));
 		const r = await bakePublished({
 			root,

package/dist/cli.mjs

@@ -77,15 +77,20 @@ const resolve$1 = (dir) => {
 	}
 };
 const cli = cac(NAME);
-cli.command("init", "Scaffold design/ in this repo").option("--mode <mode>", "studio | embedded", { default: "studio" }).option("--no-demo", "Skip the demo scene (the demo ships unless this flag is passed)").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { init } = await import("./init-DKxuRxBr.mjs");
+cli.command("init", "Scaffold design/ in this repo").option("--mode <mode>", "studio | embedded", { default: "studio" }).option("--no-demo", "Skip the demo scene (the demo ships unless this flag is passed)").option("--kind <kind>", "product | knowledge - the sidebar's typed folders (a fresh canvas: product when an app is detected)").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
+	if (opts.kind !== void 0 && opts.kind !== "product" && opts.kind !== "knowledge") {
+		console.error(`[${NAME}] --kind ${opts.kind}: use product or knowledge`);
+		process.exit(1);
+	}
+	const { init } = await import("./init-NJ3xjLVu.mjs");
 	init(resolve$1(opts.root), {
 		mode: opts.mode === "embedded" ? "embedded" : "studio",
-		demo: opts.demo !== false
+		demo: opts.demo !== false,
+		kind: opts.kind
 	});
 });
 for (const [name, desc] of [["dev", "Start the local canvas (everything on: hot reload, comments, Live Jam)"], ["canvas", "Start the local canvas - same as dev"]]) cli.command(name, desc).option("--root <dir>", "Host repo root", { default: "." }).option("--port <port>", "Port (default 5199)").action(async (opts) => {
-	const { dev } = await import("./dev-BjdDP69b.mjs");
+	const { dev } = await import("./dev-BW7a5kDF.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -95,7 +100,7 @@ for (const [name, desc] of [["dev", "Start the local canvas (everything on: hot
 	await dev(resolve$1(opts.root), port);
 });
 cli.command("build", "Static export → design/.dist (what ships comes from design/publish.json - publishing is default-closed)").option("--boards <names>", "Publish only these boards (comma-separated); overrides the publish policy").option("--all-boards", "Publish every board - the loud override for the default-closed policy").option("--embed-seeds", "Copy comment history INTO the web root (identifying - every event carries its author's email)").option("--no-textures", "Skip compiling the glass textures the published frames rest under (needs Chrome; a CI without one skips on its own)").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { buildSite } = await import("./build-DwpNPl6Z.mjs");
+	const { buildSite } = await import("./build-Dd2Qm3OG.mjs");
 	try {
 		const boards = opts.boards === void 0 ? void 0 : typeof opts.boards === "string" ? opts.boards : "";
 		await buildSite(resolve$1(opts.root), boards, opts.allBoards === true, opts.embedSeeds === true, opts.textures !== false && !process.env.MARVER_NO_TEXTURES);
@@ -140,10 +145,64 @@ cli.command("work <action> [...frames]", "Working state on the canvas: start <sc
 		process.exit(1);
 	}
 });
-cli.command("boards", "The sidebar as files: every folder and board in reading order, the landing board, the registry").option("--root <dir>", "Host repo root", { default: "." }).option("--json", "The tree as JSON ({ tree, landing, registry })").action(async (opts) => {
-	const { boardsCommand } = await import("./boards-PuVzw5Wp.mjs");
+cli.command("boards [action] [name]", "The sidebar as files: every folder and board in reading order, with types and statuses · new <name>: a board in its type's starting layout").option("--root <dir>", "Host repo root", { default: "." }).option("--json", "The tree as JSON ({ tree, boards, landing, registry })").option("--type <type>", "new: start | feature | surface | project | feedback | context | deck | archive (default: the folder's)").option("--folder <folder>", "new: the folder it sits in").option("--title <title>", "new: what humans see").option("--description <sentence>", "new: what agents read").option("--capability <slug>", "new: the capability it shows, when not its own name").action(async (action, name, opts) => {
+	const { boardsCommand, boardsNew } = await import("./boards-BTGNPVMx.mjs");
+	try {
+		if (action === void 0) boardsCommand(resolve$1(opts.root), opts);
+		else if (action === "new") {
+			if (!name) throw new Error("name the board: `boards new <name>`");
+			const made = boardsNew(resolve$1(opts.root), name, opts);
+			for (const c of made) console.log(`  + ${c}`);
+			if (made.some((c) => c.endsWith("/_brief.md")) && !made.some((c) => /\.(tsx|jsx|html)$/.test(c))) console.log(`\n  next: a frame you make in these scenes shows on the board once it is pinned - a node in\n  design/boards/${name}.json (an agent does this as it works: design/AGENTS.md)`);
+		} else throw new Error(`unknown action "${action}" - \`boards\` lists, \`boards new <name>\` creates`);
+	} catch (err) {
+		console.error(`[${NAME}] ${err.message}`);
+		process.exit(1);
+	}
+});
+cli.command("folders <action> [...modules]", "The shared sidebar's typed folders · add <start|features|surfaces|projects|feedback|context|decks|archive ...>").option("--root <dir>", "Host repo root", { default: "." }).action(async (action, modules, opts) => {
+	const { foldersAdd } = await import("./boards-BTGNPVMx.mjs");
+	try {
+		if (action !== "add") throw new Error(`unknown action "${action}" - \`folders add <module ...>\``);
+		const { added, existing } = foldersAdd(resolve$1(opts.root), modules);
+		for (const a of added) console.log(`  + design/boards/_folders.json: ${a}`);
+		for (const e of existing) console.log(`  = ${e} exists - left as it is`);
+	} catch (err) {
+		console.error(`[${NAME}] ${err.message}`);
+		process.exit(1);
+	}
+});
+cli.command("context <action>", "The project's context/ (spec 19) · init: create it · check: keep it true (exit 0 pass, 1 fail, 2 cannot determine) · index: regenerate the index's capability table").option("--root <dir>", "Host repo root", { default: "." }).option("--base <ref>", "check: the pull request's base - a change to a contracted capability's code must change its contract or say why (in ci, read from the event)").option("--head <ref>", "check: the pull request's head (default HEAD)").option("--body-file <file>", "check: the pull request's body, for `no-contract-change: <capability> - <why>`").option("--json", "check: the findings as JSON ({ exit, failures, unsure, notes })").option("--kind <kind>", "init: product (a shipped record) or knowledge (a delivered record)", { default: "product" }).action(async (action, opts) => {
+	const ctx = await import("./context-DUAENlJ6.mjs");
+	const root = resolve$1(opts.root);
 	try {
-		boardsCommand(resolve$1(opts.root), opts);
+		if (action === "init") {
+			if (opts.kind !== "product" && opts.kind !== "knowledge") throw new Error(`--kind ${opts.kind}: use product or knowledge`);
+			const created = ctx.contextInit(root, opts.kind);
+			for (const c of created) console.log(`  + ${c}`);
+			if (!created.length) console.log("  context/ is already set up - nothing to add");
+			console.log(`\n  next: tell your agent "Read ${ctx.conventionsPath(root)} and set up our context" - the setup interview, then a first draft from evidence.\n  in ci: npx ${NAME} context check  (with full history: fetch-depth: 0)\n`);
+		} else if (action === "check") {
+			const { readFileSync } = await import("node:fs");
+			const fromEnv = ctx.pullRequestFromEnv() ?? {};
+			const given = {
+				...opts.base !== void 0 ? { base: String(opts.base) } : {},
+				...opts.head !== void 0 ? { head: String(opts.head) } : {},
+				...opts.bodyFile !== void 0 ? { body: readFileSync(opts.bodyFile, "utf8") } : {}
+			};
+			const merged = {
+				...fromEnv,
+				...given
+			};
+			if (given.base !== void 0) delete merged.prError;
+			const r = ctx.contextCheck(root, merged);
+			if (opts.json) console.log(JSON.stringify(r, null, 2));
+			else ctx.printCheck(r);
+			process.exit(r.exit);
+		} else if (action === "index") {
+			const { words, changed } = ctx.contextIndex(root);
+			console.log(`  context/INDEX.md: ${changed ? "capability table regenerated" : "already current"} - ${words} / ${ctx.INDEX_BUDGET} words`);
+		} else throw new Error(`unknown action "${action}" - init, check or index`);
 	} catch (err) {
 		console.error(`[${NAME}] ${err.message}`);
 		process.exit(1);