@urbicon-ui/design 6.2.0 → 6.3.3

package/README.md

@@ -20,6 +20,17 @@ bun add -d @urbicon-ui/design   # dev tooling — not a runtime dependency
 This exposes the `urbicon` command (a self-contained, Node-runnable bundle — no
 Bun required at the consumer side).
 
+> **Running it standalone (no local install).** The bin is `urbicon` but the package
+> is `@urbicon-ui/design`, so a bare `bunx urbicon …` from a project that hasn't
+> installed it fails with `GET …/urbicon 404` (it looks for a package literally named
+> `urbicon`). To run the CLI without a local install, name both the package and the bin:
+>
+> ```bash
+> bunx --package @urbicon-ui/design urbicon validate src/   # or: npx --package @urbicon-ui/design urbicon …
+> ```
+>
+> Inside a project that already has `@urbicon-ui/design` installed, plain `bunx urbicon …` resolves fine.
+
 ## Onboarding a consumer project
 
 ```bash

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli/index.ts
 import { readFile as readFile10 } from "node:fs/promises";
-import { resolve as resolve9 } from "node:path";
+import { resolve as resolve10 } from "node:path";
 
 // src/cli/args.ts
 var BOOLEAN_FLAGS = new Set([
@@ -168,12 +168,22 @@ function parseIntent(body) {
     return emptyIntent();
   const lines = section.split(`
 `);
+  const isFieldOrHeading = (l) => /^\*\*[^*]+:\*\*/.test(l) || /^#{1,6}\s/.test(l);
   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();
+    const labelRe = new RegExp(`^\\*\\*${label}:\\*\\*\\s*(.*)$`);
+    for (let i = 0;i < lines.length; i++) {
+      const m = lines[i].match(labelRe);
+      if (!m)
+        continue;
+      const parts = m[1].trim() ? [m[1].trim()] : [];
+      for (let j = i + 1;j < lines.length; j++) {
+        const l = lines[j];
+        if (l.trim() === "" || isFieldOrHeading(l))
+          break;
+        parts.push(l.trim());
+      }
+      const value = parts.join(" ").trim();
+      return value === "" ? undefined : value;
     }
     return;
   };
@@ -181,22 +191,33 @@ function parseIntent(body) {
     const items = [];
     const labelRe = new RegExp(`^\\*\\*${label}:\\*\\*\\s*(.*)$`);
     let capturing = false;
+    let inInlineRun = false;
     for (const l of lines) {
       if (!capturing) {
         const m = l.match(labelRe);
         if (m) {
           capturing = true;
+          inInlineRun = true;
           const inline = m[1].trim();
           if (inline)
             items.push(...splitList(inline));
         }
         continue;
       }
-      if (/^\*\*[^*]+:\*\*/.test(l))
+      if (isFieldOrHeading(l))
         break;
       const bullet = l.match(/^\s*[-*]\s+(.+)$/);
-      if (bullet)
+      if (bullet) {
         items.push(bullet[1].trim());
+        inInlineRun = false;
+        continue;
+      }
+      if (l.trim() === "") {
+        inInlineRun = false;
+        continue;
+      }
+      if (inInlineRun)
+        items.push(...splitList(l.trim()));
     }
     return items;
   };
@@ -811,6 +832,51 @@ async function loadComponentLlm(slug) {
   return null;
 }
 
+// src/cli/installed.ts
+import { readFileSync } from "node:fs";
+import { dirname as dirname3, join as join2, parse, resolve as resolve4 } from "node:path";
+var DEP_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies"
+];
+function readConsumerDependencies(cwd = process.cwd()) {
+  let dir = resolve4(cwd);
+  const { root } = parse(dir);
+  for (;; ) {
+    try {
+      const pkg = JSON.parse(readFileSync(join2(dir, "package.json"), "utf-8"));
+      const names = new Set;
+      for (const field of DEP_FIELDS) {
+        const deps = pkg[field];
+        if (deps && typeof deps === "object") {
+          for (const name of Object.keys(deps))
+            names.add(name);
+        }
+      }
+      return names;
+    } catch {}
+    if (dir === root)
+      return null;
+    dir = dirname3(dir);
+  }
+}
+function installStateFor(pkg, deps) {
+  if (!deps)
+    return "unknown";
+  let hasUrbiconContext = false;
+  for (const d of deps) {
+    if (d.startsWith("@urbicon-ui/")) {
+      hasUrbiconContext = true;
+      break;
+    }
+  }
+  if (!hasUrbiconContext)
+    return "unknown";
+  return deps.has(pkg) ? "installed" : "missing";
+}
+
 // 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(" · ");
@@ -820,8 +886,14 @@ function shortDescription(description) {
 `)[0]?.trim() ?? "";
   return firstLine.length > 140 ? `${firstLine.slice(0, 139)}…` : firstLine;
 }
