cartograph AGENTS.md

AGENTS.md — install and use Cartograph v2 from an AI coding agent

Cartograph is this workspace's native code-intelligence MCP server. These instructions are deliberately mechanical: execute a step, verify its result, then continue.

Working on the Cartograph repository itself? Read AGENTS.local.md before changing code. It contains the private development conventions, architecture gates, Sonar workflow, reviewer step, and release procedure. A fresh public clone does not contain that git-ignored file.

Existing project rule

If .cartograph/ or a project-local Cartograph MCP registration exists, use Cartograph for relationship-aware exploration:

• cartograph context for broad coding-task evidence;
• cartograph find for exact name/path/reference or BM25 lookup;
• cartograph graph for callers, callees, and reverse impact;
• cartograph affected for test selection;
• cartograph review for compare-to-ref and dirty-worktree evidence;
• cartograph status before relying on the index.

If the index is stale, run cartograph index <project> or call the MCP cartograph_admin index action. Do not present stale evidence as current.

If the project has no Cartograph setup, ask:

I notice this project does not have Cartograph initialized. Would you like me to start its PostgreSQL/ParadeDB database, index it, and add project-local MCP configuration?

Architecture and hard requirements

Cartograph v2 is:

• a native Rust executable;
• PostgreSQL 18.4 or newer within major version 18;
• code-aware BM25 through ParadeDB pg_search 0.25.3;
• pgvector 0.8.4 or newer (0.8.6 recommended for external PostgreSQL; the managed ParadeDB 0.25.3 image bundles pg_search 0.25.3 and pgvector 0.8.4);
• useful without an LLM through exact, lexical, graph, review, and test-impact retrieval.

There is no SQLite runtime, importer, optional feature, or fallback. Never recommend SQLite for v2 and never attempt to open an old SQLite graph.

Step 0 — install the binary