@cyber-dash-tech/revela 0.10.0 → 0.12.0

package/plugin.ts

@@ -48,6 +48,7 @@ import { buildPptxNotesPrompt, handlePptx, parsePptxArgs, resolvePptxDeck } from
 import { handleEdit } from "./lib/commands/edit"
 import { handleInspect } from "./lib/commands/inspect"
 import { handleRefine } from "./lib/commands/refine"
+import { formatDeckHtmlContractReport, validateDeckHtmlContract } from "./lib/deck-html/contract"
 import { ensureEditableDeckOpenForChange } from "./lib/edit/open"
 import { hasLiveEditorSessionForFile } from "./lib/edit/server"
 import { handleDesignsPreview } from "./lib/commands/designs-preview"
@@ -59,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,
@@ -177,6 +178,27 @@ const server: Plugin = (async (pluginCtx) => {
     }
   }
 
+  async function appendDeckHtmlContractReport(filePath: string, output: any): Promise<void> {
+    if (!isDeckHtmlPath(filePath)) return
+
+    try {
+      const report = validateDeckHtmlContract(workspaceRoot, filePath)
+      if (report.status === "valid" || report.status === "skipped") return
+
+      appendToolResult(
+        output,
+        "---\n\n**[revela deck HTML contract]** Slide identity check failed:\n\n" +
+        formatDeckHtmlContractReport(report) +
+        "\n\nFix every `<section class=\"slide\">` to use the matching 1-based `data-slide-index` from DECKS.json before inspection or export."
+      )
+    } catch (e) {
+      childLog("deck-contract").warn("deck HTML contract report failed", {
+        filePath,
+        error: e instanceof Error ? e.message : String(e),
+      })
+    }
+  }
+
   function extractSessionID(input: any): string {
     return input?.sessionID ?? input?.session?.id ?? input?.context?.sessionID ?? ""
   }
