@cyber-dash-tech/revela 0.17.6 → 0.17.7

package/README.md

@@ -2,19 +2,21 @@
 
 **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-546%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-609%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="560" />
 </p>
 
-Revela is an [OpenCode](https://opencode.ai) plugin that turns local sources and research into a traceable narrative graph, then renders that graph into briefs and presentation decks.
+Revela works from [OpenCode](https://opencode.ai) and Codex to turn source materials, research, data, and intent into trusted, traceable, presentation-ready decision artifacts.
 
-The narrative graph records the core elements needed to generate a brief or deck: audience, decision, claims, evidence, sources, risks, objections, and open gaps.
+Its narrative workspace records the core elements needed to generate a brief or deck: audience, decision, claims, evidence, sources, risks, objections, and open gaps.
 
 ## Install
 
-Add Revela to your `opencode.json`:
+### OpenCode
+
+Install Revela through `opencode.json` with the npm package `@cyber-dash-tech/revela`:
 
 ```json
 {
@@ -27,6 +29,19 @@ Restart OpenCode.
 
 To install globally, add the same entry to `~/.config/opencode/opencode.json`.
 
+### Codex
+
+Install Revela through the Codex Git marketplace:
+
+```bash
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref main
+codex plugin add revela@revela
+```
+
+Install from the full repository ref. Do not use a sparse checkout limited to `plugins/revela`; the Codex plugin resolves the shared runtime, built-in designs, and domains from the repository snapshot.
+
+Use a release tag instead of `main` when you want a pinned install.
+
 ## Built-In Designs
 
 Revela includes built-in deck designs:
@@ -55,6 +70,8 @@ Switch designs with:
 /revela design --use summit
 ```
 
+In Codex, ask Revela to list or switch designs; the plugin uses the active design when making decks.
+
 ## Domains
 
 Domains add topic-specific narrative guidance, such as consulting, product, or investor communication. Use them when you want Revela to adapt story framing to a specific context.
@@ -63,52 +80,15 @@ Domains add topic-specific narrative guidance, such as consulting, product, or i
 /revela domain
 ```
 
-## Quick Start: Make An HTML Deck
+In Codex, ask Revela to list or switch domains; the active domain guides narrative framing during init, research, and story work.
 
-1. Initialize the narrative workspace from your local source materials.
+## Quick Start
 
-```text
-/revela init
-```
-
-2. Research missing evidence and bind useful findings to claims.
-
-```text
-/revela research
-```
-
-Skip this step if your local materials already provide enough support.
+Start with the local source materials and intent that should ground the communication. Revela identifies the audience, decision, claims, evidence, risks, objections, and gaps that shape the narrative.
 
-3. Inspect the claim flow before rendering.
+When evidence is missing, use research to gather findings and bind only the supported parts back to the narrative. Before rendering, read the Story view to inspect the claim flow, evidence support, caveats, and open gaps.
 
-```text
-/revela story
-```
-
-Use this to check the audience, decision, claims, evidence, gaps, risks, and objections.
-
-4. Generate the HTML deck.
-
-```text
-/revela make --deck
-```
-
-Revela writes the deck under `decks/` and uses the current narrative, deck plan, and active design.
-
-5. Review or revise the deck.
-
-```text
-/revela review --deck
-```
-
-See [Review A Deck](#review-a-deck) for Insight and Comment.
-
-6. Export if needed.
-
-```text
-/revela export --deck pdf decks/example.html
-/revela export --deck pptx decks/example.html
-```
+Make a deck or brief from the canonical narrative when the story is ready to present. Review the artifact with Insight to understand support and traceability, use Comment for targeted changes, and export to PDF or PPTX when you need a shareable file.
 
 ## Review A Deck
 

package/README.zh-CN.md

@@ -2,19 +2,21 @@
 
 [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-546%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-609%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="560" />
 </p>
 
-Revela 是一个 [OpenCode](https://opencode.ai) 插件，用来把本地材料和调研结果转成可追踪的叙事图谱，再基于这个图谱生成 brief 和 presentation deck。
+Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材料、调研、数据和用户意图转成可信、可追踪、可直接用于决策沟通的 narrative artifact。
 
-叙事图谱用 graph 方式记录生成 brief 或 deck 所需的关键要素：受众、决策目标、论点、论据、资料来源、风险、潜在质疑和待补齐的信息。
+它的 narrative workspace 会记录生成 brief 或 deck 所需的关键要素：受众、决策目标、论点、论据、资料来源、风险、潜在质疑和待补齐的信息。
 
 ## 安装
 
-在 `opencode.json` 中加入 Revela：
+### OpenCode
+
+通过 `opencode.json` 安装 npm package `@cyber-dash-tech/revela`：
 
 ```json
 {
@@ -27,6 +29,19 @@ Revela 是一个 [OpenCode](https://opencode.ai) 插件，用来把本地材料
 
 如果想全局安装，把同样配置写到 `~/.config/opencode/opencode.json`。
 
+### Codex
+
+通过 Codex Git marketplace 安装 Revela：
+
+```bash
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref main
+codex plugin add revela@revela
+```
+
+请从完整仓库 ref 安装。不要使用仅包含 `plugins/revela` 的 sparse checkout；Codex plugin 会从仓库快照中解析 shared runtime、内置 designs 和 domains。
+
+如果需要固定版本，把 `main` 换成 release tag。
+
 ## 内置设计
 
 Revela 内置多个 deck design：
@@ -55,6 +70,8 @@ Revela 内置多个 deck design：
 /revela design --use summit
 ```
 
+在 Codex 中，可以直接让 Revela 列出或切换 design；生成 deck 时会使用 active design。
+
 ## Domains
 
 Domain 提供特定场景的叙事 guidance，例如 consulting、product 或 investor communication。需要让 Revela 按具体沟通场景调整 story framing 时使用。
@@ -63,52 +80,15 @@ Domain 提供特定场景的叙事 guidance，例如 consulting、product 或 in
 /revela domain
 ```
 
-## Quick Start：生成 HTML Deck
+在 Codex 中，可以直接让 Revela 列出或切换 domain；active domain 会用于 init、research 和 story 阶段的叙事 framing。
 
-1. 从本地来源材料初始化 narrative workspace。
+## Quick Start
 
-```text
-/revela init
-```
-
-2. 补充缺失证据，并把有效 findings 绑定到 claims。
-
-```text
-/revela research
-```
-
-如果本地材料已经足够支撑 story，可以跳过这一步。
+从本地来源材料和沟通意图开始，让 Revela 识别受众、决策目标、论点、论据、风险、潜在质疑和信息缺口。
 
-3. 在生成 deck 前检查 claim flow。
+证据不足时，用 research 补充 findings，并只把被来源明确支持的部分绑定回 narrative。渲染前先阅读 Story view，检查 claim flow、证据支撑、caveat 和 open gap。
 
-```text
-/revela story
-```
-
-用它检查 audience、decision、claims、evidence、gaps、risks 和 objections。
-
-4. 生成 HTML deck。
-
-```text
-/revela make --deck
-```
-
-Revela 会把 deck 写到 `decks/`，并使用当前 narrative、deck plan 和 active design。
-
-5. Review 或修改 deck。
-
-```text
-/revela review --deck
-```
-
-详见 [Review Deck](#review-deck)。
-
-6. 按需导出。
-
-```text
-/revela export --deck pdf decks/example.html
-/revela export --deck pptx decks/example.html
-```
+当 story 已经适合呈现时，从 canonical narrative 生成 deck 或 brief。之后用 Insight 理解 artifact 的支撑关系和可追踪性，用 Comment 做定向修改，需要分享文件时再导出为 PDF 或 PPTX。
 
 ## Review Deck
 

package/bin/revela.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env bun
+
+type CommandResult = unknown | Promise<unknown>
+
+const [argvCommand, ...args] = process.argv.slice(2)
+const command = process.env.REVELA_CLI_COMMAND || argvCommand
+
+if (!command || command === "help" || command === "--help" || command === "-h") {
+  printHelp()
+  process.exit(0)
+}
+
+if (command === "mcp") {
+  await import("../plugins/revela/mcp/revela-server")
+}
+else {
+  const runtime = await import("../lib/runtime/index")
+  const options = parseArgs(args)
+
+  try {
+    let result: CommandResult
+    if (command === "doctor") result = runtime.doctor(options)
+    else if (command === "compile") result = runtime.compileNarrative(options)
+    else if (command === "markdown-qa") result = runtime.markdownQa(options)
+    else if (command === "deck-plan") result = runtime.readDeckPlan(options)
+    else if (command === "deck-foundation") result = runtime.createDeckFoundation(required(options, ["outputPath", "title", "language"]))
+    else if (command === "qa") result = runtime.runDeckQa(required(options, ["file"]))
+    else if (command === "review-read") result = runtime.reviewDeckRead(required(options, ["file"]))
+    else if (command === "export-pdf") result = runtime.exportPdf(required(options, ["file"]))
+    else if (command === "export-pptx") result = runtime.exportPptx(required(options, ["file"]))
+    else if (command === "design-list") result = runtime.designList()
+    else if (command === "design-read") result = runtime.designRead(options)
+    else if (command === "design-use") result = runtime.designActivate(required(options, ["name"]))
+    else if (command === "domain-list") result = runtime.domainList()
+    else if (command === "domain-read") result = runtime.domainRead(options)
+    else if (command === "domain-use") result = runtime.domainActivate(required(options, ["name"]))
+    else {
+      throw new Error(`Unknown command: ${command}`)
+    }
+
+    process.stdout.write(`${JSON.stringify(await result, null, 2)}\n`)
+  } catch (e) {
+    process.stderr.write(`${e instanceof Error ? e.message : String(e)}\n`)
+    process.exit(1)
+  }
+}
+
+function parseArgs(values: string[]): Record<string, any> {
+  const result: Record<string, any> = {}
+  for (let i = 0; i < values.length; i++) {
+    const arg = values[i]
+    if (!arg.startsWith("--")) throw new Error(`Unexpected argument: ${arg}`)
+    const key = arg.slice(2)
+    const next = values[i + 1]
+    if (next === undefined || next.startsWith("--")) {
+      result[key] = true
+      continue
+    }
+    result[key] = parseValue(next)
+    i++
+  }
+  return result
+}
+
+function parseValue(value: string): unknown {
+  if (value === "true") return true
+  if (value === "false") return false
+  return value
+}
+
+function required(input: Record<string, any>, keys: string[]): Record<string, any> {
+  const missing = keys.filter((key) => input[key] === undefined || input[key] === "")
+  if (missing.length > 0) throw new Error(`Missing required option(s): ${missing.map((key) => `--${key}`).join(", ")}`)
+  return input
+}
+
+function printHelp(): void {
+  process.stdout.write(`Revela CLI
+
+Usage:
+  revela mcp
+  revela doctor [--workspaceRoot <path>]
+  revela compile [--workspaceRoot <path>]
+  revela markdown-qa [--workspaceRoot <path>] [--scope touched|affected|full] [--strictness authoring|readiness|render]
+  revela deck-plan [--workspaceRoot <path>]
+  revela deck-foundation --outputPath <path> --title <title> --language <tag> [--workspaceRoot <path>] [--designName <name>] [--mode create|repair] [--overwrite true]
+  revela qa --file <path> [--workspaceRoot <path>]
+  revela review-read --file <path> [--workspaceRoot <path>] [--format json|markdown]
+  revela export-pdf --file <path> [--workspaceRoot <path>]
+  revela export-pptx --file <path> [--workspaceRoot <path>]
+  revela design-list
+  revela design-read [--name <design>]
+  revela design-use --name <design>
+  revela domain-list
+  revela domain-read [--name <domain>]
+  revela domain-use --name <domain>
+`)
+}

package/lib/edit/prompt.ts

@@ -26,6 +26,7 @@ export interface EditCommentPayload extends EditSelectedElementPayload {
   comments?: EditCommentDraftPayload[]
   asset?: Record<string, unknown>
   drop?: Record<string, unknown>
+  suppressAutomaticArtifactQa?: boolean
 }
 
 export function buildEditPrompt(payload: EditCommentPayload): string {
@@ -59,6 +60,10 @@ export function buildEditPrompt(payload: EditCommentPayload): string {
     asset: payload.asset,
     drop: payload.drop,
   }
+  const qaInstruction = payload.suppressAutomaticArtifactQa
+    ? `- Do not run artifact QA after this edit and do not keep editing just to satisfy post-write QA. The Review UI will refresh from the deck file version change; QA can be run later through an explicit Review, QA, or export workflow.`
+    : `- Artifact QA runs automatically after deck writes/patches/edits. It checks deck HTML contract, design component compliance, exact 1920x1080 slide geometry, scrollbars, element overflow, text clipping, and claim/evidence content-density warnings.
+- If the tool result reports hard QA errors, fix them with the smallest targeted patch and let the post-write QA run again. Refine opens automatically only after hard errors pass; warnings such as thin claim/evidence substance do not block opening.`
 
   return `The user left a visual edit comment on a Revela slide deck.
 
@@ -95,7 +100,6 @@ Instructions:
 - For targeted artifact-level edits, patch ${"`decks/*.html`"} directly. Do not call ${"`revela-decks`"} action ${"`review`"} as a precondition, and do not let ${"`writeReadiness`"}, ${"`planReview`"}, or ${"`slide_plan_unconfirmed`"} block the patch.
 - Do not patch or write ${"`DECKS.json`"} directly. If state must change, use the ${"`revela-decks`"} tool.
 - Apply the edit to ${payload.file} with the smallest targeted HTML patch that satisfies the comment.
-- Artifact QA runs automatically after deck writes/patches/edits. It checks deck HTML contract, design component compliance, exact 1920x1080 slide geometry, scrollbars, element overflow, text clipping, and claim/evidence content-density warnings.
-- If the tool result reports hard QA errors, fix them with the smallest targeted patch and let the post-write QA run again. Refine opens automatically only after hard errors pass; warnings such as thin claim/evidence substance do not block opening.
+${qaInstruction}
 - If the comment is ambiguous, ask one concise clarification question instead of guessing.`
 }

package/lib/edit/server.ts

@@ -1003,8 +1003,8 @@ export function renderEditorShell(token: string): string {
         if (status === 'updated') return 'Deck file updated';
         if (status === 'stale') return 'Still waiting for deck file update';
         if (status === 'failed') return 'Failed to send';
-        if (status === 'sending') return 'Sending to OpenCode...';
-        return '⏳ Sent to OpenCode';
+        if (status === 'sending') return 'Sending to Review agent...';
+        return 'Sent to Review agent';
       }
 
       function targetFromPointer(event) {

package/lib/inspect/prompt.ts

@@ -6,9 +6,11 @@ export function buildInspectionPrompt(input: {
   projection: InspectionPromptProjection
   language?: string
   comment?: string
+  delivery?: "tool" | "json"
 }): string {
   const language = normalizeInspectLanguage(input.language)
   const comment = typeof input.comment === "string" && input.comment.trim() ? input.comment.trim() : ""
+  const delivery = input.delivery ?? "tool"
   return `A user selected slide content in Revela Evidence Inspector. The selection may contain one referenced element, a whole slide, or multiple referenced elements selected with Cmd/Ctrl-click.
 
 Target file: ${input.file}
@@ -20,7 +22,9 @@ Use the structured projection below to produce the final inspector cards. This i
 
 Language boundary: the selected display language affects only human-readable card copy. Preserve all claim ids, canonical claim ids, evidence binding ids, source paths, findings files, URLs, numbers, quoted/source facts, caveats, artifact ids, and coverage statuses exactly as grounded in the projection. If the display language is Auto, use projection.deck.language when available; otherwise follow the user's/browser context or default to English.
 
-Return the result only by calling the \`revela-inspection-result\` tool with this request id. Do not answer in chat.
+${delivery === "json"
+    ? "Return only a single JSON object that matches the final inspector result schema. Do not wrap it in Markdown. Do not call tools. Do not edit files."
+    : "Return the result only by calling the `revela-inspection-result` tool with this request id. Do not answer in chat."}
 
 Required card model:
 - User inspect comment: if present, answer it through the Purpose and Source cards first. If it asks about trust, provenance, evidence, factuality, or where a number came from, prioritize Source. If it asks why something is on the slide or what it is doing, prioritize Purpose.

package/lib/refine/comment-requests.ts

@@ -0,0 +1,77 @@
+export type CommentRequestStatus = "pending" | "completed" | "failed" | "expired"
+
+export interface PendingCommentRequest {
+  requestId: string
+  status: CommentRequestStatus
+  deckVersion: string
+  createdAt: number
+  updatedAt: number
+  error?: string
+}
+
+const REQUEST_TTL_MS = 120 * 1000
+const requests = new Map<string, PendingCommentRequest>()
+
+export function createCommentRequest(input: {
+  requestId: string
+  deckVersion: string
+}): PendingCommentRequest {
+  cleanupCommentRequests()
+  const now = Date.now()
+  const request: PendingCommentRequest = {
+    requestId: input.requestId,
+    status: "pending",
+    deckVersion: input.deckVersion,
+    createdAt: now,
+    updatedAt: now,
+  }
+  requests.set(input.requestId, request)
+  return request
+}
+
+export function getCommentRequest(requestId: string): PendingCommentRequest | undefined {
+  cleanupCommentRequests()
+  const request = requests.get(requestId)
+  if (!request) return undefined
+  if (request.status === "pending" && Date.now() - request.createdAt > REQUEST_TTL_MS) {
+    request.status = "expired"
+    request.error = "Review agent timed out before completing the comment request."
+    request.updatedAt = Date.now()
+  }
+  return request
+}
+
+export function completeCommentRequest(requestId: string): PendingCommentRequest | undefined {
+  const request = getCommentRequest(requestId)
+  if (!request || request.status !== "pending") return request
+  request.status = "completed"
+  request.updatedAt = Date.now()
+  return request
+}
+
+export function failCommentRequest(requestId: string, error: string): PendingCommentRequest | undefined {
+  const request = getCommentRequest(requestId)
+  if (!request || request.status !== "pending") return request
+  request.status = "failed"
+  request.error = error
+  request.updatedAt = Date.now()
+  return request
+}
+
+export function cleanupCommentRequests(now = Date.now()): void {
+  for (const [requestId, request] of requests) {
+    if (request.status === "pending" && now - request.createdAt > REQUEST_TTL_MS) {
+      request.status = "expired"
+      request.error = "Review agent timed out before completing the comment request."
+      request.updatedAt = now
+      continue
+    }
+    if (request.status !== "pending" && now - request.updatedAt > REQUEST_TTL_MS) {
+      requests.delete(requestId)
+    }
+  }
+}
+
+export function clearCommentRequestsForTests(): void {
+  requests.clear()
+}

package/lib/refine/open.ts

@@ -8,6 +8,7 @@ import { ensureEditableDeckState } from "../edit/deck-state"
 import { openUrl } from "../edit/open"
 import { resolveEditableDeck, type EditableDeck } from "../edit/resolve-deck"
 import { buildPrompt } from "../prompt-builder"
+import type { ReviewPromptBridge } from "./prompt-bridge"
 import { startRefineServer, type RefineMode } from "./server"
 
 export interface OpenRefineDeckResult {
@@ -27,12 +28,13 @@ export interface EnsureRefineDeckOpenResult extends OpenRefineDeckResult {
 }
 
 export interface OpenRefineDeckOptions {
-  client: any
-  sessionID: string
+  client?: any
+  sessionID?: string
   workspaceRoot: string
   mode?: RefineMode
   openBrowser?: boolean
   openUrl?: (url: string) => void
+  promptBridge?: ReviewPromptBridge
 }
 
 export function openRefineDeck(target: string, options: OpenRefineDeckOptions): OpenRefineDeckResult {
@@ -70,6 +72,7 @@ function openRefineDeckInternal(
     workspaceRoot: options.workspaceRoot,
     deck,
     mode,
+    promptBridge: options.promptBridge,
   })
   const url = `${refineServer.baseUrl}/refine?token=${encodeURIComponent(session.token)}`
   const shouldOpen = options.openBrowser !== false && !(behavior.skipLiveSession && session.live)