carto-md 2.0.9 → 2.1.0

package/docs/api/get_service_boundary_violations.md

@@ -0,0 +1,25 @@
+# `get_service_boundary_violations`
+
+Cross-repo edges that import private/internal surface (heuristic: target path contains internal / private / _lib).
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+_None._
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_service_dependency_graph.md

@@ -0,0 +1,25 @@
+# `get_service_dependency_graph`
+
+Aggregated cross-repo graph: each repo is a node, edges grouped by (from_repo, to_repo, edge_kind).
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+_None._
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_session_context.md

@@ -0,0 +1,32 @@
+# `get_session_context`
+
+Full context for an AI session: every decision and every intervention, ordered chronologically. Use to recap what happened in a long-running session.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "session_id": {
+      "type": "number",
+      "description": "Session id. Defaults to the most recent active session."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `session_id` | number | Session id. Defaults to the most recent active session. |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_similar_patterns.md

@@ -0,0 +1,39 @@
+# `get_similar_patterns`
+
+Given a file, find structurally similar files — same import pattern, same route shape, or same domain. Use to find conventions to follow before writing new code.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file": {
+      "type": "string",
+      "description": "Relative file path from project root"
+    },
+    "limit": {
+      "type": "number",
+      "description": "Max results to return (default 5)"
+    }
+  },
+  "required": [
+    "file"
+  ]
+}
+```
+
+## Required arguments
+
+- `file`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `file` | string | Relative file path from project root |
+| `limit` | number | Max results to return (default 5) |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_stale_docs.md

@@ -0,0 +1,25 @@
+# `get_stale_docs`
+
+Docs/markdown files older than 30 days. Heuristic surface for documentation that probably needs refresh.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+_None._
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_structure.md

@@ -0,0 +1,25 @@
+# `get_structure`
+
+Get project structure: import graph, entry points, high impact files, tech stack, and domains.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+_None._
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_temporal_context.md

@@ -0,0 +1,34 @@
+# `get_temporal_context`
+
+A file's full temporal context: first_seen_ts, last_modified_ts, commit_count, blast_radius, recent events, age in days.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file": {
+      "type": "string",
+      "description": "Relative file path."
+    }
+  },
+  "required": [
+    "file"
+  ]
+}
+```
+
+## Required arguments
+
+- `file`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `file` | string | Relative file path. |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_test_coverage_map.md

@@ -0,0 +1,25 @@
+# `get_test_coverage_map`
+
+Surfaces files with no detected test alongside their blast radius. High-blast untested files are the riskiest.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+_None._
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_token_budget_report.md

@@ -0,0 +1,36 @@
+# `get_token_budget_report`
+
+Diagnostic complement to get_minimal_context_for_intent. Returns context efficiency as a fraction of repo size (used / total tokens approx).
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "intent": {
+      "type": "string",
+      "description": "Intent to budget for."
+    },
+    "budget_tokens": {
+      "type": "number"
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `intent` | string | Intent to budget for. |
+| `budget_tokens` | number |  |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_upgrade_risk.md

@@ -0,0 +1,25 @@
+# `get_upgrade_risk`
+
+Cross-references each external dep against the import graph. Returns usage count + domain count + LOW/MEDIUM/HIGH risk per dep. Use before bumping a dep version.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+_None._
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_working_memory.md

@@ -0,0 +1,25 @@
+# `get_working_memory`
+
+Live state snapshot: branch, HEAD, uncommitted files, recent decision count, open HIGH-severity warnings, recent drift. Read this at the start of every AI session.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+_None._
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/ingest_otlp_traces.md

@@ -0,0 +1,34 @@
+# `ingest_otlp_traces`
+
+Parse an OpenTelemetry OTLP JSON/JSONL trace file and aggregate per-route hit counts. Use the resulting counts with get_risk_weighted_blast_radius.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "path": {
+      "type": "string",
+      "description": "Path to OTLP file"
+    }
+  },
+  "required": [
+    "path"
+  ]
+}
+```
+
+## Required arguments
+
+- `path`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `path` | string | Path to OTLP file |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/scaffold_for_intent.md

@@ -0,0 +1,34 @@
+# `scaffold_for_intent`
+
+For a natural-language intent ("add a payment route"), returns: anchor file + co-changed files + canonical pattern + conventions to follow. Combines invariants, conventions, and procedural memory.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "intent": {
+      "type": "string",
+      "description": "Natural-language description of the change."
+    }
+  },
+  "required": [
+    "intent"
+  ]
+}
+```
+
+## Required arguments
+
+- `intent`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `intent` | string | Natural-language description of the change. |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/search_routes.md

@@ -0,0 +1,34 @@
+# `search_routes`
+
+Search API routes by path or method. Case-insensitive.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "query": {
+      "type": "string",
+      "description": "Search query e.g. \"auth\", \"POST\", \"/api/users\""
+    }
+  },
+  "required": [
+    "query"
+  ]
+}
+```
+
+## Required arguments
+
+- `query`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `query` | string | Search query e.g. "auth", "POST", "/api/users" |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/simulate_change_impact.md

@@ -0,0 +1,37 @@
+# `simulate_change_impact`
+
+Given a list of files, returns all files transitively affected by changing them simultaneously, with hop distance. Powered by the bitmap engine — only feasible at this speed (sub-millisecond) with bitmap OR-aggregation. Use when planning a refactor that touches multiple files.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Array of relative file paths from project root"
+    }
+  },
+  "required": [
+    "files"
+  ]
+}
+```
+
+## Required arguments
+
+- `files`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `files` | array | Array of relative file paths from project root |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/validate_change.md

