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) Slack notify with the same Google Drive View Link (required)
- [ ] 7) Commit and push to **main**; merge the PR if you opened one

YAML document structure

Top level

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)

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 slidestyle.backgroundimage are often relative to repo root (e.g. assets/background_alt.jpg).

How YAML becomes slides

loadversesfromfile → yaml.safeload → validateverses (praisonaippt/schema.py) → createpresentation (praisonaippt/core.py):

1. Title slide — presentationtitle / presentationsubtitle
2. For each section — if section is non-empty → section slide; if section: '' → no section slide
3. For each verse:

- slidetype: image → image slide (resolved path, optional caption, imagefit) - listtype: bullet \| numbered → list slide - else → splitlongtext on text → one verse slide per chunk via addverse_slide (background, reference, body, highlights)

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

1) Identify deck file

• Confirm the target YAML in examples/ (newest examples include 100foldblessing.yaml, freedomfromallyourtroubles.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 autouploadgdrive: 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, autouploadgdrive: 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) Slack notify (required)

Do this every time a deck build finishes — do not wait for the user to ask. Follow ~/.cursor/skills/slack-notification/SKILL.md.

The Slack body must include the Google Drive View Link (or Edit Link for a Google Doc). If upload was skipped, say why and include the local .pptx path.

source ~/.zshrc 2>/dev/null || true
# Fallback if vars missing: source ~/.config/automation/slack.env
~/.cursor/skills/slack-notification/scripts/send-slack.sh \
  --title "PraisonAIPPT: <deck title>" \
  --body "<2–5 lines: slides built, what changed>
View Link: <full https://docs.google.com/... URL>" \
  --emoji ":white_check_mark:"

Confirm in chat: "Slack notification sent". Do not log tokens.

7) Git update

• Stage only intended files (typically YAML; include .pptx if the repo tracks regenerated decks).
• Commit with a clear one-line message.
• Always push to main (git push origin main). Do not leave work only on a feature branch.
• If you created a pull request, merge it into main in the same turn (then push main if the merge was local).

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. slidestyles instead of slidestyle) log warnings—use exact key names from template.yaml.