@cyber-dash-tech/revela 0.15.2 → 0.15.3

package/lib/commands/inspect.ts

@@ -1,25 +1,7 @@
-import { openRefineDeck } from "../refine/open"
-
 export async function handleInspect(
   options: { client: any; sessionID: string; workspaceRoot: string; openBrowser?: boolean },
   send: (text: string) => Promise<void>,
 ): Promise<void> {
-  try {
-    const result = openRefineDeck("", {
-      client: options.client,
-      sessionID: options.sessionID,
-      workspaceRoot: options.workspaceRoot,
-      mode: "inspect",
-      openBrowser: options.openBrowser,
-    })
-    await send(
-      `\`/revela inspect\` is deprecated. Opened \`/revela refine\` in Inspect mode for the active HTML deck.\n` +
-      `File: \`${result.deck.file}\`\n` +
-      `${result.stateNote}\n` +
-      `URL: ${result.url}\n\n` +
-      `Use \`/revela refine\` directly going forward. Use Ctrl/Cmd-click in the browser to reference deck elements, then use the Inspect tab for read-only Source/Purpose review. There is no chat box or freeform prompt.`
-    )
-  } catch (e: any) {
-    await send(`**Inspect failed:** ${e.message || String(e)}`)
-  }
+  void options
+  await send("`/revela inspect` is no longer a public command. Use `/revela refine --deck` and the Inspect tab for grounded Source/Purpose/Narrative Reading.")
 }

package/lib/commands/narrative.ts

@@ -34,7 +34,7 @@ export function parseStoryArgs(param: string): ParseStoryArgsResult {
     if (token.startsWith("--language=")) {
       return { ok: false, error: "Usage: `/revela story --language <language>` or `/revela story -l <language>`. Do not use `--language=<language>`." }
     }
-    return { ok: false, error: "Usage: `/revela story [--language <language> | -l <language>]`. Use `/revela review` for a readiness report." }
+    return { ok: false, error: "Usage: `/revela story [--language <language> | -l <language>]`." }
   }
 
   return { ok: true, args: { language } }
