@cyber-dash-tech/revela 0.18.5 → 0.18.6

package/README.md

@@ -34,7 +34,7 @@ To install globally, add the same entry to `~/.config/opencode/opencode.json`.
 Requirements:
 
 - The Codex CLI must be installed and the `codex` command must be available in your shell.
-- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.18.5 mcp` to start the MCP server.
+- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.18.6 mcp` to start the MCP server.
 - For interactive Review Apply actions, `codex exec` must also work because the Review UI uses it after saved comments are applied.
 
 Optional preflight:
@@ -55,17 +55,17 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 Install Revela through the Codex Git marketplace:
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.5
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.6
 codex plugin add revela@revela
 ```
 
-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.18.5 mcp` so npm can fetch the published package and its dependencies.
+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.18.6 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.
 
-Codex uses five Revela skills: `revela-helper` for status and active design/domain, `revela-research` for local and web research saved under `researches/`, `revela-make-deck` for design-aware `deck-plan.md` plus `decks/*.html`, `revela-review` for the Review UI, and `revela-export` for PDF/PPTX/PNG.
+Codex uses five Revela skills: `revela-helper` for status and active design/domain, `revela-research` for local and web research saved under `researches/` plus the design-aware `deck-plan.md` handoff, `revela-make-deck` for generating `decks/*.html` from an existing plan, `revela-review` for the Review UI, and `revela-export` for PDF/PPTX/PNG.
 
 For release-aligned local validation, run `bun run smoke:mcp-pack`. It packs the current checkout to a temporary npm tarball and starts the MCP server through `npx`, matching the published Codex launcher path without requiring a registry publish.
 

package/README.zh-CN.md

@@ -34,7 +34,7 @@ Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材
 环境要求：
 
 - 需要已安装 Codex CLI，并且 shell 中可以执行 `codex`。
-- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.5 mcp` 启动 MCP server。
+- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.6 mcp` 启动 MCP server。
 - 如果使用 Review UI 的 Apply，需要 `codex exec` 可用；评论会先保存，点击 Apply 后才执行修复。
 
 可选的安装前检查：
