carto-md 2.0.9 → 2.1.0

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

package/docs/guides/pre-merge-review.md

@@ -0,0 +1,139 @@
+# Guide: Pre-merge review
+
+> Architecture review at PR time, automatically. The reviewer sees structural impact alongside the diff.
+
+## What the GitHub Action does
+
+On every pull request:
+
+1. Checks out the PR head
+2. Restores `.carto/` from `actions/cache` (or runs `carto init` cold)
+3. Runs `carto pr-impact --base $BASE --head $HEAD --format markdown`
+4. Posts the result as a sticky comment on the PR (one comment per PR, updated in place on every push)
+
+The whole flow runs in 30–120 seconds on a warm cache, 1–3 minutes cold.
+
+## Setup
+
+In `.github/workflows/carto.yml`:
+
+```yaml
+name: Carto Impact Report
+on:
+  pull_request:
+    branches: [main]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  carto:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }       # full history — pr-impact needs the base ref
+      - uses: theanshsonkar/carto@v2.0.9
+```
+
+That's the entire config. The action handles npm install, cache restore, sync, pr-impact, and the comment.
+
+## What the comment looks like
+
+```markdown
+## 🗺️ Carto Impact Report
+
+This PR touches **AUTH** and **DATABASE** domains.
+
+| Metric | Value |
+|--------|-------|
+| Risk | 🔴 HIGH |
+| Blast radius (union) | 47 files |
+| Files changed | 6 |
+| Cross-domain violations introduced | 2 |
+| Files without tests in blast radius | 5 of 31 |
+| High-impact file changed | src/auth/session.ts (8 direct dependents) |
+
+<details>
+<summary>Affected routes (4)</summary>
+
+- POST /auth/login — risk: HIGH
+- GET /auth/me — risk: HIGH
+- POST /auth/register — risk: MEDIUM
+- POST /api/users — risk: LOW
+
+</details>
+
+<details>
+<summary>Cross-domain violations (2)</summary>
+
+- auth/login.ts now imports from payments/billing.ts (AUTH→PAYMENTS)
+- database/user-repo.ts now imports from auth/jwt.ts (DATABASE→AUTH)
+
+</details>
+
+<details>
+<summary>Files without tests in blast radius (5)</summary>
+
+- src/auth/middleware.ts
+- src/auth/jwt-helpers.ts
+- …
+</details>
+```
+
+## What a reviewer does with this
+
+Look at the four signals in order:
+
+1. **Risk badge.** HIGH / MEDIUM / LOW / SAFE. If it's SAFE or LOW, you can mostly skip the structural review and focus on the code itself. If it's HIGH, look more carefully.
+
+2. **Cross-domain violations.** Each one is a new dependency between domains. Sometimes correct (a refactor moving shared logic), sometimes a smell (auth pulling from payments). Reviewer applies judgment.
+
+3. **Files without tests.** Files in the blast radius that don't have a sibling test file. Lower confidence in the change because there's no automated check. Suggest the author add tests, or document why not.
+
+4. **High-impact file changed.** Anything modifying a >20-dependent file deserves an extra read-through. Subtle changes to a widely-used utility have outsized blast.
+
+## Failing the build on risk
+
+For repos that want a harder gate, set `fail-on` in the workflow:
+
+```yaml
+- uses: theanshsonkar/carto@v2.0.9
+  with:
+    fail-on: HIGH
+```
+
+Now the build fails when the risk is HIGH. PRs need to lower the risk (split, add tests, refactor) before they can merge.
+
+Use sparingly. HIGH-risk changes are sometimes correct and *necessary* — the right reviewer call is "look more carefully", not "block automatically".
+
+## Inputs reference
+
+| Input         | Default     | What it does |
+|---------------|-------------|--------------|
+| `carto-version` | `latest`  | Pin in production for reproducibility. |
+| `base`        | auto        | Git ref the PR branched from. Auto-detected from `origin/$GITHUB_BASE_REF`. |
+| `head`        | auto        | Git ref of the PR head. Auto-detected from `$GITHUB_SHA`. |
+| `fail-on`     | _(empty)_   | Fail when risk ≥ this severity. `HIGH`, `MEDIUM`, or `LOW`. |
+| `comment-mode`| `sticky`    | `sticky` updates existing comment, `new` posts a new one every push, `none` skips the comment (renders to stdout). |
+| `node-version`| `20`        | Node version on the runner. |
+
+## Outputs
+
+| Output       | Description |
+|--------------|-------------|
+| `risk`       | `SAFE` / `LOW` / `MEDIUM` / `HIGH` — gate downstream steps on it. |
+| `comment-url`| URL of the posted comment. |
+
+## Running it locally (mirror the CI)
+
+```bash
+carto pr-impact --base origin/main --head HEAD
+carto pr-impact --base origin/main --head HEAD --format json
+carto pr-impact --base origin/main --head HEAD --fail-on HIGH
+```
+
+Same engine, same output. Useful for testing changes before pushing.
+
+## Related
+
+- [`docs/guides/ci-integration.md`](./ci-integration.md) — broader CI patterns
+- [`docs/concepts/blast-radius.md`](../concepts/blast-radius.md) — the math behind the metric

package/docs/migration/v1-to-v2.md

