docs(guide): correct layout guide's PageHeaderProps key list and registration inputs

[yinlianghui]

Fixes#5923

One blockquote in content/docs/guide/layout.md carried two claims the sources contradict. Both are corrected in place; the lists are kept (deleting them is a docs-structure decision the card declined to take, so this PR does not take it either).

Claim 1 — the PageHeaderProps key list

Was: title / subtitle / icon / breadcrumb / actions / aria.

Measured against the installed @objectstack/spec17.2.0 (the version this branch's pnpm-lock.yaml resolves) by walking the zod shape's declared keys, not one parse result:

DECLARED KEY COUNT: 11
["title","subtitle","icon","breadcrumb","actions","recordChrome",
"showStar","showCopyId","maxVisible","mobileMaxVisible","aria"]
title optional -> union
subtitle optional -> union
icon optional -> never <-- ADR-0087 D2 tombstone
breadcrumb default -> boolean
actions optional -> array
recordChrome default -> boolean
showStar default -> boolean
showCopyId default -> boolean
maxVisible optional -> number
mobileMaxVisible optional -> number
aria optional -> object

So: 10 live keys plus the icon tombstone. The guide now names the 10.

Why the derivation method is load-bearing. The card measured this with safeParseoutput keys, which for {title, subtitle} are only ["title","subtitle","breadcrumb","recordChrome","showStar","showCopyId"] — an optional key with no default never appears in a parse result. Writing the guide from that list would have silently deleted actions and aria and never surfaced maxVisible / mobileMaxVisible. Feeding all ten live keys in at once returns all ten in the output, confirming the short list was an artifact of the input, not of the contract.

Claim 2 — the registration-inputs claim

Was: "page-header's registration declares onlytitle and subtitle as authorable inputs". Re-derived from current source — packages/layout/src/index.ts:126-136 declares four: title, subtitle, icon, actions.

The icon split is real, and is now documented rather than smoothed over

icon is simultaneously a retired key on the spec shape and a live declared registration input. That is genuinely the state of the tree, not a contract defect: they are different renderers. The registration's own comment says so — the canonical page:header renderer never read icon (hence the upstream ADR-0087 D2 retirement in objectstack#6946), while @object-ui/layout's <PageHeader> does draw it beside the title, which objectui#3829 ruled it keeps.

The blockquote now states that split and quotes the tombstone's own message (rather than inventing a rationale), so a reader holding icon in an existing schema finds out why the canonical node rejects it:

page:header property icon was removed in @objectstack/spec 17.0.0 (#6946, ADR-0087 D2) — no renderer ever read it … Delete the key.

Verification

Edit proven on disk by grepping removed and injected text separately, each with a known-present control; anchor uniqueness asserted before writing (both anchors: exactly 1 occurrence). git diff HEAD --stat shows only this one file.

Gate union re-run after the final commit, at 675d333a9:

gate	exit
node scripts/check-changeset-presence.mjs	0 — "No source of a released package changed in this range, so no changeset is owed."
node scripts/check-doc-links.mjs	0 — "Links are valid across 15 scan roots."
node scripts/check-doc-component-types.mjs	0 — "Every documented component type is registered."
node scripts/check-control-bytes.mjs	0 — 5026 tracked text files scanned
node scripts/check-doc-snippet-types.mjs	0 — 157/157 blocks judged, 0 failed

No changeset is owed, per the gate's own verdict line above.

What green does not mean here

check-doc-component-types reads type literals in code blocks and check-doc-snippet-types compiles ts/tsx fences (TS_FENCE_LANGUAGES = ["ts","tsx","typescript"]). Neither claim edited here lives in a code fence, so both gates are structurally blind to this change. Their green means this PR broke nothing — it is not evidence the new prose is true. The derivation above is the verification.

One correction to the card's account of that blindness: content/docs/guide/layout.md is no longer in check-doc-snippet-types' UNGATED_DOCS list. Read at runtime, the list holds 44 entries and this file is not among them — the run reports "178 covered, 44 ungated", and this file is inside the covered set. It is covered at document level and still fence-blind to prose, so the conclusion stands for a different reason than the card gave.

eslint does not lint this path. Per eslint.config.js, the only config block with rules is scoped files: ['**/*.{ts,tsx}'], so a .md file matches no configuration; eslint's own output on this file is "File ignored because no matching configuration was supplied."

---

Generated by Claude Code

[yinlianghui]

PM status — this PR is green and will not merge. Third auto-merge attempt abandoned; escalating rather than retrying.

domain:ui @ objectui execution seat, PM session session_01CSoz9uGhaaSgiq3hshtN7L.

⛔ I am not enabling auto-merge a fourth time. Three attempts have now produced the same outcome, and repeating an action that has failed three times is not a diagnosis. Recording the measurements instead, including one hypothesis of mine that is now falsified — so the next reader does not re-derive it.

What is established

The PR is green. At head 34a132ff466de4a3d8aa122441020195ee59477c: 22 check runs, 22 completed, 19 success + 3 skipped, zero failures, zero pending. No reviews requested, none submitted, none blocking (get_reviews → []).

It reports 22 contexts where a code PR reports 25. Measured against three PRs enqueued from this seat tonight — #6209, #6211, #6225 — each of which reports exactly 25. The three this PR does not produce are:

missing context	why it does not run here
Bundle Analysis	performance-budget.yml triggers on paths: packages/**, apps/console/**, pnpm-lock.yaml. This PR changes one .md and matches none.
Live E2E (informational)	live-e2e.yml carries paths-ignore: '**/*.md', 'content/**', …. This PR's single file, content/docs/guide/layout.md, is excluded twice over.
Changeset Bump Policy	changeset-guard.yml triggers on paths: .changeset/**. This PR correctly owes no changeset, so the workflow never starts.

All three absences are correct behaviour, not defects. Each workflow is doing exactly what its trigger says.

❌ The hypothesis this suggests is FALSE — stated so it is not tried again

The obvious reading is: one of those three is a required status check, a required check that never reports is neither red nor green, so a docs-only PR blocks forever. That reading is wrong here, and the repo already measured why. .github/workflows/cross-repo-issue-closer.yml records it in its own header:

the main ruleset (11776024) carries deletion, non_fast_forward, merge_queue and pull_request rules and NO required_status_checks rule at all, so no context is required on this repository today

With no required-status-checks rule, a path-filtered absent context cannot be what is holding this PR. live-e2e.yml's own header independently forbids requiring it ("INFORMATIONAL, NON-REQUIRED lane … Do NOT add this job to required checks"). So the 22-vs-25 delta is a real and previously unrecorded measurement, but it is not the cause. I had it as my leading hypothesis and it does not survive contact with the ruleset.

What that leaves, and why I am stopping here

The ruleset carries merge_queue and pull_request rules. Which of those is refusing this PR — and why it refuses this one while #6053, #6125, #6202, #6203 and a dozen others merged through the same queue tonight — is not derivable from the endpoints available to this seat. Reading the ruleset and merge-queue configuration directly is a repository-settings read, and settings are the maintainer's, not the PM's.

⚠️ Note also that get_status on this head returns state: pending, total_count: 0, statuses: [] — no commit statuses at all, only check runs. That was my earlier lead and I am recording it as untested, not as a finding: with no required_status_checks rule it should be inert, but I have not proven it is.

Prior attempts, so the history is not lost

1. Auto-merge enabled → no merge.
2. Auto-merge enabled → no merge. I diagnosed it as three new gates missing from a 19-check commit.
3. update_pull_request_branch forced a fresh run → came back 22/22 green → auto-merge enabled → no merge. That result is what falsified attempt 2's diagnosis: I had read "22/22 green" as refuting the missing-gates theory, when in fact 22/22 green only says every present check passed and says nothing about contexts that never reported. Both readings were mine and both were wrong in different directions.

Ask

This needs a maintainer with repository-settings read to say which ruleset rule is refusing #6082. The PR content itself is not in question — it is a 12-line, one-file docs correction, fully verified in the body above, green on every gate that runs on it.

Until then #6082 stays open and #5923 stays pm:dispatched. Adding to the maintainer escalation list as item ⑯.

---

Generated by Claude Code

[yinlianghui]

✅ Root cause found, with a control — and it is not a settings problem after all

domain:ui @ objectui execution seat, PM session session_01CSoz9uGhaaSgiq3hshtN7L. Correcting my own escalation from comment 5404434910, which asked for a maintainer with repository-settings read. That is no longer needed.

The cause: the old head commit carried NO commit status at all

head	get_status
34a132ff466… (old, pushed 01:36Z)	state: pending, total_count: 0, statuses: []
b1a12278b92… (new, after a branch update at ~05:01Z)	state: success, total_count: 1 — Vercel / "Canceled by Ignored Build Step"

A combined commit status with zero statuses reports pending, not success. It is neither red nor green — it never resolves. That is what auto-merge was waiting on across all three attempts, and it is why 22/22 green check runs made no difference: check runs and commit statuses are different things, and the missing one was a status.

The control — this is what makes it a diagnosis rather than another guess

My first instinct was "docs-only PRs don't get a Vercel status." That is false, and I tested it before acting:

• docs(layout): add maxVisible and mobileMaxVisible to page-header's PageHeaderProps key list #6257 — content/docs/layout/page-header.mdx only, exactlydocs(guide): correct layout guide's PageHeaderProps key list and registration inputs #6082's file shape → has a Vercel status, success.
• fix(examples): correct the invented keys the live SchemaExample fixtures teach #6248 — examples/** only → has one.
• fix(i18n): the provider-less not-ready t now interpolates its inline defaultValue (#6219) #6255 — packages/** → has one.
• docs(guide): correct layout guide's PageHeaderProps key list and registration inputs #6082 old head → none.

So the file shape does not explain it. Vercel simply never reported on that one commit — the integration has been posting normally on every commit since at least 04:02Z today, and 34a132ff4 predates that by two and a half hours. A missed webhook, or the integration being reconnected in between, fits; ⚠️which of those it was, I have not established and am not claiming.

What I did

update_pull_request_branch — a standard operation, no history rewrite, no auto-merge change. The new head immediately received a Vercel status. Checks are re-running on b1a12278b now.

⛔ I have still not enabled auto-merge a fourth time, and I will not do so blindly. I will gate-read the new run once, past the 11-minute mark off its own started_at, and land it only if every check is green — the same discipline as any other PR. The earlier "do not retry" rule was correct while the cause was unknown; it was a rule about acting without a diagnosis, not about this PR being untouchable.

My two earlier readings, both wrong, recorded so the pattern is visible

1. "Three new gates don't exist on its stale commit." — Falsified when a forced fresh run came back 22/22 green and it still would not merge.
2. "A path-filtered required check never reports, so it blocks forever." — Falsified by the repo's own measurement in .github/workflows/cross-repo-issue-closer.yml: the main ruleset carries no required_status_checks rule at all. The 22-vs-25 check-count delta I measured was real and correctly explained by path filters — but it was not the cause, and I said so at the time.

The through-line: I twice reasoned from a measured difference to a cause without a control. The third attempt found the difference and tested it against three PRs of the same and different shapes. The control is what turned it into an answer.

Consequence for the lane

⚠️Any PR whose head commit predates the Vercel integration posting normally may be silently unmergeable in the same way — green checks, no red, no diagnosis, just permanent pending. The cheap test is get_status: total_count: 0 means the commit is unmergeable regardless of how green its check runs are. A branch update mints a fresh head and fixes it.

Adding that to this seat's gate-read discipline: on a PR that is fully green but will not merge, read get_statusbefore re-enabling auto-merge, and compare total_count against a PR that merged.

---

Generated by Claude Code

[yinlianghui]

❌ Retracting comment 5405504393 — the missing commit status was NOT the cause either. Third diagnosis falsified.

domain:ui @ objectui execution seat, PM session session_01CSoz9uGhaaSgiq3hshtN7L.

I said the root cause was found. It was not. Correcting that before it misleads anyone.

The falsification, with the control I set in advance

I wrote the falsification condition down before testing it: "if #6255/#6257 merged and #6082 alone did not, that is the falsification."

PR	enqueued	commit status on head	merged
#6255	~05:19Z	Vercel / success	✅ de570cca9
#6257	~05:21Z	Vercel / success	✅ efa630799
#6082	~05:19Z	Vercel / success (on b1a12278b, since 05:01Z)	❌ still open

So the status is present now, its checks came back 24/24 green, two PRs enqueued in the same minute have merged, and this one has not. The missing commit status was a real anomaly and a real difference — but it was not the cause.

Three hypotheses, three falsifications, one repeated error

1. "Three new gates don't exist on its stale commit." → falsified: a forced fresh run came back 22/22 green and it still would not merge.
2. "A path-filtered required check never reports, so it blocks forever." → falsified: the repo's own header in .github/workflows/cross-repo-issue-closer.yml records that the main ruleset carries no required_status_checks rule at all.
3. "The head commit carries no commit status, so the combined status never resolves." → falsified above.

⚠️The error is the same all three times, and it is mine: I found a real difference between #6082 and PRs that merge, and treated the difference as the cause. On the third attempt I did use controls — they correctly ruled out "docs-only PRs get no Vercel status" — but I then stopped at the first surviving hypothesis instead of testing whether fixing it actually changed the outcome. A control that rules out an alternative is not a test that your own explanation is right. The only test that mattered was the one I have just run: fix the difference, and see whether it merges. It did not.

What is now established, and what is not

Established: it is green (24/24), it has a commit status, it has no reviews blocking, it is not a required-status-check problem, and it is not a file-shape problem. Two PRs enqueued at the same moment with the same auto-merge settings merged past it.

Not established: why it is refused. I have no fourth hypothesis I can test from this seat, and I am not going to invent one.

⛔ Auto-merge has now been enabled four times and I am not enabling it a fifth. Whatever is refusing this PR is not something repeated attempts reach.

Ask — unchanged from the original escalation, and now better evidenced

This needs someone with repository-settings read: the main ruleset's merge_queue and pull_request rules, and the merge queue's own configuration. The PR content is not in question — a 12-line, one-file docs correction, independently corroborated: PR #6257 re-derived the same PageHeaderProps key list from scratch and got zero delta — same 11 keys, same order, same icon tombstone, same per-key annotations. #6257 merged; this did not.

⚠️If it stays refused, the cheap unblock is to abandon this PR and re-open the same one-file change on a fresh branch. That is not a diagnosis and I am not doing it silently — it discards the history, and the underlying refusal would still be unexplained and still able to catch the next PR. Maintainer's call.

Restoring this to the maintainer escalation list as item ⑯.

---

Generated by Claude Code

[os-litant]

Auto-merge disabled — making the state honest. ⛔ This is NOT a fifth diagnosis attempt.

domain:ui @ objectui execution seat, PM session session_01Mn4BZ5AVDM81pvfij1WwM9 (identity os-litant), on a maintainer forced-handover from session_01CSoz9uGhaaSgiq3hshtN7L.

What I changed and why

Auto-merge was on for the fourth time and had never fired. The PR therefore looked like "queued, merging shortly" while it was actually "escalated, waiting on a human." Those two states are indistinguishable at a glance, and this lane has spent a night on exactly that class of failure.

⚠️ Auto-merge left on was also a loaded gun: if whatever blocks it ever cleared, this would merge without the human judgement it was escalated for.

✅ Disabling it costs nothing and is one click to restore for whoever resolves the underlying cause.

State, recorded once so nobody re-measures it

reading	value
checks	24 total — 21 success, 3 skipped, zero failures
all runs	completed
mergeable_state	clean
draft	no
merged	no

⛔ Every leg that PM-side judgement can read says "mergeable". It does not merge. That is the whole finding, and it is not resolvable from the PR surface.

⛔ Why I am stopping here

The previous seat raised three diagnoses on this PR and all three were falsified. Its own account of the error is worth preserving, because the shape recurred three times in one night:

Each round found a real difference between this PR and a mergeable one, and treated the difference as the cause. The third round even ran a correct control — properly excluding "docs-only produces no Vercel status" — then stopped at the first surviving hypothesis without running the only decisive test: remove the suspected difference and see whether it merges. It was removed. It did not merge.

⭐ Excluding an alternative explanation is not verifying your own. A surviving hypothesis is not a confirmed one. So I am not opening a fourth candidate cause, and ⛔ not re-enabling auto-merge to observe it again — that is the experiment that has already run four times.

One lead for whoever has repository-settings access — ⚠️ offered untested

⛔ I am explicitly not claiming this is the cause, and I have not tested it. It is a pointer to make a settings check fast, not diagnosis attempt five.

This repo's merge queue matches its required set by job / check-run name, and two documented ways that silently hangs a queue are both visible in this PR's own check list:

• Test (coverage shard ${{ matrix.shard }}/4) appears as a literal, unexpanded matrix name. An unexpanded name is a skipped placeholder, not a real check context — a required entry naming it can never be satisfied.
• Test (coverage) and that shard row both report skipped. A job gated if: github.event_name == 'push' never reports on a merge_group build, and listing such a job as required hangs the queue with no error surfaced anywhere on the PR.

⇒ The check worth doing is: read the branch ruleset's required set and compare it name-by-name against the checks that actually report on a merge_group build. That comparison needs settings read access, which no agent in this fleet has — which is exactly why this is escalated rather than assigned.

Standing

⛔ Do not re-enable auto-merge on this PR until that comparison has been made. The content itself is not in question: the docs correction is sound, its derivation method is documented in the PR body, and its gates are green.

---

Generated by Claude Code

[os-support-ai]

The predecessor's untested lead is factually confirmed — and the remaining half needs an access this seat provably does not have

domain:ui @ objectui execution seat, PM session session_011SfZeFWrhGLHmfq61xbz4q (os-support-ai). Seat taken 11:14Z; this PR and its card #5923 were inherited, assigned to os-litant, which is now a dead identity — I have reassigned both to myself so they are owned rather than orphaned.

⛔ This is NOT a fifth diagnosis. The outgoing seat left exactly one lead marked untested, and recorded three falsified diagnoses with an explicit instruction not to open another. Confirming the factual half of an already-recorded lead costs one API call, so I did that and nothing else.

What I read — the full 24-run check list on the head commit

No run failed. 21 succeeded, 3 are skipped. The lead said this PR's check list shows an unexpanded matrix placeholder plus skipped coverage rows. It does — verbatim:

check run	conclusion
Test (coverage shard ${{ matrix.shard }}/4)	skipped
Test (coverage)	skipped
dependabot	skipped
Test (shard 1/4) … Test (shard 4/4)	✅ all success
the other 17	✅ success

⭐ The placeholder is literally the job's reported name — ${{ matrix.shard }} never interpolated, because a skipped matrix job is reported under its un-expanded template name. Note also that the four shards that actually ran are named Test (shard N/4), a different pattern from the skipped Test (coverage shard …/4).

That is one of the two documented ways a required entry can never be satisfied: required checks match by job NAME, so if the required set names the expanded coverage shards (Test (coverage shard 1/4) … 4/4), those names are never reported on this PR — not as failure, not as success, simply absent. A required check that never reports blocks the merge permanently while every check that is present reads green. That is exactly this PR's presentation.

⛔ What I have NOT established, stated plainly

This is a hypothesis with its factual half measured, not a verified cause. Confirming that the placeholder and the skipped rows exist does not confirm they are what blocks the merge — ⭐ excluding an alternative explanation is not verifying your own, which is the error shape that cost this lane the most in the previous shift and cost this very PR three falsified diagnoses.

To close it, someone has to read the repository's required-status-check list and compare it name-by-name against the 24 reported above. This seat cannot: every repo-scoped REST path returns 403 from this container (measured across 6 endpoint forms and both tokens; /rate_limit and /user return 200, so the refusal is path-scoped, not credential-scoped). ⛔ Not an org-App or account problem — add_repo with push access returns already_present.

⚠️ It is also worth disconfirming rather than assuming: if the required set turns out to name only the plain Test (shard N/4) jobs, this lead is dead too and the cause is elsewhere. Either answer is progress; ⛔ do not read the confirmation above as a conclusion.

Ask — one settings read, and the disposition either way

For whoever has repository-settings access: open Settings → Branches → the main protection rule and compare its required checks against the 24 names above.

• If it requires a coverage-shard name that is never reported ⇒ the fix is a settings change (or a workflow change so the job reports under the required name), ⛔ not a change to this PR's diff — this PR is a docs correction and has nothing to do with coverage sharding.
• If it does not ⇒ say so on this thread and the lead is closed; the next seat should not re-run it.

Meanwhile: auto-merge stays disabled (the outgoing seat disabled it deliberately so the PR stops reading as "merging shortly" when it is actually escalated — that was the right call and I am not reverting it). The PR stays open and green. ⛔ I am not pushing an empty commit, closing-and-reopening, or otherwise kicking CI: the checks are not failing, so there is nothing to re-run, and those are prohibited moves regardless.

Carried into this round's report as an item needing a human.

---

Generated by Claude Code

[os-support-ai]

⛔ RETRACTED — the lead I "confirmed" 40 minutes ago is dead. Do not spend a settings read on it.

domain:ui @ objectui execution seat, PM session session_011SfZeFWrhGLHmfq61xbz4q (os-support-ai). Correcting my own comment above.

The control I failed to run, and the answer

I confirmed that Test (coverage shard ${{ matrix.shard }}/4) appears as a literal, unexpanded job name in skipped state on this PR, and reasoned that a required check by that name could never be satisfied. The control I never ran: does that same row appear on PRs that merge perfectly well?

It does.

PR	state	Test (coverage shard ${{ matrix.shard }}/4)	Test (coverage)
#5970	✅ MERGED today (090927f4f)	skipped	skipped
#6304	open, healthy	skipped	skipped
#6082 (this one)	⛔ stuck	skipped	skipped

⇒ The unexpanded placeholder and the skipped coverage rows are ubiquitous and harmless. A PR merged into main today carrying the identical pair. They cannot be what blocks this PR, and the required-checks hypothesis built on them is falsified.

⛔ Withdrawing the ask

My previous comment asked whoever has repository-settings access to compare the required-check list against this PR's 24 rows. That is no longer worth anyone's time — #5970 is the counter-example, and it is free to read. ⚠️ I had already escalated this to the maintainer as "one click"; that escalation is retracted here so the correction reaches the same place the ask did.

The error, named — because it is the one this lane keeps paying for

I wrote, in the very comment I am now retracting, "excluding an alternative explanation is not verifying your own", and then did exactly the thing one line further on: I verified that the placeholder exists and let that stand in for verifying it matters. ⭐ A finding about a check row is only a reading once the same row has been probed on a PR that merged — the known-present control. That control was one API call away and I did not make it until a routine gate read on an unrelated PR put the identical row in front of me by accident.

This is now the fourth falsified diagnosis on this PR. Three were the predecessor's; this one is mine.

Where that leaves it — ⛔ and I am not opening a fifth

Standing instruction on this PR is that a fifth diagnosis is not wanted, and after this it is doubly warranted. What is still true and measured: 24 check runs, none failed, mergeable_state: clean, auto-merge deliberately disabled by the predecessor so the state stops reading as "merging shortly".

Two paths, both the maintainer's call — ⛔ I am taking neither unilaterally:

1. Merge it by hand. Every check is green and the diff is a docs correction. If the button works, the question was never worth answering.
2. Re-raise the same diff on a fresh branch and PR, then close this one. A cheap empirical test that routes around an unexplainable GitHub state. ⚠️ To be explicit about what this is not: it is not close-and-reopen to kick CI, and not an empty commit — both prohibited, and neither would apply here since nothing is failing. If a fresh PR sticks the same way, that is genuinely new information; if it merges, the cost was one branch.

⚠️ ⛔ Do not read "all 24 green" as "ready to merge". That reading is what this PR has falsified four times now. Whatever is holding it is not visible in the check list.

---

Generated by Claude Code