@cyber-dash-tech/revela 0.9.0 → 0.10.0

package/README.md

@@ -140,7 +140,9 @@ Disable presentation mode when done:
 /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 refine                   open unified Edit/Inspect refinement workspace
 /revela edit                     open visual editor for the only deck in decks/
+/revela inspect                  open Evidence Inspector for Cmd/Ctrl-click review
 
 /revela designs                  list installed designs
 /revela designs <name>           activate a design
@@ -159,7 +161,7 @@ Disable presentation mode when done:
 /revela pptx <file>              export an HTML deck to editable PPTX in the same directory
 ```
 
-Most `/revela` commands run locally with zero LLM cost. `/revela init`, `/revela review`, `/revela remember`, `/revela designs-new`, and `/revela designs-edit` start AI-assisted workflows because they need to read or update project files. `/revela edit` opens a local visual editor and then sends user comments back into the current OpenCode session when the user submits them.
+Most `/revela` commands run locally with zero LLM cost. `/revela init`, `/revela review`, `/revela remember`, `/revela designs-new`, and `/revela designs-edit` start AI-assisted workflows because they need to read or update project files. `/revela refine` opens a local browser workspace with Edit and Inspect tabs that share the same Cmd/Ctrl-click element references. Edit sends targeted comments back into the current OpenCode session; Inspect renders deterministic Source/Purpose preprocessing first before lazy LLM-generated cards arrive, has no chat box, and does not edit the deck.
 
 ---
 
@@ -188,8 +190,9 @@ Use Revela as a guided deck-production mode:
 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>`.
+7. Use `/revela refine` for visual comments, targeted revisions, and optional Source/Purpose inspection of selected deck elements.
+8. Use `/revela edit` or `/revela inspect` directly only if you need the older single-purpose shells.
+9. Export with `/revela pdf <file>` or `/revela pptx <file>`.
 
 `/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.
 
@@ -558,6 +561,14 @@ A custom domain is a folder containing `INDUSTRY.md`.
 
 ## Visual Editing
 
+Use the unified refinement workspace for normal post-write review and revision:
+
+```text
+/revela refine
+```
+
+`/revela refine` opens the only HTML deck in `decks/` with two tabs. Use `Ctrl`/`Cmd` + click once to reference deck elements, then choose Edit for fast natural-language change comments or Inspect for read-only Source and Purpose review. Inspect does not mutate the deck; Edit remains the mutation path.
+
 Open the visual editor for the only HTML deck in `decks/`:
 
 ```text
@@ -566,7 +577,7 @@ Open the visual editor for the only HTML deck in `decks/`:
 
 `/revela edit` does not accept a target in Revela 0.8. If `decks/` contains exactly one `.html` file, Revela opens it. If `decks/` contains zero or multiple `.html` files, Revela asks you to generate a deck first or move extra decks to separate workspaces.
 
-The editor opens in your browser. Use `Ctrl`/`Cmd` + click to reference deck elements, write a natural-language comment, then send it back to OpenCode. Revela sends a structured edit prompt that includes the deck file, slide context, selected element metadata, and your comment.
+The older edit-only shell opens in your browser. Use `Ctrl`/`Cmd` + click to reference deck elements, write a natural-language comment, then send it back to OpenCode. Revela sends a structured edit prompt that includes the deck file, slide context, selected element metadata, and your comment.
 
 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”.
 
@@ -574,6 +585,20 @@ For existing decks, `/revela edit` prepares whatever minimal project context is
 
 ---
 
+## Evidence Inspector
+
+Open the Evidence Inspector for the only HTML deck in `decks/`, or use the Inspect tab in `/revela refine`:
+
+```text
+/revela inspect
+```
+
+The inspector opens in your browser with the deck on the left and fixed cards on the right: Source and Purpose. Use `Ctrl`/`Cmd` + click to reference deck elements exactly like `/revela edit`, then click `Inspect Selection`. Selection is locked while the request is being processed.
+
+The inspector is not chat and has no freeform prompt. It does not mutate `DECKS.json` or the deck HTML. It uses recorded slide specs, narrative state, and slide-level evidence trace as grounded context. Deterministic preprocessing appears immediately; lazy LLM judgment then refines the Source and Purpose cards without inventing edits.
+
+---
+
 ## Export
 
 PDF export:

