@cyber-dash-tech/revela 0.15.2 → 0.15.4

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 review --deck` and the Insight 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/refine.ts

@@ -14,13 +14,13 @@ export async function handleRefine(
     })
 
     await send(
-      `Opened Revela Refine for the active HTML deck.\n` +
+      `Opened Revela Review for the active HTML deck.\n` +
       `File: \`${result.deck.file}\`\n` +
       `${result.stateNote}\n` +
       `URL: ${result.url}\n\n` +
-      `Use Ctrl/Cmd-click in the browser to reference deck elements. The Edit tab sends targeted change comments; the Inspect tab reviews the same selection with Source/Purpose cards and does not edit the deck.`
+      `Use Ctrl/Cmd-click in the browser to reference deck elements. The Comment tab sends targeted change comments; the Insight tab reviews the same selection with Source/Purpose cards and does not edit the deck.`
     )
   } catch (e: any) {
-    await send(`**Refine failed:** ${e.message || String(e)}`)
+    await send(`**Review failed:** ${e.message || String(e)}`)
   }
 }

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 Review. If post-write artifact QA reports hard errors, fix them and let QA run again. Review 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 Review.
 
 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.
+- 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 Review.
 
 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 review --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 review --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 review --deck. Then click <b>Get Insight</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 review --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/lib/refine/server.ts

@@ -247,7 +247,7 @@ async function handleAssetSave(req: Request, session: EditSession): Promise<Resp
     id: body?.id || candidate.candidateId,
     type: "image",
     purpose,
-    brief: body?.brief || `Saved from ${candidate.provider} for Refine asset placement.`,
+    brief: body?.brief || `Saved from ${candidate.provider} for Review asset placement.`,
     status: "success",
     sourceUrl: candidate.imageUrl,
     alt: body?.alt || candidate.alt || candidate.title,
@@ -652,7 +652,7 @@ function handleInspectResult(requestId: string | null, session: EditSession): Re
   session.lastActiveAt = Date.now()
   scheduleIdleStop()
   if (request.status === "completed") return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion, result: request.result })
-  if (request.status === "failed" || request.status === "expired") return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion, error: request.error || "Inspection failed" })
+  if (request.status === "failed" || request.status === "expired") return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion, error: request.error || "Insight failed" })
   return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion })
 }
 
