codegraph-brain 0.23.3__tar.gz → 0.24.0__tar.gz

codegraph_brain-0.24.0/.github/test-count-baseline

@@ -0,0 +1 @@
+2618

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

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

{codegraph_brain-0.23.3 → codegraph_brain-0.24.0}/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.24.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.4...codegraph-brain-v0.24.0) (2026-09-17)
+
+
+### Features
+
+* **mcp:** cgis_overview — a starting map when you have no FQN yet ([#486](https://github.com/zaebee/codegraph-brain/issues/486)) ([1580cfe](https://github.com/zaebee/codegraph-brain/commit/1580cfe53325241e149ba3bbb9388c4ddc7718d7))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#488](https://github.com/zaebee/codegraph-brain/issues/488)) ([9f169ce](https://github.com/zaebee/codegraph-brain/commit/9f169ce364f0d778c0c59b4de607a3433b800dbd))
+
+## [0.23.4](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.3...codegraph-brain-v0.23.4) (2026-09-17)
+
+
+### Bug Fixes
+
+* **mcp:** trace_flow/analyze_impact default to the CLI's view ([#482](https://github.com/zaebee/codegraph-brain/issues/482)) ([8877051](https://github.com/zaebee/codegraph-brain/commit/8877051d9b6f90e6df2a25480c3f608cdacb5f58))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#484](https://github.com/zaebee/codegraph-brain/issues/484)) ([2f507b0](https://github.com/zaebee/codegraph-brain/commit/2f507b004c232dae3d90577f73d763f4d27be357))
+
 ## [0.23.3](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.2...codegraph-brain-v0.23.3) (2026-09-17)
 
 

{codegraph_brain-0.23.3 → codegraph_brain-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.23.3
+Version: 0.24.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
@@ -143,6 +143,7 @@ The main tools:
 | Tool | Answers |
 | :--- | :--- |
 | `cgis_ingest` | Build or incrementally refresh the graph |
+| `cgis_overview` | Where to start: sizes and the largest packages, when you have no FQN yet |
 | `cgis_find_symbol` | Partial name → candidate FQNs |
 | `cgis_analyze_impact` | What breaks upstream if this changes? |
 | `cgis_trace_flow` | What does this call, transitively? |

{codegraph_brain-0.23.3 → codegraph_brain-0.24.0}/README.md

@@ -93,6 +93,7 @@ The main tools:
 | Tool | Answers |
 | :--- | :--- |
 | `cgis_ingest` | Build or incrementally refresh the graph |
+| `cgis_overview` | Where to start: sizes and the largest packages, when you have no FQN yet |
 | `cgis_find_symbol` | Partial name → candidate FQNs |
 | `cgis_analyze_impact` | What breaks upstream if this changes? |
 | `cgis_trace_flow` | What does this call, transitively? |

{codegraph_brain-0.23.3 → codegraph_brain-0.24.0}/docs/architecture/HOW_IT_WORKS.md

@@ -204,7 +204,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:42)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:48)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
@@ -237,5 +237,5 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 | `resolve` | METHOD | [`engine.py:37`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L37) |
 | `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:42`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L42) |
+| `SQLiteStore` | CLASS | [`sqlite_store.py:48`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L48) |
 <!-- END_CGIS_GRAPH -->

{codegraph_brain-0.23.3 → codegraph_brain-0.24.0}/docs/architecture/diagrams/pipeline_flow.mermaid

@@ -29,7 +29,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:42)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:48)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge

codegraph_brain-0.24.0/docs/how-to/CLI_USAGE.md

