@cyber-dash-tech/revela 0.17.5 → 0.17.7

package/plugins/revela/skills/revela-init/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: revela-init
+description: Initialize or refresh a Revela narrative workspace in Codex from local source materials, preserving source traceability and file-native state.
+---
+
+# Revela Init
+
+Use this skill when the user asks to start Revela, initialize the workspace, ingest local materials, or prepare a trusted narrative graph.
+
+## Product Contract
+
+- `revela-narrative/` is the editable source of truth for communication meaning when present.
+- `NarrativeStateV1` is the compiled internal interface.
+- `deck-plan/` is render planning, not canonical meaning.
+- `decks/*.html` are artifacts.
+- `DECKS.json` is compatibility/cache state, not workflow authority.
+- Do not invent quotes, source paths, URLs, page references, caveats, claim ids, evidence ids, or artifact coverage.
+
+## Workflow
+
+1. Inspect the workspace with normal Codex file tools. Stay inside the current workspace root.
+2. Prefer local source materials first: Markdown, text, CSV, PDFs, Office files, existing `researches/`, existing `revela-narrative/`, `deck-plan/`, and `decks/`.
+3. Call `revela_domain_list` and `revela_domain_read` for active domain guidance before authoring narrative meaning. Treat domain guidance as framing guidance, never as evidence.
+4. If `revela-narrative/` exists, call `revela_markdown_qa` and `revela_compile_narrative`.
+5. If the narrative vault is missing, create the initial `revela-narrative/` Markdown nodes directly with valid frontmatter and plain wikilink relations.
+6. Evidence nodes must preserve source, quote/snippet, support scope, unsupported scope, caveat, and strength before being treated as support.
+7. After writing narrative Markdown, call `revela_markdown_qa` and `revela_compile_narrative` again.
+8. End with a concise init report: local materials found, active domain, narrative graph status, open gaps, Markdown QA status, and next command/action.
+
+## Markdown Rules
+
+- Use node types: `index`, `audience`, `decision`, `thesis`, `claim`, `evidence`, `objection`, `risk`, `research-gap`.
+- Use one leading frontmatter block per file.
+- Use `## Relations` with plain node-id wikilinks, such as `- supports: [[claim-recommendation]]`.
+- Do not use typed wikilinks such as `[[claim:claim-recommendation]]`.
+- Do not duplicate stable headings like `## Evidence`, `## Caveats`, `## Relations`, `## Response`, or `## Mitigation`.

package/plugins/revela/skills/revela-make-deck/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: revela-make-deck
+description: Plan and generate Revela deck artifacts in Codex from canonical narrative state and deck-plan files.
+---
+
+# Revela Make Deck
+
+Use this skill when the user asks to make, generate, or update a Revela deck.
+
+## Source Authority
+
+- Canonical meaning comes from `revela-narrative/`.
+- Deck execution planning comes from `deck-plan/`.
+- Generated artifacts live under `decks/*.html`.
+- `DECKS.json.slides[]` is not the slide-count contract.
+
+## Workflow
+
+1. Call `revela_compile_narrative` and `revela_markdown_qa`.
+2. Report narrative and Markdown diagnostics, but treat only malformed/unsafe files and technical artifact validity as hard blockers.
+3. Call `revela_read_deck_plan`. If missing, author `deck-plan/index.md` and `deck-plan/slides/*.md` before HTML generation.
+4. For new HTML files, call `revela_create_deck_foundation`.
+5. Read active design guidance with `revela_design_list` and `revela_design_read` when choosing layouts/components. If the user asks to switch designs persistently, call `revela_design_activate`; if they ask for a one-off design, read that design by name and pass `designName` to `revela_create_deck_foundation`.
+6. Patch slides into the foundation between Revela slide markers. Preserve positive 1-based `data-slide-index` values.
+7. Generate chapter by chapter. Keep the HTML valid after each write.
+8. After every HTML write, call `revela_run_deck_qa` and repair hard errors before review or export.
+
+## QA Repair Loop
+
+- `revela_run_deck_qa` launches a browser. In sandboxed Codex sessions, this may require user-approved command escalation.
+- If QA reports `text_overflow` or `text_clipped`, reduce font size, line length, padding, or line-height before changing narrative meaning.
+- Prefer conservative cover and section-title sizing in smoke or diagnostic decks.
+- If QA reports that a standalone smoke artifact is not the active legacy deck target, treat it as a non-blocking warning when slide identity and canvas checks pass.
+
+## Deck Plan Requirements
+
+Every deck plan should include Cover, Table of Contents, and Closing. Use 3-5 chapter headings, explicit slide ranges, low-fidelity layout sketches, narrative links, visual intent, evidence trace, and caveats.

