@cyber-dash-tech/revela 0.10.0 → 0.12.0

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-178%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-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)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="800" />
 </p>
 
-Revela is an [OpenCode](https://opencode.ai) plugin that turns your current agent into an HTML slide deck generator.
-Enable it for the current session, assign a presentation task, and the agent can research, structure, write, QA, and export a deck.
+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.
 
 **[Live Demo — The AI Power Shift](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)**
 
@@ -17,11 +17,13 @@ Enable it for the current session, assign a presentation task, and the agent can
 
 ## What It Does
 
-- injects a presentation-specific system prompt into your current agent with `/revela enable`
-- builds that prompt from 3 layers: core skill, active domain, active design
+- 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`
 - supports workspace document discovery, transparent text extraction for `.pdf`, `.docx`, `.pptx`, and `.xlsx`, and cached embedded-material extraction for those formats
-- keeps track of deck context, slide structure, sources, and readiness across the current workspace
-- checks for missing context, weak evidence, and incomplete structure before writing `decks/*.html`
+- 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
+- records review snapshots so stale readiness cannot silently authorize new deck HTML after important state changes
+- treats HTML decks, PDF, and PPTX as render targets from shared workspace state rather than isolated output files
 - runs fast design compliance checks whenever the agent writes, patches, or edits `decks/*.html`
 - opens a visual comment editor for existing decks so users can Ctrl/Cmd-click elements and send precise edit requests back to OpenCode
 - exports finished decks to PDF and editable PPTX
@@ -103,16 +105,17 @@ Optionally switch design or domain:
 /revela domains deeptech-investment
 ```
 
-Then give the agent a deck task:
+Then shape or review the narrative. When the narrative is ready and approved, start deck handoff:
 
 ```text
-Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main market drivers, use the active design faithfully, and save the result to decks/humanoid-robotics.html.
+/revela review
+/revela deck
 ```
 
-If the task depends on sources, research, or a confirmed slide plan, you can ask Revela to review whether the deck has enough context, structure, and evidence before writing:
+If you need to check only the deck/artifact gate before HTML writing, use:
 
 ```text
-/revela review
+/revela deck --review
 ```
 
 Export when needed, either manually or by asking the agent to export:
@@ -134,11 +137,13 @@ Disable presentation mode when done:
 
 ```text
 /revela                          show status and help
-/revela enable                   enable presentation mode for this session
-/revela disable                  disable presentation mode
+/revela enable                   enable narrative/artifact mode for this session
+/revela disable                  disable Revela mode
 
-/revela init                     prepare the workspace for a deck project
-/revela review                   check whether context, structure, and evidence are ready
+/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 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/
@@ -161,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 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` 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.
 
 ---
 
@@ -169,34 +174,53 @@ Most `/revela` commands run locally with zero LLM cost. `/revela init`, `/revela
 
 When Revela is enabled, it appends a generated prompt to the current agent's system prompt.
 
-That prompt is built from 3 layers:
+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.
+
+Deck-render mode is built from 3 layers:
 
-1. `skill/SKILL.md` - the core slide-generation workflow
+1. `skill/SKILL.md` - the core deck-render workflow
 2. active domain - domain-specific report structure and terminology
 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.
 
+### Workspace State
+
+`DECKS.json` is Revela's workspace state engine and compatibility file. It is still stored at the workspace root and remains readable as the current deck project state, but internally Revela now treats it as a lightweight persistence layer for more than a deck checklist.
+
+The state records:
+
+- workspace source materials and reusable extraction cache paths
+- research plans, saved findings, and compact action provenance
+- canonical narrative state, approvals, objections, risks, slide specs, claim candidates, and evidence trace
+- render targets such as the active HTML deck plus derived PDF and PPTX artifacts
+- review snapshots with input hashes so old readiness results become stale after meaningful state changes
+
+Existing root `DECKS.json` workspaces remain compatible. Running `/revela init` or `/revela review` on an older project can normalize canonical narrative state and refresh projection fields without requiring a manual migration, moving files, or replacing `DECKS.json` with a database. `writeReadiness.status: "ready"` is deck/artifact readiness only; it is never narrative approval.
+
+Decks remain the primary authored artifact, but they are now treated as render targets from the same workspace state that can later support briefs, appendix material, Evidence Inspector views, Q&A, and interactive reading layers without duplicating source/evidence logic.
+
 ---
 
 ## Recommended Workflow
 
-Use Revela as a guided deck-production mode:
+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. Choose a design or domain if the default style is not right.
-4. Give the agent a clear deck task: audience, goal, language, number of slides, source requirements, and output path.
-5. Use `/revela review` before writing if the deck needs research, citations, or a confirmed slide plan.
-6. Let the agent write the HTML deck under `decks/`.
-7. Use `/revela refine` for visual comments, targeted revisions, and optional Source/Purpose inspection of selected deck elements.
-8. Use `/revela edit` or `/revela inspect` directly only if you need the older single-purpose shells.
-9. Export with `/revela pdf <file>` or `/revela pptx <file>`.
+3. Use `/revela review` to check narrative readiness: audience, belief shift, decision/action, thesis, central claims, evidence, objections, risks, and approval state.
+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.
+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.
+10. Export with `/revela pdf <file>` or `/revela pptx <file>`.
 
-`/revela review` checks for practical readiness problems: unclear audience, missing source material, unfinished research, unsupported claims, weak source trace, incomplete slide structure, missing design/layout information, or lightweight narrative issues such as weak so-what, missing risk/assumption handling, and abrupt transitions. It does not write the final deck.
+`/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.
 
-If Revela blocks a deck write, ask the agent to run `/revela review`, resolve the reported gaps, and try again. This protects the deck file from being overwritten before the plan, evidence, and structure are ready.
+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.
 
 To remember long-term preferences, use:
 
@@ -597,6 +621,8 @@ The inspector opens in your browser with the deck on the left and fixed cards on
 
 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.
 
+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.
+
 ---
 
 ## Export

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-178%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-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)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="800" />
 </p>
 
-Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使用的 agent 变成 HTML 幻灯片生成器。
-在当前会话中启用之后，agent 可以完成调研、结构设计、HTML 写作、QA 和导出。
+Revela 是一个 [OpenCode](https://opencode.ai) 插件，用来把工作区来源材料、调研、证据和用户意图转成可信的叙事型沟通 artifact。
+它的第一个 render target 仍然是 HTML slide deck：在当前会话中启用之后，agent 可以完成调研、结构设计、HTML 写作、QA、检查、refine 和导出。
 
 **[在线演示 — AI 权力转移](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)**
 
@@ -17,11 +17,13 @@ Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使
 
 ## 它能做什么
 
-- 通过 `/revela enable` 向当前 agent 注入演示文稿专用 system prompt
-- prompt 由 3 层组成：核心 skill、当前 domain、当前 design
+- 通过 `/revela enable` 向当前 agent 注入 narrative-first system prompt
+- 只有在显式运行 `/revela deck` 时，才切换到 deck-render prompt mode
 - 支持工作区文档扫描，以及 `.pdf`、`.docx`、`.pptx`、`.xlsx` 的透明文本提取和嵌入素材缓存提取
-- 在当前工作区持续跟踪 deck 背景、页面结构、来源材料和 readiness
-- 写入 `decks/*.html` 前检查是否缺上下文、证据或结构
+- 将 `DECKS.json` 作为当前 workspace state engine，持续记录来源材料、调研动作、findings、claims、证据、叙事意图、render targets 和 readiness
+- 先检查 narrative readiness，再用独立 deck/artifact gate 保护 deck HTML 写入
+- 记录 review snapshots，避免重要状态变化后旧的 ready 结果继续默默授权写入 deck HTML
+- 把 HTML deck、PDF 和 PPTX 视为来自同一 workspace state 的 render targets，而不是互相孤立的输出文件
 - agent 每次写入、patch 或 edit `decks/*.html` 时自动执行快速 design compliance 检查
 - 为已有 deck 打开可视化评论编辑器，用户可以 Ctrl/Cmd + 点击元素，并把精确修改意见发回 OpenCode
 - 支持导出成 PDF 和可编辑 PPTX
@@ -102,16 +104,17 @@ export { default } from "/absolute/path/to/revela/index.ts";
 /revela domains deeptech-investment
 ```
 
-然后直接给 agent 一个 deck 任务：
+然后先打磨或检查叙事。叙事 ready 并获得批准后，再进入 deck handoff：
 
 ```text
-Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main market drivers, use the active design faithfully, and save the result to decks/humanoid-robotics.html.
+/revela review
+/revela deck
 ```
 
-如果任务依赖来源材料、调研或已确认的 slide plan，可以先让 Revela 检查上下文、结构和证据是否足够：
+如果只需要检查写 HTML 前的 deck/artifact gate，使用：
 
 ```text
-/revela review
+/revela deck --review
 ```
 
 需要导出时，可以手动调用，也可以让 agent 直接导出：
@@ -133,11 +136,13 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 
 ```text
 /revela                          显示当前状态与帮助
-/revela enable                   为当前会话启用演示文稿模式
-/revela disable                  关闭演示文稿模式
+/revela enable                   为当前会话启用 narrative/artifact 模式
+/revela disable                  关闭 Revela 模式
 
-/revela init                     为当前 deck 项目准备工作区
-/revela review                   检查上下文、结构和证据是否 ready
+/revela init                     初始化或刷新 narrative workspace state
+/revela review                   检查 narrative readiness 和 approval state
+/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 的可视化编辑器
@@ -160,7 +165,7 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 /revela pptx <file>              将 HTML deck 导出为同目录可编辑 PPTX
 ```
 
-大多数 `/revela` 命令都在本地执行，不消耗 LLM token。`/revela init`、`/revela review`、`/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` 会打开一个本地浏览器 workspace，里面有 Edit 和 Inspect 两个 tab，并共享同一套 Cmd/Ctrl-click 元素引用。Edit 会把精准修改评论发回当前 OpenCode 会话；Inspect 会先渲染确定性 Source/Purpose 预处理结果，再 lazy 显示 LLM 生成的卡片。它没有聊天框，也不会修改 deck。
 
 ---
 
@@ -168,34 +173,53 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 
 启用 Revela 后，它会把一份动态生成的 prompt 追加到当前 agent 的 system prompt 中。
 
-这份 prompt 由 3 层组成：
+默认 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 前不会注入。
+
+Deck-render mode 由 3 层组成：
 
-1. `skill/SKILL.md` - 核心幻灯片生成流程
+1. `skill/SKILL.md` - 核心 deck-render 流程
 2. 当前 active domain - 行业结构与术语
 3. 当前 active design - 视觉系统、layout、component 和图表规则
 
 持久化配置保存在 `~/.config/revela/config.json`。
 是否启用 Revela 则只在当前会话生效。
 
+### Workspace State
+
+`DECKS.json` 是 Revela 当前的 workspace state engine，也是兼容旧工作流的状态文件。它仍然保存在工作区根目录，也仍然可以理解为当前 deck 项目的状态入口，但 Revela 内部已经不再把它当成单纯的 deck checklist。
+
+状态中会记录：
+
+- 工作区来源材料和可复用的 extraction cache 路径
+- 调研计划、已保存 findings，以及精简的 action provenance
+- canonical narrative state、approvals、objections、risks、slide specs、claim candidates 和 evidence trace
+- active HTML deck 以及派生 PDF、PPTX 等 render targets
+- 带 input hash 的 review snapshots，使重要状态变化后旧的 readiness 自动变 stale
+
+已有的根目录 `DECKS.json` 工作区继续兼容。对旧项目运行 `/revela init` 或 `/revela review` 时，可以安全 normalize canonical narrative state 并刷新 projection 字段；用户不需要手动迁移、不需要移动文件，也不需要把 `DECKS.json` 换成数据库。`writeReadiness.status: "ready"` 只代表 deck/artifact readiness，永远不等于 narrative approval。
+
+Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace state 渲染出来的目标之一。后续 briefs、appendix material、Evidence Inspector views、Q&A 和 interactive reading layers 都可以复用同一套来源/证据逻辑，而不是各自生成孤立内容。
+
 ---
 
 ## 推荐使用流程
 
-把 Revela 当成一个有检查环节的 deck 生产模式：
+把 Revela 当成 narrative-first artifact workflow：
 
 1. 用 `/revela enable` 启用 Revela。
 2. 新项目或工作区明显变化时，运行 `/revela init`。
-3. 如果默认风格不合适，先选择 design 或 domain。
-4. 给 agent 一个清楚的 deck 任务：受众、目标、语言、页数、来源要求和输出路径。
-5. 如果 deck 需要调研、引用或已确认的 slide plan，写作前先运行 `/revela review`。
-6. 让 agent 把 HTML deck 写到 `decks/` 下。
-7. 用 `/revela refine` 对选中 deck 元素做可视化评论、精准修改，以及可选的 Source/Purpose 检查。
-8. 只有在需要旧的单一功能 shell 时，才单独使用 `/revela edit` 或 `/revela inspect`。
-9. 用 `/revela pdf <file>` 或 `/revela pptx <file>` 导出。
+3. 用 `/revela review` 检查 narrative readiness：受众、信念变化、decision/action、thesis、central claims、证据、objections、risks 和 approval state。
+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。
+7. 只有 artifact gate ready 后，才让 agent 把 HTML deck 写到 `decks/` 下。
+8. 用 `/revela refine` 对选中 deck 元素做可视化评论、精准修改，以及可选的 Source/Purpose 检查。
+9. 只有在需要旧的单一功能 shell 时，才单独使用 `/revela edit` 或 `/revela inspect`。
+10. 用 `/revela pdf <file>` 或 `/revela pptx <file>` 导出。
 
-`/revela review` 检查的是实际生产问题：受众是否清楚、是否缺来源材料、调研是否完成、关键 claim 是否有证据、source trace 是否太弱、页面结构是否完整、design/layout 信息是否齐全，以及轻量叙事问题，例如 so-what 不清晰、缺少风险/假设处理或转场突兀。它不会写最终 deck。
+`/revela review` 检查的是 narrative readiness：受众不清、缺信念变化、缺 decision/action、thesis 弱、central claims 无证据、evidence 弱、unsupported scope、objection 未处理、缺风险/假设处理、approval stale 或缺 approval。它不检查 design/layout readiness，也不会写最终 deck。
 
-如果 Revela 阻止写入 deck，直接让 agent 运行 `/revela review`，根据报告补齐缺口后再写。这样可以避免在计划、证据或结构还不完整时覆盖真实 deck 文件。
+如果 Revela 阻止写入 deck，直接让 agent 运行 `/revela deck --review`，根据报告补齐 artifact 缺口后再写。这样可以避免在 slide specs、evidence projection、design/layout readiness、review snapshot 和 deck HTML contract 还不完整时覆盖真实 deck 文件。
 
 记住长期偏好请使用：
 
@@ -562,6 +586,8 @@ Inspector 会在浏览器中打开，左侧是 deck，右侧是固定卡片：So
 
 Inspector 不是聊天，也没有自由输入框。它不会修改 `DECKS.json` 或 deck HTML。它使用已记录的 slide spec、narrative state 和 slide-level evidence trace 作为 grounded context。确定性预处理会立即显示；LLM judgment 随后 lazy 更新 Source 和 Purpose 卡片，不会强行生成编辑动作。
 
+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 工作流信任它之前被拒绝或报告。
+
 ---
 
 ## 导出

package/lib/commands/designs.ts

@@ -35,8 +35,8 @@ export async function handleDesignsActivate(
 ): Promise<void> {
   try {
     activateDesign(name)
-    buildPrompt()
-    await send(`**Design activated:** \`${name}\`\nPrompt rebuilt. The new visual style will apply to the next message.`)
+    buildPrompt({ mode: "narrative" })
+    await send(`**Design activated:** \`${name}\`\nNarrative prompt rebuilt. The design will apply when \`/revela deck\` enters deck-render mode.`)
   } catch (e: any) {
     await send(`**Error:** ${e.message}`)
   }

package/lib/commands/domains.ts

@@ -35,8 +35,8 @@ export async function handleDomainsActivate(
 ): Promise<void> {
   try {
     activateDomain(name)
-    buildPrompt()
-    await send(`**Domain activated:** \`${name}\`\nPrompt rebuilt. The new domain context will apply to the next message.`)
+    buildPrompt({ mode: "narrative" })
+    await send(`**Domain activated:** \`${name}\`\nNarrative prompt rebuilt. Domain reasoning applies now; deck-specific render guidance applies during \`/revela deck\`.`)
   } catch (e: any) {
     await send(`**Error:** ${e.message}`)
   }

package/lib/commands/enable.ts

@@ -1,7 +1,7 @@
 /**
  * lib/commands/enable.ts
  *
- * Handler for `/revela enable` — activates slide generation mode.
+ * Handler for `/revela enable` — activates Revela narrative/artifact mode.
  */
 
 import { existsSync } from "fs"
@@ -19,30 +19,30 @@ export async function handleEnable(
   const design = activeDesign()
   const domain = activeDomain()
 
-  // Health check: ensure the active prompt file exists.
-  // If startup failed (e.g. SKILL.md missing), rebuild now so the user gets a working session.
+  // Always rebuild narrative mode on enable. A prior `/revela 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 })
-    try {
-      buildPrompt()
-      log.info("prompt rebuilt on enable", { design, domain, promptFile: ACTIVE_PROMPT_FILE })
-    } catch (e) {
-      log.error("prompt rebuild failed on enable", { error: e instanceof Error ? e.message : String(e) })
-      await send(
-        `**Revela enabled (with warnings).** Slide generation mode is active, ` +
-        `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}\``
-      )
-      return
-    }
+  }
+  try {
+    buildPrompt({ mode: "narrative" })
+    log.info("narrative prompt rebuilt on enable", { design, domain, promptFile: ACTIVE_PROMPT_FILE })
+  } 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, ` +
+      `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}\``
+    )
+    return
   }
 
   log.info("revela enabled", { design, domain })
   await send(
-    `**Revela enabled.** Slide generation mode is now active.\n` +
+    `**Revela enabled.** Narrative/artifact mode is now active.\n` +
     `Design: \`${design}\` · Domain: \`${domain}\`\n\n` +
-    `The three-layer slide generation prompt will be injected into every message. ` +
-    `Describe your presentation to get started.`
+    `The narrative-first prompt will be injected into every message. ` +
+    `Use \`/revela deck\` when you are ready to enter deck-render mode.`
   )
 }

