@cyber-dash-tech/revela 0.15.3 → 0.15.4

package/README.md

@@ -126,7 +126,7 @@ Export when needed, either manually or by asking the agent to export:
 /revela story                    open the read-only story workspace UI
 /revela make --deck              make a deck from approved story state
 /revela make --brief [file.md]   render executive brief from approved story
-/revela refine --deck            open unified deck reading, inspection, and editing workspace
+/revela review --deck            open unified deck reading, insight, and comment workspace
 /revela export --deck pdf [file] export an HTML deck to PDF in the same directory
 /revela export --deck pptx [file] [--notes] export an HTML deck to editable PPTX
 
@@ -144,7 +144,7 @@ Export when needed, either manually or by asking the agent to export:
 /revela domain --rm <name>       remove an installed domain
 ```
 
-Most `/revela` commands run locally with zero LLM cost. `/revela init`, `/revela research`, `/revela story`, `/revela make --deck`, `/revela design --new`, `/revela design --edit`, and `/revela export --deck pptx --notes` start AI-assisted workflows because they need to read or update project files. These workflow commands keep the visible chat message short and inject their detailed instructions through a one-shot system-prompt command intent. `/revela refine --deck` is the unified post-artifact workspace. It 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 sends grounded selection context to the current OpenCode session and renders localized Narrative Reading, Exploratory Reading, Source, and Purpose cards, has no chat box, and does not edit the deck. Deterministic preprocessing is kept as fallback context rather than the normal first UI. If a generated result omits newer reading cards, Refine keeps the deterministic Narrative Reading and Exploratory Reading cards instead of dropping context. Narrative Reading also shows artifact coverage for the selected canonical claim, including whether each recorded artifact contains the claim and whether coverage is current, stale, partial, or missing. Exploratory Reading is explicitly non-official and bounded to recorded claims, evidence, caveats, objections, risks, and artifact coverage. `/revela edit` and `/revela inspect` are no longer public commands; use `/revela refine --deck` instead.
+Most `/revela` commands run locally with zero LLM cost. `/revela init`, `/revela research`, `/revela story`, `/revela make --deck`, `/revela design --new`, `/revela design --edit`, and `/revela export --deck pptx --notes` start AI-assisted workflows because they need to read or update project files. These workflow commands keep the visible chat message short and inject their detailed instructions through a one-shot system-prompt command intent. `/revela review --deck` is the unified post-artifact workspace. It opens a local browser workspace with Comment and Insight tabs that share the same Cmd/Ctrl-click element references. Comment sends targeted comments back into the current OpenCode session; Insight sends grounded selection context to the current OpenCode session and renders localized Narrative Reading, Exploratory Reading, Source, and Purpose cards, has no chat box, and does not edit the deck. Deterministic preprocessing is kept as fallback context rather than the normal first UI. If a generated result omits newer reading cards, Review keeps the deterministic Narrative Reading and Exploratory Reading cards instead of dropping context. Narrative Reading also shows artifact coverage for the selected canonical claim, including whether each recorded artifact contains the claim and whether coverage is current, stale, partial, or missing. Exploratory Reading is explicitly non-official and bounded to recorded claims, evidence, caveats, objections, risks, and artifact coverage. `/revela edit` and `/revela inspect` are no longer public commands; use `/revela review --deck` instead. `/revela refine --deck` remains a compatibility alias.
 
 ---
 
@@ -152,7 +152,7 @@ Most `/revela` commands run locally with zero LLM cost. `/revela init`, `/revela
 
 Explicit Revela workflow commands append one-shot command instructions to the current agent's system prompt and choose the needed prompt mode automatically.
 
-The default prompt is narrative-first: it follows `Init -> Research -> Story -> Make -> Refine -> Export` and focuses on audience belief shift, decision/action, thesis, claims, evidence boundaries, objections, risks, research gaps, and approval. Active design CSS, layout catalogs, component indexes, chart rules, and deck HTML skeletons are intentionally omitted until `/revela make --deck` switches the session into deck-render mode or `/revela design` starts explicit design work.
+The default prompt is narrative-first: it follows `Init -> Research -> Story -> Make -> Review -> Export` and focuses on audience belief shift, decision/action, thesis, claims, evidence boundaries, objections, risks, research gaps, and approval. Active design CSS, layout catalogs, component indexes, chart rules, and deck HTML skeletons are intentionally omitted until `/revela make --deck` switches the session into deck-render mode or `/revela design` starts explicit design work.
 
 Deck-render mode is built from 2 layers:
 
@@ -195,8 +195,8 @@ Use Revela as a narrative-first artifact workflow:
 5. Run `/revela make --deck` to compile the approved narrative into deck slide specs and enter deck-render mode, or `/revela make --brief` to render an executive brief.
 6. Choose or confirm design only during deck handoff; `/revela make --deck` runs the deck/artifact gate after plan confirmation.
 7. Let the agent write the HTML deck under `decks/` only after the artifact gate is ready.
-8. Use `/revela refine --deck` for visual comments, targeted revisions, read-only Narrative Reading, bounded Exploratory Reading, Source, and Purpose inspection, and claim-to-artifact coverage for selected deck elements.
-9. Use `/revela refine --deck` for post-artifact changes; `/revela edit` and `/revela inspect` are no longer public commands.
+8. Use `/revela review --deck` for visual comments, targeted revisions, read-only Narrative Reading, bounded Exploratory Reading, Source, and Purpose insight, and claim-to-artifact coverage for selected deck elements.
+9. Use `/revela review --deck` for post-artifact changes; `/revela edit` and `/revela inspect` are no longer public commands.
 10. Export with `/revela export --deck pdf <file>` or `/revela export --deck pptx <file>`.
 
 `/revela story` opens the read-only story workspace UI for unclear audience, missing belief shift, missing decision/action, weak thesis, unsupported central claims, weak evidence, unsupported scope, unhandled objections, missing risk/assumption handling, stale approval, or missing approval. It does not review design/layout readiness or write the final deck.
@@ -561,10 +561,10 @@ A custom domain is a folder containing `INDUSTRY.md`.
 Use the unified refinement workspace for normal post-write review and revision:
 
 ```text
-/revela refine --deck
+/revela review --deck
 ```
 
-`/revela refine --deck` opens the active HTML deck 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 Narrative Reading, bounded Exploratory Reading, Source, Purpose, and artifact coverage review. Inspect does not mutate the deck; Edit remains the mutation path. This is the recommended entry for post-artifact reading, inspection, and editing.
+`/revela review --deck` opens the active HTML deck with two tabs. Use `Ctrl`/`Cmd` + click once to reference deck elements, then choose Comment for fast natural-language change comments or Insight for read-only Narrative Reading, bounded Exploratory Reading, Source, Purpose, and artifact coverage review. Insight does not mutate the deck; Comment remains the mutation path. This is the recommended entry for post-artifact reading, insight, and commenting.
 
 Removed command:
 
