@cyber-dash-tech/revela 0.8.5 → 0.8.7

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

@@ -18,6 +18,7 @@ Goal:
 - Preserve the deck spec for future sessions: every slide's content, layout, components, evidence, visuals, and production status.
 - Do not write, patch, or directly edit ${DECKS_STATE_FILE}. Use the \`revela-decks\` tool for all state changes.
 - Let \`revela-decks\` action \`review\` compute writeReadiness; do not manually set readiness to ready.
+- Treat this as an evidence-readiness review, not only a checklist review: unsupported numbers, market sizing, recommendations, competitor comparisons, technical assertions, or investment conclusions should be made visible before writing.
 
 Current state:
 - ${state}
@@ -34,8 +35,8 @@ Workflow:
 2. If no current deck exists but the conversation contains enough deck context, call \`revela-decks\` action \`upsertDeck\` with goal, outputPath, theme, requiredInputs, and researchPlan. Do not invent or ask for a deck key; the tool uses the workspace folder name internally.
 3. If a user-confirmed slide plan is available, call \`revela-decks\` action \`upsertSlides\` with every slide's title, purpose, layout, components, structured content, evidence, visuals, and status.
 4. Only set requiredInputs fields true when explicit conversation state, files read, research findings read, selected design, fetched layouts/components, or user confirmation supports them. Do not infer completion.
-5. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` for the current workspace deck.
-6. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool.
+5. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` plus structured readiness issues for the current workspace deck.
+6. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool. If warnings exist, list them after blockers as residual risks.
 
 Minimum conditions for \`ready\`:
 - Topic, audience, slide count, language, and visual style/design are decided.
@@ -44,9 +45,16 @@ Minimum conditions for \`ready\`:
 - If research is needed, all relevant findings have been read and reflected in the slide specs.
 - The user has confirmed the slide plan.
 - ${DECKS_STATE_FILE} contains per-slide specs with content, layout, components, and evidence where applicable.
+- Evidence-sensitive slide claims have compact evidence references. Numeric claims and strong recommendations should not be unsupported.
 - The needed design layouts and components have been fetched with \`revela-designs read\`.
 - No unresolved blockers remain.
 
+Report format:
+- Start with \`Ready: yes/no\`.
+- If blocked, list each blocker with slide index/title when the tool provides it, the issue type, and the suggested next action.
+- If warnings exist but the deck is otherwise ready, say the deck can be written but note the residual risks.
+- Do not invent evidence or silently downgrade blockers. Use the tool result as authoritative.
+
 Rules:
 - Do not write or overwrite \`decks/*.html\` during review.
 - Treat the workspace as one deck project. If the user wants another deck, tell them to use a separate workspace/folder.

package/lib/decks-state.ts

@@ -140,6 +140,28 @@ export interface DeckStateReadinessResult {
   status?: WriteReadinessStatus
   blocker: string
   blockers: string[]
+  warnings: string[]
+  issues: ReadinessIssue[]
+}
+
+export type ReadinessSeverity = "blocker" | "warning"
+
+export type ReadinessIssueType =
+  | "missing_required_input"
+  | "missing_slide_spec"
+  | "research_not_ready"
+  | "missing_evidence"
+  | "weak_evidence"
+  | "source_not_processed"
+
+export interface ReadinessIssue {
+  type: ReadinessIssueType
+  severity: ReadinessSeverity
+  message: string
+  suggestedAction: string
+  slideIndex?: number
+  slideTitle?: string
+  claimText?: string
 }
 
 export function decksStatePath(workspaceRoot: string): string {
@@ -279,11 +301,20 @@ export function reviewDeckState(state: DecksState, slug?: string): { state: Deck
         slug: missing,
         blocker: `Deck ${missing} does not exist in ${DECKS_STATE_FILE}.`,
         blockers: [`Deck ${missing} does not exist in ${DECKS_STATE_FILE}.`],
+        warnings: [],
+        issues: [{
+          type: "missing_slide_spec",
+          severity: "blocker",
+          message: `Deck ${missing} does not exist in ${DECKS_STATE_FILE}.`,
+          suggestedAction: "Create the current workspace deck spec with revela-decks upsertDeck before reviewing readiness.",
+        }],
       },
     }
   }
 
-  const blockers = computeDeckBlockers(deck)
+  const issues = computeDeckReadinessIssues(deck, normalized.workspace)
+  const blockers = issues.filter((issue) => issue.severity === "blocker").map((issue) => issue.message)
+  const warnings = issues.filter((issue) => issue.severity === "warning").map((issue) => issue.message)
   deck.writeReadiness = {
     status: blockers.length === 0 ? "ready" : "blocked",
     blockers,
@@ -300,6 +331,8 @@ export function reviewDeckState(state: DecksState, slug?: string): { state: Deck
       status: deck.writeReadiness.status,
       blocker: blockers.join("; "),
       blockers,
+      warnings,
+      issues,
     },
   }
 }
@@ -321,18 +354,48 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
       slug: targetSlug,
       blocker: currentDeckBlocker(normalized),
       blockers: [currentDeckBlocker(normalized)],
+      warnings: [],
+      issues: [{
+        type: "missing_slide_spec",
+        severity: "blocker",
+        message: currentDeckBlocker(normalized),
+        suggestedAction: "Create or select the current workspace deck through revela-decks before writing deck HTML.",
+      }],
     }
   }
 
-  const blockers = computeDeckBlockers(deck)
+  const issues = computeDeckReadinessIssues(deck, normalized.workspace)
+  const blockers = issues.filter((issue) => issue.severity === "blocker").map((issue) => issue.message)
+  const warnings = issues.filter((issue) => issue.severity === "warning").map((issue) => issue.message)
   if (normalizeDeckPath(deck.outputPath) !== targetPath) {
-    blockers.unshift(`Deck outputPath is ${deck.outputPath || "missing"}, not ${targetPath}`)
+    const message = `Deck outputPath is ${deck.outputPath || "missing"}, not ${targetPath}`
+    blockers.unshift(message)
+    issues.unshift({
+      type: "missing_slide_spec",
+      severity: "blocker",
+      message,
+      suggestedAction: "Update deck.outputPath through revela-decks or write to the reviewed outputPath.",
+    })
   }
   if (deck.writeReadiness.status !== "ready") {
-    blockers.unshift(`Deck writeReadiness is ${deck.writeReadiness.status || "missing"}, not ready`)
+    const message = `Deck writeReadiness is ${deck.writeReadiness.status || "missing"}, not ready`
+    blockers.unshift(message)
+    issues.unshift({
+      type: "missing_slide_spec",
+      severity: "blocker",
+      message,
+      suggestedAction: "Run /revela review and resolve all readiness blockers before writing deck HTML.",
+    })
   }
   if (deck.writeReadiness.blockers.length > 0) {
-    blockers.unshift(`Deck still has readiness blockers: ${deck.writeReadiness.blockers.join("; ")}`)
+    const message = `Deck still has readiness blockers: ${deck.writeReadiness.blockers.join("; ")}`
+    blockers.unshift(message)
+    issues.unshift({
+      type: "missing_slide_spec",
+      severity: "blocker",
+      message,
+      suggestedAction: "Resolve the stored writeReadiness blockers and rerun /revela review.",
+    })
   }
 
   return {
@@ -341,6 +404,8 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
     status: deck.writeReadiness.status,
     blocker: blockers.join("; "),
     blockers,
+    warnings,
+    issues,
   }
 }
 
@@ -416,30 +481,161 @@ function currentDeckBlocker(state: DecksState): string {
   return `${DECKS_STATE_FILE} contains multiple deck records and no activeDeck. Select one current deck explicitly or move extra decks to separate workspaces.`
 }
 
-function computeDeckBlockers(deck: DeckSpec): string[] {
-  const blockers: string[] = []
-  if (!deck.goal.trim()) blockers.push("Deck goal is missing")
-  if (!isDeckHtmlPath(deck.outputPath)) blockers.push(`outputPath must be decks/*.html, got ${deck.outputPath || "missing"}`)
+function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["workspace"]): ReadinessIssue[] {
+  const issues: ReadinessIssue[] = []
+  if (!deck.goal.trim()) issues.push(blockerIssue("missing_slide_spec", "Deck goal is missing", "Set the deck goal through revela-decks upsertDeck."))
+  if (!isDeckHtmlPath(deck.outputPath)) {
+    issues.push(blockerIssue(
+      "missing_slide_spec",
+      `outputPath must be decks/*.html, got ${deck.outputPath || "missing"}`,
+      "Set outputPath to the target decks/*.html file through revela-decks upsertDeck.",
+    ))
+  }
 
   for (const [key, value] of Object.entries(deck.requiredInputs) as Array<[keyof RequiredInputs, boolean]>) {
-    if (value !== true) blockers.push(`requiredInputs.${key} is not true`)
+    if (value !== true) {
+      issues.push(blockerIssue(
+        "missing_required_input",
+        `requiredInputs.${key} is not true`,
+        `Complete and explicitly record requiredInputs.${key} before writing the deck.`,
+      ))
+    }
   }
 
-  if (deck.slides.length === 0) blockers.push("slides are missing")
+  if (deck.slides.length === 0) issues.push(blockerIssue("missing_slide_spec", "slides are missing", "Add the confirmed slide plan through revela-decks upsertSlides."))
   for (const slide of deck.slides) {
-    if (!slide.title.trim()) blockers.push(`Slide ${slide.index} title is missing`)
-    if (!slide.layout.trim()) blockers.push(`Slide ${slide.index} layout is missing`)
-    if (slide.components.length === 0) blockers.push(`Slide ${slide.index} components are missing`)
-    if (!hasSlideContent(slide)) blockers.push(`Slide ${slide.index} content is missing`)
+    const slideRef = { slideIndex: slide.index, slideTitle: slide.title }
+    if (!slide.title.trim()) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} title is missing`, "Add a slide title to the slide spec.", slideRef))
+    if (!slide.layout.trim()) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} layout is missing`, "Fetch and record the intended design layout for this slide.", slideRef))
+    if (slide.components.length === 0) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} components are missing`, "Record the design components needed for this slide.", slideRef))
+    if (!hasSlideContent(slide)) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} content is missing`, "Add structured headline/body/bullets/data content to the slide spec.", slideRef))
+
+    const claim = findEvidenceSensitiveClaim(slide)
+    if (claim && slide.evidence.length === 0) {
+      issues.push(blockerIssue(
+        "missing_evidence",
+        `Slide ${slide.index} has an evidence-sensitive claim without evidence: ${claim}`,
+        "Add a compact evidence reference to slides[].evidence or reframe the claim as an explicit assumption/opinion.",
+        { ...slideRef, claimText: claim },
+      ))
+    } else if (claim && slide.evidence.some((item) => !hasEvidenceDetail(item))) {
+      issues.push(warningIssue(
+        "weak_evidence",
+        `Slide ${slide.index} evidence for a high-risk claim has no quote, page, or URL detail: ${claim}`,
+        "Add quote/page/url details where available so the writing agent can ground the slide more reliably.",
+        { ...slideRef, claimText: claim },
+      ))
+    }
   }
 
   for (const axis of deck.researchPlan) {
     if (axis.needed && axis.status !== "done" && axis.status !== "read" && axis.status !== "skipped") {
-      blockers.push(`Research axis ${axis.axis || "unnamed"} is needed but ${axis.status}`)
+      issues.push(blockerIssue(
+        "research_not_ready",
+        `Research axis ${axis.axis || "unnamed"} is needed but ${axis.status}`,
+        "Complete, read, or explicitly skip this research axis before writing the deck.",
+      ))
     }
   }
-  return blockers
-}
+
+  const hasNeededResearch = deck.researchPlan.some((axis) => axis.needed && axis.status !== "skipped")
+  for (const material of workspace.sourceMaterials ?? []) {
+    if (material.status !== "discovered") continue
+    const message = `Source material ${material.path} has been identified but not extracted, summarized, or researched`
+    if (hasNeededResearch) {
+      issues.push(blockerIssue(
+        "source_not_processed",
+        message,
+        "Extract, summarize, research, or explicitly exclude this source before writing evidence-backed slides.",
+      ))
+    } else {
+      issues.push(warningIssue(
+        "source_not_processed",
+        message,
+        "Consider extracting or excluding this source if it may support the deck narrative.",
+      ))
+    }
+  }
+
+  return issues
+}
+
+function blockerIssue(type: ReadinessIssueType, message: string, suggestedAction: string, extra: Partial<ReadinessIssue> = {}): ReadinessIssue {
+  return { type, severity: "blocker", message, suggestedAction, ...extra }
+}
+
+function warningIssue(type: ReadinessIssueType, message: string, suggestedAction: string, extra: Partial<ReadinessIssue> = {}): ReadinessIssue {
+  return { type, severity: "warning", message, suggestedAction, ...extra }
+}
+
+function findEvidenceSensitiveClaim(slide: SlideSpec): string | undefined {
+  const candidates = [
+    slide.title,
+    slide.purpose,
+    slide.content?.headline,
+    ...(slide.content?.body ?? []),
+    ...(slide.content?.bullets ?? []),
+  ]
+    .map((item) => item?.trim())
+    .filter((item): item is string => Boolean(item))
+
+  return candidates.find(isEvidenceSensitiveClaim)
+}
+
+function isEvidenceSensitiveClaim(text: string): boolean {
+  const normalized = text.toLowerCase()
+  return hasNumericClaim(normalized) || EVIDENCE_SENSITIVE_TERMS.some((pattern) => pattern.test(normalized))
+}
+
+function hasNumericClaim(text: string): boolean {
+  return /(?:[$¥€£]\s?\d|\d+(?:\.\d+)?\s?(?:%|x|倍|万|亿|m|mn|million|b|bn|billion|k|千|年|months?|days?|users?|customers?|revenue|margin|cagr|tam|sam|som)\b|\b20\d{2}\b)/i.test(text)
+}
+
+function hasEvidenceDetail(evidence: EvidenceRef): boolean {
+  return Boolean(evidence.quote?.trim() || evidence.page?.trim() || evidence.url?.trim())
+}
+
+const EVIDENCE_SENSITIVE_TERMS = [
+  /\bmarket size\b/,
+  /\bcagr\b/,
+  /\btam\b/,
+  /\bsam\b/,
+  /\bsom\b/,
+  /\brecommend(?:ation|ed)?\b/,
+  /\bshould\b/,
+  /\bmust\b/,
+  /\bgo\/?no-go\b/,
+  /\bvs\.?\b/,
+  /\bbetter than\b/,
+  /\boutperform\b/,
+  /\bleading\b/,
+  /\bcompetitor\b/,
+  /\bmarket leader\b/,
+  /\binvest(?:ment)?\b/,
+  /\brevenue\b/,
+  /\bmargin\b/,
+  /\bcost\b/,
+  /\brisk\b/,
+  /\blatency\b/,
+  /\baccuracy\b/,
+  /\bscalable\b/,
+  /\barchitecture\b/,
+  /市场规模/,
+  /增长/,
+  /领先/,
+  /超过/,
+  /竞品/,
+  /建议/,
+  /必须/,
+  /投资/,
+  /收入/,
+  /利润/,
+  /成本/,
+  /风险/,
+  /性能/,
+  /架构/,
+  /可扩展/,
+]
 
 function normalizeSlides(slides: SlideSpec[]): SlideSpec[] {
   return slides

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

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

@@ -248,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/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
+}