npm - phonton-cli - Versions diffs - 0.16.2 → 0.17.1 - Mend

phonton-cli 0.16.2 → 0.17.1

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

Files changed (2) hide show

package/README.md +93 -428
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -2,514 +2,179 @@
   <img src="assets/readme/phonton-cli-logo.png" width="112" alt="Phonton CLI logo">
 </p>
-<h1 align="center">Phonton CLI · v0.16.2</h1>
+<h1 align="center">Phonton CLI · v0.17.1</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>Verified code changes with local repo memory.</strong><br>
+  A local-first agentic development environment (ADE) for developers who want autonomous code changes without giving up review control.
 </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">
+  <img alt="release" src="https://img.shields.io/badge/release-v0.17.1-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.
-> 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.
+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 reliable and transparent.
 <p align="center">
   <img src="assets/readme/phonton-cli-hero.png" alt="Phonton CLI hero with terminal UI preview">
 </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
-```
-That gives Phonton a different shape from an IDE assistant or a chat-first terminal assistant:
-- **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.
-## Trust Demo Loop
-The product promise is intentionally narrow:
+## ⚡ Quick Install
-```text
-goal -> plan -> edit -> verify -> review -> remember
-```
-Try the proof-oriented demo text before configuring a provider:
-```bash
-phonton demo trust-loop
-phonton demo trust-loop --json
-```
-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 install path is npm. This downloads a prebuilt GitHub Release binary during installation.
 ```bash
+# Install globally via npm
 npm install -g phonton-cli
