cto-ai-cli 5.2.0 → 7.1.0

package/DOCS.md

@@ -1,902 +0,0 @@
-# CTO — Full Documentation
-
-> Complete reference for CLI, MCP server, API server, programmatic API, GitHub Action, and configuration.
-
-## Table of Contents
-
-- [CLI Commands](#cli-commands)
-- [Security Audit](#security-audit---audit)
-- [Context Gateway](#context-gateway)
-- [Learning Mode](#learning-mode)
-- [Code Review](#code-review)
-- [MCP Server](#mcp-server)
-- [API Server](#api-server)
-- [Programmatic API](#programmatic-api)
-- [GitHub Action](#github-action)
-- [Configuration](#configuration)
-- [Architecture](#architecture)
-
----
-
-## CLI Commands
-
-### `cto2 init [path]`
-
-Initialize CTO for a project. Creates `.cto/config.yml` and `.cto/policy.yml`.
-
-```bash
-cto2 init                  # current directory
-cto2 init ./my-project     # specific directory
-```
-
-### `cto2 analyze [path]`
-
-Analyze project structure, dependencies, and risk profile.
-
-```bash
-cto2 analyze               # full analysis
-cto2 analyze --risk-only   # show only risk distribution
-cto2 analyze --graph       # show dependency graph (hubs, clusters, orphans)
-```
-
-### `cto2 interact <task>`
-
-Build optimized AI context for a specific task.
-
-```bash
-cto2 interact "refactor the auth middleware"
-cto2 interact "fix the login bug" --explain       # show selection decisions
-cto2 interact "review this PR" --pr               # PR mode (diff vs main)
-cto2 interact "review this PR" --pr develop       # PR mode (diff vs develop)
-cto2 interact "add tests" --output file           # save to .cto/prompt-{id}.md
-cto2 interact "add tests" --output clipboard      # copy to clipboard
-cto2 interact "add tests" --json                  # JSON output
-```
-
-### `cto2 snapshot`
-
-Reproducible context snapshots.
-
-```bash
-cto2 snapshot create baseline    # save current state
-cto2 snapshot verify baseline    # check for drift
-cto2 snapshot compare a b        # diff two snapshots
-cto2 snapshot list               # list all snapshots
-```
-
-### `cto2 audit`
-
-Tamper-evident audit trail.
-
-```bash
-cto2 audit list     # show audit entries
-cto2 audit verify   # verify integrity
-cto2 audit purge    # remove old entries
-```
-
-### `cto2 policy`
-
-Context selection policies.
-
-```bash
-cto2 policy show
-cto2 policy add no-tests exclude-always --pattern "**/*.test.*" --reason "Skip tests"
-cto2 policy remove no-tests
-cto2 policy toggle no-tests
-cto2 policy validate
-cto2 policy init
-```
-
-### `npx cto-ai-cli` (zero-install CLI)
-
-The default binary. All flags work with zero install via `npx`.
-
-```bash
-npx cto-ai-cli                           # Score your project
-npx cto-ai-cli ./path                    # Score a specific project
-npx cto-ai-cli --fix                     # Auto-generate .cto/context.md, config.json, .cteignore
-npx cto-ai-cli --context "your task"     # Task-specific context with file contents
-npx cto-ai-cli --audit                   # Security audit: detect secrets & PII
-npx cto-ai-cli --report                  # Shareable markdown report + shields.io badge
-npx cto-ai-cli --compare                 # Compare your score vs popular open source projects
-npx cto-ai-cli --benchmark              # CTO vs naive vs random comparison
-npx cto-ai-cli --json                    # Machine-readable JSON output
-npx cto-ai-cli --help                    # Show all options
-
-# Phase 5 — CI/CD Quality Gate
-npx cto-ai-cli --ci                      # Run quality gate (exits 1 on failure)
-npx cto-ai-cli --ci --threshold 80       # Set minimum score (default: 70)
-npx cto-ai-cli --ci --json               # JSON output for CI pipelines
-
-# Phase 7 — Learning Mode
-npx cto-ai-cli --learn                   # Show feedback model & cross-repo intelligence
-npx cto-ai-cli --feedback                # Alias for --learn
-npx cto-ai-cli --predict                 # Predict relevant files for a task
-npx cto-ai-cli --learn --json            # Export learning data as JSON
-
-# Phase 8 — Code Review
-npx cto-ai-cli --review                  # Smart PR review analysis
-npx cto-ai-cli --review --json           # JSON output for CI
-```
-
-Flags can be combined: `npx cto-ai-cli --fix --audit --report --compare`
-
----
-
-## Security Audit (`--audit`)
-
-Full-project secret and PII detection. Scans all source files for hardcoded credentials, tokens, keys, passwords, connection strings, and personally identifiable information.
-
-### Usage
-
-```bash
-npx cto-ai-cli --audit                   # Full audit with terminal output
-npx cto-ai-cli --audit --fix             # Audit + auto-generate context files
-CI=true npx cto-ai-cli --audit           # CI mode: exit code 1 on critical/high findings
-```
-
-### Detection engine
-
-CTO uses a **dual-strategy** detection approach:
-
-**1. Pattern matching (30+ patterns)**
-
-| Type | Pattern examples | Severity |
-|------|-----------------|----------|
-| `api-key` | OpenAI `sk-*`, Anthropic `sk-ant-*`, Stripe `sk_live_*`, Google `AIza*`, SendGrid `SG.*.*` | Critical |
-| `aws-key` | `AKIA*` (Access Key ID), `aws_secret_access_key=*` | Critical |
-| `token` | GitHub `ghp_*`/`gho_*`, GitLab `glpat-*`, Slack `xoxb-*`/`xoxp-*`, npm `npm_*`, JWT `eyJ*.*.*` | Critical/High |
-| `private-key` | `-----BEGIN RSA PRIVATE KEY-----`, `-----BEGIN OPENSSH PRIVATE KEY-----` | Critical |
-| `connection-string` | `mongodb://user:pass@host`, `postgres://`, `DATABASE_URL=` | Critical |
-| `password` | `password=`, `DB_PASSWORD=`, `MYSQL_PASSWORD=` | High |
-| `env-variable` | `SECRET_KEY=`, `PRIVATE_TOKEN=`, `ENCRYPTION_PASS=` | High |
-| `pii` | Email addresses, possible SSNs | Medium |
-
-**2. Shannon entropy analysis**
-
-For strings that don't match a known pattern but look like secrets:
-- Scans all quoted strings ≥40 characters
-- Calculates Shannon entropy (randomness measure)
-- Flags strings with entropy ≥5.0 bits (very random = likely a secret)
-- Automatically skips: hex hashes, camelCase identifiers, base64 padding, integrity hashes, comments, test files
-
-### Smart filtering (false positive reduction)
-
-The scanner skips:
-- **Placeholders**: `${API_KEY}`, `{{SECRET}}`, `YOUR_KEY_HERE`, `CHANGE_ME`, `example`, `TODO`, `dummy`, `sample`
-- **Test files**: `*.test.ts`, `*.spec.ts`, `__tests__/*` (entropy analysis only — patterns still apply)
-- **Declaration files**: `*.d.ts` (entropy analysis only)
-- **Comments**: Lines starting with `//`, `#`, `*`
-
-### Output artifacts
-
-| File | Format | Purpose |
-|------|--------|---------|
-| `.cto/audit/YYYY-MM-DD.jsonl` | JSON Lines (append-only) | Audit log — one entry per run. Run daily to build history. |
-| `.cto/audit/report.md` | Markdown | Full report with findings table — share with team or compliance. |
-| `.cto/.env.example` | Text | Auto-generated `.env` template with all detected variable names. |
-
-### Audit log format (`.jsonl`)
-
-Each line is a JSON object:
-
-```json
-{
-  "timestamp": "2026-02-24T23:38:00.000Z",
-  "version": "3.2.0",
-  "summary": {
-    "filesScanned": 179,
-    "filesWithSecrets": 12,
-    "totalFindings": 51,
-    "bySeverity": { "critical": 34, "high": 5, "medium": 12, "low": 0 },
-    "byType": { "api-key": 21, "private-key": 5, "aws-key": 4, "token": 4, "connection-string": 3, "password": 2, "pii": 12 }
-  },
-  "findings": [
-    { "type": "api-key", "file": "src/config/stripe.ts", "line": 8, "severity": "critical", "redacted": "sk_l********************yZ" }
-  ]
-}
-```
-
-### Programmatic API
-
-```typescript
-import { auditProject, scanContentForSecrets, scanContentForHighEntropy } from 'cto-ai-cli/govern';
-
-// Full project audit
-const result = await auditProject('/path/to/project', filePaths, {
-  customPatterns: ['MY_INTERNAL_TOKEN=[a-z0-9]+'],  // optional extra patterns
-  entropyThreshold: 5.0,                            // default: 5.0
-  includePII: true,                                 // default: true
-});
-
-console.log(result.summary);          // { totalFindings, bySeverity, byType, ... }
-console.log(result.findings);         // SecretFinding[]
-console.log(result.recommendations);  // string[]
-
-// Scan a single string
-const findings = scanContentForSecrets(code, 'file.ts');
-
-// Entropy-only scan
-const entropyFindings = scanContentForHighEntropy(code, 'file.ts', 5.0);
-```
-
-### CI/CD integration
-
-When `CI=true` is set, `--audit` exits with code 1 if any critical or high-severity findings are detected. Use this in:
-
-**GitHub Actions:**
-```yaml
-- name: CTO Security Audit
-  run: npx cto-ai-cli --audit
-  env:
-    CI: true
-```
-
-**Pre-commit hook (`.husky/pre-commit`):**
-```bash
-CI=true npx cto-ai-cli --audit
-```
-
-### Recommendations engine
-
-Based on findings, CTO generates actionable recommendations:
-
-| Finding type | Recommendation |
-|-------------|----------------|
-| Any critical | "Rotate all detected credentials immediately" |
-| `password` | "Move passwords to environment variables or a secrets manager" |
-| `api-key` / `aws-key` | "Use environment variables. Never commit to source control" |
-| `connection-string` | "Database connection strings should use environment variables" |
-| `private-key` | "Private keys should NEVER be in source code. Use a key management service" |
-| `pii` | "Review for GDPR/CCPA compliance. Consider data anonymization" |
-| `high-entropy` | "High-entropy strings detected. Review manually" |
-| Any finding | "Add .gitignore entry for .env files" + "Run --audit regularly or add to CI" |
-
----
-
-## Context Gateway
-
-A transparent HTTP proxy that sits between your application and any LLM provider. It intercepts every request, scans for secrets, optimizes context, tracks costs, and enforces budgets — all with zero external dependencies.
-
-### Quick start
-
-```bash
-npx cto-gateway                    # Start on port 8787
-npx cto-gateway --port 9000        # Custom port
-npx cto-gateway --block-secrets    # Hard block on critical secrets
-npx cto-gateway --budget-daily 10  # $10/day limit
-```
-
-Then point your app:
-```bash
-export OPENAI_BASE_URL=http://localhost:8787
-```
-
-Every request must include the target provider URL as a header:
-```
-x-cto-target: https://api.openai.com/v1/chat/completions
-```
-
-### Architecture
-
-```
-Your App → Gateway (localhost:8787) → Provider (api.openai.com)
-                │
-                ├── Secret Scanner  → redacts/blocks secrets in messages
-                ├── Context Optimizer → injects CTO-selected context
-                ├── Cost Tracker → logs per-request cost to JSONL
-                ├── Budget Guard → rejects requests over limit (429)
-                └── Dashboard → live web UI at /__cto
-```
-
-### CLI flags
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--port <n>` | `8787` | Port to listen on |
-| `--host <addr>` | `127.0.0.1` | Host to bind to |
-| `--project <path>` | `.` | Project to analyze for context optimization |
-| `--block-secrets` | off | Hard block requests with critical secrets (403) |
-| `--budget-daily <$>` | unlimited | Max cost per day — returns 429 when exceeded |
-| `--budget-monthly <$>` | unlimited | Max cost per month |
-| `--no-optimize` | on | Disable CTO context injection |
-| `--no-redact` | on | Disable secret redaction |
-| `--no-dashboard` | on | Disable web dashboard |
-
-### Provider detection
-
-The Gateway auto-detects providers from the `x-cto-target` URL and request headers:
-
-| Provider | Detection | Auth header |
-|----------|-----------|-------------|
-| OpenAI | `api.openai.com` or `/v1/chat/completions` | `Authorization: Bearer sk-...` |
-| Anthropic | `api.anthropic.com` or `anthropic-version` header | `x-api-key` |
-| Google AI | `generativelanguage.googleapis.com` | `x-goog-api-key` |
-| Azure OpenAI | `*.openai.azure.com` or `api-key` header | `api-key` |
-| Custom | Fallback — assumes OpenAI-compatible | `Authorization` |
-
-### Model pricing
-
-Built-in pricing for accurate cost tracking:
-
-| Model | Input ($/M tokens) | Output ($/M tokens) | Context window |
-|-------|--------------------|--------------------|----------------|
-| gpt-4o | $2.50 | $10.00 | 128K |
-| gpt-4o-mini | $0.15 | $0.60 | 128K |
-| o1 | $15.00 | $60.00 | 200K |
-| o3-mini | $1.10 | $4.40 | 200K |
-| claude-sonnet-4 | $3.00 | $15.00 | 200K |
-| claude-3.5-haiku | $0.80 | $4.00 | 200K |
-| gemini-2.5-pro | $1.25 | $10.00 | 1M |
-| gemini-2.0-flash | $0.10 | $0.40 | 1M |
-
-### Request lifecycle
-
-1. **Receive** — Client sends POST request to Gateway
-2. **Budget check** — If daily/monthly budget exceeded → 429
-3. **Parse** — Detect provider, extract messages from provider-specific format
-4. **Scan secrets** — Run 30+ patterns against all message content
-5. **Redact or block** — Replace secrets with `***REDACTED***` or return 403
-6. **Optimize context** — If analysis ready, inject CTO-selected files into system prompt
-7. **Forward** — Proxy to provider (streaming SSE or buffered)
-8. **Track** — Log cost, tokens, savings, latency to JSONL
-9. **Respond** — Forward provider response to client (zero-copy for streams)
-
-### Streaming support
-
-The Gateway fully supports Server-Sent Events (SSE) streaming:
-
-- Detects streaming from `Content-Type: text/event-stream`
-- Zero-copy passthrough: chunks are forwarded to client as they arrive
-- Async token tracking: parses SSE events in background without blocking the stream
-- Usage data extracted from final SSE chunk (when provider includes it)
-
-### Dashboard
-
-Available at `http://localhost:8787/__cto` (configurable via `--dashboardPath`).
-
-Shows:
-- **Today**: requests, cost, tokens saved, secrets redacted
-- **This month**: totals + budget progress
-- **Feature status**: optimization, redaction, tracking, audit log
-- **By model**: breakdown of requests, tokens, and cost per model
-- **By provider**: requests and cost per provider
-- Auto-refreshes every 30 seconds
-
-### Usage storage
-
-| File | Format | Description |
-|------|--------|-------------|
-| `.cto/gateway/usage/YYYY-MM.jsonl` | JSON Lines | One line per request. Monthly files. |
-
-Each line:
-```json
-{
-  "id": "a1b2c3d4",
-  "timestamp": "2026-02-24T23:52:00.000Z",
-  "provider": "openai",
-  "model": "gpt-4o",
-  "inputTokens": 1200,
-  "outputTokens": 350,
-  "costUSD": 0.0065,
-  "originalTokens": 6200,
-  "optimizedTokens": 1200,
-  "savedTokens": 5000,
-  "savedUSD": 0.0130,
-  "secretsRedacted": 2,
-  "secretsBlocked": false,
-  "latencyMs": 152,
-  "stream": true
-}
-```
-
-### Budget enforcement
-
-When a budget is set, the Gateway checks cost totals before every request:
-
-| Condition | HTTP response |
-|-----------|---------------|
-| Daily budget exceeded | `429 Too Many Requests` + `{ "error": "Daily budget exceeded", "budget": 10, "current": 10.42 }` |
-| Monthly budget exceeded | `429 Too Many Requests` + `{ "error": "Monthly budget exceeded" }` |
-| Critical secrets + `--block-secrets` | `403 Forbidden` + `{ "error": "Request blocked: secrets detected" }` |
-
-Budget alerts are emitted at 80% of limit (configurable via `alertThreshold`).
-
-### Programmatic API
-
-```typescript
-import { ContextGateway, UsageTracker } from 'cto-ai-cli/gateway';
-
-const gateway = new ContextGateway({
-  port: 8787,
-  projectPath: '/path/to/project',
-  redactSecrets: true,
-  blockOnSecrets: false,
-  budgetDaily: 20,
-  budgetMonthly: 500,
-});
-
-// Listen to events
-gateway.onEvent((event) => {
-  if (event.type === 'request') console.log(`${event.record.model}: $${event.record.costUSD}`);
-  if (event.type === 'budget-alert') console.log(`Budget warning: ${event.period}`);
-});
-
-await gateway.start();
-
-// Get usage summary
-const tracker = gateway.getTracker();
-const summary = tracker.getSummary('month');
-console.log(`This month: ${summary.totalRequests} requests, $${summary.totalCostUSD}`);
-
-// Provider detection (standalone)
-import { detectProvider, estimateCost } from 'cto-ai-cli/gateway';
-
-const provider = detectProvider('https://api.openai.com/v1/chat/completions', {});
-const cost = estimateCost(provider, 'gpt-4o', 5000, 1000);
-```
-
-### Interceptor (standalone)
-
-```typescript
-import { interceptRequest } from 'cto-ai-cli/gateway';
-import type { Message, GatewayConfig } from 'cto-ai-cli/gateway';
-
-const messages: Message[] = [
-  { role: 'user', content: 'Deploy with key sk-live_abc123...' },
-];
-
-const result = await interceptRequest(messages, config, analysis);
-// result.secretsRedacted → 1
-// result.messages[0].content → 'Deploy with key sk-l**********23...'
-// result.decisions → ['Redacted 1 secret(s) in user message: api-key']
-```
-
----
-
-## Learning Mode
-
-CTO learns from your usage patterns to improve context selection over time. Three engines work together:
-
-### Feedback Engine (`--learn` / `--feedback`)
-
-Tracks which context selections lead to accepted AI output.
-
-```bash
-npx cto-ai-cli --learn                   # Full learning dashboard
-npx cto-ai-cli --learn --json            # Export for team sharing
-```
-
-**v2.0 Features:**
-
-| Feature | Description |
-|---------|-------------|
-| **EWMA Temporal Decay** | Recent feedback weighs more (α=0.15). Old patterns fade naturally. |
-| **Bayesian Confidence (Wilson Score)** | Avoids over-trusting sparse data. 1/1 ≠ 100% confidence. |
-| **Session Tracking** | Groups related feedback for per-session analysis. |
-| **A/B Strategy Comparison** | Compare different context strategies with statistical rigor. |
-| **Team Export/Import** | Share learned models across teams with weighted merge (local 70%, team 30%). |
-
-### Predictor Engine (`--predict`)
-
-Predicts which files are relevant for a task based on historical patterns.
-
-```bash
-npx cto-ai-cli --predict --context "fix auth bug"   # Predict files for a task
-npx cto-ai-cli --predict --json                      # JSON predictions
-```
-
-The predictor uses:
-- **Task type frequency** — which files were selected for similar task types (3× weight)
-- **Keyword frequency** — which files correlate with task keywords (2× weight)
-- **General selection frequency** — files selected in >30% of all observations
-- **Co-selection patterns** — files that tend to be selected together
-
-### Cross-Repo Intelligence
-
-Learns patterns across repositories. Stored in `~/.cto/global-intelligence.json`.
-
-- **Project fingerprinting** — stack, size class, structure pattern
-- **Archetype matching** — "TypeScript medium-size projects with tests"
-- **Universal patterns** — patterns that work across >50% of project types
-
-### Programmatic API
-
-```typescript
-import {
-  recordFeedback,
-  loadFeedbackModel,
-  getFeedbackBoosts,
-  exportFeedbackForTeam,
-  importTeamFeedback,
-  wilsonLowerBound,
-  renderFeedbackReport,
-  renderCrossRepoReport,
-} from 'cto-ai-cli/engine';
-import {
-  recordSelection,
-  predictRelevantFiles,
-  getPredictorBoosts,
-  loadModel,
-  getModelStats,
-} from 'cto-ai-cli/engine';
-import {
-  recordCrossRepoSelection,
-  predictFromCrossRepo,
-  loadGlobalModel,
-  getCrossRepoStats,
-  computeFingerprint,
-} from 'cto-ai-cli/engine';
-
-// Record feedback
-const model = await recordFeedback('/path/to/project', {
-  task: 'fix auth bug',
-  contextHash: 'abc123',
-  filesIncluded: ['src/auth.ts', 'src/types.ts'],
-  tokensUsed: 5000,
-  budget: 50000,
-  outcome: { accepted: true, compilable: true, timeToAcceptMs: 3000 },
-  sessionId: 'sess-1',       // optional: group feedback
-  strategy: 'experimental',  // optional: A/B testing
-});
-
-// Get boosts for context selection
-const boosts = await getFeedbackBoosts('/path/to/project', 'fix auth');
-// Map<string, number> — file path → boost value
-
-// Wilson score for statistical confidence
-const confidence = wilsonLowerBound(8, 10); // 8 successes out of 10
-// ~0.49 — 95% confident the true rate is ≥49%
-
-// Team sharing
-const exported = await exportFeedbackForTeam('/path/to/project', 'my-project');
-const merged = await importTeamFeedback('/other/project', exported);
-
-// Predict relevant files
-const predictions = await predictRelevantFiles('/path', 'fix auth', analysis);
-// { filePath, predictedScore, reasons }[]
-```
-
-### Storage
-
-| File | Scope | Description |
-|------|-------|-------------|
-| `.cto/feedback.json` | Per-project | Raw feedback entries (last 1000) |
-| `.cto/feedback-model.json` | Per-project | Rebuilt model with EWMA, Bayesian, sessions |
-| `.cto/predictor.json` | Per-project | ML predictor model |
-| `~/.cto/global-intelligence.json` | Cross-repo | Global archetype and pattern data |
-
----
-
-## Code Review
-
-Context-aware PR review intelligence. Analyzes git diffs, detects breaking changes, finds missing files, and generates AI-ready review prompts.
-
-### Usage
-
-```bash
-npx cto-ai-cli --review                  # Full review analysis
-npx cto-ai-cli --review --json           # JSON output for CI
-```
-
-Generates:
-- **Terminal dashboard** — review quality score, breaking changes, missing files, impact radius
-- **`.cto/review-prompt.md`** — AI-ready review prompt with full file contents
-
-### Features
-
-| Feature | Description |
-|---------|-------------|
-| **Diff Parsing** | Parses git diffs into structured DiffHunk[] with additions/deletions |
-| **Breaking Change Detection** | Removed exports, type changes, function signature changes, deleted files with dependents |
-| **Missing File Detection** | Sibling type files, test files, importers of changed exports, barrel index files |
-| **Impact Radius** | BFS on dependency graph: direct dependents, transitive (2-hop), affected tests |
-| **Review Quality Score** | 5-factor weighted score: PR size (25%), focus (20%), breaking changes (25%), completeness (15%), blast radius (15%) |
-| **Review Prompt Generation** | Context-rich prompt with breaking changes, missing files, and file contents for top-risk files |
-
-### Review Quality Score
-
-| Grade | Score | Meaning |
-|-------|-------|---------|
-| A+/A/A- | 85-100 | Small, focused PR with no breaking changes |
-| B+/B/B- | 70-84 | Manageable PR, some issues to review |
-| C+/C/C- | 55-69 | Large or unfocused PR, needs careful review |
-| D+/D/D- | 40-54 | Risky PR with breaking changes or missing files |
-| F | <40 | Very large, unfocused, or highly risky PR |
-
-### Breaking Change Severity
-
-| Severity | Trigger |
-|----------|--------|
-| **Critical** | Deleted file with dependents, removed export with >3 dependents |
-| **High** | Removed export, interface property removed, function signature changed |
-| **Medium** | Export changed with no direct dependents |
-
-### Programmatic API
-
-```typescript
-import { analyzeForReview, renderReviewSummary } from 'cto-ai-cli/engine';
-import type { ReviewResult, ReviewOptions } from 'cto-ai-cli/engine';
-
-const result: ReviewResult = await analyzeForReview(analysis, {
-  baseBranch: 'main',        // default: 'main'
-  depth: 2,                  // dependency expansion depth
-  maxPromptFiles: 20,        // max files in review prompt
-});
-
-console.log(result.breakingChanges);    // BreakingChange[]
-console.log(result.missingFiles);       // MissingFile[]
-console.log(result.impactRadius);       // { directlyAffected, transitivelyAffected, riskScore }
-console.log(result.reviewQuality);      // { score, grade, factors }
-console.log(result.reviewPrompt);       // Full AI-ready review prompt
-```
-
----
-
-## MCP Server
-
-CTO exposes 19 tools via the Model Context Protocol.
-
-### Setup
-
-**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
-```json
-{
-  "mcpServers": {
-    "cto": { "command": "cto2-mcp" }
-  }
-}
-```
-
-**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-```json
-{
-  "mcpServers": {
-    "cto": {
-      "command": "node",
-      "args": ["/path/to/cto-ai-cli/dist/mcp/v2.js"]
-    }
-  }
-}
-```
-
-### Tools
-
-| Tool | Category | Description |
-|------|----------|-------------|
-| `cto_analyze` | Engine | Full project analysis |
-| `cto_risk_profile` | Engine | Risk factors per file |
-| `cto_select_context` | Engine | Deterministic context selection |
-| `cto_pr_context` | Engine | PR-focused context from git diff |
-| `cto_score` | Engine | Context Score (0-100) |
-| `cto_benchmark` | Engine | CTO vs naive vs random |
-| `cto_quality_benchmark` | Engine | Relevance, completeness, noise metrics |
-| `cto_plan_interaction` | Interact | Full pipeline: analyze → select → prompt → cost |
-| `cto_get_prompt` | Interact | Rendered prompt ready to use |
-| `cto_estimate_cost` | Interact | Cost estimation for a model |
-| `cto_init` | Govern | Initialize .cto/ directory |
-| `cto_scan_secrets` | Govern | Scan for hardcoded secrets |
-| `cto_validate_policy` | Govern | Validate against policy rules |
-| `cto_snapshot_create` | Govern | Create reproducible snapshot |
-| `cto_snapshot_verify` | Govern | Verify snapshot (detect drift) |
-| `cto_snapshot_compare` | Govern | Compare two snapshots |
-| `cto_audit_query` | Govern | Query audit trail |
-| `cto_cache_stats` | Infra | Cache statistics |
-| `cto_watch_status` | Infra | Active file watchers |
-
-### Resources
-
-- `cto://analysis/{projectPath}` — Full analysis as JSON
-
-### Prompts
-
-- `plan-task` — Plan an optimized AI interaction
-- `review-context` — Review what context would be selected
-
----
-
-## API Server
-
-Start a REST API server for integration with any tool or language.
-
-```bash
-cto2-api                                    # start on port 3141
-PORT=8080 cto2-api                          # custom port
-CTO_API_KEY=your-secret cto2-api            # with auth
-CTO_API_KEY=your-secret RATE_LIMIT=30 cto2-api  # with rate limiting
-```
-
-### Endpoints
-
-| Method | Path | Body | Description |
-|--------|------|------|-------------|
-| `POST` | `/v1/analyze` | `{ "path": "..." }` | Full project analysis |
-| `POST` | `/v1/select` | `{ "path": "...", "task": "...", "budget": 50000 }` | Context selection |
-| `POST` | `/v1/score` | `{ "path": "..." }` | Context Score |
-| `POST` | `/v1/benchmark` | `{ "path": "...", "task": "..." }` | Benchmark comparison |
-| `POST` | `/v1/quality` | `{ "path": "...", "task": "..." }` | Quality benchmark |
-| `POST` | `/v1/pr-context` | `{ "path": "...", "task": "...", "base": "main" }` | PR context |
-| `POST` | `/v1/interact` | `{ "path": "...", "task": "...", "budget": 50000 }` | Full pipeline |
-| `GET` | `/v1/health` | — | Health check |
-| `GET` | `/v1/openapi` | — | OpenAPI 3.1 spec |
-
-### Example
-
-```bash
-# Score a project
-curl -X POST http://localhost:3141/v1/score \
-  -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer your-secret' \
-  -d '{"path": "/path/to/project"}'
-
-# Select context for a task
-curl -X POST http://localhost:3141/v1/select \
-  -H 'Content-Type: application/json' \
-  -d '{"path": "/path/to/project", "task": "refactor auth", "budget": 50000}'
-```
-
-### Authentication
-
-Set `CTO_API_KEY` environment variable. All requests must include `Authorization: Bearer <key>`.
-
-If `CTO_API_KEY` is not set, the server runs without auth (development mode).
-
-### Rate Limiting
-
-Default: 60 requests per minute per IP. Configurable via `RATE_LIMIT` env var.
-
----
-
-## Programmatic API
-
-```typescript
-import { analyzeProject, getCachedAnalysis } from 'cto-ai-cli/engine';
-import { planInteraction } from 'cto-ai-cli/interact';
-import { validateSelection, DEFAULT_POLICY } from 'cto-ai-cli/govern';
-
-// Analyze (cached — instant on repeat calls)
-const analysis = await getCachedAnalysis('/path/to/project');
-
-// Plan an interaction
-const plan = await planInteraction({
-  task: 'refactor the auth middleware',
-  analysis,
-  budget: 50_000,
-});
-
-console.log(plan.context.files);       // Selected files with prune levels
-console.log(plan.model);               // Recommended model + alternatives
-console.log(plan.cost.savings);        // Token & dollar savings
-console.log(plan.prompt.rendered);     // Ready-to-use prompt
-
-// Context Score
-import { computeContextScore } from 'cto-ai-cli/engine';
-const score = await computeContextScore(analysis);
-console.log(score.overall, score.grade); // 87, "A-"
-
-// Benchmark
-import { runBenchmark } from 'cto-ai-cli/engine';
-const benchmark = await runBenchmark(analysis);
-console.log(benchmark.ctoAdvantage);
-
-// Validate against policies
-const validation = validateSelection(plan.context, DEFAULT_POLICY, analysis.files);
-console.log(validation.passed);
-```
-
----
-
-## GitHub Action
-
-Post Context Score on every PR.
-
-```yaml
-# .github/workflows/cto-score.yml
-name: CTO Context Score
-on: [pull_request]
-
-jobs:
-  score:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - uses: cto-ai/cto-ai-cli@main
-        with:
-          comment-on-pr: 'true'
-          fail-below: '40'
-```
-
-### Inputs
-
-| Input | Default | Description |
-|-------|---------|-------------|
-| `path` | `.` | Project path |
-| `budget` | `50000` | Token budget |
-| `task` | `general code review` | Representative task |
-| `comment-on-pr` | `true` | Post PR comment |
-| `fail-below` | `0` | Fail if score below threshold |
-
-### Outputs
-
-| Output | Description |
-|--------|-------------|
-| `score` | Context Score (0-100) |
-| `grade` | Grade (A+ to F) |
-| `saved-percent` | Token savings % |
-| `monthly-savings` | USD saved per month |
-| `json` | Full results as JSON |
-
----
-
-## Configuration
-
-CTO uses `.cto/config.yml` in your project root.
-
-```yaml
-version: "2.0"
-tokenMethod: tiktoken    # tiktoken (accurate) | chars4 (fast)
-defaultBudget: 50000     # default token budget
-
-ignoreDirs:
-  - node_modules
-  - .git
-  - dist
-  - build
-  - coverage
-
-extensions:
-  - ts
-  - tsx
-  - js
-  - jsx
-  - py
-  - go
-  - rs
-  - java
-```
-
----
-
-## Architecture
-
-```
-src/
-├── engine/              # Context Intelligence Engine
-│   ├── analyzer.ts          # Project analysis pipeline
-│   ├── graph.ts             # Dependency graph
-│   ├── risk.ts              # Risk scoring
-│   ├── selector.ts          # Deterministic context selection
-│   ├── score.ts             # Context Score (0-100)
-│   ├── benchmark.ts         # Strategy comparison
-│   ├── compile-proof.ts     # Real tsc compilation test
-│   ├── multi-model.ts       # Per-model optimization
-│   ├── predictor.ts         # ML-based prediction (learns from usage)
-│   ├── semantic.ts          # Semantic domain analysis
-│   ├── feedback.ts          # Output feedback loop (v2: EWMA, Bayesian, A/B, team)
-│   ├── cross-repo.ts        # Cross-repo intelligence
-│   ├── code-review.ts       # Context-aware PR review engine
-│   ├── monorepo.ts          # Monorepo intelligence
-│   └── quality-gate.ts      # CI/CD quality gate
-├── interact/            # Interaction Optimization
-│   ├── orchestrator.ts      # Full pipeline
-│   ├── router.ts            # Model routing
-│   ├── prompt.ts            # Prompt builder
-│   └── estimator.ts         # Cost estimation
-├── govern/              # Governance & Audit
-│   ├── audit.ts             # Audit trail
-│   ├── secrets.ts           # Secret detection
-│   ├── policy.ts            # Policy engine
-│   ├── snapshot.ts          # Snapshots
-│   └── integrity.ts         # SHA-256 verification
-├── cli/
-│   ├── score.ts             # npx cto-score entry point
-│   └── v2/index.ts          # Full CLI
-├── mcp/v2.ts            # MCP server (19 tools)
-├── api/
-│   ├── server.ts            # REST API server
-│   └── dashboard.ts         # HTML dashboard generator
-└── action/index.ts      # GitHub Action
-```