whale-igniter 1.4.0 → 1.5.2

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to Whale Igniter are documented here.
 
+## 1.5.2 - 2026-06-10
+
+### Changed
+
+- Decisions and refinements are now stored as individual Markdown files with frontmatter (`intelligence/decisions/ADR-XXXX-*.md`, `intelligence/refinements/REF-XXXX-*.md`) instead of accumulative JSON stores. IDs are sequential and human-readable. `loadDecisions`/`loadRefinements` keep dual-reading legacy JSON, so existing projects lose no data.
+- `llm-wiki/DECISIONS.md` is now a compact index table linking to each decision's source file, instead of dumping full bodies — reducing the context an AI agent consumes.
+- Updated `glob` to its supported current major and refreshed the transitive MCP dependency tree; production audit reports zero vulnerabilities.
+
+### Security
+
+- `whale changes` now invokes git via `execFileSync` with argument arrays instead of shell-interpolated strings, removing a command-injection vector through the `--since` flag.
+
+## 1.5.1 - 2026-06-03
+
+### Added
+
+- `whale forge <Component>` — generates a Markdown implementation contract for a registered component, including spec table, derived design tokens, and an implementation checklist. `whale create component` now suggests running forge as a next step.
+- `whale scribe readme <Component>` — uses the configured AI provider (Anthropic/OpenAI) to generate a developer-ready README for a registered component. Falls back to `--prompt-only` if no API key is set.
+- `whale scribe overview` — generates a full project overview README with foundations, component catalog, and architectural decisions via AI.
+- `whale atlas health` — generates an AI-powered project health report for PMs and tech leads: validation status, design system maturity, risk signals, and prioritized next steps.
+- `whale atlas decisions` — lists active architectural decisions grouped by category, filterable by `--category` and `--status`.
+- Block-style ASCII art title in the `whale ignite` splash screen (Larry 3D → Block font, hardcoded, no runtime dependency).
+- Default header and footer in generated landing pages, with nav links to Features, Proof, and Contact.
+- Hover microinteractions on buttons, cards, hero panel, and quote block, with `prefers-reduced-motion` support.
+- Mobile-responsive fixes: media queries corrected to `768px` literal (not CSS vars), header/footer stack on mobile, contact grid single-column at narrow viewports.
+
+## 1.5.0 - 2026-06-03
+
+### Added
+
+- Custom landing-page copy without AI via `whale create landing --content <path>`.
+- Hero override flags for generated landing pages: `--title`, `--eyebrow`, `--tagline`, `--cta`, and `--cta-href`.
+- Local onboarding helpers for landing generation: `--sample-content`, `--brief`, and role-based next-edit hints.
+- Validation for local landing content JSON, with clean CLI failures for malformed content.
+
 ## 1.4.0 - 2026-06-03
 
 ### Added

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/whale-igniter@1.3.0/brand/lockup.svg" alt="Whale Igniter" width="640">
+  <img src="https://cdn.jsdelivr.net/npm/whale-igniter@latest/brand/lockup.svg" alt="Whale Igniter" width="640">
 </p>
 
 <p align="center">
@@ -34,12 +34,12 @@ my-app/
 ├── CLAUDE.md                  # agent-readable project brief, auto-synced
 ├── intelligence/
 │   ├── components.json        # component catalog with variants and states
