docs(spec): the DashboardWidgetOptionsSchema doc comment says a misspelled options key compiles and parses, and a wrong value is the type error (#21275)

Fixes #21210
Clause-②: no

## What changed

`packages/spec/src/ui/dashboard.zod.ts`: the
`DashboardWidgetOptionsSchema` doc comment said that a misspelled widget
`options` key (`sortDirection`, `granularity`) "is now an author-time
type error". That is false. The bag ends in `.passthrough()`, so such a
key compiles and parses. The paragraph now says three things:

- A wrong VALUE for a declared key (`sortOrder: 'sideways'`) is the
author-time type error and the parse error.
- A misspelled KEY compiles and parses like any other extra key, and it
changes nothing.
- The `unconsumed-widget-option` warning from `os validate`, `os build`
and `os lint` names the misspelled key. It is a warning, so none of the
three commands fails on it.

`.changeset/21210-widget-options-docblock.md` is `'@objectstack/spec':
patch` with `Clause-②: no`. The comment ships to npm in two places. It
is in `src/**/*.zod.ts`. After the build it is also in the published
`dist/ui/index.d.ts` and `dist/ui/index.d.mts`, where the new sentence
is measured. The schema's shape does not change.

## The measurements behind each clause (HEAD `9c765bf4f5`)

1. **Type error.** `tsc --noEmit` ran against the BUILT spec, with
TypeScript 6.0.3, `strict` and `NodeNext`. `--listFiles` shows 33 files
under `packages/spec/dist` and 0 under `packages/spec/src`. Each case is
written twice: once as a `DashboardWidgetOptions` annotation, and once
inside `defineStack({ dashboards })`.
   - `{ sortBy: 'total_amount', sortDirection: 'desc' }` compiles clean.
   - `{ granularity: 'month' }` compiles clean.
- `{ sortBy: 'total_amount', sortOrder: 'sideways' }` is TS2322 at both
sites: `Type '"sideways"' is not assignable to type '"asc" | "desc" |
undefined'`.
- The control, `{ dateGranularity: 'month', sortBy: 'total_amount',
sortOrder: 'desc', limit: 10 }`, compiles clean.
   - tsc exits 2, and both errors come from the wrong-value file.
2. **Doors.** A probe project ran through the built CLI. It is a
`defineStack` with one object, one dataset and one dashboard. The
dashboard has a control widget with only declared keys, a widget with
`sortDirection` and a widget with `granularity`.
- `os validate` exits 0 with 2 warnings. `--json` reports `rule:
unconsumed-widget-option` and `severity: warning` at
`dashboards[0].widgets[1].options` and
`dashboards[0].widgets[2].options`.
   - `os build` exits 0 with the same 2 warnings, and names the rule.
   - `os lint` exits 0 with `Warnings (2)`, and names the rule.
   - The control widget draws no finding.
- Wrong-value control: the same probe with `sortOrder: 'sideways'` makes
`os validate` exit 1 with `dashboards.0.widgets.0.options.sortOrder:
Invalid value 'sideways'. Expected one of: asc, desc.`
- The level and the three commands match the rule's registration in
`packages/lint/src/authoring-rules.ts` (`tier: 'advisory'`, `commands:
ALL`).

## Census of the same claim

`git grep -i "author-time type error"` over `packages/spec/src`,
`content/docs` and `skills`:

- `packages/spec/src/ui/dashboard.zod.ts` is corrected in this PR.
- `content/docs/ui/dashboards.mdx` is already correct on `main`. It says
a misspelled key parses and the warning names it.
- `skills/objectstack-ui/rules/dashboards.md` has the claim at this
branch's base `30c530e5c0`. PR #21205 already corrected it on `main`
(`f148852752`; `git merge-base --is-ancestor f148852 origin/main`
exits 0). No separate Tier H PR is needed, and this PR does not touch
`skills/**`.
- `content/docs/references/**` has 0 hits. build-docs does not lift a
schema-level doc comment into the reference page. It lifts only the
module header and the `.describe()` text. `check:docs` is green after
the edit with no regenerated diff, so no reference page changes in this
PR.

## Verification (HEAD `9c765bf4f5`)

- `pnpm --filter @objectstack/spec build`: exit 0 (lock verdict
`command-exit 0`).
- `pnpm --filter @objectstack/spec check:generated`: all 15 generated
artifacts are up to date, read against the dist that build produced.
- `pnpm --filter @objectstack/spec typecheck`: exit 0.
- `pnpm --filter @objectstack/spec exec vitest run --project local
--maxWorkers=2`: 597 files and 17465 tests passed, 1 todo.
- `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
--commands` (no paths) derives 79 families. All 79 ran and exited 0. The
`--ran` reconcile reads 79 derived, 79 run, 0 NOT-MEASURED, 0 UNRUN.
`check:dual-build-cjs-loads` first exited 3 (PREREQUISITE NOT MET,
because 9 packages had no `dist/`). After those packages were built, it
exited 0.
- eslint was narrowed to the one changed `.ts` file. `--print-config`
resolves that file, so it is in the linted population, with 5 rules.
`--format json` reports 1 file, 0 errors and 0 warnings. The config
enables no type-aware linting (no `parserOptions.project`, no
`projectService`), so a comment edit in this file cannot change any
other file's result. The repo-wide `pnpm lint` is left to CI.

## Acceptance notes

- `os validate` prints the warning text without the rule code in its
human output. `os build` and `os lint` print `unconsumed-widget-option`,
and `os validate --json` carries it. The doc comment uses the code as
the warning's name, and all three commands carry that code in their
machine output. Noted here, not filed.
- The card says the sentence lifts into the generated reference page.
The measurement shows it does not (see the census).

---
_Generated by [Claude
Code](https://claude.ai/code/session_01UtnxvdiN376GF3sgXwAw4d)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/21210-widget-options-docblock.md

@@ -0,0 +1,7 @@
+---
+'@objectstack/spec': patch
+---
+
+The `DashboardWidgetOptionsSchema` doc comment no longer says that a misspelled widget `options` key is an author-time type error. The bag ends in `.passthrough()`, so a misspelled key such as `sortDirection` or `granularity` compiles and parses like any other extra key, and it changes nothing at render time. A wrong value for a declared key, such as `sortOrder: 'sideways'`, is the type error and the parse error. `os validate`, `os build` and `os lint` name the misspelled key with the `unconsumed-widget-option` warning, which does not fail any of the three commands. Only the comment changed. The schema's shape is the same.
+
+Clause-②: no

packages/spec/src/ui/dashboard.zod.ts

@@ -242,8 +242,13 @@ const WIDGET_HISTORY =
  *
  * 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.
+ * a wrong VALUE for one (`sortOrder: 'sideways'`) is an author-time type error
+ * and a parse error. A misspelled KEY is neither: the bag is open, so
+ * `sortDirection` or `granularity` compiles and parses like any other extra
+ * and changes nothing. What names it is the `unconsumed-widget-option`
+ * warning `os validate`, `os build` and `os lint` raise for a key the
+ * dataset-bound path does not read — a warning, so none of the three fails on
+ * it.
  *
  * The dashboard/report renderer lowers these into the `DatasetSelection` it
  * posts (`dateGranularity`, `order`, `limit`); see the field docs on