@cyber-dash-tech/revela 0.13.0 → 0.14.0

package/README.md

@@ -2,7 +2,7 @@
 
 **English** | [中文](README.zh-CN.md)
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-324%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-375%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" />
@@ -145,9 +145,9 @@ Disable presentation mode when done:
 /revela deck                     start deck handoff from approved narrative
 /revela deck --review            review deck/artifact readiness before writing HTML
 /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 refine                   open unified reading, inspection, and editing workspace
+/revela edit                     deprecated shim to /revela refine Edit mode
+/revela inspect                  deprecated shim to /revela refine Inspect mode
 
 /revela designs                  list installed designs
 /revela designs <name>           activate a design
@@ -166,7 +166,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 deck`, `/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.
+Most `/revela` commands run locally with zero LLM cost. `/revela init`, `/revela review`, `/revela deck`, `/revela remember`, `/revela designs-new`, and `/revela designs-edit` start AI-assisted workflows because they need to read or update project files. `/revela refine` 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` remain only as deprecated compatibility shims to Refine.
 
 ---
 
@@ -214,8 +214,8 @@ Use Revela as a narrative-first artifact workflow:
 5. Run `/revela deck` to compile the approved narrative into deck slide specs and enter deck-render mode.
 6. Choose or confirm design only during deck handoff, then run the deck/artifact gate with `/revela deck --review` or the handoff workflow.
 7. Let the agent write the HTML deck under `decks/` only after the artifact gate is ready.
-8. Use `/revela refine` for visual comments, targeted revisions, and optional Source/Purpose inspection of selected deck elements.
-9. Use `/revela edit` or `/revela inspect` directly only if you need the older single-purpose shells.
+8. Use `/revela refine` 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 edit` or `/revela inspect` only for old scripts or habits; both open `/revela refine` in the matching mode.
 10. Export with `/revela pdf <file>` or `/revela pptx <file>`.
 
 `/revela review` checks narrative readiness: 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 and does not write the final deck.
@@ -591,19 +591,19 @@ Use the unified refinement workspace for normal post-write review and revision:
 /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.
+`/revela refine` 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.
 
-Open the visual editor for the only HTML deck in `decks/`:
+Deprecated compatibility command:
 
 ```text
 /revela edit
 ```
 
-`/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.
+`/revela edit` no longer opens a separate edit-only shell. It opens `/revela refine` in Edit mode for compatibility with old scripts and user habits.
 
-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.
+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.
 
-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”.
+LLM tool equivalent: `revela-edit` with no target. The tool is also a compatibility shim and opens Refine in Edit mode when you say things like “I want to edit the deck”.
 
 For existing decks, `/revela edit` prepares whatever minimal project context is needed so targeted edits can still use the normal safety checks.
 
@@ -611,17 +611,17 @@ 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`:
+Use `/revela refine` for evidence inspection and narrative reading. Deprecated compatibility command:
 
 ```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.
+`/revela inspect` no longer opens a separate inspector shell. It opens `/revela refine` in Inspect mode. 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.
 
-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.
+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.
 
-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.
+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.
 
 ---
 

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [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-324%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-375%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" />
@@ -144,9 +144,9 @@ export { default } from "/absolute/path/to/revela/index.ts";
 /revela deck                     从已批准 narrative 开始 deck handoff
 /revela deck --review            写 HTML 前检查 deck/artifact readiness
 /revela remember <text>          保存明确的用户/工作流偏好
-/revela refine                   打开统一的 Edit/Inspect refinement workspace
-/revela edit                     打开 decks/ 下唯一 deck 的可视化编辑器
-/revela inspect                  打开 Cmd/Ctrl-click 式 Evidence Inspector
+/revela refine                   打开统一的阅读、检查和编辑 workspace
+/revela edit                     deprecated，兼容到 /revela refine Edit mode
+/revela inspect                  deprecated，兼容到 /revela refine Inspect mode
 
 /revela designs                  列出已安装 design
 /revela designs <name>           激活某个 design
@@ -165,7 +165,7 @@ export { default } from "/absolute/path/to/revela/index.ts";
 /revela pptx <file>              将 HTML deck 导出为同目录可编辑 PPTX
 ```
 
