phonton-cli 0.16.2 → 0.19.0

package/README.md

@@ -1,515 +1,204 @@
 <p align="center">
-  <img src="assets/readme/phonton-cli-logo.png" width="112" alt="Phonton CLI logo">
+  <img src="assets/readme/phonton-cli-logo.png" width="128" alt="Phonton CLI logo">
 </p>
 
-<h1 align="center">Phonton CLI · v0.16.2</h1>
+<h1 align="center">Phonton CLI — v0.19.0</h1>
 
 <p align="center">
-  <strong>Verified code changes with repo memory.</strong><br>
-  A local-first agentic development environment for developers who want autonomous code changes without giving up review control.
+  <strong>Your keys. Your code. The autonomous coding agent that never phones home.</strong><br>
+  Phonton is a local-first agentic development environment (ADE) built around the loop: <code>goal ➔ plan ➔ edit ➔ verify ➔ review ➔ remember</code>.
 </p>
 
 <p align="center">
-  <a href="https://github.com/phonton-dev/phonton-cli/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/phonton-dev/phonton-cli/actions/workflows/ci.yml/badge.svg"></a>
-  <a href="https://github.com/phonton-dev/phonton-cli/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/phonton-dev/phonton-cli?style=flat&label=stars"></a>
-  <img alt="release" src="https://img.shields.io/badge/release-v0.16.2-6c63ff">
+  <a href="https://github.com/phonton-dev/phonton-cli/actions/workflows/ci.yml"><img alt="CI Status" src="https://github.com/phonton-dev/phonton-cli/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/phonton-dev/phonton-cli/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/phonton-dev/phonton-cli?style=flat&label=stars&color=ff69b4"></a>
+  <img alt="release" src="https://img.shields.io/badge/release-v0.19.0-6c63ff">
   <img alt="license" src="https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue">
-  <img alt="status" src="https://img.shields.io/badge/status-public_alpha-f97316">
 </p>
 
 ---
 
-Phonton plans the work, routes it through local repo context, verifies changes before handoff, and keeps the result reviewable. The goal is not to be the loudest coding agent. The goal is to make AI-assisted development feel less reckless.
+## 💡 What is Phonton?
 
-> Current status: pre-1.0 public-alpha quality. The core loop is real, the CLI runs, and the Rust workspace is tested. Public launch claims should stay tied to reproducible benchmarks.
+Every AI coding assistant makes you trade privacy for autonomy. To get an agentic experience, you either hand your code to a SaaS vendor's proxy servers, or settle for inline autocompletion. 
+
+**Phonton is the first tool to deliver both: fully agentic development and absolute, uncompromising privacy.**
+
+Phonton runs as a local-first, headless-ready terminal tool. Your code never leaves your machine. Your API keys go straight to Anthropic, OpenAI, Gemini, or Ollama. No intermediate proxy, no telemetry hooks, and no subscription required. 
 
 <p align="center">
-  <img src="assets/readme/phonton-cli-hero.png" alt="Phonton CLI hero with terminal UI preview">
+  <img src="assets/readme/phonton-cli-hero.png" alt="Phonton CLI hero with terminal UI preview" width="800">
 </p>
 
-## Why Phonton
-
-Most coding agents start with chat. Phonton starts with the engineering loop:
+---
 
-```mermaid
-flowchart LR
-    A["Goal"] --> B["Plan preview"]
-    B --> C["Repo-aware worker"]
-    C --> D["Verification gate"]
-    D --> E["Reviewable diff"]
-    E --> F["Memory and history"]
-    F --> B
-```
+## 🌟 Core Differentiators
 
-That gives Phonton a different shape from an IDE assistant or a chat-first terminal assistant:
+### 1. Zero-Telemetry BYOK (Bring Your Own Key)
+Phonton is proxy-free. Requests go directly to `api.anthropic.com`, `api.openai.com`, `generativelanguage.googleapis.com`, or your local `ollama` daemon. Phonton never intercepts your keys and never touches your code in transit. You can packet-capture the network to verify.
 
-- **Review first:** plans and diffs are first-class surfaces, not buried in a conversation.
-- **Verification first:** generated work is expected to pass checks before it is treated as ready.
-- **Local first:** config, trust, store, memory, and repo context live on your machine.
-- **BYOK:** use your own provider account instead of routing every task through a Phonton-hosted model bill.
-- **Measured claims:** token and cost efficiency should be benchmarked per task, not guessed.
+### 2. The Strict 4-Layer Verification Gate
+Unlike other tools that silently write code and let LLM hallucinations ship, Phonton enforces a strict verification gate. Every diff must pass through **four layers** before it is marked as review-ready:
+1. **Tree-Sitter Syntax check**
+2. **Crate check (`cargo check`)**
+3. **Workspace Check (Lints & Format)**
+4. **Automated Test suite execution**
+5. **Interactive Browser rendering check** (Playwright checks + Screenshots in `v0.19.0`)
 
-## Trust Demo Loop
+On failure, verifier diagnostics are surgically fed back to the worker for recursive repair loops.
 
-The product promise is intentionally narrow:
+### 3. Multi-Model Intelligence Routing
+Phonton routes subtasks by complexity using tiered model mapping (`Local ➔ Cheap ➔ Standard ➔ Frontier`). It automatically escalates to a more powerful model only on verify failure. You pay pennies for boilerplate and invoke frontier intelligence only when a task demands it.
 
-```text
-goal -> plan -> edit -> verify -> review -> remember
-```
+### 4. Semantic Memory Across Sessions
+Phonton maintains a persistent SQLite store of architectural decisions, rejected approaches, and task history. The planner consults this memory on every goal decomposition, ensuring it never re-attempts approaches that failed before and builds upon approved design patterns.
 
-Try the proof-oriented demo text before configuring a provider:
+---
 
-```bash
-phonton demo trust-loop
-phonton demo trust-loop --json
-```
+## ⚡ Quick Install
 
