docs: sync documentation with recent changes

[nadeem4]

Review window

Prior "docs: sync documentation with recent changes" PR: #103, created 2026-09-21T12:12:49Z. This reviews everything merged into main since then: #102 and #104–#132 (23 PRs; #85 is release-please's own chore: release main and carries no doc-relevant content beyond CHANGELOG.md, which release-please owns).

Nearly all of that window (#104–#132, #102) already keeps README.md and docs/ in sync as part of each PR's own commits — verified with four independent audits covering the CLI reference and configuration tables, the REST API and Python SDK sections, the playground/demo docs, and the architecture/pipeline docs, each cross-checked against the current code on main, not just the PR diffs. #131 in particular rewrote README.md against the code as of its base and added drift tests (every CLI command and every FastAPI route must appear in the README), so the bulk of the surface is now self-verifying.

This PR covers the two gaps that survived that rewrite.

Corrections

• README.md — Python SDK section: the list of NL2SQL's public attributes (engine.query, engine.datasource, engine.llm, ...) omitted engine.auth. packages/nl2sql/src/nl2sql/public_api.py sets self.auth = AuthAPI(self._ctx) as a real public attribute, documented in docs/api/core/auth.md, and the same README paragraph already mentions the check_permissions/get_allowed_resources convenience methods that delegate to it. Added engine.auth to the list.

  • Necessitated by: docs(readme): restructure around quickstart, results, CLI, REST API and screenshots #131 (wrote this list; missed the one attribute)

• web/playground/README.md — Settings panel: the "Model for each step" bullet listed 4 per-node selector ids (#model-decomposer, #model-astplanner, #model-refiner, #model-answersynthesizer) but the panel now renders 5, one per entry in LLM_NODES (packages/nl2sql/src/nl2sql/cli/demo/playground/settings.py). Added the missing #model-datasourceresolver, matching the wording already correct in docs/getting_started/demo.md and README.md.

  • Necessitated by: feat(resolver): skip vector search for a single datasource and refuse questions no datasource can answer #121 (added the datasourceresolver node to LLM_NODES and updated docs/getting_started/demo.md, but missed this file)

Verification

• Every claim above was checked against the current code on main, not just the PR diffs.
• Four parallel audits covered: (1) CLI reference + configuration docs vs. Typer commands and Settings; (2) REST API + Python SDK docs vs. FastAPI routes and the public facade; (3) playground/demo docs vs. the demo backend routes and React components; (4) architecture/pipeline docs vs. RBAC, plan cache, resolver, sub-query status, generator, retrieval-trace and provider-adapter code. No other drift traceable to a PR in this window was found, and no new user-facing behavior from this window is undocumented.
• pip install -r requirements-docs.txt && python -m mkdocs build --strict: fails with exactly one warning — mkdocs-mermaid2-plugin cannot reach unpkg.com to verify the mermaid.js CDN URL, rejected by this sandbox's outbound network policy (connect_rejected, gateway 403 per $HTTPS_PROXY/__agentproxy/status). This is the same sandbox-only failure documented by the three prior sync PRs (docs: sync documentation with recent changes #60, docs: sync documentation with recent changes #77, docs: sync documentation with recent changes #103). With no other warnings, every content and nav validation passes.

Not touched

• CHANGELOG.md and version numbers (release-please owns those).

• Four older, pre-existing doc inaccuracies noticed along the way but not fixed here because they predate this review window (all introduced by test: add OpenAI-compatible fake LLM and first end-to-end CLI test #82, merged 2026-08-28, well before docs: sync documentation with recent changes #103):

  • docs/architecture/nodes/ast_planner_node.md and docs/architecture/nodes/answer_synthesizer_node.md name the LLM config agent keys as ast_planner/answer_synthesizer (with underscores) instead of the actual astplanner/answersynthesizer the registry looks up.
  • docs/architecture/subgraphs/sql_agent.md's routing step 5 description of the WARNING-only retry path is stale relative to docs/architecture/failure_recovery.md's correct description of the same code.
  • docs/configuration/datasources.md shows statement_timeout_ms/row_limit/max_bytes/tags as siblings of connection, but DatasourceConfig only keeps id/description/connection/options and silently drops unknown top-level keys — they need to be nested under options:.
  • docs/configuration/llm.md's first example uses model: gpt-5.2, which is not the default anywhere in the code (the rest of the same file, and README, correctly use gpt-5.4).

  Flagging all four for a maintainer follow-up since they're out of this PR's window.

• Everything else in feat(trace): record every node of a run to one file, show it, and replay it without the model #104–fix(generator): render string concatenation as the dialect's own, never numeric + #132 already kept in sync via each PR's own commits.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01HyeURBJcF67mhU6v1apcoD