@aathan807/rw-design 1.0.0

package/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+const { CliError } = require("./src/utils/errors");
+
+const commands = {
+  init: () => require("./src/commands/init")(process.argv.slice(3)),
+  check: () => require("./src/commands/check")(),
+  update: () => require("./src/commands/update")(),
+  list: () => require("./src/commands/list")(),
+  pull: () => require("./src/commands/pull")(process.argv[3]),
+};
+
+function usage() {
+  console.log(
+    "rw-design — RandomWalk Design Intelligence\n\n" +
+      "Usage:\n" +
+      "  rw-design init       Install design intelligence into this project (interactive)\n" +
+      "  rw-design check      Check whether an update is available\n" +
+      "  rw-design update     Update installed design intelligence\n" +
+      "  rw-design list       Browse everything available in the KB\n" +
+      "  rw-design pull <id>  Install one knowledge file (+ dependencies)\n"
+  );
+}
+
+async function main() {
+  const command = process.argv[2];
+  const handler = commands[command];
+
+  if (!handler) {
+    usage();
+    process.exitCode = command ? 1 : 0;
+    return;
+  }
+
+  await handler();
+}
+
+main().catch((err) => {
+  if (err && err.isCliError) {
+    console.error(`\nError: ${err.message}`);
+  } else {
+    console.error(`\nUnexpected error: ${err && err.message ? err.message : err}`);
+  }
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@aathan807/rw-design",
+  "version": "1.0.0",
+  "description": "RandomWalk Design Intelligence CLI — installs versioned design knowledge into any project.",
+  "bin": {
+    "rw-design": "./index.js"
+  },
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --check index.js"
+  },
+  "keywords": ["design", "cli", "randomwalk", "design-intelligence"],
+  "author": "aathan807",
+  "license": "ISC",
+  "dependencies": {
+    "inquirer": "^14.0.2"
+  }
+}

package/src/commands/check.js

@@ -0,0 +1,34 @@
+const path = require("path");
+const github = require("../github/client");
+const fs = require("../utils/filesystem");
+const source = require("../config/source");
+const { compareVersions } = require("../utils/version");
+
+/**
+ * `rw-design check` — compare the installed KB version against the remote.
+ */
+module.exports = async function check() {
+  const installRoot = path.join(process.cwd(), source.installDir);
+  const localVersion = fs.readJSON(path.join(installRoot, "version.json"));
+
+  if (!localVersion) {
+    console.log(
+      "Design Intelligence is not installed in this project.\n\nRun:\n  rw-design init"
+    );
+    return;
+  }
+
+  const remoteVersion = await github.fetchJSON("version.json");
+  const cmp = compareVersions(localVersion.version, remoteVersion.version);
+
+  if (cmp >= 0) {
+    console.log(`✓ Design Intelligence is up to date.\n\nCurrent version: ${localVersion.version}`);
+  } else {
+    console.log(
+      "⚡ Design Intelligence update available\n\n" +
+        `Installed: ${localVersion.version}\n` +
+        `Latest:    ${remoteVersion.version}\n\n` +
+        "Run:\n  rw-design update"
+    );
+  }
+};

package/src/commands/init.js

