@marver-design/marver 0.14.0 → 0.16.0

package/dist/{build-ByYafIhj.mjs → build-Ct0iMoSi.mjs}

@@ -1,7 +1,8 @@
 import { i as ROUTE, n as NAME } from "./cli.mjs";
-import { l as detectHost, r as scanFrames, s as loadConfig } from "./manifest-DvOmglFp.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-BsmG5i2X.mjs";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { i as listBoardFiles, l as buildTree, n as checkBoardsDir, o as readRegistry, u as flatten } from "./boards-BdG1TJwU.mjs";
+import { c as detectHost, n as scanFrames, o as loadConfig } from "./manifest-CpbsqQ_v.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-BXyezwfN.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";
 import { createHash, randomBytes } from "node:crypto";
@@ -44,8 +45,9 @@ function scanAssetRefs(src, moduleId) {
 		const srcM = /\bsrc\s*=\s*["']([^"']+)["']/.exec(tag);
 		const posterM = /\bposter\s*=\s*["']([^"']+)["']/.exec(tag);
 		if (srcM) {
-			if (!/^https:\/\//.test(srcM[1]) && !posterM) throw new Error(`${moduleId}: <Video src="${srcM[1]}"> is a local file without a poster - the poster is the slide at rest. Add poster="...".`);
+			const remote = /^https:\/\//.test(srcM[1]);
 			out.push(srcM[1]);
+			if (!remote && !posterM) out.push(`${srcM[1]}.poster.png`);
 		}
 		if (posterM) out.push(posterM[1]);
 	}
@@ -147,22 +149,67 @@ function resolvePolicy(root, allBoards, boardsFlag, allBoardsFlag) {
 		reveal
 	};
 }
