@cyber-dash-tech/revela 0.17.0 → 0.17.2

package/lib/refine/server.ts

@@ -253,35 +253,105 @@ async function handleAssetSave(req: Request, session: EditSession): Promise<Resp
   const candidate = normalizeImageCandidate(body?.candidate ?? body)
   if (!candidate) return jsonResponse({ ok: false, error: "Valid image candidate is required" }, 400)
   const purpose = normalizeMediaPurpose(body?.purpose) || candidate.purpose || "illustration"
-  const result = await saveMediaAsset({
-    topic: session.deck,
+  const brief = body?.brief || `Saved from ${candidate.provider} for Review asset placement.`
+  const saved = await saveAssetCandidateUrls({
+    session,
+    candidate,
     id: body?.id || candidate.candidateId,
-    type: "image",
     purpose,
-    brief: body?.brief || `Saved from ${candidate.provider} for Review asset placement.`,
-    status: "success",
-    sourceUrl: candidate.imageUrl,
+    brief,
     alt: body?.alt || candidate.alt || candidate.title,
     notes: body?.notes,
-    provider: candidate.provider,
-    sourcePageUrl: candidate.sourcePageUrl,
-    license: candidate.license,
-    attribution: candidate.attribution,
-    width: candidate.width,
-    height: candidate.height,
-  }, session.workspaceRoot)
+  })
 
   session.lastActiveAt = Date.now()
   scheduleIdleStop()
+  const result = saved.result
   if (!result.ok) return jsonResponse({ ok: false, error: result.error }, 400)
   if (result.status !== "success" || !result.path) {
-    return jsonResponse({ ok: false, error: `Failed to save asset: ${result.status}` }, 400)
+    return jsonResponse({ ok: false, error: failedAssetSaveMessage(result.status, saved.failures) }, 400)
   }
   const asset = savedAssetForResult(session, result.assetId)
+    ?? savedAssetFallback(session, {
+      id: result.assetId,
+      path: result.path,
+      sourceUrl: saved.sourceUrl,
+      purpose,
+      brief,
+      candidate,
+    })
   if (!asset) return jsonResponse({ ok: false, error: "Saved asset was not found in workspace assets." }, 500)
   return jsonResponse({ ok: true, asset, result })
 }
 