@@ -0,0 +1,68 @@
+const path = require("path");
+const inquirer = require("inquirer").default;
+const github = require("../github/client");
+const fs = require("../utils/filesystem");
+const source = require("../config/source");
+const { buildQuestions } = require("../profile/questions");
+const { CliError } = require("../utils/errors");
+const { installFromProfile } = require("./install-core");
+
+/**
+ * `rw-design init` — first-time install.
+ * Interactive by default; non-interactive with:
+ *   --defaults             accept the default/first choice for every question
+ *   --profile <file.json>  read the full profile from a JSON file
+ * Validates env, resolves the KB, downloads files, and writes the installed
+ * layout + agent instructions. Safe to re-run.
+ */
+module.exports = async function init(args = []) {
+  const cwd = process.cwd();
+  github.requireToken(); // throws friendly error if missing
+  if (!fs.isWritable(cwd)) {
+    throw new CliError(`Current directory is not writable:\n${cwd}`);
+  }
+
+  const installRoot = path.join(cwd, source.installDir);
+
+  console.log("Fetching Design Intelligence catalog...\n");
+  const registry = await github.fetchJSON("registry.json");
+  const remoteVersion = await github.fetchJSON("version.json");
+
+  const questions = buildQuestions(registry);
+  let profile;
+  const profileFlag = args.indexOf("--profile");
+  if (profileFlag !== -1) {
+    const file = args[profileFlag + 1];
+    if (!file) throw new CliError("Usage: rw-design init --profile <file.json>");
+    profile = fs.readJSON(path.resolve(cwd, file));
+    if (!profile) throw new CliError(`Profile file not found: ${file}`);
+    // Fill anything the file omits with question defaults.
+    for (const q of questions) {
+      if (profile[q.name] === undefined) profile[q.name] = q.default ?? q.choices[0].value;
+    }
+  } else if (args.includes("--defaults")) {
+    profile = Object.fromEntries(questions.map((q) => [q.name, q.default ?? q.choices[0].value]));
+    console.log("Using defaults:", JSON.stringify(profile));
+  } else {
+    profile = { ...(await inquirer.prompt(questions)) };
+  }
+
+  console.log("\nResolving design knowledge for your project...\n");
+  const { resolved } = await installFromProfile({
+    installRoot,
+    profile,
+    registry,
+    remoteVersion,
+    source,
+  });
+
+  for (const r of resolved) {
+    console.log(`  ✓ ${r.id}`);
+  }
+
+  console.log(
+    `\n🎉 Design Intelligence installed into ${source.installDir}/` +
+      `\n   ${resolved.length} files · KB version ${remoteVersion.version}` +
+      `\n\nRead ${source.installDir}/CLAUDE.md and start building.`
+  );
+};

package/src/commands/install-core.js

