whale-igniter 1.2.1 → 1.2.3

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="./brand/lockup.svg" alt="Whale Igniter" width="640">
+  <img src="https://cdn.jsdelivr.net/npm/whale-igniter@1.2.1/brand/lockup.svg" alt="Whale Igniter" width="640">
 </p>
 
 <p align="center">
@@ -9,332 +9,123 @@
   <img alt="local first" src="https://img.shields.io/badge/local--first-agent%20memory-%230034D3?labelColor=%23F2ECE1&style=flat-square">
 </p>
 
-**CLI-first operational intelligence for AI-assisted product workflows.**
+**Local-first project memory for AI agents.**
 
-Whale gives your project a machine-readable memory so AI agents like
-Claude Code, Codex, Cursor and Copilot understand your design system,
-conventions and decisions from the first commit — without you having
-to re-explain everything every session.
+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.
 
-> AI-native, not AI-dependent. The core is deterministic and runs
-> offline. AI is an enrichment layer — opt-in via API key, or via the
-> built-in MCP server.
-
----
-
-## Install
+## Quick Start
 
 ```bash
-npm install -g whale-igniter
-# or use it directly without installing
 npx whale-igniter ignite my-app
+cd my-app
+npx whale-igniter remember
+npx whale-igniter check
 ```
 
-Requires Node 20 or newer.
-
-Whale's executable is `whale`:
+Install globally if you want the shorter `whale` command:
 
 ```bash
-whale --version
+npm install -g whale-igniter
 whale ignite my-app
 ```
 
----
-
-## The two-minute version
+Requires Node 20 or newer.
 