package/README.zh-CN.md

@@ -139,7 +139,9 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 /revela init                     为当前 deck 项目准备工作区
 /revela review                   检查上下文、结构和证据是否 ready
 /revela remember <text>          保存明确的用户/工作流偏好
+/revela refine                   打开统一的 Edit/Inspect refinement workspace
 /revela edit                     打开 decks/ 下唯一 deck 的可视化编辑器
+/revela inspect                  打开 Cmd/Ctrl-click 式 Evidence Inspector
 
 /revela designs                  列出已安装 design
 /revela designs <name>           激活某个 design
@@ -158,7 +160,7 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 /revela pptx <file>              将 HTML deck 导出为同目录可编辑 PPTX
 ```
 
-大多数 `/revela` 命令都在本地执行，不消耗 LLM token。`/revela init`、`/revela review`、`/revela remember`、`/revela designs-new` 和 `/revela designs-edit` 会启动 AI 辅助流程，因为它们需要读取或更新项目状态。`/revela edit` 会打开本地可视化编辑器，并在用户提交评论后把修改请求发回当前 OpenCode 会话。
+大多数 `/revela` 命令都在本地执行，不消耗 LLM token。`/revela init`、`/revela review`、`/revela remember`、`/revela designs-new` 和 `/revela designs-edit` 会启动 AI 辅助流程，因为它们需要读取或更新项目状态。`/revela refine` 会打开一个本地浏览器 workspace，里面有 Edit 和 Inspect 两个 tab，并共享同一套 Cmd/Ctrl-click 元素引用。Edit 会把精准修改评论发回当前 OpenCode 会话；Inspect 会先渲染确定性 Source/Purpose 预处理结果，再 lazy 显示 LLM 生成的卡片。它没有聊天框，也不会修改 deck。
 
 ---
 
@@ -187,8 +189,9 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 4. 给 agent 一个清楚的 deck 任务：受众、目标、语言、页数、来源要求和输出路径。
 5. 如果 deck 需要调研、引用或已确认的 slide plan，写作前先运行 `/revela review`。
 6. 让 agent 把 HTML deck 写到 `decks/` 下。
-7. 用 `/revela edit` 做可视化评论和精准修改。
-8. 用 `/revela pdf <file>` 或 `/revela pptx <file>` 导出。
+7. 用 `/revela refine` 对选中 deck 元素做可视化评论、精准修改，以及可选的 Source/Purpose 检查。
+8. 只有在需要旧的单一功能 shell 时，才单独使用 `/revela edit` 或 `/revela inspect`。
+9. 用 `/revela pdf <file>` 或 `/revela pptx <file>` 导出。
 
 `/revela review` 检查的是实际生产问题：受众是否清楚、是否缺来源材料、调研是否完成、关键 claim 是否有证据、source trace 是否太弱、页面结构是否完整、design/layout 信息是否齐全，以及轻量叙事问题，例如 so-what 不清晰、缺少风险/假设处理或转场突兀。它不会写最终 deck。
 
@@ -523,6 +526,14 @@ Prompt 注入规则：
 
 ## 可视化编辑
 
+正常的写后 review 和修改建议使用统一 refinement workspace：
+
+```text
+/revela refine
+```
+
+`/revela refine` 会打开 `decks/` 下唯一的 HTML deck，并提供两个 tab。使用 `Ctrl`/`Cmd` + click 先引用 deck 元素，然后在 Edit 里快速写自然语言修改评论，或在 Inspect 里做只读 Source 和 Purpose 检查。Inspect 不会修改 deck；真正的 mutation 仍然只走 Edit。
+
 打开 `decks/` 下唯一 HTML deck 的可视化编辑器：
 
 ```text
@@ -531,7 +542,7 @@ Prompt 注入规则：
 
 Revela 0.8 中 `/revela edit` 不接受 target。如果 `decks/` 下正好有一个 `.html` 文件，Revela 会打开它。如果 `decks/` 下没有 HTML 或有多个 HTML，Revela 会提示先生成 deck，或把多余 deck 移到独立 workspace。
 
