@cyber-dash-tech/revela 0.17.5 → 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/commands/review.ts

@@ -93,11 +93,12 @@ Workflow:
 6. If target slide count, audience, language, output purpose, or visual style is unclear, ask the user for the smallest needed confirmation before writing the plan.
 7. Write \`deck-plan/index.md\` and one file per planned slide under \`deck-plan/slides/*.md\` from the planning packet and requirements. The index must identify the chapter structure first: 3-5 chapter headings, each chapter's slide range, and which non-structural slides belong to each chapter. Each slide file must include frontmatter with positive 1-based \`slideIndex\` and \`## Narrative Links\` using plain wikilinks to canonical claim/evidence/risk/objection/gap ids. Include a low-fidelity ASCII/text layout sketch for every slide; do not generate visual images or HTML mockups.
 8. Stop after presenting the plan unless the user already asked to proceed. Ask whether to continue, revise the plan, or run more research. Do not require an Approval block or \`confirmDeckPlan\` gate; \`confirmDeckPlan\` is compatibility/provenance only.
-9. Ask for or confirm visual design only after the narrative deck plan exists. Fetch required design layouts/components with \`revela-designs read\` as needed.
-10. Do not update cached \`DECKS.json\` slide specs for plan authoring. Use \`deck-plan/\` files and artifact files as the execution surface.
-11. Call \`revela-decks\` action \`readDeckPlan\` before artifact review or HTML writing; use it to inspect the current deck-plan projection without regenerating it. Treat stale hashes, missing links, or incomplete coverage as advisory diagnostics unless the user asks to stop.
-12. Run artifact diagnostics when useful, but do not treat \`writeReadiness\`, cached slide specs, unconfirmed plans, missing research, or stale coverage as workflow blockers.
-13. Write \`decks/*.html\` when the user chooses to proceed and all deck HTML contract requirements can be satisfied. Generate the artifact chapter by chapter instead of drafting all content slides in one broad pass. Partial decks are allowed during chapter-by-chapter authoring when written slide sections have unique, increasing 1-based \`data-slide-index\` values and valid canvases; do not pad missing planned chapters with filler to match cached \`DECKS.json.slides[]\` length. Keep the HTML file valid after every write, preserve already-written slides, and update one chapter's slide sections at a time.
+9. Ask for or confirm visual design only after the narrative deck plan exists. For a new deck HTML file, call \`revela-deck-foundation\` first to create the active-design foundation shell; it must not create narrative slide content, choose layouts/components, or read/write \`${DECKS_STATE_FILE}\`.
+10. Fetch active design rules plus required layouts/components with \`revela-designs read\` as needed before patching slides into the foundation shell. Fetch chart rules before ECharts.
+11. Do not update cached \`DECKS.json\` slide specs for plan authoring. Use \`deck-plan/\` files and artifact files as the execution surface.
+12. Call \`revela-decks\` action \`readDeckPlan\` before artifact review or HTML writing; use it to inspect the current deck-plan projection without regenerating it. Treat stale hashes, missing links, or incomplete coverage as advisory diagnostics unless the user asks to stop.
+13. Run artifact diagnostics when useful, but do not treat \`writeReadiness\`, cached slide specs, unconfirmed plans, missing research, or stale coverage as workflow blockers.
+14. Write \`decks/*.html\` when the user chooses to proceed and all deck HTML contract requirements can be satisfied. For new files, patch slide sections between the \`revela-slides\` markers created by \`revela-deck-foundation\`. Generate the artifact chapter by chapter instead of drafting all content slides in one broad pass. Partial decks are allowed during chapter-by-chapter authoring when written slide sections have unique, increasing 1-based \`data-slide-index\` values and valid canvases; do not pad missing planned chapters with filler to match cached \`DECKS.json.slides[]\` length. Keep the HTML file valid after every write, preserve already-written slides, and update one chapter's slide sections at a time.
 15. For each chapter, make every content slide carry a distinct claim, evidence item, comparison, risk, or action. If a chapter lacks enough substance for its allocated slides, merge weak slides or reduce the slide count instead of creating sparse filler.
 16. After each HTML write, the system automatically runs artifact QA before opening Review. If post-write artifact QA reports hard errors, fix them and let QA run again. Review opens only after hard errors pass. Density warnings about thin claim/evidence substance should be reported and improved when useful, but they do not block Review.
 
@@ -142,6 +143,7 @@ Report format before any HTML write:
 - Start with \`Deck handoff: <status>\`.
 - Include which deck-plan projection and narrative hash are guiding artifact work.
 - State that \`revela-decks readDeckPlan\` was called and the current \`deck-plan/\` Chapter Writing Batches are being followed.
+- For new HTML files, state that \`revela-deck-foundation\` created the foundation shell and identify the output path/design before slide content is patched.
 - Include the chapter currently being generated and confirm already-written slides are being preserved.
 - If technical artifact checks cannot be satisfied, list those blockers separately from narrative/deck-plan diagnostics.
 - After writing HTML, read the appended \`Artifact QA\` report from the tool output. If it failed, fix hard errors before considering the deck ready for Review.
@@ -149,6 +151,7 @@ Report format before any HTML write:
 Rules:
 - \`compileDeckPlan\` prepares the canonical narrative claim/evidence packet and deck-plan requirements. The LLM authors \`deck-plan/index.md\` and \`deck-plan/slides/*.md\` from that packet and asks the user for page count, audience, language, output purpose, or visual style when unclear.
 - \`deck-plan/\` is the execution blueprint for HTML generation when present. It must be read before writing HTML and followed chapter by chapter; \`DECKS.json.slides[]\` is compatibility/cache data, not the HTML slide-count authority.
+- \`revela-deck-foundation\` is the file-native foundation helper for new deck shells. Use it before adding slides to a new \`decks/*.html\` file; do not use \`DECKS.json\` or \`revela-decks\` to create the shell.
 - Visual intent is part of the deck-plan projection. During HTML generation, satisfy the planned component/visual brief using fetched design components; do not collapse planned visuals into prose-only bullets.
 - Cached deck slide specs in \`DECKS.json\` are legacy projections only. Canonical narrative remains the authority for audience, decision, claims, evidence boundaries, objections, and risks.
 - Cover, Table of Contents, and Closing are mandatory deck structure. TOC chapter headings must match the chapter grouping used for generation.

package/lib/deck-html/foundation.ts

@@ -0,0 +1,190 @@
+import { existsSync, mkdirSync, writeFileSync } from "fs"
+import { dirname, isAbsolute, normalize, resolve } from "path"
+import { activeDesign, getDesignSection } from "../design/designs"
+
+export type DeckFoundationMode = "create" | "repair"
+export type DeckFoundationStatus = "created" | "updated"
+
+export interface CreateDeckFoundationInput {
+  workspaceRoot: string
+  outputPath: string
+  title: string
+  language: string
+  designName?: string
+  mode?: DeckFoundationMode
+  overwrite?: boolean
+}
+
+export interface CreateDeckFoundationResult {
+  ok: true
+  outputPath: string
+  design: string
+  includedSections: string[]
+  status: DeckFoundationStatus
+  next: string[]
+}
+
+interface FoundationParts {
+  fontLinks: string[]
+  cssBlocks: string[]
+  scriptBlocks: string[]
+}
+
+const SLIDES_START = "<!-- revela-slides:start -->"
+const SLIDES_END = "<!-- revela-slides:end -->"
+
+export function createDeckFoundation(input: CreateDeckFoundationInput): CreateDeckFoundationResult {
+  const outputPath = normalizeOutputPath(input.outputPath)
+  const targetPath = safeWorkspaceFilePath(input.workspaceRoot, outputPath)
+  const mode = input.mode ?? "create"
+  const canOverwrite = input.overwrite === true || mode === "repair"
+  const existed = existsSync(targetPath)
+
+  if (existed && !canOverwrite) {
+    throw new Error(`Deck HTML already exists at ${outputPath}. Pass overwrite=true or mode=repair to replace the foundation shell.`)
+  }
+
+  const design = input.designName || activeDesign()
+  const foundation = getDesignSection("foundation", design)
+  const parts = parseFoundationParts(foundation)
+  if (parts.cssBlocks.length === 0) throw new Error(`Design '${design}' foundation does not include a CSS code block.`)
+  if (parts.scriptBlocks.length === 0) throw new Error(`Design '${design}' foundation does not include a SlidePresentation JavaScript code block.`)
+
+  const html = renderFoundationHtml({
+    language: input.language || "en",
+    title: input.title || "Revela Deck",
+    fontLinks: parts.fontLinks,
+    css: parts.cssBlocks.join("\n\n"),
+    script: parts.scriptBlocks.map(guardEmptyDeckNavigation).join("\n\n"),
+  })
+
+  mkdirSync(dirname(targetPath), { recursive: true })
+  writeFileSync(targetPath, html, "utf-8")
+
+  return {
+    ok: true,
+    outputPath,
+    design,
+    includedSections: [
+      "design:foundation",
+      parts.fontLinks.length > 0 ? "foundation:font-links" : "foundation:font-links:none",
+      "foundation:css",
+      "foundation:SlidePresentation",
+    ],
+    status: existed ? "updated" : "created",
+    next: [
+      "Fetch active design rules before patching slides.",
+      "Fetch required layouts and components from the design before adding slide content.",
+      "Patch slides between the revela-slides markers chapter by chapter, then run artifact QA.",
+    ],
+  }
+}
+
+export function normalizeOutputPath(outputPath: string): string {
+  const trimmed = outputPath.trim()
+  if (!trimmed) throw new Error("outputPath is required")
+  if (!trimmed.endsWith(".html")) throw new Error("Deck foundation outputPath must end in .html")
+  if (isAbsolute(trimmed)) throw new Error("Deck foundation outputPath must be workspace-relative")
+  const segments = trimmed.split(/[\\/]+/)
+  if (segments.includes("..")) throw new Error("Deck foundation outputPath must not contain parent-directory traversal")
+  return normalize(trimmed).replace(/\\/g, "/")
+}
+
+function safeWorkspaceFilePath(workspaceRoot: string, outputPath: string): string {
+  const root = resolve(workspaceRoot)
+  const target = resolve(root, outputPath)
+  if (target !== root && !target.startsWith(`${root}/`)) {
+    throw new Error("Deck foundation outputPath must stay inside the workspace")
+  }
+  return target
+}
+
+function parseFoundationParts(foundation: string): FoundationParts {
+  const fontLinks = extractFontLinks(foundation)
+  const cssBlocks: string[] = []
+  const scriptBlocks: string[] = []
+  const fenceRe = /```([\w-]*)\n([\s\S]*?)```/g
+  let match: RegExpExecArray | null
+
+  while ((match = fenceRe.exec(foundation)) !== null) {
+    const lang = (match[1] || "").toLowerCase()
+    const body = match[2].trim()
+    if (!body) continue
+    if (lang === "css") cssBlocks.push(body)
+    if ((lang === "javascript" || lang === "js") && body.includes("class SlidePresentation")) {
+      scriptBlocks.push(body)
+    }
+  }
+
+  return { fontLinks, cssBlocks, scriptBlocks }
+}
+
+function extractFontLinks(foundation: string): string[] {
+  const links: string[] = []
+  const seen = new Set<string>()
+  const linkRe = /<link\b[^>]*(?:fonts\.googleapis|fonts\.gstatic|rel=["']preconnect["'])[^>]*>/gi
+  let match: RegExpExecArray | null
+  while ((match = linkRe.exec(foundation)) !== null) {
+    const link = match[0].trim()
+    if (seen.has(link)) continue
+    seen.add(link)
+    links.push(link)
+  }
+  return links
+}
+
+function guardEmptyDeckNavigation(script: string): string {
+  return script.replace(
+    /new\s+SlidePresentation\s*\(\s*\)\s*;?/g,
+    'if (document.querySelector(".slide")) { new SlidePresentation(); }',
+  )
+}
+
+function renderFoundationHtml(input: {
+  language: string
+  title: string
+  fontLinks: string[]
+  css: string
+  script: string
+}): string {
+  const fontLinks = input.fontLinks.map((link) => `    ${link}`).join("\n")
+  return [
+    "<!DOCTYPE html>",
+    `<html lang="${escapeAttribute(input.language)}">`,
+    "<head>",
+    "    <meta charset=\"UTF-8\">",
+    "    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">",
+    `    <title>${escapeHtml(input.title)}</title>`,
+    fontLinks,
+    "    <style>",
+    input.css,
+    "    </style>",
+    "</head>",
+    "<body>",
+    `    ${SLIDES_START}`,
+    `    ${SLIDES_END}`,
+    "    <script>",
+    input.script,
+    "    </script>",
+    "</body>",
+    "</html>",
+    "",
+  ].filter((line) => line !== "").join("\n")
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;")
+}
+
+function escapeAttribute(value: string): string {
+  return escapeHtml(value.trim() || "en")
+}
+
+export function deckFoundationMarkers(): { start: string; end: string } {
+  return { start: SLIDES_START, end: SLIDES_END }
+}

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/qa/index.ts

@@ -79,6 +79,7 @@ function scanAssetRefs(htmlFilePath: string): LayoutIssue[] {
     const ref = raw.trim()
     if (!ref || ref.startsWith("data:") || ref.startsWith("#") || ref.startsWith("mailto:") || ref.startsWith("tel:")) continue
     if (/^https?:\/\//i.test(ref) || ref.startsWith("//")) {
+      if (isAllowedRemoteRuntimeRef(ref)) continue
       issues.push({ type: "asset", sub: "remote_url", severity: "error", detail: `Deck HTML references remote asset URL \`${ref}\`. Save network images to workspace assets and reference the local file instead.` })
       continue
     }
@@ -96,6 +97,17 @@ function scanAssetRefs(htmlFilePath: string): LayoutIssue[] {
   return issues
 }
 
+function isAllowedRemoteRuntimeRef(ref: string): boolean {
+  try {
+    const url = new URL(ref.startsWith("//") ? `https:${ref}` : ref)
+    if (url.hostname === "fonts.googleapis.com" || url.hostname === "fonts.gstatic.com") return true
+    if (url.hostname === "cdn.jsdelivr.net" && url.pathname.startsWith("/npm/echarts@")) return true
+  } catch {
+    return false
+  }
+  return false
+}
+
 function looksLikeImageRef(ref: string): boolean {
   return /\.(?:png|jpe?g|webp|gif|svg)(?:[?#].*)?$/i.test(ref)
 }