@cyber-dash-tech/revela 0.12.0 → 0.13.0

package/lib/narrative-state/render-plan.ts

@@ -1,4 +1,6 @@
 import { upsertDeck, upsertSlides, type DecksState, type EvidenceRef, type RequiredInputs, type SlideSpec } from "../decks-state"
+import { ensureActiveHtmlDeckRenderTarget } from "../workspace-state/render-targets"
+import { getClaimSlideRefs } from "./queries"
 import { computeNarrativeHash } from "./hash"
 import { normalizeNarrativeState } from "./normalize"
 import { narrativeToBrief } from "./project-compat"
@@ -64,6 +66,23 @@ export function compileDeckPlanFromNarrative(state: DecksState, options: Compile
   })
   next = upsertSlides(next, slug, slides)
   next.narrative = { ...narrative, updatedAt: options.now ?? narrative.updatedAt }
+  const htmlTarget = ensureActiveHtmlDeckRenderTarget(next)
+  if (htmlTarget) {
+    htmlTarget.data = {
+      ...(htmlTarget.data ?? {}),
+      narrativeId: narrative.id,
+      narrativeHash,
+      claimSlideRefs: getClaimSlideRefs(next).map((ref) => ({
+        claimId: ref.claimId,
+        claimText: ref.claimText,
+        slideIndex: ref.slideIndex,
+        slideTitle: ref.slideTitle,
+        match: ref.match,
+        role: ref.role,
+        location: ref.location,
+      })),
+    }
+  }
 
   return {
     state: next,
@@ -110,6 +129,7 @@ function buildSlides(narrative: NarrativeStateV1): SlideSpec[] {
 
   for (const claim of centralClaims) slides.push(claimSlide(slides.length + 1, claim, evidenceByClaim.get(claim.id) ?? []))
   if (supportingClaims.length > 0) {
+    const supportingBindings = supportingClaims.flatMap((claim) => evidenceByClaim.get(claim.id) ?? [])
     slides.push({
       index: slides.length + 1,
       title: "Supporting Logic",
@@ -118,16 +138,24 @@ function buildSlides(narrative: NarrativeStateV1): SlideSpec[] {
       layout: "card-grid",
       qa: true,
       components: ["card"],
+      claimIds: supportingClaims.map((claim) => claim.id),
+      claimRefs: supportingClaims.map((claim) => ({ claimId: claim.id, role: "supporting" as const })),
+      evidenceBindingIds: supportingBindings.map((binding) => binding.id),
       content: {
         headline: "Supporting claims and boundaries",
         bullets: supportingClaims.slice(0, 5).map((claim) => claim.text),
       },
-      evidence: supportingClaims.flatMap((claim) => (evidenceByClaim.get(claim.id) ?? []).map(evidenceRefFromBinding)),
+      evidence: supportingBindings.map(evidenceRefFromBinding),
       status: "planned",
     })
   }
 
   if (narrative.risks.length > 0 || narrative.objections.length > 0) {
+    const challengedClaimRefs = [
+      ...narrative.risks.map((risk) => risk.claimId ? { claimId: risk.claimId, role: "risk" as const } : undefined).filter((ref): ref is { claimId: string; role: "risk" } => Boolean(ref)),
+      ...narrative.objections.map((objection) => objection.claimId ? { claimId: objection.claimId, role: "objection" as const } : undefined).filter((ref): ref is { claimId: string; role: "objection" } => Boolean(ref)),
+    ]
+    const challengedClaimIds = [...new Set(challengedClaimRefs.map((ref) => ref.claimId))]
     slides.push({
       index: slides.length + 1,
       title: "Risks And Objections",
@@ -136,6 +164,8 @@ function buildSlides(narrative: NarrativeStateV1): SlideSpec[] {
       layout: "two-col",
       qa: true,
       components: ["card"],
+      claimIds: challengedClaimIds,
+      claimRefs: dedupeClaimRefs(challengedClaimRefs),
       content: {
         headline: "What could break the recommendation",
         bullets: [
@@ -176,6 +206,9 @@ function claimSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvi
     layout: "two-col",
     qa: true,
     components: ["card"],
+    claimIds: [claim.id],
+    claimRefs: [{ claimId: claim.id, role: "primary" }],
+    evidenceBindingIds: bindings.map((binding) => binding.id),
     content: {
       headline: claim.text,
       bullets: [claim.supportedScope, claim.unsupportedScope ? `Unsupported scope: ${claim.unsupportedScope}` : undefined, ...(claim.caveats ?? [])].filter((item): item is string => Boolean(item)),
@@ -185,6 +218,16 @@ function claimSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvi
   }
 }
 
+function dedupeClaimRefs<T extends { claimId: string; role: "risk" | "objection" }>(refs: T[]): T[] {
+  const seen = new Set<string>()
+  return refs.filter((ref) => {
+    const key = `${ref.claimId}:${ref.role}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
 function evidenceRefFromBinding(binding: NarrativeEvidenceBinding): EvidenceRef {
   return {
     source: binding.source,

package/lib/narrative-state/research-gaps.ts

@@ -0,0 +1,191 @@
+import type { DecksState } from "../decks-state"
+import { recordWorkspaceAction } from "../workspace-state/actions"
+import { stableResearchGapId } from "./hash"
+import { normalizeNarrativeState } from "./normalize"
+import { reviewNarrativeState } from "./readiness"
+import type {
+  NarrativeReadinessIssue,
+  NarrativeResearchGap,
+  NarrativeResearchGapStatus,
+  NarrativeResearchGapTargetType,
+  NarrativeStateV1,
+} from "./types"
+
+export interface UpsertResearchGapInput {
+  id?: string
+  targetType?: NarrativeResearchGapTargetType
+  targetId?: string
+  question: string
+  status?: NarrativeResearchGapStatus
+  priority?: "high" | "medium" | "low"
+  findingsFile?: string
+  evidenceBindingIds?: string[]
+  createdFromIssueType?: NarrativeReadinessIssue["type"]
+  notes?: string
+}
+
+export interface UpdateResearchGapInput {
+  id: string
+  status?: NarrativeResearchGapStatus
+  findingsFile?: string
+  evidenceBindingIds?: string[]
+  notes?: string
+}
+
+export interface ResearchGapMutationResult {
+  created: NarrativeResearchGap[]
+  updated: NarrativeResearchGap[]
+  skipped: Array<{ id?: string; question?: string; reason: string }>
+  gaps: NarrativeResearchGap[]
+}
+
+export interface CloseResearchGapResult {
+  closed: boolean
+  skipped: boolean
+  reason?: string
+  gap?: NarrativeResearchGap
+}
+
+export function deriveResearchGapsFromReadiness(state: DecksState, options: { now?: string } = {}): { state: DecksState; result: ResearchGapMutationResult } {
+  const reviewed = reviewNarrativeState(state, { now: options.now })
+  return upsertResearchGapsInState(reviewed.state, gapsFromIssues(reviewed.state.narrative!, reviewed.result.issues), options)
+}
+
+export function upsertResearchGapsInState(state: DecksState, inputs: UpsertResearchGapInput[], options: { now?: string } = {}): { state: DecksState; result: ResearchGapMutationResult } {
+  const now = options.now ?? new Date().toISOString()
+  const narrative = ensureNarrative(state)
+  const existing = new Map((narrative.researchGaps ?? []).map((gap) => [gap.id, gap]))
+  const created: NarrativeResearchGap[] = []
+  const updated: NarrativeResearchGap[] = []
+  const skipped: ResearchGapMutationResult["skipped"] = []
+
+  for (const input of inputs) {
+    const question = clean(input.question)
+    if (!question) {
+      skipped.push({ reason: "question is required" })
+      continue
+    }
+    const targetType = input.targetType ?? "narrative"
+    const targetId = clean(input.targetId)
+    const id = input.id?.trim() || stableResearchGapId([targetType, targetId, question].filter(Boolean).join("|"))
+    const prior = existing.get(id)
+    if (prior?.status === "closed") {
+      skipped.push({ id, question, reason: "matching research gap is already closed" })
+      continue
+    }
+
+    const next: NarrativeResearchGap = {
+      id,
+      targetType,
+      targetId,
+      question,
+      status: input.status ?? prior?.status ?? "open",
+      priority: input.priority ?? prior?.priority ?? "medium",
+      findingsFile: clean(input.findingsFile) || prior?.findingsFile,
+      evidenceBindingIds: mergeIds(prior?.evidenceBindingIds, input.evidenceBindingIds),
+      createdFromIssueType: input.createdFromIssueType ?? prior?.createdFromIssueType,
+      notes: clean(input.notes) || prior?.notes,
+      createdAt: prior?.createdAt ?? now,
+      updatedAt: now,
+      closedAt: input.status === "closed" ? now : prior?.closedAt,
+    }
+    existing.set(id, next)
+    if (prior) updated.push(next)
+    else created.push(next)
+  }
+
+  const gaps = [...existing.values()].sort((a, b) => gapSortValue(a) - gapSortValue(b) || a.question.localeCompare(b.question))
+  state.narrative = { ...narrative, researchGaps: gaps, updatedAt: now }
+  if (created.length > 0) recordResearchGapAction(state, "research.gap_created", created, now)
+  if (updated.length > 0) recordResearchGapAction(state, "research.gap_updated", updated, now)
+  return { state, result: { created, updated, skipped, gaps } }
+}
+
+export function updateResearchGapInState(state: DecksState, input: UpdateResearchGapInput, options: { now?: string } = {}): { state: DecksState; result: ResearchGapMutationResult } {
+  const narrative = ensureNarrative(state)
+  const gap = (narrative.researchGaps ?? []).find((item) => item.id === input.id)
+  if (!gap) return { state, result: { created: [], updated: [], skipped: [{ id: input.id, reason: "research gap not found" }], gaps: narrative.researchGaps ?? [] } }
+  return upsertResearchGapsInState(state, [{ ...gap, ...input, question: gap.question, targetType: gap.targetType, targetId: gap.targetId }], options)
+}
+
+export function closeResearchGapInState(state: DecksState, id: string, reason?: string, options: { now?: string } = {}): { state: DecksState; result: CloseResearchGapResult } {
+  const now = options.now ?? new Date().toISOString()
+  const narrative = ensureNarrative(state)
+  const gaps = narrative.researchGaps ?? []
+  const gap = gaps.find((item) => item.id === id)
+  if (!gap) return { state, result: { closed: false, skipped: true, reason: "research gap not found" } }
+  const closed: NarrativeResearchGap = { ...gap, status: "closed", notes: clean(reason) || gap.notes, updatedAt: now, closedAt: now }
+  state.narrative = { ...narrative, researchGaps: gaps.map((item) => item.id === id ? closed : item), updatedAt: now }
+  recordResearchGapAction(state, "research.gap_closed", [closed], now)
+  return { state, result: { closed: true, skipped: false, gap: closed } }
+}
+
+function gapsFromIssues(narrative: NarrativeStateV1, issues: NarrativeReadinessIssue[]): UpsertResearchGapInput[] {
+  return issues.flatMap((issue) => {
+    if (!researchableIssue(issue)) return []
+    const target = targetForIssue(narrative, issue)
+    return [{
+      targetType: target.type,
+      targetId: target.id,
+      question: questionForIssue(issue),
+      priority: issue.severity === "blocker" ? "high" : "medium",
+      status: "open",
+      createdFromIssueType: issue.type,
+      notes: issue.suggestedAction,
+      findingsFile: issue.source?.startsWith("researches/") ? issue.source : undefined,
+    }]
+  })
+}
+
+function researchableIssue(issue: NarrativeReadinessIssue): boolean {
+  return issue.type === "missing_evidence" || issue.type === "weak_evidence" || issue.type === "unsupported_scope" || issue.type === "unhandled_objection" || issue.type === "missing_risk"
+}
+
+function targetForIssue(narrative: NarrativeStateV1, issue: NarrativeReadinessIssue): { type: NarrativeResearchGapTargetType; id?: string } {
+  if (issue.claimId) return { type: "claim", id: issue.claimId }
+  const objection = narrative.objections.find((item) => item.text === issue.claimText)
+  if (objection) return { type: "objection", id: objection.id }
+  if (issue.type === "missing_risk") return { type: "decision", id: narrative.decision.action ? stableResearchGapId(`decision:${narrative.decision.action}`) : undefined }
+  return { type: "narrative", id: narrative.id }
+}
+
+function questionForIssue(issue: NarrativeReadinessIssue): string {
+  if (issue.claimText && issue.type === "missing_evidence") return `Find evidence for claim: ${issue.claimText}`
+  if (issue.claimText && issue.type === "weak_evidence") return `Strengthen evidence for claim: ${issue.claimText}`
+  if (issue.claimText && issue.type === "unsupported_scope") return `Resolve unsupported scope for claim: ${issue.claimText}`
+  if (issue.type === "unhandled_objection") return `Find response or evidence for objection: ${issue.claimText ?? issue.message}`
+  if (issue.type === "missing_risk") return "Identify risk, assumption, caveat, or tradeoff handling for the recommendation."
+  return issue.message
+}
+
+function ensureNarrative(state: DecksState): NarrativeStateV1 {
+  state.narrative = normalizeNarrativeState(state)
+  return state.narrative
+}
+
+function recordResearchGapAction(state: DecksState, type: "research.gap_created" | "research.gap_updated" | "research.gap_closed", gaps: NarrativeResearchGap[], timestamp: string): void {
+  recordWorkspaceAction(state, {
+    type,
+    actor: "revela-decks",
+    timestamp,
+    inputs: { narrativeId: state.narrative?.id },
+    outputs: { gaps: gaps.map((gap) => ({ id: gap.id, status: gap.status, targetType: gap.targetType, targetId: gap.targetId, findingsFile: gap.findingsFile, evidenceBindingIds: gap.evidenceBindingIds })) },
+    status: "success",
+    summary: `${type === "research.gap_created" ? "Created" : type === "research.gap_closed" ? "Closed" : "Updated"} ${gaps.length} research gap${gaps.length === 1 ? "" : "s"}.`,
+    nodeIds: gaps.map((gap) => gap.id),
+  })
+}
+
+function gapSortValue(gap: NarrativeResearchGap): number {
+  const statusValue: Record<NarrativeResearchGapStatus, number> = { open: 0, in_progress: 1, findings_saved: 2, attached: 3, evidence_bound: 4, closed: 5 }
+  const priorityValue = gap.priority === "high" ? 0 : gap.priority === "medium" ? 1 : 2
+  return statusValue[gap.status] * 10 + priorityValue
+}
+
+function mergeIds(existing: string[] | undefined, next: string[] | undefined): string[] {
+  return [...new Set([...(existing ?? []), ...(next ?? [])].map(clean).filter(Boolean))].sort()
+}
+
+function clean(value: string | undefined): string {
+  return value?.trim() ?? ""
+}

package/lib/narrative-state/types.ts

@@ -4,6 +4,12 @@ export type NarrativeClaimKind = "context" | "problem" | "opportunity" | "eviden
 
 export type NarrativeEvidenceStatus = "supported" | "partial" | "weak" | "missing" | "not_required"
 
+export type NarrativeResearchGapStatus = "open" | "in_progress" | "findings_saved" | "attached" | "evidence_bound" | "closed"
+
+export type NarrativeResearchGapTargetType = "claim" | "objection" | "risk" | "decision" | "narrative"
+
+export type NarrativeClaimRelationType = "leads_to" | "supports" | "depends_on" | "contrasts_with" | "constrains" | "answers"
+
 export interface NarrativeStateV1 {
   version: 1
   id: string
@@ -12,9 +18,11 @@ export interface NarrativeStateV1 {
   decision: DecisionIntent
   thesis?: NarrativeThesis
   claims: NarrativeClaim[]
+  claimRelations?: NarrativeClaimRelation[]
   evidenceBindings: NarrativeEvidenceBinding[]
   objections: NarrativeObjection[]
   risks: NarrativeRisk[]
+  researchGaps?: NarrativeResearchGap[]
   approvals: NarrativeApproval[]
   updatedAt: string
 }
@@ -55,6 +63,14 @@ export interface NarrativeClaim {
   caveats?: string[]
 }
 
+export interface NarrativeClaimRelation {
+  id: string
+  fromClaimId: string
+  toClaimId: string
+  relation: NarrativeClaimRelationType
+  rationale?: string
+}
+
 export interface NarrativeEvidenceBinding {
   id: string
   claimId: string
@@ -86,6 +102,22 @@ export interface NarrativeRisk {
   mitigation?: string
 }
 
+export interface NarrativeResearchGap {
+  id: string
+  targetType: NarrativeResearchGapTargetType
+  targetId?: string
+  question: string
+  status: NarrativeResearchGapStatus
+  priority: "high" | "medium" | "low"
+  findingsFile?: string
+  evidenceBindingIds?: string[]
+  createdFromIssueType?: NarrativeReadinessIssueType
+  notes?: string
+  createdAt: string
+  updatedAt: string
+  closedAt?: string
+}
+
 export interface NarrativeApproval {
   id: string
   narrativeHash: string
@@ -112,6 +144,7 @@ export type NarrativeReadinessIssueType =
   | "approval_stale"
   | "artifact_stale"
   | "research_findings_unattached"
+  | "research_gap_open"
 
 export interface NarrativeReadinessIssue {
   type: NarrativeReadinessIssueType

package/lib/workspace-state/evidence-status.ts

@@ -40,15 +40,25 @@ export interface EvidenceStatusMatch {
   slideIndex?: number
   slideTitle?: string
   claimId?: string
+  canonicalClaimId?: string
   claimText?: string
   claimEvidenceSensitive?: boolean
   claimEvidenceSupport?: string
+  evidenceBindingIds: string[]
+  supportedScope?: string
+  unsupportedScope?: string
+  caveats: string[]
 }
 
 export interface EvidenceStatusEvidence extends EvidenceRef {
   slideIndex: number
   slideTitle: string
   hasDetail: boolean
+  evidenceBindingId?: string
+  claimId?: string
+  supportScope?: string
+  unsupportedScope?: string
+  strength?: "strong" | "partial" | "weak"
 }
 
 export interface EvidenceStatusGap {
@@ -159,9 +169,14 @@ function projectMatch(match: InspectionElementMatch): EvidenceStatusMatch {
     slideIndex: match.slide?.index,
     slideTitle: match.slide?.title,
     claimId: match.claim?.id,
+    canonicalClaimId: match.claim?.canonicalClaimId,
     claimText: match.claim?.text,
     claimEvidenceSensitive: match.claim?.evidenceSensitive,
     claimEvidenceSupport: match.claim?.evidenceSupport,
+    evidenceBindingIds: match.claim?.evidenceBindingIds ?? [],
+    supportedScope: match.claim?.supportedScope,
+    unsupportedScope: match.claim?.unsupportedScope,
+    caveats: match.claim?.caveats ?? [],
   }
 }
 
@@ -235,7 +250,12 @@ function relevantSearchDiagnostics(issues: ReadinessIssue[], match: InspectionEl
 
 function actionTraceForMatch(actions: WorkspaceAction[], match: InspectionElementMatch): EvidenceStatusActionTrace[] {
   const slideNodeId = match.slide ? `slide:${match.slide.index}` : undefined
-  const evidenceKeys = new Set(match.evidence.flatMap((item) => [item.source, item.sourcePath, item.findingsFile].filter((value): value is string => Boolean(value))))
+  const evidenceKeys = new Set([
+    match.claim?.id,
+    match.claim?.canonicalClaimId,
+    ...(match.claim?.evidenceBindingIds ?? []),
+    ...match.evidence.flatMap((item) => [item.source, item.sourcePath, item.findingsFile, item.evidenceBindingId, item.claimId]),
+  ].filter((value): value is string => Boolean(value)))
   return actions
     .filter((action) => actionRelevantToMatch(action, slideNodeId, evidenceKeys))
     .slice(-12)

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.13.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.")
@@ -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,