whale-igniter 1.3.6 → 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to Whale Igniter are documented here.
+
+## 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

@@ -9,132 +9,173 @@
   <img alt="local first" src="https://img.shields.io/badge/local--first-agent%20memory-%230034D3?labelColor=%23F2ECE1&style=flat-square">
 </p>
 
-**Local-first project memory for AI agents.**
+---
 
-Whale Igniter gives your repo a structured memory: design foundations,
-components, decisions, refinements and generated agent context. It is
-CLI-first, deterministic by default, and works with Codex, Claude Code,
-Cursor, Copilot and any MCP client.
+**Your agent is only as smart as the context you give it. Whale makes that context automatic.**
 
-## Quick Start
+AI agents — Claude Code, Codex, Cursor, Copilot — are powerful but amnesiac by design. Every conversation starts from zero. They don't know what you decided, why you decided it, or which exceptions are intentional. Without structure, they guess.
 
-```bash
-npx whale-igniter ignite my-app
-cd my-app
-npx whale-igniter remember
-npx whale-igniter check
-```
+Whale Igniter gives your repo a **living memory**: design foundations, components, decisions, and approved exceptions — kept in sync by the CLI, readable by any agent, and never dependent on a chat history that will disappear.
+
+---
 
-Install globally if you want the shorter `whale` command:
+## How it works
 
 ```bash
 npm install -g whale-igniter
 whale ignite my-app
 ```
 
-Requires Node 20 or newer.
+That single command creates a structured intelligence layer inside your project:
 
-## What It Creates
-
-```text
+```
 my-app/
-├── whale.config.json
-├── CLAUDE.md
+├── whale.config.json          # foundations, stack, theme, AI targets
+├── CLAUDE.md                  # agent-readable project brief, auto-synced
 ├── intelligence/
-│   ├── components.json
-│   ├── decisions.json
-│   └── refinements.json
-└── llm-wiki/
+│   ├── components.json        # component catalog with variants and states
+│   ├── decisions.json         # architectural decisions and their rationale
+│   └── refinements.json       # approved exceptions — "this is intentional"
+└── 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.
+
+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
+
+Whale ships an **MCP server** that exposes your project intelligence as structured tools any compatible client can call:
+
+```bash
+whale mcp config --client claude-code
+whale mcp config --client cursor
+whale mcp config --client zed
+```
+
+| Tool | What it does |
+|---|---|
+| `whale_project_overview` | Full project brief: stack, foundations, packs, context |
+| `whale_list_components` | Component catalog with files, variants, states, tokens |
+| `whale_list_decisions` | Architectural decisions with rationale and status |
+| `whale_list_refinements` | Approved exceptions — context for drift that's intentional |
+| `whale_insights` | Live analysis: orphans, coverage gaps, tensions, drift |
+| `whale_register_component` | Add a component to the catalog |
+| `whale_record_decision` | Log an architectural decision |
+| `whale_record_refinement` | Mark a drift exception as approved |
+
+Agents don't just read context — they can write back to it.
+
+---
+
+## Design intelligence
+
+Whale tracks your design system and detects when reality drifts from it.
+
+```bash
+whale insights drift spacing    # find off-grid spacing in CSS, JSX, Vue, Svelte
+whale insights drift color      # find raw hex values outside your token set
+whale insights drift radii      # find radius values not in your foundations
+whale insights drift spacing --review   # interactively accept or queue each issue
 ```
 
-`intelligence/*.json` is the source of truth. Markdown files are rendered
-from it so agents always read current project state.
+When something drifts intentionally — a one-off exception, a product decision — you record it as a refinement. Whale stops flagging it. The agent knows it's approved.
 
-## What's new in v1.3
+---
 
-**UI references library** — curated, copy-paste component references ship with the tool. Run `whale references add forms` (or `--all`) to install them into your project. CLAUDE.md and MCP tools automatically expose the files to agents.
+## Theme engine
 
-**Cross-framework drift detection** — `whale insights drift spacing|color|radii` scans CSS, inline styles, Vue/Svelte style blocks and JSX props for values that don't match your foundations. Run `--review` to accept exceptions as refinements or flag them for refactor.
+Landing pages and generated UI are fully theme-driven. No hardcoded tokens.
 