-编辑器会在浏览器中打开。使用 `Ctrl`/`Cmd` + 点击 deck 元素来引用它们，写一段自然语言评论，然后发送回 OpenCode。Revela 会把 deck 文件、slide 上下文、选中元素 metadata 和你的评论整理成结构化 edit prompt。
+旧的 edit-only shell 会在浏览器中打开。使用 `Ctrl`/`Cmd` + 点击 deck 元素来引用它们，写一段自然语言评论，然后发送回 OpenCode。Revela 会把 deck 文件、slide 上下文、选中元素 metadata 和你的评论整理成结构化 edit prompt。
 
 对应的 LLM tool：`revela-edit`，不需要 target。因此当你说“我要编辑这个 deck”时，agent 也可以主动打开同一个编辑器。
 
@@ -539,6 +550,20 @@ Revela 0.8 中 `/revela edit` 不接受 target。如果 `decks/` 下正好有一
 
 ---
 
+## Evidence Inspector
+
+打开 `decks/` 下唯一 HTML deck 的 Evidence Inspector，或直接使用 `/revela refine` 里的 Inspect tab：
+
+```text
+/revela inspect
+```
+
+Inspector 会在浏览器中打开，左侧是 deck，右侧是固定卡片：Source 和 Purpose。使用 `Ctrl`/`Cmd` + click 像 `/revela edit` 一样引用 deck 元素，然后点击 `Inspect Selection`。请求处理期间，deck 选择会被锁定。
+
+Inspector 不是聊天，也没有自由输入框。它不会修改 `DECKS.json` 或 deck HTML。它使用已记录的 slide spec、narrative state 和 slide-level evidence trace 作为 grounded context。确定性预处理会立即显示；LLM judgment 随后 lazy 更新 Source 和 Purpose 卡片，不会强行生成编辑动作。
+
+---
+
 ## 导出
 
 PDF 导出：

package/designs/monet/DESIGN.md

@@ -193,10 +193,10 @@ Every generated presentation must use this exact HTML skeleton:
     <style>/* all CSS here */</style>
 </head>
 <body>
-    <section class="slide cover-slide" slide-qa="false" data-index="0">
+    <section class="slide cover-slide" slide-qa="false" data-slide-index="1">
         <div class="slide-canvas"> ... </div>
     </section>
-    <section class="slide" slide-qa="true" data-index="1">
+    <section class="slide" slide-qa="true" data-slide-index="2">
         <div class="slide-canvas"> ... </div>
     </section>
     <script>/* all JS here */</script>
@@ -507,7 +507,7 @@ These rules are mandatory for Monet.
 
 ### Layout Types
 
-Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. Use the QA column to decide which value to write. Fetch any layout with the `revela-designs` tool (`action: "read"`, `layout: "<name>"`).
+Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. It must also set `data-slide-index="N"`, where `N` is the 1-based `DECKS.json` `slides[].index` value. Use the QA column to decide which value to write. Fetch any layout with the `revela-designs` tool (`action: "read"`, `layout: "<name>"`).
 
 <!-- @layout:fullbleed:start qa=false -->
 #### Fullbleed