@@ -130,9 +130,9 @@ export function buildNarrativeViewPrompt(options: { workspaceRoot: string; langu
   return `Prepare the read-only Revela narrative UI display model.
 
 Target language request: ${options.language}
-- The language value is passed from the user's /revela narrative arguments. Interpret it as the desired UI/display language.
+- The language value is passed from the user's /revela story arguments. Interpret it as the desired UI/display language.
 - Examples: --cn maps to zh-CN, --jp maps to ja-JP, while --fr, --de, --es, --ko, --Arabic, --Portuguese-BR, or a written language name should be localized normally into that requested language.
-- Default /revela narrative language is en when the user provides no language request.
+- Default /revela story language is en when the user provides no language request.
 
 You must call the \`revela-narrative-view\` tool exactly once.
 

package/lib/commands/pdf.ts

@@ -1,7 +1,7 @@
 /**
  * lib/commands/pdf.ts
  *
- * Handler for `/revela pdf <file_path>` — exports an HTML slide deck to PDF.
+ * Handler for `/revela export --deck pdf <file_path>` — exports an HTML slide deck to PDF.
  *
  * Output: same directory and base name as the input, with .pdf extension.
  * Example: decks/my-deck.html → decks/my-deck.pdf
@@ -24,8 +24,8 @@ export async function handlePdf(
 
   if (!resolvedFile) {
     await send(
-      "**Usage:** `/revela pdf [file_path]`\n\n" +
-      "Example: `/revela pdf decks/my-deck.html`"
+      "**Usage:** `/revela export --deck pdf [file_path]`\n\n" +
+      "Example: `/revela export --deck pdf decks/my-deck.html`"
     )
     return
   }

package/lib/commands/pptx.ts

@@ -1,7 +1,7 @@
 /**
  * lib/commands/pptx.ts
  *
- * Handler for `/revela pptx [file_path]` — exports an HTML slide deck to PPTX.
+ * Handler for `/revela export --deck pptx [file_path]` — exports an HTML slide deck to PPTX.
  *
  * Output: same directory and base name as the input, with .pptx extension.
  * Example: decks/my-deck.html → decks/my-deck.pptx
@@ -64,7 +64,7 @@ export function resolvePptxDeck(workspaceRoot: string, filePath = ""): ResolvedP
     throw new Error("No deck HTML found in decks/. Generate a deck first or pass a file path.")
   }
   if (htmlFiles.length > 1) {
-    throw new Error("This workspace contains multiple deck HTML files. Run `/revela pptx decks/<file>.html` to choose one.")
+    throw new Error("This workspace contains multiple deck HTML files. Run `/revela export --deck pptx decks/<file>.html` to choose one.")
   }
 
   const absoluteFile = resolve(root, htmlFiles[0])

package/lib/commands/review.ts

@@ -18,7 +18,7 @@ Goal:
 - Treat this as a narrative readiness review, not a deck HTML write-readiness review.
 - Do not write, patch, or directly edit ${DECKS_STATE_FILE}. Use the \`revela-decks\` tool for all state changes.
 - Call \`revela-decks\` action \`reviewNarrative\` as the authoritative deterministic readiness engine.
-- Do not call \`revela-decks\` action \`review\` here. That action is the deck/artifact gate and belongs to \`/revela make deck --review\`.
+- Do not call \`revela-decks\` action \`review\` here. That action is the deck/artifact gate inside \`/revela make --deck\` after the deck plan is confirmed.
 - Do not treat legacy \`writeReadiness.status\`, old review snapshots, or an existing HTML deck as narrative approval.
 - Do not write or overwrite \`decks/*.html\` during narrative review.
 - If the narrative is \`ready_for_approval\`, ask whether the user wants to approve it or revise it. Do not approve automatically.
@@ -50,7 +50,7 @@ Report format:
 - If warnings exist, list them after blockers as residual risks.
 - If approval is missing, ask whether the user wants to approve the narrative or revise it.
 - If approval is stale, say the prior approval no longer matches the current narrative hash.
-- Keep deck/artifact readiness separate. If the user wants to review slide-writing readiness, tell them to run \`/revela make deck --review\`.
+- Keep deck/artifact readiness separate. If the user wants to write or review deck artifacts, tell them to run \`/revela make --deck\`.
 
 Rules:
 - Do not write or overwrite \`decks/*.html\` during narrative review.
@@ -79,6 +79,7 @@ Goal:
 - Treat this as the explicit transition from approved narrative state to user-confirmed deck planning.
 - Use the deck-render prompt mode for design, layout, component, HTML, QA, and deck artifact rules.
 - Default behavior is two-stage: first show the compiled deck plan with low-fidelity layout sketches, then stop for user confirmation before any artifact review or HTML writing.
+- Every deck plan must include Cover, Table of Contents, and Closing slides. The TOC must show 3-5 chapter headings that match the deck's slide groups.
 - Do not write or overwrite \`decks/*.html\` until the narrative handoff, explicit user deck-plan confirmation, and deck/artifact gate are all satisfied.
 - Do not treat legacy \`writeReadiness.status\`, old review snapshots, or existing HTML decks as narrative approval.
 - Do not bypass the deck HTML contract, review snapshot freshness, source-trace expectations, or export preflight protections.
@@ -93,19 +94,22 @@ Workflow:
 3. If narrative readiness is \`approved\`, continue. If it is \`ready_for_approval\`, ask the user for explicit approval before continuing. If it is blocked, stale, or needs research, stop and report the smallest next action. Do not call \`approveNarrative\` unless the user explicitly approves or requests a render override.
 4. After approval or explicit render override exists, call \`revela-decks\` action \`compileDeckPlan\`. This projects canonical narrative claims and evidence bindings into compatibility \`slides[]\` and \`slides[].evidence[]\`; it must not write HTML.
 5. If \`compileDeckPlan\` returns \`skipped\`, stop and report the reason. Do not invent slide specs manually to bypass approval.
-6. Present the compiled deck plan to the user and include a low-fidelity layout sketch for every slide. The sketch is ASCII/text structure only; do not generate visual images or HTML mockups.
+6. Present the compiled deck plan to the user and include a low-fidelity layout sketch for every slide. The plan must identify the chapter structure first: 3-5 chapter headings, each chapter's slide range, and which non-structural slides belong to each chapter. The sketch is ASCII/text structure only; do not generate visual images or HTML mockups.
 7. Stop after presenting the plan. Ask the user to confirm or request changes. Do not call \`revela-decks review\`, do not fetch design context, and do not write HTML in the same turn unless the user had already explicitly confirmed the current plan before this command.
 8. Only after explicit user confirmation of the current slide plan, call \`revela-decks\` action \`confirmDeckPlan\` with \`approvalBy=user\` and a compact \`approvalNote\`.
 9. After confirmation is recorded, ask for or confirm visual design only after the narrative deck plan exists. Fetch required design layouts/components with \`revela-designs read\` as needed.
 10. Update only deck/artifact metadata through \`revela-decks upsertDeck\` / \`upsertSlides\` when required by confirmed design/layout choices. Do not change canonical narrative claims unless the user asks to revise the narrative.
 11. Call \`revela-decks\` action \`review\` as the artifact gate. It computes \`writeReadiness\` and review snapshots for deck HTML writing. If it reports \`slide_plan_unconfirmed\`, stop and ask for explicit deck-plan confirmation.
-12. Write \`decks/*.html\` only if the deck/artifact gate is ready and all deck HTML contract requirements can be satisfied. After each HTML write, the system automatically runs artifact QA before opening Refine.
-13. If post-write artifact QA reports hard errors, fix them and let QA run again. Refine opens only after hard errors pass. Density warnings about thin claim/evidence substance should be reported and improved when useful, but they do not block Refine.
+12. Write \`decks/*.html\` only if the deck/artifact gate is ready and all deck HTML contract requirements can be satisfied. Generate the artifact chapter by chapter instead of drafting all content slides in one broad pass. Keep the HTML file valid after every write, preserve already-written slides, and update one chapter's slide sections at a time.
+13. For each chapter, make every content slide carry a distinct claim, evidence item, comparison, risk, or action. If a chapter lacks enough substance for its allocated slides, merge weak slides or reduce the slide count instead of creating sparse filler.
+14. After each HTML write, the system automatically runs artifact QA before opening Refine. If post-write artifact QA reports hard errors, fix them and let QA run again. Refine opens only after hard errors pass. Density warnings about thin claim/evidence substance should be reported and improved when useful, but they do not block Refine.
 
 Deck plan report format:
 - Start with \`Deck plan: awaiting confirmation\` when a plan was compiled and has not yet been confirmed.
 - Include narrative readiness status and narrative hash when available.
 - Include whether \`compileDeckPlan\` compiled or skipped.
+- Include \`Required structure: Cover + Table of Contents + Closing\` and do not omit any of those slides.
+- Include a \`Chapters\` section before the slide list. It must list 3-5 TOC headings, their slide ranges, and the non-structural slides assigned to each chapter.
 - For every slide, include: slide index, title, purpose, narrative role, low-fidelity layout sketch, layout, components, primary/supporting claim ids, evidence binding ids or source summary, visual intent, and caveats/unsupported scope.
 - Use this sketch style or similarly simple ASCII boxes:
 
@@ -135,12 +139,15 @@ Caveats / unsupported scope:
 Report format before any HTML write after confirmation:
 - Start with \`Deck handoff: <status>\`.
 - Include which user-confirmed plan, approved narrative hash, and deck review snapshot authorized the artifact work.
+- Include the chapter currently being generated and confirm already-written slides are being preserved.
 - If deck/artifact review is blocked, list blockers separately from narrative blockers.
 - After writing HTML, read the appended \`Artifact QA\` report from the tool output. If it failed, fix hard errors before considering the deck ready for Refine.
 
 Rules:
 - \`compileDeckPlan\` is the canonical narrative-to-deck planning path. Do not manually invent slide specs to avoid it.
 - Deck slide specs are render-target projections. Canonical narrative remains the authority for audience, decision, claims, evidence boundaries, objections, risks, and approval.
+- Cover, Table of Contents, and Closing are mandatory deck structure. TOC chapter headings must match the chapter grouping used for generation.
+- Do not generate the complete deck content in one broad pass after confirmation. Work chapter by chapter while keeping the artifact valid after each write.
 - Applying evidence candidates, rewriting canonical claims, or approving narratives requires explicit user instruction.
 - If the user requests slide order, layout, component, or visual-intent changes that do not alter meaning, update only the deck projection through \`upsertSlides\` and present the revised plan for confirmation.
 - If the user requests claim, evidence, caveat, decision, or recommendation meaning changes, update canonical narrative first and rerun narrative review/approval or explicit render override before compiling a new deck plan.
@@ -165,7 +172,7 @@ export function buildDeckReviewPrompt({
 
 Goal:
 - Use ${DECKS_STATE_FILE} as the source of truth for whether the current workspace deck is ready to be written to \`decks/*.html\`.
-- Treat this as an artifact gate for deck rendering, not strategic narrative approval. Narrative readiness reports are reviewed by \`/revela review\`.
+- Treat this as an artifact gate for deck rendering, not strategic narrative approval. Narrative readiness is reviewed through \`/revela story\`.
 - Preserve the deck spec for future sessions: every slide's content, layout, components, evidence, visuals, production status, and the 0.9 narrative compiler brief when available.
 - 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.

package/lib/decks-state.ts

@@ -661,7 +661,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
       type: "missing_slide_spec",
       severity: "blocker",
       message,
-      suggestedAction: "Run /revela make deck --review and resolve all readiness blockers before writing deck HTML.",
+      suggestedAction: "Run /revela make --deck and resolve all readiness blockers before writing deck HTML.",
     })
   }
   if (deck.writeReadiness.blockers.length > 0) {
@@ -671,7 +671,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
       type: "missing_slide_spec",
       severity: "blocker",
       message,
-      suggestedAction: "Resolve the stored writeReadiness blockers and rerun /revela make deck --review.",
+      suggestedAction: "Resolve the stored writeReadiness blockers and rerun /revela make --deck.",
     })
   }
   if (normalized.reviews.length > 0) {
@@ -684,7 +684,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
         type: "missing_slide_spec",
         severity: "blocker",
         message,
-        suggestedAction: "Run /revela make deck --review so readiness is recorded against the current active render target.",
+        suggestedAction: "Run /revela make --deck so readiness is recorded against the current active render target.",
       })
     } else if (!isReviewSnapshotCurrent(normalized, snapshot, deck.slug)) {
       const message = "Latest review snapshot is stale for the current deck, sources, evidence, narrative state, or render target"
@@ -693,7 +693,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
         type: "missing_slide_spec",
         severity: "blocker",
         message,
-        suggestedAction: "Run /revela make deck --review again after the latest state changes before writing deck HTML.",
+        suggestedAction: "Run /revela make --deck again after the latest state changes before writing deck HTML.",
       })
     } else if (snapshot.status !== "ready") {
       const message = `Latest review snapshot is ${snapshot.status}, not ready`
@@ -702,7 +702,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
         type: "missing_slide_spec",
         severity: "blocker",
         message,
-        suggestedAction: "Resolve review blockers and rerun /revela make deck --review before writing deck HTML.",
+        suggestedAction: "Resolve review blockers and rerun /revela make --deck before writing deck HTML.",
       })
     }
   }
@@ -748,7 +748,7 @@ export function buildDecksStatePromptLayer(workspaceRoot: string, maxChars = 140
   }
   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 the single current deck's specs, slide plan, evidence, render targets, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- ${DECKS_STATE_FILE} deck slides use 1-based \`slides[].index\` values. Render every HTML \`<section class="slide">\` with a matching 1-based \`data-slide-index\` attribute, and do not use 0-based \`data-index\` as slide identity.\n- The active HTML deck is represented as a \`renderTarget\` of type \`html_deck\`; PDF/PPTX exports should be recorded as derived render targets, not as separate deck specs.\n- \`writeReadiness\` is a compatibility projection for the /revela make deck generation workflow, not a hard blocker for targeted artifact-level HTML fixes.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- For /revela make deck generated HTML, use the current deck's outputPath and satisfy the deck HTML contract. For targeted artifact-level edits, patch the requested deck HTML directly without treating \`writeReadiness\` or \`planReview\` as a precondition.`
+  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, evidence, render targets, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- ${DECKS_STATE_FILE} deck slides use 1-based \`slides[].index\` values. Render every HTML \`<section class="slide">\` with a matching 1-based \`data-slide-index\` attribute, and do not use 0-based \`data-index\` as slide identity.\n- The active HTML deck is represented as a \`renderTarget\` of type \`html_deck\`; PDF/PPTX exports should be recorded as derived render targets, not as separate deck specs.\n- \`writeReadiness\` is a compatibility projection for the /revela make --deck generation workflow, not a hard blocker for targeted artifact-level HTML fixes.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- For /revela make --deck generated HTML, use the current deck's outputPath and satisfy the deck HTML contract. For targeted artifact-level edits, patch the requested deck HTML directly without treating \`writeReadiness\` or \`planReview\` as a precondition.`
 }
 
 function compactWorkspaceForPrompt(workspace: DecksState["workspace"]): DecksState["workspace"] {

package/lib/edit/deck-state.ts

@@ -84,7 +84,7 @@ function inferSlides(filePath: string): SlideSpec[] {
       evidence: [],
       visuals: [],
       status: "ready",
-      notes: "Inferred automatically by /revela edit preflight.",
+      notes: "Inferred automatically by /revela refine --deck preflight.",
     }
   })
 }

