@cyber-dash-tech/revela 0.9.0 → 0.11.0

package/lib/workspace-state/research-attachments.ts

@@ -0,0 +1,130 @@
+import { existsSync } from "fs"
+import { basename, resolve, sep } from "path"
+import {
+  readDecksState,
+  writeDecksState,
+  type DecksState,
+  type ResearchAxis,
+} from "../decks-state"
+import { recordWorkspaceAction } from "./actions"
+
+export interface AttachResearchFindingsInput {
+  findingsFile: string
+  researchAxis?: string
+  status?: "done" | "read"
+}
+
+export interface AttachResearchFindingsResult {
+  attached: boolean
+  skipped: boolean
+  reason?: string
+  slug?: string
+  axis?: string
+  findingsFile?: string
+  status?: ResearchAxis["status"]
+}
+
+export function attachResearchFindings(workspaceRoot: string, input: AttachResearchFindingsInput): AttachResearchFindingsResult {
+  const state = readDecksState(workspaceRoot)
+  const result = attachResearchFindingsToState(state, workspaceRoot, input)
+  writeDecksState(workspaceRoot, state)
+  return result
+}
+
+export function attachResearchFindingsToState(state: DecksState, workspaceRoot: string, input: AttachResearchFindingsInput): AttachResearchFindingsResult {
+  const normalizedFile = normalizeResearchFindingsPath(input.findingsFile)
+  if (!normalizedFile) {
+    return recordSkipped(state, input, "findingsFile must be a workspace-relative researches/*.md path")
+  }
+
+  const absoluteFile = safeWorkspacePath(workspaceRoot, normalizedFile)
+  if (!absoluteFile || !existsSync(absoluteFile)) {
+    return recordSkipped(state, { ...input, findingsFile: normalizedFile }, "findingsFile does not exist inside the workspace")
+  }
+
+  const slug = state.activeDeck ?? singleDeckKey(state)
+  const deck = slug ? state.decks[slug] : undefined
+  if (!slug || !deck) return recordSkipped(state, { ...input, findingsFile: normalizedFile }, "no active deck is available")
+
+  const matches = matchingAxes(deck.researchPlan ?? [], input.researchAxis, normalizedFile)
+  if (matches.length === 0) return recordSkipped(state, { ...input, findingsFile: normalizedFile }, "no matching researchPlan axis found")
+  if (matches.length > 1) return recordSkipped(state, { ...input, findingsFile: normalizedFile }, "researchPlan axis match is ambiguous")
+
+  const index = matches[0]!
+  const existing = deck.researchPlan[index]!
+  const nextStatus = input.status ?? existing.status
+  deck.researchPlan[index] = {
+    ...existing,
+    status: nextStatus,
+    findingsFile: normalizedFile,
+  }
+
+  recordWorkspaceAction(state, {
+    type: "research.findings_attached",
+    actor: "revela-decks",
+    inputs: { activeDeck: slug, axis: existing.axis, findingsFile: normalizedFile, requestedStatus: input.status },
+    outputs: { slug, axis: existing.axis, findingsFile: normalizedFile, status: nextStatus },
+    summary: `Attached research findings ${normalizedFile} to axis ${existing.axis}.`,
+    nodeIds: [`finding:${normalizedFile}`],
+  })
+
+  return {
+    attached: true,
+    skipped: false,
+    slug,
+    axis: existing.axis,
+    findingsFile: normalizedFile,
+    status: nextStatus,
+  }
+}
+
+function matchingAxes(researchPlan: ResearchAxis[], researchAxis: string | undefined, findingsFile: string): number[] {
+  if (researchAxis?.trim()) {
+    const requested = normalizeKey(researchAxis)
+    return researchPlan.flatMap((axis, index) => normalizeKey(axis.axis) === requested ? [index] : [])
+  }
+
+  const fileKey = normalizeKey(basename(findingsFile, ".md"))
+  return researchPlan.flatMap((axis, index) => normalizeKey(axis.axis) === fileKey ? [index] : [])
+}
+
+function recordSkipped(state: DecksState, input: AttachResearchFindingsInput, reason: string): AttachResearchFindingsResult {
+  const normalizedFile = normalizeResearchFindingsPath(input.findingsFile) ?? input.findingsFile
+  recordWorkspaceAction(state, {
+    type: "research.findings_attached",
+    actor: "revela-decks",
+    inputs: { axis: input.researchAxis, findingsFile: normalizedFile, requestedStatus: input.status },
+    outputs: { reason },
+    status: "skipped",
+    summary: `Skipped research findings attachment: ${reason}.`,
+    nodeIds: normalizedFile ? [`finding:${normalizedFile}`] : [],
+  })
+  return { attached: false, skipped: true, reason }
+}
+
+function normalizeResearchFindingsPath(filePath: string | undefined): string | undefined {
+  const normalized = normalizePath(filePath ?? "").replace(/^\.\//, "")
+  if (!normalized || normalized.startsWith("../") || normalized.startsWith("/")) return undefined
+  if (!normalized.startsWith("researches/") || !normalized.endsWith(".md")) return undefined
+  return normalized
+}
+
+function safeWorkspacePath(workspaceRoot: string, relativePath: string): string | undefined {
+  const root = resolve(workspaceRoot)
+  const target = resolve(root, relativePath)
+  if (target !== root && !target.startsWith(root + sep)) return undefined
+  return target
+}
+
+function singleDeckKey(state: DecksState): string | undefined {
+  const keys = Object.keys(state.decks)
+  return keys.length === 1 ? keys[0] : undefined
+}
+
+function normalizeKey(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, "-").replace(/^-+|-+$/g, "")
+}
+
+function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, "/")
+}

