docs(objectui): replace the phantom field-level visible key with the keys that exist

[os-elon]

Fixes#12935

Docs-only, two files, no spec change. objectui#6514's maintainer ruling of 2026-08-27
declined adding a field-level visible key to the contract, so the docs are the side
that is wrong.

The premise re-measured, and it holds

The card measured 3 occurrences across 2 files at aef1b7e641e7. Re-measured on today's
main (db39dfc1c9b0), the field-level population is unchanged at 3 — no fourth
occurrence, so the class is not being newly introduced. The markdown population is also
still 453 files, matching the card's scan.

FieldSchema and FormFieldSchema are both strict objects that declare hidden and
visibleWhen and notvisible, so the key is refused by name, before either
documented value shape is reached. Confirmed from the generated reference tables, which
are rendered from the spec rather than hand-written:

• content/docs/references/data/field.mdx — visibleWhen at line 105, hidden at 110,
  no visible row.
• content/docs/references/ui/view.mdx — FormSection.fields[number] declares hidden,
  visibleWhen and the deprecated visibleOn; no visible, and no breakpoint key.

Instrument dual: the same grep over the same generated corpus returns many visible
rows on action.mdx and app.mdx (where the key really is declared), so the zero on
field.mdx is a reading rather than an instrument failure.

The two edits

concept.mdx section 3 now teaches visibleWhen with a CEL predicate over record,
plus a callout naming the polarity trap the card flagged — hidden is INVERTED, so
visible: false becomes hidden: true, which is the mechanical repair an author is most
likely to get backwards.

The card's suggested repair was verified before it was written, not assumed:
FieldSchema.visibleWhen's own description is "Predicate (CEL) — field is shown only
when TRUE (else hidden). e.g. P-backtick-record.type == 'invoice'", so a
record.shipping_required predicate is expressible. The example uses has() to guard the
unset case, because an unbound reference faults and visibility's documented fallback is
"shown" — an unguarded predicate would show the field in exactly the case the example is
teaching you to hide it.

layout-dsl.mdx "Responsive Layout Modifiers" is rewritten rather than renamed,
because there is nothing to rename onto. Measured: this repo's spec declares no
field-level breakpoint visibility at all.responsiveStyles (ADR-0065) is the only
per-breakpoint channel and it lives on a page component
(packages/spec/src/ui/page.zod.ts:185), never on a form field or section. hiddenOn
was a key of the responsive layout block, retired at protocol 18 under ADR-0049 D2
as authorable-and-inert — packages/spec/src/ui/responsive.zod.ts keeps it only as
guidance text pointing at the CSS translation.

So rewriting the example to hiddenOn — the card's first option — would have documented
a key that is both objectui-tier and retired-as-inert here: a new defect of exactly the
family this card is about. The section now states that responsive behaviour is not a
field or section key, documents responsiveStyles on a page component, and records the
removal in a callout — the same shape this page already used for the previous sweep of
this family (the lazy / source / badge callout above it).

The page now agrees with itself. Its own "Visibility Rule" section, 300 lines below,
already said breakpoint show/hide is responsiveStyles and that responsive.hiddenOn
was retired. The two halves contradicted each other until this change.

One bounded in-place repair, declared

The adjacent "Orientation-Specific Layout" example — columns: { portrait: 1, landscape: 2 } on a section — is removed in the same edit. It is inside the H2 being rewritten, and
leaving it would have left a heading called "Responsive Layout Modifiers" whose only
remaining content was another phantom responsive shape. The correct form is pinned by
generated evidence, not by judgment: content/docs/references/ui/view.mdx:293 declares
FormSection.columns as Enum<'1'|'2'|'3'|'4'> | 1|2|3|4 — a scalar, never a map. Same
two files, same gate family, no new verification surface.

What was deliberately NOT repaired

Four further visible: occurrences survive in these two files at other tiers, filed
as #13087 rather than folded in, because they are not this card's defect:

• layout-dsl.mdx:363,369 — section tier, key refused by name. The correct spelling is on
  the same page, but one of the two examples is a permission: admin gate, and rewriting
  it as a visibleWhen role test would teach the anti-pattern the spec explicitly warns
  about (nothing server-side evaluates a form-view section predicate, and it faults open
  on the public form route). That needs a documentation decision, not a rename.
• concept.mdx:592,595 — action tier, where visible genuinely is a declared key
  (action.mdx:84: boolean, CEL string, or envelope). The defect there is the filter-object
  value, a different mechanism. Folding it in would have made this PR's own claim false.

Also filed: #13086 — the reason this class survives sweeps. check:skill-examples is
the only gate that compiles doc prose against the spec, and it reads only ts/tsx
fences, opt-in by marker. YAML fences — where every metadata authoring example lives —
are outside its population by construction. This page survived two prior hand sweeps of
the same family (#8251, #8306) for that reason.

Verification

Full derived gate family re-run at head cafc34c344, after merging origin/main and
rebuilding (turbo run build for spec / lint / formula / client / client-react).

The family is node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack,
re-derived on the synced tree — the first derivation printed STALE TREE while still
exiting 0, and one of the files it named stale was scripts/docs-audit/affected-docs.mjs,
a family directly relevant here. Re-derived after the merge the warning is gone and the
25-family list is byte-identical.

24 of 25 green. Verdict lines, quoted from the gates themselves:

• check:doc-anchors — "279 internal #fragment link(s) across 410 source file(s) all
  resolve to a real heading" (this one caught two ADR filenames I had guessed wrong;
  both corrected to the real files).
• @objectstack/spec check:docs — "231 generated files in sync with packages/spec"
• check:skill-examples — "260 prose examples type-check across 3 surface(s)"
• check:docs-audit-scope — "docs-accuracy-audit scope is in sync with content/docs/:
  189 hand-written doc(s)"
• check:role-word — "OK, no new occurrences of the reserved word"
• check:nul-bytes — green. Not in the derived family; added because any edit owes it.
  Independent control-byte scan of both files is also clean, with a positive control
  proving the scanner returns a hit on a file that does carry one.

The 25th, scripts/check-test-completeness.mjs, is NOT MEASURED locally rather than
red: it takes a turbo test log as its argument and only runs meaningfully inside CI's
Test Core job. Its exit 1 is the usage message.

scripts/docs-audit/affected-docs.mjs reports "0 docs name something this change touched
across 0 changed package(s)" — expected, since the diff touches no package source.

Repo-wide eslint, narrowed and proved

pnpm lint was not run. The narrowing is a measurement, not a skip: read from eslint's
own config via ESLint.isPathIgnored, both changed files return true (outside the
matched population), while the control scripts/check-doc-anchors.mjs returns false.
Since the two files are not in eslint's population at all, this diff cannot move an
eslint verdict on any file, touched or untouched.

No changeset — derived, not assumed

skip-changeset applies, proved rather than asserted: 69 package.json files in the
workspace declare a files whitelist and not one contains an entry matching content
or docs; content/ is not covered by any pnpm-workspace.yaml package glob and carries
no package.json. Nothing in this diff is published by any package, so the PR releases
nothing. The diff touches no skills/** path, so no published-skill line budget applies.

Generated by Claude Code

---

Generated by Claude Code