@cyber-dash-tech/revela 0.4.6 → 0.5.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-138%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-207%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" />
@@ -20,6 +20,8 @@ Enable it for the current session, assign a presentation task, and the agent can
 - 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
 - supports workspace document discovery, transparent text extraction for `.pdf`, `.docx`, `.pptx`, and `.xlsx`, and cached embedded-material extraction for those formats
+- uses workspace `DECKS.json` as machine-readable deck memory, slide spec, and prewrite readiness state
+- blocks premature writes to `decks/*.html` until the active deck is marked structurally ready
 - runs automatic layout QA whenever the agent writes `decks/*.html`
 - exports finished decks to PDF and editable PPTX
 - switches designs and domains locally with zero LLM cost
@@ -86,6 +88,12 @@ Enable Revela in the current session:
 /revela enable
 ```
 
+Initialize workspace deck memory when starting in a new project:
+
+```text
+/revela init
+```
+
 Optionally switch design or domain:
 
 ```text
@@ -100,6 +108,12 @@ Then give the agent a deck task:
 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.
 ```
 
+Before the agent writes `decks/humanoid-robotics.html`, it must update `DECKS.json` through the `revela-decks` tool with the active deck, confirmed slide specs, layouts, components, and computed `writeReadiness.status: ready`. You can ask for an explicit readiness check at any time:
+
+```text
+/revela review humanoid-robotics
+```
+
 Export when needed:
 
 ```text
@@ -122,6 +136,10 @@ Disable presentation mode when done:
 /revela enable                   enable presentation mode for this session
 /revela disable                  disable presentation mode
 
+/revela init                     initialize or refresh workspace DECKS.json
+/revela review [slug]            review active deck readiness before writing HTML
+/revela remember <text>          save an explicit user/workflow preference
+
 /revela designs                  list installed designs
 /revela designs <name>           activate a design
 /revela designs-new <name>       create a custom design with AI
