@cyber-dash-tech/revela 0.11.0 → 0.12.0

package/lib/prompt-builder.ts

@@ -1,9 +1,14 @@
 /**
- * Prompt builder — assembles the three-layer system prompt.
+ * Prompt builder — assembles Revela system prompts.
  *
- * Layer 1: SKILL.md     — core protocol (conversation flow, HTML rules, quality)
- * Layer 2: DOMAIN.md    — domain knowledge (report structure, terminology)
- * Layer 3: DESIGN.md    — visual style (colors, fonts, animations, layout)
+ * Narrative mode:
+ *   Layer 1: NARRATIVE_SKILL.md — audience/decision/claim/evidence readiness
+ *   Layer 2: DOMAIN.md          — domain reasoning guidance when present
+ *
+ * Deck-render mode:
+ *   Layer 1: SKILL.md           — legacy deck render protocol (HTML rules, quality)
+ *   Layer 2: DOMAIN.md          — domain structure/terminology
+ *   Layer 3: DESIGN.md          — visual style (colors, fonts, animations, layout)
  *
  * When the active DESIGN.md has @section markers, only the global section,
  * layouts section, and a generated component index are injected into the
@@ -37,22 +42,43 @@ import { childLog } from "./log"
 
 const promptLog = childLog("prompt-builder")
 
-/** Path to SKILL.md shipped with this package. */
+export type PromptMode = "narrative" | "deck-render"
+
+export interface BuildPromptOptions {
+  mode?: PromptMode
+  designName?: string
+  domainName?: string
+}
+
+/** Path to deck-render SKILL.md shipped with this package. */
 const SKILL_MD_PATH = resolve(__dirname, "..", "skill", "SKILL.md")
+const NARRATIVE_SKILL_MD_PATH = resolve(__dirname, "..", "skill", "NARRATIVE_SKILL.md")
 
 /**
- * Build the combined system prompt and write it to _active-prompt.md.
+ * Build the active system prompt and write it to _active-prompt.md.
+ *
+ * Backward-compatible call form:
+ * - buildPrompt() builds the default narrative prompt.
+ * - buildPrompt("aurora", "general") builds the default narrative prompt with active metadata overrides.
+ *
+ * New call form:
+ * - buildPrompt({ mode: "narrative" }) avoids design/HTML instructions.
+ * - buildPrompt({ mode: "deck-render" }) preserves the legacy deck render prompt.
  *
- * @param designName - Override design (defaults to active)
- * @param domainName - Override domain (defaults to active)
  * @returns The path to the written file.
  */
-export function buildPrompt(designName?: string, domainName?: string): string {
-  const design = designName || activeDesign()
-  const domain = domainName || activeDomain()
-
-  // Layer 1 — SKILL.md
-  const coreSkill = readFileSync(SKILL_MD_PATH, "utf-8")
+export function buildPrompt(options?: BuildPromptOptions): string
+export function buildPrompt(designName?: string, domainName?: string): string
+export function buildPrompt(optionsOrDesignName?: BuildPromptOptions | string, legacyDomainName?: string): string {
+  const options = typeof optionsOrDesignName === "object" && optionsOrDesignName !== null
+    ? optionsOrDesignName
+    : { designName: optionsOrDesignName, domainName: legacyDomainName }
+  const mode: PromptMode = options.mode || "narrative"
+  const design = options.designName || activeDesign()
+  const domain = options.domainName || activeDomain()
+
+  // Layer 1 — core skill for the selected prompt mode.
+  const coreSkill = readFileSync(mode === "deck-render" ? SKILL_MD_PATH : NARRATIVE_SKILL_MD_PATH, "utf-8")
 
   // Check for preview.html
   const designDir = join(DESIGNS_DIR, design)
@@ -73,30 +99,37 @@ export function buildPrompt(designName?: string, domainName?: string): string {
     })
   }
 