-```bash
-# Brand new project
-whale ignite my-app
+## What It Creates
 
-# Existing React + Tailwind codebase
-cd my-existing-app
-whale adopt
-whale adopt review        # accept/reject scanner proposals
+```text
+my-app/
+├── whale.config.json
+├── CLAUDE.md
+├── intelligence/
+│   ├── components.json
+│   ├── decisions.json
+│   └── refinements.json
+└── llm-wiki/
 ```
 
-Either path produces a `CLAUDE.md` at the project root plus a
-`llm-wiki/` folder. Open the project in Claude Code (or any AI
-assistant) and it picks up the context automatically.
-
----
-
-## What Whale does
-
-### 1. Bootstraps AI context for new projects
-
-`whale ignite` creates a workspace with foundations, a config, the
-intelligence stores, and a fully-generated `CLAUDE.md`. Three modes:
-opinionated default, `--minimal` skeleton, or `--interactive` wizard.
-
-### 2. Adopts existing projects
-
-`whale adopt` parses your React/Tailwind source with a real AST, infers
-foundations (grid, radii, palette), detects components, and stages
-proposals you can review and accept. Idempotent — re-runs don't
-duplicate or overwrite your decisions.
-
-### 3. Records operational context as you work
+`intelligence/*.json` is the source of truth. Markdown files are rendered
+from it so agents always read current project state.
 
-Three structured stores capture what would otherwise live in your head:
+## Core Commands
 
-- **`intelligence/components.json`** — component catalog
-- **`intelligence/decisions.json`** — architectural and product decisions
-- **`intelligence/refinements.json`** — approved exceptions to the system
-
-Every write auto-regenerates `CLAUDE.md` so agents always read current state.
-
-### 4. Surfaces accountable insights
-
-`whale insights` runs deterministic analyzers over your stores and code:
-refinement clusters, decision tension, orphan components, token drift,
-grid drift, catalog coverage gaps. No AI in the loop — local,
-explainable, machine-checkable.
-
-### 5. Generates code that respects your foundations
-
-`whale create component Card --variants primary,outline` produces a
-typed React component using your actual grid, radii, and accent color.
-No invented values. Auto-registers in the catalog.
-
-### 6. Bridges to any AI agent (Selene)
-
-Three composable commands — `describe`, `audit`, `suggest` — package
-your full project context into a structured prompt. They work three ways:
-
-- **Prompt mode** (default, offline): writes the prompt to clipboard;
-  paste into Claude/ChatGPT/Cursor; paste response back with
-  `whale selene apply`.
-- **API mode** (opt-in): if `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
-  is set, Whale calls the provider directly and auto-applies the result.
-  Transparent fallback to prompt mode on any failure.
-- **MCP mode** (new in v1.0): Whale exposes its capabilities as MCP
-  tools that Claude Code, Cursor, Zed and any MCP client use natively.
-
-### 7. Stays in sync automatically
-
-`whale watch` regenerates `CLAUDE.md` and the wiki when your foundations
-or stores change. Plays well with pre-commit hooks and CI.
-
----
+| Command | Use it when you want to... |
+| --- | --- |
+| `whale ignite my-app` | Create a new Whale workspace |
+| `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 team` | See active operating roles/packs |
+| `whale create component Hero` | Generate a typed React component |
+| `whale mcp config --client cursor` | Configure an MCP client |
 
-## MCP server
+## Operating Roles
 
-The most powerful integration in v1.0. Wire Whale into your AI tool:
+Whale includes five operating roles as packs:
 
 ```bash
-whale mcp config --client claude-code
-# Prints the JSON snippet for ~/Library/Application Support/Claude/claude_desktop_config.json
+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
 ```
 
-Once configured, the agent gets tools like:
-
-- `whale_project_overview` — read foundations, packs, counts in one call
-- `whale_list_components` — see what already exists before creating duplicates
-- `whale_list_decisions` — understand why the project is structured this way
-- `whale_register_component` — record components the agent creates
-- `whale_record_decision` — record non-obvious choices as they happen
-- `whale_validate`, `whale_insights` — check state mid-session
-
-Available client snippets: `--client claude-code | cursor | zed | raw`.
-
----
-
-## Command reference
-
-| Command | What it does |
-| --- | --- |
-| `whale ignite [name]` | Bootstrap a workspace. Flags: `--interactive`, `--minimal`. |
-| `whale adopt [target]` | Scan an existing project and stage proposals. |
-| `whale adopt review` | Walk through pending proposals interactively. |
-| `whale adopt status` | List proposals without entering review. |
-| `whale sync` | Regenerate CLAUDE.md + wiki from `intelligence/*.json`. |
-| `whale remember` | Friendly alias for `sync`: update project memory for AI assistants. |
-| `whale check` | Friendly health check: run `validate` and then `insights`. |
-| `whale improve` | Friendly Selene entry point: suggest project-wide improvements. |
-| `whale explain` | Friendly docs entry point: generate reports and wiki/context. |
-| `whale team` | Show active and available AI teammates. |
-| `whale team add <name>` | Add atlas, forge, scribe, lighthouse, or selene as an AI teammate. |
-| `whale watch` | Auto-regenerate on changes. Flags: `--once`, `--verbose`, `--debounce`. |
-| `whale validate` | Run validators. Non-zero exit on errors. |
-| `whale insights` | Local analyzers + recommendations. Flags: `--json`, `--category`, `--min-severity`. |
-| `whale refine "<note>"` | Record a validator override. |
-| `whale decision` | Record an architectural / product decision. |
-| `whale component add <name>` | Register a component. |
-| `whale create component <name>` | Generate a typed component scaffold. |
-| `whale selene describe <component>` | AI-assisted catalog description. |
-| `whale selene audit <file>` | AI-assisted audit against foundations. |
-| `whale selene suggest` | AI-suggested patterns and decisions. |
-| `whale selene apply <kind>` | Apply pasted LLM response. |
-| `whale selene status` | Show provider state, mode, cache. |
-| `whale mcp serve` | Start the MCP server on stdio. |
-| `whale mcp config` | Print client configuration snippets. |
-| `whale docs` | Generate human-facing reports. |
+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
 
-## Project structure
+Selene packages your project context into structured prompts, or calls an
+API when `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` is configured.
 
+```bash
+whale selene status
+whale selene suggest --focus all
+whale selene audit src/components/Hero.tsx
 ```
-my-app/
-├── whale.config.json              foundations, packs, AI targets
-├── CLAUDE.md                      AI entry point (auto-generated)
-├── AGENTS.md                      if "codex" in aiTargets
-├── .cursorrules                   if "cursor" in aiTargets
-├── intelligence/                  source of truth (JSON)
-│   ├── refinements.json
-│   ├── decisions.json
-│   └── components.json
-├── llm-wiki/                      rendered view (markdown)
-│   ├── FOUNDATIONS.md
-│   ├── CONVENTIONS.md
-│   ├── DECISIONS.md
-│   ├── COMPONENTS.md
-│   └── WORKFLOWS.md
-└── .whale/                        runtime caches and Selene stash
-    └── selene/
-        ├── cache/
-        └── *.prompt.md / *.response.md
-```
-
-**JSON is the source of truth. Markdown is rendered.** Edit a JSON
-store by hand, run `whale sync` (or have `whale watch` running), and
-everything else catches up.
 
----
+Without an API key, Selene runs in prompt mode and prints/copies a prompt
+you can paste into Claude, ChatGPT, Cursor or Codex.
 
-## Selene configuration
+## MCP
 
-Optional block in `whale.config.json` for API mode:
-
-```json
-{
-  "selene": {
-    "provider": "anthropic",
-    "model": "claude-sonnet-4-6",
-    "temperature": 0.2,
-    "maxTokens": 1500,
-    "autoCall": true,
-    "confirmCost": false,
-    "noCache": false
-  }
-}
+```bash
+whale mcp config --client claude-code
+whale mcp config --client cursor
+whale mcp config --client zed
 ```
 
-Everything is optional. With no config and no key, Selene runs in
-prompt mode forever. Adding a key (env or here) flips it to API mode.
-Set `autoCall: false` to keep prompt mode even with a key available.
-
----
-
-## Presentation
-
-Whale's terminal output is built on a semantic UI layer: commands describe
-*intent* (success, warning, section header, key/value pair) and the active
-theme decides what each intent looks like. One result is that the same
-command produces premium output in a real terminal and clean, grep-friendly
-output in CI.
-
-Three environment variables control presentation:
-
-| Variable | Effect |
-| --- | --- |
-| `WHALE_PLAIN=1` | Disable color *and* Unicode glyphs. The output becomes ASCII-only and grep-friendly. Recommended for CI logs and pipelines. |
-| `WHALE_UNICODE=0` | Keep color, fall back to ASCII glyphs (`*`, `v`, `x`, `->`). Useful for terminals that render color but mangle Unicode. |
-| `NO_COLOR=1` / `FORCE_COLOR=0` | Standard environment overrides — chalk respects them, so does Whale. |
-
-In normal terminals Whale auto-detects capabilities and uses Unicode + color.
-In non-TTY contexts (piping, CI, scripts) it strips both automatically. You
-don't need to opt in unless you want to override the default.
-
----
-
-## Brand kit
-
-Whale ships its identity assets in `brand/` so the GitHub README, npm page,
-demos and future splash surfaces all speak the same visual language.
-
-### Palette
+MCP exposes project overview, components, decisions, refinements,
+validation, insights and write tools to compatible AI clients.
 
-| Token | Hex | Role |
-| --- | --- | --- |
-| `--wi-royal` | `#0034D3` | Primary ink, mark body, headings |
-| `--wi-paper` | `#F2ECE1` | Page background, knockout fill |
-| `--wi-sky` | `#99CCFF` | Soft accent and fills |
-| `--wi-deep` | `#003087` | Dark surface and on-light text |
-
-### Typography
+## Brand Tokens
 
 ```css
+--wi-royal: #0034D3;
+--wi-paper: #F2ECE1;
+--wi-sky:   #99CCFF;
+--wi-deep:  #003087;
+
 --wi-font-display: "Special Elite", ui-monospace, monospace;
 --wi-font-mono:    "JetBrains Mono", ui-monospace, monospace;
 ```
 
-- **Display** — `Special Elite`, used for the wordmark and expressive headings.
-- **Mono** — `JetBrains Mono`, used for CLI surfaces and code samples.
-
-### Assets
-
-| File | Use |
-| --- | --- |
-| `brand/logo.svg` | Primary mark |
-| `brand/wordmark.svg` | Wordmark only |
-| `brand/lockup.svg` | Mark + wordmark for README and docs |
-| `brand/logo-on-paper.svg` | Mark on paper background |
-| `brand/logo-on-royal.svg` | Knockout mark on royal |
-| `brand/favicon.svg` | Light favicon |
-| `brand/favicon-dark.svg` | Dark favicon |
-
----
-
-## CI usage
-
-```yaml
-- run: npx whale-igniter validate .       # exits non-zero on errors
-- run: npx whale-igniter sync              # ensure CLAUDE.md is current
-- run: git diff --exit-code                # fail if sync produced uncommitted changes
-```
-
-This turns "is the AI context current?" into a checkable property of
-the repo. Combine with `whale insights --json --min-severity warning`
-for automated quality reports.
-
----
-
-## Design principles
-
-1. **CLI-first.** Whale is a CLI and the MCP server. No dashboard, no SaaS.
-2. **Local-first.** Intelligence lives in your repo, in git. No accounts.
-3. **AI-native, not AI-dependent.** Core works offline. AI is opt-in at
-   every level.
-4. **Source of truth in JSON; rendered views in Markdown.** One direction.
-5. **Idempotent everywhere.** Re-running adopt, sync, watch, or
-   register doesn't duplicate or corrupt anything.
-6. **Honest fallbacks.** API down? Falls back to prompt mode. Scan
-   fails? Insights skip orphan/drift but still run. Watcher recursive
-   not supported? Falls back to non-recursive. The user is never stuck.
-
----
-
-## What v1.2 doesn't do (and why)
-
-- **Vue / Svelte parsing.** Scanner is React + Tailwind only. Other
-  frameworks need their own parsers; that's post-v1.0.
-- **Hosted SaaS.** Whale is a tool, not a service. By design.
-- **Real-time team sync.** Today everything is local + git. Team
-  workflows happen through PRs against `intelligence/*.json`.
-- **Generic linting.** ESLint and Stylelint exist. Whale only checks
-  what's tied to operational context.
-
-See [docs/ROADMAP.md](docs/ROADMAP.md) for what's planned next.
-
----
+Brand assets ship in `brand/` and are included in the npm package.
 
-## License
+## Links
 
-MIT. See [LICENSE](LICENSE).
+- Roadmap: [`docs/ROADMAP.md`](docs/ROADMAP.md)
+- Package: [npmjs.com/package/whale-igniter](https://www.npmjs.com/package/whale-igniter)
+- License: MIT
 
 <p align="center">
-  <img src="./brand/logo.svg" alt="" width="44"><br>
-  <sub><b>Whale Igniter</b> · local-first project memory for AI agents</sub>
+  <img src="https://cdn.jsdelivr.net/npm/whale-igniter@1.2.1/brand/logo.svg" alt="" width="44"><br>
+  <sub><b>Whale Igniter</b> · map the project before the agent moves</sub>
 </p>

package/dist/version.js

@@ -1 +1 @@
-export const PACKAGE_VERSION = "1.2.1";
+export const PACKAGE_VERSION = "1.2.3";

package/package.json

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