@openpresentation/opf 0.13.0 → 0.14.0

package/dist/{chunk-7QBCWNWL.js → chunk-LS2FMPI5.js}

@@ -17,7 +17,7 @@ var presentation = {
     },
     "name": {
       "type": "string",
-      "description": "Display name of the presentation for GUI/TUI lists, library/search indexing, OS-level metadata, and default export filenames. This is deck identity, not slide content. Use slides[].title and slides[].subtitle for text that should appear on presented slides.",
+      "description": "Display name of the presentation for GUI/TUI lists, library/search indexing, OS-level metadata, and default export filenames. This is deck identity, not slide content. Use slides[].title and slides[].subtitle for text that should appear on presented slides. Also the built-in variable 'deck.name'.",
       "examples": [
         "Q4 2026 Business Review",
         "Series B Pitch \u2014 Acme",
@@ -26,14 +26,14 @@ var presentation = {
     },
     "description": {
       "type": "string",
-      "description": "Free-form prose describing what this presentation is about. Used by agents and humans as a deck-level summary; complements purpose (the goal) and narrative (the structured storyline). Round-trips to OOXML 'docProps/core.xml' as '<dc:description>' (PowerPoint surfaces this as the 'Comments' field in File \u2192 Properties).",
+      "description": "Free-form prose describing what this presentation is about. Used by agents and humans as a deck-level summary; complements purpose (the goal) and narrative (the structured storyline). Round-trips to OOXML 'docProps/core.xml' as '<dc:description>' (PowerPoint surfaces this as the 'Comments' field in File \u2192 Properties). Also the built-in variable 'deck.description'.",
       "examples": [
         "Quarterly business review covering revenue, product, and hiring milestones for the executive team."
       ]
     },
     "filename": {
       "type": "string",
-      "description": "Optional base filename for exports (without extension). Engine strips a trailing .pptx, .pdf, .png, or .svg (case-insensitive) and appends the target format's extension. When omitted, the engine slugifies name when present. See /docs/opf for full validation rules.",
+      "description": "Optional base filename for exports (without extension). The opf CLI (render, export) and the editor strip a trailing .pptx, .pdf, .png, or .svg (case-insensitive) and append the target format's extension. When omitted, they slugify name; with no usable name the CLI uses the input file name and the editor uses 'presentation'. See /docs/opf for full validation rules.",
       "examples": [
         "q4-2026-business-review",
         "acme-series-b-pitch"
@@ -52,7 +52,7 @@ var presentation = {
           "minItems": 1
         }
       ],
-      "description": "Organization associated with the presentation, usually the presenting company. Array form supports hosts, partners, clients, and sponsors. The primary organization (declared via Organization.role or, if no role is set, the first item) drives default branding such as cover-slide logo."
+      "description": "Organization associated with the presentation, usually the presenting company. Array form supports hosts, partners, clients, and sponsors. The primary organization (Organization.role 'primary', else the first item) supplies the default deck logo, the 'organization' and 'socials' header/footer fields and the 'organization.<field>' built-in variables; the others are available by id as 'organization.<id>.<field>' and are not drawn automatically."
     },
     "speaker": {
       "oneOf": [
@@ -67,7 +67,7 @@ var presentation = {
           "minItems": 1
         }
       ],
-      "description": "Person presenting the deck. Array form supports panels and multi-speaker decks. Used for cover slides, bio slides, footers, and panel attribution."
+      "description": "Person presenting the deck. Array form supports panels and multi-speaker decks. The first speaker is the primary speaker: the built-in variables 'speaker.<field>' and the 'speaker' header/footer field read it, 'speakers' lists every name, and 'speaker.<id>.<field>' addresses one by id. A speaker is drawn nowhere else."
     },
     "author": {
       "oneOf": [
@@ -82,7 +82,7 @@ var presentation = {
           "minItems": 1
         }
       ],
-      "description": "Optional credit for the person who authored or contributed to the deck, distinct from speaker. Array form supports multiple contributors. Round-trips to OOXML 'docProps/core.xml' as '<dc:creator>' (semicolon-joined when multiple) and seeds '<cp:lastModifiedBy>' on first write; subsequent edits in PowerPoint overwrite '<cp:lastModifiedBy>' with the editing user.",
+      "description": "Optional credit for the person who authored or contributed to the deck, distinct from speaker. Array form supports multiple contributors. Round-trips to OOXML 'docProps/core.xml' as '<dc:creator>' (semicolon-joined when multiple) and seeds '<cp:lastModifiedBy>' on first write; subsequent edits in PowerPoint overwrite '<cp:lastModifiedBy>' with the editing user. Also the built-in variable 'deck.author' (an array joined with ', ').",
       "examples": [
         "Bob Lee",
         [
@@ -96,6 +96,9 @@ var presentation = {
         {
           "type": "string"
         },
+        {
+          "$ref": "#/$defs/Audience"
+        },
         {
           "type": "array",
           "items": {
@@ -111,7 +114,7 @@ var presentation = {
           "minItems": 1
         }
       ],
-      "description": "Intended audiences for the presentation. Accepts either:\n- A single string shorthand: free-form description ('Series B investors'), an audiences catalog id ('executive'), an HTTPS URL, or a 'pkg:' reference.\n- An array of string shorthands and/or inline Audience objects for custom audience metadata or catalog-backed overrides. Object form mirrors https://openpresentation.org/schema/opf-audience/v1 without '$schema'.\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 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.",
       "examples": [
         "executive",
         "Biology Students and Wildlife Enthusiasts",
@@ -122,6 +125,10 @@ var presentation = {
           "board",
           "c-suite"
         ],
+        {
+          "id": "executive",
+          "attentionBudgetMinutes": 20
+        },
         [
           "Series B investors",
           "https://acme.com/decks/audiences/acme-board.json"
@@ -259,7 +266,7 @@ var presentation = {
     "duration": {
       "type": "integer",
       "minimum": 1,
-      "description": "Target presentation duration, as an integer number of minutes. Used by AI to set pace and depth, and to compare against the resolved narrative's durationRange."
+      "description": "Target presentation duration, as an integer number of minutes. The opf-render presenter view counts the elapsed time against it, and core validate warns when it lies outside the resolved narrative's 'duration' range. Agents can also use it to set pace and depth. Nothing else reads it: the preview and the PPTX export draw no duration."
     },
     "tags": {
       "type": "array",
@@ -286,7 +293,7 @@ var presentation = {
     },
     "variables": {
       "$ref": "#/$defs/Variables",
-      "description": "Optional named variables: deck colors referenced as 'var:<id>' (the original use), and typed content variables (text, number, date, image, url, list) referenced inline as '{{<id>}}' or whole as 'var:<id>'. Variables are what makes a deck a fillable template when combined with 'template': true. Color variables complement the color scheme: scheme slots and roles stay the primary vocabulary; variables cover deck-specific named colors that have no scheme slot."
+      "description": "Optional named variables: deck colors referenced as 'var:<id>' (the original use), and typed content variables (text, number, date, image, url, list) referenced inline as '{{<id>}}' or whole as 'var:<id>'. Variables are what makes a deck a fillable template when combined with 'template': true. Color variables complement the color scheme: scheme slots and roles stay the primary vocabulary; variables cover deck-specific named colors that have no scheme slot. Built-in variables ('{{speaker.name}}', 'var:organization.logo', 'deck.name', ...) need no declaration; see Variables."
     },
     "template": {
       "type": "boolean",
@@ -294,42 +301,13 @@ var presentation = {
       "default": false
     },
     "narrative": {
-      "oneOf": [
-        {
-          "type": "string"
-        },
-        {
-          "$ref": "#/$defs/Narrative"
-        }
-      ],
-      "description": `Structured storyline describing the deck's arc and beats. Resolves to the 'id' of a 'narratives' catalog record.
-
-Accepts two forms:
-- String shorthand for the common case: 'narrative = "classic-story"'. Accepts a bare id (lowercase kebab-case), an HTTPS URL pointing at a record file, or a 'pkg:' reference to a locally-installed package.
-- Object form for inline overrides or fully custom narratives: 'narrative = { id: "classic-story", beats: [...] }'. The object shape mirrors https://openpresentation.org/schema/opf-narrative/v1 (sans '$schema'), so a library record and an inline narrative are interchangeable.
-
-Resolution 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.
-
-Deck-level concerns that aren't part of the storyline (audience, tone, takeaway, duration) live as siblings on the presentation root rather than inside the narrative object.`,
+      "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.",
       "examples": [
         "classic-story",
         "problem-solution",
         "scqa",
         "pitch-deck",
-        {
-          "id": "custom-pitch",
-          "name": "Custom Pitch",
-          "beats": [
-            {
-              "id": "hook",
-              "name": "Hook"
-            },
-            {
-              "id": "ask",
-              "name": "Ask"
-            }
-          ]
-        },
         "https://acme.com/decks/narratives/founder-pitch.json",
         "pkg:@acme/decks/narratives/founder-pitch"
       ]
@@ -347,7 +325,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
       "items": {
         "$ref": "#/$defs/Reference"
       },
-      "description": "Sources that text runs cite with 'cite'. Ids are unique. A cited reference is listed in the footnote area of every slide that cites it, with a marker number assigned per deck in order of first use; a reference no run cites is a lint warning (opf/unused-reference). referencesSlide() turns the cited references into an ordinary list slide.",
+      "description": "Sources that text runs cite with 'cite'. Ids are unique. A cited reference is listed in the footnote area of every slide that cites it, with a marker number assigned per deck in order of first use; a reference no run cites is the warning opf/unused-reference. referencesSlide() turns the cited references into an ordinary list slide.",
       "examples": [
         [
           {
@@ -360,7 +338,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
     },
     "datasets": {
       "$ref": "#/$defs/Datasets",
-      "description": `Optional shared data tables, keyed by id. A chart ('chart.data': { "dataset": "<id>" }) or a table ('table': { "dataset": "<id>" }) references one instead of holding its own copy; engines inline the reference before composing, rendering or exporting. A dataset nothing references is a lint warning (opf/unused-dataset). See docs/chart-table-data.md.`
+      "description": `Optional shared data tables, keyed by id. A chart ('chart.data': { "dataset": "<id>" }) or a table ('table': { "dataset": "<id>" }) references one instead of holding its own copy; engines inline the reference before composing, rendering or exporting. A dataset nothing references is the warning opf/unused-dataset. See docs/chart-table-data.md.`
     },
     "assets": {
       "$ref": "#/$defs/Assets",
@@ -394,13 +372,13 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
           },
           "revenue": {
             "src": "./data/revenue.csv",
-            "format": "csv"
+            "mediaType": "text/csv"
           }
         }
       ]
     },
     "Asset": {
-      "description": `Reusable or inline resource. A string is shorthand for { "src": value }. Source strings accept 'asset:<id>' references, HTTPS URLs, data URIs, relative paths resolved against the OPF file location, or local filesystem paths. Use object form when metadata such as alt text, title, mediaType, or format matters.`,
+      "description": `Reusable or inline resource. A string is shorthand for { "src": value }. Source strings accept 'asset:<id>' references, HTTPS URLs, data URIs, relative paths resolved against the OPF file location, or local filesystem paths. Use object form when metadata such as alt text, title or mediaType matters.`,
       "oneOf": [
         {
           "type": "string",
@@ -450,20 +428,6 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
                 "text/csv",
                 "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
               ]
-            },
-            "format": {
-              "type": "string",
-              "description": "Optional authoring/parsing format hint. Useful when format is more convenient than a full MIME media type.",
-              "examples": [
-                "csv",
-                "tsv",
-                "json",
-                "xlsx",
-                "svg",
-                "png",
-                "jpg",
-                "webp"
-              ]
             }
           }
         }
@@ -837,7 +801,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
     },
     "Organization": {
       "type": "object",
-      "description": "An organization associated with the presentation \u2014 typically the presenting company, but also hosts, partners, clients, or sponsors. Surfaced on cover slides, footers, and brand bars; the primary organization's logo is the default deck logo unless overridden by design.logo.",
+      "description": "An organization associated with the presentation, typically the presenting company, but also hosts, partners, clients, or sponsors. The primary organization (role 'primary', else the first one) supplies the default deck logo (unless design.logo overrides it), the 'organization' header/footer field (its name) and the 'socials' field (its socials). Every field is also a built-in variable ('{{organization.name}}', 'var:organization.logo', 'organization.<id>.<field>'). Nothing else about an organization is drawn automatically. See docs/templates-and-variables.md.",
       "required": [
         "id",
         "name"
@@ -846,7 +810,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         "id": {
           "type": "string",
           "pattern": "^[a-zA-Z0-9_-]+$",
-          "description": "Stable identifier for the organization, used to reference it from Speaker.organizationId. Must be unique within the deck.",
+          "description": "Stable identifier for the organization, used to reference it from Speaker.organizationId and to address it in built-in variables as 'organization.<id>.<field>'. Must be unique among organizations (a duplicate is a validation error).",
           "examples": [
             "acme",
             "acme-corp",
@@ -855,7 +819,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         },
         "name": {
           "type": "string",
-          "description": "Display name shown on slides.",
+          "description": "Display name. Drawn by the 'organization' header/footer field for the primary organization; the built-in variable 'organization.name' (or 'organization.<id>.name') carries it into any string.",
           "examples": [
             "Acme Corp",
             "DevConf 2026",
@@ -864,7 +828,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         },
         "legalName": {
           "type": "string",
-          "description": "Optional legal entity name when it differs from the display name.",
+          "description": "Optional legal entity name when it differs from the display name. Never drawn automatically; available as the built-in variable 'organization.legalName'.",
           "examples": [
             "Acme Corporation, Inc.",
             "Beta Industries, LLC"
@@ -872,7 +836,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         },
         "logo": {
           "$ref": "#/$defs/Asset",
-          "description": "Source for the organization's logo image. Accepts an HTTPS URL, data URI, relative path (resolved against the OPF file location), local path, or 'asset:<id>' reference. Common formats are SVG (preferred for vector logos), PNG (with transparency), or JPG. The primary organization's logo (role 'primary', else the first organization) is the fallback source wherever the deck logo is drawn: a slide's design.logo, then design.logo, then this value. It is therefore drawn on cover and section slides and by header/footer zones with logo: true, exactly as design.logo would be (see design.logo and docs/design-resolution.md).",
+          "description": "Source for the organization's logo image. Accepts an HTTPS URL, data URI, relative path (resolved against the OPF file location), local path, or 'asset:<id>' reference. Common formats are SVG (preferred for vector logos), PNG (with transparency), or JPG. The primary organization's logo (role 'primary', else the first organization) is the fallback source wherever the deck logo is drawn: a slide's design.logo, then design.logo, then this value. It is therefore drawn on cover and section slides and by header/footer zones with logo: true, exactly as design.logo would be (see design.logo and docs/design-resolution.md). It is also the built-in image variable 'organization.logo' (or 'organization.<id>.logo'), placed with 'var:organization.logo' in an image field.",
           "examples": [
             "https://cdn.acme.com/logo.svg",
             "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9V3iWggAAAAASUVORK5CYII=",
@@ -882,7 +846,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         },
         "domain": {
           "type": "string",
-          "description": "Bare internet domain for the organization. Used for footers, contact slides, and engine-driven asset lookups (e.g., favicon-based brand defaults).",
+          "description": "Bare internet domain for the organization. Never drawn automatically and not used to look up assets; available as the built-in variable 'organization.domain'.",
           "examples": [
             "acme.com",
             "beta-industries.io",
@@ -892,7 +856,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         "email": {
           "type": "string",
           "format": "email",
-          "description": "General contact email for the organization. Used on contact slides and footer attribution.",
+          "description": "General contact email for the organization. Never drawn automatically; available as the built-in variable 'organization.email'.",
           "examples": [
             "hello@acme.com",
             "sales@acme.com",
@@ -901,7 +865,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         },
         "phone": {
           "type": "string",
-          "description": "Main contact phone number for the organization. E.164 format is recommended.",
+          "description": "Main contact phone number for the organization. E.164 format is recommended. Never drawn automatically; available as the built-in variable 'organization.phone'.",
           "examples": [
             "+14155551234",
             "+442071838750"
@@ -909,7 +873,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         },
         "tagline": {
           "type": "string",
-          "description": "Short tagline rendered alongside the organization name on cover slides.",
+          "description": "Short tagline. Never drawn automatically (cover slides do not show it); available as the built-in variable 'organization.tagline', for example in a footer 'text' of '{{organization.tagline}}'.",
           "examples": [
             "Build the future of work",
             "Infrastructure for AI agents",
@@ -925,7 +889,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
             "sponsor",
             "host"
           ],
-          "description": "Role of the organization relative to the presentation. When omitted, the single organization or first organization in array form is treated as primary."
+          "description": "Role of the organization relative to the presentation. Only 'primary' has behavior: it selects the primary organization (deck logo, 'organization' and 'socials' header/footer fields, and the 'organization.<field>' built-ins). When no organization has role 'primary', the first one is primary. 'partner', 'client', 'sponsor' and 'host' are descriptive labels that change nothing."
         },
         "socials": {
           "$ref": "#/$defs/Socials",
@@ -935,7 +899,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
     },
     "Speaker": {
       "type": "object",
-      "description": "A person presenting the deck. Used for cover slides, bio/intro slides, footer attribution, and panel formats with multiple presenters.",
+      "description": "A person presenting the deck. A speaker is drawn only through built-in variables ('{{speaker.name}}' inside any string, 'var:speaker.photo' as a whole image field) and the 'speaker' header/footer field (the first speaker's name and title). No layout, cover or bio slide places a speaker on its own. See docs/templates-and-variables.md.",
       "required": [
         "id",
         "name"
@@ -944,7 +908,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         "id": {
           "type": "string",
           "pattern": "^[a-zA-Z0-9_-]+$",
-          "description": "Stable identifier for the speaker, used for cross-references within the deck. Must be unique within the deck.",
+          "description": "Stable identifier for the speaker. Must be unique among speakers (a duplicate is a validation error). Addresses this speaker in built-in variables as 'speaker.<id>.<field>', such as '{{speaker.alice.title}}'.",
           "examples": [
             "alice",
             "alice-chen",
@@ -953,7 +917,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         },
         "name": {
           "type": "string",
-          "description": "Display name.",
+          "description": "Display name. Built-in variable 'speaker.name' (first speaker) or 'speaker.<id>.name'; the first speaker's name is also drawn by the 'speaker' header/footer field and every name is listed by 'speakers'.",
           "examples": [
             "Alice Chen",
             "Bob Lee",
@@ -962,7 +926,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         },
         "title": {
           "type": "string",
-          "description": "Role or title. Often paired with the speaker's organization on cover slides.",
+          "description": "Role or title. Built-in variable 'speaker.title'; the 'speaker' header/footer field draws it after the name ('Alice Chen, VP of Engineering').",
           "examples": [
             "VP of Engineering",
             "Founder & CEO",
@@ -972,7 +936,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         },
         "photo": {
           "$ref": "#/$defs/Asset",
-          "description": "Source for the speaker's headshot image. Accepts an HTTPS URL, data URI, relative path (resolved against the OPF file location), local path, or 'asset:<id>' reference. Common formats are JPG or PNG; SVG is not appropriate for photographic content. Authoring metadata for hosts and layouts (cover and bio slides built by a host): the reference renderer and exporter do not draw it, because no slide field or layout slot places a speaker; it round-trips through PPTX provenance.",
+          "description": "Source for the speaker's headshot image. Accepts an HTTPS URL, data URI, relative path (resolved against the OPF file location), local path, or 'asset:<id>' reference. Common formats are JPG or PNG; SVG is not appropriate for photographic content. Never drawn automatically: it is the built-in image variable 'speaker.photo' (or 'speaker.<id>.photo'), placed with 'var:speaker.photo' in a slide's image field. It also round-trips through PPTX provenance.",
           "examples": [
             "https://cdn.acme.com/headshots/alice.jpg",
             "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAr/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEBAAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AJ//2Q==",
@@ -983,7 +947,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         "email": {
           "type": "string",
           "format": "email",
-          "description": "Contact email, used on contact slides or footer attribution when appropriate.",
+          "description": "Contact email. Never drawn automatically; available as the built-in variable 'speaker.email'.",
           "examples": [
             "alice@acme.com",
             "alice.chen@acme.com"
@@ -991,7 +955,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         },
         "phone": {
           "type": "string",
-          "description": "Contact phone number for the speaker. E.164 format is recommended.",
+          "description": "Contact phone number for the speaker. E.164 format is recommended. Never drawn automatically; available as the built-in variable 'speaker.phone'.",
           "examples": [
             "+14155551234",
             "+442071838750"
@@ -999,14 +963,14 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         },
         "bio": {
           "type": "string",
-          "description": "Short biographical paragraph for bio or 'about the speaker' slides.",
+          "description": "Short biographical paragraph. Never drawn automatically; available as the built-in variable 'speaker.bio', for a bio or 'about the speaker' slide you write.",
           "examples": [
             "Alice leads engineering at Acme, where she's spent the last six years scaling distributed systems from prototype to billions of requests per day. Previously, she was a staff engineer at Google."
           ]
         },
         "organizationId": {
           "type": "string",
-          "description": "Reference to an Organization.id in organization. Lets a speaker be attributed to their org in panel or multi-org decks without repeating organization details.",
+          "description": "Reference to an Organization.id in organization; it must name an existing organization (a validation error otherwise). Attribution metadata for hosts: no engine draws it or changes which organization is primary because of it.",
           "examples": [
             "acme",
             "beta",
@@ -1015,7 +979,7 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         },
         "socials": {
           "$ref": "#/$defs/Socials",
-          "description": "Optional social media handles or URLs for the speaker. Authoring metadata: no header/footer field renders speaker socials yet."
+          "description": "Optional social media handles or URLs for the speaker. Authoring metadata only: nothing draws speaker socials and there is no built-in variable for them (the 'socials' header/footer field draws the primary organization's socials)."
         }
       }
     },
@@ -1043,211 +1007,6 @@ Deck-level concerns that aren't part of the storyline (audience, tone, takeaway,
         "description": "Platform id (lowercase kebab-case). Common ids include 'linkedin', 'x', 'github', 'youtube', 'instagram', 'facebook', 'tiktok', 'threads', 'mastodon', 'bluesky'."
       }
     },
-    "Narrative": {
-      "type": "object",
-      "description": "Structured storyline used by AI to shape generated content. Mirrors the OPF Narrative Template record at https://openpresentation.org/schema/opf-narrative/v1 (sans '$schema'), so a library record and an inline narrative are interchangeable.\n\nNarrative declares the deck's intended story arc; slides may opt into beats via Slide.beat. The narrative does not constrain slide structure \u2014 validators warn on drift (orphan slides, unused beats) but never error. Slides are the source of truth; narrative is intent that travels with the deck.\n\nWhen 'id' matches a record in the resolved 'narratives' catalog, the inline fields override matching fields on the catalog record (beats merge by beat 'id'). When 'id' doesn't match, this object defines a fully custom inline narrative.\n\nDeck-level concerns that aren't part of the storyline (audience, tone, takeaway, duration) live as siblings on the presentation root rather than inside this object.",
-      "properties": {
-        "id": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Stable slug identifying this narrative. When it matches a record in the resolved 'narratives' catalog, the catalog record's beats and metadata seed this narrative; inline fields override per-key. When it doesn't match, this is a fully custom inline narrative. Lowercase kebab-case.",
-          "examples": [
-            "classic-story",
-            "problem-solution",
-            "scqa",
-            "pitch-deck",
-            "qbr",
-            "weekly-progress",
-            "custom-pitch"
-          ]
-        },
-        "name": {
-          "type": "string",
-          "description": "Human-readable narrative name.",
-          "examples": [
-            "Classic Story",
-            "Problem \u2192 Solution",
-            "SCQA",
-            "Founder Pitch"
-          ]
-        },
-        "summary": {
-          "type": "string",
-          "description": "One-sentence description of when and why to use this narrative."
-        },
-        "description": {
-          "type": "string",
-          "description": "Longer prose describing the narrative arc and ideal use cases. Used by AI-driven generation to seed deck-level direction.",
-          "examples": [
-            "Open with the cost of slow agentic workflows, contrast with what becomes possible at sub-second latency, then walk through our architecture and benchmark results, ending with a concrete adoption ask."
-          ]
-        },
-        "audienceFit": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Audiences this narrative works well for. Free-form strings or 'audiences' catalog ids.",
-          "examples": [
-            [
-              "executive",
-              "investor",
-              "customer"
-            ]
-          ]
-        },
-        "durationRange": {
-          "type": "object",
-          "description": "Typical talk-length window this narrative suits. Compared by validators against duration.",
-          "properties": {
-            "minMinutes": {
-              "type": "number",
-              "exclusiveMinimum": 0
-            },
-            "maxMinutes": {
-              "type": "number",
-              "exclusiveMinimum": 0
-            }
-          }
-        },
-        "tags": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Free-form labels for filtering and search.",
-          "examples": [
-            [
-              "business",
-              "pitch",
-              "internal"
-            ]
-          ]
-        },
-        "preview": {
-          "type": "object",
-          "description": "Visual previews of the narrative, used by picker UIs and inline rendering. All sub-fields are optional.",
-          "properties": {
-            "src": {
-              "type": "string",
-              "format": "uri",
-              "description": "Main preview image (PNG/JPG)."
-            },
-            "thumbnailSrc": {
-              "type": "string",
-              "format": "uri",
-              "description": "Smaller thumbnail preview for dense grid views."
-            },
-            "vectorSrc": {
-              "type": "string",
-              "format": "uri",
-              "description": "SVG / vector preview for crisp scaling at any size."
-            }
-          }
-        },
-        "beats": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/NarrativeBeat"
-          },
-          "description": "Ordered list of beats that make up the narrative arc. When 'id' matches a catalog record, beats here override or extend matching catalog beats by their own 'id'. Beat IDs must be unique within the narrative."
-        }
-      }
-    },
-    "NarrativeBeat": {
-      "type": "object",
-      "description": "A single narrative beat \u2014 a labeled segment of the story arc with a specific dramatic purpose (e.g. 'hook', 'problem', 'evidence', 'ask'). Slides reference beats via Slide.beat. Beats may also carry slide-blueprint hints (slideType, layoutHint, thoughtCues, instructions) that guide the assigned slide.\n\nMirrors the Beat definition in narrative.schema.json (https://openpresentation.org/schema/opf-narrative/v1) so library entries and inline OPF beats are interchangeable.",
-      "required": [
-        "id",
-        "name"
-      ],
-      "properties": {
-        "id": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Stable slug used by Slide.beat to reference this beat. Lowercase kebab-case.",
-          "examples": [
-            "hook",
-            "problem",
-            "evidence",
-            "ask",
-            "next-steps"
-          ]
-        },
-        "name": {
-          "type": "string",
-          "description": "Human-readable beat name.",
-          "examples": [
-            "The Hook",
-            "The Problem",
-            "Why Now",
-            "The Ask"
-          ]
-        },
-        "description": {
-          "type": "string",
-          "description": "Curator-written prose that explains what this beat should accomplish.",
-          "examples": [
-            "Quantify the pain customers feel today, with one striking stat the audience can repeat afterward."
-          ]
-        },
-        "instructions": {
-          "type": "string",
-          "description": "Short author-facing instruction for the beat \u2014 typically one phrase. Complements 'description' with a concise directive.",
-          "examples": [
-            "Capture audience attention",
-            "Introduce problem",
-            "Detail implementation",
-            "Inspire & conclude"
-          ]
-        },
-        "slideCount": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Optional explicit slide count for this beat. Defaults to 1 when omitted; values >1 are reserved for beats that intentionally span multiple slides. Prefer decomposing a heavy beat into multiple beats over setting a high slideCount. The validator emits a warning if the deck's actual count differs significantly."
-        },
-        "slideType": {
-          "type": "string",
-          "enum": [
-            "text",
-            "list",
-            "image",
-            "chart",
-            "table",
-            "video",
-            "code",
-            "metric",
-            "quote",
-            "timeline"
-          ],
-          "description": "Default content kind for the beat's slide. Mirrors ContentPayload.type and helps engines choose a sensible layout when only the beat is specified."
-        },
-        "layoutHint": {
-          "type": "string",
-          "description": "Suggested layout id for the beat's opening slide. Resolves the same way as Slide.layout \u2014 against catalogs.layouts and the default catalog at https://www.pptx.gallery/layouts.",
-          "examples": [
-            "section-divider",
-            "title-slide",
-            "title-left",
-            "two-column",
-            "text-left"
-          ]
-        },
-        "thoughtCues": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Optional speaker or thinking cues attached to the beat. Surfaced in presenter notes.",
-          "examples": [
-            [
-              "What pain is the audience feeling right now?",
-              "Why hasn't anyone solved this yet?"
-            ]
-          ]
-        }
-      }
-    },
     "Design": {
       "type": "object",
       "description": "Visual design system applied to the presentation; individual slides may override fields via Slide.design.",
@@ -1327,10 +1086,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "tenorite",
             {
               "id": "aptos",
-              "heading": {
-                "family": "Inter",
-                "weight": 700
-              }
+              "heading": "Inter"
             }
           ]
         },
@@ -1403,13 +1159,17 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
               "$ref": "#/$defs/Watermark"
             }
           ],
-          "description": "Optional decorative watermark applied across slides. Use false to suppress an inherited watermark in slide-level design; a string is equivalent to { src: value }.",
+          "description": "Optional decorative watermark applied across slides: an image or a text stamp, in the fixed frame and at the opacity described on Watermark. Use false to suppress an inherited watermark in slide-level design; a string or Asset is the image at opacity 0.08.",
           "examples": [
             false,
             "asset:watermark",
             {
               "src": "asset:watermark",
               "opacity": 0.08
+            },
+            {
+              "text": "DRAFT",
+              "opacity": 0.1
             }
           ]
         },
@@ -1469,7 +1229,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "center",
             "right"
           ],
-          "description": "Default horizontal alignment for title placeholders in resolved layouts."
+          "description": "Default horizontal alignment for title placeholders in resolved layouts. Effective value: the slide's design, then the deck's design, then the layout record's design.titleAlignment, then the engine default."
         },
         "contentAlignment": {
           "type": "string",
@@ -1478,11 +1238,11 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "center",
             "right"
           ],
-          "description": "Default horizontal alignment for body/content regions in resolved layouts."
+          "description": "Default horizontal alignment for body/content regions in resolved layouts. Effective value: the slide's design, then the deck's design, then the layout record's design.contentAlignment, then the engine default. A cover's tag and subtitle follow titleAlignment unless the slide's own design sets contentAlignment."
         },
         "contentBox": {
           "type": "boolean",
-          "description": "Whether body/content regions are rendered inside a visible card or surface."
+          "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": [
@@ -1651,7 +1411,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
               }
             }
           ],
-          "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 declares slideImage: true 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."
+          "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",
@@ -1659,7 +1419,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "horizontal",
             "vertical"
           ],
-          "description": "Axis along which parallel body content is arranged. Sets the root arrangement mode of blocks and root payloads when no composition.mode is set on the slide or on its layout record: 'vertical' is column, 'horizontal' is row. Precedence: composition.mode (the slide's own, else the layout record's geometry contract), then this value (slide design, then deck design), then the layout record's slideLayoutDirection, then automatic selection. A layout that carries a composition.mode keeps its grid or direction whatever this value says. Promoted regions (left, top:left, ...) keep their explicit geometry and nested groups keep their own composition."
+          "description": "Axis along which parallel body content is arranged. Sets the root arrangement mode of blocks and root payloads when no composition.mode is set on the slide or on its layout record: 'vertical' is column, 'horizontal' is row. Precedence: composition.mode (the slide's own, else the layout record's geometry contract), then the effective value (slide design, then deck design, then the layout record's design.contentDirection), then automatic selection. A layout that carries a composition.mode keeps its grid or direction whatever this value says. Promoted regions (left, top:left, ...) keep their explicit geometry and nested groups keep their own composition."
         },
         "chartPrimary": {
           "type": "string",
@@ -1670,7 +1430,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "left",
             "right"
           ],
-          "description": "Where the primary chart sits relative to supporting content. Effective value: slide design, then deck design, then the layout record's contentTypeChartPrimary. 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."
+          "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": {
           "type": "string",
@@ -1678,7 +1438,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "crop",
             "fit"
           ],
-          "description": "How picture placeholders fill their allocated region."
+          "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."
         },
         "listBullet": {
           "type": "string",
@@ -1686,7 +1446,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "character",
             "image"
           ],
-          "description": "Marker style for items and bullets lists. 'character' (the default) draws the glyph marker. 'image' draws the deck's icon logo (a slide's design.logo, then design.logo, then the primary organization's logo; light variants on dark backgrounds) as a picture bullet: a square of the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field."
+          "description": "Marker style for items and bullets lists. Effective value: the slide's design, then the deck's design, then the layout record's design.listBullet, then 'character'. 'character' (the default) draws the glyph marker. 'image' draws the deck's icon logo (a slide's design.logo, then design.logo, then the primary organization's logo; light variants on dark backgrounds) as a picture bullet: a square of the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field."
         }
       }
     },
@@ -1756,10 +1516,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "aptos",
             {
               "id": "aptos",
-              "heading": {
-                "family": "Inter",
-                "weight": 700
-              }
+              "heading": "Inter"
             }
           ]
         },
@@ -1810,7 +1567,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
     },
     "ColorScheme": {
       "type": "object",
-      "description": "Color palette used by the design system. 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, custom) - 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 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'.",
       "properties": {
         "id": {
           "type": "string",
@@ -1826,7 +1583,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "accent1": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Accent 1 color (hex). Mirrors the OOXML accent1 slot.",
           "examples": [
             "#2874A6",
@@ -1835,7 +1592,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "accent2": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Accent 2 color (hex). Mirrors the OOXML accent2 slot.",
           "examples": [
             "#1B4F72",
@@ -1844,7 +1601,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "accent3": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Accent 3 color (hex). Mirrors the OOXML accent3 slot.",
           "examples": [
             "#5499C7",
@@ -1853,7 +1610,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "accent4": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Accent 4 color (hex). Mirrors the OOXML accent4 slot.",
           "examples": [
             "#7BDBB2",
@@ -1862,7 +1619,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "accent5": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Accent 5 color (hex). Mirrors the OOXML accent5 slot.",
           "examples": [
             "#3AC67A",
@@ -1871,7 +1628,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "accent6": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Accent 6 color (hex). Mirrors the OOXML accent6 slot.",
           "examples": [
             "#24A89E",
@@ -1880,14 +1637,14 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "dark1": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Dark 1 color (hex). Typically the deepest neutral; OOXML dark1.",
           "examples": [
             "#000000"
           ]
         },
         "dark2": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Dark 2 color (hex). Secondary dark; OOXML dark2.",
           "examples": [
             "#011842",
@@ -1895,14 +1652,14 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "light1": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Light 1 color (hex). Typically the slide canvas; OOXML lt1.",
           "examples": [
             "#FFFFFF"
           ]
         },
         "light2": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Light 2 color (hex). Secondary light surface; OOXML lt2.",
           "examples": [
             "#F0F0F0",
@@ -1910,15 +1667,15 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "hyperlink": {
-          "type": "string",
-          "description": "Hyperlink color (hex). OOXML hlink.",
+          "$ref": "#/$defs/HexColor",
+          "description": "Hyperlink color (hex). OOXML hlink. Link runs with no color of their own are drawn underlined in it, in the preview and in PowerPoint, unless it has under 4.5:1 contrast against the slide background, then in the slide text color.",
           "examples": [
             "#0563C1",
             "#0066CC"
           ]
         },
         "followedHyperlink": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Followed-hyperlink color (hex). OOXML folHlink.",
           "examples": [
             "#954F72",
@@ -1926,7 +1683,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "primary": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Abstract role: primary brand color (hex). The engine maps this onto an OOXML accent slot when serializing.",
           "examples": [
             "#1E40AF",
@@ -1934,7 +1691,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "secondary": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Abstract role: secondary brand color (hex).",
           "examples": [
             "#3B82F6",
@@ -1942,7 +1699,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "accent": {
-          "type": "string",
+          "$ref": "#/$defs/HexColor",
           "description": "Abstract role: accent color used for highlights and emphasis (hex).",
           "examples": [
             "#F59E0B",
@@ -1950,56 +1707,42 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "background": {
-          "type": "string",
-          "description": "Abstract role: default slide background color (hex). The engine maps this to one of light1 / light2 / dark1 / dark2 when serializing.",
+          "$ref": "#/$defs/HexColor",
+          "description": "Abstract role: default slide background color (hex), used when the design names no single-color background (and for gradient and picture backgrounds). Overrides light1 as that default.",
           "examples": [
             "#FFFFFF",
             "#0B1220"
           ]
         },
         "surface": {
-          "type": "string",
-          "description": "Abstract role: color for elevated surfaces such as cards and panels (hex).",
+          "$ref": "#/$defs/HexColor",
+          "description": "Abstract role: color for elevated surfaces such as cards and panels (hex). Overrides the default of light2 (dark2 on a dark slide).",
           "examples": [
             "#F8FAFC",
             "#1E293B"
           ]
         },
         "text": {
-          "type": "string",
-          "description": "Abstract role: primary body text color (hex).",
+          "$ref": "#/$defs/HexColor",
+          "description": "Abstract role: primary body text color (hex). Overrides dark1 on a light slide only; a dark slide always uses light1.",
           "examples": [
             "#0F172A",
             "#F8FAFC"
           ]
         },
         "textSecondary": {
-          "type": "string",
-          "description": "Abstract role: secondary or muted text color used for captions and supporting copy (hex).",
+          "$ref": "#/$defs/HexColor",
+          "description": "Abstract role: secondary or muted text color used for captions and supporting copy (hex). Overrides the default of dark2 (light2 on a dark slide).",
           "examples": [
             "#475569",
             "#94A3B8"
           ]
-        },
-        "custom": {
-          "type": "object",
-          "additionalProperties": {
-            "type": "string"
-          },
-          "description": "Map of custom named colors for advanced or theme-specific use.",
-          "examples": [
-            {
-              "success": "#10B981",
-              "warning": "#F59E0B",
-              "danger": "#EF4444"
-            }
-          ]
         }
       }
     },
     "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 objects 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.\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 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'.",
       "properties": {
         "id": {
           "type": "string",
@@ -2099,72 +1842,54 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
         "app": {
           "type": "string",
           "enum": [
-            "PowerPoint",
-            "Google Slides"
+            "powerpoint",
+            "google-slides"
           ],
-          "description": "Target application this font pairing is intended for."
+          "description": "Target application this font pairing is intended for. Metadata for pickers and catalog filters: no engine changes its output by it."
         },
         "languageFamily": {
           "type": "string",
           "enum": [
             "latin",
             "ea",
-            "cs"
+            "cs",
+            "eastAsian",
+            "complexScript"
           ],
-          "description": "OOXML font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' for East Asian scripts, 'cs' for Complex Scripts. As the design font scheme, an 'ea' or 'cs' scheme also fills that script slot with its own major/minor families when its languages list is empty or names the presentation language."
+          "description": "Font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' (or 'eastAsian', the same value) for East Asian scripts, 'cs' (or 'complexScript', the same value) for Complex Scripts. The long names match the 'eastAsian' and 'complexScript' slot keys; the short names match the OOXML a:ea and a:cs elements; core reads both spellings as one value. As the design font scheme, an 'ea'/'eastAsian' or 'cs'/'complexScript' scheme also fills that script slot with its own major/minor families when its languages list is empty or names the presentation language."
         },
         "heading": {
-          "$ref": "#/$defs/Font",
-          "description": "Abstract role: font used for slide titles and headings. Maps onto the OOXML major slot when serializing."
+          "type": "string",
+          "description": "Abstract role: font family name used for slide titles and headings. Maps onto the OOXML major slot when serializing."
         },
         "body": {
-          "$ref": "#/$defs/Font",
-          "description": "Abstract role: font used for body copy. Maps onto the OOXML minor slot when serializing."
+          "type": "string",
+          "description": "Abstract role: font family name used for body copy. Maps onto the OOXML minor slot when serializing."
         },
         "accent": {
-          "$ref": "#/$defs/Font",
-          "description": "Abstract role: font used for accent text. When set, the slide tag (eyebrow) and the quote body use this family instead of the body and heading families; nothing else changes. resolveFontFamilies() returns it as accent only when the scheme defines it. No direct OOXML slot: PPTX export writes it on those runs, and the theme fonts stay major/minor."
+          "type": "string",
+          "description": "Abstract role: font family name used for accent text. When set, the slide tag (eyebrow) and the quote body use this family instead of the body and heading families; nothing else changes. resolveFontFamilies() returns it as accent only when the scheme defines it. No direct OOXML slot: PPTX export writes it on those runs, and the theme fonts stay major/minor."
         },
         "code": {
-          "$ref": "#/$defs/Font",
-          "description": "Abstract role: monospaced font used for code blocks and inline 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."
+          "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."
         }
       }
     },
-    "Font": {
-      "type": "object",
-      "description": "Specification for a single font role.",
-      "required": [
-        "family"
-      ],
-      "properties": {
-        "family": {
-          "type": "string",
-          "description": "Font family name.",
-          "examples": [
-            "Inter",
-            "Roboto",
-            "Source Serif Pro",
-            "JetBrains Mono"
-          ]
-        },
-        "weight": {
-          "type": "number",
-          "description": "Numeric font weight (e.g., 400 for regular, 700 for bold)."
-        },
-        "style": {
-          "type": "string",
-          "enum": [
-            "normal",
-            "italic"
-          ],
-          "description": "Font style."
+    "SlideDesign": {
+      "description": "A slide's design: every Design field except dimensions. A PPTX has one slide size, so the size is set once, on the deck's design.dimensions (or its theme), and a slide's design cannot set it. A slide-level theme whose resolved dimensions differ from the deck's is a validate warning (opf/slide-theme-dimensions); exporting such a deck to PPTX fails with mixed-slide-dimensions.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/Design"
         },
-        "letterSpacing": {
-          "type": "number",
-          "description": "Letter spacing (tracking) in ems."
+        {
+          "not": {
+            "required": [
+              "dimensions"
+            ]
+          }
         }
-      }
+      ]
     },
     "DimensionPreset": {
       "type": "string",
@@ -2172,12 +1897,15 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
         "16:9",
         "4:3",
         "16:10",
+        "1:1",
+        "4:5",
+        "9:16",
         "letter",
         "a4",
         "widescreen",
         "standard"
       ],
-      "description": "Named dimension preset; chooses both aspect ratio and physical size. 'widescreen' is an alias for 16:9 in PowerPoint widescreen size; 'standard' is an alias for 4:3 in PowerPoint standard size."
+      "description": "Named dimension preset; chooses both aspect ratio and physical size. 'widescreen' is an alias for 16:9 in PowerPoint widescreen size; 'standard' is an alias for 4:3 in PowerPoint standard size. The social-feed ratios keep the widescreen short edge of 7.5 in: 1:1 is 7.5 x 7.5 in, 4:5 is 7.5 x 9.375 in and 9:16 is 7.5 x 13.333 in (portrait)."
     },
     "Dimensions": {
       "type": "object",
@@ -2243,6 +1971,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "accent",
             "background",
             "surface",
+            "surfaceAlt",
             "text",
             "textSecondary"
           ]
@@ -2252,7 +1981,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           "pattern": "^var:[a-z][a-z0-9-]*$"
         }
       ],
-      "description": "A color value or reference, enforced on styled table cell fill and text colors and on cell border colors. Three forms:\n- Literal hex: '#RGB', '#RRGGBB', or '#RRGGBBAA'.\n- Color-scheme name, resolved through the effective color scheme after design resolution: an OOXML slot ('accent1'-'accent6', 'dark1', 'dark2', 'light1', 'light2', 'hyperlink', 'followedHyperlink') or an abstract role ('primary', 'secondary', 'accent', 'background', 'surface', 'text', 'textSecondary'). Roles resolve through the same role-to-slot mapping engines already apply to color schemes.\n- Variable reference: 'var:<id>' into the top-level variables map.\n\nNames keep content theme-portable: re-theming the deck updates every named reference, where a literal hex stays frozen. Unknown 'var:' ids produce a validation warning, never an error, and engines fall back to their default text color. TextRun.color documents the same three forms but remains an open string so imported decks with unrecognized run colors stay valid; validators warn there instead of erroring.",
+      "description": "A color value or reference, enforced on styled table cell fill and text colors, cell border colors, solid background colors, gradient stop colors and pattern foreground and background colors. Three forms:\n- Literal hex: '#RGB', '#RRGGBB', or '#RRGGBBAA'.\n- Color-scheme name, resolved through the effective color scheme after design resolution: an OOXML slot ('accent1'-'accent6', 'dark1', 'dark2', 'light1', 'light2', 'hyperlink', 'followedHyperlink') or an abstract role ('primary', 'secondary', 'accent', 'background', 'surface', 'surfaceAlt', 'text', 'textSecondary'). Roles resolve through the same role-to-slot mapping engines already apply to color schemes. 'surfaceAlt' has no slot: it is the alternate surface of banded table rows, derived from 'surface' and 'text' (the surface mixed a tenth of the way towards the text color, further when needed, so it always differs visibly from 'surface' and keeps 4.5:1 text contrast; core surfaceAltColor).\n- Variable reference: 'var:<id>' into the top-level variables map.\n\nNames keep content theme-portable: re-theming the deck updates every named reference, where a literal hex stays frozen. Unknown 'var:' ids produce a validation warning, never an error, and engines fall back to their default text color. TextRun.color documents the same three forms but remains an open string so imported decks with unrecognized run colors stay valid; validators warn there instead of erroring.",
       "examples": [
         "#0F4C81",
         "accent2",
@@ -2268,7 +1997,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
       "additionalProperties": {
         "$ref": "#/$defs/Variable"
       },
-      "description": "Named variables, keyed by stable kebab-case id. A variable is a typed, named value the deck declares once and uses in many places: a color ('var:<id>' in color fields, the original use), or content that fills a template (text, number, date, image, url, list). Content is referenced inline as '{{<id>}}' inside any string, or whole as 'var:<id>' in a field of the matching type; '\\{{' writes a literal '{{'. A hex string is shorthand for a color variable. A variable with no 'value' is unfilled: expected in a template (root 'template': true), an error in a normal deck. Engines resolve variables with resolveVariables() before composing, rendering or exporting, so a template plus its values previews and exports exactly like the equivalent hand-written deck. See docs/templates-and-variables.md.",
+      "description": "Named variables, keyed by stable kebab-case id. A variable is a typed, named value the deck declares once and uses in many places: a color ('var:<id>' in color fields, the original use), or content that fills a template (text, number, date, image, url, list). Content is referenced inline as '{{<id>}}' inside any string, or whole as 'var:<id>' in a field of the matching type; '\\{{' writes a literal '{{'. A hex string is shorthand for a color variable. A variable with no 'value' is unfilled: expected in a template (root 'template': true), an error in a normal deck. Engines resolve variables with resolveVariables() before composing, rendering or exporting, so a template plus its values previews and exports exactly like the equivalent hand-written deck. Read-only built-in variables come from the deck's own metadata and use dotted names that a user id can never take: 'deck.name', 'deck.description', 'deck.author', 'speaker.name|title|email|phone|bio|photo' (first speaker), 'speakers' (every speaker's name, a list), 'organization.name|legalName|tagline|domain|email|phone|logo' (primary organization), and 'speaker.<id>.<field>' / 'organization.<id>.<field>' by id. They are written the same two ways ('{{speaker.name}}', 'var:speaker.photo'), are never declared, and an unknown built-in path is a validation error; a known one with no source value resolves to nothing with a warning. The id 'speakers' is reserved. See docs/templates-and-variables.md.",
       "examples": [
         {
           "risk": "#B42318",
@@ -2721,7 +2450,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           "description": "Fixed solid background fill."
         },
         "color": {
-          "type": "string",
+          "$ref": "#/$defs/ColorRef",
           "description": "Fixed solid fill color: a hex string, a color-scheme slot or role name, or a var:<id> variable reference (a ColorRef, resolved against the effective color scheme and the deck variables). Use { type: 'theme', slot: ... } for PowerPoint's four theme-controlled background choices.",
           "examples": [
             "#FFFFFF",
@@ -2760,7 +2489,8 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             },
             "stops": {
               "type": "array",
-              "description": "Ordered list of color stops along the gradient.",
+              "minItems": 2,
+              "description": "Ordered list of color stops along the gradient. A gradient needs at least two stops.",
               "items": {
                 "type": "object",
                 "description": "Color stop along the gradient.",
@@ -2770,7 +2500,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
                 ],
                 "properties": {
                   "color": {
-                    "type": "string",
+                    "$ref": "#/$defs/ColorRef",
                     "description": "Stop color: a hex string, a color-scheme slot or role name, or a var:<id> variable reference (a ColorRef).",
                     "examples": [
                       "#1E40AF",
@@ -2875,14 +2605,14 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
               ]
             },
             "foregroundColor": {
-              "type": "string",
+              "$ref": "#/$defs/ColorRef",
               "description": "Foreground color for the pattern: a hex string, a color-scheme slot or role name, or a var:<id> variable reference (a ColorRef).",
               "examples": [
                 "#0F172A"
               ]
             },
             "backgroundColor": {
-              "type": "string",
+              "$ref": "#/$defs/ColorRef",
               "description": "Background color behind the pattern: a hex string, a color-scheme slot or role name, or a var:<id> variable reference (a ColorRef).",
               "examples": [
                 "#FFFFFF"
@@ -2955,15 +2685,36 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
     },
     "Watermark": {
       "type": "object",
-      "description": "Decorative watermark image and rendering options. 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 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.",
       "additionalProperties": false,
       "required": [
         "opacity"
       ],
+      "oneOf": [
+        {
+          "required": [
+            "src"
+          ]
+        },
+        {
+          "required": [
+            "text"
+          ]
+        }
+      ],
       "properties": {
         "src": {
           "type": "string",
-          "description": "Source for the watermark image."
+          "description": "Source for the watermark image: an 'asset:<id>' reference, HTTPS URL, data URI, relative path or local path, as for Asset.src. Exactly one of src and text is set."
+        },
+        "text": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Text for a text watermark, such as DRAFT or CONFIDENTIAL; line breaks are drawn as spaces. Exactly one of src and text is set.",
+          "examples": [
+            "DRAFT",
+            "CONFIDENTIAL"
+          ]
         },
         "opacity": {
           "type": "number",
@@ -2993,7 +2744,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
     },
     "HeaderFooterItem": {
       "type": "object",
-      "description": "One header/footer zone. Every configured field renders; fields in one zone stack top to bottom in the order logo, image, text, organization, socials, section, slide number, date. Put a date and a slide number in different zones to keep each on the zone's single line.",
+      "description": "One header/footer zone. Every configured field renders; fields in one zone stack top to bottom in the order logo, image, text, organization, speaker, socials, section, slide number, date. Put a date and a slide number in different zones to keep each on the zone's single line.",
       "properties": {
         "logo": {
           "type": "boolean",
@@ -3059,7 +2810,11 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
         },
         "organization": {
           "type": "boolean",
-          "description": "Whether to render the primary organization name from organization."
+          "description": "Whether to render the primary organization's name from organization (role 'primary', else the first organization)."
+        },
+        "speaker": {
+          "type": "boolean",
+          "description": "Whether to render the primary (first) speaker's name and title from speaker, joined as 'Ada Lovelace, CTO' (just the name when the speaker has no title). It is generated text: without a named speaker the engine reports unresolved-content at this field. PPTX export writes it as static text and import restores the flag from the file's furniture provenance."
         },
         "section": {
           "type": "boolean",
@@ -3114,11 +2869,11 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
               }
             }
           ],
-          "description": "Optional reference to one or more narrative beats (each value matches an id from narrative.beats or the resolved template). 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. Slides without a beat are valid; multiple slides may share a beat."
+          "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 slide layout reference. Resolves to the 'id' of a 'layouts' catalog record. When omitted, engines infer a layout from the slide's root payload or promoted region keys. Accepts a bare id (lowercase kebab-case, e.g. 'title-subtitle'), an HTTPS URL pointing at a record file, or a 'pkg:' reference. Free-form custom layout names that don't resolve through any catalog fall through to engine-defined layouts.\n\nResolution order: inline catalogs.layouts.records[] \u2192 catalogs.layouts.source \u2192 default catalog at https://www.pptx.gallery/layouts.",
+          "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.",
           "examples": [
             "title",
             "title-subtitle",
@@ -3131,25 +2886,62 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           ]
         },
         "title": {
-          "type": "string",
-          "description": "Slide-level title content. When the resolved layout exposes a 'title' placeholder, the engine renders this value there.",
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/TextRun"
+              }
+            }
+          ],
+          "description": "Slide-level title content. When the resolved layout exposes a 'title' placeholder, the engine renders this value there. Use a string for plain text or TextRun[] for inline rich text (a colored word, bold, a link, a citation or footnote marker); the heading keeps its size and fitting rules either way, and run colors resolve like body text.",
           "examples": [
             "Quarterly Review",
             "Why Now",
-            "Next Steps"
+            "Next Steps",
+            [
+              "Revenue grew ",
+              {
+                "text": "28%",
+                "color": "accent1"
+              }
+            ]
           ]
         },
         "subtitle": {
-          "type": "string",
-          "description": "Slide-level subtitle or supporting line. When the resolved layout exposes a 'subtitle' placeholder, the engine renders this value there.",
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/TextRun"
+              }
+            }
+          ],
+          "description": "Slide-level subtitle or supporting line. When the resolved layout exposes a 'subtitle' placeholder, the engine renders this value there. Use a string for plain text or TextRun[] for inline rich text (a colored word, bold, a link, a citation or footnote marker); the heading keeps its size and fitting rules either way, and run colors resolve like body text.",
           "examples": [
             "Prepared for the board",
             "Three signals changed this quarter"
           ]
         },
         "tag": {
-          "type": "string",
-          "description": "Small slide-level label or badge. When the resolved layout exposes a 'tag' placeholder, the engine renders this value there.",
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/TextRun"
+              }
+            }
+          ],
+          "description": "Small slide-level label or badge. When the resolved layout exposes a 'tag' placeholder, the engine renders this value there. Use a string for plain text or TextRun[] for inline rich text (a colored word, bold, a link, a citation or footnote marker); the heading keeps its size and fitting rules either way, and run colors resolve like body text.",
           "examples": [
             "Intro",
             "Confidential",
@@ -3211,7 +3003,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
         },
         "video": {
           "$ref": "#/$defs/Asset",
-          "description": "Full-slide video source. Presence of this field infers type 'video'."
+          "description": "Full-slide video source. Presence of this field infers type 'video'. 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)."
         },
         "chart": {
           "$ref": "#/$defs/Chart",
@@ -3244,7 +3036,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
               "$ref": "#/$defs/Metric"
             }
           ],
-          "description": `Full-slide metric payload. A string or number is shorthand for { "value": value }; object form carries optional label, description, unit, delta, and trend metadata. Numeric values remain numbers; renderers format them for display. Presence of this field infers type 'metric'.`
+          "description": `Full-slide metric payload. A string or number is shorthand for { "value": value }; object form carries optional label, description, unit, delta, trend, and sentiment metadata. Numeric values remain numbers; renderers format them for display. Presence of this field infers type 'metric'.`
         },
         "quote": {
           "oneOf": [
@@ -3273,7 +3065,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           "description": "Layout-agnostic content blocks rendered together as a composed payload when exact placement is unspecified. At slide root, multiple content payload kinds with no explicit type, blocks, or regions are accepted as shorthand for equivalent blocks."
         },
         "design": {
-          "$ref": "#/$defs/Design",
+          "$ref": "#/$defs/SlideDesign",
           "description": "Slide-level design applied on top of the deck-wide design."
         },
         "left": {
@@ -3440,7 +3232,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
         },
         "hidden": {
           "type": "boolean",
-          "description": "Whether the slide is hidden from the presented sequence."
+          "description": "Whether the slide is hidden from the presented sequence. The player skips it, the PPTX export writes it as a hidden slide, and per-slide image and PDF output skips it unless the caller asks to include hidden slides (opf CLI: --include-hidden; the deck-level renderSvg: the opt-in skipHidden). A slide named explicitly (opf render --slides, renderSvg slideIndex) is still rendered."
         },
         "composition": {
           "$ref": "#/$defs/Composition"
@@ -3581,7 +3373,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
         },
         "video": {
           "$ref": "#/$defs/Asset",
-          "description": "Source for a video item.",
+          "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).",
           "examples": [
             "asset:demo-video",
             "./media/demo.mp4"
@@ -3626,7 +3418,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
               "$ref": "#/$defs/Metric"
             }
           ],
-          "description": 'Metric payload. A string or number is shorthand for { "value": value }; object form carries optional label, description, unit, delta, and trend metadata. Numeric values remain numbers; renderers format them for display.',
+          "description": 'Metric payload. A string or number is shorthand for { "value": value }; object form carries optional label, description, unit, delta, trend, and sentiment metadata. Numeric values remain numbers; renderers format them for display.',
           "examples": [
             "98%",
             42,
@@ -3648,7 +3440,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
               "$ref": "#/$defs/Quote"
             }
           ],
-          "description": 'Quote payload. A string is shorthand for { "text": value }; object form carries optional attribution and source metadata.',
+          "description": 'Quote payload. A string is shorthand for { "text": value }; object form carries optional attribution, role, photo and source metadata.',
           "examples": [
             "This changed how our team handles reviews.",
             {
@@ -3967,29 +3759,70 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
     },
     "Quote": {
       "type": "object",
-      "description": `Quote content with optional attribution metadata. Use 'text' for the quoted text, 'attribution' for the credited person or organization, and 'source' for a citation or URL. A string value in a quote field is shorthand for { "text": value }.`,
+      "description": `Quote content with optional attribution metadata. Use 'text' for the quoted text, 'attribution' for the credited person or organization, 'role' for that person's title and organization, 'photo' for their headshot and 'source' for a citation or URL. A string value in a quote field is shorthand for { "text": value }.`,
       "additionalProperties": false,
       "required": [
         "text"
       ],
       "properties": {
         "text": {
-          "type": "string",
-          "description": "Quoted text.",
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/TextRun"
+              }
+            }
+          ],
+          "description": "Quoted text: a string, or TextRun[] for inline rich text (a colored phrase, bold, a link, or a citation or footnote marker). The engine draws the surrounding quotation marks.",
           "examples": [
-            "This changed how our team handles reviews."
+            "This changed how our team handles reviews.",
+            [
+              "Cut review time by ",
+              {
+                "text": "40%",
+                "bold": true
+              },
+              {
+                "text": " in a quarter",
+                "cite": "acme-case-study"
+              }
+            ]
           ]
         },
         "attribution": {
           "type": "string",
-          "description": "Person or organization credited for the quote.",
+          "description": "Person or organization credited for the quote. Drawn after the quote text, in the muted text color.",
           "examples": [
-            "VP Operations, Acme Corp"
+            "Priya Raman",
+            "Acme Corp"
+          ]
+        },
+        "role": {
+          "type": "string",
+          "description": "Title and organization of the attributed person. Drawn on its own line under the attribution; without an attribution it stands alone. It does not replace the attribution, so the person's name belongs in 'attribution'.",
+          "examples": [
+            "VP Operations, Acme",
+            "Head of Platform"
+          ]
+        },
+        "photo": {
+          "$ref": "#/$defs/Asset",
+          "description": "Headshot of the attributed person, drawn as a circle beside the attribution and role lines (on the end side in a right-to-left deck). Give it alt text (validate's opf/missing-alt-text rule checks it). A raster photograph works best; an SVG exports as its PNG raster because the circular mask is not confirmed on SVG pictures in PowerPoint. An unresolved source draws the ordinary image placeholder.",
+          "examples": [
+            "./assets/priya-raman.jpg",
+            {
+              "src": "asset:priya-raman",
+              "alt": "Priya Raman"
+            }
           ]
         },
         "source": {
           "type": "string",
-          "description": "Optional quote source, citation, or URL.",
+          "description": "Optional quote source, citation, or URL. Follows the attribution and role after ' - '.",
           "examples": [
             "Customer interview, March 2026",
             "https://acme.com/case-study"
@@ -3999,7 +3832,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
     },
     "Code": {
       "type": "object",
-      "description": `Code content with optional rendering metadata. Use 'source' for the code text, 'language' for syntax highlighting, and 'filename' when the rendered block should show a file label. A string value in a code field is shorthand for { "source": value }.`,
+      "description": `Code content with optional rendering metadata. Use 'source' for the code text, 'language' for syntax highlighting, 'filename' when the rendered block should show a file label, and 'highlight' to emphasize lines. A string value in a code field is shorthand for { "source": value }.`,
       "additionalProperties": false,
       "required": [
         "source"
@@ -4034,12 +3867,52 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "components/Button.tsx",
             "terraform/main.tf"
           ]
+        },
+        "highlight": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "oneOf": [
+              {
+                "type": "integer",
+                "minimum": 1
+              },
+              {
+                "type": "array",
+                "minItems": 2,
+                "maxItems": 2,
+                "items": {
+                  "type": "integer",
+                  "minimum": 1
+                }
+              }
+            ]
+          },
+          "description": "Source lines to emphasize, 1-based: each entry is a line number or an inclusive [start, end] range, so [3, [5, 7]] marks lines 3 and 5 to 7. Lines are counted by line break in 'source', so a line that wraps stays one line. Engines draw a theme-derived band behind the marked lines and dim the other lines slightly, keeping every line at least 4.5:1 against its background; PPTX export draws one native rectangle behind the line text boxes and import restores the list. A line number past the last line, or a range written end before start, gets a validation warning (code-highlight-out-of-range, code-highlight-range-reversed) and is ignored. When a code block is paginated across slides each page keeps the lines that fall on it, renumbered from 1.",
+          "examples": [
+            [
+              3
+            ],
+            [
+              3,
+              [
+                5,
+                7
+              ]
+            ],
+            [
+              [
+                2,
+                4
+              ]
+            ]
+          ]
         }
       }
     },
     "Metric": {
       "type": "object",
-      "description": `Metric content with optional display metadata. Use 'value' for the primary value, 'label' for the metric name, 'description' for supporting context, 'unit' for a suffix/currency marker, 'delta' for change, and 'trend' for direction. A string or number value in a metric field is shorthand for { "value": value }; numeric values remain numbers and are formatted by renderers.`,
+      "description": `Metric content with optional display metadata. Use 'value' for the primary value, 'label' for the metric name, 'description' for supporting context, 'unit' for a suffix/currency marker, 'delta' for change, 'trend' for direction, and 'sentiment' for whether the change is good news. A string or number value in a metric field is shorthand for { "value": value }; numeric values remain numbers and are formatted by renderers.`,
       "additionalProperties": false,
       "required": [
         "value"
@@ -4109,7 +3982,16 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "down",
             "flat"
           ],
-          "description": "Metric trend direction."
+          "description": "Metric trend direction. The preview and the PowerPoint export draw an arrow beside the trend word that always points the way the trend does (up, down or flat) and colour the arrow, the trend word and the delta text by `sentiment`."
+        },
+        "sentiment": {
+          "type": "string",
+          "enum": [
+            "positive",
+            "negative",
+            "neutral"
+          ],
+          "description": "Whether the change is good news. Positive draws the trend arrow and the trend and delta text in green, negative in red and neutral in the neutral text colour, each kept at 4.5:1 contrast or more against the slide background. When absent the colour follows the trend: up is positive, down is negative and flat is neutral. Set it when the direction is not the verdict, for example positive on a falling churn, cost or latency trend. The arrow always keeps the direction of `trend`. Only the trend arrow and the trend and delta text take the colour, so sentiment has no visible effect on a metric without a trend."
         }
       }
     },
@@ -4189,6 +4071,20 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           "examples": [
             "Launch with the first operations team."
           ]
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "done",
+            "current",
+            "planned"
+          ],
+          "description": "Progress of the event, drawn from the deck's own colors by both the SVG renderer and the PPTX exporter. Absent means no status and the event is drawn as a plain filled marker with normal text, which is also how 'done' looks. 'done' is a filled marker in the primary color with normal text. 'current' marks 'we are here': the filled marker is surrounded by a ring and the event label (`what`) is bold. 'planned' is an outlined, hollow marker (primary-color outline over the slide background) with muted secondary text. Text colors keep a 4.5:1 contrast against the slide background. In PPTX the markers are native ellipses (the ring is a second ellipse), and PPTX import restores the status the export recorded. Status describes progress only; schedule health such as at risk or blocked belongs in the event text.",
+          "examples": [
+            "done",
+            "current",
+            "planned"
+          ]
         }
       }
     },
