cto-ai-cli 5.2.0 → 7.1.0

package/README.md

@@ -1,435 +1,288 @@
-# CTO — Stop sending your entire codebase to AI
+# CTO — AI Context Selection Engine
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-606%20passing-brightgreen)](.)
 
-CTO analyzes your project and selects the **minimum set of files** your AI needs — saving tokens, reducing cost, and producing code that actually compiles.
+**Pick the right files for any AI task. Secrets auto-redacted. Learns from your feedback.**
 
 ```bash
-npx cto-ai-cli
+cto --context "fix the auth middleware" --stdout | pbcopy   # → clipboard
+cto --context "fix auth" --prompt "Refactor to use JWT"     # → AI prompt
+cto --accept                                                 # → learns
 ```
 
-**Runs in <1 second.** No API keys. No data leaves your machine.
+76KB package · 606 tests · Zero AI dependencies.
 
 ---
 
 ## The Problem
 
-When you ask an AI to help with code, it needs context. Most approaches:
+When developers use AI coding assistants, they need to provide context — the right source files. Today, most teams either:
 
-- **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
+- **Send everything** → expensive, slow, hits token limits
+- **Pick files manually** → miss dependencies, forget test files, leak secrets
 
-The result: AI generates code that **doesn't compile** because it never saw your type definitions.
+CTO solves both: it **automatically selects the most relevant files** for any task, **sanitizes secrets** before they reach any AI provider, and **learns from feedback** to get better over time.
 
-## The Fix
+## Quick Demo
 
 ```bash
-$ npx cto-ai-cli ./my-project
-```
-```
-  ⚡ cto-score — analyzing your project...
-
-  ╔══════════════════════════════════════════════════╗
-  ║                                                  ║
-  ║   🟢 Context Score™  88 / 100   Grade: A-       ║
-  ║                                                  ║
-  ║   Efficiency     ████████████████░░░░  80%       ║
-  ║   Coverage       ████████████████████ 100%       ║
-  ║   Risk Control   ████████████████████ 100%       ║
-  ║   Structure      █░░░░░░░░░░░░░░░░░░   5%       ║
-  ║   Governance     ██████████████████░  90%        ║
-  ║                                                  ║
-  ║   💰 vs. Sending Everything:                     ║
-  ║   Tokens saved: 392K (88%)                       ║
-  ║   Monthly savings: ~$943                         ║
-  ║                                                  ║
-  ╚══════════════════════════════════════════════════╝
-
-  Scanned in 0.6s · 199 files · 443K tokens
+cto --demo   # Run a live showcase on your project
 ```
 
-### What each number means
+This runs a self-contained presentation that shows: project analysis, semantic matching proof, secret sanitization, ROI calculation, and benchmark results.
 
-| 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 |
+## Benchmark Results
 
----
+Tested against 8 curated tasks with ground truth (known correct files):
 
-## Quick Start
+| Strategy | Precision | Must-have Recall | F1 |
+|---|---|---|---|
+| **CTO** | 33.6% | **100.0%** | **48.7%** |
+| TF-IDF only | 54.6% | 87.5% | 62.0% |
+| Risk-only | 20.8% | 18.8% | 15.0% |
+| Alphabetical | 8.3% | 31.3% | 12.9% |
+| Random | 7.7% | 6.3% | 2.8% |
 
-### Score your project
+**CTO never misses a must-have file** (100% recall). 3.8× better F1 than alphabetical. 17× better than random.
 
-```bash
-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
-```
+## ROI
 
-### Generate optimized context for AI
+On a typical 130-file TypeScript project:
 
-```bash
-npx cto-ai-cli --fix
-```
+| Metric | Without CTO | With CTO |
+|---|---|---|
+| Tokens per interaction | 370K (all files) | ~28K (selected) |
+| Cost per interaction (Sonnet) | $1.11 | $0.08 |
+| **Monthly cost (10 devs, 40/day)** | **$8,880** | **$640** |
+| **Annual savings** | — | **~$99,000** |
 
-Creates `.cto/context.md` — paste this into any AI chat for optimal context. Also generates `.cto/config.json` and `.cto/.cteignore`.
+Plus: fewer hallucinations (right context), zero secret leaks, and the learner gets smarter with every `--accept` / `--reject`.
 
-```bash
-npx cto-ai-cli --context "refactor the auth middleware"
-```
+## How it Works
 
