feat(cli): validate prints the union arm the document selected, not a bare "Invalid input"

.changeset/7004-cli-union-arm-selection.md

@@ -0,0 +1,39 @@
+---
+'@object-ui/cli': minor
+---
+
+`objectui validate` now prints the failing union arm the document selected, instead of a
+bare "Invalid input" (objectui#7004, maintainer ruling 2026-09-02 — option B).
+
+`safeValidateSchema` checks a document against `AnyComponentSchema`, a `z.union`. When a
+document matches no arm, Zod reports ONE top-level issue — `invalid_union` · `Invalid
+input` · path `(root)` — and hangs every arm's real diagnosis off that issue's `errors`
+array, which nothing read. So a menu whose item used the divider spelling retired in
+objectui#6523 printed a bare verdict on the whole document, while the remediation text
+objectui#6931 wrote into that arm sat one level down, unreachable.
+
+**What is printed now.** When the top-level issue is a failing union:
+
+- the document's `type` selects exactly one arm ⇒ that arm's issues are printed beneath
+ the entry as `1.1`, `1.2` … with their real paths (`Path: items → 0 → type`) and codes,
+ and **nothing** from the other arms;
+- no arm accepts the `type` ⇒ `No arm accepts type "dropdwn-menu".` plus the nearest few
+ of the accepted values, ranked by edit distance and **capped** at five
+ (`MAX_UNION_ARMS_REPORTED`);
+- the document declares no `type` at all ⇒ the note says so and offers no candidates —
+ "nearest" needs something to be near, and an alphabetical slice of 108 arm names
+ presented as guidance would be a bogus suggestion;
+- a union with no `type` discriminator to select on — `MenuItemSchema`, whose two arms
+ both declare `type` as an ADR-0049 retirement tombstone — reports every arm, labelled
+ and capped by the same constant. This is the path that finally delivers the
+ objectui#6523 text to the author.
+
+Printing EVERY arm was rejected in the ruling: `AnyComponentSchema` resolves to 108 leaf
+arms, so one mistyped `type` would have produced hundreds of lines.
+
+`objectui check` is unchanged and deliberately so: it has no zod-issue printer, using
+`safeValidateSchema(...).success` as a boolean recogniser. Printing issues behind a
+*negative* recognition would flood its report with diagnoses of non-ObjectUI files, the
+failure objectui#5127 and objectui#6075 exist to prevent.
+
+Nothing about which documents are ACCEPTED changes — this is diagnostic output only.

content/docs/utilities/cli.mdx

@@ -158,6 +158,37 @@ objectui validate app.json
 objectui validate ./schemas/dashboard.yaml
 ```
 
+#### Reading a failure
+
+A document is checked against a union of every component type, so a failure is
+reported first at the document root and then narrowed to the arm your `type`
+selected. Each numbered issue carries a path and a code; the `1.1`-style entries
+beneath it are that arm's own diagnosis, with the real path to the node that
+failed:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ 1.1 RETIRED (objectui#6523) — dividers are `{ separator: true }`; …
+ Path: items → 0 → type
+ Code: invalid_type
+```
+
+Only the selected arm is shown. When your `type` matches no component at all,
+the report says so and offers the nearest few of the accepted values instead:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ No arm accepts type "dropdwn-menu".
+ Nearest of the 108 accepted types: dropdown-menu, context-menu, component, drawer, breadcrumb
+```
+
+A document with no `type` at all is reported the same way, without a candidate
+list — there is nothing for the suggestions to be near.
+
 ### `objectui check`
 
 Scan the project for ObjectUI schema files and report on the ones it

packages/cli/README.md

@@ -117,6 +117,13 @@ Add a new component renderer to your project.
 
 Validate a schema file against the ObjectUI specification.
 
+A failure is reported at the document root and then narrowed to the union arm
+your `type` selected — the `1.1`-style entries under a numbered issue are that
+arm's own diagnosis, at the real path of the node that failed. When no component
+type matches, the report names the nearest few of the accepted values instead of
+listing all of them. See the
+[docs](https://www.objectui.org/docs/utilities/cli) for worked output.
+
 ### `objectui check`, `objectui doctor`, `objectui studio`, `objectui analyze`, `objectui create plugin <name>`
 
 Utility commands — see `objectui --help`.

packages/cli/src/__tests__/validate-root-path-line.test.ts

@@ -9,6 +9,11 @@
 /**
  * `objectui validate` and the ROOT-LEVEL issue (objectui#7004, mechanical half).
  *
+ * The arm-selection half of the same card landed later, on the 2026-09-02
+ * ruling; its contract lives in `validate-union-arm-selection.test.ts`. The last
+ * describe block here was the boundary pin that made that landing an explicit
+ * edit, and now restates the new semantics from this file's point of view.
+ *
  * The printer used to guard its Path line with `issue.path.length > 0`, so an
  * issue at the document root (`path: []`) printed no Path line at all — silent
  * in precisely the case a reader most needs oriented.
@@ -181,27 +186,40 @@ describe('objectui validate — a real path is still a real path', () => {
  });
 });
 
-describe('objectui validate — the arm-selection half is deliberately NOT done here', () => {
+describe('objectui validate — the arm-selection half, now that it is ruled', () => {
  /**
- * ⚠️ This case pins a BOUNDARY, not a desired end state. objectui#7004 splits
- * into the root-path line (done, above) and the question of whether a failing
- * union should also surface its per-arm diagnoses — and if so, which arm's.
- * The second is an author-facing diagnostic contract and is awaiting a
- * maintainer ruling, so this file records that the printer walks only the
- * top level today.
+ * ⚠️ This case USED to pin the opposite. It was written as a deliberate
+ * boundary: while the arm-selection question was with the maintainer, it
+ * asserted that the printer walked only the top level — `not.toContain
+ * ('RETIRED (objectui#6523)')`, `not.toContain('Path: items')` — so that when
+ * the ruling landed it would land as an explicit edit against a RED test
+ * rather than as a silent widening.
+ *
+ * The 2026-09-02 ruling landed (option B: the arm the document's `type`
+ * selects, nothing from the others), so the boundary moved and these
+ * assertions are inverted. That is the mechanism working, not a test being
+ * loosened: the pin forced this file to be opened and the semantics restated
+ * by hand.
  *
- * When that ruling lands, this case is EXPECTED to change with it. It exists
- * so the change is a deliberate edit rather than a silent widening.
+ * The full contract lives in `validate-union-arm-selection.test.ts`. What
+ * stays HERE is the part this file has always been about — that widening the
+ * printer did not cost the root-path line, and did not turn one top-level
+ * issue into many.
  */
- it('prints one top-level entry for a union, not the per-arm remediation text', async () => {
+ it('surfaces the selected arm\'s diagnosis without multiplying top-level entries', async () => {
  await validate(writeSchema('menu.json', MENU_WITH_RETIRED_DIVIDER));
 
  const text = printed();
- // The arm issues carry the objectui#6523 tombstone guidance. Nothing here
- // reads `issue.errors`, so none of it is printed.
- expect(text).not.toContain('RETIRED (objectui#6523)');
- expect(text).not.toContain('Path: items');
- // Exactly one numbered issue — an arm walk would multiply this.
+ // Was `not.toContain` until the ruling. The objectui#6523 tombstone text
+ // rides the per-arm issues, which is exactly why it never reached an author.
+ expect(text).toContain('RETIRED (objectui#6523)');
+ expect(text).toContain('Path: items → 0 → type');
+ // Unchanged, and load-bearing: the top-level entry still carries the root
+ // path line this file exists for.
+ expect(text).toContain('Path: (root)');
+ // Still exactly one NUMBERED issue. Arm entries are `1.1`-shaped, so a
+ // reader (and this assertion) can still count the top-level failures — an
+ // arm walk that emitted them as `2.`, `3.` … would have multiplied this.
  const numbered = printed()
  .split('\n')
  .filter((line) => /^\d+\. /.test(line.trim()));

.changeset/7004-cli-union-arm-selection.md

@@ -0,0 +1,39 @@
+---
+'@object-ui/cli': minor
+---
+
+`objectui validate` now prints the failing union arm the document selected, instead of a
+bare "Invalid input" (objectui#7004, maintainer ruling 2026-09-02 — option B).
+
+`safeValidateSchema` checks a document against `AnyComponentSchema`, a `z.union`. When a
+document matches no arm, Zod reports ONE top-level issue — `invalid_union` · `Invalid
+input` · path `(root)` — and hangs every arm's real diagnosis off that issue's `errors`
+array, which nothing read. So a menu whose item used the divider spelling retired in
+objectui#6523 printed a bare verdict on the whole document, while the remediation text
+objectui#6931 wrote into that arm sat one level down, unreachable.
+
+**What is printed now.** When the top-level issue is a failing union:
+
+- the document's `type` selects exactly one arm ⇒ that arm's issues are printed beneath
+ the entry as `1.1`, `1.2` … with their real paths (`Path: items → 0 → type`) and codes,
+ and **nothing** from the other arms;
+- no arm accepts the `type` ⇒ `No arm accepts type "dropdwn-menu".` plus the nearest few
+ of the accepted values, ranked by edit distance and **capped** at five
+ (`MAX_UNION_ARMS_REPORTED`);
+- the document declares no `type` at all ⇒ the note says so and offers no candidates —
+ "nearest" needs something to be near, and an alphabetical slice of 108 arm names
+ presented as guidance would be a bogus suggestion;
+- a union with no `type` discriminator to select on — `MenuItemSchema`, whose two arms
+ both declare `type` as an ADR-0049 retirement tombstone — reports every arm, labelled
+ and capped by the same constant. This is the path that finally delivers the
+ objectui#6523 text to the author.
+
+Printing EVERY arm was rejected in the ruling: `AnyComponentSchema` resolves to 108 leaf
+arms, so one mistyped `type` would have produced hundreds of lines.
+
+`objectui check` is unchanged and deliberately so: it has no zod-issue printer, using
+`safeValidateSchema(...).success` as a boolean recogniser. Printing issues behind a
+*negative* recognition would flood its report with diagnoses of non-ObjectUI files, the
+failure objectui#5127 and objectui#6075 exist to prevent.
+
+Nothing about which documents are ACCEPTED changes — this is diagnostic output only.

content/docs/utilities/cli.mdx

@@ -158,6 +158,37 @@ objectui validate app.json
 objectui validate ./schemas/dashboard.yaml
 ```
 
+#### Reading a failure
+
+A document is checked against a union of every component type, so a failure is
+reported first at the document root and then narrowed to the arm your `type`
+selected. Each numbered issue carries a path and a code; the `1.1`-style entries
+beneath it are that arm's own diagnosis, with the real path to the node that
+failed:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ 1.1 RETIRED (objectui#6523) — dividers are `{ separator: true }`; …
+ Path: items → 0 → type
+ Code: invalid_type
+```
+
+Only the selected arm is shown. When your `type` matches no component at all,
+the report says so and offers the nearest few of the accepted values instead:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ No arm accepts type "dropdwn-menu".
+ Nearest of the 108 accepted types: dropdown-menu, context-menu, component, drawer, breadcrumb
+```
+
+A document with no `type` at all is reported the same way, without a candidate
+list — there is nothing for the suggestions to be near.
+
 ### `objectui check`
 
 Scan the project for ObjectUI schema files and report on the ones it

packages/cli/README.md

@@ -117,6 +117,13 @@ Add a new component renderer to your project.
 
 Validate a schema file against the ObjectUI specification.
 
+A failure is reported at the document root and then narrowed to the union arm
+your `type` selected — the `1.1`-style entries under a numbered issue are that
+arm's own diagnosis, at the real path of the node that failed. When no component
+type matches, the report names the nearest few of the accepted values instead of
+listing all of them. See the
+[docs](https://www.objectui.org/docs/utilities/cli) for worked output.
+
 ### `objectui check`, `objectui doctor`, `objectui studio`, `objectui analyze`, `objectui create plugin <name>`
 
 Utility commands — see `objectui --help`.

packages/cli/src/__tests__/validate-root-path-line.test.ts

@@ -9,6 +9,11 @@
 /**
  * `objectui validate` and the ROOT-LEVEL issue (objectui#7004, mechanical half).
  *
+ * The arm-selection half of the same card landed later, on the 2026-09-02
+ * ruling; its contract lives in `validate-union-arm-selection.test.ts`. The last
+ * describe block here was the boundary pin that made that landing an explicit
+ * edit, and now restates the new semantics from this file's point of view.
+ *
  * The printer used to guard its Path line with `issue.path.length > 0`, so an
  * issue at the document root (`path: []`) printed no Path line at all — silent
  * in precisely the case a reader most needs oriented.
@@ -181,27 +186,40 @@ describe('objectui validate — a real path is still a real path', () => {
  });
 });
 
-describe('objectui validate — the arm-selection half is deliberately NOT done here', () => {
+describe('objectui validate — the arm-selection half, now that it is ruled', () => {
  /**
- * ⚠️ This case pins a BOUNDARY, not a desired end state. objectui#7004 splits
- * into the root-path line (done, above) and the question of whether a failing
- * union should also surface its per-arm diagnoses — and if so, which arm's.
- * The second is an author-facing diagnostic contract and is awaiting a
- * maintainer ruling, so this file records that the printer walks only the
- * top level today.
+ * ⚠️ This case USED to pin the opposite. It was written as a deliberate
+ * boundary: while the arm-selection question was with the maintainer, it
+ * asserted that the printer walked only the top level — `not.toContain
+ * ('RETIRED (objectui#6523)')`, `not.toContain('Path: items')` — so that when
+ * the ruling landed it would land as an explicit edit against a RED test
+ * rather than as a silent widening.
+ *
+ * The 2026-09-02 ruling landed (option B: the arm the document's `type`
+ * selects, nothing from the others), so the boundary moved and these
+ * assertions are inverted. That is the mechanism working, not a test being
+ * loosened: the pin forced this file to be opened and the semantics restated
+ * by hand.
  *
- * When that ruling lands, this case is EXPECTED to change with it. It exists
- * so the change is a deliberate edit rather than a silent widening.
+ * The full contract lives in `validate-union-arm-selection.test.ts`. What
+ * stays HERE is the part this file has always been about — that widening the
+ * printer did not cost the root-path line, and did not turn one top-level
+ * issue into many.
  */
- it('prints one top-level entry for a union, not the per-arm remediation text', async () => {
+ it('surfaces the selected arm\'s diagnosis without multiplying top-level entries', async () => {
  await validate(writeSchema('menu.json', MENU_WITH_RETIRED_DIVIDER));
 
  const text = printed();
- // The arm issues carry the objectui#6523 tombstone guidance. Nothing here
- // reads `issue.errors`, so none of it is printed.
- expect(text).not.toContain('RETIRED (objectui#6523)');
- expect(text).not.toContain('Path: items');
- // Exactly one numbered issue — an arm walk would multiply this.
+ // Was `not.toContain` until the ruling. The objectui#6523 tombstone text
+ // rides the per-arm issues, which is exactly why it never reached an author.
+ expect(text).toContain('RETIRED (objectui#6523)');
+ expect(text).toContain('Path: items → 0 → type');
+ // Unchanged, and load-bearing: the top-level entry still carries the root
+ // path line this file exists for.
+ expect(text).toContain('Path: (root)');
+ // Still exactly one NUMBERED issue. Arm entries are `1.1`-shaped, so a
+ // reader (and this assertion) can still count the top-level failures — an
+ // arm walk that emitted them as `2.`, `3.` … would have multiplied this.
  const numbered = printed()
  .split('\n')
  .filter((line) => /^\d+\. /.test(line.trim()));

.changeset/7004-cli-union-arm-selection.md

@@ -0,0 +1,39 @@
+---
+'@object-ui/cli': minor
+---
+
+`objectui validate` now prints the failing union arm the document selected, instead of a
+bare "Invalid input" (objectui#7004, maintainer ruling 2026-09-02 — option B).
+
+`safeValidateSchema` checks a document against `AnyComponentSchema`, a `z.union`. When a
+document matches no arm, Zod reports ONE top-level issue — `invalid_union` · `Invalid
+input` · path `(root)` — and hangs every arm's real diagnosis off that issue's `errors`
+array, which nothing read. So a menu whose item used the divider spelling retired in
+objectui#6523 printed a bare verdict on the whole document, while the remediation text
+objectui#6931 wrote into that arm sat one level down, unreachable.
+
+**What is printed now.** When the top-level issue is a failing union:
+
+- the document's `type` selects exactly one arm ⇒ that arm's issues are printed beneath
+ the entry as `1.1`, `1.2` … with their real paths (`Path: items → 0 → type`) and codes,
+ and **nothing** from the other arms;
+- no arm accepts the `type` ⇒ `No arm accepts type "dropdwn-menu".` plus the nearest few
+ of the accepted values, ranked by edit distance and **capped** at five
+ (`MAX_UNION_ARMS_REPORTED`);
+- the document declares no `type` at all ⇒ the note says so and offers no candidates —
+ "nearest" needs something to be near, and an alphabetical slice of 108 arm names
+ presented as guidance would be a bogus suggestion;
+- a union with no `type` discriminator to select on — `MenuItemSchema`, whose two arms
+ both declare `type` as an ADR-0049 retirement tombstone — reports every arm, labelled
+ and capped by the same constant. This is the path that finally delivers the
+ objectui#6523 text to the author.
+
+Printing EVERY arm was rejected in the ruling: `AnyComponentSchema` resolves to 108 leaf
+arms, so one mistyped `type` would have produced hundreds of lines.
+
+`objectui check` is unchanged and deliberately so: it has no zod-issue printer, using
+`safeValidateSchema(...).success` as a boolean recogniser. Printing issues behind a
+*negative* recognition would flood its report with diagnoses of non-ObjectUI files, the
+failure objectui#5127 and objectui#6075 exist to prevent.
+
+Nothing about which documents are ACCEPTED changes — this is diagnostic output only.

content/docs/utilities/cli.mdx

@@ -158,6 +158,37 @@ objectui validate app.json
 objectui validate ./schemas/dashboard.yaml
 ```
 
+#### Reading a failure
+
+A document is checked against a union of every component type, so a failure is
+reported first at the document root and then narrowed to the arm your `type`
+selected. Each numbered issue carries a path and a code; the `1.1`-style entries
+beneath it are that arm's own diagnosis, with the real path to the node that
+failed:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ 1.1 RETIRED (objectui#6523) — dividers are `{ separator: true }`; …
+ Path: items → 0 → type
+ Code: invalid_type
+```
+
+Only the selected arm is shown. When your `type` matches no component at all,
+the report says so and offers the nearest few of the accepted values instead:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ No arm accepts type "dropdwn-menu".
+ Nearest of the 108 accepted types: dropdown-menu, context-menu, component, drawer, breadcrumb
+```
+
+A document with no `type` at all is reported the same way, without a candidate
+list — there is nothing for the suggestions to be near.
+
 ### `objectui check`
 
 Scan the project for ObjectUI schema files and report on the ones it

packages/cli/README.md

@@ -117,6 +117,13 @@ Add a new component renderer to your project.
 
 Validate a schema file against the ObjectUI specification.
 
+A failure is reported at the document root and then narrowed to the union arm
+your `type` selected — the `1.1`-style entries under a numbered issue are that
+arm's own diagnosis, at the real path of the node that failed. When no component
+type matches, the report names the nearest few of the accepted values instead of
+listing all of them. See the
+[docs](https://www.objectui.org/docs/utilities/cli) for worked output.
+
 ### `objectui check`, `objectui doctor`, `objectui studio`, `objectui analyze`, `objectui create plugin <name>`
 
 Utility commands — see `objectui --help`.

packages/cli/src/__tests__/validate-root-path-line.test.ts

@@ -9,6 +9,11 @@
 /**
  * `objectui validate` and the ROOT-LEVEL issue (objectui#7004, mechanical half).
  *
+ * The arm-selection half of the same card landed later, on the 2026-09-02
+ * ruling; its contract lives in `validate-union-arm-selection.test.ts`. The last
+ * describe block here was the boundary pin that made that landing an explicit
+ * edit, and now restates the new semantics from this file's point of view.
+ *
  * The printer used to guard its Path line with `issue.path.length > 0`, so an
  * issue at the document root (`path: []`) printed no Path line at all — silent
  * in precisely the case a reader most needs oriented.
@@ -181,27 +186,40 @@ describe('objectui validate — a real path is still a real path', () => {
  });
 });
 
-describe('objectui validate — the arm-selection half is deliberately NOT done here', () => {
+describe('objectui validate — the arm-selection half, now that it is ruled', () => {
  /**
- * ⚠️ This case pins a BOUNDARY, not a desired end state. objectui#7004 splits
- * into the root-path line (done, above) and the question of whether a failing
- * union should also surface its per-arm diagnoses — and if so, which arm's.
- * The second is an author-facing diagnostic contract and is awaiting a
- * maintainer ruling, so this file records that the printer walks only the
- * top level today.
+ * ⚠️ This case USED to pin the opposite. It was written as a deliberate
+ * boundary: while the arm-selection question was with the maintainer, it
+ * asserted that the printer walked only the top level — `not.toContain
+ * ('RETIRED (objectui#6523)')`, `not.toContain('Path: items')` — so that when
+ * the ruling landed it would land as an explicit edit against a RED test
+ * rather than as a silent widening.
+ *
+ * The 2026-09-02 ruling landed (option B: the arm the document's `type`
+ * selects, nothing from the others), so the boundary moved and these
+ * assertions are inverted. That is the mechanism working, not a test being
+ * loosened: the pin forced this file to be opened and the semantics restated
+ * by hand.
  *
- * When that ruling lands, this case is EXPECTED to change with it. It exists
- * so the change is a deliberate edit rather than a silent widening.
+ * The full contract lives in `validate-union-arm-selection.test.ts`. What
+ * stays HERE is the part this file has always been about — that widening the
+ * printer did not cost the root-path line, and did not turn one top-level
+ * issue into many.
  */
- it('prints one top-level entry for a union, not the per-arm remediation text', async () => {
+ it('surfaces the selected arm\'s diagnosis without multiplying top-level entries', async () => {
  await validate(writeSchema('menu.json', MENU_WITH_RETIRED_DIVIDER));
 
  const text = printed();
- // The arm issues carry the objectui#6523 tombstone guidance. Nothing here
- // reads `issue.errors`, so none of it is printed.
- expect(text).not.toContain('RETIRED (objectui#6523)');
- expect(text).not.toContain('Path: items');
- // Exactly one numbered issue — an arm walk would multiply this.
+ // Was `not.toContain` until the ruling. The objectui#6523 tombstone text
+ // rides the per-arm issues, which is exactly why it never reached an author.
+ expect(text).toContain('RETIRED (objectui#6523)');
+ expect(text).toContain('Path: items → 0 → type');
+ // Unchanged, and load-bearing: the top-level entry still carries the root
+ // path line this file exists for.
+ expect(text).toContain('Path: (root)');
+ // Still exactly one NUMBERED issue. Arm entries are `1.1`-shaped, so a
+ // reader (and this assertion) can still count the top-level failures — an
+ // arm walk that emitted them as `2.`, `3.` … would have multiplied this.
  const numbered = printed()
  .split('\n')
  .filter((line) => /^\d+\. /.test(line.trim()));

.changeset/7004-cli-union-arm-selection.md

@@ -0,0 +1,39 @@
+---
+'@object-ui/cli': minor
+---
+
+`objectui validate` now prints the failing union arm the document selected, instead of a
+bare "Invalid input" (objectui#7004, maintainer ruling 2026-09-02 — option B).
+
+`safeValidateSchema` checks a document against `AnyComponentSchema`, a `z.union`. When a
+document matches no arm, Zod reports ONE top-level issue — `invalid_union` · `Invalid
+input` · path `(root)` — and hangs every arm's real diagnosis off that issue's `errors`
+array, which nothing read. So a menu whose item used the divider spelling retired in
+objectui#6523 printed a bare verdict on the whole document, while the remediation text
+objectui#6931 wrote into that arm sat one level down, unreachable.
+
+**What is printed now.** When the top-level issue is a failing union:
+
+- the document's `type` selects exactly one arm ⇒ that arm's issues are printed beneath
+ the entry as `1.1`, `1.2` … with their real paths (`Path: items → 0 → type`) and codes,
+ and **nothing** from the other arms;
+- no arm accepts the `type` ⇒ `No arm accepts type "dropdwn-menu".` plus the nearest few
+ of the accepted values, ranked by edit distance and **capped** at five
+ (`MAX_UNION_ARMS_REPORTED`);
+- the document declares no `type` at all ⇒ the note says so and offers no candidates —
+ "nearest" needs something to be near, and an alphabetical slice of 108 arm names
+ presented as guidance would be a bogus suggestion;
+- a union with no `type` discriminator to select on — `MenuItemSchema`, whose two arms
+ both declare `type` as an ADR-0049 retirement tombstone — reports every arm, labelled
+ and capped by the same constant. This is the path that finally delivers the
+ objectui#6523 text to the author.
+
+Printing EVERY arm was rejected in the ruling: `AnyComponentSchema` resolves to 108 leaf
+arms, so one mistyped `type` would have produced hundreds of lines.
+
+`objectui check` is unchanged and deliberately so: it has no zod-issue printer, using
+`safeValidateSchema(...).success` as a boolean recogniser. Printing issues behind a
+*negative* recognition would flood its report with diagnoses of non-ObjectUI files, the
+failure objectui#5127 and objectui#6075 exist to prevent.
+
+Nothing about which documents are ACCEPTED changes — this is diagnostic output only.

content/docs/utilities/cli.mdx

@@ -158,6 +158,37 @@ objectui validate app.json
 objectui validate ./schemas/dashboard.yaml
 ```
 
+#### Reading a failure
+
+A document is checked against a union of every component type, so a failure is
+reported first at the document root and then narrowed to the arm your `type`
+selected. Each numbered issue carries a path and a code; the `1.1`-style entries
+beneath it are that arm's own diagnosis, with the real path to the node that
+failed:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ 1.1 RETIRED (objectui#6523) — dividers are `{ separator: true }`; …
+ Path: items → 0 → type
+ Code: invalid_type
+```
+
+Only the selected arm is shown. When your `type` matches no component at all,
+the report says so and offers the nearest few of the accepted values instead:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ No arm accepts type "dropdwn-menu".
+ Nearest of the 108 accepted types: dropdown-menu, context-menu, component, drawer, breadcrumb
+```
+
+A document with no `type` at all is reported the same way, without a candidate
+list — there is nothing for the suggestions to be near.
+
 ### `objectui check`
 
 Scan the project for ObjectUI schema files and report on the ones it

packages/cli/README.md

@@ -117,6 +117,13 @@ Add a new component renderer to your project.
 
 Validate a schema file against the ObjectUI specification.
 
+A failure is reported at the document root and then narrowed to the union arm
+your `type` selected — the `1.1`-style entries under a numbered issue are that
+arm's own diagnosis, at the real path of the node that failed. When no component
+type matches, the report names the nearest few of the accepted values instead of
+listing all of them. See the
+[docs](https://www.objectui.org/docs/utilities/cli) for worked output.
+
 ### `objectui check`, `objectui doctor`, `objectui studio`, `objectui analyze`, `objectui create plugin <name>`
 
 Utility commands — see `objectui --help`.

packages/cli/src/__tests__/validate-root-path-line.test.ts

@@ -9,6 +9,11 @@
 /**
  * `objectui validate` and the ROOT-LEVEL issue (objectui#7004, mechanical half).
  *
+ * The arm-selection half of the same card landed later, on the 2026-09-02
+ * ruling; its contract lives in `validate-union-arm-selection.test.ts`. The last
+ * describe block here was the boundary pin that made that landing an explicit
+ * edit, and now restates the new semantics from this file's point of view.
+ *
  * The printer used to guard its Path line with `issue.path.length > 0`, so an
  * issue at the document root (`path: []`) printed no Path line at all — silent
  * in precisely the case a reader most needs oriented.
@@ -181,27 +186,40 @@ describe('objectui validate — a real path is still a real path', () => {
  });
 });
 
-describe('objectui validate — the arm-selection half is deliberately NOT done here', () => {
+describe('objectui validate — the arm-selection half, now that it is ruled', () => {
  /**
- * ⚠️ This case pins a BOUNDARY, not a desired end state. objectui#7004 splits
- * into the root-path line (done, above) and the question of whether a failing
- * union should also surface its per-arm diagnoses — and if so, which arm's.
- * The second is an author-facing diagnostic contract and is awaiting a
- * maintainer ruling, so this file records that the printer walks only the
- * top level today.
+ * ⚠️ This case USED to pin the opposite. It was written as a deliberate
+ * boundary: while the arm-selection question was with the maintainer, it
+ * asserted that the printer walked only the top level — `not.toContain
+ * ('RETIRED (objectui#6523)')`, `not.toContain('Path: items')` — so that when
+ * the ruling landed it would land as an explicit edit against a RED test
+ * rather than as a silent widening.
+ *
+ * The 2026-09-02 ruling landed (option B: the arm the document's `type`
+ * selects, nothing from the others), so the boundary moved and these
+ * assertions are inverted. That is the mechanism working, not a test being
+ * loosened: the pin forced this file to be opened and the semantics restated
+ * by hand.
  *
- * When that ruling lands, this case is EXPECTED to change with it. It exists
- * so the change is a deliberate edit rather than a silent widening.
+ * The full contract lives in `validate-union-arm-selection.test.ts`. What
+ * stays HERE is the part this file has always been about — that widening the
+ * printer did not cost the root-path line, and did not turn one top-level
+ * issue into many.
  */
- it('prints one top-level entry for a union, not the per-arm remediation text', async () => {
+ it('surfaces the selected arm\'s diagnosis without multiplying top-level entries', async () => {
  await validate(writeSchema('menu.json', MENU_WITH_RETIRED_DIVIDER));
 
  const text = printed();
- // The arm issues carry the objectui#6523 tombstone guidance. Nothing here
- // reads `issue.errors`, so none of it is printed.
- expect(text).not.toContain('RETIRED (objectui#6523)');
- expect(text).not.toContain('Path: items');
- // Exactly one numbered issue — an arm walk would multiply this.
+ // Was `not.toContain` until the ruling. The objectui#6523 tombstone text
+ // rides the per-arm issues, which is exactly why it never reached an author.
+ expect(text).toContain('RETIRED (objectui#6523)');
+ expect(text).toContain('Path: items → 0 → type');
+ // Unchanged, and load-bearing: the top-level entry still carries the root
+ // path line this file exists for.
+ expect(text).toContain('Path: (root)');
+ // Still exactly one NUMBERED issue. Arm entries are `1.1`-shaped, so a
+ // reader (and this assertion) can still count the top-level failures — an
+ // arm walk that emitted them as `2.`, `3.` … would have multiplied this.
  const numbered = printed()
  .split('\n')
  .filter((line) => /^\d+\. /.test(line.trim()));

.changeset/7004-cli-union-arm-selection.md

@@ -0,0 +1,39 @@
+---
+'@object-ui/cli': minor
+---
+
+`objectui validate` now prints the failing union arm the document selected, instead of a
+bare "Invalid input" (objectui#7004, maintainer ruling 2026-09-02 — option B).
+
+`safeValidateSchema` checks a document against `AnyComponentSchema`, a `z.union`. When a
+document matches no arm, Zod reports ONE top-level issue — `invalid_union` · `Invalid
+input` · path `(root)` — and hangs every arm's real diagnosis off that issue's `errors`
+array, which nothing read. So a menu whose item used the divider spelling retired in
+objectui#6523 printed a bare verdict on the whole document, while the remediation text
+objectui#6931 wrote into that arm sat one level down, unreachable.
+
+**What is printed now.** When the top-level issue is a failing union:
+
+- the document's `type` selects exactly one arm ⇒ that arm's issues are printed beneath
+ the entry as `1.1`, `1.2` … with their real paths (`Path: items → 0 → type`) and codes,
+ and **nothing** from the other arms;
+- no arm accepts the `type` ⇒ `No arm accepts type "dropdwn-menu".` plus the nearest few
+ of the accepted values, ranked by edit distance and **capped** at five
+ (`MAX_UNION_ARMS_REPORTED`);
+- the document declares no `type` at all ⇒ the note says so and offers no candidates —
+ "nearest" needs something to be near, and an alphabetical slice of 108 arm names
+ presented as guidance would be a bogus suggestion;
+- a union with no `type` discriminator to select on — `MenuItemSchema`, whose two arms
+ both declare `type` as an ADR-0049 retirement tombstone — reports every arm, labelled
+ and capped by the same constant. This is the path that finally delivers the
+ objectui#6523 text to the author.
+
+Printing EVERY arm was rejected in the ruling: `AnyComponentSchema` resolves to 108 leaf
+arms, so one mistyped `type` would have produced hundreds of lines.
+
+`objectui check` is unchanged and deliberately so: it has no zod-issue printer, using
+`safeValidateSchema(...).success` as a boolean recogniser. Printing issues behind a
+*negative* recognition would flood its report with diagnoses of non-ObjectUI files, the
+failure objectui#5127 and objectui#6075 exist to prevent.
+
+Nothing about which documents are ACCEPTED changes — this is diagnostic output only.

content/docs/utilities/cli.mdx

@@ -158,6 +158,37 @@ objectui validate app.json
 objectui validate ./schemas/dashboard.yaml
 ```
 
+#### Reading a failure
+
+A document is checked against a union of every component type, so a failure is
+reported first at the document root and then narrowed to the arm your `type`
+selected. Each numbered issue carries a path and a code; the `1.1`-style entries
+beneath it are that arm's own diagnosis, with the real path to the node that
+failed:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ 1.1 RETIRED (objectui#6523) — dividers are `{ separator: true }`; …
+ Path: items → 0 → type
+ Code: invalid_type
+```
+
+Only the selected arm is shown. When your `type` matches no component at all,
+the report says so and offers the nearest few of the accepted values instead:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ No arm accepts type "dropdwn-menu".
+ Nearest of the 108 accepted types: dropdown-menu, context-menu, component, drawer, breadcrumb
+```
+
+A document with no `type` at all is reported the same way, without a candidate
+list — there is nothing for the suggestions to be near.
+
 ### `objectui check`
 
 Scan the project for ObjectUI schema files and report on the ones it

packages/cli/README.md

@@ -117,6 +117,13 @@ Add a new component renderer to your project.
 
 Validate a schema file against the ObjectUI specification.
 
+A failure is reported at the document root and then narrowed to the union arm
+your `type` selected — the `1.1`-style entries under a numbered issue are that
+arm's own diagnosis, at the real path of the node that failed. When no component
+type matches, the report names the nearest few of the accepted values instead of
+listing all of them. See the
+[docs](https://www.objectui.org/docs/utilities/cli) for worked output.
+
 ### `objectui check`, `objectui doctor`, `objectui studio`, `objectui analyze`, `objectui create plugin <name>`
 
 Utility commands — see `objectui --help`.

packages/cli/src/__tests__/validate-root-path-line.test.ts

@@ -9,6 +9,11 @@
 /**
  * `objectui validate` and the ROOT-LEVEL issue (objectui#7004, mechanical half).
  *
+ * The arm-selection half of the same card landed later, on the 2026-09-02
+ * ruling; its contract lives in `validate-union-arm-selection.test.ts`. The last
+ * describe block here was the boundary pin that made that landing an explicit
+ * edit, and now restates the new semantics from this file's point of view.
+ *
  * The printer used to guard its Path line with `issue.path.length > 0`, so an
  * issue at the document root (`path: []`) printed no Path line at all — silent
  * in precisely the case a reader most needs oriented.
@@ -181,27 +186,40 @@ describe('objectui validate — a real path is still a real path', () => {
  });
 });
 
-describe('objectui validate — the arm-selection half is deliberately NOT done here', () => {
+describe('objectui validate — the arm-selection half, now that it is ruled', () => {
  /**
- * ⚠️ This case pins a BOUNDARY, not a desired end state. objectui#7004 splits
- * into the root-path line (done, above) and the question of whether a failing
- * union should also surface its per-arm diagnoses — and if so, which arm's.
- * The second is an author-facing diagnostic contract and is awaiting a
- * maintainer ruling, so this file records that the printer walks only the
- * top level today.
+ * ⚠️ This case USED to pin the opposite. It was written as a deliberate
+ * boundary: while the arm-selection question was with the maintainer, it
+ * asserted that the printer walked only the top level — `not.toContain
+ * ('RETIRED (objectui#6523)')`, `not.toContain('Path: items')` — so that when
+ * the ruling landed it would land as an explicit edit against a RED test
+ * rather than as a silent widening.
+ *
+ * The 2026-09-02 ruling landed (option B: the arm the document's `type`
+ * selects, nothing from the others), so the boundary moved and these
+ * assertions are inverted. That is the mechanism working, not a test being
+ * loosened: the pin forced this file to be opened and the semantics restated
+ * by hand.
  *
- * When that ruling lands, this case is EXPECTED to change with it. It exists
- * so the change is a deliberate edit rather than a silent widening.
+ * The full contract lives in `validate-union-arm-selection.test.ts`. What
+ * stays HERE is the part this file has always been about — that widening the
+ * printer did not cost the root-path line, and did not turn one top-level
+ * issue into many.
  */
- it('prints one top-level entry for a union, not the per-arm remediation text', async () => {
+ it('surfaces the selected arm\'s diagnosis without multiplying top-level entries', async () => {
  await validate(writeSchema('menu.json', MENU_WITH_RETIRED_DIVIDER));
 
  const text = printed();
- // The arm issues carry the objectui#6523 tombstone guidance. Nothing here
- // reads `issue.errors`, so none of it is printed.
- expect(text).not.toContain('RETIRED (objectui#6523)');
- expect(text).not.toContain('Path: items');
- // Exactly one numbered issue — an arm walk would multiply this.
+ // Was `not.toContain` until the ruling. The objectui#6523 tombstone text
+ // rides the per-arm issues, which is exactly why it never reached an author.
+ expect(text).toContain('RETIRED (objectui#6523)');
+ expect(text).toContain('Path: items → 0 → type');
+ // Unchanged, and load-bearing: the top-level entry still carries the root
+ // path line this file exists for.
+ expect(text).toContain('Path: (root)');
+ // Still exactly one NUMBERED issue. Arm entries are `1.1`-shaped, so a
+ // reader (and this assertion) can still count the top-level failures — an
+ // arm walk that emitted them as `2.`, `3.` … would have multiplied this.
  const numbered = printed()
  .split('\n')
  .filter((line) => /^\d+\. /.test(line.trim()));

.changeset/7004-cli-union-arm-selection.md

@@ -0,0 +1,39 @@
+---
+'@object-ui/cli': minor
+---
+
+`objectui validate` now prints the failing union arm the document selected, instead of a
+bare "Invalid input" (objectui#7004, maintainer ruling 2026-09-02 — option B).
+
+`safeValidateSchema` checks a document against `AnyComponentSchema`, a `z.union`. When a
+document matches no arm, Zod reports ONE top-level issue — `invalid_union` · `Invalid
+input` · path `(root)` — and hangs every arm's real diagnosis off that issue's `errors`
+array, which nothing read. So a menu whose item used the divider spelling retired in
+objectui#6523 printed a bare verdict on the whole document, while the remediation text
+objectui#6931 wrote into that arm sat one level down, unreachable.
+
+**What is printed now.** When the top-level issue is a failing union:
+
+- the document's `type` selects exactly one arm ⇒ that arm's issues are printed beneath
+ the entry as `1.1`, `1.2` … with their real paths (`Path: items → 0 → type`) and codes,
+ and **nothing** from the other arms;
+- no arm accepts the `type` ⇒ `No arm accepts type "dropdwn-menu".` plus the nearest few
+ of the accepted values, ranked by edit distance and **capped** at five
+ (`MAX_UNION_ARMS_REPORTED`);
+- the document declares no `type` at all ⇒ the note says so and offers no candidates —
+ "nearest" needs something to be near, and an alphabetical slice of 108 arm names
+ presented as guidance would be a bogus suggestion;
+- a union with no `type` discriminator to select on — `MenuItemSchema`, whose two arms
+ both declare `type` as an ADR-0049 retirement tombstone — reports every arm, labelled
+ and capped by the same constant. This is the path that finally delivers the
+ objectui#6523 text to the author.
+
+Printing EVERY arm was rejected in the ruling: `AnyComponentSchema` resolves to 108 leaf
+arms, so one mistyped `type` would have produced hundreds of lines.
+
+`objectui check` is unchanged and deliberately so: it has no zod-issue printer, using
+`safeValidateSchema(...).success` as a boolean recogniser. Printing issues behind a
+*negative* recognition would flood its report with diagnoses of non-ObjectUI files, the
+failure objectui#5127 and objectui#6075 exist to prevent.
+
+Nothing about which documents are ACCEPTED changes — this is diagnostic output only.

content/docs/utilities/cli.mdx

@@ -158,6 +158,37 @@ objectui validate app.json
 objectui validate ./schemas/dashboard.yaml
 ```
 
+#### Reading a failure
+
+A document is checked against a union of every component type, so a failure is
+reported first at the document root and then narrowed to the arm your `type`
+selected. Each numbered issue carries a path and a code; the `1.1`-style entries
+beneath it are that arm's own diagnosis, with the real path to the node that
+failed:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ 1.1 RETIRED (objectui#6523) — dividers are `{ separator: true }`; …
+ Path: items → 0 → type
+ Code: invalid_type
+```
+
+Only the selected arm is shown. When your `type` matches no component at all,
+the report says so and offers the nearest few of the accepted values instead:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ No arm accepts type "dropdwn-menu".
+ Nearest of the 108 accepted types: dropdown-menu, context-menu, component, drawer, breadcrumb
+```
+
+A document with no `type` at all is reported the same way, without a candidate
+list — there is nothing for the suggestions to be near.
+
 ### `objectui check`
 
 Scan the project for ObjectUI schema files and report on the ones it

packages/cli/README.md

@@ -117,6 +117,13 @@ Add a new component renderer to your project.
 
 Validate a schema file against the ObjectUI specification.
 
+A failure is reported at the document root and then narrowed to the union arm
+your `type` selected — the `1.1`-style entries under a numbered issue are that
+arm's own diagnosis, at the real path of the node that failed. When no component
+type matches, the report names the nearest few of the accepted values instead of
+listing all of them. See the
+[docs](https://www.objectui.org/docs/utilities/cli) for worked output.
+
 ### `objectui check`, `objectui doctor`, `objectui studio`, `objectui analyze`, `objectui create plugin <name>`
 
 Utility commands — see `objectui --help`.

packages/cli/src/__tests__/validate-root-path-line.test.ts

@@ -9,6 +9,11 @@
 /**
  * `objectui validate` and the ROOT-LEVEL issue (objectui#7004, mechanical half).
  *
+ * The arm-selection half of the same card landed later, on the 2026-09-02
+ * ruling; its contract lives in `validate-union-arm-selection.test.ts`. The last
+ * describe block here was the boundary pin that made that landing an explicit
+ * edit, and now restates the new semantics from this file's point of view.
+ *
  * The printer used to guard its Path line with `issue.path.length > 0`, so an
  * issue at the document root (`path: []`) printed no Path line at all — silent
  * in precisely the case a reader most needs oriented.
@@ -181,27 +186,40 @@ describe('objectui validate — a real path is still a real path', () => {
  });
 });
 
-describe('objectui validate — the arm-selection half is deliberately NOT done here', () => {
+describe('objectui validate — the arm-selection half, now that it is ruled', () => {
  /**
- * ⚠️ This case pins a BOUNDARY, not a desired end state. objectui#7004 splits
- * into the root-path line (done, above) and the question of whether a failing
- * union should also surface its per-arm diagnoses — and if so, which arm's.
- * The second is an author-facing diagnostic contract and is awaiting a
- * maintainer ruling, so this file records that the printer walks only the
- * top level today.
+ * ⚠️ This case USED to pin the opposite. It was written as a deliberate
+ * boundary: while the arm-selection question was with the maintainer, it
+ * asserted that the printer walked only the top level — `not.toContain
+ * ('RETIRED (objectui#6523)')`, `not.toContain('Path: items')` — so that when
+ * the ruling landed it would land as an explicit edit against a RED test
+ * rather than as a silent widening.
+ *
+ * The 2026-09-02 ruling landed (option B: the arm the document's `type`
+ * selects, nothing from the others), so the boundary moved and these
+ * assertions are inverted. That is the mechanism working, not a test being
+ * loosened: the pin forced this file to be opened and the semantics restated
+ * by hand.
  *
- * When that ruling lands, this case is EXPECTED to change with it. It exists
- * so the change is a deliberate edit rather than a silent widening.
+ * The full contract lives in `validate-union-arm-selection.test.ts`. What
+ * stays HERE is the part this file has always been about — that widening the
+ * printer did not cost the root-path line, and did not turn one top-level
+ * issue into many.
  */
- it('prints one top-level entry for a union, not the per-arm remediation text', async () => {
+ it('surfaces the selected arm\'s diagnosis without multiplying top-level entries', async () => {
  await validate(writeSchema('menu.json', MENU_WITH_RETIRED_DIVIDER));
 
  const text = printed();
- // The arm issues carry the objectui#6523 tombstone guidance. Nothing here
- // reads `issue.errors`, so none of it is printed.
- expect(text).not.toContain('RETIRED (objectui#6523)');
- expect(text).not.toContain('Path: items');
- // Exactly one numbered issue — an arm walk would multiply this.
+ // Was `not.toContain` until the ruling. The objectui#6523 tombstone text
+ // rides the per-arm issues, which is exactly why it never reached an author.
+ expect(text).toContain('RETIRED (objectui#6523)');
+ expect(text).toContain('Path: items → 0 → type');
+ // Unchanged, and load-bearing: the top-level entry still carries the root
+ // path line this file exists for.
+ expect(text).toContain('Path: (root)');
+ // Still exactly one NUMBERED issue. Arm entries are `1.1`-shaped, so a
+ // reader (and this assertion) can still count the top-level failures — an
+ // arm walk that emitted them as `2.`, `3.` … would have multiplied this.
  const numbered = printed()
  .split('\n')
  .filter((line) => /^\d+\. /.test(line.trim()));

.changeset/7004-cli-union-arm-selection.md

@@ -0,0 +1,39 @@
+---
+'@object-ui/cli': minor
+---
+
+`objectui validate` now prints the failing union arm the document selected, instead of a
+bare "Invalid input" (objectui#7004, maintainer ruling 2026-09-02 — option B).
+
+`safeValidateSchema` checks a document against `AnyComponentSchema`, a `z.union`. When a
+document matches no arm, Zod reports ONE top-level issue — `invalid_union` · `Invalid
+input` · path `(root)` — and hangs every arm's real diagnosis off that issue's `errors`
+array, which nothing read. So a menu whose item used the divider spelling retired in
+objectui#6523 printed a bare verdict on the whole document, while the remediation text
+objectui#6931 wrote into that arm sat one level down, unreachable.
+
+**What is printed now.** When the top-level issue is a failing union:
+
+- the document's `type` selects exactly one arm ⇒ that arm's issues are printed beneath
+ the entry as `1.1`, `1.2` … with their real paths (`Path: items → 0 → type`) and codes,
+ and **nothing** from the other arms;
+- no arm accepts the `type` ⇒ `No arm accepts type "dropdwn-menu".` plus the nearest few
+ of the accepted values, ranked by edit distance and **capped** at five
+ (`MAX_UNION_ARMS_REPORTED`);
+- the document declares no `type` at all ⇒ the note says so and offers no candidates —
+ "nearest" needs something to be near, and an alphabetical slice of 108 arm names
+ presented as guidance would be a bogus suggestion;
+- a union with no `type` discriminator to select on — `MenuItemSchema`, whose two arms
+ both declare `type` as an ADR-0049 retirement tombstone — reports every arm, labelled
+ and capped by the same constant. This is the path that finally delivers the
+ objectui#6523 text to the author.
+
+Printing EVERY arm was rejected in the ruling: `AnyComponentSchema` resolves to 108 leaf
+arms, so one mistyped `type` would have produced hundreds of lines.
+
+`objectui check` is unchanged and deliberately so: it has no zod-issue printer, using
+`safeValidateSchema(...).success` as a boolean recogniser. Printing issues behind a
+*negative* recognition would flood its report with diagnoses of non-ObjectUI files, the
+failure objectui#5127 and objectui#6075 exist to prevent.
+
+Nothing about which documents are ACCEPTED changes — this is diagnostic output only.

content/docs/utilities/cli.mdx

@@ -158,6 +158,37 @@ objectui validate app.json
 objectui validate ./schemas/dashboard.yaml
 ```
 
+#### Reading a failure
+
+A document is checked against a union of every component type, so a failure is
+reported first at the document root and then narrowed to the arm your `type`
+selected. Each numbered issue carries a path and a code; the `1.1`-style entries
+beneath it are that arm's own diagnosis, with the real path to the node that
+failed:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ 1.1 RETIRED (objectui#6523) — dividers are `{ separator: true }`; …
+ Path: items → 0 → type
+ Code: invalid_type
+```
+
+Only the selected arm is shown. When your `type` matches no component at all,
+the report says so and offers the nearest few of the accepted values instead:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ No arm accepts type "dropdwn-menu".
+ Nearest of the 108 accepted types: dropdown-menu, context-menu, component, drawer, breadcrumb
+```
+
+A document with no `type` at all is reported the same way, without a candidate
+list — there is nothing for the suggestions to be near.
+
 ### `objectui check`
 
 Scan the project for ObjectUI schema files and report on the ones it

packages/cli/README.md

@@ -117,6 +117,13 @@ Add a new component renderer to your project.
 
 Validate a schema file against the ObjectUI specification.
 
+A failure is reported at the document root and then narrowed to the union arm
+your `type` selected — the `1.1`-style entries under a numbered issue are that
+arm's own diagnosis, at the real path of the node that failed. When no component
+type matches, the report names the nearest few of the accepted values instead of
+listing all of them. See the
+[docs](https://www.objectui.org/docs/utilities/cli) for worked output.
+
 ### `objectui check`, `objectui doctor`, `objectui studio`, `objectui analyze`, `objectui create plugin <name>`
 
 Utility commands — see `objectui --help`.

packages/cli/src/__tests__/validate-root-path-line.test.ts

@@ -9,6 +9,11 @@
 /**
  * `objectui validate` and the ROOT-LEVEL issue (objectui#7004, mechanical half).
  *
+ * The arm-selection half of the same card landed later, on the 2026-09-02
+ * ruling; its contract lives in `validate-union-arm-selection.test.ts`. The last
+ * describe block here was the boundary pin that made that landing an explicit
+ * edit, and now restates the new semantics from this file's point of view.
+ *
  * The printer used to guard its Path line with `issue.path.length > 0`, so an
  * issue at the document root (`path: []`) printed no Path line at all — silent
  * in precisely the case a reader most needs oriented.
@@ -181,27 +186,40 @@ describe('objectui validate — a real path is still a real path', () => {
  });
 });
 
-describe('objectui validate — the arm-selection half is deliberately NOT done here', () => {
+describe('objectui validate — the arm-selection half, now that it is ruled', () => {
  /**
- * ⚠️ This case pins a BOUNDARY, not a desired end state. objectui#7004 splits
- * into the root-path line (done, above) and the question of whether a failing
- * union should also surface its per-arm diagnoses — and if so, which arm's.
- * The second is an author-facing diagnostic contract and is awaiting a
- * maintainer ruling, so this file records that the printer walks only the
- * top level today.
+ * ⚠️ This case USED to pin the opposite. It was written as a deliberate
+ * boundary: while the arm-selection question was with the maintainer, it
+ * asserted that the printer walked only the top level — `not.toContain
+ * ('RETIRED (objectui#6523)')`, `not.toContain('Path: items')` — so that when
+ * the ruling landed it would land as an explicit edit against a RED test
+ * rather than as a silent widening.
+ *
+ * The 2026-09-02 ruling landed (option B: the arm the document's `type`
+ * selects, nothing from the others), so the boundary moved and these
+ * assertions are inverted. That is the mechanism working, not a test being
+ * loosened: the pin forced this file to be opened and the semantics restated
+ * by hand.
  *
- * When that ruling lands, this case is EXPECTED to change with it. It exists
- * so the change is a deliberate edit rather than a silent widening.
+ * The full contract lives in `validate-union-arm-selection.test.ts`. What
+ * stays HERE is the part this file has always been about — that widening the
+ * printer did not cost the root-path line, and did not turn one top-level
+ * issue into many.
  */
- it('prints one top-level entry for a union, not the per-arm remediation text', async () => {
+ it('surfaces the selected arm\'s diagnosis without multiplying top-level entries', async () => {
  await validate(writeSchema('menu.json', MENU_WITH_RETIRED_DIVIDER));
 
  const text = printed();
- // The arm issues carry the objectui#6523 tombstone guidance. Nothing here
- // reads `issue.errors`, so none of it is printed.
- expect(text).not.toContain('RETIRED (objectui#6523)');
- expect(text).not.toContain('Path: items');
- // Exactly one numbered issue — an arm walk would multiply this.
+ // Was `not.toContain` until the ruling. The objectui#6523 tombstone text
+ // rides the per-arm issues, which is exactly why it never reached an author.
+ expect(text).toContain('RETIRED (objectui#6523)');
+ expect(text).toContain('Path: items → 0 → type');
+ // Unchanged, and load-bearing: the top-level entry still carries the root
+ // path line this file exists for.
+ expect(text).toContain('Path: (root)');
+ // Still exactly one NUMBERED issue. Arm entries are `1.1`-shaped, so a
+ // reader (and this assertion) can still count the top-level failures — an
+ // arm walk that emitted them as `2.`, `3.` … would have multiplied this.
  const numbered = printed()
  .split('\n')
  .filter((line) => /^\d+\. /.test(line.trim()));

.changeset/7004-cli-union-arm-selection.md

@@ -0,0 +1,39 @@
+---
+'@object-ui/cli': minor
+---
+
+`objectui validate` now prints the failing union arm the document selected, instead of a
+bare "Invalid input" (objectui#7004, maintainer ruling 2026-09-02 — option B).
+
+`safeValidateSchema` checks a document against `AnyComponentSchema`, a `z.union`. When a
+document matches no arm, Zod reports ONE top-level issue — `invalid_union` · `Invalid
+input` · path `(root)` — and hangs every arm's real diagnosis off that issue's `errors`
+array, which nothing read. So a menu whose item used the divider spelling retired in
+objectui#6523 printed a bare verdict on the whole document, while the remediation text
+objectui#6931 wrote into that arm sat one level down, unreachable.
+
+**What is printed now.** When the top-level issue is a failing union:
+
+- the document's `type` selects exactly one arm ⇒ that arm's issues are printed beneath
+ the entry as `1.1`, `1.2` … with their real paths (`Path: items → 0 → type`) and codes,
+ and **nothing** from the other arms;
+- no arm accepts the `type` ⇒ `No arm accepts type "dropdwn-menu".` plus the nearest few
+ of the accepted values, ranked by edit distance and **capped** at five
+ (`MAX_UNION_ARMS_REPORTED`);
+- the document declares no `type` at all ⇒ the note says so and offers no candidates —
+ "nearest" needs something to be near, and an alphabetical slice of 108 arm names
+ presented as guidance would be a bogus suggestion;
+- a union with no `type` discriminator to select on — `MenuItemSchema`, whose two arms
+ both declare `type` as an ADR-0049 retirement tombstone — reports every arm, labelled
+ and capped by the same constant. This is the path that finally delivers the
+ objectui#6523 text to the author.
+
+Printing EVERY arm was rejected in the ruling: `AnyComponentSchema` resolves to 108 leaf
+arms, so one mistyped `type` would have produced hundreds of lines.
+
+`objectui check` is unchanged and deliberately so: it has no zod-issue printer, using
+`safeValidateSchema(...).success` as a boolean recogniser. Printing issues behind a
+*negative* recognition would flood its report with diagnoses of non-ObjectUI files, the
+failure objectui#5127 and objectui#6075 exist to prevent.
+
+Nothing about which documents are ACCEPTED changes — this is diagnostic output only.

content/docs/utilities/cli.mdx

@@ -158,6 +158,37 @@ objectui validate app.json
 objectui validate ./schemas/dashboard.yaml
 ```
 
+#### Reading a failure
+
+A document is checked against a union of every component type, so a failure is
+reported first at the document root and then narrowed to the arm your `type`
+selected. Each numbered issue carries a path and a code; the `1.1`-style entries
+beneath it are that arm's own diagnosis, with the real path to the node that
+failed:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ 1.1 RETIRED (objectui#6523) — dividers are `{ separator: true }`; …
+ Path: items → 0 → type
+ Code: invalid_type
+```
+
+Only the selected arm is shown. When your `type` matches no component at all,
+the report says so and offers the nearest few of the accepted values instead:
+
+```text
+1. Invalid input
+ Path: (root)
+ Code: invalid_union
+ No arm accepts type "dropdwn-menu".
+ Nearest of the 108 accepted types: dropdown-menu, context-menu, component, drawer, breadcrumb
+```
+
+A document with no `type` at all is reported the same way, without a candidate
+list — there is nothing for the suggestions to be near.
+
 ### `objectui check`
 
 Scan the project for ObjectUI schema files and report on the ones it

packages/cli/README.md

@@ -117,6 +117,13 @@ Add a new component renderer to your project.
 
 Validate a schema file against the ObjectUI specification.
 
+A failure is reported at the document root and then narrowed to the union arm
+your `type` selected — the `1.1`-style entries under a numbered issue are that
+arm's own diagnosis, at the real path of the node that failed. When no component
+type matches, the report names the nearest few of the accepted values instead of
+listing all of them. See the
+[docs](https://www.objectui.org/docs/utilities/cli) for worked output.
+
 ### `objectui check`, `objectui doctor`, `objectui studio`, `objectui analyze`, `objectui create plugin <name>`
 
 Utility commands — see `objectui --help`.

packages/cli/src/__tests__/validate-root-path-line.test.ts

@@ -9,6 +9,11 @@
 /**
  * `objectui validate` and the ROOT-LEVEL issue (objectui#7004, mechanical half).
  *
+ * The arm-selection half of the same card landed later, on the 2026-09-02
+ * ruling; its contract lives in `validate-union-arm-selection.test.ts`. The last
+ * describe block here was the boundary pin that made that landing an explicit
+ * edit, and now restates the new semantics from this file's point of view.
+ *
  * The printer used to guard its Path line with `issue.path.length > 0`, so an
  * issue at the document root (`path: []`) printed no Path line at all — silent
  * in precisely the case a reader most needs oriented.
@@ -181,27 +186,40 @@ describe('objectui validate — a real path is still a real path', () => {
  });
 });
 
-describe('objectui validate — the arm-selection half is deliberately NOT done here', () => {
+describe('objectui validate — the arm-selection half, now that it is ruled', () => {
  /**
- * ⚠️ This case pins a BOUNDARY, not a desired end state. objectui#7004 splits
- * into the root-path line (done, above) and the question of whether a failing
- * union should also surface its per-arm diagnoses — and if so, which arm's.
- * The second is an author-facing diagnostic contract and is awaiting a
- * maintainer ruling, so this file records that the printer walks only the
- * top level today.
+ * ⚠️ This case USED to pin the opposite. It was written as a deliberate
+ * boundary: while the arm-selection question was with the maintainer, it
+ * asserted that the printer walked only the top level — `not.toContain
+ * ('RETIRED (objectui#6523)')`, `not.toContain('Path: items')` — so that when
+ * the ruling landed it would land as an explicit edit against a RED test
+ * rather than as a silent widening.
+ *
+ * The 2026-09-02 ruling landed (option B: the arm the document's `type`
+ * selects, nothing from the others), so the boundary moved and these
+ * assertions are inverted. That is the mechanism working, not a test being
+ * loosened: the pin forced this file to be opened and the semantics restated
+ * by hand.
  *
- * When that ruling lands, this case is EXPECTED to change with it. It exists
- * so the change is a deliberate edit rather than a silent widening.
+ * The full contract lives in `validate-union-arm-selection.test.ts`. What
+ * stays HERE is the part this file has always been about — that widening the
+ * printer did not cost the root-path line, and did not turn one top-level
+ * issue into many.
  */
- it('prints one top-level entry for a union, not the per-arm remediation text', async () => {
+ it('surfaces the selected arm\'s diagnosis without multiplying top-level entries', async () => {
  await validate(writeSchema('menu.json', MENU_WITH_RETIRED_DIVIDER));
 
  const text = printed();
- // The arm issues carry the objectui#6523 tombstone guidance. Nothing here
- // reads `issue.errors`, so none of it is printed.
- expect(text).not.toContain('RETIRED (objectui#6523)');
- expect(text).not.toContain('Path: items');
- // Exactly one numbered issue — an arm walk would multiply this.
+ // Was `not.toContain` until the ruling. The objectui#6523 tombstone text
+ // rides the per-arm issues, which is exactly why it never reached an author.
+ expect(text).toContain('RETIRED (objectui#6523)');
+ expect(text).toContain('Path: items → 0 → type');
+ // Unchanged, and load-bearing: the top-level entry still carries the root
+ // path line this file exists for.
+ expect(text).toContain('Path: (root)');
+ // Still exactly one NUMBERED issue. Arm entries are `1.1`-shaped, so a
+ // reader (and this assertion) can still count the top-level failures — an
+ // arm walk that emitted them as `2.`, `3.` … would have multiplied this.
  const numbered = printed()
  .split('\n')
  .filter((line) => /^\d+\. /.test(line.trim()));