@cyber-dash-tech/revela 0.17.8 → 0.17.10

package/README.md

@@ -2,7 +2,7 @@
 
 **English** | [中文](README.zh-CN.md)
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-611%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-615%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="560" />
@@ -34,11 +34,13 @@ To install globally, add the same entry to `~/.config/opencode/opencode.json`.
 Install Revela through the Codex Git marketplace:
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.8
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.10
 codex plugin add revela@revela
 ```
 
-Install from the full repository ref. Do not use a sparse checkout limited to `plugins/revela`; the Codex plugin resolves the shared runtime, built-in designs, and domains from the repository snapshot.
+The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.17.10 mcp` so npm can fetch the published package and its dependencies.
+
+You do not need to run `bun install` inside the Codex marketplace clone.
 
 Start a new Codex thread after installing so Codex loads the Revela skills, MCP tools, and hooks.
 
@@ -89,55 +91,61 @@ Use these prompts in Codex from the workspace that contains your source material
 1. Choose the narrative domain before authoring so Revela frames the audience, decision, risks, and objections for your context.
 
 ```text
-Use Revela to list available domains, switch to the consulting domain, and use that framing for the narrative workflow.
+revela, use consulting as the domain.
 ```
 
 2. Choose the deck design before rendering so generated artifacts use the intended visual language.
 
 ```text
-Use Revela to list available designs, switch to the summit design, and use it for the next deck.
+revela, use summit as the design.
 ```
 
 3. Initialize the narrative from local materials. Init grounds the narrative in the workspace and surfaces gaps; it does not replace the research step.
 
 ```text
-Use Revela to initialize this workspace. Read the local materials, identify the audience, decision, thesis, claims, existing evidence, risks, objections, and gaps, then create or update the narrative vault.
+revela, help me init this workspace from the local materials.
 ```
 
 4. Research the gaps and bind only source-supported evidence into the narrative.
 
 ```text
-Use Revela research to inspect the current narrative gaps, derive research targets, gather or evaluate findings, save research under researches/, and bind only source-supported evidence back into the narrative vault.
+revela, research the current gaps and bind only source-supported evidence.
 ```
 
 5. Read Story before rendering to inspect the claim flow, evidence support, caveats, unsupported scope, and open gaps.
 
 ```text
-Use Revela Story to show the current claim flow, evidence support, caveats, unsupported scope, and open gaps.
+revela, show me the Story before we make the deck.
+```
+
+6. Create or update the deck plan before generating HTML so slide order, chapter structure, evidence trace, caveats, and visual intent are explicit.
+
+```text
+revela, create or update the deck plan before generating HTML.
 ```
 
-6. Make an HTML deck from the canonical narrative and deck plan.
+7. Make an HTML deck from the current deck plan and canonical narrative.
 
 ```text
-Use Revela to make a deck from the current narrative. Create or update the deck plan, generate an HTML deck under decks/, run deck QA, and repair hard QA errors.
+revela, make the deck from the current deck plan and narrative.
 ```
 
-7. Review the generated deck for traceability, diagnostics, and targeted edits.
+8. Review the generated deck for traceability, diagnostics, and targeted edits.
 
 ```text
-Use Revela to review the generated deck. Open the Review UI for the HTML deck and also summarize diagnostics.
+revela, review the generated deck.
 ```
 
-8. Export a PDF after deck QA passes.
+9. Export a PDF after deck QA passes.
 
 ```text
-Use Revela to export the deck to PDF.
+revela, export the deck to PDF.
 ```
 
-9. Export an editable PPTX after deck QA passes.
+10. Export an editable PPTX after deck QA passes.
 
 ```text
-Use Revela to export the deck to PPTX.
+revela, export the deck to PPTX.
 ```
 
 ## Review A Deck

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | **中文**
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-611%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-615%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="560" />
@@ -34,11 +34,13 @@ Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材
 通过 Codex Git marketplace 安装 Revela：
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.8
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.10
 codex plugin add revela@revela
 ```
 
-请从完整仓库 ref 安装。不要使用仅包含 `plugins/revela` 的 sparse checkout；Codex plugin 会从仓库快照中解析 shared runtime、内置 designs 和 domains。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.17.10 mcp`，由 npm 获取已发布 package 及其 dependencies。
+
+不需要在 Codex marketplace clone 里运行 `bun install`。
 
 安装后开启一个新的 Codex thread，让 Codex 加载 Revela 的 skills、MCP tools 和 hooks。
 
