@urbicon-ui/design 6.1.8

package/dist/cli.js

@@ -0,0 +1,2732 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { readFile as readFile10 } from "node:fs/promises";
+import { resolve as resolve9 } from "node:path";
+
+// src/cli/args.ts
+var BOOLEAN_FLAGS = new Set([
+  "json",
+  "strict",
+  "skip-heuristics",
+  "record",
+  "hook",
+  "ci",
+  "help",
+  "version"
+]);
+function parseArgs(argv, booleans = BOOLEAN_FLAGS) {
+  let command;
+  const positionals = [];
+  const flags = {};
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === undefined)
+      continue;
+    if (arg.startsWith("--")) {
+      const body = arg.slice(2);
+      const eq = body.indexOf("=");
+      if (eq !== -1) {
+        flags[body.slice(0, eq)] = body.slice(eq + 1);
+        continue;
+      }
+      if (booleans.has(body)) {
+        flags[body] = true;
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        flags[body] = next;
+        i++;
+      } else {
+        flags[body] = true;
+      }
+      continue;
+    }
+    if (command === undefined)
+      command = arg;
+    else
+      positionals.push(arg);
+  }
+  return { command, positionals, flags };
+}
+function stringFlag(flags, key) {
+  const value = flags[key];
+  return typeof value === "string" ? value : undefined;
+}
+function boolFlag(flags, key) {
+  const value = flags[key];
+  return value === true || value === "true";
+}
+
+// src/cli/commands/context.ts
+import { readFile as readFile3 } from "node:fs/promises";
+
+// ../design-engine/src/manifest/history.ts
+function serializeHistoryEntry(entry) {
+  return JSON.stringify(entry);
+}
+function isEntry(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const e = value;
+  return typeof e.date === "string" && typeof e.files === "number" && typeof e.errors === "number" && typeof e.warnings === "number" && typeof e.infos === "number" && typeof e.correctness === "number" && typeof e.slop === "number";
+}
+function parseHistory(ndjson) {
+  const entries = [];
+  for (const line of ndjson.split(`
+`)) {
+    const trimmed = line.trim();
+    if (!trimmed)
+      continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (isEntry(parsed))
+        entries.push(parsed);
+    } catch {}
+  }
+  return entries;
+}
+// ../design-engine/src/manifest/manifest.ts
+var INTENT_HEADING = "## Product Intent";
+var TOKEN_OVERRIDES_HEADING = "## Token Overrides";
+var USAGES_HEADING = "## Pattern Usages";
+var DECISIONS_HEADING = "## Design Decisions";
+var USAGES_MARKER_PREFIX = "<!-- AUTO-GENERATED pattern usages";
+var USAGES_START = `${USAGES_MARKER_PREFIX} — regenerated from data-design-pattern markers; do not edit by hand -->`;
+var USAGES_END = "<!-- END pattern usages -->";
+function parseFrontmatter(content) {
+  const data = {};
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match)
+    return { data, body: content };
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = line.match(/^([a-zA-Z][\w-]*)\s*:\s*(.*)$/);
+    if (kv) {
+      const value = kv[2].trim().replace(/^["']|["']$/g, "");
+      if (value)
+        data[kv[1]] = value;
+    }
+  }
+  return { data, body: content.slice(match[0].length) };
+}
+function extractSection(body, heading) {
+  const lines = body.split(`
+`);
+  const start = lines.findIndex((l) => l.trim() === heading);
+  if (start === -1)
+    return null;
+  let end = lines.length;
+  for (let i = start + 1;i < lines.length; i++) {
+    if (/^## /.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start + 1, end).join(`
+`);
+}
+function parseUsages(body) {
+  const section = extractSection(body, USAGES_HEADING);
+  if (!section)
+    return [];
+  const usages = [];
+  for (const m of section.matchAll(/^- `([a-z0-9-]+)`\s+—\s+(.+)$/gm)) {
+    usages.push({ pattern: m[1], file: m[2].trim() });
+  }
+  return usages;
+}
+function parseDecisions(body) {
+  const section = extractSection(body, DECISIONS_HEADING);
+  if (!section)
+    return [];
+  const decisions = [];
+  const blocks = section.split(/^### /m).slice(1);
+  for (const block of blocks) {
+    const headerLine = block.split(`
+`, 1)[0];
+    const header = headerLine.match(/^(\d{4}-\d{2}-\d{2})\s+—\s+(.+)$/);
+    if (!header)
+      continue;
+    const field = (name) => block.match(new RegExp(`\\*\\*${name}:\\*\\*\\s*(.+)`))?.[1]?.trim();
+    decisions.push({
+      date: header[1],
+      title: header[2].trim(),
+      status: field("Status") ?? "accepted",
+      decision: field("Decision") ?? "",
+      rationale: field("Rationale")
+    });
+  }
+  return decisions;
+}
+function emptyIntent() {
+  return { voice: [], references: [], antiReferences: [] };
+}
+function parseIntent(body) {
+  const section = extractSection(body, INTENT_HEADING);
+  if (section === null)
+    return emptyIntent();
+  const lines = section.split(`
+`);
+  const inlineField = (label) => {
+    const re = new RegExp(`^\\*\\*${label}:\\*\\*\\s*(.+)$`);
+    for (const l of lines) {
+      const m = l.match(re);
+      if (m)
+        return m[1].trim();
+    }
+    return;
+  };
+  const listField = (label) => {
+    const items = [];
+    const labelRe = new RegExp(`^\\*\\*${label}:\\*\\*\\s*(.*)$`);
+    let capturing = false;
+    for (const l of lines) {
+      if (!capturing) {
+        const m = l.match(labelRe);
+        if (m) {
+          capturing = true;
+          const inline = m[1].trim();
+          if (inline)
+            items.push(...splitList(inline));
+        }
+        continue;
+      }
+      if (/^\*\*[^*]+:\*\*/.test(l))
+        break;
+      const bullet = l.match(/^\s*[-*]\s+(.+)$/);
+      if (bullet)
+        items.push(bullet[1].trim());
+    }
+    return items;
+  };
+  return {
+    audience: inlineField("Audience"),
+    voice: listField("Voice"),
+    references: listField("References"),
+    antiReferences: listField("Anti-references")
+  };
+}
+function splitList(value) {
+  return value.split(",").map((part) => part.trim()).filter(Boolean);
+}
+function parseTokenOverrides(body) {
+  const section = extractSection(body, TOKEN_OVERRIDES_HEADING);
+  if (!section)
+    return [];
+  const cores = [];
+  const seen = new Set;
+  for (const m of section.matchAll(/^\s*[-*]\s+`([a-z][a-z0-9-]*)`/gm)) {
+    const core = m[1];
+    if (!seen.has(core)) {
+      seen.add(core);
+      cores.push(core);
+    }
+  }
+  return cores;
+}
+function parseManifest(content, exists = true) {
+  const { data, body } = parseFrontmatter(content);
+  return {
+    frontmatter: data,
+    intent: parseIntent(body),
+    tokenOverrides: parseTokenOverrides(body),
+    usages: parseUsages(body),
+    decisions: parseDecisions(body),
+    exists
+  };
+}
+function emptyManifest() {
+  return {
+    frontmatter: {},
+    intent: emptyIntent(),
+    tokenOverrides: [],
+    usages: [],
+    decisions: [],
+    exists: false
+  };
+}
+function renderUsagesBlock(usages) {
+  const lines = [USAGES_START];
+  if (usages.length === 0) {
+    lines.push("", "_No `data-design-pattern` markers found yet._", "");
+  } else {
+    lines.push("");
+    const sorted = [...usages].sort((a, b) => a.pattern.localeCompare(b.pattern) || a.file.localeCompare(b.file));
+    for (const u of sorted)
+      lines.push(`- \`${u.pattern}\` — ${u.file}`);
+    lines.push("");
+  }
+  lines.push(USAGES_END);
+  return lines.join(`
+`);
+}
+function upsertUsagesSection(content, usages) {
+  const block = renderUsagesBlock(usages);
+  const startIdx = content.indexOf(USAGES_MARKER_PREFIX);
+  if (startIdx !== -1) {
+    const endIdx = content.indexOf(USAGES_END, startIdx);
+    if (endIdx !== -1) {
+      const after = endIdx + USAGES_END.length;
+      return content.slice(0, startIdx) + block + content.slice(after);
+    }
+    const nextSection = content.indexOf(`
+## `, startIdx);
+    const truncateAt = nextSection !== -1 ? nextSection : content.length;
+    return content.slice(0, startIdx) + block + content.slice(truncateAt);
+  }
+  if (content.includes(`
+${USAGES_HEADING}`) || content.startsWith(USAGES_HEADING)) {
+    return content.replace(new RegExp(`(${USAGES_HEADING}\\n)`), (_m, heading) => `${heading}
+${block}
+`);
+  }
+  const sep = content.endsWith(`
+`) ? `
+` : `
+
+`;
+  return `${content}${sep}${USAGES_HEADING}
+
+${block}
+`;
+}
+function oneLine(s) {
+  return s.replace(/[\r\n]+/g, " ").trim();
+}
+function renderDecision(d) {
+  const lines = [
+    `### ${d.date} — ${oneLine(d.title)}`,
+    "",
+    `**Status:** ${oneLine(d.status)}`,
+    "",
+    `**Decision:** ${oneLine(d.decision)}`
+  ];
+  if (d.rationale)
+    lines.push("", `**Rationale:** ${oneLine(d.rationale)}`);
+  return `${lines.join(`
+`)}
+`;
+}
+function appendDecision(content, decision) {
+  const block = renderDecision(decision);
+  const m = content.match(/(?:^|\n)## Design Decisions[^\n]*\n/);
+  if (m && m.index !== undefined) {
+    let pos = m.index + m[0].length;
+    let prefix = "";
+    if (content[pos] === `
+`)
+      pos += 1;
+    else
+      prefix = `
+`;
+    return `${content.slice(0, pos) + prefix + block}
+${content.slice(pos)}`;
+  }
+  const sep = content.endsWith(`
+`) ? `
+` : `
+
+`;
+  return `${content}${sep}${DECISIONS_HEADING}
+
+${block}`;
+}
+function createManifestTemplate(opts) {
+  const fm = [
+    "---",
+    `paradigm: ${opts.paradigm ?? "minimal"}`,
+    `theme: ${opts.theme ?? "default"}`,
+    `density: ${opts.density ?? "comfortable"}`,
+    "---"
+  ].join(`
+`);
+  return [
+    fm,
+    "",
+    `# Design Manifest${opts.projectName ? ` — ${opts.projectName}` : ""}`,
+    "",
+    "The persistent design intent for this project. Frontmatter records the enforced intake",
+    "decisions (paradigm, theme, density). `## Product Intent` is the target identity.",
+    "`## Token Overrides` lists project-specific tokens `urbicon validate` should accept.",
+    "`## Pattern Usages` is regenerated from `data-design-pattern` markers by",
+    "`urbicon sync-manifest`. `## Design Decisions` is an append-only ADR log written by",
+    "`urbicon record-decision`.",
+    "",
+    INTENT_HEADING,
+    "",
+    "<!-- The identity this project designs toward — read at the start of every design task.",
+    '     Fill each field; an empty field is simply "not set yet". Voice = a few adjectives. -->',
+    "",
+    "**Audience:**",
+    "",
+    "**Voice:**",
+    "",
+    "**References:**",
+    "",
+    "**Anti-references:**",
+    "",
+    TOKEN_OVERRIDES_HEADING,
+    "",
+    "<!-- Project-specific semantic token cores defined on top of Urbicon’s. Listed here as a",
+    "     bullet of `core` (the part after the utility prefix — `surface-brand`, not",
+    "     `bg-surface-brand`), they are treated as valid by `urbicon validate`. -->",
+    "",
+    "_None yet._",
+    "",
+    USAGES_HEADING,
+    "",
+    renderUsagesBlock([]),
+    "",
+    DECISIONS_HEADING,
+    ""
+  ].join(`
+`);
+}
+function intentIsEmpty(intent) {
+  return !intent.audience && intent.voice.length === 0 && intent.references.length === 0 && intent.antiReferences.length === 0;
+}
+function formatDrift(history) {
+  const recent = history.slice(-5);
+  const last = recent[recent.length - 1];
+  let md = `## Validation Drift
+
+`;
+  md += `Last run (${last.date}): correctness ${last.correctness}/100 · slop ${last.slop}/100 — ` + `${last.files} file(s), ${last.errors} error(s), ${last.warnings} warning(s).
+`;
+  if (recent.length > 1) {
+    md += `
+Recent correctness: ${recent.map((e) => e.correctness).join(" → ")}
+`;
+    md += `Recent slop-floor:  ${recent.map((e) => e.slop).join(" → ")}
+`;
+  }
+  return md;
+}
+function formatContext(manifest, history = []) {
+  let md = `# Design Context
+
+`;
+  const fm = manifest.frontmatter;
+  const keys = Object.keys(fm);
+  if (keys.length > 0) {
+    md += `## Intake
+
+`;
+    for (const k of keys)
+      md += `- **${k}:** ${fm[k]}
+`;
+    md += `
+`;
+    if (fm.paradigm) {
+      md += `> Stay within the **${fm.paradigm}** paradigm. Call \`get_design_principles(topic="theming")\` for its token profile.
+
+`;
+    }
+  }
+  md += `## Product Intent
+
+`;
+  const intent = manifest.intent;
+  if (intentIsEmpty(intent)) {
+    md += `_Not set._ Define audience, voice, references and anti-references so design stays consistent with a target identity, not merely generic.
+
+`;
+  } else {
+    if (intent.audience)
+      md += `- **Audience:** ${intent.audience}
+`;
+    if (intent.voice.length > 0)
+      md += `- **Voice:** ${intent.voice.join(", ")}
+`;
+    if (intent.references.length > 0)
+      md += `- **References:** ${intent.references.join("; ")}
+`;
+    if (intent.antiReferences.length > 0)
+      md += `- **Anti-references:** ${intent.antiReferences.join("; ")}
+`;
+    md += `
+`;
+  }
+  if (manifest.tokenOverrides.length > 0) {
+    md += `## Token Overrides
+
+`;
+    md += `${manifest.tokenOverrides.map((c) => `\`${c}\``).join(", ")}
+
+`;
+    md += "> Treated as valid by `urbicon validate` (passed as extra tokens for this project).\n\n";
+  }
+  md += `## Pattern Usages
+
+`;
+  if (manifest.usages.length === 0) {
+    md += '_None recorded._ Add `data-design-pattern="<name>"` to page roots, then run `urbicon sync-manifest`.\n\n';
+  } else {
+    const byPattern = new Map;
+    for (const u of manifest.usages) {
+      (byPattern.get(u.pattern) ?? byPattern.set(u.pattern, []).get(u.pattern)).push(u.file);
+    }
+    for (const [pattern, files] of [...byPattern].sort((a, b) => a[0].localeCompare(b[0]))) {
+      md += `- \`${pattern}\` (${files.length}): ${files.join(", ")}
+`;
+    }
+    md += `
+> To change a pattern across the app, migrate every file listed under it.
+
+`;
+  }
+  md += `## Design Decisions
+
+`;
+  if (manifest.decisions.length === 0) {
+    md += "_None recorded._ Use `urbicon record-decision` when you deviate from a pattern or principle.\n";
+  } else {
+    for (const d of manifest.decisions) {
+      md += `- **${d.date} — ${d.title}** (${d.status}): ${d.decision}
+`;
+    }
+  }
+  if (history.length > 0)
+    md += `
+${formatDrift(history)}`;
+  return md;
+}
+// ../design-engine/src/manifest/scan.ts
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+var SCANNED_EXT = /\.(svelte|html|tsx|jsx|astro|vue)$/;
+var SKIP_DIRS = new Set([
+  "node_modules",
+  ".svelte-kit",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  ".turbo",
+  "coverage"
+]);
+var MARKER_RE = /data-design-pattern\s*=\s*["'`]([a-z0-9-]+)["'`]/g;
+var MAX_DEPTH = 24;
+async function scanMarkers(dir, baseDir = dir, depth = 0) {
+  const usages = [];
+  if (depth > MAX_DEPTH)
+    return usages;
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch {
+    return usages;
+  }
+  for (const name of names) {
+    const full = join(dir, name);
+    const info = await stat(full).catch(() => null);
+    if (!info)
+      continue;
+    if (info.isDirectory()) {
+      if (SKIP_DIRS.has(name) || name.startsWith("."))
+        continue;
+      usages.push(...await scanMarkers(full, baseDir, depth + 1));
+    } else if (info.isFile() && SCANNED_EXT.test(name)) {
+      let content;
+      try {
+        content = await readFile(full, "utf-8");
+      } catch {
+        continue;
+      }
+      const seen = new Set;
+      for (const m of content.matchAll(MARKER_RE)) {
+        const pattern = m[1];
+        if (seen.has(pattern))
+          continue;
+        seen.add(pattern);
+        usages.push({ pattern, file: relative(baseDir, full).split(sep).join("/") });
+      }
+    }
+  }
+  return usages;
+}
+// src/cli/manifest-io.ts
+import { appendFile, readFile as readFile2, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+function resolveManifestPath(flag) {
+  return resolve(flag ?? "design.manifest.md");
+}
+function resolveSourceDir(flag) {
+  return resolve(flag ?? "src");
+}
+function resolveHistoryPath(manifestPath) {
+  return manifestPath.endsWith(".md") ? `${manifestPath.slice(0, -".md".length)}.history.ndjson` : `${manifestPath}.history.ndjson`;
+}
+async function readTokenOverrides(manifestPath) {
+  try {
+    return parseManifest(await readFile2(manifestPath, "utf-8")).tokenOverrides;
+  } catch {
+    return [];
+  }
+}
+async function readHistory(manifestPath) {
+  try {
+    return parseHistory(await readFile2(resolveHistoryPath(manifestPath), "utf-8"));
+  } catch {
+    return [];
+  }
+}
+function appendHistory(manifestPath, line) {
+  return appendFile(resolveHistoryPath(manifestPath), `${line}
+`, "utf-8");
+}
+async function readOrCreateManifest(path) {
+  try {
+    return { content: await readFile2(path, "utf-8"), created: false };
+  } catch {
+    return { content: createManifestTemplate({}), created: true };
+  }
+}
+function writeManifest(path, content) {
+  return writeFile(path, content, "utf-8");
+}
+
+// src/cli/output.ts
+var EXIT = { OK: 0, FAIL: 1, USAGE: 2 };
+var SEVERITY_ICON = { error: "✗", warning: "!", info: "·" };
+function formatFinding(f) {
+  const loc = f.line ? `:${f.line}` : "";
+  const match = f.match ? ` \`${f.match}\`` : "";
+  return `  ${SEVERITY_ICON[f.severity]} [${f.ruleId}]${loc}${match} — ${f.message}
+    ↳ ${f.fix}`;
+}
+function formatReport(report) {
+  const { scores, counts, findings, filename } = report;
+  const head = `${filename ?? "<stdin>"} — correctness ${scores.correctness}/100 · slop ${scores.slop}/100 · ` + `${counts.error} error(s), ${counts.warning} warning(s), ${counts.info} slop note(s)`;
+  if (findings.length === 0)
+    return `${head}
+  ✓ no issues`;
+  return `${head}
+${findings.map(formatFinding).join(`
+`)}`;
+}
+function printError(message) {
+  console.error(`urbicon: ${message}`);
+}
+
+// src/cli/commands/context.ts
+async function runContext(_positionals, flags) {
+  const path = resolveManifestPath(stringFlag(flags, "manifest"));
+  let manifest;
+  try {
+    manifest = parseManifest(await readFile3(path, "utf-8"));
+  } catch {
+    manifest = emptyManifest();
+  }
+  const history = await readHistory(path);
+  if (boolFlag(flags, "json")) {
+    console.log(JSON.stringify({ ...manifest, history }, null, 2));
+    return EXIT.OK;
+  }
+  let text = formatContext(manifest, history);
+  if (!manifest.exists) {
+    text += `
+
+> No manifest at \`${path}\`. Create one with \`urbicon sync-manifest\` ` + "or record the first decision with `urbicon record-decision`.";
+  }
+  console.log(text);
+  return EXIT.OK;
+}
+
+// ../design-engine/src/search/match.ts
+function matchComponents(components, query, tags, limit = 5) {
+  const keywords = query.toLowerCase().split(/[\s,\-_]+/).filter((w) => w.length > 1);
+  const scored = components.map((entry) => {
+    let score = 0;
+    const nameLower = entry.name.toLowerCase();
+    const slugLower = entry.slug.toLowerCase();
+    const descLower = entry.description.toLowerCase();
+    for (const kw of keywords) {
+      if (nameLower === kw || slugLower === kw) {
+        score += 10;
+      } else if (nameLower.includes(kw) || slugLower.includes(kw)) {
+        score += 7;
+      } else {
+        const nameDist = levenshtein(nameLower, kw);
+        const slugDist = levenshtein(slugLower, kw);
+        const minDist = Math.min(nameDist, slugDist);
+        if (minDist <= 1) {
+          score += 6;
+        } else if (minDist <= 2) {
+          score += 3;
+        }
+      }
+      if (entry.tags.some((t) => t.toLowerCase() === kw)) {
+        score += 5;
+      }
+      if (descLower.includes(kw)) {
+        score += 3;
+      }
+      if (entry.keyProps.some((p) => p.toLowerCase().includes(kw))) {
+        score += 1;
+      }
+    }
+    if (tags && tags.length > 0) {
+      const entryTags = entry.tags.map((t) => t.toLowerCase());
+      for (const tag of tags) {
+        if (entryTags.includes(tag.toLowerCase())) {
+          score += 5;
+        }
+      }
+    }
+    return { entry, score };
+  });
+  return scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score).slice(0, limit).map((s) => s.entry);
+}
+function levenshtein(a, b) {
+  if (a.length === 0)
+    return b.length;
+  if (b.length === 0)
+    return a.length;
+  if (Math.abs(a.length - b.length) > 2)
+    return 3;
+  const matrix = [];
+  for (let i = 0;i <= a.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0;j <= b.length; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1;i <= a.length; i++) {
+    for (let j = 1;j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+    }
+  }
+  return matrix[a.length][b.length];
+}
+// ../design-engine/src/search/section.ts
+var SECTION_HEADING_MAP = {
+  examples: "examples",
+  variants: "variants",
+  api: "api",
+  "slots (slotclasses keys)": "slots"
+};
+function extractSection2(content, section) {
+  if (section === "overview") {
+    const firstH3 = content.indexOf(`
+### `);
+    if (firstH3 === -1)
+      return content.trim();
+    return content.slice(0, firstH3).trim();
+  }
+  const lines = content.split(`
+`);
+  let capturing = false;
+  const result = [];
+  for (const line of lines) {
+    if (line.startsWith("### ")) {
+      const heading = line.slice(4).trim().toLowerCase();
+      const mapped = SECTION_HEADING_MAP[heading];
+      if (mapped === section) {
+        capturing = true;
+        result.push(line);
+        continue;
+      } else if (capturing) {
+        break;
+      }
+    }
+    if (capturing) {
+      result.push(line);
+    }
+  }
+  return result.length > 0 ? result.join(`
+`).trim() : null;
+}
+// src/cli/content.ts
+import { readFile as readFile4 } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname as dirname2, resolve as resolve3 } from "node:path";
+
+// ../design-content/src/content-loader.ts
+import { dirname, normalize, resolve as resolve2 } from "node:path";
+import { fileURLToPath } from "node:url";
+var moduleDir = dirname(fileURLToPath(import.meta.url));
+function getContentDir() {
+  return process.env.URBICON_CONTENT_DIR ?? resolve2(moduleDir, "..", "content");
+}
+function getCatalogPath() {
+  return resolve2(getContentDir(), "component-catalog.json");
+}
+var SAFE_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function getComponentLlmPath(group, slug) {
+  if (!SAFE_SLUG.test(slug)) {
+    throw new Error(`Invalid component slug: "${slug}"`);
+  }
+  const resolved = resolve2(getContentDir(), group, slug, "llm.txt");
+  const base = normalize(getContentDir());
+  if (!resolved.startsWith(base)) {
+    throw new Error(`Path traversal blocked for slug: "${slug}"`);
+  }
+  return resolved;
+}
+// src/cli/content.ts
+var SEARCH_GROUPS = [
+  "blocks/primitives",
+  "blocks/components",
+  "docs/components",
+  "table",
+  "auth/components"
+];
+var contentDirEnsured = false;
+function ensureContentDir() {
+  if (contentDirEnsured)
+    return;
+  contentDirEnsured = true;
+  if (process.env.URBICON_CONTENT_DIR)
+    return;
+  try {
+    const require2 = createRequire(import.meta.url);
+    const pkgJson = require2.resolve("@urbicon-ui/design-content/package.json");
+    process.env.URBICON_CONTENT_DIR = resolve3(dirname2(pkgJson), "content");
+  } catch {}
+}
+async function loadCatalog() {
+  ensureContentDir();
+  const raw = await readFile4(getCatalogPath(), "utf-8");
+  return JSON.parse(raw);
+}
+async function loadComponentLlm(slug) {
+  ensureContentDir();
+  for (const group of SEARCH_GROUPS) {
+    try {
+      return await readFile4(getComponentLlmPath(group, slug), "utf-8");
+    } catch (err) {
+      if (err.code === "ENOENT")
+        continue;
+      throw err;
+    }
+  }
+  try {
+    await readFile4(getCatalogPath(), "utf-8");
+  } catch {
+    throw new Error("design-content bundle missing — reinstall @urbicon-ui/design-content, or run `docs:gen:all` in the monorepo");
+  }
+  return null;
+}
+
+// src/cli/commands/find.ts
+function variantSummary(entry) {
+  return entry.variants.filter((v) => !v.values.every((x) => x === "true" || x === "false")).map((v) => `${v.name}: ${v.values.join("/")}`).join(" · ");
+}
+function shortDescription(description) {
+  const firstLine = description.split(`
+`)[0]?.trim() ?? "";
+  return firstLine.length > 140 ? `${firstLine.slice(0, 139)}…` : firstLine;
+}
+function formatEntry(entry) {
+  const lines = [`  ${entry.name}  ·  ${entry.slug}`, `    ${shortDescription(entry.description)}`];
+  const variants = variantSummary(entry);
+  if (variants)
+    lines.push(`    ${variants}`);
+  if (entry.relatedComponents.length > 0) {
+    lines.push(`    related: ${entry.relatedComponents.join(", ")}`);
+  }
+  return lines.join(`
+`);
+}
+async function runFind(positionals, flags) {
+  const query = positionals.join(" ").trim();
+  const asJson = boolFlag(flags, "json");
+  const tag = stringFlag(flags, "tag");
+  const tags = tag ? [tag] : undefined;
+  const limitRaw = stringFlag(flags, "limit");
+  const limit = limitRaw === undefined ? 10 : Number(limitRaw);
+  if (!Number.isInteger(limit) || limit < 1) {
+    printError("--limit needs a positive integer, e.g. --limit 10");
+    return EXIT.USAGE;
+  }
+  let components;
+  try {
+    components = (await loadCatalog()).components;
+  } catch (err) {
+    printError(`could not read the component catalog (${err.message}). ` + "Reinstall @urbicon-ui/design-content, or run `docs:gen:all` in the monorepo.");
+    return EXIT.FAIL;
+  }
+  const results = query ? matchComponents(components, query, tags, limit) : components.filter((c) => !tags || c.tags.some((t) => tags.includes(t)));
+  if (asJson) {
+    console.log(JSON.stringify(results, null, 2));
+    return EXIT.OK;
+  }
+  if (results.length === 0) {
+    console.log(query ? `No components match "${query}". Try broader terms, or run \`urbicon find\` with no query to list all.` : `No components${tag ? ` tagged "${tag}"` : ""} in the catalog.`);
+    return EXIT.OK;
+  }
+  const header = query ? `${results.length} component(s) matching "${query}":` : `${results.length} component(s)${tag ? ` tagged "${tag}"` : ""}:`;
+  console.log(`${header}
+`);
+  for (const entry of results) {
+    console.log(`${formatEntry(entry)}
+`);
+  }
+  console.log("→ `urbicon get-component <slug>` for the full API · `get_css_reference` for tokens.");
+  return EXIT.OK;
+}
+
+// src/cli/commands/get-component.ts
+var SECTIONS = ["overview", "examples", "variants", "api", "slots"];
+async function runGetComponent(positionals, flags) {
+  const slug = positionals[0];
+  if (!slug) {
+    printError("get-component needs a component slug, e.g. `urbicon get-component button`");
+    return EXIT.USAGE;
+  }
+  const section = stringFlag(flags, "section");
+  if (section && section !== "full" && !SECTIONS.includes(section)) {
+    printError(`--section must be one of: ${SECTIONS.join(", ")}, full`);
+    return EXIT.USAGE;
+  }
+  let content;
+  try {
+    content = await loadComponentLlm(slug);
+  } catch (err) {
+    printError(`could not read component "${slug}" (${err.message}).`);
+    return EXIT.FAIL;
+  }
+  if (content === null) {
+    printError(`component "${slug}" not found. Run \`urbicon find <query>\` to discover the slug.`);
+    return EXIT.FAIL;
+  }
+  if (!section || section === "full") {
+    console.log(content.trim());
+    return EXIT.OK;
+  }
+  const extracted = extractSection2(content, section);
+  if (extracted === null) {
+    printError(`component "${slug}" has no "${section}" section. Try \`--section full\` or another of: ${SECTIONS.join(", ")}.`);
+    return EXIT.FAIL;
+  }
+  console.log(extracted);
+  return EXIT.OK;
+}
+
+// src/cli/commands/hook.ts
+import { readFile as readFile5 } from "node:fs/promises";
+import { resolve as resolve4 } from "node:path";
+// ../design-engine/src/linter/heuristics.ts
+var CHROMATIC_INTENTS = ["primary", "secondary", "success", "warning", "danger", "info"];
+var HEURISTIC_THRESHOLDS = {
+  rainbowIntentFamilies: 4,
+  minSpacingUtilities: 6,
+  minCards: 4,
+  minSurfacesForRadius: 3,
+  minFontWeights: 5,
+  touchTargetUnitCeil: 7,
+  hairlinePxFloor: 3
+};
+function collectAtoms(code) {
+  const atoms = [];
+  const stringRe = /["'`]([^"'`]*?)["'`]/g;
+  for (const m of code.matchAll(stringRe)) {
+    const body = m[1];
+    if (!/[a-z]-/.test(body) && !/\b(flex|grid|block|hidden|relative|absolute)\b/.test(body))
+      continue;
+    for (const atom of body.split(/\s+/)) {
+      if (atom)
+        atoms.push(atom);
+    }
+  }
+  return atoms;
+}
+function collectHits(lines, re) {
+  const hits = [];
+  lines.forEach((line, i) => {
+    for (const m of line.matchAll(re))
+      hits.push({ line: i + 1, match: m[0] });
+  });
+  return hits;
+}
+function lineOf(code, index) {
+  let line = 1;
+  for (let i = 0;i < index && i < code.length; i++) {
+    if (code[i] === `
+`)
+      line++;
+  }
+  return line;
+}
+function classValues(text) {
+  const out = [];
+  for (const m of text.matchAll(/\bclass=(?:"([^"]*)"|'([^']*)'|\{([^}]*)\})/g)) {
+    out.push(m[1] ?? m[2] ?? m[3] ?? "");
+  }
+  return out;
+}
+function slop(ruleId, hits, message, fix) {
+  if (hits.length === 0)
+    return [];
+  const first = hits[0];
+  return [
+    {
+      ruleId,
+      severity: "info",
+      kind: "heuristic",
+      message: typeof message === "function" ? message(hits.length, first) : message,
+      fix,
+      line: first.line,
+      match: first.match
+    }
+  ];
+}
+function checkIntentRainbow(atoms) {
+  const families = new Set;
+  const bgIntent = new RegExp(`^bg-(${CHROMATIC_INTENTS.join("|")})(?:-(?:hover|active|subtle|emphasis|\\d{2,3}))?(?:\\/\\d{1,3})?$`);
+  for (const atom of atoms) {
+    const m = atom.match(bgIntent);
+    if (m)
+      families.add(m[1]);
+  }
+  if (families.size >= HEURISTIC_THRESHOLDS.rainbowIntentFamilies) {
+    return [
+      {
+        ruleId: "intent-rainbow",
+        severity: "info",
+        kind: "heuristic",
+        message: `${families.size} different intent hues used as backgrounds (${[...families].join(", ")}). Reads as decoration, not meaning.`,
+        fix: "Let neutral surfaces dominate (80–90%). Reserve intent colour for genuine status/severity/action signals."
+      }
+    ];
+  }
+  return [];
+}
+function checkSpacingUniformity(atoms) {
+  const values = new Set;
+  let total = 0;
+  const spacingRe = /^(?:gap|gap-x|gap-y|space-x|space-y)-(\d+(?:\.\d+)?|px)$/;
+  for (const atom of atoms) {
+    const m = atom.match(spacingRe);
+    if (m) {
+      values.add(m[1]);
+      total++;
+    }
+  }
+  if (total >= HEURISTIC_THRESHOLDS.minSpacingUtilities && values.size <= 1) {
+    return [
+      {
+        ruleId: "spacing-uniform",
+        severity: "info",
+        kind: "heuristic",
+        message: `All ${total} spacing utilities use one value (\`${[...values][0] ?? "?"}\`). No tight-within vs generous-between rhythm.`,
+        fix: "Use two tiers: tight (`gap-2`/`gap-3`) within related items, generous (`gap-8`/`gap-10`) between sections."
+      }
+    ];
+  }
+  return [];
+}
+function checkCardMonotony(code) {
+  const cardRe = /<Card\b([^>]*)>/g;
+  const signatures = [];
+  for (const m of code.matchAll(cardRe)) {
+    const attrs = m[1];
+    const variant = attrs.match(/\bvariant=(?:"([^"]*)"|'([^']*)'|\{['"]([^'"]*)['"]\})/);
+    const padding = attrs.match(/\bpadding=(?:"([^"]*)"|'([^']*)'|\{['"]([^'"]*)['"]\})/);
+    const v = variant ? variant[1] ?? variant[2] ?? variant[3] : "default";
+    const p = padding ? padding[1] ?? padding[2] ?? padding[3] : "default";
+    signatures.push(`${v}/${p}`);
+  }
+  if (signatures.length >= HEURISTIC_THRESHOLDS.minCards) {
+    const distinct = new Set(signatures);
+    if (distinct.size === 1) {
+      return [
+        {
+          ruleId: "card-monotony",
+          severity: "info",
+          kind: "heuristic",
+          message: `All ${signatures.length} Cards share one look (\`${[...distinct][0]}\`). Visual weight does not vary.`,
+          fix: 'Differentiate: prominent content `variant="elevated"`/`padding="lg"`, secondary `variant="outlined"`/`padding="md"`.'
+        }
+      ];
+    }
+  }
+  return [];
+}
+function checkRadiusStrategy(code, atoms) {
+  const surfaceCount = (code.match(/<Card\b/g)?.length ?? 0) + (code.match(/<(?:Dialog|Drawer|Popover)\b/g)?.length ?? 0);
+  const hasRadiusOverride = atoms.some((a) => /^rounded(?:-|$)/.test(a));
+  if (surfaceCount >= HEURISTIC_THRESHOLDS.minSurfacesForRadius && !hasRadiusOverride) {
+    return [
+      {
+        ruleId: "no-radius-strategy",
+        severity: "info",
+        kind: "heuristic",
+        message: "Multiple surfaces but no explicit radius — relying solely on component defaults.",
+        fix: "If the default tier radii do not match your design identity, commit to one philosophy (`rounded-lg`/`rounded-xl`/`rounded-2xl`) applied consistently via `class`/`slotClasses`."
+      }
+    ];
+  }
+  return [];
+}
+function checkFontWeightUniformity(atoms) {
+  const weightRe = /^font-(thin|extralight|light|normal|medium|semibold|bold|extrabold|black)$/;
+  const values = new Set;
+  let total = 0;
+  for (const atom of atoms) {
+    const m = atom.match(weightRe);
+    if (m) {
+      values.add(m[1]);
+      total++;
+    }
+  }
+  if (total >= HEURISTIC_THRESHOLDS.minFontWeights && values.size === 1) {
+    return [
+      {
+        ruleId: "font-weight-uniform",
+        severity: "info",
+        kind: "heuristic",
+        message: `All ${total} explicit font-weights are \`font-${[...values][0]}\`. No typographic hierarchy.`,
+        fix: "Vary weight to rank content: headings `font-semibold`/`font-bold`, body `font-normal`, captions `font-medium text-text-tertiary`."
+      }
+    ];
+  }
+  return [];
+}
+var GENERIC_FONT_NAMES = "arial|helvetica|system-ui|-apple-system|blinkmacsystemfont|segoe ui|segoe|roboto|times new roman|times|georgia|courier|verdana|tahoma|sans-serif|monospace";
+var GENERIC_FONT_RE = new RegExp(`(?:font-\\[[^\\]]*?(?:${GENERIC_FONT_NAMES})[^\\]]*?\\]|font-family\\s*:\\s*[^;"'}]*(?:${GENERIC_FONT_NAMES}))`, "gi");
+function checkGenericFont(lines) {
+  return slop("generic-font", collectHits(lines, GENERIC_FONT_RE), "Hardcoded generic font stack (Arial/Helvetica/system-ui…). Defaults look like an unstyled draft, not a brand.", "Use the design-system typeface via the `font-*` family tokens (e.g. `font-sans`/`font-display`) so type carries identity.");
+}
+var ARBITRARY_COLOR_RE = /\b(?:bg|text|border|ring|fill|stroke|from|via|to|outline|decoration|shadow|divide|accent|caret|placeholder)-\[(?:#[0-9a-f]{3,8}|(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|color|hwb)\()/gi;
+function checkArbitraryColor(lines) {
+  return slop("arbitrary-color", collectHits(lines, ARBITRARY_COLOR_RE), "Arbitrary colour literal in a utility — outside the token system, so no dark-mode adaptation, no theming, no cohesion.", "Use a semantic token (`bg-surface-*`, `text-text-*`, intents) or `…-[var(--color-*)]` if you must reference a token by variable.");
+}
+var TRANSITION_ALL_RE = /\btransition-all\b/g;
+function checkTransitionAll(lines) {
+  return slop("transition-all", collectHits(lines, TRANSITION_ALL_RE), "`transition-all` animates every property that changes — including layout — which is janky and rarely intended.", "Transition only what changes: `transition-colors`, `transition-opacity`, `transition-transform`.");
+}
+var ANIMATED_DIM_BRACKET_RE = /\btransition-\[([^\]]*)\]/g;
+var ANIMATED_DIM_KEYWORD_RE = /\b(?:width|height|size|top|left|right|bottom|margin|padding)\b/;
+function checkAnimatedDimensions(lines) {
+  const hits = [];
+  lines.forEach((line, i) => {
+    for (const m of line.matchAll(ANIMATED_DIM_BRACKET_RE)) {
+      if (ANIMATED_DIM_KEYWORD_RE.test(m[1]))
+        hits.push({ line: i + 1, match: m[0] });
+    }
+  });
+  return slop("animated-dimensions", hits, "Transitioning a layout dimension (width/height/inset). These trigger layout on every frame and stutter.", "Animate `transform` (`scale`/`translate`) or `opacity` instead — they composite on the GPU. For size, use a `grid-template` trick or accept an instant change.");
+}
+var MAGIC_DIM_RE = /\b(?:w|h|min-w|min-h|max-w|max-h|size|gap|gap-x|gap-y|p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|top|left|right|bottom|inset)-\[(\d+(?:\.\d+)?)px\]/g;
+function checkMagicDimensions(lines) {
+  const hits = [];
+  lines.forEach((line, i) => {
+    for (const m of line.matchAll(MAGIC_DIM_RE)) {
+      if (Number.parseFloat(m[1]) >= HEURISTIC_THRESHOLDS.hairlinePxFloor) {
+        hits.push({ line: i + 1, match: m[0] });
+      }
+    }
+  });
+  return slop("magic-dimension", hits, (count, first) => `Arbitrary px dimension(s) off the spacing scale (${count} found, first \`${first.match}\`). Magic numbers drift from the rhythm.`, "Use scale utilities (`w-64`, `h-12`, `max-w-md`) or a relative bound (`max-w-prose`, `w-full`). Reserve arbitrary px for true one-offs.");
+}
+var IMPORTANT_RE = /(?<=[\s"'`])![a-z][a-z0-9]*-[a-z0-9[]/g;
+function checkImportant(lines) {
+  return slop("important-modifier", collectHits(lines, IMPORTANT_RE), (count, first) => `\`!important\` modifier(s) (${count} found, first \`${first.match}\`). Overriding the cascade by force is a smell, not a fix.`, "Remove the `!` and resolve the specificity conflict at its source (ordering, the component’s own props, or `slotClasses`).");
+}
+var INLINE_PAINT_RE = /(?:^|;|\s)(?:color|background(?:-color|-image)?|border(?:-(?:top|right|bottom|left))?-color|box-shadow|text-shadow|font-family|font-size|font-weight|fill|stroke|opacity)\s*:/i;
+function checkInlineStyle(lines) {
+  const hits = [];
+  const styleRe = /\bstyle=(?:"([^"]*)"|'([^']*)'|\{`([^`]*)`\})/g;
+  lines.forEach((line, i) => {
+    for (const m of line.matchAll(styleRe)) {
+      const body = m[1] ?? m[2] ?? m[3] ?? "";
+      if (/\{[^}]*\}|\$\{/.test(body))
+        continue;
+      if (INLINE_PAINT_RE.test(body))
+        hits.push({ line: i + 1, match: "style=…" });
+    }
+  });
+  return slop("inline-style", hits, (count) => `Inline \`style\` hardcodes colour/typography (${count} found). Bypasses the token system — no theming, no dark-mode adaptation.`, "Use semantic utilities/tokens (`bg-surface-*`, `text-text-*`, `font-*`). Keep inline `style` for genuinely dynamic values (interpolated sizes/positions, CSS custom properties).");
+}
+var GRADIENT_TEXT_RE = /\bbg-clip-text\b/g;
+function checkGradientText(lines) {
+  return slop("gradient-text", collectHits(lines, GRADIENT_TEXT_RE), "Gradient-clipped text (`bg-clip-text` + transparent fill) — a stock flourish that reads as generic and often fails contrast.", "Prefer a solid `text-*` token. If you need emphasis, vary weight/size or use a single intent colour.");
+}
+var INTENT_BG_RE = /\bbg-(?:primary|secondary|success|warning|danger|info)(?:-emphasis)?\b(?!-)/;
+var MUTED_TEXT_RE = /\btext-(?:text-(?:tertiary|quaternary|disabled|secondary)|muted|neutral-[345]00|gray-[345]00|slate-[345]00|zinc-[345]00|stone-[345]00)\b/;
+function checkGreyOnIntent(lines) {
+  const hits = [];
+  lines.forEach((line, i) => {
+    for (const value of classValues(line)) {
+      if (INTENT_BG_RE.test(value) && MUTED_TEXT_RE.test(value)) {
+        hits.push({ line: i + 1, match: value.trim().slice(0, 40) });
+      }
+    }
+  });
+  return slop("grey-on-intent", hits, "Muted/grey text on a saturated intent background. Low contrast and muddy — the colour stops carrying meaning.", "On an intent surface use the on-colour token (`text-on-primary`/`text-on-dark`). Reserve muted greys for neutral surfaces.");
+}
+var PARA_CLASS_RE = /<p\b[^>]*?\bclass=(?:"([^"]*)"|'([^']*)'|\{([^}]*)\})/g;
+function checkCenteredBodyText(code) {
+  const hits = [];
+  for (const m of code.matchAll(PARA_CLASS_RE)) {
+    const cls = m[1] ?? m[2] ?? m[3] ?? "";
+    if (/\btext-center\b/.test(cls)) {
+      hits.push({ line: lineOf(code, m.index ?? 0), match: "<p … text-center>" });
+    }
+  }
+  return slop("centered-bodytext", hits, "Centred paragraph text. Ragged left edges make multi-line copy hard to scan.", "Left-align body copy (`text-left`). Reserve `text-center` for short headings, single labels, or empty states.");
+}
+var JUSTIFIED_RE = /\btext-justify\b/g;
+function checkJustifiedText(lines) {
+  return slop("justified-text", collectHits(lines, JUSTIFIED_RE), 'Justified text. Without hyphenation the browser stretches word spacing into uneven "rivers" that hurt readability.', "Use `text-left` (`text-right` for RTL). Justification needs typographic control the web does not give by default.");
+}
+var PLACEHOLDER_RE = /\b(?:lorem ipsum|dolor sit amet|consectetur adipiscing|sed do eiusmod|the quick brown fox)\b/gi;
+function checkPlaceholderContent(lines) {
+  return slop("placeholder-content", collectHits(lines, PLACEHOLDER_RE), 'Lorem-ipsum / filler copy in the output. Placeholder text ships as "unfinished".', "Replace with real, representative content — it changes layout, length, and tone decisions.");
+}
+var EMOJI_RE = /[\u{1F300}-\u{1FAFF}\u{2705}\u{2728}\u{274C}\u{274E}\u{2753}-\u{2755}\u{2757}\u{2795}-\u{2797}\u{27B0}\u{27BF}\u{2B1B}\u{2B1C}\u{2B50}\u{2B55}\u{26A1}\u{2614}\u{2615}]|[\u{2300}-\u{27BF}\u{2B00}-\u{2BFF}]\u{FE0F}/gu;
+function checkEmojiAsIcon(lines) {
+  return slop("emoji-as-icon", collectHits(lines, EMOJI_RE), "Emoji in the markup as iconography. They render inconsistently across platforms and clash with a real icon set.", "Use the `Icon` component / a `*Icon` from the 315-icon set (`find_icons`) — consistent stroke, size, and theming.");
+}
+function checkHeadingSkip(code) {
+  const headings = [];
+  for (const m of code.matchAll(/<h([1-6])\b/g)) {
+    headings.push({ level: Number(m[1]), index: m.index ?? 0 });
+  }
+  for (let i = 1;i < headings.length; i++) {
+    const prev = headings[i - 1];
+    const cur = headings[i];
+    if (cur.level - prev.level >= 2) {
+      return [
+        {
+          ruleId: "heading-skip",
+          severity: "info",
+          kind: "heuristic",
+          message: `Heading jumps from <h${prev.level}> to <h${cur.level}>, skipping a level. Breaks the outline and screen-reader navigation.`,
+          fix: `Use sequential ranks (<h${prev.level}> → <h${prev.level + 1}>). Style size with classes, not by picking a smaller heading tag.`,
+          line: lineOf(code, cur.index)
+        }
+      ];
+    }
+  }
+  return [];
+}
+var SMALL_TOUCH_RE = new RegExp(`<(?:button|a)\\b[^>]*?(?<![\\w-])(?:h|size)-(?:[1-${HEURISTIC_THRESHOLDS.touchTargetUnitCeil}]|0\\.5|1\\.5|2\\.5|3\\.5)\\b`, "g");
+function checkTouchTarget(code) {
+  const hits = [];
+  for (const m of code.matchAll(SMALL_TOUCH_RE)) {
+    hits.push({ line: lineOf(code, m.index ?? 0), match: m[0].replace(/\s+/g, " ").slice(0, 40) });
+  }
+  return slop("touch-target-small", hits, "Interactive element with a fixed sub-44px height. Hard to tap; fails the 44×44 touch-target guideline.", "Give tappable controls ≥ `h-11` (44px) or enough padding (`py-2.5`+). Keep tiny sizes for decorative icons only.");
+}
+function runHeuristics(code) {
+  const atoms = collectAtoms(code);
+  const lines = code.split(`
+`);
+  return [
+    ...checkIntentRainbow(atoms),
+    ...checkSpacingUniformity(atoms),
+    ...checkCardMonotony(code),
+    ...checkRadiusStrategy(code, atoms),
+    ...checkFontWeightUniformity(atoms),
+    ...checkGenericFont(lines),
+    ...checkArbitraryColor(lines),
+    ...checkTransitionAll(lines),
+    ...checkAnimatedDimensions(lines),
+    ...checkMagicDimensions(lines),
+    ...checkImportant(lines),
+    ...checkInlineStyle(lines),
+    ...checkGradientText(lines),
+    ...checkGreyOnIntent(lines),
+    ...checkCenteredBodyText(code),
+    ...checkJustifiedText(lines),
+    ...checkPlaceholderContent(lines),
+    ...checkEmojiAsIcon(lines),
+    ...checkHeadingSkip(code),
+    ...checkTouchTarget(code)
+  ];
+}
+
+// ../design-engine/src/linter/markup.ts
+var blankRegion = (s) => s.replace(/[^\n]/g, " ");
+function blankNonMarkup(src) {
+  return src.replace(/<!--[\s\S]*?-->/g, blankRegion).replace(/<script[\s\S]*?<\/script>/gi, blankRegion).replace(/<style[\s\S]*?<\/style>/gi, blankRegion);
+}
+var isNameStart = (c) => c !== undefined && /[A-Za-z]/.test(c);
+var isTagNameChar = (c) => c !== undefined && /[A-Za-z0-9.\-:]/.test(c);
+var isAttrNameChar = (c) => c !== undefined && !/[\s=/>]/.test(c) && c !== "<";
+function readQuoted(src, i) {
+  const quote = src[i];
+  let j = i + 1;
+  while (j < src.length && src[j] !== quote)
+    j++;
+  return { value: src.slice(i + 1, j), end: j + 1 };
+}
+function readBraced(src, i) {
+  let depth = 0;
+  let str = null;
+  for (let j = i;j < src.length; j++) {
+    const c = src[j];
+    if (str !== null) {
+      if (c === "\\") {
+        j++;
+        continue;
+      }
+      if (c === str)
+        str = null;
+      continue;
+    }
+    if (c === '"' || c === "'")
+      str = c;
+    else if (c === "{")
+      depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth === 0)
+        return { value: src.slice(i + 1, j), end: j + 1 };
+    }
+  }
+  return { value: "", end: -1 };
+}
+function parseAttr(src, i, line) {
+  if (src[i] === "{") {
+    const { value, end } = readBraced(src, i);
+    if (end === -1)
+      return null;
+    const trimmed = value.trim();
+    const spread = trimmed.startsWith("...");
+    return {
+      attr: {
+        name: spread ? "" : trimmed,
+        value: spread ? trimmed.slice(3).trim() : trimmed,
+        kind: spread ? "spread" : "shorthand",
+        line
+      },
+      end
+    };
+  }
+  let j = i;
+  while (isAttrNameChar(src[j]))
+    j++;
+  const name = src.slice(i, j);
+  if (name === "")
+    return null;
+  let k = j;
+  while (k < src.length && /\s/.test(src[k]))
+    k++;
+  if (src[k] !== "=") {
+    return { attr: { name, value: null, kind: "boolean", line }, end: j };
+  }
+  k++;
+  while (k < src.length && /\s/.test(src[k]))
+    k++;
+  const c = src[k];
+  if (c === '"' || c === "'") {
+    const { value, end } = readQuoted(src, k);
+    return { attr: { name, value, kind: "string", line }, end };
+  }
+  if (c === "{") {
+    const { value, end } = readBraced(src, k);
+    if (end === -1)
+      return null;
+    return { attr: { name, value, kind: "expression", line }, end };
+  }
+  let m = k;
+  while (m < src.length && !/[\s/>]/.test(src[m]))
+    m++;
+  return { attr: { name, value: src.slice(k, m), kind: "string", line }, end: m };
+}
+function parseOpenTag(src, start, line) {
+  let i = start + 1;
+  while (isTagNameChar(src[i]))
+    i++;
+  const tag = src.slice(start + 1, i);
+  if (tag === "")
+    return null;
+  const attrs = [];
+  let curLine = line;
+  const bump = (from, to) => {
+    for (let p = from;p < to; p++)
+      if (src[p] === `
+`)
+        curLine++;
+  };
+  let selfClosing = false;
+  let closed = false;
+  while (i < src.length) {
+    const before = i;
+    while (i < src.length && /\s/.test(src[i]))
+      i++;
+    bump(before, i);
+    const c = src[i];
+    if (c === undefined)
+      break;
+    if (c === ">") {
+      i++;
+      closed = true;
+      break;
+    }
+    if (c === "/" && src[i + 1] === ">") {
+      selfClosing = true;
+      i += 2;
+      closed = true;
+      break;
+    }
+    const parsed = parseAttr(src, i, curLine);
+    if (!parsed)
+      return null;
+    attrs.push(parsed.attr);
+    bump(i, parsed.end);
+    i = parsed.end;
+  }
+  if (!closed)
+    return null;
+  const isComponent = /^[A-Z]/.test(tag) || tag.includes(".");
+  return {
+    element: { tag, isComponent, attrs, line, selfClosing, openStart: start, openEnd: i },
+    end: i
+  };
+}
+function scanMarkup(source) {
+  const src = blankNonMarkup(source);
+  const elements = [];
+  let line = 1;
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === `
+`) {
+      line++;
+      i++;
+      continue;
+    }
+    if (c === "<" && isNameStart(src[i + 1])) {
+      const parsed = parseOpenTag(src, i, line);
+      if (parsed) {
+        elements.push(parsed.element);
+        for (let p = i;p < parsed.end; p++)
+          if (src[p] === `
+`)
+            line++;
+        i = parsed.end;
+        continue;
+      }
+    }
+    i++;
+  }
+  return elements;
+}
+function tagAt(src, pos, tag, closing) {
+  const lead = closing ? `</${tag}` : `<${tag}`;
+  if (!src.startsWith(lead, pos))
+    return false;
+  const after = src[pos + lead.length];
+  return after === undefined || /[\s/>]/.test(after);
+}
+function innerContent(source, el) {
+  if (el.selfClosing)
+    return null;
+  const src = blankNonMarkup(source);
+  let depth = 1;
+  let i = el.openEnd;
+  while (i < src.length) {
+    if (src[i] === "<") {
+      if (tagAt(src, i, el.tag, true)) {
+        depth--;
+        if (depth === 0)
+          return src.slice(el.openEnd, i);
+      } else if (tagAt(src, i, el.tag, false)) {
+        depth++;
+      }
+    }
+    i++;
+  }
+  return null;
+}
+
+// ../design-engine/src/linter/markup-rules.ts
+var URBICON_COMPONENTS = new Set([
+  "Accordion",
+  "Alert",
+  "Avatar",
+  "Badge",
+  "Breadcrumb",
+  "Button",
+  "ButtonGroup",
+  "Card",
+  "Checkbox",
+  "Collapsible",
+  "Combobox",
+  "ConfirmDialog",
+  "Dialog",
+  "Drawer",
+  "FormField",
+  "Input",
+  "Menu",
+  "Pagination",
+  "Popover",
+  "Progress",
+  "RadioGroup",
+  "SegmentGroup",
+  "Select",
+  "Separator",
+  "Sidebar",
+  "Skeleton",
+  "Slider",
+  "Spinner",
+  "Stepper",
+  "Tab",
+  "Textarea",
+  "Toast",
+  "Toggle",
+  "Toolbar",
+  "Tooltip",
+  "AreaChart",
+  "BarChart",
+  "Calendar",
+  "ChartFrame",
+  "CommandPalette",
+  "CompositionBar",
+  "CurrencyInput",
+  "DatePicker",
+  "DonutChart",
+  "EmptyState",
+  "FileUpload",
+  "LineChart",
+  "LocaleSwitcher",
+  "Sankey",
+  "SidebarLayout",
+  "Sparkline",
+  "ThemeSwitcher",
+  "Table"
+]);
+var PROP_NAME_CONFUSIONS = {
+  tone: "intent",
+  colour: "intent",
+  colorScheme: "intent",
+  isLoading: "loading",
+  isDisabled: "disabled"
+};
+var VALUE_CONFUSIONS = {
+  variant: { outline: "outlined" }
+};
+var cache = null;
+function scanCached(raw) {
+  if (cache?.raw !== raw)
+    cache = { raw, els: scanMarkup(raw) };
+  return cache.els;
+}
+var apiHallucination = {
+  id: "api-hallucination",
+  severity: "warning",
+  description: 'Component prop/value from another UI library (e.g. `tone=`, `variant="outline"`) that Urbicon UI does not have.',
+  check(_lines, raw) {
+    const findings = [];
+    for (const el of scanCached(raw)) {
+      if (!el.isComponent || !URBICON_COMPONENTS.has(el.tag))
+        continue;
+      for (const attr of el.attrs) {
+        const rightName = PROP_NAME_CONFUSIONS[attr.name];
+        if (rightName) {
+          findings.push({
+            ruleId: this.id,
+            severity: this.severity,
+            kind: "deterministic",
+            message: `\`${el.tag}\` has no \`${attr.name}\` prop — that is another library's name.`,
+            fix: `Use \`${rightName}\` instead.`,
+            line: attr.line,
+            match: attr.name
+          });
+          continue;
+        }
+        if (attr.kind === "string" && attr.value !== null) {
+          const right = VALUE_CONFUSIONS[attr.name]?.[attr.value];
+          if (right) {
+            findings.push({
+              ruleId: this.id,
+              severity: this.severity,
+              kind: "deterministic",
+              message: `\`${attr.name}="${attr.value}"\` is not an Urbicon UI value.`,
+              fix: `Use \`${attr.name}="${right}"\`.`,
+              line: attr.line,
+              match: `${attr.name}="${attr.value}"`
+            });
+          }
+        }
+      }
+    }
+    return findings;
+  }
+};
+var LABEL_ATTRS = new Set(["aria-label", "aria-labelledby", "title"]);
+var ICON_CONTROL_TAGS = new Set(["Button", "button"]);
+function hasTextLabel(inner) {
+  return inner.replace(/<[^>]*>/g, "").trim().length > 0;
+}
+function hasIconChild(inner) {
+  return /<svg\b/i.test(inner) || /<[A-Za-z][\w.]*Icon\b/.test(inner) || /<Icon\b/.test(inner);
+}
+var iconButtonNoLabel = {
+  id: "icon-button-no-label",
+  severity: "warning",
+  description: "Icon-only Button/button with no accessible name (aria-label / title / text).",
+  check(_lines, raw) {
+    const findings = [];
+    for (const el of scanCached(raw)) {
+      if (!ICON_CONTROL_TAGS.has(el.tag))
+        continue;
+      if (el.attrs.some((a) => a.kind === "spread"))
+        continue;
+      const labelled = el.attrs.some((a) => LABEL_ATTRS.has(a.name) && a.value !== null && a.value.trim() !== "");
+      if (labelled)
+        continue;
+      const inner = innerContent(raw, el);
+      if (inner === null)
+        continue;
+      if (inner.includes("{"))
+        continue;
+      if (hasTextLabel(inner))
+        continue;
+      if (!hasIconChild(inner))
+        continue;
+      findings.push({
+        ruleId: this.id,
+        severity: this.severity,
+        kind: "deterministic",
+        message: `Icon-only \`<${el.tag}>\` has no accessible name — a screen reader announces nothing.`,
+        fix: 'Add an `aria-label="…"` (or visually-hidden text) naming the action.',
+        line: el.line
+      });
+    }
+    return findings;
+  }
+};
+var MARKUP_RULES = [apiHallucination, iconButtonNoLabel];
+
+// ../design-engine/src/linter/tokens.ts
+var SURFACE_CORES = [
+  "surface-base",
+  "surface-quiet",
+  "surface-subtle",
+  "surface-elevated",
+  "surface-overlay",
+  "surface-interactive",
+  "surface-hover",
+  "surface-active",
+  "surface-disabled",
+  "surface-selected",
+  "surface-inverted"
+];
+var TEXT_CORES = [
+  "text-primary",
+  "text-secondary",
+  "text-tertiary",
+  "text-quaternary",
+  "text-disabled",
+  "text-inverted",
+  "text-on-primary",
+  "text-on-dark",
+  "text-on-surface"
+];
+var BORDER_CORES = [
+  "border-subtle",
+  "border-default",
+  "border-emphasis",
+  "border-strong",
+  "border-hairline"
+];
+var INTENT_NAMES = [
+  "primary",
+  "secondary",
+  "success",
+  "warning",
+  "danger",
+  "info",
+  "neutral"
+];
+var INTENT_VARIANTS = ["hover", "active", "subtle", "emphasis"];
+var SCALE_STEPS = [
+  "50",
+  "100",
+  "200",
+  "300",
+  "400",
+  "500",
+  "600",
+  "700",
+  "800",
+  "900",
+  "950"
+];
+var NEUTRAL_EXTRA_STEPS = ["0", "25", "650", "750", "850"];
+var WARM_NEUTRAL_STEPS = SCALE_STEPS;
+var FEEDBACK_CORES = [
+  "feedback-info",
+  "feedback-info-subtle",
+  "feedback-success",
+  "feedback-success-subtle",
+  "feedback-warning",
+  "feedback-warning-subtle",
+  "feedback-error",
+  "feedback-error-subtle"
+];
+var INTERACTIVE_CORES = [
+  "interactive-hover",
+  "interactive-active",
+  "interactive-focus",
+  "interactive-disabled"
+];
+var CHART_CORES = ["chart-1", "chart-2", "chart-3", "chart-4", "chart-5", "chart-6"];
+function buildIntentCores() {
+  const cores = [];
+  for (const intent of INTENT_NAMES) {
+    cores.push(intent);
+    for (const variant of INTENT_VARIANTS)
+      cores.push(`${intent}-${variant}`);
+    for (const step of SCALE_STEPS)
+      cores.push(`${intent}-${step}`);
+  }
+  return cores;
+}
+var VALID_TOKEN_CORES = new Set([
+  ...SURFACE_CORES,
+  ...TEXT_CORES,
+  ...BORDER_CORES,
+  ...buildIntentCores(),
+  ...NEUTRAL_EXTRA_STEPS.map((s) => `neutral-${s}`),
+  ...WARM_NEUTRAL_STEPS.map((s) => `warm-neutral-${s}`),
+  ...FEEDBACK_CORES,
+  ...INTERACTIVE_CORES,
+  ...CHART_CORES
+]);
+function normalizeExtraTokens(extra) {
+  return extra.map((token) => token.trim()).filter((token) => token.length > 0);
+}
+function resolveValidTokenCores(extra) {
+  if (!extra || extra.length === 0)
+    return VALID_TOKEN_CORES;
+  const normalized = normalizeExtraTokens(extra);
+  if (normalized.length === 0)
+    return VALID_TOKEN_CORES;
+  const merged = new Set(VALID_TOKEN_CORES);
+  for (const core of normalized)
+    merged.add(core);
+  return merged;
+}
+var SEMANTIC_NAMESPACES = [
+  "surface-",
+  "text-",
+  "border-",
+  "feedback-",
+  "interactive-",
+  "chart-"
+];
+var INTENT_PREFIXES = INTENT_NAMES;
+var KNOWN_FOREIGN_CORES = new Set([
+  "foreground",
+  "background",
+  "muted",
+  "accent",
+  "card",
+  "popover",
+  "input",
+  "destructive",
+  "surface",
+  "muted-foreground",
+  "accent-foreground",
+  "card-foreground",
+  "popover-foreground",
+  "primary-foreground",
+  "secondary-foreground",
+  "destructive-foreground"
+]);
+var KNOWN_BAD_NAMESPACES = {
+  "status-": "Use a `feedback-*` token (feedback-success, feedback-error, …) or a bare intent (`success`, `danger`).",
+  "-fg": "Use `text-on-primary` / `text-on-surface` for foreground-on-intent text."
+};
+
+// ../design-engine/src/linter/rules.ts
+var SHADCN_FIX = "This is shadcn/ui vocabulary, not Urbicon UI. Use surface tokens (`bg-surface-base`/`-elevated`), text tokens (`text-text-primary`/`-secondary`), or intents (`bg-primary`, `text-success`).";
+function isForeignVocab(core) {
+  return KNOWN_FOREIGN_CORES.has(core) || core.endsWith("-foreground") || core === "fg" || core.startsWith("fg-");
+}
+var RAW_PALETTE = "slate|gray|zinc|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose";
+var COLOR_PREFIXES = [
+  "ring-offset",
+  "border-x",
+  "border-y",
+  "border-t",
+  "border-r",
+  "border-b",
+  "border-l",
+  "border-s",
+  "border-e",
+  "bg",
+  "text",
+  "border",
+  "ring",
+  "divide",
+  "outline",
+  "decoration",
+  "fill",
+  "stroke",
+  "from",
+  "via",
+  "to",
+  "accent",
+  "caret",
+  "placeholder"
+];
+var DYNAMIC_UTILITY_ROOTS = [
+  "gap",
+  "gap-x",
+  "gap-y",
+  "space-x",
+  "space-y",
+  "p",
+  "px",
+  "py",
+  "pt",
+  "pb",
+  "pl",
+  "pr",
+  "m",
+  "mx",
+  "my",
+  "mt",
+  "mb",
+  "ml",
+  "mr",
+  "w",
+  "h",
+  "min-w",
+  "min-h",
+  "max-w",
+  "max-h",
+  "size",
+  "text",
+  "bg",
+  "border",
+  "rounded",
+  "grid-cols",
+  "grid-rows",
+  "col-span",
+  "row-span",
+  "top",
+  "left",
+  "right",
+  "bottom",
+  "inset",
+  "z",
+  "leading",
+  "tracking",
+  "opacity",
+  "scale",
+  "rotate",
+  "translate-x",
+  "translate-y",
+  "duration",
+  "delay"
+];
+function dedupeByLine(findings) {
+  const seen = new Set;
+  const out = [];
+  for (const f of findings) {
+    const key = `${f.ruleId}:${f.line}:${f.match}`;
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    out.push(f);
+  }
+  return out;
+}
+var rawTailwindColor = {
+  id: "raw-tailwind-color",
+  severity: "error",
+  description: "Raw Tailwind palette colour (e.g. `bg-blue-500`) instead of a semantic token.",
+  check(lines) {
+    const re = new RegExp(`\\b(?:${COLOR_PREFIXES.join("|")})-(?:${RAW_PALETTE})-(?:50|100|200|300|400|500|600|700|800|900|950)(?:\\/\\d{1,3})?(?![a-z0-9-])`, "g");
+    const findings = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: "deterministic",
+          message: `Raw Tailwind colour \`${m[0]}\` bypasses the token system (no dark-mode adaptation, no theming).`,
+          fix: "Use a semantic token: `bg-surface-*`, `text-text-*`, `border-border-*`, or an intent (`bg-primary`, `text-success`).",
+          line: i + 1,
+          match: m[0]
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+var darkModeOverride = {
+  id: "dark-mode-override",
+  severity: "error",
+  description: "Manual `dark:` override instead of automatic `light-dark()` semantic tokens.",
+  check(lines) {
+    const re = /\bdark:[a-z[!]/g;
+    const findings = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: "deterministic",
+          message: "Manual `dark:` override. Dark mode resolves automatically via `light-dark()` semantic tokens.",
+          fix: "Remove the `dark:` variant and rely on semantic tokens (`bg-surface-elevated` etc.), which already switch.",
+          line: i + 1,
+          match: m[0].slice(0, -1)
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+var focusNotVisible = {
+  id: "focus-not-visible",
+  severity: "error",
+  description: "Plain `focus:` ring instead of keyboard-only `focus-visible:`.",
+  check(lines) {
+    const re = /\bfocus:(?=[a-z[])/g;
+    const findings = [];
+    lines.forEach((line, i) => {
+      for (const _ of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: "deterministic",
+          message: "`focus:` shows a focus ring on mouse clicks too. Keyboard-only rings are the house style.",
+          fix: "Use `focus-visible:` instead of `focus:`.",
+          line: i + 1,
+          match: "focus:"
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+var hardcodedZIndex = {
+  id: "hardcoded-z-index",
+  severity: "error",
+  description: "Hardcoded z-index instead of a `z-[var(--z-*)]` token.",
+  check(lines) {
+    const re = /\bz-(?:\d{1,4}|\[\d{1,4}\])(?![\w-])/g;
+    const findings = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: "deterministic",
+          message: `Hardcoded z-index \`${m[0]}\` collides with the layering scale and can sit behind/above the wrong overlay.`,
+          fix: "Use a z-index token: `z-[var(--z-modal)]`, `z-[var(--z-dropdown)]`, `z-[var(--z-tooltip)]`, …",
+          line: i + 1,
+          match: m[0]
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+var dynamicClassInterpolation = {
+  id: "dynamic-class-interpolation",
+  severity: "error",
+  description: "String-interpolated Tailwind class fragment (e.g. `gap-{x}`) — never compiled by Tailwind.",
+  check(lines) {
+    const re = new RegExp(`\\b(?:${DYNAMIC_UTILITY_ROOTS.join("|")})-(\\$\\{|\\{)`, "g");
+    const findings = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: "deterministic",
+          message: `Interpolated class fragment \`${m[0]}…\` — Tailwind only compiles static class names, so this utility is never generated.`,
+          fix: "Switch the whole class string per state: `class={isHero ? 'gap-4' : 'gap-3'}` — keep each utility a complete literal.",
+          line: i + 1,
+          match: m[0]
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+var tokenHallucination = {
+  id: "token-hallucination",
+  severity: "warning",
+  description: "Colour utility referencing a non-existent semantic token (e.g. `bg-status-danger`).",
+  check(lines, _raw, ctx) {
+    const validCores = ctx?.validTokenCores ?? VALID_TOKEN_CORES;
+    const prefixAlt = COLOR_PREFIXES.join("|");
+    const re = new RegExp(`\\b(${prefixAlt})-([a-z][a-z0-9-]*)(?:\\/\\d{1,3})?\\b`, "g");
+    const findings = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        const core = m[2];
+        if (!looksSemantic(core))
+          continue;
+        if (validCores.has(core))
+          continue;
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: "deterministic",
+          message: `\`${m[1]}-${core}\` is not a real token — likely hallucinated.`,
+          fix: suggestForBadCore(core),
+          line: i + 1,
+          match: m[0]
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+function looksSemantic(core) {
+  if (/^text-(?:xs|sm|base|lg|\d?xl)$/.test(core))
+    return false;
+  if (isForeignVocab(core))
+    return true;
+  if (SEMANTIC_NAMESPACES.some((ns) => core.startsWith(ns)))
+    return true;
+  if (core.startsWith("status-"))
+    return true;
+  for (const intent of INTENT_PREFIXES) {
+    if (core.startsWith(`${intent}-`))
+      return true;
+  }
+  if (core.endsWith("-fg"))
+    return true;
+  return false;
+}
+function suggestForBadCore(core) {
+  if (core === "foreground" || core.endsWith("-foreground") || core === "fg" || core.endsWith("-fg")) {
+    return "Use `text-on-primary` / `text-on-surface` for foreground-on-intent text, or `text-text-primary`/`-secondary` for general text.";
+  }
+  if (isForeignVocab(core))
+    return SHADCN_FIX;
+  for (const [bad, hint] of Object.entries(KNOWN_BAD_NAMESPACES)) {
+    if (bad.endsWith("-") ? core.startsWith(bad) : core.endsWith(bad))
+      return hint;
+  }
+  if (core.startsWith("surface-"))
+    return "Valid surfaces: surface-base/quiet/subtle/elevated/overlay/hover/active/selected/inverted.";
+  if (core.startsWith("feedback-"))
+    return "Valid feedback tokens: feedback-{info,success,warning,error}[-subtle].";
+  const intent = INTENT_NAMES.find((n) => core.startsWith(`${n}-`));
+  if (intent)
+    return `Valid \`${intent}\` variants: ${intent}, ${intent}-hover, ${intent}-active, ${intent}-subtle, ${intent}-emphasis, or a scale step ${intent}-50…${intent}-950.`;
+  return "Check `get_css_reference()` for the exact token name.";
+}
+var RULES = [
+  rawTailwindColor,
+  darkModeOverride,
+  focusNotVisible,
+  hardcodedZIndex,
+  dynamicClassInterpolation,
+  tokenHallucination,
+  ...MARKUP_RULES
+];
+
+// ../design-engine/src/linter/linter.ts
+var SCORE_WEIGHTS = {
+  error: 10,
+  warning: 5,
+  info: 2
+};
+var SLOP_WEIGHT = 10;
+function maskComments(code) {
+  const blankKeepNewlines = (s) => s.replace(/[^\n]/g, " ");
+  return code.replace(/<!--[\s\S]*?-->/g, blankKeepNewlines).replace(/\/\*[\s\S]*?\*\//g, blankKeepNewlines);
+}
+var SEVERITY_ORDER = { error: 0, warning: 1, info: 2 };
+function lintDesign(code, opts = {}) {
+  const masked = maskComments(code);
+  const lines = masked.split(`
+`);
+  const ctx = { validTokenCores: resolveValidTokenCores(opts.extraTokens) };
+  const findings = [];
+  for (const rule of RULES) {
+    findings.push(...rule.check(lines, masked, ctx));
+  }
+  if (!opts.skipHeuristics) {
+    findings.push(...runHeuristics(masked));
+  }
+  findings.sort((a, b) => {
+    const lineDiff = (a.line ?? Infinity) - (b.line ?? Infinity);
+    if (lineDiff !== 0)
+      return lineDiff;
+    return SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+  });
+  const counts = { error: 0, warning: 0, info: 0 };
+  let correctnessDeduction = 0;
+  let slopDeduction = 0;
+  for (const f of findings) {
+    counts[f.severity]++;
+    if (f.kind === "heuristic")
+      slopDeduction += SLOP_WEIGHT;
+    else
+      correctnessDeduction += SCORE_WEIGHTS[f.severity];
+  }
+  const scores = {
+    correctness: Math.max(0, 100 - correctnessDeduction),
+    slop: Math.max(0, 100 - slopDeduction)
+  };
+  return { findings, scores, counts, filename: opts.filename };
+}
+// src/cli/gate.ts
+function evaluateGate(reports, opts) {
+  const totals = { error: 0, warning: 0, info: 0 };
+  const slopBreaches = [];
+  for (const r of reports) {
+    totals.error += r.counts.error;
+    totals.warning += r.counts.warning;
+    totals.info += r.counts.info;
+    if (opts.slopFloor !== null && r.scores.slop < opts.slopFloor) {
+      slopBreaches.push({ label: r.filename ?? "<stdin>", slop: r.scores.slop });
+    }
+  }
+  const correctnessFailed = totals.error > 0 || opts.strict && totals.warning > 0;
+  return {
+    failed: correctnessFailed || slopBreaches.length > 0,
+    correctnessFailed,
+    totals,
+    slopBreaches
+  };
+}
+function parseSlopFloor(raw) {
+  if (raw === undefined)
+    return null;
+  if (typeof raw === "boolean")
+    return "invalid";
+  if (!/^\d{1,3}$/.test(raw.trim()))
+    return "invalid";
+  const n = Number(raw);
+  if (n > 100)
+    return "invalid";
+  return n;
+}
+
+// src/cli/commands/hook.ts
+var HOOK_BLOCK = 2;
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+function editedPaths(event) {
+  if (typeof event !== "object" || event === null)
+    return [];
+  const input = event.tool_input;
+  if (typeof input !== "object" || input === null)
+    return [];
+  const fp = input.file_path;
+  return typeof fp === "string" && fp.length > 0 ? [fp] : [];
+}
+async function runHook(_positionals, flags) {
+  const slopFloor = parseSlopFloor(flags["slop-floor"]);
+  if (slopFloor === "invalid") {
+    printError("--slop-floor needs an integer between 0 and 100, e.g. --slop-floor 40");
+    return EXIT.USAGE;
+  }
+  let event;
+  try {
+    event = JSON.parse(await readStdin());
+  } catch {
+    return EXIT.OK;
+  }
+  const paths = editedPaths(event).filter((p) => p.endsWith(".svelte"));
+  if (paths.length === 0)
+    return EXIT.OK;
+  const manifestPath = resolveManifestPath(stringFlag(flags, "manifest"));
+  const extraTokens = await readTokenOverrides(manifestPath);
+  const strict = boolFlag(flags, "strict");
+  const skipHeuristics = boolFlag(flags, "skip-heuristics");
+  const reports = [];
+  for (const p of paths) {
+    let code;
+    try {
+      code = await readFile5(resolve4(p), "utf-8");
+    } catch {
+      continue;
+    }
+    reports.push(lintDesign(code, { filename: p, skipHeuristics, extraTokens }));
+  }
+  if (reports.length === 0)
+    return EXIT.OK;
+  const gate = evaluateGate(reports, { strict, slopFloor });
+  if (!gate.failed)
+    return EXIT.OK;
+  const blocking = (r) => r.counts.error > 0 || strict && r.counts.warning > 0 || slopFloor !== null && r.scores.slop < slopFloor;
+  for (const report of reports.filter(blocking))
+    console.error(formatReport(report));
+  if (gate.slopBreaches.length > 0) {
+    console.error(`
+Below the slop floor (${slopFloor}): ` + gate.slopBreaches.map((b) => `${b.label} (${b.slop}/100)`).join(", "));
+  }
+  console.error(`
+Fix the issues above and re-save. — urbicon design gate`);
+  return HOOK_BLOCK;
+}
+
+// src/cli/commands/init.ts
+import { mkdir, readFile as readFile7, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname4, join as join2, relative as relative2, resolve as resolve6 } from "node:path";
+
+// src/cli/package-root.ts
+import { readFile as readFile6 } from "node:fs/promises";
+import { dirname as dirname3, resolve as resolve5 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+async function findPackageRoot() {
+  let dir = dirname3(fileURLToPath2(import.meta.url));
+  for (let i = 0;i < 6; i++) {
+    try {
+      const pkg = JSON.parse(await readFile6(resolve5(dir, "package.json"), "utf-8"));
+      if (pkg.name === "@urbicon-ui/design")
+        return dir;
+    } catch {}
+    const parent = dirname3(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return null;
+}
+
+// src/cli/commands/init.ts
+var BLOCK_START = "<!-- urbicon:start";
+var BLOCK_END = "<!-- urbicon:end -->";
+async function readTemplate(name) {
+  const root = await findPackageRoot();
+  if (!root)
+    throw new Error("could not locate the @urbicon-ui/design package root");
+  return readFile7(join2(root, "templates", name), "utf-8");
+}
+async function readOrNull(path) {
+  try {
+    return await readFile7(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function upsertBlock(existing, block) {
+  const startIdx = existing.indexOf(BLOCK_START);
+  if (startIdx !== -1) {
+    const endIdx = existing.indexOf(BLOCK_END, startIdx);
+    if (endIdx === -1) {
+      throw new Error(`found an unterminated \`${BLOCK_START}\` marker (no \`${BLOCK_END}\`) — remove the partial block and re-run`);
+    }
+    const content = existing.slice(0, startIdx) + block.trim() + existing.slice(endIdx + BLOCK_END.length);
+    return { content, replaced: true };
+  }
+  const sep2 = existing.length === 0 ? "" : existing.endsWith(`
+
+`) ? "" : existing.endsWith(`
+`) ? `
+` : `
+
+`;
+  return { content: `${existing}${sep2}${block.trim()}
+`, replaced: false };
+}
+async function mergeHook(settingsPath) {
+  const existing = await readOrNull(settingsPath);
+  let settings;
+  try {
+    settings = existing ? JSON.parse(existing) : {};
+  } catch {
+    throw new Error("invalid JSON — merge templates/claude-settings.json by hand");
+  }
+  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+    throw new Error("unexpected shape (not a JSON object) — merge templates/claude-settings.json by hand");
+  }
+  settings.hooks ??= {};
+  settings.hooks.PostToolUse ??= [];
+  if (JSON.stringify(settings.hooks.PostToolUse).includes("urbicon hook"))
+    return "present";
+  settings.hooks.PostToolUse.push({
+    matcher: "Edit|MultiEdit|Write",
+    hooks: [{ type: "command", command: "urbicon hook" }]
+  });
+  await mkdir(dirname4(settingsPath), { recursive: true });
+  await writeFile2(settingsPath, `${JSON.stringify(settings, null, 2)}
+`, "utf-8");
+  return "added";
+}
+async function runInit(_positionals, flags) {
+  const cwd = process.cwd();
+  const rel = (p) => relative2(cwd, p) || p;
+  const done = [];
+  const skipped = [];
+  let block;
+  try {
+    block = await readTemplate("AGENTS.md");
+  } catch (err) {
+    printError(err.message);
+    return EXIT.FAIL;
+  }
+  const agentsPath = resolve6(stringFlag(flags, "agents-file") ?? "AGENTS.md");
+  const existingAgents = await readOrNull(agentsPath) ?? "";
+  let upserted;
+  try {
+    upserted = upsertBlock(existingAgents, block);
+  } catch (err) {
+    printError(`${rel(agentsPath)}: ${err.message}`);
+    return EXIT.FAIL;
+  }
+  await writeFile2(agentsPath, upserted.content, "utf-8");
+  const verb = upserted.replaced ? "refreshed" : existingAgents ? "added" : "created";
+  done.push(`${rel(agentsPath)} — ${verb} the Urbicon UI context block`);
+  const manifestPath = resolveManifestPath(stringFlag(flags, "manifest"));
+  if (await readOrNull(manifestPath)) {
+    skipped.push(`${rel(manifestPath)} — already present (kept your intent)`);
+  } else {
+    await writeFile2(manifestPath, createManifestTemplate({}), "utf-8");
+    done.push(`${rel(manifestPath)} — scaffolded`);
+  }
+  if (boolFlag(flags, "hook")) {
+    const settingsPath = resolve6(".claude", "settings.json");
+    try {
+      const result = await mergeHook(settingsPath);
+      (result === "added" ? done : skipped).push(`${rel(settingsPath)} — ${result === "added" ? "wired" : "already has"} the PostToolUse \`urbicon hook\``);
+    } catch (err) {
+      skipped.push(`${rel(settingsPath)} — skipped (${err.message})`);
+    }
+  }
+  if (boolFlag(flags, "ci")) {
+    const ciPath = resolve6(".github", "workflows", "design-gate.yml");
+    if (await readOrNull(ciPath)) {
+      skipped.push(`${rel(ciPath)} — already present`);
+    } else {
+      const ci = await readTemplate("ci-github.yml");
+      await mkdir(dirname4(ciPath), { recursive: true });
+      await writeFile2(ciPath, ci, "utf-8");
+      done.push(`${rel(ciPath)} — wrote the design-gate workflow`);
+    }
+  }
+  console.log(`urbicon init — project wired into the design loop
+`);
+  for (const d of done)
+    console.log(`  ✓ ${d}`);
+  for (const s of skipped)
+    console.log(`  · ${s}`);
+  console.log(`
+Next steps:`);
+  console.log("  • Make sure your agent reads AGENTS.md (or paste the block into CLAUDE.md / .cursorrules).");
+  console.log("  • Seed the design memory: `bunx urbicon verb adopt` (brownfield) or `onboard` (greenfield) — the guided intake.");
+  if (!boolFlag(flags, "hook")) {
+    console.log("  • Enforce at edit time: re-run with `--hook` to wire the PostToolUse gate.");
+  }
+  if (!boolFlag(flags, "ci")) {
+    console.log("  • Enforce in CI: re-run with `--ci`, or add `bunx urbicon validate src/` to your pipeline.");
+  }
+  return EXIT.OK;
+}
+
+// src/cli/commands/record-decision.ts
+var STATUSES = new Set(["accepted", "proposed", "superseded"]);
+var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+async function runRecordDecision(_positionals, flags) {
+  const title = stringFlag(flags, "title");
+  const decision = stringFlag(flags, "decision");
+  if (!title || !decision) {
+    printError("record-decision requires --title and --decision");
+    return EXIT.USAGE;
+  }
+  const status = stringFlag(flags, "status") ?? "accepted";
+  if (!STATUSES.has(status)) {
+    printError(`invalid --status "${status}" (accepted | proposed | superseded)`);
+    return EXIT.USAGE;
+  }
+  const date = stringFlag(flags, "date") ?? new Date().toISOString().slice(0, 10);
+  if (!DATE_RE.test(date)) {
+    printError(`invalid --date "${date}" (expected YYYY-MM-DD)`);
+    return EXIT.USAGE;
+  }
+  const path = resolveManifestPath(stringFlag(flags, "manifest"));
+  if (!path.endsWith(".md")) {
+    printError(`refusing to write: "${path}" is not a .md file`);
+    return EXIT.USAGE;
+  }
+  const { content, created } = await readOrCreateManifest(path);
+  const updated = appendDecision(content, {
+    date,
+    title,
+    status,
+    decision,
+    rationale: stringFlag(flags, "rationale")
+  });
+  try {
+    await writeManifest(path, updated);
+  } catch (err) {
+    printError(`failed to write ${path}: ${err.message}`);
+    return EXIT.FAIL;
+  }
+  const total = parseManifest(updated).decisions.length;
+  console.log(`Recorded ADR "${title}" (${date}) in ${path}${created ? " (created the manifest)" : ""}. ` + `${total} decision(s) on record.`);
+  return EXIT.OK;
+}
+
+// src/cli/commands/sync-manifest.ts
+import { dirname as dirname5 } from "node:path";
+async function runSyncManifest(_positionals, flags) {
+  const path = resolveManifestPath(stringFlag(flags, "manifest"));
+  if (!path.endsWith(".md")) {
+    printError(`refusing to write: "${path}" is not a .md file`);
+    return EXIT.USAGE;
+  }
+  const src = resolveSourceDir(stringFlag(flags, "src"));
+  const usages = await scanMarkers(src, dirname5(path));
+  const { content, created } = await readOrCreateManifest(path);
+  const updated = upsertUsagesSection(content, usages);
+  try {
+    await writeManifest(path, updated);
+  } catch (err) {
+    printError(`failed to write ${path}: ${err.message}`);
+    return EXIT.FAIL;
+  }
+  const byPattern = new Map;
+  for (const usage of usages)
+    byPattern.set(usage.pattern, (byPattern.get(usage.pattern) ?? 0) + 1);
+  if (boolFlag(flags, "json")) {
+    console.log(JSON.stringify({ manifest: path, created, scanned: src, usages }, null, 2));
+    return EXIT.OK;
+  }
+  let text = `Synced ${path}${created ? " (created it)" : ""} — scanned ${src}, ${usages.length} marker(s)`;
+  if (byPattern.size > 0) {
+    const summary = [...byPattern].sort((a, b) => a[0].localeCompare(b[0])).map(([pattern, n]) => `${pattern} (${n})`).join(", ");
+    text += ` across ${byPattern.size} pattern(s): ${summary}.`;
+  } else {
+    text += '. No markers yet — add data-design-pattern="<name>" to pattern-following pages.';
+  }
+  console.log(text);
+  return EXIT.OK;
+}
+
+// src/cli/commands/validate.ts
+import { readdir as readdir2, readFile as readFile8, stat as stat2 } from "node:fs/promises";
+import { join as join3, relative as relative3, resolve as resolve7, sep as sep2 } from "node:path";
+var SKIP_DIRS2 = new Set([
+  "node_modules",
+  ".svelte-kit",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  ".turbo",
+  "coverage"
+]);
+var MAX_DEPTH2 = 24;
+function label(abs) {
+  return relative3(process.cwd(), abs).split(sep2).join("/") || abs;
+}
+async function collectSvelte(dir, depth = 0) {
+  if (depth > MAX_DEPTH2)
+    return [];
+  let entries;
+  try {
+    entries = await readdir2(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS2.has(entry.name) || entry.name.startsWith("."))
+        continue;
+      files.push(...await collectSvelte(join3(dir, entry.name), depth + 1));
+    } else if (entry.isFile() && entry.name.endsWith(".svelte")) {
+      files.push(join3(dir, entry.name));
+    }
+  }
+  return files;
+}
+async function readStdin2() {
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+async function gather(positionals) {
+  if (positionals.length === 0 || positionals.length === 1 && positionals[0] === "-") {
+    return [{ label: "<stdin>", code: await readStdin2() }];
+  }
+  const units = [];
+  for (const p of positionals) {
+    if (p === "-") {
+      units.push({ label: "<stdin>", code: await readStdin2() });
+      continue;
+    }
+    const abs = resolve7(p);
+    let info;
+    try {
+      info = await stat2(abs);
+    } catch {
+      printError(`cannot read "${p}"`);
+      return null;
+    }
+    if (info.isDirectory()) {
+      for (const file of await collectSvelte(abs)) {
+        units.push({ label: label(file), code: await readFile8(file, "utf-8") });
+      }
+    } else {
+      units.push({ label: label(abs), code: await readFile8(abs, "utf-8") });
+    }
+  }
+  return units;
+}
+function buildHistoryEntry(reports) {
+  const files = reports.length;
+  const sum = (pick) => reports.reduce((a, r) => a + pick(r), 0);
+  const mean = (pick) => files === 0 ? 100 : Math.round(sum(pick) / files);
+  return {
+    date: new Date().toISOString(),
+    files,
+    errors: sum((r) => r.counts.error),
+    warnings: sum((r) => r.counts.warning),
+    infos: sum((r) => r.counts.info),
+    correctness: mean((r) => r.scores.correctness),
+    slop: mean((r) => r.scores.slop)
+  };
+}
+async function runValidate(positionals, flags) {
+  const asJson = boolFlag(flags, "json");
+  const strict = boolFlag(flags, "strict");
+  const skipHeuristics = boolFlag(flags, "skip-heuristics");
+  const record = boolFlag(flags, "record");
+  const slopFloor = parseSlopFloor(flags["slop-floor"]);
+  if (slopFloor === "invalid") {
+    printError("--slop-floor needs an integer between 0 and 100, e.g. --slop-floor 40");
+    return EXIT.USAGE;
+  }
+  const manifestPath = resolveManifestPath(stringFlag(flags, "manifest"));
+  const extraTokens = await readTokenOverrides(manifestPath);
+  const units = await gather(positionals);
+  if (units === null)
+    return EXIT.USAGE;
+  if (units.length === 0) {
+    printError("no .svelte files found to validate");
+    return EXIT.USAGE;
+  }
+  const reports = units.map((unit) => lintDesign(unit.code, { filename: unit.label, skipHeuristics, extraTokens }));
+  const gate = evaluateGate(reports, { strict, slopFloor });
+  const { totals, failed } = gate;
+  if (record) {
+    const line = serializeHistoryEntry(buildHistoryEntry(reports));
+    try {
+      await appendHistory(manifestPath, line);
+    } catch (err) {
+      printError(`failed to record history to ${resolveHistoryPath(manifestPath)}: ${err.message}`);
+    }
+  }
+  if (asJson) {
+    console.log(JSON.stringify({ ok: !failed, strict, slopFloor, extraTokens, results: reports }, null, 2));
+    return failed ? EXIT.FAIL : EXIT.OK;
+  }
+  for (const report of reports)
+    console.log(formatReport(report));
+  if (reports.length > 1) {
+    console.log(`
+${reports.length} file(s) · ${totals.error} error(s), ` + `${totals.warning} warning(s), ${totals.info} note(s)`);
+  }
+  if (extraTokens.length > 0) {
+    console.log(`
+${extraTokens.length} project token override(s) applied from ${relative3(process.cwd(), manifestPath).split(sep2).join("/")}.`);
+  }
+  if (gate.slopBreaches.length > 0) {
+    console.log(`
+${gate.slopBreaches.length} file(s) below the slop floor (${slopFloor}):`);
+    for (const b of gate.slopBreaches)
+      console.log(`  · ${b.label} — slop ${b.slop}/100`);
+  }
+  if (failed) {
+    const reason = gate.correctnessFailed ? strict ? "errors or warnings present (--strict)" : "fix the errors above" : "slop floor not met";
+    console.log(`
+FAIL — ${reason}.`);
+  }
+  return failed ? EXIT.FAIL : EXIT.OK;
+}
+
+// src/cli/commands/verb.ts
+import { readdir as readdir3, readFile as readFile9 } from "node:fs/promises";
+import { resolve as resolve8 } from "node:path";
+var SAFE_VERB = /^[a-z][a-z0-9-]*$/;
+async function resolveVerbsDir() {
+  const root = await findPackageRoot();
+  return root ? resolve8(root, "skill", "verbs") : null;
+}
+function purposeOf(body) {
+  const heading = body.split(`
+`, 1)[0] ?? "";
+  const m = heading.match(/^#\s+[a-z-]+\s+[—-]\s+(.+)$/);
+  return m ? m[1].trim() : "";
+}
+async function runVerbList(_positionals, _flags) {
+  const dir = await resolveVerbsDir();
+  if (!dir) {
+    printError("could not locate the bundled skill — reinstall @urbicon-ui/design");
+    return EXIT.FAIL;
+  }
+  let files;
+  try {
+    files = (await readdir3(dir)).filter((f) => f.endsWith(".md")).sort();
+  } catch {
+    printError(`no verb recipes found at ${dir}`);
+    return EXIT.FAIL;
+  }
+  console.log("Design verbs — run `urbicon verb <name>` to print one:\n");
+  for (const file of files) {
+    const name = file.replace(/\.md$/, "");
+    let purpose = "";
+    try {
+      purpose = purposeOf(await readFile9(resolve8(dir, file), "utf-8"));
+    } catch {}
+    console.log(`  ${name.padEnd(10)} ${purpose}`);
+  }
+  return EXIT.OK;
+}
+async function runVerb(positionals, _flags) {
+  const name = positionals[0];
+  if (!name) {
+    printError("verb requires a name, e.g. `urbicon verb compose` (list them with `urbicon verbs`)");
+    return EXIT.USAGE;
+  }
+  if (!SAFE_VERB.test(name)) {
+    printError(`invalid verb name "${name}"`);
+    return EXIT.USAGE;
+  }
+  const dir = await resolveVerbsDir();
+  if (!dir) {
+    printError("could not locate the bundled skill — reinstall @urbicon-ui/design");
+    return EXIT.FAIL;
+  }
+  try {
+    console.log(await readFile9(resolve8(dir, `${name}.md`), "utf-8"));
+    return EXIT.OK;
+  } catch {
+    printError(`unknown verb "${name}" — list the available verbs with \`urbicon verbs\``);
+    return EXIT.USAGE;
+  }
+}
+
+// src/cli/index.ts
+var HELP = `urbicon — design validation & manifest tooling for Urbicon UI projects
+
+Usage:
+  urbicon <command> [options]
+
+Commands:
+  init                  Wire this project into the design loop: insert the AGENTS.md
+                        context block + scaffold design.manifest.md, then print next
+                        steps. Idempotent and non-destructive.
+                        --hook             Also merge the PostToolUse gate into
+                                           .claude/settings.json.
+                        --ci               Also write .github/workflows/design-gate.yml.
+                        --agents-file <p>  Target for the context block (default AGENTS.md).
+                        --manifest <path>  Manifest path (default ./design.manifest.md).
+  validate [paths...]   Lint .svelte markup against the Urbicon UI design rules.
+                        Paths may be files, directories, or "-" (stdin).
+                        Reads ## Token Overrides from the manifest (if any) so your
+                        project's own tokens are not flagged as hallucinated.
+                        --json             Machine-readable report ({ ok, slopFloor, results }).
+                        --strict           Fail on warnings too, not just errors.
+                        --slop-floor <n>   Also fail any file scoring below n/100 on the
+                                           slop axis (0–100; off by default — slop is advisory).
+                        --skip-heuristics  Deterministic rules only (no distribution notes).
+                        --record           Append a drift entry to the sidecar history (CI).
+                        --manifest <path>  Manifest for token overrides + history
+                                           (default ./design.manifest.md).
+  hook                  Editor-hook adapter: read a Claude Code PostToolUse event on
+                        stdin, validate the edited .svelte file, and exit 2 with the
+                        findings on stderr so the agent self-corrects. Takes the same
+                        gate flags as validate (--strict, --slop-floor, --manifest).
+                        Wire it via .claude/settings.json (see templates/).
+  find [query]          Discover components by fuzzy search over the version-pinned
+                        catalog (names, tags, descriptions). No query lists all.
+                        --tag <t>          Filter by category tag (form, action, …).
+                        --limit <n>        Max results for a query (default 10).
+                        --json             Machine-readable catalog entries.
+  get-component <slug>  Print a component's API (its llm.txt) from the bundle.
+                        --section <s>      overview | examples | variants | api | slots |
+                                           full (default: full).
+  context               Print the project's design.manifest.md summary.
+                        --manifest <path>  Manifest file (default ./design.manifest.md).
+                        --json             Emit the parsed manifest as JSON.
+  record-decision       Append an ADR to the manifest.
+                        --title <t>        (required) Short decision title.
+                        --decision <d>     (required) What was decided.
+                        --rationale <r>    Why — the trade-off.
+                        --status <s>       accepted | proposed | superseded (default accepted).
+                        --date <date>      Decision date, YYYY-MM-DD (default today).
+                        --manifest <path>  Manifest file (default ./design.manifest.md).
+  sync-manifest         Re-index data-design-pattern markers into the manifest.
+                        --src <dir>        Source tree to scan (default ./src).
+                        --manifest <path>  Manifest file (default ./design.manifest.md).
+                        --json             Emit the scan result as JSON.
+  verbs                 List the design verbs (recipes over the design loop).
+  verb <name>           Print one verb recipe, e.g. "urbicon verb compose".
+  help                  Show this help.
+
+Exit codes:
+  0  ok (clean, or only warnings/notes)
+  1  failed — validate found errors (--strict: warnings too), or a command could not complete
+  2  usage error — bad flags / unreadable input
+
+Examples:
+  urbicon validate src/                          # CI: lint a whole tree
+  urbicon validate src/ --slop-floor 40 --json   # CI: gate correctness + slop
+  urbicon validate App.svelte --strict           # fail on warnings too
+  cat Page.svelte | urbicon validate -           # lint stdin
+  urbicon record-decision --title "Tabs for settings" --decision "Use Tab over Sidebar"
+`;
+async function readVersion() {
+  const root = await findPackageRoot();
+  if (!root)
+    return "unknown";
+  try {
+    const pkg = JSON.parse(await readFile10(resolve9(root, "package.json"), "utf-8"));
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function main(argv) {
+  const { command, positionals, flags } = parseArgs(argv);
+  if (flags.version === true || command === "version") {
+    console.log(await readVersion());
+    return EXIT.OK;
+  }
+  if (command === undefined || command === "help" || flags.help === true) {
+    console.log(HELP);
+    return EXIT.OK;
+  }
+  switch (command) {
+    case "init":
+      return runInit(positionals, flags);
+    case "validate":
+      return runValidate(positionals, flags);
+    case "hook":
+      return runHook(positionals, flags);
+    case "find":
+      return runFind(positionals, flags);
+    case "get-component":
+      return runGetComponent(positionals, flags);
+    case "context":
+      return runContext(positionals, flags);
+    case "record-decision":
+      return runRecordDecision(positionals, flags);
+    case "sync-manifest":
+      return runSyncManifest(positionals, flags);
+    case "verbs":
+      return runVerbList(positionals, flags);
+    case "verb":
+      return runVerb(positionals, flags);
+    default:
+      printError(`unknown command "${command}"`);
+      console.log(`
+${HELP}`);
+      return EXIT.USAGE;
+  }
+}
+main(process.argv.slice(2)).then((code) => process.exit(code)).catch((err) => {
+  printError(err instanceof Error ? err.message : String(err));
+  process.exit(EXIT.FAIL);
+});