@@ -4448,19 +4344,36 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             },
             "fontFamily": {
               "type": "string",
-              "description": "Run font family override.",
+              "description": "Run font family override. It wins over the code font a run with 'code' takes.",
               "examples": [
                 "Inter",
                 "Source Serif Pro",
                 "JetBrains Mono"
               ]
             },
+            "code": {
+              "type": "boolean",
+              "description": "Whether the run is an inline code span: it is drawn in the design's code font (design.fontScheme.code, else the resolved font scheme's code family, else Roboto Mono), unless the run names its own fontFamily. Only the font changes; there is no background, because a PPTX run cannot have one. Markdown backticks read and write code runs."
+            },
+            "lang": {
+              "type": "string",
+              "pattern": "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$",
+              "description": "BCP-47 language tag of the run, such as 'fr-FR' or 'ja-JP', when it differs from the deck language. It sets the proofing language (PPTX a:rPr lang) and the language the run's script fonts and glyph variants follow (for example the Japanese or the Simplified Chinese face for Han characters); without it the run follows the deck language.",
+              "examples": [
+                "fr-FR",
+                "ja-JP",
+                "de"
+              ]
+            },
             "link": {
               "type": "string",
-              "description": "URL to link the run text to.",
+              "pattern": "^(https?://|mailto:|tel:)\\S+$",
+              "description": "URL to link the run text to: an http(s) URL, a 'mailto:' address or a 'tel:' number, without whitespace. The preview draws it as a link and PPTX export writes a native hyperlink for all three; any other scheme is not valid.",
               "examples": [
                 "https://acme.com",
-                "https://acme.com/case-studies/beta"
+                "https://acme.com/case-studies/beta",
+                "mailto:hello@acme.com",
+                "tel:+15551234567"
               ]
             },
             "superscript": {
@@ -4486,7 +4399,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
                   }
                 }
               ],
