carto-md 2.0.8 → 2.1.0

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)

package/docs/guides/ci-integration.md

@@ -0,0 +1,175 @@
+# Guide: CI integration
+
+> Where carto fits into your CI pipeline, beyond the GitHub Action.
+
+## The default — GitHub Action
+
+[`docs/guides/pre-merge-review.md`](./pre-merge-review.md) covers the canonical case: drop the Action onto every PR, get sticky-comment impact reports automatically.
+
+This guide is for the cases where the Action isn't the right fit: GitLab, Bitbucket, custom CI, pre-commit, monorepo-specific gates.
+
+## GitLab CI
+
+```yaml
+# .gitlab-ci.yml
+carto-impact:
+  stage: test
+  image: node:20
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  cache:
+    key: carto-${CI_COMMIT_REF_SLUG}
+    paths:
+      - .carto/
+  script:
+    - npm install -g carto-md
+    - test -d .carto || carto init
+    - carto sync
+    - carto pr-impact --base origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --head HEAD --format markdown > impact.md
+    - cat impact.md
+  artifacts:
+    paths: [impact.md]
+```
+
+Posting to the merge-request as a comment requires `glab`:
+
+```yaml
+    - glab mr note ${CI_MERGE_REQUEST_IID} -F impact.md
+```
+
+## Bitbucket Pipelines
+
+```yaml
+# bitbucket-pipelines.yml
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          name: Carto Impact
+          image: node:20
+          script:
+            - npm install -g carto-md
+            - carto init || carto sync
+            - carto pr-impact --base $BITBUCKET_PR_DESTINATION_BRANCH --head HEAD --fail-on HIGH
+```
+
+## CircleCI
+
+```yaml
+# .circleci/config.yml
+version: 2.1
+jobs:
+  carto-impact:
+    docker:
+      - image: cimg/node:20.10
+    steps:
+      - checkout
+      - restore_cache:
+          keys: [carto-{{ .Branch }}, carto-]
+      - run: npm install -g carto-md
+      - run: test -d .carto || carto init
+      - run: carto sync
+      - run: carto pr-impact --base origin/main --head HEAD --format markdown
+      - save_cache:
+          key: carto-{{ .Branch }}
+          paths: [.carto/]
+```
+
+## Custom CI / shell script
+
+The whole thing is just three commands. Drop them into whatever runner you use:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+npm install -g carto-md
+
+if [ ! -d .carto ]; then
+  carto init
+else
+  carto sync
+fi
+
+carto pr-impact \
+  --base "${BASE_REF:-origin/main}" \
+  --head HEAD \
+  --format markdown \
+  --fail-on HIGH
+```
+
+Exit codes:
+
+- 0 — comment rendered, risk below threshold
+- 1 — misuse / index missing / git failure
+- 2 — `--fail-on` threshold tripped
+
+## Pre-commit hook
+
+For "fail fast" before pushing. Add to `.git/hooks/pre-commit`:
+
+```bash
+#!/bin/sh
+git diff --cached | carto validate --fail-on HIGH
+```
+
+Now a `git commit` that would produce a HIGH-risk change exits 2 and the commit is blocked. The dev sees the violation reasons in the same terminal.
+
+Note: `carto init`'s installed pre-commit hook calls `carto sync`, not `carto validate`. If you want both, prepend the validate line:
+
+```bash
+#!/bin/sh
+# Spec 22: validate the staged diff first
+git diff --cached | carto validate --fail-on HIGH || exit 2
+
+# carto-md: keep index fresh on git events
+carto sync >/dev/null 2>&1 || true
+```
+
+## Caching tips
+
+Re-running `carto init` from scratch is fast but not free (~10 seconds for a medium repo). On CI, cache `.carto/`:
+
+```yaml
+# GitHub Actions
+- uses: actions/cache@v4
+  with:
+    path: .carto/
+    key: carto-${{ hashFiles('**/*.ts', '**/*.js', '**/*.py', '**/*.go') }}
+    restore-keys: carto-
+```
+
+The cache key hashes source files — any change invalidates the cache, but the source-file hash *captures* what changed, so reuse is high across PRs.
+
+After cache restore, run `carto sync` (not `init`). Sync is incremental — mtime+size cached, only changed files re-parsed.
+
+## Slack notifications (drift digest)
+
+Not built in yet — but easy to wire from CI. Run `carto check --json` on a weekly cron, post the cross-domain section to Slack:
+
+```bash
+carto check --json | jq '.crossDomain | length' \
+  | xargs -I {} curl -X POST -H 'Content-Type: application/json' \
+      --data "{\"text\": \"This week: {} cross-domain edges in repo X\"}" \
+      $SLACK_WEBHOOK_URL
+```
+
+## Don't gate everything
+
+A few patterns we've learned not to recommend:
+
+- **Gating *every* PR on `--fail-on LOW`** — too noisy. LOW is just "a file changed" — every PR trips it.
+- **Running carto on `push` events** — wastes runner minutes; the impact report is only useful in PR context where there's a base branch to diff against.
+- **Running on docs-only changes** — `path-filters` in your workflow to skip MD-only PRs saves minutes:
+
+```yaml
+on:
+  pull_request:
+    paths-ignore: ['**/*.md', 'docs/**']
+```
+
+## Related
+
+- [`docs/guides/pre-merge-review.md`](./pre-merge-review.md) — the canonical GitHub Action setup
+- [`docs/guides/monorepo-setup.md`](./monorepo-setup.md) — caching considerations for large repos
+- [`docs/troubleshooting.md`](../troubleshooting.md) — what to do when CI fails

package/docs/guides/monorepo-setup.md

@@ -0,0 +1,121 @@
+# Guide: Monorepo setup
+
+> The realities of indexing a 30K-file monorepo with carto. Knobs, gotchas, expected sizes.
+
+## The default behavior
+
+`carto init` at the monorepo root indexes *everything*. No file cap. SQLite handles the volume; the bitmap engine handles the queries.
+
+Real numbers from the corpus runs (see [`docs/scale.md`](../scale.md)):
+
+| Repo | Indexed files | First run | Re-sync (no changes) | DB size |
+|------|--------------:|----------:|---------------------:|--------:|
+| prisma     |  961 | 1.0s  | 350ms | 1.1 MB |
+| zed        | 1,752 | 2.9s  | 468ms | 4.8 MB |
+| supabase   | 6,330 | 5.4s  | 1.2s  | 4.8 MB |
+| vscode     | 7,567 | 8.0s  | 935ms | 14.3 MB |
+
+For a 30–50K-file monorepo, expect ~30–50s first run, ~3–5s incremental. Beyond 100K files Carto prints an ETA and runs in 1–2 minutes.
+
+## What gets excluded by default
+
+`carto init` writes a `.cartoignore` if one doesn't exist. Defaults exclude:
+
+- `node_modules/`, `vendor/`, `dist/`, `build/`, `target/`, `out/`
+- `.git/`, `.svn/`, `.hg/`
+- Test files matching common conventions:
+  - `*.test.*`, `*.spec.*`, `*.stories.*` (JS/TS)
+  - `test_*.py`, `*_test.py` (Python)
+  - `test_*`, `*_test.r` (R)
+  - Subdirs named `test/`, `tests/`, `__tests__/`, `spec/`
+- Secrets / credentials: `.env*`, `*secret*`, `*credential*`, `*private_key*`, `*.pem`, `*.key`, SSH keys, AWS/GCP creds, kubeconfig, token files
+- Binaries: images, media, archives
+- Cache directories
+
+If your monorepo has unusual layout (a separately-managed `vendor/` you do want indexed, e.g.), edit `.cartoignore` to allow it back in.
+
+## Submodules
+
+If `.gitmodules` is present, `carto init` warns:
+
+```
+[CARTO] Detected 3 git submodules. Add their paths to .cartoignore
+        if you don't want them indexed.
+```
+
+Default behavior: submodule directories *are* descended into. If your submodules are external/vendored packages, you almost certainly want them excluded — add their paths to `.cartoignore`.
+
+## Per-workspace domain hints
+
+Monorepos with `packages/auth/`, `packages/payments/`, `packages/db/` produce good auto-detected domains because the path tokens line up with what the Leiden+CPM clusterer finds in the graph.
+
+If you have a flatter layout (`apps/web/src/{auth,payments,db}/`), use `carto.config.json` to pin domains:
+
+```json
+{
+  "domains": {
+    "AUTH": {
+      "keywords": ["auth", "login", "session"],
+      "anchor": ["apps/web/src/auth/session.ts"]
+    },
+    "PAYMENTS": {
+      "keywords": ["payment", "billing", "checkout"],
+      "anchor": ["apps/web/src/payments/charge.ts"]
+    }
+  }
+}
+```
+
+The `anchor` files force those paths into the named domain regardless of clustering. See [`domains.md`](../concepts/domains.md).
+
+## TypeScript path aliases
+
+Carto reads `tsconfig.json#paths` and `jsconfig.json#paths` for import resolution. In a monorepo with workspace references (e.g. `tsconfig.json#references`), each workspace's `tsconfig.json` is read independently. The aliases declared in `apps/web/tsconfig.json` apply when resolving imports *inside* `apps/web/`, etc.
+
+If you use TypeScript project references with `"composite": true`, this just works. If you use a monorepo tool that bypasses tsconfig (some Nx setups), declare the equivalent paths in a top-level `tsconfig.json` for Carto's benefit even if the build doesn't use them.
+
+## Cross-package imports
+
+When `@company/auth` is published locally (npm workspaces, pnpm workspaces, yarn workspaces), imports of `@company/auth` resolve via the workspace symlink — which Carto follows. So `import { sessionFor } from '@company/auth'` from `apps/web/src/api/users.ts` correctly resolves to `packages/auth/src/index.ts`, and the edge ends up in the graph.
+
+What this enables:
+
+- `get_blast_radius('packages/auth/src/session.ts')` returns dependents across *every* workspace
+- Cross-domain checks fire on workspace-to-workspace edges
+- The `simulate_change_impact` MCP tool correctly unions blast radius across packages
+
+## Excluding individual workspaces
+
+`carto.config.json` can pin which directories to index:
+
+```json
+{
+  "include": ["apps/", "packages/"],
+  "exclude": ["packages/legacy-thing/"]
+}
+```
+
+`include` is rare — `.cartoignore` is usually the right tool. `exclude` is the common case for "we don't index this old workspace anymore".
+
+## Scoped indexing (>100K files)
+
+For *very* large monorepos (Google-scale, ~1M files), the full index gets unwieldy. The roadmap has a `--scope=packages/changed/**` flag that only indexes affected workspaces; that hasn't shipped yet. If you hit this scale, file an issue — the gating decision is "real users at this scale" rather than premature.
+
+In the meantime, the working knob is `.cartoignore`. Exclude packages you don't change, accept a partial graph, get a usable index.
+
+## Performance expectations
+
+| Files | First run | Re-sync | DB | Bitmap | RSS |
+|------:|----------:|--------:|---:|-------:|----:|
+| 1K    | 1s        | 350ms   | 1 MB | 100 KB | 60 MB |
+| 10K   | 8s        | 1s      | 14 MB | 1.2 MB | 220 MB |
+| 50K   | 50s       | 4s      | 80 MB | 8 MB | 600 MB |
+| 100K  | ~100s     | ~10s    | 160 MB | 20 MB | 1.1 GB |
+
+These are from the synthetic stress harness (`bench/scale-test/`). Real repos vary depending on edge density, but the shape is the same.
+
+## Related
+
+- [`docs/concepts/domains.md`](../concepts/domains.md) — adaptive gamma + custom hints
+- [`docs/concepts/import-graph.md`](../concepts/import-graph.md) — alias resolution details
+- [`docs/scale.md`](../scale.md) — full benchmark table

