@cyber-dash-tech/revela 0.12.0 → 0.14.0

package/lib/workspace-state/graph.ts

@@ -1,6 +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 type { NarrativeClaimRelation, NarrativeEvidenceBinding, NarrativeResearchGap, NarrativeStateV1 } from "../narrative-state/types"
 import { renderTargetId } from "./render-targets"
 import type { GraphEdge, GraphEdgeType, GraphNode, GraphNodeType, RenderTarget, WorkspaceGraph } from "./types"
 
@@ -178,6 +178,8 @@ function addCanonicalNarrative(builder: GraphBuilder, narrative: NarrativeStateV
     }))
   }
 
+  for (const relation of narrative.claimRelations ?? []) addClaimRelation(builder, relation)
+
   for (const objection of narrative.objections) {
     addNode(builder, {
       id: objection.id,
@@ -200,6 +202,55 @@ function addCanonicalNarrative(builder: GraphBuilder, narrative: NarrativeStateV
     addEdge(builder, "constrained_by", risk.claimId || narrative.id, risk.id)
   }
 
+  for (const gap of narrative.researchGaps ?? []) addResearchGap(builder, narrative, gap)
+
+  return narrative.id
+}
+
+function addClaimRelation(builder: GraphBuilder, relation: NarrativeClaimRelation): void {
+  addEdge(builder, graphEdgeTypeForClaimRelation(relation.relation), relation.fromClaimId, relation.toClaimId, compactData({
+    relationId: relation.id,
+    relation: relation.relation,
+    rationale: relation.rationale,
+    source: "canonicalNarrative",
+  }))
+}
+
+function graphEdgeTypeForClaimRelation(relation: NarrativeClaimRelation["relation"]): GraphEdgeType {
+  if (relation === "constrains") return "constrained_by"
+  if (relation === "supports") return "supports"
+  return relation
+}
+
+function addResearchGap(builder: GraphBuilder, narrative: NarrativeStateV1, gap: NarrativeResearchGap): void {
+  addNode(builder, {
+    id: gap.id,
+    type: "researchGap",
+    label: gap.question,
+    data: compactData({
+      question: gap.question,
+      status: gap.status,
+      priority: gap.priority,
+      targetType: gap.targetType,
+      targetId: gap.targetId,
+      findingsFile: gap.findingsFile,
+      evidenceBindingIds: gap.evidenceBindingIds,
+      createdFromIssueType: gap.createdFromIssueType,
+      notes: gap.notes,
+    }),
+  })
+  addEdge(builder, "contains", narrative.id, gap.id)
+  addEdge(builder, "derived_from", gap.id, gapTargetNodeId(narrative, gap))
+  if (gap.findingsFile) addEdge(builder, "derived_from", gap.id, findingNodeId(gap.findingsFile), { status: gap.status })
+  for (const evidenceId of gap.evidenceBindingIds ?? []) {
+    const binding = narrative.evidenceBindings.find((item) => item.id === evidenceId)
+    if (binding) addEdge(builder, "derived_from", gap.id, binding.claimId, { evidenceBindingId: evidenceId })
+  }
+}
+
+function gapTargetNodeId(narrative: NarrativeStateV1, gap: NarrativeResearchGap): string {
+  if (gap.targetId) return gap.targetId
+  if (gap.targetType === "narrative" || gap.targetType === "decision") return narrative.id
   return narrative.id
 }
 
@@ -352,9 +403,11 @@ function renderTargetsForDeck(state: DecksState, deck: DeckSpec): RenderTarget[]
   const deckOutputPath = normalizePath(deck.outputPath)
   const htmlTargetId = renderTargetId("html_deck", deckOutputPath)
   const htmlArtifactId = artifactNodeId(deckOutputPath)
+  const narrativeId = state.narrative?.id
   const targets = (state.renderTargets ?? []).filter((target) => {
     if (target.id === htmlTargetId) return true
     if (target.type === "html_deck") return normalizePath(target.outputPath ?? "") === deckOutputPath
+    if (narrativeId && target.sourceNodeIds.includes(narrativeId)) return true
     const data = target.data ?? {}
     return data.sourceTargetId === htmlTargetId ||
       data.sourceOutputPath === deckOutputPath ||
@@ -422,7 +475,8 @@ function hasCanonicalNarrative(narrative: NarrativeStateV1 | undefined): narrati
       narrative?.claims.length ||
       narrative?.evidenceBindings.length ||
       narrative?.objections.length ||
-      narrative?.risks.length,
+      narrative?.risks.length ||
+      narrative?.researchGaps?.length,
   )
 }
 

package/lib/workspace-state/types.ts

@@ -50,6 +50,7 @@ export type GraphNodeType =
   | "risk"
   | "slide"
   | "artifact"
+  | "researchGap"
 
 export interface GraphEdge {
   id: string
@@ -64,6 +65,10 @@ export type GraphEdgeType =
   | "extracted_as"
   | "produced"
   | "supports"
+  | "leads_to"
+  | "depends_on"
+  | "contrasts_with"
+  | "answers"
   | "appears_in"
   | "challenges"
   | "constrained_by"
@@ -88,8 +93,12 @@ export type WorkspaceActionType =
   | "source.extracted"
   | "research.findings_saved"
   | "research.findings_attached"
+  | "research.gap_created"
+  | "research.gap_updated"
+  | "research.gap_closed"
   | "narrative.upserted"
   | "deck.plan_compiled"
+  | "artifact.coverage_backfilled"
   | "evidence.candidate_generated"
   | "evidence.binding_applied"
   | "narrative.approved"
@@ -98,7 +107,7 @@ export type WorkspaceActionType =
 
 export interface RenderTarget {
   id: string
-  type: "html_deck" | "pdf" | "pptx" | "brief" | "appendix" | "qa_view" | "interactive_page"
+  type: "html_deck" | "pdf" | "pptx" | "brief" | "executive_brief" | "appendix" | "qa_view" | "interactive_page"
   outputPath?: string
   sourceNodeIds: string[]
   artifactVersion?: string

package/package.json

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

package/plugin.ts

@@ -59,6 +59,8 @@ import {
   buildDesignsEditPrompt,
 } from "./lib/commands/designs-new"
 import { buildInitPrompt } from "./lib/commands/init"
+import { handleBrief, parseBriefArgs } from "./lib/commands/brief"
+import { buildNarrativeViewPrompt, handleNarrative, parseNarrativeArgs } from "./lib/commands/narrative"
 import { parseRememberArgs, buildRememberPrompt } from "./lib/commands/remember"
 import { buildDeckPrompt, buildDeckReviewPrompt, buildReviewPrompt } from "./lib/commands/review"
 import {
@@ -85,6 +87,7 @@ import researchImagesListTool from "./tools/research-images-list"
 import researchSaveTool from "./tools/research-save"
 import inspectionContextTool from "./tools/inspection-context"
 import inspectionResultTool from "./tools/inspection-result"
+import narrativeViewTool from "./tools/narrative-view"
 import workspaceScanTool from "./tools/workspace-scan"
 import extractDocumentMaterialsTool from "./tools/extract-document-materials"
 import qaTool from "./tools/qa"
@@ -361,6 +364,33 @@ const server: Plugin = (async (pluginCtx) => {
         } as any)
         return
       }
+      if (sub === "narrative") {
+        const parsed = parseNarrativeArgs(param)
+        if (!parsed.ok) {
+          await send(parsed.error)
+          throw new Error("__REVELA_NARRATIVE_USAGE_HANDLED__")
+        }
+        if (parsed.args.raw) {
+          await handleNarrative({ workspaceRoot, openBrowser: true, language: parsed.args.language }, send)
+          throw new Error("__REVELA_NARRATIVE_HANDLED__")
+        }
+        buildPrompt({ mode: "narrative" })
+        output.parts.length = 0
+        output.parts.push({
+          type: "text",
+          text: buildNarrativeViewPrompt({ workspaceRoot, language: parsed.args.language }),
+        } as any)
+        return
+      }
+      if (sub === "brief") {
+        const parsed = parseBriefArgs(param)
+        if (!parsed.ok) {
+          await send(parsed.error)
+          throw new Error("__REVELA_BRIEF_USAGE_HANDLED__")
+        }
+        await handleBrief({ workspaceRoot, outputPath: parsed.args.outputPath }, send)
+        throw new Error("__REVELA_BRIEF_HANDLED__")
+      }
       if (sub === "deck") {
         if (param && param !== "--review") {
           await send("Usage: `/revela deck` starts approved-narrative deck handoff; `/revela deck --review` reviews deck/artifact readiness.")
@@ -393,7 +423,7 @@ const server: Plugin = (async (pluginCtx) => {
       }
       if (sub === "edit") {
         if (param) {
-          await send("`/revela edit` no longer accepts a target. It opens the only HTML deck in `decks/`.")
+          await send("`/revela edit` is deprecated and does not accept a target. Use `/revela refine` for the unified refinement workspace.")
           throw new Error("__REVELA_EDIT_USAGE_HANDLED__")
         }
         await handleEdit({ client, sessionID, workspaceRoot }, send)
@@ -401,7 +431,7 @@ const server: Plugin = (async (pluginCtx) => {
       }
       if (sub === "inspect") {
         if (param) {
-          await send("`/revela inspect` does not accept a target. It opens the only HTML deck in `decks/`.")
+          await send("`/revela inspect` is deprecated and does not accept a target. Use `/revela refine` for the unified reading and refinement workspace.")
           throw new Error("__REVELA_INSPECT_USAGE_HANDLED__")
         }
         await handleInspect({ client, sessionID, workspaceRoot }, send)
@@ -507,6 +537,7 @@ const server: Plugin = (async (pluginCtx) => {
       "revela-research-save": researchSaveTool,
       "revela-inspection-context": inspectionContextTool,
       "revela-inspection-result": inspectionResultTool,
+      "revela-narrative-view": narrativeViewTool,
       "revela-workspace-scan": workspaceScanTool,
       "revela-extract-document-materials": extractDocumentMaterialsTool,
       "revela-qa": qaTool,

package/tools/decks.ts

@@ -28,6 +28,8 @@ import {
   reviewNarrativeState,
 } from "../lib/narrative-state/readiness"
 import { compileDeckPlanFromNarrative } from "../lib/narrative-state/render-plan"
+import { backfillSlideClaimRefsFromCoverage } from "../lib/narrative-state/coverage"
+import { closeResearchGapInState, deriveResearchGapsFromReadiness, updateResearchGapInState, upsertResearchGapsInState } from "../lib/narrative-state/research-gaps"
 import { normalizeCanonicalNarrativeState, normalizeNarrativeState } from "../lib/narrative-state/normalize"
 import { narrativeToBrief } from "../lib/narrative-state/project-compat"
 import type { NarrativeStateV1 } from "../lib/narrative-state/types"
@@ -48,9 +50,11 @@ function mergeNarrativeInput(current: NarrativeStateV1, input: Partial<Narrative
     },
     thesis: input.thesis ? { ...current.thesis, ...input.thesis } as NarrativeStateV1["thesis"] : current.thesis,
     claims: input.claims ?? current.claims,
+    claimRelations: input.claimRelations ?? current.claimRelations,
     evidenceBindings: input.evidenceBindings ?? current.evidenceBindings,
     objections: input.objections ?? current.objections,
     risks: input.risks ?? current.risks,
+    researchGaps: input.researchGaps ?? current.researchGaps,
     approvals: current.approvals,
     updatedAt: new Date().toISOString(),
   }
@@ -63,7 +67,7 @@ export default tool({
     "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", "upsertNarrative", "compileDeckPlan", "review", "reviewNarrative", "approveNarrative", "applyEvidenceCandidates", "attachResearchFindings", "remember"])
+      .enum(["read", "init", "upsertDeck", "upsertSlides", "upsertNarrative", "compileDeckPlan", "backfillClaimRefs", "review", "reviewNarrative", "approveNarrative", "deriveResearchGaps", "upsertResearchGaps", "updateResearchGap", "closeResearchGap", "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."),
@@ -113,6 +117,13 @@ export default tool({
         unsupportedScope: tool.schema.string().optional(),
         caveats: tool.schema.array(tool.schema.string()).optional(),
       })).optional(),
+      claimRelations: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().optional(),
+        fromClaimId: tool.schema.string().describe("Canonical claim id the relation starts from."),
+        toClaimId: tool.schema.string().describe("Canonical claim id the relation points to."),
+        relation: tool.schema.enum(["leads_to", "supports", "depends_on", "contrasts_with", "constrains", "answers"]).optional(),
+        rationale: tool.schema.string().optional().describe("Short explanation of why this narrative relation exists."),
+      })).optional().describe("Canonical claim-to-claim narrative progression relationships. These affect narrative approval hash."),
       evidenceBindings: tool.schema.array(tool.schema.object({
         id: tool.schema.string().optional(),
         claimId: tool.schema.string().describe("Canonical claim id this evidence supports."),
@@ -141,6 +152,18 @@ export default tool({
         severity: tool.schema.enum(["high", "medium", "low"]).optional(),
         mitigation: tool.schema.string().optional(),
       })).optional(),
+      researchGaps: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().optional(),
+        targetType: tool.schema.enum(["claim", "objection", "risk", "decision", "narrative"]).optional(),
+        targetId: tool.schema.string().optional(),
+        question: tool.schema.string().describe("Research question or gap to resolve."),
+        status: tool.schema.enum(["open", "in_progress", "findings_saved", "attached", "evidence_bound", "closed"]).optional(),
+        priority: tool.schema.enum(["high", "medium", "low"]).optional(),
+        findingsFile: tool.schema.string().optional(),
+        evidenceBindingIds: tool.schema.array(tool.schema.string()).optional(),
+        createdFromIssueType: tool.schema.string().optional(),
+        notes: 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."),
@@ -190,6 +213,13 @@ export default tool({
       layout: tool.schema.string().describe("Design layout name."),
       qa: tool.schema.boolean().optional().describe("Whether the slide is marked QA-relevant deck metadata."),
       components: tool.schema.array(tool.schema.string()).describe("Design components used by this slide."),
+      claimIds: tool.schema.array(tool.schema.string()).optional().describe("Canonical narrative claim ids directly expressed by this slide."),
+      claimRefs: tool.schema.array(tool.schema.object({
+        claimId: tool.schema.string().describe("Canonical narrative claim id referenced by this slide."),
+        role: tool.schema.enum(["primary", "supporting", "evidence", "risk", "objection"]).describe("How the slide uses this claim."),
+        note: tool.schema.string().optional().describe("Optional short rationale for this claim-slide relationship."),
+      })).optional().describe("Structured canonical claim references for this slide; preferred over flat claimIds when available."),
+      evidenceBindingIds: tool.schema.array(tool.schema.string()).optional().describe("Canonical narrative evidence binding ids used by this slide."),
       content: tool.schema.object({
         headline: tool.schema.string().optional(),
         body: tool.schema.array(tool.schema.string()).optional(),
@@ -224,6 +254,22 @@ export default tool({
     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."),
+    gapId: tool.schema.string().optional().describe("For updateResearchGap/closeResearchGap: canonical research gap id."),
+    researchGaps: tool.schema.array(tool.schema.object({
+      id: tool.schema.string().optional(),
+      targetType: tool.schema.enum(["claim", "objection", "risk", "decision", "narrative"]).optional(),
+      targetId: tool.schema.string().optional(),
+      question: tool.schema.string().describe("Research question or gap to resolve."),
+      status: tool.schema.enum(["open", "in_progress", "findings_saved", "attached", "evidence_bound", "closed"]).optional(),
+      priority: tool.schema.enum(["high", "medium", "low"]).optional(),
+      findingsFile: tool.schema.string().optional(),
+      evidenceBindingIds: tool.schema.array(tool.schema.string()).optional(),
+      createdFromIssueType: tool.schema.string().optional(),
+      notes: tool.schema.string().optional(),
+    })).optional().describe("For upsertResearchGaps: explicit canonical research gaps to create or update."),
+    gapStatus: tool.schema.enum(["open", "in_progress", "findings_saved", "attached", "evidence_bound", "closed"]).optional().describe("For updateResearchGap: lifecycle status."),
+    gapNotes: tool.schema.string().optional().describe("For updateResearchGap/closeResearchGap: notes or close reason."),
+    evidenceBindingIds: tool.schema.array(tool.schema.string()).optional().describe("For updateResearchGap: canonical narrative evidence binding ids associated with the gap."),
   },
   async execute(args, context) {
     try {
@@ -382,6 +428,12 @@ export default tool({
         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 === "backfillClaimRefs") {
+        const backfilled = backfillSlideClaimRefsFromCoverage(state)
+        writeDecksState(workspaceRoot, backfilled.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: backfilled.result, deck: backfilled.state.activeDeck ? backfilled.state.decks[backfilled.state.activeDeck] : undefined, narrative: backfilled.state.narrative }, null, 2)
+      }
+
       if (args.action === "reviewNarrative") {
         const reviewed = reviewNarrativeState(state)
         recordNarrativeReviewAction(reviewed.state, reviewed.result)
@@ -400,6 +452,39 @@ export default tool({
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: approved.result, narrative: approved.state.narrative }, null, 2)
       }
 
+      if (args.action === "deriveResearchGaps") {
+        const derived = deriveResearchGapsFromReadiness(state)
+        writeDecksState(workspaceRoot, derived.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: derived.result, narrative: derived.state.narrative }, null, 2)
+      }
+
+      if (args.action === "upsertResearchGaps") {
+        if (!args.researchGaps?.length) return JSON.stringify({ ok: false, error: "researchGaps are required for upsertResearchGaps" })
+        const upserted = upsertResearchGapsInState(state, args.researchGaps as any[])
+        writeDecksState(workspaceRoot, upserted.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: upserted.result, narrative: upserted.state.narrative }, null, 2)
+      }
+
+      if (args.action === "updateResearchGap") {
+        if (!args.gapId?.trim()) return JSON.stringify({ ok: false, error: "gapId is required for updateResearchGap" })
+        const updated = updateResearchGapInState(state, {
+          id: args.gapId,
+          status: args.gapStatus as any,
+          findingsFile: args.findingsFile,
+          evidenceBindingIds: args.evidenceBindingIds,
+          notes: args.gapNotes,
+        })
+        writeDecksState(workspaceRoot, updated.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: updated.result, narrative: updated.state.narrative }, null, 2)
+      }
+
+      if (args.action === "closeResearchGap") {
+        if (!args.gapId?.trim()) return JSON.stringify({ ok: false, error: "gapId is required for closeResearchGap" })
+        const closed = closeResearchGapInState(state, args.gapId, args.gapNotes)
+        writeDecksState(workspaceRoot, closed.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: closed.result, narrative: closed.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" })

package/tools/edit.ts

@@ -1,20 +1,20 @@
 /**
  * tools/edit.ts
  *
- * revela-edit — Open Revela's visual comment editor for an existing deck.
+ * revela-edit — Compatibility tool that opens Revela Refine in Edit mode.
  */
 
 import { tool } from "@opencode-ai/plugin"
-import { openEditableDeck } from "../lib/edit/open"
+import { openRefineDeck } from "../lib/refine/open"
 
 export function createEditTool(options: { client: any; workspaceRoot: string; openBrowser?: boolean }) {
   return tool({
     description:
-      "Open Revela's visual comment editor for an existing slide deck. " +
+      "Open Revela Refine in Edit mode for an existing slide deck. " +
       "Use this when the user asks to edit, revise, annotate, or visually comment on a deck, " +
       "including when they reference the current deck. " +
-      "Revela 0.8 opens the only HTML deck in decks/. " +
-      "This opens a local browser editor where the user can Ctrl/Cmd-click deck elements, write comments, " +
+      "This is a compatibility tool for the older edit-only workflow; the user-facing entry is /revela refine. " +
+      "It opens a local browser workspace where the user can Ctrl/Cmd-click deck elements, use the Edit tab, " +
       "and send precise edit requests back to the current OpenCode session.",
     args: {},
     async execute(_args, context: any) {
@@ -27,10 +27,11 @@ export function createEditTool(options: { client: any; workspaceRoot: string; op
       }
 
       try {
-        const result = openEditableDeck("", {
+        const result = openRefineDeck("", {
           client: options.client,
           sessionID,
           workspaceRoot: options.workspaceRoot,
+          mode: "edit",
           openBrowser: options.openBrowser,
         })
 
@@ -40,9 +41,10 @@ export function createEditTool(options: { client: any; workspaceRoot: string; op
           file: result.deck.file,
           source: result.source,
           url: result.url,
+          mode: result.mode,
           message:
-            `${result.stateNote} Opened visual editor. ` +
-            "Ask the user to use Ctrl/Cmd + click in the browser to reference elements, write a comment, then send comments.",
+            `${result.stateNote} Opened Revela Refine in Edit mode. ` +
+            "Ask the user to use Ctrl/Cmd-click in the browser to reference elements, then use the Edit tab to send comments.",
         }, null, 2)
       } catch (error) {
         return JSON.stringify({

package/tools/inspection-result.ts

@@ -29,6 +29,43 @@ export default tool({
       }).optional(),
       matchConfidence: tool.schema.enum(["none", "low", "medium", "high"]),
       cards: tool.schema.object({
+        reading: tool.schema.object({
+          status: tool.schema.enum(["matched", "no_match"]),
+          claimId: tool.schema.string().optional(),
+          canonicalClaimId: tool.schema.string().optional(),
+          claimText: tool.schema.string().optional(),
+          evidenceStatus: tool.schema.string().optional(),
+          evidenceBindingIds: tool.schema.array(tool.schema.string()),
+          supportedScope: tool.schema.string().optional(),
+          unsupportedScope: tool.schema.string().optional(),
+          caveats: tool.schema.array(tool.schema.string()),
+          relatedObjections: tool.schema.array(tool.schema.string()),
+          relatedRisks: tool.schema.array(tool.schema.string()),
+          artifactCoverage: tool.schema.array(tool.schema.object({
+            artifactId: tool.schema.string(),
+            type: tool.schema.string(),
+            outputPath: tool.schema.string().optional(),
+            coverageStatus: tool.schema.enum(["current", "stale", "partial", "missing"]),
+            containsClaim: tool.schema.boolean(),
+            stale: tool.schema.boolean(),
+            staleReason: tool.schema.string().optional(),
+            locations: tool.schema.array(tool.schema.string()),
+            note: tool.schema.string().optional(),
+          })).optional(),
+          rationale: tool.schema.string(),
+        }).optional(),
+        exploratory: tool.schema.object({
+          status: tool.schema.enum(["available", "limited", "unavailable"]),
+          official: tool.schema.boolean().describe("Must be false; exploratory reading is not official artifact content."),
+          audience: tool.schema.string().optional(),
+          claimFocus: tool.schema.string().optional(),
+          objectionPrompts: tool.schema.array(tool.schema.string()),
+          audienceReframe: tool.schema.string(),
+          appendixLeads: tool.schema.array(tool.schema.string()),
+          meetingPrep: tool.schema.array(tool.schema.string()),
+          boundaries: tool.schema.array(tool.schema.string()),
+          rationale: tool.schema.string(),
+        }).optional(),
         purpose: tool.schema.object({
           status: tool.schema.enum(["clear", "weak", "misplaced", "unknown"]),
           role: tool.schema.string().optional(),

package/tools/narrative-view.ts

@@ -0,0 +1,84 @@
+import { tool } from "@opencode-ai/plugin"
+import { hasDecksState, readDecksState } from "../lib/decks-state"
+import { buildNarrativeMap } from "../lib/narrative-state/map"
+import { validateNarrativeDisplayModel, type NarrativeDisplayModel, type NarrativeViewLanguage } from "../lib/narrative-state/display"
+import { writeNarrativeMapHtml } from "../lib/commands/narrative"
+import { openUrl } from "../lib/edit/open"
+
+export default tool({
+  description:
+    "Render Revela's read-only narrative claim-flow UI from the current deterministic narrative map plus an optional localized display model. " +
+    "This tool validates display IDs against DECKS.json, opens a local HTML view, and never mutates workspace state.",
+  args: {
+    language: tool.schema.string().describe("UI language request from /revela narrative. May be any language tag or language name, such as en, zh-CN, fr, de, Korean, Arabic, or Portuguese-BR."),
+    narrativeHash: tool.schema.string().optional().describe("Narrative hash from the prompt projection. Used to detect stale display prompts."),
+    displayModel: tool.schema.object({
+      version: tool.schema.number().describe("Must be 1."),
+      language: tool.schema.string().describe("Must exactly match the top-level language request."),
+      pageTitle: tool.schema.string().optional(),
+      summaryLine: tool.schema.string().optional(),
+      labels: tool.schema.object({
+        eyebrow: tool.schema.string().optional(),
+        claimFlow: tool.schema.string().optional(),
+        flowNote: tool.schema.string().optional(),
+        selectedClaim: tool.schema.string().optional(),
+        claim: tool.schema.string().optional(),
+        claimId: tool.schema.string().optional(),
+        status: tool.schema.string().optional(),
+        supportedScope: tool.schema.string().optional(),
+        unsupportedScope: tool.schema.string().optional(),
+        incomingRelations: tool.schema.string().optional(),
+        outgoingRelations: tool.schema.string().optional(),
+        evidence: tool.schema.string().optional(),
+        objections: tool.schema.string().optional(),
+        risks: tool.schema.string().optional(),
+        researchGaps: tool.schema.string().optional(),
+        coveredSlides: tool.schema.string().optional(),
+        noClaims: tool.schema.string().optional(),
+        none: tool.schema.string().optional(),
+      }).optional(),
+      claimCards: tool.schema.array(tool.schema.object({
+        claimId: tool.schema.string().describe("Existing canonical claim id. Must match the deterministic map."),
+        displayTitle: tool.schema.string().optional().describe("Display-only localized claim title in the requested language. For Chinese manufacturing/industrial AI context, translate autonomy as 自主化/自主能力, not 自治; convert slug-like claim text into a readable title."),
+        roleLabel: tool.schema.string().optional(),
+        narrativeJob: tool.schema.string().optional(),
+        evidenceSummary: tool.schema.string().optional(),
+        riskOrGapSummary: tool.schema.string().optional(),
+      })).optional(),
+      relations: tool.schema.array(tool.schema.object({
+        fromClaimId: tool.schema.string(),
+        toClaimId: tool.schema.string(),
+        relation: tool.schema.enum(["leads_to", "supports", "depends_on", "contrasts_with", "constrains", "answers"]),
+          displayLabel: tool.schema.string().optional().describe("Display-only localization of an existing canonical relation label. Omit for inferred relations."),
+        displayRationale: tool.schema.string().optional().describe("Display-only localization of an existing canonical rationale. Omit when canonical rationale is missing or the relation is inferred."),
+      })).optional(),
+    }).optional().describe("Localized and organized display-only projection. It must not add facts or alter IDs."),
+  },
+  async execute(args, context) {
+    const workspaceRoot = context.directory ?? process.cwd()
+    try {
+      if (!hasDecksState(workspaceRoot)) {
+        return JSON.stringify({ ok: false, error: "No DECKS.json found. Run /revela init first." })
+      }
+      const language = args.language as NarrativeViewLanguage
+      const map = buildNarrativeMap(readDecksState(workspaceRoot))
+      const stalePrompt = Boolean(args.narrativeHash && args.narrativeHash !== map.snapshot.narrativeHash)
+      const display = validateNarrativeDisplayModel(map, args.displayModel as NarrativeDisplayModel | undefined, language)
+      const htmlPath = writeNarrativeMapHtml(map, display)
+      const url = `file://${htmlPath}`
+      openUrl(url)
+      return JSON.stringify({ ok: true, url, path: htmlPath, narrativeHash: map.snapshot.narrativeHash, stalePrompt, fallback: false }, null, 2)
+    } catch (e: any) {
+      try {
+        const language = (args.language ?? "en") as NarrativeViewLanguage
+        const map = buildNarrativeMap(readDecksState(workspaceRoot))
+        const htmlPath = writeNarrativeMapHtml(map)
+        const url = `file://${htmlPath}`
+        openUrl(url)
+        return JSON.stringify({ ok: false, fallback: true, url, path: htmlPath, error: e.message || String(e) }, null, 2)
+      } catch (fallbackError: any) {
+        return JSON.stringify({ ok: false, fallback: false, error: e.message || String(e), fallbackError: fallbackError.message || String(fallbackError) })
+      }
+    }
+  },
+})