Update docs

Signed-off-by: Rahul Krishna <rkrsn@ibm.com>

Author: rahlk

src/content/docs/backends.mdx

@@ -20,7 +20,7 @@ flowchart LR
 This separation lets a single `analysis` API span languages. The SDK does not parse code itself; it invokes the appropriate backend, then maps the backend JSON onto typed models (`JApplication`, `PyModule`, and others). A backend that emits the canonical JSON makes its language available to the SDK with only binding work required. See [Add a language backend](/contributing/add-language-backend/).
 
 <Aside type="note" title="Backends are managed by the SDK">
-The SDK manages the backend automatically: it downloads the Java JAR and provisions the Python analyzer in a virtualenv. These pages document the backend layer for readers who want to understand or contribute to it.
+The SDK manages the backend automatically: each `codeanalyzer-*` backend binary ships with its packaged PyPI dependency (the JVM-free Java backend runs via `python -m codeanalyzer_java`; the TypeScript binary ships in `codeanalyzer-typescript`), and the Python analyzer is provisioned in a virtualenv. There is no separate JAR download or `analysis_backend_path` override. These pages document the backend layer for readers who want to understand or contribute to it.
 </Aside>
 
 This is the **backend** layer. For the SDKs that consume it, see the [SDKs overview](/reference/sdks/).

src/content/docs/backends/codeanalyzer-java.mdx

