npm - @cyber-dash-tech/revela - Versions diffs - 0.18.14 → 0.18.16 - Mend

@cyber-dash-tech/revela 0.18.14 → 0.18.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/README.md +35 -46
package/README.zh-CN.md +35 -46
package/bin/revela.ts +0 -0
package/designs/lucent/DESIGN.md +32 -1
package/designs/lucent/preview.html +411 -494
package/designs/monet/DESIGN.md +39 -9
package/designs/monet/preview.html +157 -2260
package/designs/starter/DESIGN.md +8 -5
package/designs/starter/preview.html +70 -49
package/designs/summit/DESIGN.md +36 -9
package/designs/summit/preview.html +139 -2237
package/lib/commands/designs-new.ts +9 -0
package/lib/design/designs.ts +84 -4
package/lib/prompt-builder.ts +4 -0
package/lib/qa/artifact.ts +52 -7
package/lib/qa/checks.ts +1 -1
package/lib/qa/component-contracts.ts +90 -0
package/package.json +1 -1
package/plugins/revela/.codex-plugin/plugin.json +4 -4
package/plugins/revela/.mcp.json +3 -2
package/plugins/revela/hooks/revela_post_write_notice.ts +39 -9
package/plugins/revela/mcp/revela-server.ts +3 -3
package/plugins/revela/skills/revela/SKILL.md +3 -3
package/plugins/revela/skills/revela-design/SKILL.md +6 -0
package/plugins/revela/skills/revela-helper/SKILL.md +3 -3
package/plugins/revela/skills/revela-make-deck/SKILL.md +9 -3
package/plugins/revela/skills/revela-research/SKILL.md +1 -0
package/skill/SKILL.md +11 -2
package/plugins/revela/skills/revela-review/SKILL.md +0 -46

package/README.md CHANGED Viewed