@@ -572,29 +572,29 @@ Removed command:
 /revela edit
 ```
 
-`/revela edit` has been removed. Use `/revela refine --deck` for the unified reading, inspection, and editing workspace.
+`/revela edit` has been removed. Use `/revela review --deck` for the unified reading, insight, and comment workspace.
 
-Use `Ctrl`/`Cmd` + click to reference deck elements, write a natural-language comment in the Edit tab, 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.
+Use `Ctrl`/`Cmd` + click to reference deck elements, write a natural-language comment in the Comment tab, 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. The tool remains a compatibility shim and opens Refine in Edit mode when you say things like “I want to edit the deck”.
+LLM tool equivalent: `revela-edit` with no target. The tool remains a compatibility shim and opens Review in Comment mode when you say things like “I want to edit the deck”.
 
-For existing decks, `/revela refine --deck` prepares whatever minimal project context is needed so targeted edits can still use the normal safety checks.
+For existing decks, `/revela review --deck` prepares whatever minimal project context is needed so targeted edits can still use the normal safety checks.
 
 ---
 
 ## Evidence Inspector
 
-Use `/revela refine --deck` for evidence inspection and narrative reading. Removed compatibility command:
+Use `/revela review --deck` for evidence insight and narrative reading. Removed compatibility command:
 
 ```text
 /revela inspect
 ```
 
-`/revela inspect` no longer opens a separate inspector shell. Use `/revela refine --deck` and the Inspect tab. The Inspect tab shows Narrative Reading and Exploratory Reading cards alongside the fixed Source and Purpose cards. Narrative Reading preserves canonical claim ids, evidence binding ids, supported scope, unsupported scope, caveats, objections, risks, and artifact coverage when the selected element maps to canonical narrative state. Coverage shows whether the selected claim appears in recorded deck/brief/export artifacts and whether those artifacts are current, stale, partial, or missing against the current narrative hash. Exploratory Reading provides non-official objection prep, audience reframing boundaries, appendix leads, and meeting-prep cues from the same recorded context only. Use `Ctrl`/`Cmd` + click to reference deck elements, then click `Inspect Selection`. Selection is locked while the request is being processed.
+`/revela inspect` no longer opens a separate inspector shell. Use `/revela review --deck` and the Insight tab. The Insight tab shows Narrative Reading and Exploratory Reading cards alongside the fixed Source and Purpose cards. Narrative Reading preserves canonical claim ids, evidence binding ids, supported scope, unsupported scope, caveats, objections, risks, and artifact coverage when the selected element maps to canonical narrative state. Coverage shows whether the selected claim appears in recorded deck/brief/export artifacts and whether those artifacts are current, stale, partial, or missing against the current narrative hash. Exploratory Reading provides non-official objection prep, audience reframing boundaries, appendix leads, and meeting-prep cues from the same recorded context only. Use `Ctrl`/`Cmd` + click to reference deck elements, then click `Get Insight`. 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. Inspect is LLM-first in the UI: it shows a reading/loading state, then renders structured generated cards. Deterministic preprocessing remains internal fallback context and is shown only if generation fails or times out. The Inspect tab includes a fixed display-language selector; language changes affect card copy only and never alter claim ids, evidence ids, source paths, URLs, numbers, quotes, or canonical facts. When an older or partial generated result only returns Source/Purpose, Refine preserves the deterministic reading cards so generated inspection cannot silently remove claim, evidence-boundary, artifact-coverage, or exploratory context.
+The insight surface 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. Insight is LLM-first in the UI: it shows a reading/loading state, then renders structured generated cards. Deterministic preprocessing remains internal fallback context and is shown only if generation fails or times out. The Insight tab includes a fixed display-language selector; language changes affect card copy only and never alter claim ids, evidence ids, source paths, URLs, numbers, quotes, or canonical facts. When an older or partial generated result only returns Source/Purpose, Review preserves the deterministic reading cards so generated insight cannot silently remove claim, evidence-boundary, artifact-coverage, or exploratory context.
 
-Refine uses 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 refine/export workflows trust them.
+Review uses 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 review/export workflows trust them.
 
 ---
 

package/README.zh-CN.md

@@ -125,7 +125,7 @@ export { default } from "/absolute/path/to/revela/index.ts";
 /revela story                    打开只读 story workspace UI
 /revela make --deck              从已批准 story 生成 deck
 /revela make --brief [file.md]   从已批准 story 渲染 executive brief
-/revela refine --deck            打开统一的 deck 阅读、检查和编辑 workspace
+/revela review --deck            打开统一的 deck 阅读、洞察和评论 workspace
 /revela export --deck pdf [file] 将 HTML deck 导出为同目录 PDF
 /revela export --deck pptx [file] [--notes] 将 HTML deck 导出为可编辑 PPTX
 
@@ -143,7 +143,7 @@ export { default } from "/absolute/path/to/revela/index.ts";
 /revela domain --rm <name>       删除已安装 domain
 ```
 
-大多数 `/revela` 命令都在本地执行，不消耗 LLM token。`/revela init`、`/revela research`、`/revela story`、`/revela make --deck`、`/revela design --new`、`/revela design --edit` 和 `/revela export --deck pptx --notes` 会启动 AI 辅助流程，因为它们需要读取或更新项目状态。这些 workflow command 只在可见聊天里显示短意图，详细内部说明通过一次性的 system-prompt command intent 注入。`/revela refine --deck` 是统一的 post-artifact workspace，会打开一个本地浏览器 workspace，里面有 Edit 和 Inspect 两个 tab，并共享同一套 Cmd/Ctrl-click 元素引用。Edit 会把精准修改评论发回当前 OpenCode 会话；Inspect 会把 grounded selection context 发给当前 OpenCode 会话，并渲染本地化的 Narrative Reading、Exploratory Reading、Source、Purpose 卡片。确定性预处理保留为 fallback context，而不是默认先展示的 UI。如果生成结果缺少较新的 reading 卡片，Refine 会保留确定性 Narrative Reading 和 Exploratory Reading，而不是丢掉这些上下文。Narrative Reading 还会显示所选 canonical claim 的 artifact coverage，包括每个已记录 artifact 是否包含该 claim，以及 coverage 是 current、stale、partial 还是 missing。Exploratory Reading 明确是非官方阅读辅助，只能基于已记录 claim、evidence、caveat、objection、risk 和 artifact coverage。它没有聊天框，也不会修改 deck。`/revela edit` 和 `/revela inspect` 不再是公开命令；请使用 `/revela refine --deck`。
+大多数 `/revela` 命令都在本地执行，不消耗 LLM token。`/revela init`、`/revela research`、`/revela story`、`/revela make --deck`、`/revela design --new`、`/revela design --edit` 和 `/revela export --deck pptx --notes` 会启动 AI 辅助流程，因为它们需要读取或更新项目状态。这些 workflow command 只在可见聊天里显示短意图，详细内部说明通过一次性的 system-prompt command intent 注入。`/revela review --deck` 是统一的 post-artifact workspace，会打开一个本地浏览器 workspace，里面有 Comment 和 Insight 两个 tab，并共享同一套 Cmd/Ctrl-click 元素引用。Comment 会把精准修改评论发回当前 OpenCode 会话；Insight 会把 grounded selection context 发给当前 OpenCode 会话，并渲染本地化的 Narrative Reading、Exploratory Reading、Source、Purpose 卡片。确定性预处理保留为 fallback context，而不是默认先展示的 UI。如果生成结果缺少较新的 reading 卡片，Review 会保留确定性 Narrative Reading 和 Exploratory Reading，而不是丢掉这些上下文。Narrative Reading 还会显示所选 canonical claim 的 artifact coverage，包括每个已记录 artifact 是否包含该 claim，以及 coverage 是 current、stale、partial 还是 missing。Exploratory Reading 明确是非官方阅读辅助，只能基于已记录 claim、evidence、caveat、objection、risk 和 artifact coverage。它没有聊天框，也不会修改 deck。`/revela edit` 和 `/revela inspect` 不再是公开命令；请使用 `/revela review --deck`。`/revela refine --deck` 仍作为兼容 alias 保留。
 
 ---
 
