@cyber-dash-tech/revela 0.13.0 → 0.15.0

package/README.zh-CN.md

@@ -2,14 +2,14 @@
 
 [English](README.md) | **中文**
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-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-380%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="800" />
 </p>
 
 Revela 是一个 [OpenCode](https://opencode.ai) 插件，用来把工作区来源材料、调研、证据和用户意图转成可信的叙事型沟通 artifact。
-它的第一个 render target 仍然是 HTML slide deck：在当前会话中启用之后，agent 可以完成调研、结构设计、HTML 写作、QA、检查、refine 和导出。
+它的第一个 render target 仍然是 HTML slide deck：启动 Revela workflow command 之后，agent 可以完成调研、结构设计、HTML 写作、QA、检查、refine 和导出。
 
 **[在线演示 — AI 权力转移](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)**
 
@@ -17,8 +17,8 @@ Revela 是一个 [OpenCode](https://opencode.ai) 插件，用来把工作区来
 
 ## 它能做什么
 
-- 通过 `/revela enable` 向当前 agent 注入 narrative-first system prompt
-- 只有在显式运行 `/revela deck` 时，才切换到 deck-render prompt mode
+- 为 `/revela init`、`/revela story`、`/revela make deck` 等显式命令注入一次性 workflow instructions
+- 只有在显式运行 `/revela make deck` 时，才切换到 deck-render prompt mode
 - 支持工作区文档扫描，以及 `.pdf`、`.docx`、`.pptx`、`.xlsx` 的透明文本提取和嵌入素材缓存提取
 - 将 `DECKS.json` 作为当前 workspace state engine，持续记录来源材料、调研动作、findings、claims、证据、叙事意图、render targets 和 readiness
 - 先检查 narrative readiness，再用独立 deck/artifact gate 保护 deck HTML 写入
@@ -84,12 +84,6 @@ export { default } from "/absolute/path/to/revela/index.ts";
 
 ## 快速开始
 
-先在当前会话中启用 Revela：
-
-```text
-/revela enable
-```
-
 在新项目里可以先准备工作区：
 
 ```text
@@ -99,22 +93,23 @@ export { default } from "/absolute/path/to/revela/index.ts";
 如有需要，先切换 design 或 domain：
 
 ```text
-/revela designs
-/revela designs summit
+/revela design
+/revela design use summit
 /revela domains deeptech-investment
 ```
 
-然后先打磨或检查叙事。叙事 ready 并获得批准后，再进入 deck handoff：
+然后先打磨、调研或检查 story。叙事 ready 并获得批准后，再生成 deck：
 
 ```text
-/revela review
-/revela deck
+/revela story
+/revela research
+/revela make deck
 ```
 
 如果只需要检查写 HTML 前的 deck/artifact gate，使用：
 
 ```text
-/revela deck --review
+/revela make deck --review
 ```
 
 需要导出时，可以手动调用，也可以让 agent 直接导出：
@@ -124,7 +119,13 @@ export { default } from "/absolute/path/to/revela/index.ts";
 /revela pptx decks/humanoid-robotics.html
 ```
 
-完成后关闭演示文稿模式：
+如果希望普通聊天消息在显式命令之间也保持 Revela narrative mode，可以启用可选 ambient mode：
+
+```text
+/revela enable
+```
+
+完成后关闭 ambient mode：
 
 ```text
 /revela disable
@@ -136,18 +137,32 @@ export { default } from "/absolute/path/to/revela/index.ts";
 
 ```text
 /revela                          显示当前状态与帮助
-/revela enable                   为当前会话启用 narrative/artifact 模式
-/revela disable                  关闭 Revela 模式
+/revela enable                   可选：让普通聊天保持 ambient narrative mode
+/revela disable                  关闭 ambient Revela mode
 
 /revela init                     初始化或刷新 narrative workspace state
-/revela review                   检查 narrative readiness 和 approval state
-/revela deck                     从已批准 narrative 开始 deck handoff
-/revela deck --review            写 HTML 前检查 deck/artifact readiness
+/revela research                 调研、绑定证据，并减少 story gaps/caveats
+/revela story                    打开只读 story workspace UI
+/revela make deck                从已批准 story 生成 deck
+/revela make deck --review       写 HTML 前检查 deck/artifact readiness
+/revela make brief [file.md]     从已批准 story 渲染 executive brief
 /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 review                   legacy story readiness report
+/revela narrative                兼容别名，等同 /revela story
+/revela deck                     兼容别名，等同 /revela make deck
+/revela brief [file.md]          兼容别名，等同 /revela make brief
+
+/revela design                   列出已安装 design
+/revela design use <name>        激活某个 design
+/revela design new <name>        通过 AI 创建一个自定义 design
+/revela design edit <name>       通过 AI 调整已有自定义 design
+/revela design preview [name]    在浏览器中打开 design preview
+/revela design add <source>      从 URL、本地路径或 github:user/repo 安装 design
+/revela design rm <name>         删除已安装 design
 /revela designs                  列出已安装 design
 /revela designs <name>           激活某个 design
 /revela designs-new <name>       通过 AI 创建一个自定义 design
@@ -165,15 +180,15 @@ 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 research`、`/revela story`、`/revela review`、`/revela make deck`、`/revela remember`、`/revela design new` 和 `/revela design edit` 会启动 AI 辅助流程，因为它们需要读取或更新项目状态。这些 workflow command 只在可见聊天里显示短意图，详细内部说明通过一次性的 system-prompt command intent 注入。`/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 兼容入口保留。
 
 ---
 
 ## 工作原理
 
-启用 Revela 后，它会把一份动态生成的 prompt 追加到当前 agent 的 system prompt 中。
+显式 Revela workflow command 会把一次性 command instructions 追加到当前 agent 的 system prompt 中。`/revela enable` 是可选 ambient mode，用于让显式命令之间的普通聊天也保持 Revela narrative mode。
 
-默认 prompt 是 narrative-first：它关注受众信念变化、decision/action、thesis、claims、证据边界、objections、risks 和 approval。Active design CSS、layout catalog、component index、chart rules 和 deck HTML skeleton 在 `/revela deck` 切换到 deck-render mode 前不会注入。
+默认 prompt 是 narrative-first：它遵循 `Init -> Research -> Story -> Make -> Refine`，关注受众信念变化、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 由 3 层组成：
 
@@ -182,7 +197,7 @@ Deck-render mode 由 3 层组成：
 3. 当前 active design - 视觉系统、layout、component 和图表规则
 
 持久化配置保存在 `~/.config/revela/config.json`。
-是否启用 Revela 则只在当前会话生效。
+ambient enable/disable 状态只在当前会话生效。
 
 ### Workspace State
 
@@ -206,20 +221,22 @@ Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace s
 
 把 Revela 当成 narrative-first artifact workflow：
 
-1. 用 `/revela enable` 启用 Revela。
-2. 新项目或工作区明显变化时，运行 `/revela init`。
-3. 用 `/revela review` 检查 narrative readiness：受众、信念变化、decision/action、thesis、central claims、证据、objections、risks 和 approval state。
+1. 新项目或工作区明显变化时，运行 `/revela init`。
+2. 如果 story gaps 或 unsupported central claims 需要外部证据，用 `/revela research` 定向调研；它应循环执行 research、证据绑定、claim/relation 收窄和 re-review，直到公开调研无法继续改善状态。
+3. 用 `/revela story` 打开 story workspace UI，查看 claim flow、证据、caveats、research gaps、approval state 和 artifact coverage。
 4. 批准 narrative 或要求修改。如果需要在完整战略批准前渲染，必须记录 explicit render override。
-5. 运行 `/revela deck`，把已批准 narrative 编译成 deck slide specs，并进入 deck-render mode。
-6. 只在 deck handoff 阶段选择或确认 design，然后通过 handoff workflow 或 `/revela deck --review` 运行 deck/artifact gate。
+5. 运行 `/revela make deck`，把已批准 narrative 编译成 deck slide specs 并进入 deck-render mode，或运行 `/revela make brief` 渲染 executive brief。
+6. 只在 deck handoff 阶段选择或确认 design，然后通过 handoff workflow 或 `/revela make 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。
+只有当你希望普通聊天消息，而不只是显式 `/revela ...` 命令，也保持 Revela narrative mode 时，才需要使用 `/revela enable`。
+
+`/revela story` 打开只读 story workspace UI。`/revela review` 生成 legacy readiness report，用于检查受众不清、缺信念变化、缺 decision/action、thesis 弱、central claims 无证据、evidence 弱、unsupported scope、objection 未处理、缺风险/假设处理、approval stale 或缺 approval。两者都不检查 design/layout readiness，也不会写最终 deck。
 
-如果 Revela 阻止写入 deck，直接让 agent 运行 `/revela deck --review`，根据报告补齐 artifact 缺口后再写。这样可以避免在 slide specs、evidence projection、design/layout readiness、review snapshot 和 deck HTML contract 还不完整时覆盖真实 deck 文件。
+如果 Revela 阻止写入 deck，直接让 agent 运行 `/revela make deck --review`，根据报告补齐 artifact 缺口后再写。这样可以避免在 slide specs、evidence projection、design/layout readiness、review snapshot 和 deck HTML contract 还不完整时覆盖真实 deck 文件。
 
 记住长期偏好请使用：
 
@@ -233,7 +250,7 @@ Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace s
 
 ## 调研与文件摄取
 
-启用 Revela 后，agent 可以使用：
+在 Revela workflow 中，agent 可以使用：
 
 - `revela-workspace-scan` 扫描工作区中的 PDF、Office 文件、CSV、Markdown 和文本文件
 - `revela-research` 子代理做定向网页调研
@@ -245,7 +262,7 @@ Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace s
 支持提取文本的入口：
 
 - 在对话里 `@` 引用或直接粘贴文件
-- 启用 Revela 后通过 `read` 工具访问文件
+- 在 Revela workflow 或 ambient mode 中通过 `read` 工具访问文件
 
 支持提取的文件类型：
 
@@ -279,7 +296,7 @@ Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace s
 
 ## Designs 与 Domains
 
-用 `/revela designs` 和 `/revela domains` 查看你当前环境里实际安装的内容。
+用 `/revela design` 和 `/revela domains` 查看你当前环境里实际安装的内容。旧的 `/revela designs*` 命令仍作为兼容别名保留。
 
 仓库内置的 domains：
 
@@ -307,6 +324,7 @@ Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace s
 
 ```text
 /revela designs-new my-design
+/revela design new my-design
 ```
 
 Agent 会先询问你的审美参考，整理设计 brief 并等待确认，然后把 `DESIGN.md` 和 `preview.html` 保存到本地 Revela designs 目录。对 AI 生成的 design，`preview.html` 是必需验收面：它必须包含 cover 和 closing 页，并且必须展示所有 `@component:*`，否则 `revela-designs-author` 不会接受这个包。默认结构底座是内部中性 `starter` design，它不会出现在普通 design 列表中。只有当你明确想从 `summit` 或 `monet` 的具体风格派生时，才建议使用 `--base summit` 或 `--base monet`。
@@ -315,6 +333,7 @@ Agent 会先询问你的审美参考，整理设计 brief 并等待确认，然
 
 ```text
 /revela designs-edit my-design
+/revela design edit my-design
 ```
 
 Agent 会询问你想修改什么，读取当前 design，整理 edit brief 并等待确认，然后通过受控 authoring tool 覆盖保存本地 design 包。
@@ -323,6 +342,7 @@ Agent 会询问你想修改什么，读取当前 design，整理 edit brief 并
 
 ```text
 /revela designs-preview my-design
+/revela design preview my-design
 ```
 
 省略 name 时会打开当前 active design 的 preview。如果该 design 没有 `preview.html`，Revela 会提示没有可用 preview。
@@ -340,7 +360,7 @@ my-design/
 ```yaml
 ---
 name: my-design
-description: 在 /revela designs 中显示的简短说明
+description: 在 /revela design 中显示的简短说明
 author: you
 version: 1.0.0
 ---
@@ -529,9 +549,9 @@ Prompt 注入规则：
 安装自定义 design：
 
 ```text
-/revela designs-add github:your-org/your-design
-/revela designs-add https://example.com/my-design.zip
-/revela designs-add ./path/to/local/design-folder
+/revela design add github:your-org/your-design
+/revela design add https://example.com/my-design.zip
+/revela design add ./path/to/local/design-folder
 ```
 
 ---
@@ -556,19 +576,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 +596,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/command-intent.ts

@@ -0,0 +1,59 @@
+import type { PromptMode } from "./prompt-builder"
+
+export interface PendingCommandIntent {
+  sessionID: string
+  name: string
+  mode: PromptMode
+  visibleText: string
+  hiddenPrompt: string
+  createdAt: number
+}
+
+const pendingCommandIntents = new Map<string, PendingCommandIntent>()
+
+export function setPendingCommandIntent(intent: Omit<PendingCommandIntent, "createdAt"> & { createdAt?: number }): PendingCommandIntent {
+  const normalized: PendingCommandIntent = {
+    ...intent,
+    createdAt: intent.createdAt ?? Date.now(),
+  }
+  pendingCommandIntents.set(normalized.sessionID, normalized)
+  return normalized
+}
+
+export function peekPendingCommandIntent(sessionID: string): PendingCommandIntent | undefined {
+  if (!sessionID) return undefined
+  return pendingCommandIntents.get(sessionID)
+}
+
+export function takePendingCommandIntent(sessionID: string): PendingCommandIntent | undefined {
+  if (!sessionID) return undefined
+  const intent = pendingCommandIntents.get(sessionID)
+  if (intent) pendingCommandIntents.delete(sessionID)
+  return intent
+}
+
+export function clearPendingCommandIntent(sessionID: string): void {
+  if (!sessionID) return
+  pendingCommandIntents.delete(sessionID)
+}
+
+export function clearAllPendingCommandIntents(): void {
+  pendingCommandIntents.clear()
+}
+
+export function formatCommandIntentSystemBlock(intent: PendingCommandIntent): string {
+  return [
+    "<revela-command-intent>",
+    `User invoked: /revela ${intent.name}`,
+    `Prompt mode: ${intent.mode}`,
+    "Visible user intent:",
+    intent.visibleText,
+    "",
+    "Execute the hidden workflow instructions below with the available Revela tools.",
+    "Do not persist this command block as workspace memory or user preference.",
+    "",
+    "Hidden workflow instructions:",
+    intent.hiddenPrompt,
+    "</revela-command-intent>",
+  ].join("\n")
+}

package/lib/commands/brief.ts

@@ -34,7 +34,7 @@ export async function handleBrief(
     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."
+      "Run `/revela story` and approve the current narrative, or record an explicit render override before retrying."
     )
     return
   }

package/lib/commands/designs.ts

@@ -36,7 +36,7 @@ export async function handleDesignsActivate(
   try {
     activateDesign(name)
     buildPrompt({ mode: "narrative" })
-    await send(`**Design activated:** \`${name}\`\nNarrative prompt rebuilt. The design will apply when \`/revela deck\` enters deck-render mode.`)
+    await send(`**Design activated:** \`${name}\`\nNarrative prompt rebuilt. The design will apply when \`/revela make deck\` enters deck-render mode.`)
   } catch (e: any) {
     await send(`**Error:** ${e.message}`)
   }

package/lib/commands/domains.ts

@@ -36,7 +36,7 @@ export async function handleDomainsActivate(
   try {
     activateDomain(name)
     buildPrompt({ mode: "narrative" })
-    await send(`**Domain activated:** \`${name}\`\nNarrative prompt rebuilt. Domain reasoning applies now; deck-specific render guidance applies during \`/revela deck\`.`)
+    await send(`**Domain activated:** \`${name}\`\nNarrative prompt rebuilt. Domain reasoning applies now; deck-specific render guidance applies during \`/revela make deck\`.`)
   } catch (e: any) {
     await send(`**Error:** ${e.message}`)
   }

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/enable.ts

@@ -1,7 +1,7 @@
 /**
  * lib/commands/enable.ts
  *
- * Handler for `/revela enable` — activates Revela narrative/artifact mode.
+ * Handler for `/revela enable` — activates Revela ambient narrative mode.
  */
 
 import { existsSync } from "fs"
@@ -19,7 +19,7 @@ export async function handleEnable(
   const design = activeDesign()
   const domain = activeDomain()
 
-  // Always rebuild narrative mode on enable. A prior `/revela deck` handoff may
+  // Always rebuild narrative mode on enable. A prior `/revela make deck` handoff may
   // have intentionally switched the active prompt to deck-render mode.
   if (!existsSync(ACTIVE_PROMPT_FILE)) {
     log.warn("active prompt file missing on enable — rebuilding", { promptFile: ACTIVE_PROMPT_FILE })
@@ -30,7 +30,7 @@ export async function handleEnable(
   } catch (e) {
     log.error("prompt rebuild failed on enable", { error: e instanceof Error ? e.message : String(e) })
     await send(
-      `**Revela enabled (with warnings).** Narrative/artifact mode is active, ` +
+      `**Revela ambient mode enabled (with warnings).** Narrative mode is active for normal chat, ` +
       `but the prompt file could not be built. ` +
       `Try \`/revela disable\` then \`/revela enable\` again, or check that the package is correctly installed.\n\n` +
       `Design: \`${design}\` · Domain: \`${domain}\``
@@ -40,9 +40,9 @@ export async function handleEnable(
 
   log.info("revela enabled", { design, domain })
   await send(
-    `**Revela enabled.** Narrative/artifact mode is now active.\n` +
+    `**Revela ambient mode enabled.** Normal chat will stay in Revela narrative mode.\n` +
     `Design: \`${design}\` · Domain: \`${domain}\`\n\n` +
-    `The narrative-first prompt will be injected into every message. ` +
-    `Use \`/revela deck\` when you are ready to enter deck-render mode.`
+    `Explicit workflow commands like \`/revela init\`, \`/revela story\`, and \`/revela make deck\` work without enabling first. ` +
+    `Use \`/revela disable\` to return normal chat to plain OpenCode mode.`
   )
 }

package/lib/commands/help.ts

@@ -24,18 +24,27 @@ export async function handleHelp(
     `🟠 **Domain:** \`${domain}\`\n\n` +
     `---\n\n` +
     `**Commands**\n\n` +
-    `\`/revela enable\`              — enable Revela narrative/artifact mode\n` +
-    `\`/revela disable\`             — disable Revela mode\n` +
+    `\`/revela enable\`              — optional ambient narrative mode for normal chat\n` +
+    `\`/revela disable\`             — disable ambient 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 research\`            — research, bind evidence, and reduce story gaps\n` +
+    `\`/revela story\`               — open the read-only story workspace UI\n` +
+    `\`/revela review\`              — legacy readiness report for story state\n` +
+    `\`/revela narrative\`           — compatibility alias for /revela story\n` +
+    `\`/revela make deck\`           — make a deck from approved story state\n` +
+    `\`/revela make deck --review\`  — review deck/artifact readiness before writing HTML\n` +
+    `\`/revela make brief [file.md]\` — render executive brief from approved story\n` +
+    `\`/revela deck\`                — compatibility alias for /revela make deck\n` +
+    `\`/revela brief [file.md]\`      — compatibility alias for /revela make brief\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 design\`              — list installed designs\n` +
+    `\`/revela design use <name>\`   — activate a design\n` +
+    `\`/revela design new <name>\`   — create a custom design with AI\n` +
+    `\`/revela design edit <name>\`  — refine an existing custom design with AI\n` +
+    `\`/revela design preview [name]\` — open a design preview in browser\n` +
     `\`/revela designs\`             — list installed designs\n` +
     `\`/revela designs <name>\`      — activate a design\n` +
     `\`/revela designs-new <name>\`  — create a new custom design with AI\n` +

package/lib/commands/init.ts

@@ -17,7 +17,7 @@ Goal:
 - Build or update ${DECKS_STATE_FILE}, the workspace-level machine-readable state file for Revela narrative and artifact work.
 - Use the \`revela-decks\` tool for state updates. Do not write or patch ${DECKS_STATE_FILE} directly.
 - Capture stable narrative context first: primary audience, belief before, belief after, decision/action, thesis, central claims, evidence availability, objections, risks, available source materials, existing artifact history, and open questions.
-- Do not treat initialization as permission to write a deck. Narrative readiness is reviewed later by \`/revela review\`; deck/artifact readiness is reviewed by \`/revela deck --review\`.
+- Do not treat initialization as permission to write a deck. Narrative readiness is reviewed later by \`/revela story\`; deck/artifact readiness is reviewed by \`/revela make deck --review\`.
 - Do not require slide count, visual style, design selection, output path, layout choices, or component choices during narrative initialization unless the user explicitly asks to render a deck now.
 - ${DECKS_STATE_FILE} is the compatibility workspace-state file. Deck specs are render-target projections, not the center of initialization.
 

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/research.ts

@@ -0,0 +1,66 @@
+import { DECKS_STATE_FILE } from "../decks-state"
+
+export function buildResearchPrompt({
+  exists,
+  workspaceRoot,
+}: {
+  exists: boolean
+  workspaceRoot?: string
+}): string {
+  const state = exists
+    ? `${DECKS_STATE_FILE} exists. Read it through the revela-decks tool before researching.`
+    : `${DECKS_STATE_FILE} does not exist yet. Do not start broad internet research; initialize the workspace first with /revela init unless the user supplied a specific research question in chat.`
+
+  return `Run Revela closed-loop research.
+
+Goal:
+- Reduce open gaps, unsupported scope, weak evidence, unattached findings, and overextended relation rationale for the current story.
+- Drive research from canonical narrative gaps: unsupported central claims, objections, risks, decision questions, explicit researchGaps, and claim_chain_gap warnings.
+- Treat /revela research as authorization to bind clearly supported findings into canonical evidence without asking for item-by-item user confirmation.
+- Preserve evidence boundaries: eliminate caveats only when evidence or narrower wording actually resolves them; otherwise keep precise caveats visible.
+- Do not write decks, briefs, or design artifacts during research.
+
+Current state:
+- ${state}
+${workspaceRoot ? `- Current workspace root: \`${workspaceRoot}\`` : ""}
+
+Closed-loop workflow:
+1. Call \`revela-decks\` action \`read\`, then \`reviewNarrative\`.
+2. If current research gaps are missing or stale, call \`deriveResearchGaps\` when useful. Do not invent gaps that are not tied to a claim, objection, risk, decision, or narrative issue.
+3. Run up to 3 research loops unless the stop conditions below are met earlier.
+4. At the start of each loop, choose the highest-value 2-3 targets: open/in-progress high-priority gaps, unattached saved findings, unsupported central claims, weak evidence, high-priority objections/risks, and claim_chain_gap relations. Prefer targets that can improve readiness or materially reduce caveats. Do not repeat searches for claims already strongly supported.
+5. If a target already has saved findings, prioritize binding/narrowing before doing more external search.
+6. For targets needing external evidence, mark matching gaps \`in_progress\` with \`revela-decks updateResearchGap\`, then delegate search to the \`revela-research\` subagent. Ask it for source URLs, quotes/snippets, dates or locations when available, caveats, remaining gaps, and a \`## Recommended evidence bindings\` section with claimId, quote, source, supportScope, unsupportedScope, caveat, and strength. Save findings with \`revela-research-save\` under \`researches/{topic}/{axis}.md\` using \`## Data\`, \`## Cases\`, \`## Images\`, and \`## Gaps\` sections as applicable.
+7. After findings are saved or existing findings are selected, read or inspect the findings file. Attach it with \`revela-decks attachResearchFindings\` when it maps to an existing research axis.
+8. Automatically bind evidence when all binding criteria are met. Use \`revela-decks applyEvidenceCandidates\` for concrete candidate ids when available, or \`upsertNarrative\` to preserve canonical evidence bindings with exact source, URL/path, quote/snippet, support scope, unsupported scope, caveat, and strength.
+9. Binding criteria: claimId exists; quote/snippet is traceable to the source and is not invented; source URL or workspace source path is present; supportScope and unsupportedScope are explicit; strength is strong or useful partial; caveat is preserved; binding does not expand the claim beyond the evidence.
+10. If a claim or relation is broader than the evidence, narrow the claim text, supportedScope, unsupportedScope, or relation rationale through \`upsertNarrative\` only when the narrower wording preserves the user's strategic meaning and source boundaries. Do not silently change the decision ask, central recommendation, or approval meaning.
+11. Update matching gaps after binding: use \`evidence_bound\` when canonical evidence was added, \`closed\` when the gap is resolved or non-researchable, \`findings_saved\` only when findings exist but binding criteria are not met, and \`open\` with notes when more external research is still warranted.
+12. Re-run \`reviewNarrative\` after each loop. Compare against the previous loop: fewer open gaps, fewer unattached findings, stronger evidence, narrower unsupported scope, or clearer internal-data caveats should count as progress.
+
+Stop conditions:
+- No open externally researchable gaps remain.
+- All useful saved findings have been attached or evidence-bound.
+- A full loop produces no new bindable evidence, narrower wording, or gap status improvement.
+- Remaining gaps require internal user/company data, confidential sources, or strategic judgment.
+- 3 loops have completed.
+
+Report format:
+- Start with \`Research loop completed after <n> round(s).\`
+- List bound evidence by claim id and count.
+- List gaps closed or moved to evidence_bound.
+- List claims or relations narrowed, with the remaining unsupported scope.
+- List remaining caveats only as one of: \`internal_data_needed\`, \`not_publicly_researchable\`, \`source_quality_limit\`, or \`still_open\`.
+- If no binding happened, say why binding criteria failed and what exact source type is needed next.
+- End with the next smallest story action, not a generic request for user confirmation.
+
+Rules:
+- Do not use primary-agent broad websearch. Use the \`revela-research\` subagent for external search.
+- Do not invent quotes, source paths, URLs, page references, locations, or caveats.
+- Do not treat \`researches/**/*.md\` as canonical evidence until attached or evidence-bound, but do not stop at findings_saved when binding criteria are met.
+- Do not mutate canonical claims merely to fit a source; narrow only to preserve evidence boundaries and avoid overstated claims.
+- Do not ask the user to approve each evidence binding. Ask only when binding would change strategic meaning, downgrade a central claim, rely on suspicious sources, or require narrative approval.
+- Do not store secrets, credentials, tokens, or sensitive personal information.
+
+Start now by reading ${DECKS_STATE_FILE} through \`revela-decks\`, reviewing current readiness, and running the first research/binding loop.`
+}