@cyber-dash-tech/revela 0.13.0 → 0.15.0

package/plugin.ts

@@ -23,6 +23,7 @@ import { seedBuiltinDomains } from "./lib/domain/domains"
 import { buildPrompt } from "./lib/prompt-builder"
 import { ACTIVE_PROMPT_FILE } from "./lib/config"
 import { ctx } from "./lib/ctx"
+import { formatCommandIntentSystemBlock, setPendingCommandIntent, takePendingCommandIntent } from "./lib/command-intent"
 import { preRead } from "./lib/read-hooks"
 import { postRead } from "./lib/read-hooks"
 import { extractPdfText } from "./lib/read-hooks/extractors/pdf"
@@ -59,6 +60,7 @@ import {
   buildDesignsEditPrompt,
 } from "./lib/commands/designs-new"
 import { buildInitPrompt } from "./lib/commands/init"
+import { buildResearchPrompt } from "./lib/commands/research"
 import { handleBrief, parseBriefArgs } from "./lib/commands/brief"
 import { buildNarrativeViewPrompt, handleNarrative, parseNarrativeArgs } from "./lib/commands/narrative"
 import { parseRememberArgs, buildRememberPrompt } from "./lib/commands/remember"
@@ -206,6 +208,27 @@ const server: Plugin = (async (pluginCtx) => {
     return input?.sessionID ?? input?.session?.id ?? input?.context?.sessionID ?? ""
   }
 
+  function queueWorkflowCommand(input: {
+    sessionID: string
+    name: string
+    mode: "narrative" | "deck-render"
+    visibleText: string
+    hiddenPrompt: string
+    output: any
+  }): void {
+    ctx.enabled = true
+    buildPrompt({ mode: input.mode })
+    setPendingCommandIntent({
+      sessionID: input.sessionID,
+      name: input.name,
+      mode: input.mode,
+      visibleText: input.visibleText,
+      hiddenPrompt: input.hiddenPrompt,
+    })
+    input.output.parts.length = 0
+    input.output.parts.push({ type: "text", text: input.visibleText } as any)
+  }
+
   function ensureEditorOpenAfterDeckChange(filePath: string, sessionID: string): void {
     if (!isDeckHtmlPath(filePath) || !sessionID) return
 
@@ -239,7 +262,7 @@ const server: Plugin = (async (pluginCtx) => {
       opencodeConfig.command ??= {}
       opencodeConfig.command["revela"] = {
         template: "",
-        description: "Revela — AI slide deck generator (enable/disable, manage designs & domains)",
+        description: "Revela — narrative artifact workspace (init, research, story, make, refine, design)",
       }
 
       // Register the research subagent.
@@ -329,12 +352,14 @@ 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",
-          text: buildInitPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: "init",
+          mode: "narrative",
+          visibleText: "Initialize Revela workspace.",
+          hiddenPrompt: buildInitPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+          output,
+        })
         return
       }
       if (sub === "remember") {
@@ -343,28 +368,73 @@ 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",
-          text: buildRememberPrompt({ memory: parsed.memory, exists: hasDecksState(workspaceRoot) }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: "remember",
+          mode: "narrative",
+          visibleText: "Remember Revela workspace preference.",
+          hiddenPrompt: buildRememberPrompt({ memory: parsed.memory, exists: hasDecksState(workspaceRoot) }),
+          output,
+        })
+        return
+      }
+      if (sub === "research") {
+        if (param) {
+          await send("`/revela research` does not accept arguments yet. Add the research question in normal chat, or run it to work from open story gaps.")
+          throw new Error("__REVELA_RESEARCH_USAGE_HANDLED__")
+        }
+        queueWorkflowCommand({
+          sessionID,
+          name: "research",
+          mode: "narrative",
+          visibleText: "Research Revela story gaps.",
+          hiddenPrompt: buildResearchPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+          output,
+        })
         return
       }
       if (sub === "review") {
         if (param) {
-          await send("`/revela review` no longer accepts a deck name. It reviews the current workspace narrative. Use `/revela deck --review` for deck/artifact readiness.")
+          await send("`/revela review` no longer accepts a deck name. It is a compatibility alias for `/revela story`. Use `/revela make 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",
-          text: buildReviewPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: "review",
+          mode: "narrative",
+          visibleText: "Review Revela story readiness.",
+          hiddenPrompt: buildReviewPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+          output,
+        })
+        return
+      }
+      if (sub === "story") {
+        if (param) {
+          await send("`/revela story` does not accept arguments yet. It opens the current workspace story UI. Use `/revela review` for a readiness report.")
+          throw new Error("__REVELA_STORY_USAGE_HANDLED__")
+        }
+        queueWorkflowCommand({
+          sessionID,
+          name: "story",
+          mode: "narrative",
+          visibleText: "Open Revela story workspace.",
+          hiddenPrompt: buildNarrativeViewPrompt({ workspaceRoot, language: "en" }),
+          output,
+        })
         return
       }
       if (sub === "narrative") {
+        if (!param) {
+          queueWorkflowCommand({
+            sessionID,
+            name: "narrative",
+            mode: "narrative",
+            visibleText: "Open Revela story workspace.",
+            hiddenPrompt: buildNarrativeViewPrompt({ workspaceRoot, language: "en" }),
+            output,
+          })
+          return
+        }
         const parsed = parseNarrativeArgs(param)
         if (!parsed.ok) {
           await send(parsed.error)
@@ -374,12 +444,14 @@ const server: Plugin = (async (pluginCtx) => {
           await handleNarrative({ workspaceRoot, openBrowser: true, language: parsed.args.language }, send)
           throw new Error("__REVELA_NARRATIVE_HANDLED__")
         }
-        buildPrompt({ mode: "narrative" })
-        output.parts.length = 0
-        output.parts.push({
-          type: "text",
-          text: buildNarrativeViewPrompt({ workspaceRoot, language: parsed.args.language }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: "narrative view",
+          mode: "narrative",
+          visibleText: "Open read-only Revela narrative map.",
+          hiddenPrompt: buildNarrativeViewPrompt({ workspaceRoot, language: parsed.args.language }),
+          output,
+        })
         return
       }
       if (sub === "brief") {
@@ -391,26 +463,62 @@ const server: Plugin = (async (pluginCtx) => {
         await handleBrief({ workspaceRoot, outputPath: parsed.args.outputPath }, send)
         throw new Error("__REVELA_BRIEF_HANDLED__")
       }
+      if (sub === "make") {
+        const target = args[1]?.toLowerCase() ?? ""
+        const makeParam = args.slice(2).join(" ")
+        if (target === "deck") {
+          if (makeParam && makeParam !== "--review") {
+            await send("Usage: `/revela make deck` starts approved-narrative deck handoff; `/revela make deck --review` reviews deck/artifact readiness.")
+            throw new Error("__REVELA_MAKE_DECK_USAGE_HANDLED__")
+          }
+          queueWorkflowCommand({
+            sessionID,
+            name: makeParam ? "make deck --review" : "make deck",
+            mode: "deck-render",
+            visibleText: makeParam ? "Review Revela deck artifact readiness." : "Make Revela deck from approved story.",
+            hiddenPrompt: makeParam
+              ? buildDeckReviewPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot })
+              : buildDeckPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+            output,
+          })
+          return
+        }
+        if (target === "brief") {
+          const parsed = parseBriefArgs(makeParam)
+          if (!parsed.ok) {
+            await send(parsed.error.replace("/revela brief", "/revela make brief"))
+            throw new Error("__REVELA_MAKE_BRIEF_USAGE_HANDLED__")
+          }
+          await handleBrief({ workspaceRoot, outputPath: parsed.args.outputPath }, send)
+          throw new Error("__REVELA_MAKE_BRIEF_HANDLED__")
+        }
+        await send("Usage: `/revela make deck [--review]` or `/revela make brief [workspace-relative-output.md]`.")
+        throw new Error("__REVELA_MAKE_USAGE_HANDLED__")
+      }
       if (sub === "deck") {
         if (param && param !== "--review") {
-          await send("Usage: `/revela deck` starts approved-narrative deck handoff; `/revela deck --review` reviews deck/artifact readiness.")
+          await send("Usage: `/revela deck` starts approved-narrative deck handoff; `/revela deck --review` reviews deck/artifact readiness. These are compatibility aliases for `/revela make deck`.")
           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)
+          queueWorkflowCommand({
+            sessionID,
+            name: "deck",
+            mode: "deck-render",
+            visibleText: "Make Revela deck from approved story.",
+            hiddenPrompt: buildDeckPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+            output,
+          })
           return
         }
-        buildPrompt({ mode: "deck-render" })
-        output.parts.length = 0
-        output.parts.push({
-          type: "text",
-          text: buildDeckReviewPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: "deck --review",
+          mode: "deck-render",
+          visibleText: "Review Revela deck artifact readiness.",
+          hiddenPrompt: buildDeckReviewPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+          output,
+        })
         return
       }
       if (sub === "refine") {
@@ -423,7 +531,7 @@ const server: Plugin = (async (pluginCtx) => {
       }
       if (sub === "edit") {
         if (param) {
-          await send("`/revela edit` no longer accepts a target. It opens the only HTML deck in `decks/`.")
+          await send("`/revela edit` is deprecated and does not accept a target. Use `/revela refine` for the unified refinement workspace.")
           throw new Error("__REVELA_EDIT_USAGE_HANDLED__")
         }
         await handleEdit({ client, sessionID, workspaceRoot }, send)
@@ -431,7 +539,7 @@ const server: Plugin = (async (pluginCtx) => {
       }
       if (sub === "inspect") {
         if (param) {
-          await send("`/revela inspect` does not accept a target. It opens the only HTML deck in `decks/`.")
+          await send("`/revela inspect` is deprecated and does not accept a target. Use `/revela refine` for the unified reading and refinement workspace.")
           throw new Error("__REVELA_INSPECT_USAGE_HANDLED__")
         }
         await handleInspect({ client, sessionID, workspaceRoot }, send)
@@ -457,17 +565,94 @@ const server: Plugin = (async (pluginCtx) => {
         await handleDesignsAdd(param, send)
         throw new Error("__REVELA_DESIGNS_ADD_HANDLED__")
       }
+      if (sub === "design") {
+        const designAction = args[1]?.toLowerCase() ?? "list"
+        const designParam = args.slice(2).join(" ")
+        if (designAction === "list") {
+          if (designParam) {
+            await send("Usage: `/revela design list`.")
+            throw new Error("__REVELA_DESIGN_LIST_USAGE_HANDLED__")
+          }
+          await handleDesignsList(send)
+          throw new Error("__REVELA_DESIGN_LIST_HANDLED__")
+        }
+        if (designAction === "use") {
+          if (!designParam) {
+            await send("Usage: `/revela design use <name>`.")
+            throw new Error("__REVELA_DESIGN_USE_USAGE_HANDLED__")
+          }
+          await handleDesignsActivate(designParam, send)
+          throw new Error("__REVELA_DESIGN_USE_HANDLED__")
+        }
+        if (designAction === "add") {
+          if (!designParam) {
+            await send("Usage: `/revela design add <url|github:user/repo|local-path>`.")
+            throw new Error("__REVELA_DESIGN_ADD_USAGE_HANDLED__")
+          }
+          await handleDesignsAdd(designParam, send)
+          throw new Error("__REVELA_DESIGN_ADD_HANDLED__")
+        }
+        if (designAction === "rm" || designAction === "remove") {
+          if (!designParam) {
+            await send("Usage: `/revela design rm <name>`.")
+            throw new Error("__REVELA_DESIGN_RM_USAGE_HANDLED__")
+          }
+          await handleDesignsRemove(designParam, send)
+          throw new Error("__REVELA_DESIGN_RM_HANDLED__")
+        }
+        if (designAction === "preview") {
+          await handleDesignsPreview(designParam, send)
+          throw new Error("__REVELA_DESIGN_PREVIEW_HANDLED__")
+        }
+        if (designAction === "new") {
+          const parsed = parseDesignsNewArgs(designParam)
+          if (!parsed.ok) {
+            await send(parsed.error.replaceAll("/revela designs-new", "/revela design new"))
+            throw new Error("__REVELA_DESIGN_NEW_USAGE_HANDLED__")
+          }
+          queueWorkflowCommand({
+            sessionID,
+            name: `design new ${parsed.name}`,
+            mode: "deck-render",
+            visibleText: `Create Revela design ${parsed.name}.`,
+            hiddenPrompt: buildDesignsNewPrompt({ name: parsed.name, base: parsed.base }),
+            output,
+          })
+          return
+        }
+        if (designAction === "edit") {
+          const parsed = parseDesignsEditArgs(designParam)
+          if (!parsed.ok) {
+            await send(parsed.error.replaceAll("/revela designs-edit", "/revela design edit"))
+            throw new Error("__REVELA_DESIGN_EDIT_USAGE_HANDLED__")
+          }
+          queueWorkflowCommand({
+            sessionID,
+            name: `design edit ${parsed.name}`,
+            mode: "deck-render",
+            visibleText: `Edit Revela design ${parsed.name}.`,
+            hiddenPrompt: buildDesignsEditPrompt({ name: parsed.name }),
+            output,
+          })
+          return
+        }
+        await send("Usage: `/revela design [list|use <name>|new <name>|edit <name>|preview [name]|add <source>|rm <name>]`.")
+        throw new Error("__REVELA_DESIGN_USAGE_HANDLED__")
+      }
       if (sub === "designs-new") {
         const parsed = parseDesignsNewArgs(param)
         if (!parsed.ok) {
           await send(parsed.error)
           throw new Error("__REVELA_DESIGNS_NEW_USAGE_HANDLED__")
         }
-        output.parts.length = 0
-        output.parts.push({
-          type: "text",
-          text: buildDesignsNewPrompt({ name: parsed.name, base: parsed.base }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: `designs-new ${parsed.name}`,
+          mode: "deck-render",
+          visibleText: `Create Revela design ${parsed.name}.`,
+          hiddenPrompt: buildDesignsNewPrompt({ name: parsed.name, base: parsed.base }),
+          output,
+        })
         return
       }
       if (sub === "designs-edit") {
@@ -476,11 +661,14 @@ const server: Plugin = (async (pluginCtx) => {
           await send(parsed.error)
           throw new Error("__REVELA_DESIGNS_EDIT_USAGE_HANDLED__")
         }
-        output.parts.length = 0
-        output.parts.push({
-          type: "text",
-          text: buildDesignsEditPrompt({ name: parsed.name }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: `designs-edit ${parsed.name}`,
+          mode: "deck-render",
+          visibleText: `Edit Revela design ${parsed.name}.`,
+          hiddenPrompt: buildDesignsEditPrompt({ name: parsed.name }),
+          output,
+        })
         return
       }
       if (sub === "designs-preview") {
@@ -508,8 +696,14 @@ const server: Plugin = (async (pluginCtx) => {
         if (args.notes) {
           try {
             const deck = resolvePptxDeck(workspaceRoot, args.filePath)
-            output.parts.length = 0
-            output.parts.push({ type: "text", text: buildPptxNotesPrompt(deck) } as any)
+            queueWorkflowCommand({
+              sessionID,
+              name: "pptx --notes",
+              mode: "deck-render",
+              visibleText: "Export Revela deck to PPTX with speaker notes.",
+              hiddenPrompt: buildPptxNotesPrompt(deck),
+              output,
+            })
             return
           } catch (e) {
             const msg = e instanceof Error ? e.message : String(e)
@@ -633,6 +827,11 @@ const server: Plugin = (async (pluginCtx) => {
             error: e instanceof Error ? e.message : String(e),
           })
         }
+        const sessionID = extractSessionID(input)
+        const commandIntent = takePendingCommandIntent(sessionID)
+        if (commandIntent) {
+          prompt += "\n\n" + formatCommandIntentSystemBlock(commandIntent)
+        }
         if (output.system.length > 0) {
           output.system[output.system.length - 1] += "\n\n" + prompt
         } else {

package/skill/NARRATIVE_SKILL.md

@@ -1,64 +1,142 @@
 ---
 name: revela-narrative
-description: Build trusted narrative readiness before rendering deck artifacts
+description: Build trusted narrative state before rendering communication 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.
+You help the user turn source materials, research, data, and intent into trusted, traceable, presentation-ready decision artifacts.
 
-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.
+Decks are important, but they are render targets. The durable source of truth is the canonical narrative state: audience, decision, thesis, claims, evidence boundaries, objections, risks, research gaps, approval provenance, and artifact coverage.
 
-## Core Job
+Default mode is narrative-first. Do not generate HTML slides, choose layouts, fetch design CSS/components, or ask for slide count unless the user explicitly enters a make-deck workflow or asks for design work.
 
-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
+## Workflow Model
+
+Use the same phase semantics whether the user invokes a slash command or asks in normal chat:
+
+- `Init` discovers local workspace materials, captures intent, initializes or refreshes `DECKS.json`, and creates conservative narrative state only from explicit user statements or source traces.
+- `Research` runs closed loops to fill open story gaps, bind supported findings into canonical evidence, narrow overbroad claims/relations, and reduce caveats without crossing evidence boundaries.
+- `Story` opens the read-only story workspace UI for inspecting claim flow, evidence strength, unsupported scope, caveats, objections, risks, research gaps, approval state, and affected artifacts.
+- `Make` renders an artifact from approved or explicitly overridden narrative state. Supported 0.15 targets are deck and executive brief.
+- `Refine` is the post-artifact workspace for reading, inspection, and targeted editing. Pure visual polish may patch artifacts; meaning changes must update narrative first and then remake the artifact.
+
+Public command surface:
+
+- `/revela init`
+- `/revela research`
+- `/revela story`
+- `/revela make deck`
+- `/revela make brief`
+- `/revela refine`
+- `/revela design`
+
+Compatibility aliases:
+
+- `/revela review` means a legacy story readiness report
+- `/revela narrative` means `/revela story`
+- `/revela deck` means `/revela make deck`
+- `/revela brief` means `/revela make brief`
 
 ## 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
+- `upsertNarrative` to preserve canonical audience, decision, thesis, claims, evidence bindings, objections, risks, and research gaps
+- `reviewNarrative` to run deterministic story readiness
+- `deriveResearchGaps`, `upsertResearchGaps`, `updateResearchGap`, and `closeResearchGap` to manage research gap lifecycle
+- `attachResearchFindings` to attach saved findings to research state
+- `applyEvidenceCandidates` only when selected candidates should become canonical support
 - `approveNarrative` only when the user explicitly approves or requests an override
+- `compileDeckPlan`, `upsertDeck`, `upsertSlides`, and `review` only inside make-deck or artifact-readiness workflows
+
+Never treat `writeReadiness.status`, old review snapshots, existing `decks/*.html`, workspace scans, extraction cache paths, or saved research actions as narrative approval or proof by themselves.
+
+## Init Rules
+
+During init:
+
+- scan local workspace materials before asking broad questions
+- reuse `workspace.sourceMaterials` and extraction cache when fingerprints match
+- extract or read only relevant local materials; do not exhaustively process large workspaces
+- derive claims, evidence bindings, caveats, unsupported scope, source paths, quotes/snippets, pages, sheets, or slide references only when explicit support exists
+- ask the smallest missing intent questions after local evidence has been considered
+- do not require slide count, design choice, layout choice, output path, or visual style unless the user explicitly asks to make an artifact immediately
+
+## Research Rules
+
+During research:
+
+- start from open research gaps, unsupported central claims, objections, risks, and decision questions
+- run multiple review/search/bind/narrow/re-review loops when useful, stopping when no public evidence can improve the state or after the workflow limit
+- avoid generic internet research when workspace evidence already supports the claim
+- delegate external web search to the `revela-research` subagent
+- save findings through `revela-research-save`
+- treat `/revela research` as permission to attach findings and bind clearly supported evidence without item-by-item user confirmation
+- use `applyEvidenceCandidates` or `upsertNarrative` to create canonical evidence bindings when claim id, quote/snippet, source, support scope, unsupported scope, caveat, and strength are explicit
+- narrow overbroad claim scope or relation rationale when the narrower wording preserves strategic meaning and better matches the evidence
+- preserve source path, URL, location/page/sheet/slide, quote/snippet, support scope, unsupported scope, and caveat
+- keep missing or partial evidence visible instead of filling it with model assumptions; classify remaining caveats as internal-data-needed, not-publicly-researchable, source-quality-limit, or still-open
 
-Never treat `writeReadiness.status`, old review snapshots, existing `decks/*.html`, or saved research actions as narrative approval.
+## Story Rules
 
-## Narrative Review Rules
+When the user invokes `/revela story`, open the read-only story workspace UI. Do not turn that command into a blocking readiness report.
 
-When reviewing, call `revela-decks` action `reviewNarrative` and report the tool result as authoritative.
+When the user invokes `/revela review` or explicitly asks for a readiness report, 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
+- research gaps and unattached findings as next work
 - 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.
 
+## Make Rules
+
+For `/revela make deck` and compatible deck handoff:
+
+- switch to deck-render mode through the command workflow
+- check narrative readiness and current approval before compiling deck specs
+- use `compileDeckPlan` as the canonical narrative-to-deck planning path
+- run the deck/artifact gate with `revela-decks review` before writing HTML
+- fetch design layouts/components only after narrative handoff is valid
+- keep the HTML deck contract valid: one `<section class="slide">` per slide, canonical 1-based `data-slide-index`, and matching `DECKS.json` slide specs
+
+For `/revela make brief`, render the executive brief from canonical narrative state and graph-backed claim/evidence relationships, not from a deck summary.
+
+If story readiness, approval, evidence, or artifact blockers remain, report the blocker and suggest `/revela review`, `/revela research`, or a targeted user answer. Do not bypass with invented state.
+
+## Refine Rules
+
+Use `/revela refine` for post-artifact reading, inspection, and editing.
+
+- Reading should explain source, support strength, caveat, unsupported scope, narrative purpose, related risks/objections, research gaps, and artifact coverage.
+- Pure artifact polish may stay artifact-level: layout, typography, spacing, crop, visual hierarchy, export mechanics, and deck contract fixes.
+- Meaning-changing edits must update canonical narrative first, then run story readiness/approval or explicit override, then remake affected artifacts.
+- Deprecated `/revela edit` and `/revela inspect` route to Refine.
+
+## Design Surface
+
+Use `/revela design` for visual-system work: list/use/new/edit/preview/install/remove designs.
+
+Do not inject design CSS, layout catalogs, component indexes, chart rules, or deck HTML skeletons during init, research, or story. Fetch design context only for make-deck or explicit design-authoring workflows.
+
 ## 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 call `revela-decks review` in story mode; that is the deck/artifact gate.
+- Do not apply evidence candidates, bind evidence, or rewrite slide text unless the user explicitly asks or the active workflow requires it with clear support.
 - 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.
+- If source support is missing, keep the gap visible instead of making the claim sound proven.

package/skill/SKILL.md

@@ -374,7 +374,7 @@ After the user confirms the slide plan, update `DECKS.json` through `revela-deck
 3. Call `revela-designs` tool with `action: "read"` and `component` set to ALL component
    names you plan to use (comma-separated, e.g. `component: "card,stat-card,evidence-list"`).
 4. Use `revela-decks` action `upsertDeck` to mark `requiredInputs.designLayoutsFetched` complete.
-5. Run `/revela review` or call `revela-decks` action `review` yourself. The tool must compute readiness from `DECKS.json`.
+5. Run `/revela make deck --review` or call `revela-decks` action `review` yourself. The tool must compute readiness from `DECKS.json`.
 6. Use `revela-decks` action `read` and confirm `writeReadiness.status` is `ready` with no blockers.
 7. Generate HTML that **exactly matches** the fetched examples — copy the HTML structure verbatim.
 

package/tools/edit.ts

@@ -1,20 +1,20 @@
 /**
  * tools/edit.ts
  *
- * revela-edit — Open Revela's visual comment editor for an existing deck.
+ * revela-edit — Compatibility tool that opens Revela Refine in Edit mode.
  */
 
 import { tool } from "@opencode-ai/plugin"
-import { openEditableDeck } from "../lib/edit/open"
+import { openRefineDeck } from "../lib/refine/open"
 
 export function createEditTool(options: { client: any; workspaceRoot: string; openBrowser?: boolean }) {
   return tool({
     description:
-      "Open Revela's visual comment editor for an existing slide deck. " +
+      "Open Revela Refine in Edit mode for an existing slide deck. " +
       "Use this when the user asks to edit, revise, annotate, or visually comment on a deck, " +
       "including when they reference the current deck. " +
-      "Revela 0.8 opens the only HTML deck in decks/. " +
-      "This opens a local browser editor where the user can Ctrl/Cmd-click deck elements, write comments, " +
+      "This is a compatibility tool for the older edit-only workflow; the user-facing entry is /revela refine. " +
+      "It opens a local browser workspace where the user can Ctrl/Cmd-click deck elements, use the Edit tab, " +
       "and send precise edit requests back to the current OpenCode session.",
     args: {},
     async execute(_args, context: any) {
@@ -27,10 +27,11 @@ export function createEditTool(options: { client: any; workspaceRoot: string; op
       }
 
       try {
-        const result = openEditableDeck("", {
+        const result = openRefineDeck("", {
           client: options.client,
           sessionID,
           workspaceRoot: options.workspaceRoot,
+          mode: "edit",
           openBrowser: options.openBrowser,
         })
 
@@ -40,9 +41,10 @@ export function createEditTool(options: { client: any; workspaceRoot: string; op
           file: result.deck.file,
           source: result.source,
           url: result.url,
+          mode: result.mode,
           message:
-            `${result.stateNote} Opened visual editor. ` +
-            "Ask the user to use Ctrl/Cmd + click in the browser to reference elements, write a comment, then send comments.",
+            `${result.stateNote} Opened Revela Refine in Edit mode. ` +
+            "Ask the user to use Ctrl/Cmd-click in the browser to reference elements, then use the Edit tab to send comments.",
         }, null, 2)
       } catch (error) {
         return JSON.stringify({