@marver-design/marver 0.20.0 → 0.22.0

package/dist/board-status-CWGHIdo_.mjs

@@ -0,0 +1,1307 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join, sep } from "node:path";
+import { createHash } from "node:crypto";
+//#region src/server/hash.ts
+/** sha256 hex of a string - the CAS token for board files, the registry, the manifest. */
+const hash = (s) => createHash("sha256").update(s).digest("hex");
+//#endregion
+//#region src/shared/board-types.ts
+/**
+* Board types (spec 20) - what a board is FOR in the workspace, one vocabulary every canvas
+* shares so any sidebar reads at a glance. A board states its own `"type"`, or wears the type of
+* the nearest typed folder above it (its folder, then that folder's parent), else it is plain.
+* Moving a board changes an inherited type, never one the board states itself.
+*
+* Pure and shared: the dev API, the manifest, the build, the shell and the CLI all read types
+* through here, so a type means one thing everywhere.
+*/
+const BOARD_TYPES = [
+	"start",
+	"feature",
+	"surface",
+	"project",
+	"feedback",
+	"context",
+	"deck",
+	"archive"
+];
+/** The grammar a stored type keeps to. Any on-grammar word survives a write - a newer Marver's
+*  type is never dropped by an older shell - while only the known ones are drawn. */
+const TYPE_GRAMMAR = /^[a-z][a-z-]{0,31}$/;
+/** A type off a file: the word when it is on-grammar, else absent. */
+const readType = (v) => typeof v === "string" && TYPE_GRAMMAR.test(v) ? v : void 0;
+/** A type this Marver draws. */
+const knownType = (v) => BOARD_TYPES.includes(v) ? v : void 0;
+/** A board's type: its own when it states one (an unknown word reads as plain - the board spoke
+*  for itself), else its folder's, else that folder's parent's, else plain. */
+function resolveType(own, folder, parent) {
+	if (readType(own)) return knownType(own) ?? "plain";
+	return knownType(folder) ?? knownType(parent) ?? "plain";
+}
+/** The publish type a board's type proposes when its publish row names none - how a board
+*  PRESENTS when published, a separate question from what it is for. */
+const PROPOSED_PUBLISH = {
+	deck: "slides",
+	context: "refs",
+	project: "doc",
+	feature: "mix",
+	surface: "mix"
+};
+/** The types that carry a status (spec 20, open question 2: features and projects - the others
+*  have no lifecycle of their own). */
+const HAS_STATUS = ["feature", "project"];
+/** The decisions a board may state by hand. `done` is never one: Done comes only from the shipped
+*  record. `todo`, `backlog` and `in-progress` count only where there is no `context/`. */
+const DECISIONS = [
+	"archived",
+	"paused",
+	"blocked"
+];
+const BY_HAND = [
+	"in-progress",
+	"todo",
+	"backlog"
+];
+const STATUS_WORDS = [
+	...DECISIONS,
+	...BY_HAND,
+	"done"
+];
+const readStatusWord = (v) => STATUS_WORDS.includes(v) ? v : void 0;
+/** The statuses a person may set on a feature or project board, in the order a picker lists them:
+*  the three decisions always; Backlog, To do and In progress only where there is no `context/`
+*  (with it they are read from the evidence). Never Done - that is the shipped record's alone. */
+const settableStatuses = (contextPresent) => contextPresent ? [
+	"blocked",
+	"paused",
+	"archived"
+] : [
+	"backlog",
+	"todo",
+	"in-progress",
+	"blocked",
+	"paused",
+	"archived"
+];
+/** A capability slug - the same grammar as a board name, so a feature board and its contract
+*  share it. */
+const readCapability = (v) => typeof v === "string" && /^[a-z0-9][a-z0-9-]{0,63}$/.test(v) ? v : void 0;
+const readReason = (v) => {
+	if (typeof v !== "string") return void 0;
+	return v.trim().replace(/\s+/g, " ").slice(0, 300) || void 0;
+};
+/** The sidebar every canvas shares (spec 19, The canvas): folder modules, each typed, so a board
+*  made inside one wears its type. `marver init --kind` creates a kind's set on a fresh canvas;
+*  `marver folders add <module>` adds one later. Names are slugs; only Start here needs a title. */
+const FOLDER_MODULES = {
+	start: {
+		name: "start-here",
+		title: "Start here",
+		type: "start"
+	},
+	features: {
+		name: "features",
+		type: "feature"
+	},
+	surfaces: {
+		name: "surfaces",
+		type: "surface"
+	},
+	projects: {
+		name: "projects",
+		type: "project"
+	},
+	feedback: {
+		name: "feedback",
+		type: "feedback"
+	},
+	context: {
+		name: "context",
+		type: "context"
+	},
+	decks: {
+		name: "decks",
+		type: "deck"
+	},
+	archive: {
+		name: "archive",
+		type: "archive"
+	}
+};
+/** A kind of work's folders, in sidebar order: the core (Start here, Feedback, Context, Archive)
+*  around the kind's own modules. Decks are an add-on for either. */
+const KIND_FOLDERS = {
+	product: [
+		"start",
+		"features",
+		"surfaces",
+		"feedback",
+		"context",
+		"archive"
+	],
+	knowledge: [
+		"start",
+		"projects",
+		"feedback",
+		"context",
+		"archive"
+	]
+};
+//#endregion
+//#region src/shared/board-tree.ts
+/**
+* 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 - one slug, the folder it sits in directly), ranked among its siblings by
+* `order`, and `design/boards/_folders.json` says which folders exist, where they rank, and
+* which folder holds which (`parent`). Two levels: a folder holds boards and folders, a
+* folder inside a folder (a sub-folder) holds boards only. `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). */
+const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/;
+const isBoardName = (n) => typeof n === "string" && n.length >= 1 && n.length <= 64 && BOARD_NAME.test(n);
+/** The folder registry beside the boards - underscore = infrastructure, never a board. */
+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. */
+const isBoardFile = (f) => f.endsWith(".json") && isBoardName(f.slice(0, -5));
+const readDescription = (v) => {
+	if (typeof v !== "string") return void 0;
+	return v.trim().replace(/\s+/g, " ").slice(0, 300) || void 0;
+};
+const readTitle = (v) => {
+	if (typeof v !== "string") return void 0;
+	return Array.from(v.replace(/[\u0000-\u001f\u007f]/g, " ").trim().replace(/\s+/g, " ")).slice(0, 120).join("").trim() || void 0;
+};
+/** Title Case off a slug - the display when no title is set ("old-stuff" → "Old Stuff"). */
+const humanize = (s) => s.replace(/-/g, " ").replace(/(^|\s)\S/g, (c) => c.toUpperCase());
+const rank = (o) => typeof o === "number" && Number.isFinite(o) ? o : Infinity;
+/** A folder's title, description and type, present only when set. */
+const folderExtras = (it) => ({
+	...it.title ? { title: it.title } : {},
+	...it.description ? { description: it.description } : {},
+	...readType(it.type) ? { type: it.type } : {}
+});
+/** 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, or
+*  flattening a broken nesting, would let the next drag overwrite their folders), while a
+*  missing file is simply no folders. */
+function parseFolders(raw) {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return "expected an object";
+	const { version, folders } = raw;
+	if (version !== void 0 && version !== 1 && version !== 2) return `unsupported version ${String(version)}`;
+	if (!Array.isArray(folders)) return "expected a \"folders\" array";
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const f of folders) {
+		const name = f?.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.order;
+		const p = f.parent;
+		if (p !== void 0 && !isBoardName(p)) return `folder "${name}" has an invalid parent - a folder name`;
+		const t = readTitle(f.title);
+		const d = readDescription(f.description);
+		const ty = readType(f.type);
+		out.push({
+			name,
+			...typeof o === "number" && Number.isFinite(o) ? { order: o } : {},
+			...p !== void 0 ? { parent: p } : {},
+			...t ? { title: t } : {},
+			...d ? { description: d } : {},
+			...ty ? { type: ty } : {}
+		});
+	}
+	const byName = new Map(out.map((f) => [f.name, f]));
+	for (const f of out) {
+		if (f.parent === void 0) continue;
+		if (version !== 2) return `folder "${f.name}" names a parent - nested folders need "version": 2`;
+		if (f.parent === f.name) return `folder "${f.name}" cannot be its own parent`;
+		const p = byName.get(f.parent);
+		if (!p) return `folder "${f.name}" names an unknown parent "${f.parent}"`;
+		if (p.parent !== void 0) return `folder "${f.name}" would sit three levels deep - folders nest one level only`;
+	}
+	return out;
+}
+/** Sidebar order from the files. At every level the boards and folders there share one
+*  sequence, ranked by `order`, then kind (board before folder), then name; unranked sorts
+*  after ranked. The root holds root boards and top-level folders (registered without a
+*  parent, or implied by a board that names an unregistered folder); a top-level folder holds
+*  its boards and its sub-folders; a sub-folder holds its boards. A folder's title and
+*  description and type 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. */
+function buildTree(boards, folders) {
+	const reg = /* @__PURE__ */ new Map();
+	for (const f of folders) if (isBoardName(f.name) && !reg.has(f.name)) reg.set(f.name, f);
+	const parentOf = (n) => {
+		const p = reg.get(n)?.parent;
+		return p !== void 0 && p !== n && reg.has(p) && reg.get(p).parent === void 0 ? p : void 0;
+	};
+	const members = /* @__PURE__ */ new Map();
+	const implied = [];
+	const rootBoards = [];
+	for (const b of boards) {
+		if (!isBoardName(b.name) || b.name === "all-scenes") continue;
+		const folder = isBoardName(b.folder) ? b.folder : void 0;
+		if (!folder) {
+			rootBoards.push(b);
+			continue;
+		}
+		if (!reg.has(folder) && !implied.includes(folder)) implied.push(folder);
+		const list = members.get(folder) ?? [];
+		list.push(b);
+		members.set(folder, list);
+	}
+	const sorted = (xs) => xs.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)).map((r) => r.item);
+	const boardsHere = (name) => (name === null ? rootBoards : members.get(name) ?? []).map((b) => ({
+		item: {
+			kind: "board",
+			name: b.name
+		},
+		order: b.order
+	}));
+	const folder = (name, kids) => ({
+		item: {
+			kind: "folder",
+			name,
+			items: sorted(kids),
+			...folderExtras(reg.get(name) ?? {})
+		},
+		order: reg.get(name)?.order
+	});
+	const subsOf = (top) => [...reg.keys()].filter((n) => parentOf(n) === top);
+	const tops = [...[...reg.keys()].filter((n) => !parentOf(n)), ...implied];
+	return sorted([...boardsHere(null), ...tops.map((t) => folder(t, [...boardsHere(t), ...subsOf(t).map((s) => folder(s, boardsHere(s)))]))]);
+}
+/** Every board in reading order, depth-first - the order the switchers and the landing pick use. */
+function flatten(tree) {
+	const out = [];
+	const walk = (items) => {
+		for (const it of items) if (it.kind === "board") out.push(it.name);
+		else walk(it.items);
+	};
+	walk(tree);
+	return out;
+}
+const wireKids = (w) => w.items ?? w.boards ?? [];
+function validateWire(wire) {
+	if (!Array.isArray(wire)) return "invalid tree";
+	const boards = /* @__PURE__ */ new Set(), folders = /* @__PURE__ */ new Set();
+	const board = (n) => {
+		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;
+	};
+	const walk = (list, depth) => {
+		for (const w of list) {
+			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";
+			if (depth >= 2) return "folders nest one level only";
+			const { folder, items, boards: legacy, title, description, type } = w;
+			if (!isBoardName(folder)) return "invalid folder name in tree";
+			if (title !== void 0 && (typeof title !== "string" || Array.from(title).length > 120)) return "invalid folder title";
+			if (description !== void 0 && (typeof description !== "string" || description.length > 300)) return "invalid folder description";
+			if (type !== void 0 && !readType(type)) return "invalid folder type";
+			if (folders.has(folder)) return `folder "${folder}" appears twice`;
+			folders.add(folder);
+			const kids = items ?? legacy;
+			if (!Array.isArray(kids)) return "invalid folder in tree";
+			if (items === void 0 && kids.some((k) => typeof k !== "string")) return "invalid folder in tree";
+			const e = walk(kids, depth + 1);
+			if (e) return e;
+		}
+		return null;
+	};
+	const e = walk(wire, 0);
+	if (e) return e;
+	if (boards.size > 200 || folders.size > 50) return "tree too large";
+	return null;
+}
+/** Every folder with the folder it sits in (null = the root), top-level folders first in
+*  reading order, each followed by its sub-folders. */
+function folderEntries(t) {
+	const out = [];
+	for (const it of t) {
+		if (it.kind !== "folder") continue;
+		out.push({
+			folder: it,
+			parent: null
+		});
+		for (const k of it.items) if (k.kind === "folder") out.push({
+			folder: k,
+			parent: it.name
+		});
+	}
+	return out;
+}
+/** Every board's folder, in one pass - for callers that ask for many boards (folderOf walks the tree). */
+function folderMap(t) {
+	const out = /* @__PURE__ */ new Map();
+	for (const { folder } of folderEntries(t)) for (const k of folder.items) if (k.kind === "board") out.set(k.name, folder.name);
+	return out;
+}
+//#endregion
+//#region src/server/boards.ts
+/**
+* Reading design/boards/ safely - the one enumerator the dev API, the build and the tests
+* share. Only REGULAR files on the board-name grammar count as boards (a symlink, dangling or
+* live, could read or publish JSON from outside the project - it is skipped, and reported so
+* the build can fail closed). The folder registry is read the same way: absent = no folders,
+* malformed = an error the human must fix, never a silently empty registry.
+*/
+/** Does realpath(dir) stay inside realpath(root)? A symlinked design/boards can't escape. */
+function underRoot(root, dir) {
+	try {
+		const rr = realpathSync(root);
+		const rd = realpathSync(dir);
+		return rd === rr || rd.startsWith(rr + sep);
+	} catch {
+		return false;
+	}
+}
+/** Is design/boards a directory we may read and write? It must not be a symlink at all (a
+*  link to the repo root would list package.json as a board and let a tree write rewrite
+*  it; a link outside would publish foreign JSON) and must resolve inside the root. Absent
+*  is fine (no boards yet). Returns the error, or null. */
+function checkBoardsDir(root, boardsDir) {
+	return checkRealDirs(root, [[join(boardsDir, ".."), "design"], [boardsDir, "design/boards"]]);
+}
+/** Every EXISTING path in `dirs` (root-down order) must be a real directory inside the root -
+*  a symlinked `design` with no boards dir yet would otherwise be followed by the mkdir that
+*  creates it; a symlinked `design/scenes` would let a brief write land outside the project.
+*  An absent one ends the walk (nothing beneath it exists either). Returns the error, or null. */
+function checkRealDirs(root, dirs) {
+	for (const [p, label] of dirs) {
+		try {
+			if (lstatSync(p).isSymbolicLink()) return `${label} must be a real directory, not a symlink`;
+		} catch {
+			return null;
+		}
+		if (!underRoot(root, p)) return `${label} escapes the project`;
+	}
+	return null;
+}
+/** A regular file (lstat: a symlink is never followed, a dangling one is not "absent"). */
+const isRegularFile = (p) => {
+	try {
+		return lstatSync(p).isFile();
+	} catch {
+		return false;
+	}
+};
+/** Is there ANY node at p (a dangling symlink counts)? */
+const nodeExists = (p) => {
+	try {
+		lstatSync(p);
+		return true;
+	} catch {
+		return false;
+	}
+};
+/** Every board file: name, raw content, hash, and its JSON (null when malformed). `skipped`
+*  names the entries that looked like boards but were not regular files. */
+function listBoardFiles(boardsDir) {
+	const boards = [], skipped = [];
+	if (!existsSync(boardsDir)) return {
+		boards,
+		skipped
+	};
+	for (const f of readdirSync(boardsDir)) {
+		if (!isBoardFile(f)) continue;
+		const file = join(boardsDir, f);
+		if (!isRegularFile(file)) {
+			skipped.push(f);
+			continue;
+		}
+		const content = readFileSync(file, "utf8");
+		let json = null;
+		try {
+			json = JSON.parse(content);
+		} catch {}
+		boards.push({
+			name: f.slice(0, -5),
+			file,
+			content,
+			sha256: hash(content),
+			json
+		});
+	}
+	return {
+		boards,
+		skipped
+	};
+}
+function boardFields(json, validName) {
+	const o = json;
+	const title = readTitle(o?.title);
+	const description = readDescription(o?.description);
+	const type = readType(o?.type), capability = readCapability(o?.capability), status = readStatusWord(o?.status), reason = readReason(o?.reason);
+	return {
+		...typeof o?.order === "number" && Number.isFinite(o.order) ? { order: o.order } : {},
+		...validName(o?.folder) ? { folder: o.folder } : {},
+		...title ? { title } : {},
+		...description ? { description } : {},
+		...type ? { type } : {},
+		...capability ? { capability } : {},
+		...status ? { status } : {},
+		...reason ? { reason } : {}
+	};
+}
+/** The fields a board's file owns that the shell's save shape never carries: an autosave keeps
+*  each one from disk when the incoming board omits it (spec 20 - the fields survive every write). */
+const AUTHOR_FIELDS = [
+	"order",
+	"folder",
+	"title",
+	"description",
+	"type",
+	"capability",
+	"status",
+	"reason"
+];
+/** The folder registry. `sha256` is the CAS token a tree write must echo (null = "there was
+*  no file"), so a write can never silently replace a registry it never saw. */
+function readRegistry(boardsDir) {
+	const p = join(boardsDir, FOLDERS_FILE);
+	if (!nodeExists(p)) return {
+		state: "absent",
+		folders: [],
+		sha256: null
+	};
+	if (!isRegularFile(p)) return {
+		state: "malformed",
+		error: `design/boards/${FOLDERS_FILE} must be a regular file, not a symlink`,
+		sha256: null
+	};
+	const content = readFileSync(p, "utf8");
+	let raw;
+	try {
+		raw = JSON.parse(content);
+	} catch {
+		return {
+			state: "malformed",
+			error: `design/boards/${FOLDERS_FILE} is not valid JSON - fix the file`,
+			sha256: hash(content)
+		};
+	}
+	const parsed = parseFolders(raw);
+	if (typeof parsed === "string") return {
+		state: "malformed",
+		error: `design/boards/${FOLDERS_FILE}: ${parsed}`,
+		sha256: hash(content)
+	};
+	return {
+		state: "ok",
+		folders: parsed,
+		sha256: hash(content)
+	};
+}
+/** The registry's write lock - one writer at a time across processes (the dev server's tree write,
+*  `folders add`, `init --kind`), so a read-modify-write of `_folders.json` is atomic among Marver's
+*  writers. A lock older than 10 s is a crashed writer's and is taken over. `wait` = how long to
+*  try (the CLI waits; the dev server never blocks its event loop - it answers 409 instead). */
+const REGISTRY_LOCK = ".folders.lock";
+function withRegistryLock(dir, wait, fn) {
+	const lock = join(dir, REGISTRY_LOCK);
+	const t0 = Date.now();
+	for (;;) try {
+		writeFileSync(lock, `${process.pid} ${Date.now()}\n`, { flag: "wx" });
+		break;
+	} catch (e) {
+		if (e.code !== "EEXIST") throw e;
+		try {
+			if (Date.now() - lstatSync(lock).mtimeMs > 1e4) {
+				rmSync(lock, { force: true });
+				continue;
+			}
+		} catch {
+			continue;
+		}
+		if (Date.now() - t0 >= wait) return null;
+		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+	}
+	try {
+		return fn();
+	} finally {
+		rmSync(lock, { force: true });
+	}
+}
+/** Append typed folders to the registry (spec 20: `init --kind`, `folders add`). Never renames,
+*  moves or retypes a folder that exists - a name already registered is skipped and reported - and
+*  never drops a field of an existing entry it does not manage. New folders rank after everything
+*  already at the root. The write is compare-and-swap: the registry is re-read just before the
+*  atomic rename, and a change since the first read (the shell's drag, another agent) starts the
+*  append over from the new file. A malformed registry is an error, never overwritten. */
+function addFolders(root, folders) {
+	const dir = join(root, "design", "boards");
+	const de = checkBoardsDir(root, dir);
+	if (de) throw new Error(de);
+	mkdirSync(dir, { recursive: true });
+	const file = join(dir, FOLDERS_FILE);
+	const done = withRegistryLock(dir, 5e3, () => appendFolders(dir, file, folders));
+	if (!done) throw new Error(`design/boards/${FOLDERS_FILE} is being written by another process - try again`);
+	return done;
+}
+function appendFolders(dir, file, folders) {
+	for (let attempt = 0; attempt < 5; attempt++) {
+		const before = nodeExists(file) ? readFileSync(file, "utf8") : null;
+		const reg = readRegistry(dir);
+		if (reg.state === "malformed") throw new Error(reg.error);
+		let raw = [];
+		if (before !== null) {
+			const j = JSON.parse(before);
+			raw = Array.isArray(j.folders) ? j.folders : [];
+		}
+		const have = new Set(raw.map((f) => f.name));
+		const rootRanks = [...raw.filter((f) => f.parent === void 0).map((f) => f.order), ...listBoardFiles(dir).boards.map((b) => {
+			const o = b.json;
+			return o?.folder ? void 0 : o?.order;
+		})].filter((o) => typeof o === "number" && Number.isFinite(o));
+		let next = rootRanks.length ? Math.max(...rootRanks) + 1 : 0;
+		const added = [], existing = [];
+		const rows = [...raw];
+		for (const f of folders) {
+			if (have.has(f.name)) {
+				existing.push(f.name);
+				continue;
+			}
+			rows.push({
+				name: f.name,
+				order: next++,
+				...f.title ? { title: f.title } : {},
+				...f.type ? { type: f.type } : {}
+			});
+			have.add(f.name);
+			added.push(f.name);
+		}
+		if (!added.length) return {
+			added,
+			existing
+		};
+		const version = rows.some((f) => f.parent !== void 0) ? 2 : 1;
+		const tmp = `${file}.${process.pid}.${Date.now()}.${attempt}.tmp`;
+		writeFileSync(tmp, JSON.stringify({
+			version,
+			folders: rows
+		}, null, 2) + "\n", { flag: "wx" });
+		if ((nodeExists(file) ? readFileSync(file, "utf8") : null) !== before) {
+			rmSync(tmp, { force: true });
+			continue;
+		}
+		renameSync(tmp, file);
+		return {
+			added,
+			existing
+		};
+	}
+	throw new Error(`design/boards/${FOLDERS_FILE} kept changing while folders were added - try again`);
+}
+//#endregion
+//#region src/shared/context.ts
+const LEVEL = /`(confirmed|reported|unknown)`/g;
+/** What counts as a citation beside a level: a `path:line`, a run id, a cited file, or a link to a
+*  system of record (a deploy run's page). A cited file must also resolve - the check sees to it. */
+const CITATION = /`[^`\s]+:\d+(-\d+)?`|\bruns? \d{6,}(, \d{6,})*|`[^`\s]+\.(md|json|ts|tsx|js|mjs|yml|yaml|sql)`|\]\(https?:\/\/[^)\s]+\)/;
+/** A cited repository file inside a cell, with or without a line: `path/to/x.ts`, `CHANGELOG.md:12`. */
+const CITED_FILE = /`((?:\.{0,2}[\w@.-]+\/)*[\w@.$-]+\.(?:md|json|ts|tsx|js|jsx|mjs|yml|yaml|sql|txt))(?::(\d+)(?:-(\d+))?)?`/g;
+const readAudience = (v) => v === "publishable" || v === "restricted" ? v : "team";
+const AUDIENCE_RANK = {
+	publishable: 0,
+	team: 1,
+	restricted: 2
+};
+/** The strictest of several audiences - what a conclusion drawn from them may be shown to. */
+const strictest = (...a) => a.reduce((x, y) => AUDIENCE_RANK[y] > AUDIENCE_RANK[x] ? y : x, "publishable");
+/** Line endings normalized: every reader parses LF, so a CRLF file means the same thing. */
+const lf = (text) => text.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+/** The headers whose cells carry evidence in a shipped table. */
+const EVIDENCE_COLUMN = /^(evidence|verified|available|delivered)$/i;
+/** A Marver-managed file's first line (the playbooks Marver maintains) - front matter follows it. */
+const MANAGED_LINE = /^<!-- marver:managed [^\n]*-->\n/;
+function frontMatter(raw) {
+	const text = lf(raw);
+	const managed = MANAGED_LINE.exec(text);
+	if (managed) {
+		const r = frontMatter(text.slice(managed[0].length));
+		return {
+			...r,
+			offset: r.offset + 1
+		};
+	}
+	if (!text.startsWith("---\n")) return {
+		data: null,
+		body: text,
+		offset: 0
+	};
+	const m = text.match(/^---\n([\s\S]*?)\n---[ \t]*(\n|$)/);
+	if (!m) return {
+		data: null,
+		body: text,
+		offset: 0,
+		error: "front matter opens with --- and never closes"
+	};
+	const data = {};
+	let key = null;
+	for (const line of m[1].split("\n")) {
+		const item = line.match(/^\s+-\s+(.*)$/);
+		if (item && key) {
+			if (!Array.isArray(data[key])) data[key] = [];
+			data[key].push(scalar(item[1]));
+			continue;
+		}
+		const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+		if (!kv) continue;
+		key = kv[1];
+		data[key] = kv[2] === "" ? [] : value(kv[2]);
+	}
+	return {
+		data,
+		body: text.slice(m[0].length),
+		offset: m[0].split("\n").length - 1
+	};
+}
+function scalar(s) {
+	s = s.trim().replace(/\s+#.*$/, "");
+	if (/^".*"$|^'.*'$/.test(s)) return s.slice(1, -1);
+	return s;
+}
+function splitTop(s) {
+	const out = [];
+	let depth = 0, cur = "", q = null;
+	for (const ch of s) {
+		if (q) {
+			cur += ch;
+			if (ch === q) q = null;
+			continue;
+		}
+		if (ch === "\"" || ch === "'") {
+			q = ch;
+			cur += ch;
+			continue;
+		}
+		if (ch === "{" || ch === "[") depth++;
+		if (ch === "}" || ch === "]") depth--;
+		if (ch === "," && depth === 0) {
+			out.push(cur);
+			cur = "";
+			continue;
+		}
+		cur += ch;
+	}
+	if (cur.trim()) out.push(cur);
+	return out;
+}
+function value(s) {
+	s = s.trim().replace(/\s+#[^"'}\]]*$/, "");
+	if (s.startsWith("{") && s.endsWith("}")) {
+		const o = {};
+		for (const part of splitTop(s.slice(1, -1))) {
+			const i = part.indexOf(":");
+			if (i > 0) o[part.slice(0, i).trim()] = value(part.slice(i + 1));
+		}
+		return o;
+	}
+	if (s.startsWith("[") && s.endsWith("]")) return splitTop(s.slice(1, -1)).map((x) => value(x));
+	return scalar(s);
+}
+/** Lines outside fenced code blocks, with their 1-based numbers in the whole file. */
+function proseLines(text, offset = 0) {
+	const out = [];
+	let fenced = false;
+	lf(text).split("\n").forEach((line, i) => {
+		if (/^\s*```/.test(line)) {
+			fenced = !fenced;
+			return;
+		}
+		if (!fenced) out.push([i + 1 + offset, line]);
+	});
+	return out;
+}
+function tables(text) {
+	const out = [];
+	let cur = null;
+	for (const [n, line] of proseLines(text)) {
+		if (!/^\s*\|/.test(line)) {
+			cur = null;
+			continue;
+		}
+		if (/^\s*\|[\s|:-]+\|\s*$/.test(line)) continue;
+		const cells = splitRow(line);
+		if (!cur) {
+			cur = {
+				header: cells,
+				headerLine: n,
+				rows: []
+			};
+			out.push(cur);
+			continue;
+		}
+		cur.rows.push({
+			line: n,
+			cells
+		});
+	}
+	return out;
+}
+/** A table row's cells - pipes inside backticks stay in their cell. */
+function splitRow(line) {
+	const s = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+	const out = [];
+	let cur = "", code = false;
+	for (const ch of s) {
+		if (ch === "`") code = !code;
+		if (ch === "|" && !code) {
+			out.push(cur.trim());
+			cur = "";
+			continue;
+		}
+		cur += ch;
+	}
+	out.push(cur.trim());
+	return out;
+}
+const levelsIn = (cell) => [...cell.matchAll(LEVEL)].map((m) => m[1]);
+/** A table whose header row has no outer pipes - Markdown renders it, the readers here do not. The
+*  check rejects it rather than read past it. Returns the separator rows' line numbers. */
+function looseTables(text) {
+	return proseLines(text).filter(([, l]) => !/^\s*\|/.test(l) && /^\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$/.test(l)).map(([n]) => n);
+}
+/** The levels an availability cell grants, clause by clause (`;` separates them). A clause counts
+*  only when it claims availability: never one carrying a negation anywhere ("nowhere", "not
+*  available", "rolled back", "withdrawn") - and, for a product's Available cell, never one scoped to
+*  a pre-production place (staging, preview, sandbox) that does not also name production. A
+*  knowledge-work Delivered cell has no environments: only negations void it. */
+const NEGATION = /\b(nowhere|none|never|no longer|not (yet )?(available|live|deployed|delivered|on|in|shipped|released|out)|not yet|pending|planned|scheduled|upcoming|awaiting|withdrawn|rolled back|reverted|removed|retired|pulled)\b|^\s*not\b/i;
+/** The places a product is NOT yet available to its users, unless the clause also names production. */
+const PRE_PRODUCTION = /\b(staging|preview|sandbox|dev|development|local|locally|testing|test environment|qa)\b/i;
+function availableLevels(cell, kind = "available") {
+	const out = [];
+	for (const clause of cell.split(";")) {
+		const c = clause.replace(/\*\*/g, "").trim();
+		if (NEGATION.test(c)) continue;
+		if (kind === "available" && PRE_PRODUCTION.test(c) && !/\b(production|prod)\b/i.test(c)) continue;
+		out.push(...levelsIn(c));
+	}
+	return out;
+}
+const RECORD_KEY = /^(capability|project|deliverable)$/i;
+const RECORD_AVAILABLE = /^(available|delivered)$/i;
+const isRecordTable = (t) => RECORD_KEY.test(t.header[0] ?? "") && t.header.some((h) => RECORD_AVAILABLE.test(h));
+function shippedRows(text) {
+	const out = [];
+	for (const t of tables(text)) {
+		if (!isRecordTable(t)) continue;
+		const a = t.header.findIndex((h) => RECORD_AVAILABLE.test(h));
+		const kind = /^delivered$/i.test(t.header[a]) ? "delivered" : "available";
+		for (const r of t.rows) {
+			const slug = /`([a-z0-9][a-z0-9-]*)`/.exec(r.cells[0] ?? "")?.[1];
+			if (!slug) continue;
+			const available = r.cells[a] ?? "";
+			out.push({
+				capability: slug,
+				line: r.line,
+				available,
+				levels: availableLevels(available, kind)
+			});
+		}
+	}
+	return out;
+}
+/** Is this a glob the matcher reads? Balanced, unnested braces; no character classes. */
+const validGlob = (g) => {
+	if (typeof g !== "string" || !g || /[[\]]/.test(g)) return false;
+	let depth = 0;
+	for (const c of g) if (c === "{") {
+		if (++depth > 1) return false;
+	} else if (c === "}") {
+		if (--depth < 0) return false;
+	}
+	return depth === 0;
+};
+const hasGlob = (g) => /[*?{]/.test(g);
+/** A glob with **, *, ? and {a,b} as a RegExp over repo-relative paths (validGlob first). */
+function globRe(glob) {
+	let re = "", brace = 0;
+	for (let i = 0; i < glob.length; i++) {
+		const c = glob[i];
+		if (c === "*") {
+			if (glob[i + 1] === "*") {
+				i++;
+				if (glob[i + 1] === "/") {
+					i++;
+					re += "(?:[\\s\\S]*/)?";
+				} else re += "[\\s\\S]*";
+			} else re += "[^/]*";
+		} else if (c === "?") re += "[^/]";
+		else if (c === "{") {
+			brace++;
+			re += "(?:";
+		} else if (c === "}" && brace) {
+			brace--;
+			re += ")";
+		} else if (c === "," && brace) re += "|";
+		else re += c.replace(/[.+^$()|[\]\\]/g, "\\$&");
+	}
+	return new RegExp(`^${re}$`);
+}
+/** Read a map's text: the map, or what is wrong with it - every field checked, every glob valid. */
+function parseMap(text) {
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch {
+		return "context/map.json is not valid JSON";
+	}
+	const m = raw;
+	if (!m || typeof m !== "object" || !m.capabilities || typeof m.capabilities !== "object" || Array.isArray(m.capabilities)) return "context/map.json needs a \"capabilities\" object";
+	const globs = (where, v, required) => {
+		if (v === void 0 && !required) return null;
+		if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) return `context/map.json: ${where} must be a list of paths`;
+		const bad = v.findIndex((g) => !validGlob(g));
+		return bad >= 0 ? `context/map.json: ${where} has an invalid glob "${v[bad]}" (not empty; balanced, unnested {a,b}; no [...])` : null;
+	};
+	for (const [k, c] of Object.entries(m.capabilities)) {
+		if (!/^[a-z0-9][a-z0-9-]*$/.test(k)) return `context/map.json: "${k}" is not a capability slug`;
+		const cc = c;
+		if (!cc || typeof cc !== "object") return `context/map.json: "${k}" must be an object`;
+		const e = globs(`"${k}".paths`, cc.paths, true) ?? globs(`"${k}".tests`, cc.tests, false);
+		if (e) return e;
+		if (cc.contract !== void 0 && typeof cc.contract !== "string") return `context/map.json: "${k}".contract must be a path`;
+		if (cc.summary !== void 0 && typeof cc.summary !== "string") return `context/map.json: "${k}".summary must be text`;
+	}
+	if (m.excluded !== void 0) {
+		if (!Array.isArray(m.excluded)) return "context/map.json: \"excluded\" must be a list";
+		for (const x of m.excluded) {
+			const e = x;
+			if (!e || typeof e.path !== "string" || !validGlob(e.path)) return "context/map.json: every \"excluded\" entry needs a valid \"path\" glob";
+			if (typeof e.reason !== "string" || !e.reason.trim()) return `context/map.json: excluded "${e.path}" needs a "reason"`;
+		}
+	}
+	{
+		const e = globs("\"source\"", m.source, false);
+		if (e) return e;
+	}
+	const source = Array.isArray(m.source) ? m.source.filter((x) => typeof x === "string") : void 0;
+	return {
+		capabilities: m.capabilities,
+		excluded: Array.isArray(m.excluded) ? m.excluded : [],
+		...source ? { source } : {}
+	};
+}
+/** The index's generated capability table, between `<!-- generated ... -->` fences. */
+const GENERATED = /<!-- generated[^>]*-->([\s\S]*?)<!-- \/generated -->/;
+/** The table the index generates from the map: one row per capability, its contract linked. */
+function capabilityTable(map) {
+	return [
+		"| Capability | Contract |",
+		"|---|---|",
+		...Object.entries(map.capabilities).map(([k, c]) => {
+			const name = `\`${k}\`${typeof c.summary === "string" && c.summary.trim() ? ` - ${c.summary.trim().replace(/\|/g, "/")}` : ""}`;
+			const rel = c.contract?.replace(/^context\//, "");
+			return rel ? `| ${name} | [\`${rel}\`](${rel}) |` : `| ${name} | none yet - see the map |`;
+		})
+	].join("\n");
+}
+/** Words in a document's body (front matter excluded) - the index's budget counts these. */
+const wordCount = (text) => frontMatter(text).body.split(/\s+/).filter(Boolean).length;
+//#endregion
+//#region src/shared/status.ts
+/**
+* Status (spec 20) - one resolver, shared by the dev server and the build: files in, a status and
+* its evidence out, pure. Feature and project boards wear it; read top to bottom, the first row
+* that matches wins:
+*
+*   1-3  the board says archived, paused or blocked (with its reason)   - a decision, by hand
+*   4    the evidence it needs cannot be read                           - Unknown, never a stale Done
+*   5    an open plan names the capability                              - In progress, filling by phase
+*   6    the shipped record shows it available, `confirmed`             - Done
+*   7    ... `reported` only                                            - Done, reported
+*   8    an accepted contract (`state: current`), no availability       - To do
+*   9    anything else                                                  - Backlog
+*
+* Without `context/`, a board may also say in-progress, todo or backlog by hand. Done is never
+* set by hand: `"status": "done"` is ignored here and reported by `marver context check`.
+*/
+const STATUS_LABEL = {
+	archived: "Archived",
+	paused: "Paused",
+	blocked: "Blocked",
+	unknown: "Unknown",
+	"in-progress": "In progress",
+	done: "Done",
+	"done-reported": "Done, reported",
+	todo: "To do",
+	backlog: "Backlog"
+};
+const PHASE_LABEL = {
+	1: "spec",
+	2: "lo-fi",
+	3: "hi-fi"
+};
+const NO_CONTEXT = {
+	present: false,
+	unreadable: /* @__PURE__ */ new Map(),
+	shipped: /* @__PURE__ */ new Map(),
+	contracts: /* @__PURE__ */ new Map(),
+	plans: /* @__PURE__ */ new Map()
+};
+const PHASE_WORDS = {
+	spec: 1,
+	specs: 1,
+	lofi: 2,
+	"lo-fi": 2,
+	hifi: 3,
+	"hi-fi": 3
+};
+/** The deciding phase and where it came from - a brief's phase carries that brief's audience. */
+function phaseSource(capability, scenes) {
+	let best;
+	for (const s of scenes) {
+		const declared = s.phase ? PHASE_WORDS[s.phase.toLowerCase()] : void 0;
+		const named = s.name === `${capability}-specs` || s.name === `${capability}-spec` ? 1 : s.name === `${capability}-lofi` ? 2 : s.name === capability ? 3 : void 0;
+		const p = declared ?? named;
+		if (p && (!best || p > best.phase)) best = {
+			phase: p,
+			scene: s.name,
+			fromBrief: !!declared,
+			audience: declared ? s.audience ?? "team" : "publishable"
+		};
+	}
+	return best;
+}
+/** A board's status, or null when its type carries none. */
+function resolveStatus(b, ctx) {
+	if (!HAS_STATUS.includes(b.type)) return null;
+	const capability = b.capability ?? b.name;
+	const out = (status, row, evidence, audience, extra = {}) => ({
+		status,
+		row,
+		capability,
+		evidence,
+		audience,
+		...extra
+	});
+	if (b.status && DECISIONS.includes(b.status)) {
+		const by = `design/boards/${b.name}.json: "status": "${b.status}"`;
+		return out(b.status, DECISIONS.indexOf(b.status) + 1, [by], "team", b.status === "blocked" && b.reason ? { reason: b.reason } : {});
+	}
+	if (!ctx.present) {
+		if (b.status === "in-progress") {
+			const f = fillOf(capability, b.scenes);
+			return out("in-progress", 5, [`design/boards/${b.name}.json: by hand`, ...f.evidence], strictest("publishable", ...f.audience), f.fill);
+		}
+		if (b.status === "todo") return out("todo", 8, [`design/boards/${b.name}.json: by hand`], "publishable");
+		return out("backlog", 9, [b.status === "backlog" ? `design/boards/${b.name}.json: by hand` : "no context/ - nothing records it"], "publishable");
+	}
+	const bad = ctx.unreadable.get("*") ?? ctx.unreadable.get(capability);
+	if (bad) return out("unknown", 4, [bad], "team");
+	const row = ctx.shipped.get(capability);
+	const live = row?.levels.includes("confirmed") ? "confirmed" : row?.levels.includes("reported") ? "reported" : null;
+	const plans = ctx.plans.get(capability);
+	if (plans?.length) {
+		const f = fillOf(capability, b.scenes);
+		const ev = [...plans.map((p) => `${p.where}: an open plan`), ...f.evidence];
+		if (live && row) ev.push(`${row.where}: available, \`${live}\` - this is the next version`);
+		return out("in-progress", 5, ev, strictest(...plans.map((p) => p.audience), ...f.audience, ...live && row ? [row.audience] : []), f.fill);
+	}
+	if (live === "confirmed") return out("done", 6, [`${row.where}: available, \`confirmed\``], row.audience);
+	if (live === "reported") return out("done-reported", 7, [`${row.where}: available, \`reported\` only`], row.audience);
+	const c = ctx.contracts.get(capability);
+	if (c?.state === "current") return out("todo", 8, [`${c.where}: state current, nothing available yet`], strictest(c.audience, ...row ? [row.audience] : []));
+	return out("backlog", 9, [c ? `${c.where}: state ${c.state}` : `no contract for ${capability}`], c ? c.audience : "publishable");
+}
+/** The fill, the line that says where it came from, and the audience of that source. */
+const fillOf = (capability, scenes) => {
+	const src = phaseSource(capability, scenes);
+	if (!src) return {
+		fill: {},
+		evidence: [],
+		audience: []
+	};
+	const where = src.fromBrief ? `design/scenes/${src.scene}/_brief.md: phase ${PHASE_LABEL[src.phase]}` : `design/scenes/${src.scene}: the ${PHASE_LABEL[src.phase]} scene`;
+	return {
+		fill: { fill: src.phase },
+		evidence: [where],
+		audience: [src.audience]
+	};
+};
+/** What a published canvas may show of a status (spec 20, Publishing status): rows 5-9 only, drawn
+*  from `publishable` evidence only, and never a reason, a record path or other evidence. */
+function publishableStatus(r) {
+	if (!r || !PUBLISHABLE.has(r.status) || r.audience !== "publishable") return null;
+	return {
+		status: r.status,
+		...r.fill ? { fill: r.fill } : {}
+	};
+}
+/** The statuses rows 5-9 produce - the only ones a published canvas may show. */
+const PUBLISHABLE = /* @__PURE__ */ new Set([
+	"in-progress",
+	"done",
+	"done-reported",
+	"todo",
+	"backlog"
+]);
+//#endregion
+//#region src/server/board-status.ts
+/**
+* Every board's type and status, read off the files (spec 20) - for the dev API's board list, the
+* manifest and the build. The rules live in shared/board-types.ts and shared/status.ts; this module
+* only reads: `context/` (the shipped record, the contracts, the plans, each with its audience), the
+* boards and their folders, and the briefs of the scenes a status board shows. Errors never throw:
+* evidence that cannot be read is a fact the resolver turns into Unknown - never a stale Done.
+*
+* The sidebar re-reads on every `sh:boards` and every poll, so the facts are cached by the files'
+* signature (names, sizes, mtimes) and a pass reads each scene brief once.
+*/
+const isDir = (p) => {
+	try {
+		return lstatSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+};
+/** Plan states that mean the plan is no longer open. */
+const CLOSED_PLAN = /* @__PURE__ */ new Set([
+	"historical",
+	"done",
+	"landed",
+	"declined",
+	"closed",
+	"superseded"
+]);
+const CONTRACT_STATES = /* @__PURE__ */ new Set([
+	"current",
+	"proposed",
+	"historical"
+]);
+/** The markdown files of a context sub-directory - or the error that kept them from being read. */
+function mdIn(dir) {
+	if (!isDir(dir)) return { files: [] };
+	try {
+		return { files: readdirSync(dir).filter((f) => f.endsWith(".md") && !f.startsWith(".")).sort() };
+	} catch (e) {
+		return {
+			files: [],
+			error: e.message
+		};
+	}
+}
+/** What decides the facts: every file they are read from, by size and mtime. */
+function signature(dir) {
+	const parts = [];
+	const stamp = (p) => {
+		try {
+			const s = statSync(p);
+			parts.push(`${p}:${s.size}:${s.mtimeMs}:${s.ctimeMs}:${s.mode}`);
+		} catch {
+			parts.push(`${p}:-`);
+		}
+	};
+	stamp(join(dir, "shipped.md"));
+	for (const sub of ["product", "plans"]) {
+		const d = join(dir, sub);
+		stamp(d);
+		for (const f of mdIn(d).files) stamp(join(d, f));
+	}
+	return parts.join("|");
+}
+const cache = /* @__PURE__ */ new Map();
+/** What `context/` says, for the resolver - cached until a file it reads changes. */
+function readContextFacts(root) {
+	const dir = join(root, "context");
+	if (!isDir(dir)) return NO_CONTEXT;
+	const sig = signature(dir);
+	const hit = cache.get(root);
+	if (hit && hit.sig === sig) return hit.facts;
+	const facts = readFresh(dir);
+	cache.set(root, {
+		sig,
+		facts
+	});
+	return facts;
+}
+function readFresh(dir) {
+	const facts = {
+		present: true,
+		unreadable: /* @__PURE__ */ new Map(),
+		shipped: /* @__PURE__ */ new Map(),
+		contracts: /* @__PURE__ */ new Map(),
+		plans: /* @__PURE__ */ new Map()
+	};
+	const shippedFile = join(dir, "shipped.md");
+	let text = null;
+	try {
+		text = readFileSync(shippedFile, "utf8");
+	} catch (e) {
+		if (e.code !== "ENOENT") facts.unreadable.set("*", `context/shipped.md: ${e.message}`);
+	}
+	if (text !== null) {
+		const fm = frontMatter(text);
+		if (fm.error) facts.unreadable.set("*", `context/shipped.md: ${fm.error}`);
+		else if (!tables(text).some(isRecordTable)) facts.unreadable.set("*", "context/shipped.md: no Capability table with an Available column");
+		else {
+			const audience = readAudience(fm.data?.audience);
+			for (const r of shippedRows(text)) facts.shipped.set(r.capability, {
+				levels: r.levels,
+				where: `context/shipped.md:${r.line}`,
+				audience
+			});
+		}
+	}
+	const product = mdIn(join(dir, "product"));
+	if (product.error) facts.unreadable.set("*", `context/product/: ${product.error}`);
+	for (const f of product.files) {
+		const where = `context/product/${f}`;
+		const slug = f.slice(0, -3);
+		try {
+			const fm = frontMatter(readFileSync(join(dir, "product", f), "utf8"));
+			if (fm.error || !fm.data) {
+				facts.unreadable.set(slug, `${where}: ${fm.error ?? "no front matter"}`);
+				continue;
+			}
+			const cap = readCapability(fm.data.capability) ?? slug;
+			const state = typeof fm.data.state === "string" ? fm.data.state : "";
+			if (!CONTRACT_STATES.has(state)) {
+				facts.unreadable.set(cap, `${where}: state "${state}" is not current, proposed or historical`);
+				continue;
+			}
+			facts.contracts.set(cap, {
+				state,
+				where,
+				audience: readAudience(fm.data.audience)
+			});
+		} catch (e) {
+			facts.unreadable.set(slug, `${where}: ${e.message}`);
+		}
+	}
+	const plans = mdIn(join(dir, "plans"));
+	if (plans.error) facts.unreadable.set("*", `context/plans/: ${plans.error}`);
+	for (const f of plans.files) {
+		const where = `context/plans/${f}`;
+		f.slice(0, -3);
+		try {
+			const fm = frontMatter(readFileSync(join(dir, "plans", f), "utf8"));
+			if (fm.error || !fm.data) {
+				facts.unreadable.set("*", `${where}: ${fm.error ?? "no front matter"}`);
+				continue;
+			}
+			if (typeof fm.data.state === "string" && CLOSED_PLAN.has(fm.data.state)) continue;
+			const list = (v) => Array.isArray(v) ? v : v === void 0 ? [] : [v];
+			const caps = [...list(fm.data.capability), ...list(fm.data.capabilities)].map(readCapability).filter((c) => !!c);
+			const audience = readAudience(fm.data.audience);
+			for (const c of caps) facts.plans.set(c, [...facts.plans.get(c) ?? [], {
+				where,
+				audience
+			}]);
+		} catch (e) {
+			facts.unreadable.set("*", `${where}: ${e.message}`);
+		}
+	}
+	return facts;
+}
+/** The scenes a board shows: its layout rows, and the scene of every frame it pins. */
+function boardScenes(json) {
+	const o = json;
+	const out = /* @__PURE__ */ new Set();
+	const rows = o?.layout?.rows;
+	if (Array.isArray(rows)) {
+		for (const r of rows) if (Array.isArray(r)) {
+			for (const s of r) if (typeof s === "string") out.add(s);
+		}
+	}
+	if (Array.isArray(o?.nodes)) for (const n of o.nodes) {
+		const f = n?.frame;
+		if (typeof f === "string" && f.includes("/")) out.add(f.split("/")[0]);
+	}
+	return [...out];
+}
+const SCENE = /^[a-z0-9][a-z0-9-]*$/;
+/** A scene as the fill reads it: does it hold a frame yet (a phase counts only once it does - a
+*  feature's starting layout names its three phase scenes before any frame exists), and the
+*  `phase` its brief declares. */
+function readScene(root, scene) {
+	if (!SCENE.test(scene)) return { frames: false };
+	const dir = join(root, "design", "scenes", scene);
+	let frames = false;
+	try {
+		frames = readdirSync(dir).some((f) => /\.(tsx|jsx|html)$/.test(f) && !f.startsWith("_"));
+	} catch {}
+	let phase;
+	let audience;
+	try {
+		const fm = frontMatter(readFileSync(join(dir, "_brief.md"), "utf8"));
+		if (typeof fm.data?.phase === "string") {
+			phase = fm.data.phase;
+			audience = fm.data.audience === void 0 ? "publishable" : readAudience(fm.data.audience);
+		}
+	} catch {}
+	return {
+		frames,
+		...phase ? {
+			phase,
+			audience
+		} : {}
+	};
+}
+/** Every board's resolved type and status. `boards` are the board files' names and JSON; `folders`
+*  the registry rows; `folderOf` the folder each board sits in directly (the tree's answer). */
+function annotateBoards(root, boards, folders, folderOf, facts = readContextFacts(root)) {
+	const byName = new Map(folders.map((f) => [f.name, f]));
+	const scenes = /* @__PURE__ */ new Map();
+	const scene = (s) => {
+		let v = scenes.get(s);
+		if (!v) {
+			v = readScene(root, s);
+			scenes.set(s, v);
+		}
+		return v;
+	};
+	const out = /* @__PURE__ */ new Map();
+	for (const b of boards) {
+		const o = b.json ?? {};
+		const f = folderOf(b.name);
+		const folder = f ? byName.get(f) : void 0;
+		const parent = folder?.parent ? byName.get(folder.parent) : void 0;
+		const type = resolveType(o.type, folder?.type, parent?.type);
+		if (!HAS_STATUS.includes(type)) {
+			out.set(b.name, {
+				type,
+				status: null
+			});
+			continue;
+		}
+		const shown = boardScenes(b.json).flatMap((name) => {
+			const sc = scene(name);
+			return sc.frames ? [{
+				name,
+				...sc.phase ? {
+					phase: sc.phase,
+					audience: sc.audience
+				} : {}
+			}] : [];
+		});
+		const status = resolveStatus({
+			name: b.name,
+			type,
+			capability: readCapability(o.capability),
+			status: readStatusWord(o.status),
+			reason: readReason(o.reason),
+			scenes: shown
+		}, facts);
+		out.set(b.name, {
+			type,
+			status
+		});
+	}
+	return out;
+}
+//#endregion
+export { readCapability as $, isRegularFile as A, folderMap as B, tables as C, boardFields as D, addFolders as E, BOARD_NAME as F, validateWire as G, isBoardName as H, FOLDERS_FILE as I, FOLDER_MODULES as J, wireKids as K, buildTree as L, nodeExists as M, readRegistry as N, checkBoardsDir as O, withRegistryLock as P, knownType as Q, flatten as R, proseLines as S, AUTHOR_FIELDS as T, readDescription as U, humanize as V, readTitle as W, KIND_FOLDERS as X, HAS_STATUS as Y, PROPOSED_PUBLISH as Z, isRecordTable as _, STATUS_LABEL as a, hash as at, looseTables as b, CITED_FILE as c, LEVEL as d, readReason as et, availableLevels as f, hasGlob as g, globRe as h, PUBLISHABLE as i, settableStatuses as it, listBoardFiles as j, checkRealDirs as k, EVIDENCE_COLUMN as l, frontMatter as m, readContextFacts as n, readType as nt, publishableStatus as o, capabilityTable as p, BOARD_TYPES as q, PHASE_LABEL as r, resolveType as rt, CITATION as s, annotateBoards as t, readStatusWord as tt, GENERATED as u, levelsIn as v, wordCount as w, parseMap as x, lf as y, folderEntries as z };