@@ -518,7 +518,7 @@ Structural intent:
 - Single slot: place one `image-title` component directly inside `.page`. The component is self-contained — it manages its own image, blur, overlay, and text layers internally.
 
 ```html
-<section class="slide" slide-qa="false" data-index="N">
+<section class="slide" slide-qa="false" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;">
 
@@ -550,7 +550,7 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;overflow:hidden;">
       <div class="narrative-grid">
@@ -610,7 +610,7 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;overflow:hidden;">
       <div class="narrative-grid narrative-grid--reverse">
@@ -649,7 +649,7 @@ Structural intent:
 Every slot accepts 1 or more components. Add or remove child divs to control column count — 3 is the default, but 4 or 5 columns work equally well.
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page">
       <div style="display:flex;flex-direction:column;gap:10px;margin-bottom:28px;max-width:520px;">
@@ -714,7 +714,7 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="overflow:hidden;">
       <div class="halves-grid" style="flex:1;min-height:0;">
@@ -768,7 +768,7 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;">
       <div class="stacked-grid">

package/designs/starter/DESIGN.md

@@ -117,7 +117,7 @@ Every generated presentation must use this exact HTML skeleton:
     <style>/* all CSS here */</style>
 </head>
 <body>
-    <section class="slide" slide-qa="false" data-index="0">
+    <section class="slide" slide-qa="false" data-slide-index="1">
         <div class="slide-canvas"><div class="page">...</div></div>
     </section>
     <script>/* all JS here */</script>
@@ -246,7 +246,7 @@ new SlidePresentation();
 
 ### Layout Types
 
-Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. Use the QA flag on each layout marker.
+Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. Use the QA flag on each layout marker. It must also set `data-slide-index="N"`, where `N` is the 1-based `DECKS.json` `slides[].index` value.
 
 <!-- @layout:fullbleed:start qa=false -->
 #### Fullbleed
@@ -254,7 +254,7 @@ Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`.
 Full-page layout for a single dominant component such as `image-title`, a large `svg-motif`, or a sparse title field.
 
 ```html
-<section class="slide" slide-qa="false" data-index="N">
+<section class="slide" slide-qa="false" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;">
       <!-- [slot: content] — usually image-title, svg-motif, or a custom hero component -->
@@ -270,7 +270,7 @@ Full-page layout for a single dominant component such as `image-title`, a large
 Asymmetric two-column layout. Use when one side needs more visual or reading weight.
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;">
       <div class="narrative-grid">
@@ -295,7 +295,7 @@ Asymmetric two-column layout. Use when one side needs more visual or reading wei
 Mirrored asymmetric two-column layout. Same structure as `narrative`, with the wider column on the right.
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;">
       <div class="narrative-grid narrative-grid--reverse">
@@ -314,7 +314,7 @@ Mirrored asymmetric two-column layout. Same structure as `narrative`, with the w
 Equal-column layout for parallel ideas, feature groups, proof points, or compact component showcases.
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page">
       <div style="display:flex;flex-direction:column;gap:10px;margin-bottom:28px;max-width:620px;">
@@ -343,7 +343,7 @@ Equal-column layout for parallel ideas, feature groups, proof points, or compact
 Symmetric two-column layout for direct comparison, paired evidence, or split workflows.
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;">
       <div class="halves-grid">
@@ -367,7 +367,7 @@ Symmetric two-column layout for direct comparison, paired evidence, or split wor
 Two-row layout for a compact header/summary above a larger evidence, chart, or flow area.
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;">
       <div class="stacked-grid">

package/designs/summit/DESIGN.md

@@ -131,10 +131,10 @@ Every generated presentation must use this exact HTML skeleton:
     <style>/* all CSS here */</style>
 </head>
 <body>
-    <section class="slide cover-slide" slide-qa="false" data-index="0">
+    <section class="slide cover-slide" slide-qa="false" data-slide-index="1">
         <div class="slide-canvas"> ... </div>
     </section>
-    <section class="slide" slide-qa="true" data-index="1">
+    <section class="slide" slide-qa="true" data-slide-index="2">
         <div class="slide-canvas"> ... </div>
     </section>
     <script>/* all JS here */</script>
@@ -445,7 +445,7 @@ These rules are mandatory for Summit.
 
 ### Layout Types
 
-Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. Use the QA column to decide which value to write. Fetch any layout with the `revela-designs` tool (`action: "read"`, `layout: "<name>"`).
+Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. It must also set `data-slide-index="N"`, where `N` is the 1-based `DECKS.json` `slides[].index` value. Use the QA column to decide which value to write. Fetch any layout with the `revela-designs` tool (`action: "read"`, `layout: "<name>"`).
 
 <!-- @layout:fullbleed:start qa=false -->
 #### Fullbleed
@@ -456,7 +456,7 @@ Structural intent:
 - Single slot: place one `image-title` component directly inside `.page`. The component is self-contained — it manages its own image, blur, overlay, and text layers internally.
 
 ```html
