@cyber-dash-tech/revela 0.9.0 → 0.11.0

package/README.md

@@ -2,14 +2,14 @@
 
 **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-178%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-302%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="800" />
 </p>
 
-Revela is an [OpenCode](https://opencode.ai) plugin that turns your current agent into an HTML slide deck generator.
-Enable it for the current session, assign a presentation task, and the agent can research, structure, write, QA, and export a deck.
+Revela is an [OpenCode](https://opencode.ai) plugin for building trusted narrative artifacts from workspace sources, research, evidence, and user intent.
+Its first render target is still the HTML slide deck: enable Revela for the current session, assign a presentation task, and the agent can research, structure, write, QA, inspect, refine, and export a deck.
 
 **[Live Demo — The AI Power Shift](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)**
 
@@ -20,8 +20,10 @@ 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
-- keeps track of deck context, slide structure, sources, and readiness across the current workspace
+- keeps `DECKS.json` as the current workspace state engine for sources, research actions, findings, claims, evidence, narrative intent, render targets, and readiness
 - checks for missing context, weak evidence, and incomplete structure before writing `decks/*.html`
+- records review snapshots so stale readiness cannot silently authorize new deck HTML after important state changes
+- treats HTML decks, PDF, and PPTX as render targets from shared workspace state rather than isolated output files
 - 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
@@ -140,7 +142,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 +163,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.
 
 ---
 
@@ -176,6 +180,22 @@ That prompt is built from 3 layers:
 Persistent preferences live in `~/.config/revela/config.json`.
 The enabled or disabled state is session-level only.
 
+### Workspace State
+
+`DECKS.json` is Revela's workspace state engine and compatibility file. It is still stored at the workspace root and remains readable as the current deck project state, but internally Revela now treats it as a lightweight persistence layer for more than a deck checklist.
+
+The state records:
+
+- workspace source materials and reusable extraction cache paths
+- research plans, saved findings, and compact action provenance
+- narrative intent, objections, risks, slide specs, claim candidates, and slide-level evidence trace
+- render targets such as the active HTML deck plus derived PDF and PPTX artifacts
+- review snapshots with input hashes so old readiness results become stale after meaningful state changes
+
+0.11 keeps backward compatibility with existing root `DECKS.json` workspaces. Running `/revela init` or `/revela review` on an older project can normalize and refresh the new projection fields without requiring a manual migration, moving files, or replacing `DECKS.json` with a database.
+
+Decks remain the primary authored artifact, but they are now treated as render targets from the same workspace state that can later support briefs, appendix material, Evidence Inspector views, Q&A, and interactive reading layers without duplicating source/evidence logic.
+
 ---
 
 ## Recommended Workflow
@@ -188,12 +208,13 @@ 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.
 
-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.
+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. In 0.11, review results are also saved as input-hashed snapshots; if sources, slide specs, evidence, narrative state, or the active render target changes afterward, the old review can no longer silently authorize a write.
 
 To remember long-term preferences, use:
 
@@ -558,6 +579,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 +595,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 +603,22 @@ 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.
+
+Inspection and refinement use the active HTML deck render target recorded in workspace state. The deck HTML must satisfy Revela's slide identity contract: every `<section class="slide">` in the active artifact needs a positive 1-based `data-slide-index` matching the current slide specs. Invalid active artifacts are refused or reported before inspect/refine/export workflows trust them.
+
+---
+
 ## Export
 
 PDF export:

package/README.zh-CN.md

@@ -2,14 +2,14 @@
 
 [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-178%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-302%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="800" />
 </p>
 
-Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使用的 agent 变成 HTML 幻灯片生成器。
-在当前会话中启用之后，agent 可以完成调研、结构设计、HTML 写作、QA 和导出。
+Revela 是一个 [OpenCode](https://opencode.ai) 插件，用来把工作区来源材料、调研、证据和用户意图转成可信的叙事型沟通 artifact。
+它的第一个 render target 仍然是 HTML slide deck：在当前会话中启用之后，agent 可以完成调研、结构设计、HTML 写作、QA、检查、refine 和导出。
 
 **[在线演示 — AI 权力转移](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)**
 
@@ -20,8 +20,10 @@ Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使
 - 通过 `/revela enable` 向当前 agent 注入演示文稿专用 system prompt
 - prompt 由 3 层组成：核心 skill、当前 domain、当前 design
 - 支持工作区文档扫描，以及 `.pdf`、`.docx`、`.pptx`、`.xlsx` 的透明文本提取和嵌入素材缓存提取
-- 在当前工作区持续跟踪 deck 背景、页面结构、来源材料和 readiness
+- 将 `DECKS.json` 作为当前 workspace state engine，持续记录来源材料、调研动作、findings、claims、证据、叙事意图、render targets 和 readiness
 - 写入 `decks/*.html` 前检查是否缺上下文、证据或结构
+- 记录 review snapshots，避免重要状态变化后旧的 ready 结果继续默默授权写入 deck HTML
+- 把 HTML deck、PDF 和 PPTX 视为来自同一 workspace state 的 render targets，而不是互相孤立的输出文件
 - agent 每次写入、patch 或 edit `decks/*.html` 时自动执行快速 design compliance 检查
 - 为已有 deck 打开可视化评论编辑器，用户可以 Ctrl/Cmd + 点击元素，并把精确修改意见发回 OpenCode
 - 支持导出成 PDF 和可编辑 PPTX
@@ -139,7 +141,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 +162,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。
 
 ---
 
@@ -175,6 +179,22 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 持久化配置保存在 `~/.config/revela/config.json`。
 是否启用 Revela 则只在当前会话生效。
 
+### Workspace State
+
+`DECKS.json` 是 Revela 当前的 workspace state engine，也是兼容旧工作流的状态文件。它仍然保存在工作区根目录，也仍然可以理解为当前 deck 项目的状态入口，但 Revela 内部已经不再把它当成单纯的 deck checklist。
+
+状态中会记录：
+
+- 工作区来源材料和可复用的 extraction cache 路径
+- 调研计划、已保存 findings，以及精简的 action provenance
+- narrative intent、objections、risks、slide specs、claim candidates 和 slide-level evidence trace
+- active HTML deck 以及派生 PDF、PPTX 等 render targets
+- 带 input hash 的 review snapshots，使重要状态变化后旧的 readiness 自动变 stale
+
+0.11 继续兼容已有的根目录 `DECKS.json` 工作区。对旧项目运行 `/revela init` 或 `/revela review` 时，可以安全 normalize 并刷新新的 projection 字段；用户不需要手动迁移、不需要移动文件，也不需要把 `DECKS.json` 换成数据库。
+
+Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace state 渲染出来的目标之一。后续 briefs、appendix material、Evidence Inspector views、Q&A 和 interactive reading layers 都可以复用同一套来源/证据逻辑，而不是各自生成孤立内容。
+
 ---
 
 ## 推荐使用流程
@@ -187,12 +207,13 @@ 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。
 
-如果 Revela 阻止写入 deck，直接让 agent 运行 `/revela review`，根据报告补齐缺口后再写。这样可以避免在计划、证据或结构还不完整时覆盖真实 deck 文件。
+如果 Revela 阻止写入 deck，直接让 agent 运行 `/revela review`，根据报告补齐缺口后再写。这样可以避免在计划、证据或结构还不完整时覆盖真实 deck 文件。0.11 还会把 review 结果保存为带 input hash 的 snapshot；如果之后来源材料、slide specs、证据、叙事状态或 active render target 发生变化，旧 review 不能继续默默授权写入。
 
 记住长期偏好请使用：
 
@@ -523,6 +544,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 +560,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 +568,22 @@ 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 卡片，不会强行生成编辑动作。
+
+Inspect 和 refine 会使用 workspace state 中记录的 active HTML deck render target。Deck HTML 必须满足 Revela 的 slide identity contract：active artifact 中每个 `<section class="slide">` 都需要有正数、1-based 的 `data-slide-index`，并且要匹配当前 slide specs。无效的 active artifact 会在 inspect/refine/export 工作流信任它之前被拒绝或报告。
+
+---
+
 ## 导出
 
 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 active HTML deck.\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/pdf.ts

@@ -8,28 +8,41 @@
  */
 
 import { resolve } from "path"
+import { hasDecksState, readDecksState } from "../decks-state"
 import { exportToPdf } from "../pdf/export"
 import { assertExportQAPassed } from "../qa/export-gate"
+import { recordRenderedArtifact, workspaceRelative } from "../workspace-state/rendered-artifacts"
+import { resolveActiveHtmlDeckPath } from "../workspace-state/render-targets"
 
 export async function handlePdf(
   filePath: string,
   send: (text: string) => Promise<void>,
+  workspaceRoot = process.cwd(),
 ): Promise<void> {
-  if (!filePath) {
+  const root = resolve(workspaceRoot)
+  const resolvedFile = resolvePdfDeckFile(root, filePath)
+
+  if (!resolvedFile) {
     await send(
-      "**Usage:** `/revela pdf <file_path>`\n\n" +
+      "**Usage:** `/revela pdf [file_path]`\n\n" +
       "Example: `/revela pdf decks/my-deck.html`"
     )
     return
   }
 
-  const abs = resolve(filePath)
+  const abs = resolvedFile.absoluteFile
   await send(`Running pre-export QA for \`${abs}\`...`)
 
   try {
-    await assertExportQAPassed(abs)
+    await assertExportQAPassed(abs, { workspaceRoot: root })
     await send(`Exporting \`${abs}\` to PDF...`)
-    const result = await exportToPdf(filePath)
+    const result = await exportToPdf(abs)
+    recordRenderedArtifact(root, {
+      sourceHtmlPath: resolvedFile.file,
+      outputPath: result.outputPath,
+      type: "pdf",
+      actor: "revela-pdf",
+    })
     const secs = (result.durationMs / 1000).toFixed(1)
     await send(
       `**PDF exported successfully**\n\n` +
@@ -42,3 +55,18 @@ export async function handlePdf(
     await send(`**PDF export failed**\n\n\`\`\`\n${msg}\n\`\`\``)
   }
 }
+
+function resolvePdfDeckFile(workspaceRoot: string, filePath: string): { file: string; absoluteFile: string } | undefined {
+  const explicit = filePath.trim()
+  if (explicit) {
+    const absoluteFile = resolve(workspaceRoot, explicit)
+    return { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile }
+  }
+
+  if (!hasDecksState(workspaceRoot)) return undefined
+  const state = readDecksState(workspaceRoot)
+  const activePath = resolveActiveHtmlDeckPath(state)
+  if (!activePath) return undefined
+  const absoluteFile = resolve(workspaceRoot, activePath)
+  return { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile }
+}