docs: document Neo4j property-graph output (scale, Kubernetes, enterprise)

Reframe the docs around the new `--emit neo4j` target: project the analysis
into a labeled Neo4j property graph that scales beyond a single JSON file.
Introduce the producer/consumer split — `canpy` runs out-of-band as a
CI/Kubernetes job pushing app-scoped subgraphs to Neo4j over Bolt, while the
CLDK Python SDK and agents read the graph read-only via Neo4jConnectionConfig.

- New Neo4j guide + graph-schema reference pages; sidebar entries
- Neo4j property-graph hero visual (src/components/Neo4jPropertyGraph.astro)
- Document --emit json|neo4j|schema, --app-name, --neo4j-* flags and NEO4J_* env
- graph.cypher snapshot vs incremental Bolt push; per-app scoping; schema_version 1.1.0
- CLDK read-back examples; extended architecture/concept mermaid diagrams
- Fix stale CLI facts and cross-links; verified with `astro build`

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rahlk

astro.config.mjs

@@ -21,7 +21,7 @@ export default defineConfig({
       title: "codeanalyzer-python",
       tagline: "Static analysis for Python your agents can call.",
       description:
-        "codeanalyzer-python turns a Python project into one typed artifact — symbol table, call graph, and framework entrypoints — using Jedi, CodeQL, and Tree-sitter. The Python backend behind CLDK.",
+        "codeanalyzer-python turns a Python project into a typed symbol table and call graph — emitted as one analysis JSON artifact or a queryable Neo4j property graph — using Jedi, CodeQL, and Tree-sitter. The Python backend behind CLDK.",
       logo: {
         src: "./src/assets/logo.png",
         replacesTitle: true,
@@ -97,6 +97,7 @@ export default defineConfig({
             { label: "CLI usage", slug: "guides/cli-usage" },
             { label: "Core concepts", slug: "guides/concepts" },
             { label: "CodeQL analysis", slug: "guides/codeql" },
+            { label: "Neo4j graph", slug: "guides/neo4j" },
           ],
         },
         {

src/components/Neo4jPropertyGraph.astro

@@ -0,0 +1,118 @@
+---
+// AUTO-GENERATED property-graph hero for python. Encodes the real Neo4j schema
+// (node labels, typed relationships, key properties). Theme-aware via Starlight
+// CSS custom properties; renders as static SVG (no client JS).
+---
+<figure class="pgraph-figure">
+<svg class="pgraph" viewBox="0 0 1080 600" role="img" aria-label="codeanalyzer-python · Neo4j property graph" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="var(--pg-edge)"/>
+    </marker>
+    <marker id="arrow-accent" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#DA7194"/>
+    </marker>
+    <radialGradient id="gloss" cx="35%" cy="30%" r="75%">
+      <stop offset="0%" stop-color="#ffffff" stop-opacity="0.35"/>
+      <stop offset="55%" stop-color="#ffffff" stop-opacity="0.0"/>
+    </radialGradient>
+    <filter id="nshadow" x="-30%" y="-30%" width="160%" height="160%">
+      <feDropShadow dx="0" dy="3" stdDeviation="4" flood-color="#0b1020" flood-opacity="0.28"/>
+    </filter>
+  </defs>
+<path d="M 155.8 271.1 L 292.7 160.2" class="rel" fill="none" marker-end="url(#arrow)"/>
+<g transform="translate(224.2,215.6)"><rect x="-49.5" y="-11" width="99.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">PY_HAS_MODULE</text></g>
+<path d="M 330.0 176.0 L 330.0 422.0" class="rel" fill="none" marker-end="url(#arrow)"/>
+<g transform="translate(330.0,333.4)"><rect x="-42.5" y="-11" width="85.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">PY_DECLARES</text></g>
+<path d="M 284.0 470.0 L 168.0 470.0" class="rel" fill="none" marker-end="url(#arrow)"/>
+<g transform="translate(226.0,470.0)"><rect x="-60.0" y="-11" width="120.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">PY_HAS_ATTRIBUTE</text></g>
+<path d="M 367.0 442.7 L 521.4 328.5" class="rel" fill="none" marker-end="url(#arrow)"/>
+<g transform="translate(444.2,385.6)"><rect x="-49.5" y="-11" width="99.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">PY_HAS_METHOD</text></g>
+<path d="M 560.0 346.0 L 560.0 422.0" class="rel" fill="none" marker-end="url(#arrow)"/>
+<g transform="translate(560.0,394.6)"><rect x="-56.5" y="-11" width="113.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">PY_DECORATED_BY</text></g>
+<path d="M 597.0 272.7 L 751.4 158.5" class="rel" fill="none" marker-end="url(#arrow)"/>
+<g transform="translate(674.2,215.6)"><rect x="-56.5" y="-11" width="113.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">PY_HAS_CALLSITE</text></g>
+<path d="M 823.9 161.1 L 939.7 267.5" class="rel" fill="none" marker-end="url(#arrow)"/>
+<g transform="translate(881.8,214.3)"><rect x="-53.0" y="-11" width="106.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">PY_RESOLVES_TO</text></g>
+<path d="M 606.0 300.0 Q 734.4 170.0 927.0 300.0" class="rel-accent" fill="none" marker-end="url(#arrow-accent)"/>
+<g transform="translate(725.2,236.7)"><rect x="-32.0" y="-11" width="64.0" height="22" rx="11" class="pill-accent"/><text x="0" y="4" class="rtype" text-anchor="middle">PY_CALLS</text></g>
+<circle cx="120" cy="300" r="46" fill="#C990C0" stroke="#ffffff" stroke-width="2.5" filter="url(#nshadow)"/>
+<circle cx="120" cy="300" r="46" fill="url(#gloss)"/>
+<text x="120" y="304" class="nlabel" text-anchor="middle">:PyApplication</text>
+<text x="120" y="362" class="prop" text-anchor="middle">name</text>
+<text x="120" y="378" class="prop" text-anchor="middle">schema_version</text>
+<circle cx="330" cy="130" r="46" fill="#4C8EDA" stroke="#ffffff" stroke-width="2.5" filter="url(#nshadow)"/>
+<circle cx="330" cy="130" r="46" fill="url(#gloss)"/>
+<text x="330" y="134" class="nlabel" text-anchor="middle">:PyModule</text>
+<text x="330" y="192" class="prop" text-anchor="middle">module_name</text>
+<text x="330" y="208" class="prop" text-anchor="middle">content_hash</text>
+<circle cx="330" cy="470" r="46" fill="#F79767" stroke="#ffffff" stroke-width="2.5" filter="url(#nshadow)"/>
+<circle cx="330" cy="470" r="46" fill="url(#gloss)"/>
+<text x="330" y="466" class="nlabel" text-anchor="middle">:PyClass</text>
+<text x="330" y="483" class="nsub" text-anchor="middle">:PySymbol</text>
+<text x="330" y="532" class="prop" text-anchor="middle">name</text>
+<text x="330" y="548" class="prop" text-anchor="middle">base_classes</text>
+<circle cx="120" cy="470" r="46" fill="#57C7E3" stroke="#ffffff" stroke-width="2.5" filter="url(#nshadow)"/>
+<circle cx="120" cy="470" r="46" fill="url(#gloss)"/>
+<text x="120" y="474" class="nlabel" text-anchor="middle">:PyAttribute</text>
+<text x="120" y="532" class="prop" text-anchor="middle">name</text>
+<text x="120" y="548" class="prop" text-anchor="middle">type</text>
+<circle cx="560" cy="300" r="46" fill="#8DCC93" stroke="#ffffff" stroke-width="2.5" filter="url(#nshadow)"/>
+<circle cx="560" cy="300" r="46" fill="url(#gloss)"/>
+<text x="560" y="296" class="nlabel" text-anchor="middle">:PyCallable</text>
+<text x="560" y="313" class="nsub" text-anchor="middle">:PySymbol</text>
+<text x="560" y="362" class="prop" text-anchor="middle">signature</text>
+<text x="560" y="378" class="prop" text-anchor="middle">cyclomatic_complexity</text>
+<circle cx="560" cy="470" r="46" fill="#ECB5C9" stroke="#ffffff" stroke-width="2.5" filter="url(#nshadow)"/>
+<circle cx="560" cy="470" r="46" fill="url(#gloss)"/>
+<text x="560" y="474" class="nlabel" text-anchor="middle">:PyDecorator</text>
+<text x="560" y="532" class="prop" text-anchor="middle">name</text>
+<circle cx="790" cy="130" r="46" fill="#FFC454" stroke="#ffffff" stroke-width="2.5" filter="url(#nshadow)"/>
+<circle cx="790" cy="130" r="46" fill="url(#gloss)"/>
+<text x="790" y="134" class="nlabel" text-anchor="middle">:PyCallSite</text>
+<text x="790" y="192" class="prop" text-anchor="middle">method_name</text>
+<text x="790" y="208" class="prop" text-anchor="middle">receiver_type</text>
+<circle cx="975" cy="300" r="46" fill="#569480" stroke="#ffffff" stroke-width="2.5" filter="url(#nshadow)"/>
+<circle cx="975" cy="300" r="46" fill="url(#gloss)"/>
+<text x="975" y="304" class="nlabel" text-anchor="middle">:PyExternal</text>
+<text x="975" y="362" class="prop" text-anchor="middle">name</text>
+<text x="975" y="378" class="prop" text-anchor="middle">module</text>
+</svg>
+  <figcaption>
+    The analysis is a <strong>Neo4j property graph</strong>: every node carries a
+    <em>label</em> (its color) and <em>properties</em>; every relationship carries a
+    <em>type</em>. The dashed ring marks an <code>entrypoint</code>;
+    the <span class="calls">PY_CALLS</span> edge is the resolved call graph.
+  </figcaption>
+</figure>
+
+<style>
+  .pgraph-figure {
+    margin: 1.5rem 0 2rem;
+    padding: 0.5rem 0.25rem 0.25rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 14px;
+    background:
+      radial-gradient(120% 80% at 15% 0%, color-mix(in srgb, var(--sl-color-accent-low) 55%, transparent), transparent 60%),
+      var(--sl-color-black);
+    overflow: hidden;
+  }
+  .pgraph { width: 100%; height: auto; display: block; }
+  /* edges + labels adapt to theme */
+  .pgraph { --pg-edge: var(--sl-color-gray-3); }
+  .pgraph .rel { stroke: var(--pg-edge); stroke-width: 2.2; }
+  .pgraph .rel-accent { stroke: #DA7194; stroke-width: 3.2; }
+  .pgraph .nlabel { fill: #fff; font: 700 14px/1.1 ui-sans-serif, system-ui, sans-serif; letter-spacing: .2px; }
+  .pgraph .nsub { fill: rgba(255,255,255,.92); font: 600 12px ui-sans-serif, system-ui, sans-serif; }
+  .pgraph .prop { fill: var(--sl-color-gray-2); font: 500 12px ui-monospace, "SFMono-Regular", monospace; }
+  .pgraph .rtype { fill: #fff; font: 700 11px ui-monospace, monospace; letter-spacing: .3px; }
+  .pgraph .pill { fill: #3a4252; stroke: rgba(255,255,255,.18); }
+  .pgraph .pill-accent { fill: #DA7194; }
+  .pgraph .badge { fill: #ffd98a; font: 700 11px ui-monospace, monospace; }
+  .pgraph-figure figcaption {
+    color: var(--sl-color-gray-2);
+    font-size: 0.85rem; line-height: 1.5;
+    padding: 0.4rem 1rem 0.75rem; text-align: center;
+  }
+  .pgraph-figure .calls { color: #DA7194; font-weight: 700; font-family: ui-monospace, monospace; }
+</style>

src/content/docs/extending/analysis-passes.mdx

@@ -45,6 +45,8 @@ Passes declare capability tokens — free-form strings — in `provides` and `re
 
 Passes hand derived facts to each other through `ctx.shared`, keyed by capability token: the provider writes `ctx.shared["odoo.model_identity"] = ...`; the consumer reads it back. `ctx.shared` is the one mutable part of the otherwise-frozen context.
 
+The pipeline produces a single enriched `PyApplication`. That in-memory model is what `canpy` then emits — as `analysis.json` by default, or projected into a Neo4j property graph with `--emit neo4j`. Either way it is the *same* model, so your pass's entrypoints and synthetic edges flow through both targets unchanged:
+
 ```mermaid
 flowchart LR
     A["pass A
@@ -53,6 +55,12 @@ requires: model_identity"]
     A --> M[merge into app]
     B --> M
     M --> N[next pass sees both]
+    N --> IR["enriched PyApplication (IR)"]
+    IR -->|"--emit json"| J["analysis.json"]
+    IR -->|"--emit neo4j"| G["labeled property graph
+(:PyApplication / PY_CALLS)"]
+    G -.->|"no --neo4j-uri"| SNAP["graph.cypher snapshot"]
+    G -.->|"--neo4j-uri (Bolt)"| LIVE["live incremental push"]
 ```
 
 ## The AnalysisContext
@@ -144,6 +152,10 @@ class OdooDispatchPass(AnalysisPass):
 
 Core never interprets your `provenance` tokens, `detection_source` values, or `tags` keys — they round-trip through `analysis.json` untouched, so downstream consumers (or an LLM) can reason over them.
 
+<Aside type="note" title="Provenance survives the Neo4j projection">
+When you emit to Neo4j with `--emit neo4j`, each synthetic `PyCallEdge` becomes a `PY_CALLS` relationship, and your `provenance` token is preserved on its `provenance` property (alongside the integer `weight`) — so an extension's edges stay attributable whether a consumer reads `analysis.json` or queries the property graph. See [Output schema](/codeanalyzer-python/reference/schema/) for the projected node and relationship types.
+</Aside>
+
 ## Registering your pass
 
 Declare the entry point in your package's `pyproject.toml`. Each entry point must resolve to an `AnalysisPass` subclass (or an instance).
@@ -158,9 +170,9 @@ odoo-dispatch = "my_package.passes:OdooDispatchPass"
 
 1. **Install your package** into the same environment as codeanalyzer (`pip install -e .`).
 
-2. **Run codeanalyzer normally.** `discover_passes()` finds your entry point, instantiates it, and the registry orders it among the built-ins.
+2. **Run `canpy` normally.** `discover_passes()` finds your entry point, instantiates it, and the registry orders it among the built-ins.
 
-3. **Check the artifact.** Your entrypoints appear under `app.entrypoints[framework]`; your edges appear in `app.call_graph` with your provenance token.
+3. **Check the artifact.** Your entrypoints appear under `app.entrypoints[framework]`; your edges appear in `app.call_graph` with your provenance token — and likewise on the `PY_CALLS` edges if you emit to Neo4j.
 
 </Steps>
 

src/content/docs/extending/overview.mdx

@@ -10,7 +10,7 @@ import { Badge, CardGrid, LinkCard, Aside } from "@astrojs/starlight/components"
   <Badge text="Help wanted" variant="note" />
 </p>
 
-After the symbol table and base call graph are built, codeanalyzer runs a pipeline of **analysis passes** — whole-application steps that contribute framework-dispatched **entrypoints** and **synthetic call edges** the static graph can't observe. Out-of-tree packages register their own through the `codeanalyzer.analysis_passes` entry-point group, so you can teach codeanalyzer a new framework or a new dispatch mechanism **without forking it**.
+After the symbol table and base call graph are built, `canpy` runs a pipeline of **analysis passes** — whole-application steps that contribute framework-dispatched **entrypoints** and **synthetic call edges** the static graph can't observe. Out-of-tree packages register their own through the `codeanalyzer.analysis_passes` entry-point group, so you can teach `canpy` a new framework or a new dispatch mechanism **without forking it**.
 
 This is the youngest part of codeanalyzer-python: the **mechanism** exists, but **no concrete framework finder ships yet**. `BUILTIN_PASS_FACTORIES` is empty, so until a finder is written, `PyApplication.entrypoints` comes back empty. The frameworks named on this page (Flask, FastAPI, Celery, Click, gRPC, …) are the **roadmap** — the shapes finders will target — not detection that runs today. Writing the first finder for a framework is itself the contribution.
 
@@ -37,6 +37,10 @@ This is the youngest part of codeanalyzer-python: the **mechanism** exists, but
 **Not built yet:** any concrete finder. No framework — Flask, FastAPI, Celery, Click, gRPC, Django, or otherwise — is detected out of the box. Synthetic-edge passes are likewise scaffolding-only. Everything framework-specific is roadmap.
 </Aside>
 
+<Aside type="note" title="Synthetic edges carry into the graph">
+A synthetic call edge contributed by a pass is tagged with a **provenance** token (the pass's framework/extension name). That token survives projection: when you run `canpy --emit neo4j`, it lands in the `provenance` array on the `PY_CALLS` relationship, exactly as it appears in `analysis.json`. So a consumer can filter the call graph by who contributed each edge — `jedi`, `codeql`, or your extension — whether it reads `analysis.json` or queries the Neo4j graph.
+</Aside>
+
 <Aside type="tip" title="Help wanted">
 The first concrete finder is the contribution. Good starting points: an `AbstractEntrypointFinder` for a framework you use, a synthetic-edge pass for an ORM or dispatch pattern the static graph misses, or test fixtures to pin a finder's behavior. Open an issue or PR on [GitHub](https://github.com/codellm-devkit/codeanalyzer-python), or come talk it through on [Discord](https://discord.gg/zEjz9YrmqN).
 </Aside>