@@ -151,7 +151,7 @@ export { default } from "/absolute/path/to/revela/index.ts";
 
 显式 Revela workflow command 会把一次性 command instructions 追加到当前 agent 的 system prompt 中。你不需要先运行 ambient enable/disable；公开入口都在 `/revela` help 中列出。
 
-默认 prompt 是 narrative-first：它遵循 `Init -> Research -> Story -> Make -> Refine -> Export`，关注受众信念变化、decision/action、thesis、claims、证据边界、objections、risks、research gaps 和 approval。Active design CSS、layout catalog、component index、chart rules 和 deck HTML skeleton 在 `/revela make --deck` 切换到 deck-render mode 或 `/revela design` 进入显式设计工作流前不会注入。
+默认 prompt 是 narrative-first：它遵循 `Init -> Research -> Story -> Make -> Review -> Export`，关注受众信念变化、decision/action、thesis、claims、证据边界、objections、risks、research gaps 和 approval。Active design CSS、layout catalog、component index、chart rules 和 deck HTML skeleton 在 `/revela make --deck` 切换到 deck-render mode 或 `/revela design` 进入显式设计工作流前不会注入。
 
 Deck-render mode 由 2 层组成：
 
@@ -193,8 +193,8 @@ Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace s
 5. 运行 `/revela make --deck`，把已批准 narrative 编译成 deck slide specs 并进入 deck-render mode，或运行 `/revela make --brief` 渲染 executive brief。
 6. 只在 deck handoff 阶段选择或确认 design；`/revela make --deck` 会在 deck plan 确认后运行 deck/artifact gate。
 7. 只有 artifact gate ready 后，才让 agent 把 HTML deck 写到 `decks/` 下。
-8. 用 `/revela refine --deck` 对选中 deck 元素做可视化评论、精准修改、只读 Narrative Reading、有边界的 Exploratory Reading、Source、Purpose 检查，以及 claim-to-artifact coverage 查看。
-9. post-artifact 修改统一使用 `/revela refine --deck`；`/revela edit` 和 `/revela inspect` 不再是公开命令。
+8. 用 `/revela review --deck` 对选中 deck 元素做可视化评论、精准修改、只读 Narrative Reading、有边界的 Exploratory Reading、Source、Purpose 洞察，以及 claim-to-artifact coverage 查看。
+9. post-artifact 修改统一使用 `/revela review --deck`；`/revela edit` 和 `/revela inspect` 不再是公开命令。
 10. 用 `/revela export --deck pdf <file>` 或 `/revela export --deck pptx <file>` 导出。
 
 普通聊天不需要 ambient command。需要 Revela 工作流时，直接运行对应的 `/revela ...` 显式命令。
@@ -527,10 +527,10 @@ Prompt 注入规则：
 正常的写后 review 和修改建议使用统一 refinement workspace：
 
 ```text
-/revela refine --deck
+/revela review --deck
 ```
 
-`/revela refine --deck` 会打开 active HTML deck，并提供两个 tab。使用 `Ctrl`/`Cmd` + click 先引用 deck 元素，然后在 Edit 里快速写自然语言修改评论，或在 Inspect 里做只读 Narrative Reading、有边界的 Exploratory Reading、Source、Purpose 和 artifact coverage 检查。Inspect 不会修改 deck；真正的 mutation 仍然只走 Edit。这是 post-artifact 阅读、检查和编辑的推荐入口。
+`/revela review --deck` 会打开 active HTML deck，并提供两个 tab。使用 `Ctrl`/`Cmd` + click 先引用 deck 元素，然后在 Comment 里快速写自然语言修改评论，或在 Insight 里做只读 Narrative Reading、有边界的 Exploratory Reading、Source、Purpose 和 artifact coverage 检查。Insight 不会修改 deck；真正的 mutation 仍然只走 Comment。这是 post-artifact 阅读、洞察和评论的推荐入口。
 
 已移除命令：
 
