@cyber-dash-tech/revela 0.17.0 → 0.17.2

package/lib/decks-state.ts

@@ -328,6 +328,8 @@ export interface ConfirmDeckPlanOptions {
   approvedBy?: "user"
   note?: string
   now?: string
+  approvedAt?: string
+  planHash?: string
 }
 
 export interface ConfirmDeckPlanResult {
@@ -441,12 +443,12 @@ export function deckPlanHash(slides: SlideSpec[]): string {
 }
 
 export function currentDeckPlanReviewStatus(deck: DeckSpec, narrativeHash?: string): { current: boolean; stale: boolean; reason?: string; planHash: string } {
-  const planHash = deckPlanHash(deck.slides)
   const review = deck.planReview
+  const planHash = deck.slides.length > 0 ? deckPlanHash(deck.slides) : review?.planHash ?? deckPlanHash(deck.slides)
   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 }
+  if (deck.slides.length > 0 && review.planHash !== planHash) return { current: false, stale: true, reason: "deck plan confirmation is stale because the cached slide projection changed", planHash }
   return { current: true, stale: false, planHash }
 }
 
@@ -457,14 +459,14 @@ export function confirmDeckPlan(state: DecksState, options: ConfirmDeckPlanOptio
   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 planHash = options.planHash ?? deckPlanHash(deck.slides)
   const pending = deck.planReview
-  if (pending && pending.status === "pending" && (pending.narrativeHash !== narrativeHash || pending.planHash !== planHash)) {
+  if (pending && pending.status === "pending" && pending.narrativeHash !== narrativeHash) {
+    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." } }
+  }
+  if (!options.planHash && pending && pending.status === "pending" && 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." } }
   }
 
@@ -472,7 +474,7 @@ export function confirmDeckPlan(state: DecksState, options: ConfirmDeckPlanOptio
     status: "confirmed",
     narrativeHash,
     planHash,
-    confirmedAt: options.now ?? new Date().toISOString(),
+    confirmedAt: options.approvedAt ?? options.now ?? new Date().toISOString(),
     confirmedBy: options.approvedBy ?? "user",
     summary: cleanOptionalText(options.note),
     qualityChecks: pending?.qualityChecks,
@@ -676,20 +678,32 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
   const targetPath = normalizeDeckPath(filePath)
   const targetSlug = deckSlugFromPath(targetPath)
   const normalized = normalizeDecksState(state)
+  if (!isDeckHtmlPath(targetPath)) {
+    const message = `Deck HTML writes must target decks/*.html, got ${filePath || "missing"}`
+    return {
+      ready: false,
+      slug: targetSlug,
+      blocker: message,
+      blockers: [message],
+      warnings: [],
+      issues: [blockerIssue("missing_slide_spec", message, "Write deck artifacts to a workspace-local decks/*.html path.")],
+    }
+  }
   const key = currentDeckKey(normalized)
   const deck = key ? normalized.decks[key] : undefined
   if (!deck) {
+    const warning = currentDeckBlocker(normalized)
     return {
-      ready: false,
+      ready: true,
       slug: targetSlug,
-      blocker: currentDeckBlocker(normalized),
-      blockers: [currentDeckBlocker(normalized)],
-      warnings: [],
+      blocker: "",
+      blockers: [],
+      warnings: [warning],
       issues: [{
         type: "missing_slide_spec",
-        severity: "blocker",
-        message: currentDeckBlocker(normalized),
-        suggestedAction: "Create or select the current workspace deck through revela-decks before writing deck HTML.",
+        severity: "warning",
+        message: warning,
+        suggestedAction: "Proceed from the file-native deck-plan/ projection or explicit user request; DECKS.json deck records are not required for artifact writing.",
       }],
     }
   }
@@ -701,32 +715,12 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
   const warnings = issues.filter((issue) => issue.severity === "warning").map((issue) => issue.message)
   if (normalizeDeckPath(deck.outputPath) !== targetPath) {
     const message = `Deck outputPath is ${deck.outputPath || "missing"}, not ${targetPath}`
-    blockers.unshift(message)
+    warnings.unshift(message)
     issues.unshift({
       type: "missing_slide_spec",
-      severity: "blocker",
+      severity: "warning",
       message,
-      suggestedAction: "Update deck.outputPath through revela-decks or write to the reviewed outputPath.",
-    })
-  }
-  if (deck.writeReadiness.status !== "ready") {
-    const message = `Deck writeReadiness is ${deck.writeReadiness.status || "missing"}, not ready`
-    blockers.unshift(message)
-    issues.unshift({
-      type: "missing_slide_spec",
-      severity: "blocker",
-      message,
-      suggestedAction: "Run /revela make --deck and resolve all readiness blockers before writing deck HTML.",
-    })
-  }
-  if (deck.writeReadiness.blockers.length > 0) {
-    const message = `Deck still has readiness blockers: ${deck.writeReadiness.blockers.join("; ")}`
-    blockers.unshift(message)
-    issues.unshift({
-      type: "missing_slide_spec",
-      severity: "blocker",
-      message,
-      suggestedAction: "Resolve the stored writeReadiness blockers and rerun /revela make --deck.",
+      suggestedAction: "Treat cached deck outputPath as diagnostic only; use the explicit artifact path requested by the user.",
     })
   }
   if (normalized.reviews.length > 0) {
@@ -734,30 +728,30 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
     const snapshot = latestReviewSnapshotForTarget(normalized, targetId)
     if (!snapshot) {
       const message = "No review snapshot exists for the active HTML render target"
-      blockers.unshift(message)
+      warnings.unshift(message)
       issues.unshift({
         type: "missing_slide_spec",
-        severity: "blocker",
+        severity: "warning",
         message,
-        suggestedAction: "Run /revela make --deck so readiness is recorded against the current active render target.",
+        suggestedAction: "Review snapshots are diagnostic only; proceed if the user explicitly requested this artifact path and HTML contract checks pass.",
       })
     } else if (!isReviewSnapshotCurrent(normalized, snapshot, deck.slug)) {
       const message = "Latest review snapshot is stale for the current deck, sources, evidence, narrative state, or render target"
-      blockers.unshift(message)
+      warnings.unshift(message)
       issues.unshift({
         type: "missing_slide_spec",
-        severity: "blocker",
+        severity: "warning",
         message,
-        suggestedAction: "Run /revela make --deck again after the latest state changes before writing deck HTML.",
+        suggestedAction: "Treat stale review snapshots as diagnostics; user decides whether to continue or refresh.",
       })
     } else if (snapshot.status !== "ready") {
       const message = `Latest review snapshot is ${snapshot.status}, not ready`
-      blockers.unshift(message)
+      warnings.unshift(message)
       issues.unshift({
         type: "missing_slide_spec",
-        severity: "blocker",
+        severity: "warning",
         message,
-        suggestedAction: "Resolve review blockers and rerun /revela make --deck before writing deck HTML.",
+        suggestedAction: "Treat prior review status as diagnostic only; current artifact validity checks decide whether writing can proceed.",
       })
     }
   }
@@ -804,7 +798,7 @@ export function buildDecksStatePromptLayer(workspaceRoot: string, maxChars = 140
   }
   let text = JSON.stringify(compact, null, 2)
   if (text.length > maxChars) text = text.slice(0, maxChars).trimEnd() + "\n[DECKS.json state truncated for prompt size.]"
-  return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as the source of truth for the single current deck's specs, slide plan, evidence, render targets, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- ${DECKS_STATE_FILE} deck slides use 1-based \`slides[].index\` values. Render every HTML \`<section class="slide">\` with a matching 1-based \`data-slide-index\` attribute, and do not use 0-based \`data-index\` as slide identity.\n- The active HTML deck is represented as a \`renderTarget\` of type \`html_deck\`; PDF/PPTX exports should be recorded as derived render targets, not as separate deck specs.\n- \`writeReadiness\` is a compatibility projection for the /revela make --deck generation workflow, not a hard blocker for targeted artifact-level HTML fixes.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- For /revela make --deck generated HTML, use the current deck's outputPath and satisfy the deck HTML contract. For targeted artifact-level edits, patch the requested deck HTML directly without treating \`writeReadiness\` or \`planReview\` as a precondition.`
+  return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as compatibility/render state: workspace context, active output path, render targets, reviews, readiness, provenance, artifact coverage, and cached projections.\n- Do not treat ${DECKS_STATE_FILE} \`slides[]\` as the authoritative HTML slide-count, slide-order, or slide-content contract. When \`deck-plan/\` exists, use \`deck-plan/index.md\` and \`deck-plan/slides/*.md\` as the deck execution blueprint for HTML generation/remake.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- HTML slide identity is artifact self-consistency: each \`<section class="slide">\` needs a positive 1-based \`data-slide-index\`, indexes must be unique and strictly increase in DOM order, and 0-based \`data-index\` is never canonical identity. Cached ${DECKS_STATE_FILE} \`slides[].index\` values are diagnostic context only.\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\` and \`planReview\` are compatibility projections for the /revela make --deck generation workflow, not hard blockers 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, read \`deck-plan/\` when present, and satisfy the deck HTML contract without padding missing chapters just to match cached ${DECKS_STATE_FILE} \`slides[]\`. Deck-plan diagnostics are advisory; 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"] {
@@ -969,52 +963,47 @@ function currentDeckBlocker(state: DecksState): string {
 function computeDeckReadinessIssues(state: DecksState, deck: DeckSpec, options: ReviewDeckStateOptions = {}): ReadinessIssue[] {
   const issues: ReadinessIssue[] = []
   const workspace = state.workspace
-  if (!deck.goal.trim()) issues.push(blockerIssue("missing_slide_spec", "Deck goal is missing", "Set the deck goal through revela-decks upsertDeck."))
+  if (!deck.goal.trim()) issues.push(warningIssue("missing_slide_spec", "Deck goal is missing", "Clarify the deck goal if it matters for this artifact pass; do not block execution solely on cached deck metadata."))
   if (!isDeckHtmlPath(deck.outputPath)) {
-    issues.push(blockerIssue(
+    issues.push(warningIssue(
       "missing_slide_spec",
       `outputPath must be decks/*.html, got ${deck.outputPath || "missing"}`,
-      "Set outputPath to the target decks/*.html file through revela-decks upsertDeck.",
+      "Resolve output path from the user request, deck-plan/index.md, or a deterministic decks/*.html default instead of treating cached state as permission.",
     ))
   }
 
   for (const [key, value] of Object.entries(deck.requiredInputs) as Array<[keyof RequiredInputs, boolean]>) {
-    if (value !== true) {
-      issues.push(blockerIssue(
-        "missing_required_input",
-        `requiredInputs.${key} is not true`,
-        `Complete and explicitly record requiredInputs.${key} before writing the deck.`,
-      ))
-    }
+    if (value !== true) issues.push(warningIssue(
+      "missing_required_input",
+      `Legacy requiredInputs.${key} is not true`,
+      "requiredInputs is legacy diagnostic/cache state only; ask the user for missing intent if needed, but do not block execution.",
+    ))
   }
 
-  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.",
-      ))
-    }
+  const planReview = currentDeckPlanReviewStatus(deck, options.narrativeHash)
+  if (!planReview.current) {
+    issues.push(warningIssue(
+      "slide_plan_unconfirmed",
+      planReview.stale ? `Deck plan confirmation is stale: ${planReview.reason}` : `Deck plan is not confirmed: ${planReview.reason}`,
+      "Write or read deck-plan/ projection Markdown if useful, then decide whether to continue. This is advisory and does not block artifact work.",
+    ))
   }
   issues.push(...deckPlanQualityIssues(deck))
   issues.push(...artifactCoverageIssues(state, deck))
   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))
-    if (!slide.layout.trim()) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} layout is missing`, "Fetch and record the intended design layout for this slide.", slideRef))
-    if (slide.components.length === 0) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} components are missing`, "Record the design components needed for this slide.", slideRef))
-    if (!hasSlideContent(slide)) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} content is missing`, "Add structured headline/body/bullets/data content to the slide spec.", slideRef))
+    if (!slide.title.trim()) issues.push(warningIssue("missing_slide_spec", `Cached slide ${slide.index} title is missing`, "Use deck-plan/ and artifact content as source for rendering; cached slide specs are diagnostics only.", slideRef))
+    if (!slide.layout.trim()) issues.push(warningIssue("missing_slide_spec", `Cached slide ${slide.index} layout is missing`, "Fetch needed design layouts before writing HTML, but do not block solely on cached slide specs.", slideRef))
+    if (slide.components.length === 0) issues.push(warningIssue("missing_slide_spec", `Cached slide ${slide.index} components are missing`, "Fetch needed design components before writing HTML, but do not block solely on cached slide specs.", slideRef))
+    if (!hasSlideContent(slide)) issues.push(warningIssue("missing_slide_spec", `Cached slide ${slide.index} content is missing`, "Use deck-plan/ and the artifact request as render guidance; cached slide specs are diagnostics only.", slideRef))
 
     const claim = findEvidenceSensitiveClaim(slide)
     if (claim && slide.evidence.length === 0 && !isNavigationSlide(slide)) {
       const { candidates: evidenceCandidates, search: evidenceCandidateSearch } = findEvidenceBindingCandidates(deck, slide, claim, options)
-      issues.push(blockerIssue(
+      issues.push(warningIssue(
         "missing_evidence",
         `Slide ${slide.index} has an evidence-sensitive claim without evidence: ${claim}`,
-        SOURCE_TRACE_ACTION,
+        `${SOURCE_TRACE_ACTION} Missing evidence is diagnostic; keep the boundary visible rather than blocking the user's requested artifact step.`,
         {
           ...slideRef,
           claimText: claim,
@@ -1036,10 +1025,10 @@ function computeDeckReadinessIssues(state: DecksState, deck: DeckSpec, options:
 
   for (const axis of deck.researchPlan) {
     if (axis.needed && axis.status !== "done" && axis.status !== "read" && axis.status !== "skipped") {
-      issues.push(blockerIssue(
+      issues.push(warningIssue(
         "research_not_ready",
         `Research axis ${axis.axis || "unnamed"} is needed but ${axis.status}`,
-        "Complete, read, or explicitly skip this research axis before writing the deck.",
+        "Research status is diagnostic only; user decides whether to continue, run research, or keep the gap visible.",
       ))
     }
   }
@@ -1050,10 +1039,10 @@ function computeDeckReadinessIssues(state: DecksState, deck: DeckSpec, options:
     if (isIgnorableSourceMaterial(material.path)) continue
     const message = `Source material ${material.path} has been identified but not extracted, summarized, or researched`
     if (hasNeededResearch) {
-      issues.push(blockerIssue(
+      issues.push(warningIssue(
         "source_not_processed",
         message,
-        "Extract, summarize, research, or explicitly exclude this source before writing evidence-backed slides.",
+        "Extract, summarize, research, or exclude this source if it matters; do not block solely on source processing state.",
       ))
     } else {
       issues.push(warningIssue(
@@ -1072,11 +1061,11 @@ function deckPlanQualityIssues(deck: DeckSpec): ReadinessIssue[] {
   return checks.flatMap((check): ReadinessIssue[] => {
     if (check.status === "pass") return []
     const suggestedAction = check.status === "blocker"
-      ? "Re-run compileDeckPlan or revise the deck projection so the deterministic plan includes Cover, TOC, central claim coverage, compatible components, and Closing/Decision Ask before confirming or writing the deck."
+      ? "Revise deck-plan/ if this quality issue matters for the user's goal. It is diagnostic, not a workflow permission blocker."
       : "Keep the stated claim boundaries visible in the plan and rendered artifact; do not stretch partial evidence beyond the supported scope."
     return [{
       type: "plan_quality",
-      severity: check.status,
+      severity: "warning",
       message: check.message,
       suggestedAction,
     }]
@@ -1088,17 +1077,17 @@ function artifactCoverageIssues(state: DecksState, deck: DeckSpec): ReadinessIss
   if (!coverage) return []
   const issues: ReadinessIssue[] = []
   if (coverage.missingClaimIds.length > 0) {
-    issues.push(blockerIssue(
+    issues.push(warningIssue(
       "artifact_coverage",
       `Active deck plan is missing required narrative claims: ${coverage.missingClaimIds.join(", ")}`,
-      "Re-run compileDeckPlan or revise the deck projection so every central or evidence-required claim appears in the planned slides before writing the deck.",
+      "Coverage gaps are diagnostic; revise deck-plan/ or proceed with the visible limitation if the user chooses.",
     ))
   }
   if (coverage.coverageStatus === "stale") {
-    issues.push(blockerIssue(
+    issues.push(warningIssue(
       "artifact_coverage",
       `Active deck artifact coverage is stale: ${coverage.staleReasons.join("; ") || "narrative or render target changed"}`,
-      "Re-run /revela make --deck so the deck plan and artifact coverage are regenerated from the current approved narrative state.",
+      "Artifact coverage staleness is diagnostic; user decides whether to remake, review, or export the current artifact.",
     ))
   } else if (coverage.coverageStatus === "partial") {
     issues.push(warningIssue(
@@ -1147,8 +1136,8 @@ function readinessNextActions(issues: ReadinessIssue[], coverage?: ArtifactCover
   const actions = issues
     .filter((issue) => issue.severity === "blocker" || issue.type === "plan_quality" || issue.type === "artifact_coverage")
     .map((issue) => issue.suggestedAction)
-  if (coverage?.missingClaimIds.length) actions.unshift("Review missingClaimIds in artifactCoverage and recompile the deterministic deck plan before writing HTML.")
-  if (coverage?.coverageStatus === "stale") actions.unshift("Regenerate the deck plan from the current narrative before writing or exporting artifacts.")
+  if (coverage?.missingClaimIds.length) actions.unshift("Review missingClaimIds in artifactCoverage and decide whether to revise deck-plan/ or continue with the current artifact.")
+  if (coverage?.coverageStatus === "stale") actions.unshift("Artifact coverage is stale; decide whether to remake, review, or export the current artifact.")
   return [...new Set(actions)].slice(0, 5)
 }
 

package/lib/edit/deck-state.ts

@@ -1,16 +1,3 @@
-import { readFileSync } from "fs"
-import { activeDesign } from "../design/designs"
-import { activeDomain } from "../domain/domains"
-import {
-  defaultRequiredInputs,
-  DECKS_STATE_FILE,
-  normalizeWorkspaceDeckState,
-  readOrCreateDecksState,
-  upsertDeck,
-  upsertSlides,
-  writeDecksState,
-  type SlideSpec,
-} from "../decks-state"
 import type { EditableDeck } from "./resolve-deck"
 
 export interface EditDeckStatePreflightResult {
@@ -18,102 +5,7 @@ export interface EditDeckStatePreflightResult {
 }
 
 export function ensureEditableDeckState(workspaceRoot: string, deck: EditableDeck): EditDeckStatePreflightResult {
-  let state = normalizeWorkspaceDeckState(readOrCreateDecksState(workspaceRoot), workspaceRoot)
-  const active = state.activeDeck ? state.decks[state.activeDeck] : undefined
-  if (active && active.slug !== deck.slug && active.outputPath !== deck.file) {
-    throw new Error(`${DECKS_STATE_FILE} already points to ${active.outputPath}. Revela 0.8 expects one deck per workspace; move extra decks to a separate workspace.`)
-  }
-  const existing = state.decks[deck.slug]
-  let changed = !existing || existing.outputPath !== deck.file
-
-  state = upsertDeck(state, {
-    ...existing,
-    slug: deck.slug,
-    goal: existing?.goal || `Edit existing Revela deck ${deck.slug}.`,
-    audience: existing?.audience || "Existing deck viewers",
-    language: existing?.language || "en",
-    outputPath: deck.file,
-    theme: {
-      design: existing?.theme?.design || safeActiveDesign(),
-      domain: existing?.theme?.domain || safeActiveDomain(),
-    },
-    requiredInputs: defaultRequiredInputs({
-      ...existing?.requiredInputs,
-      topicClarified: true,
-      audienceClarified: true,
-      languageDecided: true,
-      visualStyleSelected: true,
-      sourceMaterialsIdentified: true,
-      researchNeedAssessed: true,
-      researchFindingsRead: true,
-      slidePlanConfirmed: true,
-      designLayoutsFetched: true,
-    }),
-    researchPlan: existing?.researchPlan || [],
-  })
-
-  const current = state.decks[deck.slug]
-  if (current.slides.length === 0) {
-    state = upsertSlides(state, deck.slug, inferSlides(deck.absoluteFile))
-    changed = true
-  }
-
-  writeDecksState(workspaceRoot, state)
-
-  return {
-    changed,
-  }
-}
-
-function inferSlides(filePath: string): SlideSpec[] {
-  const html = readFileSync(filePath, "utf-8")
-  const chunks = html.match(/<section\b[\s\S]*?<\/section>/gi) || [html]
-  return chunks.map((chunk, index) => {
-    const title = extractTitle(chunk) || `Slide ${index + 1}`
-    return {
-      index: index + 1,
-      title,
-      purpose: "Existing HTML slide prepared for targeted visual edits.",
-      layout: "existing-html",
-      qa: /slide-qa=["']true["']/i.test(chunk),
-      components: ["existing-html"],
-      content: {
-        headline: title,
-        body: [extractText(chunk) || "Existing HTML slide content."],
-      },
-      evidence: [],
-      visuals: [],
-      status: "ready",
-      notes: "Inferred automatically by /revela review --deck preflight.",
-    }
-  })
-}
-
-function extractTitle(html: string): string {
-  const match = /<(?:h1|h2|h3|title)\b[^>]*>([\s\S]*?)<\/(?:h1|h2|h3|title)>/i.exec(html)
-  return normalizeText(match?.[1] || "").slice(0, 160)
-}
-
-function extractText(html: string): string {
-  return normalizeText(html.replace(/<script\b[\s\S]*?<\/script>/gi, " ").replace(/<style\b[\s\S]*?<\/style>/gi, " ").replace(/<[^>]+>/g, " ")).slice(0, 600)
-}
-
-function normalizeText(value: string): string {
-  return value.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/\s+/g, " ").trim()
-}
-
-function safeActiveDesign(): string {
-  try {
-    return activeDesign()
-  } catch {
-    return "aurora"
-  }
-}
-
-function safeActiveDomain(): string {
-  try {
-    return activeDomain()
-  } catch {
-    return "general"
-  }
+  void workspaceRoot
+  void deck
+  return { changed: false }
 }

package/lib/edit/open.ts

@@ -85,8 +85,8 @@ function openEditableDeckInternal(
   const shouldOpen = options.openBrowser !== false && !(behavior.skipLiveSession && session.live)
   if (shouldOpen) (options.openUrl ?? openUrl)(url)
 
-  const source = deck.source === "decks-state" ? "DECKS.json" : deck.source === "file-path" ? "file path" : "fallback path"
-  const stateNote = preflight.changed ? "Deck state was prepared in DECKS.json for visual editing." : "Deck state already points to this visual edit target."
+  const source = deck.source === "file-path" ? "file path" : "discovered deck file"
+  const stateNote = preflight.changed ? "Deck file preflight updated runtime state." : "Deck visual edit uses the selected HTML artifact directly."
 
   return {
     deck,

package/lib/edit/resolve-deck.ts

@@ -1,39 +1,27 @@
-import { existsSync, readdirSync } from "fs"
+import { existsSync, readdirSync, statSync } from "fs"
 import { relative, resolve, sep } from "path"
-import { DECKS_STATE_FILE, hasDecksState, isDeckHtmlPath, readDecksState, workspaceDeckSlug } from "../decks-state"
-import { resolveActiveHtmlDeckPath } from "../workspace-state/render-targets"
+import { isDeckHtmlPath, workspaceDeckSlug } from "../decks-state"
 
 export interface EditableDeck {
   slug: string
   file: string
   absoluteFile: string
-  source: "render-target" | "decks-state" | "fallback" | "file-path"
+  source: "discovered" | "file-path"
 }
 
 export function resolveEditableDeck(workspaceRoot: string, input = ""): EditableDeck {
-  if (input.trim()) {
-    throw new Error("/revela review --deck does not accept a target. It opens the active HTML deck or the only HTML deck in decks/.")
-  }
-
-  if (hasDecksState(workspaceRoot)) {
-    const state = readDecksState(workspaceRoot)
-    const deckPath = resolveActiveHtmlDeckPath(state)
-    const source = state.renderTargets.some((target) => target.type === "html_deck" && target.outputPath === deckPath) ? "render-target" : "decks-state"
-    if (deckPath && isDeckHtmlPath(deckPath)) {
-      const absoluteFile = resolve(workspaceRoot, deckPath)
-      if (existsSync(absoluteFile)) return resolveDeckFile(workspaceRoot, workspaceDeckSlug(workspaceRoot), deckPath, source)
-    }
-  }
+  const explicit = input.trim()
+  if (explicit) return resolveDeckFile(workspaceRoot, workspaceDeckSlug(workspaceRoot), explicit, "file-path")
 
   const htmlFiles = listDeckHtmlFiles(workspaceRoot)
   if (htmlFiles.length === 0) {
-    throw new Error("No deck HTML found in decks/. Generate a deck first.")
+    throw new Error("No deck HTML found in decks/. Pass a deck path or generate a deck first.")
   }
   if (htmlFiles.length > 1) {
-    throw new Error("This workspace contains multiple deck HTML files. Revela 0.8 expects one deck per workspace. Move extra decks to separate workspaces.")
+    throw new Error(`Multiple deck HTML files found in decks/: ${htmlFiles.join(", ")}. Pass the deck path explicitly.`)
   }
 
-  return resolveDeckFile(workspaceRoot, workspaceDeckSlug(workspaceRoot), htmlFiles[0], "file-path")
+  return resolveDeckFile(workspaceRoot, workspaceDeckSlug(workspaceRoot), htmlFiles[0], "discovered")
 }
 
 function listDeckHtmlFiles(workspaceRoot: string): string[] {
@@ -51,18 +39,20 @@ function resolveDeckFile(
   file: string,
   source: EditableDeck["source"],
 ): EditableDeck {
-  if (!isDeckHtmlPath(file)) {
-    throw new Error(`${DECKS_STATE_FILE} deck outputPath must be decks/*.html, got ${file || "missing"}.`)
-  }
-
   const root = resolve(workspaceRoot)
   const absoluteFile = resolve(root, file)
   if (!isInside(root, absoluteFile)) {
     throw new Error(`Resolved deck file is outside the workspace: ${file}`)
   }
+  if (!isDeckHtmlPath(workspaceRelative(root, absoluteFile)) && !/\.html?$/i.test(absoluteFile)) {
+    throw new Error(`Deck path must be an HTML file: ${file || "missing"}.`)
+  }
   if (!existsSync(absoluteFile)) {
     throw new Error(`Deck HTML not found: ${workspaceRelative(root, absoluteFile)}`)
   }
+  if (!statSync(absoluteFile).isFile()) {
+    throw new Error(`Deck path is not a file: ${workspaceRelative(root, absoluteFile)}`)
+  }
 
   return {
     slug,

package/lib/inspect/open.ts

@@ -54,8 +54,8 @@ export function openInspectDeck(target: string, options: OpenInspectDeckOptions)
   return {
     deck,
     url,
-    source: deck.source === "render-target" ? "render target" : deck.source === "decks-state" ? "DECKS.json" : deck.source === "file-path" ? "file path" : "fallback path",
-    stateNote: preflight.changed ? "Deck state was prepared in DECKS.json for inspection." : "Deck state already points to this inspection target.",
+    source: deck.source === "file-path" ? "file path" : "discovered deck file",
+    stateNote: preflight.changed ? "Deck file preflight updated runtime state." : "Deck inspection uses the selected HTML artifact directly.",
     preflightChanged: preflight.changed,
     reusedSession: session.reused,
     openedBrowser: shouldOpen,

package/lib/media/download.ts

@@ -12,6 +12,10 @@ const MIME_TO_EXT: Record<string, string> = {
 
 const ALLOWED_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".svg", ".webp", ".gif", ".ico"])
 const DEFAULT_DOWNLOAD_TIMEOUT_MS = 10_000
+const PRODUCT_USER_AGENT = "Revela/0.17 asset-save"
+const BROWSER_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"
 
 function normalizeExtension(ext: string): string {
   const value = ext.toLowerCase()
@@ -47,6 +51,24 @@ export async function downloadImageFromUrl(
     throw new Error("INVALID_URL")
   }
 
+  const userAgents = [PRODUCT_USER_AGENT, BROWSER_USER_AGENT]
+  let lastError: unknown
+  for (const userAgent of userAgents) {
+    try {
+      return await downloadWithUserAgent(parsed, userAgent, options)
+    } catch (error) {
+      lastError = error
+    }
+  }
+
+  throw lastError instanceof Error ? lastError : new Error(String(lastError))
+}
+
+async function downloadWithUserAgent(
+  parsed: URL,
+  userAgent: string,
+  options: { timeoutMs?: number },
+): Promise<{ buffer: Buffer; contentType: string | null; extension: string }> {
   const controller = new AbortController()
   let timedOut = false
   const timer = setTimeout(() => {
@@ -60,9 +82,7 @@ export async function downloadImageFromUrl(
     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",
+        "User-Agent": userAgent,
       },
       signal: controller.signal,
     })

package/lib/media/save.ts

@@ -141,6 +141,7 @@ function saveFailureResult(
     path: null,
     manifestPath: relative(workspaceDir, manifestPath),
     updated: true,
+    failureReason,
   }
 }
 

package/lib/media/types.ts

@@ -59,6 +59,7 @@ export type MediaSaveResult =
     path: string | null
     manifestPath: string
     updated: boolean
+    failureReason?: string
   }
   | {
     ok: false