whale-igniter 1.3.7 → 1.5.1

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to Whale Igniter are documented here.
+
+## 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
+
+- Local UI theme engine for generated landing pages, with Atlas, Harbor, and Aurora themes.
+- `whale themes list` for browsing shipped themes.
+- Capability-gated `whale ignite` splash with color, Unicode, and plain fallbacks.
+- README Data & privacy section, generated-output ownership note, and font attribution.
+
+### Changed
+
+- Generated landing CSS now emits theme-driven custom properties for color, typography, structure, interaction, and motion.
+- Selene response cache writes now ensure `.whale/` is ignored in the target project's `.gitignore`.
+- Reworded older brand-planning docs to avoid vague status language.
+
+### Verified
+
+- Selene API keys are read from environment variables and used only in provider request headers.
+- Selene cache stores response text under `.whale/selene/cache`; it does not store API keys.
+- No font binaries are shipped.
+- No telemetry or analytics code is present.

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">
@@ -43,6 +43,8 @@ my-app/
 
 The agent doesn't guess anymore. It reads.
 
+Generated output belongs to you. Files created by Whale Igniter, including generated HTML, CSS, CLAUDE.md, AGENTS.md, wiki pages, and copied theme files, are yours to use and modify; they are not restricted by this project's MIT license.
+
 ---
 
 ## What agents can read — and write
@@ -98,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
@@ -112,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 |
 
@@ -121,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
 ```
 
 ---
@@ -148,10 +203,30 @@ whale selene describe src/components/Button.tsx
 
 ---
 
+## Data & privacy
+
+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 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.
+
+Selene's local cache stores response text under `.whale/selene/cache` in the target project. It does not store API keys. Whale also ensures `.whale/` is ignored by the target project's `.gitignore` when writing Selene cache entries.
+
+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
+
+---
+
+## Credits
+
+Brand assets reference JetBrains Mono (SIL Open Font License 1.1) and Special Elite (Apache License 2.0). No font binaries are shipped.
 
 ---
 
@@ -164,6 +239,6 @@ whale selene describe src/components/Button.tsx
 ---
 
 <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/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/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