-**Human-language wizard** — `whale ignite --interactive` now asks plain-English questions (what are you building, which framework, team size) and maps answers to a sensible config automatically.
+```bash
+whale themes list
+whale create landing --theme harbor     # royal blue on paper — the Whale brand
+whale create landing --theme aurora     # modern SaaS, indigo, generous whitespace
+whale create landing --theme atlas      # enterprise minimal, dense, neutral (default)
+```
 
-**Template extraction** — wiki templates moved to `src/templates/` as composable render functions. CLAUDE.md is now structured as three clear sections: what the project is, what to read, and how to work here.
+Each theme defines four tiers — Identity, Typography, Structural, Interaction — and emits a complete CSS custom property block. Swap themes; everything updates.
 
-**`whale changes --since <ref>`** — shows what changed in intelligence stores (decisions, components, refinements) since any git ref, ISO date, or `HEAD~1`.
+---
 
-## Core Commands
+## Core commands
 
-| Command | Use it when you want to... |
-| --- | --- |
-| `whale ignite my-app` | Create a new Whale workspace |
+| Command | What it does |
+|---|---|
+| `whale ignite my-app` | Bootstrap a new Whale workspace |
 | `whale ignite my-app --interactive` | Wizard: project type, stack, team size, packs |
-| `whale adopt` | Scan an existing React/Tailwind project |
-| `whale remember` | Regenerate agent context and wiki |
-| `whale check` | Run validation and project insights |
-| `whale improve` | Ask Selene for improvement suggestions |
-| `whale explain` | Generate docs and AI-readable context |
-| `whale references add --all` | Install UI component reference library |
-| `whale insights drift spacing` | Find off-grid spacing across CSS and JSX |
-| `whale insights drift spacing --review` | Interactively accept or queue each drift issue |
-| `whale changes --since HEAD~5` | Show what changed in intelligence stores |
-| `whale team` | See active operating roles/packs |
-| `whale create component Hero` | Generate a typed React component |
+| `whale adopt` | Scan an existing project and propose components and foundations |
+| `whale sync` | Regenerate CLAUDE.md, wiki, and agent context |
+| `whale check` | Validation + project insights |
+| `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 selene suggest` | AI-powered improvement suggestions (API key optional) |
 | `whale mcp config --client cursor` | Configure an MCP client |
 
-## Operating Roles
+---
 
-Whale includes five operating roles as packs:
+## Operating packs
+
+Packs are structured roles — not autonomous agents, but instructions and context that help the agent you already use work with better information.
 
 ```bash
-whale team add atlas       # product strategy
-whale team add forge       # implementation architecture
-whale team add scribe      # documentation
-whale team add lighthouse  # quality checks
-whale team add selene      # AI suggestions and audits
+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
 ```
 
-They are not autonomous background agents. They are structured project
-roles and instructions that help the agent you already use work with
-better context.
+---
 
-## AI Bridge
+## AI bridge (Selene)
 
-Selene packages your project context into structured prompts, or calls an
-API when `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` is configured.
+Selene packages your project context into structured prompts. With an API key it calls the model directly; without one it prints a prompt you can paste anywhere.
 
 ```bash
+export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY
+
 whale selene status
 whale selene suggest --focus all
 whale selene audit src/components/Hero.tsx
+whale selene describe src/components/Button.tsx
 ```
 
-Without an API key, Selene runs in prompt mode and prints/copies a prompt
-you can paste into Claude, ChatGPT, Cursor or Codex.
+---
 
-## MCP
+## Data & privacy
 
-```bash
-whale mcp config --client claude-code
-whale mcp config --client cursor
-whale mcp config --client zed
-```
+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.
 
-MCP exposes project overview, components, decisions, refinements,
-validation, insights and write tools to compatible AI clients.
+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.
 
-## Brand Tokens
+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.
 
