docs(spec,ui): regenerate dashboard reference + document the widget query options (#3588)

`content/docs/references/ui/dashboard.mdx` is generated from the spec and went
stale when `DashboardWidgetOptionsSchema` was added — CI's generated-artifact
drift check caught it.

Also rewrites the hand-written `options` row in the dashboards guide, which
described the bag as "Additional display options". That description is what let
this bug happen: four of its keys change the compiled query, and an author had
no way to know which. The guide now lists the five declared keys with their
effects and the behavioural notes that are easy to get wrong (an unprojectable
`sortBy` is rejected, a bare `limit` orders by dimensions first, a derived
measure is a valid sort key, a funnel without a declared stage order falls back
to value-descending).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SEZLBGyNoJMLvtGPqsMPRC

Author: claude

content/docs/references/ui/dashboard.mdx

@@ -14,8 +14,8 @@ Color variant for dashboard widgets (e.g., KPI cards).
 ## TypeScript Usage
 
 ```typescript
-import { Dashboard, DashboardHeader, DashboardHeaderAction, DashboardWidget, GlobalFilter, GlobalFilterOptionsFrom, WidgetActionType, WidgetColorVariant } from '@objectstack/spec/ui';
-import type { Dashboard, DashboardHeader, DashboardHeaderAction, DashboardWidget, GlobalFilter, GlobalFilterOptionsFrom, WidgetActionType, WidgetColorVariant } from '@objectstack/spec/ui';
+import { Dashboard, DashboardHeader, DashboardHeaderAction, DashboardWidget, DashboardWidgetOptions, GlobalFilter, GlobalFilterOptionsFrom, WidgetActionType, WidgetColorVariant } from '@objectstack/spec/ui';
+import type { Dashboard, DashboardHeader, DashboardHeaderAction, DashboardWidget, DashboardWidgetOptions, GlobalFilter, GlobalFilterOptionsFrom, WidgetActionType, WidgetColorVariant } from '@objectstack/spec/ui';
 
 // Validate data
 const result = Dashboard.parse(data);
@@ -107,13 +107,30 @@ Dashboard header action
 | **dimensions** | `string[]` | optional | Dimension names — X/group/split |
 | **values** | `string[]` | ✅ | Measure names — Y (at least one) |
 | **layout** | `{ x: number; y: number; w: number; h: number }` | optional | Grid layout position (auto-flowed when omitted) |
-| **options** | `any` | optional | Widget specific configuration |
+| **options** | `Record<string, any>` | optional | Widget specific configuration |
 | **filterBindings** | `Record<string, string \| 'false'>` | optional | Per-widget dashboard-filter bindings: filter name → this widget's field, or false to opt out |
 | **suppressWarnings** | `string[]` | optional | Build diagnostic rule ids suppressed on this widget |
 | **responsive** | `{ breakpoint?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>; hiddenOn?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>[]; columns?: object; order?: object }` | optional | Responsive layout configuration |
 | **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes |
 
 
+---
+
+## DashboardWidgetOptions
+
+Widget configuration — declared query keys + open renderer extras
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **dateGranularity** | `Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>` | optional | Bucket selected date dimensions (day/week/month/quarter/year) |
+| **sortBy** | `string` | optional | Dimension/measure name to order by |
+| **sortOrder** | `Enum<'asc' \| 'desc'>` | optional | Sort direction for sortBy |
+| **limit** | `integer` | optional | Max rows (applied after ordering) |
+| **stageOrder** | `string \| number \| boolean[]` | optional | Explicit category order for funnel/pyramid stages (stored values) |
+
+
 ---
 
 ## GlobalFilter

content/docs/ui/dashboards.mdx

@@ -104,9 +104,50 @@ selects `dimensions` (X / group / split) and `values` (the measures to plot):
 | `chartConfig` | `object` | optional | Advanced chart configuration |
 | `colorVariant` | `enum` | optional | KPI/card accent color |
 | `compareTo` | `enum \| object` | optional | Period-over-period comparison window |
-| `options` | `object` | optional | Additional display options |
+| `options` | `object` | optional | Renderer extras **plus** the query keys below |
 | `responsive` | `object` | optional | Responsive behavior |
 
+### Widget `options`
+
+`options` is an open bag: keys the renderer understands (`icon`, `columns`,
+`striped`, `density`, …) pass through untouched. Five keys are **declared**,
+because they are not presentation-only — four of them change the query the
+dataset compiles to:
+
+| Key | Type | Effect |
+| :--- | :--- | :--- |
+| `dateGranularity` | `day \| week \| month \| quarter \| year` | Buckets this widget's selected **date** dimensions. Overrides the dataset dimension's own default for this widget only. |
+| `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. |
+
+Because they are declared, a misspelling (`sortDirection`, `granularity`) is an
+author-time error rather than an option that reads as if it works.
+
+```ts
+{
+  id: 'revenue_trend',
+  type: 'area',
+  dataset: 'opportunity_metrics',
+  dimensions: ['close_date'],
+  values: ['total_amount'],
+  // Group by month rather than by raw timestamp.
+  options: { dateGranularity: 'month' },
+}
+```
+
+Notes on behaviour:
+
+- `sortBy` must name something the widget selects; the server rejects an order
+  key it cannot resolve rather than ignoring it.
+- A `limit` with no `sortBy` orders by the selected dimensions first, so it
+  truncates a reproducible window instead of an arbitrary subset.
+- Ordering is applied to the finished grid, so a **derived measure** is a valid
+  `sortBy` even though no single SQL statement computes it.
+- A `funnel` with no declared stage order falls back to sorting by value
+  descending.
+
 ## Datasets
 
 Every widget binds to a **dataset** — the single semantic layer (ADR-0021).