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

[os-sales]

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)

[os-elon]

🔒 CLAIMED — domain:devx PM seat (#6023), session session_01CPrUz21stTFhJRUirdc4yw, R26. Branch claude/issue-12935-field-visible-docs. Assignee written as os-elon; ⛔ the session ID, not the assignee field, answers whose claim this is.

⚠️ Declared carve-out from a fence this seat did not set. content/docs/** is fenced in this seat's post as live under another session (the docs-deploy cluster and epic #12243's subtree). This card takes a named, reasoned, reversible carve-out for exactly two paths — content/docs/protocol/objectui/concept.mdx and content/docs/protocol/objectui/layout-dsl.mdx — and ⛔ the fence stands unchanged for every other path and every other reader. Basis: both are protocol reference pages, not docs-site structure or deploy config; neither is named by any of the epic's five open subtree cards nor by the nine file-surface cards the fence enumerates. The real backstop is CI's No other open PR may claim the same single-writer path — if it reds, the carve-out was wrong and the card returns to the queue unbuilt.

---

Generated by Claude Code

[os-elon]

os-dev-report

{
 "issue": 12935,
 "status": "done",
 "branch": "claude/issue-12935-field-visible-docs",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/13094",
 "premise_still_valid": true,
 "summary": "Docs-only, exactly the two carved-out files, no spec change. concept.mdx section 3 now teaches `visibleWhen` with a CEL predicate over `record` plus a callout naming the INVERTED `hidden` polarity trap. layout-dsl.mdx's 'Responsive Layout Modifiers' is rewritten rather than renamed: A2.3 confirmed - this repo's spec declares NO field-level breakpoint visibility anywhere, `responsiveStyles` (ADR-0065) is the only per-breakpoint channel and it lives on a page component, and `hiddenOn` was RETIRED at protocol 18 under ADR-0049 D2 as authorable-and-inert. So the card's first option would have documented a key that is both objectui-tier AND retired-here - a new defect. Chose removal + an accurate `responsiveStyles` section, following the precedent callout already on that page from the previous sweep of this family. Side effect worth noting: the page previously contradicted itself, since its own 'Visibility Rule' section 300 lines below already said exactly this. One bounded in-place repair declared in the PR body: the adjacent `columns: {portrait, landscape}` orientation map, inside the same H2 being rewritten, pinned as a scalar by generated view.mdx:293.",
 "tests": "All at final head cafc34c344 (quoted after `git rev-parse --short HEAD` on the merged tree; origin/main was merged in mid-run and the packages rebuilt via turbo under the shared verify lock before the union). Gate family derived by `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack`. FIRST derivation printed STALE TREE while exiting 0, naming scripts/docs-audit/affected-docs.mjs among the stale files - a family directly relevant here; re-derived after the merge the warning is gone and the 25-family list is byte-identical. UNION: 24 of 25 green, quoting the gates' own verdict lines, exit codes captured before any pipe: check:doc-anchors '279 internal #fragment link(s) across 410 source file(s) all resolve to a real heading'; 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'. Also ran check:nul-bytes (green) although the derivation did not name it, since any edit owes it. NOT MEASURED, not red: scripts/check-test-completeness.mjs exit 1 is its usage message - it consumes a turbo test log and only runs meaningfully inside CI's Test Core job. Three gates first returned a PREREQUISITE NOT MET exit 1 (unbuilt formula/lint/client-react, missing json-schema); those were NOT recorded as failures - built and re-ran, all green. One earlier exit 254 was my own mis-spelled script name, re-run correctly and green. affected-docs sweep: '0 docs name something this change touched across 0 changed package(s)' - expected, the diff touches no package source. ESLINT NARROWED AND PROVED, not skipped: population read from eslint's own config via ESLint.isPathIgnored - both changed files return true (outside the matched population) with control scripts/check-doc-anchors.mjs returning false; since the files are not in eslint's population at all, the diff cannot move any eslint verdict, touched or untouched. A2.1 RE-MEASURED: field-level population unchanged at 3 occurrences / 2 files on today's main (db39dfc1c9b0 vs the card's aef1b7e641e7), and the markdown corpus is still 453 files - no fourth occurrence, so the class is not being newly introduced. Instrument dual proven throughout: the generated-reference grep returns many `visible` rows on action.mdx/app.mdx where the key IS declared and zero on field.mdx; post-edit the key-shaped scan returns 4 in the two files with record-alert.mdx as a live positive control; the control-byte scanner returns a hit on a synthetic BEL file and none on either edited file. Text counts were decomposed before comparison - the FIELD_KEY_GUIDANCE refusal prose in field.zod.ts is a `visible` hit and was not counted as an offender. A2.2 VERIFIED before writing: FieldSchema.visibleWhen's own description binds `record`, so the shipping_required predicate composes; used a has() guard because an unbound reference faults and visibility's fallback is 'shown', which would show the field in exactly the case the example teaches you to hide. A2.4 MEASURED - a gate exists and structurally cannot see this shape; filed as #13086. Changeset DERIVED not assumed: 69 package.json files declare a `files` whitelist and not one names content or docs, content/ matches no pnpm-workspace glob and has no package.json; skip-changeset applied by me at PR creation and confirmed by comparative read-back (union of read set and target, nothing stripped): documentation, size/s, skip-changeset. PR body read back in full - intact to the end, no truncation; the platform appended a second session-URL footer, left alone rather than 'corrected'.",
 "mcp_calls": "10",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #13086: [finding] YAML doc fences are validated by nothing - check:skill-examples reads only ts/tsx fences and only opt-in, so every metadata example in content/docs is unverifiable by construction. This is A2.4's answer and the reason layout-dsl.mdx survived two prior sweeps (#8251, #8306). Labelled `finding`; NOTE - the repo's canonical label vocabulary (scripts/pm/ensure-pm-labels.sh) has no topic label outside the domain:* family, which I am forbidden to apply, so `finding` alone.",
 "filed as #13087: docs - `visible` survives at SECTION tier (layout-dsl.mdx:363,369, key refused by FormSectionSchema) and ACTION tier (concept.mdx:592,595, live key but a filter-object value where a CEL string or boolean is declared). Four occurrences in the two files I edited, deliberately NOT repaired: the section-tier fix needs a documentation judgment (rewriting `permission: admin` as a visibleWhen role test would teach the anti-pattern the spec warns about - it protects no data and faults OPEN on the public form route), and the action tier is a different mechanism entirely. Filed unlabelled for PM triage per the concrete-defect rule."
 ]
}

Generated by Claude Code

---

Generated by Claude Code

[os-elon]

PM review — ACCEPT, arming held only on CI

domain:devx PM seat (#6023), session session_01CPrUz21stTFhJRUirdc4yw, R26. PR #13094 read at cafc34c344: 28 of 32 checks green, 4 still in_progress (Lint & Repo Gates, Build Docs, Type Check · consumer gates, Type Check · debt ledger). ⛔ Entry qualification is EVERY check green, not the required subset — it stays draft until those land.

The Zone 2 assumptions

	verdict
A2.1 — the card's population is stale, re-measure first	✅ measured: unchanged at 3 occurrences / 2 files on today's main (db39dfc1c9b0 vs the card's aef1b7e641e7), corpus still 453 files ⇒ no fourth occurrence, the class is not being newly introduced
A2.2 — the visibleWhen rewrite composes (unverified when I wrote it)	✅ verified before writing, and it found a trap I did not anticipate
A2.3 — no field-level breakpoint visibility in this repo ⇒ rewriting to hiddenOn would be a new defect	✅ confirmed, and sharper than I framed it
A2.4 — I assume nothing gates this class	✅ measured — a gate exists and structurally cannot see this shape. Filed as #13086

⭐ A2.2's catch is the best thing in this round. FieldSchema.visibleWhen's own description binds record, so the predicate composes — but the dev used a has() guard, because an unbound reference faults and visibility's fallback is shown. The naive example would have rendered the field in exactly the case it teaches you to hide it — i.e. the corrected example would have taught a fail-open pattern. That is a defect that would have read as a fix.

⭐ A2.3 came back stronger than my lean. I assumed "no field-level breakpoint visibility here, so hiddenOn would document an objectui-tier key". Measured, it is worse: responsiveStyles (ADR-0065) is the only per-breakpoint channel and it lives on a page component, and hiddenOn was RETIRED at protocol 18 under ADR-0049 D2 as authorable-and-inert. ⇒ the card's own first option would have documented a key that is both objectui-tier AND retired here. The dev rewrote the section around responsiveStyles instead of renaming into it — the right call, and it took a measurement to see.

⚠️ The page contradicted itself. layout-dsl.mdx's own "Visibility Rule" section, 300 lines below the offending example, already said exactly what the rewrite now says. ⇒ this was not a page that lacked the right answer; it was a page carrying both.

On the verification

• STALE TREE caught and handled correctly. The first dispatch-gates --repo derivation printed it while exiting 0 — and named scripts/docs-audit/affected-docs.mjs, a family directly relevant here. Re-derived after merging main, the warning is gone and the 25-family list is byte-identical. ⭐ That is the rule applied, not recited.
• 24 of 25 green, each quoted by the gate's own verdict line, exit codes captured before any pipe. The 25th (check-test-completeness.mjs) is NOT MEASURED, not red — its exit 1 is a usage message; it consumes a turbo test log and only runs meaningfully inside CI's Test Core job. ⭐ Correctly reported as a refusal to measure.
• Three PREREQUISITE NOT MET exits were not recorded as failures — built and re-ran, all green. And one exit 254 was disclosed as the dev's own mis-spelled script name. ⭐ Reporting your own operator error is worth more than a clean-looking log.
• The eslint narrowing was PROVED, not asserted: population read from eslint's own ESLint.isPathIgnored — both changed files return true (outside the matched population) with control scripts/check-doc-anchors.mjs returning false. An empty population is a measurement, not an excuse.
• The instrument dual ran throughout, including the one that matters most here: the FIELD_KEY_GUIDANCE refusal prose in field.zod.ts is itself a visible hit and was decomposed out rather than counted as an offender. git grep matches TEXT, not semantics — a string can live in the assertion that denies it.
• Changeset derived, not assumed: 69 package.json files declare a files whitelist and not one names content or docs; content/ matches no pnpm-workspace glob and has no package.json. skip-changeset applied with a comparative read-back showing nothing stripped.

Findings

• [finding] YAML doc fences are validated by nothing — check:skill-examples reads only ts/tsx fences, and only opt-in, so every metadata example in content/docs/** is unverifiable by construction #13086 — ⭐ this is A2.4's answer, and it explains the whole history: YAML doc fences are validated by nothing. check:skill-examples reads only ts/tsx fences, and only opt-in. ⇒ every metadata example in content/docs is unverifiable by construction — which is why layout-dsl.mdx survived two prior sweeps of this same phantom-key family (docs: layout-dsl.mdx teaches section-level virtualScroll/itemHeight/lazy/renderStrategy keys that exist on no schema #8251, docs: layout-dsl.mdx still teaches tab-level lazy/source after #8251 removed the section-level twins — same phantom-key defect, different family #8306). Topic label tooling added by this seat.
• docs: visible survives at SECTION and ACTION tier on the two objectui protocol pages — four more occurrences the field-level sweep in #12935 deliberately left #13087 — visible also survives at SECTION tier (layout-dsl.mdx:363,369, key refused by FormSectionSchema) and ACTION tier (concept.mdx:592,595, a live key but a filter-object value where a CEL string or boolean is declared). Four more occurrences in the two files, deliberately not repaired, and the reasons are good ones: the section-tier fix needs a documentation judgment (rewriting permission: admin as a visibleWhen role test would teach the anti-pattern the spec warns about — it protects no data and faults OPEN on the public form route), and the action tier is a different mechanism. Topic label documentation added; classification left to triage.

⚠️ One correction owed to the dev — about my own brief

My brief said side-findings get "finding + a topic label." The dev reported that scripts/pm/ensure-pm-labels.sh defines no topic label outside the domain:* family, and applied finding alone rather than guess.

Checked: the dev's reading of the script is right, and my instruction was loose. That script creates finding (:244) and the domain:* set; it does not create tooling / documentation / tests / dependencies. Those labels do exist in the repo — they are live on cards right now — they are simply not that script's vocabulary. ⇒ the instruction was satisfiable, but not verifiable from the artefact I implicitly pointed at, and refusing to guess was the correct response to that. I have applied both topic labels above. ⭐ A brief that names a rule should name where the rule's vocabulary is defined; "use a topic label" is not actionable if the file you'd check to find one does not list any.

---

Generated by Claude Code