@cyber-dash-tech/revela 0.7.8 → 0.8.1

package/README.md

@@ -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-171%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-178%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="800" />
@@ -112,7 +112,7 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 Before the agent writes `decks/humanoid-robotics.html`, it must update `DECKS.json` through the `revela-decks` tool with the active deck, confirmed slide specs, layouts, components, and computed `writeReadiness.status: ready`. You can ask for an explicit readiness check at any time:
 
 ```text
-/revela review humanoid-robotics
+/revela review
 ```
 
 Export when needed, either manually or by asking the agent to export:
@@ -138,9 +138,9 @@ Disable presentation mode when done:
 /revela disable                  disable presentation mode
 
 /revela init                     initialize or refresh workspace DECKS.json
-/revela review [slug]            review active deck readiness before writing HTML
+/revela review                   review current deck readiness before writing HTML
 /revela remember <text>          save an explicit user/workflow preference
-/revela edit [target]            open visual editor for active deck or a specific target
+/revela edit                     open visual editor for the only deck in decks/
 
 /revela designs                  list installed designs
 /revela designs <name>           activate a design
@@ -185,7 +185,7 @@ Revela uses a workspace-root `DECKS.json` file for cross-session continuity and
 It has two jobs:
 
 - workspace memory: stable project context, source materials, explicit user preferences, deck history, and open questions
-- active deck spec: current deck slug, output path, prerequisites, research plan, per-slide content, layouts, components, evidence, visuals, blockers, and write readiness
+- active deck spec: current deck output path, prerequisites, research plan, per-slide content, layouts, components, evidence, visuals, blockers, and write readiness
 
 `DECKS.json` is the source of truth for workspace memory and deck readiness.
 
@@ -198,7 +198,7 @@ Create or refresh it with:
 Review the current deck state with:
 
 ```text
-/revela review [slug]
+/revela review
 ```
 
 `/revela review` does not write the final HTML deck. It reads and updates `DECKS.json` through the `revela-decks` tool, checks what is missing, and sets `writeReadiness.status` to `ready` only when the deck is ready to generate.
@@ -351,7 +351,7 @@ You can ask Revela to create a new local design interactively:
 /revela designs-new my-design
 ```
 
-The agent will interview you for visual references, summarize a design brief for confirmation, then save `DESIGN.md` and `preview.html` into your local Revela designs directory. The default structural base is an internal neutral `starter` design, which is hidden from the normal design list. Use `--base summit` or `--base monet` only when you want to derive from those specific styles.
+The agent will interview you for visual references, summarize a design brief for confirmation, then save `DESIGN.md` and `preview.html` into your local Revela designs directory. For AI-authored designs, `preview.html` is required: it must include cover and closing slides, and it must showcase every `@component:*` before `revela-designs-author` will accept the package. The default structural base is an internal neutral `starter` design, which is hidden from the normal design list. Use `--base summit` or `--base monet` only when you want to derive from those specific styles.
 
 Refine an existing local design:
 
@@ -374,7 +374,7 @@ Recommended structure:
 ```text
 my-design/
 ├── DESIGN.md
-└── preview.html        optional, but recommended for humans
+└── preview.html        required for AI-authored designs
 ```
 
 `DESIGN.md` starts with frontmatter metadata:
@@ -565,7 +565,9 @@ If a design has no markers, Revela falls back to injecting the full `DESIGN.md`
 - Put the non-negotiable rules in `foundation` and `rules`; do not hide essential constraints only inside one layout
 - Keep layout names semantically meaningful; they become the vocabulary the model sees in the layout index
 - If your design defines a custom CSS class, document that class inside `DESIGN.md`; QA checks can flag classes not present in the design vocabulary
-- Add `preview.html` when possible so humans can inspect the design before activating it
+- For AI-authored designs, `preview.html` must include `<section class="slide" data-slide-role="cover">` and `<section class="slide" data-slide-role="closing">`
+- For AI-authored designs, `preview.html` must visibly showcase every `@component:*` and mark each sample with `data-preview-component="<component-name>"`; otherwise `revela-designs-author create/validate` will fail
+- When the design supports chart styling, include a 3x3 ECharts gallery with at least 9 chart examples in `preview.html`; this is a quality requirement for the agent workflow, not a hard validation blocker
 
 Install a custom design:
 
@@ -591,19 +593,17 @@ A custom domain is a folder containing `INDUSTRY.md`.
 
 ## Visual Editing
 
-Open the visual editor for the active deck, or pass a slug / workspace-relative HTML path:
+Open the visual editor for the only HTML deck in `decks/`:
 
 ```text
 /revela edit
