@cyber-dash-tech/revela 0.8.9 → 0.10.0

package/package.json

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

package/plugin.ts

@@ -46,6 +46,8 @@ import {
 import { handlePdf } from "./lib/commands/pdf"
 import { buildPptxNotesPrompt, handlePptx, parsePptxArgs, resolvePptxDeck } from "./lib/commands/pptx"
 import { handleEdit } from "./lib/commands/edit"
+import { handleInspect } from "./lib/commands/inspect"
+import { handleRefine } from "./lib/commands/refine"
 import { ensureEditableDeckOpenForChange } from "./lib/edit/open"
 import { hasLiveEditorSessionForFile } from "./lib/edit/server"
 import { handleDesignsPreview } from "./lib/commands/designs-preview"
@@ -80,6 +82,8 @@ import mediaBatchSaveTool from "./tools/media-batch-save"
 import mediaSaveTool from "./tools/media-save"
 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 workspaceScanTool from "./tools/workspace-scan"
 import extractDocumentMaterialsTool from "./tools/extract-document-materials"
 import qaTool from "./tools/qa"
@@ -87,6 +91,7 @@ import pdfTool from "./tools/pdf"
 import pptxTool from "./tools/pptx"
 import createEditTool from "./tools/edit"
 import { RESEARCH_PROMPT, RESEARCH_AGENT_SIGNATURE } from "./lib/agents/research-prompt"
+import { NARRATIVE_REVIEWER_PROMPT, NARRATIVE_REVIEWER_SIGNATURE } from "./lib/agents/narrative-reviewer-prompt"
 import { formatReport, runComplianceQA } from "./lib/qa"
 import { extractDesignClasses } from "./lib/design/designs"
 import { log, childLog } from "./lib/log"
@@ -204,7 +209,7 @@ const server: Plugin = (async (pluginCtx) => {
   }
 
   return {
-    // ── Register /revela command + revela-research subagent ───────────────
+    // ── Register /revela command + Revela subagents ───────────────────────
     config: async (opencodeConfig) => {
       opencodeConfig.command ??= {}
       opencodeConfig.command["revela"] = {
@@ -235,6 +240,24 @@ const server: Plugin = (async (pluginCtx) => {
       // Give revela-research explicit websearch allow (overrides global deny below)
       ;(opencodeConfig.agent["revela-research"].permission as any).websearch = "allow"
 
+      // Register the read-only narrative reviewer subagent.
+      // It can inspect workspace state and referenced files, but cannot write or browse.
+      opencodeConfig.agent["revela-narrative-reviewer"] = {
+        description: "Revela narrative reviewer — read-only critique of narrative brief and slide-plan alignment",
+        mode: "subagent",
+        prompt: NARRATIVE_REVIEWER_PROMPT,
+        permission: {
+          edit: "deny",
+          bash: {
+            "*": "deny",
+            "ls *": "allow",
+            "ls": "allow",
+          },
+          webfetch: "deny",
+          websearch: "deny",
+        } as any,
+      }
+
       // Block websearch for the primary agent globally.
       // permission.ask hook is not triggered by OpenCode (no R.trigger call in binary).
       // tool.execute.before throw is swallowed (trigger().catch(()=>{})).
@@ -313,6 +336,14 @@ const server: Plugin = (async (pluginCtx) => {
         } 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/`.")
+          throw new Error("__REVELA_REFINE_USAGE_HANDLED__")
+        }
+        await handleRefine({ client, sessionID, workspaceRoot }, send)
+        throw new Error("__REVELA_REFINE_HANDLED__")
+      }
       if (sub === "edit") {
         if (param) {
           await send("`/revela edit` no longer accepts a target. It opens the only HTML deck in `decks/`.")
@@ -321,6 +352,14 @@ const server: Plugin = (async (pluginCtx) => {
         await handleEdit({ client, sessionID, workspaceRoot }, send)
         throw new Error("__REVELA_EDIT_HANDLED__")
       }
+      if (sub === "inspect") {
+        if (param) {
+          await send("`/revela inspect` does not accept a target. It opens the only HTML deck in `decks/`.")
+          throw new Error("__REVELA_INSPECT_USAGE_HANDLED__")
+        }
+        await handleInspect({ client, sessionID, workspaceRoot }, send)
+        throw new Error("__REVELA_INSPECT_HANDLED__")
+      }
       if (sub === "designs" && !param) {
         await handleDesignsList(send)
         throw new Error("__REVELA_DESIGNS_LIST_HANDLED__")
@@ -419,6 +458,8 @@ const server: Plugin = (async (pluginCtx) => {
       "revela-media-save": mediaSaveTool,
       "revela-research-images-list": researchImagesListTool,
       "revela-research-save": researchSaveTool,
+      "revela-inspection-context": inspectionContextTool,
+      "revela-inspection-result": inspectionResultTool,
       "revela-workspace-scan": workspaceScanTool,
       "revela-extract-document-materials": extractDocumentMaterialsTool,
       "revela-qa": qaTool,
@@ -481,7 +522,7 @@ const server: Plugin = (async (pluginCtx) => {
 
     // ── Inject three-layer prompt when enabled ─────────────────────────────
     // Skip injection for:
-    //   1. revela-research subagent (has its own research-focused prompt)
+    //   1. Revela subagents (they have focused prompts)
     //   2. OpenCode internal agents (title, summary, compaction)
     "experimental.chat.system.transform": async (input, output) => {
       if (!ctx.enabled) return
@@ -498,6 +539,10 @@ const server: Plugin = (async (pluginCtx) => {
         }
         ctx.isResearchAgent = false
 
+        // Skip revela-narrative-reviewer subagent — it is read-only critique,
+        // not a deck-writing agent and not a research agent.
+        if (systemText.includes(NARRATIVE_REVIEWER_SIGNATURE)) return
+
         // Skip OpenCode internal system agents (title generator, summary, compaction)
         if (INTERNAL_AGENT_SIGNATURES.some((sig) => systemText.includes(sig))) return
 

package/skill/SKILL.md

@@ -83,6 +83,7 @@ Create or update the active deck in `DECKS.json` through `revela-decks` actions
 `upsertDeck` and `upsertSlides`. Keep the deck spec current as work progresses:
 - `goal` — purpose and decision/context
 - `audience`, `language`, `outputPath`, and `theme`
+- `narrativeBrief` — for substantial decision decks, the 0.9 compiler brief: audience belief before/after, decisionOrAction, narrativeArc, keyClaims, objections, and risks
 - `requiredInputs` — checklist state for prewrite readiness
 - `researchPlan` — axes, status, and findings files
 - `slides` — confirmed per-slide title, purpose, layout, components, content, evidence, visuals, and status
@@ -200,6 +201,26 @@ state updates. Do not write temporary hypotheses, unsupported conclusions,
 secrets, or inferred user preferences. User and workflow preferences require
 explicit user intent to remember.
 
+#### Narrative Review via `revela-narrative-reviewer`
+
+`revela-narrative-reviewer` is a read-only OpenCode subagent, **not a tool**.
+Launch it through the Task tool with `subagent_type: "revela-narrative-reviewer"`
+when a substantial decision deck needs independent rubric-based critique of the
+Narrative Compiler brief and slide-plan alignment.
+
+Use it after the narrative brief and slide specs are recorded in `DECKS.json`,
+and before treating narrative quality as reviewed. The primary agent should not
+self-certify semantic narrative quality. `revela-decks review` remains the
+authoritative write-readiness gate; reviewer findings are advisory notes only.
+The reviewer uses stable finding IDs such as `NB-001`, `KC-001`, `ASK-001`, and
+`EV-001`. If the fixed rubric passes, it should return `Findings: none` rather
+than inventing optional improvements.
+
+The reviewer may read `DECKS.json`, slide specs, evidence refs, and existing
+`researches/{workspace-key}/*.md` files referenced by the deck. It must not write
+state, call `upsertDeck`, call `upsertSlides`, call `revela-decks review`, use
+websearch/webfetch, or generate/edit HTML.
+
 #### AI Knowledge and User Questions
 
 Use AI knowledge only to fill remaining gaps around verified sources. Mark it
@@ -213,6 +234,8 @@ already checked and what specific missing information is needed.
 
 - **NEVER** use `websearch` directly from the primary agent; delegate web research to `revela-research` subagents
 - **NEVER** call `revela-research` as a tool; use Task with `subagent_type: "revela-research"`
+- **NEVER** call `revela-narrative-reviewer` as a tool; use Task with `subagent_type: "revela-narrative-reviewer"`
+- **NEVER** present `revela-narrative-reviewer` findings as authoritative `revela-decks review` blockers or readiness issues
 - **NEVER** collapse distinct research axes into one broad agent brief when parallel focused briefs would be clearer
 - **ALWAYS** use `revela-decks` action `read` before deciding what research is needed
 - **ALWAYS** read each `researches/{workspace-key}/{axis}.md` after agents complete
@@ -238,12 +261,17 @@ A 6-slide deck might be: Cover → Background → Content × 3 → Closing.
 An 8-slide deck might be: Cover → TOC → Background → Content × 3 → Summary → Closing.
 Never skip Cover, Background, or Closing regardless of deck length.
 
-**Every `<section class="slide">` must include a `slide-qa` attribute.** Set
-`slide-qa="true"` for content-heavy layouts (those marked ✓ in the Layout Index
-QA column of the active design). Set `slide-qa="false"` for structural or sparse
-layouts (cover, TOC, closing, quote, summary, etc.). When unsure, use `"false"`.
+**Every `<section class="slide">` must include `slide-qa` and
+`data-slide-index` attributes.** Set `slide-qa="true"` for content-heavy layouts
+(those marked ✓ in the Layout Index QA column of the active design). Set
+`slide-qa="false"` for structural or sparse layouts (cover, TOC, closing, quote,
+summary, etc.). When unsure, use `"false"`.
+
+`data-slide-index` is the canonical 1-based slide identity. It must match the
+corresponding `DECKS.json` `slides[].index` value. Do not use 0-based
+`data-index` as slide identity.
 
-Example: `<section class="slide" slide-qa="true" data-index="0">`
+Example: `<section class="slide" slide-qa="true" data-slide-index="1">`
 
 The export QA path treats this as deck metadata. It is consumed when PDF/PPTX
 export runs preflight checks.
@@ -287,8 +315,17 @@ core rules and the visual design below.
 
 ### Phase 4 — Presentation Plan
 
-After all research is complete and findings have been read, present a detailed
-slide plan to the user **before writing any HTML**.
+After all research is complete and findings have been read, present a compact narrative brief
+and a detailed slide plan to the user **before writing any HTML**.
+
+For substantial decision decks, first summarize the Narrative Compiler brief:
+- Audience belief before: what the audience currently believes, assumes, or does not yet understand
+- Audience belief after: what the audience should believe or understand after the deck
+- Decision/action: the approval, decision, behavior, or next step the deck should drive
+- Narrative arc: the intended story path, such as context -> tension -> evidence -> recommendation -> risk -> ask
+- Key claims: the main claims the deck must prove
+- Likely objections: stakeholder resistance or questions the story should handle
+- Risks/assumptions: caveats, tradeoffs, or uncertainty that should travel with the recommendation
 
 Format the plan as a markdown table:
 
@@ -320,8 +357,9 @@ Then ask:
 - On change request → update the table and ask again
 
 After the user confirms the slide plan, update `DECKS.json` through `revela-decks`:
-- Call `upsertDeck` to mark completed `requiredInputs` only when explicitly satisfied.
+- Call `upsertDeck` to preserve `narrativeBrief` when available and mark completed `requiredInputs` only when explicitly satisfied.
 - Call `upsertSlides` with the confirmed per-slide content, narrativeRole, layout, components, and evidence.
+- For substantial decision decks, use Task with `subagent_type: "revela-narrative-reviewer"` for read-only rubric-based critique of narrativeBrief and slide-plan alignment. Ask for stable finding IDs and `Findings: none` when the rubric passes; do not ask the reviewer to write state, determine readiness, or brainstorm optional improvements.
 - Keep write readiness blocked until Phase 5 calls `revela-decks review` and the tool returns ready.
 
 ---

package/tools/decks.ts

@@ -1,5 +1,6 @@
 import { tool } from "@opencode-ai/plugin"
 import {
+  applyEvidenceCandidates,
   createDeckSpec,
   DECKS_STATE_FILE,
   normalizeWorkspaceDeckState,
@@ -10,6 +11,7 @@ import {
   writeDecksState,
   workspaceDeckSlug,
   type DeckSpec,
+  type NarrativeBrief,
   type RequiredInputs,
   type ResearchAxis,
   type SourceMaterial,
@@ -24,13 +26,22 @@ export default tool({
     "It stores active deck specs, per-slide content/layout/components, and computes write readiness.",
   args: {
     action: tool.schema
-      .enum(["read", "init", "upsertDeck", "upsertSlides", "review", "remember"])
+      .enum(["read", "init", "upsertDeck", "upsertSlides", "review", "applyEvidenceCandidates", "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."),
     audience: tool.schema.string().optional().describe("For upsertDeck: deck audience."),
     language: tool.schema.string().optional().describe("For upsertDeck: deck language."),
     outputPath: tool.schema.string().optional().describe("For upsertDeck: target output path, normally decks/{workspace-name}.html."),
+    narrativeBrief: tool.schema.object({
+      audienceBeliefBefore: tool.schema.string().optional().describe("What the audience currently believes, assumes, or does not yet understand."),
+      audienceBeliefAfter: tool.schema.string().optional().describe("What the audience should believe or understand after the deck."),
+      decisionOrAction: tool.schema.string().optional().describe("The decision, approval, action, or behavioral change the deck is meant to drive."),
+      narrativeArc: tool.schema.string().optional().describe("Compact story arc, such as context -> tension -> evidence -> recommendation -> ask."),
+      keyClaims: tool.schema.array(tool.schema.string()).optional().describe("Main claims the deck must prove or communicate."),
+      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."),
     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."),
@@ -106,6 +117,7 @@ export default tool({
       status: tool.schema.enum(["planned", "ready", "written", "qa_passed", "qa_failed"]).optional().describe("Slide production status."),
       notes: tool.schema.string().optional().describe("Implementation notes for this slide."),
     })).optional().describe("For upsertSlides: complete or partial slide specs."),
+    candidateIds: tool.schema.array(tool.schema.string()).optional().describe("For applyEvidenceCandidates: candidate IDs returned by revela-decks review to explicitly bind proposed evidenceDraft records into slide evidence."),
   },
   async execute(args, context) {
     try {
@@ -140,6 +152,7 @@ export default tool({
           audience: args.audience ?? existing?.audience,
           language: args.language ?? existing?.language,
           outputPath: args.outputPath ?? existing?.outputPath,
+          narrativeBrief: (args.narrativeBrief as NarrativeBrief | undefined) ?? existing?.narrativeBrief,
           theme: {
             design: args.design ?? existing?.theme?.design,
             domain: args.domain ?? existing?.theme?.domain,
@@ -164,11 +177,19 @@ export default tool({
       }
 
       if (args.action === "review") {
-        const reviewed = reviewDeckState(state)
+        const reviewed = reviewDeckState(state, undefined, { workspaceRoot })
         writeDecksState(workspaceRoot, reviewed.state)
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: reviewed.result }, 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" })
+        const applied = applyEvidenceCandidates(state, candidateIds, { workspaceRoot })
+        writeDecksState(workspaceRoot, applied.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: applied.result }, null, 2)
+      }
+
       if (args.action === "remember") {
         const memory = args.memory?.trim()
         if (!memory) return JSON.stringify({ ok: false, error: "memory is required for remember" })

package/tools/inspection-context.ts

@@ -0,0 +1,22 @@
+import { tool } from "@opencode-ai/plugin"
+import { compileInspectionContext } from "../lib/inspection-context/compile"
+import { normalizeWorkspaceDeckState, readOrCreateDecksState } from "../lib/decks-state"
+
+export default tool({
+  description:
+    "Compile Revela's current DECKS.json into structured inspection context for debugging and future Evidence Inspector flows. " +
+    "This is read-only: it does not write artifacts, mutate DECKS.json, or generate user-facing files.",
+  args: {
+    slug: tool.schema.string().optional().describe("Optional deck slug to compile. Defaults to the active workspace deck."),
+  },
+  async execute(args, context) {
+    try {
+      const workspaceRoot = context.directory ?? process.cwd()
+      const state = normalizeWorkspaceDeckState(readOrCreateDecksState(workspaceRoot), workspaceRoot)
+      const inspectionContext = compileInspectionContext(state, args.slug)
+      return JSON.stringify({ ok: true, inspectionContext }, null, 2)
+    } catch (e: any) {
+      return JSON.stringify({ ok: false, error: e.message || String(e) })
+    }
+  },
+})

package/tools/inspection-result.ts

@@ -0,0 +1,63 @@
+import { tool } from "@opencode-ai/plugin"
+import { completeInspectRequest } from "../lib/inspect/requests"
+import type { InspectionResult } from "../lib/inspection-context/result"
+
+const evidenceSourceItemSchema = tool.schema.object({
+  source: tool.schema.string().describe("Human-readable source label."),
+  sourcePath: tool.schema.string().optional(),
+  findingsFile: tool.schema.string().optional(),
+  location: tool.schema.string().optional(),
+  page: tool.schema.string().optional(),
+  url: tool.schema.string().optional(),
+  quote: tool.schema.string().optional(),
+  caveat: tool.schema.string().optional(),
+})
+
+export default tool({
+  description:
+    "Submit the final structured Evidence Inspector result for a pending /revela inspect request. " +
+    "Use only when responding to an inspection prompt. This updates the local browser inspector; it does not mutate DECKS.json or deck files.",
+  args: {
+    requestId: tool.schema.string().describe("Pending inspection request id from the inspection prompt."),
+    result: tool.schema.object({
+      version: tool.schema.number().describe("Must be 1."),
+      status: tool.schema.enum(["success", "no_match"]),
+      selectedText: tool.schema.string().optional(),
+      slide: tool.schema.object({
+        index: tool.schema.number(),
+        title: tool.schema.string(),
+      }).optional(),
+      matchConfidence: tool.schema.enum(["none", "low", "medium", "high"]),
+      cards: tool.schema.object({
+        purpose: tool.schema.object({
+          status: tool.schema.enum(["clear", "weak", "misplaced", "unknown"]),
+          role: tool.schema.string().optional(),
+          rationale: tool.schema.string(),
+          whyItMatters: tool.schema.string(),
+        }),
+        source: tool.schema.object({
+          status: tool.schema.enum(["supported", "weak", "unsupported", "not_needed", "unknown"]),
+          matchedClaim: tool.schema.string().optional(),
+          sources: tool.schema.array(evidenceSourceItemSchema),
+          warnings: tool.schema.array(tool.schema.string()),
+          gaps: tool.schema.array(tool.schema.string()),
+          caveats: tool.schema.array(tool.schema.string()),
+          rationale: tool.schema.string(),
+        }),
+      }),
+      stale: tool.schema.object({
+        stale: tool.schema.boolean(),
+        reason: tool.schema.string().optional(),
+      }).optional(),
+    }).describe("Final structured inspector result to render in the browser."),
+  },
+  async execute(args) {
+    try {
+      if (args.result.version !== 1) throw new Error("Inspection result version must be 1.")
+      const request = completeInspectRequest(args.requestId, args.result as InspectionResult)
+      return JSON.stringify({ ok: true, requestId: request.requestId, status: request.status })
+    } catch (e: any) {
+      return JSON.stringify({ ok: false, error: e.message || String(e) })
+    }
+  },
+})