@@ -0,0 +1,168 @@
+const path = require("path");
+const github = require("../github/client");
+const fs = require("../utils/filesystem");
+const { resolve } = require("../resolver/resolve");
+const { CliError } = require("../utils/errors");
+
+/**
+ * Shared installation logic used by `init` and `update`.
+ * Given a profile, resolves the file set from the remote registry, downloads
+ * each file into <installRoot>/knowledge/<id>.md, and (re)generates:
+ *   - DESIGN.md      — single consolidated entry file (tokens + rules + index)
+ *   - CLAUDE.md / AGENTS.md — agent instructions pointing at DESIGN.md
+ *   - manifest.json / profile.json / version.json
+ */
+
+const KNOWLEDGE_SUBDIR = "knowledge";
+
+function localRelPath(entry) {
+  return `${KNOWLEDGE_SUBDIR}/${entry.id}.md`;
+}
+
+/** Strip YAML frontmatter from a knowledge file body. */
+function stripFrontmatter(text) {
+  return text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trim();
+}
+
+async function installFromProfile({ installRoot, profile, registry, remoteVersion, source }) {
+  const resolved = resolve(profile, registry);
+  if (resolved.length === 0) {
+    // Should not happen (brand/foundations are always-on), but guard anyway.
+    throw new CliError("No design knowledge matched this project profile.");
+  }
+
+  const results = [];
+  const contentsById = new Map();
+  for (const entry of resolved) {
+    const content = await github.fetchFile(entry.path);
+    fs.writeText(path.join(installRoot, localRelPath(entry)), content);
+    contentsById.set(entry.id, content);
+    results.push({
+      id: entry.id,
+      title: entry.title,
+      category: entry.category,
+      source: entry.path,
+      local: localRelPath(entry),
+    });
+  }
+
+  // manifest.json — what is installed + where it came from.
+  const manifest = {
+    source: { owner: source.owner, repository: source.repo, branch: source.branch },
+    profile,
+    installedFiles: results,
+  };
+  fs.writeJSON(path.join(installRoot, "manifest.json"), manifest);
+
+  // profile.json — kept separately so `update` can re-resolve.
+  fs.writeJSON(path.join(installRoot, "profile.json"), profile);
+
+  // version.json — installed KB version.
+  fs.writeJSON(path.join(installRoot, "version.json"), { version: remoteVersion.version });
+
+  // DESIGN.md — the single consolidated entry file agents read first.
+  fs.writeText(
+    path.join(installRoot, "DESIGN.md"),
+    renderDesignMd({ profile, results, contentsById, version: remoteVersion.version })
+  );
+
+  // Agent instruction files (Claude Code / Codex) — point at DESIGN.md.
+  const instructions = renderAgentInstructions({ profile, results, version: remoteVersion.version });
+  fs.writeText(path.join(installRoot, "CLAUDE.md"), instructions);
+  fs.writeText(path.join(installRoot, "AGENTS.md"), instructions);
+
+  return { resolved: results };
+}
+
+/**
+ * Render the consolidated DESIGN.md: profile front matter, the full theme
+ * token sheets inlined (brand + themes are the highest-priority layers), and a
+ * priority-ordered index into the per-topic knowledge files.
+ */
+function renderDesignMd({ profile, results, contentsById, version }) {
+  const fm = [
+    "---",
+    `generated_by: rw-design`,
+    `kb_version: "${version}"`,
+    `company: ${profile.company}`,
+    `product: ${profile.product}`,
+    `project_type: ${profile.projectType}`,
+    `platform: ${profile.platform}`,
+    `framework: ${profile.framework}`,
+    ...(profile.density ? [`density: ${profile.density}`] : []),
+    ...(profile.visualTone ? [`visual_tone: ${profile.visualTone}`] : []),
+    ...(profile.colorMode ? [`color_mode: ${profile.colorMode}`] : []),
+    "---",
+  ].join("\n");
+
+  const inlineCategories = ["brand", "theme"];
+  const inlined = results
+    .filter((r) => inlineCategories.includes(r.category))
+    .map((r) => stripFrontmatter(contentsById.get(r.id) || ""))
+    .join("\n\n---\n\n");
+
+  const groups = new Map();
+  for (const r of results) {
+    if (inlineCategories.includes(r.category)) continue;
+    if (!groups.has(r.category)) groups.set(r.category, []);
+    groups.get(r.category).push(r);
+  }
+  const index = [...groups.entries()]
+    .map(([category, entries]) => {
+      const rows = entries.map((r) => `- [\`${r.id}\`](${r.local}) — ${r.title}`).join("\n");
+      return `### ${category[0].toUpperCase()}${category.slice(1)}\n${rows}`;
+    })
+    .join("\n\n");
+
+  return `${fm}
+
+# Design System — ${profile.product === "none" ? "RandomWalk" : profile.product} / ${profile.projectType}
+
+> **Read this file before generating any UI.** It is the design contract for this
+> project. Tokens and brand rules are inlined below; topic-specific rules are in the
+> linked knowledge files. Priority: brand → theme → product → pattern → topic files →
+> skill. Accessibility is a hard floor. Checklists are acceptance criteria.
+
+${inlined}
+
+---
+
+## Knowledge index (read the relevant file before building that surface)
+
+${index}
+
+_Generated by rw-design from KB version ${version}. Do not edit by hand._
+`;
+}
+
+function renderAgentInstructions({ profile, results, version }) {
+  const list = results.map((r) => `- \`${r.local}\` — ${r.title} (\`${r.id}\`)`).join("\n");
+  return `# Design Intelligence — Agent Instructions
+
+This project has RandomWalk design intelligence installed (KB version ${version}).
+**Start with \`DESIGN.md\` in this directory** — it is the consolidated design contract
+(tokens, brand rules, and an index into everything below). These files are authoritative
+for design, UI, and UX decisions; follow them over generic defaults.
+
+## Project profile
+- Company: ${profile.company}
+- Product: ${profile.product}
+- Project type: ${profile.projectType}
+- Platform: ${profile.platform}
+- Framework: ${profile.framework}
+
+## Installed knowledge (priority order)
+${list}
+
+## How to apply
+1. Read \`DESIGN.md\` first; use \`manifest.json\` to see what is installed.
+2. When building a specific surface, consult the matching knowledge file(s) above.
+3. Resolve conflicts by this priority: **brand → theme → product → pattern → navigation / interaction / content / presentation → skill**. Higher wins — except accessibility, which is a hard floor nothing may violate.
+4. Files with ids starting \`checklist.\` are acceptance criteria: verify built UI against the relevant checklist sections before considering it done.
+5. Do not edit these files by hand — they are managed by \`rw-design update\`.
+
+_Generated by rw-design. Run \`rw-design check\` for updates._
+`;
+}
+
+module.exports = { installFromProfile };

