fundus 0.0.2

package/dist/cli.js

@@ -0,0 +1,1420 @@
+#!/usr/bin/env node
+import { b as serverPluginForType, t as FundusOperations, w as loadConfig, y as pluginsByType } from "./operations-DYM-5KVl.js";
+import { n as formatCheckFinding, r as runCheck, t as runBuild } from "./build-CZYFLLvl.js";
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { MANIFEST_COLORS, MANIFEST_EMOJIS, compareCodeUnits, folderNameOf, manifestEmojiError, parentFolderPath, proposeAssetId, resolveManifestColor, typesForFileName } from "#fundus/core";
+//#region src/cli-io.ts
+/**
+* Terminal I/O for the fundus CLI (M7): hand-rolled flag parsing, the JSON
+* output envelope, and the expected-error type — no CLI framework. The output
+* contract agents rely on: with `--json`, stdout carries exactly one JSON
+* document ({"ok": true, ...} on success, {"error": {"message": ...}} on an
+* expected failure); without it, errors go to stderr. Exit codes: 0 success,
+* 1 expected error, 2 unexpected crash (see cli.ts).
+*/
+/**
+* A wrong invocation (unknown flag/subcommand, missing positional, malformed
+* flag value): an expected error whose message points at the right `--help`.
+*/
+var CliUsageError = class extends Error {};
+/**
+* Parse a command's argument list against its flag definitions. Supports
+* `--flag value` and `--flag=value`; anything not starting with `--` is a
+* positional. Unknown flags and missing values throw a `CliUsageError` that
+* names the command's `--help`.
+*/
+function parseArguments(argumentList, flagDefinitions, commandPath) {
+	const positionals = [];
+	const flags = {};
+	for (let index = 0; index < argumentList.length; index++) {
+		const argument = argumentList[index];
+		if (!argument.startsWith("--")) {
+			positionals.push(argument);
+			continue;
+		}
+		const equalsIndex = argument.indexOf("=");
+		const name = equalsIndex === -1 ? argument.slice(2) : argument.slice(2, equalsIndex);
+		const definition = flagDefinitions[name];
+		if (!definition) throw new CliUsageError(`Unknown flag "--${name}" for \`${commandPath}\` — run \`${commandPath} --help\`.`);
+		if (!definition.takesValue) {
+			if (equalsIndex !== -1) throw new CliUsageError(`Flag "--${name}" takes no value.`);
+			flags[name] = true;
+			continue;
+		}
+		if (equalsIndex !== -1) {
+			flags[name] = argument.slice(equalsIndex + 1);
+			continue;
+		}
+		const value = argumentList[index + 1];
+		if (value === void 0) throw new CliUsageError(`Flag "--${name}" needs a value — run \`${commandPath} --help\`.`);
+		flags[name] = value;
+		index++;
+	}
+	return {
+		positionals,
+		flags
+	};
+}
+/**
+* Enforce a command's exact positional shape. `names` are the placeholders
+* from the synopsis (e.g. ["<id>", "<newId>"]); the mismatch message repeats
+* the expected usage.
+*/
+function requirePositionals(parsed, names, commandPath) {
+	if (parsed.positionals.length !== names.length) {
+		const usage = names.length === 0 ? commandPath : `${commandPath} ${names.join(" ")}`;
+		throw new CliUsageError(`\`${commandPath}\` expects ${names.length} argument(s) (usage: ${usage}) — got ${parsed.positionals.length}. Run \`${commandPath} --help\`.`);
+	}
+	return parsed.positionals;
+}
+/** The single JSON document a `--json` invocation writes to stdout. */
+function printJsonDocument(document) {
+	console.log(JSON.stringify(document, null, "	"));
+}
+/** Parse a JSON-valued flag (`--parameters`), mapping bad JSON to a usage error. */
+function parseJsonFlag(name, value) {
+	try {
+		return JSON.parse(value);
+	} catch (cause) {
+		throw new CliUsageError(`Flag "--${name}" is not valid JSON (${cause instanceof Error ? cause.message : String(cause)}). Pass a single JSON value, e.g. --${name} '{"preset": "default"}'.`);
+	}
+}
+/**
+* Parse a `--manifests a,b` list: comma-separated names, whitespace-tolerant.
+* The empty string is the explicit "no manifests" — it clears the membership.
+*/
+function parseManifestList(value) {
+	return value.split(",").map((name) => name.trim()).filter((name) => name.length > 0);
+}
+/** Human-readable byte count for terminal output (1024-based, one decimal). */
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = [
+		"KiB",
+		"MiB",
+		"GiB"
+	];
+	let value = bytes;
+	let unitIndex = -1;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex++;
+	}
+	return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+//#endregion
+//#region src/cli-init.ts
+const FUNDUS_CONFIG_TEMPLATE = `import { defineConfig } from 'fundus/config';
+
+export default defineConfig({
+	rawDir: './assets/raw',
+	proxyDir: './static/fundus',
+	proxyBasePath: '/fundus/',
+	library: './assets/fundus.library.json',
+	manifestsDir: './src/lib/fundus'
+});
+`;
+const INIT_HELP = `fundus init — create a Fundus configuration file
+
+Usage: fundus init [--json]
+
+Creates a template fundus.config.ts in the current directory. The command
+refuses to overwrite an existing configuration file.
+
+Flags:
+  --json   print {"ok": true, "path": "fundus.config.ts"} on stdout
+  --help   this help
+
+Example:
+  cd my-host-app && npx fundus init
+`;
+async function runInitCommand(argumentList) {
+	if (argumentList.includes("--help")) {
+		console.log(INIT_HELP);
+		return;
+	}
+	const parsed = parseArguments(argumentList, {
+		json: { takesValue: false },
+		help: { takesValue: false }
+	}, "fundus init");
+	requirePositionals(parsed, [], "fundus init");
+	const configPath = resolve(process.cwd(), "fundus.config.ts");
+	try {
+		await writeFile(configPath, FUNDUS_CONFIG_TEMPLATE, {
+			encoding: "utf8",
+			flag: "wx"
+		});
+	} catch (cause) {
+		if (cause.code === "EEXIST") throw new Error(`fundus.config.ts already exists in ${process.cwd()}.`);
+		throw new Error(`Cannot create fundus.config.ts: ${cause instanceof Error ? cause.message : String(cause)}`);
+	}
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			path: "fundus.config.ts"
+		});
+		return;
+	}
+	console.log("Created fundus.config.ts.");
+}
+//#endregion
+//#region src/cli-commands.ts
+/**
+* The state/asset/folder/manifest command groups of the fundus CLI (M7): thin
+* terminal adapters over the one operations layer (operations.ts) — the same
+* class the REST server exposes to the editor, so every mutation runs the
+* editor's autosave chain (write library → process affected assets →
+* regenerate manifest modules). Every command supports `--json` (a single
+* JSON document on stdout, nothing else there) and `--help`; expected
+* failures throw and cli.ts maps them to exit code 1.
+*/
+const COMMON_FLAGS = {
+	json: { takesValue: false },
+	help: { takesValue: false }
+};
+function hasHelpFlag(argumentList) {
+	return argumentList.includes("--help");
+}
+async function createOperations() {
+	return new FundusOperations(await loadConfig(process.cwd()));
+}
+function manifestRows(state) {
+	return Object.keys(state.library.manifests).sort(compareCodeUnits).map((name) => ({
+		name,
+		color: state.library.manifests[name]?.color ?? null,
+		emoji: state.library.manifests[name]?.emoji ?? null,
+		explicitMemberIds: state.manifestMemberships[name]?.explicitMemberIds ?? [],
+		passiveMembers: state.manifestMemberships[name]?.passiveMembers ?? [],
+		deliveredBytes: state.manifestDeliveredBytes[name] ?? 0
+	}));
+}
+/** A manifest's `emoji name` prefix for human output (emoji only when set). */
+function manifestLabel(row) {
+	return row.emoji ? `${row.emoji} ${row.name}` : row.name;
+}
+function assetById(state, id) {
+	const asset = state.assets.find((candidate) => candidate.id === id);
+	if (!asset) throw new Error(`Unknown asset "${id}".`);
+	return asset;
+}
+function membershipSummary(asset) {
+	const parts = [];
+	if (asset.manifests.length > 0) parts.push(asset.manifests.join(","));
+	if (asset.passiveManifests.length > 0) parts.push(`passive: ${asset.passiveManifests.map((membership) => membership.manifest).join(",")}`);
+	return parts.length > 0 ? parts.join(" + ") : "(no manifest)";
+}
+function printAssetLines(assets, indent = "") {
+	const idWidth = Math.max(0, ...assets.map((asset) => asset.id.length));
+	const typeWidth = Math.max(0, ...assets.map((asset) => asset.type.length));
+	for (const asset of assets) {
+		const warningSuffix = asset.warnings.length > 0 ? `  ⚠ ${asset.warnings.length} warning(s)` : "";
+		console.log(`${indent}${asset.id.padEnd(idWidth)}  ${asset.type.padEnd(typeWidth)}  ${membershipSummary(asset)}${warningSuffix}`);
+	}
+}
+function printIssues(issues) {
+	if (issues.length === 0) return;
+	console.log("Issues:");
+	for (const issue of issues) console.log(`  - ${issue.assetId ? `[${issue.assetId}] ` : ""}${issue.message}`);
+}
+function printHumanState(state) {
+	const rows = manifestRows(state);
+	console.log(`${state.assets.length} asset(s), ${state.library.folders.length} folder(s), ${rows.length} manifest(s)`);
+	if (rows.length > 0) {
+		console.log("");
+		console.log("Manifests:");
+		const labels = rows.map(manifestLabel);
+		const nameWidth = Math.max(0, ...labels.map((label) => label.length));
+		rows.forEach((row, index) => {
+			console.log(`  ${labels[index].padEnd(nameWidth)}  ${row.explicitMemberIds.length} explicit + ${row.passiveMembers.length} passive member(s), ${formatBytes(row.deliveredBytes)} delivered`);
+		});
+	}
+	if (state.assets.length > 0) {
+		console.log("");
+		console.log("Assets:");
+		printAssetLines(state.assets, "  ");
+	}
+	const warningTotal = state.assets.reduce((sum, asset) => sum + asset.warnings.length, 0);
+	if (warningTotal > 0) {
+		console.log("");
+		console.log(`⚠ ${warningTotal} warning(s) — see \`fundus asset list --warnings-only\`.`);
+	}
+	if (state.issues.length > 0) {
+		console.log("");
+		printIssues(state.issues);
+	}
+}
+function printHumanAssetDetail(asset) {
+	console.log(`${asset.id} (${asset.type})`);
+	console.log(`  raw:        ${asset.raw}`);
+	console.log(`  folder:     ${asset.folder || "root"}`);
+	console.log(`  rawHash:    ${asset.rawHash}`);
+	console.log(`  manifests:  ${asset.manifests.length > 0 ? asset.manifests.join(", ") : "(none)"}`);
+	for (const membership of asset.passiveManifests) console.log(`  passive:    ${membership.manifest} (via ${membership.via.join(", ")})`);
+	if (asset.proxy) {
+		const dimensions = asset.proxy.width !== void 0 && asset.proxy.height !== void 0 ? `, ${asset.proxy.width}×${asset.proxy.height}` : "";
+		const duration = asset.proxy.durationMs !== void 0 ? `, ${asset.proxy.durationMs} ms` : "";
+		console.log(`  proxy:      ${asset.proxy.relativePath} (${formatBytes(asset.proxy.fileSize)}${dimensions}${duration})`);
+	} else console.log("  proxy:      (none — not delivered or not processed yet)");
+	for (const reference of asset.references.outgoing) console.log(`  reference:  ${reference.field} → ${reference.assetId}`);
+	for (const reference of asset.references.incoming) console.log(`  referenced: ← ${reference.assetId} (${reference.field})`);
+	console.log("  parameters:");
+	const parametersJson = JSON.stringify(asset.parameters, null, "	");
+	for (const line of parametersJson.split("\n")) console.log(`    ${line}`);
+	for (const warning of asset.warnings) console.log(`  ⚠ ${warning}`);
+}
+/** Human output of a successful mutation: headline, asset warnings, issues. */
+function printMutationResult(headline, asset, state) {
+	console.log(headline);
+	if (asset) for (const warning of asset.warnings) console.log(`  ⚠ ${warning}`);
+	printIssues(state.issues);
+}
+const STATE_HELP = `fundus state — the full project state in one document
+
+Usage: fundus state [--json]
+
+The agent's one-stop overview: every asset (type, raw file, parameters,
+explicit + passive manifest memberships, proxy status, reference edges,
+warnings), every manifest (members, delivered bytes), library-level
+validation issues, and the available preset names per asset type.
+
+Flags:
+  --json   print {"ok": true, "state": <FundusStateDto>} on stdout
+  --help   this help
+
+Read-only: nothing is processed or written.
+
+Example:
+  fundus state --json | jq '.state.assets[].id'
+`;
+async function runStateCommand(argumentList) {
+	if (hasHelpFlag(argumentList)) {
+		console.log(STATE_HELP);
+		return;
+	}
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus state");
+	requirePositionals(parsed, [], "fundus state");
+	const state = await (await createOperations()).state();
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			state
+		});
+		return;
+	}
+	printHumanState(state);
+}
+const ASSET_HELP = `fundus asset — inspect and mutate assets
+
+Usage: fundus asset <subcommand> …
+
+Every mutation runs the full editor autosave chain: write library →
+process affected assets → regenerate manifest modules. There is no
+separate apply/sync step. All subcommands accept --json (a single JSON
+document on stdout) and --help.
+
+Subcommands:
+  list      list assets (--manifest, --type, --warnings-only)
+  show      one asset in detail
+  ingest    copy a file into the raw dir as a typed asset
+  set       merge parameters and/or replace manifest membership
+  rename    rename an asset id
+  move      move an asset to a folder or root
+  delete    delete an asset (record, raw file, proxies)
+
+Run \`fundus asset <subcommand> --help\` for the focused page (flags,
+semantics, an example) — e.g. \`fundus asset set --help\` documents the
+--parameters merge rules.
+`;
+const ASSET_SUBCOMMAND_HELP = {
+	list: `fundus asset list — list assets, optionally filtered
+
+Usage: fundus asset list [--manifest <name>] [--type <type>] [--warnings-only] [--json]
+
+One line per asset: id, type, manifest memberships (explicit +
+passive), warning count.
+
+Flags:
+  --manifest <name>   only members of this manifest (explicit or passive)
+  --type <type>       only this asset type (${Object.keys(pluginsByType).sort().join(", ")})
+  --warnings-only     only assets with at least one warning
+  --json              print {"ok": true, "assets": [<AssetStateDto>, …]}
+  --help              this help
+
+Read-only: nothing is processed or written.
+
+Example:
+  fundus asset list --manifest mainCatalog --json
+`,
+	show: `fundus asset show — one asset in detail
+
+Usage: fundus asset show <id> [--json]
+
+Prints the asset's raw file, content hash, parameters, explicit +
+passive manifest memberships, proxy status, reference edges (outgoing
+and incoming), and warnings.
+
+Flags:
+  --json   print {"ok": true, "asset": <AssetStateDto>}
+  --help   this help
+
+Read-only: nothing is processed or written.
+
+Example:
+  fundus asset show navigationPanel --json
+`,
+	ingest: `fundus asset ingest — copy a file into the raw dir as a typed asset
+
+Usage: fundus asset ingest <file> [--type <type>] [--id <id>] [--folder <path|root>]
+                           [--manifests <a,b>] [--parameters <json>] [--json]
+
+Behaves like an editor upload: the file is copied into the raw
+directory (sanitized, non-colliding name) and content-hashed, and the
+record starts with the owning plugin's default parameters — a slice
+additionally seeds insets from the image dimensions and a pixel ratio
+from a @2x-style file-name suffix. Runs the full autosave chain
+(write library → process → regenerate manifest modules).
+
+Flags:
+  --type <type>        required when the file extension is ambiguous
+                       (.png could be image or slice, .mp4 video or
+                       chroma-key-video); optional when exactly one
+                       type accepts it (.wav → audio); known types:
+                       ${Object.keys(pluginsByType).sort().join(", ")}
+  --id <id>            asset id (camelCase identifier); default:
+                       proposed from the file name
+                       (panel_button@2x.png → sidebarPanel)
+  --folder <path|root> destination folder; default: root
+  --manifests <a,b>    explicit manifest membership, applied in the
+                       same operation (comma-separated; every name
+                       must exist)
+  --parameters <json>  parameter patch merged onto the plugin defaults
+                       — same shallow-merge semantics as \`asset set\`
+                       (see \`fundus asset set --help\`)
+  --json               print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
+  --help               this help
+
+A failed ingest (invalid patch, unknown manifest, …) leaves nothing
+behind: the raw file and record are rolled back.
+
+Example:
+  fundus asset ingest ./exports/navigation_panel@2x.png --type slice \\
+    --manifests mainCatalog --json
+`,
+	set: `fundus asset set — update an asset's parameters and/or memberships
+
+Usage: fundus asset set <id> [--parameters <json>] [--manifests <a,b>] [--json]
+
+At least one of --parameters/--manifests is required. Runs the full
+autosave chain (write library → process → regenerate manifest modules).
+
+Flags:
+  --parameters <json>  SHALLOW MERGE at the top level onto the current
+                       parameters, then plugin validation:
+                         {"preset": "webp-hq"}        sets one field,
+                                                      keeps the others
+                         {"chromaKey": {…}}           replaces the whole
+                                                      chromaKey object
+                         {"mask": null}               clears an optional
+                                                      field
+                         {"mask": {"$asset": "someImage"}}
+                                                      sets an asset
+                                                      reference
+  --manifests <a,b>    REPLACES the explicit membership set (declarative,
+                       idempotent); --manifests "" clears it
+  --json               print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
+  --help               this help
+
+The mutation is validated first and rejected (exit 1, nothing written)
+if it would leave the library invalid — e.g. a reference to a missing
+asset, a reference cycle, or an unknown manifest name. Ingest reference
+targets before pointing at them.
+
+Example:
+  fundus asset set characterIdle \\
+    --parameters '{"mask": {"$asset": "characterIdleMask"}}' --json
+`,
+	rename: `fundus asset rename — rename an asset id
+
+Usage: fundus asset rename <id> <newId> [--json]
+
+Renames the asset's id (the raw file keeps its name — ids are the
+stable key) and re-hashes its proxy under the new id via the autosave
+chain. Fails if another asset references <id> — update the referrers
+first — or if <newId> is taken or invalid.
+
+Flags:
+  --json   print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
+  --help   this help
+
+Example:
+  fundus asset rename sidebarPanel navigationPanel --json
+`,
+	move: `fundus asset move — move an asset between folders
+
+Usage: fundus asset move <id> <folder|root> [--json]
+
+Moves the raw file and its current proxy without changing the stable asset id,
+then runs the autosave chain. The destination folder must already exist; use
+the literal "root" for the implicit root.
+
+Flags:
+  --json   print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
+  --help   this help
+
+Example:
+  fundus asset move navigationPanel "UI/Buttons" --json
+`,
+	delete: `fundus asset delete — delete an asset
+
+Usage: fundus asset delete <id> [--json]
+
+Deletes the library record, its raw file, and its proxies, then
+regenerates the affected manifest modules. Fails if another asset
+references it — remove the references first.
+
+Flags:
+  --json   print {"ok": true, "deletedAssetId": "<id>", "issues": […]}
+  --help   this help
+
+Example:
+  fundus asset delete obsoleteBanner --json
+`
+};
+async function runAssetList(argumentList) {
+	const parsed = parseArguments(argumentList, {
+		...COMMON_FLAGS,
+		manifest: { takesValue: true },
+		type: { takesValue: true },
+		"warnings-only": { takesValue: false }
+	}, "fundus asset list");
+	requirePositionals(parsed, [], "fundus asset list");
+	const typeFilter = parsed.flags.type;
+	if (typeof typeFilter === "string") serverPluginForType(typeFilter);
+	const state = await (await createOperations()).state();
+	const manifestFilter = parsed.flags.manifest;
+	if (typeof manifestFilter === "string" && !Object.hasOwn(state.library.manifests, manifestFilter)) throw new Error(`Unknown manifest "${manifestFilter}".`);
+	const assets = state.assets.filter((asset) => {
+		if (typeof typeFilter === "string" && asset.type !== typeFilter) return false;
+		if (typeof manifestFilter === "string" && !asset.manifests.includes(manifestFilter) && !asset.passiveManifests.some((membership) => membership.manifest === manifestFilter)) return false;
+		if (parsed.flags["warnings-only"] && asset.warnings.length === 0) return false;
+		return true;
+	});
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			assets
+		});
+		return;
+	}
+	if (assets.length === 0) {
+		console.log("No matching assets.");
+		return;
+	}
+	printAssetLines(assets);
+}
+async function runAssetShow(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus asset show");
+	const [id] = requirePositionals(parsed, ["<id>"], "fundus asset show");
+	const asset = assetById(await (await createOperations()).state(), id);
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			asset
+		});
+		return;
+	}
+	printHumanAssetDetail(asset);
+}
+/**
+* Infer the asset type from the file extension: unambiguous → that type;
+* ambiguous (png: image/slice, mp4: video/chroma-key-video) → `--type` is
+* required; unknown → list what the plugins accept.
+*/
+function inferTypeForFileName(fileName) {
+	const candidates = typesForFileName(fileName);
+	if (candidates.length === 1) return candidates[0];
+	const extension = fileName.slice(fileName.lastIndexOf(".") + 1).toLowerCase();
+	if (candidates.length === 0) {
+		const knownExtensions = [...new Set(Object.values(pluginsByType).flatMap((plugin) => plugin.accepts))].sort().join(", ");
+		throw new Error(`No asset type accepts ".${extension}" files (accepted extensions: ${knownExtensions}).`);
+	}
+	throw new Error(`The ".${extension}" extension is ambiguous — pass --type <${candidates.join("|")}>.`);
+}
+async function runAssetIngest(argumentList) {
+	const parsed = parseArguments(argumentList, {
+		...COMMON_FLAGS,
+		type: { takesValue: true },
+		id: { takesValue: true },
+		manifests: { takesValue: true },
+		parameters: { takesValue: true },
+		folder: { takesValue: true }
+	}, "fundus asset ingest");
+	const [filePath] = requirePositionals(parsed, ["<file>"], "fundus asset ingest");
+	const absolutePath = resolve(process.cwd(), filePath);
+	let bytes;
+	try {
+		bytes = new Uint8Array(await readFile(absolutePath));
+	} catch {
+		throw new Error(`Cannot read file "${filePath}".`);
+	}
+	const fileName = basename(absolutePath);
+	const type = typeof parsed.flags.type === "string" ? parsed.flags.type : inferTypeForFileName(fileName);
+	const id = typeof parsed.flags.id === "string" ? parsed.flags.id : proposeAssetId(fileName);
+	const parametersPatch = typeof parsed.flags.parameters === "string" ? parseJsonFlag("parameters", parsed.flags.parameters) : void 0;
+	const manifests = typeof parsed.flags.manifests === "string" ? parseManifestList(parsed.flags.manifests) : void 0;
+	const folder = typeof parsed.flags.folder === "string" ? parseFolderToken(parsed.flags.folder) : "";
+	const state = await (await createOperations()).ingest({
+		fileName,
+		bytes,
+		type,
+		id,
+		folder,
+		parametersPatch,
+		manifests
+	});
+	const asset = assetById(state, id);
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			asset,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Ingested "${fileName}" as ${type} asset "${id}".`, asset, state);
+}
+async function runAssetSet(argumentList) {
+	const parsed = parseArguments(argumentList, {
+		...COMMON_FLAGS,
+		parameters: { takesValue: true },
+		manifests: { takesValue: true }
+	}, "fundus asset set");
+	const [id] = requirePositionals(parsed, ["<id>"], "fundus asset set");
+	if (parsed.flags.parameters === void 0 && parsed.flags.manifests === void 0) throw new CliUsageError("`fundus asset set` needs --parameters and/or --manifests — run `fundus asset set --help`.");
+	const parametersPatch = typeof parsed.flags.parameters === "string" ? parseJsonFlag("parameters", parsed.flags.parameters) : void 0;
+	const manifests = typeof parsed.flags.manifests === "string" ? parseManifestList(parsed.flags.manifests) : void 0;
+	const state = await (await createOperations()).setAsset(id, {
+		parametersPatch,
+		manifests
+	});
+	const asset = assetById(state, id);
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			asset,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Updated asset "${id}".`, asset, state);
+}
+async function runAssetRename(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus asset rename");
+	const [id, newId] = requirePositionals(parsed, ["<id>", "<newId>"], "fundus asset rename");
+	const state = await (await createOperations()).renameAsset(id, newId);
+	const asset = assetById(state, newId);
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			asset,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Renamed asset "${id}" to "${newId}".`, asset, state);
+}
+function parseFolderToken(token) {
+	return token.toLocaleLowerCase("en-US") === "root" ? "" : token;
+}
+async function runAssetMove(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus asset move");
+	const [id, folderToken] = requirePositionals(parsed, ["<id>", "<folder|root>"], "fundus asset move");
+	const state = await (await createOperations()).moveAsset(id, parseFolderToken(folderToken));
+	const asset = assetById(state, id);
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			asset,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Moved asset "${id}" to "${asset.folder || "root"}".`, asset, state);
+}
+async function runAssetDelete(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus asset delete");
+	const [id] = requirePositionals(parsed, ["<id>"], "fundus asset delete");
+	const state = await (await createOperations()).deleteAsset(id, { failOnIntroducedIssues: true });
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			deletedAssetId: id,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Deleted asset "${id}" (record, raw file, proxies).`, null, state);
+}
+async function runAssetCommand(argumentList) {
+	const [subcommand, ...rest] = argumentList;
+	if (subcommand === void 0 || subcommand === "--help") {
+		console.log(ASSET_HELP);
+		if (subcommand === void 0) throw new CliUsageError("`fundus asset` needs a subcommand: list, show, ingest, set, rename, move, delete.");
+		return;
+	}
+	if (hasHelpFlag(rest)) {
+		console.log(ASSET_SUBCOMMAND_HELP[subcommand] ?? ASSET_HELP);
+		return;
+	}
+	switch (subcommand) {
+		case "list": return runAssetList(rest);
+		case "show": return runAssetShow(rest);
+		case "ingest": return runAssetIngest(rest);
+		case "set": return runAssetSet(rest);
+		case "rename": return runAssetRename(rest);
+		case "move": return runAssetMove(rest);
+		case "delete": return runAssetDelete(rest);
+		default: throw new CliUsageError(`Unknown subcommand "asset ${subcommand}" — run \`fundus asset --help\`.`);
+	}
+}
+function folderRows(state) {
+	return [...state.library.folders].sort(compareCodeUnits).map((path) => ({
+		path,
+		name: folderNameOf(path),
+		parent: parentFolderPath(path),
+		directAssetIds: state.assets.filter((asset) => asset.folder === path).map((asset) => asset.id).sort(compareCodeUnits)
+	}));
+}
+const FOLDER_HELP = `fundus folder — manage the mirrored raw/proxy folder tree
+
+Usage: fundus folder <subcommand> …
+
+Subcommands:
+  list      list registered folders and their direct assets
+  create    create a persisted folder (fundus folder create <path>)
+  rename    rename one folder segment and its subtree
+  move      move a complete folder subtree below another folder
+  delete    recursively delete a folder subtree and its assets
+
+All mutations update rawDir and proxyDir together, maintain .gitkeep files,
+and run the full autosave chain. All subcommands accept --json and --help.
+`;
+const FOLDER_SUBCOMMAND_HELP = {
+	list: `fundus folder list — list registered folders
+
+Usage: fundus folder list [--json]
+
+Prints each folder path, parent, and direct assets. Root is implicit and is not
+included. Read-only: nothing is processed or written.
+
+Flags:
+  --json   print {"ok": true, "folders": […]}
+  --help   this help
+
+Example:
+  fundus folder list --json
+`,
+	create: `fundus folder create — create a persisted folder
+
+Usage: fundus folder create <path> [--json]
+
+The parent must already exist (or be the implicit root). Creates matching raw
+and proxy directories with managed .gitkeep files.
+
+Flags:
+  --json   print the created folder row and issues
+  --help   this help
+
+Example:
+  fundus folder create "UI/Buttons" --json
+`,
+	rename: `fundus folder rename — rename a folder
+
+Usage: fundus folder rename <path> <newName> [--json]
+
+Renames only the final path segment, preserving the parent. Descendant folders,
+raw paths, proxy paths, and generated URLs move with it.
+
+Flags:
+  --json   print the renamed folder row and issues
+  --help   this help
+
+Example:
+  fundus folder rename "UI/Buttons" Controls --json
+`,
+	move: `fundus folder move — move a folder subtree
+
+Usage: fundus folder move <path> <parent|root> [--json]
+
+Moves the folder, every descendant folder, and all contained raw/proxy files
+below an existing parent. The folder keeps its name and cannot move into its
+own subtree. Use the literal "root" for the implicit root.
+
+Flags:
+  --json   print the moved folder row and issues
+  --help   this help
+
+Example:
+  fundus folder move "UI/Buttons" Shared --json
+`,
+	delete: `fundus folder delete — recursively delete a folder
+
+Usage: fundus folder delete <path> --recursive [--json]
+
+Deletes the complete subtree and all assets in it. --recursive is required to
+make this destructive operation explicit. External references to deleted assets
+are reported as validation issues after deletion.
+
+Flags:
+  --recursive   required destructive-operation acknowledgement
+  --json        print the deleted path and resulting issues
+  --help        this help
+
+Example:
+  fundus folder delete "UI/Obsolete" --recursive --json
+`
+};
+async function runFolderList(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus folder list");
+	requirePositionals(parsed, [], "fundus folder list");
+	const folders = folderRows(await (await createOperations()).state());
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			folders
+		});
+		return;
+	}
+	if (folders.length === 0) {
+		console.log("No folders.");
+		return;
+	}
+	for (const folder of folders) console.log(`${folder.path}  ${folder.directAssetIds.join(", ") || "(empty)"}`);
+}
+async function runFolderCreate(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus folder create");
+	const [path] = requirePositionals(parsed, ["<path>"], "fundus folder create");
+	const state = await (await createOperations()).createFolder(path);
+	const folder = folderRows(state).find((row) => row.path === path.normalize("NFC"));
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			folder,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Created folder "${folder?.path ?? path}".`, null, state);
+}
+async function runFolderRename(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus folder rename");
+	const [path, newName] = requirePositionals(parsed, ["<path>", "<newName>"], "fundus folder rename");
+	const state = await (await createOperations()).renameFolder(path, newName);
+	const nextPath = parentFolderPath(path) === "" ? newName : `${parentFolderPath(path)}/${newName}`;
+	const folder = folderRows(state).find((row) => row.path === nextPath.normalize("NFC"));
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			folder,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Renamed folder "${path}" to "${folder?.path ?? nextPath}".`, null, state);
+}
+async function runFolderMove(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus folder move");
+	const [path, parentToken] = requirePositionals(parsed, ["<path>", "<parent|root>"], "fundus folder move");
+	const parent = parseFolderToken(parentToken);
+	const state = await (await createOperations()).moveFolder(path, parent);
+	const nextPath = parent === "" ? folderNameOf(path) : `${parent}/${folderNameOf(path)}`;
+	const folder = folderRows(state).find((row) => row.path === nextPath.normalize("NFC"));
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			folder,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Moved folder "${path}" to "${folder?.path ?? nextPath}".`, null, state);
+}
+async function runFolderDelete(argumentList) {
+	const parsed = parseArguments(argumentList, {
+		...COMMON_FLAGS,
+		recursive: { takesValue: false }
+	}, "fundus folder delete");
+	const [path] = requirePositionals(parsed, ["<path>"], "fundus folder delete");
+	if (!parsed.flags.recursive) throw new CliUsageError("`fundus folder delete` requires --recursive because it deletes the subtree and its assets.");
+	const state = await (await createOperations()).deleteFolder(path);
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			deletedFolderPath: path,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Deleted folder "${path}" recursively.`, null, state);
+}
+async function runFolderCommand(argumentList) {
+	const [subcommand, ...rest] = argumentList;
+	if (subcommand === void 0 || subcommand === "--help") {
+		console.log(FOLDER_HELP);
+		if (subcommand === void 0) throw new CliUsageError("`fundus folder` needs a subcommand: list, create, rename, move, delete.");
+		return;
+	}
+	if (hasHelpFlag(rest)) {
+		console.log(FOLDER_SUBCOMMAND_HELP[subcommand] ?? FOLDER_HELP);
+		return;
+	}
+	switch (subcommand) {
+		case "list": return runFolderList(rest);
+		case "create": return runFolderCreate(rest);
+		case "rename": return runFolderRename(rest);
+		case "move": return runFolderMove(rest);
+		case "delete": return runFolderDelete(rest);
+		default: throw new CliUsageError(`Unknown subcommand "folder ${subcommand}" — run \`fundus folder --help\`.`);
+	}
+}
+const MANIFEST_HELP = `fundus manifest — manage manifests (delivery units & preload groups)
+
+Usage: fundus manifest <subcommand> …
+
+A manifest is a delivery unit and a preload group: only assets in at
+least one manifest (explicitly, or passively via the reference closure)
+are processed into proxies and reachable from host code. Assets join and
+leave manifests via \`fundus asset set <id> --manifests <a,b>\`. All
+subcommands accept --json and --help.
+
+Subcommands:
+  list      list manifests with members and delivered bytes
+  create    create an empty manifest (fundus manifest create <name>)
+  set       set a manifest's editor color / emoji appearance
+  palette   list the selectable appearance colors and emojis
+  rename    rename a manifest (fundus manifest rename <name> <newName>)
+  delete    delete a manifest and strip its memberships
+
+Run \`fundus manifest <subcommand> --help\` for the focused page.
+`;
+const MANIFEST_SUBCOMMAND_HELP = {
+	list: `fundus manifest list — list manifests
+
+Usage: fundus manifest list [--json]
+
+One line per manifest: name, delivered bytes (the preload-budget
+number, over the full delivery set), explicit members, and passive
+members (assets pulled in via the reference closure, with via-
+attribution in the JSON output).
+
+Flags:
+  --json   print {"ok": true, "manifests": [{"name", "color", "emoji",
+           "explicitMemberIds", "passiveMembers", "deliveredBytes"}, …]}
+  --help   this help
+
+Read-only: nothing is processed or written.
+
+Example:
+  fundus manifest list --json
+`,
+	create: `fundus manifest create — create an empty manifest
+
+Usage: fundus manifest create <name> [--json]
+
+<name> must be a camelCase identifier; its kebab-case form names the
+generated module (mainCatalog → main-catalog.generated.ts). Mutations run
+the autosave chain, so the module is generated immediately.
+
+Flags:
+  --json   print {"ok": true, "manifest": {…}, "issues": […]}
+  --help   this help
+
+Example:
+  fundus manifest create mainCatalog --json
+`,
+	set: `fundus manifest set — set a manifest's editor appearance
+
+Usage: fundus manifest set <name> [--color <name|hex|none>] [--emoji <emoji|none>] [--json]
+
+Tags the manifest with a color and/or an emoji, shown on its label
+throughout the editor UI. Both are chosen from the fixed sets below;
+pass "none" (or an empty string) to clear either. At least one of
+--color/--emoji is required. Runs the autosave chain.
+
+Colors (name or #hex):
+  ${MANIFEST_COLORS.map((color) => `${color.name} (${color.value})`).join(", ")}
+
+Emojis:
+  ${MANIFEST_EMOJIS.join(" ")}
+
+Flags:
+  --color <name|hex|none>  palette name ("blue"), hex value ("#3b82f6"),
+                           or "none"/"" to clear
+  --emoji <emoji|none>     one of the emojis above, or "none"/"" to clear
+  --json                   print the created/updated manifest row + issues
+  --help                   this help
+
+Example:
+  fundus manifest set mainCatalog --color blue --emoji 🗂️ --json
+`,
+	palette: `fundus manifest palette — list the selectable appearance colors and emojis
+
+Usage: fundus manifest palette [--json]
+
+The closed sets \`fundus manifest set\` validates against. Read this first
+to discover valid --color / --emoji values programmatically instead of
+guessing.
+
+Flags:
+  --json   print {"ok": true, "colors": [{"name", "value"}, …], "emojis": […]}
+  --help   this help
+
+Read-only: nothing is processed or written.
+
+Example:
+  fundus manifest palette --json | jq '.emojis'
+`,
+	rename: `fundus manifest rename — rename a manifest
+
+Usage: fundus manifest rename <name> <newName> [--json]
+
+<newName> must be a camelCase identifier whose kebab-case form is
+distinct from every other manifest's. The rename keeps the manifest's
+appearance, rewrites every asset's membership, and replaces the
+generated module (the old file is removed, the new one written). Host
+code importing the module must be updated by hand — both the module
+file name and the exported const change with the manifest name
+(mainCatalog → main-catalog.generated.ts / \`mainCatalog\`).
+
+Flags:
+  --json   print {"ok": true, "manifest": {…}, "issues": […]}
+  --help   this help
+
+Example:
+  fundus manifest rename mainCatalog primaryCatalog --json
+`,
+	delete: `fundus manifest delete — delete a manifest
+
+Usage: fundus manifest delete <name> [--json]
+
+Deletes the manifest, strips it from every asset's membership, and
+removes its generated module. Assets left in no manifest stop being
+delivered (they warn as unreachable).
+
+Flags:
+  --json   print {"ok": true, "deletedManifestName": "<name>", "issues": […]}
+  --help   this help
+
+Example:
+  fundus manifest delete obsoleteShelf --json
+`
+};
+async function runManifestList(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus manifest list");
+	requirePositionals(parsed, [], "fundus manifest list");
+	const manifests = manifestRows(await (await createOperations()).state());
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			manifests
+		});
+		return;
+	}
+	if (manifests.length === 0) {
+		console.log("No manifests.");
+		return;
+	}
+	const labels = manifests.map(manifestLabel);
+	const nameWidth = Math.max(0, ...labels.map((label) => label.length));
+	manifests.forEach((row, index) => {
+		const passiveSuffix = row.passiveMembers.length > 0 ? ` + passive: ${row.passiveMembers.map((member) => member.assetId).join(", ")}` : "";
+		const colorSuffix = row.color ? `  ${row.color}` : "";
+		console.log(`${labels[index].padEnd(nameWidth)}  ${formatBytes(row.deliveredBytes).padStart(9)}  ${row.explicitMemberIds.join(", ") || "(empty)"}${passiveSuffix}${colorSuffix}`);
+	});
+}
+async function runManifestCreate(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus manifest create");
+	const [name] = requirePositionals(parsed, ["<name>"], "fundus manifest create");
+	const state = await (await createOperations()).createManifest(name);
+	const manifest = manifestRows(state).find((row) => row.name === name);
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			manifest,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Created manifest "${name}".`, null, state);
+}
+/** Resolve a `--color`/`--emoji` flag value to a set/clear/omit intent. */
+function resolveAppearanceFlag(value, resolve, describe) {
+	if (typeof value !== "string") return void 0;
+	const token = value.trim();
+	if (token === "" || token.toLowerCase() === "none") return null;
+	const resolved = resolve(token);
+	if (resolved === null) throw new Error(describe(token));
+	return resolved;
+}
+async function runManifestSet(argumentList) {
+	const parsed = parseArguments(argumentList, {
+		...COMMON_FLAGS,
+		color: { takesValue: true },
+		emoji: { takesValue: true }
+	}, "fundus manifest set");
+	const [name] = requirePositionals(parsed, ["<name>"], "fundus manifest set");
+	if (parsed.flags.color === void 0 && parsed.flags.emoji === void 0) throw new CliUsageError("`fundus manifest set` needs --color and/or --emoji — run `fundus manifest set --help`.");
+	const color = resolveAppearanceFlag(parsed.flags.color, resolveManifestColor, (token) => `"${token}" is not a selectable manifest color — choose one of: ${MANIFEST_COLORS.map((entry) => `${entry.name} (${entry.value})`).join(", ")}, or "none".`);
+	const emoji = resolveAppearanceFlag(parsed.flags.emoji, (token) => manifestEmojiError(token) === null ? token : null, (token) => manifestEmojiError(token) ?? `"${token}" is not a selectable manifest emoji.`);
+	const state = await (await createOperations()).setManifestAppearance(name, {
+		color,
+		emoji
+	});
+	const manifest = manifestRows(state).find((row) => row.name === name);
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			manifest,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Updated manifest "${name}" appearance.`, null, state);
+}
+async function runManifestPalette(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus manifest palette");
+	requirePositionals(parsed, [], "fundus manifest palette");
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			colors: MANIFEST_COLORS,
+			emojis: MANIFEST_EMOJIS
+		});
+		return;
+	}
+	console.log("Colors:");
+	const nameWidth = Math.max(0, ...MANIFEST_COLORS.map((color) => color.name.length));
+	for (const color of MANIFEST_COLORS) console.log(`  ${color.name.padEnd(nameWidth)}  ${color.value}`);
+	console.log("");
+	console.log(`Emojis (${MANIFEST_EMOJIS.length}):`);
+	console.log(`  ${MANIFEST_EMOJIS.join(" ")}`);
+}
+async function runManifestRename(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus manifest rename");
+	const [name, newName] = requirePositionals(parsed, ["<name>", "<newName>"], "fundus manifest rename");
+	const state = await (await createOperations()).renameManifest(name, newName);
+	const manifest = manifestRows(state).find((row) => row.name === newName);
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			manifest,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Renamed manifest "${name}" to "${newName}" — update host imports of the generated module.`, null, state);
+}
+async function runManifestDelete(argumentList) {
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus manifest delete");
+	const [name] = requirePositionals(parsed, ["<name>"], "fundus manifest delete");
+	const state = await (await createOperations()).deleteManifest(name);
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			deletedManifestName: name,
+			issues: state.issues
+		});
+		return;
+	}
+	printMutationResult(`Deleted manifest "${name}" and stripped it from every asset.`, null, state);
+}
+async function runManifestCommand(argumentList) {
+	const [subcommand, ...rest] = argumentList;
+	if (subcommand === void 0 || subcommand === "--help") {
+		console.log(MANIFEST_HELP);
+		if (subcommand === void 0) throw new CliUsageError("`fundus manifest` needs a subcommand: list, create, set, palette, rename, delete.");
+		return;
+	}
+	if (hasHelpFlag(rest)) {
+		console.log(MANIFEST_SUBCOMMAND_HELP[subcommand] ?? MANIFEST_HELP);
+		return;
+	}
+	switch (subcommand) {
+		case "list": return runManifestList(rest);
+		case "create": return runManifestCreate(rest);
+		case "set": return runManifestSet(rest);
+		case "palette": return runManifestPalette(rest);
+		case "rename": return runManifestRename(rest);
+		case "delete": return runManifestDelete(rest);
+		default: throw new CliUsageError(`Unknown subcommand "manifest ${subcommand}" — run \`fundus manifest --help\`.`);
+	}
+}
+const BUILD_HELP = `fundus build — run the headless pipeline
+
+Usage: fundus build [--json]
+
+Validates the library, processes every stale or missing proxy, prunes
+orphaned proxies, and regenerates all manifest modules. Deterministic
+and idempotent: a second run on an unchanged project processes nothing
+and rewrites byte-identical modules. Run it in CI, postinstall, or
+before the host build; commit the result.
+
+Flags:
+  --json   print {"ok": true, "processed": […], "upToDate": […],
+           "prunedProxies": […], "modulesWritten": […],
+           "modulesRemoved": […]} — asset ids for processing,
+           file names for pruning/codegen
+  --help   this help
+
+A validation failure processes nothing and exits 1 (with --json:
+{"error": {"message": …}}).
+
+Example:
+  fundus build --json | jq '.processed'
+`;
+async function runBuildCommand(argumentList) {
+	if (hasHelpFlag(argumentList)) {
+		console.log(BUILD_HELP);
+		return;
+	}
+	const parsed = parseArguments(argumentList, COMMON_FLAGS, "fundus build");
+	requirePositionals(parsed, [], "fundus build");
+	const { processing, codegen } = await runBuild(process.cwd());
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: true,
+			processed: processing.processed,
+			upToDate: processing.reused,
+			prunedProxies: processing.pruned,
+			modulesWritten: codegen.written,
+			modulesRemoved: codegen.removed
+		});
+		return;
+	}
+	console.log(`fundus build: ${processing.processed.length} processed, ${processing.reused.length} up to date, ${processing.pruned.length} pruned; ${codegen.written.length} manifest module(s) written` + (codegen.removed.length > 0 ? `, ${codegen.removed.length} removed` : "") + ".");
+}
+const CHECK_HELP = `fundus check — verify the committed state (the CI gate)
+
+Usage: fundus check [--allow-warnings] [--json]
+
+Verify-only, no writes: the library must validate, every delivered
+asset's committed proxy must exist under its expected name (staleness
+is a name check), the proxy directory must hold no orphans, and every
+generated manifest module must be byte-identical to an in-memory
+regeneration. Warnings (unreachable asset, raw-hash drift) fail the
+check too unless --allow-warnings downgrades them; errors never
+downgrade.
+
+Flags:
+  --allow-warnings   exit 0 despite warnings (errors still fail)
+  --json             print one report document:
+                     {"ok": <pass/fail>, "assetCount": …, "manifestCount": …,
+                      "errors": [<finding>, …], "warnings": [<finding>, …]}
+                     where a finding is {"kind", "message"} plus
+                     "assetId" / "manifest" / "fileName" where applicable
+  --help             this help
+
+Exit codes: 0 = clean (or warnings allowed), 1 = failed. A failure to
+even run the check (e.g. no fundus.config.ts) exits 1 with the usual
+{"error": {"message": …}} envelope under --json.
+
+Example:
+  fundus check --json | jq '.errors[].kind'
+`;
+async function runCheckCommand(argumentList) {
+	if (hasHelpFlag(argumentList)) {
+		console.log(CHECK_HELP);
+		return;
+	}
+	const parsed = parseArguments(argumentList, {
+		...COMMON_FLAGS,
+		"allow-warnings": { takesValue: false }
+	}, "fundus check");
+	requirePositionals(parsed, [], "fundus check");
+	const allowWarnings = parsed.flags["allow-warnings"] === true;
+	const report = await runCheck(process.cwd());
+	const warningsFatal = report.warnings.length > 0 && !allowWarnings;
+	const failed = report.errors.length > 0 || warningsFatal;
+	if (parsed.flags.json) {
+		printJsonDocument({
+			ok: !failed,
+			assetCount: report.assetCount,
+			manifestCount: report.manifestCount,
+			errors: report.errors,
+			warnings: report.warnings
+		});
+		if (failed) process.exitCode = 1;
+		return;
+	}
+	for (const error of report.errors) console.error(`✗ ${formatCheckFinding(error)}`);
+	for (const warning of report.warnings) console.error(`⚠ ${formatCheckFinding(warning)}`);
+	if (failed) {
+		console.error(`fundus check failed: ${report.errors.length} error(s), ${report.warnings.length} warning(s)` + (warningsFatal ? " (warnings are errors — pass --allow-warnings to downgrade them)" : "") + ".");
+		process.exitCode = 1;
+		return;
+	}
+	console.log(`fundus check: ${report.assetCount} asset(s), ${report.manifestCount} manifest(s) — clean` + (report.warnings.length > 0 ? ` (${report.warnings.length} allowed warning(s))` : "") + ".");
+}
+//#endregion
+//#region src/cli.ts
+/**
+* The fundus CLI: the full asset lifecycle drivable headlessly.
+* `init` creates the host config, `start` serves the prebuilt editor (+ API),
+* `build` runs the headless pipeline, `check` verifies without writing (the CI
+* gate), and the `state` / `asset` / `manifest` command groups let agents and
+* scripts ingest, inspect, mutate, and deliver assets without the editor UI.
+* The published binary is compiled ESM and runs directly on Node.js.
+*
+* Exit-code contract (agents rely on it):
+*   0  success
+*   1  expected error — bad invocation, unknown id, invalid parameters,
+*      validation failure; with --json, stdout carries a single
+*      {"error": {"message": …}} document, without it the message goes to
+*      stderr
+*   2  unexpected crash (stack trace on stderr)
+*/
+const ROOT_HELP = `fundus — asset management for SvelteKit hosts
+
+Usage: fundus <command> … (run in the host project root, next to fundus.config.ts)
+
+Setup:
+  init                         create a template fundus.config.ts
+
+Inspect:
+  state                        the full project state: assets, manifests,
+                               memberships, proxies, references, warnings
+  asset list                   list assets (--manifest/--type/--warnings-only)
+  asset show <id>              one asset in detail
+  manifest list                manifests with members and delivered bytes
+  folder list                  persisted raw/proxy folders with direct assets
+
+Mutate (each runs the editor autosave chain: write library → process
+affected assets → regenerate manifest modules):
+  asset ingest <file>          copy a file into the raw dir as a typed asset
+                               (--type, --id, --manifests, --parameters)
+  asset set <id>               merge parameters and/or replace manifest
+                               membership (--parameters, --manifests)
+  asset rename <id> <newId>    rename an asset id
+  asset move <id> <folder|root> move an asset without changing its id
+  asset delete <id>            delete an asset (record, raw file, proxies)
+  folder create <path>         create a mirrored persisted folder
+  folder rename <path> <name>  rename a folder and its subtree
+  folder move <path> <parent|root> move a folder and its subtree
+  folder delete <path> --recursive  delete a subtree and all of its assets
+  manifest create <name>       create a manifest
+  manifest rename <name> <newName>  rename a manifest (host imports of the
+                               generated module must be updated by hand)
+  manifest delete <name>       delete a manifest and strip memberships
+
+Pipeline:
+  start                        serve the prebuilt editor and API
+  build                        process stale proxies, prune orphans,
+                               regenerate all manifest modules
+  check                        verify without writing: validation, proxies
+                               current, modules in sync; warnings are errors
+                               unless --allow-warnings
+
+Global flags:
+  --json      machine-readable output: exactly one JSON document on stdout
+              ({"ok": true, …} on success, {"error": {"message": …}} on an
+              expected error) — supported by every command except start;
+              \`check --json\` prints its pass/fail report with the failure
+              list ({"ok": false, "errors": […], …})
+  --help      this help; every command group and subcommand has its own
+              focused page (e.g. \`fundus asset ingest --help\`)
+  --version   print the fundus version
+
+Exit codes: 0 success · 1 expected error · 2 unexpected crash.
+
+Typical agent lifecycle:
+  fundus manifest create mainCatalog --json
+  fundus asset ingest ./exports/navigation_panel@2x.png --type slice --json
+  fundus asset set navigationPanel --parameters '{"mode": "three-horizontal"}' \\
+    --manifests mainCatalog --json
+  fundus check
+`;
+function printUsage() {
+	console.log(ROOT_HELP);
+}
+async function printVersion() {
+	const packageJson = JSON.parse(await readFile(join(import.meta.dirname, "../package.json"), "utf8"));
+	console.log(`fundus ${packageJson.version ?? "unknown"}`);
+}
+/**
+* Expected errors (exit 1) are deliberate `Error` throws from the operations
+* layer and the CLI's own usage checks. Built-in error types that code throws
+* on its own (TypeError, ReferenceError, …) and non-Error throws signal a bug
+* — those crash with exit 2. A site that surfaces e.g. a JSON.parse
+* SyntaxError as an expected condition must rethrow it as a plain Error
+* (cli-io.ts's parseJsonFlag rethrows a CliUsageError).
+*/
+function isUnexpectedCrash(cause) {
+	if (!(cause instanceof Error)) return true;
+	if (cause instanceof CliUsageError) return false;
+	return cause instanceof TypeError || cause instanceof RangeError || cause instanceof ReferenceError || cause instanceof SyntaxError;
+}
+async function runCommandGroup(run) {
+	const jsonOutput = process.argv.includes("--json");
+	try {
+		await run();
+	} catch (cause) {
+		if (isUnexpectedCrash(cause)) {
+			console.error(cause instanceof Error ? cause.stack ?? cause.message : String(cause));
+			process.exit(2);
+		}
+		const message = cause.message;
+		if (jsonOutput) printJsonDocument({ error: { message } });
+		else console.error(`fundus: ${message}`);
+		process.exit(1);
+	}
+}
+const START_HELP = `fundus start — serve the prebuilt editor and API
+
+Usage: fundus start
+
+Serves the editor SPA and the fs/processing REST API for the project
+this is run in (the directory containing fundus.config.ts). The library
+is re-read per request; mutations regenerate their derived artifacts.
+The editor is always served from the prebuilt SPA shipped in the npm package.
+The command fails if that build is missing. Stop with Ctrl-C.
+
+Every edit autosaves: write library → process affected assets →
+regenerate manifest modules — the same chain the CLI mutations run.
+
+Flags:
+  --help   this help
+
+Example:
+  cd my-host-app && npx fundus start
+`;
+const command = process.argv[2];
+const commandArguments = process.argv.slice(3);
+if (command === "init") await runCommandGroup(() => runInitCommand(commandArguments));
+else if (command === "build") await runCommandGroup(() => runBuildCommand(commandArguments));
+else if (command === "check") await runCommandGroup(() => runCheckCommand(commandArguments));
+else if (command === "start") await runCommandGroup(async () => {
+	const parsed = parseArguments(commandArguments, { help: { takesValue: false } }, "fundus start");
+	requirePositionals(parsed, [], "fundus start");
+	if (parsed.flags.help) {
+		console.log(START_HELP);
+		return;
+	}
+	const { runStart } = await import("./start-D2IXOrni.js");
+	await runStart(process.cwd());
+});
+else if (command === "state") await runCommandGroup(() => runStateCommand(commandArguments));
+else if (command === "asset") await runCommandGroup(() => runAssetCommand(commandArguments));
+else if (command === "folder") await runCommandGroup(() => runFolderCommand(commandArguments));
+else if (command === "manifest") await runCommandGroup(() => runManifestCommand(commandArguments));
+else if (command === "--version") await printVersion();
+else if (command === void 0) {
+	printUsage();
+	process.exit(1);
+} else if (command === "help" || command === "--help") printUsage();
+else {
+	console.error(`fundus: unknown command "${command}" — run \`fundus --help\`.`);
+	process.exit(1);
+}
+//#endregion
+export {};