package/plugins/revela/skills/revela-research/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: revela-research
+description: Research Revela story gaps and bind evidence in Codex while preserving explicit source boundaries.
+---
+
+# Revela Research
+
+Use this skill when the user asks to research, close evidence gaps, evaluate saved findings, or bind support to current Revela claims.
+
+## Contract
+
+- Saved findings in `researches/**/*.md` are not canonical evidence until specific evidence nodes or bindings preserve source trace, quote/snippet, support scope, unsupported scope, caveat, and strength.
+- Missing evidence must stay visible as a gap.
+- Do not broaden claims to fit a source.
+- Do not write deck artifacts during research.
+
+## Workflow
+
+1. Call `revela_research_targets` to derive target order, selected target, saved findings diagnostics, and evidence gaps.
+2. For existing saved findings, call `revela_evaluate_research_findings` before deciding whether they can support a claim.
+3. Use external research only when the user allowed or requested it and the gap is publicly researchable.
+4. After external research, call `revela_research_save` with structured Markdown findings and explicit source list.
+5. Bind only when `bindingEval.status === "bindable"` by calling `revela_bind_research_findings`; do not hand-author evidence Markdown for bindable saved findings.
+6. If a finding is incomplete, report missing fields instead of inventing them.
+7. After binding or any narrative edit, call `revela_markdown_qa` and `revela_compile_narrative`.
+8. Report evidence bound, unbound findings, remaining caveats, and the next smallest story action.
+
+## Binding Criteria
+
+Bind only when the supported claim exists and the evidence includes:
+
+- source URL/path/findings file
+- quote or traceable snippet
+- support scope
+- unsupported scope
+- caveat
+- strength
+- explicit supported claim context

package/plugins/revela/skills/revela-review-deck/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: revela-review-deck
+description: Review Revela deck artifacts in Codex for technical validity, evidence trace, and narrative alignment.
+---
+
+# Revela Review Deck
+
+Use this skill when the user asks to review, inspect, diagnose, or refine a generated Revela deck.
+
+## Workflow
+
+1. Resolve the target `decks/*.html` file from the user request or unambiguous workspace state.
+2. For a plain request like `review decks/foo.html`, call `revela_review_deck_open` and let the tool open the browser by default.
+3. Use `revela_review_deck_read`, normally with `format: "markdown"`, only when the user explicitly asks to diagnose, QA, read, check, inspect source alignment, inspect evidence trace, or avoid opening a GUI.
+4. Use the read output as the deterministic diagnostics packet for artifact QA, deck-plan diagnostics, narrative/vault diagnostics, artifact coverage, and evidence trace.
+5. Pass `openBrowser: false` only for tests, no-GUI environments, or when the user explicitly asks for a link instead of opening the page.
+6. Do not call `revela_run_deck_qa`, `revela_compile_narrative`, or `revela_read_deck_plan` separately for a normal Review UI open.
+7. Call `revela_run_deck_qa` separately only for focused low-level artifact QA, after a repair, or when the user explicitly asks for QA detail.
+8. Separate technical blockers from narrative/evidence diagnostics.
+9. Pure visual/layout/export fixes may patch artifacts directly when the user asks for a change. Meaning changes must update `revela-narrative/` first.
+
+## QA Notes
+
+- `revela_review_deck_read` is read-only: it must not mutate deck HTML, `revela-narrative/`, `deck-plan/`, assets, or compatibility state.
+- `revela_review_deck_open` opens the local Review server from the MCP process and uses the Codex `codex-exec` bridge for Insight and Comment/Apply Fix. It returns URL/token/open state and basic file metadata, not aggregate diagnostics.
+- `revela_run_deck_qa` may need browser-launch permission in Codex sandboxed sessions.
+- Repair hard QA errors before treating a deck as review-ready.
+- Text clipping should usually be fixed with typography and spacing changes, not by deleting evidence or changing claim meaning.
+- A warning that a smoke/development artifact is not the active legacy deck target is non-blocking when the requested file passes hard artifact checks.
+
+## Technical Blockers
+
+Hard blockers are limited to missing or ambiguous files, invalid HTML contract, invalid slide identity, canvas/export failure, malformed Markdown/frontmatter, or unsafe writes.