-              "description": "One or more ids from the top-level references list that this run cites. Engines draw a superscript marker ('1', or '1,2' for several ids) directly after the run and list '<n> <reference text>' in the slide's footnote area; markers are numbered per deck in order of first use, and the same id keeps its number. An id missing from references is a validation error (cite-unknown-reference). Supported in text, bullets and list item runs.",
+              "description": "One or more ids from the top-level references list that this run cites. Engines draw a superscript marker ('1', or '1,2' for several ids) directly after the run and list '<n> <reference text>' in the slide's footnote area; markers are numbered per deck in order of first use, and the same id keeps its number. An id missing from references is a validation error (cite-unknown-reference). Supported in text, bullets and list item runs, in the slide title, subtitle and tag, and in the quote text.",
               "examples": [
                 "gartner-2026",
                 [
@@ -4509,7 +4422,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
                   }
                 }
               ],
-              "description": "An inline note for this run, without a references entry. Engines draw a superscript marker after the run and list the note in the slide's footnote area; every footnote takes a new number in the deck's marker sequence. Supported in text, bullets and list item runs.",
+              "description": "An inline note for this run, without a references entry. Engines draw a superscript marker after the run and list the note in the slide's footnote area; every footnote takes a new number in the deck's marker sequence. Supported in text, bullets and list item runs, in the slide title, subtitle and tag, and in the quote text.",
               "examples": [
                 "Excludes the discontinued hardware line."
               ]
