` XML doc comments on all classes, methods, and\ninterfaces. They appear in `symbols.get_card`, `symbols.get_context`, and\n`symbols.search` results — giving agents intent and context without reading\nimplementations.\n\n**When writing C# code with CodeMap enabled, always add XML doc comments.**\nThis isn't just style — it directly improves every downstream query. Agents\nusing `graph.trace_feature` see annotated call trees that read like specs.\n`codemap.export` includes docs in the portable context for other LLMs.\n\nSee [`docs/CODEMAP-AGENT-GUIDE.MD`](https://github.com/bbajt/csharp-code-map/blob/main/docs/CODEMAP-AGENT-GUIDE.MD) for the full agent workflow guide.\n\n---\n\n## Architecture\n\n```\nYour Git repo CodeMap Server\n │ │\n │ repo_path │\n ├─────────────────────────►│ GitService (repo identity, HEAD SHA)\n │ │ │\n │ solution.sln/.slnx │ ▼\n ├─────────────────────────►│ RoslynCompiler (MSBuildWorkspace for C#/VB, FCS for F#)\n │ │ │\n │ │ ▼\n │ │ Extractors (Symbols + Refs + TypeRelations + Facts)\n │ │ │\n │ │ ▼\n │ │ CustomSymbolStore (v2 binary segments, mmap'd)\n │ │ │ ↕\n │ │ │ SharedCache (file-based, optional)\n │ │ ▼\n │ your uncommitted edits │ ▼\n ├─────────────────────────►│ OverlayStore (WAL-backed incremental overlay)\n │ │ │\n │ │ ▼\n │ │ MergedQueryEngine (baseline + overlay, transparent merge)\n │ │ │\n │ MCP tool call │ ▼\n ├─────────────────────────►│ McpServer (stdio JSON-RPC 2.0, 28 tools)\n │ │ │\n │ JSON response │ ▼\n │◄─────────────────────────│ ResponseEnvelope (answer + evidence + timing + token savings)\n```\n\n**Layer dependencies** (enforced at build time — violations are build errors):\n\n```\nCodeMap.Core ← zero dependencies (domain types + interfaces)\nCodeMap.Git ← Core (LibGit2Sharp)\nCodeMap.Roslyn ← Core (Roslyn 5.x + MSBuildWorkspace)\nCodeMap.Storage.Engine ← Core (v2 binary segments, sole engine since v2.1.0)\nCodeMap.Query ← Core + Storage.Engine (query engine + cache + overlay merge)\nCodeMap.Mcp ← Core + Query (MCP tool handlers)\nCodeMap.Daemon ← ALL (DI composition root, the executable)\n```\n\n---\n\n## Observability\n\nEvery response includes:\n- **Per-phase timing** — `cache_lookup_ms`, `db_query_ms`, `ranking_ms` (sub-millisecond on v2)\n- **Token savings** — tokens saved and cost avoided vs raw file reading\n- **Semantic level** — `Full` / `Partial` / `SyntaxOnly` (index quality signal)\n- **Overlay revision** — which workspace revision answered the query\n- **Workspace ID** — which workspace context answered (null for committed mode)\n\nStructured logs to `~/.codemap/logs/codemap-{date}.log` (daily rotation, JSON lines).\nCumulative savings to `~/.codemap/_savings.json` (persists across restarts).\nConfig at `~/.codemap/config.json` (log level, cache dir, budget overrides).\n\n### v2 Data Directory\n\nBaselines are stored in `~/.codemap/store//baselines//` as binary segment files. Overlays in `~/.codemap/store/overlays//`. Use `index.list_baselines` to inspect and `index.cleanup` to reclaim space.\n\n---\n\n## Known Limitations & Coverage Gaps\n\nCodeMap won't surface a hit in every situation a `grep` would. The most\ncommon reasons are documented in [`docs/KNOWN-LIMITATIONS.md`](https://github.com/bbajt/csharp-code-map/blob/main/docs/KNOWN-LIMITATIONS.md).\nTop items to be aware of:\n\n- **Multi-target conditional symbols.** `#if NET8_0`-only types are\n invisible — extraction runs on the highest TFM only (L-01).\n- **Legacy MVC `MapControllerRoute`** — convention-routed actions don't\n surface in `surfaces.list_endpoints`. Only attribute routing,\n minimal API, and Blazor `@page` are extracted (L-02).\n- **F# fact extractors not yet wired** — F# gets symbols/refs/hierarchy\n only; endpoints / DI / config / DB tables don't extract from `.fsproj`\n yet (L-05).\n- **Fresh clone with no build** — Razor source-generator output may be\n invisible until you `dotnet build` once (L-08).\n\nWhen `symbols.search` returns nothing for code you can see in the\neditor, scan KNOWN-LIMITATIONS first before falling back to grep.\n\n---\n\n## Documentation\n\n| Doc | What's in it |\n|-----|-------------|\n| [`docs/CLAUDE-INSERT.MD`](https://github.com/bbajt/csharp-code-map/blob/main/docs/CLAUDE-INSERT.MD) | Copy-paste block for CLAUDE.md — wires up agent to use CodeMap |\n| [`docs/CODEMAP-AGENT-GUIDE.MD`](https://github.com/bbajt/csharp-code-map/blob/main/docs/CODEMAP-AGENT-GUIDE.MD) | Full agent operating guide: startup, refresh, query patterns, common mistakes |\n| [`docs/KNOWN-LIMITATIONS.md`](https://github.com/bbajt/csharp-code-map/blob/main/docs/KNOWN-LIMITATIONS.md) | Coverage gaps and intentional non-features — what `grep` finds that CodeMap doesn't |\n| [`docs/DEVELOPER-GUIDE.MD`](https://github.com/bbajt/csharp-code-map/blob/main/docs/DEVELOPER-GUIDE.MD) | How to add tools, extractors, storage methods |\n| [`docs/ARCHITECTURE-WALKTHROUGH.MD`](https://github.com/bbajt/csharp-code-map/blob/main/docs/ARCHITECTURE-WALKTHROUGH.MD) | Request traces, data model, decision log |\n| [`docs/API-SCHEMA.MD`](https://github.com/bbajt/csharp-code-map/blob/main/docs/API-SCHEMA.MD) | Every type definition and MCP tool contract |\n| [`docs/SYSTEM-ARCHITECTURE.MD`](https://github.com/bbajt/csharp-code-map/blob/main/docs/SYSTEM-ARCHITECTURE.MD) | Component design, DB schema, query model |\n\n---\n\n## Build & Test\n\n```bash\n# Build (zero warnings enforced)\ndotnet build -warnaserror\n\n# Fast unit tests\ndotnet test --filter \"Category!=Integration&Category!=Benchmark\"\n\n# Integration tests (requires MSBuild)\ndotnet test --filter \"Category=Integration\"\n\n# Token savings benchmark\ndotnet test --filter \"Category=Benchmark\" -v normal\n\n# Performance microbenchmarks (BenchmarkDotNet)\ncd tests/CodeMap.Benchmarks && dotnet run -c Release\n```\n\n---\n\n## Performance Reference\n\nWhat to expect when running CodeMap on your codebase. All v2 engine numbers (default since v2.0.0).\n\n### Indexing time by repo size\n\n| Repo | Files | Symbols | Refs | Index time |\n|------|-------|---------|------|-----------|\n| CodeMap (self-hosted) | 585 | 6,800 | 29,200 | ~24s |\n| eShopOnWeb | 278 | — | — | ~6s |\n| dotnet/fsharp | 994 | 157,000 | 58,000 | ~131s |\n| Bitwarden | 4,466 | — | — | ~110s |\n| dotnet/roslyn | 18,799 | 174,000 | 768,000 | ~97s |\n\nSubsequent runs on the same commit return immediately (`already_existed: true`). Incremental overlay refresh (after editing files) takes **~63ms**.\n\n### Query response time (v2 engine)\n\n| Query | Cold (first hit, no L1 cache) | Warm (L1 cache) |\n|-------|------------------------------|-----------------|\n| `symbols.search` | 1–10ms | <1ms |\n| `symbols.get_card` | 2–10ms | <1ms |\n| `symbols.get_context` | 5–30ms | 1–5ms |\n| `refs.find` | 5–20ms | <1ms |\n| `graph.callers / callees` | 10–50ms | 1–5ms |\n| `graph.trace_feature` | 10–100ms | 1–10ms |\n| `types.hierarchy` | 1–5ms | <1ms |\n| `codemap.summarize` | 50–200ms | 5–20ms |\n| `surfaces.list_*` | 1–10ms | <1ms |\n| `index.diff` | 100–500ms | — |\n\nCold times scale with repo size (more symbols = more BFS/join work). Warm times are nearly flat across all repo sizes — L1 cache caps at 10,000 entries with LRU eviction.\n\n### Memory footprint (v2 engine)\n\n| Repo size | Baseline on disk | Resident memory (mmap) |\n|-----------|-----------------|----------------------|\n| Small (<1K symbols) | ~1–5 MB | ~5–20 MB |\n| Medium (10K symbols) | ~20–50 MB | ~30–80 MB |\n| Large (100K+ symbols) | ~200–500 MB | ~300–600 MB |\n\nmmap pages are demand-loaded by the OS — resident memory stays proportional to queries made, not total index size.\n\n---\n\n*28 MCP tools. 90%+ token savings. Roslyn-grade semantics. C#, VB.NET, F#, **Blazor/Razor**. DLL boundary navigation. `.sln` + `.slnx` auto-discovery. v2.5.1 — multi-target compilation collapse (one extraction per `.csproj`, not per TFM), KNOWN-LIMITATIONS register surfaced via `codemap.guide`. Validated on dotnet/roslyn (174K symbols), dotnet/fsharp (157K symbols), and a 9-repo Blazor corpus including Blazorise, MudBlazor, ant-design-blazor, OrchardCore. Your agent deserves better than grep.*\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_106":107,"_108":109,"_110":111,"_112":113,"_114":-5,"_115":116},"requiredSecrets",[],"tags",[96,97,98,99,100,101,102,103,104,105],"assets",[],"stats",{"_94":81,"_95":81},"ratingAvg","reviewCount","claude","claude-code","code-analysis","code-navigation","csharp","dotnet","fsharp","roslyn","semantic-search","vbnet","topics",[96,97,98,99,100,101,102,122,123,103,104,105],"license","NOASSERTION","language","C#","registryName","io.github.bbajt/codemap-mcp","homepage","packages",[117],{"_118":119,"_120":121,"_71":72},"registryType","nuget","identifier","codemap-mcp","mcp","mcp-server","ENV",{"_126":127,"_128":129,"_130":131},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]