@@ -0,0 +1,39 @@
+# `validate_change`
+
+Pre-write governance: given a file + proposed full content, synthesizes a diff vs disk and runs validate_diff. Use in IDE onWillSaveTextDocument hooks.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file": {
+      "type": "string"
+    },
+    "content": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "file",
+    "content"
+  ]
+}
+```
+
+## Required arguments
+
+- `file`
+- `content`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `file` | string |  |
+| `content` | string |  |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/validate_diff.md

@@ -0,0 +1,39 @@
+# `validate_diff`
+
+Given a unified diff, returns: violations (cross-domain imports, high-blast files), blast radius per file, risk level (SAFE/LOW/MEDIUM/HIGH), and suggestions. Sub-15ms p99 on a 7K-file repo. Each call is recorded in the episodic memory log so other tools can ask "did we discuss this?".
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "diff": {
+      "type": "string",
+      "description": "Unified diff text (output of `git diff` / GitHub PR patch)."
+    },
+    "session_id": {
+      "type": "number",
+      "description": "Optional session id. Defaults to the most recent active session, or a fresh one."
+    }
+  },
+  "required": [
+    "diff"
+  ]
+}
+```
+
+## Required arguments
+
+- `diff`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `diff` | string | Unified diff text (output of `git diff` / GitHub PR patch). |
+| `session_id` | number | Optional session id. Defaults to the most recent active session, or a fresh one. |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/concepts/anci.md

@@ -0,0 +1,87 @@
+# Concept: ANCI
+
+> **Architecturally Normalized Code Index** — the open file format for any codebase to describe its architecture to AI tools.
+
+## The problem
+
+Every AI coding tool today re-discovers a codebase's architecture from scratch on every session. Cursor builds its own embedding index. Cline builds its own. Continue builds its own. Same parsing, every tool, every session, every time. Wasted CPU; wasted disk; inconsistent results.
+
+What's missing is a *format*. OpenAPI did this for REST APIs — once any API has an `openapi.yaml`, every tool consumes it the same way. ANCI is the equivalent for codebases.
+
+## What it is
+
+Two files at `.carto/anci.{yaml,bin}`. Together they describe:
+
+- the domain partition (which files belong to which cluster)
+- the import graph (forward + reverse adjacency)
+- per-file metadata (path, language, exports)
+- popcount index (files ranked by transitive dependents)
+
+The split is hybrid by design:
+
+- **`anci.yaml`** — strict-subset YAML 1.2, human-readable, grep-able. Holds the schema version, generator info, domain names, and counts. ~1–4 KB.
+- **`anci.bin`** — binary body. Magic `0x49434E41` ("ANCI"), version byte, six sections (forward graph, reverse graph, popcount, paths, file→domain, domain names) packed via Roaring-bitmap-like compression. ~200 KB to ~5 MB depending on repo size.
+
+Why split: a 100K-file repo as pure YAML is 50–500 MB — too large for an AI tool to consume per-session. The binary section solves the size problem without sacrificing the human-readable header.
+
+## Carto is the reference implementation
+
+`carto sync` writes both files automatically on every full sync. The same data the MCP server hands the AI is what ANCI captures on disk. Any tool can consume it without speaking MCP:
+
+```js
+const { loadAnci } = require('carto-md/src/anci/consumer');
+
+const reader = loadAnci('./.carto');
+console.log(reader.domains);                                    // [{name, file_count}, ...]
+console.log(reader.getHighImpactFiles(5));                      // top 5 by transitive dependents
+console.log(reader.blastRadius('src/auth/session.ts'));         // { count, hops, files }
+console.log(reader.simulateChangeImpact([                       // multi-file change blast radius
+  'src/auth/session.ts',
+  'src/db/connection.ts',
+]));
+```
+
+`loadAnci()` has zero dependencies. Anyone shipping an AI tool can drop it in and consume Carto's index without taking on Carto's whole tarball.
+
+## The CLI surface
+
+```bash
+carto anci publish               # re-emit anci.{yaml,bin} from the current index
+carto anci show                  # human-readable summary
+carto anci validate ./.carto     # validate a published pair
+```
+
+Publish runs implicitly on `carto sync`, so you only need to invoke these manually if you're debugging.
+
+## Versioning
+
+The spec is at `docs/anci/v0.1-DRAFT.md`. It's a draft; the wire format may break between v0.1.x patches. v1.0+ will follow semver and consumers refusing unsupported major versions is the contract.
+
+The header version is what consumers look at first:
+
+```yaml
+anci:
+  version: "0.1.0-DRAFT"
+  generator: "carto-md@2.0.9"
+  generated_at: "2026-06-26T12:34:56Z"
+```
+
+A consumer should reject anything outside its supported major.minor prefix.
+
+## Why publish a spec at all
+
+If only Carto consumes Carto's binary format, it's just an internal optimization. If three AI tools agree on a format, it becomes the standard. The OpenAPI precedent: Swagger shipped as a proprietary format in 2011, became de-facto by 2014, formalized as the OpenAPI Initiative by 2016.
+
+Carto's bet is the same: publish the binary spec early, support it as the reference implementation, and let the ecosystem coalesce. Once 3+ AI tools read ANCI, every AI tool has to.
+
+## Status
+
+- Spec: v0.1 DRAFT, published in [`docs/anci/v0.1-DRAFT.md`](../anci/v0.1-DRAFT.md)
+- Carto generates the files on every `carto sync`
+- Consumer library shipped: `src/anci/consumer.js`
+- Partner integration: TBD — first one is the unblocker
+
+## Related
+
+- [`docs/anci/v0.1-DRAFT.md`](../anci/v0.1-DRAFT.md) — the spec itself
+- [`mcp-integration.md`](./mcp-integration.md) — the alternative consumption path (live, slightly more flexible, but every consumer pays the MCP-protocol surface tax)