savant-code 0.0.16 → 0.0.19

package/protocol.config.yaml

@@ -0,0 +1,113 @@
+# Protocol Config — Project-specific configuration for ECHO Protocol
+#
+# QUICK START: Change these 3 lines for your project:
+#   1. language:       "rust" | "typescript" | "python" | "go" | "java" | "csharp"
+#   2. commands.build: your compile/build command
+#   3. commands.test:  your test runner command
+
+project:
+  name: 'savant-code'
+  description: 'Multi-Agent AI Coding Assistant with ECHO Protocol governance. TypeScript monorepo, Bun runtime.'
+  version: '0.0.18'
+
+protocol:
+  version: '0.2.0'
+  strict_mode: true # true = all 15 laws active (default), false = core 4 laws only
+
+
+language: 'typescript' # rust | typescript | python | go | java | csharp
+
+commands:
+  build: 'bun run ci' # NOTE: release-artifact build (SDK + Savant-Free binaries only, per package.json `ci`). Full 9-workspace compile verification is the `type_check` gate below.
+  test: 'bun test'
+  # Mirrors the root `typecheck` script — all 9 workspaces including packages/database
+  # (FID-2026-0803-001 ECHO-8).
+  type_check: 'bun run --cwd=common typecheck && bun run --cwd=agents typecheck && bun run --cwd=sdk typecheck && bun run --cwd=cli typecheck && bun run --cwd=evals typecheck && bun run --cwd=packages/agent-runtime typecheck && bun run --cwd=packages/code-map typecheck && bun run --cwd=packages/database typecheck && bun run --cwd=packages/llm-providers typecheck'
+  lint: 'bun x eslint . --max-warnings 0' # zero-tolerance gate (matches .githooks/pre-push)
+  lint_md: 'bun run lint:md'
+  # Full-repo prettier is a documented deferred boundary (FID-001); the
+  # practical gate is formatting changed files only (FID-2026-0803-001 ECHO-8).
+  format: 'bunx prettier --check .'
+  clean: 'bun run --cwd=sdk clean'
+
+paths:
+  src: 'src/'
+  # NOTE: workspace tests live in per-package `src/__tests__` (Bun convention);
+  # there is no top-level `tests/` dir (FID-2026-0803-001 ECHO-8).
+  tests: 'tests/'
+  docs: 'docs/'
+  dev: 'dev/'
+  fids: 'dev/fids/'
+  fids_archive: 'dev/fids/archive/'
+  session_summaries: 'dev/session-summaries/'
+  learnings: 'dev/LEARNINGS.md'
+
+# ADVISORY — documented quality bar only. Not enforced by any lint/test gate;
+# core files intentionally exceed max_file_lines (e.g. savant.ts, run.ts).
+# FID-2026-0803-001 ECHO-3.
+quality:
+  max_file_lines: 300
+  max_function_lines: 50
+  max_line_length: 100
+  max_complexity: 10
+  max_params: 4
+  max_comment_density: 0.33
+  max_nesting_depth: 3
+
+# Naming rules: see coding-standards/{language}.md
+
+# ADVISORY — aspirational testing policy; the real gates are per-workspace
+# `bun test` suites and the pre-push hook. FID-2026-0803-001 ECHO-3.
+testing:
+  fuzz_enabled: false
+  mutation_enabled: false
+  coverage_threshold: 80
+  test_timeout: 30
+  parallel_tests: true
+
+# ADVISORY — documentation of the FID policy. The runtime open-FID check is
+# presence-based (scanOpenFids) and `max_open_fids` is not enforced.
+# FID-2026-0803-001 ECHO-3/ECHO-7.
+fid:
+  auto_create: true
+  severity_levels: ['critical', 'high', 'medium', 'low']
+  max_open_fids: 20
+
+# Savant protocol contract — single-agent ECHO adaptation (v0.1.2-savant),
+# machine-readable alongside the harness `protocol:` block (v0.2.0).
+savant:
+  protocol:
+    version: '0.1.2-savant'
+    strict_mode: true
+  # ADVISORY — documents the canonical sandbox default. Actual behavior is
+  # controlled by --permission-mode and /permissions in CLI state.
+  # FID-2026-0803-001 ECHO-3.
+  sandbox:
+    permissionMode: 'prompt' # safe | prompt | unsafe
+
+# Legacy FreeBuff protocol alias. Retained because the FreeBuff ECHO
+# adaptation and FREEREADME.md route those sessions through this namespace.
+# The runtime normalizes it into the `savant` ProtocolConfig property and
+# prefers the `savant` namespace when both are present.
+freebuff:
+  protocol:
+    version: '0.1.2-freebuff'
+    strict_mode: true
+
+# max_iterations is LIVE: parsed by common/src/util/protocol-config.ts and
+# drives the FSM circuit breaker in transition-phase.ts (FID-2026-0803-001
+# ECHO-3). The remaining fields are advisory/convergence documentation.
+perfection_loop:
+  max_iterations: 10
+  change_threshold: 0.10
+  convergence_threshold: 0.02
+  convergence_passes: 2
+  oscillation_limit: 3
+
+# ADVISORY — session policy documentation; not consumed by the runtime.
+# FID-2026-0803-001 ECHO-3.
+session:
+  auto_summary: true
+  summary_interval: 30
+  max_session_hours: 4
+  autonomy_level: 3 # 1=Guided, 2=Supervised, 3=Autonomous (default)