-/revela edit my-deck
-/revela edit decks/my-deck.html
 ```
 
-Without a target, `/revela edit` opens `DECKS.json.activeDeck`. If no active deck is set and there is exactly one deck in `DECKS.json`, it opens that deck.
+`/revela edit` does not accept a target in Revela 0.8. If `decks/` contains exactly one `.html` file, Revela opens it. If `decks/` contains zero or multiple `.html` files, Revela asks you to generate a deck first or move extra decks to separate workspaces.
 
 The editor opens in your browser. Use `Ctrl`/`Cmd` + click to reference deck elements, write a natural-language comment, then send it back to OpenCode. Revela sends a structured edit prompt that includes the deck file, slide context, selected element metadata, and your comment.
 
-LLM tool equivalent: `revela-edit` with `{ "target": "decks/my-deck.html" }`. This lets the agent open the same editor when you say things like “I want to edit @decks/my-deck.html”.
+LLM tool equivalent: `revela-edit` with no target. This lets the agent open the same editor when you say things like “I want to edit the deck”.
 
 `/revela edit` prepares minimal `DECKS.json` state for the existing HTML deck if needed, so the normal deck write gate can still protect `decks/*.html` while allowing targeted edits.
 

package/README.zh-CN.md

@@ -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-171%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-178%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="800" />
@@ -111,7 +111,7 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 在 agent 写入 `decks/humanoid-robotics.html` 之前，它必须通过 `revela-decks` 工具更新 `DECKS.json`：记录 active deck、已确认的逐页规格、layout、component，并由工具计算出 `writeReadiness.status: ready`。你也可以随时显式触发 readiness 检查：
 
 ```text
-/revela review humanoid-robotics
+/revela review
 ```
 
 需要导出时，可以手动调用，也可以让 agent 直接导出：
@@ -137,9 +137,9 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 /revela disable                  关闭演示文稿模式
 
 /revela init                     初始化或刷新工作区 DECKS.json
-/revela review [slug]            写 HTML 前检查 active deck readiness
+/revela review                   写 HTML 前检查当前 deck readiness
 /revela remember <text>          保存明确的用户/工作流偏好
-/revela edit [target]            打开 active deck 或指定 target 的可视化编辑器
+/revela edit                     打开 decks/ 下唯一 deck 的可视化编辑器
 
 /revela designs                  列出已安装 design
 /revela designs <name>           激活某个 design
@@ -184,7 +184,7 @@ Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生
 它有两个职责：
 
 - 工作区记忆：稳定项目背景、源材料、明确用户偏好、历史 deck 和开放问题
-- active deck 规格：当前 deck slug、输出路径、前置条件、research plan、逐页内容、layout、component、证据、视觉需求、blocker 和 write readiness
+- active deck 规格：当前 deck 输出路径、前置条件、research plan、逐页内容、layout、component、证据、视觉需求、blocker 和 write readiness
 
 `DECKS.json` 是工作区记忆和 deck readiness 的 source of truth。
 
@@ -197,7 +197,7 @@ Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生
 检查当前 deck 状态：
 
 ```text
-/revela review [slug]
+/revela review
 ```
 
 `/revela review` 不会写最终 HTML deck。它通过 `revela-decks` 工具读取并更新 `DECKS.json`，检查缺失项，并且只有在 deck 真的可以生成时才把 `writeReadiness.status` 设为 `ready`。
@@ -317,7 +317,7 @@ Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生
 /revela designs-new my-design
 ```
 
-Agent 会先询问你的审美参考，整理设计 brief 并等待确认，然后把 `DESIGN.md` 和 `preview.html` 保存到本地 Revela designs 目录。默认结构底座是内部中性 `starter` design，它不会出现在普通 design 列表中。只有当你明确想从 `summit` 或 `monet` 的具体风格派生时，才建议使用 `--base summit` 或 `--base monet`。
+Agent 会先询问你的审美参考，整理设计 brief 并等待确认，然后把 `DESIGN.md` 和 `preview.html` 保存到本地 Revela designs 目录。对 AI 生成的 design，`preview.html` 是必需验收面：它必须包含 cover 和 closing 页，并且必须展示所有 `@component:*`，否则 `revela-designs-author` 不会接受这个包。默认结构底座是内部中性 `starter` design，它不会出现在普通 design 列表中。只有当你明确想从 `summit` 或 `monet` 的具体风格派生时，才建议使用 `--base summit` 或 `--base monet`。
 
 调整已有本地 design：
 
@@ -340,7 +340,7 @@ Agent 会询问你想修改什么，读取当前 design，整理 edit brief 并
 ```text
 my-design/
 ├── DESIGN.md
-└── preview.html        可选，但推荐，方便人工预览
+└── preview.html        AI 生成 design 必需
 ```
 
 `DESIGN.md` 顶部使用 frontmatter：
@@ -530,7 +530,9 @@ Prompt 注入规则：
 - 把不可妥协的规则放进 `foundation` 和 `rules`，不要只藏在某个 layout 里
 - layout 名称尽量语义化，因为模型在 layout index 里首先看到的就是这些名字
 - 如果定义了自定义 CSS class，记得在 `DESIGN.md` 里写出来；QA 会检查 design 词汇表之外的新 class
-- 如果条件允许，最好同时提供 `preview.html`，方便人工预览和验收
+- AI 生成的 design 必须在 `preview.html` 中包含 `<section class="slide" data-slide-role="cover">` 和 `<section class="slide" data-slide-role="closing">`
+- AI 生成的 design 必须在 `preview.html` 中可视化展示每个 `@component:*`，并用 `data-preview-component="<component-name>"` 标记；否则 `revela-designs-author create/validate` 会失败
+- 如果 design 支持图表样式，`preview.html` 应包含 3x3 ECharts 九宫格，至少展示 9 个 chart 示例；这是 agent 工作流的质量要求，不是硬校验 blocker
 
 安装自定义 design：
 
@@ -556,19 +558,17 @@ Prompt 注入规则：
 
 ## 可视化编辑
 
-可以直接打开 active deck，也可以传入 deck slug 或工作区相对 HTML 路径：
+打开 `decks/` 下唯一 HTML deck 的可视化编辑器：
 
 ```text
 /revela edit
-/revela edit my-deck
-/revela edit decks/my-deck.html
 ```
 
-不传 target 时，`/revela edit` 会打开 `DECKS.json.activeDeck`。如果没有 active deck，但 `DECKS.json` 里只有一个 deck，则打开这个唯一 deck。
+Revela 0.8 中 `/revela edit` 不接受 target。如果 `decks/` 下正好有一个 `.html` 文件，Revela 会打开它。如果 `decks/` 下没有 HTML 或有多个 HTML，Revela 会提示先生成 deck，或把多余 deck 移到独立 workspace。
 
 编辑器会在浏览器中打开。使用 `Ctrl`/`Cmd` + 点击 deck 元素来引用它们，写一段自然语言评论，然后发送回 OpenCode。Revela 会把 deck 文件、slide 上下文、选中元素 metadata 和你的评论整理成结构化 edit prompt。
 
-对应的 LLM tool：`revela-edit`，参数为 `{ "target": "decks/my-deck.html" }`。因此当你说“我要编辑 @decks/my-deck.html”时，agent 也可以主动打开同一个编辑器。
+对应的 LLM tool：`revela-edit`，不需要 target。因此当你说“我要编辑这个 deck”时，agent 也可以主动打开同一个编辑器。
 
 如果已有 HTML deck 缺少 `DECKS.json` 状态，`/revela edit` 会自动准备最小 deck state，让正常的 `decks/*.html` 写入门禁仍然生效，同时允许后续精准修改。
 

package/designs/starter/DESIGN.md

@@ -692,35 +692,139 @@ Small page number utility.
 <!-- @component:timeline-journey-horizontal:start -->
 #### Timeline Journey Horizontal (.timeline-journey-horizontal)
 
-Horizontal timeline for milestones.
+Horizontal milestone journey with a central axis line. Nodes sit on the axis; a dashed vertical stem leads to a tip dot, with date, title, and description text alongside. Alternate nodes above and below the axis for rhythm. Suitable for 4-8 milestones across a chronological arc, transformation story, roadmap, or multi-year programme recap.
 
 ```html
-<div class="timeline-journey-horizontal"><div class="timeline-node"><span>01</span><h4>Milestone</h4><p>Short note.</p></div></div>
+<div class="timeline-journey-horizontal" data-preview-component="timeline-journey-horizontal">
+  <div class="tjh-axis"></div>
+
+  <!-- Up node: label, tip-dot, stem, axis-dot. Content grows upward. -->
+  <div class="tjh-item tjh-item--up" style="left:12%; --tjh-item-color:var(--accent-primary);">
+    <div class="tjh-label">
+      <span class="tjh-date">Q1</span>
+      <span class="tjh-title">Baseline</span>
+      <span class="tjh-text">Map current signals and establish the reference state.</span>
+    </div>
+    <div class="tjh-tip-dot"></div>
+    <div class="tjh-stem"></div>
+    <div class="tjh-axis-dot"></div>
+  </div>
+
+  <!-- Down node: axis-dot, stem, tip-dot, label. Content grows downward. -->
+  <div class="tjh-item tjh-item--down" style="left:34%; --tjh-item-color:var(--accent-secondary);">
+    <div class="tjh-axis-dot"></div>
+    <div class="tjh-stem"></div>
+    <div class="tjh-tip-dot"></div>
+    <div class="tjh-label">
+      <span class="tjh-date">Q2</span>
+      <span class="tjh-title">Prototype</span>
+      <span class="tjh-text">Convert the plan into visible experiments.</span>
+    </div>
+  </div>
+</div>
 ```
 
 ```css
-.timeline-journey-horizontal { position: relative; display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 28px; }
-.timeline-journey-horizontal::before { content: ''; position: absolute; left: 0; right: 0; top: 18px; height: 1px; background: var(--line-strong); }
-.timeline-node { position: relative; z-index: 1; display: flex; flex-direction: column; gap: 12px; padding-right: 18px; }
-.timeline-node span { width: 36px; height: 36px; display: flex; align-items: center; justify-content: center; background: var(--surface); border: 1px solid var(--line-strong); color: var(--accent-primary); font-size: 12px; font-weight: 800; }
-```
+.timeline-journey-horizontal {
+  --tjh-node: 12px;
+  --tjh-stem-h: 76px;
+  --tjh-col: calc(100% / 6);
+  position: relative;
+  width: 100%;
+  height: 340px;
+}
+.tjh-axis { position: absolute; top: 50%; left: 0; right: 0; height: 1px; background: var(--line-strong); transform: translateY(-50%); }
+.tjh-item { position: absolute; display: flex; flex-direction: column; align-items: center; width: var(--tjh-col); transform: translateX(-50%); }
+.tjh-item--up { bottom: 50%; }
+.tjh-item--down { top: 50%; }
+.tjh-axis-dot, .tjh-tip-dot { width: var(--tjh-node); height: var(--tjh-node); border-radius: 999px; background: var(--tjh-item-color, var(--accent-primary)); flex-shrink: 0; }
+.tjh-item--up .tjh-axis-dot { margin-bottom: calc(-1 * var(--tjh-node) / 2); }
+.tjh-item--down .tjh-axis-dot { margin-top: calc(-1 * var(--tjh-node) / 2); }
+.tjh-stem { width: 1px; height: var(--tjh-stem-h); background-image: repeating-linear-gradient(to bottom, var(--line-strong) 0 4px, transparent 4px 8px); flex-shrink: 0; }
+.tjh-label { display: flex; flex-direction: column; gap: 4px; width: 100%; padding: 0 6px; }
+.tjh-item--up .tjh-label { margin-bottom: 8px; }
+.tjh-item--down .tjh-label { margin-top: 8px; }
+.tjh-date { font-size: var(--font-size-meta); font-weight: 800; letter-spacing: 0.14em; text-transform: uppercase; color: var(--tjh-item-color, var(--accent-primary)); line-height: 1.3; white-space: nowrap; }
+.tjh-title { font-size: 18px; font-weight: 700; line-height: 1.15; color: var(--text-primary); }
+.tjh-text { font-size: 15px; line-height: 1.45; color: var(--text-secondary); }
+```
+
+Rules:
+- Position nodes with `left: X%` inline style. For N nodes, space them at `(100 / (N + 1)) * k %` or manually distribute to show real time gaps.
+- Each node may set `--tjh-item-color` inline. Prefer existing neutral theme tokens such as `--accent-primary`, `--accent-secondary`, `--accent-danger`, or a derived local accent.
+- Up node DOM order is `label -> tip-dot -> stem -> axis-dot`; down node DOM order is `axis-dot -> stem -> tip-dot -> label`.
+- Keep `.tjh-text` short, usually 1-2 lines. The column width limits wrapping naturally.
+- Alternate up/down nodes for visual rhythm unless clustering intentionally communicates a phase.
+- Adjust `--tjh-col`, `--tjh-stem-h`, and component `height` for fewer or longer milestones.
 <!-- @component:timeline-journey-horizontal:end -->
 
 <!-- @component:timeline-journey-vertical:start -->
 #### Timeline Journey Vertical (.timeline-journey-vertical)
 
-Vertical timeline for narrow slots.
+Vertical milestone journey with a central axis line. Nodes sit on the axis; a horizontal dashed stem leads to a tip dot, with date, title, and description text alongside. Alternate nodes left and right of the axis for rhythm. Suitable for 3-8 milestones in a full-height slot.
 
 ```html
-<div class="timeline-journey-vertical"><div class="timeline-v-node"><span>01</span><div><h4>Milestone</h4><p>Short note.</p></div></div></div>
+<div class="timeline-journey-vertical" data-preview-component="timeline-journey-vertical">
+  <div class="tjv-axis"></div>
+
+  <!-- Left node: DOM order stays axis-dot, stem, tip-dot, label. CSS reverses the row. -->
+  <div class="tjv-item tjv-item--left" style="top:18%; --tjv-item-color:var(--accent-primary);">
+    <div class="tjv-axis-dot"></div>
+    <div class="tjv-stem"></div>
+    <div class="tjv-tip-dot"></div>
+    <div class="tjv-label">
+      <span class="tjv-date">Discover</span>
+      <span class="tjv-title">Signal scan</span>
+      <span class="tjv-text">Collect inputs and identify the high-confidence path.</span>
+    </div>
+  </div>
+
+  <!-- Right node: same DOM order, standard row direction. -->
+  <div class="tjv-item tjv-item--right" style="top:42%; --tjv-item-color:var(--accent-secondary);">
+    <div class="tjv-axis-dot"></div>
+    <div class="tjv-stem"></div>
+    <div class="tjv-tip-dot"></div>
+    <div class="tjv-label">
+      <span class="tjv-date">Build</span>
+      <span class="tjv-title">Visible proof</span>
+      <span class="tjv-text">Create the first proof points and refine the operating model.</span>
+    </div>
+  </div>
+</div>
 ```
 
 ```css
-.timeline-journey-vertical { display: flex; flex-direction: column; gap: 0; }
-.timeline-v-node { display: grid; grid-template-columns: 42px 1fr; gap: 18px; padding-bottom: 26px; position: relative; }
-.timeline-v-node::before { content: ''; position: absolute; left: 17px; top: 42px; bottom: 4px; width: 1px; background: var(--line-strong); }
-.timeline-v-node span { width: 36px; height: 36px; display: flex; align-items: center; justify-content: center; background: var(--surface); border: 1px solid var(--line-strong); color: var(--accent-primary); font-size: 12px; font-weight: 800; }
-```
+.timeline-journey-vertical {
+  --tjv-node: 12px;
+  --tjv-stem-w: 76px;
+  position: relative;
+  width: 100%;
+  height: 100%;
+}
+.tjv-axis { position: absolute; left: 50%; top: 0; bottom: 0; width: 1px; background: var(--line-strong); transform: translateX(-50%); }
+.tjv-item { position: absolute; display: flex; align-items: center; height: 78px; transform: translateY(-50%); }
+.tjv-item--left { right: 50%; flex-direction: row-reverse; }
+.tjv-item--right { left: 50%; flex-direction: row; }
+.tjv-axis-dot { width: var(--tjv-node); height: var(--tjv-node); border-radius: 999px; background: var(--tjv-item-color, var(--accent-primary)); flex-shrink: 0; position: relative; z-index: 1; }
+.tjv-item--left .tjv-axis-dot { margin-right: calc(-1 * var(--tjv-node) / 2); }
+.tjv-item--right .tjv-axis-dot { margin-left: calc(-1 * var(--tjv-node) / 2); }
+.tjv-tip-dot { width: 8px; height: 8px; border-radius: 999px; background: var(--tjv-item-color, var(--accent-primary)); flex-shrink: 0; }
+.tjv-stem { width: var(--tjv-stem-w); height: 1px; background-image: repeating-linear-gradient(to right, var(--line-strong) 0 4px, transparent 4px 8px); flex-shrink: 0; }
+.tjv-label { display: flex; flex-direction: column; gap: 4px; }
+.tjv-item--left .tjv-label { text-align: right; align-items: flex-end; padding-right: 18px; max-width: 440px; }
+.tjv-item--right .tjv-label { text-align: left; align-items: flex-start; padding-left: 18px; max-width: 440px; }
+.tjv-date { font-size: var(--font-size-meta); font-weight: 800; letter-spacing: 0.14em; text-transform: uppercase; color: var(--tjv-item-color, var(--accent-primary)); line-height: 1.3; white-space: nowrap; }
+.tjv-title { font-size: 18px; font-weight: 700; line-height: 1.15; color: var(--text-primary); }
+.tjv-text { font-size: 15px; line-height: 1.45; color: var(--text-secondary); max-width: 360px; }
+```
+
+Rules:
+- DOM order is identical for left and right nodes: `axis-dot -> stem -> tip-dot -> label`. Direction is controlled by CSS (`row-reverse` for left, `row` for right).
+- Position each node with `top: Y%` inline style. For N nodes, distribute evenly with `(100 / (N + 1)) * k %` or manually to reflect time proportions.
+- Each node may set `--tjv-item-color` inline. Prefer current theme tokens rather than hard-coded project colors.
+- Alternate left and right nodes for rhythm. Avoid consecutive same-side nodes unless the story needs clustering.
+- The parent container must have a defined height. Use `height: 100%` inside a layout slot, or set an explicit height when standalone.
+- Keep `.tjv-text` to 2-3 lines. Longer labels shift the perceived center away from the axis dot.
 <!-- @component:timeline-journey-vertical:end -->
 
 <!-- @component:svg-motif:start -->

package/designs/starter/preview.html

@@ -140,13 +140,37 @@
     .brand-watermark strong { font-weight: 800; color: var(--text-secondary); }
     .page-number { position: absolute; right: 34px; bottom: 26px; z-index: 10; font-size: 12px; letter-spacing: 0.14em; color: var(--text-muted); }
     .page-number--light { color: rgba(248,250,252,0.72); }
-    .timeline-journey-horizontal { position: relative; display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 28px; }
-    .timeline-journey-horizontal::before { content: ''; position: absolute; left: 0; right: 0; top: 18px; height: 1px; background: var(--line-strong); }
-    .timeline-node { position: relative; z-index: 1; display: flex; flex-direction: column; gap: 12px; padding-right: 18px; }
-    .timeline-node span, .timeline-v-node span { width: 36px; height: 36px; display: flex; align-items: center; justify-content: center; background: var(--surface); border: 1px solid var(--line-strong); color: var(--accent-primary); font-size: 12px; font-weight: 800; }
-    .timeline-journey-vertical { display: flex; flex-direction: column; gap: 0; }
-    .timeline-v-node { display: grid; grid-template-columns: 42px 1fr; gap: 18px; padding-bottom: 26px; position: relative; }
-    .timeline-v-node::before { content: ''; position: absolute; left: 17px; top: 42px; bottom: 4px; width: 1px; background: var(--line-strong); }
+    .timeline-journey-horizontal { --tjh-node: 12px; --tjh-stem-h: 62px; --tjh-col: 180px; position: relative; width: 100%; height: 245px; }
+    .tjh-axis { position: absolute; top: 50%; left: 0; right: 0; height: 1px; background: var(--line-strong); transform: translateY(-50%); }
+    .tjh-item { position: absolute; display: flex; flex-direction: column; align-items: center; width: var(--tjh-col); transform: translateX(-50%); }
+    .tjh-item--up { bottom: 50%; }
+    .tjh-item--down { top: 50%; }
+    .tjh-axis-dot, .tjh-tip-dot { width: var(--tjh-node); height: var(--tjh-node); border-radius: 999px; background: var(--tjh-item-color, var(--accent-primary)); flex-shrink: 0; }
+    .tjh-item--up .tjh-axis-dot { margin-bottom: calc(-1 * var(--tjh-node) / 2); }
+    .tjh-item--down .tjh-axis-dot { margin-top: calc(-1 * var(--tjh-node) / 2); }
+    .tjh-stem { width: 1px; height: var(--tjh-stem-h); background-image: repeating-linear-gradient(to bottom, var(--line-strong) 0 4px, transparent 4px 8px); flex-shrink: 0; }
+    .tjh-label { display: flex; flex-direction: column; gap: 3px; width: 100%; padding: 0 6px; }
+    .tjh-item--up .tjh-label { margin-bottom: 8px; }
+    .tjh-item--down .tjh-label { margin-top: 8px; }
+    .tjh-date { font-size: 11px; font-weight: 800; letter-spacing: 0.14em; text-transform: uppercase; color: var(--tjh-item-color, var(--accent-primary)); line-height: 1.3; white-space: nowrap; }
+    .tjh-title { font-size: 17px; font-weight: 700; line-height: 1.15; color: var(--text-primary); }
+    .tjh-text { font-size: 13px; line-height: 1.4; color: var(--text-secondary); }
+    .timeline-journey-vertical { --tjv-node: 12px; --tjv-stem-w: 46px; position: relative; width: 100%; height: 100%; min-height: 260px; }
+    .tjv-axis { position: absolute; left: 50%; top: 0; bottom: 0; width: 1px; background: var(--line-strong); transform: translateX(-50%); }
+    .tjv-item { position: absolute; display: flex; align-items: center; height: 72px; transform: translateY(-50%); }
+    .tjv-item--left { right: 50%; flex-direction: row-reverse; }
+    .tjv-item--right { left: 50%; flex-direction: row; }
+    .tjv-axis-dot { width: var(--tjv-node); height: var(--tjv-node); border-radius: 999px; background: var(--tjv-item-color, var(--accent-primary)); flex-shrink: 0; position: relative; z-index: 1; }
+    .tjv-item--left .tjv-axis-dot { margin-right: calc(-1 * var(--tjv-node) / 2); }
+    .tjv-item--right .tjv-axis-dot { margin-left: calc(-1 * var(--tjv-node) / 2); }
+    .tjv-tip-dot { width: 8px; height: 8px; border-radius: 999px; background: var(--tjv-item-color, var(--accent-primary)); flex-shrink: 0; }
+    .tjv-stem { width: var(--tjv-stem-w); height: 1px; background-image: repeating-linear-gradient(to right, var(--line-strong) 0 4px, transparent 4px 8px); flex-shrink: 0; }
+    .tjv-label { display: flex; flex-direction: column; gap: 3px; }
+    .tjv-item--left .tjv-label { text-align: right; align-items: flex-end; padding-right: 14px; max-width: 220px; }
+    .tjv-item--right .tjv-label { text-align: left; align-items: flex-start; padding-left: 14px; max-width: 220px; }
+    .tjv-date { font-size: 11px; font-weight: 800; letter-spacing: 0.14em; text-transform: uppercase; color: var(--tjv-item-color, var(--accent-primary)); line-height: 1.3; white-space: nowrap; }
+    .tjv-title { font-size: 17px; font-weight: 700; line-height: 1.15; color: var(--text-primary); }
+    .tjv-text { font-size: 13px; line-height: 1.4; color: var(--text-secondary); max-width: 210px; }
     .svg-motif { position: relative; pointer-events: none; color: var(--text-primary); }
     .svg-motif svg { display: block; width: 100%; height: 100%; overflow: visible; }
     .svg-motif--bottom { position: absolute; left: 0; right: 0; bottom: 0; height: 30%; }
@@ -156,7 +180,7 @@
   </style>
 </head>
 <body>
-  <section class="slide" slide-qa="false" data-index="0">
+  <section class="slide" slide-qa="false" data-index="0" data-slide-role="cover">
     <div class="slide-canvas">
       <div class="page" style="padding:0;">
         <div class="image-title image-title--left">
@@ -229,10 +253,22 @@
     <div class="slide-canvas">
       <div class="page" style="padding:0;">
         <div class="stacked-grid">
-          <div class="stacked-top text-panel reveal" style="padding:48px 56px 30px;"><div class="text-panel-body"><p class="eyebrow">Data and process</p><h2>Evidence components stay structural</h2><p>Charts, tables, and flows inherit the active theme while keeping predictable geometry.</p></div></div>
-          <div class="stacked-bottom" style="display:grid;grid-template-columns:1.2fr .8fr;gap:40px;padding:0 56px 56px;">
+          <div class="stacked-top text-panel reveal" style="padding:42px 56px 20px;"><div class="text-panel-body"><p class="eyebrow">Data and process</p><h2>Evidence components stay structural</h2><p>Charts, tables, and journey timelines inherit the active theme while keeping predictable geometry.</p></div></div>
+          <div class="stacked-bottom" style="display:grid;grid-template-columns:1fr 1fr;grid-template-rows:minmax(0,1fr) 250px;gap:26px;padding:0 56px 56px;">
             <div class="echart-panel reveal"><div class="echart-panel-header"><p class="eyebrow">Example chart</p><h3>Signal distribution</h3><p class="chart-subtitle">Neutral chart defaults with restrained labels.</p></div><div class="echart-container" id="starter-chart"></div><p class="chart-caption">Source: demo data</p></div>
-            <div class="data-table-wrap reveal"><div class="data-table-label">Component matrix</div><table class="data-table"><thead><tr><th>Primitive</th><th>Count</th><th>Role</th></tr></thead><tbody><tr><td>Layouts</td><td>6</td><td>Structure</td></tr><tr><td>Components</td><td>16</td><td>Coverage</td></tr><tr><td>SVG motif</td><td>1</td><td>Vector</td></tr></tbody></table><p class="table-caption">Starter remains visually neutral.</p></div>
+            <div class="timeline-journey-vertical reveal" data-preview-component="timeline-journey-vertical">
+              <div class="tjv-axis"></div>
+              <div class="tjv-item tjv-item--left" style="top:18%; --tjv-item-color:var(--accent-primary);"><div class="tjv-axis-dot"></div><div class="tjv-stem"></div><div class="tjv-tip-dot"></div><div class="tjv-label"><span class="tjv-date">Discover</span><span class="tjv-title">Signal scan</span><span class="tjv-text">Map inputs and identify the base pattern.</span></div></div>
+              <div class="tjv-item tjv-item--right" style="top:50%; --tjv-item-color:var(--accent-secondary);"><div class="tjv-axis-dot"></div><div class="tjv-stem"></div><div class="tjv-tip-dot"></div><div class="tjv-label"><span class="tjv-date">Build</span><span class="tjv-title">Theme draft</span><span class="tjv-text">Apply visual schema without changing structure.</span></div></div>
+              <div class="tjv-item tjv-item--left" style="top:82%; --tjv-item-color:var(--accent-danger);"><div class="tjv-axis-dot"></div><div class="tjv-stem"></div><div class="tjv-tip-dot"></div><div class="tjv-label"><span class="tjv-date">Verify</span><span class="tjv-title">Preview pass</span><span class="tjv-text">Check roles, components, and slide geometry.</span></div></div>
+            </div>
+            <div class="timeline-journey-horizontal reveal" data-preview-component="timeline-journey-horizontal" style="grid-column:1 / -1;">
+              <div class="tjh-axis"></div>
+              <div class="tjh-item tjh-item--up" style="left:14%; --tjh-item-color:var(--accent-primary);"><div class="tjh-label"><span class="tjh-date">01</span><span class="tjh-title">Brief</span><span class="tjh-text">Clarify source style.</span></div><div class="tjh-tip-dot"></div><div class="tjh-stem"></div><div class="tjh-axis-dot"></div></div>
+              <div class="tjh-item tjh-item--down" style="left:38%; --tjh-item-color:var(--accent-secondary);"><div class="tjh-axis-dot"></div><div class="tjh-stem"></div><div class="tjh-tip-dot"></div><div class="tjh-label"><span class="tjh-date">02</span><span class="tjh-title">Tokens</span><span class="tjh-text">Set color and type.</span></div></div>
+              <div class="tjh-item tjh-item--up" style="left:62%; --tjh-item-color:var(--accent-danger);"><div class="tjh-label"><span class="tjh-date">03</span><span class="tjh-title">Modules</span><span class="tjh-text">Skin components.</span></div><div class="tjh-tip-dot"></div><div class="tjh-stem"></div><div class="tjh-axis-dot"></div></div>
+              <div class="tjh-item tjh-item--down" style="left:86%; --tjh-item-color:var(--text-muted);"><div class="tjh-axis-dot"></div><div class="tjh-stem"></div><div class="tjh-tip-dot"></div><div class="tjh-label"><span class="tjh-date">04</span><span class="tjh-title">Validate</span><span class="tjh-text">Inspect preview.</span></div></div>
+            </div>
           </div>
         </div>
         <div class="page-number">05</div>
@@ -240,7 +276,7 @@
     </div>
   </section>
 
-  <section class="slide" slide-qa="false" data-index="5">
+  <section class="slide" slide-qa="false" data-index="5" data-slide-role="closing">
     <div class="slide-canvas">
       <div class="page">
         <div class="svg-motif svg-motif--corner" aria-hidden="true"><svg viewBox="0 0 600 360"><rect x="80" y="190" width="360" height="34" fill="#dbeafe"/><circle cx="190" cy="150" r="82" fill="#3b82f6" opacity=".82"/><path d="M286 230 C330 120 474 122 516 226 C458 274 348 276 286 230 Z" fill="#64748b" opacity=".68"/><path d="M112 70 l22 -22 l22 22 l-22 22 Z" fill="none" stroke="#17191c" stroke-width="8"/><path d="M470 72 C508 38 548 46 566 88" fill="none" stroke="#17191c" stroke-width="9" stroke-linecap="round"/></svg></div>

package/lib/agents/research-prompt.ts

@@ -29,7 +29,7 @@ Given a research brief specifying your topic and axis, you will:
 2. Use \`DECKS.json\` through \`revela-decks\` as the workspace material index when it exists
 3. Run a lightweight workspace freshness check when needed
 4. Search the web for current data, reports, and case studies when the brief requires it
-5. Write all findings to ONE structured file: \`researches/{topic-slug}/{axis-name}.md\`
+5. Write all findings to ONE structured file: \`researches/{topic-key}/{axis-name}.md\`
 6. Return a brief summary of what you found
 
 ---
@@ -37,7 +37,7 @@ Given a research brief specifying your topic and axis, you will:
 ## Step 1 — Research brief and workspace memory
 
 Start from the research brief supplied by the primary agent. It should include:
-- shared topic slug
+- shared topic key
 - your axis filename
 - the specific question for this axis
 - time period, geography, and evidence standard
@@ -100,7 +100,7 @@ Search strategy:
 
 Use **\`revela-research-save\`** to write ONE file with all your findings.
 
-- \`topic\`: kebab-case slug shared across all agents for this presentation
+- \`topic\`: kebab-case topic key shared across all agents for this presentation
 - \`filename\`: your axis name (e.g. \`market-data\`, \`catl-profile\`, \`tech-trends\`)
 - \`content\`: structured findings using the four sections below
 - \`sources\`: list of all URLs and filenames used
@@ -140,7 +140,7 @@ Content rules:
 After writing the file, return this summary (do NOT include the raw data):
 
 \`\`\`
-Research complete: {axis-name} → researches/{topic-slug}/{axis-name}.md
+Research complete: {axis-name} → researches/{topic-key}/{axis-name}.md
 
 Key findings (3–5, most argument-worthy only):
 - {1–2 sentence highlight with source}

package/lib/commands/designs-new.ts

@@ -79,6 +79,12 @@ const VISUAL_QUALITY_RULES = `Visual extraction and CSS quality rules:
 - For SVG motifs: set a viewBox, keep all eyes/mouths/decorations inside that coordinate system, and document intended placement/scale in the component notes.
 - Before saving, review the preview for text overlap, scale drift, lost anchoring, overflow, and whether the preview preserves the reference composition.`
 
+const PREVIEW_REQUIREMENTS = `Preview requirements:
+- \`preview.html\` must include a cover slide and a closing slide. Mark their \`<section class="slide">\` elements with \`data-slide-role="cover"\` and \`data-slide-role="closing"\`.
+- \`preview.html\` must showcase every \`@component:*\` defined in \`DESIGN.md\`. Mark each showcased component with \`data-preview-component="<component-name>"\`.
+- Do not save with \`revela-designs-author\` until every component has a corresponding preview marker. If a component is decorative or abstract, include a visible labeled sample state.
+- When the design supports chart styling, \`preview.html\` should include a 3x3 ECharts gallery with at least 9 chart examples. This is a preview quality requirement, not a validation blocker.`
+
 export function buildDesignsNewPrompt({ name, base }: DesignsNewArgs): string {
   return `You are creating a new Revela visual design package.
 
@@ -107,6 +113,8 @@ You must replace unless the user explicitly requests otherwise:
 
 ${VISUAL_QUALITY_RULES}
 
+${PREVIEW_REQUIREMENTS}
+
 Workflow:
 1. Do not generate or save files immediately.
 2. Interview the user first. Ask for visual references such as screenshots/images, webpage URLs, text descriptions, brands, or decks they like.
@@ -126,6 +134,8 @@ Hard requirements:
 - \`DESIGN.md\` must include at least \`@design:foundation\`, \`@design:rules\`, one layout, and one component.
 - \`preview.html\` must be self-contained and directly openable in a browser.
 - Every preview slide must include \`slide-qa="true"\` or \`slide-qa="false"\`.
+- \`preview.html\` must include \`data-slide-role="cover"\` and \`data-slide-role="closing"\` on slide sections.
+- \`preview.html\` must showcase every \`@component:*\` with \`data-preview-component="<component-name>"\` before saving.
 - Do not save anything until the user confirms the brief.
 
 Start now by interviewing the user. Keep the first question concise.`
@@ -144,6 +154,8 @@ Goal:
 
 ${VISUAL_QUALITY_RULES}
 
+${PREVIEW_REQUIREMENTS}
+
 Workflow:
 1. Do not save files immediately.
 2. Ask the user what they want to change. Accept text descriptions, screenshots/images, webpage URLs, or specific complaints about the current preview.
@@ -161,6 +173,8 @@ Hard requirements:
 - Preserve at least \`@design:foundation\`, \`@design:rules\`, one layout, and one component.
 - \`preview.html\` must be self-contained and directly openable in a browser.
 - Every preview slide must include \`slide-qa="true"\` or \`slide-qa="false"\`.
+- \`preview.html\` must include \`data-slide-role="cover"\` and \`data-slide-role="closing"\` on slide sections.
+- \`preview.html\` must showcase every \`@component:*\` with \`data-preview-component="<component-name>"\` before saving.
 - Do not save anything until the user confirms the edit brief.
 
 Start now by asking what the user wants to change in \`${name}\`.`

package/lib/commands/edit.ts

@@ -1,22 +1,19 @@
 import { openEditableDeck } from "../edit/open"
 
 export async function handleEdit(
-  input: string,
   options: { client: any; sessionID: string; workspaceRoot: string },
   send: (text: string) => Promise<void>,
 ): Promise<void> {
-  const target = input.trim()
-
   try {
-    const result = openEditableDeck(target, {
+    const result = openEditableDeck("", {
       client: options.client,
       sessionID: options.sessionID,
       workspaceRoot: options.workspaceRoot,
     })
 
     await send(
-      `Opened visual editor for deck \`${result.deck.slug}\`.\n` +
-      `File: \`${result.deck.file}\` (${result.source})\n` +
+      `Opened visual editor for the only deck in \`decks/\`.\n` +
+      `File: \`${result.deck.file}\`\n` +
       `${result.stateNote}\n` +
       `URL: ${result.url}\n\n` +
       `Use Ctrl/Cmd + click in the browser to reference elements, write a comment, then send comments. Revela mode has been enabled for the edit prompt.`

package/lib/commands/help.ts

@@ -27,8 +27,8 @@ export async function handleHelp(
     `\`/revela enable\`              — enable slide generation mode\n` +
     `\`/revela disable\`             — disable slide generation mode\n` +
     `\`/revela init\`                — initialize or refresh workspace DECKS.json\n` +
-    `\`/revela review [slug]\`       — review active deck readiness before writing HTML\n` +
-    `\`/revela edit [target]\`       — open visual editor for active deck or a specific target\n` +
+    `\`/revela review\`              — review current deck readiness before writing HTML\n` +
+    `\`/revela edit\`                — open visual editor for the only deck in decks/\n` +
     `\`/revela remember <text>\`     — save an explicit preference to DECKS.json\n` +
     `\`/revela designs\`             — list installed designs\n` +
     `\`/revela designs <name>\`      — activate a design\n` +