docs(core): app-schema's "Global Actions" snippet imports AppMenuItem, not the overlay MenuItem

[os-sam]

Fixes#6692

Executes the 2026-08-29 ruling on that card: option A — the docs snippet references the type AppAction.items actually resolves to. The ruling's census rider is recorded below, and it fired: option B is filed as #6854.

Diff is two files: content/docs/core/app-schema.mdx and a changeset. packages/types/** is read-only in this card (route B's surface, and held by PR #6826).

The defect

content/docs/core/app-schema.mdx's "Global Actions" section imported the bare name:

importtype{MenuItem}from'@object-ui/types';interfaceAppAction{items?: MenuItem[];}

That resolves to the overlay union — packages/types/src/overlay.ts:347, re-exported bare at packages/types/src/index.ts:255, the type behind ui:dropdown-menu / ui:context-menu / ui:menubar. But the real AppAction.items (packages/types/src/app.ts:728) is declared insideapp.ts, so it resolves to that file's own legacy navigation-item MenuItem (app.ts:461). The barrel re-exports that one renamed, as AppMenuItem (index.ts:59), precisely to avoid this collision — every line number in the finding re-derived at 26896c6 and confirmed.

The two are mutually incompatible, not merely differently named. The overlay union declares type?: never on both arms (dividers became { separator: true } in #6523), so the { "type": "separator" } item documented a few paragraphs earlier on this same page is refused by the type the snippet named.

⚠️ The suggested fix in the finding does not work

Both the original card and the ruling offer "MenuItem as AppMenuItem" as an alternative spelling. It does not fix this, and it fails in the worst way — it looks repaired and compiles:

importtype{MenuItemasAppMenuItem}from'@object-ui/types';// still the OVERLAY type

AppMenuItem is already the barrel's export name for the app.ts type. Importing MenuItem and locally aliasing it to AppMenuItem imports the overlay export and renames it, leaving the defect exactly in place under a name that reads correct. The only correct import is import type { AppMenuItem }, which is what this PR uses. Verified by type probe, below.

Census rider (required by the ruling) — result: MIXED, so #6854 is filed

The consumer named in the card is the wrong file.packages/components/src/renderers/navigation/header-bar.tsx never sees AppAction; it consumes HeaderBarSchema (packages/types/src/navigation.ts:57), whose actions?: SchemaNode[] is unrelated, and it never reads .items.

The real and only consumer is packages/runner/src/LayoutRenderer.tsx:301-315:

Field read	Line	In app.tsMenuItem (what items IS)	In overlay MenuItem
item.type === 'separator'	302	yes	no — type?: never
item.label	307	yes	yes
(item as any).onClick	304	no	yes
(item as any).shortcut	309	no	yes

Never read: path, href, badge, hidden, children.

So the renderer branches on the legacy type spelling and then reaches two overlay-shaped fields through as any, past its own declared type. That is the rider's trigger condition, so option B is filed as #6854 with this census as its evidence — not decided here, and no part of it is attempted in this PR.

This does not undermine option A: both declarations agree on what items is today (TS app.ts:728; zod mirror app.zod.ts:192, using the "Legacy MenuItem Schema" at app.zod.ts:167), so documenting AppMenuItem is documenting the shipped contract either way. If #6854 later re-types the field, this snippet changes with it.

⛔ What does NOT demonstrate this change is correct

A green CI run is not evidence here, and neither is check:doc-snippets passing. The snippet is a bare type reference (items?: MenuItem[]), never an object literal, so it compiles against eitherMenuItem. No gate goes red-to-green on this fix.

Measured rather than assumed — ablation at 4b65e8d, reverting the file to its pre-fix bytes and re-running the gate:

MUT hash : 3a8d64a (differs from HEAD blob: YES)
MUT fixed-import count : 0 (expect 0)
MUT buggy-import count : 1 (expect 1)
MUTATION CONFIRMED ON DISK
MUTATED-LEG GATE EXIT=0
Semantic phase: 267 of 267 block(s) judged, 0 failed.
Every covered documentation snippet compiles against the built types.
RESTORE CONFIRMED: hash matches HEAD blob AND git diff HEAD is empty

Identical verdict on the buggy tree. The gate is structurally blind to this defect.

What DOES demonstrate it

A type probe compiled against the builtpackages/types/dist/index.d.ts, using @ts-expect-error so each assertion fails if the expected error does not occur. Exit 0 — every assertion held:

1. AppMenuItem accepts { type: 'separator' } and the full legacy shape (type/label/path/href/badge/hidden) — it is app.ts's type.
2. The bare MenuItem the docs imported rejects{ type: 'separator' } and rejects path.
3. MenuItem as AppMenuItem still rejects { type: 'separator' } — proving that spelling stays the overlay type.
4. AppMenuItem has no onClick — the field LayoutRenderer casts past.

The probe was a scratch file, deleted before commit; it is reproducible from the four assertions above.

Gates

Run at 4b65e8d (the final commit), exit codes captured before any pipe; verdict lines quoted as each gate printed them:

Gate	Result
check:doc-snippets	exit 0 — "Every covered documentation snippet compiles against the built types." 267/267 blocks judged, 0 failed; controls (resolution / sentinel / positive / undeclared) all held. Built its declared 21-package closure first.
check:doc-fences	exit 0 — "every TypeScript block in 223 document(s) is fenced ts/tsx/typescript"
check:doc-types	exit 0
check:control-bytes	exit 0 — "scanned 5647 tracked text file(s); skipped 85 binary"
check:docs-route-closure	exit 0
check-changeset-presence	exit 0 — "No source of a released package changed in this range, so no changeset is owed."
check-changeset-no-major	exit 0 — "No changeset declares a major bump."
check-changeset-overwrite	exit 0 — "1 changeset(s) added, 0 modified, 0 deleted."

app-schema.mdx is confirmed covered by check:doc-snippets: coverage is every doc under content/docs minus the script's UNGATED_DOCS ledger, and this page has no ledger entry.

The changeset carries empty frontmatter — the repo's declaration form for a change that publishes nothing, since the presence gate itself reports nothing owed for a docs-only diff.

---

Generated by Claude Code

[os-sam]

Fixes#6692

Executes the 2026-08-29 ruling on that card: option A — the docs snippet references the type AppAction.items actually resolves to. The ruling's census rider is recorded below, and it fired: option B is filed as #6854.

Diff is two files: content/docs/core/app-schema.mdx and a changeset. packages/types/** is read-only in this card (route B's surface, and held by PR #6826).

The defect

content/docs/core/app-schema.mdx's "Global Actions" section imported the bare name:

importtype{MenuItem}from'@object-ui/types';interfaceAppAction{items?: MenuItem[];}

That resolves to the overlay union — packages/types/src/overlay.ts:347, re-exported bare at packages/types/src/index.ts:255, the type behind ui:dropdown-menu / ui:context-menu / ui:menubar. But the real AppAction.items (packages/types/src/app.ts:728) is declared insideapp.ts, so it resolves to that file's own legacy navigation-item MenuItem (app.ts:461). The barrel re-exports that one renamed, as AppMenuItem (index.ts:59), precisely to avoid this collision — every line number in the finding re-derived at 26896c6 and confirmed.

The two are mutually incompatible, not merely differently named. The overlay union declares type?: never on both arms (dividers became { separator: true } in #6523), so the { "type": "separator" } item documented a few paragraphs earlier on this same page is refused by the type the snippet named.

⚠️ The suggested fix in the finding does not work

Both the original card and the ruling offer "MenuItem as AppMenuItem" as an alternative spelling. It does not fix this, and it fails in the worst way — it looks repaired and compiles:

importtype{MenuItemasAppMenuItem}from'@object-ui/types';// still the OVERLAY type

AppMenuItem is already the barrel's export name for the app.ts type. Importing MenuItem and locally aliasing it to AppMenuItem imports the overlay export and renames it, leaving the defect exactly in place under a name that reads correct. The only correct import is import type { AppMenuItem }, which is what this PR uses. Verified by type probe, below.

Census rider (required by the ruling) — result: MIXED, so #6854 is filed

The consumer named in the card is the wrong file.packages/components/src/renderers/navigation/header-bar.tsx never sees AppAction; it consumes HeaderBarSchema (packages/types/src/navigation.ts:57), whose actions?: SchemaNode[] is unrelated, and it never reads .items.

The real and only consumer is packages/runner/src/LayoutRenderer.tsx:301-315:

Field read	Line	In app.tsMenuItem (what items IS)	In overlay MenuItem
item.type === 'separator'	302	yes	no — type?: never
item.label	307	yes	yes
(item as any).onClick	304	no	yes
(item as any).shortcut	309	no	yes

Never read: path, href, badge, hidden, children.

So the renderer branches on the legacy type spelling and then reaches two overlay-shaped fields through as any, past its own declared type. That is the rider's trigger condition, so option B is filed as #6854 with this census as its evidence — not decided here, and no part of it is attempted in this PR.

This does not undermine option A: both declarations agree on what items is today (TS app.ts:728; zod mirror app.zod.ts:192, using the "Legacy MenuItem Schema" at app.zod.ts:167), so documenting AppMenuItem is documenting the shipped contract either way. If #6854 later re-types the field, this snippet changes with it.

⛔ What does NOT demonstrate this change is correct

A green CI run is not evidence here, and neither is check:doc-snippets passing. The snippet is a bare type reference (items?: MenuItem[]), never an object literal, so it compiles against eitherMenuItem. No gate goes red-to-green on this fix.

Measured rather than assumed — ablation at 4b65e8d, reverting the file to its pre-fix bytes and re-running the gate:

MUT hash : 3a8d64a (differs from HEAD blob: YES)
MUT fixed-import count : 0 (expect 0)
MUT buggy-import count : 1 (expect 1)
MUTATION CONFIRMED ON DISK
MUTATED-LEG GATE EXIT=0
Semantic phase: 267 of 267 block(s) judged, 0 failed.
Every covered documentation snippet compiles against the built types.
RESTORE CONFIRMED: hash matches HEAD blob AND git diff HEAD is empty

Identical verdict on the buggy tree. The gate is structurally blind to this defect.

What DOES demonstrate it

A type probe compiled against the builtpackages/types/dist/index.d.ts, using @ts-expect-error so each assertion fails if the expected error does not occur. Exit 0 — every assertion held:

1. AppMenuItem accepts { type: 'separator' } and the full legacy shape (type/label/path/href/badge/hidden) — it is app.ts's type.
2. The bare MenuItem the docs imported rejects{ type: 'separator' } and rejects path.
3. MenuItem as AppMenuItem still rejects { type: 'separator' } — proving that spelling stays the overlay type.
4. AppMenuItem has no onClick — the field LayoutRenderer casts past.

The probe was a scratch file, deleted before commit; it is reproducible from the four assertions above.

Gates

Run at 4b65e8d (the final commit), exit codes captured before any pipe; verdict lines quoted as each gate printed them:

Gate	Result
check:doc-snippets	exit 0 — "Every covered documentation snippet compiles against the built types." 267/267 blocks judged, 0 failed; controls (resolution / sentinel / positive / undeclared) all held. Built its declared 21-package closure first.
check:doc-fences	exit 0 — "every TypeScript block in 223 document(s) is fenced ts/tsx/typescript"
check:doc-types	exit 0
check:control-bytes	exit 0 — "scanned 5647 tracked text file(s); skipped 85 binary"
check:docs-route-closure	exit 0
check-changeset-presence	exit 0 — "No source of a released package changed in this range, so no changeset is owed."
check-changeset-no-major	exit 0 — "No changeset declares a major bump."
check-changeset-overwrite	exit 0 — "1 changeset(s) added, 0 modified, 0 deleted."

app-schema.mdx is confirmed covered by check:doc-snippets: coverage is every doc under content/docs minus the script's UNGATED_DOCS ledger, and this page has no ledger entry.

The changeset carries empty frontmatter — the repo's declaration form for a change that publishes nothing, since the presence gate itself reports nothing owed for a docs-only diff.

---

Generated by Claude Code

[os-sam]

Fixes#6692

Executes the 2026-08-29 ruling on that card: option A — the docs snippet references the type AppAction.items actually resolves to. The ruling's census rider is recorded below, and it fired: option B is filed as #6854.

Diff is two files: content/docs/core/app-schema.mdx and a changeset. packages/types/** is read-only in this card (route B's surface, and held by PR #6826).

The defect

content/docs/core/app-schema.mdx's "Global Actions" section imported the bare name:

importtype{MenuItem}from'@object-ui/types';interfaceAppAction{items?: MenuItem[];}

That resolves to the overlay union — packages/types/src/overlay.ts:347, re-exported bare at packages/types/src/index.ts:255, the type behind ui:dropdown-menu / ui:context-menu / ui:menubar. But the real AppAction.items (packages/types/src/app.ts:728) is declared insideapp.ts, so it resolves to that file's own legacy navigation-item MenuItem (app.ts:461). The barrel re-exports that one renamed, as AppMenuItem (index.ts:59), precisely to avoid this collision — every line number in the finding re-derived at 26896c6 and confirmed.

The two are mutually incompatible, not merely differently named. The overlay union declares type?: never on both arms (dividers became { separator: true } in #6523), so the { "type": "separator" } item documented a few paragraphs earlier on this same page is refused by the type the snippet named.

⚠️ The suggested fix in the finding does not work

Both the original card and the ruling offer "MenuItem as AppMenuItem" as an alternative spelling. It does not fix this, and it fails in the worst way — it looks repaired and compiles:

importtype{MenuItemasAppMenuItem}from'@object-ui/types';// still the OVERLAY type

AppMenuItem is already the barrel's export name for the app.ts type. Importing MenuItem and locally aliasing it to AppMenuItem imports the overlay export and renames it, leaving the defect exactly in place under a name that reads correct. The only correct import is import type { AppMenuItem }, which is what this PR uses. Verified by type probe, below.

Census rider (required by the ruling) — result: MIXED, so #6854 is filed

The consumer named in the card is the wrong file.packages/components/src/renderers/navigation/header-bar.tsx never sees AppAction; it consumes HeaderBarSchema (packages/types/src/navigation.ts:57), whose actions?: SchemaNode[] is unrelated, and it never reads .items.

The real and only consumer is packages/runner/src/LayoutRenderer.tsx:301-315:

Field read	Line	In app.tsMenuItem (what items IS)	In overlay MenuItem
item.type === 'separator'	302	yes	no — type?: never
item.label	307	yes	yes
(item as any).onClick	304	no	yes
(item as any).shortcut	309	no	yes

Never read: path, href, badge, hidden, children.

So the renderer branches on the legacy type spelling and then reaches two overlay-shaped fields through as any, past its own declared type. That is the rider's trigger condition, so option B is filed as #6854 with this census as its evidence — not decided here, and no part of it is attempted in this PR.

This does not undermine option A: both declarations agree on what items is today (TS app.ts:728; zod mirror app.zod.ts:192, using the "Legacy MenuItem Schema" at app.zod.ts:167), so documenting AppMenuItem is documenting the shipped contract either way. If #6854 later re-types the field, this snippet changes with it.

⛔ What does NOT demonstrate this change is correct

A green CI run is not evidence here, and neither is check:doc-snippets passing. The snippet is a bare type reference (items?: MenuItem[]), never an object literal, so it compiles against eitherMenuItem. No gate goes red-to-green on this fix.

Measured rather than assumed — ablation at 4b65e8d, reverting the file to its pre-fix bytes and re-running the gate:

MUT hash : 3a8d64a (differs from HEAD blob: YES)
MUT fixed-import count : 0 (expect 0)
MUT buggy-import count : 1 (expect 1)
MUTATION CONFIRMED ON DISK
MUTATED-LEG GATE EXIT=0
Semantic phase: 267 of 267 block(s) judged, 0 failed.
Every covered documentation snippet compiles against the built types.
RESTORE CONFIRMED: hash matches HEAD blob AND git diff HEAD is empty

Identical verdict on the buggy tree. The gate is structurally blind to this defect.

What DOES demonstrate it

A type probe compiled against the builtpackages/types/dist/index.d.ts, using @ts-expect-error so each assertion fails if the expected error does not occur. Exit 0 — every assertion held:

1. AppMenuItem accepts { type: 'separator' } and the full legacy shape (type/label/path/href/badge/hidden) — it is app.ts's type.
2. The bare MenuItem the docs imported rejects{ type: 'separator' } and rejects path.
3. MenuItem as AppMenuItem still rejects { type: 'separator' } — proving that spelling stays the overlay type.
4. AppMenuItem has no onClick — the field LayoutRenderer casts past.

The probe was a scratch file, deleted before commit; it is reproducible from the four assertions above.

Gates

Run at 4b65e8d (the final commit), exit codes captured before any pipe; verdict lines quoted as each gate printed them:

Gate	Result
check:doc-snippets	exit 0 — "Every covered documentation snippet compiles against the built types." 267/267 blocks judged, 0 failed; controls (resolution / sentinel / positive / undeclared) all held. Built its declared 21-package closure first.
check:doc-fences	exit 0 — "every TypeScript block in 223 document(s) is fenced ts/tsx/typescript"
check:doc-types	exit 0
check:control-bytes	exit 0 — "scanned 5647 tracked text file(s); skipped 85 binary"
check:docs-route-closure	exit 0
check-changeset-presence	exit 0 — "No source of a released package changed in this range, so no changeset is owed."
check-changeset-no-major	exit 0 — "No changeset declares a major bump."
check-changeset-overwrite	exit 0 — "1 changeset(s) added, 0 modified, 0 deleted."

app-schema.mdx is confirmed covered by check:doc-snippets: coverage is every doc under content/docs minus the script's UNGATED_DOCS ledger, and this page has no ledger entry.

The changeset carries empty frontmatter — the repo's declaration form for a change that publishes nothing, since the presence gate itself reports nothing owed for a docs-only diff.

---

Generated by Claude Code

[os-sam]

Fixes#6692

Executes the 2026-08-29 ruling on that card: option A — the docs snippet references the type AppAction.items actually resolves to. The ruling's census rider is recorded below, and it fired: option B is filed as #6854.

Diff is two files: content/docs/core/app-schema.mdx and a changeset. packages/types/** is read-only in this card (route B's surface, and held by PR #6826).

The defect

content/docs/core/app-schema.mdx's "Global Actions" section imported the bare name:

importtype{MenuItem}from'@object-ui/types';interfaceAppAction{items?: MenuItem[];}

That resolves to the overlay union — packages/types/src/overlay.ts:347, re-exported bare at packages/types/src/index.ts:255, the type behind ui:dropdown-menu / ui:context-menu / ui:menubar. But the real AppAction.items (packages/types/src/app.ts:728) is declared insideapp.ts, so it resolves to that file's own legacy navigation-item MenuItem (app.ts:461). The barrel re-exports that one renamed, as AppMenuItem (index.ts:59), precisely to avoid this collision — every line number in the finding re-derived at 26896c6 and confirmed.

The two are mutually incompatible, not merely differently named. The overlay union declares type?: never on both arms (dividers became { separator: true } in #6523), so the { "type": "separator" } item documented a few paragraphs earlier on this same page is refused by the type the snippet named.

⚠️ The suggested fix in the finding does not work

Both the original card and the ruling offer "MenuItem as AppMenuItem" as an alternative spelling. It does not fix this, and it fails in the worst way — it looks repaired and compiles:

importtype{MenuItemasAppMenuItem}from'@object-ui/types';// still the OVERLAY type

AppMenuItem is already the barrel's export name for the app.ts type. Importing MenuItem and locally aliasing it to AppMenuItem imports the overlay export and renames it, leaving the defect exactly in place under a name that reads correct. The only correct import is import type { AppMenuItem }, which is what this PR uses. Verified by type probe, below.

Census rider (required by the ruling) — result: MIXED, so #6854 is filed

The consumer named in the card is the wrong file.packages/components/src/renderers/navigation/header-bar.tsx never sees AppAction; it consumes HeaderBarSchema (packages/types/src/navigation.ts:57), whose actions?: SchemaNode[] is unrelated, and it never reads .items.

The real and only consumer is packages/runner/src/LayoutRenderer.tsx:301-315:

Field read	Line	In app.tsMenuItem (what items IS)	In overlay MenuItem
item.type === 'separator'	302	yes	no — type?: never
item.label	307	yes	yes
(item as any).onClick	304	no	yes
(item as any).shortcut	309	no	yes

Never read: path, href, badge, hidden, children.

So the renderer branches on the legacy type spelling and then reaches two overlay-shaped fields through as any, past its own declared type. That is the rider's trigger condition, so option B is filed as #6854 with this census as its evidence — not decided here, and no part of it is attempted in this PR.

This does not undermine option A: both declarations agree on what items is today (TS app.ts:728; zod mirror app.zod.ts:192, using the "Legacy MenuItem Schema" at app.zod.ts:167), so documenting AppMenuItem is documenting the shipped contract either way. If #6854 later re-types the field, this snippet changes with it.

⛔ What does NOT demonstrate this change is correct

A green CI run is not evidence here, and neither is check:doc-snippets passing. The snippet is a bare type reference (items?: MenuItem[]), never an object literal, so it compiles against eitherMenuItem. No gate goes red-to-green on this fix.

Measured rather than assumed — ablation at 4b65e8d, reverting the file to its pre-fix bytes and re-running the gate:

MUT hash : 3a8d64a (differs from HEAD blob: YES)
MUT fixed-import count : 0 (expect 0)
MUT buggy-import count : 1 (expect 1)
MUTATION CONFIRMED ON DISK
MUTATED-LEG GATE EXIT=0
Semantic phase: 267 of 267 block(s) judged, 0 failed.
Every covered documentation snippet compiles against the built types.
RESTORE CONFIRMED: hash matches HEAD blob AND git diff HEAD is empty

Identical verdict on the buggy tree. The gate is structurally blind to this defect.

What DOES demonstrate it

A type probe compiled against the builtpackages/types/dist/index.d.ts, using @ts-expect-error so each assertion fails if the expected error does not occur. Exit 0 — every assertion held:

1. AppMenuItem accepts { type: 'separator' } and the full legacy shape (type/label/path/href/badge/hidden) — it is app.ts's type.
2. The bare MenuItem the docs imported rejects{ type: 'separator' } and rejects path.
3. MenuItem as AppMenuItem still rejects { type: 'separator' } — proving that spelling stays the overlay type.
4. AppMenuItem has no onClick — the field LayoutRenderer casts past.

The probe was a scratch file, deleted before commit; it is reproducible from the four assertions above.

Gates

Run at 4b65e8d (the final commit), exit codes captured before any pipe; verdict lines quoted as each gate printed them:

Gate	Result
check:doc-snippets	exit 0 — "Every covered documentation snippet compiles against the built types." 267/267 blocks judged, 0 failed; controls (resolution / sentinel / positive / undeclared) all held. Built its declared 21-package closure first.
check:doc-fences	exit 0 — "every TypeScript block in 223 document(s) is fenced ts/tsx/typescript"
check:doc-types	exit 0
check:control-bytes	exit 0 — "scanned 5647 tracked text file(s); skipped 85 binary"
check:docs-route-closure	exit 0
check-changeset-presence	exit 0 — "No source of a released package changed in this range, so no changeset is owed."
check-changeset-no-major	exit 0 — "No changeset declares a major bump."
check-changeset-overwrite	exit 0 — "1 changeset(s) added, 0 modified, 0 deleted."

app-schema.mdx is confirmed covered by check:doc-snippets: coverage is every doc under content/docs minus the script's UNGATED_DOCS ledger, and this page has no ledger entry.

The changeset carries empty frontmatter — the repo's declaration form for a change that publishes nothing, since the presence gate itself reports nothing owed for a docs-only diff.

---

Generated by Claude Code

[os-sam]

Fixes#6692

Executes the 2026-08-29 ruling on that card: option A — the docs snippet references the type AppAction.items actually resolves to. The ruling's census rider is recorded below, and it fired: option B is filed as #6854.

Diff is two files: content/docs/core/app-schema.mdx and a changeset. packages/types/** is read-only in this card (route B's surface, and held by PR #6826).

The defect

content/docs/core/app-schema.mdx's "Global Actions" section imported the bare name:

importtype{MenuItem}from'@object-ui/types';interfaceAppAction{items?: MenuItem[];}

That resolves to the overlay union — packages/types/src/overlay.ts:347, re-exported bare at packages/types/src/index.ts:255, the type behind ui:dropdown-menu / ui:context-menu / ui:menubar. But the real AppAction.items (packages/types/src/app.ts:728) is declared insideapp.ts, so it resolves to that file's own legacy navigation-item MenuItem (app.ts:461). The barrel re-exports that one renamed, as AppMenuItem (index.ts:59), precisely to avoid this collision — every line number in the finding re-derived at 26896c6 and confirmed.

The two are mutually incompatible, not merely differently named. The overlay union declares type?: never on both arms (dividers became { separator: true } in #6523), so the { "type": "separator" } item documented a few paragraphs earlier on this same page is refused by the type the snippet named.

⚠️ The suggested fix in the finding does not work

Both the original card and the ruling offer "MenuItem as AppMenuItem" as an alternative spelling. It does not fix this, and it fails in the worst way — it looks repaired and compiles:

importtype{MenuItemasAppMenuItem}from'@object-ui/types';// still the OVERLAY type

AppMenuItem is already the barrel's export name for the app.ts type. Importing MenuItem and locally aliasing it to AppMenuItem imports the overlay export and renames it, leaving the defect exactly in place under a name that reads correct. The only correct import is import type { AppMenuItem }, which is what this PR uses. Verified by type probe, below.

Census rider (required by the ruling) — result: MIXED, so #6854 is filed

The consumer named in the card is the wrong file.packages/components/src/renderers/navigation/header-bar.tsx never sees AppAction; it consumes HeaderBarSchema (packages/types/src/navigation.ts:57), whose actions?: SchemaNode[] is unrelated, and it never reads .items.

The real and only consumer is packages/runner/src/LayoutRenderer.tsx:301-315:

Field read	Line	In app.tsMenuItem (what items IS)	In overlay MenuItem
item.type === 'separator'	302	yes	no — type?: never
item.label	307	yes	yes
(item as any).onClick	304	no	yes
(item as any).shortcut	309	no	yes

Never read: path, href, badge, hidden, children.

So the renderer branches on the legacy type spelling and then reaches two overlay-shaped fields through as any, past its own declared type. That is the rider's trigger condition, so option B is filed as #6854 with this census as its evidence — not decided here, and no part of it is attempted in this PR.

This does not undermine option A: both declarations agree on what items is today (TS app.ts:728; zod mirror app.zod.ts:192, using the "Legacy MenuItem Schema" at app.zod.ts:167), so documenting AppMenuItem is documenting the shipped contract either way. If #6854 later re-types the field, this snippet changes with it.

⛔ What does NOT demonstrate this change is correct

A green CI run is not evidence here, and neither is check:doc-snippets passing. The snippet is a bare type reference (items?: MenuItem[]), never an object literal, so it compiles against eitherMenuItem. No gate goes red-to-green on this fix.

Measured rather than assumed — ablation at 4b65e8d, reverting the file to its pre-fix bytes and re-running the gate:

MUT hash : 3a8d64a (differs from HEAD blob: YES)
MUT fixed-import count : 0 (expect 0)
MUT buggy-import count : 1 (expect 1)
MUTATION CONFIRMED ON DISK
MUTATED-LEG GATE EXIT=0
Semantic phase: 267 of 267 block(s) judged, 0 failed.
Every covered documentation snippet compiles against the built types.
RESTORE CONFIRMED: hash matches HEAD blob AND git diff HEAD is empty

Identical verdict on the buggy tree. The gate is structurally blind to this defect.

What DOES demonstrate it

A type probe compiled against the builtpackages/types/dist/index.d.ts, using @ts-expect-error so each assertion fails if the expected error does not occur. Exit 0 — every assertion held:

1. AppMenuItem accepts { type: 'separator' } and the full legacy shape (type/label/path/href/badge/hidden) — it is app.ts's type.
2. The bare MenuItem the docs imported rejects{ type: 'separator' } and rejects path.
3. MenuItem as AppMenuItem still rejects { type: 'separator' } — proving that spelling stays the overlay type.
4. AppMenuItem has no onClick — the field LayoutRenderer casts past.

The probe was a scratch file, deleted before commit; it is reproducible from the four assertions above.

Gates

Run at 4b65e8d (the final commit), exit codes captured before any pipe; verdict lines quoted as each gate printed them:

Gate	Result
check:doc-snippets	exit 0 — "Every covered documentation snippet compiles against the built types." 267/267 blocks judged, 0 failed; controls (resolution / sentinel / positive / undeclared) all held. Built its declared 21-package closure first.
check:doc-fences	exit 0 — "every TypeScript block in 223 document(s) is fenced ts/tsx/typescript"
check:doc-types	exit 0
check:control-bytes	exit 0 — "scanned 5647 tracked text file(s); skipped 85 binary"
check:docs-route-closure	exit 0
check-changeset-presence	exit 0 — "No source of a released package changed in this range, so no changeset is owed."
check-changeset-no-major	exit 0 — "No changeset declares a major bump."
check-changeset-overwrite	exit 0 — "1 changeset(s) added, 0 modified, 0 deleted."

app-schema.mdx is confirmed covered by check:doc-snippets: coverage is every doc under content/docs minus the script's UNGATED_DOCS ledger, and this page has no ledger entry.

The changeset carries empty frontmatter — the repo's declaration form for a change that publishes nothing, since the presence gate itself reports nothing owed for a docs-only diff.

---

Generated by Claude Code

[os-sam]

Fixes#6692

Executes the 2026-08-29 ruling on that card: option A — the docs snippet references the type AppAction.items actually resolves to. The ruling's census rider is recorded below, and it fired: option B is filed as #6854.

Diff is two files: content/docs/core/app-schema.mdx and a changeset. packages/types/** is read-only in this card (route B's surface, and held by PR #6826).

The defect

content/docs/core/app-schema.mdx's "Global Actions" section imported the bare name:

importtype{MenuItem}from'@object-ui/types';interfaceAppAction{items?: MenuItem[];}

That resolves to the overlay union — packages/types/src/overlay.ts:347, re-exported bare at packages/types/src/index.ts:255, the type behind ui:dropdown-menu / ui:context-menu / ui:menubar. But the real AppAction.items (packages/types/src/app.ts:728) is declared insideapp.ts, so it resolves to that file's own legacy navigation-item MenuItem (app.ts:461). The barrel re-exports that one renamed, as AppMenuItem (index.ts:59), precisely to avoid this collision — every line number in the finding re-derived at 26896c6 and confirmed.

The two are mutually incompatible, not merely differently named. The overlay union declares type?: never on both arms (dividers became { separator: true } in #6523), so the { "type": "separator" } item documented a few paragraphs earlier on this same page is refused by the type the snippet named.

⚠️ The suggested fix in the finding does not work

Both the original card and the ruling offer "MenuItem as AppMenuItem" as an alternative spelling. It does not fix this, and it fails in the worst way — it looks repaired and compiles:

importtype{MenuItemasAppMenuItem}from'@object-ui/types';// still the OVERLAY type

AppMenuItem is already the barrel's export name for the app.ts type. Importing MenuItem and locally aliasing it to AppMenuItem imports the overlay export and renames it, leaving the defect exactly in place under a name that reads correct. The only correct import is import type { AppMenuItem }, which is what this PR uses. Verified by type probe, below.

Census rider (required by the ruling) — result: MIXED, so #6854 is filed

The consumer named in the card is the wrong file.packages/components/src/renderers/navigation/header-bar.tsx never sees AppAction; it consumes HeaderBarSchema (packages/types/src/navigation.ts:57), whose actions?: SchemaNode[] is unrelated, and it never reads .items.

The real and only consumer is packages/runner/src/LayoutRenderer.tsx:301-315:

Field read	Line	In app.tsMenuItem (what items IS)	In overlay MenuItem
item.type === 'separator'	302	yes	no — type?: never
item.label	307	yes	yes
(item as any).onClick	304	no	yes
(item as any).shortcut	309	no	yes

Never read: path, href, badge, hidden, children.

So the renderer branches on the legacy type spelling and then reaches two overlay-shaped fields through as any, past its own declared type. That is the rider's trigger condition, so option B is filed as #6854 with this census as its evidence — not decided here, and no part of it is attempted in this PR.

This does not undermine option A: both declarations agree on what items is today (TS app.ts:728; zod mirror app.zod.ts:192, using the "Legacy MenuItem Schema" at app.zod.ts:167), so documenting AppMenuItem is documenting the shipped contract either way. If #6854 later re-types the field, this snippet changes with it.

⛔ What does NOT demonstrate this change is correct

A green CI run is not evidence here, and neither is check:doc-snippets passing. The snippet is a bare type reference (items?: MenuItem[]), never an object literal, so it compiles against eitherMenuItem. No gate goes red-to-green on this fix.

Measured rather than assumed — ablation at 4b65e8d, reverting the file to its pre-fix bytes and re-running the gate:

MUT hash : 3a8d64a (differs from HEAD blob: YES)
MUT fixed-import count : 0 (expect 0)
MUT buggy-import count : 1 (expect 1)
MUTATION CONFIRMED ON DISK
MUTATED-LEG GATE EXIT=0
Semantic phase: 267 of 267 block(s) judged, 0 failed.
Every covered documentation snippet compiles against the built types.
RESTORE CONFIRMED: hash matches HEAD blob AND git diff HEAD is empty

Identical verdict on the buggy tree. The gate is structurally blind to this defect.

What DOES demonstrate it

A type probe compiled against the builtpackages/types/dist/index.d.ts, using @ts-expect-error so each assertion fails if the expected error does not occur. Exit 0 — every assertion held:

1. AppMenuItem accepts { type: 'separator' } and the full legacy shape (type/label/path/href/badge/hidden) — it is app.ts's type.
2. The bare MenuItem the docs imported rejects{ type: 'separator' } and rejects path.
3. MenuItem as AppMenuItem still rejects { type: 'separator' } — proving that spelling stays the overlay type.
4. AppMenuItem has no onClick — the field LayoutRenderer casts past.

The probe was a scratch file, deleted before commit; it is reproducible from the four assertions above.

Gates

Run at 4b65e8d (the final commit), exit codes captured before any pipe; verdict lines quoted as each gate printed them:

Gate	Result
check:doc-snippets	exit 0 — "Every covered documentation snippet compiles against the built types." 267/267 blocks judged, 0 failed; controls (resolution / sentinel / positive / undeclared) all held. Built its declared 21-package closure first.
check:doc-fences	exit 0 — "every TypeScript block in 223 document(s) is fenced ts/tsx/typescript"
check:doc-types	exit 0
check:control-bytes	exit 0 — "scanned 5647 tracked text file(s); skipped 85 binary"
check:docs-route-closure	exit 0
check-changeset-presence	exit 0 — "No source of a released package changed in this range, so no changeset is owed."
check-changeset-no-major	exit 0 — "No changeset declares a major bump."
check-changeset-overwrite	exit 0 — "1 changeset(s) added, 0 modified, 0 deleted."

app-schema.mdx is confirmed covered by check:doc-snippets: coverage is every doc under content/docs minus the script's UNGATED_DOCS ledger, and this page has no ledger entry.

The changeset carries empty frontmatter — the repo's declaration form for a change that publishes nothing, since the presence gate itself reports nothing owed for a docs-only diff.

---

Generated by Claude Code

[os-sam]

Fixes#6692

Executes the 2026-08-29 ruling on that card: option A — the docs snippet references the type AppAction.items actually resolves to. The ruling's census rider is recorded below, and it fired: option B is filed as #6854.

Diff is two files: content/docs/core/app-schema.mdx and a changeset. packages/types/** is read-only in this card (route B's surface, and held by PR #6826).

The defect

content/docs/core/app-schema.mdx's "Global Actions" section imported the bare name:

importtype{MenuItem}from'@object-ui/types';interfaceAppAction{items?: MenuItem[];}

That resolves to the overlay union — packages/types/src/overlay.ts:347, re-exported bare at packages/types/src/index.ts:255, the type behind ui:dropdown-menu / ui:context-menu / ui:menubar. But the real AppAction.items (packages/types/src/app.ts:728) is declared insideapp.ts, so it resolves to that file's own legacy navigation-item MenuItem (app.ts:461). The barrel re-exports that one renamed, as AppMenuItem (index.ts:59), precisely to avoid this collision — every line number in the finding re-derived at 26896c6 and confirmed.

The two are mutually incompatible, not merely differently named. The overlay union declares type?: never on both arms (dividers became { separator: true } in #6523), so the { "type": "separator" } item documented a few paragraphs earlier on this same page is refused by the type the snippet named.

⚠️ The suggested fix in the finding does not work

Both the original card and the ruling offer "MenuItem as AppMenuItem" as an alternative spelling. It does not fix this, and it fails in the worst way — it looks repaired and compiles:

importtype{MenuItemasAppMenuItem}from'@object-ui/types';// still the OVERLAY type

AppMenuItem is already the barrel's export name for the app.ts type. Importing MenuItem and locally aliasing it to AppMenuItem imports the overlay export and renames it, leaving the defect exactly in place under a name that reads correct. The only correct import is import type { AppMenuItem }, which is what this PR uses. Verified by type probe, below.

Census rider (required by the ruling) — result: MIXED, so #6854 is filed

The consumer named in the card is the wrong file.packages/components/src/renderers/navigation/header-bar.tsx never sees AppAction; it consumes HeaderBarSchema (packages/types/src/navigation.ts:57), whose actions?: SchemaNode[] is unrelated, and it never reads .items.

The real and only consumer is packages/runner/src/LayoutRenderer.tsx:301-315:

Field read	Line	In app.tsMenuItem (what items IS)	In overlay MenuItem
item.type === 'separator'	302	yes	no — type?: never
item.label	307	yes	yes
(item as any).onClick	304	no	yes
(item as any).shortcut	309	no	yes

Never read: path, href, badge, hidden, children.

So the renderer branches on the legacy type spelling and then reaches two overlay-shaped fields through as any, past its own declared type. That is the rider's trigger condition, so option B is filed as #6854 with this census as its evidence — not decided here, and no part of it is attempted in this PR.

This does not undermine option A: both declarations agree on what items is today (TS app.ts:728; zod mirror app.zod.ts:192, using the "Legacy MenuItem Schema" at app.zod.ts:167), so documenting AppMenuItem is documenting the shipped contract either way. If #6854 later re-types the field, this snippet changes with it.

⛔ What does NOT demonstrate this change is correct

A green CI run is not evidence here, and neither is check:doc-snippets passing. The snippet is a bare type reference (items?: MenuItem[]), never an object literal, so it compiles against eitherMenuItem. No gate goes red-to-green on this fix.

Measured rather than assumed — ablation at 4b65e8d, reverting the file to its pre-fix bytes and re-running the gate:

MUT hash : 3a8d64a (differs from HEAD blob: YES)
MUT fixed-import count : 0 (expect 0)
MUT buggy-import count : 1 (expect 1)
MUTATION CONFIRMED ON DISK
MUTATED-LEG GATE EXIT=0
Semantic phase: 267 of 267 block(s) judged, 0 failed.
Every covered documentation snippet compiles against the built types.
RESTORE CONFIRMED: hash matches HEAD blob AND git diff HEAD is empty

Identical verdict on the buggy tree. The gate is structurally blind to this defect.

What DOES demonstrate it

A type probe compiled against the builtpackages/types/dist/index.d.ts, using @ts-expect-error so each assertion fails if the expected error does not occur. Exit 0 — every assertion held:

1. AppMenuItem accepts { type: 'separator' } and the full legacy shape (type/label/path/href/badge/hidden) — it is app.ts's type.
2. The bare MenuItem the docs imported rejects{ type: 'separator' } and rejects path.
3. MenuItem as AppMenuItem still rejects { type: 'separator' } — proving that spelling stays the overlay type.
4. AppMenuItem has no onClick — the field LayoutRenderer casts past.

The probe was a scratch file, deleted before commit; it is reproducible from the four assertions above.

Gates

Run at 4b65e8d (the final commit), exit codes captured before any pipe; verdict lines quoted as each gate printed them:

Gate	Result
check:doc-snippets	exit 0 — "Every covered documentation snippet compiles against the built types." 267/267 blocks judged, 0 failed; controls (resolution / sentinel / positive / undeclared) all held. Built its declared 21-package closure first.
check:doc-fences	exit 0 — "every TypeScript block in 223 document(s) is fenced ts/tsx/typescript"
check:doc-types	exit 0
check:control-bytes	exit 0 — "scanned 5647 tracked text file(s); skipped 85 binary"
check:docs-route-closure	exit 0
check-changeset-presence	exit 0 — "No source of a released package changed in this range, so no changeset is owed."
check-changeset-no-major	exit 0 — "No changeset declares a major bump."
check-changeset-overwrite	exit 0 — "1 changeset(s) added, 0 modified, 0 deleted."

app-schema.mdx is confirmed covered by check:doc-snippets: coverage is every doc under content/docs minus the script's UNGATED_DOCS ledger, and this page has no ledger entry.

The changeset carries empty frontmatter — the repo's declaration form for a change that publishes nothing, since the presence gate itself reports nothing owed for a docs-only diff.

---

Generated by Claude Code

[os-sam]

Fixes#6692

Executes the 2026-08-29 ruling on that card: option A — the docs snippet references the type AppAction.items actually resolves to. The ruling's census rider is recorded below, and it fired: option B is filed as #6854.

Diff is two files: content/docs/core/app-schema.mdx and a changeset. packages/types/** is read-only in this card (route B's surface, and held by PR #6826).

The defect

content/docs/core/app-schema.mdx's "Global Actions" section imported the bare name:

importtype{MenuItem}from'@object-ui/types';interfaceAppAction{items?: MenuItem[];}

That resolves to the overlay union — packages/types/src/overlay.ts:347, re-exported bare at packages/types/src/index.ts:255, the type behind ui:dropdown-menu / ui:context-menu / ui:menubar. But the real AppAction.items (packages/types/src/app.ts:728) is declared insideapp.ts, so it resolves to that file's own legacy navigation-item MenuItem (app.ts:461). The barrel re-exports that one renamed, as AppMenuItem (index.ts:59), precisely to avoid this collision — every line number in the finding re-derived at 26896c6 and confirmed.

The two are mutually incompatible, not merely differently named. The overlay union declares type?: never on both arms (dividers became { separator: true } in #6523), so the { "type": "separator" } item documented a few paragraphs earlier on this same page is refused by the type the snippet named.

⚠️ The suggested fix in the finding does not work

Both the original card and the ruling offer "MenuItem as AppMenuItem" as an alternative spelling. It does not fix this, and it fails in the worst way — it looks repaired and compiles:

importtype{MenuItemasAppMenuItem}from'@object-ui/types';// still the OVERLAY type

AppMenuItem is already the barrel's export name for the app.ts type. Importing MenuItem and locally aliasing it to AppMenuItem imports the overlay export and renames it, leaving the defect exactly in place under a name that reads correct. The only correct import is import type { AppMenuItem }, which is what this PR uses. Verified by type probe, below.

Census rider (required by the ruling) — result: MIXED, so #6854 is filed

The consumer named in the card is the wrong file.packages/components/src/renderers/navigation/header-bar.tsx never sees AppAction; it consumes HeaderBarSchema (packages/types/src/navigation.ts:57), whose actions?: SchemaNode[] is unrelated, and it never reads .items.

The real and only consumer is packages/runner/src/LayoutRenderer.tsx:301-315:

Field read	Line	In app.tsMenuItem (what items IS)	In overlay MenuItem
item.type === 'separator'	302	yes	no — type?: never
item.label	307	yes	yes
(item as any).onClick	304	no	yes
(item as any).shortcut	309	no	yes

Never read: path, href, badge, hidden, children.

So the renderer branches on the legacy type spelling and then reaches two overlay-shaped fields through as any, past its own declared type. That is the rider's trigger condition, so option B is filed as #6854 with this census as its evidence — not decided here, and no part of it is attempted in this PR.

This does not undermine option A: both declarations agree on what items is today (TS app.ts:728; zod mirror app.zod.ts:192, using the "Legacy MenuItem Schema" at app.zod.ts:167), so documenting AppMenuItem is documenting the shipped contract either way. If #6854 later re-types the field, this snippet changes with it.

⛔ What does NOT demonstrate this change is correct

A green CI run is not evidence here, and neither is check:doc-snippets passing. The snippet is a bare type reference (items?: MenuItem[]), never an object literal, so it compiles against eitherMenuItem. No gate goes red-to-green on this fix.

Measured rather than assumed — ablation at 4b65e8d, reverting the file to its pre-fix bytes and re-running the gate:

MUT hash : 3a8d64a (differs from HEAD blob: YES)
MUT fixed-import count : 0 (expect 0)
MUT buggy-import count : 1 (expect 1)
MUTATION CONFIRMED ON DISK
MUTATED-LEG GATE EXIT=0
Semantic phase: 267 of 267 block(s) judged, 0 failed.
Every covered documentation snippet compiles against the built types.
RESTORE CONFIRMED: hash matches HEAD blob AND git diff HEAD is empty

Identical verdict on the buggy tree. The gate is structurally blind to this defect.

What DOES demonstrate it

A type probe compiled against the builtpackages/types/dist/index.d.ts, using @ts-expect-error so each assertion fails if the expected error does not occur. Exit 0 — every assertion held:

1. AppMenuItem accepts { type: 'separator' } and the full legacy shape (type/label/path/href/badge/hidden) — it is app.ts's type.
2. The bare MenuItem the docs imported rejects{ type: 'separator' } and rejects path.
3. MenuItem as AppMenuItem still rejects { type: 'separator' } — proving that spelling stays the overlay type.
4. AppMenuItem has no onClick — the field LayoutRenderer casts past.

The probe was a scratch file, deleted before commit; it is reproducible from the four assertions above.

Gates

Run at 4b65e8d (the final commit), exit codes captured before any pipe; verdict lines quoted as each gate printed them:

Gate	Result
check:doc-snippets	exit 0 — "Every covered documentation snippet compiles against the built types." 267/267 blocks judged, 0 failed; controls (resolution / sentinel / positive / undeclared) all held. Built its declared 21-package closure first.
check:doc-fences	exit 0 — "every TypeScript block in 223 document(s) is fenced ts/tsx/typescript"
check:doc-types	exit 0
check:control-bytes	exit 0 — "scanned 5647 tracked text file(s); skipped 85 binary"
check:docs-route-closure	exit 0
check-changeset-presence	exit 0 — "No source of a released package changed in this range, so no changeset is owed."
check-changeset-no-major	exit 0 — "No changeset declares a major bump."
check-changeset-overwrite	exit 0 — "1 changeset(s) added, 0 modified, 0 deleted."

app-schema.mdx is confirmed covered by check:doc-snippets: coverage is every doc under content/docs minus the script's UNGATED_DOCS ledger, and this page has no ledger entry.

The changeset carries empty frontmatter — the repo's declaration form for a change that publishes nothing, since the presence gate itself reports nothing owed for a docs-only diff.

---

Generated by Claude Code