-<section class="slide" slide-qa="false" data-index="N">
+<section class="slide" slide-qa="false" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;">
 
@@ -488,7 +488,7 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;overflow:hidden;">
       <div class="narrative-grid">
@@ -548,7 +548,7 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;overflow:hidden;">
       <div class="narrative-grid narrative-grid--reverse">
@@ -587,7 +587,7 @@ Structural intent:
 Every slot accepts 1 or more components. Add or remove child divs to control column count — 3 is the default, but 4 or 5 columns work equally well.
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page">
       <div style="display:flex;flex-direction:column;gap:10px;margin-bottom:28px;max-width:520px;">
@@ -652,7 +652,7 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="overflow:hidden;">
       <div class="halves-grid" style="flex:1;min-height:0;">
@@ -706,7 +706,7 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 
 ```html
-<section class="slide" slide-qa="true" data-index="N">
+<section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;">
       <div class="stacked-grid">

package/lib/commands/help.ts

@@ -28,7 +28,9 @@ export async function handleHelp(
     `\`/revela disable\`             — disable slide generation mode\n` +
     `\`/revela init\`                — initialize or refresh workspace DECKS.json\n` +
     `\`/revela review\`              — review current deck readiness before writing HTML\n` +
+    `\`/revela refine\`              — open unified Edit/Inspect refinement workspace\n` +
     `\`/revela edit\`                — open visual editor for the only deck in decks/\n` +
+    `\`/revela inspect\`             — open Evidence Inspector for click-to-inspect review\n` +
     `\`/revela remember <text>\`     — save an explicit preference to DECKS.json\n` +
     `\`/revela designs\`             — list installed designs\n` +
     `\`/revela designs <name>\`      — activate a design\n` +

package/lib/commands/inspect.ts

@@ -0,0 +1,23 @@
+import { openInspectDeck } from "../inspect/open"
+
+export async function handleInspect(
+  options: { client: any; sessionID: string; workspaceRoot: string },
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  try {
+    const result = openInspectDeck("", {
+      client: options.client,
+      sessionID: options.sessionID,
+      workspaceRoot: options.workspaceRoot,
+    })
+    await send(
+      `Opened Evidence Inspector for the only deck in \`decks/\`.\n` +
+      `File: \`${result.deck.file}\`\n` +
+      `${result.stateNote}\n` +
+      `URL: ${result.url}\n\n` +
+      `Use Ctrl/Cmd-click in the browser to reference deck elements exactly like /revela edit, then click Inspect Selection. Deterministic Source/Purpose preprocessing appears first, followed by lazy LLM-generated cards. Selection is locked while the request is processed. There is no chat box or freeform prompt.`
+    )
+  } catch (e: any) {
+    await send(`**Inspect failed:** ${e.message || String(e)}`)
+  }
+}

package/lib/commands/refine.ts

@@ -0,0 +1,26 @@
+import { openRefineDeck } from "../refine/open"
+import type { RefineMode } from "../refine/server"
+
+export async function handleRefine(
+  options: { client: any; sessionID: string; workspaceRoot: string; mode?: RefineMode },
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  try {
+    const result = openRefineDeck("", {
+      client: options.client,
+      sessionID: options.sessionID,
+      workspaceRoot: options.workspaceRoot,
+      mode: options.mode ?? "edit",
+    })
+
+    await send(
+      `Opened Revela Refine for the only deck in \`decks/\`.\n` +
+      `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 Edit tab sends targeted change comments; the Inspect tab reviews the same selection with Source/Purpose cards and does not edit the deck.`
+    )
+  } catch (e: any) {
+    await send(`**Refine failed:** ${e.message || String(e)}`)
+  }
+}

package/lib/commands/review.ts

