docs: sync documentation with recent changes

deploy/huggingface/README.md

@@ -133,7 +133,7 @@ Variables** can override any of them:
 | `PORT` | `7860` | the port the Space routes to (`app_port` above must match) |
 | `NL2SQL_DEMO_QUESTIONS_PER_MINUTE` | `6` | rate limit per visitor |
 | `NL2SQL_DEMO_QUESTIONS_PER_SESSION` | `30` | cap per browser session |
-| `GLOBAL_TIMEOUT_SEC` | `60` | how long one question may run |
+| `GLOBAL_TIMEOUT_SEC` | `300` (from `.env.demo`) | how long one question may run |
 | `TRACE_MODE` | `always` (from `.env.demo`) | what the playground's **Debug** drill-down reads. Every question writes a trace file to the container's own disk, which is wiped whenever the Space restarts; set it to `on_failure` to keep only the runs that went wrong |
 
 **Never add an API key as a Space secret.** The whole point of hosted mode is

docs/architecture/failure_recovery.md

@@ -108,7 +108,7 @@ Failure in this system is represented as structured `PipelineError` objects accu
 
 ### Retry scope
 - Only the SQL agent subgraph retries (planner and validation loop).
-- Other nodes (resolver, decomposer, global planner, generator, executor, aggregator, answer synthesizer) do not retry.
+- Other nodes (resolver, decomposer, generator, executor, aggregator, answer synthesizer) do not retry.
 
 ### Backoff
 - Exponential backoff with jitter in `retry_handler` using:
@@ -144,7 +144,7 @@ Failure in this system is represented as structured `PipelineError` objects accu
 
 ### What must restart
 - Any graph-level failure (timeout, cancellation, unknown exception) requires a new run.
-- Resolver failures, decomposer failures, global planner failures, generator failures, executor failures, and aggregator failures have no local recovery and require a new run.
+- Resolver failures, decomposer failures, generator failures, executor failures, and aggregator failures have no local recovery and require a new run.
 
 ### What is unrecoverable
 - `FATAL_ERRORS` or `CRITICAL` severity errors (security violations, missing datasource ID, missing LLM, invalid state) terminate the subgraph or graph without retry.

docs/architecture/graph_state.md

@@ -231,7 +231,7 @@ GraphState carries identifiers and artifact references that could support replay
 ---
 
 ## Determinism Impact
-Determinism guarantees and non-determinism sources are documented in `determinism.md`. GraphState only carries the artifacts produced by those nodes (IDs, DAG hashes, errors, and diagnostics).
+Determinism guarantees and non-determinism sources are documented in `determinism.md`. GraphState only carries the artifacts produced by those nodes (IDs, errors, and diagnostics).
 
 ---
 

docs/architecture/invariants.md

@@ -235,22 +235,6 @@ Ensures deterministic and well-ordered aggregation execution.
 
 ---
 
-## Relation Schemas Have Unique Column Names
-
-### Definition
-Each relation schema’s column names must be unique.
-
-### Enforcement Points
-- `RelationSchema.validate_unique_columns()` in `nl2sql.execution.dag`
-
-### Failure Behavior
-Raises `ValueError` during schema validation.
-
-### Why It Exists
-Prevents ambiguous column outputs in execution DAG nodes.
-
----
-
 ## Aggregation Requires Scan Artifacts and Single-Input Post Nodes
 
 ### Definition
@@ -389,7 +373,7 @@ The validator resolves columns against a throw-away query in which every table i
 
 ## Categories
 
-- **State**: Plan Model Is Strict and Read-Only; Relation Schemas Have Unique Column Names; Context Requires Vector Store and Schema Store Configuration
+- **State**: Plan Model Is Strict and Read-Only; Context Requires Vector Store and Schema Store Configuration
 - **Execution**: SQL Execution Requires SQL, Datasource, and Capability; Execution DAG Must Be Valid and Acyclic; Aggregation Requires Scan Artifacts and Single-Input Post Nodes; Pipeline Execution Is Time-Bounded
 - **Security**: Policy Enforcement Is Namespaced and Fail-Closed; Datasource Access Is RBAC-Gated; Plan Model Is Strict and Read-Only
 - **Determinism**: Expected Schema Must Match Select List; Joins Must Be Valid and Schema-Backed

docs/configuration/llm.md

@@ -336,15 +336,15 @@ cache-marked for Anthropic, the others are sent unmarked to OpenAI. The model
 each call actually used is recorded per node in `QueryResult.usage.calls` and
 in a run trace's `llm.by_node` (see [Debugging](../observability/debugging.md)).
 
-In the demo, the playground's **Settings** panel writes exactly these entries
+In the demo, the playground's **Settings** page writes exactly these entries
 into `configs/llm.demo.yaml`. Choosing a provider and a model for a step adds
 an `agents:` entry with `provider`, `model` and the temperature that model
 takes: `0.0`, or `null` for `gpt-5.5`, `gpt-5-mini`, `claude-opus-5` and
 `claude-sonnet-5`. A step on the default's provider takes the default's
 `base_url` and `api_key` reference; a step on another provider gets that
 provider's own `${env:...}` reference and no `base_url`. Choosing "Default"
 removes the entry. The running engine reloads the file, so the change applies
