carto-md 2.0.1 → 2.0.2

package/BENCHMARK_RESULTS.md

@@ -0,0 +1,34 @@
+# Carto V2 Benchmark Results
+
+Generated: 2026-05-28T17:58:28.019Z
+Platform: Node v20.20.1 · 8 CPUs · 8192.0 MB RAM · darwin arm64
+
+| Repo | Source Files | Indexed | First Run | Second Run | DB Size | Routes | Import Edges |
+|------|-------------|---------|-----------|------------|---------|--------|--------------|
+| prisma | 3303 | 3303 | 1.6s | 178ms | 2.2 MB | 10 | 3590 |
+| supabase | 6818 | 6746 | 4.9s | 725ms | 4.3 MB | 90 | 5754 |
+| vscode | 10565 | 10565 | 9.7s | 1.2s | 10.6 MB | 11 | 19769 |
+| zed | 1837 | 1837 | 2.7s | 83ms | 4.7 MB | 12 | 2176 |
+
+## Domains Detected
+
+**prisma:** DATABASE(1044) · CORE(752) · EVENTS(36) · AUTH(8)
+**supabase:** CORE(4243) · AUTH(412) · DATABASE(387) · PAYMENTS(51) · EVENTS(17) · NOTIFICATIONS(12) · TRPC(3)
+**vscode:** CORE(5330) · AUTH(850) · EVENTS(446) · DATABASE(419) · NOTIFICATIONS(5)
+**zed:** CORE(1424) · DATABASE(110) · AUTH(75) · EVENTS(55) · PAYMENTS(53) · NOTIFICATIONS(10) · TRPC(2)
+
+## MCP Query Latency
+
+| Repo | get_structure | get_routes | get_domains_list |
+|------|--------------|------------|-----------------|
+| prisma | 0ms | 0ms | 1ms |
+| supabase | 1ms | 0ms | 3ms |
+| vscode | 1ms | 0ms | 3ms |
+| zed | 0ms | 0ms | 1ms |
+
+## Target Assessment
+
+- **prisma**: ✅ All targets met
+- **supabase**: ✅ All targets met
+- **vscode**: ✅ All targets met
+- **zed**: ✅ All targets met

package/CONTRIBUTING.md

@@ -215,7 +215,7 @@ cd carto
 npm install
 node src/cli/index.js init   # test in any project
 node src/cli/index.js serve  # test MCP server
