whale-igniter 1.2.2 → 1.3.0

package/dist/commands/references.js

@@ -0,0 +1,193 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { resolveTarget } from "../utils/paths.js";
+import { loadConfig, saveConfig } from "../utils/config.js";
+import { generateWiki } from "../generators/wikiGenerator.js";
+import { ui } from "../ui/index.js";
+import prompts from "prompts";
+const VALID_CATEGORIES = ["forms", "navigation", "feedback", "surface", "layout", "data-display"];
+function shippedReferencesDir() {
+    // Resolve relative to this file's location: src/commands/ → root → ui-references/
+    const thisFile = new URL(import.meta.url).pathname;
+    return path.resolve(path.dirname(thisFile), "../../ui-references");
+}
+function projectReferencesDir(target) {
+    return path.join(target, "references");
+}
+// ---------------------------------------------------------------------------
+// `whale references list`
+// ---------------------------------------------------------------------------
+export async function referencesListCommand(targetArg) {
+    const target = resolveTarget(targetArg);
+    const config = await loadConfig(target);
+    const refDir = projectReferencesDir(target);
+    console.log();
+    console.log(ui.header("UI References", "list"));
+    console.log();
+    const configuredCategories = config.uiReferences ?? [];
+    const rows = [];
+    for (const cat of VALID_CATEGORIES) {
+        const filePath = path.join(refDir, `${cat}.md`);
+        const present = await fs.pathExists(filePath);
+        const configured = configuredCategories.includes(cat);
+        const status = present ? ui.ok("present") : ui.muted("not copied");
+        const flag = configured ? ui.glyph.check : " ";
+        rows.push([flag, ui.code(cat), status]);
+    }
+    const indexPath = path.join(refDir, "INDEX.md");
+    const indexPresent = await fs.pathExists(indexPath);
+    console.log(ui.section("Categories"));
+    for (const [flag, cat, status] of rows) {
+        console.log(`  ${flag} ${cat.padEnd(16)} ${status}`);
+    }
+    console.log();
+    console.log(ui.kv("references/INDEX.md", indexPresent ? ui.ok("present") : ui.muted("not copied")));
+    if (configuredCategories.length === 0 && !indexPresent) {
+        console.log();
+        console.log(ui.note("No references installed yet."));
+        console.log(ui.indent(ui.muted("Run `whale references add <category>` or `whale references add --all`.")));
+    }
+    console.log();
+}
+// ---------------------------------------------------------------------------
+// `whale references add [category | --all]`
+// ---------------------------------------------------------------------------
+export async function referencesAddCommand(category, opts) {
+    const target = resolveTarget(opts.target);
+    const shipped = shippedReferencesDir();
+    const refDir = projectReferencesDir(target);
+    console.log();
+    console.log(ui.header("UI References", opts.all ? "add --all" : `add ${category ?? ""}`));
+    console.log();
+    if (!opts.all && !category) {
+        console.log(ui.fail("Specify a category or use --all."));
+        console.log(ui.muted(`  Valid categories: ${VALID_CATEGORIES.join(", ")}`));
+        process.exitCode = 1;
+        return;
+    }
+    const categoriesToAdd = opts.all
+        ? [...VALID_CATEGORIES]
+        : [category];
+    // Validate
+    for (const cat of categoriesToAdd) {
+        if (!VALID_CATEGORIES.includes(cat)) {
+            console.log(ui.fail(`Unknown category: ${cat}`));
+            console.log(ui.muted(`  Valid: ${VALID_CATEGORIES.join(", ")}`));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    await fs.ensureDir(refDir);
+    // Always copy INDEX.md
+    const shippedIndex = path.join(shipped, "INDEX.md");
+    const projectIndex = path.join(refDir, "INDEX.md");
+    if (!(await fs.pathExists(projectIndex))) {
+        await fs.copy(shippedIndex, projectIndex);
+        console.log(ui.ok(`Copied references/INDEX.md`));
+    }
+    const copied = [];
+    const skipped = [];
+    for (const cat of categoriesToAdd) {
+        const src = path.join(shipped, `${cat}.md`);
+        const dest = path.join(refDir, `${cat}.md`);
+        if (!(await fs.pathExists(src))) {
+            console.log(ui.warn(`Shipped file not found for category: ${cat}`));
+            continue;
+        }
+        if (await fs.pathExists(dest)) {
+            skipped.push(cat);
+            continue;
+        }
+        await fs.copy(src, dest);
+        copied.push(cat);
+        console.log(ui.ok(`Copied references/${cat}.md`));
+    }
+    if (skipped.length > 0) {
+        console.log();
+        console.log(ui.note(`Skipped (already present): ${skipped.join(", ")}. Run \`whale references update\` to refresh.`));
+    }
+    // Update whale.config.json
+    const config = await loadConfig(target);
+    const existing = new Set(config.uiReferences ?? []);
+    for (const cat of copied)
+        existing.add(cat);
+    config.uiReferences = Array.from(existing).sort();
+    await saveConfig(target, config);
+    // Regenerate CLAUDE.md to include the references section
+    if (copied.length > 0) {
+        await generateWiki(target);
+        console.log();
+        console.log(ui.ok("CLAUDE.md updated with references section."));
+    }
+    console.log();
+    console.log(ui.info(`AI tools can now read references/ — consult references/INDEX.md for navigation.`));
+    console.log();
+}
+// ---------------------------------------------------------------------------
+// `whale references update`
+// ---------------------------------------------------------------------------
+export async function referencesUpdateCommand(targetArg) {
+    const target = resolveTarget(targetArg);
+    const shipped = shippedReferencesDir();
+    const refDir = projectReferencesDir(target);
+    console.log();
+    console.log(ui.header("UI References", "update"));
+    console.log();
+    if (!(await fs.pathExists(refDir))) {
+        console.log(ui.warn("No references/ directory found in this project."));
+        console.log(ui.muted("  Run `whale references add <category>` first."));
+        return;
+    }
+    const config = await loadConfig(target);
+    const configuredCategories = config.uiReferences ?? [];
+    const allFilesToCheck = ["INDEX", ...configuredCategories.map((c) => c)];
+    for (const slug of allFilesToCheck) {
+        const filename = slug === "INDEX" ? "INDEX.md" : `${slug}.md`;
+        const src = path.join(shipped, filename);
+        const dest = path.join(refDir, filename);
+        if (!(await fs.pathExists(src)))
+            continue;
+        if (!(await fs.pathExists(dest))) {
+            await fs.copy(src, dest);
+            console.log(ui.ok(`Added ${filename} (was missing)`));
+            continue;
+        }
+        // Compare content — only prompt if modified
+        const [srcContent, destContent] = await Promise.all([
+            fs.readFile(src, "utf-8"),
+            fs.readFile(dest, "utf-8")
+        ]);
+        if (srcContent === destContent) {
+            console.log(`  ${ui.glyph.check} ${filename} is up to date`);
+            continue;
+        }
+        // File differs — prompt
+        const { action } = await prompts({
+            type: "select",
+            name: "action",
+            message: `references/${filename} has local modifications. What would you like to do?`,
+            choices: [
+                { title: "Keep my version", value: "keep" },
+                { title: "Overwrite with shipped version", value: "overwrite" },
+                { title: "Show diff summary", value: "diff" }
+            ]
+        });
+        if (action === "overwrite") {
+            await fs.copy(src, dest);
+            console.log(ui.ok(`Overwritten: references/${filename}`));
+        }
+        else if (action === "diff") {
+            const srcLines = srcContent.split("\n").length;
+            const destLines = destContent.split("\n").length;
+            console.log(ui.note(`Shipped: ${srcLines} lines. Your version: ${destLines} lines. ` +
+                `Use a diff tool to compare: diff references/${filename} <(whale references --shipped ${slug})`));
+            console.log(ui.muted("  Keeping your version."));
+        }
+        else {
+            console.log(ui.muted(`  Kept: references/${filename}`));
+        }
+    }
+    console.log();
+    console.log(ui.accent("References are up to date."));
+    console.log();
+}

package/dist/commands/sync.js

@@ -6,6 +6,7 @@ import { loadConfig } from "../utils/config.js";
 import { loadDecisions } from "../utils/decisions.js";
 import { loadComponents } from "../utils/components.js";
 import { loadRefinements } from "../utils/refinements.js";
+import { getAiAvailability } from "../utils/aiAvailability.js";
 import { ui } from "../ui/index.js";
 /**
  * `whale sync` regenerates everything an AI agent reads, from the
@@ -40,4 +41,11 @@ export async function syncCommand(targetArg) {
     console.log();
     console.log(ui.accent("AI agents will now see the latest project state."));
     console.log(ui.muted(`Targets configured: ${(config.aiTargets ?? []).join(", ") || "(none)"}`));
+    if (config.enrichWithAi) {
+        const ai = await getAiAvailability(target);
+        if (ai.available) {
+            console.log();
+            console.log(ui.note("Scribe enrichment enabled (config.enrichWithAi=true). Run `whale selene suggest` to enrich wiki prose."));
+        }
+    }
 }

package/dist/generators/wikiGenerator.js

@@ -5,6 +5,12 @@ import { loadRefinements } from "../utils/refinements.js";
 import { loadDecisions } from "../utils/decisions.js";
 import { loadComponents } from "../utils/components.js";
 import { validateCss } from "../validators/cssValidator.js";
+import { renderFoundations } from "../templates/foundations.js";
+import { renderConventions } from "../templates/conventions.js";
+import { renderDecisions } from "../templates/decisions.js";
+import { renderComponents } from "../templates/components.js";
+import { renderProject, renderWikiReadme, renderWorkflows } from "../templates/project.js";
+import { renderRootIndex } from "../templates/claude.js";
 export async function generateWiki(target) {
     const config = await loadConfig(target);
     const refinements = await loadRefinements(target);
@@ -15,11 +21,10 @@ export async function generateWiki(target) {
     const warnings = issues.filter((i) => i.severity === "warning").length;
     const wikiDir = path.join(target, "llm-wiki");
     await fs.ensureDir(wikiDir);
-    // ---- llm-wiki/ themed files ------------------------------------------------
     const themedFiles = {
         "README.md": renderWikiReadme(config),
         "PROJECT.md": renderProject(config, errors, warnings, refinements.length, decisions.length),
-        "FOUNDATIONS.md": renderFoundations(config),
+        "FOUNDATIONS.md": renderFoundations(config, decisions),
         "CONVENTIONS.md": renderConventions(config, refinements),
         "DECISIONS.md": renderDecisions(decisions),
         "COMPONENTS.md": renderComponents(components),
@@ -31,7 +36,6 @@ export async function generateWiki(target) {
         await fs.writeFile(filePath, content);
         wikiFiles.push(filePath);
     }
-    // ---- root-level AI entry points -------------------------------------------
     const rootIndex = renderRootIndex(config, {
         errors,
         warnings,
@@ -41,14 +45,12 @@ export async function generateWiki(target) {
     });
     const rootFiles = [];
     const targets = config.aiTargets ?? ["claude"];
-    // CLAUDE.md is always written (default reader). Other agent files mirror it.
     const filenamesByTarget = {
         claude: "CLAUDE.md",
-        codex: "AGENTS.md", // OpenAI Codex / agents.md convention
+        codex: "AGENTS.md",
         cursor: ".cursorrules",
         copilot: ".github/copilot-instructions.md"
     };
-    // Always emit CLAUDE.md as the canonical file, even if claude isn't listed.
     const written = new Set();
     const emit = async (filename) => {
         if (written.has(filename))
@@ -65,301 +67,3 @@ export async function generateWiki(target) {
     }
     return { rootFiles, wikiFiles };
 }
-// ----------------------------------------------------------------------------
-// Renderers
-// ----------------------------------------------------------------------------
-function renderRootIndex(config, stats) {
-    const name = config.projectName ?? "this project";
-    const grid = config.foundations?.grid ?? 8;
-    const ctrl = config.foundations?.radius?.control ?? 2;
-    const cont = config.foundations?.radius?.container ?? 4;
-    const stack = config.stack ?? "css";
-    const packs = (config.packs ?? []).join(", ") || "(none)";
-    return `# AI Agent Context — ${name}
-
-> This file is auto-generated by [Whale Igniter](https://github.com/whale-igniter).
-> Do not edit by hand. Run \`whale sync\` after changes to regenerate.
-
-You are working in a project managed by Whale Igniter. Whale maintains
-machine-readable operational context so AI agents understand the design
-system, conventions and decisions without re-explaining them every session.
-
-## Quick facts
-
-- **Project type:** ${config.projectType ?? "unspecified"}
-- **Stack:** ${stack}
-- **Grid:** ${grid}px (all spacing must be a multiple)
-- **Border radius:** ${ctrl}px (controls), ${cont}px (containers)
-- **Active packs:** ${packs}
-- **Validation status:** ${stats.errors} error(s), ${stats.warnings} warning(s)
-- **Decisions logged:** ${stats.decisionCount}
-- **Refinements active:** ${stats.refinementCount}
-- **Components catalogued:** ${stats.componentCount}
-
-## How to read this project
-
-Whale stores structured context in two locations:
-
-1. **\`intelligence/\`** — source of truth (JSON). Read these when you need precise data:
-   - \`intelligence/refinements.json\` — validator overrides the team has accepted
-   - \`intelligence/decisions.json\` — architectural and product decisions
-   - \`intelligence/components.json\` — catalog of components in the project
-
-2. **\`llm-wiki/\`** — human + AI readable markdown rendered from the JSON:
-   - \`llm-wiki/FOUNDATIONS.md\` — design tokens and grid rules
-   - \`llm-wiki/CONVENTIONS.md\` — coding and design conventions
-   - \`llm-wiki/DECISIONS.md\` — decision log in narrative form
-   - \`llm-wiki/COMPONENTS.md\` — component catalog
-   - \`llm-wiki/WORKFLOWS.md\` — how the team uses Whale day to day
-
-If a question can be answered from \`intelligence/*.json\`, prefer that file —
-it's the source. The wiki is a rendered view.
-
-## Rules you must follow
-
-1. **Spacing.** Every padding, margin and gap must be a multiple of \`${grid}px\`.
-2. **Radius.** Buttons, inputs, selects use \`${ctrl}px\`. Cards, modals, sheets use \`${cont}px\`.
-3. **Color.** Prefer semantic tokens over raw hex. If you must add a hex,
-   record a refinement explaining why.
-4. **Focus.** Every interactive element needs a visible \`:focus-visible\` state.
-5. **Decisions.** When you make a non-obvious choice, propose recording it via
-   \`whale decision\` so future sessions inherit the reasoning.
-6. **Refinements.** Honor entries in \`intelligence/refinements.json\` —
-   they encode intentional exceptions the team approved.
-
-## When the user asks you to add a component
-
-Before writing code:
-- Check \`intelligence/components.json\` to see if it already exists.
-- Check \`llm-wiki/FOUNDATIONS.md\` for the tokens to use.
-- After creating it, suggest the user run \`whale component add <name>\`
-  so future agents know it exists.
-
-## Commands available
-
-- \`whale validate\` — runs the validators, exits non-zero on errors
-- \`whale refine "<note>"\` — record a validator override
-- \`whale decision\` — record an architectural decision (interactive)
-- \`whale component add <name>\` — register a component
-- \`whale sync\` — regenerate this file and the wiki
-- \`whale docs\` — generate human-facing reports
-
----
-_Last sync: ${new Date().toISOString()}_
-`;
-}
-function renderWikiReadme(config) {
-    return `# LLM Wiki
-
-This directory is generated by Whale Igniter. It contains a human-and-AI
-readable view of the project's operational context.
-
-**Do not edit these files directly** — they are regenerated from
-\`intelligence/*.json\` and \`whale.config.json\` whenever you run
-\`whale sync\`.
-
-## Files
-
-- \`PROJECT.md\` — high-level project facts
-- \`FOUNDATIONS.md\` — grid, radius, tokens
-- \`CONVENTIONS.md\` — active conventions and refinements
-- \`DECISIONS.md\` — decision log
-- \`COMPONENTS.md\` — component catalog
-- \`WORKFLOWS.md\` — recommended usage flow
-
-## For AI agents
-
-The canonical entry point for AI agents is \`/CLAUDE.md\` at the project root.
-This wiki is the detailed view — start with the root file, drill in here.
-
-_Generated by Whale Igniter v0.7._
-`;
-}
-function renderProject(config, errors, warnings, refinementCount, decisionCount) {
-    return `# Project Context
-
-- **Project name:** ${config.projectName ?? "(unset)"}
-- **Project type:** ${config.projectType ?? "unspecified"}
-- **Stack:** ${config.stack ?? "css"}
-- **AI targets:** ${(config.aiTargets ?? []).join(", ") || "(none)"}
-- **Active packs:** ${(config.packs ?? []).join(", ") || "(none)"}
-- **Ignited:** ${config.ignited?.at ?? "(not yet)"} (${config.ignited?.mode ?? "—"})
-
-## Current status
-
-- Validation errors: ${errors}
-- Validation warnings: ${warnings}
-- Decisions logged: ${decisionCount}
-- Active refinements: ${refinementCount}
-
-_Generated by Whale Igniter._
-`;
-}
-function renderFoundations(config) {
-    const grid = config.foundations?.grid ?? 8;
-    const ctrl = config.foundations?.radius?.control ?? 2;
-    const cont = config.foundations?.radius?.container ?? 4;
-    return `# Foundations
-
-The invariants of this project. All UI must conform unless explicitly refined.
-
-## Spacing
-
-Grid unit: **${grid}px**.
-
-Every padding, margin and gap should be a multiple of ${grid}px. The allowed
-scale is:
-
-\`\`\`
-${[1, 2, 3, 4, 5, 6, 8, 10, 12].map((n) => `${n * grid}px`).join("  ")}
-\`\`\`
-
-## Radius
-
-| Use            | Value   |
-| -------------- | ------- |
-| Controls       | ${ctrl}px |
-| Containers     | ${cont}px |
-
-Controls = buttons, inputs, selects, toggles. Containers = cards, modals,
-sheets, popovers.
-
-## Tone & accent
-
-- Tone: ${config.branding?.tone ?? "(unset)"}
-- Accent: ${config.branding?.accent ?? "(unset)"}
-
-_Generated by Whale Igniter._
-`;
-}
-function renderConventions(config, refinements) {
-    const lines = [
-        "# Conventions",
-        "",
-        "## Rules",
-        "",
-        `- Spacing is a multiple of ${config.foundations?.grid ?? 8}px.`,
-        "- Controls and containers use distinct radius values (see FOUNDATIONS.md).",
-        "- Every interactive element has a visible \`:focus-visible\` state.",
-        "- Prefer semantic tokens over raw color values.",
-        "",
-        "## Active refinements",
-        ""
-    ];
-    if (refinements.length === 0) {
-        lines.push("_No refinements recorded yet._");
-    }
-    else {
-        lines.push("These are exceptions the team has explicitly approved. The validator", "suppresses matching issues.", "");
-        for (const r of refinements) {
-            const scopeParts = [];
-            if (r.scope?.issueType)
-                scopeParts.push(`type=\`${r.scope.issueType}\``);
-            if (r.scope?.selector)
-                scopeParts.push(`selector=\`${r.scope.selector}\``);
-            if (r.scope?.file)
-                scopeParts.push(`file=\`${r.scope.file}\``);
-            const scope = scopeParts.length ? ` _(${scopeParts.join(", ")})_` : "";
-            lines.push(`- **${r.timestamp.slice(0, 10)}** — ${r.note}${scope}`);
-        }
-    }
-    lines.push("", "_Generated by Whale Igniter._");
-    return lines.join("\n");
-}
-function renderDecisions(decisions) {
-    const lines = [
-        "# Decision Log",
-        "",
-        "Architectural, product and tooling decisions, in reverse chronological order.",
-        ""
-    ];
-    if (decisions.length === 0) {
-        lines.push("_No decisions logged yet. Use `whale decision` to record one._");
-    }
-    else {
-        const sorted = [...decisions].sort((a, b) => b.timestamp.localeCompare(a.timestamp));
-        for (const d of sorted) {
-            lines.push(`## ${d.title}`);
-            lines.push("");
-            lines.push(`- **Date:** ${d.timestamp.slice(0, 10)}`);
-            lines.push(`- **Category:** ${d.category}`);
-            lines.push(`- **Status:** ${d.status}`);
-            if (d.context) {
-                lines.push("", "**Context**", "", d.context);
-            }
-            lines.push("", "**Decision**", "", d.decision);
-            if (d.consequences) {
-                lines.push("", "**Consequences**", "", d.consequences);
-            }
-            lines.push("", "---", "");
-        }
-    }
-    lines.push("_Generated by Whale Igniter._");
-    return lines.join("\n");
-}
-function renderComponents(components) {
-    const lines = ["# Component Catalog", ""];
-    if (components.length === 0) {
-        lines.push("_No components catalogued yet. Use `whale component add <name>` to register one._");
-    }
-    else {
-        const sorted = [...components].sort((a, b) => a.name.localeCompare(b.name));
-        for (const c of sorted) {
-            lines.push(`## ${c.name}`);
-            lines.push("");
-            if (c.description)
-                lines.push(c.description, "");
-            const meta = [];
-            if (c.category)
-                meta.push(`Category: ${c.category}`);
-            if (c.variants?.length)
-                meta.push(`Variants: ${c.variants.join(", ")}`);
-            if (c.states?.length)
-                meta.push(`States: ${c.states.join(", ")}`);
-            if (meta.length)
-                lines.push(meta.map((m) => `- ${m}`).join("\n"), "");
-            if (c.files?.length) {
-                lines.push("**Files:**");
-                for (const f of c.files)
-                    lines.push(`- \`${f}\``);
-                lines.push("");
-            }
-            lines.push("---", "");
-        }
-    }
-    lines.push("_Generated by Whale Igniter._");
-    return lines.join("\n");
-}
-function renderWorkflows(_config) {
-    return `# Workflows
-
-## Daily flow
-
-\`\`\`
-whale validate                  # see what's drifting
-whale refine "<note>"           # accept an intentional exception
-whale decision                  # record a non-obvious choice
-whale component add <name>      # register a new component
-whale sync                      # regenerate AI context
-\`\`\`
-
-## When to use what
-
-| You want to...                                | Command                       |
-| --------------------------------------------- | ----------------------------- |
-| See what's broken                             | \`whale validate\`            |
-| Accept an exception ("we use radius 0 here")  | \`whale refine "..."\`        |
-| Log an architecture/product choice            | \`whale decision\`            |
-| Track a new component                         | \`whale component add\`       |
-| Refresh AI context after manual edits         | \`whale sync\`                |
-| Produce human reports                         | \`whale docs\`                |
-
-## Recommended cadence
-
-- **Per change:** run \`validate\` before commit.
-- **Per significant choice:** record a \`decision\` or \`refinement\`.
-- **Per session:** run \`sync\` before handing off to an AI agent.
-
-_Generated by Whale Igniter._
-`;
-}

package/dist/index.js

@@ -12,13 +12,15 @@ import { decisionCommand } from "./commands/decision.js";
 import { componentAddCommand, componentListCommand } from "./commands/component.js";
 import { adoptCommand } from "./commands/adopt.js";
 import { adoptReviewCommand, adoptStatusCommand } from "./commands/adoptReview.js";
-import { insightsCommand } from "./commands/insights.js";
+import { insightsCommand, insightsDriftReviewCommand } from "./commands/insights.js";
 import { createComponentCommand } from "./commands/createComponent.js";
 import { seleneDescribeCommand, seleneAuditCommand, seleneSuggestCommand, seleneApplyCommand, seleneStatusCommand, seleneCacheClearCommand } from "./commands/selene.js";
 import { mcpServeCommand, mcpConfigCommand } from "./commands/mcp.js";
 import { watchCommand } from "./commands/watch.js";
 import { rememberCommand, checkCommand, improveCommand, explainCommand } from "./commands/friendly.js";
 import { teamAddCommand, teamListCommand } from "./commands/team.js";
+import { referencesListCommand, referencesAddCommand, referencesUpdateCommand } from "./commands/references.js";
+import { changesCommand } from "./commands/changes.js";
 import { PACKAGE_VERSION } from "./version.js";
 const program = new Command();
 program
@@ -142,7 +144,7 @@ cache
     .command("clear")
     .description("Delete all cached Selene responses.")
     .action(() => seleneCacheClearCommand());
-program
+const insightsCmd = program
     .command("insights [target]")
     .description("Run local analyzers over the intelligence stores and surface accountable recommendations.")
     .option("--json", "Emit insights as JSON (for scripting / CI)")
@@ -150,6 +152,12 @@ program
     .option("--min-severity <level>", "Show only insights at this severity or higher (info | warning | critical)")
     .option("--skip-scan", "Skip the source scan (faster, but disables orphan/drift insights)")
     .action((target, opts) => insightsCommand(target, opts));
+insightsCmd
+    .command("drift <category>")
+    .description("Show or review drift in spacing | color | radii.")
+    .option("--review", "Enter interactive review loop: accept as refinement, flag for refactor, or skip")
+    .option("--target <path>", "Workspace path (default: cwd)")
+    .action((category, opts) => insightsDriftReviewCommand(category, opts));
 const create = program
     .command("create")
     .description("Generate new code that respects the project's foundations.");
@@ -234,6 +242,24 @@ mcp
     .option("--client <name>", "claude-code | cursor | zed | raw", "claude-code")
     .option("--project <path>", "Workspace path (default: cwd)")
     .action((opts) => mcpConfigCommand(opts));
+const references = program
+    .command("references")
+    .description("Manage the UI component reference library for this project.");
+references
+    .command("list [target]")
+    .description("Show available reference categories and which are present in this project.")
+    .action((target) => referencesListCommand(target));
+references
+    .command("add [category]")
+    .description("Copy a reference category from the Whale library into references/<category>.md.")
+    .option("--all", "Copy all categories (INDEX + all six category files)")
+    .option("--target <path>", "Workspace path (default: cwd)")
+    .action((category, opts) => referencesAddCommand(category, opts));
+references
+    .command("update [target]")
+    .description("Re-copy references from Whale, prompting to keep/overwrite locally modified files.")
+    .action((target) => referencesUpdateCommand(target));
+references.action((opts) => referencesListCommand(opts.target));
 program
     .command("watch [target]")
     .description("Watch foundations and intelligence stores; regenerate CLAUDE.md and wiki on change.")
@@ -241,4 +267,9 @@ program
     .option("--verbose", "Print every change event and regeneration detail")
     .option("--once", "Run a single regeneration and exit (useful for CI)")
     .action((target, opts) => watchCommand(target, opts));
+program
+    .command("changes [target]")
+    .description("Show what changed in intelligence stores since a git ref.")
+    .option("--since <ref>", "Git ref to compare against (default: HEAD~1)", "HEAD~1")
+    .action((target, opts) => changesCommand({ since: opts.since, target }));
 program.parse();

package/dist/mcp/server.js

@@ -381,6 +381,35 @@ export function buildMcpServer() {
         return ok(`Regenerated ${rootFiles.length} root file(s) and ${wikiFiles.length} wiki file(s).\n` +
             `Root: ${rootFiles.map((f) => path.relative(ws, f)).join(", ")}`);
     });
+    server.registerTool("whale_ui_reference", {
+        title: "Read a UI references category file",
+        description: "Returns the contents of a curated UI component reference file from this " +
+            "project's references/ directory. These files document the quality bar and " +
+            "best implementations for each component category. Call this BEFORE building " +
+            "any UI component — consult the relevant category to understand what states " +
+            "and behaviors are required. Use 'INDEX' as the category to get the index file.",
+        inputSchema: {
+            category: z
+                .string()
+                .describe("Category slug: forms | navigation | feedback | surface | layout | data-display | INDEX"),
+            target: z.string().optional().describe("Workspace path. Defaults to WHALE_PROJECT or cwd.")
+        }
+    }, async ({ category, target }) => {
+        const ws = resolveWorkspace(target);
+        const filename = category.toUpperCase() === "INDEX" ? "INDEX.md" : `${category}.md`;
+        const referencePath = path.join(ws, "references", filename);
+        if (!(await fs.pathExists(referencePath))) {
+            const configPath = path.join(ws, "whale.config.json");
+            const hasProject = await fs.pathExists(configPath);
+            if (!hasProject) {
+                return err(`No whale.config.json found at ${ws}. Run \`whale ignite\` or \`whale adopt\` first.`);
+            }
+            return err(`references/${filename} not found in this project. ` +
+                `Run \`whale references add ${category}\` to copy it from the Whale library.`);
+        }
+        const content = await fs.readFile(referencePath, "utf-8");
+        return ok(content);
+    });
     return server;
 }
 /**