@cyber-dash-tech/revela 0.8.7 → 0.8.9

package/README.md

@@ -20,8 +20,8 @@ Enable it for the current session, assign a presentation task, and the agent can
 - injects a presentation-specific system prompt into your current agent with `/revela enable`
 - builds that prompt from 3 layers: core skill, active domain, active design
 - supports workspace document discovery, transparent text extraction for `.pdf`, `.docx`, `.pptx`, and `.xlsx`, and cached embedded-material extraction for those formats
-- uses workspace `DECKS.json` as machine-readable deck memory, slide spec, and prewrite readiness state
-- blocks premature writes to `decks/*.html` until the active deck is marked structurally ready
+- keeps track of deck context, slide structure, sources, and readiness across the current workspace
+- checks for missing context, weak evidence, and incomplete structure before writing `decks/*.html`
 - runs fast design compliance checks whenever the agent writes, patches, or edits `decks/*.html`
 - opens a visual comment editor for existing decks so users can Ctrl/Cmd-click elements and send precise edit requests back to OpenCode
 - exports finished decks to PDF and editable PPTX
@@ -89,7 +89,7 @@ Enable Revela in the current session:
 /revela enable
 ```
 
-Initialize workspace deck memory when starting in a new project:
+Prepare the workspace when starting a new deck project:
 
 ```text
 /revela init
@@ -109,7 +109,7 @@ Then give the agent a deck task:
 Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main market drivers, use the active design faithfully, and save the result to decks/humanoid-robotics.html.
 ```
 
-Before the agent writes `decks/humanoid-robotics.html`, it must update `DECKS.json` through the `revela-decks` tool with the active deck, confirmed slide specs, layouts, components, and computed `writeReadiness.status: ready`. You can ask for an explicit readiness check at any time:
+If the task depends on sources, research, or a confirmed slide plan, you can ask Revela to review whether the deck has enough context, structure, and evidence before writing:
 
 ```text
 /revela review
@@ -137,8 +137,8 @@ Disable presentation mode when done:
 /revela enable                   enable presentation mode for this session
 /revela disable                  disable presentation mode
 
-/revela init                     initialize or refresh workspace DECKS.json
-/revela review                   review current deck readiness before writing HTML
+/revela init                     prepare the workspace for a deck project
+/revela review                   check whether context, structure, and evidence are ready
 /revela remember <text>          save an explicit user/workflow preference
 /revela edit                     open visual editor for the only deck in decks/
 
@@ -178,56 +178,22 @@ The enabled or disabled state is session-level only.
 
 ---
 
-## DECKS.json Memory And Readiness Gate
+## Recommended Workflow
 
-Revela uses a workspace-root `DECKS.json` file for cross-session continuity and deck production control. It is intended for tools and the LLM, not manual editing.
+Use Revela as a guided deck-production mode:
 
-It has two jobs:
+1. Enable Revela with `/revela enable`.
+2. Run `/revela init` when starting in a new project or when the workspace has changed significantly.
+3. Choose a design or domain if the default style is not right.
+4. Give the agent a clear deck task: audience, goal, language, number of slides, source requirements, and output path.
+5. Use `/revela review` before writing if the deck needs research, citations, or a confirmed slide plan.
+6. Let the agent write the HTML deck under `decks/`.
+7. Use `/revela edit` for visual comments and targeted revisions.
+8. Export with `/revela pdf <file>` or `/revela pptx <file>`.
 
-- workspace memory: stable project context, source materials, explicit user preferences, deck history, and open questions
-- active deck spec: current deck output path, prerequisites, research plan, per-slide content, layouts, components, evidence, visuals, blockers, and write readiness
+`/revela review` checks for practical readiness problems: unclear audience, missing source material, unfinished research, unsupported claims, weak source trace, incomplete slide structure, missing design/layout information, or lightweight narrative issues such as weak so-what, missing risk/assumption handling, and abrupt transitions. It does not write the final deck.
 
-`DECKS.json` is the source of truth for workspace memory and deck readiness.
-
-Create or refresh it with:
-
-```text
-/revela init
-```
-
-Review the current deck state with:
-
-```text
-/revela review
-```
-
-`/revela review` does not write the final HTML deck. It reads and updates `DECKS.json` through the `revela-decks` tool, checks what is missing, and sets `writeReadiness.status` to `ready` only when the deck is ready to generate.
-
-Minimum readiness conditions:
-
-- topic, audience, language, visual style/design, and slide plan are decided
-- source materials are identified or explicitly deemed unnecessary
-- research need is assessed
-- needed research findings have been read and reflected in the slide specs
-- the user has confirmed the slide plan
-- required design layouts and components have been fetched
-- every slide has a title, layout, components, and structured content
-- no blockers remain
-
-The plugin enforces this before deck HTML is written. A write or patch touching `decks/*.html` is allowed only when the matching deck in `DECKS.json` passes the readiness gate. Direct writes or patches to `DECKS.json` are blocked; use `revela-decks` instead.
-
-The gate checks:
-
-- `writeReadiness.status` is `ready`
-- `writeReadiness.blockers` is empty
-- the deck `outputPath` exactly matches the target `decks/*.html` path
-- all `requiredInputs` booleans are true
-- every slide has title, layout, components, and structured content
-- every needed research axis is `done`, `read`, or `skipped`
-
-If the gate blocks a write, Revela writes a marker file under `.opencode/revela/blocked-writes/` instead of creating or overwriting the deck HTML. This makes the failure visible to the agent while keeping the real deck file untouched.
-
-For `apply_patch`, Revela only checks whether the patch touches `decks/*.html`. If not ready, the whole patch is replaced with a blocked marker patch. The `edit` tool is not gated.
+If Revela blocks a deck write, ask the agent to run `/revela review`, resolve the reported gaps, and try again. This protects the deck file from being overwritten before the plan, evidence, and structure are ready.
 
 To remember long-term preferences, use:
 
