onsystem 0.9.1 → 0.10.1

package/README.md

@@ -69,7 +69,7 @@ npx -y onsystem check .   # the same check the agent and CI run
 npx -y onsystem init      # write the config, and offer a baseline
 ```
 
-At a [monorepo root](https://onsystem.vercel.app/docs/configuration#monorepo-roots), `inspect` lists every app and design-system package, and `check` checks each file by its own project's design system. In a [design-system package](https://onsystem.vercel.app/docs/design-system-packages), `init` sets it up for every app that depends on it, with no config in the apps: as a workspace package, or installed from npm when it publishes its component sources (`init` checks its `files` list). From a package that publishes only compiled code, installed apps get the token rules but no component, prop, variant or native-element checks.
+At a [monorepo root](https://onsystem.vercel.app/docs/configuration#monorepo-roots), `inspect` lists every app and design-system package, and `check` checks each file by its own project's design system. In a [design-system package](https://onsystem.vercel.app/docs/design-system-packages), `init` sets it up for every app that depends on it, with no config in the apps: as a workspace package, or installed from npm. Installed apps read the components from the sources the package publishes, or from its type declarations (`.d.ts`) when it publishes only compiled `dist/`, and get every rule either way (`init` checks its `files` list). From a package that publishes compiled code and no type declarations, they get the token rules but no component, prop, variant or native-element checks.
 
 In a new create-next-app, the template page's hardcoded colors already make the first `check .` fail; `init` offers to record them as a baseline, so only new findings fail. Folders installed from a shadcn registry, such as `components/ai-elements`, are someone else's code: [Code from shadcn registries](https://onsystem.vercel.app/docs/configuration#code-from-shadcn-registries) says how to check them or leave them out.
 
@@ -128,6 +128,21 @@ steps:
 
 That count is onsystem's own, and the MCP server and the hook show the agent the same errors to fix. In tasks that ask for a green status label in a design system with no success token, agents with onsystem often used `chart-*` tokens, which it counts as clean. The blind labels by an AI reviewer, 12 files per arm, are too few to confirm the count either way, and every violation they found with the hook or all three is a palette color in Dub, whose tokens 0.5.0 did not read. The [benchmark page](https://onsystem.vercel.app/benchmark) has every table, and [bench/v2](bench/v2) the method, the per-run data and every generated file.
 
+## Compatibility
+
+What `package.json` declares and CI runs:
+
+| With             | Supported                                                                                                                                                                                              |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Node.js          | Node.js 20.19 or later (`engines`). CI runs the tests on Node.js 22, 24 and 26, and the built package on 20.19                                                                                         |
+| Operating system | Linux, macOS and Windows: CI runs the tests and the pack test on each                                                                                                                                  |
+| ESLint           | ESLint 8.57, 9 and 10, for the ESLint plugin only: `eslint` is an optional peer, and the CLI, the MCP server, the hook and the Action do not need it                                                   |
+| TypeScript       | Your project's TypeScript is not used, and a JavaScript project needs none: onsystem reads `.tsx` and `.jsx` with its own TypeScript 6.0, a dependency, not a peer                                     |
+| React            | Components written for React 18 (`forwardRef`) or React 19 (`ref` as a prop), read from source or type declarations. onsystem does not depend on React                                                 |
+| Tailwind CSS     | v4 (`@theme`) and v3 (`tailwind.config`, read without running it). Without Tailwind, tokens come from CSS custom properties, DTCG files or a DESIGN.md                                                 |
+| shadcn/ui        | Both bases, Radix (`asChild`) and Base UI (`render`), on Tailwind v3 or v4, with no config                                                                                                             |
+| MCP clients      | Any client that starts a stdio server; CI connects on the 2025-11-25 and 2026-07-28 protocols. [Set up your agent](https://onsystem.vercel.app/docs/clients) has each client's config and support tier |
+
 ## Docs
 
 On the [website](https://onsystem.vercel.app/docs), and as Markdown in [docs/](docs):

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { $ as LEGACY_CONFIG_FILES, A as unrecordedRules, At as relativePath, B as statusKinds, C as countBaseline, D as pruneBaseline, Dt as SCRIPT_FILE, E as onLines, Et as unique, J as ConfigError, L as toDesignMd, M as writeBaseline, Nt as readProjectConfig, O as readBaseline, Ot as isInside, R as toDtcg, S as applyBaseline, T as goneFiles, Y as DEFAULT_DOCS, _ as formatDiagnostics, _t as detectProject, b as BASELINE_FILE, c as silentLogger, et as RULE_IDS, ft as libraryTitle, g as escapeData, gt as declaredConfig, h as uncheckedNotice, i as componentFiles, j as updateBaseline, jt as toPosix, k as rulesRun, kt as matchesGlob, l as stderrLogger, mt as PACKAGE_FIELD, o as loadDesignSystem, pt as notReadYet, q as CONFIG_FILES, rt as excludedBy, s as tokenFiles, st as rulesFor, v as NAME, w as findMoves, wt as plural, x as LEGACY_BASELINE_FILE, y as VERSION, yt as isDesignSystemName } from "./design-system-DZm2aP1z.js";
-import { a as notReadNotices, i as missingDependencies, o as explainProject, s as librariesLeftOut, t as serveStdio } from "./stdio-BJvjEnKW.js";
-import { r as loadTarget } from "./workspace-Dqu3nkYM.js";
+import { $ as DEFAULT_TOKENS, A as unrecordedRules, At as toPosix, B as statusKinds, C as countBaseline, D as pruneBaseline, Dt as matchesGlob, E as onLines, Et as isInside, Ft as unique, J as ConfigError, L as toDesignMd, Lt as readProjectConfig, M as writeBaseline, Nt as plural, O as readBaseline, R as toDtcg, S as applyBaseline, T as goneFiles, Tt as SCRIPT_FILE, Y as DEFAULT_DOCS, _ as formatDiagnostics, at as excludedBy, b as BASELINE_FILE, c as silentLogger, et as FALLBACK_TOKENS, g as escapeData, gt as PACKAGE_FIELD, h as uncheckedNotice, ht as notReadYet, i as componentFiles, j as updateBaseline, k as rulesRun, kt as relativePath, l as stderrLogger, lt as rulesFor, mt as libraryTitle, nt as RULE_IDS, o as loadDesignSystem, q as CONFIG_FILES, s as tokenFiles, tt as LEGACY_CONFIG_FILES, v as NAME, vt as declaredConfig, w as findMoves, x as LEGACY_BASELINE_FILE, xt as isDesignSystemName, y as VERSION, yt as detectProject } from "./design-system-CPH4C7-1.js";
+import { a as notReadNotices, i as missingDependencies, o as explainProject, s as librariesLeftOut, t as serveStdio } from "./stdio-BK2kMN1x.js";
+import { r as loadTarget } from "./workspace-BINqxi7p.js";
 import fs from "node:fs";
 import path from "node:path";
 import { escapePath, glob } from "tinyglobby";
@@ -26,7 +26,8 @@ const GUIDE_FILE = "ONSYSTEM.md";
 * (`"onsystem": "./onsystem.config.json"`, and in `files` when the package lists them), so
 * every app that depends on the package reads it, and writes ONSYSTEM.md, which tells those
 * apps' teams how to add the agent tools and the CI check. In an app that takes on such a
-* package's config, it writes no config of its own unless --force says to.
+* package's config, it writes no config of its own unless --force says to, and then one that
+* builds on the package's, for the app's own rules and overrides.
 *
 * In a terminal, it offers to add a short section on onsystem to the project's AGENTS.md or
 * CLAUDE.md, for coding agents.
@@ -52,20 +53,28 @@ async function init(configOptions, options, io, runCheck) {
 	const notes = [];
 	const relative = (abs) => relativePath(root, abs);
 	const inherited = options.force ? void 0 : config.designSystemPackage;
-	const replaced = options.force ? config.designSystemPackage : void 0;
+	const declaring = options.force && !configOptions.components?.length ? config.designSystemPackage : void 0;
+	const replaced = declaring && (config.inherits || !await namesOwnComponents(config, declaring)) ? declaring : void 0;
 	let found = false;
-	if (inherited) notes.push(`This project takes on the config ${inherited.name} declares in its package.json (${relativePath(io.cwd, inherited.config) || inherited.config}), so it needs none of its own; nothing was written. Pass --force to write one, which is read instead.`);
+	if (inherited) notes.push(`This project takes on the config ${inherited.name} declares in its package.json (${relativePath(io.cwd, inherited.config) || inherited.config}), so it needs none of its own; nothing was written. Pass --force to write one for its own rules and overrides, which builds on ${inherited.name}'s.`);
 	else if (configOptions.components?.length) {
 		file.components = configOptions.components;
 		if (configOptions.tokens?.length) file.tokens = configOptions.tokens;
 		if (configOptions.docs?.length) file.docs = configOptions.docs;
-	} else if (workspace) notes.push(`This is a monorepo root: ${workspace.projects.length} of ${workspace.projects.length + workspace.others.length} workspace packages have a design system (${workspace.projects.map((p) => p.dir).join(", ") || "none"}). Each keeps zero config; rules and overrides you add here apply to every project without a config of its own.`);
+	} else if (replaced) {
+		const tokens = existing ? ownTokens(existing, root, replaced) : void 0;
+		if (tokens) file.tokens = tokens;
+	} else if (workspace) notes.push(`This is a monorepo root: ${workspace.projects.length} of ${workspace.projects.length + workspace.others.length} workspace packages have a design system (${workspace.projects.map((p) => p.dir).join(", ") || "none"}). Each keeps zero config; rules and overrides you add here apply to every project without a config of its own when it is checked from this folder, over the config its design-system package declares.`);
 	else if (config.detected) {
 		notes.push(`Found the design system through ${config.detected}.`);
 		const specifiers = new Set((config.imports ?? []).map((m) => m.specifier));
 		const tokens = (await tokenFiles(config)).map(relative);
-		if (specifiers.size > 1) notes.push(`"components" is left to zero config: apps import them by ${specifiers.size} specifiers from the package's exports (${[...specifiers].slice(0, 2).join(", ")}, …), which a config cannot spell.`);
+		const fromInstalled = installedFields(config.components, tokens);
+		if (fromInstalled.length) notes.push(installedNote(fromInstalled, tokens));
+		const changed = fromInstalled.includes("tokens") && !fromInstalled.includes("components") ? await tokensWithComponents(config, tokens) : void 0;
+		if (fromInstalled.includes("components")) {} else if (specifiers.size > 1) notes.push(`"components" is left to zero config: apps import them by ${specifiers.size} specifiers from the package's exports (${[...specifiers].slice(0, 2).join(", ")}, …), which a config cannot spell.`);
 		else if (config.components.length > MAX_GLOBS) notes.push(`"components" is left to zero config: it found ${config.components.length} files through the package's exports, which it keeps following as the package changes.`);
+		else if (changed) notes.push(`"components" is left to zero config as well: a config that names them reads the tokens only from the usual stylesheets (${DEFAULT_TOKENS[0]} and the like)${changed.lost.length ? `, which leave out ${andList(changed.lost)}` : ", not the ones zero config reads"}.`);
 		else {
 			file.components = config.components;
 			found = true;
@@ -74,20 +83,20 @@ async function init(configOptions, options, io, runCheck) {
 			const docs = config.docs.filter((d) => !DEFAULT_DOCS.includes(d));
 			if (docs.length) file.docs = [...DEFAULT_DOCS, ...docs];
 		}
-		if (tokens.length) file.tokens = tokens;
+		if (tokens.length && !fromInstalled.includes("tokens")) file.tokens = tokens;
 	} else if ((await componentFiles(config)).length) {
-		const declared = replaced && config.configured;
 		const matching = [];
 		for (const glob of config.components) if ((await componentFiles({
 			...config,
 			components: [glob]
 		})).length) matching.push(glob);
-		notes.push(declared ? `Found the design system through the config ${replaced.name} declares: ${matching.join(", ")}.` : `Found the design system in the default folders: ${matching.join(", ")}.`);
+		notes.push(`Found the design system in the default folders: ${matching.join(", ")}.`);
 		file.components = matching;
 		found = true;
-		if (declared && config.importPath) file.importPath = config.importPath;
 		const tokens = (await tokenFiles(config)).map(relative);
-		if (tokens.length) file.tokens = tokens;
+		const fromInstalled = installedFields([], tokens);
+		if (fromInstalled.length) notes.push(installedNote(fromInstalled, tokens));
+		else if (tokens.length) file.tokens = tokens;
 	} else {
 		if (!ask) {
 			io.stderr(`init: zero config found no design system in ${root}. Pass --components (and --tokens) to say where it is, or run init in a terminal to answer a few questions. \`${NAME} inspect --explain\` shows what it looked at.`);
@@ -124,13 +133,7 @@ async function init(configOptions, options, io, runCheck) {
 		fs.writeFileSync(out, `${JSON.stringify(file, null, 2)}\n`);
 		written.push(CONFIG_FILE);
 	}
-	if (replaced) {
-		const own = (await loadTarget({
-			...configOptions,
-			config: void 0
-		})).config;
-		notes.push(await replacedNote(replaced, config, own, io.cwd));
-	}
+	if (replaced) notes.push(replacedNote(replaced, io.cwd, file.tokens !== void 0));
 	let registry;
 	if (designSystem && manifest && name) {
 		written.push(...declarePackage(root, manifest, name, options.force, notes));
@@ -341,7 +344,7 @@ function declarePackage(root, manifest, name, force, notes) {
 		fs.writeFileSync(manifest.file, `${JSON.stringify(json, null, manifest.indent)}${manifest.newline ? "\n" : ""}`);
 		written.push("package.json");
 	}
-	notes.push(`This is a design-system package: package.json declares its config ("${PACKAGE_FIELD}": "${value}"${files ? ", also added to \"files\"" : ""}), which every app that depends on ${name} reads when it has no config of its own.`);
+	notes.push(`This is a design-system package: package.json declares its config ("${PACKAGE_FIELD}": "${value}"${files ? ", also added to \"files\"" : ""}), which every app that depends on ${name} reads, under its own config when it has one.`);
 	const guide = path.join(root, GUIDE_FILE);
 	if (force || !fs.existsSync(guide)) {
 		fs.writeFileSync(guide, consumerGuide(name));
@@ -354,7 +357,8 @@ function declarePackage(root, manifest, name, force, notes) {
 * files its `files` list leaves out of the published package, and those outside the package
 * (`../tailwind-config/theme.css`), which an installed package's config cannot reach. Undefined
 * for a private package, or when they find every file. Without a `files` list, npm publishes
-* everything in the package.
+* everything in the package. Without any component file, those apps read the components from
+* the type declarations the package publishes, when it names some.
 */
 async function unshipped(config, json) {
 	if (json.private === true) return void 0;
@@ -374,13 +378,14 @@ async function unshipped(config, json) {
 		tokens: tokens.filter(outside)
 	};
 	const noComponents = components.length > 0 && missing.components.length + away.components.length === components.length;
+	const declarations = noComponents ? publishedDeclarations(config.root, json, files) : [];
 	const lost = (lists, one) => {
 		const c = lists.components.length;
 		const t = lists.tokens.length;
 		const kinds = andList([...c ? [count$1(c, "component file")] : [], ...t ? [count$1(t, "token file")] : []]);
-		const what = andList([...c ? ["components"] : [], ...t ? ["tokens"] : []], "or");
-		const checks = c && noComponents ? `: they get no component, prop, variant or native-element checks, and \`${NAME} check --require-design-system\` fails in them` : "";
-		return `(${kinds}). Those apps do not know the ${what} in ${one ? "it" : "them"}${checks}.`;
+		const them = one ? "it" : "them";
+		if (c && noComponents && declarations.length) return `(${kinds}). Those apps read the components from the type declarations it publishes instead (${andList(declarations)})${t ? `, and do not know the tokens in ${them}` : ""}.`;
+		return `(${kinds}). Those apps do not know the ${andList([...c ? ["components"] : [], ...t ? ["tokens"] : []], "or")} in ${them}${c && noComponents ? `: with no type declarations published either, they get no component, prop, variant or native-element checks, and \`${NAME} check --require-design-system\` fails in them` : ""}.`;
 	};
 	const notes = [];
 	const top = (f) => f.includes("/") ? `${f.slice(0, f.indexOf("/"))}/` : f;
@@ -397,36 +402,121 @@ async function unshipped(config, json) {
 	if (!notes.length) return void 0;
 	return {
 		notes,
-		next: noComponents && missing.components.length ? `gets no component checks until "files" publishes ${andList([...new Set(missing.components.map(top))])}` : `does not read ${andList([...folders, ...beyond])}`
+		next: noComponents && missing.components.length ? declarations.length ? `reads its components from the type declarations it publishes, not from ${andList([...new Set(missing.components.map(top))])}` : `gets no component checks until "files" publishes ${andList([...new Set(missing.components.map(top))])}` : `does not read ${andList([...folders, ...beyond])}`
 	};
 }
 /**
-* Said when --force writes a config in an app that took on a design-system package's: the new
-* one is read instead, and what it does not take from the package. `taken` is the config the
-* app took on, `own` the one it reads now.
+* The type declarations a package's package.json names, as apps that install it look for them:
+* `types` or `typings`, a `types` condition in its `exports`, or an `index.d.ts` beside it, each
+* that its `files` list publishes. Relative to the package.
 */
-async function replacedNote(pkg, taken, own, cwd) {
-	const lacks = async (list) => {
-		const kept = new Set((await list(own)).map((f) => path.resolve(f)));
-		return (await list(taken)).some((f) => !kept.has(path.resolve(f)));
+function publishedDeclarations(root, json, files) {
+	const named = [];
+	for (const field of ["types", "typings"]) {
+		const value = json[field];
+		if (typeof value === "string") named.push(value);
+	}
+	const conditions = (value, key) => {
+		if (typeof value === "string") {
+			if (key === "types") named.push(value);
+		} else if (Array.isArray(value)) for (const item of value) conditions(item);
+		else if (value && typeof value === "object") for (const [k, v] of Object.entries(value)) conditions(v, k);
 	};
-	const components = await lacks(componentFiles);
-	const importPath = taken.importPath !== void 0 && own.importPath === void 0;
-	const tokens = await lacks(tokenFiles);
+	conditions(json.exports);
+	if (fs.existsSync(path.join(root, "index.d.ts"))) named.push("index.d.ts");
+	return [...new Set(named.map((f) => f.replace(/^\.\//, "")))].filter((f) => !files || ships(files, f));
+}
+/**
+* Said when --force writes a config in an app on a design-system package that declares one: the
+* new config builds on the package's, which still gives it what it leaves out.
+*/
+function replacedNote(pkg, cwd, keptTokens) {
 	const declared = relativePath(cwd, pkg.config) || pkg.config;
-	const replaced = `This project took on the config ${pkg.name} declares (${declared}); with --force it has one of its own, which is read instead, so ${pkg.name}'s rules and later changes to its config no longer reach it.`;
-	if (!components && !importPath && !tokens) return replaced;
-	const effects = andList([
-		...components ? [`does not know ${pkg.name}'s components`] : [],
-		...importPath && !components ? [`does not match imports from ${pkg.name} to its components`] : [],
-		...tokens ? [`does not read ${pkg.name}'s tokens`] : []
-	]);
-	const fields = [
-		...components ? ["\"components\""] : [],
-		...importPath || components && taken.importPath !== void 0 ? ["\"importPath\""] : [],
-		...tokens ? ["\"tokens\""] : []
-	];
-	return `${replaced} It ${effects}: ${(!components || taken.configured === true) && (!tokens || taken.tokensDetected !== true) ? `copy ${andList(fields)} from ${declared} into ${CONFIG_FILE}, or ` : ""}delete ${CONFIG_FILE} to take on ${pkg.name}'s config again.`;
+	const fields = keptTokens ? "\"components\" and \"importPath\"" : "\"components\", \"importPath\" and \"tokens\"";
+	const kept = keptTokens ? " It keeps the \"tokens\" the old one listed, which name a stylesheet of this project's own." : "";
+	return `This project reads the config ${pkg.name} declares (${declared}). With --force it has one of its own, ${CONFIG_FILE}, read over that one: what it leaves out, such as ${fields}, still comes from ${pkg.name}'s config, and the rules and overrides you add to it apply over ${pkg.name}'s rules.${kept} "extends": false in it reads it alone.`;
+}
+/**
+* The `tokens` an existing JSON config lists, when one of them is outside the design-system
+* package, links resolved: an app that takes the package's components and reads its own
+* stylesheet too lists both. A list of the package's files only is left to the package's config.
+*/
+function ownTokens(file, root, pkg) {
+	let tokens;
+	try {
+		tokens = JSON.parse(fs.readFileSync(file, "utf8")).tokens;
+	} catch {
+		return;
+	}
+	if (!Array.isArray(tokens) || !tokens.every((t) => typeof t === "string")) return;
+	const real = (abs) => {
+		try {
+			return fs.realpathSync(abs);
+		} catch {
+			return abs;
+		}
+	};
+	const dir = real(pkg.dir);
+	return tokens.some((t) => !isInside(dir, real(path.resolve(root, t)))) ? tokens : void 0;
+}
+/**
+* Whether the files a config's `components` match include some outside the design-system
+* package, links resolved: a config that names only the package's (copied from its config, as
+* `node_modules/@acme/ui/src/*.tsx`), or none, has no components of its own.
+*/
+async function namesOwnComponents(config, pkg) {
+	const real = (file) => {
+		try {
+			return fs.realpathSync(file);
+		} catch {
+			return path.resolve(file);
+		}
+	};
+	const dir = real(pkg.dir);
+	return (await componentFiles(config)).some((file) => !isInside(dir, real(file)));
+}
+/** Whether a path, relative to the root, is in a package installed in `node_modules`. */
+const isInstalledPath = (file) => /(?:^|\/)node_modules\//.test(file);
+/**
+* The fields `init` leaves to zero config because what zero config found for them is in a
+* package installed in `node_modules`: `components` (their globs) and `tokens` (files).
+*/
+function installedFields(components, tokens) {
+	return [...components.some(isInstalledPath) ? ["components"] : [], ...tokens.some(isInstalledPath) ? ["tokens"] : []];
+}
+/**
+* Why `fields` are left to zero config: a path into an installed package breaks when it is
+* upgraded, since pnpm keeps each version in a folder of its own
+* (`node_modules/.pnpm/@acme+ui@1.2.0_react@19.2.0/node_modules/@acme/ui`), and a list of its
+* files misses the ones a new version adds. Zero config finds it again each time.
+*/
+function installedNote(fields, tokens) {
+	const one = fields.length === 1;
+	const what = fields.includes("tokens") && !tokens.every(isInstalledPath) ? `${fields.includes("components") ? "the components and " : ""}some of the token files come` : one ? "it comes" : "they come";
+	return `${andList(fields.map((f) => `"${f}"`))} ${one ? "is" : "are"} left to zero config: ${what} from a package installed in node_modules, which zero config finds again after each upgrade, while a path written here would break once the package's folder or files change (pnpm keeps each version in a folder of its own in node_modules/.pnpm).`;
+}
+/**
+* What changes when a config names components and leaves `tokens` (relative to the root, as
+* zero config finds them) to zero config: such a config turns detection off, so the stylesheets
+* it found (components.json's `app/styles/tailwind.css`, and what they import from an installed
+* package) give way to the usual ones ({@link DEFAULT_TOKENS}), with what those import. Undefined
+* when that reads the same token files; else `lost` holds the ones it leaves out, the app's own
+* first.
+*/
+async function tokensWithComponents(config, tokens) {
+	const usual = await tokenFiles({
+		...config,
+		tokens: [...DEFAULT_TOKENS.map((p) => ({ path: p })), ...FALLBACK_TOKENS.map((p) => ({
+			path: p,
+			fallback: true
+		}))],
+		tokensDetected: true
+	});
+	const read = new Set(usual.map((f) => relativePath(config.root, f)));
+	if (read.size === tokens.length && tokens.every((t) => read.has(t))) return void 0;
+	const lost = tokens.filter((t) => !read.has(t));
+	const own = lost.filter((t) => !isInstalledPath(t));
+	return { lost: own.length ? own : lost };
 }
 const REGISTRY_DOCS = "https://onsystem.vercel.app/docs/configuration#code-from-shadcn-registries";
 /**
@@ -555,7 +645,7 @@ function consumerGuide(name) {
 		`npx -y ${NAME} inspect`,
 		"```",
 		"",
-		`An app with an ${CONFIG_FILE} of its own reads that instead.`,
+		`An app with an ${CONFIG_FILE} of its own reads it over ${name}'s config: the rules and overrides it sets apply over ${name}'s rules, and, unless it sets components of its own, what it leaves out, such as the components, \`importPath\` and tokens, comes from ${name}'s. \`"extends": false\` in it reads it alone.`,
 		"",
 		"## Coding agents",
 		"",
@@ -854,7 +944,8 @@ async function main(argv, io = defaultIo) {
 			io.stderr(error.message);
 			return 2;
 		}
-		throw error;
+		io.stderr(error.stack ?? String(error));
+		return 2;
 	}
 }
 async function check(patterns, configOptions, values, io) {
@@ -1427,7 +1518,7 @@ async function inspect(configOptions, values, io) {
 	}
 	const lines = [
 		`root     ${model.root}`,
-		`config   ${config.configFile ? `${displayPath(io.cwd, config.configFile)}${declaredBy(config)}` : "(defaults)"}`,
+		`config   ${config.configFile ? `${displayPath(io.cwd, config.configFile)}${declaredBy(config, (f) => displayPath(io.cwd, f))}` : "(defaults)"}`,
 		...config.detected ? [`detected ${config.detected}`] : [],
 		...describeLibraries(config, model, io.cwd).map((line) => `library  ${line}`),
 		`files    ${plural(model.stats.files.components, "component file")}, ${plural(model.stats.files.tokens, "token file")}, ${plural(model.stats.files.docs, "doc")}`,
@@ -1561,7 +1652,7 @@ async function inspectWorkspace(workspace, values, io) {
 		const { model } = ds;
 		const roots = ds.roots();
 		const tokens = [...tokenCounts(model)].map(([category, n]) => `${category} ${n}`);
-		const own = project.config.configFile && project.config.configFile !== workspace.configFile ? `${displayPath(workspace.root, project.config.configFile)}${declaredBy(project.config)}` : void 0;
+		const own = project.config.configFile && (project.config.configFile !== workspace.configFile || project.config.designSystemPackage) ? `${displayPath(workspace.root, project.config.configFile)}${declaredBy(project.config, (f) => displayPath(workspace.root, f))}` : void 0;
 		lines.push("", `${project.dir}${project.name ? ` (${project.name})` : ""}`, ...own ? [`  config     ${own}`] : [], ...project.config.detected ? [`  detected   ${project.config.detected}`] : [], ...describeLibraries(project.config, model, io.cwd).map((line) => `  library    ${line}`), `  files      ${plural(model.stats.files.components, "component file")}, ${plural(model.stats.files.tokens, "token file")}, ${plural(model.stats.files.docs, "doc")}`, `  components ${roots.length} + ${ds.components.length - roots.length} parts${roots.length ? `: ${listNames(roots.map((c) => c.name))}` : ""}`, `  tokens     ${tokens.length ? tokens.join(", ") : "none"}`, ...model.warnings.length ? [`  warnings   ${model.warnings.length}: ${model.warnings[0] ?? ""}`] : []);
 	}
 	if (!loaded.length) lines.push("", `No workspace package has a design system that zero config finds. See ${DOCS}/troubleshooting`);
@@ -1589,9 +1680,14 @@ function explainWorkspace(workspace, loaded, cwd) {
 	for (const { project, ds } of loaded) lines.push("", `${project.dir}${project.name ? ` (${project.name})` : ""}`, ...explainProject(ds, cwd, "  "));
 	return lines;
 }
-/** ` (declared by @acme/ui)` after a config a design-system package declares; empty otherwise. */
-function declaredBy(config) {
-	return config.designSystemPackage ? ` (declared by ${config.designSystemPackage.name})` : "";
+/**
+* ` (declared by @acme/ui)` after a config a design-system package declares, `, over
+* packages/ui/onsystem.config.json (declared by @acme/ui)` after one read over it; empty otherwise.
+*/
+function declaredBy(config, display) {
+	const declared = config.designSystemPackage;
+	if (!declared) return "";
+	return `${config.configFile === declared.config ? "" : `, over ${display(declared.config)}`} (declared by ${declared.name})`;
 }
 /** `A, B, C` up to a dozen names, then `and 40 more`. */
 function listNames(names, max = 12) {

package/dist/{config-B98w8bcg.d.ts → config-BbTW1jKU.d.ts}

@@ -303,6 +303,7 @@ declare const ruleOptionsSchema: z.ZodObject<{
 type RuleOptions = z.infer<typeof ruleOptionsSchema>;
 declare const configSchema: z.ZodObject<{
   $schema: z.ZodOptional<z.ZodString>;
+  extends: z.ZodOptional<z.ZodBoolean>;
   components: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
   exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
   tokens: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
@@ -450,12 +451,21 @@ interface ResolvedConfig {
    */
   base?: string | undefined;
   /**
-   * The design-system package whose config this is: a dependency whose package.json declares it
-   * (`"onsystem": "./onsystem.config.json"`), taken on by a project with no config of its own.
+   * The design-system package whose config this project reads: a dependency whose package.json
+   * declares it (`"onsystem": "./onsystem.config.json"`). A project with no config of its own
+   * takes it on (`configFile` is the package's); one with a config of its own, or a workspace
+   * root's, reads it under that one (`configFile` is that one), unless it sets `"extends": false`.
    * Its paths are rebased from the package; its `tsconfig`, `overrides` and
    * `includeDesignSystem` stay with it.
    */
   designSystemPackage?: DesignSystemPackage | undefined;
+  /**
+   * The project's config sets no `components`, so what it leaves out of `components`,
+   * `importPath`, `docs`, `elements`, `tokens` and `libraries` comes from `designSystemPackage`'s.
+   */
+  inherits?: boolean | undefined;
+  /** The project's config sets `"extends": false`, so no design-system package's config is read. */
+  extendsOff?: boolean | undefined;
   /** `components` comes from the config file or `--components`, not from detection or the defaults. */
   configured?: boolean | undefined;
   /**