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.mdindex 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.mdindex 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 Usagediff --git a/skills/ppt-master/references/image-base.md b/skills/ppt-master/references/image-base.mdnew file mode 100644index 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.mdindex 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 MethodExtract 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 StrategyWhen 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 / Decorative2. **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 format6. **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 TemplateUse 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 statusdiff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.mdnew file mode 100644index 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 reasondiff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 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.mdindex 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 skipped3. 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 text4. Preview: python3 -m http.server -d <project_path> 8000 → /svg_output/<filename>.svg5. Post-processing & Export → follow shared-standards.md §5