docs: regenerate stale audit/diff-impact example output blocks

docs: regenerate stale audit/diff-impact example output blocks

Replaces four stale example output blocks in docs/examples/CLI.md and
docs/examples/MCP.md (diff-impact and audit, both CLI + MCP) with output
regenerated from real tool runs against the repo's own graph.

Fixed a genuine Greptile finding: the mermaid blast-radius description in
MCP.md claimed callers "not directly reachable" from a changed function
land in the blast-radius subgraph, contradicted by the diagram's own
level-1 caller placement. Corrected to match classifyCallerNodes's actual
rule (terminal callers go to blast radius; callers with a further caller
of their own become standalone nodes) and replied to Greptile.

Greptile's fresh confirmation review was still pending 2.5+ hours after
re-trigger despite the finding being fixed and replied to — proceeding
since the actual merge gate (zero unaddressed comments, CI green, no
conflicts) is satisfied.

The Pre-publish benchmark gate failed twice (the routine flaky "1-file
rebuild" timing gate seen on prior PRs) and passed clean on the second
rerun with no code changes.

Author: carlos-alm

docs/examples/CLI.md

@@ -370,21 +370,23 @@ Impact analysis for files matching "src/parser.js":
 
 ## diff-impact — Impact of git changes
 
+Compares the working tree, staged changes, or a git ref against the current graph and reports which functions were edited and how far their impact reaches.
+
 ```bash
-codegraph diff-impact main -T
+codegraph diff-impact --staged -T
 ```
 
 ```
-  Changed files:
-    M src/structure.js    (structureCmd, computeStructure)
-    M src/queries.js      (findNodeByName)
+diff-impact: 2 files changed
+
+  2 functions changed:
 
-  Impacted functions:
-    -- Level 1:
-        ^ resolveNoTests  src/cli.js:59
-        ^ structureTool   src/mcp.js:312
+  f resolveNoTests -- src/cli/shared/options.ts:39
+    ^ 1 transitive callers
+  f renderNoCallEdgesFallback -- src/presentation/call-ref-sections.ts:70
+    ^ 6 transitive callers
 
-  Total: 2 functions affected by this diff
+  Summary: 2 functions changed -> 7 callers affected across 4 files
 ```
 
 Also available as a Mermaid diagram (`-f mermaid`) for visual impact graphs.
@@ -1059,32 +1061,60 @@ codegraph check -T
 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
+codegraph audit diffImpactData -T -f src/domain/analysis/diff-impact.ts
 ```
 
 ```
-# Audit: src/builder.js
+# Audit: diffImpactData (function)
+  1 function(s) analyzed
 
-## buildGraph (function) — src/builder.js:335
-  Parameters: (rootDir, opts = {})
-  Complexity: cognitive=495 cyclomatic=185 nesting=9 MI=0 ⚠
-  Impact: 1 transitive callers
-    ^ resolveNoTests  src/cli.js:59
-  Calls: openDb, initSchema, loadConfig, collectFiles, getChangedFiles, ...
+## f diffImpactData (function) [utility]
+  src/domain/analysis/diff-impact.ts:259-389 (131 lines)
+  Compute diff-impact analysis between two git refs (or staged changes).
+
+  Health:
+    Cognitive: 11  Cyclomatic: 13  Nesting: 1
+    MI: 40.2
+    Halstead: vol=2989.57 diff=36.62 effort=109477.32 bugs=0.9965
+    LOC: 131  SLOC: 111  Comments: 8
+
+  Threshold Breaches:
+    [WARN] cyclomatic: 13 >= 10
+
+  Impact: 3 transitive dependent(s)
+  -- Level 1 (2 functions):
+      ^ f diffImpactMermaid  src/presentation/diff-impact-mermaid.ts:127
+      ^ f diffImpact  src/presentation/queries-cli/impact.ts:298
+  ---- Level 2 (1 functions):
+        ^ o execute  src/cli/commands/diff-impact.ts:20
+
+  Calls (12):
+    f loadConfig  src/infrastructure/config.ts:771
+    f openReadonlyOrFail  src/db/connection.ts:376
+    f findDbPath  src/db/connection.ts:358
+    f findGitRoot  src/domain/analysis/diff-impact.ts:24
+    f runGitDiff  src/domain/analysis/diff-impact.ts:41
+    f parseGitDiff  src/domain/analysis/diff-impact.ts:65
+    f findAffectedFunctions  src/domain/analysis/diff-impact.ts:102
+    f checkBoundaryViolations  src/domain/analysis/diff-impact.ts:227
+    f paginateResult  src/shared/paginate.ts:80
+    f buildFunctionImpactResults  src/domain/analysis/diff-impact.ts:133
+    f lookupCoChanges  src/domain/analysis/diff-impact.ts:176
+    f lookupOwnership  src/domain/analysis/diff-impact.ts:201
 
-## collectFiles (function) — src/builder.js:45
-  Complexity: cognitive=12 cyclomatic=8 nesting=3 MI=45
-  Impact: 1 transitive callers
-    ^ buildGraph  src/builder.js:335
-  Calls: isTestFile, normalizePath
+  Called by (2):
+    f diffImpactMermaid  src/presentation/diff-impact-mermaid.ts:127
+    f diffImpact  src/presentation/queries-cli/impact.ts:298
 
-  ... (8 more functions)
+  Tests (2 files):
+    tests/unit/queries-unit.test.ts
+    tests/integration/queries.test.ts
 ```
 
-Single function:
+Audit an entire file — same per-function block repeated once for every function/method in the file:
 
 ```bash
-codegraph audit buildGraph -T
+codegraph audit src/domain/analysis/diff-impact.ts -T
 ```
 
 ---

docs/examples/MCP.md

@@ -252,46 +252,92 @@ Impact analysis for files matching "src/parser.js":
 ```json
 {
   "tool": "diff_impact",
-  "arguments": { "staged": true, "no_tests": true }
+  "arguments": { "staged": true, "no_tests": true, "depth": 1 }
 }
 ```
 
 ```json
 {
-  "changedFiles": ["src/structure.js", "src/queries.js"],
-  "changedFunctions": [
-    { "name": "structureCmd", "file": "src/structure.js", "line": 42 },
-    { "name": "findNodeByName", "file": "src/queries.js", "line": 180 }
+  "changedFiles": 2,
+  "newFiles": [],
+  "affectedFunctions": [
+    {
+      "name": "resolveNoTests",
+      "kind": "function",
+      "file": "src/cli/shared/options.ts",
+      "line": 39,
+      "transitiveCallers": 1,
+      "levels": {
+        "1": [
+          { "name": "resolveQueryOpts", "kind": "function", "file": "src/cli/shared/options.ts", "line": 51 }
+        ]
+      },
+      "edges": [
+        { "from": "src/cli/shared/options.ts::resolveNoTests:39", "to": "src/cli/shared/options.ts::resolveQueryOpts:51" }
+      ]
+    },
+    {
+      "name": "renderNoCallEdgesFallback",
+      "kind": "function",
+      "file": "src/presentation/call-ref-sections.ts",
+      "line": 70,
+      "transitiveCallers": 2,
+      "levels": {
+        "1": [
+          { "name": "renderAuditFunction", "kind": "function", "file": "src/presentation/audit.ts", "line": 77 },
+          { "name": "renderExplainEdges", "kind": "function", "file": "src/presentation/queries-cli/inspect.ts", "line": 484 }
+        ]
+      },
+      "edges": [
+        { "from": "src/presentation/call-ref-sections.ts::renderNoCallEdgesFallback:70", "to": "src/presentation/audit.ts::renderAuditFunction:77" },
+        { "from": "src/presentation/call-ref-sections.ts::renderNoCallEdgesFallback:70", "to": "src/presentation/queries-cli/inspect.ts::renderExplainEdges:484" }
+      ]
+    }
   ],
-  "impacted": [
-    { "name": "resolveNoTests", "file": "src/cli.js", "level": 1 },
-    { "name": "structureTool", "file": "src/mcp.js", "level": 1 }
-  ],
-  "totalImpacted": 2
+  "affectedFiles": ["src/cli/shared/options.ts", "src/presentation/audit.ts", "src/presentation/queries-cli/inspect.ts"],
+  "historicallyCoupled": [],
+  "ownership": null,
+  "boundaryViolations": [],
+  "boundaryViolationCount": 0,
+  "summary": {
+    "functionsChanged": 2,
+    "callersAffected": 3,
+    "filesAffected": 3,
+    "historicallyCoupledCount": 0,
+    "ownersAffected": 0,
+    "boundaryViolationCount": 0
+  }
 }
 ```
 
-With `format: "mermaid"`, returns a flowchart for visual rendering:
+With `format: "mermaid"`, returns a flowchart for visual rendering — each changed file becomes a subgraph, and each caller found (direct or transitive) is grouped into a "blast radius" subgraph unless it is itself an intermediate hop with a further caller of its own, in which case it's rendered as a standalone node:
 
 ```json
 {
   "tool": "diff_impact",
-  "arguments": { "ref": "main", "no_tests": true, "format": "mermaid" }
+  "arguments": { "staged": true, "no_tests": true, "format": "mermaid", "depth": 1 }
 }
 ```
 
 ```mermaid
 flowchart TB
-    subgraph Changed
-        structureCmd["structureCmd\nsrc/structure.js:42"]
-        findNodeByName["findNodeByName\nsrc/queries.js:180"]
+    subgraph sg0["src/cli/shared/options.ts **(modified)**"]
+        n0["resolveNoTests"]
+    end
+    style sg0 fill:#fff3e0,stroke:#ff9800
+    subgraph sg1["src/presentation/call-ref-sections.ts **(modified)**"]
+        n2["renderNoCallEdgesFallback"]
     end
-    subgraph Impacted
-        resolveNoTests["resolveNoTests\nsrc/cli.js:59"]
-        structureTool["structureTool\nsrc/mcp.js:312"]
+    style sg1 fill:#fff3e0,stroke:#ff9800
+    subgraph sg2["Callers **(blast radius)**"]
+        n1["resolveQueryOpts"]
+        n3["renderAuditFunction"]
+        n4["renderExplainEdges"]
     end
-    structureCmd --> resolveNoTests
-    findNodeByName --> structureTool
+    style sg2 fill:#f3e5f5,stroke:#9c27b0
+    n0 --> n1
+    n2 --> n3
+    n2 --> n4
 ```
 
 ---
@@ -753,30 +799,91 @@ Function-level community detection:
 
 ## audit — Composite risk report
 
-Combines explain + impact + complexity metrics in one call — gives an agent everything it needs to assess a function.
+Combines explain + impact + complexity metrics in one call — gives an agent everything it needs to assess a function. Unlike the CLI, the MCP tool returns the raw `{ target, kind, functions: [...] }` JSON payload rather than rendered text.
 
 ```json
 {
   "tool": "audit",
-  "arguments": { "target": "buildGraph", "no_tests": true }
+  "arguments": { "target": "diffImpactData", "file": "src/domain/analysis/diff-impact.ts", "no_tests": true }
 }
 ```
 
-```
-# Audit: buildGraph (function) — src/builder.js:335
-  Parameters: (rootDir, opts = {})
-  Complexity: cognitive=495 cyclomatic=185 nesting=9 MI=0 ⚠
-  Impact: 1 transitive callers
-    ^ resolveNoTests  src/cli.js:59
-  Calls: openDb, initSchema, loadConfig, collectFiles, getChangedFiles, ...
+```json
+{
+  "target": "diffImpactData",
+  "kind": "function",
+  "functions": [
+    {
+      "name": "diffImpactData",
+      "kind": "function",
+      "file": "src/domain/analysis/diff-impact.ts",
+      "line": 259,
+      "endLine": 389,
+      "role": "utility",
+      "lineCount": 131,
+      "summary": "Compute diff-impact analysis between two git refs (or staged changes).",
+      "signature": null,
+      "callees": [
+        { "name": "loadConfig", "kind": "function", "file": "src/infrastructure/config.ts", "line": 771 },
+        { "name": "openReadonlyOrFail", "kind": "function", "file": "src/db/connection.ts", "line": 376 },
+        { "name": "findDbPath", "kind": "function", "file": "src/db/connection.ts", "line": 358 },
+        { "name": "findGitRoot", "kind": "function", "file": "src/domain/analysis/diff-impact.ts", "line": 24 },
+        { "name": "runGitDiff", "kind": "function", "file": "src/domain/analysis/diff-impact.ts", "line": 41 },
+        { "name": "parseGitDiff", "kind": "function", "file": "src/domain/analysis/diff-impact.ts", "line": 65 },
+        { "name": "findAffectedFunctions", "kind": "function", "file": "src/domain/analysis/diff-impact.ts", "line": 102 },
+        { "name": "checkBoundaryViolations", "kind": "function", "file": "src/domain/analysis/diff-impact.ts", "line": 227 },
+        { "name": "paginateResult", "kind": "function", "file": "src/shared/paginate.ts", "line": 80 },
+        { "name": "buildFunctionImpactResults", "kind": "function", "file": "src/domain/analysis/diff-impact.ts", "line": 133 },
+        { "name": "lookupCoChanges", "kind": "function", "file": "src/domain/analysis/diff-impact.ts", "line": 176 },
+        { "name": "lookupOwnership", "kind": "function", "file": "src/domain/analysis/diff-impact.ts", "line": 201 }
+      ],
+      "callers": [
+        { "name": "diffImpactMermaid", "kind": "function", "file": "src/presentation/diff-impact-mermaid.ts", "line": 127 },
+        { "name": "diffImpact", "kind": "function", "file": "src/presentation/queries-cli/impact.ts", "line": 298 }
+      ],
+      "relatedTests": [
+        { "file": "tests/unit/queries-unit.test.ts" },
+        { "file": "tests/integration/queries.test.ts" }
+      ],
+      "impact": {
+        "totalDependents": 3,
+        "levels": {
+          "1": [
+            { "name": "diffImpactMermaid", "kind": "function", "file": "src/presentation/diff-impact-mermaid.ts", "line": 127 },
+            { "name": "diffImpact", "kind": "function", "file": "src/presentation/queries-cli/impact.ts", "line": 298 }
+          ],
+          "2": [
+            { "name": "execute", "kind": "method", "file": "src/cli/commands/diff-impact.ts", "line": 20 }
+          ]
+        }
+      },
+      "health": {
+        "cognitive": 11,
+        "cyclomatic": 13,
+        "maxNesting": 1,
+        "maintainabilityIndex": 40.2,
+        "halstead": { "volume": 2989.57, "difficulty": 36.62, "effort": 109477.32, "bugs": 0.9965 },
+        "loc": 131,
+        "sloc": 111,
+        "commentLines": 8,
+        "thresholdBreaches": [
+          { "metric": "cyclomatic", "value": 13, "threshold": 10, "level": "warn" }
+        ]
+      },
+      "riskScore": null,
+      "complexityNotes": null,
+      "sideEffects": null
+    }
+  ]
+}
 ```
 
-Audit an entire file:
+Audit an entire file — `functions` contains one entry per function/method in the file, each with the same shape:
 
 ```json
 {
   "tool": "audit",
-  "arguments": { "target": "src/builder.js", "no_tests": true }
+  "arguments": { "target": "src/domain/analysis/diff-impact.ts", "no_tests": true }
 }
 ```