@cyber-dash-tech/revela 0.12.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/brief.ts

@@ -0,0 +1,63 @@
+import { existsSync, mkdirSync, writeFileSync } from "fs"
+import { dirname, isAbsolute, join, normalize, resolve } from "path"
+import { readDecksState, writeDecksState } from "../decks-state"
+import { compileExecutiveBrief, DEFAULT_EXECUTIVE_BRIEF_PATH } from "../narrative-state/executive-brief"
+
+export interface BriefArgs {
+  outputPath?: string
+}
+
+export type ParseBriefArgsResult = { ok: true; args: BriefArgs } | { ok: false; error: string }
+
+export function parseBriefArgs(input: string): ParseBriefArgsResult {
+  const value = input.trim()
+  if (!value) return { ok: true, args: {} }
+  if (value.startsWith("--")) return { ok: false, error: "Usage: `/revela brief [workspace-relative-output.md]`" }
+  if (!value.endsWith(".md")) return { ok: false, error: "Executive brief output must be a Markdown file ending in `.md`." }
+  if (isAbsolute(value) || value.split(/[\\/]+/).includes("..")) return { ok: false, error: "Executive brief output must be a safe workspace-relative path." }
+  return { ok: true, args: { outputPath: normalize(value).replace(/\\/g, "/") } }
+}
+
+export async function handleBrief(
+  input: { workspaceRoot: string; outputPath?: string },
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  const statePath = join(input.workspaceRoot, "DECKS.json")
+  if (!existsSync(statePath)) {
+    await send("No `DECKS.json` found. Run `/revela init` before rendering an executive brief.")
+    return
+  }
+
+  const state = readDecksState(input.workspaceRoot)
+  const result = compileExecutiveBrief(state, { outputPath: input.outputPath })
+  if (!result.ok) {
+    await send(
+      `**Executive brief not rendered**\n\n${result.reason}\n\n` +
+      (result.narrativeHash ? `Narrative hash: \`${result.narrativeHash}\`\n\n` : "") +
+      "Run `/revela review` and approve the current narrative, or record an explicit render override before retrying."
+    )
+    return
+  }
+
+  const filePath = safeWorkspaceFilePath(input.workspaceRoot, result.outputPath)
+  mkdirSync(dirname(filePath), { recursive: true })
+  writeFileSync(filePath, result.content, "utf-8")
+  writeDecksState(input.workspaceRoot, result.state)
+
+  await send(
+    `**Executive brief rendered**\n\n` +
+    `- Output: \`${result.outputPath}\`\n` +
+    `- Render target: \`${result.target.id}\`\n` +
+    `- Narrative hash: \`${result.narrativeHash}\`\n\n` +
+    "The brief was compiled from canonical narrative state, not from a deck summary."
+  )
+}
+
+function safeWorkspaceFilePath(workspaceRoot: string, outputPath: string): string {
+  const relative = outputPath || DEFAULT_EXECUTIVE_BRIEF_PATH
+  if (isAbsolute(relative) || relative.split(/[\\/]+/).includes("..")) throw new Error("Executive brief output must be a safe workspace-relative path.")
+  const root = resolve(workspaceRoot)
+  const target = resolve(root, relative)
+  if (target !== root && !target.startsWith(`${root}/`)) throw new Error("Executive brief output must stay inside the workspace.")
+  return target
+}

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

