@cyber-dash-tech/revela 0.15.1 → 0.15.3

package/lib/commands/inspect.ts

@@ -1,25 +1,7 @@
-import { openRefineDeck } from "../refine/open"
-
 export async function handleInspect(
   options: { client: any; sessionID: string; workspaceRoot: string; openBrowser?: boolean },
   send: (text: string) => Promise<void>,
 ): Promise<void> {
-  try {
-    const result = openRefineDeck("", {
-      client: options.client,
-      sessionID: options.sessionID,
-      workspaceRoot: options.workspaceRoot,
-      mode: "inspect",
-      openBrowser: options.openBrowser,
-    })
-    await send(
-      `\`/revela inspect\` is deprecated. Opened \`/revela refine\` in Inspect mode for the active HTML deck.\n` +
-      `File: \`${result.deck.file}\`\n` +
-      `${result.stateNote}\n` +
-      `URL: ${result.url}\n\n` +
-      `Use \`/revela refine\` directly going forward. Use Ctrl/Cmd-click in the browser to reference deck elements, then use the Inspect tab for read-only Source/Purpose review. There is no chat box or freeform prompt.`
-    )
-  } catch (e: any) {
-    await send(`**Inspect failed:** ${e.message || String(e)}`)
-  }
+  void options
+  await send("`/revela inspect` is no longer a public command. Use `/revela refine --deck` and the Inspect tab for grounded Source/Purpose/Narrative Reading.")
 }

package/lib/commands/narrative.ts

@@ -34,7 +34,7 @@ export function parseStoryArgs(param: string): ParseStoryArgsResult {
     if (token.startsWith("--language=")) {
       return { ok: false, error: "Usage: `/revela story --language <language>` or `/revela story -l <language>`. Do not use `--language=<language>`." }
     }
-    return { ok: false, error: "Usage: `/revela story [--language <language> | -l <language>]`. Use `/revela review` for a readiness report." }
+    return { ok: false, error: "Usage: `/revela story [--language <language> | -l <language>]`." }
   }
 
   return { ok: true, args: { language } }
