@@ -0,0 +1,14 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the `DashboardWidgetOptionsSchema` doc comment states which widget `options` keys a renderer reads, instead of naming presentation extras (`icon`, `trend`, `columns`, `striped`, `density`) it called renderer-understood
+
+Clause-②: no — no key is declared and no value is typed, so the accept set is unchanged.
+
+`options` still parses any key. A widget always binds a `dataset`, so it renders through
+objectui's dataset-bound path, and that path reads only the five declared keys
+(`dateGranularity`, `sortBy`, `sortOrder`, `limit`, `stageOrder`) and the `description`
+sub-caption. Any other key parses and renders nothing. To format a number, set `format` and
+`currency` on the dataset measure. To accent a tile, set the widget's `colorVariant`. To style
+a chart, set the widget's `chartConfig`.
@@ -35,6 +35,11 @@ export const PipelineDashboard: Dashboard = {
   columns: 12,
   widgets: [
     // --- Row 1: KPI tiles -------------------------------------------------
+    // No `options` on these tiles: the currency face comes from the dataset
+    // measure (`total_amount` / `avg_amount` declare `format` + `currency` in
+    // `opportunity.dataset.ts`). A dataset-bound widget reads only the `options`
+    // keys the spec declares (plus the `description` sub-caption), so an
+    // `options.format` / `options.currency` here was inert.
     {
       id: 'total_pipeline',
       type: 'metric',
@@ -43,7 +48,6 @@ export const PipelineDashboard: Dashboard = {
       filter: { stage: { $nin: ['closed_won', 'closed_lost'] } },
       dataset: 'opportunity_metrics',
       values: ['total_amount'],
-      options: { format: 'currency', currency: 'USD' },
       layout: { x: 0, y: 0, w: 4, h: 2 },
     },
     {
@@ -61,7 +65,6 @@ export const PipelineDashboard: Dashboard = {
       compareTo: { kind: 'previousPeriod' },
       dataset: 'opportunity_metrics',
       values: ['total_amount'],
-      options: { format: 'currency', currency: 'USD' },
       layout: { x: 4, y: 0, w: 4, h: 2 },
     },
     {
@@ -79,7 +82,6 @@ export const PipelineDashboard: Dashboard = {
       compareTo: { kind: 'previousYear' },
       dataset: 'opportunity_metrics',
       values: ['avg_amount'],
-      options: { format: 'currency', currency: 'USD' },
       layout: { x: 8, y: 0, w: 4, h: 2 },
     },
 
 
@@ -17,6 +17,11 @@ export const TaskDashboard: Dashboard = {
   label: 'Task Overview',
   description: 'Key task metrics and productivity overview',
 
+  // No widget carries `options`: a dataset-bound widget reads only the keys the
+  // spec declares there (`dateGranularity`, `sortBy`, `sortOrder`, `limit`,
+  // `stageOrder`) plus the `description` sub-caption, so a presentation key in
+  // the bag renders nothing. A tile accent is `colorVariant`, a chart's look is
+  // `chartConfig`, and a number's face is the dataset measure's own `format`.
   widgets: [
     // Row 1: Key Metrics
     {
@@ -26,7 +31,6 @@ export const TaskDashboard: Dashboard = {
       dataset: 'task_metrics',
       values: ['task_count'],
       layout: { x: 0, y: 0, w: 3, h: 2 },
-      options: { color: '#3B82F6' }
     },
     {
       id: 'completed_today',
@@ -36,7 +40,6 @@ export const TaskDashboard: Dashboard = {
       dataset: 'task_metrics',
       values: ['task_count'],
       layout: { x: 3, y: 0, w: 3, h: 2 },
-      options: { color: '#10B981' }
     },
     {
       id: 'overdue_tasks',
@@ -46,7 +49,6 @@ export const TaskDashboard: Dashboard = {
       dataset: 'task_metrics',
       values: ['task_count'],
       layout: { x: 6, y: 0, w: 3, h: 2 },
-      options: { color: '#EF4444' }
     },
     {
       id: 'completion_rate',
@@ -56,7 +58,6 @@ export const TaskDashboard: Dashboard = {
       dataset: 'task_metrics',
       values: ['task_count'],
       layout: { x: 9, y: 0, w: 3, h: 2 },
-      options: { suffix: '%', color: '#8B5CF6' }
     },
 
     // Row 2: Task Distribution
@@ -75,7 +76,6 @@ export const TaskDashboard: Dashboard = {
       dimensions: ['status'],
       values: ['task_count'],
       layout: { x: 0, y: 2, w: 6, h: 4 },
-      options: { showLegend: true }
     },
     {
       id: 'tasks_by_priority',
@@ -86,7 +86,6 @@ export const TaskDashboard: Dashboard = {
       dimensions: ['priority'],
       values: ['task_count'],
       layout: { x: 6, y: 2, w: 6, h: 4 },
-      options: { horizontal: true }
     },
 
     // Row 3: Trends
@@ -99,7 +98,6 @@ export const TaskDashboard: Dashboard = {
       dimensions: ['completed_date'],
       values: ['task_count'],
       layout: { x: 0, y: 6, w: 8, h: 4 },
-      options: { showDataLabels: true }
     },
     {
       id: 'tasks_by_category',
@@ -110,7 +108,6 @@ export const TaskDashboard: Dashboard = {
       dimensions: ['category'],
       values: ['task_count'],
       layout: { x: 8, y: 6, w: 4, h: 4 },
-      options: { showLegend: true }
     },
 
     // The former Row 4 count-only `table` widgets (`overdue_tasks_table`,
 
@@ -214,15 +214,35 @@ const WIDGET_HISTORY =
   + 'shipping inert metadata; a stale or mis-layered key is now a loud parse error.';
 
 /**
- * Widget `options` — the renderer-extras escape hatch, with the keys that
- * reach the ANALYTICS QUERY declared explicitly (framework#3588).
- *
- * The bag stays open (`passthrough`): presentation-only settings the renderer
- * understands — `icon`, `trend`, `columns`, `striped`, `density`, … — are
- * carried through untouched and are none of the spec's business. What the
- * declared keys below buy is a real contract for the four that are NOT
- * presentation-only: they change the SQL the dataset query compiles to, so a
- * typo (`sortDirection`, `granularity`) is now an author-time type error
+ * Widget `options` — an open bag, with the keys that reach the ANALYTICS QUERY
+ * declared explicitly (framework#3588).
+ *
+ * The bag stays open (`passthrough`), but an undeclared key in it is NOT a
+ * renderer setting. `dataset` is required, so every widget renders through
+ * objectui's dataset-bound path (`DatasetWidget`), and that path reads exactly
+ * the five keys declared below plus `description`, the metric sub-caption.
+ * Any other key parses and reaches no renderer. The #20960 census measured
+ * that at objectui `main` `5262f7dd` over every key this repo's examples wrote
+ * here (`format`, `currency`, `color`, `suffix`, `showLegend`, `horizontal`,
+ * `showDataLabels`): none is read on that path — only the legacy inline arm,
+ * which a widget carrying a `dataset` never reaches, spreads the bag into
+ * component props — so each was removed from its producer rather than
+ * declared. `description` is the opposite case, read but unwritten: no
+ * authored source writes it (only `translateDashboard` overlays it, from a
+ * `subCaption` bundle entry — `system/i18n-resolver.ts`), and objectui#11228
+ * ruled it out with the inline dialect, so it stays undeclared and dropping
+ * the read is objectui's follow-up. ⛔ A key is declared here only with both
+ * a writer and a read site on the dataset-bound path, and it then joins
+ * `CONSUMED_WIDGET_OPTION_KEYS` in `@objectstack/sdui-parser`
+ * (`check:widget-option-census`).
+ *
+ * Presentation has declared homes instead: a number's face is the dataset
+ * MEASURE's `format` + `currency`, a tile's accent is the widget's
+ * `colorVariant`, and a chart's look is the widget's `chartConfig`.
+ *
+ * What the declared keys below buy is a real contract for the four that are
+ * NOT presentation-only: they change the SQL the dataset query compiles to, so
+ * a typo (`sortDirection`, `granularity`) is now an author-time type error
  * instead of an option that reads as if it works and silently does nothing.
  *
  * The dashboard/report renderer lowers these into the `DatasetSelection` it