package/lib/commands/help.ts

@@ -24,10 +24,12 @@ export async function handleHelp(
     `🟠 **Domain:** \`${domain}\`\n\n` +
     `---\n\n` +
     `**Commands**\n\n` +
-    `\`/revela enable\`              — enable slide generation mode\n` +
-    `\`/revela disable\`             — disable slide generation mode\n` +
+    `\`/revela enable\`              — enable Revela narrative/artifact mode\n` +
+    `\`/revela disable\`             — disable Revela mode\n` +
     `\`/revela init\`                — initialize or refresh workspace DECKS.json\n` +
-    `\`/revela review\`              — review current deck readiness before writing HTML\n` +
+    `\`/revela review\`              — review narrative readiness and approval state\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` +

package/lib/commands/init.ts

@@ -9,17 +9,17 @@ export function buildInitPrompt({
 }): string {
   const mode = exists
     ? `A ${DECKS_STATE_FILE} file already exists. Read it first through the revela-decks tool and update it conservatively.`
-    : `No ${DECKS_STATE_FILE} file exists yet. Create it through the revela-decks tool.`
+    : `No ${DECKS_STATE_FILE} file exists yet. Create it through the revela-decks tool only when there is enough stable workspace or narrative context.`
 
-  return `Initialize Revela workspace state and deck workboard.
+  return `Initialize Revela narrative workspace state.
 
 Goal:
-- Build or update ${DECKS_STATE_FILE}, the workspace-level machine-readable state file for slide deck work.
+- 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 project context, professional/domain context, topic, audience, available source materials, the current deck artifact, slide specs, and open questions for future sessions.
-- Do not treat initialization as permission to write a slide deck; the current deck must pass a later readiness review.
-- ${DECKS_STATE_FILE} is the source of truth for the single current workspace deck.
-- \`slides\` is the only slide-plan source of truth. Do not track or infer a separate slide count field.
+- 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 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.
 
 Current state:
 - ${mode}
@@ -35,30 +35,41 @@ Workspace boundary rules:
 
 Workflow:
 1. Use the \`revela-workspace-scan\` tool to inspect document and data files in the workspace. Start with no \`path\` and \`max_depth: 2\`.
-2. Separately search for existing deck outputs and deck history, especially:
+2. Separately search for existing artifact history, especially:
    - \`decks/**/*.html\`
    - \`slides/**/*.html\`
    - \`presentations/**/*.html\`
    - \`decks/**/*.pdf\`
    - \`slides/**/*.pdf\`
-   Run these searches only inside the current workspace root. These are generated/output decks, not necessarily source materials. If \`decks/\` contains exactly one HTML file, treat it as the current deck artifact. If \`decks/\` contains multiple HTML files, stop and ask the user to move extra decks to separate workspaces before adopting one.
+   Run these searches only inside the current workspace root. These are generated/output artifacts, not necessarily source materials. If \`decks/\` contains exactly one HTML file, record it as existing artifact history and possible current deck artifact. If \`decks/\` contains multiple HTML files, do not guess which one is canonical; ask the user which artifact belongs to this workspace or whether extra decks should move to separate workspaces.
 3. Register or refresh source material records by passing the scan result's \`sourceMaterial\` objects to \`revela-decks\` action \`init\`. Preserve unchanged existing records; the tool will upsert by path and fingerprint.
-4. Select the files that look most relevant for future slide decks. Prioritize source decks, PDFs, Word docs, spreadsheets, CSVs, Markdown, text notes, and relevant existing generated decks.
-5. Do not automatically extract every PDF/PPTX/DOCX/XLSX during init. Call \`revela-extract-document-materials\` only for selected files that are clearly needed to form conservative workspace memory, or when the user explicitly asked to analyze the material now.
+4. Select the files that look most relevant for understanding the narrative problem. Prioritize source decks, PDFs, Word docs, spreadsheets, CSVs, Markdown, text notes, and relevant existing generated artifacts.
+5. Do not automatically extract every PDF/PPTX/DOCX/XLSX during init. Call \`revela-extract-document-materials\` only for selected files that are clearly needed to form conservative narrative memory, or when the user explicitly asked to analyze the material now.
 6. Before extracting or deeply reading a selected document, check \`DECKS.json.workspace.sourceMaterials\`. If the same path has the same fingerprint and valid extraction paths, reuse those paths instead of repeating extraction.
-7. Read only the materials needed to form a conservative workspace memory. Do not exhaustively read every file if the workspace is large.
-8. If this conversation or the workspace contains a concrete deck task or an existing deck artifact, call \`revela-decks\` with action \`upsertDeck\` and later \`upsertSlides\` for explicit deck information. Do not pass or ask for a deck key; the tool uses the workspace folder name internally. Do not mark readiness ready during init.
-9. When adopting an existing HTML deck, analyze the artifact and create one conservative \`SlideSpec\` per identifiable slide/page. Record only visible source notes or explicit source information as evidence; do not infer original evidence that is not present in the artifact.
-10. When a read or extracted source material clearly supports a specific slide claim, you may attach compact evidence fields such as \`sourcePath\`, \`location\`, \`extractedTextPath\`, or \`extractedManifestPath\`. Attach extraction cache paths only when they support that specific claim, not to every slide by default.
-11. Treat \`workspace.sourceMaterials\` as a reusable candidate index, not proof by itself. A source material record alone is not slide evidence.
-12. Report what was initialized or updated and list any open questions.
+7. Read only the materials needed to form conservative narrative memory. Do not exhaustively read every file if the workspace is large.
+8. If enough information is available, preserve canonical narrative intent through \`revela-decks\` action \`upsertNarrative\`: audience intent, decision intent, thesis, central claims, explicit evidence bindings where known, objections, and risks. This does not require deck rendering inputs.
+9. If the workspace has explicit slide/deck information, existing HTML, or a user-requested deck task, you may also call \`upsertDeck\` and \`upsertSlides\` for explicit deck information. The tool projects canonical narrative state back to compatibility \`narrativeBrief\` when a deck record exists. Do not pass or ask for a deck key; the tool uses the workspace folder name internally. Do not mark deck readiness ready during init.
+10. When adopting an existing HTML deck, analyze the artifact and create one conservative \`SlideSpec\` per identifiable slide/page only if the artifact is clearly the current workspace artifact. Record only visible source notes or explicit source information as evidence; do not infer original evidence that is not present in the artifact.
+11. When a read or extracted source material clearly supports a specific narrative or slide claim, preserve compact evidence trace such as \`sourcePath\`, \`location\`, \`extractedTextPath\`, or \`extractedManifestPath\`. Attach extraction cache paths only when they support that specific claim, not to every claim or slide by default.
+12. Treat \`workspace.sourceMaterials\` as a reusable candidate index, not proof by itself. A source material record alone is not narrative evidence or slide evidence.
+13. Report what was initialized or updated and list the smallest open narrative questions needed to proceed.
+
+Narrative questions to ask only when missing:
+- Who is the primary audience?
+- What do they believe before this communication?
+- What should they believe after it?
+- What decision or action is required?
+- What is the working thesis or recommendation?
+- Which central claims support the thesis?
+- Which sources or findings support those claims?
+- What objections, risks, assumptions, or caveats could break the argument?
 
 Memory rules:
-- Only write facts supported by workspace files into ${DECKS_STATE_FILE} workspace state, source materials, deck memory, and open questions.
+- Only write facts supported by workspace files or explicit user statements into ${DECKS_STATE_FILE} workspace state, source materials, narrative compatibility fields, deck memory, and open questions.
 - Only write user preferences if the user explicitly stated that Revela should remember them.
 - Do not infer personal preferences from one-off requests.
 - Do not store secrets, credentials, API keys, tokens, account details, or sensitive personal information.
-- Do not mark writeReadiness as ready during init unless the current deck has already passed an explicit \`revela-decks\` review.
+- Do not mark narrative approval, render override, or writeReadiness as ready during init.
 - Treat this workspace as a single deck project. If the user wants another deck, guide them to create another workspace/folder rather than adding a second deck record.
 - If new evidence conflicts with existing memory, preserve both briefly and add an Open Question instead of silently overwriting.
 

package/lib/commands/inspect.ts

@@ -11,7 +11,7 @@ export async function handleInspect(
       workspaceRoot: options.workspaceRoot,
     })
     await send(
-      `Opened Evidence Inspector for the only deck in \`decks/\`.\n` +
+      `Opened Evidence Inspector for the active HTML deck.\n` +
       `File: \`${result.deck.file}\`\n` +
       `${result.stateNote}\n` +
       `URL: ${result.url}\n\n` +

package/lib/commands/pdf.ts

@@ -8,28 +8,41 @@
  */
 
 import { resolve } from "path"
+import { hasDecksState, readDecksState } from "../decks-state"
 import { exportToPdf } from "../pdf/export"
 import { assertExportQAPassed } from "../qa/export-gate"
+import { recordRenderedArtifact, workspaceRelative } from "../workspace-state/rendered-artifacts"
+import { resolveActiveHtmlDeckPath } from "../workspace-state/render-targets"
 
 export async function handlePdf(
   filePath: string,
   send: (text: string) => Promise<void>,
+  workspaceRoot = process.cwd(),
 ): Promise<void> {
-  if (!filePath) {
+  const root = resolve(workspaceRoot)
+  const resolvedFile = resolvePdfDeckFile(root, filePath)
+
+  if (!resolvedFile) {
     await send(
-      "**Usage:** `/revela pdf <file_path>`\n\n" +
+      "**Usage:** `/revela pdf [file_path]`\n\n" +
       "Example: `/revela pdf decks/my-deck.html`"
     )
     return
   }
 
-  const abs = resolve(filePath)
+  const abs = resolvedFile.absoluteFile
   await send(`Running pre-export QA for \`${abs}\`...`)
 
   try {
-    await assertExportQAPassed(abs)
+    await assertExportQAPassed(abs, { workspaceRoot: root })
     await send(`Exporting \`${abs}\` to PDF...`)
-    const result = await exportToPdf(filePath)
+    const result = await exportToPdf(abs)
+    recordRenderedArtifact(root, {
+      sourceHtmlPath: resolvedFile.file,
+      outputPath: result.outputPath,
+      type: "pdf",
+      actor: "revela-pdf",
+    })
     const secs = (result.durationMs / 1000).toFixed(1)
     await send(
       `**PDF exported successfully**\n\n` +
@@ -42,3 +55,18 @@ export async function handlePdf(
     await send(`**PDF export failed**\n\n\`\`\`\n${msg}\n\`\`\``)
   }
 }
+
+function resolvePdfDeckFile(workspaceRoot: string, filePath: string): { file: string; absoluteFile: string } | undefined {
+  const explicit = filePath.trim()
+  if (explicit) {
+    const absoluteFile = resolve(workspaceRoot, explicit)
+    return { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile }
+  }
+
+  if (!hasDecksState(workspaceRoot)) return undefined
+  const state = readDecksState(workspaceRoot)
+  const activePath = resolveActiveHtmlDeckPath(state)
+  if (!activePath) return undefined
+  const absoluteFile = resolve(workspaceRoot, activePath)
+  return { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile }
+}