pptx-cli 1.2.5__tar.gz → 1.3.0__tar.gz

pptx_cli-1.3.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run pyright src/pptx_cli/commands/schema.py tests/test_schema.py)"
+    ]
+  }
+}

{pptx_cli-1.2.5 → pptx_cli-1.3.0}/.github/skills/pptx/SKILL.md

@@ -154,6 +154,10 @@ pptx validate --manifest ./.pptx --deck ./out/deck.pptx --strict --format json
 - `chart` — chart data
 - `markdown-to-text` — markdown converted to formatted text
 
+Speaker notes are supported separately from placeholder content types. Use a
+slide-level `notes` field in deck specs, or `pptx slide create --notes` / `--notes-file`
+for single-slide generation.
+
 ## Error handling
 
 All commands return a structured JSON envelope with `ok`, `errors`, and `warnings` fields. Key exit codes:

{pptx_cli-1.2.5 → pptx_cli-1.3.0}/.github/skills/pptx-deck-builder/SKILL.md

@@ -184,6 +184,11 @@ slides:
         - Bullet point one
         - Bullet point two
       source: "Source: Data attribution"
+    notes: |
+      # Speaker notes
+
+      - Open with the takeaway before reading the slide
+      - Keep timing to under 90 seconds
 
   - layout: picture-layout-id
     content:
@@ -202,6 +207,7 @@ slides:
 - `@notes.md` via `--set key=@notes.md` or `{ kind: "markdown-text", value:
   "..." }` → markdown parsed with headings, lists, inline emphasis, and light
   presentation-aware spacing
+- Slide-level speaker notes → `notes: |` in the deck spec, or `pptx slide create --notes/--notes-file` for single-slide generation
 - `{ kind: "image", path: "path/to/file.png" }` → image insertion
 - `{ kind: "table", columns: [...], rows: [[...], ...] }` → table
 - `{ kind: "chart", chart_type: "column_clustered", categories: [...], series: [{name: "...", values: [...]}] }` → chart
@@ -399,7 +405,7 @@ pptx theme show --manifest ./manifest-dir --format json
 pptx assets list --manifest ./manifest-dir --format json
 
 # Single slide (quick test)
-pptx slide create --manifest ./manifest-dir --layout <id> --set title="Hello" --set content_1=@notes.md --out slide.pptx
+pptx slide create --manifest ./manifest-dir --layout <id> --set title="Hello" --notes-file ./speaker-notes.md --out slide.pptx
 
 # Full deck
 pptx deck build --manifest ./manifest-dir --spec deck.yaml --out deck.pptx --format json

