savant-code 0.0.19 → 0.0.20

package/README.md

@@ -1,550 +1,381 @@
-<!-- markdownlint-disable MD041 -->
-<!-- markdownlint-disable MD033 -->
-<div align="center">
-
-<img src="assets/banner.png" alt="Savant-Code — Multi-Agent AI Coding Assistant" width="850" />
-
-**A terminal-native AI coding assistant that audits every change before it
-touches your repo.**
-
-Built with TypeScript/Bun, governed by the ECHO Protocol, and designed for
-local-first use with Ollama.
-
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-%23000000?style=flat-square&logo=typescript&logoColor=%2300fbff)](https://www.typescriptlang.org/)[![Bun](https://img.shields.io/badge/Bun-1.3.14-%23000000?style=flat-square&logo=bun&logoColor=%2300fbff)](https://bun.sh/)[![React](https://img.shields.io/badge/React-19-%23000000?style=flat-square&logo=react&logoColor=%2300fbff)](https://react.dev/)[![OpenTUI](https://img.shields.io/badge/OpenTUI-0.2.2-%23000000?style=flat-square&logo=github&logoColor=%2300fbff)](https://github.com/anomalyco/opentui)[![ECHO](https://img.shields.io/badge/ECHO-v0.2.0-%23000000?style=flat-square&logo=github&logoColor=%2300fbff)](ECHO.md)[![License](https://img.shields.io/badge/License-Apache_2.0-%23000000?style=flat-square&logo=apache&logoColor=%2300fbff)](LICENSE)[![Release](https://img.shields.io/badge/Release-v0.0.18-%23000000?style=flat-square&logo=semver&logoColor=%2300fbff)](CHANGELOG.md)
-
-</div>
-
-> **v0.0.18** — Hotfix release: fixes the standalone npm binary footer showing `v0.0.0`,
-> synchronizes release metadata, and rebuilds the official binary artifacts so model
-> selection and routing use the published provider catalog consistently. It carries
-> forward Checkpoint & Rewind, provider setup, ECHO enforcement, and the prior
-> quality and build-hygiene work.
-
----
-
-## Get Started in 30 Seconds
-
-```bash
-# Install the CLI
-npm install -g savant-code
-
-# Run it. If Ollama is running, it will auto-detect and use it.
-savant-code
-```
-
-_A terminal demo video is not yet available; the landing page and CLI source
-links below describe the currently verified workflow._
-
-No Ollama yet?
-
-```bash
-# macOS / Linux
-curl -fsSL https://ollama.com/install.sh | sh
-ollama serve
-
-# Windows: https://ollama.com/download/windows
-```
-
-Then run `savant-code` again, or type `/health` inside the chat to verify the
-connection.
-
-If Ollama is not running, configure a hosted provider before sending a prompt:
-
-```text
-/provider opencode-go
-```
-
-You can also enter `/provider` to choose from the interactive picker. Paste the
-key into the masked prompt; it is stored globally and is never added to chat
-history. The supported hosted providers are:
-
-| Provider | Command | Environment variable | Notes |
-| --- | --- | --- | --- |
-| Ollama | automatic detection | — | Local inference; no API key required |
-| OpenRouter direct | `DIRECT_PROVIDER=openrouter` | `OR_MASTER_KEY`, `OPENROUTER_API_KEY`, or `INFERENCE_API_KEY` | Direct mode; master key, regular key, then inference key precedence |
-| OpenCode Go | `/provider opencode-go` | `OPENCODE_GO_API_KEY` | Default hosted provider; MiMo 2.5 default |
-| TokenRouter | `/provider tokenrouter` | `TOKENROUTER_API_KEY` | Multi-provider gateway |
-| NVIDIA NIM | `/provider nvidia` | `NVIDIA_API_KEY` | NVIDIA-hosted inference |
-| CommandCode | `/provider commandcode` | `COMMAND_CODE_API_KEY` | OpenAI-compatible hosted inference |
-
-The key is persisted at
-`C:\\Users\\<username>\\.savant-code\\credentials.json` on Windows or
-`~/.savant-code/credentials.json` on macOS/Linux. Environment variables take
-precedence over saved credentials. For automation, set one provider key before
-launching Savant-Code:
-
-```powershell
-# PowerShell — choose one provider key
-$env:OPENCODE_GO_API_KEY = "your-key"
-# $env:TOKENROUTER_API_KEY = "your-key"
-# $env:NVIDIA_API_KEY = "your-key"
-# $env:COMMAND_CODE_API_KEY = "your-key"
-savant-code
-```
-
-```cmd
-:: Command Prompt — choose one provider key
-set OPENCODE_GO_API_KEY=your-key
-:: set TOKENROUTER_API_KEY=your-key
-:: set NVIDIA_API_KEY=your-key
-:: set COMMAND_CODE_API_KEY=your-key
-savant-code
-```
-
-```bash
-# macOS/Linux — choose one provider key
-export OPENCODE_GO_API_KEY="your-key"
-# export TOKENROUTER_API_KEY="your-key"
-# export NVIDIA_API_KEY="your-key"
-# export COMMAND_CODE_API_KEY="your-key"
-savant-code
-```
-
-### OpenRouter direct mode
-
-To bypass the Savant Code backend and route inference directly to OpenRouter, set:
-
-```bash
-export DIRECT_PROVIDER=openrouter
-export INFERENCE_BASE_URL=https://openrouter.ai/api/v1
-```
-
-OpenRouter key resolution is ordered as follows:
-
-1. `OR_MASTER_KEY` — exchanges for a regular key through OpenRouter `/api/v1/keys`.
-2. `OPENROUTER_API_KEY` — uses an existing regular OpenRouter key directly.
-3. `INFERENCE_API_KEY` — uses the SDK-specific inference key.
-
-Advanced Cloudflare Workers AI integrations use `CLOUDFLARE_API_TOKEN` together
-with `CLOUDFLARE_ACCOUNT_ID`. Ordinary CLI users should use `/provider` or one
-of the four provider-specific keys above. Do not create a project-local `.env`
-file or edit `credentials.json` manually.
-
----
-
-## Overview
-
-Savant-Code is a TypeScript monorepo that builds and ships the terminal-native
-AI coding assistant **Savant Code** and the public
-[`@savant-code/sdk`](https://www.npmjs.com/package/@savant-code/sdk). The CLI
-provides multi-agent orchestration, custom skills, MCP tool discovery, mode
-switching (`EDIT` / `ANALYZE` / `SCAFFOLD`), and local-first Ollama support. The
-SDK, agent runtime, multi-agent orchestration engine, tool layer, and LLM
-provider shims are shared so both surfaces ship from one codebase.
-
-The whole project ships under [ECHO Protocol v0.2.0](ECHO.md) — the same 15-law
-agent discipline that governs the Savant ecosystem. Every change goes through
-the RED → GREEN → AUDIT → SELF-CORRECT → COMPLETE Perfection Loop FSM, with a
-hard 10-iteration cap and a 10% Levenshtein change-cap per pass.
-
----
-
-## Key Technologies
-
-| Layer           | Tech                              | Version                                           |
-| --------------- | --------------------------------- | ------------------------------------------------- |
-| Runtime         | Bun                               | 1.3.14 (engines `>=1.3.11`)                       |
-| Language        | TypeScript                        | 5.5.4 (`strict: true`, `noImplicitReturns: true`) |
-| TUI             | OpenTUI + React 19                | `@opentui/core` 0.2.2, `react` ^19.0.0            |
-| State           | Zustand + Immer                   | zustand ^5.0.8, immer ^10.1.3                     |
-| Validation      | Zod                               | ^4.2.1                                            |
-| LLM SDK         | Vercel AI SDK                     | `ai` ^5.0.52 + `@ai-sdk/anthropic` 2.0.50         |
-| MCP             | Model Context Protocol            | `@modelcontextprotocol/sdk` ^1.18.2               |
-| Code parsing    | tree-sitter (WASM)                | `@vscode/tree-sitter-wasm` 0.1.4                  |
-| HTTP / WS       | ws, node-fetch, custom SDK client | ws ^8.18.0                                        |
-| Package manager | Bun workspaces (hoisted)          | `bunfig.toml` `[install] linker = "hoisted"`      |
-
----
-
-## Features
-
-### CLI (`@savant-code/cli`)
-
-- **Multi-agent orchestration** — 9 specialized agents coordinate via ECHO
-  Protocol: Detective finds issues, Forge implements, Verifier audits, Recorder
-  manages FIDs, Thinker reasons, Scout explores, Researcher investigates, Scribe
-  documents.
-- **Thinker with sequential thinking** — the Thinker agent accumulates stacked
-  reasoning steps via `sequentialthinking`, converges to a typed non-null
-  `FinalArtifact` (status/synthesis/payload/metrics/thoughts), and never returns
-  a null or empty result.
-- **Native tool-call hardening** — fail-closed streaming boundary for
-  incomplete/malformed/truncated tool calls; stale-fragment replacement for
-  placeholder arguments; permissive coercion of stringified numbers/booleans
-  before strict Zod validation.
-- **Tool permission boundary** — strict allowlist-based tool provisioning via
-  `filterToolSet`; restricted agents (Thinker, Scout) never receive parent-only
-  tools; executor authorization unchanged.
-- **`/init` command** — scaffolds
-  `.agents/types/{agent-definition,tools,util-types}.ts` and a starter
-  `knowledge.md`.
-- **Slash commands** — `/new`, `/history`, `/bash`, `/goal`, `/loop`,
-  `/feedback`, `/rewind`, `/theme:toggle`, `/login`, `/logout`, `/exit`, plus
-  agent-specific commands.
-- **Provider setup** — `/provider` opens an interactive dropdown picker showing
-  all providers with ✓/✗ configuration status. Select a provider to enter its
-  API key (masked input). Keys stored in local `credentials.json`.
-- **Telemetry controls** — `/telemetry status|enable|disable` toggles remote
-  analytics and error reporting. Remote analytics is enabled by default in the
-  main CLI but remains user-disableable; local logs remain available when it is
-  disabled. Contextual ads are separate: ads are disabled by default in the
-  main CLI and can be controlled independently where available. Savant-Free is
-  the separate ad-supported product surface.
-- **`@filename` and `@AgentName` mentions** — file and agent mentions with
-  inline autocomplete.
-- **Bash mode** — `!command` or `/bash` to run shell commands inline (with
-  confirmation).
-- **Permission and sandbox controls** — `--permission-mode safe|prompt|unsafe`
-  sets the startup policy, while `/permissions` (aliases `/sandbox` and
-  `/safety`) shows or changes it during a session. `safe` denies risky tools;
-  `prompt` currently also denies risky tools because interactive confirmations
-  are not yet implemented, and `unsafe` allows them
-  explicitly. Use `unsafe` only when you understand the command risk.
-- **Goal loop** — `/goal` sets a goal condition; `/loop <cadence>` schedules
-  recurring prompt execution (e.g., `/loop 5m check build status`). The loop
-  scheduler manages cadence, run counts, and convergence detection.
-- **Structured planning and review** — `/interview` turns an underspecified
-  request into a structured specification, `/plan` creates an implementation
-  plan, and `/review` opens a focused code-review workflow.
-- **In-chat verification** — `/verify` runs the four supported core workspace
-  typechecks, or target one with `/verify sdk`, `/verify common`,
-  `/verify agent-runtime`, or `/verify cli`. `/diagnostics` reports local
-  process/resource information.
-- **Conversation utilities** — `/copy` (aliases `/copy-chat` and `/export`) copies
-  the full conversation, while `/image` (aliases `/img` and `/attach`) attaches
-  an image when the selected provider supports multimodal input.
-- **Agent publishing** — `/publish` opens the agent publishing flow for
-  templates with the required publisher metadata. It requires the Savant Code
-  backend rather than direct-provider mode.
-- **Mode switching** — `EDIT` / `ANALYZE` / `SCAFFOLD` execution-scope modes,
-  togglable at runtime via UI.
-- **Streaming & cancellation** — token-by-token SSE streaming with mid-stream
-  cancellation, retry-with-backoff, and subagent streaming for parallel work.
-- **Knowledge files** — project-level `knowledge.md` plus per-user home-dir
-  knowledge, auto-loaded into agent context.
-- **Skills** — OpenClaw-format `SKILL.md` files discovered at startup, schemas
-  sent to the LLM, available as native tools.
-- **MCP tools** — Model Context Protocol servers discovered at startup, schemas
-  published to the LLM API.
-- **Context compaction** — 4-layer progressive auto-compaction: L0 (summarize
-  old turns), L1 (compress tool results), L2 (prune stale context), L3
-  (aggressive reduction). Preserves critical context while reducing token usage.
-- **Context window resolution** — gateway models (e.g. `opencode-go/mimo-v2.5`)
-  resolve their real context length from the OpenRouter catalog at runtime.
-- **Universal copy buttons** — hover-to-copy on code blocks, tool outputs, and
-  file diffs throughout the TUI.
-- **Gateway providers** — TokenRouter, NVIDIA NIM, OpenCode Go, CommandCode, and
-  Cloudflare Workers AI via `@savant-code/llm-providers`.
-- **Default model** — MiMo 2.5 via OpenCode Go (configurable via `/model`).
-- **Theming** — light/dark toggle (`/theme:toggle`), Neon Slate aesthetic.
-- **Sidebar folding** — right-sidebar sections and FID cards start collapsed
-  for a compact first render; click to expand.
-- **Full command surface** — the primary slash-command families are documented
-  in the reference below; advanced commands remain available through the
-  registry and autocomplete.
-- **Checkpoint & Rewind** — one persistent checkpoint per user turn records the
-  pre-edit content of every file first touched (including subagent writes) plus
-  the conversation boundary; `/rewind` opens a picker to restore **code only**,
-  **conversation only**, **both**, or **fork a new session** from an earlier
-  turn — no git required. Retention is bounded to the most recent 20 turns,
-  and terminal side effects are never rewound.
-
-### SDK (`@savant-code/sdk`)
-
-- **`SavantCodeClient` class** — single entry point for running agents from any
-  Node.js / Bun / browser app.
-- **Streaming events** — `handleEvent` callback receives `RunState` updates,
-  tool calls, file diffs, and final output.
-- **Custom agents** — pass `agentDefinitions: AgentDefinition[]` to override
-  defaults.
-- **Custom tools** — pass `customToolDefinitions` to extend the tool registry.
-- **Cancellation** — `AbortSignal` propagates through subagent streams.
-- **Checkpoint API** — the persistent checkpoint store (`openTurn`,
-  `captureSnapshot`, `closeTurn`, `listTurns`, `restoreTurn`, `forkFrom`) is
-  re-exported from the SDK, so hosts can checkpoint and rewind any run;
-  `checkpointDir`/`checkpointTurnId` run options thread the turn boundary into
-  subagent writes.
-
-### Agent Runtime (`@savant-code/agent-runtime`)
-
-- **LLM-agnostic** — calls any provider registered with
-  `@savant-code/llm-providers` (OpenAI-compatible chat, Anthropic, etc.).
-- **Multi-step loop** — model decides tool → tool executes → result fed back →
-  repeat until `end_turn` or budget exhausted.
-- **Tool registry** — built-in (`read_files`, `write_file`,
-  `run_terminal_command`, `code_search`, `web_search`, `spawn_agents_inline`,
-  …) + custom + MCP.
-- **Cost aggregation** — per-call token counts and USD cost estimates surfaced
-  in `RunState`.
-- **Turn checkpoints** — the write-gate in `executeToolCall` captures
-  pre-edit content before `write_file`/`str_replace`/`apply_patch` dispatch;
-  subagent writes inherit the parent turn via spawn context.
-
-### ECHO Protocol Integration
-
-- **9 specialized agents** — Orchestrator, Detective, Forge, Verifier, Recorder,
-  Thinker, Scout, Researcher, Scribe
-- **FID-Bound Execution** — Code is never written until the FID converges
-- **Perfection Loop FSM** — RED → GREEN → AUDIT → SELF-CORRECT → COMPLETE
-- **Separation of Duties** — The agent that writes code cannot verify it
-- **15 Laws** — 4 immutable process + 11 extended code laws
-
----
-
-## Repo Map
-
-<!-- markdownlint-disable MD013 MD060 -->
-
-| Workspace                 | Package                      | Purpose                                                           |
-| ------------------------- | ---------------------------- | ----------------------------------------------------------------- |
-| `agents/`                 | `@savant-code/agents`        | Public agent definitions shipped with the CLI                     |
-| `cli/`                    | `@savant-code/cli`           | CLI source — UI, commands, state, hooks, OpenTUI/React components |
-| `common/`                 | `@savant-code/common`        | Shared types, tool definitions, utilities                         |
-| `evals/`                  | `@savant-code/evals`         | ECHO-native benchmark v2 runner + legacy eval fixtures            |
-| `savant-free/`            | `@savant-code/savant-free`   | Private/pre-release free/ad-supported variant; local binary + E2E support |
-| `packages/agent-runtime/` | `@savant-code/agent-runtime` | Agent loop, tool executor, LLM API integration                    |
-| `packages/code-map/`      | `@savant-code/code-map`      | tree-sitter code indexing, language detection                     |
-| `packages/database/`      | `@savant-code/database`      | Database abstraction layer                                        |
-| `packages/llm-providers/` | `@savant-code/llm-providers` | Public LLM provider shims                                         |
-| `sdk/`                    | `@savant-code/sdk`           | Public SDK — `SavantCodeClient`, types, build + verify scripts    |
-| `scripts/tmux/`           | `@savant-code/tmux`          | tmux CLI helpers used in interactive test runs                    |
-
-<!-- markdownlint-enable MD013 MD060 -->
-
----
-
-## Quick Start
-
-### 1. Clone and Install
-
-```bash
-git clone https://github.com/savant0x/savant-code.git
-cd savant-code
-bun install
-```
-
-### 2. Run the CLI (development)
-
-```bash
-# Run the CLI in dev mode
-bun run dev
-
-# Or run with a specific permission mode
-bun run dev -- --permission-mode safe
-```
-
-### 3. Build for Release
-
-```bash
-# Build the SDK
-bun run build:sdk
-
-# Build the CLI binary from the CLI workspace
-bun run --cwd=cli build:binary
-```
-
-### 4. Use the SDK
-
-```ts
-import { SavantCodeClient } from '@savant-code/sdk'
-
-const client = new SavantCodeClient({
-  apiKey: process.env.SAVANT_CODE_API_KEY,
-  cwd: '/path/to/your/project',
-  onError: (err) => console.error('Savant-Code error:', err.message),
-})
-
-const result = await client.run({
-  agent: 'savant',
-  prompt: 'Add error handling to all API endpoints',
-  handleEvent: (event) => console.log('Progress', event),
-})
-```
-
-### 5. End-User Install
-
-```bash
-# npm
-npm install -g savant-code
-```
-
-### 6. Use with local Ollama (zero API key)
-
-If you have [Ollama](https://ollama.com/) installed and running, Savant Code
-auto-detects it on first launch and routes inference to your local daemon — no
-API key, no account, no prompts.
-
-```bash
-# Start Ollama in the background, then run the CLI
-ollama serve
-savant-code
-```
-
-Run `/health` inside the chat to verify the Ollama connection, available local
-models, and current permission mode.
-
-### Configure a hosted provider key
-
-If Ollama is not running, Savant-Code needs a provider API key for the selected
-gateway model. Use `/provider` for the interactive picker or choose one directly:
-
-```text
-/provider opencode-go
-/provider tokenrouter
-/provider nvidia
-/provider commandcode
-```
-
-The supported environment variables are `OPENCODE_GO_API_KEY`,
-`TOKENROUTER_API_KEY`, `NVIDIA_API_KEY`, and `COMMAND_CODE_API_KEY`. The key
-prompt is masked and stores the key globally in the Savant-Code config
-`credentials.json`; it is not added to chat history. Shell environment variables
-take precedence over stored keys, so CI and managed environments can configure
-providers without using local persistence. Advanced direct-provider integrations
-may use `INFERENCE_BASE_URL` and `INFERENCE_API_KEY`; OpenRouter can use
-`OPENROUTER_API_KEY` or `SAVANT_CODE_BYOK_OPENROUTER`.
-
----
-
-## CLI Commands
-
-<!-- markdownlint-disable MD013 MD060 -->
-
-| Command                           | What it does                     |
-| --------------------------------- | -------------------------------- |
-| `bun run dev`                     | Launch CLI in dev mode           |
-| `bun run build:sdk`               | Build the SDK for npm publish    |
-| `bun run --cwd=cli build:binary`  | Build the CLI binary from `cli/` |
-| `bun run ci`                      | Build SDK and release artifacts  |
-| `bun test`                        | Run the test suite               |
-| `bun x tsc --noEmit`              | Type check                       |
-| `bun x eslint . --max-warnings 0` | Lint                             |
-
-<!-- markdownlint-enable MD013 MD060 -->
-
----
-
-## Slash Command Reference
-
-Commands can be entered with `/`; aliases are shown in parentheses. Availability
-can differ in Savant-Free mode, which intentionally removes paid/backend-only
-commands.
-
-| Command | Purpose |
-| --- | --- |
-| `/help` (`/h`, `/?`) | Show command help and tips |
-| `/new` (`/clear`, `/reset`) | Start a fresh chat; optional text starts the first prompt |
-| `/history` (`/chats`) | Browse and resume previous conversations |
-| `/copy` (`/export`) | Copy the complete conversation |
-| `/interview` | Turn an idea into a structured specification |
-| `/plan` | Create an implementation plan |
-| `/review` | Review code changes |
-| `/goal` (`/g`) | Iterate until a verifiable goal is satisfied |
-| `/loop` (`/repeat`) | Run a prompt on a recurring cadence; use `stop` or `status` |
-| `/verify` (`/typecheck`) | Run the four supported core workspace typechecks, all or one selected |
-| `/permissions` (`/sandbox`, `/safety`) | View or set `safe`, `prompt`, or `unsafe` tool policy |
-| `/rewind` (`/undo`, `/checkpoint`) | Restore a previous turn’s files and/or conversation |
-| `/health` (`/status`, `/check`) | Check Ollama, provider mode, model, and permission status |
-| `/diagnostics` (`/diag`, `/processes`) | Show local process and resource diagnostics |
-| `/provider` | Configure a hosted provider key with masked input |
-| `/model` | Select or switch the active hosted model |
-| `/publish` | Publish agent templates through the Savant backend |
-| `/feedback` (`/bug`, `/report`) | Open the feedback flow |
-| `/telemetry` (`/analytics`) | View or change remote analytics consent |
-| `/theme:toggle` | Switch between light and dark themes |
-| `/bash` (`!`) | Run a shell command or enter Bash mode |
-| `/image` (`/img`, `/attach`) | Attach an image for supported multimodal models |
-| `/init` | Create starter agent types and `knowledge.md` |
-| `/login` / `/logout` | Authenticate or end the current session |
-| `/exit` (`/quit`, `/q`) | Quit the CLI |
-
-Savant-Free additionally exposes free-session controls such as `/end-session`
-and its model picker; paid/backend-only commands are filtered from that build.
-
----
-
-## ECHO Protocol
-
-This project ships with [ECHO Protocol v0.2.0](ECHO.md) — the single bootstrap
-file for agent behavior.
-
-### Core Principles
-
-- **FID-Bound Execution** — Code is never written until the FID converges
-- **Perfection Loop** — RED → GREEN → AUDIT → SELF-CORRECT → COMPLETE
-- **Separation of Duties** — The agent that writes code cannot verify it
-- **No Deferrals** — Every approved work item must be completed
-
-### 15 Laws
-
-4 immutable process laws (Read 0-EOF, Present Before Act, Verify Before Proceed,
-Call-Graph Reachability) + 11 extended code laws. `strict: true` in TypeScript.
-
-### Key Files
-
-| File                     | Purpose                                           |
-| ------------------------ | ------------------------------------------------- |
-| `ECHO.md`                | The 15 Laws + Perfection Loop FSM + FID lifecycle |
-| `ARCHITECTURE.md`        | Agent roster and tool restrictions                |
-| `protocol.config.yaml`   | Build commands, quality bar, paths                |
-| `dev/fids/`              | Feature Implementation Documents                  |
-| `dev/session-summaries/` | Session audit trail                               |
-| `dev/LEARNINGS.md`       | Cross-session lessons                             |
-
----
-
-## Configuration
-
-| What                         | Where                  | Format                                    |
-| ---------------------------- | ---------------------- | ----------------------------------------- |
-| ECHO Protocol runtime config | `protocol.config.yaml` | YAML — language, commands, quality limits |
-| TypeScript base config       | `tsconfig.json`        | JSON — `strict: true`                     |
-| ESLint config                | `eslint.config.js`     | Flat config                               |
-| Bun config                   | `bunfig.toml`          | TOML — `linker: "hoisted"`                |
-
----
-
-## Validation
-
-```bash
-# Build
-bun run build:sdk && bun run ci
-
-# Test
-bun test
-
-# Type check
-bun x tsc --noEmit
-
-# Lint
-bun x eslint . --max-warnings 0
-
-# Format
-bun x prettier --write .
-```
-
----
-
-## Documentation
-
-- [`ECHO.md`](ECHO.md) — The 15 Laws + Perfection Loop FSM
-- [`ARCHITECTURE.md`](ARCHITECTURE.md) — Agent roster and tool restrictions
-- [`protocol.config.yaml`](protocol.config.yaml) — Build commands, quality bar
-- [`CHANGELOG.md`](CHANGELOG.md) — Release history
-- [`docs/launch/landing/index.html`](docs/launch/landing/index.html) — Public
-  landing page
-- [`dev/LEARNINGS.md`](dev/LEARNINGS.md) — Cross-session lessons
-- [`dev/session-summaries/`](dev/session-summaries/) — Session audit trail
-
----
-
-## License
-
-[Apache-2.0](LICENSE) — see [LICENSE](LICENSE) for full text.
-
----
-
-_Savant-Code is the public TypeScript monorepo for the Savant-Code agent
-framework._
-
-**Savant** • 2026
+<!-- markdownlint-disable MD013 -->
+
+# Savant-Code
+
+**A terminal-native multi-agent AI coding assistant that audits every change before it touches your repo.**
+
+Built with TypeScript/Bun, governed by the [ECHO Protocol](https://github.com/savant0x/savant-code/blob/main/ECHO.md), and designed for local-first use with Ollama or any OpenAI-compatible provider.
+
+[![GitHub Stars](https://img.shields.io/github/stars/savant0x/savant-code?style=social)](https://github.com/savant0x/savant-code)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/savant0x/savant-code/blob/main/LICENSE)
+
+## Installation
+
+```bash
+npm install -g savant-code
+```
+
+## Quick Start
+
+```bash
+cd your-project
+savant-code
+```
+
+Describe the change you want. Savant-Code explores the repository, plans the work, implements approved changes, and verifies the result.
+
+If Ollama is installed and running, it is detected automatically and requires no API key:
+
+```bash
+ollama serve
+savant-code
+```
+
+Run `/health` inside the chat to inspect Ollama connectivity, available local models, provider mode, and permission mode.
+
+## Provider Setup
+
+Savant-Code supports local Ollama, hosted gateway providers, and direct OpenRouter or OpenAI-compatible endpoints. Use the interactive picker:
+
+```text
+/provider
+```
+
+Or select one of the supported gateway providers directly:
+
+| Provider | Selection | Environment variable | Notes |
+| --- | --- | --- | --- |
+| Ollama | Automatic detection | `OLLAMA_HOST` (optional) | Local inference; no API key required |
+| OpenCode Go | `/provider opencode-go` | `OPENCODE_GO_API_KEY` | Hosted gateway; MiMo 2.5 is the default model |
+| TokenRouter | `/provider tokenrouter` | `TOKENROUTER_API_KEY` | Multi-provider gateway |
+| NVIDIA NIM | `/provider nvidia` | `NVIDIA_API_KEY` | NVIDIA-hosted inference |
+| CommandCode | `/provider commandcode` | `COMMAND_CODE_API_KEY` | OpenAI-compatible hosted inference |
+| OpenRouter direct | `/provider openrouter` or `DIRECT_PROVIDER=openrouter` | `OR_MASTER_KEY`, `OPENROUTER_API_KEY`, or `INFERENCE_API_KEY` | Direct mode without the Savant backend |
+| Custom endpoint | Environment configuration | `INFERENCE_BASE_URL`, `INFERENCE_API_KEY` | Advanced OpenAI-compatible endpoint |
+
+The interactive key prompt is masked. Saved provider credentials are stored in the user configuration directory and are not added to chat history:
+
+- **Windows:** `C:\Users\<username>\.savant-code\credentials.json`
+- **macOS/Linux:** `~/.savant-code/credentials.json`
+
+Shell environment variables take precedence over saved credentials. Configure one provider key before launching:
+
+```powershell
+# PowerShell — choose one hosted gateway
+$env:OPENCODE_GO_API_KEY = "your-key"
+# $env:TOKENROUTER_API_KEY = "your-key"
+# $env:NVIDIA_API_KEY = "your-key"
+# $env:COMMAND_CODE_API_KEY = "your-key"
+savant-code
+```
+
+```cmd
+:: Windows Command Prompt — choose one hosted gateway
+set OPENCODE_GO_API_KEY=your-key
+:: set TOKENROUTER_API_KEY=your-key
+:: set NVIDIA_API_KEY=your-key
+:: set COMMAND_CODE_API_KEY=your-key
+savant-code
+```
+
+```bash
+# macOS/Linux — choose one hosted gateway
+export OPENCODE_GO_API_KEY="your-key"
+# export TOKENROUTER_API_KEY="your-key"
+# export NVIDIA_API_KEY="your-key"
+# export COMMAND_CODE_API_KEY="your-key"
+savant-code
+```
+
+### OpenRouter direct mode
+
+To bypass the Savant Code backend for inference and route directly to OpenRouter:
+
+```bash
+export DIRECT_PROVIDER=openrouter
+export INFERENCE_BASE_URL=https://openrouter.ai/api/v1
+```
+
+The credential resolution order is:
+
+1. `OR_MASTER_KEY` — exchanges a master key for a regular key through OpenRouter `/api/v1/keys`.
+2. `OPENROUTER_API_KEY` — uses an existing regular OpenRouter key directly.
+3. `INFERENCE_API_KEY` — uses the SDK-specific inference key.
+
+### Complete safe local configuration example
+
+The following is a public template containing dummy values only. Copy it to `.env.local` for local development, then replace only the values you actually use. Configure one inference mode or hosted provider at a time; the entries below document the complete variable surface, not a recommendation to enable every provider simultaneously. `.env.local` must remain private and gitignored. Never copy real credentials into documentation.
+
+```dotenv
+# Core and app configuration
+NEXT_PUBLIC_CB_ENVIRONMENT=dev
+NEXT_PUBLIC_WEB_PORT=3000
+NEXT_PUBLIC_SAVANT_CODE_APP_URL=http://localhost:3000
+# NEXT_PUBLIC_FREEBUFF_APP_URL=http://localhost:3001
+
+# Analytics, support, and billing placeholders
+NEXT_PUBLIC_POSTHOG_API_KEY=phc_dummy_replace_me
+NEXT_PUBLIC_POSTHOG_HOST_URL=http://localhost:4000
+NEXT_PUBLIC_GRAVITY_PIXEL_ID=00000000-0000-0000-0000-000000000000
+NEXT_PUBLIC_SUPPORT_EMAIL=replace-me@example.com
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_dummy_replace_me
+NEXT_PUBLIC_STRIPE_CUSTOMER_PORTAL=http://localhost:3000/portal
+NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION_ID=dummy_replace_me
+
+# OpenRouter direct mode
+DIRECT_PROVIDER=openrouter
+INFERENCE_BASE_URL=https://openrouter.ai/api/v1
+OR_MASTER_KEY=dummy-or-master-key-replace-me
+# OPENROUTER_API_KEY=dummy-openrouter-api-key-replace-me
+# INFERENCE_API_KEY=dummy-inference-api-key-replace-me
+
+# Supported hosted gateways
+OPENCODE_GO_API_KEY=dummy-opencode-go-key-replace-me
+TOKENROUTER_API_KEY=dummy-tokenrouter-key-replace-me
+NVIDIA_API_KEY=dummy-nvidia-key-replace-me
+COMMAND_CODE_API_KEY=dummy-commandcode-key-replace-me
+
+# Local Ollama override (optional)
+# OLLAMA_HOST=http://localhost:11434
+
+# GitHub MCP helper (read-only) and database helper
+# SAVANT_CODE_GITHUB_TOKEN=dummy-github-token-replace-me
+# SAVANT_CODE_DATABASE_URL=sqlite://./local.db
+
+# Optional backend and advanced integrations
+# SAVANT_CODE_API_KEY=backend-dummy-replace-me
+# CLOUDFLARE_API_TOKEN=cloudflare-dummy-replace-me
+# CLOUDFLARE_ACCOUNT_ID=cloudflare-account-dummy-replace-me
+AMAZON_WORKER=amazon-worker-dummy-replace-me
+```
+
+`AMAZON_WORKER` is retained for local deployment integrations. `GITHUB_TOKEN` and `NPM_PUBLISH` are intentionally not part of the public template because they are private release credentials.
+
+### Building release binaries
+
+Release binaries ship a sibling `env.json` with the canonical production `NEXT_PUBLIC_*` defaults (prod environment, `https://savant-code.com`, `support@savant-code.com`, release placeholders). `cli/scripts/build-binary.ts` fails the build if any dev `NEXT_PUBLIC_*` value — localhost URLs, personal emails, or dummy keys from the build shell or a repo `.env.local` — leaks into that file. Two escape hatches exist for intentional deviations:
+
+- `SAVANT_CODE_BUILD_ENV=<env>` — build a local dev binary (skips the integrity check).
+- `SAVANT_CODE_ALLOW_NEXT_PUBLIC_OVERRIDES=1` — CI/release override when injecting real production keys (for example PostHog or Stripe) that intentionally differ from the canonical placeholders.
+
+Build release artifacts from a clean shell (no dev `NEXT_PUBLIC_*` exports, no `.env.local` loaded) so `env.json` matches the canonical defaults exactly.
+
+## What Makes Savant-Code Different
+
+Savant-Code is a multi-agent system rather than a single model guessing at your code. Nine canonical ECHO roles coordinate with strict separation of duties:
+
+| Agent | Responsibility |
+| --- | --- |
+| **Savant** | Orchestrator — routes work, enforces protocol, and spawns agents |
+| **Detective** | Finds bugs and issues with evidence before code is written |
+| **Forge** | Implements code changes from a converged plan |
+| **Verifier** | Performs the independent double-audit after implementation |
+| **Recorder** | Manages FID lifecycle and release tracking |
+| **Thinker** | Performs deep sequential reasoning for complex problems |
+| **Scout** | Explores files and code to gather context |
+| **Researcher** | Performs web search, documentation lookup, and multi-query `deep_research` |
+| **Scribe** | Captures session summaries and durable knowledge |
+
+Infrastructure helpers such as terminal execution, browser automation, and web/docs tool libraries support these roles; they are not additional roster members.
+
+### ECHO Protocol
+
+Every code change follows the ECHO Perfection Loop:
+
+1. **RED** — identify all failures and issues with evidence.
+2. **GREEN** — implement minimal, surgical changes from the converged FID.
+3. **AUDIT** — independently verify the implementation and call-graph reachability.
+4. **SELF-CORRECT** — resolve audit findings and repeat verification when needed.
+5. **COMPLETE** — record evidence, update tracking, and close the work item.
+
+No code is written without a converged plan, and the implementing agent cannot serve as the final verifier.
+
+## Features
+
+### Multi-agent orchestration
+
+- Nine canonical agents coordinate through ECHO with explicit separation of duties.
+- Child agents receive only their authorized tool subset through strict allowlist filtering.
+- Parallel agent work supports exploration, research, implementation, and independent review.
+- FID-bound execution keeps implementation tied to an approved specification.
+
+### Thinker and sequential reasoning
+
+The Thinker accumulates typed sequential reasoning steps and converges to a non-null final artifact containing status, synthesis, payload, metrics, and thoughts. Thinker cascades preserve prompt inheritance while keeping child tools restricted.
+
+### Safe execution and tool-call hardening
+
+- Fail-closed handling for incomplete, malformed, or truncated native tool calls.
+- Strict tool schema validation with safe coercion of stringified numbers and booleans.
+- Programmatic tool primitives with explicit authorization boundaries.
+- Write-gate checkpoints capture files before `write_file`, `str_replace`, or `apply_patch` changes.
+- Tool errors, cancellation, retry, and child-agent failures are surfaced rather than silently treated as success.
+
+### Checkpoint and Rewind
+
+Each user turn can persist the pre-edit content of every first-touched file, including subagent writes. `/rewind` supports:
+
+- **Code only** — restore files while keeping the conversation.
+- **Conversation only** — restore the transcript boundary without changing files.
+- **Both** — restore code and conversation together.
+- **Fork** — restore the selected turn into a fresh chat.
+
+Retention is bounded to the most recent 20 turns, restore paths are revalidated, and terminal side effects are intentionally not rewound. No Git repository is required.
+
+### Permissions and modes
+
+- `--permission-mode safe|prompt|unsafe` selects the startup policy.
+- `/permissions` (aliases `/sandbox` and `/safety`) views or changes the policy.
+- `safe` denies risky tools; `prompt` currently also denies them because interactive confirmations are not yet implemented; `unsafe` allows them explicitly.
+- `HYBRID`, `SCAFFOLD`, `STRICT`, and `ANALYZE` modes change the execution scope at runtime (hovering the toggle shows each mode's contract). `HYBRID` (default) is the frictionless flow: you write directly while the harness deterministically enforces Law 1/3 and the Verifier criteria at `warn`, and the full Perfection Loop auto-engages past the 20-line threshold. `STRICT` guarantees the full ceremony on **every** code change: Recorder creates a FID, RED (Detective) analyzes, GREEN (Forge) writes, AUDIT (Verifier) double-checks with Law-4 reachability greps, and Recorder archives the FID with a CHANGELOG entry. Use `STRICT` for security-sensitive or long-lived code (auth, payments, migrations); use `HYBRID` for day-to-day building and exploration.
+
+### Planning, review, and goals
+
+- `/interview` turns an underspecified idea into a structured specification.
+- `/plan` creates an implementation plan.
+- `/review` opens a focused code-review workflow.
+- `/goal` defines a verifiable goal.
+- `/loop` schedules recurring checks with cadence, run counts, and convergence detection.
+
+### Context and project knowledge
+
+- Four-layer progressive context compaction keeps large repositories within model limits.
+- `knowledge.md` files provide durable project conventions and preferences.
+- User-level knowledge can be loaded alongside project knowledge.
+- OpenClaw-format `SKILL.md` files are discovered and exposed as native skills.
+- MCP servers are discovered at startup and their tools are published to the model.
+- The Researcher role ships a mechanical `deep_research` tool: multi-query web research
+  with concurrency limits, URL dedup, domain scoring, citations, and graceful
+  degradation (`incomplete` + gaps) — a pure search facade, no second LLM.
+- A read-only `github` helper connects to the official GitHub MCP server
+  (`SAVANT_CODE_GITHUB_TOKEN`) for PR/issue/CI review, code search, and secret scanning.
+- A `database` helper exposes `list_tables`, `describe_table`, `execute_query`, and
+  `analyze_query` over `bun:sqlite` with an adapter-enforced safety contract:
+  read-only by default, LIMIT injection, SQL redaction, and destructive-DDL blocking.
+- Browser automation supports `viewport` presets (mobile/tablet/desktop), an offline
+  WCAG accessibility scan, and optional session persistence.
+- Gateway model context lengths can be resolved from the live catalog.
+- A harness-side ECHO compliance layer enforces Law 1 (read-before-write) and Law 3
+  (verify-after-write) deterministically, mechanically flags the Verifier-criteria
+  (10+ lines / 2+ files / new API / security-sensitive / Forge), and escalates when a
+  write touches an active FID — non-blocking receipts plus corrective steering.
+
+### Terminal UI
+
+- Token-by-token streaming with cancellation and retry backoff.
+- Universal copy actions for code blocks, tool output, and diffs.
+- Light/dark themes with the Neon Slate aesthetic.
+- Collapsible sidebar sections and FID cards.
+- `@filename` and `@AgentName` autocomplete.
+- Bash mode via `!command` or `/bash` with permission enforcement.
+- Masked provider setup and health diagnostics.
+- Telemetry consent controls through `/telemetry status|enable|disable`.
+- Optional image attachments for multimodal providers.
+- `/export` writes a fully self-contained branded HTML report of the conversation
+  (offline fonts, collapsible tool rows, per-message and copy-all buttons).
+- Edit diffs tint added lines 50% neon green and removed lines 50% neon red, with a
+  `[-N/+M]` add/remove counter beside the copy button.
+
+### SDK and runtime
+
+The package ships the CLI on top of shared runtime and SDK capabilities:
+
+- `SavantCodeClient` for running agents from Node.js, Bun, or browser applications.
+- Streaming `RunState` events for progress, tool calls, diffs, and final output.
+- Custom `AgentDefinition[]` agents and custom tool definitions.
+- `AbortSignal` cancellation propagated through subagent streams.
+- Checkpoint APIs (`openTurn`, `captureSnapshot`, `closeTurn`, `listTurns`, `restoreTurn`, and `forkFrom`).
+- LLM-agnostic runtime with OpenAI-compatible, Anthropic, Ollama, and gateway provider shims.
+- Per-call token counts and USD cost estimates surfaced in run state.
+
+## Slash Command Reference
+
+Commands can be entered with `/`; aliases are shown in parentheses. Some commands are intentionally unavailable in Savant-Free builds.
+
+| Command | Purpose |
+| --- | --- |
+| `/help` (`/h`, `/?`) | Show command help and tips |
+| `/new` (`/clear`, `/reset`) | Start a fresh conversation |
+| `/history` (`/chats`) | Browse and resume previous sessions |
+| `/copy` (`/copy-chat`) | Copy the complete conversation to the clipboard |
+| `/export` (`/save`) | Write a self-contained branded HTML report of the conversation |
+| `/interview` | Create a structured specification |
+| `/plan` | Create an implementation plan |
+| `/review` | Review code changes |
+| `/goal` (`/g`) | Iterate toward a verifiable goal |
+| `/loop` (`/repeat`) | Schedule recurring checks; use `status` or `stop` |
+| `/verify` (`/typecheck`) | Run all four core workspace typechecks or one selected workspace |
+| `/permissions` (`/sandbox`, `/safety`) | View or set the tool permission mode |
+| `/rewind` (`/undo`, `/checkpoint`) | Restore code and/or conversation from a prior turn |
+| `/health` (`/status`, `/check`) | Check provider, Ollama, model, and permission status |
+| `/diagnostics` (`/diag`, `/processes`) | Show local process and resource diagnostics |
+| `/provider` | Configure a hosted provider key with masked input |
+| `/mode` | List the four modes and their contracts, or switch: `/mode <name>` or `/mode:<name>` |
+| `/model` | Select or switch the active model |
+| `/publish` | Publish agent templates through the Savant backend |
+| `/feedback` (`/bug`, `/report`) | Open the feedback flow |
+| `/telemetry` (`/analytics`) | View or change remote analytics consent |
+| `/theme:toggle` | Switch between light and dark themes |
+| `/bash` (`!`) | Run a shell command or enter Bash mode |
+| `/image` (`/img`, `/attach`) | Attach an image for supported multimodal models |
+| `/init` | Create starter agent types and `knowledge.md` |
+| `/login` / `/logout` | Authenticate or end the current session |
+| `/exit` (`/quit`, `/q`) | Quit the CLI |
+
+## Usage Examples
+
+**Implement a feature:**
+
+> Add a rate limiter to the API endpoints that allows 100 requests per minute per IP address, with Redis-backed counting.
+
+**Fix a bug:**
+
+> The login form crashes on submit when the email field is empty. Find the bug and fix it.
+
+**Write tests:**
+
+> Add unit tests for the UserService class covering all edge cases in the register flow.
+
+**Refactor:**
+
+> Refactor the database connection layer to use connection pooling instead of creating a new connection per request.
+
+**Code review:**
+
+> Review my recent changes and flag security issues, performance problems, and style violations.
+
+## Troubleshooting
+
+### Permission errors
+
+Use a user-writable Node/npm installation or, where appropriate, install globally with elevated permissions:
+
+```bash
+sudo npm install -g savant-code
+```
+
+### Corporate proxy or firewall
+
+```bash
+export HTTPS_PROXY=http://your-proxy-server:port
+savant-code
+```
+
+### No model available
+
+Run `/provider` to configure one of the hosted gateways, or install and start [Ollama](https://ollama.com) for local inference.
+
+### Direct-provider mode cannot connect
+
+Confirm that `DIRECT_PROVIDER`, `INFERENCE_BASE_URL`, and the selected credential are set in the same shell that launches Savant-Code. For OpenRouter, verify the precedence order above and use `/health` to inspect the active mode.
+
+## Links
+
+- **GitHub:** [github.com/savant0x/savant-code](https://github.com/savant0x/savant-code)
+- **Documentation:** [savant-code.com/docs](https://savant-code.com/docs)
+- **Issues:** [GitHub Issues](https://github.com/savant0x/savant-code/issues)
+- **License:** [Apache 2.0](https://github.com/savant0x/savant-code/blob/main/LICENSE)
+
+---
+
+_Savant-Code is the public TypeScript monorepo for the Savant-Code agent framework._