@@ -89,55 +91,61 @@ Domain 提供特定场景的叙事 guidance，例如 consulting、product 或 in
 1. 先选择 domain，让 Revela 按你的沟通场景 framing 受众、决策、风险和潜在质疑。
 
 ```text
-用 Revela 列出可用 domains，切换到 consulting domain，并把这个 framing 用在后续 narrative workflow 中。
+revela，use consulting as domain.
 ```
 
 2. 再选择 design，让后续生成的 deck 使用指定视觉风格。
 
 ```text
-用 Revela 列出可用 designs，切换到 summit design，并把它用于下一次 deck 生成。
+revela，use summit as design.
 ```
 
 3. 从本地材料初始化 narrative。Init 负责基于 workspace 做 grounding 并暴露 gap；它不替代 research 步骤。
 
 ```text
-用 Revela 初始化这个 workspace。读取本地材料，识别受众、决策目标、thesis、claims、已有 evidence、risks、objections 和 gaps，然后创建或更新 narrative vault。
+revela，帮我 init 这个 workspace，先读本地材料。
 ```
 
 4. 针对 gap 做 research，并且只把来源明确支持的 evidence 绑定回 narrative。
 
 ```text
-用 Revela research 检查当前 narrative gaps，生成 research targets，收集或评估 findings，把 research 保存到 researches/，并且只把有来源支撑的 evidence 绑定回 narrative vault。
+revela，research 当前 gaps，只绑定 source-supported evidence。
 ```
 
 5. 生成 deck 前先读 Story，检查 claim flow、证据支撑、caveats、unsupported scope 和 open gaps。
 
 ```text
-用 Revela Story 展示当前 claim flow、evidence support、caveats、unsupported scope 和 open gaps。
+revela，先给我看 Story，再 make deck。
+```
+
+6. 先创建或更新 deck plan，明确 slide 顺序、章节结构、evidence trace、caveats 和 visual intent，再生成 HTML。
+
+```text
+revela，生成 HTML 前先 create or update deck plan。
 ```
 
-6. 从 canonical narrative 和 deck plan 生成 HTML deck。
+7. 基于当前 deck plan 和 canonical narrative 生成 HTML deck。
 
 ```text
-用 Revela 基于当前 narrative 制作 deck。创建或更新 deck plan，在 decks/ 下生成 HTML deck，运行 deck QA，并修复 hard QA errors。
+revela，基于当前 deck plan 和 narrative make deck。
 ```
 
-7. Review 生成后的 deck，检查 traceability、diagnostics，并做定向修改。
+8. Review 生成后的 deck，检查 traceability、diagnostics，并做定向修改。
 
 ```text
-用 Revela review 生成好的 deck。打开这个 HTML deck 的 Review UI，并总结 diagnostics。
+revela，review 生成好的 deck。
 ```
 
-8. QA 通过后导出 PDF。
+9. QA 通过后导出 PDF。
 
 ```text
-用 Revela 把 deck 导出为 PDF。
+revela，把 deck export 成 PDF。
 ```
 
-9. QA 通过后导出可编辑 PPTX。
+10. QA 通过后导出可编辑 PPTX。
 
 ```text
-用 Revela 把 deck 导出为 PPTX。
+revela，把 deck export 成 PPTX。
 ```
 
 ## Review Deck

package/lib/log.ts

@@ -1,28 +1,39 @@
-import { Logger } from "tslog"
-
 /**
- * Revela structured logger (tslog).
- *
- * Log levels:
- *   0 = silly, 1 = trace, 2 = debug, 3 = info, 4 = warn, 5 = error, 6 = fatal
- *
- * Set REVELA_DEBUG=1 to enable debug-level output (minLevel 2).
- * Default minLevel is 3 (info) in production.
+ * Revela logger facade.
+ * Keep this module dependency-free so lightweight runtime tools can load from
+ * Codex Git marketplace checkouts that do not have package dependencies
+ * installed. Logging is intentionally silent by default because Revela often
+ * runs over stdio protocols where stderr noise is user-visible.
  */
-const minLevel = process.env.REVELA_DEBUG === "1" ? 2 : 3
+type LogMethod = (message?: unknown, ...args: unknown[]) => void
+
+export interface RevelaLogger {
+  silly: LogMethod
+  trace: LogMethod
+  debug: LogMethod
+  info: LogMethod
+  warn: LogMethod
+  error: LogMethod
+  fatal: LogMethod
+  getSubLogger(input?: { name?: string }): RevelaLogger
+}
+
+const noop: LogMethod = () => {}
+
+function createNoopLogger(_name = "revela"): RevelaLogger {
+  return {
+    silly: noop,
+    trace: noop,
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    fatal: noop,
+    getSubLogger: (input?: { name?: string }) => createNoopLogger(input?.name),
+  }
+}
 