-to the next question. The panel offers the providers and models in
+to the next question. The page offers the providers and models in
 `VERIFIED_MODELS` (`nl2sql/llm/providers.py`), OpenAI and Anthropic for
 now, and a provider only once its key is saved. See
 [the Settings page](../getting_started/demo.md#the-settings-page).

docs/deployment/hosted-demo.md

@@ -133,7 +133,7 @@ no storage.
 | --- | --- | --- | --- |
 | Questions per minute | 6 | `NL2SQL_DEMO_QUESTIONS_PER_MINUTE` | client address (a token bucket) |
 | Questions per session | 30 | `NL2SQL_DEMO_QUESTIONS_PER_SESSION` | a random session cookie |
-| Query timeout | 60s | `GLOBAL_TIMEOUT_SEC` | the run |
+| Query timeout | 300s | `GLOBAL_TIMEOUT_SEC` | the run |
 | Rows returned | 1000 | the datasource's `row_limit` option | the query |
 
 Hitting one is a `429` with a sentence, never a stack trace: the rate limit says
@@ -286,9 +286,10 @@ command rather than saved into `.git/config`.
 **When it runs.** On every push to `main` that touches something the Space is
 built from -- `deploy/huggingface/**` (its root), `packages/nl2sql/**` (the
 engine the image installs) or `web/playground/**` (the page the engine serves)
--- and on demand. A docs-only merge changes none of those and does not
-redeploy. One deploy runs at a time; a run overtaken by a newer push is
-cancelled.
+-- or the workflow file itself, `.github/workflows/publish_space.yml`, so a
+change to the deploy logic redeploys too -- and on demand. A docs-only merge
+changes none of those and does not redeploy. One deploy runs at a time; a run
+overtaken by a newer push is cancelled.
 
 **What it reports.** The job never calls a build that did not happen a success.
 If the push produced a commit, the workflow checks the Space's head is that

docs/getting_started/demo.md

@@ -244,7 +244,7 @@ Debug choice: they belong to the visit, not to the page.
 **Pipeline** lists every step a question passes through, in the order a run
 takes them, and marks which of them a model decides. Five do: the answerability
 check, the question splitter, the query planner, the plan repair and the answer
-writer. The other nine are ordinary code -- the schema search, the execution
+writer. The other eight are ordinary code -- the schema search, the execution
 plan, the layer router, the plan checks, the SQL writer, the executor and the
 result combiner among them -- which is the point: the model plans, and
 deterministic code writes the SQL, checks it against the real schema and this

web/playground/README.md

@@ -257,8 +257,10 @@ rows, and the router over `hashchange`), `src/questions.js` (the guided
 questions grouped by datasource), `src/firstRun.js` (when the hosted demo has
 to ask for a key before it takes a question, and what the mode line then says),
 `src/datasources.js` (the
-databases the switcher offers, and which one a run was answered from) and
-`src/retrieval.js` (the MMR summary line, picks
+databases the switcher offers, and which one a run was answered from),
+`src/pipeline.js` (the run/model join for the Pipeline page), `src/hostedKey.js`
+(per-provider key parsing and masking), `src/hostedModels.js` (per-step model
+choice storage), `src/retrieval.js` (the MMR summary line, picks
 in order, entries passed over, the copyable text form) and `src/feedback.js`
 (when a run can be rated, the request body, the saved line) with Node's built-in test runner; there is no test dependency.
 
@@ -281,8 +283,8 @@ npm run dev
 
 Vite serves the page on its own port. Run `nl2sql demo --no-browser` alongside
 it and proxy or point `fetch` at `http://127.0.0.1:8765` to exercise the real
-API; the app calls `/api/meta`, `/api/schema`, `/api/ask`, `/api/trace/{id}`
-the settings routes (`GET /api/settings`, `POST /api/settings/key`,
+API; the app calls `/api/meta`, `/api/schema`, `/api/ask`, `/api/trace/{id}`,
+`/api/pipeline`, the settings routes (`GET /api/settings`, `POST /api/settings/key`,
 `POST /api/settings/models`) and the index routes (`GET /api/index`,
 `POST /api/index/rebuild`), the inspector's (`GET /api/retrieval`,
 `POST /api/retrieval`) and feedback's (`GET /api/feedback`, `POST /api/feedback`).
@@ -292,7 +294,7 @@ serves, not from the Vite dev server.
 
 ## Scope
 
-React and Vite only -- no router library (`src/router.js` is 110 lines over the
+React and Vite only -- no router library (`src/router.js` is 119 lines over the
 hash), no state library, no component kit, no CSS framework, no TypeScript. Plain JSX and plain CSS, kept small enough to read in
 one sitting. Light and dark follow `prefers-color-scheme`; motion is limited to
 the run arriving in order and is off under `prefers-reduced-motion`. The only