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): fetch adopted page packages on demand
hugohe3201c3425b713
diff --git a/AGENTS.md b/AGENTS.mdindex 76ba95df..6c192544 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 import as text-only evidence, while 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; its facts URLs are not auto-expanded. After normal image search fails, one relevant webpage may be fetched as a source package and only reviewed selections enter the runtime image pool.- 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 3e883d4c..6f45af63 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. 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.+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. Project import does not bulk-fetch the adopted webpage URLs recorded in provenance. After normal image search fails, one relevant page may be fetched with its companion images for review, and only selected files enter the deck's image pool.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 877fbc6e..5503e8a0 100644--- a/docs/rules/prompt-style.md+++ b/docs/rules/prompt-style.md@@ -102,16 +102,18 @@ 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 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 |+| Strategist / plan + preparation | Assess material sufficiency; trigger permitted topic research and retain its research/provenance pair without expanding adopted webpage URLs; 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 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 the+its two-artifact research pair may run before final confirmation. Facts JSON+URLs are not auto-expanded. AI / web / slice acquisition runs only from thecompleted `design_spec.md §VIII` and `spec_lock.md`, after final confirmation-and before Executor. Image_Generator, Image_Searcher, and icon-sync tooling-execute Strategist-owned preparation; they are not independent decision owners.+and before Executor. Only after normal image search fails may one relevant+adopted page become a Markdown + companion-image source package; review it and+promote accepted files individually, never the whole package. Image_Generator,+Image_Searcher, and icon-sync tooling execute Strategist-owned preparation;+they are not independent decision owners.**Post-motion sound exception**: optional transition/object sound is not apage-authoring ingredient and never enters Strategist planning,diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 496e86d1..95e53cf4 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, `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.+**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` imports the research/provenance pair as ordinary files and never expands the v1 facts JSON's `source_url` values. 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. If normal image search is exhausted, one relevant adopted URL may be fetched as a Markdown + companion-image source package; the image owner reviews that package and promotes only accepted files into the runtime image pool. 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 62030896..706dc80d 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -10,7 +10,7 @@## Q: 只有一个主题或想法、没有任何资料,也能生成吗?-可以。直接告诉 AI 你想做的主题或场景(如"做一个关于宫崎骏的 PPT"、"介绍我们公司新产品"),Generate PPTX 路线会运行 **topic-research 阶段**,补齐规划所需的事实基础与来源记录。已有部分材料时,只补实现用户目标仍缺少的事实;如果用户要求只使用原材料,则不做外部补充。研究网页只导入文字;其图片仅在常规搜图失败后按需尝试一张。+可以。直接告诉 AI 你想做的主题或场景(如"做一个关于宫崎骏的 PPT"、"介绍我们公司新产品"),Generate PPTX 路线会运行 **topic-research 阶段**,补齐规划所需的事实基础与来源记录。已有部分材料时,只补实现用户目标仍缺少的事实;如果用户要求只使用原材料,则不做外部补充。项目导入不会根据来源记录中的网页 URL 批量抓取材料;常规搜图失败后,才会按需获取一个相关网页及其图片资源包,审阅后只把选中的图片加入项目图池。效果取决于公开网页的覆盖度。如果你已有专业资料(论文、内部文档),直接把文件给 AI 比联网检索更准。diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex 2de5b77e..523eb9b2 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 在最终确认前补充规划所需的事实并识别最终采用的网页:只有主题时立即运行;已有材料时先转换 / 阅读,仅在仍有关键事实缺口时补齐。项目初始化后,`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 根据上下文决策按需使用这些备料机制,不插入确认门禁。+**默认备料有两个时点。** Topic Research 在最终确认前补充规划所需的事实并识别最终采用的网页:只有主题时立即运行;已有材料时先转换 / 阅读,仅在仍有关键事实缺口时补齐。项目初始化后,`project_manager.py import-sources` 只把研究 / 来源记录对当作普通文件导入,不展开 v1 事实 JSON 里的 `source_url`。当前 AI 编辑器若能提供具备网页检索 / 抓取能力并可写入声明输出路径的隔离研究子代理,由主代理定义缺口,子代理写入现有研究及来源产物并只返回回执;否则研究仍在主上下文运行。独立的 AI / web / slice 图片只能在最终确认以及完整的 `design_spec.md §VIII` / `spec_lock.md` 之后获取,并在 Executor 开始前进入终态。常规搜图穷尽后,图片负责人可以按需获取一个相关网页的 Markdown 与伴随图片资源包,审阅后只把选中的文件提升到运行时图池。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 3dbf474e..9077b3ff 100644--- a/skills/ppt-master/references/image-searcher.md+++ b/skills/ppt-master/references/image-searcher.md@@ -10,13 +10,13 @@ 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 directly selected [`--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 replacement from [`--from-url`](#5-running-image_searchpy) or an adopted-page source package — it is never the result of a provider search accepting an unknown license.| 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 |-| `manual` | User-supplied via `--from-url` (license unverified) | None — verifying rights / any credit is the user's responsibility |+| `manual` | Directly selected URL or adopted-page package image (license unverified) | None — verifying rights / any credit is the user's responsibility |**Forbidden — auto-rejected licenses**:@@ -213,7 +213,7 @@ 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. 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.+4. With vision only, if normal search is exhausted, select one relevant adopted `source_url` and follow [`topic-research`](../workflows/stages/topic-research.md) § Hand-off to fetch its Markdown + companion-image source package. Review that package, copy only one passing image into `<project>/images/`, and reconcile the query row plus `image_sources.json` from the selected `image_manifest.json` entry with `license_tier: manual`. Fetch another page only when the current package has no passing image; never auto-expand facts URLs or promote the whole package.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@@ -226,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);-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`.+6. When the query variants, ranked pages, configured provider chain, permitted license stages, and eligible adopted-page package 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.@@ -319,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 directly selected `--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 URL/source-package 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. |@@ -390,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 — directly selected URL (`--from-url`); verifying usage rights / any required credit is the user's responsibility |+| `manual` | Embed `<image>` only — directly selected URL or adopted-page package image; verifying usage rights / any required credit is the user's responsibility |Executor does not interpret raw license strings — `license_tier` is sufficient.@@ -404,7 +404,7 @@ In addition to the shared checkpoint in [`image-base.md`](./image-base.md) §10:- [ ] Every required web row is `Sourced` with a downloaded original at `project/images/<filename>` OR is marked `Needs-Manual`; `Needs-Selection` remains incomplete- [ ] Each multimodal `Sourced` web image was selected from a bounded ranked thumbnail page and only its winner original was downloaded; a no-pass page advanced through remaining pages before query replacement. Without vision, only strict metadata candidates may become `Sourced`, with `selection_method: metadata-ranked`; unresolved or visually unprovable intent becomes `Needs-Manual` without pretending a visual check occurred-- [ ] Each `Sourced` row has a manifest entry with valid `license_tier` and non-empty `attribution_text` (except `manual` `--from-url` rows, which carry no `attribution_text`)+- [ ] Each `Sourced` row has a manifest entry with valid `license_tier` and non-empty `attribution_text` (except `manual` directly selected rows, which carry no `attribution_text`)- [ ] Any `attribution-required` image has visible author + license credit in every SVG that references it- [ ] `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 49f49b81..de3b6558 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 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.+**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 two-artifact research pair may precede confirmation; facts URLs are not auto-expanded. Only after normal image search fails may one adopted webpage become a reviewable Markdown + companion-image source package, with accepted files promoted individually. 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/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex 3123d244..38befd72 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; Step 2 reads retained-> webpage URLs from the facts JSON and imports them as text evidence.+> then use its research pair as source content; Step 2 imports that pair without+> expanding the facts JSON's webpage URLs.When the user provides non-Markdown content, convert immediately through theunified dispatcher. It preserves the backend converters' existing behavior,@@ -87,8 +87,8 @@ 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 or-length is irrelevant. It records the needed facts and adopted webpages. Step 2-imports those webpages as text-only evidence; Step 5+length is irrelevant. It records the needed facts and adopted webpage URLs in+the research pair. Step 2 fetches no adopted page; Step 5acquires only Strategist-selected independent AI / web / slice assets afterfinal confirmation.@@ -106,7 +106,7 @@ final confirmation.> Browser-based live preview cannot render EMF (will show blank) — this is expected;> the PPTX output is the source of truth.-**✅ Checkpoint — Confirm source content, retained webpage inputs, and any factual supplement are ready, proceed to Step 2.**+**✅ Checkpoint — Confirm source content and any factual supplement/provenance pair are ready, proceed to Step 2.**---@@ -158,9 +158,8 @@ Import source content (choose based on the situation):| 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 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/`.+imports the facts JSON as an ordinary file and never expands its `source_url`+values, so project initialization fetches no adopted page.For PPTX sources, `import-sources` automatically runs the standard intake enrichment:@@ -532,7 +531,7 @@ 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.+> **Adopted-page fallback**: only after that normal search is exhausted, a vision-capable image owner may follow [`topic-research`](stages/topic-research.md) § Hand-off to fetch one relevant `source_url` as a Markdown + companion-image source package, review it, and copy only accepted files into `<project>/images/`. Never auto-expand facts URLs or promote the whole package; 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.diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.mdindex 179ffa1d..2960d587 100644--- a/skills/ppt-master/workflows/profiles/quick-generate.md+++ b/skills/ppt-master/workflows/profiles/quick-generate.md@@ -92,7 +92,7 @@ Prepare source facts before initialization:| Input | Action ||---|---|-| Topic or requirements without supporting facts | Run [`topic-research`](../stages/topic-research.md) immediately and retain its Markdown supplement, fact-provenance JSON, and adopted webpage inputs for import |+| Topic or requirements without supporting facts | Run [`topic-research`](../stages/topic-research.md) immediately and retain its Markdown supplement plus fact-provenance JSON; adopted webpage URLs remain inside that pair and are not import inputs || One or more PNG / JPEG / WebP files representing page frames under Image to PPTX | Do not call `source_to_md.py`; normalize single-page files and multi-frame contact sheets into the canonical ordered frame roster through that profile, then import the originals below || PDF / DOCX / Office document / XLSX / XLSM / PPTX / EPUB / HTML / LaTeX / RST / web URL | Run `python3 ${SKILL_DIR}/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...]` || CSV / TSV | Read directly as a plain-text table source |@@ -121,9 +121,9 @@ 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. Those pages import as text-only evidence;-independent AI / web / slice acquisition remains part of the-resource preparation below.+the needed facts and adopted webpage URLs in its research pair. Project+initialization fetches none of those pages; independent AI / web / slice+acquisition remains part of the resource preparation below.**Conditional video-delivery context**: when the intended use is recorded,self-running, or video-directed—or an explicit final/literal narration script@@ -184,9 +184,11 @@ python3 ${SKILL_DIR}/scripts/project_manager.py import-sources \[projects/<research_slug>.md projects/<research_slug>.facts.json]```-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/`.+The facts JSON is the sole URL authority, not a download queue.+`project_manager.py` imports it as an ordinary file and never expands its+`source_url` values. If normal web-image search is exhausted, follow+[`topic-research`](../stages/topic-research.md) § Hand-off to fetch one relevant+webpage package, review it, and copy only accepted images into the runtime pool.Only inputs already under the repository's `projects/` tree move into thetarget project; every external path is copied and remains untouched. Use@@ -437,8 +439,9 @@ 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.+only then may a vision-capable owner fetch one adopted-page source package,+review its companion images, and promote only accepted files; never auto-expand+facts URLs or use those packages 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 c8655878..937f98ad 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 text evidence before planning or direct SVG authoring.+description: Generate source-intake stage that fills factual gaps and records adopted webpage provenance before planning or direct SVG authoring.---# Topic Research Stage@@ -8,16 +8,16 @@ description: Generate source-intake stage that fills factual gaps and retains ad> Default Generate hands its output to Strategist; Quick Generate's main agent> 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 text evidence in-> the active Generate profile's project-initialization handoff.+> factual gaps. Output is exactly a research supplement plus stable fact+> provenance for project import. Adopted webpage URLs remain in the provenance+> file and are not expanded during the project-initialization handoff.-This stage supplies facts needed to build the requested deck and preserves the+This stage supplies facts needed to build the requested deck and records thewebpages actually adopted during that research. It makes no deck image-selection and performs no independent image search or generation. During the-handoff, `project_manager.py import-sources` converts each retained URL, archives-its Markdown as text evidence, and retains remote inline-image links without-downloading them. Those links are not an initial image pool.+selection and performs no independent image search or generation. The facts+JSON is provenance, not a page-download queue: `project_manager.py+import-sources` imports the research pair without fetching its `source_url`+values. A page may be fetched later only for the bounded image fallback below.## When to Run@@ -102,7 +102,7 @@ inline-image links remain in the Markdown; no image files are downloaded.| 3 | Reputable reporting or analysis when primary evidence is unavailable || Avoid | Unsourced reposts, unverifiable summaries, and stock-aggregator pages |-**Retained webpage boundary**: Record a page URL only in the matching fact's+**Adopted webpage boundary**: Record a page URL only in the matching fact's`source_url`, and only when it materially supports that retained fact. Do notretain a page merely because its images may be useful, and do not add unopenedsearch results or pages found through a separate image-search pass.@@ -153,8 +153,8 @@ IDs are immutable within the file. Correct a claim under the same ID; never reus## Hand-offAfter 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.+sources. The facts JSON is imported as an ordinary source file; its `source_url`+values are never expanded, so this command performs no webpage retrieval.```bashpython3 ${SKILL_DIR}/scripts/project_manager.py import-sources \@@ -162,25 +162,35 @@ python3 ${SKILL_DIR}/scripts/project_manager.py import-sources \projects/<research_slug>.md projects/<research_slug>.facts.json```-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.+If planning later exposes a required factual gap, return to this stage and+repair the research supplement plus facts JSON before continuing. Do not let+Strategist or Quick consume a newly fetched claim without updating that pair.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.+different queries fail may an image owner with visual capability select one+relevant `source_url` from the facts JSON and fetch that one webpage package:++```bash+python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py "<source_url>" \+ -o <project_path>/sources/<source_slug>.md+```++This writes the page Markdown, conversion profile, and companion+`<source_slug>_files/` image package with `image_manifest.json`. Review that+package, then copy only accepted image files into `<project_path>/images/`;+leave every rejected or unused file in the source package. Fetch another page+only after the current package has no usable image. Do not pass the URL to+`project_manager.py import-sources`, which would promote every companion image+into the runtime pool. Without vision, skip this fallback and retain+`Needs-Manual`.The imported research pair remains the compact evidence-facing contentauthority, not a locked presentation contract. Default Generate has Strategistread 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-context-content, design, and resource decisions. Reopen an imported webpage Markdown-only for missing factual detail or the post-exhaustion single-image fallback.+content, design, and resource decisions. A webpage Markdown enters the project+only through the post-exhaustion single-page image fallback above.```markdown## ✅ Topic Research Complete@@ -188,6 +198,6 @@ only for missing factual detail or the post-exhaustion single-image 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`, 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+- [x] Adopted webpage URLs: N unique `source_url` values in the facts JSON; no webpage automatically imported and no image copied into the runtime pool- [ ] **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```