@@ -0,0 +1,184 @@
+# 💻 CLI Usage Guide
+
+## Installation
+
+```bash
+uv pip install -e .
+```
+
+Verify:
+
+```bash
+cgis --version
+```
+
+---
+
+## Commands
+
+### `cgis ingest`
+
+Scan a repository, extract code structure, and build the semantic graph.
+
+```bash
+cgis ingest <path> [OPTIONS]
+```
+
+| Option | Default | Description |
+| :--- | :--- | :--- |
+| `--output`, `-o` | `graph.json` | Output path (`.db` for SQLite, `.json` for raw dump) |
+| `--incremental`, `-i` | `False` | Only re-ingest changed files (requires `.db` output) |
+| `--domains`, `-d` | `None` | Path to `domains.yaml` for semantic uplift |
+
+**Examples:**
+
+```bash
+# Full ingest with semantic uplift
+cgis ingest ./src --output graph.db --domains docs/ontology/domains.yaml
+
+# Incremental update after code changes
+cgis ingest ./src --output graph.db --incremental
+
+# Raw JSON dump for inspection
+cgis ingest ./src --output graph.json
+```
+
+---
+
+### `cgis overview`
+
+Where to start in a graph you know nothing about: how big it is, how much of it resolved, and the largest packages with production and tests listed separately. Every prefix it prints is one `find --prefix` and `metrics --scope` accept. `structure` takes a node's FQN instead — a package is a node only when it has an `__init__.py` — so reach a module through `find` first. The MCP tool is `cgis_overview`.
+
+```bash
+cgis overview [OPTIONS]
+```
+
+| Option | Default | Description |
+| :--- | :--- | :--- |
+| `--db`, `-d` | `graph.db` | Path to the graph database |
+| `--depth` | `2` | FQN segments per package prefix; `1` is the top level |
+| `--limit`, `-n` | `15` | Maximum packages listed per section |
+| `--format`, `-f` | `text` | `text` or `json` |
+
+**Examples:**
+
+```bash
+# First call in an unfamiliar repository
+cgis overview
+
+# Top-level map only, as JSON
+cgis overview --depth 1 --format json
+```
+
+---
+
+### `cgis trace`
+
+Everything a FQN reaches **downstream**: every edge except containment, which in practice means calls, imports, inheritance, DI dependencies and references between internal code. Containment stays out unless `--show-structure` adds it, and so do stdlib, third-party and unresolved call targets unless `--show-external` does. The MCP tool `cgis_trace_flow` uses the same defaults (`include_structure`, `include_external`).
+
+```bash
+cgis trace <fqn> [OPTIONS]
+```
+
+| Option | Default | Description |
+| :--- | :--- | :--- |
+| `--db`, `-d` | `graph.db` | Path to the graph database |
+| `--depth` | `5` | Maximum traversal depth |
+| `--format`, `-f` | `text` | `text`, `mermaid`, or `json` (joinable `{root, nodes, edges, coverage}`) |
+| `--show-structure` | off | Also follow containment (CONTAINS/DECLARES) |
+| `--show-external` | off | Also show stdlib, third-party and unresolved call targets |
+| `--internal-only` | off | Drop those nodes again from `mermaid`/`json` output; a no-op unless `--show-external` is on, and not valid with `text` |
+| `--min-confidence` | none | Hide edges below this confidence. Resolved calls score 1.0 and inferred ones 0.8, so a threshold above 0.8 is what filters anything |
+
+**Examples:**
+
+```bash
+# Text tree of what IngestionPipeline.run depends on
+cgis trace "cgis.pipeline.IngestionPipeline.run" --depth 3
+
+# Mermaid diagram for pasting into docs
+cgis trace "cgis.pipeline.IngestionPipeline.run" --format mermaid
+
+# Machine-readable, with the module's own members included
+cgis trace "cgis.query.engine" --format json --show-structure
+```
+
+---
+
+### `cgis impact`
+
+Everything that reaches a FQN **upstream**: callers, importers, subclasses, type references and DI dependents. The enclosing class or file stays out unless `--show-structure` adds it, and so do stdlib, third-party and unresolved call targets unless `--show-external` does. The MCP tool `cgis_analyze_impact` uses the same defaults.
+
+```bash
+cgis impact <fqn> [OPTIONS]
+```
+
+| Option | Default | Description |
+| :--- | :--- | :--- |
+| `--db`, `-d` | `graph.db` | Path to the graph database |
+| `--depth` | `5` | Maximum traversal depth |
+| `--format`, `-f` | `text` | `text`, `mermaid`, or `json` (joinable `{root, nodes, edges, coverage}`) |
+| `--show-structure` | off | Also follow containment (CONTAINS/DECLARES) |
+| `--show-external` | off | Also show stdlib, third-party and unresolved call targets |
+| `--internal-only` | off | Drop those nodes again from `mermaid`/`json` output; a no-op unless `--show-external` is on, and not valid with `text` |
+| `--min-confidence` | none | Hide edges below this confidence. Resolved calls score 1.0 and inferred ones 0.8, so a threshold above 0.8 is what filters anything |
+
+**Examples:**
+
+```bash
+# What depends on SQLiteStore.save_graph?
+cgis impact "cgis.storage.sqlite_store.SQLiteStore.save_graph"
+
+# Blast radius of changing the Node model
+cgis impact "cgis.core.models.Node" --depth 4 --format mermaid
+```
+
+---
+
+### `cgis structure`
+
+Show the internal layout of a module or class.
+
+```bash
+cgis structure <fqn> [OPTIONS]
+```
+
+| Option | Default | Description |
+| :--- | :--- | :--- |
+| `--db`, `-d` | `graph.db` | Path to the graph database |
+| `--depth` | `2` | Traversal depth |
+| `--show-external` | `False` | Include external nodes |
+
+**Example:**
+
+```bash
+cgis structure "cgis.storage.sqlite_store.SQLiteStore"
+```
+
+---
+
+### `cgis validate`
+
+Validate the graph database for integrity and schema compliance.
+
+```bash
+cgis validate [OPTIONS]
+```
+
+| Option | Default | Description |
+| :--- | :--- | :--- |
+| `--db`, `-d` | `graph.db` | Path to the graph database |
+
+---
+
+## FQN format
+
+All commands accept FQNs in dot-separated form derived from file paths:
+
+```
+src/cgis/pipeline.py                →  cgis.pipeline
+src/cgis/pipeline.py::IngestionPipeline  →  cgis.pipeline.IngestionPipeline
+src/cgis/pipeline.py::IngestionPipeline.run  →  cgis.pipeline.IngestionPipeline.run
+```
+
+Use `cgis structure` on a module to discover available FQNs before running `trace` or `impact`.

