codegraph-brain 0.18.0__tar.gz → 0.20.0__tar.gz

codegraph_brain-0.20.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.20.0"
+}

{codegraph_brain-0.18.0 → codegraph_brain-0.20.0}/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [0.20.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.19.0...codegraph-brain-v0.20.0) (2026-09-11)
+
+
+### Features
+
+* **query:** a traversal says how much of its neighbourhood resolved ([#201](https://github.com/zaebee/codegraph-brain/issues/201)) ([#448](https://github.com/zaebee/codegraph-brain/issues/448)) ([0c63469](https://github.com/zaebee/codegraph-brain/commit/0c634697789f5264316c8a218e993f13a9a0f73f))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#449](https://github.com/zaebee/codegraph-brain/issues/449)) ([e9eccae](https://github.com/zaebee/codegraph-brain/commit/e9eccae8d43e8dc264ca87f8ea0a45752471f079))
+
+## [0.19.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.18.0...codegraph-brain-v0.19.0) (2026-09-09)
+
+
+### Features
+
+* **freshness:** every query says when the graph is out of date ([#175](https://github.com/zaebee/codegraph-brain/issues/175) part 2) ([#443](https://github.com/zaebee/codegraph-brain/issues/443)) ([0d6d197](https://github.com/zaebee/codegraph-brain/commit/0d6d197133c1315698b10a223aaf8efb47784578))
+* **metrics:** --scope <prefix> to focus rankings on one subtree ([#239](https://github.com/zaebee/codegraph-brain/issues/239)) ([#439](https://github.com/zaebee/codegraph-brain/issues/439)) ([59605d3](https://github.com/zaebee/codegraph-brain/commit/59605d361f95aeea18b8272183f20938c0ca10b8))
+* **orphans:** generated classes are noise, not findings — hide them by default ([#432](https://github.com/zaebee/codegraph-brain/issues/432)) ([#441](https://github.com/zaebee/codegraph-brain/issues/441)) ([52e0de1](https://github.com/zaebee/codegraph-brain/commit/52e0de1e666612f72d5a58eaad9509252db098e2))
+
+
+### Bug Fixes
+
+* **extractor:** `with X() as y` records y's type ([#444](https://github.com/zaebee/codegraph-brain/issues/444)) ([#445](https://github.com/zaebee/codegraph-brain/issues/445)) ([529b2e2](https://github.com/zaebee/codegraph-brain/commit/529b2e2239ab62a14211d95291afb1d7a6666cfc))
+* **resolver:** only a head-discarding strip is forbidden a foreign head ([#435](https://github.com/zaebee/codegraph-brain/issues/435)) ([#437](https://github.com/zaebee/codegraph-brain/issues/437)) ([3e5309a](https://github.com/zaebee/codegraph-brain/commit/3e5309ac6e65cfdc5174dc70c6ae9d4b5036d92a))
+* **suggest-packages:** name a member by its path under the package ([#446](https://github.com/zaebee/codegraph-brain/issues/446)) ([#447](https://github.com/zaebee/codegraph-brain/issues/447)) ([08af353](https://github.com/zaebee/codegraph-brain/commit/08af353f88b0026f799eb2cb2f9ed5f0c9733d22))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#442](https://github.com/zaebee/codegraph-brain/issues/442)) ([47a6aab](https://github.com/zaebee/codegraph-brain/commit/47a6aab38225f8e8936abd9d9e72b9449f10afe2))
+
 ## [0.18.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.17.0...codegraph-brain-v0.18.0) (2026-09-06)
 
 

{codegraph_brain-0.18.0 → codegraph_brain-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.18.0
+Version: 0.20.0
 Summary: Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP.
 Project-URL: Homepage, https://github.com/zaebee/codegraph-brain
 Project-URL: Repository, https://github.com/zaebee/codegraph-brain
@@ -198,15 +198,15 @@ classDef stdlibNode fill:#eceff1,stroke:#607d8b,stroke-width:1px,color:#455a64;
 classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dasharray: 3 3,color:#bf360c;
 
     subgraph sg_models["models.py"]
-        models_Edge["Edge (models.py:138)"]:::classNode
+        models_Edge["Edge (models.py:142)"]:::classNode
         models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
-        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:245)"]:::methodNode
-        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:185)"]:::methodNode
-        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:204)"]:::methodNode
-        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:155)"]:::methodNode
-        pipeline_IngestionPipeline_run["run (pipeline.py:51)"]:::methodNode
+        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:252)"]:::methodNode
+        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:192)"]:::methodNode
+        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:211)"]:::methodNode
+        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:157)"]:::methodNode
+        pipeline_IngestionPipeline_run["run (pipeline.py:53)"]:::methodNode
     end
     subgraph sg_engine["engine.py"]
         engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
@@ -217,7 +217,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         uplift_SemanticUpliftEngine_execute_uplift["execute_uplift (uplift.py:91)"]:::methodNode
     end
     subgraph sg_sqlite_store["sqlite_store.py"]
-        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:30)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:40)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
@@ -235,17 +235,17 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 | Symbol | Type | File |
 |--------|------|------|
 | `Node` | CLASS | [`models.py:85`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L85) |
-| `Edge` | CLASS | [`models.py:138`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L138) |
-| `run` | METHOD | [`pipeline.py:51`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L51) |
-| `_process_file` | METHOD | [`pipeline.py:155`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L155) |
-| `_is_noop_incremental` | METHOD | [`pipeline.py:185`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L185) |
-| `_persist_incremental` | METHOD | [`pipeline.py:204`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L204) |
-| `_get_extractor` | METHOD | [`pipeline.py:245`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L245) |
+| `Edge` | CLASS | [`models.py:142`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L142) |
+| `run` | METHOD | [`pipeline.py:53`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L53) |
+| `_process_file` | METHOD | [`pipeline.py:157`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L157) |
+| `_is_noop_incremental` | METHOD | [`pipeline.py:192`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L192) |
+| `_persist_incremental` | METHOD | [`pipeline.py:211`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L211) |
+| `_get_extractor` | METHOD | [`pipeline.py:252`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L252) |
 | `ResolverEngine` | CLASS | [`engine.py:19`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L19) |
 | `resolve` | METHOD | [`engine.py:36`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L36) |
 | `SemanticUpliftEngine` | CLASS | [`uplift.py:66`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L66) |
 | `execute_uplift` | METHOD | [`uplift.py:91`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L91) |
-| `SQLiteStore` | CLASS | [`sqlite_store.py:30`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L30) |
+| `SQLiteStore` | CLASS | [`sqlite_store.py:40`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L40) |
 <!-- END_CGIS_GRAPH -->
 
 ---

{codegraph_brain-0.18.0 → codegraph_brain-0.20.0}/README.md

@@ -148,15 +148,15 @@ classDef stdlibNode fill:#eceff1,stroke:#607d8b,stroke-width:1px,color:#455a64;
 classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dasharray: 3 3,color:#bf360c;
 
     subgraph sg_models["models.py"]
-        models_Edge["Edge (models.py:138)"]:::classNode
+        models_Edge["Edge (models.py:142)"]:::classNode
         models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
-        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:245)"]:::methodNode
-        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:185)"]:::methodNode
-        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:204)"]:::methodNode
-        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:155)"]:::methodNode
-        pipeline_IngestionPipeline_run["run (pipeline.py:51)"]:::methodNode
+        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:252)"]:::methodNode
+        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:192)"]:::methodNode
+        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:211)"]:::methodNode
+        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:157)"]:::methodNode
+        pipeline_IngestionPipeline_run["run (pipeline.py:53)"]:::methodNode
     end
     subgraph sg_engine["engine.py"]
         engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