-npm test                     # run test suite (30 tests)
+npm test                     # run test suite (35 tests)
 node test/correctness.js     # run correctness tests (31 tests)
 node test/benchmark.js       # run benchmarks against real repos
 ```
@@ -232,7 +232,7 @@ node test/benchmark.js       # run benchmarks against real repos
 - [ ] Extension added to `CODE_EXTS` and `detectLanguage()` in `sync-v2.js`
 - [ ] No changes to merger logic (unless explicitly fixing a merger bug)
 - [ ] No network calls added
-- [ ] `npm test` passes (30/30)
+- [ ] `npm test` passes (35/35)
 - [ ] `node test/correctness.js` passes (31/31)
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carto-md",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Structural intelligence layer for AI coding tools. Indexes your codebase into SQLite — routes, models, import graph, blast radius, domains — and exposes 16 MCP tools for Kiro, Cursor, and Claude.",
   "bin": {
     "carto": "src/cli/index.js"

package/src/agents/formatter.js

@@ -16,6 +16,9 @@ function formatSections({ routes, models, frontend, structure, warnings, fileMap
       sections.push(`- ${icon} ${entry.name}${suffix}`);
     }
   } else {
+    if (process.env.CARTO_DEBUG) {
+      console.warn('[CARTO] Warning: structure data was empty when formatting AGENTS.md');
+    }
     sections.push('_No structure data available._');
   }
 

package/src/agents/scan-structure.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * IGNORE_DIRS — names skipped at the top level when listing project structure.
+ *
+ * This is intentionally a *small* set tuned for the "Project Structure (auto)"
+ * block in AGENTS.md. It is NOT the same as the recursive file-discovery
+ * ignore lists (e.g. JS_IGNORE / PYTHON_IGNORE in src/detector/files.js or
+ * IGNORE_DIRS in src/store/sync-v2.js) — those filter what gets indexed.
+ *
+ * Top-level structure should still surface things like `dist/`, `build/`,
+ * `coverage/` (so users see what their project actually contains), but it
+ * should hide noise (`node_modules`, `.git`, `.carto`, etc.) and the file
+ * the structure block is about to be merged into (`AGENTS.md`).
+ *
+ * Anchored on the original V1 set in src/sync.js so existing AGENTS.md
+ * outputs do not drift after the V1 → V2 cleanup.
+ */
+const IGNORE_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '__pycache__',
+  '.venv',
+  'venv',
+  '.idea',
+  '.vscode',
+  '.carto',
+  'AGENTS.md'
+]);
+
+/**
+ * scanStructure(basePath) → Array<{ name: string, type: 'dir' | 'file' }>
+ *
+ * Lists the immediate children of `basePath` (one level deep, no recursion).
+ * Filters out IGNORE_DIRS. Sorts: directories before files; alphabetical
+ * within each group.
+ *
+ * Symlinks are reported by Dirent as neither dir nor file → treated as 'file'.
+ * Failures (missing dir, EACCES, etc.) return an empty array silently — the
+ * formatter handles the empty case.
+ */
+async function scanStructure(basePath) {
+  const entries = [];
+  let items;
+  try {
+    items = await fs.promises.readdir(basePath, { withFileTypes: true });
+  } catch {
+    return entries;
+  }
+
+  for (const item of items) {
+    if (IGNORE_DIRS.has(item.name)) continue;
+    entries.push({
+      name: item.name,
+      type: item.isDirectory() ? 'dir' : 'file'
+    });
+  }
+
+  entries.sort((a, b) => {
+    if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+
+  return entries;
+}
+
+module.exports = { scanStructure, IGNORE_DIRS };

package/src/store/sync-v2.js

@@ -13,6 +13,7 @@ const { clusterByDomain } = require('../agents/domains');
 const { clusterByGraph } = require('../agents/leiden');
 const { formatSections, formatDomainFile } = require('../agents/formatter');
 const { mergeIntoAgentsMd } = require('../agents/merger');
+const { scanStructure } = require('../agents/scan-structure');
 const { WorkerPool, POOL_SIZE } = require('../engine/worker-pool');
 const { parseCartoIgnore } = require('../security/ignore');
 
@@ -420,7 +421,7 @@ async function runSyncV2(config) {
 
   // 8. Generate outputs (only if files changed)
   if (toProcess.length > 0) {
-    generateOutputs(store, config, projectRoot, store.getImportGraph());
+    await generateOutputs(store, config, projectRoot, store.getImportGraph());
   }
 
   console.log(`[CARTO] Indexed ${toProcess.length} files (${cached} cached) in ${elapsed}ms`);
@@ -461,12 +462,13 @@ function buildFileDataFromStore(store) {
 /**
  * Generate backward-compatible outputs (AGENTS.md, context files, map.json)
  */
-function generateOutputs(store, config, projectRoot, importGraph) {
+async function generateOutputs(store, config, projectRoot, importGraph) {
   const structure = store.getStructure();
   const routes = store.getRoutes();
   const models = store.getModels();
   const envVars = store.getEnvVars();
   const domains = store.getDomainsList();
+  const topLevelStructure = await scanStructure(projectRoot);
 
   // Write domain context files — lazy: only write if stale or missing
   const contextDir = path.join(projectRoot, '.carto', 'context');
@@ -518,7 +520,7 @@ function generateOutputs(store, config, projectRoot, importGraph) {
       routes,
       models,
       frontend: { fetches: [], storageKeys: [] },
-      structure: [],
+      structure: topLevelStructure,
       warnings: [],
       fileMap: [],
       functions: {},

package/src/sync.js

@@ -13,8 +13,7 @@ const { buildStackLine } = require('./extractors/stack');
 const { loadHashes, saveHashes, computeChangedFiles } = require('./cache/file-hash');
 const { loadGraphCache, saveGraphCache, buildEmptyCache } = require('./cache/graph-cache');
 const { applyIncrementalUpdate, recomputeGraphMetrics } = require('./engine/incremental');
-
-const IGNORE_DIRS = new Set(['node_modules', '.git', '__pycache__', '.venv', 'venv', '.idea', '.vscode', '.carto', 'AGENTS.md']);
+const { scanStructure } = require('./agents/scan-structure');
 
 // Load plugins once at module load
 const plugins = loadLanguagePlugins();
@@ -29,22 +28,6 @@ async function safeReadFile(filePath, warnings) {
   }
 }
 
-async function scanStructure(basePath) {
-  const entries = [];
-  try {
-    const items = await fs.promises.readdir(basePath, { withFileTypes: true });
-    for (const item of items) {
-      if (IGNORE_DIRS.has(item.name)) continue;
-      entries.push({ name: item.name, type: item.isDirectory() ? 'dir' : 'file' });
-    }
-    entries.sort((a, b) => {
-      if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
-      return a.name.localeCompare(b.name);
-    });
-  } catch {}
-  return entries;
-}
-
 /**
  * runFullSync(config)
  *

package/acp-strategy.md

@@ -1,480 +0,0 @@
-# Carto ACP Agent — Strategy & Implementation Plan
-
-> Build the brain, not the editor. Ship to every IDE in weeks.
-
----
-
-## What is ACP?
-
-**Agent Client Protocol (ACP)** is an open standard created by Zed Industries that lets any AI coding agent work inside any compatible editor — without custom integrations.
-
-- **LSP** = one standard so any editor supports any programming language
-- **ACP** = one standard so any editor supports any AI coding agent
-
-**Transport:** JSON-RPC 2.0 over stdin/stdout (local) or HTTP/WebSocket (remote)  
-**Editors:** Zed, JetBrains (IntelliJ, WebStorm, etc.), VS Code (in progress)  
-**SDK:** `@agentclientprotocol/sdk` (TypeScript/JS, Python, Rust, Kotlin, Java)
-
----
-
-## The Core Idea
-
-Instead of building a standalone editor, build Carto as an **ACP agent** that plugs into existing editors. Carto already has the structural intelligence — ACP gives it hands.
-
-```
-┌─────────────────────────────────────────┐
-│  Zed / JetBrains / VS Code             │
-│  ┌───────────────────────────────────┐  │
-│  │  Agent Panel → "Carto" thread     │  │
-│  │                                   │  │
-│  │  User: "Add rate limiting to      │  │
-│  │         /api/users"               │  │
-│  │                                   │  │
-│  │  Carto: I see AUTH domain has     │  │
-│  │  12 files, 3 routes. Highest      │  │
-│  │  impact: auth/session.ts          │  │
-│  │  (8 dependents). Here's my plan:  │  │
-│  │  [shows file diffs inline]        │  │
-│  └───────────────────────────────────┘  │
-└─────────────────────────────────────────┘
-         ↕ ACP (stdin/stdout)
-┌─────────────────────────────────────────┐
-│  carto agent (Node.js process)          │
-│  ├── Carto structural intelligence      │
-│  ├── LLM calls (user's own API key)    │
-│  └── File edits streamed back           │
-└─────────────────────────────────────────┘
-```
-
----
-
-## How Data Flows (MCP vs ACP)
-
-### Current: MCP (passive tool server)
-
-```
-External AI (Claude/Cursor) decides to call a tool
-    ↓
-get_blast_radius("auth.service.ts")
-    ↓
-Carto returns a SUMMARY → "3 files affected, risk HIGH"
-    ↓
-AI uses summary to answer (may miss context, can't read files through Carto)
-```
-
-**Problem:** LLM gets summaries, not full context. It has to guess which tools to call. It can't read actual file contents through Carto.
-
-### New: ACP (active intelligent agent)
-
-```
-User asks: "Add rate limiting to /api/users"
-    ↓
-Carto agent receives message
-    ↓
-Carto INTERNALLY queries its own SQLite:
-  - Blast radius of relevant files
-  - Domain context (AUTH)
-  - Similar patterns in codebase
-  - Import graph neighbors
-    ↓
-Carto reads ACTUAL file contents via ACP fileSystem
-    ↓
-Carto builds a RICH prompt with all context + file contents
-    ↓
-Sends to LLM (user's API key) → gets response
-    ↓
-Streams answer + file diffs back to editor
-```
-
-**Key difference:** Carto controls the LLM call. It proactively provides the right context instead of waiting for the LLM to ask.
-
-### What the LLM receives (built by Carto):
-
-| Data | How it gets to the LLM |
-|------|----------------------|
-| Structural facts (blast radius, domains, routes) | Carto queries SQLite internally → injects into system prompt |
-| Relevant file contents (actual code) | Carto reads via ACP fileSystem → includes in prompt |
-| Domain context (`.carto/context/AUTH.md` etc.) | Carto reads internally → includes relevant domain |
-| Import graph | Carto summarizes relevant portion → injects |
-| Similar patterns | Carto finds matching files → includes as examples |
-
-Carto acts as a **smart filter** — only sends what's relevant. No token waste.
-
----
-
-## Auto-Index on First Session
-
-When a user opens a Carto agent thread in any project:
-
-```
-User opens Carto agent thread in Zed
-    ↓
-Carto checks: does .carto/carto.db exist?
-    ↓
-NO → automatically runs full indexing
-    ↓
-  • Discovers all source files
-  • tree-sitter parse → imports + symbols (0.05–0.2ms/file)
-  • Babel deep parse → routes + models (API files only)
-  • Leiden+CPM graph clustering → domain detection
-  • Computes reverse deps → blast radius
-  • Writes .carto/carto.db + context/*.md
-    ↓
-Takes 1-10 seconds depending on repo size:
-  • Prisma (3,303 files): 1.6s
-  • Supabase (6,818 files): 4.9s
-  • VS Code (10,565 files): 9.7s
-    ↓
-Agent responds: "Indexed! Found X files, Y routes, Z domains. How can I help?"
-    ↓
-YES → opens SQLite instantly (<10ms), ready to go
-```
-
-**On subsequent sessions:** No re-indexing. SQLite opens in <10ms.
-
-**On file changes:** If `carto watch` is running, DB stays live. If not, agent can do a quick mtime check on session start (178ms–1.2s for unchanged repos).
-
-### What gets created on disk:
-
-```
-project/
-├── .carto/
-│   ├── carto.db              ← SQLite (import graph, routes, models, domains, blast radius)
-│   ├── config.json           ← project settings
-│   └── context/
-│       ├── AUTH.md           ← domain context (auto-generated)
-│       ├── CORE.md
-│       ├── DATABASE.md
-│       └── PAYMENTS.md
-├── AGENTS.md                 ← still generated (useful for other MCP tools)
-└── src/...
-```
-
-Same as today. ACP doesn't change what Carto creates — just who reads it.
-
----
-
-## Supported LLM Providers (BYOK)
-
-Carto currently has **zero LLM integration** — it's purely structural intelligence. The ACP agent adds LLM calls. We support any provider the user brings:
-
-### Tier 1 — Full support (streaming, tool use, all models)
-
-| Provider | Protocol | Models |
-|----------|----------|--------|
-| **OpenAI** | `openai` | GPT-4o, GPT-4o-mini, o1, o3 |
-| **Anthropic** | `anthropic` | Claude Sonnet 4, Claude Haiku |
-| **Google Gemini** | `openai` (compatible) | Gemini 2.5 Pro, 2.5 Flash |
-
-### Tier 2 — Works via OpenAI-compatible API
-
-| Provider | Protocol | Notes |
-|----------|----------|-------|
-| **Azure OpenAI** | `azure` | Enterprise deployments |
-| **AWS Bedrock** | `bedrock` | Claude/Titan via AWS |
-| **Ollama** | `openai` | Local models (Llama, Mistral, Qwen, DeepSeek) |
-| **OpenRouter** | `openai` | Any model via single API |
-| **Together AI** | `openai` | Open-source models hosted |
-| **Groq** | `openai` | Ultra-fast inference |
-| **LM Studio** | `openai` | Local GUI + API |
-| **vLLM** | `openai` | Self-hosted inference |
-
-### How BYOK works in ACP:
-
-```
-1. User installs Carto agent in Zed/JetBrains
-2. Editor calls providers/list → Carto returns supported providers
-3. User configures their key in editor settings:
-   - API key (stored securely by editor)
-   - Base URL (for self-hosted/proxy)
-   - Model name
-4. Editor calls providers/set → Carto stores config
-5. All LLM calls use user's key — zero cost to us
-```
-
-### Provider config stored in:
-
-```json
-// .carto/agent-config.json (gitignored)
-{
-  "provider": {
-    "apiType": "anthropic",
-    "baseUrl": "https://api.anthropic.com",
-    "model": "claude-sonnet-4-20250514"
-  }
-}
-```
-
-API keys are NEVER stored by Carto — they're passed via ACP `providers/set` headers at runtime and held in memory only.
-
-### Cost to user:
-
-| Usage Level | Tokens/day | Claude Sonnet | Gemini Flash (free) | Ollama (local) |
-|-------------|-----------|---------------|--------------------|----|
-| Light (5 tasks) | ~50K | ~$0.15 | $0.00 | $0.00 |
-| Medium (15 tasks) | ~150K | ~$0.50 | $0.00 | $0.00 |
-| Heavy (30+ tasks) | ~400K | ~$1.20 | $0.00 (rate limits) | $0.00 |
-| Power user | ~1M | ~$3.00 | Needs paid tier | $0.00 |
-
----
-
-## What ACP Gives You For Free
-
-Everything the editor handles natively — zero code from us:
-
-| Feature | ACP / Editor Handles It |
-|---------|------------------------|
-| Chat panel UI | ✅ Zed/JetBrains Agent Panel |
-| Multiple chats / threads | ✅ Built-in threads sidebar |
-| Conversation persistence & resume | ✅ Editor manages sessions |
-| Stop / Interrupt button | ✅ Native editor stop |
-| Inline diffs with Accept / Reject | ✅ ACP native diff content type |
-| "Open in Editor" for large diffs | ✅ Native editor behavior |
-| Tool call visibility (collapsed) | ✅ Editor renders agent plan |
-| File read / write / create / delete | ✅ ACP `fileSystem` capability |
-| Terminal / command execution | ✅ ACP `terminals` capability |
-| Streaming token responses | ✅ ACP streams natively |
-| BYOK (Bring Your Own Key) | ✅ ACP `providers/set` |
-| Session list / resume old chats | ✅ ACP `session/list`, `session/resume` |
-| Redirect mid-task | ✅ Editor supports new message while agent runs |
-| Keyboard shortcuts | ✅ Editor-native |
-
-**~75-80% of the chat.md spec is free from ACP.**
-
----
-
-## What We Build (The Actual Product)
-
-### 1. Auto-Context Injection
-
-Every user message gets enriched with structural context before hitting the LLM:
-
-```javascript
-// What we inject into the system prompt (user doesn't see this)
-const context = carto.getContextForFile(session.currentFile);
-
-// Becomes:
-`Current file: src/auth/auth.service.ts
-Domain: AUTH
-Blast radius: 3 routes, 2 services affected
-  - Directly affected: auth.routes.ts, auth.controller.ts, auth.middleware.ts
-  - Routes impacted: POST /auth/login, GET /auth/me, POST /auth/register
-Import graph: session.service.ts, user.repository.ts
-Imported by: auth.routes.ts, auth.middleware.ts`
-```
-
-### 2. Carto Intelligence as Internal Tools
-
-The LLM can call these during reasoning (Carto handles them internally):
-
-```
-get_blast_radius(file)     → full impact analysis
-get_structure()            → project architecture
-get_domain(name)           → domain routes, models, files
-get_routes()               → all API endpoints
-get_change_plan(intent)    → files to touch, similar patterns
-get_context(file)          → everything about a file
-get_similar_patterns(file) → conventions to follow
-```
-
-### 3. The Agent Loop
-
-```javascript
-async function handlePrompt(userMessage, session) {
-  // 1. Auto-index if needed
-  if (!dbExists(session.workingDir)) {
-    await indexProject(session.workingDir);
-    stream("Indexed! Found X files, Y routes, Z domains.\n\n");
-  }
-
-  // 2. Get structural context for current file
-  const context = carto.getContextForFile(session.currentFile);
-
-  // 3. Build messages with rich context
-  const messages = [
-    { role: "system", content: buildSystemPrompt(context) },
-    ...session.history,
-    { role: "user", content: userMessage }
-  ];
-
-  // 4. Agent loop
-  let iterations = 0;
-  while (iterations++ < 25) {
-    const response = await callLLM(messages, {
-      provider: session.provider,
-      tools: [...CARTO_TOOLS, ...FILE_TOOLS],
-      stream: true
-    });
-
-    for (const block of response) {
-      if (block.type === "text") stream(block.text);
-      if (block.type === "tool_use") {
-        const result = await executeTool(block, session);
-        messages.push(toolResult(block.id, result));
-      }
-    }
-
-    if (noMoreToolCalls(response)) break;
-  }
-}
-```
-
-### 4. System Prompt
-
-```
-You are Carto, an AI coding agent with deep architectural awareness.
-
-You understand this project's structure before writing a single line:
-- Every file's blast radius (what breaks if this changes)
-- All API routes and which files define them
-- Domain clusters (AUTH, PAYMENTS, DATABASE, etc.)
-- The full import graph and cross-domain dependencies
-
-RULES:
-1. Always check blast radius before making changes to high-impact files
-2. Reference real file names and routes — never hallucinate paths
-3. Make minimal, focused changes — read first, then write
-4. Warn the user if a change crosses domain boundaries
-5. After changes, confirm what was changed and what it affects
-6. Use existing patterns (check get_similar_patterns before writing new code)
-7. If unsure, read the relevant files — don't guess
-
-CONTEXT (auto-provided every message):
-Current file: {filePath}
-Domain: {domain}
-Blast radius: {blastRadius}
-Imports: {imports}
-Imported by: {importedBy}
-```
-
----
-
-## What You Lose vs Standalone Editor
-
-| Spec Feature | Reality with ACP |
-|---|---|
-| Custom UI layout (exact mockup) | ❌ Editor's standard agent panel |
-| `📖 🎯 ⚡` icons per tool type | ❌ Editor decides tool call rendering |
-| Auto-context badge visible to user | ❌ Context is invisible (sent to LLM only) |
-| Custom storage format | ❌ Editor manages persistence |
-| Custom keyboard shortcuts | ❌ Editor controls shortcuts |
-
-**All cosmetic.** The intelligence differentiators are fully preserved.
-
----
-
-## ACP vs Building Standalone
-
-| | Standalone Editor | ACP Agent |
-|---|---|---|
-| Time to ship V1 | 6-12 months | 4-6 weeks |
-| UI control | Full | Limited (editor's panel) |
-| Editor reach | Only ours | Zed + JetBrains + VS Code |
-| Core intelligence | ✅ | ✅ (same) |
-| Blast radius / domain awareness | ✅ | ✅ (same) |
-| BYOK | Build it | Free from ACP |
-| Diff viewer | Build it | Free from ACP |
-| Terminal integration | Build it | Free from ACP |
-| Session persistence | Build it | Free from ACP |
-| LLM provider switching | Build it | Free from ACP |
-
----
-
-## Implementation Plan
-
-### Phase 1 — Core Agent (Week 1-2)
-
-- [ ] Add `carto agent` CLI command (starts ACP mode via stdin/stdout)
-- [ ] Implement `AgentSideConnection` with capabilities: `fileSystem`, `terminals`
-- [ ] Auto-index on first session (detect missing `.carto/carto.db` → run sync)
-- [ ] Wire Carto tools as internal agent tools
-- [ ] Build agent loop (context injection → LLM call → tool routing → stream back)
-- [ ] Write system prompt with auto-context
-
-### Phase 2 — LLM Providers / BYOK (Week 2-3)
-
-- [ ] Implement `providers/list` — advertise supported providers
-- [ ] Implement `providers/set` — accept API key + base URL + model
-- [ ] OpenAI provider (GPT-4o, GPT-4o-mini)
-- [ ] Anthropic provider (Claude Sonnet, Haiku)
-- [ ] Gemini provider (via OpenAI-compatible endpoint)
-- [ ] Generic OpenAI-compatible provider (Ollama, OpenRouter, Together, Groq, LM Studio, vLLM)
-- [ ] Azure OpenAI provider
-- [ ] Store model config in `.carto/agent-config.json` (gitignored, no secrets)
-
-### Phase 3 — Polish (Week 3-4)
-
-- [ ] 25-iteration safety cap with pause + user prompt
-- [ ] Context overflow handling (auto-summarize old messages)
-- [ ] Blast radius check before AND after file writes
-- [ ] Cross-domain change warnings
-- [ ] Register in ACP Registry (discoverable from Zed/JetBrains)
-
-### Phase 4 — Advanced (Week 5+)
-
-- [ ] Parallel agent support (multiple Carto threads on different tasks)
-- [ ] Slash commands (`/blast`, `/domain`, `/routes`)
-- [ ] Agent plan display (show what Carto intends to do before doing it)
-- [ ] If traction warrants: standalone editor with full UI control
-
----
-
-## Technical Setup
-
-```bash
-# Install ACP SDK
-npm install @agentclientprotocol/sdk
-
-# CLI commands
-carto serve    # existing — MCP mode (passive tools, keep as-is)
-carto agent    # new — ACP mode (active agent, stdin/stdout)
-```
-
-### File structure (new code):
-
-```
-src/
-├── acp/
-│   ├── agent.js           ← ACP AgentSideConnection setup
-│   ├── session.js         ← Session management + auto-index
-│   ├── prompt.js          ← System prompt builder + context injection
-│   ├── tools.js           ← Carto tools exposed to LLM
-│   └── providers/
-│       ├── index.js       ← Provider registry + BYOK logic
-│       ├── openai.js      ← OpenAI/compatible provider
-│       ├── anthropic.js   ← Anthropic provider
-│       └── types.js       ← Shared types
-├── cli/
-│   ├── index.js           ← add "agent" command
-│   └── agent.js           ← new: starts ACP mode
-├── mcp/                   ← existing MCP server (unchanged)
-└── ...                    ← existing Carto intelligence (unchanged)
-```
-
----
-
-## References
-
-- **ACP TypeScript SDK:** `@agentclientprotocol/sdk` ([npm](https://www.npmjs.com/package/@agentclientprotocol/sdk))
-- **ACP Spec:** https://agentclientprotocol.com
-- **Reference impl:** [Gemini CLI ACP](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/zed-integration/zedIntegration.ts)
-- **ACP Registry:** https://zed.dev/blog/acp-registry
-- **Configurable LLM Providers RFD:** https://agentclientprotocol.com/rfds/custom-llm-endpoint
-
----
-
-## Why This Makes Sense
-
-Carto already has the hard part — understanding codebases at scale:
-- 10,565 files indexed in <10 seconds
-- Blast radius computed in <5ms
-- Domain detection via graph clustering
-- Route/model extraction across 8 languages
-
-What it's missing: the ability to **act** on that knowledge. ACP gives it hands (file edits, terminal) and a voice (LLM reasoning). The combination — structural intelligence + LLM + editor integration — is what makes this better than every other AI coding agent.
-
-Other agents are smart but blind. Carto sees the architecture. ACP lets it act on what it sees.
-
----
-
-*Decision: Go ACP. Auto-index on first session. Support all major LLM providers via BYOK. Ship to Zed + JetBrains in 4-6 weeks.*