@cyber-dash-tech/revela 0.15.0 → 0.15.1

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/help.ts

@@ -28,7 +28,7 @@ export async function handleHelp(
     `\`/revela disable\`             — disable ambient Revela mode\n` +
     `\`/revela init\`                — initialize or refresh workspace DECKS.json\n` +
     `\`/revela research\`            — research, bind evidence, and reduce story gaps\n` +
-    `\`/revela story\`               — open the read-only story workspace UI\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` +
@@ -37,7 +37,6 @@ export async function handleHelp(
     `\`/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` +

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/review.ts

@@ -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({

package/lib/decks-state.ts

@@ -18,6 +18,7 @@ import {
 } from "./workspace-state/review-snapshots"
 import { WORKSPACE_STATE_FILE, type RenderTarget, type ReviewSnapshot, type WorkspaceAction } from "./workspace-state/types"
 import { normalizeCanonicalNarrativeState, normalizeNarrativeState } from "./narrative-state/normalize"
+import { computeNarrativeHash } from "./narrative-state/hash"
 import type { NarrativeStateV1 } from "./narrative-state/types"
 
 export const DECKS_STATE_FILE = WORKSPACE_STATE_FILE
@@ -91,6 +92,7 @@ export interface DeckSpec {
   researchPlan: ResearchAxis[]
   slides: SlideSpec[]
   assets: DeckAsset[]
+  planReview?: DeckPlanReview
   writeReadiness: {
     status: WriteReadinessStatus
     blockers: string[]
@@ -98,6 +100,15 @@ export interface DeckSpec {
   }
 }
 
+export interface DeckPlanReview {
+  status: "pending" | "confirmed"
+  narrativeHash: string
+  planHash: string
+  confirmedAt?: string
+  confirmedBy?: "user"
+  summary?: string
+}
+
 export interface NarrativeBrief {
   audienceBeliefBefore?: string
   audienceBeliefAfter?: string
@@ -202,6 +213,7 @@ export type ReadinessSeverity = "blocker" | "warning"
 export type ReadinessIssueType =
   | "missing_required_input"
   | "missing_slide_spec"
+  | "slide_plan_unconfirmed"
   | "research_not_ready"
   | "missing_evidence"
   | "weak_evidence"
@@ -278,6 +290,22 @@ const SOURCE_TRACE_ACTION = "Add slide evidence with source plus source trace su
 
 export interface ReviewDeckStateOptions {
   workspaceRoot?: string
+  narrativeHash?: string
+}
+
+export interface ConfirmDeckPlanOptions {
+  approvedBy?: "user"
+  note?: string
+  now?: string
+}
+
+export interface ConfirmDeckPlanResult {
+  confirmed: boolean
+  skipped: boolean
+  reason?: string
+  slug?: string
+  narrativeHash?: string
+  planHash?: string
 }
 
 export function decksStatePath(workspaceRoot: string): string {
@@ -357,10 +385,74 @@ export function createDeckSpec(input: Partial<DeckSpec> & { slug: string }): Dec
     researchPlan: input.researchPlan ?? [],
     slides: normalizeSlides(input.slides ?? []),
     assets: input.assets ?? [],
+    planReview: normalizeDeckPlanReview(input.planReview),
     writeReadiness: input.writeReadiness ?? { status: "blocked", blockers: [] },
   }
 }
 
+export function deckPlanHash(slides: SlideSpec[]): string {
+  return createHash("sha1")
+    .update(JSON.stringify(normalizeSlides(slides).map((slide) => ({
+      index: slide.index,
+      title: slide.title,
+      purpose: slide.purpose,
+      narrativeRole: slide.narrativeRole,
+      layout: slide.layout,
+      components: slide.components,
+      claimIds: slide.claimIds ?? [],
+      claimRefs: slide.claimRefs ?? [],
+      evidenceBindingIds: slide.evidenceBindingIds ?? [],
+      content: slide.content,
+      evidence: slide.evidence,
+      visuals: slide.visuals ?? [],
+    }))))
+    .digest("hex")
+}
+
+export function currentDeckPlanReviewStatus(deck: DeckSpec, narrativeHash?: string): { current: boolean; stale: boolean; reason?: string; planHash: string } {
+  const planHash = deckPlanHash(deck.slides)
+  const review = deck.planReview
+  if (!review) return { current: false, stale: false, reason: "deck plan has not been shown and confirmed", planHash }
+  if (review.status !== "confirmed") return { current: false, stale: false, reason: "deck plan is pending user confirmation", planHash }
+  if (narrativeHash && review.narrativeHash !== narrativeHash) return { current: false, stale: true, reason: "deck plan confirmation is stale because the narrative hash changed", planHash }
+  if (review.planHash !== planHash) return { current: false, stale: true, reason: "deck plan confirmation is stale because the slide plan changed", planHash }
+  return { current: true, stale: false, planHash }
+}
+
+export function confirmDeckPlan(state: DecksState, options: ConfirmDeckPlanOptions = {}): { state: DecksState; result: ConfirmDeckPlanResult } {
+  const normalized = normalizeDecksStateWithNarrative(state)
+  const key = currentDeckKey(normalized)
+  const deck = key ? normalized.decks[key] : undefined
+  if (!deck) {
+    return { state: normalized, result: { confirmed: false, skipped: true, reason: `No active deck exists in ${DECKS_STATE_FILE}.` } }
+  }
+  if (deck.slides.length === 0) {
+    return { state: normalized, result: { confirmed: false, skipped: true, slug: deck.slug, reason: "Cannot confirm a deck plan with no slides." } }
+  }
+  const narrative = normalizeNarrativeState(normalized)
+  const narrativeHash = computeNarrativeHash(narrative)
+  const planHash = deckPlanHash(deck.slides)
+  const pending = deck.planReview
+  if (pending && pending.status === "pending" && (pending.narrativeHash !== narrativeHash || pending.planHash !== planHash)) {
+    return { state: normalized, result: { confirmed: false, skipped: true, slug: deck.slug, narrativeHash, planHash, reason: "Cannot confirm because the pending deck plan is stale. Re-run compileDeckPlan first." } }
+  }
+
+  deck.planReview = {
+    status: "confirmed",
+    narrativeHash,
+    planHash,
+    confirmedAt: options.now ?? new Date().toISOString(),
+    confirmedBy: options.approvedBy ?? "user",
+    summary: cleanOptionalText(options.note),
+  }
+  deck.requiredInputs = { ...deck.requiredInputs, slidePlanConfirmed: true }
+  deck.writeReadiness = { status: "blocked", blockers: [] }
+  normalized.decks[deck.slug] = deck
+  normalized.activeDeck = deck.slug
+  normalized.narrative = narrative
+  return { state: normalized, result: { confirmed: true, skipped: false, slug: deck.slug, narrativeHash, planHash } }
+}
+
 export function readDecksState(workspaceRoot: string): DecksState {
   return readWorkspaceState(workspaceRoot, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative })
 }
@@ -487,7 +579,10 @@ export function reviewDeckState(state: DecksState, slug?: string, options: Revie
     }
   }
 
-  const issues = computeDeckReadinessIssues(deck, normalized.workspace, options)
+  const issues = computeDeckReadinessIssues(deck, normalized.workspace, {
+    ...options,
+    narrativeHash: options.narrativeHash ?? computeNarrativeHash(normalizeNarrativeState(normalized)),
+  })
   const blockers = issues.filter((issue) => issue.severity === "blocker").map((issue) => issue.message)
   const warnings = issues.filter((issue) => issue.severity === "warning").map((issue) => issue.message)
   const evidenceCandidates = issues.flatMap((issue) => issue.evidenceCandidates ?? [])
@@ -544,7 +639,9 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
     }
   }
 
-  const issues = computeDeckReadinessIssues(deck, normalized.workspace)
+  const issues = computeDeckReadinessIssues(deck, normalized.workspace, {
+    narrativeHash: computeNarrativeHash(normalizeNarrativeState(normalized)),
+  })
   const blockers = issues.filter((issue) => issue.severity === "blocker").map((issue) => issue.message)
   const warnings = issues.filter((issue) => issue.severity === "warning").map((issue) => issue.message)
   if (normalizeDeckPath(deck.outputPath) !== targetPath) {
@@ -651,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. When review snapshots exist, deck HTML writes require a current non-stale ready review snapshot for the active HTML render target.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- Before writing decks/*.html, the current deck must have writeReadiness.status=ready and a complete slide spec, and its outputPath must match the target file.`
+  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"] {
@@ -765,6 +862,18 @@ function normalizeDecksStateWithNarrative(input: DecksState): DecksState {
   return state
 }
 
+function normalizeDeckPlanReview(input: DeckPlanReview | undefined): DeckPlanReview | undefined {
+  if (!input || !input.narrativeHash || !input.planHash) return undefined
+  return {
+    status: input.status === "confirmed" ? "confirmed" : "pending",
+    narrativeHash: input.narrativeHash,
+    planHash: input.planHash,
+    confirmedAt: cleanOptionalText(input.confirmedAt),
+    confirmedBy: input.confirmedBy === "user" ? "user" : undefined,
+    summary: cleanOptionalText(input.summary),
+  }
+}
+
 function currentDeckKey(state: DecksState): string | undefined {
   if (state.activeDeck && state.decks[state.activeDeck]) return state.activeDeck
   const keys = Object.keys(state.decks)
@@ -800,6 +909,16 @@ function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["works
   }
 
   if (deck.slides.length === 0) issues.push(blockerIssue("missing_slide_spec", "slides are missing", "Add the confirmed slide plan through revela-decks upsertSlides."))
+  if (deck.slides.length > 0) {
+    const planReview = currentDeckPlanReviewStatus(deck, options.narrativeHash)
+    if (!planReview.current) {
+      issues.push(blockerIssue(
+        "slide_plan_unconfirmed",
+        planReview.stale ? `Deck slide plan confirmation is stale: ${planReview.reason}` : `Deck slide plan is not confirmed: ${planReview.reason}`,
+        "Show the compiled deck plan with low-fidelity layout sketches to the user, then call revela-decks confirmDeckPlan only after explicit user confirmation.",
+      ))
+    }
+  }
   for (const slide of deck.slides) {
     const slideRef = { slideIndex: slide.index, slideTitle: slide.title }
     if (!slide.title.trim()) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} title is missing`, "Add a slide title to the slide spec.", slideRef))

package/lib/design/designs.ts

@@ -642,7 +642,6 @@ const UNIVERSAL_CLASSES = new Set([
   "slide-canvas",
   "visible",
   "reveal",
-  "editable",
   "page",
   "bg",
   "fg",
@@ -655,7 +654,7 @@ const UNIVERSAL_CLASSES = new Set([
  * CSS class prefixes that are always exempt from compliance checks.
  * Third-party libraries (icons, charts) generate classes with these prefixes.
  */
-export const DEFAULT_PREFIX_EXEMPTIONS: string[] = ["lucide-", "echarts-", "editable-"]
+export const DEFAULT_PREFIX_EXEMPTIONS: string[] = ["lucide-", "echarts-"]
 
 export interface DesignClassVocabulary {
   /** Complete set of allowed CSS class names. */

package/lib/edit/prompt.ts

@@ -72,14 +72,15 @@ Instructions:
 - If there are multiple comments, apply them as one coherent edit pass and avoid changes from one comment overwriting another.
 - Each comment may reference one or more selected elements. Treat the elements in a single comment as a group.
 - Preserve the narrative boundary: if the requested edit changes audience framing, belief shift, decision/action, thesis, recommendation, claim wording, evidence scope, caveat, risk, objection, or decision ask, do not patch the HTML directly. Explain that the canonical narrative must be updated first through ${"`revela-decks`"} action ${"`upsertNarrative`"}, then reviewed/approved or explicitly overridden before updating the deck projection.
-- Pure artifact polish such as layout, spacing, typography, alignment, color, image crop, animation, export fidelity, or deck HTML contract fixes may remain an artifact-level edit.
+- Pure artifact polish such as layout, spacing, typography, alignment, color, image crop, animation, export fidelity, runtime JavaScript fixes, or deck HTML contract fixes may remain an artifact-level edit.
 - If the request mixes content meaning and visual polish, treat it as narrative-impacting unless the user clarifies otherwise.
 - Preserve the existing deck structure, active design language, typography, spacing system, animations, and slide count unless the comment explicitly asks otherwise.
 - Do not rewrite unrelated slides or broad sections of the deck.
 - Locate each target primarily with slideIndex, slideTitle, selected text, nearbyText, and outerHTMLExcerpt. Use selector/domPath as hints; they may be approximate.
-- Before patching or writing ${"`decks/*.html`"}, ensure ${"`DECKS.json`"} contains this deck and call ${"`revela-decks`"} with action ${"`review`"}. If ${"`DECKS.json`"} or the deck entry is missing, initialize/upsert the deck state with ${"`revela-decks`"} first. If readiness remains blocked, explain the blockers instead of forcing the edit.
-- Apply the edit to ${payload.file} only after readiness allows deck HTML changes.
-- Static design compliance is checked automatically after deck writes. If the tool result reports unknown classes, replace them with classes from the active design.
-- Do not run QA after the edit unless the user explicitly asks for diagnostics. PDF/PPTX export commands run hard-error pre-export QA automatically.
+- For targeted artifact-level edits, patch ${"`decks/*.html`"} directly. Do not call ${"`revela-decks`"} action ${"`review`"} as a precondition, and do not let ${"`writeReadiness`"}, ${"`planReview`"}, or ${"`slide_plan_unconfirmed`"} block the patch.
+- Do not patch or write ${"`DECKS.json`"} directly. If state must change, use the ${"`revela-decks`"} tool.
+- Apply the edit to ${payload.file} with the smallest targeted HTML patch that satisfies the comment.
+- Artifact QA runs automatically after deck writes/patches/edits. It checks deck HTML contract, design component compliance, exact 1920x1080 slide geometry, scrollbars, element overflow, text clipping, and claim/evidence content-density warnings.
+- If the tool result reports hard QA errors, fix them with the smallest targeted patch and let the post-write QA run again. Refine opens automatically only after hard errors pass; warnings such as thin claim/evidence substance do not block opening.
 - If the comment is ambiguous, ask one concise clarification question instead of guessing.`
 }

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 edit no longer accepts a target. It opens the only HTML deck in decks/.")
+    throw new Error("/revela refine does not accept a target. It opens the active HTML deck or the only HTML deck in decks/.")
   }
 
   if (hasDecksState(workspaceRoot)) {

package/lib/narrative-state/render-plan.ts

@@ -1,4 +1,4 @@
-import { upsertDeck, upsertSlides, type DecksState, type EvidenceRef, type RequiredInputs, type SlideSpec } from "../decks-state"
+import { deckPlanHash, upsertDeck, upsertSlides, type DecksState, type EvidenceRef, type RequiredInputs, type SlideSpec } from "../decks-state"
 import { ensureActiveHtmlDeckRenderTarget } from "../workspace-state/render-targets"
 import { getClaimSlideRefs } from "./queries"
 import { computeNarrativeHash } from "./hash"
@@ -65,6 +65,15 @@ export function compileDeckPlanFromNarrative(state: DecksState, options: Compile
     writeReadiness: deck?.writeReadiness ?? { status: "blocked" as const, blockers: [] },
   })
   next = upsertSlides(next, slug, slides)
+  const plannedDeck = next.decks[slug]
+  plannedDeck.planReview = {
+    status: "pending",
+    narrativeHash,
+    planHash: deckPlanHash(plannedDeck.slides),
+  }
+  plannedDeck.requiredInputs = { ...plannedDeck.requiredInputs, slidePlanConfirmed: false }
+  plannedDeck.writeReadiness = { status: "blocked", blockers: [] }
+  next.decks[slug] = plannedDeck
   next.narrative = { ...narrative, updatedAt: options.now ?? narrative.updatedAt }
   const htmlTarget = ensureActiveHtmlDeckRenderTarget(next)
   if (htmlTarget) {

package/lib/qa/artifact.ts

@@ -0,0 +1,77 @@
+import { formatDeckHtmlContractReport, validateDeckHtmlContract } from "../deck-html/contract"
+import type { DesignClassVocabulary } from "../design/designs"
+import { formatReport, runQA } from "./index"
+import { runComplianceQA } from "./compliance"
+import type { QAReport } from "./checks"
+
+export interface ArtifactQAReport {
+  file: string
+  passed: boolean
+  hardErrorCount: number
+  warningCount: number
+  sections: string[]
+}
+
+function hardErrors(report: QAReport): number {
+  return report.slides.reduce((sum, slide) => sum + slide.issues.filter((issue) => issue.severity === "error").length, 0)
+}
+
+function warnings(report: QAReport): number {
+  return report.slides.reduce((sum, slide) => sum + slide.issues.filter((issue) => issue.severity === "warning").length, 0)
+}
+
+export async function runArtifactQA(input: {
+  workspaceRoot: string
+  filePath: string
+  vocabulary?: DesignClassVocabulary
+}): Promise<ArtifactQAReport> {
+  const sections: string[] = []
+  let hardErrorCount = 0
+  let warningCount = 0
+
+  const contract = validateDeckHtmlContract(input.workspaceRoot, input.filePath)
+  if (contract.status === "invalid") {
+    hardErrorCount += contract.issues.filter((issue) => issue.severity === "error").length
+    warningCount += contract.warnings.length
+    sections.push("**[deck HTML contract]**\n\n" + formatDeckHtmlContractReport(contract))
+  } else if (contract.warnings.length > 0) {
+    warningCount += contract.warnings.length
+    sections.push("**[deck HTML contract]**\n\n" + formatDeckHtmlContractReport(contract))
+  }
+
+  const compliance = runComplianceQA(input.filePath, input.vocabulary)
+  const complianceErrors = hardErrors(compliance)
+  if (compliance.totalIssues > 0) {
+    hardErrorCount += complianceErrors
+    warningCount += warnings(compliance)
+    sections.push("**[component compliance]**\n\n" + formatReport(compliance))
+  }
+
+  try {
+    const browser = await runQA(input.filePath)
+    const browserErrors = hardErrors(browser)
+    if (browser.totalIssues > 0) {
+      hardErrorCount += browserErrors
+      warningCount += warnings(browser)
+      sections.push("**[browser artifact QA]**\n\n" + formatReport(browser))
+    }
+  } catch (e) {
+    hardErrorCount += 1
+    sections.push("**[browser artifact QA]**\n\nError running browser QA: " + (e instanceof Error ? e.message : String(e)))
+  }
+
+  return {
+    file: input.filePath,
+    passed: hardErrorCount === 0,
+    hardErrorCount,
+    warningCount,
+    sections,
+  }
+}
+
+export function formatArtifactQAReport(report: ArtifactQAReport): string {
+  const heading = report.passed ? "Artifact QA: PASSED" : "Artifact QA: FAILED"
+  const summary = `**File:** \`${report.file}\`\n\n**Hard errors:** ${report.hardErrorCount}\n**Warnings:** ${report.warningCount}`
+  if (report.sections.length === 0) return `## ${heading}\n\n${summary}\n\nAll artifact QA checks passed.`
+  return `## ${heading}\n\n${summary}\n\n${report.sections.join("\n\n---\n\n")}`
+}