-  // Layer 3 — DESIGN.md: marker-aware or full-text fallback
-  const designSkill = buildDesignLayer(design)
+  // Layer 3 — DESIGN.md: deck-render only. Narrative mode must not inject
+  // visual CSS, layout catalogs, component indexes, or HTML skeleton rules.
+  const designSkill = mode === "deck-render" ? buildDesignLayer(design) : ""
 
   // Assemble header
-  const header =
-    `<!-- Active design: ${design} -->\n` +
-    `<!-- Active domain: ${domain} -->\n` +
-    `<!-- Design files: ${designDir}/ -->\n` +
-    `<!--   - DESIGN.md — metadata + style instructions (injected below) -->\n` +
-    `${previewLine}\n\n`
-
-  // Three-layer concatenation: Header → SKILL → Domain → Design
+  const header = mode === "deck-render"
+    ? `<!-- Revela prompt mode: deck-render -->\n` +
+      `<!-- Active design: ${design} -->\n` +
+      `<!-- Active domain: ${domain} -->\n` +
+      `<!-- Design files: ${designDir}/ -->\n` +
+      `<!--   - DESIGN.md — metadata + style instructions (injected below) -->\n` +
+      `${previewLine}\n\n`
+    : `<!-- Revela prompt mode: narrative -->\n` +
+      `<!-- Active domain: ${domain} -->\n` +
+      `<!-- Design layer intentionally omitted in narrative mode. Use deck-render mode before writing deck artifacts. -->\n\n`
+
+  // Concatenation: Header → Skill → Domain → Design (deck-render only)
   const parts = [header, coreSkill]
   if (domainSkill) {
     parts.push(`\n\n---\n\n${domainSkill}`)
   }
-  parts.push(`\n\n---\n\n${designSkill}`)
+  if (designSkill) {
+    parts.push(`\n\n---\n\n${designSkill}`)
+  }
 
   const prompt = parts.join("")
 
   // Write to _active-prompt.md
   mkdirSync(CONFIG_DIR, { recursive: true })
   writeFileSync(ACTIVE_PROMPT_FILE, prompt, "utf-8")
-  promptLog.info("prompt rebuilt", { design, domain, bytes: prompt.length })
+  promptLog.info("prompt rebuilt", { mode, design, domain, bytes: prompt.length })
 
   return ACTIVE_PROMPT_FILE
 }

package/lib/workspace-state/graph.ts

@@ -1,5 +1,6 @@
 import { createHash } from "crypto"
 import type { DeckSpec, DecksState, EvidenceRef, NarrativeBrief, ResearchAxis, SlideSpec, SourceMaterial } from "../decks-state"
+import type { NarrativeEvidenceBinding, NarrativeStateV1 } from "../narrative-state/types"
 import { renderTargetId } from "./render-targets"
 import type { GraphEdge, GraphEdgeType, GraphNode, GraphNodeType, RenderTarget, WorkspaceGraph } from "./types"
 
@@ -19,7 +20,7 @@ export function projectWorkspaceGraph(state: DecksState, options: ProjectWorkspa
   for (const material of state.workspace.sourceMaterials ?? []) addSourceMaterial(builder, material)
   for (const axis of deck.researchPlan ?? []) addResearchFinding(builder, axis)
 
-  const narrativeId = addNarrative(builder, deck)
+  const narrativeId = addNarrative(builder, state, deck)
   for (const slide of deck.slides.slice().sort((a, b) => a.index - b.index)) addSlide(builder, slide)
   for (const slide of deck.slides.slice().sort((a, b) => a.index - b.index)) addSlideClaimsAndEvidence(builder, slide)
   const targets = renderTargetsForDeck(state, deck)
@@ -84,7 +85,9 @@ function addResearchFinding(builder: GraphBuilder, axis: ResearchAxis): void {
   })
 }
 
