docs: Wave 2 fixes (KI-004 to KI-211, KI-247 to KI-259)

platform/data-api/endpoints/access.md

@@ -35,12 +35,9 @@ The status under **Invoke** is one of:
 | **Not granted** | The account cannot call this endpoint. |
 | **No grant on this endpoint** | Egret could not check whether the account inherits invoke, usually because the endpoint is not live yet. |
 
-Two notes appear on a row when they matter:
+A granted row can carry the note **Revoking will not remove access** (*This account also reaches invoke through the workspace, so revoking here removes the grant but not the access.*, with a link to **Workspace membership**). It appears only when the account's workspace role gives it invoke on every endpoint in the workspace. Egret asks this at workspace scope, where the grant on this endpoint does not count, so a granted account with no such role carries no note and loses access when you revoke it. The answer comes with the grant list, so it is given on a draft or disabled endpoint too.
 
-- **Revoking will not remove access**, meant for a granted account that also reaches invoke through the workspace: revoking removes the grant but not the access. On the demo stack this note is shown on **every** granted service account, including ones with no workspace role, and is wrong for them: revoking `finance-dashboard` on **Orders by status** made its next call answer `403 not_granted`. Trust the result of **Try it** after a revoke, not the note.
-- **Revoking may not remove access**, shown when Egret cannot check the inherited access, for example while the endpoint is not live.
-
-The check for inherited access runs the account's own OpenAPI document and looks for this endpoint in it, so it only works on a live endpoint. A draft or disabled endpoint says so above the table: *This endpoint is not live, so nothing is being served yet and egret cannot check workspace-inherited invoke rights against it. Grants recorded here are real and take effect when it is published.*
+For an account with no grant here, Egret checks whether it inherits invoke by running the account's own OpenAPI document and looking for this endpoint in it. That only works on a live endpoint, so a draft or disabled endpoint says so above the table: *This endpoint is not live, so nothing is being served yet and egret cannot check workspace-inherited invoke rights against it. Grants recorded here are real and take effect when it is published.* While the check runs the row reads *Checking workspace-inherited invoke…*; if it fails, *egret could not check whether this account inherits invoke from the workspace.*
 
 ### The Try it action
 

platform/data-api/endpoints/config.md

@@ -20,9 +20,11 @@ The tab is a table with **Setting**, **Details** and **Value** columns, grouped
 | **Path** | Appended to the workspace's Data API base URL to form the URL callers call. Same rules as at creation: see [Endpoints](../endpoints#path-rules). | The path you gave it |
 
 :::caution