@@ -167,7 +167,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         uplift_SemanticUpliftEngine_execute_uplift["execute_uplift (uplift.py:91)"]:::methodNode
     end
     subgraph sg_sqlite_store["sqlite_store.py"]
-        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:30)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:40)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
@@ -185,17 +185,17 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 | Symbol | Type | File |
 |--------|------|------|
 | `Node` | CLASS | [`models.py:85`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L85) |
-| `Edge` | CLASS | [`models.py:138`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L138) |
-| `run` | METHOD | [`pipeline.py:51`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L51) |
-| `_process_file` | METHOD | [`pipeline.py:155`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L155) |
-| `_is_noop_incremental` | METHOD | [`pipeline.py:185`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L185) |
-| `_persist_incremental` | METHOD | [`pipeline.py:204`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L204) |
-| `_get_extractor` | METHOD | [`pipeline.py:245`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L245) |
+| `Edge` | CLASS | [`models.py:142`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L142) |
+| `run` | METHOD | [`pipeline.py:53`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L53) |
+| `_process_file` | METHOD | [`pipeline.py:157`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L157) |
+| `_is_noop_incremental` | METHOD | [`pipeline.py:192`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L192) |
+| `_persist_incremental` | METHOD | [`pipeline.py:211`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L211) |
+| `_get_extractor` | METHOD | [`pipeline.py:252`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L252) |
 | `ResolverEngine` | CLASS | [`engine.py:19`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L19) |
 | `resolve` | METHOD | [`engine.py:36`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L36) |
 | `SemanticUpliftEngine` | CLASS | [`uplift.py:66`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L66) |
 | `execute_uplift` | METHOD | [`uplift.py:91`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L91) |
