@cyber-dash-tech/revela 0.17.1 → 0.17.3

package/designs/starter/DESIGN.md

@@ -253,7 +253,7 @@ new SlidePresentation();
 
 ### Layout Types
 
-Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. Use the QA flag on each layout marker. It must also set `data-slide-index="N"`, where `N` is the 1-based `DECKS.json` `slides[].index` value.
+Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. Use the QA flag on each layout marker. It must also set `data-slide-index="N"`, where `N` is the canonical positive 1-based artifact slide identity from the approved deck plan or DOM order. Indexes must be unique and strictly increase.
 
 Normal `qa=true` content layouts should start with a slide-level title block unless the layout marker explicitly says otherwise. Use this structure as the default: an eyebrow for chapter/section context, then an `h2` that states the slide's claim or takeaway. Keep body boxes, charts, media, and text panels below or beside that title region.
 

package/designs/summit/DESIGN.md

@@ -470,7 +470,7 @@ These rules are mandatory for Summit.
 
 ### Layout Types
 
-Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. It must also set `data-slide-index="N"`, where `N` is the 1-based `DECKS.json` `slides[].index` value. Use the QA column to decide which value to write. Fetch any layout with the `revela-designs` tool (`action: "read"`, `layout: "<name>"`).
+Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. It must also set `data-slide-index="N"`, where `N` is the canonical positive 1-based artifact slide identity from the approved deck plan or DOM order. Indexes must be unique and strictly increase. Use the QA column to decide which `slide-qa` value to write. Fetch any layout with the `revela-designs` tool (`action: "read"`, `layout: "<name>"`).
 
 Normal `qa=true` content layouts should start with a slide-level title block unless the layout marker explicitly says otherwise. Use an eyebrow for chapter/section context, then an `h2` that states the slide's claim or takeaway. Body boxes, charts, media, tables, and text panels should sit below or beside that title region rather than replacing it.
 

package/lib/commands/help.ts

@@ -27,10 +27,10 @@ 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 approval\n` +
-    `4. \`make\` — generate deck or brief from approved story state\n` +
+    `3. \`story\` — inspect audience, thesis, claims, evidence, risks, and diagnostics\n` +
+    `4. \`make\` — generate deck or brief from canonical story state\n` +
     `5. \`review\` — comment on and inspect rendered deck artifacts\n` +
     `6. \`export\` — export deck artifacts to PDF or PPTX\n\n` +
     `---\n\n` +
@@ -38,11 +38,11 @@ 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 approved story state\n` +
-    `\`/revela make --brief [file.md]\`                — render executive brief from approved story\n` +
+    `\`/revela make --deck\`                          — make a deck from story state and deck-plan/\n` +
+    `\`/revela make --brief [file.md]\`                — render executive brief from story state\n` +
     `\`/revela review --deck\`                        — open deck reading, insight, and comment workspace\n` +
     `\`/revela export --deck pdf [file.html]\`         — export HTML deck to PDF\n` +
     `\`/revela export --deck pptx [file.html] [--notes]\` — export HTML deck to PPTX\n` +

package/lib/commands/init.ts

