@cyber-dash-tech/revela 0.17.8 → 0.17.9

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,7 +34,7 @@ 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.9
 codex plugin add revela@revela
 ```
 
@@ -89,55 +89,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. Make an HTML deck from the canonical narrative and deck plan.
+6. Create or update the deck plan before generating HTML so slide order, chapter structure, evidence trace, caveats, and visual intent are explicit.
 
 ```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, create or update the deck plan before generating HTML.
 ```
 
-7. Review the generated deck for traceability, diagnostics, and targeted edits.
+7. Make an HTML deck from the current deck plan and canonical narrative.
 
 ```text
-Use Revela to review the generated deck. Open the Review UI for the HTML deck and also summarize diagnostics.
+revela, make the deck from the current deck plan and narrative.
 ```
 
-8. Export a PDF after deck QA passes.
+8. Review the generated deck for traceability, diagnostics, and targeted edits.
 
 ```text
-Use Revela to export the deck to PDF.
+revela, review the generated deck.
 ```
 
-9. Export an editable PPTX after deck QA passes.
+9. Export a PDF after deck QA passes.
 
 ```text
-Use Revela to export the deck to PPTX.
+revela, export the deck to PDF.
+```
+
+10. Export an editable PPTX after deck QA passes.
+
+```text
+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,7 +34,7 @@ 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.9
 codex plugin add revela@revela
 ```
 
@@ -89,55 +89,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. 从 canonical narrative 和 deck plan 生成 HTML deck。
+6. 先创建或更新 deck plan，明确 slide 顺序、章节结构、evidence trace、caveats 和 visual intent，再生成 HTML。
 
 ```text
-用 Revela 基于当前 narrative 制作 deck。创建或更新 deck plan，在 decks/ 下生成 HTML deck，运行 deck QA，并修复 hard QA errors。
+revela，生成 HTML 前先 create or update deck plan。
 ```
 
-7. Review 生成后的 deck，检查 traceability、diagnostics，并做定向修改。
+7. 基于当前 deck plan 和 canonical narrative 生成 HTML deck。
 
 ```text
-用 Revela review 生成好的 deck。打开这个 HTML deck 的 Review UI，并总结 diagnostics。
+revela，基于当前 deck plan 和 narrative make deck。
 ```
 
-8. QA 通过后导出 PDF。
+8. Review 生成后的 deck，检查 traceability、diagnostics，并做定向修改。
 
 ```text
-用 Revela 把 deck 导出为 PDF。
+revela，review 生成好的 deck。
 ```
 
-9. QA 通过后导出可编辑 PPTX。
+9. QA 通过后导出 PDF。
 
 ```text
-用 Revela 把 deck 导出为 PPTX。
+revela，把 deck export 成 PDF。
+```
+
+10. QA 通过后导出可编辑 PPTX。
+
+```text
+revela，把 deck export 成 PPTX。
 ```
 
 ## Review Deck

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.17.8",
+  "version": "0.17.9",
   "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

@@ -4,7 +4,7 @@
       "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);"
+        "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 && !/^[a-z][a-z0-9+.-]*:\\/\\//i.test(match[1])) candidates.push(path.join(match[1], 'bin/revela.ts'));\n  }\n}\nfor (const marketplaceName of marketplaceNames) {\n  candidates.push(path.join(home, '.codex', '.tmp', 'marketplaces', marketplaceName, 'bin/revela.ts'));\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);"
       ]
     }
   }

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.