-export const log = new Logger({
-  name: "revela",
-  minLevel,
-  type: "json",
-  hideLogPositionForProduction: true,
-  overwrite: {
-    transportJSON: (_logObj: unknown) => {
-      // Silenced: revela runs as an OpenCode plugin; writing to stderr
-      // pollutes the host terminal. Logs are intentionally suppressed.
-    },
-  },
-})
+export const log: RevelaLogger = createNoopLogger()
 
 /**
  * Create a child logger for a specific sub-module.

package/lib/runtime/index.ts

@@ -7,14 +7,10 @@ import { computeNarrativeHash } from "../narrative-state/hash"
 import { compileNarrativeVault } from "../narrative-vault/compile"
 import { runNarrativeMarkdownQa, type MarkdownQaOptions } from "../narrative-vault/markdown-qa"
 import { readDeckPlanArtifact } from "../narrative-state/deck-plan-artifact"
-import { exportToPdf } from "../pdf/export"
-import { exportToPptx } from "../pptx/export"
-import { assertExportQAPassed } from "../qa/export-gate"
-import { formatArtifactQAReport, runArtifactQA } from "../qa/artifact"
 import { extractDesignClasses } from "../design/designs"
 import { recordRenderedArtifact, workspaceRelative } from "../workspace-state/rendered-artifacts"
+import type { ReviewDeckOpenInput, ReviewDeckReadInput } from "./review"
 export { bindResearchFindings, evaluateResearchFindings, researchSave, researchTargets } from "./research"
-export { reviewDeckOpen, reviewDeckRead } from "./review"
 export { storyRead } from "./story"
 
 export interface RuntimeWorkspaceInput {
@@ -91,6 +87,7 @@ export function createDeckFoundation(input: RuntimeDeckFoundationInput) {
 }
 
 export async function runDeckQa(input: RuntimeFileInput) {
+  const { formatArtifactQAReport, runArtifactQA } = await import("../qa/artifact")
   const workspaceRoot = root(input.workspaceRoot)
   const filePath = resolve(workspaceRoot, input.file)
   let vocabulary
@@ -113,6 +110,8 @@ export async function runDeckQa(input: RuntimeFileInput) {
 }
 
 export async function exportPdf(input: RuntimeFileInput) {
+  const { exportToPdf } = await import("../pdf/export")
+  const { assertExportQAPassed } = await import("../qa/export-gate")
   const workspaceRoot = root(input.workspaceRoot)
   const filePath = resolve(workspaceRoot, input.file)
   await assertExportQAPassed(filePath, { workspaceRoot })
@@ -127,6 +126,8 @@ export async function exportPdf(input: RuntimeFileInput) {
 }
 
 export async function exportPptx(input: RuntimeFileInput & { speakerNotes?: Array<string | null | undefined> }) {
+  const { exportToPptx } = await import("../pptx/export")
+  const { assertExportQAPassed } = await import("../qa/export-gate")
   const workspaceRoot = root(input.workspaceRoot)
   const filePath = resolve(workspaceRoot, input.file)
   await assertExportQAPassed(filePath, { workspaceRoot })
@@ -140,6 +141,16 @@ export async function exportPptx(input: RuntimeFileInput & { speakerNotes?: Arra
   return { ok: true, ...result }
 }
 
+export async function reviewDeckRead(input: ReviewDeckReadInput) {
+  const review = await import("./review")
+  return review.reviewDeckRead(input)
+}
+
+export async function reviewDeckOpen(input: ReviewDeckOpenInput) {
+  const review = await import("./review")
+  return review.reviewDeckOpen(input)
+}
+
 export function designList() {
   seedBuiltinDesigns()
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.17.8",
+  "version": "0.17.10",
   "description": "OpenCode plugin for trusted narrative artifacts from local sources, research, and evidence",
   "type": "module",
   "main": "./index.ts",

package/plugins/revela/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "revela",
-  "version": "0.1.0+codex.20260523122203",
+  "version": "0.1.0+codex.20260524121829",
   "description": "Use Revela in Codex to build trusted, traceable narrative decision artifacts from local sources and research.",
   "author": {
     "name": "cyber-dash-tech",

package/plugins/revela/.mcp.json

@@ -1,11 +1,8 @@
 {
   "mcpServers": {
     "revela": {
-      "command": "bun",
-      "args": [
-        "--eval",
-        "const fs = await import('fs');\nconst path = await import('path');\nconst { pathToFileURL } = await import('url');\nconst candidates = [];\nconst home = process.env.HOME || '';\nconst marketplaceNames = ['revela', 'revela-local'];\ncandidates.push(path.resolve(process.cwd(), 'bin/revela.ts'));\nconst configPath = path.join(home, '.codex', 'config.toml');\nif (fs.existsSync(configPath)) {\n  const text = fs.readFileSync(configPath, 'utf-8');\n  const sections = text.split(/\\n(?=\\s*\\[)/);\n  for (const marketplaceName of marketplaceNames) {\n    const section = sections.find((item) => item.trimStart().startsWith(`[marketplaces.${marketplaceName}]`));\n    const match = section?.match(/^\\s*source\\s*=\\s*\"([^\"]+)\"/m);\n    if (match) candidates.push(path.join(match[1], 'bin/revela.ts'));\n  }\n}\nfor (const marketplaceName of marketplaceNames) {\n  const cacheRoot = path.join(home, '.codex', 'plugins', 'cache', marketplaceName, 'revela');\n  if (fs.existsSync(cacheRoot)) {\n    for (const version of fs.readdirSync(cacheRoot).sort().reverse()) candidates.push(path.join(cacheRoot, version, 'bin/revela.ts'));\n  }\n}\nconst cli = candidates.find((candidate) => fs.existsSync(candidate));\nif (!cli) {\n  console.error(`Could not locate Revela CLI. Checked: ${candidates.join(', ')}`);\n  process.exit(1);\n}\nprocess.env.REVELA_CLI_COMMAND = 'mcp';\nawait import(pathToFileURL(cli).href);"
-      ]
+      "command": "npx",
+      "args": ["-y", "@cyber-dash-tech/revela@0.17.10", "mcp"]
     }
   }
 }

package/plugins/revela/mcp/runtime-resolver.ts

@@ -33,14 +33,27 @@ export function resolveRevelaRuntime(options: ResolveRuntimeOptions): ResolveRun
 
   const marketplaceName = marketplaceNameFromPluginRoot(pluginRoot)
   if (marketplaceName) {
-    const source = marketplaceSourceFromCodexConfig(marketplaceName, options.homeDir ?? env.HOME)
+    const homeDir = options.homeDir ?? env.HOME
+    const source = marketplaceSourceFromCodexConfig(marketplaceName, homeDir)
     if (source) {
-      const result = runtimeAt(source, "codex-marketplace", diagnostics)
-      if (result.ok) return result
-      diagnostics.push(`Marketplace ${marketplaceName} source did not contain lib/runtime/index.ts: ${source}`)
+      if (looksLikeLocalPath(source)) {
+        const result = runtimeAt(source, "codex-marketplace", diagnostics)
+        if (result.ok) return result
+        diagnostics.push(`Marketplace ${marketplaceName} local source did not contain lib/runtime/index.ts: ${source}`)
+      } else {
+        diagnostics.push(`Marketplace ${marketplaceName} source is not a local path: ${source}`)
+      }
     } else {
       diagnostics.push(`Marketplace ${marketplaceName} was not found in Codex config.`)
     }
+    const clone = marketplaceCloneRoot(marketplaceName, homeDir)
+    if (clone) {
+      const result = fullRepoRuntimeAt(clone, "codex-marketplace", diagnostics)
+      if (result.ok) return result
+      diagnostics.push(`Marketplace ${marketplaceName} clone did not contain a complete Revela runtime: ${clone}`)
+    } else {
+      diagnostics.push(`Marketplace ${marketplaceName} clone was not found in Codex temp marketplaces.`)
+    }
   } else {
     diagnostics.push(`Could not infer marketplace name from plugin root: ${pluginRoot}`)
   }
@@ -60,6 +73,17 @@ function runtimeAt(root: string, source: ResolveRuntimeResult["source"], diagnos
     : { ok: false, source: "missing", diagnostics }
 }
 
+function fullRepoRuntimeAt(root: string, source: ResolveRuntimeResult["source"], diagnostics: string[]): ResolveRuntimeResult {
+  const repoRoot = resolve(root)
+  const runtimePath = join(repoRoot, "lib", "runtime", "index.ts")
+  const hasRuntime = existsSync(runtimePath)
+  const hasDesigns = existsSync(join(repoRoot, "designs"))
+  const hasDomains = existsSync(join(repoRoot, "domains"))
+  return hasRuntime && hasDesigns && hasDomains
+    ? { ok: true, repoRoot, runtimePath, source, diagnostics }
+    : { ok: false, source: "missing", diagnostics }
+}
+
 function findSourceCheckoutRoot(pluginRoot: string): string | undefined {
   let current = resolve(pluginRoot)
   for (let i = 0; i < 6; i++) {
@@ -95,6 +119,16 @@ function marketplaceSourceFromCodexConfig(marketplaceName: string, homeDir: stri
   return match?.[1]
 }
 
+function marketplaceCloneRoot(marketplaceName: string, homeDir: string | undefined): string | undefined {
+  if (!homeDir) return undefined
+  const candidate = join(homeDir, ".codex", ".tmp", "marketplaces", marketplaceName)
+  return existsSync(candidate) ? candidate : undefined
+}
+
+function looksLikeLocalPath(source: string): boolean {
+  return !/^[a-z][a-z0-9+.-]*:\/\//i.test(source)
+}
+
 function sectionBody(text: string, sectionName: string): string | undefined {
   const lines = text.split(/\r?\n/)
   const header = `[${sectionName}]`

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

@@ -18,12 +18,24 @@ Use this skill when the user asks to make, generate, or update a Revela deck.
 
 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.
+3. Call `revela_read_deck_plan` as the required deck-plan preflight before any HTML generation.
+4. If `deck-plan/` is missing or incomplete, author or repair `deck-plan/index.md` and `deck-plan/slides/*.md` before calling `revela_create_deck_foundation`.
+5. Report deck-plan diagnostics before artifact generation, including stale narrative hashes, missing slide projections, missing evidence trace, caveats, or malformed plan files.
+6. Do not start HTML generation from narrative alone unless the user explicitly asks for a throwaway diagnostic smoke deck.
+7. For new HTML files, call `revela_create_deck_foundation`.
+8. 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`.
+9. Patch slides into the foundation between Revela slide markers. Preserve positive 1-based `data-slide-index` values.
+10. Generate chapter by chapter. Keep the HTML valid after each write.
+11. After every HTML write, call `revela_run_deck_qa` and repair hard errors before review or export.
+
+## Generated Visual Assets
+
+- Codex may use the `imagegen` skill for deck-level visual assets when a slide's visual intent calls for an image or diagram and no suitable workspace/source asset exists.
+- Prefer `imagegen` for flow diagrams, framework diagrams, process visuals, system relationship maps, journey maps, before/after schematics, conceptual illustrations, abstract heroes, chapter dividers, background textures, non-evidence metaphor visuals, and visual drafts.
+- Do not use generated images for source evidence, factual screenshots, real people, real places, real products, logos, data charts, tables, or visuals that need verifiable factual accuracy.
+- If the visual needs exact editable text, precise data, axes, code, tables, or strict structure, build it with HTML/CSS, ECharts, or `data-table` instead of `imagegen`.
+- Generated images are artifact-level visuals only. Do not treat them as evidence, source materials, quote support, or factual proof.
+- If a generated image is referenced by deck HTML, move or copy the final asset into the workspace, preferably under `assets/<topic>/media/` or the project's existing asset directory. Deck HTML must reference a workspace-relative local path, never Codex's default generated-image path.
 
 ## QA Repair Loop
 

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

@@ -19,6 +19,15 @@ Use this skill when the user asks to review, inspect, diagnose, or refine a gene
 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.
 
+## Generated Visual Assets
+
+- For Review Comment or Apply Fix requests such as adding an image, replacing a cover visual, creating a concept illustration, making a media block visual, or turning a slide idea into a flow/framework diagram, Codex may use the `imagegen` skill.
+- Prefer `imagegen` for flow diagrams, framework diagrams, process visuals, system relationship maps, journey maps, before/after schematics, conceptual illustrations, abstract heroes, chapter dividers, background textures, non-evidence metaphor visuals, and visual drafts.
+- Do not use generated images for source evidence, factual screenshots, real people, real places, real products, logos, data charts, tables, or visuals that need verifiable factual accuracy. Use workspace/source assets instead, or report the missing asset.
+- If the visual needs exact editable text, precise data, axes, code, tables, or strict structure, patch the deck with HTML/CSS, ECharts, or `data-table` instead of `imagegen`.
+- Generated images are artifact-level visual patches only. Do not add them to evidence, source materials, narrative support, or factual trace.
+- If a generated image is referenced by deck HTML, move or copy the final asset into the workspace, preferably under `assets/<topic>/media/` or the project's existing asset directory. Deck HTML must reference a workspace-relative local path, never Codex's default generated-image path.
+
 ## QA Notes
 
 - `revela_review_deck_read` is read-only: it must not mutate deck HTML, `revela-narrative/`, `deck-plan/`, assets, or compatibility state.