Consolidate D&D entity documentation

README.md

@@ -2,9 +2,9 @@
 
 Notarius is a Go CLI for turning source material into structured artifacts with
 configured extraction pipelines. The implemented D&D workflow reads Seriatim
-transcript JSON and can produce location registries and occurrences, scene
+transcript JSON and can produce NPC, location, and item registries; their
-descriptions, item and currency events, NPC identities, combat turns, NPC
+source-grounded occurrences; scene descriptions, combat turns, enemy events,
-occurrences, enemy events, and spell casts.
+and spell casts.
 
 ## Quickstart
 

docs/config.md

@@ -298,7 +298,7 @@ output:
       enabled: true
       window_units: 3
       lanes:
-        - npc_registry
+        - npc-registry
         - spells
 ~~~
 
@@ -332,7 +332,7 @@ step:
 steps:
   - id: describe-session
     artifacts:
-      npc_registry:
+      npc-registry:
         extract: dnd/npc-registry
         normalize: dnd/npc-registry
   - id: extract-events
@@ -340,7 +340,7 @@ steps:
       npc_registry:
         artifact:
           step: describe-session
-          lane: npc_registry
+          lane: npc-registry
     artifacts:
       spells:
         extract: dnd/spells
@@ -371,14 +371,17 @@ selected target declares them:
 | **glossary** | Optional text campaign glossary. |
 | **spell_catalog** | Optional JSON spell-catalog overlay for spell extraction and normalization. See [spell-catalog overlays](integrations/dnd-spell-catalog-overlays.md). |
 | **location_registry** | Required normalized location registry for location-occurrence extraction and normalization. |
+| **item_registry** | Required normalized item registry for item-occurrence extraction and normalization. |
 | **npc_registry** | Normalized NPC registry. Optional for spells and combat turns; required for NPC occurrences and enemy-event extraction and normalization. |
 | **scene_descriptions** | Required normalized scene-description artifact for combat-turn and enemy-event extraction. |
 | **combat_turns** | Required normalized combat-turn artifact for enemy-event extraction. |
 | **npc_occurrences** | Required normalized NPC-occurrence artifact for enemy-event extraction. |
 
-Location-occurrence and enemy-event artifact slots have the following exact
+Registry-backed occurrence and enemy-event artifact slots have the following
-binding contracts. Durable semantics and wire shapes remain in their
+exact binding contracts. Durable semantics and wire shapes remain in their
-[location-occurrence](integrations/dnd-location-occurrence-artifacts.md) and
+[NPC occurrence](integrations/dnd-npc-occurrence-artifacts.md),
+[location occurrence](integrations/dnd-location-occurrence-artifacts.md),
+[item occurrence](integrations/dnd-item-occurrence-artifacts.md), and
 [enemy-event](integrations/dnd-enemy-event-artifacts.md) contracts.
 
 | Slot | Accepted artifact kind | Media type | Maximum size | Required stage |
@@ -388,13 +391,15 @@ binding contracts. Durable semantics and wire shapes remain in their
 | `combat_turns` | `dnd/combat-turn-list` | `application/json` | 1,048,576 bytes | extract only |
 | `npc_occurrences` | `dnd/npc-occurrence-list` | `application/json` | 1,048,576 bytes | extract only |
 | `location_registry` | `dnd/location-registry` | `application/json` | 1,048,576 bytes | location-occurrence extract and normalize |
+| `item_registry` | `dnd/item-registry` | `application/json` | 1,048,576 bytes | item-occurrence extract and normalize |
 
 Scene descriptions accept **party**, **players**, and **glossary**, but not
 **roster**. NPC occurrences require **npc_registry** for both extraction and
 normalization. Combat turns require **scene_descriptions** for extraction; the
 normalized combat-turn module may use optional **npc_registry**. Location occurrences
-require **location_registry** for extraction and normalization. Enemy-event extraction
+require **location_registry** for extraction and normalization. Item occurrences require
-requires all four of its JSON artifact slots; its normalizer requires **npc_registry**.
+**item_registry** for extraction and normalization. Enemy-event extraction requires all
+four of its JSON artifact slots; its normalizer requires **npc_registry**.
 The [complete example](../examples/dnd-complete.config.yml) shows the ordered
 generated bindings.
 
@@ -409,21 +414,21 @@ generated bindings.
 | Normalize | **noop**, **dnd/spells**, **dnd/npc-registry**, **dnd/combat-turns**, **dnd/item-occurrences**, **dnd/item-registry**, **dnd/npc-occurrences**, **dnd/scene-descriptions**, **dnd/enemy-events**, **dnd/location-registry**, **dnd/location-occurrences** |
 | Output | **json** |
 