-Generates **task-specific** context — only files relevant to auth, including types, dependencies, and related tests.
-
-Example output:
 ```
-  📋 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)
+Task description ──→ TF-IDF/BM25 ──→ Semantic scores ──┐
+                                                         │
+Project files ──→ Dependency graph ──→ Risk scores ──────┤──→ Composite ──→ Greedy ──→ Selection
+                                                         │     ranking      alloc
+Feedback history ──→ Bayesian learner ──→ Boosts ────────┘
 ```
 
-### Security audit
+1. **Dependency graph** — parses imports, builds adjacency list, identifies hubs
+2. **Risk scoring** — complexity × centrality × recency (continuous, log-scaled)
+3. **TF-IDF/BM25 semantic matching** — task description scored against file contents + path boosting
+4. **Composite ranking** — `finalScore = semantic × 0.55 + risk × 0.25 + learner × 0.2`
+5. **Noise filtering** — files with zero semantic relevance are excluded (benchmark-driven optimization)
+6. **Greedy allocation** — fills token budget top-down, cascading prune levels (full → signatures → skeleton)
+7. **Bayesian learning** — exponential decay, Wilson score confidence, per-task-type patterns
+
+**No AI is used for selection.** Same input → same output. Deterministic.
+
+## Install
 
 ```bash
-npx cto-ai-cli --audit
+npm i -g cto-ai-cli    # global
+npx cto-ai-cli         # or one-shot
 ```
 
-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.
+## Context Selection
 
+```bash
+cto --context "refactor the auth middleware"                 # human-readable summary
+cto --context "fix login bug" --stdout | pbcopy              # pipe to clipboard
+cto --context "add tests" --output context.md                # save to file
+cto --context "fix login" --prompt "Refactor to async/await" # full AI prompt
+cto --context "debug scoring" --json                         # JSON for tooling
+cto --context "fix auth" --budget 30000                      # custom token budget
 ```
-  🔴 CRITICAL src/config/stripe.ts:8
-             api-key: sk_l********************yZ
-  🔴 CRITICAL src/config/database.ts:14
-             connection-string: post********************db
-  🟠 HIGH     src/utils/email.ts:22
-             pii: admi**********om
-
-  🚨 3 critical findings. Rotate credentials immediately.
-```
 
-Run in CI to block PRs with secrets: `CI=true npx cto-ai-cli --audit`
+Output includes full file contents in markdown, ready for Claude, ChatGPT, or any AI. **Secrets are automatically redacted** — API keys, tokens, passwords, PII are replaced with `****` before output.
+
+## Feedback Loop
 
-### Code review intelligence
+CTO learns from real feedback, not from itself:
 
 ```bash
-npx cto-ai-cli --review
+cto --accept                         # last selection was good
+cto --reject                         # last selection was bad
+cto --reject --missing src/auth.ts   # this file was missing
+cto --stats                          # see what CTO has learned
 ```
 
-Analyzes your git diff and generates a structured review:
+On `--reject`, CTO also detects files you edited after the selection that weren't in the context — those get automatically boosted for next time.
 
-```
-  📊 Review Quality: 82/100 (B+)
-
-  Breaking Changes:
-    🔴 Removed export: UserService.findById (used by 4 files)
-    🟡 Changed signature: authenticate(token) → authenticate(token, opts)
+## Secret Audit
 
-  Missing Files:
-    ⚠️  No test file for src/services/auth.ts
-    ⚠️  src/types/user.ts changed but barrel index not updated
+```bash
+cto --audit                  # scan all files
+cto --audit --init-hook      # install pre-commit hook
+cto --audit --full-scan      # ignore cache, scan everything
+cto --audit --json           # machine-readable output
+```
 
-  Impact Radius:
-    Direct: 4 files  |  Transitive: 12 files  |  Tests: 3 files
+45+ patterns (AWS, Stripe, GitHub, OpenAI, Slack, Cloudflare...) plus Shannon entropy analysis. The real value: **audit protects context** — every `--stdout`, `--output`, and `--prompt` auto-sanitizes secrets before output.
 
-  Saved review prompt to .cto/review-prompt.md
+```
+Before:  OPENAI_KEY = "sk-Rk8bN3xYz2Wq5PmL7jCvT1aBcDe"
+After:   OPENAI_KEY = "sk-R********************De"
 ```
 
-| 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 |
+## AI Gateway (Enterprise)
 