{codegraph_brain-0.23.3 → codegraph_brain-0.24.0}/docs/how-to/MCP_REFERENCE.md

@@ -9,9 +9,12 @@
 
 Upstream subgraph of one FQN: everything that reaches it within ``depth`` hops.
 
-    Every edge type counts — callers, but also importers, subclasses, type
-    references, DI dependents and the enclosing class or file — so this answers
-    "what breaks if I change X?". For what X depends on use
+    Follows every edge except containment — in practice callers, importers,
+    subclasses, type references and DI dependents — within internal code, so this
+    answers "what breaks if I change X?". The
+    enclosing class or file and stdlib/third-party nodes are left out unless
+    ``include_structure`` / ``include_external`` ask for them — the same view as
+    the CLI's ``impact``. For what X depends on use
     ``cgis_trace_flow``; for only the members of a module or class,
     ``cgis_get_structure``; for a source-included brief to read before editing
     one symbol, ``cgis_context``.
@@ -29,8 +32,10 @@ Upstream subgraph of one FQN: everything that reaches it within ``depth`` hops.
 | :--- | :--- | :---: | :--- |
 | `fqn` | `string` | ✓ | Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up. |
 | `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
-| `depth` | `integer` |  | Maximum edge hops upstream. Every edge type counts as a hop — callers, importers, subclasses, type references, DI dependents and the enclosing class or file all appear alongside each other. |
+| `depth` | `integer` |  | Maximum edge hops upstream, over callers, importers, subclasses, type references and DI dependents (plus the enclosing class or file with include_structure). |
 | `output_format` | `string` |  | "mermaid" for a diagram, or "json" for a payload with real FQNs (case-insensitive). Any other value returns an error. |
+| `include_structure` | `boolean` |  | Also follow containment (CONTAINS/DECLARES): a module's or class's own members, and the class or file enclosing a symbol. Off by default, as in the CLI; cgis_get_structure is the tool for members alone. |
+| `include_external` | `boolean` |  | Also return stdlib, third-party and unresolved call targets — calls on values whose type is decided at runtime. Off by default, as in the CLI, because they dominate the payload; in json, coverage/top_unresolved still counts what was dropped. |
 
 ---
 
@@ -69,7 +74,8 @@ Prompt-ready brief on one FQN: its source, class, direct callers and callees.
     calls only, one hop by default. Source is included when the file is found
     (see ``source_root``), and the domain when the graph was tagged with one.
     For a multi-hop subgraph
-    over every edge type without source, use ``cgis_trace_flow`` (downstream) or
+    over calls, imports, inheritance and references without source, use
+    ``cgis_trace_flow`` (downstream) or
     ``cgis_analyze_impact`` (upstream).
 
     Returns an XML-tagged prompt — the focal node's source, its enclosing class,
@@ -324,6 +330,31 @@ Whole-graph architectural metrics — coupling bottlenecks, God classes, PageRan
 
 ---
 
+## `cgis_overview`
+
+Where to start in a graph you know nothing about: sizes and a package map.
+
+    Call this first in an unfamiliar repository — every other tool needs a name,
+    and this is the one that hands you some. Returns JSON: symbol counts by type,
+    file and edge totals, the unresolved-edge ratio, and the largest packages with
+    production and tests listed separately. Each ``prefix`` goes straight into
+    ``cgis_find_symbol`` (``fqn_prefix``) or ``cgis_metrics`` (``scope``), which
+    match on prefixes. ``cgis_get_structure`` takes a node id, not a prefix: a
+    package is a node only when it has an ``__init__.py``, and then holds no
+    members of its own — reach a module through ``cgis_find_symbol`` first.
+
+    Listings are capped; ``packages_omitted`` appears when rows were cut. Entry
+    points are deliberately not reported — "nothing calls it" is not one on a
+    framework codebase, where most handlers have no incoming call edge.
+
+| Argument | Type | Required | Description |
+| :--- | :--- | :---: | :--- |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `depth` | `integer` |  | FQN segments per package prefix; 1 is the top level. |
+| `limit` | `integer` |  | Maximum packages listed per section. |
+
+---
+
 ## `cgis_suggest_packages`
 
 Suggest sub-package boundaries for a package from its dependency communities.
@@ -350,10 +381,13 @@ Suggest sub-package boundaries for a package from its dependency communities.
 
 Downstream subgraph of one FQN: everything it reaches within ``depth`` hops.
 
-    Every edge type counts — calls, imports, inheritance, DI dependencies,
-    references, and containment (so from a module or class the first hop includes
-    its own members) — so this answers "what does X depend on?". For what depends
-    on X use
+    Follows every edge except containment — in practice calls, imports,
+    inheritance, DI dependencies and references — between internal code, so this
+    answers "what does X depend on?". Containment and
+    stdlib/third-party nodes are left out unless ``include_structure`` /
+    ``include_external`` ask for them (external covers stdlib, third-party and
+    unresolved call targets) — the same view as the CLI's ``trace``.
+    For what depends on X use
     ``cgis_analyze_impact``; for only the members of a module or class,
     ``cgis_get_structure``; for a source-included brief to read before editing
     one symbol, ``cgis_context``.
@@ -371,8 +405,10 @@ Downstream subgraph of one FQN: everything it reaches within ``depth`` hops.
 | :--- | :--- | :---: | :--- |
 | `fqn` | `string` | ✓ | Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up. |
 | `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
