@cyber-dash-tech/revela 0.7.9 → 0.8.2

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-171%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-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)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="800" />
@@ -112,7 +112,7 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 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
+/revela review
 ```
 
 Export when needed, either manually or by asking the agent to export:
@@ -138,9 +138,9 @@ Disable presentation mode when done:
 /revela disable                  disable presentation mode
 
 /revela init                     initialize or refresh workspace DECKS.json
-/revela review [slug]            review active deck readiness before writing HTML
+/revela review                   review current deck readiness before writing HTML
 /revela remember <text>          save an explicit user/workflow preference
-/revela edit [target]            open visual editor for active deck or a specific target
+/revela edit                     open visual editor for the only deck in decks/
 
 /revela designs                  list installed designs
 /revela designs <name>           activate a design
@@ -185,7 +185,7 @@ Revela uses a workspace-root `DECKS.json` file for cross-session continuity and
 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
+- active deck spec: current deck output path, prerequisites, research plan, per-slide content, layouts, components, evidence, visuals, blockers, and write readiness
 
 `DECKS.json` is the source of truth for workspace memory and deck readiness.
 
@@ -198,7 +198,7 @@ Create or refresh it with:
 Review the current deck state with:
 
 ```text
-/revela review [slug]
+/revela review
 ```
 
 `/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.
@@ -593,19 +593,17 @@ A custom domain is a folder containing `INDUSTRY.md`.
 
 ## Visual Editing
 
-Open the visual editor for the active deck, or pass a slug / workspace-relative HTML path:
+Open the visual editor for the only HTML deck in `decks/`:
 
 ```text
 /revela edit
-/revela edit my-deck
-/revela edit decks/my-deck.html
 ```
 
-Without a target, `/revela edit` opens `DECKS.json.activeDeck`. If no active deck is set and there is exactly one deck in `DECKS.json`, it opens that deck.
+`/revela edit` does not accept a target in Revela 0.8. If `decks/` contains exactly one `.html` file, Revela opens it. If `decks/` contains zero or multiple `.html` files, Revela asks you to generate a deck first or move extra decks to separate workspaces.
 
 The editor opens in your browser. Use `Ctrl`/`Cmd` + click to reference deck elements, write a natural-language comment, then send it back to OpenCode. Revela sends a structured edit prompt that includes the deck file, slide context, selected element metadata, and your comment.
 
-LLM tool equivalent: `revela-edit` with `{ "target": "decks/my-deck.html" }`. This lets the agent open the same editor when you say things like “I want to edit @decks/my-deck.html”.
+LLM tool equivalent: `revela-edit` with no target. This lets the agent open the same editor when you say things like “I want to edit the deck”.
 
 `/revela edit` prepares minimal `DECKS.json` state for the existing HTML deck if needed, so the normal deck write gate can still protect `decks/*.html` while allowing targeted edits.
 

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-171%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-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)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="800" />
@@ -111,7 +111,7 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 在 agent 写入 `decks/humanoid-robotics.html` 之前，它必须通过 `revela-decks` 工具更新 `DECKS.json`：记录 active deck、已确认的逐页规格、layout、component，并由工具计算出 `writeReadiness.status: ready`。你也可以随时显式触发 readiness 检查：
 
 ```text
-/revela review humanoid-robotics
+/revela review
 ```
 
 需要导出时，可以手动调用，也可以让 agent 直接导出：
@@ -137,9 +137,9 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 /revela disable                  关闭演示文稿模式
 
 /revela init                     初始化或刷新工作区 DECKS.json
-/revela review [slug]            写 HTML 前检查 active deck readiness
+/revela review                   写 HTML 前检查当前 deck readiness
 /revela remember <text>          保存明确的用户/工作流偏好
-/revela edit [target]            打开 active deck 或指定 target 的可视化编辑器
+/revela edit                     打开 decks/ 下唯一 deck 的可视化编辑器
 
 /revela designs                  列出已安装 design
 /revela designs <name>           激活某个 design
@@ -184,7 +184,7 @@ Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生
 它有两个职责：
 
 - 工作区记忆：稳定项目背景、源材料、明确用户偏好、历史 deck 和开放问题