package/src/commands/list.js

@@ -0,0 +1,33 @@
+const github = require("../github/client");
+
+/**
+ * `rw-design list` — browse the KB registry: every installable knowledge file,
+ * grouped by category, with targeting metadata.
+ */
+module.exports = async function list() {
+  const registry = await github.fetchJSON("registry.json");
+  const version = await github.fetchJSON("version.json");
+
+  const groups = new Map();
+  for (const entry of registry.files) {
+    if (!groups.has(entry.category)) groups.set(entry.category, []);
+    groups.get(entry.category).push(entry);
+  }
+
+  console.log(`Design Intelligence KB — version ${version.version}\n`);
+  for (const [category, entries] of groups) {
+    console.log(`${category.toUpperCase()}`);
+    for (const e of entries.sort((a, b) => a.id.localeCompare(b.id))) {
+      const scope = [
+        e.applies_to?.length ? `applies: ${e.applies_to.join(", ")}` : "",
+        e.platforms?.length ? `platforms: ${e.platforms.join(", ")}` : "",
+        e.variant_of ? `variant of ${e.variant_of}` : "",
+      ]
+        .filter(Boolean)
+        .join(" · ");
+      console.log(`  ${e.id.padEnd(32)} ${e.title}${scope ? `  (${scope})` : ""}`);
+    }
+    console.log("");
+  }
+  console.log(`${registry.files.length} files. Install one with:  rw-design pull <id>`);
+};

package/src/commands/pull.js

@@ -0,0 +1,86 @@
+const path = require("path");
+const github = require("../github/client");
+const fs = require("../utils/filesystem");
+const source = require("../config/source");
+const { CliError } = require("../utils/errors");
+
+/**
+ * `rw-design pull <id>` — install a single knowledge file (plus its transitive
+ * dependencies) on top of whatever is already installed. Useful for grabbing
+ * knowledge outside your profile's automatic resolution.
+ */
+module.exports = async function pull(id) {
+  if (!id) {
+    throw new CliError("Usage: rw-design pull <id>\n\nSee available ids with:  rw-design list");
+  }
+
+  const installRoot = path.join(process.cwd(), source.installDir);
+  const registry = await github.fetchJSON("registry.json");
+  const byId = new Map(registry.files.map((f) => [f.id, f]));
+
+  if (!byId.has(id)) {
+    throw new CliError(`Unknown id: ${id}\n\nSee available ids with:  rw-design list`);
+  }
+
+  // Close over dependencies.
+  const wanted = new Set([id]);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const wid of [...wanted]) {
+      for (const dep of byId.get(wid).dependencies || []) {
+        if (byId.has(dep) && !wanted.has(dep)) {
+          wanted.add(dep);
+          changed = true;
+        }
+      }
+    }
+  }
+
+  // Skip files already installed (manifest is the record of truth).
+  const manifestPath = path.join(installRoot, "manifest.json");
+  const manifest =
+    fs.readJSON(manifestPath) || {
+      source: { owner: source.owner, repository: source.repo, branch: source.branch },
+      profile: null,
+      installedFiles: [],
+    };
+  const installedIds = new Set(manifest.installedFiles.map((f) => f.id));
+
+  const toInstall = [...wanted].map((wid) => byId.get(wid));
+  let added = 0;
+  for (const entry of toInstall) {
+    const local = `knowledge/${entry.id}.md`;
+    const content = await github.fetchFile(entry.path);
+    fs.writeText(path.join(installRoot, local), content);
+    if (installedIds.has(entry.id)) {
+      console.log(`  ✓ ${entry.id} (refreshed)`);
+    } else {
+      manifest.installedFiles.push({
+        id: entry.id,
+        title: entry.title,
+        category: entry.category,
+        source: entry.path,
+        local,
+      });
+      console.log(`  ✓ ${entry.id} (added)`);
+      added++;
+    }
+  }
+
+  fs.writeJSON(manifestPath, manifest);
+
+  // Record the KB version if this is a fresh directory (don't clobber an existing one).
+  const versionPath = path.join(installRoot, "version.json");
+  if (!fs.exists(versionPath)) {
+    const remoteVersion = await github.fetchJSON("version.json");
+    fs.writeJSON(versionPath, { version: remoteVersion.version });
+  }
+
+  console.log(
+    `\n✓ Pulled ${toInstall.length} file(s) (${added} new).` +
+      (manifest.profile
+        ? ""
+        : "\n  Note: no project profile found — run `rw-design init` for full setup (DESIGN.md, agent instructions).")
+  );
+};

