whale-igniter 1.3.6 → 1.3.7

package/README.md

@@ -9,132 +9,151 @@
   <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 files are rendered
-from it so agents always read current project state.
+`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.
 
-## What's new in v1.3
+The agent doesn't guess anymore. It reads.
 
-**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.
+---
 
-**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.
+## What agents can read — and write
 
-**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.
+Whale ships an **MCP server** that exposes your project intelligence as structured tools any compatible client can call:
 
-**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.
+```bash
+whale mcp config --client claude-code
+whale mcp config --client cursor
+whale mcp config --client zed
+```
 
-**`whale changes --since <ref>`** — shows what changed in intelligence stores (decisions, components, refinements) since any git ref, ISO date, or `HEAD~1`.
+| 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 |
 
-## Core Commands
+Agents don't just read context — they can write back to it.
 
-| Command | Use it when you want to... |
-| --- | --- |
-| `whale ignite my-app` | Create 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 mcp config --client cursor` | Configure an MCP client |
+---
 
-## Operating Roles
+## Design intelligence
 
-Whale includes five operating roles as packs:
+Whale tracks your design system and detects when reality drifts from it.
 
 ```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 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
 ```
 
-They are not autonomous background agents. They are structured project
-roles and instructions that help the agent you already use work with
-better context.
+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.
 
-## AI Bridge
+---
 
-Selene packages your project context into structured prompts, or calls an
-API when `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` is configured.
+## Theme engine
+
+Landing pages and generated UI are fully theme-driven. No hardcoded tokens.
 
 ```bash
-whale selene status
-whale selene suggest --focus all
-whale selene audit src/components/Hero.tsx
+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)
 ```
 
-Without an API key, Selene runs in prompt mode and prints/copies a prompt
-you can paste into Claude, ChatGPT, Cursor or Codex.
+Each theme defines four tiers — Identity, Typography, Structural, Interaction — and emits a complete CSS custom property block. Swap themes; everything updates.
 
-## MCP
+---
+
+## Core commands
+
+| 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 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 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 mcp config --client claude-code
-whale mcp config --client cursor
-whale mcp config --client zed
+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
 ```
 
-MCP exposes project overview, components, decisions, refinements,
-validation, insights and write tools to compatible AI clients.
+---
 
-## Brand Tokens
+## AI bridge (Selene)
 
-```css
---wi-royal: #0034D3;
---wi-paper: #F2ECE1;
---wi-sky:   #99CCFF;
---wi-deep:  #003087;
+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.
 
---wi-font-display: "Special Elite", ui-monospace, monospace;
---wi-font-mono:    "JetBrains Mono", ui-monospace, monospace;
+```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
 ```
 
-Brand assets ship in `brand/` and are included in the npm package.
+---
+
+## Requirements
+
+- Node ≥ 20
+- No API key required for any core flow — themes, drift detection, wiki generation, and MCP are fully local and deterministic
+
+---
 
 ## Links
 
@@ -142,6 +161,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/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whale-igniter",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "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",