package/lib/workspace-state/review-snapshots.ts

@@ -0,0 +1,127 @@
+import { createHash } from "crypto"
+import type { DeckSpec, DecksState, DeckStateReadinessResult } from "../decks-state"
+import { projectWorkspaceGraph } from "./graph"
+import { activeHtmlDeckRenderTarget, ensureActiveHtmlDeckRenderTarget } from "./render-targets"
+import type { ReviewSnapshot } from "./types"
+
+export const MAX_REVIEW_SNAPSHOTS = 50
+
+export interface ReviewSnapshotInput {
+  slug: string
+  result: DeckStateReadinessResult
+  reviewedAt?: string
+}
+
+export function currentReviewInputHash(state: DecksState, slug?: string): string {
+  return stableHash(stableStringify(reviewInputProjection(state, slug)))
+}
+
+export function activeReviewTargetId(state: DecksState): string | undefined {
+  return activeHtmlDeckRenderTarget(state)?.id ?? ensureActiveHtmlDeckRenderTarget(state)?.id
+}
+
+export function createReviewSnapshot(state: DecksState, input: ReviewSnapshotInput): ReviewSnapshot {
+  const reviewedAt = input.reviewedAt ?? new Date().toISOString()
+  const targetId = activeReviewTargetId(state)
+  const inputHash = currentReviewInputHash(state, input.slug)
+  return {
+    id: reviewSnapshotId(targetId, inputHash, reviewedAt),
+    ...(targetId ? { targetId } : {}),
+    inputHash,
+    status: input.result.status ?? (input.result.ready ? "ready" : "blocked"),
+    blockers: input.result.blockers,
+    warnings: input.result.warnings,
+    issues: input.result.issues,
+    ...(input.result.evidenceCandidates ? { evidenceCandidates: input.result.evidenceCandidates } : {}),
+    reviewedAt,
+  }
+}
+
+export function appendReviewSnapshot(state: DecksState, snapshot: ReviewSnapshot): DecksState {
+  const next = (state.reviews ?? []).filter((item) => item.id !== snapshot.id)
+  next.push(snapshot)
+  state.reviews = next
+    .sort((a, b) => a.reviewedAt.localeCompare(b.reviewedAt))
+    .slice(-MAX_REVIEW_SNAPSHOTS)
+  return state
+}
+
+export function latestReviewSnapshotForTarget(state: DecksState, targetId?: string): ReviewSnapshot | undefined {
+  const reviews = state.reviews ?? []
+  const candidates = targetId ? reviews.filter((item) => item.targetId === targetId) : reviews
+  return candidates.reduce<ReviewSnapshot | undefined>((latest, item) => {
+    if (!latest) return item
+    return item.reviewedAt.localeCompare(latest.reviewedAt) >= 0 ? item : latest
+  }, undefined)
+}
+
+export function isReviewSnapshotCurrent(state: DecksState, snapshot: ReviewSnapshot, slug?: string): boolean {
+  return snapshot.inputHash === currentReviewInputHash(state, slug)
+}
+
+function reviewInputProjection(state: DecksState, slug?: string): unknown {
+  const key = slug || state.activeDeck || singleDeckKey(state.decks)
+  const deck = key ? state.decks[key] : undefined
+  const stableState = cloneForGraphProjection(state, key)
+  return {
+    version: state.version,
+    activeDeck: key,
+    workspace: {
+      brief: state.workspace.brief,
+      sourceMaterials: state.workspace.sourceMaterials,
+      openQuestions: state.workspace.openQuestions,
+    },
+    deck: deck ? stableDeckProjection(deck) : undefined,
+    renderTarget: activeHtmlDeckRenderTarget(state) ?? ensureActiveHtmlDeckRenderTarget(state),
+    graph: deck ? projectWorkspaceGraph(stableState, { slug: key }) : undefined,
+  }
+}
+
+function stableDeckProjection(deck: DeckSpec): unknown {
+  return {
+    slug: deck.slug,
+    goal: deck.goal,
+    audience: deck.audience,
+    language: deck.language,
+    outputPath: deck.outputPath,
+    narrativeBrief: deck.narrativeBrief,
+    theme: deck.theme,
+    requiredInputs: deck.requiredInputs,
+    researchPlan: deck.researchPlan,
+    slides: deck.slides,
+    assets: deck.assets,
+  }
+}
+
+function cloneForGraphProjection(state: DecksState, slug?: string): DecksState {
+  const clone = structuredClone(state) as DecksState
+  const key = slug || clone.activeDeck || singleDeckKey(clone.decks)
+  const deck = key ? clone.decks[key] : undefined
+  if (deck) {
+    deck.status = "planning"
+    deck.writeReadiness = { status: "blocked", blockers: [] }
+  }
+  clone.actions = []
+  clone.reviews = []
+  return clone
+}
+
+function reviewSnapshotId(targetId: string | undefined, inputHash: string, reviewedAt: string): string {
+  return `review:${targetId ?? "workspace"}:${inputHash.slice(0, 12)}:${stableHash(reviewedAt).slice(0, 8)}`
+}
+
+function stableHash(value: string): string {
+  return createHash("sha1").update(value).digest("hex")
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`
+  const object = value as Record<string, unknown>
+  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`
+}
+
+function singleDeckKey(decks: Record<string, DeckSpec>): string | undefined {
+  const keys = Object.keys(decks)
+  return keys.length === 1 ? keys[0] : undefined
+}