-| `depth` | `integer` |  | Maximum edge hops downstream. Every edge type counts as a hop — calls, imports, inheritance, DI dependencies, references and containment — so from a module or class the first hop is mostly its own members and imports. |
+| `depth` | `integer` |  | Maximum edge hops downstream, over calls, imports, inheritance, DI dependencies and references (plus containment with include_structure). |
 | `output_format` | `string` |  | "mermaid" for a diagram, or "json" for a payload with real FQNs (case-insensitive). Any other value returns an error. |
+| `include_structure` | `boolean` |  | Also follow containment (CONTAINS/DECLARES): a module's or class's own members, and the class or file enclosing a symbol. Off by default, as in the CLI; cgis_get_structure is the tool for members alone. |
+| `include_external` | `boolean` |  | Also return stdlib, third-party and unresolved call targets — calls on values whose type is decided at runtime. Off by default, as in the CLI, because they dominate the payload; in json, coverage/top_unresolved still counts what was dropped. |
 
 ---
 

{codegraph_brain-0.23.3 → codegraph_brain-0.24.0}/plugin/skills/cgis/SKILL.md

@@ -11,6 +11,7 @@ Reading files to answer a structural question is the slow, lossy path: it burns
 
 | Question | Tool | Instead of |
 | :--- | :--- | :--- |
