docs: document identity.primary singleton default-naming (FR-024 friction)

The loader now names a name-less identity.primary "primary" (config-driven singleton
default), so the minimal `{ "identity.primary": { "@fields": "id" } }` form loads — no
more copy-paste trap. Document this in entities.md (the singleton rule + the
ERR_TOO_MANY_OCCURRENCES guard) and the metamodel spec (the generic maxOccurs/defaultName
mechanism). Existing no-name examples throughout the docs are now correct as-is.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

docs/features/entities.md

@@ -76,6 +76,13 @@ YAML is desugared to canonical JSON at load time. See
 | `identity.secondary` | Unique secondary index. | No. |
 | `identity.reference` | Inbound FK from this entity to another. | No. |
 
+> **`identity.primary` is a singleton — its name is optional.** An entity may carry
+> at most one `identity.primary`; the loader names a name-less one `"primary"`
+> automatically (so `{ "identity.primary": { "@fields": "id" } }` is the canonical
+> minimal form — no need to invent a name). Declaring two primaries on one entity is
+> an `ERR_TOO_MANY_OCCURRENCES` load error. `identity.secondary` / `identity.reference`
+> are not singletons and DO require an explicit `name`.
+
 ## `extends:` for shared abstract bases
 
 Common base fields (`id`, `createdAt`, `updatedAt`) live on an abstract entity that

spec/metamodel.md

@@ -42,5 +42,14 @@ Inside each node body, the **reserved structural keys** are exactly:
 Everything else inside a body is an `@`-prefixed attribute (e.g. `@column`, `@currency`,
 `@fields`). `@`-attrs appear in alphabetical order in the canonical form.
 
+**Singleton default-naming.** A type may declare itself a singleton (`maxOccurs: 1`)
+with a `defaultName`. A name-less node of such a type is named from `defaultName` by
+the loader and serialized with that name; a second occurrence under the same parent is
+an `ERR_TOO_MANY_OCCURRENCES` error. `identity.primary` is the canonical case
+(`defaultName: "primary"`), so `{ "identity.primary": { "@fields": "id" } }` is a
+complete, loadable node — the name is optional. This is a generic registry rule, not a
+per-type loader special-case, and is gated cross-port by the
+`identity-primary-default-name` / `error-too-many-primary` conformance fixtures.
+
 See `typescript/packages/metadata/src/constants.ts` for the canonical vocabulary
 (type names, subtype names, structural keys, separators).