-### Learning mode
+A transparent HTTP proxy between your developers and AI providers. Automatically injects optimized context, redacts secrets, and tracks costs — without changing developer workflow.
 
 ```bash
-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
+cto --gateway                        # Start on port 8787
+cto --gateway --port 9000            # Custom port
+cto --gateway --block-secrets        # Block requests with critical secrets
+cto --gateway --budget-daily 50      # $50/day budget limit
+cto --gateway --budget-monthly 500   # $500/month budget limit
 ```
 
-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).
+```
+Developer → CTO Gateway → [context injection + sanitization + cost tracking] → AI Provider
+                ↓
+          Dashboard (http://localhost:8787/__cto)
+```
 
-### Quality gate for CI/CD
+**What the gateway does automatically:**
+- **Injects CTO-selected context** into every AI request (TF-IDF + composite scoring)
+- **Redacts secrets** before they leave the network (45+ patterns)
+- **Tracks costs** per model, per day, per month with budget alerts
+- **Streams responses** with zero-copy SSE passthrough
+- **Serves a live dashboard** at `/__cto` with real-time metrics
 
-```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
-```
+Supports OpenAI, Anthropic, Google, and Azure OpenAI. SSRF protection built-in.
 
-Block merges when context quality drops below your threshold. Tracks baselines and detects regressions.
+## Cross-Repo Context
 
-### Monorepo support
+When working on a task, CTO can pull relevant files from **sibling repositories** — not just the current project.
 
 ```bash
-npx cto-ai-cli --monorepo             # Analyze all packages
-npx cto-ai-cli --monorepo --package api  # Focus on one package
+cto --context "fix payment webhook" --auto-repos   # Auto-discover sibling repos
+cto --context "fix payment webhook" --repos shared-types,payment-service
 ```
 
-Detects npm/yarn/pnpm workspaces, Turborepo, Nx, and Lerna. Shows cross-package dependencies, isolation scores, and shared package analysis.
+**How it works:**
+1. Discovers sibling repos in parent directory (any dir with `package.json`, `tsconfig.json`, `Cargo.toml`, etc.)
+2. Builds a lightweight TF-IDF index per sibling (reads source files, no full analysis)
+3. Queries each sibling with the task description
+4. Returns ranked matches with repo attribution and content
 
----
+Real use case: You're fixing a webhook handler in `api-gateway` — CTO finds the `Payment` interface in `shared-types` and the consumer in `notification-service` automatically.
+
+## Cost-Aware Model Routing
 
-## All CLI Flags
+CTO analyzes the **actual selected context** (not just the project) to recommend the cheapest model that can handle the task.
 
 ```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 "update readme" --route     # → Haiku ($0.08/call, 73% cheaper)
+cto --context "fix auth bug" --route      # → Opus ($1.33/call, critical complexity)
+cto --context "refactor API" --route      # → Sonnet ($0.30/call, balanced)
 ```
 
----
+**Complexity is computed from real signals:**
+- Token density (% of budget used)
+- Risk concentration (top-5 file avg risk vs project max)
+- Directory diversity (cross-cutting = harder)
+- Dependency density among selected files
 
-## MCP Server (for AI Editors)
+The gateway also uses this: every proxied request gets a model recommendation in the injected context.
 
-CTO works as an [MCP server](https://modelcontextprotocol.io/) — plug it into Claude, Windsurf, or Cursor.
+## MCP Server
 
-**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:
-```json
-{
-  "mcpServers": {
-    "cto": { "command": "cto-mcp" }
-  }
-}
-```
+Works as an MCP server for AI editors (Windsurf, Claude Desktop, Cursor).
+
+**3 tools:** `cto_select_context`, `cto_audit_secrets`, `cto_explain`
 
-**Claude Desktop:**
 ```json
-{
-  "mcpServers": {
-    "cto": { "command": "npx", "args": ["-y", "cto-ai-cli", "--mcp"] }
-  }
-}
-```
+// Windsurf: ~/.codeium/windsurf/mcp_config.json
+{ "mcpServers": { "cto": { "command": "cto-mcp" } } }
 
-19 tools available: `cto_analyze`, `cto_select_context`, `cto_score`, `cto_benchmark`, `cto_risk`, `cto_quality_benchmark`, `cto_compilability`, `cto_audit`, `cto_review`, `cto_monorepo`, and more.
+// Claude Desktop
+{ "mcpServers": { "cto": { "command": "npx", "args": ["-y", "cto-ai-cli"] } } }
+```
 
----
+MCP output is also auto-sanitized when `includeContents: true`.
 
 ## Programmatic API
 
 ```typescript
-import { analyzeProject, computeContextScore, selectContext } from 'cto-ai-cli';
+import { analyzeProject, selectContext, buildIndex, query } from 'cto-ai-cli';
 
-// Analyze a project
 const analysis = await analyzeProject('./my-project');
+const index = buildIndex(files);
+const semanticScores = query(index, 'fix auth', 50)
+  .map(m => ({ filePath: m.filePath, score: m.score }));
 
-// 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',
+  task: 'fix auth',
   analysis,
-  budget: 50_000,  // 50K token budget
+  budget: 50_000,
+  semanticScores,
 });
