@cyber-dash-tech/revela 0.16.4 → 0.17.1

package/lib/commands/review.ts

@@ -35,10 +35,10 @@ Workspace boundary rules:
 - For Glob/file searches, use the current workspace as the search root. Do not set the search root to a parent directory or home directory.
 
 Workflow:
-1. Call \`revela-decks\` with action \`read\` to inspect the current workspace state.
+1. Call \`revela-decks\` with action \`read\` and \`summary: true\` to inspect the current workspace state, \`vaultDiagnostics\`, \`markdownQa\`, and \`narrativeInventory\` when a vault exists.
 2. If ${DECKS_STATE_FILE} is missing or empty, do not invent a deck plan, slide count, design, output path, or visual style. Report the smallest narrative inputs needed, usually audience, belief-before, belief-after, decision/action, thesis, central claims, evidence availability, objections, and risks.
 3. If legacy deck state exists, let the tool-normalized canonical narrative derived from \`narrativeBrief\`, slide roles, slide content, and slide evidence be reviewed. Do not assume old deck readiness means approval.
-4. Call \`revela-decks\` action \`reviewNarrative\`. Use its returned \`status\`, \`blockers\`, \`warnings\`, \`issues\`, \`narrativeHash\`, \`approval\`, and \`nextActions\` as authoritative.
+4. Call \`revela-decks\` action \`reviewNarrative\`. Use its returned \`status\`, \`blockers\`, \`warnings\`, \`issues\`, \`narrativeHash\`, \`approval\`, and \`nextActions\` as authoritative. If the read summary returned \`markdownQa.repairCards\` or \`vaultDiagnostics\`, report Markdown QA repair cards and compile diagnostics before readiness blockers and include file/node/code/message plus smallest repair or suggested next action.
 5. If research findings have been saved but not attached or evidence-bound, report them as unattached research state, not proof.
 6. If central claims lack required evidence, report the named claim and the exact next action: attach findings, bind evidence, run targeted research, narrow unsupported scope, or rewrite the claim.
 7. If approval is missing or stale, clearly distinguish \`ready_for_approval\`, \`approved\`, and render override.
@@ -46,7 +46,7 @@ Workflow:
 Report format:
 - Start with \`Narrative readiness: <status>\`.
 - Include \`Narrative hash: <hash>\` when returned.
-- If blocked or needs research, list each blocker with issue type, claim text when available, and suggested next action.
+- If blocked or needs research, list each blocker with issue type, claim text when available, and suggested next action. Keep Markdown QA repair cards separate from compiler diagnostics and narrative readiness blockers.
 - 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.
@@ -89,28 +89,30 @@ Current state:
 ${workspaceRoot ? `- Current workspace root: \`${workspaceRoot}\`` : ""}
 
 Workflow:
-1. Call \`revela-decks\` action \`read\`.
+1. Call \`revela-decks\` action \`read\` with \`summary: true\`.
 2. Call \`revela-decks\` action \`reviewNarrative\` before planning deck slides.
-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.
+3. If the read summary returned \`markdownQa.blockers\` or \`vaultDiagnostics.blockers\`, stop before deck planning and report Markdown QA repair cards separately from compile diagnostics with file/node/code/message and smallest repair or suggested next action. 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 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. 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 Review. If post-write artifact QA reports hard errors, fix them and let QA run again. Review 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 Review.
+6. Treat each compiled slide's \`visuals[]\` and \`content.data.visualIntent\` as required render instructions, not optional decoration. Do not downgrade a planned chart, metric card, evidence table, comparison grid, risk matrix, steps view, or media brief into generic bullets unless the plan is revised and reconfirmed.
+7. 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.
+8. 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.
+9. Only after explicit user confirmation of the current slide plan, call \`revela-decks\` action \`confirmDeckPlan\` with \`approvalBy=user\` and a compact \`approvalNote\`.
+10. 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.
+11. 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.
+12. 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.
+13. 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.
+14. 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.
+15. After each HTML write, the system automatically runs artifact QA before opening Review. If post-write artifact QA reports hard errors, fix them and let QA run again. Review 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 Review.
 
 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 Markdown QA repair cards and vault diagnostic blockers or warnings when returned by \`read(summary: true)\`; blockers prevent deck planning until fixed.
 - 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.
+- 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 from \`content.data.visualIntent\`, visual brief from \`visuals[]\`, and caveats/unsupported scope.
 - Use this sketch style or similarly simple ASCII boxes:
 
 \`\`\`text
@@ -132,6 +134,8 @@ Components:
 Primary claim:
 Supporting claims:
 Evidence bindings:
+Visual intent:
+Visual brief:
 Caveats / unsupported scope:
 \`\`\`
 - End by asking the user to confirm the deck plan or request changes.
@@ -145,6 +149,7 @@ Report format before any HTML write after confirmation:
 
 Rules:
 - \`compileDeckPlan\` is the canonical narrative-to-deck planning path. Do not manually invent slide specs to avoid it.
+- Visual intent is part of the confirmed plan. During HTML generation, satisfy the planned component/visual brief using fetched design components; do not collapse planned visuals into prose-only bullets.
 - 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.
@@ -181,7 +186,7 @@ Goal:
 - Treat \`revela-narrative-reviewer\` findings as advisory critique only. Do not represent them as \`revela-decks\` readiness issues, blockers, or authoritative \`writeReadiness\`.
 - Treat source trace mapping as part of evidence readiness: when research findings have been read, relevant findings should appear in slide-level \`slides[].evidence[]\` records rather than only in raw research files.
 - When \`revela-decks review\` returns \`evidenceCandidates\`, treat them as conservative binding candidates only. They are not proof that the full slide is supported, and they are not automatically applied to \`slides[].evidence[]\`. If a candidate has \`sourceKind: "researchesFallback"\`, say it was discovered from workspace \`researches/\` files that are not currently referenced by \`researchPlan\`.
-- When an evidence candidate includes \`evidenceDraft\`, report it as a proposed slide evidence record with its \`candidateId\`; it still requires explicit user/agent confirmation before calling \`revela-decks\` action \`applyEvidenceCandidates\`. Also report \`unsupportedScope\` and \`recommendedRewrite\` so partial evidence is not stretched to future-state claims.
+- When an evidence candidate includes \`evidenceDraft\`, report it as a proposed slide evidence record with its \`candidateId\`; it still requires explicit user/agent confirmation before binding. Binding canonical evidence means using \`initNarrativeVault\` if needed, writing \`revela-narrative/evidence/*.md\` with explicit source trace, and running \`compileNarrativeVault\`. Also report \`unsupportedScope\` and \`recommendedRewrite\` so partial evidence is not stretched to future-state claims.
 - When a missing-evidence issue has \`evidenceCandidateSearch\`, use it to explain search coverage: which \`researchPlan\` findings were searched, which fallback \`researches/**/*.md\` files were searched, and any near misses that were below binding threshold.
 
 Current state:
@@ -195,17 +200,18 @@ Workspace boundary rules:
 - For Glob/file searches, use the current workspace as the search root. Do not set the search root to a parent directory or home directory.
 
 Workflow:
-1. Call \`revela-decks\` with action \`read\` for the current workspace deck.
-2. If no current deck exists but the conversation contains enough deck context, call \`revela-decks\` action \`upsertDeck\` with goal, outputPath, theme, requiredInputs, researchPlan, and narrativeBrief if the story intent is clear. Do not invent or ask for a deck key; the tool uses the workspace folder name internally.
-3. If \`researchPlan[].status\` is \`done\` or \`read\` and \`researchPlan[].findingsFile\` exists, verify that evidence-sensitive slide claims are backed by compact \`slides[].evidence[]\` records that reference the relevant findings file or source material where known. The review tool may surface conservative \`evidenceCandidates\` for missing evidence by matching slide text against those findings files, and may fall back to bounded workspace \`researches/**/*.md\` discovery when the research plan has no matching findings file; report these as candidate bindings, not as already-bound evidence.
-4. If a user-confirmed slide plan is available, call \`revela-decks\` action \`upsertSlides\` with every slide's title, purpose, narrativeRole, layout, components, structured content, evidence, visuals, and status. Use only lightweight narrativeRole values that are clear from the plan: \`context\`, \`tension\`, \`evidence\`, \`recommendation\`, \`risk\`, \`ask\`, \`appendix\`, or \`close\`.
-5. Prefer evidence records with \`findingsFile\`, \`sourcePath\`, \`location\`, \`quote\`, \`url\`, \`caveat\`, \`extractedTextPath\`, or \`extractedManifestPath\` when those fields are known from research files or extracted workspace materials.
-6. Do not invent quotes, page references, locations, URLs, caveats, or extraction paths. If source trace is missing, preserve the blocker or warning and report exactly what trace is needed.
-7. Only set requiredInputs fields true when explicit conversation state, files read, research findings read, selected design, fetched layouts/components, or user confirmation supports them. Do not infer completion.
-8. For substantial decision decks, preserve a compact \`narrativeBrief\` through \`upsertDeck\` when the conversation or confirmed plan supports it. Do not invent stakeholder beliefs, objections, or risks; leave gaps visible if unknown.
-9. For substantial decision decks, launch the Task subagent with \`subagent_type: "revela-narrative-reviewer"\` after deck/slides are up to date. Ask it to read the current \`DECKS.json\`, run only its fixed rubric, use stable finding IDs, return \`Findings: none\` when all checks pass, and avoid optional pre-write improvements. Do not ask it to write state, call \`revela-decks review\`, or produce HTML.
-10. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` plus structured readiness issues for the current workspace deck.
-11. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool. If warnings exist, list them after blockers as residual risks; separate evidence/source warnings from narrative warnings when possible. If the review result includes \`diagnostics\`, include a \`Plan and coverage diagnostics\` section with plan quality blockers/warnings, artifact \`coverageStatus\`, \`missingClaimIds\`, \`affectedClaimIds\`, stale reasons, and \`nextActions\`. If the review result includes \`evidenceCandidates\`, add a separate \`Candidate evidence bindings\` section with candidateId, slide index/title, supported claim scope, sourceKind, findingsFile/sourcePath, quote/snippet, caveat, evidenceDraft summary, unsupportedScope, and recommendedRewrite. Tell the user they may explicitly ask to apply selected candidate IDs; do not apply them during review. If candidates are absent but \`evidenceCandidateSearch\` is present, briefly report searched file counts and the best near misses so the user can tell whether review failed to search or searched but did not find a bindable match. If the reviewer returned findings, include them in a separate \`Narrative reviewer notes\` section and label them advisory.
+1. Call \`revela-decks\` with action \`read\` and \`summary: true\` for the current workspace deck and any \`markdownQa\`, \`vaultDiagnostics\`, and \`narrativeInventory\`.
+2. If the read summary returned \`markdownQa.blockers\` or \`vaultDiagnostics.blockers\`, report Markdown QA repair cards separately from compile diagnostics before artifact readiness with file/node/code/message and smallestRepair/suggestedAction; stop before \`revela-decks review\`, deck HTML writes, or export guidance until the blocker is fixed.
+3. If no current deck exists but the conversation contains enough deck context, call \`revela-decks\` action \`upsertDeck\` with goal, outputPath, theme, requiredInputs, researchPlan, and narrativeBrief if the story intent is clear. Do not invent or ask for a deck key; the tool uses the workspace folder name internally.
+4. If \`researchPlan[].status\` is \`done\` or \`read\` and \`researchPlan[].findingsFile\` exists, verify that evidence-sensitive slide claims are backed by compact \`slides[].evidence[]\` records that reference the relevant findings file or source material where known. The review tool may surface conservative \`evidenceCandidates\` for missing evidence by matching slide text against those findings files, and may fall back to bounded workspace \`researches/**/*.md\` discovery when the research plan has no matching findings file; report these as candidate bindings, not as already-bound evidence.
+5. If a user-confirmed slide plan is available, call \`revela-decks\` action \`upsertSlides\` with every slide's title, purpose, narrativeRole, layout, components, structured content, evidence, visuals, and status. Use only lightweight narrativeRole values that are clear from the plan: \`context\`, \`tension\`, \`evidence\`, \`recommendation\`, \`risk\`, \`ask\`, \`appendix\`, or \`close\`.
+6. Prefer evidence records with \`findingsFile\`, \`sourcePath\`, \`location\`, \`quote\`, \`url\`, \`caveat\`, \`extractedTextPath\`, or \`extractedManifestPath\` when those fields are known from research files or extracted workspace materials.
+7. Do not invent quotes, page references, locations, URLs, caveats, or extraction paths. If source trace is missing, preserve the blocker or warning and report exactly what trace is needed.
+8. Only set requiredInputs fields true when explicit conversation state, files read, research findings read, selected design, fetched layouts/components, or user confirmation supports them. Do not infer completion.
+9. For substantial decision decks, preserve a compact \`narrativeBrief\` through \`upsertDeck\` when the conversation or confirmed plan supports it. Do not invent stakeholder beliefs, objections, or risks; leave gaps visible if unknown.
+10. For substantial decision decks, launch the Task subagent with \`subagent_type: "revela-narrative-reviewer"\` after deck/slides are up to date. Ask it to read the current \`DECKS.json\`, run only its fixed rubric, use stable finding IDs, return \`Findings: none\` when all checks pass, and avoid optional pre-write improvements. Do not ask it to write state, call \`revela-decks review\`, or produce HTML.
+11. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` plus structured readiness issues for the current workspace deck.
+12. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool. If warnings exist, list them after blockers as residual risks; separate evidence/source warnings from narrative warnings when possible. If the read summary or review result includes \`markdownQa\`, \`vaultDiagnostics\`, or \`diagnosticReport\`, include \`Markdown QA\` and \`Vault diagnostics\` sections before artifact readiness with file/node/code/message and smallestRepair/suggestedAction. If the review result includes \`diagnostics\`, include a \`Plan and coverage diagnostics\` section with plan quality blockers/warnings, artifact \`coverageStatus\`, \`missingClaimIds\`, \`affectedClaimIds\`, stale reasons, and \`nextActions\`. If the review result includes \`evidenceCandidates\`, add a separate \`Candidate evidence bindings\` section with candidateId, slide index/title, supported claim scope, sourceKind, findingsFile/sourcePath, quote/snippet, caveat, evidenceDraft summary, unsupportedScope, and recommendedRewrite. Tell the user they may explicitly ask to apply selected candidate IDs; do not apply them during review. If candidates are absent but \`evidenceCandidateSearch\` is present, briefly report searched file counts and the best near misses so the user can tell whether review failed to search or searched but did not find a bindable match. If the reviewer returned findings, include them in a separate \`Narrative reviewer notes\` section and label them advisory.
 
 Minimum conditions for \`ready\`:
 - Topic, audience, slide count, language, and visual style/design are decided.
@@ -231,8 +237,9 @@ Report format:
 - Do not convert \`revela-narrative-reviewer\` advisory findings into tool readiness issues. Keep them separate from \`revela-decks review\` blockers and warnings, and preserve the reviewer's stable finding IDs when reporting them.
 - When reporting weak evidence, say whether the missing trace is \`findingsFile\`, \`sourcePath\`, \`location\`, \`quote\`, \`url\`, or \`caveat\` if that is clear from the reviewed materials.
 - When reporting candidate evidence bindings, distinguish partial support from full-slide support. Never say a candidate supports unrelated future-state, recommendation, roadmap, or product-vision claims unless the candidate explicitly supports those claims.
-- Treat \`evidenceDraft\` as a proposed record, not a mutation. Do not call \`upsertSlides\` to bind it. Only call \`revela-decks\` action \`applyEvidenceCandidates\` with explicit \`candidateIds\` if the user asks to apply candidate bindings.
+- Treat \`evidenceDraft\` as a proposed record, not a mutation. Do not call \`upsertSlides\` to bind it. If the user asks to apply candidate bindings, use \`initNarrativeVault\` if needed, write \`revela-narrative/evidence/*.md\` directly with explicit source trace, then run \`compileNarrativeVault\`. Use \`upsertVaultEvidence\` only as a fallback helper when direct Markdown editing is unavailable or unsafe.
 - When reporting candidate search diagnostics, do not present near misses as evidence. Say they are below binding threshold and use them only to explain why no candidate was returned.
+- When reporting vault diagnostics, do not fill missing evidence, source trace, quotes, URLs, page references, or caveats from model memory. Preserve the blocker until the Markdown source is fixed and compiled.
 
 Rules:
 - Do not write or overwrite \`decks/*.html\` during review.

package/lib/ctx.ts

@@ -22,6 +22,6 @@ export interface RevelaCtx {
 
 /** Global singleton. Import and use directly from any module. */
 export const ctx: RevelaCtx = {
-  enabled: false,
+  enabled: true,
   isResearchAgent: false,
 }

package/lib/decks-state.ts

@@ -20,7 +20,8 @@ import { WORKSPACE_STATE_FILE, type RenderTarget, type ReviewSnapshot, type Work
 import { normalizeCanonicalNarrativeState, normalizeNarrativeState } from "./narrative-state/normalize"
 import { computeNarrativeHash } from "./narrative-state/hash"
 import { getArtifactClaimRefs } from "./narrative-state/queries"
-import type { NarrativeStateV1 } from "./narrative-state/types"
+import type { NarrativeApproval, NarrativeStateV1 } from "./narrative-state/types"
+import { hasNarrativeVault, loadNarrativeFromPreferredSource } from "./narrative-vault"
 
 export const DECKS_STATE_FILE = WORKSPACE_STATE_FILE
 
@@ -34,6 +35,7 @@ export interface DecksState {
   version: 1
   activeDeck?: string
   narrative?: NarrativeStateV1
+  narrativeApprovals?: NarrativeApproval[]
   workspace: {
     brief?: string
     sourceMaterials: SourceMaterial[]
@@ -55,6 +57,7 @@ export interface SourceMaterial {
   type?: string
   size?: number
   fingerprint?: string
+  lastModified?: string
   status?: "discovered" | "extracted" | "summarized" | "researched"
   extraction?: {
     manifestPath?: string
@@ -483,15 +486,37 @@ export function confirmDeckPlan(state: DecksState, options: ConfirmDeckPlanOptio
 }
 
 export function readDecksState(workspaceRoot: string): DecksState {
-  return readWorkspaceState(workspaceRoot, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative })
+  return applyPreferredNarrativeSource(workspaceRoot, readWorkspaceState(workspaceRoot, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative }))
 }
 
 export function writeDecksState(workspaceRoot: string, state: DecksState): void {
-  writeWorkspaceState(workspaceRoot, state, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative })
+  const vault = hasNarrativeVault(workspaceRoot)
+  writeWorkspaceState(workspaceRoot, prepareStateForWrite(workspaceRoot, state), { fileName: DECKS_STATE_FILE, normalize: vault ? normalizeDecksState : normalizeDecksStateWithNarrative })
 }
 
 export function readOrCreateDecksState(workspaceRoot: string): DecksState {
-  return readOrCreateWorkspaceState(workspaceRoot, createEmptyDecksState, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative })
+  return applyPreferredNarrativeSource(workspaceRoot, readOrCreateWorkspaceState(workspaceRoot, createEmptyDecksState, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative }))
+}
+
+function applyPreferredNarrativeSource(workspaceRoot: string, state: DecksState): DecksState {
+  const normalized = normalizeDecksStateWithNarrative(state)
+  const loaded = loadNarrativeFromPreferredSource(workspaceRoot, normalized.narrative, narrativeApprovalsForHydration(normalized))
+  if (loaded.source !== "vault" || !loaded.narrative) return normalized
+  return normalizeDecksStateWithNarrative({ ...normalized, narrative: loaded.narrative, narrativeApprovals: loaded.narrative.approvals })
+}
+
+function prepareStateForWrite(workspaceRoot: string, state: DecksState): DecksState {
+  const normalized = normalizeDecksStateWithNarrative(state)
+  if (!hasNarrativeVault(workspaceRoot)) return normalized
+  const loaded = loadNarrativeFromPreferredSource(workspaceRoot, normalized.narrative, narrativeApprovalsForHydration(normalized))
+  const narrativeApprovals = loaded.narrative?.approvals ?? narrativeApprovalsForHydration(normalized)
+  const prepared = normalizeDecksStateWithNarrative({ ...normalized, narrative: loaded.narrative ?? normalized.narrative, narrativeApprovals })
+  const { narrative: _narrative, ...withoutNarrative } = prepared
+  return withoutNarrative as DecksState
+}
+
+function narrativeApprovalsForHydration(state: DecksState): NarrativeApproval[] {
+  return state.narrativeApprovals ?? state.narrative?.approvals ?? []
 }
 
 export function upsertDeck(state: DecksState, input: Partial<DeckSpec> & { slug: string }): DecksState {
@@ -859,6 +884,7 @@ function normalizeDecksState(input: DecksState): DecksState {
     version: 1,
     activeDeck: input.activeDeck ? normalizeSlug(input.activeDeck) : undefined,
     narrative: normalizeCanonicalNarrativeState(input.narrative, input.activeDeck || "workspace"),
+    narrativeApprovals: normalizeNarrativeApprovals([...(input.narrativeApprovals ?? []), ...(input.narrative?.approvals ?? [])]),
     workspace: {
       brief: input.workspace?.brief,
       sourceMaterials: input.workspace?.sourceMaterials ?? [],
@@ -890,9 +916,17 @@ function normalizeDecksState(input: DecksState): DecksState {
 function normalizeDecksStateWithNarrative(input: DecksState): DecksState {
   const state = normalizeDecksState(input)
   if (!state.narrative && currentDeckKey(state)) state.narrative = normalizeNarrativeState(state)
+  if (state.narrative && state.narrativeApprovals && state.narrativeApprovals.length > 0) {
+    state.narrative = { ...state.narrative, approvals: normalizeNarrativeApprovals([...state.narrative.approvals, ...state.narrativeApprovals]) ?? [] }
+  }
   return state
 }
 
+function normalizeNarrativeApprovals(approvals: NarrativeApproval[]): NarrativeApproval[] | undefined {
+  const normalized = [...new Map(approvals.filter((approval) => approval?.id).map((approval) => [approval.id, approval])).values()]
+  return normalized.length > 0 ? normalized : undefined
+}
+
 function normalizeDeckPlanReview(input: DeckPlanReview | undefined): DeckPlanReview | undefined {
   if (!input || !input.narrativeHash || !input.planHash) return undefined
   return {

package/lib/edit/prompt.ts

@@ -75,7 +75,7 @@ Instructions:
 - Make the smallest targeted change that satisfies the user's comment.
 - If there are multiple comments, apply them as one coherent edit pass and avoid changes from one comment overwriting another.
 - Each comment may reference one or more selected elements. Treat the elements in a single comment as a group.
-- Preserve the narrative boundary: if the requested edit changes audience framing, belief shift, decision/action, thesis, recommendation, claim wording, evidence scope, caveat, risk, objection, or decision ask, do not patch the HTML directly. Explain that the canonical narrative must be updated first through ${"`revela-decks`"} action ${"`upsertNarrative`"}, then reviewed/approved or explicitly overridden before updating the deck projection.
+- Preserve the narrative boundary: if the requested edit changes audience framing, belief shift, decision/action, thesis, recommendation, claim wording, evidence scope, caveat, risk, objection, or decision ask, do not patch the HTML directly. Explain that the canonical narrative must be updated first through targeted ${"`revela-decks`"} vault actions (${"`initNarrativeVault`"} if needed, then ${"`updateVaultCoreNarrative`"}, ${"`upsertVaultClaim`"}, ${"`upsertVaultEvidence`"}, ${"`upsertVaultObjection`"}, or ${"`upsertVaultRisk`"}), with manual Markdown edits plus ${"`compileNarrativeVault`"} only for unsupported node changes. Then the narrative must be reviewed/approved or explicitly overridden before updating the deck projection.
 - Pure artifact polish such as layout, spacing, typography, alignment, color, image crop, animation, export fidelity, 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.

package/lib/hook-notifications.ts

@@ -0,0 +1,53 @@
+import type { ArtifactQAReport } from "./qa/artifact"
+import type { AutoCompileNarrativeVaultResult } from "./narrative-vault/auto-compile"
+
+export function formatMarkdownQaUserNotice(result: AutoCompileNarrativeVaultResult): string | undefined {
+  if (result.ok) return undefined
+
+  const lines = ["**Markdown QA blocked**"]
+  lines.push(`Touched: ${result.touched.length > 0 ? result.touched.map((file) => `\`${file}\``).join(", ") : "unknown"}`)
+
+  const blockers = result.markdownQa?.blockers ?? []
+  if (blockers.length > 0) {
+    lines.push("Top repair(s):")
+    for (const card of blockers.slice(0, 3)) {
+      const location = [card.file, card.nodeId].filter(Boolean).join(" / ")
+      lines.push(`- \`${card.issueCode}\`${location ? ` (${location})` : ""}: ${card.smallestRepair}`)
+    }
+    if (blockers.length > 3) lines.push(`- ... ${blockers.length - 3} more`)
+  } else if (result.error) {
+    lines.push(`Hook error: ${result.error}`)
+  } else {
+    lines.push("Compile diagnostics are blocking the vault. See the tool output for details.")
+  }
+
+  return lines.join("\n")
+}
+
+export function formatArtifactQaUserNotice(report: ArtifactQAReport): string | undefined {
+  if (report.passed) return undefined
+
+  const lines = ["**Artifact QA failed**"]
+  lines.push(`File: \`${report.file}\``)
+  lines.push(`Hard errors: ${report.hardErrorCount}; warnings: ${report.warningCount}`)
+  if (report.sections.length > 0) {
+    lines.push("Top issue area(s):")
+    for (const section of report.sections.slice(0, 3)) lines.push(`- ${firstLine(section)}`)
+    if (report.sections.length > 3) lines.push(`- ... ${report.sections.length - 3} more`)
+  }
+  lines.push("Fix the reported artifact issues before treating the deck as ready.")
+  return lines.join("\n")
+}
+
+export function formatStateGateUserNotice(kind: "write" | "patch", reason: string): string {
+  return [
+    "**Revela state gate blocked a direct DECKS.json edit**",
+    `Operation: ${kind}`,
+    `Reason: ${reason}`,
+    "Use the `revela-decks` tool for controlled workspace state changes.",
+  ].join("\n")
+}
+
+function firstLine(text: string): string {
+  return text.split(/\r?\n/).map((line) => line.trim()).find(Boolean)?.replace(/^#+\s*/, "") ?? "See report details."
+}

package/lib/media/download.ts

@@ -12,6 +12,10 @@ const MIME_TO_EXT: Record<string, string> = {
 
 const ALLOWED_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".svg", ".webp", ".gif", ".ico"])
 const DEFAULT_DOWNLOAD_TIMEOUT_MS = 10_000
