docs(spec): `navigationContributions[].group` describe() documents the omitted case but not the mis-aimed one

[hotlong]

Found while implementing the #14553 diagnostic (PR #14920). Filing rather than fixing there — see "Why not in that PR" below. Not blocked by anything; #14553 remains open on its own terms and is not addressed by this card.

What is missing

packages/spec/src/ui/app.zod.ts:764 is the authoring-time description for the key:

group: SnakeCaseIdentifierSchema.optional().describe(
  'Target group nav-item id to append into (e.g. "group_integrations"); omit to append at the app top level'),

That sentence is true and incomplete. It documents what happens when group is omitted. It says nothing about what happens when group is present and names no group in the target app — which is the case that actually bites, because:

• the contributing package cannot see the target app's group ids at authoring time (the target app belongs to another package), so a wrong id is not detectable by reading the contributor's own source;
• the platform relocates the items to the app's top level rather than refusing or dropping them, so the menu renders and a smoke test passes while the information architecture has changed.

Since PR #14920 that relocation emits a nav_contribution_group_missing diagnostic at warn and os build reports it at compile time — but the describe() string, which is what an AI author reads first and what the generated reference renders, still only covers the omitted case.

Where it surfaces

That one string feeds the generated reference rows an author actually reads:

• content/docs/references/kernel/manifest.mdx (the group row)
• content/docs/references/ui/app.mdx (same row)
• packages/spec/json-schema/ui/NavigationContribution.json, plus ~11 json-schema/api/*.json package-envelope schemas that embed it

Suggested shape

Extend the describe() to name the third case — something like: naming a group the target app does not declare is not refused; the items are appended at the app's top level and a nav_contribution_group_missing diagnostic is emitted. Then regenerate with the repo's own tooling (never hand-edit the generated artifacts).

Why not in PR #14920

It fails the bounded-in-place-fix test on the "no new verification surface" condition: the edit is in packages/spec, and that one string is embedded in ~14 generated artifacts, so it pulls the spec regeneration family (gen:schema / check:authorable-surface) into a PR whose scope is an objectql/cli diagnostic — while two sibling PRs are churning nearby spec files. The wording is also a judgement call rather than a mechanical repair, so it wants its own review.

Confirmed not already filed: a targeted search over this repo returned only #14553 itself and an unrelated CLICommandContributionSchema card.

[hotlong]

Accuracy update after #14920 landed its final shape — this card is not falsified, but one sentence in the body is now incomplete.

The body says "Since PR #14920 that relocation emits a nav_contribution_group_missing diagnostic at warn and os build reports it at compile time". Two corrections to what actually shipped:

• os validate reports it too, not only os build. The --json payload of os build is deliberately closed (pinned by build-json-advisory-parity.e2e.test.ts and build-json-undeclared-key-parity.e2e.test.ts), so the finding fills the existing warnings key rather than adding one — and a third pin in that file requires that nothing rides in build's warnings that validate does not also report. Both commands compute the list.
• An earlier draft of that PR carried a top-level navigationGroupDiagnostics key. It does not exist; if you saw it referenced anywhere, that reference is stale.

Nothing here changes what this card asks for: the describe() on packages/spec/src/ui/app.zod.ts still documents only the omitted case, and the suggested shape in the body still applies as written — with the small addition that the third case is now visible from os validate as well as os build.

---

Generated by Claude Code