@@ -538,29 +538,29 @@ Prompt 注入规则：
 /revela edit
 ```
 
-`/revela edit` 已移除。请使用 `/revela refine --deck` 打开统一的阅读、检查和编辑 workspace。
+`/revela edit` 已移除。请使用 `/revela review --deck` 打开统一的阅读、洞察和评论 workspace。
 
-使用 `Ctrl`/`Cmd` + 点击 deck 元素来引用它们，在 Edit tab 写一段自然语言评论，然后发送回 OpenCode。Revela 会把 deck 文件、slide 上下文、选中元素 metadata 和你的评论整理成结构化 edit prompt。
+使用 `Ctrl`/`Cmd` + 点击 deck 元素来引用它们，在 Comment tab 写一段自然语言评论，然后发送回 OpenCode。Revela 会把 deck 文件、slide 上下文、选中元素 metadata 和你的评论整理成结构化 edit prompt。
 
-对应的 LLM tool：`revela-edit`，不需要 target。这个 tool 仍作为兼容入口保留，当你说“我要编辑这个 deck”时，agent 会打开 Refine 的 Edit mode。
+对应的 LLM tool：`revela-edit`，不需要 target。这个 tool 仍作为兼容入口保留，当你说“我要编辑这个 deck”时，agent 会打开 Review 的 Comment mode。
 
-对于已有 HTML deck，`/revela refine --deck` 会自动准备必要的最小项目上下文，让后续精准修改仍然经过正常安全检查。
+对于已有 HTML deck，`/revela review --deck` 会自动准备必要的最小项目上下文，让后续精准修改仍然经过正常安全检查。
 
 ---
 
 ## Evidence Inspector
 
-用 `/revela refine --deck` 做 evidence inspection 和 narrative reading。已移除的兼容命令：
+用 `/revela review --deck` 做 evidence insight 和 narrative reading。已移除的兼容命令：
 
 ```text
 /revela inspect
 ```
 
-`/revela inspect` 不再打开独立 inspector shell。请使用 `/revela refine --deck` 的 Inspect tab。Inspect tab 会在固定 Source 和 Purpose 卡片之外显示 Narrative Reading 和 Exploratory Reading 卡片。当选中元素能映射到 canonical narrative state 时，Narrative Reading 会保留 canonical claim id、evidence binding id、supported scope、unsupported scope、caveat、objection、risk 和 artifact coverage。Coverage 会显示所选 claim 是否出现在已记录的 deck/brief/export artifact 中，以及这些 artifact 相对当前 narrative hash 是 current、stale、partial 还是 missing。Exploratory Reading 提供非官方的 objection prep、audience reframing 边界、appendix leads 和 meeting-prep cues，并且只能使用同一份已记录 context。使用 `Ctrl`/`Cmd` + click 引用 deck 元素，然后点击 `Inspect Selection`。请求处理期间，deck 选择会被锁定。
+`/revela inspect` 不再打开独立 inspector shell。请使用 `/revela review --deck` 的 Insight tab。Insight tab 会在固定 Source 和 Purpose 卡片之外显示 Narrative Reading 和 Exploratory Reading 卡片。当选中元素能映射到 canonical narrative state 时，Narrative Reading 会保留 canonical claim id、evidence binding id、supported scope、unsupported scope、caveat、objection、risk 和 artifact coverage。Coverage 会显示所选 claim 是否出现在已记录的 deck/brief/export artifact 中，以及这些 artifact 相对当前 narrative hash 是 current、stale、partial 还是 missing。Exploratory Reading 提供非官方的 objection prep、audience reframing 边界、appendix leads 和 meeting-prep cues，并且只能使用同一份已记录 context。使用 `Ctrl`/`Cmd` + click 引用 deck 元素，然后点击 `Get Insight`。请求处理期间，deck 选择会被锁定。
 
-Inspector 不是聊天，也没有自由输入框。它不会修改 `DECKS.json` 或 deck HTML。它使用已记录的 slide spec、narrative state 和 slide-level evidence trace 作为 grounded context。Inspect 的用户界面是 LLM-first：先显示 reading/loading 状态，再渲染结构化生成卡片。确定性预处理仍作为内部 fallback context，仅在生成失败或超时时显示。Inspect tab 提供固定 display-language 下拉选项；语言只影响卡片文案，不会改变 claim id、evidence id、source path、URL、数字、引用或 canonical facts。如果旧版或不完整的生成结果只返回 Source/Purpose，Refine 会保留确定性 reading 卡片，避免 generated inspection 静默移除 claim、evidence boundary、artifact coverage 或 exploratory context。
+Insight 不是聊天，也没有自由输入框。它不会修改 `DECKS.json` 或 deck HTML。它使用已记录的 slide spec、narrative state 和 slide-level evidence trace 作为 grounded context。Insight 的用户界面是 LLM-first：先显示 reading/loading 状态，再渲染结构化生成卡片。确定性预处理仍作为内部 fallback context，仅在生成失败或超时时显示。Insight tab 提供固定 display-language 下拉选项；语言只影响卡片文案，不会改变 claim id、evidence id、source path、URL、数字、引用或 canonical facts。如果旧版或不完整的生成结果只返回 Source/Purpose，Review 会保留确定性 reading 卡片，避免 generated insight 静默移除 claim、evidence boundary、artifact coverage 或 exploratory context。
 
-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 会在 refine/export 工作流信任它之前被拒绝或报告。
+Review 会使用 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 会在 review/export 工作流信任它之前被拒绝或报告。
 
 ---
 

package/lib/commands/edit.ts

@@ -3,5 +3,5 @@ export async function handleEdit(
   send: (text: string) => Promise<void>,
 ): Promise<void> {
   void options
-  await send("`/revela edit` has been removed. Use `/revela refine --deck` for the unified reading, inspection, and editing workspace.")
+  await send("`/revela edit` has been removed. Use `/revela review --deck` and the Comment tab for the unified deck review workspace.")
 }

package/lib/commands/help.ts

@@ -30,7 +30,7 @@ export async function handleHelp(
     `2. \`research\` — close evidence gaps and bind support\n` +
     `3. \`story\` — inspect audience, thesis, claims, evidence, risks, and approval\n` +
     `4. \`make\` — generate deck or brief from approved story state\n` +
-    `5. \`refine\` — inspect and edit rendered deck artifacts\n` +
+    `5. \`review\` — comment on and inspect rendered deck artifacts\n` +
     `6. \`export\` — export deck artifacts to PDF or PPTX\n\n` +
     `---\n\n` +
     `**Commands**\n\n` +
@@ -40,7 +40,7 @@ export async function handleHelp(
     `\`/revela story [-l language]\`                   — open the read-only story workspace UI\n` +
     `\`/revela make --deck\`                          — make a deck from approved story state\n` +
     `\`/revela make --brief [file.md]\`                — render executive brief from approved story\n` +
-    `\`/revela refine --deck\`                        — open deck reading, inspection, and editing workspace\n` +
+    `\`/revela review --deck\`                        — open deck reading, insight, and comment workspace\n` +
     `\`/revela export --deck pdf [file.html]\`         — export HTML deck to PDF\n` +
     `\`/revela export --deck pptx [file.html] [--notes]\` — export HTML deck to PPTX\n` +
     `\`/revela design\`                               — list installed designs\n` +

package/lib/commands/inspect.ts

@@ -3,5 +3,5 @@ export async function handleInspect(
   send: (text: string) => Promise<void>,
 ): Promise<void> {
   void options
-  await send("`/revela inspect` is no longer a public command. Use `/revela refine --deck` and the Inspect tab for grounded Source/Purpose/Narrative Reading.")
+  await send("`/revela inspect` is no longer a public command. Use `/revela review --deck` and the Insight tab for grounded Source/Purpose/Narrative Reading.")
 }

package/lib/commands/refine.ts

@@ -14,13 +14,13 @@ export async function handleRefine(
     })
 
     await send(
-      `Opened Revela Refine for the active HTML deck.\n` +
+      `Opened Revela Review 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. The Edit tab sends targeted change comments; the Inspect tab reviews the same selection with Source/Purpose cards and does not edit the deck.`
+      `Use Ctrl/Cmd-click in the browser to reference deck elements. The Comment tab sends targeted change comments; the Insight 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)}`)
+    await send(`**Review failed:** ${e.message || String(e)}`)
   }
 }

package/lib/commands/review.ts