-It walks through the evidence trail a real run should expose: GoalContract, plan preview, verification failure and retry, review receipt, known gaps, rollback point, and memory prompt.
-
-## What Works Today
-
-- Interactive Ratatui TUI with goal, task, ask, settings, git, and flight-log surfaces.
-- v0.16.2 hardens headless benchmark runs: `phonton goal --prompt-file <path> --json --yes` captures bounded baseline test evidence when prompts ask to run tests first, extracts prompt-mentioned files/APIs into the GoalContract, avoids parent-repo checkpoint escapes in nested work folders, and keeps mixed local-template/provider runs out of token-claim eligibility.
-- v0.16.1 adds `phonton goal --prompt-file <path>` for CI and benchmark runs that need the same goal execution spine without clipboard, paste, or PTY automation.
-- v0.16.1 adds `phonton extensions install <source>` for installing audited `.phonton` packs from GitHub or local paths, plus built-in open-source MCP catalog ids such as `context7`, `github`, `chrome-devtools`, `playwright`, `firecrawl`, `supabase`, `mongodb`, and `figma`.
-- v0.16.1 adds `phonton extensions catalog`, `phonton extensions new <path> [skill|steering|mcp-server|profile]`, and `phonton extensions validate` so extension discovery, scaffolding, and validation feel closer to Gemini CLI while preserving Phonton's local trust and approval model.
-- v0.16.1 hardens the local ADE spine: memory retrieval now uses light stemming, engineering-term synonyms, stopword filtering, and IDF-weighted overlap; cargo verification uses file-backed locks under `target/.phonton-locks`; Windows sandbox job-object fallback is reported explicitly.
-- v0.16.0 adds typed `@...` context mentions for files, directories, symbols, MCP servers, and MCP tools, with resolved/missing/approval-gated rows visible in `/context` and the Context focus surface.
-- v0.16.0 separates local prompt token estimates from provider-reported billing usage in `phonton why-tokens --by-source`; local-only runs now render as `no provider call`, and prompt manifests carry resolved `@...` mention rows plus attribution-only token totals instead of double-counting attachments or MCP/tool context.
-- v0.16.0 tightens extension and MCP diagnostics so `phonton extensions doctor` warns on networked or mutating MCP trust even when a server has not listed explicit permissions.
-- Unified slash commands in the TUI: `/settings`, `/config`, `/status`, `/context`, `/compact`, `/compact-context`, `/compress`, `/problems`, `/diagnostics`, `/retry`, `/repair`, `/why-tokens`, `/ask`, `/plan`, `/approve`, `/goals`, `/switch`, `/focus`, `/diff`, `/code`, `/copy`, `/rerun`, `/stats`, `/stop`, `/review`, `/memory`, `/permissions`, `/trust`, `/model`, `/commands`, `/run`, and `!` all route through the same command registry and prompt drawer.
-- Static syntax verification now covers Rust, Python, JavaScript, TypeScript, JSON, TOML, YAML, HTML, and CSS changed files before review-ready status. Generated code that cannot parse stays failed/unverified instead of becoming a receipt.
-- Failed goals default to a Problems focus view with grouped verifier/provider/quality diagnostics, compact repair hints, and `Alt+P` / `Alt+R` keyboard shortcuts for inspection and repair.
-- `/why-tokens` and `phonton why-tokens --by-source` explain the latest prompt manifest in plain language, including first-attempt, repair-attempt, context/artifact, system, goal, memory, attachment, repo-code, MCP/tool, `@...` mention attribution, retry, compaction, dedupe, and cached-token buckets.
-- v0.15.5 fixes TUI prompt typing and Ask readability: bare `f`, `d`, `p`, and `r` now type normally, focus shortcuts moved to `Alt+F/D/P/R`, the prompt bar shows a static caret rectangle, and Ask answers style inline markdown such as `**bold**`, `*italic*`, and `` `code` ``.
-- v0.15.4 fixes the existing Vite chess quality gate: the zero-token App shell now renders an accessible named-piece legend for king, queen, rook, bishop, knight, and pawn, and the seeded App test asserts that evidence.
-- v0.15.3 fixes stale existing Vite App tests during the zero-token chess UI seed: old placeholder heading assertions in `src/App.test.*` are replaced with a local Vitest server-render test for the generated chess shell.
-- v0.15.2 fixes the existing Vite chess UI hot path: `src/App.tsx`, `src/App.css`, and `src/vite-env.d.ts` seed locally with a playable app shell, repeated UI slices become zero-token no-ops, and the TUI no longer shows a blinking native cursor over the prompt or compact header.
-- v0.15.1 fixes the v0.15.0 hot path: generated Vite chess rules seeds declare a real Vitest suite, the compact header gradient animates while work is active, the Receipt focus shortcut row no longer wraps `d diff` onto a stranded line, and Flight Log PgUp/mouse scrolling works from tail mode.
-- v0.15.0 adds a summary-first proof layer: deterministic Plan, Work, Verification, Failure, Token, Context, and Handoff summaries are derived from typed facts and exported through proof/review surfaces.
-- v0.15.0 expands the Active panel focus surfaces to Plan, Receipt, Problems, Code, Commands, Context, Tokens, and Log so broad work can be inspected without opening the Flight Log.
-- `/plan <goal>` now previews the GoalContract and verification/run plan in the TUI without starting workers; `/approve` starts the selected preview after review.
-- OutcomeLedger proof records now carry persisted context buckets, selected index slices, MCP permission evidence, command-run evidence, and summary bundles for history, review JSON, proof export, and benchmark export.
-- Generated web/runtime verification plans that do not produce runtime proof are surfaced as known gaps and verification findings, not treated as proof of correctness.
-- v0.11 context planning builds a compact repo map, selects only the highest-value code slices under a target budget, exposes omitted code tokens, and labels target-exceeded prompts honestly when one required slice must go over budget.
-- v0.12 enforces lower spend before the provider call: generated app/game goals dispatch as acceptance-slice subtasks, simple/docs/test prompts use small task-class budgets, generated repairs use a sub-1k context target, semantic retrieval top-k and repo maps shrink by task class, MCP result context is capped, and provider output ceilings are lower.
-- v0.14.1 fixes generated-web failure diagnostics: Problems focus now jumps to the changed file named by the verifier, and `src/App.tsx:1:1` diagnostics are normalized for retry policy.
-- v0.14.0 hardens Node verification so stock Vite/Vitest/Jest test scripts run in non-interactive CI mode instead of hanging in watch mode.
-- v0.13.5 seeds the existing Vite/React chess rules/test boundary with a locally verified template before provider UI slices, including recovery from partial invalid `src/chessRules.ts` artifacts without another provider call.
-- v0.13.4 detects existing Vite/React workspaces for chess benchmark prompts that say "use the existing project stack," then starts on source/test slices instead of fragile `package.json` or `index.html` scaffold edits.
-- v0.13.1 hardens generated web-app token behavior: Vite/React chess prompts stay on compact acceptance slices even in partial workspaces, and first-attempt TSX/HTML syntax failures stop before automatic repair.
-- v0.13.0 makes Ask workspace-aware under a bounded context budget and carries forward verified diff export: `phonton diff`, `--stat`, `--name-only`, `/diff`, `/code`, and `d`.
-- v0.12.6 hardens provider contracts further: DeepSeek V4/reasoner routes disable provider thinking for diff-only worker calls, stale v0.12.5 canary cache entries are invalidated, reasoning-only replies fail clearly, and provider tests time out quickly instead of hanging.
-- v0.12.5 blocks bad provider/model routes before goal dispatch: provider readiness now uses a parseable unified-diff canary, empty OpenAI-compatible responses fail immediately, OpenCode/OpenCode Go routes work through `OPENCODE_API_KEY`, and `phonton providers` can list/sync the Models.dev catalog.
-- v0.12.4 cuts wasted repair tokens in generated-app failures: workers stop after repeated verifier/parser diagnostics, redispatch prompts start with prior verifier evidence, stale hunk repairs get explicit guidance, and the Flight Log shows compact `repair` events before bounded retries.
-- v0.12.3 fixes stale generated-test hunks during the chess benchmark: rules/test slices now carry paired current artifacts, and repair attempts include the exact current file named in verifier diagnostics instead of retrying blind.
-- v0.12.2 fixes early generated Vite/React chess slices so Vitest does not fail before test files exist: scaffold slices now request a starter rules module and smoke test, and npm verification waits to run Vitest/Jest discovery scripts until a test file exists.
-- v0.12.1 fixes the playable chess benchmark path: explicit Vite/TypeScript/React prompts now scaffold an npm app contract, use chess.js-backed rules/test slices, carry current artifact snapshots between slices, use compact slice labels instead of repeating the full pasted prompt, and run npm install/test/build verification before review-ready status.
-- `phonton proof export --latest --format json` exports the latest proof bundle from the OutcomeLedger, and `phonton context eval|diff` evaluates deterministic context-selection fixtures before benchmark runs.
-- Ask mode supports `/ask <question>`, scrollable answers, lightweight markdown-style rendering, and bounded read-only workspace context with visible `ctx:` token/file summaries. `phonton ask --no-workspace` keeps the old stateless behavior.
-- Faster multi-goal navigation: the sidebar shows stable goal indexes, `Alt+Up` / `Alt+Down` switches goals even while drafting text, `Alt+1` through `Alt+9` jumps directly, and `/goals` opens a searchable switcher.
-- Review-ready goals now default to a Receipt focus view, with Plan, Problems, Code, Commands, Context, Tokens, and Log tabs in the Active panel plus `p` / `r` / `f` / `d` / `[` / `]` keyboard navigation.
-- Command run receipts stay collapsed by default; the Commands focus view shows status, exit code, duration, and short stdout/stderr previews. `/rerun` repeats the latest command through the same sandbox path and `/copy` copies the current focus view to the Windows clipboard.
-- Saved workspace sessions: use `phonton -r` or `phonton --resume` to reopen the last saved TUI conversation for the current repo.
-- Prompt bar paste artifacts: long or multiline pasted text collapses into a compact colored chip while the full content stays attached to the submitted goal; credential-looking pasted blocks are blocked before they can reach the model.
-- Image path paste/drop artifacts: pasted image file paths collapse into `[image: name.png]` chips and flow into the submitted prompt as image artifacts.
-- Active review/code output is scrollable with the mouse wheel, `PgUp` / `PgDn`, and `Home` / `End`, so large generated diffs do not trap the user at the top of the receipt.
-- Windows clipboard import in the TUI with `Ctrl+V`, including content selected from Windows clipboard history (`Win+V`) when the terminal does not emit bracketed paste directly.
-- Lower-noise worker prompts: first attempts omit bulky diff examples, duplicate repo context slices are deduped, and Flight Log prompt manifests show repo-code, compaction, dedupe, and budget buckets.
-- Resumed sessions keep recent prompt history, and the History view supports in-place filtering and row selection for inspecting previous task receipts.
-- Workspace trust is saved as structured per-workspace records, mirrored into the local store, visible with `/trust current` or `/trust list`, and revocable with `/trust revoke-current`.
-- Sandboxed command runs from the prompt bar with `/run <cmd>` or `!<cmd>`, plus command status, output previews, context meters, and permission mode controls in the TUI and Flight Log.
-- `phonton doctor` setup diagnostics for config, provider key, store, trust, git, cargo, and Nexus config.
-- `phonton plan` preview for task DAGs and the visible GoalContract before edits happen.
-- `phonton review` surfaces for verified diff review payloads, approvals, rejections, rollback, and Markdown receipt export. `phonton diff` exports the verified unified diff or compact file/stat views without opening the TUI. Failed runs can still export a failed/unverified Markdown receipt with diagnostics.
-- `phonton run latest` executes the latest receipt-suggested run command through the sandbox.
-- TUI goal prompts can mention workspace files and images with `@path`; text files become bounded context and image metadata/payloads flow to compatible providers.
-- Review-ready runs now show a handoff receipt in the TUI and persist a minimal outcome ledger for history/review evidence.
-- `phonton memory` commands for inspecting, editing, deleting, pinning, and unpinning local decision memory.
-- `phonton extensions` commands for inspecting resolved skills, steering, MCP servers, profiles, conflicts, and diagnostics.
-- `phonton mcp` commands for listing configured servers and lazily approving tool discovery or tool calls.
-- BYOK provider adapters for Anthropic, OpenAI, OpenRouter, OpenCode, OpenCode Go, Gemini/Google, Cloudflare Workers AI, AgentRouter, DeepSeek, xAI/Grok, Groq, Together, Ollama, and custom OpenAI-compatible endpoints. `phonton doctor --provider` verifies your configured provider with a tiny parseable-diff canary through the same adapter used for runs.
-- `phonton providers list|sync|doctor|import-opencode` exposes Models.dev provider metadata, verifies the configured provider/model route, and can read OpenCode auth on demand without copying or printing secrets.
-- Local store, memory, planner, worker, diff, sandbox, verification, and orchestration crates.
-- Prompt-section token manifests in the Flight Log so system, goal, memory, attachment, MCP, and retry-context costs are inspectable.
-- `phonton demo trust-loop` prints a compact proof-oriented walkthrough of the GoalContract -> verification -> receipt -> memory loop for first-run demos, with `--json` for reproducible demos.
-- Semantic indexing behind the CLI stack for repo-aware workflows.
-
-## What Is Still Early
-
-Phonton is not yet as polished as Codex, Claude Code, Cursor, or Windsurf. It has fewer integrations, less onboarding polish, narrower public documentation, and no mature hosted/team workflow yet.
-
-The current release target is a public alpha for real Rust repo tasks. Phonton can ask configured models to write app-sized changes, but quality is only claimed after plan review, sandboxed edits, verification, and human review. Use it if you are comfortable running a Rust binary, reading diagnostics, and filing sharp bug reports.
-
-## Install
-
-The easiest install path is npm. This downloads a prebuilt GitHub Release binary when the package installs.
+The easiest path to install is via npm. The wrapper automatically downloads the prebuilt binary for your platform.
 
 ```bash
+# Install globally
 npm install -g phonton-cli
-phonton
-```
-
-Run without installing:
-
-```bash
-npx phonton-cli
-```
 
