carto-md 1.1.2 → 1.1.4

package/CONTRIBUTING.md

@@ -10,23 +10,32 @@ Carto is free, open source, and community-maintained. The core team owns the mer
 
 New language support lives in `src/extractors/languages/`. Each language is an isolated module.
 
-Currently supported: JavaScript/TypeScript, Python, R.
+Currently supported: JavaScript/TypeScript, Python, Go, R.
 
-Wanted: Go, Rust, Ruby, Java, PHP, C#.
+Wanted: Rust, Ruby, Java, PHP, C#, Swift, Kotlin.
 
 ### Tier 2 — Framework extractors (safe to add, easy to review)
 
 Framework-specific route and model extraction lives in `src/extractors/`. Each framework is an isolated module.
 
-Currently supported: FastAPI, Express, Next.js App Router, Prisma, tRPC, HTML fetch(), Plumber, Shiny.
+Currently supported:
+- **JS/TS**: Express, Next.js (App + Pages Router), tRPC, Drizzle, Zod
+- **Python**: FastAPI, Flask, Pydantic, SQLAlchemy, Django (models + URLs)
+- **Go**: Gin, Echo, Chi, Fiber, net/http — routes, structs, import graph
+- **Schema**: Prisma
+- **Frontend**: HTML fetch()
+- **R**: Plumber, Shiny, R6, S7
 
-Wanted: Django, Rails, Laravel, NestJS, Hono, Gin, Spring.
+Wanted: Rails, Laravel, NestJS, Hono, Spring, Fastify.
 
 ### Tier 3 — Core (review carefully before merging)
 
 - `src/agents/merger.js` — merger logic. One bad merge = developer loses manual notes = project dies.
 - `src/agents/domains.js` — graph-based domain clustering. Wrong clusters = wrong context files.
+- `src/engine/carto.js` — programmatic module API. Breaking changes affect tools that import Carto.
 - `src/mcp/server.js` — MCP server tools. Breaking changes affect Kiro/Cursor/Claude integration.
+- `src/engine/incremental.js` — incremental graph update engine. Bugs here cause stale graphs.
+- `src/cache/` — file hash + graph cache. Bugs here cause wrong re-index behavior.
 - `src/detector/` — framework detection logic.
 - `src/cli/` — CLI commands.
 
@@ -36,23 +45,27 @@ Wanted: Django, Rails, Laravel, NestJS, Hono, Gin, Spring.
 
 1. Create `src/extractors/languages/yourlanguage.js`
 2. Export a plugin object:
+
 ```js
 module.exports = {
   name: 'yourlanguage',
   extensions: ['.ext'],
   extract(content, relPath) {
     return {
-      routes: [{ method, path, functionName }],
-      models: [{ className, fields: [{ name, type }] }],
-      functions: [{ name, params, returnType }],
-      envVars: ['VAR_NAME'],
-      dbTables: [{ tableName, modelName }],
-      fetches: [],
-      storageKeys: []
+      routes:      [{ method, path, functionName }],
+      models:      [{ className, fields: [{ name, type }], kind: 'yourlanguage' }],
+      functions:   [{ name, params, returnType }],
+      envVars:     ['VAR_NAME'],
+      dbTables:    [{ tableName, modelName }],
+      fetches:     [],
+      storageKeys: [],
+      events:      [{ type: 'listener'|'emitter', event: 'event.name' }],
+      jobs:        [{ type: 'cron'|'queue'|'interval', expression?: '* * * * *', name?: 'job-name' }],
     };
   }
 };
 ```
+
 3. The loader auto-discovers it — no changes to `loader.js` needed
 4. Test on at least 3 real open-source projects
 5. Open a PR with before/after AGENTS.md examples