{pptx_cli-1.2.5 → pptx_cli-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pptx-cli
-Version: 1.2.5
+Version: 1.3.0
 Summary: Template-bound PowerPoint generation for enterprise decks
 Author: Thomas Rohde
 License: MIT License
@@ -155,6 +155,7 @@ pptx slide create \
   --layout title-only \
   --set title="Enterprise AI Operating Model" \
   --set subtitle="March 2026" \
+  --notes-file ./speaker-notes.md \
   --out ./out/operating-model-slide.pptx
 ```
 
@@ -209,6 +210,11 @@ slides:
     content:
       title: Enterprise AI Operating Model
       subtitle: March 2026
+    notes: |
+      # Opening talk track
+
+      - Lead with why preserving the template matters
+      - Call out that validation stays available for CI
   - layout: 1-breaker-with-pattern
     content:
       title: Why this change
@@ -281,6 +287,11 @@ corp-template/
 - chart
 - markdown-text
 
+Speaker notes are also supported in v1 as optional slide-level metadata via
+`slides[].notes` in deck specs or `pptx slide create --notes/--notes-file`.
+They are not placeholder content types and do not change layout placeholder
+contracts.
+
 `markdown-text` is parsed with `markdown-it-py` and currently maps CommonMark blocks into
 PowerPoint paragraphs. Headings become plain paragraphs, bullet lists use native PowerPoint
 bullet levels, ordered lists render as numbered paragraph text, and basic inline emphasis such
@@ -288,6 +299,10 @@ as bold/italic/code spans is preserved where PowerPoint run formatting can expre
 blocks also receive light presentation-aware spacing so headings, paragraphs, and lists do not
 collapse into a dense wall of text.
 
+The same markdown-to-text parsing pipeline is used for speaker notes, so headings,
+bullets, ordered lists, and basic inline emphasis remain available in presenter
+notes without introducing a separate formatting model.
+
 ## Structured content objects
 
 `pptx slide create --set picture=@diagram.png` automatically normalizes the file into an

{pptx_cli-1.2.5 → pptx_cli-1.3.0}/PRD.md

@@ -248,6 +248,7 @@ pptx slide create \
   --set title="Enterprise AI Operating Model" \
   --set left_body=@left.md \
   --set right_body=@right.md \
+  --notes-file speaker-notes.md \
   --out slide.pptx
 ```
 
@@ -264,6 +265,7 @@ Composition rules:
 - only declared placeholders can be filled
 - content types must match placeholder types
 - v1 supported placeholder content types are text, images, tables, charts, and markdown-to-text mappings
+- speaker notes are optional per-slide metadata, not placeholder content types, and may use the same markdown-to-text formatting pipeline
 - v1 tables and charts preserve approved placeholder geometry and accept structured data population, but do not guarantee full preservation of advanced workbook internals or highly custom styling behaviors
 - static brand elements remain untouched unless explicitly marked overridable
 - theme and master dependencies must be preserved
@@ -378,6 +380,11 @@ The v1 supported placeholder content types shall include:
 - chart
 - markdown-to-text
 
+The system shall also support optional per-slide speaker notes supplied either
+through the structured deck spec or dedicated direct-command inputs. These notes
+are slide metadata rather than placeholders and reuse the markdown-to-text
+formatting pipeline for rich presenter text.
+
 ### FR-9: Validate output
 
 The system shall validate output decks against the manifest and return machine-friendly errors.
@@ -669,6 +676,9 @@ slides:
   - layout: section-divider
     content:
       title: Why this change
+    notes: |
+      - Pause before the transition
+      - Re-anchor the audience on governance and brand fidelity
   - layout: executive-two-column
     content:
       title: Core idea
@@ -1132,6 +1142,7 @@ The following product decisions are now fixed for v1:
 12. Preview metadata uses a single canonical preview path field per layout.
 13. The CLI adopts an agent-first machine contract with a structured response envelope, stable error codes, exit-code mapping, and a built-in `guide` command.
 14. Mutating commands support `--dry-run` and structured change summaries.
+15. V1 supports optional per-slide speaker notes using text/markdown formatting, but notes are not part of the placeholder contract and are never required by default.
 
 ## 26. Recommendation
 

{pptx_cli-1.2.5 → pptx_cli-1.3.0}/README.md

@@ -108,6 +108,7 @@ pptx slide create \
   --layout title-only \
   --set title="Enterprise AI Operating Model" \
   --set subtitle="March 2026" \
+  --notes-file ./speaker-notes.md \
   --out ./out/operating-model-slide.pptx
 ```
 
@@ -162,6 +163,11 @@ slides:
     content:
       title: Enterprise AI Operating Model
       subtitle: March 2026
+    notes: |
+      # Opening talk track
+
+      - Lead with why preserving the template matters
+      - Call out that validation stays available for CI
   - layout: 1-breaker-with-pattern
     content:
       title: Why this change
@@ -234,6 +240,11 @@ corp-template/
 - chart
 - markdown-text
 
+Speaker notes are also supported in v1 as optional slide-level metadata via
+`slides[].notes` in deck specs or `pptx slide create --notes/--notes-file`.
+They are not placeholder content types and do not change layout placeholder
+contracts.
+
 `markdown-text` is parsed with `markdown-it-py` and currently maps CommonMark blocks into
 PowerPoint paragraphs. Headings become plain paragraphs, bullet lists use native PowerPoint
 bullet levels, ordered lists render as numbered paragraph text, and basic inline emphasis such
@@ -241,6 +252,10 @@ as bold/italic/code spans is preserved where PowerPoint run formatting can expre
 blocks also receive light presentation-aware spacing so headings, paragraphs, and lists do not
 collapse into a dense wall of text.
 
+The same markdown-to-text parsing pipeline is used for speaker notes, so headings,
+bullets, ordered lists, and basic inline emphasis remain available in presenter
+notes without introducing a separate formatting model.
+
 ## Structured content objects
 
 `pptx slide create --set picture=@diagram.png` automatically normalizes the file into an

{pptx_cli-1.2.5 → pptx_cli-1.3.0}/src/pptx_cli/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "1.2.5"
+__version__ = "1.3.0"

{pptx_cli-1.2.5 → pptx_cli-1.3.0}/src/pptx_cli/cli.py

@@ -20,6 +20,7 @@ from pptx_cli.commands.inspect import (
     show_theme,
 )
 from pptx_cli.commands.manifest_ops import manifest_diff, manifest_schema
+from pptx_cli.commands.schema import build_schema_document, copy_to_clipboard
 from pptx_cli.commands.validate import validate_command
 from pptx_cli.commands.wrapper import wrapper_generate
 from pptx_cli.core.composition import CompositionError
@@ -30,8 +31,8 @@ from pptx_cli.models.envelope import CliMessage, Envelope, Metrics
 app = typer.Typer(
     help=(
         "Template-bound PowerPoint generation for enterprise decks. Supports text, "
-        "images, tables, charts, and markdown-text content in template-approved "
-        "placeholders."
+        "images, tables, charts, markdown-text content in template-approved "
+        "placeholders, and optional per-slide speaker notes."
     ),
     no_args_is_help=True,
 )
@@ -41,7 +42,10 @@ theme_app = typer.Typer(help="Inspect extracted theme metadata.")
 assets_app = typer.Typer(help="Inspect extracted asset references.")
 slide_app = typer.Typer(help="Create slides from approved layouts.")
 deck_app = typer.Typer(
-    help="Build full decks from structured specs, including markdown-text content."
+    help=(
+        "Build full decks from structured specs, including markdown-text content "
+        "and optional per-slide speaker notes."
+    )
 )
 manifest_app = typer.Typer(help="Work with manifest packages and schemas.")
 wrapper_app = typer.Typer(help="Generate thin template-specific wrapper CLIs.")
@@ -235,6 +239,27 @@ def guide(format: FormatOption = None) -> None:
     execute("guide.show", format, lambda: build_guide_document().model_dump(mode="json"))
 
 
+@app.command("schema")
+def schema_command(
+    template: Annotated[
+        Path | None,
+        typer.Option("--template", help="Path to a manifest package directory."),
+    ] = None,
+    no_copy: Annotated[
+        bool,
+        typer.Option("--no-copy", help="Skip copying output to the clipboard."),
+    ] = False,
+) -> None:
+    """Print the deck-spec YAML reference (for pasting into LLM prompts)."""
+    text = build_schema_document(template)
+    typer.echo(text)
+    if not no_copy:
+        if copy_to_clipboard(text):
+            typer.echo("(copied to clipboard)", err=True)
+        else:
+            typer.echo("(clipboard copy failed – install xclip or pipe manually)", err=True)
+
+
 @app.command("init")
 def init_command(
     template: Annotated[Path, typer.Argument(help="Path to the source .pptx template")],
@@ -338,6 +363,20 @@ def slide_create_command(
             ),
         ),
     ] = None,
+    notes: Annotated[
+        str | None,
+        typer.Option(
+            "--notes",
+            help="Speaker notes text for the slide. Markdown-looking multiline text is supported.",
+        ),
+    ] = None,
+    notes_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--notes-file",
+            help="Path to a UTF-8 text or markdown file to use as speaker notes.",
+        ),
+    ] = None,
     dry_run: DryRunOption = False,
     overwrite: OverwriteOption = False,
     format: FormatOption = None,
@@ -346,6 +385,7 @@ def slide_create_command(
 
     Use --set key=@notes.md or a multiline markdown-looking value to populate
     markdown-text placeholders with headings, lists, and inline emphasis.
+    Use --notes or --notes-file for slide-level speaker notes.
     """
 
     execute(
@@ -356,6 +396,8 @@ def slide_create_command(
             layout,
             list(set_values or []),
             out,
+            notes=notes,
+            notes_file=notes_file,
             dry_run=dry_run,
             overwrite=overwrite,
         ),
@@ -383,7 +425,8 @@ def deck_build_command(
     """Build a deck from a structured spec.
 
     Deck specs can provide markdown-text content explicitly or rely on multiline
-    markdown-looking strings for headings, lists, and inline emphasis.
+    markdown-looking strings for headings, lists, and inline emphasis. Each slide
+    may also provide an optional `notes` field for speaker notes.
     """
 
     execute(

{pptx_cli-1.2.5 → pptx_cli-1.3.0}/src/pptx_cli/commands/compose.py

@@ -4,6 +4,7 @@ from pathlib import Path
 from typing import Any
 
 from pptx_cli.core.composition import (
+    CompositionError,
     build_presentation,
     create_single_slide_spec,
     parse_set_arguments,
@@ -19,13 +20,17 @@ def slide_create(
     set_values: list[str],
     output_path: Path,
     *,
+    notes: str | None,
+    notes_file: Path | None,
     dry_run: bool,
     overwrite: bool,
 ) -> dict[str, Any]:
     manifest = load_effective_manifest(manifest_dir)
     content = parse_set_arguments(set_values)
-    spec = create_single_slide_spec(layout_id, content)
-    planned_changes = [plan_output_change(output_path, overwrite=overwrite)]
+    resolved_notes = _resolve_notes_input(notes, notes_file)
+    spec = create_single_slide_spec(layout_id, content, notes=resolved_notes)
+    notes_changes = _plan_notes_changes(spec)
+    planned_changes = [plan_output_change(output_path, overwrite=overwrite), *notes_changes]
     if not dry_run:
         prs = build_presentation(manifest_dir, manifest, spec)
         save_presentation(prs, output_path, overwrite=overwrite)
@@ -36,7 +41,7 @@ def slide_create(
         "out": str(output_path),
         "overwrite": overwrite,
         "changes": planned_changes,
-        "summary": {"slides": 1, "artifacts": 1},
+        "summary": {"slides": 1, "artifacts": 1, "notes_slides": len(notes_changes)},
     }
 
 
@@ -50,7 +55,8 @@ def deck_build(
 ) -> dict[str, Any]:
     manifest = load_effective_manifest(manifest_dir)
     spec = load_deck_spec(spec_path)
-    planned_changes = [plan_output_change(output_path, overwrite=overwrite)]
+    notes_changes = _plan_notes_changes(spec)
+    planned_changes = [plan_output_change(output_path, overwrite=overwrite), *notes_changes]
     if not dry_run:
         prs = build_presentation(manifest_dir, manifest, spec)
         save_presentation(prs, output_path, overwrite=overwrite)
@@ -61,6 +67,42 @@ def deck_build(
         "out": str(output_path),
         "overwrite": overwrite,
         "changes": planned_changes,
-        "summary": {"slides": len(spec.slides), "artifacts": 1},
+        "summary": {
+            "slides": len(spec.slides),
+            "artifacts": 1,
+            "notes_slides": len(notes_changes),
+        },
         "metadata": spec.metadata,
     }
+
+
+def _resolve_notes_input(notes: str | None, notes_file: Path | None) -> str | None:
+    if notes is not None and notes_file is not None:
+        raise CompositionError(
+            "ERR_VALIDATION_INPUT",
+            "Use either --notes or --notes-file, not both.",
+        )
+    if notes_file is None:
+        return notes
+    if not notes_file.exists():
+        raise CompositionError(
+            "ERR_IO_NOT_FOUND",
+            f"Speaker notes file not found: {notes_file}",
+        )
+    return notes_file.read_text(encoding="utf-8")
+
+
+def _plan_notes_changes(spec: Any) -> list[dict[str, Any]]:
+    changes: list[dict[str, Any]] = []
+    for slide_index, slide in enumerate(spec.slides, start=1):
+        if slide.notes is None:
+            continue
+        changes.append(
+            {
+                "target": f"slide[{slide_index}].notes",
+                "operation": "create",
+                "artifact_type": "speaker-notes",
+                "text_length": len(slide.notes),
+            }
+        )
+    return changes

{pptx_cli-1.2.5 → pptx_cli-1.3.0}/src/pptx_cli/commands/guide.py

@@ -17,6 +17,16 @@ def build_guide_document() -> GuideDocument:
                 mutates=False,
                 examples=["pptx guide --format json"],
             ),
+            GuideCommand(
+                id="schema.show",
+                summary="Print the deck-spec YAML reference for pasting into LLM prompts",
+                mutates=False,
+                examples=[
+                    "pptx schema",
+                    "pptx schema --template ./corp-template",
+                    "pptx schema --no-copy",
+                ],
+            ),
             GuideCommand(
                 id="template.init",
                 summary="Initialize a manifest package from a source template",
@@ -64,12 +74,15 @@ def build_guide_document() -> GuideDocument:
             ),
             GuideCommand(
                 id="slide.create",
-                summary="Create a slide from an approved layout",
+                summary="Create a slide from an approved layout with optional speaker notes",
                 mutates=True,
                 input_schema=DeckSpec.model_json_schema(),
                 examples=[
                     "pptx slide create --manifest ./corp-template --layout title-only "
                     "--set title=Hello --out ./out/slide.pptx --dry-run",
+                    "pptx slide create --manifest ./corp-template --layout title-only "
+                    "--set title=Hello --notes-file ./speaker-notes.md "
+                    "--out ./out/slide-with-notes.pptx",
                     "pptx slide create --manifest ./corp-template "
                     "--layout 3-front-page-title-and-picture "
                     "--set title=Workflow --set picture=@out/workflow.png "
@@ -78,7 +91,7 @@ def build_guide_document() -> GuideDocument:
             ),
             GuideCommand(
                 id="deck.build",
-                summary="Build a deck from a structured spec",
+                summary="Build a deck from a structured spec with optional per-slide speaker notes",
                 mutates=True,
                 input_schema=DeckSpec.model_json_schema(),
                 examples=[
@@ -151,6 +164,9 @@ def build_guide_document() -> GuideDocument:
             "placeholder_keys": (
                 "logical placeholder keys such as title, subtitle, content_1, or picture"
             ),
+            "slide_notes": (
+                "optional per-slide speaker notes via SlideSpec.notes or slide create --notes"
+            ),
             "manifest_path": "path to a manifest package directory containing manifest.yaml",
         },
         concurrency={

pptx_cli-1.3.0/src/pptx_cli/commands/schema.py

@@ -0,0 +1,224 @@
+"""Build a human-readable YAML reference for deck specs.
+
+Designed to be pasted into LLM prompts so the model knows how to
+author valid ``pptx deck build`` input.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from pptx_cli.core.manifest_store import load_effective_manifest
+from pptx_cli.models.manifest import LayoutContract, ManifestDocument
+
+# ---------------------------------------------------------------------------
+# Clipboard helper
+# ---------------------------------------------------------------------------
+
+def copy_to_clipboard(text: str) -> bool:
+    """Copy *text* to the system clipboard.  Returns True on success."""
+    if sys.platform == "win32":
+        cmd = ["clip"]
+    elif sys.platform == "darwin":
+        cmd = ["pbcopy"]
+    else:
+        cmd = ["xclip", "-selection", "clipboard"]
+    try:
+        subprocess.run(
+            cmd,
+            input=text.encode("utf-8"),
+            check=True,
+            timeout=5,
+        )
+    except (FileNotFoundError, subprocess.SubprocessError):
+        return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Generic (template-free) schema
+# ---------------------------------------------------------------------------
+
+_GENERIC_SCHEMA = """\
+<slide-schema>
+Use this schema to draft presentation content.  Layout assignment and
+template binding happen later, so focus on the slides themselves.
+
+metadata:
+  title: "<deck title>"
+  author: "<author name>"
+
+slides:
+  - title: "Slide heading"
+    body: |
+      - Bullet one
+      - Bullet two
+    notes: |
+      Talk track for this slide.
+
+  - title: "Data slide"
+    body: |
+      Key observations from the quarter.
+    table:
+      kind: table
+      columns: [Col A, Col B]
+      rows:
+        - [val1, val2]
+        - [val3, val4]
+    notes: Additional context.
+
+  - title: "Trend slide"
+    body: |
+      Revenue grew 50% year-over-year.
+    chart:
+      kind: chart
+      chart_type: column_clustered
+      categories: [Q1, Q2, Q3]
+      series:
+        - name: Revenue
+          values: [12, 15, 18]
+
+  - title: "Visual slide"
+    image:
+      kind: image
+      path: path/to/image.png
+      image_fit: fit
+</slide-schema>
+
+<content-rules>
+- Each slide MUST have a "title".
+- Use "body" for the main text area.  Markdown is auto-detected
+  (headings, bullets, **bold**, *italic*).
+- Use "table", "chart", or "image" keys for structured content.
+  chart_type accepts: column_clustered, bar_clustered, line, pie.
+  image_fit accepts: "fit" (default) or "cover".
+- "notes" is optional speaker-notes text (markdown ok).
+- Do NOT include a "layout" key – layout is assigned later when
+  binding to a corporate template.
+</content-rules>
+
+<style-guide>
+Follow these principles to produce decision-grade slides.
+
+Structure
+- Lead with the answer.  Do not build up to the conclusion.
+- Pyramid Principle: governing thought -> supporting arguments -> evidence.
+- Arguments must be MECE (mutually exclusive, collectively exhaustive).
+- One slide = one message.  Two insights -> two slides.
+
+Titles
+- Use action titles, not topic labels.  The title states the takeaway.
+  Bad:  "Market overview"
+  Good: "Nordic retail banking margins will remain under pressure through 2027"
+- Title storyline reads on its own – skim only titles and understand the
+  full argument.
+- Formulas:
+    Insight:        "[What happened] because [driver]"
+    Comparison:     "[A] outperforms [B] on [criterion]"
+    Implication:    "[Fact] puts [objective] at risk"
+    Recommendation: "[Org] should [action] to achieve [outcome]"
+
+Executive summary slide
+- Situation: what context everyone agrees on.
+- Complication: what changed or created urgency.
+- Answer: the recommended response.
+- Support: 2-3 reasons the answer is correct.
+
+Deck sequence (typical)
+1. Title page
+2. Executive summary (situation -> complication -> resolution)
+3. Context / problem framing (only enough to orient)
+4. Analysis body (current state -> root causes -> options -> recommendation)
+5. Recommendation (explicit, decision-ready)
+6. Implementation / roadmap
+7. Risks and mitigations
+8. Appendix (source data, benchmarks, methodology)
+
+Body content
+- Every claim backed by evidence.  The body proves the headline.
+- Quantify.  Replace vague adjectives with measured claims.
+- Keep text tight: verbs, short bullets, no filler.
+- Move backup detail to appendix – main story stays focused.
+</style-guide>
+"""
+
+
+# ---------------------------------------------------------------------------
+# Template-enriched schema
+# ---------------------------------------------------------------------------
+
+def _placeholder_summary(ph: Any) -> dict[str, Any]:
+    """Compact summary of a placeholder contract."""
+    entry: dict[str, Any] = {
+        "types": ph.supported_content_types,
+    }
+    if ph.required:
+        entry["required"] = True
+    if ph.guidance_text:
+        entry["guidance"] = ph.guidance_text
+    cap = ph.estimated_text_capacity
+    if cap is not None:
+        entry["max_lines"] = cap.max_lines
+    return entry
+
+
+def _layout_section(layout: LayoutContract) -> dict[str, Any]:
+    """Build a dict describing one layout for the reference doc."""
+    section: dict[str, Any] = {}
+    if layout.description:
+        section["description"] = layout.description
+    if layout.aliases:
+        section["aliases"] = layout.aliases
+    placeholders: dict[str, Any] = {}
+    for ph in layout.placeholders:
+        placeholders[ph.logical_name] = _placeholder_summary(ph)
+    section["placeholders"] = placeholders
+    return section
+
+
+def _example_slide(layout: LayoutContract) -> dict[str, Any]:
+    """Generate an example slide entry using real placeholder names."""
+    content: dict[str, str] = {}
+    for ph in layout.placeholders:
+        if "image" in ph.supported_content_types and "text" not in ph.supported_content_types:
+            content[ph.logical_name] = "{ kind: image, path: path/to/image.png }"
+        else:
+            content[ph.logical_name] = f"<{ph.logical_name} text>"
+    slide: dict[str, Any] = {"layout": layout.id, "content": content}
+    return slide
+
+
+def _build_template_section(manifest: ManifestDocument) -> str:
+    """Return the template-specific portion of the reference doc."""
+    layouts_ref: dict[str, Any] = {}
+    examples: list[dict[str, Any]] = []
+
+    for layout in manifest.layouts:
+        layouts_ref[layout.id] = _layout_section(layout)
+        examples.append(_example_slide(layout))
+
+    doc: dict[str, Any] = {
+        "template": manifest.template.name,
+        "layouts": layouts_ref,
+        "example_slides": examples,
+    }
+    return yaml.safe_dump(doc, sort_keys=False, allow_unicode=True, width=120)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def build_schema_document(template_dir: Path | None = None) -> str:
+    """Return the full reference document as a string."""
+    parts = [_GENERIC_SCHEMA]
+    if template_dir is not None:
+        manifest = load_effective_manifest(template_dir)
+        parts.append("\n# ── Template-specific layouts ──────────────────────────────────\n")
+        parts.append(_build_template_section(manifest))
+    return "\n".join(parts)

{pptx_cli-1.2.5 → pptx_cli-1.3.0}/src/pptx_cli/core/composition.py

@@ -118,8 +118,13 @@ def _load_inline_or_file_value(raw_value: str) -> Any:
     return raw_value
 
 
-def create_single_slide_spec(layout: str, content: dict[str, Any]) -> DeckSpec:
-    return DeckSpec(slides=[SlideSpec(layout=layout, content=content)])
+def create_single_slide_spec(
+    layout: str,
+    content: dict[str, Any],
+    *,
+    notes: str | None = None,
+) -> DeckSpec:
+    return DeckSpec(slides=[SlideSpec(layout=layout, content=content, notes=notes)])
 
 
 def build_presentation(manifest_dir: Path, manifest: ManifestDocument, spec: DeckSpec) -> Any:
@@ -137,6 +142,8 @@ def build_presentation(manifest_dir: Path, manifest: ManifestDocument, spec: Dec
             slide_layout = prs.slide_layouts[layout_contract.source_layout_index]
             slide = prs.slides.add_slide(slide_layout)
             _populate_slide(slide, layout_contract, slide_spec.content)
+            if slide_spec.notes is not None:
+                _apply_slide_notes(slide, slide_spec.notes)
         except CompositionError as exc:
             raise CompositionError(
                 exc.code,
@@ -302,6 +309,37 @@ def _apply_text(shape: Any, text: str, *, markdown: bool) -> None:
     paragraphs = parse_markdown_paragraphs(text) if markdown else parse_plain_text_paragraphs(text)
     list_level_offset = _first_markdown_list_level(shape) if markdown else 0
 
+    _write_text_frame_paragraphs(
+        text_frame,
+        paragraphs,
+        markdown=markdown,
+        list_level_offset=list_level_offset,
+    )
+
+
+def _apply_slide_notes(slide: Any, text: str) -> None:
+    notes_slide = slide.notes_slide
+    text_frame = notes_slide.notes_text_frame
+    text_frame.clear()
+    markdown = looks_like_markdown(text)
+    paragraphs = parse_markdown_paragraphs(text) if markdown else parse_plain_text_paragraphs(text)
+
+    _write_text_frame_paragraphs(
+        text_frame,
+        paragraphs,
+        markdown=markdown,
+        list_level_offset=0,
+    )
+
+
+def _write_text_frame_paragraphs(
+    text_frame: Any,
+    paragraphs: list[ParsedParagraph],
+    *,
+    markdown: bool,
+    list_level_offset: int,
+) -> None:
+
     previous: ParsedParagraph | None = None
     for index, parsed in enumerate(paragraphs):
         paragraph = text_frame.paragraphs[0] if index == 0 else text_frame.add_paragraph()

{pptx_cli-1.2.5 → pptx_cli-1.3.0}/src/pptx_cli/models/manifest.py

@@ -162,6 +162,7 @@ class InitReport(BaseModel):
 class SlideSpec(BaseModel):
     layout: str
     content: dict[str, Any] = Field(default_factory=dict)
+    notes: str | None = None
 
 
 class DeckSpec(BaseModel):

{pptx_cli-1.2.5 → pptx_cli-1.3.0}/tests/test_cli.py

@@ -59,6 +59,11 @@ def test_guide_returns_structured_envelope_with_catalog() -> None:
     command_ids = {command["id"] for command in payload["result"]["commands"]}
     assert "layouts.list" in command_ids
     assert "deck.build" in command_ids
+    slide_create_command = next(
+        command for command in payload["result"]["commands"] if command["id"] == "slide.create"
+    )
+    slide_spec_properties = slide_create_command["input_schema"]["$defs"]["SlideSpec"]["properties"]
+    assert "notes" in slide_spec_properties
     assert payload["result"]["exit_codes"]["validation_error"] == 10
     assert "ERR_IO_NOT_FOUND" in payload["result"]["error_codes"]
     assert payload["result"]["content_objects"]["image"]["example"]["kind"] == "image"
@@ -257,6 +262,64 @@ def test_slide_create_and_validate_round_trip(
     assert title_shape.text_frame.vertical_anchor == template_title_shape.text_frame.vertical_anchor
 
 
+def test_slide_create_supports_speaker_notes_from_markdown_file(
+    template_path: Path,
+    manifest_dir: Path,
+    tmp_path: Path,
+) -> None:
+    out_file = tmp_path / "slide-with-notes.pptx"
+    notes_file = tmp_path / "speaker-notes.md"
+    notes_file.write_text(
+        "# Talking points\n\n- Lead with customer outcomes\n- Close on delivery confidence\n",
+        encoding="utf-8",
+    )
+    _init_manifest(template_path, manifest_dir)
+
+    payload = _invoke_json(
+        [
+            "slide",
+            "create",
+            "--manifest",
+            str(manifest_dir),
+            "--layout",
+            "title-only",
+            "--set",
+            "title=Quarterly Update",
+            "--notes-file",
+            str(notes_file),
+            "--out",
+            str(out_file),
+        ]
+    )
+
+    assert payload["result"]["summary"]["notes_slides"] == 1
+    assert any(change["target"] == "slide[1].notes" for change in payload["result"]["changes"])
+
+    generated = Presentation(str(out_file))
+    notes_frame = generated.slides[0].notes_slide.notes_text_frame
+    assert notes_frame is not None
+    paragraphs = notes_frame.paragraphs
+    assert [paragraph.text for paragraph in paragraphs] == [
+        "Talking points",
+        "Lead with customer outcomes",
+        "Close on delivery confidence",
+    ]
+    assert paragraphs[0].runs[0].font.bold is True
+    assert paragraphs[1].level == 0
+    assert paragraphs[2].level == 0
+
+    validation = _invoke_json(
+        [
+            "validate",
+            "--manifest",
+            str(manifest_dir),
+            "--deck",
+            str(out_file),
+        ]
+    )
+    assert validation["result"]["ok"] is True
+
+
 def test_slide_create_picture_placeholder_uses_fit_by_default(
     template_path: Path,
     manifest_dir: Path,
@@ -409,6 +472,119 @@ def test_deck_build_supports_structured_image_table_and_chart_content(
     assert chart_shape.has_chart is True
 
 
+def test_deck_build_supports_speaker_notes_and_reports_them_in_dry_run(
+    template_path: Path,
+    manifest_dir: Path,
+    tmp_path: Path,
+) -> None:
+    deck_spec = tmp_path / "speaker-notes-deck.yaml"
+    out_file = tmp_path / "speaker-notes-deck.pptx"
+    _init_manifest(template_path, manifest_dir)
+
+    deck_spec.write_text(
+        yaml.safe_dump(
+            {
+                "slides": [
+                    {
+                        "layout": "title-only",
+                        "content": {"title": "Opening"},
+                    },
+                    {
+                        "layout": "1-title-and-content",
+                        "content": {
+                            "title": "Operating model",
+                            "content_1": "Preserve the template contract.",
+                        },
+                        "notes": "Lead with the governance angle.\n\n- Mention change control",
+                    },
+                ]
+            },
+            sort_keys=False,
+        ),
+        encoding="utf-8",
+    )
+
+    dry_run_payload = _invoke_json(
+        [
+            "deck",
+            "build",
+            "--manifest",
+            str(manifest_dir),
+            "--spec",
+            str(deck_spec),
+            "--out",
+            str(out_file),
+            "--dry-run",
+        ]
+    )
+
+    assert dry_run_payload["result"]["summary"]["notes_slides"] == 1
+    assert any(
+        change["target"] == "slide[2].notes" and change["artifact_type"] == "speaker-notes"
+        for change in dry_run_payload["result"]["changes"]
+    )
+    assert out_file.exists() is False
+
+    build_payload = _invoke_json(
+        [
+            "deck",
+            "build",
+            "--manifest",
+            str(manifest_dir),
+            "--spec",
+            str(deck_spec),
+            "--out",
+            str(out_file),
+        ]
+    )
+
+    assert build_payload["result"]["summary"]["notes_slides"] == 1
+    generated = Presentation(str(out_file))
+    notes_frame = generated.slides[1].notes_slide.notes_text_frame
+    assert notes_frame is not None
+    assert [paragraph.text for paragraph in notes_frame.paragraphs] == [
+        "Lead with the governance angle.",
+        "Mention change control",
+    ]
+
+
+def test_slide_create_rejects_conflicting_speaker_notes_inputs(
+    template_path: Path,
+    manifest_dir: Path,
+    tmp_path: Path,
+) -> None:
+    out_file = tmp_path / "slide-conflicting-notes.pptx"
+    notes_file = tmp_path / "speaker-notes.txt"
+    notes_file.write_text("Use one notes input only.", encoding="utf-8")
+    _init_manifest(template_path, manifest_dir)
+
+    result = runner.invoke(
+        app,
+        [
+            "slide",
+            "create",
+            "--manifest",
+            str(manifest_dir),
+            "--layout",
+            "title-only",
+            "--set",
+            "title=Quarterly Update",
+            "--notes",
+            "Inline notes",
+            "--notes-file",
+            str(notes_file),
+            "--out",
+            str(out_file),
+            "--format",
+            "json",
+        ],
+    )
+
+    assert result.exit_code == 10
+    payload = json.loads(result.stdout)
+    assert payload["errors"][0]["code"] == "ERR_VALIDATION_INPUT"
+
+
 def test_deck_build_auto_detects_markdown_bullets_and_preserves_text_opt_out(
     template_path: Path,
     manifest_dir: Path,

pptx_cli-1.3.0/tests/test_schema.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from typer.testing import CliRunner
+
+from pptx_cli.cli import app
+from pptx_cli.commands.schema import build_schema_document
+
+runner = CliRunner()
+
+
+def test_generic_schema_contains_deck_structure() -> None:
+    text = build_schema_document()
+    assert "<slide-schema>" in text
+    assert "metadata:" in text
+    assert "slides:" in text
+    assert "title:" in text
+    assert "body:" in text
+    assert "notes:" in text
+
+
+def test_generic_schema_documents_content_types() -> None:
+    text = build_schema_document()
+    assert "kind: image" in text
+    assert "kind: table" in text
+    assert "kind: chart" in text
+
+
+def test_generic_schema_uses_xml_sections() -> None:
+    text = build_schema_document()
+    assert "<slide-schema>" in text
+    assert "</slide-schema>" in text
+    assert "<content-rules>" in text
+    assert "</content-rules>" in text
+    assert "<style-guide>" in text
+    assert "</style-guide>" in text
+
+
+def test_generic_schema_omits_layout() -> None:
+    text = build_schema_document()
+    assert "Do NOT include" in text
+    assert "layout is assigned later" in text
+
+
+def test_schema_command_outputs_text(tmp_path: str) -> None:
+    result = runner.invoke(app, ["schema", "--no-copy"])
+    assert result.exit_code == 0
+    assert "metadata:" in result.stdout
+    assert "slides:" in result.stdout
+
+
+def test_schema_command_copies_to_clipboard() -> None:
+    with patch("pptx_cli.cli.copy_to_clipboard", return_value=True) as mock_copy:
+        result = runner.invoke(app, ["schema"])
+    assert result.exit_code == 0
+    mock_copy.assert_called_once()
+    assert "copied to clipboard" in result.stderr
+
+
+def test_schema_command_no_copy_skips_clipboard() -> None:
+    with patch("pptx_cli.cli.copy_to_clipboard") as mock_copy:
+        result = runner.invoke(app, ["schema", "--no-copy"])
+    assert result.exit_code == 0
+    mock_copy.assert_not_called()
+
+
+def test_schema_with_template(template_path: str, manifest_dir: str) -> None:
+    # First init a manifest so we can point --template at it
+    init_result = runner.invoke(
+        app,
+        ["init", str(template_path), "--out", str(manifest_dir), "--format", "json"],
+    )
+    assert init_result.exit_code == 0
+
+    result = runner.invoke(app, ["schema", "--template", str(manifest_dir), "--no-copy"])
+    assert result.exit_code == 0
+    assert "template:" in result.stdout
+    assert "layouts:" in result.stdout
+    assert "placeholders:" in result.stdout