@@ -28,11 +28,13 @@ export async function handleHelp(
     `\`/revela disable\`             — disable Revela mode\n` +
     `\`/revela init\`                — initialize or refresh workspace DECKS.json\n` +
     `\`/revela review\`              — review narrative readiness and approval state\n` +
+    `\`/revela narrative\`           — open read-only narrative workspace map\n` +
+    `\`/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/commands/narrative.ts

@@ -0,0 +1,160 @@
+import { mkdirSync, writeFileSync } from "fs"
+import { tmpdir } from "os"
+import { join } from "path"
+import { openUrl as defaultOpenUrl } from "../edit/open"
+import { hasDecksState, readDecksState } from "../decks-state"
+import { buildNarrativeMap, formatNarrativeMap } from "../narrative-state/map"
+import { renderNarrativeMapHtmlWithDisplay } from "../narrative-state/map-html"
+import { emptyDisplayModel, type NarrativeViewLanguage, type ValidatedNarrativeDisplayModel } from "../narrative-state/display"
+
+export interface NarrativeArgs {
+  language: NarrativeViewLanguage
+  raw: boolean
+}
+
+export type ParseNarrativeArgsResult = { ok: true; args: NarrativeArgs } | { ok: false; error: string }
+
+export function parseNarrativeArgs(param: string): ParseNarrativeArgsResult {
+  const tokens = param.trim().split(/\s+/).filter(Boolean)
+  let language: NarrativeViewLanguage = "en"
+  let raw = false
+  const languageParts: string[] = []
+  for (const token of tokens) {
+    const normalized = token.toLowerCase()
+    if (normalized === "--raw") {
+      raw = true
+      continue
+    }
+    if (token.startsWith("--") && token.length > 2) {
+      language = normalizeLanguageRequest(token.slice(2))
+      continue
+    }
+    languageParts.push(token)
+  }
+  if (languageParts.length > 0) language = normalizeLanguageRequest(languageParts.join(" "))
+  return { ok: true, args: { language, raw } }
+}
+
+function normalizeLanguageRequest(value: string): NarrativeViewLanguage {
+  const trimmed = value.trim()
+  const normalized = trimmed.toLowerCase()
+  if (["en", "eng", "english"].includes(normalized)) return "en"
+  if (["cn", "zh", "zh-cn", "chinese"].includes(normalized)) return "zh-CN"
+  if (["jp", "ja", "ja-jp", "japanese"].includes(normalized)) return "ja-JP"
+  return trimmed || "en"
+}
+
+export async function handleNarrative(
+  options: { workspaceRoot: string; openBrowser?: boolean; openUrl?: (url: string) => void; language?: NarrativeViewLanguage; display?: ValidatedNarrativeDisplayModel },
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  try {
+    if (!hasDecksState(options.workspaceRoot)) {
+      await send("No `DECKS.json` found. Run `/revela init` first to initialize the narrative workspace.")
+      return
+    }
+
+    const state = readDecksState(options.workspaceRoot)
+    const map = buildNarrativeMap(state)
+    const markdown = formatNarrativeMap(map)
+
+    if (options.openBrowser) {
+      const htmlPath = writeNarrativeMapHtml(map, options.display ?? emptyDisplayModel(options.language ?? "en"))
+      const url = `file://${htmlPath}`
+      try {
+        ;(options.openUrl ?? defaultOpenUrl)(url)
+        await send(`Opened read-only narrative workspace: ${url}\n\n${markdown}`)
+      } catch (e: any) {
+        await send(`Read-only narrative workspace generated but could not open automatically: ${url}\n\n${e.message || String(e)}\n\n${markdown}`)
+      }
+      return
+    }
+
+    await send(markdown)
+  } catch (e: any) {
+    await send(`**Narrative map failed:** ${e.message || String(e)}`)
+  }
+}
+
+export function buildNarrativeViewPrompt(options: { workspaceRoot: string; language: NarrativeViewLanguage }): string {
+  if (!hasDecksState(options.workspaceRoot)) {
+    return "No `DECKS.json` found. Tell the user to run `/revela init` before opening the narrative view. Do not call any tool."
+  }
+
+  const map = buildNarrativeMap(readDecksState(options.workspaceRoot))
+  const projection = {
+    narrativeHash: map.snapshot.narrativeHash,
+    language: options.language,
+    snapshot: map.snapshot,
+    claims: map.claimFlow.map((claim) => ({
+      id: claim.id,
+      kind: claim.kind,
+      importance: claim.importance,
+      evidenceStatus: claim.evidenceStatus,
+      text: claim.text,
+      supportedScope: claim.supportedScope,
+      unsupportedScope: claim.unsupportedScope,
+      evidence: claim.evidence.map((evidence) => ({ source: evidence.source, strength: evidence.strength, findingsFile: evidence.findingsFile, location: evidence.location, quote: evidence.quote, caveat: evidence.caveat, unsupportedScope: evidence.unsupportedScope })),
+    })),
+    relations: map.claimRelations.map((relation) => ({ id: relation.id, fromClaimId: relation.fromClaimId, toClaimId: relation.toClaimId, relation: relation.relation, rationale: relation.rationale, inferred: relation.inferred })),
+    researchGaps: map.researchGaps.map((gap) => ({ id: gap.id, targetType: gap.targetType, targetId: gap.targetId, status: gap.status, priority: gap.priority, question: gap.question })),
+    artifactCoverage: map.artifactCoverage.map((artifact) => ({ type: artifact.type, outputPath: artifact.outputPath, stale: artifact.stale, slideRefs: artifact.slideRefs.map((ref) => ({ claimId: ref.claimId, slideIndex: ref.slideIndex, role: ref.role, match: ref.match, location: ref.location })) })),
+  }
+
+  return `Prepare the read-only Revela narrative UI display model.
+
+Target language request: ${options.language}
+- The language value is passed from the user's /revela narrative arguments. Interpret it as the desired UI/display language.
+- Examples: --cn maps to zh-CN, --jp maps to ja-JP, while --fr, --de, --es, --ko, --Arabic, --Portuguese-BR, or a written language name should be localized normally into that requested language.
+- Default /revela narrative language is en when the user provides no language request.
+
+You must call the \`revela-narrative-view\` tool exactly once.
+
+Hard rules:
+- Do not mutate DECKS.json, deck HTML, evidence, claims, relations, approvals, or artifacts.
+- Do not invent new claims, evidence, relations, slide coverage, source paths, findings files, quotes, or caveats.
+- Preserve every claimId exactly.
+- Preserve every relation endpoint exactly: fromClaimId, toClaimId, relation.
+- You may only organize and localize display copy for the UI: pageTitle, summaryLine, section labels, claim card displayTitle, roleLabel, narrativeJob, evidenceSummary, riskOrGapSummary, relation displayLabel, and relation displayRationale.
+- For inferred relations, do not provide relation displayLabel or displayRationale; inferred relations are unconfirmed order notes, not causal/support/dependency judgments.
+- relation displayRationale may only localize or clarify an existing canonical relation rationale. If relation.rationale is missing or the relation is inferred, do not provide displayRationale; the UI will show the missing or inferred status.
+- Keep source paths, findings files, claim IDs, narrative hash, and numbers unchanged.
+- Translate normal UI/display text into the target language request: pageTitle, summaryLine, labels, claim displayTitle, roleLabel, narrativeJob, evidenceSummary, riskOrGapSummary, relation displayLabel, and relation displayRationale.
+- Do not translate claim IDs, relation endpoints, narrative hash, source paths, findings files, URLs, numbers, or quoted/source facts.
+- Use natural business and manufacturing terminology in the target language, not word-by-word machine translation.
+- If a fact is missing, describe it as missing instead of filling it in.
+
+Chinese localization rules when the target language request is Chinese, zh, zh-CN, --cn, 中文, or Simplified Chinese:
+- Use natural business/manufacturing Chinese, not word-by-word machine translation.
+- In manufacturing, industrial AI, automation, and autonomous systems context, translate "autonomy" as "自主化", "自主能力", or "自主系统". Do not translate it as "自治".
+- Translate "autonomous" as "自主的" / "自主化的" where appropriate, not "自治的".
+- Translate "architectural" as "架构层面的", "架构性", or "架构问题" according to context.
+- Slug-like or kebab-case claim text such as "autonomy-is-architectural" should become a readable displayTitle such as "自主化是架构问题" or "自主化必须作为架构问题处理", not a literal token-by-token translation.
+- If the canonical claim text is only a slug, preserve the claimId exactly but write displayTitle as a readable claim title.
+
+Call \`revela-narrative-view\` with:
+- language: ${options.language}
+- narrativeHash: ${map.snapshot.narrativeHash}
+- displayModel.version: 1
+- displayModel.language: ${options.language}
+- displayModel.claimCards only for claim IDs listed below
+- displayModel.relations only for relations listed below
+
+Compact deterministic narrative map:
+
+\`\`\`json
+${JSON.stringify(projection, null, 2)}
+\`\`\``
+}
+
+export function writeNarrativeMapHtml(map: ReturnType<typeof buildNarrativeMap>, display: ValidatedNarrativeDisplayModel = emptyDisplayModel("en")): string {
+  const dir = join(tmpdir(), "revela-narrative")
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, `${safeFilePart(map.snapshot.narrativeId)}-${map.snapshot.narrativeHash}.html`)
+  writeFileSync(file, renderNarrativeMapHtmlWithDisplay(map, display), "utf-8")
+  return file
+}
+
+function safeFilePart(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "narrative"
+}