package/lib/edit/resolve-deck.ts

@@ -12,7 +12,7 @@ export interface EditableDeck {
 
 export function resolveEditableDeck(workspaceRoot: string, input = ""): EditableDeck {
   if (input.trim()) {
-    throw new Error("/revela refine does not accept a target. It opens the active HTML deck or the only HTML deck in decks/.")
+    throw new Error("/revela refine --deck does not accept a target. It opens the active HTML deck or the only HTML deck in decks/.")
   }
 
   if (hasDecksState(workspaceRoot)) {

package/lib/inspect/server.ts

@@ -484,7 +484,7 @@ export function renderInspectorShell(token: string): string {
     <aside>
       <div>
         <h1>Evidence Inspector</h1>
-        <p class="hint">Cmd/Ctrl-click slide elements to attach them as references, exactly like /revela edit. Then click <b>Inspect Selection</b>. This is not chat.</p>
+        <p class="hint">Cmd/Ctrl-click slide elements to attach them as references in /revela refine --deck. Then click <b>Inspect Selection</b>. This is not chat.</p>
       </div>
       <div id="selection" class="selection">
         <strong>Selection</strong>
@@ -632,7 +632,7 @@ export function renderInspectorShell(token: string): string {
         if (bindAttempts >= 80) {
           clearInterval(bindTimer);
           bindTimer = 0;
-          setBindingStatus('error', 'Selection binding timed out. Reopen /revela inspect or reload this page.');
+          setBindingStatus('error', 'Selection binding timed out. Reopen /revela refine --deck or reload this page.');
         }
       }, 150);
     }

package/lib/prompt-builder.ts

@@ -7,8 +7,10 @@
  *
  * Deck-render mode:
  *   Layer 1: SKILL.md           — legacy deck render protocol (HTML rules, quality)
- *   Layer 2: DOMAIN.md          — domain structure/terminology
- *   Layer 3: DESIGN.md          — visual style (colors, fonts, animations, layout)
+ *   Layer 2: DESIGN.md          — visual style (colors, fonts, animations, layout)
+ *
+ * Domain guidance is intentionally narrative-only. Deck-render mode must render
+ * the approved canonical narrative instead of re-interpreting domain semantics.
  *
  * When the active DESIGN.md has @section markers, only the global section,
  * layouts section, and a generated component index are injected into the
@@ -87,19 +89,23 @@ export function buildPrompt(optionsOrDesignName?: BuildPromptOptions | string, l
     ? "<!--   - preview.html — canonical visual reference (read this before generating slides) -->"
     : "<!--   - (no preview.html for this design) -->"
 
-  // Layer 2 — DOMAIN.md skill text (may be empty for "general")
+  // Layer 2 — DOMAIN.md skill text (narrative mode only). Deck-render mode
+  // renders the approved canonical narrative and must not re-interpret domain
+  // semantics from the full domain prompt.
   let domainSkill = ""
-  try {
-    domainSkill = getDomainSkillMd(domain)
-  } catch (e) {
-    // Domain not installed or empty — proceed without domain layer
-    promptLog.warn("domain skill not found — building without domain layer", {
-      domain,
-      error: e instanceof Error ? e.message : String(e),
-    })
+  if (mode === "narrative") {
+    try {
+      domainSkill = getDomainSkillMd(domain)
+    } catch (e) {
+      // Domain not installed or empty — proceed without domain layer
+      promptLog.warn("domain skill not found — building without domain layer", {
+        domain,
+        error: e instanceof Error ? e.message : String(e),
+      })
+    }
   }
 
-  // Layer 3 — DESIGN.md: deck-render only. Narrative mode must not inject
+  // DESIGN.md: deck-render only. Narrative mode must not inject
   // visual CSS, layout catalogs, component indexes, or HTML skeleton rules.
   const designSkill = mode === "deck-render" ? buildDesignLayer(design) : ""
 
@@ -107,7 +113,7 @@ export function buildPrompt(optionsOrDesignName?: BuildPromptOptions | string, l
   const header = mode === "deck-render"
     ? `<!-- Revela prompt mode: deck-render -->\n` +
       `<!-- Active design: ${design} -->\n` +
-      `<!-- Active domain: ${domain} -->\n` +
+      `<!-- Active domain: ${domain} (not injected in deck-render mode) -->\n` +
       `<!-- Design files: ${designDir}/ -->\n` +
       `<!--   - DESIGN.md — metadata + style instructions (injected below) -->\n` +
       `${previewLine}\n\n`
@@ -115,7 +121,7 @@ export function buildPrompt(optionsOrDesignName?: BuildPromptOptions | string, l
       `<!-- Active domain: ${domain} -->\n` +
       `<!-- Design layer intentionally omitted in narrative mode. Use deck-render mode before writing deck artifacts. -->\n\n`
 
-  // Concatenation: Header → Skill → Domain → Design (deck-render only)
+  // Concatenation: Header → Skill → Domain (narrative only) → Design (deck-render only)
   const parts = [header, coreSkill]
   if (domainSkill) {
     parts.push(`\n\n---\n\n${domainSkill}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",