@cyber-dash-tech/revela 0.18.7 → 0.18.8

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-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)
+[![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-722%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.7 mcp` to start the MCP server.
+- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.18.8 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.7
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.8
 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.7 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.8 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 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.
+Codex uses nine Revela skills: `revela` for routing the next workflow step, `revela-spec` for writing root-level `spec.md`, `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-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)
+[![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-722%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.7 mcp` 启动 MCP server。
+- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.8 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.7
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.8
 codex plugin add revela@revela
 ```
 
-Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.7 mcp`，由 npm 获取已发布 package 及其 dependencies。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.8 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-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。
+Codex 使用九个 Revela skills：`revela` 路由下一步 workflow，`revela-spec` 产出根目录 `spec.md`，`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/lib/agents/research-prompt.ts

@@ -109,40 +109,81 @@ Use **\`revela-research-save\`** to write ONE file with all your findings.
 
 - \`topic\`: kebab-case topic key shared across all agents for this presentation
 - \`filename\`: your axis name (e.g. \`market-data\`, \`catl-profile\`, \`tech-trends\`)
-- \`content\`: structured findings using the four sections below
+- \`content\`: structured findings using the block types below
 - \`sources\`: list of all URLs and filenames used
 
 The primary agent will map your findings into \`DECKS.json\` slide-level evidence.
 Preserve compact source trace so it can do that without rediscovering sources.
+For the current deck-first workflow, structure findings for finding-level deck-plan source links and later artifact planning.
 
 ### Findings file format
 
-Use these four sections — omit any that are empty:
+Use stable blocks. Omit empty optional fields:
 
 \`\`\`markdown
-## Data
-- {stat or finding} [Source: {url or filename}; Location: {page/slide/sheet/section if known}; Quote: "{short exact snippet if available}"; Caveat: {scope/uncertainty if relevant}]
-- {stat or finding} [Source: {url or filename}; Location: {page/slide/sheet/section if known}; Quote: "{short exact snippet if available}"; Caveat: {scope/uncertainty if relevant}]
-(5–10 items, most argument-worthy only)
-
-## Cases
-- **{Company/Entity}**: {1–2 sentence profile with key metrics} [Source: {url or filename}; Location: {page/slide/sheet/section if known}; Caveat: {scope/uncertainty if relevant}]
-(2–4 entries max)
-
-## Images
-- {Description}: {url} | Alt: {brief alt text} | Use: logo|screenshot|portrait
-(only if found — do NOT fabricate URLs)
+## Finding: <stable-id>
+
+Source: {source name and publication/check date when known}
+URL: {url when available}
+Location: {page/slide/sheet/section if known}
+Quote/Snippet: "{short exact snippet if available, or explicit note that no exact quote is available}"
+Supports: {narrow support scope or intended slide/source context}
+Evidence boundary: {internal support limit, unsupported scope, or uncertainty; not default deck copy}
+Strength: {strong|directional|weak|context-only}
+Deck use: {where this belongs in deck planning}
+Display note: {optional short audience-facing scope note for captions/source notes}
+
+## Synthesis: <stable-id>
+
+Question answered: {research question this synthesis resolves}
+Basis: {finding ids, source files, or URLs used}
+Interpretation: {what the evidence means when read together}
+So what: {why this matters for the audience or decision}
+Decision implication: {what should change in the recommendation, story, or slide argument}
+Confidence: {high|medium|low}
+Alternative reading: {plausible competing interpretation or contradiction}
+Evidence boundary: {internal guardrail; what this synthesis must not overclaim}
+Deck use: {where this belongs in deck planning}
+Display note: {optional short user-facing scope note}
+
+## Analysis: <stable-id>
+
+Basis: {user/LLM analytical framework or synthesis basis}
+Assumptions: {key assumptions}
+Deck use: {where this supports structure or methodology}
+Evidence boundary: This is an analytical framework, not external source evidence.
+Display note: {optional visible note}
+
+## Implementation Note: <stable-id>
+
+Purpose: {render/data/API contract purpose}
+Required fields: {fields, data shape, or implementation constraints}
+Deck use: {where this supports rendering}
+Evidence boundary: This is a rendering/data contract, not market evidence.
+Display note: {optional visible note}
+
+## Asset Lead: <stable-id>
+
+Source: {url or workspace path}
+Description: {image/logo/screenshot/diagram description}
+Alt: {brief alt text}
+License/Attribution: {known status; do not invent clearance}
+Deck use: {logo|screenshot|portrait|diagram|visual draft}
 
 ## Gaps
 - {topic or data point not found or insufficiently covered}
 \`\`\`
 
 Content rules:
-- Every data point MUST have inline source attribution: \`[Source: {url}]\` or \`[Source: AI knowledge — verify]\` or \`[Source: {filename}]\`
+- Every evidence finding MUST have source attribution: \`Source:\` plus \`URL:\` or workspace filename/path. Use \`Source: AI knowledge - verify\` only as a gap/context marker, not proof.
 - For workspace documents, identify the original filename and available page, slide, sheet, or section location. Do not cite only the extracted summary.
 - When extracted materials were used, include \`extractedTextPath\` or \`extractedManifestPath\` when useful for traceability.
 - Preserve compact direct snippets or quotes when available. Do not invent quotes, page references, locations, URLs, or caveats.
-- Include caveats or scope limitations for estimates, rankings, market sizes, forecasts, and conflicting sources.
+- Use \`Evidence boundary\` for internal support limits, unsupported scope, estimates, rankings, market sizes, forecasts, and conflicting sources.
+- Use \`Display note\` only for short user-facing scope text that may appear in captions or source notes.
+- Do not mechanically copy \`Evidence boundary\` into deck copy; expose it only when needed to avoid a misleading audience conclusion.
+- For deck goals, turn related findings into \`Synthesis\` before planning slides. Findings are evidence basis; synthesis carries Interpretation, So what, Decision implication, and Audience takeaway material.
+- Do not mechanically copy finding bullets into deck copy. Use \`Synthesis\` to write slide claims and takeaways, then keep findings in source notes, captions, evidence charts, or speaker notes.
 - Preserve raw numbers and direct quotes — do not summarize prematurely
 - Use tables for comparative data when 3+ entities are compared
 - Include publication dates where available
@@ -176,8 +217,9 @@ Gaps:
 - **NEVER** fabricate image URLs — only record URLs you actually found
 - **Always** call \`revela-extract-document-materials\` for every selected workspace file before deciding which extracted materials to read next
 - **Avoid** repeated extraction or deep reading for files that are clearly irrelevant to this axis
-- **Always** include source attribution on every data point
-- **Always** preserve source trace: URL or filename, location when available, compact quote/snippet when available, and caveat/scope where relevant
+- **Always** include source attribution on every evidence finding
+- **Always** preserve source trace: URL or filename, location when available, compact quote/snippet when available, Evidence boundary, Strength, Deck use, and Display note where relevant
+- **Always** write synthesis when multiple findings answer the same deck question or when a finding needs interpretation before it can become a slide argument
 - **Always** use tables for comparative data (more useful than bullets for presentations)
 - **Preserve** raw data — the primary agent will select what to include in slides
 - **Note** data freshness — include publication dates where available

package/lib/narrative-state/deck-plan-artifact.ts

@@ -905,6 +905,7 @@ function htmlWritingInstruction(): string {
 function slideDiagnostics(slide: DeckPlanSlideProjection, knownNodeIds?: Set<string>): DeckPlanProjectionDiagnostic[] {
   const diagnostics: DeckPlanProjectionDiagnostic[] = []
   if (!slide.structural && linksCount(slide.sourceLinks) === 0) diagnostics.push({ severity: "warning", code: "slide_source_link_missing", message: `Non-structural deck-plan slide ${slide.id} has no material, finding, asset, or URL source link.`, file: slide.path, nodeId: slide.id })
+  if (!slide.structural && linksCount(slide.sourceLinks) > 0) diagnostics.push(...slideSynthesisDiagnostics(slide))
   if (!slide.layout) diagnostics.push({ severity: "warning", code: "slide_layout_missing", message: `Deck-plan slide ${slide.id} is missing a layout.`, file: slide.path, nodeId: slide.id })
   if (slide.components.length === 0) diagnostics.push({ severity: "warning", code: "slide_components_missing", message: `Deck-plan slide ${slide.id} has no component names in frontmatter.`, file: slide.path, nodeId: slide.id })
   if (slide.componentPlan.length === 0) diagnostics.push({ severity: "warning", code: "slide_component_plan_missing", message: `Deck-plan slide ${slide.id} is missing structured ## Component Plan entries.`, file: slide.path, nodeId: slide.id })
@@ -921,6 +922,36 @@ function slideDiagnostics(slide: DeckPlanSlideProjection, knownNodeIds?: Set<str
   return diagnostics
 }
 
+function slideSynthesisDiagnostics(slide: DeckPlanSlideProjection): DeckPlanProjectionDiagnostic[] {
+  const diagnostics: DeckPlanProjectionDiagnostic[] = []
+  const contentPlan = singleFileSubsection(slide.markdown, "Content Plan")
+  const missing = ["Claim", "Reasoning", "Audience takeaway"].filter((field) => !hasPlanField(contentPlan, field))
+  if (missing.length > 0) diagnostics.push({
+    severity: "warning",
+    code: "slide_synthesis_thin",
+    message: `Non-structural deck-plan slide ${slide.id} has source links but lacks synthesis fields in Content Plan: ${missing.join(", ")}.`,
+    file: slide.path,
+    nodeId: slide.id,
+  })
+  if (contentPlanContainsFindingCopy(contentPlan)) diagnostics.push({
+    severity: "warning",
+    code: "slide_finding_copy_risk",
+    message: `Deck-plan slide ${slide.id} appears to use raw finding text in Content Plan; use synthesis for the claim, reasoning, and audience takeaway, and keep findings as evidence/source context.`,
+    file: slide.path,
+    nodeId: slide.id,
+  })
+  return diagnostics
+}
+
+function hasPlanField(markdown: string, field: string): boolean {
+  const escaped = field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  return new RegExp(`^\\s*[-*]?\\s*${escaped}\\s*:`, "im").test(markdown)
+}
+
+function contentPlanContainsFindingCopy(markdown: string): boolean {
+  return /^\s*[-*]?\s*(Finding|Quote\/Snippet|Source|URL)\s*:/im.test(markdown)
+}
+
 export function deckPlanDesignDiagnostics(projection: DeckPlanProjection | undefined, inventory: { layouts: string[]; components: string[]; layoutSlots?: Record<string, string[]>; componentNesting?: Record<string, { acceptsChildren: boolean; allowedChildren?: string[] }> }): DeckPlanProjectionDiagnostic[] {
   if (!projection) return []
   const layouts = new Set(inventory.layouts)

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

@@ -254,6 +254,8 @@ function buildDeckPlanRequirements(narrativeHash: string): DeckPlanRequirements
       "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.",
+      "For non-structural slides, write Content Plan fields for Claim, Reasoning, Audience takeaway, Evidence basis, and Boundary handling before design details.",
+      "Use synthesized interpretation for slide arguments; do not mechanically copy raw research findings into executive body copy.",
       "Do not render internal labels such as Evidence gap:, Unsupported scope:, Caveat:, Missing Data, or Evidence Boundary in executive body copy.",
       "Do not infer plan structure from DECKS.json slides[]; it is compatibility cache only.",
       "Use sourceLinks in slide blocks for materials, findings, assets, and URLs; do not use canonical ## Relations in deck-plan files.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.18.7",
+  "version": "0.18.8",
   "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,7 +1,7 @@
 {
   "name": "revela",
   "version": "0.1.0+codex.20260524164007",
-  "description": "Use Revela in Codex to build trusted, traceable narrative decision artifacts from local sources and research.",
+  "description": "Use Revela in Codex to specify, research, plan, make, review, and export trusted narrative decision artifacts.",
   "author": {
     "name": "cyber-dash-tech",
     "url": "https://github.com/cyber-dash-tech"
@@ -20,7 +20,7 @@
   "interface": {
     "displayName": "Revela",
     "shortDescription": "Trusted narrative artifacts from local sources and research.",
-    "longDescription": "Revela helps Codex ingest local materials, save research findings, plan decks, generate HTML deck artifacts, review them, and export PDF/PPTX/PNG outputs while preserving source traceability.",
+    "longDescription": "Revela helps Codex route workspace workflows, capture requirements in spec.md, ingest local materials, save research findings, plan decks, generate HTML deck artifacts, review them, and export PDF/PPTX/PNG outputs while preserving source traceability.",
     "developerName": "cyber-dash-tech",
     "category": "Productivity",
     "capabilities": [
@@ -28,7 +28,8 @@
       "Write"
     ],
     "defaultPrompt": [
-      "Use Revela to initialize this workspace.",
+      "Use Revela to route the next workflow step for this workspace.",
+      "Use Revela to write a spec.md for this deck objective.",
       "Use Revela to make a deck from the deck plan.",
       "Use Revela to review this deck artifact."
     ],

package/plugins/revela/.mcp.json

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

package/plugins/revela/mcp/revela-server.ts

@@ -289,12 +289,12 @@ const tools = [
   },
   {
     name: "revela_research_save",
-    description: "Save source-linked research findings under researches/{topic}/{filename}.md for deck-plan use.",
+    description: "Save source-linked research findings under researches/{topic}/{filename}.md for deck-plan use. Prefer structured blocks: ## Finding: <stable-id> for evidence, ## Synthesis: <stable-id> for interpretation across findings, ## Analysis: <stable-id> for analytical frameworks, ## Implementation Note: <stable-id> for render/data/API contracts, ## Asset Lead: <stable-id> for media leads, and ## Gaps for missing support.",
     inputSchema: objectSchema({
       workspaceRoot: stringProp("Optional workspace root."),
       topic: requiredStringProp("Research topic key."),
       filename: requiredStringProp("Findings filename without extension."),
-      content: requiredStringProp("Structured Markdown findings content."),
+      content: requiredStringProp("Structured Markdown findings content. Evidence findings should preserve source, quote/snippet, support scope or Supports, Evidence boundary or unsupported scope, Strength, Deck use, and optional Display note. Synthesis entries should preserve Basis, Interpretation, So what, Decision implication, Confidence, Alternative reading, Evidence boundary, and Deck use. Analysis and Implementation Note entries may support planning or rendering but are not external factual proof."),
       sources: arrayProp("Source URLs or workspace files for YAML frontmatter."),
     }, ["topic", "filename", "content"]),
   },

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

@@ -0,0 +1,51 @@
+---
+name: revela
+description: Route Revela requests to the right specialist workflow based on user intent and workspace state. Use when the user asks generally to use Revela, start or continue a Revela workflow, inspect next steps, or decide what to do from existing spec.md, researches/, deck-plan.md, or deck artifacts.
+---
+
+# Revela Router
+
+Use this skill as the main Revela entrypoint in Codex. It should inspect intent and file-native workspace state, then route to the narrow specialist skill that owns the next action.
+
+## Contract
+
+- This is a non-mutating router.
+- It may inspect runtime, active design/domain, and workspace artifact status.
+- It must not write `spec.md`, save research findings, write `deck-plan.md`, generate deck HTML, open Review UI, or export artifacts.
+- Route quickly once the next workflow is clear.
+
+## Required Tools
+
+1. Call `revela_doctor` to inspect runtime and workspace status.
+2. Call `revela_design_list` to identify the active design.
+3. Call `revela_domain_list` to identify the active domain.
+4. Read files only as needed to distinguish `spec.md`, `researches/`, `deck-plan.md`, `decks/*.html`, and `assets/` state.
+
+## Routing Rules
+
+- Custom visual system, design package, layout, component, or activation request: use `revela-design`.
+- Custom narrative domain, industry guidance, evidence standard, or domain activation request: use `revela-domain`.
+- No `spec.md`, unclear objective, missing audience, missing output target, or missing acceptance criteria: use `revela-spec`.
+- `spec.md` exists but source support, material review, or findings are missing: use `revela-research`.
+- `spec.md` and sufficient findings exist but `deck-plan.md` is missing or needs normal authoring: use `revela-research` Planning Handoff.
+- Valid `deck-plan.md` exists and the user asks to make, generate, render, or update a deck: use `revela-make-deck`.
+- Existing deck artifact and the user asks to review, diagnose, QA, or refine: use `revela-review`.
+- Existing deck artifact and the user asks for PDF, PPTX, or PNG output: use `revela-export`.
+- If the next step is still ambiguous after inspection, ask the smallest missing question and recommend the safest next specialist skill.
+
+## Output
+
+Report:
+
+- Current workflow state: `spec.md`, `researches/`, `deck-plan.md`, `decks/*.html`, and `assets/`.
+- Active design and active domain.
+- The selected specialist skill and why.
+- Any missing input that prevents routing.
+
+## Must Not
+
+- Do not write or patch files.
+- Do not do external web research.
+- Do not create or repair `spec.md` or `deck-plan.md`.
+- Do not generate, review, patch, or export deck artifacts.
+- Do not install or activate designs or domains; route those requests to `revela-design` or `revela-domain`.

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

@@ -1,6 +1,6 @@
 ---
 name: revela-helper
-description: Explain Revela, inspect the current Revela workspace status, and report active design/domain guidance in Codex.
+description: Explain Revela, inspect the current Revela workspace status, and report active design/domain guidance in Codex. Use the revela router for workflow routing when the user wants to start or continue work.
 ---
 
 # Revela Helper
@@ -10,8 +10,9 @@ Use this skill when the user asks what Revela is, what the current workspace sta
 ## Contract
 
 - This is a read-only helper and orientation surface.
+- `revela` is the main workflow router; this skill explains status and capabilities.
 - It may inspect runtime, design, domain, and workspace artifact status.
-- It must not perform research, write files, create `deck-plan.md`, generate decks, open Review UI, or export artifacts.
+- It must not perform research, write files, create `spec.md`, create `deck-plan.md`, generate decks, open Review UI, or export artifacts.
 - Keep the answer short and operational.
 
 ## Preconditions
@@ -21,7 +22,7 @@ Use this skill when the user asks what Revela is, what the current workspace sta
 ## Inputs
 
 - User questions about Revela, current status, active design/domain, or next workflow step.
-- Optional workspace context such as existing `researches/`, `deck-plan.md`, `decks/*.html`, and `assets/`.
+- Optional workspace context such as existing `spec.md`, `researches/`, `deck-plan.md`, `decks/*.html`, and `assets/`.
 
 ## Required Tools
 
@@ -37,11 +38,12 @@ Report:
 - What Revela does: trusted, traceable, deck-first decision artifacts from local materials, research, data, and user intent.
 - 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.
+- Workspace artifact status: whether `spec.md`, `researches/`, `deck-plan.md`, `decks/*.html`, and `assets/` appear available.
 - Recommended next step:
   - Custom visual system requested: use `revela-design`.
   - Custom narrative domain guidance requested: use `revela-domain`.
-  - No `researches/`: run `revela-research`.
+  - No `spec.md` or unclear objective: run `revela-spec`.
+  - `spec.md` exists but 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.
@@ -50,6 +52,7 @@ Report:
 
 - Do not write or patch files.
 - Do not do external web research.
+- Do not generate or repair `spec.md`.
 - 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

@@ -11,6 +11,7 @@ Use this skill when the user asks to make, generate, render, or update a Revela
 
 - Deck execution planning comes from canonical `deck-plan.md`.
 - Local materials, material reviews, `researches/`, `assets/`, and user intent provide source context.
+- Slide argument copy comes from `deck-plan.md` `Claim`, `Reasoning`, and `Audience takeaway` fields when present; raw findings are evidence/source context, not default body copy.
 - 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`.
@@ -22,7 +23,7 @@ Use this skill when the user asks to make, generate, render, or update a Revela
 
 - 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 missing, stop and tell the user to run `revela` for routing, `revela-spec` for missing requirements, or `revela-research` for the Planning Handoff.
 - If `deck-plan.md` is structurally invalid, only repair technical plan diagnostics reported during render preflight.
 
 ## Inputs
@@ -61,7 +62,9 @@ Allowed plan repairs are limited to technical diagnostics from `revela_read_deck
 - 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.
 
-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.
+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` routing or `revela-research` Planning Handoff.
+
+If a non-structural slide plan has source links but lacks `Claim`, `Reasoning`, or `Audience takeaway`, treat it as synthesis-thin: do not fill the gap by copying raw findings into slide body copy. Report that the plan needs `revela-research` Planning Handoff repair.
 
 ## Render Phase
 
@@ -70,14 +73,15 @@ Use this phase when the user asks to make, generate, render, or update an HTML d
 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.
 3. For new HTML files, call `revela_create_deck_foundation`.
-4. Generate one `htmlWritingBatches` entry at a time.
-5. A single HTML write/edit/apply_patch may add or rewrite at most 5 slide sections.
-6. If a chapter is longer than 5 slides, use the consecutive batch parts returned by `revela_read_deck_plan`.
-7. Patch slides into the foundation between Revela slide markers.
-8. Preserve positive 1-based `data-slide-index` values.
-9. Every slide must have exactly one direct `.slide-canvas` child.
-10. Keep the HTML valid after each write.
-11. After every HTML write, call `revela_run_deck_qa` and repair hard errors before continuing, review, or export.
+4. Use the deck-plan's `Claim`, `Reasoning`, and `Audience takeaway` as the primary slide copy. Keep finding text in source notes, captions, evidence charts, or speaker notes unless the plan explicitly calls for a direct evidence quote.
+5. Generate one `htmlWritingBatches` entry at a time.
+6. A single HTML write/edit/apply_patch may add or rewrite at most 5 slide sections.
+7. If a chapter is longer than 5 slides, use the consecutive batch parts returned by `revela_read_deck_plan`.
+8. Patch slides into the foundation between Revela slide markers.
+9. Preserve positive 1-based `data-slide-index` values.
+10. Every slide must have exactly one direct `.slide-canvas` child.
+11. Keep the HTML valid after each write.
+12. After every HTML write, call `revela_run_deck_qa` and repair hard errors before continuing, review, or export.
 
 ## Outputs
 

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

@@ -1,6 +1,6 @@
 ---
 name: revela-research
-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.
+description: Research from an existing or emerging Revela spec.md and public/workspace sources, using active domain/design guidance to save source-linked findings and hand off deck-plan.md.
 ---
 
 # Revela Research
@@ -10,6 +10,7 @@ Use this skill when the user asks to start from a goal, inspect local materials,
 ## Contract
 
 - Research is the source-preparation workflow for Codex Revela.
+- Prefer root-level `spec.md` as the demand contract. If it is missing or the objective is unclear, route to `revela-spec` unless the user gave enough intent to research immediately.
 - 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.
@@ -21,11 +22,12 @@ Use this skill when the user asks to start from a goal, inspect local materials,
 
 ## Preconditions
 
-- The user provides at least one of: objective, topic, audience, decision/action, source materials, or deck intent.
+- The user provides at least one of: existing `spec.md`, objective, topic, audience, decision/action, source materials, or deck intent.
 - If intent is unclear, inspect the workspace first and ask only the smallest missing high-impact questions.
 
 ## Inputs
 
+- Root-level `spec.md` when present.
 - User objective, constraints, audience, decision/action, and language preference when available.
 - Workspace materials, extracted material read views, existing `researches/**/*.md`, existing `deck-plan.md`, and `assets/`.
 - Active or user-requested domain guidance.
@@ -35,14 +37,15 @@ Use this skill when the user asks to start from a goal, inspect local materials,
 
 1. Call `revela_domain_list`.
 2. Call `revela_domain_read` for the active domain or user-requested domain.
-3. Call `revela_prepare_local_materials`.
-4. For Office/PDF sources, read the provided `allowedReadPath` / `read_view_path`; if missing, call `revela_extract_document_materials`.
-5. Read original text/Markdown/CSV files or extracted read views before treating a material as usable.
-6. Call `revela_record_material_review` for each reviewed Office/PDF source.
-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:
+3. Read `spec.md` when present and use it to scope material review, findings, and deck-plan handoff.
+4. Call `revela_prepare_local_materials`.
+5. For Office/PDF sources, read the provided `allowedReadPath` / `read_view_path`; if missing, call `revela_extract_document_materials`.
+6. Read original text/Markdown/CSV files or extracted read views before treating a material as usable.
+7. Call `revela_record_material_review` for each reviewed Office/PDF source.
+8. Call `revela_check_material_intake` before reporting research readiness.
+9. Use external research only for public facts, user-authorized questions, or gaps not covered by local materials or `spec.md`.
+10. Save useful findings with `revela_research_save`.
+11. 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`.
@@ -52,17 +55,55 @@ Use this skill when the user asks to start from a goal, inspect local materials,
 
 ## Finding Requirements
 
-Each saved finding should include:
+Saved research should use stable, reusable Markdown blocks. Evidence findings use:
+
+```md
+## Finding: <stable-id>
+
+Source: <source name and date when known>
+URL: <source URL when available>
+Location: <page/slide/sheet/section when known>
+Quote/Snippet: <short exact quote or compact snippet; note when no exact quote is available>
+Supports: <narrow support scope or intended slide/source context>
+Evidence boundary: <internal guardrail; what this finding does not prove>
+Strength: <strong|directional|weak|context-only>
+Deck use: <where this belongs in deck planning>
+Display note: <optional short user-facing scope note for captions/source notes>
+```
+
+Use synthesis blocks to turn multiple findings into decision-relevant interpretation before deck planning:
+
+```md
+## Synthesis: <stable-id>
+
+Question answered: <research question this synthesis resolves>
+Basis: <finding ids, source files, or URLs used>
+Interpretation: <what the evidence means when read together>
+So what: <why this matters for the audience or decision>
+Decision implication: <what should change in the recommendation, story, or slide argument>
+Confidence: <high|medium|low>
+Alternative reading: <plausible competing interpretation or contradiction>
+Evidence boundary: <internal guardrail; what this synthesis must not overclaim>
+Deck use: <where this belongs in deck planning>
+Display note: <optional short user-facing scope note>
+```
+
+Use `## Analysis: <stable-id>` for user/LLM analytical frameworks, `## Implementation Note: <stable-id>` for render/data/API contracts, `## Asset Lead: <stable-id>` for image/logo/media leads, and `## Gaps` for missing or insufficient source support.
+
+Each saved evidence finding should include:
 
 - Source URL or workspace path.
 - Quote/snippet or explicit note when no exact quote is available.
 - What it supports.
-- What it does not support.
-- Caveat or limitation.
+- `Evidence boundary` for internal support limits, unsupported scope, or uncertainty.
+- `Deck use` for likely planning placement.
+- Optional `Display note` for short audience-facing scope text.
 - Date checked.
 - Optional image/logo/screenshot leads with known source and license/attribution status.
 
-If a finding is context only, label it as context and do not present it as proof.
+If a finding is context only, label it as context and do not present it as proof. Internal boundaries must not be mechanically copied into deck text; use `Display note` for default visible caption/source-note scope, and expose `Evidence boundary` only when needed to avoid a misleading audience conclusion.
+
+Do not use raw findings as the default deck argument. For deck goals, synthesize findings first; findings provide evidence basis, while `Synthesis` provides the interpretation, decision implication, and audience takeaway that should drive `deck-plan.md`.
 
 ## Outputs
 
@@ -82,12 +123,17 @@ Each non-structural slide block must include:
 
 - Slide title and role when relevant.
 - `#### Content Plan`
-- `#### Source Links` for materials, findings, assets, URLs, and caveats.
+- In `#### Content Plan`: `Claim`, `Reasoning`, `Audience takeaway`, `Evidence basis`, and `Boundary handling`.
+- `#### Source Links` for materials, finding-level references when available, 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.
+- Base slide arguments on `Synthesis` blocks when available; use finding text as evidence/source context, not as default body copy.
+- Use `Display note` for short visible caption/source-note scope.
+- Keep `Evidence boundary` internal unless it is required to avoid a misleading audience conclusion.
+- `Analysis` and `Implementation Note` entries may support deck structure or rendering, but must not be cited as external factual proof.
 - 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.
@@ -95,6 +141,7 @@ Do not duplicate the same child as both nested and top-level. Do not add source
 ## Must Not
 
 - Do not generate `revela-narrative/`.
+- Do not write `spec.md`; route demand changes to `revela-spec`.
 - 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/plugins/revela/skills/revela-spec/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: revela-spec
+description: Discover Revela artifact requirements and write a root-level spec.md before research or deck planning. Use when the user goal, audience, output type, constraints, acceptance criteria, or next workflow step is unclear or not yet captured.
+---
+
+# Revela Spec
+
+Use this skill to turn user intent and available workspace context into a concise root-level `spec.md` demand contract.
+
+## Contract
+
+- `spec.md` is the canonical demand and task specification for Codex Revela.
+- The spec answers what to build, for whom, why it matters, what constraints apply, and how success will be judged.
+- Local materials may be inspected only to ground scope and identify available inputs.
+- This skill does not own research findings, deck planning, deck rendering, Review, or Export.
+- Ask the smallest missing high-impact questions after local inspection.
+
+## Preconditions
+
+- The user provides at least one of: objective, topic, audience, decision/action, source material, desired artifact, or open problem.
+- If no local workspace exists, write the spec from user intent and mark material gaps explicitly.
+
+## Inputs
+
+- User objective, audience, decision/action, output type, language, style, constraints, and deadline when available.
+- Existing workspace context: local materials, `researches/`, `deck-plan.md`, `decks/*.html`, `assets/`, active design, and active domain.
+
+## Workflow
+
+1. Call `revela_doctor` to inspect workspace state.
+2. Call `revela_domain_list` to capture active narrative guidance.
+3. Call `revela_design_list` to capture active design guidance.
+4. Call `revela_prepare_local_materials` when local material awareness is needed for scope.
+5. For Office/PDF sources, do not treat them as reviewed evidence unless extracted/read in a later `revela-research` workflow.
+6. Ask only for missing information that materially changes the spec or next step.
+7. Write or update root-level `spec.md`.
+8. End by recommending the next specialist skill:
+   - `revela-research` when sources or findings are needed.
+   - `revela-make-deck` only when a valid `deck-plan.md` already exists and the spec does not require new source work.
+   - `revela-design` or `revela-domain` when the spec requires custom guidance first.
+
+## spec.md Requirements
+
+`spec.md` must include these sections:
+
+- `# Spec`
+- `## Objective`
+- `## Audience`
+- `## Decision Or Action`
+- `## Output`
+- `## Constraints`
+- `## Available Materials`
+- `## Known Gaps`
+- `## Acceptance Criteria`
+- `## Recommended Next Step`
+
+Use explicit `Unknown` or `Pending user input` entries instead of inventing requirements.
+
+## Outputs
+
+- Root-level `spec.md`.
+- A short summary of open questions, source limitations, and the recommended next skill.
+
+## Must Not
+
+- Do not write `researches/**/*.md`.
+- 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 or unreviewed local files as source evidence.
+- Do not invent requirements, constraints, citations, source paths, URLs, numbers, licenses, or acceptance criteria.

package/tools/research-save.ts

@@ -6,7 +6,8 @@ export default tool({
     "Save a research findings file to the workspace researches/ directory. " +
     "Creates researches/{topic}/{filename}.md with YAML frontmatter. " +
     "Each research axis gets its own file (e.g. 'market-data', 'catl-profile'). " +
-    "Content should use ## Data / ## Cases / ## Images / ## Gaps sections.",
+    "Content should use structured blocks such as ## Finding: <stable-id>, ## Synthesis: <stable-id>, ## Analysis: <stable-id>, " +
+    "## Implementation Note: <stable-id>, ## Asset Lead: <stable-id>, and ## Gaps.",
   args: {
     topic: tool.schema
       .string()
@@ -23,10 +24,12 @@ export default tool({
     content: tool.schema
       .string()
       .describe(
-        "Structured markdown findings. Use these sections (omit empty ones):\n" +
-        "## Data — key stats and data points, each with [Source: url]\n" +
-        "## Cases — company/entity profiles, 1-2 sentences each with [Source: url]\n" +
-        "## Images — image URLs: '{description}: {url} | Alt: {text} | Use: logo|screenshot|portrait'\n" +
+        "Structured markdown findings. Prefer stable cards:\n" +
+        "## Finding: <stable-id> — evidence with Source, URL/path, Quote/Snippet, Supports, Evidence boundary, Strength, Deck use, and optional Display note\n" +
+        "## Synthesis: <stable-id> — interpretation across findings with Basis, Interpretation, So what, Decision implication, Confidence, Alternative reading, Evidence boundary, Deck use, and optional Display note\n" +
+        "## Analysis: <stable-id> — LLM/user analytical frameworks; not external factual proof\n" +
+        "## Implementation Note: <stable-id> — render/data/API contracts; not market evidence\n" +
+        "## Asset Lead: <stable-id> — image/logo/media leads with source, license/attribution status, alt text, and deck use\n" +
         "## Gaps — topics not found or insufficiently covered",
       ),
     sources: tool.schema