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(topic-research): make retained-page images fallback-only
hugohe3fd4324c0d5ea
diff --git a/AGENTS.md b/AGENTS.mdindex 232d02a2..76ba95df 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -10,7 +10,7 @@ PPT Master turns source material into natively editable DrawingML PPTX. Generate**Route selection authority**: [`skills/ppt-master/workflows/routing.md`](skills/ppt-master/workflows/routing.md) owns the four top-level artifact routes: Generate PPTX, Create Template, Fill Native PPTX, and Enhance Native PPTX. Child workflows, profiles, stages, and governance documents refine one selected route; they are not competing top-level routes.-- Topic-only or fact-insufficient inputs run [`topic-research`](skills/ppt-master/workflows/stages/topic-research.md) inside the selected Generate profile's source intake; retained webpages are imported as source packages whose embedded images remain source-extracted inventory, while independent image acquisition stays in later resource preparation.+- Topic-only or fact-insufficient inputs run [`topic-research`](skills/ppt-master/workflows/stages/topic-research.md) inside the selected Generate profile's source intake; retained webpages import as text-only evidence, while image acquisition stays in later resource preparation.- Default Generate prepares template candidates internally in Step 3, then confirms the communication contract and free-design/template choice together in Stage 1. Template content stays unread until that confirmation; selected roots are installed before template-aware Stage 2. Quick skips this interaction.- Raw PPTX template plus new material/topic routes to [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md), not the SVG pipeline.- Raw PPTX cannot be consumed as a Generate template workspace; run [`create-template`](skills/ppt-master/workflows/create-template.md) first and return with the generated workspace root as a Stage-1 candidate. Never add Master/Layout structure directly to an existing PPTX/SVG; generate new structured SVG pages from the workspace.diff --git a/docs/faq.md b/docs/faq.mdindex a215c948..3e883d4c 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -10,7 +10,7 @@ Almost anything: **PDF**, **DOCX**, **PPTX**, **EPUB**, **HTML**, **LaTeX**, **R## 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 Generate PPTX route will run its **topic-research stage** to gather the factual baseline and provenance needed for planning. If you provide partial material, the same stage may fill only the factual gaps required by your requested outcome unless you ask for a source-only result. Webpages adopted during research are imported with their embedded images as source packages; Strategist later decides whether to use those images. Independent AI or web image acquisition still follows final confirmation.+Yes. Tell the AI your topic or scenario (e.g. "make a PPT about Hayao Miyazaki", "introduce our new product"). The Generate PPTX route will run its **topic-research stage** to gather the factual baseline and provenance needed for planning. If you provide partial material, the same stage may fill only the factual gaps required by your requested outcome unless you ask for a source-only result. Adopted webpages are imported as text-only evidence; their images are considered only as a one-at-a-time fallback after normal image search fails.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.diff --git a/docs/rules/prompt-style.md b/docs/rules/prompt-style.mdindex 53acf578..877fbc6e 100644--- a/docs/rules/prompt-style.md+++ b/docs/rules/prompt-style.md@@ -102,13 +102,13 @@ Constraint strength and decision ownership are independent. Preserve this chain| Layer | Owns ||---|---|| User / initial materials | Supplied facts/assets, desired outcome, exclusions, and permission boundaries remain authoritative |-| Strategist / plan + preparation | Assess material sufficiency; trigger permitted topic research and retain its adopted webpage source packages; decide the approved content, resources, keys, identity anchors, and exact page roster; record optional capability/expression recommendations; materialize the planned project-local inventory or record an explicit `Needs-Manual` dependency before execution. For icons, prepare a curated project pool with broad semantic fit rather than assigning files to pages |+| Strategist / plan + preparation | Assess material sufficiency; trigger permitted topic research and retain its adopted webpage text evidence; decide the approved content, resources, keys, identity anchors, and exact page roster; record optional capability/expression recommendations; materialize the planned project-local inventory or record an explicit `Needs-Manual` dependency before execution. For icons, prepare a curated project pool with broad semantic fit rather than assigning files to pages || Executor / realization | Use only prepared project-local assets; preserve approved content, resources, and identity anchors; realize them through geometry, composition, hierarchy, and treatment. Fields explicitly labeled `suggestion` or Reference are preferred expression rather than binding selections: Executor may adapt or decline them when content and explicit constraints remain intact. For icons, the complete `<project>/icons/` pool is prepared material; `icons.inventory` is a curated bundled-pool index, not a page-use plan or whitelist, and Executor chooses prepared icons per page without a coverage quota. Sparse local font/color garnish is allowed only while non-structural and non-recurring |**Preparation timing**: In the default pipeline, topic research and import of-its retained webpage source packages may run before final confirmation.-Embedded images in those packages are initial source inventory, not independent-web image acquisition. AI / web / slice acquisition runs only from the+its retained webpage text evidence may run before final confirmation.+Those imports are text-only; their image links are a post-search fallback, not+initial inventory. AI / web / slice acquisition runs only from thecompleted `design_spec.md §VIII` and `spec_lock.md`, after final confirmationand before Executor. Image_Generator, Image_Searcher, and icon-sync toolingexecute Strategist-owned preparation; they are not independent decision owners.diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 2e256a1f..496e86d1 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -616,7 +616,7 @@ One agent may therefore perform several creative stages in sequence, but theirownership boundaries do not merge; checker, exporter, and transcript recorderremain separate deterministic tools.-**Default preparation has two clocks.** Topic Research supplies facts and identifies adopted webpages before final confirmation: it starts immediately for topic-only input, or after supplied material is converted/read when planning-critical factual gaps remain. It supplements only those gaps. After project initialization, the retained URLs or already-converted webpage packages enter `project_manager.py import-sources`; their Markdown, companion files, `image_manifest.json`, and embedded images become source inventory. This materialization is source intake, not independent web image acquisition. When the current AI editor provides an isolated worker with web/fetch access and write access to the declared outputs, the main agent defines the gaps and the worker writes the existing research/provenance artifacts, returning only a receipt; otherwise research runs in the main context. Independent AI / web / slice image acquisition runs only after final confirmation and the completed `design_spec.md §VIII` / `spec_lock.md`, then reaches a terminal status before Executor starts. Strategist also resolves, syncs, and validates a curated project icon pool while authoring the final plan. Image_Generator, Image_Searcher, and icon-sync tooling are preparation mechanisms under Strategist ownership, not independent decision owners. Quick generation uses those preparation mechanisms as needed under the current agent's in-context decisions, without inserting a confirmation gate.+**Default preparation has two clocks.** Topic Research supplies facts and identifies adopted webpages before final confirmation: it starts immediately for topic-only input, or after supplied material is converted/read when planning-critical factual gaps remain. It supplements only those gaps. After project initialization, `project_manager.py import-sources` reads retained URLs from the v1 facts JSON and archives their Markdown as text-only evidence; remote image links remain available only as a one-at-a-time fallback after normal image search fails. When the current AI editor provides an isolated worker with web/fetch access and write access to the declared outputs, the main agent defines the gaps and the worker writes the existing research/provenance artifacts, returning only a receipt; otherwise research runs in the main context. Independent AI / web / slice image acquisition runs only after final confirmation and the completed `design_spec.md §VIII` / `spec_lock.md`, then reaches a terminal status before Executor starts. Strategist also resolves, syncs, and validates a curated project icon pool while authoring the final plan. Image_Generator, Image_Searcher, and icon-sync tooling are preparation mechanisms under Strategist ownership, not independent decision owners. Quick generation uses those preparation mechanisms as needed under the current agent's in-context decisions, without inserting a confirmation gate.**Prepared project-local assets are the boundary.** In the default pipeline, images and other declared resources remain available only when Strategist has selected them, recorded them in the planning artifacts, and made their project paths resolvable or explicitly `Needs-Manual`. Icons are prepared when their SVG files exist under `<project>/icons/`; `spec_lock.icons.inventory` indexes the Strategist's curated synced bundled pool but neither assigns page usage nor exhaustively whitelists execution. Executor chooses among prepared icons per page. In quick generation, active-context resource decisions and their project-local files/manifests replace that planning projection; no general roster or page assignment is written. The current agent may acquire and prepare those resources before SVG authoring. Files elsewhere on disk are not authorized. Missing material returns to the owning preparation step; SVG authoring never silently substitutes it.diff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex eb5b4205..62030896 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -10,7 +10,7 @@## Q: 只有一个主题或想法、没有任何资料,也能生成吗?-可以。直接告诉 AI 你想做的主题或场景(如"做一个关于宫崎骏的 PPT"、"介绍我们公司新产品"),Generate PPTX 路线会运行 **topic-research 阶段**,补齐规划所需的事实基础与来源记录。已有部分材料时,只补实现用户目标仍缺少的事实;如果用户要求只使用原材料,则不做外部补充。研究中最终采用的网页会连同正文图片作为来源包导入,再由 Strategist 判断是否使用;独立的 AI 或网络图片获取仍在最终确认后进行。+可以。直接告诉 AI 你想做的主题或场景(如"做一个关于宫崎骏的 PPT"、"介绍我们公司新产品"),Generate PPTX 路线会运行 **topic-research 阶段**,补齐规划所需的事实基础与来源记录。已有部分材料时,只补实现用户目标仍缺少的事实;如果用户要求只使用原材料,则不做外部补充。研究网页只导入文字;其图片仅在常规搜图失败后按需尝试一张。效果取决于公开网页的覆盖度。如果你已有专业资料(论文、内部文档),直接把文件给 AI 比联网检索更准。diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex c4fee8de..2de5b77e 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -513,7 +513,7 @@ Generate 路由会在加载流程前选定一份运行时权威:[`workflows/ge**快速生成把规划职责合并到当前 Agent。** 来源转换、事实缺口研究和资源准备仍按需运行。当前 Agent 在上下文中自动选择内容、页面清单、mode、visual style 和资源需求;把图片、图标、定性 Structure、原生形状、图表 / 表格、公式与纯字体 / 几何作为完整载体菜单进行一次判断;准备实际选中的用户提供 / 来源抽取 / AI / 网络 / 切片图片、图标及其必要操作 manifest 或来源记录,随后手写 SVG 与所需原生公式 marker;不进入 Strategist、Confirm UI、`design_spec.md`、`spec_lock.md`,也不创建替代规划产物。这些决策在上下文丢失后无法恢复。因此同一 Agent 可以顺序承担多个创作阶段,但阶段权责不会合并;Checker、Exporter 与运行记录器仍是独立的确定性工具。-**默认备料有两个时点。** Topic Research 在最终确认前补充规划所需的事实并识别最终采用的网页:只有主题时立即运行;已有材料时先转换 / 阅读,仅在仍有关键事实缺口时补齐。项目初始化后,保留的 URL 或已经转换的网页来源包进入 `project_manager.py import-sources`,其 Markdown、配套文件、`image_manifest.json` 和正文图片共同成为来源资源;这是来源导入,不是独立的网络图片获取。当前 AI 编辑器若能提供具备网页检索 / 抓取能力并可写入声明输出路径的隔离研究子代理,由主代理定义缺口,子代理写入现有研究及来源产物并只返回回执;否则研究仍在主上下文运行。独立的 AI / web / slice 图片只能在最终确认以及完整的 `design_spec.md §VIII` / `spec_lock.md` 之后获取,并在 Executor 开始前进入终态。Strategist 还会在编写最终方案时解析、同步并验证精选项目图标池。Image_Generator、Image_Searcher 与图标同步工具只是 Strategist 负责的备料机制,不是独立决策者。快速生成则由当前 Agent 根据上下文决策按需使用这些备料机制,不插入确认门禁。+**默认备料有两个时点。** Topic Research 在最终确认前补充规划所需的事实并识别最终采用的网页:只有主题时立即运行;已有材料时先转换 / 阅读,仅在仍有关键事实缺口时补齐。项目初始化后,`project_manager.py import-sources` 从 v1 事实 JSON 读取保留 URL,并把网页 Markdown 归档为纯文字证据;远程图片链接只在常规搜图失败后作为一次一张的兜底。当前 AI 编辑器若能提供具备网页检索 / 抓取能力并可写入声明输出路径的隔离研究子代理,由主代理定义缺口,子代理写入现有研究及来源产物并只返回回执;否则研究仍在主上下文运行。独立的 AI / web / slice 图片只能在最终确认以及完整的 `design_spec.md §VIII` / `spec_lock.md` 之后获取,并在 Executor 开始前进入终态。Strategist 还会在编写最终方案时解析、同步并验证精选项目图标池。Image_Generator、Image_Searcher 与图标同步工具只是 Strategist 负责的备料机制,不是独立决策者。快速生成则由当前 Agent 根据上下文决策按需使用这些备料机制,不插入确认门禁。**项目中已备好的材料就是边界。** 默认流程中,图片和其他声明型资源须由 Strategist 选定、写入规划产物,并保证项目路径可解析或明确标为 `Needs-Manual`。图标 SVG 只要已位于 `<project>/icons/` 就属于已备材料;`spec_lock.icons.inventory` 是 Strategist 已同步精选内置图标池的索引,既不分配具体页面,也不是穷尽式执行白名单。Executor 按页从已备图标中选择。快速生成以当前上下文中的资源决策及其项目级文件 / manifest 代替该规划投影,不写通用资源清单或逐页分配;当前 Agent 可以在手写 SVG 前获取并准备这些资源。其他目录中的文件不构成使用许可。缺料必须回到所属备料步骤;SVG 创作阶段不得静默换料。diff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.mdindex ba638865..3dbf474e 100644--- a/skills/ppt-master/references/image-searcher.md+++ b/skills/ppt-master/references/image-searcher.md@@ -10,7 +10,7 @@ Role definition for the **web image acquisition path**: translate the active res## 1. License Tier Discipline-Every **provider-sourced** image is classified into one of two tiers; anything else is rejected outright. A third tier, `manual`, exists **only** for a user-supplied [`--from-url`](#5-running-image_searchpy) replacement — it is never the result of a provider search accepting an unknown license.+Every **provider-sourced** image is classified into one of two tiers; anything else is rejected outright. A third tier, `manual`, exists **only** for a directly selected [`--from-url`](#5-running-image_searchpy) replacement — it is never the result of a provider search accepting an unknown license.| Tier | Licenses | On-slide attribution ||---|---|---|@@ -125,7 +125,7 @@ python3 scripts/image_search.py "<query>" \| `--max-candidates` | no | `8` | Thumbnail page size. `0` explicitly requests the complete pool and is reserved for debugging / exceptional review, not normal Generate || `--candidate-page` | no | `1` | Ranked thumbnail page to fetch. Page 2 starts at rank 9 with the default page size. Batch rows may override with `candidate_page` || `--promote` | no | — | Download exactly one selected candidate original, enforce the request's size/readability gates, and write provenance |-| `--from-url` | no | — | Manual replace: download a user-supplied image URL into `--filename` (recorded `license_tier: manual`); works without a multimodal model |+| `--from-url` | no | — | Manual replace: download a directly selected image URL into `--filename` (recorded `license_tier: manual`); works without a multimodal model |### Batch mode (≥ 2 web rows) — preferred@@ -213,7 +213,8 @@ Never treat a generic `required_terms` pass as acceptance. For example, matching1. With vision, promote the one passing thumbnail selected under the review-stage contract; this is the first original-image request.2. If none passes and `has_more_candidates` is true, fetch the next ranked page (8 by default). Candidate numbers continue globally, so page 2 starts at `candidate_09`; do not repeat page 1 or download an original.3. After the current pool is exhausted, add materially different query variants for identity wording, official translation, alias, viewpoint, or disambiguation and generate a fresh pool; do not repeat a semantically exhausted query.-4. **manual URL replace (universal, model-agnostic)** — use a user-supplied URL and swap it in:+4. With vision only, if normal search is exhausted, open one relevant retained research page and test one plausible inline-image URL with the same `--from-url` command below. Inspect that single download before trying another; never bulk-download the page or use it as the initial pool.+5. **manual URL replace (universal, model-agnostic)** — use a directly selected URL and swap it in:```bashpython3 scripts/image_search.py --from-url <image-url> --filename <name>.jpg -o <project_path>/images```@@ -225,7 +226,7 @@ Never treat a generic `required_terms` pass as acceptance. For example, matchingthat query row and the active roster to `Sourced` before export; a stale`Needs-Manual` status remains blocking([`executor-web-image.md`](./executor-web-image.md) §1);-5. When the query variants, ranked pages, configured provider chain, and permitted license stages are exhausted and no user-confirmed manual URL is available, mark the row `Needs-Manual`.+6. When the query variants, ranked pages, configured provider chain, permitted license stages, and eligible retained-page fallback are exhausted, mark the row `Needs-Manual`.**This review never opens an acquisition-time interaction** ([`image-base.md`](./image-base.md) §6). Default Generate may build a placeholder and continue to Step 6. Quick Generate finishes all permitted automated strategies, records `Needs-Manual`, and blocks direct export when the unresolved image is required.@@ -318,7 +319,7 @@ Every successful download appends or replaces one entry keyed on `filename`:| `selection_method` | `visual-thumbnail` after promotion from a reviewed preview, or `metadata-ranked` for the strict no-vision / best-only path. It never claims a visual check that did not occur. || `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: `no-attribution` / `attribution-required` for provider-sourced images, or `manual` for a user-supplied `--from-url` replacement (embed only; rights/credit are the user's responsibility). |+| `license_tier` | Drives Executor's attribution decision: `no-attribution` / `attribution-required` for provider-sourced images, or `manual` for a directly selected `--from-url` replacement (embed only; rights/credit are the user's responsibility). || `attribution_required` | Boolean alias of `license_tier == "attribution-required"`. || `attribution_text` | Canonical credit source. Preserve its author/provider/license facts; compress only through §7's visual grammar rather than inventing or dropping identity. || `stage` | `all` by default, or `no-attribution-only` when strict mode is used. |@@ -389,7 +390,7 @@ Executor reads `image_sources.json` per slide that uses a Sourced image. For eac|---|---|| `no-attribution` | Embed `<image>` only || `attribution-required` | Embed `<image>` **and** an inline credit element per §7 |-| `manual` | Embed `<image>` only — user-supplied URL (`--from-url`); verifying usage rights / any required credit is the user's responsibility |+| `manual` | Embed `<image>` only — directly selected URL (`--from-url`); verifying usage rights / any required credit is the user's responsibility |Executor does not interpret raw license strings — `license_tier` is sufficient.diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex d65b9f20..49f49b81 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -58,7 +58,7 @@ Do not force communication intent into one catalog label; Stage 1 records compos| Reference | Preserve the selected direction or role; adapt its realization to context. || Permission / default | An allowed candidate/source boundary or preference; Strategist may leave it unused, with no quota. |-**Authority chain — materials → Strategist preparation → realization.** User inputs set materials/acquisition bounds. Strategist owns sufficiency, gap-filling, and selection: roster/content, resources, page-local visualization/Layout references, fonts, palette anchors, the icon library/stroke plus curated project pool, and crop bans. Topic research and import of its retained webpage source packages may precede confirmation; their embedded images are source-extracted inventory. Independent AI/web/slice acquisition follows final confirmation plus completed §VIII/lock; icons are synced/validated during authoring without page assignment. Before Executor, each resource has a path and terminal/`Needs-Manual` state. Executor owns geometry, composition, hierarchy, spacing, treatment, and per-page choice among prepared icons; it never searches, generates, syncs, invents, or substitutes resources. Missing material/reselection returns upstream. Specificity defines freedom; References flex realization, never selection.+**Authority chain — materials → Strategist preparation → realization.** User inputs set materials/acquisition bounds. Strategist owns sufficiency, gap-filling, and selection: roster/content, resources, page-local visualization/Layout references, fonts, palette anchors, the icon library/stroke plus curated project pool, and crop bans. Topic research and text-only import of its retained webpages may precede confirmation; their image links are only a post-search fallback. Independent AI/web/slice acquisition follows final confirmation plus completed §VIII/lock; icons are synced/validated during authoring without page assignment. Before Executor, each resource has a path and terminal/`Needs-Manual` state. Executor owns geometry, composition, hierarchy, spacing, treatment, and per-page choice among prepared icons; it never searches, generates, syncs, invents, or substitutes resources. Missing material/reselection returns upstream. Specificity defines freedom; References flex realization, never selection.Explicit *must*, *only*, *exactly*, *verbatim*, *do not*, or `no-crop` wording may strengthen only the named property into the appropriate Literal or Semantic requirement. Accepting an AI recommendation keeps the field's default type; it does not promote a Reference or Permission into a Literal requirement.diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.mdindex ad910931..5436231e 100644--- a/skills/ppt-master/scripts/docs/conversion.md+++ b/skills/ppt-master/scripts/docs/conversion.md@@ -55,9 +55,9 @@ Useful options:- `--json` prints a compact machine-readable result after success when theoutput path is known. With multiple inputs, each successful conversion printsits own JSON line after that source finishes.-- `--images all|filtered|none`, `--no-images`, and `--filter-images` map to the- existing PDF image mode. They are intentionally PDF-only until other backends- expose the same behavior natively.+- At the unified `source_to_md.py` entry, `--images all|filtered|none`,+ `--no-images`, and `--filter-images` map to the PDF image mode. The web+ backend exposes its own direct `--no-images` option described below.- Unknown backend-specific flags are passed through to each selected converter.- `-o/--output` selects one Markdown file for one input, or an output directoryfor multiple inputs / directory inputs.@@ -608,7 +608,8 @@ Error: PPTX-to-SVG conversion failed: Invalid DrawingML sRGB color structure## `source_to_md/web_to_md.py`-Convert web pages to Markdown and download images locally.+Convert web pages to Markdown and download images locally by default. Use+`--no-images` to retain remote image links without downloading their files.```bashpython3 scripts/source_to_md/web_to_md.py https://example.com/article@@ -616,6 +617,7 @@ python3 scripts/source_to_md/web_to_md.py https://url1.com https://url2.compython3 scripts/source_to_md/web_to_md.py -f urls.txtpython3 scripts/source_to_md/web_to_md.py https://example.com -o output.mdpython3 scripts/source_to_md/web_to_md.py https://example.com --emit-result /tmp/result.json+python3 scripts/source_to_md/web_to_md.py https://example.com -o evidence.md --no-images```When `curl_cffi` is installed (included in `requirements.txt`), this scriptdiff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex 40ba8779..3123d244 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -51,8 +51,8 @@ request does not explicitly select Quick.🚧 **GATE**: The user has provided a topic / desired outcome and any available initial material.> **Topic-only**: run [`topic-research`](stages/topic-research.md) immediately,-> then use its factual supplement as source content and retain its adopted-> webpage inputs for Step 2 source-package import.+> then use its factual supplement as source content; Step 2 reads retained+> webpage URLs from the facts JSON and imports them as text evidence.When the user provides non-Markdown content, convert immediately through theunified dispatcher. It preserves the backend converters' existing behavior,@@ -88,7 +88,7 @@ After reading direct and converted content, assess factual sufficiency:**Sufficiency test**: research only to avoid inventing, omitting, or leavingunsupported a factual claim the requested outcome requires; file presence orlength is irrelevant. It records the needed facts and adopted webpages. Step 2-imports those webpages and their embedded images as source packages; Step 5+imports those webpages as text-only evidence; Step 5acquires only Strategist-selected independent AI / web / slice assets afterfinal confirmation.@@ -157,12 +157,10 @@ Import source content (choose based on the situation):| Has source files (PDF/MD/etc.) | `python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...>` || User provided text directly in conversation | No import needed — content is already in conversation context; subsequent steps can reference it directly |-When Topic Research ran, include its research pair plus each exact retained URL-or already-converted webpage Markdown package in the same import. Pass only one-form per webpage. `project_manager.py` archives the page Markdown and companion-files, merges its `image_manifest.json`, and synchronizes embedded images into-`<project>/images/`; this is source intake, not `Acquire Via: web` image-acquisition.+When Topic Research ran, include only its research pair. `project_manager.py`+reads the facts JSON's unique `source_url` values, archives each page in+text-only mode, and fails incomplete source reconciliation. It does not add page+images to `<project>/images/`.For PPTX sources, `import-sources` automatically runs the standard intake enrichment:@@ -534,6 +532,8 @@ A deck with only `ai` rows never loads `image-searcher.md`; a deck with only `we> **Default — bounded multimodal web thumbnail selection**: when either the current agent or an available isolated reviewer can inspect images, add `--save-candidates` to the single or batch web command. Author explicit `query_variants` for materially different official translations, spellings, aliases, or Chinese names; the tool aggregates and deduplicates them, then saves only the first ranked page (8 previews by default), writes `candidates/<stem>/review_sheet.jpg`, marks the batch row `Needs-Selection`, and downloads no original. Run [`web-image-review`](stages/web-image-review.md): dispatch exactly one isolated reviewer for all current sheets when supported, passing only each row's locked Reference/Crop Policy plus candidate sidecar/sheet paths; otherwise the active image owner reads that stage and reviews locally. Only a stage-selected passing candidate may be used with `--promote` to download one original and write provenance (pass the same `--batch images/image_queries.json` to reconcile its row to `Sourced`). If none passes and `has_more_candidates` is true, advance that row to `next_candidate_page` before changing the query. Only after the pool is exhausted may the row receive materially different query variants and return to `Pending`. When no available context has vision, omit `--save-candidates`: best-only mode may download only a strict metadata-verified candidate, records `selection_method: metadata-ranked`, and otherwise stops at `Needs-Manual` without claiming visual confirmation.+> **Retained-page fallback**: only after that normal search is exhausted, a vision-capable image owner may open one relevant research page and test one inline-image URL at a time with `--from-url`. Never use retained pages as the initial pool or bulk-download them; without vision, skip this fallback.+> **Default — short provider query (may override for a complete entity name or necessary disambiguation)**: keep §VIII `Reference` as the locked subject/focal/crop intent and author a separate concrete `image_queries.json.query`. Search/review never rewrites the Design Spec or lock to fit a candidate.> **Default — one sheet for compatible AI spots or decorative lettering elements (may override for different cell shape, detail, quality, or semantics)**: prefer one grid sheet for a same-family set; independent `ai` rows remain valid. A lettering sheet records every exact stable string and contains no scene or page chrome. When selected, choose a grid matching the planned cells, keep the sheet unplaced, and place/project each transparent `slice` row. Contract: [image-generator.md](../references/image-generator.md) §4.3.diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.mdindex c19c2089..179ffa1d 100644--- a/skills/ppt-master/workflows/profiles/quick-generate.md+++ b/skills/ppt-master/workflows/profiles/quick-generate.md@@ -121,8 +121,8 @@ After reading every direct and converted source, assess factual sufficiency:**Sufficiency test**: research only when the requested outcome would otherwiserequire inventing, omitting, or leaving unsupported an externally verifiableclaim. File presence or length does not establish sufficiency. Research records-the needed facts and adopted webpages. Their embedded images enter the imported-source inventory; independent AI / web / slice acquisition remains part of the+the needed facts and adopted webpages. Those pages import as text-only evidence;+independent AI / web / slice acquisition remains part of theresource preparation below.**Conditional video-delivery context**: when the intended use is recorded,@@ -181,15 +181,12 @@ research pair together:```bashpython3 ${SKILL_DIR}/scripts/project_manager.py import-sources \<project_path> <source_files_or_dirs...> [<converted_outputs...>] \- [<retained_URLs_or_converted_webpage_paths...>] \[projects/<research_slug>.md projects/<research_slug>.facts.json]```-For each retained webpage, pass either its exact URL or an existing converted-Markdown package, never both. `project_manager.py` archives the page Markdown-and companion files, merges its `image_manifest.json`, and synchronizes-embedded images into `<project>/images/`. Treat them as source-extracted-inventory rather than `Acquire Via: web` acquisitions.+The facts JSON owns retained URLs. `project_manager.py` imports them+automatically in text-only mode and fails incomplete reconciliation; do not+repeat URLs or add page images to `<project>/images/`.Only inputs already under the repository's `projects/` tree move into thetarget project; every external path is copied and remains untouched. Use@@ -440,6 +437,8 @@ strategy.Every required file-backed resource must reach a usable terminal state beforeits page. Web `Needs-Selection` blocks until one thumbnail is promoted or thebounded ranked pages and materially different query variants are exhausted;+only then may a vision-capable owner test one retained-page image URL at a time+with `--from-url`; never bulk-download or use those pages as the initial pool.`Needs-Manual` blocks even when an unverified file exists. With no visualcapability, only the strict metadata-ranked web path may reach `Sourced`, andits provenance must say `selection_method: metadata-ranked` rather than implydiff --git a/skills/ppt-master/workflows/stages/topic-research.md b/skills/ppt-master/workflows/stages/topic-research.mdindex 2e3fc649..c8655878 100644--- a/skills/ppt-master/workflows/stages/topic-research.md+++ b/skills/ppt-master/workflows/stages/topic-research.md@@ -1,5 +1,5 @@----description: Generate source-intake stage that fills factual gaps and retains adopted webpage source packages before planning or direct SVG authoring.+description: Generate source-intake stage that fills factual gaps and retains adopted webpage text evidence before planning or direct SVG authoring.---# Topic Research Stage@@ -9,17 +9,15 @@ description: Generate source-intake stage that fills factual gaps and retains ad> consumes the same output. Run immediately for topic-only input, or after> supplied material is converted and read when it leaves planning-critical> factual gaps. Output is a research supplement plus stable fact provenance for-> project import; its retained webpage URLs are imported as source packages in+> project import; its retained webpage URLs are imported as text evidence in> the active Generate profile's project-initialization handoff.This stage supplies facts needed to build the requested deck and preserves thewebpages actually adopted during that research. It makes no deck imageselection and performs no independent image search or generation. During thehandoff, `project_manager.py import-sources` converts each retained URL, archives-its Markdown and companion files, and synchronizes embedded main-content images-into the project resource pool. Those files are source-extracted assets, not-`Acquire Via: web` acquisitions. Default Generate still resolves their use in-the final Strategist plan; Quick Generate resolves their use in active context.+its Markdown as text evidence, and retains remote inline-image links without+downloading them. Those links are not an initial image pool.## When to Run@@ -75,7 +73,7 @@ confirmation stage.**Hard rule — isolate retrieval, not research**: Raw page content and fetch transcripts stay in the worker context. The 250-word limit applies only to its chat receipt: return `status`, exact artifact paths, covered/unresolved gap counts, external-fact count, and material conflicts. It does not cap or replace the two artifacts. After validation and import, the active content owner reads the complete imported research supplement and fact-provenance JSON into the main context before planning or direct SVG authoring; never use the receipt or validation summary as content.-**Validation**: Before import, the main agent verifies both exact files exist, the Markdown contains `## Research Brief` and `## Sources`, the JSON parses with schema `ppt-master.fact-provenance.v1` and unique sequential IDs, and the two files agree. Return an invalid pair to the research worker for owning-artifact repair; use main-context web research only when isolated execution is unavailable.+**Validation**: Before import, the main agent verifies both exact files exist, the Markdown contains `## Research Brief` and no source list or URL, the JSON parses with schema `ppt-master.fact-provenance.v1` and unique sequential IDs, and the two files agree. Return an invalid pair to the research worker for owning-artifact repair; use main-context web research only when isolated execution is unavailable.---@@ -85,11 +83,11 @@ Use the web search and fetch tools available in the active research context. An```bashpython3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL> \- -o projects/<research_slug>_web_sources/<source_slug>.md+ -o projects/<research_slug>_web_sources/<source_slug>.md --no-images```-Preserve the resulting Markdown, conversion profile, and companion `_files/`-directory for the handoff instead of fetching the same URL again.+Preserve the resulting Markdown and conversion profile for research. Remote+inline-image links remain in the Markdown; no image files are downloaded.| Phase | Action ||---|---|@@ -104,12 +102,10 @@ directory for the handoff instead of fetching the same URL again.| 3 | Reputable reporting or analysis when primary evidence is unavailable || Avoid | Unsourced reposts, unverifiable summaries, and stock-aggregator pages |-**Retained webpage boundary**: End `## Sources` with every exact webpage URL-that materially supports a retained fact or whose embedded main-content visual-was encountered while researching the declared gaps and may serve the requested-outcome. Do not add unopened search results, orientation-only hits, or new pages-found through a separate image-search pass. A retained page is a pending source-package, not a deck-image selection.+**Retained webpage boundary**: Record a page URL only in the matching fact's+`source_url`, and only when it materially supports that retained fact. Do not+retain a page merely because its images may be useful, and do not add unopened+search results or pages found through a separate image-search pass.**Stop condition**: stop when every declared gap has enough sourced evidence forthe active content owner to decide whether and how to include it. Do not expand@@ -127,9 +123,9 @@ Write two artifacts under `projects/`:| Research supplement | `projects/<research_slug>.md` || Fact provenance | `projects/<research_slug>.facts.json` |-**Hard rule — location and preservation**: write both files under `projects/`, never the repository root. Do not overwrite an existing user file; choose a new research stem instead. Do not create a parallel research-image manifest or copy embedded images into an ad hoc folder; the source-package import owns that materialization. Preserve any webpage package already produced by the no-web-tools fallback at its declared output path.+**Hard rule — location and preservation**: write both files under `projects/`, never the repository root. Do not overwrite an existing user file; choose a new research stem instead. Do not create a research-image manifest or download embedded images.-Begin the research Markdown with a compact `## Research Brief` containing the supplied-material baseline, declared gaps, audience / intent already known, and requested outcome. Organize the body by gap, include concrete facts only, flag material conflicts, and end with `## Sources` listing each retained page title and exact URL once.+Begin the research Markdown with a compact `## Research Brief` containing the supplied-material baseline, declared gaps, audience / intent already known, and requested outcome. Organize the body by gap, include concrete facts only, flag material conflicts, and cite claims by `fact_id`. Do not add `## Sources` or URLs; the facts JSON is the only URL authority.Write every externally sourced claim that may enter the deck to `<research_slug>.facts.json` with a stable sequential ID, especially quantitative, date, ranking, attribution, and named-entity claims. Do not include user-supplied claims or invented scenario values. When no external claim is retained, write the schema with an empty `facts` array.@@ -156,27 +152,27 @@ IDs are immutable within the file. Correct a claim under the same ID; never reus## Hand-off-After project initialization, import the research pair, user-supplied sources,-and one copy of every retained webpage source through the active profile's-source intake. Pass an exact URL when the page has not yet been converted; pass-its existing converted Markdown path when the no-web-tools fallback already-created the webpage package. Never pass both forms for the same page.+After project initialization, import the research pair and user-supplied+sources. `project_manager.py` reads unique `source_url` values from the v1 facts+JSON automatically; do not repeat those URLs in the command or Markdown.```bashpython3 ${SKILL_DIR}/scripts/project_manager.py import-sources \projects/<project_name> [<source_paths...>] \- [<retained_URLs_or_converted_webpage_paths...>] \projects/<research_slug>.md projects/<research_slug>.facts.json```-For retained URLs, `project_manager.py` invokes the existing webpage converter,-archives the webpage Markdown plus conversion profile, preserves its companion-`_files/` package and `image_manifest.json`, and synchronizes embedded images-into `<project>/images/`. These imported files are source-extracted inventory;-they do not create `image_sources.json`, run `web-image-review`, or consume an-`Acquire Via: web` choice. The active image owner may later select or ignore-them like other document-extracted images. Independent AI / web / slice-acquisition remains in the owning profile's later resource-preparation phase.+For retained URLs, `project_manager.py` invokes the webpage converter in+text-only mode and fails the import when any registered URL cannot be archived.+It never copies page images into `<project>/images/`. A URL explicitly supplied+as initial material keeps normal source-import behavior even when a later fact+cites it; text-only mode applies only to URLs auto-expanded from the facts JSON.++Only after normal web-image providers, ranked thumbnail pages, and materially+different queries fail may an image owner with visual capability open one+relevant retained page, choose one inline-image URL, download it with the+existing `image_search.py --from-url`, and inspect it. Try another only after+rejection; never bulk-download a page. Without vision, skip this fallback.The imported research pair remains the compact evidence-facing contentauthority, not a locked presentation contract. Default Generate has Strategist@@ -184,15 +180,14 @@ read both files completely before confirmation and use them with the importedsource inventory to select the content, page roster, and image resource plan.Quick Generate has the current agent do the same before its active-contextcontent, design, and resource decisions. Reopen an imported webpage Markdown-only when its raw detail is needed; do not bulk-read it merely because the-source package was retained.+only for missing factual detail or the post-exhaustion single-image fallback.```markdown## ✅ Topic Research Complete- [x] Research execution: <isolated worker | main-context fallback>- [x] Research supplement: `projects/<research_slug>.md` (N declared gaps covered)- [x] Fact provenance: `projects/<research_slug>.facts.json` (N external facts)-- [x] Artifact contract validated: `## Research Brief`, `## Sources`, `ppt-master.fact-provenance.v1`, unique sequential IDs, and Markdown/JSON agreement-- [x] Retained webpage inputs: N exact URL(s) or already-converted source package(s); no independent image search/generation or deck-image selection-- [ ] **Next**: Default returns to [`generate-pptx`](../generate-pptx.md) Step 2; Quick returns to [`quick-generate`](../profiles/quick-generate.md) §2. Import all source artifacts and retained webpage packages, then fully read the imported research pair before planning or direct SVG authoring+- [x] Artifact contract validated: `## Research Brief`, no Markdown source list, `ppt-master.fact-provenance.v1`, unique sequential IDs, and Markdown/JSON agreement+- [x] Retained webpage URLs: N unique `source_url` values in the facts JSON; no page images downloaded+- [ ] **Next**: Default returns to [`generate-pptx`](../generate-pptx.md) Step 2; Quick returns to [`quick-generate`](../profiles/quick-generate.md) §2. Import the source artifacts plus research pair, then fully read the imported pair before planning or direct SVG authoring```