-
-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})`);
-}
 ```
 
----
-
-## How It Works
-
-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
-
-No AI is used for selection. Same input always produces the same output. Fully reproducible.
-
----
-
-## Benchmark Proof
-
-CTO includes an automated benchmark that runs **real context selection** on this repository (or any repo) and compares CTO vs naive (alphabetical) vs random strategies.
-
-```bash
-$ npx tsx scripts/benchmark.ts --json
-```
-
-**Results on this repo (124 files, 346K tokens):**
-
-| Metric | Result |
-|--------|--------|
-| **CTO win rate** | 100% (20/20 runs across 5 tasks × 4 budgets) |
-| **Coverage gain vs random** | +81% average |
-| **Tokens saved vs naive** | 10% average |
-| **Compilability: CTO** | 92/100 |
-| **Compilability: Naive** | 40/100 |
-| **CTO fewer predicted errors** | 2 fewer type/import errors per task |
-| **Avg selection time** | 16ms |
-
-The benchmark uses the same scoring engine as the CLI. No hardcoded numbers — run it yourself on any project.
+## v7.0 Enterprise Features
 
----
+### Precision Reranker (96.9% precision, was 33.6%)
 
-## Gateway — AI Proxy with Security
+Multi-signal reranker between BM25 retrieval and greedy allocation:
+- **Term coverage**: fraction of unique query terms matched per file
+- **Term specificity**: IDF-weighted — rare terms matter more
+- **Bigram proximity**: query terms appearing close together in the file
+- **Dependency signal**: files in the dependency cone of top matches
+- **Quality gate**: adaptive cutoff stops filling budget with noise
 
-```bash
-npx cto-gateway                       # Start proxy server
-npx cto-gateway --port 9000           # Custom port
-npx cto-gateway --budget-daily 10     # $10/day budget enforcement
-npx cto-gateway --block-secrets        # Strip secrets from prompts
-npx cto-gateway --api-key <key>       # Require authentication
-```
+### Persistent Index Cache
 
-The gateway sits between your AI editor and the model API, adding:
+TF-IDF index persisted to `.cto/index-cache.json` with per-file mtime tracking. Subsequent queries only re-tokenize changed files. 50K-file repos go from 5s → <100ms on warm cache.
 
-- **Context optimization** — injects relevant file contents into prompts automatically
-- **Secret scanning** — strips API keys and PII from outbound messages
-- **Budget enforcement** — daily/weekly spend limits with alerts
-- **Usage tracking** — JSONL logs of all requests with token counts and costs
-- **SSRF protection** — domain allowlist, private IP blocking, HTTPS-only
-- **Body size limits** — 10MB default, prevents abuse
-- **Upstream timeouts** — 120s default with socket cleanup
-- **Connection pooling** — keep-alive agents with 50 max sockets
+### Multi-Language Dependency Graphs
 
-Supports **OpenAI, Anthropic, Google, and Azure** providers with SSE streaming.
-
----
-
-## Multi-Model Optimization
+Regex-based import parsing for **Python**, **Go**, **Java**, and **Rust** alongside ts-morph for TS/JS. Enables hub detection, risk scoring, and dependency expansion for polyglot codebases.
 
 ```bash
-npx cto-ai-cli --benchmark
+# Works on Python, Go, Java, Rust projects — not just TypeScript
+cto --context "fix auth handler" /path/to/go-project
 ```
 
-CTO knows 8 model profiles and recommends the best model for your task:
-
-| Model | Context Window | Strengths |
-|-------|---------------|----------|
-| GPT-4o | 128K | General coding, debugging |
-| GPT-4o Mini | 128K | Fast, cheap, simple tasks |
-| Claude Sonnet 4 | 200K | Complex refactoring, architecture |
-| Claude 3.5 Haiku | 200K | Fast analysis, code review |
-| Gemini 2.0 Flash | 1M | Huge codebases, exploration |
-| Gemini 2.5 Pro | 1M | Deep reasoning, long context |
-| DeepSeek V3 | 128K | Cost-effective coding |
-| Codestral | 256K | Code completion, generation |
+### Team Authentication & SSO
 
