@cyber-dash-tech/revela 0.14.0 → 0.15.1

package/lib/command-intent.ts

@@ -0,0 +1,59 @@
+import type { PromptMode } from "./prompt-builder"
+
+export interface PendingCommandIntent {
+  sessionID: string
+  name: string
+  mode: PromptMode
+  visibleText: string
+  hiddenPrompt: string
+  createdAt: number
+}
+
+const pendingCommandIntents = new Map<string, PendingCommandIntent>()
+
+export function setPendingCommandIntent(intent: Omit<PendingCommandIntent, "createdAt"> & { createdAt?: number }): PendingCommandIntent {
+  const normalized: PendingCommandIntent = {
+    ...intent,
+    createdAt: intent.createdAt ?? Date.now(),
+  }
+  pendingCommandIntents.set(normalized.sessionID, normalized)
+  return normalized
+}
+
+export function peekPendingCommandIntent(sessionID: string): PendingCommandIntent | undefined {
+  if (!sessionID) return undefined
+  return pendingCommandIntents.get(sessionID)
+}
+
+export function takePendingCommandIntent(sessionID: string): PendingCommandIntent | undefined {
+  if (!sessionID) return undefined
+  const intent = pendingCommandIntents.get(sessionID)
+  if (intent) pendingCommandIntents.delete(sessionID)
+  return intent
+}
+
+export function clearPendingCommandIntent(sessionID: string): void {
+  if (!sessionID) return
+  pendingCommandIntents.delete(sessionID)
+}
+
+export function clearAllPendingCommandIntents(): void {
+  pendingCommandIntents.clear()
+}
+
+export function formatCommandIntentSystemBlock(intent: PendingCommandIntent): string {
+  return [
+    "<revela-command-intent>",
+    `User invoked: /revela ${intent.name}`,
+    `Prompt mode: ${intent.mode}`,
+    "Visible user intent:",
+    intent.visibleText,
+    "",
+    "Execute the hidden workflow instructions below with the available Revela tools.",
+    "Do not persist this command block as workspace memory or user preference.",
+    "",
+    "Hidden workflow instructions:",
+    intent.hiddenPrompt,
+    "</revela-command-intent>",
+  ].join("\n")
+}

package/lib/commands/brief.ts

@@ -34,7 +34,7 @@ export async function handleBrief(
     await send(
       `**Executive brief not rendered**\n\n${result.reason}\n\n` +
       (result.narrativeHash ? `Narrative hash: \`${result.narrativeHash}\`\n\n` : "") +
-      "Run `/revela review` and approve the current narrative, or record an explicit render override before retrying."
+      "Run `/revela story` and approve the current narrative, or record an explicit render override before retrying."
     )
     return
   }

package/lib/commands/designs.ts

@@ -36,7 +36,7 @@ export async function handleDesignsActivate(
   try {
     activateDesign(name)
     buildPrompt({ mode: "narrative" })
-    await send(`**Design activated:** \`${name}\`\nNarrative prompt rebuilt. The design will apply when \`/revela deck\` enters deck-render mode.`)
+    await send(`**Design activated:** \`${name}\`\nNarrative prompt rebuilt. The design will apply when \`/revela make deck\` enters deck-render mode.`)
   } catch (e: any) {
     await send(`**Error:** ${e.message}`)
   }

package/lib/commands/domains.ts

@@ -36,7 +36,7 @@ export async function handleDomainsActivate(
   try {
     activateDomain(name)
     buildPrompt({ mode: "narrative" })
-    await send(`**Domain activated:** \`${name}\`\nNarrative prompt rebuilt. Domain reasoning applies now; deck-specific render guidance applies during \`/revela deck\`.`)
+    await send(`**Domain activated:** \`${name}\`\nNarrative prompt rebuilt. Domain reasoning applies now; deck-specific render guidance applies during \`/revela make deck\`.`)
   } catch (e: any) {
     await send(`**Error:** ${e.message}`)
   }

package/lib/commands/edit.ts

@@ -1,26 +1,7 @@
-import { openRefineDeck } from "../refine/open"
-
 export async function handleEdit(
   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: "edit",
-      openBrowser: options.openBrowser,
-    })
-
-    await send(
-      `\`/revela edit\` is deprecated. Opened \`/revela refine\` in Edit 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 elements, then use the Edit tab to send targeted change comments.`
-    )
-  } catch (e: any) {
-    await send(`**Edit failed:** ${e.message || String(e)}`)
-  }
+  void options
+  await send("`/revela edit` has been removed. Use `/revela refine` for the unified reading, inspection, and editing workspace.")
 }

