canon-ds 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Canon contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# Canon
+
+**Connect Canon to your agent. Shape the design in Studio.**
+
+Canon is an open-source design system for apps built with coding agents. It provides shared tokens, components, page layouts, a visual Studio and focused instructions that keep interface work consistent.
+
+[Documentation and connection prompt](https://marcosdocanto.github.io/canon/) · [Explore the Studio](https://marcosdocanto.github.io/canon/preview.html) · [Contribute](CONTRIBUTING.md)
+
+## Connect your agent
+
+Paste this into the Claude or Codex conversation for a new or existing project:
+
+```text
+Use Canon as this project's design system.
+Read and follow: https://marcosdocanto.github.io/canon/CONNECT.md
+```
+
+The agent installs Canon, imports the design, connects its generated CSS to the existing app and opens the project's Studio. You can customize the design before building the first screen or at any point later. Reconnecting preserves existing Canon definitions and their configured path. You do not need to describe the app again.
+
+The public site is a catalog. Your editable Studio runs locally, and your design files stay in the project. The application uses generated CSS through its own frontend and deployment stack; Canon requires no hosted service at runtime. Node.js **22.18.0 or newer** is needed for Canon's build tools and Studio.
+
+<details>
+<summary>npm installation reference</summary>
+
+For an npm release, the agent can install the package directly:
+
+```sh
+npm install --save-dev canon-ds
+npx canon connect https://marcosdocanto.github.io/canon/CONNECT.md
+npx canon studio --port 0 --open
+```
+
+Use the project's existing package manager. The connection procedure also supports the site's downloadable package when a registry release is unavailable, retaining that archive in the project for future installs.
+
+</details>
+
+## Use Studio
+
+Explore the public component catalog and page layouts. In the Studio opened by your agent, use **Customize → Style** to change the visual direction, or click a component with the editor open to adjust its parts in **Inspect**. Choose an example and compare desktop/mobile layouts at Fit or 100%.
+
+In a bound Studio, **Save** atomically updates the design source, generated CSS and installed agent references. MCP reads the new build on its next data request, so there is no sync or reload step to ask for. The app reflects CSS changes through its framework's normal reload or build. Use **Undo** to revert an edit and save again when needed.
+
+Screen layout, routes and application behavior remain agent work; Save does not rewrite or deploy the app. For design-source edits made outside Studio, run `canon sync`.
+
+## Contribute
+
+Contributions to components, accessibility, performance, Studio, agent integrations and documentation are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), [component authoring](docs/AUTHORING.md) or [pattern authoring](docs/PATTERNS.md). Use an issue to report a reproducible problem or discuss a larger change, then open a focused pull request.
+
+Canon is distributed under the [MIT license](LICENSE). You can use it in personal, commercial and closed-source applications, subject to the license terms. [Third-party notices](THIRD_PARTY_NOTICES.md) cover the included icon references and external assets. Maintainers follow the [release guide](docs/RELEASING.md).
+
+<details>
+<summary>Technical reference for agents and contributors</summary>
+
+## How it stays consistent
+
+1. **Shared definitions.** `design/tokens.json`, component specs and patterns generate CSS, docs, React and the gallery from the same source. `src/engine.js` runs in Node and in the browser editor.
+2. **Focused agent context.** Start with `DESIGN.compact.md` and MCP's `design_rules`. Discover pieces with `search`, `list_components` or `list_patterns`; fetch only the required specs with `get_component` and `get_pattern`. Without MCP, read the relevant source JSON and sections of `DESIGN.md`.
+3. **Installed references.** `canon connect` builds and installs managed blocks in `AGENTS.md` and `CLAUDE.md`, the Claude Code skill, Cursor rule, MCP configuration and optional lint hook, then records the design path in `.canon/project.json`. `--no-hooks` skips adding the hook; it does not remove an existing one.
+4. **Code checks.** `canon lint` detects supported violations such as raw style values, Tailwind palette classes, unknown Canon classes and invalid prop values. `canon check` verifies a complete build, compiler version, source content and generated file hashes, then runs lint. Application tests and browser review cover the remaining delivery requirements.
+
+## Generated files
+
+With the default output directory, these files live in `design/dist/`:
+
+| File | Purpose |
+| --- | --- |
+| `<prefix>.css` | Complete token, reset, component and pattern styles, ready for a prototype. |
+| `tokens.css`, `base.css`, `components.css` | The same styles as separate layers. |
+| `css/components/<slug>.css`, `css/patterns/<slug>.css` | Individual styles for explicit imports of the pieces used by a product. |
+| `tailwind.theme.css`, `tailwind.preset.cjs` | Tailwind v4 and v3 themes mapped to the tokens. |
+| `react/` | Typed React wrappers for components and their parts. |
+| `tokens.dtcg.json` | Tokens in DTCG format. |
+| `preview.html`, `docs.html` | Studio and the user guide. |
+| `CONNECT.md` | Canon's setup procedure for agents connecting to a new or existing project. |
+| `DESIGN.compact.md`, `DESIGN.md` | Focused agent reference and the complete specification. |
+| `agents/` | Instructions, skill, rules and MCP configuration for installation. |
+| `canon.lock.json` | The build manifest verified by `canon check`. |
+
+For a product, the agent can import `tokens.css`, `base.css` and the individual component and pattern styles actually used, including components referenced by each pattern. This is an explicit integration choice; the agent should measure the resulting route rather than assume unused styles are automatically removed.
+
+## Commands
+
+These are reference commands for the agent. Run them in the application repository and use `--design` consistently if the source lives outside `design/`.
+
+```text
+canon connect <Studio URL|/full/snapshot.json> --root <project-root>
+              [--design <existing-custom-path>] [--no-hooks]
+canon init <name> [--preset canon|editorial|vera|clean|dark] [--prefix app]
+                 [--brand '#B4309F'] [--font 'DM Sans'] [--design design]
+canon build [--design design] [--only react,preview]
+canon install [--design design] [--root .] [--no-hooks]
+canon sync [--design design] [--root .] [--no-hooks]
+canon studio --root <project-root> [--design design] [--port 0] [--open]
+canon serve                                  # alias for studio
+canon lint [paths…] [--design design] [--json] [--changed]
+canon check [--design design] [--root .]
+canon mcp [--design design]
+canon add <component-slug> [--design design]
+canon doctor [--design design]
+canon presets
+canon --help
+canon --version
+```
+
+`connect` imports the saved snapshot from `./api/system` beside the connection document, or from a full local JSON path, only when the project has no configured design. Public sites hosted under a path such as `/canon/` retain that path. Otherwise the command reuses the source recorded in `.canon/project.json` without fetching or resetting it. For a legacy installation, discover its source and pass `--design`; never use `init` or a preset as fallback for a failed import.
+
+`init` requires a name and builds automatically. Use `sync` after editing an existing source outside Studio; `init --force` intentionally resets its definitions. `add` imports a missing catalogue component. `hook` accepts the Claude Code edit event on stdin and is normally configured by `install`.
+
+`canon mcp` runs over stdio and is started by the agent client. It refreshes data on the request after a successful build. Agents read the current installed references at the beginning of UI work. `canon lint src app` checks those paths; use the application's actual directories and confirm the report covers the changed files.
+
+A build with `--only` selects optional generators while still generating CSS. Run a complete `canon build` before `canon check`. In CI, check versioned outputs directly; if outputs are generated in CI, build before checking.
+
+## Local CLI reference
+
+The compiler and CLI have zero runtime dependencies and require Node.js **22.18.0 or newer**. A source checkout uses Node's native TypeScript support; packaged versions run compiled JavaScript.
+
+The Studio serves the connection procedure at `./CONNECT.md`, the saved snapshot at `./api/system` and an installable package at `./canon-package.tgz`. The public website exposes those files too. Registry releases use `canon-ds`; a retained archive also supports installations without registry access. A localhost URL works for an agent on the same computer. If the agent runs elsewhere, use the public URL or an address it can reach.
+
+From a source checkout, invoke `node bin/canon.js` directly, or create a short command once:
+
+```bash
+npm link
+canon --version
+```
+
+Then continue in the application's repository. Replace the checkout path when needed.
+
+Presets are `canon` (default), `editorial`, `vera`, `clean` and `dark`. `canon presets` describes their visual directions. Seed options include `--brand`, `--action`, `--font`, `--radius`, `--base`, `--control`, `--canvas`, `--ink`, `--mono`, `--display`, `--shadow-tint`, `--neutral-hue`, `--neutral-chroma` and `--theme`.
+
+Explicit seeds replace corresponding preset defaults. Deliberate token overrides live in `seeds.overrides`; defaults live in `seeds.presetOverrides`. Studio preserves hand-edited token values when changing unrelated seeds.
+
+## What is in the catalog
+
+- **Components** (`src/components/*.ts`, 90): actions (buttons, icon buttons, groups, close, social/app-store), forms (fields, inputs and groups, textarea, select, combobox, multi-select, checkbox, radio, switch, slider, segmented control, pin/number/tags inputs, date picker, color picker, file dropzone, rich text editor), navigation (sidebar family, topbar, header navigation, mobile header, tabs, breadcrumb, pagination, menu, command palette, stepper, page and section headers), data display (badge, badge group, tag, counter, avatar and groups, table, list, description list, stat/metrics, accordion, timeline, kanban, tree view, chart frame, rating, activity feed, messages, account card), feedback (alert, banner, toast, notification, progress bar and circle, spinner, skeleton, empty state, inline CTA, featured card), overlays (tooltip, popover, dialog, drawer), media (featured icon, media frame, carousel, video player, credit card), typography (kicker, prose, link, code, kbd).
+- **Patterns** (`src/patterns/*.ts`): application layouts and pages only — app shell, form layout, dashboard, settings, list with detail drawer, inbox / chat / notification center, onboarding wizard, profile, files, calendar, dialog and drawer flows, phone-width screens, first-run and empty states, billing and checkout, audit log, roles and permissions, auth and error pages — each with 2–6 layout variants, rendered at desktop and 375px in the gallery.
+- **Presets**: `canon` (default), `editorial`, `vera`, `clean`, `dark`.
+
+## Authoring
+
+Components live in `src/components/*.ts` as data (see `docs/AUTHORING.md`). Patterns (layouts, sections, pages) in `src/patterns/*.ts`. `canon init` copies them into a project's `design/` as JSON where they can be edited by hand or in the editor; `canon add <slug>` pulls a new catalog component into an existing project.
+
+## Tests
+
+```bash
+npm ci
+npm test
+npx playwright install chromium
+npm run test:browser
+```
+
+`npm run test:ci` typechecks the source and runs both suites. `npm run build` prepares the compiled `lib/` runtime; `npm pack` runs it automatically. The packaging tests install the tarball in a temporary consumer and exercise the CLI without runtime dependencies.
+
+</details>

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,55 @@
+# Third-party notices
+
+Canon includes inline outline icons in its examples and Studio. Lucide is the recommended product icon set; the applicable Lucide and Feather notices are retained below.
+
+Source: https://github.com/lucide-icons/lucide/blob/main/LICENSE
+
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Fonts and brand examples
+
+The Studio requests selected fonts from Google Fonts. Font binaries are not bundled in the npm package; self-hosted copies retain their respective font licenses.
+
+Company names and logo representations in example components identify those companies. They are not covered by a grant of trademark rights from Canon and do not imply endorsement.

