cascivo 0.1.6 → 0.3.4

package/dist/index.mjs

@@ -1,70 +1,17 @@
 #!/usr/bin/env node
-import { t as fetchJson } from "./http-CLkdTpxD.mjs";
+import { a as detectPackageManager, c as __exportAll, n as DEFAULT_CONFIG$1, o as installCommand, r as THEMES, s as loadConfig, t as CASCIVO_HOST } from "./config-BsyJbMvD.mjs";
+import { n as resolveOutputPath, r as writeFileSafe, t as readFileSafe } from "./fs-m7ZvuBBm.mjs";
+import { r as fetchTextRetry, t as fetchJson } from "./http-CJZ5W0Fa.mjs";
+import { a as updateLockEntry, c as fileName, i as sha256, l as findComponent, n as createLock, o as writeLock, r as readLock, s as fetchRegistry, t as checkPeerVersions } from "./peer-versions-B2bCgko-.mjs";
+import { createRequire } from "node:module";
 import { argv, stdin, stdout } from "node:process";
 import { pathToFileURL } from "node:url";
-import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { asTemplateMeta, buildRegistry, isTemplateItem, parseLegacyRegistry, validateIndex, validateTemplate } from "@cascivo/registry";
 import { createInterface } from "node:readline/promises";
-import { buildRegistry, parseLegacyRegistry, validateIndex } from "@cascivo/registry";
-//#region src/utils/config.ts
-const DEFAULT_CONFIG = {
-	registry: "https://cascivo.com/registry.json",
-	outputDir: "src/components/ui",
-	theme: "light"
-};
-const CONFIG_FILES = [
-	"cascivo.config.ts",
-	"cascivo.config.js",
-	"cascivo.config.mjs"
-];
-/** Apply defaults over a (possibly partial) user config object. */
-function resolveConfig(partial) {
-	return {
-		...DEFAULT_CONFIG,
-		...partial
-	};
-}
-/** Let env vars override config — used by the MCP server to pass `outputDir`. */
-function applyEnvOverrides(config, env = process.env) {
-	return {
-		...config,
-		...env.CASCIVO_REGISTRY ? { registry: env.CASCIVO_REGISTRY } : {},
-		...env.CASCIVO_OUTPUT_DIR ? { outputDir: env.CASCIVO_OUTPUT_DIR } : {}
-	};
-}
-/**
-* Locate and load `cascivo.config.{ts,js,mjs}` from `cwd`. Falls back to the
-* default config when no file is found or the file cannot be loaded. Env vars
-* (`CASCIVO_REGISTRY`, `CASCIVO_OUTPUT_DIR`) take precedence.
-*/
-async function loadConfig(cwd = process.cwd()) {
-	for (const file of CONFIG_FILES) {
-		const path = join(cwd, file);
-		if (!existsSync(path)) continue;
-		try {
-			const mod = await import(pathToFileURL(path).href);
-			return applyEnvOverrides(resolveConfig(mod.default ?? mod));
-		} catch {
-			return applyEnvOverrides(resolveConfig(null));
-		}
-	}
-	return applyEnvOverrides(resolveConfig(null));
-}
-/** Detect the package manager in use from lock files, defaulting to npm. */
-function detectPackageManager(cwd = process.cwd()) {
-	if (existsSync(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-	if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
-	if (existsSync(join(cwd, "bun.lockb"))) return "bun";
-	return "npm";
-}
-/** The install subcommand each package manager uses to add dependencies. */
-function installCommand(pm, packages) {
-	return [pm, [pm === "npm" ? "install" : "add", ...packages]];
-}
-//#endregion
 //#region src/utils/exec.ts
 /**
 * Install npm packages using the detected package manager, inheriting stdio so
@@ -85,153 +32,6 @@ function installPackages(packages, cwd = process.cwd()) {
 	return true;
 }
 //#endregion
-//#region src/utils/fs.ts
-/** Resolve where a component file should be written. */
-function resolveOutputPath(outputDir, component, file, cwd = process.cwd()) {
-	return join(resolve(cwd, outputDir), component, file);
-}
-/** Write a file, creating parent directories as needed. */
-async function writeFileSafe(path, content) {
-	await mkdir(dirname(path), { recursive: true });
-	await writeFile(path, content, "utf8");
-}
-/** Read a file, returning null if it does not exist. */
-async function readFileSafe(path) {
-	try {
-		return await readFile(path, "utf8");
-	} catch {
-		return null;
-	}
-}
-//#endregion
-//#region src/utils/registry.ts
-function asStringArray(value) {
-	return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
-}
-/** Validate and normalize raw JSON into a typed Registry. Throws on bad shape. */
-function parseRegistry(raw) {
-	if (typeof raw !== "object" || raw === null) throw new Error("Invalid registry: expected an object");
-	const obj = raw;
-	if (!Array.isArray(obj.components)) throw new Error("Invalid registry: \"components\" must be an array");
-	const components = obj.components.map((entry, i) => {
-		if (typeof entry !== "object" || entry === null) throw new Error(`Invalid registry: component at index ${i} is not an object`);
-		const c = entry;
-		if (typeof c.name !== "string") throw new Error(`Invalid registry: component at index ${i} is missing "name"`);
-		const rawType = c.type;
-		const type = rawType === "component" || rawType === "layout" || rawType === "block" || rawType === "chart" ? rawType : void 0;
-		const rawMeta = c.meta;
-		const metaName = typeof rawMeta === "object" && rawMeta !== null && typeof rawMeta.name === "string" ? rawMeta.name : c.name;
-		const result = {
-			name: c.name,
-			description: typeof c.description === "string" ? c.description : "",
-			category: typeof c.category === "string" ? c.category : "",
-			version: typeof c.version === "string" ? c.version : "0.0.0",
-			files: asStringArray(c.files),
-			dependencies: asStringArray(c.dependencies),
-			tags: asStringArray(c.tags),
-			meta: { name: metaName }
-		};
-		if (type !== void 0) result.type = type;
-		if (typeof c.install === "string") result.install = c.install;
-		return result;
-	});
-	const blocks = Array.isArray(obj.blocks) ? obj.blocks.flatMap((entry) => {
-		if (typeof entry !== "object" || entry === null) return [];
-		const b = entry;
-		if (typeof b.name !== "string") return [];
-		const rawScreenshot = typeof b.screenshot === "object" && b.screenshot !== null ? b.screenshot : {};
-		return [{
-			name: b.name,
-			type: "block",
-			displayName: typeof b.displayName === "string" ? b.displayName : b.name,
-			description: typeof b.description === "string" ? b.description : "",
-			category: typeof b.category === "string" ? b.category : "",
-			version: typeof b.version === "string" ? b.version : "0.0.0",
-			files: asStringArray(b.files),
-			dependencies: asStringArray(b.dependencies),
-			tags: asStringArray(b.tags),
-			screenshot: {
-				light: typeof rawScreenshot.light === "string" ? rawScreenshot.light : "",
-				dark: typeof rawScreenshot.dark === "string" ? rawScreenshot.dark : ""
-			}
-		}];
-	}) : [];
-	return {
-		version: typeof obj.version === "string" ? obj.version : "0.0.0",
-		generatedAt: typeof obj.generatedAt === "string" ? obj.generatedAt : "",
-		components,
-		blocks
-	};
-}
-/** Fetch and parse the registry from a URL. */
-async function fetchRegistry(url) {
-	const res = await fetch(url);
-	if (!res.ok) throw new Error(`Failed to fetch registry from ${url}: ${res.status} ${res.statusText}`);
-	return parseRegistry(await res.json());
-}
-/**
-* Find a component by name (case-insensitive, full name or unambiguous suffix).
-*
-* Examples:
-*   "layout/app-shell" → exact match on full name
-*   "app-shell"        → suffix match if exactly one entry ends with "/app-shell"
-*   "button"           → exact match (no slash, no suffix ambiguity)
-*/
-function findComponent(registry, name) {
-	const target = name.toLowerCase();
-	if (target.startsWith("block/")) {
-		const blockName = target.slice(6);
-		const block = (registry.blocks ?? []).find((b) => b.name.toLowerCase() === blockName);
-		if (!block) throw new Error(`Block "${blockName}" not found in registry.`);
-		return block;
-	}
-	const exact = registry.components.find((c) => c.name.toLowerCase() === target);
-	if (exact) return exact;
-	const suffix = `/${target}`;
-	const matches = registry.components.filter((c) => c.name.toLowerCase().endsWith(suffix));
-	if (matches.length === 1) return matches[0];
-}
-/** Extract the file name from a registry file URL. */
-function fileName(url) {
-	const stripped = url.split(/[?#]/)[0] ?? url;
-	return stripped.split("/").pop() || stripped;
-}
-//#endregion
-//#region src/utils/lock.ts
-function sha256(content) {
-	return `sha256-${createHash("sha256").update(content).digest("hex")}`;
-}
-const LOCK_FILENAME = "cascade.lock";
-async function readLock(cwd = process.cwd()) {
-	const path = join(cwd, LOCK_FILENAME);
-	if (!existsSync(path)) return null;
-	try {
-		const raw = JSON.parse(await readFile(path, "utf8"));
-		if (typeof raw !== "object" || raw === null) return null;
-		return raw;
-	} catch {
-		return null;
-	}
-}
-async function writeLock(lock, cwd = process.cwd()) {
-	await writeFile(join(cwd, LOCK_FILENAME), `${JSON.stringify(lock, null, 2)}\n`, "utf8");
-}
-function createLock() {
-	return {
-		lockVersion: 1,
-		items: {}
-	};
-}
-function updateLockEntry(lock, name, entry) {
-	return {
-		...lock,
-		items: {
-			...lock.items,
-			[name]: entry
-		}
-	};
-}
-//#endregion
 //#region src/utils/resolve.ts
 const GITHUB_RE = /^([^/]+)\/([^/]+)\/([^#]+)(?:#(.+))?$/;
 function expandEnv(str, env = process.env) {
@@ -309,7 +109,7 @@ async function resolveItemUrl(addr, config, env = process.env, resolveNamespaceH
 				const hookResult = await resolveNamespaceHook(ns);
 				if (hookResult) return { url: resolveNamespaceUrl(ns, name, hookResult, env) };
 			}
-			if (ns === "@cascade") return { url: `https://cascivo.com/r/${name}.json` };
+			if (ns === "@cascivo" || ns === "@cascade") return { url: `${CASCIVO_HOST}/r/${name}.json` };
 			throw new Error(`Unknown namespace "${ns}". Add it to registries in cascivo.config.ts or check the directory at cascivo.com`);
 		}
 	}
@@ -345,7 +145,7 @@ async function resolveClosure(specs, config, env = process.env, resolveNamespace
 }
 //#endregion
 //#region src/utils/directory.ts
-const DIRECTORY_URL = "https://cascivo.com/r/registries.json";
+const DIRECTORY_URL = `${CASCIVO_HOST}/r/registries.json`;
 async function resolveFromDirectory(ns, fetchFn) {
 	try {
 		let data;
@@ -365,12 +165,95 @@ async function resolveFromDirectory(ns, fetchFn) {
 }
 //#endregion
 //#region src/commands/add.ts
+var add_exports = /* @__PURE__ */ __exportAll({
+	LAYOUT_ALIASES: () => LAYOUT_ALIASES,
+	add: () => add,
+	isThirdParty: () => isThirdParty,
+	resolveBareClosure: () => resolveBareClosure,
+	resolveTemplateTarget: () => resolveTemplateTarget
+});
 /** Dependencies always present in a cascade project — never auto-installed. */
 const ASSUMED_DEPS = new Set(["react", "react-dom"]);
-async function fetchText$1(url) {
-	const res = await fetch(url);
-	if (!res.ok) throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
-	return res.text();
+/**
+* Copied components read `--cascivo-*` custom properties; without
+* @cascivo/tokens or @cascivo/themes imported somewhere, they render unstyled.
+* Print the wiring once after a successful install if neither is a dependency.
+*/
+function hintThemesIfMissing(cwd) {
+	let deps = {};
+	try {
+		const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+		deps = {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+	} catch {}
+	if (deps["@cascivo/themes"] !== void 0 || deps["@cascivo/tokens"] !== void 0) return;
+	console.log("\nStyling: cascivo components read --cascivo-* tokens, which this project does not import yet.");
+	console.log("  npm install @cascivo/themes");
+	console.log("  import '@cascivo/themes/all'   // once, in your entry file");
+	console.log("  <html data-theme=\"light\">      // or any container");
+}
+/** Resolve where a template's own file is written — relative to the project root. */
+function resolveTemplateTarget(cwd, target) {
+	return resolve(cwd, target);
+}
+/**
+* Names from other libraries → the cascivo layout primitive that fills the same
+* role, so `cascivo add flex` installs `layout/stack`. Bare names that already
+* resolve (e.g. `stack` → `layout/stack` via suffix match) need no alias.
+*/
+const LAYOUT_ALIASES = {
+	flex: "stack",
+	box: "stack",
+	hstack: "stack",
+	vstack: "stack",
+	gap: "spacer"
+};
+/**
+* Resolve the transitive closure of bare-name registry entries, following each
+* entry's `registryDependencies`. De-duped by resolved registry name and
+* cycle-safe (an entry is processed at most once). Returns resolved entries in
+* install order plus the names that could not be found. Pure — no I/O.
+*/
+function resolveBareClosure(registry, bareSpecs) {
+	const queue = bareSpecs.map((name) => ({
+		name,
+		requested: true
+	}));
+	const installed = /* @__PURE__ */ new Set();
+	const resolved = [];
+	const missing = [];
+	while (queue.length > 0) {
+		const { name, requested } = queue.shift();
+		const entry = findComponent(registry, LAYOUT_ALIASES[name.toLowerCase()] ?? name);
+		if (!entry) {
+			missing.push(name);
+			continue;
+		}
+		if (installed.has(entry.name)) continue;
+		installed.add(entry.name);
+		resolved.push({
+			entry,
+			requested
+		});
+		for (const dep of entry.registryDependencies ?? []) queue.push({
+			name: dep,
+			requested: false
+		});
+	}
+	return {
+		resolved,
+		missing
+	};
+}
+/**
+* First-party items are hosted on cascivo.com or the cascivo/cascivo GitHub
+* repo (raw file URLs). Anything else gets a review-before-use notice.
+*/
+const FIRST_PARTY_URL = /^https:\/\/(cascivo\.com|raw\.githubusercontent\.com\/cascivo\/cascivo)\//;
+function isThirdParty(itemUrl) {
+	return !FIRST_PARTY_URL.test(itemUrl);
 }
 function isMultiRegistrySpec(name) {
 	return name.startsWith("@") || name.startsWith("http://") || name.startsWith("https://") || name.startsWith("./") || name.startsWith("/") || name.split("/").length >= 3;
@@ -380,81 +263,539 @@ async function add(names, config, opts = {}) {
 		console.error("Usage: cascivo add <component...>");
 		return;
 	}
+	const cwd = opts.cwd ?? process.cwd();
 	const multiSpecs = names.filter(isMultiRegistrySpec);
-	const bareSpecs = names.filter((n) => !isMultiRegistrySpec(n));
-	let lock = await readLock() ?? createLock();
+	let bareSpecs = names.filter((n) => !isMultiRegistrySpec(n));
+	let registry = null;
+	if (bareSpecs.length > 0) {
+		registry = await fetchRegistry(config.registry);
+		const templateNames = new Set(registry.templates.map((t) => t.toLowerCase()));
+		const templateSpecs = bareSpecs.filter((n) => templateNames.has(n.toLowerCase()));
+		if (templateSpecs.length > 0) {
+			bareSpecs = bareSpecs.filter((n) => !templateNames.has(n.toLowerCase()));
+			multiSpecs.push(...templateSpecs.map((n) => `@cascivo/${n.toLowerCase()}`));
+		}
+	}
+	let lock = await readLock(cwd) ?? createLock();
 	if (multiSpecs.length > 0) {
 		const plan = await resolveClosure(multiSpecs, config, process.env, resolveFromDirectory);
 		if (opts.dryRun) {
 			console.log("Dry run — would install:");
 			for (const item of plan.items) {
-				console.log(`  ${item.spec} (${item.item.name}@${item.item.version}) from ${item.itemUrl}`);
-				for (const f of item.item.files) console.log(`    ${f.url}`);
+				const kind = isTemplateItem(item.item) ? " [template]" : "";
+				console.log(`  ${item.spec} (${item.item.name}@${item.item.version})${kind} from ${item.itemUrl}`);
+				for (const f of item.item.files) {
+					const arrow = isTemplateItem(item.item) && f.target ? ` → ${f.target}` : "";
+					console.log(`    ${f.url}${arrow}`);
+				}
+				if (item.item.registryDependencies?.length) console.log(`    components: ${item.item.registryDependencies.join(", ")}`);
 			}
 			return;
 		}
-		const isThirdParty = (itemUrl) => !itemUrl.includes("cascivo.com");
 		for (const { item, itemUrl, registryBase } of plan.items) {
 			if (isThirdParty(itemUrl)) console.log(`\nReview before use — files from non-directory registry: ${registryBase}\n` + (item.files ?? []).map((f) => `  ${f.url}`).join("\n"));
-			await installItem(item, config, lock, registryBase);
+			let fileHashes;
+			try {
+				fileHashes = await installItem(item, config, cwd);
+			} catch (e) {
+				console.error(`Failed to install ${item.name}: ${e instanceof Error ? e.message : e}`);
+				process.exitCode = 1;
+				continue;
+			}
 			lock = updateLockEntry(lock, item.name, {
 				registry: registryBase,
 				version: item.version,
 				installedAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
-				files: {}
+				files: fileHashes
 			});
 		}
-		await writeLock(lock);
-		return;
+		await writeLock(lock, cwd);
+		if (bareSpecs.length === 0) {
+			hintThemesIfMissing(cwd);
+			return;
+		}
 	}
-	const registry = await fetchRegistry(config.registry);
+	if (bareSpecs.length === 0) return;
+	registry ??= await fetchRegistry(config.registry);
 	const missingDeps = /* @__PURE__ */ new Set();
-	for (const name of bareSpecs) {
-		const entry = findComponent(registry, name);
-		if (!entry) {
-			console.error(`Component "${name}" not found in registry. Run "cascivo list".`);
-			continue;
-		}
-		if (entry.type === "chart") {
-			const pkg = entry.install ?? "@cascivo/charts";
-			console.log(`Chart "${entry.name}" is distributed as an npm package.`);
+	const registryBase = config.registry.replace(/\/registry\.json$/, "").replace(/\/r$/, "");
+	for (const spec of bareSpecs) {
+		const alias = LAYOUT_ALIASES[spec.toLowerCase()];
+		if (!alias) continue;
+		const target = findComponent(registry, alias);
+		if (target) console.log(`"${spec}" is not a cascivo component — installing ${target.name} (its ${spec} primitive).`);
+	}
+	const { resolved, missing } = resolveBareClosure(registry, bareSpecs);
+	for (const name of missing) console.error(`Component "${name}" not found in registry. Run "cascivo list".`);
+	const peerFloors = {};
+	for (const { entry } of resolved) for (const [pkg, floor] of Object.entries(entry.peerVersions ?? {})) peerFloors[pkg] = floor;
+	for (const { entry, requested } of resolved) {
+		if (entry.install) {
+			const pkg = entry.install;
+			console.log(`"${entry.name}" is distributed as the npm package ${pkg}.`);
 			console.log(`Install it with: npm install ${pkg}`);
 			console.log(`Then import: import { ${entry.meta.name} } from '${pkg}'`);
+			if (entry.styles) console.log(`And import its stylesheet once: import '${entry.styles}'`);
 			continue;
 		}
 		const outputName = entry.name.includes("/") ? entry.name.split("/").pop() : entry.name;
 		const fileHashes = {};
-		for (const url of entry.files) {
-			const content = await fetchText$1(url);
-			const dest = resolveOutputPath(config.outputDir, outputName, fileName(url));
+		let fetched;
+		try {
+			fetched = await Promise.all(entry.files.map(async (url) => ({
+				url,
+				content: await fetchTextRetry(url)
+			})));
+		} catch (e) {
+			console.error(`Failed to install ${entry.name}: ${e instanceof Error ? e.message : e}`);
+			process.exitCode = 1;
+			continue;
+		}
+		for (const { url, content } of fetched) {
+			const dest = resolveOutputPath(config.outputDir, outputName, fileName(url), cwd);
 			await writeFileSafe(dest, content);
 			fileHashes[dest] = sha256(content);
 		}
 		for (const dep of entry.dependencies) if (!ASSUMED_DEPS.has(dep)) missingDeps.add(dep);
-		const registryBase = config.registry.replace(/\/registry\.json$/, "").replace(/\/r$/, "");
 		lock = updateLockEntry(lock, entry.name, {
 			registry: registryBase,
 			version: entry.version,
 			installedAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
 			files: fileHashes
 		});
-		console.log(`Added ${entry.name} to ${config.outputDir}/${outputName}/`);
+		const suffix = requested ? "" : " (dependency)";
+		console.log(`Added ${entry.name} to ${config.outputDir}/${outputName}/${suffix}`);
 	}
 	if (missingDeps.size > 0) installPackages([...missingDeps]);
-	await writeLock(lock);
+	if (Object.keys(peerFloors).length > 0) {
+		const violations = await checkPeerVersions(cwd, peerFloors);
+		for (const v of violations) {
+			console.error(`\nWarning: ${v.pkg} ${v.installed ? `${v.installed} is` : "is not"} installed, but the copied component source needs ${v.pkg} ${v.required}. Run: npm install ${v.pkg}@latest`);
+			process.exitCode = 1;
+		}
+	}
+	await writeLock(lock, cwd);
+	hintThemesIfMissing(cwd);
 }
-async function installItem(item, config, _lock, _registryBase) {
-	const outputName = item.name.includes("/") ? item.name.split("/").pop() : item.name;
+/**
+* Install a single resolved item, returning a map of written path → content
+* hash for the lockfile. A template writes its own files to their `target`
+* paths (relative to the project root); every other item writes its files under
+* the components output directory. A template's components are installed
+* separately as their own plan entries (via `registryDependencies`).
+*/
+async function installItem(item, config, cwd) {
+	const fileHashes = {};
 	const missingDeps = /* @__PURE__ */ new Set();
-	for (const file of item.files ?? []) try {
-		const content = await fetchText$1(file.url);
-		await writeFileSafe(resolveOutputPath(config.outputDir, outputName, fileName(file.url)), content);
-	} catch {
-		console.warn(`  Could not fetch ${file.url}`);
+	const template = isTemplateItem(item);
+	const outputName = item.name.includes("/") ? item.name.split("/").pop() : item.name;
+	const fetched = await Promise.all((item.files ?? []).map(async (file) => ({
+		file,
+		content: await fetchTextRetry(file.url)
+	})));
+	for (const { file, content } of fetched) {
+		const dest = template && file.target ? resolveTemplateTarget(cwd, file.target) : resolveOutputPath(config.outputDir, outputName, fileName(file.url), cwd);
+		await writeFileSafe(dest, content);
+		fileHashes[dest] = sha256(content);
 	}
 	for (const dep of item.dependencies ?? []) if (!ASSUMED_DEPS.has(dep)) missingDeps.add(dep);
 	if (missingDeps.size > 0) installPackages([...missingDeps]);
-	console.log(`Added ${item.name} to ${config.outputDir}/${outputName}/`);
+	if (template) {
+		const pages = item.files?.filter((f) => f.target).map((f) => f.target) ?? [];
+		console.log(`Installed template ${item.name} (${pages.length} files)`);
+	} else console.log(`Added ${item.name} to ${config.outputDir}/${outputName}/`);
+	return fileHashes;
+}
+//#endregion
+//#region src/commands/create.ts
+/** Version specifier used for every `@cascivo/*` dependency in generated apps. */
+const CASCIVO_DEP = "latest";
+/** Slug suitable for a union-member string literal: lower-kebab, alnum only. */
+function slug(label) {
+	return label.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "section";
+}
+/** PascalCase identifier derived from a free-text label. */
+function pascalCase(label) {
+	const safe = label.trim().split(/[^a-zA-Z0-9]+/).filter(Boolean).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("") || "Section";
+	return /^[0-9]/.test(safe) ? `Section${safe}` : safe;
+}
+/** Normalize the project name into a valid npm package name. */
+function packageName(name) {
+	return name.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "cascivo-app";
+}
+/** Turn raw section labels into unique keyed/component-named sections. */
+function resolveSections(labels) {
+	const seenKeys = /* @__PURE__ */ new Set();
+	const seenComponents = /* @__PURE__ */ new Set();
+	const sections = [];
+	for (const label of labels) {
+		const trimmed = label.trim();
+		if (!trimmed) continue;
+		let key = slug(trimmed);
+		let component = pascalCase(trimmed);
+		let n = 2;
+		while (seenKeys.has(key) || seenComponents.has(component)) {
+			key = `${slug(trimmed)}-${n}`;
+			component = `${pascalCase(trimmed)}${n}`;
+			n++;
+		}
+		seenKeys.add(key);
+		seenComponents.add(component);
+		sections.push({
+			key,
+			label: trimmed,
+			component
+		});
+	}
+	return sections.length > 0 ? sections : [{
+		key: "home",
+		label: "Home",
+		component: "Home"
+	}];
+}
+function packageJson(opts) {
+	const pkg = {
+		name: packageName(opts.name),
+		private: true,
+		version: "0.0.0",
+		type: "module",
+		scripts: {
+			dev: "vite",
+			build: "tsc && vite build",
+			preview: "vite preview"
+		},
+		dependencies: {
+			"@cascivo/core": CASCIVO_DEP,
+			"@cascivo/react": CASCIVO_DEP,
+			"@cascivo/themes": CASCIVO_DEP,
+			"@cascivo/tokens": CASCIVO_DEP,
+			react: "^19.0.0",
+			"react-dom": "^19.0.0"
+		},
+		devDependencies: {
+			"@types/react": "^19.0.0",
+			"@types/react-dom": "^19.0.0",
+			"@vitejs/plugin-react": "^5.0.0",
+			typescript: "^5.7.0",
+			vite: "^7.0.0"
+		}
+	};
+	return JSON.stringify(pkg, null, 2) + "\n";
+}
+function tsconfig() {
+	return JSON.stringify({
+		compilerOptions: {
+			target: "ES2022",
+			useDefineForClassFields: true,
+			lib: [
+				"ES2022",
+				"DOM",
+				"DOM.Iterable"
+			],
+			module: "ESNext",
+			skipLibCheck: true,
+			moduleResolution: "bundler",
+			allowImportingTsExtensions: true,
+			resolveJsonModule: true,
+			isolatedModules: true,
+			moduleDetection: "force",
+			noEmit: true,
+			jsx: "react-jsx",
+			strict: true,
+			noUnusedLocals: true,
+			noUnusedParameters: true,
+			noFallthroughCasesInSwitch: true
+		},
+		include: ["src"]
+	}, null, 2) + "\n";
+}
+function viteConfig() {
+	return `import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [react()],
+})
+`;
+}
+function indexHtml(opts) {
+	return `<!doctype html>
+<html lang="en" data-theme="${opts.theme}">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${opts.name}</title>
+    <style>
+      @layer cascivo.reset, cascivo.tokens, cascivo.component, cascivo.theme;
+      @layer cascivo.reset {
+        *,
+        *::before,
+        *::after {
+          box-sizing: border-box;
+          margin: 0;
+          padding: 0;
+        }
+      }
+      html,
+      body,
+      #root {
+        height: 100%;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"><\/script>
+  </body>
+</html>
+`;
+}
+function mainTsx() {
+	return `import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App'
+
+const root = document.getElementById('root')
+if (root) {
+  ReactDOM.createRoot(root).render(
+    <React.StrictMode>
+      <App />
+    </React.StrictMode>,
+  )
+}
+`;
+}
+function viteEnv() {
+	return `/// <reference types="vite/client" />\n`;
+}
+function appTsx(opts, sections) {
+	const sectionImports = sections.map((s) => `import { ${s.component} } from './sections/${s.component}'`).join("\n");
+	const unionType = sections.map((s) => `'${s.key}'`).join(" | ");
+	const navItems = sections.map((s) => `    {
+      label: '${s.label.replace(/'/g, "\\'")}',
+      active: section.value === '${s.key}',
+      onClick: (e) => {
+        e.preventDefault()
+        section.value = '${s.key}'
+      },
+    },`).join("\n");
+	const renderedSections = sections.map((s) => `      {section.value === '${s.key}' && <${s.component} />}`).join("\n");
+	return `'use client'
+import { signal, useSignals } from '@cascivo/core'
+import { AppShell, ShellHeader, SideNav, type SideNavItem } from '@cascivo/react'
+${sectionImports}
+
+import '@cascivo/tokens'
+import '@cascivo/themes/${opts.theme}.css'
+import '@cascivo/react/styles.css'
+
+type Section = ${unionType}
+
+const section = signal<Section>('${sections[0].key}')
+
+export default function App() {
+  useSignals()
+
+  const navItems: SideNavItem[] = [
+${navItems}
+  ]
+
+  return (
+    <AppShell
+      header={<ShellHeader brand={{ name: '${opts.name.replace(/'/g, "\\'")}' }} />}
+      nav={<SideNav items={navItems} />}
+    >
+${renderedSections}
+    </AppShell>
+  )
+}
+`;
+}
+function sectionTsx(section) {
+	return `import { Card, CardContent, CardHeader, CardTitle, Heading, Text } from '@cascivo/react'
+
+export function ${section.component}() {
+  return (
+    <div
+      style={{
+        display: 'grid',
+        gap: 'var(--cascivo-space-6)',
+        padding: 'var(--cascivo-space-6)',
+        maxWidth: '64rem',
+      }}
+    >
+      <div style={{ display: 'grid', gap: 'var(--cascivo-space-2)' }}>
+        <Heading level={1}>${section.label}</Heading>
+        <Text muted>
+          Edit <code>src/sections/${section.component}.tsx</code> to build out this page.
+        </Text>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Get started</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <Text>
+            This page is wired into the app shell. Add components with{' '}
+            <code>npx cascivo add &lt;component&gt;</code>.
+          </Text>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}
+`;
+}
+function cascivoConfig(opts) {
+	return `import type { CascadeConfig } from 'cascivo'
+
+const config: CascadeConfig = {
+  registry: '${CASCIVO_HOST}/registry.json',
+  outputDir: 'src/components/ui',
+  theme: '${opts.theme}',
+}
+
+export default config
+`;
+}
+function gitignore() {
+	return `node_modules
+dist
+*.local
+.DS_Store
+`;
+}
+function readme(opts) {
+	return `# ${opts.name}
+
+A [cascivo](https://cascivo.com) app — Vite + React + TypeScript, pre-wired with
+the cascivo app shell, side navigation, and the \`${opts.theme}\` theme.
+
+## Develop
+
+\`\`\`sh
+npm install
+npm run dev
+\`\`\`
+
+## Structure
+
+- \`src/App.tsx\` — app shell, navigation, and section routing
+- \`src/sections/\` — one component per nav item
+
+Add more components with \`npx cascivo add <component>\`.
+`;
+}
+/** Build the full set of files for a new cascivo app. Pure — no filesystem I/O. */
+function buildScaffold(opts) {
+	const sections = resolveSections(opts.sections);
+	return [
+		{
+			path: "package.json",
+			contents: packageJson(opts)
+		},
+		{
+			path: "tsconfig.json",
+			contents: tsconfig()
+		},
+		{
+			path: "vite.config.ts",
+			contents: viteConfig()
+		},
+		{
+			path: "index.html",
+			contents: indexHtml(opts)
+		},
+		{
+			path: "cascivo.config.ts",
+			contents: cascivoConfig(opts)
+		},
+		{
+			path: ".gitignore",
+			contents: gitignore()
+		},
+		{
+			path: "README.md",
+			contents: readme(opts)
+		},
+		{
+			path: "src/main.tsx",
+			contents: mainTsx()
+		},
+		{
+			path: "src/vite-env.d.ts",
+			contents: viteEnv()
+		},
+		{
+			path: "src/App.tsx",
+			contents: appTsx(opts, sections)
+		},
+		...sections.map((s) => ({
+			path: `src/sections/${s.component}.tsx`,
+			contents: sectionTsx(s)
+		}))
+	];
+}
+function flagValue$1(args, key) {
+	const eq = args.find((a) => a.startsWith(`--${key}=`));
+	if (eq) return eq.slice(key.length + 3);
+	const idx = args.indexOf(`--${key}`);
+	const next = idx !== -1 ? args[idx + 1] : void 0;
+	return next && !next.startsWith("--") ? next : void 0;
+}
+const DEFAULT_SECTIONS = [
+	"Dashboard",
+	"Reports",
+	"Settings"
+];
+async function create(args, cwd = process.cwd()) {
+	const yes = args.includes("--yes") || args.includes("-y");
+	const nameArg = args.find((a) => !a.startsWith("-"));
+	const themeArg = flagValue$1(args, "theme");
+	const sectionsArg = flagValue$1(args, "sections");
+	const rl = !yes && stdin.isTTY ? createInterface({
+		input: stdin,
+		output: stdout
+	}) : null;
+	try {
+		let name = nameArg;
+		if (!name && rl) name = (await rl.question("Project name? [my-cascivo-app]: ")).trim();
+		name = name || "my-cascivo-app";
+		let theme = (themeArg ?? "").toLowerCase();
+		if (!THEMES.includes(theme) && rl) theme = (await rl.question(`Theme? (${THEMES.join("/")}) [light]: `)).trim().toLowerCase();
+		const resolvedTheme = THEMES.includes(theme) ? theme : "light";
+		let sectionsInput = sectionsArg;
+		if (!sectionsInput && rl) sectionsInput = (await rl.question(`Nav sections? (comma-separated) [${DEFAULT_SECTIONS.join(", ")}]: `)).trim();
+		const sections = (sectionsInput ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+		const opts = {
+			name,
+			theme: resolvedTheme,
+			sections: sections.length > 0 ? sections : DEFAULT_SECTIONS
+		};
+		const targetDir = join(cwd, name);
+		if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+			console.error(`Target directory "${name}" already exists and is not empty.`);
+			process.exitCode = 1;
+			return;
+		}
+		const files = buildScaffold(opts);
+		for (const file of files) await writeFileSafe(join(targetDir, file.path), file.contents);
+		console.log(`\nCreated ${name} with the ${resolvedTheme} theme (${files.length} files).`);
+		const templateSpec = flagValue$1(args, "template");
+		if (templateSpec) {
+			const { add } = await Promise.resolve().then(() => add_exports);
+			const { loadConfig } = await import("./config-BsyJbMvD.mjs").then((n) => n.i);
+			console.log(`\nInstalling template "${templateSpec}"…`);
+			await add([templateSpec], await loadConfig(), { cwd: targetDir });
+		}
+		console.log("\nNext steps:");
+		console.log(`  cd ${name}`);
+		console.log("  npm install");
+		console.log("  npm run dev");
+	} finally {
+		rl?.close();
+	}
 }
 //#endregion
 //#region src/commands/doctor.ts
@@ -465,6 +806,47 @@ const BANNED_HOOKS = [
 	"useContext",
 	"useReducer"
 ];
+/**
+* Blank out comments and string/template-literal contents so identifier scans
+* only match real code. A mention of `useEffect` in a comment must not trip
+* the no-react-hooks rule. Single pass — a `//` inside a string (URLs) is not
+* treated as a comment.
+*/
+function stripCommentsAndStrings(source) {
+	let out = "";
+	let i = 0;
+	const n = source.length;
+	while (i < n) {
+		const c = source[i];
+		const next = source[i + 1];
+		if (c === "/" && next === "/") while (i < n && source[i] !== "\n") i++;
+		else if (c === "/" && next === "*") {
+			i += 2;
+			while (i < n && !(source[i] === "*" && source[i + 1] === "/")) i++;
+			i += 2;
+		} else if (c === "'" || c === "\"") {
+			i++;
+			while (i < n && source[i] !== c) {
+				if (source[i] === "\\") i++;
+				i++;
+			}
+			i++;
+			out += c + c;
+		} else if (c === "`") {
+			i++;
+			while (i < n && source[i] !== "`") {
+				if (source[i] === "\\") i++;
+				i++;
+			}
+			i++;
+			out += "``";
+		} else {
+			out += c;
+			i++;
+		}
+	}
+	return out;
+}
 async function runDoctor(root) {
 	const violations = [];
 	const componentsDir = join(root, "packages", "components", "src");
@@ -479,7 +861,8 @@ async function runDoctor(root) {
 		const tsxPath = join(componentsDir, name, `${name}.tsx`);
 		if (!existsSync(tsxPath)) continue;
 		const content = readFileSync(tsxPath, "utf8");
-		for (const hook of BANNED_HOOKS) if (new RegExp(`\\b${hook}\\b`).test(content)) violations.push({
+		const code = stripCommentsAndStrings(content);
+		for (const hook of BANNED_HOOKS) if (new RegExp(`\\b${hook}\\b`).test(code)) violations.push({
 			file: tsxPath,
 			rule: "no-react-hooks",
 			detail: `Banned hook '${hook}' in ${name}.tsx`
@@ -623,19 +1006,21 @@ async function generate(args, config) {
 }
 //#endregion
 //#region src/commands/init.ts
-const THEMES$1 = [
-	"light",
-	"dark",
-	"warm"
-];
+function flagValue(args, key) {
+	const eq = args.find((a) => a.startsWith(`--${key}=`));
+	if (eq) return eq.slice(key.length + 3);
+	const idx = args.indexOf(`--${key}`);
+	const next = idx !== -1 ? args[idx + 1] : void 0;
+	return next && !next.startsWith("--") ? next : void 0;
+}
 async function promptTheme() {
 	const rl = createInterface({
 		input: stdin,
 		output: stdout
 	});
 	try {
-		const answer = (await rl.question("Theme? (light/dark/warm) [light]: ")).trim().toLowerCase();
-		return THEMES$1.includes(answer) ? answer : "light";
+		const answer = (await rl.question(`Theme? (${THEMES.join("/")}) [light]: `)).trim().toLowerCase();
+		return THEMES.includes(answer) ? answer : "light";
 	} finally {
 		rl.close();
 	}
@@ -644,17 +1029,25 @@ function configFileContents(theme) {
 	return `import type { CascadeConfig } from 'cascivo'
 
 const config: CascadeConfig = {
-  registry: '${DEFAULT_CONFIG.registry}',
-  outputDir: '${DEFAULT_CONFIG.outputDir}',
+  registry: '${DEFAULT_CONFIG$1.registry}',
+  outputDir: '${DEFAULT_CONFIG$1.outputDir}',
   theme: '${theme}',
 }
 
 export default config
 `;
 }
-async function init(cwd = process.cwd()) {
+async function init(args = [], cwd = process.cwd()) {
+	const yes = args.includes("--yes") || args.includes("-y");
+	const themeArg = flagValue(args, "theme")?.toLowerCase();
+	if (themeArg !== void 0 && !THEMES.includes(themeArg)) {
+		console.error(`Unknown theme "${themeArg}". Available: ${THEMES.join(", ")}`);
+		process.exitCode = 1;
+		return;
+	}
 	installPackages(["@cascivo/core", "@cascivo/tokens"], cwd);
-	const theme = await promptTheme();
+	const interactive = themeArg === void 0 && !yes && stdin.isTTY;
+	const theme = themeArg ?? (interactive ? await promptTheme() : "light");
 	await writeFileSafe(join(cwd, "cascivo.config.ts"), configFileContents(theme));
 	console.log(`\nCreated cascivo.config.ts (theme: ${theme})`);
 	console.log("Import the theme in your root CSS or entry file:");
@@ -667,9 +1060,12 @@ async function init(cwd = process.cwd()) {
 //#region src/commands/list.ts
 const TYPE_LABELS = {
 	component: "Components",
-	layout: "Layouts",
-	block: "Blocks",
-	section: "Sections"
+	layout: "Layouts (copy-paste)",
+	block: "Blocks (copy-paste)",
+	section: "Sections (copy-paste)",
+	chart: "Charts (npm: @cascivo/charts)",
+	flow: "Flow (npm: @cascivo/flow)",
+	editor: "Editor (npm: @cascivo/editor)"
 };
 /** Render a group of entries as an aligned text table (no section header). */
 function formatGroup(entries) {
@@ -716,9 +1112,30 @@ async function list(config, options = {}) {
 		return existsSync(join(process.cwd(), config.outputDir, outputName));
 	});
 	console.log(formatList(components));
+	console.log("\nTip: install any entry by its bare name — `cascivo add stack` resolves to `layout/stack`. Layout primitives (Stack, Grid, AutoGrid, Columns, Spacer, Center) replace inline-style layout; see docs/cookbooks/layout-and-spacing.md.");
 }
 //#endregion
 //#region src/commands/registry.ts
+/**
+* Validate every template item in an index: each must pass `validateTemplate`,
+* and any bare `registryDependencies` not present in the same index produce a
+* warning (they are expected to resolve from another registry at install time).
+* Returns `{ errors, warnings }`.
+*/
+function validateTemplates(index) {
+	const errors = [];
+	const warnings = [];
+	const localNames = new Set(index.items.map((i) => i.name));
+	for (const item of index.items) {
+		if (!isTemplateItem(item)) continue;
+		for (const e of validateTemplate(item)) errors.push(`template "${item.name}": ${e}`);
+		for (const dep of item.registryDependencies ?? []) if (!(dep.includes("/") || dep.startsWith("@") || dep.startsWith("http")) && !localNames.has(dep)) warnings.push(`template "${item.name}": component "${dep}" is not in this index — it must resolve from another registry at install time`);
+	}
+	return {
+		errors,
+		warnings
+	};
+}
 async function registryBuild(args) {
 	let inFile = "cascade-registry.json";
 	let outDir = "public/r";
@@ -748,6 +1165,13 @@ async function registryBuild(args) {
 		process.exitCode = 1;
 		return;
 	}
+	const templateResult = validateTemplates(index);
+	for (const w of templateResult.warnings) console.warn(`warn: ${w}`);
+	if (templateResult.errors.length > 0) {
+		for (const e of templateResult.errors) console.error(`error: ${e}`);
+		process.exitCode = 1;
+		return;
+	}
 	const outPath = resolve(outDir);
 	await buildRegistry(index, outPath);
 	console.log(`cascade registry build: wrote static output to ${outPath}`);
@@ -763,7 +1187,7 @@ async function search(args, config) {
 	const registryFilter = nsFlag !== -1 ? args[nsFlag + 1] : void 0;
 	const query = args.filter((a, i) => a !== "--registry" && args[i - 1] !== "--registry").join(" ").trim();
 	if (!query) {
-		console.error("Usage: cascade search <query> [--registry @ns]");
+		console.error("Usage: cascivo search <query> [--registry @ns]");
 		return;
 	}
 	const results = [];
@@ -800,25 +1224,224 @@ async function search(args, config) {
 	}
 }
 //#endregion
+//#region ../theme-kit/src/config.ts
+const DEFAULT_CONFIG = {
+	baseMode: "light",
+	accentHue: 250,
+	accentChroma: .2,
+	radiusBase: .375,
+	fontFamily: "system",
+	presetId: "light"
+};
+//#endregion
+//#region ../theme-kit/src/hash.ts
+/** Decode a hash produced by {@link configToHash}. Returns null on malformed
+*  input; unknown/missing fields fall back to {@link DEFAULT_CONFIG}. */
+function hashToConfig(hash) {
+	if (!hash) return null;
+	try {
+		const base64 = hash.replace(/-/g, "+").replace(/_/g, "/");
+		const json = atob(base64);
+		const parsed = JSON.parse(json);
+		return {
+			baseMode: parsed.baseMode === "dark" ? "dark" : "light",
+			accentHue: typeof parsed.accentHue === "number" ? parsed.accentHue : DEFAULT_CONFIG.accentHue,
+			accentChroma: typeof parsed.accentChroma === "number" ? parsed.accentChroma : DEFAULT_CONFIG.accentChroma,
+			radiusBase: typeof parsed.radiusBase === "number" ? parsed.radiusBase : DEFAULT_CONFIG.radiusBase,
+			fontFamily: parsed.fontFamily ?? DEFAULT_CONFIG.fontFamily,
+			presetId: parsed.presetId ?? null
+		};
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region ../theme-kit/src/css.ts
+const FONT_STACKS = {
+	geometric: "'Futura', 'Century Gothic', 'Trebuchet MS', ui-sans-serif, sans-serif",
+	humanist: "'Gill Sans', 'Trebuchet MS', 'Calibri', ui-sans-serif, sans-serif",
+	transitional: "'Optima', 'Candara', 'Palatino Linotype', ui-sans-serif, sans-serif",
+	mono: "ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace"
+};
+const BASE_LIGHT = `
+    color-scheme: light;
+    --cascivo-color-background: oklch(1 0 0);
+    --cascivo-color-surface: oklch(0.985 0.002 264);
+    --cascivo-color-surface-2: oklch(0.967 0.003 264);
+    --cascivo-color-bg: var(--cascivo-color-background);
+    --cascivo-color-bg-subtle: var(--cascivo-color-surface);
+    --cascivo-color-surface-raised: var(--cascivo-color-surface);
+    --cascivo-color-surface-overlay: var(--cascivo-color-background);
+    --cascivo-color-border: oklch(0.928 0.006 264);
+    --cascivo-color-border-strong: oklch(0.872 0.008 264);
+    --cascivo-border-subtle: oklch(0.928 0.006 264);
+    --cascivo-border-default: oklch(0.872 0.008 264);
+    --cascivo-border-strong: oklch(0.707 0.015 264);
+    --cascivo-color-foreground: oklch(0.145 0.005 264);
+    --cascivo-color-foreground-muted: oklch(0.554 0.018 264);
+    --cascivo-color-text: var(--cascivo-color-foreground);
+    --cascivo-color-text-subtle: oklch(0.446 0.018 264);
+    --cascivo-color-text-muted: oklch(0.707 0.015 264);
+    --cascivo-color-text-on-accent: oklch(1 0 0);
+    --cascivo-color-text-on-destructive: oklch(1 0 0);
+    --cascivo-color-primary: oklch(0.205 0 0);
+    --cascivo-color-primary-fg: oklch(0.985 0 0);
+    --cascivo-color-primary-hover: oklch(0.27 0 0);
+    --cascivo-color-primary-active: oklch(0.32 0 0);
+    --cascivo-color-active-bg: oklch(0.145 0.005 264 / 6%);
+    --cascivo-color-destructive: oklch(0.54 0.188 22);
+    --cascivo-color-destructive-hover: oklch(0.448 0.17 22);
+    --cascivo-color-destructive-subtle: oklch(0.971 0.013 22);
+    --cascivo-color-error: oklch(0.628 0.188 22);
+    --cascivo-color-warning: oklch(0.768 0.145 75);
+    --cascivo-color-success: oklch(0.648 0.15 145);
+    --cascivo-color-success-subtle: oklch(0.982 0.018 145);
+    --cascivo-color-warning-subtle: oklch(0.98 0.02 75);
+    --cascivo-color-info: oklch(0.546 0.224 250);
+    --cascivo-color-info-subtle: oklch(0.97 0.025 250);
+    --cascivo-color-success-foreground: oklch(0.45 0.14 145);
+    --cascivo-color-warning-foreground: oklch(0.5 0.14 75);
+    --cascivo-shadow-xs: 0 1px 2px oklch(0 0 0 / 0.05);
+    --cascivo-shadow-sm: 0 1px 3px oklch(0 0 0 / 0.07), 0 1px 2px oklch(0 0 0 / 0.04);
+    --cascivo-shadow-md: 0 2px 8px oklch(0 0 0 / 0.07), 0 1px 2px oklch(0 0 0 / 0.04);
+    --cascivo-shadow-overlay: 0 4px 32px oklch(0 0 0 / 0.16), 0 0 0 1px oklch(0 0 0 / 0.04);
+    --cascivo-shadow-lg: var(--cascivo-shadow-overlay);
+    --cascivo-ring-width: 2px;
+    --cascivo-ring-offset: 0px;
+    --cascivo-ring-color: color-mix(in oklch, var(--cascivo-color-accent) 55%, transparent);
+    --cascivo-focus-ring: 0 0 0 var(--cascivo-ring-width) var(--cascivo-ring-color);`;
+const BASE_DARK = `
+    color-scheme: dark;
+    --cascivo-color-background: oklch(0.145 0.005 250);
+    --cascivo-color-surface: oklch(0.185 0.007 250);
+    --cascivo-color-surface-2: oklch(0.22 0.008 250);
+    --cascivo-color-bg: var(--cascivo-color-background);
+    --cascivo-color-bg-subtle: var(--cascivo-color-surface);
+    --cascivo-color-surface-raised: var(--cascivo-color-surface-2);
+    --cascivo-color-surface-overlay: var(--cascivo-color-surface);
+    --cascivo-color-border: oklch(1 0 0 / 10%);
+    --cascivo-color-border-strong: oklch(1 0 0 / 16%);
+    --cascivo-border-subtle: oklch(1 0 0 / 0.06);
+    --cascivo-border-default: oklch(1 0 0 / 0.1);
+    --cascivo-border-strong: oklch(1 0 0 / 0.2);
+    --cascivo-color-foreground: oklch(0.985 0.002 264);
+    --cascivo-color-foreground-muted: oklch(0.707 0.015 264);
+    --cascivo-color-text: var(--cascivo-color-foreground);
+    --cascivo-color-text-subtle: oklch(0.707 0.015 264);
+    --cascivo-color-text-muted: oklch(0.554 0.018 264);
+    --cascivo-color-text-on-accent: oklch(0.145 0.005 250);
+    --cascivo-color-text-on-destructive: oklch(1 0 0);
+    --cascivo-color-primary: oklch(0.922 0 0);
+    --cascivo-color-primary-fg: oklch(0.205 0 0);
+    --cascivo-color-primary-hover: oklch(0.86 0 0);
+    --cascivo-color-primary-active: oklch(0.8 0 0);
+    --cascivo-color-active-bg: oklch(1 0 0 / 8%);
+    --cascivo-color-destructive: oklch(0.72 0.16 22);
+    --cascivo-color-destructive-hover: oklch(0.628 0.188 22);
+    --cascivo-color-destructive-subtle: oklch(0.628 0.188 22 / 0.1);
+    --cascivo-color-error: oklch(0.72 0.16 22);
+    --cascivo-color-warning: oklch(0.82 0.13 75);
+    --cascivo-color-success: oklch(0.72 0.13 145);
+    --cascivo-color-success-subtle: oklch(0.72 0.13 145 / 0.1);
+    --cascivo-color-warning-subtle: oklch(0.82 0.13 75 / 0.1);
+    --cascivo-color-info: oklch(0.65 0.2 250);
+    --cascivo-color-info-subtle: oklch(0.65 0.2 250 / 0.1);
+    --cascivo-color-success-foreground: oklch(0.72 0.13 145);
+    --cascivo-color-warning-foreground: oklch(0.82 0.13 75);
+    --cascivo-shadow-xs: none;
+    --cascivo-shadow-sm: 0 1px 3px oklch(0 0 0 / 0.4);
+    --cascivo-shadow-md: 0 2px 8px oklch(0 0 0 / 0.45);
+    --cascivo-shadow-overlay: 0 4px 32px oklch(0 0 0 / 0.6), 0 0 0 1px oklch(1 0 0 / 0.06);
+    --cascivo-shadow-lg: var(--cascivo-shadow-overlay);
+    --cascivo-ring-width: 2px;
+    --cascivo-ring-offset: 0px;
+    --cascivo-ring-color: color-mix(in oklch, var(--cascivo-color-accent) 65%, transparent);
+    --cascivo-focus-ring: 0 0 0 var(--cascivo-ring-width) var(--cascivo-ring-color);`;
+function configToCSS(config, options = {}) {
+	const { previewMode = false, themeName = "create-custom" } = options;
+	const light = config.baseMode === "light";
+	const h = config.accentHue;
+	const c = config.accentChroma;
+	const acc = (l, chroma = c) => `oklch(${l} ${chroma.toFixed(3)} ${h})`;
+	const lines = [
+		`/* Add to your project CSS after importing the base theme: */`,
+		`/* @import '@cascivo/themes/${config.baseMode}.css'; */`,
+		`/* @import './theme.css'; */`,
+		``,
+		`@layer cascivo.theme {`,
+		`  [data-theme="${themeName}"] {`
+	];
+	if (previewMode) {
+		lines.push(light ? BASE_LIGHT : BASE_DARK);
+		lines.push(``);
+	}
+	lines.push(`    /* ── Accent ─────────────────────────────────── */`, `    --cascivo-color-accent: ${acc(light ? .52 : .65)};`, `    --cascivo-color-accent-foreground: ${light ? "oklch(1 0 0)" : `oklch(0.145 0.005 ${h})`};`, `    --cascivo-color-accent-hover: ${acc(light ? .45 : .707)};`, `    --cascivo-color-accent-active: ${acc(light ? .373 : .808, Math.min(c, .155))};`, `    --cascivo-color-accent-subtle: ${acc(light ? .97 : .623, .025)};`, `    --cascivo-color-accent-muted: ${acc(light ? .932 : .623, light ? .055 : c * .2)};`, ``, `    /* ── Radius ─────────────────────────────────── */`, `    --cascivo-radius-base: ${config.radiusBase}rem;`, `    --cascivo-radius-control: var(--cascivo-radius-base);`, `    --cascivo-radius-surface: calc(var(--cascivo-radius-base) * 1.66);`, `    --cascivo-radius-indicator: calc(var(--cascivo-radius-base) / 2);`, `    --cascivo-radius-full: 9999px;`, `    --cascivo-radius-component: var(--cascivo-radius-base);`, `    --cascivo-radius-button: var(--cascivo-radius-base);`, `    --cascivo-radius-input: var(--cascivo-radius-base);`, `    --cascivo-radius-card: calc(var(--cascivo-radius-base) * 1.66);`, `    --cascivo-radius-badge: var(--cascivo-radius-full);`, `    --cascivo-radius-modal: calc(var(--cascivo-radius-base) * 2);`);
+	if (config.fontFamily !== "system") {
+		lines.push(``);
+		lines.push(`    /* ── Font ───────────────────────────────────── */`);
+		lines.push(`    --cascivo-font-sans: ${FONT_STACKS[config.fontFamily] ?? FONT_STACKS["humanist"]};`);
+	}
+	lines.push(`  }`);
+	lines.push(`}`);
+	return lines.join("\n");
+}
+//#endregion
 //#region src/commands/theme.ts
-const THEMES = [
-	"light",
-	"dark",
-	"warm",
-	"flat",
-	"minimal",
-	"midnight",
-	"pastel",
-	"brutalist",
-	"corporate",
-	"terminal",
-	"cyberpunk",
-	"arcade"
-];
+const THEME_NAME_RE = /^[a-z][a-z0-9-]*$/;
+/** Read a `--key value` or `--key=value` flag from an argv slice. */
+function flag(args, key) {
+	const eq = args.find((a) => a.startsWith(`--${key}=`));
+	if (eq) return eq.slice(key.length + 3);
+	const idx = args.indexOf(`--${key}`);
+	const next = idx !== -1 ? args[idx + 1] : void 0;
+	return next && !next.startsWith("--") ? next : void 0;
+}
+/**
+* `cascivo theme create <name> --from <hash>` — turn a /create theme-builder
+* config (the `#hash` in the builder URL, or its "Copy CLI command" output) into
+* an owned `<name>.theme.css` in the project. Uses the same generator the builder
+* previews with, so the file matches the preview exactly.
+*/
+async function themeCreate(args, cwd) {
+	const name = args.find((a) => !a.startsWith("--"));
+	const hash = flag(args, "from");
+	const dryRun = args.includes("--dry-run");
+	if (!name || !hash) {
+		console.error("Usage: cascivo theme create <name> --from <hash> [--out <path>]");
+		console.error("Get <hash> from the theme builder at https://cascivo.com/create (Copy CLI command).");
+		return;
+	}
+	if (!THEME_NAME_RE.test(name)) {
+		console.error(`Invalid theme name "${name}". Use lowercase letters, digits, and dashes.`);
+		return;
+	}
+	const config = hashToConfig(hash);
+	if (!config) {
+		console.error("Could not decode --from. Copy the command again from the theme builder.");
+		return;
+	}
+	const css = configToCSS(config, { themeName: name });
+	if (dryRun) {
+		console.log(css);
+		return;
+	}
+	await writeFileSafe(resolve(cwd, flag(args, "out") ?? `${name}.theme.css`), css);
+	console.log(`\n✓ Wrote ${name}.theme.css`);
+	console.log(`\nImport the base theme and your overlay in your entry CSS:`);
+	console.log(`  @import '@cascivo/themes/${config.baseMode}.css';`);
+	console.log(`  @import './${name}.theme.css';`);
+	console.log(`Then set it on a container:`);
+	console.log(`  <div data-theme="${name}">…</div>`);
+}
 async function theme(args) {
 	const [sub, name] = args;
+	if (sub === "create") {
+		await themeCreate(args.slice(1), process.cwd());
+		return;
+	}
 	if (sub !== "add" || !name) {
-		console.error(`Usage: cascade theme add <${THEMES.join("|")}>`);
+		console.error(`Usage: cascivo theme add <${THEMES.join("|")}>`);
+		console.error(`       cascivo theme create <name> --from <hash>`);
 		return;
 	}
 	if (!THEMES.includes(name)) {
@@ -1051,11 +1674,6 @@ async function confirm(question) {
 		rl.close();
 	}
 }
-async function fetchText(url) {
-	const res = await fetch(url);
-	if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
-	return res.text();
-}
 async function update(name, config, opts = {}) {
 	if (opts.check) return updateCheck(config);
 	if (!name) {
@@ -1093,9 +1711,9 @@ async function threeWayUpdate(name, upstreamEntry, baseItem, config, opts) {
 		const fname = fileName(url);
 		const baseFile = baseItem.files.find((f) => fileName(f.url) === fname);
 		const dest = resolveOutputPath(config.outputDir, outputName, fname);
-		const upstream = await fetchText(url);
+		const upstream = await fetchTextRetry(url);
 		const local = existsSync(dest) ? await readFile(dest, "utf8") : "";
-		const base = baseFile ? await fetchText(baseFile.url) : "";
+		const base = baseFile ? await fetchTextRetry(baseFile.url) : "";
 		if (base === "" && local === "") {
 			summaries.push({
 				file: fname,
@@ -1165,12 +1783,13 @@ async function twoWayUpdate(name, entry, config, opts) {
 	if (!entry) return;
 	const pending = [];
 	for (const url of entry.files) {
-		const res = await fetch(url);
-		if (!res.ok) {
-			console.error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
+		let latest;
+		try {
+			latest = await fetchTextRetry(url);
+		} catch (e) {
+			console.error(e instanceof Error ? e.message : String(e));
 			return;
 		}
-		const latest = await res.text();
 		const dest = resolveOutputPath(config.outputDir, entry.name, fileName(url));
 		const current = await readFileSafe(dest);
 		if (current === null) {
@@ -1208,7 +1827,14 @@ async function updateCheck(config) {
 	for (const [name, entry] of Object.entries(lock.items)) {
 		const current = findComponent(registry, name);
 		if (!current) continue;
-		if (current.version !== entry.version) {
+		if (current.fileHashes && Object.keys(current.fileHashes).length > 0) {
+			const lockByBase = new Map(Object.entries(entry.files).map(([dest, hash]) => [dest.split("/").pop(), hash]));
+			const changed = Object.entries(current.fileHashes).filter(([file, hash]) => lockByBase.get(file) !== hash);
+			if (changed.length > 0) {
+				console.log(`${name}: ${changed.length} file(s) changed upstream (${entry.version} → ${current.version})`);
+				outdated++;
+			}
+		} else if (current.version !== entry.version) {
 			console.log(`${name}: ${entry.version} → ${current.version}`);
 			outdated++;
 		}
@@ -1220,10 +1846,48 @@ async function updateCheck(config) {
 }
 //#endregion
 //#region src/commands/view.ts
+/** Render an item's details as text. Pure, so it can be unit-tested. */
+function formatItem(item) {
+	const lines = [];
+	lines.push(`\n${item.name}  v${item.version}`);
+	lines.push(`Type: ${item.type}${item.category ? ` / ${item.category}` : ""}`);
+	lines.push(item.description);
+	if (item.author) lines.push(`Author: ${item.author}`);
+	if (item.license) lines.push(`License: ${item.license}`);
+	if (item.homepage) lines.push(`Homepage: ${item.homepage}`);
+	if (item.install) {
+		lines.push(`Distribution: npm package — pnpm add ${item.install}`);
+		if (item.styles) lines.push(`Stylesheet: import '${item.styles}' (required)`);
+	} else if (!isTemplateItem(item)) lines.push(`Distribution: copy-paste — npx cascivo add ${item.name}`);
+	if (isTemplateItem(item)) try {
+		const meta = asTemplateMeta(item.meta);
+		lines.push(`\nTemplate: ${meta.intent}`);
+		lines.push(`Framework: ${meta.framework}`);
+		if (meta.demoUrl) lines.push(`Demo: ${meta.demoUrl}`);
+		if (meta.pages?.length) {
+			lines.push("Pages:");
+			for (const p of meta.pages) lines.push(`  ${p.name} → ${p.target}`);
+		}
+	} catch {}
+	if (item.changelog?.length) {
+		lines.push("\nChangelog:");
+		for (const c of item.changelog.slice(0, 5)) lines.push(`  ${c.version}: ${c.note}`);
+	}
+	if (item.files?.length) {
+		lines.push("\nFiles:");
+		for (const f of item.files) lines.push(`  ${f.url}${f.target ? ` → ${f.target}` : ""}`);
+	}
+	if (item.dependencies?.length) lines.push(`\nDependencies: ${item.dependencies.join(", ")}`);
+	if (item.registryDependencies?.length) {
+		const label = isTemplateItem(item) ? "Components" : "Registry dependencies";
+		lines.push(`${label}: ${item.registryDependencies.join(", ")}`);
+	}
+	return lines.join("\n");
+}
 async function view(args, config) {
 	const spec = args[0];
 	if (!spec) {
-		console.error("Usage: cascade view <component-spec>");
+		console.error("Usage: cascivo view <component-spec>");
 		return;
 	}
 	const { url, headers, params } = await resolveItemUrl(parseAddress(spec), config);
@@ -1231,53 +1895,164 @@ async function view(args, config) {
 	if (headers) fetchOpts.headers = headers;
 	if (params) fetchOpts.params = params;
 	const item = await fetchJson(url, fetchOpts);
-	console.log(`\n${item.name}  v${item.version}`);
-	console.log(`Type: ${item.type}${item.category ? ` / ${item.category}` : ""}`);
-	console.log(`${item.description}`);
-	if (item.author) console.log(`Author: ${item.author}`);
-	if (item.license) console.log(`License: ${item.license}`);
-	if (item.homepage) console.log(`Homepage: ${item.homepage}`);
-	if (item.changelog?.length) {
-		console.log("\nChangelog:");
-		for (const c of item.changelog.slice(0, 5)) console.log(`  ${c.version}: ${c.note}`);
-	}
-	if (item.files?.length) {
-		console.log("\nFiles:");
-		for (const f of item.files) {
-			const target = f.target ? ` → ${f.target}` : "";
-			console.log(`  ${f.url}${target}`);
-		}
-	}
-	if (item.dependencies?.length) console.log(`\nDependencies: ${item.dependencies.join(", ")}`);
-	if (item.registryDependencies?.length) console.log(`Registry dependencies: ${item.registryDependencies.join(", ")}`);
+	console.log(formatItem(item));
 }
 //#endregion
 //#region src/index.ts
-const VERSION = "0.0.0";
+const VERSION = createRequire(import.meta.url)("../package.json").version;
 const HELP = `cascivo ${VERSION} — the CSS-native, signal-driven, AI-first design system
 
 Usage: cascivo <command> [options]
 
 Commands:
+  create [name]            Scaffold a new ready-to-run app (shell + nav + theme)
+                           (--template <spec>: start from a marketplace template)
   init                     Set up cascivo in the current project
-  add <component...>       Add one or more components to your project
+  add <component...>       Add components or a template to your project
   list [--installed]       List available components
   update [component]       Update installed components (--check: list outdated)
   search <query>           Search components across registries
   view <spec>              View a component before installing
-  theme add <name>         Install a theme (light | dark | warm)
+  theme <add|create>       Install a first-party theme, or build a custom one from /create
   eject <component>        Eject specific tokens into a scoped local override file
   generate <config.json>   Generate TSX from a ViewConfig JSON file
   doctor [--ci]            Check components for rule violations
   audit --ai <paths...>    Audit AI-generated code against the cascivo contract
   registry build           Build a static registry from a cascivo-registry.json file
+  template init <name>     Scaffold a new template (source + manifest + registry entry)
+  tokens import <file>     Import external design tokens as cascivo overrides
 
 Run "cascivo <command> --help" for details.`;
+const THEME_LIST = THEMES.join(" | ");
+const COMMAND_HELP = {
+	create: `Usage: cascivo create [name] [options]
+
+Scaffold a new ready-to-run app — Vite + React + TypeScript, pre-wired with the
+cascivo app shell, side navigation, header, and a theme.
+
+Options:
+  --template <spec>     Start from a marketplace template (@ns/name or owner/repo/name)
+  --theme <name>        Theme to install (${THEME_LIST})
+  --sections "<a, b>"   Comma-separated nav section labels (one component each)
+  --yes, -y             Accept defaults, never prompt`,
+	init: `Usage: cascivo init [options]
+
+Set up cascivo in the current project: installs @cascivo/core + @cascivo/tokens
+and writes cascivo.config.ts.
+
+Options:
+  --theme <name>  Theme to configure (${THEME_LIST})
+  --yes, -y       Accept defaults, never prompt (implied when stdin is not a TTY)`,
+	add: `Usage: cascivo add <component...> [options]
+
+Copy component source (TSX + CSS module) from the registry into your project,
+resolving component dependencies. Also installs templates (@ns/name) and
+third-party components (owner/repo/name).
+
+Options:
+  --dry-run  Show what would be written without writing
+  --yes, -y  Skip confirmation prompts`,
+	list: `Usage: cascivo list [options]
+
+List components available in the configured registry.
+
+Options:
+  --installed  Only list components already installed in this project`,
+	update: `Usage: cascivo update [component] [options]
+
+Update installed components to the current registry version. Without a
+component argument, updates everything in the lockfile.
+
+Options:
+  --check    List outdated components without writing
+  --yes, -y  Skip confirmation prompts`,
+	search: `Usage: cascivo search <query> [options]
+
+Search components across the configured registries.
+
+Options:
+  --registry <@ns>  Restrict the search to one registry namespace`,
+	view: `Usage: cascivo view <spec>
+
+Preview a component or template (files, dependencies, description) before
+installing. <spec> is a bare name, @ns/name, or owner/repo/name.`,
+	theme: `Usage: cascivo theme add <name>
+       cascivo theme create <name> --from <hash> [--out <path>]
+
+add     Install @cascivo/themes and print the import + data-theme wiring.
+create  Turn a theme-builder config into an owned <name>.theme.css. Get <hash>
+        from https://cascivo.com/create ("Copy CLI command"). --dry-run prints
+        the CSS without writing.
+
+Themes: ${THEME_LIST}`,
+	eject: `Usage: cascivo eject <component> [options]
+
+Eject specific tokens into a scoped local override file so you can restyle a
+component without forking it.
+
+Options:
+  --tokens <a,b>  Comma-separated token names to eject (default: all)
+  --scope <sel>   CSS selector the overrides are scoped to
+  --out <file>    Output file path
+  --dry-run       Print the override file without writing`,
+	generate: `Usage: cascivo generate <config.json> [options]
+
+Generate TSX from a ViewConfig JSON file (see the MCP scaffold_view tool).
+
+Options:
+  --out <file>            Output file (default: stdout)
+  --components-dir <dir>  Components import base (default: ./src/components/ui)`,
+	doctor: `Usage: cascivo doctor [options]
+
+Check components in this repo for cascivo rule violations (banned React hooks,
+hardcoded strings, missing @cascivo/react exports).
+
+Options:
+  --ci     Exit non-zero when violations are found
+  --drift  Compare installed components against the registry (copy-paste drift)`,
+	audit: `Usage: cascivo audit --ai <paths...> [options]
+
+Audit AI-generated code against the cascivo contract: hard-coded values that
+should be tokens, invented props, missing required props, raw strings where
+i18n is expected.
+
+Options:
+  --fix           Rewrite unambiguous CSS literals to their token equivalents
+  --json          Machine-readable output
+  --level <name>  Minimum finding level to report (error | warn; default error)`,
+	registry: `Usage: cascivo registry build [dir]
+
+Build a static registry (registry.json + file payloads) from a
+cascivo-registry.json manifest, ready to host on any static file server.`,
+	template: `Usage: cascivo template init <name> [options]
+
+Scaffold a new template: source, manifest, and registry entry.
+
+Options:
+  --category <name>    Template category (e.g. dashboard)
+  --framework <name>   Target framework (default react-vite)
+  --components <a,b>   Registry components the template composes
+  --repo <owner/repo>  Repository the template will be hosted in`,
+	tokens: `Usage: cascivo tokens import <file>
+
+Import external design tokens (W3C design-tokens JSON) as cascivo token
+overrides.`
+};
 async function run(args) {
 	const [command, ...rest] = args;
+	if (command !== void 0 && (rest.includes("--help") || rest.includes("-h"))) {
+		const commandHelp = COMMAND_HELP[command];
+		if (commandHelp !== void 0) {
+			console.log(commandHelp);
+			return;
+		}
+	}
 	switch (command) {
+		case "create":
+			await create(rest);
+			break;
 		case "init":
-			await init();
+			await init(rest);
 			break;
 		case "add":
 			await add(rest, await loadConfig(), {
@@ -1304,7 +2079,7 @@ async function run(args) {
 			await theme(rest);
 			break;
 		case "eject": {
-			const { eject } = await import("./eject-D_mC1lsq.mjs");
+			const { eject } = await import("./eject-Br8V7I3m.mjs");
 			const flag = (key) => {
 				const eq = rest.find((r) => r.startsWith(`--${key}=`));
 				if (eq) return eq.slice(key.length + 3);
@@ -1331,11 +2106,20 @@ async function run(args) {
 				process.exitCode = 1;
 			}
 			break;
+		case "template":
+			if (rest[0] === "init") {
+				const { templateInit } = await import("./template-init-C46fRXo-.mjs");
+				await templateInit(rest.slice(1));
+			} else {
+				console.error(`Unknown template subcommand: ${rest[0]}`);
+				process.exitCode = 1;
+			}
+			break;
 		case "doctor": {
 			const ci = rest.includes("--ci");
 			if (rest.includes("--drift")) {
-				const { runDoctorDrift } = await import("./drift-D7JFzpP_.mjs");
-				await runDoctorDrift(rest);
+				const { runDoctorDrift } = await import("./drift-Ciw5qeEt.mjs");
+				await runDoctorDrift(await loadConfig());
 			} else {
 				const result = await runDoctor(process.cwd());
 				if (result.passed) console.log("No violations found.");
@@ -1347,7 +2131,7 @@ async function run(args) {
 			break;
 		}
 		case "audit": {
-			const { audit } = await import("./audit-AHr4MDMK.mjs");
+			const { audit } = await import("./audit-InQqdY1s.mjs");
 			await audit(rest, await loadConfig());
 			break;
 		}