@cyber-dash-tech/revela 0.18.5 → 0.18.7

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-709%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-716%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`.
 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.7 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.7
 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.7 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 seven Revela skills: `revela-helper` for status and active design/domain, `revela-design` for custom design creation/validation/activation, `revela-domain` for custom narrative domain creation/validation/activation, `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

@@ -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-709%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-716%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 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.7 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.7
 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.7 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-design` 创建、验证、激活 custom design，`revela-domain` 创建、验证、激活 custom narrative 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/designs/monet/DESIGN.md

@@ -838,6 +838,25 @@ Every slot accepts 1 or more components, but the layout should preserve a synthe
 - **Dark background variant.** Set CSS variable overrides (`--text-primary` etc.) on `.stacked-grid` to cascade into both slots automatically.
 <!-- @layout:stacked:end -->
 
+<!-- @layout:toc:start qa=false -->
+#### TOC
+
+Editorial wayfinding layout for a table of contents, agenda, section map, or chapter divider. Use with the `toc` component as the primary structure so Monet keeps its print-like chapter list and page-number rhythm. Do not use this as a general two-column narrative layout, and do not replace the TOC structure with a `text-panel`.
+
+Structural intent:
+- main slot: one `toc` component.
+
+```html
+<section class="slide" slide-qa="false" data-slide-index="N">
+  <div class="slide-canvas">
+    <div class="page" style="padding:0;overflow:hidden;">
+      <!-- [slot: main] — use one toc component -->
+    </div>
+  </div>
+</section>
+```
+<!-- @layout:toc:end -->
+
 <!-- @design:layouts:end -->
 
 

package/designs/starter/DESIGN.md

@@ -422,6 +422,25 @@ Two-row layout for a compact header/summary above a larger evidence, chart, or f
 ```
 <!-- @layout:stacked:end -->
 
+<!-- @layout:toc:start qa=false -->
+#### TOC
+
+Structural wayfinding layout for a table of contents, agenda, section map, or chapter divider. Use with the `toc` component as the primary structure. Do not use this as a general two-column narrative layout, and do not replace the TOC structure with a `text-panel`.
+
+Structural intent:
+- main slot: one `toc` component.
+
+```html
+<section class="slide" slide-qa="false" data-slide-index="N">
+  <div class="slide-canvas">
+    <div class="page" style="padding:0;">
+      <!-- [slot: main] — use one toc component -->
+    </div>
+  </div>
+</section>
+```
+<!-- @layout:toc:end -->
+
 <!-- @design:layouts:end -->
 
 <!-- @design:components:start -->

package/designs/summit/DESIGN.md

@@ -801,6 +801,25 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 - **Dark background variant.** Set CSS variable overrides (`--text-primary` etc.) on `.stacked-grid` to cascade into both slots automatically.
 <!-- @layout:stacked:end -->
 
+<!-- @layout:toc:start qa=false -->
+#### TOC
+
+Structural wayfinding layout for a table of contents, agenda, section map, or chapter divider. Use with the `toc` component as the primary structure so Summit can keep its wide editorial spacing, understated rules, and section rhythm. Do not use this as a general two-column narrative layout, and do not replace the TOC structure with a `text-panel`.
+
+Structural intent:
+- main slot: one `toc` component.
+
+```html
+<section class="slide" slide-qa="false" data-slide-index="N">
+  <div class="slide-canvas">
+    <div class="page" style="padding:0;overflow:hidden;">
+      <!-- [slot: main] — use one toc component -->
+    </div>
+  </div>
+</section>
+```
+<!-- @layout:toc:end -->
+
 <!-- @design:layouts:end -->
 
 

package/lib/design/designs.ts