@@ -8,16 +8,18 @@ export function buildInitPrompt({
   workspaceRoot?: string
 }): string {
   const mode = exists
-    ? `A ${DECKS_STATE_FILE} file already exists. Read it first through the revela-decks tool and update it conservatively.`
-    : `No ${DECKS_STATE_FILE} file exists yet. Initialize the Markdown narrative vault through the revela-decks tool before writing narrative meaning.`
+    ? `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:
-- Build or refresh ${DECKS_STATE_FILE} and the Markdown narrative vault from local workspace evidence.
+- 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.
 
 Current state:
 - ${mode}
@@ -32,7 +34,7 @@ Workspace boundary rules:
 - If the current workspace appears too broad, stop and ask the user which workspace subdirectory to initialize instead of scanning outside or deeply across everything.
 
 Expected tool use during init:
-- \`revela-decks init\` and \`revela-decks initNarrativeVault\` are expected controlled workspace-state/vault boundaries. Empty-looking optional fields in tool UI are a schema display artifact, not user-provided evidence.
+- \`revela-decks init\` and \`revela-decks initNarrativeVault\` are expected controlled file-native/vault boundaries. In fresh workspaces they must not create ${DECKS_STATE_FILE}; if legacy state already exists, they may update compatibility metadata conservatively. Empty-looking optional fields in tool UI are a schema display artifact, not user-provided evidence.
 - Treat \`authoringContract\` returned by \`read(summary: true)\`, \`initNarrativeVault\`, or \`narrativeInventory\` as the Markdown authoring guide: valid node types, plain id convention, inline relation syntax, forbidden compatibility actions, and optional helper templates.
 - Treat \`markdownQa\` returned by \`read(summary: true)\`, \`compileNarrativeVault\`, or \`revela-decks markdownQa\` as post-authoring repair feedback that is separate from compiler diagnostics. Fix \`repairCards\` by smallest repair; do not invent missing claims, evidence, source paths, URLs, quotes, or caveats just to clear QA. If \`compileNarrativeVault\` output does not visibly include \`markdownQa\`, call \`revela-decks markdownQa\` before final reporting.
 - Before authoring claims, evidence, relations, objections, risks, or research gaps, inspect \`narrativeInventory\` from \`read(summary: true)\` or call \`revela-decks narrativeInventory\`. Reuse existing ids and relation targets. Do not invent evidence ids, claim ids, or relation targets before checking inventory unless you are intentionally creating the missing node in Markdown.
@@ -58,8 +60,8 @@ Required workflow:
 5. For selected relevant tasks, read directly when \`suggestedAction: "read_directly"\`; call \`revela-extract-document-materials\` first when \`suggestedAction: "extract_then_read"\`. Do not extract every document by default.
 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 deck specs 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.
+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. 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.
@@ -67,6 +69,7 @@ Evidence boundary:
 - Preserve graph meaning by writing explicit edges in node-local \`## Relations\` sections after nodes exist. Use plain node-id wikilinks and optional inline rationale.
 - Intent briefs, proposals, and user-authored plans may support audience, decision, thesis, stakeholder framing, and stated internal intent. They do not by themselves prove market size, competitor performance, product-market fit, operating-model effectiveness, or external factual claims.
 - If a source states an intended strategy but not its external factual basis, record the strategy as a claim with partial or missing support and add a research gap instead of binding it as strong evidence.
+- If a central claim cannot yet sustain a future claim-led chapter, keep the insufficiency visible through evidence status, unsupported scope, caveats, or a research gap rather than padding the future deck with generic slides.
 - A successful vault compile means the vault is structurally valid. It is not evidence readiness, narrative approval, or permission to make a deck/brief.
 
 Narrative questions to ask only when missing:
@@ -79,12 +82,19 @@ 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 ${DECKS_STATE_FILE} workspace state, source materials, narrative compatibility fields, deck memory, and open questions.
+- 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.
 - Do not infer personal preferences from one-off requests.
 - Do not store secrets, credentials, API keys, tokens, account details, or sensitive personal information.
-- Do not mark narrative approval, render override, or writeReadiness as ready during init.
+- Do not create or update approval, render override, or writeReadiness workflow state during init.
 - Treat this workspace as a single deck project. If the user wants another deck, guide them to create another workspace/folder rather than adding a second deck record.
 - If new evidence conflicts with existing memory, preserve both briefly and add an Open Question instead of silently overwriting.
 

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/commands/pdf.ts

@@ -7,12 +7,11 @@
  * Example: decks/my-deck.html → decks/my-deck.pdf
  */
 
+import { existsSync, readdirSync } from "fs"
 import { resolve } from "path"
-import { hasDecksState, readDecksState } from "../decks-state"
 import { exportToPdf } from "../pdf/export"
 import { assertExportQAPassed } from "../qa/export-gate"
 import { recordRenderedArtifact, workspaceRelative } from "../workspace-state/rendered-artifacts"
-import { resolveActiveHtmlDeckPath } from "../workspace-state/render-targets"
 
 export async function handlePdf(
   filePath: string,
@@ -22,15 +21,15 @@ export async function handlePdf(
   const root = resolve(workspaceRoot)
   const resolvedFile = resolvePdfDeckFile(root, filePath)
 
-  if (!resolvedFile) {
+  if (!resolvedFile.ok) {
     await send(
-      "**Usage:** `/revela export --deck pdf [file_path]`\n\n" +
-      "Example: `/revela export --deck pdf decks/my-deck.html`"
+      `**PDF export cannot start**\n\n${resolvedFile.error}\n\n` +
+      "Usage: `/revela export --deck pdf [file_path]`"
     )
     return
   }
 
-  const abs = resolvedFile.absoluteFile
+  const abs = resolvedFile.deck.absoluteFile
   await send(`Running pre-export QA for \`${abs}\`...`)
 
   try {
@@ -38,7 +37,7 @@ export async function handlePdf(
     await send(`Exporting \`${abs}\` to PDF...`)
     const result = await exportToPdf(abs)
     recordRenderedArtifact(root, {
-      sourceHtmlPath: resolvedFile.file,
+      sourceHtmlPath: resolvedFile.deck.file,
       outputPath: result.outputPath,
       type: "pdf",
       actor: "revela-pdf",
@@ -56,17 +55,27 @@ export async function handlePdf(
   }
 }
 
-function resolvePdfDeckFile(workspaceRoot: string, filePath: string): { file: string; absoluteFile: string } | undefined {
+function resolvePdfDeckFile(workspaceRoot: string, filePath: string): { ok: true; deck: { file: string; absoluteFile: string } } | { ok: false; error: string } {
   const explicit = filePath.trim()
   if (explicit) {
     const absoluteFile = resolve(workspaceRoot, explicit)
-    return { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile }
+    if (!existsSync(absoluteFile)) return { ok: false, error: `Deck HTML not found: ${explicit}` }
+    if (!/\.html?$/i.test(absoluteFile)) return { ok: false, error: `File must be an HTML file: ${explicit}` }
+    return { ok: true, deck: { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile } }
   }
 
-  if (!hasDecksState(workspaceRoot)) return undefined
-  const state = readDecksState(workspaceRoot)
-  const activePath = resolveActiveHtmlDeckPath(state)
-  if (!activePath) return undefined
-  const absoluteFile = resolve(workspaceRoot, activePath)
-  return { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile }
+  const htmlFiles = listDeckHtmlFiles(workspaceRoot)
+  if (htmlFiles.length === 0) return { ok: false, error: "No deck HTML found in decks/. Pass a file path or generate a deck first." }
+  if (htmlFiles.length > 1) return { ok: false, error: `Multiple deck HTML files found in decks/: ${htmlFiles.join(", ")}. Pass the deck path explicitly.` }
+  const absoluteFile = resolve(workspaceRoot, htmlFiles[0])
+  return { ok: true, deck: { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile } }
+}
+
+function listDeckHtmlFiles(workspaceRoot: string): string[] {
+  const dir = resolve(workspaceRoot, "decks")
+  if (!existsSync(dir)) return []
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".html"))
+    .map((entry) => `decks/${entry.name}`)
+    .sort((a, b) => a.localeCompare(b))
 }

package/lib/commands/pptx.ts

@@ -9,11 +9,9 @@
 
 import { existsSync, readdirSync } from "fs"
 import { relative, resolve, sep } from "path"
-import { hasDecksState, isDeckHtmlPath, readDecksState } from "../decks-state"
 import { assertDeckHtmlContractValid } from "../deck-html/contract"
 import { exportToPptx } from "../pptx/export"
 import { recordRenderedArtifact } from "../workspace-state/rendered-artifacts"
-import { resolveActiveHtmlDeckPath } from "../workspace-state/render-targets"
 
 export interface PptxArgs {
   filePath: string
@@ -23,7 +21,7 @@ export interface PptxArgs {
 export interface ResolvedPptxDeck {
   file: string
   absoluteFile: string
-  source: "render-target" | "decks-state" | "fallback" | "file-path"
+  source: "discovered" | "file-path"
 }
 
 function formatSecs(ms: number): string {
@@ -47,18 +45,6 @@ export function resolvePptxDeck(workspaceRoot: string, filePath = ""): ResolvedP
     return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "file-path" }
   }
 
-  if (hasDecksState(root)) {
-    const state = readDecksState(root)
-    const outputPath = resolveActiveHtmlDeckPath(state)
-    if (outputPath && isDeckHtmlPath(outputPath)) {
-      const absoluteFile = resolve(root, outputPath)
-      if (existsSync(absoluteFile)) {
-        const source = state.renderTargets.some((target) => target.type === "html_deck" && target.outputPath === outputPath) ? "render-target" : "decks-state"
-        return { file: workspaceRelative(root, absoluteFile), absoluteFile, source }
-      }
-    }
-  }
-
   const htmlFiles = listDeckHtmlFiles(root)
   if (htmlFiles.length === 0) {
     throw new Error("No deck HTML found in decks/. Generate a deck first or pass a file path.")
@@ -68,7 +54,7 @@ export function resolvePptxDeck(workspaceRoot: string, filePath = ""): ResolvedP
   }
 
   const absoluteFile = resolve(root, htmlFiles[0])
-  return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "fallback" }
+  return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "discovered" }
 }
 
 export function buildPptxNotesPrompt(deck: ResolvedPptxDeck): string {

package/lib/commands/research.ts

@@ -16,6 +16,7 @@ export function buildResearchPrompt({
 Goal:
 - Reduce open gaps, unsupported scope, weak evidence, unattached findings, and overextended relation rationale for the current story.
 - Drive research from canonical narrative gaps: unsupported central claims, objections, risks, decision questions, explicit researchGaps, and claim_chain_gap warnings.
+- Drive research from central-claim chapter sufficiency, not only missing proof. Each central claim should aim for framing/background support, one or two bound evidence items or cases/quantitative signals, and implication/risk/boundary material before it is treated as deck-ready.
 - Treat /revela research as authorization to bind clearly supported findings through the safe \`bindResearchFindings\` boundary without asking for item-by-item user confirmation.
 - Preserve evidence boundaries: eliminate caveats only when evidence or narrower wording actually resolves them; otherwise keep precise caveats visible.
 - Do not write decks, briefs, or design artifacts during research.
@@ -50,6 +51,7 @@ Allowed mutations:
 
 Binding criteria:
 - supported claim id exists and is expressed as \`## Relations\` with \`- supports: [[claim-id]]\` for new evidence; quote/snippet is traceable and not invented; source URL/path/findingsFile is present; supportScope and unsupportedScope are explicit; caveat is preserved; strength is strong or useful partial; binding does not expand the claim. Frontmatter \`claimId\` is compatibility fallback, not the preferred graph source.
+- For central claims, prefer evidence that helps one of the future chapter jobs: framing/background, proof/case/quantitative signal, or implication/risk/boundary. If research only finds a weak context fact, bind or record it narrowly and keep the chapter sufficiency gap open.
 
 Stop conditions:
 - No open externally researchable gaps remain.