package/lib/workspace-state/types.ts

@@ -0,0 +1,119 @@
+import type { DecksState } from "../decks-state"
+
+export const WORKSPACE_STATE_FILE = "DECKS.json"
+
+export type WorkspaceStateVersion = 1 | 2
+
+export interface WorkspaceStateRepositoryOptions<TState> {
+  fileName?: string
+  normalize?: (state: TState) => TState
+}
+
+export interface WorkspaceStateV2 {
+  version: 2
+  workspace: WorkspaceMeta
+  graph: WorkspaceGraph
+  actions: WorkspaceAction[]
+  renderTargets: RenderTarget[]
+  reviews: ReviewSnapshot[]
+  compatibility?: DecksStateV1Projection
+}
+
+export interface WorkspaceMeta {
+  brief?: string
+  preferences?: {
+    user: string[]
+    workflow: string[]
+  }
+  openQuestions?: string[]
+}
+
+export interface WorkspaceGraph {
+  nodes: Record<string, GraphNode>
+  edges: GraphEdge[]
+}
+
+export interface GraphNode {
+  id: string
+  type: GraphNodeType
+  label?: string
+  data?: Record<string, unknown>
+}
+
+export type GraphNodeType =
+  | "source"
+  | "extraction"
+  | "finding"
+  | "claim"
+  | "narrativeIntent"
+  | "objection"
+  | "risk"
+  | "slide"
+  | "artifact"
+
+export interface GraphEdge {
+  id: string
+  type: GraphEdgeType
+  from: string
+  to: string
+  data?: Record<string, unknown>
+}
+
+export type GraphEdgeType =
+  | "contains"
+  | "extracted_as"
+  | "produced"
+  | "supports"
+  | "appears_in"
+  | "challenges"
+  | "constrained_by"
+  | "renders_from"
+  | "derived_from"
+
+export interface WorkspaceAction {
+  id: string
+  type: WorkspaceActionType
+  timestamp: string
+  actor?: string
+  inputs?: Record<string, unknown>
+  outputs?: Record<string, unknown>
+  status: "success" | "failed" | "skipped"
+  summary?: string
+  nodeIds?: string[]
+}
+
+export type WorkspaceActionType =
+  | "workspace.scanned"
+  | "source.discovered"
+  | "source.extracted"
+  | "research.findings_saved"
+  | "research.findings_attached"
+  | "evidence.candidate_generated"
+  | "evidence.binding_applied"
+  | "review.performed"
+  | "artifact.rendered"
+
+export interface RenderTarget {
+  id: string
+  type: "html_deck" | "pdf" | "pptx" | "brief" | "appendix" | "qa_view" | "interactive_page"
+  outputPath?: string
+  sourceNodeIds: string[]
+  artifactVersion?: string
+  contractStatus?: "unknown" | "valid" | "invalid" | "stale"
+  data?: Record<string, unknown>
+}
+
+export interface ReviewSnapshot {
+  id: string
+  targetId?: string
+  inputHash: string
+  status: "blocked" | "ready" | "written"
+  blockers: string[]
+  warnings: string[]
+  issues: unknown[]
+  evidenceCandidates?: unknown[]
+  reviewedAt: string
+}
+
+export type DecksStateV1Projection = DecksState
+export type WorkspaceState = DecksState | WorkspaceStateV2