-Method and path are part of the contract. Publishing a change to either is reported as a breaking change, and saving a new path moves the live URL at once; see [Publishing](./publishing#breaking-changes).
+Method and path are part of the contract. Publishing a change to either is reported as a breaking change; see [Publishing](./publishing#breaking-changes).
 :::
 
+A new method or path on a live endpoint is saved on the draft only. Callers keep using the live URL until you publish; the field then says *The new path goes live when you publish. Callers still use GET /orders/by-status.* (or *The new method goes live…* for a method change), and the Endpoints list shows *Pending publish: GET /orders/lookup* under the live URL. When you publish, the new URL starts serving and the old one answers `404 not_found`; there is no redirect.
+
 ## Cache
 
 An endpoint can serve repeat calls from a stored answer instead of running the query again. A cached answer sets `meta.cached` to `true` in the response.

platform/data-api/endpoints/index.md

@@ -15,7 +15,7 @@ Open **Explore → Data API → Endpoints**. The list shows every endpoint in th
 | Column | What it shows |
 |---|---|
 | **Name** | The endpoint's name, with a star to bookmark it. |
-| **Method & path** | The HTTP method and the path callers append to the workspace's base URL, for example `GET /orders/by-status`. |
+| **Method & path** | The HTTP method and the path callers append to the workspace's base URL, for example `GET /orders/by-status`. For a published endpoint this is the URL it is served on. When the draft has a new method or path, the line under it reads *Pending publish:* and the new one until you publish. |
 | **State** | **Live**, **Draft**, or **Disabled · was live** (see [lifecycle](./overview#endpoint-lifecycle)). |
 | **Engine** | The engine of the endpoint's database connection, for example Trino. |
 | **Last edited** | When the draft last changed. |
@@ -106,8 +106,8 @@ Opening an endpoint shows its editor. The header carries the name, a state badge
 
 The header badge reads **Draft · never published**, **Live · v2**, **Live · v1 · unpublished changes** (the saved draft differs from what is served, as on **Top customers** in the walk-through) or **Disabled · was live**. Pressing the badge opens **Versions**.
 
-:::caution Changing the path moves the live URL
-Saving a new **Path** in **Config** changes the URL that is served immediately, before you publish. A call to the old path returns `404 not_found` while the new path answers with the live version's data. Publishing then reports the change as breaking. Treat a path change as a breaking change to make deliberately. See [Publishing](./endpoints/publishing#breaking-changes).
+:::note A new path goes live at publish
+Saving a new **Path** or **Method** in **Config** changes only the draft. Callers keep the live URL until you publish; then the new URL serves and the old one answers `404 not_found`, with no redirect. Publishing reports the change as breaking. See [Cache, limits and rate limits](./endpoints/config) and [Publishing](./endpoints/publishing#breaking-changes).
 :::
 
 ## Limits and known issues

platform/data-api/endpoints/parameters.md

@@ -31,8 +31,8 @@ Every parameter is read from the query string, for `GET` and `POST` endpoints al
 
 | Type | Accepted values | Notes |
 |---|---|---|
-| `string` | Any text. | Use **min length**, **max length** and **pattern** to constrain it. |
-| `number` | `-?digits` with an optional decimal part, such as `12`, `-3` or `12.5`. | Exponent notation (`1e3`), a leading `+`, and non-numbers are refused. A value outside **minimum** and **maximum** is refused. |
+| `string` | Any text. | Use **Min length**, **Max length** and **Pattern (regex)** to constrain it. |
+| `number` | `-?digits` with an optional decimal part, such as `12`, `-3` or `12.5`. | Exponent notation (`1e3`), a leading `+`, and non-numbers are refused. A value outside **Minimum** and **Maximum** is refused. |
 | `boolean` | `true`, `false`, `TRUE`, `1`, `0`. | Anything else, such as `yes`, is `400 param_invalid`. |
 | `date` | `YYYY-MM-DD`. `1998-6-1` is also read. | A timestamp or `06/01/1998` is refused. |
 | `timestamp` | `YYYY-MM-DDTHH:MM:SS` or `YYYY-MM-DD HH:MM:SS`, with optional fractional seconds. No time zone. | A trailing `Z` or an offset is refused. Use **not before** and **not after** to bound it, written in the same form. |
@@ -42,14 +42,14 @@ An empty value (`?priority=`) is not treated as absent. It is checked like any o
 
 ### Constraints
 
-Constraints are checked on every call, before the query runs and before the cache is consulted. They also appear in the OpenAPI document, so a client generator can enforce them.
+In the editor the constraint boxes sit under the parameter's type, each with its own label. Constraints are checked on every call, before the query runs and before the cache is consulted. They also appear in the OpenAPI document, so a client generator can enforce them.
 
 | Type | Constraint fields | Meaning |
 |---|---|---|
-| `string` | **min length**, **max length** | Length in Unicode characters, not bytes. |
-| `string` | **pattern (regex)** | The value must match. |
-| `number` | **minimum**, **maximum** | Inclusive bounds. Stored as text so decimals are compared exactly. |
-| `date`, `timestamp` | **not before**, **not after** | Inclusive bounds. |
+| `string` | **Min length**, **Max length** | Length in Unicode characters, not bytes. |
+| `string` | **Pattern (regex)** | The value must match. |
+| `number` | **Minimum**, **Maximum** | Inclusive bounds. Stored as text so decimals are compared exactly. |
+| `date`, `timestamp` | **Not before**, **Not after** | Inclusive bounds. |
 | `enum` | **allowed values** | The closed list. |
 
 Changing a parameter's type clears the constraints that no longer apply. A constraint on a type that cannot carry it is refused at publish.
@@ -143,7 +143,6 @@ The **Preview** panel under the editor has one input per declared parameter. Fil
 
 - Parameter errors never name the parameter.
 - A parameter name may be referenced from several statements; a key sent once is a list wherever any statement loops over it.
-- Number constraint boxes in the editor show their value without a label; they are **minimum** then **maximum** in that order.
 
 ## Further reading
 

platform/data-api/endpoints/publishing.md

@@ -59,9 +59,11 @@ Under the hood the acknowledgement is a token that `POST …/validate` issues fo
 
 The version row keeps the record. **1 breaking change** on `v2` of the walk-through endpoint *Orders by status* shows that someone acknowledged the removal of the `orders` column.
 
-:::caution Changing the path moves the live URL
-Saving a new **Path** changes the URL served at once, before any publish. See [Endpoints](../endpoints#the-editor). Treat it as breaking even though it only becomes visible as such when you publish.
-:::
+### A new method or path
+
+A new method or path takes effect when you publish, not when you save it. Until then the endpoint is served on its live URL, which the generated OpenAPI document and **Try it** use too. On publish the new URL starts serving and the old one answers `404 not_found`. There is no redirect, so tell your callers before you publish.
+
+Only one endpoint can be served at a URL. An endpoint keeps its published URL until it is published again, even when its draft has moved on. Publishing a second endpoint at that URL is refused with `409 conflict`: *another endpoint in this workspace is served at GET /x; an endpoint keeps its published URL until it is published again, so choose another path or publish the move of the endpoint that holds it first*. A disabled or trashed endpoint keeps its claim on its URL.
 
 ## Roll back
 
@@ -77,6 +79,8 @@ A message confirms *Rolled back to vN*. Nothing is deleted. The draft is untouch
 
 Rollback re-checks the rules whose inputs are live now, such as whether the connection is governed, and refuses if the old version could not be served safely today.
 
+The rolled-back version is served at the URL it was published at. If its method or path differs from the current one, callers must switch URLs. A rollback is refused with `409 conflict` when another endpoint is now served at that URL.
+
 ## Pin a consumer to a version
 
 A consumer that wants to keep calling a specific version while you publish others can send the `X-Egret-Version` header with the version number:
@@ -104,8 +108,7 @@ An endpoint in the trash cannot be edited, published, rolled back, enabled or di
 ## Limits and known issues
 
 - The **Roll back** button needs the endpoint to be out of the trash.
-- Saving a changed **Path** moves live traffic before publish.
-- The breaking-change badge can overlap the version's note text in a narrow **Version** column.
+- A draft can be saved at a URL that another endpoint still serves; only its publish is refused.
 
 ## Further reading
 

platform/data-api/endpoints/try-it.md

@@ -86,7 +86,7 @@ A trial runs as the service account, not as you. It uses the endpoint-wide rate-
 
 ## Limits and known issues
 
-- **Try it** runs the published version. Draft edits, saved or not, are not part of it.
+- **Try it** runs the published version at its live URL. Draft edits, saved or not, are not part of it, including a new method or path.
 - A result too large to display shows *This result is too large to display here. The call still ran for real*; check Activity.
 - **Try it** needs at least one service account. With none, it says *This workspace has no service accounts yet* and links to **Create one in Clients**.
 

platform/data-api/openapi.md

@@ -101,7 +101,7 @@ The error statuses documented on every operation are `400`, `401`, `403`, `404`,
 
 ## Limits and known issues
 
-- The document is generated from the **published** version. Draft changes do not appear.
+- The document is generated from the **published** version. Draft changes do not appear, including a new method or path: each endpoint is listed at the URL it is served on until you publish the move.
 - It is generated on demand, so a very large workspace can hit the generation limit; Egret answers `500 internal` rather than an incomplete document.
 - Two columns that collapse onto one key under **Naming** make an endpoint refuse to document (`503 output_naming_collision`); republish after fixing it.
 

platform/data-api/overview.md

@@ -50,7 +50,7 @@ A client gives a service account the ability to *get a token*. Two separate thin
 
 ## Endpoint lifecycle
 
-An endpoint is never edited in place for its consumers. You edit the **draft**; consumers only ever see a **version**, which is a frozen copy of the draft taken when you press **Publish**.
+An endpoint is never edited in place for its consumers. You edit the **draft**; consumers only ever see a **version**, which is a frozen copy of the draft taken when you press **Publish**. That includes the URL: a new method or path on the draft is served only from the next publish.
 
 | State | Meaning | Serves calls |
 |---|---|---|

platform/deploy-operate/troubleshooting/engine-406-502.md

@@ -12,7 +12,7 @@ or with *502 Bad Gateway*. This is the most common first-run failure with a Trin
 | Where | Message |
 |---|---|
 | **Test** on a connection, or `POST /api/ws/{workspace}/databases/test` | The request answers `200`, but the body says `{"ok":false,"detail":"engine: http 406 Not Acceptable"}` |
-| Creating a dataset, `POST /api/ws/{workspace}/datasets` | HTTP **502** with `{"error":"engine: engine: http 406 Not Acceptable"}` |
+| Creating a dataset, `POST /api/ws/{workspace}/datasets` | HTTP **502** with `{"error":"engine: http 406 Not Acceptable"}` |
 | A query in SQL Lab | The query status ends as `failed` with an `engine:` error |
 | Saving a connection through the API | It saves, with status `unknown`: the connection is stored without being proven, and the failure appears at the first use or on **Test**. |
 

platform/deploy-operate/troubleshooting/queries-fail.md

@@ -51,7 +51,9 @@ See [Engine 406 and 502 errors](./engine-406-502).
 
 ## The query times out
 
-The per-query timeout is `engine.query_timeout_secs` (default 60 seconds). Data Apps have their own limit
+The per-query timeout is `engine.query_timeout_secs` (default 60 seconds). In SQL Lab a query that runs longer fails with
+*timeout: the query ran longer than the 60 s limit for SQL Lab queries and was stopped. The limit is the server setting
+`engine.query_timeout_secs`.* (or with Trino's *exceeded maximum time limit* and the same hint). Data Apps have their own limit
 (`apps.timeout_secs`, 60). Raise the key if long queries are legitimate, or make the query cheaper. The key must stay at
 least 1.
 
@@ -65,7 +67,8 @@ least 1.
 | Row limit on a chart | The chart's Data tab | 1,000 (up to 10,000) |
 | `apps.max_rows` | Data Apps gateway | 10,000 |
 
-A result that hit a cap is marked as truncated in the query's status (`"truncated": true`).
+A result that hit a cap is marked as truncated in the query's status (`"truncated": true`), and SQL Lab shows the chip
+*Results were limited to n rows.*
 
 ## *Missing query:run permission* (403)
 

platform/explore/charts/cartesian-settings.md

@@ -42,7 +42,7 @@ Bar, row, line, area and combo charts. Empty by default (**Keep every category**
 
 ### Sort and Row limit
 
-The same query controls every chart has. See [Sort](./the-chart-editor#sort) and [Row limit](./the-chart-editor#row-limit). The chart is always ordered by the X-axis, ascending, after any sort you add.
+The same query controls every chart has. See [Sort](./the-chart-editor#sort) and [Row limit](./the-chart-editor#row-limit). The chart is always ordered by the X-axis, ascending, after any sort you add. A row chart with no sort is the exception: it orders by its first metric, descending, then by the X-axis (see [Row chart](./row)).
 
 ## Display tab
 

platform/explore/charts/column-formatting.md

@@ -19,7 +19,7 @@ Which columns are listed depends on the chart: the ones it plots (for a bar char
 
 ### Column title
 
-Replaces the column's name in headers, legends and tooltips. The placeholder is the original name. Clearing the box goes back to the original.
+Replaces the column's name in headers, legends and tooltips. The placeholder is the original name. Clearing the box goes back to the original. When the dataset gives the column or metric a **Display name**, that name is used as the title in the chart editor and the dataset's Preview unless you set a title here; see [Columns](../datasets-and-metrics/columns#display-name). Dashboard cards do not apply the dataset's display names.
 
 ## Number columns
 

platform/explore/charts/funnel.md

@@ -53,7 +53,7 @@ One row for the dimension and one for the metric. See [Column formatting and num
 
 ![The same data as a Bar funnel, one column per stage](/img/platform/charts/funnel-bar.png)
 
-With **Bar — a column per step**, each stage is a column on a bar chart with its own legend entry, which is easier to read when stages are many or the values very different.
+With **Bar — a column per step**, each stage is a column on a bar chart with its own legend entry, which is easier to read when stages are many or the values very different. The stage names under the columns follow the same fit rule as a bar chart's X axis: all of them are drawn, upright or rotated, or none when they cannot all fit.
 
 ## Settings at a glance
 
@@ -72,6 +72,7 @@ There is no **Axes** tab.
 - The percentage under each stage is relative to the **first stage in the displayed order**, not to the previous stage.
 - Stage names cannot be renamed here; rename or alias them in the dataset or the query.
 - Clicking a stage opens the drill menu for that stage.
+- **.png** export is offered only with **Bar — a column per step**. The default funnel is not drawn as one image, so it offers **.csv**, **.xlsx** and **.json** only.
 
 ## Further reading
 

platform/explore/charts/gauge.md

@@ -19,8 +19,7 @@ A gauge shows one value on a dial, with the dial divided into colored ranges. Us
 | Field | What it does |
 |---|---|
 | **Dataset** | The dataset to read. |
-| **Metric** | The value the needle points to. Required. The query returns one row. |
-| **Row limit** | Present but ignored. |
+| **Metric** | The value the needle points to. Required. The query returns one row, so there is no **Row limit**. |
 
 ## Display
 
@@ -61,7 +60,6 @@ Open **Formatting → *metric*** and set **Number style** to **Percent**. The di
 | Setting | Where | Default |
 |---|---|---|
 | **Metric** | Data | Required |
-| **Row limit** | Data | Ignored |
 | **Ranges** (color, **Min**, **Max**, **Label**) | Display | Three equal ranges from 0 to twice the value (red, yellow, green) |
 | **Formatting** (one row for the metric) | Display | Dataset's format |
 | **Axes** tab | | Not applicable |