optave · carlos-alm · Mar 3, 2026 · Mar 3, 2026 · Mar 3, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,7 +2,7 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-> **Use codegraph before editing code.** This project has a pre-built dependency graph at `.codegraph/graph.db`. Before modifying any function or file, run `node src/cli.js where <name>` to locate it, `node src/cli.js explain <target>` to understand the structure, `node src/cli.js context <name> -T` to gather full context, and `node src/cli.js fn-impact <name> -T` to check blast radius. After staging changes, run `node src/cli.js diff-impact --staged -T` to verify impact. This saves tokens, prevents blind edits, and catches breakage before it happens. See the [Dogfooding](#dogfooding--codegraph-on-itself) section for the full command reference.
+> **Use codegraph before editing code.** This project has a pre-built dependency graph at `.codegraph/graph.db`. Before modifying any function or file, run `node src/cli.js where <name>` to locate it, `node src/cli.js audit <target> --quick` to understand the structure, `node src/cli.js context <name> -T` to gather full context, and `node src/cli.js fn-impact <name> -T` to check blast radius. After staging changes, run `node src/cli.js diff-impact --staged -T` to verify impact. This saves tokens, prevents blind edits, and catches breakage before it happens. See the [Dogfooding](#dogfooding--codegraph-on-itself) section for the full command reference.
 
 ## Project Overview
 
@@ -114,7 +114,7 @@ Codegraph is **our own tool**. Use it to analyze this repository before making c
 
 ### Before modifying code, always:
 1. `node src/cli.js where <name>` — find where the symbol lives
-2. `node src/cli.js explain <file-or-function>` — understand the structure
+2. `node src/cli.js audit <file-or-function> --quick` — understand the structure
 3. `node src/cli.js context <name> -T` — get full context (source, deps, callers)
 4. `node src/cli.js fn-impact <name> -T` — check blast radius before editing
 
@@ -127,13 +127,13 @@ node src/cli.js build .              # Build/update the graph (incremental)
 node src/cli.js map --limit 20       # Module overview & most-connected nodes
 node src/cli.js stats                # Graph health and quality score
 node src/cli.js query <name> -T       # Function call chain (callers + callees)
-node src/cli.js query <a> --path <b> -T  # Shortest path between two symbols
+node src/cli.js path <a> <b> -T          # Shortest path between two symbols
 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 audit <target> -T    # Combined explain + impact + health report
+node src/cli.js check -T             # Rule engine pass/fail check
+node src/cli.js audit <target> -T    # Combined structural summary + impact + health report
 node src/cli.js triage -T            # Ranked audit priority queue
 node src/cli.js check --staged       # CI validation predicates (exit code 0/1)
 node src/cli.js batch t1 t2 -T      # Batch query multiple targets

diff --git a/README.md b/README.md
@@ -169,7 +169,7 @@ Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) &middot; [CLAU
 | 📁 | **File dependencies** | See what a file imports and what imports it |
 | 💥 | **Impact analysis** | Trace every file affected by a change (transitive) |
 | 🧬 | **Function-level tracing** | Call chains, caller trees, function-level impact, and A→B pathfinding with qualified call resolution |
-| 🎯 | **Deep context** | `context` gives AI agents source, deps, callers, signature, and tests for a function in one call; `explain` gives structural summaries of files or functions |
+| 🎯 | **Deep context** | `context` gives AI agents source, deps, callers, signature, and tests for a function in one call; `audit --quick` gives structural summaries of files or functions |
 | 📍 | **Fast lookup** | `where` shows exactly where a symbol is defined and used — minimal, fast |
 | 📊 | **Diff impact** | Parse `git diff`, find overlapping functions, trace their callers |
 | 🔗 | **Co-change analysis** | Analyze git history for files that always change together — surfaces hidden coupling the static graph can't see; enriches `diff-impact` with historically coupled files |
@@ -184,7 +184,7 @@ Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) &middot; [CLAU
 | ⚡ | **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) |
+| 📜 | **Manifesto rule engine** | Configurable pass/fail rules with warn/fail thresholds for CI gates via `check` (exit code 1 on fail) |
 | 👥 | **CODEOWNERS integration** | Map graph nodes to CODEOWNERS entries — see who owns each function, ownership boundaries in `diff-impact` |
 | 💾 | **Graph snapshots** | `snapshot save`/`restore` for instant DB backup and rollback — checkpoint before refactoring, restore without rebuilding |
 | 🔎 | **Hybrid BM25 + semantic search** | FTS5 keyword search + embedding-based semantic search fused via Reciprocal Rank Fusion — `hybrid`, `semantic`, or `keyword` modes |
@@ -229,8 +229,8 @@ codegraph roles --role core --file src/  # Core symbols in src/
 ```bash
 codegraph context <name>       # Full context: source, deps, callers, signature, tests
 codegraph context <name> --depth 2 --no-tests  # Include callee source 2 levels deep
-codegraph explain <file>       # Structural summary: public API, internals, data flow
-codegraph explain <function>   # Function summary: signature, calls, callers, tests
+codegraph audit <file> --quick    # Structural summary: public API, internals, data flow
+codegraph audit <function> --quick  # Function summary: signature, calls, callers, tests
 ```
 
 ### Impact Analysis
@@ -240,9 +240,9 @@ codegraph impact <file>        # Transitive reverse dependency trace
 codegraph query <name>         # Function-level: callers, callees, call chain
 codegraph query <name> --no-tests --depth 5
 codegraph fn-impact <name>     # What functions break if this one changes
-codegraph query <from> --path <to>     # Shortest path between two symbols (A calls...calls B)
-codegraph query <from> --path <to> --reverse  # Follow edges backward
-codegraph query <from> --path <to> --depth 5 --kinds calls,imports
+codegraph path <from> <to>            # Shortest path between two symbols (A calls...calls B)
+codegraph path <from> <to> --reverse  # Follow edges backward
+codegraph path <from> <to> --depth 5 --kinds calls,imports
 codegraph diff-impact          # Impact of unstaged git changes
 codegraph diff-impact --staged # Impact of staged changes
 codegraph diff-impact HEAD~3   # Impact vs a specific ref
@@ -273,8 +273,8 @@ Co-change data also enriches `diff-impact` — historically coupled files appear
 
 ```bash
 codegraph structure            # Directory overview with cohesion scores
-codegraph hotspots             # Files with extreme fan-in, fan-out, or density
-codegraph hotspots --metric coupling --level directory --no-tests
+codegraph triage --level file  # Files with extreme fan-in, fan-out, or density
+codegraph triage --level directory --sort coupling --no-tests
 ```
 
 ### Code Health & Architecture
@@ -287,19 +287,22 @@ codegraph complexity --above-threshold -T  # Only functions exceeding warn thres
 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
+codegraph check                   # Pass/fail rule engine (exit code 1 on fail)
+codegraph check -T                # Exclude test files from rule evaluation
 ```
 
 ### Audit, Triage & Batch
 
 Composite commands for risk-driven workflows and multi-agent dispatch.
 
 ```bash
-codegraph audit <file-or-function>    # Combined explain + impact + health in one report
+codegraph audit <file-or-function>    # Combined structural summary + impact + health in one report
+codegraph audit <target> --quick      # Structural summary only (skip impact and health)
 codegraph audit src/queries.js -T     # Audit all functions in a file
 codegraph triage                      # Ranked audit priority queue (connectivity + hotspots + roles)
 codegraph triage -T --limit 20        # Top 20 riskiest functions, excluding tests
+codegraph triage --level file -T      # File-level hotspot analysis
+codegraph triage --level directory -T # Directory-level hotspot analysis
 codegraph batch target1 target2 ...   # Batch query multiple targets in one call
 codegraph batch --json targets.json   # Batch from a JSON file
 ```
@@ -309,7 +312,9 @@ codegraph batch --json targets.json   # Batch from a JSON file
 `codegraph check` provides configurable pass/fail predicates for CI gates and state machines. Exit code 0 = pass, 1 = fail.
 
 ```bash
-codegraph check --staged                    # Check staged changes
+codegraph check                             # Run manifesto rules on whole codebase
+codegraph check --staged                    # Check staged changes (diff predicates)
+codegraph check --staged --rules            # Run both diff predicates AND manifesto rules
 codegraph check --no-new-cycles             # Fail if staged changes introduce cycles
 codegraph check --max-complexity 30         # Fail if any function exceeds complexity threshold
 codegraph check --max-blast-radius 50       # Fail if blast radius exceeds limit
@@ -413,7 +418,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`, `complexity`, `communities`, `manifesto`, `branch-compare`, `audit`, `triage`, `check`) |
+| `-T, --no-tests` | Exclude `.test.`, `.spec.`, `__test__` files (available on `fn`, `fn-impact`, `path`, `context`, `where`, `diff-impact`, `search`, `map`, `roles`, `co-change`, `deps`, `impact`, `complexity`, `communities`, `branch-compare`, `audit`, `triage`, `check`) |
 | `--depth <n>` | Transitive trace depth (default varies by command) |
 | `-j, --json` | Output as JSON |
 | `-v, --verbose` | Enable debug output |
@@ -556,7 +561,7 @@ This project uses codegraph. The database is at `.codegraph/graph.db`.
 
 ### Before modifying code, always:
 1. `codegraph where <name>` — find where the symbol lives
-2. `codegraph explain <file-or-function>` — understand the structure
+2. `codegraph audit <file-or-function> --quick` — understand the structure
 3. `codegraph context <name> -T` — get full context (source, deps, callers)
 4. `codegraph fn-impact <name> -T` — check blast radius before editing
 
@@ -567,16 +572,17 @@ This project uses codegraph. The database is at `.codegraph/graph.db`.
 - `codegraph build .` — rebuild the graph (incremental by default)
 - `codegraph map` — module overview
 - `codegraph query <name> -T` — function call chain (callers + callees)
-- `codegraph query <from> --path <to> -T` — shortest call path between two symbols
+- `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 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 audit <target> -T` — combined explain + impact + health in one report
+- `codegraph check -T` — pass/fail rule check (CI gate, exit code 1 on fail)
+- `codegraph audit <target> -T` — combined structural summary + impact + health in one report
 - `codegraph triage -T` — ranked audit priority queue
+- `codegraph triage --level file -T` — file-level hotspot analysis
 - `codegraph check --staged` — CI validation predicates (exit code 0/1)
 - `codegraph batch target1 target2` — batch query multiple targets at once
 - `codegraph owners [target]` — CODEOWNERS mapping for symbols
@@ -665,7 +671,7 @@ Create a `.codegraphrc.json` in your project root to customize behavior:
 
 ### Manifesto rules
 
-Configure pass/fail thresholds for `codegraph manifesto`:
+Configure pass/fail thresholds for `codegraph check` (manifesto mode):
 
 ```json
 {
@@ -681,7 +687,7 @@ Configure pass/fail thresholds for `codegraph manifesto`:
 }
 ```
 
-When any function exceeds a `fail` threshold, `codegraph manifesto` exits with code 1 — perfect for CI gates.
+When any function exceeds a `fail` threshold, `codegraph check` exits with code 1 — perfect for CI gates.
 
 ### LLM credentials
 

diff --git a/docs/examples/CLI.md b/docs/examples/CLI.md
@@ -95,12 +95,12 @@ codegraph where -f src/db.js -T
 
 ---
 
-## explain — Structural summary (file or function)
+## audit --quick — Structural summary (file or function)
 
 ### On a file
 
 ```bash
-codegraph explain src/builder.js -T
+codegraph audit src/builder.js --quick -T
 ```
 
 ```
@@ -132,7 +132,7 @@ codegraph explain src/builder.js -T
 ### On a function
 
 ```bash
-codegraph explain buildGraph -T
+codegraph audit buildGraph --quick -T
 ```
 
 ```
@@ -450,10 +450,10 @@ tests/  (0 files, 32 symbols, <-0 ->6 cohesion=0.00)
 
 ---
 
-## hotspots — Find structural hotspots
+## triage --level — Find structural hotspots
 
 ```bash
-codegraph hotspots --metric fan-in -T
+codegraph triage --level file --sort fan-in -T
 ```
 
 ```
@@ -469,7 +469,7 @@ Hotspots by fan-in (file-level, top 10):
    8. src/cli.js  <-0 ->10  (570L, 1 symbols)
 ```
 
-Other metrics: `fan-out`, `density`, `coupling`.
+Other metrics: `fan-out`, `density`, `coupling`. Use `--level directory` for directory-level hotspots.
 
 ---
 
@@ -903,14 +903,16 @@ codegraph communities --drift -T
 
 ---
 
-## manifesto — Rule engine pass/fail
+## check — Rule engine pass/fail (manifesto mode)
+
+Running `check` with no ref or `--staged` runs manifesto rules on the whole codebase:
 
 ```bash
-codegraph manifesto -T
+codegraph check -T
 ```
 
 ```
-# Manifesto Results
+# Manifesto Rules
 
   Rule                      Status   Threshold         Violations
   ────────────────────────── ──────── ──────────────── ──────────
@@ -927,7 +929,7 @@ codegraph manifesto -T
 
 ## audit — Composite risk report
 
-Combines explain + fn-impact + complexity metrics into one structured report per function. One call instead of 3-4.
+Combines structural summary + fn-impact + complexity metrics into one structured report per function. Use `--quick` for structural summary only (skip impact and health metrics).
 
 ```bash
 codegraph audit src/builder.js -T
@@ -962,7 +964,7 @@ codegraph audit buildGraph -T
 
 ## triage — Risk-ranked audit queue
 
-Merges connectivity, hotspots, node roles, and complexity into a prioritized audit queue.
+Merges connectivity, hotspots, node roles, and complexity into a prioritized audit queue. Use `--level file` or `--level directory` for file/directory-level hotspot analysis.
 
 ```bash
 codegraph triage -T --limit 5
@@ -1008,6 +1010,10 @@ codegraph batch buildGraph openDb parseFile -T --json
 
 Configurable pass/fail gates. Exit code 0 = pass, 1 = fail.
 
+- `check` (no args) — runs manifesto rules on whole codebase (see above)
+- `check --staged` / `check <ref>` — runs diff predicates against changes
+- `check --staged --rules` — runs both diff predicates AND manifesto rules
+
 ```bash
 codegraph check --staged --no-new-cycles --max-complexity 30
 ```

diff --git a/docs/examples/claude-code-hooks/remind-codegraph.sh b/docs/examples/claude-code-hooks/remind-codegraph.sh
@@ -61,7 +61,7 @@ cat <<HOOK_OUTPUT
   "hookSpecificOutput": {
     "hookEventName": "PreToolUse",
     "permissionDecision": "allow",
-    "additionalContext": "[codegraph reminder] You are about to edit ${REL_PATH}. Did you run codegraph first? Before editing, always: (1) 'codegraph where <name>' to locate the symbol, (2) 'codegraph explain ${REL_PATH}' to understand the file, (3) 'codegraph context <name> -T' for full context, (4) 'codegraph fn-impact <name> -T' to check blast radius. If you already did this, proceed."
+    "additionalContext": "[codegraph reminder] You are about to edit ${REL_PATH}. Did you run codegraph first? Before editing, always: (1) 'codegraph where <name>' to locate the symbol, (2) 'codegraph audit --quick ${REL_PATH}' to understand the file, (3) 'codegraph context <name> -T' for full context, (4) 'codegraph fn-impact <name> -T' to check blast radius. If you already did this, proceed."
   }
 }
 HOOK_OUTPUT