-/** Read every board file; returns name -> parsed json. Bad JSON fails the build loudly. */
+/** Read every board file; returns name -> parsed json. Bad JSON fails the build loudly, and so
+*  does a board-named entry that is not a regular file (a symlink could publish JSON from
+*  outside the project - the build fails closed rather than skipping it quietly). */
 function readBoards(root) {
 	const dir = join(root, "design", "boards");
+	const de = checkBoardsDir(root, dir);
+	if (de) throw new Error(de);
+	const { boards, skipped } = listBoardFiles(dir);
+	if (skipped.length) throw new Error(`design/boards/${skipped[0]} is not a regular file (a symlinked board cannot be published)`);
 	const out = {};
-	if (!existsSync(dir)) return out;
-	for (const f of readdirSync(dir)) {
-		if (!f.endsWith(".json")) continue;
-		const name = f.replace(/\.json$/, "");
-		try {
-			out[name] = JSON.parse(readFileSync(join(dir, f), "utf8"));
-		} catch {
-			throw new Error(`design/boards/${f} is not valid JSON`);
-		}
+	for (const b of boards) {
+		if (b.json === null) throw new Error(`design/boards/${b.name}.json is not valid JSON`);
+		out[b.name] = b.json;
 	}
 	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),
+*  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 field = (n, k) => allBoards[n]?.[k];
+	const tree = buildTree(published.filter((n) => n !== "all-scenes").map((n) => ({
+		name: n,
+		order: field(n, "order"),
+		folder: field(n, "folder")
+	})), folders).filter((it) => it.kind === "board" || it.boards.length > 0);
+	return {
+		tree,
+		names: [...flatten(tree), ...published.includes("all-scenes") ? ["all-scenes"] : []]
+	};
+}
+/** 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) {
+	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 pubFolderSet = new Set(pubBoards.map((b) => b.folder).filter(Boolean));
+	const pubFolders = (manifest.folders ?? []).filter((f) => pubFolderSet.has(f.name));
+	return {
+		...manifest.project ? { project: manifest.project } : {},
+		...pubFolders.length ? { folders: pubFolders } : {},
+		...pubBoards.length ? { boards: pubBoards } : {},
+		scenes: manifest.scenes.filter((s) => pubScenes.has(s.name)).map(({ name, description, brief }) => ({
+			name,
+			frames: pubFrames.filter((f) => f.scene === name).length,
+			...description ? { description } : {},
+			...brief && !strip ? { brief } : {}
+		})),
+		frames: pubFrames
+	};
+}
+/** The folder registry: absent = no folders (boards still imply theirs); malformed fails the build. */
+function readFolders(root) {
+	const reg = readRegistry(join(root, "design", "boards"));
+	if (reg.state === "malformed") throw new Error(reg.error);
+	return reg.folders;
+}
 /**
 * The generated registry with OPAQUE keys - the source strip's half of the
 * bundle (01-sharing §6.2). Object keys are string literals that survive
@@ -266,18 +313,17 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds) {
 	const pkgDir = packageDir();
 	const clientDir = join(pkgDir, "src", "client");
 	const outDir = join(root, "design", ".dist");
-	const manifest = scanFrames(root);
+	const manifest = scanFrames(root, {
+		name: config.share.name || basename(root),
+		description: config.description
+	});
 	const allBoards = readBoards(root);
 	const policy = resolvePolicy(root, allBoards, boardsFlag, allBoardsFlag);
 	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");
 	const opaquePath = (id, ext) => `__mv/f/mv${createHash("sha256").update(buildSalt).update(id).digest("hex").slice(0, 12)}${ext}`;
-	const boardOrder = (n) => {
-		const o = allBoards[n]?.order;
-		return typeof o === "number" && Number.isFinite(o) ? o : Infinity;
-	};
-	const publishedNames = Object.keys(rights).sort((a, b) => a === "all-scenes" ? 1 : b === "all-scenes" ? -1 : boardOrder(a) - boardOrder(b) || a.localeCompare(b));
+	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];
@@ -287,17 +333,10 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds) {
 		for (const b of Object.values(boards)) for (const node of Array.isArray(b?.nodes) ? b.nodes : []) if (typeof node?.frame === "string") wanted.add(node.frame);
 		frames = manifest.frames.filter((f) => wanted.has(f.id));
 	}
-	const pubFrames = strip ? frames.map((f) => ({
+	const pubManifest = publishedManifest(manifest, strip ? frames.map((f) => ({
 		...f,
 		file: opaquePath(f.id, f.kind === "html" ? ".html" : "")
-	})) : frames;
-	const pubManifest = {
-		frames: pubFrames,
-		scenes: [...new Set(pubFrames.map((f) => f.scene))].sort().map((name) => ({
-			name,
-			frames: pubFrames.filter((f) => f.scene === name).length
-		}))
-	};
+	})) : frames, publishedNames, strip);
 	for (const n of publishedNames) {
 		const pb = policy.boards[n];
 		if (pb?.type !== "slides" && pb?.open !== "slides") continue;
@@ -329,6 +368,7 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds) {
 		manifest: pubManifest,
 		boards,
 		names: publishedNames,
+		tree,
 		default: publishedNames.find((n) => n !== "all-scenes") ?? publishedNames[0],
 		rights,
 		policy: {
@@ -458,6 +498,13 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds) {
 	}
 	let copiedAssets = 0;
 	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-DOY7pax8.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})`);
+	}
 	for (const r of refs) {
 		if (!isLocalAssetRef(r)) continue;
 		const srcFile = join(assetsDir, r);
@@ -526,4 +573,4 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds) {
 	console.log(`\n  serve it:  npx ${NAME} serve   (set MARVER_PASSWORD to gate it)\n`);
 }
 //#endregion
-export { buildSite };
+export { buildSite, isLocalAssetRef, scanAssetRefs };

package/dist/cli.mjs

@@ -53,14 +53,14 @@ function version() {
 }
 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-Dvaso7YO.mjs");
+	const { init } = await import("./init-BQIpIpIv.mjs");
 	init(resolve(opts.root), {
 		mode: opts.mode === "embedded" ? "embedded" : "studio",
 		demo: opts.demo !== false
 	});
 });
 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-yZMyQeUj.mjs");
+	const { dev } = await import("./dev-CdcIuhZJ.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -70,7 +70,7 @@ for (const [name, desc] of [["dev", "Start the local canvas (everything on: hot
 	await dev(resolve(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("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { buildSite } = await import("./build-ByYafIhj.mjs");
+	const { buildSite } = await import("./build-Ct0iMoSi.mjs");
 	try {
 		const boards = opts.boards === void 0 ? void 0 : typeof opts.boards === "string" ? opts.boards : "";
 		await buildSite(resolve(opts.root), boards, opts.allBoards === true, opts.embedSeeds === true);
@@ -89,7 +89,7 @@ cli.command("serve", "Serve design/.dist (set MARVER_PASSWORD to gate it)").opti
 	serve(resolve(opts.root), port);
 });
 cli.command("comments <action> [value]", "Comment collaboration: connect <url> · sync · list · reply <thread> · resolve <thread> · invite <email> · revoke <email>").option("--root <dir>", "Host repo root", { default: "." }).option("--token <token>", "connect: the canvas's MARVER_CLI_TOKEN (default $MARVER_CLI_TOKEN) - the identity-mode path").option("--invite <token>", "connect: claim this invite instead of signing in").option("--canvas-password <password>", "connect: the canvas gate password (default $MARVER_PASSWORD or prompt)").option("--email <email>", "connect: account email (skips the prompt)").option("--password <password>", "connect: account password (skips the prompt - mind your shell history)").option("--name <name>", "connect --invite: display name for the new account").option("--open", "list: only unresolved threads").option("--json", "list: machine-readable output").option("--board <board>", "scope to one board").option("--body <text>", "reply: the reply text").option("--addressed-in <frame>", "resolve: the variant frame that answered the feedback").action(async (action, value, opts) => {
-	const { commentsCommand } = await import("./comments-DHB_8BRa.mjs");
+	const { commentsCommand } = await import("./comments-oYcZ3cE-.mjs");
 	try {
 		await commentsCommand(resolve(opts.root), action, value, opts);
 	} catch (err) {
@@ -115,8 +115,17 @@ cli.command("work <action> [...frames]", "Working state on the canvas: start <sc
 		process.exit(1);
 	}
 });
-cli.command("shot <frame>", "Render one frame headless and print the PNG path (needs `dev` running)").option("--root <dir>", "Host repo root", { default: "." }).option("--theme <name>", "Theme to render (default: light)").action(async (frame, opts) => {
-	const { shotCommand } = await import("./shot-DkkwuCZ2.mjs");
+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-6hKVW42a.mjs");
+	try {
+		boardsCommand(resolve(opts.root), opts);
+	} catch (err) {
+		console.error(`[${NAME}] ${err.message}`);
+		process.exit(1);
+	}
+});
+cli.command("shot <frame>", "Render one frame headless and print the PNG path (needs `dev` running)").option("--root <dir>", "Host repo root", { default: "." }).option("--theme <name>", "Theme to render (default: light)").option("--scale <n>", "Device pixels per CSS px, 1-4 (default: 2; 4 for print-quality stills)").action(async (frame, opts) => {
+	const { shotCommand } = await import("./shot-By1AItpD.mjs");
 	try {
 		await shotCommand(resolve(opts.root), frame, opts);
 	} catch (err) {

package/dist/{daemon-Bfucyf1o.mjs → daemon-Cb4JjpgL.mjs}

@@ -1,7 +1,7 @@
 import { n as replay } from "./events-B3LBn74P.mjs";
 import { i as readLog, r as listBoards, t as appendEvents } from "./comments-DZyobpxG.mjs";
 import { n as localProfile } from "./profile-BjAPAJSb.mjs";
-import { i as toFrameId } from "./manifest-DvOmglFp.mjs";
+import { r as toFrameId } from "./manifest-CpbsqQ_v.mjs";
 import { workActivity } from "./work-CLrmY-vQ.mjs";
 import { r as deviceId, t as has } from "./ledger-Bu0BjqIe.mjs";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, watch, writeFileSync, writeSync } from "node:fs";

package/dist/{dev-yZMyQeUj.mjs → dev-CdcIuhZJ.mjs}

@@ -1,6 +1,6 @@
 import { n as NAME, r as PKG } from "./cli.mjs";
-import { l as detectHost, s as loadConfig } from "./manifest-DvOmglFp.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-BsmG5i2X.mjs";
+import { c as detectHost, o as loadConfig } from "./manifest-CpbsqQ_v.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-BXyezwfN.mjs";
 import { realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -18,6 +18,14 @@ const portFree = (p) => new Promise((res) => {
 	s.once("listening", () => s.close(() => res(true)));
 	s.listen(p, "127.0.0.1");
 });
+/** realpath, or the path itself when it cannot be resolved (never throws at boot). */
+const safeReal = (p) => {
+	try {
+		return realpathSync(p);
+	} catch {
+		return p;
+	}
+};
 /** C1: a deterministic per-project port in [5200,5399] derived from the root path. Two projects
 *  never collide, and the same project always lands on the same port across restarts. */
 const projectPort = (root) => {
@@ -189,7 +197,9 @@ async function dev(root, portFlag) {
 			fs: {
 				allow: [.../* @__PURE__ */ new Set([
 					root,
+					safeReal(root),
 					pkgDir,
+					safeReal(pkgDir),
 					searchForWorkspaceRoot(root)
 				])],
 				deny: FS_DENY
@@ -247,7 +257,7 @@ async function dev(root, portFlag) {
 	console.log(`\n  ${NAME} · ${projectName} → http://localhost:${port}/\n`);
 	try {
 		const { staleManagedInstructions } = await import("./managed-HwHVNI3h.mjs");
-		const { installedVersion } = await import("./plugin-BsmG5i2X.mjs").then((n) => n.i);
+		const { installedVersion } = await import("./plugin-BXyezwfN.mjs").then((n) => n.i);
 		const stale = staleManagedInstructions(root);
 		if (stale.length) {
 			const shown = stale.slice(0, 4).join(", ") + (stale.length > 4 ? `, +${stale.length - 4} more` : "");
@@ -285,7 +295,7 @@ async function dev(root, portFlag) {
 		});
 	}
 	if (config.jam) {
-		const { startJam } = await import("./daemon-Bfucyf1o.mjs");
+		const { startJam } = await import("./daemon-Cb4JjpgL.mjs");
 		const jam = startJam(root, config.jam, (m) => console.log(m), (board) => server.ws.send("sh:jam-comment", { board }));
 		if (jam) {
 			const close = server.close.bind(server);

package/dist/{init-Dvaso7YO.mjs → init-BQIpIpIv.mjs}

@@ -1,8 +1,8 @@
 import { n as NAME } from "./cli.mjs";
-import { a as writeManifest, c as detectAgent, l as detectHost, o as DEFAULTS, r as scanFrames, u as readJson } from "./manifest-DvOmglFp.mjs";
+import { a as DEFAULTS, c as detectHost, i as writeManifest, l as readJson, n as scanFrames, s as detectAgent } from "./manifest-CpbsqQ_v.mjs";
 import { MANAGED_PREFIX, enumerateInstructionTemplates, hashBody, managedFile, pkgDir } from "./managed-HwHVNI3h.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 //#region src/cli/init.ts
 /** Idempotent scaffolder: never overwrites existing files; every host-repo touch prints a diff. */
 function init(root, opts) {
@@ -221,7 +221,7 @@ function init(root, opts) {
 		created.push("design/scenes/demo/ (3 frames)");
 	}
 	if (host.tsconfigSweepsDesign) patchTsconfigExclude(root);
-	writeManifest(root, scanFrames(root));
+	writeManifest(root, scanFrames(root, { name: basename(root) }));
 	console.log(`\n${NAME} initialized (${opts.mode} mode). Created:`);
 	for (const f of created) console.log(`  + ${f}`);
 	if (host.router === "next") console.log(`\n  note: Next.js support is partial - frames render outside Next, so next/font, next/image and Server Components do not exist inside them (details in design/AGENTS.md).`);
@@ -540,6 +540,9 @@ const configTemplate = (mode, jamAgent) => `// ${NAME} config - OPTIONAL. Delete
 // relative imports need extensions, tsconfig paths are ignored here.
 export default {
   mode: ${JSON.stringify(mode)},
+  // One sentence on what this product is and for whom. It lands in design/manifest.json
+  // as the project's description - the first thing a new agent session reads.
+  // description: "Analytics for indie SaaS - the founder's Monday-morning read",
   // Device widths for frames and the Devices view. Rename, retune, or uncomment tv.
   viewports: {
     mobile: { width: 390, height: 844 },

package/dist/{manifest-DvOmglFp.mjs → manifest-CpbsqQ_v.mjs}

@@ -1,8 +1,8 @@
 import { r as PKG, t as CONTENT_WIDTH } from "./cli.mjs";
+import { d as isBoardName, f as readDescription, i as listBoardFiles, l as buildTree, m as hash, n as checkBoardsDir, o as readRegistry, t as boardFields, u as flatten } from "./boards-BdG1TJwU.mjs";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { delimiter, isAbsolute, join, relative, sep } from "node:path";
 import { pathToFileURL } from "node:url";
-import { createHash } from "node:crypto";
 //#region src/server/detect.ts
 function readJson(file) {
 	try {
@@ -261,6 +261,7 @@ async function loadConfig(root) {
 			themes: Array.isArray(user.themes) && user.themes.length ? user.themes.map(String) : DEFAULTS.themes,
 			port: validPort(user.port) ?? DEFAULTS.port,
 			zoomSpeed: validZoom(user.zoomSpeed) ?? DEFAULTS.zoomSpeed,
+			description: readDescription(user.description),
 			share: {
 				branding: user.share?.branding !== false,
 				name: typeof user.share?.name === "string" ? user.share.name : void 0,
@@ -379,8 +380,8 @@ function extractMeta(src) {
 	if (!m) return {};
 	const body = m[1];
 	const pick = (key) => {
-		const r = new RegExp(`(?:^|[{,])\\s*${key}\\s*:\\s*(['"\`])([^'"\`]*)\\1`).exec(body);
-		return r ? r[2] : void 0;
+		const r = new RegExp(`(?:^|[{,])\\s*${key}\\s*:\\s*(?:'([^'\\n]*)'|"([^"\\n]*)"|\`([^\`\\n]*)\`)\\s*(?=[,}\\n]|$)`).exec(body);
+		return r ? r[1] ?? r[2] ?? r[3] : void 0;
 	};
 	const pickBool = (key) => {
 		const r = new RegExp(`(?:^|[{,])\\s*${key}\\s*:\\s*(true|false)\\b`).exec(body);
@@ -401,22 +402,35 @@ function extractMeta(src) {
 	if (intent) out.intent = intent;
 	const slide = pickBool("slide");
 	if (slide !== void 0) out.slide = slide;
+	const description = readDescription(pick("description"));
+	if (description) out.description = description;
 	return out;
 }
-/** Content-frame detection: LEXICAL by convention - the frame file
-*  itself imports PKG/content (an import specifier scan, so "<Diagram" inside a
-*  string in a UI frame can never misbadge it; barrels/re-exports are not
-*  detected - meta.intent is the taught path and always works). Returns the
-*  inferred intent + natural width, or null for UI frames. */
+/** Content-frame detection: LEXICAL by convention - the frame file itself imports
+*  PKG/content (an import specifier scan, so "<Diagram" inside a string in a UI frame can
+*  never misbadge it; barrels/re-exports are not detected - meta.intent is the taught path
+*  and always works) AND renders a DOCUMENT primitive: Doc, Md, Diagram or Img (reference
+*  imagery - a moodboard is Rows of Img). The import alone is not enough - Chart, Video, Row,
+*  Col and Space are shared blocks a UI screen or a slide uses too, and a dashboard with one
+*  <Chart> is still a screen (device height, no document measuring), never a spec. Returns
+*  the inferred intent + natural width, or null for UI frames. */
 const CONTENT_IMPORT = new RegExp(`from\\s+['"]${PKG}/content['"]`);
 const WIDE_DOC = /<Doc\b[^>]*\blayout\s*=\s*["']wide["']/;
 const contentWidthOf = (src) => WIDE_DOC.test(src) ? CONTENT_WIDTH.wide : CONTENT_WIDTH.document;
+/** The source with comments, template literals and CODE-shaped strings blanked (a JSX
+*  expression string `{'<Diagram>'}`, an attribute value), so a tag name quoted in an example
+*  or a comment never counts as a rendered element. Prose is left alone: JSX text has
+*  apostrophes ("it's"), and a blanket quote match would swallow real tags between two of them. */
+const codeOnly = (src) => src.replace(/`(?:[^`\\]|\\[\s\S])*`/g, "``").replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1").replace(/\{\s*(?:"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*')\s*\}/g, "{\"\"}").replace(/([=(,:[{?+|&!]|\breturn)\s*(?:"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*')/g, "$1\"\"").replace(/([=(,:[{?+|&!]|\breturn)\s*\/(?:[^/\\\n[]|\\.|\[(?:[^\]\\\n]|\\.)*\])+\/[gimsuy]*/g, "$1/re/");
 function contentScan(src) {
 	if (!CONTENT_IMPORT.test(src)) return null;
-	const count = (re) => (src.match(re) ?? []).length;
+	const code = codeOnly(src);
+	const count = (re) => (code.match(re) ?? []).length;
+	const docs = count(/<Doc[\s>/]/g);
 	const diagrams = count(/<Diagram[\s>/]/g);
 	const imgs = count(/<Img[\s>/]/g);
 	const mds = count(/<Md[\s>/]/g);
+	if (docs + diagrams + mds + imgs === 0) return null;
 	return {
 		intent: diagrams > 0 ? "diagram" : imgs > mds ? "moodboard" : "spec",
 		width: contentWidthOf(src)
@@ -462,7 +476,63 @@ function walk(dir, out = []) {
 	}
 	return out;
 }
-function scanFrames(root) {
+/** A scene's description is the first non-blank line of its `_brief.md` (a leading `#`
+*  stripped, a YAML front-matter block skipped) - no new file. */
+function sceneBrief(root, scene) {
+	if (!scene) return {};
+	const rel = `design/scenes/${scene}/_brief.md`;
+	const abs = join(root, ...rel.split("/"));
+	if (!existsSync(abs)) return {};
+	let description;
+	try {
+		const lines = readFileSync(abs, "utf8").split(/\r?\n/).map((l) => l.trim());
+		let i = 0;
+		if (lines[0] === "---") {
+			i = lines.indexOf("---", 1) + 1;
+			if (i === 0) i = lines.length;
+		}
+		const line = lines.slice(i).find((l) => l);
+		description = readDescription(line?.replace(/^#+\s*/, ""));
+	} catch {}
+	return {
+		brief: rel,
+		...description ? { description } : {}
+	};
+}
+/** The sidebar as files say it is, for the manifest: folders in root order, boards in
+*  reading order with their folder and description. A boards dir we may not read (symlink)
+*  or a malformed registry yields nothing here - the API and the build say why; the
+*  orientation file must never fail to write. */
+function scanBoards(root) {
+	const dir = join(root, "design", "boards");
+	if (checkBoardsDir(root, dir)) return {};
+	const reg = readRegistry(dir);
+	if (reg.state === "malformed") return {};
+	const rows = listBoardFiles(dir).boards.map((b) => ({
+		name: b.name,
+		...boardFields(b.json, isBoardName)
+	}));
+	const tree = buildTree(rows, reg.folders);
+	const folderOf = /* @__PURE__ */ new Map();
+	for (const it of tree) if (it.kind === "folder") for (const b of it.boards) folderOf.set(b, it.name);
+	const folders = tree.filter((it) => it.kind === "folder").map((it) => ({
+		name: it.name,
+		...it.description ? { description: it.description } : {}
+	}));
+	const boards = flatten(tree).map((name) => {
+		const d = rows.find((r) => r.name === name)?.description;
+		return {
+			name,
+			...folderOf.has(name) ? { folder: folderOf.get(name) } : {},
+			...d ? { description: d } : {}
+		};
+	});
+	return {
+		...folders.length ? { folders } : {},
+		...boards.length ? { boards } : {}
+	};
+}
+function scanFrames(root, project) {
 	const design = join(root, "design");
 	const frames = [];
 	for (const base of ["scenes", "components"]) for (const abs of walk(join(design, base))) {
@@ -491,6 +561,7 @@ function scanFrames(root) {
 			if (meta.of) entry.variantGroup = meta.of;
 			if (meta.variant) entry.variant = meta.variant;
 			if (meta.slide) entry.slide = true;
+			if (meta.description) entry.description = meta.description;
 			const content = contentScan(src);
 			if (content || meta.intent) {
 				entry.intent = meta.intent ?? content.intent;
@@ -516,12 +587,19 @@ function scanFrames(root) {
 	inferVariantGroups(frames);
 	const sceneCounts = /* @__PURE__ */ new Map();
 	for (const f of frames) sceneCounts.set(f.scene, (sceneCounts.get(f.scene) ?? 0) + 1);
+	const scenes = [...sceneCounts.entries()].map(([name, n]) => ({
+		name,
+		frames: n,
+		...sceneBrief(root, name)
+	})).sort((a, b) => a.name.localeCompare(b.name));
 	return {
-		frames,
-		scenes: [...sceneCounts.entries()].map(([name, n]) => ({
-			name,
-			frames: n
-		})).sort((a, b) => a.name.localeCompare(b.name))
+		...project && (project.name || project.description) ? { project: {
+			...project.name ? { name: project.name } : {},
+			...project.description ? { description: project.description } : {}
+		} } : {},
+		...scanBoards(root),
+		scenes,
+		frames
 	};
 }
 /** Variant groups. A group = 2+ frames in one DIRECTORY whose basenames
@@ -603,6 +681,5 @@ function writeManifest(root, manifest) {
 	writeFileSync(file, next);
 	return true;
 }
-const hash = (s) => createHash("sha256").update(s).digest("hex");
 //#endregion
-export { writeManifest as a, detectAgent as c, toFrameId as i, detectHost as l, hash as n, DEFAULTS as o, scanFrames as r, loadConfig as s, affectedFrameIds as t, readJson as u };
+export { DEFAULTS as a, detectHost as c, writeManifest as i, readJson as l, scanFrames as n, loadConfig as o, toFrameId as r, detectAgent as s, affectedFrameIds as t };