-大多数 `/revela` 命令都在本地执行，不消耗 LLM token。`/revela init`、`/revela review`、`/revela deck`、`/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。
+大多数 `/revela` 命令都在本地执行，不消耗 LLM token。`/revela init`、`/revela review`、`/revela deck`、`/revela remember`、`/revela designs-new` 和 `/revela designs-edit` 会启动 AI 辅助流程，因为它们需要读取或更新项目状态。`/revela refine` 是统一的 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` 只作为 deprecated 兼容入口保留。
 
 ---
 
@@ -213,8 +213,8 @@ Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace s
 5. 运行 `/revela deck`，把已批准 narrative 编译成 deck slide specs，并进入 deck-render mode。
 6. 只在 deck handoff 阶段选择或确认 design，然后通过 handoff workflow 或 `/revela deck --review` 运行 deck/artifact gate。
 7. 只有 artifact gate ready 后，才让 agent 把 HTML deck 写到 `decks/` 下。
-8. 用 `/revela refine` 对选中 deck 元素做可视化评论、精准修改，以及可选的 Source/Purpose 检查。
-9. 只有在需要旧的单一功能 shell 时，才单独使用 `/revela edit` 或 `/revela inspect`。
+8. 用 `/revela refine` 对选中 deck 元素做可视化评论、精准修改、只读 Narrative Reading、有边界的 Exploratory Reading、Source、Purpose 检查，以及 claim-to-artifact coverage 查看。
+9. 只有旧脚本或旧习惯需要时，才使用 `/revela edit` 或 `/revela inspect`；两者都会打开对应模式的 `/revela refine`。
 10. 用 `/revela pdf <file>` 或 `/revela pptx <file>` 导出。
 
 `/revela review` 检查的是 narrative readiness：受众不清、缺信念变化、缺 decision/action、thesis 弱、central claims 无证据、evidence 弱、unsupported scope、objection 未处理、缺风险/假设处理、approval stale 或缺 approval。它不检查 design/layout readiness，也不会写最终 deck。