-`dnd/location-registry` and `dnd/item-registry` extraction and normalization
+`dnd/scenes` and every D&D extractor are `llm_backed`. The
-are `llm_backed`; their normalizers may use the pipeline's selected LLM profile
+`dnd/npc-registry`, `dnd/location-registry`, and `dnd/item-registry`
-for bounded duplicate proposals. `dnd/location-occurrences` and
+normalizers are also `llm_backed` for bounded duplicate proposals; every other
-`dnd/item-occurrences` extraction are `llm_backed`, while their normalizers are
+D&D normalizer is `deterministic`. LLM-backed bindings use the effective
-`deterministic`. The complete example binds each registry in an earlier step
+[PromptKit profile](#promptkit-profiles). The complete example binds each
-before its occurrence consumer.
+registry in an earlier step before its occurrence consumer.
 
 The D&D artifact contracts define each emitted schema:
 [spells](integrations/dnd-spell-artifacts.md),
 [NPC registry](integrations/dnd-npc-registry-artifacts.md),
 [NPC occurrences](integrations/dnd-npc-occurrence-artifacts.md),
 [combat turns](integrations/dnd-combat-turn-artifacts.md),
-[item occurrences](integrations/dnd-item-occurrence-artifacts.md),
 [item registry](integrations/dnd-item-registry-artifacts.md),
-[scene descriptions](integrations/dnd-scene-description-artifacts.md), and
+[item occurrences](integrations/dnd-item-occurrence-artifacts.md),
+[scene descriptions](integrations/dnd-scene-description-artifacts.md),
 [enemy events](integrations/dnd-enemy-event-artifacts.md),
 [location registry](integrations/dnd-location-registry-artifacts.md), and
 [location occurrences](integrations/dnd-location-occurrence-artifacts.md).

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`,
+`v1` accepts one strict JSON object with required `occurrences`; the array may
-`kind`, and `source_refs`; unknown fields are rejected. `quantity`, `from`, and
+be empty. Each occurrence has required `item_id`, `name`, `kind`, and
-`to` appear only when their kind permits them.
+`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
+`dnd/item-occurrences` requires one approved item registry through its
-[Configuration](../config.md#production-module-keys) for module keys and
+`item_registry` reference slot for both extraction and normalization. Its
-validator chains, and the [JSON output contract](json-output.md) for
+consumer receives only an ordered, source-free `{id,name}` projection; the
-publication. It does not yet define a consumer handoff contract.
+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
+Occurrence consumers receive an ordered source-free `{id,name}` projection;
-subject grounding and canonical display names.
+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).

docs/internal/dnd.md

@@ -50,7 +50,10 @@ such as a catalog, registry, grounding projection, or candidate collection are
 local only when that module needs them. New extractor content uses its feature
 subtree, while families with both extraction and normalization content use their
 `extract` and `normalize` subtrees. Shared visual-provenance fragments use
-the `common-dnd-` prefix.
+the `common-dnd-` prefix. Production lane code belongs with its D&D codec,
+extractor, normalizer, and validator packages; registry projections and
+identity helpers remain in their owning entity packages rather than in a
+consumer lane.
 
 The owning module’s manifest is the source of truth for which local and shared
 assets are selected, their mount paths, their message order, cache controls,
@@ -83,7 +86,7 @@ source. Deployment profile selection is documented in
 
 The transcript assets have distinct consumers. Scene chunking consumes the
 complete-session `common-dnd-transcript-full.md`; extraction prompts consume
-the current-chunk `common-dnd-transcript-chunk.md`; and NPC and location
+the current-chunk `common-dnd-transcript-chunk.md`; and NPC, location, and item
 normalization consume `common-dnd-transcript-windows.md` alongside their
 candidate collections. Player, party, glossary, and compatible campaign
 references provide disambiguating context, not evidence. Reference material is
@@ -141,17 +144,16 @@ producer provenance; consumers resolve the handed-off artifact into an
 immutable, validated projection for each operation. External files are checked
 during preparation, while generated artifacts are resolved at the handoff.
 
-NPC registries are names-only grounding projections: they may canonicalize
+NPC, location, and item registries project ordered, source-free `{id, name}`
-actors for spells and combat turns and are required for NPC occurrences, but
+pairs to their respective occurrence extractors and normalizers. Exact ID/name
-they do not supply evidence. Scene-description registries are eligibility-only
+matching preserves every identity the registry recognizes, including same-name
-projections: they retain the current chunk’s classification data, not scene
+locations with distinct source anchors. The NPC registry additionally supplies
-prose or evidence, and exist to route combat extraction. Enemy-event extraction
+names-only actor grounding to spells, combat turns, and enemy events.
-also projects combat turns to `actor` and `turn_kind` and filters NPC
+Scene descriptions are eligibility-only projections: they retain current-chunk
-occurrences to `combat_opponent` names and kinds. Location registries project
+classification data, not scene prose or evidence, and exist to route combat
-ordered `{id, name}` pairs to location-occurrence extraction and normalization;
+extraction. Enemy-event extraction also projects combat turns to `actor` and
-exact ID/name matching keeps same-name locations distinguishable. These compact
+`turn_kind` and filters NPC occurrences to `combat_opponent` names and kinds.
-projections, like NPC grounding, are source-free guidance and never event
+These projections are guidance only and never event evidence.
-evidence.
 
 ## Lane-Specific Rules
 
@@ -161,9 +163,9 @@ shared helper changes.
 | Lane | Intentional behavior |
 | --- | --- |
 | Spells | May use a spell-catalog overlay and optional NPC grounding; the catalog validator supplies domain-specific semantic checks. |
-| NPCs | Does not consume an NPC registry. Its normalizer is the LLM-assisted reconciliation exception described above. |
+| NPC registry | Does not consume an NPC registry. Its normalizer is the LLM-assisted reconciliation exception described above. |
 | Combat turns | Requires a scene-description artifact. It calls the LLM only for an exact `combat` classification; exact non-combat classifications return an accepted empty result, while missing or mismatched classifications return an empty result with a bounded warning. Optional NPC grounding never becomes evidence. |
-| Item occurrences | Uses campaign context for disambiguation but has no NPC-registry or scene-description dependency. |
+| Item occurrences | Requires the normalized item registry for exact ID/name grounding at extraction and normalization. Campaign context may disambiguate, but the registry never becomes occurrence evidence. |
 | Item registry | Produces source-grounded item types and unique designations. Its LLM-assisted reconciliation is proposal-only, preserves distinct currency denominations and item types, and does not create per-instance identities. |
 | NPC occurrences | Requires the normalized NPC registry at extraction and normalization, using it for canonical actor grounding only. |
 | Scene descriptions | Produces the classifications consumed by combat routing; it does not consume an NPC registry or provide evidence for combat artifacts. |