fix(ci): unblock main — integration-test pom versions + regenerate metamodel-docs

fixtures/metamodel-docs/expected/types/field.md

@@ -46,6 +46,8 @@ True/false flag. Binds to the native boolean type; DB column is BOOLEAN.
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** A true/false flag.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -78,6 +80,8 @@ Stores money as integer minor units (cents). Binds to long; the client formats v
 
 **Rules:** Storage is integer minor units (cents for USD, yen for JPY) — the wire form is unchanged from long. The server never formats currency; all formatting is client-side via Intl.NumberFormat using @currency (ISO 4217) and @locale (BCP 47). Float arithmetic for money is forbidden.
 
+**When to use:** A column holds money. Use currency so it stores integer minor-units and the client formats it — never floats or hand-rolled cents math.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -109,6 +113,8 @@ Calendar date (no time-of-day). Binds to the native date/temporal type; DB colum
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** A column is a calendar date with no time-of-day. Use date instead of a string.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -142,6 +148,8 @@ Precision-exact decimal (use @precision/@scale). Native TS binding is string (lo
 
 **Rules:** The wire and native-TS form is a STRING to stay precision-exact end-to-end (Drizzle pg numeric infers as string; SP-H/ADR-0019). Set @precision (total significant digits) and @scale (digits right of the point) to drive NUMERIC(p,s).
 
+**When to use:** A value needs exact precision (money amounts, rates, quantities). Use decimal with @precision/@scale — never double, which loses precision.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -174,6 +182,8 @@ Double-precision (64-bit) IEEE-754 floating point. Binds to the native double/nu
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** An approximate floating-point number where exactness is not required. For money/precision use decimal.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -206,6 +216,8 @@ String-backed enumeration constrained to a closed set of member symbols (@values
 
 **Rules:** Required @values is a non-empty, duplicate-free set; each member must match ^[A-Za-z_][A-Za-z0-9_]*$ so symbol == stored string in every target language. Optional FR-010/FR-011 overlays add tolerant-extract aliasing (@enumAlias), per-member docs (@enumDoc), an uncoercible-value fallback (@coerceDefault, must be one of @values), and ASCII normalization mode (@normalize).
 
+**When to use:** A field is a fixed, closed set of string values. Set @values so the union type, DB CHECK, and validation are generated — don't hand-roll constants + checks.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -272,6 +284,8 @@ Single-precision floating point. Binds to the native double/number type (TS has
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** A whole number within +/-2^31. Use long instead if values can exceed that.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -302,6 +316,8 @@ Single-precision floating point. Binds to the native double/number type (TS has
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** A whole number that may exceed 32 bits (ids, counters, epoch millis).
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -334,6 +350,8 @@ An open-keyed map (Record<string,V> / dict[str,V]) stored in a single jsonb colu
 
 **Rules:** Keys are always strings. Set exactly one of @valueType (a scalar value subtype: string/int/long/double/float/decimal/boolean/date/time/timestamp/uuid) or @objectRef (a value-object name or FQN). Stored as a single jsonb column holding the JSON object — never a native array; isArray does not apply.
 
+**When to use:** A field is an open-keyed map of values (Record<string,V>). Use it for dynamic keys instead of an untyped jsonb string.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -368,6 +386,8 @@ A nested structured value (set @objectRef to the target object). Storage is gove
 
 **Rules:** Set @objectRef to the nested object's name (or FQN). @storage selects physical layout — flattened expands into prefixed parent columns (isArray must be false), jsonb stores the structured value (or array when isArray=true) in one jsonb column, subdocument emits no Postgres column. Defaults to single-jsonb-column when @storage is absent.
 
+**When to use:** A field holds a nested structured value (or an array of them). Set @objectRef + @storage so the shape is typed and persisted (flattened/jsonb) instead of an untyped blob.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -400,6 +420,8 @@ Variable-length text. Binds to the native string type; DB column is VARCHAR/TEXT
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** Plain variable-length text. Set @maxLength to size the column. The default for textual data.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -462,6 +484,8 @@ Date + time-of-day instant (optionally with timezone). Binds to the native date/
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** A column records an instant (created/updated at). Use timestamp so it serializes ISO-8601 with timezone consistently.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -493,6 +517,8 @@ Logical UUID identity scalar. A bare scalar (no required attrs, no loader value-
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** A key or external identifier is a UUID. Use it for a typed UUID column instead of a plain string.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |

fixtures/metamodel-docs/expected/types/identity.md

@@ -16,6 +16,8 @@ The primary key — one per entity; @fields names its column(s), @generation the
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** Every entity needs exactly one — names the primary-key field(s) and how the value is generated. Always declare it.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -33,6 +35,8 @@ A foreign-key reference to another entity (@references target; @enforce toggles
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** This entity holds a foreign key to another. Declare it to generate the FK constraint + typed navigation, instead of a loose id field you join on by hand.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -52,6 +56,8 @@ A secondary index (unique by default via @unique).
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** A column or set must be unique, or you want an index for lookups/sorting. Declare it instead of a hand-written UNIQUE constraint or CREATE INDEX.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |

fixtures/metamodel-docs/expected/types/object.md

@@ -36,6 +36,8 @@ An object that owns its data: own identity, writable sources, and lifecycle. The
 
 **Rules:** object.entity owns data — it declares its own identity, its primary source must be a writable @kind (read-only kinds may appear only in a read role), and it carries lifecycle. A field carrying origin.* is derived ⇒ read-only wherever it lives, including on an entity. Templates (template.*) may be nested so a prompt can be co-located with its owning entity. See ADR-0028 (object taxonomy).
 
+**When to use:** The thing owns its own data and lifecycle — a table you create/read/update/delete. The default for any persisted resource.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -61,6 +63,8 @@ A derived read-only representation of entities. Its fields are extends-bound / o
 
 **Rules:** object.projection is a derived read-only representation: every field is extends-bound, origin-derived, or self-declared-under-external-assembly, and all are read-only at the subtype level. Identity is optional and, when present, MUST extend an entity identity. Sources are restricted to read-only @kinds. The declared field set IS the exposure — an inclusive list, fail-closed. A projection NEVER declares relationships (derivation is expressed via @via, not a relationship child) and NEVER co-locates templates — hence its child set omits both relationship and template. See ADR-0028 (object taxonomy, projection).
 
+**When to use:** You need a derived, read-only view over entities — a report, summary, or joined/aggregated read model. Declare it (with origin.* children) instead of hand-writing the SELECT/joins; it stays read-only and regenerates.
+
 **Attributes**
 
 _No subtype-specific attributes._
@@ -81,6 +85,8 @@ A value object — pure shape with NO identity and NO source, ever. Constructed
 
 **Rules:** object.value is pure shape: it NEVER declares an identity and NEVER declares a source, in any role. It is constructed — by a caller, by assembly, or by embedding — and is never populated from a backing store. It may `extends` an entity's fields to reuse their shape. @normalize is the object-level default ASCII normalization mode applied to this value's enum fields' tolerant extract (each field may still override per-field). See ADR-0028 (object taxonomy, value purity).
 
+**When to use:** You need a reusable typed shape with NO identity and NO table — an embedded value, a DTO, a prompt/response payload. Constructed in memory, never persisted on its own.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |

fixtures/metamodel-docs/expected/types/origin.md

@@ -18,6 +18,8 @@ A count/sum/avg/min/max (@agg) computed over a column (@of) reached along a rela
 
 **Rules:** @via may be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (single-hop-unique inference; FR-024, ADR-0029). Multi-hop paths must always be stated explicitly.
 
+**When to use:** A projection needs a derived count/sum/avg/min/max over related rows. Declare it instead of hand-writing the aggregate query — it stays consistent and regenerates.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -50,6 +52,8 @@ A relationship-derived array of nested view-objects: walks @via to produce the c
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** A projection needs an array of nested child view-objects (a parent with its children inline). Declare it instead of hand-assembling the nested query + mapping.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -66,6 +70,8 @@ A cross-entity field reference: this projection field passes a source entity's v
 
 **Owning provider:** metaobjects-core-types
 
+**When to use:** A projection field just surfaces a field from a related entity. Declare the cross-entity passthrough instead of re-joining and re-selecting it by hand.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |

fixtures/metamodel-docs/expected/types/relationship.md

@@ -18,6 +18,8 @@ A shared/independent containment — the parent groups the target but does not o
 
 **Rules:** M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Aggregation is shared/independent — the target outlives the parent (default @onDelete set-null).
 
+**When to use:** One entity groups others it does NOT own (children outlive the parent; delete sets the FK null). Use instead of composition when there is no ownership.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -42,6 +44,8 @@ A plain reference to another entity — no ownership; the target has an independ
 
 **Rules:** M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Association is a plain reference — the target's lifecycle is independent (default @onDelete restrict).
 
+**When to use:** A plain directed reference to another entity, no ownership or cascade. The lightest link — when you just need to point at another entity.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -90,6 +94,8 @@ An owned containment — the parent owns the target's lifecycle; deleting the pa
 
 **Rules:** M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Composition is owned lifecycle — the children do not outlive the parent (default @onDelete cascade).
 
+**When to use:** You need a parent that OWNS a child collection (one-to-many, cascade on delete). Declare it to generate the FK + typed navigation instead of a bare FK field + hand-written joins.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |

fixtures/metamodel-docs/expected/types/source.md

@@ -32,6 +32,8 @@ The relational-database paradigm source (ADR-0007): binds an object to a physica
 
 **Rules:** ADR-0007: source declares where an object's data lives; rdb is the relational paradigm subtype. An object may declare multiple sources, distinguished by @role, with exactly ONE @role: "primary" per object (write-through CQRS: a writable table for writes plus a read-only view for reads). The physical name is the @table attr (or the @kind-matching alias), never the structural `name`. Read-only-ness is derived from @kind (table → writable; view / materializedView / storedProc / tableFunction → read-only). The pre-v2 dbTable / dbView subtypes are retired.
 
+**When to use:** The entity is backed by a relational table or view. Set @table/@kind — the default persistence source for any entity.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |

fixtures/metamodel-docs/expected/types/template.md

@@ -34,6 +34,8 @@ An output / serialization template (FR-004): every rendered artifact other than
 
 **Rules:** output is either a document (@kind="document" or absent → renders @textRef in @format to one string) or an email (@kind="email" → renders subject + html + optional text to a structured EmailDocument). The cross-field presence rule is enforced in the loader's validateTemplatePayloadRefs pass: document requires @textRef; email requires @subjectRef AND @htmlBodyRef (with @textBodyRef optional) and carries NO @textRef. @format is a closed enum keyed by the render engine's escaper; @promptStyle (FR-010) selects the output-format prompt presentation and is never emitted as comments.
 
+**When to use:** You render a document/email/serialized output from typed data. Declare an output template so the {{fields}} are drift-checked against the payload VO at build time.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
@@ -63,6 +65,8 @@ An LLM-targeted renderable prompt template (FR-004). Carries the generic referen
 
 **Rules:** prompt requires @payloadRef (the typed payload it renders against) AND @textRef (the body text, provider-resolved at render time — enforced in the loader's validateTemplatePayloadRefs pass, not at the attr layer where @textRef is relaxed to optional so template.output email can omit it). @format is a closed enum keyed by the render engine's escaper. @responseRef (optional) names the response value-object the prompt expects and drives typed LLM-call trace derivation.
 
+**When to use:** You are sending text to an LLM. Declare a prompt template with a typed payload so the prompt is versioned, drift-checked against its fields, and cache-stable — instead of string-building it in code.
+
 **Attributes**
 
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |