@cyber-dash-tech/revela 0.16.4 → 0.17.0

package/lib/source-materials.ts

@@ -46,6 +46,103 @@ export function sourceMaterialMetadata(filePath: string, workspaceRoot: string):
     type: sourceMaterialType(resolvedFile),
     size: stat.size,
     fingerprint: computeSourceFingerprint(resolvedFile),
+    lastModified: new Date(stat.mtimeMs).toISOString(),
+  }
+}
+
+export function sourceMaterialModifiedMs(material: SourceMaterial, workspaceRoot: string): number {
+  if (material.lastModified) {
+    const parsed = Date.parse(material.lastModified)
+    if (Number.isFinite(parsed)) return parsed
+  }
+
+  try {
+    return statSync(ensureWorkspaceFile(material.path, workspaceRoot)).mtimeMs
+  } catch {
+    return 0
+  }
+}
+
+export interface SourceMaterialIngestPlan {
+  vaultTimestamp: string | null
+  vaultTimestampMs: number
+  addedSourceMaterials: SourceMaterial[]
+  changedSourceMaterials: SourceMaterial[]
+  newerThanVaultSourceMaterials: SourceMaterial[]
+  unchangedSourceMaterials: SourceMaterial[]
+  ingestCandidates: SourceMaterial[]
+  suggestedTasks: SourceMaterialIngestTask[]
+}
+
+export interface SourceMaterialIngestTask {
+  path: string
+  reason: Array<"added" | "changed" | "newer_than_vault">
+  materialType: string
+  needsExtraction: boolean
+  suggestedAction: "read_directly" | "extract_then_read"
+  note: string
+}
+
+export function classifySourceMaterialIngest(
+  state: DecksState,
+  materials: SourceMaterial[],
+  workspaceRoot: string,
+  vaultTimestampMs: number,
+): SourceMaterialIngestPlan {
+  const existingByPath = new Map((state.workspace.sourceMaterials ?? []).map((item) => [item.path.replace(/\\/g, "/"), item]))
+  const addedSourceMaterials: SourceMaterial[] = []
+  const changedSourceMaterials: SourceMaterial[] = []
+  const newerThanVaultSourceMaterials: SourceMaterial[] = []
+  const unchangedSourceMaterials: SourceMaterial[] = []
+  const ingestByPath = new Map<string, SourceMaterial>()
+  const reasonsByPath = new Map<string, SourceMaterialIngestTask["reason"]>()
+
+  for (const material of materials) {
+    const path = material.path.replace(/\\/g, "/")
+    const existing = existingByPath.get(path)
+    const added = !existing
+    const changed = Boolean(existing?.fingerprint && material.fingerprint && existing.fingerprint !== material.fingerprint)
+    const newerThanVault = sourceMaterialModifiedMs(material, workspaceRoot) > vaultTimestampMs
+    const reasons: SourceMaterialIngestTask["reason"] = []
+
+    if (added) addedSourceMaterials.push(material)
+    if (changed) changedSourceMaterials.push(material)
+    if (newerThanVault) newerThanVaultSourceMaterials.push(material)
+    if (added) reasons.push("added")
+    if (changed) reasons.push("changed")
+    if (newerThanVault) reasons.push("newer_than_vault")
+    if (added || changed || newerThanVault) {
+      ingestByPath.set(path, material)
+      reasonsByPath.set(path, reasons)
+    }
+    else unchangedSourceMaterials.push(material)
+  }
+  const ingestCandidates = [...ingestByPath.values()].sort((a, b) => a.path.localeCompare(b.path))
+
+  return {
+    vaultTimestamp: vaultTimestampMs > 0 ? new Date(vaultTimestampMs).toISOString() : null,
+    vaultTimestampMs,
+    addedSourceMaterials,
+    changedSourceMaterials,
+    newerThanVaultSourceMaterials,
+    unchangedSourceMaterials,
+    ingestCandidates,
+    suggestedTasks: ingestCandidates.map((material) => sourceMaterialIngestTask(material, reasonsByPath.get(material.path.replace(/\\/g, "/")) ?? [])),
+  }
+}
+
+function sourceMaterialIngestTask(material: SourceMaterial, reason: SourceMaterialIngestTask["reason"]): SourceMaterialIngestTask {
+  const materialType = (material.type || sourceMaterialType(material.path)).toLowerCase()
+  const needsExtraction = ["pdf", "ppt", "pptx", "doc", "docx", "xls", "xlsx"].includes(materialType)
+  return {
+    path: material.path,
+    reason,
+    materialType,
+    needsExtraction,
+    suggestedAction: needsExtraction ? "extract_then_read" : "read_directly",
+    note: needsExtraction
+      ? "Use revela-extract-document-materials before synthesizing stable narrative findings when this file is relevant."
+      : "Read directly when relevant and distill stable narrative findings into the Markdown vault.",
   }
 }
 
@@ -77,6 +174,7 @@ export function upsertSourceMaterial(
     path,
     type: material.type ?? existing?.type,
     status: nextStatus,
+    lastModified: material.lastModified ?? existing?.lastModified,
     firstSeen: existing?.firstSeen ?? material.firstSeen ?? now,
     lastChecked: now,
   }

package/lib/tool-result.ts

@@ -0,0 +1,34 @@
+export function appendToolResult(output: any, text: string): void {
+  if (!output || typeof output !== "object") return
+
+  if (typeof output.output === "string") {
+    output.output = appendText(output.output, text)
+    return
+  }
+
+  if (typeof output.result === "string") {
+    output.result = appendText(output.result, text)
+    return
+  }
+
+  if (typeof output.text === "string") {
+    output.text = appendText(output.text, text)
+    return
+  }
+
+  if (typeof output.message === "string") {
+    output.message = appendText(output.message, text)
+    return
+  }
+
+  if (Array.isArray(output.content)) {
+    output.content.push({ type: "text", text })
+    return
+  }
+
+  output.output = text
+}
+
+function appendText(existing: string, text: string): string {
+  return (existing ? `${existing}\n\n` : "") + text
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.16.4",
-  "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
+  "version": "0.17.0",
+  "description": "OpenCode plugin for trusted narrative artifacts from local sources, research, and evidence",
   "type": "module",
   "main": "./index.ts",
   "exports": {

package/plugin.ts

@@ -72,6 +72,11 @@ import {
   hasDecksState,
   isDecksStatePath,
 } from "./lib/decks-state"
+import { autoCompileNarrativeVault } from "./lib/narrative-vault/auto-compile"
+import {
+  extractNarrativeVaultMarkdownTargetsFromPatch,
+  normalizeNarrativeVaultMarkdownPath,
+} from "./lib/narrative-vault/hook-targets"
 import decksTool from "./tools/decks"
 import designsAuthorTool from "./tools/designs-author"
 import designsTool from "./tools/designs"
@@ -93,6 +98,8 @@ import { RESEARCH_PROMPT, RESEARCH_AGENT_SIGNATURE } from "./lib/agents/research
 import { NARRATIVE_REVIEWER_PROMPT, NARRATIVE_REVIEWER_SIGNATURE } from "./lib/agents/narrative-reviewer-prompt"
 import { extractDesignClasses } from "./lib/design/designs"
 import { log, childLog } from "./lib/log"
+import { appendToolResult } from "./lib/tool-result"
+import { formatArtifactQaUserNotice, formatMarkdownQaUserNotice, formatStateGateUserNotice } from "./lib/hook-notifications"
 
 // OpenCode internal agent signatures — used to skip system prompt injection
 // for built-in system agents (title, summary, compaction).
@@ -102,16 +109,6 @@ const INTERNAL_AGENT_SIGNATURES = [
   "Summarize what was done in this conversation",
 ]
 
-function appendToolResult(output: any, text: string): void {
-  if (typeof output.output === "string") {
-    output.output = (output.output ? output.output + "\n\n" : "") + text
-    return
-  }
-
-  const existing = output.result ?? ""
-  output.result = (existing ? existing + "\n\n" : "") + text
-}
-
 function extractEditFilePath(args: any): string {
   return args?.filePath ?? args?.file_path ?? args?.path ?? args?.file ?? ""
 }
@@ -148,7 +145,7 @@ const server: Plugin = (async (pluginCtx) => {
   const blockedDeckWrites = new Map<string, string>()
   const blockedPatches = new Map<string, string>()
 
-  async function runPostWriteArtifactQA(filePath: string, output: any): Promise<boolean> {
+  async function runPostWriteArtifactQA(filePath: string, output: any, sessionID = ""): Promise<boolean> {
     if (!isDeckHtmlPath(filePath)) return true
 
     try {
@@ -161,6 +158,8 @@ const server: Plugin = (async (pluginCtx) => {
 
       const report = await runArtifactQA({ workspaceRoot, filePath, vocabulary })
       appendToolResult(output, "---\n\n" + formatArtifactQAReport(report))
+      const notice = formatArtifactQaUserNotice(report)
+      if (notice && sessionID) await sendIgnoredMessage(client, sessionID, notice)
       return report.passed
     } catch (e) {
       childLog("artifact-qa").warn("post-write artifact QA failed", {
@@ -168,10 +167,27 @@ const server: Plugin = (async (pluginCtx) => {
         error: e instanceof Error ? e.message : String(e),
       })
       appendToolResult(output, "---\n\n## Artifact QA: FAILED\n\nError running artifact QA: " + (e instanceof Error ? e.message : String(e)))
+      if (sessionID) await sendIgnoredMessage(client, sessionID, `**Artifact QA failed**\nFile: \`${filePath}\`\nError: ${e instanceof Error ? e.message : String(e)}`)
       return false
     }
   }
 
+  async function runPostWriteNarrativeVaultCompile(touched: string[], output: any, sessionID = ""): Promise<void> {
+    if (touched.length === 0) return
+
+    const result = autoCompileNarrativeVault(workspaceRoot, touched)
+    appendToolResult(output, "---\n\n" + result.markdown)
+    const notice = formatMarkdownQaUserNotice(result)
+    if (notice && sessionID) await sendIgnoredMessage(client, sessionID, notice)
+    if (!result.ok) {
+      childLog("narrative-vault").warn("auto-compile reported blockers", {
+        touched,
+        mirror: result.mirrored,
+        error: result.error,
+      })
+    }
+  }
+
   function extractSessionID(input: any): string {
     return input?.sessionID ?? input?.session?.id ?? input?.context?.sessionID ?? ""
   }
@@ -314,6 +330,17 @@ const server: Plugin = (async (pluginCtx) => {
         await handleHelp(send)
         throw new Error("__REVELA_STATUS_HANDLED__")
       }
+      if (sub === "enable") {
+        ctx.enabled = true
+        buildPrompt()
+        await send("Revela enabled. Workflow commands and Revela context are active.")
+        throw new Error("__REVELA_ENABLE_HANDLED__")
+      }
+      if (sub === "disable") {
+        ctx.enabled = false
+        await send("Revela disabled. Run `/revela enable` or any workflow command to reactivate.")
+        throw new Error("__REVELA_DISABLE_HANDLED__")
+      }
       if (sub === "make") {
         const target = args[1]?.toLowerCase() ?? ""
         const makeParam = args.slice(2).join(" ")
@@ -500,7 +527,7 @@ const server: Plugin = (async (pluginCtx) => {
         throw new Error("__REVELA_DOMAIN_USAGE_HANDLED__")
       }
       const legacyCommands = new Set([
-        "enable", "disable", "review", "narrative", "deck", "brief", "edit", "inspect", "remember",
+        "review", "narrative", "deck", "brief", "edit", "inspect", "remember",
         "designs", "designs-new", "designs-edit", "designs-preview", "designs-add", "designs-rm",
         "domains", "domains-add", "domains-rm", "pdf", "pptx",
       ])
@@ -689,8 +716,6 @@ const server: Plugin = (async (pluginCtx) => {
     // - write/apply_patch: protect DECKS.json, but do not block deck HTML edits.
     "tool.execute.before": async (input, output) => {
       log.info("[hook] tool.execute.before fired", { tool: input.tool, enabled: ctx.enabled, isResearch: ctx.isResearchAgent })
-      if (!ctx.enabled) return
-
       if (input.tool === "write") {
         const filePath: string = (output.args as any)?.filePath ?? ""
         if (isDecksStatePath(filePath)) {
@@ -741,6 +766,8 @@ Next step: use \`revela-decks\` with action \`init\`, \`upsertDeck\`, \`upsertSl
         }
       }
 
+      if (!ctx.enabled) return
+
       if (input.tool === "read") {
         try {
           await preRead(output.args)
@@ -760,10 +787,9 @@ Next step: use \`revela-decks\` with action \`init\`, \`upsertDeck\`, \`upsertSl
     // Also reports writes/patches blocked by the DECKS.json prewrite gate and
     // runs artifact QA before opening Refine after successful deck changes.
     "tool.execute.after": async (input, output) => {
-      if (!ctx.enabled) return
-
       // ── Post-read processing ───────────────────────────────────────────
       if (input.tool === "read") {
+        if (!ctx.enabled) return
         try {
           await postRead(input.args, output)
         } catch (e) {
@@ -787,39 +813,51 @@ Next step: use \`revela-decks\` with action \`init\`, \`upsertDeck\`, \`upsertSl
             `${blockedReason}\n\n` +
             "Use the `revela-decks` tool or complete the DECKS.json review workflow instead."
           )
+          await sendIgnoredMessage(client, extractSessionID(input), formatStateGateUserNotice("write", blockedReason))
           return
         }
-        const qaPassed = await runPostWriteArtifactQA(filePath, output)
+        const vaultTarget = normalizeNarrativeVaultMarkdownPath(filePath, workspaceRoot)
+        const sessionID = extractSessionID(input)
+        if (vaultTarget) await runPostWriteNarrativeVaultCompile([vaultTarget], output, sessionID)
+        const qaPassed = await runPostWriteArtifactQA(filePath, output, sessionID)
         if (qaPassed) ensureRefineOpenAfterDeckChange(filePath, extractSessionID(input))
         return
       }
 
       if (input.tool === "apply_patch" && blockedPatches.size > 0) {
         const [blockedPath, blockedReason] = blockedPatches.entries().next().value ?? []
+        if (!blockedPath || !blockedReason) return
         if (blockedPath) blockedPatches.delete(blockedPath)
         appendToolResult(
           output,
           "---\n\n**[revela prewrite gate]** Patch was blocked.\n\n" +
           `${blockedReason}\n\n` +
-          "Use the `revela-decks` tool for controlled workspace state changes."
+            "Use the `revela-decks` tool for controlled workspace state changes."
         )
+        await sendIgnoredMessage(client, extractSessionID(input), formatStateGateUserNotice("patch", blockedReason))
         return
       }
 
       if (input.tool === "apply_patch") {
         const patchText = extractPatchTextArg(input.args as Record<string, unknown>)
+        const vaultTargets = patchText ? extractNarrativeVaultMarkdownTargetsFromPatch(patchText, workspaceRoot) : []
+        const sessionID = extractSessionID(input)
+        await runPostWriteNarrativeVaultCompile(vaultTargets, output, sessionID)
         const targets = patchText ? extractDeckHtmlTargetsFromPatch(patchText) : []
         for (const target of targets) {
-          const qaPassed = await runPostWriteArtifactQA(target, output)
-          if (qaPassed) ensureRefineOpenAfterDeckChange(target, extractSessionID(input))
+          const qaPassed = await runPostWriteArtifactQA(target, output, sessionID)
+          if (qaPassed) ensureRefineOpenAfterDeckChange(target, sessionID)
         }
         return
       }
 
       if (input.tool === "edit") {
         const filePath = extractEditFilePath(input.args)
-        const qaPassed = await runPostWriteArtifactQA(filePath, output)
-        if (qaPassed) ensureRefineOpenAfterDeckChange(filePath, extractSessionID(input))
+        const vaultTarget = normalizeNarrativeVaultMarkdownPath(filePath, workspaceRoot)
+        const sessionID = extractSessionID(input)
+        if (vaultTarget) await runPostWriteNarrativeVaultCompile([vaultTarget], output, sessionID)
+        const qaPassed = await runPostWriteArtifactQA(filePath, output, sessionID)
+        if (qaPassed) ensureRefineOpenAfterDeckChange(filePath, sessionID)
         return
       }
     },

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. The durable source of truth is the 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, approval provenance, 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.
 
@@ -16,7 +16,7 @@ Default mode is narrative-first. Do not generate HTML slides, choose layouts, fe
 
 Use the same phase semantics whether the user invokes a slash command or asks in normal chat:
 
-- `Init` discovers local workspace materials, captures intent, initializes or refreshes `DECKS.json`, and creates conservative narrative state only from explicit user statements or source traces.
+- `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.
@@ -39,32 +39,43 @@ Deprecated compatibility aliases such as `/revela review`, `/revela narrative`,
 
 ## Workspace State
 
-Use `DECKS.json` as Revela's current compatibility workspace-state file. Do not write or patch it directly.
+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-decks` for state operations:
 
 - `read` to inspect current workspace state
+- `read` with `summary: true` to inspect compact deck state plus `vaultDiagnostics` when a Markdown vault exists and `migration` guidance when JSON narrative state can be exported to a vault
 - `init` to register discovered source material candidates during workspace initialization
-- `upsertNarrative` to preserve canonical audience, decision, thesis, claims, evidence bindings, objections, risks, and research gaps
+- `initNarrativeVault` to create `revela-narrative/` and draft core Markdown files before writing canonical narrative meaning in a new workspace
+- `exportNarrativeVault` to export existing `DECKS.json.narrative` into `revela-narrative/` when no vault exists; its result states which Markdown files were written and which provenance/render fields remain in `DECKS.json`
+- `compileNarrativeVault` to compile Markdown vault nodes, refresh cache, and mirror compiled narrative into `DECKS.json`
+- `updateVaultCoreNarrative`, `upsertVaultClaim`, `upsertVaultEvidence`, `upsertVaultObjection`, `upsertVaultRisk`, and `updateVaultResearchGap` are deterministic helper actions for common Markdown vault edits; prefer direct Markdown node edits when you can preserve surrounding content safely
+- `upsertNarrative` is deprecated and should not be used; create or update canonical narrative meaning through Markdown vault files, then compile
 - `reviewNarrative` to run deterministic story readiness
-- `deriveResearchGaps`, `upsertResearchGaps`, `updateResearchGap`, and `closeResearchGap` to manage research gap lifecycle
+- `deriveResearchGaps`, `upsertResearchGaps`, `updateResearchGap`, and `closeResearchGap` are compatibility helpers; prefer `updateVaultResearchGap` for canonical gap lifecycle updates
 - `attachResearchFindings` to attach saved findings to research state
-- `applyEvidenceCandidates` only when selected candidates should become canonical support
+- `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
 
 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.
 
+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.
+
 ## Init Rules
 
 During init:
 
-- scan local workspace materials before asking broad questions
+- if no `revela-narrative/` exists, call `initNarrativeVault` before writing canonical narrative meaning; use `exportNarrativeVault` only for developer workspaces that already have a JSON narrative mirror and no vault
+- scan local workspace materials before asking broad questions, and treat init as repeatable ingest for both first discovery and user-added or user-modified files
+- after `revela-decks init`, inspect `ingest.ingestCandidates`; these include added files, files whose fingerprint changed, and files newer than the vault timestamp, and they must be considered for extraction/reading in this init pass
 - reuse `workspace.sourceMaterials` and extraction cache when fingerprints match
 - extract or read only relevant local materials; do not exhaustively process large workspaces
-- derive claims, evidence bindings, caveats, unsupported scope, source paths, quotes/snippets, pages, sheets, or slide references only when explicit support exists
+- derive claims, evidence bindings, caveats, unsupported scope, source paths, quotes/snippets, pages, sheets, or slide references only when explicit support exists; distill ingested files by writing Markdown nodes under `revela-narrative/` even when the narrative is incomplete, and represent missing information as research gaps or caveats
+- 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`
 
 ## Research Rules
 
@@ -76,8 +87,9 @@ During research:
 - delegate external web search to the `revela-research` subagent
 - save findings through `revela-research-save`
 - treat `/revela research` as permission to attach findings and bind clearly supported evidence without item-by-item user confirmation
-- use `applyEvidenceCandidates` or `upsertNarrative` to create canonical evidence bindings when claim id, quote/snippet, source, support scope, unsupported scope, caveat, and strength are explicit
-- narrow overbroad claim scope or relation rationale when the narrower wording preserves strategic meaning and better matches the evidence
+- create canonical evidence bindings only when the supported claim id, quote/snippet, source, support scope, unsupported scope, caveat, and strength are explicit; new evidence should express support with `## Relations` such as `- supports: [[claim-id]]`, while `claimId` remains compatibility fallback
+- compile after Markdown edits, inspect returned `diagnosticReport`, and report remaining blockers or warnings in the research summary
+- narrow overbroad claim scope by editing `revela-narrative/claims/*.md` only when the narrower wording preserves strategic meaning and better matches the evidence; report relation rewrites or strategic claim changes for Story/user confirmation
 - preserve source path, URL, location/page/sheet/slide, quote/snippet, support scope, unsupported scope, and caveat
 - keep missing or partial evidence visible instead of filling it with model assumptions; classify remaining caveats as internal-data-needed, not-publicly-researchable, source-quality-limit, or still-open
 
@@ -85,6 +97,8 @@ During research:
 
 When the user invokes `/revela story`, open the read-only story workspace UI. Do not turn that command into a blocking readiness report.
 
+If a Markdown vault has compile diagnostics, surface the diagnostic summary alongside the Story output without mutating state. Errors should identify the Markdown file/node and the next smallest fix.
+
 When the user explicitly asks for a readiness report, call `revela-decks` action `reviewNarrative` and report the tool result as authoritative.
 
 Use this report shape:
@@ -106,6 +120,7 @@ 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
 - 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