npm - @proxysoul/soulforge - Versions diffs - 2.3.0 → 2.4.0 - Mend

@proxysoul/soulforge 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -1,103 +1,242 @@
-<p align="center">
-  <a href="https://paypal.me/waeru"><img src="https://img.shields.io/badge/%E2%9A%94%EF%B8%8F_Fuel_the_Forge-PayPal-9B30FF.svg?style=for-the-badge&logo=paypal&logoColor=white" alt="Fuel the Forge" /></a>
-</p>
+<div align="center">
-<h1 align="center">SoulForge</h1>
+<a href="https://paypal.me/waeru"><img src="https://img.shields.io/badge/%E2%9A%94%EF%B8%8F_Fuel_the_Forge-PayPal-9B30FF.svg?style=for-the-badge&logo=paypal&logoColor=white" alt="Fuel the Forge" /></a>
-<p align="center">
-  <strong>The AI coding agent that already knows your codebase.</strong><br/>
-  Graph-powered intelligence · multi-agent dispatch · terminal-native
-</p>
+<br/>
-<p align="center">
-  <a href="https://www.npmjs.com/package/@proxysoul/soulforge"><img src="https://img.shields.io/npm/v/@proxysoul/soulforge?label=version&color=brightgreen" alt="Version" /></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-BSL%201.1-blue.svg" alt="License" /></a>
-  <a href="https://github.com/ProxySoul/soulforge/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ProxySoul/soulforge/ci.yml?label=CI" alt="CI" /></a>
-  <a href="https://github.com/ProxySoul/soulforge/actions/workflows/playground.yml"><img src="https://img.shields.io/github/actions/workflow/status/ProxySoul/soulforge/headless-forge.yml?label=Soul" alt="Headless Forge" /></a>
-  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-blue.svg" alt="TypeScript" /></a>
-  <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f472b6.svg" alt="Bun" /></a>
-</p>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/header-dark.svg" />
+  <source media="(prefers-color-scheme: light)" srcset="assets/header-light.svg" />
+  <img alt="SoulForge" src="assets/header-dark.svg" width="800" />
+</picture>
+<a href="https://www.npmjs.com/package/@proxysoul/soulforge"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/v/@proxysoul/soulforge?label=version&color=7844f0&style=flat-square&labelColor=0a0818" /><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/npm/v/@proxysoul/soulforge?label=version&color=7844f0&style=flat-square" /><img alt="Version" src="https://img.shields.io/npm/v/@proxysoul/soulforge?label=version&color=7844f0&style=flat-square" /></picture></a>&nbsp;
+<a href="LICENSE"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/License-BSL%201.1-ff0059.svg?style=flat-square&labelColor=0a0818" /><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/badge/License-BSL%201.1-ff0059.svg?style=flat-square" /><img alt="License" src="https://img.shields.io/badge/License-BSL%201.1-ff0059.svg?style=flat-square" /></picture></a>&nbsp;
+<a href="https://github.com/ProxySoul/soulforge/actions/workflows/ci.yml"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/actions/workflow/status/ProxySoul/soulforge/ci.yml?label=CI&style=flat-square&color=0b8b00&labelColor=0a0818" /><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/actions/workflow/status/ProxySoul/soulforge/ci.yml?label=CI&style=flat-square&color=0b8b00" /><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/ProxySoul/soulforge/ci.yml?label=CI&style=flat-square" /></picture></a>&nbsp;
+<a href="https://github.com/ProxySoul/soulforge/actions/workflows/playground.yml"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/actions/workflow/status/ProxySoul/soulforge/headless-forge.yml?label=Soul&style=flat-square&color=9b6af5&labelColor=0a0818" /><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/actions/workflow/status/ProxySoul/soulforge/headless-forge.yml?label=Soul&style=flat-square&color=9b6af5" /><img alt="Headless Forge" src="https://img.shields.io/github/actions/workflow/status/ProxySoul/soulforge/headless-forge.yml?label=Soul&style=flat-square" /></picture></a>&nbsp;
+<a href="https://www.typescriptlang.org/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/TypeScript-strict-00a2ce.svg?style=flat-square&labelColor=0a0818" /><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/badge/TypeScript-strict-00a2ce.svg?style=flat-square" /><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-00a2ce.svg?style=flat-square" /></picture></a>&nbsp;
+<a href="https://bun.sh"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/runtime-Bun-ff0059.svg?style=flat-square&labelColor=0a0818" /><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/badge/runtime-Bun-ff0059.svg?style=flat-square" /><img alt="Bun" src="https://img.shields.io/badge/runtime-Bun-ff0059.svg?style=flat-square" /></picture></a>
-<p align="center">
-  <img src="assets/main-1.png" alt="SoulForge — Graph-Powered Code Intelligence" width="900" />
-</p>
+<br/><br/>
----
+<img src="assets/main-1.png" alt="SoulForge" width="900" />
-## Table of Contents
+<br/>
-- [Why SoulForge?](#why-soulforge)
-- [How it compares](#how-it-compares)
-- [Installation](#installation)
-- [Usage](#usage)
-- [Providers](#providers)
-- [Configuration](#configuration)
-- [Documentation](#documentation)
-- [Roadmap](#roadmap)
-- [Inspirations](#inspirations)
-- [License](#license)
+<img src="assets/features.svg" width="800" />
----
+</div>
-## Why SoulForge?
-Every AI coding tool starts blind. The agent reads files, greps around, slowly pieces together what your codebase looks like. You're paying for the agent to figure out what you already know.
+<img src="assets/separator.svg" width="100%" height="8" />
-SoulForge doesn't work that way. On startup, it builds a **live dependency graph** of your entire codebase. Every file, symbol, import, and export, ranked by importance, enriched with git history, updated in real-time as files change. The agent already knows which files matter, what depends on what, and how far an edit will ripple. It doesn't need to explore. It just starts working.
+## Why SoulForge?
-### How SoulForge saves you 30-50% on API costs & in less time
+Every AI coding tool starts blind. It reads files, greps around, slowly builds a mental model of your codebase. You wait. You pay. The agent is doing orientation work, not real work.
+SoulForge already knows. On startup it builds a **live dependency graph** of your entire codebase: every file, symbol, import, and export, ranked by PageRank importance, enriched with git co-change history, updated in real-time as files change. The agent knows which files matter, what depends on what, and how far an edit will ripple before it writes a single line. It's faster. It's more accurate. And it costs less.
+<img src="assets/separator.svg" width="100%" height="8" />
+### Faster, smarter, cheaper
+<table>
+<tr>
+<td width="50%" valign="top">
+<h4><a href="docs/repo-map.md">Live Soul Map</a></h4>
+<p>SQLite-backed graph of every file, symbol, import, and export. PageRank ranking, git co-change history, blast radius scoring, clone detection, FTS5 search, unused export tracking. Updated in real-time. The agent never wastes a turn orienting itself.</p>
+</td>
+<td width="50%" valign="top">
+<h4><a href="docs/architecture.md">Surgical reads</a></h4>
+<p>Instead of reading entire files, the agent extracts exactly the function or class it needs by name. A 500-line file becomes a 20-line symbol extraction. Works across 33 languages via a 4-tier fallback chain: LSP, ts-morph, tree-sitter, regex.</p>
+</td>
+</tr>
+<tr>
+<td valign="top">
+<h4><a href="docs/compaction.md">Instant compaction</a></h4>
+<p>Working state is extracted incrementally as the conversation happens: files touched, decisions made, errors hit. When context gets long, compaction fires instantly from this pre-built state. Rich enough state skips the LLM entirely.</p>
+</td>
+<td valign="top">
+<h4><a href="docs/agent-bus.md">Multi-agent dispatch</a></h4>
+<p>Parallel explore, code, and web search agents. First read caches the file; others get a compact stub. Edit coordination prevents conflicts.</p>
+</td>
+</tr>
+<tr>
+<td valign="top">
+<h4><a href="docs/cross-tab-coordination.md">Multi-tab</a></h4>
+<p>Concurrent sessions, per-tab models and modes. Agents see cross-tab edits, get warnings on contested files, git ops coordinate automatically.</p>
+</td>
+<td valign="top">
+<h4><a href="docs/compound-tools.md">Compound tools</a></h4>
+<p><code>read</code> batches parallel + surgical. <code>multi_edit</code> atomic. <code>rename_symbol</code>, <code>move_symbol</code>, <code>rename_file</code> compiler-guaranteed cross-file. <code>project</code> auto-detects 25+ ecosystems.</p>
+</td>
+</tr>
+<tr>
+<td valign="top">
+<h4>Mix-and-match models</h4>
+<p>Opus on planning, Sonnet on coding, Haiku on cleanup. Or one model for everything. Task router gives full control.</p>
+</td>
+<td valign="top">
+<h4>Prompt caching</h4>
+<p>Soul Map is stable across turns, stays cached. On Anthropic the system prompt costs a fraction of normal.</p>
+</td>
+</tr>
+</table>
+<br/>
-| | |
-|---|---|
-| **[Live Soul Map](docs/repo-map.md)** | A SQLite-backed graph of every file, symbol, import, and export — ranked by PageRank, enriched with git co-change history, updated in real-time. The agent already knows where everything lives and how far an edit will ripple. No wasted tokens orienting itself. |
-| **[Surgical reads](docs/architecture.md)** | Instead of reading entire files, the agent extracts exactly the function or class it needs by name via a 4-tier intelligence chain (LSP → ts-morph → tree-sitter → regex) across 30 languages. A 500-line file becomes a 20-line symbol extraction. |
-| **[Zero-cost compaction](docs/compaction.md)** | State extraction runs as the conversation happens: files touched, decisions made, errors hit. When context gets long, it compacts instantly from this pre-built state. No LLM call, no latency, no cost. |
-| **[Multi-agent dispatch](docs/agent-bus.md)** | Parallelize work across explore, code, and web search agents. The first agent to read a large file caches it — others get a compact stub with symbol names and line ranges. Edit coordination prevents conflicts. |
-| **[Multi-tab coordination](docs/cross-tab-coordination.md)** | Run concurrent sessions with different models and modes per tab. Agents see what other tabs are editing, get warnings on contested files, and git operations coordinate automatically. |
-| **[Compound tools](docs/compound-tools.md)** | `read` batches files in parallel with surgical extraction. `multi_edit` applies changes atomically. `rename_symbol`, `move_symbol`, `rename_file` are compiler-guaranteed and cross-file. `project` auto-detects lint/test/build across 23 ecosystems. |
-| **Mix-and-match models** | You choose which model handles which job. Put Opus on planning, Sonnet on coding, Haiku on search and cleanup. Or use one model for everything. The task router gives you full control. |
-| **Prompt caching** | The Soul Map is stable across turns, so it stays cached. On Anthropic, that means the bulk of the system prompt costs a fraction of what it would otherwise. |
+<details>
+<summary><strong>More features</strong></summary>
+<br/>
+<table>
+<tr>
+<td width="180"><strong>Lock-in mode</strong></td>
+<td>Hides narration, shows only tool activity and final answer. <code>/lock-in</code> or config.</td>
+</tr>
+<tr>
+<td><strong>Embedded Neovim</strong></td>
+<td>Your config, plugins, LSP servers. The AI works through the same editor you use. <a href="docs/architecture.md">More</a></td>
+</tr>
+<tr>
+<td><strong>19 providers</strong></td>
+<td>Anthropic, OpenAI, Google, xAI, Groq, DeepSeek, Mistral, Bedrock, Fireworks, MiniMax, Copilot, GitHub Models, Ollama, LM Studio, OpenRouter, LLM Gateway, Vercel AI Gateway, Proxy, any OpenAI-compatible.</td>
+</tr>
+<tr>
+<td><strong>Task router</strong></td>
+<td>Per-job model assignment. Spark agents and ember agents each get their own model. <a href="docs/architecture.md">More</a></td>
+</tr>
+<tr>
+<td><strong>Code execution</strong></td>
+<td>Sandboxed Python via Anthropic's <code>code_execution</code> tool. Process data, calculations, batch tool calls.</td>
+</tr>
+<tr>
+<td><strong>User steering</strong></td>
+<td>Type while the agent works. Messages queue and arrive at the next step. <a href="docs/steering.md">More</a></td>
+</tr>
+<tr>
+<td><strong>Skills + gates</strong></td>
+<td>Installable skills for domain work. Destructive actions need confirmation. Auto mode for full autonomy.</td>
+</tr>
+<tr>
+<td><strong>4-tier intelligence</strong></td>
+<td>LSP, ts-morph, tree-sitter, regex. 33 languages. Dual LSP: Neovim bridge when the editor is open, standalone servers when it's not. <a href="docs/architecture.md">More</a></td>
+</tr>
+</table>
-### And also
+</details>
-- **Lock-in mode.** Hides agent narration during work, shows only tool activity and the final answer. Toggle via `/lock-in` or config.
-- **Embedded Neovim.** Your actual config, plugins, and LSP servers. The AI works through the same editor you use. [Deep dive →](docs/architecture.md)
-- **18 providers.** Anthropic, OpenAI, Google, xAI, Groq, DeepSeek, Mistral, Amazon Bedrock, Fireworks, GitHub Copilot, GitHub Models, Ollama, LM Studio, OpenRouter, LLM Gateway, Vercel AI Gateway, Proxy, and any OpenAI-compatible API.
-- **Task router.** Assign different models to different jobs. Spark agents (explore/investigate) and ember agents (code edits) can each use different models. You pick what goes where. [Deep dive →](docs/architecture.md)
-- **Code execution (Smithy).** Sandboxed code execution via Anthropic's `code_execution` tool. The agent can run Python to process data, do calculations, or batch tool calls programmatically.
-- **User steering.** Type while the agent works. Messages queue up and reach the agent at the next step. [Deep dive →](docs/steering.md)
-- **Skills & approval gates.** Installable skills for domain-specific work. Destructive actions require confirmation. Auto mode when you want full autonomy.
-- **4-tier code intelligence.** LSP → ts-morph → tree-sitter → regex fallback across 30 languages. Dual LSP: Neovim bridge when the editor is open, standalone servers when it's not. [Deep dive →](docs/architecture.md)
+<br/>
-<p align="center">
-  <img src="assets/main-2.png" alt="SoulForge — Multi-Agent Dispatch" width="900" />
-</p>
+<div align="center">
+  <img src="assets/main-2.png" alt="SoulForge" width="900" />
+</div>
----
+<img src="assets/separator.svg" width="100%" height="8" />
 ## How it compares
-| | SoulForge | Claude Code | Copilot CLI | Codex CLI | Aider |
-|---|---|---|---|---|---|
-| **Codebase awareness** | Live SQLite graph: PageRank, blast radius, cochange, clone detection, FTS5, unused exports | None (file reads + grep) | None | None (MCP plugins) | Tree-sitter repo map + PageRank |
-| **Cost optimization** | Soul Map + surgical reads + zero-cost compaction + shared agent cache + mix-and-match models + prompt caching | Auto-compaction | Context window management | Server-side compaction | — |
-| **Code intelligence** | 4-tier fallback: LSP → ts-morph → tree-sitter → regex. Dual LSP. 30 languages | LSP via plugins (no fallback chain) | LSP (VS Code) | MCP-based LSP | Tree-sitter AST |
-| **Multi-agent** | Parallel dispatch with shared file/tool cache and edit coordination | Subagents + Agent Teams | Subagents + Fleet | Multi-agent v2 | Single agent |
-| **Multi-tab** | Concurrent tabs with per-tab models, file claim awareness, cross-tab git coordination | — | — | — | — |
-| **Task routing** | Per-task model assignment (spark, ember, web search, verify, desloppify, compact) | Single model | Single model | Per-agent model | Single model |
-| **Compound tools** | `read` (batch + surgical), `multi_edit` (atomic), `rename_symbol`, `move_symbol`, `rename_file`, `refactor`, `project` | Rename via LSP | — | — | — |
-| **Editor** | Embedded Neovim (your config, your plugins) | No editor | No editor | No editor | No editor |
-| **Providers** | 18 + custom OpenAI-compatible | Anthropic only | Multi-model | OpenAI only | 100+ LLMs |
-| **License** | BSL 1.1 (source-available) | Proprietary | Proprietary | Apache 2.0 | Apache 2.0 |
-> *Competitor features verified as of March 29, 2026. [Let us know](https://github.com/ProxySoul/soulforge/issues) if something's changed.*
----
+<table>
+<thead>
+<tr>
+<th width="160"></th>
+<th>SoulForge</th>
+<th>Claude Code</th>
+<th>Copilot CLI</th>
+<th>Codex CLI</th>
+<th>Aider</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>Codebase awareness</strong></td>
+<td>Live SQLite graph: PageRank, blast radius, cochange, clone detection, FTS5, unused exports</td>
+<td>File reads + grep</td>
+<td>None</td>
+<td>MCP plugins</td>
+<td>Tree-sitter + PageRank</td>
+</tr>
+<tr>
+<td><strong>Cost optimization</strong></td>
+<td>Soul Map + surgical reads + instant compaction + shared agent cache + model mixing + prompt caching</td>
+<td>Auto-compaction</td>
+<td>Context window mgmt</td>
+<td>Server-side compaction</td>
+<td>-</td>
+</tr>
+<tr>
+<td><strong>Code intelligence</strong></td>
+<td>4-tier: LSP / ts-morph / tree-sitter / regex. Dual LSP. 33 langs</td>
+<td>LSP via plugins</td>
+<td>LSP (VS Code)</td>
+<td>MCP-based LSP</td>
+<td>Tree-sitter AST</td>
+</tr>
+<tr>
+<td><strong>Multi-agent</strong></td>
+<td>Parallel dispatch, shared file/tool cache, edit coordination</td>
+<td>Subagents + Teams</td>
+<td>Subagents + Fleet</td>
+<td>Multi-agent v2</td>
+<td>Single</td>
+</tr>
+<tr>
+<td><strong>Multi-tab</strong></td>
+<td>Per-tab models, file claims, cross-tab git coordination</td>
+<td>-</td>
+<td>-</td>
+<td>-</td>
+<td>-</td>
+</tr>
+<tr>
+<td><strong>Task routing</strong></td>
+<td>Per-task model (spark, ember, web search, verify, desloppify, compact)</td>
+<td>Single model</td>
+<td>Single model</td>
+<td>Per-agent model</td>
+<td>Single model</td>
+</tr>
+<tr>
+<td><strong>Compound tools</strong></td>
+<td><code>read</code> batch+surgical, <code>multi_edit</code> atomic, <code>rename_symbol</code>, <code>move_symbol</code>, <code>refactor</code>, <code>project</code></td>
+<td>Rename via LSP</td>
+<td>-</td>
+<td>-</td>
+<td>-</td>
+</tr>
+<tr>
+<td><strong>Editor</strong></td>
+<td>Embedded Neovim (your config, your plugins)</td>
+<td>No</td>
+<td>No</td>
+<td>No</td>
+<td>No</td>
+</tr>
+<tr>
+<td><strong>Providers</strong></td>
+<td>19 + custom OpenAI-compatible</td>
+<td>Anthropic only</td>
+<td>Multi-model</td>
+<td>OpenAI only</td>
+<td>100+ LLMs</td>
+</tr>
+<tr>
+<td><strong>License</strong></td>
+<td>BSL 1.1</td>
+<td>Proprietary</td>
+<td>Proprietary</td>
+<td>Apache 2.0</td>
+<td>Apache 2.0</td>
+</tr>
+</tbody>
+</table>
+<sub>Verified March 29, 2026. <a href="https://github.com/ProxySoul/soulforge/issues">Report inaccuracies.</a></sub>
+<img src="assets/separator.svg" width="100%" height="8" />
 ## Installation
-macOS and Linux. SoulForge checks for prerequisites on first launch and offers to install Neovim and Nerd Fonts if missing.
+macOS and Linux. First launch checks for prerequisites and offers to install Neovim and Nerd Fonts.
 ### Homebrew (recommended)
@@ -107,7 +246,8 @@ brew install soulforge
 ```
 <details>
-<summary><strong>Bun (global install)</strong></summary>
+<summary><strong>Bun (global)</strong></summary>
+<br/>
 ```bash
 curl -fsSL https://bun.sh/install | bash
@@ -119,8 +259,9 @@ soulforge
 <details>
 <summary><strong>Prebuilt binary</strong></summary>
+<br/>
-Download from [GitHub Releases](https://github.com/ProxySoul/soulforge/releases/latest), extract, and run the installer:
+Download from [Releases](https://github.com/ProxySoul/soulforge/releases/latest):
 ```bash
 tar xzf soulforge-*.tar.gz && cd soulforge-*/ && ./install.sh
@@ -132,15 +273,16 @@ Installs to `~/.soulforge/`, adds to PATH.
 <details>
 <summary><strong>Self-contained bundle</strong></summary>
+<br/>
-Ships everything: Neovim 0.11, ripgrep, fd, lazygit, tree-sitter grammars, Nerd Font symbols. No system dependencies.
+Ships Neovim 0.11, ripgrep, fd, lazygit, tree-sitter grammars, Nerd Font symbols. Zero system deps.
 ```bash
 git clone https://github.com/ProxySoul/soulforge.git && cd soulforge && bun install
 ./scripts/bundle.sh              # macOS ARM64
 ./scripts/bundle.sh x64          # Intel Mac
 ./scripts/bundle.sh x64 linux    # Linux x64
-./scripts/bundle.sh x64-baseline linux  # Linux x64 (older CPUs without AVX)
+./scripts/bundle.sh x64-baseline linux  # Linux x64 (older CPUs)
 ./scripts/bundle.sh arm64 linux  # Linux ARM64
 cd dist/bundle/soulforge-*/ && ./install.sh
 ```
@@ -149,6 +291,7 @@ cd dist/bundle/soulforge-*/ && ./install.sh
 <details>
 <summary><strong>Build from source</strong></summary>
+<br/>
 Requires [Bun](https://bun.sh) >= 1.0 and [Neovim](https://neovim.io) >= 0.11.
@@ -164,74 +307,87 @@ bun run build && bun link && soulforge
 ### Quick start
 ```bash
-soulforge                                  # Launch, pick a model with Ctrl+L
-soulforge --set-key anthropic sk-ant-...   # Save a key
-soulforge --headless "your prompt here"    # Non-interactive mode
+soulforge                                  # launch, pick a model with Ctrl+L
+soulforge --set-key anthropic sk-ant-...   # save a key
+soulforge --headless "your prompt here"    # non-interactive
 ```
 See [GETTING_STARTED.md](GETTING_STARTED.md) for a full walkthrough.
----
+<img src="assets/separator.svg" width="100%" height="8" />
 ## Usage
 ```bash
-soulforge                                    # Launch TUI
-soulforge --headless "prompt"               # Stream to stdout
-soulforge --headless --json "prompt"        # Structured JSON output
-soulforge --headless --chat                 # Interactive multi-turn
-soulforge --headless --model provider/model # Override model
-soulforge --headless --mode architect       # Read-only analysis
-soulforge --headless --diff "fix the bug"   # Show changed files
+soulforge                                    # TUI
+soulforge --headless "prompt"               # stream to stdout
+soulforge --headless --json "prompt"        # structured JSON
+soulforge --headless --chat                 # multi-turn
+soulforge --headless --model provider/model # override model
+soulforge --headless --mode architect       # read-only
+soulforge --headless --diff "fix the bug"   # show changed files
 ```
-| Mode | Description |
-|------|-------------|
-| `default` | Full agent with all tools |
-| `auto` | Executes immediately, no questions |
-| `architect` | Read-only analysis and review |
-| `socratic` | Guided learning through questions |
-| `challenge` | Pushes back on your assumptions |
-| `plan` | Planning mode, no code changes |
+<table>
+<thead><tr><th width="140">Mode</th><th>What it does</th></tr></thead>
+<tbody>
+<tr><td><code>default</code></td><td>Full agent, all tools</td></tr>
+<tr><td><code>auto</code></td><td>Executes immediately, no questions</td></tr>
+<tr><td><code>architect</code></td><td>Read-only analysis and review</td></tr>
+<tr><td><code>socratic</code></td><td>Guided learning through questions</td></tr>
+<tr><td><code>challenge</code></td><td>Pushes back on assumptions</td></tr>
+<tr><td><code>plan</code></td><td>Planning only, no code changes</td></tr>
+</tbody>
+</table>
 [Full CLI reference](docs/headless.md)
----
+<img src="assets/separator.svg" width="100%" height="8" />
 ## Providers
-| Provider | Setup |
-|----------|-------|
-| [**LLM Gateway**](https://llmgateway.io/?ref=6tjJR2H3X4E9RmVQiQwK) | `LLM_GATEWAY_API_KEY` |
-| [**Anthropic**](https://console.anthropic.com/) | `ANTHROPIC_API_KEY` |
-| [**OpenAI**](https://platform.openai.com/) | `OPENAI_API_KEY` |
-| [**Google**](https://aistudio.google.com/) | `GOOGLE_GENERATIVE_AI_API_KEY` |
-| [**xAI**](https://console.x.ai/) | `XAI_API_KEY` |
-| [**Groq**](https://console.groq.com/) | `GROQ_API_KEY` |
-| [**DeepSeek**](https://platform.deepseek.com/) | `DEEPSEEK_API_KEY` |
-| [**Mistral**](https://console.mistral.ai/) | `MISTRAL_API_KEY` |
-| [**Amazon Bedrock**](https://aws.amazon.com/bedrock/) | `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION` |
-| [**Fireworks**](https://fireworks.ai/) | `FIREWORKS_API_KEY` |
-| [**GitHub Copilot**](https://github.com/features/copilot) | OAuth token from IDE ([setup](docs/copilot-provider.md)) |
-| [**GitHub Models**](https://github.com/marketplace/models) | `GITHUB_MODELS_API_KEY` (PAT with `models:read`) |
-| [**Ollama**](https://ollama.ai) | Auto-detected |
-| [**LM Studio**](https://lmstudio.ai) | Auto-detected |
-| [**OpenRouter**](https://openrouter.ai) | `OPENROUTER_API_KEY` |
-| [**Vercel AI Gateway**](https://vercel.com/ai-gateway) | `AI_GATEWAY_API_KEY` |
-| [**Proxy**](https://github.com/router-for-me/CLIProxyAPI) | `PROXY_API_KEY` |
-| **Custom** | Any OpenAI-compatible API |
+<table>
+<thead><tr><th width="200">Provider</th><th>Setup</th></tr></thead>
+<tbody>
+<tr><td><a href="https://llmgateway.io/?ref=6tjJR2H3X4E9RmVQiQwK"><strong>LLM Gateway</strong></a></td><td><code>LLM_GATEWAY_API_KEY</code></td></tr>
+<tr><td><a href="https://console.anthropic.com/"><strong>Anthropic</strong></a></td><td><code>ANTHROPIC_API_KEY</code></td></tr>
+<tr><td><a href="https://platform.openai.com/"><strong>OpenAI</strong></a></td><td><code>OPENAI_API_KEY</code></td></tr>
+<tr><td><a href="https://aistudio.google.com/"><strong>Google</strong></a></td><td><code>GOOGLE_GENERATIVE_AI_API_KEY</code></td></tr>
+<tr><td><a href="https://console.x.ai/"><strong>xAI</strong></a></td><td><code>XAI_API_KEY</code></td></tr>
+<tr><td><a href="https://console.groq.com/"><strong>Groq</strong></a></td><td><code>GROQ_API_KEY</code></td></tr>
+<tr><td><a href="https://platform.deepseek.com/"><strong>DeepSeek</strong></a></td><td><code>DEEPSEEK_API_KEY</code></td></tr>
+<tr><td><a href="https://console.mistral.ai/"><strong>Mistral</strong></a></td><td><code>MISTRAL_API_KEY</code></td></tr>
+<tr><td><a href="https://aws.amazon.com/bedrock/"><strong>Amazon Bedrock</strong></a></td><td><code>AWS_ACCESS_KEY_ID</code> + <code>AWS_SECRET_ACCESS_KEY</code> + <code>AWS_REGION</code></td></tr>
+<tr><td><a href="https://fireworks.ai/"><strong>Fireworks</strong></a></td><td><code>FIREWORKS_API_KEY</code></td></tr>
+<tr><td><a href="https://platform.minimaxi.com/"><strong>MiniMax</strong></a></td><td><code>MINIMAX_API_KEY</code></td></tr>
+<tr><td><a href="https://github.com/features/copilot"><strong>GitHub Copilot</strong></a></td><td>OAuth token from IDE (<a href="docs/copilot-provider.md">setup</a>)</td></tr>
+<tr><td><a href="https://github.com/marketplace/models"><strong>GitHub Models</strong></a></td><td><code>GITHUB_MODELS_API_KEY</code> (PAT with <code>models:read</code>)</td></tr>
+<tr><td><a href="https://ollama.ai"><strong>Ollama</strong></a></td><td>Auto-detected</td></tr>
+<tr><td><a href="https://lmstudio.ai"><strong>LM Studio</strong></a></td><td>Auto-detected</td></tr>
+<tr><td><a href="https://openrouter.ai"><strong>OpenRouter</strong></a></td><td><code>OPENROUTER_API_KEY</code></td></tr>
+<tr><td><a href="https://vercel.com/ai-gateway"><strong>Vercel AI Gateway</strong></a></td><td><code>AI_GATEWAY_API_KEY</code></td></tr>
+<tr><td><a href="https://github.com/router-for-me/CLIProxyAPI"><strong>Proxy</strong></a></td><td><code>PROXY_API_KEY</code></td></tr>
+<tr><td><strong>Custom</strong></td><td>Any OpenAI-compatible API</td></tr>
+</tbody>
+</table>
-**Amazon Bedrock**: Uses AWS IAM credentials — set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` (defaults to `us-east-1`). Supports `AWS_SESSION_TOKEN` for temporary credentials.
+<details>
+<summary><strong>Provider notes</strong></summary>
+<br/>
+**Amazon Bedrock** uses AWS IAM credentials. Set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` (defaults `us-east-1`). Supports `AWS_SESSION_TOKEN` for temporary creds.
+**GitHub Copilot**: sign in via IDE, copy `oauth_token` from `~/.config/github-copilot/apps.json`, save with `/keys` or `--set-key copilot`. [Full guide](docs/copilot-provider.md).
-**GitHub Copilot**: Sign in via your IDE (VS Code, JetBrains), copy `oauth_token` from `~/.config/github-copilot/apps.json`, save with `/keys` or `--set-key copilot`. [Full setup guide](docs/copilot-provider.md).
+**GitHub Models**: free playground API, per-token billing. Fine-grained PAT with `models:read`. Lower rate limits than Copilot.
-**GitHub Models**: Free playground API with per-token billing. Create a fine-grained PAT with `models:read` scope. Lower rate limits than Copilot.
+**Ollama**: auto-detected at `localhost:11434`. Override with `OLLAMA_HOST`.
-**Ollama**: Auto-detected at `localhost:11434`. Override with `OLLAMA_HOST=http://host:port`.
+**LM Studio**: auto-detected at `localhost:1234`. Override with `LM_STUDIO_URL`. Optional auth via `LM_API_TOKEN`.
-**LM Studio**: Auto-detected at `localhost:1234`. Uses the [REST API v0](https://lmstudio.ai/docs/developer/rest/endpoints) for rich model data (context length, type filtering). Override with `LM_STUDIO_URL=http://host:port`. Optional auth: set `LM_API_TOKEN` if you've enabled authentication in LM Studio.
+</details>
-Add custom providers in config, no code changes:
+Custom providers via config:
 ```json
 {
@@ -245,9 +401,9 @@ Add custom providers in config, no code changes:
 }
 ```
-[Custom providers](docs/headless.md#custom-providers) · [Provider options](docs/provider-options.md)
+[Custom providers](docs/headless.md#custom-providers) / [Provider options](docs/provider-options.md)
----
+<img src="assets/separator.svg" width="100%" height="8" />
 ## Configuration
@@ -269,62 +425,76 @@ Layered: global (`~/.soulforge/config.json`) + project (`.soulforge/config.json`
 }
 ```
-**Project instructions:** Drop a `SOULFORGE.md` in your project root with conventions, architecture notes, preferences. Also supports `CLAUDE.md`, `.cursorrules`, `AGENTS.md`, and others. Toggle via `/instructions`.
+Drop a `SOULFORGE.md` in your project root for conventions, architecture notes, preferences. Also reads `CLAUDE.md`, `.cursorrules`, `AGENTS.md`. Toggle via `/instructions`.
 See [GETTING_STARTED.md](GETTING_STARTED.md) for the full config reference.
----
+<img src="assets/separator.svg" width="100%" height="8" />
 ## Documentation
-| | |
-|---|---|
-| [Architecture](docs/architecture.md) | System overview, intelligence router, agent system, tool design |
-| [Repo Map](docs/repo-map.md) | PageRank, cochange, blast radius, clone detection, language support |
-| [Agent Bus](docs/agent-bus.md) | Multi-agent coordination, shared cache, edit ownership |
-| [Compaction](docs/compaction.md) | V1/V2 context management, working state extraction |
-| [Compound Tools](docs/compound-tools.md) | read, multi_edit, rename_symbol, move_symbol, refactor, project |
-| [Project Tool](docs/project-tool.md) | 23 ecosystems, pre-commit checks, monorepo discovery |
-| [Headless Mode](docs/headless.md) | CLI flags, JSON/JSONL output, CI/CD integration |
-| [Commands](docs/commands-reference.md) | All 86 slash commands |
-| [Steering](docs/steering.md) | Mid-stream user input |
-| [Provider Options](docs/provider-options.md) | Thinking modes, context management |
-| [Copilot Provider](docs/copilot-provider.md) | Setup, legal review |
-| [Cross-Tab Coordination](docs/cross-tab-coordination.md) | Multi-tab file claims, git coordination |
-| [Themes](docs/themes.md) | 24 themes, custom themes, hot reload |
-| [Prompt System](docs/prompt-system.md) | Per-family prompts, mode overlays |
-| [Getting Started](GETTING_STARTED.md) | First launch walkthrough |
-| [Contributing](CONTRIBUTING.md) | Dev setup, PR guidelines |
----
+<table>
+<thead><tr><th width="240">Topic</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td colspan="2"><strong>Core</strong></td></tr>
+<tr><td><a href="docs/architecture.md">Architecture</a></td><td>System overview, intelligence router, agent system, tool design</td></tr>
+<tr><td><a href="docs/repo-map.md">Repo Map</a></td><td>PageRank, cochange, blast radius, clone detection, language support</td></tr>
+<tr><td><a href="docs/agent-bus.md">Agent Bus</a></td><td>Multi-agent coordination, shared cache, edit ownership</td></tr>
+<tr><td><a href="docs/compaction.md">Compaction</a></td><td>Context management, working state extraction</td></tr>
+<tr><td colspan="2"><strong>Tools</strong></td></tr>
+<tr><td><a href="docs/compound-tools.md">Compound Tools</a></td><td>read, multi_edit, rename_symbol, move_symbol, refactor, project</td></tr>
+<tr><td><a href="docs/project-tool.md">Project Tool</a></td><td>25+ ecosystems, pre-commit checks, monorepo discovery</td></tr>
+<tr><td><a href="docs/commands-reference.md">Commands</a></td><td>All 86 slash commands</td></tr>
+<tr><td colspan="2"><strong>Usage</strong></td></tr>
+<tr><td><a href="docs/headless.md">Headless Mode</a></td><td>CLI flags, JSON/JSONL output, CI/CD integration</td></tr>
+<tr><td><a href="docs/steering.md">Steering</a></td><td>Mid-stream user input</td></tr>
+<tr><td><a href="docs/cross-tab-coordination.md">Cross-Tab Coordination</a></td><td>Multi-tab file claims, git coordination</td></tr>
+<tr><td colspan="2"><strong>Config</strong></td></tr>
+<tr><td><a href="docs/provider-options.md">Provider Options</a></td><td>Thinking modes, context management</td></tr>
+<tr><td><a href="docs/themes.md">Themes</a></td><td>24 themes, custom themes, hot reload</td></tr>
+<tr><td><a href="docs/prompt-system.md">Prompt System</a></td><td>Per-family prompts, mode overlays</td></tr>
+<tr><td><a href="docs/copilot-provider.md">Copilot Provider</a></td><td>Setup, legal review</td></tr>
+<tr><td colspan="2"><strong>Start</strong></td></tr>
+<tr><td><a href="GETTING_STARTED.md">Getting Started</a></td><td>First launch walkthrough</td></tr>
+<tr><td><a href="CONTRIBUTING.md">Contributing</a></td><td>Dev setup, PR guidelines</td></tr>
+</tbody>
+</table>
+<img src="assets/separator.svg" width="100%" height="8" />
 ## Roadmap
-The intelligence layer is being extracted into reusable packages:
-- **`@soulforge/intelligence`**: graph intelligence, tools, and agent orchestration as an importable library
-- **`@soulforge/mcp`**: expose Soul Map tools as MCP servers for Claude Code, Cursor, Copilot, or any MCP client
-- **`sf --headless`**: shipped. Non-interactive mode for CI/CD, automation, and scripting. [Docs →](docs/headless.md)
+Extracting the intelligence layer into reusable packages:
-**In progress:** MCP support · repo map visualization · GitHub CLI integration · dispatch worktrees · [ACP support](https://agentclientprotocol.com/)
+- **`@soulforge/intelligence`** : graph intelligence, tools, agent orchestration as a library
+- **`@soulforge/mcp`** : Soul Map tools as MCP servers for Claude Code, Cursor, Copilot, any MCP client
+- **`sf --headless`** : shipped. [Docs](docs/headless.md)
-**Planned:** monorepo graph support · benchmarks · orchestrated workflows (planner → TDD → reviewer → security)
+<table>
+<thead><tr><th width="120">Status</th><th>Item</th></tr></thead>
+<tbody>
+<tr><td><strong>In progress</strong></td><td>MCP support, repo map visualization, GitHub CLI integration, dispatch worktrees, <a href="https://agentclientprotocol.com/">ACP</a></td></tr>
+<tr><td><strong>Planned</strong></td><td>Monorepo graph support, benchmarks, orchestrated workflows (planner &gt; TDD &gt; reviewer &gt; security)</td></tr>
+</tbody>
+</table>
----
+<img src="assets/separator.svg" width="100%" height="8" />
 ## Inspirations
-- **[Aider](https://github.com/Aider-AI/aider)**: tree-sitter repo maps with PageRank. SoulForge adds cochange analysis, blast radius, clone detection, and live updates.
-- **[Everything Claude Code](https://github.com/affaan-m/everything-claude-code)**: enforce behavior with code, not prompts. Our schema validation, pre-commit gates, and auto-enrichment patterns come from this thinking.
-- **[Vercel AI SDK](https://sdk.vercel.ai)**: the multi-provider abstraction that makes 12 providers possible.
-- **[Neovim](https://neovim.io)**: embedded via msgpack-RPC. Your config and muscle memory shouldn't be a compromise.
+- **[Aider](https://github.com/Aider-AI/aider)** : tree-sitter repo maps with PageRank. SoulForge adds cochange, blast radius, clone detection, live updates.
+- **[Everything Claude Code](https://github.com/affaan-m/everything-claude-code)** : enforce behavior with code, not prompts.
+- **[Vercel AI SDK](https://sdk.vercel.ai)** : multi-provider abstraction.
+- **[Neovim](https://neovim.io)** : embedded via msgpack-RPC. Your config and muscle memory intact.
----
+<img src="assets/separator.svg" width="100%" height="8" />
 ## License
 [Business Source License 1.1](LICENSE). Free for personal and internal use. Commercial use requires a [commercial license](COMMERCIAL_LICENSE.md). Converts to Apache 2.0 on March 15, 2030.
-<p align="center">
-  <sub>Built with care by <a href="https://github.com/proxysoul">proxySoul</a></sub>
-</p>
+<br/>
+<div align="center">
+<sub>Built by <a href="https://github.com/proxysoul">proxySoul</a></sub>
+</div>