savant-code 0.0.17 → 0.0.19

package/README.md

@@ -1,348 +1,550 @@
-<!-- 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 | `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
-
-# 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.
-
-## 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 and documentation lookup |
-| **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.
-- `EDIT`, `ANALYZE`, and `SCAFFOLD` modes change the execution scope at runtime.
-
-### 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.
-- Gateway model context lengths can be resolved from the live catalog.
-
-### 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.
-
-### 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` (`/export`) | Copy the complete 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 |
-| `/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._
+<!-- 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