@@ -0,0 +1,110 @@
+# Migration: V1 → V2
+
+> Notes for anyone who installed `carto-md` pre-2.0.6.
+
+## What V2 changed
+
+V1 stored the index as JSON files at `.carto/cache/graph-cache.json` and `.carto/cache/hashes.json`. V2 stores it as SQLite at `.carto/carto.db` with a derived bitmap sidecar at `.carto/bitmap.bin`.
+
+Why: SQLite handles 100K-file repos cleanly where the JSON approach started getting slow at ~10K files. The bitmap layer makes graph queries 100–10,000× faster than SQL at scale (see [`docs/scale.md`](../scale.md)).
+
+V1 has been fully deleted from the tree as of carto-md@2.0.6.
+
+## What you need to do
+
+In most cases — nothing. `carto init` (or any `carto` command that touches the index) detects the old V1 cache files and migrates them transparently on first run.
+
+Specifically, the migration:
+
+1. Reads `.carto/cache/graph-cache.json` if present (V1 metadata)
+2. Notices it's incompatible with the V2 schema
+3. Runs a fresh `carto sync` to repopulate `.carto/carto.db` from source
+4. Leaves the V1 files in place (they're harmless dead bytes)
+
+The Spec 7 test suite explicitly covers this case: *"carto init migrates leftover V1 graph-cache.json cleanly (no errors)"*.
+
+## Manual cleanup (optional)
+
+After the first V2 sync succeeds, the V1 files are no longer read. Reclaim a bit of disk:
+
+```bash
+rm -f .carto/cache/graph-cache.json
+rm -f .carto/cache/hashes.json
+rmdir .carto/cache  # if empty
+```
+
+Or just `carto remove && carto init` for a clean slate.
+
+## MCP wiring changes
+
+V1 exposed 12 MCP tools. V2 ships ~75, organized into 8 categories (core graph, episodic memory, temporal, brain, predictive, AI-native retrieval, adjacent, org-wide).
+
+The highest-impact additions from V1:
+
+- `get_architecture()` — the "use this first" tool
+- `get_file_summary(file)` — surfaces what `carto why` shows
+- `get_change_plan(intent)` — real graph traversal (V1 was keyword grep — Spec 2 rewrite)
+- `get_similar_patterns(file)` — Jaccard-similarity over import sets
+- `validate_diff(diff)` — sub-15ms pre-write governance, writes every call into the episodic log
+- `did_we_discuss_this(topic)` — six-week recall over the decision log
+- `get_predictive_risk(file?)` — P(file causes the next incident) score
+- `get_minimal_context_for_intent(intent, budget)` — token-budgeted hybrid retrieval (structural + lexical + semantic with RRF fusion)
+- `simulate_change_impact(files)` — bitmap-backed multi-file blast radius
+
+Plus the temporal trio (`get_architectural_drift`, `get_domain_evolution`, `get_hotspot_files`), the brain stack (`get_invariants`, `get_conventions`, `get_action_patterns`, `scaffold_for_intent`), and the org/cross-repo set (`get_org_architecture`, `get_service_dependency_graph`, `find_consumers_of_api`).
+
+Full reference: [`docs/api/`](../api/).
+
+If your AI tool was configured against V1 and you're seeing tool-not-found errors, restart the tool to pick up the V2 server's new `tools/list` response. The wire protocol is the same.
+
+## ACP agent
+
+V1's ACP agent (in Zed / JetBrains / VS Code via `carto agent`) used its own in-memory index. V2's ACP agent shares the SQLite index with the MCP server (Spec 5). Re-running `carto init` in your project ensures both ACP and MCP see the same data.
+
+## `.cartoignore` defaults
+
+V2 expanded the default exclusion list from 12 patterns to 39 (Spec 8: SSH keys, AWS/GCP creds, `.netrc`, kubeconfig, etc.). If your project had a custom `.cartoignore`, it's preserved — Carto only writes a default when none exists. To pick up the new defaults, delete your `.cartoignore` and run `carto init` to regenerate.
+
+## Git hooks
+
+V1 didn't install git hooks. V2 (Spec 9) installs four:
+
+- `pre-commit`
+- `post-checkout`
+- `post-merge`
+- `post-rewrite`
+
+Each runs `carto sync >/dev/null 2>&1 || true` — never blocks git, never errors loudly. If you already have hooks for other purposes, Carto appends to them non-destructively. Run `carto doctor` to confirm the hooks installed.
+
+## Behavior changes worth flagging
+
+| Behavior | V1 | V2 |
+|----------|----|----|
+| File-discovery cap | hard cap at ~50K files | uncapped |
+| Index format | JSON | SQLite + bitmap |
+| Re-parse on edit | only via `carto watch` | lazy at MCP query time + git hooks |
+| `get_change_plan` | keyword grep | real graph traversal |
+| Cross-domain detection | path-based | graph-clustered |
+| ACP / MCP share index | no | yes |
+| Read-only MCP DB | no | yes |
+| Default `.cartoignore` | 12 patterns | 39 patterns |
+
+If you depended on a V1-specific behavior that's no longer accurate, file an issue — we may have broken something we shouldn't have.
+
+## Pinned-version recommendation
+
+If you're upgrading in CI, pin a known-good Carto version:
+
+```yaml
+# .github/workflows/carto.yml
+- uses: theanshsonkar/carto@v2.0.9
+  with:
+    carto-version: '2.0.9'    # pin instead of `latest`
+```
+
+This way the action's output (and the PR-comment shape) stays stable across CI runs even when newer Carto versions ship.
+
+## Related
+
+- [`docs/troubleshooting.md`](../troubleshooting.md) — what to do when migration goes sideways
+- [Spec 6](../../Progress/working.md) in `Progress/working.md` — the deletion that removed V1