package/plugins/revela/skills/revela-story/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: revela-story
+description: Inspect a Revela narrative graph in Codex without mutating artifacts or canonical meaning.
+---
+
+# Revela Story
+
+Use this skill when the user asks to view, inspect, understand, or audit the current Revela story.
+
+## Workflow
+
+1. Call `revela_story_read` first, normally with `format: "markdown"`.
+2. Use the returned deterministic map, diagnostics, narrative hash, and Markdown reading view as the authoritative Story surface.
+3. Call `revela_markdown_qa` or `revela_compile_narrative` only when you need deeper structural diagnostics than `revela_story_read` returned.
+4. If `revela_story_read.ok` is false because `revela-narrative/` is missing, report the init guidance. Do not create files from Story mode.
+5. Present audience, belief shift, decision/action, thesis, central claims, evidence, objections, risks, research gaps, artifact coverage, and diagnostics.
+6. Keep claim ids, evidence ids, source facts, quotes, URLs, numbers, and caveats exact.
+7. Do not write claims, evidence, research gaps, deck HTML, deck-plan files, assets, or artifacts from Story mode.
+
+## Output
+
+Lead with the narrative status, narrative hash, and key diagnostics. Then show the claim flow and evidence boundaries.
+
+Keep the reading evidence-first: for each claim, show source trace, support scope, unsupported scope, caveat, support strength, linked objections/risks, and remaining research gaps. Separate structural Markdown QA from evidence trust. Story is read-only; do not turn it into a mutation workflow.

package/skill/SKILL.md

@@ -64,8 +64,13 @@ handoff exactly:
 5. Use `readDeckPlan` to inspect the current `deck-plan/` projection before
    artifact review or HTML generation. Diagnostics are advisory unless they are
    artifact validity errors handled by QA.
-6. Fetch the required design layouts/components with `revela-designs read`.
-7. Write HTML when the user proceeds and the deck contract can be satisfied.
+6. For a new deck HTML file, call `revela-deck-foundation` to create the
+   active-design foundation shell. The helper is file-native and must not create
+   narrative slide content, choose layouts/components, or read/write `DECKS.json`.
+7. Fetch the required design rules, layouts, and components with
+   `revela-designs read`.
+8. Patch slides between the foundation shell's `revela-slides` markers when the
+   user proceeds and the deck contract can be satisfied.
 
 Before any HTML generation, call `revela-decks` action `readDeckPlan` and follow
 the current `deck-plan/`: Source Authority, deck parameters, Chapter Writing
@@ -164,7 +169,8 @@ one broad `write`, `edit`, or `apply_patch` call.
 
 For decks with 5 or more slides:
 
-- First create a stable HTML shell plus structural slides and the first chapter.
+- First call `revela-deck-foundation` for new files, then patch structural
+  slides and the first chapter between the `revela-slides` markers.
 - Then fill or revise exactly one chapter range at a time.
 - Do not mix multiple central-claim chapters in the same write.
 - Chapter divider or chapter TOC slides are allowed as structural wayfinding and
@@ -193,14 +199,17 @@ If a write produces QA hard errors, fix them before continuing.
 Before writing or materially changing HTML:
 
 1. Read the deck-plan projection's layout and component names.
-2. Call `revela-designs` with `action: "read"` and `section: "rules"` to fetch
+2. For a new deck HTML file, call `revela-deck-foundation` before adding slide
+   content. Use `mode: "repair"` only for explicit foundation repair or QA
+   foundation contract fixes, not normal Review Comment edits.
+3. Call `revela-designs` with `action: "read"` and `section: "rules"` to fetch
    the active design's current composition and usage rules.
-3. Call `revela-designs` with `action: "read"` and `layout` set to all required
+4. Call `revela-designs` with `action: "read"` and `layout` set to all required
    layout names, comma-separated.
-4. Call `revela-designs` with `action: "read"` and `component` set to all
+5. Call `revela-designs` with `action: "read"` and `component` set to all
    required component names, comma-separated.