-| `SQLiteStore` | CLASS | [`sqlite_store.py:30`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L30) |
+| `SQLiteStore` | CLASS | [`sqlite_store.py:40`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L40) |
 <!-- END_CGIS_GRAPH -->
 
 ---

{codegraph_brain-0.18.0 → codegraph_brain-0.20.0}/docs/architecture/HOW_IT_WORKS.md

@@ -86,7 +86,8 @@ CREATE TABLE IF NOT EXISTS nodes (
             confidence_score REAL NOT NULL,
             metadata TEXT,
             namespace TEXT NOT NULL DEFAULT 'INTERNAL',
-            is_test INTEGER NOT NULL DEFAULT 0
+            is_test INTEGER NOT NULL DEFAULT 0,
+            is_generated INTEGER NOT NULL DEFAULT 0
         );
 
         CREATE TABLE IF NOT EXISTS edges (
@@ -106,6 +107,11 @@ CREATE TABLE IF NOT EXISTS nodes (
             hash TEXT NOT NULL
         );
 
+        CREATE TABLE IF NOT EXISTS ingest_state (
+            key   TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+        );
+
         CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type);
         CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source);
         CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target);

{codegraph_brain-0.18.0 → codegraph_brain-0.20.0}/docs/architecture/diagrams/pipeline_flow.mermaid

@@ -8,15 +8,15 @@ classDef stdlibNode fill:#eceff1,stroke:#607d8b,stroke-width:1px,color:#455a64;
 classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dasharray: 3 3,color:#bf360c;
 
     subgraph sg_models["models.py"]
-        models_Edge["Edge (models.py:138)"]:::classNode
+        models_Edge["Edge (models.py:142)"]:::classNode
         models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
-        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:245)"]:::methodNode
-        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:185)"]:::methodNode
-        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:204)"]:::methodNode
-        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:155)"]:::methodNode
-        pipeline_IngestionPipeline_run["run (pipeline.py:51)"]:::methodNode
+        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:252)"]:::methodNode
+        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:192)"]:::methodNode
+        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:211)"]:::methodNode
+        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:157)"]:::methodNode
+        pipeline_IngestionPipeline_run["run (pipeline.py:53)"]:::methodNode
     end
     subgraph sg_engine["engine.py"]
         engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
@@ -27,7 +27,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         uplift_SemanticUpliftEngine_execute_uplift["execute_uplift (uplift.py:91)"]:::methodNode
     end
     subgraph sg_sqlite_store["sqlite_store.py"]
-        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:30)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:40)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge

{codegraph_brain-0.18.0 → codegraph_brain-0.20.0}/docs/how-to/MCP_REFERENCE.md

@@ -10,9 +10,13 @@
 Analyse transitive upstream callers of a specific FQN.
 
     Answers "what breaks if I change X?". ``output_format="mermaid"`` (default)