@@ -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-729%20passing-brightgreen)](tests/) [![Codex MCP](https://img.shields.io/badge/Codex-MCP-blue)](https://github.com/openai/codex) [![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-730%20passing-brightgreen)](tests/) [![Codex MCP](https://img.shields.io/badge/Codex-MCP-blue)](https://github.com/openai/codex) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 <p align="center">
   <img src="assets/img/logo-wordmark.png" alt="Revela" width="320" />
@@ -10,7 +10,7 @@
 Revela is a Codex plugin for turning source materials, research, data, and intent into trusted, traceable, presentation-ready decision artifacts.
-In your local workspace, Revela reviews materials, saves source-linked research, builds an explicit `deck-plan.md`, generates HTML decks, reviews them, and exports PDF/PPTX/PNG artifacts.
+In your local workspace, Revela reviews materials, saves source-linked research, builds an explicit `deck-plan.md`, generates HTML decks, surfaces them as Codex Browser website cards for annotation, and exports PDF/PPTX/PNG artifacts.
 ## Install
@@ -19,18 +19,17 @@ In your local workspace, Revela reviews materials, saves source-linked research,
 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.14 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.
+- Your environment must be able to run `bun`; Revela uses `bun ./mcp/revela-server.ts` from the installed Codex plugin cache to start the MCP server.
 Optional preflight:
 ```bash
 codex --version
 codex exec --help
-npx --version
+bun --version
 ```
-If `npx` fails with an npm cache permission error, repair the cache ownership or use a writable cache for local checks:
+If npm package checks fail with an npm cache permission error, repair the cache ownership or use a writable cache for local checks:
 ```bash
 sudo chown -R "$(id -u):$(id -g)" ~/.npm
@@ -40,19 +39,19 @@ 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.14
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.16
 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.14 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, it runs `bun ./mcp/revela-server.ts` from the installed plugin cache and resolves the checked-out marketplace runtime.
 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 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.
+Codex uses eight 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 HTML deck artifacts from an existing plan and surfacing the QA-passed deck as a Codex Browser website card, 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.
+For release-aligned local validation, run `bun run smoke:mcp-pack`. It packs the current checkout to a temporary npm tarball, extracts it, and starts the MCP server through the packaged Codex plugin launcher path without requiring a registry publish.
 #### Codex Upgrade
@@ -74,7 +73,7 @@ codex plugin marketplace upgrade revela
 codex plugin add revela@revela
 ```
-The Git marketplace ref and `.mcp.json` npm pin are part of the same release artifact. Start a new Codex thread after upgrading so Codex reloads the Revela skills, MCP tools, hooks, and runtime pin.
+The Git marketplace ref and `.mcp.json` plugin launcher are part of the same release artifact. Start a new Codex thread after upgrading so Codex reloads the Revela skills, MCP tools, hooks, and runtime launcher.
 ## Built-In Designs
@@ -83,32 +82,32 @@ Revela includes built-in deck designs:
 ### [summit](designs/summit/preview.html)
 <p align="center">
-  <img src="assets/img/summit-01.jpg" alt="Summit design preview 1" width="32%" />
-  <img src="assets/img/summit-02.jpg" alt="Summit design preview 2" width="32%" />
-  <img src="assets/img/summit-03.jpg" alt="Summit design preview 3" width="32%" />
+  <img src="assets/img/summit-01.jpg" alt="Summit design cover preview" width="32%" />
+  <img src="assets/img/summit-02.jpg" alt="Summit design narrative layout preview" width="32%" />
+  <img src="assets/img/summit-03.jpg" alt="Summit design timeline preview" width="32%" />
 </p>
 ### [monet](designs/monet/preview.html)
 <p align="center">
-  <img src="assets/img/monet-01.jpg" alt="Monet design preview 1" width="32%" />
-  <img src="assets/img/monet-02.jpg" alt="Monet design preview 2" width="32%" />
-  <img src="assets/img/monet-03.jpg" alt="Monet design preview 3" width="32%" />
+  <img src="assets/img/monet-01.jpg" alt="Monet design cover preview" width="32%" />
+  <img src="assets/img/monet-02.jpg" alt="Monet design narrative layout preview" width="32%" />
+  <img src="assets/img/monet-03.jpg" alt="Monet design timeline preview" width="32%" />
 </p>
 ### [lucent](designs/lucent/preview.html)
 <p align="center">
   <img src="assets/img/lucent-01.jpg" alt="Lucent design cover preview" width="32%" />
-  <img src="assets/img/lucent-02.jpg" alt="Lucent design table of contents preview" width="32%" />
-  <img src="assets/img/lucent-03.jpg" alt="Lucent design Sankey preview" width="32%" />
+  <img src="assets/img/lucent-02.jpg" alt="Lucent design narrative layout preview" width="32%" />
+  <img src="assets/img/lucent-03.jpg" alt="Lucent design roadmap preview" width="32%" />
 </p>
 `starter` is the clean default presentation style.
 To switch designs in Codex, ask:
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), use summit as the design.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), use summit as the design.
 In Codex, ask Revela to list or switch designs; the plugin uses the active design when making decks.
@@ -116,7 +115,7 @@ In Codex, ask Revela to list or switch designs; the plugin uses the active desig
 Domains add topic-specific communication guidance, such as consulting, product, or investor communication. Use them when you want Revela to adapt deck framing to a specific context.
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), list available domains.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), list available domains.
 In Codex, ask Revela to list or switch domains; the active domain guides deck framing during init, research, and planning.
