[rahlk]

Closes #14. Supersedes #8.

This PR rewrites the Python API reference (/reference/python-api/) for cldk 2.0.0, and adds two pages: "Results and errors" and "Tree-sitter utilities". It also updates the generator that writes the reference from the SDK docstrings, and it adds a link check to the build.

Merge order

Merge #15 first, then #16, then this PR, back to back.

• ci(api-docs): build the reference from the latest stable SDK tag #15. Without it, the deploy regenerates the reference from v2.0.0-rc.8 and installs griffe without the pin.
• docs: bring the guides, examples and install pages up to cldk 2.0.0 #16. This PR links to the install, quickstart and guide pages that docs: bring the guides, examples and install pages up to cldk 2.0.0 #16 updates. On astro alone, those pages still describe the release candidate.

Commits

The four commits are easier to review one by one:

1. scripts/gen_api_docs.py and the griffe pin. The generator changes are listed below.
2. The regenerated reference. Only the blocks between the CLDK:API markers change, plus the two new pages and their sidebar entries.
3. The authored text of all seven pages. No line between the markers changes in this commit.
4. starlight-links-validator and the edit link.

Each commit builds.

The pages

Each language page has three parts: an overview, a worked example on a pinned sample project, and the generated reference.

Page	What it gives a first-time reader
index.md	Install (Python 3.11 to 3.14, quoted extras, SYSTEM_PYTHON), how the three factories fit together, the reference pages, the shared and the language-only methods, analysis levels, the Python value-flow caveat
core.md	The factories and their keyword-only parameters, analysis levels, the local and Neo4j backends, the cache rules, an errors table, worked examples on Commons CLI 1.7.0, Flask 3.1.3 and Zod v4.6.7, and the upgrade from 1.5.0
python.md	PythonAnalysis on Flask: setup and SYSTEM_PYTHON, the four levels, names, the call graph, a worked example, a task table, Neo4j, errors
java.md	JavaAnalysis on Commons CLI: the java extra, the JDK and Maven, test sources, names (fully qualified parameter types), a worked example with taint, what Java refuses, the cache, Neo4j
typescript.md	TypeScriptAnalysis on Zod: what a run does to the project, levels, the cache trap, key formats, entrypoints, the Neo4j limit for declaration merging, errors
results.md (new)	Bounded results, paging, the result types, how to read a taint result, the default bounds, and the exceptions
treesitter.md (new)	TreesitterJava, TreesitterPython, TreesitterSanitizer, and the move from the 1.x source_code mode

Each page also has an "Errors in the generated reference" aside. It lists the SDK docstring errors that break user code, for example page.has_more, sl.truncated, create(String), and the CRUD accessors. Remove each item when the SDK fixes the docstring.

The generator

• Signatures. They show the keyword-only * and positional-only /. 57 public methods take keyword-only parameters, and the old signatures invited a TypeError. They also show default values as literals (page_size: int = 10000) and @staticmethod or @classmethod, and they wrap long lines.
• Returns sections. Each one is a single item (returns_multiple_items=False). Before, 103 of 124 split into one bullet per source line.
• Conversion to Markdown. Sphinx roles, :: literal blocks, RST links and .. deprecated:: become Markdown, Python code fences and Starlight asides. Prose dashes become commas or parentheses.
• Attribute tables. They merge the class docstring's descriptions, list inherited fields, and hide pydantic internals. Type aliases such as TSType get entries.
• Method index. Each facade class opens with a linked method index, because the method headings are below the page TOC.
• New sections. AnalysisLevel and the backend configs (core), the Java projections and enums, and the two new pages.
• Filters to review. Bracketed spec ids such as "(leg 1.5, E6-E8)" are stripped from the docstring text, because a reader cannot look them up. Two TreesitterSanitizer doctests that fail on cldk 2.0.0 are left out (FAILING_EXAMPLES) while the docstring holds them word for word.
• Determinism. Output is byte-identical between runs. A run like the deploy run (Python 3.12, python-sdk at v2.0.0, scripts/requirements.txt) gives the committed pages.

How the changes were checked

• Samples. Every sample ran on cldk==2.0.0 from PyPI, on private copies of the pinned samples. The Neo4j samples ran on a private Neo4j instance.
• Review. For each page, a runtime reviewer ran every block and an editorial reviewer checked the text and the style rules. A fixer and a recheck followed. A final pass checked these pages against docs: bring the guides, examples and install pages up to cldk 2.0.0 #16 for consistency.
• Spot check. I reran the core.md worked example myself. Every output matched: 75 classes, 652 nodes and 1980 edges on JDK 17, 31 main classes, 46 Flask classes, 53 Zod classes.
• Build. The build passes with the new link validator ("All internal links are valid").
• Merged state. A build of astro with ci(api-docs): build the reference from the latest stable SDK tag #15, docs: bring the guides, examples and install pages up to cldk 2.0.0 #16 and this PR merged, after npm ci from the committed lockfile, passes with 35 pages and 0 broken links.

Open items

• No workflow builds a pull request. A new SDK release that renames a linked method fails the next deploy, which is the intent of the validator. A pull_request build would catch it earlier.
• The generated text keeps maintainer notes, benchmark names and modal verbs from the SDK docstrings. Notes on the pages tell readers to ignore them.
• 22 TypeScriptAnalysis methods have no docstring, so their rows in the method index have no summary.

SDK problems found on the way

The docs work around these, and each one needs an SDK or analyzer fix:

1. CLDK.python() raises RuntimeError in a run from a virtual environment. codeanalyzer-python reads sys.base_executable instead of sys._base_executable. Present in 1.5.3 through 1.6.2. The pages give the SYSTEM_PYTHON workaround.
2. TypeScript reuses a cached analysis at any level. It also reuses one after source edits, and a target_files run writes over it. The pages tell readers to pass eager=True.
3. Python and TypeScript taint and resolve_value raise SelectorNotInGraph below the needed level. They do this for a correct name, instead of giving the level message.
4. The unresolved ledger of taint is always empty. No backend writes unresolved_dispatch.
5. The factories raise three different exceptions without project_path.
6. The docstring errors listed in the asides above.