-function formatEntry(entry) {
-  const lines = [`  ${entry.name}  ·  ${entry.slug}`, `    ${shortDescription(entry.description)}`];
+function packageTag(entry, state) {
+  return state === "missing" ? `${entry.package}  ·  ⚠ not installed` : entry.package;
+}
+function formatEntry(entry, state) {
+  const lines = [
+    `  ${entry.name}  ·  ${entry.slug}  ·  ${packageTag(entry, state)}`,
+    `    ${shortDescription(entry.description)}`
+  ];
   const variants = variantSummary(entry);
   if (variants)
     lines.push(`    ${variants}`);
@@ -850,8 +922,14 @@ async function runFind(positionals, flags) {
     return EXIT.FAIL;
   }
   const results = query ? matchComponents(components, query, tags, limit) : components.filter((c) => !tags || c.tags.some((t) => tags.includes(t)));
+  const deps = readConsumerDependencies();
+  const stateOf = (entry) => installStateFor(entry.package, deps);
   if (asJson) {
-    console.log(JSON.stringify(results, null, 2));
+    const annotated = results.map((entry) => {
+      const state = stateOf(entry);
+      return { ...entry, installed: state === "unknown" ? null : state === "installed" };
+    });
+    console.log(JSON.stringify(annotated, null, 2));
     return EXIT.OK;
   }
   if (results.length === 0) {
@@ -862,15 +940,31 @@ async function runFind(positionals, flags) {
   console.log(`${header}
 `);
   for (const entry of results) {
-    console.log(`${formatEntry(entry)}
+    console.log(`${formatEntry(entry, stateOf(entry))}
 `);
   }
+  const missing = [
+    ...new Set(results.filter((e) => stateOf(e) === "missing").map((e) => e.package))
+  ];
+  if (missing.length > 0) {
+    console.log(`⚠ Not in your dependencies: ${missing.join(", ")} — install before importing (e.g. \`bun add ${missing[0]}\`).`);
+  }
   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 warnIfNotInstalled(slug) {
+  try {
+    const entry = (await loadCatalog()).components.find((c) => c.slug === slug);
+    if (!entry)
+      return;
+    if (installStateFor(entry.package, readConsumerDependencies()) === "missing") {
+      console.error(`⚠ ${entry.name} ships from ${entry.package}, which isn't in your dependencies — ` + `install it before importing (e.g. \`bun add ${entry.package}\`).`);
+    }
+  } catch {}
+}
 async function runGetComponent(positionals, flags) {
   const slug = positionals[0];
   if (!slug) {
@@ -893,6 +987,7 @@ async function runGetComponent(positionals, flags) {
     printError(`component "${slug}" not found. Run \`urbicon find <query>\` to discover the slug.`);
     return EXIT.FAIL;
   }
+  await warnIfNotInstalled(slug);
   if (!section || section === "full") {
     console.log(content.trim());
     return EXIT.OK;
@@ -908,7 +1003,7 @@ async function runGetComponent(positionals, flags) {
 
 // src/cli/commands/hook.ts
 import { readFile as readFile5 } from "node:fs/promises";
-import { resolve as resolve4 } from "node:path";
+import { resolve as resolve5 } from "node:path";
 // ../design-engine/src/linter/heuristics.ts
 var CHROMATIC_INTENTS = ["primary", "secondary", "success", "warning", "danger", "info"];
 var HEURISTIC_THRESHOLDS = {
@@ -1671,6 +1766,7 @@ var INTERACTIVE_CORES = [
   "interactive-disabled"
 ];
 var CHART_CORES = ["chart-1", "chart-2", "chart-3", "chart-4", "chart-5", "chart-6"];
+var SKELETON_CORES = ["skeleton-shimmer"];
 function buildIntentCores() {
   const cores = [];
   for (const intent of INTENT_NAMES) {
@@ -1691,7 +1787,8 @@ var VALID_TOKEN_CORES = new Set([
   ...WARM_NEUTRAL_STEPS.map((s) => `warm-neutral-${s}`),
   ...FEEDBACK_CORES,
   ...INTERACTIVE_CORES,
-  ...CHART_CORES
+  ...CHART_CORES,
+  ...SKELETON_CORES
 ]);
 function normalizeExtraTokens(extra) {
   return extra.map((token) => token.trim()).filter((token) => token.length > 0);
@@ -1738,6 +1835,53 @@ 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."
 };
+function isSingleEditApart(a, b) {
+  if (a === b)
+    return false;
+  if (a.length === b.length) {
+    let diffs = 0;
+    let at = -1;
+    for (let i2 = 0;i2 < a.length; i2++) {
+      if (a[i2] !== b[i2]) {
+        diffs++;
+        if (at === -1)
+          at = i2;
+      }
+    }
+    if (diffs === 1)
+      return true;
+    return diffs === 2 && at >= 0 && a[at] === b[at + 1] && a[at + 1] === b[at];
+  }
+  if (Math.abs(a.length - b.length) !== 1)
+    return false;
+  const [short, long] = a.length < b.length ? [a, b] : [b, a];
+  let i = 0;
+  let j = 0;
+  let skipped = false;
+  while (i < short.length && j < long.length) {
+    if (short[i] === long[j]) {
+      i++;
+      j++;
+    } else if (!skipped) {
+      skipped = true;
+      j++;
+    } else {
+      return false;
+    }
+  }
+  return true;
+}
+function suggestIntentTypo(core) {
+  if (core.includes("-"))
+    return null;
+  if (INTENT_NAMES.includes(core))
+    return null;
+  for (const intent of INTENT_NAMES) {
+    if (isSingleEditApart(core, intent))
+      return intent;
+  }
+  return null;
+}
 
 // ../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`).";
@@ -1949,6 +2093,81 @@ var dynamicClassInterpolation = {
     return dedupeByLine(findings);
   }
 };
+var INTERNAL_SUBPATH_SEGMENTS = new Set([
+  "primitives",
+  "components",
+  "lib",
+  "dist",
+  "src",
+  "icons"
+]);
+function isDeepInternalSubpath(subpath) {
+  if (/\.svelte(\.[jt]s)?$|\.[jt]s$/.test(subpath))
+    return true;
+  return subpath.split("/").some((seg) => INTERNAL_SUBPATH_SEGMENTS.has(seg));
+}
+var deepInternalImport = {
+  id: "deep-internal-import",
+  severity: "error",
+  description: "Deep/internal import into an `@urbicon-ui` package instead of its public root.",
+  check(lines) {
+    const re = /['"](@urbicon-ui\/[a-z-]+)\/([^'"]+)['"]/g;
+    const findings = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        const pkg = m[1];
+        const subpath = m[2];
+        if (!isDeepInternalSubpath(subpath))
+          continue;
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: "deterministic",
+          message: `Deep import \`${pkg}/${subpath}\` reaches into ${pkg}'s internals — they can move between releases.`,
+          fix: `Import from the package root: \`import { … } from '${pkg}'\`.`,
+          line: i + 1,
+          match: `${pkg}/${subpath}`
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+var hardcodedMotion = {
+  id: "hardcoded-motion",
+  severity: "error",
+  description: "Hardcoded transition duration or `cubic-bezier()` easing instead of a motion token.",
+  check(lines) {
+    const duration = /\bduration-\[\d+(?:\.\d+)?m?s\]/g;
+    const easing = /\bease-\[cubic-bezier\([^\]]*\)\]/g;
+    const findings = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(duration)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: "deterministic",
+          message: `Hardcoded transition duration \`${m[0]}\` bypasses the motion scale (no global speed / reduced-motion control).`,
+          fix: "Use a duration token: `duration-[var(--blocks-duration-fast)]` / `-normal` / `-slow`.",
+          line: i + 1,
+          match: m[0]
+        });
+      }
+      for (const m of line.matchAll(easing)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: "deterministic",
+          message: `Hardcoded \`cubic-bezier()\` easing \`${m[0]}\` bypasses the motion system's easing tokens.`,
+          fix: "Use an easing token: `ease-[var(--blocks-ease-smooth)]` / `-snappy` / `-gentle`, or a named Tailwind ease (`ease-out`).",
+          line: i + 1,
+          match: m[0]
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
 var tokenHallucination = {
   id: "token-hallucination",
   severity: "warning",
@@ -1961,8 +2180,21 @@ var tokenHallucination = {
     lines.forEach((line, i) => {
       for (const m of line.matchAll(re)) {
         const core = m[2];
-        if (!looksSemantic(core))
+        if (!looksSemantic(core)) {
+          const intended = suggestIntentTypo(core);
+          if (intended) {
+            findings.push({
+              ruleId: this.id,
+              severity: this.severity,
+              kind: "deterministic",
+              message: `\`${m[1]}-${core}\` looks like a typo of \`${m[1]}-${intended}\`.`,
+              fix: `Did you mean \`${m[1]}-${intended}\`? Valid intents: ${INTENT_NAMES.join(", ")}.`,
+              line: i + 1,
+              match: m[0]
+            });
+          }
           continue;
+        }
         if (validCores.has(core))
           continue;
         findings.push({
@@ -2020,6 +2252,8 @@ var RULES = [
   darkModeOverride,
   focusNotVisible,
   hardcodedZIndex,
+  hardcodedMotion,
+  deepInternalImport,
   dynamicClassInterpolation,
   tokenHallucination,
   ...MARKUP_RULES
@@ -2144,7 +2378,7 @@ async function runHook(_positionals, flags) {
   for (const p of paths) {
     let code;
     try {
-      code = await readFile5(resolve4(p), "utf-8");
+      code = await readFile5(resolve5(p), "utf-8");
     } catch {
       continue;
     }
@@ -2169,21 +2403,21 @@ Fix the issues above and re-save. — urbicon design gate`);
 
 // 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";
+import { dirname as dirname5, join as join3, relative as relative2, resolve as resolve7 } 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 { dirname as dirname4, resolve as resolve6 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 async function findPackageRoot() {
-  let dir = dirname3(fileURLToPath2(import.meta.url));
+  let dir = dirname4(fileURLToPath2(import.meta.url));
   for (let i = 0;i < 6; i++) {
     try {
-      const pkg = JSON.parse(await readFile6(resolve5(dir, "package.json"), "utf-8"));
+      const pkg = JSON.parse(await readFile6(resolve6(dir, "package.json"), "utf-8"));
       if (pkg.name === "@urbicon-ui/design")
         return dir;
     } catch {}
-    const parent = dirname3(dir);
+    const parent = dirname4(dir);
     if (parent === dir)
       break;
     dir = parent;
@@ -2194,11 +2428,31 @@ async function findPackageRoot() {
 // src/cli/commands/init.ts
 var BLOCK_START = "<!-- urbicon:start";
 var BLOCK_END = "<!-- urbicon:end -->";
+function tailwindSteps(deps) {
+  const has = (p) => deps?.has(p) ?? false;
+  const tailwindWired = has("@tailwindcss/vite") || has("tailwindcss");
+  if (tailwindWired) {
+    return [
+      "  • Tailwind is installed — ensure your `app.css` has `@source '../node_modules/@urbicon-ui/blocks/dist';`",
+      "    (relative to app.css) so the components' utility classes are generated. Easy to miss."
+    ];
+  }
+  return [
+    "  • Wire up Tailwind 4 — REQUIRED, or components render unstyled (they emit Tailwind classes):",
+    "      1. bun add -D tailwindcss @tailwindcss/vite",
+    "      2. vite.config.ts → add the `tailwindcss()` plugin",
+    "      3. src/app.css →",
+    "           @import 'tailwindcss';",
+    "           @import '@urbicon-ui/blocks/style/index.css';",
+    "           @source '../node_modules/@urbicon-ui/blocks/dist';   /* generates component classes */",
+    "      4. import './app.css' in your root +layout.svelte"
+  ];
+}
 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");
+  return readFile7(join3(root, "templates", name), "utf-8");
 }
 async function readOrNull(path) {
   try {
@@ -2246,7 +2500,7 @@ async function mergeHook(settingsPath) {
     matcher: "Edit|MultiEdit|Write",
     hooks: [{ type: "command", command: "urbicon hook" }]
   });
-  await mkdir(dirname4(settingsPath), { recursive: true });
+  await mkdir(dirname5(settingsPath), { recursive: true });
   await writeFile2(settingsPath, `${JSON.stringify(settings, null, 2)}
 `, "utf-8");
   return "added";
@@ -2263,7 +2517,7 @@ async function runInit(_positionals, flags) {
     printError(err.message);
     return EXIT.FAIL;
   }
-  const agentsPath = resolve6(stringFlag(flags, "agents-file") ?? "AGENTS.md");
+  const agentsPath = resolve7(stringFlag(flags, "agents-file") ?? "AGENTS.md");
   const existingAgents = await readOrNull(agentsPath) ?? "";
   let upserted;
   try {
@@ -2283,7 +2537,7 @@ async function runInit(_positionals, flags) {
     done.push(`${rel(manifestPath)} — scaffolded`);
   }
   if (boolFlag(flags, "hook")) {
-    const settingsPath = resolve6(".claude", "settings.json");
+    const settingsPath = resolve7(".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\``);
@@ -2292,12 +2546,12 @@ async function runInit(_positionals, flags) {
     }
   }
   if (boolFlag(flags, "ci")) {
-    const ciPath = resolve6(".github", "workflows", "design-gate.yml");
+    const ciPath = resolve7(".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 mkdir(dirname5(ciPath), { recursive: true });
       await writeFile2(ciPath, ci, "utf-8");
       done.push(`${rel(ciPath)} — wrote the design-gate workflow`);
     }
@@ -2310,6 +2564,8 @@ async function runInit(_positionals, flags) {
     console.log(`  · ${s}`);
   console.log(`
 Next steps:`);
+  for (const line of tailwindSteps(readConsumerDependencies()))
+    console.log(line);
   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")) {
@@ -2366,7 +2622,7 @@ async function runRecordDecision(_positionals, flags) {
 }
 
 // src/cli/commands/sync-manifest.ts
-import { dirname as dirname5 } from "node:path";
+import { dirname as dirname6 } from "node:path";
 async function runSyncManifest(_positionals, flags) {
   const path = resolveManifestPath(stringFlag(flags, "manifest"));
   if (!path.endsWith(".md")) {
@@ -2374,7 +2630,7 @@ async function runSyncManifest(_positionals, flags) {
     return EXIT.USAGE;
   }
   const src = resolveSourceDir(stringFlag(flags, "src"));
-  const usages = await scanMarkers(src, dirname5(path));
+  const usages = await scanMarkers(src, dirname6(path));
   const { content, created } = await readOrCreateManifest(path);
   const updated = upsertUsagesSection(content, usages);
   try {
@@ -2403,7 +2659,7 @@ async function runSyncManifest(_positionals, flags) {
 
 // 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";
+import { join as join4, relative as relative3, resolve as resolve8, sep as sep2 } from "node:path";
 var SKIP_DIRS2 = new Set([
   "node_modules",
   ".svelte-kit",
@@ -2432,9 +2688,9 @@ async function collectSvelte(dir, depth = 0) {
     if (entry.isDirectory()) {
       if (SKIP_DIRS2.has(entry.name) || entry.name.startsWith("."))
         continue;
-      files.push(...await collectSvelte(join3(dir, entry.name), depth + 1));
+      files.push(...await collectSvelte(join4(dir, entry.name), depth + 1));
     } else if (entry.isFile() && entry.name.endsWith(".svelte")) {
-      files.push(join3(dir, entry.name));
+      files.push(join4(dir, entry.name));
     }
   }
   return files;
@@ -2455,7 +2711,7 @@ async function gather(positionals) {
       units.push({ label: "<stdin>", code: await readStdin2() });
       continue;
     }
-    const abs = resolve7(p);
+    const abs = resolve8(p);
     let info;
     try {
       info = await stat2(abs);
@@ -2547,11 +2803,11 @@ FAIL — ${reason}.`);
 
 // src/cli/commands/verb.ts
 import { readdir as readdir3, readFile as readFile9 } from "node:fs/promises";
-import { resolve as resolve8 } from "node:path";
+import { resolve as resolve9 } 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;
+  return root ? resolve9(root, "skill", "verbs") : null;
 }
 function purposeOf(body) {
   const heading = body.split(`
@@ -2577,7 +2833,7 @@ async function runVerbList(_positionals, _flags) {
     const name = file.replace(/\.md$/, "");
     let purpose = "";
     try {
-      purpose = purposeOf(await readFile9(resolve8(dir, file), "utf-8"));
+      purpose = purposeOf(await readFile9(resolve9(dir, file), "utf-8"));
     } catch {}
     console.log(`  ${name.padEnd(10)} ${purpose}`);
   }
@@ -2599,7 +2855,7 @@ async function runVerb(positionals, _flags) {
     return EXIT.FAIL;
   }
   try {
-    console.log(await readFile9(resolve8(dir, `${name}.md`), "utf-8"));
+    console.log(await readFile9(resolve9(dir, `${name}.md`), "utf-8"));
     return EXIT.OK;
   } catch {
     printError(`unknown verb "${name}" — list the available verbs with \`urbicon verbs\``);
@@ -2682,7 +2938,7 @@ async function readVersion() {
   if (!root)
     return "unknown";
   try {
-    const pkg = JSON.parse(await readFile10(resolve9(root, "package.json"), "utf-8"));
+    const pkg = JSON.parse(await readFile10(resolve10(root, "package.json"), "utf-8"));
     return pkg.version ?? "unknown";
   } catch {
     return "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/design",
-  "version": "6.2.0",
+  "version": "6.3.3",
   "description": "The urbicon CLI — version-pinned design validation and design-manifest tooling for projects built with Urbicon UI. Wraps @urbicon-ui/design-engine for editor hooks and CI.",
   "license": "MIT",
   "repository": {
@@ -38,8 +38,8 @@
     "test:run": "vitest run"
   },
   "dependencies": {
-    "@urbicon-ui/design-content": "6.2.0",
-    "@urbicon-ui/design-engine": "6.2.0"
+    "@urbicon-ui/design-content": "6.3.3",
+    "@urbicon-ui/design-engine": "6.3.3"
   },
   "devDependencies": {
     "typescript": "^6.0.3",

package/templates/AGENTS.md

@@ -78,6 +78,8 @@ app root and reference it by name; never force colours with inline `!` overrides
 </BlocksProvider>
 ```
 
+The full override ladder (weakest → strongest): `class` (root slot only) → instance `slotClasses={{ <slot>: … }}` → `BlocksProvider` `defaults`/`presets` → prop-conditional `overrides` (one variant/intent/state) → `unstyled` + `slotClasses` (strip & rebuild).
+
 **Svelte 5** — `$props()` not `export let`; `{#snippet}` / `{@render}` not `<slot>`; callback props
 (`onValueChange`) not `createEventDispatcher`; lowercase DOM events (`onclick`).