Deck Illustration Generation — Detail

Reference for Step 3 (deck illustrations) and Step 5 (apply to deck) in SKILL.md. The illustration-rules and title-overlay-rules steering rules are auto-loaded — apply them, don't restate them.

Setup

Before generating, ensure:

1. API key — add your Gemini key to {vault}/secrets.json (preferred):

   { "gemini": { "api_key": "your-key-here" } }

   Or set GEMINI_API_KEY as a fallback. Get a key from https://aistudio.google.com/app/apikey.

2. Model availability — verify the model in the outline header is accessible with your key. The script reads it from the **Model:** \model-name`` line in the Illustration Style Anchor section.

3. Python 3 — stdlib only (urllib, json, base64). No pip install needed.

Slide Selection Modes

python3 skills/illustrations/scripts/generate-illustrations.py presentation-outline.md remaining

remaining skips slides whose images already exist; all regenerates every slide; specific slides can be passed as 2 5 9 or a range 2-10.

Model Comparison (Phase 2 model selection)

python3 skills/illustrations/scripts/generate-illustrations.py presentation-outline.md --compare 2

Generates the same prompt across multiple Gemini image models for visual comparison. Output lands in illustrations/model-comparison/.

Edit / Fix / Versioned Generation

--edit and --fix auto-append the safety suffixes (DO NOT add any new elements, Let background continue naturally). The explicit preservation list (Keep the X. Keep the Y.) must always be added manually — the script cannot know what to preserve.

Slide Format Vocabulary

The outline's Illustration Style Anchor block defines format codes per slide. The apply-illustrations-to-deck.py script maps each code to a layout + positioning:

File Layout

{talk-dir}/illustrations/
├── slide-01.jpg               ← one file per illustrated slide
├── slide-02.png
├── slide-05-v2.jpg            ← versioned iterations (--fix / --edit / -v)
├── builds/                    ← progressive reveal build steps (see builds.md)
│   ├── slide-05-build-00.jpg
│   ├── slide-05-build-01.jpg
│   └── slide-05-build-02.jpg
└── model-comparison/          ← --compare output

Title Safe Zone

The Safe zone: line in each FULL slide block tells the script to append a TITLE SAFE ZONE directive to the prompt before generation. Five zones are supported: upper_third, middle_third, lower_third, left_half, right_half. See skills/illustrations/references/title-placement.md for the outline schema and rules/title-overlay-rules.md for the full policy (auto-loaded).

Apply to Deck

python3 skills/illustrations/scripts/apply-illustrations-to-deck.py \
  deck.pptx illustrations/ presentation-outline.md \
  --out deck-with-titles.pptx \
  --scrim-color 100903 --scrim-alpha 47553   # omit for plain 45% black

The script:

1. For each slide whose outline block has a Safe zone: field, swaps the background picture with the matching illustration from illustrations/.
2. Adds a zone-sized scrim rectangle between the picture and the title text.
3. Repositions title text boxes into the declared safe zone.
4. For each slide with Format: IMG+TXT, applies the IMG+TXT layout (image ~60% on the left, title placeholder + body on the right).
5. Inserts build sequences (see skills/illustrations/references/builds.md) for any slide with a - Builds: block.

If no scrim color is supplied, run python3 skills/illustrations/scripts/suggest-scrim-color.py illustrations/ first to sample a deck-tuned color. For warm or cool styled decks, the sampled color reads as "deeper shadow in the same style" instead of a flat black film.