@@ -126,62 +125,52 @@ Use these prompts in Codex from the workspace that contains your source material
 1. Choose the narrative domain before authoring so Revela frames the audience, decision, risks, and objections for your context.
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), use consulting as the domain.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), use consulting as the domain.
 2. Choose the deck design before rendering so generated artifacts use the intended visual language.
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), use summit as the design.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), use summit as the design.
 3. Create a custom design when you want a different visual direction.
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), create a new design named neon-finance with a crisp financial-dashboard style: dark surfaces, precise grids, and bright green accents.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), create a new design named neon-finance with a crisp financial-dashboard style: dark surfaces, precise grids, and bright green accents.
 Revela may ask for references or constraints, then creates and validates the design. When it is ready, switch to it:
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), use neon-finance as the design.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), use neon-finance as the design.
 4. Initialize local material intake. Init scans, extracts, and reviews workspace sources; it does not create a Narrative Vault.
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), help me init this workspace from the local materials.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), help me init this workspace from the local materials.
 5. Research source-linked deck inputs and save findings.
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), research the public evidence and examples needed for this deck.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), research the public evidence and examples needed for this deck.
 6. Create or update the deck plan before generating HTML so slide order, chapter structure, source links, unresolved inputs, source limitations, and visual intent are explicit.
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), create or update the deck plan before generating HTML.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), create or update the deck plan before generating HTML.
 7. Make an HTML deck from the current deck plan.
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), make the deck from the current deck plan.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), make the deck from the current deck plan.
-8. Review the generated deck for Artifact QA and targeted edits.
+8. Review and annotate the generated deck from the website card after make-deck completes.
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), review the generated deck.
+Use Codex Browser's native annotation tools on the opened HTML deck.
 9. Export a PDF after deck QA passes.
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), export the deck to PDF.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), export the deck to PDF.
 10. Export an editable PPTX after deck QA passes.
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), export the deck to PPTX.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), export the deck to PPTX.
 11. Export per-slide PNG files after deck QA passes.
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), export the deck to PNG.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), export the deck to PNG.
-## Review A Deck
+## Annotate A Deck
-Use Review after generating an HTML deck:
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), review the generated deck.
-<p align="center">
-  <img src="assets/img/review-ui.png" alt="Revela Review UI showing @ref comments and deck QA" width="900" />
-</p>
-Review opens a local deck workspace for QA and targeted edits:
-- Comment lets you request targeted edits on the deck, such as layout, copy, hierarchy, spacing, or visual changes.
+After `revela-make-deck` generates an HTML deck and Artifact QA passes, Codex replies with a website card that opens the deck in Codex Browser. Use the browser's native annotation tools for targeted edits such as layout, copy, hierarchy, spacing, or visual changes.

package/README.zh-CN.md CHANGED Viewed

