@cyber-dash-tech/revela 0.16.3 → 0.17.0

package/lib/refine/visual-targets.ts

@@ -0,0 +1,295 @@
+import { readFileSync, statSync, writeFileSync } from "fs"
+
+export type VisualEditKind = "image" | "text-width" | "box"
+
+export interface VisualEditTarget {
+  editId: string
+  kind: VisualEditKind
+  tagName: "img" | "h1" | "h2" | "h3" | "h4" | "p" | "div" | "figure"
+  startOffset: number
+  openEndOffset: number
+  originalOpenTag: string
+  originalStyle: string
+}
+
+export interface VisualTargetResizeChange {
+  type: "resize"
+  editId: string
+  kind?: VisualEditKind
+  after: {
+    stylePatch?: Record<string, unknown>
+    width?: number
+    height?: number
+  }
+}
+
+export interface VisualTargetMoveChange {
+  type: "move"
+  editId: string
+  kind?: VisualEditKind
+  after: {
+    stylePatch?: Record<string, unknown>
+    dx?: number
+    dy?: number
+  }
+}
+
+export type VisualTargetChange = VisualTargetResizeChange | VisualTargetMoveChange
+
+export interface ApplyVisualTargetChangesInput {
+  file: string
+  deckVersion?: string
+  targetDeckVersion?: string
+  targets: Map<string, VisualEditTarget>
+  changes: VisualTargetChange[]
+}
+
+export interface ApplyVisualTargetChangesResult {
+  ok: true
+  deckVersion: string
+  changeCount: number
+}
+
+const TEXT_TAGS = new Set(["h1", "h2", "h3", "h4", "p"])
+const BOX_TAGS = new Set(["div", "figure"])
+const EDIT_TAGS = new Set(["img", ...TEXT_TAGS, ...BOX_TAGS])
+const MAX_DIMENSION_PX = 3840
+const MIN_IMAGE_DIMENSION_PX = 24
+const MIN_TEXT_WIDTH_PX = 80
+const MIN_BOX_WIDTH_PX = 40
+const MIN_BOX_HEIGHT_PX = 24
+
+export function annotateVisualEditTargets(html: string): { html: string; targets: Map<string, VisualEditTarget> } {
+  const targets = new Map<string, VisualEditTarget>()
+  const insertions: Array<{ offset: number; text: string }> = []
+  let nextId = 1
+
+  for (const tag of scanOpeningTags(html)) {
+    if (!EDIT_TAGS.has(tag.tagName)) continue
+    if (BOX_TAGS.has(tag.tagName) && !isSafeBoxTarget(tag.openTag)) continue
+    const editId = `rve-${nextId++}`
+    const kind: VisualEditKind = tag.tagName === "img" ? "image" : BOX_TAGS.has(tag.tagName) ? "box" : "text-width"
+    targets.set(editId, {
+      editId,
+      kind,
+      tagName: tag.tagName as VisualEditTarget["tagName"],
+      startOffset: tag.startOffset,
+      openEndOffset: tag.openEndOffset,
+      originalOpenTag: tag.openTag,
+      originalStyle: attrValue(tag.openTag, "style") || "",
+    })
+    insertions.push({ offset: tag.openEndOffset - (tag.openTag.endsWith("/>") ? 2 : 1), text: ` data-revela-edit-id="${editId}" data-revela-edit-kind="${kind}"` })
+  }
+
+  let annotated = html
+  for (const insertion of insertions.reverse()) {
+    annotated = annotated.slice(0, insertion.offset) + insertion.text + annotated.slice(insertion.offset)
+  }
+  return { html: annotated, targets }
+}
+
+export function applyVisualTargetChanges(input: ApplyVisualTargetChangesInput): ApplyVisualTargetChangesResult {
+  const currentVersion = readDeckVersion(input.file).version
+  if (input.deckVersion && input.deckVersion !== currentVersion) throw new Error("Deck changed outside Review. Refresh Review before saving visual edits.")
+  if (input.targetDeckVersion && input.targetDeckVersion !== currentVersion) throw new Error("Review visual targets are stale. Refresh Review before saving visual edits.")
+  if (!input.changes.length) throw new Error("No visual changes to save.")
+
+  let html = readFileSync(input.file, "utf-8")
+  const resolved = new Map<string, { target: VisualEditTarget; patch: Record<string, string> }>()
+  for (const change of input.changes) {
+    const target = input.targets.get(change.editId)
+    if (!target) throw new Error("Target is no longer editable. Refresh Review and try again.")
+    if (change.kind && change.kind !== target.kind) throw new Error("Visual edit target kind changed. Refresh Review and try again.")
+    const currentOpenTag = html.slice(target.startOffset, target.openEndOffset)
+    if (currentOpenTag !== target.originalOpenTag) throw new Error("Target is no longer editable. Refresh Review and try again.")
+    const patch = normalizeStylePatch(target, change)
+    if (!Object.keys(patch).length) throw new Error("Visual change does not contain valid style updates.")
+    const existing = resolved.get(target.editId)
+    resolved.set(target.editId, { target, patch: { ...(existing?.patch ?? {}), ...patch } })
+  }
+
+  for (const { target, patch } of Array.from(resolved.values()).sort((a, b) => b.target.startOffset - a.target.startOffset)) {
+    const updatedOpenTag = patchOpenTagStyle(target.originalOpenTag, patch)
+    html = html.slice(0, target.startOffset) + updatedOpenTag + html.slice(target.openEndOffset)
+  }
+
+  writeFileSync(input.file, html, "utf-8")
+  return { ok: true, deckVersion: readDeckVersion(input.file).version, changeCount: input.changes.length }
+}
+
+export function readDeckVersion(file: string): { mtimeMs: number; size: number; version: string } {
+  const stat = statSync(file)
+  return { mtimeMs: stat.mtimeMs, size: stat.size, version: `${stat.mtimeMs}:${stat.size}` }
+}
+
+function normalizeStylePatch(target: VisualEditTarget, change: VisualTargetChange): Record<string, string> {
+  const input = change.after.stylePatch ?? {}
+  if (change.type === "move") return normalizeMovePatch(target, input)
+  if (change.type !== "resize") throw new Error(`Unsupported visual change type: ${(change as any).type}`)
+  return normalizeResizePatch(target.kind, input)
+}
+
+function normalizeResizePatch(kind: VisualEditKind, input: Record<string, unknown>): Record<string, string> {
+  const patch: Record<string, string> = {}
+  const width = typeof input.width === "string" ? normalizePxValue(input.width, kind === "image" ? MIN_IMAGE_DIMENSION_PX : kind === "box" ? MIN_BOX_WIDTH_PX : MIN_TEXT_WIDTH_PX) : null
+  if (width) patch.width = width
+  if (kind === "image" || kind === "box") {
+    const height = typeof input.height === "string" ? normalizePxValue(input.height, kind === "image" ? MIN_IMAGE_DIMENSION_PX : MIN_BOX_HEIGHT_PX) : null
+    if (height) patch.height = height
+  } else {
+    const maxWidth = typeof input["max-width"] === "string" ? normalizePxValue(input["max-width"], MIN_TEXT_WIDTH_PX) : null
+    if (maxWidth) patch["max-width"] = maxWidth
+  }
+  return patch
+}
+
+function normalizeMovePatch(target: VisualEditTarget, input: Record<string, unknown>): Record<string, string> {
+  const translate = typeof input.translate === "string" ? normalizeTranslateValue(input.translate) : null
+  if (translate) return { translate }
+  const transform = typeof input.transform === "string" ? normalizeLegacyTransformValue(input.transform) : null
+  return transform ? { translate: transform } : {}
+}
+
+function normalizeTranslateValue(value: string): string | null {
+  const direct = parseTranslateProperty(value)
+  if (direct) return normalizeTranslatePoint(direct)
+  return normalizeLegacyTransformValue(value)
+}
+
+function normalizeLegacyTransformValue(value: string): string | null {
+  const parsed = parseSimpleTranslate(value)
+  if (!parsed) return null
+  return normalizeTranslatePoint(parsed)
+}
+
+function normalizeTranslatePoint(parsed: { x: number; y: number }): string | null {
+  const { x, y } = parsed
+  if (Math.abs(x) > MAX_DIMENSION_PX || Math.abs(y) > MAX_DIMENSION_PX) return null
+  return `${Math.round(x)}px ${Math.round(y)}px`
+}
+
+function parseTranslateProperty(value: string): { x: number; y: number } | null {
+  const normalized = value.trim()
+  const match = /^(-?\d+(?:\.\d+)?)px(?:\s+|\s*,\s*)(-?\d+(?:\.\d+)?)px$/.exec(normalized)
+  return match ? finitePoint(Number(match[1]), Number(match[2])) : null
+}
+
+function parseSimpleTranslate(value: string): { x: number; y: number } | null {
+  const normalized = value.trim()
+  if (!normalized || normalized === "none") return { x: 0, y: 0 }
+  const translate = /^translate\(\s*(-?\d+(?:\.\d+)?)px(?:\s*,\s*|\s+)(-?\d+(?:\.\d+)?)px\s*\)$/.exec(normalized)
+  if (translate) return finitePoint(Number(translate[1]), Number(translate[2]))
+  const matrix = /^matrix\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\)$/.exec(normalized)
+  if (!matrix) return null
+  const a = Number(matrix[1])
+  const b = Number(matrix[2])
+  const c = Number(matrix[3])
+  const d = Number(matrix[4])
+  if (a !== 1 || b !== 0 || c !== 0 || d !== 1) return null
+  return finitePoint(Number(matrix[5]), Number(matrix[6]))
+}
+
+function finitePoint(x: number, y: number): { x: number; y: number } | null {
+  return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : null
+}
+
+function normalizePxValue(value: string, min: number): string | null {
+  const match = /^(\d+(?:\.\d+)?)px$/.exec(value.trim())
+  if (!match) return null
+  const number = Number(match[1])
+  if (!Number.isFinite(number) || number < min || number > MAX_DIMENSION_PX) return null
+  return `${Math.round(number)}px`
+}
+
+function patchOpenTagStyle(openTag: string, patch: Record<string, string>): string {
+  const styleMatch = /\sstyle=("([^"]*)"|'([^']*)')/i.exec(openTag)
+  const current = styleMatch ? parseStyle(styleMatch[2] ?? styleMatch[3] ?? "") : {}
+  const next = serializeStyle({ ...current, ...patch })
+  if (styleMatch) return openTag.slice(0, styleMatch.index) + ` style="${escapeAttr(next)}"` + openTag.slice(styleMatch.index + styleMatch[0].length)
+  return openTag.replace(/\s*\/?>$/, (ending) => ` style="${escapeAttr(next)}"${ending}`)
+}
+
+function parseStyle(style: string): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const part of style.split(";")) {
+    const index = part.indexOf(":")
+    if (index < 0) continue
+    const key = part.slice(0, index).trim().toLowerCase()
+    const value = part.slice(index + 1).trim()
+    if (key && value) result[key] = value
+  }
+  return result
+}
+
+function serializeStyle(style: Record<string, string>): string {
+  return Object.entries(style).map(([key, value]) => `${key}: ${value}`).join("; ")
+}
+
+function escapeAttr(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;")
+}
+
+interface OpenTagRegion {
+  tagName: string
+  startOffset: number
+  openEndOffset: number
+  openTag: string
+}
+
+function scanOpeningTags(html: string): OpenTagRegion[] {
+  const tags: OpenTagRegion[] = []
+  let index = 0
+  while (index < html.length) {
+    const open = html.indexOf("<", index)
+    if (open < 0) break
+    if (html.startsWith("<!--", open)) {
+      const close = html.indexOf("-->", open + 4)
+      index = close < 0 ? html.length : close + 3
+      continue
+    }
+    const close = html.indexOf(">", open + 1)
+    if (close < 0) break
+    const raw = html.slice(open, close + 1)
+    const tagName = normalizeName(/^<\s*([a-zA-Z0-9-]+)/.exec(raw)?.[1] || "")
+    if (!tagName || /^<\s*[!/]/.test(raw) || /^<\s*\//.test(raw)) {
+      index = close + 1
+      continue
+    }
+    tags.push({ tagName, startOffset: open, openEndOffset: close + 1, openTag: raw })
+    if (tagName === "script" || tagName === "style") {
+      const closeTag = new RegExp(`</\\s*${tagName}\\s*>`, "ig")
+      closeTag.lastIndex = close + 1
+      const match = closeTag.exec(html)
+      index = match ? match.index + match[0].length : close + 1
+    } else {
+      index = close + 1
+    }
+  }
+  return tags
+}
+
+function attrValue(openTag: string, name: string): string | undefined {
+  const escaped = escapeRegExp(name)
+  const match = new RegExp(`\\s${escaped}=("([^"]*)"|'([^']*)')`, "i").exec(openTag)
+  return match ? match[2] ?? match[3] : undefined
+}
+
+function isSafeBoxTarget(openTag: string): boolean {
+  const tagName = normalizeName(/^<\s*([a-zA-Z0-9-]+)/.exec(openTag)?.[1] || "")
+  const className = attrValue(openTag, "class") || ""
+  const classes = className.split(/\s+/).map((item) => item.trim().toLowerCase()).filter(Boolean)
+  if (tagName === "div" && classes.length === 0) return false
+  if (/\s(?:data-chart|data-echarts|_echarts_instance_)\b/i.test(openTag)) return false
+  if (classes.some((name) => name === "slide" || name === "slide-canvas" || name === "deck" || name === "page")) return false
+  if (classes.some((name) => name.startsWith("revela-") || name.startsWith("echarts-") || name === "echart-container" || name === "echart-panel")) return false
+  if (classes.some((name) => /(^|-)echart($|-)/.test(name) || name === "chart-container" || name === "chart-panel")) return false
+  return true
+}
+
+function normalizeName(value: string | undefined): string {
+  return (value || "").trim().toLowerCase()
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}

