carto-md 1.1.2 → 1.1.3

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, Pydantic, SQLAlchemy, Django (models + URLs)
+- **Go**: Gin, Echo, Chi, net/http
+- **Schema**: Prisma
+- **Frontend**: HTML fetch()
+- **R**: Plumber, Shiny, R6, S7
 
-Wanted: Django, Rails, Laravel, NestJS, Hono, Gin, Spring.
+Wanted: Rails, Laravel, NestJS, Hono, Spring, Flask, 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
@@ -96,7 +109,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 +118,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,332 @@
 [![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)
 
-`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.
+Fresh `carto init`. No prior knowledge of the repo.
 
-**Carto makes it live. And queryable.**
+```
+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:
+
+```
+packages/ui/src/lib/utils/cn.ts updated
 
-| | 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 |
+Re-indexed in 129ms.
+
+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
+```
+
+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 |
+
+**With Carto:** Correct route, correct handler, correct file, all 35+ fields. One shot. Zero follow-ups.
 
-**4 wrong file paths → 0. 20 missing fields → 0. Zero follow-up clarifications.**
+**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, Express, Next.js App/Pages Router, React Router (JSX + createBrowserRouter), tRPC procedures, Django URLs, Gin/Echo (Go) |
+| **Models** | Prisma, Pydantic, SQLAlchemy, Django ORM, TypeScript interfaces/types, Zod schemas, Drizzle tables |
+| **Graph** | Full import graph: who imports what, transitive dependencies up to 5 hops |
+| **Blast radius** | Risk level (HIGH/MEDIUM/LOW) per file and per route |
+| **Domains** | AUTH, PAYMENTS, DATABASE, EVENTS, TRPC, NOTIFICATIONS, CORE, auto-clustered from imports |
+| **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, Pydantic, SQLAlchemy, Django |
+| Go | Gin, Echo, Chi, net/http |
+| 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"
-    }
-  }
-}
-```
+---
 
-**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "carto": {
-      "command": "carto",
-      "args": ["serve"],
-      "cwd": "/path/to/your/project"
-    }
-  }
-}
-```
+## Commands
 
-Then run `carto serve` in your project directory alongside `carto watch`.
+| 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 |
 
 ---
 
-## Domain context files
-
-Large codebases kill AI accuracy. A 2900-line AGENTS.md means AI reads 500 lines and guesses the rest.
+## `carto check`
 
-Carto splits context by domain automatically:
+Run before committing. Tells you what's risky before you push.
 
 ```
-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.
+  Files indexed : 310
+  Routes found  : 104
+  Import edges  : 5,248
+  Domains       : AUTH · DATABASE · PAYMENTS · EVENTS · CORE
 
-Domain assignment uses your import graph — files that import each other cluster together, regardless of folder names.
+  ⚠️  High-risk uncommitted changes (1):
+     🔴 src/lib/auth.service.ts
+        11 files depend on this, blast risk: HIGH
 
----
-
-## Know what breaks before you break it
+  ✅ No cross-domain dependency violations
 
-```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
+  🔥 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
 ```
 
-No AI. No cloud. Runs in under a second. From your live import graph.
-
 ---
 
-## 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 +337,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.3",
   "description": "The context layer for AI-native development.",
   "bin": {
     "carto": "src/cli/index.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/