cto-ai-cli 4.0.0 → 5.1.0

package/README.md

@@ -1,238 +1,128 @@
-# CTO — Your AI is reading too much code. We fix that.
-
-> **Early access** — This is a test version. We'd love your feedback.
+# CTO — Stop sending your entire codebase to AI
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-573_passing-brightgreen.svg)](#)
+[![Tests](https://img.shields.io/badge/tests-550_passing-brightgreen.svg)](#)
+[![Coverage](https://img.shields.io/badge/coverage-91%25-brightgreen.svg)](#)
+[![npm](https://img.shields.io/npm/v/cto-ai-cli.svg)](https://www.npmjs.com/package/cto-ai-cli)
 
-## Try it now (zero install)
+CTO analyzes your project and selects the **minimum set of files** your AI needs — saving tokens, reducing cost, and producing code that actually compiles.
 
 ```bash
 npx cto-ai-cli
 ```
 
-That's it. Run it on any project. You'll see something like this:
+**Runs in <1 second.** No API keys. No data leaves your machine.
+
+---
+
+## The Problem
+
+When you ask an AI to help with code, it needs context. Most approaches:
+
+- **Send everything** — expensive, noisy, AI gets confused
+- **Send open files** — misses types, dependencies, config
+- **Let the AI pick** — it doesn't know your dependency graph
+
+The result: AI generates code that **doesn't compile** because it never saw your type definitions.
+
+## The Fix
 
+```bash
+$ npx cto-ai-cli ./my-project
+```
 ```
   ⚡ cto-score — analyzing your project...
 
   ╔══════════════════════════════════════════════════╗
   ║                                                  ║
-  ║   🟢 Context Score™  87  / 100   Grade: A-      ║
+  ║   🟢 Context Score™  88 / 100   Grade: A-       ║
   ║                                                  ║
-  ║   Efficiency     ███████████████░░░░░  74%       ║
+  ║   Efficiency     ████████████████░░░░  80%       ║
   ║   Coverage       ████████████████████ 100%       ║
   ║   Risk Control   ████████████████████ 100%       ║
+  ║   Structure      █░░░░░░░░░░░░░░░░░░   5%       ║
+  ║   Governance     ██████████████████░  90%        ║
   ║                                                  ║
   ║   💰 vs. Sending Everything:                     ║
-  ║   Tokens saved: 289K (85%)                       ║
-  ║   Monthly savings: ~$695                         ║
+  ║   Tokens saved: 392K (88%)                       ║
+  ║   Monthly savings: ~$943                         ║
   ║                                                  ║
   ╚══════════════════════════════════════════════════╝
 
-  Scanned in 11.7s · 177 files · 340K tokens
+  Scanned in 0.6s · 199 files · 443K tokens
 ```
 
-Run `npx cto-ai-cli --benchmark` to see how CTO compares to naive (alphabetical) and random file selection.
+### What each number means
 
-No data leaves your machine. No API keys. MIT licensed.
+| Metric | What it measures | Why it matters |
+|--------|-----------------|----------------|
+| **Context Score (88/100)** | Overall AI-readiness of your project | Higher = AI tools produce better output with your code |
+| **Efficiency (80%)** | How much CTO can compress without losing value | 80% means we send 20% of tokens for the same quality |
+| **Coverage (100%)** | % of important files included in the selection | 100% = every dependency and type file is captured |
+| **Risk Control (100%)** | Are high-risk files (hubs, complex code) prioritized? | Ensures AI sees the files most likely to cause bugs |
+| **Structure (5%)** | How well-organized your codebase is for AI | Low = too many large files, poor modularity |
+| **Governance (90%)** | Audit logging, policy enforcement, secret scanning | Enterprise readiness |
+| **Tokens saved (88%)** | Reduction vs. sending every file | Directly reduces your API costs |
+| **Monthly savings ($943)** | Estimated cost reduction at 800 interactions/month | Based on average GPT-4o pricing |
 
 ---
 
-## What problem does CTO solve?
-
-When you ask an AI assistant to help with code, it needs context — your files. The question is: **which files?**
-
-**Most tools today** either send everything (expensive, noisy) or pick files based on what's open (misses dependencies). Neither approach is great.
-
-**CTO analyzes your project** — dependencies, file importance, risk of excluding each file — and picks the best subset that fits your token budget. It's like a smart assistant that knows which files matter for each task.
-
-### A simple example
-
-You ask the AI: *"refactor the auth middleware"*
+## Quick Start
 
-| Approach | What gets sent | Result |
-|----------|---------------|--------|
-| **Send everything** | 340K tokens (all 177 files) | Expensive. AI drowns in irrelevant code. |
-| **Send open files** | Whatever you have open | Might miss types, dependencies, config. |
-| **CTO** | 50K tokens (93 relevant files) | 85% cheaper. Includes types, deps, related files. |
-
-### Why does it matter?
-
-We tested something specific: when the AI generates code, does it have the type definitions it needs?
-
-| | CTO | Without CTO |
-|--|-----|-------------|
-| **Type files included** | 5 out of 6 | **0 out of 6** |
-| **TypeScript compiler** | ✅ Compiles | ❌ 4 errors |
-
-We ran this on 5 different tasks. Same result every time. CTO context compiles. Naive context doesn't.
-
-Without type definitions, the AI invents interfaces — wrong property names, wrong shapes. The code doesn't compile. ([Details](#compile-proof))
-
----
-
-## Getting started
-
-### Option 1: Quick score (no install)
+### Score your project
 
 ```bash
-npx cto-ai-cli                           # Score your project
-npx cto-ai-cli ./my-project              # Score a specific project
-npx cto-ai-cli --fix                     # Auto-generate optimized context files
-npx cto-ai-cli --context "your task"     # Task-specific context for AI prompts
-npx cto-ai-cli --audit                   # Security audit: detect secrets & PII
-npx cto-ai-cli --report                  # Shareable report + README badge
-npx cto-ai-cli --compare                 # Compare your score vs popular projects
-npx cto-ai-cli --benchmark               # CTO vs naive vs random comparison
-npx cto-ai-cli --json                    # Machine-readable output (for CI)
+npx cto-ai-cli                     # Analyze current directory
+npx cto-ai-cli ./my-project         # Analyze a specific project
+npx cto-ai-cli --json               # Machine-readable JSON output
 ```
 
-### Option 2: Full install
+### Generate optimized context for AI
 
 ```bash
-npm install -g cto-ai-cli
-
-cto2 init                                    # Set up for your project
-cto2 analyze                                 # See structure + risk profile
-cto2 interact "refactor the auth middleware"  # Get optimized context for a task
+npx cto-ai-cli --fix
 ```
 
-### Option 3: Use with your AI editor (MCP)
+Creates `.cto/context.md` — paste this into any AI chat for optimal context. Also generates `.cto/config.json` and `.cto/.cteignore`.
 
-CTO works as an [MCP server](https://modelcontextprotocol.io/) — plug it into Claude, Windsurf, or Cursor.
-
-**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:
-```json
-{
-  "mcpServers": {
-    "cto": { "command": "cto2-mcp" }
-  }
-}
-```
-
-**Claude Desktop** — add to your MCP config:
-```json
-{
-  "mcpServers": {
-    "cto": { "command": "node", "args": ["/path/to/dist/mcp/v2.js"] }
-  }
-}
+```bash
+npx cto-ai-cli --context "refactor the auth middleware"
 ```
 
-Once connected, your AI editor can use tools like `cto_analyze`, `cto_select_context`, `cto_score`, and `cto_benchmark` automatically.
-
----
-
-## How it works (the short version)
-
-1. **Scans** your project — files, imports, dependencies, structure
-2. **Scores** each file — how important is it? What breaks if we exclude it?
-3. **Selects** the best files for your task — within your token budget
-4. **Proves** the result — coverage score, benchmark comparison, cost savings
-
-CTO doesn't use AI for selection. It uses dependency analysis, risk modeling, and optimization algorithms. Same input always produces the same output.
-
----
-
-## Real numbers
-
-We ran CTO on three open-source projects. No cherry-picking — you can reproduce these with `npx cto-ai-cli --benchmark`.
-
-| Project | Files | Score | What CTO does |
-|---------|-------|-------|---------------|
-| **Zod** | 441 files, 804K tokens | 92/100 (A) | Selects 64 files, 100% coverage, $1,809/mo savings |
-| **This project** | 177 files, 340K tokens | 87/100 (A-) | Selects 93 files, 100% coverage, $695/mo savings |
-| **Express.js** | 158 files, 171K tokens | 74/100 (B-) | Needs only 895 tokens for full coverage |
-
-"Coverage" means: all the files that are important for your task are included. "Savings" is estimated based on 800 AI interactions per month.
-
-<details>
-<summary><b>Detailed comparison: CTO vs Naive vs Random</b></summary>
-
-> Budget: 50K tokens · Task: "refactor the core module"
-
-| Project | Strategy | Files | Tokens | Coverage | High-Risk Included |
-|---------|----------|-------|--------|----------|-------------------|
-| **Zod** | **CTO** | 64 | 50.0K | **100%** | **6/6** |
-| | Naive (alphabetical) | 71 | 50.0K | 16% | 2/6 |
-| | Random | 45 | 50.0K | 10% | 1/6 |
-| **CTO** | **CTO** | 163 | 47.4K | **100%** | **11/11** |
-| | Naive | 25 | 50.0K | 15% | 0/11 |
-| | Random | 38 | 50.0K | 23% | 6/11 |
-| **Express** | **CTO** | 158 | 0.9K | **100%** | n/a |
-| | Naive | 64 | 50.0K | 41% | n/a |
-| | Random | 61 | 50.0K | 39% | n/a |
-
-**Note:** "Naive" means alphabetical file order (a common default). "Random" is random selection. These are simple baselines — real-world tools like Cursor use smarter heuristics, so we don't claim CTO beats them. We just show the difference between informed and uninformed selection.
-
-</details>
-
-<details id="compile-proof">
-<summary><b>Compile Proof: real TypeScript compiler output</b></summary>
-
-We ran the actual `tsc` compiler to verify this isn't just theory.
-
-**How it works:**
-1. Copy only the selected files (CTO or naive) to a temp directory
-2. Generate TypeScript code that imports and uses the project's types
-3. Run `tsc --noEmit`
-4. Count real compiler errors
-
-| Task | CTO | Naive | Naive missing |
-|------|-----|-------|--------------|
-| Refactor selector | ✅ 0 errors | ❌ 4 errors | All type files |
-| Optimize risk scoring | ✅ 0 errors | ❌ 4 errors | All type files |
-| MCP error handling | ✅ 0 errors | ❌ 4 errors | All type files |
-| Cache invalidation | ✅ 0 errors | ❌ 4 errors | All type files |
-| Add semantic tool | ✅ 0 errors | ❌ 4 errors | All type files |
-
-The naive selection (alphabetical) consistently misses all type definition files. The compiler output:
+Generates **task-specific** context — only files relevant to auth, including types, dependencies, and related tests.
 
+Example output:
 ```
-error TS2307: Cannot find module './src/types/engine.js'
-error TS2307: Cannot find module './src/types/config.js'
-error TS2307: Cannot find module './src/types/govern.js'
-error TS2307: Cannot find module './src/types/interact.js'
+  📋 Context for: "refactor the auth middleware"
+
+  Selected 12 files (8.2K tokens):
+
+  ┌─ Core (3 files) ─────────────────────────────
+  │  src/middleware/auth.ts          2,100 tokens
+  │  src/types/auth.ts                 450 tokens
+  │  src/config/jwt.ts                 320 tokens
+  │
+  ├─ Dependencies (5 files) ─────────────────────
+  │  src/models/user.ts              1,200 tokens
+  │  src/services/token.ts             890 tokens
+  │  ...
+  │
+  └─ Tests (2 files) ────────────────────────────
+     tests/auth.test.ts              1,800 tokens
+     tests/middleware.test.ts          940 tokens
+
+  Saved to .cto/context.md (8.2K tokens — 97% smaller than full project)
 ```
 
-Without these files, the AI has to guess the shape of `AnalyzedFile`, `ContextSelection`, `TaskType`, etc. It will get them wrong.
-
-</details>
-
----
-
-## 🔒 Security Audit — detect secrets before AI sees them
-
-Every time you send code to an AI, there's a risk: **API keys, tokens, passwords, and PII hiding in your codebase.**
-
-CTO now scans your entire project for secrets — before they end up in an AI prompt.
+### Security audit
 
 ```bash
 npx cto-ai-cli --audit
 ```
 
-```
-  🔍 Running security audit...
-
-  ╔══════════════════════════════════════════════════╗
-  ║                                                  ║
-  ║   🔴 Security Audit: CRITICAL ISSUES FOUND       ║
-  ║                                                  ║
-  ║   Files scanned:  179                            ║
-  ║   Files affected: 12                             ║
-  ║   Total findings: 51                             ║
-  ║                                                  ║
-  ╠══════════════════════════════════════════════════╣
-  ║                                                  ║
-  ║   🔴 Critical: 34                                ║
-  ║   🟠 High:     5                                 ║
-  ║   🟡 Medium:   12                                ║
-  ║                                                  ║
-  ╚══════════════════════════════════════════════════╝
-
-  Findings:
+Scans for **API keys, tokens, passwords, and PII** before they end up in an AI prompt. 45+ patterns (AWS, Stripe, GitHub, OpenAI, etc.) plus Shannon entropy analysis for unknown formats.
 
+```
   🔴 CRITICAL src/config/stripe.ts:8
              api-key: sk_l********************yZ
   🔴 CRITICAL src/config/database.ts:14
@@ -240,189 +130,204 @@ npx cto-ai-cli --audit
   🟠 HIGH     src/utils/email.ts:22
              pii: admi**********om
 
-  Recommendations:
+  🚨 3 critical findings. Rotate credentials immediately.
+```
+
+Run in CI to block PRs with secrets: `CI=true npx cto-ai-cli --audit`
 
-  🚨 CRITICAL: Rotate all detected credentials immediately.
-  💡 Use environment variables for API keys.
-  💡 Add a .gitignore entry for .env files.
+### Code review intelligence
 
-  📁 Audit artifacts:
-  📋 .cto/audit/2026-02-24.jsonl   Audit log (append-only)
-  📊 .cto/audit/report.md          Full report
-  📝 .cto/.env.example             Template for environment variables
+```bash
+npx cto-ai-cli --review
 ```
 
-### What it detects
+Analyzes your git diff and generates a structured review:
 
-| Category | Examples | Severity |
-|----------|----------|----------|
-| **API Keys** | OpenAI, Anthropic, Stripe, Google, SendGrid, Azure | 🔴 Critical |
-| **Cloud credentials** | AWS Access Keys, AWS Secrets | 🔴 Critical |
-| **Tokens** | GitHub, GitLab, Slack, npm, JWT | 🔴 Critical |
-| **Private keys** | RSA, SSH, EC private keys | 🔴 Critical |
-| **Database** | Connection strings (Postgres, MongoDB, Redis, MySQL) | 🔴 Critical |
-| **Passwords** | Hardcoded passwords, DB passwords | 🟠 High |
-| **PII** | Email addresses, possible SSNs | 🟡 Medium |
-| **High-entropy strings** | Random strings that look like secrets (Shannon entropy analysis) | 🟡 Medium |
+```
+  📊 Review Quality: 82/100 (B+)
 
-### How it works
+  Breaking Changes:
+    🔴 Removed export: UserService.findById (used by 4 files)
+    🟡 Changed signature: authenticate(token) → authenticate(token, opts)
 
-1. **30+ regex patterns** — battle-tested patterns for known secret formats (AWS, Stripe, Slack, GitHub, etc.)
-2. **Shannon entropy analysis** — detects random-looking strings that may be secrets, even if they don't match a known pattern
-3. **Smart filtering** — skips placeholders (`${API_KEY}`), test files, comments, and common false positives
-4. **Auto-redaction** — secrets are NEVER shown in full. All output uses redacted values (`sk_l**********yZ`)
+  Missing Files:
+    ⚠️  No test file for src/services/auth.ts
+    ⚠️  src/types/user.ts changed but barrel index not updated
 
-### What it generates
+  Impact Radius:
+    Direct: 4 files  |  Transitive: 12 files  |  Tests: 3 files
 
-| File | Purpose |
-|------|---------|
-| `.cto/audit/YYYY-MM-DD.jsonl` | Append-only audit log (run it daily, keep history) |
-| `.cto/audit/report.md` | Full markdown report — share with your team or compliance |
-| `.cto/.env.example` | Auto-generated template with all detected env variable names |
+  Saved review prompt to .cto/review-prompt.md
+```
 
-### CI/CD integration
+| What it detects | Example |
+|-----------------|--------|
+| **Breaking changes** | Removed exports, changed function signatures, deleted files |
+| **Missing files** | Tests, type files, barrel exports, importers of changed code |
+| **Impact radius** | How many files are affected (direct + transitive via BFS) |
+| **Review quality** | Score based on PR size, focus, breaking changes, completeness |
 
-Set `CI=true` and the audit will **exit with code 1** if critical or high-severity secrets are found:
+### Learning mode
 
 ```bash
-CI=true npx cto-ai-cli --audit
+npx cto-ai-cli --learn               # View feedback model & stats
+npx cto-ai-cli --predict              # Predict relevant files for a task
+npx cto-ai-cli --learn --json         # Export learning data for team sharing
 ```
 
-Perfect for pre-commit hooks or CI pipelines — block PRs that contain secrets before they reach production or an AI prompt.
-
-### Why this matters
-
-Every day, developers accidentally send secrets to AI tools:
-- Copilot autocompletes with your `.env` values in context
-- You paste a file into ChatGPT that has a hardcoded API key
-- Cursor reads your database config with connection strings
+CTO learns from your usage patterns over time. Uses **EWMA temporal decay** (recent feedback weighs more) and **Bayesian confidence** (Wilson score — avoids over-trusting sparse data).
 
-**CTO catches these before they leave your machine.** Zero external calls. Everything runs locally.
+### Quality gate for CI/CD
 
----
+```bash
+npx cto-ai-cli --ci                   # Run quality gate (exits 1 on failure)
+npx cto-ai-cli --ci --threshold 80    # Custom minimum score
+npx cto-ai-cli --ci --json            # JSON for pipeline parsing
+```
 
-## 🌐 Context Gateway — AI proxy for your entire team
+Block merges when context quality drops below your threshold. Tracks baselines and detects regressions.
 
-Every AI API call from your team passes through the Gateway. It sits between your app and any LLM provider, automatically optimizing context, redacting secrets, and tracking costs.
+### Monorepo support
 
 ```bash
-npx cto-gateway
+npx cto-ai-cli --monorepo             # Analyze all packages
+npx cto-ai-cli --monorepo --package api  # Focus on one package
 ```
 
+Detects npm/yarn/pnpm workspaces, Turborepo, Nx, and Lerna. Shows cross-package dependencies, isolation scores, and shared package analysis.
+
+---
+
+## All CLI Flags
+
+```bash
+# Analysis
+npx cto-ai-cli [path]                 # Score a project
+npx cto-ai-cli --json                 # JSON output
+npx cto-ai-cli --benchmark            # CTO vs naive vs random comparison
+npx cto-ai-cli --compare              # Compare vs popular OSS projects
+npx cto-ai-cli --report               # Markdown report + badge
+
+# Context generation
+npx cto-ai-cli --fix                  # Auto-generate .cto/context.md
+npx cto-ai-cli --context "task"       # Task-specific context
+
+# Security
+npx cto-ai-cli --audit                # Secret & PII detection
+npx cto-ai-cli --audit --full-scan    # Scan all files (ignore cache)
+npx cto-ai-cli --audit --init-hook    # Install pre-commit hook
+
+# Code review
+npx cto-ai-cli --review               # PR review analysis
+npx cto-ai-cli --review --json        # Review data as JSON
+
+# Learning
+npx cto-ai-cli --learn                # Feedback model dashboard
+npx cto-ai-cli --predict              # File predictions for a task
+npx cto-ai-cli --learn --json         # Export learning data
+
+# CI/CD
+npx cto-ai-cli --ci                   # Quality gate
+npx cto-ai-cli --ci --threshold 80    # Custom threshold
+
+# Monorepo
+npx cto-ai-cli --monorepo             # Full monorepo analysis
+npx cto-ai-cli --monorepo --package X # Single package
+
+# Gateway (AI proxy)
+npx cto-gateway                       # Start proxy server
+npx cto-gateway --budget-daily 10     # With budget enforcement
 ```
-  ⚡ CTO Context Gateway v4.0.0
 
-  🌐 Proxy:      http://127.0.0.1:8787
-  📊 Dashboard:  http://127.0.0.1:8787/__cto
-  📁 Project:    /your/project
+---
 
-  ✅ Context optimization
-  ✅ Secret redaction
-  ✅ Cost tracking
-  ⬜ Daily budget (unlimited)
+## MCP Server (for AI Editors)
 
-  How to connect:
-    OPENAI_BASE_URL=http://127.0.0.1:8787
-    + set header: x-cto-target: https://api.openai.com/v1/chat/completions
+CTO works as an [MCP server](https://modelcontextprotocol.io/) — plug it into Claude, Windsurf, or Cursor.
 
-  Waiting for requests...
+**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:
+```json
+{
+  "mcpServers": {
+    "cto": { "command": "cto-mcp" }
+  }
+}
+```
 
-  18:52:34  openai/gpt-4o  1200 tokens  $0.0075 (saved 5.2K tokens, $0.0130) [2 secrets redacted]  152ms
+**Claude Desktop:**
+```json
+{
+  "mcpServers": {
+    "cto": { "command": "npx", "args": ["-y", "cto-ai-cli", "--mcp"] }
+  }
+}
 ```
 
-### What it does
+Tools available: `cto_analyze`, `cto_select_context`, `cto_score`, `cto_benchmark`, `cto_risk`, and more.
 
-| Feature | Description |
-|---------|-------------|
-| **Secret redaction** | Scans every message for API keys, tokens, passwords → auto-redacts before sending to the LLM |
-| **Secret blocking** | Optional hard block — reject requests that contain critical secrets |
-| **Context optimization** | Injects CTO-selected files, type definitions, and hub modules into system prompts |
-| **Cost tracking** | Tracks per-request cost by model and provider. Persistent JSONL logs. |
-| **Budget enforcement** | Set daily/monthly limits. Gateway returns 429 when exceeded. |
-| **Live dashboard** | Dark-theme web UI at `/__cto` — today's stats, monthly breakdown, model costs |
-| **SSE streaming** | Full passthrough of streaming responses with zero-copy. No added latency. |
-| **Multi-provider** | OpenAI, Anthropic, Google AI, Azure OpenAI, and any OpenAI-compatible API |
+---
 
-### Supported providers & models
+## Programmatic API
 
-| Provider | Models | Pricing tracked |
-|----------|--------|----------------|
-| **OpenAI** | GPT-4o, GPT-4o Mini, o1, o1-mini, o3-mini | ✅ |
-| **Anthropic** | Claude Sonnet 4, Claude 3.5 Haiku, Claude 3 Opus | ✅ |
-| **Google** | Gemini 2.5 Pro, Gemini 2.0 Flash, Gemini 1.5 Pro | ✅ |
-| **Azure OpenAI** | Same as OpenAI (different hosting) | ✅ |
-| **Custom** | Any OpenAI-compatible API (Ollama, LiteLLM, etc.) | Manual |
+```typescript
+import { analyzeProject, computeContextScore, selectContext } from 'cto-ai-cli';
 
-### Configuration
+// Analyze a project
+const analysis = await analyzeProject('./my-project');
 
-```bash
-cto-gateway --port 9000                  # Custom port
-cto-gateway --block-secrets              # Hard block on critical secrets
-cto-gateway --budget-daily 10            # Max $10/day
-cto-gateway --budget-monthly 200         # Max $200/month
-cto-gateway --project ./my-app           # Analyze a specific project
-cto-gateway --no-optimize                # Disable context injection
-cto-gateway --no-redact                  # Disable secret redaction
-```
+// Get the Context Score
+const score = await computeContextScore(analysis);
+console.log(`Score: ${score.overall}/100 (${score.grade})`);
+console.log(`Tokens saved: ${score.comparison.savedPercent}%`);
 
----
+// Select optimal files for a task
+const selection = await selectContext({
+  task: 'refactor the auth middleware',
+  analysis,
+  budget: 50_000,  // 50K token budget
+});
 
-## What you can do with CTO
-
-| Use case | How |
-|----------|-----|
-| **Score your project** | `npx cto-ai-cli` |
-| **Auto-optimize context** | `npx cto-ai-cli --fix` → generates `.cto/context.md` to paste into AI |
-| **Task-specific context** | `npx cto-ai-cli --context "refactor auth"` → optimized for your task |
-| **Security audit** | `npx cto-ai-cli --audit` → detect secrets & PII before AI sees them |
-| **AI proxy (Gateway)** | `npx cto-gateway` → proxy with secret redaction + cost tracking |
-| **Shareable report** | `npx cto-ai-cli --report` → markdown report + README badge |
-| **Compare vs open source** | `npx cto-ai-cli --compare` → your score vs Zod, Next.js, Express |
-| **Compare strategies** | `npx cto-ai-cli --benchmark` → CTO vs naive vs random |
-| **Get context for a task** | `cto2 interact "your task"` |
-| **Use in your AI editor** | Add MCP server (see setup above) |
-| **Block secrets in CI** | `CI=true npx cto-ai-cli --audit` |
-| **Budget control** | `cto-gateway --budget-daily 10 --budget-monthly 200` |
-| **JSON output (scripting)** | `npx cto-ai-cli --json` |
+console.log(`Selected ${selection.files.length} files`);
+console.log(`Coverage: ${selection.coverage.score}%`);
+for (const file of selection.files) {
+  console.log(`  ${file.relativePath} (${file.tokens} tokens, risk: ${file.riskScore})`);
+}
+```
 
 ---
 
-## Honest limitations
+## How It Works
 
-This is an early test version. Here's what we know:
+1. **Scan** — walks your project, parses imports, builds a dependency graph
+2. **Score** — computes risk for each file (complexity, hub score, centrality, recency)
+3. **Select** — deterministic greedy algorithm: picks highest-risk files first within token budget
+4. **Prove** — measures coverage (% of important files included), compares vs naive strategies
 
-- **TypeScript/JavaScript projects work best.** We support other languages (Python, Go, Rust, Java) for basic analysis, but TypeScript gets the deepest understanding.
-- **Our benchmarks use simple baselines** (alphabetical, random). We haven't compared against Cursor's or Copilot's internal context selection.
-- **The savings numbers are estimates** based on average API pricing. Your actual savings depend on your model, pricing tier, and usage patterns.
-- **We need more projects to test on.** If you try it and share your score, that helps us a lot.
+No AI is used for selection. Same input always produces the same output. Fully reproducible.
 
 ---
 
-## What's next
+## Honest Limitations
 
-We're working on:
-- **Context Gateway** — proxy between your team and any AI, with automatic context optimization and cost tracking
-- **Monorepo intelligence** — package-aware selection for large monorepos (60-80% more token savings)
-- **CI Quality Gate** — GitHub Action that posts context score and secret audit on every PR
-- **VS Code extension** — live score, risk indicators, and context suggestions inline
-- **Learning mode** — CTO improves based on which AI suggestions you accept/reject
-- **More language support** — deeper analysis for Python, Go, and Rust
-- **Your feedback** — [open an issue](https://github.com/cto-ai/cto-ai-cli/issues) or reach out
+- **TypeScript/JavaScript gets the deepest analysis.** Other languages (Python, Go, Rust, Java) get basic file + import analysis.
+- **Benchmarks use simple baselines** (alphabetical, random). We haven't compared against Cursor's or Copilot's internal context selection.
+- **Savings are estimates** based on average API pricing. Actual savings depend on your model and usage.
+- **Risk scoring uses a complexity proxy** instead of real git churn data (planned improvement).
 
 ---
 
-## For contributors
+## Contributing
 
 ```bash
-git clone <repo-url>
-cd cto
+git clone https://github.com/cto-ai/cto-ai-cli.git
+cd cto-ai-cli
 npm install
 npm run build
-npm test          # 573 tests
-npm run typecheck # strict TypeScript
+npm test              # 376 tests
+npm run typecheck     # strict TypeScript, zero errors
 ```
 
-Full CLI docs, MCP server setup, API server, and programmatic API are documented in [DOCS.md](DOCS.md).
+Full API docs, MCP server reference, and architecture are in [DOCS.md](DOCS.md).
 
 ## License