docs(skills): document the action and component nav item types

[claude]

Fixes #13890

The published skills/objectstack-ui "Navigation Item Types" table listed 7 of the 9 live
NavItemVariant members: action and component had no row, in a section whose heading
names the catalog and whose other seven rows are present — so an AI author reading it
could not reach either variant.

Part of #13658. The objectstack twin of the fix the objectui sweep landed in that repo's
skills/objectui/guides/app-composition.md; the rows here are written in this table's own
Type | Properties | Purpose idiom rather than copied.

Member set, verified against the schema

The live set is read out of the schema at runtime — hand the discriminated union a bogus
type and print the options it names, rather than trusting the card's "9" or the
NavItemVariant type alias:

DISCRIMINATOR OPTIONS (from the schema): ["object","dashboard","page","url","report","action","component","separator","group"]
COUNT: 9
ISSUE: invalid_union | Invalid discriminator value. Expected 'object' | 'dashboard' | 'page' | 'url' | 'report' | 'action' | 'component' | 'separator' | 'group'

Nine members; the two absent from the table are exactly action and component.
packages/spec/src/ui/app.zod.ts backs each row: ActionNavItemSchema requires
actionDef, itself a strict object of actionName plus an optional open params;
ComponentNavItemSchema requires componentRef (a ComponentRegistry key such as
metadata:resource) with an optional open params passed to the component as props.
Neither variant accepts children — NAV_VARIANTS_ACCEPTING_CHILDREN is object and
group only — so neither row lists it.

pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/ui/app.test.ts —
102 passed (1 file), including the pin that parses all nine variants with their full
declared payloads.

Rows added

| `action`    | `actionDef` (`{ actionName, params? }`), `label`, `icon` | Run an action instead of navigating |
| `component` | `componentRef`, `params?`, `label`, `icon`    | Built-in platform component; `componentRef` is a colon-joined registry key (`metadata:resource`), `params` become props |

Token budget — funded by deletion in the same file, no ceiling raise

The file sat at its ceiling with headroom 0, so the two rows are paid for by removing text,
not by moving a ceiling. Verdict lines from node scripts/check-skills-token-ratchet.mjs:

before: ✓ check-skills-token-ratchet: skills/objectstack-ui/SKILL.md is 25445 tokens (ceiling 25445; headroom 0).
after:  ✓ check-skills-token-ratchet: skills/objectstack-ui/SKILL.md is 25441 tokens (ceiling 25445; headroom 4).

Funding source — two Common Pitfalls entries deleted, neither of which carries a fact the
file does not state better elsewhere (a real deletion, not a re-wrap; the ceiling constant
is untouched):

• "Using provider: 'api' when provider: 'object' is available" — a strict subset of
  the Data Source best-practice block a thousand lines above, which is the richer of the two
  (it also names automatic CRUD).
• "Not setting quick filters … always add a 'My Records' filter" — superseded by the
  ADR-0047 userFilters section in the same file, which prescribes the opposite default:
  "Omit userFilters when unsure … most views need no filter elements at all." Keeping
  both left the skill teaching two contradictory defaults.

Required skills/** readings, lines and tokens (token unit is the ratchet's own
ceil(utf8 bytes / 4)):

Reading	Before	After	Delta
skills/objectstack-ui/SKILL.md, whole file — lines	2111	2105	-6
skills/objectstack-ui/SKILL.md, whole file — tokens	25445	25441	-4
Whole published package, all 11 SKILL.md — lines	10533	10527	-6
Whole published package, all 11 SKILL.md — tokens	118696	118692	-4

Both readings are net negative: the catalog gets two missing rows and gets shorter.

Ledger

scripts/check-skill-identifier-liveness.mjs records this gap in
scripts/skill-identifier-liveness-ledger.json under leg2Gaps.navigation-item-types, and
refuses an improvement that does not ratchet it down. Second commit does exactly that; the
gate now reports Leg 2: 9 registered exhaustive section(s), 0 ledgered gap(s).

Gates

Full derived union at HEAD c587bd7ff, from
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands run
against that same commit (21 commands over the 2 changed paths), plus check:nul-bytes.
Exit codes captured before any pipe. 21 green; one NOT MEASURED:

• node scripts/check-test-completeness.mjs exits 3 with no argument by design — it parses
  a saved turbo run test log, which a local family run has none of. Its own text says this
  is not a red and there is nothing here to fix.
• pnpm --filter @objectstack/lint run check:doc-formula-expressions first exited 3
  (PREREQUISITE NOT MET) because @objectstack/formula and @objectstack/lint were not
  built in this fresh worktree; after building both it exits 0 at the same HEAD.

No changeset: the diff publishes nothing from any package, so the PR carries
skip-changeset.

Landing

skills/** is a governed surface — this PR stays a draft and is merged by the
maintainer, by hand. No auto-merge, no queue.

Session: session_01Msg17tAHJ3jVTYFgHydCm2.

Generated by Claude Code

---

Generated by Claude Code