package/src/commands/update.js

@@ -0,0 +1,52 @@
+const path = require("path");
+const github = require("../github/client");
+const fs = require("../utils/filesystem");
+const source = require("../config/source");
+const { compareVersions } = require("../utils/version");
+const { CliError } = require("../utils/errors");
+const { installFromProfile } = require("./install-core");
+
+/**
+ * `rw-design update` — re-resolve from the saved profile and refresh files.
+ * Re-resolving (rather than just re-downloading the old set) means newly
+ * applicable knowledge is picked up as the KB grows.
+ */
+module.exports = async function update() {
+  const installRoot = path.join(process.cwd(), source.installDir);
+  const localVersion = fs.readJSON(path.join(installRoot, "version.json"));
+  const profile = fs.readJSON(path.join(installRoot, "profile.json"));
+
+  if (!localVersion || !profile) {
+    throw new CliError(
+      "Design Intelligence is not installed in this project.\n\nRun:\n  rw-design init"
+    );
+  }
+
+  const remoteVersion = await github.fetchJSON("version.json");
+  if (compareVersions(localVersion.version, remoteVersion.version) >= 0) {
+    console.log(`✓ Already up to date.\n\nCurrent version: ${localVersion.version}`);
+    return;
+  }
+
+  console.log(
+    "Design Intelligence update available\n\n" +
+      `${localVersion.version} → ${remoteVersion.version}\n\nUpdating...\n`
+  );
+
+  const registry = await github.fetchJSON("registry.json");
+  const { resolved } = await installFromProfile({
+    installRoot,
+    profile,
+    registry,
+    remoteVersion,
+    source,
+  });
+
+  for (const r of resolved) {
+    console.log(`  ✓ ${r.local} updated`);
+  }
+
+  console.log(
+    `\nDesign Intelligence updated successfully.\n\n${localVersion.version} → ${remoteVersion.version}`
+  );
+};

package/src/config/source.js

@@ -0,0 +1,12 @@
+/**
+ * Where the design knowledge base lives. Single place to configure the source
+ * repository (principle: keep the GitHub repo configurable).
+ */
+module.exports = {
+  owner: "AathanRW",
+  repo: "rw-design-kb",
+  branch: "main",
+
+  // Path (inside the developer's project) where design intelligence is installed.
+  installDir: ".design-intelligence",
+};

package/src/github/client.js

