@lemoncode/lemony 0.5.0 → 0.5.1

package/dist/cli.mjs

@@ -6,9 +6,9 @@ import { argv, cwd, env, exit, stderr, stdin, stdout } from "node:process";
 import { createInterface } from "node:readline/promises";
 import { promisify } from "node:util";
 import { parse, parseDocument } from "yaml";
+import { constants } from "node:fs";
 import { z } from "zod";
 import { createHash, randomBytes } from "node:crypto";
-import { constants } from "node:fs";
 //#region src/events/append.ts
 const appendEvent = async (eventsPath, event) => {
 	await mkdir(dirname(eventsPath), { recursive: true });
@@ -47,6 +47,136 @@ const PATHS_DEFAULTS = {
 	playbooks_global: "~/.claude/playbooks"
 };
 //#endregion
+//#region src/fs/exists.ts
+const pathExists = async (path) => {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const entryExists = async (path) => {
+	try {
+		await lstat(path);
+		return true;
+	} catch (error) {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	}
+};
+//#endregion
+//#region src/fs/list-files.ts
+const listFiles = async (dir) => {
+	const entries = await readdir(dir, { withFileTypes: true });
+	return (await Promise.all(entries.map(async (entry) => {
+		if (entry.isDirectory()) return (await listFiles(join(dir, entry.name))).map((rel) => join(entry.name, rel));
+		return [entry.name];
+	}))).flat();
+};
+//#endregion
+//#region src/fs/prune-empty-dirs.ts
+const pruneEmptyDirs = async (repoRoot, removedFiles) => {
+	const dirs = /* @__PURE__ */ new Set();
+	for (const relPath of removedFiles) {
+		let dir = dirname(relPath);
+		while (dir !== "." && dir !== sep) {
+			dirs.add(dir);
+			dir = dirname(dir);
+		}
+	}
+	const ordered = [...dirs].toSorted((a, b) => b.length - a.length);
+	for (const dir of ordered) try {
+		await rmdir(join(repoRoot, dir));
+	} catch {}
+};
+//#endregion
+//#region src/fs/fs.constant.ts
+const SPECIAL_FILE_REFUSAL = "the entry is not a regular file (a FIFO, a socket or a device), so it was not read.";
+const DANGLING_WRITE_REFUSAL = "the entry is a symlink whose target is missing, so it was not written (writing through it would create the file it points at).";
+const SPECIAL_FILE_WRITE_REFUSAL = "the entry is not a regular file (a FIFO, a socket or a device), so it was not written.";
+//#endregion
+//#region src/fs/read-regular-file.ts
+const readRegularFile = async (path) => {
+	let handle;
+	try {
+		handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+	} catch (error) {
+		const target = await stat(path).catch(() => void 0);
+		if (target && !target.isFile() && !target.isDirectory()) throw new Error(SPECIAL_FILE_REFUSAL, { cause: error });
+		throw error;
+	}
+	try {
+		const target = await handle.stat();
+		if (!target.isFile() && !target.isDirectory()) throw new Error(SPECIAL_FILE_REFUSAL);
+		return await handle.readFile("utf8");
+	} finally {
+		await handle.close();
+	}
+};
+//#endregion
+//#region src/fs/write-managed.ts
+const writeManaged = async (root, relPath, content, executable) => {
+	const dest = join(root, relPath);
+	await mkdir(dirname(dest), { recursive: true });
+	await writeFile(dest, content);
+	await chmod(dest, executable ? 493 : 420);
+};
+//#endregion
+//#region src/fs/write-regular-file.ts
+const writeRegularFile = async (path, text) => {
+	let handle;
+	try {
+		handle = await openForWrite(path);
+	} catch (error) {
+		const target = await stat(path).catch(() => void 0);
+		if (target && !target.isFile() && !target.isDirectory()) throw new Error(SPECIAL_FILE_WRITE_REFUSAL, { cause: error });
+		throw error;
+	}
+	try {
+		if (!(await handle.stat()).isFile()) throw new Error(SPECIAL_FILE_WRITE_REFUSAL);
+		await handle.writeFile(text, "utf8");
+	} finally {
+		await handle.close();
+	}
+};
+const WRITE = constants.O_WRONLY | constants.O_TRUNC | constants.O_NONBLOCK;
+const openForWrite = async (path) => {
+	try {
+		return await open(path, WRITE);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	try {
+		return await open(path, WRITE | constants.O_CREAT | constants.O_EXCL);
+	} catch (error) {
+		const link = await lstat(path).catch(() => void 0);
+		if (error.code === "EEXIST" && link?.isSymbolicLink()) throw new Error(DANGLING_WRITE_REFUSAL, { cause: error });
+		throw error;
+	}
+};
+//#endregion
+//#region src/fs/symlink-guard.ts
+const assertNoSymlinkTraversal = async (root, relPaths) => {
+	const components = /* @__PURE__ */ new Set();
+	for (const relPath of relPaths) {
+		let current = "";
+		for (const part of relPath.split(sep)) {
+			if (part.length === 0) continue;
+			current = current ? join(current, part) : part;
+			components.add(current);
+		}
+	}
+	const offenders = (await Promise.all([...components].map(async (rel) => {
+		try {
+			return (await lstat(join(root, rel))).isSymbolicLink() ? rel : null;
+		} catch {
+			return null;
+		}
+	}))).filter((rel) => rel !== null);
+	if (offenders.length > 0) throw new Error("Refusing to write — a managed path traverses a symlink (a redirect could land outside the repo):\n" + offenders.map((rel) => `  ${rel}`).join("\n"));
+};
+//#endregion
 //#region src/config/config-error.ts
 const formatConfigError = (schema, error) => {
 	return error.issues.flatMap((issue) => formatIssue(schema, issue)).join("\n");
@@ -149,7 +279,7 @@ const readHarnessConfig = async (repoRoot) => {
 	const configPath = join(repoRoot, HARNESS_CONFIG_FILENAME);
 	let raw;
 	try {
-		raw = await readFile(configPath, "utf8");
+		raw = await readRegularFile(configPath);
 	} catch (cause) {
 		if (cause.code === "ENOENT") throw new Error(`${HARNESS_CONFIG_FILENAME} not found at ${repoRoot}. Run \`lemony install\` first.`, { cause });
 		throw new Error(`Cannot read ${HARNESS_CONFIG_FILENAME} at ${repoRoot}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
@@ -179,6 +309,21 @@ const readHarnessConfig = async (repoRoot) => {
 	if (!result.success) throw new Error(`${HARNESS_CONFIG_FILENAME} is invalid:\n${formatConfigError(harnessConfigSchema, result.error)}`);
 	return result.data;
 };
+const readOptionalHarnessConfig = async (repoRoot) => {
+	let present;
+	try {
+		present = await entryExists(join(repoRoot, HARNESS_CONFIG_FILENAME));
+	} catch (error) {
+		throw new Error(`Cannot read ${HARNESS_CONFIG_FILENAME} at ${repoRoot}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+	if (!present) return void 0;
+	try {
+		return await readHarnessConfig(repoRoot);
+	} catch (error) {
+		if (error.cause?.code === "ENOENT") throw new Error(`Cannot read ${HARNESS_CONFIG_FILENAME} at ${repoRoot}: the entry is there but its target is missing (a broken symlink?).`, { cause: error });
+		throw error;
+	}
+};
 //#endregion
 //#region src/config/compare-version.ts
 const PRERELEASE_RANK = {
@@ -995,70 +1140,6 @@ const failureReason$1 = (result) => {
 	return `\`gh\` failed (exit ${result.code})${suffix}${detail ? `: ${detail}` : ""}`;
 };
 //#endregion
-//#region src/fs/exists.ts
-const pathExists = async (path) => {
-	try {
-		await stat(path);
-		return true;
-	} catch {
-		return false;
-	}
-};
-//#endregion
-//#region src/fs/list-files.ts
-const listFiles = async (dir) => {
-	const entries = await readdir(dir, { withFileTypes: true });
-	return (await Promise.all(entries.map(async (entry) => {
-		if (entry.isDirectory()) return (await listFiles(join(dir, entry.name))).map((rel) => join(entry.name, rel));
-		return [entry.name];
-	}))).flat();
-};
-//#endregion
-//#region src/fs/prune-empty-dirs.ts
-const pruneEmptyDirs = async (repoRoot, removedFiles) => {
-	const dirs = /* @__PURE__ */ new Set();
-	for (const relPath of removedFiles) {
-		let dir = dirname(relPath);
-		while (dir !== "." && dir !== sep) {
-			dirs.add(dir);
-			dir = dirname(dir);
-		}
-	}
-	const ordered = [...dirs].toSorted((a, b) => b.length - a.length);
-	for (const dir of ordered) try {
-		await rmdir(join(repoRoot, dir));
-	} catch {}
-};
-//#endregion
-//#region src/fs/write-managed.ts
-const writeManaged = async (root, relPath, content, executable) => {
-	const dest = join(root, relPath);
-	await mkdir(dirname(dest), { recursive: true });
-	await writeFile(dest, content);
-	await chmod(dest, executable ? 493 : 420);
-};
-//#endregion
-//#region src/fs/symlink-guard.ts
-const assertNoSymlinkTraversal = async (root, relPaths) => {
-	const components = /* @__PURE__ */ new Set();
-	for (const relPath of relPaths) {
-		let current = "";
-		for (const part of relPath.split(sep)) {
-			if (part.length === 0) continue;
-			current = current ? join(current, part) : part;
-			components.add(current);
-		}
-	}
-	const offenders = (await Promise.all([...components].map(async (rel) => {
-		try {
-			return (await lstat(join(root, rel))).isSymbolicLink() ? rel : null;
-		} catch {
-			return null;
-		}
-	}))).filter((rel) => rel !== null);
-	if (offenders.length > 0) throw new Error("Refusing to write — a managed path traverses a symlink (a redirect could land outside the repo):\n" + offenders.map((rel) => `  ${rel}`).join("\n"));
-};
-//#endregion
 //#region src/design-tokens/design-tokens.constant.ts
 const DESIGN_TOKENS_FILE = "docs/design-tokens.json";
 const SCANNED_EXTENSIONS = [
@@ -1101,6 +1182,19 @@ const IGNORED_DIRS = /* @__PURE__ */ new Set([
 	".cache",
 	".claude"
 ]);
+const NESTED_TOO_DEEPLY = `${DESIGN_TOKENS_FILE} nests deeper than 64 levels, the most Lemony reads.`;
+//#endregion
+//#region src/design-tokens/read-token-file.ts
+const readOptionalTokenFile = async (repoRoot) => {
+	const tokenPath = join(repoRoot, DESIGN_TOKENS_FILE);
+	try {
+		if (!await entryExists(tokenPath)) return void 0;
+		return await readRegularFile(tokenPath);
+	} catch (error) {
+		if (error.code === "ENOENT") throw new Error(`Cannot read ${DESIGN_TOKENS_FILE} at ${repoRoot}: the entry is there but its target is missing (a broken symlink?).`, { cause: error });
+		throw new Error(`Cannot read ${DESIGN_TOKENS_FILE} at ${repoRoot}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+};
 //#endregion
 //#region src/design-tokens/design-tokens.model.ts
 const TOKEN_TIERS = [
@@ -1109,6 +1203,46 @@ const TOKEN_TIERS = [
 	"component"
 ];
 //#endregion
+//#region src/design-tokens/contrast.constant.ts
+const CONTRAST_EXTENSION = "com.lemony.contrast";
+const MODES_EXTENSION = "com.lemony.modes";
+const BASE_MODE = "base";
+const DEFAULT_LEVEL = "text";
+const WCAG_FLOORS = {
+	text: 4.5,
+	large: 3,
+	"non-text": 3
+};
+//#endregion
+//#region src/design-tokens/nesting-depth.ts
+const exceedsNestingLimit = (value, limit = 64) => {
+	const pending = [{
+		node: value,
+		depth: 1
+	}];
+	for (let next = pending.pop(); next !== void 0; next = pending.pop()) {
+		const { node, depth } = next;
+		if (typeof node !== "object" || node === null) continue;
+		if (depth > limit) return true;
+		for (const child of Object.values(node)) pending.push({
+			node: child,
+			depth: depth + 1
+		});
+	}
+	return false;
+};
+//#endregion
+//#region src/design-tokens/non-finite-number.ts
+const nonFiniteNumberFaults = (value) => nonFiniteNumbers(value, []).map(({ path, number }) => `${DESIGN_TOKENS_FILE} has a number at "${path}" too large for JSON to carry: it reads as ${number}, and rewriting the file would turn it into null.`);
+const nonFiniteNumbers = (value, path) => {
+	if (typeof value === "number") return Number.isFinite(value) ? [] : [{
+		path: path.join("."),
+		number: value
+	}];
+	if (typeof value !== "object" || value === null) return [];
+	return Object.entries(value).flatMap(([key, child]) => nonFiniteNumbers(child, [...path, key]));
+};
+//#endregion
 //#region src/design-tokens/token-parse.ts
 const aliasTarget = (value) => {
 	if (typeof value !== "string") return void 0;
@@ -1119,15 +1253,28 @@ const isRecord = (value) => typeof value === "object" && value !== null && !Arra
 //#endregion
 //#region src/design-tokens/design-tokens.ts
 const runValidate = async (inputs) => {
-	const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
-	if (!await pathExists(tokenPath)) return {
+	let raw;
+	try {
+		raw = await readOptionalTokenFile(inputs.repoRoot);
+	} catch (error) {
+		return {
+			ok: false,
+			tokensFound: true,
+			tokenCount: 0,
+			filesScanned: 0,
+			violations: [{
+				kind: "unreadable-token-file",
+				message: error instanceof Error ? error.message : String(error)
+			}]
+		};
+	}
+	if (raw === void 0) return {
 		ok: true,
 		tokensFound: false,
 		tokenCount: 0,
 		filesScanned: 0,
 		violations: []
 	};
-	const raw = await readFile(tokenPath, "utf8");
 	const fileCheck = validateTokenFile(raw);
 	if (!fileCheck.ok) return {
 		ok: false,
@@ -1137,6 +1284,19 @@ const runValidate = async (inputs) => {
 		violations: fileCheck.violations
 	};
 	const scanRoot = inputs.scanDir ? join(inputs.repoRoot, inputs.scanDir) : inputs.repoRoot;
+	if (inputs.scanDir) {
+		const unreadable = await describeUnreadableDir(scanRoot);
+		if (unreadable !== void 0) return {
+			ok: false,
+			tokensFound: true,
+			tokenCount: fileCheck.tokenCount,
+			filesScanned: 0,
+			violations: [{
+				kind: "unreadable-scan-root",
+				message: `--scan=${inputs.scanDir} ${unreadable} — nothing was scanned.`
+			}]
+		};
+	}
 	const extensions = mergeExtensions(inputs.extraExtensions);
 	const sourceViolations = await scanSource(inputs.repoRoot, scanRoot, extensions);
 	return {
@@ -1147,6 +1307,13 @@ const runValidate = async (inputs) => {
 		violations: sourceViolations.violations
 	};
 };
+const summarizeTokenFileViolations = (raw) => summarizeMessages(tokenFileViolationMessages(raw));
+const tokenFileViolationMessages = (raw) => validateTokenFile(raw).violations.map((violation) => violation.message);
+const summarizeMessages = (messages) => {
+	const [first, ...more] = messages;
+	if (first === void 0) return void 0;
+	return `${first}${more.length > 0 ? ` (and ${more.length} more)` : ""}`;
+};
 const validateTokenFile = (raw) => {
 	let parsed;
 	try {
@@ -1169,7 +1336,19 @@ const validateTokenFile = (raw) => {
 			message: `${DESIGN_TOKENS_FILE} must be a JSON object with primitive/semantic/component tiers.`
 		}]
 	};
+	if (exceedsNestingLimit(parsed)) return {
+		ok: false,
+		tokenCount: 0,
+		violations: [{
+			kind: "malformed-token-file",
+			message: NESTED_TOO_DEEPLY
+		}]
+	};
 	const violations = [];
+	for (const message of nonFiniteNumberFaults(parsed)) violations.push({
+		kind: "malformed-token-file",
+		message
+	});
 	for (const key of Object.keys(parsed)) {
 		if (key.startsWith("$")) continue;
 		if (!TOKEN_TIERS.includes(key)) violations.push({
@@ -1197,6 +1376,10 @@ const validateTokenFile = (raw) => {
 		violations
 	};
 };
+const modeValues = (extensions) => {
+	const modes = isRecord(extensions) ? extensions[MODES_EXTENSION] : void 0;
+	return isRecord(modes) ? modes : {};
+};
 const collectTokens$1 = (node, tier, path, out, violations) => {
 	for (const [key, child] of Object.entries(node)) {
 		if (key.startsWith("$")) continue;
@@ -1211,7 +1394,8 @@ const collectTokens$1 = (node, tier, path, out, violations) => {
 		if ("$value" in child) {
 			out.set(childPath, {
 				tier,
-				value: child.$value
+				value: child.$value,
+				modes: modeValues(child["$extensions"])
 			});
 			const stray = Object.keys(child).filter((k) => !k.startsWith("$"));
 			if (stray.length > 0) violations.push({
@@ -1223,6 +1407,13 @@ const collectTokens$1 = (node, tier, path, out, violations) => {
 };
 const collectAliasViolations = (tokens) => {
 	const violations = [];
+	for (const [path, token] of tokens) for (const [mode, value] of Object.entries(token.modes)) {
+		const alias = aliasTarget(value);
+		if (alias !== void 0 && !tokens.has(alias)) violations.push({
+			kind: "unresolved-alias",
+			message: `token "${path}" references "{${alias}}" in mode "${mode}", which does not exist.`
+		});
+	}
 	for (const [path, token] of tokens) {
 		const alias = aliasTarget(token.value);
 		if (alias === void 0) continue;
@@ -1245,9 +1436,16 @@ const collectAliasViolations = (tokens) => {
 			message: `token "${path}" has an alias chain that never resolves to a literal value (alias cycle).`
 		});
 	}
+	for (const [path, token] of tokens) for (const [mode, value] of Object.entries(token.modes)) {
+		if (aliasTarget(value) === void 0) continue;
+		if (aliasChainCycles(path, tokens, mode)) violations.push({
+			kind: "cyclic-alias",
+			message: `token "${path}" has an alias chain in mode "${mode}" that never resolves to a literal value (alias cycle).`
+		});
+	}
 	return violations;
 };
-const aliasChainCycles = (start, tokens) => {
+const aliasChainCycles = (start, tokens, mode) => {
 	const seen = /* @__PURE__ */ new Set();
 	let current = start;
 	while (current !== void 0) {
@@ -1255,7 +1453,7 @@ const aliasChainCycles = (start, tokens) => {
 		seen.add(current);
 		const token = tokens.get(current);
 		if (token === void 0) return false;
-		current = aliasTarget(token.value);
+		current = aliasTarget(mode !== void 0 && Object.hasOwn(token.modes, mode) ? token.modes[mode] : token.value);
 	}
 	return false;
 };
@@ -1268,16 +1466,38 @@ const mergeExtensions = (extra) => {
 	}
 	return set;
 };
+const codeOf = (error) => error.code ?? String(error);
+const describeUnreadableDir = async (dir) => {
+	try {
+		await readdir(dir);
+	} catch (error) {
+		const code = codeOf(error);
+		if (code === "ENOENT") return "does not exist";
+		if (code === "ENOTDIR") return "is not a directory";
+		return `cannot be listed (${code})`;
+	}
+	try {
+		await access(dir, constants.R_OK | constants.X_OK);
+		return;
+	} catch (error) {
+		return `can be listed but not searched (${codeOf(error)})`;
+	}
+};
 const scanSource = async (repoRoot, scanRoot, extensions) => {
 	if (!await pathExists(scanRoot)) return {
 		filesScanned: 0,
 		violations: []
 	};
-	const files = (await collectSourceFiles(scanRoot, extensions)).toSorted();
-	const violations = [];
+	const unlistable = [];
+	const files = (await collectSourceFiles(scanRoot, extensions, unlistable)).toSorted();
+	const violations = unlistable.map(({ dir, code }) => ({
+		kind: "unreadable-source-dir",
+		message: `directory cannot be listed (${code}) — nothing under it was scanned.`,
+		file: relative(repoRoot, dir).split(sep).join("/") || "."
+	})).toSorted((a, b) => a.file.localeCompare(b.file));
 	let filesScanned = 0;
 	for (const file of files) {
-		const content = await readFile(file, "utf8").catch(() => void 0);
+		const content = await readRegularFile(file).catch(() => void 0);
 		if (content === void 0) continue;
 		filesScanned += 1;
 		const relPath = relative(repoRoot, file).split(sep).join("/");
@@ -1288,13 +1508,22 @@ const scanSource = async (repoRoot, scanRoot, extensions) => {
 		violations
 	};
 };
-const collectSourceFiles = async (dir, extensions) => {
-	const entries = await readdir(dir, { withFileTypes: true });
+const collectSourceFiles = async (dir, extensions, unlistable) => {
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch (error) {
+		unlistable.push({
+			dir,
+			code: codeOf(error)
+		});
+		return [];
+	}
 	return (await Promise.all(entries.map(async (entry) => {
 		const full = join(dir, entry.name);
 		if (entry.isDirectory()) {
 			if (IGNORED_DIRS.has(entry.name)) return [];
-			return collectSourceFiles(full, extensions);
+			return collectSourceFiles(full, extensions, unlistable);
 		}
 		return extensions.has(extname(entry.name).toLowerCase()) ? [full] : [];
 	}))).flat();
@@ -1468,17 +1697,6 @@ const contrastRatio = (foreground, background) => {
 	return Math.round((light + .05) / (dark + .05) * 100) / 100;
 };
 //#endregion
-//#region src/design-tokens/contrast.constant.ts
-const CONTRAST_EXTENSION = "com.lemony.contrast";
-const MODES_EXTENSION = "com.lemony.modes";
-const BASE_MODE = "base";
-const DEFAULT_LEVEL = "text";
-const WCAG_FLOORS = {
-	text: 4.5,
-	large: 3,
-	"non-text": 3
-};
-//#endregion
 //#region src/design-tokens/contrast.model.ts
 const CONTRAST_LEVELS = [
 	"text",
@@ -1488,38 +1706,57 @@ const CONTRAST_LEVELS = [
 //#endregion
 //#region src/design-tokens/contrast.ts
 const runContrast = async (inputs) => {
-	const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
-	if (!await pathExists(tokenPath)) return emptyResult$1(false);
-	const raw = await readFile(tokenPath, "utf8");
+	let raw;
+	let unreadable;
+	try {
+		raw = await readOptionalTokenFile(inputs.repoRoot);
+	} catch (error) {
+		unreadable = error instanceof Error ? error.message : String(error);
+	}
+	const verify = inputs.verify ? await runVerifier(inputs.verify) : void 0;
+	const withVerify = (result) => ({
+		...result,
+		ok: result.ok && (verify === void 0 || verify.code === 0),
+		...verify === void 0 ? {} : { verify }
+	});
+	if (unreadable !== void 0) return withVerify({
+		...emptyResult$1(true),
+		ok: false,
+		problems: [unreadable]
+	});
+	if (raw === void 0) return withVerify(emptyResult$1(false));
 	let parsed;
 	try {
 		parsed = JSON.parse(raw);
 	} catch (error) {
-		return {
+		return withVerify({
 			...emptyResult$1(true),
 			ok: false,
 			problems: [`${DESIGN_TOKENS_FILE} is not valid JSON (${error instanceof Error ? error.message : String(error)}) — run \`design-tokens validate\` first.`]
-		};
+		});
 	}
-	if (!isRecord(parsed)) return {
+	if (!isRecord(parsed)) return withVerify({
 		...emptyResult$1(true),
 		ok: false,
 		problems: [`${DESIGN_TOKENS_FILE} must be a JSON object — run \`design-tokens validate\` first.`]
-	};
+	});
+	if (exceedsNestingLimit(parsed)) return withVerify({
+		...emptyResult$1(true),
+		ok: false,
+		problems: [`${NESTED_TOO_DEEPLY} Run \`design-tokens validate\` first.`]
+	});
 	const tokens = collectTokens(parsed);
 	const problems = [];
 	const modes = declaredModes(tokens);
 	const specs = discoverPairs(tokens, modes, problems);
 	const pairs = measurePairs(specs, modes, tokens);
-	const verify = inputs.verify ? await runVerifier(inputs.verify) : void 0;
-	return {
-		ok: problems.length === 0 && pairs.every((pair) => pair.passes) && (verify === void 0 || verify.code === 0),
+	return withVerify({
+		ok: problems.length === 0 && pairs.every((pair) => pair.passes),
 		tokensFound: true,
 		pairsChecked: pairs.length,
 		pairs,
-		problems,
-		...verify === void 0 ? {} : { verify }
-	};
+		problems
+	});
 };
 const emptyResult$1 = (tokensFound) => ({
 	ok: true,
@@ -1564,12 +1801,12 @@ const declaredModes = (tokens) => {
 };
 const pairKey = (spec) => `${spec.foreground}|${spec.background}`;
 const discoverPairs = (tokens, modes, problems) => {
-	const convention = new Map(conventionPairs(tokens).map((spec) => [pairKey(spec), spec]));
+	const convention = new Map(conventionPairs(tokens, modes, problems).map((spec) => [pairKey(spec), spec]));
 	const explicit = extensionPairs(tokens, modes, problems);
 	for (const spec of explicit) convention.delete(pairKey(spec));
 	return [...convention.values(), ...explicit];
 };
-const conventionPairs = (tokens) => {
+const conventionPairs = (tokens, modes, problems) => {
 	const pairs = [];
 	for (const [path, token] of tokens) {
 		if (token.tier !== "semantic") continue;
@@ -1580,6 +1817,21 @@ const conventionPairs = (tokens) => {
 		if (!tokens.has(basePath)) continue;
 		if (!resolveColor(path, "base", tokens)) continue;
 		if (!resolveColor(basePath, "base", tokens)) continue;
+		const broken = [{
+			end: path,
+			other: basePath
+		}, {
+			end: basePath,
+			other: path
+		}].flatMap(({ end, other }) => modes.flatMap((mode) => {
+			const fault = modeAliasBreak(end, mode, tokens);
+			if (fault === void 0) return [];
+			return fault === "too-deep" ? [`token "${end}" has a "${mode}" mode alias chain of 64 hops or more, which contrast does not follow, so its convention pair with "${other}" is not measured — shorten the chain.`] : [`token "${end}" has a "${mode}" mode alias that does not resolve (a missing token or an alias cycle), so its convention pair with "${other}" is not measured — run \`design-tokens validate\`.`];
+		}));
+		if (broken.length > 0) {
+			problems.push(...broken);
+			continue;
+		}
 		pairs.push({
 			foreground: path,
 			background: basePath,
@@ -1794,6 +2046,20 @@ const resolveColor = (path, mode, tokens, seen = /* @__PURE__ */ new Set()) => {
 	if (alias !== void 0) return resolveColor(alias, mode, tokens, seen);
 	return typeof value === "string" ? parseColor(value) : void 0;
 };
+const modeAliasBreak = (path, mode, tokens) => {
+	const seen = /* @__PURE__ */ new Set();
+	let current = path;
+	while (current !== void 0) {
+		if (seen.has(current)) return "unresolved";
+		seen.add(current);
+		const token = tokens.get(current);
+		if (!token) return "unresolved";
+		const modes = readExtension(token.node, MODES_EXTENSION);
+		const value = isRecord(modes) && Object.hasOwn(modes, mode) ? modes[mode] : token.value;
+		current = aliasTarget(value);
+	}
+	return seen.size > 64 ? "too-deep" : void 0;
+};
 const runVerifier = async (hook) => {
 	const result = await hook.run("sh", ["-c", hook.command]);
 	return {
@@ -1804,32 +2070,105 @@ const runVerifier = async (hook) => {
 //#endregion
 //#region src/design-tokens/design-sync.constant.ts
 const DESIGN_TOOL_EXTENSION = "com.lemony.design-tool";
+const NEUTRAL_STRING_VALUES = "The neutral format carries every value as a string (e.g. \"1024\", \"#3b82f6\") — fix the adapter that wrote the file.";
+const NEUTRAL_MODES_OBJECT = "It maps each mode name to that mode's value (e.g. {\"dark\": \"#000000\"}) — fix the adapter that wrote the file.";
+const NEUTRAL_VALUE_OR_REF = "Each variable carries a string \"value\" (a literal) or a non-empty string \"ref\" (the name of the variable it aliases) — fix the adapter that wrote the file.";
+const NEUTRAL_NAME_SHAPE = "A name is dot-separated segments, like \"primitive.color.brand\" — fix the adapter that wrote the file.";
+const VALIDATE_HINT = "Run `lemony design-tokens validate` for the full list.";
+const IMPORT_INVALID_HINT = "Change the `--only` slice (add what it references), or fix the file first; nothing was written.";
+const IMPORT_NOT_CARRIED_HINT = "add the token in the design tool (or in docs/design-tokens.json) first, or leave out what references it; nothing was written.";
+const IMPORT_PREVIEW_INVALID_HINT = "`--apply` refuses any slice that leaves it failing: include what repairs it, or fix the file first.";
+const IMPORT_TOO_DEEP_HINT = "Shorten the dotted names of the variables that land that deep, or leave them out with `--only`; nothing was written.";
+//#endregion
+//#region src/design-tokens/read-required-file.ts
+const readRequiredFile = async (path, label) => {
+	try {
+		return await readRegularFile(path);
+	} catch (error) {
+		if (error.code === "ENOENT") {
+			if (!await entryExists(path)) throw new Error(`${label} file not found: ${path}`, { cause: error });
+			throw new Error(`Cannot read ${label} file at ${path}: the entry is there but its target is missing (a broken symlink?).`, { cause: error });
+		}
+		throw new Error(`Cannot read ${label} file at ${path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+};
 //#endregion
 //#region src/design-tokens/neutral-mapping.ts
 const KNOWN_TIERS = new Set(TOKEN_TIERS);
 const dtcgToNeutral = (parsed) => {
+	const nodes = tokenNodes(parsed);
+	const unsynced = unsyncedReasons(nodes);
 	const variables = [];
-	for (const tier of TOKEN_TIERS) {
-		const group = parsed[tier];
-		if (isRecord(group)) walk(group, tier, variables);
-	}
+	for (const [path, node] of nodes) if (!unsynced.has(path)) variables.push(toVariable$1(path, node));
 	return {
 		schemaVersion: 1,
 		variables: variables.toSorted(byName)
 	};
 };
-const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+const unsyncedTokens = (parsed) => [...unsyncedReasons(tokenNodes(parsed))].map(([path, reason]) => ({
+	path,
+	reason
+})).toSorted((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+const tokenNodes = (parsed) => {
+	const nodes = /* @__PURE__ */ new Map();
+	for (const tier of TOKEN_TIERS) {
+		const group = parsed[tier];
+		if (isRecord(group)) walk(group, tier, nodes);
+	}
+	return nodes;
+};
 const walk = (node, path, out) => {
 	for (const [key, child] of Object.entries(node)) {
 		if (key.startsWith("$") || !isRecord(child)) continue;
 		const childPath = `${path}.${key}`;
-		if ("$value" in child) out.push(toVariable$1(childPath, child));
+		if ("$value" in child) out.set(childPath, child);
 		else walk(child, childPath, out);
 	}
 };
+const unsyncedReasons = (nodes) => {
+	const reasons = /* @__PURE__ */ new Map();
+	for (const [path, node] of nodes) {
+		const reason = ownUnsyncedReason(node);
+		if (reason !== void 0) reasons.set(path, reason);
+	}
+	let grew = true;
+	while (grew) {
+		grew = false;
+		for (const [path, node] of nodes) {
+			if (reasons.has(path)) continue;
+			const target = aliasTargetsOf(node).find((name) => reasons.has(name));
+			if (target === void 0) continue;
+			reasons.set(path, `an alias to ${target}`);
+			grew = true;
+		}
+	}
+	return reasons;
+};
+const ownUnsyncedReason = (node) => {
+	if (isCompositeValue(node["$value"])) return "a composite value";
+	const modes = modesExtension(node);
+	if (modes === void 0) return void 0;
+	if (!isRecord(modes)) return "a modes extension that is not an object";
+	for (const [name, value] of Object.entries(modes)) {
+		if (name.trim().length === 0) return "a mode with a blank name";
+		if (name === "__proto__") return "a mode named \"__proto__\"";
+		if (!isScalar(value)) return `mode "${name}" holding neither text, a number nor a boolean`;
+	}
+};
+const aliasTargetsOf = (node) => {
+	const modes = modesExtension(node);
+	return [node["$value"], ...isRecord(modes) ? Object.values(modes) : []].map(aliasTarget).filter((target) => target !== void 0);
+};
+const modesExtension = (node) => {
+	const extensions = node["$extensions"];
+	return isRecord(extensions) ? extensions[MODES_EXTENSION] : void 0;
+};
+const isCompositeValue = (value) => typeof value === "object" && value !== null;
+const isScalar = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
 const toVariable$1 = (name, node) => {
 	const type = typeof node["$type"] === "string" ? node["$type"] : "";
-	const modes = readModes(node);
+	const modes = readModes$1(node);
 	const alias = aliasTarget(node["$value"]);
 	const base = {
 		name,
@@ -1846,37 +2185,64 @@ const toVariable$1 = (name, node) => {
 	};
 };
 const stringifyValue = (value) => value === void 0 || value === null ? "" : String(value);
-const readModes = (node) => {
-	const extensions = node["$extensions"];
-	const modes = isRecord(extensions) ? extensions[MODES_EXTENSION] : void 0;
+const readModes$1 = (node) => {
+	const modes = modesExtension(node);
 	if (!isRecord(modes)) return void 0;
 	const out = {};
-	for (const [name, value] of Object.entries(modes)) if (name.trim().length > 0 && typeof value === "string") out[name] = value;
+	for (const [name, value] of Object.entries(modes)) if (isScalar(value)) out[name] = String(value);
 	return Object.keys(out).length > 0 ? out : void 0;
 };
-const toIncoming = (variable) => {
-	const isAlias = variable.ref !== void 0;
-	const value = isAlias ? `{${variable.ref}}` : variable.value ?? "";
-	const type = variable.type;
+const landingPath = (variable, known) => {
 	const first = variable.name.split(".")[0] ?? "";
-	if (KNOWN_TIERS.has(first)) return withModes({
-		path: variable.name,
-		tier: first,
-		type,
-		value
-	}, variable);
-	const tier = isAlias ? "semantic" : "primitive";
-	return withModes({
-		path: `${tier}.${variable.name}`,
-		tier,
-		type,
+	if (KNOWN_TIERS.has(first)) return variable.name;
+	const existing = existingTierPath(variable.name, known);
+	if (existing !== void 0) return existing;
+	return `${variable.ref === void 0 ? "primitive" : "semantic"}.${variable.name}`;
+};
+const existingTierPath = (bare, known) => {
+	const matches = TOKEN_TIERS.map((tier) => `${tier}.${bare}`).filter((path) => known.has(path));
+	return matches.length === 1 ? matches[0] : void 0;
+};
+const refResolver = (neutral, known) => {
+	const landings = /* @__PURE__ */ new Map();
+	for (const variable of neutral.variables) landings.set(variable.name, landingPath(variable, known));
+	return (ref) => {
+		const first = ref.split(".")[0] ?? "";
+		if (KNOWN_TIERS.has(first)) return ref;
+		return landings.get(ref) ?? existingTierPath(ref, known) ?? ref;
+	};
+};
+const toIncoming = (variable, resolveRef, known) => {
+	const value = variable.ref === void 0 ? variable.value ?? "" : `{${resolveRef(variable.ref)}}`;
+	const path = landingPath(variable, known);
+	const token = {
+		path,
+		tier: path.split(".")[0],
+		type: variable.type,
 		value
-	}, variable);
+	};
+	if (!variable.modes) return token;
+	const modes = {};
+	for (const [mode, modeValue] of Object.entries(variable.modes)) {
+		const alias = aliasTarget(modeValue);
+		modes[mode] = alias === void 0 ? modeValue : `{${resolveRef(alias)}}`;
+	}
+	return {
+		...token,
+		modes
+	};
+};
+const incomingByPath = (neutral, known) => {
+	const resolveRef = refResolver(neutral, known);
+	const tokens = neutral.variables.map((variable) => ({
+		exact: KNOWN_TIERS.has(variable.name.split(".")[0] ?? ""),
+		token: toIncoming(variable, resolveRef, known)
+	}));
+	const byPath = /* @__PURE__ */ new Map();
+	for (const { exact, token } of tokens) if (exact) byPath.set(token.path, token);
+	for (const { exact, token } of tokens) if (!exact && !byPath.has(token.path)) byPath.set(token.path, token);
+	return byPath;
 };
-const withModes = (token, variable) => variable.modes ? {
-	...token,
-	modes: variable.modes
-} : token;
 const comparisonKey = (type, value, modes) => JSON.stringify({
 	type,
 	value,
@@ -1891,41 +2257,78 @@ const sortedModes = (modes) => {
 const diffNeutralAgainstJson = (neutral, parsed) => {
 	const current = /* @__PURE__ */ new Map();
 	for (const variable of dtcgToNeutral(parsed).variables) current.set(variable.name, variable);
+	const unsynced = new Map(unsyncedTokens(parsed).map(({ path, reason }) => [path, reason]));
 	const changes = [];
-	for (const variable of neutral.variables) {
-		const incoming = toIncoming(variable);
+	for (const incoming of incomingByPath(neutral, /* @__PURE__ */ new Set([...current.keys(), ...unsynced.keys()])).values()) {
+		const reason = unsynced.get(incoming.path);
+		if (reason !== void 0) {
+			changes.push({
+				path: incoming.path,
+				tier: incoming.tier,
+				kind: "changed",
+				before: `(outside the sync: ${reason})`,
+				after: incoming.value
+			});
+			continue;
+		}
 		const existing = current.get(incoming.path);
 		const after = incoming.value;
 		const before = existing ? neutralValue(existing) : void 0;
+		const kind = classifyImport(existing, incoming);
 		changes.push({
 			path: incoming.path,
 			tier: incoming.tier,
-			kind: classifyImport(existing, incoming, variable),
+			kind,
 			...before !== void 0 ? { before } : {},
-			after
+			after,
+			...existing && kind === "changed" ? changeDetail(existing, incoming) : {}
 		});
 	}
 	return changes.toSorted((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
 };
+const changeDetail = (existing, incoming) => {
+	const detail = {};
+	if (existing.type !== incoming.type) detail.typeChange = {
+		before: existing.type,
+		after: incoming.type
+	};
+	const before = existing.modes ?? {};
+	const after = incoming.modes ?? {};
+	const modeChanges = [.../* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])].toSorted().filter((mode) => before[mode] !== after[mode]).map((mode) => ({
+		mode,
+		...before[mode] !== void 0 ? { before: before[mode] } : {},
+		...after[mode] !== void 0 ? { after: after[mode] } : {}
+	}));
+	if (modeChanges.length > 0) detail.modeChanges = modeChanges;
+	return detail;
+};
 const neutralValue = (variable) => variable.ref !== void 0 ? `{${variable.ref}}` : variable.value ?? "";
-const classifyImport = (existing, incoming, variable) => {
+const classifyImport = (existing, incoming) => {
 	if (!existing) return "new";
-	return comparisonKey(existing.type, neutralValue(existing), existing.modes) === comparisonKey(incoming.type, incoming.value, variable.modes) ? "unchanged" : "changed";
+	return comparisonKey(existing.type, neutralValue(existing), existing.modes) === comparisonKey(incoming.type, incoming.value, incoming.modes) ? "unchanged" : "changed";
 };
 const mergeNeutralIntoJson = (neutral, parsed, only) => {
 	const merged = structuredClone(parsed);
 	const onlySet = only ? new Set(only) : void 0;
 	const written = [];
 	const skipped = [];
-	for (const variable of neutral.variables) {
-		const incoming = toIncoming(variable);
+	const unsyncedLanded = [];
+	const current = new Map(dtcgToNeutral(parsed).variables.map((variable) => [variable.name, variable]));
+	const unsynced = new Set(unsyncedTokens(parsed).map(({ path }) => path));
+	for (const incoming of incomingByPath(neutral, /* @__PURE__ */ new Set([...current.keys(), ...unsynced])).values()) {
 		if (onlySet && !onlySet.has(incoming.path)) continue;
+		if (unsynced.has(incoming.path)) {
+			unsyncedLanded.push(incoming.path);
+			continue;
+		}
+		if (classifyImport(current.get(incoming.path), incoming) === "unchanged") continue;
 		(setToken(merged, incoming) ? written : skipped).push(incoming.path);
 	}
 	return {
 		merged,
 		written: written.toSorted(),
-		skipped: skipped.toSorted()
+		skipped: skipped.toSorted(),
+		unsynced: unsyncedLanded.toSorted()
 	};
 };
 const isTokenNode = (value) => isRecord(value) && "$value" in value;
@@ -1948,17 +2351,44 @@ const setToken = (root, incoming) => {
 		if (!isRecord(next)) node[segment] = {};
 		node = node[segment];
 	}
-	const leaf = { $value: incoming.value };
+	const existing = node[leafKey];
+	const leaf = isRecord(existing) ? { ...existing } : {};
+	const typeBefore = typeof leaf["$type"] === "string" ? leaf["$type"] : "";
+	const sameType = incoming.type === typeBefore;
+	const keep = (before, text) => sameType ? keptScalar(before, text) : text;
+	leaf["$value"] = keep(leaf["$value"], incoming.value);
 	if (incoming.type.length > 0) leaf["$type"] = incoming.type;
-	if (incoming.modes) leaf["$extensions"] = { [MODES_EXTENSION]: incoming.modes };
+	else delete leaf["$type"];
+	const extensions = isRecord(leaf["$extensions"]) ? { ...leaf["$extensions"] } : {};
+	if (incoming.modes) {
+		const before = extensions[MODES_EXTENSION];
+		const modes = {};
+		for (const [mode, value] of Object.entries(incoming.modes)) modes[mode] = keep(isRecord(before) && Object.hasOwn(before, mode) ? before[mode] : void 0, value);
+		extensions[MODES_EXTENSION] = modes;
+	} else delete extensions[MODES_EXTENSION];
+	if (Object.keys(extensions).length > 0) leaf["$extensions"] = extensions;
+	else delete leaf["$extensions"];
 	node[leafKey] = leaf;
 	return true;
 };
+const keptScalar = (before, incoming) => (typeof before === "number" || typeof before === "boolean") && String(before) === incoming ? before : incoming;
+const danglingAliasTargets = (parsed, paths) => {
+	const { variables } = dtcgToNeutral(parsed);
+	const names = new Set(variables.map((variable) => variable.name));
+	const wanted = new Set(paths);
+	const dangling = /* @__PURE__ */ new Set();
+	for (const variable of variables) {
+		if (!wanted.has(variable.name)) continue;
+		const targets = [variable.ref, ...Object.values(variable.modes ?? {}).map(aliasTarget)];
+		for (const target of targets) if (target !== void 0 && !names.has(target)) dangling.add(target);
+	}
+	return [...dangling].toSorted();
+};
 const upsertPlan = (parsed, toolState) => {
-	const current = /* @__PURE__ */ new Map();
-	for (const variable of toolState?.variables ?? []) current.set(variable.name, variable);
+	const { variables } = dtcgToNeutral(parsed);
+	const current = toolState ? incomingByPath(toolState, /* @__PURE__ */ new Set([...variables.map((variable) => variable.name), ...unsyncedTokens(parsed).map(({ path }) => path)])) : /* @__PURE__ */ new Map();
 	const plan = [];
-	for (const variable of dtcgToNeutral(parsed).variables) plan.push({
+	for (const variable of variables) plan.push({
 		name: variable.name,
 		kind: classifyExport(variable, current)
 	});
@@ -1967,45 +2397,78 @@ const upsertPlan = (parsed, toolState) => {
 const classifyExport = (projected, current) => {
 	const existing = current.get(projected.name);
 	if (!existing) return "create";
-	return comparisonKey(projected.type, neutralValue(projected), projected.modes) === comparisonKey(existing.type, neutralValue(existing), existing.modes) ? "unchanged" : "update";
+	return comparisonKey(projected.type, neutralValue(projected), projected.modes) === comparisonKey(existing.type, existing.value, existing.modes) ? "unchanged" : "update";
 };
 //#endregion
 //#region src/design-tokens/sync-io.ts
-const parseNeutralFile = (raw) => {
+const parseNeutralFile = (raw, label) => {
 	let parsed;
 	try {
 		parsed = JSON.parse(raw);
 	} catch (error) {
-		throw new Error(`neutral file is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		throw new Error(`${label} file is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
 	}
-	if (!isRecord(parsed) || !Array.isArray(parsed["variables"])) throw new Error("neutral file must be a JSON object with a \"variables\" array.");
+	if (!isRecord(parsed) || !Array.isArray(parsed["variables"])) throw new Error(`${label} file must be a JSON object with a "variables" array.`);
 	const schemaVersion = typeof parsed["schemaVersion"] === "number" ? parsed["schemaVersion"] : 0;
 	const provider = typeof parsed["provider"] === "string" ? parsed["provider"] : void 0;
+	const variables = parsed["variables"].flatMap((entry) => toVariable(entry, label));
+	const seen = /* @__PURE__ */ new Set();
+	for (const { name } of variables) {
+		if (seen.has(name)) throw new Error(`${label} file: variable "${name}" appears more than once — fix the adapter that wrote the file.`);
+		seen.add(name);
+	}
 	return {
 		schemaVersion,
 		...provider ? { provider } : {},
-		variables: parsed["variables"].flatMap(toVariable)
+		variables
 	};
 };
-const toVariable = (raw) => {
+const toVariable = (raw, label) => {
 	if (!isRecord(raw) || typeof raw["name"] !== "string" || raw["name"].trim().length === 0) return [];
-	const type = typeof raw["type"] === "string" ? raw["type"] : "";
+	const name = raw["name"];
 	const variable = {
-		name: raw["name"],
-		type
-	};
-	if (typeof raw["ref"] === "string") variable.ref = raw["ref"];
-	else if (typeof raw["value"] === "string") variable.value = raw["value"];
-	const modes = readStringMap(raw["modes"]);
+		name,
+		type: typeof raw["type"] === "string" ? raw["type"] : ""
+	};
+	const refuse = (fault, hint) => /* @__PURE__ */ new Error(`${label} file: variable "${name}" ${fault}. ${hint}`);
+	const nameFault = tokenNameFault(name);
+	if (nameFault !== void 0) throw refuse(nameFault, NEUTRAL_NAME_SHAPE);
+	if (raw["ref"] !== void 0) {
+		if (typeof raw["ref"] !== "string") throw refuse(`has ${jsonKind(raw["ref"])} ref`, NEUTRAL_VALUE_OR_REF);
+		if (raw["ref"].trim().length === 0) throw refuse("has an empty ref", NEUTRAL_VALUE_OR_REF);
+		variable.ref = raw["ref"];
+	} else if (typeof raw["value"] === "string") variable.value = raw["value"];
+	else if (raw["value"] !== void 0) throw refuse(`has ${jsonKind(raw["value"])} value`, NEUTRAL_STRING_VALUES);
+	else throw refuse("has neither a value nor a ref", NEUTRAL_VALUE_OR_REF);
+	const modes = readModes(raw["modes"], name, label);
 	if (modes) variable.modes = modes;
 	return [variable];
 };
-const readStringMap = (raw) => {
-	if (!isRecord(raw)) return void 0;
+const readModes = (raw, name, label) => {
+	if (raw === void 0) return void 0;
+	if (!isRecord(raw)) throw new Error(`${label} file: variable "${name}" has ${jsonKind(raw)} "modes". ${NEUTRAL_MODES_OBJECT}`);
 	const out = {};
-	for (const [key, value] of Object.entries(raw)) if (key.trim().length > 0 && typeof value === "string") out[key] = value;
+	for (const [mode, value] of Object.entries(raw)) {
+		if (mode.trim().length === 0 || mode === "__proto__") throw new Error(`${label} file: variable "${name}" has a mode named ${JSON.stringify(mode)}, which no mode can be named. ${NEUTRAL_MODES_OBJECT}`);
+		if (typeof value !== "string") throw new Error(`${label} file: variable "${name}" has ${jsonKind(value)} value in mode "${mode}". ${NEUTRAL_STRING_VALUES}`);
+		out[mode] = value;
+	}
 	return Object.keys(out).length > 0 ? out : void 0;
 };
+const tokenNameFault = (name) => {
+	const segments = name.split(".");
+	if (segments.some((segment) => segment.trim().length === 0)) return "has an empty segment in its name";
+	if (segments.some((segment) => segment.startsWith("$"))) return "has a segment starting with \"$\", which DTCG keeps for its own keys";
+	if (segments.includes("__proto__")) return "has a \"__proto__\" segment, which no token can be named";
+	if (segments.length === 1 && TIERS.has(name)) return `names only the tier "${name}", with no token under it`;
+};
+const TIERS = new Set(TOKEN_TIERS);
+const jsonKind = (value) => {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	const kind = typeof value;
+	return kind === "object" ? "an object" : `a ${kind}`;
+};
 const readJsonObject = (raw) => {
 	let parsed;
 	try {
@@ -2014,6 +2477,7 @@ const readJsonObject = (raw) => {
 		throw new Error(`${DESIGN_TOKENS_FILE} is not valid JSON (${error instanceof Error ? error.message : String(error)}) — run \`design-tokens validate\` first.`, { cause: error });
 	}
 	if (!isRecord(parsed)) throw new Error(`${DESIGN_TOKENS_FILE} must be a JSON object — run \`design-tokens validate\` first.`);
+	if (exceedsNestingLimit(parsed)) throw new Error(`${NESTED_TOO_DEEPLY} Run \`design-tokens validate\` first.`);
 	return parsed;
 };
 const writeJsonFile = (value) => `${JSON.stringify(value, null, 2)}\n`;
@@ -2025,17 +2489,16 @@ const runImport = async (inputs) => {
 		tokensFound: false,
 		changes: [],
 		applied: false,
+		refused: false,
 		written: [],
 		skipped: [],
-		problems: []
-	};
-	if (!await pathExists(inputs.neutralPath)) return {
-		...empty,
-		problems: [`neutral file not found: ${inputs.neutralPath}`]
+		unsynced: [],
+		problems: [],
+		warnings: []
 	};
 	let neutral;
 	try {
-		neutral = parseNeutralFile(await readFile(inputs.neutralPath, "utf8"));
+		neutral = parseNeutralFile(await readRequiredFile(inputs.neutralPath, "neutral"), "neutral");
 	} catch (error) {
 		return {
 			...empty,
@@ -2046,37 +2509,79 @@ const runImport = async (inputs) => {
 		...empty,
 		problems: [`neutral file schemaVersion ${neutral.schemaVersion} is not supported (expected 1).`]
 	};
-	const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
-	const tokensFound = await pathExists(tokenPath);
+	let tokensFound = false;
+	let raw;
 	let parsed;
 	try {
-		parsed = tokensFound ? readJsonObject(await readFile(tokenPath, "utf8")) : {};
+		raw = await readOptionalTokenFile(inputs.repoRoot);
+		tokensFound = raw !== void 0;
+		parsed = raw === void 0 ? {} : readJsonObject(raw);
 	} catch (error) {
 		return {
 			...empty,
-			tokensFound,
+			tokensFound: true,
 			problems: [asMessage$1(error)]
 		};
 	}
 	const changes = diffNeutralAgainstJson(neutral, parsed);
-	if (!inputs.apply) return {
+	if (!inputs.apply) {
+		const faults = summarizeMessages(raw === void 0 ? [] : tokenFileViolationMessages(raw));
+		return {
+			...empty,
+			tokensFound,
+			changes,
+			warnings: faults === void 0 ? [] : [`${DESIGN_TOKENS_FILE} already fails validation: ${faults} ${IMPORT_PREVIEW_INVALID_HINT} ${VALIDATE_HINT}`]
+		};
+	}
+	const unmatched = (inputs.only ?? []).filter((path) => !changes.some((change) => change.path === path));
+	if (unmatched.length > 0) return {
+		...empty,
 		tokensFound,
 		changes,
-		applied: false,
-		written: [],
-		skipped: [],
-		problems: []
+		refused: true,
+		problems: [`--only names ${unmatched.length === 1 ? "a path" : "paths"} no variable in the neutral file lands at: ${unmatched.join(", ")}. Use the tiered paths the preview prints; nothing was written.`]
 	};
-	const { merged, written, skipped } = mergeNeutralIntoJson(neutral, parsed, inputs.only);
-	await mkdir(dirname(tokenPath), { recursive: true });
-	await writeFile(tokenPath, writeJsonFile(merged));
+	const { merged, written, skipped, unsynced } = mergeNeutralIntoJson(neutral, parsed, inputs.only);
+	if (exceedsNestingLimit(merged)) return {
+		...empty,
+		tokensFound,
+		changes,
+		refused: true,
+		problems: [`not applied — with this import, ${DESIGN_TOKENS_FILE} would fail validation: ${NESTED_TOO_DEEPLY} ${IMPORT_TOO_DEEP_HINT}`]
+	};
+	const text = writeJsonFile(merged);
+	const mergedFaults = [...nonFiniteNumberFaults(merged), ...tokenFileViolationMessages(text)];
+	if (mergedFaults.length > 0) {
+		const onDisk = new Set(raw === void 0 ? [] : tokenFileViolationMessages(raw));
+		const introduced = mergedFaults.filter((fault) => !onDisk.has(fault));
+		const landings = new Set(changes.map((change) => change.path));
+		const dangling = danglingAliasTargets(merged, written);
+		const leftBehind = dangling.filter((target) => landings.has(target));
+		const notCarried = dangling.filter((target) => !landings.has(target));
+		const hint = notCarried.length === 0 ? IMPORT_INVALID_HINT : `${leftBehind.length > 0 ? `Add ${leftBehind.join(", ")} to the \`--only\` slice. ` : ""}The neutral file carries no variable that lands at ${notCarried.join(", ")}, so no \`--only\` slice can supply ${notCarried.length === 1 ? "it" : "them"}: ${IMPORT_NOT_CARRIED_HINT}`;
+		return {
+			...empty,
+			tokensFound,
+			changes,
+			refused: true,
+			problems: [introduced.length > 0 ? `not applied — with this import, ${DESIGN_TOKENS_FILE} would fail validation: ${summarizeMessages(introduced)} ${hint}` : `not applied — ${DESIGN_TOKENS_FILE} already fails validation and this import does not repair it: ${summarizeMessages(mergedFaults)} ${VALIDATE_HINT}`]
+		};
+	}
+	if (written.length > 0) {
+		const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
+		await mkdir(dirname(tokenPath), { recursive: true });
+		await writeFile(tokenPath, text);
+	}
 	return {
 		tokensFound,
 		changes,
 		applied: true,
+		refused: false,
 		written,
 		skipped,
-		problems: []
+		unsynced,
+		problems: [],
+		warnings: []
 	};
 };
 const asMessage$1 = (error) => error instanceof Error ? error.message : String(error);
@@ -2130,15 +2635,22 @@ const runExport = async (inputs) => {
 	const empty = {
 		tokensFound: false,
 		plan: [],
+		unprojected: [],
 		hash: "",
 		recorded: false,
 		problems: []
 	};
-	const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
-	if (!await pathExists(tokenPath)) return empty;
 	let parsed;
 	try {
-		parsed = readJsonObject(await readFile(tokenPath, "utf8"));
+		const raw = await readOptionalTokenFile(inputs.repoRoot);
+		if (raw === void 0) return empty;
+		parsed = readJsonObject(raw);
+		const invalid = summarizeTokenFileViolations(raw);
+		if (invalid !== void 0) return {
+			...empty,
+			tokensFound: true,
+			problems: [`${DESIGN_TOKENS_FILE} fails validation: ${invalid} ${VALIDATE_HINT}`]
+		};
 	} catch (error) {
 		return {
 			...empty,
@@ -2154,35 +2666,46 @@ const runExport = async (inputs) => {
 	};
 	const hash = projectionHash(parsed);
 	let toolState;
-	if (inputs.toolStatePath !== void 0) {
-		if (!await pathExists(inputs.toolStatePath)) return {
+	if (inputs.toolStatePath !== void 0) try {
+		toolState = parseNeutralFile(await readRequiredFile(inputs.toolStatePath, "tool-state"), "tool-state");
+	} catch (error) {
+		return {
 			...empty,
 			tokensFound: true,
 			hash,
-			problems: [`tool-state file not found: ${inputs.toolStatePath}`]
+			problems: [asMessage(error)]
+		};
+	}
+	const plan = upsertPlan(parsed, toolState);
+	const unprojected = unsyncedTokens(parsed);
+	if (inputs.outPath !== void 0) {
+		const projection = dtcgToNeutral(parsed);
+		projection.provider = binding.provider;
+		if (await sameEntry(inputs.outPath, join(inputs.repoRoot, "docs/design-tokens.json"))) return {
+			...empty,
+			tokensFound: true,
+			hash,
+			problems: [`Cannot write the projection to ${inputs.outPath}: it is ${DESIGN_TOKENS_FILE} itself, which the projection would replace. Name another path.`]
 		};
 		try {
-			toolState = parseNeutralFile(await readFile(inputs.toolStatePath, "utf8"));
+			await writeRegularFile(inputs.outPath, writeNeutralFile(projection));
 		} catch (error) {
 			return {
 				...empty,
 				tokensFound: true,
 				hash,
-				problems: [asMessage(error)]
+				problems: [`Cannot write the projection to ${inputs.outPath}: ${asMessage(error)}`]
 			};
 		}
 	}
-	const plan = upsertPlan(parsed, toolState);
-	if (inputs.outPath !== void 0) {
-		const projection = dtcgToNeutral(parsed);
-		projection.provider = binding.provider;
-		await writeFile(inputs.outPath, writeNeutralFile(projection));
-	}
 	if (inputs.record) {
-		await writeFile(tokenPath, writeJsonFile(stampBaseline(parsed, hash)));
+		const stamped = writeJsonFile(stampBaseline(parsed, hash));
+		const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
+		await writeFile(tokenPath, stamped);
 		return {
 			tokensFound: true,
 			plan,
+			unprojected,
 			hash,
 			recorded: true,
 			problems: []
@@ -2191,13 +2714,14 @@ const runExport = async (inputs) => {
 	return {
 		tokensFound: true,
 		plan,
+		unprojected,
 		hash,
 		recorded: false,
 		problems: []
 	};
 };
 const stampBaseline = (parsed, hash) => {
-	const clone = structuredClone(parsed);
+	const clone = { ...parsed };
 	const extensions = isRecord(clone["$extensions"]) ? { ...clone["$extensions"] } : {};
 	const binding = isRecord(extensions["com.lemony.design-tool"]) ? { ...extensions[DESIGN_TOOL_EXTENSION] } : {};
 	binding["lastProjected"] = hash;
@@ -2205,6 +2729,10 @@ const stampBaseline = (parsed, hash) => {
 	clone["$extensions"] = extensions;
 	return clone;
 };
+const sameEntry = async (a, b) => {
+	const [left, right] = await Promise.all([a, b].map((path) => stat(path).catch(() => void 0)));
+	return left !== void 0 && right !== void 0 && left.dev === right.dev && left.ino === right.ino;
+};
 const asMessage = (error) => error instanceof Error ? error.message : String(error);
 //#endregion
 //#region src/review-ledger/review-ledger.constant.ts
@@ -2710,19 +3238,7 @@ const checkMutantsFloor = (ledger, owedFiles, anchor, problems) => {
 		});
 	}
 };
-const collectDeclaredGates = async (repoRoot) => {
-	if (!await configEntryExists(join(repoRoot, "harness.config.yml"))) return;
-	return (await readHarnessConfig(repoRoot)).gates;
-};
-const configEntryExists = async (path) => {
-	try {
-		await lstat(path);
-		return true;
-	} catch (error) {
-		if (error.code === "ENOENT") return false;
-		throw error;
-	}
-};
+const collectDeclaredGates = async (repoRoot) => (await readOptionalHarnessConfig(repoRoot))?.gates;
 const owedGates = (declared) => ({
 	basis: declared === void 0 ? "undeclared" : "config",
 	required: [...new Set(declared ?? [])],
@@ -3549,7 +4065,7 @@ const inspectDevDependency = async (repoRoot) => {
 	const pkgPath = join(repoRoot, "package.json");
 	if (!await pathExists(pkgPath)) return "no-package-json";
 	try {
-		const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+		const pkg = JSON.parse(await readRegularFile(pkgPath));
 		return Object.hasOwn(pkg.dependencies ?? {}, "@lemoncode/lemony") || Object.hasOwn(pkg.devDependencies ?? {}, "@lemoncode/lemony") ? "declared" : "missing";
 	} catch {
 		return "no-package-json";
@@ -3820,14 +4336,27 @@ const checkHooks = async (repoRoot) => {
 	const settingsPath = join(repoRoot, SETTINGS_FILE);
 	let raw;
 	try {
-		raw = await readFile(settingsPath, "utf8");
-	} catch {
-		return {
+		raw = await readRegularFile(settingsPath);
+	} catch (error) {
+		const code = error.code;
+		if (code === "ENOENT" && await lstat(settingsPath).then(() => true, () => false)) return {
+			name,
+			status: "fail",
+			detail: ".claude/settings.json is a symlink whose target is missing.",
+			remediation: "Remove the symlink, then run `lemony repair`."
+		};
+		if (code === "ENOENT") return {
 			name,
 			status: "fail",
 			detail: ".claude/settings.json not found.",
 			remediation: "Run `lemony repair`."
 		};
+		return {
+			name,
+			status: "fail",
+			detail: `Cannot read .claude/settings.json: ${code === void 0 ? error.message : `${code}.`}`,
+			remediation: "Replace it with a readable file (or remove it), then run `lemony repair`."
+		};
 	}
 	let commands;
 	try {
@@ -3984,29 +4513,46 @@ const checkCapabilities = async (deps, config) => {
 };
 const checkDesignToolDrift = async (deps) => {
 	const name = "design-tool-drift";
-	const tokenPath = join(deps.repoRoot, DESIGN_TOKENS_FILE);
-	if (!await pathExists(tokenPath)) return {
+	let raw;
+	try {
+		raw = await readOptionalTokenFile(deps.repoRoot);
+	} catch (error) {
+		return {
+			name,
+			status: "fail",
+			detail: error.message,
+			remediation: "Run `lemony design-tokens validate` to find the problem."
+		};
+	}
+	if (raw === void 0) return {
 		name,
 		status: "info",
 		detail: `No ${DESIGN_TOKENS_FILE} — token sync not in use.`
 	};
 	let parsed;
 	try {
-		parsed = JSON.parse(await readFile(tokenPath, "utf8"));
+		parsed = JSON.parse(raw);
 	} catch (error) {
 		return {
 			name,
-			status: "warn",
-			detail: `Could not read ${DESIGN_TOKENS_FILE}: ${error.message}`,
+			status: "fail",
+			detail: `${DESIGN_TOKENS_FILE} is not valid JSON: ${error.message}`,
 			remediation: "Run `lemony design-tokens validate` to find the problem."
 		};
 	}
 	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
 		name,
-		status: "warn",
+		status: "fail",
 		detail: `${DESIGN_TOKENS_FILE} is not a JSON object.`,
 		remediation: "Run `lemony design-tokens validate` to find the problem."
 	};
+	const invalid = summarizeTokenFileViolations(raw);
+	if (invalid !== void 0) return {
+		name,
+		status: "fail",
+		detail: `${DESIGN_TOKENS_FILE} fails validation: ${invalid}`,
+		remediation: "Run `lemony design-tokens validate` to find the problem."
+	};
 	const report = driftReport(parsed);
 	switch (report.state) {
 		case "n/a": return {
@@ -4144,11 +4690,12 @@ const runStatus = async (deps) => {
 	};
 };
 const readDriftState = async (repoRoot) => {
-	const tokenPath = join(repoRoot, DESIGN_TOKENS_FILE);
-	if (!await pathExists(tokenPath)) return null;
 	try {
-		const parsed = JSON.parse(await readFile(tokenPath, "utf8"));
+		const raw = await readOptionalTokenFile(repoRoot);
+		if (raw === void 0) return null;
+		const parsed = JSON.parse(raw);
 		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+		if (summarizeTokenFileViolations(raw) !== void 0) return null;
 		return driftReport(parsed).state;
 	} catch {
 		return null;
@@ -4163,7 +4710,7 @@ const readPointer = async (repoRoot, readGitUserEmail) => {
 	const pointerPath = join(repoRoot, STATE_DIR, `current-${slug}.md`);
 	let raw;
 	try {
-		raw = await readFile(pointerPath, "utf8");
+		raw = await readRegularFile(pointerPath);
 	} catch {
 		return empty;
 	}
@@ -4238,7 +4785,7 @@ const COMMANDS = [
 	},
 	{
 		name: "design-tokens",
-		summary: "Validate the 3-tier design-token file (and gate UI source against hardcoded values), check WCAG contrast of token pairs, or sync tokens with a design tool (consume-if-exists; never created).",
+		summary: "Validate the 3-tier design-token file (and gate UI source against hardcoded values), check WCAG contrast of token pairs, or sync tokens with a design tool (consume-if-exists: the gates never create the file; `import --apply` bootstraps it).",
 		usage: "lemony design-tokens <validate [--scan=<dir>] | contrast | import --from=<file> [--apply] [--only=<paths>] | export [--tool-state=<file>] [--out=<file>] [--record]>"
 	},
 	{
@@ -4808,54 +5355,6 @@ const materializeVendorFiles = async (ctx) => {
 	];
 };
 //#endregion
-//#region src/install/gitignore.ts
-const GITIGNORE_BEGIN = "# BEGIN lemony";
-const GITIGNORE_END = "# END lemony";
-const GITIGNORE_BLOCK = [
-	GITIGNORE_BEGIN,
-	".claude/state/current-*.md",
-	".claude/state/.ptr.*",
-	".claude/state/sessions/",
-	".claude/state/events.jsonl",
-	".claude/state/telemetry-cursor.json",
-	".claude/state/telemetry-consent.json",
-	".claude/state/.telemetry-notice-shown",
-	".claude/state/telemetry-rejected.jsonl",
-	".claude/.harness/snapshots/",
-	GITIGNORE_END
-].join("\n");
-const appendGitignoreBlock = async (repoRoot) => {
-	const gitignorePath = join(repoRoot, ".gitignore");
-	const current = await pathExists(gitignorePath) ? await readFile(gitignorePath, "utf8") : "";
-	const beginIdx = current.indexOf(GITIGNORE_BEGIN);
-	const endIdx = current.indexOf(GITIGNORE_END, beginIdx);
-	if (beginIdx !== -1 && endIdx !== -1) {
-		const next = current.slice(0, beginIdx) + GITIGNORE_BLOCK + current.slice(endIdx + 12);
-		if (next === current) return null;
-		await writeFile(gitignorePath, next);
-		return ".gitignore";
-	}
-	const prefix = current.length === 0 ? "" : current.endsWith("\n") ? "\n" : "\n\n";
-	await writeFile(gitignorePath, `${current}${prefix}${GITIGNORE_BLOCK}\n`);
-	return ".gitignore";
-};
-const removeGitignoreBlock = async (repoRoot) => {
-	const relPath = ".gitignore";
-	const gitignorePath = join(repoRoot, relPath);
-	if (!await pathExists(gitignorePath)) return null;
-	const lines = (await readFile(gitignorePath, "utf8")).split("\n");
-	const startLine = lines.findIndex((line) => line.trim() === GITIGNORE_BEGIN);
-	const endLine = startLine === -1 ? -1 : lines.findIndex((line, index) => index > startLine && line.trim() === GITIGNORE_END);
-	if (startLine === -1 || endLine === -1) return null;
-	const result = [...lines.slice(0, startLine), ...lines.slice(endLine + 1)].join("\n").replace(/\n+$/, "\n");
-	if (result.trim() === "") {
-		await rm(gitignorePath, { force: true });
-		return relPath;
-	}
-	await writeFile(gitignorePath, result);
-	return relPath;
-};
-//#endregion
 //#region src/install/merge-settings.ts
 const mergeSettingsHooks = async (templatePath, destPath) => {
 	const templateRaw = await readFile(templatePath, "utf8");
@@ -4863,7 +5362,7 @@ const mergeSettingsHooks = async (templatePath, destPath) => {
 	if (template.hooks === void 0) throw new Error(`settings template at ${templatePath} has no "hooks" key — vendor authority is the hooks block.`);
 	let existing = {};
 	if (await pathExists(destPath)) {
-		const existingRaw = await readFile(destPath, "utf8");
+		const existingRaw = await readSettings(destPath, mergeContext(destPath));
 		if (existingRaw.trim().length > 0) try {
 			existing = JSON.parse(existingRaw);
 		} catch (cause) {
@@ -4881,7 +5380,7 @@ const mergeSettingsHooks = async (templatePath, destPath) => {
 };
 const removeSettingsHooks = async (settingsPath) => {
 	if (!await pathExists(settingsPath)) return "absent";
-	const raw = await readFile(settingsPath, "utf8");
+	const raw = await readSettings(settingsPath, removeContext(settingsPath));
 	if (raw.trim().length === 0) return "absent";
 	let parsed;
 	try {
@@ -4898,6 +5397,24 @@ const removeSettingsHooks = async (settingsPath) => {
 	await writeFile(settingsPath, `${JSON.stringify(rest, null, 2)}\n`);
 	return "stripped";
 };
+const mergeContext = (path) => `Cannot merge the harness hooks into ${path}`;
+const removeContext = (path) => `Cannot remove the harness hooks from ${path}`;
+const assertSettingsNotSpecial = async (path, action) => {
+	const target = await stat(path).catch(() => void 0);
+	if (target === void 0 || target.isFile()) return;
+	const context = action === "merge" ? mergeContext(path) : removeContext(path);
+	const reason = target.isDirectory() ? "the entry is a directory." : SPECIAL_FILE_REFUSAL;
+	throw new Error(`${context}: ${reason} ${REMOVE_IT}`);
+};
+const REMOVE_IT = "Remove it before re-running.";
+const readSettings = async (path, context) => {
+	try {
+		return await readRegularFile(path);
+	} catch (error) {
+		if (error.code !== void 0) throw error;
+		throw new Error(`${context}: ${error.message} ${REMOVE_IT}`, { cause: error });
+	}
+};
 const collectCommands = (hooks) => {
 	const result = /* @__PURE__ */ new Set();
 	if (!hooks || typeof hooks !== "object") return result;
@@ -4922,6 +5439,54 @@ const diffLostCommands = (existingHooks, templateHooks) => {
 	return lost.toSorted();
 };
 //#endregion
+//#region src/install/gitignore.ts
+const GITIGNORE_BEGIN = "# BEGIN lemony";
+const GITIGNORE_END = "# END lemony";
+const GITIGNORE_BLOCK = [
+	GITIGNORE_BEGIN,
+	".claude/state/current-*.md",
+	".claude/state/.ptr.*",
+	".claude/state/sessions/",
+	".claude/state/events.jsonl",
+	".claude/state/telemetry-cursor.json",
+	".claude/state/telemetry-consent.json",
+	".claude/state/.telemetry-notice-shown",
+	".claude/state/telemetry-rejected.jsonl",
+	".claude/.harness/snapshots/",
+	GITIGNORE_END
+].join("\n");
+const appendGitignoreBlock = async (repoRoot) => {
+	const gitignorePath = join(repoRoot, ".gitignore");
+	const current = await pathExists(gitignorePath) ? await readFile(gitignorePath, "utf8") : "";
+	const beginIdx = current.indexOf(GITIGNORE_BEGIN);
+	const endIdx = current.indexOf(GITIGNORE_END, beginIdx);
+	if (beginIdx !== -1 && endIdx !== -1) {
+		const next = current.slice(0, beginIdx) + GITIGNORE_BLOCK + current.slice(endIdx + 12);
+		if (next === current) return null;
+		await writeFile(gitignorePath, next);
+		return ".gitignore";
+	}
+	const prefix = current.length === 0 ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+	await writeFile(gitignorePath, `${current}${prefix}${GITIGNORE_BLOCK}\n`);
+	return ".gitignore";
+};
+const removeGitignoreBlock = async (repoRoot) => {
+	const relPath = ".gitignore";
+	const gitignorePath = join(repoRoot, relPath);
+	if (!await pathExists(gitignorePath)) return null;
+	const lines = (await readFile(gitignorePath, "utf8")).split("\n");
+	const startLine = lines.findIndex((line) => line.trim() === GITIGNORE_BEGIN);
+	const endLine = startLine === -1 ? -1 : lines.findIndex((line, index) => index > startLine && line.trim() === GITIGNORE_END);
+	if (startLine === -1 || endLine === -1) return null;
+	const result = [...lines.slice(0, startLine), ...lines.slice(endLine + 1)].join("\n").replace(/\n+$/, "\n");
+	if (result.trim() === "") {
+		await rm(gitignorePath, { force: true });
+		return relPath;
+	}
+	await writeFile(gitignorePath, result);
+	return relPath;
+};
+//#endregion
 //#region src/install/resync.ts
 const resyncSpecialCased = async (repoRoot, templateRoot) => {
 	const { lostCommands } = await mergeSettingsHooks(join(templateRoot, CLAUDE_DIR, "settings.json.tpl"), join(repoRoot, SETTINGS_FILE));
@@ -4978,6 +5543,7 @@ const runInstall = async (options) => {
 		...COMMITTED_STATE_DIRS.map((dir) => join(STATE_DIR, dir, ".gitkeep")),
 		HARNESS_CONFIG_FILENAME
 	]);
+	await assertSettingsNotSpecial(join(repoRoot, SETTINGS_FILE), "merge");
 	const readClient = async (relPath) => {
 		const filePath = join(repoRoot, relPath);
 		if (!await pathExists(filePath)) return null;
@@ -5126,6 +5692,7 @@ const runReconcile = async (inputs) => {
 		SETTINGS_FILE,
 		".gitignore"
 	]);
+	await assertSettingsNotSpecial(join(repoRoot, SETTINGS_FILE), "merge");
 	const actions = await runEngine({
 		baseline,
 		vendorNew,
@@ -5282,6 +5849,7 @@ const runUninstall = async (options) => {
 		HARNESS_DIR,
 		HARNESS_CONFIG_FILENAME
 	]);
+	await assertSettingsNotSpecial(join(repoRoot, SETTINGS_FILE), "remove");
 	await Promise.all(removedFiles.map((relPath) => rm(join(repoRoot, relPath), { force: true })));
 	await pruneEmptyDirs(repoRoot, removedFiles);
 	const settings = await removeSettingsHooks(join(repoRoot, SETTINGS_FILE));
@@ -5493,8 +6061,14 @@ const PACKAGE_JSON_PATH = join(PACKAGE_ROOT, "package.json");
 const execFileAsync = promisify(execFile);
 const parseFlag = (args, name) => {
 	const prefix = `--${name}=`;
-	const value = args.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
-	return value ? value : void 0;
+	const joined = args.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
+	if (joined !== void 0) return joined ? joined : void 0;
+	const at = args.indexOf(`--${name}`);
+	const next = at === -1 ? void 0 : args[at + 1];
+	return next !== void 0 && next !== "" && !next.startsWith("--") ? next : void 0;
+};
+const rejectValuelessFlags = (verb, args, names) => {
+	for (const name of names) if (args.some((arg) => arg === `--${name}` || arg.startsWith(`--${name}=`)) && parseFlag(args, name) === void 0) throw new Error(`${verb}: --${name} was given without a value.`);
 };
 const readHarnessVersion = async () => {
 	const raw = await readFile(PACKAGE_JSON_PATH, "utf8");
@@ -5545,7 +6119,8 @@ const makeVerifierRunCommand = () => (cmd, args) => new Promise((resolveResult)
 		resolveResult({
 			code: code ?? 1,
 			stdout: Buffer.concat(out).toString("utf8"),
-			stderr: `${Buffer.concat(err).toString("utf8")}${signal ? `killed by ${signal}\n` : ""}`
+			stderr: Buffer.concat(err).toString("utf8"),
+			...signal === null ? {} : { signal }
 		});
 	});
 });
@@ -5938,18 +6513,18 @@ const designTokens = async (args) => {
 	throw new Error(`Usage: lemony design-tokens <validate [--scan=<dir>] | contrast | import --from=<file> [--apply] [--only=<paths>] | export [--tool-state=<file>] [--out=<file>] [--record]>. Unknown action "${action}".`);
 };
 const designTokensValidate = async (args) => {
-	const config = await readHarnessConfig(cwd()).catch(() => void 0);
+	const config = await readOptionalHarnessConfig(cwd());
 	const result = await runValidate({
 		repoRoot: cwd(),
 		scanDir: parseFlag(args, "scan"),
 		extraExtensions: config?.design_tokens.scan_extensions
 	});
 	if (!result.tokensFound) {
-		console.log(`No docs/design-tokens.json — design-tokens validate skipped (consume-if-exists; the harness never creates it).`);
+		console.log(`No docs/design-tokens.json — design-tokens validate skipped (consume-if-exists; the gates never create it).`);
 		return;
 	}
 	if (result.ok) {
-		console.log(`design-tokens valid: ${result.tokenCount} token(s), ${result.filesScanned} file(s) scanned, no hardcoded values.`);
+		console.log(result.filesScanned === 0 ? `design-tokens valid: ${result.tokenCount} token(s), but 0 file(s) scanned — no readable source with a scanned extension was found, so nothing was checked for hardcoded values.` : `design-tokens valid: ${result.tokenCount} token(s), ${result.filesScanned} file(s) scanned, no hardcoded values.`);
 		return;
 	}
 	console.error(`design-tokens validate found ${result.violations.length} violation(s):`);
@@ -5959,8 +6534,22 @@ const designTokensValidate = async (args) => {
 	}
 	exit(1);
 };
+const verifierEnding = (outcome) => outcome.signal === void 0 ? `exited ${outcome.code}` : `was killed by ${outcome.signal}`;
+const quotedCommand = (command) => {
+	const lines = command.trimEnd().split("\n");
+	return lines.length > 1 ? `\`${lines[0]} …\`` : `\`${command}\``;
+};
+const drained = (stream) => new Promise((resolve) => {
+	stream.once("error", () => resolve());
+	stream.write("", () => resolve());
+});
+const contrastFailedLine = (pairCheck, verify) => {
+	if (verify === void 0) return `design-tokens contrast failed: ${pairCheck}.`;
+	const outcome = verify.code === 0 && verify.signal === void 0 ? "passed (exited 0)" : verifierEnding(verify);
+	return `design-tokens contrast failed: ${pairCheck}; design_tokens.verify ${quotedCommand(verify.command)} ${outcome}.`;
+};
 const designTokensContrast = async () => {
-	const verify = (await pathExists(join(cwd(), "harness.config.yml")) ? await readHarnessConfig(cwd()) : void 0)?.design_tokens.verify;
+	const verify = (await readOptionalHarnessConfig(cwd()))?.design_tokens.verify;
 	const result = await runContrast({
 		repoRoot: cwd(),
 		...verify === void 0 ? {} : { verify: {
@@ -5968,10 +6557,6 @@ const designTokensContrast = async () => {
 			run: makeVerifierRunCommand()
 		} }
 	});
-	if (!result.tokensFound) {
-		console.log(`No docs/design-tokens.json — design-tokens contrast skipped (consume-if-exists; the harness never creates it).`);
-		return;
-	}
 	const failures = result.pairs.filter((pair) => !pair.passes);
 	const forwardVerifier = () => {
 		if (result.verify === void 0) return;
@@ -5979,13 +6564,28 @@ const designTokensContrast = async () => {
 		if (out.length > 0) stdout.write(out.endsWith("\n") ? out : `${out}\n`);
 		if (err.length > 0) stderr.write(err.endsWith("\n") ? err : `${err}\n`);
 	};
+	const failedVerifier = result.verify !== void 0 && result.verify.code !== 0 ? result.verify : void 0;
+	if (!result.tokensFound) {
+		console.log(result.verify === void 0 ? `No docs/design-tokens.json — design-tokens contrast skipped (consume-if-exists; the gates never create it).` : `No docs/design-tokens.json — design-tokens contrast pair check skipped (consume-if-exists; the gates never create it); running the declared design_tokens.verify.`);
+		if (result.verify === void 0) return;
+		if (failedVerifier) console.error(`design-tokens contrast found 1 issue(s):`);
+		forwardVerifier();
+		await Promise.all([drained(stdout), drained(stderr)]);
+		if (failedVerifier) {
+			console.error(`  design_tokens.verify ${quotedCommand(failedVerifier.command)} ${verifierEnding(failedVerifier)}.`);
+			console.error(contrastFailedLine("pair check skipped (no docs/design-tokens.json)", failedVerifier));
+			process.exitCode = 1;
+			return;
+		}
+		console.log(`design-tokens verify OK: ${quotedCommand(result.verify.command)} exited 0.`);
+		return;
+	}
 	if (result.ok) {
 		console.log(result.pairsChecked === 0 ? `design-tokens contrast: no foreground/background pairs found (use the on-* convention or $extensions["com.lemony.contrast"]).` : `design-tokens contrast OK: ${result.pairsChecked} pair(s) meet their WCAG floor.`);
 		forwardVerifier();
-		if (result.verify !== void 0) console.log(`design-tokens verify OK: \`${result.verify.command}\` exited 0.`);
+		if (result.verify !== void 0) console.log(`design-tokens verify OK: ${quotedCommand(result.verify.command)} exited 0.`);
 		return;
 	}
-	const failedVerifier = result.verify !== void 0 && result.verify.code !== 0 ? result.verify : void 0;
 	console.error(`design-tokens contrast found ${failures.length + result.problems.length + (failedVerifier ? 1 : 0)} issue(s):`);
 	for (const pair of failures) {
 		const over = pair.over === void 0 ? "" : ` over ${pair.over}`;
@@ -5993,13 +6593,18 @@ const designTokensContrast = async () => {
 	}
 	for (const problem of result.problems) console.error(`  ${problem}`);
 	forwardVerifier();
-	if (failedVerifier) console.error(`  design_tokens.verify \`${failedVerifier.command}\` exited ${failedVerifier.code}.`);
+	await Promise.all([drained(stdout), drained(stderr)]);
+	if (failedVerifier) console.error(`  design_tokens.verify ${quotedCommand(failedVerifier.command)} ${verifierEnding(failedVerifier)}.`);
+	const pairIssues = failures.length + result.problems.length;
+	console.error(contrastFailedLine(pairIssues > 0 ? result.pairsChecked === 0 ? `pair check measured no pair (${pairIssues} issue(s) above)` : `pair check found ${pairIssues} issue(s)` : result.pairsChecked === 0 ? "pair check found no pairs" : "pair check passed", result.verify));
 	process.exitCode = 1;
 };
 const designTokensImport = async (args) => {
 	const from = parseFlag(args, "from");
 	if (from === void 0) throw new Error("Usage: lemony design-tokens import --from=<neutral-file> [--apply] [--only=<dotted,paths>]");
+	rejectValuelessFlags("design-tokens import", args, ["only"]);
 	const only = parseFlag(args, "only")?.split(",").map((path) => path.trim()).filter((path) => path.length > 0);
+	if (only?.length === 0) throw new Error("design-tokens import: --only names no path.");
 	const result = await runImport({
 		repoRoot: cwd(),
 		neutralPath: resolve(cwd(), from),
@@ -6007,26 +6612,43 @@ const designTokensImport = async (args) => {
 		only
 	});
 	if (result.problems.length > 0) {
-		console.error("design-tokens import could not run:");
+		console.error(result.refused ? "design-tokens import --apply refused:" : "design-tokens import could not run:");
 		for (const problem of result.problems) console.error(`  ${problem}`);
-		exit(1);
+		if (result.changes.length > 0) printImportPreview(result);
+		process.exitCode = 1;
+		return;
 	}
 	if (result.applied) {
 		console.log(`design-tokens import applied: wrote ${result.written.length} token(s) to ${DESIGN_TOKENS_FILE}.`);
 		if (result.skipped.length > 0) console.log(`  skipped ${result.skipped.length} path(s) that would clobber an existing group or token — resolve by hand: ${result.skipped.join(", ")}`);
+		if (result.unsynced.length > 0) console.log(`  not applied: ${result.unsynced.length} token(s) outside the design-tool sync, which one tool value cannot replace: ${result.unsynced.join(", ")}`);
 		return;
 	}
+	const landing = printImportPreview(result);
+	for (const warning of result.warnings) console.error(`  Warning: ${warning}`);
+	if (landing > 0) console.log(`Curate the slice, then: lemony design-tokens import --from=${from} --apply --only=<paths>`);
+};
+const printImportPreview = (result) => {
 	const landing = result.changes.filter((change) => change.kind !== "unchanged");
 	const news = landing.filter((change) => change.kind === "new").length;
 	const changed = landing.length - news;
 	console.log(`design-tokens import preview: ${news} new, ${changed} changed, ${result.changes.length - landing.length} unchanged.`);
 	for (const change of landing) {
-		const detail = change.kind === "changed" ? `${change.before} → ${change.after}` : change.after;
+		const detail = change.kind === "changed" ? changedDetail(change) : change.after;
 		console.log(`  [${change.kind}] ${change.path} (${change.tier}): ${detail}`);
 	}
-	if (landing.length > 0) console.log(`Curate the slice, then: lemony design-tokens import --from=${from} --apply --only=<paths>`);
+	return landing.length;
+};
+const changedDetail = (change) => {
+	const parts = [];
+	if (change.before !== change.after) parts.push(`${shown(change.before)} → ${shown(change.after)}`);
+	if (change.typeChange) parts.push(`$type ${shown(change.typeChange.before)} → ${shown(change.typeChange.after)}`);
+	for (const mode of change.modeChanges ?? []) parts.push(`${mode.mode}: ${shown(mode.before)} → ${shown(mode.after)}`);
+	return parts.join("; ");
 };
+const shown = (value) => value === void 0 || value === "" ? "(none)" : value;
 const designTokensExport = async (args) => {
+	rejectValuelessFlags("design-tokens export", args, ["tool-state", "out"]);
 	const toolState = parseFlag(args, "tool-state");
 	const out = parseFlag(args, "out");
 	if (out !== void 0 && args.includes("--record")) {
@@ -6040,7 +6662,7 @@ const designTokensExport = async (args) => {
 		record: args.includes("--record")
 	});
 	if (!result.tokensFound) {
-		console.log(`No ${DESIGN_TOKENS_FILE} — design-tokens export skipped (consume-if-exists; the harness never creates it).`);
+		console.log(`No ${DESIGN_TOKENS_FILE} — design-tokens export skipped (consume-if-exists; export never creates it).`);
 		return;
 	}
 	if (result.problems.length > 0) {
@@ -6055,6 +6677,7 @@ const designTokensExport = async (args) => {
 	const creates = result.plan.filter((entry) => entry.kind === "create").length;
 	const updates = result.plan.filter((entry) => entry.kind === "update").length;
 	console.log(`design-tokens export plan: ${creates} to create, ${updates} to update (tool-only variables are never deleted).`);
+	if (result.unprojected.length > 0) console.log(`  not projected: ${result.unprojected.length} token(s) a design tool variable cannot hold: ${result.unprojected.map(({ path, reason }) => `${path} (${reason})`).join(", ")}`);
 	if (out !== void 0) console.log(`  projection written to ${out}`);
 };
 const REVIEW_LEDGER_USAGE = "Usage: lemony review-ledger validate --task-id=<id> --anchor=<oid> (--step=<N> | --full-pass).";