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 — `codeanalyzer` 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.0.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

@@ -19,9 +19,9 @@ export default defineConfig({
     }),
     starlight({
       title: "codeanalyzer-java",
-      tagline: "WALA + Javaparser static analysis for enterprise Java, as one JSON schema.",
+      tagline: "WALA + Javaparser static analysis for enterprise Java — one JSON artifact or a queryable Neo4j graph.",
       description:
-        "codeanalyzer-java is the JVM static-analysis backend behind CodeLLM-DevKit's Java support: a standalone JAR that turns a Java project into a symbol table and call graph, emitted as one versioned JSON schema.",
+        "codeanalyzer-java is the JVM static-analysis backend behind CodeLLM-DevKit's Java support: a standalone JAR that turns a Java project into a symbol table and call graph, emitted as one versioned analysis JSON artifact or projected into a queryable Neo4j property graph.",
       logo: {
         src: "./src/assets/logo.png",
         replacesTitle: true,
@@ -97,6 +97,7 @@ export default defineConfig({
             { label: "Analysis levels", slug: "guides/analysis-levels" },
             { label: "Build integration", slug: "guides/build-integration" },
             { label: "Incremental analysis", slug: "guides/incremental-analysis" },
+            { label: "Neo4j output", slug: "guides/neo4j-output" },
           ],
         },
         {
@@ -112,6 +113,7 @@ export default defineConfig({
             { label: "Overview", slug: "schema" },
             { label: "Symbol table", slug: "schema/symbol-table" },
             { label: "Call graph", slug: "schema/call-graph" },
+            { label: "Neo4j graph", slug: "schema/neo4j-graph" },
           ],
         },
         {

src/components/Neo4jPropertyGraph.astro

@@ -0,0 +1,121 @@
+---
+// AUTO-GENERATED property-graph hero for java. 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-java · 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="-39.0" y="-11" width="78.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">J_HAS_UNIT</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="-56.5" y="-11" width="113.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">J_DECLARES_TYPE</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="-42.5" y="-11" width="85.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">J_HAS_FIELD</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="-53.0" y="-11" width="106.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">J_HAS_CALLABLE</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">J_HAS_PARAMETER</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="-53.0" y="-11" width="106.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">J_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="-49.5" y="-11" width="99.0" height="22" rx="11" class="pill"/><text x="0" y="4" class="rtype" text-anchor="middle">J_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="-28.5" y="-11" width="57.0" height="22" rx="11" class="pill-accent"/><text x="0" y="4" class="rtype" text-anchor="middle">J_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">:JApplication</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">:JCompilationUnit</text>
+<text x="330" y="192" class="prop" text-anchor="middle">file_path</text>
+<text x="330" y="208" class="prop" text-anchor="middle">package_name</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">:JType</text>
+<text x="330" y="483" class="nsub" text-anchor="middle">:JSymbol</text>
+<text x="330" y="532" class="prop" text-anchor="middle">fqn</text>
+<text x="330" y="548" class="prop" text-anchor="middle">is_interface</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">:JField</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="53" fill="none" stroke="#FFC454" stroke-width="3" stroke-dasharray="5 5" opacity="0.95"/>
+<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">:JCallable</text>
+<text x="560" y="313" class="nsub" text-anchor="middle">:JSymbol</text>
+<g transform="translate(560,238)"><rect x="-52" y="-12" width="104" height="20" rx="10" fill="#1b1b2b" opacity="0.92"/><text x="0" y="2" class="badge" text-anchor="middle">★ :JEntrypoint</text></g>
+<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">:JParameter</text>
+<text x="560" y="532" class="prop" text-anchor="middle">name</text>
+<text x="560" y="548" class="prop" text-anchor="middle">type</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">:JCallSite</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">:JCallable</text>
+<text x="975" y="362" class="prop" text-anchor="middle">name</text>
+<text x="975" y="378" class="prop" text-anchor="middle">is_entrypoint</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>:JEntrypoint</code>;
+    the <span class="calls">J_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/frameworks/crud.mdx

@@ -79,15 +79,42 @@ These come from `EntityManager.createQuery(String)` and `EntityManager.createNam
 CRUD data is part of the symbol table, so it's available at [analysis level 1](/codeanalyzer-java/guides/analysis-levels/) — you don't need a call graph to enumerate persistence operations across the app.
 </Aside>
 
+## In the Neo4j graph
+
+When you project the analysis with `--emit neo4j`, CRUD detection is not flattened into the callable — it becomes **first-class graph structure**. Each detected operation is a `:JCrudOperation` node and each query a `:JCrudQuery` node, hung off its owning `:JCallable` or `:JCallSite`:
+
+```cypher
+(:JCallable | :JCallSite)-[:J_HAS_CRUD_OPERATION]->(:JCrudOperation)
+(:JCallable | :JCallSite)-[:J_HAS_CRUD_QUERY]->(:JCrudQuery)
+```
+
+That turns "where does this application write to persistent storage?" into a Cypher traversal across the whole graph — and, once many applications share one database, across the entire portfolio. For example, every method that issues a write:
+
+```cypher
+MATCH (c:JCallable)-[:J_HAS_CRUD_OPERATION]->(op:JCrudOperation)
+WHERE op.operation_type IN ['CREATE', 'UPDATE', 'DELETE']
+RETURN c.signature, op.operation_type
+```
+
+`JCrudOperation` exposes `operation_type` along with the `target_table`, `involved_columns`, `condition`, and `joined_tables` properties — keep in mind those last four are reserved (see above), so today you filter on `operation_type`. See the [Neo4j graph-schema reference](/codeanalyzer-java/schema/neo4j-graph/) for the full node and relationship inventory.
+
 ## Using it downstream
 
 ```python
-analysis = CLDK(language="java").analysis(project_path="my-app")
+from cldk import CLDK
+from cldk.analysis import AnalysisLevel
+
+analysis = CLDK.java(
+    project_path="my-app",
+    analysis_level=AnalysisLevel.symbol_table,
+)
 
 for cls in analysis.get_classes():
     for sig, m in analysis.get_methods_in_class(cls).items():
         for op in m.crud_operations:
             print(f"{op.operation_type} at {cls}:{op.line_number}")
 ```
 
+The same query works unchanged against a graph that was produced out of band: pass a `Neo4jConnectionConfig` instead of `project_path` and the read-only Neo4j backend reconstructs the identical models — no JDK, native binary, or project source required. Set `application_name` to the `--app-name` the graph was loaded with. See the [Neo4j graph output guide](/codeanalyzer-java/guides/neo4j-output/) for the full read-back flow.
+
 Combine with [entry-point](/codeanalyzer-java/frameworks/entry-points/) and call-graph data to answer questions like "which externally-reachable methods perform writes?"

src/content/docs/frameworks/entry-points.mdx

@@ -59,7 +59,7 @@ WALA builds the call graph by traversing outward from entry points. If a project
 
 ## Using entry points downstream
 
-Once analyzed, you can filter on the flags to drive reachability. Via the Python SDK:
+Once analyzed, you can filter on the flags to drive reachability. Via the Python SDK, against an in-process analysis:
 
 ```python
 analysis = CLDK(language="java").analysis(
@@ -77,3 +77,38 @@ entrypoints = [
 ```
 
 Seed a `networkx` reachability query from these to ask whether a sink is reachable from any externally-invocable method.
+
+## Entry points in the Neo4j projection
+
+When you project to a Neo4j property graph with [`--emit neo4j`](/codeanalyzer-java/guides/neo4j-output/), the `is_entrypoint` / `is_entrypoint_class` properties are still carried on the `:JCallable` and `:JType` nodes — but the projection *also* layers a marker label, `:JEntrypoint`, onto the owning callable (and entry-point class). That turns reachability seeding into a one-line `MATCH` instead of a property filter:
+
+```cypher
+// Every entry-point method in one application — the reachability seeds
+MATCH (a:JApplication {name: 'daytrader8'})-[:J_HAS_UNIT]->(:JCompilationUnit)
+      -[:J_DECLARES_TYPE]->(:JType)-[:J_HAS_CALLABLE]->(c:JCallable:JEntrypoint)
+RETURN c.signature
+```
+
+From there you traverse `J_CALLS` edges (present once you analyze at [level 2](/codeanalyzer-java/guides/analysis-levels/)) to ask the same reachability question entirely in Cypher, across every application in the database. Reading the seeds back through the SDK is identical to the in-process path above — point the facade at the graph and the same typed `JCallable` objects come back, with no JDK, native binary, or project source on the consumer:
+
+```python
+from cldk import CLDK
+from cldk.analysis import AnalysisLevel
+from cldk.analysis.commons.backend_config import Neo4jConnectionConfig
+
+analysis = CLDK.java(
+    analysis_level=AnalysisLevel.call_graph,
+    backend=Neo4jConnectionConfig(
+        uri="bolt://localhost:7687",
+        username="neo4j",
+        password="neo4j",              # or set NEO4J_PASSWORD
+        application_name="daytrader8",  # must match the --app-name the graph was loaded with
+    ),
+)
+
+entrypoints = analysis.get_entry_point_methods()
+```
+
+<Aside type="note" title="Where the labels and properties are defined">
+`:JEntrypoint` and the `is_entrypoint` / `is_entrypoint_class` properties are part of the versioned graph contract. For the full node-label and relationship inventory, see the [Neo4j graph schema](/codeanalyzer-java/schema/neo4j-graph/).
+</Aside>

src/content/docs/guides/analysis-levels.mdx

@@ -45,6 +45,12 @@ See [Build integration](/codeanalyzer-java/guides/build-integration/) for how th
 WALA needs entry points to anchor the graph. If a project has no `main(String[])` and no recognized framework entry points, the call graph can come back empty. See [Entry points](/codeanalyzer-java/frameworks/entry-points/) and [Troubleshooting](/codeanalyzer-java/troubleshooting/).
 </Aside>
 
+## The level also shapes the Neo4j graph
+
+The analysis level governs the [Neo4j projection](/codeanalyzer-java/guides/neo4j-output/) the same way it governs `analysis.json`. Level 1 emits the lossless symbol-table subgraph — compilation units, types, callables, fields, and the rest — with **no `J_CALLS` edges**. Level 2 adds the call graph as `(:JCallable)-[:J_CALLS]->(:JCallable)` relationships on top of it.
+
+This carries through the `-t` downgrade: because passing `-t` with `-a 2` forces level 1, a targeted incremental Bolt push (`--emit neo4j -t ...`) replaces only the changed units' symbol-table subgraphs and **carries no call edges**. Refresh `J_CALLS` with a full level-2 run.
+
 ## Choosing a level
 
 - **Use level 1** when you need the program's *structure*: listing classes and methods, reading method bodies, finding fields, extracting Javadoc, surveying imports, or doing incremental per-file updates.
@@ -57,4 +63,5 @@ WALA needs entry points to anchor the graph. If a project has no `main(String[])
   <LinkCard title="Symbol table schema" description="Everything level 1 produces." href="/codeanalyzer-java/schema/symbol-table/" />
   <LinkCard title="Call graph schema" description="The edge shape level 2 adds." href="/codeanalyzer-java/schema/call-graph/" />
   <LinkCard title="Incremental analysis" description="Level-1 target-file updates to an existing analysis.json." href="/codeanalyzer-java/guides/incremental-analysis/" />
+  <LinkCard title="Neo4j graph output" description="How each level projects into the property graph — and why level 2 adds J_CALLS." href="/codeanalyzer-java/guides/neo4j-output/" />
 </CardGrid>