+| "Where do I even start?" | `cgis_overview` | opening files to find the shape of the repo |
 | "What calls this?" | `cgis_analyze_impact` | grepping the name and hoping |
 | "Is this rename safe?" | `cgis_analyze_impact` | reading every plausible caller |
 | "What does this end up calling?" | `cgis_trace_flow` | following imports by hand |
@@ -21,7 +22,7 @@ Reading files to answer a structural question is the slow, lossy path: it burns
 | "Did this change drift the architecture?" | `cgis_drift` | nothing — there is no manual equivalent |
 | "Does every handler reach its authz guard?" | `cgis_audit_reachability` | auditing routes one by one |
 
-A subgraph at depth 2 costs a few hundred tokens. The equivalent in file chunks costs thousands and is less precise.
+A depth-2 trace or impact of a function or method costs a few hundred tokens: median about 300, and 9 in 10 under 1,600. Measured over every function and method of two real graphs (700 and 5,800 symbols), in the default mermaid format and in json. The equivalent in file chunks costs thousands and is less precise. A module or a heavily used symbol costs more — the worst symbol on the larger graph returns 36k tokens, so raise `depth` deliberately and prefer `cgis_context` for a single symbol. Containment, stdlib/third-party nodes and unresolved call targets are off by default; `include_structure` and `include_external` add them when that is the question.
 
 ## First run in a repository
 

