Ground spell extraction with the effective catalog

docs/config.md

@@ -325,16 +325,20 @@ declares optional `players`, `party`, and `glossary` references for scene
 disambiguation, and accepts `roster` as a deprecated compatibility alias for
 `party`.
 
-The `dnd/spells` extractor declares optional reference slots:
+The `dnd/spells` extractor declares optional campaign reference slots:
 
 - `players`
 - `party`
 - `glossary`
 - `roster` as a deprecated compatibility alias for `party`
 
-Both modules accept UTF-8 plain text, Markdown, YAML, or JSON reference files.
-The extractor uses references only as supporting disambiguation material; spell
-casts still must be present in the source transcript.
+These campaign slots accept UTF-8 plain text, Markdown, YAML, or JSON reference
+files. The extractor also declares an optional `spell_catalog` slot that accepts
+one UTF-8 `application/json` overlay bundle no larger than 1 MiB. The slot does
+not allow multiple files. Its format is defined in the
+[spell-catalog overlay contract](integrations/dnd-spell-catalog-overlays.md).
+The extractor uses campaign references only as supporting disambiguation
+material; spell casts still must be present in the source transcript.
 
 ## State Surfaces
 

docs/integrations/dnd-spell-catalog-overlays.md

@@ -5,6 +5,12 @@ resolver. An overlay supplies campaign-specific spell names and aliases for
 recognition. It does not supply spell rules, levels, classes, effects, or
 source evidence.
 
+The `dnd/spells` extractor accepts one optional UTF-8 `application/json` overlay
+bundle through its `spell_catalog` reference slot. The framework materializes
+that file relative to the configuration or command-line binding, enforces the
+1 MiB slot limit, and records its origin and raw digest separately from the
+effective catalog digest.
+
 ## Shape
 
 An overlay bundle has this shape:

docs/internal/llm.md

@@ -103,6 +103,13 @@ return defensive copies, and expose a diagnostics map that omits schema bytes.
 The small framework registry contains only generic test schemas; production
 schemas remain package-owned.
 
+The spell extractor's package-owned prompt declares a required
+`application/json` `spell_catalog` input. The extractor generates that input
+from its prepared effective catalog as `{"spell_names":[...]}` using sorted
+canonical names only. Its input digest covers those generated bytes; manifests
+record catalog identity and digest rather than names, aliases, overlay bytes,
+or source metadata.
+
 ## Debug And Redaction Boundaries
 
 The pipeline may wrap the client with a debug recorder that captures prepared

docs/internal/modules.md

@@ -153,7 +153,12 @@ earliest cited unit, and returns `dnd.SpellList`.
 
 The extractor owns its private model-response DTO, embedded prompt, LLM response
 schema, strict option decoder, injected shared LLM client, and prompt/schema
-manifest metadata. The separate `internal/modules/dnd/codec/spells` package
+manifest metadata. During preparation it resolves the optional `spell_catalog`
+reference into an immutable effective catalog and adds a generated
+canonical-name-only JSON input to every structured completion request. Overlay
+failures therefore stop construction before source parsing or an LLM call;
+campaign references remain separate disambiguation inputs and never become
+source evidence. The separate `internal/modules/dnd/codec/spells` package
 owns the durable schema and stable JSON representation for artifact kind
 `dnd/spell-list`. The runner keeps the result typed through validators and later
 stages, using the codec only for checkpoint, debug, and output boundaries.