@cyber-dash-tech/revela 0.15.0 → 0.15.2

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

@@ -24,6 +24,8 @@ export interface EditCommentPayload extends EditSelectedElementPayload {
   comment: string
   elements?: EditSelectedElementPayload[]
   comments?: EditCommentDraftPayload[]
+  asset?: Record<string, unknown>
+  drop?: Record<string, unknown>
 }
 
 export function buildEditPrompt(payload: EditCommentPayload): string {
@@ -54,6 +56,8 @@ export function buildEditPrompt(payload: EditCommentPayload): string {
     deck: payload.deck,
     file: payload.file,
     comments,
+    asset: payload.asset,
+    drop: payload.drop,
   }
 
   return `The user left a visual edit comment on a Revela slide deck.
@@ -72,14 +76,23 @@ 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.
+- If an asset/drop payload is present, this is an asset placement request. Use only the saved local asset path from the asset payload in deck HTML. Prefer asset.deckPath when present because it is relative to the target HTML file; otherwise use asset.path.
+- Do not write remote imageUrl, thumbnailUrl, source page URLs, or ${"`/__revela_asset`"} proxy URLs into deck HTML.
+- Logo assets should remain small, clear, and brand-like; do not use logos as decorative backgrounds.
+- Photography can be cropped or masked when appropriate, but must not cover text, charts, tables, evidence, or important claims.
+- Screenshots, diagrams, charts, tables, and evidence images must remain readable and should not be converted into decorative hero imagery.
+- For asset targetMode ${"`replace`"}, prefer replacing the targeted image or visual element. For ${"`insert-into`"}, place the asset inside the targeted card, media box, or semantic container while preserving that element's layout role. For ${"`add`"}, place the asset near the drop coordinates within the existing layout or semantic box. Do not invent a new visual system when the existing deck grammar can express the placement.
+- If an asset payload is present without drop coordinates, use the user's comment and selected element context to choose placement; if placement remains ambiguous, ask one concise clarification question instead of guessing.
+- Preserve source/license/attribution facts if you surface them in visible notes; do not invent missing licensing or attribution.
 - 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/inspect/prompt.ts

@@ -5,21 +5,25 @@ export function buildInspectionPrompt(input: {
   file: string
   projection: InspectionPromptProjection
   language?: string
+  comment?: string
 }): string {
   const language = normalizeInspectLanguage(input.language)
+  const comment = typeof input.comment === "string" && input.comment.trim() ? input.comment.trim() : ""
   return `A user selected slide content in Revela Evidence Inspector. The selection may contain one referenced element, a whole slide, or multiple referenced elements selected with Cmd/Ctrl-click.
 
 Target file: ${input.file}
 Inspection request id: ${input.requestId}
 Display language: ${language}
+User inspect comment: ${comment || "(none; explain purpose and source only)"}
 
-Use the structured projection below to produce the final inspector cards. This is LLM judgment with grounded boundaries: explain the selected object's narrative reading context, bounded exploratory reading context, purpose, and source credibility only. Do not edit files. Do not mutate DECKS.json. Do not invent claim ids, evidence binding ids, sources, quotes, URLs, page references, caveats, objections, risks, artifact coverage, or evidence not present in the projection.
+Use the structured projection below to produce the final inspector cards. This is LLM judgment with grounded boundaries. The user's inspect comment is the complete request about the selected reference; do not parse it into a separate question field. The user primarily wants to understand the selected component: what purpose it serves and what source support exists. Use narrative reading and exploratory reading only as internal grounding unless needed to answer the user's comment. Do not edit files. Do not mutate DECKS.json. Do not invent claim ids, evidence binding ids, sources, quotes, URLs, page references, caveats, objections, risks, artifact coverage, or evidence not present in the projection.
 
 Language boundary: the selected display language affects only human-readable card copy. Preserve all claim ids, canonical claim ids, evidence binding ids, source paths, findings files, URLs, numbers, quoted/source facts, caveats, artifact ids, and coverage statuses exactly as grounded in the projection. If the display language is Auto, use projection.deck.language when available; otherwise follow the user's/browser context or default to English.
 
 Return the result only by calling the \`revela-inspection-result\` tool with this request id. Do not answer in chat.
 
 Required card model:
+- User inspect comment: if present, answer it through the Purpose and Source cards first. If it asks about trust, provenance, evidence, factuality, or where a number came from, prioritize Source. If it asks why something is on the slide or what it is doing, prioritize Purpose.
 - Narrative Reading: when the projection includes a matched claim, preserve its claim id, canonical claim id, evidence binding ids, supported scope, unsupported scope, caveats, related objections, related risks, and artifact coverage. Artifact coverage must come only from projection.cards.artifacts; do not invent where a claim appears or whether an artifact is stale/current/partial/missing. If canonical narrative linkage is missing, say so and fall back to the matched slide claim; do not invent canonical ids.
 - Candidate boundary: when projection.match.claim is absent but projection.match.candidateClaims is present, explain the selected child element only within those candidate claim boundaries. You may describe that the child element functions as a detail, prerequisite, source note, risk cue, or evidence cue inside the slide, but you must not select one candidate claim id by semantic guess. If projection.match.confidence is none or candidateClaims is empty, explain the mapping gap instead of inventing a plausible claim.
 - Exploratory Reading: provide bounded, non-official reading cues for objection prep, audience reframing, appendix leads, and meeting prep only from the projection. Mark official as false. Keep missing evidence, caveats, unsupported scope, and stale artifacts visible. Do not make exploratory text sound like approved artifact content, and do not turn this into chat or a fix plan.
@@ -29,6 +33,7 @@ Required card model:
 Boundaries:
 - Do not hunt for problems. If it works, say it works.
 - Do not recommend edits or fixes; this inspector view only explains narrative context, bounded exploratory reading context, purpose, and source credibility.
+- Keep Purpose and Source concise and directly useful. Avoid long narrative-reading exposition unless the selected content cannot be explained without it.
 - Do not turn every caveat into a problem.
 - If confidence is low, use unclear or unknown instead of pretending certainty.
 

package/lib/media/download.ts

@@ -3,11 +3,15 @@ import { extname } from "path"
 const MIME_TO_EXT: Record<string, string> = {
   "image/png": ".png",
   "image/jpeg": ".jpg",
+  "image/svg+xml": ".svg",
   "image/webp": ".webp",
   "image/gif": ".gif",
+  "image/x-icon": ".ico",
+  "image/vnd.microsoft.icon": ".ico",
 }
 
-const ALLOWED_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif"])
+const ALLOWED_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".svg", ".webp", ".gif", ".ico"])
+const DEFAULT_DOWNLOAD_TIMEOUT_MS = 10_000
 
 function normalizeExtension(ext: string): string {
   const value = ext.toLowerCase()
@@ -30,6 +34,7 @@ export function inferImageExtension(contentType: string | null, sourceName = "")
 
 export async function downloadImageFromUrl(
   url: string,
+  options: { timeoutMs?: number } = {},
 ): Promise<{ buffer: Buffer; contentType: string | null; extension: string }> {
   let parsed: URL
   try {
@@ -42,16 +47,36 @@ export async function downloadImageFromUrl(
     throw new Error("INVALID_URL")
   }
 
-  const response = await fetch(parsed, {
-    headers: {
-      "User-Agent":
-        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
-        "(KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
-    },
-  })
+  const controller = new AbortController()
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    controller.abort()
+  }, Math.max(1, options.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS))
 
-  if (!response.ok) {
-    throw new Error(`DOWNLOAD_FAILED:${response.status}`)
+  let response: Response
+  let buffer: Buffer
+  try {
+    response = await fetch(parsed, {
+      headers: {
+        Accept: "image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8",
+        "User-Agent":
+          "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+          "(KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
+      },
+      signal: controller.signal,
+    })
+
+    if (!response.ok) {
+      throw new Error(`DOWNLOAD_FAILED:${response.status}`)
+    }
+
+    buffer = Buffer.from(await response.arrayBuffer())
+  } catch (error) {
+    if (timedOut) throw new Error("DOWNLOAD_TIMEOUT")
+    throw error
+  } finally {
+    clearTimeout(timer)
   }
 
   const contentType = response.headers.get("content-type")
@@ -61,7 +86,7 @@ export async function downloadImageFromUrl(
   }
 
   return {
-    buffer: Buffer.from(await response.arrayBuffer()),
+    buffer,
     contentType,
     extension,
   }

package/lib/media/save.ts

@@ -69,6 +69,12 @@ function buildFailureRecord(
     alt: input.alt,
     notes: input.notes,
     failureReason,
+    provider: input.provider,
+    sourcePageUrl: input.sourcePageUrl,
+    license: input.license,
+    attribution: input.attribution,
+    width: input.width,
+    height: input.height,
     savedAt: nowIso(),
   }
 }
@@ -112,6 +118,12 @@ function saveFailureResult(
       sourcePath: sourcePath ?? existing.sourcePath,
       alt: input.alt ?? existing.alt,
       notes: input.notes ?? existing.notes,
+      provider: input.provider ?? existing.provider,
+      sourcePageUrl: input.sourcePageUrl ?? existing.sourcePageUrl,
+      license: input.license ?? existing.license,
+      attribution: input.attribution ?? existing.attribution,
+      width: input.width ?? existing.width,
+      height: input.height ?? existing.height,
       failureReason,
     }
     : buildFailureRecord(input, topic, status, failureReason, sourcePath)
@@ -196,6 +208,12 @@ export async function saveMediaAsset(input: MediaSaveInput, workspaceDir: string
         intendedSection: input.intendedSection,
         alt: input.alt,
         notes: input.notes,
+        provider: input.provider,
+        sourcePageUrl: input.sourcePageUrl,
+        license: input.license,
+        attribution: input.attribution,
+        width: input.width,
+        height: input.height,
         savedAt: nowIso(),
       }
       const { manifest: nextManifest } = upsertAsset(manifest, record)
@@ -248,6 +266,12 @@ export async function saveMediaAsset(input: MediaSaveInput, workspaceDir: string
       intendedSection: input.intendedSection,
       alt: input.alt,
       notes: input.notes,
+      provider: input.provider,
+      sourcePageUrl: input.sourcePageUrl,
+      license: input.license,
+      attribution: input.attribution,
+      width: input.width,
+      height: input.height,
       savedAt: nowIso(),
     }
     const { manifest: nextManifest } = upsertAsset(manifest, record)