@@ -235,7 +201,7 @@ To remember long-term preferences, use:
 /revela remember Prefer concise Chinese consulting-style decks.
 ```
 
-Do not use `remember` for temporary checklist state; temporary state belongs in the active deck spec in `DECKS.json`.
+Do not use `remember` for temporary checklist state; use it only for durable user or workflow preferences.
 
 ---
 
@@ -604,7 +570,7 @@ The editor opens in your browser. Use `Ctrl`/`Cmd` + click to reference deck ele
 
 LLM tool equivalent: `revela-edit` with no target. This lets the agent open the same editor when you say things like “I want to edit the deck”.
 
-`/revela edit` prepares minimal `DECKS.json` state for the existing HTML deck if needed, so the normal deck write gate can still protect `decks/*.html` while allowing targeted edits.
+For existing decks, `/revela edit` prepares whatever minimal project context is needed so targeted edits can still use the normal safety checks.
 
 ---
 

package/README.zh-CN.md

@@ -20,8 +20,8 @@ Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使
 - 通过 `/revela enable` 向当前 agent 注入演示文稿专用 system prompt
 - prompt 由 3 层组成：核心 skill、当前 domain、当前 design
 - 支持工作区文档扫描，以及 `.pdf`、`.docx`、`.pptx`、`.xlsx` 的透明文本提取和嵌入素材缓存提取
-- 使用工作区 `DECKS.json` 保存机器可读的 deck 记忆、逐页规格和写入前 readiness 状态
-- 在 active deck 结构化 ready 前，阻止过早写入 `decks/*.html`
+- 在当前工作区持续跟踪 deck 背景、页面结构、来源材料和 readiness
+- 写入 `decks/*.html` 前检查是否缺上下文、证据或结构
 - agent 每次写入、patch 或 edit `decks/*.html` 时自动执行快速 design compliance 检查
 - 为已有 deck 打开可视化评论编辑器，用户可以 Ctrl/Cmd + 点击元素，并把精确修改意见发回 OpenCode
 - 支持导出成 PDF 和可编辑 PPTX
@@ -88,7 +88,7 @@ export { default } from "/absolute/path/to/revela/index.ts";
 /revela enable
 ```
 
-在新项目里可以先初始化工作区 deck 状态：
+在新项目里可以先准备工作区：
 
 ```text
 /revela init
@@ -108,7 +108,7 @@ export { default } from "/absolute/path/to/revela/index.ts";
 Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main market drivers, use the active design faithfully, and save the result to decks/humanoid-robotics.html.
 ```
 
-在 agent 写入 `decks/humanoid-robotics.html` 之前，它必须通过 `revela-decks` 工具更新 `DECKS.json`：记录 active deck、已确认的逐页规格、layout、component，并由工具计算出 `writeReadiness.status: ready`。你也可以随时显式触发 readiness 检查：
+如果任务依赖来源材料、调研或已确认的 slide plan，可以先让 Revela 检查上下文、结构和证据是否足够：
 
 ```text
 /revela review
@@ -136,8 +136,8 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 /revela enable                   为当前会话启用演示文稿模式
 /revela disable                  关闭演示文稿模式
 
-/revela init                     初始化或刷新工作区 DECKS.json
-/revela review                   写 HTML 前检查当前 deck readiness
+/revela init                     为当前 deck 项目准备工作区
+/revela review                   检查上下文、结构和证据是否 ready
 /revela remember <text>          保存明确的用户/工作流偏好
 /revela edit                     打开 decks/ 下唯一 deck 的可视化编辑器
 
@@ -177,56 +177,22 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 
 ---
 
-## DECKS.json 记忆与写入门禁
+## 推荐使用流程
 
-Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生产控制。它主要给工具和 LLM 使用，不建议人工直接编辑。
+把 Revela 当成一个有检查环节的 deck 生产模式：
 
-它有两个职责：
+1. 用 `/revela enable` 启用 Revela。
+2. 新项目或工作区明显变化时，运行 `/revela init`。
+3. 如果默认风格不合适，先选择 design 或 domain。
+4. 给 agent 一个清楚的 deck 任务：受众、目标、语言、页数、来源要求和输出路径。
+5. 如果 deck 需要调研、引用或已确认的 slide plan，写作前先运行 `/revela review`。
+6. 让 agent 把 HTML deck 写到 `decks/` 下。
+7. 用 `/revela edit` 做可视化评论和精准修改。
+8. 用 `/revela pdf <file>` 或 `/revela pptx <file>` 导出。
 
-- 工作区记忆：稳定项目背景、源材料、明确用户偏好、历史 deck 和开放问题
-- active deck 规格：当前 deck 输出路径、前置条件、research plan、逐页内容、layout、component、证据、视觉需求、blocker 和 write readiness
+`/revela review` 检查的是实际生产问题：受众是否清楚、是否缺来源材料、调研是否完成、关键 claim 是否有证据、source trace 是否太弱、页面结构是否完整、design/layout 信息是否齐全，以及轻量叙事问题，例如 so-what 不清晰、缺少风险/假设处理或转场突兀。它不会写最终 deck。
 
-`DECKS.json` 是工作区记忆和 deck readiness 的 source of truth。
-
-创建或刷新：
-
-```text
-/revela init
-```
-
-检查当前 deck 状态：
-
-```text
-/revela review
-```
-
-`/revela review` 不会写最终 HTML deck。它通过 `revela-decks` 工具读取并更新 `DECKS.json`，检查缺失项，并且只有在 deck 真的可以生成时才把 `writeReadiness.status` 设为 `ready`。
-
-最小 readiness 条件：
-
-- topic、audience、language、visual style/design 和 slide plan 已确定
-- source materials 已识别，或明确不需要源材料
-- research need 已评估
-- 需要调研时，相关 findings 已读取并反映到逐页规格中
-- 用户已确认 slide plan
-- 需要的 design layouts 和 components 已获取
-- 每页都有 title、layout、components 和结构化 content
-- 没有 unresolved blockers
-
-插件会在写 deck HTML 前强制检查这些条件。任何触碰 `decks/*.html` 的 `write` 或 `apply_patch`，只有在 `DECKS.json` 里匹配的 deck 通过 readiness gate 后才允许执行。直接写入或 patch `DECKS.json` 会被阻止；必须使用 `revela-decks` 工具更新状态。
-
-门禁会检查：
-
-- `writeReadiness.status` 是 `ready`
-- `writeReadiness.blockers` 为空
-- deck `outputPath` 精确匹配目标 `decks/*.html` 路径
-- 所有 `requiredInputs` 布尔值都是 true
-- 每页都有 title、layout、components 和结构化 content
-- 每个 needed research axis 都是 `done`、`read` 或 `skipped`
-
-如果门禁阻止写入，Revela 会在 `.opencode/revela/blocked-writes/` 下写一个 marker 文件，而不是创建或覆盖真实 HTML deck。这样 agent 能看到失败原因，同时真实 deck 文件不会被污染。
-
-对 `apply_patch`，Revela 只检查 patch 是否触碰 `decks/*.html`。如果未 ready，整个 patch 会被替换成 blocked marker patch。`edit` 工具不做门禁。
+如果 Revela 阻止写入 deck，直接让 agent 运行 `/revela review`，根据报告补齐缺口后再写。这样可以避免在计划、证据或结构还不完整时覆盖真实 deck 文件。
 
 记住长期偏好请使用：
 
@@ -234,7 +200,7 @@ Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生
 /revela remember 我偏好中文、咨询风格、每页只表达一个核心观点。
 ```
 
-不要用 `remember` 保存临时 checklist 状态；临时状态应该保存在 `DECKS.json` 的 active deck spec 中。
+不要用 `remember` 保存临时 checklist 状态；它只适合保存长期用户偏好或工作流偏好。
 
 ---
 
@@ -569,7 +535,7 @@ Revela 0.8 中 `/revela edit` 不接受 target。如果 `decks/` 下正好有一
 
 对应的 LLM tool：`revela-edit`，不需要 target。因此当你说“我要编辑这个 deck”时，agent 也可以主动打开同一个编辑器。
 
-如果已有 HTML deck 缺少 `DECKS.json` 状态，`/revela edit` 会自动准备最小 deck state，让正常的 `decks/*.html` 写入门禁仍然生效，同时允许后续精准修改。
+对于已有 HTML deck，`/revela edit` 会自动准备必要的最小项目上下文，让后续精准修改仍然经过正常安全检查。
 
 ---
 

package/lib/agents/research-prompt.ts

@@ -29,7 +29,7 @@ Given a research brief specifying your topic and axis, you will:
 2. Use \`DECKS.json\` through \`revela-decks\` as the workspace material index when it exists
 3. Run a lightweight workspace freshness check when needed
 4. Search the web for current data, reports, and case studies when the brief requires it
-5. Write all findings to ONE structured file: \`researches/{topic-key}/{axis-name}.md\`
+5. Write all findings to ONE structured file: \`researches/{topic-key}/{axis-name}.md\` with source trace detailed enough for slide-level evidence mapping
 6. Return a brief summary of what you found
 
 ---
@@ -112,18 +112,21 @@ Use **\`revela-research-save\`** to write ONE file with all your findings.
 - \`content\`: structured findings using the four sections below
 - \`sources\`: list of all URLs and filenames used
 
+The primary agent will map your findings into \`DECKS.json\` slide-level evidence.
+Preserve compact source trace so it can do that without rediscovering sources.
+
 ### Findings file format
 
 Use these four sections — omit any that are empty:
 
 \`\`\`markdown
 ## Data
-- {stat or finding} [Source: {url or filename}]
-- {stat or finding} [Source: {url or filename}]
+- {stat or finding} [Source: {url or filename}; Location: {page/slide/sheet/section if known}; Quote: "{short exact snippet if available}"; Caveat: {scope/uncertainty if relevant}]
+- {stat or finding} [Source: {url or filename}; Location: {page/slide/sheet/section if known}; Quote: "{short exact snippet if available}"; Caveat: {scope/uncertainty if relevant}]
 (5–10 items, most argument-worthy only)
 
 ## Cases
-- **{Company/Entity}**: {1–2 sentence profile with key metrics} [Source: {url}]
+- **{Company/Entity}**: {1–2 sentence profile with key metrics} [Source: {url or filename}; Location: {page/slide/sheet/section if known}; Caveat: {scope/uncertainty if relevant}]
 (2–4 entries max)
 
 ## Images
@@ -136,6 +139,10 @@ Use these four sections — omit any that are empty:
 
 Content rules:
 - Every data point MUST have inline source attribution: \`[Source: {url}]\` or \`[Source: AI knowledge — verify]\` or \`[Source: {filename}]\`
+- For workspace documents, identify the original filename and available page, slide, sheet, or section location. Do not cite only the extracted summary.
+- When extracted materials were used, include \`extractedTextPath\` or \`extractedManifestPath\` when useful for traceability.
+- Preserve compact direct snippets or quotes when available. Do not invent quotes, page references, locations, URLs, or caveats.
+- Include caveats or scope limitations for estimates, rankings, market sizes, forecasts, and conflicting sources.
 - Preserve raw numbers and direct quotes — do not summarize prematurely
 - Use tables for comparative data when 3+ entities are compared
 - Include publication dates where available
@@ -170,6 +177,7 @@ Gaps:
 - **Always** call \`revela-extract-document-materials\` for every selected workspace file before deciding which extracted materials to read next
 - **Avoid** repeated extraction or deep reading for files that are clearly irrelevant to this axis
 - **Always** include source attribution on every data point
+- **Always** preserve source trace: URL or filename, location when available, compact quote/snippet when available, and caveat/scope where relevant
 - **Always** use tables for comparative data (more useful than bullets for presentations)
 - **Preserve** raw data — the primary agent will select what to include in slides
 - **Note** data freshness — include publication dates where available

package/lib/commands/init.ts

@@ -48,8 +48,10 @@ Workflow:
 6. Before extracting or deeply reading a selected document, check \`DECKS.json.workspace.sourceMaterials\`. If the same path has the same fingerprint and valid extraction paths, reuse those paths instead of repeating extraction.
 7. Read only the materials needed to form a conservative workspace memory. Do not exhaustively read every file if the workspace is large.
 8. If this conversation or the workspace contains a concrete deck task or an existing deck artifact, call \`revela-decks\` with action \`upsertDeck\` and later \`upsertSlides\` for explicit deck information. Do not pass or ask for a deck key; the tool uses the workspace folder name internally. Do not mark readiness ready during init.
-9. When adopting an existing HTML deck, analyze the artifact and create one conservative \`SlideSpec\` per identifiable slide/page. The \`SlideSpec[]\` itself is the worklist; do not create a separate target slide count.
-10. Report what was initialized or updated and list any open questions.
+9. When adopting an existing HTML deck, analyze the artifact and create one conservative \`SlideSpec\` per identifiable slide/page. Record only visible source notes or explicit source information as evidence; do not infer original evidence that is not present in the artifact.
+10. When a read or extracted source material clearly supports a specific slide claim, you may attach compact evidence fields such as \`sourcePath\`, \`location\`, \`extractedTextPath\`, or \`extractedManifestPath\`. Attach extraction cache paths only when they support that specific claim, not to every slide by default.
+11. Treat \`workspace.sourceMaterials\` as a reusable candidate index, not proof by itself. A source material record alone is not slide evidence.
+12. Report what was initialized or updated and list any open questions.
 
 Memory rules:
 - Only write facts supported by workspace files into ${DECKS_STATE_FILE} workspace state, source materials, deck memory, and open questions.

package/lib/commands/review.ts

@@ -18,7 +18,8 @@ Goal:
 - Preserve the deck spec for future sessions: every slide's content, layout, components, evidence, visuals, and production status.
 - Do not write, patch, or directly edit ${DECKS_STATE_FILE}. Use the \`revela-decks\` tool for all state changes.
 - Let \`revela-decks\` action \`review\` compute writeReadiness; do not manually set readiness to ready.
-- Treat this as an evidence-readiness review, not only a checklist review: unsupported numbers, market sizing, recommendations, competitor comparisons, technical assertions, or investment conclusions should be made visible before writing.
+- Treat this as an evidence and lightweight narrative readiness review, not only a checklist review: unsupported numbers, market sizing, recommendations, competitor comparisons, technical assertions, investment conclusions, weak so-what, missing risk/assumption handling, or abrupt narrative transitions should be made visible before writing.
+- Treat source trace mapping as part of evidence readiness: when research findings have been read, relevant findings should appear in slide-level \`slides[].evidence[]\` records rather than only in raw research files.
 
 Current state:
 - ${state}
@@ -33,19 +34,24 @@ Workspace boundary rules:
 Workflow:
 1. Call \`revela-decks\` with action \`read\` for the current workspace deck.
 2. If no current deck exists but the conversation contains enough deck context, call \`revela-decks\` action \`upsertDeck\` with goal, outputPath, theme, requiredInputs, and researchPlan. Do not invent or ask for a deck key; the tool uses the workspace folder name internally.
-3. If a user-confirmed slide plan is available, call \`revela-decks\` action \`upsertSlides\` with every slide's title, purpose, layout, components, structured content, evidence, visuals, and status.
-4. Only set requiredInputs fields true when explicit conversation state, files read, research findings read, selected design, fetched layouts/components, or user confirmation supports them. Do not infer completion.
-5. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` plus structured readiness issues for the current workspace deck.
-6. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool. If warnings exist, list them after blockers as residual risks.
+3. If \`researchPlan[].status\` is \`done\` or \`read\` and \`researchPlan[].findingsFile\` exists, verify that evidence-sensitive slide claims are backed by compact \`slides[].evidence[]\` records that reference the relevant findings file or source material where known.
+4. If a user-confirmed slide plan is available, call \`revela-decks\` action \`upsertSlides\` with every slide's title, purpose, narrativeRole, layout, components, structured content, evidence, visuals, and status. Use only lightweight narrativeRole values that are clear from the plan: \`context\`, \`tension\`, \`evidence\`, \`recommendation\`, \`risk\`, \`ask\`, \`appendix\`, or \`close\`.
+5. Prefer evidence records with \`findingsFile\`, \`sourcePath\`, \`location\`, \`quote\`, \`url\`, \`caveat\`, \`extractedTextPath\`, or \`extractedManifestPath\` when those fields are known from research files or extracted workspace materials.
+6. Do not invent quotes, page references, locations, URLs, caveats, or extraction paths. If source trace is missing, preserve the blocker or warning and report exactly what trace is needed.
+7. Only set requiredInputs fields true when explicit conversation state, files read, research findings read, selected design, fetched layouts/components, or user confirmation supports them. Do not infer completion.
+8. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` plus structured readiness issues for the current workspace deck.
+9. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool. If warnings exist, list them after blockers as residual risks; separate evidence/source warnings from narrative warnings when possible.
 
 Minimum conditions for \`ready\`:
 - Topic, audience, slide count, language, and visual style/design are decided.
 - Source materials have been identified or explicitly deemed unnecessary.
 - Research need has been assessed.
 - If research is needed, all relevant findings have been read and reflected in the slide specs.
+- Read or done research findings are mapped into \`slides[].evidence[]\` where they support evidence-sensitive slide claims.
 - The user has confirmed the slide plan.
 - ${DECKS_STATE_FILE} contains per-slide specs with content, layout, components, and evidence where applicable.
-- Evidence-sensitive slide claims have compact evidence references. Numeric claims and strong recommendations should not be unsupported.
+- Evidence-sensitive slide claims have compact evidence references with source trace where available. Numeric claims and strong recommendations should not be unsupported or source-only when trace exists.
+- Multi-slide decision decks have a practical narrative flow: context/tension before evidence, recommendations after support, risk or assumption handling when recommending action, and a clear so-what or ask at the end. Narrative gaps are normally warnings, not hard blockers.
 - The needed design layouts and components have been fetched with \`revela-designs read\`.
 - No unresolved blockers remain.
 
@@ -53,7 +59,9 @@ Report format:
 - Start with \`Ready: yes/no\`.
 - If blocked, list each blocker with slide index/title when the tool provides it, the issue type, and the suggested next action.
 - If warnings exist but the deck is otherwise ready, say the deck can be written but note the residual risks.
+- Report \`narrative_gap\` warnings as story-structure risks such as weak so-what, missing risk/assumption handling, conclusion before support, missing audience framing, or abrupt transition.
 - Do not invent evidence or silently downgrade blockers. Use the tool result as authoritative.
+- When reporting weak evidence, say whether the missing trace is \`findingsFile\`, \`sourcePath\`, \`location\`, \`quote\`, \`url\`, or \`caveat\` if that is clear from the reviewed materials.
 
 Rules:
 - Do not write or overwrite \`decks/*.html\` during review.

package/lib/decks-state.ts

@@ -6,6 +6,7 @@ export const DECKS_STATE_FILE = "DECKS.json"
 export type DeckProductionStatus = "planning" | "blocked" | "ready" | "written"
 export type SlideProductionStatus = "planned" | "ready" | "written" | "qa_passed" | "qa_failed"
 export type WriteReadinessStatus = "blocked" | "ready" | "written"
+export type NarrativeRole = "context" | "tension" | "evidence" | "recommendation" | "risk" | "ask" | "appendix" | "close"
 
 export interface DecksState {
   version: 1
@@ -96,6 +97,7 @@ export interface SlideSpec {
   index: number
   title: string
   purpose?: string
+  narrativeRole?: NarrativeRole
   layout: string
   qa?: boolean
   components: string[]
@@ -117,6 +119,12 @@ export interface EvidenceRef {
   quote?: string
   page?: string
   url?: string
+  sourcePath?: string
+  location?: string
+  findingsFile?: string
+  caveat?: string
+  extractedTextPath?: string
+  extractedManifestPath?: string
 }
 
 export interface VisualBrief {
@@ -153,6 +161,7 @@ export type ReadinessIssueType =
   | "missing_evidence"
   | "weak_evidence"
   | "source_not_processed"
+  | "narrative_gap"
 
 export interface ReadinessIssue {
   type: ReadinessIssueType
@@ -164,6 +173,8 @@ export interface ReadinessIssue {
   claimText?: string
 }
 
+const SOURCE_TRACE_ACTION = "Add slide evidence with source plus source trace such as findingsFile or sourcePath, and quote, location, url, or caveat where available; otherwise reframe the claim as an explicit assumption/opinion."
+
 export function decksStatePath(workspaceRoot: string): string {
   return join(workspaceRoot, DECKS_STATE_FILE)
 }
@@ -432,14 +443,58 @@ export function buildDecksStatePromptLayer(workspaceRoot: string, maxChars = 140
   const compact = {
     sourceOfTruth: DECKS_STATE_FILE,
     activeDeck: activeKey,
-    workspace: state.workspace,
-    deck: active,
+    workspace: compactWorkspaceForPrompt(state.workspace),
+    deck: active ? compactDeckForPrompt(active) : undefined,
   }
   let text = JSON.stringify(compact, null, 2)
   if (text.length > maxChars) text = text.slice(0, maxChars).trimEnd() + "\n[DECKS.json state truncated for prompt size.]"
   return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as the source of truth for the single current deck's specs, slide plan, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- Before writing decks/*.html, the current deck must have writeReadiness.status=ready and a complete slide spec, and its outputPath must match the target file.`
 }
 
+function compactWorkspaceForPrompt(workspace: DecksState["workspace"]): DecksState["workspace"] {
+  return {
+    brief: truncatePromptText(workspace.brief),
+    sourceMaterials: workspace.sourceMaterials.map((source) => ({
+      ...source,
+      summary: truncatePromptText(source.summary),
+      bestUsedFor: truncatePromptText(source.bestUsedFor),
+    })),
+    preferences: workspace.preferences,
+    deckMemory: workspace.deckMemory,
+    openQuestions: workspace.openQuestions.map((question) => truncatePromptText(question)).filter(Boolean) as string[],
+  }
+}
+
+function compactDeckForPrompt(deck: DeckSpec): DeckSpec {
+  return {
+    ...deck,
+    slides: deck.slides.map((slide) => ({
+      ...slide,
+      content: {
+        ...slide.content,
+        speakerNotes: truncatePromptText(slide.content.speakerNotes),
+      },
+      evidence: slide.evidence.map(compactEvidenceForPrompt),
+      notes: truncatePromptText(slide.notes),
+    })),
+  }
+}
+
+function compactEvidenceForPrompt(evidence: EvidenceRef): EvidenceRef {
+  return {
+    ...evidence,
+    source: truncatePromptText(evidence.source, 180) ?? evidence.source,
+    quote: truncatePromptText(evidence.quote, 320),
+    caveat: truncatePromptText(evidence.caveat, 220),
+  }
+}
+
+function truncatePromptText(text: string | undefined, maxLength = 400): string | undefined {
+  if (!text) return undefined
+  if (text.length <= maxLength) return text
+  return `${text.slice(0, maxLength).trimEnd()}... [truncated]`
+}
+
 function normalizeDecksState(input: DecksState): DecksState {
   const state: DecksState = {
     version: 1,
@@ -515,19 +570,21 @@ function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["works
       issues.push(blockerIssue(
         "missing_evidence",
         `Slide ${slide.index} has an evidence-sensitive claim without evidence: ${claim}`,
-        "Add a compact evidence reference to slides[].evidence or reframe the claim as an explicit assumption/opinion.",
+        SOURCE_TRACE_ACTION,
         { ...slideRef, claimText: claim },
       ))
     } else if (claim && slide.evidence.some((item) => !hasEvidenceDetail(item))) {
       issues.push(warningIssue(
         "weak_evidence",
-        `Slide ${slide.index} evidence for a high-risk claim has no quote, page, or URL detail: ${claim}`,
-        "Add quote/page/url details where available so the writing agent can ground the slide more reliably.",
+        `Slide ${slide.index} evidence for a high-risk claim has no source trace detail: ${claim}`,
+        "Add source trace detail to this evidence record: findingsFile or sourcePath plus quote, location, url, or caveat where available so the writing agent can ground the slide reliably.",
         { ...slideRef, claimText: claim },
       ))
     }
   }
 
+  issues.push(...computeNarrativeReadinessIssues(deck))
+
   for (const axis of deck.researchPlan) {
     if (axis.needed && axis.status !== "done" && axis.status !== "read" && axis.status !== "skipped") {
       issues.push(blockerIssue(
@@ -560,6 +617,89 @@ function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["works
   return issues
 }
 
+function computeNarrativeReadinessIssues(deck: DeckSpec): ReadinessIssue[] {
+  const issues: ReadinessIssue[] = []
+  const slides = deck.slides.filter((slide) => slide.index > 0).sort((a, b) => a.index - b.index)
+  if (slides.length === 0) return issues
+
+  if (slides.length >= 4 && slides.every((slide) => !slide.narrativeRole)) {
+    issues.push(warningIssue(
+      "narrative_gap",
+      "No slide narrativeRole values are recorded for a multi-slide deck",
+      "Add lightweight narrativeRole values such as context, tension, evidence, recommendation, risk, ask, appendix, or close to improve story-structure review.",
+    ))
+  }
+
+  if (slides.length >= 4 && deck.audience?.trim() && slides.every(hasWeakNarrativePurpose)) {
+    issues.push(warningIssue(
+      "narrative_gap",
+      `Slide purposes do not clearly frame the story for the audience: ${deck.audience}`,
+      "Rewrite slide purpose fields to explain what this audience should understand, believe, decide, or do after each slide.",
+    ))
+  }
+
+  const firstRecommendationIndex = slides.findIndex(isRecommendationSlide)
+  if (firstRecommendationIndex >= 0) {
+    const recommendation = slides[firstRecommendationIndex]
+    const priorSlides = slides.slice(0, firstRecommendationIndex)
+    const earlyBoundary = Math.max(1, Math.ceil(slides.length * 0.3))
+    if (firstRecommendationIndex < earlyBoundary && !priorSlides.some(hasEvidenceOrTensionRole)) {
+      issues.push(warningIssue(
+        "narrative_gap",
+        `Slide ${recommendation.index} presents a recommendation before context, tension, or evidence has been established`,
+        "Consider moving the recommendation later or adding preceding context, tension, or evidence slides so the conclusion does not arrive before support.",
+        { slideIndex: recommendation.index, slideTitle: recommendation.title },
+      ))
+    }
+
+    if (!slides.some(hasRiskOrAssumptionHandling)) {
+      issues.push(warningIssue(
+        "narrative_gap",
+        "Recommendation has no visible risk, assumption, caveat, or tradeoff handling",
+        "Add a risk/assumption/tradeoff slide or make the relevant caveats explicit before writing a decision-oriented recommendation deck.",
+        { slideIndex: recommendation.index, slideTitle: recommendation.title },
+      ))
+    }
+  }
+
+  if (slides.length >= 4 && !hasClearEnding(slides)) {
+    const last = slides[slides.length - 1]
+    issues.push(warningIssue(
+      "narrative_gap",
+      "Deck may end without a clear so-what, ask, or closing takeaway",
+      "Use the final slide or final section to state the decision, action request, recommendation, or closing takeaway explicitly.",
+      { slideIndex: last.index, slideTitle: last.title },
+    ))
+  }
+
+  const firstAskIndex = slides.findIndex(isAskSlide)
+  if (firstAskIndex === 0 && slides.length > 2) {
+    const ask = slides[firstAskIndex]
+    issues.push(warningIssue(
+      "narrative_gap",
+      `Slide ${ask.index} asks for action before the deck has established the case`,
+      "Consider moving the ask later or opening with context before requesting a decision or action.",
+      { slideIndex: ask.index, slideTitle: ask.title },
+    ))
+  } else if (firstAskIndex > 0) {
+    const contextIndex = slides.findIndex((slide) => slide.narrativeRole === "context")
+    if (contextIndex >= 0 && contextIndex < firstAskIndex) {
+      const bridgeSlides = slides.slice(contextIndex + 1, firstAskIndex)
+      if (!bridgeSlides.some((slide) => hasEvidenceOrTensionRole(slide) || isRecommendationSlide(slide))) {
+        const ask = slides[firstAskIndex]
+        issues.push(warningIssue(
+          "narrative_gap",
+          `Slide ${ask.index} jumps from context to ask without evidence, tension, or recommendation in between`,
+          "Add an evidence, tension, or recommendation bridge before the ask so the narrative transition is easier to follow.",
+          { slideIndex: ask.index, slideTitle: ask.title },
+        ))
+      }
+    }
+  }
+
+  return issues
+}
+
 function blockerIssue(type: ReadinessIssueType, message: string, suggestedAction: string, extra: Partial<ReadinessIssue> = {}): ReadinessIssue {
   return { type, severity: "blocker", message, suggestedAction, ...extra }
 }
@@ -582,6 +722,46 @@ function findEvidenceSensitiveClaim(slide: SlideSpec): string | undefined {
   return candidates.find(isEvidenceSensitiveClaim)
 }
 
+function isRecommendationSlide(slide: SlideSpec): boolean {
+  return slide.narrativeRole === "recommendation" || /\b(recommend(?:ation|ed)?|should|must|go\/?no-go)\b|建议|必须/.test(slideSearchText(slide))
+}
+
+function isAskSlide(slide: SlideSpec): boolean {
+  return slide.narrativeRole === "ask" || /\b(ask|decision|approve|approval|next step|action required|call to action)\b|请求|决策|批准|下一步|行动/.test(slideSearchText(slide))
+}
+
+function hasEvidenceOrTensionRole(slide: SlideSpec): boolean {
+  return slide.narrativeRole === "evidence" || slide.narrativeRole === "tension"
+}
+
+function hasRiskOrAssumptionHandling(slide: SlideSpec): boolean {
+  return slide.narrativeRole === "risk" || /\b(risk|assumption|caveat|trade-?off|constraint|limitation|uncertainty)\b|风险|假设|取舍|限制|不确定|前提/.test(slideSearchText(slide))
+}
+
+function hasWeakNarrativePurpose(slide: SlideSpec): boolean {
+  const purpose = slide.purpose?.trim().toLowerCase()
+  if (!purpose) return true
+  return /^(explain|show|introduce|present|describe|overview|clarify)\b/.test(purpose) || /^(说明|展示|介绍|呈现|概述)/.test(purpose)
+}
+
+function hasClearEnding(slides: SlideSpec[]): boolean {
+  const finalSlides = slides.slice(-2)
+  return finalSlides.some((slide) => slide.narrativeRole === "recommendation" || slide.narrativeRole === "ask" || slide.narrativeRole === "close" || /\b(so what|takeaway|recommend(?:ation)?|decision|ask|next step|conclusion|close)\b|结论|建议|决策|请求|下一步|收尾|总结/.test(slideSearchText(slide)))
+}
+
+function slideSearchText(slide: SlideSpec): string {
+  return [
+    slide.title,
+    slide.purpose,
+    slide.content?.headline,
+    ...(slide.content?.body ?? []),
+    ...(slide.content?.bullets ?? []),
+  ]
+    .filter((item): item is string => Boolean(item))
+    .join("\n")
+    .toLowerCase()
+}
+
 function isEvidenceSensitiveClaim(text: string): boolean {
   const normalized = text.toLowerCase()
   return hasNumericClaim(normalized) || EVIDENCE_SENSITIVE_TERMS.some((pattern) => pattern.test(normalized))
@@ -592,7 +772,15 @@ function hasNumericClaim(text: string): boolean {
 }
 
 function hasEvidenceDetail(evidence: EvidenceRef): boolean {
-  return Boolean(evidence.quote?.trim() || evidence.page?.trim() || evidence.url?.trim())
+  return Boolean(
+    evidence.quote?.trim() ||
+      evidence.page?.trim() ||
+      evidence.location?.trim() ||
+      evidence.url?.trim() ||
+      evidence.findingsFile?.trim() ||
+      evidence.sourcePath?.trim() ||
+      evidence.extractedTextPath?.trim()
+  )
 }
 
 const EVIDENCE_SENSITIVE_TERMS = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",

package/skill/SKILL.md

@@ -292,15 +292,17 @@ slide plan to the user **before writing any HTML**.
 
 Format the plan as a markdown table:
 
-| # | Title | Content Summary | Layout | Components |
-|---|-------|-----------------|--------|------------|
-| 1 | Cover | Topic title, subtitle, presenter, date | `cover` | `gradient-text`, `deco-blob`, `accent-line` |
-| 2 | Table of Contents | 5 chapter headings | `toc` | `toc-list` |
-| 3 | Market Background | Key problem, 3 pain points, $4.2B TAM | `two-col` | `evidence-list`, `card` |
-| 4 | Key Metrics | Growth 85%, TAM $12B, NPS 72 | `stats` | `stat-card ×3`, `gradient-text` |
+| # | Title | Narrative Role | Content Summary | Layout | Components |
+|---|-------|----------------|-----------------|--------|------------|
+| 1 | Cover | `context` | Topic title, subtitle, presenter, date | `cover` | `gradient-text`, `deco-blob`, `accent-line` |
+| 2 | Table of Contents | `context` | 5 chapter headings | `toc` | `toc-list` |
+| 3 | Market Background | `tension` | Key problem, 3 pain points, $4.2B TAM | `two-col` | `evidence-list`, `card` |
+| 4 | Key Metrics | `evidence` | Growth 85%, TAM $12B, NPS 72 | `stats` | `stat-card ×3`, `gradient-text` |
 
 Rules for filling the table:
 - **Layout**: use the exact layout name from the Layout Index (e.g. `cover`, `two-col`, `card-grid`, `stats`)
+- **Narrative Role**: use one lightweight role when clear: `context`, `tension`, `evidence`,
+  `recommendation`, `risk`, `ask`, `appendix`, or `close`
 - **Components**: list component names from the Component Index — no CSS details
   (e.g. `card ×3`, `stat-card`, `evidence-list`, `step-flow`, `quote-block`)
 - **Content Summary**: 1 sentence of actual content — specific numbers, key points, or
@@ -319,7 +321,7 @@ Then ask:
 
 After the user confirms the slide plan, update `DECKS.json` through `revela-decks`:
 - Call `upsertDeck` to mark completed `requiredInputs` only when explicitly satisfied.
-- Call `upsertSlides` with the confirmed per-slide content, layout, components, and evidence.
+- Call `upsertSlides` with the confirmed per-slide content, narrativeRole, layout, components, and evidence.
 - Keep write readiness blocked until Phase 5 calls `revela-decks review` and the tool returns ready.
 
 ---

package/tools/decks.ts

@@ -75,6 +75,7 @@ export default tool({
       index: tool.schema.number().describe("1-based slide index."),
       title: tool.schema.string().describe("Slide title."),
       purpose: tool.schema.string().optional().describe("Narrative purpose of this slide."),
+      narrativeRole: tool.schema.enum(["context", "tension", "evidence", "recommendation", "risk", "ask", "appendix", "close"]).optional().describe("Lightweight narrative role for review guidance."),
       layout: tool.schema.string().describe("Design layout name."),
       qa: tool.schema.boolean().optional().describe("Whether the slide is marked QA-relevant deck metadata."),
       components: tool.schema.array(tool.schema.string()).describe("Design components used by this slide."),
@@ -86,10 +87,16 @@ export default tool({
       }).describe("Structured slide content."),
       evidence: tool.schema.array(tool.schema.object({
         source: tool.schema.string().describe("Source file, URL, or research note."),
-        quote: tool.schema.string().optional(),
-        page: tool.schema.string().optional(),
-        url: tool.schema.string().optional(),
-      })).optional().describe("Evidence references for this slide."),
+        quote: tool.schema.string().optional().describe("Compact quote or snippet supporting the slide claim."),
+        page: tool.schema.string().optional().describe("Legacy page reference; prefer location for new page/slide/sheet/section references."),
+        url: tool.schema.string().optional().describe("Source URL when available."),
+        sourcePath: tool.schema.string().optional().describe("Workspace source file path when the evidence came from a local material."),
+        location: tool.schema.string().optional().describe("Generic page, slide, sheet, section, or other source location reference."),
+        findingsFile: tool.schema.string().optional().describe("researches/{topic}/{axis}.md findings file that records the supporting evidence."),
+        caveat: tool.schema.string().optional().describe("Scope, uncertainty, or limitation that should travel with this evidence."),
+        extractedTextPath: tool.schema.string().optional().describe("Reusable extracted text cache path when this evidence came from extracted materials."),
+        extractedManifestPath: tool.schema.string().optional().describe("Reusable extracted materials manifest path when available."),
+      })).optional().describe("Compact evidence references and source trace for this slide."),
       visuals: tool.schema.array(tool.schema.object({
         id: tool.schema.string().optional(),
         purpose: tool.schema.string().optional(),