-- active deck 规格：当前 deck slug、输出路径、前置条件、research plan、逐页内容、layout、component、证据、视觉需求、blocker 和 write readiness
+- active deck 规格：当前 deck 输出路径、前置条件、research plan、逐页内容、layout、component、证据、视觉需求、blocker 和 write readiness
 
 `DECKS.json` 是工作区记忆和 deck readiness 的 source of truth。
 
@@ -197,7 +197,7 @@ Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生
 检查当前 deck 状态：
 
 ```text
-/revela review [slug]
+/revela review
 ```
 
 `/revela review` 不会写最终 HTML deck。它通过 `revela-decks` 工具读取并更新 `DECKS.json`，检查缺失项，并且只有在 deck 真的可以生成时才把 `writeReadiness.status` 设为 `ready`。
@@ -558,19 +558,17 @@ Prompt 注入规则：
 
 ## 可视化编辑
 
-可以直接打开 active deck，也可以传入 deck slug 或工作区相对 HTML 路径：
+打开 `decks/` 下唯一 HTML deck 的可视化编辑器：
 
 ```text
 /revela edit
-/revela edit my-deck
-/revela edit decks/my-deck.html
 ```
 
-不传 target 时，`/revela edit` 会打开 `DECKS.json.activeDeck`。如果没有 active deck，但 `DECKS.json` 里只有一个 deck，则打开这个唯一 deck。
+Revela 0.8 中 `/revela edit` 不接受 target。如果 `decks/` 下正好有一个 `.html` 文件，Revela 会打开它。如果 `decks/` 下没有 HTML 或有多个 HTML，Revela 会提示先生成 deck，或把多余 deck 移到独立 workspace。
 
 编辑器会在浏览器中打开。使用 `Ctrl`/`Cmd` + 点击 deck 元素来引用它们，写一段自然语言评论，然后发送回 OpenCode。Revela 会把 deck 文件、slide 上下文、选中元素 metadata 和你的评论整理成结构化 edit prompt。
 
-对应的 LLM tool：`revela-edit`，参数为 `{ "target": "decks/my-deck.html" }`。因此当你说“我要编辑 @decks/my-deck.html”时，agent 也可以主动打开同一个编辑器。
+对应的 LLM tool：`revela-edit`，不需要 target。因此当你说“我要编辑这个 deck”时，agent 也可以主动打开同一个编辑器。
 
 如果已有 HTML deck 缺少 `DECKS.json` 状态，`/revela edit` 会自动准备最小 deck state，让正常的 `decks/*.html` 写入门禁仍然生效，同时允许后续精准修改。
 

package/lib/agents/research-prompt.ts

@@ -29,7 +29,7 @@ Given a research brief specifying your topic and axis, you will:
 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\`
+5. Write all findings to ONE structured file: \`researches/{topic-key}/{axis-name}.md\`
 6. Return a brief summary of what you found
 
 ---
@@ -37,7 +37,7 @@ Given a research brief specifying your topic and axis, you will:
 ## Step 1 — Research brief and workspace memory
 
 Start from the research brief supplied by the primary agent. It should include:
-- shared topic slug
+- shared topic key
 - your axis filename
 - the specific question for this axis
 - time period, geography, and evidence standard
@@ -100,7 +100,7 @@ Search strategy:
 
 Use **\`revela-research-save\`** to write ONE file with all your findings.
 
-- \`topic\`: kebab-case slug shared across all agents for this presentation
+- \`topic\`: kebab-case topic key shared across all agents for this presentation
 - \`filename\`: your axis name (e.g. \`market-data\`, \`catl-profile\`, \`tech-trends\`)
 - \`content\`: structured findings using the four sections below
 - \`sources\`: list of all URLs and filenames used
@@ -140,7 +140,7 @@ Content rules:
 After writing the file, return this summary (do NOT include the raw data):
 
 \`\`\`
-Research complete: {axis-name} → researches/{topic-slug}/{axis-name}.md
+Research complete: {axis-name} → researches/{topic-key}/{axis-name}.md
 
 Key findings (3–5, most argument-worthy only):
 - {1–2 sentence highlight with source}

package/lib/commands/edit.ts

@@ -1,22 +1,19 @@
 import { openEditableDeck } from "../edit/open"
 
 export async function handleEdit(
-  input: string,
   options: { client: any; sessionID: string; workspaceRoot: string },
   send: (text: string) => Promise<void>,
 ): Promise<void> {
-  const target = input.trim()
-
   try {
-    const result = openEditableDeck(target, {
+    const result = openEditableDeck("", {
       client: options.client,
       sessionID: options.sessionID,
       workspaceRoot: options.workspaceRoot,
     })
 
     await send(
-      `Opened visual editor for deck \`${result.deck.slug}\`.\n` +
-      `File: \`${result.deck.file}\` (${result.source})\n` +
+      `Opened visual editor for the only deck in \`decks/\`.\n` +
+      `File: \`${result.deck.file}\`\n` +
       `${result.stateNote}\n` +
       `URL: ${result.url}\n\n` +
       `Use Ctrl/Cmd + click in the browser to reference elements, write a comment, then send comments. Revela mode has been enabled for the edit prompt.`