@@ -22,6 +22,9 @@ Goal:
 - For substantial decision decks, use the read-only Task subagent \`revela-narrative-reviewer\` for independent rubric-based critique of narrative brief and slide-plan alignment. Do not self-certify semantic narrative quality in the primary agent.
 - Treat \`revela-narrative-reviewer\` findings as advisory critique only. Do not represent them as \`revela-decks\` readiness issues, blockers, or authoritative \`writeReadiness\`.
 - 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.
+- When \`revela-decks review\` returns \`evidenceCandidates\`, treat them as conservative binding candidates only. They are not proof that the full slide is supported, and they are not automatically applied to \`slides[].evidence[]\`. If a candidate has \`sourceKind: "researchesFallback"\`, say it was discovered from workspace \`researches/\` files that are not currently referenced by \`researchPlan\`.
+- When an evidence candidate includes \`evidenceDraft\`, report it as a proposed slide evidence record with its \`candidateId\`; it still requires explicit user/agent confirmation before calling \`revela-decks\` action \`applyEvidenceCandidates\`. Also report \`unsupportedScope\` and \`recommendedRewrite\` so partial evidence is not stretched to future-state claims.
+- When a missing-evidence issue has \`evidenceCandidateSearch\`, use it to explain search coverage: which \`researchPlan\` findings were searched, which fallback \`researches/**/*.md\` files were searched, and any near misses that were below binding threshold.
 
 Current state:
 - ${state}
@@ -36,7 +39,7 @@ 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, researchPlan, and narrativeBrief if the story intent is clear. Do not invent or ask for a deck key; the tool uses the workspace folder name internally.
-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.
+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. The review tool may surface conservative \`evidenceCandidates\` for missing evidence by matching slide text against those findings files, and may fall back to bounded workspace \`researches/**/*.md\` discovery when the research plan has no matching findings file; report these as candidate bindings, not as already-bound evidence.
 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.
@@ -44,7 +47,7 @@ Workflow:
 8. For substantial decision decks, preserve a compact \`narrativeBrief\` through \`upsertDeck\` when the conversation or confirmed plan supports it. Do not invent stakeholder beliefs, objections, or risks; leave gaps visible if unknown.
 9. For substantial decision decks, launch the Task subagent with \`subagent_type: "revela-narrative-reviewer"\` after deck/slides are up to date. Ask it to read the current \`DECKS.json\`, run only its fixed rubric, use stable finding IDs, return \`Findings: none\` when all checks pass, and avoid optional pre-write improvements. Do not ask it to write state, call \`revela-decks review\`, or produce HTML.
 10. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` plus structured readiness issues for the current workspace deck.
-11. 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. If the reviewer returned findings, include them in a separate \`Narrative reviewer notes\` section and label them advisory.
+11. 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. If the review result includes \`evidenceCandidates\`, add a separate \`Candidate evidence bindings\` section with candidateId, slide index/title, supported claim scope, sourceKind, findingsFile/sourcePath, quote/snippet, caveat, evidenceDraft summary, unsupportedScope, and recommendedRewrite. Tell the user they may explicitly ask to apply selected candidate IDs; do not apply them during review. If candidates are absent but \`evidenceCandidateSearch\` is present, briefly report searched file counts and the best near misses so the user can tell whether review failed to search or searched but did not find a bindable match. If the reviewer returned findings, include them in a separate \`Narrative reviewer notes\` section and label them advisory.
 
 Minimum conditions for \`ready\`:
 - Topic, audience, slide count, language, and visual style/design are decided.
@@ -68,6 +71,9 @@ Report format:
 - Do not invent evidence or silently downgrade blockers. Use the tool result as authoritative.
 - Do not convert \`revela-narrative-reviewer\` advisory findings into tool readiness issues. Keep them separate from \`revela-decks review\` blockers and warnings, and preserve the reviewer's stable finding IDs when reporting them.
 - 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.
+- When reporting candidate evidence bindings, distinguish partial support from full-slide support. Never say a candidate supports unrelated future-state, recommendation, roadmap, or product-vision claims unless the candidate explicitly supports those claims.
+- Treat \`evidenceDraft\` as a proposed record, not a mutation. Do not call \`upsertSlides\` to bind it. Only call \`revela-decks\` action \`applyEvidenceCandidates\` with explicit \`candidateIds\` if the user asks to apply candidate bindings.
+- When reporting candidate search diagnostics, do not present near misses as evidence. Say they are below binding threshold and use them only to explain why no candidate was returned.
 
 Rules:
 - Do not write or overwrite \`decks/*.html\` during review.