-│   ├── decisions.json         # architectural decisions and their rationale
-│   └── refinements.json       # approved exceptions — "this is intentional"
+│   ├── decisions/             # one Markdown ADR per decision
+│   └── refinements/           # one Markdown file per approved exception
 └── llm-wiki/                  # generated markdown, one file per concern
 ```
 
-`intelligence/*.json` is the source of truth. Markdown is generated from it. When you run `whale sync`, everything regenerates — CLAUDE.md, the wiki, the context your agent reads on the next conversation.
+`whale.config.json` and `intelligence/` are the source of truth. Decisions and refinements use individual Markdown files with frontmatter; component metadata remains structured JSON. When you run `whale sync`, everything regenerates — CLAUDE.md, the wiki, and the context your agent reads on the next conversation.
 
 The agent doesn't guess anymore. It reads.
 
@@ -100,6 +100,55 @@ whale create landing --theme atlas      # enterprise minimal, dense, neutral (de
 
 Each theme defines four tiers — Identity, Typography, Structural, Interaction — and emits a complete CSS custom property block. Swap themes; everything updates.
 
+Landing copy can be customized without AI:
+
+```bash
+whale create landing --theme harbor --title "FuelForge" --tagline "Meal planning for athletes who train hard."
+whale create landing --theme aurora --content landing.json
+whale create landing --brief
+```
+
+`landing.json` can define the brand, hero copy, CTA, features, proof, and contact copy. CLI flags override the JSON, so quick edits stay fast. Use `--sample-content` to generate an editable starter file, or `--brief` for a short local questionnaire that creates the JSON and landing together.
+
+---
+
+## Implementation intelligence
+
+Once a component exists, Whale helps you build it right and document it thoroughly. Three commands, one chain:
+
+```bash
+# 1. Generate a typed component scaffold
+whale create component Button --variants primary,secondary,ghost --states hover,focus,disabled
+
+# 2. Generate an implementation contract — spec, tokens, checklist
+whale forge Button
+
+# 3. Generate a developer README using AI
+whale scribe readme Button
+```
+
+`whale forge` produces a Markdown contract in `docs/forge/` with the component's foundation spec (grid, radius, padding), derived design tokens, and an implementation checklist. No API key required.
+
+`whale scribe readme` calls your configured AI provider (Anthropic or OpenAI) and writes a developer-ready README to `docs/scribe/`. Use `--prompt-only` to get the prompt without an API call.
+
+`whale scribe overview` generates a full project README — foundations, component catalog, architectural decisions — in one pass.
+
+---
+
+## Project health (Atlas)
+
+Atlas gives product managers and tech leads a narrative view of the project's operational health.
+
+```bash
+whale atlas health       # AI-generated health report: errors, risk areas, next steps
+whale atlas decisions    # list active architectural decisions by category
+whale atlas decisions --category design-system
+```
+
+`whale atlas health` scans validation issues, component coverage, and recorded decisions, then generates a prioritized health report in `docs/atlas/health.md`. Use `--prompt-only` without an API key.
+
+`whale atlas decisions` lists active decisions inline, grouped by category, with rationale and consequences.
+
 ---
 
 ## Core commands
@@ -114,8 +163,12 @@ Each theme defines four tiers — Identity, Typography, Structural, Interaction
 | `whale changes --since HEAD~5` | What changed in intelligence stores since a git ref |
 | `whale themes list` | Browse available UI themes |
 | `whale create landing --theme <name>` | Generate a themed HTML/CSS landing page |
-| `whale create component Hero` | Generate a typed component with intelligence registration |
-| `whale references add --all` | Install the UI component reference library |
+| `whale create component <Name>` | Generate a typed component with intelligence registration |
+| `whale forge <Component>` | Generate an implementation contract for a registered component |
+| `whale scribe readme <Component>` | Generate a developer README for a component using AI |
+| `whale scribe overview` | Generate a full project README using AI |
+| `whale atlas health` | Generate an AI-powered project health report |
+| `whale atlas decisions` | List active architectural decisions |
 | `whale selene suggest` | AI-powered improvement suggestions (API key optional) |
 | `whale mcp config --client cursor` | Configure an MCP client |
 
@@ -123,14 +176,14 @@ Each theme defines four tiers — Identity, Typography, Structural, Interaction
 
 ## Operating packs
 
-Packs are structured roles — not autonomous agents, but instructions and context that help the agent you already use work with better information.
+Packs add structured operational context to your project. `forge`, `scribe`, and `atlas` are available as both standalone commands and installable packs — installing a pack makes its context visible to AI agents via CLAUDE.md and the MCP server.
 
 ```bash
-whale team add lighthouse   # quality and validation checks
-whale team add scribe       # documentation and wiki generation
-whale team add forge        # implementation architecture
-whale team add atlas        # product strategy
-whale team add selene       # AI suggestions and audits
+whale team add lighthouse   # quality and accessibility validation
+whale team add scribe       # documentation generation
+whale team add forge        # implementation contracts and handoff
+whale team add atlas        # product health and decision tracking
+whale team add selene       # AI suggestions and component audits
 ```
 
 ---
@@ -154,7 +207,7 @@ whale selene describe src/components/Button.tsx
 
 Whale Igniter runs offline by default. Core flows such as themes, drift detection, wiki generation, MCP, and local project analysis do not require an API key and do not send project data over the network.
 
-AI features are opt-in. When you enable Selene API mode, Whale sends the prompt and project context to the selected provider, Anthropic or OpenAI, under that provider's terms. You are responsible for reviewing context before sending it and for keeping secrets or sensitive data out of prompts.
+AI features are opt-in. When you enable Selene API mode or use `whale scribe` / `whale atlas health`, Whale sends the prompt and project context to the selected provider, Anthropic or OpenAI, under that provider's terms. You are responsible for reviewing context before sending it and for keeping secrets or sensitive data out of prompts.
 
 API keys are read from environment variables only: `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`. The key is used only in request headers, and Whale does not log it, write it to config, or persist it on disk.
 
@@ -167,7 +220,7 @@ Whale Igniter has no telemetry or analytics.
 ## Requirements
 
 - Node ≥ 20
-- No API key required for any core flow — themes, drift detection, wiki generation, and MCP are fully local and deterministic
+- No API key required for any core flow — themes, drift detection, wiki generation, MCP, `whale forge`, and `whale atlas decisions` are fully local and deterministic
 
 ---
 
@@ -186,6 +239,6 @@ Brand assets reference JetBrains Mono (SIL Open Font License 1.1) and Special El
 ---
 
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/whale-igniter@1.3.0/brand/logo.svg" alt="" width="44"><br>
+  <img src="https://cdn.jsdelivr.net/npm/whale-igniter@latest/brand/logo.svg" alt="" width="44"><br>
   <sub><b>Whale Igniter</b> · map the project before the agent moves</sub>
 </p>

package/dist/commands/adopt.js

@@ -136,11 +136,13 @@ export async function adoptCommand(targetArg, options = {}) {
             console.log(ui.note("Updated stack to 'tailwind' in whale.config.json"));
         }
     }
-    // ---- Step 6: ensure other intelligence files exist ------------------------
-    for (const file of ["refinements.json", "decisions.json", "components.json"]) {
-        const p = path.join(target, "intelligence", file);
-        if (!(await fs.pathExists(p)))
-            await fs.writeJson(p, [], { spaces: 2 });
+    // ---- Step 6: ensure other intelligence stores exist -----------------------
+    const intelligenceDir = path.join(target, "intelligence");
+    await fs.ensureDir(path.join(intelligenceDir, "decisions"));
+    await fs.ensureDir(path.join(intelligenceDir, "refinements"));
+    const componentsPath = path.join(intelligenceDir, "components.json");
+    if (!(await fs.pathExists(componentsPath))) {
+        await fs.writeJson(componentsPath, [], { spaces: 2 });
     }
     // ---- Step 7: optional Selene enrichment -----------------------------------
     const ai = await getAiAvailability(target);

package/dist/commands/atlas.js

@@ -0,0 +1,196 @@
+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 { validateCss } from "../validators/cssValidator.js";
+import { resolveProvider } from "../selene/providers.js";
+import { callProvider } from "../selene/apiClient.js";
+import { ui } from "../ui/index.js";
+// ---------------------------------------------------------------------------
+// whale atlas health
+// ---------------------------------------------------------------------------
+export async function atlasHealthCommand(options = {}) {
+    const target = resolveTarget();
+    const config = await loadConfig(target);
+    const spinner = ora("Atlas · scanning project health").start();
+    const [components, decisions, refinements, issues] = await Promise.all([
+        loadComponents(target),
+        loadDecisions(target),
+        loadRefinements(target),
+        validateCss(target),
+    ]);
+    spinner.stop();
+    const errors = issues.filter((i) => i.severity === "error");
+    const warnings = issues.filter((i) => i.severity === "warning");
+    // Group issues by type to surface patterns
+    const issuesByType = new Map();
+    for (const issue of issues) {
+        issuesByType.set(issue.type, (issuesByType.get(issue.type) ?? 0) + 1);
+    }
+    const topIssueTypes = [...issuesByType.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5);
+    const activeDecisions = decisions.filter((d) => d.status === "active");
+    const outDir = options.out ?? "docs/atlas";
+    const fileRel = path.join(outDir, "health.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 = buildHealthPrompt({
+        config,
+        components,
+        activeDecisions,
+        refinementsCount: refinements.length,
+        errorCount: errors.length,
+        warningCount: warnings.length,
+        topIssueTypes,
+    });
+    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 spinner2 = ora("Atlas · generating health report").start();
+    const result = await callProvider(resolved, { prompt, maxTokens: 1400, temperature: 0.3 });
+    if (!result.ok) {
+        spinner2.fail(`API error: ${result.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    spinner2.succeed("Health report generated");
+    const content = result.text.trim();
+    await fs.ensureDir(path.dirname(fileAbs));
+    await fs.writeFile(fileAbs, content + "\n", "utf8");
+    console.log(ui.ok(`Atlas → ${ui.path(fileRel)}`));
+    console.log(ui.muted(`  provider: ${resolved.provider} · ${resolved.model}`));
+    // Print a quick inline summary so the user sees signal immediately
+    console.log("");
+    printInlineSummary({ errorCount: errors.length, warningCount: warnings.length, activeDecisions, components });
+}
+// ---------------------------------------------------------------------------
+// whale atlas decisions
+// ---------------------------------------------------------------------------
+export async function atlasDecisionsCommand(options = {}) {
+    const target = resolveTarget();
+    const decisions = await loadDecisions(target);
+    if (decisions.length === 0) {
+        console.log(ui.muted("No decisions recorded yet. Run `whale decision` to add one."));
+        return;
+    }
+    let filtered = decisions;
+    if (options.category) {
+        filtered = filtered.filter((d) => d.category === options.category);
+    }
+    if (options.status) {
+        filtered = filtered.filter((d) => d.status === options.status);
+    }
+    else {
+        filtered = filtered.filter((d) => d.status === "active");
+    }
+    if (filtered.length === 0) {
+        console.log(ui.muted("No decisions match the given filters."));
+        return;
+    }
+    const byCategory = new Map();
+    for (const d of filtered) {
+        const list = byCategory.get(d.category) ?? [];
+        list.push(d);
+        byCategory.set(d.category, list);
+    }
+    for (const [category, list] of byCategory) {
+        console.log(ui.emphasis(`\n${category.toUpperCase()}`));
+        for (const d of list) {
+            console.log(`  ${ui.ok(d.title)}`);
+            console.log(`  ${ui.muted(d.decision)}`);
+            if (d.consequences) {
+                console.log(`  ${ui.muted("→ " + d.consequences)}`);
+            }
+            console.log(`  ${ui.muted(d.timestamp.slice(0, 10) + " · " + d.status)}`);
+        }
+    }
+    console.log(`\n${ui.muted(`${filtered.length} decision(s) shown.`)}`);
+}
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+function buildHealthPrompt(args) {
+    const { config, components, activeDecisions, refinementsCount, errorCount, warningCount, topIssueTypes } = args;
+    const decisionSummary = activeDecisions.length > 0
+        ? activeDecisions.map((d) => `- [${d.category}] ${d.title}: ${d.decision}${d.consequences ? ` (consequences: ${d.consequences})` : ""}`).join("\n")
+        : "  (none recorded)";
+    const issueBreakdown = topIssueTypes.length > 0
+        ? topIssueTypes.map(([type, count]) => `- ${type}: ${count} occurrence(s)`).join("\n")
+        : "  (no issues detected)";
+    const riskSignals = [];
+    if (errorCount > 100)
+        riskSignals.push("High error volume — likely systemic design-system drift");
+    if (errorCount > 0 && refinementsCount === 0)
+        riskSignals.push("Errors present but no refinements recorded — exceptions not being tracked");
+    if (activeDecisions.length === 0)
+        riskSignals.push("No architectural decisions recorded — context risk for future agents and contributors");
+    if (components.length === 0)
+        riskSignals.push("No components registered — catalog is empty");
+    return [
+        "# Atlas task — project health report",
+        "",
+        "You are a technical product advisor reviewing a frontend project's operational health.",
+        "Write a concise, actionable health report for a PM or tech lead.",
+        "",
+        "## Project",
+        `- Name: ${config.projectName ?? "unnamed"}`,
+        `- Type: ${config.projectType ?? "unspecified"}`,
+        `- Stack: ${config.stack ?? "unspecified"}`,
+        `- Active packs: ${(config.packs ?? []).join(", ") || "none"}`,
+        "",
+        "## Validation status",
+        `- Errors: ${errorCount}`,
+        `- Warnings: ${warningCount}`,
+        `- Top issue types:`,
+        issueBreakdown,
+        "",
+        "## Design system posture",
+        `- Components registered: ${components.length}`,
+        `- Active decisions: ${activeDecisions.length}`,
+        `- Refinements (approved exceptions): ${refinementsCount}`,
+        "",
+        "## Active decisions",
+        decisionSummary,
+        "",
+        ...(riskSignals.length > 0 ? [
+            "## Risk signals detected",
+            riskSignals.map((s) => `- ${s}`).join("\n"),
+            "",
+        ] : []),
+        "## Task",
+        "Write a health report with these sections:",
+        "1. **Executive summary** (2-3 sentences on overall project health)",
+        "2. **Validation health** (what the error/warning counts mean in practice)",
+        "3. **Design system maturity** (component coverage, decision hygiene)",
+        "4. **Risk areas** (specific things that need attention)",
+        "5. **Recommended next steps** (3-5 concrete actions, ordered by priority)",
+        "",
+        "Be direct and specific. No generic advice. Audience: PM or tech lead who can act on it.",
+        "Write in plain Markdown. No preamble or explanation outside the report.",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Inline summary
+// ---------------------------------------------------------------------------
+function printInlineSummary(args) {
+    const { errorCount, warningCount, activeDecisions, components } = args;
+    const healthEmoji = errorCount === 0 ? "●" : errorCount < 50 ? "◐" : "○";
+    console.log(`${healthEmoji}  ${errorCount} error(s) · ${warningCount} warning(s) · ${components.length} component(s) · ${activeDecisions.length} decision(s)`);
+}

package/dist/commands/changes.js

@@ -1,21 +1,22 @@
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
+import matter from "gray-matter";
 import { resolveTarget } from "../utils/paths.js";
-import { loadDecisions } from "../utils/decisions.js";
 import { loadComponents } from "../utils/components.js";
-import { loadRefinements } from "../utils/refinements.js";
 import { ui } from "../ui/index.js";
+const DECISIONS_DIR = "intelligence/decisions";
+const REFINEMENTS_DIR = "intelligence/refinements";
 const INTELLIGENCE_FILES = [
-    "intelligence/decisions.json",
+    DECISIONS_DIR,
+    REFINEMENTS_DIR,
     "intelligence/components.json",
-    "intelligence/refinements.json",
     "whale.config.json"
 ];
+function git(target, args) {
+    return execFileSync("git", args, { cwd: target, encoding: "utf8" });
+}
 function gitDiffFiles(target, since) {
     try {
-        const result = execSync(`git diff --name-only ${since} HEAD -- ${INTELLIGENCE_FILES.join(" ")}`, {
-            cwd: target,
-            encoding: "utf8"
-        });
+        const result = git(target, ["diff", "--name-only", since, "HEAD", "--", ...INTELLIGENCE_FILES]);
         return result.trim().split("\n").filter(Boolean);
     }
     catch {
@@ -24,13 +25,49 @@ function gitDiffFiles(target, since) {
 }
 function gitFileAtRef(target, ref, file) {
     try {
-        const raw = execSync(`git show ${ref}:${file}`, { cwd: target, encoding: "utf8" });
+        const raw = git(target, ["show", `${ref}:${file}`]);
         return JSON.parse(raw);
     }
     catch {
         return [];
     }
 }
+function mdLabelAtRef(target, ref, file, label) {
+    try {
+        const raw = git(target, ["show", `${ref}:${file}`]);
+        return label(raw) || file;
+    }
+    catch {
+        return file;
+    }
+}
+const decisionLabel = (raw) => {
+    const title = matter(raw).data?.title;
+    return title ? String(title) : "";
+};
+const refinementLabel = (raw) => matter(raw).content.trim().split("\n")[0] ?? "";
+function gitDirChanges(target, since, dir, label) {
+    const result = { added: [], removed: [], modified: [] };
+    let raw = "";
+    try {
+        raw = git(target, ["diff", "--name-status", since, "HEAD", "--", dir]);
+    }
+    catch {
+        return result;
+    }
+    for (const line of raw.trim().split("\n").filter(Boolean)) {
+        const [status, file] = line.split("\t");
+        if (!file || !file.endsWith(".md"))
+            continue;
+        if (status.startsWith("A"))
+            result.added.push(mdLabelAtRef(target, "HEAD", file, label));
+        else if (status.startsWith("D"))
+            result.removed.push(mdLabelAtRef(target, since, file, label));
+        else if (status.startsWith("M") || status.startsWith("R"))
+            result.modified.push(mdLabelAtRef(target, "HEAD", file, label));
+    }
+    return result;
+}
 export async function changesCommand(opts) {
     const target = resolveTarget(opts.target);
     const since = opts.since ?? "HEAD~1";
@@ -49,21 +86,8 @@ export async function changesCommand(opts) {
     if (changedFiles.includes("whale.config.json")) {
         summary.configChanged = true;
     }
-    if (changedFiles.includes("intelligence/decisions.json")) {
-        const before = gitFileAtRef(target, since, "intelligence/decisions.json");
-        const after = await loadDecisions(target);
-        const beforeIds = new Map(before.map((d) => [d.id, d.title]));
-        const afterIds = new Map(after.map((d) => [d.id, d.title]));
-        for (const [id, title] of afterIds) {
-            if (!beforeIds.has(id))
-                summary.decisions.added.push(title);
-        }
-        for (const [id, title] of beforeIds) {
-            if (!afterIds.has(id))
-                summary.decisions.removed.push(title);
-            else if (afterIds.get(id) !== title)
-                summary.decisions.modified.push(title);
-        }
+    if (changedFiles.some((f) => f.startsWith(`${DECISIONS_DIR}/`))) {
+        summary.decisions = gitDirChanges(target, since, DECISIONS_DIR, decisionLabel);
     }
     if (changedFiles.includes("intelligence/components.json")) {
         const before = gitFileAtRef(target, since, "intelligence/components.json");
@@ -79,20 +103,10 @@ export async function changesCommand(opts) {
                 summary.components.removed.push(name);
         }
     }
-    if (changedFiles.includes("intelligence/refinements.json")) {
-        const before = gitFileAtRef(target, since, "intelligence/refinements.json");
-        const after = await loadRefinements(target);
-        const beforeIds = new Set(before.map((r) => r.id));
-        const afterIds = new Set(after.map((r) => r.id));
-        const beforeNotes = new Map(before.map((r) => [r.id, r.note]));
-        for (const r of after) {
-            if (!beforeIds.has(r.id))
-                summary.refinements.added.push(r.note);
-        }
-        for (const [id, note] of beforeNotes) {
-            if (!afterIds.has(id))
-                summary.refinements.removed.push(note);
-        }
+    if (changedFiles.some((f) => f.startsWith(`${REFINEMENTS_DIR}/`))) {
+        const changes = gitDirChanges(target, since, REFINEMENTS_DIR, refinementLabel);
+        summary.refinements.added = changes.added;
+        summary.refinements.removed = changes.removed;
     }
     // ---- Render ----------------------------------------------------------------
     if (summary.configChanged) {

package/dist/commands/createComponent.js

@@ -98,6 +98,9 @@ export async function createComponentCommand(name, options = {}) {
         await generateWiki(target);
         console.log(ui.muted(`${ui.glyph.check} AI context updated`));
     }
+    if (shouldRegister) {
+        console.log(ui.muted(`  → run \`whale forge ${name}\` to generate an implementation contract`));
+    }
 }
 // ---------------------------------------------------------------------------
 // Heuristics & templates