@@ -4632,7 +4545,7 @@ 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; deprecated ids still resolve but validate with a warning naming their replacement.",
+          "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').",
           "examples": [
             "column",
             "bar",
@@ -4645,7 +4558,8 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "waterfall",
             "funnel",
             "treemap",
-            "stacked-column-3x"
+            "stacked-column",
+            "combo"
           ]
         },
         "data": {
@@ -4653,22 +4567,47 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             {
               "$ref": "#/$defs/ChartData"
             },
-            {
-              "$ref": "#/$defs/ChartDataSource"
-            },
             {
               "$ref": "#/$defs/DatasetRef"
             }
           ],
-          "description": `Chart data. Inline data uses a tabular columns/rows shape; renderers convert rows to chart series internally. A DatasetRef ({ "dataset": "<id>" }) plots a top-level dataset instead. A ChartDataSource is not resolved by any engine (a 'chart-data-source-unresolved' warning; engines draw a placeholder); prefer inline data with a 'source'.`
+          "description": 'Chart data. Inline data uses a tabular columns/rows shape; renderers convert rows to chart series internally. A DatasetRef ({ "dataset": "<id>" }) plots a top-level dataset instead. Data from a spreadsheet or file is imported into inline columns and rows, and its origin is recorded in data.source.'
         },
         "mapping": {
           "$ref": "#/$defs/ChartMapping",
           "description": "Optional series mapping by column name: which column is the category, which is the X column of a scatter chart, and which columns are plotted, in order. Absent keeps the positional rule (first column the category, then the X column for scatter, every other column a series)."
         },