package/lib/commands/help.ts

@@ -27,8 +27,8 @@ export async function handleHelp(
     `\`/revela enable\`              — enable slide generation mode\n` +
     `\`/revela disable\`             — disable slide generation mode\n` +
     `\`/revela init\`                — initialize or refresh workspace DECKS.json\n` +
-    `\`/revela review [slug]\`       — review active deck readiness before writing HTML\n` +
-    `\`/revela edit [target]\`       — open visual editor for active deck or a specific target\n` +
+    `\`/revela review\`              — review current deck readiness before writing HTML\n` +
+    `\`/revela edit\`                — open visual editor for the only deck in decks/\n` +
     `\`/revela remember <text>\`     — save an explicit preference to DECKS.json\n` +
     `\`/revela designs\`             — list installed designs\n` +
     `\`/revela designs <name>\`      — activate a design\n` +

package/lib/commands/init.ts

@@ -16,9 +16,9 @@ export function buildInitPrompt({
 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_STATE_FILE} is the source of truth for Revela workspace state.
+- Capture stable project context, available source materials, the current deck spec, slide plan, 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.
 
 Current state:
 - ${mode}
@@ -40,12 +40,12 @@ Workflow:
    - \`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.
+   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.
 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.
+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 pass or ask for a deck key; the tool uses the workspace folder name internally. Do not mark readiness ready during init.
 8. Report what was initialized or updated and list any open questions.
 
 Memory rules:
@@ -54,6 +54,7 @@ Memory rules:
 - 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.
+- 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.
 
 Start now by scanning the workspace.`

package/lib/commands/review.ts

@@ -1,16 +1,12 @@
 import { DECKS_STATE_FILE } from "../decks-state"
 
 export function buildReviewPrompt({
-  slug,
   exists,
   workspaceRoot,
 }: {
-  slug?: string
   exists: 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.`
@@ -18,7 +14,7 @@ export function buildReviewPrompt({
   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\`.
+- Use ${DECKS_STATE_FILE} as the source of truth for whether the current workspace deck 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.
@@ -34,11 +30,11 @@ Workspace boundary rules:
 - 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.
+1. Call \`revela-decks\` with action \`read\` for the current workspace deck.
+2. If no current deck exists but the conversation contains enough deck context, call \`revela-decks\` action \`upsertDeck\` with goal, outputPath, theme, requiredInputs, and researchPlan. Do not invent or ask for a deck key; the tool uses the workspace folder name internally.
 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\`.
+5. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` for the current workspace deck.
 6. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool.
 
 Minimum conditions for \`ready\`:
@@ -53,6 +49,7 @@ Minimum conditions for \`ready\`:
 
 Rules:
 - Do not write or overwrite \`decks/*.html\` during review.
+- Treat the workspace as one deck project. If the user wants another deck, tell them to use a separate workspace/folder.
 - 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.

package/lib/decks-state.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs"
-import { basename, dirname, join } from "path"
+import { basename, dirname, join, resolve } from "path"
 
 export const DECKS_STATE_FILE = "DECKS.json"
 
@@ -154,6 +154,29 @@ export function createEmptyDecksState(): DecksState {
   }
 }
 
+export function workspaceDeckSlug(workspaceRoot: string): string {
+  return normalizeSlug(basename(resolve(workspaceRoot)) || "deck") || "deck"
+}
+
+export function normalizeWorkspaceDeckState(state: DecksState, workspaceRoot: string): DecksState {
+  const normalized = normalizeDecksState(state)
+  const keys = Object.keys(normalized.decks)
+  if (keys.length !== 1) return normalized
+
+  const slug = workspaceDeckSlug(workspaceRoot)
+  const existingKey = keys[0]
+  if (existingKey === slug) {
+    normalized.activeDeck = slug
+    return normalized
+  }
+
+  const deck = createDeckSpec({ ...normalized.decks[existingKey], slug })
+  delete normalized.decks[existingKey]
+  normalized.decks[slug] = deck
+  normalized.activeDeck = slug
+  return normalized
+}
+
 export function defaultRequiredInputs(overrides?: Partial<RequiredInputs>): RequiredInputs {
   return {
     topicClarified: false,
@@ -210,6 +233,10 @@ export function readOrCreateDecksState(workspaceRoot: string): DecksState {
 export function upsertDeck(state: DecksState, input: Partial<DeckSpec> & { slug: string }): DecksState {
   const normalized = normalizeDecksState(state)
   const slug = normalizeSlug(input.slug)
+  const existingKey = currentDeckKey(normalized)
+  if (existingKey && slug !== existingKey && !normalized.decks[slug]) {
+    throw new Error(`${DECKS_STATE_FILE} already has a current deck (${existingKey}). Use a separate workspace for another deck.`)
+  }
   const existing = normalized.decks[slug]
   const next = createDeckSpec({ ...existing, ...input, slug })
   normalized.decks[slug] = next
@@ -220,6 +247,10 @@ export function upsertDeck(state: DecksState, input: Partial<DeckSpec> & { slug:
 export function upsertSlides(state: DecksState, slug: string, slides: SlideSpec[]): DecksState {
   const normalized = normalizeDecksState(state)
   const key = normalizeSlug(slug)
+  const existingKey = currentDeckKey(normalized)
+  if (existingKey && key !== existingKey && !normalized.decks[key]) {
+    throw new Error(`${DECKS_STATE_FILE} already has a current deck (${existingKey}). Use a separate workspace for another deck.`)
+  }
   const deck = normalized.decks[key] ?? createDeckSpec({ slug: key })
   const byIndex = new Map(deck.slides.map((slide) => [slide.index, slide]))
   for (const slide of normalizeSlides(slides)) byIndex.set(slide.index, slide)
@@ -231,7 +262,7 @@ export function upsertSlides(state: DecksState, slug: string, slides: SlideSpec[
 
 export function reviewDeckState(state: DecksState, slug?: string): { state: DecksState; result: DeckStateReadinessResult } {
   const normalized = normalizeDecksState(state)
-  const key = normalizeSlug(slug || normalized.activeDeck || "")
+  const key = normalizeSlug(slug || currentDeckKey(normalized) || "")
   const deck = key ? normalized.decks[key] : undefined
   if (!deck) {
     const missing = key || "active deck"
@@ -276,13 +307,14 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
   const targetPath = normalizeDeckPath(filePath)
   const targetSlug = deckSlugFromPath(targetPath)
   const normalized = normalizeDecksState(state)
-  const deck = findDeckForTarget(normalized, targetPath, targetSlug)
+  const key = currentDeckKey(normalized)
+  const deck = key ? normalized.decks[key] : undefined
   if (!deck) {
     return {
       ready: false,
       slug: targetSlug,
-      blocker: `No deck in ${DECKS_STATE_FILE} matches ${targetPath}. Use revela-decks upsertDeck/upsertSlides, then review before writing.`,
-      blockers: [`No deck in ${DECKS_STATE_FILE} matches ${targetPath}.`],
+      blocker: currentDeckBlocker(normalized),
+      blockers: [currentDeckBlocker(normalized)],
     }
   }
 
@@ -324,16 +356,17 @@ export function extractDecksStateTargetsFromPatch(patchText: string): string[] {
 export function buildDecksStatePromptLayer(workspaceRoot: string, maxChars = 14000): string {
   if (!hasDecksState(workspaceRoot)) return ""
   const state = readDecksState(workspaceRoot)
-  const active = state.activeDeck ? state.decks[state.activeDeck] : undefined
+  const activeKey = currentDeckKey(state)
+  const active = activeKey ? state.decks[activeKey] : undefined
   const compact = {
     sourceOfTruth: DECKS_STATE_FILE,
-    activeDeck: state.activeDeck,
+    activeDeck: activeKey,
     workspace: state.workspace,
     deck: active,
   }
   let text = JSON.stringify(compact, null, 2)
   if (text.length > maxChars) text = text.slice(0, maxChars).trimEnd() + "\n[DECKS.json state truncated for prompt size.]"
-  return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as the source of truth for deck specs, slide plans, and write readiness.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- Before writing decks/*.html, the matching deck must have writeReadiness.status=ready and a complete slide spec.`
+  return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as the source of truth for the single current deck's specs, slide plan, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- Before writing decks/*.html, the current deck must have writeReadiness.status=ready and a complete slide spec, and its outputPath must match the target file.`
 }
 
 function normalizeDecksState(input: DecksState): DecksState {
@@ -357,9 +390,26 @@ function normalizeDecksState(input: DecksState): DecksState {
     state.decks[normalizedSlug] = createDeckSpec({ ...deck, slug: normalizedSlug })
   }
   if (state.activeDeck && !state.decks[state.activeDeck]) state.activeDeck = undefined
+  if (!state.activeDeck) {
+    const keys = Object.keys(state.decks)
+    if (keys.length === 1) state.activeDeck = keys[0]
+  }
   return state
 }
 
+function currentDeckKey(state: DecksState): string | undefined {
+  if (state.activeDeck && state.decks[state.activeDeck]) return state.activeDeck
+  const keys = Object.keys(state.decks)
+  if (keys.length === 1) return keys[0]
+  return undefined
+}
+
+function currentDeckBlocker(state: DecksState): string {
+  const count = Object.keys(state.decks).length
+  if (count === 0) return `No current deck exists in ${DECKS_STATE_FILE}. Use revela-decks upsertDeck/upsertSlides/review before writing deck HTML.`
+  return `${DECKS_STATE_FILE} contains multiple deck records and no activeDeck. Select one current deck explicitly or move extra decks to separate workspaces.`
+}
+
 function computeDeckBlockers(deck: DeckSpec): string[] {
   const blockers: string[] = []
   if (!deck.goal.trim()) blockers.push("Deck goal is missing")
@@ -402,10 +452,6 @@ function normalizeSlides(slides: SlideSpec[]): SlideSpec[] {
     .sort((a, b) => a.index - b.index)
 }
 
-function findDeckForTarget(state: DecksState, targetPath: string, targetSlug: string): DeckSpec | undefined {
-  return Object.values(state.decks).find((deck) => normalizeDeckPath(deck.outputPath) === targetPath) ?? state.decks[normalizeSlug(targetSlug)]
-}
-
 function hasSlideContent(slide: SlideSpec): boolean {
   const content = slide.content ?? {}
   return Boolean(

package/lib/edit/deck-state.ts

@@ -3,25 +3,27 @@ import { activeDesign } from "../design/designs"
 import { activeDomain } from "../domain/domains"
 import {
   defaultRequiredInputs,
+  DECKS_STATE_FILE,
+  normalizeWorkspaceDeckState,
   readOrCreateDecksState,
-  reviewDeckState,
   upsertDeck,
   upsertSlides,
   writeDecksState,
-  type DeckStateReadinessResult,
   type SlideSpec,
 } from "../decks-state"
 import type { EditableDeck } from "./resolve-deck"
 
 export interface EditDeckStatePreflightResult {
   changed: boolean
-  readiness: DeckStateReadinessResult
 }
 
 export function ensureEditableDeckState(workspaceRoot: string, deck: EditableDeck): EditDeckStatePreflightResult {
-  let state = readOrCreateDecksState(workspaceRoot)
+  let state = normalizeWorkspaceDeckState(readOrCreateDecksState(workspaceRoot), workspaceRoot)
+  const active = state.activeDeck ? state.decks[state.activeDeck] : undefined
+  if (active && active.slug !== deck.slug && active.outputPath !== deck.file) {
+    throw new Error(`${DECKS_STATE_FILE} already points to ${active.outputPath}. Revela 0.8 expects one deck per workspace; move extra decks to a separate workspace.`)
+  }
   const existing = state.decks[deck.slug]
-  const existingReady = existing?.writeReadiness?.status === "ready" && existing.writeReadiness.blockers.length === 0
   let changed = !existing || existing.outputPath !== deck.file
 
   state = upsertDeck(state, {
@@ -58,12 +60,10 @@ export function ensureEditableDeckState(workspaceRoot: string, deck: EditableDec
     changed = true
   }
 
-  const reviewed = reviewDeckState(state, deck.slug)
-  writeDecksState(workspaceRoot, reviewed.state)
+  writeDecksState(workspaceRoot, state)
 
   return {
-    changed: changed || !existingReady,
-    readiness: reviewed.result,
+    changed,
   }
 }
 
@@ -112,7 +112,7 @@ function safeActiveDesign(): string {
   try {
     return activeDesign()
   } catch {
-    return "summit"
+    return "aurora"
   }
 }
 

package/lib/edit/open.ts

@@ -14,6 +14,9 @@ export interface OpenEditableDeckResult {
   source: string
   stateNote: string
   preflightChanged: boolean
+  reusedSession: boolean
+  liveSession: boolean
+  openedBrowser: boolean
 }
 
 export interface OpenEditableDeckOptions {
@@ -21,6 +24,11 @@ export interface OpenEditableDeckOptions {
   sessionID: string
   workspaceRoot: string
   openBrowser?: boolean
+  openUrl?: (url: string) => void
+}
+
+export interface EnsureEditableDeckOpenResult extends OpenEditableDeckResult {
+  skippedReason?: "live-session"
 }
 
 export function openUrl(url: string): void {
@@ -41,11 +49,23 @@ export function openUrl(url: string): void {
 }
 
 export function openEditableDeck(target: string, options: OpenEditableDeckOptions): OpenEditableDeckResult {
+  return openEditableDeckInternal(target, options, { skipLiveSession: false })
+}
+
+export function ensureEditableDeckOpenForChange(
+  target: string,
+  options: OpenEditableDeckOptions,
+): EnsureEditableDeckOpenResult {
+  return openEditableDeckInternal(target, options, { skipLiveSession: true })
+}
+
+function openEditableDeckInternal(
+  target: string,
+  options: OpenEditableDeckOptions,
+  behavior: { skipLiveSession: boolean },
+): EnsureEditableDeckOpenResult {
   const deck = resolveEditableDeck(options.workspaceRoot, target)
   const preflight = ensureEditableDeckState(options.workspaceRoot, deck)
-  if (!preflight.readiness.ready) {
-    throw new Error(preflight.readiness.blocker || "Deck is not ready for HTML edits.")
-  }
 
   ctx.enabled = true
   if (!existsSync(ACTIVE_PROMPT_FILE)) {
@@ -55,16 +75,17 @@ export function openEditableDeck(target: string, options: OpenEditableDeckOption
   }
 
   const editServer = startEditServer()
-  const token = editServer.createSession({
+  const session = editServer.getOrCreateSession({
     client: options.client,
     sessionID: options.sessionID,
     deck,
   })
-  const url = `${editServer.baseUrl}/edit?token=${encodeURIComponent(token)}`
-  if (options.openBrowser !== false) openUrl(url)
+  const url = `${editServer.baseUrl}/edit?token=${encodeURIComponent(session.token)}`
+  const shouldOpen = options.openBrowser !== false && !(behavior.skipLiveSession && session.live)
+  if (shouldOpen) (options.openUrl ?? openUrl)(url)
 
   const source = deck.source === "decks-state" ? "DECKS.json" : deck.source === "file-path" ? "file path" : "fallback path"
-  const stateNote = preflight.changed ? "Deck state was prepared in DECKS.json before opening the editor." : "Deck state is ready in DECKS.json."
+  const stateNote = preflight.changed ? "Deck state was prepared in DECKS.json for visual editing." : "Deck state already points to this visual edit target."
 
   return {
     deck,
@@ -72,5 +93,9 @@ export function openEditableDeck(target: string, options: OpenEditableDeckOption
     source,
     stateNote,
     preflightChanged: preflight.changed,
+    reusedSession: session.reused,
+    liveSession: session.live,
+    openedBrowser: shouldOpen,
+    skippedReason: behavior.skipLiveSession && session.live ? "live-session" : undefined,
   }
 }