docs(api): teach the singular /meta/:type spelling as the canonical one (#10078)

[os-elon]

Part of #10078 — the docs half only. The SDK half stopped at the card's own trip-wire; the measurement is below.

What changed

content/docs/api/metadata-api.mdx — the GET /meta/:type parameter row and the paragraph under it. It taught the plural as a co-equal address:

Metadata type name, singular or plural — object and objects address the same type
Both spellings are accepted and behave identically … so both forms exist in the wild.

It now teaches the singular as the spelling, and explains why the plurals elsewhere in this API (a collection of records, a manifest key) do not carry across to a /meta type segment.

Per the 2026-08-17 re-weigh of the #9180 ruling (comment 5311434183), verbatim and untranslated: 「② 照原样做；只需要修正 objectstack objectui cloud 中错误的写法。」 Step ③ is internal spelling correction only.

⛔ The boundary fold is untouched and stays undocumented. Nothing here changes what the API accepts or refuses. The page stops advertising a tolerance; the tolerance itself is exactly as it was, and this PR adds no promise about it in either direction.

Why the SDK half (site 1) is not in this PR

The card's trip-wire, verbatim: "If any slice of your diff turns out to change what a request is answered with (not merely what we emit or teach), STOP and report the fork — that slice belongs at the claude-fable-5 floor and is not this card."

Site 1 asked the client SDK's variable-typed item routes to normalize toward singular. Measured on this branch, folding the emitted :type segment does change what a request is answered with — and, on the write door, where a row lands. The REST /meta doors decide the organization scope from the raw URL spelling (organizationIdForMetaRead / organizationIdForMetaWrite, whose declaresOrgOverride folds through the manifest map PLURAL_TO_SINGULAR), while the protocol boundary folds through the complete URL map. For two spellings the two maps disagree:

spelling in URL map protocol fold REST org READ REST org WRITE
object false object undefined undefined
objects true object undefined undefined
view false view org_1 org_1
views true view org_1 org_1
translation false translation org_1 org_1
translations true translation undefined undefined
email_template false email_template org_1 org_1
email_templates true email_template undefined undefined
emailTemplates true email_template org_1 org_1

Executed against the built @objectstack/metadata-core and @objectstack/spec/meta-spelling on this branch, not read off the source.

So an SDK that normalized translations to translation before emitting would move an org-active caller from the env-wide row to the org-scoped row on reads, and would land a saveItem on an org-scoped row where it lands env-wide today. That is the accept/serve half of the boundary, not the emit half — the trip-wire's stop condition exactly. Filed separately as a defect in its own right (it is the #7894 class one layer down: the plural is a door around the singular's gate) and reported to the PM for re-tiering.

Two things follow, and both are deliberate:

• No fold, no partial fold. Folding only the spellings that happen to agree would fossilize the server's disagreement into the client — a second dialect, which Prime Directive Add comprehensive test suite for Zod schema validation #12 forbids.
• The remaining "tighten the typing" route needs a change outside this card's file surface. A closed union of type names is wrong (plugin-registered types are extensible, and narrowing a published string parameter is a public-surface break). A conditional type that rejects only a literal plural argument would be right-shaped and would emit no runtime bytes at all, but it needs META_URL_TO_SINGULAR to expose literal key types — a packages/spec change, outside the claim's declared surface, and a hand-copied key list in the client would violate the derived-never-hand-written rule the map exists to enforce.

Also measured and left alone: GET /meta/:type/:name/published falls back to svc.getPublished(type, name) with the raw segment after its layered lookup misses, and listDrafts deliberately applies no fold (it matches the draft row's stored type). Both are named in the filed defect.

Not touched

• Two docs/skill sites still teach the plural /meta/objects/:name/state/:field, which step ② of #9180 retires #10178's two sites — content/docs/protocol/objectql/state-machine.mdx:126 and skills/objectstack-automation/SKILL.md:281. The docs sweep reached both; skills/** is a governed surface and cannot ride a normal PR, and the sub-issue owns them. Stopped at the boundary.
• content/docs/releases/** — release-owned, read-only. Release pages naming the plural stay as they are.
• packages/client/src/index.ts — getLegalNextStates already spells the segment object after Retire the plural /meta/objects/:name/state/:field registration: SDK moves to the singular twin, the collision's registration-order pin is deleted (step ② of the #9180 ruling) #10077; nothing here re-touches it.

Gates

Re-derived with node scripts/pm/dispatch-gates.mjs (no path arguments) against the real change set at 88c09c986, and every family it named was run. All green, quoting each gate's own verdict line:

gate	verdict
check:cross-package-test-inputs	OK: 12 package(s) read outside themselves, all declared
check:doc-anchors	252 internal #fragment link(s) across 399 source file(s) all resolve to a real heading
check:docs-audit-scope	docs-accuracy-audit scope is in sync with content/docs/: 180 hand-written doc(s)
check:docs-redirects	OK (apps/docs/redirects.mjs: 92 entries …)
check:published-readme-links	152 outbound link(s) across 60 published markdown file(s)
check:role-word	OK, no new occurrences of the reserved word
spec check:empty-state	all classified (1 closed, 2 open, 4 output, 9 scope)
spec check:liveness	every governed-type property … is classified
spec check:strictness-ledger	61 file(s) across 5 triaged director(ies)
spec check:variant-docs	18 discriminated union(s) — 8 governed, 10 exempt
node scripts/check-cross-package-test-inputs.mjs	OK: 12 package(s) read outside themselves
check:slot-lookup (named at dispatch, not by the re-derivation)	ratchet holds: 107 unswept site(s) in 25 file(s), none new
scripts/docs-audit/check-affected-docs.mjs (same)	exit 0

The re-derivation named no family the dispatch brief had not, and named two fewer (check:slot-lookup, check-affected-docs.mjs) because the diff no longer touches packages/**; both were run anyway.

pnpm lint — narrowed, and the narrowing provably excludes nothing. eslint's configured population in eslint.config.mjs is **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}; this PR's one changed file is .mdx. Run directly at the file, eslint answers File ignored because no matching configuration was supplied. (--format json, one result, errorCount: 0) — so the repo-wide run can produce no finding attributable to this diff. CI runs the full farm regardless.

No changeset: docs-only, releases nothing — skip-changeset.

---

Generated by Claude Code