+        "line": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "Combo charts only (type 'combo'): the plotted series, by column name, that are drawn as lines with markers; every other plotted series is drawn as clustered columns. Absent: the last plotted series is the line. A combo chart keeps at least one column series, so a list that names every series draws the first one as columns. Column series are drawn, exported and listed in the legend first, then the line series on the primary axis, then those on the secondary axis, each in plotted order. A name that is not a column is a 'chart-mapping-unknown-column' error; a column that is not plotted is a 'chart-mapping-adapted' warning. On any other chart type it is ignored with a 'chart-option-adapted' warning.",
+          "examples": [
+            [
+              "Margin"
+            ]
+          ]
+        },
+        "secondaryAxis": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "Combo charts only: line series, by column name, plotted against a secondary value axis at the right of the plot. That axis has its own scale, and its tick labels use the number format of the first secondary series' column (DataColumn.format), for example '0%' for a margin. Absent: every series shares the primary value axis at the left. A name that is not a line series (see 'line') stays on the primary axis with a 'chart-mapping-adapted' warning; an unknown column is a 'chart-mapping-unknown-column' error. On any other chart type it is ignored with a 'chart-option-adapted' warning.",
+          "examples": [
+            [
+              "Margin"
+            ]
+          ]
+        },
         "axisTitles": {
           "$ref": "#/$defs/ChartAxisTitles",
-          "description": "Optional axis titles. Absent keeps today's untitled axes. Supported on the chart types that have a category/value (or X/Y) axis pair (column, bar, line, area, scatter, and the histogram, pareto, waterfall and box-and-whisker constructs; the funnel construct takes a category title only); a title on a type without that axis (pie, doughnut, radar, treemap, map) is dropped with a 'chart-option-adapted' diagnostic by renderers and exporters."
+          "description": "Optional axis titles. Absent keeps today's untitled axes. Supported on the chart types that have a category/value (or X/Y) axis pair (column, bar, line, area, scatter, and the histogram, pareto, waterfall and box-and-whisker constructs; the funnel construct takes a category title only; a combo chart also takes 'secondary' when it plots a series on the secondary axis); a title on a type without that axis (pie, doughnut, radar, treemap, map) is dropped with a 'chart-option-adapted' diagnostic by renderers and exporters."
         },
         "legend": {
           "type": "string",
@@ -4691,13 +4630,24 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             }
           ],
           "description": "Optional data labels. true shows value labels at each type's default position, false (or absent) shows none, which is today's behaviour. Use the object form for the label content, position and separator."
+        },
+        "alt": {
+          "type": "string",
+          "description": "Text alternative for the chart: what the data shows (the point and the key numbers), not 'a chart' or 'bar chart'. The preview exposes it as the chart's accessible name (role img with aria-label) and the PowerPoint export writes it as the chart frame's alternative text (descr); import reads it back. An empty string marks the chart decorative, with the same meaning as an empty Asset alt, but it is a reviewed choice that opf/chart-text-alternative still reports as info (a chart almost always carries a message). When absent, validate accepts text beside the chart instead.",
+          "examples": [
+            "Revenue grew from $12M in Q1 to $18M in Q2, with the steepest rise in the West region."
+          ]
+        },
+        "highlight": {
+          "$ref": "#/$defs/ChartHighlight",
+          "description": "Optional emphasis: the series and/or categories that carry the message. The engines draw the highlighted marks in the deck's primary (accent) color and every other mark in a muted neutral derived from the theme (a light grey on a light chart panel, a dim grey on a dark one); there is no color field. A mark is highlighted when its series OR its category is named. Absent keeps today's colors exactly. Supported on column, bar and line charts (series and categories; on a line a category highlight marks that category's points), pie and doughnut charts (categories, one per slice), and area, scatter and radar charts (series); the histogram, pareto, waterfall, funnel, treemap, box-and-whisker, map and combo constructs drop the option with a 'chart-option-adapted' diagnostic, as does a part the type cannot highlight. A name that matches no column or row label is a 'chart-highlight-unknown-name' error."
         }
       }
     },
     "ChartAxisTitles": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Titles for the two axes of a chart. 'category' is the axis that carries the row labels (the horizontal axis of a column or line chart, the vertical axis of a bar chart, the X axis of a scatter chart); 'value' is the other axis.",
+      "description": "Titles for the axes of a chart. 'category' is the axis that carries the row labels (the horizontal axis of a column or line chart, the vertical axis of a bar chart, the X axis of a scatter chart); 'value' is the other axis; 'secondary' is the secondary value axis of a combo chart.",
       "properties": {
         "category": {
           "type": "string",
@@ -4709,14 +4659,69 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
         },
         "value": {
           "type": "string",
-          "description": "Title of the value (Y) axis.",
+          "description": "Title of the value (Y) axis. On a combo chart, the primary (left) value axis.",
           "examples": [
             "Revenue ($M)",
             "Customers"
           ]
+        },
+        "secondary": {
+          "type": "string",
+          "description": "Combo charts only: title of the secondary value axis at the right of the plot, drawn rotated like the primary value axis title. Dropped with a 'chart-option-adapted' diagnostic on any other chart type and on a combo chart without 'secondaryAxis'.",
+          "examples": [
+            "Margin (%)"
+          ]
         }
       }
     },
+    "ChartHighlight": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "description": "Which series and categories a chart emphasizes. Names are matched exactly: series by data column name (after any 'fields' selection; a series is a plotted value column), categories by row label (the first column, or mapping.category), as text. A category label shared by several rows highlights each of them.",
+      "properties": {
+        "series": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "Series (value columns) to highlight: all marks of each named series. A name that is not a column is a 'chart-highlight-unknown-name' error; a column that is not plotted as a series (the category or X column, or one mapping.series leaves out) highlights nothing and is a 'chart-highlight-adapted' warning.",
+          "examples": [
+            [
+              "Revenue"
+            ]
+          ]
+        },
+        "categories": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "Categories (row labels) to highlight: the marks of each named category (a column or bar of every series, a line's points, a pie or doughnut slice). A label no row has is a 'chart-highlight-unknown-name' error.",
+          "examples": [
+            [
+              "Q3"
+            ]
+          ]
+        }
+      },
+      "examples": [
+        {
+          "series": [
+            "Revenue"
+          ]
+        },
+        {
+          "categories": [
+            "Q3"
+          ]
+        }
+      ]
+    },
     "ChartDataLabels": {
       "type": "object",
       "additionalProperties": false,
@@ -4749,7 +4754,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
             "left",
             "right"
           ],
-          "description": "Where a label sits relative to its mark. 'auto' (the default) is the type's default: outside-end for clustered columns and bars, pie slices and the histogram, pareto and waterfall constructs; center for stacked columns and bars; above for line and scatter points. Clustered columns and bars and the histogram, pareto and waterfall constructs take center, inside-end, inside-base and outside-end; stacked columns and bars take center, inside-end and inside-base; pie takes center, inside-end and outside-end; line and scatter points take above, below, left, right and center. Area, doughnut and radar charts and the funnel and treemap constructs take only 'auto' (the box-and-whisker and map constructs have no data labels). An unsupported position falls back to 'auto' with a 'chart-option-adapted' diagnostic."
+          "description": "Where a label sits relative to its mark. 'auto' (the default) is the type's default: outside-end for clustered columns and bars, pie slices and the histogram, pareto and waterfall constructs; center for stacked columns and bars; above for line and scatter points. Clustered columns and bars and the histogram, pareto and waterfall constructs take center, inside-end, inside-base and outside-end; stacked columns and bars take center, inside-end and inside-base; pie takes center, inside-end and outside-end; line and scatter points take above, below, left, right and center. Area, doughnut and radar charts and the funnel and treemap constructs take only 'auto' (the box-and-whisker and map constructs have no data labels). A combo chart places the labels of its column series like clustered columns and those of its line series like line points; a position only one part takes applies to that part, and the other part keeps its default (outside-end, above). An unsupported position falls back to 'auto' with a 'chart-option-adapted' diagnostic."
         },
         "separator": {
           "type": "string",
@@ -5274,60 +5279,6 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
         }
       ]
     },
