@cyber-dash-tech/revela 0.17.7 → 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-609%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,13 +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 main
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.9
 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.
 
-Use a release tag instead of `main` when you want a pinned install.
+Start a new Codex thread after installing so Codex loads the Revela skills, MCP tools, and hooks.
 
 ## Built-In Designs
 
@@ -84,11 +84,67 @@ In Codex, ask Revela to list or switch domains; the active domain guides narrati
 
 ## Quick Start
 
-Start with the local source materials and intent that should ground the communication. Revela identifies the audience, decision, claims, evidence, risks, objections, and gaps that shape the narrative.
+Use these prompts in Codex from the workspace that contains your source materials.
 
-When evidence is missing, use research to gather findings and bind only the supported parts back to the narrative. Before rendering, read the Story view to inspect the claim flow, evidence support, caveats, and open gaps.
+1. Choose the narrative domain before authoring so Revela frames the audience, decision, risks, and objections for your context.
 
-Make a deck or brief from the canonical narrative when the story is ready to present. Review the artifact with Insight to understand support and traceability, use Comment for targeted changes, and export to PDF or PPTX when you need a shareable file.
+```text
+revela, use consulting as the domain.
+```
+
+2. Choose the deck design before rendering so generated artifacts use the intended visual language.
+
+```text
+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
+revela, help me init this workspace from the local materials.
+```
+
+4. Research the gaps and bind only source-supported evidence into the narrative.
+
+```text
+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
+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.
+```
+
+7. Make an HTML deck from the current deck plan and canonical narrative.
+
+```text
+revela, make the deck from the current deck plan and narrative.
+```
+
+8. Review the generated deck for traceability, diagnostics, and targeted edits.
+
+```text
+revela, review the generated deck.
+```
+
+9. Export a PDF after deck QA passes.
+
+```text
+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-609%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,13 +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 main
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.9
 codex plugin add revela@revela
 ```
 
 请从完整仓库 ref 安装。不要使用仅包含 `plugins/revela` 的 sparse checkout；Codex plugin 会从仓库快照中解析 shared runtime、内置 designs 和 domains。
 
-如果需要固定版本，把 `main` 换成 release tag。
+安装后开启一个新的 Codex thread，让 Codex 加载 Revela 的 skills、MCP tools 和 hooks。
 
 ## 内置设计
 
@@ -84,11 +84,67 @@ Domain 提供特定场景的叙事 guidance，例如 consulting、product 或 in
 
 ## Quick Start
 
-从本地来源材料和沟通意图开始，让 Revela 识别受众、决策目标、论点、论据、风险、潜在质疑和信息缺口。
+在包含来源材料的 workspace 中打开 Codex，然后按下面步骤逐条发送 prompt。
 
-证据不足时，用 research 补充 findings，并只把被来源明确支持的部分绑定回 narrative。渲染前先阅读 Story view，检查 claim flow、证据支撑、caveat 和 open gap。
+1. 先选择 domain，让 Revela 按你的沟通场景 framing 受众、决策、风险和潜在质疑。
 
-当 story 已经适合呈现时，从 canonical narrative 生成 deck 或 brief。之后用 Insight 理解 artifact 的支撑关系和可追踪性，用 Comment 做定向修改，需要分享文件时再导出为 PDF 或 PPTX。
+```text
+revela，use consulting as domain.
+```
+
+2. 再选择 design，让后续生成的 deck 使用指定视觉风格。
+
+```text
+revela，use summit as design.
+```
+
+3. 从本地材料初始化 narrative。Init 负责基于 workspace 做 grounding 并暴露 gap；它不替代 research 步骤。
+
+```text
+revela，帮我 init 这个 workspace，先读本地材料。
+```
+
+4. 针对 gap 做 research，并且只把来源明确支持的 evidence 绑定回 narrative。
+
+```text
+revela，research 当前 gaps，只绑定 source-supported evidence。
+```
+
+5. 生成 deck 前先读 Story，检查 claim flow、证据支撑、caveats、unsupported scope 和 open gaps。
+
+```text
+revela，先给我看 Story，再 make deck。
+```
+
+6. 先创建或更新 deck plan，明确 slide 顺序、章节结构、evidence trace、caveats 和 visual intent，再生成 HTML。
+
+```text
+revela，生成 HTML 前先 create or update deck plan。
+```
+
+7. 基于当前 deck plan 和 canonical narrative 生成 HTML deck。
+
+```text
+revela，基于当前 deck plan 和 narrative make deck。
+```
+
+8. Review 生成后的 deck，检查 traceability、diagnostics，并做定向修改。
+
+```text
+revela，review 生成好的 deck。
+```
+
+9. QA 通过后导出 PDF。
+
+```text
+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.7",
+  "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.