@@ -55,17 +55,17 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 通过 Codex Git marketplace 安装 Revela：
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.5
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.6
 codex plugin add revela@revela
 ```
 
-Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.5 mcp`，由 npm 获取已发布 package 及其 dependencies。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.6 mcp`，由 npm 获取已发布 package 及其 dependencies。
 
 不需要在 Codex marketplace clone 里运行 `bun install`。
 
 安装后开启一个新的 Codex thread，让 Codex 加载 Revela 的 skills、MCP tools 和 hooks。
 
-Codex 使用五个 Revela skills：`revela-helper` 查看状态和 active design/domain，`revela-research` 调研本地与网络资料并保存到 `researches/`，`revela-make-deck` 基于 design 工具生成 `deck-plan.md` 和 `decks/*.html`，`revela-review` 打开 Review UI，`revela-export` 导出 PDF/PPTX/PNG。
+Codex 使用五个 Revela skills：`revela-helper` 查看状态和 active design/domain，`revela-research` 调研本地与网络资料、保存到 `researches/`，并产出 design-aware `deck-plan.md` handoff；`revela-make-deck` 基于已有 plan 生成 `decks/*.html`，`revela-review` 打开 Review UI，`revela-export` 导出 PDF/PPTX/PNG。
 
 如果要按发布路径做本地验证，运行 `bun run smoke:mcp-pack`。它会把当前 checkout 打成临时 npm tarball，再通过 `npx` 启动 MCP server，不需要先发布到 registry。
 

package/package.json

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

package/plugins/revela/.mcp.json

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

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

@@ -38,7 +38,11 @@ Report:
 - Runtime/version status from `revela_doctor`.
 - Active design and active domain.
 - Workspace artifact status: whether `researches/`, `deck-plan.md`, `decks/*.html`, and `assets/` appear available.
-- Recommended next step: `revela-research`, `revela-make-deck`, `revela-review`, or `revela-export`.
+- Recommended next step:
+  - No `researches/`: run `revela-research`.
+  - Research exists but no `deck-plan.md`: continue `revela-research` to the Planning Handoff.
+  - Valid `deck-plan.md` but no deck artifact: run `revela-make-deck`.
+  - Existing deck artifact: run `revela-review` or `revela-export` depending on the user goal.
 
 ## Must Not
 

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

@@ -1,11 +1,11 @@
 ---
 name: revela-make-deck
-description: Plan and generate Revela HTML deck artifacts in Codex from researches, workspace materials, active design, and deck-plan files.
+description: Generate Revela HTML deck artifacts in Codex from an existing deck-plan.md and active design files.
 ---
 
 # Revela Make Deck
 
-Use this skill when the user asks to plan, make, generate, or update a Revela deck. This skill owns both the Plan phase (`deck-plan.md`) and the Render phase (`decks/*.html`).
+Use this skill when the user asks to make, generate, render, or update a Revela HTML deck from an existing `deck-plan.md`.
 
 ## Contract
 
@@ -14,14 +14,16 @@ Use this skill when the user asks to plan, make, generate, or update a Revela de
 - Active/requested design tools define valid layouts, slots, components, nesting hints, and HTML writing rules.
 - Active/requested domain guidance may inform communication framing, but it is not source evidence.
 - Generated artifacts live under `decks/*.html`.
-- Do not require a Narrative Vault before planning or generating a deck.
-- Do not skip `deck-plan.md` for normal deck generation.
+- Do not require a Narrative Vault before generating a deck.
+- This skill does not own normal plan authoring; `revela-research` owns source preparation and `deck-plan.md` planning handoff.
+- `deck-plan.md` is required for normal deck generation.
 
 ## Preconditions
 
-- Recommended: source-linked `researches/**/*.md` and reviewed workspace materials exist.
-- If research is thin, the user may explicitly ask to continue with limited materials; then record source limitations in `deck-plan.md`.
+- Required: readable `deck-plan.md`.
 - An active or user-requested design must be readable.
+- If `deck-plan.md` is missing, stop and tell the user to run `revela-research` or continue `revela-research` to the Planning Handoff.
+- If `deck-plan.md` is structurally invalid, only repair technical plan diagnostics reported during render preflight.
 
 ## Inputs
 
@@ -29,18 +31,18 @@ Use this skill when the user asks to plan, make, generate, or update a Revela de
 - Reviewed workspace materials and material review records.
 - `assets/`
 - User deck objective, audience, and constraints.
-- Existing `deck-plan.md` when present.
+- Existing `deck-plan.md`.
 - Active/requested design and optional active/requested domain.
 
 ## Required Design Tools
 
-Before Plan phase authoring:
+Before render preflight:
 
 1. Call `revela_design_list`.
 2. Call `revela_design_read` with `section: "rules"` for the active/requested design.
 3. Call `revela_design_inventory`.
 
-Before Render phase HTML writing:
+Before HTML writing:
 
 1. Call `revela_read_deck_plan`.
 2. Read the returned `htmlWritingBatches`.
@@ -48,38 +50,22 @@ Before Render phase HTML writing:
 4. Call `revela_design_read_component` for each component used in the current batch.
 5. Fetch chart rules before creating or modifying ECharts.
 
-## Plan Phase
+## Plan Preflight And Repair
 
-Use this phase when the user asks for a plan, outline, deck-plan, or when a make request lacks a valid `deck-plan.md`.
+Call `revela_read_deck_plan` before HTML generation and treat the result as the render blueprint.
 
-1. Inspect local materials, material reviews, existing research findings, assets, and user intent.
-2. Read active/requested domain guidance only as framing context; never cite it as evidence.
-3. Use design inventory to choose valid layouts, slots, components, and component nesting.
-4. Write or repair `deck-plan.md` directly. Do not use structured upsert tools for normal plan authoring.
-5. Call `revela_read_deck_plan` after writing or repairing `deck-plan.md`.
-6. If diagnostics report layout, slot, component, `children`, or `sourceLinks` issues, patch the Markdown directly and call `revela_read_deck_plan` again.
+Allowed plan repairs are limited to technical diagnostics from `revela_read_deck_plan`:
 
-## Deck Plan Requirements
+- Broken Markdown/frontmatter structure.
+- Invalid or missing `sourceLinks` field structure, without adding new unsupported source links.
+- Layout, slot, component, or `children` names that do not match `revela_design_inventory`.
+- Component nesting fixes such as using `box.children` when the selected component model requires nested semantic groups.
 
-Every normal deck plan should include Cover, Table of Contents, and Closing. Use 3-5 chapter headings, explicit slide ranges, and `---` slide separators under `## Slides`.
-
-Each slide block must include:
-
-- Slide title and role when relevant.
-- `#### Content Plan`
-- `#### Source Links` for materials, findings, assets, URLs, and caveats.
-- `#### Design Plan`
-- Selected layout from design inventory.
-- Component plan using component names from design inventory.
-- Valid slots from the selected layout.
-- Valid component nesting hints, including `box.children` when multiple child components support one semantic idea.
-- Unresolved inputs, source limitations, and user review notes instead of AI-authored caveat/risk judgement.
-
-Do not duplicate the same child as both nested and top-level.
+Do not redesign the argument structure, add new slides, remove supported slides, rewrite claims, or add source links that were not reviewed or saved by `revela-research`. If normal plan authoring is needed, stop and send the user back to `revela-research` Planning Handoff.
 
 ## Render Phase
 
-Use this phase when the user asks to make, generate, render, or update an HTML deck.
+Use this phase when the user asks to make, generate, render, or update an HTML deck and `deck-plan.md` is readable.
 
 1. Call `revela_read_deck_plan` before HTML generation and follow the current projection.
 2. Read `htmlWritingBatches` before any HTML write. `revela_read_deck_plan` is QA/diagnostics, not a writer.
@@ -95,13 +81,15 @@ Use this phase when the user asks to make, generate, render, or update an HTML d
 
 ## Outputs
 