@@ -102,7 +102,7 @@ Workflow:
 11. Call \`revela-decks\` action \`review\` as the artifact gate. It computes \`writeReadiness\` and review snapshots for deck HTML writing. If it reports \`slide_plan_unconfirmed\`, stop and ask for explicit deck-plan confirmation.
 12. Write \`decks/*.html\` only if the deck/artifact gate is ready and all deck HTML contract requirements can be satisfied. Generate the artifact chapter by chapter instead of drafting all content slides in one broad pass. Keep the HTML file valid after every write, preserve already-written slides, and update one chapter's slide sections at a time.
 13. For each chapter, make every content slide carry a distinct claim, evidence item, comparison, risk, or action. If a chapter lacks enough substance for its allocated slides, merge weak slides or reduce the slide count instead of creating sparse filler.
-14. After each HTML write, the system automatically runs artifact QA before opening Refine. If post-write artifact QA reports hard errors, fix them and let QA run again. Refine opens only after hard errors pass. Density warnings about thin claim/evidence substance should be reported and improved when useful, but they do not block Refine.
+14. After each HTML write, the system automatically runs artifact QA before opening Review. If post-write artifact QA reports hard errors, fix them and let QA run again. Review opens only after hard errors pass. Density warnings about thin claim/evidence substance should be reported and improved when useful, but they do not block Review.
 
 Deck plan report format:
 - Start with \`Deck plan: awaiting confirmation\` when a plan was compiled and has not yet been confirmed.
@@ -141,7 +141,7 @@ Report format before any HTML write after confirmation:
 - Include which user-confirmed plan, approved narrative hash, and deck review snapshot authorized the artifact work.
 - Include the chapter currently being generated and confirm already-written slides are being preserved.
 - If deck/artifact review is blocked, list blockers separately from narrative blockers.
-- After writing HTML, read the appended \`Artifact QA\` report from the tool output. If it failed, fix hard errors before considering the deck ready for Refine.
+- After writing HTML, read the appended \`Artifact QA\` report from the tool output. If it failed, fix hard errors before considering the deck ready for Review.
 
 Rules:
 - \`compileDeckPlan\` is the canonical narrative-to-deck planning path. Do not manually invent slide specs to avoid it.

package/lib/edit/deck-state.ts

@@ -84,7 +84,7 @@ function inferSlides(filePath: string): SlideSpec[] {
       evidence: [],
       visuals: [],
       status: "ready",
-      notes: "Inferred automatically by /revela refine --deck preflight.",
+      notes: "Inferred automatically by /revela review --deck preflight.",
     }
   })
 }

package/lib/edit/resolve-deck.ts

@@ -12,7 +12,7 @@ export interface EditableDeck {
 
 export function resolveEditableDeck(workspaceRoot: string, input = ""): EditableDeck {
   if (input.trim()) {
-    throw new Error("/revela refine --deck does not accept a target. It opens the active HTML deck or the only HTML deck in decks/.")
+    throw new Error("/revela review --deck does not accept a target. It opens the active HTML deck or the only HTML deck in decks/.")
   }
 
   if (hasDecksState(workspaceRoot)) {

package/lib/inspect/server.ts

@@ -484,7 +484,7 @@ export function renderInspectorShell(token: string): string {
     <aside>
       <div>
         <h1>Evidence Inspector</h1>
-        <p class="hint">Cmd/Ctrl-click slide elements to attach them as references in /revela refine --deck. Then click <b>Inspect Selection</b>. This is not chat.</p>
+        <p class="hint">Cmd/Ctrl-click slide elements to attach them as references in /revela review --deck. Then click <b>Get Insight</b>. This is not chat.</p>
       </div>
       <div id="selection" class="selection">
         <strong>Selection</strong>
@@ -632,7 +632,7 @@ export function renderInspectorShell(token: string): string {
         if (bindAttempts >= 80) {
           clearInterval(bindTimer);
           bindTimer = 0;
-          setBindingStatus('error', 'Selection binding timed out. Reopen /revela refine --deck or reload this page.');
+          setBindingStatus('error', 'Selection binding timed out. Reopen /revela review --deck or reload this page.');
         }
       }, 150);
     }

package/lib/refine/server.ts

@@ -247,7 +247,7 @@ async function handleAssetSave(req: Request, session: EditSession): Promise<Resp
     id: body?.id || candidate.candidateId,
     type: "image",
     purpose,
-    brief: body?.brief || `Saved from ${candidate.provider} for Refine asset placement.`,
+    brief: body?.brief || `Saved from ${candidate.provider} for Review asset placement.`,
     status: "success",
     sourceUrl: candidate.imageUrl,
     alt: body?.alt || candidate.alt || candidate.title,
@@ -652,7 +652,7 @@ function handleInspectResult(requestId: string | null, session: EditSession): Re
   session.lastActiveAt = Date.now()
   scheduleIdleStop()
   if (request.status === "completed") return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion, result: request.result })
-  if (request.status === "failed" || request.status === "expired") return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion, error: request.error || "Inspection failed" })
+  if (request.status === "failed" || request.status === "expired") return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion, error: request.error || "Insight failed" })
   return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion })
 }
 
@@ -764,7 +764,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>Revela Refine</title>
+  <title>Revela Review</title>
   <style>
     :root { color-scheme: light; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
     * { box-sizing: border-box; }
@@ -783,15 +783,16 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     .deck-nav button:hover:not(:disabled) { background: rgba(255,255,255,.22); }
     .deck-nav button:disabled { opacity: .38; }
     .deck-nav-status { min-width: 76px; color: #e2e8f0; font-size: 12px; font-weight: 900; text-align: center; font-variant-numeric: tabular-nums; }
-    aside { position: relative; display: flex; flex-direction: column; gap: 16px; padding: 20px; background: linear-gradient(180deg, #fbfaf7 0%, #f2eee6 100%); overflow: auto; border-left: 1px solid #d8d2c6; }
+    aside { position: relative; display: flex; flex-direction: column; gap: 16px; padding: 20px; background: linear-gradient(180deg, #fbfaf7 0%, #f2eee6 100%); overflow: auto; border-left: 1px solid #d8d2c6; font-family: Garamond, "Iowan Old Style", Georgia, serif; }
+    aside button, aside input, aside select, aside textarea, aside .comment-editor { font-family: inherit; }
     h1 { margin: 0; font-size: 18px; line-height: 1.2; letter-spacing: -.01em; color: #0f172a; }
     .wordmark { font-family: Garamond, "Iowan Old Style", Georgia, serif; font-size: 21px; letter-spacing: .08em; font-weight: 600; }
-    .hint { margin: 0; color: #756f66; font-size: 13px; line-height: 1.5; }
     .panel { display: flex; flex-direction: column; gap: 10px; }
-    .tabs { display: grid; grid-template-columns: 1fr 1fr; gap: 6px; padding: 4px; border: 1px solid #d8d2c6; border-radius: 14px; background: #ebe4d8; }
-    .tab { padding: 9px 10px; border: 0; border-radius: 10px; background: transparent; color: #5f594f; box-shadow: none; font-weight: 900; }
-    .tab.active { background: #fbfaf7; color: #111827; box-shadow: 0 6px 16px rgba(31,41,51,.1); }
-    .tab-panel { display: none; flex-direction: column; gap: 12px; }
+    .tabs { display: flex; gap: 2px; padding: 0 0 0 8px; border-bottom: 1px solid #d8d2c6; background: transparent; }
+    .tab { width: auto; min-width: 112px; padding: 10px 18px; border: 1px solid transparent; border-bottom: 0; border-radius: 13px 13px 0 0; background: transparent; color: #5f594f; box-shadow: none; font-weight: 900; }
+    .tab:hover:not(:disabled) { background: rgba(255,253,248,.58); }
+    .tab.active { position: relative; top: 1px; background: #fbfaf7; border-color: #d8d2c6; color: #111827; box-shadow: 0 -7px 16px rgba(31,41,51,.05); }
+    .tab-panel { display: none; flex-direction: column; gap: 12px; padding-top: 12px; }
     .tab-panel.active { display: flex; }
     .sr-only { position: absolute !important; width: 1px !important; height: 1px !important; padding: 0 !important; margin: -1px !important; overflow: hidden !important; clip: rect(0,0,0,0) !important; white-space: nowrap !important; border: 0 !important; }
     .selection-summary { padding: 10px 12px; border: 1px solid #d8d2c6; border-radius: 14px; background: #fbfaf7; color: #3f3a33; font-size: 13px; line-height: 1.45; box-shadow: 0 8px 22px rgba(31,41,51,.05); }
@@ -885,20 +886,19 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     <div id="resizeHandle" class="resize-handle" role="separator" aria-label="Resize editor panel" aria-orientation="vertical" title="Drag to resize editor. Double-click to reset."></div>
     <aside>
       <div>
-        <h1><span class="wordmark">REVELA</span> Refine</h1>
-        <p class="hint">Select refs, describe the change, then send. Use Inspect only when you need source or purpose context.</p>
+        <h1><span class="wordmark">REVELA</span> Review</h1>
       </div>
       <div id="selectionSummary" class="selection-summary sr-only" aria-live="polite"><strong>Selection</strong><span>No references selected.</span><div id="selectionChips" class="selection-chips"></div></div>
-      <div class="tabs" role="tablist" aria-label="Refine mode">
-        <button id="editTab" class="tab" type="button" role="tab">Edit</button>
-        <button id="inspectTab" class="tab" type="button" role="tab">Inspect</button>
+      <div class="tabs" role="tablist" aria-label="Review mode">
+        <button id="editTab" class="tab" type="button" role="tab">Comment</button>
+        <button id="inspectTab" class="tab" type="button" role="tab">Insight</button>
       </div>
       <div id="editPanel" class="tab-panel">
         <div class="panel">
           <div class="label">Describe the change</div>
           <div id="comment" class="comment-editor" contenteditable="true" role="textbox" aria-multiline="true" data-placeholder="Cmd/Ctrl-click slide elements to add @refs, then describe the exact edit."></div>
         </div>
-        <div class="edit-assets" aria-label="Edit assets">
+        <div class="edit-assets" aria-label="Comment assets">
           <div class="panel">
             <div class="asset-tools"><div class="label">Local Assets</div><button id="assetSearchToggle" class="asset-search-toggle" type="button" aria-expanded="false" aria-controls="assetSearchView" title="Search assets">+</button></div>
             <div id="editSavedAssets" class="asset-grid"><p class="asset-empty">No local assets yet. Click + to search assets.</p></div>
@@ -909,20 +909,20 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       </div>
       <div id="inspectPanel" class="tab-panel">
         <div class="panel">
-          <label class="label" for="inspectComment">Inspect comment</label>
+          <label class="label" for="inspectComment">Insight comment</label>
           <div id="inspectComment" class="comment-editor" contenteditable="true" role="textbox" aria-multiline="true" data-placeholder="Cmd/Ctrl-click slide elements to add @refs, then ask about purpose or source."></div>
         </div>
         <div class="inspect-actions">
           <div class="inspect-options"><label for="inspectLanguage">Display Language</label><select id="inspectLanguage" class="inspect-select"><option>Auto</option><option>English</option><option>简体中文</option><option>繁體中文</option><option>日本語</option><option>Deutsch</option><option>Français</option><option>Español</option><option>Português</option><option>Arabic</option></select></div>
-          <button id="inspectButton" disabled>Inspect Reference</button>
+          <button id="inspectButton" disabled>Get Insight</button>
           <div id="inspectStale"></div>
         </div>
-        <div id="inspectCards" class="inspect-cards"><div class="inspect-empty">Select a deck element to create an @ref, optionally ask a question, then Inspect. This does not edit the deck.</div></div>
+        <div id="inspectCards" class="inspect-cards"><div class="inspect-empty">Select a deck element to create an @ref, optionally ask a question, then get insight. This does not edit the deck.</div></div>
       </div>
       <div id="assetSearchView" class="asset-search-view" aria-hidden="true">
         <div class="asset-search-head">
           <button id="assetSearchBack" class="asset-back" type="button">← Back</button>
-          <div class="asset-search-title"><h2>Search Assets</h2><span>Save images to Local Assets, then use them from Edit.</span></div>
+          <div class="asset-search-title"><h2>Search Assets</h2><span>Save images to Local Assets, then use them from Comment.</span></div>
         </div>
         <div class="panel">
           <div class="asset-search"><input id="assetQuery" type="search" placeholder="Company logo, product photo, portrait..." /><select id="assetPurpose"><option value="logo" selected>logo</option><option value="illustration">photo</option><option value="hero">hero</option><option value="portrait">portrait</option><option value="screenshot">screenshot</option></select></div>
@@ -1072,7 +1072,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           restoreEditorWidth();
           bindEvents();
           setMode(state.mode);
-          setStatus('Editor ready. Ctrl/Cmd + click deck elements to reference them.');
+          setStatus('Review ready. Ctrl/Cmd + click deck elements to reference them.');
           initFrame();
           loadSavedAssets();
           startDeckVersionPolling();
@@ -1116,6 +1116,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         els.inspectComment.addEventListener('mouseup', saveCommentRange);
         document.addEventListener('selectionchange', saveCommentRange);
         els.hitbox.addEventListener('pointermove', onHover);
+        els.hitbox.addEventListener('pointerleave', clearHoverSilently);
         els.hitbox.addEventListener('pointerdown', onPointerDown);
         els.hitbox.addEventListener('click', onClick);
         els.hitbox.addEventListener('contextmenu', (event) => {
@@ -1263,7 +1264,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
             state.pendingRefreshMessage = false;
             setStatus('Deck updated. Preview refreshed. Element references were cleared.');
           } else {
-            setStatus(slides.length > 0 ? 'Editor ready. Found ' + slides.length + ' slides. Ctrl/Cmd + click to reference elements.' : 'Editor ready, but no .slide elements were found. Ctrl/Cmd + click to reference elements.');
+            setStatus(slides.length > 0 ? 'Review ready. Found ' + slides.length + ' slides. Ctrl/Cmd + click to reference elements.' : 'Review ready, but no .slide elements were found. Ctrl/Cmd + click to reference elements.');
           }
         } catch (error) {
           reportError(error);
@@ -1336,9 +1337,11 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
             } catch {}
           }
           if (!handled) applyFallbackDeckNavigation(win, doc, slides, clamped);
+          const changed = clamped !== state.deckSlideIndex;
           state.deckSlideIndex = clamped;
           updateDeckNavControls();
-          renderHoverOutline(state.hoverEl);
+          if (changed) clearHoverSilently();
+          else renderHoverOutline(state.hoverEl);
           renderReferenceOutlines();
         } catch (error) {
           reportError(error);
@@ -1415,6 +1418,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           initFrame();
           const target = selectable(targetFromPointer(event));
           if (!target || isReferenced(target)) {
+            state.hoverEl = null;
             renderHoverOutline(null);
             return;
           }
@@ -1829,7 +1833,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         renderReferenceOutlines();
         updateSendState();
         renderSelectionSummary();
-        resetInspectCards('References ready. Open Inspect and click Inspect Reference for concise Purpose and Source context.');
+        resetInspectCards('References ready. Open Insight and click Get Insight for concise Purpose and Source context.');
         setStatus('Inserted @' + label + '. ' + state.references.length + ' reference' + (state.references.length === 1 ? '' : 's') + ' will be sent.');
       }
 
@@ -1997,14 +2001,27 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       function renderReferenceOutlines() {
         const doc = els.frame.contentDocument;
         if (!doc || doc.location.href === 'about:blank') return;
+        const slides = getSlides(doc);
+        const currentSlide = slides[state.deckSlideIndex];
+        const explicitSlideIndex = Number(currentSlide?.getAttribute('data-slide-index'));
+        const currentSlideIndex = Number.isFinite(explicitSlideIndex) && explicitSlideIndex > 0 ? explicitSlideIndex : state.deckSlideIndex + 1;
         while (state.referenceOutlines.length < state.references.length) state.referenceOutlines.push(createOutline(doc, '#7aa6d8', 'rgba(122,166,216,.18)'));
         state.referenceOutlines.forEach((outline, index) => {
           const reference = state.references[index];
           setOutlineColor(outline, reference?.color);
+          if (!reference || reference.payload?.slideIndex !== currentSlideIndex) {
+            renderBox(outline, null);
+            return;
+          }
           renderBox(outline, reference?.target);
         });
       }
 
+      function clearHoverSilently() {
+        state.hoverEl = null;
+        if (state.hoverOutline) state.hoverOutline.style.display = 'none';
+      }
+
       function clearHover() {
         state.hoverEl = null;
         setStatus('Hover cleared. Existing references are kept.');
@@ -2015,8 +2032,8 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         if (state.sendingEdit) setButtonLoading(els.send, true, 'Sending...');
         else setButtonLoading(els.send, false, '<svg class="send-icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94L14.7 6.3z"/></svg><span>Apply Fix</span>', true);
         els.send.disabled = state.sendingEdit || !getCommentText().trim();
-        if (state.inspecting) setButtonLoading(els.inspectButton, true, 'Inspecting...');
-        else setButtonLoading(els.inspectButton, false, 'Inspect Reference');
+        if (state.inspecting) setButtonLoading(els.inspectButton, true, 'Getting insight...');
+        else setButtonLoading(els.inspectButton, false, 'Get Insight');
         els.inspectButton.disabled = state.inspecting || state.references.length === 0;
       }
 
@@ -2077,7 +2094,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
             body: JSON.stringify({ snapshot, deckVersion: state.deckVersion, language: state.inspectLanguage, comment }),
           });
           const body = await res.json().catch(() => ({}));
-          if (!res.ok || !body.ok) throw new Error(body.error || 'Inspection failed');
+          if (!res.ok || !body.ok) throw new Error(body.error || 'Insight failed');
           state.deckVersion = body.deckVersion || state.deckVersion;
           state.activeInspectRequestId = body.requestId;
           state.inspectFallback = body.preprocess || null;
@@ -2086,7 +2103,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         } catch (error) {
           if (state.inspectFallback) {
             renderInspectResult(state.inspectFallback, 'Deterministic fallback');
-            els.inspectCards.insertAdjacentHTML('afterbegin', '<div class="inspect-warning">Generated inspection failed or timed out. Showing deterministic fallback context only.</div>');
+            els.inspectCards.insertAdjacentHTML('afterbegin', '<div class="inspect-warning">Generated insight failed or timed out. Showing deterministic fallback context only.</div>');
           } else {
             resetInspectCards(error && error.message ? error.message : String(error));
           }
@@ -2101,15 +2118,15 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           await delay(900);
           const res = await fetch('/api/inspect-result?token=' + encodeURIComponent(token) + '&requestId=' + encodeURIComponent(requestId));
           const body = await res.json().catch(() => ({}));
-          if (!res.ok || !body.ok) throw new Error(body.error || 'Inspection result failed');
+          if (!res.ok || !body.ok) throw new Error(body.error || 'Insight result failed');
           if (body.status === 'completed') {
             state.deckVersion = body.deckVersion || state.deckVersion;
             renderInspectResult(body.result, 'Generated');
             return;
           }
-          if (body.status === 'failed' || body.status === 'expired') throw new Error(body.error || 'Inspection failed');
+          if (body.status === 'failed' || body.status === 'expired') throw new Error(body.error || 'Insight failed');
         }
-        throw new Error('Inspection timed out while waiting for OpenCode result');
+        throw new Error('Insight timed out while waiting for OpenCode result');
       }
 
       function collectReferenceSnapshot() {
@@ -2136,10 +2153,10 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       }
 
       function renderInspectResult(result, phase) {
-        if (result.stale?.stale) els.inspectStale.innerHTML = '<div class="inspect-stale">' + escapeHtml(result.stale.reason || 'Inspection may be stale.') + '</div>';
+        if (result.stale?.stale) els.inspectStale.innerHTML = '<div class="inspect-stale">' + escapeHtml(result.stale.reason || 'Insight may be stale.') + '</div>';
         else els.inspectStale.innerHTML = '';
         els.inspectCards.innerHTML = [
-          '<div class="status">' + escapeHtml(phase || 'Inspection') + '</div>',
+          '<div class="status">' + escapeHtml(phase || 'Insight') + '</div>',
           renderInspectCard('Purpose', result.cards.purpose.status, result.cards.purpose.rationale, renderPurpose(result.cards.purpose)),
           renderInspectCard('Source', result.cards.source.status, result.cards.source.rationale, renderSource(result.cards.source)),
         ].join('');
@@ -2303,7 +2320,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           removeAssetChip();
         }
         renderSelectionSummary();
-        resetInspectCards('Select a deck element to create an @ref, optionally ask a question, then Inspect. This does not edit the deck.');
+        resetInspectCards('Select a deck element to create an @ref, optionally ask a question, then get insight. This does not edit the deck.');
       }
 
       function getCommentText(editor) {

package/package.json

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

package/plugin.ts

@@ -341,11 +341,20 @@ const server: Plugin = (async (pluginCtx) => {
         await send("Usage: `/revela make --deck` or `/revela make --brief [workspace-relative-output.md]`.")
         throw new Error("__REVELA_MAKE_USAGE_HANDLED__")
       }
+      if (sub === "review") {
+        if (param !== "--deck") {
+          await send("Usage: `/revela review --deck`.")
+          throw new Error("__REVELA_REVIEW_USAGE_HANDLED__")
+        }
+        await handleRefine({ client, sessionID, workspaceRoot }, send)
+        throw new Error("__REVELA_REVIEW_HANDLED__")
+      }
       if (sub === "refine") {
         if (param !== "--deck") {
-          await send("Usage: `/revela refine --deck`.")
+          await send("Usage: `/revela review --deck`.")
           throw new Error("__REVELA_REFINE_USAGE_HANDLED__")
         }
+        await send("`/revela refine --deck` is deprecated. Use `/revela review --deck`.")
         await handleRefine({ client, sessionID, workspaceRoot }, send)
         throw new Error("__REVELA_REFINE_HANDLED__")
       }

package/skill/NARRATIVE_SKILL.md

@@ -20,7 +20,7 @@ Use the same phase semantics whether the user invokes a slash command or asks in
 - `Research` runs closed loops to fill open story gaps, bind supported findings into canonical evidence, narrow overbroad claims/relations, and reduce caveats without crossing evidence boundaries.
 - `Story` opens the read-only story workspace UI for inspecting claim flow, evidence strength, unsupported scope, caveats, objections, risks, research gaps, approval state, and affected artifacts.
 - `Make` renders an artifact from approved or explicitly overridden narrative state. Supported 0.15 targets are deck and executive brief.
-- `Refine` is the post-artifact workspace for reading, inspection, and targeted editing. Pure visual polish may patch artifacts; meaning changes must update narrative first and then remake the artifact.
+- `Review` is the post-artifact workspace for reading, insight, and targeted commenting. Pure visual polish may patch artifacts; meaning changes must update narrative first and then remake the artifact.
 
 Public command surface:
 
@@ -29,7 +29,7 @@ Public command surface:
 - `/revela story`
 - `/revela make --deck`
 - `/revela make --brief`
-- `/revela refine --deck`
+- `/revela review --deck`
 - `/revela export --deck pdf`
 - `/revela export --deck pptx`
 - `/revela design`
@@ -115,14 +115,14 @@ For `/revela make --brief`, render the executive brief from canonical narrative
 
 If story readiness, approval, evidence, or artifact blockers remain, report the blocker and suggest `/revela story`, `/revela research`, or a targeted user answer. Do not bypass with invented state.
 
-## Refine Rules
+## Review Rules
 
-Use `/revela refine --deck` for post-artifact reading, inspection, and editing.
+Use `/revela review --deck` for post-artifact reading, insight, and commenting.
 
 - Reading should explain source, support strength, caveat, unsupported scope, narrative purpose, related risks/objections, research gaps, and artifact coverage.
 - Pure artifact polish may stay artifact-level: layout, typography, spacing, crop, visual hierarchy, export mechanics, and deck contract fixes.
 - Meaning-changing edits must update canonical narrative first, then run story readiness/approval or explicit override, then remake affected artifacts.
-- `/revela edit` and `/revela inspect` have been removed from the public surface; use `/revela refine --deck`.
+- `/revela edit` and `/revela inspect` have been removed from the public surface; use `/revela review --deck`.
 
 ## Design Surface
 

package/skill/SKILL.md

@@ -182,7 +182,7 @@ Required contract:
 - All JS methods must be fully implemented. No empty stubs and no TODO comments.
 - Do not add deck-local editing JavaScript, `contenteditable`, `editable` classes,
   or `window.getEditedHTML()` implementations. Post-artifact editing belongs in
-  `/revela refine --deck`.
+  `/revela review --deck`.
 
 Example slide identity:
 
@@ -283,4 +283,4 @@ instructions, secrets, or unverified claims.
 - Avoid text overflow, clipping, element overflow, unintended overlap, and page
   scrollbars.
 - Artifact QA hard errors must be fixed before opening or reporting the deck as
-  ready for Refine.
+  ready for Review.

package/tools/edit.ts

@@ -1,7 +1,7 @@
 /**
  * tools/edit.ts
  *
- * revela-edit — Compatibility tool that opens Revela Refine in Edit mode.
+ * revela-edit — Compatibility tool that opens Revela Review in Comment mode.
  */
 
 import { tool } from "@opencode-ai/plugin"
@@ -10,11 +10,11 @@ import { openRefineDeck } from "../lib/refine/open"
 export function createEditTool(options: { client: any; workspaceRoot: string; openBrowser?: boolean }) {
   return tool({
     description:
-      "Open Revela Refine in Edit mode for an existing slide deck. " +
+      "Open Revela Review in Comment mode for an existing slide deck. " +
       "Use this when the user asks to edit, revise, annotate, or visually comment on a deck, " +
       "including when they reference the current deck. " +
-      "This is a compatibility tool for the older edit-only workflow; the user-facing entry is /revela refine --deck. " +
-      "It opens a local browser workspace where the user can Ctrl/Cmd-click deck elements, use the Edit tab, " +
+      "This is a compatibility tool for the older edit-only workflow; the user-facing entry is /revela review --deck. " +
+      "It opens a local browser workspace where the user can Ctrl/Cmd-click deck elements, use the Comment tab, " +
       "and send precise edit requests back to the current OpenCode session.",
     args: {},
     async execute(_args, context: any) {
@@ -43,8 +43,8 @@ export function createEditTool(options: { client: any; workspaceRoot: string; op
           url: result.url,
           mode: result.mode,
           message:
-            `${result.stateNote} Opened Revela Refine in Edit mode. ` +
-            "Ask the user to use Ctrl/Cmd-click in the browser to reference elements, then use the Edit tab to send comments.",
+            `${result.stateNote} Opened Revela Review in Comment mode. ` +
+            "Ask the user to use Ctrl/Cmd-click in the browser to reference elements, then use the Comment tab to send comments.",
         }, null, 2)
       } catch (error) {
         return JSON.stringify({

package/tools/inspection-result.ts

@@ -15,7 +15,7 @@ const evidenceSourceItemSchema = tool.schema.object({
 
 export default tool({
   description:
-    "Submit the final structured Evidence Inspector result for a pending /revela refine --deck Inspect request. " +
+    "Submit the final structured Evidence Inspector result for a pending /revela review --deck Insight request. " +
     "Use only when responding to an inspection prompt. This updates the local browser inspector; it does not mutate DECKS.json or deck files.",
   args: {
     requestId: tool.schema.string().describe("Pending inspection request id from the inspection prompt."),