@@ -18,7 +18,7 @@ codeanalyzer-java is a **standalone JAR tool** that takes a Java project (or a s
 - **Comments & Javadoc**: Extracted and positioned for each entity
 - **Entry points**: Main methods and framework-identified entry points (REST endpoints, Struts actions)
 
-The Python SDK invokes this JAR, parses the JSON, and wraps it in `JavaAnalysis`, so callers interact with an `analysis` object rather than the backend directly.
+The Python SDK invokes this backend, parses the JSON, and wraps it in `JavaAnalysis`, so callers interact with an `analysis` object rather than the backend directly. The backend is a JVM-free binary that ships with the packaged `codeanalyzer-java` PyPI dependency and is run via `python -m codeanalyzer_java`; there is no separate JAR download or `analysis_backend_path` override.
 
 ## Architecture
 
@@ -329,10 +329,10 @@ java -jar codeanalyzer-2.3.7.jar \
 
 ## How the Python SDK uses it
 
-The Python SDK (`JavaAnalysis`) automates JAR invocation:
+The Python SDK (`JavaAnalysis`) automates backend invocation:
 
-1. **JAR discovery**: If `analysis_backend_path` is not provided, searches the package resources for `codeanalyzer-*.jar` (bundled)
-2. **Invocation**: Calls `java -jar codeanalyzer-*.jar -i <project> -a <level> -o <tmpdir>` (or reads from stdout)
+1. **Backend discovery**: The JVM-free backend ships with the packaged `codeanalyzer-java` PyPI dependency and is run via `python -m codeanalyzer_java`. There is no `analysis_backend_path` override anymore.
+2. **Invocation**: Calls the backend with `-i <project> -a <level> -o <cache_dir>` (or reads from stdout)
 3. **JSON parsing**: Deserializes the output into Pydantic models (`JApplication`, `JType`, `JCallable`, etc.)
 4. **Facade**: Wraps the models in `JavaAnalysis`, exposing query methods like `get_classes()`, `get_call_graph()`, `get_callers()`
 
@@ -341,29 +341,49 @@ from cldk import CLDK
 from cldk.analysis import AnalysisLevel
 
 # Behind the scenes:
-# 1. CLDK detects language="java" -> uses JCodeanalyzer backend
-# 2. JCodeanalyzer finds/downloads codeanalyzer-2.3.7.jar
-# 3. Invokes: java -jar ... -i commons-cli -a 2 -o /tmp/...
-# 4. Parses JSON -> JApplication (symbol_table + call_graph)
-# 5. Returns JavaAnalysis
+# 1. CLDK.java(...) selects the codeanalyzer-java backend (default CodeAnalyzerConfig)
+# 2. Runs the packaged backend: python -m codeanalyzer_java -i commons-cli -a 2 -o <cache_dir>
+# 3. Parses JSON -> JApplication (symbol_table + call_graph)
+# 4. Returns JavaAnalysis
 
-analysis = CLDK(language="java").analysis(
+analysis = CLDK.java(
     project_path="commons-cli",
     analysis_level=AnalysisLevel.call_graph,
-    analysis_backend_path="/path/to/jar/dir"  # Optional: custom JAR location
 )
 ```
 
-To point at a custom JAR location (for example, a locally built version):
+The old `CLDK(language="java").analysis(...)` form still works but is **deprecated**; prefer the `CLDK.java(...)` factory shown above. The `from cldk import CLDK` import is unchanged.
+
+To control where analysis artifacts are cached, pass a backend config:
 
 ```python
-analysis = CLDK(language="java").analysis(
+from cldk import CLDK
+from cldk.analysis import AnalysisLevel
+from cldk.analysis.commons.backend_config import CodeAnalyzerConfig
+
+analysis = CLDK.java(
     project_path="my_project",
     analysis_level=AnalysisLevel.call_graph,
-    analysis_backend_path="/path/containing/codeanalyzer-custom.jar"
+    backend=CodeAnalyzerConfig(cache_dir="/tmp/analysis-cache"),
 )
 ```
 
+### Keyword arguments
+
+`CLDK.java(...)` accepts `project_path`, `analysis_level`, `target_files`, and `eager`. The backend is selected by the **type** of the `backend=` config; for Java the only backend is the in-memory codeanalyzer (`CodeAnalyzerConfig`), so omit `backend=` for the default. Pass `backend=CodeAnalyzerConfig(cache_dir=...)` only to override where artifacts are cached. Caching is **on by default**; the cache root defaults to `<project>/.codeanalyzer` and artifacts are written under a language-keyed subdirectory (`<cache_dir>/java/`).
+
+Java also accepts `source_code=...` for analyzing a single Java source string, but this is **deprecated**; prefer `project_path`.
+
+```python
+analysis = CLDK.java(source_code="public class Test {}")  # deprecated; prefer project_path
+```
+
+Import the config objects from:
+
+```python
+from cldk.analysis.commons.backend_config import CodeAnalyzerConfig
+```
+
 ## Building & testing
 
 To build codeanalyzer-java from source:

src/content/docs/backends/codeanalyzer-python.mdx

@@ -174,7 +174,7 @@ codeanalyzer --input /path/to/my_pkg [OPTIONS]
 ```
 
 <Aside type="note">
-The CLI is intended for backend developers and direct analysis runs. CLDK SDK users invoke the backend indirectly through `CLDK(language="python").analysis(...)`, which manages the virtualenv and invokes the CLI internally.
+The CLI is intended for backend developers and direct analysis runs. CLDK SDK users invoke the backend indirectly through `CLDK.python(...)`, which manages the virtualenv and runs the analysis internally.
 </Aside>
 
 ### Options
@@ -233,7 +233,7 @@ Analyzes only `src/handlers.py`.
 
 ## How the SDK consumes it
 
-A call to `CLDK(language="python").analysis(project_path="my_pkg")` in the Python SDK proceeds as follows:
+A call to `CLDK.python(project_path="my_pkg")` in the Python SDK proceeds as follows:
 
 1. **Virtualenv provisioning**: CLDK detects or installs `codeanalyzer-python` into a managed virtualenv in the cache directory (default: `<project_dir>/.codeanalyzer/venv`).
 
@@ -253,11 +253,12 @@ A call to `CLDK(language="python").analysis(project_path="my_pkg")` in the Pytho
 ```python
 from cldk import CLDK
 from cldk.analysis import AnalysisLevel
+from cldk.analysis.commons.backend_config import PyCodeAnalyzerConfig
 
-analysis = CLDK(language="python").analysis(
+analysis = CLDK.python(
     project_path="my_pkg",
     analysis_level=AnalysisLevel.call_graph,
-    use_codeql=True,  # optional; merges CodeQL edges
+    backend=PyCodeAnalyzerConfig(use_codeql=True),  # optional; merges CodeQL edges
 )
 
 # Query the symbol table
@@ -281,14 +282,55 @@ cat results/analysis.json | jq '.symbol_table | keys'
   </TabItem>
 </Tabs>
 
+### Choosing a backend
+
+The backend is selected by the **type** of the `backend=` config passed to `CLDK.python(...)`:
+
+- **In-memory codeanalyzer** (default): omit `backend=`, or pass `backend=PyCodeAnalyzerConfig(...)`. The Python-only call-graph knobs `use_codeql=...` and `use_ray=...` live on this config, as does `cache_dir=...`.
+- **Read-only Neo4j**: pass `backend=Neo4jConnectionConfig(...)` to query a graph populated out of band (no local analysis is run).
+
+```python
+from cldk import CLDK
+from cldk.analysis.commons.backend_config import (
+    PyCodeAnalyzerConfig,
+    Neo4jConnectionConfig,
+)
+
+# In-memory backend with Ray + custom cache directory
+analysis = CLDK.python(
+    project_path="my_pkg",
+    backend=PyCodeAnalyzerConfig(
+        use_codeql=True,
+        use_ray=True,
+        cache_dir="/tmp/analysis-cache",
+    ),
+)
+
+# Read-only Neo4j backend
+analysis = CLDK.python(
+    project_path="my_pkg",
+    backend=Neo4jConnectionConfig(
+        uri="bolt://localhost:7687",
+        username="neo4j",
+        password="neo4j",
+        database=None,
+        application_name="my_pkg",
+    ),
+)
+```
+
+`Neo4jConnectionConfig` is importable from `cldk.analysis.commons.backend_config` (and also from `cldk.analysis.python.neo4j`).
+
+`CLDK.python(...)` keeps the `project_path`, `analysis_level`, `target_files`, and `eager` keyword arguments. The old `CLDK(language="python").analysis(...)` form still works but is **deprecated**; prefer `CLDK.python(...)`. The `from cldk import CLDK` import is unchanged.
+
 ### Caching and virtualenv management
 
-- **Cache location**: Stored in `cache_dir/.codeanalyzer/` (default: `<project_dir>/.codeanalyzer/`).
-- **Virtualenv**: Auto-created at `.codeanalyzer/<project_name>/virtualenv/`. The backend installs dependencies from `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile`, etc.
+- **Cache location**: A single language-keyed `cache_dir` (default: `<project_dir>/.codeanalyzer`); Python artifacts live under `<cache_dir>/python/`. Set it via `backend=PyCodeAnalyzerConfig(cache_dir=...)`.
+- **Virtualenv**: Auto-created under the cache directory. The backend installs dependencies from `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile`, etc.
 - **Analysis cache**: Indexed by file content hash; unchanged files reuse cached results.
-- **CodeQL database**: Stored in `.codeanalyzer/codeql/` if `--codeql` is enabled; downloaded on first use.
+- **CodeQL database**: Stored under the cache directory if CodeQL is enabled; downloaded on first use.
 
-To force a clean rebuild, pass `--eager` (or `eager_analysis=True` in the SDK), or delete the cache directory.
+To force a clean rebuild, pass `eager=True` to `CLDK.python(...)` (or `--eager` on the CLI), or delete the cache directory.
 
 ## Design principles
 

src/content/docs/backends/codeanalyzer-ts.mdx

@@ -56,7 +56,7 @@ The `cants` CLI is available from **PyPI** and **Homebrew**. Both distribute a p
   </TabItem>
 </Tabs>
 
-The CLDK Python SDK depends on the PyPI package `codeanalyzer-typescript` to locate this backend; the package exposes `bin_path()`, which returns the path to the bundled binary.
+The CLDK Python SDK depends on the PyPI package `codeanalyzer-typescript` to locate this backend; the package exposes `bin_path()`, which returns the path to the bundled binary. There is no `analysis_backend_path` argument. To override the binary out of band (for example, a locally built `cants`), set the `$CODEANALYZER_TS_BIN` environment variable to its path; this is the sole override.
 
 <Aside type="note">
 The distributable is named **`codeanalyzer-typescript`** (the PyPI package and the Homebrew formula), but the command it installs on `PATH` is **`cants`**, the analyzer's binary name. Run `cants`, not `codeanalyzer-typescript`.
@@ -297,13 +297,13 @@ TypeScript includes several language-specific constructs that codeanalyzer-ts mo
 
 ## Python SDK integration
 
-TypeScript support in the Python SDK is **in development**. Once available, TypeScript projects will be analyzable through the same `CLDK` analysis API as Python and Java:
+TypeScript projects are analyzable through the same `CLDK` analysis API as Python and Java, via the `CLDK.typescript(...)` factory:
 
 ```python
 from cldk import CLDK
 from cldk.analysis import AnalysisLevel
 
-analysis = CLDK(language="typescript").analysis(
+analysis = CLDK.typescript(
     project_path="/path/to/ts/project",
     analysis_level=AnalysisLevel.call_graph,
 )
@@ -313,9 +313,42 @@ print(analysis.get_classes())      # Dict[str, TSClass]
 graph = analysis.get_call_graph()  # networkx.DiGraph
 ```
 
-<Aside type="note">
-The codeanalyzer-ts backend is complete and production-ready. The Python SDK integration is in progress on the `add-typescript-support` branch.
-</Aside>
+The old `CLDK(language="typescript").analysis(...)` form still works but is **deprecated**; prefer `CLDK.typescript(...)`. The `from cldk import CLDK` import is unchanged.
+
+### Choosing a backend
+
+`CLDK.typescript(...)` keeps the `project_path`, `analysis_level`, `target_files`, and `eager` keyword arguments. The backend is selected by the **type** of the `backend=` config:
+
+- **In-memory codeanalyzer** (default): omit `backend=`, or pass `backend=CodeAnalyzerConfig(cache_dir=...)` to override where artifacts are cached.
+- **Read-only Neo4j**: pass `backend=Neo4jConnectionConfig(...)` to query a graph populated out of band.
+
+```python
+from cldk import CLDK
+from cldk.analysis.commons.backend_config import (
+    CodeAnalyzerConfig,
+    Neo4jConnectionConfig,
+)
+
+# In-memory backend with a custom cache directory
+analysis = CLDK.typescript(
+    project_path="/path/to/ts/project",
+    backend=CodeAnalyzerConfig(cache_dir="/tmp/analysis-cache"),
+)
+
+# Read-only Neo4j backend
+analysis = CLDK.typescript(
+    project_path="/path/to/ts/project",
+    backend=Neo4jConnectionConfig(
+        uri="bolt://localhost:7687",
+        username="neo4j",
+        password="neo4j",
+        database=None,
+        application_name="my_project",
+    ),
+)
+```
+
+`Neo4jConnectionConfig` is importable from `cldk.analysis.commons.backend_config` (and also from `cldk.analysis.typescript.neo4j`).
 
 ## Schema invariants
 
@@ -330,7 +363,7 @@ This ensures every call-graph edge points to a real symbol-table entry.
 
 ## Caching and incremental analysis
 
-The analyzer maintains a cache under `<project>/.codeanalyzer/` (or `-c <dir>`), stamped with the analyzer version. The cache is invalidated on:
+The analyzer maintains a cache under a single language-keyed `cache_dir` (default: `<project>/.codeanalyzer`), with TypeScript artifacts under `<cache_dir>/typescript/`, stamped with the analyzer version. Caching is **on by default**. From the SDK, set the cache root via `backend=CodeAnalyzerConfig(cache_dir=...)`; on the CLI, use `-c <dir>`. The cache is invalidated on:
 - Analyzer version change
 - Any source file modification (content hash mismatch)
 - `--eager` flag (forces clean rebuild)

src/content/docs/cocoa.mdx

@@ -41,7 +41,7 @@ from cldk import CLDK
 from cldk.analysis import AnalysisLevel
 import networkx as nx
 
-analysis = CLDK(language="java").analysis(
+analysis = CLDK.java(
     project_path=".",
     analysis_level=AnalysisLevel.call_graph,   # needed for callers/reachability
 )
@@ -168,7 +168,7 @@ The trace is reconstructed from call-graph edges.
    from cldk.analysis import AnalysisLevel
    import networkx as nx
 
-   analysis = CLDK(language="java").analysis(
+   analysis = CLDK.java(
        project_path=".", analysis_level=AnalysisLevel.call_graph,
    )
    # ... query analysis (get_callers / get_callees / get_call_graph) and print() ...
@@ -203,7 +203,7 @@ The trace is reconstructed from call-graph edges.
      from cldk import CLDK
      from cldk.analysis import AnalysisLevel
 
-     analysis = CLDK(language="java").analysis(
+     analysis = CLDK.java(
          project_path=".", analysis_level=AnalysisLevel.call_graph,
      )
      callers = analysis.get_callers("<CLASS>", "<METHOD>")
@@ -230,7 +230,7 @@ The trace is reconstructed from call-graph edges.
      from cldk.analysis import AnalysisLevel
      import networkx as nx
 
-     analysis = CLDK(language="java").analysis(
+     analysis = CLDK.java(
          project_path=".", analysis_level=AnalysisLevel.call_graph,
      )
      cg = analysis.get_call_graph()