@@ -556,19 +556,19 @@ Prompt 注入规则：
 /revela refine
 ```
 
-`/revela refine` 会打开 `decks/` 下唯一的 HTML deck，并提供两个 tab。使用 `Ctrl`/`Cmd` + click 先引用 deck 元素，然后在 Edit 里快速写自然语言修改评论，或在 Inspect 里做只读 Source 和 Purpose 检查。Inspect 不会修改 deck；真正的 mutation 仍然只走 Edit。
+`/revela refine` 会打开 active HTML deck，并提供两个 tab。使用 `Ctrl`/`Cmd` + click 先引用 deck 元素，然后在 Edit 里快速写自然语言修改评论，或在 Inspect 里做只读 Narrative Reading、有边界的 Exploratory Reading、Source、Purpose 和 artifact coverage 检查。Inspect 不会修改 deck；真正的 mutation 仍然只走 Edit。这是 post-artifact 阅读、检查和编辑的推荐入口。
 
-打开 `decks/` 下唯一 HTML deck 的可视化编辑器：
+Deprecated 兼容命令：
 
 ```text
 /revela edit
 ```
 
-Revela 0.8 中 `/revela edit` 不接受 target。如果 `decks/` 下正好有一个 `.html` 文件，Revela 会打开它。如果 `decks/` 下没有 HTML 或有多个 HTML，Revela 会提示先生成 deck，或把多余 deck 移到独立 workspace。
+`/revela edit` 不再打开独立的 edit-only shell。它会打开 `/revela refine` 的 Edit mode，用于兼容旧脚本和旧使用习惯。
 
-旧的 edit-only shell 会在浏览器中打开。使用 `Ctrl`/`Cmd` + 点击 deck 元素来引用它们，写一段自然语言评论，然后发送回 OpenCode。Revela 会把 deck 文件、slide 上下文、选中元素 metadata 和你的评论整理成结构化 edit prompt。
+使用 `Ctrl`/`Cmd` + 点击 deck 元素来引用它们，在 Edit tab 写一段自然语言评论，然后发送回 OpenCode。Revela 会把 deck 文件、slide 上下文、选中元素 metadata 和你的评论整理成结构化 edit prompt。
 
-对应的 LLM tool：`revela-edit`，不需要 target。因此当你说“我要编辑这个 deck”时，agent 也可以主动打开同一个编辑器。
+对应的 LLM tool：`revela-edit`，不需要 target。这个 tool 也是兼容入口，当你说“我要编辑这个 deck”时，agent 会打开 Refine 的 Edit mode。
 
 对于已有 HTML deck，`/revela edit` 会自动准备必要的最小项目上下文，让后续精准修改仍然经过正常安全检查。
 
@@ -576,17 +576,17 @@ Revela 0.8 中 `/revela edit` 不接受 target。如果 `decks/` 下正好有一
 
 ## Evidence Inspector
 
-打开 `decks/` 下唯一 HTML deck 的 Evidence Inspector，或直接使用 `/revela refine` 里的 Inspect tab：
+用 `/revela refine` 做 evidence inspection 和 narrative reading。Deprecated 兼容命令：
 
 ```text
 /revela inspect
 ```
 
-Inspector 会在浏览器中打开，左侧是 deck，右侧是固定卡片：Source 和 Purpose。使用 `Ctrl`/`Cmd` + click 像 `/revela edit` 一样引用 deck 元素，然后点击 `Inspect Selection`。请求处理期间，deck 选择会被锁定。
+`/revela inspect` 不再打开独立 inspector shell。它会打开 `/revela refine` 的 Inspect mode。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 选择会被锁定。
 
-Inspector 不是聊天，也没有自由输入框。它不会修改 `DECKS.json` 或 deck HTML。它使用已记录的 slide spec、narrative state 和 slide-level evidence trace 作为 grounded context。确定性预处理会立即显示；LLM judgment 随后 lazy 更新 Source 和 Purpose 卡片，不会强行生成编辑动作。
+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。
 
-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 工作流信任它之前被拒绝或报告。
+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 工作流信任它之前被拒绝或报告。
 
 ---
 

package/lib/commands/edit.ts

@@ -1,22 +1,24 @@
-import { openEditableDeck } from "../edit/open"
+import { openRefineDeck } from "../refine/open"
 
 export async function handleEdit(
-  options: { client: any; sessionID: string; workspaceRoot: string },
+  options: { client: any; sessionID: string; workspaceRoot: string; openBrowser?: boolean },
   send: (text: string) => Promise<void>,
 ): Promise<void> {
   try {
-    const result = openEditableDeck("", {
+    const result = openRefineDeck("", {
       client: options.client,
       sessionID: options.sessionID,
       workspaceRoot: options.workspaceRoot,
+      mode: "edit",
+      openBrowser: options.openBrowser,
     })
 
     await send(
-      `Opened visual editor for the only deck in \`decks/\`.\n` +
+      `\`/revela edit\` is deprecated. Opened \`/revela refine\` in Edit mode 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 elements, write a comment, then send comments. Revela mode has been enabled for the edit prompt.`
+      `Use \`/revela refine\` directly going forward. Use Ctrl/Cmd-click in the browser to reference elements, then use the Edit tab to send targeted change comments.`
     )
   } catch (e: any) {
     await send(`**Edit failed:** ${e.message || String(e)}`)

package/lib/commands/help.ts

@@ -32,9 +32,9 @@ export async function handleHelp(
     `\`/revela brief [file.md]\`      — render executive brief from approved narrative\n` +
     `\`/revela deck\`                — start deck handoff from approved narrative\n` +
     `\`/revela deck --review\`       — review deck/artifact 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 refine\`              — open unified reading, inspection, and editing workspace\n` +
+    `\`/revela edit\`                — deprecated compatibility shim to /revela refine Edit\n` +
+    `\`/revela inspect\`             — deprecated compatibility shim to /revela refine Inspect\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

@@ -1,21 +1,23 @@
-import { openInspectDeck } from "../inspect/open"
+import { openRefineDeck } from "../refine/open"
 
 export async function handleInspect(
-  options: { client: any; sessionID: string; workspaceRoot: string },
+  options: { client: any; sessionID: string; workspaceRoot: string; openBrowser?: boolean },
   send: (text: string) => Promise<void>,
 ): Promise<void> {
   try {
-    const result = openInspectDeck("", {
+    const result = openRefineDeck("", {
       client: options.client,
       sessionID: options.sessionID,
       workspaceRoot: options.workspaceRoot,
+      mode: "inspect",
+      openBrowser: options.openBrowser,
     })
     await send(
-      `Opened Evidence Inspector for the active HTML deck.\n` +
+      `\`/revela inspect\` is deprecated. Opened \`/revela refine\` in Inspect mode 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.`
+      `Use \`/revela refine\` directly going forward. Use Ctrl/Cmd-click in the browser to reference deck elements, then use the Inspect tab for read-only Source/Purpose review. There is no chat box or freeform prompt.`
     )
   } catch (e: any) {
     await send(`**Inspect failed:** ${e.message || String(e)}`)

package/lib/inspect/prompt.ts

@@ -4,23 +4,31 @@ export function buildInspectionPrompt(input: {
   requestId: string
   file: string
   projection: InspectionPromptProjection
+  language?: string
 }): string {
+  const language = normalizeInspectLanguage(input.language)
   return `A user selected slide content in Revela Evidence Inspector. The selection may contain one referenced element, a whole slide, or multiple referenced elements selected with Cmd/Ctrl-click.
 
 Target file: ${input.file}
 Inspection request id: ${input.requestId}
+Display language: ${language}
 
-Use the structured projection below to produce the final inspector cards. This is LLM judgment with grounded boundaries: answer the selected object's purpose and source credibility only. Do not edit files. Do not mutate DECKS.json. Do not invent sources, quotes, URLs, page references, caveats, or evidence not present in the projection.
+Use the structured projection below to produce the final inspector cards. This is LLM judgment with grounded boundaries: explain the selected object's narrative reading context, bounded exploratory reading context, purpose, and source credibility only. Do not edit files. Do not mutate DECKS.json. Do not invent claim ids, evidence binding ids, sources, quotes, URLs, page references, caveats, objections, risks, artifact coverage, or evidence not present in the projection.
+
+Language boundary: the selected display language affects only human-readable card copy. Preserve all claim ids, canonical claim ids, evidence binding ids, source paths, findings files, URLs, numbers, quoted/source facts, caveats, artifact ids, and coverage statuses exactly as grounded in the projection. If the display language is Auto, use projection.deck.language when available; otherwise follow the user's/browser context or default to English.
 
 Return the result only by calling the \`revela-inspection-result\` tool with this request id. Do not answer in chat.
 
 Required card model:
+- Narrative Reading: when the projection includes a matched claim, preserve its claim id, canonical claim id, evidence binding ids, supported scope, unsupported scope, caveats, related objections, related risks, and artifact coverage. Artifact coverage must come only from projection.cards.artifacts; do not invent where a claim appears or whether an artifact is stale/current/partial/missing. If canonical narrative linkage is missing, say so and fall back to the matched slide claim; do not invent canonical ids.
+- Candidate boundary: when projection.match.claim is absent but projection.match.candidateClaims is present, explain the selected child element only within those candidate claim boundaries. You may describe that the child element functions as a detail, prerequisite, source note, risk cue, or evidence cue inside the slide, but you must not select one candidate claim id by semantic guess. If projection.match.confidence is none or candidateClaims is empty, explain the mapping gap instead of inventing a plausible claim.
+- Exploratory Reading: provide bounded, non-official reading cues for objection prep, audience reframing, appendix leads, and meeting prep only from the projection. Mark official as false. Keep missing evidence, caveats, unsupported scope, and stale artifacts visible. Do not make exploratory text sound like approved artifact content, and do not turn this into chat or a fix plan.
 - Purpose: explain why this selected content appears here, what job it serves in the slide purpose, narrative role, deck goal, audience, or narrative brief, and why it matters.
 - Source: if the selection contains a factual claim, number, comparison, conclusion, or recommendation, judge source credibility. Use not_needed for structural, transitional, or purely explanatory content that does not need evidence. Include source trace, warnings, gaps, and caveats here.
 
 Boundaries:
 - Do not hunt for problems. If it works, say it works.
-- Do not recommend edits or fixes; this inspector view only explains purpose and source credibility.
+- Do not recommend edits or fixes; this inspector view only explains narrative context, bounded exploratory reading context, purpose, and source credibility.
 - Do not turn every caveat into a problem.
 - If confidence is low, use unclear or unknown instead of pretending certainty.
 
@@ -30,3 +38,8 @@ Projection JSON:
 ${JSON.stringify(input.projection, null, 2)}
 \`\`\``
 }
+
+function normalizeInspectLanguage(language: string | undefined): string {
+  const value = typeof language === "string" ? language.trim() : ""
+  return value || "Auto"
+}

package/lib/inspect/requests.ts

@@ -1,5 +1,5 @@
 import type { InspectionPromptProjection } from "../inspection-context/project"
-import type { InspectionResult } from "../inspection-context/result"
+import { buildDeterministicInspectionResult, type InspectionResult } from "../inspection-context/result"
 
 export type InspectRequestStatus = "pending" | "completed" | "failed" | "expired"
 
@@ -53,11 +53,30 @@ export function completeInspectRequest(requestId: string, result: InspectionResu
   if (!request) throw new Error(`Unknown inspection request: ${requestId}`)
   if (request.status !== "pending") throw new Error(`Inspection request is not pending: ${request.status}`)
   request.status = "completed"
-  request.result = { ...result, requestId }
+  request.result = normalizeInspectionResult(request.projection, result, requestId)
   request.updatedAt = Date.now()
   return request
 }
 
+function normalizeInspectionResult(
+  projection: InspectionPromptProjection,
+  result: InspectionResult,
+  requestId: string,
+): InspectionResult {
+  const deterministic = buildDeterministicInspectionResult(projection, { requestId })
+  return {
+    ...result,
+    requestId,
+    cards: {
+      reading: result.cards.reading ?? deterministic.cards.reading,
+      exploratory: result.cards.exploratory ?? deterministic.cards.exploratory,
+      purpose: result.cards.purpose,
+      source: result.cards.source,
+    },
+    stale: result.stale ?? deterministic.stale,
+  }
+}
+
 export function failInspectRequest(requestId: string, error: string): PendingInspectRequest | undefined {
   const request = getInspectRequest(requestId)
   if (!request || request.status !== "pending") return request

package/lib/inspection-context/compile.ts

@@ -1,4 +1,5 @@
 import type { DeckSpec, DecksState, EvidenceRef, NarrativeBrief, NarrativeRole, SlideSpec, SourceMaterial } from "../decks-state"
+import { getArtifactClaimRefs, type ArtifactClaimRef, type ClaimSlideRef } from "../narrative-state/queries"
 import type { NarrativeClaim, NarrativeEvidenceBinding, NarrativeStateV1 } from "../narrative-state/types"
 
 export type InspectionClaimOrigin = "narrative" | "title" | "headline" | "body" | "bullet" | "purpose"
@@ -20,6 +21,7 @@ export interface InspectionContext {
   appendixCandidates: InspectionAppendixCandidate[]
   objectionContext: InspectionNarrativeContext[]
   riskContext: InspectionNarrativeContext[]
+  artifactCoverage: InspectionArtifactCoverage[]
 }
 
 export interface InspectionNarrativeStateContext {
@@ -98,11 +100,35 @@ export interface InspectionAppendixCandidate {
 
 export interface InspectionNarrativeContext {
   text: string
-  source: "narrativeBrief" | "slide"
+  source: "narrative" | "narrativeBrief" | "slide"
   slideIndex?: number
   slideTitle?: string
 }
 
+export interface InspectionArtifactCoverage {
+  artifactId: string
+  type: ArtifactClaimRef["type"]
+  outputPath?: string
+  coverageStatus: ArtifactClaimRef["coverageStatus"]
+  claimIds: string[]
+  affectedClaimIds: string[]
+  missingClaimIds: string[]
+  stale: boolean
+  staleReason?: string
+  staleReasons: string[]
+  note?: string
+  slideRefs: InspectionArtifactSlideRef[]
+}
+
+export interface InspectionArtifactSlideRef {
+  claimId: string
+  slideIndex: number
+  slideTitle: string
+  role: ClaimSlideRef["role"]
+  match: ClaimSlideRef["match"]
+  location: string
+}
+
 export function compileInspectionContext(state: DecksState, slug?: string): InspectionContext {
   const deck = activeDeck(state, slug)
   const narrative = state.narrative
@@ -127,11 +153,36 @@ export function compileInspectionContext(state: DecksState, slug?: string): Insp
     slides,
     gaps,
     appendixCandidates: compileAppendixCandidates(slides),
-    objectionContext: compileNarrativeList(deck, "objections"),
-    riskContext: compileNarrativeList(deck, "risks"),
+    objectionContext: compileNarrativeList(deck, "objections", narrative),
+    riskContext: compileNarrativeList(deck, "risks", narrative),
+    artifactCoverage: compileArtifactCoverage(state),
   }
 }
 
+function compileArtifactCoverage(state: DecksState): InspectionArtifactCoverage[] {
+  return getArtifactClaimRefs(state).map((artifact) => ({
+    artifactId: artifact.artifactId,
+    type: artifact.type,
+    outputPath: artifact.outputPath,
+    coverageStatus: artifact.coverageStatus,
+    claimIds: artifact.claimIds,
+    affectedClaimIds: artifact.affectedClaimIds,
+    missingClaimIds: artifact.missingClaimIds,
+    stale: artifact.stale,
+    staleReason: artifact.staleReason,
+    staleReasons: artifact.staleReasons,
+    note: artifact.note,
+    slideRefs: artifact.slideRefs.map((ref) => ({
+      claimId: ref.claimId,
+      slideIndex: ref.slideIndex,
+      slideTitle: ref.slideTitle,
+      role: ref.role,
+      match: ref.match,
+      location: ref.location,
+    })),
+  }))
+}
+
 function activeDeck(state: DecksState, slug?: string): DeckSpec {
   const key = slug || state.activeDeck || (Object.keys(state.decks).length === 1 ? Object.keys(state.decks)[0] : undefined)
   if (!key || !state.decks[key]) throw new Error("No active deck is available for inspection context compilation.")
@@ -389,7 +440,10 @@ function appendixReason(slide: InspectionSlideContext): string {
   return "Slide has recorded evidence that may be useful for source excerpts or backup detail."
 }
 
-function compileNarrativeList(deck: DeckSpec, key: "objections" | "risks"): InspectionNarrativeContext[] {
+function compileNarrativeList(deck: DeckSpec, key: "objections" | "risks", narrative: NarrativeStateV1 | undefined): InspectionNarrativeContext[] {
+  const fromNarrative = key === "objections"
+    ? (narrative?.objections ?? []).map((item) => ({ text: item.text, source: "narrative" as const }))
+    : (narrative?.risks ?? []).map((item) => ({ text: item.text, source: "narrative" as const }))
   const fromBrief = (deck.narrativeBrief?.[key] ?? []).map((text) => ({ text, source: "narrativeBrief" as const }))
   const role = key === "risks" ? "risk" : undefined
   const fromSlides = deck.slides
@@ -400,7 +454,19 @@ function compileNarrativeList(deck: DeckSpec, key: "objections" | "risks"): Insp
       slideIndex: slide.index,
       slideTitle: slide.title,
     })))
-  return [...fromBrief, ...fromSlides]
+  return dedupeNarrativeContext([...fromNarrative, ...fromBrief, ...fromSlides])
+}
+
+function dedupeNarrativeContext(values: InspectionNarrativeContext[]): InspectionNarrativeContext[] {
+  const seen = new Set<string>()
+  const result: InspectionNarrativeContext[] = []
+  for (const value of values) {
+    const key = `${normalizeText(value.text)}:${value.slideIndex ?? "global"}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(value)
+  }
+  return result
 }
 
 function slideTextList(slide: SlideSpec): string[] {

package/lib/inspection-context/match.ts

@@ -45,6 +45,7 @@ export interface InspectionElementSnapshot {
 export interface InspectionElementMatch {
   slide?: InspectionSlideContext
   claim?: InspectionClaimCandidate
+  candidateClaims?: InspectionClaimCandidate[]
   evidence: InspectionEvidenceTrace[]
   gaps: InspectionGap[]
   caveats: string[]
@@ -55,8 +56,12 @@ export interface InspectionElementMatch {
 
 export function matchInspectionElement(context: InspectionContext, snapshot: InspectionElementSnapshot): InspectionElementMatch {
   const selectedText = normalizeText(snapshot.text)
+  const surroundingText = normalizeText(snapshot.nearbyText || snapshot.outerHTMLExcerpt)
   const candidateSlides = candidateSlidesForSnapshot(context, snapshot)
 
+  const anchoredClaim = findAnchoredClaimMatch(candidateSlides, snapshot)
+  if (anchoredClaim) return claimMatch(context, anchoredClaim.slide, anchoredClaim.claim, "high", "Matched explicit claim anchor from selection snapshot.")
+
   if (selectedText) {
     const exactClaim = findClaimMatch(candidateSlides, selectedText, "exact")
     if (exactClaim) return claimMatch(context, exactClaim.slide, exactClaim.claim, "high", "Exact normalized text match.")
@@ -77,8 +82,27 @@ export function matchInspectionElement(context: InspectionContext, snapshot: Ins
     }
   }
 
+  if (surroundingText && surroundingText !== selectedText) {
+    const contextualClaim = findClaimMatch(candidateSlides, surroundingText, "contains")
+    if (contextualClaim) return claimMatch(context, contextualClaim.slide, contextualClaim.claim, "medium", "Matched claim using surrounding slide context.")
+  }
+
   const slide = candidateSlides[0]
-  if (slide) return slideMatch(context, slide, snapshot.slideIndex ? "medium" : "low", snapshot.slideIndex ? "Matched by slideIndex only." : "No claim text matched; returning first candidate slide.")
+  if (slide) {
+    const canonicalClaims = slide.claims.filter((claim) => claim.canonicalClaimId || claim.origin === "narrative")
+    if (canonicalClaims.length === 1) {
+      return claimMatch(context, slide, canonicalClaims[0], "medium", "Selected element matched the slide; the slide has one canonical narrative claim candidate.", canonicalClaims)
+    }
+    return slideMatch(
+      context,
+      slide,
+      snapshot.slideIndex ? "medium" : "low",
+      canonicalClaims.length > 1
+        ? "Matched slide only; multiple canonical claim candidates are available, so no claim id was chosen by semantic guess."
+        : snapshot.slideIndex ? "Matched by slideIndex only." : "No claim text matched; returning first candidate slide.",
+      canonicalClaims,
+    )
+  }
 
   return {
     evidence: [],
@@ -114,6 +138,37 @@ function findClaimMatch(
   return undefined
 }
 
+function findAnchoredClaimMatch(
+  slides: InspectionSlideContext[],
+  snapshot: InspectionElementSnapshot,
+): { slide: InspectionSlideContext; claim: InspectionClaimCandidate } | undefined {
+  const claimIds = explicitClaimIds(snapshot)
+  if (claimIds.length === 0) return undefined
+  for (const slide of slides) {
+    for (const claim of slide.claims) {
+      const ids = [claim.id, claim.canonicalClaimId].filter((item): item is string => Boolean(item))
+      if (ids.some((id) => claimIds.includes(id))) return { slide, claim }
+    }
+  }
+  return undefined
+}
+
+function explicitClaimIds(snapshot: InspectionElementSnapshot): string[] {
+  const values = [
+    snapshot.selector,
+    snapshot.domPath,
+    snapshot.outerHTMLExcerpt,
+    ...(snapshot.elements ?? []).flatMap((item) => [item.selector, item.domPath, item.outerHTMLExcerpt]),
+  ]
+  const ids: string[] = []
+  for (const value of values) {
+    if (!value) continue
+    for (const match of value.matchAll(/data-claim-id\s*=\s*["']([^"']+)["']/gi)) ids.push(match[1])
+    for (const match of value.matchAll(/data-claim-id=([^\]\s>"']+)/gi)) ids.push(match[1])
+  }
+  return dedupe(ids.map((item) => item.trim()).filter(Boolean))
+}
+
 function conservativeContains(claimText: string, selectedText: string): boolean {
   if (selectedText.length < 12 && claimText.length < 12) return false
   return claimText.includes(selectedText) || selectedText.includes(claimText)
@@ -125,10 +180,12 @@ function claimMatch(
   claim: InspectionClaimCandidate,
   confidence: InspectionMatchConfidence,
   reason: string,
+  candidateClaims: InspectionClaimCandidate[] = [],
 ): InspectionElementMatch {
   return {
     slide,
     claim,
+    candidateClaims: candidateClaims.length ? candidateClaims : [claim],
     evidence: claim.evidence,
     gaps: claim.gaps,
     caveats: slide.caveats,
@@ -143,9 +200,11 @@ function slideMatch(
   slide: InspectionSlideContext,
   confidence: InspectionMatchConfidence,
   reason: string,
+  candidateClaims: InspectionClaimCandidate[] = [],
 ): InspectionElementMatch {
   return {
     slide,
+    candidateClaims,
     evidence: slide.evidence,
     gaps: slide.claims.flatMap((claim) => claim.gaps),
     caveats: slide.caveats,
@@ -167,3 +226,14 @@ function normalizeText(text: string | undefined): string {
     .trim()
     .toLowerCase()
 }
+
+function dedupe(values: string[]): string[] {
+  const seen = new Set<string>()
+  const result: string[] = []
+  for (const value of values) {
+    if (seen.has(value)) continue
+    seen.add(value)
+    result.push(value)
+  }
+  return result
+}