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

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

@@ -0,0 +1 @@
+2459

{codegraph_brain-0.20.0 → codegraph_brain-0.22.0}/.github/workflows/autodoc.yml

@@ -46,9 +46,9 @@ jobs:
       - name: Compute graph health badge
         run: uv run --frozen python scripts/generate_health.py --db /tmp/self_graph.db
 
-      - name: Inject graph into README.md
+      - name: Inject graph into HOW_IT_WORKS.md
         run: |
-          uv run --frozen python scripts/inject_readme_graph.py \
+          uv run --frozen python scripts/inject_architecture_graph.py \
             --db /tmp/self_graph.db \
             --fqn "cgis.pipeline.IngestionPipeline.run" \
             --depth 1 \
@@ -74,10 +74,8 @@ jobs:
             Updates:
             - Pipeline flow diagram (`docs/architecture/diagrams/pipeline_flow.mermaid`)
             - Graph health badge (`docs/architecture/health_badge.json`)
-            - Schema docs (`docs/architecture/HOW_IT_WORKS.md`)
+            - Schema docs and pipeline graph (`docs/architecture/HOW_IT_WORKS.md`)
             - MCP reference (`docs/how-to/MCP_REFERENCE.md`)
-            - README diagram injection
           labels: "docs,automated"
           add-paths: |