-```css
---wi-royal: #0034D3;
---wi-paper: #F2ECE1;
---wi-sky:   #99CCFF;
---wi-deep:  #003087;
+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.
 
---wi-font-display: "Special Elite", ui-monospace, monospace;
---wi-font-mono:    "JetBrains Mono", ui-monospace, monospace;
-```
+Whale Igniter has no telemetry or analytics.
+
+---
+
+## Requirements
 
-Brand assets ship in `brand/` and are included in the npm package.
+- Node ≥ 20
+- No API key required for any core flow — themes, drift detection, wiki generation, and MCP 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.
+
+---
 
 ## Links
 
@@ -142,6 +183,8 @@ Brand assets ship in `brand/` and are included in the npm package.
 - Package: [npmjs.com/package/whale-igniter](https://www.npmjs.com/package/whale-igniter)
 - License: MIT
 
+---
+
 <p align="center">
   <img src="https://cdn.jsdelivr.net/npm/whale-igniter@1.3.0/brand/logo.svg" alt="" width="44"><br>
   <sub><b>Whale Igniter</b> · map the project before the agent moves</sub>

package/dist/selene/cache.js

@@ -44,6 +44,7 @@ export async function writeCache(target, model, prompt, text) {
     const key = cacheKey(model, prompt);
     const dir = path.join(target, CACHE_DIR_REL);
     await fs.ensureDir(dir);
+    await ensureWhaleGitignore(target);
     const entry = {
         key,
         model,
@@ -66,3 +67,13 @@ export async function clearCache(target) {
     }
     return removed;
 }
+async function ensureWhaleGitignore(target) {
+    const gitignore = path.join(target, ".gitignore");
+    const entry = ".whale/";
+    const existing = (await fs.pathExists(gitignore)) ? await fs.readFile(gitignore, "utf8") : "";
+    const lines = existing.split(/\r?\n/).map((line) => line.trim());
+    if (lines.includes(entry))
+        return;
+    const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    await fs.appendFile(gitignore, `${prefix}${entry}\n`, "utf8");
+}

package/dist/ui/splash.js

@@ -6,7 +6,7 @@
  *   2. Unicode, no color       — same layout, no color
  *   3. Plain                   — single ASCII line, no glyphs
  *
- * Rules: no chalk imports, no direct env var reads, no "premium".
+ * Rules: no chalk imports, no direct env var reads, no vague status copy.
  * Uses `capabilities()` from capabilities.js and `ui` atoms.
  */
 import { capabilities } from "./capabilities.js";

package/dist/version.js

@@ -1 +1 @@
-export const PACKAGE_VERSION = "1.3.6";
+export const PACKAGE_VERSION = "1.4.0";

package/docs/ROADMAP.md

@@ -85,7 +85,7 @@ reveals that the next plan needs revising, we revise it before shipping.
 - **Test coverage.** 44 unit tests + MCP smoke test that spawns the
   server and exercises real protocol calls end-to-end.
 
-### v1.1 — Premium runtime UI
+### v1.1 — Polished runtime UI
 
 The terminal output became the product surface. Commands stopped reaching
 for chalk directly; every command now consumes a semantic UI layer where
@@ -96,7 +96,7 @@ pair) and the active theme decides what each intent looks like.
   with ASCII fallbacks), blocks (header, section, kv, panel, summary,
   next, ok/fail/warn/note), theme dispatcher. Commands import from `ui/`
   rather than chalk; chalk is now confined to the theme module.
-- **Single premium theme — graphite.** Cyan accent, charcoal grays, three
+- **Single polished theme — graphite.** Cyan accent, charcoal grays, three
   text-hierarchy levels. Structure ready for v1.2's multi-theme without
   touching any command.
 - **Capability detection.** Auto-detects color and Unicode support; falls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whale-igniter",
-  "version": "1.3.6",
+  "version": "1.4.0",
   "description": "CLI-first operational intelligence. Bootstraps and adopts AI-readable project context so agents like Claude Code, Codex and Cursor understand your design system from the first commit. Includes an MCP server, a file watcher, deterministic insights, and an opt-in AI bridge (Selene).",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,6 +14,7 @@
     "themes",
     "ui-references",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "docs/ROADMAP.md"
   ],