@@ -130,9 +130,9 @@ export function buildNarrativeViewPrompt(options: { workspaceRoot: string; langu
   return `Prepare the read-only Revela narrative UI display model.
 
 Target language request: ${options.language}
-- The language value is passed from the user's /revela narrative arguments. Interpret it as the desired UI/display language.
+- The language value is passed from the user's /revela story arguments. Interpret it as the desired UI/display language.
 - Examples: --cn maps to zh-CN, --jp maps to ja-JP, while --fr, --de, --es, --ko, --Arabic, --Portuguese-BR, or a written language name should be localized normally into that requested language.
-- Default /revela narrative language is en when the user provides no language request.
+- Default /revela story language is en when the user provides no language request.
 
 You must call the \`revela-narrative-view\` tool exactly once.
 

package/lib/commands/pdf.ts

@@ -1,7 +1,7 @@
 /**
  * lib/commands/pdf.ts
  *
- * Handler for `/revela pdf <file_path>` — exports an HTML slide deck to PDF.
+ * Handler for `/revela export --deck pdf <file_path>` — exports an HTML slide deck to PDF.
  *
  * Output: same directory and base name as the input, with .pdf extension.
  * Example: decks/my-deck.html → decks/my-deck.pdf
@@ -24,8 +24,8 @@ export async function handlePdf(
 
   if (!resolvedFile) {
     await send(
-      "**Usage:** `/revela pdf [file_path]`\n\n" +
-      "Example: `/revela pdf decks/my-deck.html`"
+      "**Usage:** `/revela export --deck pdf [file_path]`\n\n" +
+      "Example: `/revela export --deck pdf decks/my-deck.html`"
     )
     return
   }

package/lib/commands/pptx.ts

@@ -1,7 +1,7 @@
 /**
  * lib/commands/pptx.ts
  *
- * Handler for `/revela pptx [file_path]` — exports an HTML slide deck to PPTX.
+ * Handler for `/revela export --deck pptx [file_path]` — exports an HTML slide deck to PPTX.
  *
  * Output: same directory and base name as the input, with .pptx extension.
  * Example: decks/my-deck.html → decks/my-deck.pptx
@@ -64,7 +64,7 @@ export function resolvePptxDeck(workspaceRoot: string, filePath = ""): ResolvedP
     throw new Error("No deck HTML found in decks/. Generate a deck first or pass a file path.")
   }
   if (htmlFiles.length > 1) {
-    throw new Error("This workspace contains multiple deck HTML files. Run `/revela pptx decks/<file>.html` to choose one.")
+    throw new Error("This workspace contains multiple deck HTML files. Run `/revela export --deck pptx decks/<file>.html` to choose one.")
   }
 
   const absoluteFile = resolve(root, htmlFiles[0])

package/lib/commands/review.ts

@@ -18,7 +18,7 @@ Goal:
 - Treat this as a narrative readiness review, not a deck HTML write-readiness review.
 - Do not write, patch, or directly edit ${DECKS_STATE_FILE}. Use the \`revela-decks\` tool for all state changes.
 - Call \`revela-decks\` action \`reviewNarrative\` as the authoritative deterministic readiness engine.
-- Do not call \`revela-decks\` action \`review\` here. That action is the deck/artifact gate and belongs to \`/revela make deck --review\`.
+- Do not call \`revela-decks\` action \`review\` here. That action is the deck/artifact gate inside \`/revela make --deck\` after the deck plan is confirmed.
 - Do not treat legacy \`writeReadiness.status\`, old review snapshots, or an existing HTML deck as narrative approval.
 - Do not write or overwrite \`decks/*.html\` during narrative review.
 - If the narrative is \`ready_for_approval\`, ask whether the user wants to approve it or revise it. Do not approve automatically.
@@ -50,7 +50,7 @@ Report format:
 - If warnings exist, list them after blockers as residual risks.
 - If approval is missing, ask whether the user wants to approve the narrative or revise it.
 - If approval is stale, say the prior approval no longer matches the current narrative hash.
-- Keep deck/artifact readiness separate. If the user wants to review slide-writing readiness, tell them to run \`/revela make deck --review\`.
+- Keep deck/artifact readiness separate. If the user wants to write or review deck artifacts, tell them to run \`/revela make --deck\`.
 
 Rules:
 - Do not write or overwrite \`decks/*.html\` during narrative review.
@@ -79,6 +79,7 @@ Goal:
 - Treat this as the explicit transition from approved narrative state to user-confirmed deck planning.
 - Use the deck-render prompt mode for design, layout, component, HTML, QA, and deck artifact rules.
 - Default behavior is two-stage: first show the compiled deck plan with low-fidelity layout sketches, then stop for user confirmation before any artifact review or HTML writing.
+- Every deck plan must include Cover, Table of Contents, and Closing slides. The TOC must show 3-5 chapter headings that match the deck's slide groups.
 - Do not write or overwrite \`decks/*.html\` until the narrative handoff, explicit user deck-plan confirmation, and deck/artifact gate are all satisfied.
 - Do not treat legacy \`writeReadiness.status\`, old review snapshots, or existing HTML decks as narrative approval.
 - Do not bypass the deck HTML contract, review snapshot freshness, source-trace expectations, or export preflight protections.
@@ -93,19 +94,22 @@ Workflow:
 3. If narrative readiness is \`approved\`, continue. If it is \`ready_for_approval\`, ask the user for explicit approval before continuing. If it is blocked, stale, or needs research, stop and report the smallest next action. Do not call \`approveNarrative\` unless the user explicitly approves or requests a render override.
 4. After approval or explicit render override exists, call \`revela-decks\` action \`compileDeckPlan\`. This projects canonical narrative claims and evidence bindings into compatibility \`slides[]\` and \`slides[].evidence[]\`; it must not write HTML.
 5. If \`compileDeckPlan\` returns \`skipped\`, stop and report the reason. Do not invent slide specs manually to bypass approval.
-6. Present the compiled deck plan to the user and include a low-fidelity layout sketch for every slide. The sketch is ASCII/text structure only; do not generate visual images or HTML mockups.
+6. Present the compiled deck plan to the user and include a low-fidelity layout sketch for every slide. The plan must identify the chapter structure first: 3-5 chapter headings, each chapter's slide range, and which non-structural slides belong to each chapter. The sketch is ASCII/text structure only; do not generate visual images or HTML mockups.
 7. Stop after presenting the plan. Ask the user to confirm or request changes. Do not call \`revela-decks review\`, do not fetch design context, and do not write HTML in the same turn unless the user had already explicitly confirmed the current plan before this command.
 8. Only after explicit user confirmation of the current slide plan, call \`revela-decks\` action \`confirmDeckPlan\` with \`approvalBy=user\` and a compact \`approvalNote\`.
 9. After confirmation is recorded, ask for or confirm visual design only after the narrative deck plan exists. Fetch required design layouts/components with \`revela-designs read\` as needed.
 10. Update only deck/artifact metadata through \`revela-decks upsertDeck\` / \`upsertSlides\` when required by confirmed design/layout choices. Do not change canonical narrative claims unless the user asks to revise the narrative.
 11. Call \`revela-decks\` action \`review\` as the artifact gate. It computes \`writeReadiness\` and review snapshots for deck HTML writing. If it reports \`slide_plan_unconfirmed\`, stop and ask for explicit deck-plan confirmation.
-12. Write \`decks/*.html\` only if the deck/artifact gate is ready and all deck HTML contract requirements can be satisfied. After each HTML write, the system automatically runs artifact QA before opening Refine.
-13. If post-write artifact QA reports hard errors, fix them and let QA run again. Refine opens only after hard errors pass. Density warnings about thin claim/evidence substance should be reported and improved when useful, but they do not block Refine.
+12. Write \`decks/*.html\` only if the deck/artifact gate is ready and all deck HTML contract requirements can be satisfied. Generate the artifact chapter by chapter instead of drafting all content slides in one broad pass. Keep the HTML file valid after every write, preserve already-written slides, and update one chapter's slide sections at a time.
+13. For each chapter, make every content slide carry a distinct claim, evidence item, comparison, risk, or action. If a chapter lacks enough substance for its allocated slides, merge weak slides or reduce the slide count instead of creating sparse filler.
+14. After each HTML write, the system automatically runs artifact QA before opening Refine. 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.
+- Include \`Required structure: Cover + Table of Contents + Closing\` and do not omit any of those slides.
+- Include a \`Chapters\` section before the slide list. It must list 3-5 TOC headings, their slide ranges, and the non-structural slides assigned to each chapter.
 - For every slide, include: slide index, title, purpose, narrative role, low-fidelity layout sketch, layout, components, primary/supporting claim ids, evidence binding ids or source summary, visual intent, and caveats/unsupported scope.
 - Use this sketch style or similarly simple ASCII boxes:
 
@@ -135,12 +139,15 @@ Caveats / unsupported scope:
 Report format before any HTML write after confirmation:
 - Start with \`Deck handoff: <status>\`.
 - Include which user-confirmed plan, approved narrative hash, and deck review snapshot authorized the artifact work.
+- Include the chapter currently being generated and confirm already-written slides are being preserved.
 - If deck/artifact review is blocked, list blockers separately from narrative blockers.
 - After writing HTML, read the appended \`Artifact QA\` report from the tool output. If it failed, fix hard errors before considering the deck ready for Refine.
 
 Rules:
 - \`compileDeckPlan\` is the canonical narrative-to-deck planning path. Do not manually invent slide specs to avoid it.
 - Deck slide specs are render-target projections. Canonical narrative remains the authority for audience, decision, claims, evidence boundaries, objections, risks, and approval.
+- Cover, Table of Contents, and Closing are mandatory deck structure. TOC chapter headings must match the chapter grouping used for generation.
+- Do not generate the complete deck content in one broad pass after confirmation. Work chapter by chapter while keeping the artifact valid after each write.
 - Applying evidence candidates, rewriting canonical claims, or approving narratives requires explicit user instruction.
 - If the user requests slide order, layout, component, or visual-intent changes that do not alter meaning, update only the deck projection through \`upsertSlides\` and present the revised plan for confirmation.
 - If the user requests claim, evidence, caveat, decision, or recommendation meaning changes, update canonical narrative first and rerun narrative review/approval or explicit render override before compiling a new deck plan.
@@ -165,7 +172,7 @@ export function buildDeckReviewPrompt({
 
 Goal:
 - Use ${DECKS_STATE_FILE} as the source of truth for whether the current workspace deck is ready to be written to \`decks/*.html\`.
-- Treat this as an artifact gate for deck rendering, not strategic narrative approval. Narrative readiness reports are reviewed by \`/revela review\`.
+- Treat this as an artifact gate for deck rendering, not strategic narrative approval. Narrative readiness is reviewed through \`/revela story\`.
 - Preserve the deck spec for future sessions: every slide's content, layout, components, evidence, visuals, production status, and the 0.9 narrative compiler brief when available.
 - Do not write, patch, or directly edit ${DECKS_STATE_FILE}. Use the \`revela-decks\` tool for all state changes.
 - Let \`revela-decks\` action \`review\` compute writeReadiness; do not manually set readiness to ready.

package/lib/decks-state.ts

@@ -661,7 +661,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
       type: "missing_slide_spec",
       severity: "blocker",
       message,
-      suggestedAction: "Run /revela make deck --review and resolve all readiness blockers before writing deck HTML.",
+      suggestedAction: "Run /revela make --deck and resolve all readiness blockers before writing deck HTML.",
     })
   }
   if (deck.writeReadiness.blockers.length > 0) {
@@ -671,7 +671,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
       type: "missing_slide_spec",
       severity: "blocker",
       message,
-      suggestedAction: "Resolve the stored writeReadiness blockers and rerun /revela make deck --review.",
+      suggestedAction: "Resolve the stored writeReadiness blockers and rerun /revela make --deck.",
     })
   }
   if (normalized.reviews.length > 0) {
@@ -684,7 +684,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
         type: "missing_slide_spec",
         severity: "blocker",
         message,
-        suggestedAction: "Run /revela make deck --review so readiness is recorded against the current active render target.",
+        suggestedAction: "Run /revela make --deck so readiness is recorded against the current active render target.",
       })
     } else if (!isReviewSnapshotCurrent(normalized, snapshot, deck.slug)) {
       const message = "Latest review snapshot is stale for the current deck, sources, evidence, narrative state, or render target"
@@ -693,7 +693,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
         type: "missing_slide_spec",
         severity: "blocker",
         message,
-        suggestedAction: "Run /revela make deck --review again after the latest state changes before writing deck HTML.",
+        suggestedAction: "Run /revela make --deck again after the latest state changes before writing deck HTML.",
       })
     } else if (snapshot.status !== "ready") {
       const message = `Latest review snapshot is ${snapshot.status}, not ready`
@@ -702,7 +702,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
         type: "missing_slide_spec",
         severity: "blocker",
         message,
-        suggestedAction: "Resolve review blockers and rerun /revela make deck --review before writing deck HTML.",
+        suggestedAction: "Resolve review blockers and rerun /revela make --deck before writing deck HTML.",
       })
     }
   }
@@ -748,7 +748,7 @@ export function buildDecksStatePromptLayer(workspaceRoot: string, maxChars = 140
   }
   let text = JSON.stringify(compact, null, 2)
   if (text.length > maxChars) text = text.slice(0, maxChars).trimEnd() + "\n[DECKS.json state truncated for prompt size.]"
-  return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as the source of truth for the single current deck's specs, slide plan, evidence, render targets, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- ${DECKS_STATE_FILE} deck slides use 1-based \`slides[].index\` values. Render every HTML \`<section class="slide">\` with a matching 1-based \`data-slide-index\` attribute, and do not use 0-based \`data-index\` as slide identity.\n- The active HTML deck is represented as a \`renderTarget\` of type \`html_deck\`; PDF/PPTX exports should be recorded as derived render targets, not as separate deck specs.\n- \`writeReadiness\` is a compatibility projection for the /revela make deck generation workflow, not a hard blocker for targeted artifact-level HTML fixes.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- For /revela make deck generated HTML, use the current deck's outputPath and satisfy the deck HTML contract. For targeted artifact-level edits, patch the requested deck HTML directly without treating \`writeReadiness\` or \`planReview\` as a precondition.`
+  return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as the source of truth for the single current deck's specs, slide plan, evidence, render targets, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- ${DECKS_STATE_FILE} deck slides use 1-based \`slides[].index\` values. Render every HTML \`<section class="slide">\` with a matching 1-based \`data-slide-index\` attribute, and do not use 0-based \`data-index\` as slide identity.\n- The active HTML deck is represented as a \`renderTarget\` of type \`html_deck\`; PDF/PPTX exports should be recorded as derived render targets, not as separate deck specs.\n- \`writeReadiness\` is a compatibility projection for the /revela make --deck generation workflow, not a hard blocker for targeted artifact-level HTML fixes.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- For /revela make --deck generated HTML, use the current deck's outputPath and satisfy the deck HTML contract. For targeted artifact-level edits, patch the requested deck HTML directly without treating \`writeReadiness\` or \`planReview\` as a precondition.`
 }
 
 function compactWorkspaceForPrompt(workspace: DecksState["workspace"]): DecksState["workspace"] {

package/lib/edit/deck-state.ts

@@ -84,7 +84,7 @@ function inferSlides(filePath: string): SlideSpec[] {
       evidence: [],
       visuals: [],
       status: "ready",
-      notes: "Inferred automatically by /revela edit preflight.",
+      notes: "Inferred automatically by /revela refine --deck preflight.",
     }
   })
 }

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.
@@ -75,6 +79,14 @@ Instructions:
 - 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.
 - 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.