-5. Fetch `section: "chart-rules"` before using ECharts.
-6. Do not update legacy `requiredInputs`; design fetching is an execution step,
+6. Fetch `section: "chart-rules"` before using ECharts.
+7. Do not update legacy `requiredInputs`; design fetching is an execution step,
    not a workflow permission gate.
 
 Never generate HTML from memory or prior knowledge of a design. Copy the fetched

package/tools/deck-foundation.ts

@@ -0,0 +1,48 @@
+import { tool } from "@opencode-ai/plugin"
+import { createDeckFoundation } from "../lib/deck-html/foundation"
+
+export default tool({
+  description:
+    "Create or repair a file-native Revela deck HTML foundation shell from the active design. " +
+    "Writes a deterministic empty deck shell with doctype, html/head/body, active design foundation CSS, complete SlidePresentation JavaScript, and stable slide insertion markers. " +
+    "It does not create narrative slide content, choose layouts/components, or read/write DECKS.json.",
+  args: {
+    outputPath: tool.schema
+      .string()
+      .describe("Workspace-relative HTML output path, usually decks/{name}.html."),
+    title: tool.schema
+      .string()
+      .describe("Presentation title for the HTML <title> tag only; this does not create a cover slide."),
+    language: tool.schema
+      .string()
+      .describe("HTML language tag, e.g. en or zh-CN."),
+    designName: tool.schema
+      .string()
+      .optional()
+      .describe("Optional design name. Defaults to the active design."),
+    mode: tool.schema
+      .enum(["create", "repair"])
+      .optional()
+      .describe("create protects existing files unless overwrite=true; repair may replace an existing foundation shell."),
+    overwrite: tool.schema
+      .boolean()
+      .optional()
+      .describe("Whether create mode may overwrite an existing HTML file. Defaults to false."),
+  },
+  async execute(args, { directory }) {
+    try {
+      const result = createDeckFoundation({
+        workspaceRoot: directory || process.cwd(),
+        outputPath: args.outputPath,
+        title: args.title,
+        language: args.language,
+        designName: args.designName,
+        mode: args.mode,
+        overwrite: args.overwrite ?? false,
+      })
+      return JSON.stringify(result, null, 2)
+    } catch (e: any) {
+      return JSON.stringify({ error: e?.message || String(e) })
+    }
+  },
+})

package/tools/decks.ts

