@cyber-dash-tech/revela 0.14.0 → 0.15.1

package/README.md

@@ -2,14 +2,14 @@
 
 **English** | [中文](README.zh-CN.md)
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-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)
+[![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 is an [OpenCode](https://opencode.ai) plugin for building trusted narrative artifacts from workspace sources, research, evidence, and user intent.
-Its first render target is still the HTML slide deck: enable Revela for the current session, assign a presentation task, and the agent can research, structure, write, QA, inspect, refine, and export a deck.
+Its first render target is still the HTML slide deck: start a Revela workflow command, assign a presentation task, and the agent can research, structure, write, QA, inspect, refine, and export a deck.
 
 **[Live Demo — The AI Power Shift](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)**
 
@@ -17,8 +17,8 @@ Its first render target is still the HTML slide deck: enable Revela for the curr
 
 ## What It Does
 
-- injects a narrative-first system prompt into your current agent with `/revela enable`
-- switches into deck-render prompt mode only when you explicitly start `/revela deck`
+- injects one-shot workflow instructions for explicit commands such as `/revela init`, `/revela story`, and `/revela make deck`
+- switches into deck-render prompt mode only when you explicitly start `/revela make deck`
 - supports workspace document discovery, transparent text extraction for `.pdf`, `.docx`, `.pptx`, and `.xlsx`, and cached embedded-material extraction for those formats
 - keeps `DECKS.json` as the current workspace state engine for sources, research actions, findings, claims, evidence, narrative intent, render targets, and readiness
 - reviews narrative readiness before artifact rendering, then separately gates deck HTML writes through deck/artifact readiness
@@ -85,12 +85,6 @@ If you use the local wrapper route, remove any `@cyber-dash-tech/revela` entry f
 
 ## Quick Start
 
-Enable Revela in the current session:
-
-```text
-/revela enable
-```
-
 Prepare the workspace when starting a new deck project:
 
 ```text
@@ -100,22 +94,23 @@ Prepare the workspace when starting a new deck project:
 Optionally switch design or domain:
 
 ```text
-/revela designs
-/revela designs summit
+/revela design
+/revela design use summit
 /revela domains deeptech-investment
 ```
 
-Then shape or review the narrative. When the narrative is ready and approved, start deck handoff:
+Then shape, research, or review the story. When the narrative is ready and approved, make the deck:
 
 ```text
-/revela review
-/revela deck
+/revela story
+/revela research
+/revela make deck
 ```
 
 If you need to check only the deck/artifact gate before HTML writing, use:
 
 ```text
-/revela deck --review
+/revela make deck --review
 ```
 
 Export when needed, either manually or by asking the agent to export:
@@ -125,7 +120,13 @@ Export when needed, either manually or by asking the agent to export:
 /revela pptx decks/humanoid-robotics.html
 ```
 
-Disable presentation mode when done:
+If you want normal chat messages to stay in Revela narrative mode between explicit commands, enable optional ambient mode:
+
+```text
+/revela enable
+```
+
+Disable ambient mode when done:
 
 ```text
 /revela disable
@@ -137,18 +138,31 @@ Disable presentation mode when done:
 
 ```text
 /revela                          show status and help
-/revela enable                   enable narrative/artifact mode for this session
-/revela disable                  disable Revela mode
+/revela enable                   optional ambient narrative mode for normal chat
+/revela disable                  disable ambient Revela mode
 
 /revela init                     initialize or refresh narrative workspace state
-/revela review                   review narrative readiness and approval state
-/revela deck                     start deck handoff from approved narrative
-/revela deck --review            review deck/artifact readiness before writing HTML
+/revela research                 research, bind evidence, and reduce story gaps/caveats
+/revela story                    open the read-only story workspace UI
+/revela make deck                make a deck from approved story state
+/revela make deck --review       review deck/artifact readiness before writing HTML
+/revela make brief [file.md]     render executive brief from approved story
 /revela remember <text>          save an explicit user/workflow preference
 /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 review                   legacy readiness report for story state
+/revela narrative                compatibility alias for /revela story
+/revela deck                     compatibility alias for /revela make deck
+/revela brief [file.md]          compatibility alias for /revela make brief
+
+/revela design                   list installed designs
+/revela design use <name>        activate a design
+/revela design new <name>        create a custom design with AI
+/revela design edit <name>       refine an existing custom design with AI
+/revela design preview [name]    open a design preview in the browser
+/revela design add <source>      install a design from URL, local path, or github:user/repo
+/revela design rm <name>         remove an installed design
 /revela designs                  list installed designs
 /revela designs <name>           activate a design
 /revela designs-new <name>       create a custom design with AI
@@ -166,15 +180,15 @@ 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` 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.
+Most `/revela` commands run locally with zero LLM cost. `/revela init`, `/revela research`, `/revela story`, `/revela review`, `/revela make deck`, `/revela remember`, `/revela design new`, and `/revela design edit` start AI-assisted workflows because they need to read or update project files. These workflow commands keep the visible chat message short and inject their detailed instructions through a one-shot system-prompt command intent. `/revela refine` 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` has been removed; use `/revela refine` instead. `/revela inspect` remains only as a deprecated compatibility shim to Refine.
 
 ---
 
 ## How It Works
 
-When Revela is enabled, it appends a generated prompt to the current agent's system prompt.
+Explicit Revela workflow commands append one-shot command instructions to the current agent's system prompt. `/revela enable` is optional ambient mode for keeping normal chat in Revela narrative mode between explicit commands.
 
-The default prompt is narrative-first: it focuses on audience belief shift, decision/action, thesis, claims, evidence boundaries, objections, risks, and approval. Active design CSS, layout catalogs, component indexes, chart rules, and deck HTML skeletons are intentionally omitted until `/revela deck` switches the session into deck-render mode.
+The default prompt is narrative-first: it follows `Init -> Research -> Story -> Make -> Refine` and focuses on audience belief shift, decision/action, thesis, claims, evidence boundaries, objections, risks, research gaps, and approval. Active design CSS, layout catalogs, component indexes, chart rules, and deck HTML skeletons are intentionally omitted until `/revela make deck` switches the session into deck-render mode or `/revela design` starts explicit design work.
 
 Deck-render mode is built from 3 layers:
 
@@ -183,7 +197,7 @@ Deck-render mode is built from 3 layers:
 3. active design - visual system, layouts, components, and chart rules
 
 Persistent preferences live in `~/.config/revela/config.json`.
-The enabled or disabled state is session-level only.
+The ambient enabled or disabled state is session-level only.
 
 ### Workspace State
 
@@ -207,20 +221,22 @@ Decks remain the primary authored artifact, but they are now treated as render t
 
 Use Revela as a narrative-first artifact workflow:
 
-1. Enable Revela with `/revela enable`.
-2. Run `/revela init` when starting in a new project or when the workspace has changed significantly.
-3. Use `/revela review` to check narrative readiness: audience, belief shift, decision/action, thesis, central claims, evidence, objections, risks, and approval state.
+1. Run `/revela init` when starting in a new project or when the workspace has changed significantly.
+2. Use `/revela research` when story gaps or unsupported central claims need external evidence; it should loop through research, evidence binding, claim/relation narrowing, and re-review until public research stops improving the state.
+3. Use `/revela story` to open the story workspace UI and inspect claim flow, evidence, caveats, research gaps, approval state, and artifact coverage.
 4. Approve the narrative or request revisions. If you intentionally render before full strategic approval, record an explicit render override.
-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.
+5. Run `/revela make deck` to compile the approved narrative into deck slide specs and enter deck-render mode, or `/revela make brief` to render an executive brief.
+6. Choose or confirm design only during deck handoff, then run the deck/artifact gate with `/revela make 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, 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.
+9. Use `/revela refine` for post-artifact changes; `/revela edit` has been removed and `/revela inspect` remains only for old scripts or habits.
 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.
+Use `/revela enable` only when you want ordinary chat messages, not just explicit `/revela ...` commands, to stay in Revela narrative mode.
+
+`/revela story` opens the read-only story workspace UI. `/revela review` produces the legacy readiness report for unclear audience, missing belief shift, missing decision/action, weak thesis, unsupported central claims, weak evidence, unsupported scope, unhandled objections, missing risk/assumption handling, stale approval, or missing approval. Neither command reviews design/layout readiness or writes the final deck.
 
-If Revela blocks a deck write, ask the agent to run `/revela deck --review`, resolve the reported artifact gaps, and try again. This protects the deck file from being overwritten before the slide specs, evidence projection, design/layout readiness, review snapshot, and deck HTML contract are ready.
+If Revela blocks a deck write, ask the agent to run `/revela make deck --review`, resolve the reported artifact gaps, and try again. This protects the deck file from being overwritten before the slide specs, evidence projection, design/layout readiness, review snapshot, and deck HTML contract are ready.
 
 To remember long-term preferences, use:
 
@@ -234,7 +250,7 @@ Do not use `remember` for temporary checklist state; use it only for durable use
 
 ## Research And File Ingestion
 
-When Revela is enabled, the agent can use:
+During Revela workflows, the agent can use:
 
 - `revela-workspace-scan` to discover PDFs, Office files, CSVs, Markdown, and text files in the workspace
 - the `revela-research` subagent for targeted web research
@@ -246,7 +262,7 @@ When Revela is enabled, the agent can use:
 Supported document extraction paths:
 
 - `@` reference or pasted file in chat
-- `read` tool access while Revela is enabled
+- `read` tool access during Revela workflows or ambient mode
 
 Supported extracted file types:
 
@@ -313,7 +329,7 @@ You can also run QA manually with the `revela-qa` tool.
 
 ## Designs And Domains
 
-Use `/revela designs` and `/revela domains` to inspect what is installed in your environment.
+Use `/revela design` and `/revela domains` to inspect what is installed in your environment. Older `/revela designs*` commands remain compatibility aliases.
 
 Bundled domains in this repository:
 
@@ -341,6 +357,7 @@ You can ask Revela to create a new local design interactively:
 
 ```text
 /revela designs-new my-design
+/revela design new my-design
 ```
 
 The agent will interview you for visual references, summarize a design brief for confirmation, then save `DESIGN.md` and `preview.html` into your local Revela designs directory. For AI-authored designs, `preview.html` is required: it must include cover and closing slides, and it must showcase every `@component:*` before `revela-designs-author` will accept the package. The default structural base is an internal neutral `starter` design, which is hidden from the normal design list. Use `--base summit` or `--base monet` only when you want to derive from those specific styles.
@@ -349,6 +366,7 @@ Refine an existing local design:
 
 ```text
 /revela designs-edit my-design
+/revela design edit my-design
 ```
 
 The agent will ask what to change, inspect the current design, confirm an edit brief, then overwrite the local design package through the controlled authoring tool.
@@ -357,6 +375,7 @@ Open a design preview in your browser:
 
 ```text
 /revela designs-preview my-design
+/revela design preview my-design
 ```
 
 Omit the name to preview the active design. If a design has no `preview.html`, Revela will report that no preview is available.
@@ -374,7 +393,7 @@ my-design/
 ```yaml
 ---
 name: my-design
-description: Short description shown in /revela designs
+description: Short description shown in /revela design
 author: you
 version: 1.0.0
 ---
@@ -564,9 +583,9 @@ If a design has no markers, Revela falls back to injecting the full `DESIGN.md`
 Install a custom 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
 ```
 
 ---
@@ -593,19 +612,19 @@ Use the unified refinement workspace for normal post-write review and revision:
 
 `/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.
 
-Deprecated compatibility command:
+Removed command:
 
 ```text
 /revela edit
 ```
 
-`/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.
+`/revela edit` has been removed. Use `/revela refine` for the unified reading, inspection, and editing workspace.
 
 Use `Ctrl`/`Cmd` + click to reference deck elements, write a natural-language comment in the Edit tab, then send it back to OpenCode. Revela sends a structured edit prompt that includes the deck file, slide context, selected element metadata, and your comment.
 
-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”.
+LLM tool equivalent: `revela-edit` with no target. The tool remains a compatibility shim and opens Refine in Edit mode when you say things like “I want to edit the deck”.
 
-For existing decks, `/revela edit` prepares whatever minimal project context is needed so targeted edits can still use the normal safety checks.
+For existing decks, `/revela refine` prepares whatever minimal project context is needed so targeted edits can still use the normal safety checks.
 
 ---
 

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-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)
+[![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,31 @@ 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                   打开统一的阅读、检查和编辑 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 +179,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` 是统一的 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` 命令都在本地执行，不消耗 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 refine`。`/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 +196,7 @@ Deck-render mode 由 3 层组成：
 3. 当前 active design - 视觉系统、layout、component 和图表规则
 
 持久化配置保存在 `~/.config/revela/config.json`。
-是否启用 Revela 则只在当前会话生效。
+ambient enable/disable 状态只在当前会话生效。
 
 ### Workspace State
 
@@ -206,20 +220,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 元素做可视化评论、精准修改、只读 Narrative Reading、有边界的 Exploratory Reading、Source、Purpose 检查，以及 claim-to-artifact coverage 查看。
-9. 只有旧脚本或旧习惯需要时，才使用 `/revela edit` 或 `/revela inspect`；两者都会打开对应模式的 `/revela refine`。
+9. post-artifact 修改统一使用 `/revela refine`；`/revela edit` 已移除，`/revela inspect` 仅保留给旧脚本或旧习惯。
 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 +249,7 @@ Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace s
 
 ## 调研与文件摄取
 
-启用 Revela 后，agent 可以使用：
+在 Revela workflow 中，agent 可以使用：
 
 - `revela-workspace-scan` 扫描工作区中的 PDF、Office 文件、CSV、Markdown 和文本文件
 - `revela-research` 子代理做定向网页调研
@@ -245,7 +261,7 @@ Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace s
 支持提取文本的入口：
 
 - 在对话里 `@` 引用或直接粘贴文件
-- 启用 Revela 后通过 `read` 工具访问文件
+- 在 Revela workflow 或 ambient mode 中通过 `read` 工具访问文件
 
 支持提取的文件类型：
 
@@ -279,7 +295,7 @@ Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace s
 
 ## Designs 与 Domains
 
-用 `/revela designs` 和 `/revela domains` 查看你当前环境里实际安装的内容。
+用 `/revela design` 和 `/revela domains` 查看你当前环境里实际安装的内容。旧的 `/revela designs*` 命令仍作为兼容别名保留。
 
 仓库内置的 domains：
 
@@ -307,6 +323,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 +332,7 @@ Agent 会先询问你的审美参考，整理设计 brief 并等待确认，然
 
 ```text
 /revela designs-edit my-design
+/revela design edit my-design
 ```
 
 Agent 会询问你想修改什么，读取当前 design，整理 edit brief 并等待确认，然后通过受控 authoring tool 覆盖保存本地 design 包。
@@ -323,6 +341,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 +359,7 @@ my-design/
 ```yaml
 ---
 name: my-design
-description: 在 /revela designs 中显示的简短说明
+description: 在 /revela design 中显示的简短说明
 author: you
 version: 1.0.0
 ---
@@ -529,9 +548,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
 ```
 
 ---
@@ -558,19 +577,19 @@ Prompt 注入规则：
 
 `/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 阅读、检查和编辑的推荐入口。
 
-Deprecated 兼容命令：
+已移除命令：
 
 ```text
 /revela edit
 ```
 
-`/revela edit` 不再打开独立的 edit-only shell。它会打开 `/revela refine` 的 Edit mode，用于兼容旧脚本和旧使用习惯。
+`/revela edit` 已移除。请使用 `/revela refine` 打开统一的阅读、检查和编辑 workspace。
 
 使用 `Ctrl`/`Cmd` + 点击 deck 元素来引用它们，在 Edit tab 写一段自然语言评论，然后发送回 OpenCode。Revela 会把 deck 文件、slide 上下文、选中元素 metadata 和你的评论整理成结构化 edit prompt。
 
-对应的 LLM tool：`revela-edit`，不需要 target。这个 tool 也是兼容入口，当你说“我要编辑这个 deck”时，agent 会打开 Refine 的 Edit mode。
+对应的 LLM tool：`revela-edit`，不需要 target。这个 tool 仍作为兼容入口保留，当你说“我要编辑这个 deck”时，agent 会打开 Refine 的 Edit mode。
 
-对于已有 HTML deck，`/revela edit` 会自动准备必要的最小项目上下文，让后续精准修改仍然经过正常安全检查。
+对于已有 HTML deck，`/revela refine` 会自动准备必要的最小项目上下文，让后续精准修改仍然经过正常安全检查。
 
 ---