package/savant-free/README.md

@@ -0,0 +1,73 @@
+<!-- markdownlint-disable MD041 -->
+<img src="../assets/banner.png" alt="SavantFree — The free coding agent. No subscription, no config." width="650" />
+
+# SavantFree
+
+**The free coding agent** — no subscription, no API key, no configuration. Start in seconds.
+
+An AI coding agent that runs in your terminal. Describe what you want, and SavantFree edits your code. Built from
+the same `@savant-code/cli` source as Savant-Code, then compiled with `SAVANT_FREE_MODE=true` so the bundler strips
+paid-only features (credits UI, mode switching, MAX/PLAN prompts).
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-%23000000?style=flat-square&logo=apache&logoColor=%2300fbff)](LICENSE)[![ECHO](https://img.shields.io/badge/ECHO-v0.2.0-%23000000?style=flat-square&logo=github&logoColor=%2300fbff)](../ECHO.md)[![Release](https://img.shields.io/badge/Release-pre__publishing-%23ff9500?style=flat-square&logo=semver&logoColor=%2300fbff)](../CHANGELOG.md)
+
+## Features
+
+- **Zero-config** — no API key (uses bundled inference), no account, no subscription
+- **Multi-agent orchestration** — 9 specialized ECHO agents coordinate via [ECHO Protocol v0.2.0](../ECHO.md)
+- **Perfection Loop** — RED → GREEN → AUDIT → SELF-CORRECT → COMPLETE state machine
+- **Streaming output** — token-by-token display, mid-stream cancellation
+- **Slash commands** — `/new`, `/history`, `/bash`, `/feedback`, `/theme:toggle`, `/exit`
+- **Knowledge files** — auto-loaded from `knowledge.md`, `AGENTS.md`, or `CLAUDE.md`
+- **Skills system** — auto-discovered `SKILL.md` files via OpenClaw format
+
+## Install
+
+> **Status:** `@savant-code/savant-free` is not yet published on the npm registry (private workspace, v0.0.1). For
+  now, **build from source** (see below) to produce a local `savant-free` binary. The npm install command will be
+  `npm install -g @savant-code/savant-free` once the free variant ships.
+
+## Usage
+
+```bash
+cd ~/my-project
+savant-free
+```
+
+For end-user Quick Start including how Savant-Code and Savant-Free relate, see the [repo root README](../README.md).
+
+## Project Structure
+
+```text
+savant-free/
+├── cli/       # CLI build & npm release files (binary: savant-free)
+└── e2e/       # E2E tests for the free variant
+```
+
+## Building from Source
+
+```bash
+# From the repo root
+bun savant-free/cli/build.ts 1.0.0
+```
+
+Built binary lives at `savant-free/bin/savant-free`.
+
+---
+
+For everything else — what SavantFree does, how it works, FAQ, and how it relates to SavantCode — see the [repo
+root README](../README.md). We keep that one up to date as the single source of truth.
+
+## License
+
+[Apache-2.0](../LICENSE) — see [LICENSE](../LICENSE) for full text.
+
+---
+
+<div align="center">
+
+_Savant is part of the [savant-code/savant-code monorepo](https://github.com/savant0x/savant-code), governed by
+the [ECHO Protocol v0.2.0](../ECHO.md). It's the free, ad-supported companion to the full **Savant-Code** CLI._
+
+**Savant** • 2026
+</div>

package/savant-free/SPEC.md

@@ -0,0 +1,385 @@
+# SavantFree Spec
+
+SavantFree is a free-only variant of the SavantCode CLI, distributed as a separate npm package (`savant-free`). It
+reuses the entire `cli/` package but builds with a compile-time flag that strips out paid features, subscription
+logic, credits display, and mode switching — leaving only the FREE mode experience.
+
+---
+
+## 1. Build-Time Flag
+
+### Environment Variable
+
+- **`SAVANT_FREE_MODE=true`** — set during the build to produce a SavantFree binary.
+- Injected via `--define process.env.SAVANT_FREE_MODE="true"` in `bun build`, following the same pattern as
+  `CODEBUFF_IS_BINARY` and `CODEBUFF_CLI_VERSION`.
+
+### Runtime Constant
+
+Create a shared constant in `cli/src/utils/constants.ts`:
+
+```ts
+export const IS_SAVANT_FREE = process.env.SAVANT_FREE_MODE === 'true'
+```
+
+This enables dead-code elimination in production builds — all `if (!IS_SAVANT_FREE)` branches are removed by the bundler.
+
+---
+
+## 2. Branding Changes
+
+| Area                  | SavantCode                                                       | SavantFree                                                       |
+| --------------------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
+| Terminal title prefix | `SavantCode: `                                                   | `SavantFree: `                                                   |
+| CLI commander name    | `savant-code`                                                     | `savant-free`                                                     |
+| npm package name      | `savant-code`                                                     | `savant-free`                                                     |
+| Binary name           | `savant-code`                                                     | `savant-free`                                                     |
+| App header text       | "SavantCode will run commands on your behalf to help you build." | "SavantFree will run commands on your behalf to help you build." |
+| ASCII logo            | `SAVANT_CODE` block letters                                       | `SAVANT` block letters (new logo)                            |
+| Description           | "AI coding agent"                                              | "Free AI coding assistant"                                     |
+| Homepage              | savant-code.com                                                   | savant-code.com/free (or same)                                    |
+| `WEBSITE_URL` usage   | Points to savant-code.com                                         | Same (login, feedback, etc. stay on savant-code.com)              |
+
+### Files to modify (conditional on `IS_SAVANT_FREE`)
+
+- **`cli/src/utils/terminal-title.ts`** — Change `TITLE_PREFIX` from `'SavantCode: '` to `'SavantFree: '` when
+  `IS_SAVANT_FREE`.
+- **`cli/src/login/constants.ts`** — Add a `LOGO_SAVANT_FREE` ASCII art variant, select based on `IS_SAVANT_FREE`.
+- **`cli/src/app.tsx`** — Conditional header text ("SavantFree will run commands...").
+- **`cli/src/index.tsx`** — Change commander `.name('savant-free')` and `.description(...)` when `IS_SAVANT_FREE`.
+
+---
+
+## 3. Mode Restrictions
+
+SavantFree only supports **FREE mode**. All mode-related features are stripped.
+
+### Behavior
+
+- `agentMode` is always `'FREE'` and never changes.
+- The initial mode flag (`--free`, `--max`, `--plan`) CLI options are removed in SavantFree; mode is hardcoded.
+- No mode divider messages are ever inserted into chat history.
+
+### Files to modify
+
+- **`cli/src/utils/constants.ts`** — When `IS_SAVANT_FREE`, export a single-element `AGENT_MODES = ['FREE']` and
+  `AGENT_MODE_TO_ID` with only the FREE entry. Or: the mode toggle component simply never renders.
+- **`cli/src/components/agent-mode-toggle.tsx`** — Return `null` when `IS_SAVANT_FREE` (hide entirely).
+- **`cli/src/components/build-mode-buttons.tsx`** — Return `null` when `IS_SAVANT_FREE` (hides mode-switching buttons
+  in message UI).
+- **`cli/src/components/mode-divider.tsx`** — Return `null` when `IS_SAVANT_FREE` (no mode transition markers).
+- **`cli/src/utils/input-modes.ts`** — Set `showAgentModeToggle: false` for all input mode configs when `IS_SAVANT_FREE`.
+- **`cli/src/index.tsx`** — Remove `--free`, `--max`, `--plan`, `--lite` CLI flags when `IS_SAVANT_FREE`; hardcode
+  `initialMode = 'FREE'`.
+- **`cli/src/state/chat-store.ts`** — Default `agentMode` to `'FREE'`; make `setAgentMode` a no-op when `IS_SAVANT_FREE`.
+
+---
+
+## 4. Slash Commands
+
+### Commands to REMOVE in SavantFree
+
+| Command                                            | Reason                                                                                         |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `/subscribe` (+ `/strong`, `/sub`, `/buy-credits`) | No subscription model                                                                          |
+| `/usage` (+ `/credits`)                            | No credits display                                                                             |
+| `/ads:enable`                                      | Ads always on, not toggleable                                                                  |
+| `/ads:disable`                                     | Ads always on, not toggleable                                                                  |
+| `/connect:claude` (+ `/claude`)                    | Claude subscription not available                                                              |
+| `/refer-friends` (+ `/referral`, `/redeem`)        | Referrals earn credits, not applicable                                                         |
+| `/mode:*` (all mode commands)                      | Only FREE mode                                                                                 |
+| `/agent:gpt-5`                                     | Premium agent, not available in free tier                                                      |
+| `/review`                                          | Uses thinker-gpt under the hood                                                                |
+| `/publish`                                         | Agent publishing not available in free tier                                                    |
+| `/image` (+ `/img`, `/attach`)                     | Image attachments unavailable with non-multimodal free models (DeepSeek V4 Pro, DeepSeek V4 Flash) |
+
+### Commands to KEEP
+
+| Command                                   | Notes                          |
+| ----------------------------------------- | ------------------------------ |
+| `/help`                                   | Modified help content (see §6) |
+| `/new` (+ `/clear`, `/reset`, `/n`, `/c`) | Clear conversation             |
+| `/history` (+ `/chats`)                   | Browse past conversations      |
+| `/feedback` (+ `/bug`, `/report`)         | Share feedback                 |
+| `/bash` (+ `/!`)                          | Bash mode                      |
+| `/theme:toggle`                           | Light/dark toggle              |
+| `/logout` (+ `/signout`)                  | Sign out                       |
+| `/exit` (+ `/quit`, `/q`)                 | Quit                           |
+| `/login` (+ `/signin`)                    | Already-logged-in message      |
+| Skill commands (`/skill:*`)               | Keep if skills are loaded      |
+
+### Implementation
+
+- **`cli/src/data/slash-commands.ts`** — Filter `SLASH_COMMANDS` based on `IS_SAVANT_FREE`. Remove mode commands,
+  subscription commands, credits commands, ads commands, referral, review, publish, and gpt-5 agent commands.
+- **`cli/src/commands/command-registry.ts`** — Filter `COMMAND_REGISTRY` similarly. Wrap removed commands in
+  `!IS_SAVANT_FREE` guards.
+
+---
+
+## 5. Credits & Subscription UI
+
+SavantFree never displays credits, usage, subscription info, or out-of-credits states.
+
+### Components to suppress (render `null` when `IS_SAVANT_FREE`)
+
+| Component                  | File                                       | Behavior                                                                 |
+| -------------------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
+| `UsageBanner`              | `components/usage-banner.tsx`              | Never rendered                                                           |
+| `OutOfCreditsBanner`       | `components/out-of-credits-banner.tsx`     | Never rendered                                                           |
+| `SubscriptionLimitBanner`  | `components/subscription-limit-banner.tsx` | Never rendered                                                           |
+| `BottomStatusLine`         | `components/bottom-status-line.tsx`        | Never rendered (Claude subscription status)                              |
+| Credits in `MessageFooter` | `components/message-footer.tsx`            | Remove `CreditsOrSubscriptionIndicator` — no credits or "✓ Strong" shown |
+| `ClaudeConnectBanner`      | `components/claude-connect-banner.tsx`     | Never rendered                                                           |
+
+### Input modes to disable
+
+When `IS_SAVANT_FREE`, these input modes should be unreachable:
+
+- `outOfCredits` — never triggered
+- `subscriptionLimit` — never triggered
+- `usage` — no `/usage` command
+- `connect:claude` — no `/connect:claude` command
+- `referral` — no `/refer-friends` command
+
+### Hooks to disable/skip
+
+- **`use-usage-monitor.ts`** — Return early when `IS_SAVANT_FREE` (no credits to monitor).
+- **`use-subscription-query.ts`** — Return empty/disabled when `IS_SAVANT_FREE`.
+- **`use-claude-quota-query.ts`** — Return empty/disabled when `IS_SAVANT_FREE`.
+- **`use-usage-query.ts`** — Still needed for server-side billing, but UI never shows it.
+
+### Session credits tracking
+
+- `sessionCreditsUsed` in `chat-store.ts` still accumulates (server tracks usage), but the UI never displays it.
+- The `chat.tsx` ad banner continues to pass `isFreeMode={true}` (hardcoded).
+
+---
+
+## 6. Help Menu
+
+The `/help` banner in SavantFree should be simplified. Remove the **Credits** section entirely.
+
+### SavantFree Help Content
+
+```text
+Shortcuts
+  Ctrl+C / Esc  stop
+  Ctrl+J / Opt+Enter  newline
+  ↑↓  history
+  Ctrl+T  collapse/expand agents
+
+Features
+  /  commands
+  @files  mention
+  @agents  use agent
+  !bash  run command
+```
+
+No "Credits" section. No `/subscribe`, `/usage`, or `/ads:enable` references.
+
+### File to modify
+
+- **`cli/src/components/help-banner.tsx`** — Conditionally hide the Credits section when `IS_SAVANT_FREE`.
+
+---
+
+## 7. Ads Behavior
+
+In SavantFree, ads are **always enabled** and **cannot be disabled**.
+
+- The ad banner always renders (when an ad is available).
+- The "Hide ads" link in the info panel is replaced with "Ads are required in Free mode." (this already exists in
+  `ad-banner.tsx` when `isFreeMode` is true).
+- The `/ads:enable` and `/ads:disable` commands are removed (see §4).
+- `getAdsEnabled()` always returns `true` when `IS_SAVANT_FREE`.
+
+### Files to modify
+
+- **`cli/src/commands/ads.ts`** — `getAdsEnabled()` returns `true` unconditionally when `IS_SAVANT_FREE`.
+- **`cli/src/chat.tsx`** — Skip the `!hasSubscription` guard for ads when `IS_SAVANT_FREE`; always show.
+
+---
+
+## 8. Build & Release
+
+### Directory Structure
+
+The `savant-free/` directory is organized as a product-level directory with subdirectories for each surface (CLI,
+web, etc.):
+
+```text
+savant-free/
+├── SPEC.md           # This file (product-level spec)
+├── README.md         # Product-level documentation
+├── cli/              # CLI build & release infrastructure
+│   ├── build.ts      # Build script that sets SAVANT_FREE_MODE=true
+│   └── release/
+│       ├── package.json  # npm package metadata (name: "savant-free")
+│       ├── index.js      # Thin product configuration entry point
+│       └── README.md     # npm package README
+└── web/              # (Future) SavantFree website code
+```
+
+This structure allows `savant-free/web/` (or other surfaces) to be added alongside the CLI without restructuring.
+
+### Build Script (`savant-free/cli/build.ts`)
+
+Wraps `cli/scripts/build-binary.ts` with:
+
+```bash
+SAVANT_FREE_MODE=true bun cli/scripts/build-binary.ts savant-free <version>
+```
+
+The existing `build-binary.ts` already supports a custom binary name argument and passes `NEXT_PUBLIC_*` env vars.
+We add `SAVANT_FREE_MODE` to the `defineFlags` array in `build-binary.ts`.
+
+### Release Package (`savant-free/cli/release/package.json`)
+
+Mirrors `cli/release/package.json` but with:
+
+- `"name": "savant-free"`
+- `"description": "Free AI coding assistant"`
+- `"bin": { "savant-free": "index.js" }`
+- Shared launcher implementation from `cli/release-core/`, materialized during `npm pack`
+- Downloads the platform-specific binary on first launch
+- Binary stored at `~/.config/savant/savant-free` (or `savant-free.exe` on Windows)
+
+### GitHub Workflow
+
+New file: `.github/workflows/savant-free-release.yml`
+
+Mirrors `cli-release-prod.yml` with these changes:
+
+- **Trigger**: `workflow_dispatch` (manual) or scheduled
+- **Binary name**: `savant-free`
+- **Version source**: `savant-free/cli/release/package.json`
+- **Git tags**: `savant-free-v<version>`
+- **npm publish**: `savant-free` package
+- **Environment overrides**: `{"SAVANT_FREE_MODE": "true", "NEXT_PUBLIC_CB_ENVIRONMENT": "prod"}`
+- **GitHub Release**: Creates releases in `savant0x/savant-code-community` (or a separate repo)
+
+---
+
+## 9. Changes to `cli/scripts/build-binary.ts`
+
+Add `SAVANT_FREE_MODE` to the define flags so it's available at compile time:
+
+```ts
+const defineFlags = [
+  ['process.env.NODE_ENV', '"production"'],
+  ['process.env.CODEBUFF_IS_BINARY', '"true"'],
+  ['process.env.CODEBUFF_CLI_VERSION', `"${version}"`],
+  [
+    'process.env.CODEBUFF_CLI_TARGET',
+    `"${targetInfo.platform}-${targetInfo.arch}"`,
+  ],
+  // SavantFree mode flag
+  ['process.env.SAVANT_FREE_MODE', `"${process.env.SAVANT_FREE_MODE ?? 'false'}"`],
+  ...nextPublicEnvVars,
+]
+```
+
+---
+
+## 10. Features That Stay Unchanged
+
+These features work identically in SavantFree:
+
+- **Authentication** — Login/logout flow, API key storage
+- **Chat** — Message history, streaming, agent spawning
+- **File mentions** (`@files`) — Browse and attach files
+- **Agent mentions** (`@agents`) — Use available agents (free-tier agents only)
+- **Bash mode** — Run terminal commands
+- **Image attachments** — Attach and paste images
+- **Knowledge files** — `knowledge.md`
+- **Chat history** — `/history`, resume conversations
+- **Feedback** — `/feedback` command
+- **Theme** — Light/dark toggle
+- **Skills** — Loaded from `.agents/skills`
+- **Local agents** — Loaded from `.agents/` directory
+
+---
+
+## 11. Analytics
+
+When `IS_SAVANT_FREE`:
+
+- `APP_LAUNCHED` event includes `isSavant: true`
+- All existing analytics events continue to fire (helps understand free vs paid usage)
+- No new analytics events needed initially
+
+---
+
+## 12. Server-Side Considerations
+
+The server already handles FREE mode correctly:
+
+- `isFreeMode(costMode)` in `common/src/constants/free-agents.ts` recognizes the `'free'` cost mode
+- `AGENT_MODE_TO_COST_MODE.FREE === 'free'` is already set
+- Free-mode-allowed agent+model combos cost 0 credits
+- Ad impressions in FREE mode already don't grant credits
+
+No server-side changes are needed for SavantFree, **except** the release download API (`/api/releases/download/`)
+must be configured to serve `savant-free-*` binary tarballs. This may require updating the download route to
+recognize SavantFree release tags (`savant-free-v*`).
+
+---
+
+## 13. Testing Strategy
+
+### Unit Tests
+
+- Test that `IS_SAVANT_FREE` guards correctly hide/show components
+- Test filtered slash commands list
+- Test filtered command registry
+- Test help banner content
+
+### Integration Tests
+
+- Build a SavantFree binary and verify:
+  - Title says "SavantFree"
+  - No mode toggle visible
+  - `/subscribe`, `/usage` commands not found
+  - Help menu has no Credits section
+  - Ads always show
+
+### E2E (tmux)
+
+- Use `savant-code-local-cli` agent with `SAVANT_FREE_MODE=true` to verify visual output
+
+---
+
+## 14. Implementation Phases
+
+### Phase 1: Core Flag & Branding
+
+1. Add `IS_SAVANT_FREE` constant
+2. Update `build-binary.ts` to pass through `SAVANT_FREE_MODE`
+3. Conditional branding (title, logo, app header, CLI name)
+
+### Phase 2: Feature Stripping
+
+4. Filter slash commands and command registry
+5. Hide agent mode toggle
+6. Suppress credits/subscription UI components
+7. Disable usage monitor hook
+8. Simplify help banner
+
+### Phase 3: Ads & Cleanup
+
+9. Always-on ads behavior
+10. Disable unreachable input modes
+11. Hide `BuildModeButtons` and `ModeDivider` components
+
+### Phase 4: Build & Release Infrastructure
+
+11. Create `savant-free/cli/release/` package files
+12. Create `savant-free/cli/build.ts` script
+13. Create `.github/workflows/savant-free-release.yml`
+
+### Phase 5: Testing
+
+14. Add unit tests for IS_SAVANT_FREE guards
+15. Add integration/E2E tests
+16. Manual QA of built binary

package/savant-free/cli/build.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env bun
+
+/**
+ * SavantFree CLI build script.
+ *
+ * Wraps the existing CLI build-binary.ts with SAVANT_FREE_MODE=true
+ * to produce a free-only variant of the SavantCode CLI.
+ *
+ * Usage:
+ *   bun savant-free/cli/build.ts <version>
+ *
+ * Example:
+ *   bun savant-free/cli/build.ts 1.0.0
+ */
+
+import { spawnSync } from 'child_process'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const repoRoot = join(__dirname, '..', '..')
+
+const version = process.argv[2]
+if (!version) {
+  console.error('Usage: bun savant-free/cli/build.ts <version>')
+  process.exit(1)
+}
+
+console.log(`Building SavantFree v${version}...`)
+
+const result = spawnSync(
+  'bun',
+  ['cli/scripts/build-binary.ts', 'savant-free', version],
+  {
+    cwd: repoRoot,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      SAVANT_FREE_MODE: 'true',
+    },
+  },
+)
+
+if (result.status !== 0) {
+  console.error('SavantFree build failed')
+  process.exit(result.status ?? 1)
+}
+
+console.log(`✅ SavantFree v${version} built successfully`)

package/savant-free/cli/release/README.md

@@ -0,0 +1,55 @@
+# SavantFree
+
+**The free coding agent.** No subscription. No configuration. Start in seconds.
+
+An AI coding agent that runs in your terminal — describe what you want, and SavantFree edits your code.
+
+## Install
+
+```bash
+npm install -g savant-free
+```
+
+## Usage
+
+```bash
+cd ~/my-project
+savant-free
+```
+
+## Why SavantFree?
+
+**Best open-source models** — Powered by the strongest open-source models available, like DeepSeek, Kimi, and
+MiniMax — no proprietary lock-in.
+
+**Fast** — 5–10× speed up. 3–5× tokens per second compared to Claude, plus context gathering in seconds.
+
+**Loaded** — Built-in web research, browser use, and more.
+
+## FAQ
+
+**How can it be free?** SavantFree is supported by text ads.
+
+**What models do you use?** The best open-source models available. In full mode you can choose from DeepSeek V4
+Pro, MiMo 2.5 Pro, Kimi K2.7 Code, DeepSeek V4 Flash, MiMo 2.5, and MiniMax M3. Limited mode uses DeepSeek V4 Flash
+and MiMo 2.5. Gemini 3.1 Flash Lite handles file finding and research.
+
+**Which countries is SavantFree available in?** All countries. SavantFree runs in "full" mode in the US, Canada,
+UK, EU, and other select countries, and in "limited" mode everywhere else (or while using a VPN). See
+[savant-free.com](https://savant-free.com) for the full list.
+
+**What is limited mode?** Limited mode lets you use SavantFree outside the full-access countries, or while using a
+VPN. It includes DeepSeek V4 Flash and MiMo 2.5, with 5 one-hour sessions per day.
+
+**Are you training on my data?** No. We don't share your data with third parties that would train on it or use it
+for another purpose, unless you choose a model clearly labeled as "Collects data for training."
+
+**What data do you store?** We don't store your codebase. We only collect minimal logs for debugging purposes.
+
+## Links
+
+- [Documentation](https://savant-code.com/docs)
+- [GitHub](https://github.com/savant0x/savant-code)
+- [Website](https://savant-code.com)
+
+> Built on the [SavantCode](https://savant-code.com) platform.