-For each model, CTO computes: **budget** (based on context window), **quality score** (strength match + coverage), **estimated cost**, and a **recommendation** (best quality, best value, cheapest).
+Per-team API keys, JWT validation (HS256/RS256), rate limiting, model allowlists. Teams stored in `.cto/gateway/teams.json`.
 
----
+### Metrics Export
 
-## Security
+Prometheus exposition format at `/__cto/metrics`, Datadog JSON, and StatsD UDP. Counters, histograms, gauges for requests, tokens, cost, latency, secrets.
 
-### API Server Path Traversal Protection
+### Per-Team Policy Engine
 
-The API server (`cto-api`) validates all project paths:
+Routing rules per team: model overrides by task type, cost caps per request, context budget limits, block rules. Preset policies: `createCostConscious()`, `createSecurityFirst()`.
 
-- **Forbidden system paths** — blocks `/etc`, `/usr`, `/var`, `/sys`, `/proc`, `/dev`, `/boot`, `/tmp`, `/root`
-- **Forbidden patterns** — blocks paths containing `.ssh`, `.gnupg`, `.aws`, `.env`, `passwd`, `shadow`
-- **Allowlist** — set `CTO_ALLOWED_ROOTS=/home/deploy,/opt/projects` to restrict access to specific directories
+### Closed-Loop A/B Testing
 
-### Secret Detection
+Real experimentation on context strategies with two-proportion z-test for statistical significance. Deterministic assignment (SHA-256 hashing), auto-conclusion when p < 0.05.
 
-45+ patterns including AWS, Stripe, GitHub, OpenAI, Datadog, Sentry, Firebase, Supabase, and more. Plus:
+### LSP Bridge (IDE Plugin)
 
-- **Shannon entropy analysis** for unknown secret formats
-- **PII detection** (emails, SSNs, phone numbers) with safe domain filtering
-- **Allowlist system** — SHA-256 fingerprinted exceptions in `.cto/audit/allowlist.json`
-- **Incremental scanning** — file hash cache, only re-scans changed files
-- **Pre-commit hook** — `npx cto-ai-cli --audit --init-hook` installs a git hook that blocks commits with secrets
-
----
+JSON-RPC 2.0 server over stdin/stdout for any IDE: VS Code, JetBrains, Neovim, Emacs. Custom methods: `cto/selectContext`, `cto/score`, `cto/audit`, `cto/experiments`.
 
 ## Honest Limitations
 
-- **TypeScript/JavaScript gets the deepest analysis.** Other languages (Python, Go, Rust, Java) get basic file + import analysis.
-- **Benchmarks use simple baselines** (alphabetical, random). Run `npx tsx scripts/benchmark.ts` on your own repo to see real numbers. 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).
-
----
+- **TypeScript/JavaScript gets AST analysis.** Python/Go/Java/Rust get regex-based import parsing (good for graphs, not AST-accurate).
+- **BM25 + reranker, not embeddings.** 96.9% precision on our benchmark. No neural model needed.
+- **Learning needs ~5 feedback cycles** to start influencing selection. First runs are pure graph + risk + semantic.
+- **Benchmarked against naive baselines** (alphabetical, random, risk-only, TF-IDF-only). Not compared against Cursor/Copilot internal context engines.
 
 ## Contributing
 
 ```bash
-git clone https://github.com/cto-ai/cto-ai-cli.git
-cd cto-ai-cli
-npm install
-npm run build
-npm test              # 550 tests, 91% coverage
-npm run typecheck     # strict TypeScript, zero errors
-```
-
-Run the automated benchmark to see CTO vs naive on this repo:
-
-```bash
-npx tsx scripts/benchmark.ts          # Human-readable report
-npx tsx scripts/benchmark.ts --json   # Machine-readable JSON
+git clone https://github.com/cto-ai/cto-ai-cli.git && cd cto-ai-cli
+npm install && npm run build && npm test  # 776 tests
 ```
 
-Full API docs, MCP server reference, and architecture are in [DOCS.md](DOCS.md).
-
 ## License
 
 [MIT](LICENSE)