docs: complexity, communities, manifesto across all docs (#144)

* fix: strict type validation for threshold values in complexity queries

Replace loose `!= null` checks with `typeof === 'number' && Number.isFinite()`
to prevent `Number("")`, `Number(null)`, and `Number(true)` from silently
coercing into valid SQL values. Add integration test verifying exceeds
arrays and summary.aboveWarn are correctly computed.

Addresses Greptile review feedback on #136.

Impact: 2 functions changed, 3 affected

* docs: add complexity, communities, and manifesto to all docs

Update README, CLAUDE.md, BACKLOG, titan-paradigm, recommended-practices,
and CLI/MCP examples to reflect today's merged PRs: complexity metrics
(#130/#139), Louvain community detection (#133/#134), and manifesto rule
engine (#138). Updates MCP tool count from 21 to 24 (25 in multi-repo),
marks backlog items 6/11/21/22 as done, and adds real CLI output examples.

* fix: remove redundant condition in paginate guard clauses

When limit === undefined, limit !== 0 is always true — the && check
was dead code. Simplified to just check limit === undefined.

Impact: 2 functions changed, 18 affected

* docs: update dogfood report with fix statuses

All 4 bugs now fixed (PR #117 merged, #116 closed via reverse-dep
cascade). 3 of 4 suggestions addressed. MCP tool counts updated
18→23 / 19→24. Rating upgraded 7/10 → 9/10 post-fix.

* fix: rename misleading test to match actual behavior

Test was named "handles non-numeric thresholds gracefully" but only
validated baseline exceeds/aboveWarn with valid thresholds. Actual
non-numeric threshold tests exist separately. Renamed to "produces
correct exceeds and aboveWarn with valid thresholds".

* fix: update stale MCP tool count in dogfood skill (21→24)

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: carlos-alm

.claude/skills/dogfood/SKILL.md

@@ -203,7 +203,7 @@ Before writing the report, **stop and think** about:
 
 - What testing approaches am I missing?
 - **Cross-command pipelines:** Have I tested `build` → `embed` → `search` → modify → `build` → `search`? Have I tested `watch` detecting changes then `diff-impact`?
-- **MCP server:** Have I tested the `mcp` command? Initialize via JSON-RPC on stdin, send `tools/list`, verify all 21 tools are present. Test single-repo mode (default — `list_repos` should be absent, no `repo` parameter on tools) vs `--multi-repo` mode.
+- **MCP server:** Have I tested the `mcp` command? Initialize via JSON-RPC on stdin, send `tools/list`, verify all 24 tools are present (23 in single-repo mode; 24 with `list_repos` in multi-repo). Test single-repo mode (default — `list_repos` should be absent, no `repo` parameter on tools) vs `--multi-repo` mode.
 - **Programmatic API:** Have I tested `require('@optave/codegraph')` or `import` from `index.js`? Key exports to verify: `buildGraph`, `loadConfig`, `openDb`, `findDbPath`, `contextData`, `explainData`, `whereData`, `fnDepsData`, `diffImpactData`, `statsData`, `isNativeAvailable`, `EXTENSIONS`, `IGNORE_DIRS`, `ALL_SYMBOL_KINDS`, `MODELS`.
 - **Config options:** Have I tested `.codegraphrc.json`? Create one with `include`/`exclude` patterns, custom `aliases`, `build.incremental: false`, `query.defaultDepth`, `search.defaultMinScore`. Verify overrides work.
 - **Env var overrides:** `CODEGRAPH_LLM_PROVIDER`, `CODEGRAPH_LLM_API_KEY`, `CODEGRAPH_LLM_MODEL`, `CODEGRAPH_REGISTRY_PATH`.

CLAUDE.md

@@ -56,6 +56,10 @@ JS source is plain JavaScript (ES modules) in `src/`. No transpilation step. The
 | `native.js` | Native napi-rs addon loader with WASM fallback |
 | `registry.js` | Global repo registry (`~/.codegraph/registry.json`) for multi-repo MCP |
 | `resolve.js` | Import resolution (supports native batch mode) |
+| `complexity.js` | Cognitive, cyclomatic, Halstead, MI computation from AST; `complexity` CLI command |
+| `communities.js` | Louvain community detection, drift analysis |
+| `manifesto.js` | Configurable rule engine with warn/fail thresholds; CI gate |
+| `paginate.js` | Pagination helpers for bounded query results |
 | `logger.js` | Structured logging (`warn`, `debug`, `info`, `error`) |
 
 **Key design decisions:**
@@ -71,7 +75,7 @@ JS source is plain JavaScript (ES modules) in `src/`. No transpilation step. The
 - **MCP single-repo isolation:** `startMCPServer` defaults to single-repo mode — tools have no `repo` property and `list_repos` is not exposed. Passing `--multi-repo` or `--repos` to the CLI (or `options.multiRepo` / `options.allowedRepos` programmatically) enables multi-repo access. `buildToolList(multiRepo)` builds the tool list dynamically; the backward-compatible `TOOLS` export equals `buildToolList(true)`
 - **Credential resolution:** `loadConfig` pipeline is `mergeConfig → applyEnvOverrides → resolveSecrets`. The `apiKeyCommand` config field shells out to an external secret manager via `execFileSync` (no shell). Priority: command output > env var > file config > defaults. On failure, warns and falls back gracefully
 
-**Database:** SQLite at `.codegraph/graph.db` with tables: `nodes`, `edges`, `metadata`, `embeddings`
+**Database:** SQLite at `.codegraph/graph.db` with tables: `nodes`, `edges`, `metadata`, `embeddings`, `function_complexity`
 
 ## Test Structure
 
@@ -118,6 +122,9 @@ node src/cli.js stats                # Graph health and quality score
 node src/cli.js fn <name> -T         # Function call chain (callers + callees)
 node src/cli.js deps src/<file>.js   # File-level imports and importers
 node src/cli.js diff-impact main     # Impact of current branch vs main
+node src/cli.js complexity -T         # Per-function complexity metrics
+node src/cli.js communities -T       # Community detection & drift analysis
+node src/cli.js manifesto -T         # Rule engine pass/fail check
 node src/cli.js cycles               # Check for circular dependencies
 node src/cli.js search "<query>"     # Semantic search (requires `embed` first)
 ```

README.md

@@ -55,7 +55,7 @@ cd your-project
 codegraph build
 ```
 
-That's it. No config files, no Docker, no JVM, no API keys, no accounts. The graph is ready to query. Add `codegraph mcp` to your AI agent's config and it has full access to your dependency graph through 21 MCP tools (22 in multi-repo mode).
+That's it. No config files, no Docker, no JVM, no API keys, no accounts. The graph is ready to query. Add `codegraph mcp` to your AI agent's config and it has full access to your dependency graph through 24 MCP tools (25 in multi-repo mode).
 
 ### Why it matters
 
@@ -97,7 +97,7 @@ That's it. No config files, no Docker, no JVM, no API keys, no accounts. The gra
 | **🔓** | **Zero-cost core, LLM-enhanced when you want** | Full graph analysis with no API keys, no accounts, no cost. Optionally bring your own LLM provider — your code only goes where you choose |
 | **🔬** | **Function-level, not just files** | Traces `handleAuth()` → `validateToken()` → `decryptJWT()` and shows 14 callers across 9 files break if `decryptJWT` changes |
 | **🏷️** | **Role classification** | Every symbol auto-tagged as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` — agents instantly know what they're looking at |
-| **🤖** | **Built for AI agents** | 21-tool [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly. Single-repo by default |
+| **🤖** | **Built for AI agents** | 24-tool [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly. Single-repo by default |
 | **🌐** | **Multi-language, one CLI** | JS/TS + Python + Go + Rust + Java + C# + PHP + Ruby + HCL in a single graph |
 | **💥** | **Git diff impact** | `codegraph diff-impact` shows changed functions, their callers, and full blast radius — enriched with historically coupled files from git co-change analysis. Ships with a GitHub Actions workflow |
 | **🧠** | **Semantic search** | Local embeddings by default, LLM-powered when opted in — multi-query with RRF ranking via `"auth; token; JWT"` |
@@ -144,7 +144,7 @@ After modifying code:
 Or connect directly via MCP:
 
 ```bash
-codegraph mcp          # 21-tool MCP server — AI queries the graph directly
+codegraph mcp          # 24-tool MCP server — AI queries the graph directly
 ```
 
 Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) · [CLAUDE.md template](docs/guides/ai-agent-guide.md#claudemd-template)
@@ -170,8 +170,11 @@ Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) · [CLAU
 | 📤 | **Export** | DOT (Graphviz), Mermaid, and JSON graph export |
 | 🧠 | **Semantic search** | Embeddings-powered natural language search with multi-query RRF ranking |
 | 👀 | **Watch mode** | Incrementally update the graph as files change |
-| 🤖 | **MCP server** | 21-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
+| 🤖 | **MCP server** | 24-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
 | ⚡ | **Always fresh** | Three-tier incremental detection — sub-second rebuilds even on large codebases |
+| 🧮 | **Complexity metrics** | Cognitive, cyclomatic, nesting depth, Halstead, and Maintainability Index per function |
+| 🏘️ | **Community detection** | Louvain clustering to discover natural module boundaries and architectural drift |
+| 📜 | **Manifesto rule engine** | Configurable pass/fail rules with warn/fail thresholds for CI gates (exit code 1 on fail) |
 
 See [docs/examples](docs/examples) for real-world CLI and MCP usage examples.
 
@@ -250,6 +253,20 @@ codegraph hotspots             # Files with extreme fan-in, fan-out, or density
 codegraph hotspots --metric coupling --level directory --no-tests
 ```
 
+### Code Health & Architecture
+
+```bash
+codegraph complexity              # Per-function cognitive, cyclomatic, nesting, MI
+codegraph complexity --health -T  # Full Halstead health view (volume, effort, bugs, MI)
+codegraph complexity --sort mi -T # Sort by worst maintainability index
+codegraph complexity --above-threshold -T  # Only functions exceeding warn thresholds
+codegraph communities             # Louvain community detection — natural module boundaries
+codegraph communities --drift -T  # Drift analysis only — split/merge candidates
+codegraph communities --functions # Function-level community detection
+codegraph manifesto               # Pass/fail rule engine (exit code 1 on fail)
+codegraph manifesto -T            # Exclude test files from rule evaluation
+```
+
 ### Export & Visualization
 
 ```bash
@@ -319,7 +336,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`, `roles`, `co-change`, `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`, `complexity`, `communities`, `manifesto`) |
 | `--depth <n>` | Transitive trace depth (default varies by command) |
 | `-j, --json` | Output as JSON |
 | `-v, --verbose` | Enable debug output |
@@ -431,7 +448,7 @@ Optional: `@huggingface/transformers` (semantic search), `@modelcontextprotocol/
 
 ### MCP Server
 
-Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server with 21 tools (22 in multi-repo mode), so AI assistants can query your dependency graph directly:
+Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server with 24 tools (25 in multi-repo mode), so AI assistants can query your dependency graph directly:
 
 ```bash
 codegraph mcp                  # Single-repo mode (default) — only local project
@@ -470,6 +487,9 @@ This project uses codegraph. The database is at `.codegraph/graph.db`.
 - `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 complexity -T` — per-function complexity metrics (cognitive, cyclomatic, MI)
+- `codegraph communities --drift -T` — module boundary drift analysis
+- `codegraph manifesto -T` — pass/fail rule check (CI gate, exit code 1 on fail)
 - `codegraph search "<query>"` — semantic search (requires `codegraph embed`)
 - `codegraph cycles` — check for circular dependencies
 
@@ -550,6 +570,26 @@ Create a `.codegraphrc.json` in your project root to customize behavior:
 
 > **Tip:** `excludeTests` can also be set at the top level as a shorthand — `{ "excludeTests": true }` is equivalent to nesting it under `query`. If both are present, the nested `query.excludeTests` takes precedence.
 
+### Manifesto rules
+
+Configure pass/fail thresholds for `codegraph manifesto`:
+
+```json
+{
+  "manifesto": {
+    "rules": {
+      "cognitive_complexity": { "warn": 15, "fail": 30 },
+      "cyclomatic_complexity": { "warn": 10, "fail": 20 },
+      "nesting_depth": { "warn": 4, "fail": 6 },
+      "maintainability_index": { "warn": 40, "fail": 20 },
+      "halstead_bugs": { "warn": 0.5, "fail": 1.0 }
+    }
+  }
+}
+```
+
+When any function exceeds a `fail` threshold, `codegraph manifesto` exits with code 1 — perfect for CI gates.
+
 ### LLM credentials
 
 Codegraph supports an `apiKeyCommand` field for secure credential management. Instead of storing API keys in config files or environment variables, you can shell out to a secret manager at runtime:

docs/examples/CLI.md

@@ -758,6 +758,173 @@ Top co-change pairs:
 
 ---
 
+## complexity — Per-function complexity metrics
+
+```bash
+codegraph complexity -T --limit 5
+```
+
+```
+# Function Complexity
+
+  Function                                 File                            Cog  Cyc  Nest    MI
+  ──────────────────────────────────────── ────────────────────────────── ──── ──── ───── ─────
+  buildGraph                               src/builder.js                  495  185     9     - !
+  extractJavaSymbols                       src/extractors/java.js          208   64    10  13.9 !
+  extractSymbolsWalk                       src/extractors/javascript.js    197   72    11  11.1 !
+  walkJavaNode                             src/extractors/java.js          161   59     9    16 !
+  walkJavaScriptNode                       src/extractors/javascript.js    160   72    10  11.6 !
+
+  339 functions analyzed | avg cognitive: 18.8 | avg cyclomatic: 10.5 | avg MI: 22 | 106 above threshold
+```
+
+Full Halstead health view:
+
+```bash
+codegraph complexity --health -T --limit 5
+```
+
+```
+# Function Complexity
+
+  Function                            File                         MI     Vol   Diff    Effort   Bugs   LOC  SLOC
+  ─────────────────────────────────── ───────────────────────── ───── ─────── ────── ───────── ────── ───── ─────
+  buildGraph                          src/builder.js                0       0      0         0      0     0     0
+  extractJavaSymbols                  src/extractors/java.js     13.9!6673.96  70.52 470637.77 2.2247   225   212
+  extractSymbolsWalk                  …tractors/javascript.js    11.1!7911.66  50.02 395780.68 2.6372   251   239
+  walkJavaNode                        src/extractors/java.js       16!5939.15  65.25 387509.16 1.9797   198   188
+  walkJavaScriptNode                  …tractors/javascript.js    11.6!7624.39  47.67 363429.06 2.5415   240   230
+
+  339 functions analyzed | avg cognitive: 18.8 | avg cyclomatic: 10.5 | avg MI: 22 | 106 above threshold
+```
+
+Only functions exceeding warn thresholds:
+
+```bash
+codegraph complexity --above-threshold -T --limit 5
+```
+
+```
+# Functions Above Threshold
+
+  Function                                 File                            Cog  Cyc  Nest    MI
+  ──────────────────────────────────────── ────────────────────────────── ──── ──── ───── ─────
+  buildGraph                               src/builder.js                  495  185     9     - !
+  extractJavaSymbols                       src/extractors/java.js          208   64    10  13.9 !
+  extractSymbolsWalk                       src/extractors/javascript.js    197   72    11  11.1 !
+  walkJavaNode                             src/extractors/java.js          161   59     9    16 !
+  walkJavaScriptNode                       src/extractors/javascript.js    160   72    10  11.6 !
+
+  339 functions analyzed | avg cognitive: 18.8 | avg cyclomatic: 10.5 | avg MI: 22 | 106 above threshold
+```
+
+Sort by worst maintainability index:
+
+```bash
+codegraph complexity --sort mi -T --limit 5
+```
+
+```
+# Function Complexity
+
+  Function                                 File                            Cog  Cyc  Nest    MI
+  ──────────────────────────────────────── ────────────────────────────── ──── ──── ───── ─────
+  median                                   scripts/benchmark.js              1    2     1     -
+  round1                                   scripts/benchmark.js              0    1     0     -
+  selectTargets                            scripts/benchmark.js              1    2     1     -
+  benchmarkEngine                          scripts/benchmark.js              5    5     2     -
+  benchQuery                               scripts/benchmark.js              1    2     1     -
+
+  339 functions analyzed | avg cognitive: 18.8 | avg cyclomatic: 10.5 | avg MI: 22 | 106 above threshold
+```
+
+---
+
+## communities — Community detection & drift analysis
+
+```bash
+codegraph communities -T
+```
+
+```
+# File-Level Communities
+
+  41 communities | 73 nodes | modularity: 0.4114 | drift: 39%
+
+  Community 34 (16 members): src (16)
+    - src/cochange.js
+    - src/communities.js
+    - src/cycles.js
+    - src/embedder.js
+    - src/logger.js
+    - src/registry.js
+    - src/structure.js
+    - src/update-check.js
+    ... and 8 more
+  Community 35 (12 members): src/extractors (11), src (1)
+    - src/extractors/csharp.js
+    - src/extractors/go.js
+    - src/extractors/helpers.js
+    - src/extractors/javascript.js
+    - src/extractors/php.js
+    ... and 7 more
+  Community 33 (6 members): src (6)
+    - src/builder.js
+    - src/constants.js
+    - src/journal.js
+    - src/native.js
+    - src/resolve.js
+    - src/watcher.js
+```
+
+Drift analysis only:
+
+```bash
+codegraph communities --drift -T
+```
+
+```
+# File-Level Communities
+
+  41 communities | 73 nodes | modularity: 0.4114 | drift: 39%
+
+# Drift Analysis (score: 39%)
+
+  Split candidates (directories spanning multiple communities):
+    - scripts → 13 communities
+    - crates/codegraph-core/src/extractors → 11 communities
+    - crates/codegraph-core/src → 7 communities
+    - src → 4 communities
+    - tests/fixtures/sample-project → 3 communities
+    - (root) → 2 communities
+  Merge candidates (communities spanning multiple directories):
+    - Community 35 (12 members) → 2 dirs: src/extractors, src
+```
+
+---
+
+## manifesto — Rule engine pass/fail
+
+```bash
+codegraph manifesto -T
+```
+
+```
+# Manifesto Results
+
+  Rule                      Status   Threshold         Violations
+  ────────────────────────── ──────── ──────────────── ──────────
+  cognitive_complexity       FAIL     warn>15 fail>30   84 functions
+  cyclomatic_complexity      FAIL     warn>10 fail>20   42 functions
+  nesting_depth              FAIL     warn>4 fail>6     28 functions
+  maintainability_index      FAIL     warn<40 fail<20   52 functions
+  halstead_bugs              WARN     warn>0.5 fail>1   18 functions
+
+  Result: FAIL (exit code 1)
+```
+
+---
+
 ## path — Shortest path between two symbols
 
 ```bash