package/docs/guides/onboarding-new-engineer.md

@@ -0,0 +1,121 @@
+# Guide: Onboarding a new engineer
+
+> Day 1, hour 1, productive. Without 47 Slack DMs to teammates.
+
+## The cold start
+
+New engineer joins. The repo has 50K lines, three years of history, no architecture docs. The standard onboarding pattern is:
+
+- Day 1–3: Set up tooling. Read README. Get the app running locally.
+- Day 4–10: Get assigned a "starter ticket" — a tiny bug fix in a dark corner. Realize you have no idea where to begin.
+- Day 11–20: Slack DMs. *"Where does session validation live?"* *"What does this file do?"* *"Is this safe to change?"*
+- Day 21+: Maybe starting to feel productive.
+
+That's 3 weeks × $5K/week = $15K of ramp time per hire. Most of it is the new engineer trying to build the mental model of the codebase that everyone else already has.
+
+## What Carto does instead
+
+`carto init` produces three things the new engineer can read on day 1:
+
+1. **`AGENTS.md`** at the project root. Plain markdown. Architecture overview, domain list with file counts, top high-impact files. Skim in 5 minutes.
+
+2. **`.carto/context/<DOMAIN>.md`** for each detected domain. Per-domain context: entry points, key files, common patterns. Read just the ones relevant to your starter ticket.
+
+3. **A live MCP server** their AI tool (Cursor/Claude/Kiro/etc.) is already wired to. Every question the new engineer would have asked in Slack — "where does session validation live?", "what does this file do?", "what's the blast radius of this change?" — is one MCP call away.
+
+## A literal day-1 walk-through
+
+```bash
+# new engineer just cloned the repo
+git clone …
+cd …
+
+# carto is probably already installed; if not:
+npm install -g carto-md
+
+# first command they run:
+carto init
+```
+
+The init banner gives the mirror moment:
+
+```
+┌─ Carto · indexed ─────────────────────────────────────────
+│  3,847 files · 7 domains · 142 routes · 8,201 import edges
+│
+│  Top domains:
+│    CORE          (1,940 files)
+│    DATABASE      (412 files)
+│    AUTH          (287 files)
+│    PAYMENTS      (235 files)
+│
+│  💡 Highest-risk file: src/lib/db/client.ts
+│     (94 files depend on it — try `carto why src/lib/db/client.ts`)
+└───────────────────────────────────────────────────────────
+```
+
+They now know:
+
+- This repo has ~4K source files (real size, not the inflated package.json claim)
+- It's split into 7 domains they should learn one at a time
+- The single most important file is `src/lib/db/client.ts`
+
+Five minutes in, they've replaced 30 minutes of clicking around.
+
+## What to ask first
+
+Three questions every new engineer should ask their AI tool in the first hour:
+
+1. *"Give me the architectural overview of this project."* → calls `get_architecture()`. 500-word summary.
+
+2. *"What's in the AUTH domain?"* (or whichever they're working on) → calls `get_domain("AUTH")`. Routes, models, key files.
+
+3. *"What does `src/lib/db/client.ts` do and what depends on it?"* → calls `get_file_summary()` + `get_blast_radius()`. Now they know the danger zone.
+
+## When they pick up their first ticket
+
+They start with:
+
+```bash
+carto explain "fix the bug in user signup where email validation is skipped"
+```
+
+This calls `get_change_plan()` — same engine the AI uses. Output:
+
+```
+## Plan: fix bug in user signup where email validation is skipped
+
+### Relevant routes
+- POST /auth/signup   src/auth/signup.ts:42
+
+### Files to touch
+- src/auth/signup.ts        — the route handler (15 direct dependents)
+- src/auth/validators.ts    — email validation lives here
+
+### Similar patterns
+- src/auth/login.ts already validates email format using validateEmail()
+- src/auth/reset-password.ts also uses validateEmail()
+
+### Blast radius
+- src/auth/signup.ts: 15 dependent files. Test coverage in
+  src/auth/__tests__/signup.test.ts — re-run after change.
+```
+
+A new engineer who's never opened `signup.ts` can read this, open the 3 files it names, find the bug, fix it correctly the first time. No Slack DM needed.
+
+## When they break something
+
+Even with Carto, mistakes happen. The two tools that help most:
+
+- **`carto diff`** before committing. Shows the architectural impact of the local change — blast radius, cross-domain violations, files-without-tests. The new engineer self-corrects.
+- **The GitHub Action** ([guide](./ci-integration.md)) catches what the new engineer didn't. The PR gets an impact comment; reviewers spot risky changes before merge.
+
+## The team multiplier
+
+Onboarding is the cost the *team* pays for a hire, not just the hire. Every Slack DM from a new engineer is an interruption to a senior. A 1-week ramp instead of a 3-week ramp doesn't just save the new engineer's time — it saves the senior's too.
+
+## Related
+
+- [`docs/quickstart.md`](../quickstart.md) — install + init
+- [`docs/concepts/domains.md`](../concepts/domains.md) — how domains are named
+- [`docs/guides/adding-feature-safely.md`](./adding-feature-safely.md) — the workflow for the second week onward