docs: add Titan Paradigm use case, update docs with roles/co-change/path

- Create docs/use-cases/titan-paradigm.md — maps Johannes R.'s multi-agent
  codebase cleanup architecture (RECON, GAUNTLET, GLOBAL SYNC, STATE MACHINE)
  to codegraph commands, roadmap items, and post-LLM-integration recommendations

- Update roadmap/BACKLOG.md: mark #4 (node classification), #9 (git change
  coupling), #1 (dead code), #2 (shortest path), #12 (execution flow) as DONE;
  add 6 new Titan Paradigm-inspired items (#21-#26): composite audit, batch
  querying, triage priority queue, change validation predicates, graph
  snapshots, MCP orchestration tools

- Update README.md: add roles + co-change to features table, differentiators,
  commands section, agent template, common flags, comparison table; update MCP
  tool count 18 → 19

- Update docs/recommended-practices.md: update MCP tool count and tool list,
  add roles/co-change/path to CLAUDE.md template and developer workflow, add
  "Understand architectural roles" and "Surface hidden coupling" sections,
  add co-change step to setup checklist

- Add full examples with real output for roles, co-change, and path to
  docs/examples/CLI.md and docs/examples/MCP.md

- Update GitHub repo description with new capabilities

Author: github-actions[bot]

README.md

@@ -319,7 +319,7 @@ codegraph registry remove <name>  # Unregister
 | Flag | Description |
 |---|---|
 | `-d, --db <path>` | Custom path to `graph.db` |
-| `-T, --no-tests` | Exclude `.test.`, `.spec.`, `__test__` files (available on `fn`, `fn-impact`, `path`, `context`, `explain`, `where`, `diff-impact`, `search`, `map`, `hotspots`, `deps`, `impact`) |
+| `-T, --no-tests` | Exclude `.test.`, `.spec.`, `__test__` files (available on `fn`, `fn-impact`, `path`, `context`, `explain`, `where`, `diff-impact`, `search`, `map`, `hotspots`, `roles`, `co-change`, `deps`, `impact`) |
 | `--depth <n>` | Transitive trace depth (default varies by command) |
 | `-j, --json` | Output as JSON |
 | `-v, --verbose` | Enable debug output |
@@ -467,6 +467,9 @@ This project uses codegraph. The database is at `.codegraph/graph.db`.
 - `codegraph fn <name> -T` — function call chain
 - `codegraph path <from> <to> -T` — shortest call path between two symbols
 - `codegraph deps <file>` — file-level dependencies
+- `codegraph roles --role dead -T` — find dead code (unreferenced symbols)
+- `codegraph roles --role core -T` — find core symbols (high fan-in)
+- `codegraph co-change <file>` — files that historically change together
 - `codegraph search "<query>"` — semantic search (requires `codegraph embed`)
 - `codegraph cycles` — check for circular dependencies
 

docs/examples/CLI.md

@@ -620,6 +620,192 @@ Codegraph Diagnostics
 
 ---
 
+## roles — Node role classification
+
+```bash
+codegraph roles -T
+```
+
+```
+Node roles (639 symbols):
+
+  core: 168  utility: 285  entry: 29  dead: 137  leaf: 20
+
+## core (168)
+  f safePath           src/queries.js:14
+  f isTestFile         src/queries.js:21
+  f getClassHierarchy  src/queries.js:76
+  f findMatchingNodes  src/queries.js:127
+  f kindIcon           src/queries.js:175
+  ...
+```
+
+Filter by role and file:
+
+```bash
+codegraph roles --role dead -T
+```
+
+```
+Node roles (137 symbols):
+
+  dead: 137
+
+## dead (137)
+  f main                 crates/codegraph-core/build.rs:3
+  - TarjanState          crates/codegraph-core/src/cycles.rs:38
+  - CSharpExtractor      crates/codegraph-core/src/extractors/csharp.rs:6
+  o CSharpExtractor.extract  crates/codegraph-core/src/extractors/csharp.rs:9
+  ...
+```
+
+```bash
+codegraph roles --role entry -T
+```
+
+```
+Node roles (29 symbols):
+
+  entry: 29
+
+## entry (29)
+  f command:build        src/cli.js:89
+  f command:query        src/cli.js:102
+  f command:impact       src/cli.js:113
+  f command:map          src/cli.js:125
+  f command:stats        src/cli.js:139
+  ...
+```
+
+```bash
+codegraph roles --role core --file src/queries.js
+```
+
+```
+Node roles (16 symbols):
+
+  core: 16
+
+## core (16)
+  f safePath             src/queries.js:14
+  f isTestFile           src/queries.js:21
+  f getClassHierarchy    src/queries.js:76
+  f resolveMethodViaHierarchy  src/queries.js:97
+  f findMatchingNodes    src/queries.js:127
+  f kindIcon             src/queries.js:175
+  f moduleMapData        src/queries.js:310
+  f diffImpactMermaid    src/queries.js:766
+  ...
+```
+
+---
+
+## co-change — Git co-change analysis
+
+First, scan git history:
+
+```bash
+codegraph co-change --analyze
+```
+
+```
+Co-change analysis complete: 173 pairs from 289 commits (since: 1 year ago)
+```
+
+Then query globally or per file:
+
+```bash
+codegraph co-change
+```
+
+```
+Top co-change pairs:
+
+  100%     3 commits  src/extractors/csharp.js  <->  src/extractors/go.js
+  100%     3 commits  src/extractors/csharp.js  <->  src/extractors/java.js
+  100%     3 commits  src/extractors/csharp.js  <->  src/extractors/php.js
+  100%     3 commits  src/extractors/csharp.js  <->  src/extractors/ruby.js
+  100%     3 commits  src/extractors/go.js      <->  src/extractors/java.js
+  ...
+
+  Analyzed: 2026-02-26 | Window: 1 year ago
+```
+
+```bash
+codegraph co-change src/queries.js
+```
+
+```
+Co-change partners for src/queries.js:
+
+   43%    12 commits  src/mcp.js
+
+  Analyzed: 2026-02-26 | Window: 1 year ago
+```
+
+```bash
+codegraph co-change --min-jaccard 0.5 --min-support 5
+```
+
+```
+Top co-change pairs:
+
+  100%     5 commits  src/parser.js  <->  src/constants.js
+   78%     7 commits  src/builder.js  <->  src/resolve.js
+
+  Analyzed: 2026-02-26 | Window: 1 year ago
+```
+
+---
+
+## path — Shortest path between two symbols
+
+```bash
+codegraph path buildGraph resolveImports -T
+```
+
+```
+Path: buildGraph → resolveImports (1 hop)
+
+  buildGraph  src/builder.js:335  →(calls)→  resolveImports  src/resolve.js:42
+
+  Hops: 1 | Alternate paths: 0
+```
+
+```bash
+codegraph path buildGraph isTestFile -T
+```
+
+```
+Path: buildGraph → isTestFile (2 hops)
+
+  buildGraph      src/builder.js:335
+    →(calls)→  collectFiles  src/builder.js:45
+    →(calls)→  isTestFile    src/queries.js:21
+
+  Hops: 2 | Alternate paths: 1
+```
+
+```bash
+codegraph path buildGraph isTestFile -T --json
+```
+
+```json
+{
+  "from": "buildGraph",
+  "to": "isTestFile",
+  "hops": 2,
+  "path": [
+    { "name": "buildGraph", "file": "src/builder.js", "line": 335 },
+    { "name": "collectFiles", "file": "src/builder.js", "line": 45, "edgeKind": "calls" },
+    { "name": "isTestFile", "file": "src/queries.js", "line": 21, "edgeKind": "calls" }
+  ],
+  "alternatePaths": 1
+}
+```
+
+---
+
 ## registry — Multi-repo management
 
 ```bash

docs/examples/MCP.md

@@ -583,6 +583,155 @@ graph LR
 
 ---
 
+## node_roles — Node role classification
+
+```json
+{
+  "tool": "node_roles",
+  "arguments": { "no_tests": true }
+}
+```
+
+```
+Node roles (639 symbols):
+
+  core: 168  utility: 285  entry: 29  dead: 137  leaf: 20
+
+## core (168)
+  f safePath           src/queries.js:14
+  f isTestFile         src/queries.js:21
+  f getClassHierarchy  src/queries.js:76
+  ...
+
+## entry (29)
+  f command:build      src/cli.js:89
+  f command:query      src/cli.js:102
+  ...
+```
+
+Filter by role:
+
+```json
+{
+  "tool": "node_roles",
+  "arguments": { "role": "dead", "no_tests": true }
+}
+```
+
+```
+Node roles (137 symbols):
+
+  dead: 137
+
+## dead (137)
+  f main                 crates/codegraph-core/build.rs:3
+  - TarjanState          crates/codegraph-core/src/cycles.rs:38
+  - CSharpExtractor      crates/codegraph-core/src/extractors/csharp.rs:6
+  ...
+```
+
+Filter by role and file:
+
+```json
+{
+  "tool": "node_roles",
+  "arguments": { "role": "core", "file": "src/queries.js" }
+}
+```
+
+```
+Node roles (16 symbols):
+
+  core: 16
+
+## core (16)
+  f safePath             src/queries.js:14
+  f isTestFile           src/queries.js:21
+  f getClassHierarchy    src/queries.js:76
+  f resolveMethodViaHierarchy  src/queries.js:97
+  f findMatchingNodes    src/queries.js:127
+  ...
+```
+
+---
+
+## co_changes — Git co-change analysis
+
+Query top co-changing file pairs:
+
+```json
+{
+  "tool": "co_changes",
+  "arguments": { "no_tests": true }
+}
+```
+
+```
+Top co-change pairs:
+
+  100%     3 commits  src/extractors/csharp.js  <->  src/extractors/go.js
+  100%     3 commits  src/extractors/csharp.js  <->  src/extractors/java.js
+  100%     3 commits  src/extractors/go.js      <->  src/extractors/java.js
+  ...
+
+  Analyzed: 2026-02-26 | Window: 1 year ago
+```
+
+Query co-change partners for a specific file:
+
+```json
+{
+  "tool": "co_changes",
+  "arguments": { "file": "src/queries.js" }
+}
+```
+
+```
+Co-change partners for src/queries.js:
+
+   43%    12 commits  src/mcp.js
+
+  Analyzed: 2026-02-26 | Window: 1 year ago
+```
+
+---
+
+## symbol_path — Shortest path between two symbols
+
+```json
+{
+  "tool": "symbol_path",
+  "arguments": { "from": "buildGraph", "to": "resolveImports", "no_tests": true }
+}
+```
+
+```
+Path: buildGraph → resolveImports (1 hop)
+
+  buildGraph  src/builder.js:335  →(calls)→  resolveImports  src/resolve.js:42
+
+  Hops: 1 | Alternate paths: 0
+```
+
+```json
+{
+  "tool": "symbol_path",
+  "arguments": { "from": "buildGraph", "to": "isTestFile", "no_tests": true }
+}
+```
+
+```
+Path: buildGraph → isTestFile (2 hops)
+
+  buildGraph      src/builder.js:335
+    →(calls)→  collectFiles  src/builder.js:45
+    →(calls)→  isTestFile    src/queries.js:21
+
+  Hops: 2 | Alternate paths: 1
+```
+
+---
+
 ## list_repos — Multi-repo registry (multi-repo mode only)
 
 Only available when the MCP server is started with `--multi-repo`.