docs: sync documentation with recent changes

[nadeem4]

Review window

Prior "docs: sync documentation with recent changes" PR: #167, created 2026-09-23T12:17:29Z, merged 2026-09-23T13:32:11Z. This reviews everything merged into main since then: #168-#179 (12 PRs).

That window landed the hosted Hugging Face Space (Dockerfile, publish workflow, link-preview card, commit-pinned rebuilds), several playground features (first-run key prompt, database switcher, a new Pipeline page, per-step model selection with per-provider keys), and two engine refactors (dropping the plan's ordinal fields, folding the standalone global_planner node into the decomposer). Each of those 12 PRs already updated most of its own docs as part of its commits — three parallel audits (hosted-demo/deploy docs, playground docs, architecture docs) cross-checked what remained against the current code on main, not just the PR diffs. This PR covers what survived that self-documentation.

Corrections

• docs/architecture/invariants.md: dropped the "Relation Schemas Have Unique Column Names" section (and its listing under the "State" category) — it referenced RelationSchema.validate_unique_columns(), but RelationSchema and ColumnSpec were deleted entirely by refactor(pipeline): build the execution DAG in the decomposer instead of its own node #177 and no longer exist anywhere in packages/.

  • Necessitated by: refactor(pipeline): build the execution DAG in the decomposer instead of its own node #177

• docs/architecture/failure_recovery.md (two spots) and docs/architecture/graph_state.md: dropped "global planner" from the lists of nodes that don't retry / have no local recovery, and dropped "DAG hashes" from what GraphState carries. refactor(pipeline): build the execution DAG in the decomposer instead of its own node #177 deleted the standalone global_planner pipeline node (folded into decomposer/dag.py, called from decomposer/node.py) and removed ExecutionDAG.dag_id/.content_hash — confirmed neither field exists in packages/nl2sql/src/nl2sql/execution/dag.py any more.

  • Necessitated by: refactor(pipeline): build the execution DAG in the decomposer instead of its own node #177

• docs/deployment/hosted-demo.md and deploy/huggingface/README.md: the query-timeout row said 60s/60. packages/nl2sql/src/nl2sql/cli/generators/env/templates.py:24-26 writes GLOBAL_TIMEOUT_SEC=300 into every demo project's .env.demo (with a comment explaining the 60s library default caused every live nl2sql demo question to hit PIPELINE_TIMEOUT), and deploy/huggingface/Dockerfile's ENV block never overrides it back down — so 300s is the actual effective default, both locally and on the hosted Space. Also noted in hosted-demo.md that a push to the workflow file itself (.github/workflows/publish_space.yml) redeploys the Space, per its own paths: trigger, which the prose previously left out.

  • Necessitated by: feat(demo): Dockerfile and Hugging Face Space configuration for the hosted demo #168, ci: rebuild the Space from the commit it deploys #174

• web/playground/README.md: the dev-proxy route list was missing GET /api/pipeline (added in feat(playground): a Pipeline page showing what each step does #171, fetched by App.jsx:122/190 and served by cli/demo/playground/app.py); the npm test paragraph named every tested helper module except src/pipeline.js, src/hostedKey.js and src/hostedModels.js (each has its own *.test.js, added in feat(playground): a Pipeline page showing what each step does #171/feat(playground): choose a model per step in the hosted demo, with a key per provider #173/feat(demo): hosted mode so a public demo can take each visitor's own key #165); and the "Scope" section's line count for src/router.js (110) was stale — it's 119 lines now.

  • Necessitated by: feat(playground): a Pipeline page showing what each step does #171, feat(playground): choose a model per step in the hosted demo, with a key per provider #173

• docs/getting_started/demo.md: the Pipeline page section said "the other nine are ordinary code." packages/nl2sql/src/nl2sql/pipeline/steps.py's PIPELINE_STEPS lists 13 steps total, and llm/providers.py's LLM_AGENTS names 5 as model-decided — leaving eight, not nine.

  • Necessitated by: feat(playground): a Pipeline page showing what each step does #171

• docs/configuration/llm.md: "the playground's Settings panel" → "Settings page", for consistency with the rest of the same paragraph and file, which correctly call it a page elsewhere (Settings has been its own routed page, #/settings, since an earlier PR).

  • Necessitated by: feat(playground): choose a model per step in the hosted demo, with a key per provider #173

Verification

• Every claim above was checked against the current code on main, not just the PR diffs.
• 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). This is the identical sandbox-only failure documented by every prior sync PR (docs: sync documentation with recent changes #60, docs: sync documentation with recent changes #77, docs: sync documentation with recent changes #103, docs: sync documentation with recent changes #135, docs: sync documentation with recent changes #167). With no other warnings, every content and nav validation passes.

Not touched

• CHANGELOG.md and version numbers (release-please owns those).
• Everything else in feat(demo): Dockerfile and Hugging Face Space configuration for the hosted demo #168-docs(readme): update for the hosted demo and fix the diagram on dark backgrounds #179 already kept in sync via each PR's own commits (verified, not assumed, by the three audits above).

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01SAJucHo2Qx4qVUgiyNVLwy

---

Generated by Claude Code