-function addNarrative(builder: GraphBuilder, deck: DeckSpec): string | undefined {
+function addNarrative(builder: GraphBuilder, state: DecksState, deck: DeckSpec): string | undefined {
+  if (hasCanonicalNarrative(state.narrative)) return addCanonicalNarrative(builder, state.narrative, deck)
+
   const brief = deck.narrativeBrief
   if (!hasNarrativeBrief(brief)) return undefined
 
@@ -122,6 +125,84 @@ function addNarrative(builder: GraphBuilder, deck: DeckSpec): string | undefined
   return narrativeId
 }
 
+function addCanonicalNarrative(builder: GraphBuilder, narrative: NarrativeStateV1, deck: DeckSpec): string {
+  addNode(builder, {
+    id: narrative.id,
+    type: "narrativeIntent",
+    label: narrative.thesis?.statement || deck.goal || narrative.id,
+    data: compactData({
+      status: narrative.status,
+      goal: deck.goal,
+      audience: narrative.audience.primary || deck.audience,
+      language: deck.language,
+      beliefBefore: narrative.audience.beliefBefore,
+      beliefAfter: narrative.audience.beliefAfter,
+      decisionOrAction: narrative.decision.action,
+      thesis: narrative.thesis?.statement,
+    }),
+  })
+
+  for (const claim of narrative.claims) {
+    addNode(builder, {
+      id: claim.id,
+      type: "claim",
+      label: claim.text,
+      data: compactData({
+        text: claim.text,
+        kind: claim.kind,
+        importance: claim.importance,
+        evidenceRequired: claim.evidenceRequired,
+        evidenceStatus: claim.evidenceStatus,
+        supportedScope: claim.supportedScope,
+        unsupportedScope: claim.unsupportedScope,
+        caveats: claim.caveats,
+        source: "canonicalNarrative",
+      }),
+    })
+    addEdge(builder, "contains", narrative.id, claim.id)
+  }
+
+  for (const binding of narrative.evidenceBindings) {
+    const supportId = addNarrativeEvidenceSupportNode(builder, binding)
+    addEdge(builder, "supports", supportId, binding.claimId, compactData({
+      strength: binding.strength,
+      source: binding.source,
+      quote: binding.quote,
+      url: binding.url,
+      sourcePath: binding.sourcePath,
+      location: binding.location,
+      findingsFile: binding.findingsFile,
+      caveat: binding.caveat,
+      supportScope: binding.supportScope,
+      unsupportedScope: binding.unsupportedScope,
+    }))
+  }
+
+  for (const objection of narrative.objections) {
+    addNode(builder, {
+      id: objection.id,
+      type: "objection",
+      label: objection.text,
+      data: compactData({ text: objection.text, priority: objection.priority, response: objection.response }),
+    })
+    addEdge(builder, "contains", narrative.id, objection.id)
+    addEdge(builder, "challenges", objection.id, objection.claimId || narrative.id)
+  }
+
+  for (const risk of narrative.risks) {
+    addNode(builder, {
+      id: risk.id,
+      type: "risk",
+      label: risk.text,
+      data: compactData({ text: risk.text, severity: risk.severity, mitigation: risk.mitigation }),
+    })
+    addEdge(builder, "contains", narrative.id, risk.id)
+    addEdge(builder, "constrained_by", risk.claimId || narrative.id, risk.id)
+  }
+
+  return narrative.id
+}
+
 function addSlide(builder: GraphBuilder, slide: SlideSpec): void {
   addNode(builder, {
     id: slideNodeId(slide.index),
@@ -222,6 +303,29 @@ function addEvidenceSupportNode(builder: GraphBuilder, evidence: EvidenceRef): s
   return id
 }
 
+function addNarrativeEvidenceSupportNode(builder: GraphBuilder, binding: NarrativeEvidenceBinding): string {
+  if (binding.findingsFile?.trim()) {
+    const id = findingNodeId(binding.findingsFile)
+    addNode(builder, {
+      id,
+      type: "finding",
+      label: binding.findingsFile,
+      data: compactData({ findingsFile: binding.findingsFile, source: binding.source, quote: binding.quote, location: binding.location, caveat: binding.caveat }),
+    })
+    return id
+  }
+
+  const sourceKey = binding.sourcePath || binding.source || binding.url || "unknown-narrative-evidence-source"
+  const id = sourceNodeId(sourceKey)
+  addNode(builder, {
+    id,
+    type: "source",
+    label: sourceKey,
+    data: compactData({ source: binding.source, sourcePath: binding.sourcePath, url: binding.url }),
+  })
+  return id
+}
+
 function addArtifact(builder: GraphBuilder, deck: DeckSpec, target: RenderTarget, narrativeId: string | undefined, targets: RenderTarget[]): void {
   const artifactId = artifactNodeId(target.outputPath ?? deck.outputPath)
   addNode(builder, {
@@ -308,6 +412,20 @@ function hasNarrativeBrief(brief: NarrativeBrief | undefined): boolean {
   )
 }
 
+function hasCanonicalNarrative(narrative: NarrativeStateV1 | undefined): narrative is NarrativeStateV1 {
+  return Boolean(
+    narrative?.audience.primary?.trim() ||
+      narrative?.audience.beliefBefore?.trim() ||
+      narrative?.audience.beliefAfter?.trim() ||
+      narrative?.decision.action?.trim() ||
+      narrative?.thesis?.statement?.trim() ||
+      narrative?.claims.length ||
+      narrative?.evidenceBindings.length ||
+      narrative?.objections.length ||
+      narrative?.risks.length,
+  )
+}
+
 function hasEvidenceDetail(evidence: EvidenceRef): boolean {
   return Boolean(
     evidence.quote?.trim() ||

package/lib/workspace-state/types.ts

@@ -88,8 +88,11 @@ export type WorkspaceActionType =
   | "source.extracted"
   | "research.findings_saved"
   | "research.findings_attached"
+  | "narrative.upserted"
+  | "deck.plan_compiled"
   | "evidence.candidate_generated"
   | "evidence.binding_applied"
+  | "narrative.approved"
   | "review.performed"
   | "artifact.rendered"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",

package/plugin.ts

@@ -60,7 +60,7 @@ import {
 } from "./lib/commands/designs-new"
 import { buildInitPrompt } from "./lib/commands/init"
 import { parseRememberArgs, buildRememberPrompt } from "./lib/commands/remember"
-import { buildReviewPrompt } from "./lib/commands/review"
+import { buildDeckPrompt, buildDeckReviewPrompt, buildReviewPrompt } from "./lib/commands/review"
 import {
   extractDeckHtmlTargetsFromPatch,
   extractPatchTextArg,
@@ -326,6 +326,7 @@ const server: Plugin = (async (pluginCtx) => {
         throw new Error("__REVELA_DISABLE_HANDLED__")
       }
       if (sub === "init") {
+        buildPrompt({ mode: "narrative" })
         output.parts.length = 0
         output.parts.push({
           type: "text",
@@ -339,6 +340,7 @@ const server: Plugin = (async (pluginCtx) => {
           await send(parsed.error)
           throw new Error("__REVELA_REMEMBER_USAGE_HANDLED__")
         }
+        buildPrompt({ mode: "narrative" })
         output.parts.length = 0
         output.parts.push({
           type: "text",
@@ -348,9 +350,10 @@ const server: Plugin = (async (pluginCtx) => {
       }
       if (sub === "review") {
         if (param) {
-          await send("`/revela review` no longer accepts a deck name. It reviews the current workspace deck.")
+          await send("`/revela review` no longer accepts a deck name. It reviews the current workspace narrative. Use `/revela deck --review` for deck/artifact readiness.")
           throw new Error("__REVELA_REVIEW_USAGE_HANDLED__")
         }
+        buildPrompt({ mode: "narrative" })
         output.parts.length = 0
         output.parts.push({
           type: "text",
@@ -358,6 +361,28 @@ const server: Plugin = (async (pluginCtx) => {
         } as any)
         return
       }
+      if (sub === "deck") {
+        if (param && param !== "--review") {
+          await send("Usage: `/revela deck` starts approved-narrative deck handoff; `/revela deck --review` reviews deck/artifact readiness.")
+          throw new Error("__REVELA_DECK_USAGE_HANDLED__")
+        }
+        if (!param) {
+          buildPrompt({ mode: "deck-render" })
+          output.parts.length = 0
+          output.parts.push({
+            type: "text",
+            text: buildDeckPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+          } as any)
+          return
+        }
+        buildPrompt({ mode: "deck-render" })
+        output.parts.length = 0
+        output.parts.push({
+          type: "text",
+          text: buildDeckReviewPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+        } as any)
+        return
+      }
       if (sub === "refine") {
         if (param) {
           await send("`/revela refine` does not accept a target. It opens the only HTML deck in `decks/`.")

package/skill/NARRATIVE_SKILL.md

@@ -0,0 +1,64 @@
+---
+name: revela-narrative
+description: Build trusted narrative readiness before rendering deck artifacts
+compatibility: opencode
+---
+
+# Revela — Narrative Workspace
+
+You help the user turn source materials, research, and intent into a trusted communication narrative before any deck is rendered.
+
+Default mode is narrative-first. Do not generate HTML slides, choose visual layouts, fetch design components, or ask for slide count unless the user explicitly enters a deck-render workflow.
+
+## Core Job
+
+Build and review the narrative state around:
+- primary audience and stakeholder context
+- audience belief before and desired belief after
+- decision or action required
+- thesis or central recommendation
+- central claims and their evidence boundaries
+- objections, risks, assumptions, caveats, and unsupported scope
+- narrative approval state and whether approval is stale
+
+## Workspace State
+
+Use `DECKS.json` as Revela's current compatibility workspace-state file. Do not write or patch it directly.
+
+Use `revela-decks` for state operations:
+- `read` to inspect current workspace state
+- `init` to register discovered source material candidates during workspace initialization
+- `upsertNarrative` to preserve canonical audience, decision, thesis, claims, evidence bindings, objections, and risks
+- `upsertDeck` or `upsertSlides` only when explicitly needed by a deck/artifact workflow prompt
+- `reviewNarrative` to run deterministic narrative readiness
+- `approveNarrative` only when the user explicitly approves or requests an override
+
+Never treat `writeReadiness.status`, old review snapshots, existing `decks/*.html`, or saved research actions as narrative approval.
+
+## Narrative Review Rules
+
+When reviewing, call `revela-decks` action `reviewNarrative` and report the tool result as authoritative.
+
+Use this report shape:
+- `Narrative readiness: <status>`
+- `Narrative hash: <hash>` when available
+- blockers first, with issue type, claim text when available, and suggested next action
+- warnings second, as residual risks
+- approval state last, clearly distinguishing `ready_for_approval`, `approved`, stale approval, and render override
+
+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 research findings were saved but not attached or bound, describe them as unattached research state, not proof.
+
+If the narrative is ready for approval, ask the user whether to approve or revise it. Do not approve automatically.
+
+## Boundaries
+
+- Do not write or overwrite `decks/*.html` in narrative mode.
+- Do not call `revela-decks review` in narrative mode; that is the deck/artifact gate.
+- Do not apply evidence candidates, bind evidence, or rewrite slide text unless the user explicitly asks.
+- Do not fetch design CSS, layouts, components, chart rules, or HTML skeletons in narrative mode.
+- Do not store secrets, credentials, tokens, or sensitive personal information.
+- Do not infer long-term user preferences from one-off tasks.
+
+When the user wants deck/artifact readiness, direct them to `/revela deck --review`. When they want to render a deck, wait for the explicit deck workflow.

package/tools/decks.ts

@@ -21,15 +21,49 @@ import { recordWorkspaceAction } from "../lib/workspace-state/actions"
 import { applyEvidenceBindings } from "../lib/workspace-state/evidence-status"
 import { attachResearchFindings } from "../lib/workspace-state/research-attachments"
 import { activeReviewTargetId, latestReviewSnapshotForTarget } from "../lib/workspace-state/review-snapshots"
+import {
+  approveNarrativeState,
+  recordNarrativeApprovalAction,
+  recordNarrativeReviewAction,
+  reviewNarrativeState,
+} from "../lib/narrative-state/readiness"
+import { compileDeckPlanFromNarrative } from "../lib/narrative-state/render-plan"
+import { normalizeCanonicalNarrativeState, normalizeNarrativeState } from "../lib/narrative-state/normalize"
+import { narrativeToBrief } from "../lib/narrative-state/project-compat"
+import type { NarrativeStateV1 } from "../lib/narrative-state/types"
+
+function mergeNarrativeInput(current: NarrativeStateV1, input: Partial<NarrativeStateV1>): Partial<NarrativeStateV1> {
+  return {
+    ...current,
+    ...input,
+    id: current.id,
+    version: 1,
+    audience: {
+      ...current.audience,
+      ...(input.audience ?? {}),
+    },
+    decision: {
+      ...current.decision,
+      ...(input.decision ?? {}),
+    },
+    thesis: input.thesis ? { ...current.thesis, ...input.thesis } as NarrativeStateV1["thesis"] : current.thesis,
+    claims: input.claims ?? current.claims,
+    evidenceBindings: input.evidenceBindings ?? current.evidenceBindings,
+    objections: input.objections ?? current.objections,
+    risks: input.risks ?? current.risks,
+    approvals: current.approvals,
+    updatedAt: new Date().toISOString(),
+  }
+}
 
 export default tool({
   description:
     `Read and update ${DECKS_STATE_FILE}, Revela's workspace deck state file. ` +
     "Use this tool instead of writing or patching the state file directly. " +
-    "It stores active deck specs, per-slide content/layout/components, and computes write readiness.",
+    "It stores workspace narrative state, active deck specs, per-slide content/layout/components, and computes narrative or deck readiness.",
   args: {
     action: tool.schema
-      .enum(["read", "init", "upsertDeck", "upsertSlides", "review", "applyEvidenceCandidates", "attachResearchFindings", "remember"])
+      .enum(["read", "init", "upsertDeck", "upsertSlides", "upsertNarrative", "compileDeckPlan", "review", "reviewNarrative", "approveNarrative", "applyEvidenceCandidates", "attachResearchFindings", "remember"])
       .describe("Action to perform on DECKS.json."),
     summary: tool.schema.boolean().optional().describe("For read: return a compact summary instead of full state."),
     goal: tool.schema.string().optional().describe("For upsertDeck: deck goal."),
@@ -45,6 +79,69 @@ export default tool({
       objections: tool.schema.array(tool.schema.string()).optional().describe("Likely stakeholder objections or questions the narrative should handle."),
       risks: tool.schema.array(tool.schema.string()).optional().describe("Risks, assumptions, caveats, or tradeoffs that should travel with the narrative."),
     }).optional().describe("For upsertDeck: 0.9 Narrative Compiler brief used to review story intent before writing."),
+    narrative: tool.schema.object({
+      status: tool.schema.enum(["draft", "needs_research", "needs_user_confirmation", "ready_for_approval", "approved"]).optional(),
+      audience: tool.schema.object({
+        primary: tool.schema.string().optional(),
+        secondary: tool.schema.array(tool.schema.string()).optional(),
+        beliefBefore: tool.schema.string().optional(),
+        beliefAfter: tool.schema.string().optional(),
+        decisionContext: tool.schema.string().optional(),
+        successCriteria: tool.schema.array(tool.schema.string()).optional(),
+      }).optional(),
+      decision: tool.schema.object({
+        action: tool.schema.string().optional(),
+        owner: tool.schema.string().optional(),
+        deadline: tool.schema.string().optional(),
+        decisionType: tool.schema.enum(["approve", "invest", "prioritize", "align", "choose", "understand", "other"]).optional(),
+        consequenceOfNoDecision: tool.schema.string().optional(),
+      }).optional(),
+      thesis: tool.schema.object({
+        id: tool.schema.string().optional(),
+        statement: tool.schema.string().optional(),
+        confidence: tool.schema.enum(["high", "medium", "low"]).optional(),
+        caveat: tool.schema.string().optional(),
+      }).optional(),
+      claims: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().optional(),
+        kind: tool.schema.enum(["context", "problem", "opportunity", "evidence", "recommendation", "risk", "assumption", "ask"]).optional(),
+        text: tool.schema.string().describe("Claim text."),
+        importance: tool.schema.enum(["central", "supporting", "background"]).optional(),
+        evidenceRequired: tool.schema.boolean().optional(),
+        evidenceStatus: tool.schema.enum(["supported", "partial", "weak", "missing", "not_required"]).optional(),
+        supportedScope: tool.schema.string().optional(),
+        unsupportedScope: tool.schema.string().optional(),
+        caveats: tool.schema.array(tool.schema.string()).optional(),
+      })).optional(),
+      evidenceBindings: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().optional(),
+        claimId: tool.schema.string().describe("Canonical claim id this evidence supports."),
+        source: tool.schema.string().describe("Source file, URL, research finding, or material name."),
+        sourcePath: tool.schema.string().optional(),
+        findingsFile: tool.schema.string().optional(),
+        quote: tool.schema.string().optional(),
+        location: tool.schema.string().optional(),
+        url: tool.schema.string().optional(),
+        caveat: tool.schema.string().optional(),
+        supportScope: tool.schema.string().optional(),
+        unsupportedScope: tool.schema.string().optional(),
+        strength: tool.schema.enum(["strong", "partial", "weak"]).optional(),
+      })).optional(),
+      objections: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().optional(),
+        text: tool.schema.string().describe("Objection text."),
+        claimId: tool.schema.string().optional(),
+        priority: tool.schema.enum(["high", "medium", "low"]).optional(),
+        response: tool.schema.string().optional(),
+      })).optional(),
+      risks: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().optional(),
+        text: tool.schema.string().describe("Risk, assumption, caveat, or tradeoff text."),
+        claimId: tool.schema.string().optional(),
+        severity: tool.schema.enum(["high", "medium", "low"]).optional(),
+        mitigation: tool.schema.string().optional(),
+      })).optional(),
+    }).optional().describe("For upsertNarrative: canonical narrative state fields to merge into DECKS.json. Replaces provided arrays, preserves approvals."),
     design: tool.schema.string().optional().describe("For upsertDeck: active design name."),
     domain: tool.schema.string().optional().describe("For upsertDeck: active domain name."),
     memory: tool.schema.string().optional().describe("For remember: explicit user or workflow preference to store."),
@@ -124,6 +221,9 @@ export default tool({
     findingsFile: tool.schema.string().optional().describe("For attachResearchFindings: workspace-relative researches/{topic}/{axis}.md file to attach to researchPlan."),
     researchAxis: tool.schema.string().optional().describe("For attachResearchFindings: researchPlan axis to attach the findings file to. Required when filename matching would be ambiguous."),
     researchStatus: tool.schema.enum(["done", "read"]).optional().describe("For attachResearchFindings: optional explicit status to set on the matched research axis."),
+    approvalNote: tool.schema.string().optional().describe("For approveNarrative: optional note explaining the approval or override."),
+    approvalBy: tool.schema.enum(["user", "override"]).optional().describe("For approveNarrative: use override only for explicit render overrides, not normal strategic approval."),
+    approvalScope: tool.schema.enum(["narrative", "render_override"]).optional().describe("For approveNarrative: narrative approval or explicit render override scope."),
   },
   async execute(args, context) {
     try {
@@ -194,6 +294,45 @@ export default tool({
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, deck: next.activeDeck ? next.decks[next.activeDeck] : undefined }, null, 2)
       }
 
+      if (args.action === "upsertNarrative") {
+        if (!args.narrative) return JSON.stringify({ ok: false, error: "narrative is required for upsertNarrative" })
+        const current = state.narrative ?? normalizeNarrativeState(state)
+        const merged = mergeNarrativeInput(current, args.narrative as Partial<NarrativeStateV1>)
+        const normalized = normalizeCanonicalNarrativeState(merged, state.activeDeck ?? defaultSlug)
+        if (!normalized) return JSON.stringify({ ok: false, error: "narrative could not be normalized" })
+        state.narrative = normalized
+
+        const deckKey = state.activeDeck
+        if (deckKey && state.decks[deckKey]) {
+          state = upsertDeck(state, {
+            ...state.decks[deckKey],
+            slug: deckKey,
+            audience: normalized.audience.primary || state.decks[deckKey].audience,
+            narrativeBrief: narrativeToBrief(normalized),
+          })
+        }
+
+        recordWorkspaceAction(state, {
+          type: "narrative.upserted",
+          actor: "revela-decks",
+          inputs: { hadExistingNarrative: Boolean(current), providedFields: Object.keys(args.narrative as object) },
+          outputs: {
+            narrativeId: normalized.id,
+            status: normalized.status,
+            claimCount: normalized.claims.length,
+            evidenceBindingCount: normalized.evidenceBindings.length,
+            objectionCount: normalized.objections.length,
+            riskCount: normalized.risks.length,
+          },
+          status: "success",
+          summary: `Updated canonical narrative state with ${normalized.claims.length} claim${normalized.claims.length === 1 ? "" : "s"}.`,
+          nodeIds: [normalized.id],
+        })
+
+        writeDecksState(workspaceRoot, state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, narrative: state.narrative, deck: state.activeDeck ? state.decks[state.activeDeck] : undefined }, null, 2)
+      }
+
       if (args.action === "review") {
         const reviewed = reviewDeckState(state, undefined, { workspaceRoot })
         const targetId = activeReviewTargetId(reviewed.state)
@@ -222,6 +361,45 @@ export default tool({
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: reviewed.result }, null, 2)
       }
 
+      if (args.action === "compileDeckPlan") {
+        const compiled = compileDeckPlanFromNarrative(state)
+        if (compiled.result.compiled) {
+          recordWorkspaceAction(compiled.state, {
+            type: "deck.plan_compiled",
+            actor: "revela-decks",
+            inputs: { narrativeId: compiled.state.narrative?.id, activeDeck: compiled.state.activeDeck },
+            outputs: {
+              narrativeHash: compiled.result.narrativeHash,
+              slideCount: compiled.result.slideCount,
+              outputPath: compiled.state.activeDeck ? compiled.state.decks[compiled.state.activeDeck]?.outputPath : undefined,
+            },
+            status: "success",
+            summary: `Compiled deck plan from canonical narrative with ${compiled.result.slideCount} slide${compiled.result.slideCount === 1 ? "" : "s"}.`,
+            nodeIds: [compiled.state.narrative?.id, compiled.state.activeDeck ? `artifact:${compiled.state.decks[compiled.state.activeDeck]?.outputPath ?? compiled.state.activeDeck}` : undefined].filter((item): item is string => Boolean(item)),
+          })
+        }
+        writeDecksState(workspaceRoot, compiled.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: compiled.result, deck: compiled.state.activeDeck ? compiled.state.decks[compiled.state.activeDeck] : undefined, narrative: compiled.state.narrative }, null, 2)
+      }
+
+      if (args.action === "reviewNarrative") {
+        const reviewed = reviewNarrativeState(state)
+        recordNarrativeReviewAction(reviewed.state, reviewed.result)
+        writeDecksState(workspaceRoot, reviewed.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: reviewed.result, narrative: reviewed.state.narrative }, null, 2)
+      }
+
+      if (args.action === "approveNarrative") {
+        const approved = approveNarrativeState(state, {
+          approvedBy: args.approvalBy,
+          scope: args.approvalScope,
+          note: args.approvalNote,
+        })
+        recordNarrativeApprovalAction(approved.state, approved.result)
+        writeDecksState(workspaceRoot, approved.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: approved.result, narrative: approved.state.narrative }, null, 2)
+      }
+
       if (args.action === "applyEvidenceCandidates") {
         const candidateIds = args.candidateIds ?? []
         if (candidateIds.length === 0) return JSON.stringify({ ok: false, error: "candidateIds are required for applyEvidenceCandidates" })