package/bin/canon.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+
+// A checkout runs current source; npm ships only the compiled runtime.
+const source = new URL('../src/cli.ts', import.meta.url);
+await import(existsSync(source) ? source.href : new URL('../lib/cli.mjs', import.meta.url).href);

package/lib/build-manifest.mjs

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { VERSION } from "./version.mjs";
+export const BUILD_GENERATORS = ['css', 'tailwind', 'dtcg', 'react', 'preview', 'designmd', 'agents'];
+export const contentHash = (content) => createHash('sha256').update(content).digest('hex');
+export const sourceHash = (system) => contentHash(JSON.stringify(system));
+/** Manifest paths are portable, output-relative file names, never filesystem paths. */
+export function outputPath(outDir, rel) {
+    const path = resolve(outDir, rel);
+    const within = relative(resolve(outDir), path);
+    if (!rel || rel.includes('\\') || isAbsolute(rel) || within === '' || within === '..' || within.startsWith(`..${sep}`) || isAbsolute(within)) {
+        throw new Error(`Invalid generated file path: ${rel}`);
+    }
+    return path;
+}
+export function checkBuild(system, designDir) {
+    const outDir = join(designDir, system.meta.out || 'dist');
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(join(outDir, 'canon.lock.json'), 'utf8'));
+    }
+    catch (error) {
+        const missing = error.code === 'ENOENT';
+        return { ok: false, issues: [missing ? 'dist not built (missing build manifest).' : 'Build manifest cannot be read.'] };
+    }
+    if (!manifest || manifest.manifestVersion !== 1 || !Array.isArray(manifest.generators)
+        || !manifest.files || typeof manifest.files !== 'object' || Array.isArray(manifest.files)
+        || Object.keys(manifest.files).length === 0) {
+        return { ok: false, issues: ['Build manifest is incomplete or uses an older format.'] };
+    }
+    const issues = [];
+    if (manifest.canon !== VERSION)
+        issues.push(`Compiler version changed (built with ${manifest.canon}, current ${VERSION}).`);
+    if (manifest.sourceHash !== sourceHash(system))
+        issues.push('dist is stale (design source changed since last build).');
+    const missing = BUILD_GENERATORS.filter((name) => !manifest.generators.includes(name));
+    if (missing.length)
+        issues.push(`Build is incomplete; missing generators: ${missing.join(', ')}.`);
+    for (const [rel, expected] of Object.entries(manifest.files)) {
+        try {
+            if (typeof expected !== 'string' || !/^[a-f0-9]{64}$/.test(expected))
+                throw new Error('invalid content hash');
+            const actual = contentHash(readFileSync(outputPath(outDir, rel)));
+            if (actual !== expected)
+                issues.push(`Generated file changed: ${rel}.`);
+        }
+        catch (error) {
+            const code = error.code;
+            issues.push(code === 'ENOENT' ? `Generated file missing: ${rel}.` : `Generated file cannot be verified: ${rel}.`);
+        }
+    }
+    return { ok: issues.length === 0, issues };
+}