{codegraph_brain-0.23.3 → codegraph_brain-0.24.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.23.3"
+version = "0.24.0"
 description = "Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP."
 readme = "README.md"
 requires-python = ">=3.12"

{codegraph_brain-0.23.3 → codegraph_brain-0.24.0}/scripts/check_pytest_raises.py

@@ -54,7 +54,6 @@ GRANDFATHERED: frozenset[str] = frozenset(
         "unit/test_drift_service.py::test_analyze_drift_bad_suffix_raises",
         "unit/test_drift_service.py::test_analyze_drift_missing_db_raises",
         "unit/test_drift_service.py::test_analyze_drift_missing_patterns_raises",
-        "unit/test_guardian_martian_script.py::test_a_missing_concurrency_raises_instead_of_defaulting",
         "unit/test_guardian_recording.py::test_a_non_json_path_is_rejected",
         "unit/test_metrics.py::test_missing_database_raises_file_not_found",
         "unit/test_ontology_init.py::test_propose_missing_db_raises",

{codegraph_brain-0.23.3 → codegraph_brain-0.24.0}/server.json

@@ -8,13 +8,13 @@
     "source": "github",
     "id": "1260843154"
   },
-  "version": "0.23.3",
+  "version": "0.24.0",
   "packages": [
     {
       "registryType": "pypi",
       "registryBaseUrl": "https://pypi.org",
       "identifier": "codegraph-brain",
-      "version": "0.23.3",
+      "version": "0.24.0",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"

{codegraph_brain-0.23.3 → codegraph_brain-0.24.0}/src/cgis/api/mcp_server.py

@@ -17,10 +17,11 @@ from pydantic import Field
 from cgis import __version__
 from cgis.core.coverage import TraversalCoverage
 from cgis.core.freshness import Freshness, FreshnessState
-from cgis.core.models import Edge, Node, NodeType
+from cgis.core.models import Edge, EdgeType, Node, NodeType
 from cgis.extractors.python_extractor import PythonExtractor
 from cgis.extractors.typescript_extractor import TypeScriptExtractor
 from cgis.pipeline import IngestionPipeline
+from cgis.query.analysis.overview import DEFAULT_DEPTH, DEFAULT_LIMIT, build_overview
 from cgis.query.analysis.suggest_service import report_to_dict, suggest_packages
 from cgis.query.context.audit import audit_reachability
 from cgis.query.context.context_service import build_context
@@ -28,7 +29,7 @@ from cgis.query.context.orphans import find_orphan_classes
 from cgis.query.drift.drift_service import analyze_drift
 from cgis.query.drift.fractal import analyze_fractal_db
 from cgis.query.drift.ontology_init import propose_ontology
-from cgis.query.engine import QueryEngine
+from cgis.query.engine import BEHAVIORAL_EDGE_TYPES, QueryEngine
 from cgis.query.fqn import resolve_fqn
 from cgis.query.render.graph_json import graph_to_json
 from cgis.query.render.mermaid import MermaidCompiler
@@ -65,6 +66,31 @@ Fqn = Annotated[
         "to look a name up."
     ),
 ]
+IncludeStructure = Annotated[
+    bool,
+    Field(
+        description="Also follow containment (CONTAINS/DECLARES): a module's or class's own "
+        "members, and the class or file enclosing a symbol. Off by default, as in the CLI; "
+        "cgis_get_structure is the tool for members alone."
+    ),
+]
+IncludeExternal = Annotated[
+    bool,
+    Field(
+        description="Also return stdlib, third-party and unresolved call targets — calls on "
+        "values whose type is decided at runtime. Off by default, as in the CLI, because they "
+        "dominate the payload; in json, coverage/top_unresolved still counts what was dropped."
+    ),
+]
+
+
+def _traversal_filters(
+    include_structure: bool, include_external: bool
+) -> tuple[frozenset[EdgeType] | None, bool]:
+    """Edge-type allowlist and external flag for trace/impact — the CLI's defaults (#481)."""
+    return (None if include_structure else BEHAVIORAL_EDGE_TYPES), include_external
+
+
 OutputFormat = Annotated[
     str,
     Field(
@@ -363,19 +389,23 @@ def cgis_trace_flow(
     depth: Annotated[
         int,
         Field(
-            description="Maximum edge hops downstream. Every edge type counts as a hop — "
-            "calls, imports, inheritance, DI dependencies, references and containment — so "
-            "from a module or class the first hop is mostly its own members and imports."
+            description="Maximum edge hops downstream, over calls, imports, inheritance, DI "
+            "dependencies and references (plus containment with include_structure)."
         ),
     ] = 3,
     output_format: OutputFormat = "mermaid",
+    include_structure: IncludeStructure = False,
+    include_external: IncludeExternal = False,
 ) -> str:
     """Downstream subgraph of one FQN: everything it reaches within ``depth`` hops.
 
-    Every edge type counts — calls, imports, inheritance, DI dependencies,
-    references, and containment (so from a module or class the first hop includes
-    its own members) — so this answers "what does X depend on?". For what depends
-    on X use
+    Follows every edge except containment — in practice calls, imports,
+    inheritance, DI dependencies and references — between internal code, so this
+    answers "what does X depend on?". Containment and
+    stdlib/third-party nodes are left out unless ``include_structure`` /
+    ``include_external`` ask for them (external covers stdlib, third-party and
+    unresolved call targets) — the same view as the CLI's ``trace``.
+    For what depends on X use
     ``cgis_analyze_impact``; for only the members of a module or class,
     ``cgis_get_structure``; for a source-included brief to read before editing
     one symbol, ``cgis_context``.
@@ -398,8 +428,13 @@ def cgis_trace_flow(
             res = resolve_fqn(store, fqn)
             if res.resolved is None:
                 return _resolution_error(fqn, res.candidates, res.truncated)
+            allowed, show_external = _traversal_filters(include_structure, include_external)
             result = QueryEngine(store).get_flow_result(
-                res.resolved, max_depth=depth, with_coverage=_wants_json(output_format)
+                res.resolved,
+                max_depth=depth,
+                allowed_edge_types=allowed,
+                show_external=show_external,
+                with_coverage=_wants_json(output_format),
             )
     except Exception as exc:
         return f"❌ {exc}"
@@ -424,18 +459,23 @@ def cgis_analyze_impact(
     depth: Annotated[
         int,
         Field(
-            description="Maximum edge hops upstream. Every edge type counts as a hop — "
-            "callers, importers, subclasses, type references, DI dependents and the "
-            "enclosing class or file all appear alongside each other."
+            description="Maximum edge hops upstream, over callers, importers, subclasses, "
+            "type references and DI dependents (plus the enclosing class or file with "
+            "include_structure)."
         ),
     ] = 3,
     output_format: OutputFormat = "mermaid",
+    include_structure: IncludeStructure = False,
+    include_external: IncludeExternal = False,
 ) -> str:
     """Upstream subgraph of one FQN: everything that reaches it within ``depth`` hops.
 
-    Every edge type counts — callers, but also importers, subclasses, type
-    references, DI dependents and the enclosing class or file — so this answers
-    "what breaks if I change X?". For what X depends on use
+    Follows every edge except containment — in practice callers, importers,
+    subclasses, type references and DI dependents — within internal code, so this
+    answers "what breaks if I change X?". The
+    enclosing class or file and stdlib/third-party nodes are left out unless
+    ``include_structure`` / ``include_external`` ask for them — the same view as
+    the CLI's ``impact``. For what X depends on use
     ``cgis_trace_flow``; for only the members of a module or class,
     ``cgis_get_structure``; for a source-included brief to read before editing
     one symbol, ``cgis_context``.
@@ -458,8 +498,13 @@ def cgis_analyze_impact(
             res = resolve_fqn(store, fqn)
             if res.resolved is None:
                 return _resolution_error(fqn, res.candidates, res.truncated)
+            allowed, show_external = _traversal_filters(include_structure, include_external)
             result = QueryEngine(store).get_impact_result(
-                res.resolved, max_depth=depth, with_coverage=_wants_json(output_format)
+                res.resolved,
+                max_depth=depth,
+                allowed_edge_types=allowed,
+                show_external=show_external,
+                with_coverage=_wants_json(output_format),
             )
     except Exception as exc:
         return f"❌ {exc}"
@@ -678,6 +723,42 @@ def cgis_validate(
         return f"❌ {exc}"
 
 
+@mcp.tool()
+def cgis_overview(
+    db_path: DbPath = _DEFAULT_DB,
+    depth: Annotated[
+        int,
+        Field(description="FQN segments per package prefix; 1 is the top level."),
+    ] = DEFAULT_DEPTH,
+    limit: Annotated[
+        int, Field(description="Maximum packages listed per section.")
+    ] = DEFAULT_LIMIT,
+) -> str:
+    """Where to start in a graph you know nothing about: sizes and a package map.
+
+    Call this first in an unfamiliar repository — every other tool needs a name,
+    and this is the one that hands you some. Returns JSON: symbol counts by type,
+    file and edge totals, the unresolved-edge ratio, and the largest packages with
+    production and tests listed separately. Each ``prefix`` goes straight into
+    ``cgis_find_symbol`` (``fqn_prefix``) or ``cgis_metrics`` (``scope``), which
+    match on prefixes. ``cgis_get_structure`` takes a node id, not a prefix: a
+    package is a node only when it has an ``__init__.py``, and then holds no
+    members of its own — reach a module through ``cgis_find_symbol`` first.
+
+    Listings are capped; ``packages_omitted`` appears when rows were cut. Entry
+    points are deliberately not reported — "nothing calls it" is not one on a
+    framework codebase, where most handlers have no incoming call edge.
+    """
+    if not Path(db_path).exists():
+        return f"❌ Database not found at: {db_path}. Run cgis_ingest first."
+    try:
+        with SQLiteStore(db_path) as store:
+            report = build_overview(store, depth=depth, limit=limit)
+    except Exception as exc:
+        return f"❌ {exc}"
+    return json.dumps(_with_freshness(db_path, report), indent=2)
+
+
 @mcp.tool()
 def cgis_find_symbol(
     query: Annotated[
@@ -809,7 +890,8 @@ def cgis_context(
     calls only, one hop by default. Source is included when the file is found
     (see ``source_root``), and the domain when the graph was tagged with one.
     For a multi-hop subgraph
-    over every edge type without source, use ``cgis_trace_flow`` (downstream) or
+    over calls, imports, inheritance and references without source, use
+    ``cgis_trace_flow`` (downstream) or
     ``cgis_analyze_impact`` (upstream).
 
     Returns an XML-tagged prompt — the focal node's source, its enclosing class,