@vegastack/design 0.1.1 → 0.3.0

package/bin/doctor.mjs

@@ -0,0 +1,332 @@
+// `vegastack-design doctor` — check a consuming project's setup.
+//
+// Motivated by a real consumer failure (VegaStack CRM, 2026-07-27): a missing
+// `@tailwindcss/postcss` plugin produces two different, equally misleading results.
+// Under Turbopack the build dies with `Can't resolve 'tw-animate-css'`, naming a
+// dependency that is installed and fine. Under webpack the build SUCCEEDS, the token
+// theme lands (it is literal CSS inside preset.css), and zero utility classes are
+// generated — so the app renders with correct colours and no spacing or layout, which
+// reads as "the design system is broken".
+//
+// A human will not attribute either symptom correctly, which is exactly why this is a
+// command and not a paragraph in a guide. Every check here maps to a documented failure
+// mode in the Troubleshooting guide.
+//
+// Read-only: it never writes, installs, or edits. Exit 0 = all good, 1 = a real problem,
+// so it composes into CI as `vegastack-design doctor`.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+
+const POSTCSS_CONFIGS = [
+  "postcss.config.mjs",
+  "postcss.config.js",
+  "postcss.config.cjs",
+  "postcss.config.ts",
+  "postcss.config.json",
+  ".postcssrc",
+  ".postcssrc.json",
+];
+
+const CSS_SEARCH_DIRS = [
+  "app",
+  "src/app",
+  "src/styles",
+  "styles",
+  "src",
+  "apps",
+];
+
+const USAGE = `
+Usage: vegastack-design doctor [options]
+
+Checks a consuming project's VegaStack setup and reports what is wrong and how to fix it.
+
+Options:
+  --dir <path>   Project root to inspect (default: the current directory)
+  -h, --help     Show this help
+
+Exit codes: 0 = no problems · 1 = at least one failure · 2 = bad usage
+`.trim();
+
+/** Collect .css files under a few conventional roots, shallowly, without walking node_modules. */
+function findCssFiles(root, max = 200) {
+  const out = [];
+  const seen = new Set();
+  const walk = (dir, depth) => {
+    if (out.length >= max || depth > 4) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (out.length >= max) return;
+      if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+      const full = join(dir, e.name);
+      if (seen.has(full)) continue;
+      seen.add(full);
+      if (e.isDirectory()) walk(full, depth + 1);
+      else if (e.name.endsWith(".css")) out.push(full);
+    }
+  };
+  for (const d of CSS_SEARCH_DIRS) {
+    const full = join(root, d);
+    if (existsSync(full) && statSync(full).isDirectory()) walk(full, 0);
+  }
+  return out;
+}
+
+/** CSS comments frequently *mention* the thing we are looking for — strip them before matching. */
+function stripCssComments(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+/** Nearest ancestor of `from` (inclusive) that has a package.json, bounded by `root`. */
+function nearestPackageRoot(from, root) {
+  let dir = from;
+  for (let i = 0; i < 8; i += 1) {
+    if (existsSync(join(dir, "package.json"))) return dir;
+    if (dir === root) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return root;
+}
+
+function readIfExists(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function readJson(path) {
+  const raw = readIfExists(path);
+  if (raw == null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function main(argv = []) {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    console.log(USAGE);
+    return 0;
+  }
+  const dirFlag = argv.indexOf("--dir");
+  if (dirFlag !== -1 && argv[dirFlag + 1] == null) {
+    console.error("doctor: --dir requires a path\n");
+    console.error(USAGE);
+    return 2;
+  }
+  const root = dirFlag === -1 ? process.cwd() : argv[dirFlag + 1];
+
+  if (!existsSync(root)) {
+    console.error(`doctor: no such directory: ${root}`);
+    return 2;
+  }
+
+  const results = [];
+  const ok = (name, detail) => results.push({ level: "ok", name, detail });
+  const warn = (name, detail, fix) =>
+    results.push({ level: "warn", name, detail, fix });
+  const fail = (name, detail, fix) =>
+    results.push({ level: "fail", name, detail, fix });
+
+  // ---- 1. the design system is installed -------------------------------------------------
+  const pkg = readJson(join(root, "package.json"));
+  const deps = {
+    ...(pkg?.dependencies ?? {}),
+    ...(pkg?.devDependencies ?? {}),
+  };
+  const designInstalled =
+    "@vegastack/design" in deps ||
+    existsSync(join(root, "node_modules", "@vegastack", "design"));
+
+  if (designInstalled) {
+    const installed = readJson(
+      join(root, "node_modules", "@vegastack", "design", "package.json"),
+    );
+    ok(
+      "@vegastack/design installed",
+      installed?.version
+        ? `v${installed.version}`
+        : (deps["@vegastack/design"] ?? ""),
+    );
+  } else {
+    fail(
+      "@vegastack/design installed",
+      "not found in package.json or node_modules",
+      "pnpm add @vegastack/design",
+    );
+  }
+
+  // ---- 2. the preset is imported ----------------------------------------------------------
+  const cssFiles = findCssFiles(root);
+  const presetFiles = cssFiles.filter((f) =>
+    (readIfExists(f) ?? "").includes("@vegastack/design/preset.css"),
+  );
+
+  if (presetFiles.length > 0) {
+    ok(
+      "preset.css imported",
+      presetFiles.map((f) => relative(root, f)).join(", "),
+    );
+  } else {
+    fail(
+      "preset.css imported",
+      cssFiles.length === 0
+        ? "no .css files found under app/, src/, or styles/"
+        : `none of ${cssFiles.length} .css file(s) import it`,
+      'add `@import "@vegastack/design/preset.css";` to your global stylesheet',
+    );
+  }
+
+  // ---- 3. THE BIG ONE: the Tailwind PostCSS plugin ----------------------------------------
+  // Without it Tailwind never runs: no utilities are generated, and depending on the bundler
+  // you either get a misleading `Can't resolve 'tw-animate-css'` or a silently unstyled app.
+  // In a workspace the config correctly lives in the APP package, not the repo root, so search
+  // every package that owns a preset-importing stylesheet as well as the root itself.
+  const postcssRoots = [
+    root,
+    ...presetFiles.map((f) => nearestPackageRoot(dirname(f), root)),
+  ].filter((d, i, a) => a.indexOf(d) === i);
+  const postcssPath = postcssRoots
+    .flatMap((d) => POSTCSS_CONFIGS.map((n) => join(d, n)))
+    .find(existsSync);
+  const postcssOwnerPkg = postcssPath
+    ? readJson(join(dirname(postcssPath), "package.json"))
+    : null;
+  const postcssInline = (postcssOwnerPkg ?? pkg)?.postcss
+    ? JSON.stringify((postcssOwnerPkg ?? pkg).postcss)
+    : null;
+  const postcssSource = postcssPath ? readIfExists(postcssPath) : postcssInline;
+  const hasPlugin =
+    postcssSource != null && postcssSource.includes("@tailwindcss/postcss");
+
+  if (hasPlugin) {
+    ok(
+      "Tailwind PostCSS plugin",
+      postcssPath ? relative(root, postcssPath) : "package.json#postcss",
+    );
+  } else if (postcssSource != null) {
+    fail(
+      "Tailwind PostCSS plugin",
+      `${postcssPath ? relative(root, postcssPath) : "package.json#postcss"} exists but does not configure @tailwindcss/postcss`,
+      'add `"@tailwindcss/postcss": {}` to its plugins',
+    );
+  } else {
+    fail(
+      "Tailwind PostCSS plugin",
+      "no PostCSS config found — Tailwind will not run, so NO utility classes are generated",
+      'pnpm add -D @tailwindcss/postcss, then create postcss.config.mjs:\n     const config = { plugins: { "@tailwindcss/postcss": {} } };\n     export default config;',
+    );
+  }
+
+  // ---- 4. no duplicate Tailwind import ----------------------------------------------------
+  // preset.css already imports Tailwind; a second bare import is the documented cause of
+  // "utilities exist but everything is unstyled".
+  const duplicateTailwind = presetFiles.filter((f) => {
+    const src = stripCssComments(readIfExists(f) ?? "");
+    return /@import\s+["']tailwindcss["']/.test(src);
+  });
+  if (duplicateTailwind.length > 0) {
+    warn(
+      "no duplicate Tailwind import",
+      `${duplicateTailwind.map((f) => relative(root, f)).join(", ")} also imports "tailwindcss" directly`,
+      "remove it — preset.css imports Tailwind itself",
+    );
+  } else if (presetFiles.length > 0) {
+    ok("no duplicate Tailwind import", "preset.css is the only Tailwind entry");
+  }
+
+  // ---- 5. registry access is configured ---------------------------------------------------
+  let componentsJsonPath = join(root, "components.json");
+  let componentsJson = readJson(componentsJsonPath);
+  if (componentsJson == null) {
+    // Walk up: in a workspace the canonical components.json commonly sits at the repo root.
+    let dir = root;
+    for (let i = 0; i < 5 && componentsJson == null; i += 1) {
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+      const candidate = join(dir, "components.json");
+      if (existsSync(candidate)) {
+        componentsJsonPath = candidate;
+        componentsJson = readJson(candidate);
+      }
+    }
+  }
+  if (componentsJson == null) {
+    warn(
+      "registry configured",
+      "no components.json here or in any parent directory",
+      "see the Quickstart — needed before `shadcn add @vegastack/<name>`",
+    );
+  } else if (componentsJson.registries?.["@vegastack"] == null) {
+    fail(
+      "registry configured",
+      'components.json has no `registries["@vegastack"]` entry',
+      "add the registries block from the Quickstart",
+    );
+  } else {
+    ok(
+      "registry configured",
+      `${relative(root, componentsJsonPath) || "components.json"} declares @vegastack`,
+    );
+  }
+
+  // ---- 6. monorepo hint --------------------------------------------------------------------
+  // Source detection is relative to the CSS file, so components living outside the app's tree
+  // compile to nothing unless declared. Only worth saying when this actually looks like a workspace.
+  const isWorkspace =
+    existsSync(join(root, "pnpm-workspace.yaml")) ||
+    Array.isArray(pkg?.workspaces) ||
+    pkg?.workspaces != null;
+  if (isWorkspace && presetFiles.length > 0) {
+    const declaresSource = presetFiles.some((f) =>
+      (readIfExists(f) ?? "").includes("@source"),
+    );
+    if (declaresSource) {
+      ok("monorepo sources declared", "@source directives present");
+    } else {
+      warn(
+        "monorepo sources declared",
+        "workspace detected but no @source directive — components outside this app's tree will compile to nothing",
+        'add e.g. `@source "../../../../packages/ui/src";` next to the preset import',
+      );
+    }
+  }
+
+  // ---- report -------------------------------------------------------------------------------
+  const glyph = { ok: "✓", warn: "!", fail: "✗" };
+  console.log("");
+  for (const r of results) {
+    console.log(
+      `  ${glyph[r.level]} ${r.name}${r.detail ? ` — ${r.detail}` : ""}`,
+    );
+    if (r.fix) console.log(`     fix: ${r.fix}`);
+  }
+
+  const failures = results.filter((r) => r.level === "fail").length;
+  const warnings = results.filter((r) => r.level === "warn").length;
+  console.log("");
+  if (failures > 0) {
+    console.log(
+      `  ${failures} problem(s), ${warnings} warning(s). See https://design.vegastack.com/docs/guides/troubleshooting`,
+    );
+    return 1;
+  }
+  console.log(
+    warnings > 0
+      ? `  setup looks correct (${warnings} warning(s)).`
+      : "  setup looks correct.",
+  );
+  return 0;
+}

package/bin/skills.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+// vegastack-design skills — install the public VegaStack agent skills into a consuming project.
+//
+// The skills ship inside this package (see `files` in package.json), so this is a pure local
+// copy: no network, no credentials, no registry access. Files are COPIED rather than symlinked
+// because node_modules is ephemeral — a symlink into it breaks on the next clean install.
+//
+// Safety posture, matching the registry verifier:
+//   • never overwrite an existing file without --force (it reports what would change instead)
+//   • never write THROUGH a symlink at the destination — refuse it, do not follow it
+//   • --dry-run performs every check and writes nothing
+import {
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  lstatSync,
+} from "node:fs";
+import { join, dirname, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const SKILLS_DIR = join(PKG_ROOT, "skills");
+
+const SURFACES = {
+  claude: ".claude/skills",
+  codex: ".agents/skills",
+};
+
+const USAGE = `vegastack-design skills — install the VegaStack agent skills
+
+Usage:
+  vegastack-design skills install [options]   Copy the skills into this project
+  vegastack-design skills list                Show the skills bundled with this package
+
+Options:
+  --dir <path>    Project root to install into (default: the current directory)
+  --claude        Only install for Claude Code (.claude/skills)
+  --codex         Only install for Codex (.agents/skills)
+  --force         Overwrite files that already exist and differ
+  --dry-run       Report what would change; write nothing
+  -h, --help      Show this help
+
+With neither --claude nor --codex, both surfaces are installed.`;
+
+/** Skill directory names bundled in this package. */
+function bundledSkills() {
+  if (!existsSync(SKILLS_DIR)) return [];
+  return readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter(
+      (e) =>
+        e.isDirectory() && existsSync(join(SKILLS_DIR, e.name, "SKILL.md")),
+    )
+    .map((e) => e.name)
+    .sort();
+}
+
+/** Files of one skill, relative to that skill's directory. */
+function skillFiles(skill) {
+  const base = join(SKILLS_DIR, skill);
+  const out = [];
+  for (const entry of readdirSync(base, {
+    withFileTypes: true,
+    recursive: true,
+  })) {
+    if (!entry.isFile()) continue;
+    const abs = join(entry.parentPath ?? entry.path, entry.name);
+    out.push(relative(base, abs).split(sep).join("/"));
+  }
+  return out.sort();
+}
+
+function describe(skill) {
+  const src = readFileSync(join(SKILLS_DIR, skill, "SKILL.md"), "utf8");
+  const fm = /^---\n([\s\S]*?)\n---/.exec(src);
+  const desc = fm && /^description:\s*(.+)$/m.exec(fm[1])?.[1]?.trim();
+  if (!desc) return "";
+  return desc.length > 100 ? `${desc.slice(0, 99)}…` : desc;
+}
+
+function parseArgs(argv) {
+  const opts = {
+    dir: process.cwd(),
+    surfaces: [],
+    force: false,
+    dryRun: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--dir") {
+      const value = argv[++i];
+      if (!value) throw new Error("--dir needs a path");
+      opts.dir = resolve(value);
+    } else if (arg === "--claude") opts.surfaces.push("claude");
+    else if (arg === "--codex") opts.surfaces.push("codex");
+    else if (arg === "--force") opts.force = true;
+    else if (arg === "--dry-run") opts.dryRun = true;
+    else throw new Error(`unknown option: ${arg}`);
+  }
+  if (opts.surfaces.length === 0) opts.surfaces = ["claude", "codex"];
+  return opts;
+}
+
+function list() {
+  const skills = bundledSkills();
+  if (skills.length === 0) {
+    console.error("no skills are bundled with this build of @vegastack/design");
+    return 1;
+  }
+  console.log(`${skills.length} skill(s) bundled with @vegastack/design:\n`);
+  for (const skill of skills)
+    console.log(`  ${skill}\n    ${describe(skill)}\n`);
+  console.log("Install with: vegastack-design skills install");
+  return 0;
+}
+
+function install(argv) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (error) {
+    console.error(`${error.message}\n`);
+    console.error(USAGE);
+    return 2;
+  }
+
+  const skills = bundledSkills();
+  if (skills.length === 0) {
+    console.error("no skills are bundled with this build of @vegastack/design");
+    return 1;
+  }
+  if (!existsSync(opts.dir)) {
+    console.error(`target directory does not exist: ${opts.dir}`);
+    return 1;
+  }
+
+  const planned = []; // { to, from, action }
+  const blocked = [];
+  const conflicts = [];
+
+  for (const surface of opts.surfaces) {
+    for (const skill of skills) {
+      for (const file of skillFiles(skill)) {
+        const from = join(SKILLS_DIR, skill, file);
+        const to = join(opts.dir, SURFACES[surface], skill, file);
+
+        // Refuse to write through a symlink anywhere on the destination path we own.
+        let symlinked = false;
+        for (
+          let probe = to;
+          probe.startsWith(join(opts.dir, SURFACES[surface].split("/")[0]));
+          probe = dirname(probe)
+        ) {
+          try {
+            if (lstatSync(probe).isSymbolicLink()) {
+              symlinked = true;
+              break;
+            }
+          } catch {
+            /* does not exist yet — fine */
+          }
+        }
+        if (symlinked) {
+          blocked.push(relative(opts.dir, to));
+          continue;
+        }
+
+        if (existsSync(to)) {
+          if (readFileSync(to).equals(readFileSync(from))) continue; // already correct
+          if (!opts.force) {
+            conflicts.push(relative(opts.dir, to));
+            continue;
+          }
+          planned.push({ from, to, action: "overwrite" });
+        } else {
+          planned.push({ from, to, action: "write" });
+        }
+      }
+    }
+  }
+
+  if (blocked.length) {
+    console.error("refusing to write through a symlink:");
+    for (const path of blocked) console.error(`  ${path}`);
+    console.error("\nRemove or relocate these entries, then run again.");
+    return 1;
+  }
+
+  if (conflicts.length) {
+    console.error("these files already exist and differ — not overwriting:");
+    for (const path of conflicts) console.error(`  ${path}`);
+    console.error(
+      "\nRe-run with --force to overwrite, or move your versions aside first.",
+    );
+    return 1;
+  }
+
+  if (planned.length === 0) {
+    console.log(`✓ skills already up to date in ${opts.dir}`);
+    return 0;
+  }
+
+  if (opts.dryRun) {
+    console.log(`Would write ${planned.length} file(s) into ${opts.dir}:\n`);
+    for (const { to, action } of planned)
+      console.log(`  ${action}  ${relative(opts.dir, to)}`);
+    console.log("\n(dry run — nothing was written)");
+    return 0;
+  }
+
+  // A read-only checkout, a permissions problem, or a full disk must fail with something a human
+  // can act on — not an unhandled stack trace out of a CLI a consumer just installed.
+  const written = [];
+  for (const { from, to } of planned) {
+    try {
+      mkdirSync(dirname(to), { recursive: true });
+      writeFileSync(to, readFileSync(from));
+      written.push(to);
+    } catch (error) {
+      console.error(
+        `failed to write ${relative(opts.dir, to)}: ${error.code ?? ""} ${error.message}`,
+      );
+      if (written.length) {
+        console.error(
+          `\n${written.length} file(s) were already written before this failed:`,
+        );
+        for (const path of written)
+          console.error(`  ${relative(opts.dir, path)}`);
+        console.error(
+          "Re-run once the cause is fixed; the command is idempotent.",
+        );
+      }
+      return 1;
+    }
+  }
+
+  const surfaceLabel = opts.surfaces.map((s) => SURFACES[s]).join(" and ");
+  console.log(`✓ installed ${skills.length} skill(s) into ${surfaceLabel}`);
+  for (const skill of skills) console.log(`  ${skill}`);
+  console.log(
+    "\nRestart your agent if it was already running, so it picks up the new directory.",
+  );
+  return 0;
+}
+
+export function main(argv) {
+  const [sub, ...rest] = argv;
+  if (sub === "--help" || sub === "-h" || sub === "help" || sub == null) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (sub === "list") return list();
+  if (sub === "install") return install(rest);
+  console.error(`unknown skills subcommand: ${sub}\n`);
+  console.error(USAGE);
+  return 2;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exit(main(process.argv.slice(2)));
+}

package/bin/vegastack-design.mjs

@@ -4,15 +4,17 @@
 // Subcommands:
 //   check-updates   Show which copied-in components have newer registry versions (what to re-pull).
 //   verify          Verify a registry item's integrity before/after `shadcn add` (Sigstore + hash).
+//   skills          Install the bundled VegaStack agent skills into the consuming project.
+//   doctor          Check a consuming project's setup (PostCSS plugin, preset import, registry).
 //
 // The bin is named `vegastack-design` (NOT `vegastack`) so it never collides with a platform CLI.
 // `check-updates` is imported in-process; `verify` is spawned (it's the standalone, hash-parity-tested
 // verifier — we run it untouched). Exit codes are forwarded from the subcommand.
-import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
-const HERE = new URL('.', import.meta.url);
+const HERE = new URL(".", import.meta.url);
 
 const USAGE = `vegastack-design — VegaStack design-system CLI
 
@@ -21,6 +23,8 @@ Usage: vegastack-design <command> [options]
 Commands:
   check-updates     Show which copied-in components have newer registry versions
   verify            Verify a registry item's integrity (pre/post \`shadcn add\`)
+  skills            Install the VegaStack agent skills (Claude Code + Codex)
+  doctor            Check this project's setup and report what is wrong
 
 Run \`vegastack-design <command> --help\` for command options.
   -v, --version     Print version
@@ -28,39 +32,61 @@ Run \`vegastack-design <command> --help\` for command options.
 
 function version() {
   try {
-    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+    return JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+    ).version;
   } catch {
-    return '0.0.0';
+    return "0.0.0";
   }
 }
 
 const [cmd, ...rest] = process.argv.slice(2);
 
-if (cmd === '--version' || cmd === '-v') {
+if (cmd === "--version" || cmd === "-v") {
   console.log(version());
   process.exit(0);
 }
-if (cmd == null || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+if (cmd == null || cmd === "--help" || cmd === "-h" || cmd === "help") {
   console.log(USAGE);
   process.exit(0);
 }
 
-if (cmd === 'check-updates') {
+if (cmd === "check-updates") {
   // imported in-process (it's our own code with an exported main())
-  const { main } = await import(new URL('./check-updates.mjs', HERE).href);
+  const { main } = await import(new URL("./check-updates.mjs", HERE).href);
   process.exit(await main(rest));
 }
 
-if (cmd === 'verify') {
+if (cmd === "skills") {
+  // imported in-process (our own code, no network, no credentials)
+  const { main } = await import(new URL("./skills.mjs", HERE).href);
+  process.exit(main(rest));
+}
+
+if (cmd === "doctor") {
+  // imported in-process (our own code, read-only, no network, no credentials)
+  const { main } = await import(new URL("./doctor.mjs", HERE).href);
+  process.exit(main(rest));
+}
+
+if (cmd === "verify") {
   // spawn the standalone verifier untouched; mark the dispatch so it skips its deprecation notice.
-  const verifier = fileURLToPath(new URL('./verify-registry-item.mjs', HERE));
+  const verifier = fileURLToPath(new URL("./verify-registry-item.mjs", HERE));
   const r = spawnSync(process.execPath, [verifier, ...rest], {
-    stdio: 'inherit',
-    env: { ...process.env, VEGASTACK_DESIGN_DISPATCH: '1' },
+    stdio: "inherit",
+    env: { ...process.env, VEGASTACK_DESIGN_DISPATCH: "1" },
   });
   process.exit(r.status ?? 1);
 }
 
+// Name the installed version: the most common cause of "unknown command" is a consumer following
+// documentation for a newer release than the one they actually have installed.
 console.error(`unknown command: ${cmd}\n`);
+console.error(
+  `(this is @vegastack/design@${version()} — if you expected "${cmd}", check whether it`,
+);
+console.error(
+  `requires a newer version: npm view @vegastack/design version)\n`,
+);
 console.error(USAGE);
 process.exit(2);