@getvitops/cli 0.4.0 → 0.6.0

package/README.md

@@ -23,7 +23,8 @@ npx vitops generate --format bricks,css --out dist
 | `vitops validate <file>`                           | schema-check (non-zero exit on error)         |
 | `vitops generate -i <file> -f <formats> -o <dir>`  | generate `bricks` / `css` / `tailwind` output |
 | `vitops favicon -i <svg\|png> -o <dir>`            | generate a favicon set from a source image    |
-| `vitops agents [-o AGENTS.md] [--docs-dir <dir>]`  | teach AI agents about the design system       |
+| `vitops agents [-o AGENTS.md] [--docs-dir <dir>]`  | link the agent skill + AGENTS.md pointer      |
+| `vitops docs [topic] [--all]`                      | print live reference docs to stdout           |
 
 ## Using the output
 
@@ -79,22 +80,36 @@ The CLI only writes files — how they reach WordPress is up to you:
 - **CI:** run `vitops generate --format bricks` in your pipeline and deploy the artifact the
   same way you deploy the rest of the theme.
 
-## Teaching AI agents (`vitops agents`)
+## Teaching AI agents (`vitops agents` + `vitops docs`)
 
-So an AI coding agent in a consumer project can discover the design system, `vitops agents`
-writes a small, marker-delimited **managed block** into your `AGENTS.md` (idempotent — re-run to
-update) and emits the reference docs bundle it points at:
+This package **ships an agent skill** (`skill/SKILL.md`, the [Agent Skills](https://code.claude.com/docs/en/skills)
+format) that teaches AI coding agents to fetch design-system context on demand. Nothing is
+generated into your repo — reference docs print live via `vitops docs`:
 
 ```sh
-vitops agents                                   # updates ./AGENTS.md, docs → ./.vitops/docs
-vitops agents --out CLAUDE.md --docs-dir docs/vitops --input design-system.json
+vitops docs                # list topics
+vitops docs classes        # the class vocabulary, rendered from YOUR design-system.json
+vitops docs authoring      # every config field, from the JSON Schema
+vitops docs formats        # tailwind vs css vs bricks (incl. which utilities Tailwind owns)
 ```
 
-The block lists the CLI commands and points at the generated class vocabulary
-(`<docs-dir>/css/classes.md`) and Bricks element reference (`<docs-dir>/bricks/elements.md`), both
-derived from your `design-system.json`. Re-running only replaces the content between the
-`<!-- vitops:start -->` / `<!-- vitops:end -->` markers, leaving the rest of the file untouched. If
-you'd rather not commit the generated docs, add your `--docs-dir` (e.g. `.vitops/`) to
-`.gitignore` and run `vitops agents` in a postinstall/CI step.
+Because output is rendered at call time from your config + the installed package version, it is
+never stale. `vitops agents` wires up discovery:
+
+```sh
+vitops agents                                   # links the skill + updates ./AGENTS.md
+vitops agents --out CLAUDE.md                   # different pointer file
+```
+
+It symlinks `.agents/skills/vitops-design-system` and `.claude/skills/vitops-design-system` to the
+skill inside the installed package (the links target the logical `node_modules/@getvitops/cli/skill`
+path, so they survive version bumps and reinstalls — re-run only if you delete them), and writes a
+marker-delimited **managed block** into your `AGENTS.md` listing the CLI commands and `vitops docs`
+topics. Re-running only replaces the content between the `<!-- vitops:start -->` /
+`<!-- vitops:end -->` markers.
+
+Prefer materialized files (offline/CI contexts, or agents that can't run commands)? The legacy
+layout still works: `vitops agents --docs-dir .vitops/docs` writes the full docs bundle as files
+and points the AGENTS.md block at them (no skill link).
 
 Powered by [`@getvitops/generator`](https://www.npmjs.com/package/@getvitops/generator).

package/dist/cli.mjs

@@ -1,11 +1,100 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { parseArgs } from "node:util";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, parse, relative, resolve } from "node:path";
 import { SCHEMA_URL, defaultConfig, generate, generateDocs, validate } from "@getvitops/generator";
 import { generateFavicons } from "@getvitops/utils";
 
+//#region src/agents.ts
+/**
+* Side-effect-free helpers for the `vitops agents` / `vitops docs` commands.
+* Kept out of cli.ts (which runs main() on import) so they are unit-testable.
+*/
+const SKILL_NAME = "vitops-design-system";
+/** Marker the 0.5.0-era generated skill carried; lets us migrate that layout. */
+const GENERATED_MARKER = "<!-- GENERATED by @getvitops/cli";
+/**
+* `vitops docs` topics → docs-bundle paths (as returned by `generateDocs`).
+* Order is the `--all` concatenation order.
+*/
+const TOPICS = {
+	classes: {
+		path: "css/classes.md",
+		summary: "CSS framework class vocabulary (colour, type, space, layout, animation, patterns)"
+	},
+	authoring: {
+		path: "authoring.md",
+		summary: "every design-system.json field, rendered from the JSON Schema"
+	},
+	formats: {
+		path: "formats.md",
+		summary: "tailwind vs css vs bricks: what's emitted vs what the platform provides"
+	},
+	color: {
+		path: "concepts/color.md",
+		summary: "seeded OKLCH scales, functional tokens, automatic dark mode"
+	},
+	scales: {
+		path: "concepts/scales.md",
+		summary: "fluid modular type & space scales"
+	},
+	patterns: {
+		path: "concepts/patterns.md",
+		summary: "pattern CSS: token cascade, override hooks, states, role variants"
+	},
+	elements: {
+		path: "bricks/elements.md",
+		summary: "Bricks Builder custom elements, controls, defaults"
+	}
+};
+/**
+* Find the installed package's skill directory by walking up from `cwd` looking
+* for `node_modules/@getvitops/cli/skill/SKILL.md`. Returns the LOGICAL path
+* (through the `node_modules/@getvitops/cli` link, unresolved) or null.
+*
+* Deliberately not derived from import.meta.url: under pnpm the running module's
+* URL is the realpath in `node_modules/.pnpm/@getvitops+cli@<version>/…`, which
+* changes on every version bump — a symlink to it would dangle after upgrades.
+* The logical path is recreated by the package manager on every install, so a
+* link through it always resolves to the currently installed version.
+*/
+function findSkillTarget(cwd) {
+	let dir = resolve(cwd);
+	const { root } = parse(dir);
+	for (;;) {
+		const skillDir = join(dir, "node_modules", "@getvitops", "cli", "skill");
+		if (existsSync(join(skillDir, "SKILL.md"))) return skillDir;
+		if (dir === root) return null;
+		dir = dirname(dir);
+	}
+}
+/**
+* Idempotently symlink `linkPath` → `targetDir` (relative target). Replaces a
+* stale symlink; migrates a real directory left by the old emitting `vitops
+* agents` (identified by GENERATED_MARKER in its SKILL.md); refuses to clobber
+* anything else. Returns a warning string, or null on success / no-op.
+*/
+function linkSkill(linkPath, targetDir) {
+	const target = relative(dirname(linkPath), resolve(targetDir));
+	try {
+		const st = lstatSync(linkPath, { throwIfNoEntry: false });
+		if (st && !st.isSymbolicLink()) {
+			const oldSkill = join(linkPath, "SKILL.md");
+			if (!(st.isDirectory() && existsSync(oldSkill) && readFileSync(oldSkill, "utf8").includes("<!-- GENERATED by @getvitops/cli"))) return `left ${linkPath} alone (exists and is not a symlink) — link it to ${targetDir} yourself if wanted`;
+			rmSync(linkPath, { recursive: true });
+		} else if (st) {
+			if (readlinkSync(linkPath) === target) return null;
+			rmSync(linkPath);
+		} else mkdirSync(dirname(linkPath), { recursive: true });
+		symlinkSync(target, linkPath);
+		return null;
+	} catch (err) {
+		return `could not symlink ${linkPath}: ${err.message}`;
+	}
+}
+
+//#endregion
 //#region src/cli.ts
 /**
 * `vitops` — CLI for the Vitops design-system generator.
@@ -15,6 +104,7 @@ import { generateFavicons } from "@getvitops/utils";
 *   vitops validate  <design-system.json>
 *   vitops favicon   --input <svg|png> --out <dir> [--low-res <svg|png>]
 *   vitops agents    [--input <json>] [--out AGENTS.md] [--docs-dir <dir>]
+*   vitops docs      [topic] [--input <json>] [--all]
 *
 * Thin wrapper over @getvitops/generator (generation) and @getvitops/utils (favicons).
 * Every client brings their own consumer-editable design-system.json.
@@ -31,7 +121,8 @@ Usage:
   vitops init [options]         Scaffold a starter design-system.json
   vitops validate <file>        Validate a config against the schema
   vitops favicon [options]      Generate a favicon set from a source image
-  vitops agents [options]       Write design-system docs into AGENTS.md (for AI agents)
+  vitops agents [options]       Link the design-system agent skill + AGENTS.md pointer
+  vitops docs [topic]           Print live design-system reference docs to stdout
 
 Generate options:
   -i, --input <path>    Config file (default: ./design-system.json)
@@ -48,9 +139,16 @@ Favicon options:
       --low-res <path>  Optional simplified source for the 16px icon
 
 Agents options:
-  -i, --input <path>    Config file (default: ./design-system.json)
+  -i, --input <path>    Config file (default: ./design-system.json; validated if present)
   -o, --out <path>      Doc file to update, idempotently (default: ./AGENTS.md)
-      --docs-dir <dir>  Where to write the reference docs bundle (default: ./.vitops/docs)
+      --docs-dir <dir>  Legacy layout: write the docs bundle as files to this dir
+                        instead of linking the packaged skill
+
+Docs options:
+  <topic>               classes | authoring | formats | color | scales | patterns | elements
+                        (no topic: list topics with summaries)
+  -i, --input <path>    Config file (default: ./design-system.json)
+      --all             Print every topic, concatenated
 
 Common:
   -h, --help            Show this help
@@ -204,6 +302,34 @@ function generatorAssetsDir() {
 }
 const AGENTS_START = "<!-- vitops:start -->";
 const AGENTS_END = "<!-- vitops:end -->";
+/** Print a live reference doc (rendered from the project's config) to stdout. */
+function cmdDocs(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		options: {
+			input: {
+				type: "string",
+				short: "i",
+				default: "design-system.json"
+			},
+			all: {
+				type: "boolean",
+				default: false
+			}
+		},
+		allowPositionals: true
+	});
+	const topic = positionals[0];
+	const topicList = () => Object.entries(TOPICS).map(([name, t]) => `  ${name.padEnd(10)} ${t.summary}`).join("\n");
+	if (!topic && !values.all) {
+		console.log(`vitops docs <topic> — print a live design-system reference to stdout\n\nTopics:\n${topicList()}\n\nAlso: vitops docs --all (every topic, concatenated)`);
+		return;
+	}
+	if (topic && !TOPICS[topic]) fail(`unknown topic "${topic}". Valid topics:\n${topicList()}`);
+	const docs = generateDocs(loadConfig(resolve(values.input)), generatorAssetsDir());
+	const paths = values.all ? Object.values(TOPICS).map((t) => t.path) : [TOPICS[topic].path];
+	process.stdout.write(paths.map((p) => docs[p]).join("\n"));
+}
 function cmdAgents(argv) {
 	const { values } = parseArgs({
 		args: argv,
@@ -218,26 +344,57 @@ function cmdAgents(argv) {
 				short: "o",
 				default: "AGENTS.md"
 			},
-			"docs-dir": {
-				type: "string",
-				default: ".vitops/docs"
-			}
+			"docs-dir": { type: "string" }
 		},
 		allowPositionals: false
 	});
 	const inputRel = values.input;