+const PRODUCT_USER_AGENT = "Revela/0.17 asset-save"
+const BROWSER_USER_AGENT =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
 
 function normalizeExtension(ext: string): string {
   const value = ext.toLowerCase()
@@ -47,6 +51,24 @@ export async function downloadImageFromUrl(
     throw new Error("INVALID_URL")
   }
 
+  const userAgents = [PRODUCT_USER_AGENT, BROWSER_USER_AGENT]
+  let lastError: unknown
+  for (const userAgent of userAgents) {
+    try {
+      return await downloadWithUserAgent(parsed, userAgent, options)
+    } catch (error) {
+      lastError = error
+    }
+  }
+
+  throw lastError instanceof Error ? lastError : new Error(String(lastError))
+}
+
+async function downloadWithUserAgent(
+  parsed: URL,
+  userAgent: string,
+  options: { timeoutMs?: number },
+): Promise<{ buffer: Buffer; contentType: string | null; extension: string }> {
   const controller = new AbortController()
   let timedOut = false
   const timer = setTimeout(() => {
@@ -60,9 +82,7 @@ export async function downloadImageFromUrl(
     response = await fetch(parsed, {
       headers: {
         Accept: "image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8",
-        "User-Agent":
-          "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
-          "(KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
+        "User-Agent": userAgent,
       },
       signal: controller.signal,
     })

package/lib/media/save.ts

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

package/lib/media/types.ts

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

package/lib/narrative-state/display.ts

@@ -9,6 +9,7 @@ export interface NarrativeDisplayModel {
   summaryLine?: string
   labels?: Partial<NarrativeDisplayLabels>
   claimCards?: NarrativeDisplayClaimCard[]
+  researchGapCards?: NarrativeDisplayResearchGapCard[]
   relations?: NarrativeDisplayRelation[]
 }
 
@@ -17,6 +18,18 @@ export interface NarrativeDisplayLabels {
   claimFlow: string
   flowNote: string
   selectedClaim: string
+  selectedEvidence: string
+  evidenceList: string
+  gap: string
+  gaps: string
+  noEvidence: string
+  selectEvidencePrompt: string
+  sourceTrace: string
+  evidenceSource: string
+  whyThisSupports: string
+  linkedGaps: string
+  selectedGap: string
+  noLinkedGaps: string
   claim: string
   claimId: string
   status: string
@@ -48,6 +61,11 @@ export interface NarrativeDisplayClaimCard {
   researchGapsSummary?: string
 }
 
+export interface NarrativeDisplayResearchGapCard {
+  gapId: string
+  displayQuestion?: string
+}
+
 export interface NarrativeDisplayRelation {
   fromClaimId: string
   toClaimId: string
@@ -63,6 +81,7 @@ export interface ValidatedNarrativeDisplayModel {
   summaryLine?: string
   labels: NarrativeDisplayLabels
   claimCards: Map<string, NarrativeDisplayClaimCard>
+  researchGapCards: Map<string, NarrativeDisplayResearchGapCard>
   relations: Map<string, NarrativeDisplayRelation>
 }
 
@@ -71,8 +90,20 @@ export function defaultNarrativeDisplayLabels(language: NarrativeViewLanguage):
     return {
       eyebrow: "只读主张流",
       claimFlow: "主张推进",
-      flowNote: "点击主张查看证据、关系、风险、缺口和已覆盖页面。",
+      flowNote: "点击主张查看论据和真实存在的缺口；点击论据查看它关联的缺口。",
       selectedClaim: "当前主张",
+      selectedEvidence: "当前论据",
+      evidenceList: "论据",
+      gap: "缺口",
+      gaps: "缺口",
+      noEvidence: "没有绑定论据",
+      selectEvidencePrompt: "选择一条论据或缺口查看详情",
+      sourceTrace: "来源追踪",
+      evidenceSource: "来源",
+      whyThisSupports: "为什么支撑论点",
+      linkedGaps: "这条论据关联的缺口",
+      selectedGap: "当前缺口",
+      noLinkedGaps: "这条论据没有关联缺口",
       claim: "主张",
       claimId: "主张 ID",
       status: "状态",
@@ -93,8 +124,20 @@ export function defaultNarrativeDisplayLabels(language: NarrativeViewLanguage):
     return {
       eyebrow: "読み取り専用クレームフロー",
       claimFlow: "クレームフロー",
-      flowNote: "クレームをクリックすると、根拠、関係、リスク、ギャップ、該当スライドを確認できます。",
+      flowNote: "クレームをクリックして根拠と実在するギャップを確認し、根拠をクリックして紐づくギャップを確認します。",
       selectedClaim: "選択中のクレーム",
+      selectedEvidence: "選択中の根拠",
+      evidenceList: "根拠",
+      gap: "ギャップ",
+      gaps: "ギャップ",
+      noEvidence: "紐づいた根拠はありません",
+      selectEvidencePrompt: "根拠またはギャップを選択して詳細を確認してください",
+      sourceTrace: "出典トレース",
+      evidenceSource: "出典",
+      whyThisSupports: "この根拠がクレームを支える理由",
+      linkedGaps: "この根拠に紐づくギャップ",
+      selectedGap: "選択中のギャップ",
+      noLinkedGaps: "この根拠に紐づくギャップはありません",
       claim: "クレーム",
       claimId: "クレーム ID",
       status: "ステータス",
@@ -114,8 +157,20 @@ export function defaultNarrativeDisplayLabels(language: NarrativeViewLanguage):
   return {
     eyebrow: "Read-only claim flow board",
     claimFlow: "Claim Flow",
-    flowNote: "Click a claim to inspect support, relation context, gaps, and covered slides.",
+    flowNote: "Click a claim to read its evidence and real gaps; click evidence to see gaps linked to that evidence.",
     selectedClaim: "Selected claim",
+    selectedEvidence: "Selected evidence",
+    evidenceList: "Evidence",
+    gap: "Gap",
+    gaps: "Gaps",
+    noEvidence: "No evidence bound",
+    selectEvidencePrompt: "Select evidence or a gap to inspect details.",
+    sourceTrace: "Source trace",
+    evidenceSource: "Source",
+    whyThisSupports: "Why this supports the claim",
+    linkedGaps: "Gaps linked to evidence",
+    selectedGap: "Selected gap",
+    noLinkedGaps: "No gaps linked to this evidence.",
     claim: "Claim",
     claimId: "Claim ID",
     status: "Status",
@@ -140,6 +195,7 @@ export function validateNarrativeDisplayModel(map: NarrativeMap, input: Narrativ
   if (input.language !== language) throw new Error(`Narrative display model language must be ${language}.`)
 
   const claimIds = new Set(map.claimFlow.map((claim) => claim.id))
+  const gapIds = new Set(map.researchGaps.map((gap) => gap.id))
   const relationByKey = new Map(map.claimRelations.map((relation) => [relationKey(relation), relation]))
   const claimCards = new Map<string, NarrativeDisplayClaimCard>()
   for (const card of input.claimCards ?? []) {
@@ -147,6 +203,12 @@ export function validateNarrativeDisplayModel(map: NarrativeMap, input: Narrativ
     claimCards.set(card.claimId, cleanClaimCard(card))
   }
 
+  const researchGapCards = new Map<string, NarrativeDisplayResearchGapCard>()
+  for (const card of input.researchGapCards ?? []) {
+    if (!gapIds.has(card.gapId)) throw new Error(`Unknown display gapId: ${card.gapId}`)
+    researchGapCards.set(card.gapId, cleanResearchGapCard(card))
+  }
+
   const relations = new Map<string, NarrativeDisplayRelation>()
   for (const relation of input.relations ?? []) {
     const key = relationKey(relation)
@@ -162,12 +224,13 @@ export function validateNarrativeDisplayModel(map: NarrativeMap, input: Narrativ
     summaryLine: clean(input.summaryLine),
     labels: mergeLabels(defaults, input.labels),
     claimCards,
+    researchGapCards,
     relations,
   }
 }
 
 export function emptyDisplayModel(language: NarrativeViewLanguage, labels = defaultNarrativeDisplayLabels(language)): ValidatedNarrativeDisplayModel {
-  return { version: 1, language, labels, claimCards: new Map(), relations: new Map() }
+  return { version: 1, language, labels, claimCards: new Map(), researchGapCards: new Map(), relations: new Map() }
 }
 
 export function relationKey(relation: Pick<NarrativeDisplayRelation, "fromClaimId" | "toClaimId" | "relation">): string {
@@ -210,6 +273,13 @@ function cleanClaimCard(card: NarrativeDisplayClaimCard): NarrativeDisplayClaimC
   }
 }
 
+function cleanResearchGapCard(card: NarrativeDisplayResearchGapCard): NarrativeDisplayResearchGapCard {
+  return {
+    gapId: card.gapId,
+    displayQuestion: clean(card.displayQuestion),
+  }
+}
+
 function cleanRelation(relation: NarrativeDisplayRelation, canonical: NarrativeMapClaimRelation): NarrativeDisplayRelation {
   const displayLabel = clean(relation.displayLabel)
   const displayRationale = clean(relation.displayRationale)