Consolidate D&D entity documentation

docs/integrations/dnd-item-occurrence-artifacts.md

@@ -14,9 +14,11 @@ inventory, balance, or ledger.
 | Schema version | `v1` |
 | Media type | `application/json` |
 
-The strict root has required `occurrences`. Records require `item_id`, `name`,
-`kind`, and `source_refs`; unknown fields are rejected. `quantity`, `from`, and
-`to` appear only when their kind permits them.
+`v1` accepts one strict JSON object with required `occurrences`; the array may
+be empty. Each occurrence has required `item_id`, `name`, `kind`, and
+`source_refs`, and occurrence and source-reference objects reject unknown
+fields. `quantity`, `from`, and `to` appear only when their kind permits them.
+An incompatible shape change requires a new schema version.
 
 ## Registry grounding
 
@@ -33,6 +35,10 @@ pairs.
 
 ## Wire shape
 
+Each source reference has exactly `source_id`, `start_unit_id`, and
+`end_unit_id`. It identifies an inclusive range in the current transcript;
+unit IDs are positive and the start may not follow the end.
+
 ```json
 {
   "occurrences": [
@@ -54,7 +60,10 @@ The five kinds remain `discovered`, `acquired`, `lost`, `consumed`, and
 `transferred`. Holder, quantity, currency, ordering, and exact-duplicate rules
 are unchanged: discovered has no holder; acquired requires `to`; lost and
 consumed require `from`; transferred requires distinct non-`party` holders.
-Each source reference is an inclusive current-transcript range.
+The only current downstream compatibility requirement is its registry handoff;
+the normalized occurrence list is otherwise published for callers. See
+[Configuration](../config.md#d-d-reference-slots) for the binding and
+[JSON output](json-output.md) for publication.
 
 See [item registry](dnd-item-registry-artifacts.md) for the grounding artifact
 and [D&D module internals](../internal/dnd.md) for implementation details.

docs/integrations/dnd-item-registry-artifacts.md

@@ -78,9 +78,14 @@ result with retry or fallback diagnostics. Currency denominations, materially
 different item types, and merely nearby objects remain distinct. Source
 references establish registry provenance, not evidence for later artifacts.
 
-## Publication
+## Consumers and publication
 
-The registry is a selectable D&D artifact. See
-[Configuration](../config.md#production-module-keys) for module keys and
-validator chains, and the [JSON output contract](json-output.md) for
-publication. It does not yet define a consumer handoff contract.
+`dnd/item-occurrences` requires one approved item registry through its
+`item_registry` reference slot for both extraction and normalization. Its
+consumer receives only an ordered, source-free `{id,name}` projection; the
+registry’s source references are never occurrence evidence. Unknown IDs and
+mismatched pairs are rejected by the occurrence contract. See the
+[item-occurrence artifact](dnd-item-occurrence-artifacts.md) for that strict
+wire contract, [Configuration](../config.md#d-d-reference-slots) for binding
+rules and validator selection, and the [JSON output contract](json-output.md)
+for publication.

docs/integrations/dnd-npc-registry-artifacts.md

@@ -76,7 +76,10 @@ occurrence.
 This registry can ground actor or caster names in the [spell](dnd-spell-artifacts.md)
 and [combat-turn](dnd-combat-turn-artifacts.md) artifacts. It is required to
 resolve the canonical `name` in an [NPC occurrence](dnd-npc-occurrence-artifacts.md).
-The [enemy-event artifact](dnd-enemy-event-artifacts.md) also uses it only for
-subject grounding and canonical display names.
+Occurrence consumers receive an ordered source-free `{id,name}` projection;
+spells, combat turns, and the [enemy-event artifact](dnd-enemy-event-artifacts.md)
+receive names-only grounding for actor or subject display. None of these
+projections supply later-artifact evidence. [Configuration](../config.md#d-d-reference-slots)
+owns the `npc_registry` binding rules.
 The [JSON output contract](json-output.md) defines publication, and
 [D&D module internals](../internal/dnd.md) owns pipeline mechanics.

docs/integrations/json-output.md

@@ -74,8 +74,9 @@ than infer a lane schema from its name. The current D&D payload contracts are
 [spells](dnd-spell-artifacts.md), [NPC registry](dnd-npc-registry-artifacts.md),
 [NPC occurrences](dnd-npc-occurrence-artifacts.md),
 [combat turns](dnd-combat-turn-artifacts.md),
+[item registry](dnd-item-registry-artifacts.md),
 [item occurrences](dnd-item-occurrence-artifacts.md),
-[scene descriptions](dnd-scene-description-artifacts.md), and
+[scene descriptions](dnd-scene-description-artifacts.md),
 [enemy events](dnd-enemy-event-artifacts.md),
 [location registry](dnd-location-registry-artifacts.md), and
 [location occurrences](dnd-location-occurrence-artifacts.md).