@cyber-dash-tech/revela 0.17.2 → 0.17.3

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "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/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)