@@ -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-729%20passing-brightgreen)](tests/) [![Codex MCP](https://img.shields.io/badge/Codex-MCP-blue)](https://github.com/openai/codex) [![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-730%20passing-brightgreen)](tests/) [![Codex MCP](https://img.shields.io/badge/Codex-MCP-blue)](https://github.com/openai/codex) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 <p align="center">
   <img src="assets/img/logo-wordmark.png" alt="Revela" width="320" />
@@ -10,7 +10,7 @@
 Revela 是 Codex plugin，用来把来源材料、调研、数据和用户意图转成可信、可追踪、可直接用于决策沟通的 deck artifact。
-在你的本地 workspace 中，Revela 会审阅本地资料、保存 source-linked research、生成明确的 `deck-plan.md`、产出 HTML deck，并支持 Review 与 PDF/PPTX/PNG 导出。
+在你的本地 workspace 中，Revela 会审阅本地资料、保存 source-linked research、生成明确的 `deck-plan.md`、产出 HTML deck，并以可在 Codex Browser 打开的 website card 交付以便 annotation，并支持 PDF/PPTX/PNG 导出。
 ## 安装
@@ -19,18 +19,17 @@ Revela 是 Codex plugin，用来把来源材料、调研、数据和用户意图
 环境要求：
 - 需要已安装 Codex CLI，并且 shell 中可以执行 `codex`。
-- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.14 mcp` 启动 MCP server。
-- 如果使用 Review UI 的 Apply，需要 `codex exec` 可用；评论会先保存，点击 Apply 后才执行修复。
+- 环境中需要可以执行 `bun`；Revela 会从已安装的 Codex plugin cache 中运行 `bun ./mcp/revela-server.ts` 来启动 MCP server。
 可选的安装前检查：
 ```bash
 codex --version
 codex exec --help
-npx --version
+bun --version
 ```
-如果 `npx` 报 npm cache 权限错误，可以修复 cache owner，或在本地检查时使用可写 cache：
+如果 npm package 检查时报 npm cache 权限错误，可以修复 cache owner，或在本地检查时使用可写 cache：
 ```bash
 sudo chown -R "$(id -u):$(id -g)" ~/.npm
@@ -40,19 +39,19 @@ 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.14
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.16
 codex plugin add revela@revela
 ```
-Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.14 mcp`，由 npm 获取已发布 package 及其 dependencies。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 启动 Revela MCP server 时，会从已安装的 plugin cache 中运行 `bun ./mcp/revela-server.ts`，并解析该 marketplace checkout 中的 runtime。
 不需要在 Codex marketplace clone 里运行 `bun install`。
 安装后开启一个新的 Codex thread，让 Codex 加载 Revela 的 skills、MCP tools 和 hooks。
-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。
+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 生成 HTML deck artifact，并在 QA 通过后以 Codex Browser website card 形式交付，`revela-export` 导出 PDF/PPTX/PNG。
-如果要按发布路径做本地验证，运行 `bun run smoke:mcp-pack`。它会把当前 checkout 打成临时 npm tarball，再通过 `npx` 启动 MCP server，不需要先发布到 registry。
+如果要按发布路径做本地验证，运行 `bun run smoke:mcp-pack`。它会把当前 checkout 打成临时 npm tarball，解包后通过打包出的 Codex plugin launcher 路径启动 MCP server，不需要先发布到 registry。
 #### Codex 升级
@@ -74,7 +73,7 @@ codex plugin marketplace upgrade revela
 codex plugin add revela@revela
 ```
-Git marketplace ref 和 `.mcp.json` npm pin 属于同一个 release artifact。升级后开启一个新的 Codex thread，让 Codex 重新加载 Revela skills、MCP tools、hooks 和 runtime pin。
+Git marketplace ref 和 `.mcp.json` plugin launcher 属于同一个 release artifact。升级后开启一个新的 Codex thread，让 Codex 重新加载 Revela skills、MCP tools、hooks 和 runtime launcher。
 ## 内置设计
@@ -83,32 +82,32 @@ Revela 内置多个 deck design：
 ### [summit](designs/summit/preview.html)
 <p align="center">
-  <img src="assets/img/summit-01.jpg" alt="Summit design preview 1" width="32%" />
-  <img src="assets/img/summit-02.jpg" alt="Summit design preview 2" width="32%" />
-  <img src="assets/img/summit-03.jpg" alt="Summit design preview 3" width="32%" />
+  <img src="assets/img/summit-01.jpg" alt="Summit design cover preview" width="32%" />
+  <img src="assets/img/summit-02.jpg" alt="Summit design narrative layout preview" width="32%" />
+  <img src="assets/img/summit-03.jpg" alt="Summit design timeline preview" width="32%" />
 </p>
 ### [monet](designs/monet/preview.html)
 <p align="center">
-  <img src="assets/img/monet-01.jpg" alt="Monet design preview 1" width="32%" />
-  <img src="assets/img/monet-02.jpg" alt="Monet design preview 2" width="32%" />
-  <img src="assets/img/monet-03.jpg" alt="Monet design preview 3" width="32%" />
+  <img src="assets/img/monet-01.jpg" alt="Monet design cover preview" width="32%" />
+  <img src="assets/img/monet-02.jpg" alt="Monet design narrative layout preview" width="32%" />
+  <img src="assets/img/monet-03.jpg" alt="Monet design timeline preview" width="32%" />
 </p>
 ### [lucent](designs/lucent/preview.html)
 <p align="center">
   <img src="assets/img/lucent-01.jpg" alt="Lucent design cover preview" width="32%" />
-  <img src="assets/img/lucent-02.jpg" alt="Lucent design table of contents preview" width="32%" />
-  <img src="assets/img/lucent-03.jpg" alt="Lucent design Sankey preview" width="32%" />
+  <img src="assets/img/lucent-02.jpg" alt="Lucent design narrative layout preview" width="32%" />
+  <img src="assets/img/lucent-03.jpg" alt="Lucent design roadmap preview" width="32%" />
 </p>
 `starter` 是简洁默认演示风格。
 在 Codex 中切换 design，可以这样问：
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，use summit as design.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，use summit as design.
 在 Codex 中，可以直接让 Revela 列出或切换 design；生成 deck 时会使用 active design。
@@ -116,7 +115,7 @@ Revela 内置多个 deck design：
 Domain 提供特定场景的沟通 guidance，例如 consulting、product 或 investor communication。需要让 Revela 按具体沟通场景调整 deck framing 时使用。
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，列出 available domains。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，列出 available domains。
 在 Codex 中，可以直接让 Revela 列出或切换 domain；active domain 会用于 init、research 和 deck planning 阶段的 framing。
@@ -126,62 +125,52 @@ Domain 提供特定场景的沟通 guidance，例如 consulting、product 或 in
 1. 先选择 domain，让 Revela 按你的沟通场景 framing 受众、决策、风险和潜在质疑。
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，use consulting as domain.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，use consulting as domain.
 2. 再选择 design，让后续生成的 deck 使用指定视觉风格。
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，use summit as design.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，use summit as design.
 3. 如果需要不同的视觉方向，可以创建一个自定义 design。
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，创建一个名为 neon-finance 的新 design：金融仪表盘风格，深色界面、精密网格、亮绿色重点色。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，创建一个名为 neon-finance 的新 design：金融仪表盘风格，深色界面、精密网格、亮绿色重点色。
 Revela 可能会继续询问参考图、风格约束或禁忌项，然后创建并校验 design。创建完成后再切换使用：
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，使用 neon-finance 作为 design。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，使用 neon-finance 作为 design。
 4. 初始化本地 material intake。Init 会扫描、抽取并审阅 workspace source；它不会创建 Narrative Vault。
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，帮我 init 这个 workspace，先读本地材料。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，帮我 init 这个 workspace，先读本地材料。
 5. 针对 deck 所需输入做 research，并保存带来源的 findings。
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，research 这个 deck 需要的公开证据、案例和 source。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，research 这个 deck 需要的公开证据、案例和 source。
 6. 先创建或更新 deck plan，明确 slide 顺序、章节结构、source links、unresolved inputs、source limitations 和 visual intent，再生成 HTML。
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，生成 HTML 前先 create or update deck plan。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，生成 HTML 前先 create or update deck plan。
 7. 基于当前 deck plan 生成 HTML deck。
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，基于当前 deck plan make deck。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，基于当前 deck plan make deck。
-8. Review 生成后的 deck，检查 Artifact QA，并做定向修改。
+8. make-deck 完成后，从 website card 打开生成的 deck，并在 Codex Browser 中做 annotation 和定向修改。
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，review 生成好的 deck。
+使用 Codex Browser 原生 annotation 工具标注打开的 HTML deck。
 9. QA 通过后导出 PDF。
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，把 deck export 成 PDF。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，把 deck export 成 PDF。
 10. QA 通过后导出可编辑 PPTX。
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，把 deck export 成 PPTX。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，把 deck export 成 PPTX。
 11. QA 通过后导出每页 PNG。
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，把 deck export 成 PNG。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，把 deck export 成 PNG。
-## Review Deck
+## Annotate Deck
-生成 HTML deck 后可以进入 Review：
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，review 生成好的 deck。
-<p align="center">
-  <img src="assets/img/review-ui.png" alt="Revela Review UI showing @ref comments and deck QA" width="900" />
-</p>
-Review 会打开本地 deck 工作台，用于 QA 和定向修改：
-- Comment：对 deck 发起定向修改，例如 layout、文案、层级、间距或视觉调整。
+`revela-make-deck` 生成 HTML deck 且 Artifact QA 通过后，会在对话中回复可用 Codex Browser 打开的 website card。使用 Codex Browser 原生 annotation 工具标注 layout、文案、层级、间距或视觉修改。

package/bin/revela.ts CHANGED Viewed

File without changes

package/designs/lucent/DESIGN.md CHANGED Viewed

@@ -37,9 +37,37 @@ Use a fixed `1920px` x `1080px` `.slide-canvas` inside a dark navy browser frame
   --shadow-soft: rgba(30, 65, 130, 0.13);
   --font-display: DengXian, "Microsoft YaHei", "PingFang SC", Arial, ui-sans-serif, sans-serif;
   --font-body: DengXian, "Microsoft YaHei", "PingFang SC", Arial, ui-sans-serif, sans-serif;
+  --grid-margin-x: 72px;
+  --grid-margin-y: 56px;
+  --grid-columns: 12;
+  --grid-gutter: 24px;
+  --grid-safe-top: 56px;
+  --grid-safe-bottom: 64px;
+  --space-1: 8px;
+  --space-2: 16px;
+  --space-3: 24px;
+  --space-4: 32px;
+  --space-5: 48px;
+  --space-6: 72px;
+  --font-size-caption: 16px;
+  --font-size-body: 22px;
+  --font-size-body-small: 18px;
+  --font-size-h3: 31px;
+  --font-size-h2: 52px;
+  --font-size-hero: 104px;
+  --surface-radius: 8px;
+  --surface-radius-large: 12px;
 }
 ```
+Design contract:
+- Grid: content slides use a 12-column mental grid inside `--grid-margin-x` / `--grid-margin-y`; layout slots should align to declared grid rails or documented column ratios.
+- Safe area: titles, body slots, source notes, page numbers, and logos stay inside the safe area unless a `hero` layout owns a full-bleed image.
+- Spacing: use the `--space-*` scale and keep dense report pages on an 8px rhythm; do not hand-tune every card with unrelated gaps.
+- Type scale: use the declared fixed-pixel type tokens for the 1920x1080 canvas; do not use `clamp()`, viewport units, or negative tracking.
+- Surfaces: cards and panels use `--surface`, `--line`, `--shadow-soft`, and radius tokens; avoid new one-off glass/orb treatments outside Lucent's supplied assets.
+- Chart tokens: ECharts use `--accent-primary`, `--accent-secondary`, `--accent-cyan`, `--accent-coral`, transparent backgrounds, muted axes, and explicit container heights.
 Asset policy:
 - Use `assets/cover-background.jpg` and `assets/closing-background.jpg` for full-bleed hero backgrounds.
 - Use `assets/toc-orb.png` only when transparency is needed for the Lucent glass orb.
@@ -54,6 +82,9 @@ Asset policy:
 - Use Lucent for strategy, operating review, research synthesis, market diagnosis, and data-backed decision decks.
 - Prefer bright report pages with subtle radial accents. Reserve dark full-bleed imagery for cover, section divider, and closing slides.
 - Put the slide-level title in each layout's title slot or hero text area. Do not hide the main claim inside a card.
+- Treat the design as a measurable report system: every content layout should expose clear grid rails, stable slot dimensions, and a visible reading order.
+- Use declared spacing/type/surface tokens before adding local CSS. Local overrides should serve a documented state such as dense table, long title, or mixed-language body copy.
+- Preview examples should mark every layout with `data-preview-layout="<layout-name>"` and every component with `data-preview-component="<component-name>"`.
 - Use `box` for one idea, evidence item, operating gap, risk, or action. Use 2-4 boxes on dense synthesis slides.
 - Use ECharts for all data charts, including Sankey. Do not fake charts with CSS shapes.
 - Keep typography quiet and legible: large claim headings, compact metadata, and source notes in muted color.
@@ -141,7 +172,7 @@ Structured table component with `.table-panel`, tabular numbers, muted headers,
 <!-- @component:data-table:end -->
 <!-- @component:roadmap-horizontal:start -->
-Four-phase horizontal roadmap with alternating cards around a gradient axis. Use for staged plans, milestones, or migration paths.
+Four-phase horizontal roadmap with alternating cards around a gradient axis. Use for staged plans, milestones, or migration paths. The dot is the milestone marker, not card decoration: place each marker on the shared axis and connect the card back to that marker so the phase label, card, and axis read as one anchored event.
 <!-- @component:roadmap-horizontal:end -->
 <!-- @component:steps:start -->