cascivo 0.6.2 → 0.7.2

package/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as detectPackageManager, c as isPackageManager, l as loadConfig, n as DEFAULT_CONFIG$1, o as installCommand, r as THEMES, s as installHint, t as CASCIVO_HOST, u as __exportAll } from "./config-C6GdrbvF.mjs";
+import { a as detectPackageManager, c as isPackageManager, l as loadConfig, n as DEFAULT_CONFIG$1, o as installCommand, r as THEMES, s as installHint, t as CASCIVO_HOST, u as __exportAll } from "./config-D7ddWN_9.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 writeLock, c as findComponent, i as updateLockEntry, n as readLock, o as fetchRegistry, r as sha256, s as fileName, t as createLock } from "./lock-CW8UuEPJ.mjs";
@@ -24,7 +24,11 @@ import { createInterface } from "node:readline/promises";
 function installPackages(packages, cwd = process.cwd(), opts = {}) {
 	if (packages.length === 0) return true;
 	const pm = opts.pm ?? detectPackageManager(cwd);
-	const [cmd, args] = installCommand(pm, packages, { dev: opts.dev ?? false });
+	const [cmd, args] = installCommand(pm, packages, {
+		dev: opts.dev ?? false,
+		...opts.floors ? { floors: opts.floors } : {},
+		...opts.pin ? { pin: opts.pin } : {}
+	});
 	console.log(`Installing ${packages.join(", ")} with ${cmd}…`);
 	if (spawnSync(cmd, args, {
 		cwd,
@@ -351,6 +355,17 @@ async function add(names, config, opts = {}) {
 	}
 	const { resolved, missing } = resolveBareClosure(registry, bareSpecs);
 	for (const name of missing) console.error(`Component "${name}" not found in registry. Run "cascivo list".`);
+	const announced = /* @__PURE__ */ new Set();
+	for (const { entry, requested } of resolved) {
+		if (!requested || !entry.install || announced.has(entry.install)) continue;
+		announced.add(entry.install);
+		console.log(`\n"${entry.name}" ships in the ${entry.install} npm package — no source is copied into your project. Updates come from your package manager, not \`cascivo update\`.`);
+	}
+	for (const { entry, requested } of resolved) {
+		if (!requested || !entry.deprecated) continue;
+		const { replacement, since, note } = entry.deprecated;
+		console.warn(`\n⚠ "${entry.name}" is deprecated since ${since}. Use "${replacement}" instead:\n    cascivo add ${replacement}\n` + (note ? `  ${note}\n` : "") + `  Adding "${entry.name}" anyway — it still works.\n`);
+	}
 	const peerFloors = {};
 	for (const { entry } of resolved) for (const [pkg, floor] of Object.entries(entry.peerVersions ?? {})) peerFloors[pkg] = floor;
 	const npmPackages = /* @__PURE__ */ new Set();
@@ -490,9 +505,35 @@ function resolvePackageManagerFlag(args) {
 	return { error: `Unknown package manager "${raw}". Use one of: pnpm, yarn, npm, bun.` };
 }
 //#endregion
+//#region src/generated/versions.ts
+/**
+* Exact published versions, baked in at build time.
+*
+* Scaffolded apps pin these rather than `"latest"`: the cascivo packages version
+* independently on 0.x, so a floating specifier can resolve a mutually incompatible set,
+* and GETTING-STARTED.md tells adopters to pin exactly. Regenerate with `pnpm regen`.
+*/
+const CASCIVO_VERSIONS = {
+	"@cascivo/react": "0.16.1",
+	"@cascivo/themes": "0.4.11",
+	"@cascivo/charts": "0.16.1",
+	"@cascivo/icons": "0.3.8",
+	"@cascivo/eslint-config": "0.2.2"
+};
+/** `@cascivo/core`'s declared `@preact/signals-react` peer range. */
+const SIGNALS_PEER = ">=3.0.0";
+//#endregion
 //#region src/commands/create.ts
-/** Version specifier used for every `@cascivo/*` dependency in generated apps. */
-const CASCIVO_DEP = "latest";
+/**
+* Exact published versions, baked in at build time by `scripts/registry/cli-versions.ts`.
+*
+* This used to be the literal `'latest'` for every cascivo dependency — the loosest
+* possible specifier on a set of independently-versioned 0.x packages, and the direct
+* opposite of GETTING-STARTED.md's "pin **exact** versions (no `^`)". A scaffold that
+* contradicts the docs on the very first file an adopter opens undermines every other rule
+* those docs state, so the pins are generated rather than hand-written.
+*/
+const V = CASCIVO_VERSIONS;
 /** Install-everything command for a package manager (`pnpm install`, `yarn`, …). */
 function installAllCommand(pm) {
 	return pm === "yarn" ? "yarn" : `${pm} install`;
@@ -510,6 +551,24 @@ 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;
 }
+/**
+* Short, human-readable brand for the shell header.
+*
+* The directory name is the wrong thing to render verbatim: a dated demo directory
+* (`vercel-dashboard-2026-07-30-take2`) produced a 45-character brand in the top-left of
+* every page. Take the leading words, title-case them, and stop — a brand is a label, not a
+* slug. Bare numbers and `v2`-style segments are dropped rather than counted.
+*/
+function brandName(name) {
+	const words = name.trim().split(/[^a-zA-Z0-9]+/).filter((w) => w !== "" && !/^\d+$/.test(w) && !/^v\d+$/i.test(w));
+	const kept = [];
+	for (const word of words) {
+		if (kept.length >= 3) break;
+		if (kept.length > 0 && kept.join(" ").length + 1 + word.length > 24) break;
+		kept.push(word.charAt(0).toUpperCase() + word.slice(1));
+	}
+	return kept.join(" ") || "App";
+}
 /** 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";
@@ -553,20 +612,25 @@ function packageJson(opts) {
 		scripts: {
 			dev: "vite",
 			build: "tsc && vite build",
-			preview: "vite preview"
+			preview: "vite preview",
+			typecheck: "tsc --noEmit",
+			lint: "eslint ."
 		},
 		dependencies: {
-			"@cascivo/core": CASCIVO_DEP,
-			"@cascivo/react": CASCIVO_DEP,
-			"@cascivo/themes": CASCIVO_DEP,
-			"@cascivo/tokens": CASCIVO_DEP,
+			"@cascivo/react": V["@cascivo/react"],
+			"@cascivo/themes": V["@cascivo/themes"],
+			"@preact/signals-react": SIGNALS_PEER,
 			react: "^19.0.0",
 			"react-dom": "^19.0.0"
 		},
 		devDependencies: {
+			"@cascivo/eslint-config": V["@cascivo/eslint-config"],
+			"@eslint/js": "^9.0.0",
 			"@types/react": "^19.0.0",
 			"@types/react-dom": "^19.0.0",
 			"@vitejs/plugin-react": "^5.0.0",
+			eslint: "^9.0.0",
+			"eslint-plugin-react-hooks": "^7.0.0",
 			typescript: "^5.7.0",
 			vite: "^7.0.0"
 		}
@@ -617,7 +681,13 @@ function indexHtml(opts) {
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>${opts.name}</title>
     <style>
-      @layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component, cascivo.theme, cascivo.blocks, cascivo.override;
+      @layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component,
+        cascivo.platform, cascivo.theme, cascivo.blocks, cascivo.example, cascivo.override;
+      /* cascivo.example is this app's own slot — above the component/blocks layers so your
+         styles win, below cascivo.override which stays free for one-off hotfixes. The
+         generated AGENTS.md tells the agent to write there, and this statement is what makes
+         that legal: a layer used but never declared falls to the end of the cascade and
+         beats everything, which is the opposite of what the ordering is for. */
       /* Third-party CSS goes in the low-priority vendor layer so it can't beat cascivo:
          @import url('some-lib/styles.css') layer(vendor); — see docs/THIRD-PARTY-CSS.md */
       @layer cascivo.reset {
@@ -674,11 +744,16 @@ function appTsx(opts, sections) {
     },`).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'
+import {
+  AppShell,
+  ShellHeader,
+  SideNav,
+  signal,
+  useSignals,
+  type SideNavItem,
+} from '@cascivo/react'
 ${sectionImports}
 
-import '@cascivo/tokens'
 import '@cascivo/themes/${opts.theme}.css'
 import '@cascivo/react/styles.css'
 
@@ -695,7 +770,7 @@ ${navItems}
 
   return (
     <AppShell
-      header={<ShellHeader brand={{ name: '${opts.name.replace(/'/g, "\\'")}' }} />}
+      header={<ShellHeader brand={{ name: '${brandName(opts.name).replace(/'/g, "\\'")}' }} />}
       nav={<SideNav items={navItems} />}
     >
 ${renderedSections}
@@ -740,16 +815,31 @@ export function ${section.component}() {
 }
 `;
 }
-function cascivoConfig(opts) {
-	return `import type { CascadeConfig } from 'cascivo'
-
-const config: CascadeConfig = {
-  registry: '${CASCIVO_HOST}/registry.json',
-  outputDir: 'src/components/ui',
-  theme: '${opts.theme}',
-}
+/**
+* ESLint flat config for the scaffold.
+*
+* `@cascivo/eslint-config` is wired in from the start because
+* `eslint-plugin-react-hooks@7`'s `recommended-latest` reports every `signal.value = next`
+* — the idiom AI-RULES.md mandates and the generated `App.tsx` below uses — as
+* `Error: This value cannot be modified`. Without this, `pnpm lint` on a freshly scaffolded
+* app errors on every piece of state it ships with.
+*/
+function eslintConfig() {
+	return `import js from '@eslint/js'
+import reactHooks from 'eslint-plugin-react-hooks'
+import cascivo from '@cascivo/eslint-config'
 
-export default config
+export default [
+  js.configs.recommended,
+  // NOTE the \`.flat\` — the plugin exports both \`configs['recommended-latest']\` (the legacy
+  // eslintrc shape, which applies NOTHING here and reports no error) and this one.
+  reactHooks.configs.flat['recommended-latest'],
+  // Spread LAST — flat config is last-wins. This turns off \`react-hooks/immutability\`,
+  // which reports cascivo's signal writes (\`signal.value = next\`) as errors.
+  // See https://cascivo.com/docs/using-with-strict-eslint.md
+  ...cascivo,
+  { ignores: ['dist/**'] },
+]
 `;
 }
 function gitignore() {
@@ -807,7 +897,7 @@ This app's declared layer order (in \`index.html\`):
 
 \`\`\`css
 @layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component,
-  cascivo.theme, cascivo.blocks, cascivo.override;
+  cascivo.platform, cascivo.theme, cascivo.blocks, cascivo.example, cascivo.override;
 \`\`\`
 
 ### Worked example — nesting, not new layers
@@ -850,8 +940,8 @@ function buildScaffold(opts) {
 			contents: indexHtml(opts)
 		},
 		{
-			path: "cascivo.config.ts",
-			contents: cascivoConfig(opts)
+			path: "eslint.config.js",
+			contents: eslintConfig()
 		},
 		{
 			path: ".gitignore",
@@ -938,7 +1028,7 @@ async function create(args, cwd = process.cwd()) {
 		const templateSpec = flagValue(args, "template");
 		if (templateSpec) {
 			const { add } = await Promise.resolve().then(() => add_exports);
-			const { loadConfig } = await import("./config-C6GdrbvF.mjs").then((n) => n.i);
+			const { loadConfig } = await import("./config-D7ddWN_9.mjs").then((n) => n.i);
 			console.log(`\nInstalling template "${templateSpec}"…`);
 			await add([templateSpec], await loadConfig(), {
 				cwd: targetDir,
@@ -956,20 +1046,36 @@ async function create(args, cwd = process.cwd()) {
 //#endregion
 //#region src/commands/doctor.ts
 var doctor_exports = /* @__PURE__ */ __exportAll({
+	checkDuplicateCore: () => checkDuplicateCore,
+	checkFormatterIgnore: () => checkFormatterIgnore,
 	checkProjectDependencies: () => checkProjectDependencies,
 	checkSignalsCompat: () => checkSignalsCompat,
 	checkSsrConfig: () => checkSsrConfig,
-	isAdopterProject: () => isAdopterProject,
+	detectInstallPath: () => detectInstallPath,
 	runDoctor: () => runDoctor,
 	stripCommentsAndStrings: () => stripCommentsAndStrings
 });
-/** Runtime packages copied cascivo source needs; the last is @cascivo/core's peer. */
+/** Runtime packages **copied** cascivo source needs; the last is @cascivo/core's peer. */
 const REQUIRED_RUNTIME_DEPS = [
 	"@cascivo/core",
 	"@cascivo/tokens",
 	"@cascivo/themes",
 	"@preact/signals-react"
 ];
+/** Runtime packages a **prebuilt** (Path B) app needs. */
+const REQUIRED_PREBUILT_DEPS = [
+	"@cascivo/react",
+	"@cascivo/themes",
+	"@preact/signals-react"
+];
+/**
+* Packages a prebuilt app must NOT declare directly, with the rule each one breaks. They
+* are transitive there, and everything they export is re-exported from `@cascivo/react`.
+*/
+const FORBIDDEN_PREBUILT_DEPS = {
+	"@cascivo/core": "AI-RULES.md: never add @cascivo/core to a prebuilt-path app — it is transitive, and everything is re-exported from @cascivo/react",
+	"@cascivo/tokens": "GETTING-STARTED.md: @cascivo/tokens comes with @cascivo/themes as a direct dependency — never install it by hand"
+};
 /** Installed on demand by `cascivo add` when a component/chart declares them. */
 const ON_DEMAND_DEPS = ["@cascivo/i18n", "@cascivo/charts"];
 const CONFIG_FILES = [
@@ -977,17 +1083,74 @@ const CONFIG_FILES = [
 	"cascivo.config.js",
 	"cascivo.config.mjs"
 ];
-/** Whether cwd looks like a cascivo adopter project (has a generated config). */
-function isAdopterProject(cwd) {
-	return CONFIG_FILES.some((f) => existsSync(join(cwd, f)));
+/**
+* Infer the install path from evidence.
+*
+* This used to be `isAdopterProject()` — "does a `cascivo.config.*` exist?" — and
+* `cascivo create` wrote that config into every scaffold, including prebuilt-path ones. So
+* every scaffolded app was judged copy-paste and told to install `@cascivo/core` and
+* `@cascivo/tokens`, which the docs explicitly forbid on that path. `doctor --ci` exited 1
+* on a correctly-installed app, which made the CI gate the docs recommend
+* (`cascivo doctor --ci && cascivo audit --ai src`) red on day one.
+*
+* A config file now only contributes evidence when it points at a directory that actually
+* contains copied source, which is what it was ever meant to signal.
+*/
+function detectInstallPath(cwd) {
+	let deps = {};
+	let hasPackageJson = true;
+	try {
+		const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+		deps = {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+	} catch {
+		hasPackageJson = false;
+	}
+	if (!hasPackageJson) return "unknown";
+	const usesPackage = deps["@cascivo/react"] !== void 0;
+	const copied = hasCopiedSource(cwd);
+	if (usesPackage && copied) return "hybrid";
+	if (usesPackage) return "prebuilt";
+	if (copied) return "copied";
+	return "unknown";
+}
+/** Whether the configured output directory holds vendored component source. */
+function hasCopiedSource(cwd) {
+	for (const dir of outputDirCandidates(cwd)) {
+		const full = join(cwd, dir);
+		if (!existsSync(full)) continue;
+		try {
+			if (readdirSync(full).some((f) => f.endsWith(".tsx"))) return true;
+		} catch {}
+	}
+	return false;
+}
+/** `outputDir` from the config if it declares one, plus the documented default. */
+function outputDirCandidates(cwd) {
+	const dirs = new Set(["src/components/ui"]);
+	for (const file of CONFIG_FILES) {
+		const full = join(cwd, file);
+		if (!existsSync(full)) continue;
+		try {
+			const declared = /outputDir\s*:\s*['"]([^'"]+)['"]/.exec(readFileSync(full, "utf8"))?.[1];
+			if (declared !== void 0) dirs.add(declared);
+		} catch {}
+	}
+	return [...dirs];
 }
 /**
-* Advisory check that the runtime dependencies copied source needs are declared
-* in the project's package.json. Turns the opaque "cannot find module
-* '@preact/signals-react'" build failure — the report's #4, where the peer was
-* invisible — into a diagnosed condition with a fix. Adopter-only (gated on a
-* cascivo.config by the caller); `@cascivo/i18n`/`@cascivo/charts` are advisory
-* since not every project uses them.
+* Check that the runtime dependencies this project's install path needs are declared in its
+* package.json — and, on the prebuilt path, that it declares none it must not.
+*
+* Turns the opaque "cannot find module '@preact/signals-react'" build failure into a
+* diagnosed condition with a fix. What it demands depends on `detectInstallPath`: requiring
+* `@cascivo/core` of a prebuilt app is not merely unhelpful, it is the opposite of what the
+* docs say, and following the advice makes a correct project wrong.
+*
+* `@cascivo/i18n`/`@cascivo/charts` stay advisory since not every project uses them, and an
+* `unknown` path emits nothing at all rather than guessing.
 */
 function checkProjectDependencies(cwd) {
 	let deps = {};
@@ -1000,13 +1163,24 @@ function checkProjectDependencies(cwd) {
 	} catch {
 		return [];
 	}
+	const path = detectInstallPath(cwd);
+	if (path === "unknown") return [];
 	const pm = detectPackageManager(cwd);
 	const findings = [];
-	for (const pkg of REQUIRED_RUNTIME_DEPS) if (deps[pkg] === void 0) findings.push({
+	const required = path === "prebuilt" ? REQUIRED_PREBUILT_DEPS : REQUIRED_RUNTIME_DEPS;
+	for (const pkg of required) if (deps[pkg] === void 0) findings.push({
 		package: pkg,
 		required: true,
-		hint: installHint(pm, [pkg])
+		hint: `detected ${path} install path — ${installHint(pm, [pkg])}`
 	});
+	if (path === "prebuilt") {
+		for (const [pkg, reason] of Object.entries(FORBIDDEN_PREBUILT_DEPS)) if (deps[pkg] !== void 0) findings.push({
+			package: pkg,
+			required: true,
+			kind: "forbidden",
+			hint: reason
+		});
+	}
 	for (const pkg of ON_DEMAND_DEPS) if (deps[pkg] === void 0) findings.push({
 		package: pkg,
 		required: false,
@@ -1014,6 +1188,29 @@ function checkProjectDependencies(cwd) {
 	});
 	return findings;
 }
+/** Packages that carry their own `@cascivo/core` dependency. */
+const CORE_DEPENDENTS = [
+	"@cascivo/react",
+	"@cascivo/charts",
+	"@cascivo/flow",
+	"@cascivo/editor"
+];
+async function checkDuplicateCore(cwd) {
+	const root = await readInstalledPackageVersion(cwd, "@cascivo/core");
+	const nested = [];
+	for (const owner of CORE_DEPENDENTS) {
+		const ownerRoot = join(cwd, "node_modules", owner);
+		if (!existsSync(ownerRoot)) continue;
+		const version = await readInstalledPackageVersion(ownerRoot, "@cascivo/core");
+		if (version !== null && version !== root) nested.push(`${owner} → ${version}`);
+	}
+	if (nested.length === 0) return null;
+	return {
+		root,
+		nested,
+		hint: "Align the @cascivo/* versions (they are released together — see breaking-changes.json) and reinstall. Two copies of @cascivo/core means two signal registries: writes through one are invisible to components subscribed through the other, with no error."
+	};
+}
 /**
 * Checks the installed `@preact/signals-react` against the installed React.
 * React 19 removed the `__SECRET_INTERNALS…` export that signals-react 2.x
@@ -1071,6 +1268,38 @@ const VITE_CONFIG_FILES = [
 * cliff the 2026-07-20 report hit (blocker #1). A text match, not a gate. Returns
 * null when there's no Vite SSR framework or the config already handles it.
 */
+/**
+* Warn when the vendored components dir is not excluded from the project's formatter.
+*
+* Owning the code means your formatter rewrites it, and `cascivo update` then reports drift
+* on files you never edited. `cascivo init` writes the exclusion for you, but a project that
+* adopted cascivo before that existed — or that added Prettier afterwards — never got it.
+*/
+function checkFormatterIgnore(cwd, outputDir) {
+	const pairs = [{
+		configs: [
+			".prettierrc",
+			".prettierrc.json",
+			".prettierrc.js",
+			"prettier.config.js"
+		],
+		ignore: ".prettierignore"
+	}, {
+		configs: [".oxfmtrc", ".oxfmtrc.json"],
+		ignore: ".oxfmtignore"
+	}];
+	const dir = outputDir.replace(/\/+$/, "");
+	for (const { configs, ignore } of pairs) {
+		if (!configs.some((f) => existsSync(join(cwd, f)))) continue;
+		let content = "";
+		try {
+			content = readFileSync(join(cwd, ignore), "utf8");
+		} catch {}
+		if (content.split("\n").some((l) => l.trim().replace(/\/+$/, "") === dir)) continue;
+		return `"${dir}/" is not excluded from your formatter. Running it will rewrite code you own, and \`cascivo update\` will then report drift on files you never edited. Add "${dir}/" to ${ignore}.`;
+	}
+	return null;
+}
 function checkSsrConfig(cwd) {
 	let deps = {};
 	try {
@@ -1299,9 +1528,7 @@ async function generate(args, config) {
 	}
 	const { readFileSync } = await import("node:fs");
 	const configJson = readFileSync(inputArg, "utf-8");
-	const viewConfig = JSON.parse(configJson);
-	await fetchRegistry(config.registry);
-	const tsx = generateTsx(viewConfig, /* @__PURE__ */ new Map(), componentsDirArg ?? config.outputDir ?? "./src/components/ui");
+	const tsx = generateTsx(JSON.parse(configJson), /* @__PURE__ */ new Map(), componentsDirArg ?? config.outputDir ?? "./src/components/ui");
 	const outPath = outArg ?? join(dirname(inputArg), `${basename(inputArg, ".json")}.tsx`);
 	writeFileSync(outPath, tsx, "utf-8");
 	console.log(`Generated ${outPath}`);
@@ -1391,6 +1618,85 @@ function hintEslintIfPresent(cwd) {
 	console.log("\nESLint: copied cascivo source may trip a strict host config on stylistic rules.");
 	console.log("  Scope them off your components dir — see docs/USING-WITH-STRICT-ESLINT.md");
 }
+/**
+* Write dependency entries into `package.json` so a failed install still leaves a
+* DECLARATIVE-complete project, one `install` away from working.
+*
+* The reported failure: one unrelated bad version range elsewhere in the adopter's
+* `package.json` made `pnpm add` exit non-zero. cascivo had already written
+* `cascivo.config.ts`, so the project claimed to be cascivo-configured with none of the
+* runtime present, and the printed advice ("install them yourself") was the same command
+* that had just failed. Recording the dependencies is the difference between "recoverable
+* with one command" and "figure out what was supposed to be here".
+*
+* Never overwrites an entry that already exists — the app's own pin wins.
+*/
+function recordDependencies(cwd, packages, opts) {
+	const pkgPath = join(cwd, "package.json");
+	if (!existsSync(pkgPath)) return [];
+	let pkg;
+	try {
+		pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+	} catch {
+		return [];
+	}
+	const field = opts.dev ? "devDependencies" : "dependencies";
+	const deps = pkg[field] ??= {};
+	const added = [];
+	for (const name of packages) {
+		if (deps[name] !== void 0) continue;
+		deps[name] = "latest";
+		added.push(name);
+	}
+	if (added.length === 0) return [];
+	writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+	return added;
+}
+/** Formatter ignore files, in the order a project is likely to use them. */
+const FORMATTER_IGNORES = [{
+	config: [
+		".prettierrc",
+		".prettierrc.json",
+		".prettierrc.js",
+		"prettier.config.js"
+	],
+	ignore: ".prettierignore"
+}, {
+	config: [".oxfmtrc", ".oxfmtrc.json"],
+	ignore: ".oxfmtignore"
+}];
+/**
+* Exclude the vendored components dir from the project's formatter.
+*
+* Owning the code means your formatter reformats it, and then `cascivo update` reports drift
+* on files you never touched. This ACTS rather than hints: the ESLint equivalent below only
+* prints a pointer, and an adopter ran `prettier --write .` before ever reading it.
+*
+* Idempotent, and never rewrites an existing line.
+*/
+function ensureFormatterIgnore(cwd, outputDir) {
+	const line = `${outputDir.replace(/\/+$/, "")}/`;
+	for (const { config, ignore } of FORMATTER_IGNORES) {
+		if (!(config.some((f) => existsSync(join(cwd, f))) || hasPrettierKeyInPackageJson(cwd, ignore))) continue;
+		const path = join(cwd, ignore);
+		const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+		if (current.split("\n").some((l) => l.trim() === line)) continue;
+		const banner = "# cascivo: vendored component source — you own it, so do not reformat it\n";
+		writeFileSync(path, current === "" ? banner + line + "\n" : `${current.replace(/\n*$/, "\n")}\n${banner}${line}\n`, "utf8");
+		console.log(`\nAdded "${line}" to ${ignore} (so your formatter does not rewrite copied source).`);
+	}
+}
+/** `prettier` key in package.json counts as a Prettier config — only relevant to .prettierignore. */
+function hasPrettierKeyInPackageJson(cwd, ignore) {
+	if (ignore !== ".prettierignore") return false;
+	const pkgPath = join(cwd, "package.json");
+	if (!existsSync(pkgPath)) return false;
+	try {
+		return "prettier" in JSON.parse(readFileSync(pkgPath, "utf8"));
+	} catch {
+		return false;
+	}
+}
 /** The "here's everything you need" summary, printed once at the end of init. */
 function printDependencySummary() {
 	console.log("\nDependencies");
@@ -1428,13 +1734,36 @@ async function init(args = [], cwd = process.cwd()) {
 			pm,
 			dev: true
 		});
-		if (!runtimeOk || !devOk) process.exitCode = 1;
+		if (!runtimeOk || !devOk) {
+			const recorded = [...runtimeOk ? [] : recordDependencies(cwd, RUNTIME_DEPS, { dev: false }), ...devOk ? [] : recordDependencies(cwd, DEV_DEPS, { dev: true })];
+			console.error("\nInstall failed — cascivo.config.ts was written but the packages are not installed.");
+			if (recorded.length > 0) {
+				console.error(`Wrote ${recorded.length} dependency entries to package.json: ${recorded.join(", ")}`);
+				console.error(`Recover with:\n  ${pm} install`);
+			} else console.error(`Recover with:\n  ${installHint(pm, RUNTIME_DEPS)}\n  ${installHint(pm, DEV_DEPS, { dev: true })}`);
+			process.exitCode = 1;
+		}
 	}
-	console.log("\nImport the theme in your root CSS or entry file:");
-	console.log(`  import '@cascivo/themes/${theme}.css'`);
-	console.log("Then set the theme on your root element:");
+	console.log("\nStylesheets — import these once, in this order, in your entry file:");
+	console.log(`  import '@cascivo/tokens'                 // primitive tokens — every --cascivo-* value`);
+	console.log(`  import '@cascivo/themes/${theme}.css'${" ".repeat(Math.max(1, 16 - theme.length))}// the ${theme} theme's semantic values`);
+	console.log(`  // …then your component CSS (\`cascivo add\` writes .module.css beside each component)`);
+	console.log("\nThen set the theme on your root element:");
 	console.log(`  <html data-theme="${theme}">`);
+	console.log("\nSwitching themes at runtime? Use a bundle instead of the single theme:");
+	console.log("  import '@cascivo/themes/light-dark.css'  // light + dark — the common case");
+	console.log("  import '@cascivo/themes/all.css'         // all twelve themes");
+	console.log("  import { ThemeProvider } from '@cascivo/core'");
+	console.log("\nIn YOUR components, when you read a signal during render:");
+	console.log("  import { useSignals } from '@cascivo/core'");
+	console.log("  function MyComponent() {");
+	console.log("    useSignals()   // ← first statement, or the component never re-renders");
+	console.log("    return <span>{count.value}</span>");
+	console.log("  }");
+	console.log("\nAdding a chart later? Charts ship as an npm package with their own stylesheet:");
+	console.log("  import '@cascivo/charts/styles.css'      // `cascivo add <chart>` reminds you");
 	printDependencySummary();
+	ensureFormatterIgnore(cwd, DEFAULT_CONFIG$1.outputDir);
 	hintEslintIfPresent(cwd);
 	console.log("\nAdd components with: cascivo add <name>");
 }
@@ -1449,12 +1778,22 @@ const TYPE_LABELS = {
 	flow: "Flow (npm: @cascivo/flow)",
 	editor: "Editor (npm: @cascivo/editor)"
 };
+/**
+* Deprecation marker for the listing.
+*
+* Shown at DISCOVERY time on purpose. `overflow-menu` carried a `@deprecated` JSDoc in its
+* source for months, which an adopter only meets after they have already vendored the file —
+* and it pointed at an import path that cannot resolve on either install path.
+*/
+function deprecationSuffix(c) {
+	return c.deprecated ? `  ⚠ deprecated → ${c.deprecated.replacement}` : "";
+}
 /** Render a group of entries as an aligned text table (no section header). */
 function formatGroup(entries) {
 	const rows = entries.map((c) => [
 		c.name,
 		c.category,
-		c.description
+		c.description + deprecationSuffix(c)
 	]);
 	const headers = [
 		"Name",
@@ -2518,32 +2857,42 @@ async function run(args) {
 		case "doctor": {
 			const ci = rest.includes("--ci");
 			if (rest.includes("--drift")) {
-				const { runDoctorDrift } = await import("./drift-qTzJ75Ds.mjs");
+				const { runDoctorDrift } = await import("./drift-B02BbFN_.mjs");
 				await runDoctorDrift(await loadConfig());
 			} else {
 				const cwd = process.cwd();
 				const result = await runDoctor(cwd);
-				const { checkProjectDependencies, checkSignalsCompat, checkSsrConfig, isAdopterProject } = await Promise.resolve().then(() => doctor_exports);
-				const adopter = isAdopterProject(cwd);
+				const { checkDuplicateCore, checkFormatterIgnore, checkProjectDependencies, checkSignalsCompat, checkSsrConfig, detectInstallPath } = await Promise.resolve().then(() => doctor_exports);
+				const adopter = detectInstallPath(cwd) !== "unknown";
 				const deps = adopter ? checkProjectDependencies(cwd) : [];
 				const missingRequired = deps.filter((d) => d.required);
 				const signalsCompat = adopter ? await checkSignalsCompat(cwd) : null;
 				const signalsError = signalsCompat?.severity === "error";
 				const ssrHint = adopter ? checkSsrConfig(cwd) : null;
-				if (result.passed && deps.length === 0 && signalsCompat === null && ssrHint === null) console.log("No violations found.");
+				const duplicateCore = adopter ? await checkDuplicateCore(cwd) : null;
+				const formatterHint = adopter ? checkFormatterIgnore(cwd, (await loadConfig()).outputDir) : null;
+				const { runDoctorDrift } = await import("./drift-B02BbFN_.mjs");
+				const driftOutcome = adopter ? await runDoctorDrift(await loadConfig(), cwd) : {
+					ran: false,
+					reason: "no cascivo install detected",
+					issues: 0
+				};
+				if (result.passed && deps.length === 0 && signalsCompat === null && ssrHint === null && duplicateCore === null && formatterHint === null && driftOutcome.issues === 0) console.log(driftOutcome.ran ? "No violations found." : `No violations found (drift: not checked — ${driftOutcome.reason}).`);
 				else {
 					for (const v of result.violations) console.error(`[${v.rule}] ${v.detail}\n  ${v.file}`);
-					for (const d of missingRequired) console.error(`[missing-dependency] ${d.package} is not in package.json — copied cascivo source needs it. Install: ${d.hint}`);
+					for (const d of missingRequired) console.error(d.kind === "forbidden" ? `[forbidden-dependency] ${d.package} must not be a direct dependency here. Remove it — ${d.hint}` : `[missing-dependency] ${d.package} is not in package.json. Install: ${d.hint}`);
 					if (signalsCompat) (signalsError ? console.error : console.log)(`[${signalsError ? "signals-incompatible" : "signals-outdated"}] ${signalsCompat.detail} Upgrade: ${signalsCompat.hint}`);
 					if (ssrHint) console.log(`[ssr-config] ${ssrHint}`);
+					if (formatterHint) console.log(`[formatter-drift] ${formatterHint}`);
+					if (duplicateCore) console.error(`[duplicate-core] More than one @cascivo/core is installed (root: ${duplicateCore.root ?? "none"}; ${duplicateCore.nested.join("; ")}). ` + duplicateCore.hint);
 					for (const d of deps.filter((x) => !x.required)) console.log(`[optional] ${d.package} is not installed; add it when a component or chart needs it: ${d.hint}`);
-					if (ci && (result.violations.length > 0 || missingRequired.length > 0 || signalsError)) process.exitCode = 1;
+					if (ci && (result.violations.length > 0 || missingRequired.length > 0 || signalsError || duplicateCore !== null || driftOutcome.issues > 0)) process.exitCode = 1;
 				}
 			}
 			break;
 		}
 		case "audit": {
-			const { audit } = await import("./audit-Cn6HJkuo.mjs");
+			const { audit } = await import("./audit-C4ul-2Ix.mjs");
 			await audit(rest, await loadConfig());
 			break;
 		}