@cyber-dash-tech/revela 0.18.7 → 0.18.9

package/README.md

@@ -2,7 +2,7 @@
 
 **English** | [中文](README.zh-CN.md)
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-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-723%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.9 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.9
 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.9 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-723%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.9 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.9
 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.9 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.",