@cyber-dash-tech/revela 0.17.23 → 0.18.2

package/README.md

@@ -2,7 +2,7 @@
 
 **English** | [中文](README.zh-CN.md)
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-617%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-688%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="560" />
@@ -10,7 +10,7 @@
 
 Revela works from [OpenCode](https://opencode.ai) and Codex to turn source materials, research, data, and intent into trusted, traceable, presentation-ready decision artifacts.
 
-Its narrative workspace records the core elements needed to generate a brief or deck: audience, decision, claims, evidence, sources, risks, objections, and open gaps.
+Its deck-first workspace reviews local materials, saves source-linked research, builds an explicit `deck-plan.md`, generates HTML decks, reviews them, and exports PDF/PPTX/PNG artifacts.
 
 ## Install
 
@@ -34,8 +34,8 @@ To install globally, add the same entry to `~/.config/opencode/opencode.json`.
 Requirements:
 
 - The Codex CLI must be installed and the `codex` command must be available in your shell.
-- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.17.21 mcp` to start the MCP server.
-- For interactive Review actions, `codex exec` must also work because the Review UI uses it for Insight and Comment/Apply Fix requests.
+- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.18.2 mcp` to start the MCP server.
+- For interactive Review actions, `codex exec` must also work because the Review UI uses it for Comment/Apply Fix requests.
 
 Optional preflight:
 
@@ -55,11 +55,11 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 Install Revela through the Codex Git marketplace:
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.21
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.2
 codex plugin add revela@revela
 ```
 
-The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.17.21 mcp` so npm can fetch the published package and its dependencies.
+The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.18.2 mcp` so npm can fetch the published package and its dependencies.
 
 You do not need to run `bun install` inside the Codex marketplace clone.
 
@@ -121,13 +121,13 @@ In Codex, ask Revela to list or switch designs; the plugin uses the active desig
 
 ## Domains
 
-Domains add topic-specific narrative guidance, such as consulting, product, or investor communication. Use them when you want Revela to adapt story framing to a specific context.
+Domains add topic-specific communication guidance, such as consulting, product, or investor communication. Use them when you want Revela to adapt deck framing to a specific context.
 
 ```text
 /revela domain
 ```
 
-In Codex, ask Revela to list or switch domains; the active domain guides narrative framing during init, research, and story work.
+In Codex, ask Revela to list or switch domains; the active domain guides deck framing during init, research, and planning.
 
 ## Quick Start
 
@@ -157,54 +157,54 @@ Revela may ask for references or constraints, then creates and validates the des
 revela, use neon-finance as the design.
 ```
 
-4. Initialize the narrative from local materials. Init grounds the narrative in the workspace and surfaces gaps; it does not replace the research step.
+4. Initialize local material intake. Init scans, extracts, and reviews workspace sources; it does not create a Narrative Vault.
 
 ```text
 revela, help me init this workspace from the local materials.
 ```
 
-5. Research the gaps and bind only source-supported evidence into the narrative.
+5. Research source-linked deck inputs and save findings.
 
 ```text
-revela, research the current gaps and bind only source-supported evidence.
+revela, research the public evidence and examples needed for this deck.
 ```
 
-6. Read Story before rendering to inspect the claim flow, evidence support, caveats, unsupported scope, and open gaps.
-
-```text
-revela, show me the Story before we make the deck.
-```
-
-7. Create or update the deck plan before generating HTML so slide order, chapter structure, evidence trace, caveats, and visual intent are explicit.
+6. Create or update the deck plan before generating HTML so slide order, chapter structure, source links, caveats, and visual intent are explicit.
 
 ```text
 revela, create or update the deck plan before generating HTML.
 ```
 
-8. Make an HTML deck from the current deck plan and canonical narrative.
+7. Make an HTML deck from the current deck plan.
 
 ```text
-revela, make the deck from the current deck plan and narrative.
+revela, make the deck from the current deck plan.
 ```
 
-9. Review the generated deck for traceability, diagnostics, and targeted edits.
+8. Review the generated deck for Artifact QA and targeted edits.
 
 ```text
 revela, review the generated deck.
 ```
 
-10. Export a PDF after deck QA passes.
+9. Export a PDF after deck QA passes.
 
 ```text
 revela, export the deck to PDF.
 ```
 
-11. Export an editable PPTX after deck QA passes.
+10. Export an editable PPTX after deck QA passes.
 
 ```text
 revela, export the deck to PPTX.
 ```
 
+11. Export per-slide PNG files after deck QA passes.
+
+```text
+revela, export the deck to PNG.
+```
+
 ## Review A Deck
 
 Use Review after generating an HTML deck:
@@ -213,7 +213,6 @@ Use Review after generating an HTML deck:
 /revela review --deck
 ```
 
-Review opens a local deck workspace with two main modes:
+Review opens a local deck workspace for QA and targeted edits:
 
-- Insight explains selected slide content: what claim it supports, what evidence backs it, what caveats or gaps remain, and why it matters in the narrative.
 - Comment lets you request targeted edits on the deck, such as layout, copy, hierarchy, spacing, or visual changes.

package/README.zh-CN.md

@@ -2,15 +2,15 @@
 
 [English](README.md) | **中文**
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-617%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-688%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="560" />
 </p>
 
-Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材料、调研、数据和用户意图转成可信、可追踪、可直接用于决策沟通的 narrative artifact。
+Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材料、调研、数据和用户意图转成可信、可追踪、可直接用于决策沟通的 deck artifact。
 
-它的 narrative workspace 会记录生成 brief 或 deck 所需的关键要素：受众、决策目标、论点、论据、资料来源、风险、潜在质疑和待补齐的信息。
+它的 deck-first workspace 会审阅本地资料、保存 source-linked research、生成明确的 `deck-plan.md`、产出 HTML deck，并支持 Review 与 PDF/PPTX/PNG 导出。
 
 ## 安装
 
@@ -34,8 +34,8 @@ Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材
 环境要求：
 
 - 需要已安装 Codex CLI，并且 shell 中可以执行 `codex`。
-- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.17.21 mcp` 启动 MCP server。
-- 如果使用 Review UI 的 Insight、Comment 或 Apply Fix，需要 `codex exec` 可用。
+- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.2 mcp` 启动 MCP server。
+- 如果使用 Review UI 的 Comment 或 Apply Fix，需要 `codex exec` 可用。
 
 可选的安装前检查：
 
@@ -55,11 +55,11 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 通过 Codex Git marketplace 安装 Revela：
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.21
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.2
 codex plugin add revela@revela
 ```
 
-Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.17.21 mcp`，由 npm 获取已发布 package 及其 dependencies。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.2 mcp`，由 npm 获取已发布 package 及其 dependencies。
 
 不需要在 Codex marketplace clone 里运行 `bun install`。
 
@@ -121,13 +121,13 @@ Revela 内置多个 deck design：
 
 ## Domains
 
-Domain 提供特定场景的叙事 guidance，例如 consulting、product 或 investor communication。需要让 Revela 按具体沟通场景调整 story framing 时使用。
+Domain 提供特定场景的沟通 guidance，例如 consulting、product 或 investor communication。需要让 Revela 按具体沟通场景调整 deck framing 时使用。
 
 ```text
 /revela domain
 ```
 
-在 Codex 中，可以直接让 Revela 列出或切换 domain；active domain 会用于 init、research 和 story 阶段的叙事 framing。
+在 Codex 中，可以直接让 Revela 列出或切换 domain；active domain 会用于 init、research 和 deck planning 阶段的 framing。
 
 ## Quick Start
 
@@ -157,54 +157,54 @@ Revela 可能会继续询问参考图、风格约束或禁忌项，然后创建
 revela，使用 neon-finance 作为 design。
 ```
 
-4. 从本地材料初始化 narrative。Init 负责基于 workspace 做 grounding 并暴露 gap；它不替代 research 步骤。
+4. 初始化本地 material intake。Init 会扫描、抽取并审阅 workspace source；它不会创建 Narrative Vault。
 
 ```text
 revela，帮我 init 这个 workspace，先读本地材料。
 ```
 
-5. 针对 gap 做 research，并且只把来源明确支持的 evidence 绑定回 narrative。
+5. 针对 deck 所需输入做 research，并保存带来源的 findings。
 
 ```text
-revela，research 当前 gaps，只绑定 source-supported evidence。
+revela，research 这个 deck 需要的公开证据、案例和 source。
 ```
 
-6. 生成 deck 前先读 Story，检查 claim flow、证据支撑、caveats、unsupported scope 和 open gaps。
-
-```text
-revela，先给我看 Story，再 make deck。
-```
-
-7. 先创建或更新 deck plan，明确 slide 顺序、章节结构、evidence trace、caveats 和 visual intent，再生成 HTML。
+6. 先创建或更新 deck plan，明确 slide 顺序、章节结构、source links、caveats 和 visual intent，再生成 HTML。
 
 ```text
 revela，生成 HTML 前先 create or update deck plan。
 ```
 
-8. 基于当前 deck plan 和 canonical narrative 生成 HTML deck。
+7. 基于当前 deck plan 生成 HTML deck。
 
 ```text
-revela，基于当前 deck plan 和 narrative make deck。
+revela，基于当前 deck plan make deck。
 ```
 
-9. Review 生成后的 deck，检查 traceability、diagnostics，并做定向修改。
+8. Review 生成后的 deck，检查 Artifact QA，并做定向修改。
 
 ```text
 revela，review 生成好的 deck。
 ```
 
-10. QA 通过后导出 PDF。
+9. QA 通过后导出 PDF。
 
 ```text
 revela，把 deck export 成 PDF。
 ```
 
-11. QA 通过后导出可编辑 PPTX。
+10. QA 通过后导出可编辑 PPTX。
 
 ```text
 revela，把 deck export 成 PPTX。
 ```
 
+11. QA 通过后导出每页 PNG。
+
+```text
+revela，把 deck export 成 PNG。
+```
+
 ## Review Deck
 
 生成 HTML deck 后可以进入 Review：
@@ -213,7 +213,6 @@ revela，把 deck export 成 PPTX。
 /revela review --deck
 ```
 
-Review 会打开本地 deck 工作台，主要包含两种模式：
+Review 会打开本地 deck 工作台，用于 QA 和定向修改：
 
-- Insight：解释选中的 slide 内容支持哪个 claim、有哪些 evidence、还剩哪些 caveat 或 gap，以及它在叙事里的作用。
 - Comment：对 deck 发起定向修改，例如 layout、文案、层级、间距或视觉调整。

package/bin/revela.ts

@@ -20,14 +20,13 @@ else {
   try {
     let result: CommandResult
     if (command === "doctor") result = runtime.doctor(options)
-    else if (command === "compile") result = runtime.compileNarrative(options)
-    else if (command === "markdown-qa") result = runtime.markdownQa(options)
     else if (command === "deck-plan") result = runtime.readDeckPlan(options)
     else if (command === "deck-foundation") result = runtime.createDeckFoundation(required(options, ["outputPath", "title", "language"]))
     else if (command === "qa") result = runtime.runDeckQa(required(options, ["file"]))
     else if (command === "review-read") result = runtime.reviewDeckRead(required(options, ["file"]))
     else if (command === "export-pdf") result = runtime.exportPdf(required(options, ["file"]))
     else if (command === "export-pptx") result = runtime.exportPptx(required(options, ["file"]))
+    else if (command === "export-png") result = runtime.exportPng(required(options, ["file"]))
     else if (command === "design-list") result = runtime.designList()
     else if (command === "design-read") result = runtime.designRead(options)
     else if (command === "design-use") result = runtime.designActivate(required(options, ["name"]))
@@ -82,14 +81,13 @@ function printHelp(): void {
 Usage:
   revela mcp
   revela doctor [--workspaceRoot <path>]
-  revela compile [--workspaceRoot <path>]
-  revela markdown-qa [--workspaceRoot <path>] [--scope touched|affected|full] [--strictness authoring|readiness|render]
   revela deck-plan [--workspaceRoot <path>]
   revela deck-foundation --outputPath <path> --title <title> --language <tag> [--workspaceRoot <path>] [--designName <name>] [--mode create|repair] [--overwrite true]
   revela qa --file <path> [--workspaceRoot <path>]
   revela review-read --file <path> [--workspaceRoot <path>] [--format json|markdown]
   revela export-pdf --file <path> [--workspaceRoot <path>]  # deck PDF, or single-page PDF fallback for non-deck HTML
   revela export-pptx --file <path> [--workspaceRoot <path>]
+  revela export-png --file <path> [--workspaceRoot <path>] [--outputDir <path>]
   revela design-list
   revela design-read [--name <design>] [--section <rules|foundation|chart-rules>] [--workspaceRoot <path>]
   revela design-use --name <design>

package/lib/commands/help.ts

@@ -19,7 +19,7 @@ export async function handleHelp(
     `\`\`\`\n` +
     `             R E V E L A   H e l p   v${pkg.version}\n` +
     `\`\`\`\n` +
-    `Turn source materials, research, and narrative state into trusted, traceable decision artifacts.\n\n` +
+    `Turn source materials, research, and deck plans into trusted, traceable decision artifacts.\n\n` +
     `**Current**\n\n` +
     `Status: ${status}\n` +
     `Design: \`${design}\`\n` +
@@ -27,25 +27,25 @@ export async function handleHelp(
     `Run \`/revela enable\` to load Revela context without starting a workflow, or run \`/revela disable\` to pause it. Workflow commands still auto-enable Revela.\n\n` +
     `---\n\n` +
     `**Workflow**\n\n` +
-    `1. \`init\` — discover sources, refresh the graph, ask key questions, and recommend next steps\n` +
-    `2. \`research\` — close evidence gaps and bind support\n` +
-    `3. \`story\` — inspect audience, thesis, claims, evidence, risks, and diagnostics\n` +
-    `4. \`make\` — generate deck or brief from canonical story state\n` +
-    `5. \`review\` — comment on and inspect rendered deck artifacts\n` +
-    `6. \`export\` — export deck artifacts to PDF or PPTX\n\n` +
+    `1. \`init\` — discover and review local source materials\n` +
+    `2. \`research\` — save source-linked findings for the deck objective\n` +
+    `3. \`plan --deck\` — create deck-plan/ from materials, research, and user intent\n` +
+    `4. \`make --deck\` — generate HTML deck from deck-plan/\n` +
+    `5. \`review --deck\` — QA and comment on rendered deck artifacts\n` +
+    `6. \`export\` — export deck artifacts to PDF, PPTX, or PNG\n\n` +
     `---\n\n` +
     `**Commands**\n\n` +
     `\`/revela\`                                      — show REVELA help\n` +
     `\`/revela enable\`                               — enable Revela prompt/context without starting a workflow\n` +
     `\`/revela disable\`                              — disable Revela prompt/context for this session\n` +
-    `\`/revela init\`                                 — start Revela: discover sources, refresh story state, ask key questions, and recommend next steps\n` +
-    `\`/revela research\`                             — research, bind evidence, and reduce story gaps\n` +
-    `\`/revela story [-l language]\`                   — open the read-only story workspace UI\n` +
-    `\`/revela make --deck\`                          — make a deck from story state and deck-plan/\n` +
-    `\`/revela make --brief [file.md]\`                — render executive brief from story state\n` +
-    `\`/revela review --deck\`                        — open deck reading, insight, and comment workspace\n` +
+    `\`/revela init\`                                 — discover local sources, extract materials, and capture deck intent\n` +
+    `\`/revela research\`                             — research and save source-linked deck findings\n` +
+    `\`/revela plan --deck\`                          — create or update deck-plan/ from materials and research\n` +
+    `\`/revela make --deck\`                          — make a deck from deck-plan/\n` +
+    `\`/revela review --deck\`                        — open deck QA and comment workspace\n` +
     `\`/revela export --deck pdf [file.html]\`         — export HTML deck to PDF\n` +
     `\`/revela export --deck pptx [file.html] [--notes]\` — export HTML deck to PPTX\n` +
+    `\`/revela export --deck png [file.html]\`         — export HTML deck to per-slide PNG files\n` +
     `\`/revela design\`                               — list installed designs\n` +
     `\`/revela design --use <name>\`                  — activate a design\n` +
     `\`/revela design --preview [name]\`              — open a design preview in browser\n` +

package/lib/commands/init.ts

@@ -7,6 +7,30 @@ export function buildInitPrompt({
   exists: boolean
   workspaceRoot?: string
 }): string {
+  return `Start Revela deck-first workspace intake.
+
+Goal:
+- Discover local source materials and prepare them for deck planning.
+- Do not create or update revela-narrative/.
+- Treat local files, extraction read views, material reviews, saved research, assets, deck-plan.md, and decks/*.html as the product workspace.
+- End with a concise intake report and the next command: /revela research when external support is needed, or /revela plan --deck when enough inputs exist.
+
+Current state:
+- Legacy/cache state exists: ${exists ? "yes" : "no"}.
+${workspaceRoot ? `- Current workspace root: \`${workspaceRoot}\`` : ""}
+
+Workflow:
+1. Call revela_prepare_local_materials or the OpenCode material tools to scan at max depth 2 and extract Office/PDF sources when supported.
+2. Read direct text/Markdown/CSV sources and extracted read views only for relevant materials.
+3. Record material reviews for every Office/PDF source you rely on. Use "merged", "deferred", "ignored", or "gap" decisions as intake notes only; do not create a product research-gap object.
+4. Check material intake before final reporting and surface scanned-but-unreviewed, unsupported, failed, or text-only limitations.
+5. Ask only high-impact missing intent questions: audience, objective, decision/action, scope, language, source priority, or whether public research is allowed.
+
+Report:
+- Start with "Init: completed" or "Init: needs input".
+- Include local files found, extracted read views, material reviews recorded, source limitations, user intent captured, and next command.
+- Do not ask for slide layout, visual style, export format, or approval during init.`
+
   const mode = exists
     ? `A ${DECKS_STATE_FILE} file already exists as legacy/cache state. Read it first through the revela-decks tool and update it conservatively only for compatibility metadata.`
     : `No ${DECKS_STATE_FILE} file exists yet. Keep this workspace file-native: initialize the Markdown narrative vault before writing narrative meaning and do not create ${DECKS_STATE_FILE}.`

package/lib/commands/png.ts

@@ -0,0 +1,29 @@
+import { resolve } from "path"
+import { exportDeckToPng } from "../pdf/export"
+
+export async function handlePng(
+  rawPath: string,
+  send: (text: string) => Promise<void>,
+  workspaceRoot = process.cwd(),
+): Promise<void> {
+  const requested = rawPath.trim()
+  if (requested.split(/\s+/).filter(Boolean).length > 1) {
+    await send("Usage: `/revela export --deck png [file.html]`.")
+    return
+  }
+
+  const file = requested || "decks/deck.html"
+  try {
+    const result = await exportDeckToPng(resolve(workspaceRoot, file))
+    await send([
+      "**PNG export complete**",
+      "",
+      `Output directory: \`${result.outputDir}\``,
+      `Slides: ${result.slideCount}`,
+      `Duration: ${result.durationMs}ms`,
+    ].join("\n"))
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    await send(`**PNG export failed**\n\n\`\`\`\n${msg}\n\`\`\``)
+  }
+}

package/lib/commands/refine.ts

@@ -18,7 +18,7 @@ export async function handleRefine(
       `File: \`${result.deck.file}\`\n` +
       `${result.stateNote}\n` +
       `URL: ${result.url}\n\n` +
-      `Use Ctrl/Cmd-click in the browser to reference deck elements. The Comment tab sends targeted change comments; the Insight tab reviews the same selection with Source/Purpose cards and does not edit the deck.`
+      `Use Ctrl/Cmd-click in the browser to reference deck elements. The Comment tab sends targeted change comments and applies deck edits after artifact QA.`
     )
   } catch (e: any) {
     await send(`**Review failed:** ${e.message || String(e)}`)

package/lib/commands/research.ts

@@ -7,6 +7,30 @@ export function buildResearchPrompt({
   exists: boolean
   workspaceRoot?: string
 }): string {
+  return `Run Revela deck-first research.
+
+Goal:
+- Gather source-linked findings that help the user's deck objective, current material reviews, existing research files, and deck-plan unresolved inputs.
+- Save useful findings under researches/{topic}/{filename}.md.
+- Do not create, bind, compile, or require revela-narrative/.
+- Do not use canonical evidence binding, narrative research targets, Story, or research-gap lifecycle concepts.
+
+Current state:
+- Legacy/cache state exists: ${exists ? "yes" : "no"}.
+${workspaceRoot ? `- Current workspace root: \`${workspaceRoot}\`` : ""}
+
+Workflow:
+1. Inspect material intake registry/check output, material review files, existing researches/**/*.md, and deck-plan.md when present.
+2. Identify the smallest research tasks needed for the deck: missing market facts, benchmarks, examples, source quotes, images/logos/screenshots, or caveats.
+3. Use external research only for public facts or user-authorized questions. Do not invent URLs, quotes, page references, numbers, or licenses.
+4. Save every useful finding with source URLs/paths, quote/snippet, what it supports, what it does not support, caveat, date checked, and optional image leads.
+5. If a finding is only context, label it as context. Do not promote it to proof.
+
+Report:
+- Start with "Research: completed".
+- List research tasks addressed, saved findings paths, source limitations, unresolved inputs, and whether /revela plan --deck can proceed.
+- If no useful findings were saved, state exactly what source type is needed next.`
+
   const state = exists
     ? `${DECKS_STATE_FILE} exists. Read it through the revela-decks tool before researching.`
     : `${DECKS_STATE_FILE} does not exist yet. Do not start broad internet research; initialize the workspace first with /revela init unless the user supplied a specific research question in chat.`