@@ -764,7 +764,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>Revela Refine</title>
+  <title>Revela Review</title>
   <style>
     :root { color-scheme: light; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
     * { box-sizing: border-box; }
@@ -783,15 +783,16 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     .deck-nav button:hover:not(:disabled) { background: rgba(255,255,255,.22); }
     .deck-nav button:disabled { opacity: .38; }
     .deck-nav-status { min-width: 76px; color: #e2e8f0; font-size: 12px; font-weight: 900; text-align: center; font-variant-numeric: tabular-nums; }
-    aside { position: relative; display: flex; flex-direction: column; gap: 16px; padding: 20px; background: linear-gradient(180deg, #fbfaf7 0%, #f2eee6 100%); overflow: auto; border-left: 1px solid #d8d2c6; }
+    aside { position: relative; display: flex; flex-direction: column; gap: 16px; padding: 20px; background: linear-gradient(180deg, #fbfaf7 0%, #f2eee6 100%); overflow: auto; border-left: 1px solid #d8d2c6; font-family: Garamond, "Iowan Old Style", Georgia, serif; }
+    aside button, aside input, aside select, aside textarea, aside .comment-editor { font-family: inherit; }
     h1 { margin: 0; font-size: 18px; line-height: 1.2; letter-spacing: -.01em; color: #0f172a; }
     .wordmark { font-family: Garamond, "Iowan Old Style", Georgia, serif; font-size: 21px; letter-spacing: .08em; font-weight: 600; }
-    .hint { margin: 0; color: #756f66; font-size: 13px; line-height: 1.5; }
     .panel { display: flex; flex-direction: column; gap: 10px; }
-    .tabs { display: grid; grid-template-columns: 1fr 1fr; gap: 6px; padding: 4px; border: 1px solid #d8d2c6; border-radius: 14px; background: #ebe4d8; }
-    .tab { padding: 9px 10px; border: 0; border-radius: 10px; background: transparent; color: #5f594f; box-shadow: none; font-weight: 900; }
-    .tab.active { background: #fbfaf7; color: #111827; box-shadow: 0 6px 16px rgba(31,41,51,.1); }
-    .tab-panel { display: none; flex-direction: column; gap: 12px; }
+    .tabs { display: flex; gap: 2px; padding: 0 0 0 8px; border-bottom: 1px solid #d8d2c6; background: transparent; }
+    .tab { width: auto; min-width: 112px; padding: 10px 18px; border: 1px solid transparent; border-bottom: 0; border-radius: 13px 13px 0 0; background: transparent; color: #5f594f; box-shadow: none; font-weight: 900; }
+    .tab:hover:not(:disabled) { background: rgba(255,253,248,.58); }
+    .tab.active { position: relative; top: 1px; background: #fbfaf7; border-color: #d8d2c6; color: #111827; box-shadow: 0 -7px 16px rgba(31,41,51,.05); }
+    .tab-panel { display: none; flex-direction: column; gap: 12px; padding-top: 12px; }
     .tab-panel.active { display: flex; }
     .sr-only { position: absolute !important; width: 1px !important; height: 1px !important; padding: 0 !important; margin: -1px !important; overflow: hidden !important; clip: rect(0,0,0,0) !important; white-space: nowrap !important; border: 0 !important; }
     .selection-summary { padding: 10px 12px; border: 1px solid #d8d2c6; border-radius: 14px; background: #fbfaf7; color: #3f3a33; font-size: 13px; line-height: 1.45; box-shadow: 0 8px 22px rgba(31,41,51,.05); }
@@ -885,20 +886,19 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     <div id="resizeHandle" class="resize-handle" role="separator" aria-label="Resize editor panel" aria-orientation="vertical" title="Drag to resize editor. Double-click to reset."></div>
     <aside>
       <div>
-        <h1><span class="wordmark">REVELA</span> Refine</h1>
-        <p class="hint">Select refs, describe the change, then send. Use Inspect only when you need source or purpose context.</p>
+        <h1><span class="wordmark">REVELA</span> Review</h1>
       </div>
       <div id="selectionSummary" class="selection-summary sr-only" aria-live="polite"><strong>Selection</strong><span>No references selected.</span><div id="selectionChips" class="selection-chips"></div></div>
-      <div class="tabs" role="tablist" aria-label="Refine mode">
-        <button id="editTab" class="tab" type="button" role="tab">Edit</button>
-        <button id="inspectTab" class="tab" type="button" role="tab">Inspect</button>
+      <div class="tabs" role="tablist" aria-label="Review mode">
+        <button id="editTab" class="tab" type="button" role="tab">Comment</button>
+        <button id="inspectTab" class="tab" type="button" role="tab">Insight</button>
       </div>
       <div id="editPanel" class="tab-panel">
         <div class="panel">
           <div class="label">Describe the change</div>
           <div id="comment" class="comment-editor" contenteditable="true" role="textbox" aria-multiline="true" data-placeholder="Cmd/Ctrl-click slide elements to add @refs, then describe the exact edit."></div>
         </div>
-        <div class="edit-assets" aria-label="Edit assets">
+        <div class="edit-assets" aria-label="Comment assets">
           <div class="panel">
             <div class="asset-tools"><div class="label">Local Assets</div><button id="assetSearchToggle" class="asset-search-toggle" type="button" aria-expanded="false" aria-controls="assetSearchView" title="Search assets">+</button></div>
             <div id="editSavedAssets" class="asset-grid"><p class="asset-empty">No local assets yet. Click + to search assets.</p></div>
@@ -909,20 +909,20 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       </div>
       <div id="inspectPanel" class="tab-panel">
         <div class="panel">
-          <label class="label" for="inspectComment">Inspect comment</label>
+          <label class="label" for="inspectComment">Insight comment</label>
           <div id="inspectComment" class="comment-editor" contenteditable="true" role="textbox" aria-multiline="true" data-placeholder="Cmd/Ctrl-click slide elements to add @refs, then ask about purpose or source."></div>
         </div>
         <div class="inspect-actions">
           <div class="inspect-options"><label for="inspectLanguage">Display Language</label><select id="inspectLanguage" class="inspect-select"><option>Auto</option><option>English</option><option>简体中文</option><option>繁體中文</option><option>日本語</option><option>Deutsch</option><option>Français</option><option>Español</option><option>Português</option><option>Arabic</option></select></div>
-          <button id="inspectButton" disabled>Inspect Reference</button>
+          <button id="inspectButton" disabled>Get Insight</button>
           <div id="inspectStale"></div>
         </div>
-        <div id="inspectCards" class="inspect-cards"><div class="inspect-empty">Select a deck element to create an @ref, optionally ask a question, then Inspect. This does not edit the deck.</div></div>
+        <div id="inspectCards" class="inspect-cards"><div class="inspect-empty">Select a deck element to create an @ref, optionally ask a question, then get insight. This does not edit the deck.</div></div>
       </div>
       <div id="assetSearchView" class="asset-search-view" aria-hidden="true">
         <div class="asset-search-head">
           <button id="assetSearchBack" class="asset-back" type="button">← Back</button>
-          <div class="asset-search-title"><h2>Search Assets</h2><span>Save images to Local Assets, then use them from Edit.</span></div>
+          <div class="asset-search-title"><h2>Search Assets</h2><span>Save images to Local Assets, then use them from Comment.</span></div>
         </div>
         <div class="panel">
           <div class="asset-search"><input id="assetQuery" type="search" placeholder="Company logo, product photo, portrait..." /><select id="assetPurpose"><option value="logo" selected>logo</option><option value="illustration">photo</option><option value="hero">hero</option><option value="portrait">portrait</option><option value="screenshot">screenshot</option></select></div>
@@ -1072,7 +1072,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           restoreEditorWidth();
           bindEvents();
           setMode(state.mode);
-          setStatus('Editor ready. Ctrl/Cmd + click deck elements to reference them.');
+          setStatus('Review ready. Ctrl/Cmd + click deck elements to reference them.');
           initFrame();
           loadSavedAssets();
           startDeckVersionPolling();
@@ -1116,6 +1116,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         els.inspectComment.addEventListener('mouseup', saveCommentRange);
         document.addEventListener('selectionchange', saveCommentRange);
         els.hitbox.addEventListener('pointermove', onHover);
+        els.hitbox.addEventListener('pointerleave', clearHoverSilently);
         els.hitbox.addEventListener('pointerdown', onPointerDown);
         els.hitbox.addEventListener('click', onClick);
         els.hitbox.addEventListener('contextmenu', (event) => {
@@ -1263,7 +1264,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
             state.pendingRefreshMessage = false;
             setStatus('Deck updated. Preview refreshed. Element references were cleared.');
           } else {
-            setStatus(slides.length > 0 ? 'Editor ready. Found ' + slides.length + ' slides. Ctrl/Cmd + click to reference elements.' : 'Editor ready, but no .slide elements were found. Ctrl/Cmd + click to reference elements.');
+            setStatus(slides.length > 0 ? 'Review ready. Found ' + slides.length + ' slides. Ctrl/Cmd + click to reference elements.' : 'Review ready, but no .slide elements were found. Ctrl/Cmd + click to reference elements.');
           }
         } catch (error) {
           reportError(error);
@@ -1336,9 +1337,11 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
             } catch {}
           }
           if (!handled) applyFallbackDeckNavigation(win, doc, slides, clamped);
+          const changed = clamped !== state.deckSlideIndex;
           state.deckSlideIndex = clamped;
           updateDeckNavControls();
-          renderHoverOutline(state.hoverEl);
+          if (changed) clearHoverSilently();
+          else renderHoverOutline(state.hoverEl);
           renderReferenceOutlines();
         } catch (error) {
           reportError(error);
@@ -1415,6 +1418,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           initFrame();
           const target = selectable(targetFromPointer(event));
           if (!target || isReferenced(target)) {
+            state.hoverEl = null;
             renderHoverOutline(null);
             return;
           }
@@ -1829,7 +1833,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         renderReferenceOutlines();
         updateSendState();
         renderSelectionSummary();
-        resetInspectCards('References ready. Open Inspect and click Inspect Reference for concise Purpose and Source context.');
+        resetInspectCards('References ready. Open Insight and click Get Insight for concise Purpose and Source context.');
         setStatus('Inserted @' + label + '. ' + state.references.length + ' reference' + (state.references.length === 1 ? '' : 's') + ' will be sent.');
       }
 
@@ -1997,14 +2001,27 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       function renderReferenceOutlines() {
         const doc = els.frame.contentDocument;
         if (!doc || doc.location.href === 'about:blank') return;
+        const slides = getSlides(doc);
+        const currentSlide = slides[state.deckSlideIndex];
+        const explicitSlideIndex = Number(currentSlide?.getAttribute('data-slide-index'));
+        const currentSlideIndex = Number.isFinite(explicitSlideIndex) && explicitSlideIndex > 0 ? explicitSlideIndex : state.deckSlideIndex + 1;
         while (state.referenceOutlines.length < state.references.length) state.referenceOutlines.push(createOutline(doc, '#7aa6d8', 'rgba(122,166,216,.18)'));
         state.referenceOutlines.forEach((outline, index) => {
           const reference = state.references[index];
           setOutlineColor(outline, reference?.color);
+          if (!reference || reference.payload?.slideIndex !== currentSlideIndex) {
+            renderBox(outline, null);
+            return;
+          }
           renderBox(outline, reference?.target);
         });
       }
 
+      function clearHoverSilently() {
+        state.hoverEl = null;
+        if (state.hoverOutline) state.hoverOutline.style.display = 'none';
+      }
+
       function clearHover() {
         state.hoverEl = null;
         setStatus('Hover cleared. Existing references are kept.');
@@ -2015,8 +2032,8 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         if (state.sendingEdit) setButtonLoading(els.send, true, 'Sending...');
         else setButtonLoading(els.send, false, '<svg class="send-icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94L14.7 6.3z"/></svg><span>Apply Fix</span>', true);
         els.send.disabled = state.sendingEdit || !getCommentText().trim();
-        if (state.inspecting) setButtonLoading(els.inspectButton, true, 'Inspecting...');
-        else setButtonLoading(els.inspectButton, false, 'Inspect Reference');
+        if (state.inspecting) setButtonLoading(els.inspectButton, true, 'Getting insight...');
+        else setButtonLoading(els.inspectButton, false, 'Get Insight');
         els.inspectButton.disabled = state.inspecting || state.references.length === 0;
       }
 
@@ -2077,7 +2094,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
             body: JSON.stringify({ snapshot, deckVersion: state.deckVersion, language: state.inspectLanguage, comment }),
           });
           const body = await res.json().catch(() => ({}));
-          if (!res.ok || !body.ok) throw new Error(body.error || 'Inspection failed');
+          if (!res.ok || !body.ok) throw new Error(body.error || 'Insight failed');
           state.deckVersion = body.deckVersion || state.deckVersion;
           state.activeInspectRequestId = body.requestId;
           state.inspectFallback = body.preprocess || null;
@@ -2086,7 +2103,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         } catch (error) {
           if (state.inspectFallback) {
             renderInspectResult(state.inspectFallback, 'Deterministic fallback');
-            els.inspectCards.insertAdjacentHTML('afterbegin', '<div class="inspect-warning">Generated inspection failed or timed out. Showing deterministic fallback context only.</div>');
+            els.inspectCards.insertAdjacentHTML('afterbegin', '<div class="inspect-warning">Generated insight failed or timed out. Showing deterministic fallback context only.</div>');
           } else {
             resetInspectCards(error && error.message ? error.message : String(error));
           }
@@ -2101,15 +2118,15 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           await delay(900);
           const res = await fetch('/api/inspect-result?token=' + encodeURIComponent(token) + '&requestId=' + encodeURIComponent(requestId));
           const body = await res.json().catch(() => ({}));
-          if (!res.ok || !body.ok) throw new Error(body.error || 'Inspection result failed');
+          if (!res.ok || !body.ok) throw new Error(body.error || 'Insight result failed');
           if (body.status === 'completed') {
             state.deckVersion = body.deckVersion || state.deckVersion;
             renderInspectResult(body.result, 'Generated');
             return;
           }
-          if (body.status === 'failed' || body.status === 'expired') throw new Error(body.error || 'Inspection failed');
+          if (body.status === 'failed' || body.status === 'expired') throw new Error(body.error || 'Insight failed');
         }
-        throw new Error('Inspection timed out while waiting for OpenCode result');
+        throw new Error('Insight timed out while waiting for OpenCode result');
       }
 
       function collectReferenceSnapshot() {
@@ -2136,10 +2153,10 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       }
 
       function renderInspectResult(result, phase) {
-        if (result.stale?.stale) els.inspectStale.innerHTML = '<div class="inspect-stale">' + escapeHtml(result.stale.reason || 'Inspection may be stale.') + '</div>';
+        if (result.stale?.stale) els.inspectStale.innerHTML = '<div class="inspect-stale">' + escapeHtml(result.stale.reason || 'Insight may be stale.') + '</div>';
         else els.inspectStale.innerHTML = '';
         els.inspectCards.innerHTML = [
-          '<div class="status">' + escapeHtml(phase || 'Inspection') + '</div>',
+          '<div class="status">' + escapeHtml(phase || 'Insight') + '</div>',
           renderInspectCard('Purpose', result.cards.purpose.status, result.cards.purpose.rationale, renderPurpose(result.cards.purpose)),
           renderInspectCard('Source', result.cards.source.status, result.cards.source.rationale, renderSource(result.cards.source)),
         ].join('');
@@ -2303,7 +2320,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           removeAssetChip();
         }
         renderSelectionSummary();
-        resetInspectCards('Select a deck element to create an @ref, optionally ask a question, then Inspect. This does not edit the deck.');
+        resetInspectCards('Select a deck element to create an @ref, optionally ask a question, then get insight. This does not edit the deck.');
       }
 
       function getCommentText(editor) {

package/package.json

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