@cyber-dash-tech/revela 0.18.11 → 0.18.13

package/README.md

@@ -2,39 +2,24 @@
 
 **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-727%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-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)
 
 <p align="center">
-  <img src="assets/img/logo.png" alt="Revela" width="560" />
+  <img src="assets/img/logo-wordmark.png" alt="Revela" width="320" />
 </p>
 
-Revela works from [OpenCode](https://opencode.ai) and Codex to turn source materials, research, data, and intent into trusted, traceable, presentation-ready decision artifacts.
+Revela is a Codex plugin for turning source materials, research, data, and intent into trusted, traceable, presentation-ready decision artifacts.
 
-Its deck-first workspace reviews local 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, reviews them, and exports PDF/PPTX/PNG artifacts.
 
 ## Install
 
-### OpenCode
-
-Install Revela through `opencode.json` with the npm package `@cyber-dash-tech/revela`:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@cyber-dash-tech/revela"]
-}
-```
-
-Restart OpenCode.
-
-To install globally, add the same entry to `~/.config/opencode/opencode.json`.
-
 ### Codex
 
 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.11 mcp` to start the MCP server.
+- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.18.13 mcp` to start the MCP server.
 - For interactive Review Apply actions, `codex exec` must also work because the Review UI uses it after saved comments are applied.
 
 Optional preflight:
@@ -55,11 +40,11 @@ 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.11
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.13
 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.11 mcp` so npm can fetch the published package and its dependencies.
+The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.18.13 mcp` so npm can fetch the published package and its dependencies.
 
 You do not need to run `bun install` inside the Codex marketplace clone.
 
@@ -111,13 +96,19 @@ Revela includes built-in deck designs:
   <img src="assets/img/monet-03.jpg" alt="Monet design preview 3" 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%" />
+</p>
+
 `starter` is the clean default presentation style.
 
-Switch designs with:
+To switch designs in Codex, ask:
 
-```text
-/revela design --use summit
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/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.
 
@@ -125,9 +116,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.
 
-```text
-/revela domain
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/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.
 
@@ -137,83 +126,61 @@ 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.
 
-```text
-revela, use consulting as the domain.
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), use consulting as the domain.
 
 2. Choose the deck design before rendering so generated artifacts use the intended visual language.
 
-```text
-revela, use summit as the design.
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), use summit as the design.
 
 3. Create a custom design when you want a different visual direction.
 
-```text
-revela, 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.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 may ask for references or constraints, then creates and validates the design. When it is ready, switch to it:
 
-```text
-revela, use neon-finance as the design.
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/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.
 
-```text
-revela, help me init this workspace from the local materials.
-```
+> [$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.
 
 5. Research source-linked deck inputs and save findings.
 
-```text
-revela, research the public evidence and examples needed for this deck.
-```
+> [$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.
 
 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.
 
-```text
-revela, create or update the deck plan before generating HTML.
-```
+> [$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.
 
 7. Make an HTML deck from the current deck plan.
 
-```text
-revela, make the 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.
 
 8. Review the generated deck for Artifact QA and targeted edits.
 
-```text
-revela, review the generated deck.
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), review the generated deck.
 
 9. Export a PDF after deck QA passes.
 
-```text
-revela, export the deck to PDF.
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), export the deck to PDF.
 
 10. Export an editable PPTX after deck QA passes.
 
-```text
-revela, export the deck to PPTX.
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), export the deck to PPTX.
 
 11. Export per-slide PNG files after deck QA passes.
 
-```text
-revela, export the deck to PNG.
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md), export the deck to PNG.
 
 ## Review A Deck
 
 Use Review after generating an HTML deck:
 
