docs(fields): `lookup.mdx` still claims option `description` is aligned with `@objectstack/spec` — the spec refuses it by name

[os-project-manager]

Filed unassigned by the domain:ui execution seat while implementing objectui#7014 Q1 (the Tier-1 select-option convergence). Recording, not claiming. Not fixed in that PR: the fix is one prose sentence in content/docs/**, which pulls in the docs gate family (doc-component-types, doc-snippet-types, doc-fence-languages, docs-links) that the Q1 diff otherwise does not touch, so it is a separable docs-only change rather than a rider on a types refactor.

Dedupe: searched before filing; the one hit the instrument returned was objectui#6247 (closed, a different defect on the same key), so the nil result on this claim is a reading and not a blind instrument. No open card covers it.

The defect

PR #7510 corrected three doc comments that asserted the installed @objectstack/spec DECLARES a key it in fact refuses by name. One of those three claims survives, verbatim, in shipped documentation.

content/docs/fields/lookup.mdx:68:

It is a declared SelectOptionMetadata member (declared for exactly that consumption — objectui#6153 — and aligned with @objectstack/spec's SelectOptionSchema.description).

Re-measured today against the installed @objectstack/spec 17.2.0, each refusal behind a control that accepts the same payload minus the key (and with a value long enough that a too_small on value cannot be mistaken for the boundary — a one-character value fails for that different reason, which is how the ACCEPT below is known to be a reading):

SelectOptionSchema declared keys : color, default, label, value, visibleWhen
CONTROL clean option : ACCEPT
NEG-CONTROL 1-char value : REJECT too_small@value
option + description : REJECT unrecognized_keys(description)
FIELD control (clean option) : ACCEPT
FIELD option + description : REJECT unrecognized_keys(description) at [options.0]

So the claim is false in the direction that costs the reader the most: FieldSchema routes a select/lookup field's options through that strict schema, so a reader who trusts the sentence and authors description on an option in a published object document fails the whole field with a 422. The key itself is legitimate and consumed — LookupField really does search it (objectui#6153) — it is only the attribution that is wrong. That is the same failure class scripts/check-spec-symbol-derivation.mjs exists to prevent, and the same class PR #7510 corrected in the TypeScript JSDoc; the gate cannot see prose in content/docs, which is why this copy survived.

Landing objectui#7014 Q1 makes the contradiction sharper rather than milder: the published JSDoc on SelectOptionMetadata.description now states that the spec refuses the key by name, one directory over from a docs page saying it is aligned with the spec.

A second, separate instance — do NOT fold it into the same edit

.changeset/6140-field-metadata-rows-option-description.md:18 carries the same false sentence:

SelectOptionMetadata.description — secondary option text LookupField searches on authored static options and emits from recordToOption, aligned with @objectstack/spec SelectOptionSchema.description.

That changeset is still unconsumed, so the sentence is scheduled to ship into the CHANGELOG and from there into the release notes. It cannot simply be edited by a passing PR: scripts/check-changeset-overwrite.mjs fails any change that modifies a pre-existing changeset, and it is right to — the correction has to be a deliberate call about an already-declared release note, not a drive-by. Flagging it here so the two are triaged together and the release does not publish the claim the code now contradicts.

Suggested shape of the fix

Reword the lookup.mdx sentence the way the JSDoc was reworded: the key is an objectui-side read-model extension that the spec refuses by name, declared because LookupField consumes it, and it must never reach an authored object document. No behaviour, no type and no export moves.

Generated by Claude Code