-- Plan-only request: `deck-plan.md`.
-- Make/render request: `deck-plan.md` and `decks/*.html`.
-- QA status and unresolved source/design limitations.
+- `decks/*.html`.
+- Artifact QA status.
+- Unresolved render/design issues and any plan diagnostics that require `revela-research` Planning Handoff.
 
 ## Must Not
 
-- Do not skip `deck-plan.md` for normal decks.
+- Do not skip or synthesize `deck-plan.md` for normal decks.
+- Do not claim ownership of normal plan authoring.
+- Do not write a new `deck-plan.md` when it is missing.
 - Do not use design inventory names, slots, or components that were not returned by the active/requested design tools.
 - Do not use a slot that does not belong to the selected layout.
 - Do not patch more than 5 slide sections in one HTML write.

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

@@ -1,20 +1,22 @@
 ---
 name: revela-research
-description: Research workspace materials and public sources for a Revela deck objective, using active domain guidance and saving source-linked findings.
+description: Research workspace materials and public sources for a Revela deck objective, using active domain/design guidance to save source-linked findings and hand off deck-plan.md.
 ---
 
 # Revela Research
 
-Use this skill when the user asks to start from a goal, inspect local materials, research missing inputs, gather public support, save findings, or find source-linked examples/assets for a deck.
+Use this skill when the user asks to start from a goal, inspect local materials, research missing inputs, gather public support, save findings, find source-linked examples/assets, or prepare the deck planning handoff.
 
 ## Contract
 
 - Research is the source-preparation workflow for Codex Revela.
-- Research output is saved under `researches/**/*.md` for later `deck-plan.md` use.
+- Research output is saved under `researches/**/*.md` and, when the user goal is a deck and materials are sufficient, handed off as `deck-plan.md`.
 - Local materials are only usable after direct text review or extracted read-view review.
 - Active/requested domain guidance informs audience, decision framing, claim standards, evidence expectations, objection/risk interpretation, and research-gap priority.
 - Domain guidance is not evidence and must never be cited as proof for factual claims.
-- Do not create `deck-plan.md`, deck artifacts, a Narrative Vault, or canonical evidence bindings during research.
+- Active/requested design tools define valid layouts, slots, components, nesting hints, and deck-plan design vocabulary.
+- `deck-plan.md` is the formal research-to-make-deck handoff when a deck objective is sufficiently supported.
+- Do not create deck artifacts, a Narrative Vault, or canonical evidence bindings during research.
 - Do not invent URLs, quotes, page references, numbers, caveats, or licenses.
 
 ## Preconditions
@@ -40,6 +42,13 @@ Use this skill when the user asks to start from a goal, inspect local materials,
 7. Call `revela_check_material_intake` before reporting research readiness.
 8. Use external research only for public facts, user-authorized questions, or gaps not covered by local materials.
 9. Save useful findings with `revela_research_save`.
+10. For deck goals with sufficient materials, run Planning Handoff:
+    - Call `revela_design_list`.
+    - Call `revela_design_read` with `section: "rules"` for the active/requested design.
+    - Call `revela_design_inventory`.
+    - Write `deck-plan.md` directly from reviewed materials, saved findings, assets, user intent, active domain framing, and active design vocabulary.
+    - Call `revela_read_deck_plan` after writing `deck-plan.md`.
+    - If diagnostics report `sourceLinks`, layout, slot, component, or `children` issues, patch `deck-plan.md` directly and call `revela_read_deck_plan` again.
 
 ## Finding Requirements
 
@@ -59,13 +68,33 @@ If a finding is context only, label it as context and do not present it as proof
 
 - `researches/{topic}/{filename}.md`
 - Material review records for reviewed Office/PDF sources.
+- `deck-plan.md` when the user goal is a deck and reviewed materials/findings are sufficient for a traceable plan.
 - Source limitations and unresolved gaps.
 - A clear statement of whether `revela-make-deck` can proceed or whether more research is needed.
 
+## Planning Handoff
+
+Use this final stage only for deck goals. If sources are too thin, report unresolved inputs and source limitations instead of drafting unsupported slides.
+
+Every `deck-plan.md` handoff should include Cover, Table of Contents, Closing, 3-5 chapter headings, explicit slide ranges, and `---` slide separators under `## Slides`.
+
+Each non-structural slide block must include:
+
+- Slide title and role when relevant.
+- `#### Content Plan`
+- `#### Source Links` for materials, findings, assets, URLs, and caveats.
+- `#### Design Plan`
+- Selected layout from design inventory.
+- Component plan using component names from design inventory.
+- Valid slots from the selected layout.
+- Valid component nesting hints, including `box.children` when multiple child components support one semantic idea.
+- Unresolved inputs, source limitations, and user review notes instead of AI-authored caveat/risk judgement.
+
+Do not duplicate the same child as both nested and top-level. Do not add source links that were not reviewed or saved during research.
+
 ## Must Not
 
 - Do not generate `revela-narrative/`.
-- Do not write `deck-plan.md`.
 - Do not write `decks/*.html`.
 - Do not bind findings into a Narrative Vault or canonical evidence graph.
 - Do not treat domain guidance as source evidence.