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

feat(workflow): add split-mode resume-execute and refresh topic-research

hugohe3215e05b9b3f4
diff --git a/AGENTS.md b/AGENTS.md
index 653a57a9..0283ece7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,6 +10,10 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat
**Core Pipeline**: `Source Document → Create Project → Template Option → Strategist Eight Confirmations → [Image_Generator] → Executor → Quality Check → Post-processing → Export PPTX`
+> Topic-only requests with no source material: run the standalone [`topic-research`](skills/ppt-master/workflows/topic-research.md) workflow before SKILL.md Step 1 to gather web materials.
+>
+> Phase B resumption (split-mode execution): when the user opens a fresh chat and says "继续生成 projects/<x>" or similar, run the standalone [`resume-execute`](skills/ppt-master/workflows/resume-execute.md) workflow to enter Phase B (SVG generation + export) without re-running Phase A.
+>
> Decks containing data charts: run the standalone [`verify-charts`](skills/ppt-master/workflows/verify-charts.md) workflow between the executor and post-processing steps to calibrate chart coordinates.
>
> Recorded narration / video export: run the standalone [`generate-audio`](skills/ppt-master/workflows/generate-audio.md) workflow after post-processing.
diff --git a/CLAUDE.md b/CLAUDE.md
index c5600c8b..6eb9e6af 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,6 +10,10 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat
**Core Pipeline**: `Source Document → Create Project → Template Option → Strategist Eight Confirmations → [Image_Generator] → Executor → Quality Check → Post-processing → Export PPTX`
+> Topic-only requests with no source material: run the standalone [`topic-research`](skills/ppt-master/workflows/topic-research.md) workflow before SKILL.md Step 1 to gather web materials.
+>
+> Phase B resumption (split-mode execution): when the user opens a fresh chat and says "继续生成 projects/<x>" or similar, run the standalone [`resume-execute`](skills/ppt-master/workflows/resume-execute.md) workflow to enter Phase B (SVG generation + export) without re-running Phase A.
+>
> Decks containing data charts: run the standalone [`verify-charts`](skills/ppt-master/workflows/verify-charts.md) workflow between the executor and post-processing steps to calibrate chart coordinates.
>
> Recorded narration / video export: run the standalone [`generate-audio`](skills/ppt-master/workflows/generate-audio.md) workflow after post-processing.
diff --git a/docs/faq.md b/docs/faq.md
index 115bc8d2..10d9e4c2 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -8,6 +8,12 @@
Almost anything: **PDF**, **DOCX**, **PPTX**, **EPUB**, **HTML**, **LaTeX**, **RST**, **URLs** (including WeChat articles), **Markdown**, or just plain text pasted into the conversation. The AI agent converts your source material to Markdown automatically before generating slides.
+## Q: Can I generate a deck with just a topic, no source materials?
+
+Yes. Tell the AI your topic or scenario (e.g. "make a PPT about Hayao Miyazaki", "introduce our new product"). The AI will trigger the **topic-research workflow** — gathering authoritative sources via web search (Wikipedia / official sites / institutional releases), assembling them into a Markdown research document + image folder, then feeding both into the main pipeline.
+
+Quality depends on what's on the open web. If you already have specialized material (papers, internal docs), giving those files to the AI directly produces better results than web research alone.
+
## Q: Can PPT Master produce formats other than PowerPoint?
Yes. Besides the standard **16:9** and **4:3** presentation formats, PPT Master supports social media and marketing formats out of the box:
@@ -98,6 +104,14 @@ A typical 10–15 page presentation takes about **10–20 minutes** with a fast
If generation feels slow, check your model's token throughput. The bottleneck is usually the model's output speed, not the scripts.
+## Q: Will long decks blow out the context window in one shot?
+
+Default recommendation: **continuous one-shot generation**. 10–15 page decks fit comfortably in a 200K window, and cross-page visual consistency is best when the Executor can see prior pages in the same session (it actively aligns style, font sizes, and rhythm).
+
+Only when signals are heavy (≥ 18 pages, thick source material, or `topic-research` ran with substantial web-fetch accumulation) does the AI surface an optional **two-stage (split mode)** hint at the Strategist phase: Phase A (eight confirmations + image acquisition) ends in the current chat; you open a fresh chat window and type `继续生成 projects/<project_name>` (or "resume execution projects/<project_name>") to enter Phase B (SVG generation + export). The new session reloads `design_spec` / `spec_lock` / `sources` / `images` from disk and continues from there.
+
+Split mode is a **compromise** — it pays ~6K tokens (re-reading SKILL.md) to drop 60–200K of Phase A noise, then reuses the freed budget in Phase B to re-read `sources/` for richer slide content. **Not needed when signals are normal**; the hint won't appear, and you can always ignore it and stay in continuous mode.
+
## Q: Can I preview or fix individual pages before the full export?
Yes. You can **interrupt the workflow at any time** — after the first few pages are generated, review them and give feedback. The AI can regenerate specific pages based on your comments. You don't need to wait until the end to make corrections.
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 170a9488..2cc10743 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -8,6 +8,12 @@
几乎所有常见格式都支持:**PDF**、**DOCX**、**PPTX**、**EPUB**、**HTML**、**LaTeX**、**RST**、**网页链接**(包括微信公众号文章)、**Markdown**,或者直接在对话中粘贴文字内容。AI 代理会自动将源材料转换为 Markdown 后再生成幻灯片。
+## Q: 只有一个主题或想法、没有任何资料,也能生成吗?
+
+可以。直接告诉 AI 你想做的主题或场景(如"做一个关于宫崎骏的 PPT"、"介绍我们公司新产品"),AI 会自动启动 **topic-research 工作流**——通过网页搜索抓取权威来源(Wikipedia / 官网 / 机构发布),整理成 Markdown 资料文档 + 配图集后再走主流程生成幻灯片。
+
+效果取决于公开网页的覆盖度。如果你已有专业资料(论文、内部文档),直接把文件给 AI 比联网检索更准。
+
## Q: 除了 PPT 还能生成其他格式吗?
可以。除了标准的 **16:9** 和 **4:3** 演示文稿格式,PPT Master 还内置了社交媒体和营销类格式:
@@ -98,6 +104,14 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger o
如果感觉生成很慢,检查一下模型的 token 吞吐速度。瓶颈通常在模型的输出速度,而不是脚本本身。
+## Q: 长 PPT 一次生成会不会上下文爆掉?
+
+默认推荐**一次性连续生成**——10–15 页的 deck 在 200K 上下文窗口下完全够用,跨页视觉一致性也最好(Executor 看到前几页 SVG 后会主动对齐风格、字号、节奏)。
+
+只有信号偏重的场景(页数 ≥ 18 / 源材料很厚 / 走过 topic-research 累积大量 web 抓取),AI 才会在策略师阶段给出**两段式(拆分模式)**的可选提示:第一阶段(八项确认 + 图片获取)结束后停止当前对话;你新开聊天窗口,输入 `继续生成 projects/<项目名>` 进入第二阶段(SVG 生成 + 导出)。新会话从磁盘重新加载 `design_spec` / `spec_lock` / `sources` / `images` 继续执行。
+
+两段式是**折中方案**——付出约 6K tokens 的 SKILL.md 重读成本,换得 60–200K 的 Phase A 噪声丢弃,并把节省下来的窗口空间用于 Phase B 主动重读 `sources/` 做内容增稠。**信号正常时不需要**,提示也不会出现;用户随时可以忽略提示,走默认连续模式。
+
## Q: 能在导出前预览或修正某一页吗?
可以。你可以**随时中断工作流**——前几页生成后就可以查看并反馈意见。AI 可以根据你的意见重新生成特定页面,不需要等到全部完成再修改。
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 6a94978c..0baf7e5b 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -73,7 +73,9 @@ For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.
| Workflow | Path | Purpose |
|----------|------|---------|
+| `topic-research` | `workflows/topic-research.md` | Pre-pipeline — gather web sources when the user supplies only a topic with no source files |
| `create-template` | `workflows/create-template.md` | Standalone template creation workflow |
+| `resume-execute` | `workflows/resume-execute.md` | Phase B entry — resume execution in a fresh chat after Phase A (Step 1–5) completed in another session (split mode) |
| `verify-charts` | `workflows/verify-charts.md` | Chart coordinate calibration — run after SVG generation if the deck contains data charts |
| `visual-edit` | `workflows/visual-edit.md` | Browser-based visual editor for fine-grained edits — run only when the user explicitly requests it after export |
@@ -85,6 +87,8 @@ For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.
🚧 **GATE**: User has provided source material (PDF / DOCX / EPUB / URL / Markdown file / text description / conversation content — any form is acceptable).
+> **No source content?** When the user supplies only a topic name or requirements without any file or substantive description, run the [`topic-research`](workflows/topic-research.md) workflow first, then return here with its products as input.
+
When the user provides non-Markdown content, convert immediately:
| User Provides | Command |
@@ -172,7 +176,7 @@ Read references/strategist.md
**Eight Confirmations** (full template: `templates/design_spec_reference.md`):
-⛔ **BLOCKING**: present the Eight Confirmations as a bundled recommendation set and **wait for explicit user confirmation or modification** before outputting Design Specification & Content Outline. This is the single core confirmation point — once confirmed, all subsequent steps proceed automatically.
+⛔ **BLOCKING**: present the Eight Confirmations as a single bundled recommendation set and **wait for explicit user confirmation or modification** before outputting Design Specification & Content Outline. This is the single core confirmation point — once confirmed, all subsequent steps proceed automatically.
1. Canvas format
2. Page count range
@@ -183,6 +187,12 @@ Read references/strategist.md
7. Typography plan
8. Image usage approach
+**Optional — split-mode hint** (not a ninth confirmation): when Phase A signals point to heavy downstream load — recommended page count is on the long side, source materials are bulky, or `topic-research` ran with substantial web-fetch accumulation — append a single short suggestion below the eight confirmations:
+
+> 💡 本次预计生成 ~N 页、源材料体量较大,建议 Step 5 完成后切换至[拆分模式](workflows/resume-execute.md):本对话停止,新窗口输入 `继续生成 projects/<project_name>` 进入 Phase B(SVG 生成 + 导出)。无回应或选择继续 = 默认连续模式。
+
+This is a hint, not a confirmation item — the user may ignore it. When signals are normal, omit the hint entirely. Default behavior remains continuous mode.
+
If the user provided images, run analysis **before outputting the design spec**:
```bash
python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
@@ -233,7 +243,7 @@ Workflow:
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 acquisition attempted for every row, proceed to Step 6**:
+**✅ Checkpoint — Confirm acquisition attempted for every row**:
```markdown
## ✅ Image Acquisition Phase Complete
- [x] image_prompts.md created (when any ai rows processed)
@@ -241,7 +251,16 @@ Workflow:
- [x] Each row: status is `Generated` / `Sourced` / `Needs-Manual` (no `Pending` remaining)
```
-> 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.
+**Default — auto-proceed to Step 6.** Only when the user's Step 4 response explicitly opted into split mode (in reply to the optional hint), output the Phase A hand-off below and stop this conversation:
+
+ ```markdown
+ ## ✅ Phase A Complete
+ - [x] Spec: `design_spec.md`, `spec_lock.md`
+ - [x] Resources: `sources/`, `images/`, `templates/`
+ - [ ] **Next**: open a fresh chat window and input `继续生成 projects/<project_name>` to enter Phase B via the [`resume-execute`](workflows/resume-execute.md) workflow.
+ ```
+
+> 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 the checkpoint above.
---
diff --git a/skills/ppt-master/workflows/resume-execute.md b/skills/ppt-master/workflows/resume-execute.md
new file mode 100644
index 00000000..4fd339a7
--- /dev/null
+++ b/skills/ppt-master/workflows/resume-execute.md
@@ -0,0 +1,68 @@
+---
+description: Phase B entry — resume PPT execution in a fresh chat after Phase A (SKILL.md Step 1-5) completed in a previous session. Reads project state from disk and runs Step 6 + Step 7 with no Phase-A context carry-over.
+---
+
+# Resume Execute Workflow
+
+> Standalone Phase-B entry. Run when Phase A (SKILL.md Step 1–5) completed in a previous session and the user wants to continue with SVG generation + export. Loads project state from disk and runs Step 6 + Step 7 in a clean session.
+
+This workflow is **independent**: it owns Phase B starting from a fresh chat — no upstream conversation context required. By isolating SVG generation in its own session, the model gains 20–40K context headroom by not carrying Phase A's eight-confirmation dialogue, image search/fetch results, or Strategist references.
+
+## When to Run
+
+The user opens a new chat and gives a phrase that names a project path and signals continuation. Recognize any of:
+
+| Pattern | Example |
+|---|---|
+| "继续生成 projects/<project_name>" | "继续生成 projects/ppt169_joe_hisaishi" |
+| "resume execution projects/<project_name>" | "resume execution projects/ppt169_joe_hisaishi" |
+| Project path + any "继续 / 恢复 / 继续做 / 接着做" semantic | "把 projects/ppt169_joe_hisaishi 继续做完" |
+
+**Prerequisite**: Phase A must have completed in the named project. Verified by file presence in Step 1; do NOT auto-trigger Phase A on missing state.
+
+---
+
+## Step 1: Sanity check
+
+Verify the project's Phase-A artifacts before doing anything else:
+
+| File / Directory | Required when | Reason |
+|---|---|---|
+| `<project_path>/spec_lock.md` | Always | Strategist's execution contract; Executor reads it per page |
+| `<project_path>/design_spec.md` | Always | Section IX page outline; Executor cross-references it |
+| `<project_path>/images/` | `spec_lock images` references any image | Images must exist for embedding |
+| `<project_path>/templates/` | `spec_lock page_layouts` / `page_charts` references any | Layout / chart SVGs needed for batch read |
+
+If any required artifact is missing → report which one(s) and stop. Do NOT auto-fall-back into Phase A; the user must either complete Phase A in the original session or explicitly restart.
+
+---
+
+## Step 2: Load SKILL.md, proceed from Step 6
+
+```
+Read skills/ppt-master/SKILL.md
+```
+
+Then jump to `### Step 6: Executor Phase` and run the documented pipeline:
+
+- Read references (executor-base + shared-standards + chosen style file + image-layout-spec + svg-image-embedding)
+- Design Parameter Confirmation
+- Pre-generation Batch Read (every layout / chart SVG referenced in `spec_lock`)
+- Per-page `spec_lock` re-read + sequential page generation
+- Quality Check Gate
+- Speaker notes generation
+- Step 7: Post-processing & Export (`total_md_split` → `finalize_svg` → `svg_to_pptx`)
+
+The fresh session pays the cost of re-reading references (~14K tokens) but earns back substantially more headroom by dropping Phase A's accumulated context. Net win in both window pressure and reasoning budget per page.
+
+**Source materials**: Phase B is a fresh session; `<project_path>/sources/<file>.md` is NOT in context. The Executor SHOULD read the relevant `sources/` files when crafting per-page content — they hold the concrete facts, quotes, names, and details that turn skeleton outlines into substantive slides. `design_spec.md §IX` only carries the per-page intent; the source materials carry the texture. The Phase A → Phase B split is designed to free context budget precisely for this kind of high-quality enrichment.
+
+> Note: this workflow does NOT duplicate Step 6 / Step 7 content. SKILL.md is the authoritative procedure; resume-execute only adds the resumption entry (When to Run + Step 1 sanity check above) and the source-materials guidance above.
+
+---
+
+## Step 3: Hand-back
+
+When Step 7 completes and `exports/<project_name>_<timestamp>.pptx` is produced, the workflow ends. Report the export path to the user.
+
+If the deck contains data charts, the [`verify-charts`](verify-charts.md) workflow runs between Step 6 and Step 7 as documented in SKILL.md — resume mode handles it the same way the continuous mode does.
diff --git a/skills/ppt-master/workflows/topic-research.md b/skills/ppt-master/workflows/topic-research.md
index 781f0dc4..6eb4df4a 100644
--- a/skills/ppt-master/workflows/topic-research.md
+++ b/skills/ppt-master/workflows/topic-research.md
@@ -1,200 +1,119 @@
---
-description: Research a topic from scratch when the user provides only a brief description or requirements without detailed source materials. Produces a structured Markdown document and a folder of related images.
+description: Gather source materials via web search when the user supplies only a topic or requirements without source files. Produces a Markdown document and an image folder that feed SKILL.md Step 2's import-sources.
---
# Topic Research Workflow
-> **Standalone pre-processing workflow** — produces source materials that can feed into the main PPT generation pipeline or be used independently.
+> Standalone pre-processing step. Run before SKILL.md Step 1 when the user supplies only a topic or requirements with no source files. Output is a research document + image folder, both shaped to feed `project_manager.py import-sources` directly.
-## Trigger Condition
+This workflow is **independent**: it owns the source-acquisition step when no file exists; subsequent SKILL.md steps proceed normally with the produced materials as input.
-The user provides **only a topic name, a brief description, or a set of requirements** — no PDF, DOCX, URL, or other source files.
+## When to Run
-Examples:
-- "Make a PPT about Joe Hisaishi"
-- "Create a presentation about renewable energy trends"
-- "I want to introduce our new product (with a brief description)"
-
-## Deliverables
-
-All outputs MUST be placed under the `projects/` directory:
-
-| Deliverable | Path | Example |
-|-------------|------|---------|
-| Structured Markdown document | `projects/<topic_name>.md` | `projects/joe_hisaishi.md` |
-| Image folder | `projects/<topic_name>/` (same name as the document, without extension) | `projects/joe_hisaishi/` |
-
-> **Naming consistency rule**: The Markdown filename (without `.md`) and the image folder name MUST be identical.
->
-> **Output directory rule**: Both the document and image folder MUST be created inside `projects/`. Never place them in the repository root or any other location.
-
-## Process Overview
-
-```
-Confirm Topic → Research Content → Collect Images → Output
-```
+| User-supplied input | Action |
+|---|---|
+| Topic name only (e.g. "做一个关于宫崎骏的 PPT") | Run this workflow |
+| Requirement description without facts (e.g. "介绍我们公司新产品") | Run this workflow |
+| ≥1 page of substantive content already in chat | Skip — feed chat content into SKILL.md Step 1 directly |
+| Source file attached (PDF / DOCX / URL / Markdown) | Skip — go to SKILL.md Step 1 source converter |
---
-## Step 1: Topic Confirmation
+## Step 1: Confirm topic
-⛔ **BLOCKING**: Before starting research, confirm the following with the user. If the user's initial message already covers these points clearly, skip the confirmation and proceed.
+⛔ **BLOCKING**: confirm scope as a single bundled clarifier. Skip when the user's initial message already covers it.
-| Item | Description | Example |
-|------|-------------|---------|
-| **Topic** | Core subject | Joe Hisaishi |
-| **Scope / Focus** | What aspects to cover | Biography, major works, collaboration with Miyazaki, awards |
-| **Depth** | Surface overview vs. deep dive | General knowledge level |
-| **Language** | Output language | English |
+| Item | Default if user did not specify |
+|---|---|
+| Topic | (from user input) |
+| Scope / focus | Broad overview |
+| Depth | General-knowledge level |
+| Output language | Match user input |
+| Slug for files (`<topic_slug>`) | snake_case English identifier derived from topic |
-**If the user's request is already clear enough** (e.g., "Make a PPT about Joe Hisaishi"), infer reasonable defaults and proceed — do not over-ask.
+**Forbidden — itemized confirmation**: do NOT ask each row separately. One bundled clarifier or none.
---
-## Step 2: Content Research
-
-### 2.1 Information Gathering
-
-Use `WebSearch` and `WebFetch` to collect information from multiple sources:
-
-| Source Type | Priority | Tools | Notes |
-|------------|----------|-------|-------|
-| Wikipedia / Encyclopedia | High | WebSearch → WebFetch | Authoritative overview, timeline, key facts |
-| Official websites | High | WebFetch | First-party information |
-| News / media articles | Medium | WebSearch → WebFetch | Recent events, awards, public reception |
-| Professional databases | Low | WebSearch | Industry-specific data if relevant |
-
-**Research strategy**:
-1. Start with a broad WebSearch to understand the topic landscape
-2. WebFetch 2-3 key authoritative pages (Wikipedia, official sites) for detailed content
-3. Supplement with targeted searches for specific subtopics as needed
-
-### 2.2 Content Organization
-
-Organize the gathered information into a structured Markdown document with the following skeleton:
-
-```markdown
-# <Topic Name>
-
-> Brief one-line description of the topic.
+## Step 2: Gather via web search
-## Overview
-[2-3 paragraph summary]
+**Tools** — use the web search and web fetch tools the current IDE provides:
-## Background / History
-[Timeline, origin story, key milestones]
+| IDE | Web search | Web fetch |
+|---|---|---|
+| Claude Code | `WebSearch` | `WebFetch` |
+| Cursor / Codebuddy / VS Code + Copilot | provider-equivalent built-in | provider-equivalent built-in |
+| None available | — | fallback below |
-## Key Aspects
-### Aspect 1: [...]
-### Aspect 2: [...]
-### Aspect 3: [...]
+**Fallback when no IDE web tools** — pause, ask the user for 2–4 authoritative URLs (Wikipedia / official site / institutional release), then fetch each:
-## Achievements / Impact
-[Awards, recognition, influence]
-
-## Key Facts & Figures
-| Item | Value |
-|------|-------|
-| ... | ... |
-
-## Sources
-- [Source 1 title](URL)
-- [Source 2 title](URL)
+```bash
+python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>
```
-> The skeleton above is a **reference template** — adapt the section structure to fit the topic. A person biography will differ from a technology overview or a company profile.
+**Search strategy**:
-**Content guidelines**:
-- Include specific facts, dates, and names — avoid vague generalizations
-- Preserve key quotes when found
-- Note data sources for verifiability
-- Aim for PPT-ready content density: enough detail to fill 10-15 slides, but not an exhaustive research paper
+| Phase | Action |
+|---|---|
+| Landscape | One broad search; identify authoritative sources |
+| Deep fetch | Pull 2–4 highest-signal pages in full |
+| Targeted fill | Search for subtopics the deep fetch flagged |
-### 2.3 Save Document
+**Source priority**:
-Save the Markdown document to the `projects/` directory:
+| Tier | Source |
+|---|---|
+| 1 | Wikipedia / Wikimedia Commons |
+| 2 | Official sites, institutional releases |
+| 3 | Reputable news / academic articles |
+| Avoid | Stock-aggregator watermarked images, social-media reposts without source |
-```
-projects/<topic_name>.md
-```
+**Stop condition**: stop when gathered material covers overview / history / key aspects / impact / sources with concrete facts and named entities. Endless searching produces noise.
---
-## Step 3: Image Collection
+## Step 3: Save materials
-### 3.1 Image Source Strategy
+Two artifacts under `projects/`:
-Search for **publicly available, freely usable** images in this priority order:
+| Artifact | Path |
+|---|---|
+| Research document | `projects/<topic_slug>.md` |
+| Image folder | `projects/<topic_slug>/` |
-| Source | How to Find | License Notes |
-|--------|------------|---------------|
-| **Wikipedia / Wikimedia Commons** | WebFetch the Wikipedia page → extract `upload.wikimedia.org` image URLs → get full-resolution versions (remove `/thumb/` and size suffix from URL) | CC-BY-SA or Public Domain |
-| **Official websites** | WebFetch official/institutional pages → look for gallery or press sections | Typically free for editorial/educational use |
-| **Government / institutional releases** | WebSearch for official press kits, public galleries | Usually public domain |
-| **Creative Commons search** | WebSearch with `site:commons.wikimedia.org` or `site:flickr.com/photos` + creative commons | Check specific CC license |
+**Hard rule — naming**: filename (without `.md`) and folder name MUST match. **Hard rule — location**: under `projects/`, never the repository root.
-**Avoid**: Stock photo sites with watermarks, copyrighted commercial images, social media uploads without clear licensing.
+**Document structure** — section layout follows the topic: person → biography / works / impact; technology → background / mechanism / applications / outlook; company → overview / products / market / culture. The file MUST end with a `## Sources` section listing the URLs used.
-### 3.2 Image Selection Criteria
+**Content density** — concrete facts (dates, names, numbers, quotes). Skip filler prose; the Strategist composes final slide copy.
-| Criterion | Guideline |
-|-----------|-----------|
-| **Quantity** | 6-12 images (enough to support a 10-15 page PPT) |
-| **Variety** | Mix of portraits, scenes, logos, event photos as relevant |
-| **Resolution** | Prefer 1000px+ width; avoid thumbnails |
-| **Relevance** | Each image should serve a clear purpose (cover, illustration, background) |
-| **Aspect ratio mix** | Include both landscape (for backgrounds) and portrait (for profiles) when applicable |
+**Images**:
-### 3.3 Download Process
+| Decision | Rule |
+|---|---|
+| Quantity | Cover the deck's likely scenes (cover, key aspects, key entities); the Strategist decides the final cut |
+| Resolution | Prefer originals. Wikimedia: strip `/thumb/` and the `Npx-` prefix from the URL to get full resolution |
+| License | Wikimedia / public-domain / CC-licensed; avoid stock-aggregator watermarks and unsourced uploads |
+| Filename | descriptive English snake_case (`joe_hisaishi_concert.jpg`, not `image1.jpg`) |
```bash
-# Create image folder under projects/ (same name as the document)
-mkdir -p "projects/<topic_name>"
-
-# Download images with descriptive filenames
-curl -L -o "projects/<topic_name>/descriptive_name.jpg" "<image_url>"
+mkdir -p "projects/<topic_slug>"
+curl -L -o "projects/<topic_slug>/<descriptive_name>.<ext>" "<image_url>"
```
-**Filename rules**:
-- Use descriptive English names: `joe_hisaishi_concert.jpg`, not `image1.jpg`
-- Lowercase, underscores for spaces
-- Include subject and context: `spirited_away_poster.jpg`, `tokyo_concert_2023.jpg`
-
-### 3.4 Full-Resolution URL Patterns
-
-Common patterns for getting full-resolution images from known sources:
-
-| Source | Thumbnail URL | Full-Resolution URL |
-|--------|--------------|---------------------|
-| Wikimedia | `.../thumb/a/ab/File.jpg/250px-File.jpg` | `.../a/ab/File.jpg` (remove `thumb/` and `/250px-File.jpg`) |
-| Ghibli official | `www.ghibli.jp/gallery/thumb-xxx.png` | `www.ghibli.jp/gallery/xxx.jpg` |
-
---
-## Step 4: Output Summary
+## Hand-off
-After completing Steps 2 and 3, output a brief summary:
+Output a checkpoint, then continue with the main pipeline. The artifacts feed directly into Step 2's `import-sources`:
```markdown
-## Topic Research Complete
-
-**Topic**: <topic_name>
-**Document**: `projects/<topic_name>.md` — [X sections, approximately Y words]
-**Images**: `projects/<topic_name>/` — [N images collected]
-
-| Filename | Source | Description |
-|----------|--------|-------------|
-| ... | ... | ... |
+## ✅ Topic Research Complete
+- [x] Document: `projects/<topic_slug>.md` (N sections)
+- [x] Images: `projects/<topic_slug>/` (N files)
+- [ ] **Next**: SKILL.md Step 2 →
+ `project_manager.py init <project_name> --format <format>`
+ `project_manager.py import-sources projects/<project_name> projects/<topic_slug>.md projects/<topic_slug>/*.* --move`
```
-> From here, the user or main pipeline can use these materials as input for PPT generation (import via `project_manager.py import-sources` or read directly).
-
----
-
-## Notes
-
-- This workflow is **content-gathering only** — it does not create a PPT project, generate SVGs, or produce a design spec
-- The Markdown document should be **PPT-ready**: well-structured, factual, with clear sections that map naturally to presentation slides
-- Always include a **Sources** section in the Markdown for attribution and verifiability
-- When a topic is well-known (e.g., a famous person, a major technology), 2-3 WebSearch + WebFetch rounds are usually sufficient; avoid over-researching
-- For niche topics, more extensive searching may be needed — use judgment
+`<project_name>` is the user's chosen project identifier (typically `<format>_<topic_slug>`, e.g. `ppt169_joe_hisaishi`); `--move` removes the research artifacts from `projects/<topic_slug>` after they are imported.