onsystem 0.5.0 → 0.6.0

package/README.md

@@ -6,8 +6,15 @@ Built for design-system and platform teams with a React design-system package; a
 
 [![CI](https://img.shields.io/github/actions/workflow/status/dgesteves/onsystem/ci.yml?branch=main&style=flat-square&label=CI&labelColor=0d0f12)](https://github.com/dgesteves/onsystem/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/onsystem?style=flat-square&labelColor=0d0f12&color=22d3ee)](https://www.npmjs.com/package/onsystem)
+[![Downloads](https://img.shields.io/npm/dw/onsystem?style=flat-square&labelColor=0d0f12&color=22d3ee)](https://www.npmjs.com/package/onsystem)
+[![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0%2Fservers%3Fsearch%3Dio.github.dgesteves%2Fonsystem%26version%3Dlatest&query=%24.servers%5B0%5D.server.version&prefix=v&label=MCP%20Registry&style=flat-square&labelColor=0d0f12&color=22d3ee&logo=modelcontextprotocol&logoColor=white)](https://registry.modelcontextprotocol.io/?q=io.github.dgesteves%2Fonsystem)
+[![Cursor Directory](https://img.shields.io/badge/Cursor_Directory-Listed-0d0f12?style=flat-square&logo=cursor&logoColor=white)](https://cursor.directory/plugins/design-system-mcp)
 [![License: MIT](https://img.shields.io/github/license/dgesteves/onsystem?style=flat-square&labelColor=0d0f12&color=22d3ee)](LICENSE)
 
+[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_server-0d0f12?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=onsystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm9uc3lzdGVtIiwiLS1yb290IiwiJHt3b3Jrc3BhY2VGb2xkZXJ9Il19)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?style=flat-square)](https://insiders.vscode.dev/redirect/mcp/install?name=onsystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22onsystem%22%2C%22--root%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D)
+[![Claude Code plugin](https://img.shields.io/badge/Claude_Code-Install_plugin-d97757?style=flat-square&logo=claude&logoColor=white)](https://onsystem.vercel.app/docs/plugin)
+
 **Website and docs:** [onsystem.vercel.app](https://onsystem.vercel.app), with a [playground](https://onsystem.vercel.app/playground) that checks your own code.
 
 <p align="center">
@@ -22,7 +29,7 @@ Coding agents write UI from their training data, not from your design system. As
 
 ## What it checks
 
-onsystem reads your components, `cva` and `tv` variants, parts and tokens from source with the TypeScript compiler, and checks `.tsx` and `.jsx` against them. Every finding has a rule id, a location and the fix.
+onsystem reads your components, `cva` and `tv` variants, parts and tokens from source with the TypeScript compiler, and checks `.tsx` and `.jsx` against them. Every finding has a rule id, a location and the fix. Tokens come from your stylesheets, [DTCG 2025.10 files or a DESIGN.md](https://onsystem.vercel.app/docs/tokens), and `onsystem export` writes them out as either.
 
 | Rule                             | Default | Catches                                                                         |
 | -------------------------------- | ------- | ------------------------------------------------------------------------------- |
@@ -35,11 +42,21 @@ onsystem reads your components, `cva` and `tv` variants, parts and tokens from s
 | `no-hardcoded-spacing`           | warn    | Arbitrary padding, margin and gap (`p-[13px]` → `p-3`)                          |
 | `no-hardcoded-radius`            | warn    | Arbitrary radius (`rounded-[7px]` → `rounded-sm`)                               |
 
-**How often it is wrong.** The [corpus](corpus) job runs `check` on 10 public repositories pinned by commit (Documenso, Dub, Cal.com, midday and others, the four monorepos also from their root: 21 runs, 4,731 findings) and compares the findings with hand labels. In a random sample of 126 findings, 5 are false positives (4.0%) and 55 are debatable; weighted by each run's and rule's share of all findings, about 1.0% are false positives. Shipped code rarely invents components, props or variants, so those three rules have 1 finding in the corpus and none in the sample; their precision comes from the test suite. The [rules reference](https://onsystem.vercel.app/rules) shows each rule on an example and how to [suppress a finding](https://onsystem.vercel.app/rules#suppressing-findings).
+**How often it is wrong.** The [corpus](corpus) job runs `check` on 12 public repositories pinned by commit (Documenso, Dub, Cal.com, midday, Flowise and others, the four monorepos also from their root, and Dub's app also with a config and with `@dub/ui` set up by `init`: 24 runs, 4,076 distinct findings) and compares the findings with hand labels. In a random sample of 149 findings, 88 are clearly right (59.1%), 56 are debatable and 5 are false positives (3.4%); weighted by each run's and rule's share of all findings, about 1.0% are false positives. Shipped code rarely invents components, props or variants: those three rules have 56 findings in the corpus, 55 of them in Flowise, an MUI app that passes props and values MUI's components do not take, and the 10 in the sample are all right. The [rules reference](https://onsystem.vercel.app/rules) shows each rule on an example and how to [suppress a finding](https://onsystem.vercel.app/rules#suppressing-findings).
 
 ## Quickstart
 
-Run it from the app's folder or from the monorepo root, with Node.js 20.19 or later. `npx onsystem inspect` shows what it found, and `--explain` why; at a [monorepo root](https://onsystem.vercel.app/docs/configuration#monorepo-roots), every app and design-system package, each file checked by its own project's design system. `npx onsystem init` writes the config from it and offers a baseline.
+Run it from the app's folder or from the monorepo root, with Node.js 20.19 or later:
+
+```sh
+npx -y onsystem inspect   # what it found; --explain says why
+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, workspace or npm, with no config in the apps.
+
+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.
 
 **Claude Code.** The plugin brings the hook, the MCP server and a skill:
 
@@ -50,7 +67,7 @@ Run it from the app's folder or from the monorepo root, with Node.js 20.19 or la
 
 After each Write or Edit of a `.tsx` or `.jsx` file, the hook runs `onsystem check` on it. Errors go back to Claude as a blocking error with the fix, so Claude corrects the file before it moves on; warnings go as a note. It stays quiet in projects without a design system. [What it runs and touches](https://onsystem.vercel.app/docs/plugin).
 
-**Cursor or VS Code.** [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_server-0d0f12?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=onsystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm9uc3lzdGVtIiwiLS1yb290IiwiJHt3b3Jrc3BhY2VGb2xkZXJ9Il19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?style=flat-square)](https://insiders.vscode.dev/redirect/mcp/install?name=onsystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22onsystem%22%5D%7D), or commit the [config](https://onsystem.vercel.app/docs/clients#cursor-and-vs-code). The agent gets the tools and runs `check_ui` on what it writes.
+**Cursor or VS Code.** [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_server-0d0f12?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=onsystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm9uc3lzdGVtIiwiLS1yb290IiwiJHt3b3Jrc3BhY2VGb2xkZXJ9Il19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?style=flat-square)](https://insiders.vscode.dev/redirect/mcp/install?name=onsystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22onsystem%22%2C%22--root%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D), or commit the [config](https://onsystem.vercel.app/docs/clients#cursor-and-vs-code). The agent gets the tools and runs `check_ui` on what it writes.
 
 **Other agents.** `npx skills add dgesteves/onsystem` adds the skill to any agent with Agent Skills, and there are [plugins for Codex, GitHub Copilot CLI, VS Code and Cursor](https://onsystem.vercel.app/docs/clients#plugins-for-other-agents).
 

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { $ as plural, C as updateBaseline, F as CONFIG_FILES, H as RULE_IDS, I as ConfigError, J as detectProject, K as rulesFor, L as DEFAULT_DOCS, R as DEFAULT_SEVERITY, S as readBaseline, V as LEGACY_CONFIG_FILES, _ as VERSION, at as toPosix, b as applyBaseline, c as silentLogger, g as NAME, h as formatDiagnostics, i as componentFiles, it as relativePath, l as stderrLogger, m as uncheckedNotice, nt as isInside, o as loadDesignSystem, rt as matchesGlob, s as tokenFiles, tt as unique, v as BASELINE_FILE, w as writeBaseline, x as countBaseline, y as LEGACY_BASELINE_FILE } from "./design-system-CnEv5sIL.js";
-import { t as serveStdio } from "./stdio-DjfkiDMV.js";
-import { r as loadTarget } from "./workspace-DzWQ4L8R.js";
+import { A as toDtcg, B as DEFAULT_DOCS, C as updateBaseline, G as RULE_IDS, R as CONFIG_FILES, S as readBaseline, V as DEFAULT_SEVERITY, W as LEGACY_CONFIG_FILES, Z as rulesFor, _ as VERSION, _t as relativePath, at as detectProject, b as applyBaseline, c as silentLogger, et as LIBRARY_IDS, ft as plural, g as NAME, gt as matchesGlob, h as formatDiagnostics, ht as isInside, i as componentFiles, it as declaredConfig, k as toDesignMd, l as stderrLogger, m as uncheckedNotice, mt as unique, nt as PACKAGE_FIELD, o as loadDesignSystem, ot as findDesignSystemPackage, s as tokenFiles, st as isDesignSystemName, tt as libraryAdapter, v as BASELINE_FILE, vt as toPosix, w as writeBaseline, x as countBaseline, y as LEGACY_BASELINE_FILE, z as ConfigError } from "./design-system-A3pRX3Ka.js";
+import { t as serveStdio } from "./stdio-CEChNFLR.js";
+import { r as loadTarget } from "./workspace-CHvUwgz9.js";
 import fs from "node:fs";
 import path from "node:path";
 import { escapePath, glob } from "tinyglobby";
-import fs$1 from "node:fs/promises";
+import fsp from "node:fs/promises";
 import { spawnSync } from "node:child_process";
 import readline from "node:readline/promises";
 import { parseArgs } from "node:util";
@@ -20,24 +20,32 @@ function explainProject(ds, cwd, indent = "") {
 	const lines = [];
 	const out = (line = "") => lines.push(line ? `${indent}${line}` : "");
 	out("How the design system was found");
+	for (const step of packageSteps(config, cwd)) out(`  ${(step.accepted ? "found" : "no").padEnd(6)} ${step.candidate}: ${step.reason}`);
 	if (config.configured) out(`  components come from ${config.configFile ? display(cwd, config.configFile) : "--components"}, so zero config did not look`);
 	else {
 		const steps = [];
-		detectProject(config.root, config.tsconfig, steps);
+		detectProject(config.root, config.tsconfig, steps, config.designSystemPackage);
 		for (const step of steps) out(`  ${(step.accepted ? "found" : "no").padEnd(6)} ${step.candidate}: ${step.reason}`);
 		if (!config.detected) out(`  So the defaults apply: ${config.components.join(", ")}${model.stats.files.components ? "" : ", which match nothing"}.`);
 	}
+	const named = (library) => `${library.package}${library.version ? ` ${library.version}` : ""}`;
+	for (const library of config.libraries ?? []) {
+		const count = model.components.filter((c) => c.library === library.package).length;
+		out(library.dir ? `  ${"found".padEnd(6)} ${named(library)}: a dependency, ${count} components from its type declarations in ${display(cwd, library.dir)}` : `  ${"no".padEnd(6)} ${named(library)}: a dependency, but not installed`);
+	}
+	for (const library of config.librariesOff ?? []) out(`  ${"no".padEnd(6)} ${named(library)}: a dependency, ${librariesLeftOut(config, cwd)}`);
 	out();
 	out("Resolved config");
 	const field = (name, value) => out(`  ${name.padEnd(12)} ${value}`);
 	field("root", config.root);
-	field("config", config.configFile ? display(cwd, config.configFile) : "(none)");
+	field("config", config.configFile ? `${display(cwd, config.configFile)}${config.designSystemPackage ? ` (declared by ${config.designSystemPackage.name})` : ""}` : "(none)");
 	field("components", listOf$1(config.components) || "(none)");
 	field("exclude", listOf$1(config.exclude));
-	field("tokens", listOf$1(config.tokens.map((t) => `${t.path}${t.prefix ? ` (prefix ${t.prefix})` : ""}`)));
+	field("tokens", listOf$1(config.tokens.map((t) => `${t.path}${t.prefix ? ` (prefix ${t.prefix})` : ""}${t.fallback ? " (when nothing else is found)" : ""}`)));
 	field("docs", listOf$1(config.docs));
 	field("tsconfig", config.tsconfig ?? (fs.existsSync(path.join(config.root, "tsconfig.json")) ? "tsconfig.json" : "(none)"));
 	field("importPath", importPaths(ds));
+	field("libraries", config.libraryIds === void 0 ? `every library onsystem reads (${LIBRARY_IDS.join(", ")})` : config.libraryIds !== false && config.libraryIds.length ? config.libraryIds.join(", ") : `none ("libraries": ${JSON.stringify(config.libraryIds)})`);
 	if (config.tailwindConfig) field("tailwind", display(config.root, config.tailwindConfig));
 	if (config.designSystems) field("primary", config.designSystems.map((d, i) => `${i ? "then " : ""}${d.source} (${d.imports} imports)`).join("; "));
 	const changed = RULE_IDS.filter((id) => config.rules[id].severity !== DEFAULT_SEVERITY[id]);
@@ -48,7 +56,12 @@ function explainProject(ds, cwd, indent = "") {
 	out("Tokens");
 	const found = ds.tokens;
 	const files = model.stats.files.tokens;
-	out(`  ${found.length} tokens from ${files} ${files === 1 ? "file" : "files"}${files ? "" : `: no file matches ${config.tokens.map((t) => t.path).join(", ")}`}`);
+	const themed = found.filter((t) => t.origin === "library");
+	out(`  ${found.length - themed.length} tokens from ${files} ${files === 1 ? "file" : "files"}${files ? "" : `: no file matches ${config.tokens.map((t) => t.path).join(", ")}`}`);
+	if (themed.length) {
+		const sources = [...new Set(themed.map((t) => t.source.file))];
+		out(`  ${themed.length} tokens from a library's theme in ${sources.join(", ")}`);
+	}
 	const defined = new Set(found.map((t) => t.cssVar).filter((v) => Boolean(v)));
 	const missing = (value) => [...value.matchAll(/var\(\s*(--[\w-]+)/g)].map((m) => m[1] ?? "").filter((v) => !defined.has(v));
 	const unresolved = found.filter((t) => missing(t.value).length);
@@ -69,6 +82,10 @@ function explainProject(ds, cwd, indent = "") {
 	}
 	return lines;
 }
+/** Why a library the project depends on is not read: `left out by "libraries" in onsystem.config.json`. */
+function librariesLeftOut(config, cwd) {
+	return `left out by "libraries" in ${config.configFile ? display(cwd, config.configFile) : "the config"}`;
+}
 /** The first few, then how many more: a package's exports can name hundreds of files. */
 function listOf$1(items, max = 8) {
 	const shown = items.slice(0, max).join(", ");
@@ -95,15 +112,46 @@ function display(cwd, file) {
 	const rel = relativePath(cwd, file);
 	return rel && !rel.startsWith("..") ? rel : file;
 }
+/**
+* Whether a dependency's declared config was taken on, for a project without a config of its
+* own: the package it came from and the others that declare one, or that none does.
+*/
+function packageSteps(config, cwd) {
+	const declared = config.designSystemPackage;
+	if (config.configFile && !declared) return [];
+	const lookup = findDesignSystemPackage(config.root);
+	if (!lookup) return [];
+	const candidate = "a design-system package's config";
+	const skipped = lookup.skipped.length ? `; ${lookup.skipped.map((p) => p.name).join(", ")} ${lookup.skipped.length === 1 ? "declares one" : "declare one"} that cannot be read, skipped since installed` : "";
+	if (!declared) return [{
+		candidate,
+		accepted: false,
+		reason: `no dependency declares one ("onsystem" in its package.json) among ${lookup.dependencies} ${lookup.dependencies === 1 ? "dependency" : "dependencies"}${skipped}`
+	}];
+	return [{
+		candidate,
+		accepted: true,
+		reason: `${declared.name} (${declared.installed ? "installed" : "a workspace package"}) declares ${display(cwd, declared.config)}, which this project takes on, with its paths from ${display(cwd, declared.dir)}${lookup.others.length ? `; ${lookup.others.join(", ")} also declare one, not read: one config is taken on, from the package the code imports most` : ""}${skipped}`
+	}];
+}
 //#endregion
 //#region src/init.ts
 const SCHEMA = "https://unpkg.com/onsystem/schema.json";
 /** More detected globs than this are files, not folders: zero config keeps them. */
 const MAX_GLOBS = 6;
+/** What a design-system package's apps are told about it, next to its config. */
+const GUIDE_FILE = "ONSYSTEM.md";
 /**
 * Writes `onsystem.config.json` in the root from what zero config finds there, or from
 * the answers to up to three questions when it finds nothing, then checks the project
 * once without failing and offers to record what it found as the baseline.
+*
+* In a design-system package (one zero config reads through its own `exports`, or named like
+* one, as apps look for it), it also declares the config in package.json
+* (`"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.
 */
 async function init(configOptions, options, io, runCheck) {
 	const { config, workspace } = await loadTarget({
@@ -111,16 +159,23 @@ async function init(configOptions, options, io, runCheck) {
 		config: void 0
 	});
 	const root = config.root;
-	const existing = [...CONFIG_FILES, ...LEGACY_CONFIG_FILES].map((name) => path.join(root, name)).find((file) => fs.existsSync(file));
+	const declared = declaredConfig(root);
+	const existing = [...CONFIG_FILES, ...LEGACY_CONFIG_FILES].map((name) => path.join(root, name)).find((file) => fs.existsSync(file)) ?? (declared && "file" in declared ? declared.file : void 0);
+	const manifest = readManifest(root);
+	const name = typeof manifest?.json.name === "string" ? manifest.json.name : void 0;
+	const designSystem = !workspace && !config.designSystemPackage && name !== void 0 && (config.detected?.startsWith("package.json exports of") === true || isDesignSystemName(name));
 	if (existing && !options.force) {
-		io.stderr(`init: ${relativePath(io.cwd, existing) || existing} already exists. Run \`${NAME} inspect --explain\` to see what it resolves to, or pass --force to write a new onsystem.config.json.`);
+		const share = designSystem && !declared && existing.endsWith(".json") ? ` To share it with the apps that depend on ${name}, add "${PACKAGE_FIELD}": "./${path.basename(existing)}" to package.json, and to "files" when it lists them (https://onsystem.vercel.app/docs/design-system-packages).` : "";
+		io.stderr(`init: ${relativePath(io.cwd, existing) || existing} already exists. Run \`${NAME} inspect --explain\` to see what it resolves to, or pass --force to write a new onsystem.config.json.${share}`);
 		return 2;
 	}
 	const ask = options.yes ? void 0 : io.prompt;
 	const file = { $schema: SCHEMA };
 	const notes = [];
 	const relative = (abs) => relativePath(root, abs);
-	if (configOptions.components?.length) {
+	const inherited = options.force ? void 0 : config.designSystemPackage;
+	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.`);
+	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;
@@ -138,6 +193,16 @@ async function init(configOptions, options, io, runCheck) {
 			if (docs.length) file.docs = [...DEFAULT_DOCS, ...docs];
 		}
 		if (tokens.length) file.tokens = tokens;
+	} else if ((await componentFiles(config)).length) {
+		const matching = [];
+		for (const glob of config.components) if ((await componentFiles({
+			...config,
+			components: [glob]
+		})).length) matching.push(glob);
+		notes.push(`Found the design system in the default folders: ${matching.join(", ")}.`);
+		file.components = matching;
+		const tokens = (await tokenFiles(config)).map(relative);
+		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.`);
@@ -167,10 +232,19 @@ async function init(configOptions, options, io, runCheck) {
 		const importPath = (await ask("How do apps import them? A package name such as @acme/ui, or leave it empty for tsconfig paths: ")).trim();
 		if (importPath) file.importPath = importPath;
 	}
-	const out = path.join(root, "onsystem.config.json");
-	fs.writeFileSync(out, `${JSON.stringify(file, null, 2)}\n`);
+	const written = [];
+	if (!inherited) {
+		const out = path.join(root, CONFIG_FILE);
+		fs.writeFileSync(out, `${JSON.stringify(file, null, 2)}\n`);
+		written.push(CONFIG_FILE);
+	}
+	if (designSystem && manifest && name) {
+		written.push(...declarePackage(root, manifest, name, options.force, notes));
+		const shipped = await unshipped(config, manifest.json);
+		if (shipped) notes.push(shipped);
+	}
 	for (const note of notes) io.stdout(note);
-	io.stdout(`Wrote ${relativePath(io.cwd, out) || out}.`);
+	if (written.length) io.stdout(`Wrote ${written.map((f) => relativePath(io.cwd, path.join(root, f)) || f).join(", ")}.`);
 	const checkIo = {
 		...io,
 		cwd: root
@@ -202,9 +276,11 @@ async function init(configOptions, options, io, runCheck) {
 	io.stdout(total ? `Dry run of \`${NAME} check .\`: ${count$1(errors, "error")} and ${count$1(warnings, "warning")} in ${flagged} of ${count$1(results.length, "file")}. By rule: ${[...byRule].sort((a, b) => b[1] - a[1]).map(([rule, n]) => `${rule} ${n.toLocaleString("en-US")}`).join(", ")}.` : `Dry run of \`${NAME} check .\`: no problems in ${count$1(results.length, "file")}.`);
 	for (const line of dry.stderr.split("\n").filter(Boolean)) io.stdout(line);
 	const hasBaseline = [BASELINE_FILE, LEGACY_BASELINE_FILE].some((name) => fs.existsSync(path.join(root, name)));
+	let baselineWritten = false;
 	if (total && !hasBaseline) {
-		const answer = options.yes ? "y" : ask ? (await ask(`Record these ${total.toLocaleString("en-US")} findings in ${BASELINE_FILE}, so check fails only on new ones? [Y/n] `)).trim().toLowerCase() : "n";
-		if (answer === "" || answer.startsWith("y")) {
+		const answer = options.yes ? "y" : ask ? (await ask(`Record these ${total.toLocaleString("en-US")} findings in ${BASELINE_FILE}, so check fails only on new ones? [Y/n] `)).trim().toLowerCase() : void 0;
+		if (answer === void 0) io.stdout(`No terminal to ask in, so the baseline question was skipped and no baseline was written; \`${NAME} check . --update-baseline\` records one.`);
+		else if (answer === "" || answer.startsWith("y")) {
 			const recorded = await runCheck([
 				"check",
 				".",
@@ -212,11 +288,128 @@ async function init(configOptions, options, io, runCheck) {
 				...options.cache ? [] : ["--no-cache"]
 			], checkIo);
 			if (recorded.stdout) io.stdout(recorded.stdout);
+			baselineWritten = fs.existsSync(path.join(root, BASELINE_FILE));
 		} else io.stdout(`No baseline written; \`${NAME} check . --update-baseline\` records one later.`);
 	}
-	io.stdout(`Next: commit onsystem.config.json${total && !hasBaseline ? ` and ${BASELINE_FILE}` : ""}, and run \`npx ${NAME} check . --format github --require-design-system\` in CI.`);
+	const commit = [...written, ...baselineWritten ? [BASELINE_FILE] : []];
+	const files = commit.length > 1 ? `${commit.slice(0, -1).join(", ")} and ${commit.at(-1) ?? ""}` : commit[0];
+	io.stdout(designSystem && name ? `Next: commit ${files}. An app that depends on ${name} now finds it with no config of its own: run \`npx ${NAME} inspect\` in one to see it, and give its team ${GUIDE_FILE}.` : `Next: ${files ? `commit ${files}, and ` : ""}run \`npx ${NAME} check . --format github --require-design-system\` in CI.`);
 	return 0;
 }
+const CONFIG_FILE = "onsystem.config.json";
+function readManifest(root) {
+	const file = path.join(root, "package.json");
+	try {
+		const text = fs.readFileSync(file, "utf8");
+		const json = JSON.parse(text);
+		if (!json || typeof json !== "object" || Array.isArray(json)) return void 0;
+		return {
+			file,
+			json,
+			indent: /^([ \t]+)"/m.exec(text)?.[1] ?? "  ",
+			newline: text.endsWith("\n")
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* Declares the config in the package's package.json, `"onsystem": "./onsystem.config.json"`,
+* and adds it to `files` when the package lists the files it publishes, so apps that install it
+* get it too. Writes ONSYSTEM.md for the apps' teams unless one exists. Returns what it wrote.
+*/
+function declarePackage(root, manifest, name, force, notes) {
+	const written = [];
+	const { json } = manifest;
+	const value = `./${CONFIG_FILE}`;
+	let changed = false;
+	if (json["onsystem"] !== value) {
+		json[PACKAGE_FIELD] = value;
+		changed = true;
+	}
+	const files = Array.isArray(json.files) ? json.files : void 0;
+	if (files && !ships(files, CONFIG_FILE)) {
+		files.push(CONFIG_FILE);
+		changed = true;
+	}
+	if (changed) {
+		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.`);
+	const guide = path.join(root, GUIDE_FILE);
+	if (force || !fs.existsSync(guide)) {
+		fs.writeFileSync(guide, consumerGuide(name));
+		written.push(GUIDE_FILE);
+	} else notes.push(`${GUIDE_FILE} already exists; it was left as it is (--force replaces it).`);
+	return written;
+}
+/**
+* What apps that install the package from a registry will not find: the component and token
+* files its `files` list leaves out of the published package. Undefined for a private package,
+* one without a `files` list (npm then ships everything), or when nothing is left out.
+*/
+async function unshipped(config, json) {
+	if (json.private === true || !Array.isArray(json.files)) return void 0;
+	const files = json.files;
+	const missing = [...await componentFiles(config), ...await tokenFiles(config)].map((f) => relativePath(config.root, f)).filter((f) => !f.startsWith("../")).filter((f) => !ships(files, f));
+	if (!missing.length) return void 0;
+	const folders = [...new Set(missing.map((f) => f.includes("/") ? `${f.slice(0, f.indexOf("/"))}/` : f))];
+	return `Apps that install ${typeof json.name === "string" ? json.name : "the package"} from a registry get only what "files" in package.json publishes, which leaves out ${folders.join(", ")} (${count$1(missing.length, "component or token file")}): they will not find those. Add ${folders.length === 1 ? "it" : "them"} to "files" for them; workspace apps read the sources either way.`;
+}
+/** Whether npm's `files` list publishes `file`, a path relative to the package. */
+function ships(files, file) {
+	return files.some((entry) => {
+		if (typeof entry !== "string") return false;
+		const pattern = entry.replace(/^\.?\//, "").replace(/\/+$/, "");
+		if (!pattern || pattern.startsWith("!")) return false;
+		return file === pattern || file.startsWith(`${pattern}/`) || matchesGlob(file, pattern) || matchesGlob(file, `${pattern}/**`);
+	});
+}
+/** ONSYSTEM.md: how an app that uses the package gets the design system to its agents and CI. */
+function consumerGuide(name) {
+	return `${[
+		`# onsystem in apps that use ${name}`,
+		"",
+		`${name} declares its [onsystem](https://onsystem.vercel.app) config in its package.json: \`"${PACKAGE_FIELD}": "./${CONFIG_FILE}"\`. An app that depends on ${name}, as a workspace package or installed from npm, reads that config when it has none of its own, and its UI is checked against ${name}'s components, props, variants and tokens. To see what an app finds, run this in its folder:`,
+		"",
+		"```sh",
+		`npx -y ${NAME} inspect`,
+		"```",
+		"",
+		`An app with an ${CONFIG_FILE} of its own reads that instead.`,
+		"",
+		"## Coding agents",
+		"",
+		"Claude Code: the plugin checks every UI file the agent writes and hands the errors back to fix, and adds the MCP server and a skill.",
+		"",
+		"```text",
+		"/plugin marketplace add dgesteves/onsystem",
+		"/plugin install onsystem@dgesteves",
+		"```",
+		"",
+		`Other agents: \`npx skills add dgesteves/onsystem\` adds the skill, and \`npx -y ${NAME}\` started in the app is the MCP server. [Set up your agent](https://onsystem.vercel.app/docs/clients) has the config for each client.`,
+		"",
+		"## CI",
+		"",
+		"In the app, record the findings it already has once, and commit the baseline, so pull requests fail only on new ones:",
+		"",
+		"```sh",
+		`npm install --save-dev ${NAME}`,
+		`npx ${NAME} check . --update-baseline`,
+		"```",
+		"",
+		"```yaml",
+		`- run: npx ${NAME} check . --format github --require-design-system`,
+		"```",
+		"",
+		"[CI and baselines](https://onsystem.vercel.app/docs/ci) has the GitHub Action and the rest.",
+		"",
+		"## Changing the config",
+		"",
+		`${CONFIG_FILE} in ${name} sets what every app gets: where the components, tokens and docs are, and the rules' severities. Its \`tsconfig\`, \`overrides\` and \`includeDesignSystem\` apply to ${name}'s own files only. [Design-system packages](https://onsystem.vercel.app/docs/design-system-packages) has the details.`
+	].join("\n")}\n`;
+}
 function count$1(n, word) {
 	return `${n.toLocaleString("en-US")} ${n === 1 ? word : `${word}s`}`;
 }
@@ -234,6 +427,9 @@ Usage
   onsystem check <paths...>      Lint files, folders or globs with the check_ui rules
                                  (for CI)
   onsystem inspect               Print what was extracted from the project
+  onsystem export --format dtcg|design-md
+                                 Print the tokens it found as a DTCG 2025.10 file or a
+                                 DESIGN.md (--out <file> writes them to a file)
   onsystem init                  Write onsystem.config.json from what was found, run a
                                  dry-run check and offer a baseline
   onsystem help                  Show this help
@@ -252,7 +448,9 @@ Options
   --docs <glob>           Component docs (Markdown/MDX), repeatable
   --no-cache              Ignore the on-disk extraction cache
   --no-watch              serve: do not reload when files change
-  --format <format>       check: pretty | json | github | sarif (default: pretty)
+  --format <format>       check: pretty | json | github | sarif (default: pretty);
+                          export: dtcg | design-md
+  --out <file>            export: write to this file instead of stdout
   --max-warnings <n>      check: exit 1 when there are more than n warnings
   --update-baseline       check: record the current findings as accepted, and exit 0
   --baseline <file>       check: baseline file (default: ${BASELINE_FILE} in the root,
@@ -292,7 +490,8 @@ const defaultIo = {
 	stdout: (text) => process.stdout.write(`${text}\n`),
 	stderr: (text) => process.stderr.write(`${text}\n`),
 	color: process.stdout.isTTY && !process.env.NO_COLOR,
-	prompt: process.stdin.isTTY && process.stdout.isTTY ? askInTerminal : void 0
+	prompt: process.stdin.isTTY && process.stdout.isTTY ? askInTerminal : void 0,
+	stdinIsTTY: process.stdin.isTTY
 };
 /** One question on the terminal, answered with a line. */
 async function askInTerminal(question) {
@@ -337,10 +536,8 @@ async function main(argv, io = defaultIo) {
 					type: "boolean",
 					default: true
 				},
-				format: {
-					type: "string",
-					default: "pretty"
-				},
+				format: { type: "string" },
+				out: { type: "string" },
 				"max-warnings": { type: "string" },
 				baseline: { type: "string" },
 				"update-baseline": {
@@ -422,15 +619,18 @@ async function main(argv, io = defaultIo) {
 	try {
 		switch (command) {
 			case "serve":
+				if (io.stdinIsTTY) io.stderr(`${NAME} is an MCP server: it is waiting for an agent on stdin. Add it to your agent (${DOCS}/clients), or run \`npx -y ${NAME} inspect\` or \`npx -y ${NAME} check .\` here. Ctrl+C quits.`);
 				await serveStdio({
 					...configOptions,
 					cache: values.cache,
 					watch: values.watch,
-					logger: stderrLogger
+					logger: stderrLogger,
+					...io.transport ? { transport: io.transport } : {}
 				});
 				return 0;
 			case "check": return await check(rest, configOptions, values, io);
 			case "inspect": return await inspect(configOptions, values, io);
+			case "export": return await exportTokens(configOptions, values, io);
 			case "init": return await init(configOptions, {
 				yes: values.yes,
 				force: values.force,
@@ -470,14 +670,14 @@ async function check(patterns, configOptions, values, io) {
 		io.stderr(`check: pass files, folders or globs, e.g. ${NAME} check .`);
 		return 2;
 	}
-	const format = values.format;
+	const format = values.format ?? "pretty";
 	if (![
 		"pretty",
 		"json",
 		"github",
 		"sarif"
 	].includes(format)) {
-		io.stderr(`check: unknown --format "${values.format}" (pretty, json, github, sarif)`);
+		io.stderr(`check: unknown --format "${format}" (pretty, json, github, sarif)`);
 		return 2;
 	}
 	const maxWarnings = values["max-warnings"] === void 0 ? void 0 : Number(values["max-warnings"]);
@@ -487,6 +687,7 @@ async function check(patterns, configOptions, values, io) {
 	}
 	const target = await loadTarget(configOptions);
 	warnDeprecated(target.config.deprecations, format, io);
+	warnDeprecated(configWarnings(target), format, io);
 	const selection = target.workspace ? await selectInWorkspace(target.workspace, patterns, values, format, io) : await selectInProject(target.config, patterns, values, format, io);
 	if (typeof selection === "number") return selection;
 	const { files, notes } = selection;
@@ -518,7 +719,7 @@ async function check(patterns, configOptions, values, io) {
 	let baselined = 0;
 	let fixed = 0;
 	for (const file of files) {
-		const code = await fs$1.readFile(file, "utf8");
+		const code = await fsp.readFile(file, "utf8");
 		const ds = selection.designSystemOf(file);
 		let result = ds.check(code, relativePath(ds.root, file));
 		const key = baselineKey(file);
@@ -660,7 +861,7 @@ async function selectInProject(config, patterns, values, format, io) {
 		return 0;
 	}
 	const notice = ds.notice();
-	if (notice && values["require-design-system"]) {
+	if (notice && values["require-design-system"] && !ds.hasDesignSystem()) {
 		io.stderr(`check --require-design-system: ${notice}`);
 		return 2;
 	}
@@ -747,7 +948,7 @@ async function selectInWorkspace(workspace, patterns, values, format, io) {
 	}
 	if (values["require-design-system"]) {
 		let complete = false;
-		for (const p of workspace.projects) if (!(await load(p)).notice()) {
+		for (const p of workspace.projects) if ((await load(p)).hasDesignSystem()) {
 			complete = true;
 			break;
 		}
@@ -799,6 +1000,7 @@ async function inspect(configOptions, values, io) {
 	const target = await loadTarget(configOptions);
 	const { config } = target;
 	warnDeprecated(config.deprecations, "pretty", io);
+	warnDeprecated(configWarnings(target), "pretty", io);
 	if (target.workspace) return inspectWorkspace(target.workspace, values, io);
 	const ds = await loadDesignSystem(config, {
 		cache: values.cache,
@@ -811,12 +1013,13 @@ async function inspect(configOptions, values, io) {
 	}
 	const lines = [
 		`root     ${model.root}`,
-		`config   ${config.configFile ? displayPath(io.cwd, config.configFile) : "(defaults)"}`,
+		`config   ${config.configFile ? `${displayPath(io.cwd, config.configFile)}${declaredBy(config)}` : "(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")}`,
 		`time     ${model.stats.durationMs}ms${model.stats.fromCache ? " (cache)" : ""}`,
 		"",
-		`Components (${ds.roots().length} + ${model.components.length - ds.roots().length} parts)`
+		`Components (${ds.roots().length} + ${ds.components.length - ds.roots().length} parts)`
 	];
 	for (const c of ds.roots()) {
 		const variants = c.variants.map((v) => `${v.name}[${v.values.length}]`).join(" ");
@@ -840,6 +1043,64 @@ async function inspect(configOptions, values, io) {
 	io.stdout(lines.join("\n"));
 	return 0;
 }
+/**
+* `MUI (@mui/material 9.4.0): 149 components from its type declarations`, per library the
+* project depends on, including those the config's `libraries` leaves out.
+*/
+function describeLibraries(config, model, cwd) {
+	const name = (library) => `${libraryAdapter(library.package)?.title ?? library.package} (${library.package}${library.version ? ` ${library.version}` : ""})`;
+	return [...(config.libraries ?? []).map((library) => {
+		if (!library.dir) return `${name(library)}: a dependency, but not installed`;
+		const count = model.components.filter((c) => c.library === library.package).length;
+		return `${name(library)}: ${plural(count, "component")} from its type declarations`;
+	}), ...(config.librariesOff ?? []).map((library) => `${name(library)}: ${librariesLeftOut(config, cwd)}`)];
+}
+/**
+* `export --format dtcg|design-md`: the project's tokens as a DTCG 2025.10 file or a
+* DESIGN.md, on stdout or in the `--out` file.
+*/
+async function exportTokens(configOptions, values, io) {
+	const format = values.format;
+	if (format !== "dtcg" && format !== "design-md") {
+		io.stderr(`export: pass --format dtcg or --format design-md${format === void 0 ? "" : ` (not "${format}")`}`);
+		return 2;
+	}
+	const target = await loadTarget(configOptions);
+	warnDeprecated(target.config.deprecations, "pretty", io);
+	warnDeprecated(configWarnings(target), "pretty", io);
+	if (target.workspace) {
+		const dirs = target.workspace.projects.map((p) => p.dir);
+		io.stderr(`export: ${target.workspace.root} is a monorepo root, and each project has its own tokens. Pass --root with one of them${dirs.length ? ` (${listOf(dirs)})` : ""}.`);
+		return 2;
+	}
+	const ds = await loadDesignSystem(target.config, {
+		cache: values.cache,
+		logger: silentLogger
+	});
+	if (!ds.tokens.length) {
+		io.stderr(`export: no design tokens found in ${ds.root}. \`${NAME} inspect --explain\` shows where it looked.`);
+		return 2;
+	}
+	const result = format === "dtcg" ? toDtcg(ds.tokens) : toDesignMd(ds.tokens, { name: projectName(ds.root) });
+	for (const warning of result.warnings) io.stderr(`export: ${warning}`);
+	if (values.out === void 0) {
+		io.stdout(result.text.trimEnd());
+		return 0;
+	}
+	const file = path.resolve(io.cwd, values.out);
+	await fsp.mkdir(path.dirname(file), { recursive: true });
+	await fsp.writeFile(file, result.text);
+	io.stdout(`Wrote ${plural(result.count, "token")} to ${displayPath(io.cwd, file)} (${format === "dtcg" ? "DTCG 2025.10" : "DESIGN.md"})`);
+	return 0;
+}
+/** The package name in the root's package.json, else the folder's name. */
+function projectName(root) {
+	try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+		if (typeof pkg.name === "string" && pkg.name) return pkg.name;
+	} catch {}
+	return path.basename(root);
+}
 function tokenCounts(model) {
 	const counts = /* @__PURE__ */ new Map();
 	for (const t of model.tokens) counts.set(t.category, (counts.get(t.category) ?? 0) + 1);
@@ -880,8 +1141,8 @@ 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) : void 0;
-		lines.push("", `${project.dir}${project.name ? ` (${project.name})` : ""}`, ...own ? [`  config     ${own}`] : [], ...project.config.detected ? [`  detected   ${project.config.detected}`] : [], `  files      ${plural(model.stats.files.components, "component file")}, ${plural(model.stats.files.tokens, "token file")}, ${plural(model.stats.files.docs, "doc")}`, `  components ${roots.length} + ${model.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] ?? ""}`] : []);
+		const own = project.config.configFile && project.config.configFile !== workspace.configFile ? `${displayPath(workspace.root, project.config.configFile)}${declaredBy(project.config)}` : 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`);
 	if (workspace.others.length) lines.push("", `Without a design system (${workspace.others.length}): ${listNames(workspace.others)}`);
@@ -903,6 +1164,10 @@ 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})` : "";
+}
 /** `A, B, C` up to a dozen names, then `and 40 more`. */
 function listNames(names, max = 12) {
 	const shown = names.slice(0, max).join(", ");
@@ -912,6 +1177,10 @@ function listNames(names, max = 12) {
 * Says once what a file's old name means: on stderr, or as a workflow warning with
 * `--format github` so it shows on the run. Never on stdout otherwise, which JSON output owns.
 */
+/** What the configs read have to say: the project's, or every package's at a monorepo root. */
+function configWarnings(target) {
+	return target.workspace ? target.workspace.warnings : target.config.warnings;
+}
 function warnDeprecated(messages, format, io) {
 	for (const text of messages ?? []) if (format === "github") io.stdout(`::warning title=${NAME}::${text}`);
 	else io.stderr(text);