@openpresentation/opf 0.14.0 → 0.15.1

package/dist/{chunk-LS2FMPI5.js → chunk-2CJPC4HI.js}

@@ -3,7 +3,7 @@ var presentation = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf/v1",
   "title": "Presentation",
-  "description": "Open-source JSON format for describing PowerPoint presentations. Agents describe narratives, content, audience, reusable assets, and design \u2014 the engine handles OOXML complexity.\n\nFields that reference catalog records (narrative, language, tone, audience, purpose, design.theme / design.theme.id, design.colorScheme / design.colorScheme.id, design.fontScheme / design.fontScheme.id, Slide.layout, Chart.type, Organization.socials / Speaker.socials) resolve through the catalog system: inline 'catalogs.<kind>.records[]' on the document \u2192 'catalogs.<kind>.source' on the document \u2192 engine defaults \u2192 the default catalog at https://www.pptx.gallery/<kind>. The default catalog is published by pptx.gallery: the index at https://www.pptx.gallery/<kind>/index.json (also GET https://www.pptx.gallery/<kind> with Accept: application/json) and each record at https://www.pptx.gallery/<kind>/<id>.json. Engines resolve it from the pinned snapshot bundled in @openpresentation/opf (spec/catalogs, pinned by spec/catalogs/manifest.json) and never fetch it at run time; fetching a document's catalogs.<kind>.source is an explicit opt-in by the caller. Every reference resolves to the catalog record's 'id' field. When an OPF document omits a reference entirely, the engine falls back to engine defaults (see /spec/reference/engine-defaults.json for a reference example). The defaults file is engine configuration; it is not part of the OPF document contract and has no JSON Schema.\n\nMost catalog references accept the bare 'id' as a string for the common case (e.g. narrative = 'classic-story', design.colorScheme = 'cool-horizon'). Audience, purpose, tone, design, and language object forms use 'id' as a base catalog reference plus inline overrides. Asset references use 'asset:<id>' strings that point into the top-level assets registry, and content color fields (rich-text runs, styled table cells) accept hex values, color-scheme slot/role names, or 'var:<id>' references into the top-level variables map.",
+  "description": "Open-source JSON format for describing PowerPoint presentations. Agents describe narratives, content, audience, reusable assets, and design \u2014 the engine handles OOXML complexity.\n\nContent references (Slide.layout, design.theme, design.colorScheme / design.colorScheme.id, design.fontScheme / design.fontScheme.id, narrative, audience, purpose and tone, and the colorScheme / fontScheme a theme record names) point at catalog records. Each is a bare 'id' or a 'name:id' whose prefix names a group in 'catalogs'. A bare id resolves in catalogs.custom, then in the records embedded under catalogs.default, then in the catalog the host registered for catalogs.default.source (or the host's default catalog when 'default' is omitted); 'name:id' resolves in catalogs.<name>, then in the catalog the host registered for its source. A reference that resolves nowhere is the warning opf/unresolved-reference, and the slide uses automatic composition or the engine default. Engines never fetch a catalog: a saved document embeds every record it uses, and hosts register any other catalog by its source string. See docs/default-catalog.md.\n\nchart.type, the language tag and the keys of Organization.socials / Speaker.socials are engine vocabularies, validated directly with no catalog lookup. When a document names no theme, colour scheme or font scheme, every engine uses the same small engine defaults (spec/reference/engine-defaults.json). Asset references use 'asset:<id>' strings that point into the top-level assets registry, and content color fields (rich-text runs, styled table cells) accept hex values, color-scheme slot/role names, or 'var:<id>' references into the top-level variables map.",
   "type": "object",
   "required": [
     "slides"
@@ -114,7 +114,7 @@ var presentation = {
           "minItems": 1
         }
       ],