package/lib/source-materials.ts

@@ -46,6 +46,103 @@ export function sourceMaterialMetadata(filePath: string, workspaceRoot: string):
     type: sourceMaterialType(resolvedFile),
     size: stat.size,
     fingerprint: computeSourceFingerprint(resolvedFile),
+    lastModified: new Date(stat.mtimeMs).toISOString(),
+  }
+}
+
+export function sourceMaterialModifiedMs(material: SourceMaterial, workspaceRoot: string): number {
+  if (material.lastModified) {
+    const parsed = Date.parse(material.lastModified)
+    if (Number.isFinite(parsed)) return parsed
+  }
+
+  try {
+    return statSync(ensureWorkspaceFile(material.path, workspaceRoot)).mtimeMs
+  } catch {
+    return 0
+  }
+}
+
+export interface SourceMaterialIngestPlan {
+  vaultTimestamp: string | null
+  vaultTimestampMs: number
+  addedSourceMaterials: SourceMaterial[]
+  changedSourceMaterials: SourceMaterial[]
+  newerThanVaultSourceMaterials: SourceMaterial[]
+  unchangedSourceMaterials: SourceMaterial[]
+  ingestCandidates: SourceMaterial[]
+  suggestedTasks: SourceMaterialIngestTask[]
+}
+
+export interface SourceMaterialIngestTask {
+  path: string
+  reason: Array<"added" | "changed" | "newer_than_vault">
+  materialType: string
+  needsExtraction: boolean
+  suggestedAction: "read_directly" | "extract_then_read"
+  note: string
+}
+
+export function classifySourceMaterialIngest(
+  state: DecksState,
+  materials: SourceMaterial[],
+  workspaceRoot: string,
+  vaultTimestampMs: number,
+): SourceMaterialIngestPlan {
+  const existingByPath = new Map((state.workspace.sourceMaterials ?? []).map((item) => [item.path.replace(/\\/g, "/"), item]))
+  const addedSourceMaterials: SourceMaterial[] = []
+  const changedSourceMaterials: SourceMaterial[] = []
+  const newerThanVaultSourceMaterials: SourceMaterial[] = []
+  const unchangedSourceMaterials: SourceMaterial[] = []
+  const ingestByPath = new Map<string, SourceMaterial>()
+  const reasonsByPath = new Map<string, SourceMaterialIngestTask["reason"]>()
+
+  for (const material of materials) {
+    const path = material.path.replace(/\\/g, "/")
+    const existing = existingByPath.get(path)
+    const added = !existing
+    const changed = Boolean(existing?.fingerprint && material.fingerprint && existing.fingerprint !== material.fingerprint)
+    const newerThanVault = sourceMaterialModifiedMs(material, workspaceRoot) > vaultTimestampMs
+    const reasons: SourceMaterialIngestTask["reason"] = []
+
+    if (added) addedSourceMaterials.push(material)
+    if (changed) changedSourceMaterials.push(material)
+    if (newerThanVault) newerThanVaultSourceMaterials.push(material)
+    if (added) reasons.push("added")
+    if (changed) reasons.push("changed")
+    if (newerThanVault) reasons.push("newer_than_vault")
+    if (added || changed || newerThanVault) {
+      ingestByPath.set(path, material)
+      reasonsByPath.set(path, reasons)
+    }
+    else unchangedSourceMaterials.push(material)
+  }
+  const ingestCandidates = [...ingestByPath.values()].sort((a, b) => a.path.localeCompare(b.path))
+
+  return {
+    vaultTimestamp: vaultTimestampMs > 0 ? new Date(vaultTimestampMs).toISOString() : null,
+    vaultTimestampMs,
+    addedSourceMaterials,
+    changedSourceMaterials,
+    newerThanVaultSourceMaterials,
+    unchangedSourceMaterials,
+    ingestCandidates,
+    suggestedTasks: ingestCandidates.map((material) => sourceMaterialIngestTask(material, reasonsByPath.get(material.path.replace(/\\/g, "/")) ?? [])),
+  }
+}
+
+function sourceMaterialIngestTask(material: SourceMaterial, reason: SourceMaterialIngestTask["reason"]): SourceMaterialIngestTask {
+  const materialType = (material.type || sourceMaterialType(material.path)).toLowerCase()
+  const needsExtraction = ["pdf", "ppt", "pptx", "doc", "docx", "xls", "xlsx"].includes(materialType)
+  return {
+    path: material.path,
+    reason,
+    materialType,
+    needsExtraction,
+    suggestedAction: needsExtraction ? "extract_then_read" : "read_directly",
+    note: needsExtraction
+      ? "Use revela-extract-document-materials before synthesizing stable narrative findings when this file is relevant."
+      : "Read directly when relevant and distill stable narrative findings into the Markdown vault.",
   }
 }
 
