docs: sync documentation with recent changes

[nadeem4]

Review window

Prior "docs: sync documentation with recent changes" PR: #60, created 2026-08-28T12:17:56Z. This reviews everything merged into main since then: #62–#75 (excluding #65/#67, which are release-please's own chore: release main PRs with no doc-relevant content beyond CHANGELOG.md, which release-please owns).

Most of those PRs (#62, #63, #64, #66, #68, #69, #70, #73, #74) already keep README.md/docs/ in sync as part of their own commits — verified by grepping the repo for every package-name reference #62 could have missed and checking each PR's own docs edits against the current code. This PR only covers what PR #75 missed, plus one API behavior change from #74 that had no doc coverage at all, plus a pre-existing nav gap that blocks mkdocs build --strict.

Corrections

• docs/architecture/pipeline.md and docs/architecture/failure_recovery.md: both said routing "raises PipelineError" when no compatible subgraph is found for a datasource. That was the exact bug fix(pipeline): raise a real exception when no subgraph matches #75 fixed — PipelineError is a pydantic BaseModel, not an exception, so that code actually raised TypeError: exceptions must derive from BaseException (see the regression test fix(pipeline): raise a real exception when no subgraph matches #75 added, test_scan_layer_router_raise_is_a_real_exception_not_a_type_error). fix(pipeline): raise a real exception when no subgraph matches #75 introduced PipelineExecutionError (an NL2SQLError carrying the PipelineError on .error) and updated docs/architecture/subgraphs/main_pipeline_graph.md in its own commit, but missed these two other files describing the same code path. Verified against packages/nl2sql/src/nl2sql/pipeline/routes.py and packages/nl2sql/src/nl2sql/common/exceptions.py on main.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/observability/error-handling.md: opened with the blanket claim "NL2SQL represents failures as structured PipelineError objects and propagates them through state," which is now incomplete — the router path added by fix(pipeline): raise a real exception when no subgraph matches #75 raises an exception instead. Added a paragraph naming PipelineExecutionError and how run_with_graph()'s crash handler folds it back into GraphState.errors as an UNKNOWN_ERROR. Verified against packages/nl2sql/src/nl2sql/pipeline/runtime.py.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/api/core/datasource.md: DatasourceAPI.get_datasource_details returns connection args, but the docs never mentioned that secret-shaped values are masked. fix(demo): make the docker demo datasources reachable #74 added mask_connection_args() (packages/nl2sql/src/nl2sql/datasources/registry.py), which replaces any connection-arg value whose key contains password, secret, token, or api_key with "***", and wired it into get_datasource_details (packages/nl2sql/src/nl2sql/api/datasource_api.py:126) as a security fix (a pydantic ValidationError used to be able to echo a plaintext password). Documented the masking so the public API surface doc matches actual behavior.

  • Necessitated by: fix(demo): make the docker demo datasources reachable #74

• mkdocs.yml: docs/getting_started/demo.md exists and is already linked from docs/getting_started/index.md ("Demo Data (CLI-first)"), but was never added to the nav: tree, which makes mkdocs build --strict fail with "pages exist... but are not included in the nav configuration." This predates the review window, but it blocks the strict build required by this task, so I registered it under Getting Started to match its existing sibling entries and its own link text in index.md.

Verification

• Every claim above was checked against the current code on main, not just the PR diffs.
• Grepped the whole repo for any remaining nl2sql[ / pip install nl2sql references that chore: rename the published distribution to nl2sql-engine #62's own docs commit might have missed — none found; all remaining hits are the import package name (nl2sql) or the packages/nl2sql source path, both correctly unchanged by the PyPI rename.
• pip install -r requirements-docs.txt && python -m mkdocs build --strict: fails locally with exactly one warning — mkdocs-mermaid2-plugin can't reach unpkg.com to verify the mermaid.js CDN URL. curl -sS "$HTTPS_PROXY/__agentproxy/status" confirms unpkg.com:443 is rejected by this sandbox's outbound network policy (connect_rejected, gateway 403), not by anything in the repo. This is the identical, sandbox-only failure PR docs: sync documentation with recent changes #60 documented and it was not a regression there either — the docs CI check (real internet access) already passed on main at feat(cli): add application container to docker demo; make mssql opt-in #59/fix(ci): build the API image from the repository root #70. With the nav fix above, that CDN check is the only warning the strict build produces; every content and nav validation passes.

Not touched

• CHANGELOG.md and version numbers (release-please owns those).
• packages/api/Dockerfile.dev — still flagged from docs: sync documentation with recent changes #60 as broken and out of scope for a docs fix (code issue, not a docs one).
• The doctor CLI command (fix(cli): repair the doctor connectivity check #72 fixed a bug in it, restoring behavior to what limited existing docs already implied) — it isn't documented anywhere in docs/ or README.md, but that gap predates this review window and fix(cli): repair the doctor connectivity check #72 didn't change what's documented, so it's out of scope here.

---

Generated by Claude Code

[nadeem4]

Review window

Prior "docs: sync documentation with recent changes" PR: #60, created 2026-08-28T12:17:56Z. This reviews everything merged into main since then: #62–#75 (excluding #65/#67, which are release-please's own chore: release main PRs with no doc-relevant content beyond CHANGELOG.md, which release-please owns).

Most of those PRs (#62, #63, #64, #66, #68, #69, #70, #73, #74) already keep README.md/docs/ in sync as part of their own commits — verified by grepping the repo for every package-name reference #62 could have missed and checking each PR's own docs edits against the current code. This PR only covers what PR #75 missed, plus one API behavior change from #74 that had no doc coverage at all, plus a pre-existing nav gap that blocks mkdocs build --strict.

Corrections

• docs/architecture/pipeline.md and docs/architecture/failure_recovery.md: both said routing "raises PipelineError" when no compatible subgraph is found for a datasource. That was the exact bug fix(pipeline): raise a real exception when no subgraph matches #75 fixed — PipelineError is a pydantic BaseModel, not an exception, so that code actually raised TypeError: exceptions must derive from BaseException (see the regression test fix(pipeline): raise a real exception when no subgraph matches #75 added, test_scan_layer_router_raise_is_a_real_exception_not_a_type_error). fix(pipeline): raise a real exception when no subgraph matches #75 introduced PipelineExecutionError (an NL2SQLError carrying the PipelineError on .error) and updated docs/architecture/subgraphs/main_pipeline_graph.md in its own commit, but missed these two other files describing the same code path. Verified against packages/nl2sql/src/nl2sql/pipeline/routes.py and packages/nl2sql/src/nl2sql/common/exceptions.py on main.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/observability/error-handling.md: opened with the blanket claim "NL2SQL represents failures as structured PipelineError objects and propagates them through state," which is now incomplete — the router path added by fix(pipeline): raise a real exception when no subgraph matches #75 raises an exception instead. Added a paragraph naming PipelineExecutionError and how run_with_graph()'s crash handler folds it back into GraphState.errors as an UNKNOWN_ERROR. Verified against packages/nl2sql/src/nl2sql/pipeline/runtime.py.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/api/core/datasource.md: DatasourceAPI.get_datasource_details returns connection args, but the docs never mentioned that secret-shaped values are masked. fix(demo): make the docker demo datasources reachable #74 added mask_connection_args() (packages/nl2sql/src/nl2sql/datasources/registry.py), which replaces any connection-arg value whose key contains password, secret, token, or api_key with "***", and wired it into get_datasource_details (packages/nl2sql/src/nl2sql/api/datasource_api.py:126) as a security fix (a pydantic ValidationError used to be able to echo a plaintext password). Documented the masking so the public API surface doc matches actual behavior.

  • Necessitated by: fix(demo): make the docker demo datasources reachable #74

• mkdocs.yml: docs/getting_started/demo.md exists and is already linked from docs/getting_started/index.md ("Demo Data (CLI-first)"), but was never added to the nav: tree, which makes mkdocs build --strict fail with "pages exist... but are not included in the nav configuration." This predates the review window, but it blocks the strict build required by this task, so I registered it under Getting Started to match its existing sibling entries and its own link text in index.md.

Verification

• Every claim above was checked against the current code on main, not just the PR diffs.
• Grepped the whole repo for any remaining nl2sql[ / pip install nl2sql references that chore: rename the published distribution to nl2sql-engine #62's own docs commit might have missed — none found; all remaining hits are the import package name (nl2sql) or the packages/nl2sql source path, both correctly unchanged by the PyPI rename.
• pip install -r requirements-docs.txt && python -m mkdocs build --strict: fails locally with exactly one warning — mkdocs-mermaid2-plugin can't reach unpkg.com to verify the mermaid.js CDN URL. curl -sS "$HTTPS_PROXY/__agentproxy/status" confirms unpkg.com:443 is rejected by this sandbox's outbound network policy (connect_rejected, gateway 403), not by anything in the repo. This is the identical, sandbox-only failure PR docs: sync documentation with recent changes #60 documented and it was not a regression there either — the docs CI check (real internet access) already passed on main at feat(cli): add application container to docker demo; make mssql opt-in #59/fix(ci): build the API image from the repository root #70. With the nav fix above, that CDN check is the only warning the strict build produces; every content and nav validation passes.

Not touched

• CHANGELOG.md and version numbers (release-please owns those).
• packages/api/Dockerfile.dev — still flagged from docs: sync documentation with recent changes #60 as broken and out of scope for a docs fix (code issue, not a docs one).
• The doctor CLI command (fix(cli): repair the doctor connectivity check #72 fixed a bug in it, restoring behavior to what limited existing docs already implied) — it isn't documented anywhere in docs/ or README.md, but that gap predates this review window and fix(cli): repair the doctor connectivity check #72 didn't change what's documented, so it's out of scope here.

---

Generated by Claude Code

[nadeem4]

Review window

Prior "docs: sync documentation with recent changes" PR: #60, created 2026-08-28T12:17:56Z. This reviews everything merged into main since then: #62–#75 (excluding #65/#67, which are release-please's own chore: release main PRs with no doc-relevant content beyond CHANGELOG.md, which release-please owns).

Most of those PRs (#62, #63, #64, #66, #68, #69, #70, #73, #74) already keep README.md/docs/ in sync as part of their own commits — verified by grepping the repo for every package-name reference #62 could have missed and checking each PR's own docs edits against the current code. This PR only covers what PR #75 missed, plus one API behavior change from #74 that had no doc coverage at all, plus a pre-existing nav gap that blocks mkdocs build --strict.

Corrections

• docs/architecture/pipeline.md and docs/architecture/failure_recovery.md: both said routing "raises PipelineError" when no compatible subgraph is found for a datasource. That was the exact bug fix(pipeline): raise a real exception when no subgraph matches #75 fixed — PipelineError is a pydantic BaseModel, not an exception, so that code actually raised TypeError: exceptions must derive from BaseException (see the regression test fix(pipeline): raise a real exception when no subgraph matches #75 added, test_scan_layer_router_raise_is_a_real_exception_not_a_type_error). fix(pipeline): raise a real exception when no subgraph matches #75 introduced PipelineExecutionError (an NL2SQLError carrying the PipelineError on .error) and updated docs/architecture/subgraphs/main_pipeline_graph.md in its own commit, but missed these two other files describing the same code path. Verified against packages/nl2sql/src/nl2sql/pipeline/routes.py and packages/nl2sql/src/nl2sql/common/exceptions.py on main.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/observability/error-handling.md: opened with the blanket claim "NL2SQL represents failures as structured PipelineError objects and propagates them through state," which is now incomplete — the router path added by fix(pipeline): raise a real exception when no subgraph matches #75 raises an exception instead. Added a paragraph naming PipelineExecutionError and how run_with_graph()'s crash handler folds it back into GraphState.errors as an UNKNOWN_ERROR. Verified against packages/nl2sql/src/nl2sql/pipeline/runtime.py.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/api/core/datasource.md: DatasourceAPI.get_datasource_details returns connection args, but the docs never mentioned that secret-shaped values are masked. fix(demo): make the docker demo datasources reachable #74 added mask_connection_args() (packages/nl2sql/src/nl2sql/datasources/registry.py), which replaces any connection-arg value whose key contains password, secret, token, or api_key with "***", and wired it into get_datasource_details (packages/nl2sql/src/nl2sql/api/datasource_api.py:126) as a security fix (a pydantic ValidationError used to be able to echo a plaintext password). Documented the masking so the public API surface doc matches actual behavior.

  • Necessitated by: fix(demo): make the docker demo datasources reachable #74

• mkdocs.yml: docs/getting_started/demo.md exists and is already linked from docs/getting_started/index.md ("Demo Data (CLI-first)"), but was never added to the nav: tree, which makes mkdocs build --strict fail with "pages exist... but are not included in the nav configuration." This predates the review window, but it blocks the strict build required by this task, so I registered it under Getting Started to match its existing sibling entries and its own link text in index.md.

Verification

• Every claim above was checked against the current code on main, not just the PR diffs.
• Grepped the whole repo for any remaining nl2sql[ / pip install nl2sql references that chore: rename the published distribution to nl2sql-engine #62's own docs commit might have missed — none found; all remaining hits are the import package name (nl2sql) or the packages/nl2sql source path, both correctly unchanged by the PyPI rename.
• pip install -r requirements-docs.txt && python -m mkdocs build --strict: fails locally with exactly one warning — mkdocs-mermaid2-plugin can't reach unpkg.com to verify the mermaid.js CDN URL. curl -sS "$HTTPS_PROXY/__agentproxy/status" confirms unpkg.com:443 is rejected by this sandbox's outbound network policy (connect_rejected, gateway 403), not by anything in the repo. This is the identical, sandbox-only failure PR docs: sync documentation with recent changes #60 documented and it was not a regression there either — the docs CI check (real internet access) already passed on main at feat(cli): add application container to docker demo; make mssql opt-in #59/fix(ci): build the API image from the repository root #70. With the nav fix above, that CDN check is the only warning the strict build produces; every content and nav validation passes.

Not touched

• CHANGELOG.md and version numbers (release-please owns those).
• packages/api/Dockerfile.dev — still flagged from docs: sync documentation with recent changes #60 as broken and out of scope for a docs fix (code issue, not a docs one).
• The doctor CLI command (fix(cli): repair the doctor connectivity check #72 fixed a bug in it, restoring behavior to what limited existing docs already implied) — it isn't documented anywhere in docs/ or README.md, but that gap predates this review window and fix(cli): repair the doctor connectivity check #72 didn't change what's documented, so it's out of scope here.

---

Generated by Claude Code

[nadeem4]

Review window

Prior "docs: sync documentation with recent changes" PR: #60, created 2026-08-28T12:17:56Z. This reviews everything merged into main since then: #62–#75 (excluding #65/#67, which are release-please's own chore: release main PRs with no doc-relevant content beyond CHANGELOG.md, which release-please owns).

Most of those PRs (#62, #63, #64, #66, #68, #69, #70, #73, #74) already keep README.md/docs/ in sync as part of their own commits — verified by grepping the repo for every package-name reference #62 could have missed and checking each PR's own docs edits against the current code. This PR only covers what PR #75 missed, plus one API behavior change from #74 that had no doc coverage at all, plus a pre-existing nav gap that blocks mkdocs build --strict.

Corrections

• docs/architecture/pipeline.md and docs/architecture/failure_recovery.md: both said routing "raises PipelineError" when no compatible subgraph is found for a datasource. That was the exact bug fix(pipeline): raise a real exception when no subgraph matches #75 fixed — PipelineError is a pydantic BaseModel, not an exception, so that code actually raised TypeError: exceptions must derive from BaseException (see the regression test fix(pipeline): raise a real exception when no subgraph matches #75 added, test_scan_layer_router_raise_is_a_real_exception_not_a_type_error). fix(pipeline): raise a real exception when no subgraph matches #75 introduced PipelineExecutionError (an NL2SQLError carrying the PipelineError on .error) and updated docs/architecture/subgraphs/main_pipeline_graph.md in its own commit, but missed these two other files describing the same code path. Verified against packages/nl2sql/src/nl2sql/pipeline/routes.py and packages/nl2sql/src/nl2sql/common/exceptions.py on main.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/observability/error-handling.md: opened with the blanket claim "NL2SQL represents failures as structured PipelineError objects and propagates them through state," which is now incomplete — the router path added by fix(pipeline): raise a real exception when no subgraph matches #75 raises an exception instead. Added a paragraph naming PipelineExecutionError and how run_with_graph()'s crash handler folds it back into GraphState.errors as an UNKNOWN_ERROR. Verified against packages/nl2sql/src/nl2sql/pipeline/runtime.py.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/api/core/datasource.md: DatasourceAPI.get_datasource_details returns connection args, but the docs never mentioned that secret-shaped values are masked. fix(demo): make the docker demo datasources reachable #74 added mask_connection_args() (packages/nl2sql/src/nl2sql/datasources/registry.py), which replaces any connection-arg value whose key contains password, secret, token, or api_key with "***", and wired it into get_datasource_details (packages/nl2sql/src/nl2sql/api/datasource_api.py:126) as a security fix (a pydantic ValidationError used to be able to echo a plaintext password). Documented the masking so the public API surface doc matches actual behavior.

  • Necessitated by: fix(demo): make the docker demo datasources reachable #74

• mkdocs.yml: docs/getting_started/demo.md exists and is already linked from docs/getting_started/index.md ("Demo Data (CLI-first)"), but was never added to the nav: tree, which makes mkdocs build --strict fail with "pages exist... but are not included in the nav configuration." This predates the review window, but it blocks the strict build required by this task, so I registered it under Getting Started to match its existing sibling entries and its own link text in index.md.

Verification

• Every claim above was checked against the current code on main, not just the PR diffs.
• Grepped the whole repo for any remaining nl2sql[ / pip install nl2sql references that chore: rename the published distribution to nl2sql-engine #62's own docs commit might have missed — none found; all remaining hits are the import package name (nl2sql) or the packages/nl2sql source path, both correctly unchanged by the PyPI rename.
• pip install -r requirements-docs.txt && python -m mkdocs build --strict: fails locally with exactly one warning — mkdocs-mermaid2-plugin can't reach unpkg.com to verify the mermaid.js CDN URL. curl -sS "$HTTPS_PROXY/__agentproxy/status" confirms unpkg.com:443 is rejected by this sandbox's outbound network policy (connect_rejected, gateway 403), not by anything in the repo. This is the identical, sandbox-only failure PR docs: sync documentation with recent changes #60 documented and it was not a regression there either — the docs CI check (real internet access) already passed on main at feat(cli): add application container to docker demo; make mssql opt-in #59/fix(ci): build the API image from the repository root #70. With the nav fix above, that CDN check is the only warning the strict build produces; every content and nav validation passes.

Not touched

• CHANGELOG.md and version numbers (release-please owns those).
• packages/api/Dockerfile.dev — still flagged from docs: sync documentation with recent changes #60 as broken and out of scope for a docs fix (code issue, not a docs one).
• The doctor CLI command (fix(cli): repair the doctor connectivity check #72 fixed a bug in it, restoring behavior to what limited existing docs already implied) — it isn't documented anywhere in docs/ or README.md, but that gap predates this review window and fix(cli): repair the doctor connectivity check #72 didn't change what's documented, so it's out of scope here.

---

Generated by Claude Code

[nadeem4]

Review window

Prior "docs: sync documentation with recent changes" PR: #60, created 2026-08-28T12:17:56Z. This reviews everything merged into main since then: #62–#75 (excluding #65/#67, which are release-please's own chore: release main PRs with no doc-relevant content beyond CHANGELOG.md, which release-please owns).

Most of those PRs (#62, #63, #64, #66, #68, #69, #70, #73, #74) already keep README.md/docs/ in sync as part of their own commits — verified by grepping the repo for every package-name reference #62 could have missed and checking each PR's own docs edits against the current code. This PR only covers what PR #75 missed, plus one API behavior change from #74 that had no doc coverage at all, plus a pre-existing nav gap that blocks mkdocs build --strict.

Corrections

• docs/architecture/pipeline.md and docs/architecture/failure_recovery.md: both said routing "raises PipelineError" when no compatible subgraph is found for a datasource. That was the exact bug fix(pipeline): raise a real exception when no subgraph matches #75 fixed — PipelineError is a pydantic BaseModel, not an exception, so that code actually raised TypeError: exceptions must derive from BaseException (see the regression test fix(pipeline): raise a real exception when no subgraph matches #75 added, test_scan_layer_router_raise_is_a_real_exception_not_a_type_error). fix(pipeline): raise a real exception when no subgraph matches #75 introduced PipelineExecutionError (an NL2SQLError carrying the PipelineError on .error) and updated docs/architecture/subgraphs/main_pipeline_graph.md in its own commit, but missed these two other files describing the same code path. Verified against packages/nl2sql/src/nl2sql/pipeline/routes.py and packages/nl2sql/src/nl2sql/common/exceptions.py on main.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/observability/error-handling.md: opened with the blanket claim "NL2SQL represents failures as structured PipelineError objects and propagates them through state," which is now incomplete — the router path added by fix(pipeline): raise a real exception when no subgraph matches #75 raises an exception instead. Added a paragraph naming PipelineExecutionError and how run_with_graph()'s crash handler folds it back into GraphState.errors as an UNKNOWN_ERROR. Verified against packages/nl2sql/src/nl2sql/pipeline/runtime.py.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/api/core/datasource.md: DatasourceAPI.get_datasource_details returns connection args, but the docs never mentioned that secret-shaped values are masked. fix(demo): make the docker demo datasources reachable #74 added mask_connection_args() (packages/nl2sql/src/nl2sql/datasources/registry.py), which replaces any connection-arg value whose key contains password, secret, token, or api_key with "***", and wired it into get_datasource_details (packages/nl2sql/src/nl2sql/api/datasource_api.py:126) as a security fix (a pydantic ValidationError used to be able to echo a plaintext password). Documented the masking so the public API surface doc matches actual behavior.

  • Necessitated by: fix(demo): make the docker demo datasources reachable #74

• mkdocs.yml: docs/getting_started/demo.md exists and is already linked from docs/getting_started/index.md ("Demo Data (CLI-first)"), but was never added to the nav: tree, which makes mkdocs build --strict fail with "pages exist... but are not included in the nav configuration." This predates the review window, but it blocks the strict build required by this task, so I registered it under Getting Started to match its existing sibling entries and its own link text in index.md.

Verification

• Every claim above was checked against the current code on main, not just the PR diffs.
• Grepped the whole repo for any remaining nl2sql[ / pip install nl2sql references that chore: rename the published distribution to nl2sql-engine #62's own docs commit might have missed — none found; all remaining hits are the import package name (nl2sql) or the packages/nl2sql source path, both correctly unchanged by the PyPI rename.
• pip install -r requirements-docs.txt && python -m mkdocs build --strict: fails locally with exactly one warning — mkdocs-mermaid2-plugin can't reach unpkg.com to verify the mermaid.js CDN URL. curl -sS "$HTTPS_PROXY/__agentproxy/status" confirms unpkg.com:443 is rejected by this sandbox's outbound network policy (connect_rejected, gateway 403), not by anything in the repo. This is the identical, sandbox-only failure PR docs: sync documentation with recent changes #60 documented and it was not a regression there either — the docs CI check (real internet access) already passed on main at feat(cli): add application container to docker demo; make mssql opt-in #59/fix(ci): build the API image from the repository root #70. With the nav fix above, that CDN check is the only warning the strict build produces; every content and nav validation passes.

Not touched

• CHANGELOG.md and version numbers (release-please owns those).
• packages/api/Dockerfile.dev — still flagged from docs: sync documentation with recent changes #60 as broken and out of scope for a docs fix (code issue, not a docs one).
• The doctor CLI command (fix(cli): repair the doctor connectivity check #72 fixed a bug in it, restoring behavior to what limited existing docs already implied) — it isn't documented anywhere in docs/ or README.md, but that gap predates this review window and fix(cli): repair the doctor connectivity check #72 didn't change what's documented, so it's out of scope here.

---

Generated by Claude Code

[nadeem4]

Review window

Prior "docs: sync documentation with recent changes" PR: #60, created 2026-08-28T12:17:56Z. This reviews everything merged into main since then: #62–#75 (excluding #65/#67, which are release-please's own chore: release main PRs with no doc-relevant content beyond CHANGELOG.md, which release-please owns).

Most of those PRs (#62, #63, #64, #66, #68, #69, #70, #73, #74) already keep README.md/docs/ in sync as part of their own commits — verified by grepping the repo for every package-name reference #62 could have missed and checking each PR's own docs edits against the current code. This PR only covers what PR #75 missed, plus one API behavior change from #74 that had no doc coverage at all, plus a pre-existing nav gap that blocks mkdocs build --strict.

Corrections

• docs/architecture/pipeline.md and docs/architecture/failure_recovery.md: both said routing "raises PipelineError" when no compatible subgraph is found for a datasource. That was the exact bug fix(pipeline): raise a real exception when no subgraph matches #75 fixed — PipelineError is a pydantic BaseModel, not an exception, so that code actually raised TypeError: exceptions must derive from BaseException (see the regression test fix(pipeline): raise a real exception when no subgraph matches #75 added, test_scan_layer_router_raise_is_a_real_exception_not_a_type_error). fix(pipeline): raise a real exception when no subgraph matches #75 introduced PipelineExecutionError (an NL2SQLError carrying the PipelineError on .error) and updated docs/architecture/subgraphs/main_pipeline_graph.md in its own commit, but missed these two other files describing the same code path. Verified against packages/nl2sql/src/nl2sql/pipeline/routes.py and packages/nl2sql/src/nl2sql/common/exceptions.py on main.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/observability/error-handling.md: opened with the blanket claim "NL2SQL represents failures as structured PipelineError objects and propagates them through state," which is now incomplete — the router path added by fix(pipeline): raise a real exception when no subgraph matches #75 raises an exception instead. Added a paragraph naming PipelineExecutionError and how run_with_graph()'s crash handler folds it back into GraphState.errors as an UNKNOWN_ERROR. Verified against packages/nl2sql/src/nl2sql/pipeline/runtime.py.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/api/core/datasource.md: DatasourceAPI.get_datasource_details returns connection args, but the docs never mentioned that secret-shaped values are masked. fix(demo): make the docker demo datasources reachable #74 added mask_connection_args() (packages/nl2sql/src/nl2sql/datasources/registry.py), which replaces any connection-arg value whose key contains password, secret, token, or api_key with "***", and wired it into get_datasource_details (packages/nl2sql/src/nl2sql/api/datasource_api.py:126) as a security fix (a pydantic ValidationError used to be able to echo a plaintext password). Documented the masking so the public API surface doc matches actual behavior.

  • Necessitated by: fix(demo): make the docker demo datasources reachable #74

• mkdocs.yml: docs/getting_started/demo.md exists and is already linked from docs/getting_started/index.md ("Demo Data (CLI-first)"), but was never added to the nav: tree, which makes mkdocs build --strict fail with "pages exist... but are not included in the nav configuration." This predates the review window, but it blocks the strict build required by this task, so I registered it under Getting Started to match its existing sibling entries and its own link text in index.md.

Verification

• Every claim above was checked against the current code on main, not just the PR diffs.
• Grepped the whole repo for any remaining nl2sql[ / pip install nl2sql references that chore: rename the published distribution to nl2sql-engine #62's own docs commit might have missed — none found; all remaining hits are the import package name (nl2sql) or the packages/nl2sql source path, both correctly unchanged by the PyPI rename.
• pip install -r requirements-docs.txt && python -m mkdocs build --strict: fails locally with exactly one warning — mkdocs-mermaid2-plugin can't reach unpkg.com to verify the mermaid.js CDN URL. curl -sS "$HTTPS_PROXY/__agentproxy/status" confirms unpkg.com:443 is rejected by this sandbox's outbound network policy (connect_rejected, gateway 403), not by anything in the repo. This is the identical, sandbox-only failure PR docs: sync documentation with recent changes #60 documented and it was not a regression there either — the docs CI check (real internet access) already passed on main at feat(cli): add application container to docker demo; make mssql opt-in #59/fix(ci): build the API image from the repository root #70. With the nav fix above, that CDN check is the only warning the strict build produces; every content and nav validation passes.

Not touched

• CHANGELOG.md and version numbers (release-please owns those).
• packages/api/Dockerfile.dev — still flagged from docs: sync documentation with recent changes #60 as broken and out of scope for a docs fix (code issue, not a docs one).
• The doctor CLI command (fix(cli): repair the doctor connectivity check #72 fixed a bug in it, restoring behavior to what limited existing docs already implied) — it isn't documented anywhere in docs/ or README.md, but that gap predates this review window and fix(cli): repair the doctor connectivity check #72 didn't change what's documented, so it's out of scope here.

---

Generated by Claude Code

[nadeem4]

Review window

Prior "docs: sync documentation with recent changes" PR: #60, created 2026-08-28T12:17:56Z. This reviews everything merged into main since then: #62–#75 (excluding #65/#67, which are release-please's own chore: release main PRs with no doc-relevant content beyond CHANGELOG.md, which release-please owns).

Most of those PRs (#62, #63, #64, #66, #68, #69, #70, #73, #74) already keep README.md/docs/ in sync as part of their own commits — verified by grepping the repo for every package-name reference #62 could have missed and checking each PR's own docs edits against the current code. This PR only covers what PR #75 missed, plus one API behavior change from #74 that had no doc coverage at all, plus a pre-existing nav gap that blocks mkdocs build --strict.

Corrections

• docs/architecture/pipeline.md and docs/architecture/failure_recovery.md: both said routing "raises PipelineError" when no compatible subgraph is found for a datasource. That was the exact bug fix(pipeline): raise a real exception when no subgraph matches #75 fixed — PipelineError is a pydantic BaseModel, not an exception, so that code actually raised TypeError: exceptions must derive from BaseException (see the regression test fix(pipeline): raise a real exception when no subgraph matches #75 added, test_scan_layer_router_raise_is_a_real_exception_not_a_type_error). fix(pipeline): raise a real exception when no subgraph matches #75 introduced PipelineExecutionError (an NL2SQLError carrying the PipelineError on .error) and updated docs/architecture/subgraphs/main_pipeline_graph.md in its own commit, but missed these two other files describing the same code path. Verified against packages/nl2sql/src/nl2sql/pipeline/routes.py and packages/nl2sql/src/nl2sql/common/exceptions.py on main.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/observability/error-handling.md: opened with the blanket claim "NL2SQL represents failures as structured PipelineError objects and propagates them through state," which is now incomplete — the router path added by fix(pipeline): raise a real exception when no subgraph matches #75 raises an exception instead. Added a paragraph naming PipelineExecutionError and how run_with_graph()'s crash handler folds it back into GraphState.errors as an UNKNOWN_ERROR. Verified against packages/nl2sql/src/nl2sql/pipeline/runtime.py.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/api/core/datasource.md: DatasourceAPI.get_datasource_details returns connection args, but the docs never mentioned that secret-shaped values are masked. fix(demo): make the docker demo datasources reachable #74 added mask_connection_args() (packages/nl2sql/src/nl2sql/datasources/registry.py), which replaces any connection-arg value whose key contains password, secret, token, or api_key with "***", and wired it into get_datasource_details (packages/nl2sql/src/nl2sql/api/datasource_api.py:126) as a security fix (a pydantic ValidationError used to be able to echo a plaintext password). Documented the masking so the public API surface doc matches actual behavior.

  • Necessitated by: fix(demo): make the docker demo datasources reachable #74

• mkdocs.yml: docs/getting_started/demo.md exists and is already linked from docs/getting_started/index.md ("Demo Data (CLI-first)"), but was never added to the nav: tree, which makes mkdocs build --strict fail with "pages exist... but are not included in the nav configuration." This predates the review window, but it blocks the strict build required by this task, so I registered it under Getting Started to match its existing sibling entries and its own link text in index.md.

Verification

• Every claim above was checked against the current code on main, not just the PR diffs.
• Grepped the whole repo for any remaining nl2sql[ / pip install nl2sql references that chore: rename the published distribution to nl2sql-engine #62's own docs commit might have missed — none found; all remaining hits are the import package name (nl2sql) or the packages/nl2sql source path, both correctly unchanged by the PyPI rename.
• pip install -r requirements-docs.txt && python -m mkdocs build --strict: fails locally with exactly one warning — mkdocs-mermaid2-plugin can't reach unpkg.com to verify the mermaid.js CDN URL. curl -sS "$HTTPS_PROXY/__agentproxy/status" confirms unpkg.com:443 is rejected by this sandbox's outbound network policy (connect_rejected, gateway 403), not by anything in the repo. This is the identical, sandbox-only failure PR docs: sync documentation with recent changes #60 documented and it was not a regression there either — the docs CI check (real internet access) already passed on main at feat(cli): add application container to docker demo; make mssql opt-in #59/fix(ci): build the API image from the repository root #70. With the nav fix above, that CDN check is the only warning the strict build produces; every content and nav validation passes.

Not touched

• CHANGELOG.md and version numbers (release-please owns those).
• packages/api/Dockerfile.dev — still flagged from docs: sync documentation with recent changes #60 as broken and out of scope for a docs fix (code issue, not a docs one).
• The doctor CLI command (fix(cli): repair the doctor connectivity check #72 fixed a bug in it, restoring behavior to what limited existing docs already implied) — it isn't documented anywhere in docs/ or README.md, but that gap predates this review window and fix(cli): repair the doctor connectivity check #72 didn't change what's documented, so it's out of scope here.

---

Generated by Claude Code

[nadeem4]

Review window

Prior "docs: sync documentation with recent changes" PR: #60, created 2026-08-28T12:17:56Z. This reviews everything merged into main since then: #62–#75 (excluding #65/#67, which are release-please's own chore: release main PRs with no doc-relevant content beyond CHANGELOG.md, which release-please owns).

Most of those PRs (#62, #63, #64, #66, #68, #69, #70, #73, #74) already keep README.md/docs/ in sync as part of their own commits — verified by grepping the repo for every package-name reference #62 could have missed and checking each PR's own docs edits against the current code. This PR only covers what PR #75 missed, plus one API behavior change from #74 that had no doc coverage at all, plus a pre-existing nav gap that blocks mkdocs build --strict.

Corrections

• docs/architecture/pipeline.md and docs/architecture/failure_recovery.md: both said routing "raises PipelineError" when no compatible subgraph is found for a datasource. That was the exact bug fix(pipeline): raise a real exception when no subgraph matches #75 fixed — PipelineError is a pydantic BaseModel, not an exception, so that code actually raised TypeError: exceptions must derive from BaseException (see the regression test fix(pipeline): raise a real exception when no subgraph matches #75 added, test_scan_layer_router_raise_is_a_real_exception_not_a_type_error). fix(pipeline): raise a real exception when no subgraph matches #75 introduced PipelineExecutionError (an NL2SQLError carrying the PipelineError on .error) and updated docs/architecture/subgraphs/main_pipeline_graph.md in its own commit, but missed these two other files describing the same code path. Verified against packages/nl2sql/src/nl2sql/pipeline/routes.py and packages/nl2sql/src/nl2sql/common/exceptions.py on main.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/observability/error-handling.md: opened with the blanket claim "NL2SQL represents failures as structured PipelineError objects and propagates them through state," which is now incomplete — the router path added by fix(pipeline): raise a real exception when no subgraph matches #75 raises an exception instead. Added a paragraph naming PipelineExecutionError and how run_with_graph()'s crash handler folds it back into GraphState.errors as an UNKNOWN_ERROR. Verified against packages/nl2sql/src/nl2sql/pipeline/runtime.py.

  • Necessitated by: fix(pipeline): raise a real exception when no subgraph matches #75

• docs/api/core/datasource.md: DatasourceAPI.get_datasource_details returns connection args, but the docs never mentioned that secret-shaped values are masked. fix(demo): make the docker demo datasources reachable #74 added mask_connection_args() (packages/nl2sql/src/nl2sql/datasources/registry.py), which replaces any connection-arg value whose key contains password, secret, token, or api_key with "***", and wired it into get_datasource_details (packages/nl2sql/src/nl2sql/api/datasource_api.py:126) as a security fix (a pydantic ValidationError used to be able to echo a plaintext password). Documented the masking so the public API surface doc matches actual behavior.

  • Necessitated by: fix(demo): make the docker demo datasources reachable #74

• mkdocs.yml: docs/getting_started/demo.md exists and is already linked from docs/getting_started/index.md ("Demo Data (CLI-first)"), but was never added to the nav: tree, which makes mkdocs build --strict fail with "pages exist... but are not included in the nav configuration." This predates the review window, but it blocks the strict build required by this task, so I registered it under Getting Started to match its existing sibling entries and its own link text in index.md.

Verification

• Every claim above was checked against the current code on main, not just the PR diffs.
• Grepped the whole repo for any remaining nl2sql[ / pip install nl2sql references that chore: rename the published distribution to nl2sql-engine #62's own docs commit might have missed — none found; all remaining hits are the import package name (nl2sql) or the packages/nl2sql source path, both correctly unchanged by the PyPI rename.
• pip install -r requirements-docs.txt && python -m mkdocs build --strict: fails locally with exactly one warning — mkdocs-mermaid2-plugin can't reach unpkg.com to verify the mermaid.js CDN URL. curl -sS "$HTTPS_PROXY/__agentproxy/status" confirms unpkg.com:443 is rejected by this sandbox's outbound network policy (connect_rejected, gateway 403), not by anything in the repo. This is the identical, sandbox-only failure PR docs: sync documentation with recent changes #60 documented and it was not a regression there either — the docs CI check (real internet access) already passed on main at feat(cli): add application container to docker demo; make mssql opt-in #59/fix(ci): build the API image from the repository root #70. With the nav fix above, that CDN check is the only warning the strict build produces; every content and nav validation passes.

Not touched

• CHANGELOG.md and version numbers (release-please owns those).
• packages/api/Dockerfile.dev — still flagged from docs: sync documentation with recent changes #60 as broken and out of scope for a docs fix (code issue, not a docs one).
• The doctor CLI command (fix(cli): repair the doctor connectivity check #72 fixed a bug in it, restoring behavior to what limited existing docs already implied) — it isn't documented anywhere in docs/ or README.md, but that gap predates this review window and fix(cli): repair the doctor connectivity check #72 didn't change what's documented, so it's out of scope here.

---

Generated by Claude Code