carto-md 2.0.9 → 2.1.0

package/docs/concepts/blast-radius.md

@@ -0,0 +1,66 @@
+# Concept: Blast Radius
+
+> The set of files affected by changing a given file, computed transitively over the import graph.
+
+## The intuition
+
+Open `src/lib/db.ts`. Other files `import` from it. Those files have other files that import *them*. And so on. Anything reachable by following reverse-import edges is in the **blast radius** of `db.ts`.
+
+```
+src/lib/db.ts
+   ↑
+src/store/user.ts ← src/api/users.ts
+                  ← src/api/admin.ts
+   ↑
+src/store/order.ts ← src/api/orders.ts
+                   ← src/jobs/billing.ts
+```
+
+If you change `db.ts`, six files might break. That's the blast radius.
+
+## How carto computes it
+
+Two layers:
+
+**1. Direct dependents (1 hop).** The import graph stores every `from_file → to_file` edge. The reverse — *who imports me* — is one SQL query: `SELECT from_file_id FROM imports WHERE to_file_id = ?`.
+
+**2. Transitive dependents (≤5 hops).** From the seed file, BFS over the reverse-import graph. Carto caps at 5 hops because diminishing returns: 99% of real change impact lives in the first 3 hops, hops 4–5 catch the outliers, and beyond that you're paying memory for noise.
+
+The bitmap engine makes this fast. A 1M-edge graph fits in a few MB of Roaring Bitmaps; one transitive query is a chain of `bitmap_OR` operations executed in SIMD at ~1 cycle per 512 bits. On the vscode repo (7,567 files, 13,335 edges) a 5-hop blast-radius query returns in ~3 µs.
+
+## What you do with it
+
+Three places it lands:
+
+- **`carto impact <file>`** prints the radius for a single file
+- **`get_blast_radius(file)`** MCP tool gives the AI the same data
+- **`validate_diff(patch)`** uses blast radius to assign a risk grade to a PR
+
+For the last one, the rule of thumb is:
+
+| Direct dependents | Risk (default thresholds) |
+|------------------:|---------------------------|
+| 0–2               | SAFE                      |
+| 3–20              | LOW                       |
+| 21–50             | MEDIUM                    |
+| 51+               | HIGH                      |
+
+These thresholds are tunable per project via `carto.config.json`. Cross-domain edges (e.g. AUTH importing PAYMENTS) escalate independently — see [`domains.md`](./domains.md).
+
+## What it isn't
+
+- **Not a behavioral analysis.** Blast radius doesn't tell you which dependents will actually break, just which ones *might*. The AI uses this as a pre-filter, not as a verdict.
+- **Not call-graph reachability.** It's import-graph reachability. If A imports B but never calls anything from it (dead import), B is still in A's blast radius. We don't try to model dynamic dispatch or runtime imports.
+- **Not a refactoring oracle.** A 50-dependent file isn't automatically bad. Some files (utility modules, type definitions) *should* be widely depended on. Blast radius is a signal, not a sentence.
+
+## Why the bitmap version matters
+
+The original SQLite-only implementation worked fine to ~10K files but slowed down rapidly past that — each transitive query is `O(hops × dependents × indexed-lookup)` which adds up. Bitmap queries are `O(hops × bitmap-width)` regardless of how many dependents each file has. On 1M-file synthetic graphs the bitmap path returns in microseconds where SQLite takes seconds.
+
+See [`docs/scale.md`](../scale.md) for the per-tool latency table at synthetic scale and on real-world repos.
+
+## Related
+
+- [`get_blast_radius`](./mcp-integration.md#get_blast_radius) MCP tool reference
+- [`simulate_change_impact`](./mcp-integration.md#simulate_change_impact) — union of the blast radius for multiple files
+- [`validate_diff`](./mcp-integration.md#validate_diff) — diff-shaped risk grade built on blast radius

package/docs/concepts/domains.md

@@ -0,0 +1,91 @@
+# Concept: Domains
+
+> Auto-detected clusters of tightly-coupled files. Carto's "AUTH", "PAYMENTS", "DATABASE" — without you writing a config.
+
+## The intuition
+
+Files that import each other heavily belong together. Files that don't, don't. Cluster the import graph and you get a set of communities — those communities are the codebase's *domains*.
+
+Carto runs **Leiden+CPM** (Constant Potts Model) on the import graph. It's the same family of community-detection algorithms used in social-network analysis. The output: each file gets a domain id; the bitmap engine indexes by it; everything downstream (cross-domain checks, the impact report, the validation API) reads off this.
+
+## Why not just regex on paths?
+
+Path-based detection works for greenfield projects with a clean `src/auth/`, `src/payments/` layout. It collapses on:
+
+- Monorepos where every package has its own `auth/` subdir
+- Legacy projects where the directory structure doesn't match the actual coupling (auth code mysteriously lives in `lib/middleware/`)
+- Frameworks that hide the structure (Next.js routes spread across `pages/`, `app/`, `api/`)
+
+Graph clustering is path-agnostic. It looks at who imports whom and produces named communities whose names are derived from the path tokens *most common in that cluster*. That's the magic — the cluster is found by structure, the *name* is found by frequency on the actual file paths in it.
+
+## Naming heuristics
+
+After clustering, Carto picks a name for each cluster:
+
+1. Tokenize each file path: `src/auth/login.ts` → `[src, auth, login]`
+2. Drop stopwords (`src`, `lib`, `app`, `index`, `utils`, `helpers`)
+3. Cross-reference with a small built-in dictionary of well-known domain hints: `AUTH`, `PAYMENTS`, `DATABASE`, `NOTIFICATIONS`, `EVENTS`, `TRPC`, `CORE`
+4. Most-frequent matching token wins. Ties broken by dictionary priority (security-relevant domains first).
+5. If no token matches the dictionary, the most-common path token becomes the domain name (uppercased).
+
+The result: real repos light up with sensible labels — vscode gets `EXTENSIONS`, `EVENTS`, `DATABASE`, `CLI`, `CORE`; zed (Rust) gets `DATABASE`, `AUTH`, `EVENTS`, `CORE`. A game engine would get `RENDERER`, `PHYSICS`, `AUDIO` automatically because those tokens dominate the path namespace.
+
+## Adaptive gamma
+
+The Leiden+CPM algorithm has a resolution parameter γ (gamma). High γ → many small clusters. Low γ → few big clusters. Carto picks γ based on repo size:
+
+- **<100 files:** keyword-only fallback (graph clustering over-fragments tiny repos)
+- **100–1,000 files:** γ = 0.04
+- **1,000–10,000 files:** γ scales linearly to 0.02
+- **>10,000 files:** γ = 0.015 (large repos have dense graphs; tighter resolution prevents one giant component)
+
+These constants come from validation on 12 real repos. See `src/store/sync.js` for the exact formula.
+
+## Custom domains via `carto.config.json`
+
+Override the auto-detection if your repo needs it. Two shapes:
+
+**Simple — keyword hints:**
+
+```json
+{
+  "domains": {
+    "EDITOR": ["editor", "monaco", "text"],
+    "WORKBENCH": ["workbench", "layout", "panel"]
+  }
+}
+```
+
+Files whose path tokens match the hints get pulled into the named domain even if the graph clusterer would have put them elsewhere.
+
+**Full — keywords + anchors:**
+
+```json
+{
+  "domains": {
+    "AUTH": {
+      "keywords": ["auth", "login", "session"],
+      "anchor": ["src/auth/session.ts", "src/auth/middleware.ts"]
+    }
+  }
+}
+```
+
+Anchor files are *pinned*. They always end up in their named domain regardless of clustering. Useful when you've got a deliberately central auth file that the graph clusterer would otherwise lump into CORE.
+
+## Stability across syncs
+
+Re-clustering after a code change can shuffle domain assignments. Carto tracks the previous mapping and warns when >5% of files change domain between syncs (`carto check` surfaces it as "unstable clustering"). Anchor files give you a way to force stability where it matters.
+
+## Where domains show up
+
+- **`AGENTS.md`** lists them with file counts
+- **`.carto/context/<DOMAIN>.md`** has per-domain context the AI reads when working in that area
+- **`get_domain(name)`** MCP tool returns the full list of files, routes, models in a domain
+- **`validate_diff`** uses cross-domain edges as a violation signal — adding `auth/login.ts → payments/billing.ts` is HIGH-risk because it crosses a sensitive boundary
+
+## Related
+
+- [`get_cross_domain`](./mcp-integration.md#get_cross_domain) — every import edge that crosses a domain
+- [`carto check`](../../README.md#cli-commands) — flags new cross-domain violations
+- [Leiden algorithm paper](https://www.nature.com/articles/s41598-019-41695-z) — the algorithm Carto uses

package/docs/concepts/import-graph.md

@@ -0,0 +1,102 @@
+# Concept: Import Graph
+
+> The foundation. Every other Carto feature is computed from this one structure.
+
+## What's in it
+
+For each source file Carto parses, it records:
+
+| Source field | Meaning |
+|--------------|---------|
+| `id`         | Stable integer (monotonic per project) |
+| `path`       | Project-relative, forward-slash-normalized |
+| `language`   | `javascript`, `typescript`, `python`, `go`, `rust`, `java`, `cpp`, `csharp`, `ruby`, `r`, `prisma` |
+| `hash`       | SHA-256 of content (mtime+size cache uses this) |
+| `is_entry_point` | True for top-level CLIs, `main.*` files, Next.js page entries |
+
+And for each import the parser finds:
+
+| Edge field | Meaning |
+|------------|---------|
+| `from_file_id` | The importer |
+| `to_file_id`   | The importee (null if unresolved — e.g. a bare module name like `express`) |
+| `to_path`      | The raw import specifier |
+| `resolved`     | Boolean — did we successfully find the target in the index? |
+
+## What parser does what
+
+Two-layer extraction:
+
+**1. Tree-sitter** (per-language plugin in `src/extractors/languages/`). Parses the file into a syntax tree, walks the tree, pulls out:
+
+- import statements (`import x from`, `from x import`, `use crate::x`, `using A.B;`, `require 'x'`, `#include "x"`)
+- exported symbols
+- type definitions (interfaces, classes, structs)
+
+For supported grammars, this is ~0.05–0.2 ms/file.
+
+**2. Babel deep-parse** (TypeScript/JavaScript only, opt-in for route+model files). Used when the framework-specific extractor needs more than tree-sitter can give — e.g. tRPC procedures, React Router routes, Zod schemas, Prisma models. Slower (~5–20 ms/file) but reserved for the small subset of files where it matters.
+
+## Import resolution
+
+Local imports (`./foo`, `../utils`) are resolved relative to the importing file's directory, then tried against the index:
+
+```
+./foo                  → src/lib/foo.ts ?
+                       → src/lib/foo.js ?
+                       → src/lib/foo/index.ts ?
+                       → src/lib/foo/index.js ?
+```
+
+The first hit wins. TypeScript `paths` aliases (`@/components/Button`) are read from `tsconfig.json` and applied before the relative search — so `@/components/Button` resolves to `src/components/Button.tsx` if that's what the alias maps to.
+
+Bare module names (`express`, `react`, `lodash`) are *intentionally* not resolved. They're external; Carto's job is to know the *internal* structure.
+
+## How it's stored
+
+SQLite tables `files` + `imports`. One row per file, one row per edge. Indexes on `(from_file_id)`, `(to_file_id)`, `(path)`.
+
+Plus a derived bitmap layer in `.carto/bitmap.bin`:
+
+- `forward[i]` = bitmap of files that file `i` imports (1-hop)
+- `reverse[i]` = bitmap of files that import file `i` (1-hop)
+- `popcountIndex` = files sorted by transitive 5-hop dependent count, desc
+
+The bitmap layer is the read path. The SQLite tables are the write path + source of truth. The bitmap is rebuilt from SQLite on first sync after upgrade.
+
+## Path-alias support
+
+Carto reads `paths` from:
+
+- `tsconfig.json` → alias resolution for `.ts/.tsx`
+- `jsconfig.json` → alias resolution for `.js/.jsx`
+
+It does *not* currently read:
+
+- `webpack.config.js` `resolve.alias` (too many variants — convert to tsconfig if you need it indexed)
+- `vite.config.{js,ts}` `resolve.alias` (same)
+- `next.config.{js,mjs}` `experimental.transpilePackages` (only affects bundling, not module resolution)
+
+If you have a path alias that's not being resolved, declare it in `tsconfig.json#paths` even if you don't use TypeScript. Carto reads it; your runtime ignores it.
+
+## Edge cases we handle
+
+- **Type-only imports** (`import type { X }`) — counted as edges. They're real dependencies; if the type changes, the importer needs to update.
+- **Dynamic imports** (`import('./foo')`) — captured when the path argument is a string literal. Computed values are not resolved (no symbolic execution).
+- **Conditional imports** (inside `if (process.env.X)`) — captured statically; we don't try to evaluate the condition.
+- **Barrel re-exports** (`export * from './foo'`) — captured as edges, but the barrel itself doesn't get flagged as a "consumer" (it's just a pass-through).
+- **CommonJS `require()`** — captured for `.js/.cjs` files.
+- **Python `from .x import y`** — relative imports resolved against the package layout. Was a bug pre-2.0.7; fixed in Spec 7.
+
+## Edge cases we don't handle
+
+- **Monkey-patching / runtime mutation** — no.
+- **Reflection-based loading** (Python `importlib`, Java `Class.forName`) — no.
+- **Cross-language imports** (TS frontend HTTP-calling a Python backend route) — handled by route extraction, not the import graph. See [`get_change_plan`](./mcp-integration.md#get_change_plan).
+
+## What you'd want to look at
+
+- `carto inspect` — shows file count, edge count, schema version
+- `get_neighbors(file, hops)` MCP tool — exact 1- or 2-hop import neighbors of a single file
+- `get_high_impact_files(n)` MCP tool — top-N by transitive dependent count
+- `.carto/anci.bin` — the binary serialization of the whole graph; consumable by any AI tool via the `loadAnci()` library

package/docs/concepts/mcp-integration.md

@@ -0,0 +1,148 @@
+# Concept: MCP Integration
+
+> The protocol layer that makes Carto's index visible to your AI tool.
+
+## What MCP is
+
+The [Model Context Protocol](https://modelcontextprotocol.io) is an open protocol Anthropic introduced in late 2024 for connecting LLMs to external tools and data. An MCP **server** exposes tools and resources; an MCP **client** (Cursor, Claude Desktop, Kiro, Claude Code, Cline, Continue, Windsurf, Zed) calls them on behalf of the model.
+
+Carto runs an MCP server in stdio mode. You start it with `carto serve`, but you almost never do that by hand — your AI tool spawns it.
+
+## What `carto init` writes
+
+For each AI tool it detects on your machine, init writes the appropriate MCP config:
+
+| Tool | Config file | Format |
+|------|-------------|--------|
+| Cursor          | `~/.cursor/mcp.json`                                      | `{ mcpServers: { carto: ... } }` |
+| Claude Code     | `<project>/.mcp.json`                                     | same |
+| Claude Desktop  | `~/Library/Application Support/Claude/claude_desktop_config.json` | same (cross-platform paths in README) |
+| Kiro            | `~/.kiro/settings/mcp.json`                               | same |
+| Codex CLI       | `~/.codex/config.toml`                                    | `[mcp_servers.carto]` |
+| VS Code Copilot | `<project>/.vscode/mcp.json`                              | `{ servers: { carto: { type: "stdio", ... } } }` |
+| Windsurf        | `~/.codeium/windsurf/mcp_config.json`                     | `{ mcpServers: { carto: ... } }` |
+
+Each config tells the tool: *"when the user starts a chat, run `carto serve` as a child process and route MCP traffic to it"*.
+
+## The ~76 tools Carto exposes
+
+Grouped by what they answer. Categories below match the [`docs/api/`](../api/) layout — that directory is the full per-tool reference (auto-generated from `src/mcp/server.js`). The picks below are the high-impact ones; your AI tool picks whichever one fits the question mid-task.
+
+### Core graph (16) — project shape, blast radius, change planning
+
+- **`get_architecture()`** — 500-word overview. The right *first* call for any new task.
+- **`get_blast_radius(file)`** — every file affected by changing this one, with hop distance.
+- **`get_change_plan(intent)`** — natural-language intent → files to touch, affected domains, similar patterns.
+- **`simulate_change_impact(files)`** — union of the blast radius for *multiple* files at once. The bitmap engine is what makes this feasible at scale.
+- **`get_high_impact_files(n)`** — top N files by transitive dependents.
+- **`get_cross_domain()`** — every import edge that crosses a domain boundary.
+
+Plus `get_structure`, `get_context`, `get_neighbors`, `get_domain`, `get_domains_list`, `get_routes`, `search_routes`, `get_models`, `get_env_vars`, `get_file_summary`, `get_similar_patterns`.
+
+### Episodic memory (5) — what your AI decided last week
+
+- **`validate_diff(diff)`** — given a unified diff: violations, blast radius, risk grade, suggestions. Sub-15ms p99. **Every call writes a row to the decision log** — the rest of this category reads from it.
+- **`did_we_discuss_this(topic)`** — substring search over the decision log. Six-week recall, conversational.
+- **`get_recent_decisions(time_range, kind?)`**, **`get_session_context(session_id?)`**, **`get_intervention_history(file?)`** — the underlying log surfaced different ways.
+
+### Temporal (9) — how the architecture changed over time
+
+- **`get_architectural_drift()`** — per-domain growth/shrink + event count over a window.
+- **`get_hotspot_files()`** — top files by churn × blast_radius (the CodeHealth heuristic).
+- **`get_domain_evolution(domain)`** — time-series of one domain's file count by snapshot.
+
+Plus `get_arch_events`, `get_temporal_context`, `get_change_velocity`, `get_complexity_trend`, `get_churn_vs_blast_radius`, `get_domain_health`.
+
+### Brain (10) — invariants, conventions, action patterns
+
+Carto's "rules of the codebase" — mined from the import graph and git history, not written by hand.
+
+- **`get_invariants(domain?, threshold?)`** — confidence-scored architectural rules: *"AUTH never imports from PAYMENTS"*.
+- **`get_conventions(file?)`** — naming, export, and directory conventions that apply to a given location.
+- **`get_action_patterns(intent?)`** — *"when developers add X, they also touch Y"* — procedural patterns from git history.
+- **`scaffold_for_intent(intent)`** — anchor file + co-changed files + canonical pattern + conventions.
+
+Plus `get_canonical_pattern`, `get_working_memory`, `get_active_suggestions`, `get_pending_decisions`, `get_active_drift`, `dismiss_suggestion`.
+
+### Predictive (7) — P(file causes the next bug)
+
+- **`get_predictive_risk(file?)`** — 0–1 score per file combining blast radius, churn, cross-domain coupling, prior interventions, and test coverage.
+- **`get_safety_checklist(file)`** — per-file pre-edit safety summary.
+- **`validate_change(file, content)`** — pre-write governance: diffs `content` vs disk then runs `validate_diff`.
+- **`get_drift_digest(time_range)`** — weekly architectural digest in CLI-renderable markdown.
+
+Plus `get_microservice_cut_points`, `get_file_ownership`, `get_cross_team_coupling`, `get_ai_cost_attribution`.
+
+### AI-native retrieval (14) — context that fits the budget
+
+- **`get_minimal_context_for_intent(intent, budget_tokens)`** — token-budgeted hybrid retrieval (structural + lexical + semantic, fused with RRF, boosted by same-domain and recent-churn). Usually returns 6–12 files instead of the usual 40+.
+- **`get_progressive_disclosure_tree()`** — domain → top files → exports, structured for an LLM to drill into.
+- **`get_token_budget_report(intent, budget)`** — diagnostic complement: which files would be picked and at what cost.
+
+Plus `get_data_flow`, `get_interface_contract`, `get_dependency_surface`, `get_upgrade_risk`, `get_test_coverage_map`, `get_stale_docs`, `get_decision_log`, `get_evolution_delta`, `get_change_velocity`, `explain_change_in_natural_language`.
+
+### Adjacent (8) — runtime, IaC, cross-language, dead code
+
+- **`get_cross_language_call_graph()`** — match frontend `fetch()` to backend route handlers across language boundaries.
+- **`get_iac_resources()`** — Terraform / Helm / Pulumi / CDK resources discovered in the repo.
+- **`ingest_otlp_traces(path)`** + **`get_risk_weighted_blast_radius(otlp?)`** — combine static dependents with runtime call counts.
+- **`get_dead_code_with_confidence(otlp?)`** — zero static dependents AND zero runtime hits → the safe-to-delete list.
+- **`get_semantic_diff(diff)`** — rename + symbol-relocation detection beyond line-level.
+
+Plus `get_hot_in_prod_no_tests`, `get_llm_enrichment`.
+
+### Org / multi-repo (7) — service graphs across repos
+
+- **`get_org_architecture()`** — org-wide summary across registered repos.
+- **`get_cross_repo_blast_radius(repo)`** — *"if I break repo X, who notices?"*
+- **`find_consumers_of_api(target)`** — every file importing a given npm/pypi/go/maven package across the org.
+- **`get_service_dependency_graph()`**, **`get_service_boundary_violations()`** — service-shape views.
+
+Plus `get_org_domain_mapping`, `get_microservices_migration_cut_points`.
+
+> Full per-tool API reference at [`docs/api/`](../api/). You don't memorize these — your AI picks the right one mid-task.
+
+## How the AI knows when to call which tool
+
+The model reads the tool descriptions Carto provides in the `tools/list` response. Each description is one sentence written so the model has enough context to choose. Examples:
+
+> *"Get a 500-word project overview: domains, entry points, stack, key patterns. **Use this first.**"*
+
+> *"Given a unified diff: violations (cross-domain imports, high-blast files), blast radius per file, risk level (SAFE/LOW/MEDIUM/HIGH), suggestions. Each call is recorded in the episodic memory log so other tools can ask 'did we discuss this?'. Sub-15ms p99."*
+
+The "Use this first" hint matters. The model orients itself with `get_architecture()`, then narrows to specific tools based on what the user asked.
+
+## Lazy re-parse on stale files
+
+When the model asks about `src/lib/db.ts` and you've edited it since the last `carto sync`, the MCP server stats the file, sees the mtime is newer than the DB row, and re-parses it inline (~50 ms). The model gets a fresh answer; you didn't think about freshness at all.
+
+That's why Carto doesn't need a daemon. Git hooks handle the "I just committed" case; lazy re-parse handles the "I edited but didn't commit yet" case. Together they cover ~100% of real usage.
+
+## Wiring it manually
+
+If `carto init` didn't detect your AI tool, the README's [Manual MCP wiring](../../README.md) section (collapsed `<details>` block right after the install snippet) has copy-paste snippets for every supported client. The shape is always:
+
+```json
+{
+  "mcpServers": {
+    "carto": {
+      "command": "carto",
+      "args": ["serve"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+Restart the tool, and it'll show carto in its MCP server list.
+
+## Debugging
+
+- `carto doctor` runs a sanity check on Node version, native modules, the index, git hooks, and the *presence* of MCP config files (it doesn't validate their content — that varies per tool).
+- Set `CARTO_DEBUG=1` before launching your AI tool to make the MCP server log every tool call to stderr.
+- Read [`troubleshooting.md`](../troubleshooting.md) for known gotchas.
+
+## Related
+
+- [Model Context Protocol spec](https://modelcontextprotocol.io)
+- [`anci.md`](./anci.md) — the file-format Carto exports for tools that prefer reading a static file over speaking MCP

package/docs/guides/adding-feature-safely.md

@@ -0,0 +1,101 @@
+# Guide: Adding a feature safely
+
+> The workflow Carto makes possible. Add a feature without breaking five other files you didn't know existed.
+
+## The before-Carto pattern
+
+You're asked to *"add rate limiting to /api/users"*. You ask Cursor. Cursor:
+
+1. Greps for `users` — finds 47 matches across 12 files
+2. Picks the first one that looks like a route handler
+3. Adds rate-limiting middleware to it
+4. Confidently announces success
+
+What got missed:
+
+- The middleware was already declared in `src/auth/middleware.ts` — now you have two copies
+- The route handler is one of three for `/api/users` (GET, POST, PATCH) — the AI updated GET only
+- Three callers in tests still pass requests through the un-rate-limited path
+
+You merge it. CI passes (tests didn't cover the new middleware). It ships. The next time someone hits POST /api/users from production they're not rate-limited and the AbusePrevention engineer wakes up at 2 AM.
+
+## The with-Carto pattern
+
+Same task. Open your AI tool — which is now wired to carto MCP — and ask the same question.
+
+The AI calls `get_change_plan("add rate limiting to /api/users")`. Carto's response:
+
+```
+## Plan: add rate limiting to /api/users
+
+### Relevant routes
+- POST /api/users   src/api/users.ts:42   (no rate limit)
+- GET  /api/users   src/api/users.ts:18   (no rate limit)
+- PATCH /api/users  src/api/users.ts:67   (no rate limit)
+
+### Files to touch
+- src/api/users.ts        — primary (modify 3 route handlers)
+- src/auth/middleware.ts  — rate-limit middleware already exists here, reuse it
+
+### Similar patterns
+- src/api/posts.ts        — already uses rateLimit() middleware (12 callers)
+- src/api/billing.ts      — already uses rateLimit() middleware (4 callers)
+
+### Blast radius
+- src/api/users.ts has 8 direct dependents
+- src/auth/middleware.ts has 23 transitive dependents — changes here
+  ripple wide; do not modify the middleware signature
+
+### Cross-domain check
+- No new cross-domain edges introduced by reusing existing middleware
+```
+
+The AI now has every fact it needs. It writes the change correctly the first time.
+
+## The literal step-by-step
+
+```bash
+# 1. Ask carto first
+carto explain "add rate limiting to /api/users"
+# (or do this implicitly via your AI tool — same call under the hood)
+
+# 2. Read the existing pattern
+carto why src/api/posts.ts        # see how rate limiting is already used
+
+# 3. Make the change in your AI tool
+#    (the AI references the plan from step 1)
+
+# 4. Before committing, validate
+git diff | carto validate --fail-on HIGH
+# Exits 2 if the diff would be HIGH-risk → blocks the commit
+
+# 5. Final check
+carto diff
+# Markdown impact report against HEAD
+```
+
+If you're using the [GitHub Action](./ci-integration.md), step 4 happens automatically on the PR. The local `carto validate` step is for catching issues earlier.
+
+## What "safely" actually means
+
+Three signals Carto surfaces that you wouldn't see otherwise:
+
+1. **The right files.** `get_change_plan` ranks files by relevance to intent (IDF token scoring + route anchoring + graph expansion). The model's hit rate jumps from "pick the most plausible from 47 grep hits" to "use the 2–3 files Carto identified".
+
+2. **Existing patterns.** `get_similar_patterns` finds files that already solve the same shape of problem in your codebase. The model copies your conventions instead of inventing new ones.
+
+3. **The boundary it's about to cross.** If reusing the middleware works, no new cross-domain edge. If the AI tries to import auth utilities into the payments domain, `validate_diff` catches it before save.
+
+## When to override
+
+Carto's heuristics are statistical. Sometimes the right answer involves crossing a domain boundary, or modifying a high-blast-radius file. Don't refuse — *acknowledge*.
+
+The MCP `did_we_discuss_this("auth-to-payments coupling")` tool lets the AI check whether the decision has already been made. If yes, it proceeds with cited context. If no, it asks you, then records the decision so future sessions don't re-litigate.
+
+This is the episodic-memory layer in action: not a gate, but a continuity.
+
+## Related
+
+- [`docs/concepts/blast-radius.md`](../concepts/blast-radius.md)
+- [`docs/concepts/domains.md`](../concepts/domains.md) (the cross-domain check)
+- [`docs/guides/pre-merge-review.md`](./pre-merge-review.md) (the CI-gated version)