cto-ai-cli 3.2.0 → 5.0.0

package/README.md

@@ -1,360 +1,332 @@
-# 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-449_passing-brightgreen.svg)](#)
+[![Tests](https://img.shields.io/badge/tests-376_passing-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
+## Quick Start
 
-You ask the AI: *"refactor the auth middleware"*
+### Score your project
 
-| 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
+```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
+```
 
-### Option 1: Quick score (no install)
+### Generate optimized context for AI
 
 ```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 --fix
 ```
 
-### Option 2: Full install
+Creates `.cto/context.md` — paste this into any AI chat for optimal context. Also generates `.cto/config.json` and `.cto/.cteignore`.
 
 ```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 --context "refactor the auth middleware"
 ```
 
-### Option 3: Use with your AI editor (MCP)
-
-CTO works as an [MCP server](https://modelcontextprotocol.io/) — plug it into Claude, Windsurf, or Cursor.
+Generates **task-specific** context — only files relevant to auth, including types, dependencies, and related tests.
 
-**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:
-```json
-{
-  "mcpServers": {
-    "cto": { "command": "cto2-mcp" }
-  }
-}
+Example output:
 ```
-
-**Claude Desktop** — add to your MCP config:
-```json
-{
-  "mcpServers": {
-    "cto": { "command": "node", "args": ["/path/to/dist/mcp/v2.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)
 ```
 
-Once connected, your AI editor can use tools like `cto_analyze`, `cto_select_context`, `cto_score`, and `cto_benchmark` automatically.
-
----
+### Security audit
 
-## How it works (the short version)
+```bash
+npx cto-ai-cli --audit
+```
 
-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
+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.
 
-CTO doesn't use AI for selection. It uses dependency analysis, risk modeling, and optimization algorithms. Same input always produces the same output.
+```
+  🔴 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.
+```
 
-## Real numbers
+Run in CI to block PRs with secrets: `CI=true npx cto-ai-cli --audit`
 
-We ran CTO on three open-source projects. No cherry-picking — you can reproduce these with `npx cto-ai-cli --benchmark`.
+### Code review intelligence
 
-| 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 |
+```bash
+npx cto-ai-cli --review
+```
 
-"Coverage" means: all the files that are important for your task are included. "Savings" is estimated based on 800 AI interactions per month.
+Analyzes your git diff and generates a structured review:
 
-<details>
-<summary><b>Detailed comparison: CTO vs Naive vs Random</b></summary>
+```
+  📊 Review Quality: 82/100 (B+)
 
-> Budget: 50K tokens · Task: "refactor the core module"
+  Breaking Changes:
+    🔴 Removed export: UserService.findById (used by 4 files)
+    🟡 Changed signature: authenticate(token) → authenticate(token, opts)
 
-| 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 |
+  Missing Files:
+    ⚠️  No test file for src/services/auth.ts
+    ⚠️  src/types/user.ts changed but barrel index not updated
 
-**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.
+  Impact Radius:
+    Direct: 4 files  |  Transitive: 12 files  |  Tests: 3 files
 
-</details>
+  Saved review prompt to .cto/review-prompt.md
+```
 
-<details id="compile-proof">
-<summary><b>Compile Proof: real TypeScript compiler output</b></summary>
+| 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 |
 
-We ran the actual `tsc` compiler to verify this isn't just theory.
+### Learning mode
 
-**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
+```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
+```
 
-| 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 |
+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).
 
-The naive selection (alphabetical) consistently misses all type definition files. The compiler output:
+### Quality gate for CI/CD
 
-```
-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'
+```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
 ```
 
-Without these files, the AI has to guess the shape of `AnalyzedFile`, `ContextSelection`, `TaskType`, etc. It will get them wrong.
+Block merges when context quality drops below your threshold. Tracks baselines and detects regressions.
 
-</details>
+### Monorepo support
 
----
+```bash
+npx cto-ai-cli --monorepo             # Analyze all packages
+npx cto-ai-cli --monorepo --package api  # Focus on one package
+```
 
-## 🔒 Security Audit — detect secrets before AI sees them
+Detects npm/yarn/pnpm workspaces, Turborepo, Nx, and Lerna. Shows cross-package dependencies, isolation scores, and shared package analysis.
 
-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.
+## All CLI Flags
 
 ```bash
-npx cto-ai-cli --audit
-```
-
+# 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
 ```
-  🔍 Running security audit...
 
-  ╔══════════════════════════════════════════════════╗
-  ║                                                  ║
-  ║   🔴 Security Audit: CRITICAL ISSUES FOUND       ║
-  ║                                                  ║
-  ║   Files scanned:  179                            ║
-  ║   Files affected: 12                             ║
-  ║   Total findings: 51                             ║
-  ║                                                  ║
-  ╠══════════════════════════════════════════════════╣
-  ║                                                  ║
-  ║   🔴 Critical: 34                                ║
-  ║   🟠 High:     5                                 ║
-  ║   🟡 Medium:   12                                ║
-  ║                                                  ║
-  ╚══════════════════════════════════════════════════╝
-
-  Findings:
-
-  🔴 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
+---
 
-  Recommendations:
+## MCP Server (for AI Editors)
 
-  🚨 CRITICAL: Rotate all detected credentials immediately.
-  💡 Use environment variables for API keys.
-  💡 Add a .gitignore entry for .env files.
+CTO works as an [MCP server](https://modelcontextprotocol.io/) — plug it into Claude, Windsurf, or Cursor.
 
-  📁 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
+**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:
+```json
+{
+  "mcpServers": {
+    "cto": { "command": "cto-mcp" }
+  }
+}
 ```
 
-### What it detects
+**Claude Desktop:**
+```json
+{
+  "mcpServers": {
+    "cto": { "command": "npx", "args": ["-y", "cto-ai-cli", "--mcp"] }
+  }
+}
+```
 
-| 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 |
+Tools available: `cto_analyze`, `cto_select_context`, `cto_score`, `cto_benchmark`, `cto_risk`, and more.
 
-### How it works
+---
 
-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`)
+## Programmatic API
 
-### What it generates
+```typescript
+import { analyzeProject, computeContextScore, selectContext } from 'cto-ai-cli';
 
-| 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 |
+// Analyze a project
+const analysis = await analyzeProject('./my-project');
 
-### CI/CD integration
+// Get the Context Score
+const score = await computeContextScore(analysis);
+console.log(`Score: ${score.overall}/100 (${score.grade})`);
+console.log(`Tokens saved: ${score.comparison.savedPercent}%`);
 
-Set `CI=true` and the audit will **exit with code 1** if critical or high-severity secrets are found:
+// Select optimal files for a task
+const selection = await selectContext({
+  task: 'refactor the auth middleware',
+  analysis,
+  budget: 50_000,  // 50K token budget
+});
 
-```bash
-CI=true npx cto-ai-cli --audit
+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})`);
+}
 ```
 
-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 catches these before they leave your machine.** Zero external calls. Everything runs locally.
-
----
-
-## 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 |
-| **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` |
-| **JSON output (scripting)** | `npx cto-ai-cli --json` |
-
 ---
 
-## 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          # 449 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