+async function saveAssetCandidateUrls(input: {
+  session: EditSession
+  candidate: ImageCandidate
+  id: string
+  purpose: MediaPurpose
+  brief: string
+  alt?: string
+  notes?: string
+}): Promise<{
+  result: Awaited<ReturnType<typeof saveMediaAsset>>
+  sourceUrl?: string
+  failures: Array<{ url: string; status: string }>
+}> {
+  const urls = uniqueAssetUrls([input.candidate.imageUrl, input.candidate.thumbnailUrl])
+  const failures: Array<{ url: string; status: string }> = []
+  let lastResult: Awaited<ReturnType<typeof saveMediaAsset>> | undefined
+
+  for (const sourceUrl of urls) {
+    const result = await saveMediaAsset({
+      topic: input.session.deck,
+      id: input.id,
+      type: "image",
+      purpose: input.purpose,
+      brief: input.brief,
+      status: "success",
+      sourceUrl,
+      alt: input.alt,
+      notes: input.notes,
+      provider: input.candidate.provider,
+      sourcePageUrl: input.candidate.sourcePageUrl,
+      license: input.candidate.license,
+      attribution: input.candidate.attribution,
+      width: input.candidate.width,
+      height: input.candidate.height,
+    }, input.session.workspaceRoot)
+    lastResult = result
+    if (result.ok && result.status === "success" && result.path) return { result, sourceUrl, failures }
+    failures.push({ url: sourceUrl, status: result.ok ? result.failureReason ?? result.status : result.error })
+  }
+
+  return {
+    result: lastResult ?? { ok: false, error: "No downloadable image URL was provided" },
+    failures,
+  }
+}
+
+function uniqueAssetUrls(values: Array<string | undefined>): string[] {
+  const seen = new Set<string>()
+  return values.flatMap((value) => {
+    const url = value?.trim()
+    if (!url || seen.has(url)) return []
+    seen.add(url)
+    return [url]
+  })
+}
+
+function failedAssetSaveMessage(status: string, failures: Array<{ url: string; status: string }>): string {
+  if (!failures.length) return `Failed to save asset: ${status}`
+  const details = failures
+    .map((failure) => `${shortUrl(failure.url)}: ${failure.status}`)
+    .join("; ")
+  return `Failed to save asset: ${status} (${details})`
+}
+
+function shortUrl(value: string): string {
+  return value.length <= 96 ? value : `${value.slice(0, 93)}...`
+}
+
 function handleAssetList(session: EditSession): Response {
   session.lastActiveAt = Date.now()
   scheduleIdleStop()
@@ -292,6 +362,39 @@ function savedAssetForResult(session: EditSession, assetId: string): (MediaAsset
   return listSavedAssets(session).find((asset) => asset.id === assetId) ?? null
 }
 
+function savedAssetFallback(
+  session: EditSession,
+  input: {
+    id: string
+    path: string | null
+    sourceUrl?: string
+    purpose: MediaPurpose
+    brief: string
+    candidate: ImageCandidate
+  },
+): (MediaAssetRecord & { previewUrl?: string; deckPath?: string }) | null {
+  if (!input.path) return null
+  return {
+    id: input.id,
+    type: "image",
+    purpose: input.purpose,
+    brief: input.brief,
+    status: "success",
+    path: input.path,
+    sourceUrl: input.sourceUrl ?? input.candidate.imageUrl,
+    alt: input.candidate.alt || input.candidate.title,
+    provider: input.candidate.provider,
+    sourcePageUrl: input.candidate.sourcePageUrl,
+    license: input.candidate.license,
+    attribution: input.candidate.attribution,
+    width: input.candidate.width,
+    height: input.candidate.height,
+    savedAt: new Date().toISOString(),
+    previewUrl: assetUrlForRef(input.path, session, session.workspaceRoot) ?? undefined,
+    deckPath: relative(dirname(session.absoluteFile), resolve(session.workspaceRoot, input.path)).replace(/\\/g, "/"),
+  }
+}
+
 function listSavedAssets(session: EditSession): Array<MediaAssetRecord & { previewUrl?: string; deckPath?: string }> {
   const manifestPath = resolve(session.workspaceRoot, "assets", slugify(session.deck), "media-manifest.json")
   if (!existsSync(manifestPath)) return []
@@ -891,6 +994,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     .skeleton-line.long { width: 92%; }
     .asset-card.is-saving::after { content: ""; position: absolute; inset: 0; background: rgba(15,23,42,.32); }
     .asset-card.is-saving .asset-save { z-index: 1; }
+    .asset-card.is-saved-candidate .asset-thumb { opacity: .72; }
     @keyframes spin { to { transform: rotate(360deg); } }
     @keyframes shimmer { 0% { background-position: 200% 0; } 100% { background-position: -200% 0; } }
     .asset-search { display: grid; grid-template-columns: minmax(0, 1fr) 118px; gap: 8px; }
@@ -913,6 +1017,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     .asset-search-title span { color: #756f66; font-size: 12px; line-height: 1.35; }
     .asset-back { width: auto; padding: 9px 11px; border-radius: 999px; background: #ebe4d8; color: #111827; box-shadow: none; }
     .asset-save { position: absolute; left: 7px; right: 7px; bottom: 7px; width: auto; padding: 7px 8px; border-radius: 10px; font-size: 11px; background: rgba(17,24,39,.9); color: #fbfaf7; box-shadow: 0 8px 16px rgba(31,41,51,.2); opacity: .96; }
+    .asset-save.saved { background: rgba(77,97,56,.94); color: #fbfaf7; cursor: default; }
     .asset-empty { grid-column: 1 / -1; margin: 0; color: #756f66; font-size: 12px; line-height: 1.45; }
     .edit-assets { padding: 10px; border: 1px solid #d8d2c6; border-radius: 16px; background: #f7f3ea; }
     .edit-assets .panel { gap: 8px; }
@@ -2000,9 +2105,13 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         }
         state.assetCandidates.forEach((candidate, index) => {
           const card = assetCard(candidate, false, index);
+          const savedAsset = savedAssetForCandidate(candidate);
           if (state.assetSavingIndex === index) {
             card.classList.add('is-saving');
             appendAssetSaveButton(card, 'Saving...', 'Saving to workspace', () => {}, true);
+          } else if (savedAsset) {
+            card.classList.add('is-saved-candidate');
+            appendAssetSaveButton(card, '✅ Saved', 'Asset already saved to Local Assets', () => {}, false, 'saved');
           } else {
             appendAssetSaveButton(card, 'Save', 'Save to workspace', () => saveCandidate(index));
           }
@@ -2025,7 +2134,11 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           });
           const body = await res.json().catch(() => ({}));
           if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to save asset');
-          await loadSavedAssets();
+          const listed = await loadSavedAssets();
+          if (body.asset && (!listed || !findSavedAsset(body.asset.id))) {
+            mergeSavedAsset(body.asset);
+            renderSavedAssets();
+          }
           const path = body.asset && (body.asset.path || body.asset.deckPath);
           setStatus(path ? 'Saved to ' + path + '. Use it from Local Assets.' : 'Asset saved. Use it from Local Assets.');
         } catch (error) {
@@ -2043,12 +2156,36 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to list assets');
           state.savedAssets = Array.isArray(body.assets) ? body.assets : [];
           renderSavedAssets();
+          return true;
         } catch (error) {
-          const message = '<p class="asset-empty">' + escapeHtml(error && error.message ? error.message : String(error)) + '</p>';
-          els.editSavedAssets.innerHTML = message;
+          if (!state.savedAssets.length) {
+            const message = '<p class="asset-empty">' + escapeHtml(error && error.message ? error.message : String(error)) + '</p>';
+            els.editSavedAssets.innerHTML = message;
+          }
+          return false;
         }
       }
 
+      function mergeSavedAsset(asset) {
+        if (!asset || !asset.id) return;
+        const next = state.savedAssets.filter((existing) => existing.id !== asset.id);
+        next.unshift(asset);
+        state.savedAssets = next;
+      }
+
+      function savedAssetForCandidate(candidate) {
+        const id = slugifyAssetId(candidate && candidate.candidateId);
+        if (!id) return null;
+        return state.savedAssets.find((asset) => asset.id === id) || null;
+      }
+
+      function slugifyAssetId(value) {
+        return String(value || '')
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/g, '-')
+          .replace(/^-+|-+$/g, '');
+      }
+
       function renderSavedAssets() {
         renderSavedAssetGrid(els.editSavedAssets, 'No local assets yet. Click + to search assets.');
       }
@@ -2108,12 +2245,12 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         }
       }
 
-      function appendAssetSaveButton(card, text, label, onClick, loading) {
+      function appendAssetSaveButton(card, text, label, onClick, loading, variant) {
         const button = document.createElement('button');
         button.type = 'button';
-        button.className = 'asset-save';
+        button.className = variant ? 'asset-save ' + variant : 'asset-save';
         button.innerHTML = loading ? '<span class="spinner" aria-hidden="true"></span><span>' + escapeHtml(text) + '</span>' : escapeHtml(text);
-        button.disabled = !!loading;
+        button.disabled = !!loading || variant === 'saved';
         button.setAttribute('aria-label', label);
         button.title = label;
         button.addEventListener('click', onClick);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "OpenCode plugin for trusted narrative artifacts from local sources, research, and evidence",
   "type": "module",
   "main": "./index.ts",

package/plugin.ts

@@ -784,7 +784,7 @@ Next step: use \`revela-decks\` with action \`init\`, \`upsertDeck\`, \`upsertSl
     // Handles PDF and images — read tool succeeds with base64 attachment.
     // PDF: extract text, remove base64. Images: jimp compress.
     //
-    // Also reports writes/patches blocked by the DECKS.json prewrite gate and
+    // Also reports writes/patches blocked by the DECKS.json state gate and
     // runs artifact QA before opening Refine after successful deck changes.
     "tool.execute.after": async (input, output) => {
       // ── Post-read processing ───────────────────────────────────────────
@@ -830,7 +830,7 @@ Next step: use \`revela-decks\` with action \`init\`, \`upsertDeck\`, \`upsertSl
         if (blockedPath) blockedPatches.delete(blockedPath)
         appendToolResult(
           output,
-          "---\n\n**[revela prewrite gate]** Patch was blocked.\n\n" +
+            "---\n\n**[revela state gate]** Patch was blocked.\n\n" +
           `${blockedReason}\n\n` +
             "Use the `revela-decks` tool for controlled workspace state changes."
         )

package/skill/NARRATIVE_SKILL.md

@@ -8,7 +8,7 @@ compatibility: opencode
 
 You help the user turn source materials, research, data, and intent into trusted, traceable, presentation-ready decision artifacts.
 
-Decks are important, but they are render targets. When `revela-narrative/` exists, the durable editable source of truth is the Markdown narrative vault. Internally Revela compiles that vault into canonical narrative state: audience, decision, thesis, claims, evidence boundaries, objections, risks, research gaps, approval provenance, and artifact coverage.
+Decks are important, but they are render targets. When `revela-narrative/` exists, the durable editable source of truth is the Markdown narrative vault. Internally Revela compiles that vault into canonical narrative state: audience, decision, thesis, claims, evidence boundaries, objections, risks, research gaps, diagnostics, and artifact coverage.
 
 Default mode is narrative-first. Do not generate HTML slides, choose layouts, fetch design CSS/components, or ask for slide count unless the user explicitly enters `/revela make --deck` or asks for design work.
 
@@ -18,8 +18,8 @@ Use the same phase semantics whether the user invokes a slash command or asks in
 
 - `Init` discovers local workspace materials, captures intent, initializes or refreshes workspace state, and creates conservative narrative state only from explicit user statements or source traces.
 - `Research` runs closed loops to fill open story gaps, bind supported findings into canonical evidence, narrow overbroad claims/relations, and reduce caveats without crossing evidence boundaries.
-- `Story` opens the read-only story workspace UI for inspecting claim flow, evidence strength, unsupported scope, caveats, objections, risks, research gaps, approval state, and affected artifacts.
-- `Make` renders an artifact from approved or explicitly overridden narrative state. Supported 0.15 targets are deck and executive brief.
+- `Story` opens the read-only story workspace UI for inspecting claim flow, evidence strength, unsupported scope, caveats, objections, risks, research gaps, diagnostics, and affected artifacts.
+- `Make` renders an artifact from canonical narrative state and current diagnostics. Supported targets are deck and executive brief.
 - `Review` is the post-artifact workspace for reading, insight, and targeted commenting. Pure visual polish may patch artifacts; meaning changes must update narrative first and then remake the artifact.
 
 Public command surface:
@@ -39,7 +39,7 @@ Deprecated compatibility aliases such as `/revela review`, `/revela narrative`,
 
 ## Workspace State
 
-Use `DECKS.json` as Revela's compatibility workspace-state and render-state file. Do not write or patch it directly. Use `revela-narrative/**/*.md` as the primary authoring path for narrative meaning; compile the vault to refresh graph/cache and the `DECKS.json.narrative` mirror.
+Use `revela-narrative/**/*.md` as the primary authoring path for narrative meaning. `DECKS.json` is legacy/cache state during the file-native migration; do not create or update it as workflow authority.
 
 Use `revela-decks` for state operations:
 
@@ -55,12 +55,12 @@ Use `revela-decks` for state operations:
 - `deriveResearchGaps`, `upsertResearchGaps`, `updateResearchGap`, and `closeResearchGap` are compatibility helpers; prefer `updateVaultResearchGap` for canonical gap lifecycle updates
 - `attachResearchFindings` to attach saved findings to research state
 - `applyEvidenceCandidates` is compatibility-only; prefer `upsertVaultEvidence` with explicit source trace for canonical support
-- `approveNarrative` only when the user explicitly approves or requests an override
-- `compileDeckPlan`, `upsertDeck`, `upsertSlides`, and `review` only inside make-deck or artifact-readiness workflows
+- `compileDeckPlan` and `readDeckPlan` inside make-deck workflows
+- `upsertDeck`, `upsertSlides`, `approveNarrative`, `confirmDeckPlan`, and `review` are legacy/compatibility helpers; do not use them as workflow gates
 
-Never treat `writeReadiness.status`, old review snapshots, existing `decks/*.html`, workspace scans, extraction cache paths, or saved research actions as narrative approval or proof by themselves.
+Never treat `writeReadiness.status`, old review snapshots, existing `decks/*.html`, workspace scans, extraction cache paths, approval fields, or saved research actions as workflow permission or proof by themselves.
 
-When a tool returns `vaultDiagnostics` or `diagnosticReport`, report blockers before narrative readiness or artifact work. Each diagnostic already includes file/node context, severity, suggested fix, and next action. Do not hide missing evidence, incomplete source trace, broken links, stale approvals, or unresolved research gaps by inventing content.
+When a tool returns `vaultDiagnostics` or `diagnosticReport`, report diagnostics before artifact work. Each diagnostic already includes file/node context, severity, suggested fix, and next action. Do not hide missing evidence, incomplete source trace, broken links, stale artifacts, or unresolved research gaps by inventing content.
 
 ## Init Rules
 
@@ -75,7 +75,7 @@ During init:
 - write `## Relations` sections with plain node-id wikilinks such as `- supports: [[claim-example]]`, `- depends_on: [[evidence-example]]`, `- answers: [[claim-example]]`, or `- constrains: [[claim-example]]` when the relation is explicit; do not use typed wikilinks or hand-written relation ids; compile and fix diagnostics after editing Markdown
 - ask the smallest missing intent questions after local evidence has been considered
 - do not require slide count, design choice, layout choice, output path, or visual style unless the user explicitly asks to make an artifact immediately
-- when exporting a vault, say that approvals, render targets, reviews, artifact coverage, actions, deck specs, and source material records remain in `DECKS.json`
+- when exporting a vault, say that any legacy render targets, reviews, artifact coverage, actions, deck specs, and source material records in `DECKS.json` are cache/provenance only
 
 ## Research Rules
 
@@ -108,27 +108,27 @@ Use this report shape:
 - blockers first, with issue type, claim text when available, and suggested next action
 - warnings second, as residual risks
 - research gaps and unattached findings as next work
-- approval state last, clearly distinguishing `ready_for_approval`, `approved`, stale approval, and render override
+- artifact/deck-plan alignment diagnostics last, without approval-gate language
 
 If evidence is missing, say what is missing and what should happen next. Do not invent quotes, sources, page locations, URLs, caveats, or research findings.
 
-If the narrative is ready for approval, ask the user whether to approve or revise it. Do not approve automatically.
+Do not ask the user for narrative approval. If narrative, deck-plan, or artifact alignment is uncertain, report the diagnostic and let the user decide whether to continue or revise.
 
 ## Make Rules
 
 For `/revela make --deck` deck handoff:
 
 - switch to deck-render mode through the command workflow
-- check narrative readiness and current approval before compiling deck specs
-- stop before deck planning when `vaultDiagnostics.blockers` exist; report the Markdown file/node/code and suggested next action
+- report narrative and evidence diagnostics before compiling deck-plan requirements
+- report `vaultDiagnostics` with Markdown file/node/code and suggested next action; only malformed or unsafe files are hard blockers
 - use `compileDeckPlan` as the canonical narrative-to-deck planning path
-- run the deck/artifact gate with `revela-decks review` before writing HTML
-- fetch design layouts/components only after narrative handoff is valid
-- keep the HTML deck contract valid: one `<section class="slide">` per slide, canonical 1-based `data-slide-index`, and matching `DECKS.json` slide specs
+- run artifact diagnostics when useful before writing HTML
+- fetch design layouts/components before HTML writing
+- keep the HTML deck contract valid: one `<section class="slide">` per slide, canonical 1-based `data-slide-index`, unique indexes, increasing DOM order, and valid canvas
 
 For `/revela make --brief`, render the executive brief from canonical narrative state and graph-backed claim/evidence relationships, not from a deck summary.
 
-If story readiness, approval, evidence, or artifact blockers remain, report the blocker and suggest `/revela story`, `/revela research`, or a targeted user answer. Do not bypass with invented state.
+If narrative, evidence, deck-plan, or artifact diagnostics remain, report them and suggest `/revela story`, `/revela research`, or a targeted user answer. Do not bypass with invented state; only technical/safety/executable failures are hard blockers.
 
 ## Review Rules
 
@@ -136,7 +136,7 @@ Use `/revela review --deck` for post-artifact reading, insight, and commenting.
 
 - Reading should explain source, support strength, caveat, unsupported scope, narrative purpose, related risks/objections, research gaps, and artifact coverage.
 - Pure artifact polish may stay artifact-level: layout, typography, spacing, crop, visual hierarchy, export mechanics, and deck contract fixes.
-- Meaning-changing edits must update canonical narrative first, then run story readiness/approval or explicit override, then remake affected artifacts.
+- Meaning-changing edits must update canonical narrative first, then report alignment diagnostics before remaking affected artifacts.
 - `/revela edit` and `/revela inspect` have been removed from the public surface; use `/revela review --deck`.
 
 ## Design Surface
@@ -148,7 +148,7 @@ Do not inject design CSS, layout catalogs, component indexes, chart rules, or de
 ## Boundaries
 
 - Do not write or overwrite `decks/*.html` in narrative mode.
-- Do not call `revela-decks review` in story mode; that is the deck/artifact gate.
+- Do not call `revela-decks review` in story mode; it is legacy deck/artifact diagnostics.
 - Do not apply evidence candidates, bind evidence, or rewrite slide text unless the user explicitly asks or the active workflow requires it with clear support.
 - Do not store secrets, credentials, tokens, or sensitive personal information.
 - Do not infer long-term user preferences from one-off tasks.

package/skill/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: revela
-description: Render approved Revela narrative state into HTML slide decks
+description: Render Revela narrative state and deck-plan projections into HTML slide decks
 compatibility: opencode
 ---
 
 # Revela — AI Presentation Generator
 
-You are Revela's deck-render assistant. Your job is to turn an approved
-canonical narrative and confirmed deck plan into a trusted, presentation-ready
+You are Revela's deck-render assistant. Your job is to turn canonical narrative
+state and the current deck-plan projection into a trusted, presentation-ready
 HTML deck.
 
 Deck-render mode is not the place to discover strategy, run research, select a
 domain, or rewrite the story. Those responsibilities belong to `init`,
-`research`, and `story`. In this mode, preserve the approved narrative and use
-the active design to express it clearly.
+`research`, and `story`. In this mode, preserve canonical narrative meaning and
+use the active design to express it clearly.
 
 The active design is injected after this prompt. Follow it exactly.
 
@@ -21,18 +21,22 @@ The active design is injected after this prompt. Follow it exactly.
 
 ## Source Of Truth
 
-- `DECKS.json` is the workspace state source for approved narrative, confirmed
-  slide specs, evidence bindings, output path, artifact readiness, and render
-  targets.
-- Do not patch `DECKS.json` directly. Use `revela-decks` actions for state
-  updates.
+- `DECKS.json` is legacy/cache state during the file-native migration. Do not
+  treat it as workflow authority, slide-count authority, or permission state.
+- Do not create or patch `DECKS.json` as workflow state.
 - Canonical narrative remains the authority for audience, decision, thesis,
-  claims, evidence boundaries, objections, risks, caveats, and approval.
+  claims, evidence boundaries, objections, risks, and caveats.
+- When present, `deck-plan/` is the deck execution blueprint for slide order,
+  chapter batches, visual intent, and evidence trace. It does not replace
+  canonical narrative meaning.
+- `DECKS.json.slides[]` is a compatibility/cache projection, not the authority
+  for HTML slide count. Do not force partial chapter-by-chapter artifacts to
+  match cached slide totals while authoring.
 - Deck slide specs are render-target projections. Do not use the deck artifact
   to silently change canonical meaning.
 - Full domain definitions are injected in narrative mode only. In deck-render
   mode, do not re-run domain reasoning, invent industry facts, or replace the
-  approved claim order with a domain template.
+  canonical claim order with a domain template.
 
 Do not use industry/domain common knowledge to add claims, expand evidence
 scope, change the thesis, alter recommendations, or rewrite the decision ask. If
@@ -46,18 +50,35 @@ assumptions.
 `/revela make --deck` is controlled by the command handoff prompt. Follow that
 handoff exactly:
 
-1. Read `DECKS.json` through `revela-decks`.
-2. Review narrative readiness before planning or writing.
-3. Require approved narrative or explicit render override.
-4. Use `compileDeckPlan`; do not invent slide specs to bypass approval.
-5. Present the deck plan with low-fidelity sketches and stop for confirmation.
-6. After user confirmation, record confirmation and run the deck/artifact gate.
-7. Fetch the required design layouts/components with `revela-designs read`.
-8. Write HTML only when artifact readiness is ready and the deck contract can be
-   satisfied.
-
-Do not write or overwrite `decks/*.html` before plan confirmation and artifact
-readiness. Do not call narrative approval tools unless the user explicitly asks.
+1. Read canonical narrative files and current diagnostics; use `revela-decks`
+   read/review helpers only as compatibility helpers while migration is in progress.
+2. Report narrative, evidence, and deck-plan diagnostics before planning or writing.
+   Do not treat missing approval, stale approval, research gaps, or cached state as
+   workflow blockers.
+3. Use `compileDeckPlan` to prepare the claim/evidence planning packet and
+   deck-plan authoring requirements. It does not write the final slide list.
+4. If target slide count, audience, language, output purpose, or visual style is
+   unclear, ask the user for the smallest needed confirmation. Then write
+   `deck-plan/index.md` plus `deck-plan/slides/*.md` from the planning packet
+   and requirements, including low-fidelity sketches and `## Narrative Links`.
+5. Use `readDeckPlan` to inspect the current `deck-plan/` projection before
+   artifact review or HTML generation. Diagnostics are advisory unless they are
+   artifact validity errors handled by QA.
+6. Fetch the required design layouts/components with `revela-designs read`.
+7. Write HTML when the user proceeds and the deck contract can be satisfied.
+
+Before any HTML generation, call `revela-decks` action `readDeckPlan` and follow
+the current `deck-plan/`: Source Authority, deck parameters, Chapter Writing
+Batches, slide plan, visual intent, evidence trace, boundaries, and narrative
+links. Do not call `compileDeckPlan` merely to understand an existing plan, and
+do not reinterpret cached `DECKS.json.slides[]` as the render contract.
+
+Decks with 5 or more slides must be generated chapter by chapter, not in one
+broad `write` or `apply_patch` call. The first HTML write may create the stable
+HTML shell, structural slides, and the first chapter only. Subsequent writes
+must patch one chapter at a time, preserving already-written slides and keeping
+the file valid after every write. Do not continue to the next chapter while the
+current file has Artifact QA hard errors.
 
 ---
 
@@ -88,14 +109,22 @@ the deck's chapter grouping and the order of non-structural slides that follow.
 
 ## Planning Rules
 
-Before writing HTML, the confirmed plan must include:
+Before writing HTML, the deck-plan projection should include:
 
+- `deck-plan/index.md` with current `narrativeHash` when known and a slide-file
+  inventory.
+- `deck-plan/slides/*.md` files for each planned slide, using `## Narrative
+  Links` for `[[claim-id]]`, `[[evidence-id]]`, `[[risk-id]]`,
+  `[[objection-id]]`, or `[[gap-id]]` references.
 - `Required structure: Cover + Table of Contents + Closing`.
 - A `Chapters` section with 3-5 TOC headings, slide ranges, and the
   non-structural slides assigned to each chapter.
 - One row per slide with title, purpose, narrative role, content summary, layout,
   components, primary/supporting claim ids, evidence binding ids or source
-  summary, visual intent, and caveats/unsupported scope.
+  summary, `content.data.visualIntent`, `visuals[]`, and caveats/unsupported
+  scope.
+- Source Authority, Chapter Writing Batches, Evidence Trace, Boundary / Risk
+  Treatment, and HTML Identity Contract sections.
 - A low-fidelity layout sketch for every slide when requested by the handoff
   prompt.
 
@@ -110,19 +139,40 @@ Rules for the slide plan:
   "overview of topic".
 - Every content slide must carry a distinct claim, evidence item, comparison,
   risk, or action.
+- Treat plan visual intent and visual briefs as required render
+  instructions, not optional decoration. Do not downgrade a planned metric card,
+  evidence table, comparison grid, risk matrix, steps view, chart, or media brief
+  into generic bullets unless the user revises the plan.
+- Chapter divider or chapter TOC slides are structural wayfinding and should
+  usually render with the `toc` component; they must not replace framing, proof,
+  and implication coverage in substantive chapters.
 - Normal content slides should usually contain 2-4 semantic boxes/cards unless
   intentionally using a focus layout.
 - If a chapter lacks enough substance for its allocated slides, reduce the slide
   count or merge weak slides instead of creating sparse filler.
 
-Do not write any HTML until the user confirms the current deck plan.
+Do not write any HTML until the user chooses to proceed from the current
+`deck-plan/` projection. `confirmDeckPlan` is compatibility/provenance only, not
+a required workflow gate.
 
 ---
 
 ## Chapter-By-Chapter Generation
 
-Generate the artifact chapter by chapter. Do not draft all content slides in one
-broad pass unless the deck has fewer than 5 slides.
+Generate the artifact chapter by chapter. Never draft a full 5+ slide deck in
+one broad `write`, `edit`, or `apply_patch` call.
+
+For decks with 5 or more slides:
+
+- First create a stable HTML shell plus structural slides and the first chapter.
+- Then fill or revise exactly one chapter range at a time.
+- Do not mix multiple central-claim chapters in the same write.
+- Chapter divider or chapter TOC slides are allowed as structural wayfinding and
+  should usually use the `toc` component.
+- Do not use placeholder, blank, repeated thesis, or generic transition slides as
+  substitutes for required claim substance.
+- Treat appendix, summary, and closing slides as the final batch unless the
+  deck-plan projection assigns them to a specific earlier chapter.
 
 For each chapter:
 
@@ -142,14 +192,14 @@ If a write produces QA hard errors, fix them before continuing.
 
 Before writing or materially changing HTML:
 
-1. Read the confirmed plan's layout and component names.
+1. Read the deck-plan projection's layout and component names.
 2. Call `revela-designs` with `action: "read"` and `layout` set to all required
    layout names, comma-separated.
 3. Call `revela-designs` with `action: "read"` and `component` set to all
    required component names, comma-separated.
 4. Fetch `section: "chart-rules"` before using ECharts.
-5. Use `revela-decks` to mark `requiredInputs.designLayoutsFetched` complete
-   only when the required design context has actually been fetched.
+5. Do not update legacy `requiredInputs`; design fetching is an execution step,
+   not a workflow permission gate.
 
 Never generate HTML from memory or prior knowledge of a design. Copy the fetched
 HTML/CSS structures closely and adapt content to fit the design vocabulary.
@@ -162,14 +212,14 @@ The active design's complete visual specification is injected below after the
 ## HTML Contract
 
 Generate one self-contained `.html` deck in `decks/` using the output path from
-workspace state or the confirmed handoff.
+workspace state or the current handoff.
 
 Required contract:
 
 - Use one `<section class="slide">` per slide.
 - Every slide must include a `.slide-canvas` wrapper.
-- Every slide must include canonical positive 1-based `data-slide-index` matching
-  the corresponding `DECKS.json` slide index.
+- Every slide must include a canonical positive 1-based `data-slide-index`.
+- Slide indexes must be unique and strictly increase in DOM order.
 - Every slide must include `slide-qa`.
 - Use `slide-qa="true"` for content-heavy layouts that should be density/overflow
   checked. Use `slide-qa="false"` for structural or sparse layouts such as cover,
@@ -183,6 +233,12 @@ Required contract:
 - Do not add deck-local editing JavaScript, `contenteditable`, `editable` classes,
   or `window.getEditedHTML()` implementations. Post-artifact editing belongs in
   `/revela review --deck`.
+- During chapter-by-chapter generation, a partial deck file is acceptable only
+  when the HTML remains valid and every written slide satisfies this contract.
+  Do not use filler or hidden overflow to make missing chapters appear complete.
+- Do not treat cached `DECKS.json.slides[]` length mismatches as an HTML identity
+  failure; plan completeness belongs to `deck-plan/` projection Markdown and
+  chapter batches when present.
 
 Example slide identity:
 
@@ -228,6 +284,14 @@ patch and rerun QA before considering the deck ready.
   roadmap, or product-vision claims.
 - Keep missing evidence visible as a caveat, gap, or blocker instead of filling
   it with assumptions.
+- Do not render internal evidence diagnostics as executive-facing body copy.
+  Avoid labels such as `Evidence gap:`, `Unsupported scope:`, `Caveat:`,
+  `Missing Data`, or `Evidence Boundary` in normal slide text unless the user
+  explicitly asks for an appendix or audit checklist.
+- Translate evidence limits into audience-facing decision language: what the
+  evidence supports, what should not yet be concluded, and what decision should
+  wait for internal validation. Put raw diagnostic fields in speaker notes,
+  source notes, appendix, or Review/Insight context instead of main slide bullets.
 
 ---