-            README.md
             docs/

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

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

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

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.22.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.21.0...codegraph-brain-v0.22.0) (2026-09-17)
+
+
+### Features
+
+* **mcp:** publishable to the official MCP Registry ([#464](https://github.com/zaebee/codegraph-brain/issues/464)) ([328ef6e](https://github.com/zaebee/codegraph-brain/commit/328ef6e655fa9324c2dc9940928edc065c28561e))
+
+
+### Documentation
+
+* **readme:** lead with what CGIS does, for whom, and how to try it ([#462](https://github.com/zaebee/codegraph-brain/issues/462)) ([3288c3e](https://github.com/zaebee/codegraph-brain/commit/3288c3ea44cf0099651bb8b9a0224b5c0044b16f))
+
+## [0.21.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.20.0...codegraph-brain-v0.21.0) (2026-09-16)
+
+
+### Features
+
+* **resolver:** resolve JS/TS runtime globals into js_builtins.* ([#111](https://github.com/zaebee/codegraph-brain/issues/111)) ([#453](https://github.com/zaebee/codegraph-brain/issues/453)) ([84e790b](https://github.com/zaebee/codegraph-brain/commit/84e790b404f7a515e048f7a2370b8865b71912ff))
+
+
+### Bug Fixes
+
+* **cli:** a full ingest into a database records file hashes ([#461](https://github.com/zaebee/codegraph-brain/issues/461)) ([e0a4a5e](https://github.com/zaebee/codegraph-brain/commit/e0a4a5ec34f8b0b34220f3f318ce0edc99ed1d9b))
+* **pipeline:** rebuild when a change alters what other files resolve against ([#38](https://github.com/zaebee/codegraph-brain/issues/38)) ([#458](https://github.com/zaebee/codegraph-brain/issues/458)) ([8126fd6](https://github.com/zaebee/codegraph-brain/commit/8126fd6377c82613f9f8a76f33253a8cd9e636f0))
+* **resolver:** Python stdlib names are STDLIB only in Python sources ([#454](https://github.com/zaebee/codegraph-brain/issues/454)) ([#457](https://github.com/zaebee/codegraph-brain/issues/457)) ([15e7ba1](https://github.com/zaebee/codegraph-brain/commit/15e7ba17ae49e2e3c10a2ef9f6cf1f11e663edfb))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#456](https://github.com/zaebee/codegraph-brain/issues/456)) ([ae24054](https://github.com/zaebee/codegraph-brain/commit/ae24054361935dbb1a1f9471eea7b4b949ab8a10))
+* auto-sync architecture graph and MCP reference ([#460](https://github.com/zaebee/codegraph-brain/issues/460)) ([a341063](https://github.com/zaebee/codegraph-brain/commit/a3410631511802bdc9851decadbbbf25b40d8d22))
+
 ## [0.20.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.19.0...codegraph-brain-v0.20.0) (2026-09-11)
 
 

codegraph_brain-0.22.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.5
+Name: codegraph-brain
+Version: 0.22.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
+Project-URL: Documentation, https://github.com/zaebee/codegraph-brain#readme
+Project-URL: Changelog, https://github.com/zaebee/codegraph-brain/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/zaebee/codegraph-brain/issues
+Author-email: Andrey G <zaebuntu@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,architecture,call-graph,code-graph,code-review,llm,mcp,model-context-protocol,static-analysis,tree-sitter
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]>=2
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=15.0.0
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: tree-sitter-python>=0.25.0
+Requires-Dist: tree-sitter-typescript>=0.23.2
+Requires-Dist: tree-sitter>=0.25.2
+Requires-Dist: typer>=0.26.7
+Provides-Extra: all
+Requires-Dist: cohere>=5.0.0; extra == 'all'
+Requires-Dist: duckdb>=1.1.0; extra == 'all'
+Requires-Dist: google-genai>=0.8.0; extra == 'all'
+Requires-Dist: mistralai>=1.0.0; extra == 'all'
+Requires-Dist: ollama>=0.3.0; extra == 'all'
+Provides-Extra: analytics
+Requires-Dist: duckdb>=1.1.0; extra == 'analytics'
+Provides-Extra: guardian
+Requires-Dist: cohere>=5.0.0; extra == 'guardian'
+Requires-Dist: google-genai>=0.8.0; extra == 'guardian'
+Requires-Dist: mistralai>=1.0.0; extra == 'guardian'
+Requires-Dist: ollama>=0.3.0; extra == 'guardian'
+Description-Content-Type: text/markdown
+
+# 🧠 CGIS: Code Graph Intelligence System
+<!-- mcp-name: io.github.zaebee/codegraph-brain -->
+### *A code graph your AI agent can query instead of guess*
+
+[![Continuous Integration](https://github.com/zaebee/codegraph-brain/actions/workflows/ci.yml/badge.svg)](https://github.com/zaebee/codegraph-brain/actions/workflows/ci.yml)
+[![Graph Integrity](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/zaebee/codegraph-brain/main/docs/architecture/health_badge.json)](https://github.com/zaebee/codegraph-brain/actions/workflows/autodoc.yml)
+[![PyPI](https://img.shields.io/pypi/v/codegraph-brain)](https://pypi.org/project/codegraph-brain/)
+
+**Ask "what breaks if I change this?" and get the call chain, not a guess.**
+
+CGIS parses a repository with tree-sitter into a graph of fully qualified symbols and the calls, imports and containment between them, stores it in SQLite, and serves it to AI agents over MCP. An agent that would otherwise grep and read whole files asks the graph instead.
+
+- **Languages:** Python · TypeScript / TSX
+- **Runs:** locally — no account, no telemetry; the graph never leaves your disk ([the one opt-in exception](https://github.com/zaebee/codegraph-brain/blob/main/PRIVACY.md))
+
+```console
+$ cgis ingest src --output graph.db
+$ cgis impact cgis.query.engine.QueryEngine.get_flow_graph --db graph.db --depth 2
+🔍 Analyzing transitive upstream callers of: cgis.query.engine.QueryEngine.get_flow_graph
+
+METHOD cgis.query.engine.QueryEngine.get_flow_graph (cgis/query/engine.py:215)
+├── FUNCTION cgis.query.context.context_service._collect_callees (cgis/query/context/context_service.py:44)
+│   └── FUNCTION cgis.query.context.context_service.build_context (cgis/query/context/context_service.py:96)
+└── METHOD cgis.guardian.collector.ContextCollector._graph_sections (cgis/guardian/collector.py:174)
+    ├── METHOD cgis.guardian.collector.ContextCollector.collect_graph_context (cgis/guardian/collector.py:213)
+    └── METHOD cgis.guardian.collector.ContextCollector.collect_for_chunk (cgis/guardian/collector.py:303)
+```
+
+*Real output — CGIS run on its own source.*
+
+---
+
+## 🚀 Quickstart
+
+### In Claude Code (fastest)
+
+```bash
+/plugin marketplace add zaebee/codegraph-brain
+/plugin install cgis@codegraph-brain
+```
+
+That ships the MCP server, a skill that teaches the agent *when* to query the graph instead of reading files, and `/cgis:ingest` to build the graph on first use. The server is pulled from PyPI on demand via `uvx`, so there is nothing to clone or build.
+
+### Any other MCP client (Cursor, Claude Desktop, …)
+
+```json
+{
+  "mcpServers": {
+    "cgis": { "command": "uvx", "args": ["--from", "codegraph-brain", "cgis-mcp"] }
+  }
+}
+```
+
+### From the terminal
+
+```bash
+# No install needed — uvx fetches it from PyPI
+uvx --from codegraph-brain cgis ingest ./my-project --output graph.db
+
+uvx --from codegraph-brain cgis impact "my_module.core_function" --db graph.db --depth 5   # who calls this
+uvx --from codegraph-brain cgis trace  "my_module.MyClass.run"   --db graph.db --depth 3   # what this calls
+# add --format mermaid (or json) to either for a diagram or machine-readable output
+```
+
+Or install it for good: `pip install codegraph-brain` (Python 3.12+), then use `cgis` directly. The full command list is in [CLI_USAGE.md](https://github.com/zaebee/codegraph-brain/blob/main/docs/how-to/CLI_USAGE.md).
+
+---
+
+## 📈 Proof at Real Scale
+
+CGIS runs on a working twelve-repository estate — four languages, 8,146 commits, shipping daily. On its 512-file FastAPI backend it classifies **88.4% of 40,493 edges** definitively, and prints the remaining 11.6% instead of inventing targets for them.
+
+**[Read the case study →](https://github.com/zaebee/codegraph-brain/blob/main/docs/CASE_STUDY.md)** — every figure measured and reproducible, including what CGIS *doesn't* cover.
+
+---
+
+## 🤔 Why a graph, and how this differs
+
+Text retrieval hands an agent chunks that *look* related. It cannot say which of three functions named `save` a call reaches, or what sits five callers up. CGIS resolves every call site to a fully qualified name when the source allows it — and when it does not, the edge stays marked unresolved and is counted, never filled with a plausible guess.
+
+| If you use… | CGIS adds |
+| :--- | :--- |
+| grep / file reads in the agent | Transitive callers and callees in one call, without spending context on whole files |
+| LSP-backed symbol tools (e.g. Serena) | A persisted whole-repo graph for multi-hop impact, coupling, PageRank and drift |
+| A repo map (e.g. aider) | Resolved edges you can traverse and audit, with the resolved/unresolved ratio reported |
+
+---
+
+## 🤖 MCP Tools
+
+The main tools:
+
+| Tool | Answers |
+| :--- | :--- |
+| `cgis_ingest` | Build or incrementally refresh the graph |
+| `cgis_find_symbol` | Partial name → candidate FQNs |
+| `cgis_analyze_impact` | What breaks upstream if this changes? |
+| `cgis_trace_flow` | What does this call, transitively? |
+| `cgis_get_structure` | Class / module hierarchy |
+| `cgis_context` | A compact GraphRAG context package for one symbol |
+| `cgis_metrics` | Coupling, god classes, PageRank, package cohesion |
+| `cgis_audit_reachability` | Authz / IDOR coverage — does every handler reach its guard? |
+| `cgis_drift` | How far each domain has moved from its declared pattern |
+| `cgis_validate` | Graph integrity: resolved vs unresolved edges |
+
+All 14 tools, with parameters: [MCP_REFERENCE.md](https://github.com/zaebee/codegraph-brain/blob/main/docs/how-to/MCP_REFERENCE.md).
+
+---
+
+## 🏗️ How It Works
+
+1.  **Extract** — tree-sitter parsers turn each file into nodes and raw call edges.
+2.  **Resolve** — the `ResolverEngine` maps raw calls to fully qualified names, or leaves them explicitly unresolved.
+3.  **Store** — SQLite holds the graph; queries are breadth-first traversals over it.
+
+```mermaid
+graph LR
+    A[Source Code] --> B[Extractors]
+    B --> C[Resolver Engine]
+    C --> D[(SQLite Graph DB)]
+    D --> E[MCP Server]
+    D --> F[Prompt Compiler]
+    E --> G[AI Agents]
+    F --> G
+```
+
+The details — and a pipeline graph CGIS regenerates from its own source on every change — are in [HOW_IT_WORKS.md](https://github.com/zaebee/codegraph-brain/blob/main/docs/architecture/HOW_IT_WORKS.md).
+
+---
+
+## 🛡️ Guardian: Graph-Aware Code Review
+
+**Guardian** is CGIS's built-in LLM reviewer — it reviews pull requests using the *graph* as context, not just the diff text. It runs in CI and posts inline comments anchored to the exact line.
+
+*   **Two-stage, recall-first:** a **finder** surfaces every plausible defect (optimised for recall), then a separate **skeptic** pass filters false positives — closer to how human reviewers work, and far more reliable than a single precision-gated prompt.
+*   **Local *or* cloud, no lock-in:** point it at **Ollama** (`qwen2.5-coder`, `llama3.1`, `granite-code`, …) for free local inference, or at **Mistral / Gemini** in the cloud. You can even mix them — a strong cloud finder with a free local *cross-model* skeptic.
+*   **Graph-aware context:** the reviewer sees impact graphs, architectural drift, and project ontology — so it catches structural and convention defects a flat-diff reviewer can't.
+*   **Deterministic anchoring:** every inline comment is positioned by a verbatim quote from the diff, not the model's (often wrong) line guess.
+*   **Dogfooded & measured:** Guardian reviews CGIS's *own* pull requests, and a benchmark harness scores it against curated ground truth — so prompt changes are validated, not guessed.
+
+```bash
+# Build the graph, then review a PR with a local model (no API key)
+cgis ingest ./src --output graph.db
+GUARDIAN_PROVIDER=ollama GUARDIAN_MODEL=qwen2.5-coder:14b \
+  uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline
+```
+
+No GPU on hand? **[Benchmark it on a notebook GPU →](https://github.com/zaebee/codegraph-brain/blob/main/docs/GUARDIAN_LOCAL_BENCH.md)** — free end to end, since the fixtures score without an LLM judge. Or **[point Guardian at a remote Ollama →](https://github.com/zaebee/codegraph-brain/blob/main/docs/GUARDIAN_REMOTE_OLLAMA.md)** — over an frp stcp tunnel, no public port, and a guard that refuses a review of a silently truncated prompt.
+
+---
+
+## 🔒 Privacy
+
+CGIS collects nothing: no telemetry, no analytics, no account. Your code and the graph built from it stay on your machine. The one exception is opt-in: Guardian, if you run it with a cloud model, sends the reviewed diff to the provider you chose. See [PRIVACY.md](https://github.com/zaebee/codegraph-brain/blob/main/PRIVACY.md).
+
+---
+
+## 🛠️ Development
+
+Requires Python 3.12+ and [`uv`](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/zaebee/codegraph-brain && cd codegraph-brain
+uv sync
+make pytest
+```
+
+See [CONTRIBUTING.md](https://github.com/zaebee/codegraph-brain/blob/main/CONTRIBUTING.md) for the standards: strict MyPy, linting, ontology compliance.
+
+---
+
+## 💼 Architecture Audit
+
+CGIS is free and you can run it yourself. If you would rather have the analysis than the tool, I run a fixed-price audit of your codebase's structure — authorisation coverage, blast radius, coupling, architectural drift — delivered in five working days, $2,400 fixed, with an explicit list of what the analysis cannot see. **[Read what's included →](https://github.com/zaebee/codegraph-brain/blob/main/docs/AUDIT.md)**

codegraph_brain-0.22.0/README.md

@@ -0,0 +1,174 @@
+# 🧠 CGIS: Code Graph Intelligence System
+<!-- mcp-name: io.github.zaebee/codegraph-brain -->
+### *A code graph your AI agent can query instead of guess*
+
+[![Continuous Integration](https://github.com/zaebee/codegraph-brain/actions/workflows/ci.yml/badge.svg)](https://github.com/zaebee/codegraph-brain/actions/workflows/ci.yml)
+[![Graph Integrity](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/zaebee/codegraph-brain/main/docs/architecture/health_badge.json)](https://github.com/zaebee/codegraph-brain/actions/workflows/autodoc.yml)
+[![PyPI](https://img.shields.io/pypi/v/codegraph-brain)](https://pypi.org/project/codegraph-brain/)
+
+**Ask "what breaks if I change this?" and get the call chain, not a guess.**
+
+CGIS parses a repository with tree-sitter into a graph of fully qualified symbols and the calls, imports and containment between them, stores it in SQLite, and serves it to AI agents over MCP. An agent that would otherwise grep and read whole files asks the graph instead.
+
+- **Languages:** Python · TypeScript / TSX
+- **Runs:** locally — no account, no telemetry; the graph never leaves your disk ([the one opt-in exception](https://github.com/zaebee/codegraph-brain/blob/main/PRIVACY.md))
+
+```console
+$ cgis ingest src --output graph.db
+$ cgis impact cgis.query.engine.QueryEngine.get_flow_graph --db graph.db --depth 2
+🔍 Analyzing transitive upstream callers of: cgis.query.engine.QueryEngine.get_flow_graph
+
+METHOD cgis.query.engine.QueryEngine.get_flow_graph (cgis/query/engine.py:215)
+├── FUNCTION cgis.query.context.context_service._collect_callees (cgis/query/context/context_service.py:44)
+│   └── FUNCTION cgis.query.context.context_service.build_context (cgis/query/context/context_service.py:96)
+└── METHOD cgis.guardian.collector.ContextCollector._graph_sections (cgis/guardian/collector.py:174)
+    ├── METHOD cgis.guardian.collector.ContextCollector.collect_graph_context (cgis/guardian/collector.py:213)
+    └── METHOD cgis.guardian.collector.ContextCollector.collect_for_chunk (cgis/guardian/collector.py:303)
+```
+
+*Real output — CGIS run on its own source.*
+
+---
+
+## 🚀 Quickstart
+
+### In Claude Code (fastest)
+
+```bash
+/plugin marketplace add zaebee/codegraph-brain
+/plugin install cgis@codegraph-brain
+```
+
+That ships the MCP server, a skill that teaches the agent *when* to query the graph instead of reading files, and `/cgis:ingest` to build the graph on first use. The server is pulled from PyPI on demand via `uvx`, so there is nothing to clone or build.
+
+### Any other MCP client (Cursor, Claude Desktop, …)
+
+```json
+{
+  "mcpServers": {
+    "cgis": { "command": "uvx", "args": ["--from", "codegraph-brain", "cgis-mcp"] }
+  }
+}
+```
+
+### From the terminal
+
+```bash
+# No install needed — uvx fetches it from PyPI
+uvx --from codegraph-brain cgis ingest ./my-project --output graph.db
+
+uvx --from codegraph-brain cgis impact "my_module.core_function" --db graph.db --depth 5   # who calls this
+uvx --from codegraph-brain cgis trace  "my_module.MyClass.run"   --db graph.db --depth 3   # what this calls
+# add --format mermaid (or json) to either for a diagram or machine-readable output
+```
+
+Or install it for good: `pip install codegraph-brain` (Python 3.12+), then use `cgis` directly. The full command list is in [CLI_USAGE.md](https://github.com/zaebee/codegraph-brain/blob/main/docs/how-to/CLI_USAGE.md).
+
+---
+
+## 📈 Proof at Real Scale
+
+CGIS runs on a working twelve-repository estate — four languages, 8,146 commits, shipping daily. On its 512-file FastAPI backend it classifies **88.4% of 40,493 edges** definitively, and prints the remaining 11.6% instead of inventing targets for them.
+
+**[Read the case study →](https://github.com/zaebee/codegraph-brain/blob/main/docs/CASE_STUDY.md)** — every figure measured and reproducible, including what CGIS *doesn't* cover.
+
+---
+
+## 🤔 Why a graph, and how this differs
+
+Text retrieval hands an agent chunks that *look* related. It cannot say which of three functions named `save` a call reaches, or what sits five callers up. CGIS resolves every call site to a fully qualified name when the source allows it — and when it does not, the edge stays marked unresolved and is counted, never filled with a plausible guess.
+
+| If you use… | CGIS adds |
+| :--- | :--- |
+| grep / file reads in the agent | Transitive callers and callees in one call, without spending context on whole files |
+| LSP-backed symbol tools (e.g. Serena) | A persisted whole-repo graph for multi-hop impact, coupling, PageRank and drift |
+| A repo map (e.g. aider) | Resolved edges you can traverse and audit, with the resolved/unresolved ratio reported |
+
+---
+
+## 🤖 MCP Tools
+
+The main tools:
+
+| Tool | Answers |
+| :--- | :--- |
+| `cgis_ingest` | Build or incrementally refresh the graph |
+| `cgis_find_symbol` | Partial name → candidate FQNs |
+| `cgis_analyze_impact` | What breaks upstream if this changes? |
+| `cgis_trace_flow` | What does this call, transitively? |
+| `cgis_get_structure` | Class / module hierarchy |
+| `cgis_context` | A compact GraphRAG context package for one symbol |
+| `cgis_metrics` | Coupling, god classes, PageRank, package cohesion |
+| `cgis_audit_reachability` | Authz / IDOR coverage — does every handler reach its guard? |
+| `cgis_drift` | How far each domain has moved from its declared pattern |
+| `cgis_validate` | Graph integrity: resolved vs unresolved edges |
+
+All 14 tools, with parameters: [MCP_REFERENCE.md](https://github.com/zaebee/codegraph-brain/blob/main/docs/how-to/MCP_REFERENCE.md).
+
+---
+
+## 🏗️ How It Works
+
+1.  **Extract** — tree-sitter parsers turn each file into nodes and raw call edges.
+2.  **Resolve** — the `ResolverEngine` maps raw calls to fully qualified names, or leaves them explicitly unresolved.
+3.  **Store** — SQLite holds the graph; queries are breadth-first traversals over it.
+
+```mermaid
+graph LR
+    A[Source Code] --> B[Extractors]
+    B --> C[Resolver Engine]
+    C --> D[(SQLite Graph DB)]
+    D --> E[MCP Server]
+    D --> F[Prompt Compiler]
+    E --> G[AI Agents]
+    F --> G
+```
+
+The details — and a pipeline graph CGIS regenerates from its own source on every change — are in [HOW_IT_WORKS.md](https://github.com/zaebee/codegraph-brain/blob/main/docs/architecture/HOW_IT_WORKS.md).
+
+---
+
+## 🛡️ Guardian: Graph-Aware Code Review
+
+**Guardian** is CGIS's built-in LLM reviewer — it reviews pull requests using the *graph* as context, not just the diff text. It runs in CI and posts inline comments anchored to the exact line.
+
+*   **Two-stage, recall-first:** a **finder** surfaces every plausible defect (optimised for recall), then a separate **skeptic** pass filters false positives — closer to how human reviewers work, and far more reliable than a single precision-gated prompt.
+*   **Local *or* cloud, no lock-in:** point it at **Ollama** (`qwen2.5-coder`, `llama3.1`, `granite-code`, …) for free local inference, or at **Mistral / Gemini** in the cloud. You can even mix them — a strong cloud finder with a free local *cross-model* skeptic.
+*   **Graph-aware context:** the reviewer sees impact graphs, architectural drift, and project ontology — so it catches structural and convention defects a flat-diff reviewer can't.
+*   **Deterministic anchoring:** every inline comment is positioned by a verbatim quote from the diff, not the model's (often wrong) line guess.
+*   **Dogfooded & measured:** Guardian reviews CGIS's *own* pull requests, and a benchmark harness scores it against curated ground truth — so prompt changes are validated, not guessed.
+
+```bash
+# Build the graph, then review a PR with a local model (no API key)
+cgis ingest ./src --output graph.db
+GUARDIAN_PROVIDER=ollama GUARDIAN_MODEL=qwen2.5-coder:14b \
+  uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline
+```
+
+No GPU on hand? **[Benchmark it on a notebook GPU →](https://github.com/zaebee/codegraph-brain/blob/main/docs/GUARDIAN_LOCAL_BENCH.md)** — free end to end, since the fixtures score without an LLM judge. Or **[point Guardian at a remote Ollama →](https://github.com/zaebee/codegraph-brain/blob/main/docs/GUARDIAN_REMOTE_OLLAMA.md)** — over an frp stcp tunnel, no public port, and a guard that refuses a review of a silently truncated prompt.
+
+---
+
+## 🔒 Privacy
+
+CGIS collects nothing: no telemetry, no analytics, no account. Your code and the graph built from it stay on your machine. The one exception is opt-in: Guardian, if you run it with a cloud model, sends the reviewed diff to the provider you chose. See [PRIVACY.md](https://github.com/zaebee/codegraph-brain/blob/main/PRIVACY.md).
+
+---
+
+## 🛠️ Development
+
+Requires Python 3.12+ and [`uv`](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/zaebee/codegraph-brain && cd codegraph-brain
+uv sync
+make pytest
+```
+
+See [CONTRIBUTING.md](https://github.com/zaebee/codegraph-brain/blob/main/CONTRIBUTING.md) for the standards: strict MyPy, linting, ontology compliance.
+
+---
+
+## 💼 Architecture Audit
+
+CGIS is free and you can run it yourself. If you would rather have the analysis than the tool, I run a fixed-price audit of your codebase's structure — authorisation coverage, blast radius, coupling, architectural drift — delivered in five working days, $2,400 fixed, with an explicit list of what the analysis cannot see. **[Read what's included →](https://github.com/zaebee/codegraph-brain/blob/main/docs/AUDIT.md)**

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

@@ -162,3 +162,80 @@ Two BFS traversals are exposed via `QueryEngine`:
 | `get_impact_graph(fqn)` | Upstream (incoming) | "What breaks if X changes?" |
 
 Both return `(nodes, edges)` suitable for rendering as a Mermaid diagram.
+
+---
+
+## Live Pipeline Graph
+
+The callees of `IngestionPipeline.run`, regenerated from CGIS's own source by the autodoc workflow on pushes to `main`, which opens a docs PR with the result.
+
+<!-- START_CGIS_GRAPH -->
+> *Auto-generated by CGIS parsing its own source — the tool documents itself.*
+
+```mermaid
+graph TD
+classDef classNode fill:#e8f5e9,stroke:#2e7d32,stroke-width:1.5px,color:#1b5e20;
+classDef funcNode fill:#e3f2fd,stroke:#1565c0,stroke-width:1.5px,color:#0d47a1;
+classDef methodNode fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1.5px,color:#4a148c;
+classDef unresolvedNode fill:#fffde7,stroke:#fbc02d,stroke-width:1.5px,stroke-dasharray: 4 4,color:#f57f17;
+classDef defaultNode fill:#fafafa,stroke:#9e9e9e,stroke-width:1.5px,color:#212121;
+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:142)"]:::classNode
+        models_Node["Node (models.py:85)"]:::classNode
+    end
+    subgraph sg_pipeline["pipeline.py"]
+        pipeline_IngestionPipeline_cross_file_inputs_changed["_cross_file_inputs_changed (pipeline.py:249)"]:::methodNode
+        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:384)"]:::methodNode
+        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:310)"]:::methodNode
+        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:334)"]:::methodNode
+        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:212)"]:::methodNode
+        pipeline_IngestionPipeline_run["run (pipeline.py:99)"]:::methodNode
+        pipeline_IngestionPipeline_workspace_root["workspace_root (pipeline.py:82)"]:::methodNode
+    end
+    subgraph sg_engine["engine.py"]
+        engine_ResolverEngine["ResolverEngine (engine.py:20)"]:::classNode
+        engine_ResolverEngine_resolve["resolve (engine.py:37)"]:::methodNode
+    end
+    subgraph sg_uplift["uplift.py"]
+        uplift_SemanticUpliftEngine["SemanticUpliftEngine (uplift.py:66)"]:::classNode
+        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
+    end
+    pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
+    pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
+    pipeline_IngestionPipeline_run -->|REFERENCES| sqlite_store_SQLiteStore
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_workspace_root
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_get_extractor
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_process_file
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_is_noop_incremental
+    pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine
+    pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine_resolve
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_cross_file_inputs_changed
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_run
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_persist_incremental
+    pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine_execute_uplift
+    pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine
+```
+
+| 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:142`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L142) |
+| `workspace_root` | METHOD | [`pipeline.py:82`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L82) |
+| `run` | METHOD | [`pipeline.py:99`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L99) |
+| `_process_file` | METHOD | [`pipeline.py:212`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L212) |
+| `_cross_file_inputs_changed` | METHOD | [`pipeline.py:249`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L249) |
+| `_is_noop_incremental` | METHOD | [`pipeline.py:310`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L310) |
+| `_persist_incremental` | METHOD | [`pipeline.py:334`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L334) |
+| `_get_extractor` | METHOD | [`pipeline.py:384`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L384) |
+| `ResolverEngine` | CLASS | [`engine.py:20`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L20) |
+| `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) |
+<!-- END_CGIS_GRAPH -->

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

@@ -12,31 +12,36 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
-        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
+        pipeline_IngestionPipeline_cross_file_inputs_changed["_cross_file_inputs_changed (pipeline.py:249)"]:::methodNode
+        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:384)"]:::methodNode
+        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:310)"]:::methodNode
+        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:334)"]:::methodNode
+        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:212)"]:::methodNode
+        pipeline_IngestionPipeline_run["run (pipeline.py:99)"]:::methodNode
+        pipeline_IngestionPipeline_workspace_root["workspace_root (pipeline.py:82)"]:::methodNode
     end
     subgraph sg_engine["engine.py"]
-        engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
-        engine_ResolverEngine_resolve["resolve (engine.py:36)"]:::methodNode
+        engine_ResolverEngine["ResolverEngine (engine.py:20)"]:::classNode
+        engine_ResolverEngine_resolve["resolve (engine.py:37)"]:::methodNode
     end
     subgraph sg_uplift["uplift.py"]
         uplift_SemanticUpliftEngine["SemanticUpliftEngine (uplift.py:66)"]:::classNode
         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:40)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:42)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
     pipeline_IngestionPipeline_run -->|REFERENCES| sqlite_store_SQLiteStore
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_workspace_root
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_get_extractor
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_process_file
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_is_noop_incremental
     pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine
     pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine_resolve
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_cross_file_inputs_changed
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_run
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_persist_incremental
     pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine_execute_uplift
     pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine

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

@@ -237,9 +237,11 @@ Scan a local directory, extract all symbols, resolve links, and build the graph
 
     By default the ingest is **incremental**: only changed/new files are
     re-scanned, and the summary reports both what changed this run and the
-    whole-graph total. Set ``full_rebuild=True`` to re-scan every file and
-    overwrite the database from scratch — use this to drop nodes for files that
-    were deleted or renamed, which an incremental run leaves behind.
+    whole-graph total. When a change alters what other files resolve against — a
+    renamed, removed or added symbol, a deleted or new file, a changed base class
+    or re-export — the incremental run rebuilds the whole graph itself, so edges
+    in unchanged files never point at symbols that no longer exist. Set
+    ``full_rebuild=True`` to force a re-scan of every file from scratch.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |

codegraph_brain-0.22.0/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["zaebee"]
+}

{codegraph_brain-0.20.0 → codegraph_brain-0.22.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.20.0"
+version = "0.22.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"
@@ -93,6 +93,9 @@ dev = [
 [project.scripts]
 cgis = "cgis.cli:app"
 cgis-mcp = "cgis.api.mcp_server:mcp.run"
+# Same server under the package name, so `uvx codegraph-brain` starts it — what the
+# MCP Registry entry (server.json, runtimeHint uvx) runs.
+codegraph-brain = "cgis.api.mcp_server:mcp.run"
 
 [tool.ruff]
 # Target Python 3.12+