ppt-yaml-deck-workflow

name	ppt-yaml-deck-workflow
description	Edit PraisonAIPPT YAML decks in examples, keep style consistent, regenerate matching PPTX, and verify output. Use when users request slide/verse/section/highlight updates for deck YAML files.
disable-model-invocation	true

PPT YAML Deck Workflow

Scope

Use this workflow for deck edits in examples/*.yaml where the output is a .pptx generated by praisonaippt (python-pptx via praisonaippt/core.py). This is not the Codex artifact-tool JS slide builder.

• Source of truth: examples/<deck>.yaml
• Generated artefact: examples/<deck>.pptx (same basename; regenerate after every YAML edit)
• Full field reference: copy from examples/template.yaml

Standard checklist

Copy and track:

Progress:
- [ ] 1) Identify target YAML deck and exact requested changes
- [ ] 2) Read current YAML structure before editing
- [ ] 3) Apply minimal YAML edits only
- [ ] 4) Regenerate matching PPTX with CLI
- [ ] 5) Confirm build success; paste slide outline + Google Drive View Link to user
- [ ] 6) Commit/push YAML (+ PPTX if tracked) when requested

YAML document structure

Top level

Key	Purpose
presentation_title	Opening title slide
presentation_subtitle	Optional subtitle on title slide
slide_style	Global look (background, colours, font, alignment) — or use template: sermon-dark
template	Built-in style theme name (praisonaippt --list-templates); replaces inline slide_style
slide_size	Optional: widescreen / 16:9 / standard / 4:3 / 16:10, or { width, height } in inches
auto_upload_gdrive	Default true on example decks; uploads PPTX after build when credentials exist (also honour ~/.praisonaippt defaults.auto_upload_gdrive)
sections	List of section blocks (required)

Default style (use a theme template)

Prefer a built-in theme instead of copying slide_style into every deck:

template: sermon-dark
auto_upload_gdrive: true

Other themes: default, sermon-gold, light-minimal — see docs/templates.md or praisonaippt --list-templates.

Inline override example:

template: sermon-dark
slide_style:
  highlight_color: '#FFD700'

Legacy inline block (equivalent to template: sermon-dark):

auto_upload_gdrive: true
slide_style:
  background_image: assets/background_alt.jpg
  text_color: white
  alignment: left
  reference_position: top
  font_name: Palatino

Omit slide_size unless the user needs standard / 4:3; default build is widescreen (16:9).

Section block

sections:
  - section: Section title here    # use '' to skip the section divider slide
    section_subtitle: Optional     # second line on section slide
    verses:
      - reference: ...
        text: ...

Verse block (common keys)

Key	Effect
reference + text	Standard verse slide(s)
highlights	Strings, or objects: text, color, bold, italic, underline, annotation (1–9)
leading_title	Large headline above reference (sermon “message” slides); only on first slide when text is split
split_max_length	Max chars per slide before splitting (default 200); use 400–500 for long NKJV passages
font_size, alignment	Per-verse overrides (else from slide_style)
reference_font_size	Larger reference line (title-style slides)
list_type: bullet | numbered	List slide; text lines separated by \n
slide_type: image + image_path	Image slide (image_fit: contain / cover / fill; optional reference + text as caption)
text_below_reference	Extra passage block below verse body (same slide)

Image slides — add a verse entry:

- slide_type: image
  image_path: assets/diagrams/my_chart.png
  image_fit: contain
  reference: Slide label
  text: Optional caption under the image

Paths resolve relative to the YAML file, then cwd, then repo root. Extract images from an existing PPTX with praisonaippt convert-json deck.pptx (saves under assets/extracted_images/<stem>/ when slides are image-only).

Generate new slide art with the gpt-image skill (.cursor/skills/gpt-image/): uv run .cursor/skills/gpt-image/scripts/generate.py --size 1536x864 --output assets/generated/...png, then reference that path in YAML. Validate setup: uv run .cursor/skills/gpt-image/scripts/validate_skill.py.

Paths in slide_style.background_image are often relative to repo root (e.g. assets/background_alt.jpg).

How YAML becomes slides

load_verses_from_file → yaml.safe_load → validate_verses (praisonaippt/schema.py) → create_presentation (praisonaippt/core.py):

1. Title slide — presentation_title / presentation_subtitle
2. For each section — if section is non-empty → section slide; if section: '' → no section slide
3. For each verse:
   • slide_type: image → image slide (resolved path, optional caption, image_fit)
   • list_type: bullet | numbered → list slide
   • else → split_long_text on text → one verse slide per chunk via add_verse_slide (background, reference, body, highlights)

Optional CLI extras (only when user asks): --convert-pdf, --upload-gdrive (also triggered by auto_upload_gdrive: true).

1) Identify deck file

• Confirm the target YAML in examples/ (newest examples include 100_fold_blessing.yaml, freedom_from_all_your_troubles.yaml, elshadai.yaml).
• If user gives only topic/title, create a new YAML in examples/ (copy template.yaml) with the requested name.

2) Read before edit

• Read the YAML section where changes are needed before modifying.
• For reorder requests, verify both source and destination blocks first.
• Match indentation and patterns used in neighbouring verses in that deck.

3) Apply minimal edits

• New decks and restyle requests: apply the default slide_style above so design matches the latest example decks.
• Keep existing slide_style on small content-only edits unless the user asked to restyle.
• Preserve verse text unless the user asked to rewrite it.
• For highlights, prefer keyword-only highlights unless user asks for colour/annotation objects (e.g. color: green for law, #FFD700 for promise/grace, #9900FF for Hebrew names).
• When rebuilding from an existing .pptx, run praisonaippt convert-json file.pptx to recover highlights; if none are extracted, add them manually in YAML—create_presentation does not invent highlights.
• Confirm presentation_title matches what the user requested before regenerating.
• For section title slides, add a new section block only where needed.
• Do not edit praisonaippt/core.py for content changes—change YAML only.

4) Regenerate PPTX (required after YAML edit)

From repo root:

python3 -m praisonaippt.cli -i examples/<deck>.yaml -o examples/<deck>.pptx

Optional: export plain Markdown from the same YAML:

python3 -m praisonaippt.cli convert-markdown examples/<deck>.yaml
# → examples/<deck>.md (blockquotes, **highlights**, section headings)
# Google Doc upload uses examples/<deck>.html with yellow/green highlight colours like PPT
# Uploads as native Google Doc when auto_upload_gdrive: true or --upload-gdrive

Equivalent: praisonaippt convert-markdown examples/<deck>.yaml --markdown-output notes.md --upload-gdrive

Equivalent: praisonaippt -i examples/<deck>.yaml -o examples/<deck>.pptx

After a successful build, the CLI automatically prints a numbered slide outline (same as list-slides below). Use that output when reporting order to the user—do not run ad-hoc python3 -c snippets.

To list slides on an existing PPTX without rebuilding:

python3 -m praisonaippt.cli list-slides examples/<deck>.pptx

Equivalent: praisonaippt list-slides examples/<deck>.pptx

Skip the post-build outline with --no-list-slides on the generate command.

Example:

python3 -m praisonaippt.cli -i examples/100_fold_blessing.yaml -o examples/100_fold_blessing.pptx

5) Verify result and Google Drive URL

• Ensure CLI reports: Presentation created successfully, then the slide outline (slides: N and 01: … lines).
• When confirming order in chat, paste or summarise that CLI outline (from build output or list-slides).
• Default: set auto_upload_gdrive: true in the deck YAML (and rely on ~/.praisonaippt credentials). After every successful build, copy the CLI View Link: URL and give it to the user in your reply (full https://docs.google.com/... URL).
• If upload is skipped, say why (missing credentials, auto_upload_gdrive: false, or upload error) and still confirm the local .pptx path.
• If YAML parse or schema errors occur, fix quoting/block-scalar/indentation and rerun immediately.

6) Git update

• Stage only intended files (typically YAML; include .pptx if the repo tracks regenerated decks).
• Commit with a clear one-line message.
• Push the current branch only when the user requested it.

Common YAML pitfalls

• Plain scalars containing : may require quotes (e.g. 'Romans 2:13 (NKJV)').
• Keep list indentation consistent under sections and verses.
• Use block scalars (>- or |-) for multi-line verse text.
• Unknown top-level keys (e.g. slide_styles instead of slide_style) log warnings—use exact key names from template.yaml.