whale-igniter 1.4.0 → 1.5.2

package/dist/commands/decision.js

@@ -86,7 +86,7 @@ export async function decisionCommand(options = {}) {
         consequences: consequences?.trim() || undefined
     });
     console.log();
-    console.log(ui.ok(`Decision recorded ${ui.muted("— " + created.id.slice(0, 8))}`));
+    console.log(ui.ok(`Decision recorded ${ui.muted("— " + created.id)}`));
     console.log(`  ${ui.accent(created.title)}`);
     console.log(`  ${ui.kv("category", created.category, { keyWidth: 8 })}`);
     if (options.sync !== false) {

package/dist/commands/forge.js

@@ -0,0 +1,159 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { resolveTarget } from "../utils/paths.js";
+import { loadConfig } from "../utils/config.js";
+import { loadComponents } from "../utils/components.js";
+import { ui } from "../ui/index.js";
+export async function forgeCommand(componentName, options = {}) {
+    const target = resolveTarget();
+    const config = await loadConfig(target);
+    const components = await loadComponents(target);
+    const component = components.find((c) => c.name === componentName);
+    if (!component) {
+        console.log(ui.fail(`Component "${componentName}" not found in intelligence/components.json.`));
+        console.log(ui.muted(`  Run \`whale create component ${componentName}\` first, or \`whale component add ${componentName}\`.`));
+        process.exitCode = 1;
+        return;
+    }
+    const grid = config.foundations?.grid ?? 8;
+    const controlRadius = config.foundations?.radius?.control ?? 2;
+    const containerRadius = config.foundations?.radius?.container ?? 4;
+    const accent = config.branding?.accent ?? "blue";
+    const isControl = isControlCategory(component.category);
+    const radius = isControl ? controlRadius : containerRadius;
+    const px = grid * 2;
+    const py = grid;
+    const outDir = options.out ?? "docs/forge";
+    const fileRel = path.join(outDir, `${componentName}.md`).replace(/\\/g, "/");
+    const fileAbs = path.join(target, fileRel);
+    if (await fs.pathExists(fileAbs) && !options.force) {
+        console.log(ui.fail(`${ui.path(fileRel)} already exists. Use --force to overwrite.`));
+        process.exitCode = 1;
+        return;
+    }
+    await fs.ensureDir(path.dirname(fileAbs));
+    const content = renderForgeContract({
+        component,
+        grid,
+        radius,
+        px,
+        py,
+        accent,
+        isControl,
+    });
+    await fs.writeFile(fileAbs, content, "utf8");
+    console.log(ui.ok(`Forge contract → ${ui.path(fileRel)}`));
+    console.log(`  ${ui.kv("component", componentName, { keyWidth: 10 })}`);
+    console.log(`  ${ui.kv("template", isControl ? "control" : "container", { keyWidth: 10 })}`);
+    console.log(`  ${ui.kv("grid", `${grid}px`, { keyWidth: 10 })}`);
+    console.log(`  ${ui.kv("radius", `${radius}px`, { keyWidth: 10 })}`);
+}
+// ---------------------------------------------------------------------------
+// Renderer
+// ---------------------------------------------------------------------------
+function renderForgeContract(args) {
+    const { component, grid, radius, px, py, accent, isControl } = args;
+    const { name, category, variants = [], states = [], files = [], tokens = [] } = component;
+    const paddingNote = isControl
+        ? `${px}px horizontal / ${py}px vertical (${grid}px grid × 2 / × 1)`
+        : `${py * 3}px all sides (${grid}px grid × 3)`;
+    const derivedTokens = deriveTokens(variants, accent, tokens);
+    const checklist = buildChecklist(isControl, variants, states);
+    const lines = [
+        `# Forge — ${name}`,
+        "",
+        `> Auto-generated implementation contract. Keep in sync with \`intelligence/components.json\`.`,
+        "",
+        "## Component spec",
+        "",
+        `| Property  | Value |`,
+        `|-----------|-------|`,
+        `| Template  | ${isControl ? "control" : "container"} |`,
+        `| Category  | ${category ?? "unspecified"} |`,
+        `| Grid      | ${grid}px |`,
+        `| Radius    | ${radius}px |`,
+        `| Padding   | ${paddingNote} |`,
+    ];
+    if (variants.length > 0) {
+        lines.push(`| Variants  | ${variants.join(", ")} |`);
+    }
+    if (states.length > 0) {
+        lines.push(`| States    | ${states.join(", ")} |`);
+    }
+    lines.push("", "## Design tokens", "");
+    if (derivedTokens.length > 0) {
+        for (const t of derivedTokens) {
+            lines.push(`- \`${t.token}\` — ${t.usage}`);
+        }
+    }
+    else {
+        lines.push("- No tokens registered. Run `whale selene describe` to infer them.");
+    }
+    lines.push("", "## Implementation checklist", "");
+    for (const item of checklist) {
+        lines.push(`- [ ] ${item}`);
+    }
+    if (files.length > 0) {
+        lines.push("", "## Files", "");
+        for (const f of files) {
+            lines.push(`- \`${f}\``);
+        }
+    }
+    lines.push("", "---", `_Generated by Whale Igniter · \`whale forge ${name}\`_`, "");
+    return lines.join("\n");
+}
+function deriveTokens(variants, accent, existing) {
+    if (existing.length > 0) {
+        return existing.map((t) => ({ token: t, usage: "registered token" }));
+    }
+    const result = [];
+    for (const v of variants) {
+        switch (v) {
+            case "primary":
+                result.push({ token: `--color-${accent}-600`, usage: "primary background" });
+                result.push({ token: `--color-${accent}-700`, usage: "primary hover" });
+                break;
+            case "secondary":
+                result.push({ token: `--color-gray-100`, usage: "secondary background" });
+                result.push({ token: `--color-gray-200`, usage: "secondary hover" });
+                break;
+            case "ghost":
+                result.push({ token: `--color-gray-100`, usage: "ghost hover background" });
+                break;
+            case "destructive":
+                result.push({ token: `--color-red-600`, usage: "destructive background" });
+                break;
+        }
+    }
+    return result;
+}
+function buildChecklist(isControl, variants, states) {
+    const items = [];
+    if (isControl) {
+        items.push("forwardRef implemented with correct HTMLElement type");
+        items.push("baseClasses use grid-aligned padding");
+        items.push(`radius matches control radius from whale.config.json`);
+    }
+    else {
+        items.push("Container uses grid-aligned padding (grid × 3)");
+        items.push("radius matches container radius from whale.config.json");
+    }
+    if (states.includes("focus") || states.includes("focus-visible")) {
+        items.push(":focus-visible ring is visible at 2px offset");
+    }
+    if (states.includes("disabled")) {
+        items.push("disabled state reduces opacity and removes pointer-events");
+    }
+    if (states.includes("hover")) {
+        items.push("hover state uses a darker/lighter token variant, not raw hex");
+    }
+    for (const v of variants) {
+        items.push(`Variant "${v}" visually tested at all states`);
+    }
+    items.push("Color values come from tokens (var(--color-*)), not raw hex");
+    items.push("Component registered in intelligence/components.json");
+    return items;
+}
+function isControlCategory(category) {
+    return ["form", "navigation"].includes(category ?? "");
+}

package/dist/commands/init.js

@@ -27,8 +27,6 @@ async function ensureIntelligenceFiles(target) {
     const intelligenceDir = path.join(target, "intelligence");
     await fs.ensureDir(intelligenceDir);
     const seeds = {
-        "refinements.json": [],
-        "decisions.json": [],
         "components.json": []
     };
     for (const [name, content] of Object.entries(seeds)) {
@@ -37,6 +35,9 @@ async function ensureIntelligenceFiles(target) {
             await fs.writeJson(file, content, { spaces: 2 });
         }
     }
+    // Decisions and refinements are stored as individual Markdown files.
+    await fs.ensureDir(path.join(intelligenceDir, "decisions"));
+    await fs.ensureDir(path.join(intelligenceDir, "refinements"));
 }
 export async function initCommand(projectName = "whale-project", options = {}) {
     const target = path.resolve(process.cwd(), projectName);

package/dist/commands/insights.js

@@ -168,8 +168,6 @@ export async function insightsDriftReviewCommand(category, opts) {
             break;
         if (action === "refine") {
             await appendRefinement(target, {
-                id: randomUUID(),
-                timestamp: new Date().toISOString(),
                 note: ins.title,
                 scope: { issueType: cat }
             });

package/dist/commands/refine.js

@@ -1,4 +1,3 @@
-import { randomUUID } from "node:crypto";
 import { resolveTarget } from "../utils/paths.js";
 import { appendRefinement, inferScope } from "../utils/refinements.js";
 import { generateWiki } from "../generators/wikiGenerator.js";
@@ -6,13 +5,7 @@ import { ui } from "../ui/index.js";
 export async function refineCommand(note, options = {}) {
     const target = resolveTarget();
     const scope = inferScope(note);
-    const refinement = {
-        id: randomUUID(),
-        timestamp: new Date().toISOString(),
-        note,
-        scope
-    };
-    await appendRefinement(target, refinement);
+    await appendRefinement(target, { note, scope });
     console.log(ui.ok("Refinement recorded"));
     if (scope) {
         const parts = [];

package/dist/commands/scribe.js

@@ -0,0 +1,189 @@
+import path from "node:path";
+import fs from "fs-extra";
+import ora from "ora";
+import { resolveTarget } from "../utils/paths.js";
+import { loadConfig } from "../utils/config.js";
+import { loadComponents } from "../utils/components.js";
+import { loadDecisions } from "../utils/decisions.js";
+import { loadRefinements } from "../utils/refinements.js";
+import { resolveProvider } from "../selene/providers.js";
+import { callProvider } from "../selene/apiClient.js";
+import { ui } from "../ui/index.js";
+// ---------------------------------------------------------------------------
+// whale scribe readme <ComponentName>
+// ---------------------------------------------------------------------------
+export async function scribeReadmeCommand(componentName, options = {}) {
+    const target = resolveTarget();
+    const config = await loadConfig(target);
+    const components = await loadComponents(target);
+    const component = components.find((c) => c.name === componentName);
+    if (!component) {
+        console.log(ui.fail(`Component "${componentName}" not found in intelligence/components.json.`));
+        console.log(ui.muted(`  Run \`whale create component ${componentName}\` first.`));
+        process.exitCode = 1;
+        return;
+    }
+    const outDir = options.out ?? "docs/scribe";
+    const fileRel = path.join(outDir, `${componentName}.md`).replace(/\\/g, "/");
+    const fileAbs = path.join(target, fileRel);
+    if (await fs.pathExists(fileAbs) && !options.force) {
+        console.log(ui.fail(`${ui.path(fileRel)} already exists. Use --force to overwrite.`));
+        process.exitCode = 1;
+        return;
+    }
+    const grid = config.foundations?.grid ?? 8;
+    const controlRadius = config.foundations?.radius?.control ?? 2;
+    const containerRadius = config.foundations?.radius?.container ?? 4;
+    const accent = config.branding?.accent ?? "blue";
+    const projectName = config.projectName ?? "this project";
+    const prompt = buildReadmePrompt({
+        componentName,
+        component,
+        grid,
+        controlRadius,
+        containerRadius,
+        accent,
+        projectName,
+    });
+    if (options.promptOnly) {
+        console.log(prompt);
+        return;
+    }
+    const resolved = resolveProvider(config);
+    if (!resolved) {
+        console.log(ui.warn("No API key found — printing prompt instead."));
+        console.log(ui.muted("  Set ANTHROPIC_API_KEY or OPENAI_API_KEY to use AI generation."));
+        console.log("\n" + prompt);
+        return;
+    }
+    const spinner = ora(`Scribe · generating README for ${componentName}`).start();
+    const result = await callProvider(resolved, { prompt, maxTokens: 1200, temperature: 0.4 });
+    if (!result.ok) {
+        spinner.fail(`API error: ${result.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    spinner.succeed(`README generated`);
+    const content = result.text.trim();
+    await fs.ensureDir(path.dirname(fileAbs));
+    await fs.writeFile(fileAbs, content + "\n", "utf8");
+    console.log(ui.ok(`Scribe → ${ui.path(fileRel)}`));
+    console.log(ui.muted(`  provider: ${resolved.provider} · ${resolved.model}`));
+}
+// ---------------------------------------------------------------------------
+// whale scribe overview
+// ---------------------------------------------------------------------------
+export async function scribeOverviewCommand(options = {}) {
+    const target = resolveTarget();
+    const config = await loadConfig(target);
+    const components = await loadComponents(target);
+    const decisions = await loadDecisions(target);
+    const refinements = await loadRefinements(target);
+    const outDir = options.out ?? "docs/scribe";
+    const fileRel = path.join(outDir, "overview.md").replace(/\\/g, "/");
+    const fileAbs = path.join(target, fileRel);
+    if (await fs.pathExists(fileAbs) && !options.force) {
+        console.log(ui.fail(`${ui.path(fileRel)} already exists. Use --force to overwrite.`));
+        process.exitCode = 1;
+        return;
+    }
+    const prompt = buildOverviewPrompt({ config, components, decisions, refinements });
+    if (options.promptOnly) {
+        console.log(prompt);
+        return;
+    }
+    const resolved = resolveProvider(config);
+    if (!resolved) {
+        console.log(ui.warn("No API key found — printing prompt instead."));
+        console.log(ui.muted("  Set ANTHROPIC_API_KEY or OPENAI_API_KEY to use AI generation."));
+        console.log("\n" + prompt);
+        return;
+    }
+    const spinner = ora("Scribe · generating project overview").start();
+    const result = await callProvider(resolved, { prompt, maxTokens: 1600, temperature: 0.4 });
+    if (!result.ok) {
+        spinner.fail(`API error: ${result.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    spinner.succeed("Overview generated");
+    const content = result.text.trim();
+    await fs.ensureDir(path.dirname(fileAbs));
+    await fs.writeFile(fileAbs, content + "\n", "utf8");
+    console.log(ui.ok(`Scribe → ${ui.path(fileRel)}`));
+    console.log(ui.muted(`  provider: ${resolved.provider} · ${resolved.model}`));
+}
+// ---------------------------------------------------------------------------
+// Prompt builders
+// ---------------------------------------------------------------------------
+function buildReadmePrompt(args) {
+    const { componentName, component, grid, controlRadius, containerRadius, accent, projectName } = args;
+    const { category, description, variants = [], states = [], files = [], tokens = [] } = component;
+    return [
+        `# Scribe task — README for component: ${componentName}`,
+        "",
+        "You are a technical writer generating a component README for a design system.",
+        `The project is called "${projectName}" and uses an ${grid}px grid, ${controlRadius}px control radius, ${containerRadius}px container radius, and "${accent}" as accent color.`,
+        "",
+        "## Component metadata",
+        `- Name: ${componentName}`,
+        `- Category: ${category ?? "unspecified"}`,
+        `- Description: ${description ?? "(none)"}`,
+        `- Variants: ${variants.length > 0 ? variants.join(", ") : "none"}`,
+        `- States: ${states.length > 0 ? states.join(", ") : "none"}`,
+        `- Files: ${files.length > 0 ? files.join(", ") : "not specified"}`,
+        `- Tokens: ${tokens.length > 0 ? tokens.join(", ") : "not specified"}`,
+        "",
+        "## Task",
+        `Write a concise, developer-focused README.md for the ${componentName} component.`,
+        "Include:",
+        "1. A one-paragraph description of what it does and when to use it",
+        "2. A usage example (JSX/TSX code block)",
+        "3. A props table (name | type | default | description)",
+        "4. A section on accessibility (focus, ARIA if relevant)",
+        "5. A brief design notes section mentioning the grid and token constraints",
+        "",
+        "Write in plain Markdown. Be concise — target 150-250 lines max. No preamble or explanation.",
+    ].join("\n");
+}
+function buildOverviewPrompt(args) {
+    const { config, components, decisions, refinements } = args;
+    const componentList = components
+        .map((c) => `- ${c.name}${c.description ? `: ${c.description}` : ""}`)
+        .join("\n") || "  (none registered)";
+    const decisionList = decisions
+        .map((d) => `- ${d.title}: ${d.decision}`)
+        .join("\n") || "  (none)";
+    return [
+        "# Scribe task — project overview README",
+        "",
+        "You are a technical writer generating a project overview README.",
+        "",
+        "## Project config",
+        `- Name: ${config.projectName ?? "unnamed"}`,
+        `- Type: ${config.projectType ?? "unspecified"}`,
+        `- Stack: ${config.stack ?? "unspecified"}`,
+        `- Grid: ${config.foundations?.grid ?? 8}px`,
+        `- Control radius: ${config.foundations?.radius?.control ?? 2}px`,
+        `- Container radius: ${config.foundations?.radius?.container ?? 4}px`,
+        `- Accent: ${config.branding?.accent ?? "unspecified"}`,
+        `- Active packs: ${(config.packs ?? []).join(", ") || "none"}`,
+        "",
+        "## Registered components",
+        componentList,
+        "",
+        "## Architectural decisions",
+        decisionList,
+        `- Refinements recorded: ${refinements.length}`,
+        "",
+        "## Task",
+        "Write a project overview README.md that a new developer would read to understand:",
+        "1. What this project is and who it's for",
+        "2. The design system foundations (grid, radius, tokens)",
+        "3. The component catalog (what exists, categories)",
+        "4. Key architectural decisions",
+        "5. How to get started (whale commands to run)",
+        "",
+        "Write in plain Markdown. Be concise and direct. No preamble or explanation.",
+    ].join("\n");
+}

package/dist/commands/selene.js

@@ -14,7 +14,6 @@ import { copyToClipboard } from "../selene/clipboard.js";
 import { resolveProvider, describeProviderState } from "../selene/providers.js";
 import { callProvider, estimateTokens, estimateCostUsd } from "../selene/apiClient.js";
 import { readCache, writeCache, clearCache } from "../selene/cache.js";
-import { randomUUID } from "node:crypto";
 import { ui } from "../ui/index.js";
 const PENDING_DIR = ".whale/selene";
 // ---------------------------------------------------------------------------
@@ -421,8 +420,6 @@ async function applySuggest(target, raw, options) {
             }
             else if (s.kind === "refinement") {
                 await appendRefinement(target, {
-                    id: randomUUID(),
-                    timestamp: new Date().toISOString(),
                     note: s.proposed_text
                 });
                 console.log(ui.success("  ✓ Recorded as refinement."));

package/dist/commands/sync.js

@@ -10,10 +10,10 @@ import { getAiAvailability } from "../utils/aiAvailability.js";
 import { ui } from "../ui/index.js";
 /**
  * `whale sync` regenerates everything an AI agent reads, from the
- * intelligence JSON files (which are the source of truth).
+ * project configuration and intelligence stores (the source of truth).
  *
  * Run this:
- *   - after manually editing intelligence/*.json
+ *   - after manually editing whale.config.json or intelligence stores
  *   - before handing the project to an AI agent
  *   - in CI to ensure CLAUDE.md stays in sync
  */

package/dist/commands/watch.js

@@ -3,7 +3,7 @@
  *
  * Why this exists. Whale's value depends on CLAUDE.md being current.
  * Every write command (refine, decision, component add, adopt review) auto-syncs,
- * but humans also edit `intelligence/*.json` directly, change `whale.config.json`,
+ * but humans also edit `intelligence/` directly, change `whale.config.json`,
  * or commit catalog files from another tool. Without a watcher the gap between
  * "what's true" and "what the AI sees" silently widens. Watcher closes that gap.
  *

package/dist/index.js

@@ -15,6 +15,9 @@ import { adoptReviewCommand, adoptStatusCommand } from "./commands/adoptReview.j
 import { insightsCommand, insightsDriftReviewCommand } from "./commands/insights.js";
 import { createComponentCommand } from "./commands/createComponent.js";
 import { createLandingCommand } from "./commands/createLanding.js";
+import { forgeCommand } from "./commands/forge.js";
+import { scribeReadmeCommand, scribeOverviewCommand } from "./commands/scribe.js";
+import { atlasHealthCommand, atlasDecisionsCommand } from "./commands/atlas.js";
 import { themesListCommand } from "./commands/themes.js";
 import { updateTokensCommand } from "./commands/updateTokens.js";
 import { seleneDescribeCommand, seleneAuditCommand, seleneSuggestCommand, seleneApplyCommand, seleneStatusCommand, seleneCacheClearCommand } from "./commands/selene.js";
@@ -45,7 +48,7 @@ program
 });
 program
     .command("sync [target]")
-    .description("Regenerate CLAUDE.md and the LLM Wiki from intelligence/*.json.")
+    .description("Regenerate CLAUDE.md and the LLM Wiki from project intelligence.")
     .action(syncCommand);
 program
     .command("remember [target]")
@@ -178,13 +181,60 @@ create
 create
     .command("landing")
     .description("Generate a static HTML/CSS landing page using current foundations.")
-    .option("--sections <list>", "Comma-separated sections (hero,features,proof,contact)")
+    .option("--sections <list>", "Comma-separated sections (header,hero,features,proof,contact,footer)")
     .option("--out-dir <path>", "Output directory relative to project root (default: src)")
     .option("--force", "Overwrite generated files if they already exist")
     .option("--no-register", "Don't add generated sections to intelligence/components.json")
     .option("--no-sync", "Don't regenerate CLAUDE.md / wiki after creating")
     .option("--theme <name>", "Visual theme for the generated UI (see `whale themes list`)")
+    .option("--content <path>", "Read landing copy from a local JSON file")
+    .option("--sample-content", "Create an editable landing.json sample and use it")
+    .option("--brief", "Ask a short local brief and generate landing.json")
+    .option("--title <text>", "Override the hero headline")
+    .option("--eyebrow <text>", "Override the hero eyebrow")
+    .option("--tagline <text>", "Override the hero supporting copy")
+    .option("--cta <text>", "Override the primary CTA label")
+    .option("--cta-href <href>", "Override the primary CTA href")
     .action((opts) => createLandingCommand(opts));
+program
+    .command("forge <component>")
+    .description("Generate an implementation contract (Markdown) for a registered component.")
+    .option("--out <dir>", "Output directory relative to project root (default: docs/forge)")
+    .option("--force", "Overwrite the contract if it already exists")
+    .action((component, opts) => forgeCommand(component, opts));
+const atlas = program
+    .command("atlas")
+    .description("Project health and decision intelligence for PMs and tech leads.");
+atlas
+    .command("health")
+    .description("Generate an AI-powered project health report.")
+    .option("--out <dir>", "Output directory (default: docs/atlas)")
+    .option("--force", "Overwrite if already exists")
+    .option("--prompt-only", "Print the prompt without calling the API")
+    .action((opts) => atlasHealthCommand(opts));
+atlas
+    .command("decisions")
+    .description("List active architectural decisions, optionally filtered.")
+    .option("--category <name>", "Filter by category (architecture, design-system, product, tooling, convention)")
+    .option("--status <status>", "Filter by status (active, superseded, deprecated) — default: active")
+    .action((opts) => atlasDecisionsCommand(opts));
+const scribe = program
+    .command("scribe")
+    .description("AI-generated documentation for components and projects.");
+scribe
+    .command("readme <component>")
+    .description("Generate a developer README for a registered component using AI.")
+    .option("--out <dir>", "Output directory (default: docs/scribe)")
+    .option("--force", "Overwrite if already exists")
+    .option("--prompt-only", "Print the prompt without calling the API")
+    .action((component, opts) => scribeReadmeCommand(component, opts));
+scribe
+    .command("overview")
+    .description("Generate a project overview README using AI.")
+    .option("--out <dir>", "Output directory (default: docs/scribe)")
+    .option("--force", "Overwrite if already exists")
+    .option("--prompt-only", "Print the prompt without calling the API")
+    .action((opts) => scribeOverviewCommand(opts));
 const adopt = program
     .command("adopt [target]")
     .description("Scan an existing project and propose components, foundations and decisions.")

package/dist/mcp/server.js

@@ -38,7 +38,6 @@ import { collectReferencedFiles, normalizePath } from "../analyzer/imports.js";
 import { scanComponents } from "../scanner/componentScanner.js";
 import { aggregateTailwind } from "../scanner/tailwindScanner.js";
 import { validateCss } from "../validators/cssValidator.js";
-import { randomUUID } from "node:crypto";
 import { PACKAGE_VERSION } from "../version.js";
 function ok(text) {
     return { content: [{ type: "text", text }] };
@@ -354,12 +353,7 @@ export function buildMcpServer() {
         if (!check.ok)
             return err(check.reason);
         const scope = inferScope(note);
-        await appendRefinement(ws, {
-            id: randomUUID(),
-            timestamp: new Date().toISOString(),
-            note,
-            scope
-        });
+        await appendRefinement(ws, { note, scope });
         await generateWiki(ws);
         const scopeDesc = scope
             ? `Scope inferred: ${Object.entries(scope).map(([k, v]) => `${k}=${v}`).join(", ")}.`
@@ -368,8 +362,8 @@ export function buildMcpServer() {
     });
     server.registerTool("whale_sync", {
         title: "Regenerate CLAUDE.md and the LLM wiki",
-        description: "Regenerates the AI-readable context files from intelligence/*.json. Call " +
-            "this if you've manually edited the JSON stores and want the wiki to catch " +
+        description: "Regenerates the AI-readable context files from project intelligence. Call " +
+            "this if you've manually edited the source stores and want the wiki to catch " +
             "up. Whale auto-syncs on every recorded change, so manual calls are rarely needed.",
         inputSchema: { target: z.string().optional() }
     }, async ({ target }) => {

package/dist/selene/promptBuilder.js

@@ -42,7 +42,7 @@ function renderProjectContext(ctx) {
     lines.push(`- Control radius: ${c.foundations?.radius?.control ?? 4}px (buttons, inputs)`);
     lines.push(`- Container radius: ${c.foundations?.radius?.container ?? 8}px (cards, modals)`);
     // Active decisions — show titles only to keep tokens down. Full text
-    // is available in intelligence/decisions.json if the model needs it.
+    // is available in the linked intelligence/decisions Markdown files.
     const active = ctx.decisions.filter((d) => d.status === "active");
     if (active.length > 0) {
         lines.push("");
@@ -52,7 +52,7 @@ function renderProjectContext(ctx) {
             lines.push(`- [${d.category}] ${d.title}`);
         }
         if (active.length > recent.length) {
-            lines.push(`- … and ${active.length - recent.length} more in intelligence/decisions.json`);
+            lines.push(`- … and ${active.length - recent.length} more in llm-wiki/DECISIONS.md`);
         }
     }
     if (ctx.refinements.length > 0) {

package/dist/templates/claude.js

@@ -53,12 +53,12 @@ the design system, conventions and decisions without re-explaining them every se
 
 Whale stores structured context in two locations:
 
-1. **\`intelligence/\`** — source of truth (JSON). Prefer these for precise data:
-   - \`intelligence/refinements.json\` — approved validator overrides
-   - \`intelligence/decisions.json\` — architectural and product decisions
+1. **\`intelligence/\`** — source of truth. Prefer these for precise data:
+   - \`intelligence/refinements/\` — approved validator overrides as Markdown
+   - \`intelligence/decisions/\` — architectural and product decisions as ADRs
    - \`intelligence/components.json\` — component catalog
 
-2. **\`llm-wiki/\`** — human + AI readable markdown rendered from the JSON:
+2. **\`llm-wiki/\`** — compact human + AI readable markdown indexes:
    - \`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

package/dist/templates/conventions.js

@@ -28,7 +28,8 @@ export function renderConventions(config, refinements) {
             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}`);
+            const ref = r.sourcePath ? `[${r.id}](../${r.sourcePath})` : r.id;
+            lines.push(`- **${ref}** · ${r.timestamp.slice(0, 10)} — ${r.note}${scope}`);
         }
         lines.push("");
     }
@@ -36,7 +37,8 @@ export function renderConventions(config, refinements) {
         lines.push("## Open questions", "");
         lines.push("These notes do not yet have a scope — the validator cannot act on them.", "Review and convert to scoped refinements or decisions.", "");
         for (const r of scopeless) {
-            lines.push(`> ⚠️ Unresolved — **${r.timestamp.slice(0, 10)}**: ${r.note}`);
+            const ref = r.sourcePath ? `[${r.id}](../${r.sourcePath})` : r.id;
+            lines.push(`> ⚠️ Unresolved — **${ref}** · ${r.timestamp.slice(0, 10)}: ${r.note}`);
         }
         lines.push("");
     }