@cyber-dash-tech/revela 0.17.20 → 0.17.22

package/plugins/revela/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "revela": {
       "command": "npx",
-      "args": ["-y", "@cyber-dash-tech/revela@0.17.20", "mcp"]
+      "args": ["-y", "@cyber-dash-tech/revela@0.17.22", "mcp"]
     }
   }
 }

package/plugins/revela/hooks/hooks.json

@@ -1,6 +1,16 @@
 {
   "hooks": {
     "PreToolUse": [
+      {
+        "matcher": "exec_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun ${PLUGIN_ROOT}/hooks/revela_material_notice.ts",
+            "statusMessage": "Checking Revela material intake"
+          }
+        ]
+      },
       {
         "matcher": "apply_patch",
         "hooks": [

package/plugins/revela/hooks/revela_guard.ts

@@ -17,6 +17,15 @@ export async function runPreWriteChecks(input: string): Promise<HookResult> {
     messages.push(`Revela controls ${controlledStateFile}. Use Revela MCP/runtime tools or file-native narrative files instead of direct ${controlledStateFile} patches.`)
   }
 
+  const cacheTargets = extractNarrativeCachePatchTargets(input)
+  if (cacheTargets.length > 0) {
+    messages.push([
+      "Revela narrative cache patches are blocked.",
+      `Controlled cache target(s): ${cacheTargets.map((target) => `\`${target}\``).join(", ")}`,
+      "Edit `revela-narrative/**/*.md` instead; compile/cache files under `.opencode/revela/narrative-cache/` are regenerated.",
+    ].join("\n"))
+  }
+
   const deckTargets = extractDeckHtmlPatchTargets(input)
   if (deckTargets.length > 0) {
     const pluginRoot = resolve(process.env.PLUGIN_ROOT || dirname(dirname(fileURLToPath(import.meta.url))))
@@ -55,6 +64,16 @@ export function extractDeckHtmlPatchTargets(input: string): string[] {
   return [...targets].sort((a, b) => a.localeCompare(b))
 }
 
+export function extractNarrativeCachePatchTargets(input: string): string[] {
+  const targets = new Set<string>()
+  for (const patch of patchPayloads(input)) {
+    const pattern = /(?:^\*\*\* Update File: |^\*\*\* Add File: |^\*\*\* Delete File: |^\*\*\* Move to: )([^\r\n]*\.opencode\/revela\/narrative-cache\/[^\r\n]+)\s*$/gm
+    let match: RegExpExecArray | null
+    while ((match = pattern.exec(patch))) targets.add(match[1].trim())
+  }
+  return [...targets].sort((a, b) => a.localeCompare(b))
+}
+
 function patchPayloads(input: string): string[] {
   try {
     const parsed = JSON.parse(input)

package/plugins/revela/hooks/revela_material_notice.ts

@@ -0,0 +1,58 @@
+import { dirname, resolve } from "path"
+import { fileURLToPath, pathToFileURL } from "url"
+import { resolveRevelaRuntime } from "../mcp/runtime-resolver"
+import { workspaceRootFromInput } from "./revela_post_write_notice"
+
+export interface MaterialNoticeResult {
+  ok: true
+  messages: string[]
+}
+
+export async function runMaterialReadNotice(input: string): Promise<MaterialNoticeResult> {
+  const command = commandFromInput(input)
+  if (!command) return { ok: true, messages: [] }
+
+  const pluginRoot = resolve(process.env.PLUGIN_ROOT || dirname(dirname(fileURLToPath(import.meta.url))))
+  const runtime = resolveRevelaRuntime({ pluginRoot })
+  if (!runtime.ok || !runtime.runtimePath) return { ok: true, messages: [] }
+
+  const workspaceRoot = workspaceRootFromInput(input)
+  const runtimeModule = await import(pathToFileURL(runtime.runtimePath).href)
+  const notice = runtimeModule.materialIntakeNoticeForCommand?.({ workspaceRoot, command })
+  return { ok: true, messages: notice ? [notice] : [] }
+}
+
+export function commandFromInput(input: string): string | null {
+  try {
+    const parsed = JSON.parse(input)
+    const candidates = [
+      parsed.cmd,
+      parsed.command,
+      parsed.args?.cmd,
+      parsed.args?.command,
+      parsed.tool_input?.cmd,
+      parsed.tool_input?.command,
+      parsed.toolInput?.cmd,
+      parsed.toolInput?.command,
+    ]
+    for (const candidate of candidates) {
+      if (typeof candidate === "string" && candidate.trim()) return candidate
+    }
+    return null
+  } catch {
+    return input.trim() || null
+  }
+}
+
+if (import.meta.main) {
+  const input = await new Response(Bun.stdin.stream()).text()
+  try {
+    const result = await runMaterialReadNotice(input)
+    if (result.messages.length > 0) console.error(result.messages.join("\n\n---\n\n"))
+    process.exit(0)
+  } catch (e) {
+    console.error("Revela material intake notice failed to run.")
+    console.error(e instanceof Error ? e.message : String(e))
+    process.exit(0)
+  }
+}

package/plugins/revela/hooks/revela_post_write_notice.ts

@@ -24,6 +24,20 @@ export function extractDeckHtmlTargets(input: string): string[] {
   return [...targets].sort((a, b) => a.localeCompare(b))
 }
 
+export function patchPayloadsFromInput(input: string): string[] {
+  try {
+    const parsed = JSON.parse(input)
+    return [
+      parsed.patch,
+      parsed.args?.patch,
+      parsed.tool_input?.patch,
+      parsed.toolInput?.patch,
+    ].filter((item): item is string => typeof item === "string")
+  } catch {
+    return [input]
+  }
+}
+
 export function workspaceRootFromInput(input: string): string {
   try {
     const parsed = JSON.parse(input)
@@ -47,18 +61,16 @@ export function workspaceRootFromInput(input: string): string {
 
 export async function runPostWriteChecks(input: string): Promise<HookResult> {
   const messages: string[] = []
-  if (/revela-narrative\/.*\.md/.test(input)) {
-    messages.push("Revela narrative Markdown changed. Run `revela_markdown_qa` and `revela_compile_narrative` before treating the graph as usable.")
-  }
-
   const deckTargets = extractDeckHtmlTargets(input)
-  if (deckTargets.length === 0) return { ok: true, messages }
+  const hasPossibleNarrativeMarkdown = /revela-narrative\/.*\.md/.test(input)
+  if (deckTargets.length === 0 && !hasPossibleNarrativeMarkdown) return { ok: true, messages }
 
   const pluginRoot = resolve(process.env.PLUGIN_ROOT || dirname(dirname(fileURLToPath(import.meta.url))))
   const runtime = resolveRevelaRuntime({ pluginRoot })
   if (!runtime.ok || !runtime.runtimePath) {
+    const changed = deckTargets.length > 0 ? "deck HTML changed" : "narrative Markdown changed"
     messages.push([
-      "Revela deck HTML changed, but Codex hook could not locate the Revela runtime to run Artifact QA.",
+      `Revela ${changed}, but Codex hook could not locate the Revela runtime to run write-after checks.`,
       ...runtime.diagnostics.map((item) => `- ${item}`),
     ].join("\n"))
     return { ok: false, messages }
@@ -67,9 +79,28 @@ export async function runPostWriteChecks(input: string): Promise<HookResult> {
   const workspaceRoot = workspaceRootFromInput(input)
   const runtimeModule = await import(pathToFileURL(runtime.runtimePath).href)
   let ok = true
+
+  if (hasPossibleNarrativeMarkdown) {
+    const touched = new Set<string>()
+    for (const patch of patchPayloadsFromInput(input)) {
+      const targets = runtimeModule.extractNarrativeVaultMarkdownPatchTargets({ workspaceRoot, patch })
+      for (const target of targets) touched.add(target)
+    }
+
+    if (touched.size > 0) {
+      const result = runtimeModule.autoCompileNarrative({ workspaceRoot, touched: [...touched] })
+      messages.push(result.markdown ?? JSON.stringify(result, null, 2))
+      const notice = runtimeModule.formatMarkdownQaUserNotice?.(result)
+      if (notice) messages.push(notice)
+      if (!result.ok) ok = false
+    }
+  }
+
   for (const target of deckTargets) {
     const result = await runtimeModule.runDeckQa({ workspaceRoot, file: target })
     messages.push(result.markdown ?? JSON.stringify(result, null, 2))
+    const notice = runtimeModule.formatArtifactQaUserNotice?.(result.report)
+    if (notice) messages.push(notice)
     if (!result.ok) ok = false
   }
 

package/plugins/revela/mcp/revela-server.ts

@@ -22,9 +22,17 @@ type RuntimeModule = {
   designActivate(input: any): any
   designCreate(input: any): any
   designValidate(input: any): any
+  designDraftCreate(input: any): any
+  designDraftValidate(input: any): any
+  designDraftInstall(input: any): any
   domainList(): any
   domainRead(input?: any): any
   domainActivate(input: any): any
+  domainCreate(input: any): any
+  domainValidate(input: any): any
+  domainDraftCreate(input: any): any
+  domainDraftValidate(input: any): any
+  domainDraftInstall(input: any): any
   storyRead(input?: any): any
   reviewDeckRead(input: any): Promise<any>
   reviewDeckOpen(input: any): Promise<any>
@@ -32,6 +40,10 @@ type RuntimeModule = {
   researchSave(input: any): any
   evaluateResearchFindings(input: any): any
   bindResearchFindings(input: any): any
+  prepareLocalMaterials(input: any): Promise<any>
+  extractMaterial(input: any): Promise<any>
+  recordMaterialReview(input: any): any
+  checkMaterialIntake(input: any): any
 }
 
 type MessageMode = "framed" | "raw"
@@ -134,6 +146,35 @@ const tools = [
     description: "Validate a local Revela design package.",
     inputSchema: objectSchema({ name: requiredStringProp("Design name to validate.") }, ["name"]),
   },
+  {
+    name: "revela_design_draft_create",
+    description: "Create and validate a workspace-local Revela design draft package.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Design name in kebab-case."),
+      base: stringProp("Optional base design used as structural scaffold."),
+      designMd: requiredStringProp("Complete DESIGN.md content."),
+      previewHtml: requiredStringProp("Complete preview.html content."),
+      overwrite: booleanProp("Whether to replace an existing workspace draft. Defaults to false."),
+    }, ["name", "designMd", "previewHtml"]),
+  },
+  {
+    name: "revela_design_draft_validate",
+    description: "Validate a workspace-local Revela design draft package.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Design draft name to validate."),
+    }, ["name"]),
+  },
+  {
+    name: "revela_design_draft_install",
+    description: "Install a validated workspace-local Revela design draft into the user-level design registry.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Design draft name to install."),
+      overwrite: booleanProp("Whether to replace an existing user-level design package. Defaults to false."),
+    }, ["name"]),
+  },
   {
     name: "revela_domain_list",
     description: "List installed Revela narrative domains and the active domain.",
@@ -149,6 +190,47 @@ const tools = [
     description: "Activate a Revela narrative domain for future narrative authoring guidance.",
     inputSchema: objectSchema({ name: requiredStringProp("Domain name to activate.") }, ["name"]),
   },
+  {
+    name: "revela_domain_create",
+    description: "Create and validate a local Revela narrative domain package from complete INDUSTRY.md content.",
+    inputSchema: objectSchema({
+      name: requiredStringProp("Domain name in kebab-case."),
+      domainMd: requiredStringProp("Complete INDUSTRY.md content."),
+      overwrite: booleanProp("Whether to replace an existing local domain package. Defaults to false."),
+    }, ["name", "domainMd"]),
+  },
+  {
+    name: "revela_domain_validate",
+    description: "Validate a local Revela narrative domain package.",
+    inputSchema: objectSchema({ name: requiredStringProp("Domain name to validate.") }, ["name"]),
+  },
+  {
+    name: "revela_domain_draft_create",
+    description: "Create and validate a workspace-local Revela narrative domain draft package.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Domain name in kebab-case."),
+      domainMd: requiredStringProp("Complete INDUSTRY.md content."),
+      overwrite: booleanProp("Whether to replace an existing workspace draft. Defaults to false."),
+    }, ["name", "domainMd"]),
+  },
+  {
+    name: "revela_domain_draft_validate",
+    description: "Validate a workspace-local Revela narrative domain draft package.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Domain draft name to validate."),
+    }, ["name"]),
+  },
+  {
+    name: "revela_domain_draft_install",
+    description: "Install a validated workspace-local Revela narrative domain draft into the user-level domain registry.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Domain draft name to install."),
+      overwrite: booleanProp("Whether to replace an existing user-level domain package. Defaults to false."),
+    }, ["name"]),
+  },
   {
     name: "revela_story_read",
     description: "Read a deterministic Revela Story map and optional Markdown view from the canonical narrative vault without mutating files.",
@@ -209,6 +291,43 @@ const tools = [
       evidenceId: stringProp("Optional canonical evidence node id override."),
     }, ["findingsFile"]),
   },
+  {
+    name: "revela_prepare_local_materials",
+    description: "Scan local workspace source materials, create/update the material-intake registry, and optionally extract Office/PDF files into read views.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      path: stringProp("Optional workspace-relative subdirectory to scan."),
+      maxDepth: numberProp("Maximum scan depth. Defaults to 2."),
+      autoExtract: booleanProp("Whether to extract Office/PDF sources during prepare. Defaults to true."),
+    }),
+  },
+  {
+    name: "revela_extract_document_materials",
+    description: "Extract text, manifest, read view, and embedded images from a workspace document. Supports pdf, pptx, docx, and xlsx.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      file: requiredStringProp("Workspace-relative source file path."),
+    }, ["file"]),
+  },
+  {
+    name: "revela_record_material_review",
+    description: "Record that an LLM has read extracted local material and decided what was merged, deferred, ignored, or left as a gap.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      sourcePath: requiredStringProp("Workspace-relative source file path."),
+      reviewedPaths: arrayProp("Workspace-relative extracted paths actually reviewed."),
+      reviewSummary: requiredStringProp("Concise summary of the reviewed material."),
+      narrativeDecisions: arrayObjectProp("Narrative decisions with kind, optional target, and rationale."),
+    }, ["sourcePath", "reviewedPaths", "reviewSummary", "narrativeDecisions"]),
+  },
+  {
+    name: "revela_check_material_intake",
+    description: "Check whether scanned Office/PDF sources were extracted and reviewed before being treated as narrative intake.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      strictness: enumProp(["authoring", "readiness", "render"], "Check strictness."),
+    }),
+  },
 ]
 
 let runtimePromise: Promise<RuntimeModule> | undefined
@@ -278,9 +397,17 @@ async function callTool(name: string, args: any): Promise<any> {
   if (name === "revela_design_activate") return r.designActivate(args)
   if (name === "revela_design_create") return r.designCreate(args)
   if (name === "revela_design_validate") return r.designValidate(args)
+  if (name === "revela_design_draft_create") return r.designDraftCreate(args)
+  if (name === "revela_design_draft_validate") return r.designDraftValidate(args)
+  if (name === "revela_design_draft_install") return r.designDraftInstall(args)
   if (name === "revela_domain_list") return r.domainList()
   if (name === "revela_domain_read") return r.domainRead(args)
   if (name === "revela_domain_activate") return r.domainActivate(args)
+  if (name === "revela_domain_create") return r.domainCreate(args)
+  if (name === "revela_domain_validate") return r.domainValidate(args)
+  if (name === "revela_domain_draft_create") return r.domainDraftCreate(args)
+  if (name === "revela_domain_draft_validate") return r.domainDraftValidate(args)
+  if (name === "revela_domain_draft_install") return r.domainDraftInstall(args)
   if (name === "revela_story_read") return r.storyRead(args)
   if (name === "revela_review_deck_read") return r.reviewDeckRead(args)
   if (name === "revela_review_deck_open") return r.reviewDeckOpen(args)
@@ -288,6 +415,10 @@ async function callTool(name: string, args: any): Promise<any> {
   if (name === "revela_research_save") return r.researchSave(args)
   if (name === "revela_evaluate_research_findings") return r.evaluateResearchFindings(args)
   if (name === "revela_bind_research_findings") return r.bindResearchFindings(args)
+  if (name === "revela_prepare_local_materials") return r.prepareLocalMaterials(args)
+  if (name === "revela_extract_document_materials") return r.extractMaterial(args)
+  if (name === "revela_record_material_review") return r.recordMaterialReview(args)
+  if (name === "revela_check_material_intake") return r.checkMaterialIntake(args)
   throw new Error(`Unknown tool: ${name}`)
 }
 
@@ -315,6 +446,10 @@ function booleanProp(description: string) {
   return { type: "boolean", description }
 }
 
+function numberProp(description: string) {
+  return { type: "number", description }
+}
+
 function enumProp(values: string[], description: string) {
   return { type: "string", enum: values, description }
 }
@@ -323,6 +458,23 @@ function arrayProp(description: string) {
   return { type: "array", items: { type: "string" }, description }
 }
 
+function arrayObjectProp(description: string) {
+  return {
+    type: "array",
+    description,
+    items: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: ["merged", "gap", "ignored", "deferred"] },
+        target: { type: "string" },
+        rationale: { type: "string" },
+      },
+      required: ["kind", "rationale"],
+      additionalProperties: false,
+    },
+  }
+}
+
 function writeMessage(message: any, mode: MessageMode = activeResponseMode): void {
   activeResponseMode = mode
   const body = JSON.stringify(message)

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

@@ -25,10 +25,12 @@ Design changes are visual/artifact-level unless they change claim meaning, evide
 
 When the user asks to create a new design, use `starter` as the default base design unless they specify another base. Interview the user before saving anything: collect visual references such as images, webpages, brands, decks, or text descriptions, plus must-have and must-avoid constraints. Summarize the design brief and visual schema, then wait for the user to confirm before creating files.
 
-After confirmation, read the base design with `revela_design_read`. Generate complete `DESIGN.md` and complete `preview.html` content, then call `revela_design_create`. For edits to an existing design, read the existing design first, preserve useful layout/component coverage, and call `revela_design_create` with `overwrite: true` only after the user confirms the edit brief. Always call `revela_design_validate` after creation or overwrite.
+After confirmation, read the base design with `revela_design_read`. Generate complete `DESIGN.md` and complete `preview.html` content, then call `revela_design_draft_create` to save a workspace-local draft under `.revela/drafts/designs/<name>/`. Always call `revela_design_draft_validate` after draft creation or overwrite. The direct registry tools `revela_design_create` and `revela_design_validate` remain available for existing workflows, but Codex design authoring should use the draft workflow before install.
+
+Install the draft globally only after the user confirms the validated draft should be installed. Call `revela_design_draft_install` to copy the draft into the user-level design registry. If a user-level design already exists, pass `overwrite: true` only after the user confirms replacement. In sandboxed Codex sessions, the install step may require permission to write Revela user config under `~/.config/revela`.
 
 `DESIGN.md` must include frontmatter with `name`, `description`, `author`, and `version`, plus valid marker blocks for `@design:foundation`, `@design:rules`, at least one `@layout`, and at least one `@component`.
 
 `preview.html` must be self-contained and directly openable in a browser. Every `<section class="slide">` must include `slide-qa` and exactly one direct `.slide-canvas` child. Every direct `.slide-canvas` is the fixed 1920px x 1080px export surface and must use explicit CSS with `width: 1920px` and `height: 1080px`; `.slide` may remain a viewport/navigation wrapper. Include a cover slide with `data-slide-role="cover"`, a closing slide with `data-slide-role="closing"`, and a visible sample for every `@component:*` using `data-preview-component="<component-name>"`.
 
-Do not automatically activate a newly created design. Report the saved path and tell the user they can activate it with `revela_design_activate`.
+Do not automatically activate a newly created design. Do not automatically activate a newly installed design. Report the draft path, installed path when installed, and tell the user they can activate it with `revela_design_activate`.

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

@@ -5,7 +5,7 @@ description: Use or switch Revela narrative domain guidance in Codex for init, r
 
 # Revela Domain
 
-Use this skill when the user asks about Revela domains, wants domain-specific narrative guidance, or asks to switch the active domain.
+Use this skill when the user asks about Revela domains, wants domain-specific narrative guidance, asks to switch the active domain, or asks to create a new domain.
 
 ## Workflow
 
@@ -16,3 +16,15 @@ Use this skill when the user asks about Revela domains, wants domain-specific na
 5. Do not treat domain guidance as evidence, source material, or proof for factual claims.
 
 Domain changes are narrative-framing preferences. They do not rewrite existing claims, evidence boundaries, artifacts, or deck plans unless the user asks for those updates.
+
+## Creating Or Editing Domains
+
+When the user asks to create a new domain, interview the user before saving anything. Collect the communication context, typical audience, decisions, claim patterns, evidence expectations, common objections, risks, research-gap heuristics, terminology to use, and terminology to avoid. Summarize the domain brief, then wait for the user to confirm before creating files.
+
+After confirmation, generate complete `INDUSTRY.md` content and call `revela_domain_draft_create` to save a workspace-local draft under `.revela/drafts/domains/<name>/`. Always call `revela_domain_draft_validate` after draft creation or overwrite.
+
+Install the draft globally only after the user confirms the validated draft should be installed. Call `revela_domain_draft_install` to copy the draft into the user-level domain registry. If a user-level domain already exists, pass `overwrite: true` only after the user confirms replacement. In sandboxed Codex sessions, the install step may require permission to write Revela user config under `~/.config/revela`.
+
+`INDUSTRY.md` must include frontmatter with `name`, `description`, `author`, and `version`, followed by concrete narrative guidance for audience framing, decision framing, claim standards, evidence expectations, objection/risk handling, and research-gap interpretation.
+
+Do not automatically activate a newly installed domain. Report the draft path, installed path when installed, and tell the user they can activate it with `revela_domain_activate`.

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

@@ -18,14 +18,24 @@ Use this skill when the user asks to start Revela, initialize the workspace, ing
 
 ## 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.
+1. Call `revela_prepare_local_materials` first. Treat scan results as an intake registry and task list, not as source content.
+2. For any registry entry with `requiresExtraction: true`, do not read the original Office/PDF file directly for narrative intake. Use the returned `allowedReadPath` / `read_view_path`; if missing, call `revela_extract_document_materials` first.
+3. Prefer local source materials first: Markdown, text, CSV, PDFs, Office files, existing `researches/`, existing `revela-narrative/`, `deck-plan/`, and `decks/`.
+4. After reading extracted material views, call `revela_record_material_review` for each considered Office/PDF source. Record what was merged, deferred, ignored, or left as a gap.
+5. 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.
+6. If `revela-narrative/` exists, call `revela_markdown_qa` and `revela_compile_narrative`.
+7. If the narrative vault is missing, create the initial `revela-narrative/` Markdown nodes directly with valid frontmatter and plain wikilink relations.
+8. Evidence nodes must preserve source, quote/snippet, support scope, unsupported scope, caveat, and strength before being treated as support.
+9. After writing narrative Markdown, call `revela_markdown_qa` and `revela_compile_narrative` again.
+10. Before the final report, call `revela_check_material_intake` and surface any warnings about scanned-but-unextracted, extracted-but-unreviewed, unsupported, failed, or text-only sources.
+11. End with a concise init report: local materials found, active domain, narrative graph status, material intake status, open gaps, Markdown QA status, and next command/action.
+
+## Material Intake Rules
+
+- Scan results only prove that files exist; they do not prove file content.
+- For `.docx`, `.pptx`, `.xlsx`, and `.pdf`, read the extracted `read_view_path` instead of using Codex/textutil/raw reads of the original file.
+- Extracted images are candidate materials only. Do not interpret them as evidence unless image meaning is explicitly reviewed or supplied by the user.
+- If a user explicitly asks for text-only inspection, report it as degraded intake and do not treat it as complete source review.
 
 ## Markdown Rules
 

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

@@ -0,0 +1,33 @@
+---
+name: revela-upgrade
+description: Guide Revela Codex plugin upgrade, update, version, and reinstall requests while checking the running runtime version first.
+---
+
+# Revela Upgrade
+
+Use this skill when the user asks how to upgrade, update, reinstall, or check the version of the Revela Codex plugin.
+
+## Workflow
+
+1. Call `revela_doctor` first to inspect the currently running Revela runtime version.
+2. Report the current runtime version from doctor output. Do not check the latest version online unless the user explicitly asks you to look it up.
+3. Explain that the Codex Git marketplace ref and `.mcp.json` npm runtime pin are published together for the same Revela release.
+4. If the user wants a fixed release, guide them through removing the installed plugin, removing the marketplace entry, adding the desired release tag, then adding the plugin again:
+
+```bash
+codex plugin remove revela@revela
+codex plugin marketplace remove revela
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref vX.Y.Z
+codex plugin add revela@revela
+```
+
+5. If the user already tracks a branch or movable ref, guide them through upgrading the marketplace clone, then re-adding the plugin:
+
+```bash
+codex plugin marketplace upgrade revela
+codex plugin add revela@revela
+```
+
+6. Tell the user to start a new Codex thread after upgrading so Codex reloads the Revela skills, MCP tools, hooks, and runtime pin.
+
+Do not run `codex plugin remove`, `codex plugin marketplace remove`, `codex plugin marketplace add`, `codex plugin marketplace upgrade`, or `codex plugin add` unless the user explicitly asks you to perform the upgrade or reinstall.