@@ -77,6 +174,7 @@ export function upsertSourceMaterial(
     path,
     type: material.type ?? existing?.type,
     status: nextStatus,
+    lastModified: material.lastModified ?? existing?.lastModified,
     firstSeen: existing?.firstSeen ?? material.firstSeen ?? now,
     lastChecked: now,
   }

package/lib/tool-result.ts

@@ -0,0 +1,34 @@
+export function appendToolResult(output: any, text: string): void {
+  if (!output || typeof output !== "object") return
+
+  if (typeof output.output === "string") {
+    output.output = appendText(output.output, text)
+    return
+  }
+
+  if (typeof output.result === "string") {
+    output.result = appendText(output.result, text)
+    return
+  }
+
+  if (typeof output.text === "string") {
+    output.text = appendText(output.text, text)
+    return
+  }
+
+  if (typeof output.message === "string") {
+    output.message = appendText(output.message, text)
+    return
+  }
+
+  if (Array.isArray(output.content)) {
+    output.content.push({ type: "text", text })
+    return
+  }
+
+  output.output = text
+}
+
+function appendText(existing: string, text: string): string {
+  return (existing ? `${existing}\n\n` : "") + text
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.16.3",
-  "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
+  "version": "0.17.0",
+  "description": "OpenCode plugin for trusted narrative artifacts from local sources, research, and evidence",
   "type": "module",
   "main": "./index.ts",
   "exports": {

package/plugin.ts

@@ -72,6 +72,11 @@ import {
   hasDecksState,
   isDecksStatePath,
 } from "./lib/decks-state"
+import { autoCompileNarrativeVault } from "./lib/narrative-vault/auto-compile"
+import {
+  extractNarrativeVaultMarkdownTargetsFromPatch,
+  normalizeNarrativeVaultMarkdownPath,
+} from "./lib/narrative-vault/hook-targets"
 import decksTool from "./tools/decks"
 import designsAuthorTool from "./tools/designs-author"
 import designsTool from "./tools/designs"
@@ -93,6 +98,8 @@ import { RESEARCH_PROMPT, RESEARCH_AGENT_SIGNATURE } from "./lib/agents/research
 import { NARRATIVE_REVIEWER_PROMPT, NARRATIVE_REVIEWER_SIGNATURE } from "./lib/agents/narrative-reviewer-prompt"
 import { extractDesignClasses } from "./lib/design/designs"
 import { log, childLog } from "./lib/log"
+import { appendToolResult } from "./lib/tool-result"
+import { formatArtifactQaUserNotice, formatMarkdownQaUserNotice, formatStateGateUserNotice } from "./lib/hook-notifications"
 
 // OpenCode internal agent signatures — used to skip system prompt injection
 // for built-in system agents (title, summary, compaction).
@@ -102,16 +109,6 @@ const INTERNAL_AGENT_SIGNATURES = [
   "Summarize what was done in this conversation",
 ]
 
-function appendToolResult(output: any, text: string): void {
-  if (typeof output.output === "string") {
-    output.output = (output.output ? output.output + "\n\n" : "") + text
-    return
-  }
-
-  const existing = output.result ?? ""
-  output.result = (existing ? existing + "\n\n" : "") + text
-}
-
 function extractEditFilePath(args: any): string {
   return args?.filePath ?? args?.file_path ?? args?.path ?? args?.file ?? ""
 }
@@ -148,7 +145,7 @@ const server: Plugin = (async (pluginCtx) => {
   const blockedDeckWrites = new Map<string, string>()
   const blockedPatches = new Map<string, string>()
 
-  async function runPostWriteArtifactQA(filePath: string, output: any): Promise<boolean> {
+  async function runPostWriteArtifactQA(filePath: string, output: any, sessionID = ""): Promise<boolean> {
     if (!isDeckHtmlPath(filePath)) return true
 
     try {
@@ -161,6 +158,8 @@ const server: Plugin = (async (pluginCtx) => {
 
       const report = await runArtifactQA({ workspaceRoot, filePath, vocabulary })
       appendToolResult(output, "---\n\n" + formatArtifactQAReport(report))
+      const notice = formatArtifactQaUserNotice(report)
+      if (notice && sessionID) await sendIgnoredMessage(client, sessionID, notice)
       return report.passed
     } catch (e) {
       childLog("artifact-qa").warn("post-write artifact QA failed", {
@@ -168,10 +167,27 @@ const server: Plugin = (async (pluginCtx) => {
         error: e instanceof Error ? e.message : String(e),
       })
       appendToolResult(output, "---\n\n## Artifact QA: FAILED\n\nError running artifact QA: " + (e instanceof Error ? e.message : String(e)))
+      if (sessionID) await sendIgnoredMessage(client, sessionID, `**Artifact QA failed**\nFile: \`${filePath}\`\nError: ${e instanceof Error ? e.message : String(e)}`)
       return false
     }
   }
 
+  async function runPostWriteNarrativeVaultCompile(touched: string[], output: any, sessionID = ""): Promise<void> {
+    if (touched.length === 0) return
+
+    const result = autoCompileNarrativeVault(workspaceRoot, touched)
+    appendToolResult(output, "---\n\n" + result.markdown)
+    const notice = formatMarkdownQaUserNotice(result)
+    if (notice && sessionID) await sendIgnoredMessage(client, sessionID, notice)
+    if (!result.ok) {
+      childLog("narrative-vault").warn("auto-compile reported blockers", {
+        touched,
+        mirror: result.mirrored,
+        error: result.error,
+      })
+    }
+  }
+
   function extractSessionID(input: any): string {
     return input?.sessionID ?? input?.session?.id ?? input?.context?.sessionID ?? ""
   }
@@ -314,6 +330,17 @@ const server: Plugin = (async (pluginCtx) => {
         await handleHelp(send)
         throw new Error("__REVELA_STATUS_HANDLED__")
       }
+      if (sub === "enable") {
+        ctx.enabled = true
+        buildPrompt()
+        await send("Revela enabled. Workflow commands and Revela context are active.")
+        throw new Error("__REVELA_ENABLE_HANDLED__")
+      }
+      if (sub === "disable") {
+        ctx.enabled = false
+        await send("Revela disabled. Run `/revela enable` or any workflow command to reactivate.")
+        throw new Error("__REVELA_DISABLE_HANDLED__")
+      }
       if (sub === "make") {
         const target = args[1]?.toLowerCase() ?? ""
         const makeParam = args.slice(2).join(" ")
@@ -500,7 +527,7 @@ const server: Plugin = (async (pluginCtx) => {
         throw new Error("__REVELA_DOMAIN_USAGE_HANDLED__")
       }
       const legacyCommands = new Set([
-        "enable", "disable", "review", "narrative", "deck", "brief", "edit", "inspect", "remember",
+        "review", "narrative", "deck", "brief", "edit", "inspect", "remember",
         "designs", "designs-new", "designs-edit", "designs-preview", "designs-add", "designs-rm",
         "domains", "domains-add", "domains-rm", "pdf", "pptx",
       ])
@@ -689,8 +716,6 @@ const server: Plugin = (async (pluginCtx) => {
     // - write/apply_patch: protect DECKS.json, but do not block deck HTML edits.
     "tool.execute.before": async (input, output) => {
       log.info("[hook] tool.execute.before fired", { tool: input.tool, enabled: ctx.enabled, isResearch: ctx.isResearchAgent })
-      if (!ctx.enabled) return
-
       if (input.tool === "write") {
         const filePath: string = (output.args as any)?.filePath ?? ""
         if (isDecksStatePath(filePath)) {
@@ -741,6 +766,8 @@ Next step: use \`revela-decks\` with action \`init\`, \`upsertDeck\`, \`upsertSl
         }
       }
 
+      if (!ctx.enabled) return
+
       if (input.tool === "read") {
         try {
           await preRead(output.args)
@@ -760,10 +787,9 @@ Next step: use \`revela-decks\` with action \`init\`, \`upsertDeck\`, \`upsertSl
     // Also reports writes/patches blocked by the DECKS.json prewrite gate and
     // runs artifact QA before opening Refine after successful deck changes.
     "tool.execute.after": async (input, output) => {
-      if (!ctx.enabled) return
-
       // ── Post-read processing ───────────────────────────────────────────
       if (input.tool === "read") {
+        if (!ctx.enabled) return
         try {
           await postRead(input.args, output)
         } catch (e) {
@@ -787,39 +813,51 @@ Next step: use \`revela-decks\` with action \`init\`, \`upsertDeck\`, \`upsertSl
             `${blockedReason}\n\n` +
             "Use the `revela-decks` tool or complete the DECKS.json review workflow instead."
           )
+          await sendIgnoredMessage(client, extractSessionID(input), formatStateGateUserNotice("write", blockedReason))
           return
         }
-        const qaPassed = await runPostWriteArtifactQA(filePath, output)
+        const vaultTarget = normalizeNarrativeVaultMarkdownPath(filePath, workspaceRoot)
+        const sessionID = extractSessionID(input)
+        if (vaultTarget) await runPostWriteNarrativeVaultCompile([vaultTarget], output, sessionID)
+        const qaPassed = await runPostWriteArtifactQA(filePath, output, sessionID)
         if (qaPassed) ensureRefineOpenAfterDeckChange(filePath, extractSessionID(input))
         return
       }
 
       if (input.tool === "apply_patch" && blockedPatches.size > 0) {
         const [blockedPath, blockedReason] = blockedPatches.entries().next().value ?? []
+        if (!blockedPath || !blockedReason) return
         if (blockedPath) blockedPatches.delete(blockedPath)
         appendToolResult(
           output,
           "---\n\n**[revela prewrite gate]** Patch was blocked.\n\n" +
           `${blockedReason}\n\n` +
-          "Use the `revela-decks` tool for controlled workspace state changes."
+            "Use the `revela-decks` tool for controlled workspace state changes."
         )
+        await sendIgnoredMessage(client, extractSessionID(input), formatStateGateUserNotice("patch", blockedReason))
         return
       }
 
       if (input.tool === "apply_patch") {
         const patchText = extractPatchTextArg(input.args as Record<string, unknown>)
+        const vaultTargets = patchText ? extractNarrativeVaultMarkdownTargetsFromPatch(patchText, workspaceRoot) : []
+        const sessionID = extractSessionID(input)
+        await runPostWriteNarrativeVaultCompile(vaultTargets, output, sessionID)
         const targets = patchText ? extractDeckHtmlTargetsFromPatch(patchText) : []
         for (const target of targets) {
-          const qaPassed = await runPostWriteArtifactQA(target, output)
-          if (qaPassed) ensureRefineOpenAfterDeckChange(target, extractSessionID(input))
+          const qaPassed = await runPostWriteArtifactQA(target, output, sessionID)
+          if (qaPassed) ensureRefineOpenAfterDeckChange(target, sessionID)
         }
         return
       }
 
       if (input.tool === "edit") {
         const filePath = extractEditFilePath(input.args)
-        const qaPassed = await runPostWriteArtifactQA(filePath, output)
-        if (qaPassed) ensureRefineOpenAfterDeckChange(filePath, extractSessionID(input))
+        const vaultTarget = normalizeNarrativeVaultMarkdownPath(filePath, workspaceRoot)
+        const sessionID = extractSessionID(input)
+        if (vaultTarget) await runPostWriteNarrativeVaultCompile([vaultTarget], output, sessionID)
+        const qaPassed = await runPostWriteArtifactQA(filePath, output, sessionID)
+        if (qaPassed) ensureRefineOpenAfterDeckChange(filePath, sessionID)
         return
       }
     },