-phonton
-```
-Run without installing:
-```bash
+# Or run directly without installing
 npx phonton-cli
 ```
-Cargo still works if you prefer building from source. Rust is required for the Cargo path.
-macOS/Linux:
+### Alternative Installation Methods
+**macOS / Linux Shell Installer:**
 ```bash
 curl -fsSL https://raw.githubusercontent.com/phonton-dev/phonton-cli/main/scripts/install.sh | sh
 ```
-Windows PowerShell:
+**Windows PowerShell Installer:**
 ```powershell
 & ([scriptblock]::Create((irm https://raw.githubusercontent.com/phonton-dev/phonton-cli/main/scripts/install.ps1)))
 ```
-Direct Cargo install:
+**Direct Cargo Install (Builds from Source):**
 ```bash
-cargo install --git https://github.com/phonton-dev/phonton-cli --tag v0.16.2 phonton-cli --locked --force
+cargo install --git https://github.com/phonton-dev/phonton-cli --tag v0.17.1 phonton-cli --locked --force
 ```
-Check the install:
+Verify your installation:
 ```bash
 phonton version
 phonton doctor
 ```
-## Release Channels
-Phonton uses GitHub branches and releases as install channels:
-| 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).
-## Build From Source
-```bash
-git clone https://github.com/phonton-dev/phonton-cli.git
-cd phonton-cli
-cargo build --release -p phonton-cli
-```
-Run the binary:
-```bash
-./target/release/phonton
-```
-On Windows:
-```powershell
-.\target\release\phonton.exe
-```
-## Configure A Provider
-Phonton reads `~/.phonton/config.toml` and also checks provider-specific environment variables.
-Minimal config:
-```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="..."
-```
+## 💡 Why Phonton
-Windows PowerShell:
+Most coding agents start with chat. Phonton starts with the engineering loop:
-```powershell
-$env:GEMINI_API_KEY = "..."
-$env:CLOUDFLARE_API_TOKEN = "..."
-$env:CLOUDFLARE_ACCOUNT_ID = "..."
+```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
 ```
-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.
+This structural architecture gives Phonton a distinct advantage for serious code editing:
-Check the install:
+- **Review First:** Diffs are first-class, fully interactive terminal surfaces, not buried in a chat stream.
+- **Verification First:** Diffs are validated via Tree-sitter syntax checks and test suites before presentation.
+- **Local First:** Settings, session store, local history, and vector memory live entirely on your machine.
+- **AST Quality Gates:** In-process tree-sitter validators catch parsing issues across Rust, Python, TypeScript, and more in **under 50ms**.
+- **BYOK (Bring Your Own Key):** Connect directly to Anthropic, OpenAI, DeepSeek, Gemini, xAI, or local Ollama with zero server proxying.
-```bash
-phonton doctor
-phonton doctor --provider
-```
+---
-`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
-```
+## 🏆 Benchmark Results
-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
-```
+Phonton prioritizes surgical context retrieval over massive, expensive whole-repo context dumps. We run continuous, auditable benchmarks against popular coding agents under the exact same prompts, fixtures, and execution bounds.
-Plan preview:
+### 1. Headline Benchmarking Comparison
-```bash
-phonton plan --json "add input validation to config loading"
-```
+| Suite | Tool | Status | Elapsed Time | Input Tokens | Output Tokens | Cached Tokens | Total Tokens | Changed Paths |
+|---|---|---|---|---|---|---|---|---:|
+| **`02-bugfix`** | **Phonton v0.17.1** | **verified_success** | **38.6s** | **2,006** | **730** | **1,280** | **2,736** | **1** |
+| | Claude Code | completed | 58.0s | 212 | 3,261 | 163,137 | 203,018 | 1 |
+| | DeepSeek-TUI | completed | 88.2s | 28,490 | 1,210 | 22,400 | 52,100 | 1 |
+| | Gemini CLI | completed | 199.8s | 95,008 | 1,948 | 113,770 | 214,287 | 1 |
+| | Codex CLI | completed | 218.9s | 379,331 | 5,515 | 346,624 | 384,846 | 2 |
+| **`03-refactor`** | **Phonton v0.17.1** | **verified_success** | **50.6s** | **5,164** | **5,034** | **768** | **10,198** | **2** |
+| | Gemini CLI | completed | 118.4s | 76,079 | 5,092 | 453,239 | 536,583 | 2 |
+| | DeepSeek-TUI | completed | 112.5s | 42,300 | 4,890 | 55,600 | 102,790 | 2 |
+| | Claude Code | completed | 156.7s | 2,821 | 11,781 | 176,187 | 224,947 | 2 |
+| | Codex CLI | completed | 229.0s | 451,983 | 8,479 | 412,416 | 460,462 | 2 |
-The text preview shows the visible GoalContract, including acceptance criteria,
-likely files, verification plan, run plan, assumptions, and clarifications.
+### 2. Core Takeaways
+* **98%+ Token Savings:** Swapping generic directory dumps for high-speed local semantic memories gives Phonton a massive token-usage saving.
+* **Microsecond Context Retrieval:** The concurrent HNSW vector index searches 1,000 architectural concepts in just **158.697µs**, yielding highly targeted model prompts.
+* **Grammar Quality Guard:** Preflight checks compile and verify AST structures locally before touching the git tree, guaranteeing syntax safety.
-Headless goal execution for CI and benchmark harnesses:
+---
-```bash
-phonton goal --prompt-file prompt.md --yes --permission-mode full-access --timeout-seconds 900 --json
-```
+## ⚙️ Quick Start & Setup
-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.
+### 1. Configure a Provider
+Phonton looks for credentials inside `~/.phonton/config.toml`. Create it with a minimal configuration:
-Review latest completed task:
+```toml
+[provider]
+name = "deepseek"
+model = "deepseek-v4-flash"
-```bash
-phonton review latest
-phonton review latest --markdown
-phonton review approve latest
-phonton review reject latest
+[provider.keys]
+deepseek = "sk-deepseek-api-key-here"
+anthropic = "sk-ant-api-key-here"
 ```
-Run the latest suggested command from a review receipt:
+### 2. Auto-Import Credentials
+Alternatively, automatically import API keys from standard environments:
 ```bash
-phonton run latest
-phonton run latest --index 2
+export DEEPSEEK_API_KEY="sk-..."
+phonton providers import-opencode
 ```
-Memory management:
+### 3. Verify Configuration
+Ensure everything is set up correctly:
 ```bash
-phonton memory list --json
-phonton memory edit <id> "updated rationale"
-phonton memory pin <id>
-phonton memory delete <id>
+phonton doctor --provider
 ```
-Extension visibility:
+### 4. Run the Trust-Loop Demo
+Explore Phonton's evidence trail (GoalContract, AST checking, verification gates) locally without sending remote model calls:
 ```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:
-```powershell
-.\scripts\benchmark-plan.ps1
-```
-It runs repeatable planning tasks, captures estimated Phonton tokens versus the planner's naive baseline, and writes Markdown plus JSON reports to `benchmarks/results/`.
-Export the latest real OutcomeLedger run:
-```powershell
-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
+phonton demo trust-loop
 ```
-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.
+## 🛠️ CLI Command Reference
-Manual checks worth doing before a public release:
+Execute commands directly from your shell or use the interactive Ratatui TUI dashboard.
-- 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.
+* **`phonton`**: Starts the interactive Ratatui terminal UI dashboard for managing tasks, reviewing plans, and executing rollbacks.
+* **`phonton goal "<prompt>"`**: Submit a long-running, multi-step engineering goal in headless mode. Supports `--prompt-file <path>` and `--yes` for automated scripts.
+* **`phonton ask "<question>"`**: Ask a workspace-aware, semantic question. Mentions (e.g. `@src/lib.rs`) are automatically gathered into context.
+* **`phonton diff`**: Export verified unified diffs from completed subtasks in the task store. Supports `--stat` and `--name-only`.
+* **`phonton doctor`**: Run diagnostics on tool installations (git, cargo, npm) and provider key routing.
+* **`phonton extensions`**: Manage extension packs. Install MCP servers, custom profiles, or steering guides.
+  * Install an MCP recipe: `phonton extensions install github`
-## Comparison
+---
-Phonton is not trying to win by pretending the incumbents are weak.
+## 🏁 Release Channels
-| Tool | Strongest fit | Where Phonton is trying to be different |
+| Channel | Install Command | Use Case |
 |---|---|---|
-| 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
-```bash
-cargo fmt --all -- --check
-cargo clippy --locked --workspace --all-targets -- -D warnings
-cargo test --locked --workspace
-cargo build --locked --release -p phonton-cli
-```
-Run from source:
+| **Stable** | `cargo install --git https://github.com/phonton-dev/phonton-cli --tag v0.17.1 phonton-cli --locked --force` | Best validated release |
+| **Dev** | `cargo install --git https://github.com/phonton-dev/phonton-cli --branch dev phonton-cli --locked --force` | Upcoming release features |
+| **Nightly** | `cargo install --git https://github.com/phonton-dev/phonton-cli --branch nightly phonton-cli --locked --force` | Daily automated snapshots |
-```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
-- MIT License
+* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
+* MIT License ([LICENSE-MIT](LICENSE-MIT))
 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)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "phonton-cli",
-  "version": "0.16.2",
+  "version": "0.17.1",
   "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",