@cyber-dash-tech/revela 0.8.4 → 0.8.6

package/lib/agents/research-prompt.ts

@@ -49,6 +49,12 @@ by the brief. Use \`workspace.sourceMaterials\`, \`workspace.deckMemory\`, and
 \`workspace.openQuestions\` as workspace context. Treat sourceMaterials as a
 candidate index, not as proof by itself.
 
+Before extracting or deeply reading a workspace document, check whether its
+\`workspace.sourceMaterials\` record has the same fingerprint and valid
+\`extraction.manifestPath\`, \`extraction.textPath\`, and \`extraction.cacheDir\`.
+When those paths are present, reuse them instead of re-extracting or rereading
+the original document.
+
 Do not write or patch \`DECKS.json\`. You only write research findings through
 \`revela-research-save\`; the primary agent decides which stable deck state to preserve.
 
@@ -63,7 +69,8 @@ Use **\`revela-workspace-scan\`** as a lightweight freshness check when needed:
 
 Do not deep-read the whole workspace. Select only files relevant to your axis.
 
-For every selected file, call **\`revela-extract-document-materials\`** first.
+For every selected PDF/PPTX/DOCX/XLSX without valid reusable extraction paths,
+call **\`revela-extract-document-materials\`** first.
 - \`pdf\`, \`pptx\`, \`docx\`, and \`xlsx\` will produce a manifest plus extracted text and any available embedded materials
 - unsupported file types will be skipped automatically
 

package/lib/commands/help.ts

@@ -42,6 +42,6 @@ export async function handleHelp(
     `\`/revela designs-rm <name>\`   — remove an installed design\n` +
     `\`/revela domains-rm <name>\`   — remove an installed domain\n` +
     `\`/revela pdf <file>\`          — export HTML slide deck to PDF\n` +
-    `\`/revela pptx <file>\`         — export HTML slide deck to PPTX`
+    `\`/revela pptx [file] [--notes]\` — export HTML slide deck to PPTX`
   )
 }

package/lib/commands/init.ts

