Reorganize user and operator documentation

docs/integrations/dnd-spell-artifacts.md

@@ -13,100 +13,48 @@ This document is the durable raw output contract for the implemented
 - Response schema version: `v1`
 - Media type: `application/json`
 
-The extractor requires source chunks and transcript source capability. It
-returns canonical spell-cast JSON derived from the structured LLM response. The
-extractor assigns source IDs deterministically and keeps source-unit ranges as
-model-authored evidence locations. The default `appendorder` merger passes a
-single chunk output through and concatenates multiple
-`spell_casts` arrays in chunk order. The default `noop` normalizer passes the
-merge output through unchanged.
+The output contains canonical spell casts derived from transcript evidence.
+Source IDs are assigned from the input identity; source-unit ranges identify
+the evidence location.
 
 ## Output Shape
 
-For a single chunk, `lanes/spells.json` has this shape:
+`lanes/spells.json` is a JSON object with one required top-level array. Its
+structure is:
 
-```json
-{
-  "spell_casts": [
-    {
-      "caster": "Aria",
-      "spell": "Cure Wounds",
-      "effect": "heals an injured ally",
-      "narrative_description": "Aria raises her holy symbol and casts Cure Wounds.",
-      "source_refs": [
-        {
-          "source_id": "session-alpha",
-          "start_unit_id": 1,
-          "end_unit_id": 1
-        }
-      ]
-    }
-  ]
-}
+```text
+{"spell_casts": [<spell-cast object>, ...]}
 ```
 
 `spell_casts` must be present. It may be empty when no spell casts are found.
-
-For multiple chunks with the default merger, the lane output keeps the same
-top-level shape and concatenates `spell_casts` in chunk order:
-
-```json
-{
-  "spell_casts": [
-    {
-      "caster": "Aria",
-      "spell": "Cure Wounds",
-      "effect": "heals an injured ally",
-      "narrative_description": "Aria raises her holy symbol and casts Cure Wounds.",
-      "source_refs": [
-        {
-          "source_id": "session-alpha",
-          "start_unit_id": 1,
-          "end_unit_id": 1
-        }
-      ]
-    }
-  ]
-}
-```
+With the default configured merger, multiple chunk results are concatenated in
+chunk order.
 
 ## Spell-Cast Fields
 
-Each spell cast contains:
+Each spell cast contains exactly these required fields:
 
 - `caster`: in-world character or creature casting the spell;
 - `spell`: spell name;
 - `effect`: concise spell effect in the scene;
 - `narrative_description`: short description of the spell cast in context;
 - `source_refs`: transcript source references with extractor-assigned source
-  IDs and model-supplied unit ranges.
+  IDs and evidence unit ranges. It must contain at least one entry.
 
-`caster` is the in-world caster, not the transcript speaker.
+All four string fields must be non-empty. `caster` is the in-world caster, not
+the transcript speaker. Unknown fields are rejected.
 
 ## Source References
 
-Each source reference uses the generic source-reference shape:
+Each source reference contains exactly three required fields: `source_id`,
+`start_unit_id`, and `end_unit_id`. The source ID must match the input identity.
+The unit IDs must be positive integers present in the input, and the start unit
+must not appear after the end unit. Unknown fields are rejected.
 
-- `source_id`
-- `start_unit_id`
-- `end_unit_id`
-
-The LLM-facing prompt schema asks only for integer `start_unit_id` and
-`end_unit_id` values matching source-unit IDs. `source_id` is assigned by the
-extractor from the source document ID before validation and output, and is
-required in this durable output contract.
-
-## References
-
-The extractor accepts optional UTF-8 text references:
-
-- `players`
-- `party`
-- `glossary`
-- `roster`, a deprecated compatibility alias for `party`
-
-References are supporting disambiguation material only. They are not source
-evidence and are not addressable through `source_refs`.
+Reference slot keys and accepted file types are defined in
+[Configuration](../config.md#implemented-production-modules). References are
+supporting disambiguation material, not source evidence, and are not
+addressable through `source_refs`.
 
 ## Manifest Metadata