-    returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges}``
-    payload with real FQNs — letting an agent compute set differences (e.g.
-    "which route handlers never reach ``verify_ownership``?") directly.
+    returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges,
+    coverage}`` payload with real FQNs — letting an agent compute set
+    differences (e.g. "which route handlers never reach ``verify_ownership``?")
+    directly. ``coverage`` counts unresolved calls whose name matches a
+    traversed function, method or class: callers that may be missing, named in
+    ``top_unresolved``. It is an upper bound — a common name matches calls on
+    unrelated objects, which the names make visible.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
@@ -126,18 +130,30 @@ Classes nothing in production builds, extends or names — dead-code candidates
     ``prefix`` narrows to one package on a dot boundary. ``include_tests`` counts
     test code as a user, turning the report into "unreachable from anywhere".
 
-    Returns JSON ``{orphans, considered, test_sources}``; each orphan carries
-    ``fqn``/``file``/``line``. **A listing is a candidate for deletion, not a
-    proof** — a class named only inside a decorator (#429) or arriving through a
-    star import is invisible here, so the sweep errs towards reporting a live
-    class rather than hiding a dead one. ``test_sources: 0`` in a repository that
-    has tests means the graph predates the ``is_test`` column: re-ingest.
+    Machine-generated classes are **hidden by default**, and ``include_generated``
+    puts them back. The query is right about them — nothing constructs a
+    betterproto stub — but nobody hand-deletes one either, so they are noise
+    rather than a finding. Measured on owner-api at b7d02fe6, five of six
+    reported orphans were generated entities and the sixth a nested pydantic
+    ``Config``: the unfiltered report had no actionable row in it (#432).
+
+    Returns JSON ``{orphans, considered, test_sources, generated_excluded}``;
+    each orphan carries ``fqn``/``file``/``line``. **A listing is a candidate for
+    deletion, not a proof** — a class named only inside a decorator (#429) or
+    arriving through a star import is invisible here, so the sweep errs towards
+    reporting a live class rather than hiding a dead one. ``test_sources: 0`` in a
+    repository that has tests means the graph predates the ``is_test`` column:
+    re-ingest. ``generated_excluded`` counts every generated class left out of
+    the population under the same ``prefix``, referenced or not — so ``0`` on a
+    repository with generated code means the same for ``is_generated``, which has
+    no backfill: the marker is in the file header, not in the database.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
 | `db_path` | `string` |  |  |
 | `prefix` | `any` |  |  |
 | `include_tests` | `boolean` |  |  |
+| `include_generated` | `boolean` |  |  |
 
 ---
 
@@ -267,11 +283,22 @@ Whole-graph architectural metrics — coupling bottlenecks + God classes (#16).
     (e.g. ``["tests"]`` removes both ``tests.*`` and ``domains.*.tests.*``) so
     test/vendor scaffolding stays out of the rankings.
 
+    ``scope`` is its complement: it keeps only nodes under one of the given
+    dot-prefixes, anchored and cut on a dot boundary, so
+    ``["domains.reservation"]`` is that subtree and not
+    ``domains.reservation_archive``. Use it for a per-domain review. The two
+    compose, and they differ where it matters for PageRank — ``exclude`` removes
+    nodes from the propagation graph, ``scope`` filters the rows and lets rank
+    propagate over the whole graph, so a scoped run reports how central the
+    subtree is *globally*. Coupling in-degree likewise keeps counting callers
+    from outside the scope, which is the ripple a domain review is after (#239).
+
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
 | `db_path` | `string` |  |  |
 | `limit` | `integer` |  |  |
 | `exclude` | `any` |  |  |
+| `scope` | `any` |  |  |
 
 ---
 
@@ -302,8 +329,12 @@ Suggest sub-package boundaries for a package from its dependency communities.
 Trace the execution call-graph starting from a specific FQN downwards.
 
     ``output_format="mermaid"`` (default) returns a human-readable diagram;
-    ``"json"`` returns a joinable ``{root, nodes, edges}`` payload with real
-    FQNs (not display hashes) for agent/CI use. Use ``cgis_ingest`` first if
+    ``"json"`` returns a joinable ``{root, nodes, edges, coverage}`` payload
+    with real FQNs (not display hashes) for agent/CI use. ``coverage`` counts
+    the calls the traversed functions make that resolved to nothing, and
+    ``top_unresolved`` names the most frequent. Read the names, not only the
+    ratio: in Python most are methods on untyped locals (``logger.info``,
+    ``items.append``), which cut nothing short. Use ``cgis_ingest`` first if
     the database does not exist yet.
 
 | Argument | Type | Required | Description |