carto-md 2.0.9 → 2.1.1

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/history.md

@@ -0,0 +1,78 @@
+# `history`
+
+Temporal/architectural history: domain drift (default), domain evolution, hotspots, arch events, a file's timeline, change velocity, complexity trend, churn-vs-blast, domain health. Requires `carto temporal init`.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "view": {
+      "type": "string",
+      "enum": [
+        "drift",
+        "evolution",
+        "hotspots",
+        "events",
+        "file",
+        "velocity",
+        "complexity",
+        "churn",
+        "health"
+      ],
+      "description": "Which historical view to return (default drift)."
+    },
+    "domain": {
+      "type": "string",
+      "description": "Domain filter (drift/evolution/health)."
+    },
+    "file": {
+      "type": "string",
+      "description": "File (file/complexity views)."
+    },
+    "time_range": {
+      "type": "string",
+      "description": "Window like \"30d\", \"90d\"."
+    },
+    "limit": {
+      "type": "number",
+      "description": "Row cap (hotspots)."
+    },
+    "severity": {
+      "type": "string",
+      "description": "Event severity (events)."
+    },
+    "kind": {
+      "type": "string",
+      "description": "Event kind (events)."
+    },
+    "days": {
+      "type": "number",
+      "description": "Lookback days (velocity)."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `view` | string | Which historical view to return (default drift). |
+| `domain` | string | Domain filter (drift/evolution/health). |
+| `file` | string | File (file/complexity views). |
+| `time_range` | string | Window like "30d", "90d". |
+| `limit` | number | Row cap (hotspots). |
+| `severity` | string | Event severity (events). |
+| `kind` | string | Event kind (events). |
+| `days` | number | Lookback days (velocity). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/impact.md

@@ -0,0 +1,56 @@
+# `impact`
+
+Impact of changing code: blast radius (default), multi-file simulate, import neighbors, or data flow. Signature capability — "what breaks if I touch this?"
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file": {
+      "type": "string",
+      "description": "Relative file path (modes: blast, neighbors, data_flow)."
+    },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "File paths for mode=\"simulate\" (change a set at once)."
+    },
+    "mode": {
+      "type": "string",
+      "enum": [
+        "blast",
+        "simulate",
+        "neighbors",
+        "data_flow"
+      ],
+      "description": "blast=transitive dependents (default); simulate=union for a file set; neighbors=import graph neighbors; data_flow=upstream/downstream + routes/models/env."
+    },
+    "hops": {
+      "type": "number",
+      "description": "Neighbor hops (mode=\"neighbors\", default 1, max 3)."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `file` | string | Relative file path (modes: blast, neighbors, data_flow). |
+| `files` | array | File paths for mode="simulate" (change a set at once). |
+| `mode` | string | blast=transitive dependents (default); simulate=union for a file set; neighbors=import graph neighbors; data_flow=upstream/downstream + routes/models/env. |
+| `hops` | number | Neighbor hops (mode="neighbors", default 1, max 3). |
+
+## 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/memory.md

@@ -0,0 +1,70 @@
+# `memory`
+
+Episodic memory: search past decisions (default), decision log, recent decisions, session recap, pending work, or a file's intervention history. Ask "did we already decide this?"
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "kind": {
+      "type": "string",
+      "enum": [
+        "search",
+        "log",
+        "recent",
+        "session",
+        "pending",
+        "interventions"
+      ],
+      "description": "search=substring over the log (default); log=recent decision log; recent=validation decisions; session=full session recap; pending=unfinished/HIGH-risk work; interventions=warnings on a file."
+    },
+    "query": {
+      "type": "string",
+      "description": "Search topic (kind=\"search\")."
+    },
+    "file": {
+      "type": "string",
+      "description": "File filter (kind=\"interventions\")."
+    },
+    "hours": {
+      "type": "number",
+      "description": "Lookback hours (kind=\"log\"/\"pending\")."
+    },
+    "time_range": {
+      "type": "string",
+      "description": "Window like \"7d\" (kind=\"recent\")."
+    },
+    "filter": {
+      "type": "string",
+      "description": "Decision-kind filter (kind=\"recent\")."
+    },
+    "session_id": {
+      "type": "number",
+      "description": "Session id (kind=\"session\")."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `kind` | string | search=substring over the log (default); log=recent decision log; recent=validation decisions; session=full session recap; pending=unfinished/HIGH-risk work; interventions=warnings on a file. |
+| `query` | string | Search topic (kind="search"). |
+| `file` | string | File filter (kind="interventions"). |
+| `hours` | number | Lookback hours (kind="log"/"pending"). |
+| `time_range` | string | Window like "7d" (kind="recent"). |
+| `filter` | string | Decision-kind filter (kind="recent"). |
+| `session_id` | number | Session id (kind="session"). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/org.md

@@ -0,0 +1,51 @@
+# `org`
+
+Cross-repo / multi-repo view: org architecture (default), service dependency graph, cross-repo blast radius, API consumers, per-repo domains, boundary violations, or migration cut points. Requires `carto org init`.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "view": {
+      "type": "string",
+      "enum": [
+        "architecture",
+        "graph",
+        "blast",
+        "consumers",
+        "domains",
+        "violations",
+        "migration"
+      ],
+      "description": "Which org-wide view to return (default architecture)."
+    },
+    "repo": {
+      "type": "string",
+      "description": "Producer repo (view=\"blast\")."
+    },
+    "target": {
+      "type": "string",
+      "description": "Package/module (view=\"consumers\")."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `view` | string | Which org-wide view to return (default architecture). |
+| `repo` | string | Producer repo (view="blast"). |
+| `target` | string | Package/module (view="consumers"). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/patterns.md

@@ -0,0 +1,63 @@
+# `patterns`
+
+Semantic + procedural patterns mined from the repo: architectural invariants (default), naming/export/dir conventions, canonical exemplar, or "when X changes, Y changes" action patterns.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "kind": {
+      "type": "string",
+      "enum": [
+        "invariants",
+        "conventions",
+        "canonical",
+        "actions"
+      ],
+      "description": "invariants=mined rules (default); conventions=naming/export/dir; canonical=best exemplar; actions=git co-change patterns."
+    },
+    "domain": {
+      "type": "string",
+      "description": "Domain filter (invariants/canonical)."
+    },
+    "threshold": {
+      "type": "number",
+      "description": "Confidence threshold (invariants)."
+    },
+    "file": {
+      "type": "string",
+      "description": "File or directory (conventions)."
+    },
+    "pattern_type": {
+      "type": "string",
+      "description": "route_handler | model_definition (canonical)."
+    },
+    "intent": {
+      "type": "string",
+      "description": "Intent filter (actions)."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `kind` | string | invariants=mined rules (default); conventions=naming/export/dir; canonical=best exemplar; actions=git co-change patterns. |
+| `domain` | string | Domain filter (invariants/canonical). |
+| `threshold` | number | Confidence threshold (invariants). |
+| `file` | string | File or directory (conventions). |
+| `pattern_type` | string | route_handler \| model_definition (canonical). |
+| `intent` | string | Intent filter (actions). |
+
+## 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/set_intent.md

@@ -0,0 +1,45 @@
+# `set_intent`
+
+Capture a user-stated intent about this project — product type, stack, or a scope note ("single-user for now"). Product-type gates every rule in the rule engine, so calling this correctly is how the AI unlocks (or narrows) gap detection. Notes accumulate — this tool never overwrites prior notes, only appends.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "product_type": {
+      "type": "string",
+      "description": "The product classification, e.g. \"saas-with-auth\" or \"unsupported\"."
+    },
+    "stack": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Optional explicit stack list, e.g. [\"Next.js\", \"Supabase\"]. Replaces the auto-detected stack."
+    },
+    "note": {
+      "type": "string",
+      "description": "A single scope statement from the user. Timestamped and appended to the notes array."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `product_type` | string | The product classification, e.g. "saas-with-auth" or "unsupported". |
+| `stack` | array | Optional explicit stack list, e.g. ["Next.js", "Supabase"]. Replaces the auto-detected stack. |
+| `note` | string | A single scope statement from the user. Timestamped and appended to the notes array. |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/simulate_change_impact.md

@@ -0,0 +1,39 @@
+# `simulate_change_impact`
+
+> ⚠️ **Deprecated (CF-7).** Use `impact(files, mode="simulate")` instead. This name still resolves and returns byte-identical output for a deprecation window, but is no longer listed by default and emits a one-line notice.
+
+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)