-```text
-/revela review --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:
 

package/README.zh-CN.md

@@ -2,39 +2,24 @@
 
 [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-727%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-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)
 
 <p align="center">
-  <img src="assets/img/logo.png" alt="Revela" width="560" />
+  <img src="assets/img/logo-wordmark.png" alt="Revela" width="320" />
 </p>
 
-Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材料、调研、数据和用户意图转成可信、可追踪、可直接用于决策沟通的 deck artifact。
+Revela 是 Codex plugin，用来把来源材料、调研、数据和用户意图转成可信、可追踪、可直接用于决策沟通的 deck artifact。
 
-它的 deck-first workspace 会审阅本地资料、保存 source-linked research、生成明确的 `deck-plan.md`、产出 HTML deck，并支持 Review 与 PDF/PPTX/PNG 导出。
+在你的本地 workspace 中，Revela 会审阅本地资料、保存 source-linked research、生成明确的 `deck-plan.md`、产出 HTML deck，并支持 Review 与 PDF/PPTX/PNG 导出。
 
 ## 安装
 
-### OpenCode
-
-通过 `opencode.json` 安装 npm package `@cyber-dash-tech/revela`：
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@cyber-dash-tech/revela"]
-}
-```
-
-重启 OpenCode。
-
-如果想全局安装，把同样配置写到 `~/.config/opencode/opencode.json`。
-
 ### Codex
 
 环境要求：
 
 - 需要已安装 Codex CLI，并且 shell 中可以执行 `codex`。
-- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.11 mcp` 启动 MCP server。
+- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.13 mcp` 启动 MCP server。
 - 如果使用 Review UI 的 Apply，需要 `codex exec` 可用；评论会先保存，点击 Apply 后才执行修复。
 
 可选的安装前检查：
@@ -55,11 +40,11 @@ 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.11
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.13
 codex plugin add revela@revela
 ```
 
-Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.11 mcp`，由 npm 获取已发布 package 及其 dependencies。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.13 mcp`，由 npm 获取已发布 package 及其 dependencies。
 
 不需要在 Codex marketplace clone 里运行 `bun install`。
 
@@ -111,13 +96,19 @@ Revela 内置多个 deck design：
   <img src="assets/img/monet-03.jpg" alt="Monet design preview 3" 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%" />
+</p>
+
 `starter` 是简洁默认演示风格。
 
-切换设计：
+在 Codex 中切换 design，可以这样问：
 
-```text
-/revela design --use summit
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，use summit as design.
 
 在 Codex 中，可以直接让 Revela 列出或切换 design；生成 deck 时会使用 active design。
 
@@ -125,9 +116,7 @@ Revela 内置多个 deck design：
 
 Domain 提供特定场景的沟通 guidance，例如 consulting、product 或 investor communication。需要让 Revela 按具体沟通场景调整 deck framing 时使用。
 
-```text
-/revela domain
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，列出 available domains。
 
 在 Codex 中，可以直接让 Revela 列出或切换 domain；active domain 会用于 init、research 和 deck planning 阶段的 framing。
 
@@ -137,83 +126,61 @@ Domain 提供特定场景的沟通 guidance，例如 consulting、product 或 in
 
 1. 先选择 domain，让 Revela 按你的沟通场景 framing 受众、决策、风险和潜在质疑。
 
-```text
-revela，use consulting as domain.
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，use consulting as domain.
 
 2. 再选择 design，让后续生成的 deck 使用指定视觉风格。
 
-```text
-revela，use summit as design.
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，use summit as design.
 
 3. 如果需要不同的视觉方向，可以创建一个自定义 design。
 
-```text
-revela，创建一个名为 neon-finance 的新 design：金融仪表盘风格，深色界面、精密网格、亮绿色重点色。
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，创建一个名为 neon-finance 的新 design：金融仪表盘风格，深色界面、精密网格、亮绿色重点色。
 
 Revela 可能会继续询问参考图、风格约束或禁忌项，然后创建并校验 design。创建完成后再切换使用：
 
-```text
-revela，使用 neon-finance 作为 design。
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，使用 neon-finance 作为 design。
 
 4. 初始化本地 material intake。Init 会扫描、抽取并审阅 workspace source；它不会创建 Narrative Vault。
 
-```text
-revela，帮我 init 这个 workspace，先读本地材料。
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，帮我 init 这个 workspace，先读本地材料。
 
 5. 针对 deck 所需输入做 research，并保存带来源的 findings。
 
-```text
-revela，research 这个 deck 需要的公开证据、案例和 source。
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，research 这个 deck 需要的公开证据、案例和 source。
 
 6. 先创建或更新 deck plan，明确 slide 顺序、章节结构、source links、unresolved inputs、source limitations 和 visual intent，再生成 HTML。
 
-```text
-revela，生成 HTML 前先 create or update deck plan。
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，生成 HTML 前先 create or update deck plan。
 
 7. 基于当前 deck plan 生成 HTML deck。
 