package/package.json

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

package/plugin.ts

@@ -46,6 +46,9 @@ 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 { 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"
@@ -80,6 +83,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"
@@ -173,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 ?? ""
   }
@@ -332,6 +358,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/`.")
@@ -340,6 +374,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__")
@@ -403,7 +445,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") {
@@ -438,6 +480,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,
@@ -720,6 +764,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
       }
@@ -741,6 +786,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
@@ -749,6 +795,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/SKILL.md

@@ -261,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"`.
 
-Example: `<section class="slide" slide-qa="true" data-index="0">`
+`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-slide-index="1">`
 
 The export QA path treats this as deck metadata. It is consumed when PDF/PPTX
 export runs preflight checks.

package/tools/decks.ts

@@ -17,6 +17,10 @@ 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"
 
 export default tool({
   description:
@@ -25,7 +29,7 @@ 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", "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."),
@@ -116,6 +120,10 @@ 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."),
+    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."),
   },
   async execute(args, context) {
     try {
@@ -124,8 +132,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)
@@ -175,11 +195,50 @@ export default tool({
       }
 
       if (args.action === "review") {
-        const reviewed = reviewDeckState(state)
+        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 === "applyEvidenceCandidates") {
+        const candidateIds = args.candidateIds ?? []
+        if (candidateIds.length === 0) return JSON.stringify({ ok: false, error: "candidateIds are required for applyEvidenceCandidates" })
+        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") {
         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) })
+    }
+  },
+})