@@ -304,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",
@@ -317,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",
@@ -326,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",
@@ -336,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/`.")
@@ -423,7 +470,7 @@ const server: Plugin = (async (pluginCtx) => {
         throw new Error("__REVELA_DOMAINS_RM_HANDLED__")
       }
       if (sub === "pdf") {
-        await handlePdf(param, send)
+        await handlePdf(param, send, workspaceRoot)
         throw new Error("__REVELA_PDF_HANDLED__")
       }
       if (sub === "pptx") {
@@ -742,6 +789,7 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
           return
         }
         await appendComplianceReport(filePath, output)
+        await appendDeckHtmlContractReport(filePath, output)
         ensureEditorOpenAfterDeckChange(filePath, extractSessionID(input))
         return
       }
@@ -763,6 +811,7 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
         const targets = patchText ? extractDeckHtmlTargetsFromPatch(patchText) : []
         for (const target of targets) {
           await appendComplianceReport(target, output)
+          await appendDeckHtmlContractReport(target, output)
           ensureEditorOpenAfterDeckChange(target, extractSessionID(input))
         }
         return
@@ -771,6 +820,7 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
       if (input.tool === "edit") {
         const filePath = extractEditFilePath(input.args)
         await appendComplianceReport(filePath, output)
+        await appendDeckHtmlContractReport(filePath, output)
         ensureEditorOpenAfterDeckChange(filePath, extractSessionID(input))
         return
       }

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

@@ -1,6 +1,5 @@
 import { tool } from "@opencode-ai/plugin"
 import {
-  applyEvidenceCandidates,
   createDeckSpec,
   DECKS_STATE_FILE,
   normalizeWorkspaceDeckState,
@@ -18,15 +17,53 @@ import {
   type SlideSpec,
 } from "../lib/decks-state"
 import { upsertSourceMaterial } from "../lib/source-materials"
+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", "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."),
@@ -42,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."),
@@ -118,6 +218,12 @@ export default tool({
       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."),
+    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 {
@@ -126,8 +232,20 @@ export default tool({
       const defaultSlug = workspaceDeckSlug(workspaceRoot)
 
       if (args.action === "init") {
+        const discovered: SourceMaterial[] = []
         for (const material of (args.sourceMaterials ?? []) as SourceMaterial[]) {
           upsertSourceMaterial(state, material, material.status ?? "discovered")
+          discovered.push(material)
+        }
+        if (discovered.length > 0) {
+          recordWorkspaceAction(state, {
+            type: "source.discovered",
+            actor: "revela-decks",
+            inputs: { count: discovered.length },
+            outputs: { paths: discovered.map((material) => material.path), statuses: discovered.map((material) => material.status ?? "discovered") },
+            summary: `Registered ${discovered.length} discovered source material${discovered.length === 1 ? "" : "s"}.`,
+            nodeIds: discovered.map((material) => `source:${material.path}`),
+          })
         }
         writeDecksState(workspaceRoot, state)
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, state }, null, 2)
@@ -176,18 +294,127 @@ 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)
+        const snapshot = latestReviewSnapshotForTarget(reviewed.state, targetId)
+        recordWorkspaceAction(reviewed.state, {
+          type: "review.performed",
+          actor: "revela-decks",
+          inputs: { activeDeck: state.activeDeck },
+          outputs: {
+            slug: reviewed.result.slug,
+            status: reviewed.result.status,
+            ready: reviewed.result.ready,
+            blockerCount: reviewed.result.blockers.length,
+            warningCount: reviewed.result.warnings.length,
+            issueCount: reviewed.result.issues.length,
+            evidenceCandidateCount: reviewed.result.evidenceCandidates?.length ?? 0,
+            snapshotId: snapshot?.id,
+            inputHash: snapshot?.inputHash,
+            targetId: snapshot?.targetId,
+          },
+          status: "success",
+          summary: `Reviewed deck readiness: ${reviewed.result.ready ? "ready" : "blocked"}.`,
+          nodeIds: [`artifact:${reviewed.state.decks[reviewed.result.slug]?.outputPath ?? reviewed.result.slug}`, ...(snapshot ? [snapshot.id] : [])],
+        })
         writeDecksState(workspaceRoot, reviewed.state)
         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" })
-        const applied = applyEvidenceCandidates(state, candidateIds, { workspaceRoot })
-        writeDecksState(workspaceRoot, applied.state)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: applied.result }, null, 2)
+        const result = applyEvidenceBindings(workspaceRoot, candidateIds)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result }, null, 2)
+      }
+
+      if (args.action === "attachResearchFindings") {
+        if (!args.findingsFile?.trim()) return JSON.stringify({ ok: false, error: "findingsFile is required for attachResearchFindings" })
+        const result = attachResearchFindings(workspaceRoot, {
+          findingsFile: args.findingsFile,
+          researchAxis: args.researchAxis,
+          status: args.researchStatus,
+        })
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result }, null, 2)
       }
 
       if (args.action === "remember") {

package/tools/pdf.ts

@@ -9,6 +9,7 @@ import { existsSync } from "fs"
 import { resolve } from "path"
 import { exportToPdf } from "../lib/pdf/export"
 import { assertExportQAPassed } from "../lib/qa/export-gate"
+import { recordRenderedArtifact, workspaceRelative } from "../lib/workspace-state/rendered-artifacts"
 
 export default tool({
   description:
@@ -35,8 +36,15 @@ export default tool({
     }
 
     try {
-      await assertExportQAPassed(filePath)
+      const root = directory || process.cwd()
+      await assertExportQAPassed(filePath, { workspaceRoot: root })
       const result = await exportToPdf(filePath)
+      recordRenderedArtifact(root, {
+        sourceHtmlPath: workspaceRelative(resolve(root), filePath),
+        outputPath: result.outputPath,
+        type: "pdf",
+        actor: "revela-pdf",
+      })
       return JSON.stringify({ ok: true, ...result }, null, 2)
     } catch (e: any) {
       return JSON.stringify({ ok: false, error: e?.message ?? String(e) })

package/tools/pptx.ts

@@ -7,7 +7,9 @@
 import { tool } from "@opencode-ai/plugin"
 import { existsSync } from "fs"
 import { resolve } from "path"
+import { assertDeckHtmlContractValid } from "../lib/deck-html/contract"
 import { exportToPptx } from "../lib/pptx/export"
+import { recordRenderedArtifact, workspaceRelative } from "../lib/workspace-state/rendered-artifacts"
 
 export default tool({
   description:
@@ -42,12 +44,20 @@ export default tool({
     const progress: string[] = []
 
     try {
+      const root = directory || process.cwd()
+      assertDeckHtmlContractValid(root, filePath)
       const result = await exportToPptx(filePath, {
         speakerNotes: normalizeSpeakerNotes(speakerNotes),
         onProgress: (event) => {
           progress.push(event.message)
         },
       })
+      recordRenderedArtifact(root, {
+        sourceHtmlPath: workspaceRelative(resolve(root), filePath),
+        outputPath: result.outputPath,
+        type: "pptx",
+        actor: "revela-pptx",
+      })
       return JSON.stringify({ ok: true, ...result, progress }, null, 2)
     } catch (e: any) {
       return JSON.stringify({ ok: false, error: e?.message ?? String(e), progress })

package/tools/research-save.ts

@@ -1,6 +1,8 @@
 import { tool } from "@opencode-ai/plugin"
 import { mkdirSync, writeFileSync } from "fs"
 import { join } from "path"
+import { hasDecksState, readDecksState, writeDecksState } from "../lib/decks-state"
+import { recordWorkspaceAction } from "../lib/workspace-state/actions"
 
 /**
  * Format today's date as YYYY-MM-DD
@@ -88,6 +90,19 @@ export default tool({
 
       writeFileSync(filePath, fileContent, "utf-8")
 
+      if (hasDecksState(workspaceDir)) {
+        const state = readDecksState(workspaceDir)
+        recordWorkspaceAction(state, {
+          type: "research.findings_saved",
+          actor: "revela-research-save",
+          inputs: { topic: topicKey, axis: fileKey, sourceCount: args.sources?.length ?? 0 },
+          outputs: { path: relPath, sources: args.sources ?? [] },
+          summary: `Saved research findings for ${topicKey}/${fileKey}.`,
+          nodeIds: [`finding:${relPath}`],
+        })
+        writeDecksState(workspaceDir, state)
+      }
+
       return JSON.stringify({ ok: true, path: relPath })
     } catch (e: any) {
       return JSON.stringify({ error: e.message || String(e) })

package/tools/workspace-scan.ts

@@ -3,6 +3,8 @@ import { readdirSync, statSync, existsSync } from "fs"
 import { join, relative, extname, resolve, sep, isAbsolute } from "path"
 import { sourceMaterialMetadata } from "../lib/source-materials"
 import type { SourceMaterial } from "../lib/decks-state"
+import { hasDecksState, readDecksState, writeDecksState } from "../lib/decks-state"
+import { recordWorkspaceAction } from "../lib/workspace-state/actions"
 
 const DOC_EXTENSIONS = new Set([
   ".pdf", ".docx", ".doc", ".xlsx", ".xls",
@@ -16,6 +18,17 @@ const EXCLUDE_DIRS = new Set([
   "designs", "domains",  // Exclude revela plugin assets
 ])
 
+const EXCLUDE_FILENAMES = new Set([
+  "AGENTS.md",
+  "DECKS.md",
+  "README.md",
+  "README.zh-CN.md",
+])
+
+function isExcludedFile(entry: string): boolean {
+  return entry.startsWith("~$") || EXCLUDE_FILENAMES.has(entry)
+}
+
 type FileEntry = {
   path: string
   type: string
@@ -82,6 +95,8 @@ function scanDir(dir: string, rootDir: string, results: FileEntry[], maxDepth: n
     if (stat.isDirectory()) {
       scanDir(fullPath, rootDir, results, maxDepth, depth + 1)
     } else if (stat.isFile()) {
+      if (isExcludedFile(entry)) continue
+
       const ext = extname(entry).toLowerCase()
       if (DOC_EXTENSIONS.has(ext)) {
         const sourceMaterial = sourceMaterialMetadata(fullPath, rootDir)
@@ -102,7 +117,7 @@ export default tool({
     "Scan the current workspace for document and data files that can be used as research input. " +
     "Returns a structured list of all found files with their type and size. " +
     "Searches for: PDF, Word (docx/doc), Excel (xlsx/xls), PowerPoint (pptx/ppt), CSV, Markdown, and text files. " +
-    "Excludes node_modules, .git, dist, and the researches/ output directory. " +
+    "Excludes node_modules, .git, dist, the researches/ output directory, project docs, and Office lock files. " +
     "Use this as the first step before reading workspace documents.",
   args: {
     path: tool.schema
@@ -145,6 +160,19 @@ export default tool({
       const results: FileEntry[] = []
       scanDir(scanRoot, workspaceDir, results, maxDepth, 0)
 
+      if (hasDecksState(workspaceDir)) {
+        const state = readDecksState(workspaceDir)
+        recordWorkspaceAction(state, {
+          type: "workspace.scanned",
+          actor: "revela-workspace-scan",
+          inputs: { path: args.path, maxDepth },
+          outputs: { found: results.length, paths: results.map((file) => file.path) },
+          summary: `Scanned workspace documents and found ${results.length} file${results.length === 1 ? "" : "s"}.`,
+          nodeIds: results.map((file) => `source:${file.sourceMaterial.path}`),
+        })
+        writeDecksState(workspaceDir, state)
+      }
+
       if (results.length === 0) {
         return JSON.stringify({
           found: 0,