Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(refs): wire web image search into the workflow + split image refs

hugohe386bbe020090a
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index ff56e4eb..3ff4fbbf 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -204,30 +204,43 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
---
-### Step 5: Image_Generator Phase (Conditional)
+### Step 5: Image Acquisition Phase (Conditional)
🚧 **GATE**: Step 4 complete; Design Specification & Content Outline generated and user confirmed.
-> **Trigger**: Image approach includes "AI generation". Otherwise skip to Step 6.
+> **Trigger**: At least one row in the resource list has `Acquire Via: ai` and/or `Acquire Via: web`. If every row is `user` or `placeholder`, skip to Step 6.
-Read `references/image-generator.md`
+**Always load the common framework**:
-1. Extract all images with status `Pending` from the design spec
-2. Generate prompt document → `<project_path>/images/image_prompts.md`
-3. Generate images (CLI tool recommended):
- ```bash
- python3 ${SKILL_DIR}/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images
- ```
+```
+Read references/image-base.md
+```
+
+Then **lazy-load the path-specific reference** for each row that actually needs it:
+
+| Acquire Via | Load reference (only if any such row exists) | Run |
+|---|---|---|
+| `ai` | `references/image-generator.md` | `python3 ${SKILL_DIR}/scripts/image_gen.py ...` |
+| `web` | `references/image-searcher.md` | `python3 ${SKILL_DIR}/scripts/image_search.py ...` |
+| `user` / `placeholder` | (skip) | (skip) |
+
+A deck with only `ai` rows never loads `image-searcher.md`; a deck with only `web` rows never loads `image-generator.md`. A mixed deck loads both, processes each row through its own path, and writes both `image_prompts.md` and `image_sources.json`.
+
+Workflow:
+
+1. Extract all rows with `Status: Pending` and `Acquire Via ∈ {ai, web}` from the design spec
+2. Generate prompts (ai rows) and/or run search (web rows) per [image-base.md](references/image-base.md) §2 dispatch table
+3. Verify every row reaches a terminal status: `Generated` (ai success), `Sourced` (web success), or `Needs-Manual`
-**✅ Checkpoint — Confirm image generation attempted for every row, proceed to Step 6**:
+**✅ Checkpoint — Confirm acquisition attempted for every row, proceed to Step 6**:
```markdown
-## ✅ Image_Generator Phase Complete
-- [x] Prompt document created
-- [x] Each image: status is either `Generated` (file present in images/) or `Needs-Manual` (reported to user with filename + reason)
-- [x] No row remains `Pending`
+## ✅ Image Acquisition Phase Complete
+- [x] image_prompts.md created (when any ai rows processed)
+- [x] image_sources.json created (when any web rows processed)
+- [x] Each row: status is `Generated` / `Sourced` / `Needs-Manual` (no `Pending` remaining)
```
-> On generation failure, do NOT halt — follow the Failure Handling rule in `references/image-generator.md` §4.3: retry once, then mark the row `Needs-Manual`, report to user, and continue to Step 6.
+> On acquisition failure, do NOT halt — follow the Failure Handling rule in [image-base.md](references/image-base.md) §5: retry once, then mark the row `Needs-Manual`, report to user, and continue to Step 6.
---
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 7df01c87..4fde93d0 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -238,13 +238,29 @@ Handle images by their status in the Design Spec's Image Resource List. Status e
|--------|--------|----------|
| **Existing** | User-provided | Reference images directly from `../images/` directory |
| **Generated** | Generated by Image_Generator | Reference images directly from `../images/` directory |
-| **Needs-Manual** | Generation failed and file is absent | Use dashed border placeholder unless the expected file exists |
+| **Sourced** | Web-acquired by Image_Searcher | Reference from `../images/`. **Read [`image_sources.json`](image-searcher.md) to decide attribution** — see §6.1 below. |
+| **Needs-Manual** | Acquisition failed and file is absent | Use dashed border placeholder unless the expected file exists |
| **Placeholder** | Not yet prepared | Use dashed border placeholder |
**Reference syntax**: see [`svg-image-embedding.md`](svg-image-embedding.md).
**Placeholder**: Dashed border `<rect stroke-dasharray="8,4" .../>` + description text
+### 6.1 Inline Attribution for Sourced Images (web path)
+
+Whenever the slide uses an image with `Status: Sourced`, look up the corresponding entry in `project/images/image_sources.json` and act on `license_tier`:
+
+| `license_tier` | Action on this slide |
+|---|---|
+| `no-attribution` | Embed the `<image>` element only. **No credit element needed.** |
+| `attribution-required` | Embed the `<image>` element **plus** a small inline `<text>` credit element per the visual spec in [image-searcher.md §7](./image-searcher.md). |
+
+The credit text is **not** rendered by post-processing or export — it must be present in the SVG you produce. The shape of the credit element (size, position, color, multi-image source line, hero gradient overlay) is specified in [image-searcher.md §7](./image-searcher.md). Do not invent a different style.
+
+Use `attribution_text` from the manifest entry as the **starting point**, then compress for the small-text constraint (drop URL, drop filename, keep "via Provider / License"). For CC0/PD images that landed in the `attribution-required` tier only because of upstream metadata quirks (rare), credits are still safe to render.
+
+**The manifest is the single source of truth for credits.** Do not duplicate license info into speaker notes or any other artifact.
+
---
## 7. Font Usage
diff --git a/skills/ppt-master/references/image-base.md b/skills/ppt-master/references/image-base.md
new file mode 100644
index 00000000..a52336e4
--- /dev/null
+++ b/skills/ppt-master/references/image-base.md
@@ -0,0 +1,129 @@
+> See [`image-generator.md`](./image-generator.md) and [`image-searcher.md`](./image-searcher.md) for path-specific behavior.
+
+# Image Acquisition Common Reference
+
+Shared baseline for both acquisition paths. Path-specific behavior lives in the path's own reference.
+
+---
+
+## 1. Trigger Condition
+
+Active when at least one resource list row has `Acquire Via: ai` or `Acquire Via: web`. Rows with `user` / `placeholder` are skipped.
+
+| Mode | Trigger |
+|---|---|
+| In-pipeline | `generate-ppt` workflow, image rows present |
+| Standalone | Direct request against an existing project |
+
+---
+
+## 2. Image Resource List Format
+
+Defined in `design_spec.md §VIII`. Status enum: see [`svg-image-embedding.md`](svg-image-embedding.md).
+
+| Filename | Dimensions | Purpose | Type | Acquire Via | Status | Reference |
+|---|---|---|---|---|---|---|
+| cover.png | 1280x720 | Cover background | Background | `ai` | Pending | Modern tech abstract, deep blue gradient #0A2540 |
+| team.jpg | 800x600 | Team photo | Photography | `web` | Pending | Diverse engineering team in modern office |
+
+**Required per non-skipped row**: `Acquire Via`, `Status`, `Reference`.
+
+---
+
+## 3. Path Dispatch
+
+For each row with `Status: Pending`:
+
+| Acquire Via | Load reference | Run | Success status |
+|---|---|---|---|
+| `ai` | [`image-generator.md`](./image-generator.md) | `image_gen.py` | `Generated` |
+| `web` | [`image-searcher.md`](./image-searcher.md) | `image_search.py` | `Sourced` |
+| `user` | — | — | (already `Existing`) |
+| `placeholder` | — | — | (already `Placeholder`) |
+
+> Lazy load: an all-`web` deck never reads `image-generator.md`, and vice versa.
+
+---
+
+## 4. Analysis Phase
+
+Before processing any row:
+
+1. `read_file <project_path>/design_spec.md` — extract color scheme, canvas format, target audience
+2. Group resource list rows by `Acquire Via`
+3. Confirm `project/images/` exists
+
+---
+
+## 5. Verification Phase
+
+After all rows reach terminal status:
+
+- Every non-skipped row has a file at `project/images/<filename>`, or is marked `Needs-Manual`
+- No `Pending` rows remain
+- `image_prompts.md` exists when ≥1 ai row processed
+- `image_sources.json` exists when ≥1 web row processed; every entry has `license_tier ∈ {no-attribution, attribution-required}`
+
+---
+
+## 6. Failure Handling
+
+**Hard rule**: acquisition failures MUST NOT halt the pipeline.
+
+1. Try once
+2. On recoverable failure (network, no candidates, license rejection, rate limit), retry once with broadened parameters
+3. On second failure, set `Status: Needs-Manual`, log the reason in conversation, continue
+4. After the phase completes, summarize all `Needs-Manual` rows for the user
+
+Path-specific retry policies (provider chain, backend chain) live in the path's own reference.
+
+---
+
+## 7. Credits — Single Source of Truth
+
+License / attribution data lives **only** in `project/images/image_sources.json`.
+
+**Forbidden — credits anywhere else**:
+
+- `notes/*.md` (TTS would speak them in the audio export)
+- `total.md` (gets split, then overwritten)
+- SVG `<title>` / `<desc>` (stripped by `svg_to_pptx.py`)
+- A separate "Image Credits" appendix slide (lost on single-page sharing)
+
+Executor reads the manifest per slide and renders inline credits when needed — see [`executor-base.md`](./executor-base.md) §6.1 and [`image-searcher.md`](./image-searcher.md) §7.
+
+---
+
+## 8. Handoff with Strategist
+
+The `Reference` field is **intent**, not a query. Strategist writes free-form intent; the receiving role translates.
+
+| ✅ Intent | ❌ Pre-processed |
+|---|---|
+| `"Diverse engineering team in modern office, natural light"` | `"team office light"` |
+| `"Abstract digital waves, deep navy gradient #0A2540"` | `"use openverse, search 'waves'"` |
+
+---
+
+## 9. Handoff with Executor
+
+Executor consumes the resource list plus:
+
+| Artifact | Path | Purpose |
+|---|---|---|
+| Image files | `project/images/*.{jpg,png,webp}` | `<image>` references |
+| Manifest | `project/images/image_sources.json` | `license_tier` per Sourced image |
+
+Executor does NOT invoke `image_gen.py` / `image_search.py`.
+
+---
+
+## 10. Task Completion Checkpoint
+
+```markdown
+## ✅ Image Acquisition Phase Complete
+- [x] {N} rows processed (`ai`: {a} / `web`: {b})
+- [x] {a} `Generated`, {b} `Sourced`, {c} `Needs-Manual`
+- [x] image_prompts.md / image_sources.json written
+- [ ] **Next**: Auto-proceed to Executor phase
+```
diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.md
index 2eaf8c8b..0cb632c5 100644
--- a/skills/ppt-master/references/image-generator.md
+++ b/skills/ppt-master/references/image-generator.md
@@ -1,51 +1,18 @@
-# Image_Generator Reference Manual
-
-> This file is the streamlined reference for the Image_Generator role. Common standards (SVG technical constraints, canvas formats, post-processing pipeline, etc.) are in [shared-standards.md](./shared-standards.md).
-
-## Core Mission
-
-Receive the "Image Resource List" from the Design Specification & Content Outline output by the Strategist, create optimized prompts for each image pending generation, generate images via AI tools, and save them to the project's `images/` directory.
-
-**Trigger condition**: When AI image generation is needed (standalone use or invoked within pipeline)
-
-| Mode | Trigger | Description |
-|------|---------|-------------|
-| **Standalone** | Directly describe image needs | Generate single or multiple AI images |
-| **In-pipeline** | `generate-ppt` with AI image generation selected | Batch-generate image assets for a project |
-
-> Next step in pipeline: Executor generates SVGs
-
----
-
-## 1. Input & Output
+> See [`image-base.md`](./image-base.md) for the common framework. For the web sourcing path, see [`image-searcher.md`](./image-searcher.md).
-### Input
-
-- **Design Specification & Content Outline** (from Strategist): project theme, target audience, design style, color scheme, canvas format
-- **Image Resource List** (key input):
-
- | Filename | Dimensions | Purpose | Type | Status | Generation Description |
- |----------|-----------|---------|------|--------|----------------------|
- | cover_bg.png | 1920x1080 | Cover background | Background | Pending | Modern tech abstract background, deep blue gradient |
-
- Status values are defined in [`svg-image-embedding.md`](svg-image-embedding.md). Image_Generator consumes only `Pending` rows and changes them to `Generated` or `Needs-Manual`.
+# Image_Generator Reference Manual
-### Output
+Role definition for the **AI image generation path**: convert each `Acquire Via: ai` row into an optimized prompt, generate the image, and save it to `project/images/`.
-| Deliverable | Path / Description | Requirements |
-|------------|-------------------|--------------|
-| Prompt document | `project/images/image_prompts.md` | **Must** be saved using file write tool — cannot just be output in conversation |
-| Optimized prompts | Individual prompt per image | Directly usable with AI image generation tools; doubles as alt text |
-| Image files | `project/images/` directory | Named per the resource list filenames |
-| Updated list | Status changes | `Pending` -> `Generated` (success) or `Pending` -> `Needs-Manual` (generation attempted and failed) |
+**Trigger**: resource list rows with `Acquire Via: ai`. The role is loaded only when at least one such row exists.
---
-## 2. Unified Prompt Structure
+## 1. Unified Prompt Structure
-### 2.1 Standard Output Format
+### 1.1 Standard Output Format
-Every image must be output in the following format:
+Every image must be emitted into `image_prompts.md` in the following block format:
```markdown
### Image N: {filename}
@@ -55,7 +22,7 @@ Every image must be output in the following format:
| Purpose | {which page / what function} |
| Type | {Background / Illustration / Photography / Diagram / Decorative} |
| Dimensions | {width}x{height} ({aspect ratio}) |
-| Original description | {description provided by user in the list} |
+| Original description | {Reference field from the resource list} |
**Prompt**:
{subject description}, {style directive}, {color directive}, {composition directive}, {quality directive}
@@ -67,7 +34,7 @@ Every image must be output in the following format:
> {Description for accessibility and image captions}
```
-### 2.2 Prompt Components
+### 1.2 Prompt Components
| Component | Description | Example |
|-----------|-------------|---------|
@@ -78,7 +45,7 @@ Every image must be output in the following format:
| Quality directive | Resolution quality | `high quality`, `4K resolution`, `sharp details` |
| Negative prompt | Exclude elements | `text, watermark, blurry, low quality` |
-### 2.3 Style Keywords Quick Reference
+### 1.3 Style Keywords Quick Reference
| Design Style | Recommended Image Style | Core Keywords |
|-------------|------------------------|---------------|
@@ -92,7 +59,7 @@ Every image must be output in the following format:
| Finance / Banking | Conservative, trustworthy | `conservative`, `trustworthy`, `blue-gray palette`, `structured`, `precise` |
| Creative / Design | Artistic, experimental | `artistic`, `experimental`, `asymmetric`, `textured`, `hand-crafted feel` |
-### 2.4 Color Integration Method
+### 1.4 Color Integration Method
Extract colors from design spec, convert to prompt directives:
@@ -104,7 +71,7 @@ Accent: #D4AF37 (Gold) → "gold accent (#D4AF37)"
Full directive: "color palette: deep navy blue (#1E3A5F), light gray (#F8F9FA), gold accent (#D4AF37)"
```
-### 2.5 Canvas Format & Aspect Ratio
+### 1.5 Canvas Format & Aspect Ratio
| Canvas Format | Background Aspect Ratio | Recommended Resolution |
|--------------|------------------------|----------------------|
@@ -116,11 +83,11 @@ Full directive: "color palette: deep navy blue (#1E3A5F), light gray (#F8F9FA),
> Supported aspect ratios: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` (Gemini also supports `1:4`, `1:8`, `4:1`, `8:1`)
-### 2.6 Multi-Image Coherence Strategy
+### 1.6 Multi-Image Coherence Strategy
When generating multiple images for a single deck, visual coherence is critical. Use a **Deck Style Anchor** — a shared prefix of 15-25 words prepended to every image prompt.
-**Construction**: Combine style keywords (Section 2.3) + color directive (Section 2.4) + quality directive into one reusable prefix.
+**Construction**: Combine style keywords (Section 1.3) + color directive (Section 1.4) + quality directive into one reusable prefix.
**Example**:
```
@@ -134,21 +101,21 @@ Image 3 prompt: [Deck Style Anchor], growth chart with upward trending line...
**Exception**: Background images may replace style keywords with `background`, `backdrop`, `negative space for text overlay` while keeping the same color directive. This ensures color consistency without compromising background functionality.
-**Rule**: Define the Deck Style Anchor once in the prompt document header (Section 5), then reference it in every individual prompt.
+**Rule**: Define the Deck Style Anchor once in the prompt document header (Section 4), then reference it in every individual prompt.
---
-## 3. Image Type Classification & Handling
+## 2. Image Type Classification & Handling
### Type Determination Flow
-1. Full-page / large-area backdrop → **Background** (3.1)
-2. Real scenes / people / products → **Photography** (3.2)
-3. Flat / illustration / cartoon style → **Illustration** (3.3)
-4. Process / architecture / relationships → **Diagram** (3.4)
-5. Partial decoration / texture → **Decorative Pattern** (3.5)
+1. Full-page / large-area backdrop → **Background** (2.1)
+2. Real scenes / people / products → **Photography** (2.2)
+3. Flat / illustration / cartoon style → **Illustration** (2.3)
+4. Process / architecture / relationships → **Diagram** (2.4)
+5. Partial decoration / texture → **Decorative Pattern** (2.5)
-### 3.1 Background
+### 2.1 Background
**Identifying characteristics**: Full-page background for covers or chapter pages; must support text overlay
@@ -163,7 +130,7 @@ Image 3 prompt: [Deck Style Anchor], growth chart with upward trending line...
**Negative prompt**: `text, letters, watermark, faces, busy patterns, high contrast details`
-### 3.2 Photography
+### 2.2 Photography
**Identifying characteristics**: Real scenes, people, products, architecture — photographic quality
@@ -178,7 +145,7 @@ Image 3 prompt: [Deck Style Anchor], growth chart with upward trending line...
**Negative prompt**: `watermark, text overlay, artificial, CGI, illustration, cartoon, distorted faces`
-### 3.3 Illustration
+### 2.3 Illustration
**Identifying characteristics**: Flat design, vector style, cartoon, concept diagrams
@@ -193,7 +160,7 @@ Image 3 prompt: [Deck Style Anchor], growth chart with upward trending line...
**Negative prompt**: `realistic, photography, 3D render, complex textures, watermark`
-### 3.4 Diagram
+### 2.4 Diagram
**Identifying characteristics**: Flowcharts, architecture diagrams, concept relationship maps, data visualizations
@@ -208,7 +175,7 @@ Image 3 prompt: [Deck Style Anchor], growth chart with upward trending line...
**Negative prompt**: `cluttered, messy, overlapping elements, dark background, realistic, photography`
-### 3.5 Decorative Pattern
+### 2.5 Decorative Pattern
**Identifying characteristics**: Partial decoration, textures, borders, divider elements
@@ -225,29 +192,22 @@ Image 3 prompt: [Deck Style Anchor], growth chart with upward trending line...
---
-## 4. Image Generation Workflow
-
-### 4.1 Analysis Phase
+## 3. Generation Workflow
-1. Read the design spec; understand overall project style
-2. Extract color scheme, canvas format, target audience
-3. Analyze each image in the resource list individually
-4. Determine each image's type (refer to Section 3)
+### 3.1 Prompt Generation Phase
-### 4.2 Prompt Generation Phase
-
-For each image with "Pending" status:
+For each image with `Acquire Via: ai` and `Status: Pending`:
1. **Determine type** → Background / Photography / Illustration / Diagram / Decorative
2. **Understand purpose** → Which page? What function?
-3. **Analyze original description** → Information from the user's "Generation description"
-4. **Apply type-specific key points** → Reference the corresponding type's table
-5. **Generate optimized prompt** → Use the 2.1 standard output format
+3. **Analyze the Reference field** → User's intent description
+4. **Apply type-specific key points** → Reference §2's table for that type
+5. **Generate optimized prompt** → Use the §1.1 standard output format
6. **Save prompt document** → **Must** write to `project/images/image_prompts.md`
-### 4.3 Image Generation Phase
+### 3.2 Image Generation Phase
-> Prerequisite: Section 4.2 must be complete; `images/image_prompts.md` must exist
+> Prerequisite: §3.1 must be complete; `images/image_prompts.md` must exist.
#### Path Selection (Deterministic)
@@ -315,16 +275,13 @@ Triggered only when the user explicitly asks the skill to use the host's built-i
- Outputs **must** land at `project/images/<filename-from-resource-list>` with dimensions matching the Image Resource List
- Executor downstream is path-agnostic — no spec change required between Path A and Path B
-#### Failure Handling (Applies to Both Paths)
-
-If generation fails for a given image:
+#### AI-specific Failure Handling (extends image-base.md §5)
-1. **Retry once.** If the retry also fails, stop attempting that image — do not loop further.
-2. **Do NOT halt the pipeline.** Report the failures to the user: list the affected filenames and the error reason, and ask the user to generate those images manually and place them at `project/images/<filename>` with the exact filename from the resource list.
-3. **Mark the affected rows** in the Image Resource List as `Needs-Manual` (not `Generated`).
-4. **Proceed to the Executor phase.** Executor consumes whatever is in `project/images/` at its runtime; missing files are handled downstream (placeholder or user prompt), not by blocking here.
+If a single backend fails twice in a row:
-If the user chooses to generate manually on a platform that watermarks outputs (e.g. Gemini web), the repository includes `scripts/gemini_watermark_remover.py` as a utility.
+1. Per the shared rule, mark the row `Needs-Manual` after one retry — do **not** silently switch backends
+2. Report the failure to the user: filename, prompt used, error message
+3. Suggest the user manually generate the image elsewhere and place it at `project/images/<filename>`. If the alternate platform watermarks outputs (e.g. Gemini web), the repository includes `scripts/gemini_watermark_remover.py`
#### Guardrails (Both Paths)
@@ -332,16 +289,9 @@ If the user chooses to generate manually on a platform that watermarks outputs (
- Agent must NOT mark an image as `Needs-Manual` without a real generation attempt having failed
- Status transitions are evidence-driven: `Pending` -> `Generated` (file exists at expected path) or `Pending` -> `Needs-Manual` (generation attempted and failed after one retry)
-### 4.4 Verification Phase
-
-- Confirm all successfully generated images are saved to `images/` directory
-- Check filenames match the resource list
-- Update image resource list: `Generated` for files present at the expected path, `Needs-Manual` for rows whose generation failed after one retry
-- Any `Needs-Manual` rows must have been reported to the user with filename and error reason before this phase completes
-
---
-## 5. Prompt Document Template
+## 4. Prompt Document Template
Use the following structure when creating `project/images/image_prompts.md`:
@@ -351,6 +301,7 @@ Use the following structure when creating `project/images/image_prompts.md`:
> Project: {project_name}
> Generated: {date}
> Color scheme: Primary {#HEX} | Secondary {#HEX} | Accent {#HEX}
+> Deck Style Anchor: {15–25 word prefix per §1.6}
---
@@ -374,7 +325,7 @@ Use the following structure when creating `project/images/image_prompts.md`:
| Original description | Modern tech abstract background, deep blue gradient |
**Prompt**:
-Abstract futuristic background with flowing digital waves...
+[Deck Style Anchor], Abstract futuristic background with flowing digital waves...
**Alt Text**:
> Modern tech abstract background with deep blue gradient, digital waves, and particle effects
@@ -391,7 +342,7 @@ Abstract futuristic background with flowing digital waves...
---
-## 6. Negative Prompt Quick Reference
+## 5. Negative Prompt Quick Reference
### By Image Type
@@ -410,9 +361,9 @@ Abstract futuristic background with flowing digital waves...
---
-## 7. Common Issues
+## 6. Common Issues
-### Default Inference When No "Generation Description" Provided
+### Default Inference When No `Reference` Provided
| Purpose | Default Inference |
|---------|------------------|
@@ -442,61 +393,10 @@ Diagnose the problem category and apply a targeted prompt fix:
---
-## 8. Role Collaboration
-
-### Handoff with Strategist
-
-| Direction | Content |
-|-----------|---------|
-| Receives | Design Specification & Content Outline (with image resource list) |
-| Trigger condition | User selected "C) AI generation" in "Image usage" |
-| Key information | Color scheme, design style, canvas format |
-
-### Handoff with Executor
-
-| Direction | Content |
-|-----------|---------|
-| Delivers | All images placed in `project/images/` directory |
-| Executor reference | `<image href="../images/xxx.png" .../>` |
-| Path note | SVGs in `svg_output/`, images in `images/`; use relative path `../images/` |
-
----
-
-## 9. Task Completion Checkpoint
-
-### Must-complete Items
-
-- [ ] Created prompt document `project/images/image_prompts.md`
-- [ ] Each image has: type determination + optimized prompt + negative prompt + Alt Text
-- [ ] Uses unified output format (2.1 standard format)
-- [ ] Phase completion confirmation output
-
-### Image Readiness (at least one must be satisfied)
-
-- [ ] All images saved to `project/images/` directory
-- [ ] Or: User clearly informed to self-generate using `image_prompts.md`
+## 7. Forbidden
-### Pipeline Flow
-
-- [ ] User prompted to proceed to next step (switch to Executor role)
-
-> **Critical check**: If `images/image_prompts.md` was not created, or the output format does not comply with 2.1 standard, the task is NOT complete.
-
-### Completion Confirmation Output Format
-
-```markdown
-## Image_Generator Phase Complete
-
-- [x] Created prompt document `project/images/image_prompts.md`
-- [x] Generated optimized prompts for X images
-- [x] All images saved to `images/` directory
-- [x] Updated image resource list status
-
-**Image Status Summary**:
-
-| Filename | Type | Dimensions | Status |
-|----------|------|-----------|--------|
-| cover_bg.png | Background | 1920x1080 | Generated |
-
-**Next step**: Switch to Executor role to begin SVG generation
-```
+- Generating prompts for `web` rows — those go through [`image-searcher.md`](./image-searcher.md)
+- Brand names or HEX codes inside the subject description (degrades output)
+- Skipping the negative prompt
+- Mixed Deck Style Anchors across images in the same deck (breaks coherence)
+- Placing an image without updating `image_prompts.md` and the resource list status
diff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.md
new file mode 100644
index 00000000..887ac755
--- /dev/null
+++ b/skills/ppt-master/references/image-searcher.md
@@ -0,0 +1,249 @@
+> See [`image-base.md`](./image-base.md) for the common framework. Technical SVG/PPT constraints are in [`shared-standards.md`](./shared-standards.md).
+
+# Image_Searcher Reference Manual
+
+Role definition for the **web image acquisition path**: translate Strategist intent into keyword queries, search openly-licensed providers, download a license-cleared image into `project/images/`, and record provenance + license metadata into `image_sources.json`.
+
+**Trigger**: resource list rows with `Acquire Via: web`. The role is loaded only when at least one such row exists.
+
+---
+
+## 1. License Tier Discipline
+
+Every accepted image is classified into one of two tiers. Anything else is rejected outright.
+
+| Tier | Licenses | On-slide attribution |
+|---|---|---|
+| `no-attribution` | CC0, Public Domain, Pexels License, Pixabay Content License | None |
+| `attribution-required` | CC BY, CC BY-SA | Inline credit `<text>` on the slide |
+
+**Forbidden — auto-rejected licenses**:
+
+- CC BY-NC, CC BY-NC-SA (non-commercial)
+- CC BY-ND, CC BY-NC-ND (no derivatives)
+- All Rights Reserved
+- Unknown / missing license
+
+> `license_tier` is the central abstraction. Downstream consumers (Executor) read this single field and never interpret raw license strings.
+
+---
+
+## 2. Two-Stage Search Strategy
+
+Default: prefer no-attribution images so the deck stays visually clean. Fall back to attribution-required only when the public domain has no match.
+
+```
+Stage 1: ALL providers, license filter = cc0,pdm,pexels,pixabay
+ → first hit wins, done.
+Stage 2: ALL providers, license filter += cc by, cc by-sa
+ → flag chosen item as attribution-required.
+```
+
+`--strict-no-attribution` skips Stage 2 and exits non-zero if Stage 1 finds nothing. Use when the deck cannot tolerate any on-slide credit (corporate template, full-bleed hero).
+
+---
+
+## 3. Providers
+
+| Provider | Config | Strength |
+|---|---|---|
+| Openverse | zero-config | aggregator: Wikimedia + Flickr + museums + rawpixel |
+| Wikimedia Commons | zero-config | educational, scientific, geographic, historical |
+| Pexels | `PEXELS_API_KEY` (free, [signup](https://www.pexels.com/api/)) | modern stock photography, people, scenes |
+| Pixabay | `PIXABAY_API_KEY` (free, [signup](https://pixabay.com/api/docs/)) | broad type coverage including illustrations |
+
+Default chain (when `--provider` is unset):
+
+```
+openverse → wikimedia → pexels (if PEXELS_API_KEY set) → pixabay (if PIXABAY_API_KEY set)
+```
+
+Keyed providers without an API key are silently skipped — not an error.
+
+---
+
+## 4. Intent → Query Translation
+
+Web image APIs match keywords against image metadata, not semantic embeddings. `simplify_query` automatically:
+
+1. Strips HEX color codes (`#1E3A5F`) and parentheticals (`(corporate vibe)`)
+2. Drops hard-noise words: brand names, generic filler
+3. Drops soft-noise words (`ai`, `tech`, `platform`, `system`, `digital`) — only when concrete nouns remain
+4. Caps at 4 words
+5. **Fail-open**: if filtering empties the query, return the original
+
+Then `build_query_progression` tries: original → simplified (4 words) → simplified (3 words). First non-empty hit wins.
+
+| ✅ Good Reference (intent) | ❌ Avoid |
+|---|---|
+| "Aerial view of offshore wind farm at dusk" | "aerial offshore wind 4 keywords" (already keyword-shaped) |
+| "Diverse engineering team collaborating around a laptop" | "use Openverse, search 'team'" (provider mechanics) |
+| "Sunlit forest path in autumn" | "Hero image, dramatic lighting" (composition jargon, no subject) |
+
+---
+
+## 5. Running `image_search.py`
+
+```bash
+python3 scripts/image_search.py "<query>" \
+ --filename <name>.jpg \
+ --slide <slide_id> \
+ --orientation landscape \
+ --purpose background \
+ -o <project_path>/images
+```
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `query` | yes | — | Positional. Pre-simplification not necessary; CLI runs `simplify_query` internally. |
+| `--filename` | yes | — | Output filename matching the resource list |
+| `-o / --output` | no | `.` | Output directory; manifest defaults to `<output>/image_sources.json` |
+| `--slide` | no | `""` | Slide ID from resource list (recorded in manifest) |
+| `--purpose` | no | `""` | `background` / `hero` / `side` / `accent` |
+| `--orientation` | no | `any` | `any` / `landscape` / `portrait` / `square` |
+| `--provider` | no | (chain) | Pin one provider |
+| `--strict-no-attribution` | no | off | Skip Stage 2; refuse CC BY / CC BY-SA |
+| `--manifest` | no | (default) | Override manifest path |
+
+**Pacing (mandatory)**: one search at a time. Wikimedia/Openverse expect identifying User-Agent and reasonable rate (~1 req/sec). Default pacing is fine.
+
+---
+
+## 6. Manifest Format (`image_sources.json`)
+
+Every successful download appends or replaces one entry keyed on `filename`:
+
+```json
+{
+ "license_verification": "provider metadata used; manual review recommended for external delivery",
+ "generated_at": "2026-05-01T12:17:59.856275Z",
+ "items": [
+ {
+ "filename": "team.jpg",
+ "slide": "03_team",
+ "purpose": "Leadership photo",
+ "search_query": "executive boardroom meeting",
+ "orientation": "landscape",
+ "provider": "openverse",
+ "stage": "no-attribution-only",
+ "title": "Untitled",
+ "author": "",
+ "source_page_url": "https://www.rawpixel.com/...",
+ "download_url": "https://...",
+ "license_name": "CC0",
+ "license_url": "https://creativecommons.org/publicdomain/zero/1.0/",
+ "license_tier": "no-attribution",
+ "attribution_required": false,
+ "width": 1024,
+ "height": 683,
+ "metadata_dimensions": {
+ "width": 4800,
+ "height": 3200,
+ "note": "upstream-reported size; actual downloaded file is smaller (likely a preview)"
+ },
+ "attribution_text": "team.jpg — \"Untitled\" via Openverse — license: CC0 (...)",
+ "status": "sourced"
+ }
+ ]
+}
+```
+
+| Field | Notes |
+|---|---|
+| `width` / `height` | Measured from the file actually saved to disk. Use these for layout. |
+| `metadata_dimensions` | Present only when upstream-claimed size differs from the saved file (preview vs original). Informational only. |
+| `license_tier` | Drives Executor's attribution decision. Only `no-attribution` / `attribution-required`. |
+| `attribution_required` | Boolean alias of `license_tier == "attribution-required"`. |
+| `attribution_text` | Pre-rendered canonical credit string. **Use as-is; do not regenerate.** |
+| `stage` | `no-attribution-only` or `all`. Useful for auditing fallbacks. |
+
+> Manifest is **idempotent on `filename`**. Rerunning the CLI replaces that entry; other entries are preserved.
+
+---
+
+## 7. On-Slide Attribution — Visual Specification
+
+Applied by Executor when an image's `license_tier == "attribution-required"`. Three layouts depending on the page.
+
+### 7.1 Single-image page
+
+- **Position**: bottom-right of the image's container, hugging the image edge (within ~8 px)
+- **Font size**: 6–8pt equivalent (≈ 0.7–1 % of canvas short edge)
+- **Color**: `#999` on light/photo backgrounds; `rgba(255,255,255,0.6)` on dark/photo
+- **Content**: `© {author} / {provider_short} / {license_short}`
+ - `provider_short`: `Openverse` / `Wikimedia` / `Pexels` / `Pixabay`
+ - `license_short`: `CC BY 4.0` / `CC BY-SA 4.0` / `Public Domain`
+ - Drop empty fields (CC0 with no author → `via Openverse`)
+
+**Forbidden — fields that break the visual line**: full URLs, `attribution_text` verbatim, "License:" prefix.
+
+### 7.2 Multi-image page (≥ 2 attribution-required)
+
+Combine into one source line at the page bottom rather than scattering credits:
+
+```
+Sources: a, b via Wikimedia (CC BY); c via Openverse (CC BY-SA)
+```
+
+Use single-letter labels (a/b/c) only when needed for disambiguation.
+
+### 7.3 Hero / full-bleed image
+
+- Bottom 1.5 cm gradient overlay: transparent → `rgba(0,0,0,0.5)`
+- 7pt white semi-transparent text inside the overlay band, right-aligned ~24 px from edge
+
+### 7.4 Source for the credit text
+
+Use `attribution_text` from the manifest as the **starting point**. Compress for the small-text constraint:
+
+| Manifest | Slide credit |
+|---|---|
+| `team.jpg — "Untitled" via Openverse — license: CC0 (...)` | `via Openverse / CC0` |
+| `team.jpg — "Sunset" by Jane Doe via Wikimedia Commons — license: CC BY-SA 4.0 (...)` | `© Jane Doe / Wikimedia / CC BY-SA 4.0` |
+
+---
+
+## 8. Failure Handling (web-specific)
+
+Extends [`image-base.md`](./image-base.md) §6.
+
+| Situation | Behavior |
+|---|---|
+| No candidates from any provider in either stage | Mark row `Needs-Manual`. Suggest: shorter query, drop `--strict-no-attribution`, or set keyed provider's API key. |
+| Single candidate fails to download (HTTP 403/404) | Dispatcher auto-falls through to the next ranked candidate. No user action. |
+| All candidates from one provider fail | Dispatcher moves to the next provider in the chain. |
+| Keyed provider has no API key | Silently skipped. Not an error. |
+
+CLI exit: `0` on success, `1` only when no acceptable image was found across the entire dispatch matrix.
+
+---
+
+## 9. Handoff with Strategist
+
+Reference field is **intent description**, not a query. See [`image-base.md`](./image-base.md) §8 for the rule.
+
+If the description is verbose, that's fine — `simplify_query` handles it.
+
+---
+
+## 10. Handoff with Executor
+
+Executor reads `image_sources.json` per slide that uses a Sourced image. For each entry:
+
+| `license_tier` | Slide-level action |
+|---|---|
+| `no-attribution` | Embed `<image>` only |
+| `attribution-required` | Embed `<image>` **and** an inline credit element per §7 |
+
+Executor does not interpret raw license strings — `license_tier` is sufficient.
+
+---
+
+## 11. Task Completion Checkpoint
+
+In addition to the shared checkpoint in [`image-base.md`](./image-base.md) §10:
+
+- [ ] Every web row has a downloaded file at `project/images/<filename>` OR is marked `Needs-Manual`
+- [ ] Each `Sourced` row has a manifest entry with valid `license_tier` and non-empty `attribution_text`
+- [ ] `metadata_dimensions` warnings surfaced when downloaded preview is much smaller than upstream-claimed size
+- [ ] `Needs-Manual` rows include the failure reason
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index c2761246..9296a418 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -185,11 +185,14 @@ Baseline choice follows **content density**, not style. Common: `18px` (dense) /
| **A** | No images | Data reports, process documentation |
| **B** | User-provided | Has existing image assets |
| **C** | AI-generated | Custom illustrations, backgrounds needed |
-| **D** | Placeholders | Images to be added later |
+| **D** | Web-sourced | Real-world reference imagery, editorial support, stock-style needs (no API key required for default providers) |
+| **E** | Placeholders | Images to be added later |
+
+Selections may be mixed at the row level — e.g. a deck can use C for hero illustrations while sourcing D for supporting team photos.
**When selection includes B**, you must run `python3 scripts/analyze_images.py <project_path>/images` before outputting the spec, and integrate scan results into the image resource list.
-**When B/C/D is selected**, add an image resource list to the spec:
+**When B / C / D / E is selected**, add an image resource list to the spec:
| Column | Description |
|--------|-------------|
@@ -199,12 +202,24 @@ Baseline choice follows **content density**, not style. Common: `18px` (dense) /
| Layout suggestion | e.g., `Wide landscape (suitable for full-screen/illustration)` |
| Purpose | e.g., `Cover background` |
| Type | Background / Photography / Illustration / Diagram / Decorative pattern |
+| **Acquire Via** | `ai` / `web` / `user` / `placeholder` — drives Step 5 dispatch |
| Status | Initial status must be `Pending`, `Existing`, or `Placeholder`; see [`svg-image-embedding.md`](svg-image-embedding.md) for the full status enum |
-| Generation description | Fill in detailed description for AI generation |
+| **Reference** | Free-form **intent description** (NOT a search query); feeds Image_Generator (ai) or Image_Searcher (web) |
+
+**Reference field — write intent, not mechanics**:
+
+This field is consumed by either Image_Generator (which expands it into an AI prompt) or Image_Searcher (which simplifies it into 2–5 keywords). The Strategist's job is to describe the **visual intent**:
+
+- ✅ "Diverse engineering team collaborating around a laptop, modern office, natural light"
+- ✅ "Abstract flowing digital waves in deep navy (#1E3A5F) to midnight blue gradient, subtle particle effects, clean center area for text overlay"
+- ✅ "Sunlit forest path in autumn"
+- ❌ "team laptop office" (already keyword-shaped — let Image_Searcher do that)
+- ❌ "use openverse, search 'office'" (provider mechanics are not a Strategist concern)
+- ❌ "team photo" (too thin)
-**Generation description quality** — feeds Image_Generator's prompt; specify subject, count, setting, lighting, colors (HEX), composition. Avoid one-word descriptions like "team photo" / "tech background" / "chart".
+For `ai` rows, include subject + style + colors (HEX) + composition. For `web` rows, prioritize concrete nouns and visual descriptors — but you can still write the description naturally; `simplify_query` strips noise words automatically.
-| Good examples |
+| Good examples (work for both ai and web) |
|---------------|
| "Professional team of 4 diverse people collaborating at a modern office desk, natural lighting, laptop visible" |
| "Abstract flowing digital waves in deep navy (#1E3A5F) to midnight blue gradient, subtle particle effects, clean center area for text overlay" |
diff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.md
index 754e435e..5c637da7 100644
--- a/skills/ppt-master/references/svg-image-embedding.md
+++ b/skills/ppt-master/references/svg-image-embedding.md
@@ -8,35 +8,42 @@ Technical spec and workflow for adding images to SVG files.
## Image Resource List Format
-Defined in the Design Specification & Content Outline; each image carries a status annotation. This file is authoritative for status names and SVG embedding behavior. If image approach includes "B) User-provided": run `analyze_images.py` right after the Eight Confirmations and complete the list before outputting the design spec.
+Defined in the Design Specification & Content Outline; each image carries an `Acquire Via` field plus a status annotation. This file is authoritative for status names and SVG embedding behavior. If image approach includes "B) User-provided": run `analyze_images.py` right after the Eight Confirmations and complete the list before outputting the design spec.
```markdown
-| Filename | Dimensions | Purpose | Type | Status | Generation Description |
-|----------|------------|---------|------|--------|------------------------|
-| cover_bg.png | 1280x720 | Cover background | Background | Pending | Modern tech abstract background, deep blue gradient |
-| product.png | 600x400 | Page 3 product photo | Photography | Existing | - |
-| team.png | 600x400 | Page 5 team scene | Illustration | Placeholder | Team collaboration scene to be added later |
+| Filename | Dimensions | Purpose | Type | Acquire Via | Status | Reference |
+|----------|------------|---------|------|-------------|--------|-----------|
+| cover_bg.png | 1280x720 | Cover background | Background | ai | Pending | Modern tech abstract, deep blue gradient |
+| team.jpg | 800x600 | Team photo | Photography | web | Pending | Diverse engineering team in modern office |
+| product.png | 600x400 | Page 3 product photo | Photography | user | Existing | - |
+| chart.png | 600x400 | Page 5 placeholder | Illustration | placeholder | Placeholder | Team collaboration scene to be added later |
```
### Image Status Enum
| Status | Meaning | Executor Handling |
|--------|---------|-------------------|
-| **Pending** | Needs AI generation, has generation description | Image_Generator attempts generation before Executor; must not remain after Step 5 |
-| **Generated** | AI-generated file exists at expected path | Reference directly from `../images/` |
-| **Needs-Manual** | Generation attempted once + one retry, failed | Dashed placeholder unless user has manually supplied the file |
-| **Existing** | User already has image | Place in `images/`, reference with `<image>` |
-| **Placeholder** | Intentionally not prepared yet | Dashed border placeholder; replace later |
+| **Pending** | Acquisition needed (`Acquire Via: ai` or `web`); not yet attempted | Image Acquisition Phase (Step 5) consumes this; must not remain after Step 5 |
+| **Generated** | AI-generated file exists at expected path | Reference from `../images/`; no on-slide credit needed |
+| **Sourced** | Web-sourced file exists at expected path | Reference from `../images/`; check `image_sources.json` for `license_tier` — if `attribution-required`, render an inline credit element on the slide (see [executor-base.md §6](./executor-base.md) and [image-searcher.md §7](./image-searcher.md) for the visual spec) |
+| **Needs-Manual** | Acquisition attempted once + one retry, failed | Dashed placeholder unless user has manually supplied the file |
+| **Existing** | User already has image (`Acquire Via: user`) | Place in `images/`, reference with `<image>` |
+| **Placeholder** | Intentionally not prepared yet (`Acquire Via: placeholder`) | Dashed border placeholder; replace later |
---
## Workflow
```
-1. Strategist defines image needs → Add image resource list, annotate each status
-2. Image preparation (Pending / Existing) → Place available files in project/images/
+1. Strategist defines image needs → Add image resource list with Acquire Via + Status per row
+2. Image Acquisition (Step 5):
+ - Pending + ai → Image_Generator runs image_gen.py → Generated
+ - Pending + web → Image_Searcher runs image_search.py → Sourced
+ - user / placeholder rows are skipped
3. Executor generates SVGs (svg_output/)
├── Existing / Generated → <image href="../images/xxx.png" .../>
+ ├── Sourced + license_tier=no-attribution → <image href=...> only
+ ├── Sourced + license_tier=attribution-required → <image href=...> + small <text> credit element on the slide
└── Placeholder / Needs-Manual without file → Dashed border + description text
4. Preview: python3 -m http.server -d <project_path> 8000 → /svg_output/<filename>.svg
5. Post-processing & Export → follow shared-standards.md §5