@@ -0,0 +1,78 @@
+const { CliError } = require("../utils/errors");
+const source = require("../config/source");
+
+/**
+ * GitHub access layer. Responsible for authentication, URL building, fetching
+ * files from the private KB, and mapping API/network failures to friendly errors.
+ * Never logs or exposes the token or request headers.
+ */
+
+function requireToken() {
+  const token = process.env.GITHUB_TOKEN;
+  if (!token || !token.trim()) {
+    throw new CliError(
+      "GITHUB_TOKEN is not configured.\n\n" +
+        'Set it first, e.g. (PowerShell):  $env:GITHUB_TOKEN="<your token>"'
+    );
+  }
+  return token;
+}
+
+function contentsUrl(path) {
+  const { owner, repo, branch } = source;
+  return `https://api.github.com/repos/${owner}/${repo}/contents/${path}?ref=${branch}`;
+}
+
+async function fetchRaw(path, { asJson = false } = {}) {
+  const token = requireToken();
+  let response;
+  try {
+    response = await fetch(contentsUrl(path), {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github.raw+json",
+        "User-Agent": "rw-design-cli",
+      },
+    });
+  } catch {
+    throw new CliError(
+      "Unable to connect to the Design Intelligence repository.\n" +
+        "Check your internet connection and try again."
+    );
+  }
+
+  if (response.status === 401) {
+    throw new CliError("Unable to authenticate with GitHub. Check your GITHUB_TOKEN.");
+  }
+  if (response.status === 404) {
+    throw new CliError(`Knowledge file not found in the repository:\n${path}`);
+  }
+  if (response.status === 403) {
+    throw new CliError(
+      "Unable to access the Design Intelligence repository (permission denied or rate limited)."
+    );
+  }
+  if (!response.ok) {
+    throw new CliError(`Unable to fetch ${path} (HTTP ${response.status}).`);
+  }
+
+  const text = await response.text();
+  if (!asJson) return text;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CliError(`Malformed JSON received for ${path}.`);
+  }
+}
+
+/** Fetch a markdown/text file from the KB. */
+function fetchFile(path) {
+  return fetchRaw(path, { asJson: false });
+}
+
+/** Fetch and parse a JSON file (registry.json, version.json) from the KB. */
+function fetchJSON(path) {
+  return fetchRaw(path, { asJson: true });
+}
+
+module.exports = { fetchFile, fetchJSON, requireToken };

package/src/profile/questions.js