package/lib/edit/resolve-deck.ts

@@ -12,7 +12,7 @@ export interface EditableDeck {
 
 export function resolveEditableDeck(workspaceRoot: string, input = ""): EditableDeck {
   if (input.trim()) {
-    throw new Error("/revela refine does not accept a target. It opens the active HTML deck or the only HTML deck in decks/.")
+    throw new Error("/revela refine --deck does not accept a target. It opens the active HTML deck or the only HTML deck in decks/.")
   }
 
   if (hasDecksState(workspaceRoot)) {

package/lib/inspect/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/inspect/server.ts

@@ -484,7 +484,7 @@ export function renderInspectorShell(token: string): string {
     <aside>
       <div>
         <h1>Evidence Inspector</h1>
-        <p class="hint">Cmd/Ctrl-click slide elements to attach them as references, exactly like /revela edit. Then click <b>Inspect Selection</b>. This is not chat.</p>
+        <p class="hint">Cmd/Ctrl-click slide elements to attach them as references in /revela refine --deck. Then click <b>Inspect Selection</b>. This is not chat.</p>
       </div>
       <div id="selection" class="selection">
         <strong>Selection</strong>
@@ -632,7 +632,7 @@ export function renderInspectorShell(token: string): string {
         if (bindAttempts >= 80) {
           clearInterval(bindTimer);
           bindTimer = 0;
-          setBindingStatus('error', 'Selection binding timed out. Reopen /revela inspect or reload this page.');
+          setBindingStatus('error', 'Selection binding timed out. Reopen /revela refine --deck or reload this page.');
         }
       }, 150);
     }

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)