-Cargo still works if you prefer building from source. Rust is required for the Cargo path.
-
-macOS/Linux:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/phonton-dev/phonton-cli/main/scripts/install.sh | sh
-```
-
-Windows PowerShell:
-
-```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/phonton-dev/phonton-cli/main/scripts/install.ps1)))
-```
-
-Direct Cargo install:
-
-```bash
-cargo install --git https://github.com/phonton-dev/phonton-cli --tag v0.16.2 phonton-cli --locked --force
-```
-
-Check the install:
-
-```bash
+# Verify your installation
 phonton version
 phonton doctor
 ```
 
-## Release Channels
+### Alternative Installers
 
-Phonton uses GitHub branches and releases as install channels:
+* **Shell Script (macOS/Linux)**:
+  ```bash
+  curl -fsSL https://raw.githubusercontent.com/phonton-dev/phonton-cli/main/scripts/install.sh | sh
+  ```
+* **PowerShell (Windows)**:
+  ```powershell
+  & ([scriptblock]::Create((irm https://raw.githubusercontent.com/phonton-dev/phonton-cli/main/scripts/install.ps1)))
+  ```
+* **Cargo (From Source)**:
+  ```bash
+  cargo install --git https://github.com/phonton-dev/phonton-cli --tag v0.19.0 phonton-cli --locked --force
+  ```
 
-| Channel | Install | Use when |
-|---|---|---|
-| Stable | `cargo install --git https://github.com/phonton-dev/phonton-cli --tag v0.16.2 phonton-cli --locked --force` | You want the best validated public alpha |
-| Dev | `cargo install --git https://github.com/phonton-dev/phonton-cli --branch dev phonton-cli --locked --force` | You want next-release integration changes |
-| Nightly | `cargo install --git https://github.com/phonton-dev/phonton-cli --branch nightly phonton-cli --locked --force` | You want daily snapshots and can tolerate breakage |
-| Main | `cargo install --git https://github.com/phonton-dev/phonton-cli --branch main phonton-cli --locked --force` | You want the current release branch tip |
+---
 
-For the channel policy and automation, read [docs/RELEASE_CHANNELS.md](docs/RELEASE_CHANNELS.md).
+## ⚖️ How We Compare
 
-## Build From Source
+| Feature | Phonton CLI | Claude Code | Cursor | Aider |
+|---|---|---|---|---|
+| **Privacy Model** | **100% Direct (No Proxy)** | Anthropic Proxy | Cursor Proxy | Direct (No Proxy) |
+| **Telemetry** | **Zero** | Opt-out | Opt-out | Optional |
+| **Multi-Model Support** | **All (BYOK & Local)** | Anthropic Only | Pre-selected | Many |
+| **Subscription Fee** | **$0 (Open Source)** | Usage-based | $20/month | $0 (Open Source) |
+| **Execution Loop** | **Full Plan/Edit/Verify** | Interactive Chat | Interactive Chat | Interactive Chat |
+| **Verification Gates** | **Mandatory 4-Layer** | Manual/Run Command | Manual | Optional |
+| **Memory Spine** | **Semantic SQLite** | None | Simple Context | None |
 
-```bash
-git clone https://github.com/phonton-dev/phonton-cli.git
-cd phonton-cli
-cargo build --release -p phonton-cli
-```
+---
 
-Run the binary:
+## 🔄 The Autonomous ADE Loop
 
-```bash
-./target/release/phonton
+```mermaid
+flowchart TD
+    Goal["Goal (User Request)"] --> Plan["1. Goal Decomposition (Planner)"]
+    Plan --> Graph["2. PlanGraph & Conflict Groups Staged"]
+    Graph --> Dispatch["3. Concurrent / Serialized Worker Dispatch"]
+    Dispatch --> Edit["4. Bounded Code Modifications (Diff-Only)"]
+    Edit --> Verify{"5. Strict Verification Gate"}
+    Verify -- FAIL: Surgical Repair Prompt --> Edit
+    Verify -- PASS --> Review["6. Reviewable Handoff (HandoffPacket)"]
+    Review --> Remember["7. SQLite Memory & Session Snapshot Saved"]
 ```
 
-On Windows:
+---
 
-```powershell
-.\target\release\phonton.exe
-```
+## 🚀 New in v0.19.0: Swarm Planning & Pluggable Indices
 
-## Configure A Provider
+* **Conflict-Aware Swarm Scheduling (`PlanGraph`)**: Broad goals are decomposed into collaborative swarms. Overlapping touch scopes are isolated into Conflict Groups and serialized, while independent subtasks run concurrently to optimize execution time.
+* **Pluggable Code Indexing**: Upgraded `phonton-index` with a pluggable `CodeRetriever` trait. Supports default high-performance `local-hnsw` search and external `qdrant` HTTP vector storage for larger enterprise repositories.
+* **Dynamic MCP Capability Discovery**: Run `phonton mcp capabilities <server-id> [--yes]` to preview server info, exposed tools, and sandbox permission proposals safely before initiating any tool execution.
+* **Robust Browser Verification**: Dynamically injected `NODE_PATH` resolution guarantees Playwright DOM and interaction tests run flawlessly on isolated temp directories and production workspaces alike.
 
-Phonton reads `~/.phonton/config.toml` and also checks provider-specific environment variables.
+---
+
+## ⚙️ Configuration
 
-Minimal config:
+Configure your direct providers and indexing backend in `~/.phonton/config.toml`:
 
 ```toml
 [provider]
-name = "gemini"
-model = "gemma-4-31b-it"
-
-[budget]
-max_tokens = 120000
-max_usd_cents = 200
-```
-
-Environment-variable setup examples:
-
-```bash
-export ANTHROPIC_API_KEY="..."
-export OPENAI_API_KEY="..."
-export GEMINI_API_KEY="..."
-export OPENROUTER_API_KEY="..."
-export CLOUDFLARE_API_TOKEN="..."
-export CLOUDFLARE_ACCOUNT_ID="..."
-```
-
-Windows PowerShell:
-
-```powershell
-$env:GEMINI_API_KEY = "..."
-$env:CLOUDFLARE_API_TOKEN = "..."
-$env:CLOUDFLARE_ACCOUNT_ID = "..."
-```
+name = "deepseek"
+model = "deepseek-v4-flash"
 
-Cloudflare Workers AI uses the OpenAI-compatible endpoint. Set
-`name = "cloudflare"` and the default model is `@cf/moonshotai/kimi-k2.6`.
-Set `provider.account_id` or `CLOUDFLARE_ACCOUNT_ID` for the Workers AI account.
-`provider.base_url` remains available for a full
-`https://api.cloudflare.com/client/v4/accounts/<id>/ai/v1` base URL override.
+[provider.keys]
+deepseek = "sk-deepseek-api-key-here"
+anthropic = "sk-ant-api-key-here"
+openai = "sk-proj-openai-key-here"
 
-Check the install:
-
-```bash
-phonton doctor
-phonton doctor --provider
+[index]
+backend = "local-hnsw"
 ```
 
-`phonton doctor --provider` proves the configured key/model/base URL can make a real completion call. It does not claim every listed provider works for every account, model name, quota state, or proxy configuration.
-
-## CLI Commands
-
-```text
-phonton                 Launch the interactive TUI
-phonton -r              Resume the saved TUI session for this workspace
-phonton init            Create ~/.phonton/config.toml if it is missing
-phonton ask [flags] <q> Workspace-aware Q&A using the configured provider
-phonton goal [flags] <p> Execute one goal without launching the TUI
-phonton demo trust-loop Print the evidence-trail demo loop
-phonton doctor          Check config, store, trust, git, cargo, and Nexus
-phonton plan <goal>     Preview the task DAG and GoalContract without changing files
-phonton review          Show verified diff review payloads
-phonton diff            Print verified unified diffs from review-ready tasks
-phonton run latest      Run the latest receipt-suggested command
-phonton memory list     Inspect local decision memory
-phonton extensions      Install and inspect skills, steering, MCP servers, and profiles
-phonton mcp list        Show configured MCP servers without starting them
-phonton config path     Print the resolved config file path
-phonton config show     Dump resolved config as TOML
-phonton version         Print version
-```
-
-Inside the TUI prompt bar:
-
-```text
-/settings, /config      Open provider/model/budget settings
-/status                 Show version, provider, model, workspace, and token state
-/review                 Show review receipt guidance for the selected goal
-/ask <question>         Ask a bounded workspace question without queueing a goal
-/plan <goal>            Preview a GoalContract and plan without execution
-/approve                Execute the selected plan preview
-/diff, /code, d         Jump to verified Code/Diff focus
-/memory                 Inspect local decision memory
-/permissions            Show sandbox, trust, and approval status
-/trust                  Show or revoke workspace trust records
-/model set <name>       Save a model preference
-/commands               Show slash-command and keyboard help
-/run <cmd>              Run a sandboxed command
-!<cmd>                  Shorthand for a sandboxed command
-Ctrl+V                  Paste from the Windows clipboard
-Ctrl+U / Ctrl+K         Clear before / after cursor
-PgUp / PgDn             Scroll the Active receipt/code surface
-Mouse wheel             Scroll the visible Active, Ask, or Flight Log surface
-Tab                     Complete slash commands
-```
-
-Plan preview:
-
-```bash
-phonton plan --json "add input validation to config loading"
-```
+To enable the external **Qdrant** backend:
 
-The text preview shows the visible GoalContract, including acceptance criteria,
-likely files, verification plan, run plan, assumptions, and clarifications.
-
-Headless goal execution for CI and benchmark harnesses:
-
-```bash
-phonton goal --prompt-file prompt.md --yes --permission-mode full-access --timeout-seconds 900 --json
-```
-
-The headless command runs the same planner, worker, verifier, review receipt,
-memory, extension, MCP, and OutcomeLedger path used by the TUI. `--yes`
-records workspace trust for the current run, and `--permission-mode` keeps the
-automation posture explicit.
-
-Review latest completed task:
-
-```bash
-phonton review latest
-phonton review latest --markdown
-phonton review approve latest
-phonton review reject latest
-```
-
-Run the latest suggested command from a review receipt:
-
-```bash
-phonton run latest
-phonton run latest --index 2
+```toml
+[index]
+backend = "qdrant"
+qdrant_url = "http://127.0.0.1:6333"
+qdrant_collection = "phonton-code"
 ```
 
-Memory management:
-
-```bash
-phonton memory list --json
-phonton memory edit <id> "updated rationale"
-phonton memory pin <id>
-phonton memory delete <id>
-```
+---
 
-Extension visibility:
+## 🛠️ Commands Reference
 
 ```bash
-phonton extensions catalog
-phonton extensions install context7
-phonton extensions install https://github.com/phonton-dev/phonton-review-gate-extension
-phonton extensions new ./my-extension skill
-phonton extensions list --json
-phonton extensions doctor --json
-phonton extensions validate --json
-phonton skills list --json
-phonton steering list --json
-phonton mcp list --json
-```
-
-## How Phonton Handles Context
-
-<p align="center">
-  <img src="assets/readme/context-efficiency.png" alt="Diagram contrasting whole repo context with compact context packs and verified diffs">
-</p>
-
-Phonton is built around a simple rule: do not blindly dump the whole repo into the model.
-
-```mermaid
-flowchart TD
-    Repo["Local repo"] --> Index["Source index"]
-    Index --> Planner["Planner"]
-    Planner --> Pack["Task-specific context"]
-    Pack --> Worker["Worker"]
-    Worker --> Verify["Verify"]
-    Verify --> Review["Review"]
-    Review --> Store["Memory and event store"]
-    Store --> Planner
-```
-
-The intended result is lower context waste and better reviewability. The honest way to prove that is with benchmarks, so this repo includes a benchmark harness instead of hard-coded marketing numbers.
-
-## Benchmarks
-
-Run the plan benchmark harness:
+# Launch the interactive Ratatui TUI
+phonton
 
-```powershell
-.\scripts\benchmark-plan.ps1
-```
+# Run a goal non-interactively through the full plan/edit/verify pipeline
+phonton goal "add input validation to config loading" --yes
 
-It runs repeatable planning tasks, captures estimated Phonton tokens versus the planner's naive baseline, and writes Markdown plus JSON reports to `benchmarks/results/`.
+# Preview the subtask graph and Conflict Groups without editing files
+phonton plan "refactor auth layer"
 
-Export the latest real OutcomeLedger run:
+# Audit configuration, API keys, database, and vector index connectivity
+phonton doctor --provider
 
-```powershell
+# Export benchmark telemetry from the latest run
 phonton benchmark export --latest --format json
-phonton proof export --latest --format json
-phonton context eval fixtures/context.json --format json
-phonton context diff --indexed --non-indexed fixtures/context.json --format json
-phonton why-tokens --by-source
-```
-
-Benchmark exports label token comparability explicitly: `token_usage_source`, `execution_mode`, `provider_call_count`, `token_claim_eligible`, and `benchmark_warnings`. Only verified provider runs with `token_claim_eligible: true` are valid for public token-efficiency claims. Estimated, local-template, mixed, unavailable, and failed runs remain useful product evidence, but they must stay out of headline token comparisons.
-
-Read the methodology in [docs/BENCHMARKS.md](docs/BENCHMARKS.md).
-
-Important: benchmark output is evidence, not a slogan. Do not claim "X percent savings" publicly until you can reproduce it on multiple real tasks and include the raw report.
-
-## Architecture
-
-```mermaid
-flowchart TB
-    CLI["phonton-cli"] --> Planner["phonton-planner"]
-    CLI --> Orchestrator["phonton-orchestrator"]
-    Orchestrator --> Worker["phonton-worker"]
-    Orchestrator --> Verify["phonton-verify"]
-    Worker --> Providers["phonton-providers"]
-    Worker --> Context["phonton-context"]
-    Context --> Index["phonton-index"]
-    Verify --> Diff["phonton-diff"]
-    Verify --> Sandbox["phonton-sandbox"]
-    Planner --> Memory["phonton-memory"]
-    Memory --> Store["phonton-store"]
-    Types["phonton-types"] --> CLI
-    Types --> Orchestrator
-    Types --> Worker
-```
-
-Repository layout:
-
-- `phonton-cli` - terminal UI and user-facing command surface.
-- `phonton-planner` - goal decomposition and plan preview.
-- `phonton-orchestrator` - task state, dependencies, retries, and event flow.
-- `phonton-worker` - model-call loop, tool policy, and patch generation.
-- `phonton-verify` - syntax/type/test/decision checks before review.
-- `phonton-index` - local source indexing and semantic retrieval.
-- `phonton-context` - task-specific context compilation.
-- `phonton-diff` - diff application and rollback support.
-- `phonton-memory` / `phonton-store` - local persistence and decision memory.
-- `phonton-providers` - BYOK provider adapters.
-- `phonton-sandbox` - command execution policy.
-- `phonton-types` - shared domain contracts.
-
-## Release Checks
-
-Before cutting a release:
-
-```powershell
-.\scripts\release-check.ps1
 ```
 
-The script runs formatting, clippy, tests, release build, doctor, and the plan benchmark harness.
-
-Manual checks worth doing before a public release:
-
-- Fresh clone install on Windows, macOS, and Linux.
-- `phonton doctor --provider` with at least one hosted provider, confirming both model discovery and a completion call.
-- One real repo task from goal to reviewable verified diff.
-- Benchmark report committed or attached to the release notes.
-- No secrets printed in logs, screenshots, or benchmark output.
+---
 
-## Comparison
+## 🗺️ Crate Architecture
 
-Phonton is not trying to win by pretending the incumbents are weak.
+Phonton is written entirely in Rust for performance, correctness, and low memory overhead:
+* `phonton-cli`: Interactive TUI, headless runner, benchmark, and CLI commands.
+* `phonton-planner`: Multi-model goal decomposition and `PlanGraph` sidecar staging.
+* `phonton-orchestrator`: Swarm scheduler, Conflict Group serialization, and verifier pipeline execution.
+* `phonton-worker`: Highly optimized context assembler and diff-only code modifier.
+* `phonton-index`: Local HNSW symbol index and Qdrant integration.
+* `phonton-verify`: Four-layer static checkers (Tree-Sitter, Cargo, Playwright Browser/Screenshot).
+* `phonton-mcp`: Lazy initialization client, permission gates, and capabilities descriptor.
 
-| Tool | Strongest fit | Where Phonton is trying to be different |
-|---|---|---|
-| Codex | Mature agent workflow, cloud/editor/CLI integration | Local-first ADE kernel, BYOK, explicit verification and review surfaces |
-| Claude Code | Excellent terminal-native coding agent | Less chat-first, more plan/verify/review oriented |
-| Cursor | Polished AI editor experience | Less editor polish, more auditable repo workflow |
-| Windsurf | Agentic IDE workflow | Narrower release scope, explicit local-first positioning |
-| Phonton CLI | Verified local ADE loop for serious repo tasks | Early product, smaller ecosystem, benchmark claims still being built |
+---
 
-## Development
+## 💖 Star History
 
-```bash
-cargo fmt --all -- --check
-cargo clippy --locked --workspace --all-targets -- -D warnings
-cargo test --locked --workspace
-cargo build --locked --release -p phonton-cli
-```
+If you support a privacy-first, fully autonomous developer experience, please leave us a star!
 
-Run from source:
+[![Star History Chart](https://api.star-history.com/chart?repos=phonton-dev/phonton-cli&type=date&legend=top-left)](https://www.star-history.com/?repos=phonton-dev%2Fphonton-cli&type=date&legend=top-left)
 
-```bash
-cargo run -p phonton-cli -- doctor
-cargo run -p phonton-cli -- plan "add input validation to config loading"
-```
+---
 
-## License
+## 📄 License
 
 Licensed under either of:
+* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
+* MIT License ([LICENSE-MIT](LICENSE-MIT))
 
-- Apache License, Version 2.0
-- MIT License
-
-at your option.
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/chart?repos=phonton-dev/phonton-cli&type=date&legend=top-left)](https://www.star-history.com/?repos=phonton-dev%2Fphonton-cli&type=date&legend=top-left)
+At your option.

package/npm/bin/phonton.js

@@ -4,18 +4,14 @@ const fs = require("fs");
 const path = require("path");
 const { spawn, spawnSync } = require("child_process");
 
-const packageJson = require("../../package.json");
 const binaryName = process.platform === "win32" ? "phonton.exe" : "phonton";
 const configuredBinary = process.env.PHONTON_BINARY || process.env.PHONTON_CLI_BINARY;
 const binaryPath = configuredBinary
   ? path.resolve(configuredBinary)
   : path.join(__dirname, "..", "vendor", binaryName);
-const vendorDir = path.join(__dirname, "..", "vendor");
-const markerPath = path.join(vendorDir, "version.json");
 
 function ensureBinary() {
-  if (configuredBinary && fs.existsSync(binaryPath)) {
-    assertBinaryVersion(binaryPath);
+  if (fs.existsSync(binaryPath)) {
     return;
   }
 
@@ -24,53 +20,11 @@ function ensureBinary() {
     process.exit(1);
   }
 
-  if (fs.existsSync(binaryPath) && vendorMatchesPackage() && binaryVersionMatches(binaryPath).ok) {
-    return;
-  }
-
-  fs.rmSync(vendorDir, { recursive: true, force: true });
-
-  const installScript = process.env.PHONTON_INSTALL_SCRIPT || path.join(__dirname, "..", "install.js");
+  const installScript = path.join(__dirname, "..", "install.js");
   const result = spawnSync(process.execPath, [installScript], { stdio: "inherit" });
   if (result.status !== 0 || !fs.existsSync(binaryPath)) {
     process.exit(result.status || 1);
   }
-  assertBinaryVersion(binaryPath);
-}
-
-function vendorMatchesPackage() {
-  try {
-    const marker = JSON.parse(fs.readFileSync(markerPath, "utf8"));
-    return (
-      marker.version === packageJson.version &&
-      marker.platform === process.platform &&
-      marker.arch === process.arch
-    );
-  } catch (_error) {
-    return false;
-  }
-}
-
-function assertBinaryVersion(candidate) {
-  const check = binaryVersionMatches(candidate);
-  if (!check.ok) {
-    console.error(`Installed Phonton binary is stale or invalid: expected ${check.expected}, got ${check.output}`);
-    if (!configuredBinary) {
-      fs.rmSync(vendorDir, { recursive: true, force: true });
-    }
-    process.exit(1);
-  }
-}
-
-function binaryVersionMatches(candidate) {
-  const result = spawnSync(candidate, ["version"], { encoding: "utf8" });
-  const output = `${result.stdout || ""}${result.stderr || ""}`.trim() || "no output";
-  const expected = `phonton ${packageJson.version}`;
-  return {
-    ok: result.status === 0 && output.includes(expected),
-    expected,
-    output,
-  };
 }
 
 ensureBinary();

package/npm/install.js

@@ -12,7 +12,6 @@ const repo = "phonton-dev/phonton-cli";
 const version = packageJson.version;
 const tag = process.env.PHONTON_RELEASE_TAG || (version.includes("nightly") ? "nightly" : `v${version}`);
 const vendorDir = path.join(__dirname, "vendor");
-const markerPath = path.join(vendorDir, "version.json");
 
 const targets = {
   "linux-x64": {
@@ -56,20 +55,6 @@ download(url, archivePath)
     if (process.platform !== "win32") {
       fs.chmodSync(binaryPath, 0o755);
     }
-    fs.writeFileSync(
-      markerPath,
-      `${JSON.stringify(
-        {
-          version,
-          tag,
-          asset: target.asset,
-          platform: process.platform,
-          arch: process.arch,
-        },
-        null,
-        2,
-      )}\n`,
-    );
     console.log(`Installed Phonton CLI ${tag} for ${process.platform}-${process.arch}`);
   })
   .catch((error) => {

package/npm/test-wrapper.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 const fs = require("fs");
-const os = require("os");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
@@ -19,118 +18,24 @@ if (!binary) {
   process.exit(1);
 }
 
-function runWrapper(args) {
-  const result = spawnSync(process.execPath, [path.join(root, "npm", "bin", "phonton.js"), ...args], {
-    cwd: root,
-    encoding: "utf8",
-    env: {
-      ...process.env,
-      PHONTON_BINARY: binary,
-    },
-  });
+const result = spawnSync(process.execPath, [path.join(root, "npm", "bin", "phonton.js"), "version"], {
+  cwd: root,
+  encoding: "utf8",
+  env: {
+    ...process.env,
+    PHONTON_BINARY: binary,
+  },
+});
 
-  process.stdout.write(result.stdout || "");
-  process.stderr.write(result.stderr || "");
+process.stdout.write(result.stdout || "");
+process.stderr.write(result.stderr || "");
 
-  if (result.status !== 0) {
-    process.exit(result.status || 1);
-  }
-
-  return result.stdout;
+if (result.status !== 0) {
+  process.exit(result.status || 1);
 }
 
-const versionOutput = runWrapper(["version"]);
-
 const expected = `phonton ${packageJson.version}`;
-if (!versionOutput.includes(expected)) {
+if (!result.stdout.includes(expected)) {
   console.error(`Expected npm wrapper to report ${expected}.`);
   process.exit(1);
 }
-
-testStaleVendorReinstall();
-
-const goal = "add input validation to config loading";
-const planOutput = runWrapper(["plan", "--json", "--no-memory", goal]);
-let planJson;
-try {
-  planJson = JSON.parse(planOutput);
-} catch (error) {
-  console.error(`Expected plan --json to emit parseable JSON: ${error.message}`);
-  process.exit(1);
-}
-
-if (!planJson.goal_contract) {
-  console.error("Expected plan --json to expose goal_contract at the top level.");
-  process.exit(1);
-}
-
-if (planJson.goal_contract.goal !== goal) {
-  console.error("Expected plan --json goal_contract.goal to match the requested goal.");
-  process.exit(1);
-}
-
-function testStaleVendorReinstall() {
-  const vendorDir = path.join(root, "npm", "vendor");
-  const vendorBinary = path.join(vendorDir, binaryName);
-  const markerPath = path.join(vendorDir, "version.json");
-  const installScript = path.join(os.tmpdir(), `phonton-test-install-${process.pid}.js`);
-
-  fs.rmSync(vendorDir, { recursive: true, force: true });
-  fs.mkdirSync(vendorDir, { recursive: true });
-  fs.copyFileSync(binary, vendorBinary);
-  if (process.platform !== "win32") {
-    fs.chmodSync(vendorBinary, 0o755);
-  }
-  fs.writeFileSync(
-    markerPath,
-    JSON.stringify({
-      version: "0.0.0-stale",
-      platform: process.platform,
-      arch: process.arch,
-    }),
-  );
-
-  fs.writeFileSync(
-    installScript,
-    `
-const fs = require("fs");
-const path = require("path");
-const vendorDir = ${JSON.stringify(vendorDir)};
-const binary = ${JSON.stringify(binary)};
-const binaryName = ${JSON.stringify(binaryName)};
-const version = ${JSON.stringify(packageJson.version)};
-fs.mkdirSync(vendorDir, { recursive: true });
-fs.copyFileSync(binary, path.join(vendorDir, binaryName));
-if (process.platform !== "win32") fs.chmodSync(path.join(vendorDir, binaryName), 0o755);
-fs.writeFileSync(path.join(vendorDir, "version.json"), JSON.stringify({
-  version,
-  platform: process.platform,
-  arch: process.arch,
-}, null, 2));
-`,
-  );
-
-  try {
-    const result = spawnSync(process.execPath, [path.join(root, "npm", "bin", "phonton.js"), "version"], {
-      cwd: root,
-      encoding: "utf8",
-      env: {
-        ...process.env,
-        PHONTON_INSTALL_SCRIPT: installScript,
-        PHONTON_BINARY: "",
-        PHONTON_CLI_BINARY: "",
-      },
-    });
-
-    process.stdout.write(result.stdout || "");
-    process.stderr.write(result.stderr || "");
-
-    if (result.status !== 0 || !result.stdout.includes(expected)) {
-      console.error("Expected npm wrapper to refresh stale vendor binary metadata.");
-      process.exit(result.status || 1);
-    }
-  } finally {
-    fs.rmSync(installScript, { force: true });
-    fs.rmSync(vendorDir, { recursive: true, force: true });
-  }
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phonton-cli",
-  "version": "0.16.2",
+  "version": "0.19.0",
   "description": "Local-first agentic development terminal with context packs, source handles, and verification gates.",
   "license": "MIT OR Apache-2.0",
   "homepage": "https://github.com/phonton-dev/phonton-cli#readme",
@@ -41,5 +41,9 @@
   ],
   "engines": {
     "node": ">=18"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "playwright": "^1.60.0"
   }
 }