@@ -70,12 +83,27 @@ module.exports = {
 
 ## How to add a domain keyword
 
-Domain clustering lives in `src/agents/domains.js`. The `DOMAIN_MAP` array maps keywords to domain names. If your framework creates a new domain category, add it:
+Domain clustering lives in `src/agents/domains.js`. The `DEFAULT_DOMAIN_MAP` array maps keywords to domain names. If your framework creates a new domain category, add it:
 
 ```js
 { keywords: ['graphql', 'resolver', 'mutation'], domain: 'GRAPHQL' },
 ```
 
+### Project-level custom domains
+
+For non-web repos (CLIs, desktop apps, compilers), users can define their own domains in `carto.config.json` at the project root without touching `domains.js`:
+
+```json
+{
+  "domains": {
+    "EDITOR": ["editor", "monaco", "text"],
+    "PLATFORM": ["platform", "service", "registry"]
+  }
+}
+```
+
+Custom config overrides the default domain map entirely for that project.
+
 ---
 
 ## Ground rules
@@ -96,7 +124,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
+npm test                     # run test suite (30 tests)
 ```
 
 ---
@@ -105,6 +133,7 @@ npm test                     # run test suite
 
 - [ ] Tested on at least 2-3 real open-source projects
 - [ ] Before/after AGENTS.md included in PR description
+- [ ] Plugin returns all fields including `events` and `jobs` (can be empty arrays)
 - [ ] No changes to merger logic (unless explicitly fixing a merger bug)
 - [ ] No network calls added
 - [ ] `carto --version` still works

package/README.md

@@ -4,293 +4,351 @@
 [![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 [![npm downloads](https://img.shields.io/npm/dm/carto-md)](https://www.npmjs.com/package/carto-md)
 
-**The codebase intelligence layer every AI tool queries instead of guessing.**
+**The structural intelligence layer for AI coding tools.**
 
 ```bash
 npm install -g carto-md
 ```
 
-Carto maps your codebase — routes, models, import graph, domain context — and exposes it as a live MCP server that Kiro, Cursor, and Claude can query mid-task. No hallucinations about your own project. No rebuilding context every session.
+Carto indexes your codebase (routes, models, import graph, blast radius, domain clusters) and keeps it live. Every AI tool you use gets accurate structural facts about your project instead of guessing.
 
 ---
 
-## The problem
+## What it does in one sentence
 
-AI coding tools are blind to your actual project. Every session starts from zero.
+**Your file changes. Carto re-indexes in ~130ms. Every AI tool instantly knows what broke.**
 
-- Claude hallucinates your schema
-- Copilot suggests wrong field names
-- Kiro asks what framework you're using
-- You rebuild context manually, every time
+---
+
+## Proof: Supabase repo (6,335 files)
+
+Fresh `carto init`. No prior knowledge of the repo.
+
+```
+Detected:   nextjs (javascript)
+Indexed:    310 files in 422ms
+Routes:     104 API endpoints
+Models:     3,598 extracted
+Domains:    AUTH · DATABASE · PAYMENTS · EVENTS · NOTIFICATIONS · TRPC · CORE
+Import edges: 5,248
+```
+
+Then a file changes:
 
-`AGENTS.md` fixes this — a standard file every AI tool reads. But it's static. You write it manually. It gets stale the moment your code changes.
+```
+packages/ui/src/lib/utils/cn.ts updated
+
+Re-indexed in 129ms.
 
-**Carto makes it live. And queryable.**
+Risk: 🔴 HIGH
+Directly affected: 55 files
+Potentially affected: 83 files total
+
+Files that depend on this:
+  → packages/ui/src/components/Button/Button.tsx
+  → packages/ui/src/components/Modal/Modal.tsx
+  → packages/ui/src/components/shadcn/ui/button.tsx
+  → ...83 more
+```
 
-| | Without Carto | With Carto |
-|---|---|---|
-| Knows blast radius before editing | Never | Always, instantly |
-| Knows which routes break | Never | Exact list |
-| Plans multi-file changes | Guesses | Fully informed |
-| Hallucinates field names | Often | Never |
-| Understands codebase on session start | 10–20 min | 0 |
-| Works across Kiro, Cursor, Claude, Copilot | Separately | One shared graph |
-| Stays current as code changes | Goes stale | Live on every save |
+One file changed. Carto told you exactly what broke. In 129ms. On a 6,335 file monorepo.
 
 ---
 
-## Proof — cal.com (800k lines)
+## Proof: cal.com (800k lines)
 
 Same task, two Claude sessions: *"Add a `notes` field to the booking model."*
 
 **Without Carto:**
-- Wrong API route: suggested `POST /api/bookings` → actual is `POST /v2/bookings`
-- Wrong handler: suggested `handleNewBooking.ts` → not the creation path
-- Wrong file paths: pointed to v1 API → v1 is legacy
-- Wrong tRPC file: `bookings.tsx` → actual is `bookings/_router.tsx`
-- Field list: ~15 fields guessed → missing 20+ real fields
 
-**With Carto:**
-- Correct API route ✅
-- Correct controller path ✅
-- Correct tRPC file ✅
-- All 35+ booking fields returned accurately ✅
-- Answered in one shot. No follow-up needed.
+| | What AI suggested | Reality |
+|--|---|---|
+| API route | `POST /api/bookings` | `POST /v2/bookings` |
+| Handler | `handleNewBooking.ts` | Not the creation path |
+| File path | v1 API files | v1 is legacy |
+| tRPC file | `bookings.tsx` | `bookings/_router.tsx` |
+| Fields found | ~15 guessed | 35+ actual fields |
 
-**4 wrong file paths → 0. 20 missing fields → 0. Zero follow-up clarifications.**
+**With Carto:** Correct route, correct handler, correct file, all 35+ fields. One shot. Zero follow-ups.
+
+**4 wrong paths → 0. 20 missing fields → 0.**
 
 Not smarter AI. The same AI with accurate facts.
 
 ---
 
+## Performance
+
+Tested on Supabase (6,335 files, 310 watched):
+
+| Operation | Time |
+|-----------|------|
+| Cold start (first `carto init`) | 422ms |
+| Warm start (files cached) | 66ms |
+| One file change (incremental re-index) | ~130ms |
+| Blast radius lookup | <5ms |
+| Route search | <1ms |
+
+The secret: file hashes. On warm runs, Carto skips every file whose content hasn't changed. On a file save, only that one file gets re-parsed. The rest loads from disk cache in milliseconds.
+
+---
+
 ## How it works
 
 ```
 carto init
-      ↓
-Carto maps your codebase
-  → AGENTS.md (79 lines — lean map every AI reads)
-  → .carto/context/AUTH.md, PAYMENTS.md, TRPC.md, DATABASE.md
-  → .carto/map.json (import graph, routes, blast radius)
-  → MCP server auto-wired into Kiro, Cursor, Claude Desktop
-      ↓
-carto watch  (keeps everything live on every file save)
-carto serve  (MCP server — AI tools query graph mid-task)
+  ↓
+Hashes every file → skips unchanged on re-runs
+Builds import graph → knows who depends on who
+Extracts routes, models, functions, env vars
+Clusters into domains (AUTH, PAYMENTS, DATABASE...)
+Calculates blast radius for every file
+Writes AGENTS.md + .carto/context/*.md
+Auto-wires MCP into Kiro, Cursor, Claude Desktop
+  ↓
+carto watch
+  ↓
+File saved → re-parse 1 file → update graph → ~130ms
 ```
 
 ---
 
-## MCP — AI queries your codebase live
+## 12 MCP tools: AI queries your codebase live
+
+`carto serve` exposes a local MCP server. Kiro, Cursor, and Claude query it mid-task instead of guessing.
+
+| Tool | What it returns |
+|------|----------------|
+| `get_blast_radius(file)` | Risk level, all affected files, routes at risk per domain |
+| `get_context(file)` | Everything about a file in one call: domain, blast radius, neighbors, routes, models |
+| `get_routes()` | All API endpoints with file mapping |
+| `get_structure()` | Import graph, entry points, high-impact files, tech stack |
+| `get_domain(name)` | All routes, models, functions for AUTH / PAYMENTS / DATABASE / etc. |
+| `get_neighbors(file, hops)` | Import graph neighbors: nodes and edges |
+| `get_cross_domain()` | Import edges that cross domain boundaries |
+| `search_routes(query)` | Search API routes by path or method |
+| `get_models(domain?)` | All data models, optionally filtered by domain |
+| `get_high_impact_files(n)` | Top N files by blast radius, highest-risk to change |
+| `get_env_vars(domain?)` | All env vars with domain mapping |
+| `get_domains_list()` | All detected domains with file, route, model counts |
 
-`carto init` auto-wires the MCP config into Kiro, Cursor, and Claude Desktop automatically. When Kiro or Cursor is mid-task, it can call Carto directly instead of guessing:
+---
 
-**`get_blast_radius("src/lib/payments.ts")`**
-```
-Files affected:
-  → apps/web/app/api/checkout/route.ts
-  → apps/web/app/api/webhook/route.ts
-  → packages/trpc/routers/billing.ts
-
-Routes at risk:
-  → POST /api/checkout
-  → POST /api/webhook
-  → POST /trpc/createSubscription
-```
+## What gets extracted
 
-**`get_routes()`**
-```
-| Method | Path                        | Handler             |
-|--------|-----------------------------|---------------------|
-| POST   | /api/auth/signup            | POST                |
-| GET    | /api/auth/oauth/me          | GET                 |
-| POST   | /trpc/createBooking         | createBooking       |
-| GET    | /trpc/getAvailability       | getAvailability     |
-| ...    | ...                         | ...                 |
-```
+| Category | What Carto finds |
+|----------|-----------------|
+| **Routes** | FastAPI, Flask, Express, Next.js App/Pages Router, React Router (JSX + createBrowserRouter), tRPC procedures, Django URLs, Gin/Echo/Chi/Fiber (Go) |
+| **Models** | Prisma, Pydantic, SQLAlchemy, Django ORM, TypeScript interfaces/types, Zod schemas, Drizzle tables, Go structs |
+| **Graph** | Full import graph: who imports what, transitive dependencies up to 5 hops — JS/TS, Python, Go, R |
+| **Blast radius** | Risk level (HIGH/MEDIUM/LOW) per file and per route |
+| **Domains** | AUTO-clustered from imports. Defaults: AUTH, PAYMENTS, DATABASE, EVENTS, TRPC, NOTIFICATIONS, CORE. Custom domains via `carto.config.json`. |
+| **Events** | EventEmitter listeners, webhook handlers, queue jobs, cron schedules |
+| **Env vars** | Every `process.env` / `os.Getenv` call (names only, never values) |
+| **Functions** | Signatures with param names and return types |
 
-**`get_domain("AUTH")`**
-Returns `AUTH.md` — all auth routes, session models, JWT functions, env vars.
+---
 
-**`get_structure()`**
-Returns import graph, entry points, high impact files, tech stack.
+## Languages and frameworks
 
-### Manual MCP config (if auto-wire didn't detect your IDE)
+| Language | Frameworks |
+|----------|------------|
+| TypeScript / JavaScript | Express, Next.js (App + Pages Router), React Router, tRPC, Drizzle, Zod |
+| Python | FastAPI, Flask, Pydantic, SQLAlchemy, Django |
+| Go | Gin, Echo, Chi, Fiber, net/http — including full import graph |
+| R | Plumber, Shiny, R6, S7 |
+| Schema | Prisma |
+| HTML | fetch() calls |
 
-**Kiro** — add to `~/.kiro/settings/mcp.json`:
-```json
-{
-  "mcpServers": {
-    "carto": {
-      "command": "carto",
-      "args": ["serve"],
-      "cwd": "/path/to/your/project"
-    }
-  }
-}
-```
+More via community. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-**Cursor** — add to `~/.cursor/mcp.json`:
-```json
-{
-  "mcpServers": {
-    "carto": {
-      "command": "carto",
-      "args": ["serve"],
-      "cwd": "/path/to/your/project"
-    }
-  }
-}
-```
+---
+
+## Custom domains (`carto.config.json`)
+
+By default Carto clusters into web-app domains (AUTH, PAYMENTS, etc.). For any other architecture — desktop apps, CLIs, compilers, monorepos — define your own:
 
-**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 ```json
 {
-  "mcpServers": {
-    "carto": {
-      "command": "carto",
-      "args": ["serve"],
-      "cwd": "/path/to/your/project"
-    }
+  "domains": {
+    "EDITOR": ["editor", "monaco", "text", "cursor"],
+    "WORKBENCH": ["workbench", "layout", "panel", "sidebar"],
+    "PLATFORM": ["platform", "service", "registry"],
+    "BASE": ["base", "common", "util"]
   }
 }
 ```
 
-Then run `carto serve` in your project directory alongside `carto watch`.
+Drop `carto.config.json` in your project root. Carto picks it up on the next `carto init` or `carto sync`. The import graph and blast radius always work regardless — custom domains only affect how files are clustered and labeled.
 
 ---
 
-## Domain context files
+## Commands
 
-Large codebases kill AI accuracy. A 2900-line AGENTS.md means AI reads 500 lines and guesses the rest.
+| Command | What it does |
+|---------|-------------|
+| `carto init` | Detect project, index codebase, generate AGENTS.md, wire MCP |
+| `carto watch` | Incremental live re-index on every file save (~130ms) |
+| `carto sync` | One-time manual re-index |
+| `carto impact <file>` | Blast radius: risk level, affected files, routes at risk |
+| `carto check` | Cross-domain violations, high-risk uncommitted changes, domain health |
+| `carto serve` | Start MCP server for Kiro / Cursor / Claude |
+| `carto remove` | Remove AGENTS.md and .carto/ from project |
+| `carto --version` | Show version |
 
-Carto splits context by domain automatically:
+---
 
-```
-AGENTS.md                  → 79 lines, always loaded
-.carto/context/
-  AUTH.md                  → auth routes, session models, JWT functions
-  PAYMENTS.md              → Stripe routes, billing models
-  TRPC.md                  → all tRPC procedures
-  DATABASE.md              → every model, schema, table
-  EVENTS.md                → webhooks, queues, cron jobs
-  CORE.md                  → shared utilities
-```
+## `carto check`
 
-AI reads AGENTS.md always. Then reads only the relevant domain file for the current task. 400 lines of exact context instead of 2900 lines of everything.
+Run before committing. Tells you what's risky before you push.
 
-Domain assignment uses your import graph — files that import each other cluster together, regardless of folder names.
+```
+── Carto Check ───────────────────────────────────────
 
----
+  Files indexed : 310
+  Routes found  : 104
+  Import edges  : 5,248
+  Domains       : AUTH · DATABASE · PAYMENTS · EVENTS · CORE
 
-## Know what breaks before you break it
+  ⚠️  High-risk uncommitted changes (1):
+     🔴 src/lib/auth.service.ts
+        11 files depend on this, blast risk: HIGH
 
-```bash
-carto impact apps/web/app/api/auth/signup/route.ts
-
-# Impact analysis: apps/web/app/api/auth/signup/route.ts
-#
-# Imported by:
-#   → apps/web/app/api/auth/signup/handlers/calcomSignupHandler.ts
-#   → apps/web/app/api/auth/signup/handlers/selfHostedHandler.ts
-#
-# Routes at risk:
-#   → POST /api/auth/signup
-#   → ALL /api/auth/signup/handlers
-#
-# Risk: MEDIUM
-```
+  ✅ No cross-domain dependency violations
 
-No AI. No cloud. Runs in under a second. From your live import graph.
+  🔥 Top high-impact files:
+      83 dependents - packages/ui/src/lib/utils/cn.ts
+      35 dependents - packages/pg-meta/src/pg-format/index.ts
+      34 dependents - packages/icons/src/createSupabaseIcon.ts
+```
 
 ---
 
-## Install
+## `carto impact`
 
 ```bash
-npm install -g carto-md
-```
+carto impact src/middleware.ts
 
-Or without installing:
+Impact analysis: src/middleware.ts
 
-```bash
-npx carto-md init
+Risk: 🔴 HIGH
+Directly affected: 11 files across 2 domain(s)
+Domains impacted: AUTH, PAYMENTS
+
+Files that depend on this (11):
+  → src/routes/auth.ts
+  → src/routes/billing.ts
+  → ...
+
+Routes at risk (4):
+  🔴 POST /api/auth/login
+  🔴 POST /api/billing/checkout
+  🟡 GET  /api/users/me
+  🟢 GET  /api/health
 ```
 
 ---
 
-## Usage
+## Programmatic API
 
-```bash
-cd your-project
-carto init
-```
+Use Carto as a module, no CLI required. This is how tools embed it.
 
-That's it. Carto:
-- Maps your codebase
-- Generates AGENTS.md + domain context files
-- Auto-wires MCP into Kiro, Cursor, Claude Desktop
-- Installs a git hook — syncs on every commit
+```js
+const { Carto } = require('carto-md');
 
-Run `carto watch` in background for live updates on every file save.
-Run `carto serve` to start the MCP server manually if needed.
+const carto = new Carto();
+await carto.index('/path/to/project');
 
----
+// Everything about a file in one call
+const ctx = carto.getContextForFile('src/auth/auth.service.ts');
+// {
+//   domain: 'AUTH',
+//   routes: ['POST /api/auth/login', 'GET /api/auth/me'],
+//   models: ['User', 'Session'],
+//   blastRadius: { risk: 'HIGH', directlyAffected: { files: 8, domains: 2 } },
+//   neighbors: { nodes: [...], edges: [...] },  // React Flow compatible
+//   crossDomainDeps: [...],
+//   domainContext: '...AUTH.md content...'
+// }
 
-## Commands
+// Live updates
+carto.on('updated', ({ file, blastRadius }) => {
+  console.log(`${file} changed, blast risk: ${blastRadius.risk}`);
+});
 
-| Command | What it does |
-|---------|-------------|
-| `carto init` | Map codebase, generate context files, wire MCP into IDEs |
-| `carto watch` | Live updates on every file save |
-| `carto sync` | One-time manual refresh |
-| `carto serve` | Start MCP server for Kiro/Cursor/Claude queries |
-| `carto impact <file>` | Show blast radius before touching a file |
-| `carto remove` | Remove AGENTS.md and .carto/ from this project |
-| `carto --version` | Show version |
+await carto.reindex('src/auth/auth.service.ts'); // ~130ms
+```
+
+**Full API:**
+
+```js
+carto.getBlastRadius(file)       // Risk + affected files + routes
+carto.getNeighbors(file, hops)   // Import graph, React Flow nodes/edges
+carto.getCrossDomainDeps()       // Cross-boundary import edges
+carto.getHighImpactFiles(n)      // Top N by blast radius
+carto.searchRoutes(query)        // Route search
+carto.getRoutes()                // All API routes
+carto.getDomain(name)            // Domain cluster + context file
+carto.getDomainsList()           // All domains with counts
+carto.getModels(domain?)         // All models
+carto.getEnvVars(domain?)        // Env vars with domain mapping
+carto.getMeta()                  // Index stats
+```
+
+Events: `status` · `indexed` · `updated`
 
 ---
 
-## Works with
+## Domain context files
 
-| Language | Frameworks |
-|----------|------------|
-| Python | FastAPI, Pydantic |
-| JavaScript | Express, Next.js |
-| TypeScript | Express, Next.js, Prisma, tRPC |
-| R | Plumber, Shiny, R6, S7 |
-| HTML | fetch() calls |
+Large codebases kill AI accuracy. A 2,900-line AGENTS.md means the AI reads 500 lines and guesses the rest.
 
-More languages via community — open an issue or see [CONTRIBUTING.md](CONTRIBUTING.md).
+Carto splits context by domain automatically:
 
----
+```
+AGENTS.md                 → lean map, always loaded by every AI
+.carto/context/
+  AUTH.md                 → auth routes, session models, JWT functions, middleware
+  PAYMENTS.md             → Stripe routes, billing models, webhook handlers
+  DATABASE.md             → every model, schema, table, migration pattern
+  EVENTS.md               → webhooks, queues, cron jobs, event emitters
+  TRPC.md                 → all procedures with input/output schemas
+  CORE.md                 → shared utilities
+```
 
-## What gets extracted
+AI reads AGENTS.md always. Then fetches only the domain file relevant to the task. 400 lines of exact context instead of 2,900 lines of everything.
 
-- API routes — FastAPI, Express, Next.js App Router, tRPC procedures
-- Data models — Pydantic, Prisma, TypeScript interfaces
-- Function signatures — across all files
-- Import graph — which files depend on which
-- Domain clusters — AUTH, PAYMENTS, TRPC, DATABASE, EVENTS
-- Blast radius — what breaks if you change a file
-- Environment variable names — never values
-- Database tables — SQLAlchemy, Django ORM, Prisma
+Domain assignment runs on your import graph: files that import each other cluster together, regardless of folder names.
 
 ---
 
-## What Carto never touches
+## MCP config (if auto-wire missed your IDE)
 
-Your manual sections stay yours forever. Carto only rewrites between its own markers:
+**Kiro**: `~/.kiro/settings/mcp.json`
+```json
+{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
+```
 
+**Cursor**: `~/.cursor/mcp.json`
+```json
+{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
 ```
-<!-- CARTO:AUTO:START -->
-... auto-generated content ...
-<!-- CARTO:AUTO:END -->
 
-Your manual notes here. Never touched.
+**Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+```json
+{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
 ```
 
 ---
 
+## AI tools that read AGENTS.md natively
+
+Cursor · GitHub Copilot · Kiro · Claude Desktop · Claude Code · Codex · VS Code · Gemini CLI · Devin · Jules
+
+Carto generates the file they all read. One source of truth. Every tool stays accurate.
+
+---
+
 ## What Carto fixes
 
 Carto fixes **factual hallucination about your own project**:
@@ -298,66 +356,56 @@ Carto fixes **factual hallucination about your own project**:
 - AI guessing wrong routes → fixed
 - AI guessing wrong field names → fixed
 - AI assuming wrong framework → fixed
-- AI guessing wrong DB schema → fixed
 - AI not knowing blast radius → fixed
+- AI losing context between sessions → fixed
+- Rebuilding project context every session → gone
 
-What Carto does not fix: AI reasoning badly, wrong implementation logic, misunderstanding what you want. Carto makes AI **accurate** about your project. Not smarter. Accurate. Different thing.
+What Carto does not fix: AI reasoning badly, wrong implementation logic, misunderstanding requirements. Carto makes AI **accurate** about your project. Not smarter. Accurate. Different thing.
 
 ---
 
-## AI tools that read AGENTS.md
+## What Carto never does
 
-- **Cursor** — via context rules + MCP
-- **GitHub Copilot** — via workspace instructions
-- **Kiro** — natively + MCP
-- **Claude Desktop** — via MCP
-- **Claude Code** — natively
-- **Codex** — natively
-- **VS Code** — via workspace context
-- **Gemini CLI** — natively
-- **Devin** — natively
-- **Jules** — natively
+- Sends your code anywhere. Local only.
+- Writes secrets into AGENTS.md. `.cartoignore` blocks `.env` and credential files by default.
+- Touches your manual notes. It writes only between `<!-- CARTO:AUTO:START -->` and `<!-- CARTO:AUTO:END -->`.
+- Costs money. MIT license. Free forever.
 
 ---
 
-## What it does NOT do
-
-- No cloud. No servers. No telemetry. No tracking.
-- Your code never leaves your machine.
-- No paid tiers. Free forever. MIT license.
-
----
-
-## Security
-
-Carto never writes secrets into AGENTS.md. `.cartoignore` blocks `.env` files, secret files, key files, and credential files by default. The sanitizer strips API key patterns from extracted code.
+## Install
 
----
+```bash
+npm install -g carto-md
+```
 
-## Contributing
+```bash
+cd your-project
+carto init
+```
 
-Python, JS/TS, and R today. Want Go, Ruby, Django, Rails? Open an issue — or read [CONTRIBUTING.md](CONTRIBUTING.md) to add it yourself.
+That's it.
 
 ---
 
 ## Origin
 
-I was building [Emfirge](https://emfirge.cloud) — a cloud security agent for AWS.
+I was building Emfirge, a cloud security agent for AWS.
 
-To make the AI inside Emfirge understand infrastructure, I wrote a module called `cartography.py`. It mapped AWS resources, built a graph of how they connected, and wrote it into a structured map. The AI stopped hallucinating. It worked with accurate facts — not guesses.
+To make the AI understand infrastructure, I built a module that mapped AWS resources into a graph. The AI stopped hallucinating. It worked with facts.
 
-Halfway through, I switched AI tools. Opened a new session. Had to explain everything again from scratch.
+Then I switched AI tools. New session. Had to explain the whole project again from scratch.
 
-I thought: *I just built a cartography system so AI can understand infrastructure. Why doesn't this exist for codebases?*
+I thought: *I just built a cartography system for infrastructure. Why doesn't this exist for codebases?*
 
-Carto is that. Same insight, different domain.
+Carto is that.
 
 ---
 
 ## License
 
-MIT — free forever.
+MIT. Free forever.
 
 ---
 
-*Built because AGENTS.md won. Someone had to keep it alive — and make it queryable.*
+*Your code changes. Carto knows. Every AI you use knows.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carto-md",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "The context layer for AI-native development.",
   "bin": {
     "carto": "src/cli/index.js"

package/src/agents/domains.js

@@ -1,6 +1,6 @@
 const path = require('path');
 
-const DOMAIN_MAP = [
+const DEFAULT_DOMAIN_MAP = [
   { keywords: ['auth', 'login', 'session', 'oauth', 'token', 'jwt', 'password', 'credential'], domain: 'AUTH' },
   { keywords: ['payment', 'billing', 'stripe', 'invoice', 'charge', 'subscription', 'checkout'], domain: 'PAYMENTS' },
   { keywords: ['trpc', 'router', 'routers', 'procedure'], domain: 'TRPC' },
@@ -9,6 +9,29 @@ const DOMAIN_MAP = [
   { keywords: ['email', 'notification', 'mail', 'sms', 'alert'], domain: 'NOTIFICATIONS' },
 ];
 
+// Active domain map — replaced by setDomainMap() when carto.config.json is present
+let DOMAIN_MAP = DEFAULT_DOMAIN_MAP;
+
+/**
+ * setDomainMap(customDomains)
+ * Override the domain map from carto.config.json.
+ *
+ * customDomains format:
+ *   { "EDITOR": ["editor", "monaco"], "WORKBENCH": ["workbench", "panel"] }
+ *
+ * Pass null to reset to defaults.
+ */
+function setDomainMap(customDomains) {
+  if (!customDomains || typeof customDomains !== 'object' || Array.isArray(customDomains)) {
+    DOMAIN_MAP = DEFAULT_DOMAIN_MAP;
+    return;
+  }
+  DOMAIN_MAP = Object.entries(customDomains).map(([domain, keywords]) => ({
+    domain: domain.toUpperCase(),
+    keywords: keywords.map(k => String(k).toLowerCase()),
+  }));
+}
+
 /**
  * getDomainForFile(relPath) → domain string or null
  * Returns domain if path matches a keyword, null if no match.
@@ -112,7 +135,7 @@ function clusterByDomain(data) {
 
   function getCluster(domain) {
     if (!clusters[domain]) {
-      clusters[domain] = { routes: [], models: [], functions: {}, envVars: [], dbTables: [], fileMap: [] };
+      clusters[domain] = { routes: [], models: [], functions: {}, envVars: [], dbTables: [], fileMap: [], files: [] };
     }
     return clusters[domain];
   }
@@ -182,7 +205,12 @@ function clusterByDomain(data) {
     getCluster(domain).fileMap.push(entry);
   }
 
+  // Files — populate from assignments so cluster.files is always set
+  for (const [file, domain] of assignments.entries()) {
+    getCluster(domain).files.push(file);
+  }
+
   return clusters;
 }
 
-module.exports = { clusterByDomain, getDomainForFile, buildFileAssignments };
+module.exports = { clusterByDomain, getDomainForFile, buildFileAssignments, setDomainMap };

package/src/detector/framework.js

@@ -7,6 +7,7 @@ const IGNORE_DIRS = new Set(['node_modules', '.git', '__pycache__', '.venv', 've
 const PYTHON_PRIORITY = ['fastapi', 'django', 'flask', 'python-generic'];
 const JS_PRIORITY = ['nextjs', 'express', 'react', 'node-generic'];
 const R_PRIORITY = ['plumber', 'shiny', 'r-generic'];
+const GO_PRIORITY = ['gin', 'echo', 'chi', 'fiber', 'go-generic'];
 
 /**
  * detectFramework(projectRoot) → { framework, language, confidence, secondaryFramework?, secondaryLanguage? }
@@ -17,7 +18,7 @@ const R_PRIORITY = ['plumber', 'shiny', 'r-generic'];
  * (primary = highest priority overall, secondary = the other language).
  */
 function detectFramework(projectRoot) {
-  const candidates = findFile(projectRoot, ['requirements.txt', 'package.json', 'pyproject.toml', 'DESCRIPTION'], 3);
+  const candidates = findFile(projectRoot, ['requirements.txt', 'package.json', 'pyproject.toml', 'DESCRIPTION', 'go.mod'], 3);
 
   const pythonDetections = new Set();
   const jsDetections = new Set();
@@ -43,9 +44,15 @@ function detectFramework(projectRoot) {
     for (const r of detectAllFromRFiles(projectRoot)) rDetections.add(r);
   }
 
+  const goDetections = new Set();
+  for (const f of candidates.filter(f => path.basename(f) === 'go.mod')) {
+    for (const r of detectAllFromGoMod(f)) goDetections.add(r);
+  }
+
   const bestPython = PYTHON_PRIORITY.find(fw => pythonDetections.has(fw)) || null;
   const bestJS = JS_PRIORITY.find(fw => jsDetections.has(fw)) || null;
   const bestR = R_PRIORITY.find(fw => rDetections.has(fw)) || null;
+  const bestGo = GO_PRIORITY.find(fw => goDetections.has(fw)) || null;
 
   if (bestPython && bestJS) {
     return {
@@ -57,17 +64,10 @@ function detectFramework(projectRoot) {
     };
   }
 
-  if (bestPython) {
-    return { framework: bestPython, language: 'python', confidence: 'high' };
-  }
-
-  if (bestJS) {
-    return { framework: bestJS, language: 'javascript', confidence: 'high' };
-  }
-
-  if (bestR) {
-    return { framework: bestR, language: 'r', confidence: 'high' };
-  }
+  if (bestPython) return { framework: bestPython, language: 'python', confidence: 'high' };
+  if (bestJS)     return { framework: bestJS, language: 'javascript', confidence: 'high' };
+  if (bestGo)     return { framework: bestGo, language: 'go', confidence: 'high' };
+  if (bestR)      return { framework: bestR, language: 'r', confidence: 'high' };
 
   return { framework: 'unknown', language: 'unknown', confidence: 'none' };
 }
@@ -141,6 +141,18 @@ function detectAllFromPackageJson(filePath) {
   return detected;
 }
 
+function detectAllFromGoMod(filePath) {
+  const detected = [];
+  let content;
+  try { content = fs.readFileSync(filePath, 'utf-8').toLowerCase(); } catch { return detected; }
+  if (content.includes('gin-gonic/gin'))   detected.push('gin');
+  if (content.includes('labstack/echo'))   detected.push('echo');
+  if (content.includes('go-chi/chi'))      detected.push('chi');
+  if (content.includes('gofiber/fiber'))   detected.push('fiber');
+  if (!detected.length)                    detected.push('go-generic');
+  return detected;
+}
+
 function detectAllFromRDescription(filePath) {
   const detected = [];
   let content;

package/src/engine/carto.js

@@ -11,7 +11,7 @@ const { WorkerPool } = require('./worker-pool');
 const { loadLanguagePlugins, getPluginForFile } = require('../extractors/loader');
 const { buildImportGraph } = require('../extractors/imports');
 const { buildStackLine } = require('../extractors/stack');
-const { getDomainForFile, buildFileAssignments } = require('../agents/domains');
+const { getDomainForFile, buildFileAssignments, setDomainMap } = require('../agents/domains');
 const { extractImports } = require('../extractors/imports');
 
 const plugins = loadLanguagePlugins();
@@ -39,6 +39,7 @@ class Carto extends EventEmitter {
     this._cache = null;
     this._projectRoot = null;
     this._pool = null;
+    this._domainByFile = null; // reverse map: relPath → domainName
   }
 
   // ─── Indexing ────────────────────────────────────────────────────────────
@@ -54,6 +55,14 @@ class Carto extends EventEmitter {
 
     this.emit('status', { state: 'indexing', progress: 0 });
 
+    // Load custom domain config if present
+    try {
+      const config = JSON.parse(fs.readFileSync(path.join(projectRoot, 'carto.config.json'), 'utf-8'));
+      setDomainMap(config.domains || null);
+    } catch {
+      setDomainMap(null); // reset to defaults
+    }
+
     const cartoDir = path.join(projectRoot, '.carto');
     try { fs.mkdirSync(cartoDir, { recursive: true }); } catch {}
 
@@ -146,6 +155,7 @@ class Carto extends EventEmitter {
     }
 
     recomputeGraphMetrics(this._cache);
+    this._buildDomainMap();
     this._cache.meta.indexDuration = Date.now() - start;
     this._cache.meta.lastIndexed = new Date().toISOString();
     this._cache.generated = new Date().toISOString();
@@ -185,6 +195,7 @@ class Carto extends EventEmitter {
     updateFileHash(this._projectRoot, relPath, content);
     saveGraphCache(this._projectRoot, this._cache);
 
+    this._buildDomainMap();
     const blastRadius = this.getBlastRadius(relPath);
     this.emit('status', { state: 'ready' });
     this.emit('updated', { file: relPath, blastRadius });
@@ -555,12 +566,17 @@ class Carto extends EventEmitter {
     return null;
   }
 
-  _getDomainForFile(relPath) {
-    const domains = this._cache.domains || {};
-    for (const [name, cluster] of Object.entries(domains)) {
-      if ((cluster.files || []).includes(relPath)) return name;
+  _buildDomainMap() {
+    this._domainByFile = {};
+    for (const [name, cluster] of Object.entries(this._cache.domains || {})) {
+      for (const file of (cluster.files || [])) {
+        this._domainByFile[file] = name;
+      }
     }
-    return null;
+  }
+
+  _getDomainForFile(relPath) {
+    return this._domainByFile ? (this._domainByFile[relPath] || null) : null;
   }
 
   _discoverFiles(projectRoot) {

package/src/extractors/imports.js

@@ -39,6 +39,8 @@ function extractImports(content, filePath, projectRoot) {
     rawImports = extractPythonImports(content, filePath, projectRoot);
   } else if (ext === '.r') {
     return extractRImports(content, filePath, projectRoot);
+  } else if (ext === '.go') {
+    return extractGoImports(content, filePath, projectRoot);
   }
 
   // Resolve and deduplicate
@@ -220,6 +222,79 @@ function resolveImportPath(importPath, fileDir, projectRoot, sourceExt) {
   return null;
 }
 
+// ─── Go imports ──────────────────────────────────────────────────────────────
+
+// Cache go.mod module name per projectRoot — read once, reuse
+const _goModCache = new Map();
+
+function _getGoModuleName(projectRoot) {
+  if (_goModCache.has(projectRoot)) return _goModCache.get(projectRoot);
+  try {
+    const content = fs.readFileSync(path.join(projectRoot, 'go.mod'), 'utf-8');
+    const m = content.match(/^module\s+(\S+)/m);
+    const name = m ? m[1] : null;
+    _goModCache.set(projectRoot, name);
+    return name;
+  } catch {
+    _goModCache.set(projectRoot, null);
+    return null;
+  }
+}
+
+/**
+ * extractGoImports(content, filePath, projectRoot) → Array<string>
+ *
+ * Resolves local Go imports (same module) to actual .go files.
+ * Requires go.mod at projectRoot to determine the module name.
+ *
+ * Handles:
+ *   import "module/path/pkg"
+ *   import ( "module/path/pkg1" \n "module/path/pkg2" )
+ *   import alias "module/path/pkg"
+ */
+function extractGoImports(content, filePath, projectRoot) {
+  const moduleName = _getGoModuleName(projectRoot);
+  if (!moduleName) return [];
+
+  const results = new Set();
+
+  // Collect all import paths from both single and block imports
+  const importPaths = [];
+
+  // Single-line: import "path" or import alias "path"
+  const singleRe = /^import\s+(?:\w+\s+)?"([^"]+)"/gm;
+  let m;
+  while ((m = singleRe.exec(content)) !== null) importPaths.push(m[1]);
+
+  // Block: import ( ... )
+  const blockRe = /import\s*\(([^)]+)\)/g;
+  while ((m = blockRe.exec(content)) !== null) {
+    const block = m[1];
+    const lineRe = /"([^"]+)"/g;
+    let lm;
+    while ((lm = lineRe.exec(block)) !== null) importPaths.push(lm[1]);
+  }
+
+  // Resolve local imports only (starts with this module's name)
+  const prefix = moduleName + '/';
+  for (const imp of importPaths) {
+    if (!imp.startsWith(prefix)) continue;
+    const localPkg = imp.slice(prefix.length); // e.g. "internal/auth"
+    const pkgDir = path.join(projectRoot, localPkg);
+
+    // Find first non-test .go file in the package directory
+    try {
+      const entries = fs.readdirSync(pkgDir);
+      const goFile = entries.find(e => e.endsWith('.go') && !e.endsWith('_test.go'));
+      if (goFile) {
+        results.add(path.relative(projectRoot, path.join(pkgDir, goFile)));
+      }
+    } catch { /* directory doesn't exist or can't be read */ }
+  }
+
+  return [...results].sort();
+}
+
 /**
  * buildImportGraph(fileContents, projectRoot) → { 'relative/path.js': ['relative/dep.js', ...] }
  *

package/src/extractors/languages/javascript.js

@@ -38,6 +38,7 @@ module.exports = {
 
   // Expose internals for typescript.js to reuse
   _extractExpressRoutes: extractExpressRoutes,
+  _extractReactRouterRoutes: extractReactRouterRoutes,
   _extractProcessEnv: extractProcessEnv,
   _extractJSFetches: extractJSFetches,
   _extractJSFunctions: extractJSFunctions,
@@ -77,6 +78,10 @@ function extractExpressRoutes(ast, filename) {
   const nextRoutes = extractNextJSPagesRoutes(ast, filename);
   routes.push(...nextRoutes);
 
+  // React Router (JSX <Route> + createBrowserRouter/createHashRouter/createMemoryRouter)
+  const reactRoutes = extractReactRouterRoutes(ast);
+  routes.push(...reactRoutes);
+
   walk(ast, (node) => {
     if (node.type !== 'CallExpression') return;
     if (!node.callee || node.callee.type !== 'MemberExpression') return;
@@ -134,6 +139,120 @@ function extractExpressRoutes(ast, filename) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// React Router extraction
+// ---------------------------------------------------------------------------
+
+const REACT_ROUTER_CREATORS = new Set(['createBrowserRouter', 'createHashRouter', 'createMemoryRouter', 'useRoutes']);
+
+function extractReactRouterRoutes(ast) {
+  const routes = [];
+
+  // 1. JSX <Route path="..." component={X} /> or element={<X />}
+  walk(ast, (node) => {
+    if (node.type !== 'JSXOpeningElement') return;
+    if (!node.name || node.name.name !== 'Route') return;
+
+    let routePath = null;
+    let componentName = '[anonymous]';
+
+    for (const attr of (node.attributes || [])) {
+      if (attr.type !== 'JSXAttribute' || !attr.name) continue;
+      const attrName = attr.name.name;
+
+      if (attrName === 'path' && attr.value) {
+        if (attr.value.type === 'StringLiteral') {
+          routePath = attr.value.value;
+        }
+      }
+
+      if ((attrName === 'component' || attrName === 'element') && attr.value) {
+        if (attr.value.type === 'JSXExpressionContainer' && attr.value.expression) {
+          const expr = attr.value.expression;
+          if (expr.type === 'Identifier') {
+            componentName = expr.name;
+          } else if (expr.type === 'JSXElement' && expr.openingElement && expr.openingElement.name) {
+            componentName = expr.openingElement.name.name || '[anonymous]';
+          }
+        }
+      }
+    }
+
+    if (routePath !== null) {
+      routes.push({ method: 'VIEW', path: routePath, functionName: componentName });
+    }
+  });
+
+  // 2. createBrowserRouter / createHashRouter / createMemoryRouter / useRoutes
+  walk(ast, (node) => {
+    if (node.type !== 'CallExpression') return;
+    const callee = node.callee;
+    if (!callee) return;
+    const calleeName = callee.type === 'Identifier' ? callee.name
+      : (callee.type === 'MemberExpression' && callee.property) ? callee.property.name
+      : null;
+    if (!calleeName || !REACT_ROUTER_CREATORS.has(calleeName)) return;
+    if (!node.arguments || node.arguments.length === 0) return;
+
+    const firstArg = node.arguments[0];
+    if (firstArg.type === 'ArrayExpression') {
+      extractRoutesFromRouteArray(firstArg, routes);
+    }
+  });
+
+  const seen = new Set();
+  return routes.filter(r => {
+    const key = `VIEW::${r.path}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function extractRoutesFromRouteArray(arrayNode, routes) {
+  for (const element of (arrayNode.elements || [])) {
+    if (!element || element.type !== 'ObjectExpression') continue;
+    extractRouteFromRouteObject(element, routes);
+  }
+}
+
+function extractRouteFromRouteObject(objNode, routes) {
+  let routePath = null;
+  let componentName = '[anonymous]';
+  let childrenNode = null;
+
+  for (const prop of (objNode.properties || [])) {
+    if (prop.type !== 'ObjectProperty' && prop.type !== 'Property') continue;
+    if (!prop.key) continue;
+    const key = prop.key.name || prop.key.value;
+
+    if (key === 'path' && prop.value && prop.value.type === 'StringLiteral') {
+      routePath = prop.value.value;
+    }
+
+    if ((key === 'element' || key === 'component') && prop.value) {
+      const val = prop.value;
+      if (val.type === 'Identifier') {
+        componentName = val.name;
+      } else if (val.type === 'JSXElement' && val.openingElement && val.openingElement.name) {
+        componentName = val.openingElement.name.name || '[anonymous]';
+      }
+    }
+
+    if (key === 'children' && prop.value && prop.value.type === 'ArrayExpression') {
+      childrenNode = prop.value;
+    }
+  }
+
+  if (routePath !== null) {
+    routes.push({ method: 'VIEW', path: routePath, functionName: componentName });
+  }
+
+  if (childrenNode) {
+    extractRoutesFromRouteArray(childrenNode, routes);
+  }
+}
+
 /**
  * Detects Next.js Pages Router pattern:
  *   export default function handler(req, res) in files under pages/api/

package/src/extractors/routes.js

@@ -25,11 +25,12 @@ function collapseMultilineDecorators(content) {
 }
 
 /**
- * Extracts HTTP routes from FastAPI and Django files.
+ * Extracts HTTP routes from FastAPI, Flask, and Django files.
  */
 function extractRoutes(content) {
   return [
     ...extractFastAPIRoutes(content),
+    ...extractFlaskRoutes(content),
     ...extractDjangoRoutes(content),
   ];
 }
@@ -61,6 +62,45 @@ function extractFastAPIRoutes(content) {
   return routes;
 }
 
+// ─── Flask ───────────────────────────────────────────────────────────────────
+
+function extractFlaskRoutes(content) {
+  const routes = [];
+
+  if (!content.includes('.route(') && !content.includes('from flask')) return routes;
+
+  // @app.route('/path') or @bp.route('/path', methods=['GET', 'POST'])
+  // Also handles: @api.route, @blueprint.route, any @x.route pattern
+  const decoratorRe = /@\w+\.route\s*\(\s*['"]([^'"]+)['"]\s*(?:,\s*methods\s*=\s*\[([^\]]+)\])?\s*\)/g;
+  const funcRe = /(?:async\s+)?def\s+(\w+)/;
+
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    decoratorRe.lastIndex = 0;
+    const match = decoratorRe.exec(lines[i]);
+    if (!match) continue;
+
+    const routePath = match[1];
+    const methodsRaw = match[2];
+    const methods = methodsRaw
+      ? methodsRaw.split(',').map(m => m.trim().replace(/['"]/g, '').toUpperCase()).filter(Boolean)
+      : ['GET'];
+
+    let functionName = '[anonymous]';
+    for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
+      const fm = lines[j].match(funcRe);
+      if (fm) { functionName = fm[1]; break; }
+    }
+
+    for (const method of methods) {
+      routes.push({ method, path: routePath, functionName });
+    }
+  }
+
+  return routes;
+}
+
 // ─── Django ───────────────────────────────────────────────────────────────────
 
 function extractDjangoRoutes(content) {