@cyber-dash-tech/revela 0.11.0 → 0.13.0

package/README.md

@@ -2,7 +2,7 @@
 
 **English** | [中文](README.zh-CN.md)
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-302%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" />
@@ -17,11 +17,11 @@ Its first render target is still the HTML slide deck: enable Revela for the curr
 
 ## 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 `DECKS.json` as the current workspace state engine for sources, research actions, findings, claims, evidence, narrative intent, render targets, and readiness
-- checks for missing context, weak evidence, and incomplete structure before writing `decks/*.html`
+- 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`
@@ -105,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:
@@ -136,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/
@@ -163,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.
 
 ---
 
@@ -171,9 +174,11 @@ 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
 
@@ -188,11 +193,11 @@ The state records:
 
 - workspace source materials and reusable extraction cache paths
 - research plans, saved findings, and compact action provenance
-- narrative intent, objections, risks, slide specs, claim candidates, and slide-level evidence trace
+- 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
 
-0.11 keeps backward compatibility with existing root `DECKS.json` workspaces. Running `/revela init` or `/revela review` on an older project can normalize and refresh the new projection fields without requiring a manual migration, moving files, or replacing `DECKS.json` with a database.
+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.
 
@@ -200,21 +205,22 @@ Decks remain the primary authored artifact, but they are now treated as render t
 
 ## 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>`.
-
-`/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.
-
-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. In 0.11, review results are also saved as input-hashed snapshots; if sources, slide specs, evidence, narrative state, or the active render target changes afterward, the old review can no longer silently authorize a write.
+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 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 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:
 

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | **中文**
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-302%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" />
@@ -17,11 +17,11 @@ 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` 的透明文本提取和嵌入素材缓存提取
 - 将 `DECKS.json` 作为当前 workspace state engine，持续记录来源材料、调研动作、findings、claims、证据、叙事意图、render targets 和 readiness
-- 写入 `decks/*.html` 前检查是否缺上下文、证据或结构
+- 先检查 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 检查
@@ -104,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 直接导出：
@@ -135,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 的可视化编辑器
@@ -162,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。
 
 ---
 
@@ -170,9 +173,11 @@ 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 和图表规则
 
@@ -187,11 +192,11 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 
 - 工作区来源材料和可复用的 extraction cache 路径
 - 调研计划、已保存 findings，以及精简的 action provenance
-- narrative intent、objections、risks、slide specs、claim candidates 和 slide-level evidence trace
+- 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
 
-0.11 继续兼容已有的根目录 `DECKS.json` 工作区。对旧项目运行 `/revela init` 或 `/revela review` 时，可以安全 normalize 并刷新新的 projection 字段；用户不需要手动迁移、不需要移动文件，也不需要把 `DECKS.json` 换成数据库。
+已有的根目录 `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 都可以复用同一套来源/证据逻辑，而不是各自生成孤立内容。
 
@@ -199,21 +204,22 @@ Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace s
 
 ## 推荐使用流程
 
-把 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>` 导出。
-
-`/revela review` 检查的是实际生产问题：受众是否清楚、是否缺来源材料、调研是否完成、关键 claim 是否有证据、source trace 是否太弱、页面结构是否完整、design/layout 信息是否齐全，以及轻量叙事问题，例如 so-what 不清晰、缺少风险/假设处理或转场突兀。它不会写最终 deck。
-
-如果 Revela 阻止写入 deck，直接让 agent 运行 `/revela review`，根据报告补齐缺口后再写。这样可以避免在计划、证据或结构还不完整时覆盖真实 deck 文件。0.11 还会把 review 结果保存为带 input hash 的 snapshot；如果之后来源材料、slide specs、证据、叙事状态或 active render target 发生变化，旧 review 不能继续默默授权写入。
+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` 检查的是 narrative readiness：受众不清、缺信念变化、缺 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 文件。
 
 记住长期偏好请使用：
 

package/lib/commands/brief.ts

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

package/lib/commands/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,14 @@ 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 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` +

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.