docs(guide): layout guide's PageHeaderProps list names a retired key and omits three live ones; its registration-inputs claim is two entries behind

[claude]

Found while adding the canonical-key banner for #3906 (PR #5922). Not fixed there — different defect class, filed unassigned for triage.

content/docs/guide/layout.md states a PageHeaderProps key list that the contract contradicts, and a registration input list that packages/layout contradicts. Two claims, both measurable, both in the same blockquote.

Claim 1 — a retired key listed as declared, three live keys missing

content/docs/guide/layout.md:287:

PageHeaderProps — the contract for the canonical page:header node — declares
title / subtitle / icon / breadcrumb / actions / aria

Measured against the installed @objectstack/spec (PageHeaderProps.safeParse, values quoted from the parser's own verdict):

• { title: 'Accounts', icon: 'users' } → REJECTED, code=invalid_type path=["icon"], message: ``page:headerpropertyicon` was removed ... (ADR-0087 D2) — no renderer ever read it ...`. `icon` is a `retiredKey` tombstone on this shape, not a declared key.
• { title: 'Accounts', subtitle: 'All accounts' } → OK, output keys ["title","subtitle","breadcrumb","recordChrome","showStar","showCopyId"]. The guide's list omits recordChrome, showStar and showCopyId.
• Negative control, { title: 'Accounts', zzzNotAKey: 1 } → REJECTED unrecognized_keys, so the shape really is strict and the readings above mean something.

The sibling page already says the right thing — content/docs/layout/page-header.mdx lists title / subtitle / breadcrumb / actions / recordChrome / showStar / showCopyId / aria. So two docs pages disagree, and the guide is the wrong one. An author who trusts it writes icon on a canonical node and gets a parse failure naming a key the docs told them to use.

Claim 2 — the registration input list is two entries behind

Same blockquote, content/docs/guide/layout.md:288:

and page-header's registration declares only title and subtitle as authorable inputs

packages/layout/src/index.ts:121 declares four: title, subtitle, icon, actions — icon and actions were added deliberately (the registration's own comment cites objectui#3829 and objectui#3972, on renderer-read-point evidence). The word "only" is what makes this a false statement rather than an incomplete one.

Why no gate caught it

Neither claim lives in a code fence, so check-doc-component-types (type literals in code blocks) and check-doc-snippet-types (ts/tsx block compilation) are both structurally blind to it. content/docs/guide/layout.md is additionally in check-doc-snippet-types' UNGATED_DOCS debt list. Prose claims about a declared surface have no mechanical judge in this repo today — worth noting when sizing this, because the same drift can recur silently anywhere prose restates a schema.

Suggested shape

Re-derive both lists from the sources rather than hand-editing: the spec shape for claim 1, registerLayout()'s inputs for claim 2 — and consider whether the two lists belong on the guide at all, given the reference page already carries them and only one of the two copies stayed current.

---

Generated by Claude Code

[claude]

Triage (daily round, session session_01Kktexqp6uVuFMztvvTMf3V, 2026-08-24): lands in content/docs/guide/layout.md (published docs face) → domain:ui + pm:queue, Task. Both claims are measured against the installed contract; fix the key list (drop tombstoned icon, add the three live keys) and the registration-inputs claim against packages/layout current source.

---

Generated by Claude Code

[yinlianghui]

Claim: PM loop round 38 (refill slot)
Session: session_01CSoz9uGhaaSgiq3hshtN7L
Branch: claude/issue-5923-layout-guide-pageheader-keys
Worktree: objectui-issue-5923
Domain: domain:ui
File surface: content/docs/guide/layout.md — the one blockquote at :287-288 — plus a changeset if one is owed. ⛔ Nothing else. ⛔ ⛔ Never content/docs/releases/.
Container & model: S, mode:subagent, model: opus
Clause-②: no — prose only, no contract accept/reject behaviour changes and no published surface widens.
⚠️ Serial: siblings in flight touch packages/types (#5859), packages/plugin-tree (#6014), app-shell/src/utils/ + views/RecordDetailView.tsx + plugin-detail/src/synth/ (#5795), app-shell/.../metadata-admin/previews/ (#5725). content/docs/ is uncontended. You will read packages/layout/src/index.ts and the installed @objectstack/spec — ⛔ do not write to either.

裁决 — triage

Triage (daily round, 2026-08-24 01:30Z), verbatim:

lands in content/docs/guide/layout.md (published docs face) → domain:ui + pm:queue, Task. Both claims are measured against the installed contract; fix the key list (drop tombstoned icon, add the three live keys) and the registration-inputs claim against packages/layout current source.

Two false claims in one blockquote: (1) PageHeaderProps "declares title / subtitle / icon / breadcrumb / actions / aria" — icon is an ADR-0087 D2 retiredKey tombstone on this shape, and three live keys are missing; (2) "page-header's registration declares only title and subtitle" — packages/layout/src/index.ts:121 declares four.

PM mechanism assumptions — measure, do not inherit

1. ⛔ The card's own evidence has a trap in it, and copying the card is how you fall in. Its measurement quotes safeParse output keys — ["title","subtitle","breadcrumb","recordChrome","showStar","showCopyId"] — and from that concludes "the guide omits recordChrome, showStar, showCopyId". That conclusion is right. But an output-key list is not a declared-key list: it shows the keys present after defaults are applied, so an optional key with no default never appears. Note that actions and aria are absent from that output while the sibling reference page content/docs/layout/page-header.mdx lists both. ⛔ If you write the guide's new list from the card's output keys, you will silently delete two live keys. Derive the list from the shape's declared keys (walk the zod shape / the type, not one parse result), and show both readings side by side in your report so the difference is on the record.
2. ⚠️ icon is not simply absent — it is a tombstone with a message. The parser rejects it by name with an ADR-0087 D2 explanation. So "drop icon" is not the whole edit: state why it is gone where a reader who has icon in an existing schema will see it, rather than leaving them to rediscover the parse failure. ⛔ Do not invent the retirement rationale — quote the tombstone's own message.
3. ⚠️ Claim 2's defect is the word "only". packages/layout/src/index.ts:121 declares title, subtitle, icon, actions, and the registration's own comment cites objectui#3829 and objectui#3972 as renderer-read-point evidence. Re-derive that list from current source — the card measured it, but packages/layout may have moved since 01:12Z today. ⚠️ Note the awkwardness you are about to document and do not paper over it: icon is a retired key on the spec shape and simultaneously a declared registration input. If that is genuinely the state of the tree, say so plainly in the guide; if your measurement says otherwise, ⛔ stop and report — that would be a contract finding, not a docs fix.
4. ⚠️ Nothing mechanically judges this file, so your derivation is the verification. The card establishes it: neither claim is in a code fence, so check-doc-component-types and check-doc-snippet-types are structurally blind, and content/docs/guide/layout.md is additionally in check-doc-snippet-types' UNGATED_DOCS debt list. ⚠️ Therefore a green CI run is not evidence your new text is true — it is only evidence you broke nothing. Say that explicitly in the report rather than letting green stand in for correctness.

PM建议路线 — and a route the card leaves open that you ⛔ may not take

Fix in place, and add a pointer to content/docs/layout/page-header.mdx as the reference face. The card's "Suggested shape" wonders "whether the two lists belong on the guide at all" — ⛔ do not delete the lists. That is a docs-structure decision the card explicitly declines to take and this dispatch does not grant. If, having done the fix, you think deletion is the better end state, ✅ say so in the report with your reasoning and leave it for a ruling.

Verification

Predict the direction before running. Prove the edit on disk by grepping the injected text and, separately, the removed text — for this card that means the retired icon mention is gone from the claim-1 list, the three live keys are present, and the word only is gone from claim 2. ⚠️ Print the landing site; ⚠️ assert anchor uniqueness before writing (this blockquote's phrasing may well appear elsewhere in the file); ⚠️ restore any probe mutation under trap … EXIT INT TERM with a cwd-independent command and confirm git diff HEAD --stat shows only your intended file. Every zero-hit grep needs a known-present control.

Gates by name, with exit codes: node scripts/check-changeset-presence.mjs (⚠️ a docs-only change under content/docs/ may legitimately owe no changeset — quote the gate's own verdict line either way; if one is owed, this repo accepts empty frontmatter as the explicit "releases nothing" declaration), node scripts/check-doc-links.mjs, node scripts/check-doc-component-types.mjs, node scripts/check-control-bytes.mjs, and check:doc-snippets — ⚠️ for that last one state its verdict and its blindness: report whether this file is inside its scan surface at all, quoting the script's own DOCS_ROOT constant and the UNGATED_DOCS entry, rather than reporting a pass that means nothing here. ⚠️ If eslint does not lint this path, say so by quoting the config that excludes it, ⛔ not by your own judgement that prose needs no linting.

Deliverable

Draft PR, body with Fixes #5923. ⛔ Do not mark ready, ⛔ do not enqueue, ⛔ no auto-merge — the PM lands it. Post the terminal report here (plain-text first-line marker os-dev-report; ⛔ avoid short angle-bracket placeholders in prose — they render as HTML and vanish) and return it. State, per gate: command, exit code, what a red would have meant, and for the doc gates, what a green does not mean; plus the measured answer to each of assumptions 1–4 and any deviation with its reason.

---

Generated by Claude Code

[yinlianghui]

os-dev-report

{
 "issue": 5923,
 "status": "done",
 "branch": "claude/issue-5923-layout-guide-pageheader-keys",
 "pr": "https://github.com/objectstack-ai/objectui/pull/6082",
 "premise_still_valid": true,
 "summary": "Both false claims in the one blockquote at content/docs/guide/layout.md:288-298 are corrected in place, and the lists are kept (deletion is a docs-structure decision this dispatch does not grant). Claim 1's key list now names the 10 live declared keys of PageHeaderProps, derived by walking the zod shape rather than from a parse result; claim 2's 'only title and subtitle' is replaced by the four inputs packages/layout/src/index.ts:126-136 actually declares. The icon split (retired on the spec shape, live as a registration input) is genuinely the state of the tree — two different renderers — and is now stated plainly with the tombstone's own message quoted rather than a rationale invented. Commit 675d333a9; no changeset owed per the gate's own verdict. One out-of-scope finding filed.",
 "tests": "Gate union re-run AFTER the final commit, at HEAD 675d333a9 (exit codes captured before any pipe; verdict lines are each gate's own, not a bare $?). node scripts/check-changeset-presence.mjs EXIT=0 — 'No source of a released package changed in this range, so no changeset is owed.' (1 file changed, 0 under a released package's src/, 0 changesets added) — a red would have meant a released package's source changed undeclared; NO changeset is owed, so none was added and no empty-frontmatter declaration was needed. node scripts/check-doc-links.mjs EXIT=0 — 'Links are valid across 15 scan roots.' — a red would have meant the /docs/layout/page-header pointer resolved nowhere. node scripts/check-doc-component-types.mjs EXIT=0 — 'Every documented component type is registered.' (183 doc files, 1054 code blocks, 886 type literals). node scripts/check-control-bytes.mjs EXIT=0 — 5026 tracked text files scanned; plus my own out-of-gate scan of the changed file with grep -naP over the control-byte ranges: zero hits. node scripts/check-doc-snippet-types.mjs EXIT=0 — '157 of 157 block(s) judged, 0 failed'. That gate first exited 1 with 'The snippet program was NOT run: the packages it resolves against are not built' — an unbuilt tree, not a defect in this change; resolved by running the workflow's own steps (node scripts/check-doc-snippet-types.mjs --build-filter, then turbo run build over the 20 packages it names, 32/32 successful) before re-reading the result. EDIT PROVEN ON DISK: anchor uniqueness asserted BEFORE writing (both anchors exactly 1 occurrence each, repo-wide grep for the key-list anchor returned only line 290); after writing, removed text and injected text grepped SEPARATELY, each prediction stated first and all met — removed: old icon-bearing key list 0, 'declares only title and subtitle' 0, any 'declares only' 0; injected: 'recordChrome / showStar / showCopyId' 1, 'maxVisible / mobileMaxVisible' 1, 'four authorable inputs' 1, tombstone quote 1; controls known-present: PageHeaderProps still 2, /docs/layout/page-header still 2. git diff HEAD --stat showed exactly one file. No probe mutation was needed, so no trap-based restore was required. Worktree removed WITHOUT --force (clean exit 0), confirming nothing uncommitted was left. Heavy commands (install, turbo build, snippet gate) all ran through scripts/pm/os-verify-lock.sh; one run waited 128s behind issue-5859's type-check and its VERDICT line correctly reported command-exit rather than a lock failure.",
 "open_questions": [
 {
 "question": "Should the guide keep its two lists at all, given content/docs/layout/page-header.mdx is the reference face and only one of the two copies stayed current? The dispatch forbade acting on this; raising it for a ruling as invited.",
 "options": [
 "A. Keep both lists (what this PR does) — the guide stays readable standalone; the duplication remains, and so does the drift risk that produced this card.",
 "B. Replace the guide's lists with a pointer to the reference page — one copy to keep current, but the guide's blockquote loses its self-contained answer to 'what may I write here', which is the question that blockquote exists to answer.",
 "C. Keep the guide's lists but add a mechanical judge so prose restating a declared surface cannot drift silently — the root cause both this card and the finding below share."
 ],
 "recommendation": "A for now, C as the durable fix. B trades one stale copy for a worse reading experience without removing the class: the reference page was ALSO measurably behind (see the finding below), so 'one copy' would not have been a correct copy. C is the only option that closes the class rather than this instance, but it is a new gate and belongs in its own card, not this docs fix."
 }
 ],
 "out_of_scope_findings": [
 "filed as #6083: content/docs/layout/page-header.mdx:66-68's PageHeaderProps list omits two live keys, maxVisible and mobileMaxVisible — the sibling reference page is itself two keys behind, so it was never the correct copy to defer to. Unassigned, no label, left for PM triage."
 ]
}

Measured answers to PM mechanism assumptions 1-4

1 — CONFIRMED, and the trap was real. Both readings side by side, against installed @objectstack/spec 17.2.0 (the version this branch's pnpm-lock.yaml resolves; read from an already-installed copy of the identical version, then re-confirmed after installing in my own worktree):

reading	result
card's safeParse output keys for {title, subtitle}	title, subtitle, breadcrumb, recordChrome, showStar, showCopyId — 6
declared keys, walking the zod shape	title, subtitle, icon, breadcrumb, actions, recordChrome, showStar, showCopyId, maxVisible, mobileMaxVisible, aria — 11 entries, 10 live + the icon tombstone

Writing the guide from the card's output list would have deleted actions and aria exactly as predicted, and would never have surfaced maxVisible / mobileMaxVisible — two live keys the card did not know about and which the sibling reference page also omits. Feeding all ten live keys in at once returns all ten in the output, which is the control proving the short list was an artifact of the input, not of the contract. Negative control {title, zzzNotAKey} still rejects with unrecognized_keys, so the shape is strict and these readings mean something.

2 — CONFIRMED; message quoted, not invented. icon is optional -> never in the shape — the tombstone lives in the shape, which is why it rejects with invalid_type path=["icon"] rather than unrecognized_keys. The guide now carries the tombstone's own words: "page:header property icon was removed in @objectstack/spec 17.0.0 (#6946, ADR-0087 D2) — no renderer ever read it … Delete the key."

3 — CONFIRMED against current source; the awkwardness is real and is documented, not papered over. packages/layout/src/index.ts:121 registers page-header; :126-136 declares four inputs — title, subtitle, icon, actions. Unchanged since the card was filed. This is not a contract finding: the registration's own comment explains the split, and it is coherent. PageHeaderProps.icon was retired upstream because the canonical page:header renderer never read it; @object-ui/layout's PageHeader does draw it beside the title (read at PageHeader.tsx:123, rendered at :231-233), which objectui#3829 ruled it keeps, and page-header-authorable-keys.test.tsx skips tombstones when deriving the spec key set so the retired key cannot read as parity. Different renderers, opposite read facts. The guide now says so plainly.

4 — CONFIRMED in conclusion, but one premise is STALE. The conclusion holds: neither claim is in a code fence, and check-doc-snippet-types compiles only TS_FENCE_LANGUAGES = ["ts","tsx","typescript"], so both doc gates are structurally blind to this edit. A green run is not evidence the new prose is true — only that nothing broke. The derivation above is the verification. The stale premise: content/docs/guide/layout.md is no longer in UNGATED_DOCS. Read at runtime, that map holds 44 entries and this file is not among them; the run reports "178 covered, 44 ungated" and this file sits in the covered set. It is covered at document level and still fence-blind to prose — so the right conclusion, for a different reason than the card gave. (A textual scrape of the constant gave me 12 entries; the runtime read of 44 is the authoritative one and corrected my own first measurement.)

eslint does not lint this path, per the config rather than my judgement: the only rule-bearing block in eslint.config.js is scoped files: ['**/*.{ts,tsx}'], so a .md file matches no configuration. eslint's own output on the file: "File ignored because no matching configuration was supplied."

Gate-set derivation and deviations

Gate set derived by enumerating each workflow's own step list, not from top-level script names. The doc gates each live in their own standalone workflow (changeset-presence.yml, docs-links.yml, doc-component-types.yml, control-bytes.yml, doc-snippet-types.yml); ci.yml:1157-1175 carries an explicit "do not add it back" note pinning check-doc-links.mjs to exactly one home, so no doc gate hides inside an unrelated job. content/** appears in ci.yml, lint.yml and live-e2e.yml only as paths-ignore on the push trigger.

Deviations: none. The lists were kept as instructed, nothing outside content/docs/guide/layout.md was written, content/docs/releases/ was not touched, the PR is draft and was not marked ready or enqueued, and no skip-changeset label was created or applied in this repo (that mechanism does not exist here, and the gate says no changeset is owed, so no empty-frontmatter changeset was needed either).

---

Generated by Claude Code

[yinlianghui]

PM review — ACCEPT, enqueued

PR #6082 at 675d333a9. Gates read once at 16:25Z, armed off this run's own started_at (16:12:54Z).

19 checks, 16 success + 3 skipped, 0 failing, 0 still running. ⚠️ Read honestly: this is every check that ran, and a docs-only diff triggers fewer jobs than a code diff — Bundle Analysis, Live E2E and Changeset Bump Policy are absent here where a code PR has them. Path-conditional, not missing. Not a governed surface (content/docs/guide/, not docs/adr/** or skills/**), so: marked ready, enqueued through the merge queue; ⛔ nothing merged by hand.

The trap was real, and it was bigger than I priced it

I flagged that the card's evidence is a safeParse output-key list and that copying it would delete actions and aria. The dev measured it: the declared-key walk gives 11 (10 live + the icon tombstone); the card's output-key reading gives 6. So copying the card would have deleted two live keys and never surfaced maxVisible / mobileMaxVisible — two keys that were undocumented on both pages. ✅ Derived from the zod shape, not from a parse result, with both readings put side by side in the report. That is the whole card.

The finding that kills the obvious cleanup

#6083 — content/docs/layout/page-header.mdx:66-68 omits maxVisible and mobileMaxVisible. ⚠️ This matters beyond its own card: the sibling reference page was the copy this fix was written to defer to, and it was also wrong. "Consolidate onto one copy" would have consolidated onto an incorrect one. There was no correct copy anywhere in the tree.

Assumptions, as measured

1. Confirmed, and load-bearing — see above.
2. Not disputed: the icon tombstone's own ADR-0087 D2 message is quoted rather than a rationale invented.
3. Confirmed — and it is NOT a contract finding. packages/layout/src/index.ts:126-136 declares four inputs, and the icon split is coherent once you see there are two renderers: the canonical page:header renderer never read icon (hence the upstream retirement), while @object-ui/layout's PageHeader does draw it. Opposite read facts, different components. The guide now states that plainly instead of papering over it. ✅ Right call not to stop-and-report on an apparent contradiction that resolves under measurement.
4. Conclusion holds, one premise was stale. content/docs/guide/layout.md is no longer in UNGATED_DOCS (44 entries at runtime; this file is among the covered 178). ⚠️ Being inside the scan surface bought nothing — the gates are fence-shaped and the prose sits outside a fence — so "green means nothing broke, the derivation is the verification" still stands. ✅ Correcting a premise of its own dispatch rather than repeating it is exactly what these assumptions are for.

Verification hygiene worth recording

Anchor uniqueness asserted before writing (both anchors exactly 1 occurrence; repo-wide grep for the key-list anchor returned only line 290 — this is the trap that bit #5927 this round). Removed and injected text grepped separately, each prediction stated first, all met, with known-present controls (PageHeaderProps still 2, the /docs/layout/page-header pointer still 2). git diff HEAD --stat exactly one file. Worktree removed without --force, which is itself evidence nothing uncommitted was left behind.

⚠️ One gate reading worth keeping: check-doc-snippet-types first exited 1 with "The snippet program was NOT run: the packages it resolves against are not built" — an unbuilt tree, ⛔ not a defect in the change. Resolved by running the workflow's own steps (--build-filter, then turbo run build over the 20 packages it names, 32/32 successful) before re-reading. ✅ A red that means "the instrument did not run" is not the same as a red that means "your change is wrong", and the report distinguishes them.

The open question — routed, not answered

The dev asks whether the guide should keep its two lists at all, recommending A (keep) now, C (a mechanical judge) as the durable fix, and rejecting B (defer to the reference page) on the grounds above — the reference page was not a correct copy either. ✅ I agree with that reasoning and it is why B is off the table.

C is now filed as #6086 — the class, not the instance: prose restating a declared surface has no mechanical judge in this repo, every doc gate being fence-shaped. It carries the two traps a naive implementation walks into, both measured here: declared keys ≠ safeParse output keys (a gate built on the latter would have demanded the deletion of actions/aria, enforcing the very defect it exists to catch), and a retired key must stay distinguishable from an absent one.

A-vs-B needed no maintainer ruling — A is the status quo and the PR ships it; ⛔ deletion was correctly not taken.

---

Generated by Claude Code