@@ -34,30 +34,12 @@ import {
 import { compileDeckPlanFromNarrative } from "../lib/narrative-state/render-plan"
 import { DECK_PLAN_ARTIFACT_PATH, readDeckPlanArtifact } from "../lib/narrative-state/deck-plan-artifact"
 import { backfillSlideClaimRefsFromCoverage } from "../lib/narrative-state/coverage"
-import { closeResearchGapInState, deriveResearchGapsFromReadiness, deriveResearchTargets, updateResearchGapInState, upsertResearchGapsInState } from "../lib/narrative-state/research-gaps"
-import { evaluateResearchFindingsBinding } from "../lib/narrative-state/research-binding-eval"
-import { computeNarrativeHash, stableEvidenceId } from "../lib/narrative-state/hash"
+import { closeResearchGapInState, deriveResearchGapsFromReadiness, updateResearchGapInState, upsertResearchGapsInState } from "../lib/narrative-state/research-gaps"
+import { computeNarrativeHash } from "../lib/narrative-state/hash"
 import { normalizeNarrativeState } from "../lib/narrative-state/normalize"
 import { buildNarrativeVaultInventory, compileNarrativeVault, exportNarrativeStateToVault, formatVaultDiagnosticReport, getNarrativeVaultMigrationHint, hasNarrativeVault, initNarrativeVault, narrativeVaultAuthoringContract, narrativeVaultTimestampMs, removeVaultRelation, runNarrativeMarkdownQa, updateVaultCoreNodes, updateVaultResearchGapNode, upsertVaultClaimNode, upsertVaultEvidenceNode, upsertVaultObjectionNode, upsertVaultRelation, upsertVaultRiskNode, VAULT_MIGRATION_PRESERVED_IN_DECKS_JSON } from "../lib/narrative-vault"
 import { compileCacheMirrorNarrativeVault } from "../lib/narrative-vault/compile-mirror"
-
-function missingBindableEvidenceFields(input: Record<string, unknown>): string[] {
-  const missing: string[] = []
-  for (const key of ["id", "claimId", "source", "quote", "supportScope", "unsupportedScope", "caveat", "strength"] as const) {
-    if (!String(input[key] ?? "").trim()) missing.push(key)
-  }
-  if (!String(input.sourcePath ?? "").trim() && !String(input.url ?? "").trim() && !String(input.findingsFile ?? "").trim()) missing.push("sourcePath|url|findingsFile")
-  return missing
-}
-
-function exactResearchGapForBinding(state: DecksState, findingsFile: string, claimId: string) {
-  const gaps = state.narrative?.researchGaps ?? []
-  const exact = gaps.filter((gap) => gap.targetType === "claim" && gap.targetId === claimId && gap.findingsFile === findingsFile)
-  if (exact.length === 1) return exact[0]
-  if (exact.length > 1) return undefined
-  const byClaim = gaps.filter((gap) => gap.targetType === "claim" && gap.targetId === claimId && !gap.findingsFile)
-  return byClaim.length === 1 ? byClaim[0] : undefined
-}
+import { bindResearchFindings as bindResearchFindingsRuntime, evaluateResearchFindings as evaluateResearchFindingsRuntime, researchTargets as researchTargetsRuntime } from "../lib/runtime/research"
 
 function forbiddenVaultCompatibilityAction(action: string, replacement: string): string {
   return `${action} is a JSON-era compatibility action and is blocked in vault workspaces. Use ${replacement}, or patch the existing Markdown node only for a small read-before-edit repair.`
@@ -469,54 +451,11 @@ export default tool({
       }
 
       if (args.action === "bindResearchFindings") {
-        if (!hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: "bindResearchFindings requires revela-narrative/ to exist. Use initNarrativeVault first, then evaluateResearchFindings." })
-        if (!args.findingsFile?.trim()) return JSON.stringify({ ok: false, error: "findingsFile is required for bindResearchFindings" })
-        const bindingEval = evaluateResearchFindingsBinding(state, workspaceRoot, args.findingsFile)
-        if (bindingEval.status !== "bindable" || !bindingEval.claimId || !bindingEval.recommendedEvidenceDraft) {
-          return JSON.stringify({ ok: false, skipped: true, reason: "findings are not safely bindable", bindingEval }, null, 2)
-        }
-        const draft = bindingEval.recommendedEvidenceDraft
-        const evidence = {
-          id: args.evidence?.id?.trim() || stableEvidenceId(bindingEval.claimId, `${bindingEval.findingsFile}:${draft.quote ?? ""}`),
-          claimId: bindingEval.claimId,
-          source: draft.source,
-          sourcePath: draft.sourcePath,
-          findingsFile: draft.findingsFile ?? bindingEval.findingsFile,
-          quote: draft.quote,
-          location: draft.location,
-          url: draft.url,
-          caveat: draft.caveat,
-          supportScope: draft.supportScope,
-          unsupportedScope: draft.unsupportedScope,
-          strength: draft.strength,
-        }
-        const missing = missingBindableEvidenceFields(evidence)
-        if (missing.length > 0) return JSON.stringify({ ok: false, skipped: true, reason: "recommended evidence draft is incomplete", missingFields: missing, bindingEval }, null, 2)
-
-        const mutation = upsertVaultEvidenceNode(workspaceRoot, evidence as any)
-        if (!mutation.ok) return JSON.stringify({ ok: false, mutation, bindingEval }, null, 2)
-        const gap = exactResearchGapForBinding(state, bindingEval.findingsFile, bindingEval.claimId)
-        const gapMutation = gap
-          ? updateVaultResearchGapNode(workspaceRoot, {
-            id: gap.id,
-            status: "evidence_bound",
-            findingsFile: bindingEval.findingsFile,
-            evidenceBindingIds: [...new Set([...(gap.evidenceBindingIds ?? []), evidence.id])],
-            notes: gap.notes,
-          })
-          : undefined
-        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
-        return JSON.stringify({
-          ok: compiled.result.ok,
-          path: mutation.file,
-          bindingEval,
-          mutation,
-          gapMutation: gapMutation ?? { ok: true, skipped: true, reason: "no exact single research gap matched this findings file and claim" },
-          evidence,
-          diagnostics: compiled.result.diagnostics,
-          diagnosticReport: compiled.diagnosticReport,
-          narrative: compiled.result.narrative,
-        }, null, 2)
+        return JSON.stringify(bindResearchFindingsRuntime({
+          workspaceRoot,
+          findingsFile: args.findingsFile ?? "",
+          evidenceId: args.evidence?.id,
+        }), null, 2)
       }
 
       if (args.action === "updateVaultResearchGap") {
@@ -799,18 +738,11 @@ export default tool({
       }
 
       if (args.action === "deriveResearchTargets") {
-        const result = deriveResearchTargets(state, { workspaceRoot })
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result }, null, 2)
+        return JSON.stringify(researchTargetsRuntime({ workspaceRoot }), null, 2)
       }
 
       if (args.action === "evaluateResearchFindings") {
-        if (!args.findingsFile?.trim()) return JSON.stringify({ ok: false, error: "findingsFile is required for evaluateResearchFindings" })
-        const bindingEval = evaluateResearchFindingsBinding(state, workspaceRoot, args.findingsFile)
-        const targets = deriveResearchTargets(state, { workspaceRoot })
-        const vaultDiagnostics = hasNarrativeVault(workspaceRoot)
-          ? formatVaultDiagnosticReport(compileNarrativeVault(workspaceRoot, { fallbackApprovals: state.narrative?.approvals ?? [] }).diagnostics)
-          : undefined
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: { bindingEval, selected: targets.selected, vaultDiagnostics } }, null, 2)
+        return JSON.stringify(evaluateResearchFindingsRuntime({ workspaceRoot, findingsFile: args.findingsFile ?? "" }), null, 2)
       }
 
       if (args.action === "upsertResearchGaps") {

package/tools/research-save.ts

@@ -1,46 +1,5 @@
 import { tool } from "@opencode-ai/plugin"
-import { mkdirSync, writeFileSync } from "fs"
-import { join } from "path"
-import { hasDecksState, readDecksState, writeDecksState } from "../lib/decks-state"
-import { evaluateResearchFindingsBinding } from "../lib/narrative-state/research-binding-eval"
-import { recordWorkspaceAction } from "../lib/workspace-state/actions"
-
-/**
- * Format today's date as YYYY-MM-DD
- */
-function today(): string {
-  return new Date().toISOString().slice(0, 10)
-}
-
-/**
- * Sanitize a key: lowercase, alphanumeric + hyphens only.
- */
-function keyify(s: string): string {
-  return s
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-}
-
-/**
- * Build YAML frontmatter string.
- */
-function buildFrontmatter(topic: string, axis: string, sources: string[]): string {
-  const lines = [
-    "---",
-    `topic: ${topic}`,
-    `axis: ${axis}`,
-    `date: ${today()}`,
-  ]
-  if (sources.length > 0) {
-    lines.push("sources:")
-    for (const s of sources) {
-      lines.push(`  - "${s.replace(/"/g, '\\"')}"`)
-    }
-  }
-  lines.push("---")
-  return lines.join("\n")
-}
+import { researchSave } from "../lib/runtime/research"
 
 export default tool({
   description:
@@ -77,36 +36,13 @@ export default tool({
   },
   async execute(args, context) {
     try {
-      const topicKey = keyify(args.topic || "research")
-      const fileKey = keyify(args.filename || "findings")
-      const workspaceDir = context.directory ?? process.cwd()
-      const topicDir = join(workspaceDir, "researches", topicKey)
-
-      mkdirSync(topicDir, { recursive: true })
-
-      const frontmatter = buildFrontmatter(args.topic, fileKey, args.sources ?? [])
-      const fileContent = `${frontmatter}\n\n${args.content ?? ""}\n`
-      const filePath = join(topicDir, `${fileKey}.md`)
-      const relPath = `researches/${topicKey}/${fileKey}.md`
-
-      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}`],
-        })
-        const bindingEval = evaluateResearchFindingsBinding(state, workspaceDir, relPath)
-        writeDecksState(workspaceDir, state)
-        return JSON.stringify({ ok: true, path: relPath, bindingEval })
-      }
-
-      return JSON.stringify({ ok: true, path: relPath })
+      return JSON.stringify(researchSave({
+        topic: args.topic,
+        filename: args.filename,
+        content: args.content,
+        sources: args.sources,
+        workspaceRoot: context.directory ?? process.cwd(),
+      }))
     } catch (e: any) {
       return JSON.stringify({ error: e.message || String(e) })
     }