-	const ds = loadConfig(resolve(inputRel));
-	const docsDir = values["docs-dir"];
-	let docs = {};
-	try {
-		docs = generateDocs(ds, generatorAssetsDir());
-	} catch (err) {
-		fail(`could not generate docs: ${err.message}`);
-	}
-	for (const [rel, content] of Object.entries(docs)) {
-		const p = resolve(docsDir, rel);
-		mkdirSync(dirname(p), { recursive: true });
-		writeFileSync(p, content);
+	let ds = null;
+	if (existsSync(resolve(inputRel))) ds = loadConfig(resolve(inputRel));
+	else console.warn(`  ⚠ ${inputRel} not found — run \`vitops init\` to scaffold one`);
+	const legacyDocsDir = values["docs-dir"];
+	let summary;
+	let pointer;
+	if (legacyDocsDir) {
+		if (!ds) fail(`--docs-dir needs a config to render docs from (${inputRel} not found)`);
+		let docs = {};
+		try {
+			docs = generateDocs(ds, generatorAssetsDir());
+		} catch (err) {
+			fail(`could not generate docs: ${err.message}`);
+		}
+		for (const [rel, content] of Object.entries(docs)) {
+			const p = resolve(legacyDocsDir, rel);
+			mkdirSync(dirname(p), { recursive: true });
+			writeFileSync(p, content);
+		}
+		summary = `wrote ${Object.keys(docs).length} docs to ${legacyDocsDir}/`;
+		pointer = [
+			"Prefer the framework’s utility + component classes over hand-written CSS.",
+			`Reference docs (regenerate with \`vitops agents --docs-dir ${legacyDocsDir}\`): \`${legacyDocsDir}/css/classes.md\`,`,
+			`\`${legacyDocsDir}/authoring.md\`, \`${legacyDocsDir}/formats.md\`, \`${legacyDocsDir}/bricks/elements.md\`.`
+		];
+	} else {
+		const target = findSkillTarget(process.cwd());
+		if (target) {
+			for (const dir of [".agents", ".claude"]) {
+				const warn = linkSkill(resolve(dir, "skills", SKILL_NAME), target);
+				if (warn) console.warn(`  ⚠ ${warn}`);
+			}
+			summary = `linked {.agents,.claude}/skills/${SKILL_NAME} → ${target}`;
+		} else {
+			console.warn(`  ⚠ could not find node_modules/@getvitops/cli/skill — install @getvitops/cli as a devDependency, then re-run \`vitops agents\``);
+			summary = "no skill linked";
+		}
+		pointer = [
+			"Prefer the framework’s utility + component classes over hand-written CSS.",
+			`Full design-system context lives in the \`${SKILL_NAME}\` skill (linked from`,
+			"`.agents/skills/` and `.claude/skills/` into the installed `@getvitops/cli`;",
+			"re-link with `vitops agents` if the links are deleted — they survive version",
+			"bumps). Reference docs print live, from this project’s config, via:",
+			"",
+			...Object.entries(TOPICS).map(([name, t]) => `- \`vitops docs ${name}\` — ${t.summary}`)
+		];
 	}
 	const block = [
 		AGENTS_START,
@@ -251,9 +408,7 @@ function cmdAgents(argv) {
 		"- `vitops generate --format bricks --out <theme>/dist` — WordPress / Bricks",
 		"- `vitops init` · `vitops validate` · `vitops favicon`",
 		"",
-		"Prefer the framework’s utility + component classes over hand-written CSS.",
-		`Full class vocabulary + Bricks element reference: \`${docsDir}/css/classes.md\`,`,
-		`\`${docsDir}/bricks/elements.md\` (regenerate both with \`vitops agents\`).`,
+		...pointer,
 		"",
 		`<!-- regenerate: vitops agents · @getvitops/cli@${cliVersion()} -->`,
 		AGENTS_END
@@ -278,7 +433,7 @@ function cmdAgents(argv) {
 		action = "created";
 	}
 	writeFileSync(outPath, next);
-	console.log(`✓ ${action} ${values.out} + wrote ${Object.keys(docs).length} docs to ${docsDir}/`);
+	console.log(`✓ ${action} ${values.out} + ${summary}`);
 }
 async function main() {
 	const [command, ...rest] = process.argv.slice(2);
@@ -292,7 +447,8 @@ async function main() {
 		case "validate": return cmdValidate(rest);
 		case "favicon": return cmdFavicon(rest);
 		case "agents": return cmdAgents(rest);
-		default: fail(`unknown command "${command}" (expected: generate | init | validate | favicon | agents). Try: vitops --help`);
+		case "docs": return cmdDocs(rest);
+		default: fail(`unknown command "${command}" (expected: generate | init | validate | favicon | agents | docs). Try: vitops --help`);
 	}
 }
 main().catch((err) => fail(err.message));

package/dist/cli.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * `vitops` — CLI for the Vitops design-system generator.\n *\n *   vitops generate  --input <json> --format <bricks|css|tailwind[,…]> --out <dir>\n *   vitops init      [--out design-system.json] [--force]\n *   vitops validate  <design-system.json>\n *   vitops favicon   --input <svg|png> --out <dir> [--low-res <svg|png>]\n *   vitops agents    [--input <json>] [--out AGENTS.md] [--docs-dir <dir>]\n *\n * Thin wrapper over @getvitops/generator (generation) and @getvitops/utils (favicons).\n * Every client brings their own consumer-editable design-system.json.\n */\nimport { parseArgs } from 'node:util';\nimport { writeFileSync, existsSync, readFileSync, mkdirSync } from 'node:fs';\nimport { resolve, join, dirname } from 'node:path';\nimport { createRequire } from 'node:module';\nimport {\n  generate,\n  validate,\n  defaultConfig,\n  generateDocs,\n  SCHEMA_URL,\n  type Format,\n  type DesignSystem,\n} from '@getvitops/generator';\nimport { generateFavicons } from '@getvitops/utils';\n\nconst FORMATS = new Set<Format>(['bricks', 'css', 'tailwind']);\n\nconst HELP = `vitops — generate design-system outputs from a design-system.json\n\nUsage:\n  vitops generate [options]     Generate platform output from a config\n  vitops init [options]         Scaffold a starter design-system.json\n  vitops validate <file>        Validate a config against the schema\n  vitops favicon [options]      Generate a favicon set from a source image\n  vitops agents [options]       Write design-system docs into AGENTS.md (for AI agents)\n\nGenerate options:\n  -i, --input <path>    Config file (default: ./design-system.json)\n  -f, --format <list>   bricks | css | tailwind (comma-separated; default: bricks)\n  -o, --out <dir>       Output directory (default: ./dist)\n\nInit options:\n  -o, --out <path>      Where to write (default: ./design-system.json)\n      --force           Overwrite an existing file\n\nFavicon options:\n  -i, --input <path>    Source SVG or PNG (required)\n  -o, --out <dir>       Output directory (default: ./public)\n      --low-res <path>  Optional simplified source for the 16px icon\n\nAgents options:\n  -i, --input <path>    Config file (default: ./design-system.json)\n  -o, --out <path>      Doc file to update, idempotently (default: ./AGENTS.md)\n      --docs-dir <dir>  Where to write the reference docs bundle (default: ./.vitops/docs)\n\nCommon:\n  -h, --help            Show this help\n`;\n\nfunction fail(msg: string): never {\n  console.error(`✖ ${msg}`);\n  process.exit(1);\n}\n\nasync function cmdGenerate(argv: string[]) {\n  const { values } = parseArgs({\n    args: argv,\n    options: {\n      input: { type: 'string', short: 'i', default: 'design-system.json' },\n      format: { type: 'string', short: 'f', default: 'bricks' },\n      out: { type: 'string', short: 'o', default: 'dist' },\n    },\n    allowPositionals: false,\n  });\n  const input = resolve(values.input as string);\n  if (!existsSync(input)) fail(`config not found: ${input}`);\n  const formats = (values.format as string)\n    .split(',')\n    .map((f) => f.trim())\n    .filter(Boolean);\n  for (const f of formats)\n    if (!FORMATS.has(f as Format))\n      fail(`unknown format \"${f}\" (expected: bricks | css | tailwind)`);\n\n  for (const format of formats as Format[]) {\n    try {\n      const res = await generate({ input, format, outDir: values.out as string });\n      console.log(`✓ ${format} → ${res.outDir} (${res.written.length} paths)`);\n    } catch (err) {\n      fail((err as Error).message);\n    }\n  }\n}\n\nfunction cmdInit(argv: string[]) {\n  const { values } = parseArgs({\n    args: argv,\n    options: {\n      out: { type: 'string', short: 'o', default: 'design-system.json' },\n      force: { type: 'boolean', default: false },\n    },\n    allowPositionals: false,\n  });\n  const out = resolve(values.out as string);\n  if (existsSync(out) && !values.force) fail(`${out} already exists (use --force to overwrite)`);\n  writeFileSync(out, JSON.stringify(defaultConfig(), null, 2) + '\\n');\n  console.log(`✓ wrote ${out}`);\n  console.log(\n    `  Edit it, then: vitops generate --input ${values.out} --format tailwind --out src/styles`,\n  );\n  console.log(`  Editors read the \"$schema\" (${SCHEMA_URL}) for autocomplete + validation.`);\n}\n\nfunction cmdValidate(argv: string[]) {\n  const { values, positionals } = parseArgs({\n    args: argv,\n    options: { input: { type: 'string', short: 'i' } },\n    allowPositionals: true,\n  });\n  const path = resolve((positionals[0] ?? values.input ?? 'design-system.json') as string);\n  if (!existsSync(path)) fail(`config not found: ${path}`);\n  let raw: unknown;\n  try {\n    raw = JSON.parse(readFileSync(path, 'utf8'));\n  } catch (err) {\n    fail(`could not parse JSON: ${(err as Error).message}`);\n  }\n  const result = validate(raw);\n  if (result.ok) {\n    console.log(`✓ ${path} is valid`);\n    return;\n  }\n  console.error(`✖ ${path} is invalid:`);\n  for (const e of result.errors) console.error(`  • ${e.path.join('.') || '(root)'}: ${e.message}`);\n  process.exit(1);\n}\n\nasync function cmdFavicon(argv: string[]) {\n  const { values } = parseArgs({\n    args: argv,\n    options: {\n      input: { type: 'string', short: 'i' },\n      out: { type: 'string', short: 'o', default: 'public' },\n      'low-res': { type: 'string' },\n    },\n    allowPositionals: false,\n  });\n  if (!values.input) fail('favicon: --input <svg|png> is required');\n  const source = resolve(values.input as string);\n  if (!existsSync(source)) fail(`source not found: ${source}`);\n  try {\n    const written = await generateFavicons({\n      source,\n      outputDir: values.out as string,\n      ...(values['low-res'] ? { lowResSource: resolve(values['low-res'] as string) } : {}),\n    });\n    console.log(`✓ favicons → ${values.out} (${written.length} files)`);\n  } catch (err) {\n    fail((err as Error).message);\n  }\n}\n\n// Read + parse + validate a design-system.json, or exit with a message.\nfunction loadConfig(path: string): DesignSystem {\n  if (!existsSync(path)) fail(`config not found: ${path}`);\n  let raw: unknown;\n  try {\n    raw = JSON.parse(readFileSync(path, 'utf8'));\n  } catch (err) {\n    fail(`could not parse JSON: ${(err as Error).message}`);\n  }\n  const result = validate(raw);\n  if (!result.ok) {\n    console.error(`✖ ${path} is invalid:`);\n    for (const e of result.errors)\n      console.error(`  • ${e.path.join('.') || '(root)'}: ${e.message}`);\n    process.exit(1);\n  }\n  return result.data;\n}\n\n// This CLI's own version (dist/cli.mjs → package-root package.json).\nfunction cliVersion(): string {\n  try {\n    return (\n      JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version ??\n      '0.0.0'\n    );\n  } catch {\n    return '0.0.0';\n  }\n}\n\n// The framework asset root shipped inside @getvitops/generator (holds the Bricks\n// PHP that generateDocs reads for the element reference).\nfunction generatorAssetsDir(): string {\n  const pkg = createRequire(import.meta.url).resolve('@getvitops/generator/package.json');\n  return join(dirname(pkg), 'assets');\n}\n\nconst AGENTS_START = '<!-- vitops:start -->';\nconst AGENTS_END = '<!-- vitops:end -->';\n\nfunction cmdAgents(argv: string[]) {\n  const { values } = parseArgs({\n    args: argv,\n    options: {\n      input: { type: 'string', short: 'i', default: 'design-system.json' },\n      out: { type: 'string', short: 'o', default: 'AGENTS.md' },\n      'docs-dir': { type: 'string', default: '.vitops/docs' },\n    },\n    allowPositionals: false,\n  });\n  const inputRel = values.input as string;\n  const ds = loadConfig(resolve(inputRel));\n  const docsDir = values['docs-dir'] as string;\n\n  // Emit the OKF docs bundle so the AGENTS.md pointer resolves for every consumer\n  // (only the `bricks` generate format writes docs/ otherwise).\n  let docs: Record<string, string> = {};\n  try {\n    docs = generateDocs(ds, generatorAssetsDir());\n  } catch (err) {\n    fail(`could not generate docs: ${(err as Error).message}`);\n  }\n  for (const [rel, content] of Object.entries(docs)) {\n    const p = resolve(docsDir, rel);\n    mkdirSync(dirname(p), { recursive: true });\n    writeFileSync(p, content);\n  }\n\n  const block = [\n    AGENTS_START,\n    '## Vitops design system',\n    '',\n    `Styled with the Vitops design system (\\`@getvitops/*\\`); tokens live in \\`${inputRel}\\`.`,\n    'Generate output with the CLI:',\n    '',\n    '- `vitops generate --format tailwind --out src/styles` — Tailwind v4 / Astro',\n    '- `vitops generate --format css --out dist` — standalone CSS',\n    '- `vitops generate --format bricks --out <theme>/dist` — WordPress / Bricks',\n    '- `vitops init` · `vitops validate` · `vitops favicon`',\n    '',\n    'Prefer the framework’s utility + component classes over hand-written CSS.',\n    `Full class vocabulary + Bricks element reference: \\`${docsDir}/css/classes.md\\`,`,\n    `\\`${docsDir}/bricks/elements.md\\` (regenerate both with \\`vitops agents\\`).`,\n    '',\n    `<!-- regenerate: vitops agents · @getvitops/cli@${cliVersion()} -->`,\n    AGENTS_END,\n  ].join('\\n');\n\n  const outPath = resolve(values.out as string);\n  let next: string;\n  let action: string;\n  if (existsSync(outPath)) {\n    const cur = readFileSync(outPath, 'utf8');\n    const s = cur.indexOf(AGENTS_START);\n    const e = cur.indexOf(AGENTS_END);\n    if (s !== -1 && e !== -1 && e > s) {\n      next = cur.slice(0, s) + block + cur.slice(e + AGENTS_END.length);\n      action = 'updated block in';\n    } else {\n      next = cur.replace(/\\s*$/, '') + '\\n\\n' + block + '\\n';\n      action = 'appended block to';\n    }\n  } else {\n    mkdirSync(dirname(outPath), { recursive: true });\n    next = block + '\\n';\n    action = 'created';\n  }\n  writeFileSync(outPath, next);\n  console.log(`✓ ${action} ${values.out} + wrote ${Object.keys(docs).length} docs to ${docsDir}/`);\n}\n\nasync function main() {\n  const [command, ...rest] = process.argv.slice(2);\n  if (!command || command === '-h' || command === '--help' || command === 'help') {\n    console.log(HELP);\n    return;\n  }\n  switch (command) {\n    case 'generate':\n      return cmdGenerate(rest);\n    case 'init':\n      return cmdInit(rest);\n    case 'validate':\n      return cmdValidate(rest);\n    case 'favicon':\n      return cmdFavicon(rest);\n    case 'agents':\n      return cmdAgents(rest);\n    default:\n      fail(\n        `unknown command \"${command}\" (expected: generate | init | validate | favicon | agents). Try: vitops --help`,\n      );\n  }\n}\n\nmain().catch((err) => fail((err as Error).message));\n"],"mappings":"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"}
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/agents.ts","../src/cli.ts"],"sourcesContent":["/**\n * Side-effect-free helpers for the `vitops agents` / `vitops docs` commands.\n * Kept out of cli.ts (which runs main() on import) so they are unit-testable.\n */\nimport {\n  existsSync,\n  lstatSync,\n  mkdirSync,\n  readFileSync,\n  readlinkSync,\n  rmSync,\n  symlinkSync,\n} from 'node:fs';\nimport { dirname, join, parse, relative, resolve } from 'node:path';\n\nexport const SKILL_NAME = 'vitops-design-system';\n\n/** Marker the 0.5.0-era generated skill carried; lets us migrate that layout. */\nexport const GENERATED_MARKER = '<!-- GENERATED by @getvitops/cli';\n\n/**\n * `vitops docs` topics → docs-bundle paths (as returned by `generateDocs`).\n * Order is the `--all` concatenation order.\n */\nexport const TOPICS: Record<string, { path: string; summary: string }> = {\n  classes: {\n    path: 'css/classes.md',\n    summary: 'CSS framework class vocabulary (colour, type, space, layout, animation, patterns)',\n  },\n  authoring: {\n    path: 'authoring.md',\n    summary: 'every design-system.json field, rendered from the JSON Schema',\n  },\n  formats: {\n    path: 'formats.md',\n    summary: \"tailwind vs css vs bricks: what's emitted vs what the platform provides\",\n  },\n  color: {\n    path: 'concepts/color.md',\n    summary: 'seeded OKLCH scales, functional tokens, automatic dark mode',\n  },\n  scales: {\n    path: 'concepts/scales.md',\n    summary: 'fluid modular type & space scales',\n  },\n  patterns: {\n    path: 'concepts/patterns.md',\n    summary: 'pattern CSS: token cascade, override hooks, states, role variants',\n  },\n  elements: {\n    path: 'bricks/elements.md',\n    summary: 'Bricks Builder custom elements, controls, defaults',\n  },\n};\n\n/**\n * Find the installed package's skill directory by walking up from `cwd` looking\n * for `node_modules/@getvitops/cli/skill/SKILL.md`. Returns the LOGICAL path\n * (through the `node_modules/@getvitops/cli` link, unresolved) or null.\n *\n * Deliberately not derived from import.meta.url: under pnpm the running module's\n * URL is the realpath in `node_modules/.pnpm/@getvitops+cli@<version>/…`, which\n * changes on every version bump — a symlink to it would dangle after upgrades.\n * The logical path is recreated by the package manager on every install, so a\n * link through it always resolves to the currently installed version.\n */\nexport function findSkillTarget(cwd: string): string | null {\n  let dir = resolve(cwd);\n  const { root } = parse(dir);\n  for (;;) {\n    const skillDir = join(dir, 'node_modules', '@getvitops', 'cli', 'skill');\n    if (existsSync(join(skillDir, 'SKILL.md'))) return skillDir;\n    if (dir === root) return null;\n    dir = dirname(dir);\n  }\n}\n\n/**\n * Idempotently symlink `linkPath` → `targetDir` (relative target). Replaces a\n * stale symlink; migrates a real directory left by the old emitting `vitops\n * agents` (identified by GENERATED_MARKER in its SKILL.md); refuses to clobber\n * anything else. Returns a warning string, or null on success / no-op.\n */\nexport function linkSkill(linkPath: string, targetDir: string): string | null {\n  const target = relative(dirname(linkPath), resolve(targetDir));\n  try {\n    const st = lstatSync(linkPath, { throwIfNoEntry: false });\n    if (st && !st.isSymbolicLink()) {\n      const oldSkill = join(linkPath, 'SKILL.md');\n      const isGenerated =\n        st.isDirectory() &&\n        existsSync(oldSkill) &&\n        readFileSync(oldSkill, 'utf8').includes(GENERATED_MARKER);\n      if (!isGenerated)\n        return `left ${linkPath} alone (exists and is not a symlink) — link it to ${targetDir} yourself if wanted`;\n      rmSync(linkPath, { recursive: true }); // old generated skill layout → replace\n    } else if (st) {\n      if (readlinkSync(linkPath) === target) return null;\n      rmSync(linkPath);\n    } else {\n      mkdirSync(dirname(linkPath), { recursive: true });\n    }\n    symlinkSync(target, linkPath);\n    return null;\n  } catch (err) {\n    return `could not symlink ${linkPath}: ${(err as Error).message}`;\n  }\n}\n","#!/usr/bin/env node\n/**\n * `vitops` — CLI for the Vitops design-system generator.\n *\n *   vitops generate  --input <json> --format <bricks|css|tailwind[,…]> --out <dir>\n *   vitops init      [--out design-system.json] [--force]\n *   vitops validate  <design-system.json>\n *   vitops favicon   --input <svg|png> --out <dir> [--low-res <svg|png>]\n *   vitops agents    [--input <json>] [--out AGENTS.md] [--docs-dir <dir>]\n *   vitops docs      [topic] [--input <json>] [--all]\n *\n * Thin wrapper over @getvitops/generator (generation) and @getvitops/utils (favicons).\n * Every client brings their own consumer-editable design-system.json.\n */\nimport { parseArgs } from 'node:util';\nimport { writeFileSync, existsSync, readFileSync, mkdirSync } from 'node:fs';\nimport { resolve, join, dirname } from 'node:path';\nimport { createRequire } from 'node:module';\nimport {\n  generate,\n  validate,\n  defaultConfig,\n  generateDocs,\n  SCHEMA_URL,\n  type Format,\n  type DesignSystem,\n} from '@getvitops/generator';\nimport { generateFavicons } from '@getvitops/utils';\nimport { findSkillTarget, linkSkill, SKILL_NAME, TOPICS } from './agents.ts';\n\nconst FORMATS = new Set<Format>(['bricks', 'css', 'tailwind']);\n\nconst HELP = `vitops — generate design-system outputs from a design-system.json\n\nUsage:\n  vitops generate [options]     Generate platform output from a config\n  vitops init [options]         Scaffold a starter design-system.json\n  vitops validate <file>        Validate a config against the schema\n  vitops favicon [options]      Generate a favicon set from a source image\n  vitops agents [options]       Link the design-system agent skill + AGENTS.md pointer\n  vitops docs [topic]           Print live design-system reference docs to stdout\n\nGenerate options:\n  -i, --input <path>    Config file (default: ./design-system.json)\n  -f, --format <list>   bricks | css | tailwind (comma-separated; default: bricks)\n  -o, --out <dir>       Output directory (default: ./dist)\n\nInit options:\n  -o, --out <path>      Where to write (default: ./design-system.json)\n      --force           Overwrite an existing file\n\nFavicon options:\n  -i, --input <path>    Source SVG or PNG (required)\n  -o, --out <dir>       Output directory (default: ./public)\n      --low-res <path>  Optional simplified source for the 16px icon\n\nAgents options:\n  -i, --input <path>    Config file (default: ./design-system.json; validated if present)\n  -o, --out <path>      Doc file to update, idempotently (default: ./AGENTS.md)\n      --docs-dir <dir>  Legacy layout: write the docs bundle as files to this dir\n                        instead of linking the packaged skill\n\nDocs options:\n  <topic>               classes | authoring | formats | color | scales | patterns | elements\n                        (no topic: list topics with summaries)\n  -i, --input <path>    Config file (default: ./design-system.json)\n      --all             Print every topic, concatenated\n\nCommon:\n  -h, --help            Show this help\n`;\n\nfunction fail(msg: string): never {\n  console.error(`✖ ${msg}`);\n  process.exit(1);\n}\n\nasync function cmdGenerate(argv: string[]) {\n  const { values } = parseArgs({\n    args: argv,\n    options: {\n      input: { type: 'string', short: 'i', default: 'design-system.json' },\n      format: { type: 'string', short: 'f', default: 'bricks' },\n      out: { type: 'string', short: 'o', default: 'dist' },\n    },\n    allowPositionals: false,\n  });\n  const input = resolve(values.input as string);\n  if (!existsSync(input)) fail(`config not found: ${input}`);\n  const formats = (values.format as string)\n    .split(',')\n    .map((f) => f.trim())\n    .filter(Boolean);\n  for (const f of formats)\n    if (!FORMATS.has(f as Format))\n      fail(`unknown format \"${f}\" (expected: bricks | css | tailwind)`);\n\n  for (const format of formats as Format[]) {\n    try {\n      const res = await generate({ input, format, outDir: values.out as string });\n      console.log(`✓ ${format} → ${res.outDir} (${res.written.length} paths)`);\n    } catch (err) {\n      fail((err as Error).message);\n    }\n  }\n}\n\nfunction cmdInit(argv: string[]) {\n  const { values } = parseArgs({\n    args: argv,\n    options: {\n      out: { type: 'string', short: 'o', default: 'design-system.json' },\n      force: { type: 'boolean', default: false },\n    },\n    allowPositionals: false,\n  });\n  const out = resolve(values.out as string);\n  if (existsSync(out) && !values.force) fail(`${out} already exists (use --force to overwrite)`);\n  writeFileSync(out, JSON.stringify(defaultConfig(), null, 2) + '\\n');\n  console.log(`✓ wrote ${out}`);\n  console.log(\n    `  Edit it, then: vitops generate --input ${values.out} --format tailwind --out src/styles`,\n  );\n  console.log(`  Editors read the \"$schema\" (${SCHEMA_URL}) for autocomplete + validation.`);\n}\n\nfunction cmdValidate(argv: string[]) {\n  const { values, positionals } = parseArgs({\n    args: argv,\n    options: { input: { type: 'string', short: 'i' } },\n    allowPositionals: true,\n  });\n  const path = resolve((positionals[0] ?? values.input ?? 'design-system.json') as string);\n  if (!existsSync(path)) fail(`config not found: ${path}`);\n  let raw: unknown;\n  try {\n    raw = JSON.parse(readFileSync(path, 'utf8'));\n  } catch (err) {\n    fail(`could not parse JSON: ${(err as Error).message}`);\n  }\n  const result = validate(raw);\n  if (result.ok) {\n    console.log(`✓ ${path} is valid`);\n    return;\n  }\n  console.error(`✖ ${path} is invalid:`);\n  for (const e of result.errors) console.error(`  • ${e.path.join('.') || '(root)'}: ${e.message}`);\n  process.exit(1);\n}\n\nasync function cmdFavicon(argv: string[]) {\n  const { values } = parseArgs({\n    args: argv,\n    options: {\n      input: { type: 'string', short: 'i' },\n      out: { type: 'string', short: 'o', default: 'public' },\n      'low-res': { type: 'string' },\n    },\n    allowPositionals: false,\n  });\n  if (!values.input) fail('favicon: --input <svg|png> is required');\n  const source = resolve(values.input as string);\n  if (!existsSync(source)) fail(`source not found: ${source}`);\n  try {\n    const written = await generateFavicons({\n      source,\n      outputDir: values.out as string,\n      ...(values['low-res'] ? { lowResSource: resolve(values['low-res'] as string) } : {}),\n    });\n    console.log(`✓ favicons → ${values.out} (${written.length} files)`);\n  } catch (err) {\n    fail((err as Error).message);\n  }\n}\n\n// Read + parse + validate a design-system.json, or exit with a message.\nfunction loadConfig(path: string): DesignSystem {\n  if (!existsSync(path)) fail(`config not found: ${path}`);\n  let raw: unknown;\n  try {\n    raw = JSON.parse(readFileSync(path, 'utf8'));\n  } catch (err) {\n    fail(`could not parse JSON: ${(err as Error).message}`);\n  }\n  const result = validate(raw);\n  if (!result.ok) {\n    console.error(`✖ ${path} is invalid:`);\n    for (const e of result.errors)\n      console.error(`  • ${e.path.join('.') || '(root)'}: ${e.message}`);\n    process.exit(1);\n  }\n  return result.data;\n}\n\n// This CLI's own version (dist/cli.mjs → package-root package.json).\nfunction cliVersion(): string {\n  try {\n    return (\n      JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version ??\n      '0.0.0'\n    );\n  } catch {\n    return '0.0.0';\n  }\n}\n\n// The framework asset root shipped inside @getvitops/generator (holds the Bricks\n// PHP that generateDocs reads for the element reference).\nfunction generatorAssetsDir(): string {\n  const pkg = createRequire(import.meta.url).resolve('@getvitops/generator/package.json');\n  return join(dirname(pkg), 'assets');\n}\n\nconst AGENTS_START = '<!-- vitops:start -->';\nconst AGENTS_END = '<!-- vitops:end -->';\n\n/** Print a live reference doc (rendered from the project's config) to stdout. */\nfunction cmdDocs(argv: string[]) {\n  const { values, positionals } = parseArgs({\n    args: argv,\n    options: {\n      input: { type: 'string', short: 'i', default: 'design-system.json' },\n      all: { type: 'boolean', default: false },\n    },\n    allowPositionals: true,\n  });\n  const topic = positionals[0];\n  const topicList = () =>\n    Object.entries(TOPICS)\n      .map(([name, t]) => `  ${name.padEnd(10)} ${t.summary}`)\n      .join('\\n');\n  if (!topic && !values.all) {\n    console.log(\n      `vitops docs <topic> — print a live design-system reference to stdout\\n\\nTopics:\\n${topicList()}\\n\\nAlso: vitops docs --all (every topic, concatenated)`,\n    );\n    return;\n  }\n  if (topic && !TOPICS[topic]) fail(`unknown topic \"${topic}\". Valid topics:\\n${topicList()}`);\n  const ds = loadConfig(resolve(values.input as string));\n  const docs = generateDocs(ds, generatorAssetsDir());\n  const paths = values.all\n    ? Object.values(TOPICS).map((t) => t.path)\n    : [TOPICS[topic as string]!.path];\n  process.stdout.write(paths.map((p) => docs[p]).join('\\n'));\n}\n\nfunction cmdAgents(argv: string[]) {\n  const { values } = parseArgs({\n    args: argv,\n    options: {\n      input: { type: 'string', short: 'i', default: 'design-system.json' },\n      out: { type: 'string', short: 'o', default: 'AGENTS.md' },\n      'docs-dir': { type: 'string' },\n    },\n    allowPositionals: false,\n  });\n  const inputRel = values.input as string;\n  // The command is pure wiring: validate the config when present (fail on an\n  // invalid one), but don't require it — docs are rendered live by `vitops docs`.\n  let ds: DesignSystem | null = null;\n  if (existsSync(resolve(inputRel))) ds = loadConfig(resolve(inputRel));\n  else console.warn(`  ⚠ ${inputRel} not found — run \\`vitops init\\` to scaffold one`);\n\n  // Explicit --docs-dir = legacy layout: write the docs bundle as files, no skill.\n  const legacyDocsDir = values['docs-dir'] as string | undefined;\n  let summary: string;\n  let pointer: string[];\n\n  if (legacyDocsDir) {\n    if (!ds) fail(`--docs-dir needs a config to render docs from (${inputRel} not found)`);\n    let docs: Record<string, string> = {};\n    try {\n      docs = generateDocs(ds, generatorAssetsDir());\n    } catch (err) {\n      fail(`could not generate docs: ${(err as Error).message}`);\n    }\n    for (const [rel, content] of Object.entries(docs)) {\n      const p = resolve(legacyDocsDir, rel);\n      mkdirSync(dirname(p), { recursive: true });\n      writeFileSync(p, content);\n    }\n    summary = `wrote ${Object.keys(docs).length} docs to ${legacyDocsDir}/`;\n    pointer = [\n      'Prefer the framework’s utility + component classes over hand-written CSS.',\n      `Reference docs (regenerate with \\`vitops agents --docs-dir ${legacyDocsDir}\\`): \\`${legacyDocsDir}/css/classes.md\\`,`,\n      `\\`${legacyDocsDir}/authoring.md\\`, \\`${legacyDocsDir}/formats.md\\`, \\`${legacyDocsDir}/bricks/elements.md\\`.`,\n    ];\n  } else {\n    // Link the packaged skill (ships inside @getvitops/cli) into the agent\n    // discovery locations; nothing is generated into the repo.\n    const target = findSkillTarget(process.cwd());\n    if (target) {\n      for (const dir of ['.agents', '.claude']) {\n        const warn = linkSkill(resolve(dir, 'skills', SKILL_NAME), target);\n        if (warn) console.warn(`  ⚠ ${warn}`);\n      }\n      summary = `linked {.agents,.claude}/skills/${SKILL_NAME} → ${target}`;\n    } else {\n      console.warn(\n        `  ⚠ could not find node_modules/@getvitops/cli/skill — install @getvitops/cli as a devDependency, then re-run \\`vitops agents\\``,\n      );\n      summary = 'no skill linked';\n    }\n    pointer = [\n      'Prefer the framework’s utility + component classes over hand-written CSS.',\n      `Full design-system context lives in the \\`${SKILL_NAME}\\` skill (linked from`,\n      '`.agents/skills/` and `.claude/skills/` into the installed `@getvitops/cli`;',\n      're-link with `vitops agents` if the links are deleted — they survive version',\n      'bumps). Reference docs print live, from this project’s config, via:',\n      '',\n      ...Object.entries(TOPICS).map(([name, t]) => `- \\`vitops docs ${name}\\` — ${t.summary}`),\n    ];\n  }\n\n  const block = [\n    AGENTS_START,\n    '## Vitops design system',\n    '',\n    `Styled with the Vitops design system (\\`@getvitops/*\\`); tokens live in \\`${inputRel}\\`.`,\n    'Generate output with the CLI:',\n    '',\n    '- `vitops generate --format tailwind --out src/styles` — Tailwind v4 / Astro',\n    '- `vitops generate --format css --out dist` — standalone CSS',\n    '- `vitops generate --format bricks --out <theme>/dist` — WordPress / Bricks',\n    '- `vitops init` · `vitops validate` · `vitops favicon`',\n    '',\n    ...pointer,\n    '',\n    `<!-- regenerate: vitops agents · @getvitops/cli@${cliVersion()} -->`,\n    AGENTS_END,\n  ].join('\\n');\n\n  const outPath = resolve(values.out as string);\n  let next: string;\n  let action: string;\n  if (existsSync(outPath)) {\n    const cur = readFileSync(outPath, 'utf8');\n    const s = cur.indexOf(AGENTS_START);\n    const e = cur.indexOf(AGENTS_END);\n    if (s !== -1 && e !== -1 && e > s) {\n      next = cur.slice(0, s) + block + cur.slice(e + AGENTS_END.length);\n      action = 'updated block in';\n    } else {\n      next = cur.replace(/\\s*$/, '') + '\\n\\n' + block + '\\n';\n      action = 'appended block to';\n    }\n  } else {\n    mkdirSync(dirname(outPath), { recursive: true });\n    next = block + '\\n';\n    action = 'created';\n  }\n  writeFileSync(outPath, next);\n  console.log(`✓ ${action} ${values.out} + ${summary}`);\n}\n\nasync function main() {\n  const [command, ...rest] = process.argv.slice(2);\n  if (!command || command === '-h' || command === '--help' || command === 'help') {\n    console.log(HELP);\n    return;\n  }\n  switch (command) {\n    case 'generate':\n      return cmdGenerate(rest);\n    case 'init':\n      return cmdInit(rest);\n    case 'validate':\n      return cmdValidate(rest);\n    case 'favicon':\n      return cmdFavicon(rest);\n    case 'agents':\n      return cmdAgents(rest);\n    case 'docs':\n      return cmdDocs(rest);\n    default:\n      fail(\n        `unknown command \"${command}\" (expected: generate | init | validate | favicon | agents | docs). Try: vitops --help`,\n      );\n  }\n}\n\nmain().catch((err) => fail((err as Error).message));\n"],"mappings":"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"}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@getvitops/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "CLI for the Vitops design-system generator: generate, init, and validate a design-system.json.",
   "license": "MIT",
   "bin": {
     "vitops": "./dist/cli.mjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "skill"
   ],
   "type": "module",
   "exports": {
@@ -20,7 +21,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@getvitops/generator": "0.4.0",
-    "@getvitops/utils": "0.4.0"
+    "@getvitops/generator": "0.6.0",
+    "@getvitops/utils": "0.6.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.9"
   }
 }

package/skill/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: vitops-design-system
+description: >-
+  Work with this project's Vitops design system. Use when styling or authoring
+  pages or components (choosing utility/pattern classes, colours, spacing,
+  typography), when editing design-system.json (tokens, palette, patterns,
+  scales, animations), when generating output (vitops generate --format
+  tailwind|css|bricks), or when asking what the design system provides on a
+  given platform (Tailwind vs Bricks vs standalone CSS).
+---
+
+# Vitops design system
+
+This project is styled with the Vitops design system (`@getvitops/*`): a variable-driven
+CSS framework generated from `design-system.json` (the single source of truth — semantic
+colour roles, fluid type/space scales, component patterns, animation effects).
+
+**Core rule:** prefer the framework's utility + component classes over hand-written CSS or
+ad-hoc values — they encode the tokens, respond to dark mode, and update with the system.
+
+## Getting the current reference docs
+
+Run **`vitops docs <topic>`** — it prints the reference as markdown to stdout, generated
+live from this project's `design-system.json` and the installed package version, so it is
+never stale and always names the project's actual tokens. (If `vitops` isn't on PATH, use
+`pnpm exec vitops docs <topic>` or `npx vitops docs <topic>`.)
+
+| Run                     | When you need                                                          |
+| ----------------------- | ---------------------------------------------------------------------- |
+| `vitops docs classes`   | which class to apply — the full class vocabulary as naming rules       |
+| `vitops docs authoring` | what a `design-system.json` field means / what's valid                 |
+| `vitops docs formats`   | tailwind vs css vs bricks output — incl. which utilities Tailwind owns |
+| `vitops docs color`     | how the colour system works (seeded OKLCH scales, roles, dark mode)    |
+| `vitops docs scales`    | how the fluid type/space scales work                                   |
+| `vitops docs patterns`  | how pattern CSS is assembled (token cascade, override hooks, states)   |
+| `vitops docs elements`  | the custom Bricks Builder elements and their controls                  |
+
+`vitops docs` (no topic) lists the topics; `vitops docs --all` prints everything.
+
+## Other commands
+
+- `vitops generate --format <tailwind|css|bricks>` — generate the platform output.
+- `vitops init` / `vitops validate` — scaffold / check a `design-system.json`.
+- `vitops agents` — (re-)link this skill into `.agents/skills/` + `.claude/skills/` and
+  refresh the AGENTS.md pointer block. The links point into the installed package and
+  survive version bumps; re-run only if they were deleted.