package/lib/build.mjs

@@ -0,0 +1,69 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { indexTokens } from "./tokens/resolve.mjs";
+import { componentCss, fullCss, patternsCss } from "./generators/css.mjs";
+import { validateSystem } from "./system.mjs";
+import { VERSION } from "./version.mjs";
+import { contentHash, outputPath, sourceHash } from "./build-manifest.mjs";
+const optional = [
+    { name: 'tailwind', load: () => import("./generators/tailwind.mjs") },
+    { name: 'dtcg', load: () => import("./generators/dtcg.mjs") },
+    { name: 'react', load: () => import("./generators/react.mjs") },
+    { name: 'preview', load: () => import("./generators/preview.mjs") },
+    { name: 'designmd', load: () => import("./generators/designmd.mjs") },
+    { name: 'agents', load: () => import("./generators/agents.mjs") },
+];
+export async function buildSystem(system, designDir, opts = {}) {
+    const v = validateSystem(system);
+    if (v.errors.length)
+        throw new Error(`Design system is invalid:\n  - ${v.errors.join('\n  - ')}`);
+    const idx = indexTokens(system.tokens, system.meta.prefix);
+    const outDir = join(designDir, system.meta.out || 'dist');
+    mkdirSync(outDir, { recursive: true });
+    const files = [];
+    const hashes = {};
+    const generators = [];
+    const warnings = [...v.warnings];
+    const write = (rel, content) => {
+        const p = outputPath(outDir, rel);
+        mkdirSync(join(p, '..'), { recursive: true });
+        writeFileSync(p, content);
+        files.push(p);
+        hashes[rel] = contentHash(content);
+    };
+    const css = fullCss(system, idx);
+    write('tokens.css', css.tokens);
+    write('base.css', css.base);
+    write('components.css', css.components);
+    write(`${system.meta.prefix}.css`, css.all);
+    // Selective imports keep dependencies explicit: tokens, base, components, then patterns.
+    for (const component of system.components) {
+        write(`css/components/${component.slug}.css`, componentCss(component, idx, system.meta.prefix));
+    }
+    for (const pattern of system.patterns) {
+        write(`css/patterns/${pattern.slug}.css`, patternsCss({ ...system, patterns: [pattern] }, idx));
+    }
+    generators.push('css');
+    for (const g of optional) {
+        if (opts.only && !opts.only.includes(g.name))
+            continue;
+        try {
+            const mod = await g.load();
+            await mod.generate(system, idx, write);
+            generators.push(g.name);
+        }
+        catch (e) {
+            const err = e;
+            if (err.code === 'ERR_MODULE_NOT_FOUND') {
+                warnings.push(`generator "${g.name}" not available yet`);
+                continue;
+            }
+            throw new Error(`generator "${g.name}" failed: ${err.stack ?? err.message}`);
+        }
+    }
+    const hash = sourceHash(system);
+    // Certify only this invocation's generators, even if older files remain in dist.
+    const manifest = { manifestVersion: 1, canon: VERSION, system: system.meta.name, version: system.meta.version, sourceHash: hash, builtAt: new Date().toISOString(), components: system.components.length, tokens: idx.size, generators, files: { ...hashes } };
+    write('canon.lock.json', JSON.stringify(manifest, null, 2) + '\n');
+    return { outDir, files, hash, warnings };
+}