-    "ChartDataSource": {
-      "type": "object",
-      "description": "Chart data sourced from an asset reference, URL, data URI, relative path, or local path such as CSV, TSV, JSON, or XLSX. The source is interpreted as a table; optional columns select or order fields from that table.",
-      "additionalProperties": false,
-      "required": [
-        "src"
-      ],
-      "properties": {
-        "src": {
-          "type": "string",
-          "description": "Data source. Use 'asset:<id>' to reference the top-level assets registry, or provide an HTTPS URL, data URI, relative path, or local filesystem path.",
-          "examples": [
-            "asset:revenue",
-            "asset:pipeline-csv",
-            "./data/revenue.csv",
-            "https://cdn.acme.com/data/revenue.csv"
-          ]
-        },
-        "sheet": {
-          "type": "string",
-          "description": "Optional sheet name or table name for spreadsheet-like assets.",
-          "examples": [
-            "Sheet1",
-            "Revenue"
-          ]
-        },
-        "range": {
-          "type": "string",
-          "description": "Optional A1-style range or engine-defined range selector for spreadsheet-like assets.",
-          "examples": [
-            "A1:D8",
-            "Revenue!A1:D8"
-          ]
-        },
-        "columns": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Optional ordered columns or fields to read from the source. When omitted, renderers may use the source's own header row or schema.",
-          "examples": [
-            [
-              "Quarter",
-              "Revenue"
-            ],
-            [
-              "Month",
-              "Revenue",
-              "Costs"
-            ]
-          ]
-        }
-      }
-    },
     "ChartDataCell": {
       "oneOf": [
         {
@@ -5528,7 +5479,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
       "properties": {
         "narratives": {
           "$ref": "#/$defs/CatalogEntry",
-          "description": "Catalog of narrative templates. Records validate against https://openpresentation.org/schema/opf-narrative/v1. Default source: https://www.pptx.gallery/narratives."
+          "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."
         },
         "themes": {
           "$ref": "#/$defs/CatalogEntry",
@@ -5590,7 +5541,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
               "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."
             }
           ],
-          "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. Fetching a declared source is an explicit opt-in: the engine or its caller performs that fetch."
+          "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",
@@ -5603,7 +5554,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
     },
     "CatalogSource": {
       "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>]'; resolved through a locally-installed package on the engine's package path.",
+      "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.",
       "examples": [
         "https://www.pptx.gallery/narratives",
         "https://acme.com/decks/narratives/index.json",
@@ -5795,7 +5746,7 @@ var audience = {
     "attentionBudgetMinutes": {
       "type": "number",
       "exclusiveMinimum": 0,
-      "description": "Realistic upper bound on this audience's focused attention for a single presentation, in minutes. Used as a hint when comparing against duration and the resolved narrative's durationRange."
+      "description": "Realistic upper bound on this audience's focused attention for a single presentation, in minutes. Used as a hint when comparing against duration and the resolved narrative's duration range."
     },
     "recommendedNarratives": {
       "type": "array",
@@ -6288,6 +6239,9 @@ var theme = {
         "16:9",
         "4:3",
         "16:10",
+        "1:1",
+        "4:5",
+        "9:16",
         "letter",
         "a4",
         "widescreen",
@@ -6298,6 +6252,9 @@ var theme = {
         "16:9",
         "4:3",
         "16:10",
+        "1:1",
+        "4:5",
+        "9:16",
         "letter",
         "a4",
         "widescreen",
@@ -6459,159 +6416,16 @@ var layout = {
         "Two equal-width columns under a left-aligned slide title. Use when comparing two ideas, before/after pairs, or paired text + image content."
       ]
     },
-    "contentType": {
-      "type": "string",
-      "enum": [
-        "Title",
-        "Text",
-        "List",
-        "Image",
-        "Number",
-        "Metric",
-        "Chart",
-        "Table",
-        "Code",
-        "Video",
-        "Quote",
-        "Timeline"
-      ],
-      "description": "Primary kind of content the layout holds. Drives pickers and AI placement decisions. Metric is the canonical numeric/KPI category; Number remains an accepted legacy label."
-    },
-    "contentMultiple": {
-      "type": "string",
-      "enum": [
-        "None",
-        "1x",
-        "2x",
-        "3x",
-        "4x",
-        "5x",
-        "6x"
-      ],
-      "description": "How many parallel content blocks the layout exposes ('2x' = two-column, '3x' = three-up, etc.)."
-    },
-    "contentAlignment": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Left",
-        "Center"
-      ],
-      "description": "Default horizontal alignment of the content area."
-    },
-    "contentBox": {
-      "type": "boolean",
-      "description": "Whether the content area is rendered inside a visible box / card.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "contentTypeChartPrimary": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Top",
-        "Bottom",
-        "Left",
-        "Right"
-      ],
-      "description": "For chart layouts, where the primary chart sits relative to the rest of the content."
-    },
-    "contentTypeImageFill": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Crop",
-        "Fit"
-      ],
-      "description": "For image layouts, how the image fills its slot."
-    },
-    "contentTypeListBullet": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Character",
-        "Image"
-      ],
-      "description": "For list layouts, how bullets are rendered."
-    },
-    "contentTypeListHeading": {
-      "type": "boolean",
-      "description": "For list layouts, whether each list item carries a heading.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "slideTag": {
-      "type": "boolean",
-      "description": "Whether the layout includes a small slide-level tag / label region above or near the title.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "slideTitle": {
-      "type": "boolean",
-      "description": "Whether the layout includes a slide title region.",
-      "examples": [
-        true,
-        false
-      ]
-    },
-    "slideSubtitle": {
-      "type": "boolean",
-      "description": "Whether the layout includes a slide-level subtitle or supporting-description region. When placeholders is present, this is true exactly when the layout exposes a placeholder with type 'subtitle'.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "slideTitleAlignment": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Left",
-        "Center"
-      ],
-      "description": "Horizontal alignment of the slide title region."
-    },
-    "slideImage": {
-      "type": "boolean",
-      "description": "Whether the layout includes a dedicated slide-level image region (separate from any content image).",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "slideImageAlignment": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Top",
-        "Bottom",
-        "Left",
-        "Right",
-        "Background"
-      ],
-      "description": "Where the slide-level image sits relative to the content."
-    },
-    "slideLayoutDirection": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Horizontal",
-        "Vertical"
-      ],
-      "description": "Axis along which the layout's primary regions are arranged."
+    "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."
     },
     "placeholders": {
       "type": "array",
       "items": {
         "$ref": "#/$defs/Placeholder"
       },
-      "description": "Ordered regions the layout exposes. The engine fills 'title', 'subtitle', and 'tag' placeholders from Slide.title, Slide.subtitle, and Slide.tag. Other placeholders are content-kind hints for renderers and pickers. Slide content itself lives either in root payload fields or promoted region keys on Slide. Chrome \u2014 slide number, footer, date \u2014 is not included here; it is owned by Design.header / Design.footer."
+      "description": "Ordered regions the layout exposes. This is the single source of truth for what the layout holds: the content kind, the number of body regions and whether it has a title, subtitle or tag are derived from it (layoutContent in @openpresentation/opf), never stored separately. The engine fills 'title', 'subtitle' and 'tag' placeholders from Slide.title, Slide.subtitle and Slide.tag. The other placeholders are content-kind regions that composition uses to size the body and that pickers use to match layouts. Slide content itself lives either in root payload fields or promoted region keys on Slide. Chrome (slide number, footer, date) is not included here; it is owned by Design.header / Design.footer."
     },
     "tags": {
       "type": "array",
@@ -6643,7 +6457,7 @@ var layout = {
           "format": "uri",
           "description": "Main preview image (PNG/JPG). Used as the primary visual in picker UIs and previews of the record.",
           "examples": [
-            "https://www.pptx.gallery/layouts/title-left.png"
+            "https://example.com/layouts/title-subtitle.png"
           ]
         },
         "thumbnailSrc": {
@@ -6651,7 +6465,7 @@ var layout = {
           "format": "uri",
           "description": "Smaller thumbnail preview suited to dense grid views.",
           "examples": [
-            "https://www.pptx.gallery/layouts/title-left.thumbnail.png"
+            "https://example.com/layouts/title-subtitle.thumbnail.png"
           ]
         },
         "vectorSrc": {
@@ -6659,7 +6473,7 @@ var layout = {
           "format": "uri",
           "description": "SVG / vector preview for crisp scaling at any size.",
           "examples": [
-            "https://www.pptx.gallery/layouts/title-left.svg"
+            "https://www.pptx.gallery/layout-previews/title-subtitle.svg"
           ]
         }
       }
@@ -6674,7 +6488,7 @@ var layout = {
       "required": [
         "type"
       ],
-      "description": "A single region inside a slide layout. Title, subtitle, and tag placeholders bind to the corresponding Slide fields; other placeholders describe the intended content kind for that region. The array order in the surrounding 'placeholders' field preserves layout region order.",
+      "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.",
       "properties": {
         "type": {
           "type": "string",
@@ -6683,18 +6497,102 @@ var layout = {
             "subtitle",
             "tag",
             "text",
-            "metric",
-            "quote",
-            "timeline",
             "list",
+            "image",
+            "video",
             "chart",
-            "picture",
             "table",
-            "media",
-            "diagram",
-            "code"
+            "code",
+            "metric",
+            "quote",
+            "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."
+        }
+      }
+    },
+    "DesignHints": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Design hints a layout carries. The keys and lowercase values are those of the deck's design and a slide's design in opf.schema.json (Design), so a slide overrides a layout by the same name and layout.design can be copied into slide.design unchanged. An absent key means the layout has no opinion. Only the keys the layout sets are stored. scripts/check-spec-integrity.mjs verifies that every key here has the same type and values as its Design counterpart.",
+      "properties": {
+        "titleAlignment": {
+          "type": "string",
+          "enum": [
+            "left",
+            "center",
+            "right"
+          ],
+          "description": "Horizontal alignment of the title placeholder."
+        },
+        "contentAlignment": {
+          "type": "string",
+          "enum": [
+            "left",
+            "center",
+            "right"
+          ],
+          "description": "Horizontal alignment of the body regions."
+        },
+        "contentBox": {
+          "type": "boolean",
+          "description": "Whether the body regions are drawn inside a visible card or surface."
+        },
+        "contentDirection": {
+          "type": "string",
+          "enum": [
+            "horizontal",
+            "vertical"
           ],
-          "description": "OPF placeholder kind. 'text' and 'list' are flexible textual content regions. 'metric' is a numeric/KPI content region filled by a metric payload, including its optional label, description, unit, delta, and trend. The named kinds describe a specific content role used by pickers, AI generation, and engine defaulting. 'picture' and legacy 'diagram' use image payloads; 'media' uses video. Quote and timeline use their corresponding payload fields."
+          "description": "Axis along which parallel body content is arranged: 'vertical' is a column, 'horizontal' a row. Composition applies it when neither the slide nor this layout's composition sets a mode, below the slide's and the deck's design.contentDirection and above automatic selection."
+        },
+        "chartPrimary": {
+          "type": "string",
+          "enum": [
+            "none",
+            "top",
+            "bottom",
+            "left",
+            "right"
+          ],
+          "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": {
+          "type": "string",
+          "enum": [
+            "crop",
+            "fit"
+          ],
+          "description": "How images fill their region: 'crop' covers the region, 'fit' shows the whole image."
+        },
+        "listBullet": {
+          "type": "string",
+          "enum": [
+            "character",
+            "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."
+            }
+          }
         }
       }
     },
@@ -6764,7 +6662,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). Each record describes a named chart variant, its Open XML mapping, its series/category cardinality, the column structure of the underlying workbook, and a small sample dataset suitable for previews. 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 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.`,
   "type": "object",
   "additionalProperties": false,
   "patternProperties": {
@@ -6787,29 +6685,19 @@ var chartType = {
     "id": {
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this 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": "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.",
       "examples": [
         "column",
         "bar",
-        "stacked-column-3x",
+        "stacked-column",
         "doughnut",
         "treemap",
-        "100pct-stacked-column-3x"
+        "100pct-stacked-column"
       ]
     },
     "name": {
       "type": "string",
-      "description": "Stable display/programmatic name for this chart type.",
-      "examples": [
-        "COLUMN",
-        "STACKED_COLUMN_3X",
-        "DOUGHNUT",
-        "TREEMAP"
-      ]
-    },
-    "label": {
-      "type": "string",
-      "description": "Human-readable label shown in chart pickers.",
+      "description": "Human-readable name of the chart type, as a chart picker shows it.",
       "examples": [
         "Column",
         "Stacked Column",
@@ -6822,14 +6710,14 @@ var chartType = {
       "description": "One-sentence positioning: when to reach for this chart variant.",
       "examples": [
         "Single-series vertical column chart for comparing values across categories.",
-        "Bullet chart that benchmarks one value against ranked threshold bands."
+        "Stacked column chart that shows how the parts of each category add up to its total."
       ]
     },
     "description": {
       "type": "string",
       "description": "Longer prose describing the chart and ideal use cases.",
       "examples": [
-        "Use a clustered column when you want to compare a small number of series across the same categories \u2014 e.g., revenue by quarter for two product lines. Best with 2\u20134 series and \u226412 categories."
+        "Use a stacked column when you want to compare totals across categories and also show how each series contributes \u2014 e.g., revenue by quarter split by product line. Best with 2\u20134 series and \u226412 categories."
       ]
     },
     "mappings": {
@@ -6838,11 +6726,11 @@ var chartType = {
     },
     "deprecation": {
       "$ref": "#/$defs/ChartTypeDeprecation",
-      "description": "Present when this chart type is deprecated. Deprecated records stay resolvable so existing documents keep validating, but pickers and default listings exclude them, validators warn when a document references them, and they are removed in the release named by `removal`."
+      "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 (column, bar, line, area, pie, radar, etc.).",
+      "description": "Top-level grouping in the chart picker.",
       "examples": [
         "Column",
         "Bar",
@@ -6853,9 +6741,8 @@ var chartType = {
         "Histogram",
         "XY (Scatter)",
         "Treemap",
-        "Bullet",
-        "Sparkline",
         "Map",
+        "Combo",
         "Other"
       ]
     },
@@ -6877,155 +6764,18 @@ var chartType = {
         "hierarchical",
         "normalized"
       ],
-      "description": "Shape of the underlying data: a flat series ('simple'), one with engine-side calculation ('calculated'), parent-child rows ('hierarchical'), or pre-normalized rows ('normalized')."
+      "description": "Shape of the underlying data: a flat series ('simple'), one with engine-side calculation ('calculated'), parent-child rows ('hierarchical'), or pre-normalized rows ('normalized'). The editor offers only 'simple' types as switch targets for a chart's existing data."
     },
     "series": {
       "type": "integer",
       "minimum": 0,
-      "description": "Number of data series this chart type expects.",
-      "examples": [
-        1,
-        2,
-        3,
-        4
-      ]
-    },
-    "categories": {
-      "type": "integer",
-      "minimum": 0,
-      "description": "Number of category labels this chart type expects on the primary axis.",
-      "examples": [
-        4,
-        6,
-        8,
-        12
-      ]
-    },
-    "seriesGroups": {
-      "type": "integer",
-      "minimum": 1,
-      "description": "Number of series groups (axis bands) this chart type uses; >1 for combo or banded charts.",
+      "description": "Number of data series this chart type expects: exactly that many, except that a stacked or percent-stacked type and a combination (composition 'mixed', such as combo) expect at least that many. The editor offers a type that expects more than one series only for data with a fitting number of value columns; a one-series type fits one value column, and column, bar, line, area and radar types fit any number.",
       "examples": [
         1,
         2,
         3
       ]
     },
-    "useSecondaryCategories": {
-      "type": "boolean",
-      "description": "Whether the chart type uses a secondary category axis.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "workbookRange": {
-      "type": "string",
-      "description": "A1 reference to the source range in the embedded workbook.",
-      "examples": [
-        "Sheet1!$A$1:$I$2",
-        "Sheet1!$A$1:$G$3"
-      ]
-    },
-    "columns": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Column header names of the embedded workbook, in left-to-right order.",
-      "examples": [
-        [
-          "Series 1",
-          "Value"
-        ],
-        [
-          "Series 1",
-          "Value 1",
-          "Value 2"
-        ]
-      ]
-    },
-    "dataColumns": {
-      "type": "array",
-      "items": {
-        "$ref": "#/$defs/ChartDataColumn"
-      },
-      "description": "Per-column metadata describing the role and position of each column in the workbook source.",
-      "examples": [
-        [
-          {
-            "name": "Series 1",
-            "role": "categoryLabel",
-            "type": "string",
-            "position": "row0_col0"
-          },
-          {
-            "name": "Value 1",
-            "role": "series",
-            "type": "number",
-            "position": "row1_col0"
-          },
-          {
-            "name": "Value 2",
-            "role": "series",
-            "type": "number",
-            "position": "row2_col0"
-          }
-        ]
-      ]
-    },
-    "helperColumns": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Optional auxiliary column names used by calculated or banded charts (e.g., 'Excellent', 'Good', 'Fair', 'Poor' for a bullet chart).",
-      "examples": [
-        [
-          "Excellent",
-          "Good",
-          "Fair",
-          "Poor"
-        ],
-        [
-          "Band"
-        ]
-      ]
-    },
-    "sampleData": {
-      "$ref": "#/$defs/ChartSampleData",
-      "description": "Inline sample dataset for previews and pickers.",
-      "examples": [
-        {
-          "headers": [
-            "Series 1",
-            "Q1 2024",
-            "Q2 2024",
-            "Q3 2024",
-            "Q4 2024"
-          ],
-          "rows": [
-            [
-              "Value",
-              93810,
-              24592,
-              13278,
-              46048
-            ]
-          ]
-        }
-      ]
-    },
-    "slideNumber": {
-      "type": "integer",
-      "minimum": 1,
-      "description": "Source slide number in the original chart-gallery deck. Carried for traceability.",
-      "examples": [
-        1,
-        2,
-        48
-      ]
-    },
     "tags": {
       "type": "array",
       "items": {
@@ -7038,9 +6788,8 @@ var chartType = {
           "comparison"
         ],
         [
-          "bullet",
-          "kpi",
-          "benchmark"
+          "stacked",
+          "composition"
         ]
       ]
     },
@@ -7053,7 +6802,7 @@ var chartType = {
           "format": "uri",
           "description": "Main preview image (PNG/JPG). Used as the primary visual in picker UIs and previews of the record.",
           "examples": [
-            "https://www.pptx.gallery/chart-types/clustered-column.png"
+            "https://www.pptx.gallery/chart-types/column.png"
           ]
         },
         "thumbnailSrc": {
@@ -7061,7 +6810,7 @@ var chartType = {
           "format": "uri",
           "description": "Smaller thumbnail preview suited to dense grid views.",
           "examples": [
-            "https://www.pptx.gallery/chart-types/clustered-column.thumbnail.png"
+            "https://www.pptx.gallery/chart-types/column.thumbnail.png"
           ]
         },
         "vectorSrc": {
@@ -7069,7 +6818,7 @@ var chartType = {
           "format": "uri",
           "description": "SVG / vector preview for crisp scaling at any size.",
           "examples": [
-            "https://www.pptx.gallery/chart-types/clustered-column.svg"
+            "https://www.pptx.gallery/chart-types/column.svg"
           ]
         }
       }
@@ -7089,7 +6838,7 @@ var chartType = {
           "description": "Id of the non-deprecated chart type that documents should reference instead.",
           "examples": [
             "column",
-            "stacked-column-3x"
+            "stacked-column"
           ]
         },
         "reason": {
@@ -7118,7 +6867,7 @@ var chartType = {
         },
         "renderers": {
           "type": "object",
-          "description": 'Optional renderer-specific mappings. Keys are renderer ids; values are intentionally opaque to OPF. The bundled catalog records the matching Aspose.Slides ChartType enumeration member under the "aspose-slides" key, e.g. {"aspose-slides": {"chartType": "StackedColumn"}}.',
+          "description": 'Optional renderer-specific mappings. Keys are renderer ids; values are intentionally opaque to OPF. The bundled catalog records the matching Aspose.Slides ChartType enumeration member under the "aspose-slides" key, e.g. {"aspose-slides": {"chartType": "StackedColumn"}}; a mixed composition names the ChartType it starts from and the series type it switches series to, e.g. {"chartType": "ClusteredColumn", "lineSeriesType": "LineWithMarkers"}.',
           "additionalProperties": {
             "type": "object",
             "additionalProperties": true
@@ -7217,171 +6966,49 @@ var chartType = {
           "description": "Short implementation note for mappings that need renderer interpretation."
         }
       }
+    }
+  }
+};
+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).",
+  "type": "object",
+  "required": [
+    "$schema",
+    "id",
+    "name",
+    "beats"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://openpresentation.org/schema/opf-narrative/v1"
+    },
+    "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."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable template name, e.g. 'Problem \u2192 Solution'."
     },
-    "ChartDataColumn": {
+    "deprecation": {
       "type": "object",
-      "description": "One column of the embedded chart workbook, annotated with its role and grid position.",
+      "additionalProperties": false,
       "required": [
-        "name",
-        "role",
-        "type"
+        "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": {
-        "name": {
+        "replacedBy": {
           "type": "string",
-          "description": "Column header name (e.g. 'Series 1', 'Value', 'Level1', 'Level2').",
-          "examples": [
-            "Series 1",
-            "Value",
-            "Level1",
-            "Level2"
-          ]
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Id of the non-deprecated narrative record that documents should reference instead."
         },
-        "role": {
-          "type": "string",
-          "enum": [
-            "categoryLabel",
-            "series",
-            "helper"
-          ],
-          "description": "Role this column plays: a category label (axis tick), a series (plotted values), or a helper (calculated/auxiliary)."
-        },
-        "type": {
-          "type": "string",
-          "enum": [
-            "string",
-            "number"
-          ],
-          "description": "Cell value type for the column."
-        },
-        "position": {
-          "type": "string",
-          "pattern": "^row[0-9]+_col[0-9]+$",
-          "description": "Grid position of the column header in the source workbook, as 'row<N>_col<M>' (zero-indexed).",
-          "examples": [
-            "row0_col0",
-            "row1_col0",
-            "row2_col0"
-          ]
-        }
-      }
-    },
-    "ChartSampleData": {
-      "type": "object",
-      "description": "Inline sample dataset for previews. Mirrors a small workbook with header row plus data rows.",
-      "required": [
-        "headers",
-        "rows"
-      ],
-      "properties": {
-        "headers": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Header row labels. The first cell typically labels the series column; the rest are category labels.",
-          "examples": [
-            [
-              "Series 1",
-              "Q1 2024",
-              "Q2 2024",
-              "Q3 2024",
-              "Q4 2024",
-              "Q1 2025",
-              "Q2 2025",
-              "Q3 2025",
-              "Q4 2025"
-            ]
-          ]
-        },
-        "rows": {
-          "type": "array",
-          "items": {
-            "type": "array",
-            "items": {
-              "type": [
-                "string",
-                "number"
-              ]
-            }
-          },
-          "description": "Two-dimensional sample data. Each row aligns by index with the headers \u2014 first cell is the row label, remaining cells are values.",
-          "examples": [
-            [
-              [
-                "Value",
-                93810,
-                24592,
-                13278,
-                46048,
-                42098,
-                39256,
-                28289,
-                23434
-              ]
-            ],
-            [
-              [
-                "Value 1",
-                98696,
-                81482,
-                21395,
-                87397
-              ],
-              [
-                "Value 2",
-                38657,
-                40495,
-                76237,
-                88907
-              ]
-            ]
-          ]
-        }
-      }
-    }
-  }
-};
-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. Each template describes a named story arc (e.g. 'problem-solution', 'scqa') as an ordered list of beats. Templates are referenced from OPF documents via narrative \u2014 either as a bare id string (e.g. 'classic-story') or as an inline object whose shape matches this schema (sans '$schema').",
-  "type": "object",
-  "required": [
-    "$schema",
-    "id",
-    "name",
-    "beats"
-  ],
-  "properties": {
-    "$schema": {
-      "type": "string",
-      "const": "https://openpresentation.org/schema/opf-narrative/v1"
-    },
-    "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."
-    },
-    "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": {
+        "reason": {
           "type": "string",
           "description": "Why the record is deprecated."
         },
@@ -7409,17 +7036,20 @@ var narrative = {
       },
       "description": "Audiences this narrative works well for, e.g. ['executive', 'investor', 'customer']."
     },
-    "durationRange": {
+    "duration": {
       "type": "object",
-      "description": "Typical talk-length window this narrative suits.",
+      "additionalProperties": false,
+      "description": "Typical talk length this narrative suits, as a range in minutes. A deck's own target is the root 'duration' (one number); core validate warns when that target lies outside this range, and when 'min' is greater than 'max'.",
       "properties": {
-        "minMinutes": {
+        "min": {
           "type": "number",
-          "exclusiveMinimum": 0
+          "exclusiveMinimum": 0,
+          "description": "Shortest talk length, in minutes, this narrative suits."
         },
-        "maxMinutes": {
+        "max": {
           "type": "number",
-          "exclusiveMinimum": 0
+          "exclusiveMinimum": 0,
+          "description": "Longest talk length, in minutes, this narrative suits."
         }
       }
     },
@@ -7472,7 +7102,7 @@ var narrative = {
   "$defs": {
     "Beat": {
       "type": "object",
-      "description": "A single narrative beat \u2014 a labeled segment of the story arc with a specific dramatic purpose. Mirrors the NarrativeBeat definition in opf.schema.json so library entries and inline OPF beats are interchangeable.",
+      "description": "A single narrative beat \u2014 a labeled segment of the story arc with a specific dramatic purpose. One beat is one slide: 'type' is that slide's Slide.type and 'layout' is its Slide.layout, so a planner copies them straight into a skeleton deck. Split a heavy beat into several beats rather than giving it several slides.",
       "required": [
         "id",
         "name"
@@ -7517,36 +7147,25 @@ var narrative = {
             "Inspire & conclude"
           ]
         },
-        "slideCount": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Optional explicit slide count for this beat. Defaults to 1 when omitted; values >1 are reserved for beats that intentionally span multiple slides. Prefer decomposing a heavy beat into multiple beats over setting a high slideCount. The validator emits a warning if the deck's actual count differs significantly.",
-          "examples": [
-            1,
-            2,
-            3
-          ]
-        },
-        "slideType": {
+        "type": {
           "type": "string",
           "enum": [
             "text",
             "list",
             "image",
-            "shape",
+            "video",
             "chart",
             "table",
-            "video",
             "code",
             "metric",
             "quote",
             "timeline"
           ],
-          "description": "Default content kind for the beat's slide. Uses ContentPayload.type names to help engines choose a layout. The legacy shape value is retained for compatibility and requests an image representation; it is not a native ContentPayload type."
+          "description": "Default content kind for the beat's slide: the same values as Slide.type. Helps engines and planners choose a layout when only the beat is known."
         },
-        "layoutHint": {
+        "layout": {
           "type": "string",
-          "description": "Suggested layout id for the beat's opening slide, e.g. 'section-divider', 'title-slide', 'text-left'. Resolves the same way as Slide.layout \u2014 against catalogs.layouts and the default catalog at https://www.pptx.gallery/layouts.",
+          "description": "Suggested layout id for the beat's slide, e.g. 'section-divider', 'title-slide', 'text-left'. Resolves the same way as Slide.layout \u2014 against catalogs.layouts and the default catalog at https://www.pptx.gallery/layouts.",
           "examples": [
             "section-divider",
             "title-slide",
@@ -7560,7 +7179,7 @@ var narrative = {
           "items": {
             "type": "string"
           },
-          "description": "Optional speaker or thinking cues attached to the beat. Surfaced in presenter notes.",
+          "description": "Optional speaker or thinking cues for the beat: questions the slide should answer. A planner or author turns them into the slide's notes; no engine copies them there on its own.",
           "examples": [
             [
               "What pain is the audience feeling right now?",
@@ -7576,7 +7195,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, brand color, and themed icons. 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 and the themed icons are catalog metadata for authoring UIs: engines (opf-render, opf-pptx) render the profile URL, not icons or 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 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.",
   "type": "object",
   "required": [
     "$schema",
@@ -7719,31 +7338,6 @@ var socialPlatform = {
         "#FF0000"
       ]
     },
-    "icon": {
-      "type": "string",
-      "description": "Default icon source. Accepts an HTTPS URL, data URI, relative path, or asset reference. Used as the fallback when a themed (Light/Dark) variant isn't set. Catalog metadata for authoring UIs: engines do not draw icons.",
-      "examples": [
-        "https://www.pptx.gallery/social-platforms/linkedin.svg",
-        "./assets/social-platforms/linkedin.svg",
-        "asset:social-linkedin"
-      ]
-    },
-    "iconLight": {
-      "type": "string",
-      "description": "Light-colored icon variant intended for authoring UIs that draw the icon on dark backgrounds (engines do not draw icons).",
-      "examples": [
-        "https://www.pptx.gallery/social-platforms/linkedin-light.svg",
-        "./assets/social-platforms/linkedin-light.svg"
-      ]
-    },
-    "iconDark": {
-      "type": "string",
-      "description": "Dark-colored icon variant intended for authoring UIs that draw the icon on light backgrounds (engines do not draw icons).",
-      "examples": [
-        "https://www.pptx.gallery/social-platforms/linkedin-dark.svg",
-        "./assets/social-platforms/linkedin-dark.svg"
-      ]
-    },
     "tags": {
       "type": "array",
       "items": {
@@ -8016,6 +7610,18 @@ var colorScheme = {
     "id",
     "name"
   ],
+  "$defs": {
+    "HexColor": {
+      "type": "string",
+      "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
+      "description": "Hex color: '#RGB', '#RRGGBB' or '#RRGGBBAA'. The same definition as HexColor in opf.schema.json.",
+      "examples": [
+        "#fff",
+        "#2874A6",
+        "#0F172AFF"
+      ]
+    }
+  },
   "properties": {
     "$schema": {
       "type": "string",
@@ -8082,7 +7688,7 @@ var colorScheme = {
       ]
     },
     "accent1": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 1 color (hex). Mirrors the OOXML accent1 slot.",
       "examples": [
         "#2874A6",
@@ -8091,7 +7697,7 @@ var colorScheme = {
       ]
     },
     "accent2": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 2 color (hex). Mirrors the OOXML accent2 slot.",
       "examples": [
         "#1B4F72",
@@ -8100,7 +7706,7 @@ var colorScheme = {
       ]
     },
     "accent3": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 3 color (hex). Mirrors the OOXML accent3 slot.",
       "examples": [
         "#5499C7",
@@ -8109,7 +7715,7 @@ var colorScheme = {
       ]
     },
     "accent4": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 4 color (hex). Mirrors the OOXML accent4 slot.",
       "examples": [
         "#7BDBB2",
@@ -8118,7 +7724,7 @@ var colorScheme = {
       ]
     },
     "accent5": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 5 color (hex). Mirrors the OOXML accent5 slot.",
       "examples": [
         "#3AC67A",
@@ -8127,7 +7733,7 @@ var colorScheme = {
       ]
     },
     "accent6": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 6 color (hex). Mirrors the OOXML accent6 slot.",
       "examples": [
         "#24A89E",
@@ -8136,42 +7742,42 @@ var colorScheme = {
       ]
     },
     "dark1": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Dark 1 color (hex). Typically the deepest neutral; OOXML dark1.",
       "examples": [
         "#000000"
       ]
     },
     "dark2": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Dark 2 color (hex). Secondary dark; OOXML dark2.",
       "examples": [
         "#011842"
       ]
     },
     "light1": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Light 1 color (hex). Typically the slide canvas; OOXML lt1.",
       "examples": [
         "#FFFFFF"
       ]
     },
     "light2": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Light 2 color (hex). Secondary light surface; OOXML lt2.",
       "examples": [
         "#F0F0F0"
       ]
     },
     "hyperlink": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Hyperlink color (hex). OOXML hlink.",
       "examples": [
         "#0563C1"
       ]
     },
     "followedHyperlink": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Followed-hyperlink color (hex). OOXML folHlink.",
       "examples": [
         "#954F72"
@@ -8232,7 +7838,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) take precedence over the resolved 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.",
   "type": "object",
   "required": [
     "$schema",
@@ -8312,41 +7918,11 @@ var fontScheme = {
       ]
     },
     "code": {
-      "type": "object",
-      "description": "Optional monospaced font for code blocks and inline code. It has the same shape as the OPF FontScheme 'code' role, so a record and an inline design.fontScheme override are interchangeable. OOXML has no code slot, so exporters write this family on code runs. When neither design.fontScheme nor the resolved record defines 'code', engines fall back to Roboto Mono.",
-      "required": [
-        "family"
-      ],
-      "properties": {
-        "family": {
-          "type": "string",
-          "description": "Monospaced font family name.",
-          "examples": [
-            "Consolas",
-            "Courier New"
-          ]
-        },
-        "weight": {
-          "type": "number",
-          "description": "Numeric font weight (e.g., 400 for regular, 700 for bold)."
-        },
-        "style": {
-          "type": "string",
-          "enum": [
-            "normal",
-            "italic"
-          ],
-          "description": "Font style."
-        },
-        "letterSpacing": {
-          "type": "number",
-          "description": "Letter spacing (tracking) in ems."
-        }
-      },
+      "type": "string",
+      "description": "Optional monospaced font family name for code blocks and for inline code runs (TextRun.code). It has the same shape as the OPF FontScheme 'code' role, so a record and an inline design.fontScheme override are interchangeable. OOXML has no code slot, so exporters write this family on code runs. When neither design.fontScheme nor the resolved record defines 'code', engines fall back to Roboto Mono.",
       "examples": [
-        {
-          "family": "Consolas"
-        }
+        "Consolas",
+        "Courier New"
       ]
     },
     "eastAsian": {
@@ -8413,32 +7989,35 @@ var fontScheme = {
     "app": {
       "type": "string",
       "enum": [
-        "PowerPoint",
-        "Google Slides"
+        "powerpoint",
+        "google-slides"
       ],
-      "description": "Target application this font pairing is intended for."
+      "description": "Target application this font pairing is intended for. Metadata for pickers and catalog filters: no engine changes its output by it."
     },
     "languageFamily": {
       "type": "string",
       "enum": [
         "latin",
         "ea",
-        "cs"
+        "cs",
+        "eastAsian",
+        "complexScript"
       ],
-      "description": "OOXML font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' for East Asian scripts, 'cs' for Complex Scripts. As the design font scheme, an 'ea' or 'cs' scheme also fills that script slot with its own major/minor families when its languages list is empty or names the presentation language."
+      "description": "Font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' (or 'eastAsian', the same value) for East Asian scripts, 'cs' (or 'complexScript', the same value) for Complex Scripts. The long names match the 'eastAsian' and 'complexScript' slot keys; the short names match the OOXML a:ea and a:cs elements; core reads both spellings as one value. As the design font scheme, an 'ea'/'eastAsian' or 'cs'/'complexScript' scheme also fills that script slot with its own major/minor families when its languages list is empty or names the presentation language."
     },
     "languages": {
       "type": "array",
       "items": {
-        "type": "string"
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
       },
-      "description": "Optional list of human-readable language names this scheme is curated for. Useful for picker UIs that group fonts by language coverage.",
+      "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.",
       "examples": [
         [
-          "Chinese (simplified)",
-          "Chinese (traditional)",
-          "Japanese",
-          "Korean"
+          "chinese-simplified",
+          "chinese-traditional",
+          "japanese",
+          "korean"
         ]
       ]
     },
@@ -8515,6 +8094,418 @@ var fontScheme = {
     }
   }
 };
+var finding = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openpresentation.org/schema/opf-finding/v1",
+  "title": "Finding Report",
+  "description": "The report format every OPF tool shares. A finding is one thing a checker found at one place in a presentation: a stable rule id, a severity, a category, a JSON Pointer path, a message, and optionally source positions, the measured numbers behind it and suggested fixes as JSON Patch. `validate` in `@openpresentation/opf`, the Markdown and YAML converters, the editor's Review panel and hosted reviewers such as pptx.dev's AI review all produce this shape, so a host shows and applies findings from any of them the same way. A report lists findings, tells whether any has severity `error` (`valid`) and counts them by severity; `validate` adds `schemaValid`, `checks` and variable fields on top of it. Core's checks are deterministic and run locally; findings from other producers use their own rule-id prefix and say so in `source`.",
+  "type": "object",
+  "required": [
+    "valid",
+    "findings",
+    "counts"
+  ],
+  "properties": {
+    "valid": {
+      "type": "boolean",
+      "description": "True when no finding has severity `error`."
+    },
+    "findings": {
+      "type": "array",
+      "description": "Every finding, in report order.",
+      "items": {
+        "$ref": "#/$defs/Finding"
+      }
+    },
+    "counts": {
+      "type": "object",
+      "description": "How many findings each severity has.",
+      "required": [
+        "error",
+        "warning",
+        "info"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "error": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "warning": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "info": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  },
+  "$defs": {
+    "FindingSeverity": {
+      "type": "string",
+      "enum": [
+        "error",
+        "warning",
+        "info"
+      ],
+      "description": "`error` makes a report invalid. `warning` is a problem the author should fix. `info` is advisory."
+    },
+    "FindingCategory": {
+      "description": "What kind of question the finding answers. Core uses `format` (is it well-formed OPF), `references` (does everything it points at resolve), `policy` (host house rules), `accessibility`, `layout` (will it present as authored) and `content` (is anything left unfinished). Other producers may use their own category names, such as `narrative` or `audience-fit`.",
+      "anyOf": [
+        {
+          "type": "string",
+          "enum": [
+            "format",
+            "references",
+            "policy",
+            "accessibility",
+            "layout",
+            "content"
+          ]
+        },
+        {
+          "type": "string",
+          "minLength": 1
+        }
+      ]
+    },
+    "FindingLocation": {
+      "type": "object",
+      "description": "A range in the checked text: UTF-16 offset and length from the start, and the one-based line and column of the start. Present when the finding was produced from text (JSON, Markdown or YAML).",
+      "required": [
+        "offset",
+        "length",
+        "line",
+        "column"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "offset": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "length": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "column": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "JsonPatchOperation": {
+      "description": "One RFC 6902 JSON Patch operation. Paths are JSON Pointers into the checked presentation.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "op",
+            "path",
+            "value"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "op": {
+              "type": "string",
+              "enum": [
+                "add",
+                "replace",
+                "test"
+              ]
+            },
+            "path": {
+              "type": "string"
+            },
+            "value": {}
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "op",
+            "path"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "op": {
+              "type": "string",
+              "const": "remove"
+            },
+            "path": {
+              "type": "string"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "op",
+            "from",
+            "path"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "op": {
+              "type": "string",
+              "enum": [
+                "move",
+                "copy"
+              ]
+            },
+            "from": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string"
+            }
+          }
+        }
+      ]
+    },
+    "FindingFocus": {
+      "type": "object",
+      "description": "The field an author has to fill in, for a fix that cannot be written as a patch.",
+      "required": [
+        "path",
+        "field"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "JSON Pointer of the field to edit."
+        },
+        "field": {
+          "type": "string",
+          "description": "What the field is, such as `alt`, `title`, `text`, `link`, `language` or `fontSize`."
+        },
+        "value": {
+          "type": [
+            "string",
+            "number",
+            "boolean",
+            "null",
+            "array",
+            "object"
+          ],
+          "description": "The field's current value, when it has one."
+        }
+      }
+    },
+    "FindingFix": {
+      "type": "object",
+      "description": "A suggested repair. Core never applies it: the host shows it and applies it through its own undoable edit path. A `patch` fix carries JSON Patch operations; a `focus` fix only names the field the author has to fill in.",
+      "required": [
+        "title"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What applying the fix does, in a few words."
+        },
+        "id": {
+          "type": "string",
+          "description": "Stable id within one finding, such as `focus-alt` or `use-readable-color`."
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "patch",
+            "focus"
+          ],
+          "default": "patch",
+          "description": "`patch` fixes carry `patch`; `focus` fixes carry `focus`."
+        },
+        "safe": {
+          "type": "boolean",
+          "description": "True when applying the fix cannot change what the content says or how it looks beyond the repair, such as switching a failing colour to the one the theme chose. False fixes need a deliberate choice."
+        },
+        "patch": {
+          "type": "array",
+          "description": "RFC 6902 JSON Patch operations that apply the fix to the checked presentation.",
+          "items": {
+            "$ref": "#/$defs/JsonPatchOperation"
+          }
+        },
+        "focus": {
+          "$ref": "#/$defs/FindingFocus"
+        }
+      }
+    },
+    "FindingSuggestion": {
+      "type": "object",
+      "description": "A value the author could use instead, such as a catalog record that exists. Suggestions name records actually present in the checked context and never replace authored values silently.",
+      "required": [
+        "value",
+        "label",
+        "origin"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "type": [
+            "string",
+            "number",
+            "boolean",
+            "null"
+          ]
+        },
+        "label": {
+          "type": "string"
+        },
+        "origin": {
+          "type": "string",
+          "description": "Where the suggestion comes from: `schema`, `built-in`, `loaded`, `document` or `contract`."
+        },
+        "definition": {
+          "type": "string",
+          "description": "Where the suggested record or constraint is defined."
+        }
+      }
+    },
+    "ValidationIssue": {
+      "type": "object",
+      "description": "The raw schema or semantic issue behind a finding, kept with every union alternative so a host can inspect the exact constraint.",
+      "required": [
+        "path",
+        "message",
+        "keyword",
+        "schemaPath",
+        "params"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "keyword": {
+          "type": "string",
+          "description": "The JSON Schema keyword that failed, or `opf` for a rule the schema cannot express."
+        },
+        "schemaPath": {
+          "type": "string"
+        },
+        "params": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    "Finding": {
+      "type": "object",
+      "description": "One thing a checker found at one place in a presentation.",
+      "required": [
+        "ruleId",
+        "severity",
+        "category",
+        "path",
+        "message"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "ruleId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$",
+          "description": "Stable `<producer>/<rule>` id, such as `opf/text-contrast` for core or `pptx.dev/narrative-gap` for a hosted reviewer. Ids do not change between releases."
+        },
+        "source": {
+          "type": "string",
+          "description": "The producer: `opf` (the default) for core, or the name of another tool such as `pptx.dev/review`."
+        },
+        "severity": {
+          "$ref": "#/$defs/FindingSeverity"
+        },
+        "category": {
+          "$ref": "#/$defs/FindingCategory"
+        },
+        "path": {
+          "type": "string",
+          "description": "JSON Pointer to the value the finding is about, such as `/slides/4/title`. Empty for the whole document, or for a value in a supplied context such as a loaded catalog."
+        },
+        "scope": {
+          "type": "string",
+          "enum": [
+            "document",
+            "context"
+          ],
+          "description": "`document` (the default) when `path` points into the checked presentation, `context` when it points into host-supplied context such as loaded catalog records."
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What is wrong, in a sentence."
+        },
+        "help": {
+          "type": "string",
+          "description": "What to do about it."
+        },
+        "slide": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Zero-based index of the slide the finding belongs to."
+        },
+        "slideId": {
+          "type": "string",
+          "description": "The id of that slide, when it has one."
+        },
+        "location": {
+          "$ref": "#/$defs/FindingLocation"
+        },
+        "definition": {
+          "type": "string",
+          "description": "A link to the rule's documentation or to the schema constraint or catalog record the finding is about."
+        },
+        "lookup": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Arguments for the `opf schema` or `opf catalog` command that shows the definition, as an argument list rather than a shell string."
+        },
+        "suggestions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/FindingSuggestion"
+          }
+        },
+        "measured": {
+          "type": "object",
+          "description": 'The numbers behind the finding, such as `{ "ratio": 2.1, "needed": 4.5 }`.',
+          "additionalProperties": {
+            "type": [
+              "number",
+              "string",
+              "boolean",
+              "null"
+            ]
+          }
+        },
+        "fixes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/FindingFix"
+          }
+        },
+        "validation": {
+          "$ref": "#/$defs/ValidationIssue"
+        }
+      }
+    }
+  }
+};
 var schemas = {
   presentation,
   audience,
@@ -8527,7 +8518,8 @@ var schemas = {
   socialPlatform,
   language,
   colorScheme,
-  fontScheme
+  fontScheme,
+  finding
 };
 var schemaNames = [
   "presentation",
@@ -8541,7 +8533,8 @@ var schemaNames = [
   "socialPlatform",
   "language",
   "colorScheme",
-  "fontScheme"
+  "fontScheme",
+  "finding"
 ];
 var schemaEntries = [
   { name: "presentation", file: "schemas/opf.schema.json", schema: presentation },
@@ -8555,7 +8548,8 @@ var schemaEntries = [
   { name: "socialPlatform", file: "schemas/social-platform.schema.json", schema: socialPlatform },
   { name: "language", file: "schemas/language.schema.json", schema: language },
   { name: "colorScheme", file: "schemas/color-scheme.schema.json", schema: colorScheme },
-  { name: "fontScheme", file: "schemas/font-scheme.schema.json", schema: fontScheme }
+  { name: "fontScheme", file: "schemas/font-scheme.schema.json", schema: fontScheme },
+  { name: "finding", file: "schemas/finding.schema.json", schema: finding }
 ];
 
 export { audience, chartType, colorScheme, fontScheme, language, layout, narrative, presentation, purpose, schemaEntries, schemaNames, schemas, socialPlatform, theme, tone };