@cyber-dash-tech/revela 0.17.2 → 0.17.4

package/README.md

@@ -2,11 +2,15 @@
 
 **English** | [中文](README.zh-CN.md)
 
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-546%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="560" />
 </p>
 
-Revela is an [OpenCode](https://opencode.ai) plugin for turning workspace sources, research, evidence, and user intent into trusted narrative artifacts. Its first render target is HTML slide decks.
+Revela is an [OpenCode](https://opencode.ai) plugin that turns local sources and research into a traceable narrative graph, then renders that graph into briefs and presentation decks.
+
+The narrative graph records the core elements needed to generate a brief or deck: audience, decision, claims, evidence, sources, risks, objections, and open gaps.
 
 ## Install
 
@@ -30,17 +34,17 @@ Revela includes built-in deck designs:
 ### [summit](designs/summit/preview.html)
 
 <p align="center">
-  <img src="assets/img/summit-01.png" alt="Summit design preview 1" width="32%" />
-  <img src="assets/img/summit-02.png" alt="Summit design preview 2" width="32%" />
-  <img src="assets/img/summit-03.png" alt="Summit design preview 3" width="32%" />
+  <img src="assets/img/summit-01.jpg" alt="Summit design preview 1" width="32%" />
+  <img src="assets/img/summit-02.jpg" alt="Summit design preview 2" width="32%" />
+  <img src="assets/img/summit-03.jpg" alt="Summit design preview 3" width="32%" />
 </p>
 
 ### [monet](designs/monet/preview.html)
 
 <p align="center">
-  <img src="assets/img/monet-01.png" alt="Monet design preview 1" width="32%" />
-  <img src="assets/img/monet-02.png" alt="Monet design preview 2" width="32%" />
-  <img src="assets/img/monet-03.png" alt="Monet design preview 3" width="32%" />
+  <img src="assets/img/monet-01.jpg" alt="Monet design preview 1" width="32%" />
+  <img src="assets/img/monet-02.jpg" alt="Monet design preview 2" width="32%" />
+  <img src="assets/img/monet-03.jpg" alt="Monet design preview 3" width="32%" />
 </p>
 
 `starter` is the clean default presentation style.

package/README.zh-CN.md

@@ -2,11 +2,15 @@
 
 [English](README.md) | **中文**
 
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-546%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="560" />
 </p>
 
-Revela 是一个 [OpenCode](https://opencode.ai) 插件，用来把工作区来源材料、调研、证据和用户意图转成可信的叙事型沟通 artifact。它的第一个 render target 是 HTML slide deck。
+Revela 是一个 [OpenCode](https://opencode.ai) 插件，用来把本地材料和调研结果转成可追踪的叙事图谱，再基于这个图谱生成 brief 和 presentation deck。
+
+叙事图谱用 graph 方式记录生成 brief 或 deck 所需的关键要素：受众、决策目标、论点、论据、资料来源、风险、潜在质疑和待补齐的信息。
 
 ## 安装
 
@@ -30,17 +34,17 @@ Revela 内置多个 deck design：
 ### [summit](designs/summit/preview.html)
 
 <p align="center">
-  <img src="assets/img/summit-01.png" alt="Summit design preview 1" width="32%" />
-  <img src="assets/img/summit-02.png" alt="Summit design preview 2" width="32%" />
-  <img src="assets/img/summit-03.png" alt="Summit design preview 3" width="32%" />
+  <img src="assets/img/summit-01.jpg" alt="Summit design preview 1" width="32%" />
+  <img src="assets/img/summit-02.jpg" alt="Summit design preview 2" width="32%" />
+  <img src="assets/img/summit-03.jpg" alt="Summit design preview 3" width="32%" />
 </p>
 
 ### [monet](designs/monet/preview.html)
 
 <p align="center">
-  <img src="assets/img/monet-01.png" alt="Monet design preview 1" width="32%" />
-  <img src="assets/img/monet-02.png" alt="Monet design preview 2" width="32%" />
-  <img src="assets/img/monet-03.png" alt="Monet design preview 3" width="32%" />
+  <img src="assets/img/monet-01.jpg" alt="Monet design preview 1" width="32%" />
+  <img src="assets/img/monet-02.jpg" alt="Monet design preview 2" width="32%" />
+  <img src="assets/img/monet-03.jpg" alt="Monet design preview 3" width="32%" />
 </p>
 
 `starter` 是简洁默认演示风格。

package/designs/monet/DESIGN.md

@@ -480,6 +480,7 @@ These rules are mandatory for Monet.
 - **Sparse slides depend on image weight.** If content is light, the photo or page framing must hold the composition.
 - **No glass cards, neon KPI styling, or startup-product chrome.** Monet is editorial and print-adjacent.
 - **Visual hierarchy is strict:** eyebrow -> heading -> body -> caption.
+- **Icon system is Lucide.** For ordinary UI, semantic, status, category, process, and navigation icons, use Lucide (`data-lucide`). Do not hand-write inline SVG for icons. SVG is allowed only for intentional decorative motifs, illustrations, or design-specific artwork. If any `data-lucide` icon is present, load Lucide via CDN and call `lucide.createIcons()` after `SlidePresentation`.
 
 ### Common Mistakes
 
@@ -823,6 +824,31 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 Use these components when a page needs repeatable editorial modules inside a larger layout. Components define the block itself, not the page grid around it.
 
+<!-- @component:box:start -->
+#### Box
+
+Card/group primitive for one idea, case, evidence item, metric, objection, risk, or action. Put `text-panel`, `media`, `echart-panel`, `data-table`, `stat-card`, or `quote` inside a box when they support the same idea.
+
+```html
+<div class="box">
+  <div class="text-panel text-panel--plain">
+    <div class="text-panel-body">
+      <p class="eyebrow">Evidence</p>
+      <h3>One clear idea</h3>
+      <p>Short supporting copy or source-bound explanation.</p>
+    </div>
+  </div>
+</div>
+```
+
+```css
+.box { height: 100%; min-height: 0; padding: 28px; border: 1px solid var(--line); background: rgba(255,255,255,0.46); display: flex; flex-direction: column; gap: 18px; overflow: hidden; }
+.box--quiet { background: transparent; }
+.box--mist { background: rgba(240,244,247,0.72); }
+.box--dark { background: #0d1a24; --text-primary:#f0f4f7; --text-secondary:rgba(240,244,247,0.72); --text-muted:rgba(240,244,247,0.55); --line:rgba(240,244,247,0.16); }
+```
+<!-- @component:box:end -->
+
 
 
 <!-- @component:text-panel:start -->
@@ -937,6 +963,35 @@ Rules:
 - **`editorial-list` inside `--dark`.** Add `style="--accent-earth:rgba(240,244,247,0.72)"` on the `<ul>` wrapper so the bullet squares read against the dark background.
 <!-- @component:text-panel:end -->
 
+<!-- @component:media:start -->
+#### Media
+
+Normal image, screenshot, diagram, logo, or portrait component. Keep important visual information understandable. Do not use `media` for full-bleed covers/dividers/closings; use `hero` for those.
+
+```html
+<figure class="media">
+  <div class="media-frame">
+    <img src="https://images.unsplash.com/photo-1464822759023-fed622ff2c3b?q=80&w=1200&auto=format&fit=crop" alt="Atmospheric water garden detail">
+  </div>
+  <figcaption class="media-caption source-note">Optional source or field note</figcaption>
+</figure>
+```
+
+```css
+.media { height: 100%; min-height: 0; display: flex; flex-direction: column; gap: 12px; }
+.media-frame { position: relative; overflow: hidden; background: transparent; width: 100%; flex: 1; min-height: 0; }
+.media-frame img { width: 100%; height: 100%; display: block; object-fit: cover; }
+.media--contain .media-frame img { object-fit: contain; }
+.media-caption { margin-top: 0; font-size: 11px; line-height: 1.45; letter-spacing: 0.12em; text-transform: uppercase; color: var(--text-muted); }
+.media-caption.source, .media-caption.source-note { font-family: "Times New Roman", Times, serif; font-size: 11px; line-height: 1.35; letter-spacing: 0; text-transform: none; }
+```
+
+Rules:
+- Use `media` for screenshots, charts exported as images, diagrams, logos, portraits, and evidence visuals that must stay readable.
+- Use `object-fit: contain` through `media--contain` for screenshots, diagrams, and logos when cropping would remove information.
+- Put `media` inside a `box` when the visual and text support one semantic idea.
+<!-- @component:media:end -->
+
 <!-- @component:stat-card:start -->
 #### Stat Card
 
@@ -1010,7 +1065,7 @@ Rules:
 - **Do not over-explain.** If the description starts to become paragraph-length, switch to `text-panel` or pair the stat card with a narrative component in the neighboring slot.
 <!-- @component:stat-card:end -->
 
-<!-- @component:editorial-image-top:start -->
+<!-- @compat:editorial-image-top:start -->
 #### Editorial Image Top
 
 Image-first editorial module: image on top, text below. Best for highlight grids, product/material stories, and any module where the picture should lead before the reader enters the copy.
@@ -1094,9 +1149,9 @@ Rules:
 - **Image aspect ratio.** Aim for 16:9 or 3:2 crops for the image block. Portrait crops create tall image zones that push text down and unbalance the composition.
 - **Kicker icon size.** Keep Lucide SVG icons at 16–20px. Larger icons shift visual weight from the image to the label zone.
 - **`editorial-list` font-size.** Override to `font-size:13px;gap:10px` inline when used inside a very narrow copy zone — the base `editorial-list` is `17px/gap:14px`, which may be too large for tight columns.
-<!-- @component:editorial-image-top:end -->
+<!-- @compat:editorial-image-top:end -->
 
-<!-- @component:editorial-text-top:start -->
+<!-- @compat:editorial-text-top:start -->
 #### Editorial Text Top
 
 Text-first editorial module: text on top, image below. Best for narrative snippets, report-style explanations, or blocks where the image serves as evidence rather than the primary hook.
@@ -1160,9 +1215,9 @@ Rules:
 - **Same height/stretch rule as `editorial-image-top`.** Do not set fixed heights; let parent grid stretch control the column.
 - **When used as a center spine in `highlight-cols`,** this is the one component that may legitimately be taller than its neighbors. That density imbalance is intentional — do not try to equalize it with padding or extra content in the outer columns.
 - **`editorial-list` font-size.** Override to `font-size:13px;gap:10px` inline when used inside a very narrow copy zone — the base `editorial-list` is `17px/gap:14px`, which may be too large for tight columns.
-<!-- @component:editorial-text-top:end -->
+<!-- @compat:editorial-text-top:end -->
 
-<!-- @component:editorial-text-left:start -->
+<!-- @compat:editorial-text-left:start -->
 #### Editorial Text Left
 
 Horizontal editorial module: a full-width title band on top, with text on the left and a visual slot on the right below. Best for compact feature rows or any slot where a wide-but-short frame suits a side-by-side composition with a clear heading above.
@@ -1274,7 +1329,7 @@ Rules:
 - **`echart-container` in visual slot.** Set `width:100%;height:100%` on the container and call `echarts.init()` after `SlidePresentation` is instantiated. The `position:relative;overflow:hidden` on `.editorial-text-left-visual` contains the canvas correctly.
 - **`image-title` in visual slot.** The component is self-contained and fills `width:100%;height:100%` automatically. Use `image-title--right` modifier with a bottom-heavy overlay and right-biased blur mask for the most common editorial orientation.
 - **Dark background.** Override CSS variables on `.editorial-text-left` to cascade into both the copy and visual zones: `--text-primary`, `--text-secondary`, `--text-muted`, `--line`, `--line-strong` — all set to white-family values.
-<!-- @component:editorial-text-left:end -->
+<!-- @compat:editorial-text-left:end -->
 
 <!-- @component:echart-panel:start -->
 #### EChart Panel
@@ -1357,7 +1412,11 @@ Rules:
 - **Chart sizing for `narrative-hero-left-dark`.** The left 7.8fr column is wide. A donut or candlestick chart works best centered with some breathing room. Add `padding: 24px 32px` to `.echart-container` to prevent the chart from touching the column edges.
 <!-- @component:echart-panel:end -->
 
-<!-- @component:flow-horizontal:start -->
+<!-- @component:steps:start -->
+#### Steps
+
+Monet step and phase sequences use the flow-horizontal and flow-vertical implementations. Use `.flow-horizontal` for left-to-right process stages and `.flow-vertical` for top-to-bottom phases.
+
 #### Flow Horizontal
 
 Horizontal step or phase sequence. Use for process stages, numbered definitions, or parallel concepts that should be read left to right. Suitable for 2–5 items.
@@ -1487,9 +1546,9 @@ Rules:
 - **Step copy length directly affects column balance.** One step with a long paragraph will push its column taller than the others and break the horizontal rhythm. Trim all steps to roughly equal length (2–4 lines each).
 - **Number card design.** Each `.flow-number` uses two overlapping squares: a white `::before` base square (with border) and a blue `::after` top square (`--accent-earth`) rotated by `--fn-rot`. Set `data-n="01"` on the element (the `::after` reads it via `content: attr(data-n)`). Vary `--fn-rot` per item (e.g. `-9deg`, `7deg`, `-6deg`, `10deg`) for a hand-placed impression.
 - **Horizontal rule connector.** The `::before` pseudo-element on `.flow-horizontal` draws a full-width line at `top: 18px` (vertical centre of the 36px number box). `.flow-number` sits above it via `z-index: 1`; its `::before` background is set to `var(--bg-page)` to mask the line behind the white square. On dark backgrounds, override `.flow-horizontal .flow-number::before { background: <dark-bg-color>; }` and set `.flow-horizontal::before { background: rgba(240,244,247,0.15); }`.
-<!-- @component:flow-horizontal:end -->
+<!-- flow-horizontal implementation ends -->
 
-<!-- @component:flow-vertical:start -->
+<!-- flow-vertical implementation starts -->
 #### Flow Vertical
 
 Vertical step or timeline sequence. Use for chronological phases, execution stages, or progress narratives that should be read top to bottom. Suitable for 2–6 items.
@@ -1587,7 +1646,7 @@ Rules:
 - **Number card design (same as flow-horizontal).** Use `data-n="01"` and `style="--fn-rot:-8deg;"` on each `.flow-number`. Vary the rotation angle per item.
 - **Dark text overrides.** Flow-number `::before` border: `rgba(240,244,247,0.3)`; `::after` background: a darker accent or `rgba(41,128,175,0.85)`. h4: `color:#f0f4f7`; p: `color:rgba(240,244,247,0.7)`. Also override the connecting line: `background:rgba(240,244,247,0.2)`.
 - **Column height constraint.** `flow-vertical` expands naturally with content. In a two-column layout, ensure the opposing column (`text-panel` or `echart-panel`) has enough content to avoid a large height mismatch.
-<!-- @component:flow-vertical:end -->
+<!-- @component:steps:end -->
 
 <!-- @component:data-table:start -->
 #### Data Table
@@ -1781,7 +1840,11 @@ Rules:
 
 
 
-<!-- @component:image-title:start -->
+<!-- @component:hero:start -->
+#### Hero
+
+Monet hero slides use the image-title implementation for full-bleed cover, closing, atmospheric section divider, or strong visual statement slides.
+
 #### Image Title
 
 Self-contained full-canvas component: a dominant photograph with a directional blur layer, a gradient overlay, and a foreground text stack — all composited inside one element. Use for cover slides, closing slides, atmospheric section dividers, or any full-bleed spread where a single image should dominate the entire canvas.
@@ -1945,7 +2008,7 @@ Rules:
 - **`--right` closing variant.** Mirror the blur mask: use `mask-image:linear-gradient(to right, transparent 0%, transparent 20%, black 100%)`. The right side stays blurred (text zone); the left side of the image stays sharp.
 - **`--center` variant.** Use a radial or symmetric overlay: `radial-gradient(ellipse at center, rgba(5,5,5,0.72) 0%, rgba(5,5,5,0.20) 100%)` or a flat `rgba(5,5,5,0.55)`. Center blur mask: `mask-image:radial-gradient(ellipse at center, black 0%, transparent 80%)`.
 - **Subtitle width on `--right`.** `.image-title-subtitle` inherits `max-width:480px` which is set for left-aligned text. On `--right`, override to match the `.image-title-body` width: `style="max-width:520px;margin-left:auto;"`.
-<!-- @component:image-title:end -->
+<!-- @component:hero:end -->
 
 <!-- @component:toc:start -->
 #### TOC Panel
@@ -2368,7 +2431,11 @@ Omit `--light` only on slides with a white/light background.
 
 <!-- @component:page-number:end -->
 
-<!-- @component:timeline-journey-horizontal:start -->
+<!-- @component:roadmap-horizontal:start -->
+#### Roadmap Horizontal
+
+Monet horizontal roadmaps use the timeline-journey-horizontal implementation.
+
 #### Timeline Journey Horizontal
 
 A horizontal milestone timeline with a central axis line. Nodes sit on the axis; a dashed vertical stem leads to a tip node, 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, or multi-year programme recap.
@@ -2534,9 +2601,13 @@ Rules:
 - **Adjust stem length**: Change `--tjh-stem-h` to lengthen or shorten the dashed connector.
 - **Dark background overrides**: Set `--line-strong: rgba(240,244,247,0.25)` on `.tjh`, override `.tjh-axis { background }`, set `.tjh-title { color: #f0f4f7 }`, `.tjh-text { color: rgba(240,244,247,0.7) }`. The `--tjh-item-color` accent colours work on dark backgrounds without change.
 - **Fewer nodes**: For 4–5 nodes, widen `--tjh-col` by using a smaller denominator (e.g. `calc(100% / 5)`), and space `left` values accordingly.
-<!-- @component:timeline-journey-horizontal:end -->
+<!-- @component:roadmap-horizontal:end -->
+
+<!-- @component:roadmap-vertical:start -->
+#### Roadmap Vertical
+
+Monet vertical roadmaps use the timeline-journey-vertical implementation.
 
-<!-- @component:timeline-journey-vertical:start -->
 #### Timeline Journey Vertical
 
 A vertical milestone timeline 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 across a chronological arc, transformation story, or multi-year programme recap.
@@ -2731,6 +2802,6 @@ Rules:
 - **Dark background overrides**: set on the `.tjv` wrapper — `--line-strong: rgba(240,244,247,0.25)` (axis + stem), `.tjv-title { color: #f0f4f7 }`, `.tjv-text { color: rgba(240,244,247,0.7) }`. The `--tjv-item-color` accent colours work on dark backgrounds without change.
 - **Fewer nodes (3–4)**: increase spacing — use `top` values like `15%, 35%, 55%, 75%` to prevent the timeline from clustering at the top.
 - **More nodes (6–8)**: keep `.tjv-text` to 1-2 lines and increase vertical spacing between nodes if needed. Treat `17px` as the default body size; only use a smaller local override in exceptional dense layouts.
-<!-- @component:timeline-journey-vertical:end -->
+<!-- @component:roadmap-vertical:end -->
 
 <!-- @design:components:end -->

package/designs/starter/DESIGN.md

@@ -233,6 +233,7 @@ new SlidePresentation();
 - **Stable layout CSS.** Do not rewrite base layout/container CSS unless the structure itself must change. Prefer tokens, typography, component skins, and small motif components.
 - **Reusable class vocabulary.** New classes must be documented in this DESIGN.md. Avoid many one-off selectors in generated decks.
 - **SVG is exceptional.** Use decorative SVG only when the user explicitly asks for an illustration/icon-like visual or when design authoring requires a motif.
+- **Icon system is Lucide.** For ordinary UI, semantic, status, category, process, and navigation icons, use Lucide (`data-lucide`). Do not hand-write inline SVG for icons. SVG is allowed only for intentional decorative motifs, illustrations, or design-specific artwork. If any `data-lucide` icon is present, load Lucide via CDN and call `lucide.createIcons()` after `SlidePresentation`.
 - **Images for photographic references.** Use image treatment rules rather than fake SVG when the reference is photographic, UI, webpage, or product imagery.
 - **Content pages need a stable title block.** Except cover, TOC, closing, section divider, and full-bleed hero slides, every normal content slide should include a visible title block from the upper-left safe area. It should contain a compact chapter/section label plus a slide title written as the page's claim or takeaway.
 - **Do not hide the page title inside a card.** Body components may have their own headings, but the slide-level title block should remain separate and easy to scan unless the chosen layout explicitly defines a compact side-title variant.

package/designs/summit/DESIGN.md

@@ -443,6 +443,7 @@ These rules are mandatory for Summit.
 - **Text panels are not decorative rule panels.** Do not add a default left border, vertical accent bar, yellow/gold line, or inline rule to `text-panel`. Use typography, spacing, boxes, stats, quotes, or layout-level dividers for emphasis.
 - **Titles are Title Case.** Do not set `text-transform:uppercase` on `h1`, `h2`, `h3`, or `h4` titles. Uppercase is reserved for eyebrows, captions, metadata labels, short codes, and date/code-like markers.
 - **Components are transparent by default.** Component primitives should not bring their own paper/background fill. Let `.page`, layout containers, or explicit modifier variants provide background color when needed.
+- **Icon system is Lucide.** For ordinary UI, semantic, status, category, process, and navigation icons, use Lucide (`data-lucide`). Do not hand-write inline SVG for icons. SVG is allowed only for intentional decorative motifs, illustrations, or design-specific artwork. If any `data-lucide` icon is present, load Lucide via CDN and call `lucide.createIcons()` after `SlidePresentation`.
 
 ### Common Mistakes
 

package/lib/commands/help.ts

@@ -27,7 +27,7 @@ export async function handleHelp(
     `Run \`/revela enable\` to load Revela context without starting a workflow, or run \`/revela disable\` to pause it. Workflow commands still auto-enable Revela.\n\n` +
     `---\n\n` +
     `**Workflow**\n\n` +
-    `1. \`init\` — discover workspace sources and capture intent\n` +
+    `1. \`init\` — discover sources, refresh the graph, ask key questions, and recommend next steps\n` +
     `2. \`research\` — close evidence gaps and bind support\n` +
     `3. \`story\` — inspect audience, thesis, claims, evidence, risks, and diagnostics\n` +
     `4. \`make\` — generate deck or brief from canonical story state\n` +
@@ -38,7 +38,7 @@ export async function handleHelp(
     `\`/revela\`                                      — show REVELA help\n` +
     `\`/revela enable\`                               — enable Revela prompt/context without starting a workflow\n` +
     `\`/revela disable\`                              — disable Revela prompt/context for this session\n` +
-    `\`/revela init\`                                 — initialize or refresh workspace story state\n` +
+    `\`/revela init\`                                 — start Revela: discover sources, refresh story state, ask key questions, and recommend next steps\n` +
     `\`/revela research\`                             — research, bind evidence, and reduce story gaps\n` +
     `\`/revela story [-l language]\`                   — open the read-only story workspace UI\n` +
     `\`/revela make --deck\`                          — make a deck from story state and deck-plan/\n` +

package/lib/commands/init.ts

@@ -11,12 +11,13 @@ export function buildInitPrompt({
     ? `A ${DECKS_STATE_FILE} file already exists as legacy/cache state. Read it first through the revela-decks tool and update it conservatively only for compatibility metadata.`
     : `No ${DECKS_STATE_FILE} file exists yet. Keep this workspace file-native: initialize the Markdown narrative vault before writing narrative meaning and do not create ${DECKS_STATE_FILE}.`
 
-  return `Initialize Revela narrative workspace state.
+  return `Start Revela on the current workspace.
 
 Goal:
 - Initialize or refresh the Markdown narrative vault and file-native source inventory from local workspace evidence.
 - Treat init as repeatable ingest: discover files, register source materials, follow returned ingest task hints, and distill stable narrative meaning.
 - Capture primary audience, belief before/after, decision/action, thesis, central claims, evidence availability, objections, risks, source materials, artifact history, and open questions.
+- End init with a guided completion report: what local discovery found, what the narrative graph currently contains, what gaps remain, what user clarification is needed, and which command should run next.
 - Do not treat initialization as permission to write a deck. Do not require slide count, visual style, design selection, output path, layout choices, or component choices unless the user explicitly asks to render.
 - Treat central claims as chapter-ready claims, not evidence fragments: a central claim should be able to support framing/context, proof/evidence, decision implication, and explicit boundary/gap/risk material. If local material only supports a narrow fact, record it as supporting evidence or a supporting claim instead of promoting it to central importance.
 
@@ -60,7 +61,7 @@ Required workflow:
 6. Before writing narrative meaning, inspect \`narrativeInventory\` from the latest \`read(summary: true)\` result or call \`revela-decks narrativeInventory\`. Then distill stable findings into \`revela-narrative/**/*.md\` using the Markdown authoring guide. Completeness is not a gate: write partial claims, caveats, unsupported scope, and research gaps rather than waiting for a complete story. Use optional helpers such as \`upsertVaultResearchGap\`, \`upsertVaultEvidence\`, or \`bindResearchFindings\` only when they fit the exact update. Preserve frontmatter ids and existing section headings when editing Markdown. Write nodes first; add inline \`## Relations\` edges afterward only when explicit.
 7. After Markdown changes, rely on the vault write hook or call \`revela-decks markdownQa\`, then \`revela-decks compileNarrativeVault\`; keep \`markdownQa.repairCards\` separate from compiler blockers and fix both before treating the narrative as usable. If no explicit \`markdownQa\` result is visible after compile, call \`revela-decks markdownQa\` as a manual fallback. Do not use \`upsertNarrative\`.
 8. If explicit deck/artifact information exists, record conservative artifact context in file-native outputs or existing compatibility state only from visible information. Do not infer hidden evidence from generated artifacts.
-9. Report initialized/updated/migrated state plus counts and paths for added, changed, newer-than-vault, unchanged, \`ingest.ingestCandidates\`, and \`ingest.suggestedTasks\`. Always include \`Markdown QA: clean\` or \`Markdown QA blockers:\` in the final report. If Markdown QA blockers remain, do not say the workspace initialized cleanly; say the vault was initialized but Markdown repairs remain.
+9. Complete an Init Completion Report before ending. Do not end with only a technical success message. Include local discovery counts and paths for added, changed, newer-than-vault, unchanged, \`ingest.ingestCandidates\`, and \`ingest.suggestedTasks\`; a narrative graph summary; open evidence/research gaps; any Markdown QA status; user clarification questions; and recommended next commands. Always include \`Markdown QA: clean\` or \`Markdown QA blockers:\` in the final report. If Markdown QA blockers remain, do not say the workspace initialized cleanly; say the vault was initialized but Markdown repairs remain.
 
 Evidence boundary:
 - \`workspace.sourceMaterials\` and ingest task hints are candidate context, not proof.
@@ -81,6 +82,13 @@ Narrative questions to ask only when missing:
 - Which sources or findings support those claims?
 - What objections, risks, assumptions, or caveats could break the argument?
 
+Init completion rules:
+- Before ending \`/revela init\`, either use the question tool (AskQuestion) for at least one useful clarification or explicitly state that no clarification is needed now.
+- Ask only narrative-startup questions during init: audience, decision/action, scope, source priority, missing internal data, or whether external research is allowed for public evidence gaps.
+- Do not ask for slide count, design choice, layout choice, visual style, output path, PDF/PPTX export, or component preferences during init.
+- Always surface open gaps. Classify them as evidence gaps, research gaps, internal-data-needed, source-quality limits, or user-intent questions when possible.
+- Always recommend the next command: \`/revela research\` when evidence gaps need support, \`/revela story\` when the graph is ready to inspect, and \`/revela make --deck\` only when the user is ready to render from the current story.
+
 Memory rules:
 - Only write facts supported by workspace files or explicit user statements into file-native narrative/source files or, when ${DECKS_STATE_FILE} already exists, conservative compatibility metadata such as source materials, deck memory, and open questions.
 - Only write user preferences if the user explicitly stated that Revela should remember them.

package/lib/commands/narrative.ts

@@ -2,11 +2,10 @@ import { mkdirSync, writeFileSync } from "fs"
 import { tmpdir } from "os"
 import { join } from "path"
 import { openUrl as defaultOpenUrl } from "../edit/open"
-import { hasDecksState, readDecksState } from "../decks-state"
+import { createEmptyDecksState } from "../decks-state"
 import { buildNarrativeMap, formatNarrativeMap } from "../narrative-state/map"
 import { renderNarrativeMapHtmlWithDisplay } from "../narrative-state/map-html"
 import { emptyDisplayModel, type NarrativeViewLanguage, type ValidatedNarrativeDisplayModel } from "../narrative-state/display"
-import type { NarrativeApproval } from "../narrative-state/types"
 import { compileNarrativeVault, formatVaultDiagnosticMarkdown, formatVaultDiagnosticReport, hasNarrativeVault } from "../narrative-vault"
 
 export interface NarrativeArgs {
@@ -18,6 +17,10 @@ export interface StoryArgs {
   language: NarrativeViewLanguage
 }
 
+export type StoryMapLoadResult =
+  | { ok: true; map: ReturnType<typeof buildNarrativeMap>; diagnosticsMarkdown: string; diagnosticsReport: ReturnType<typeof formatVaultDiagnosticReport> }
+  | { ok: false; error: string; diagnosticsMarkdown: string; diagnosticsReport?: ReturnType<typeof formatVaultDiagnosticReport> }
+
 export type ParseNarrativeArgsResult = { ok: true; args: NarrativeArgs } | { ok: false; error: string }
 export type ParseStoryArgsResult = { ok: true; args: StoryArgs } | { ok: false; error: string }
 
@@ -77,14 +80,14 @@ export async function handleNarrative(
   send: (text: string) => Promise<void>,
 ): Promise<void> {
   try {
-    if (!hasDecksState(options.workspaceRoot)) {
-      await send("No `DECKS.json` found. Run `/revela init` first to initialize the narrative workspace.")
+    const loaded = loadStoryMap(options.workspaceRoot)
+    if (!loaded.ok) {
+      await send([loaded.error, loaded.diagnosticsMarkdown].filter(Boolean).join("\n\n"))
       return
     }
 
-    const state = readDecksState(options.workspaceRoot)
-    const map = buildNarrativeMap(state)
-    const diagnosticsMarkdown = vaultDiagnosticsMarkdown(options.workspaceRoot, state.narrative?.approvals ?? [])
+    const map = loaded.map
+    const diagnosticsMarkdown = loaded.diagnosticsMarkdown
     const markdown = [diagnosticsMarkdown, formatNarrativeMap(map)].filter(Boolean).join("\n\n")
 
     if (options.openBrowser) {
@@ -105,22 +108,40 @@ export async function handleNarrative(
   }
 }
 
-function vaultDiagnosticsMarkdown(workspaceRoot: string, fallbackApprovals: NarrativeApproval[]): string {
-  if (!hasNarrativeVault(workspaceRoot)) return ""
-  const result = compileNarrativeVault(workspaceRoot, { fallbackApprovals })
-  return formatVaultDiagnosticMarkdown(formatVaultDiagnosticReport(result.diagnostics))
+export function loadStoryMap(workspaceRoot: string): StoryMapLoadResult {
+  if (!hasNarrativeVault(workspaceRoot)) {
+    return {
+      ok: false,
+      error: "No `revela-narrative/` vault found. Run `/revela init` first to initialize the narrative workspace.",
+      diagnosticsMarkdown: "",
+    }
+  }
+
+  const result = compileNarrativeVault(workspaceRoot)
+  const diagnosticsReport = formatVaultDiagnosticReport(result.diagnostics)
+  const diagnosticsMarkdown = formatVaultDiagnosticMarkdown(diagnosticsReport)
+  if (!result.narrative) {
+    return {
+      ok: false,
+      error: "The `revela-narrative/` vault could not be compiled into a narrative map.",
+      diagnosticsMarkdown,
+      diagnosticsReport,
+    }
+  }
+
+  const state = createEmptyDecksState()
+  state.narrative = result.narrative
+  return { ok: true, map: buildNarrativeMap(state), diagnosticsMarkdown, diagnosticsReport }
 }
 
 export function buildNarrativeViewPrompt(options: { workspaceRoot: string; language: NarrativeViewLanguage }): string {
-  if (!hasDecksState(options.workspaceRoot)) {
-    return "No `DECKS.json` found. Tell the user to run `/revela init` before opening the narrative view. Do not call any tool."
+  const loaded = loadStoryMap(options.workspaceRoot)
+  if (!loaded.ok) {
+    return `${loaded.error}\n\n${loaded.diagnosticsMarkdown}\n\nDo not call any tool.`
   }
 
-  const state = readDecksState(options.workspaceRoot)
-  const map = buildNarrativeMap(state)
-  const vaultDiagnostics = hasNarrativeVault(options.workspaceRoot)
-    ? formatVaultDiagnosticReport(compileNarrativeVault(options.workspaceRoot, { fallbackApprovals: state.narrative?.approvals ?? [] }).diagnostics)
-    : undefined
+  const map = loaded.map
+  const vaultDiagnostics = loaded.diagnosticsReport
   const projection = {
     narrativeHash: map.snapshot.narrativeHash,
     language: options.language,
@@ -161,7 +182,7 @@ Target language request: ${options.language}
 You must call the \`revela-narrative-view\` tool exactly once.
 
 Hard rules:
-- Do not mutate DECKS.json, deck HTML, evidence, claims, relations, approvals, or artifacts.
+- Do not mutate narrative files, deck HTML, evidence, claims, relations, approvals, or artifacts.
 - Do not invent new claims, evidence, relations, slide coverage, source paths, findings files, quotes, or caveats.
 - Preserve every claimId exactly.
 - Preserve every relation endpoint exactly: fromClaimId, toClaimId, relation.

package/lib/prompt-builder.ts

@@ -202,6 +202,7 @@ function buildDesignLayer(designName: string): string {
       "",
       "| Section | Fetch with |",
       "|---|---|",
+      "| Design composition and usage rules | `section: \"rules\"` |",
       "| Layout HTML/CSS details | `layout: \"<name>\"` (see Layout Index above) |",
       "| Component CSS/HTML details | `component: \"<name>\"` (see Component Index above) |",
       "| Data Visualization (ECharts) | `section: \"chart-rules\"` |",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "description": "OpenCode plugin for trusted narrative artifacts from local sources, research, and evidence",
   "type": "module",
   "main": "./index.ts",

package/skill/NARRATIVE_SKILL.md

@@ -16,7 +16,7 @@ Default mode is narrative-first. Do not generate HTML slides, choose layouts, fe
 
 Use the same phase semantics whether the user invokes a slash command or asks in normal chat:
 
-- `Init` discovers local workspace materials, captures intent, initializes or refreshes workspace state, and creates conservative narrative state only from explicit user statements or source traces.
+- `Init` starts Revela on the current workspace: discover local materials, capture missing intent, refresh the narrative graph, surface gaps, and recommend the next command.
 - `Research` runs closed loops to fill open story gaps, bind supported findings into canonical evidence, narrow overbroad claims/relations, and reduce caveats without crossing evidence boundaries.
 - `Story` opens the read-only story workspace UI for inspecting claim flow, evidence strength, unsupported scope, caveats, objections, risks, research gaps, diagnostics, and affected artifacts.
 - `Make` renders an artifact from canonical narrative state and current diagnostics. Supported targets are deck and executive brief.
@@ -74,6 +74,9 @@ During init:
 - derive claims, evidence bindings, caveats, unsupported scope, source paths, quotes/snippets, pages, sheets, or slide references only when explicit support exists; distill ingested files by writing Markdown nodes under `revela-narrative/` even when the narrative is incomplete, and represent missing information as research gaps or caveats
 - write `## Relations` sections with plain node-id wikilinks such as `- supports: [[claim-example]]`, `- depends_on: [[evidence-example]]`, `- answers: [[claim-example]]`, or `- constrains: [[claim-example]]` when the relation is explicit; do not use typed wikilinks or hand-written relation ids; compile and fix diagnostics after editing Markdown
 - ask the smallest missing intent questions after local evidence has been considered
+- before ending `/revela init`, either use the question tool (AskQuestion) for a useful clarification or explicitly state that no clarification is needed now
+- always report local discovery status, narrative graph status, open evidence/research gaps, Markdown QA status, and recommended next commands
+- recommend `/revela research` when gaps need evidence, `/revela story` when the graph is ready to inspect, and `/revela make --deck` only when the user is ready to render
 - do not require slide count, design choice, layout choice, output path, or visual style unless the user explicitly asks to make an artifact immediately
 - when exporting a vault, say that any legacy render targets, reviews, artifact coverage, actions, deck specs, and source material records in `DECKS.json` are cache/provenance only
 

package/skill/SKILL.md

@@ -193,16 +193,20 @@ If a write produces QA hard errors, fix them before continuing.
 Before writing or materially changing HTML:
 
 1. Read the deck-plan projection's layout and component names.
-2. Call `revela-designs` with `action: "read"` and `layout` set to all required
+2. Call `revela-designs` with `action: "read"` and `section: "rules"` to fetch
+   the active design's current composition and usage rules.
+3. Call `revela-designs` with `action: "read"` and `layout` set to all required
    layout names, comma-separated.
-3. Call `revela-designs` with `action: "read"` and `component` set to all
+4. Call `revela-designs` with `action: "read"` and `component` set to all
    required component names, comma-separated.
-4. Fetch `section: "chart-rules"` before using ECharts.
-5. Do not update legacy `requiredInputs`; design fetching is an execution step,
+5. Fetch `section: "chart-rules"` before using ECharts.
+6. Do not update legacy `requiredInputs`; design fetching is an execution step,
    not a workflow permission gate.
 
 Never generate HTML from memory or prior knowledge of a design. Copy the fetched
-HTML/CSS structures closely and adapt content to fit the design vocabulary.
+HTML/CSS structures closely and adapt content to fit the design vocabulary. Do
+not treat the injected design summary as a substitute for the fetched `rules`,
+layout, and component details when generating or materially changing HTML.
 
 The active design's complete visual specification is injected below after the
 `---` separator. It is the sole visual reference for generating slides.
@@ -227,7 +231,8 @@ Required contract:
 - Do not use 0-based `data-index` as slide identity.
 - Keep the canvas exactly 1920x1080 and 16:9.
 - Keep all CSS inline in one `<style>` block and all JS inline in one `<script>`
-  block, except approved CDNs for fonts, Lucide icons, and ECharts when needed.
+  block, except approved CDNs for fonts, ECharts when needed, or libraries
+  explicitly required by fetched design/component rules.
 - Use vanilla JS only. No React, Vue, jQuery, or external application framework.
 - All JS methods must be fully implemented. No empty stubs and no TODO comments.
 - Do not add deck-local editing JavaScript, `contenteditable`, `editable` classes,
@@ -338,8 +343,6 @@ instructions, secrets, or unverified claims.
 - Use semantic HTML where practical.
 - Full keyboard navigation must work.
 - `prefers-reduced-motion` must disable transitions/animations.
-- Use Lucide icons only when icons are needed; load via CDN and call
-  `lucide.createIcons()`.
 - Avoid plain background plus unstyled bullet lists.
 - Every slide needs one clear message and one dominant visual focal point.
 - Keep bullet lists short. Prefer semantic boxes, evidence cards, charts, tables,

package/tools/designs.ts

@@ -25,7 +25,7 @@ export default tool({
     "Use action 'activate' to switch to a different design (requires name). " +
     "Use action 'install' to add a new design from a URL, local path, or github:user/repo shorthand (requires source). " +
     "Use action 'remove' to uninstall a design (requires name). " +
-    "Use action 'read' to fetch on-demand design content: pass layout (comma-separated names) to get full HTML/CSS for specific layouts, pass component (comma-separated names) to get full CSS/HTML for specific components, or section ('chart-rules' | 'foundation' | 'layouts' | 'components') to get an entire section. Pass neither to get the Component Index table. " +
+    "Use action 'read' to fetch on-demand design content: pass layout (comma-separated names) to get full HTML/CSS for specific layouts, pass component (comma-separated names) to get full CSS/HTML for specific components, or section ('rules' | 'chart-rules' | 'foundation' | 'layouts' | 'components') to get an entire section. Pass neither to get the Component Index table. " +
     "After activating a new design, the system prompt is automatically rebuilt.",
   args: {
     action: tool.schema

package/tools/narrative-view.ts

@@ -1,14 +1,12 @@
 import { tool } from "@opencode-ai/plugin"
-import { hasDecksState, readDecksState } from "../lib/decks-state"
-import { buildNarrativeMap } from "../lib/narrative-state/map"
 import { validateNarrativeDisplayModel, type NarrativeDisplayModel, type NarrativeViewLanguage } from "../lib/narrative-state/display"
-import { writeNarrativeMapHtml } from "../lib/commands/narrative"
+import { loadStoryMap, writeNarrativeMapHtml } from "../lib/commands/narrative"
 import { openUrl } from "../lib/edit/open"
 
 export default tool({
   description:
     "Render Revela's read-only narrative claim-flow UI from the current deterministic narrative map plus an optional localized display model. " +
-    "This tool validates display IDs against DECKS.json, opens a local HTML view, and never mutates workspace state.",
+    "This tool validates display IDs against the file-native narrative vault, opens a local HTML view, and never mutates workspace state.",
   args: {
     language: tool.schema.string().describe("UI language request from /revela story or /revela narrative. May be any language tag or language name, such as en, zh-CN, fr, de, Korean, Arabic, or Portuguese-BR."),
     narrativeHash: tool.schema.string().optional().describe("Narrative hash from the prompt projection. Used to detect stale display prompts."),
@@ -79,11 +77,10 @@ export default tool({
   async execute(args, context) {
     const workspaceRoot = context.directory ?? process.cwd()
     try {
-      if (!hasDecksState(workspaceRoot)) {
-        return JSON.stringify({ ok: false, error: "No DECKS.json found. Run /revela init first." })
-      }
       const language = args.language as NarrativeViewLanguage
-      const map = buildNarrativeMap(readDecksState(workspaceRoot))
+      const loaded = loadStoryMap(workspaceRoot)
+      if (!loaded.ok) return JSON.stringify({ ok: false, error: loaded.error, diagnostics: loaded.diagnosticsReport, diagnosticsMarkdown: loaded.diagnosticsMarkdown })
+      const map = loaded.map
       const stalePrompt = Boolean(args.narrativeHash && args.narrativeHash !== map.snapshot.narrativeHash)
       const display = validateNarrativeDisplayModel(map, args.displayModel as NarrativeDisplayModel | undefined, language)
       const htmlPath = writeNarrativeMapHtml(map, display)
@@ -92,8 +89,9 @@ export default tool({
       return JSON.stringify({ ok: true, url, path: htmlPath, narrativeHash: map.snapshot.narrativeHash, stalePrompt, fallback: false }, null, 2)
     } catch (e: any) {
       try {
-        const language = (args.language ?? "en") as NarrativeViewLanguage
-        const map = buildNarrativeMap(readDecksState(workspaceRoot))
+        const loaded = loadStoryMap(workspaceRoot)
+        if (!loaded.ok) return JSON.stringify({ ok: false, fallback: false, error: e.message || String(e), fallbackError: loaded.error, diagnostics: loaded.diagnosticsReport, diagnosticsMarkdown: loaded.diagnosticsMarkdown })
+        const map = loaded.map
         const htmlPath = writeNarrativeMapHtml(map)
         const url = `file://${htmlPath}`
         openUrl(url)