@@ -157,14 +157,26 @@ function designDirHasPackage(dir: string): boolean {
 function resolveDesignDir(nameInput?: string): string | null {
   const name = normalizeDesignName(nameInput || activeDesign())
   const userDir = join(DESIGNS_DIR, name)
-  if (designDirHasPackage(userDir)) return userDir
-
   const bundledDir = join(SEED_DIR, name)
+  if (designDirHasPackage(userDir)) {
+    if (designDirHasPackage(bundledDir) && isSeededBuiltinCopy(userDir, bundledDir)) return bundledDir
+    return userDir
+  }
+
   if (designDirHasPackage(bundledDir)) return bundledDir
 
   return null
 }
 
+function isSeededBuiltinCopy(userDir: string, bundledDir: string): boolean {
+  const userInfo = parseDesignFile(join(userDir, "DESIGN.md"))
+  const bundledInfo = parseDesignFile(join(bundledDir, "DESIGN.md"))
+  if (!userInfo || !bundledInfo) return false
+  return userInfo.author === bundledInfo.author
+    && userInfo.version === bundledInfo.version
+    && userInfo.description === bundledInfo.description
+}
+
 function readDesignsFromDir(root: string): Map<string, DesignInfo> {
   const designs = new Map<string, DesignInfo>()
   if (!existsSync(root)) return designs

package/lib/narrative-state/render-plan.ts

@@ -251,7 +251,7 @@ function buildDeckPlanRequirements(narrativeHash: string): DeckPlanRequirements
       "Use 3-5 chapters for normal executive decks.",
       "Cover every central claim, but group related central claims into chapters instead of giving each claim its own chapter.",
       "Each substantive chapter should have framing, proof, and implication/boundary coverage.",
-      "Chapter divider or chapter TOC slides may use the toc component as structural wayfinding.",
+      "Chapter divider or chapter TOC slides should use layout: toc with the toc component as structural wayfinding.",
       "Do not create filler slides, repeated thesis pages, or generic bridge slides.",
       "Preserve evidence ids, source trace, source limitations, unresolved inputs, and user review notes where available.",
       "Do not render internal labels such as Evidence gap:, Unsupported scope:, Caveat:, Missing Data, or Evidence Boundary in executive body copy.",
@@ -283,7 +283,7 @@ export function buildRenderPlanContract(deck: DeckSpec, chapters: DeckPlanChapte
     renderRules: [
       "Do not infer deck structure, slide count, or chapter substance from DECKS.json slides[].",
       "Use the compileDeckPlan planning packet plus deck-plan.md as the render-plan contract.",
-      "Render chapter divider slides with the toc component when slideKind is chapter-divider.",
+      "Render chapter divider slides with layout: toc and the toc component when slideKind is chapter-divider.",
       "Chapter divider and global TOC slides are structural wayfinding and do not count toward central-claim substance.",
       "Each central claim chapter needs non-structural framing, proof, and implication/boundary slides unless the current deck-plan projection explicitly says otherwise.",
       `Generate HTML in chapter-bounded batches of at most ${MAX_HTML_SLIDES_PER_BATCH} slides, preserving valid HTML and already-written slides after every batch.`,
@@ -470,7 +470,7 @@ function tocSlide(index: number, chapters: DeckPlanChapter[]): SlideSpec {
     narrativeRole: "context",
     layout: "toc",
     qa: false,
-    components: ["toc", "text-panel"],
+    components: ["toc"],
     content: {
       headline: "How the decision story is organized",
       bullets: chapters.map((chapter) => chapter.title),
@@ -491,7 +491,7 @@ function chapterDividerSlide(index: number, chapters: DeckPlanChapter[], chapter
     narrativeRole: "context",
     layout: "toc",
     qa: false,
-    components: ["toc", "text-panel"],
+    components: ["toc"],
     claimIds: chapter.sourceClaimId ? [chapter.sourceClaimId] : [],
     claimRefs: chapter.sourceClaimId ? [{ claimId: chapter.sourceClaimId, role: "supporting", note: "Structural chapter divider; not counted as claim proof." }] : [],
     evidenceBindingIds: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.18.5",
+  "version": "0.18.7",
   "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.7", "mcp"]
     }
   }
 }

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

@@ -0,0 +1,60 @@
+---
+name: revela-design
+description: Create, edit, validate, install, activate, inspect, or list Revela design packages in Codex using design MCP tools.
+---
+
+# Revela Design
+
+Use this skill when the user asks to create, customize, edit, validate, install, activate, inspect, list, or switch a Revela design.
+
+## Contract
+
+- Designs define deck visual systems: rules, foundation, layouts, components, chart rules, and preview coverage.
+- Default authoring is workspace draft first, then validate, then install only when appropriate.
+- Direct user-level creation is reserved for explicit create/install-now requests.
+- Do not use domain tools for visual design work.
+- Do not generate deck HTML while authoring a design.
+
+## Required Tools
+
+For status, inspection, activation, or selection:
+
+1. Call `revela_design_list`.
+2. Call `revela_design_read`, `revela_design_inventory`, `revela_design_read_layout`, or `revela_design_read_component` as needed.
+3. Call `revela_design_activate` only when the user asks to use a design.
+
+For new or edited designs:
+
+1. Call `revela_design_list`.
+2. Read the requested base design or active design with `revela_design_read`.
+3. Draft complete `DESIGN.md` and complete `preview.html` content.
+4. Call `revela_design_draft_create`.
+5. Call `revela_design_draft_validate`.
+6. If validation fails, revise the draft content and repeat draft create/validate.
+7. Call `revela_design_draft_install` only after the draft validates and the user intent is to install it.
+8. Call `revela_design_activate` only when the user asks to make it active.
+
+Use `revela_design_create` only when the user explicitly requests direct local creation outside the workspace draft workflow. Follow it with `revela_design_validate`.
+
+## Design Package Requirements
+
+- Use a kebab-case design name.
+- `DESIGN.md` must include valid frontmatter and complete design marker sections.
+- Include design rules, foundation guidance, at least one layout, and at least one component.
+- `preview.html` must use the fixed Revela preview canvas contract and visibly preview the design.
+- Preview must include cover and closing examples and showcase every component.
+- Preserve source inspiration and limitations explicitly; do not copy copyrighted design text or assets into the package.
+
+## Outputs
+
+- Design draft path/status or installed design name.
+- Validation result and any remaining diagnostics.
+- Whether the design was activated.
+- Next step, usually `revela-research` for planning with the design or `revela-make-deck` when a valid `deck-plan.md` already exists.
+
+## Must Not
+
+- Do not write `deck-plan.md`.
+- Do not write `decks/*.html`.
+- Do not install or activate a design unless the user requested that outcome.
+- Do not invent licenses, asset provenance, or brand permissions.

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

@@ -0,0 +1,59 @@
+---
+name: revela-domain
+description: Create, edit, validate, install, activate, inspect, or list Revela narrative domain packages in Codex using domain MCP tools.
+---
+
+# Revela Domain
+
+Use this skill when the user asks to create, customize, edit, validate, install, activate, inspect, list, or switch a Revela narrative domain.
+
+## Contract
+
+- Domains guide narrative authoring: audience framing, decision standards, evidence expectations, objection/risk handling, and research priorities.
+- Domain guidance is not evidence and must never be cited as proof for factual claims.
+- Default authoring is workspace draft first, then validate, then install only when appropriate.
+- Direct user-level creation is reserved for explicit create/install-now requests.
+- Do not use design tools for narrative domain work.
+
+## Required Tools
+
+For status, inspection, activation, or selection:
+
+1. Call `revela_domain_list`.
+2. Call `revela_domain_read` when the user asks for detail or comparison.
+3. Call `revela_domain_activate` only when the user asks to use a domain.
+
+For new or edited domains:
+
+1. Call `revela_domain_list`.
+2. Read a relevant existing domain with `revela_domain_read` when useful as a reference.
+3. Draft complete `INDUSTRY.md` content.
+4. Call `revela_domain_draft_create`.
+5. Call `revela_domain_draft_validate`.
+6. If validation fails, revise the draft content and repeat draft create/validate.
+7. Call `revela_domain_draft_install` only after the draft validates and the user intent is to install it.
+8. Call `revela_domain_activate` only when the user asks to make it active.
+
+Use `revela_domain_create` only when the user explicitly requests direct local creation outside the workspace draft workflow. Follow it with `revela_domain_validate`.
+
+## Domain Package Requirements
+
+- Use a kebab-case domain name.
+- `INDUSTRY.md` must be complete domain guidance, not a research report.
+- Include audience/decision framing, claim standards, evidence expectations, objection/risk guidance, and research-gap priorities.
+- Keep guidance procedural and reusable; do not include unsupported factual claims as evidence.
+- Preserve source limitations explicitly when domain guidance is based on user-provided context.
+
+## Outputs
+
+- Domain draft path/status or installed domain name.
+- Validation result and any remaining diagnostics.
+- Whether the domain was activated.
+- Next step, usually `revela-research` so the active domain informs material intake and planning.
+
+## Must Not
+
+- Do not write `researches/**/*.md`, `deck-plan.md`, or `decks/*.html`.
+- Do not install or activate a domain unless the user requested that outcome.
+- Do not treat domain guidance as source evidence.
+- Do not invent citations, claims, URLs, or industry facts.

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

@@ -38,7 +38,13 @@ 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:
+  - Custom visual system requested: use `revela-design`.
+  - Custom narrative domain guidance requested: use `revela-domain`.
+  - 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
 
@@ -46,3 +52,4 @@ Report:
 - Do not do external web research.
 - Do not generate or repair `deck-plan.md`.
 - Do not generate, review, patch, or export deck artifacts.
+- Do not create, install, or activate designs or domains; route those requests to `revela-design` or `revela-domain`.

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.

package/skill/SKILL.md

@@ -156,8 +156,8 @@ Rules for the slide plan:
   evidence table, comparison grid, risk matrix, steps view, chart, or media brief
   into generic bullets unless the user revises the plan.
 - Chapter divider or chapter TOC slides are structural wayfinding and should
-  usually render with the `toc` component; they must not replace framing, proof,
-  and implication coverage in substantive chapters.
+  use `layout: toc` with the `toc` component; they must not replace framing,
+  proof, and implication coverage in substantive chapters.
 - Normal content slides should usually contain 2-4 semantic boxes/cards unless
   intentionally using a focus layout.
 - If a chapter lacks enough substance for its allocated slides, reduce the slide
@@ -183,7 +183,7 @@ For decks with 5 or more slides:
   `htmlWritingBatches`.
 - Do not mix multiple central-claim chapters in the same write.
 - Chapter divider or chapter TOC slides are allowed as structural wayfinding and
-  should usually use the `toc` component.
+  should use `layout: toc` with the `toc` component.
 - Do not use placeholder, blank, repeated thesis, or generic transition slides as
   substitutes for required claim substance.
 - Treat appendix, summary, and closing slides as the final batch unless the