@@ -139,7 +157,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 designs-new` and `/revela designs-edit` start AI-assisted design authoring workflows.
+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.
 
 ---
 
@@ -158,6 +176,68 @@ The enabled or disabled state is session-level only.
 
 ---
 
+## DECKS.json Memory And Readiness Gate
+
+Revela uses a workspace-root `DECKS.json` file for cross-session continuity and deck production control. It is intended for tools and the LLM, not manual editing.
+
+It has two jobs:
+
+- workspace memory: stable project context, source materials, explicit user preferences, deck history, and open questions
+- active deck spec: current deck slug, output path, prerequisites, research plan, per-slide content, layouts, components, evidence, visuals, blockers, and write readiness
+
+`DECKS.md` is legacy fallback context only. `DECKS.json` is the source of truth.
+
+Create or refresh it with:
+
+```text
+/revela init
+```
+
+Review the current deck state with:
+
+```text
+/revela review [slug]
+```
+
+`/revela review` does not write the final HTML deck. It reads and updates `DECKS.json` through the `revela-decks` tool, checks what is missing, and sets `writeReadiness.status` to `ready` only when the deck is ready to generate.
+
+Minimum readiness conditions:
+
+- topic, audience, slide count, language, and visual style/design are decided
+- source materials are identified or explicitly deemed unnecessary
+- research need is assessed
+- needed research findings have been read and reflected in the slide specs
+- the user has confirmed the slide plan
+- required design layouts and components have been fetched
+- every slide has a title, layout, components, and structured content
+- no blockers remain
+
+The plugin enforces this before deck HTML is written. A write or patch touching `decks/*.html` is allowed only when the matching deck in `DECKS.json` passes the readiness gate. Direct writes or patches to `DECKS.json` are blocked; use `revela-decks` instead.
+
+The gate checks:
+
+- `writeReadiness.status` is `ready`
+- `writeReadiness.blockers` is empty
+- the deck `outputPath` exactly matches the target `decks/*.html` path
+- all `requiredInputs` booleans are true
+- `slides.length` matches `slideCount` when a slide count is set
+- every slide has title, layout, components, and structured content
+- every needed research axis is `done`, `read`, or `skipped`
+
+If the gate blocks a write, Revela writes a marker file under `.opencode/revela/blocked-writes/` instead of creating or overwriting the deck HTML. This makes the failure visible to the agent while keeping the real deck file untouched.
+
+For `apply_patch`, Revela only checks whether the patch touches `decks/*.html`. If not ready, the whole patch is replaced with a blocked marker patch. The `edit` tool is not gated.
+
+To remember long-term preferences, use:
+
+```text
+/revela remember Prefer concise Chinese consulting-style decks.
+```
+
+Do not use `remember` for temporary checklist state; temporary state belongs in the active deck spec in `DECKS.json`.
+
+---
+
 ## Research And File Ingestion
 
 When Revela is enabled, the agent can 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-125%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-207%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" />
@@ -20,6 +20,8 @@ Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使
 - 通过 `/revela enable` 向当前 agent 注入演示文稿专用 system prompt
 - prompt 由 3 层组成：核心 skill、当前 domain、当前 design
 - 支持工作区文档扫描，以及 `.pdf`、`.docx`、`.pptx`、`.xlsx` 的透明文本提取和嵌入素材缓存提取
+- 使用工作区 `DECKS.json` 保存机器可读的 deck 记忆、逐页规格和写入前 readiness 状态
+- 在 active deck 结构化 ready 前，阻止过早写入 `decks/*.html`
 - agent 每次写入 `decks/*.html` 时自动执行布局 QA
 - 支持导出成 PDF 和可编辑 PPTX
 - design 和 domain 的切换都在本地完成，不消耗 LLM token
@@ -85,6 +87,12 @@ export { default } from "/absolute/path/to/revela/index.ts";
 /revela enable
 ```
 
+在新项目里可以先初始化工作区 deck 状态：
+
+```text
+/revela init
+```
+
 如有需要，先切换 design 或 domain：
 
 ```text
@@ -99,6 +107,12 @@ export { default } from "/absolute/path/to/revela/index.ts";
 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.
 ```
 
+在 agent 写入 `decks/humanoid-robotics.html` 之前，它必须通过 `revela-decks` 工具更新 `DECKS.json`：记录 active deck、已确认的逐页规格、layout、component，并由工具计算出 `writeReadiness.status: ready`。你也可以随时显式触发 readiness 检查：
+
+```text
+/revela review humanoid-robotics
+```
+
 需要导出时：
 
 ```text
@@ -121,6 +135,10 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 /revela enable                   为当前会话启用演示文稿模式
 /revela disable                  关闭演示文稿模式
 
+/revela init                     初始化或刷新工作区 DECKS.json
+/revela review [slug]            写 HTML 前检查 active deck readiness
+/revela remember <text>          保存明确的用户/工作流偏好
+
 /revela designs                  列出已安装 design
 /revela designs <name>           激活某个 design
 /revela designs-new <name>       通过 AI 创建一个自定义 design
@@ -138,7 +156,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 designs-new` 和 `/revela designs-edit` 会启动 AI 辅助的 design 创建/编辑流程。
+大多数 `/revela` 命令都在本地执行，不消耗 LLM token。`/revela init`、`/revela review`、`/revela remember`、`/revela designs-new` 和 `/revela designs-edit` 会启动 AI 辅助流程，因为它们需要读取或更新项目状态。
 
 ---
 
@@ -157,6 +175,68 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 
 ---
 
+## DECKS.json 记忆与写入门禁
+
+Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生产控制。它主要给工具和 LLM 使用，不建议人工直接编辑。
+
+它有两个职责：
+
+- 工作区记忆：稳定项目背景、源材料、明确用户偏好、历史 deck 和开放问题
+- active deck 规格：当前 deck slug、输出路径、前置条件、research plan、逐页内容、layout、component、证据、视觉需求、blocker 和 write readiness
+
+`DECKS.md` 只作为旧版 fallback context；`DECKS.json` 才是 source of truth。
+
+创建或刷新：
+
+```text
+/revela init
+```
+
+检查当前 deck 状态：
+
+```text
+/revela review [slug]
+```
+
+`/revela review` 不会写最终 HTML deck。它通过 `revela-decks` 工具读取并更新 `DECKS.json`，检查缺失项，并且只有在 deck 真的可以生成时才把 `writeReadiness.status` 设为 `ready`。
+
+最小 readiness 条件：
+
+- topic、audience、slide count、language、visual style/design 已确定
+- source materials 已识别，或明确不需要源材料
+- research need 已评估
+- 需要调研时，相关 findings 已读取并反映到逐页规格中
+- 用户已确认 slide plan
+- 需要的 design layouts 和 components 已获取
+- 每页都有 title、layout、components 和结构化 content
+- 没有 unresolved blockers
+
+插件会在写 deck HTML 前强制检查这些条件。任何触碰 `decks/*.html` 的 `write` 或 `apply_patch`，只有在 `DECKS.json` 里匹配的 deck 通过 readiness gate 后才允许执行。直接写入或 patch `DECKS.json` 会被阻止；必须使用 `revela-decks` 工具更新状态。
+
+门禁会检查：
+
+- `writeReadiness.status` 是 `ready`
+- `writeReadiness.blockers` 为空
+- deck `outputPath` 精确匹配目标 `decks/*.html` 路径
+- 所有 `requiredInputs` 布尔值都是 true
+- 如果设置了 `slideCount`，`slides.length` 必须匹配
+- 每页都有 title、layout、components 和结构化 content
+- 每个 needed research axis 都是 `done`、`read` 或 `skipped`
+
+如果门禁阻止写入，Revela 会在 `.opencode/revela/blocked-writes/` 下写一个 marker 文件，而不是创建或覆盖真实 HTML deck。这样 agent 能看到失败原因，同时真实 deck 文件不会被污染。
+
+对 `apply_patch`，Revela 只检查 patch 是否触碰 `decks/*.html`。如果未 ready，整个 patch 会被替换成 blocked marker patch。`edit` 工具不做门禁。
+
+记住长期偏好请使用：
+
+```text
+/revela remember 我偏好中文、咨询风格、每页只表达一个核心观点。
+```
+
+不要用 `remember` 保存临时 checklist 状态；临时状态应该保存在 `DECKS.json` 的 active deck spec 中。
+
+---
+
 ## 调研与文件摄取
 
 启用 Revela 后，agent 可以使用：
@@ -164,6 +244,9 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 - `revela-workspace-scan` 扫描工作区中的 PDF、Office 文件、CSV、Markdown 和文本文件
 - `revela-research` 子代理做定向网页调研
 - `revela-research-save` 把结构化 findings 写入 `researches/<topic>/`
+- `revela-research-images-list` 从 `researches/<topic>/*.md` 中提取结构化图片候选
+- `revela-media-batch-save` 批量保存选中的调研图片素材到工作区 assets
+- `revela-media-save` 把选中的本地或远程图片保存为 `assets/<topic>/media/` 下的可复用素材
 
 支持提取文本的入口：
 

package/lib/agents/research-prompt.ts

@@ -25,19 +25,43 @@ Write your findings to a single file and return a brief summary.
 
 Given a research brief specifying your topic and axis, you will:
 
-1. Scan the workspace for existing documents (always first)
-2. Search the web for current data, reports, and case studies
-3. Write all findings to ONE structured file: \`researches/{topic-slug}/{axis-name}.md\`
-4. Return a brief summary of what you found
+1. Understand the axis-specific research brief and its evidence needs
+2. Use \`DECKS.json\` through \`revela-decks\` as the workspace material index when it exists
+3. Run a lightweight workspace freshness check when needed
+4. Search the web for current data, reports, and case studies when the brief requires it
+5. Write all findings to ONE structured file: \`researches/{topic-slug}/{axis-name}.md\`
+6. Return a brief summary of what you found
 
 ---
 
-## Step 1 — Workspace documents (always first)
+## Step 1 — Research brief and workspace memory
 
-Use the **\`revela-workspace-scan\`** tool in a single call to discover all document
-files in the workspace (PDF, Word, Excel, PowerPoint, CSV, text).
+Start from the research brief supplied by the primary agent. It should include:
+- shared topic slug
+- your axis filename
+- the specific question for this axis
+- time period, geography, and evidence standard
+- known workspace sources from \`DECKS.json\` or user-provided files
+- whether web research is needed
 
-Then select the files relevant to your research axis.
+Use \`revela-decks\` action \`read\` first when \`DECKS.json\` exists or is referenced
+by the brief. Use \`workspace.sourceMaterials\`, \`workspace.deckMemory\`, and
+\`workspace.openQuestions\` as workspace context. Treat sourceMaterials as a
+candidate index, not as proof by itself.
+
+Do not write or patch \`DECKS.json\`. You only write research findings through
+\`revela-research-save\`; the primary agent decides which stable deck state to preserve.
+
+---
+
+## Step 2 — Workspace freshness check and selected documents
+
+Use **\`revela-workspace-scan\`** as a lightweight freshness check when needed:
+- discover files added after \`/revela init\`
+- verify source files listed in \`DECKS.json\`
+- find files that match your axis but were not listed in the brief
+
+Do not deep-read the whole workspace. Select only files relevant to your axis.
 
 For every selected file, call **\`revela-extract-document-materials\`** first.
 - \`pdf\`, \`pptx\`, \`docx\`, and \`xlsx\` will produce a manifest plus extracted text and any available embedded materials
@@ -51,7 +75,7 @@ For PDFs and Office formats, the Revela plugin extracts text transparently — j
 
 ---
 
-## Step 2 — Web search (targeted)
+## Step 3 — Web search (targeted)
 
 Formulate **3–6 targeted search queries** for your specific axis, covering:
 - Quantitative data (market size, growth rates, rankings, financials)
@@ -72,7 +96,7 @@ Search strategy:
 
 ---
 
-## Step 3 — Write findings file
+## Step 4 — Write findings file
 
 Use **\`revela-research-save\`** to write ONE file with all your findings.
 
@@ -133,8 +157,11 @@ Gaps:
 - **NEVER** generate slide content or HTML — that is the primary agent's job
 - **NEVER** ask the user for information you can find through search or workspace files
 - **NEVER** use the raw \`write\` tool — always use \`revela-research-save\`
+- **NEVER** write or patch \`DECKS.json\` — the primary agent decides what stable state to preserve
 - **NEVER** fabricate image URLs — only record URLs you actually found
+- **Always** use \`revela-decks\` action \`read\` first when \`DECKS.json\` exists or is referenced by the brief
 - **Always** call \`revela-extract-document-materials\` for every selected workspace file before deciding which extracted materials to read next
+- **Avoid** repeated extraction or deep reading for files that are clearly irrelevant to this axis
 - **Always** include source attribution on every data point
 - **Always** use tables for comparative data (more useful than bullets for presentations)
 - **Preserve** raw data — the primary agent will select what to include in slides

package/lib/commands/help.ts

@@ -26,6 +26,9 @@ export async function handleHelp(
     `**Commands**\n\n` +
     `\`/revela enable\`              — enable slide generation mode\n` +
     `\`/revela disable\`             — disable slide generation mode\n` +
+    `\`/revela init\`                — initialize workspace deck memory in DECKS.md\n` +
+    `\`/revela review [slug]\`       — review active deck readiness before writing HTML\n` +
+    `\`/revela remember <text>\`     — save an explicit user preference to DECKS.md\n` +
     `\`/revela designs\`             — list installed designs\n` +
     `\`/revela designs <name>\`      — activate a design\n` +
     `\`/revela designs-new <name>\`  — create a new custom design with AI\n` +

package/lib/commands/init.ts

@@ -0,0 +1,68 @@
+import { DECKS_MEMORY_FILE } from "../decks-memory"
+import { DECKS_STATE_FILE } from "../decks-state"
+
+export function buildInitPrompt({
+  exists,
+  legacyExists,
+  workspaceRoot,
+}: {
+  exists: boolean
+  legacyExists?: boolean
+  workspaceRoot?: string
+}): 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.`
+  const legacy = legacyExists
+    ? `A legacy ${DECKS_MEMORY_FILE} file may exist. You may read it as migration context, but do not write or patch it unless explicitly asked.`
+    : `No legacy ${DECKS_MEMORY_FILE} context is known.`
+
+  return `Initialize Revela workspace state and deck workboard.
+
+Goal:
+- Build or update ${DECKS_STATE_FILE}, the workspace-level machine-readable state file for slide deck work.
+- Use the \`revela-decks\` tool for state updates. Do not write or patch ${DECKS_STATE_FILE} directly.
+- Capture stable project context, available source materials, deck history, active deck specs, slide plans, and open questions for future sessions.
+- Do not treat initialization as permission to write a slide deck; each deck must pass a later readiness review.
+- ${DECKS_MEMORY_FILE} is legacy fallback context only; ${DECKS_STATE_FILE} is the source of truth.
+
+Current state:
+- ${mode}
+- ${legacy}
+${workspaceRoot ? `- Current workspace root: \`${workspaceRoot}\`` : ""}
+
+Workspace boundary rules:
+- Stay strictly inside the current workspace root for every scan, glob, read, and write.
+- Do not search parent directories, home directories, or unrelated absolute directories.
+- For \`revela-workspace-scan\`, omit \`path\` for the initial scan or use a workspace-relative path only.
+- For Glob/file searches, use the current workspace as the search root. Do not set the search root to a parent directory or home directory.
+- Do not use \`~\`, \`..\`, or parent-directory traversal to discover files.
+- If the current workspace appears too broad, stop and ask the user which workspace subdirectory to initialize instead of scanning outside or deeply across everything.
+
+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:
+   - \`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. Record stable history, themes, filenames, and obvious reuse opportunities without treating them as authoritative source data.
+3. 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.
+4. For selected PDF/PPTX/DOCX/XLSX files, call \`revela-extract-document-materials\` before deciding what to summarize.
+5. Read only the materials needed to form a conservative workspace memory. Do not exhaustively read every file if the workspace is large.
+6. Call \`revela-decks\` with action \`init\` to create ${DECKS_STATE_FILE} if needed.
+7. If this conversation already contains a concrete deck task, call \`revela-decks\` with action \`upsertDeck\` and later \`upsertSlides\` only for explicit deck spec information. Do not mark readiness ready during init.
+8. Report what was initialized or updated and list any open questions.
+
+Memory rules:
+- Only write facts supported by workspace files into ${DECKS_STATE_FILE} workspace state, source materials, 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.
+- If legacy ${DECKS_MEMORY_FILE} exists, preserve any useful explicit preferences by migrating them through the revela-decks tool; do not copy temporary checklist state blindly.
+- Do not mark writeReadiness as ready during init unless the current deck has already passed an explicit \`revela-decks\` review.
+- If new evidence conflicts with existing memory, preserve both briefly and add an Open Question instead of silently overwriting.
+
+Start now by scanning the workspace.`
+}

package/lib/commands/remember.ts

@@ -0,0 +1,46 @@
+import { DECKS_MEMORY_FILE } from "../decks-memory"
+import { DECKS_STATE_FILE } from "../decks-state"
+
+export type RememberParseResult =
+  | { ok: true; memory: string }
+  | { ok: false; error: string }
+
+const USAGE =
+  "**Usage:** `/revela remember <preference or workflow habit>`\n" +
+  "Example: `/revela remember 我偏好中文、咨询风格、每页只表达一个核心观点`"
+
+export function parseRememberArgs(input: string): RememberParseResult {
+  const memory = input.trim()
+  if (!memory) return { ok: false, error: USAGE }
+  return { ok: true, memory }
+}
+
+export function buildRememberPrompt({ memory, exists, legacyExists }: { memory: string; exists: boolean; legacyExists?: boolean }): string {
+  const state = exists
+    ? `Read the existing ${DECKS_STATE_FILE} through revela-decks before updating preferences.`
+    : `Create ${DECKS_STATE_FILE} through revela-decks action init before recording this memory.`
+  const legacy = legacyExists
+    ? `Legacy ${DECKS_MEMORY_FILE} may exist as context, but do not write or patch it.`
+    : `No legacy ${DECKS_MEMORY_FILE} context is known.`
+
+  return `Record explicit Revela workspace memory.
+
+The user explicitly asked Revela to remember this:
+
+\`\`\`text
+${memory}
+\`\`\`
+
+Task:
+- ${state}
+- ${legacy}
+- Use the \`revela-decks\` tool with action \`remember\` to update ${DECKS_STATE_FILE}; do not write or patch the file directly.
+- Use preferenceType \`user\` if it describes output style, visual taste, language, audience, narrative, or content constraints.
+- Use preferenceType \`workflow\` if it describes how the user wants Revela to work.
+- Keep the entry concise and faithful to the user's wording.
+- Do not add inferred preferences or unrelated context.
+- Do not duplicate an existing equivalent preference; merge or refine it instead.
+- Do not store secrets, credentials, API keys, tokens, account details, or sensitive personal information.
+
+After updating ${DECKS_STATE_FILE}, briefly report which preference type you changed.`
+}

package/lib/commands/review.ts

@@ -0,0 +1,68 @@
+import { DECKS_MEMORY_FILE } from "../decks-memory"
+import { DECKS_STATE_FILE } from "../decks-state"
+
+export function buildReviewPrompt({
+  slug,
+  exists,
+  legacyExists,
+  workspaceRoot,
+}: {
+  slug?: string
+  exists: boolean
+  legacyExists?: boolean
+  workspaceRoot?: string
+}): string {
+  const target = slug?.trim()
+  const deckTarget = target ? `the deck slug or output path matching \`${target}\`` : "the current active deck"
+  const state = exists
+    ? `${DECKS_STATE_FILE} exists. Read it through the revela-decks tool.`
+    : `${DECKS_STATE_FILE} does not exist yet. Create it through the revela-decks tool if there is enough deck context.`
+  const legacy = legacyExists
+    ? `Legacy ${DECKS_MEMORY_FILE} may exist as migration context, but ${DECKS_STATE_FILE} is the source of truth.`
+    : `No legacy ${DECKS_MEMORY_FILE} context is known.`
+
+  return `Review Revela deck write readiness.
+
+Goal:
+- Use ${DECKS_STATE_FILE} as the source of truth for whether ${deckTarget} is ready to be written to \`decks/*.html\`.
+- Preserve the deck spec for future sessions: every slide's content, layout, components, evidence, visuals, and production status.
+- Do not write, patch, or directly edit ${DECKS_STATE_FILE}. Use the \`revela-decks\` tool for all state changes.
+- Let \`revela-decks\` action \`review\` compute writeReadiness; do not manually set readiness to ready.
+
+Current state:
+- ${state}
+- ${legacy}
+${workspaceRoot ? `- Current workspace root: \`${workspaceRoot}\`` : ""}
+
+Workspace boundary rules:
+- Stay strictly inside the current workspace root for every scan, glob, read, and write.
+- Do not search parent directories, home directories, or unrelated absolute directories.
+- Do not use \`~\`, \`..\`, or parent-directory traversal to discover files.
+- For Glob/file searches, use the current workspace as the search root. Do not set the search root to a parent directory or home directory.
+
+Workflow:
+1. Call \`revela-decks\` with action \`read\` for ${deckTarget}.
+2. If no matching deck exists but the conversation contains enough deck context, call \`revela-decks\` action \`upsertDeck\` with slug, goal, outputPath, theme, requiredInputs, and researchPlan.
+3. If a user-confirmed slide plan is available, call \`revela-decks\` action \`upsertSlides\` with every slide's title, purpose, layout, components, structured content, evidence, visuals, and status.
+4. Only set requiredInputs fields true when explicit conversation state, files read, research findings read, selected design, fetched layouts/components, or user confirmation supports them. Do not infer completion.
+5. Call \`revela-decks\` action \`review\` for the slug. The tool computes and writes \`writeReadiness\`.
+6. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool.
+
+Minimum conditions for \`ready\`:
+- Topic, audience, slide count, language, and visual style/design are decided.
+- Source materials have been identified or explicitly deemed unnecessary.
+- Research need has been assessed.
+- If research is needed, all relevant findings have been read and reflected in the slide specs.
+- The user has confirmed the slide plan.
+- ${DECKS_STATE_FILE} contains per-slide specs with content, layout, components, and evidence where applicable.
+- The needed design layouts and components have been fetched with \`revela-designs read\`.
+- No unresolved blockers remain.
+
+Rules:
+- Do not write or overwrite \`decks/*.html\` during review.
+- Do not write, patch, or directly edit ${DECKS_STATE_FILE}; use \`revela-decks\`.
+- Do not store secrets, credentials, tokens, or sensitive personal information.
+- Do not add inferred user preferences to long-term preference state.
+
+Start now by reading ${DECKS_STATE_FILE} through \`revela-decks\`.`
+}