@cyber-dash-tech/revela 0.19.0 → 0.19.2

package/README.md

@@ -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, surfaces them as Codex Browser website cards for annotation, 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 localhost Codex Browser website cards for annotation, and exports PDF/PPTX/PNG artifacts.
 
 ## Install
 
@@ -39,7 +39,7 @@ 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.19.0
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.19.2
 codex plugin add revela@revela
 ```
 
@@ -49,7 +49,7 @@ 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 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.
+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 localhost 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, extracts it, and starts the MCP server through the packaged Codex plugin launcher path without requiring a registry publish.
 
@@ -92,7 +92,7 @@ Revela includes built-in deck designs. Design previews are generated from the bu
 <p align="center">
   <img src="assets/img/summit-01.jpg" alt="Summit design cover preview" width="32%" />
   <img src="assets/img/summit-02.jpg" alt="Summit design agenda preview" width="32%" />
-  <img src="assets/img/summit-03.jpg" alt="Summit design vertical timeline-roadmap preview" width="32%" />
+  <img src="assets/img/summit-03.jpg" alt="Summit design vertical timeline preview" width="32%" />
 </p>
 
 ### monet
@@ -116,12 +116,12 @@ Revela includes built-in deck designs. Design previews are generated from the bu
 <p align="center">
   <img src="assets/img/lucent-dark-01.jpg" alt="Lucent Dark design cover preview" width="32%" />
   <img src="assets/img/lucent-dark-02.jpg" alt="Lucent Dark design agenda preview" width="32%" />
-  <img src="assets/img/lucent-dark-03.jpg" alt="Lucent Dark design horizontal timeline-roadmap preview" width="32%" />
+  <img src="assets/img/lucent-dark-03.jpg" alt="Lucent Dark design horizontal milestone preview" width="32%" />
 </p>
 
 To switch designs in Codex, ask:
 
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), use summit as the design.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.
 
@@ -129,7 +129,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.18.16/skills/revela/SKILL.md), list available domains.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.
 
@@ -139,52 +139,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.18.16/skills/revela/SKILL.md), use consulting as the domain.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.18.16/skills/revela/SKILL.md), use summit as the design.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.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:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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 a workspace draft with `DESIGN.md`, `design.css`, and any local `assets/**`. It generates a preview from the built-in page-template fixture plus that CSS so you can review cover, agenda, timelines, charts, tables, cards, and visual slots before installing. When it is ready, switch to it:
 
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md), use neon-finance as the design.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.18.16/skills/revela/SKILL.md), help me init this workspace from the local materials.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.18.16/skills/revela/SKILL.md), research the public evidence and examples needed for this deck.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.18.16/skills/revela/SKILL.md), create or update the deck plan before generating HTML.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.18.16/skills/revela/SKILL.md), make the deck from the current deck plan.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/skills/revela/SKILL.md), make the deck from the current deck plan.
 
-8. Review and annotate the generated deck from the website card after make-deck completes.
+8. Review and annotate the generated deck from the localhost website card after make-deck completes.
 
-Use Codex Browser's native annotation tools on the opened HTML deck.
+Revela serves the deck from `http://127.0.0.1:<port>/decks/<file>.html` so you can click the card and open it in Codex Browser. 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.18.16/skills/revela/SKILL.md), export the deck to PDF.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.18.16/skills/revela/SKILL.md), export the deck to PPTX.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.18.16/skills/revela/SKILL.md), export the deck to PNG.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/skills/revela/SKILL.md), export the deck to PNG.
 
 ## Annotate A Deck
 
-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.
+After `revela-make-deck` generates an HTML deck and Artifact QA passes, Codex replies with a localhost website card that you can click to open 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

@@ -10,7 +10,7 @@
 
 Revela 是 Codex plugin，用来把来源材料、调研、数据和用户意图转成可信、可追踪、可直接用于决策沟通的 deck artifact。
 
-在你的本地 workspace 中，Revela 会审阅本地资料、保存 source-linked research、生成明确的 `deck-plan.md`、产出 HTML deck，并以可在 Codex Browser 打开的 website card 交付以便 annotation，并支持 PDF/PPTX/PNG 导出。
+在你的本地 workspace 中，Revela 会审阅本地资料、保存 source-linked research、生成明确的 `deck-plan.md`、产出 HTML deck，并以 localhost Codex Browser website card 交付以便 annotation，并支持 PDF/PPTX/PNG 导出。
 
 ## 安装
 
@@ -39,7 +39,7 @@ 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.19.0
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.19.2
 codex plugin add revela@revela
 ```
 
@@ -49,7 +49,7 @@ Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。
 
 安装后开启一个新的 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 生成 HTML deck artifact，并在 QA 通过后以 Codex Browser website card 形式交付，`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 通过后以 localhost Codex Browser website card 形式交付，`revela-export` 导出 PDF/PPTX/PNG。
 
 如果要按发布路径做本地验证，运行 `bun run smoke:mcp-pack`。它会把当前 checkout 打成临时 npm tarball，解包后通过打包出的 Codex plugin launcher 路径启动 MCP server，不需要先发布到 registry。
 
@@ -92,7 +92,7 @@ Revela 内置多个 deck design。Design preview 由内置 page-template preview
 <p align="center">
   <img src="assets/img/summit-01.jpg" alt="Summit design cover preview" width="32%" />
   <img src="assets/img/summit-02.jpg" alt="Summit design agenda preview" width="32%" />
-  <img src="assets/img/summit-03.jpg" alt="Summit design vertical timeline-roadmap preview" width="32%" />
+  <img src="assets/img/summit-03.jpg" alt="Summit design vertical timeline preview" width="32%" />
 </p>
 
 ### monet
@@ -116,12 +116,12 @@ Revela 内置多个 deck design。Design preview 由内置 page-template preview
 <p align="center">
   <img src="assets/img/lucent-dark-01.jpg" alt="Lucent Dark design cover preview" width="32%" />
   <img src="assets/img/lucent-dark-02.jpg" alt="Lucent Dark design agenda preview" width="32%" />
-  <img src="assets/img/lucent-dark-03.jpg" alt="Lucent Dark design horizontal timeline-roadmap preview" width="32%" />
+  <img src="assets/img/lucent-dark-03.jpg" alt="Lucent Dark design horizontal milestone preview" width="32%" />
 </p>
 
 在 Codex 中切换 design，可以这样问：
 
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，use summit as design.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/skills/revela/SKILL.md)，use summit as design.
 
 在 Codex 中，可以直接让 Revela 列出或切换 design；生成 deck 时会使用 active design。
 
@@ -129,7 +129,7 @@ Revela 内置多个 deck design。Design preview 由内置 page-template preview
 
 Domain 提供特定场景的沟通 guidance，例如 consulting、product 或 investor communication。需要让 Revela 按具体沟通场景调整 deck framing 时使用。
 
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，列出 available domains。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/skills/revela/SKILL.md)，列出 available domains。
 
 在 Codex 中，可以直接让 Revela 列出或切换 domain；active domain 会用于 init、research 和 deck planning 阶段的 framing。
 
@@ -139,52 +139,52 @@ Domain 提供特定场景的沟通 guidance，例如 consulting、product 或 in
 
 1. 先选择 domain，让 Revela 按你的沟通场景 framing 受众、决策、风险和潜在质疑。
 
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，use consulting as domain.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/skills/revela/SKILL.md)，use consulting as domain.
 
 2. 再选择 design，让后续生成的 deck 使用指定视觉风格。
 
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，use summit as design.
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/skills/revela/SKILL.md)，use summit as design.
 
 3. 如果需要不同的视觉方向，可以创建一个自定义 design。
 
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，创建一个名为 neon-finance 的新 design：金融仪表盘风格，深色界面、精密网格、亮绿色重点色。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/skills/revela/SKILL.md)，创建一个名为 neon-finance 的新 design：金融仪表盘风格，深色界面、精密网格、亮绿色重点色。
 
 Revela 可能会继续询问参考图、风格约束或禁忌项，然后在 workspace draft 中创建 `DESIGN.md`、`design.css` 和需要的本地 `assets/**`。它会用内置 page-template fixture 加上这份 CSS 生成 preview，让你在 install 前先检查 cover、agenda、timeline、chart、table、card 和 visual slot。创建完成后再切换使用：
 
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，使用 neon-finance 作为 design。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.18.16/skills/revela/SKILL.md)，帮我 init 这个 workspace，先读本地材料。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/skills/revela/SKILL.md)，帮我 init 这个 workspace，先读本地材料。
 
 5. 针对 deck 所需输入做 research，并保存带来源的 findings。
 
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，research 这个 deck 需要的公开证据、案例和 source。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.18.16/skills/revela/SKILL.md)，生成 HTML 前先 create or update deck plan。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/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.18.16/skills/revela/SKILL.md)，基于当前 deck plan make deck。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/skills/revela/SKILL.md)，基于当前 deck plan make deck。
 
-8. make-deck 完成后，从 website card 打开生成的 deck，并在 Codex Browser 中做 annotation 和定向修改。
+8. make-deck 完成后，从 localhost website card 打开生成的 deck，并在 Codex Browser 中做 annotation 和定向修改。
 
-使用 Codex Browser 原生 annotation 工具标注打开的 HTML deck。
+Revela 会通过 `http://127.0.0.1:<port>/decks/<file>.html` 服务 deck，你点击 card 后在 Codex Browser 中打开。使用 Codex Browser 原生 annotation 工具标注打开的 HTML deck。
 
 9. QA 通过后导出 PDF。
 
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，把 deck export 成 PDF。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/skills/revela/SKILL.md)，把 deck export 成 PDF。
 
 10. QA 通过后导出可编辑 PPTX。
 
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，把 deck export 成 PPTX。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/skills/revela/SKILL.md)，把 deck export 成 PPTX。
 
 11. QA 通过后导出每页 PNG。
 
-> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.18.16/skills/revela/SKILL.md)，把 deck export 成 PNG。
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.19.2/skills/revela/SKILL.md)，把 deck export 成 PNG。
 
 ## Annotate Deck
 
-`revela-make-deck` 生成 HTML deck 且 Artifact QA 通过后，会在对话中回复可用 Codex Browser 打开的 website card。使用 Codex Browser 原生 annotation 工具标注 layout、文案、层级、间距或视觉修改。
+`revela-make-deck` 生成 HTML deck 且 Artifact QA 通过后，会在对话中回复可点击打开的 localhost website card。使用 Codex Browser 原生 annotation 工具标注 layout、文案、层级、间距或视觉修改。

package/designs/lucent/DESIGN.md

@@ -260,7 +260,8 @@ Lucent skins Revela built-in page templates without owning their semantic struct
 - `cover`, `section-divider`, `closing`: use full-bleed hero treatment with Lucent package assets.
 - `agenda`, `executive-summary`, `problem-context`, `key-message-evidence`, `claim-supporting-visual`: use report-story/card-grid language with quiet surfaces.
 - `metric-highlight`, `chart-takeaways`, `table-comparison`: use data-forward Lucent panels with explicit interpretation regions.
-- `timeline-roadmap`: map to the roadmap visual system. Dots remain milestone anchors inside each timeline item; do not absolutely position detached decorative dots.
+- `milestone`: map to the horizontal roadmap visual system. Dots remain milestone anchors inside each milestone item; do not absolutely position detached decorative dots.
+- `timeline`: map to the vertical timeline visual system. Dots remain event anchors inside each timeline item; do not absolutely position detached decorative dots.
 - `process-steps`, `recommendation-decision`, `risks-tradeoffs`: use recommendation and steps surfaces with no nested card-in-card framing.
 
 <!-- @design:page-templates:end -->

package/designs/lucent-dark/DESIGN.md

@@ -260,7 +260,8 @@ Lucent skins Revela built-in page templates without owning their semantic struct
 - `cover`, `section-divider`, `closing`: use full-bleed hero treatment with Lucent package assets.
 - `agenda`, `executive-summary`, `problem-context`, `key-message-evidence`, `claim-supporting-visual`: use report-story/card-grid language with quiet surfaces.
 - `metric-highlight`, `chart-takeaways`, `table-comparison`: use data-forward Lucent panels with explicit interpretation regions.
-- `timeline-roadmap`: map to the roadmap visual system. Dots remain milestone anchors inside each timeline item; do not absolutely position detached decorative dots.
+- `milestone`: map to the horizontal roadmap visual system. Dots remain milestone anchors inside each milestone item; do not absolutely position detached decorative dots.
+- `timeline`: map to the vertical timeline visual system. Dots remain event anchors inside each timeline item; do not absolutely position detached decorative dots.
 - `process-steps`, `recommendation-decision`, `risks-tradeoffs`: use recommendation and steps surfaces with no nested card-in-card framing.
 
 <!-- @design:page-templates:end -->

package/designs/monet/DESIGN.md

@@ -2887,7 +2887,8 @@ Monet skins Revela built-in page templates with soft editorial rhythm, painterly
 - `cover`, `section-divider`, `closing`: use expressive title-led structural pages.
 - `agenda`, `executive-summary`, `problem-context`, `key-message-evidence`, `claim-supporting-visual`: use soft narrative regions with no heavy outer box.
 - `metric-highlight`, `chart-takeaways`, `table-comparison`: use calm data surfaces and readable interpretation zones.
-- `timeline-roadmap`: dots remain milestone anchors inside each timeline item; do not position detached decorative markers.
+- `milestone`: dots remain milestone anchors inside each horizontal milestone item; do not position detached decorative markers.
+- `timeline`: dots remain event anchors inside each vertical timeline item; do not position detached decorative markers.
 - `process-steps`, `recommendation-decision`, `risks-tradeoffs`: use quiet action and tradeoff panels.
 
 <!-- @design:page-templates:end -->

package/designs/starter/DESIGN.md

@@ -911,7 +911,8 @@ Starter skins Revela built-in page templates as a neutral authoring system. The
 - `cover`, `section-divider`, `closing`: use clear title-first structural pages.
 - `agenda`, `executive-summary`, `problem-context`, `key-message-evidence`, `claim-supporting-visual`: use plain narrative and card-grid surfaces.
 - `metric-highlight`, `chart-takeaways`, `table-comparison`: use direct data panels with minimal decoration.
-- `timeline-roadmap`: dots remain milestone anchors inside each timeline item; do not position detached decorative markers.
+- `milestone`: dots remain milestone anchors inside each horizontal milestone item; do not position detached decorative markers.
+- `timeline`: dots remain event anchors inside each vertical timeline item; do not position detached decorative markers.
 - `process-steps`, `recommendation-decision`, `risks-tradeoffs`: use simple step and decision panels.
 
 <!-- @design:page-templates:end -->

package/designs/summit/DESIGN.md

@@ -2671,7 +2671,8 @@ Summit skins Revela built-in page templates with editorial hierarchy, broad whit
 - `cover`, `section-divider`, `closing`: use strong editorial title pages.
 - `agenda`, `executive-summary`, `problem-context`, `key-message-evidence`, `claim-supporting-visual`: use borderless narrative groupings with clear hierarchy.
 - `metric-highlight`, `chart-takeaways`, `table-comparison`: use evidence-first data regions without outer container borders.
-- `timeline-roadmap`: dots remain milestone anchors inside each timeline item; do not position detached decorative markers.
+- `milestone`: dots remain milestone anchors inside each horizontal milestone item; do not position detached decorative markers.
+- `timeline`: dots remain event anchors inside each vertical timeline item; do not position detached decorative markers.
 - `process-steps`, `recommendation-decision`, `risks-tradeoffs`: use decisive action panels with minimal framing.
 
 <!-- @design:page-templates:end -->

package/lib/design/designs.ts

@@ -166,6 +166,12 @@ export interface MaterializeDesignPreviewResult {
   previewDir: string
   previewPath: string
   previewUrl: string
+  browserHandoff: {
+    serveRoot: string
+    path: string
+    urlTemplate: string
+    instructions: string
+  }
   designCssPath: string
   files: string[]
   warnings: string[]
@@ -374,6 +380,12 @@ export function materializeDesignPreview(args: MaterializeDesignPreviewArgs): Ma
     previewDir,
     previewPath,
     previewUrl: pathToFileURL(previewPath).href,
+    browserHandoff: {
+      serveRoot: previewDir,
+      path: "preview.html",
+      urlTemplate: "http://127.0.0.1:<port>/preview.html",
+      instructions: "Start a read-only local static server from serveRoot, then reply with the localhost URL so the user can click it open in Codex Browser. Do not open the file:// preview directly.",
+    },
     designCssPath,
     files: listDesignPackageFiles(previewDir),
     warnings,

package/lib/page-templates/built-in-preview.html

@@ -162,12 +162,12 @@
             <div class="template-page-number">11</div>
         </div>
     </section>
-    <section class="slide template-slide" slide-qa="true" data-slide-index="12" data-design="built-in-preview" data-template="timeline-roadmap">
+    <section class="slide template-slide" slide-qa="true" data-slide-index="12" data-design="built-in-preview" data-template="milestone">
         <div class="slide-canvas">
             <div class="template-frame">
                 <header>
                     <p class="template-eyebrow">Template 12 / 16</p>
-                    <h1 class="template-title">timeline-roadmap</h1>
+                    <h1 class="template-title">milestone</h1>
                 </header><div class="template-body"><div class="template-timeline template-timeline--horizontal" data-template-slot="timeline" style="--timeline-count:5"><article class="template-timeline-item">
                         <div class="template-timeline-copy template-card">
                             <i class="template-insight-icon" data-lucide="scan-search" aria-hidden="true"></i>
@@ -214,12 +214,12 @@
             <div class="template-page-number">12</div>
         </div>
     </section>
-    <section class="slide template-slide" slide-qa="true" data-slide-index="13" data-design="built-in-preview" data-template="timeline-roadmap">
+    <section class="slide template-slide" slide-qa="true" data-slide-index="13" data-design="built-in-preview" data-template="timeline">
         <div class="slide-canvas">
             <div class="template-frame">
                 <header>
                     <p class="template-eyebrow">Template 13 / 16</p>
-                    <h1 class="template-title">timeline-roadmap-vertical</h1>
+                    <h1 class="template-title">timeline</h1>
                 </header><div class="template-body"><div class="template-timeline-layout template-timeline-layout--left"><div class="template-side-panel template-text-panel" data-template-slot="insight"><h2 class="template-side-panel-title template-text-panel-title">Reading the journey</h2><p class="template-side-panel-body template-text-panel-body">The timeline should show sequence and decision rhythm, while the side panel explains why the milestones matter.</p></div><div class="template-timeline template-timeline--vertical" data-template-slot="timeline" style="--timeline-count:4"><article class="template-timeline-item">
                         <span class="template-timeline-dot" aria-hidden="true"></span>
                         <div class="template-timeline-copy">

package/lib/page-templates/render.ts

@@ -150,10 +150,13 @@ const templates: PageTemplateDefinition[] = [
     field("insightBody", "string", "Interpretation, reading note, or caveat below the table."),
     field("insightIcon", "string", "Lucide icon name for the insight title."),
   ], ["Keep rows scannable.", "Do not use a table for pure prose."], ["Table has headers and body rows."]),
-  define("timeline-roadmap", "Timeline / Roadmap", "Show dated phases, milestones, or journey steps.", [
+  define("milestone", "Milestone", "Show dated phases or milestones on a horizontal roadmap axis.", [
     field("title", "string", "Slide title.", true),
-    field("orientation", "string", "horizontal or vertical."),
-    field("milestones", "milestones[]", "Timeline milestones.", true),
+    field("milestones", "milestones[]", "Horizontal milestones.", true),
+  ], ["Use 3-6 milestones.", "Milestone cards sit above the axis and date labels sit below it.", "Each dot belongs to the same DOM item as its copy."], ["Timeline root exists.", "Every milestone has dot and copy.", "Dot and copy are sibling anchors inside one timeline item."]),
+  define("timeline", "Timeline", "Show dated events, journey steps, or sequence as a vertical timeline.", [
+    field("title", "string", "Slide title.", true),
+    field("milestones", "milestones[]", "Timeline events.", true),
     field("insightTitle", "string", "Side panel title."),
     field("insightBody", "string", "Timeline interpretation, so-what, or caveat."),
     field("insightSide", "string", "left or right side panel placement."),
@@ -188,19 +191,21 @@ export function listPageTemplates(): { ok: true; templates: PageTemplateDefiniti
 }
 
 export function renderTemplateSlide(input: RenderTemplateSlideInput): RenderTemplateSlideResult {
-  const template = getPageTemplate(input.templateId)
+  const requestedTemplateId = normalizeTemplateId(input.templateId)
+  const template = getPageTemplate(requestedTemplateId)
   const slideIndex = positiveIndex(input.slideIndex)
   const content = input.content ?? {}
   const designName = input.designName || "lucent"
   const warnings = validateRequiredFields(template, content)
+  const outputTemplate = requestedTemplateId === "timeline-roadmap" ? { ...template, id: "timeline-roadmap", title: "Timeline / Roadmap" } : template
   const html = renderSlideShell({
-    template,
+    template: outputTemplate,
     slideIndex,
     designName,
     title: stringValue(content.title) || template.title,
-    body: renderBody(template.id, content),
+    body: renderBody(requestedTemplateId, content),
   })
-  return { ok: true, templateId: template.id, slideIndex, designName, html, warnings }
+  return { ok: true, templateId: outputTemplate.id, slideIndex, designName, html, warnings }
 }
 
 export function builtInPreviewFixtures(): BuiltInPreviewFixture[] {
@@ -284,9 +289,8 @@ export function builtInPreviewFixtures(): BuiltInPreviewFixture[] {
       insightIcon: "lightbulb",
       insightBody: "The template layer owns structure, while the design layer owns visual treatment. This keeps agent edits bounded without freezing the final look.",
     }),
-    fixture("timeline-roadmap", {
-      title: "timeline-roadmap",
-      orientation: "horizontal",
+    fixture("milestone", {
+      title: "milestone",
       milestones: [
         { date: "2022", label: "Signal", description: "Map the baseline." },
         { date: "2023", label: "Proof", description: "Validate the evidence threshold." },
@@ -295,9 +299,8 @@ export function builtInPreviewFixtures(): BuiltInPreviewFixture[] {
         { date: "2026", label: "Decision", description: "Commit to the next path." },
       ],
     }),
-    fixture("timeline-roadmap", {
-      title: "timeline-roadmap-vertical",
-      orientation: "vertical",
+    fixture("timeline", {
+      title: "timeline",
       insightTitle: "Reading the journey",
       insightBody: "The timeline should show sequence and decision rhythm, while the side panel explains why the milestones matter.",
       milestones: [
@@ -785,7 +788,7 @@ export function validatePageTemplateContracts(filePath: string): PageTemplateCon
     const body = section[2]
     const slideIndex = Number(/data-slide-index=["'](\d+)["']/i.exec(section[0])?.[1])
     issues.push(...validateVocabularyContract(templateId, body, Number.isInteger(slideIndex) ? slideIndex : undefined))
-    if (templateId === "timeline-roadmap") issues.push(...validateTimelineContract(body, Number.isInteger(slideIndex) ? slideIndex : undefined))
+    if (isTimelineTemplateId(templateId)) issues.push(...validateTimelineContract(templateId, body, Number.isInteger(slideIndex) ? slideIndex : undefined))
   }
   return { ok: !issues.some((issue) => issue.severity === "error"), issues }
 }
@@ -815,7 +818,7 @@ export function validateBoundedTemplateEdit(input: BoundedTemplateEditInput): Pa
   } else {
     const templateId = /data-template=["']([^"']+)["']/i.exec(target)?.[1] || "unknown"
     issues.push(...validateVocabularyContract(templateId, target, slideIndex))
-    if (templateId === "timeline-roadmap") issues.push(...validateTimelineContract(target, slideIndex))
+    if (isTimelineTemplateId(templateId)) issues.push(...validateTimelineContract(templateId, target, slideIndex))
   }
   return { ok: !issues.some((issue) => issue.severity === "error"), issues }
 }
@@ -824,23 +827,23 @@ function define(id: string, title: string, purpose: string, fields: PageTemplate
   return { id, title, purpose, status: "renderable", fields, contentRules, qaRules }
 }
 
-function validateTimelineContract(html: string, slideIndex?: number): PageTemplateContractIssue[] {
+function validateTimelineContract(templateId: string, html: string, slideIndex?: number): PageTemplateContractIssue[] {
   const issues: PageTemplateContractIssue[] = []
   const root = /class=["'][^"']*\btemplate-timeline\b[^"']*["']/i.test(html)
   if (!root) {
-    issues.push({ severity: "error", templateId: "timeline-roadmap", slideIndex, message: "Missing .template-timeline root." })
+    issues.push({ severity: "error", templateId, slideIndex, message: "Missing .template-timeline root." })
     return issues
   }
   const itemMatches = [...html.matchAll(/<article\b[^>]*class=["'][^"']*\btemplate-timeline-item\b[^"']*["'][^>]*>([\s\S]*?)<\/article>/gi)]
-  if (itemMatches.length < 3) issues.push({ severity: "warning", templateId: "timeline-roadmap", slideIndex, message: "Timeline should usually contain at least three milestones." })
+  if (itemMatches.length < 3) issues.push({ severity: "warning", templateId, slideIndex, message: "Timeline should usually contain at least three milestones." })
   for (let index = 0; index < itemMatches.length; index++) {
     const item = itemMatches[index][1]
-    if (!/class=["'][^"']*\btemplate-timeline-dot\b[^"']*["']/i.test(item)) issues.push({ severity: "error", templateId: "timeline-roadmap", slideIndex, message: `Milestone ${index + 1} is missing .template-timeline-dot inside its item.` })
-    if (!/class=["'][^"']*\btemplate-timeline-copy\b[^"']*["']/i.test(item)) issues.push({ severity: "error", templateId: "timeline-roadmap", slideIndex, message: `Milestone ${index + 1} is missing .template-timeline-copy inside its item.` })
+    if (!/class=["'][^"']*\btemplate-timeline-dot\b[^"']*["']/i.test(item)) issues.push({ severity: "error", templateId, slideIndex, message: `Milestone ${index + 1} is missing .template-timeline-dot inside its item.` })
+    if (!/class=["'][^"']*\btemplate-timeline-copy\b[^"']*["']/i.test(item)) issues.push({ severity: "error", templateId, slideIndex, message: `Milestone ${index + 1} is missing .template-timeline-copy inside its item.` })
   }
   const dotCount = (html.match(/\btemplate-timeline-dot\b/g) ?? []).length
   const copyCount = (html.match(/\btemplate-timeline-copy\b/g) ?? []).length
-  if (dotCount !== copyCount) issues.push({ severity: "error", templateId: "timeline-roadmap", slideIndex, message: `Timeline dot count (${dotCount}) must match copy count (${copyCount}).` })
+  if (dotCount !== copyCount) issues.push({ severity: "error", templateId, slideIndex, message: `Timeline dot count (${dotCount}) must match copy count (${copyCount}).` })
   return issues
 }
 
@@ -889,12 +892,26 @@ function field(name: string, type: PageTemplateField["type"], description: strin
 }
 
 function getPageTemplate(templateId: string): PageTemplateDefinition {
-  const id = String(templateId || "").trim()
+  const id = canonicalTemplateId(templateId)
   const template = templates.find((item) => item.id === id)
   if (!template) throw new Error(`Unknown page template: ${templateId}`)
   return template
 }
 
+function normalizeTemplateId(templateId: string): string {
+  return String(templateId || "").trim()
+}
+
+function canonicalTemplateId(templateId: string): string {
+  const id = normalizeTemplateId(templateId)
+  if (id === "timeline-roadmap") return "milestone"
+  return id
+}
+
+function isTimelineTemplateId(templateId: string): boolean {
+  return ["milestone", "timeline", "timeline-roadmap"].includes(templateId)
+}
+
 function renderSlideShell(input: { template: PageTemplateDefinition; slideIndex: number; designName: string; title: string; body: string; catalog?: any }): string {
   const hero = ["cover", "section-divider", "closing"].includes(input.template.id)
   const slideQa = hero ? "false" : "true"
@@ -946,6 +963,8 @@ function renderBody(templateId: string, content: Record<string, any>): string {
   if (templateId === "metric-highlight") return `${renderHeader(content, "Metric Highlight")}<div class="template-body">${metricHighlight(content)}</div>`
   if (templateId === "chart-takeaways") return `${renderHeader(content, "Chart + Takeaways")}<div class="template-body template-grid template-chart-layout">${visualSlotPanel()}${chartTakeawayPanel(content)}</div>`
   if (templateId === "table-comparison") return `${renderHeader(content, "Table / Comparison")}<div class="template-body" data-template-slot="table">${table(content)}</div>`
+  if (templateId === "milestone") return `${renderHeader(content, "Milestone")}<div class="template-body">${timeline({ ...content, orientation: "horizontal" })}</div>`
+  if (templateId === "timeline") return `${renderHeader(content, "Timeline")}<div class="template-body">${timeline({ ...content, orientation: "vertical" })}</div>`
   if (templateId === "timeline-roadmap") return `${renderHeader(content, "Timeline / Roadmap")}<div class="template-body">${timeline(content)}</div>`
   if (templateId === "process-steps") return `${renderHeader(content, "Process / Steps")}<div class="template-body"><div class="template-steps" data-template-slot="steps">${steps(content.steps)}</div></div>`
   if (templateId === "recommendation-decision") return `${renderHeader(content, "Recommendation / Decision")}<div class="template-body template-grid cols-3"><div class="template-card" data-template-slot="recommendation"><h2>Recommendation</h2><p>${escapeHtml(stringValue(content.recommendation))}</p>${imageCard(content)}</div><div data-template-slot="rationale">${cards(items(content).slice(0, 1), "h3")}</div><div class="template-card" data-template-slot="next-steps"><h2>Next steps</h2>${orderedSteps(content.steps)}</div></div>`
@@ -1132,7 +1151,8 @@ function scaffoldSeed(templateId: string, seed: Record<string, any>): Record<str
   if (templateId === "metric-highlight") return { metrics: [{ value: "67%", label: "Metric", description: "Replace with interpretation." }, { value: "3x", label: "Comparison", description: "Replace with reading note." }, { value: "14d", label: "Window", description: "Replace with time context." }], insightTitle: "Read the signal", insightBody: "Replace with the decision implication, caveat, or next reading step.", ...base }
   if (templateId === "chart-takeaways") return { takeawaysTitle: "What to read", items: defaultItems(["Trend", "Driver", "Decision use"]), ...base }
   if (templateId === "table-comparison") return { columns: ["Dimension", "Current", "Target"], rows: [["Replace", "Current state", "Target state"], ["Caveat", "Known limit", "Next proof"]], insightTitle: "Insight", insightBody: "Replace with the table reading note or caveat.", ...base }
-  if (templateId === "timeline-roadmap") return { orientation: "horizontal", milestones: [{ date: "2022", label: "Signal", description: "Name the starting condition." }, { date: "2023", label: "Proof", description: "Show the evidence threshold." }, { date: "2024", label: "Inflection", description: "Use the pivotal moment to frame the shift." }, { date: "2025", label: "Scale", description: "Use a taller card for the highlighted milestone.", highlight: true }, { date: "2026", label: "Decision", description: "State what changes next." }], ...base }
+  if (templateId === "milestone" || templateId === "timeline-roadmap") return { orientation: "horizontal", milestones: [{ date: "2022", label: "Signal", description: "Name the starting condition." }, { date: "2023", label: "Proof", description: "Show the evidence threshold." }, { date: "2024", label: "Inflection", description: "Use the pivotal moment to frame the shift." }, { date: "2025", label: "Scale", description: "Use a taller card for the highlighted milestone.", highlight: true }, { date: "2026", label: "Decision", description: "State what changes next." }], ...base }
+  if (templateId === "timeline") return { orientation: "vertical", insightTitle: "Reading the journey", insightBody: "Replace with the timeline interpretation or caveat.", milestones: [{ date: "Mar 2019", label: "Launch", description: "Name the starting event." }, { date: "Nov 2019", label: "Audit", description: "Show the evidence threshold." }, { date: "May 2020", label: "Scale", description: "Explain the operating cadence." }, { date: "Feb 2021", label: "Review", description: "State what changes next." }], ...base }
   if (templateId === "process-steps") return { steps: defaultItems(["Step 1", "Step 2", "Step 3"]), ...base }
   if (templateId === "recommendation-decision") return { recommendation: "Replace with the recommended decision.", items: defaultItems(["Rationale"]), steps: defaultItems(["Pilot", "Validate", "Ship"]), ...base }
   if (templateId === "risks-tradeoffs") return { items: defaultItems(["Risk", "Tradeoff", "Mitigation"]), ...base }

package/lib/page-templates/templates/index.ts

@@ -10,10 +10,12 @@ export * from "./cover"
 export * from "./executive-summary"
 export * from "./key-message-evidence"
 export * from "./metric-highlight"
+export * from "./milestone"
 export * from "./problem-context"
 export * from "./process-steps"
 export * from "./recommendation-decision"
 export * from "./risks-tradeoffs"
 export * from "./section-divider"
 export * from "./table-comparison"
+export * from "./timeline"
 export * from "./timeline-roadmap"

package/lib/page-templates/templates/milestone.ts

@@ -0,0 +1,3 @@
+import { templateModule } from "./shared"
+
+export const milestoneTemplate = templateModule("milestone")

package/lib/page-templates/templates/timeline.ts

@@ -0,0 +1,3 @@
+import { templateModule } from "./shared"
+
+export const timelineTemplate = templateModule("timeline")

package/lib/page-templates/vocabulary.ts

@@ -57,7 +57,8 @@ export const PAGE_TEMPLATE_VOCABULARY: PageTemplateVocabulary[] = [
   vocab("metric-highlight", ["template-stat-grid"], ["metrics"], ["metrics", "insight"], ["Metric values should remain visible outside prose."]),
   vocab("chart-takeaways", ["template-chart-panel", "template-chart-takeaway-panel"], ["visual", "takeaways"], ["visual", "takeaways"], ["Chart/image slot and takeaway text panel must both remain present."]),
   vocab("table-comparison", ["template-table-wrap", "template-table"], ["table"], ["table", "insight"], ["Table headers and body should remain structured, not prose-only."]),
-  vocab("timeline-roadmap", ["template-timeline", "template-timeline-item", "template-timeline-dot", "template-timeline-copy", "template-insight-icon"], ["timeline"], ["timeline", "insight"], ["Each timeline item must keep dot and copy as sibling anchors inside one item.", "Horizontal timeline cards reuse .template-card; highlight uses the item modifier."]),
+  vocab("milestone", ["template-timeline", "template-timeline-item", "template-timeline-dot", "template-timeline-copy", "template-insight-icon"], ["timeline"], ["timeline"], ["Each milestone item must keep dot and copy as sibling anchors inside one item.", "Milestone cards reuse .template-card; highlight uses the item modifier."]),
+  vocab("timeline", ["template-timeline", "template-timeline-item", "template-timeline-dot", "template-timeline-copy"], ["timeline"], ["timeline", "insight"], ["Each timeline item must keep dot and copy as sibling anchors inside one item.", "The optional insight slot explains the sequence without replacing event copy."]),
   vocab("process-steps", ["template-steps", "template-step-number"], ["steps"], ["steps"], ["Steps should remain ordered in DOM order."]),
   vocab("recommendation-decision", ["template-card"], ["recommendation", "rationale", "next-steps"], ["recommendation", "rationale", "next-steps"], ["Keep recommendation, rationale, and next steps separate."]),
   vocab("risks-tradeoffs", ["template-card"], ["risks"], ["risks"], ["Risk/tradeoff cards should name uncertainty explicitly."]),
@@ -132,9 +133,10 @@ export function listPageTemplateVocabulary(): PageTemplateVocabulary[] {
 }
 
 export function getPageTemplateVocabulary(templateId: string): PageTemplateVocabulary {
-  const vocabulary = PAGE_TEMPLATE_VOCABULARY.find((item) => item.templateId === templateId)
+  const id = templateId === "timeline-roadmap" ? "milestone" : templateId
+  const vocabulary = PAGE_TEMPLATE_VOCABULARY.find((item) => item.templateId === id)
   if (!vocabulary) throw new Error(`Unknown page template vocabulary: ${templateId}`)
-  return vocabulary
+  return templateId === "timeline-roadmap" ? { ...vocabulary, templateId } : vocabulary
 }
 
 function vocab(templateId: string, requiredClasses: string[], slotNames: string[], replaceableSlots: string[], contractNotes: string[]): PageTemplateVocabulary {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "description": "Codex-first CLI/MCP workspace for trusted narrative artifacts from local sources, research, and evidence",
   "type": "module",
   "main": "./index.ts",

package/plugins/revela/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "revela",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "description": "Use Revela in Codex to specify, research, plan, make, and export trusted narrative decision artifacts.",
   "author": {
     "name": "cyber-dash-tech",

package/plugins/revela/hooks/revela_post_write_notice.ts

@@ -71,16 +71,16 @@ function titleFromDeckHtml(absolutePath: string): string {
 
 export function formatDeckWebsiteCardHandoffNotice(workspaceRoot: string, target: string): string {
   const absolutePath = resolve(workspaceRoot, target)
-  const deckUrl = pathToFileURL(absolutePath).href
   const title = titleFromDeckHtml(absolutePath)
+  const httpUrlTemplate = `http://127.0.0.1:<port>/${target}`
   return [
     "**Deck website card ready**",
     "",
-    `Artifact QA passed for \`${target}\`. Reply with this standalone deck link so Codex renders an Open in Browser website card:`,
+    `Artifact QA passed for \`${target}\`. Do not open the deck file directly. Start a read-only local static server from the workspace root, then reply with this standalone deck link so Codex renders an Open in Browser website card the user can click:`,
     "",
-    `[${title}](${deckUrl})`,
+    `[${title}](${httpUrlTemplate})`,
     "",
-    `If the card or direct \`file://\` navigation is unavailable, start a read-only local static server from the workspace root and link to \`http://127.0.0.1:<port>/${target}\` instead.`,
+    `Replace \`<port>\` with the actual localhost port. Keep \`file://\` only for non-Codex surfaces that allow direct local-file navigation.`,
   ].join("\n")
 }
 

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

@@ -113,7 +113,7 @@ const tools = [
     inputSchema: objectSchema({
       workspaceRoot: stringProp("Optional workspace root."),
       designName: stringProp("Optional design name. Defaults to the active design."),
-      templateId: requiredStringProp("Built-in template id, such as timeline-roadmap."),
+      templateId: requiredStringProp("Built-in template id, such as milestone or timeline."),
       slideIndex: requiredNumberProp("Positive 1-based slide index."),
       content: objectProp("Template content fields. The built-in template renderer owns the HTML skeleton."),
     }, ["templateId", "slideIndex", "content"]),
@@ -122,14 +122,14 @@ const tools = [
     name: "revela_page_template_foundation",
     description: "Read the built-in template foundation for custom design authoring: scaffold HTML, CSS hooks, slots, and contract notes.",
     inputSchema: objectSchema({
-      templateId: requiredStringProp("Built-in template id, such as timeline-roadmap."),
+      templateId: requiredStringProp("Built-in template id, such as milestone or timeline."),
     }, ["templateId"]),
   },
   {
     name: "revela_page_template_vocabulary",
     description: "Read machine-readable classes, slots, editable regions, replaceable regions, and contract notes for one page template.",
     inputSchema: objectSchema({
-      templateId: requiredStringProp("Built-in template id, such as timeline-roadmap."),
+      templateId: requiredStringProp("Built-in template id, such as milestone or timeline."),
     }, ["templateId"]),
   },
   {
@@ -138,7 +138,7 @@ const tools = [
     inputSchema: objectSchema({
       workspaceRoot: stringProp("Optional workspace root."),
       designName: stringProp("Optional design name. Defaults to the active design."),
-      templateId: requiredStringProp("Built-in template id, such as timeline-roadmap."),
+      templateId: requiredStringProp("Built-in template id, such as milestone or timeline."),
       slideIndex: requiredNumberProp("Positive 1-based slide index."),
       seed: objectProp("Optional scaffold seed fields. This is not the final authoring interface."),
     }, ["templateId", "slideIndex"]),
@@ -150,7 +150,7 @@ const tools = [
       workspaceRoot: stringProp("Optional workspace root."),
       outputPath: requiredStringProp("Workspace-relative HTML deck path."),
       designName: stringProp("Optional design name. Defaults to the active design."),
-      templateId: requiredStringProp("Built-in template id, such as timeline-roadmap."),
+      templateId: requiredStringProp("Built-in template id, such as milestone or timeline."),
       slideIndex: requiredNumberProp("Positive 1-based slide index."),
       seed: objectProp("Optional scaffold seed fields. LLM should bounded-edit the inserted slide after scaffold creation."),
     }, ["outputPath", "templateId", "slideIndex"]),
@@ -162,7 +162,7 @@ const tools = [
       workspaceRoot: stringProp("Optional workspace root."),
       outputPath: requiredStringProp("Workspace-relative HTML deck path."),
       designName: stringProp("Optional design name. Defaults to the active design."),
-      templateId: requiredStringProp("Built-in template id, such as timeline-roadmap."),
+      templateId: requiredStringProp("Built-in template id, such as milestone or timeline."),
       slideIndex: requiredNumberProp("Positive 1-based slide index."),
       content: objectProp("Template content fields. Prefer scaffold-first flow for new deck creation."),
     }, ["outputPath", "templateId", "slideIndex", "content"]),
@@ -288,7 +288,7 @@ const tools = [
     inputSchema: objectSchema({
       workspaceRoot: stringProp("Optional workspace root."),
       name: requiredStringProp("Design name to preview."),
-      source: stringProp("Optional source: draft, installed, or builtin. Defaults to draft when present, otherwise installed/builtin."),
+      source: enumProp(["draft", "installed", "builtin"], "Optional source. Defaults to draft when present, otherwise installed/builtin."),
     }, ["name"]),
   },
   {
@@ -476,10 +476,12 @@ async function handle(req: JsonRpcRequest): Promise<any | undefined> {
     bootLog("request", { id: req.id, method: req.method })
     if (req.method === "initialize") {
       bootLog("initialize-received", { id: req.id, protocolVersion: req.params?.protocolVersion })
+      const runtimeInfo = await runtime()
+      const doctor = runtimeInfo.doctor({})
       return result(req.id, {
         protocolVersion: req.params?.protocolVersion || "2024-11-05",
         capabilities: { tools: {} },
-        serverInfo: { name: "revela", version: "0.18.15" },
+        serverInfo: { name: "revela", version: doctor.version },
       })
     }
     if (req.method === "tools/list") {

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

@@ -29,7 +29,7 @@ Use this skill as the main Revela entrypoint in Codex. It should inspect intent
 - `spec.md` exists but source support, material review, or findings are missing: use `revela-research`.
 - `spec.md` and sufficient findings exist but `deck-plan.md` is missing or needs normal authoring: use `revela-research` Planning Handoff.
 - Valid `deck-plan.md` exists and the user asks to make, generate, render, or update a deck: use `revela-make-deck`.
-- Existing deck artifact and the user asks to review, annotate, diagnose, QA, or refine: use Codex Browser's native browsing/annotation flow. If the deck was not just generated, reply with the existing deck as a website card/link and use native annotations after it opens; route export requests to `revela-export`.
+- Existing deck artifact and the user asks to review, annotate, diagnose, QA, or refine: use Codex Browser's native browsing/annotation flow. If the deck was not just generated, start a read-only local static server from the workspace root, reply with the existing deck as a localhost website card/link, and use native annotations after the user opens it; route export requests to `revela-export`.
 - Existing deck artifact and the user asks for PDF, PPTX, or PNG output: use `revela-export`.
 - If the next step is still ambiguous after inspection, ask the smallest missing question and recommend the safest next specialist skill.
 

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

@@ -38,7 +38,7 @@ For new or edited designs:
 5. Draft complete `DESIGN.md` and complete `design.css` content.
 6. Call `revela_design_draft_create` with `designCss`; when uploaded or local design material exists, pass `assets: [{ path: "assets/...", contentBase64|content|sourcePath }]` so the files are written into the draft package.
 7. Call `revela_design_draft_validate`.
-8. Call `revela_design_preview` for the draft and inspect the generated preview in Browser.
+8. Call `revela_design_preview` for the draft, start a read-only local static server from the returned `browserHandoff.serveRoot`, and reply with the resulting localhost preview link for the user to open in Codex Browser.
 9. If validation or preview review fails, revise the draft content and repeat draft create/validate/preview.
 10. Call `revela_design_draft_install` only after the draft validates and the user intent is to install it.
 11. Call `revela_design_activate` only when the user asks to make it active.
@@ -66,6 +66,7 @@ Use `revela_design_create` only when the user explicitly requests direct local c
 - Optional assets must live under `assets/**`; reference them as package-relative paths like `assets/cover-background.png`.
 - `DESIGN.md` may reference package assets in rules, layouts, or components with `assets/...`; do not reference workspace `assets/` media manifest entries for design-owned visuals.
 - `revela_design_preview` must generate the visual preview; do not hand-write package `preview.html` for ordinary CSS-native design drafts.
+- Do not open `file://` preview URLs in Codex Browser. Use the returned `browserHandoff` fields to serve the preview over `http://127.0.0.1:<port>/preview.html` and let the user click the link.
 - If design assets are present, the generated preview should visibly use the saved `assets/...` files when the design CSS references them.
 - Generated preview should show the built-in page templates with normal, dense, chart/table, timeline, image, and source-note-like states.
 - Preserve source inspiration and limitations explicitly; do not copy copyrighted design text or assets into the package.

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

@@ -46,7 +46,7 @@ Report:
   - `spec.md` exists but no `researches/`: run `revela-research`.
   - Research exists but no `deck-plan.md`: continue `revela-research` to the Planning Handoff.
   - Valid `deck-plan.md` but no deck artifact: run `revela-make-deck`.
-  - Existing deck artifact: surface the HTML deck as a website card/link for Codex Browser native annotation, or run `revela-export` for PDF/PPTX/PNG.
+  - Existing deck artifact: start a read-only local static server from the workspace root and surface the HTML deck as a localhost website card/link for Codex Browser native annotation, or run `revela-export` for PDF/PPTX/PNG.
 
 ## Must Not
 

package/plugins/revela/skills/revela-make-deck/SKILL.md

@@ -17,7 +17,7 @@ Use this skill when the user asks to make, generate, render, or update a Revela
 - Deck-local `decks/_revela-design/**/design.css` files are generated design snapshots. Do not patch them during deck making; regenerate the deck foundation or enter the design workflow instead.
 - Active/requested domain guidance may inform communication framing, but it is not source evidence.
 - Generated artifacts live under `decks/*.html`.
-- After final Artifact QA passes, reply with the generated HTML deck as a standalone website link/card that opens in Codex Browser for native browsing and annotation.
+- After final Artifact QA passes, reply with the generated HTML deck as a standalone localhost website link/card that the user can click to open in Codex Browser for native browsing and annotation.
 - Do not require a Narrative Vault before generating a deck.
 - This skill does not own normal plan authoring; `revela-research` owns source preparation and `deck-plan.md` planning handoff.
 - `deck-plan.md` is required for normal deck generation.
@@ -93,8 +93,8 @@ Use this phase when the user asks to make, generate, render, or update an HTML d
 12. Every slide must have exactly one direct `.slide-canvas` child.
 13. Keep the HTML valid after each write.
 14. After every HTML write, call `revela_run_deck_qa` and repair hard errors before continuing or export.
-15. After the final `revela_run_deck_qa` passes with zero hard errors, reply with a standalone Markdown link to the generated HTML deck artifact so Codex renders an Open in Browser website card.
-16. Prefer an absolute `file://` URL for the card. If the card or direct file navigation is unavailable, start a read-only local static server from the workspace root and use the exact `http://127.0.0.1:<port>/decks/<file>.html` URL.
+15. After the final `revela_run_deck_qa` passes with zero hard errors, do not open the deck file directly. Start a read-only local static server from the workspace root and reply with a standalone Markdown link to the generated HTML deck artifact so the user can click it open in Codex Browser.
+16. Use the exact `http://127.0.0.1:<port>/decks/<file>.html` URL for the card, replacing `<port>` with the actual localhost port. Keep `file://` only for non-Codex surfaces that allow direct local-file navigation.
 
 ## Outputs