@@ -0,0 +1,114 @@
+/**
+ * Builds the interactive questions for `rw-design init` FROM THE KB REGISTRY,
+ * so designers can add products, patterns, and skills to the KB without any
+ * CLI change:
+ *   - products      ← entries with category "product"  (id: product.<value>)
+ *   - project types ← entries with category "pattern"  (id: pattern.<value>)
+ *   - frameworks    ← entries with category "skill"    (framework: <value>)
+ *
+ * Preference questions (density, tone, color mode) drive VARIANT selection —
+ * see templates/variant-template.md in the KB.
+ */
+
+function titleCase(slug) {
+  return slug
+    .split("-")
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+function buildQuestions(registry) {
+  const products = registry.files
+    .filter((f) => f.category === "product")
+    .map((f) => ({ name: f.title.replace(/ Product$/, ""), value: f.id.replace(/^product\./, "") }));
+
+  const projectTypes = registry.files
+    .filter((f) => f.category === "pattern")
+    .map((f) => ({ name: f.title.replace(/ Pattern$/, ""), value: f.id.replace(/^pattern\./, "") }));
+
+  // Project types can also come from applies_to targeting on knowledge files
+  // even when no pattern exists yet.
+  const fromAppliesTo = new Set(registry.files.flatMap((f) => f.applies_to || []));
+  for (const t of fromAppliesTo) {
+    if (!projectTypes.some((p) => p.value === t)) projectTypes.push({ name: titleCase(t), value: t });
+  }
+
+  const frameworks = registry.files
+    .filter((f) => f.category === "skill" && f.framework)
+    .map((f) => ({ name: f.title.replace(/ Implementation$/, ""), value: f.framework }));
+
+  const platforms = [...new Set(registry.files.flatMap((f) => f.platforms || []))].map((p) => ({
+    name: titleCase(p),
+    value: p,
+  }));
+
+  return [
+    {
+      type: "select",
+      name: "company",
+      message: "Is this project part of RandomWalk?",
+      choices: [{ name: "RandomWalk", value: "randomwalk" }],
+      default: "randomwalk",
+    },
+    {
+      type: "select",
+      name: "product",
+      message: "Which product?",
+      choices: [...products, { name: "None / general", value: "none" }],
+    },
+    {
+      type: "select",
+      name: "projectType",
+      message: "What are you building?",
+      choices: projectTypes.sort((a, b) => a.name.localeCompare(b.name)),
+    },
+    {
+      type: "select",
+      name: "platform",
+      message: "Platform?",
+      choices: platforms.length ? platforms : [{ name: "Web", value: "web" }],
+      default: "web",
+    },
+    {
+      type: "select",
+      name: "framework",
+      message: "Framework?",
+      choices: [...frameworks, { name: "Other / none", value: "none" }],
+    },
+
+    // Design preferences — select knowledge VARIANTS when the KB provides them.
+    {
+      type: "select",
+      name: "density",
+      message: "Interface density?",
+      choices: [
+        { name: "Comfortable (default)", value: "comfortable" },
+        { name: "Dense (data-heavy screens)", value: "dense" },
+      ],
+      default: "comfortable",
+    },
+    {
+      type: "select",
+      name: "visualTone",
+      message: "Visual tone?",
+      choices: [
+        { name: "Minimal / professional (default)", value: "minimal" },
+        { name: "Expressive / bold", value: "expressive" },
+      ],
+      default: "minimal",
+    },
+    {
+      type: "select",
+      name: "colorMode",
+      message: "Default color mode?",
+      choices: [
+        { name: "Follow system (default)", value: "system" },
+        { name: "Light", value: "light" },
+        { name: "Dark", value: "dark" },
+      ],
+      default: "system",
+    },
+  ];
+}
+
+module.exports = { buildQuestions };

package/src/resolver/resolve.js

@@ -0,0 +1,106 @@
+/**
+ * Resolver: turns a project profile + the KB registry into the concrete set of
+ * knowledge files to install. This is the module a future, smarter resolver
+ * replaces — commands depend only on `resolve(profile, registry)`.
+ *
+ * Selection rules:
+ *   - Always include: brand.*, core presentation (spacing, typography),
+ *     content.voice-tone, and accessibility for the chosen platform.
+ *   - Include the chosen product   (product.<product>).
+ *   - Include the chosen pattern    (pattern.<projectType>).
+ *   - Include the chosen skill      (skill.<framework>).
+ *   - Include any knowledge whose applies_to matches projectType AND whose
+ *     platforms include the chosen platform (empty platforms = all).
+ *   - Then close over `dependencies` transitively.
+ */
+
+function platformMatches(entry, platform) {
+  return !entry.platforms || entry.platforms.length === 0 || entry.platforms.includes(platform);
+}
+
+function productMatches(entry, product) {
+  return !entry.products || entry.products.length === 0 || entry.products.includes(product);
+}
+
+function resolve(profile, registry) {
+  const byId = new Map(registry.files.map((f) => [f.id, f]));
+  const selected = new Set();
+
+  const add = (id) => {
+    if (byId.has(id)) selected.add(id);
+  };
+
+  for (const entry of registry.files) {
+    // Variants never enter through base selection — only via substitution below.
+    if (entry.variant_of) continue;
+    if (!platformMatches(entry, profile.platform)) continue;
+    if (!productMatches(entry, profile.product)) continue;
+
+    // Always-on foundations. Themes and checklists are filtered by the
+    // platform/product guards above (e.g. theme.visual-ai only installs for visual-ai).
+    if (entry.category === "brand") add(entry.id);
+    if (entry.category === "theme") add(entry.id);
+    if (entry.category === "checklist") add(entry.id);
+
+    // Product-scoped knowledge: a file declaring products: [x] is by definition
+    // relevant to product x — auto-install when the profile's product matches.
+    // (Files with empty products pass productMatches for everyone, so require
+    // an explicit non-empty products list here.)
+    if (entry.products && entry.products.length > 0) add(entry.id);
+    if (entry.id === "presentation.spacing" || entry.id === "presentation.typography") add(entry.id);
+    if (entry.id === "content.voice-tone") add(entry.id);
+    if (entry.category === "accessibility") add(entry.id);
+
+    // Profile-driven selections.
+    if (entry.id === `product.${profile.product}`) add(entry.id);
+    if (entry.id === `pattern.${profile.projectType}`) add(entry.id);
+    if (entry.framework && entry.framework === profile.framework) add(entry.id);
+
+    // Knowledge that declares it applies to this project type.
+    if (entry.applies_to && entry.applies_to.includes(profile.projectType)) add(entry.id);
+  }
+
+  // Variant substitution: an entry with `variant_of: <baseId>` plus `when_*`
+  // conditions replaces its base when every condition matches the profile
+  // (e.g. when_density: dense). Authored via templates/variant-template.md.
+  for (const entry of registry.files) {
+    if (!entry.variant_of || !selected.has(entry.variant_of)) continue;
+    if (!platformMatches(entry, profile.platform)) continue;
+    if (!productMatches(entry, profile.product)) continue;
+    const conditions = Object.entries(entry).filter(([k]) => k.startsWith("when_"));
+    if (conditions.length === 0) continue;
+    const allMatch = conditions.every(([k, v]) => profile[k.slice(5)] === v);
+    if (allMatch) {
+      selected.delete(entry.variant_of);
+      selected.add(entry.id);
+    }
+  }
+
+  // Transitive dependency closure.
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const id of [...selected]) {
+      const entry = byId.get(id);
+      for (const dep of entry.dependencies || []) {
+        if (byId.has(dep) && !selected.has(dep)) {
+          selected.add(dep);
+          changed = true;
+        }
+      }
+    }
+  }
+
+  // Return registry entries, ordered by priority for readable output/manifest.
+  const order = ["brand", "theme", "product", "pattern", "component", "navigation", "interaction", "content", "presentation", "accessibility", "skill", "checklist"];
+  return [...selected]
+    .map((id) => byId.get(id))
+    .sort((a, b) => {
+      const oa = order.indexOf(a.category);
+      const ob = order.indexOf(b.category);
+      if (oa !== ob) return oa - ob;
+      return a.id.localeCompare(b.id);
+    });
+}
+
+module.exports = { resolve };