package/lib/decks-state.ts

@@ -26,6 +26,7 @@ export type DeckProductionStatus = "planning" | "blocked" | "ready" | "written"
 export type SlideProductionStatus = "planned" | "ready" | "written" | "qa_passed" | "qa_failed"
 export type WriteReadinessStatus = "blocked" | "ready" | "written"
 export type NarrativeRole = "context" | "tension" | "evidence" | "recommendation" | "risk" | "ask" | "appendix" | "close"
+export type SlideClaimRefRole = "primary" | "supporting" | "evidence" | "risk" | "objection"
 
 export interface DecksState {
   version: 1
@@ -135,6 +136,9 @@ export interface SlideSpec {
   layout: string
   qa?: boolean
   components: string[]
+  claimIds?: string[]
+  claimRefs?: SlideClaimRef[]
+  evidenceBindingIds?: string[]
   content: {
     headline?: string
     body?: string[]
@@ -148,6 +152,12 @@ export interface SlideSpec {
   notes?: string
 }
 
+export interface SlideClaimRef {
+  claimId: string
+  role: SlideClaimRefRole
+  note?: string
+}
+
 export interface EvidenceRef {
   source: string
   quote?: string
@@ -1478,6 +1488,9 @@ function normalizeSlides(slides: SlideSpec[]): SlideSpec[] {
       title: slide.title ?? "",
       layout: slide.layout ?? "",
       components: slide.components ?? [],
+      claimIds: normalizeTextList(slide.claimIds),
+      claimRefs: normalizeSlideClaimRefs(slide.claimRefs),
+      evidenceBindingIds: normalizeTextList(slide.evidenceBindingIds),
       content: slide.content ?? {},
       evidence: slide.evidence ?? [],
       status: slide.status ?? "planned",
@@ -1485,6 +1498,26 @@ function normalizeSlides(slides: SlideSpec[]): SlideSpec[] {
     .sort((a, b) => a.index - b.index)
 }
 
+function normalizeSlideClaimRefs(refs: SlideClaimRef[] | undefined): SlideClaimRef[] {
+  const seen = new Set<string>()
+  const out: SlideClaimRef[] = []
+  for (const ref of refs ?? []) {
+    const claimId = cleanOptionalText(ref.claimId)
+    if (!claimId) continue
+    const role = isSlideClaimRefRole(ref.role) ? ref.role : "supporting"
+    const key = `${claimId}:${role}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    const note = cleanOptionalText(ref.note)
+    out.push({ claimId, role, ...(note ? { note } : {}) })
+  }
+  return out
+}
+
+function isSlideClaimRefRole(value: string | undefined): value is SlideClaimRefRole {
+  return value === "primary" || value === "supporting" || value === "evidence" || value === "risk" || value === "objection"
+}
+
 function normalizeNarrativeBrief(brief: NarrativeBrief | undefined): NarrativeBrief | undefined {
   if (!brief) return undefined
   const normalized: NarrativeBrief = {

package/lib/edit/prompt.ts

@@ -71,6 +71,9 @@ Instructions:
 - Make the smallest targeted change that satisfies the user's comment.
 - If there are multiple comments, apply them as one coherent edit pass and avoid changes from one comment overwriting another.
 - Each comment may reference one or more selected elements. Treat the elements in a single comment as a group.
+- Preserve the narrative boundary: if the requested edit changes audience framing, belief shift, decision/action, thesis, recommendation, claim wording, evidence scope, caveat, risk, objection, or decision ask, do not patch the HTML directly. Explain that the canonical narrative must be updated first through ${"`revela-decks`"} action ${"`upsertNarrative`"}, then reviewed/approved or explicitly overridden before updating the deck projection.
+- Pure artifact polish such as layout, spacing, typography, alignment, color, image crop, animation, export fidelity, or deck HTML contract fixes may remain an artifact-level edit.
+- If the request mixes content meaning and visual polish, treat it as narrative-impacting unless the user clarifies otherwise.
 - Preserve the existing deck structure, active design language, typography, spacing system, animations, and slide count unless the comment explicitly asks otherwise.
 - Do not rewrite unrelated slides or broad sections of the deck.
 - Locate each target primarily with slideIndex, slideTitle, selected text, nearbyText, and outerHTMLExcerpt. Use selector/domPath as hints; they may be approximate.