diff --git a/.changeset/sdui-parser-stageorder-funnel-only.md b/.changeset/sdui-parser-stageorder-funnel-only.md
new file mode 100644
index 00000000000..57810963f21
--- /dev/null
+++ b/.changeset/sdui-parser-stageorder-funnel-only.md
@@ -0,0 +1,13 @@
+---
+'@objectstack/sdui-parser': patch
+---
+
+`dashboard-widget-options.ts` header: `stageOrder` is a `funnel`-only key, not `funnel` / `pyramid`
+
+The accepted-set census comment at the top of the module (carried into the
+published `index.d.ts`) described `stageOrder` as "funnel/pyramid stage order".
+There is no `pyramid` widget type: `ChartTypeSchema` refuses it, so an author
+who copied the pair got a parse refusal. The line now says what the schema's
+own `.describe()` says: `funnel` is the only widget type that reads the key.
+Comment-only — the accepted set, the diagnostic code and the emitted JS are
+unchanged.
diff --git a/content/docs/ui/dashboards.mdx b/content/docs/ui/dashboards.mdx
index 4f64e99d1f2..60c7f2b1adb 100644
--- a/content/docs/ui/dashboards.mdx
+++ b/content/docs/ui/dashboards.mdx
@@ -118,7 +118,7 @@ dataset compiles to:
 | `sortBy` | `string` | Orders rows by a dimension or measure **this widget selects**. |
 | `sortOrder` | `asc \| desc` | Direction for `sortBy` (default `asc`). |
 | `limit` | `number` | Max rows, applied **after** ordering. |
-| `stageOrder` | `(string \| number \| boolean)[]` | Explicit stage order for `funnel` / `pyramid`, as the dimension's **stored values**. Omit to use the dimension field's picklist option order. |
+| `stageOrder` | `(string \| number \| boolean)[]` | Explicit stage order for a `funnel` widget, as the dimension's **stored values**. `funnel` is the only widget type that reads it — on any other type the key parses and is never consulted; order those with `sortBy` / `sortOrder`. Omit to use the dimension field's picklist option order. |
 
 Because they are declared, a misspelling (`sortDirection`, `granularity`) is an
 author-time error rather than an option that reads as if it works.
diff --git a/packages/sdui-parser/src/dashboard-widget-options.ts b/packages/sdui-parser/src/dashboard-widget-options.ts
index d0f95264ffb..4bff1398a9e 100644
--- a/packages/sdui-parser/src/dashboard-widget-options.ts
+++ b/packages/sdui-parser/src/dashboard-widget-options.ts
@@ -48,7 +48,7 @@
  * the five the spec DECLARES:
  *
  *   dateGranularity, sortBy, sortOrder, limit   (query-affecting, framework#3588)
- *   stageOrder                                  (funnel/pyramid stage order)
+ *   stageOrder                                  (funnel stage order — the only type that reads it)
  *
  * plus ONE undeclared key with a real read site:
  *
diff --git a/skills/objectstack-ui/rules/dashboards.md b/skills/objectstack-ui/rules/dashboards.md
index 80236e9a525..b376e001961 100644
--- a/skills/objectstack-ui/rules/dashboards.md
+++ b/skills/objectstack-ui/rules/dashboards.md
@@ -342,7 +342,7 @@ author-time type error rather than an option that silently does nothing.
 | `sortBy` | a name this widget selects | Order by that dimension or measure. It must be one of this widget's own `dimensions` / `values` entries. |
 | `sortOrder` | `'asc'` \| `'desc'` | Direction for `sortBy` (default ascending). |
 | `limit` | positive integer | Max rows, applied **after** ordering — so "top 10 accounts" is `limit` **plus** `sortBy`. Without `sortBy` the runtime orders by the selected dimensions: deterministic, but not the top of anything. |
-| `stageOrder` | array of **stored** values | Explicit category order for `funnel` / `pyramid`. Stored values, not display labels; omit it to inherit the field's own picklist order. |
+| `stageOrder` | array of **stored** values | Explicit stage order for `funnel`; no other type reads it. Stored values, not display labels; omit to inherit the field's picklist order. |
 
 ```typescript
 // Top 10 accounts by revenue, bucketed monthly for this widget only