package/src/utils/errors.js

@@ -0,0 +1,13 @@
+/**
+ * Centralized error type. Commands throw CliError with a user-friendly message;
+ * index.js prints only that message (never stack traces, tokens, or headers).
+ */
+class CliError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliError";
+    this.isCliError = true;
+  }
+}
+
+module.exports = { CliError };

package/src/utils/filesystem.js

@@ -0,0 +1,43 @@
+const fs = require("fs");
+const path = require("path");
+
+/** Create a directory (and parents) if it does not exist. */
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+/** True if a path exists. */
+function exists(target) {
+  return fs.existsSync(target);
+}
+
+/** Read and parse a JSON file. Returns null if it does not exist. */
+function readJSON(file) {
+  if (!fs.existsSync(file)) return null;
+  // Strip a UTF-8 BOM if present (PowerShell 5.1's Out-File adds one).
+  return JSON.parse(fs.readFileSync(file, "utf8").replace(/^/, ""));
+}
+
+/** Write a value as pretty JSON (trailing newline). */
+function writeJSON(file, value) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + "\n");
+}
+
+/** Write a text/markdown file, creating parent dirs. */
+function writeText(file, content) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, content);
+}
+
+/** True if a directory is writable (used to validate cwd before install). */
+function isWritable(dir) {
+  try {
+    fs.accessSync(dir, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { ensureDir, exists, readJSON, writeJSON, writeText, isWritable };

package/src/utils/version.js

@@ -0,0 +1,20 @@
+/**
+ * Version comparison. Kept deliberately simple for the POC but structured so a
+ * full semver implementation can replace `compareVersions` without touching callers.
+ *
+ * Returns: -1 if a < b, 0 if equal, 1 if a > b.
+ */
+function compareVersions(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+module.exports = { compareVersions };