[finding] docs teach a field-level visible key in three shapes, none of which exists — FieldSchema refuses the spelling by name #12935

Found while implementing objectui#6514 (the two app-shell call sites moving off the
spec-refused fields[].visible onto the declared hidden / visibleWhen). Filed
unassigned, recording only — not graded, no type. Related to objectui#6514 but not part
of it: that card is a renderer call-site change in objectui; this is a docs defect here.

Measured on origin/main @ aef1b7e641e7cead90f35db7cd1e06c46a021944.

What was measured

FieldSchema is a strictObject and visible is not one of its keys. It appears in
FIELD_KEY_GUIDANCE (packages/spec/src/data/field.zod.ts) as prose that REFUSES the
spelling, deliberately not as an alias:

visible is not a field key, and which key you want depends on the form: a static
boolean is hidden — INVERTED, so visible: false is hidden: true — while a
per-record CEL predicate is visibleWhen (shown only when TRUE). Its siblings are
readonlyWhen and requiredWhen.

The guidance's own comment says the prose form was chosen over a rename deliberately,
because "this surface declares BOTH forms and the two answers have opposite polarity".

Scanning the 453 content/docs/** and skills/** markdown files at that ref for a
visible: key appearing inside a fields: block finds 3 occurrences across 2 files,
in three mutually incompatible shapes, and not one of them is spec-valid:

• content/docs/protocol/objectui/concept.mdx:614 — section "3. Conditional Field
  Visibility" teaches a filter-object form:

  fields:
    - name: shipping_address
      type: textarea
      visible: { shipping_required: true }  # Show only if checkbox checked

• content/docs/protocol/objectui/layout-dsl.mdx:530 and :537 — section
  "Device-Specific Visibility" teaches a breakpoint map:

  fields:
    - name: detailed_description
      visible:
        desktop: true
        tablet: true
        mobile: false

Neither shape exists anywhere. FieldSchema rejects the KEY before either value shape is
reached, so both examples produce a save-blocking validation error naming visible — and
the guidance the author then reads points at hidden / visibleWhen, neither of which
takes a filter object or a breakpoint map. The responsive intent in the second example is
spelled hiddenOn at the tier that has breakpoints (objectui packages/types/src/mobile.ts),
not visible.

Why it is worth recording

This is the phantom-key family that objectstack#8251 and objectstack#8306 already worked
on layout-dsl.mdx — same file, same defect shape, different keys — and it survived both
sweeps. It is worse than an inert key, for two reasons:

• The docs are the reason the spelling circulates. objectui#6514's census found ZERO
  field-level visible keys in the framework's 113 *.object.* files, yet the renderer
  had been gating on the key for its whole life. Published examples teaching it are the
  most plausible remaining source of an author writing one.
• It bears directly on the two confidence gaps objectui#6514's analysis declared and could
  not close: whether deployments carry stored visible data written past schema
  validation, and whether third parties read the same key name. A documented spelling is
  exactly what a hand-written YAML or a third-party producer that never calls
  FieldSchema.safeParse would carry.

An AI author following either page writes metadata that cannot publish, and the polarity
trap in the guidance means the mechanical repair (visible: false becomes hidden: true)
is the one an author is most likely to get backwards.

Suggested repair, not a decision

Docs-only, in this repo. concept.mdx §3's example becomes visibleWhen with a CEL
predicate (P + backtick + record.shipping_required + backtick); layout-dsl.mdx's
responsive example either moves to the key that tier actually declares or is dropped if no
field-level breakpoint visibility exists there. No spec change is implied: objectui#6514
declined adding field-level visible to the contract (maintainer ruling 2026-08-27), so
the docs are the side that is wrong.

Re-check commands:

• git grep -n "visible" -- content/docs/protocol/objectui/concept.mdx content/docs/protocol/objectui/layout-dsl.mdx
• git grep -n "visible" -- packages/spec/src/data/field.zod.ts (FIELD_KEY_GUIDANCE, refusal prose)