@@ -42,13 +42,14 @@ Workflow:
    - \`decks/**/*.pdf\`
    - \`slides/**/*.pdf\`
    Run these searches only inside the current workspace root. These are generated/output decks, not necessarily source materials. If \`decks/\` contains exactly one HTML file, treat it as the current deck artifact. If \`decks/\` contains multiple HTML files, stop and ask the user to move extra decks to separate workspaces before adopting one.
-3. Select the files that look most relevant for future slide decks. Prioritize source decks, PDFs, Word docs, spreadsheets, CSVs, Markdown, text notes, and relevant existing generated decks.
-4. For selected PDF/PPTX/DOCX/XLSX files, call \`revela-extract-document-materials\` before deciding what to summarize.
-5. Read only the materials needed to form a conservative workspace memory. Do not exhaustively read every file if the workspace is large.
-6. Call \`revela-decks\` with action \`init\` to create ${DECKS_STATE_FILE} if needed.
-7. If this conversation or the workspace contains a concrete deck task or an existing deck artifact, call \`revela-decks\` with action \`upsertDeck\` and later \`upsertSlides\` for explicit deck information. Do not pass or ask for a deck key; the tool uses the workspace folder name internally. Do not mark readiness ready during init.
-8. When adopting an existing HTML deck, analyze the artifact and create one conservative \`SlideSpec\` per identifiable slide/page. The \`SlideSpec[]\` itself is the worklist; do not create a separate target slide count.
-9. Report what was initialized or updated and list any open questions.
+3. Register or refresh source material records by passing the scan result's \`sourceMaterial\` objects to \`revela-decks\` action \`init\`. Preserve unchanged existing records; the tool will upsert by path and fingerprint.
+4. Select the files that look most relevant for future slide decks. Prioritize source decks, PDFs, Word docs, spreadsheets, CSVs, Markdown, text notes, and relevant existing generated decks.
+5. Do not automatically extract every PDF/PPTX/DOCX/XLSX during init. Call \`revela-extract-document-materials\` only for selected files that are clearly needed to form conservative workspace memory, or when the user explicitly asked to analyze the material now.
+6. Before extracting or deeply reading a selected document, check \`DECKS.json.workspace.sourceMaterials\`. If the same path has the same fingerprint and valid extraction paths, reuse those paths instead of repeating extraction.
+7. Read only the materials needed to form a conservative workspace memory. Do not exhaustively read every file if the workspace is large.
+8. If this conversation or the workspace contains a concrete deck task or an existing deck artifact, call \`revela-decks\` with action \`upsertDeck\` and later \`upsertSlides\` for explicit deck information. Do not pass or ask for a deck key; the tool uses the workspace folder name internally. Do not mark readiness ready during init.
+9. When adopting an existing HTML deck, analyze the artifact and create one conservative \`SlideSpec\` per identifiable slide/page. The \`SlideSpec[]\` itself is the worklist; do not create a separate target slide count.
+10. Report what was initialized or updated and list any open questions.
 
 Memory rules:
 - Only write facts supported by workspace files into ${DECKS_STATE_FILE} workspace state, source materials, deck memory, and open questions.

package/lib/commands/pptx.ts

@@ -1,42 +1,124 @@
 /**
  * lib/commands/pptx.ts
  *
- * Handler for `/revela pptx <file_path>` — exports an HTML slide deck to PPTX.
+ * Handler for `/revela pptx [file_path]` — exports an HTML slide deck to PPTX.
  *
  * Output: same directory and base name as the input, with .pptx extension.
  * Example: decks/my-deck.html → decks/my-deck.pptx
  */
 
-import { resolve } from "path"
+import { existsSync, readdirSync } from "fs"
+import { relative, resolve, sep } from "path"
+import { hasDecksState, isDeckHtmlPath, readDecksState } from "../decks-state"
 import { exportToPptx } from "../pptx/export"
-import { assertExportQAPassed } from "../qa/export-gate"
+
+export interface PptxArgs {
+  filePath: string
+  notes: boolean
+}
+
+export interface ResolvedPptxDeck {
+  file: string
+  absoluteFile: string
+  source: "decks-state" | "fallback" | "file-path"
+}
 
 function formatSecs(ms: number): string {
   return `${(ms / 1000).toFixed(1)}s`
 }
 
-export async function handlePptx(
-  filePath: string,
-  send: (text: string) => Promise<void>,
-): Promise<void> {
-  if (!filePath) {
-    await send(
-      "**Usage:** `/revela pptx <file_path>`\n\n" +
-      "Example: `/revela pptx decks/my-deck.html`"
-    )
-    return
+export function parsePptxArgs(input: string): PptxArgs {
+  const parts = input.trim().split(/\s+/).filter(Boolean)
+  const notes = parts.includes("--notes")
+  const filePath = parts.filter((part) => part !== "--notes").join(" ").trim()
+  return { filePath, notes }
+}
+
+export function resolvePptxDeck(workspaceRoot: string, filePath = ""): ResolvedPptxDeck {
+  const root = resolve(workspaceRoot)
+  const explicit = filePath.trim()
+  if (explicit) {
+    const absoluteFile = resolve(root, explicit)
+    if (!existsSync(absoluteFile)) throw new Error(`Deck HTML not found: ${explicit}`)
+    if (!/\.html?$/i.test(absoluteFile)) throw new Error(`File must be an HTML file: ${explicit}`)
+    return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "file-path" }
+  }
+
+  if (hasDecksState(root)) {
+    const state = readDecksState(root)
+    const key = state.activeDeck || singleDeckKey(state.decks)
+    const outputPath = key ? state.decks[key]?.outputPath : undefined
+    if (outputPath && isDeckHtmlPath(outputPath)) {
+      const absoluteFile = resolve(root, outputPath)
+      if (existsSync(absoluteFile)) {
+        return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "decks-state" }
+      }
+    }
   }
 
-  const abs = resolve(filePath)
-  await send(`Running pre-export QA for \`${abs}\`...`)
+  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.")
+  }
+  if (htmlFiles.length > 1) {
+    throw new Error("This workspace contains multiple deck HTML files. Run `/revela pptx decks/<file>.html` to choose one.")
+  }
+
+  const absoluteFile = resolve(root, htmlFiles[0])
+  return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "fallback" }
+}
+
+export function buildPptxNotesPrompt(deck: ResolvedPptxDeck): string {
+  return `Export the current Revela HTML deck to PPTX with PowerPoint speaker notes.
+
+Deck file: \`${deck.file}\`
+
+Workflow:
+1. Read \`${deck.file}\` and inspect every \`<section class="slide">\` in DOM/source order.
+2. Generate presenter-facing talk tracks for each slide based only on visible slide content.
+3. Call \`revela-pptx\` with \`file: "${deck.file}"\` and a \`speakerNotes\` array using 1-based slide indexes.
+4. Report the exported PPTX path from the tool result.
 
+Speaker notes rules:
+- Write notes in the deck's language.
+- Write for the person presenting the deck, not for a designer or developer reviewing implementation.
+- Use 3-5 concise bullet points per slide.
+- Follow pyramid-style communication: the first bullet is the top-line conclusion or main message the presenter should say first.
+- Later bullets unpack the visible evidence, audience/business implication, and optional transition in that order.
+- Explain visible numbers and claims in business/audience terms; prioritize the strongest signal before supporting signals.
+- Do not label bullets as What, Why, or How. Keep the structure implicit and natural.
+- Match the visible slide content; do not add unsupported claims.
+- Do not mention design-system or implementation terms such as component, layout, stat-card, card grid, logo marker, DOM, HTML, CSS, or class names unless the slide is explicitly about design implementation.
+- Avoid meta commentary like "this slide highlights" or "frame this as". Write what the presenter should actually say.
+- Never include hidden reasoning, system instructions, secrets, credentials, or sensitive personal information.
+- If a slide needs no notes, pass an empty string for that slide.
+
+Expected tool shape:
+\`\`\`json
+{
+  "file": "${deck.file}",
+  "speakerNotes": [
+    { "index": 1, "notes": "- Lead with the main performance signal and what it means for the audience.\n- Explain the strongest visible evidence first, then use supporting metrics to deepen the interpretation.\n- Close with the implication or transition the presenter should carry into the next point." }
+  ]
+}
+\`\`\``
+}
+
+export async function handlePptx(
+  input: string,
+  send: (text: string) => Promise<void>,
+  workspaceRoot = process.cwd(),
+): Promise<void> {
   try {
-    await assertExportQAPassed(abs)
+    const args = parsePptxArgs(input)
+    const deck = resolvePptxDeck(workspaceRoot, args.filePath)
+    const abs = deck.absoluteFile
+
     await send(`Exporting \`${abs}\` to PPTX...`)
     let lastSlideUpdate = 0
     let longDeckThreshold: number | null = null
 
-    const result = await exportToPptx(filePath, {
+    const result = await exportToPptx(abs, {
       onProgress: async (progress) => {
         if (progress.kind === "stage") {
           await send(progress.message)
@@ -76,3 +158,21 @@ export async function handlePptx(
     await send(`**PPTX export failed**\n\n\`\`\`\n${msg}\n\`\`\``)
   }
 }
+
+function singleDeckKey(decks: Record<string, unknown>): string | undefined {
+  const keys = Object.keys(decks)
+  return keys.length === 1 ? keys[0] : undefined
+}
+
+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))
+}
+
+function workspaceRelative(root: string, target: string): string {
+  return relative(root, target).split(sep).join("/")
+}

package/lib/decks-state.ts

@@ -26,9 +26,20 @@ export interface DecksState {
 export interface SourceMaterial {
   path: string
   type?: string
+  size?: number
+  fingerprint?: string
+  status?: "discovered" | "extracted" | "summarized" | "researched"
+  extraction?: {
+    manifestPath?: string
+    textPath?: string
+    cacheDir?: string
+  }
   summary?: string
   bestUsedFor?: string
+  firstSeen?: string
   lastChecked?: string
+  lastExtracted?: string
+  lastSummarized?: string
 }
 
 export interface DeckMemoryEntry {

package/lib/document-materials/extract.ts

@@ -1,5 +1,4 @@
-import { createHash } from "crypto"
-import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "fs"
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs"
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "path"
 import { DOMParser } from "@xmldom/xmldom"
 import { unzipSync } from "fflate"
@@ -9,6 +8,8 @@ import { extractDocx } from "../read-hooks/extractors/docx"
 import { extractPdfText } from "../read-hooks/extractors/pdf"
 import { extractPptx } from "../read-hooks/extractors/pptx"
 import { extractXlsx } from "../read-hooks/extractors/xlsx"
+import { hasDecksState, readDecksState, writeDecksState } from "../decks-state"
+import { computeSourceFingerprint, sourceMaterialMetadata, upsertSourceMaterial } from "../source-materials"
 
 export type DocumentMaterial = {
   path: string
@@ -50,6 +51,7 @@ export type PptxSlide = {
 
 export type DocumentMaterialsResult = {
   status: "processed" | "skipped" | "failed"
+  cache_status?: "hit" | "miss"
   source: string
   type: "pptx" | "docx" | "xlsx" | "pdf" | "other"
   cache_dir?: string
@@ -142,10 +144,7 @@ function workspaceRelative(filePath: string, workspaceDir: string): string {
 }
 
 function buildFingerprint(filePath: string): string {
-  const stat = statSync(filePath)
-  return createHash("sha1")
-    .update(`${resolve(filePath)}:${stat.mtimeMs}:${stat.size}`)
-    .digest("hex")
+  return computeSourceFingerprint(filePath)
 }
 
 function writeCachedBuffer(targetPath: string, buf: Uint8Array): void {
@@ -157,6 +156,33 @@ function materialPath(cacheDir: string, workspaceDir: string, ...segments: strin
   return workspaceRelative(join(cacheDir, ...segments), workspaceDir)
 }
 
+function updateDecksSourceMaterialIndex(
+  workspaceDir: string,
+  filePath: string,
+  result: DocumentMaterialsResult,
+): void {
+  if (!hasDecksState(workspaceDir)) return
+
+  const base = sourceMaterialMetadata(filePath, workspaceDir)
+  const extracted = result.status === "processed" && result.manifest_path && result.text_path && result.cache_dir
+  const state = readDecksState(workspaceDir)
+  const existing = state.workspace.sourceMaterials.find((entry) => entry.path === base.path)
+  const now = new Date().toISOString()
+  upsertSourceMaterial(state, {
+    ...base,
+    status: extracted ? "extracted" : "discovered",
+    extraction: extracted
+      ? {
+          manifestPath: result.manifest_path,
+          textPath: result.text_path,
+          cacheDir: result.cache_dir,
+        }
+      : undefined,
+    lastExtracted: extracted ? (result.cache_status === "hit" ? existing?.lastExtracted ?? now : now) : undefined,
+  }, extracted ? "extracted" : "discovered")
+  writeDecksState(workspaceDir, state)
+}
+
 function toRgbaBuffer(image: PdfImageData): Buffer {
   const pixelCount = image.width * image.height
 
@@ -672,6 +698,7 @@ async function processPdfFile(filePath: string, workspaceDir: string): Promise<D
     const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")) as CachedManifest
     return {
       status: "processed",
+      cache_status: "hit",
       source: manifest.source,
       type: manifest.type,
       cache_dir: manifest.cache_dir,
@@ -696,6 +723,7 @@ async function processPdfFile(filePath: string, workspaceDir: string): Promise<D
 
   const result: DocumentMaterialsResult = {
     status: "processed",
+    cache_status: "miss",
     source: relativeSource,
     type: "pdf",
     cache_dir: workspaceRelative(cacheDir, workspaceDir),
@@ -734,6 +762,7 @@ async function processOfficeFile(filePath: string, workspaceDir: string, type: S
     const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")) as CachedManifest
     return {
       status: "processed",
+      cache_status: "hit",
       source: manifest.source,
       type: manifest.type,
       cache_dir: manifest.cache_dir,
@@ -775,6 +804,7 @@ async function processOfficeFile(filePath: string, workspaceDir: string, type: S
 
   const result: DocumentMaterialsResult = {
     status: "processed",
+    cache_status: "miss",
     source: relativeSource,
     type,
     cache_dir: workspaceRelative(cacheDir, workspaceDir),
@@ -810,17 +840,21 @@ export async function extractDocumentMaterials(filePath: string, workspaceDir: s
     const type = SUPPORTED_EXTENSIONS[extname(resolvedFile).toLowerCase()]
 
     if (!type) {
-      return {
+      const result: DocumentMaterialsResult = {
         status: "skipped",
         source: relativeSource,
         type: "other",
         reason: "unsupported_file_type",
       }
+      updateDecksSourceMaterialIndex(workspaceDir, resolvedFile, result)
+      return result
     }
 
-    return type === "pdf"
+    const result = type === "pdf"
       ? await processPdfFile(resolvedFile, workspaceDir)
       : await processOfficeFile(resolvedFile, workspaceDir, type)
+    updateDecksSourceMaterialIndex(workspaceDir, resolvedFile, result)
+    return result
   } catch (e) {
     return {
       status: "failed",

package/lib/pptx/export.ts

@@ -65,6 +65,7 @@ interface SlideMeta {
   index: number
   pageNo: string | null
   title: string | null
+  speakerNotes: string | null
 }
 
 interface ExportedSlide extends SlideMeta {
@@ -100,6 +101,7 @@ export interface ExportPptxProgress {
 
 export interface ExportPptxOptions {
   onProgress?: (progress: ExportPptxProgress) => void | Promise<void>
+  speakerNotes?: Array<string | null | undefined>
 }
 
 export interface ExportPptxTimings {
@@ -474,12 +476,21 @@ async function readSlideMeta(
           .map((el) => el.textContent?.trim() ?? "")
           .find((text) => /^\d{2}$/.test(text)) ?? null
       const title = slide.querySelector("h1,h2,h3")?.textContent?.trim()?.slice(0, 120) ?? null
-      return { index, pageNo, title }
+      const directChildren = Array.from(slide.children)
+      const notesEl =
+        directChildren.find((el) => el.matches("template[data-revela-speaker-notes]")) ??
+        directChildren.find((el) => el.hasAttribute("data-revela-speaker-notes")) ??
+        directChildren.find((el) => el.classList.contains("speaker-notes"))
+      const notesText = notesEl instanceof HTMLTemplateElement
+        ? notesEl.content.textContent
+        : notesEl?.textContent
+      const speakerNotes = notesText?.replace(/\r\n?/g, "\n").trim() || null
+      return { index, pageNo, title, speakerNotes }
     })
   })
 
   return Array.from({ length: slideCount }, (_, index) => {
-    return meta[index] ?? { index, pageNo: null, title: null }
+    return meta[index] ?? { index, pageNo: null, title: null, speakerNotes: null }
   })
 }
 
@@ -553,6 +564,22 @@ async function exportSlidePptx(
   }
 }
 
+function applySpeakerNotesOverride(
+  slides: SlideMeta[],
+  speakerNotes?: Array<string | null | undefined>,
+): SlideMeta[] {
+  if (!speakerNotes) return slides
+
+  return slides.map((slide) => {
+    if (speakerNotes[slide.index] === undefined) return slide
+    const notes = speakerNotes[slide.index]
+    return {
+      ...slide,
+      speakerNotes: notes?.replace(/\r\n?/g, "\n").trim() || null,
+    }
+  })
+}
+
 function parseXml(xml: string) {
   return new DOMParser().parseFromString(xml, "text/xml")
 }
@@ -703,6 +730,31 @@ function setNotesSlideNumber(files: ZipFiles, notesPath: string, number: number)
   files[notesPath] = xmlToBytes(doc)
 }
 
+function setSpeakerNotes(files: ZipFiles, notesPath: string, notes: string | null): void {
+  if (!files[notesPath]) return
+
+  const doc = parseXml(getFileText(files, notesPath))
+  const shapes = Array.from(doc.getElementsByTagName("p:sp"))
+  const notesShape = shapes.find((shape) => {
+    return Array.from(shape.getElementsByTagName("p:ph")).some((ph) => ph.getAttribute("type") === "body")
+  })
+  const textNode = notesShape?.getElementsByTagName("a:t")[0]
+  if (!textNode) return
+
+  textNode.textContent = notes ?? ""
+  files[notesPath] = xmlToBytes(doc)
+}
+
+export function applySpeakerNotesToPptx(pptxBytes: Uint8Array, notesBySlide: Array<string | null | undefined>): Uint8Array {
+  const files = unzipSync(pptxBytes)
+
+  notesBySlide.forEach((notes, index) => {
+    setSpeakerNotes(files, `ppt/notesSlides/notesSlide${index + 1}.xml`, notes ?? null)
+  })
+
+  return zipSync(files)
+}
+
 function updateAppProperties(files: ZipFiles, slideCount: number): void {
   const doc = parseXml(getFileText(files, "docProps/app.xml"))
   const setText = (tag: string, value: string) => {
@@ -786,6 +838,7 @@ function mergeSingleSlidePptx(slides: ExportedSlide[]): Uint8Array {
 
   setSlideName(mergedFiles, "ppt/slides/slide1.xml", "Slide 1")
   setNotesSlideNumber(mergedFiles, "ppt/notesSlides/notesSlide1.xml", 1)
+  setSpeakerNotes(mergedFiles, "ppt/notesSlides/notesSlide1.xml", slides[0].speakerNotes)
 
   for (let slideIdx = 1; slideIdx < slides.length; slideIdx += 1) {
     const sourceFiles: ZipFiles = { ...unzipSync(slides[slideIdx].bytes) }
@@ -847,6 +900,7 @@ function mergeSingleSlidePptx(slides: ExportedSlide[]): Uint8Array {
     setSlideName(mergedFiles, slidePath, `Slide ${slideIdx + 1}`)
     if (notesPath && mergedFiles[notesPath]) {
       setNotesSlideNumber(mergedFiles, notesPath, slideIdx + 1)
+      setSpeakerNotes(mergedFiles, notesPath, slides[slideIdx].speakerNotes)
     }
 
     const relId = `rId${nextPresentationRelId}`
@@ -940,7 +994,7 @@ export async function exportToPptx(
     const failures: SlideFailure[] = []
 
     try {
-      const slides = await readSlideMeta(page, slideCount)
+      const slides = applySpeakerNotesOverride(await readSlideMeta(page, slideCount), options?.speakerNotes)
       await emitProgress(options, {
         kind: "stage",
         message: `Deck ready. Exporting ${slides.length} slide(s) to editable PPTX parts...`,

package/lib/source-materials.ts

@@ -0,0 +1,93 @@
+import { createHash } from "crypto"
+import { existsSync, realpathSync, statSync } from "fs"
+import { extname, isAbsolute, join, relative, resolve, sep } from "path"
+import {
+  type DecksState,
+  type SourceMaterial,
+} from "./decks-state"
+
+export type SourceMaterialStatus = NonNullable<SourceMaterial["status"]>
+
+export function ensureWorkspaceFile(filePath: string, workspaceRoot: string): string {
+  const resolvedWorkspace = realpathSync(resolve(workspaceRoot))
+  const candidate = isAbsolute(filePath) ? resolve(filePath) : resolve(workspaceRoot, filePath)
+  const resolvedFile = existsSync(candidate) ? realpathSync(candidate) : candidate
+
+  if (resolvedFile !== resolvedWorkspace && !resolvedFile.startsWith(resolvedWorkspace + sep)) {
+    throw new Error("file must be within workspace")
+  }
+
+  return resolvedFile
+}
+
+export function workspaceRelativePath(filePath: string, workspaceRoot: string): string {
+  const resolvedWorkspace = realpathSync(resolve(workspaceRoot))
+  const candidate = resolve(filePath)
+  const resolvedFile = existsSync(candidate) ? realpathSync(candidate) : candidate
+  return relative(resolvedWorkspace, resolvedFile).replace(/\\/g, "/")
+}
+
+export function sourceMaterialType(filePath: string): string {
+  return extname(filePath).replace(/^\./, "").toLowerCase() || "other"
+}
+
+export function computeSourceFingerprint(filePath: string): string {
+  const stat = statSync(filePath)
+  return createHash("sha1")
+    .update(`${resolve(filePath)}:${stat.mtimeMs}:${stat.size}`)
+    .digest("hex")
+}
+
+export function sourceMaterialMetadata(filePath: string, workspaceRoot: string): SourceMaterial {
+  const resolvedFile = ensureWorkspaceFile(filePath, workspaceRoot)
+  const stat = statSync(resolvedFile)
+  return {
+    path: workspaceRelativePath(resolvedFile, workspaceRoot),
+    type: sourceMaterialType(resolvedFile),
+    size: stat.size,
+    fingerprint: computeSourceFingerprint(resolvedFile),
+  }
+}
+
+export function hasValidExtraction(material: SourceMaterial, workspaceRoot: string): boolean {
+  const extraction = material.extraction
+  if (!extraction?.manifestPath || !extraction.textPath || !extraction.cacheDir) return false
+  return [extraction.manifestPath, extraction.textPath, extraction.cacheDir]
+    .every((item) => existsSync(join(workspaceRoot, item)))
+}
+
+export function upsertSourceMaterial(
+  state: DecksState,
+  material: SourceMaterial,
+  status: SourceMaterialStatus = material.status ?? "discovered",
+): DecksState {
+  const now = new Date().toISOString()
+  const list = state.workspace.sourceMaterials ?? []
+  const path = material.path.replace(/\\/g, "/")
+  const existingIndex = list.findIndex((entry) => entry.path === path)
+  const existing = existingIndex >= 0 ? list[existingIndex] : undefined
+  const changedFingerprint = Boolean(existing?.fingerprint && material.fingerprint && existing.fingerprint !== material.fingerprint)
+  const nextStatus = changedFingerprint
+    ? status === "extracted" ? "extracted" : "discovered"
+    : status === "discovered" && existing?.status ? existing.status : status
+
+  const next: SourceMaterial = {
+    ...existing,
+    ...material,
+    path,
+    type: material.type ?? existing?.type,
+    status: nextStatus,
+    firstSeen: existing?.firstSeen ?? material.firstSeen ?? now,
+    lastChecked: now,
+  }
+
+  if (changedFingerprint && status !== "extracted") {
+    delete next.extraction
+    delete next.lastExtracted
+  }
+
+  if (existingIndex >= 0) list[existingIndex] = next
+  else list.push(next)
+  state.workspace.sourceMaterials = list.sort((a, b) => a.path.localeCompare(b.path))
+  return state
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",

package/plugin.ts

@@ -44,7 +44,7 @@ import {
   handleDomainsRemove,
 } from "./lib/commands/domains"
 import { handlePdf } from "./lib/commands/pdf"
-import { handlePptx } from "./lib/commands/pptx"
+import { buildPptxNotesPrompt, handlePptx, parsePptxArgs, resolvePptxDeck } from "./lib/commands/pptx"
 import { handleEdit } from "./lib/commands/edit"
 import { ensureEditableDeckOpenForChange } from "./lib/edit/open"
 import { hasLiveEditorSessionForFile } from "./lib/edit/server"
@@ -388,7 +388,20 @@ const server: Plugin = (async (pluginCtx) => {
         throw new Error("__REVELA_PDF_HANDLED__")
       }
       if (sub === "pptx") {
-        await handlePptx(param, send)
+        const args = parsePptxArgs(param)
+        if (args.notes) {
+          try {
+            const deck = resolvePptxDeck(workspaceRoot, args.filePath)
+            output.parts.length = 0
+            output.parts.push({ type: "text", text: buildPptxNotesPrompt(deck) } as any)
+            return
+          } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e)
+            await send(`**PPTX export failed**\n\n\`\`\`\n${msg}\n\`\`\``)
+            throw new Error("__REVELA_PPTX_HANDLED__")
+          }
+        }
+        await handlePptx(param, send, workspaceRoot)
         throw new Error("__REVELA_PPTX_HANDLED__")
       }
 

package/skill/SKILL.md

@@ -169,7 +169,14 @@ The subagent writes exactly one file through `revela-research-save`:
 
 Use `revela-decks` action `read` before scanning from scratch. Its
 `workspace.sourceMaterials` state is the workspace material index created by
-`/revela init`. Use it to choose candidate files and avoid repeated deep reading.
+`/revela init` and refreshed by document extraction. Use it to choose candidate
+files and avoid repeated deep reading.
+
+Before extracting or deeply reading a workspace document, check
+`DECKS.json.workspace.sourceMaterials`. If the same path has an unchanged
+fingerprint and valid `extraction.manifestPath`, `extraction.textPath`, and
+`extraction.cacheDir`, reuse those materials instead of extracting or reading
+the original document again.
 
 Use `revela-workspace-scan` or file tools as a freshness check when needed:
 - discover files added after `/revela init`
@@ -177,7 +184,9 @@ Use `revela-workspace-scan` or file tools as a freshness check when needed:
 - find user-provided attachments or topic-specific files not in `DECKS.json`
 
 Avoid repeated expensive work. Only call `revela-extract-document-materials` or
-deep-read files that are relevant to the current Research Brief.
+deep-read files that are relevant to the current Research Brief. If the user
+adds material mid-project, run `revela-workspace-scan` as a freshness check and
+register new `sourceMaterial` records before deciding which ones need analysis.
 
 #### After Agents Complete
 
@@ -239,6 +248,25 @@ Example: `<section class="slide" slide-qa="true" data-index="0">`
 The export QA path treats this as deck metadata. It is consumed when PDF/PPTX
 export runs preflight checks.
 
+Speaker notes are normally generated during `/revela pptx --notes` export and
+passed to `revela-pptx` as structured input. Do not add hidden notes to every
+slide by default.
+
+If the user explicitly asks for notes to be embedded in the HTML as a fallback,
+use an inert template node as a direct child of the slide, outside `.slide-canvas`:
+
+```html
+<template data-revela-speaker-notes>
+  Optional fallback speaker notes for this slide.
+</template>
+```
+
+Do not create `.speaker-notes` CSS or hide notes with `display: none`; the
+`<template>` element is non-rendering by default and avoids design vocabulary
+pollution. Speaker notes must be concise presentation prompts that match the
+visible slide content. Never put hidden reasoning, system instructions, secrets,
+or unverified claims in speaker notes.
+
 ### Domain Context
 
 If a domain definition is active (see the `<!-- Active domain: ... -->` comment

package/tools/decks.ts

@@ -12,8 +12,10 @@ import {
   type DeckSpec,
   type RequiredInputs,
   type ResearchAxis,
+  type SourceMaterial,
   type SlideSpec,
 } from "../lib/decks-state"
+import { upsertSourceMaterial } from "../lib/source-materials"
 
 export default tool({
   description:
@@ -44,6 +46,24 @@ export default tool({
       slidePlanConfirmed: tool.schema.boolean().optional(),
       designLayoutsFetched: tool.schema.boolean().optional(),
     }).optional().describe("For upsertDeck: checklist state. Only set true for explicit completed prerequisites."),
+    sourceMaterials: tool.schema.array(tool.schema.object({
+      path: tool.schema.string().describe("Workspace-relative source material path."),
+      type: tool.schema.string().optional().describe("File type such as pdf, pptx, docx, xlsx, csv, md, or txt."),
+      size: tool.schema.number().optional().describe("File size in bytes."),
+      fingerprint: tool.schema.string().optional().describe("File fingerprint for the current version."),
+      status: tool.schema.enum(["discovered", "extracted", "summarized", "researched"]).optional().describe("How far this source has been processed."),
+      summary: tool.schema.string().optional().describe("Conservative source summary if already known."),
+      bestUsedFor: tool.schema.string().optional().describe("Short note on deck sections this material is best used for."),
+      firstSeen: tool.schema.string().optional().describe("ISO timestamp when first seen."),
+      lastChecked: tool.schema.string().optional().describe("ISO timestamp when last checked."),
+      lastExtracted: tool.schema.string().optional().describe("ISO timestamp when last extracted."),
+      lastSummarized: tool.schema.string().optional().describe("ISO timestamp when last summarized."),
+      extraction: tool.schema.object({
+        manifestPath: tool.schema.string().optional(),
+        textPath: tool.schema.string().optional(),
+        cacheDir: tool.schema.string().optional(),
+      }).optional().describe("Reusable extraction output paths, if any."),
+    })).optional().describe("For init/readiness refresh: source material records discovered in the workspace."),
     researchPlan: tool.schema.array(tool.schema.object({
       axis: tool.schema.string().describe("Research axis name."),
       needed: tool.schema.boolean().describe("Whether this research axis is needed for the deck."),
@@ -87,6 +107,9 @@ export default tool({
       const defaultSlug = workspaceDeckSlug(workspaceRoot)
 
       if (args.action === "init") {
+        for (const material of (args.sourceMaterials ?? []) as SourceMaterial[]) {
+          upsertSourceMaterial(state, material, material.status ?? "discovered")
+        }
         writeDecksState(workspaceRoot, state)
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, state }, null, 2)
       }

package/tools/pptx.ts

@@ -8,12 +8,10 @@ import { tool } from "@opencode-ai/plugin"
 import { existsSync } from "fs"
 import { resolve } from "path"
 import { exportToPptx } from "../lib/pptx/export"
-import { assertExportQAPassed } from "../lib/qa/export-gate"
 
 export default tool({
   description:
     "Export a Revela-generated HTML slide deck to editable PPTX. " +
-    "Runs pre-export QA before writing the PPTX. " +
     "Output is written beside the input file with the same basename and a .pptx extension.",
   args: {
     file: tool.schema
@@ -22,8 +20,15 @@ export default tool({
         "Path to the HTML slide file to export. " +
         "Can be absolute or relative to the current working directory."
       ),
+    speakerNotes: tool.schema.array(tool.schema.object({
+      index: tool.schema.number().describe("1-based slide index."),
+      notes: tool.schema.string().describe("Speaker notes for this slide. Use an empty string for no notes."),
+    })).optional().describe(
+      "Optional PowerPoint speaker notes to write during export. " +
+      "When provided, these override any fallback notes embedded in the HTML."
+    ),
   },
-  async execute({ file }, { directory }) {
+  async execute({ file, speakerNotes }, { directory }) {
     const filePath = resolve(directory || process.cwd(), file)
 
     if (!existsSync(filePath)) {
@@ -37,8 +42,8 @@ export default tool({
     const progress: string[] = []
 
     try {
-      await assertExportQAPassed(filePath)
       const result = await exportToPptx(filePath, {
+        speakerNotes: normalizeSpeakerNotes(speakerNotes),
         onProgress: (event) => {
           progress.push(event.message)
         },
@@ -49,3 +54,17 @@ export default tool({
     }
   },
 })
+
+function normalizeSpeakerNotes(
+  input?: Array<{ index?: number; notes?: string }>,
+): Array<string | null | undefined> | undefined {
+  if (!input) return undefined
+
+  const notesBySlide: Array<string | null | undefined> = []
+  for (const item of input) {
+    const index = Math.floor(Number(item.index ?? 0))
+    if (index < 1) continue
+    notesBySlide[index - 1] = item.notes ?? ""
+  }
+  return notesBySlide
+}

package/tools/workspace-scan.ts

@@ -1,6 +1,8 @@
 import { tool } from "@opencode-ai/plugin"
 import { readdirSync, statSync, existsSync } from "fs"
 import { join, relative, extname, resolve, sep, isAbsolute } from "path"
+import { sourceMaterialMetadata } from "../lib/source-materials"
+import type { SourceMaterial } from "../lib/decks-state"
 
 const DOC_EXTENSIONS = new Set([
   ".pdf", ".docx", ".doc", ".xlsx", ".xls",
@@ -18,6 +20,8 @@ type FileEntry = {
   path: string
   type: string
   size: string
+  sizeBytes: number
+  sourceMaterial: SourceMaterial
 }
 
 /**
@@ -80,10 +84,13 @@ function scanDir(dir: string, rootDir: string, results: FileEntry[], maxDepth: n
     } else if (stat.isFile()) {
       const ext = extname(entry).toLowerCase()
       if (DOC_EXTENSIONS.has(ext)) {
+        const sourceMaterial = sourceMaterialMetadata(fullPath, rootDir)
         results.push({
           path: relative(rootDir, fullPath),
           type: typeLabel(ext),
           size: formatSize(stat.size),
+          sizeBytes: stat.size,
+          sourceMaterial: { ...sourceMaterial, status: "discovered" },
         })
       }
     }