-      "description": "Intended audiences for the presentation. Accepts any of:\n- A single string shorthand: free-form description ('Series B investors'), an audiences catalog id ('executive'), an HTTPS URL, or a 'pkg:' reference.\n- A single inline Audience object, like purpose and tone, for custom audience metadata or catalog-backed overrides. Object form mirrors https://openpresentation.org/schema/opf-audience/v1 without '$schema'.\n- An array of string shorthands and/or inline Audience objects, for more than one audience.\n\nResolution order for catalog ids and references: inline catalogs.audiences.records[] \u2192 catalogs.audiences.source \u2192 default catalog at https://www.pptx.gallery/audiences.",
+      "description": "Intended audiences for the presentation. Accepts any of:\n- A single string: an audiences reference ('executive', or 'acme:board' for a record of the catalogs.acme group), or free-form text ('Series B investors'). A string that is a bare id or 'name:id' is a reference; any other string is free text and is never looked up.\n- A single inline Audience object, for custom audience metadata or overrides on a referenced record. Object form has the fields of https://openpresentation.org/schema/opf-audience/v1.\n- An array of strings and/or inline Audience objects, for more than one audience.\n\nA reference resolves like every content reference (see catalogs); one that resolves nowhere is the warning opf/unresolved-reference. Nothing is drawn from the audience.",
       "examples": [
         "executive",
         "Biology Students and Wildlife Enthusiasts",
@@ -131,7 +131,7 @@ var presentation = {
         },
         [
           "Series B investors",
-          "https://acme.com/decks/audiences/acme-board.json"
+          "acme:board"
         ],
         [
           {
@@ -156,13 +156,12 @@ var presentation = {
           "$ref": "#/$defs/Purpose"
         }
       ],
-      "description": "Primary goal of the presentation. Accepts either:\n- A string shorthand: free-form goal ('Raise a Series B round of $30M'), a purposes catalog id ('decide', 'align'), an HTTPS URL, or a 'pkg:' reference.\n- An inline Purpose object for custom purpose metadata or catalog-backed overrides. Object form mirrors https://openpresentation.org/schema/opf-purpose/v1 without '$schema'.\n\nResolution order for catalog ids and references: inline catalogs.purposes.records[] \u2192 catalogs.purposes.source \u2192 default catalog at https://www.pptx.gallery/purposes.",
+      "description": "Primary goal of the presentation. Accepts either:\n- A string: a purposes reference ('decide', or 'acme:fundraise' for a record of the catalogs.acme group), or a free-form goal ('Raise a Series B round of $30M'). A string that is a bare id or 'name:id' is a reference; any other string is free text and is never looked up.\n- An inline Purpose object for custom purpose metadata or overrides on a referenced record. Object form has the fields of https://openpresentation.org/schema/opf-purpose/v1.\n\nA reference resolves like every content reference (see catalogs); one that resolves nowhere is the warning opf/unresolved-reference. Nothing is drawn from the purpose.",
       "examples": [
         "Raise a Series B round of $30M",
         "align",
         "educate",
-        "https://acme.com/decks/purposes/fundraise.json",
-        "pkg:@acme/decks/purposes/fundraise",
+        "acme:fundraise",
         {
           "id": "decide",
           "outcome": "Approve the Q4 hiring plan"
@@ -176,25 +175,20 @@ var presentation = {
     "language": {
       "oneOf": [
         {
-          "type": "string"
+          "$ref": "#/$defs/LanguageTag"
         },
         {
           "$ref": "#/$defs/Language"
         }
       ],
-      "description": "Language for the presentation content. Accepts either:\n- A string shorthand: a BCP-47 language tag ('en-US', 'en-GB', 'ja-JP', 'fr'), a languages catalog id ('english', 'japanese'), an HTTPS URL, or a 'pkg:' reference.\n- An inline Language object for custom language metadata or catalog-backed overrides. Object form mirrors https://openpresentation.org/schema/opf-language/v1 without '$schema'.\n\nResolution order for catalog ids and references: inline catalogs.languages.records[] \u2192 catalogs.languages.source \u2192 default catalog at https://www.pptx.gallery/languages.",
+      "description": "Language of the presentation content, an engine vocabulary: a BCP-47 language tag, validated directly with no catalog lookup. Accepts either:\n- A BCP-47 tag ('en-US', 'en-GB', 'ja', 'zh-Hans', 'ar-SA').\n- An inline Language object: a 'bcp47' tag plus overrides of what engines know about it (name, ooxmlLang, script, direction, the script font schemes).\n\nEngines know the script, base direction, OOXML language tag and default script fonts of the tags in spec/reference/engine-vocabularies.json; any other well-formed tag is accepted and its script is inferred from the tag. Language names and descriptions are catalog display metadata, not part of the document.",
       "examples": [
         "en-US",
         "en-GB",
         "es-MX",
-        "ja-JP",
+        "ja",
         "fr",
-        "english",
-        "japanese",
-        "https://acme.com/decks/languages/en-acme.json",
-        "pkg:@acme/decks/languages/en-acme",
         {
-          "id": "english",
           "bcp47": "en-US",
           "fontScheme": "aptos",
           "googleFontScheme": "roboto"
@@ -210,21 +204,20 @@ var presentation = {
     "tone": {
       "oneOf": [
         {
-          "type": "string"
+          "$ref": "#/$defs/CatalogReference"
         },
         {
           "$ref": "#/$defs/Tone"
         }
       ],
-      "description": "Desired tone for the presentation. Accepts either:\n- A string shorthand: a tones catalog id ('formal'), an HTTPS URL, or a 'pkg:' reference.\n- An inline Tone object for custom tone metadata or catalog-backed overrides. Object form mirrors https://openpresentation.org/schema/opf-tone/v1 without '$schema'.\n\nResolution order for catalog ids and references: inline catalogs.tones.records[] \u2192 catalogs.tones.source \u2192 default catalog at https://www.pptx.gallery/tones.",
+      "description": "Desired tone for the presentation. Accepts either:\n- A tones reference: a bare id ('formal') or 'name:id' for a record of a named catalogs group.\n- An inline Tone object for custom tone metadata or overrides on a referenced record. Object form has the fields of https://openpresentation.org/schema/opf-tone/v1.\n\nA reference resolves like every content reference (see catalogs); one that resolves nowhere is the warning opf/unresolved-reference. Nothing is drawn from the tone.",
       "examples": [
         "formal",
         "casual",
         "inspirational",
         "technical",
         "persuasive",
-        "https://acme.com/decks/tones/acme-voice.json",
-        "pkg:@acme/decks/tones/acme-voice",
+        "acme:house-voice",
         {
           "id": "formal",
           "voiceCues": [
@@ -301,15 +294,14 @@ var presentation = {
       "default": false
     },
     "narrative": {
-      "type": "string",
-      "description": "The deck's narrative plan, by reference: the 'id' of a 'narratives' catalog record, an HTTPS URL pointing at a record file, or a 'pkg:' reference to a locally-installed package. The deck holds only this pointer; the plan (the arc, its beats and what each beat must do) lives in the catalog record, which validates against https://openpresentation.org/schema/opf-narrative/v1. A custom narrative is a record in catalogs.narratives.records, referenced here by its id.\n\nSlides link themselves to beats with slides[].beat. Core validate warns about a slides[].beat id the resolved narrative does not define and about a root 'duration' outside its 'duration' range, and reports a beat that no slide references. The preview and the PPTX export draw nothing from the narrative; opf-pptx stores the reference for round-trip.\n\nResolution order: inline catalogs.narratives.records[] \u2192 catalogs.narratives.source \u2192 default catalog at https://www.pptx.gallery/narratives. Unknown ids produce a validation warning, not an error.\n\nDeck-level concerns that are not part of the storyline (audience, tone, takeaway, duration) live as siblings on the presentation root.",
+      "$ref": "#/$defs/CatalogReference",
+      "description": "The deck's narrative plan, by reference: a bare narratives id ('classic-story') or 'name:id' for a record of a named catalogs group ('acme:founder-pitch'). The deck holds only this pointer; the plan (the arc, its beats and what each beat must do) lives in the record, which has the fields of https://openpresentation.org/schema/opf-narrative/v1. A narrative the document defines itself is a record in catalogs.custom.narratives, referenced here by its key.\n\nSlides link themselves to beats with slides[].beat. Core validate warns about a slides[].beat id the resolved narrative does not define and about a root 'duration' outside its 'duration' range, and reports a beat that no slide references. The preview and the PPTX export draw nothing from the narrative; opf-pptx stores the reference for round-trip.\n\nThe reference resolves like every content reference (see catalogs); one that resolves nowhere is the warning opf/unresolved-reference, never an error.\n\nDeck-level concerns that are not part of the storyline (audience, tone, takeaway, duration) live as siblings on the presentation root.",
       "examples": [
         "classic-story",
         "problem-solution",
         "scqa",
         "pitch-deck",
-        "https://acme.com/decks/narratives/founder-pitch.json",
-        "pkg:@acme/decks/narratives/founder-pitch"
+        "acme:founder-pitch"
       ]
     },
     "slides": {
@@ -346,7 +338,7 @@ var presentation = {
     },
     "catalogs": {
       "$ref": "#/$defs/Catalogs",
-      "description": "Optional per-kind catalog overrides. Each kind may declare a non-default 'source' and/or inline 'records' that override or supplement the default catalog at https://www.pptx.gallery/<kind>. References elsewhere in the document (e.g. design.theme, narrative) resolve through this section before falling back to the default catalog."
+      "description": "The catalog records this document embeds, grouped by the catalog they came from: 'default' (the catalog bare ids come from), 'custom' (records the document defines itself) and any number of named catalogs ('acme', referenced as 'acme:<id>'). A saved document embeds every record it references, so it renders the same with no catalog registered. See Catalogs."
     },
     "extensions": {
       "type": "object",
@@ -435,7 +427,7 @@ var presentation = {
     },
     "Audience": {
       "type": "object",
-      "description": "Inline audience metadata for the presentation. Use 'id' to reference an audiences catalog record and override selected fields, or use 'name' for a custom inline audience.",
+      "description": "Inline audience metadata for the presentation. Use 'id' to reference an audiences record (a bare id or 'name:id') and override selected fields, or use 'name' for a custom inline audience.",
       "anyOf": [
         {
           "required": [
@@ -450,9 +442,8 @@ var presentation = {
       ],
       "properties": {
         "id": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Optional audiences catalog id to resolve before applying inline overrides.",
+          "$ref": "#/$defs/CatalogReference",
+          "description": "Optional audiences reference (a bare id or 'name:id') resolved before applying the inline overrides.",
           "examples": [
             "executive",
             "board",
@@ -512,14 +503,14 @@ var presentation = {
           "items": {
             "type": "string"
           },
-          "description": "Soft cross-link: narrative-catalog ids that work well for this audience."
+          "description": "Soft cross-link: narrative ids that work well for this audience, for picker UIs. Never resolved, embedded or validated as references."
         },
         "recommendedTones": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Soft cross-link: tone-catalog ids that work well for this audience."
+          "description": "Soft cross-link: tone ids that work well for this audience, for picker UIs. Never resolved, embedded or validated as references."
         },
         "tags": {
           "type": "array",
@@ -532,7 +523,7 @@ var presentation = {
     },
     "Purpose": {
       "type": "object",
-      "description": "Inline purpose metadata for the presentation. Use 'id' to reference a purposes catalog record and override selected fields, or use 'name' for a custom inline purpose.",
+      "description": "Inline purpose metadata for the presentation. Use 'id' to reference a purposes record (a bare id or 'name:id') and override selected fields, or use 'name' for a custom inline purpose.",
       "anyOf": [
         {
           "required": [
@@ -547,9 +538,8 @@ var presentation = {
       ],
       "properties": {
         "id": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Optional purposes catalog id to resolve before applying inline overrides.",
+          "$ref": "#/$defs/CatalogReference",
+          "description": "Optional purposes reference (a bare id or 'name:id') resolved before applying the inline overrides.",
           "examples": [
             "inform",
             "decide",
@@ -586,14 +576,14 @@ var presentation = {
           "items": {
             "type": "string"
           },
-          "description": "Soft cross-link: narrative-catalog ids that work well for this purpose."
+          "description": "Soft cross-link: narrative ids that work well for this purpose, for picker UIs. Never resolved, embedded or validated as references."
         },
         "recommendedTones": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Soft cross-link: tone-catalog ids that work well for this purpose."
+          "description": "Soft cross-link: tone ids that work well for this purpose, for picker UIs. Never resolved, embedded or validated as references."
         },
         "tags": {
           "type": "array",
@@ -606,31 +596,16 @@ var presentation = {
     },
     "Language": {
       "type": "object",
-      "description": "Inline language metadata for the presentation. Use 'id' to reference a languages catalog record and override selected fields, or use 'bcp47' for a custom language tag without a catalog record.",
-      "anyOf": [
-        {
-          "required": [
-            "id"
-          ]
-        },
-        {
-          "required": [
-            "bcp47"
-          ]
-        }
+      "description": "Inline language metadata for the presentation: a BCP-47 'bcp47' tag plus overrides of what engines know about it. Languages are an engine vocabulary, not catalog records, so there is no 'id'.",
+      "required": [
+        "bcp47"
       ],
+      "not": {
+        "required": [
+          "id"
+        ]
+      },
       "properties": {
-        "id": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Optional languages catalog id to resolve before applying inline overrides.",
-          "examples": [
-            "english",
-            "japanese",
-            "chinese-simplified",
-            "english-uk"
-          ]
-        },
         "name": {
           "type": "string",
           "description": "Human-readable language name.",
@@ -641,7 +616,7 @@ var presentation = {
           ]
         },
         "bcp47": {
-          "type": "string",
+          "$ref": "#/$defs/LanguageTag",
           "description": "BCP-47 language tag used for locale-aware rendering, proofing, and accessibility metadata. Use 'en-GB' for UK English; 'en-UK' is not a valid BCP-47 region form.",
           "examples": [
             "en",
@@ -653,7 +628,7 @@ var presentation = {
         },
         "ooxmlLang": {
           "type": "string",
-          "description": "Curated culture tag for OOXML text-run language attributes (a:rPr/@lang, a:endParaRPr/@lang), in the language-[Script-]REGION form Office recognizes (e.g. 'ja-JP', 'ar-SA', 'ms-MY', 'nb-NO', 'fil-PH', 'zh-CN'). Engines emit it instead of 'bcp47' when the document names the language by catalog id or by a tag without a region; a region-bearing tag written by the author is emitted as written. Curated rather than inferred so output does not depend on the runtime's locale data.",
+          "description": "Culture tag for OOXML text-run language attributes (a:rPr/@lang, a:endParaRPr/@lang), in the language-[Script-]REGION form Office recognizes (e.g. 'ja-JP', 'ar-SA', 'ms-MY', 'nb-NO', 'fil-PH', 'zh-CN'). Without it, engines emit the curated tag of their language vocabulary (spec/reference/engine-vocabularies.json) for a tag without a region, and a region-bearing tag as written. Curated rather than inferred so output does not depend on the runtime's locale data.",
           "examples": [
             "en-US",
             "ja-JP",
@@ -679,11 +654,11 @@ var presentation = {
             "ltr",
             "rtl"
           ],
-          "description": "Base text direction for the language. When omitted, engines derive it from the script: Arabic (Arab), Hebrew (Hebr), Syriac (Syrc), Thaana (Thaa), N'Ko (Nkoo), Adlam (Adlm), Samaritan (Samr), Mandaic (Mand) and Hanifi Rohingya (Rohg) are right-to-left; every other script is left-to-right. Bundled language records state it explicitly."
+          "description": "Base text direction for the language. When omitted, engines derive it from the script: Arabic (Arab), Hebrew (Hebr), Syriac (Syrc), Thaana (Thaa), N'Ko (Nkoo), Adlam (Adlm), Samaritan (Samr), Mandaic (Mand) and Hanifi Rohingya (Rohg) are right-to-left; every other script is left-to-right. The engine language vocabulary (spec/reference/engine-vocabularies.json) states it for the tags it knows."
         },
         "script": {
           "type": "string",
-          "description": "ISO 15924 script code of the language's writing system. The script selects the OOXML font slot the language's text uses: East Asian scripts (Hans, Hant, Hani, Jpan, Kore, Hang, Hira, Kana, Bopo, Yiii) use the eastAsian slot; complex scripts (for example Arab, Hebr, Syrc, Thaa, Deva, Beng, Guru, Gujr, Orya, Taml, Telu, Knda, Mlym, Sinh, Thai, Laoo, Tibt, Mymr, Khmr, Mong) use the complexScript slot; every other script (Latn, Cyrl, Grek, Armn, Geor, Ethi, ...) uses the latin slot. When omitted, engines infer it from the BCP-47 tag. Bundled language records state it explicitly. See docs/programs/font-fidelity-everywhere/script-font-model.md.",
+          "description": "ISO 15924 script code of the language's writing system. The script selects the OOXML font slot the language's text uses: East Asian scripts (Hans, Hant, Hani, Jpan, Kore, Hang, Hira, Kana, Bopo, Yiii) use the eastAsian slot; complex scripts (for example Arab, Hebr, Syrc, Thaa, Deva, Beng, Guru, Gujr, Orya, Taml, Telu, Knda, Mlym, Sinh, Thai, Laoo, Tibt, Mymr, Khmr, Mong) use the complexScript slot; every other script (Latn, Cyrl, Grek, Armn, Geor, Ethi, ...) uses the latin slot. When omitted, engines infer it from the BCP-47 tag. The engine language vocabulary (spec/reference/engine-vocabularies.json) states it for the tags it knows. See docs/programs/font-fidelity-everywhere/script-font-model.md.",
           "examples": [
             "Latn",
             "Cyrl",
@@ -699,12 +674,12 @@ var presentation = {
           ]
         },
         "fontScheme": {
-          "type": "string",
-          "description": "Default font-scheme id for this language when targeting PowerPoint output. Resolves against catalogs.fontSchemes the same way design.fontScheme or design.fontScheme.id does. Its major/minor families fill the language's script slot (eastAsian or complexScript, chosen by 'script') unless the effective design font scheme sets that slot itself; the latin slot always follows the design font scheme."
+          "$ref": "#/$defs/CatalogReference",
+          "description": "Font-scheme reference (a bare id or 'name:id') for this language's script slot when targeting PowerPoint output. Its major/minor families fill the language's script slot (eastAsian or complexScript, chosen by 'script') unless the effective design font scheme sets that slot itself; the latin slot always follows the design font scheme. Without it, engines use the default script fonts of their language vocabulary."
         },
         "googleFontScheme": {
-          "type": "string",
-          "description": "Default font-scheme id for this language when targeting Google Slides output. Resolves against catalogs.fontSchemes the same way design.fontScheme or design.fontScheme.id does. Used in place of 'fontScheme' when resolving script fonts for Google Slides output."
+          "$ref": "#/$defs/CatalogReference",
+          "description": "Font-scheme reference (a bare id or 'name:id') used in place of 'fontScheme' when resolving script fonts for Google Slides output."
         },
         "summary": {
           "type": "string",
@@ -725,7 +700,7 @@ var presentation = {
     },
     "Tone": {
       "type": "object",
-      "description": "Inline tone metadata for the presentation. Use 'id' to reference a tones catalog record and override selected fields, or use 'name' for a custom inline tone.",
+      "description": "Inline tone metadata for the presentation. Use 'id' to reference a tones record (a bare id or 'name:id') and override selected fields, or use 'name' for a custom inline tone.",
       "anyOf": [
         {
           "required": [
@@ -740,9 +715,8 @@ var presentation = {
       ],
       "properties": {
         "id": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Optional tones catalog id to resolve before applying inline overrides.",
+          "$ref": "#/$defs/CatalogReference",
+          "description": "Optional tones reference (a bare id or 'name:id') resolved before applying the inline overrides.",
           "examples": [
             "formal",
             "casual",
@@ -788,7 +762,7 @@ var presentation = {
           "items": {
             "type": "string"
           },
-          "description": "Soft cross-link: narrative-catalog ids this tone pairs well with."
+          "description": "Soft cross-link: narrative ids this tone pairs well with, for picker UIs. Never resolved, embedded or validated as references."
         },
         "tags": {
           "type": "array",
@@ -985,7 +959,7 @@ var presentation = {
     },
     "Socials": {
       "type": "object",
-      "description": "Social media handles or URLs, keyed by platform id from the 'socialPlatforms' catalog. Each value is a string \u2014 either a full URL or a platform handle (e.g., '@acme'). The catalog record for each platform carries the URL pattern and handle prefix that engines use to render and link the profile URL, plus brand color and themed icons as catalog metadata for authoring UIs (engines render the profile URL, not icons or brand colors).\n\nKeys resolve to the 'id' of a 'socialPlatforms' catalog record. Resolution order: inline catalogs.socialPlatforms.records[] \u2192 catalogs.socialPlatforms.source \u2192 default catalog at https://www.pptx.gallery/social-platforms. Unknown platform keys render with engine fallbacks (the raw value as text). Used both for organization and speaker records.",
+      "description": "Social media handles or URLs, keyed by platform. The keys are an engine vocabulary validated directly (no catalog lookup): engines link a handle with the platform's URL pattern and handle prefix (spec/reference/engine-vocabularies.json). Each value is a string, either a full URL or a platform handle (e.g., '@acme'). Brand colours and icons are catalog display metadata for authoring UIs; engines render the profile URL, not icons or brand colours. Used both for organization and speaker records.",
       "additionalProperties": {
         "type": "string",
         "description": "Handle or URL for the platform identified by the property key."
@@ -1003,8 +977,19 @@ var presentation = {
         }
       ],
       "propertyNames": {
-        "pattern": "^[a-z][a-z0-9-]*$",
-        "description": "Platform id (lowercase kebab-case). Common ids include 'linkedin', 'x', 'github', 'youtube', 'instagram', 'facebook', 'tiktok', 'threads', 'mastodon', 'bluesky'."
+        "enum": [
+          "linkedin",
+          "x",
+          "github",
+          "youtube",
+          "instagram",
+          "facebook",
+          "tiktok",
+          "threads",
+          "mastodon",
+          "bluesky"
+        ],
+        "description": "Platform key, one of the engine's social platforms."
       }
     },
     "Design": {
@@ -1012,35 +997,14 @@ var presentation = {
       "description": "Visual design system applied to the presentation; individual slides may override fields via Slide.design.",
       "properties": {
         "theme": {
-          "oneOf": [
-            {
-              "type": "string"
-            },
-            {
-              "$ref": "#/$defs/Theme"
-            }
-          ],
-          "description": `Theme for the deck. Accepts two forms:
-- String shorthand: 'design.theme = "minimal"'. Bare id, HTTPS URL, or 'pkg:' reference resolved as the 'id' of a 'themes' catalog record.
-- Object form: a Theme with an optional 'id' base reference plus theme-level overrides.
-
-Inline overrides on design.colorScheme / design.fontScheme / design.background / design.dimensions take precedence over the resolved theme.
-
-Resolution order: inline catalogs.themes.records[] -> catalogs.themes.source -> default catalog at https://www.pptx.gallery/themes.`,
+          "$ref": "#/$defs/CatalogReference",
+          "description": "Theme for the deck: a themes reference, a bare id ('minimal') or 'name:id' ('acme:brand'). The theme supplies the default colour scheme, font scheme, background and dimensions; design.colorScheme, design.fontScheme, design.background and design.dimensions override it field by field. A reference that resolves nowhere is the warning opf/unresolved-reference and engines use the engine default theme.",
           "examples": [
             "minimal",
             "classic",
             "dark",
             "bold",
-            "corporate-minimal",
-            "ocean-depth",
-            "https://acme.com/decks/themes/acme-brand.json",
-            "pkg:@acme/decks/themes/acme-brand",
-            {
-              "id": "minimal",
-              "background": "dark1",
-              "dimensions": "widescreen"
-            }
+            "acme:brand"
           ]
         },
         "colorScheme": {
@@ -1052,11 +1016,7 @@ Resolution order: inline catalogs.themes.records[] -> catalogs.themes.source ->
               "$ref": "#/$defs/ColorScheme"
             }
           ],
-          "description": `Color scheme for the presentation. Accepts two forms:
-- String shorthand: 'design.colorScheme = "cool-horizon"'. Bare id, HTTPS URL, or 'pkg:' reference resolved as the 'id' of a 'colorSchemes' catalog record.
-- Object form: a ColorScheme with an optional 'id' base reference plus slot/role overrides.
-
-Resolution order: inline catalogs.colorSchemes.records[] -> catalogs.colorSchemes.source -> default catalog at https://www.pptx.gallery/color-schemes.`,
+          "description": "Color scheme for the presentation. Accepts two forms:\n- A colorSchemes reference: a bare id ('cool-horizon') or 'name:id' ('acme:ocean').\n- Object form: a ColorScheme with an optional 'id' reference as the base plus slot/role overrides. Without 'id', the overrides apply on top of the engine default colour scheme.\n\nWithout either, the theme's colorScheme applies, then the engine default colour scheme.",
           "examples": [
             "cool-horizon",
             "boost",
@@ -1076,11 +1036,7 @@ Resolution order: inline catalogs.colorSchemes.records[] -> catalogs.colorScheme
               "$ref": "#/$defs/FontScheme"
             }
           ],
-          "description": `Font scheme for heading, body, accent, and code text. Accepts two forms:
-- String shorthand: 'design.fontScheme = "aptos"'. Bare id, HTTPS URL, or 'pkg:' reference resolved as the 'id' of a 'fontSchemes' catalog record.
-- Object form: a FontScheme with an optional 'id' base reference plus pair/role overrides.
-
-Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.source -> default catalog at https://www.pptx.gallery/font-schemes.`,
+          "description": "Font scheme for heading, body, accent, and code text. Accepts two forms:\n- A fontSchemes reference: a bare id ('aptos') or 'name:id' ('acme:inter').\n- Object form: a FontScheme with an optional 'id' reference as the base plus pair/role overrides.\n\nWithout either, the theme's fontScheme applies, then the engine default font scheme.",
           "examples": [
             "aptos",
             "tenorite",
@@ -1117,7 +1073,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
               "$ref": "#/$defs/Background"
             }
           ],
-          "description": "Default slide background applied across the deck unless overridden on a slide. String shorthand accepts theme slots ('light1', 'light2', 'dark1', 'dark2') or hex colors; object forms support theme, solid, gradient, image, or pattern fills.",
+          "description": "Default slide background applied across the deck unless overridden on a slide (slides.N.design.background); the resolved theme's background is the fallback. A background is the only canvas fill and never moves content. String shorthand accepts theme slots ('light1', 'light2', 'dark1', 'dark2'), hex colors, or an image source starting with 'asset:', 'https://', 'data:', './' or '../' (a cover image); object forms support theme, solid, gradient, image, or pattern fills.",
           "examples": [
             "dark1",
             "#ffff00",
@@ -1244,175 +1200,6 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           "type": "boolean",
           "description": "Whether body/content regions are rendered inside a visible card or surface. Effective value: the slide's design, then the deck's design, then the layout record's design.contentBox, then the engine default."
         },
-        "slideImage": {
-          "oneOf": [
-            {
-              "$ref": "#/$defs/Asset"
-            },
-            {
-              "type": "object",
-              "additionalProperties": false,
-              "required": [
-                "position"
-              ],
-              "properties": {
-                "src": {
-                  "type": "string",
-                  "description": "Source for the slide-level image. When omitted in a design override, the object only configures how a slide-level image should be placed when one is supplied by a content payload, asset, or renderer convention."
-                },
-                "position": {
-                  "type": "string",
-                  "enum": [
-                    "background",
-                    "top",
-                    "bottom",
-                    "left",
-                    "right"
-                  ],
-                  "description": "Where the slide-level image sits relative to the content. 'background' is a full-bleed image behind the content. The other positions give the image a band along that edge (see size) and compose headings and content in the rest of the slide."
-                },
-                "alt": {
-                  "type": "string",
-                  "description": "Alternative text for the slide-level image. Overrides the alt text of a referenced asset."
-                },
-                "fill": {
-                  "type": "string",
-                  "enum": [
-                    "crop",
-                    "fit"
-                  ],
-                  "description": "How the image fills its frame: 'crop' covers the frame from the center; 'fit' shows the whole image centered inside it. Overrides design.imageFill for this image. Default: design.imageFill, else 'crop'."
-                },
-                "size": {
-                  "type": "number",
-                  "minimum": 0.1,
-                  "maximum": 0.9,
-                  "description": "Share of the slide width (left/right) or height (top/bottom) given to the image band. Ignored for 'background'. Default 0.5."
-                },
-                "inset": {
-                  "type": "boolean",
-                  "description": "Place the frame inside the slide padding instead of edge to edge, like a card. Default false."
-                },
-                "aspectRatio": {
-                  "type": "number",
-                  "exclusiveMinimum": 0,
-                  "maximum": 10,
-                  "description": "Width-to-height ratio of the frame. The frame becomes the largest centered box with this ratio inside the band or slide, for example 2.39 for a cinematic letterbox or 0.5 for a phone-shaped frame. 'circle' always uses 1."
-                },
-                "shape": {
-                  "type": "string",
-                  "enum": [
-                    "rectangle",
-                    "rounded",
-                    "circle",
-                    "hexagon"
-                  ],
-                  "description": "Mask applied to the frame, exported as the picture's native preset geometry (rect, roundRect, ellipse, hexagon). 'circle' makes the frame square. Default 'rectangle'."
-                },
-                "cornerRadius": {
-                  "type": "number",
-                  "minimum": 0,
-                  "maximum": 0.5,
-                  "description": "Corner radius for shape 'rounded' as a fraction of the frame's shorter side. Default 0.16667, PowerPoint's roundRect default."
-                },
-                "border": {
-                  "type": "object",
-                  "additionalProperties": false,
-                  "required": [
-                    "color",
-                    "width"
-                  ],
-                  "properties": {
-                    "color": {
-                      "$ref": "#/$defs/ColorRef",
-                      "description": "Line color: a hex color, a color-scheme slot or role name, or a 'var:<id>' variable reference."
-                    },
-                    "width": {
-                      "type": "number",
-                      "minimum": 0,
-                      "maximum": 64,
-                      "description": "Line width in reference pixels at a 720-pixel short edge, centered on the frame outline like a native picture line. 0 removes the line."
-                    }
-                  },
-                  "description": "Solid line along the frame's shape. A thick dark border on a rounded portrait frame gives a device bezel."
-                },
-                "opacity": {
-                  "type": "number",
-                  "minimum": 0,
-                  "maximum": 1,
-                  "description": "Image opacity from 0 to 1, exported as a native alphaModFix. The border and overlay keep their own opacity. Default 1."
-                },
-                "recolor": {
-                  "oneOf": [
-                    {
-                      "type": "string",
-                      "const": "grayscale",
-                      "description": "Replace each pixel with its luminance, exported as native a:grayscl."
-                    },
-                    {
-                      "type": "object",
-                      "additionalProperties": false,
-                      "required": [
-                        "dark",
-                        "light"
-                      ],
-                      "properties": {
-                        "dark": {
-                          "$ref": "#/$defs/ColorRef",
-                          "description": "Color at luminance 0."
-                        },
-                        "light": {
-                          "$ref": "#/$defs/ColorRef",
-                          "description": "Color at luminance 1."
-                        }
-                      },
-                      "description": "Duotone: map each pixel's luminance linearly from dark to light, exported as native a:duotone."
-                    }
-                  ],
-                  "description": "Color treatment for the image pixels. Luminance uses Rec. 601 weights (0.299, 0.587, 0.114) on sRGB values."
-                },
-                "overlay": {
-                  "type": "object",
-                  "additionalProperties": false,
-                  "required": [
-                    "color",
-                    "opacity"
-                  ],
-                  "properties": {
-                    "color": {
-                      "$ref": "#/$defs/ColorRef",
-                      "description": "Overlay fill color."
-                    },
-                    "opacity": {
-                      "type": "number",
-                      "minimum": 0,
-                      "maximum": 1,
-                      "description": "Overlay fill opacity."
-                    },
-                    "edge": {
-                      "type": "string",
-                      "enum": [
-                        "top",
-                        "bottom",
-                        "left",
-                        "right"
-                      ],
-                      "description": "Cover only a band along this edge of the frame, for example a caption strip. Rectangle frames only; other shapes report unsupported-image-treatment and draw no overlay. Omit to cover the whole frame."
-                    },
-                    "size": {
-                      "type": "number",
-                      "minimum": 0.05,
-                      "maximum": 1,
-                      "description": "Band share of the frame for an edge overlay. Default 0.3."
-                    }
-                  },
-                  "description": "Solid scrim drawn over the image in the frame's shape, beneath headings and content, for example to keep overlaid text readable. Exported as a native shape above the picture."
-                }
-              }
-            }
-          ],
-          "description": "Optional slide-level image, separate from content images. It applies to a slide that sets its own design.slideImage, and to slides whose layout record sets design.slideImage or whose root image is the same source as a deck-level value. A root image with the same source becomes the slide image instead of a content item. Blur, shadows, soft edges, background removal and device artwork are not part of the treatment vocabulary; see docs/image-treatments.md."
-        },
         "contentDirection": {
           "type": "string",
           "enum": [
@@ -1432,13 +1219,14 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ],
           "description": "Where the primary chart sits relative to supporting content. Effective value: slide design, then deck design, then the layout record's design.chartPrimary. When the slide has no promoted regions and no composition.mode of its own, and its root nodes mix at least one chart with other content, the first chart becomes a primary track and the other nodes form one synthetic sub-grid: 'left'/'right' is a two-track row and 'top'/'bottom' a two-track column, weighted 3:2 in favor of the chart; explicit root columns and weights are ignored while it applies. 'none' (the default) keeps the ordinary automatic grid with equal weight."
         },
-        "imageFill": {
+        "imageFit": {
           "type": "string",
           "enum": [
-            "crop",
-            "fit"
+            "cover",
+            "contain",
+            "stretch"
           ],
-          "description": "How images fill their allocated region: crop covers the region, fit shows the whole image. Effective value: the slide's design, then the deck's design, then the layout record's design.imageFill, then the engine default."
+          "description": "Default fit of image blocks (and Slide.image) that set no fit of their own: 'cover' fills the frame and crops what overflows around the block's focus, 'contain' shows the whole picture centered in the frame, 'stretch' scales it to the frame exactly. Effective value: the slide's design, then the deck's design, then the layout record's design.imageFit, then 'cover'. Backgrounds set their own fit."
         },
         "listBullet": {
           "type": "string",
@@ -1450,136 +1238,19 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
         }
       }
     },
-    "Theme": {
-      "type": "object",
-      "description": "Theme bundle used by the design system. In design.theme, 'id' resolves a themes catalog record as the base; any sibling fields override the resolved theme. The string shorthand on design.theme is equivalent to setting only 'id'.",
-      "properties": {
-        "id": {
-          "type": "string",
-          "description": "Theme reference. Resolves to the 'id' of a 'themes' catalog record. Accepts a bare id (lowercase kebab-case, e.g. 'minimal'), an HTTPS URL pointing at a record file, or a 'pkg:' reference. Field overrides on the surrounding Theme object take precedence over the resolved theme.\n\nResolution order: inline catalogs.themes.records[] -> catalogs.themes.source -> default catalog at https://www.pptx.gallery/themes.",
-          "examples": [
-            "minimal",
-            "classic",
-            "dark",
-            "bold",
-            "https://acme.com/decks/themes/acme-brand.json",
-            "pkg:@acme/decks/themes/acme-brand"
-          ]
-        },
-        "name": {
-          "type": "string",
-          "description": "Human-readable theme name shown in pickers.",
-          "examples": [
-            "Minimal",
-            "Classic",
-            "Dark",
-            "Bold"
-          ]
-        },
-        "summary": {
-          "type": "string",
-          "description": "One-sentence positioning of the theme - when to reach for it."
-        },
-        "description": {
-          "type": "string",
-          "description": "Longer prose describing what the theme looks and feels like and the kinds of decks it suits."
-        },
-        "colorScheme": {
-          "oneOf": [
-            {
-              "type": "string"
-            },
-            {
-              "$ref": "#/$defs/ColorScheme"
-            }
-          ],
-          "description": "Default color scheme for this theme. A string resolves against catalogs.colorSchemes; an object may provide an 'id' base reference plus overrides.",
-          "examples": [
-            "cool-horizon",
-            {
-              "id": "cool-horizon",
-              "accent1": "#FF6F61"
-            }
-          ]
-        },
-        "fontScheme": {
-          "oneOf": [
-            {
-              "type": "string"
-            },
-            {
-              "$ref": "#/$defs/FontScheme"
-            }
-          ],
-          "description": "Default font scheme for this theme. A string resolves against catalogs.fontSchemes; an object may provide an 'id' base reference plus overrides.",
-          "examples": [
-            "aptos",
-            {
-              "id": "aptos",
-              "heading": "Inter"
-            }
-          ]
-        },
-        "background": {
-          "oneOf": [
-            {
-              "$ref": "#/$defs/BackgroundShortcut"
-            },
-            {
-              "$ref": "#/$defs/Background"
-            }
-          ],
-          "description": "Default background for this theme. String shorthand accepts theme slots ('light1', 'light2', 'dark1', 'dark2') or hex colors.",
-          "examples": [
-            "dark1",
-            "#ffff00",
-            {
-              "type": "theme",
-              "slot": "dark2"
-            }
-          ]
-        },
-        "dimensions": {
-          "oneOf": [
-            {
-              "$ref": "#/$defs/DimensionPreset"
-            },
-            {
-              "$ref": "#/$defs/Dimensions"
-            }
-          ],
-          "description": "Default slide size for this theme. A string preset is equivalent to { preset: value }.",
-          "examples": [
-            "widescreen",
-            {
-              "preset": "16:9"
-            }
-          ]
-        },
-        "tags": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Free-form labels for filtering and search."
-        }
-      }
-    },
     "ColorScheme": {
       "type": "object",
-      "description": "Color palette used by the design system. Every slot and role is a hex color ('#RGB', '#RRGGBB' or '#RRGGBBAA'); a color-scheme name or a 'var:<id>' reference is not valid here, because those resolve through the scheme. The slot fields (accent1-accent6, dark1, dark2, light1, light2, hyperlink, followedHyperlink) mirror color-scheme.schema.json (https://openpresentation.org/schema/opf-color-scheme/v1) so library records and inline OPF overrides are interchangeable on those fields.\n\nTwo parallel models are supported and may be mixed:\n- OOXML slots - the 12-slot PowerPoint theme model that round-trips directly to OOXML. Use these for full control over the palette as PowerPoint sees it.\n- Abstract roles (primary, secondary, accent, background, surface, text, textSecondary) - OPF-specific semantic aliases the engine maps onto the OOXML slots. Convenient for inline overrides without thinking in slot numbers; not part of the catalog record schema.\n\nIn design.colorScheme, 'id' resolves a colorSchemes catalog record as the base; slot and role overrides on the same object take precedence over the resolved scheme. The string shorthand on design.colorScheme is equivalent to setting only 'id'.",
+      "description": "Color palette used by the design system. Every slot and role is a hex color ('#RGB', '#RRGGBB' or '#RRGGBBAA'); a color-scheme name or a 'var:<id>' reference is not valid here, because those resolve through the scheme. The slot fields (accent1-accent6, dark1, dark2, light1, light2, hyperlink, followedHyperlink) mirror color-scheme.schema.json (https://openpresentation.org/schema/opf-color-scheme/v1) so library records and inline OPF overrides are interchangeable on those fields.\n\nTwo parallel models are supported and may be mixed:\n- OOXML slots - the 12-slot PowerPoint theme model that round-trips directly to OOXML. Use these for full control over the palette as PowerPoint sees it.\n- Abstract roles (primary, secondary, accent, background, surface, text, textSecondary) - OPF-specific semantic aliases the engine maps onto the OOXML slots. Convenient for inline overrides without thinking in slot numbers; not part of the catalog record schema.\n\nIn design.colorScheme, 'id' resolves a colorSchemes record as the base; slot and role overrides on the same object take precedence over the resolved scheme. The string form of design.colorScheme is equivalent to setting only 'id'.",
       "properties": {
         "id": {
-          "type": "string",
-          "description": "Color scheme reference. Resolves to the 'id' of a 'colorSchemes' catalog record. Accepts a bare id (lowercase kebab-case, e.g. 'cool-horizon'), an HTTPS URL pointing at a record file, or a 'pkg:' reference. Slot and role overrides on the surrounding ColorScheme object take precedence over the resolved scheme.\n\nResolution order: inline catalogs.colorSchemes.records[] -> catalogs.colorSchemes.source -> default catalog at https://www.pptx.gallery/color-schemes.",
+          "$ref": "#/$defs/CatalogReference",
+          "description": "Colour-scheme reference (a bare id or 'name:id') resolved as the base; slot and role overrides on the surrounding ColorScheme object take precedence over the resolved scheme.",
           "examples": [
             "cool-horizon",
             "boost",
             "burnt-orange",
             "ocean-depth",
-            "corporate-blue",
-            "https://acme.com/decks/color-schemes/acme.json",
-            "pkg:@acme/decks/color-schemes/acme"
+            "corporate-blue"
           ]
         },
         "accent1": {
@@ -1742,20 +1413,18 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
     },
     "FontScheme": {
       "type": "object",
-      "description": "Typography selections used by the design system. The pair fields (major, minor) and refinement fields (type, app, languageFamily) mirror font-scheme.schema.json (https://openpresentation.org/schema/opf-font-scheme/v1) so library records and inline OPF overrides are interchangeable on those fields.\n\nTwo parallel models are supported and may be mixed:\n- OOXML pairs (major, minor) - heading and body family names that round-trip directly to PowerPoint majorFont/minorFont entries.\n- Abstract roles (heading, body, accent, code) - OPF-specific font family names the engine maps onto the OOXML pair when serializing. Convenient for inline overrides and for adding accent/code roles that don't have a direct OOXML slot. Catalog records may also carry 'code' (for example the consolas and courier-new records); heading, body and accent are not part of the catalog record schema. A role is a family name only: weight, style and tracking come from the text styles, and PowerPoint has no numeric weight.\n\nIn design.fontScheme, 'id' resolves a fontSchemes catalog record as the base; pair and role overrides on the same object take precedence over the resolved scheme. The string shorthand on design.fontScheme is equivalent to setting only 'id'.",
+      "description": "Typography selections used by the design system. The pair fields (major, minor) and refinement fields (type, app, languageFamily) mirror font-scheme.schema.json (https://openpresentation.org/schema/opf-font-scheme/v1) so library records and inline OPF overrides are interchangeable on those fields.\n\nTwo parallel models are supported and may be mixed:\n- OOXML pairs (major, minor) - heading and body family names that round-trip directly to PowerPoint majorFont/minorFont entries.\n- Abstract roles (heading, body, accent, code) - OPF-specific font family names the engine maps onto the OOXML pair when serializing. Convenient for inline overrides and for adding accent/code roles that don't have a direct OOXML slot. Catalog records may also carry 'code' (for example the consolas and courier-new records); heading, body and accent are not part of the catalog record schema. A role is a family name only: weight, style and tracking come from the text styles, and PowerPoint has no numeric weight.\n\nIn design.fontScheme, 'id' resolves a fontSchemes record as the base; pair and role overrides on the same object take precedence over the resolved scheme. The string form of design.fontScheme is equivalent to setting only 'id'.",
       "properties": {
         "id": {
-          "type": "string",
-          "description": "Font scheme reference. Resolves to the 'id' of a 'fontSchemes' catalog record. Accepts a bare id (lowercase kebab-case, e.g. 'aptos'), an HTTPS URL pointing at a record file, or a 'pkg:' reference. Field overrides on the surrounding FontScheme object take precedence over the resolved scheme.\n\nResolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.source -> default catalog at https://www.pptx.gallery/font-schemes.",
+          "$ref": "#/$defs/CatalogReference",
+          "description": "Font-scheme reference (a bare id or 'name:id') resolved as the base; field overrides on the surrounding FontScheme object take precedence over the resolved scheme.",
           "examples": [
             "aptos",
             "tenorite",
             "seaford",
             "noto-sans",
             "modern-sans",
-            "classic-serif",
-            "https://acme.com/decks/font-schemes/acme.json",
-            "pkg:@acme/decks/font-schemes/acme"
+            "classic-serif"
           ]
         },
         "major": {
@@ -1872,7 +1541,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
         },
         "code": {
           "type": "string",
-          "description": "Abstract role: monospaced font family name used for code blocks and for inline code runs (TextRun.code). No direct OOXML slot. Resolution: this override, then the resolved catalog record's 'code' (for example Consolas for the consolas scheme), then the engine fallback Roboto Mono. Heading and body families are never used as the code fallback."
+          "description": "Abstract role: monospaced font family name used for code blocks and for inline code runs (TextRun.code). No direct OOXML slot. Resolution: this override, then the resolved font-scheme record's 'code' (for example Consolas for the consolas scheme), then the engine fallback Roboto Mono. Heading and body families are never used as the code fallback."
         }
       }
     },
@@ -2389,13 +2058,28 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
         },
         {
           "$ref": "#/$defs/HexColor"
+        },
+        {
+          "$ref": "#/$defs/ImageSource"
         }
       ],
-      "description": "String shorthand for a background. Theme slots ('light1', 'light2', 'dark1', 'dark2') are equivalent to { type: 'theme', slot: value }; hex colors are equivalent to { type: 'solid', color: value }.",
+      "description": "String shorthand for a background. Theme slots ('light1', 'light2', 'dark1', 'dark2') are equivalent to { type: 'theme', slot: value }; hex colors are equivalent to { type: 'solid', color: value }; an image source (starting with 'asset:', 'https://', 'data:', './' or '../') is equivalent to { type: 'image', src: value }, a cover image. Any other string is invalid.",
       "examples": [
         "dark1",
         "light2",
-        "#ffff00"
+        "#ffff00",
+        "asset:cover-photo",
+        "./images/harbour.jpg"
+      ]
+    },
+    "ImageSource": {
+      "type": "string",
+      "pattern": "^(asset:|https://|data:|\\./|\\.\\./)",
+      "description": "An image source in a string shorthand: an 'asset:<id>' reference, an HTTPS URL, a data URI, or a relative path starting with './' or '../' (resolved against the OPF file location).",
+      "examples": [
+        "asset:cover-photo",
+        "https://cdn.acme.com/backgrounds/cover.jpg",
+        "./images/harbour.jpg"
       ]
     },
     "Background": {
@@ -2528,53 +2212,250 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
     },
     "ImageBackground": {
       "type": "object",
-      "description": "Fixed image slide background fill.",
+      "additionalProperties": false,
+      "description": "Picture background: the image fills the whole canvas behind everything and never moves content (to push content aside, use an image block with placement). The string shorthand 'asset:x' (or any image source) is { type: 'image', src: 'asset:x' }, a cover image. Paint order: the colour scheme's default slide background, the picture, then the overlay, then furniture and content.",
       "required": [
         "type",
-        "image"
+        "src"
       ],
       "properties": {
         "type": {
           "type": "string",
           "const": "image",
-          "description": "Fixed image background fill."
+          "description": "Picture background."
         },
-        "image": {
-          "type": "object",
-          "description": "Image fill definition.",
-          "required": [
-            "src"
+        "src": {
+          "type": "string",
+          "description": "Source for the background image: an 'asset:<id>' reference, HTTPS URL, data URI, or a relative path resolved against the OPF file location.",
+          "examples": [
+            "https://cdn.acme.com/backgrounds/cover.jpg",
+            "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA...",
+            "./backgrounds/cover.jpg",
+            "asset:bg-cover"
+          ]
+        },
+        "alt": {
+          "type": "string",
+          "description": "Alternative text. A background with alt is meaningful: PowerPoint export draws it as a full-slide picture at the back that carries the text, so screen readers see it. Without alt it is decorative and exports as the native slide background; the alt text of a referenced asset does not count, so a background is decorative unless it says otherwise."
+        },
+        "fit": {
+          "type": "string",
+          "enum": [
+            "cover",
+            "contain",
+            "stretch",
+            "tile"
           ],
-          "properties": {
-            "src": {
-              "type": "string",
-              "description": "Source for the background image.",
-              "examples": [
-                "https://cdn.acme.com/backgrounds/cover.jpg",
-                "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA...",
-                "./backgrounds/cover.jpg",
-                "asset:bg-cover"
-              ]
-            },
-            "fit": {
-              "type": "string",
-              "enum": [
-                "cover",
-                "contain",
-                "tile"
-              ],
-              "description": "How the image fills the slide background."
-            }
+          "description": "How the picture fills the canvas: 'cover' fills it and crops what overflows around focus; 'contain' shows the whole picture centered over the colour scheme's default background; 'stretch' scales it to the canvas exactly; 'tile' repeats it at its own size from the top-left corner. Default 'cover'."
+        },
+        "focus": {
+          "$ref": "#/$defs/ImageFocus",
+          "description": "Point of the picture to keep in view when 'cover' crops it. Ignored by the other fits."
+        },
+        "opacity": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Picture opacity from 0 (fully transparent) to 1 (fully opaque); the overlay keeps its own opacity. Default 1."
+        },
+        "recolor": {
+          "$ref": "#/$defs/ImageRecolor",
+          "description": "Grayscale or duotone treatment of the picture's pixels, as on an image block: recolor and opacity apply to the pixels, then the overlay is drawn above."
+        },
+        "overlay": {
+          "$ref": "#/$defs/Overlay",
+          "description": "Scrim over the whole picture or a band along one edge (edge, size), beneath furniture and content, for example to keep a title readable over a busy photo."
+        }
+      },
+      "examples": [
+        {
+          "type": "image",
+          "src": "asset:cover-photo"
+        },
+        {
+          "type": "image",
+          "src": "./images/harbour.jpg",
+          "alt": "Container ships at dawn",
+          "focus": {
+            "x": 0.5,
+            "y": 0.7
+          },
+          "overlay": {
+            "color": "dark1",
+            "opacity": 0.4
           }
+        }
+      ]
+    },
+    "ImageFocus": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "x",
+        "y"
+      ],
+      "description": "A point of a picture as fractions of its width and height, from the top-left corner. A cover fit centers this point in the frame as far as the picture still covers the frame, so it always stays in view: { x: 0.5, y: 0.5 } (the default) is a center crop, { x: 0, y: 0 } keeps the top-left corner.",
+      "properties": {
+        "x": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Horizontal position, 0 (left edge) to 1 (right edge)."
+        },
+        "y": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Vertical position, 0 (top edge) to 1 (bottom edge)."
+        }
+      },
+      "examples": [
+        {
+          "x": 0.5,
+          "y": 0.7
+        }
+      ]
+    },
+    "Overlay": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "color",
+        "opacity"
+      ],
+      "description": "Solid scrim over a picture: the whole frame in the frame's shape, or a band along one edge. Shared by image backgrounds and image blocks. Drawn directly above its picture and beneath headings and content; PowerPoint export writes one native shape above the picture.",
+      "properties": {
+        "color": {
+          "$ref": "#/$defs/ColorRef",
+          "description": "Overlay fill color: a hex color (eight-digit hex keeps its alpha), a color-scheme slot or role name, or a 'var:<id>' variable reference."
         },
         "opacity": {
           "type": "number",
           "minimum": 0,
           "maximum": 1,
-          "description": "Background opacity from 0 (fully transparent) to 1 (fully opaque)."
+          "description": "Overlay fill opacity."
+        },
+        "edge": {
+          "type": "string",
+          "enum": [
+            "top",
+            "bottom",
+            "left",
+            "right"
+          ],
+          "description": "Cover only a band along this edge of the frame, for example a caption strip. Backgrounds and rectangle image frames only; on another shape the overlay is not drawn and composition reports unsupported-image-treatment. Omit to cover the whole frame. In a right-to-left deck 'left' and 'right' are the start and end sides."
+        },
+        "size": {
+          "type": "number",
+          "minimum": 0.05,
+          "maximum": 1,
+          "description": "Band share of the frame for an edge overlay. Default 0.3. Ignored without edge."
+        }
+      },
+      "examples": [
+        {
+          "color": "dark1",
+          "opacity": 0.4
+        },
+        {
+          "color": "#000000",
+          "opacity": 0.75,
+          "edge": "bottom",
+          "size": 0.25
+        }
+      ]
+    },
+    "ImagePlacement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "edge"
+      ],
+      "description": "Bleeds an image block to one edge of the slide: the image takes a band along that edge, edge to edge, and the headings and other content compose in the rest of the slide at the normal padding. Only top-level blocks (slides.N.blocks.I) can be placed, at most one per edge; a layout's image placeholder may carry the same placement for the slide's image. Bands are taken in block order, each spanning the free area left by earlier ones. Placement is the only mechanism that moves content aside; a background never does. A slide whose only body is placed images is composed like a cover: its headings center in the free area. In a right-to-left deck 'left' is the start side, drawn at the right.",
+      "properties": {
+        "edge": {
+          "type": "string",
+          "enum": [
+            "left",
+            "right",
+            "top",
+            "bottom"
+          ],
+          "description": "The slide edge the image bleeds to."
+        },
+        "size": {
+          "type": "number",
+          "minimum": 0.1,
+          "maximum": 0.9,
+          "description": "Share of the slide width (left, right) or height (top, bottom) given to the band. Default 0.5."
+        },
+        "inset": {
+          "type": "boolean",
+          "description": "Draw the frame inside the slide padding on every side of the band, like a card, instead of edge to edge. Default false."
+        }
+      },
+      "examples": [
+        {
+          "edge": "left",
+          "size": 0.45
+        },
+        {
+          "edge": "right",
+          "size": 0.4,
+          "inset": true
+        }
+      ]
+    },
+    "ImageBorder": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "color",
+        "width"
+      ],
+      "description": "Solid line along the image frame's shape, centered on the outline with a miter join, like a native picture line. A thick dark border on a rounded portrait frame gives a device bezel.",
+      "properties": {
+        "color": {
+          "$ref": "#/$defs/ColorRef",
+          "description": "Line color: a hex color, a color-scheme slot or role name, or a 'var:<id>' variable reference."
+        },
+        "width": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 64,
+          "description": "Line width in reference pixels at a 720-pixel short edge. 0 removes the line."
         }
       }
     },
+    "ImageRecolor": {
+      "oneOf": [
+        {
+          "type": "string",
+          "const": "grayscale",
+          "description": "Replace each pixel with its luminance, exported as native a:grayscl."
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "dark",
+            "light"
+          ],
+          "properties": {
+            "dark": {
+              "$ref": "#/$defs/ColorRef",
+              "description": "Color at luminance 0."
+            },
+            "light": {
+              "$ref": "#/$defs/ColorRef",
+              "description": "Color at luminance 1."
+            }
+          },
+          "description": "Duotone: map each pixel's luminance linearly from dark to light, exported as native a:duotone."
+        }
+      ],
+      "description": "Color treatment for the image pixels. Luminance uses Rec. 601 weights (0.299, 0.587, 0.114) on sRGB values."
+    },
     "PatternBackground": {
       "type": "object",
       "description": "Fixed pattern slide background fill.",
@@ -2685,7 +2566,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
     },
     "Watermark": {
       "type": "object",
-      "description": "Decorative watermark: an image ('src') or a text stamp ('text'), exactly one of the two, with its opacity. An image is drawn once per slide, contained and centered in a fixed frame (the middle 40% of the slide width and height, from 30% to 70% on each axis). A text watermark is one line of text in the heading font and the theme text color at the given opacity, centered on the slide and rotated 30 degrees counterclockwise (rising to the right), sized to span at most 70% of the slide width and at most 30% of the shorter slide edge in height; it is drawn behind the slide content and above the background and slide image. There is no option to move, scale, rotate or tile either form. PPTX export writes one native picture (image) or one native text box (text) per slide with the opacity as alpha, and import restores the watermark. A string or Asset (no opacity) is the image watermark at opacity 0.08. A watermark object needs opacity and exactly one of src and text; use a plain string or Asset for an image at the default opacity. Use design.watermark = false to disable an inherited watermark.",
+      "description": "Decorative watermark: an image ('src') or a text stamp ('text'), exactly one of the two, with its opacity. An image is drawn once per slide, contained and centered in a fixed frame (the middle 40% of the slide width and height, from 30% to 70% on each axis). A text watermark is one line of text in the heading font and the theme text color at the given opacity, centered on the slide and rotated 30 degrees counterclockwise (rising to the right), sized to span at most 70% of the slide width and at most 30% of the shorter slide edge in height; it is drawn behind the slide content and above the background. There is no option to move, scale, rotate or tile either form. PPTX export writes one native picture (image) or one native text box (text) per slide with the opacity as alpha, and import restores the watermark. A string or Asset (no opacity) is the image watermark at opacity 0.08. A watermark object needs opacity and exactly one of src and text; use a plain string or Asset for an image at the default opacity. Use design.watermark = false to disable an inherited watermark.",
       "additionalProperties": false,
       "required": [
         "opacity"
@@ -2872,17 +2753,15 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           "description": "Optional reference to one or more beats of the deck's narrative (each value is the id of a beat in the narrative record that the root 'narrative' resolves to). A single string declares the slide's primary beat; an array declares that one slide covers multiple beats. Declares the slide's role in the story arc; does not constrain ordering or structure. Core validate warns about a beat id the resolved narrative does not define, and reports a beat that no slide references. Slides without a beat are valid; multiple slides may share a beat."
         },
         "layout": {
-          "type": "string",
-          "description": "Optional. Resolves to the 'id' of a 'layouts' catalog record. When omitted, or when it names an id that no inline record, host catalog or default catalog defines, the slide is composed with no layout record: engines arrange title, subtitle, tag and content automatically, a slide with no body payload is a cover (vertically centered), and design hints apply. A layout never changes what a slide contains. An unresolved id is an `unresolved-layout` diagnostic and a `catalog-reference` warning, never an error. Engines must not substitute a different layout for an omitted one. Accepts a bare id (lowercase kebab-case, e.g. 'title-subtitle'), an HTTPS URL pointing at a record file, or a 'pkg:' reference.\n\nResolution order: inline catalogs.layouts.records[] \u2192 catalogs.layouts.source \u2192 default catalog at https://www.pptx.gallery/layouts.",
+          "$ref": "#/$defs/CatalogReference",
+          "description": "Optional layout: a layouts reference, a bare id ('title-subtitle') or 'name:id' ('acme:hero'). When omitted, the slide is composed with no layout record: engines arrange title, subtitle, tag and content automatically, a slide with no body payload is a cover (vertically centered), and design hints apply; there is no finding. A reference that resolves nowhere is the warning opf/unresolved-reference (and the 'unresolved-reference' diagnostic of resolveSlideContext), the slide composes automatically, and a strict export fails. A layout never changes what a slide contains, and engines never substitute a different layout.",
           "examples": [
             "title",
             "title-subtitle",
             "text-2x",
             "chart-3x",
-            "image-bleed",
             "blank",
-            "https://acme.com/decks/layouts/cover.json",
-            "pkg:@acme/decks/layouts/cover"
+            "acme:hero"
           ]
         },
         "title": {
@@ -2999,7 +2878,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
         },
         "image": {
           "$ref": "#/$defs/Asset",
-          "description": "Full-slide image source. Presence of this field infers type 'image'."
+          "description": "Shorthand for one image block: the picture composes as body content, like { type: 'image', image: value }, with the effective design.imageFit. A layout's image placeholder may place it along an edge (placement). For fit, focus, treatments or an explicit placement use an image block in blocks; for a full-slide picture behind the content use design.background. Presence of this field infers type 'image'."
         },
         "video": {
           "$ref": "#/$defs/Asset",
@@ -3371,6 +3250,63 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "asset:img-diagram"
           ]
         },
+        "fit": {
+          "type": "string",
+          "enum": [
+            "cover",
+            "contain",
+            "stretch"
+          ],
+          "description": "Image payloads only. How the picture fills its frame: 'cover' fills it and crops what overflows around focus; 'contain' shows the whole picture centered; 'stretch' scales it to the frame exactly. Default: the effective design.imageFit, else 'cover'."
+        },
+        "focus": {
+          "$ref": "#/$defs/ImageFocus",
+          "description": "Image payloads only. Point of the picture to keep in view when 'cover' crops it. Ignored by the other fits."
+        },
+        "aspectRatio": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "maximum": 10,
+          "description": "Image payloads only. Width-to-height ratio of the frame: the frame becomes the largest centered box with this ratio inside the block's region, for example 2.39 for a cinematic letterbox or 0.5 for a phone-shaped frame. shape 'circle' always uses 1."
+        },
+        "shape": {
+          "type": "string",
+          "enum": [
+            "rectangle",
+            "rounded",
+            "circle",
+            "hexagon"
+          ],
+          "description": "Image payloads only. Mask applied to the frame, exported as the picture's native preset geometry (rect, roundRect, ellipse, hexagon). 'circle' makes the frame square. Default 'rectangle'."
+        },
+        "cornerRadius": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 0.5,
+          "description": "Image payloads only. Corner radius for shape 'rounded' as a fraction of the frame's shorter side. Default 0.16667, PowerPoint's roundRect default."
+        },
+        "border": {
+          "$ref": "#/$defs/ImageBorder",
+          "description": "Image payloads only. Line along the frame's shape."
+        },
+        "opacity": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Image payloads only. Picture opacity from 0 to 1, exported as a native alphaModFix. The border and overlay keep their own opacity. Default 1."
+        },
+        "recolor": {
+          "$ref": "#/$defs/ImageRecolor",
+          "description": "Image payloads only. Grayscale or duotone treatment of the picture's pixels."
+        },
+        "overlay": {
+          "$ref": "#/$defs/Overlay",
+          "description": "Image payloads only. Scrim over the picture in the frame's shape, or a band along one edge of a rectangle frame."
+        },
+        "placement": {
+          "$ref": "#/$defs/ImagePlacement",
+          "description": "Image payloads only, and only on a top-level block (slides.N.blocks.I), at most one per edge. Bleeds the image to one slide edge; the headings and the other blocks compose in the rest of the slide."
+        },
         "video": {
           "$ref": "#/$defs/Asset",
           "description": "Source for a video item. Engines do not play video: the preview draws a placeholder (a play badge with the asset's title or source as its caption), and PPTX export draws the same placeholder as native shapes linked to an http(s) source, with no embedded media. Native playback is out of scope (docs/programs/release-readiness).",
@@ -4545,7 +4481,36 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
       "properties": {
         "type": {
           "type": "string",
-          "description": "Chart type id. Resolves to the id of a chartTypes catalog record; renderers map that record through mappings.openxml and any renderer-specific mapping they understand. The bundled catalog covers the chart types Aspose.Slides officially supports, plus 'combo' (clustered columns with line series, see 'line' and 'secondaryAxis').",
+          "enum": [
+            "100pct-stacked-area",
+            "100pct-stacked-bar",
+            "100pct-stacked-column",
+            "area",
+            "bar",
+            "box-and-whisker",
+            "column",
+            "combo",
+            "doughnut",
+            "filled-radar",
+            "funnel",
+            "histogram",
+            "line",
+            "line-with-markers",
+            "pareto",
+            "pie",
+            "radar",
+            "radar-with-markers",
+            "scatter",
+            "stacked-area",
+            "stacked-bar",
+            "stacked-column",
+            "stacked-line",
+            "stacked-line-with-markers",
+            "treemap",
+            "waterfall",
+            "world"
+          ],
+          "description": "Chart type, an engine vocabulary validated directly (no catalog lookup): the chart types Aspose.Slides officially supports, plus 'combo' (clustered columns with line series, see 'line' and 'secondaryAxis'). Each engine maps a type to its own chart model; labels and picker groups are catalog display metadata.",
           "examples": [
             "column",
             "bar",
@@ -5470,96 +5435,274 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ],
           "description": "Default solid."
         }
-      },
-      "description": "One explicit cell border."
+      },
+      "description": "One explicit cell border."
+    },
+    "Catalogs": {
+      "type": "object",
+      "description": "The catalog records a document embeds, grouped by the catalog they came from. Each property is a group; inside a group, records are keyed by kind and then by id.\n- 'default': the catalog bare ids come from. It needs a 'source' when it holds records. Omitted: bare ids fall back to the host's default catalog. false: no catalog fallback, so every bare id must be embedded (under 'custom' or 'default').\n- 'custom': the records the document defines itself. It has no source.\n- any other name ('acme'): an extra catalog, identified by its 'source'. The name is the prefix references use ('acme:hero'). Names are lowercase kebab-case; 'default' and 'custom' are reserved.\n\nResolution, for every kind: a bare id resolves in 'custom', then in the records embedded under 'default', then in the catalog the host registered for default.source (the host's default catalog when 'default' is omitted). 'name:id' resolves in that group's records, then in the catalog the host registered for its source. A reference written inside an embedded record (a theme's colorScheme) resolves in that record's own group first. A prefix that names no group is a validation error; a reference that resolves nowhere is the warning opf/unresolved-reference. Engines never fetch a source: hosts register catalogs by their source string, and authoring tools embed every record a document uses when they save it.",
+      "properties": {
+        "default": {
+          "oneOf": [
+            {
+              "allOf": [
+                {
+                  "$ref": "#/$defs/CatalogGroup"
+                },
+                {
+                  "if": {
+                    "anyOf": [
+                      {
+                        "required": [
+                          "layouts"
+                        ]
+                      },
+                      {
+                        "required": [
+                          "themes"
+                        ]
+                      },
+                      {
+                        "required": [
+                          "colorSchemes"
+                        ]
+                      },
+                      {
+                        "required": [
+                          "fontSchemes"
+                        ]
+                      },
+                      {
+                        "required": [
+                          "narratives"
+                        ]
+                      },
+                      {
+                        "required": [
+                          "audiences"
+                        ]
+                      },
+                      {
+                        "required": [
+                          "purposes"
+                        ]
+                      },
+                      {
+                        "required": [
+                          "tones"
+                        ]
+                      }
+                    ]
+                  },
+                  "then": {
+                    "required": [
+                      "source"
+                    ]
+                  }
+                }
+              ]
+            },
+            {
+              "const": false
+            }
+          ],
+          "description": "The catalog bare ids come from: its source and the records of it this document embeds. false turns off the catalog fallback for bare ids.",
+          "examples": [
+            {
+              "source": "https://www.pptx.gallery",
+              "layouts": {
+                "two-column": {
+                  "name": "Two column",
+                  "placeholders": [
+                    {
+                      "type": "title"
+                    },
+                    {
+                      "type": "text"
+                    },
+                    {
+                      "type": "text"
+                    }
+                  ]
+                }
+              }
+            },
+            false
+          ]
+        },
+        "custom": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/CatalogGroup"
+            },
+            {
+              "not": {
+                "required": [
+                  "source"
+                ]
+              }
+            }
+          ],
+          "description": "Records the document defines itself, referenced by bare id. Checked first for every bare id. Forking a catalog record copies it here under a new id, so the change of ownership is visible."
+        }
+      },
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "description": "Group name: lowercase kebab-case. 'default' and 'custom' are reserved."
+      },
+      "additionalProperties": {
+        "allOf": [
+          {
+            "$ref": "#/$defs/CatalogGroup"
+          },
+          {
+            "required": [
+              "source"
+            ]
+          }
+        ],
+        "description": "A named catalog: its source and the records of it this document embeds. References name it as a prefix ('acme:hero')."
+      },
+      "examples": [
+        {
+          "default": {
+            "source": "https://www.pptx.gallery",
+            "themes": {
+              "minimal": {
+                "name": "Minimal",
+                "colorScheme": "cool-horizon",
+                "fontScheme": "aptos"
+              }
+            }
+          },
+          "acme": {
+            "source": "pkg:@acme/opf-catalog",
+            "layouts": {
+              "hero": {
+                "name": "Hero",
+                "placeholders": [
+                  {
+                    "type": "title"
+                  }
+                ]
+              }
+            }
+          },
+          "custom": {
+            "layouts": {
+              "q4-special": {
+                "name": "Q4 special",
+                "placeholders": [
+                  {
+                    "type": "title"
+                  },
+                  {
+                    "type": "chart"
+                  }
+                ]
+              }
+            }
+          }
+        }
+      ]
     },
-    "Catalogs": {
+    "CatalogGroup": {
       "type": "object",
-      "description": "Catalog overrides for the in-document references. Every property is optional. The default catalog for a kind lives at https://www.pptx.gallery/<kind> (e.g. https://www.pptx.gallery/narratives, https://www.pptx.gallery/themes). pptx.gallery is its canonical publisher: GET https://www.pptx.gallery/<kind>/index.json (or https://www.pptx.gallery/<kind> with Accept: application/json) returns a catalog index (https://openpresentation.org/schema/opf-catalog-index/v1) and https://www.pptx.gallery/<kind>/<id>.json returns one record that validates against the kind's companion schema; publisher metadata sits in top-level 'x-*' members that consumers ignore. Engines resolve the default catalog from the pinned snapshot bundled in @openpresentation/opf (spec/catalogs, pinned to a publisher commit and content hash by spec/catalogs/manifest.json), so resolution is deterministic offline and in the cloud; they do not fetch pptx.gallery at run time. For each kind, declaring a 'source' replaces the default registry and/or 'records' adds inline records that take precedence over anything fetched from a source.\n\nResolution order for any reference (e.g. narrative, design.theme): inline catalogs.<kind>.records[] \u2192 catalogs.<kind>.source \u2192 default catalog at https://www.pptx.gallery/<kind>. Every reference resolves to the catalog record's 'id' field. References that are themselves URLs or 'pkg:' references skip the catalog lookup and resolve directly.",
+      "additionalProperties": false,
+      "description": "One catalog group: the catalog's source and the records of it the document embeds, by kind and then by id.",
       "properties": {
-        "narratives": {
-          "$ref": "#/$defs/CatalogEntry",
-          "description": "Catalog of narrative templates. Records validate against https://openpresentation.org/schema/opf-narrative/v1. A custom narrative goes in 'catalogs.narratives.records' and is referenced by its id from the root 'narrative'. Default source: https://www.pptx.gallery/narratives."
+        "source": {
+          "$ref": "#/$defs/CatalogSource"
+        },
+        "layouts": {
+          "$ref": "#/$defs/CatalogRecords",
+          "description": "Layout records keyed by id, each with the fields of https://openpresentation.org/schema/opf-layout/v1. Referenced from Slide.layout."
         },
         "themes": {
-          "$ref": "#/$defs/CatalogEntry",
-          "description": "Catalog of themes. Records validate against https://openpresentation.org/schema/opf-theme/v1. Default source: https://www.pptx.gallery/themes."
+          "$ref": "#/$defs/CatalogRecords",
+          "description": "Theme records keyed by id, each with the fields of https://openpresentation.org/schema/opf-theme/v1. Referenced from design.theme."
         },
         "colorSchemes": {
-          "$ref": "#/$defs/CatalogEntry",
-          "description": "Catalog of color schemes. Records validate against https://openpresentation.org/schema/opf-color-scheme/v1. Default source: https://www.pptx.gallery/color-schemes."
+          "$ref": "#/$defs/CatalogRecords",
+          "description": "Colour-scheme records keyed by id, each with the fields of https://openpresentation.org/schema/opf-color-scheme/v1. Referenced from design.colorScheme and a theme's colorScheme."
         },
         "fontSchemes": {
-          "$ref": "#/$defs/CatalogEntry",
-          "description": "Catalog of font schemes. Records validate against https://openpresentation.org/schema/opf-font-scheme/v1. Default source: https://www.pptx.gallery/font-schemes."
-        },
-        "languages": {
-          "$ref": "#/$defs/CatalogEntry",
-          "description": "Catalog of languages. Records validate against https://openpresentation.org/schema/opf-language/v1. Default source: https://www.pptx.gallery/languages."
-        },
-        "layouts": {
-          "$ref": "#/$defs/CatalogEntry",
-          "description": "Catalog of slide layouts. Records validate against https://openpresentation.org/schema/opf-layout/v1. Default source: https://www.pptx.gallery/layouts."
+          "$ref": "#/$defs/CatalogRecords",
+          "description": "Font-scheme records keyed by id, each with the fields of https://openpresentation.org/schema/opf-font-scheme/v1. Referenced from design.fontScheme, a theme's fontScheme and a language's font schemes."
         },
-        "chartTypes": {
-          "$ref": "#/$defs/CatalogEntry",
-          "description": "Catalog of chart types. Records validate against https://openpresentation.org/schema/opf-chart-type/v1. Default source: https://www.pptx.gallery/chart-types."
+        "narratives": {
+          "$ref": "#/$defs/CatalogRecords",
+          "description": "Narrative records keyed by id, each with the fields of https://openpresentation.org/schema/opf-narrative/v1. Referenced from narrative."
         },
-        "tones": {
-          "$ref": "#/$defs/CatalogEntry",
-          "description": "Catalog of presentation tones. Records validate against https://openpresentation.org/schema/opf-tone/v1. Default source: https://www.pptx.gallery/tones. Referenced from tone."
+        "audiences": {
+          "$ref": "#/$defs/CatalogRecords",
+          "description": "Audience records keyed by id, each with the fields of https://openpresentation.org/schema/opf-audience/v1. Referenced from audience."
         },
         "purposes": {
-          "$ref": "#/$defs/CatalogEntry",
-          "description": "Catalog of presentation purposes. Records validate against https://openpresentation.org/schema/opf-purpose/v1. Default source: https://www.pptx.gallery/purposes. Referenced from purpose."
+          "$ref": "#/$defs/CatalogRecords",
+          "description": "Purpose records keyed by id, each with the fields of https://openpresentation.org/schema/opf-purpose/v1. Referenced from purpose."
         },
-        "audiences": {
-          "$ref": "#/$defs/CatalogEntry",
-          "description": "Catalog of presentation audiences. Records validate against https://openpresentation.org/schema/opf-audience/v1. Default source: https://www.pptx.gallery/audiences. Referenced from audience."
-        },
-        "socialPlatforms": {
-          "$ref": "#/$defs/CatalogEntry",
-          "description": "Catalog of social-media platforms. Records validate against https://openpresentation.org/schema/opf-social-platform/v1. Default source: https://www.pptx.gallery/social-platforms. Referenced via the property keys of any Socials object (Organization.socials, Speaker.socials)."
+        "tones": {
+          "$ref": "#/$defs/CatalogRecords",
+          "description": "Tone records keyed by id, each with the fields of https://openpresentation.org/schema/opf-tone/v1. Referenced from tone."
         }
       }
     },
-    "CatalogEntry": {
+    "CatalogSource": {
+      "type": "string",
+      "pattern": "^(?:https://[^\\s]+|pkg:[^\\s]+)$",
+      "description": "Identity of a catalog: an HTTPS URL ('https://www.pptx.gallery') or a package reference ('pkg:@acme/opf-catalog'). It names the catalog; engines never fetch or install it. A host registers the catalog's records under this exact string, and copying slides between documents matches groups by it.",
+      "examples": [
+        "https://www.pptx.gallery",
+        "pkg:@acme/opf-catalog"
+      ]
+    },
+    "CatalogRecords": {
       "type": "object",
-      "description": "A catalog override for one record kind. 'source' replaces the default registry; 'records' adds inline records that take precedence over anything fetched from a source. Either or both may be provided; both omitted means the kind uses its default catalog.",
-      "properties": {
-        "source": {
-          "oneOf": [
+      "description": "Embedded records of one kind, keyed by id. The key is the record's id; an embedded record carries no '$schema', 'id', origin or digest. Catalog display metadata ('x-*' members) is stripped when a record is embedded.",
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "not": {
+          "anyOf": [
             {
-              "$ref": "#/$defs/CatalogSource"
+              "required": [
+                "$schema"
+              ]
             },
             {
-              "type": "array",
-              "items": {
-                "$ref": "#/$defs/CatalogSource"
-              },
-              "minItems": 1,
-              "description": "Ordered search path of sources. The engine tries each in order; first match wins. The default catalog for the kind is appended implicitly at the end."
+              "required": [
+                "id"
+              ]
             }
-          ],
-          "description": "Single source or an ordered search path of sources. When omitted, the engine falls back to the default catalog at https://www.pptx.gallery/<kind>, resolved from its bundled snapshot. Engines never fetch a source. The host loads the records itself and passes them to the renderer and exporter as a 'catalogSources' map from the source string to its records; a source with no entry in that map contributes no records, except the default catalog's own URL and the '@openpresentation/opf' package, which resolve from the bundled snapshot."
+          ]
         },
-        "records": {
-          "type": "array",
-          "items": {
-            "type": "object"
-          },
-          "description": "Inline catalog records embedded in this OPF document. Each record validates against the kind's companion schema (e.g. https://openpresentation.org/schema/opf-narrative/v1 for narratives). Inline records win over anything resolved from 'source' and over the default catalog."
-        }
+        "description": "One embedded record: the fields of the kind's companion schema without '$schema' and 'id'."
       }
     },
-    "CatalogSource": {
+    "CatalogReference": {
+      "type": "string",
+      "pattern": "^(?:[a-z][a-z0-9-]*:)?[a-z][a-z0-9-]*$",
+      "description": "A content reference: a bare id ('two-column') or 'name:id' ('acme:hero'), where the prefix names a group of 'catalogs'. URLs and 'pkg:' strings are not references; a named catalog group replaces them. See Catalogs for the resolution order.",
+      "examples": [
+        "two-column",
+        "acme:hero",
+        "default:minimal",
+        "custom:q4-special"
+      ]
+    },
+    "LanguageTag": {
       "type": "string",
-      "description": "Catalog source location. Accepts:\n- A bare URL pointing at a catalog directory (e.g. 'https://acme.com/decks/narratives'); record ids resolve to '<base>/<id>.json'.\n- A URL pointing at an index file (e.g. 'https://acme.com/decks/narratives/index.json'); records are resolved relative to the index file's directory and the index entries describe what's available. Index files follow https://openpresentation.org/schema/opf-catalog-index/v1; the default catalog's index is https://www.pptx.gallery/<kind>/index.json.\n- A package reference of the form 'pkg:<package>[/<subpath>]'. 'pkg:@openpresentation/opf/...' resolves from the bundled snapshot; any other package reference needs the host to supply its records in 'catalogSources'.\n\nEngines never fetch or install anything for a source: the host supplies the records of every source other than the bundled default, as a 'catalogSources' map from the source string to its records.",
+      "pattern": "^(?:[A-Za-z]{2,3}|[iIxX])(?:-[A-Za-z0-9]{1,8})*$",
+      "description": "A BCP-47 language tag ('en-US', 'ja', 'zh-Hans', 'sr-Latn-ME'), an engine vocabulary. Use 'en-GB' for UK English; 'en-UK' is not a valid region.",
       "examples": [
-        "https://www.pptx.gallery/narratives",
-        "https://acme.com/decks/narratives/index.json",
-        "pkg:@acme/decks/narratives",
-        "pkg:pptx-gallery"
+        "en-US",
+        "en-GB",
+        "ja",
+        "zh-Hans",
+        "ar-SA"
       ]
     },
     "Composition": {
@@ -5628,7 +5771,7 @@ var audience = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-audience/v1",
   "title": "Audience",
-  "description": "Schema for audience records in the pptx.gallery library. Each record names an audience archetype (e.g. 'executive', 'engineering-team', 'investor') and carries seniority, technical-fluency, decision-power, and attention-budget hints used by AI-driven generation. Audiences are referenced from OPF documents via audience; the engine resolves the reference against catalogs.audiences (inline) \u2192 catalogs.audiences.source \u2192 the default catalog at https://www.pptx.gallery/audiences. The audience field also accepts free-form strings; this catalog is for engine-aware audience archetypes that carry generation hints.",
+  "description": "Schema for audience records. Each record names an audience archetype (e.g. 'executive', 'engineering-team', 'investor') and carries seniority, technical-fluency, decision-power, and attention-budget hints used by AI-driven generation. Documents reference an audience from 'audience', which also accepts free-form text.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",
   "required": [
     "$schema",
@@ -5639,12 +5782,12 @@ var audience = {
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-audience/v1",
-      "description": "Identifies this record as an audience in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a audience record. Required in a published file; an embedded copy omits it."
     },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this audience via audience. Lowercase kebab-case.",
+      "description": "The audience's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field.",
       "examples": [
         "executive",
         "board",
@@ -5674,29 +5817,6 @@ var audience = {
         "Regulators"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "replacedBy"
-      ],
-      "description": "Present when this audience is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated audience record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "summary": {
       "type": "string",
       "description": "One-sentence positioning of the audience \u2014 who they are and what they care about.",
@@ -5753,7 +5873,7 @@ var audience = {
       "items": {
         "type": "string"
       },
-      "description": "Soft cross-link: narrative-catalog ids that work well for this audience. Used by picker UIs to suggest narratives once an audience is chosen. Validators warn on unknown ids; never error.",
+      "description": "Soft cross-link: ids of narratives in the same catalog that work well for this audience. Used by picker UIs to suggest narratives once an audience is chosen. Never resolved, embedded or validated as references.",
       "examples": [
         [
           "scqa",
@@ -5767,7 +5887,7 @@ var audience = {
       "items": {
         "type": "string"
       },
-      "description": "Soft cross-link: tone-catalog ids that work well for this audience.",
+      "description": "Soft cross-link: ids of tones in the same catalog that work well for this audience. Never resolved, embedded or validated as references.",
       "examples": [
         [
           "formal",
@@ -5823,7 +5943,7 @@ var purpose = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-purpose/v1",
   "title": "Purpose",
-  "description": "Schema for purpose records in the pptx.gallery library. Each record names a presentation objective such as informing, aligning, persuading, driving a decision, or selling. Purposes are referenced from OPF documents via purpose; the engine resolves the reference against catalogs.purposes (inline) \u2192 catalogs.purposes.source \u2192 the default catalog at https://www.pptx.gallery/purposes. The purpose field also accepts free-form strings and inline Purpose objects.",
+  "description": "Schema for purpose records. Each record names a presentation objective such as informing, aligning, persuading, driving a decision, or selling. Documents reference a purpose from 'purpose', which also accepts free-form text and inline Purpose objects.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",
   "required": [
     "$schema",
@@ -5834,12 +5954,12 @@ var purpose = {
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-purpose/v1",
-      "description": "Identifies this record as a purpose in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a purpose record. Required in a published file; an embedded copy omits it."
     },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this purpose via purpose. Lowercase kebab-case.",
+      "description": "The purpose's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field.",
       "examples": [
         "inform",
         "decide",
@@ -5862,29 +5982,6 @@ var purpose = {
         "Persuade"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "replacedBy"
-      ],
-      "description": "Present when this purpose is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated purpose record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "summary": {
       "type": "string",
       "description": "One-sentence positioning of the purpose \u2014 what this deck is trying to accomplish."
@@ -5914,14 +6011,14 @@ var purpose = {
       "items": {
         "type": "string"
       },
-      "description": "Soft cross-link: narrative-catalog ids that work well for this purpose."
+      "description": "Soft cross-link: ids of narratives in the same catalog that work well for this purpose. Never resolved, embedded or validated as references."
     },
     "recommendedTones": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Soft cross-link: tone-catalog ids that work well for this purpose."
+      "description": "Soft cross-link: ids of tones in the same catalog that work well for this purpose. Never resolved, embedded or validated as references."
     },
     "tags": {
       "type": "array",
@@ -5957,7 +6054,7 @@ var tone = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-tone/v1",
   "title": "Tone",
-  "description": "Schema for tone records in the pptx.gallery library. Each record names a presentation tone (e.g. 'formal', 'casual', 'inspirational') and carries voice cues, anti-patterns, and sample phrases that AI-driven generation uses to shape output. Tones are referenced from OPF documents via tone; the engine resolves the reference against catalogs.tones (inline) \u2192 catalogs.tones.source \u2192 the default catalog at https://www.pptx.gallery/tones.",
+  "description": "Schema for tone records. Each record names a presentation tone (e.g. 'formal', 'casual', 'inspirational') and carries voice cues, anti-patterns, and sample phrases that AI-driven generation uses to shape output. Documents reference a tone from 'tone'.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",
   "required": [
     "$schema",
@@ -5968,12 +6065,12 @@ var tone = {
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-tone/v1",
-      "description": "Identifies this record as a tone in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a tone record. Required in a published file; an embedded copy omits it."
     },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this tone via tone. Lowercase kebab-case.",
+      "description": "The tone's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field.",
       "examples": [
         "formal",
         "casual",
@@ -5997,29 +6094,6 @@ var tone = {
         "Conversational"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "replacedBy"
-      ],
-      "description": "Present when this tone is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated tone record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "summary": {
       "type": "string",
       "description": "One-sentence positioning of the tone \u2014 when to reach for it.",
@@ -6082,7 +6156,7 @@ var tone = {
       "items": {
         "type": "string"
       },
-      "description": "Soft cross-link: narrative-catalog ids this tone pairs well with. Used by picker UIs to suggest narratives once a tone is chosen. Validators warn on unknown ids; never error.",
+      "description": "Soft cross-link: ids of narratives in the same catalog this tone pairs well with. Used by picker UIs to suggest narratives once a tone is chosen. Never resolved, embedded or validated as references.",
       "examples": [
         [
           "board-meeting",
@@ -6139,7 +6213,7 @@ var theme = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-theme/v1",
   "title": "Theme",
-  "description": "Schema for theme records in the pptx.gallery library. Each theme is a small, named bundle that pairs a color scheme, a font scheme, a default theme-controlled background, and a slide size. Themes are referenced from OPF documents via design.theme or design.theme.id; the engine resolves the reference against catalogs.themes (inline) \u2192 catalogs.themes.source \u2192 the default catalog at https://www.pptx.gallery/themes. Inline overrides on design.colorScheme / design.fontScheme / design.background / design.dimensions take precedence over a resolved theme.",
+  "description": "Schema for theme records. Each theme is a small, named bundle that pairs a color scheme, a font scheme, a default theme-controlled background, and a slide size. Documents reference a theme from design.theme; design.colorScheme, design.fontScheme, design.background and design.dimensions take precedence over the resolved theme. The theme's own colorScheme and fontScheme references resolve in the theme's group first, so a catalog's theme finds that catalog's schemes.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",
   "required": [
     "$schema",
@@ -6150,12 +6224,12 @@ var theme = {
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-theme/v1",
-      "description": "Identifies this record as a theme in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a theme record. Required in a published file; an embedded copy omits it."
     },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this theme via design.theme. Lowercase kebab-case.",
+      "description": "The theme's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field.",
       "examples": [
         "minimal",
         "classic",
@@ -6173,29 +6247,6 @@ var theme = {
         "Bold"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "replacedBy"
-      ],
-      "description": "Present when this theme is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated theme record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "summary": {
       "type": "string",
       "description": "One-sentence positioning of the theme \u2014 when to reach for it.",
@@ -6213,7 +6264,8 @@ var theme = {
     },
     "colorScheme": {
       "type": "string",
-      "description": "Catalog reference to the theme's default color scheme \u2014 resolved against catalogs.colorSchemes the same way design.colorScheme or design.colorScheme.id is. Accepts a bare id, HTTPS URL, or 'pkg:' reference.",
+      "pattern": "^(?:[a-z][a-z0-9-]*:)?[a-z][a-z0-9-]*$",
+      "description": "The theme's default colour scheme: a reference (a bare id or 'name:id') resolved like design.colorScheme, but in the theme's own catalogs group first.",
       "examples": [
         "cool-horizon",
         "boost",
@@ -6222,7 +6274,8 @@ var theme = {
     },
     "fontScheme": {
       "type": "string",
-      "description": "Catalog reference to the theme's default font scheme \u2014 resolved against catalogs.fontSchemes the same way design.fontScheme or design.fontScheme.id is. Accepts a bare id, HTTPS URL, or 'pkg:' reference.",
+      "pattern": "^(?:[a-z][a-z0-9-]*:)?[a-z][a-z0-9-]*$",
+      "description": "The theme's default font scheme: a reference (a bare id or 'name:id') resolved like design.fontScheme, but in the theme's own catalogs group first.",
       "examples": [
         "aptos",
         "tenorite",
@@ -6344,7 +6397,7 @@ var layout = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-layout/v1",
   "title": "Slide Layout",
-  "description": "Schema for slide-layout records in the pptx.gallery library. Each record describes a semantic slide layout \u2014 what regions it exposes and what content kinds those regions are intended to hold. Layouts are referenced from OPF documents via Slide.layout; the engine resolves the reference against catalogs.layouts (inline) \u2192 catalogs.layouts.source \u2192 the default catalog at https://www.pptx.gallery/layouts. Free-form custom layout names that don't resolve through any catalog fall through to engine-defined layouts.",
+  "description": "Schema for slide-layout records. Each record describes a semantic slide layout: what regions it exposes, what content kinds those regions are intended to hold, how they are arranged (composition) and its design hints. Documents reference a layout from Slide.layout; a slide without a layout, or whose layout resolves nowhere, composes automatically.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",
   "required": [
     "$schema",
@@ -6355,17 +6408,17 @@ var layout = {
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-layout/v1",
-      "description": "Identifies this record as a slide layout in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a layout record. Required in a published file; an embedded copy omits it."
     },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this layout via Slide.layout. Lowercase kebab-case.",
+      "description": "The layout's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field.",
       "examples": [
         "title",
         "title-subtitle",
         "chart-1x",
-        "image-bleed"
+        "image-focus"
       ]
     },
     "name": {
@@ -6378,29 +6431,6 @@ var layout = {
         "Image Bleed"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "replacedBy"
-      ],
-      "description": "Present when this layout is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated layout record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "summary": {
       "type": "string",
       "description": "One-sentence positioning of the layout \u2014 when to reach for it.",
@@ -6418,7 +6448,7 @@ var layout = {
     },
     "design": {
       "$ref": "#/$defs/DesignHints",
-      "description": "The layout's design hints, with the same keys and values as the deck's design and a slide's design (a slide overrides exactly what its layout sets, by the same name). An absent key means the layout has no opinion. Every key is applied from the record as the lowest-precedence default, per key: the slide's design, then the deck's design, then this record's design, then the engine default, so a layout value nobody overrides is honored without copying it anywhere (a layout's composition.mode still ranks above contentDirection; slideImage.position is the fallback position of a slide image the layout reserves). Composition, the renderer and the PPTX exporter all read the one result."
+      "description": "The layout's design hints, with the same keys and values as the deck's design and a slide's design (a slide overrides exactly what its layout sets, by the same name). An absent key means the layout has no opinion. Every key is applied from the record as the lowest-precedence default, per key: the slide's design, then the deck's design, then this record's design, then the engine default, so a layout value nobody overrides is honored without copying it anywhere (a layout's composition.mode still ranks above contentDirection). Composition, the renderer and the PPTX exporter all read the one result."
     },
     "placeholders": {
       "type": "array",
@@ -6489,6 +6519,18 @@ var layout = {
         "type"
       ],
       "description": "A single region inside a slide layout. Title, subtitle, and tag placeholders bind to the corresponding Slide fields; every other placeholder describes the content kind that region holds. The array order in the surrounding 'placeholders' field preserves layout region order.",
+      "if": {
+        "required": [
+          "placement"
+        ]
+      },
+      "then": {
+        "properties": {
+          "type": {
+            "const": "image"
+          }
+        }
+      },
       "properties": {
         "type": {
           "type": "string",
@@ -6508,6 +6550,40 @@ var layout = {
             "timeline"
           ],
           "description": "The content kind of the region. This is the one OPF content-kind vocabulary: the same words name a slide's payload fields (text, items, image, video, chart, table, code, metric, quote, timeline). 'title', 'subtitle' and 'tag' are the heading kinds and bind to Slide.title, Slide.subtitle and Slide.tag. 'text' holds text and bullets; 'list' holds items. 'image' is filled by an image payload and 'video' by a video payload. 'metric', 'quote', 'timeline', 'chart', 'table' and 'code' are filled by the payload of the same name; a metric region shows the metric payload with its optional label, description, unit, delta, trend and sentiment."
+        },
+        "placement": {
+          "$ref": "#/$defs/ImagePlacement",
+          "description": "Image placeholders only. Bleeds the slide's image for this region to one slide edge, as an image block's placement does: the n-th image placeholder places the slide's n-th top-level image (Slide.image or an image block in blocks) unless that block sets its own placement. The headings and the other content compose in the rest of the slide."
+        }
+      }
+    },
+    "ImagePlacement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "edge"
+      ],
+      "description": "The same object as ImagePlacement in opf.schema.json: a band along one slide edge for the image, edge to edge, with the rest of the slide left to the headings and the other content.",
+      "properties": {
+        "edge": {
+          "type": "string",
+          "enum": [
+            "left",
+            "right",
+            "top",
+            "bottom"
+          ],
+          "description": "The slide edge the image bleeds to. In a right-to-left deck 'left' is the start side, drawn at the right."
+        },
+        "size": {
+          "type": "number",
+          "minimum": 0.1,
+          "maximum": 0.9,
+          "description": "Share of the slide width (left, right) or height (top, bottom) given to the band. Default 0.5."
+        },
+        "inset": {
+          "type": "boolean",
+          "description": "Draw the frame inside the slide padding on every side of the band instead of edge to edge. Default false."
         }
       }
     },
@@ -6557,13 +6633,14 @@ var layout = {
           ],
           "description": "Where the primary chart sits relative to the other body content. Composition applies it below the slide's and the deck's design.chartPrimary, with the semantics described there."
         },
-        "imageFill": {
+        "imageFit": {
           "type": "string",
           "enum": [
-            "crop",
-            "fit"
+            "cover",
+            "contain",
+            "stretch"
           ],
-          "description": "How images fill their region: 'crop' covers the region, 'fit' shows the whole image."
+          "description": "Default fit of the slide's image blocks: 'cover' fills the frame and crops around focus, 'contain' shows the whole picture, 'stretch' scales it to the frame."
         },
         "listBullet": {
           "type": "string",
@@ -6572,27 +6649,6 @@ var layout = {
             "image"
           ],
           "description": "Marker style of lists: 'character' draws the glyph, 'image' draws the deck's icon logo as a picture bullet."
-        },
-        "slideImage": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": [
-            "position"
-          ],
-          "description": "A slide-level image region the layout reserves, separate from any content image. Its presence is what lets a deck-wide design.slideImage apply to slides on this layout. The image itself comes from the slide or the deck design.",
-          "properties": {
-            "position": {
-              "type": "string",
-              "enum": [
-                "background",
-                "top",
-                "bottom",
-                "left",
-                "right"
-              ],
-              "description": "Where the slide-level image sits relative to the content. 'background' is a full-bleed image behind the content; the other positions give the image a band along that edge. Used when the slide's or deck's design.slideImage gives no position."
-            }
-          }
         }
       }
     },
@@ -6662,7 +6718,7 @@ var chartType = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-chart-type/v1",
   "title": "Chart Type",
-  "description": `Schema for chart-type records in the pptx.gallery catalog. The bundled catalog holds one record per chart type that Aspose.Slides officially supports (see mappings.renderers["aspose-slides"].chartType), plus the column-and-line combination 'combo' (mappings.openxml.composition "mixed"). Each record names a chart variant, its Open XML mapping, how many data series it expects and how pickers group it. Chart types are referenced from OPF chart content payloads; the engine resolves the reference against catalogs.chartTypes (inline) -> catalogs.chartTypes.source -> the default catalog at https://www.pptx.gallery/chart-types.`,
+  "description": `Schema for chart-type records: display metadata for chart pickers (name, group, expected series, complexity) and the Open XML mapping a picker can describe. One record per chart type that Aspose.Slides officially supports (see mappings.renderers["aspose-slides"].chartType), plus the column-and-line combination 'combo'. A document's chart.type is an engine vocabulary validated directly; engines never look a chart-type record up. pptx.gallery publishes these records and @openpresentation/opf/catalog ships them as catalogDisplay.chartTypes.`,
   "type": "object",
   "additionalProperties": false,
   "patternProperties": {
@@ -6685,7 +6741,7 @@ var chartType = {
     "id": {
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this chart type (`chart.type`). Lowercase kebab-case. Chart type ids may start with a digit (e.g., '100pct-stacked-column', '3d-column') to mirror conventional chart naming.",
+      "description": "The chart-type value (`chart.type`) this record describes. Lowercase kebab-case; it may start with a digit (e.g., '100pct-stacked-column') to mirror conventional chart naming.",
       "examples": [
         "column",
         "bar",
@@ -6724,10 +6780,6 @@ var chartType = {
       "$ref": "#/$defs/ChartTypeMappings",
       "description": "Canonical and optional renderer-specific mappings used by engines to render this chart type."
     },
-    "deprecation": {
-      "$ref": "#/$defs/ChartTypeDeprecation",
-      "description": "Present when this chart type is deprecated. A deprecated record stays resolvable so existing documents keep validating, validators warn when a document references it, and pickers and generators should not offer it. The bundled default catalog holds no deprecated records; a publisher or an inline `catalogs.chartTypes.records` entry can still use the field."
-    },
     "group": {
       "type": "string",
       "description": "Top-level grouping in the chart picker.",
@@ -6825,35 +6877,6 @@ var chartType = {
     }
   },
   "$defs": {
-    "ChartTypeDeprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "replacedBy"
-      ],
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z0-9][a-z0-9-]*$",
-          "description": "Id of the non-deprecated chart type that documents should reference instead.",
-          "examples": [
-            "column",
-            "stacked-column"
-          ]
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog.",
-          "examples": [
-            "0.12.0"
-          ]
-        }
-      }
-    },
     "ChartTypeMappings": {
       "type": "object",
       "additionalProperties": false,
@@ -6973,7 +6996,7 @@ var narrative = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-narrative/v1",
   "title": "Narrative Template",
-  "description": "Schema for narrative template files in the openpresentation.org catalog. A narrative is a plan: a named story arc (e.g. 'problem-solution', 'scqa') as an ordered list of beats, each saying what its slide must do. A document points at one with the string 'narrative' (a catalog id, an HTTPS URL or a 'pkg:' reference) and links its slides to beats with 'slides[].beat'. A custom narrative is a record in 'catalogs.narratives.records'. Core validate warns about a 'slides[].beat' id the resolved narrative does not define (opf/unknown-beat) and about a root 'duration' outside this record's 'duration' range (opf/duration-outside-narrative), and reports a beat no slide references (opf/unused-beat).",
+  "description": "Schema for narrative records. A narrative is a plan: a named story arc (e.g. 'problem-solution', 'scqa') as an ordered list of beats, each saying what its slide must do. A document points at one with the string 'narrative' and links its slides to beats with 'slides[].beat'; a narrative the document defines itself is a record in catalogs.custom.narratives. Core validate warns about a 'slides[].beat' id the resolved narrative does not define (opf/unknown-beat) and about a root 'duration' outside this record's 'duration' range (opf/duration-outside-narrative), and reports a beat no slide references (opf/unused-beat).\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",
   "required": [
     "$schema",
@@ -6984,40 +7007,18 @@ var narrative = {
   "properties": {
     "$schema": {
       "type": "string",
-      "const": "https://openpresentation.org/schema/opf-narrative/v1"
+      "const": "https://openpresentation.org/schema/opf-narrative/v1",
+      "description": "Identifies a published record file as a narrative record. Required in a published file; an embedded copy omits it."
     },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this template, e.g. 'problem-solution'. Lowercase kebab-case."
+      "description": "The narrative's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field."
     },
     "name": {
       "type": "string",
       "description": "Human-readable template name, e.g. 'Problem \u2192 Solution'."
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "replacedBy"
-      ],
-      "description": "Present when this narrative is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated narrative record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "summary": {
       "type": "string",
       "description": "One-sentence description of when and why to use this narrative."
@@ -7195,7 +7196,7 @@ var socialPlatform = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-social-platform/v1",
   "title": "Social Platform",
-  "description": "Schema for social-platform records in the pptx.gallery library. Each record describes a single social-media platform \u2014 its base URL, profile-URL pattern, handle prefix, and brand color. Records are referenced from OPF documents indirectly: the property keys of any Socials object (Organization.socials, Speaker.socials) match record ids, and engines use the catalog record's URL patterns and handle prefix to format and link the profile URL. The brand color is catalog metadata for authoring UIs: engines (opf-render, opf-pptx) render the profile URL, not brand colors. The engine resolves references against catalogs.socialPlatforms (inline) \u2192 catalogs.socialPlatforms.source \u2192 the default catalog at https://www.pptx.gallery/social-platforms.",
+  "description": "Schema for social-platform records: display metadata for authoring UIs (name, brand color, handle example) alongside the URL patterns. The keys of a Socials object are an engine vocabulary validated directly; engines link a handle with the patterns in spec/reference/engine-vocabularies.json and never look a social-platform record up. pptx.gallery publishes these records and @openpresentation/opf/catalog ships them as catalogDisplay.socialPlatforms.",
   "type": "object",
   "required": [
     "$schema",
@@ -7211,7 +7212,7 @@ var socialPlatform = {
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this platform \u2014 appears as a property key on Socials objects. Lowercase kebab-case.",
+      "description": "The social platform's key, as written in a Socials object. Lowercase kebab-case.",
       "examples": [
         "linkedin",
         "x",
@@ -7241,29 +7242,6 @@ var socialPlatform = {
         "Bluesky"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "replacedBy"
-      ],
-      "description": "Present when this social platform is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated social platform record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "summary": {
       "type": "string",
       "description": "One-sentence positioning of the platform \u2014 what it's used for and who's on it.",
@@ -7392,7 +7370,7 @@ var language = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-language/v1",
   "title": "Language",
-  "description": "Schema for language records in the pptx.gallery library. Each record names a presentation language, carries a BCP-47 language tag, and pairs it with sensible default font schemes for PowerPoint and Google Slides output. Languages are referenced from OPF documents via language; the engine resolves the reference against catalogs.languages (inline) \u2192 catalogs.languages.source \u2192 the default catalog at https://www.pptx.gallery/languages. The presentation language field also accepts BCP-47 tags directly or inline Language objects for engine-aware language records that carry default-font hints.",
+  "description": "Schema for language records: display metadata for the language pickers of authoring tools (name, ISO code, the default font schemes a picker suggests). The document's 'language' is an engine vocabulary, a BCP-47 tag validated directly; engines never look a language record up, and their script, direction, OOXML tag and default script fonts come from spec/reference/engine-vocabularies.json. pptx.gallery publishes these records and @openpresentation/opf/catalog ships them as catalogDisplay.languages.",
   "type": "object",
   "required": [
     "$schema",
@@ -7409,7 +7387,7 @@ var language = {
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this language via language. Lowercase kebab-case.",
+      "description": "The record's id in the gallery's language catalog, lowercase kebab-case. Documents name a language by its BCP-47 tag ('bcp47'), never by this id.",
       "examples": [
         "english",
         "spanish",
@@ -7427,29 +7405,6 @@ var language = {
         "Chinese (simplified)"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "replacedBy"
-      ],
-      "description": "Present when this language is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated language record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "code": {
       "type": "string",
       "description": "ISO 639-3 (or 639-2) three-letter language code. Carried for engines that prefer ISO codes.",
@@ -7475,7 +7430,7 @@ var language = {
     },
     "ooxmlLang": {
       "type": "string",
-      "description": "Curated culture tag for OOXML text-run language attributes (a:rPr/@lang, a:endParaRPr/@lang), in the language-[Script-]REGION form Office recognizes (e.g. 'ja-JP', 'ar-SA', 'ms-MY', 'nb-NO', 'fil-PH', 'zh-CN'). Engines emit it instead of 'bcp47' when the document names the language by catalog id or by a tag without a region; a region-bearing tag written by the author is emitted as written. Curated rather than inferred so output does not depend on the runtime's locale data.",
+      "description": "Curated culture tag for OOXML text-run language attributes (a:rPr/@lang, a:endParaRPr/@lang), in the language-[Script-]REGION form Office recognizes (e.g. 'ja-JP', 'ar-SA', 'ms-MY', 'nb-NO', 'fil-PH', 'zh-CN'). Engines emit it instead of 'bcp47' for a tag without a region; a region-bearing tag written by the author is emitted as written. Display metadata here: engines take the curated tag from their language vocabulary. Curated rather than inferred so output does not depend on the runtime's locale data.",
       "examples": [
         "en-US",
         "ja-JP",
@@ -7491,7 +7446,7 @@ var language = {
         "ltr",
         "rtl"
       ],
-      "description": "Base text direction for the language. When omitted, engines derive it from the script: Arabic (Arab), Hebrew (Hebr), Syriac (Syrc), Thaana (Thaa), N'Ko (Nkoo), Adlam (Adlm), Samaritan (Samr), Mandaic (Mand) and Hanifi Rohingya (Rohg) are right-to-left; every other script is left-to-right. Bundled language records state it explicitly.",
+      "description": "Base text direction for the language. When omitted, engines derive it from the script: Arabic (Arab), Hebrew (Hebr), Syriac (Syrc), Thaana (Thaa), N'Ko (Nkoo), Adlam (Adlm), Samaritan (Samr), Mandaic (Mand) and Hanifi Rohingya (Rohg) are right-to-left; every other script is left-to-right. The engine language vocabulary (spec/reference/engine-vocabularies.json) states it for the tags it knows.",
       "examples": [
         "ltr",
         "rtl"
@@ -7499,7 +7454,7 @@ var language = {
     },
     "script": {
       "type": "string",
-      "description": "ISO 15924 script code of the language's writing system. The script selects the OOXML font slot the language's text uses: East Asian scripts (Hans, Hant, Hani, Jpan, Kore, Hang, Hira, Kana, Bopo, Yiii) use the eastAsian slot; complex scripts (for example Arab, Hebr, Syrc, Thaa, Deva, Beng, Guru, Gujr, Orya, Taml, Telu, Knda, Mlym, Sinh, Thai, Laoo, Tibt, Mymr, Khmr, Mong) use the complexScript slot; every other script (Latn, Cyrl, Grek, Armn, Geor, Ethi, ...) uses the latin slot. When omitted, engines infer it from the BCP-47 tag. Bundled language records state it explicitly. See docs/programs/font-fidelity-everywhere/script-font-model.md.",
+      "description": "ISO 15924 script code of the language's writing system. The script selects the OOXML font slot the language's text uses: East Asian scripts (Hans, Hant, Hani, Jpan, Kore, Hang, Hira, Kana, Bopo, Yiii) use the eastAsian slot; complex scripts (for example Arab, Hebr, Syrc, Thaa, Deva, Beng, Guru, Gujr, Orya, Taml, Telu, Knda, Mlym, Sinh, Thai, Laoo, Tibt, Mymr, Khmr, Mong) use the complexScript slot; every other script (Latn, Cyrl, Grek, Armn, Geor, Ethi, ...) uses the latin slot. When omitted, engines infer it from the BCP-47 tag. The engine language vocabulary (spec/reference/engine-vocabularies.json) states it for the tags it knows. See docs/programs/font-fidelity-everywhere/script-font-model.md.",
       "examples": [
         "Latn",
         "Cyrl",
@@ -7516,7 +7471,7 @@ var language = {
     },
     "fontScheme": {
       "type": "string",
-      "description": "Default font-scheme id for this language when targeting PowerPoint output. Resolves against catalogs.fontSchemes the same way design.fontScheme or design.fontScheme.id does. Its major/minor families fill the language's script slot (eastAsian or complexScript, chosen by 'script') unless the effective design font scheme sets that slot itself; the latin slot always follows the design font scheme.",
+      "description": "The font-scheme id a picker suggests for this language when targeting PowerPoint output. Display metadata: engines take a language's default script fonts from their own vocabulary.",
       "examples": [
         "aptos",
         "microsoft-yahei",
@@ -7525,7 +7480,7 @@ var language = {
     },
     "googleFontScheme": {
       "type": "string",
-      "description": "Default font-scheme id for this language when targeting Google Slides output. Resolves against catalogs.fontSchemes the same way design.fontScheme or design.fontScheme.id does. Used in place of 'fontScheme' when resolving script fonts for Google Slides output.",
+      "description": "The font-scheme id a picker suggests for this language when targeting Google Slides output. Display metadata.",
       "examples": [
         "roboto",
         "noto-sans",
@@ -7603,7 +7558,7 @@ var colorScheme = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-color-scheme/v1",
   "title": "Color Scheme",
-  "description": "Schema for color-scheme records in the pptx.gallery library. Each scheme is a named palette with the twelve PowerPoint color slots (six accents, two darks, two lights, plus hyperlink and followed-hyperlink), suitable for being mapped directly into OOXML theme XML. Color schemes are referenced from OPF documents via design.colorScheme or design.colorScheme.id; the engine resolves the reference against catalogs.colorSchemes (inline) -> catalogs.colorSchemes.source -> the default catalog at https://www.pptx.gallery/color-schemes. Slot overrides on design.colorScheme take precedence over the resolved scheme.\n\nThe slot fields here mirror the inline-override fields on the in-document ColorScheme type (in opf.schema.json), so library entries and inline OPF overrides are interchangeable.",
+  "description": "Schema for color-scheme records. Each scheme is a named palette with the twelve PowerPoint color slots (six accents, two darks, two lights, plus hyperlink and followed-hyperlink), suitable for being mapped directly into OOXML theme XML. Documents reference a scheme from design.colorScheme (or design.colorScheme.id) and from a theme's colorScheme; slot overrides on design.colorScheme take precedence over the resolved scheme.\n\nThe slot fields here mirror the inline-override fields on the in-document ColorScheme type (in opf.schema.json), so records and inline OPF overrides are interchangeable.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",
   "required": [
     "$schema",
@@ -7626,12 +7581,12 @@ var colorScheme = {
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-color-scheme/v1",
-      "description": "Identifies this record as a color scheme in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a colour scheme record. Required in a published file; an embedded copy omits it."
     },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this color scheme. Lowercase kebab-case.",
+      "description": "The colour scheme's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field.",
       "examples": [
         "cool-horizon",
         "boost",
@@ -7649,29 +7604,6 @@ var colorScheme = {
         "Forest Green"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "replacedBy"
-      ],
-      "description": "Present when this color scheme is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated color scheme record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "summary": {
       "type": "string",
       "description": "One-sentence positioning of the palette \u2014 what mood it evokes and where to use it.",
@@ -7838,7 +7770,7 @@ var fontScheme = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-font-scheme/v1",
   "title": "Font Scheme",
-  "description": "Schema for font-scheme records in the pptx.gallery library. Each scheme pairs a major (heading) and minor (body) font family in the OOXML majorFont/minorFont sense, scoped to a target app (powerpoint or google-slides) and a language family (Latin, East Asian, or Complex Script). Font schemes are referenced from OPF documents via design.fontScheme or design.fontScheme.id; the engine resolves the reference against catalogs.fontSchemes (inline) \u2192 catalogs.fontSchemes.source \u2192 the default catalog at https://www.pptx.gallery/font-schemes. Role overrides on design.fontScheme (heading, body, accent, code), each a font family name, take precedence over the resolved scheme.",
+  "description": "Schema for font-scheme records. Each scheme pairs a major (heading) and minor (body) font family in the OOXML majorFont/minorFont sense, scoped to a target app (powerpoint or google-slides) and a language family (Latin, East Asian, or Complex Script). Documents reference a scheme from design.fontScheme (or design.fontScheme.id), from a theme's fontScheme and from a language's fontScheme / googleFontScheme. Role overrides on design.fontScheme (heading, body, accent, code), each a font family name, take precedence over the resolved scheme.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",
   "required": [
     "$schema",
@@ -7851,12 +7783,12 @@ var fontScheme = {
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-font-scheme/v1",
-      "description": "Identifies this record as a font scheme in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a font scheme record. Required in a published file; an embedded copy omits it."
     },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this font scheme. Lowercase kebab-case.",
+      "description": "The font scheme's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field.",
       "examples": [
         "aptos",
         "tenorite",
@@ -7876,29 +7808,6 @@ var fontScheme = {
         "Microsoft Yahei"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "replacedBy"
-      ],
-      "description": "Present when this font scheme is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated font scheme record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "major": {
       "type": "string",
       "description": "Heading (major) font family \u2014 mirrors the OOXML majorFont entry.",
@@ -8009,15 +7918,15 @@ var fontScheme = {
       "type": "array",
       "items": {
         "type": "string",
-        "pattern": "^[a-z][a-z0-9-]*$"
+        "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$"
       },
-      "description": "Optional list of languages catalog ids (see the languages catalog, https://www.pptx.gallery/languages) this scheme is curated for. Useful for picker UIs that group fonts by language coverage. As the design font scheme, an 'ea' or 'cs' scheme fills its script slot only when this list is empty or names the presentation language by id.",
+      "description": "Optional list of BCP-47 language tags this scheme is curated for. Useful for picker UIs that group fonts by language coverage. As the design font scheme, an 'ea' or 'cs' scheme fills its script slot only when this list is empty or names the presentation language: an entry matches a tag with the same language subtag (and the same script, when the entry names one).",
       "examples": [
         [
-          "chinese-simplified",
-          "chinese-traditional",
-          "japanese",
-          "korean"
+          "zh-Hans",
+          "zh-Hant",
+          "ja",
+          "ko"
         ]
       ]
     },
@@ -8365,7 +8274,7 @@ var finding = {
         },
         "origin": {
           "type": "string",
-          "description": "Where the suggestion comes from: `schema`, `built-in`, `loaded`, `document` or `contract`."
+          "description": "Where the suggestion comes from: `schema`, `document` (a record the document embeds), `registered` (a catalog the host registered) or `contract`."
         },
         "definition": {
           "type": "string",