-```text
-revela，基于当前 deck plan make deck。
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，基于当前 deck plan make deck。
 
 8. Review 生成后的 deck，检查 Artifact QA，并做定向修改。
 
-```text
-revela，review 生成好的 deck。
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，review 生成好的 deck。
 
 9. QA 通过后导出 PDF。
 
-```text
-revela，把 deck export 成 PDF。
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，把 deck export 成 PDF。
 
 10. QA 通过后导出可编辑 PPTX。
 
-```text
-revela，把 deck export 成 PPTX。
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，把 deck export 成 PPTX。
 
 11. QA 通过后导出每页 PNG。
 
-```text
-revela，把 deck export 成 PNG。
-```
+> [$revela:revela](/Users/mengdigao/.codex/plugins/cache/revela/revela/0.1.0+codex.20260524164007/skills/revela/SKILL.md)，把 deck export 成 PNG。
 
 ## Review Deck
 
 生成 HTML deck 后可以进入 Review：
 
-```text
-/revela review --deck
-```
+> [$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 和定向修改：
 

package/designs/lucent/DESIGN.md

@@ -0,0 +1,171 @@
+---
+name: lucent
+description: Luminous report design with pale analytical pages, glassy blue-violet accents, and data-forward layouts
+author: cyber-dash
+version: 1.0.0
+preview:
+---
+
+## Visual Style - Lucent
+
+Lucent is a clean executive report design for analytical and strategic decks. It uses bright pages, restrained glass textures, crisp Chinese/English typography, and blue-violet-cyan accent gradients. The design is optimized for source-backed narrative, charts, Sankey flows, tables, recommendation cards, and polished cover/closing moments.
+
+<!-- @design:foundation:start -->
+
+### Foundation
+
+Use a fixed `1920px` x `1080px` `.slide-canvas` inside a dark navy browser frame. Scale the canvas with JavaScript transform on viewport resize. Keep all dimensions fixed in pixels; do not use viewport-scaled typography.
+
+```css
+:root {
+  --bg-frame: #07111f;
+  --bg-page: #f7f9fc;
+  --bg-page-alt: #eef3f9;
+  --surface: #ffffff;
+  --surface-tint: #f1f6fc;
+  --surface-blue: #e7f0fb;
+  --text-primary: #101a2b;
+  --text-secondary: #42526a;
+  --text-muted: #7b8aa0;
+  --line: rgba(44, 70, 108, 0.14);
+  --line-strong: rgba(44, 70, 108, 0.28);
+  --accent-primary: #315eea;
+  --accent-secondary: #6e5df6;
+  --accent-cyan: #18a8d8;
+  --accent-coral: #f06370;
+  --accent-soft: #dbe8ff;
+  --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;
+}
+```
+
+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.
+- Use `assets/soft-texture.jpg`, `assets/card-lens.jpg`, and `assets/report-visual.jpg` as subtle report accents; never inline base64 images in generated decks.
+
+<!-- @design:foundation:end -->
+
+<!-- @design:rules:start -->
+
+### Rules
+
+- 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.
+- 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.
+- Avoid decorative orbs except the Lucent glass assets provided in `assets/`; do not create new gradient blobs.
+- All image assets in design previews must be local package assets under `designs/lucent/assets/`.
+
+<!-- @design:rules:end -->
+
+<!-- @design:layouts:start -->
+
+<!-- @layout:cover:start qa=false -->
+Full-bleed opening slide with one dominant background image, dark overlay, and bottom-left hero title. Slots: `hero`.
+<!-- @layout:cover:end -->
+
+<!-- @layout:toc:start qa=true -->
+Two-column table of contents with a left title rail, right numbered agenda, and optional glass orb. Slots: `left`, `list`, `asset`.
+<!-- @layout:toc:end -->
+
+<!-- @layout:report-story:start qa=true -->
+Report slide with top title block and a two-column body for narrative text plus supporting media or evidence. Slots: `title`, `left`, `right`.
+<!-- @layout:report-story:end -->
+
+<!-- @layout:card-grid:start qa=true -->
+Top title block with three card columns. Use for insight clusters, operating gaps, or comparison. Slots: `title`, `cards`.
+<!-- @layout:card-grid:end -->
+
+<!-- @layout:chart-with-takeaways:start qa=true -->
+Top title block with a dominant chart on the left and stacked takeaway cards on the right. Slots: `title`, `chart`, `takeaways`.
+<!-- @layout:chart-with-takeaways:end -->
+
+<!-- @layout:sankey:start qa=true -->
+Top title block with a wide Sankey chart and a right explanation column. Slots: `title`, `sankey`, `takeaways`.
+<!-- @layout:sankey:end -->
+
+<!-- @layout:table:start qa=true -->
+Top title block with one large table panel and explanatory reading notes. Slots: `title`, `table`.
+<!-- @layout:table:end -->
+
+<!-- @layout:roadmap:start qa=true -->
+Top title block with a horizontal four-phase roadmap across the body. Slots: `title`, `roadmap`.
+<!-- @layout:roadmap:end -->
+
+<!-- @layout:recommendation:start qa=true -->
+Three-column recommendation page with primary recommendation, reasoning, and next steps. Slots: `recommendation`, `rationale`, `steps`.
+<!-- @layout:recommendation:end -->
+
+<!-- @layout:closing:start qa=false -->
+Full-bleed closing slide with a background image, soft overlay, and concise final title. Slots: `hero`.
+<!-- @layout:closing:end -->
+
+<!-- @design:layouts:end -->
+
+<!-- @design:components:start -->
+
+<!-- @component:hero:start -->
+Full-canvas image-backed hero with `.hero`, `.hero-bg`, `.hero-shade`, and `.hero-title`. Use only for cover, section divider, and closing slides.
+<!-- @component:hero:end -->
+
+<!-- @component:toc:start -->
+Lucent agenda component using `.toc-wrap`, `.toc-title`, `.toc-list`, and optional `.toc-orb`. Use for navigation, not for normal text-heavy content.
+<!-- @component:toc:end -->
+
+<!-- @component:text-panel:start -->
+Focused text module for setup, reading guidance, and narrative explanation. Use inside report layouts or boxes.
+<!-- @component:text-panel:end -->
+
+<!-- @component:box:start -->
+Card/group primitive for insights, evidence, operating gaps, recommendations, and rationale. Use `.box`, `.insight-card`, or `.rec-panel` depending on density.
+<!-- @component:box:end -->
+
+<!-- @component:media:start -->
+Image frame for screenshots, report visuals, diagrams, and supporting photography. Use local assets and keep evidence visuals readable.
+<!-- @component:media:end -->
+
+<!-- @component:stat-card:start -->
+Compact metric tile with `.stat-card` and `.stat-value`. Use for one number plus one interpretation line.
+<!-- @component:stat-card:end -->
+
+<!-- @component:echart-panel:start -->
+Chart frame with `.echart-panel`, `.chart-header`, `.echart-container`, and caption/source text. Use ECharts after DOM initialization and call resize on viewport changes. Sankey charts are an `echart-panel` usage pattern, not a separate primary component; keep the chart wide, labels muted, and interpretation in the layout's takeaway slot.
+<!-- @component:echart-panel:end -->
+
+<!-- @component:data-table:start -->
+Structured table component with `.table-panel`, tabular numbers, muted headers, and right-aligned numeric columns.
+<!-- @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.
+<!-- @component:roadmap-horizontal:end -->
+
+<!-- @component:steps:start -->
+Ordered action list for next steps. Keep it short: three to five steps, each with a number and one concise action.
+<!-- @component:steps:end -->
+
+<!-- @component:page-number:start -->
+Small absolute page number utility. Use muted color on report pages and light color on dark hero pages.
+<!-- @component:page-number:end -->
+
+<!-- @component:brand-watermark:start -->
+Small top-right logo or brand mark. Keep it clear, restrained, and never use logos as decorative backgrounds.
+<!-- @component:brand-watermark:end -->
+
+<!-- @design:components:end -->
+
+<!-- @design:chart-rules:start -->
+
+### Chart Rules
+
+- Use ECharts for line, bar, and Sankey charts.
+- Initialize charts after `SlidePresentation` setup and resize them on `window.resize`.
+- Use Lucent chart colors: `#315eea`, `#6e5df6`, `#18a8d8`, `#f06370`, and muted text `#7b8aa0`.
+- Keep chart backgrounds transparent and place charts inside stable `.echart-container` regions with explicit height or flex sizing.
+- Sankey charts inside `echart-panel` should use low-curvature links, restrained labels, and a separate takeaway column for interpretation.
+
+<!-- @design:chart-rules:end -->