infernoflow 0.33.0 → 0.34.0

package/README.md

@@ -1,11 +1,37 @@
 # 🔥 infernoflow
-> The forge for liquid code — keep capabilities, contracts, and docs in sync automatically as your codebase evolves.
+> Persistent memory for AI coding sessions — captures what agents can't infer from code alone.
 
-## What it does
+AI agents forget everything between sessions. They repeat mistakes you already fixed, ignore decisions you already made, and miss landmines that burned you last week. infernoflow gives every agent a memory that persists.
 
-infernoflow prevents **semantic drift** — where code changes daily but nobody knows what the system actually does. It tracks your project's capabilities, keeps contracts up to date, and works silently in the background so developers never have to think about it.
+Works standalone in any terminal, as a VS Code extension, and as an MCP server inside Claude Code, Cursor, and GitHub Copilot — silently and automatically.
 
-Works standalone in any terminal, as a VS Code extension, and as an MCP server inside Claude Code, Cursor, and GitHub Copilot.
+---
+
+## The problem
+
+Every time you start a new AI session, the agent starts cold. It doesn't know:
+- The gotcha you discovered last Tuesday (don't use X, it breaks Y)
+- The approach you tried and abandoned (3 hours down the drain)
+- The design decisions your team made (we use Tailwind, never inline styles)
+- What you were working on when you handed off to a different agent
+
+So you tell it again. And again. And it still misses things.
+
+## The solution
+
+infernoflow keeps a memory file — `inferno/sessions.jsonl` — that travels with the project. It captures gotchas, decisions, failed attempts, and preferences in real time. Every AI agent that opens this project reads the memory first.
+
+```bash
+infernoflow log "don't use bcrypt v3 — breaks on Windows" --type gotcha
+infernoflow log "decided to use server actions over API routes" --type decision
+infernoflow log "tried react-query for this, performance was worse" --type attempt --result failed
+```
+
+When you switch agents or start a new session, `infernoflow switch` generates a handoff summary — all the gotchas, decisions, and failed attempts for this session — formatted for pasting at the start of the next chat.
+
+When you're wrapping up, `infernoflow recap` shows your session health score: what you captured, what git changes weren't logged, and a nudge to capture the last landmines before you go.
+
+---
 
 ## Install
 
@@ -19,78 +45,158 @@ npm install -g infernoflow
 # Initialize infernoflow in your project
 infernoflow init
 
-# Set up AI provider (Anthropic, OpenAI, Gemini, OpenRouter, or Ollama)
-infernoflow ai setup
+# Log something you just discovered
+infernoflow log "auth token expires in 15 min, not 1h — caught us off-guard" --type gotcha
 
-# Set up MCP server for Claude Code / Cursor
-infernoflow setup --yes
+# Query what's in memory before starting work
+infernoflow ask "auth"
+
+# At end of session — see what's captured and what isn't
+infernoflow recap
 
-# Check project health
-infernoflow doctor
+# Hand off to a new agent — generates a briefing to paste at session start
+infernoflow switch
+
+# Set up MCP server (Cursor / Claude Code) for automatic memory use
+infernoflow setup --yes
 ```
 
 ---
 
-## AI Provider Setup
+## Session memory commands
 
-infernoflow uses AI for `explain`, `why`, `review`, `changelog ai`, and auto contract sync.
+| Command | What it does |
+|---|---|
+| `infernoflow log "..." --type gotcha` | Log a landmine — things that will burn the next agent |
+| `infernoflow log "..." --type decision` | Record a design decision and why |
+| `infernoflow log "..." --type attempt --result failed` | "Don't repeat this" |
+| `infernoflow log "..." --type preference` | Developer habits the agent should match |
+| `infernoflow ask "keyword"` | Search memory — gotchas surface first |
+| `infernoflow ask --recent` | What was logged in the last session |
+| `infernoflow recap` | Session summary + health score + unlogged git changes |
+| `infernoflow switch` | Handoff briefing for the next AI agent |
+| `infernoflow stats` | Value dashboard — entries, token savings, coverage |
+
+### Log types
+
+| Type | Icon | Purpose | Token value |
+|---|---|---|---|
+| `gotcha` | ⚠ | Landmines, unexpected behavior, "don't do X" | Highest |
+| `decision` | ✓ | Architecture and design choices made | High |
+| `attempt` | ↺ | Approaches tried — especially failures | Medium |
+| `preference` | ♦ | Code style, tools, naming conventions | Medium |
+| `theme` | ◈ | Design system changes — colors, fonts, tokens | Medium |
+| `note` | · | General notes | Low |
+
+---
+
+## MCP integration — fully automatic memory
+
+After `infernoflow setup --yes`, infernoflow runs as an MCP server inside Claude Code and Cursor. Agents call infernoflow tools automatically — the developer never has to think about it.
 
 ```bash
-infernoflow ai setup    # interactive numbered menu
-infernoflow ai status   # show configured providers
-infernoflow ai test     # send a test prompt
-infernoflow ai clear    # remove a provider's key
+infernoflow setup --yes                    # Claude Code / Cursor
+infernoflow install-cursor-hooks           # Cursor only
+infernoflow install-vscode-copilot-hooks   # VS Code + Copilot
 ```
 
-Supported providers — no API key needed for Ollama:
+### How it works in practice
 
-| Provider | Env variable | Default model |
+```
+You: "add search to the task list"
+Claude: [calls infernoflow_ask "search" — finds gotcha: "avoid full-text search on tasks table, perf issues"]
+Claude: "One note before I start — previous attempt at full-text search hit perf issues. I'll use..."
+Claude: [writes code, calls infernoflow_suggest → contract updated silently]
+```
+
+### MCP tools
+
+| Tool | When it fires | What it does |
 |---|---|---|
-| Anthropic (Claude) | `ANTHROPIC_API_KEY` | claude-sonnet-4-6 |
-| OpenAI (GPT) | `OPENAI_API_KEY` | gpt-4o |
-| Google Gemini | `GOOGLE_AI_API_KEY` | gemini-2.0-flash |
-| OpenRouter | `OPENROUTER_API_KEY` | any model |
-| Ollama (local) | — | llama3.2 |
+| `infernoflow_status` | Session start | Contract health snapshot |
+| `infernoflow_context` | Session start | Load full project state into AI context |
+| `infernoflow_ask` | Before any implementation | Search memory for gotchas, decisions, failed attempts |
+| `infernoflow_implement` | Before writing code | Generate structured implementation plan |
+| `infernoflow_suggest` | After code changes | Update capability contract silently |
+| `infernoflow_check` | Session end | Validate contract sync |
+| `infernoflow_recap` | Session end | Show unlogged topics, nudge for gotchas |
+| `infernoflow_review` | Pre-push / PR | Check capability drift risk |
+| `infernoflow_synthesize` | Every ~5 sessions | Detect repeating workflows, suggest agents |
+| `infernoflow_log` | Anytime | Log a memory entry directly from chat |
+| `infernoflow_switch` | Agent handoff | Generate handoff briefing |
+| `infernoflow_scan` | On request | Deep code scan — route discovery, entry points |
+| `infernoflow_stats` | On request | Memory + value dashboard |
 
-If you have **Claude Code for VS Code** or **GitHub Copilot**, infernoflow picks up the active model automatically — no API key required.
+---
+
+## Session recap
+
+`infernoflow recap` gives you a D-to-A session health score at the end of every session.
+
+```
+  🔥 infernoflow recap
+  Session since: 27 Apr, 09:15
+
+  Captured this session
+
+  ⚠ gotcha        (2h ago)
+    don't use bcrypt v3 — breaks on Windows ARM
+
+  ✓ decision       (1h ago)
+    using server actions over API routes — simpler auth context
+
+  ─────────────────────────────────────────────────
+
+  Changed but not logged  (git diff since session start)
+
+  ? database
+      prisma/migrations/20260427_add_tokens.sql
+      src/lib/db.ts
+
+  Any gotchas or decisions from these areas worth capturing?
+
+  ─────────────────────────────────────────────────
+
+  Session health
+
+  B  72/100
+
+  ✔  2 entries logged
+  ✔  gotchas captured
+  ·  no decisions recorded
+```
 
 ---
 
-## MCP Integration (Claude Code / Cursor / Copilot)
+## Handoff between agents
 
-After setup, infernoflow registers as an MCP server. Claude Code and Cursor call infernoflow tools automatically — no manual commands needed.
+`infernoflow switch` builds a handoff briefing — all gotchas, decisions, and failed attempts from the current session — formatted to paste at the start of the next AI chat.
 
 ```bash
-infernoflow setup --yes                    # Claude Code / Cursor
-infernoflow install-cursor-hooks           # Cursor only
-infernoflow install-vscode-copilot-hooks   # VS Code + Copilot
+infernoflow switch             # generate inferno/HANDOFF.md
+infernoflow switch --copy      # copy to clipboard
+infernoflow switch --to cursor # label it for the next agent
+infernoflow switch --all       # include all-time memory, not just this session
 ```
 
-### MCP tools available in chat
+The generated briefing puts gotchas first — the most critical things the next agent needs to know — before any capability context or design system info.
 
-| Tool | What it does |
-|---|---|
-| `infernoflow_status` | Contract health snapshot |
-| `infernoflow_context` | Load full project state into AI context |
-| `infernoflow_suggest` | Update capability contract from a description |
-| `infernoflow_apply` | Apply a JSON suggestion — updates contract + CHANGELOG |
-| `infernoflow_check` | Validate contract sync |
-| `infernoflow_implement` | Generate a structured implementation plan |
-| `infernoflow_review` | Check for capability drift risk |
-| `infernoflow_synthesize` | Detect repeating workflows and turn them into agents |
-| `infernoflow_version` | Recommend semver bump based on capability changes |
-| `infernoflow_git_drift` | Detect drift between git commits and contract |
-
-### How it works in Claude Code
+---
 
-```
-You: "add search functionality to the task list"
-Claude: [calls infernoflow_implement → structured plan]
-Claude: [writes the code]
-Claude: [calls infernoflow_suggest → contract updated silently]
-→ capabilities.json, contract.json, CHANGELOG.md stay in sync
+## Capability contract (what was here before)
+
+infernoflow also tracks your project's capabilities — what the system actually does — and keeps contracts, changelogs, and docs in sync automatically as code changes. This is the original infernoflow feature.
+
+```bash
+infernoflow check       # validate contract + capabilities
+infernoflow scan        # detect capabilities from source code
+infernoflow suggest     # AI-powered contract update
+infernoflow status      # contract health at a glance
+infernoflow diff        # what changed since last tag
 ```
 
+The memory layer (log, ask, recap, switch) and the capability layer (check, scan, suggest, contract) work together — scan detects what you built, memory records the gotchas you hit while building it.
+
 ---
 
 ## VS Code Extension
@@ -98,78 +204,92 @@ Claude: [calls infernoflow_suggest → contract updated silently]
 Install `infernoflow-X.X.X.vsix` from the `vscode-extension/` folder in the repo.
 
 **What the extension does:**
-- **Status bar** — permanent `🔥 infernoflow: 12 caps ✓` badge. Click for quick actions menu.
-- **Save-triggered sync** — when you save a source file mapped in `capability-map.json`, infernoflow automatically runs `suggest` + `check` in the background (3s debounce). Zero manual steps.
-- **Drift notification** — if check finds issues after a save, a one-time warning appears with a "View check" button.
-- **Right-click → Sync contract** — right-click any `.ts`/`.js`/`.py` file to manually sync.
-- **Sidebar panels** — Capabilities, Scenarios, Changelog, Agents tree views.
-- **Inline annotations** — capability IDs shown next to matching functions.
-- **AI review** — uses Claude Code / Copilot model directly, no extra key needed.
+- **Status bar** — permanent `🔥 infernoflow: 12 caps ✓` badge with quick actions menu
+- **Save-triggered sync** — when you save a mapped source file, infernoflow runs `suggest` + `check` in the background (3s debounce). Zero manual steps.
+- **Drift notification** — if check finds issues after a save, a one-time warning appears
+- **Sidebar panels** — Capabilities, Scenarios, Changelog, Agents tree views
+- **AI review** — uses Claude Code / Copilot model directly, no extra key needed
+
+---
+
+## AI Provider Setup
+
+infernoflow uses AI for `explain`, `why`, `review`, `changelog ai`, and auto contract sync.
+
+```bash
+infernoflow ai setup    # interactive numbered menu
+infernoflow ai status   # show configured providers
+infernoflow ai test     # test AI connection
+```
+
+Supported providers — no API key needed for Ollama:
+
+| Provider | Env variable | Default model |
+|---|---|---|
+| Anthropic (Claude) | `ANTHROPIC_API_KEY` | claude-sonnet-4-6 |
+| OpenAI (GPT) | `OPENAI_API_KEY` | gpt-4o |
+| Google Gemini | `GOOGLE_AI_API_KEY` | gemini-2.0-flash |
+| OpenRouter | `OPENROUTER_API_KEY` | any model |
+| Ollama (local) | — | llama3.2 |
+
+If you have **Claude Code for VS Code** or **GitHub Copilot**, infernoflow picks up the active model automatically — no API key required.
 
 ---
 
-## Commands
+## All commands
 
-### Core
+### Memory
+| Command | Description |
+|---|---|
+| `infernoflow log "..." --type <type>` | Append to session memory |
+| `infernoflow ask "keyword"` | Search memory by topic — gotchas first |
+| `infernoflow recap` | End-of-session summary + health score |
+| `infernoflow switch` | Handoff briefing for the next AI agent |
+| `infernoflow stats` | Memory value dashboard |
+| `infernoflow theme` | Scan + record design system (colors, fonts, tokens) |
+
+### Contract
 | Command | Description |
 |---|---|
 | `infernoflow init` | Scaffold `inferno/` in your project |
 | `infernoflow status` | Contract health at a glance |
 | `infernoflow check` | Full contract validation |
-| `infernoflow doctor` | Full diagnostic with auto-fix suggestions |
-| `infernoflow setup --yes` | Install MCP server, CLAUDE.md, git hooks |
+| `infernoflow suggest "what changed"` | AI-powered contract update |
+| `infernoflow scan` | AST scan — detect capabilities from code |
+| `infernoflow diff` | Capability changes since last tag |
+| `infernoflow stability` | Frozen / stable / experimental markers |
 
-### AI
+### Intelligence
 | Command | Description |
 |---|---|
-| `infernoflow ai setup` | Interactive AI provider setup |
-| `infernoflow ai status` | Show configured providers |
-| `infernoflow ai test` | Test AI connection |
-| `infernoflow suggest "what changed"` | AI-powered contract update |
 | `infernoflow explain src/auth.ts` | Explain a file's capabilities |
-| `infernoflow why src/auth.ts` | Map file to contract capabilities |
+| `infernoflow why src/auth.ts` | Map file → contract capabilities |
 | `infernoflow review` | AI review of staged changes |
-| `infernoflow changelog ai` | AI-generated changelog entry |
-
-### Code Intelligence
-| Command | Description |
-|---|---|
-| `infernoflow scan` | AST scan — detect capabilities from code |
 | `infernoflow graph` | Capability dependency graph |
 | `infernoflow impact` | Blast radius of a change |
 | `infernoflow coverage` | Map test files to capabilities |
-| `infernoflow stability` | Show frozen/stable/experimental capabilities |
-| `infernoflow freeze <cap>` | Lock a capability (prevents accidental changes) |
 
 ### Workflow
 | Command | Description |
 |---|---|
-| `infernoflow watch` | Auto-run suggest on every file save |
-| `infernoflow run` | One-command detect → propose → apply flow |
 | `infernoflow implement "task"` | Generate a structured coding plan |
 | `infernoflow context` | Build AI session context file |
-| `infernoflow diff` | Show capability changes since last tag |
+| `infernoflow watch` | Auto-run suggest on every file save |
+| `infernoflow synthesize` | Detect repeating workflows → auto-agents |
 | `infernoflow version` | Recommend semver bump |
 | `infernoflow changelog update` | Draft Unreleased section from commits |
 
 ### Ops
 | Command | Description |
 |---|---|
+| `infernoflow doctor` | Full diagnostic with auto-fix suggestions |
+| `infernoflow setup --yes` | Install MCP server, CLAUDE.md, git hooks |
 | `infernoflow ci` | CI/CD integration helper |
-| `infernoflow report` | Generate capability report |
-| `infernoflow snapshot save <name>` | Save a contract snapshot |
-| `infernoflow export` | Export contract to various formats |
 | `infernoflow audit` | Security audit of capabilities |
 | `infernoflow health` | Health score (0–100) |
+| `infernoflow export` | Export contract to OpenAPI / CSV / Markdown |
 | `infernoflow demo` | Narrated 7-step walkthrough |
 
-### Agents
-| Command | Description |
-|---|---|
-| `infernoflow synthesize` | Detect repeating workflows → auto-agents |
-| `infernoflow agent run <name>` | Run a synthesized agent |
-| `infernoflow test` | Run capability scenario tests |
-
 ---
 
 ## CI Integration
@@ -184,34 +304,6 @@ Install `infernoflow-X.X.X.vsix` from the `vscode-extension/` folder in the repo
 
 ---
 
-## Watch Mode
-
-Zero-effort contract sync while you code:
-
-```bash
-infernoflow watch           # watches src/ (auto-detected)
-infernoflow watch src lib   # watch specific directories
-infernoflow watch --interval 5   # 5s debounce
-```
-
-On every source file save, infernoflow checks if the file is mapped to any capabilities, runs `suggest` silently, and logs any issues to `inferno/WATCH.log`.
-
----
-
-## Stability Markers
-
-Tag capabilities as frozen, stable, or experimental:
-
-```bash
-infernoflow freeze auth-login      # lock — no changes allowed
-infernoflow thaw auth-login        # unlock
-infernoflow stability              # view all markers
-```
-
-Frozen capabilities are protected from accidental contract changes.
-
----
-
 ## Troubleshooting
 
 | Problem | Fix |
@@ -225,9 +317,5 @@ Frozen capabilities are protected from accidental contract changes.
 
 ---
 
-## Why infernoflow?
-
-AI-assisted development moves fast. Code changes daily. But what does the system *actually do*? infernoflow keeps the answer current — automatically, invisibly, without interrupting the developer.
-
 ## License
 MIT