package/lib/cli.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+import { resolve, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { VERSION } from "./version.mjs";
+import { PRESETS } from "./tokens/presets.mjs";
+import { findProject } from "./project.mjs";
+const args = process.argv.slice(2);
+const cmd = args[0];
+function flag(name, def) {
+    const i = args.findIndex((a) => a === `--${name}` || a.startsWith(`--${name}=`));
+    if (i === -1)
+        return def;
+    const a = args[i];
+    if (a.includes('='))
+        return a.slice(a.indexOf('=') + 1);
+    const next = args[i + 1];
+    if (next && !next.startsWith('--'))
+        return next;
+    return 'true';
+}
+const has = (name) => args.includes(`--${name}`) || args.some((a) => a.startsWith(`--${name}=`));
+const positional = args.slice(1).filter((a, i, arr) => !a.startsWith('--') && !(arr[i - 1]?.startsWith('--') && !arr[i - 1].includes('=') && !['true', 'false'].includes(a) && isFlagWithValue(arr[i - 1])));
+function isFlagWithValue(f) { return !['--force', '--no-install', '--json', '--quiet', '--fix', '--changed', '--annotate', '--hooks', '--no-hooks', '--open'].includes(f); }
+const rootDir = () => resolve(flag('root') ?? findProject(process.cwd())?.root ?? '.');
+const designDir = () => {
+    const from = flag('root') ? resolve(flag('root')) : process.cwd();
+    if (flag('design'))
+        return resolve(from, flag('design'));
+    const project = findProject(from);
+    if (project)
+        return project.design;
+    return existsSync(join(from, 'system.json')) ? from : join(from, 'design');
+};
+const HELP = `canon ${VERSION} — design systems that AI agents cannot get wrong.
+
+Usage
+  canon connect <studio-url|snapshot.json> [--root .] [--design design] [--no-hooks]
+                                           Import the saved design or reuse this project's existing Canon
+  canon init <name> [--preset canon|editorial|vera|clean|dark] [--prefix cn] [--brand #hex] [--action #hex]
+             [--font "Geist"] [--radius 1] [--base 14] [--control 36] [--design design] [--force]
+  canon build [--design design]            Compile tokens → css, tailwind, react, gallery, DESIGN.md, agent files
+  canon install [--design design] [--root .] [--no-hooks]
+                                           Put DESIGN.md, AGENTS.md/CLAUDE.md blocks, skill, cursor rules, MCP config and lint hook in a project
+  canon sync                               build + install
+  canon lint [paths…] [--design design] [--json] [--changed]
+                                           Find raw colors/sizes/fonts/tailwind palette classes outside the system
+  canon check                              Fail if dist is stale or lint fails (CI / pre-commit)
+  canon mcp [--design design]              MCP server (stdio) exposing tokens, components, rules and lint to any agent
+  canon add <component-slug>               Add a catalog component missing from the design dir
+  canon presets                            List presets
+  canon studio [--root .] [--port 4600] [--open]
+                                           Edit this project's design and save its styles and agent references
+  canon serve                              Alias for studio
+  canon doctor                             Sanity-check a design dir
+
+Examples
+  canon init "Vera" --preset vera --prefix vera && canon install
+  canon lint src app
+  canon mcp --design ./design   (register in .mcp.json; canon install does it)
+`;
+async function main() {
+    switch (cmd) {
+        case 'connect': {
+            const { connect } = await import("./connect.mjs");
+            const result = await connect(positional[0], { root: rootDir(), design: flag('design'), hooks: !has('no-hooks') });
+            console.log(`✓ ${result.reused ? 'Reused existing design' : 'Imported saved Studio design'} → ${result.design}`);
+            for (const line of result.log)
+                console.log(line);
+            console.log('Start this project’s Studio: canon studio --port 0 --open');
+            return;
+        }
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            console.log(HELP);
+            return;
+        case '--version':
+        case '-v':
+        case 'version':
+            console.log(VERSION);
+            return;
+        case 'presets': {
+            for (const p of Object.values(PRESETS))
+                console.log(`${p.id.padEnd(9)} ${p.label}\n${''.padEnd(10)}${p.direction.summary}\n`);
+            return;
+        }
+        case 'init': {
+            const { createSystem, writeDesignDir } = await import("./system.mjs");
+            const { buildSystem } = await import("./build.mjs");
+            const name = positional[0] ?? flag('name');
+            if (!name) {
+                console.error('canon init <name> — a name is required.');
+                process.exit(2);
+            }
+            const dir = resolve(flag('design', 'design'));
+            if (existsSync(join(dir, 'system.json')) && !has('force')) {
+                console.error(`${dir}/system.json already exists. Use --force to overwrite (components you customized will be reset).`);
+                process.exit(2);
+            }
+            const num = (n) => (flag(n) !== undefined ? Number(flag(n)) : undefined);
+            const system = await createSystem({
+                name,
+                prefix: flag('prefix'),
+                preset: flag('preset', 'canon'),
+                description: flag('description'),
+                seeds: {
+                    brand: flag('brand'), action: flag('action'),
+                    fontSans: flag('font'), fontMono: flag('mono'), fontDisplay: flag('display'),
+                    radiusScale: num('radius'), baseFontSize: num('base'), controlHeight: num('control'),
+                    canvasLight: flag('canvas'), inkDark: flag('ink'), shadowTint: flag('shadow-tint'),
+                    neutralHue: num('neutral-hue'), neutralChroma: num('neutral-chroma'),
+                    defaultTheme: flag('theme'),
+                },
+            });
+            const written = writeDesignDir(system, dir);
+            console.log(`✓ ${system.meta.name} (prefix "${system.meta.prefix}", preset ${flag('preset', 'canon')}) → ${dir}`);
+            console.log(`  ${written.length} source files: system.json, tokens.json, ${system.components.length} components, ${system.patterns.length} patterns`);
+            const r = await buildSystem(system, dir);
+            report(r);
+            console.log(`\nNext: open ${join(r.outDir, 'preview.html')} to see everything, then \`canon install\` to wire agents.`);
+            return;
+        }
+        case 'build': {
+            const { loadDesignDir } = await import("./system.mjs");
+            const { buildSystem } = await import("./build.mjs");
+            const dir = designDir();
+            const system = loadDesignDir(dir);
+            const r = await buildSystem(system, dir, { only: flag('only')?.split(',') });
+            report(r);
+            return;
+        }
+        case 'install':
+        case 'sync': {
+            const { loadDesignDir } = await import("./system.mjs");
+            const { buildSystem } = await import("./build.mjs");
+            const { install } = await import("./install.mjs");
+            const dir = designDir();
+            const system = loadDesignDir(dir);
+            if (cmd === 'sync')
+                report(await buildSystem(system, dir));
+            const res = install(system, dir, { root: rootDir(), hooks: !has('no-hooks') });
+            for (const l of res.log)
+                console.log(l);
+            return;
+        }
+        case 'lint': {
+            const { runLint, formatReport } = await import("./lint.mjs");
+            const { loadDesignDir } = await import("./system.mjs");
+            const dir = designDir();
+            const system = loadDesignDir(dir);
+            const paths = positional.length ? positional : undefined;
+            const res = await runLint(system, dir, { paths, root: rootDir(), changed: has('changed') });
+            if (has('json'))
+                console.log(JSON.stringify(res, null, 2));
+            else
+                console.log(formatReport(res));
+            process.exit(res.violations.filter((v) => v.severity === 'error').length ? 1 : 0);
+        }
+        case 'check': {
+            const { loadDesignDir } = await import("./system.mjs");
+            const { runLint, formatReport } = await import("./lint.mjs");
+            const { checkBuild } = await import("./build-manifest.mjs");
+            const dir = designDir();
+            const system = loadDesignDir(dir);
+            const build = checkBuild(system, dir);
+            let ok = build.ok;
+            if (build.ok)
+                console.log('✓ dist is up to date (all generators and file hashes verified)');
+            else {
+                for (const issue of build.issues)
+                    console.log(`✗ ${issue}`);
+                console.log('  Run `canon build` to rebuild all artifacts.');
+            }
+            const res = await runLint(system, dir, { root: rootDir() });
+            console.log(formatReport(res));
+            if (res.violations.some((v) => v.severity === 'error'))
+                ok = false;
+            process.exit(ok ? 0 : 1);
+        }
+        case 'hook': {
+            // Claude Code PostToolUse hook: lint the edited file; exit 2 + stderr feeds violations back to the agent.
+            const { runLint, formatReport } = await import("./lint.mjs");
+            const { loadDesignDir } = await import("./system.mjs");
+            const chunks = [];
+            for await (const c of process.stdin)
+                chunks.push(c);
+            let file;
+            try {
+                const j = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                file = j.tool_input?.file_path ?? j.tool_input?.path;
+            }
+            catch { /* ignore */ }
+            if (!file || !existsSync(file) || !/\.(css|scss|less|tsx|jsx|ts|js|mjs|html|vue|svelte|astro|mdx)$/.test(file))
+                return;
+            const dir = designDir();
+            const system = loadDesignDir(dir);
+            const res = await runLint(system, dir, { paths: [file], root: process.cwd() });
+            if (res.summary.errors) {
+                console.error(`canon lint found ${res.summary.errors} design-system violation(s) in ${file}. Fix them using tokens/components from DESIGN.md:\n` + formatReport(res));
+                process.exit(2);
+            }
+            return;
+        }
+        case 'mcp': {
+            const { startMcp } = await import("./mcp.mjs");
+            await startMcp(designDir());
+            return;
+        }
+        case 'add': {
+            const { loadDesignDir } = await import("./system.mjs");
+            const { loadCatalog } = await import("./components/index.mjs");
+            const CATALOG = await loadCatalog();
+            const { writeFileSync } = await import('node:fs');
+            const dir = designDir();
+            const system = loadDesignDir(dir);
+            const slug = positional[0];
+            const spec = CATALOG.find((c) => c.slug === slug);
+            if (!spec) {
+                console.error(`Unknown component "${slug}". Available: ${CATALOG.map((c) => c.slug).join(', ')}`);
+                process.exit(2);
+            }
+            if (system.components.some((c) => c.slug === slug) && !has('force')) {
+                console.error(`${slug} already exists in ${dir}/components. Use --force to reset it.`);
+                process.exit(2);
+            }
+            writeFileSync(join(dir, 'components', `${slug}.json`), JSON.stringify(spec, null, 2) + '\n');
+            console.log(`✓ added components/${slug}.json — run canon build`);
+            return;
+        }
+        case 'serve':
+        case 'studio': {
+            const { serve } = await import("./serve.mjs");
+            const { loadDesignDir } = await import("./system.mjs");
+            const dir = designDir();
+            const system = loadDesignDir(dir);
+            const project = findProject(rootDir()) ?? findProject(dir);
+            const { realpathSync } = await import('node:fs');
+            const projectRoot = project && realpathSync(project.design) === realpathSync(dir) ? project.root : undefined;
+            await serve(join(dir, system.meta.out || 'dist'), Number(flag('port', '4600')), dir, { projectRoot, open: has('open') });
+            return;
+        }
+        case 'doctor': {
+            const { loadDesignDir, validateSystem } = await import("./system.mjs");
+            const dir = designDir();
+            const system = loadDesignDir(dir);
+            const v = validateSystem(system);
+            for (const w of v.warnings)
+                console.log(`  ! ${w}`);
+            if (v.errors.length) {
+                console.log(`✗ ${v.errors.length} problem(s):\n  - ${v.errors.join('\n  - ')}`);
+                process.exit(1);
+            }
+            console.log(`✓ ${system.meta.name}: ${system.components.length} components, ${system.patterns.length} patterns, tokens ok`);
+            return;
+        }
+        default:
+            console.error(`Unknown command "${cmd}".\n`);
+            console.log(HELP);
+            process.exit(2);
+    }
+}
+function report(r) {
+    console.log(`✓ built ${r.files.length} files → ${r.outDir}`);
+    for (const w of r.warnings)
+        console.log(`  ! ${w}`);
+}
+main().catch((e) => {
+    console.error(`✗ ${e.message}`);
+    if (process.env.CANON_DEBUG)
+        console.error(e.stack);
+    process.exit(1);
+});