Harmonize foundational integration contracts

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

@@ -1,19 +1,27 @@
-# D&D Spell-Catalog Overlay Contract
+# D&D Spell-Catalog Overlays
 
-This document defines the JSON format accepted by the D&D spell catalog
-resolver. An overlay supplies campaign-specific spell names and aliases for
-recognition. It does not supply spell rules, levels, classes, effects, or
-source evidence.
+This document defines the optional JSON overlay consumed by the D&D spell
+extractor. An overlay contributes campaign spell names and aliases for
+recognition. It does not define spell rules, effects, levels, classes, or
+transcript evidence. Bind the optional `spell_catalog` reference as described
+in [Configuration](../config.md#references-and-ordered-handoffs).
 
-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.
+## Contract Identity
 
-## Shape
+| Property | Value |
+| --- | --- |
+| Consumer | D&D spell extraction and normalization |
+| Reference slot | `spell_catalog` |
+| Media type | `application/json` |
+| Required schema version | `notarius.dnd.spell-catalog-overlay.v1` |
+| Base catalog | Embedded D&D 5e 2014 SRD catalog |
 
-An overlay bundle has this shape:
+At most one overlay document may be bound. The maintained example is
+[dnd-spell-catalog.json](../../examples/dnd-spell-catalog.json).
+
+## Wire Shape
+
+This is a minimal valid overlay:
 
 ```json
 {
@@ -22,49 +30,43 @@ An overlay bundle has this shape:
     {
       "id": "campaign.example",
       "ruleset": "dnd-5e-2014",
-      "source": {
-        "title": "Example campaign spells",
-        "version": "1",
-        "url": "",
-        "license": ""
-      },
-      "spells": [
-        {
-          "name": "Aegis of Emberfall",
-          "aliases": ["Emberfall Aegis"]
-        }
-      ]
+      "source": {"title": "Example campaign spells"},
+      "spells": [{"name": "Aegis of Emberfall"}]
     }
   ]
 }
 ```
 
-The top-level `schema_version` and `catalogs` fields are required. The schema
-version must be exactly `notarius.dnd.spell-catalog-overlay.v1`, and at least
-one catalog is required. Catalogs require a unique, non-empty, trimmed `id`,
-the exact `dnd-5e-2014` `ruleset`, a `source`, and a non-empty `spells` array.
+| Field | Required | Meaning and constraints |
+| --- | --- | --- |
+| `schema_version` | Yes | Exactly `notarius.dnd.spell-catalog-overlay.v1`. |
+| `catalogs` | Yes | Non-empty array of catalog objects with unique IDs. |
+| `catalogs[].id` | Yes | Non-empty trimmed string. |
+| `catalogs[].ruleset` | Yes | Exactly `dnd-5e-2014`. |
+| `catalogs[].source.title` | Yes | Non-empty trimmed string. |
+| `catalogs[].source.version` | No | String when present. |
+| `catalogs[].source.url` | No | String when present. |
+| `catalogs[].source.license` | No | String when present. |
+| `catalogs[].spells` | Yes | Non-empty array of spell objects. |
+| `catalogs[].spells[].name` | Yes | Non-empty trimmed string. |
+| `catalogs[].spells[].aliases` | No | Array of non-empty trimmed strings when present. |
 
-`source.title` is required and must be non-empty and trimmed. `source.version`,
-`source.url`, and `source.license` are optional strings and may be empty.
-Each spell requires a non-empty, trimmed `name`. `aliases` may be omitted or
-may be an array of trimmed, non-empty strings; JSON `null` is not an alias
-array. Overlay objects contain no other supported spell fields.
+Unknown fields are rejected at every object level. The document must contain
+one JSON value; `null` is not accepted for optional strings or aliases.
 
-Decoding is strict: unknown fields, malformed JSON, trailing JSON values, and
-non-string optional source fields are rejected.
+## Composition And Compatibility
 
-## Composition
+Notarius starts with the embedded base catalog, then applies overlay catalogs
+in ascending catalog-ID order. A new canonical spell name adds a recognition
+entry. If an overlay names an existing canonical spell, it augments that spell
+with aliases while retaining the established display spelling.
 
-The resolver always starts with the embedded D&D 5e 2014 SRD catalog. Overlay
-catalogs are sorted by `id` before composition, so the input order does not
-affect the result. A new canonical name adds a recognition entry. A canonical
-name matching an existing canonical name augments that spell and keeps the
-established canonical display spelling. Repeated aliases for the same spell
-are idempotent.
+Repeated aliases for the same spell are accepted. A canonical-name, canonical-
+to-alias, or alias-to-alias collision between different spells is rejected,
+including a collision with the embedded catalog. Matching uses the catalog’s
+case, whitespace, and apostrophe normalization, so authors should avoid names
+or aliases that normalize to another spell.
 
-Canonical-name display conflicts and canonical/alias or alias/alias collisions
-between different spells are errors, including collisions with the embedded
-catalog. Canonical names and aliases use the catalog's case, whitespace, and
-common-apostrophe normalization rules. The effective catalog returns canonical
-names in sorted order and produces a semantic SHA-256 digest that is stable
-under JSON formatting, object-key, catalog, spell, and alias reordering.
+The overlay is a recognition aid only. The durable spell-artifact schema and
+source-evidence rules are defined by the
+[D&D spell artifact contract](dnd-spell-artifacts.md).