package/lib/commands/enable.ts

@@ -1,7 +1,7 @@
 /**
  * lib/commands/enable.ts
  *
- * Handler for `/revela enable` — activates Revela narrative/artifact mode.
+ * Handler for `/revela enable` — activates Revela ambient narrative mode.
  */
 
 import { existsSync } from "fs"
@@ -19,7 +19,7 @@ export async function handleEnable(
   const design = activeDesign()
   const domain = activeDomain()
 
-  // Always rebuild narrative mode on enable. A prior `/revela deck` handoff may
+  // Always rebuild narrative mode on enable. A prior `/revela make deck` handoff may
   // have intentionally switched the active prompt to deck-render mode.
   if (!existsSync(ACTIVE_PROMPT_FILE)) {
     log.warn("active prompt file missing on enable — rebuilding", { promptFile: ACTIVE_PROMPT_FILE })
@@ -30,7 +30,7 @@ export async function handleEnable(
   } catch (e) {
     log.error("prompt rebuild failed on enable", { error: e instanceof Error ? e.message : String(e) })
     await send(
-      `**Revela enabled (with warnings).** Narrative/artifact mode is active, ` +
+      `**Revela ambient mode enabled (with warnings).** Narrative mode is active for normal chat, ` +
       `but the prompt file could not be built. ` +
       `Try \`/revela disable\` then \`/revela enable\` again, or check that the package is correctly installed.\n\n` +
       `Design: \`${design}\` · Domain: \`${domain}\``
@@ -40,9 +40,9 @@ export async function handleEnable(
 
   log.info("revela enabled", { design, domain })
   await send(
-    `**Revela enabled.** Narrative/artifact mode is now active.\n` +
+    `**Revela ambient mode enabled.** Normal chat will stay in Revela narrative mode.\n` +
     `Design: \`${design}\` · Domain: \`${domain}\`\n\n` +
-    `The narrative-first prompt will be injected into every message. ` +
-    `Use \`/revela deck\` when you are ready to enter deck-render mode.`
+    `Explicit workflow commands like \`/revela init\`, \`/revela story\`, and \`/revela make deck\` work without enabling first. ` +
+    `Use \`/revela disable\` to return normal chat to plain OpenCode mode.`
   )
 }

package/lib/commands/help.ts

@@ -24,18 +24,26 @@ export async function handleHelp(
     `🟠 **Domain:** \`${domain}\`\n\n` +
     `---\n\n` +
     `**Commands**\n\n` +
-    `\`/revela enable\`              — enable Revela narrative/artifact mode\n` +
-    `\`/revela disable\`             — disable Revela mode\n` +
+    `\`/revela enable\`              — optional ambient narrative mode for normal chat\n` +
+    `\`/revela disable\`             — disable ambient Revela mode\n` +
     `\`/revela init\`                — initialize or refresh workspace DECKS.json\n` +
-    `\`/revela review\`              — review narrative readiness and approval state\n` +
-    `\`/revela narrative\`           — open read-only narrative workspace map\n` +
-    `\`/revela brief [file.md]\`      — render executive brief from approved narrative\n` +
-    `\`/revela deck\`                — start deck handoff from approved narrative\n` +
-    `\`/revela deck --review\`       — review deck/artifact readiness before writing HTML\n` +
+    `\`/revela research\`            — research, bind evidence, and reduce story gaps\n` +
+    `\`/revela story [-l language]\`  — open the read-only story workspace UI\n` +
+    `\`/revela review\`              — legacy readiness report for story state\n` +
+    `\`/revela narrative\`           — compatibility alias for /revela story\n` +
+    `\`/revela make deck\`           — make a deck from approved story state\n` +
+    `\`/revela make deck --review\`  — review deck/artifact readiness before writing HTML\n` +
+    `\`/revela make brief [file.md]\` — render executive brief from approved story\n` +
+    `\`/revela deck\`                — compatibility alias for /revela make deck\n` +
+    `\`/revela brief [file.md]\`      — compatibility alias for /revela make brief\n` +
     `\`/revela refine\`              — open unified reading, inspection, and editing workspace\n` +
-    `\`/revela edit\`                — deprecated compatibility shim to /revela refine Edit\n` +
     `\`/revela inspect\`             — deprecated compatibility shim to /revela refine Inspect\n` +
     `\`/revela remember <text>\`     — save an explicit preference to DECKS.json\n` +
+    `\`/revela design\`              — list installed designs\n` +
+    `\`/revela design use <name>\`   — activate a design\n` +
+    `\`/revela design new <name>\`   — create a custom design with AI\n` +
+    `\`/revela design edit <name>\`  — refine an existing custom design with AI\n` +
+    `\`/revela design preview [name]\` — open a design preview in browser\n` +
     `\`/revela designs\`             — list installed designs\n` +
     `\`/revela designs <name>\`      — activate a design\n` +
     `\`/revela designs-new <name>\`  — create a new custom design with AI\n` +

package/lib/commands/init.ts

@@ -17,7 +17,7 @@ Goal:
 - Build or update ${DECKS_STATE_FILE}, the workspace-level machine-readable state file for Revela narrative and artifact work.
 - Use the \`revela-decks\` tool for state updates. Do not write or patch ${DECKS_STATE_FILE} directly.
 - Capture stable narrative context first: primary audience, belief before, belief after, decision/action, thesis, central claims, evidence availability, objections, risks, available source materials, existing artifact history, and open questions.
-- Do not treat initialization as permission to write a deck. Narrative readiness is reviewed later by \`/revela review\`; deck/artifact readiness is reviewed by \`/revela deck --review\`.
+- Do not treat initialization as permission to write a deck. Narrative readiness is reviewed later by \`/revela story\`; deck/artifact readiness is reviewed by \`/revela make deck --review\`.
 - Do not require slide count, visual style, design selection, output path, layout choices, or component choices during narrative initialization unless the user explicitly asks to render a deck now.
 - ${DECKS_STATE_FILE} is the compatibility workspace-state file. Deck specs are render-target projections, not the center of initialization.
 

package/lib/commands/narrative.ts

@@ -12,7 +12,33 @@ export interface NarrativeArgs {
   raw: boolean
 }
 
+export interface StoryArgs {
+  language: NarrativeViewLanguage
+}
+
 export type ParseNarrativeArgsResult = { ok: true; args: NarrativeArgs } | { ok: false; error: string }
+export type ParseStoryArgsResult = { ok: true; args: StoryArgs } | { ok: false; error: string }
+
+export function parseStoryArgs(param: string): ParseStoryArgsResult {
+  const tokens = param.trim().split(/\s+/).filter(Boolean)
+  let language: NarrativeViewLanguage = "en"
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]
+    if (token === "--language" || token === "-l") {
+      const value = tokens[++i]
+      if (!value) return { ok: false, error: "Usage: `/revela story [--language <language> | -l <language>]`" }
+      language = normalizeLanguageRequest(value)
+      continue
+    }
+    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: true, args: { language } }
+}
 
 export function parseNarrativeArgs(param: string): ParseNarrativeArgsResult {
   const tokens = param.trim().split(/\s+/).filter(Boolean)

package/lib/commands/research.ts

@@ -0,0 +1,66 @@
+import { DECKS_STATE_FILE } from "../decks-state"
+
+export function buildResearchPrompt({
+  exists,
+  workspaceRoot,
+}: {
+  exists: boolean
+  workspaceRoot?: string
+}): string {
+  const state = exists
+    ? `${DECKS_STATE_FILE} exists. Read it through the revela-decks tool before researching.`
+    : `${DECKS_STATE_FILE} does not exist yet. Do not start broad internet research; initialize the workspace first with /revela init unless the user supplied a specific research question in chat.`
+
+  return `Run Revela closed-loop research.
+
+Goal:
+- Reduce open gaps, unsupported scope, weak evidence, unattached findings, and overextended relation rationale for the current story.
+- Drive research from canonical narrative gaps: unsupported central claims, objections, risks, decision questions, explicit researchGaps, and claim_chain_gap warnings.
+- Treat /revela research as authorization to bind clearly supported findings into canonical evidence without asking for item-by-item user confirmation.
+- Preserve evidence boundaries: eliminate caveats only when evidence or narrower wording actually resolves them; otherwise keep precise caveats visible.
+- Do not write decks, briefs, or design artifacts during research.
+
+Current state:
+- ${state}
+${workspaceRoot ? `- Current workspace root: \`${workspaceRoot}\`` : ""}
+
+Closed-loop workflow:
+1. Call \`revela-decks\` action \`read\`, then \`reviewNarrative\`.
+2. If current research gaps are missing or stale, call \`deriveResearchGaps\` when useful. Do not invent gaps that are not tied to a claim, objection, risk, decision, or narrative issue.
+3. Run up to 3 research loops unless the stop conditions below are met earlier.
+4. At the start of each loop, choose the highest-value 2-3 targets: open/in-progress high-priority gaps, unattached saved findings, unsupported central claims, weak evidence, high-priority objections/risks, and claim_chain_gap relations. Prefer targets that can improve readiness or materially reduce caveats. Do not repeat searches for claims already strongly supported.
+5. If a target already has saved findings, prioritize binding/narrowing before doing more external search.
+6. For targets needing external evidence, mark matching gaps \`in_progress\` with \`revela-decks updateResearchGap\`, then delegate search to the \`revela-research\` subagent. Ask it for source URLs, quotes/snippets, dates or locations when available, caveats, remaining gaps, and a \`## Recommended evidence bindings\` section with claimId, quote, source, supportScope, unsupportedScope, caveat, and strength. Save findings with \`revela-research-save\` under \`researches/{topic}/{axis}.md\` using \`## Data\`, \`## Cases\`, \`## Images\`, and \`## Gaps\` sections as applicable.
+7. After findings are saved or existing findings are selected, read or inspect the findings file. Attach it with \`revela-decks attachResearchFindings\` when it maps to an existing research axis.
+8. Automatically bind evidence when all binding criteria are met. Use \`revela-decks applyEvidenceCandidates\` for concrete candidate ids when available, or \`upsertNarrative\` to preserve canonical evidence bindings with exact source, URL/path, quote/snippet, support scope, unsupported scope, caveat, and strength.
+9. Binding criteria: claimId exists; quote/snippet is traceable to the source and is not invented; source URL or workspace source path is present; supportScope and unsupportedScope are explicit; strength is strong or useful partial; caveat is preserved; binding does not expand the claim beyond the evidence.
+10. If a claim or relation is broader than the evidence, narrow the claim text, supportedScope, unsupportedScope, or relation rationale through \`upsertNarrative\` only when the narrower wording preserves the user's strategic meaning and source boundaries. Do not silently change the decision ask, central recommendation, or approval meaning.
+11. Update matching gaps after binding: use \`evidence_bound\` when canonical evidence was added, \`closed\` when the gap is resolved or non-researchable, \`findings_saved\` only when findings exist but binding criteria are not met, and \`open\` with notes when more external research is still warranted.
+12. Re-run \`reviewNarrative\` after each loop. Compare against the previous loop: fewer open gaps, fewer unattached findings, stronger evidence, narrower unsupported scope, or clearer internal-data caveats should count as progress.
+
+Stop conditions:
+- No open externally researchable gaps remain.
+- All useful saved findings have been attached or evidence-bound.
+- A full loop produces no new bindable evidence, narrower wording, or gap status improvement.
+- Remaining gaps require internal user/company data, confidential sources, or strategic judgment.
+- 3 loops have completed.
+
+Report format:
+- Start with \`Research loop completed after <n> round(s).\`
+- List bound evidence by claim id and count.
+- List gaps closed or moved to evidence_bound.
+- List claims or relations narrowed, with the remaining unsupported scope.
+- List remaining caveats only as one of: \`internal_data_needed\`, \`not_publicly_researchable\`, \`source_quality_limit\`, or \`still_open\`.
+- If no binding happened, say why binding criteria failed and what exact source type is needed next.
+- End with the next smallest story action, not a generic request for user confirmation.
+
+Rules:
+- Do not use primary-agent broad websearch. Use the \`revela-research\` subagent for external search.
+- Do not invent quotes, source paths, URLs, page references, locations, or caveats.
+- Do not treat \`researches/**/*.md\` as canonical evidence until attached or evidence-bound, but do not stop at findings_saved when binding criteria are met.
+- Do not mutate canonical claims merely to fit a source; narrow only to preserve evidence boundaries and avoid overstated claims.
+- Do not ask the user to approve each evidence binding. Ask only when binding would change strategic meaning, downgrade a central claim, rely on suspicious sources, or require narrative approval.
+- Do not store secrets, credentials, tokens, or sensitive personal information.
+
+Start now by reading ${DECKS_STATE_FILE} through \`revela-decks\`, reviewing current readiness, and running the first research/binding loop.`
+}

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 deck --review\`.
+- Do not call \`revela-decks\` action \`review\` here. That action is the deck/artifact gate and belongs to \`/revela make deck --review\`.
 - 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 deck --review\`.
+- Keep deck/artifact readiness separate. If the user wants to review slide-writing readiness, tell them to run \`/revela make deck --review\`.
 
 Rules:
 - Do not write or overwrite \`decks/*.html\` during narrative review.
@@ -73,12 +73,13 @@ export function buildDeckPrompt({
     ? `${DECKS_STATE_FILE} exists. Read it through the revela-decks tool.`
     : `${DECKS_STATE_FILE} does not exist yet. Do not invent a deck; initialize narrative state first with /revela init.`
 
-  return `Begin Revela deck render handoff.
+  return `Begin Revela deck plan handoff.
 
 Goal:
-- Treat this as the explicit transition from approved narrative state to deck render planning.
+- 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.
-- Do not write or overwrite \`decks/*.html\` until the narrative handoff and deck/artifact gate are both satisfied.
+- 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.
+- 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.
 
@@ -92,25 +93,61 @@ 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. Ask for or confirm visual design only after the narrative deck plan exists. Fetch required design layouts/components with \`revela-designs read\` as needed.
-7. 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.
-8. Call \`revela-decks\` action \`review\` as the artifact gate. It computes \`writeReadiness\` and review snapshots for deck HTML writing.
-9. Write \`decks/*.html\` only if the deck/artifact gate is ready and all deck HTML contract requirements can be satisfied. If not ready, report blockers and stop.
-
-Report format before any HTML write:
-- Start with \`Deck handoff: <status>\`.
+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.
+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.
+
+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.
+- 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:
+
+\`\`\`text
+Slide N: <title>
+
+Purpose:
+<one sentence>
+
+Layout sketch:
+┌──────────────────────────────────────────────┐
+│ Headline                                     │
+├──────────────────────┬───────────────────────┤
+│ Main chart/media     │ Evidence boxes         │
+│                      │ Source/caveat note     │
+└──────────────────────┴───────────────────────┘
+
+Layout:
+Components:
+Primary claim:
+Supporting claims:
+Evidence bindings:
+Caveats / unsupported scope:
+\`\`\`
+- End by asking the user to confirm the deck plan or request changes.
+
+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.
 - If deck/artifact review is blocked, list blockers separately from narrative blockers.
-- If proceeding to HTML writing, state which approved narrative hash and deck review snapshot authorized the artifact work.
+- 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.
 - 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.
 - Do not store secrets, credentials, tokens, or sensitive personal information.
+- Artifact QA requires each slide to render exactly 1920x1080px, not merely any 16:9 ratio. It also checks component compliance, text overflow/clipping, page scrollbars, and whether normal QA-enabled content slides have enough claim/evidence/source substance.
 
-Start now by reading ${DECKS_STATE_FILE}, reviewing narrative readiness, and then compiling the deck plan only if approval or explicit render override is current.`
+Start now by reading ${DECKS_STATE_FILE}, reviewing narrative readiness, compiling the deck plan only if approval or explicit render override is current, then showing the deck plan with low-fidelity layout sketches and stopping for user confirmation.`
 }
 
 export function buildDeckReviewPrompt({
@@ -128,7 +165,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 is reviewed by \`/revela review\`.
+- Treat this as an artifact gate for deck rendering, not strategic narrative approval. Narrative readiness reports are reviewed by \`/revela review\`.
 - 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.