@cyber-dash-tech/revela 0.18.2 → 0.18.3

package/README.md

@@ -34,7 +34,7 @@ To install globally, add the same entry to `~/.config/opencode/opencode.json`.
 Requirements:
 
 - The Codex CLI must be installed and the `codex` command must be available in your shell.
-- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.18.2 mcp` to start the MCP server.
+- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.18.3 mcp` to start the MCP server.
 - For interactive Review actions, `codex exec` must also work because the Review UI uses it for Comment/Apply Fix requests.
 
 Optional preflight:
@@ -55,11 +55,11 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 Install Revela through the Codex Git marketplace:
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.2
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.3
 codex plugin add revela@revela
 ```
 
-The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.18.2 mcp` so npm can fetch the published package and its dependencies.
+The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.18.3 mcp` so npm can fetch the published package and its dependencies.
 
 You do not need to run `bun install` inside the Codex marketplace clone.
 
@@ -169,7 +169,7 @@ revela, help me init this workspace from the local materials.
 revela, research the public evidence and examples needed for this deck.
 ```
 
-6. Create or update the deck plan before generating HTML so slide order, chapter structure, source links, caveats, and visual intent are explicit.
+6. Create or update the deck plan before generating HTML so slide order, chapter structure, source links, unresolved inputs, source limitations, and visual intent are explicit.
 
 ```text
 revela, create or update the deck plan before generating HTML.

package/README.zh-CN.md

@@ -34,7 +34,7 @@ Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材
 环境要求：
 
 - 需要已安装 Codex CLI，并且 shell 中可以执行 `codex`。
-- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.2 mcp` 启动 MCP server。
+- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.3 mcp` 启动 MCP server。
 - 如果使用 Review UI 的 Comment 或 Apply Fix，需要 `codex exec` 可用。
 
 可选的安装前检查：
@@ -55,11 +55,11 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 通过 Codex Git marketplace 安装 Revela：
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.2
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.3
 codex plugin add revela@revela
 ```
 
-Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.2 mcp`，由 npm 获取已发布 package 及其 dependencies。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.3 mcp`，由 npm 获取已发布 package 及其 dependencies。
 
 不需要在 Codex marketplace clone 里运行 `bun install`。
 
@@ -169,7 +169,7 @@ revela，帮我 init 这个 workspace，先读本地材料。
 revela，research 这个 deck 需要的公开证据、案例和 source。
 ```
 
-6. 先创建或更新 deck plan，明确 slide 顺序、章节结构、source links、caveats 和 visual intent，再生成 HTML。
+6. 先创建或更新 deck plan，明确 slide 顺序、章节结构、source links、unresolved inputs、source limitations 和 visual intent，再生成 HTML。
 
 ```text
 revela，生成 HTML 前先 create or update deck plan。

package/lib/commands/review.ts

@@ -45,7 +45,7 @@ Report format:
 - Start with \`Narrative readiness: <status>\`.
 - Include \`Narrative hash: <hash>\` when returned.
 - List diagnostics with issue type, claim text when available, and suggested next action. Keep Markdown QA repair cards separate from compiler diagnostics.
-- If warnings exist, list them after blockers as residual risks.
+- If warnings exist, list them after blockers as residual diagnostics.
 - Keep deck/artifact readiness separate. If the user wants to write or review deck artifacts, tell them to run \`/revela make --deck\`.
 
 Rules:
@@ -74,8 +74,8 @@ export function buildDeckPlanPrompt({
 Goal:
 - Build canonical deck-plan.md directly from the user's goal, reviewed local materials, saved research findings, and active design vocabulary.
 - Do not create, read, repair, or require revela-narrative/.
-- Use sourceLinks in deck-plan.md to reference material paths, material review files, research findings, asset paths, URLs, and caveats. These are source links, not narrative graph links.
-- Use "unresolved inputs", "research tasks", "source limitations", or "caveats"; do not use the product concept of research gaps.
+- Use sourceLinks in deck-plan.md to reference material paths, material review files, research findings, asset paths, and URLs. These are source links, not narrative graph links.
+- Use "unresolved inputs", "research tasks", "source limitations", or "user review notes"; do not use the product concept of research gaps.
 - Do not write HTML during planning.
 
 Current state:
@@ -88,7 +88,7 @@ Workflow:
 3. Ask only for missing high-impact intent: audience, objective, decision/action, language, rough slide count, or source priority.
 4. Read active design inventory/rules before selecting layouts/components.
 5. Write deck-plan.md with deck objective, audience, output format, chapter outline, source authority, unresolved inputs, and an ordered slide plan.
-6. For every slide block, include positive 1-based slideIndex, title, chapter, purpose, layout, component plan, visual intent, sourceLinks, caveats, and speaker/content notes.
+6. For every slide block, use a \`---\` slide separator with slide-local metadata, then include \`#### Content Plan\`, \`#### Source Links\`, and \`#### Design Plan\`.
 7. Include Cover, Table of Contents, and Closing slides unless the user explicitly asks for a non-standard artifact.
 8. Run/read deck-plan diagnostics after writing and report technical issues separately from source limitations.
 
@@ -115,7 +115,7 @@ Goal:
 - Read the current deck-plan.md projection and generate or update decks/*.html.
 - Do not create, compile, or require revela-narrative/.
 - Use the deck-render prompt mode for design, layout, components, HTML, QA, and export preflight.
-- Preserve source links and caveats from deck-plan in slide source notes or speaker notes where appropriate.
+- Preserve source links, unresolved inputs, source limitations, and user review notes from deck-plan in slide source notes or speaker notes where appropriate.
 
 Current state:
 - ${state}
@@ -126,7 +126,7 @@ Workflow:
 2. If deck-plan.md is missing or structurally invalid, stop and tell the user to run /revela plan --deck.
 3. For a new deck, call revela-deck-foundation before adding slide content.
 4. Read active design rules and needed layouts/components before patching HTML.
-5. Generate chapter by chapter. Keep the HTML valid after every write and preserve existing completed slides.
+5. Generate one \`htmlWritingBatches\` entry at a time. Each HTML write/edit/apply_patch may add or rewrite at most 5 slide sections. Keep the HTML valid after every write and preserve existing completed slides.
 6. Each slide must have unique increasing 1-based data-slide-index, a 1920x1080 .slide-canvas, no text overflow, and no unsafe remote asset references.
 7. Run Artifact QA after writes and fix hard errors before reporting ready.
 
@@ -152,7 +152,7 @@ export function buildDeckPrompt({
 Goal:
 - Treat this as the explicit transition from canonical narrative state to user-directed deck planning.
 - Use the deck-render prompt mode for design, layout, component, HTML, QA, and deck artifact rules.
-- Default behavior is two-stage: first generate or update \`deck-plan.md\` with ordered slide blocks, low-fidelity layout notes, sourceLinks, and caveats, then proceed only when the user chooses to continue.
+- Default behavior is two-stage: first generate or update \`deck-plan.md\` with ordered \`---\` slide blocks, low-fidelity layout notes, sourceLinks, unresolved inputs, source limitations, and user review notes, then proceed only when the user chooses to continue.
 - Every deck plan must include Cover, Table of Contents, and Closing slides. The TOC must show 3-5 chapter headings that match the deck's slide groups.
 - Do not write or overwrite \`decks/*.html\` until the user chooses to proceed from the current deck-plan projection.
 - Do not treat legacy \`writeReadiness.status\`, old review snapshots, approval fields, or existing HTML decks as workflow permission.
@@ -169,7 +169,7 @@ Workflow:
 4. Call \`revela-decks\` action \`compileDeckPlan\`. This returns a claim/evidence planning packet plus deck-plan authoring requirements; it must not write HTML and does not generate the final slide list. Do not infer render structure from \`DECKS.json.slides[]\`.
 5. If \`compileDeckPlan\` returns \`skipped\`, report the reason and ask the user whether to continue manually, repair narrative files, or provide missing intent.
 6. If target slide count, audience, language, output purpose, or visual style is unclear, ask the user for the smallest needed confirmation before writing the plan.
-7. Write \`deck-plan.md\` directly from the planning packet and requirements. Do not use structured upsert tools for normal plan authoring. It must identify the chapter structure first: 3-5 chapter headings, each chapter's slide range, and which non-structural slides belong to each chapter. Each slide block must include positive 1-based \`slideIndex\`, layout, component plan, \`sourceLinks\` for materials/findings/assets/URLs/caveats, and low-fidelity render notes. Do not generate visual images or HTML mockups during planning.
+7. Write \`deck-plan.md\` directly from the planning packet and requirements. Do not use structured upsert tools for normal plan authoring. It must identify the chapter structure first: 3-5 chapter headings, each chapter's slide range, and which non-structural slides belong to each chapter. Each slide block must use a \`---\` separator with positive 1-based \`slideIndex\`, layout, components, and then \`#### Content Plan\`, \`#### Source Links\` for materials/findings/assets/URLs, and \`#### Design Plan\` with low-fidelity render notes. Do not generate visual images or HTML mockups during planning.
 8. Stop after presenting the plan unless the user already asked to proceed. Ask whether to continue, revise the plan, or run more research. Do not require an Approval block or \`confirmDeckPlan\` gate; \`confirmDeckPlan\` is compatibility/provenance only.
 9. Ask for or confirm visual design only after the narrative deck plan exists. For a new deck HTML file, call \`revela-deck-foundation\` first to create the active-design foundation shell; it must not create narrative slide content, choose layouts/components, or read/write \`${DECKS_STATE_FILE}\`.
 10. Fetch active design rules plus required layouts/components with \`revela-designs read\` as needed before patching slides into the foundation shell. Fetch chart rules before ECharts.
@@ -178,6 +178,7 @@ Workflow:
 13. Run artifact diagnostics when useful, but do not treat \`writeReadiness\`, cached slide specs, unconfirmed plans, missing research, or stale coverage as workflow blockers.
 14. Write \`decks/*.html\` when the user chooses to proceed and all deck HTML contract requirements can be satisfied. For new files, patch slide sections between the \`revela-slides\` markers created by \`revela-deck-foundation\`. Generate the artifact chapter by chapter instead of drafting all content slides in one broad pass. Partial decks are allowed during chapter-by-chapter authoring when written slide sections have unique, increasing 1-based \`data-slide-index\` values and valid canvases; do not pad missing planned chapters with filler to match cached \`DECKS.json.slides[]\` length. Keep the HTML file valid after every write, preserve already-written slides, and update one chapter's slide sections at a time.
 15. For each chapter, make every content slide carry a distinct claim, evidence item, comparison, risk, or action. If a chapter lacks enough substance for its allocated slides, merge weak slides or reduce the slide count instead of creating sparse filler.
+15a. Use the current \`htmlWritingBatches\` entry as the HTML write boundary. Each HTML write/edit/apply_patch may add or rewrite at most 5 slide sections.
 16. After each HTML write, the system automatically runs artifact QA before opening Review. If post-write artifact QA reports hard errors, fix them and let QA run again. Review opens only after hard errors pass. Density warnings about thin claim/evidence substance should be reported and improved when useful, but they do not block Review.
 
 Deck plan report format:
@@ -189,7 +190,7 @@ Deck plan report format:
 - Include the required Source Authority and remind that \`DECKS.json.slides[]\` is cache/compatibility data, not the render contract.
 - Include \`Required structure: Cover + Table of Contents + Closing\` and do not omit any of those slides.
 - Include a \`Chapters\` section before the slide list. It must list 3-5 TOC headings, their slide ranges, and the non-structural slides assigned to each chapter.
-- For every slide block, include: slide index, title, purpose, narrative role, low-fidelity layout note, layout, components, sourceLinks, visual intent, visual brief, caveats/unsupported scope, and render notes.
+- For every slide block, include: slide index, title, purpose, narrative role, low-fidelity layout note, layout, components, sourceLinks, visual intent, visual brief, unresolved inputs, source limitations, user review notes, and render notes.
 - Use this sketch style or similarly simple ASCII boxes:
 
 \`\`\`text
@@ -213,7 +214,7 @@ Supporting claims:
 Evidence bindings:
 Visual intent:
 Visual brief:
-Caveats / unsupported scope:
+Unresolved inputs / source limitations / user review notes:
 \`\`\`
 - End by asking the user whether to proceed to HTML, revise the plan, or run more research.
 
@@ -222,7 +223,7 @@ Report format before any HTML write:
 - Include which deck-plan projection and narrative hash are guiding artifact work.
 - State that \`revela-decks readDeckPlan\` was called and the current \`deck-plan.md\` slide order/chapter groups are being followed.
 - For new HTML files, state that \`revela-deck-foundation\` created the foundation shell and identify the output path/design before slide content is patched.
-- Include the chapter currently being generated and confirm already-written slides are being preserved.
+- Include the current \`htmlWritingBatches\` entry, its slide indexes, and confirm already-written slides are being preserved.
 - If technical artifact checks cannot be satisfied, list those blockers separately from narrative/deck-plan diagnostics.
 - After writing HTML, read the appended \`Artifact QA\` report from the tool output. If it failed, fix hard errors before considering the deck ready for Review.
 
@@ -233,7 +234,7 @@ Rules:
 - Visual intent is part of the deck-plan projection. During HTML generation, satisfy the planned component/visual brief using fetched design components; do not collapse planned visuals into prose-only bullets.
 - Cached deck slide specs in \`DECKS.json\` are legacy projections only. Canonical narrative remains the authority for audience, decision, claims, evidence boundaries, objections, and risks.
 - Cover, Table of Contents, and Closing are mandatory deck structure. TOC chapter headings must match the chapter grouping used for generation.
-- Do not generate the complete deck content in one broad pass. Work chapter by chapter while keeping the artifact valid after each write.
+- Do not generate the complete deck content in one broad pass. Work one \`htmlWritingBatches\` entry at a time while keeping the artifact valid after each write.
 - Applying evidence candidates or rewriting canonical claims requires explicit user instruction.
 - If the user requests slide order, layout, component, or visual-intent changes that do not alter meaning, update only \`deck-plan.md\` or artifact-level plan content.
 - If the user requests claim, evidence, caveat, decision, or recommendation meaning changes, update canonical narrative first, then report alignment diagnostics before compiling a new deck plan.
@@ -295,7 +296,7 @@ Technical blockers only:
 Report format:
 - Start with \`Artifact diagnostics: <status>\`.
 - If technically blocked, list each blocker with file/slide when available, issue type, and smallest repair.
-- If warnings exist but no technical blocker exists, say the user can proceed and note residual risks.
+- If warnings exist but no technical blocker exists, say the user can proceed and note residual diagnostics.
 - Include coverage-driven make diagnostics when returned: whether the active deck artifact coverage is current/stale/partial/missing, which required claims are missing, which claims are affected, and the next command/action recommended by the tool.
 - Report \`narrative_gap\` warnings as story-structure risks such as weak so-what, missing risk/assumption handling, conclusion before support, missing audience framing, or abrupt transition.
 - Do not invent evidence or silently downgrade blockers. Use the tool result as authoritative.

package/lib/narrative-state/deck-plan-artifact.ts

@@ -14,6 +14,7 @@ export const DECK_PLAN_INDEX_PATH = "deck-plan/index.md"
 export const DECK_PLAN_SLIDES_DIR = "deck-plan/slides"
 export const LEGACY_DECK_PLAN_ARTIFACT_PATH = "decks/deck-plan.md"
 export const DECK_PLAN_ARTIFACT_PATH = DECK_PLAN_MARKDOWN_PATH
+export const MAX_HTML_SLIDES_PER_BATCH = 5
 
 export interface DeckPlanArtifactInput {
   deck: DeckSpec
@@ -69,11 +70,21 @@ export interface DeckPlanProjection {
   designName?: string
   outputPath?: string
   slides: DeckPlanSlideProjection[]
+  htmlWritingBatches: DeckPlanHtmlWritingBatch[]
+  htmlWritingInstruction: string
   graphNodes: Array<{ id: string; type: WorkspaceGraphNodeType; file: string }>
   graphRelations: VaultRelation[]
   diagnostics: DeckPlanProjectionDiagnostic[]
 }
 
+export interface DeckPlanHtmlWritingBatch {
+  label: string
+  chapterTitle: string
+  slideIndexes: number[]
+  maxSlides: number
+  instructions: string
+}
+
 export interface DeckPlanSlideProjection {
   path: string
   absolutePath: string
@@ -283,6 +294,7 @@ export function readDeckPlanProjection(workspaceRoot: string, expected?: { narra
     file: slide.path,
     source: "inline" as const,
   })))
+  const htmlWritingBatches = buildHtmlWritingBatches(slides)
   return {
     path,
     absolutePath,
@@ -294,6 +306,8 @@ export function readDeckPlanProjection(workspaceRoot: string, expected?: { narra
     designName: stringField(parsed.frontmatter, "designName") || stringField(parsed.frontmatter, "design"),
     outputPath: stringField(parsed.frontmatter, "outputPath") || stringField(parsed.frontmatter, "output"),
     slides,
+    htmlWritingBatches,
+    htmlWritingInstruction: htmlWritingInstruction(),
     graphNodes,
     graphRelations,
     diagnostics,
@@ -470,31 +484,35 @@ function writeDeckPlanSingleFile(workspaceRoot: string, input: {
 
 function renderDeckPlanSlideBlock(slide: DeckPlanSlideProjection, visualIntent?: DeckPlanSlideUpsertInput["visualIntent"]): string {
   const lines: string[] = []
-  lines.push(`### Slide ${slide.slideIndex ?? "?"} — ${slide.title}`)
-  lines.push("")
-  lines.push(`- Id: ${slide.id}`)
-  lines.push(`- Chapter: ${slide.chapter || "Unassigned"}`)
-  lines.push(`- Role: ${slide.narrativeRole || "Not specified"}`)
-  lines.push(`- Structural: ${slide.structural ? "true" : "false"}`)
-  lines.push(`- Layout: ${slide.layout || "unspecified"}`)
-  lines.push(`- Components: ${slide.components.join(", ") || "none"}`)
-  lines.push("")
-  lines.push("#### Visual Intent")
+  lines.push("---")
+  lines.push(`slideIndex: ${slide.slideIndex ?? ""}`)
+  lines.push(`id: ${slide.id}`)
+  lines.push(`title: ${yamlScalar(slide.title)}`)
+  lines.push(`chapter: ${yamlScalar(slide.chapter || "Unassigned")}`)
+  lines.push(`role: ${yamlScalar(slide.narrativeRole || "Not specified")}`)
+  lines.push(`structural: ${slide.structural ? "true" : "false"}`)
+  lines.push(`layout: ${slide.layout || "unspecified"}`)
+  lines.push(`components: ${slide.components.join(", ") || "none"}`)
+  lines.push("---")
   lines.push("")
-  if (visualIntent) lines.push(renderVisualIntent(visualIntent))
-  else lines.push("- Brief: Not specified.")
+  lines.push("#### Content Plan")
   lines.push("")
-  lines.push("#### Component Plan")
+  lines.push(`- Message: ${slide.narrativeRole || "Not specified."}`)
+  lines.push(`- Role: ${slide.narrativeRole || "Not specified"}`)
+  lines.push("- Speaker notes: Not specified.")
   lines.push("")
-  for (const component of slide.componentPlan) lines.push(renderComponentPlanMarkdown(component, 5))
   lines.push("#### Source Links")
   lines.push("")
   lines.push(renderSourceLinksMarkdown(slide.sourceLinks))
   lines.push("")
-  lines.push("#### Caveats")
+  lines.push("#### Design Plan")
   lines.push("")
-  if (slide.caveats.length === 0) lines.push("- None.")
-  else for (const caveat of slide.caveats) lines.push(`- ${caveat}`)
+  lines.push(`- Layout: ${slide.layout || "unspecified"}`)
+  lines.push(`- Components: ${slide.components.join(", ") || "none"}`)
+  lines.push("- Visual intent:")
+  lines.push(...indentMultiline(visualIntent ? renderVisualIntent(visualIntent) : "- Brief: Not specified."))
+  lines.push("")
+  for (const component of slide.componentPlan) lines.push(renderComponentPlanMarkdown(component, 5))
   lines.push("")
   return lines.join("\n")
 }
@@ -525,7 +543,6 @@ function renderSourceLinksMarkdown(sourceLinks: DeckPlanSourceLinks): string {
     ["Findings", sourceLinks.findings],
     ["Assets", sourceLinks.assets],
     ["URLs", sourceLinks.urls],
-    ["Caveats", sourceLinks.caveats],
   ] as const) {
     lines.push(`${label}:`)
     if (values.length === 0) lines.push("- None.")
@@ -575,6 +592,8 @@ function readDeckPlanSlideFiles(workspaceRoot: string, knownNodeIds?: Set<string
 }
 
 function readDeckPlanSlidesFromSingleFile(workspaceRoot: string, absolutePath: string, markdown: string, knownNodeIds?: Set<string>): DeckPlanSlideProjection[] {
+  const slideBlocks = readDeckPlanSeparatorSlidesFromSingleFile(workspaceRoot, absolutePath, markdown, knownNodeIds)
+  if (slideBlocks.length > 0) return slideBlocks
   const path = relativePath(workspaceRoot, absolutePath)
   const body = parseVaultFrontmatter(markdown).body
   const matches = [...body.matchAll(/^[ \t]*###\s+Slide\s+(\d+)\s+(?:—|-)\s+(.+?)\s*$/gm)]
@@ -620,6 +639,58 @@ function readDeckPlanSlidesFromSingleFile(workspaceRoot: string, absolutePath: s
   return slides.sort((a, b) => (a.slideIndex ?? Number.MAX_SAFE_INTEGER) - (b.slideIndex ?? Number.MAX_SAFE_INTEGER))
 }
 
+function readDeckPlanSeparatorSlidesFromSingleFile(workspaceRoot: string, absolutePath: string, markdown: string, knownNodeIds?: Set<string>): DeckPlanSlideProjection[] {
+  const path = relativePath(workspaceRoot, absolutePath)
+  const body = parseVaultFrontmatter(markdown).body
+  const slidesHeading = /^[ \t]*##\s+Slides\s*$/mi.exec(body)
+  if (!slidesHeading || slidesHeading.index === undefined) return []
+  const headingEnd = body.indexOf("\n", slidesHeading.index)
+  const slidesStart = headingEnd === -1 ? slidesHeading.index + slidesHeading[0].length : headingEnd + 1
+  const rest = body.slice(slidesStart)
+  const nextSection = rest.search(/^[ \t]*##\s+(?!#)/m)
+  const slidesRegion = nextSection === -1 ? rest : rest.slice(0, nextSection)
+  const metadataMatches = [...slidesRegion.matchAll(/^[ \t]*---[ \t]*\n[\s\S]*?\n[ \t]*---[ \t]*(?:\n|$)/gm)]
+  const slides: DeckPlanSlideProjection[] = []
+  for (let i = 0; i < metadataMatches.length; i++) {
+    const match = metadataMatches[i]
+    const start = match.index ?? 0
+    const next = i + 1 < metadataMatches.length ? metadataMatches[i + 1].index ?? slidesRegion.length : slidesRegion.length
+    const block = slidesRegion.slice(start, next).trim()
+    const parsed = parseVaultFrontmatter(block)
+    const slideIndex = numberField(parsed.frontmatter, "slideIndex")
+    const title = stringField(parsed.frontmatter, "title") || firstHeading(parsed.body) || `Slide ${slideIndex ?? i + 1}`
+    const fields = parseSlideBlockFields(parsed.body)
+    const sourceLinks = normalizeSourceLinks(parseDeckPlanSourceLinks(singleFileSubsection(block, "Source Links")))
+    const narrativeLinks = parseDeckPlanNarrativeLinks(singleFileSubsection(block, "Narrative Links") || block, knownNodeIds)
+    const links = sourceLinksToNarrativeLinks(sourceLinks, narrativeLinks)
+    const componentPlan = parseDeckPlanComponentPlan(singleFileSubsection(block, "Component Plan") || singleFileSubsection(block, "Design Plan"))
+    slides.push({
+      path,
+      absolutePath,
+      id: stringField(parsed.frontmatter, "id") || fields.id || `slide-${slugify(title)}`,
+      slideIndex,
+      title,
+      chapter: stringField(parsed.frontmatter, "chapter") || fields.chapter || "",
+      layout: stringField(parsed.frontmatter, "layout") || fields.layout || "",
+      components: arrayField(parsed.frontmatter, "components").length > 0 ? arrayField(parsed.frontmatter, "components") : parseCsv(fields.components || componentPlan.map((component) => component.name).join(", ")),
+      componentPlan,
+      structural: booleanField(parsed.frontmatter, "structural", fields.structural === "true" || fields.structural === "yes"),
+      narrativeRole: stringField(parsed.frontmatter, "role") || stringField(parsed.frontmatter, "narrativeRole") || fields.role || fields.narrativeRole || "",
+      markdown: block,
+      frontmatter: parsed.frontmatter,
+      sections: parseMarkdownSections(block),
+      links,
+      sourceLinks,
+      caveats: uniqueStrings([...parseBulletText(singleFileSubsection(block, "Caveats")), ...sourceLinks.caveats]),
+    })
+  }
+  return slides.sort((a, b) => (a.slideIndex ?? Number.MAX_SAFE_INTEGER) - (b.slideIndex ?? Number.MAX_SAFE_INTEGER))
+}
+
+function firstHeading(markdown: string): string {
+  return /^#{1,6}\s+(.+?)\s*$/m.exec(markdown)?.[1]?.trim() ?? ""
+}
+
 function parseSlideBlockFields(block: string): Record<string, string> {
   const fields: Record<string, string> = {}
   for (const rawLine of block.split(/\r?\n/)) {
@@ -787,9 +858,53 @@ function deckPlanIndexDiagnostics(slides: DeckPlanSlideProjection[]): DeckPlanPr
   return diagnostics
 }
 
+function buildHtmlWritingBatches(slides: DeckPlanSlideProjection[]): DeckPlanHtmlWritingBatch[] {
+  const ordered = slides
+    .filter((slide) => Number.isInteger(slide.slideIndex) && (slide.slideIndex ?? 0) > 0)
+    .sort((a, b) => (a.slideIndex ?? Number.MAX_SAFE_INTEGER) - (b.slideIndex ?? Number.MAX_SAFE_INTEGER))
+  const chapterGroups: Array<{ chapterTitle: string; slideIndexes: number[] }> = []
+  for (const slide of ordered) {
+    const chapterTitle = slide.chapter || "Unassigned"
+    const current = chapterGroups[chapterGroups.length - 1]
+    if (current && current.chapterTitle === chapterTitle) current.slideIndexes.push(slide.slideIndex!)
+    else chapterGroups.push({ chapterTitle, slideIndexes: [slide.slideIndex!] })
+  }
+  const batches: DeckPlanHtmlWritingBatch[] = []
+  for (const group of chapterGroups) {
+    const chunks = chunkNumbers(group.slideIndexes, MAX_HTML_SLIDES_PER_BATCH)
+    for (let index = 0; index < chunks.length; index += 1) {
+      const chunk = chunks[index]
+      const chapterSuffix = chunks.length > 1 ? ` part ${index + 1}` : ""
+      const label = batches.length === 0
+        ? `Initial shell and ${group.chapterTitle}${chapterSuffix}`
+        : `${group.chapterTitle}${chapterSuffix}`
+      batches.push({
+        label,
+        chapterTitle: group.chapterTitle,
+        slideIndexes: chunk,
+        maxSlides: MAX_HTML_SLIDES_PER_BATCH,
+        instructions: batches.length === 0
+          ? `Create or update the foundation if needed, then write only slide sections ${formatSlideRange(chunk)}. Do not add or rewrite more than ${MAX_HTML_SLIDES_PER_BATCH} slide sections in this write.`
+          : `Patch only slide sections ${formatSlideRange(chunk)}, preserve previously written slides, and keep the file valid after the patch. Do not add or rewrite more than ${MAX_HTML_SLIDES_PER_BATCH} slide sections in this write.`,
+      })
+    }
+  }
+  return batches
+}
+
+function chunkNumbers(values: number[], size: number): number[][] {
+  const chunks: number[][] = []
+  for (let index = 0; index < values.length; index += size) chunks.push(values.slice(index, index + size))
+  return chunks
+}
+
+function htmlWritingInstruction(): string {
+  return `Before every HTML write/edit/apply_patch, follow htmlWritingBatches and add or rewrite at most ${MAX_HTML_SLIDES_PER_BATCH} <section class="slide"> blocks. Run Artifact QA after each batch before continuing.`
+}
+
 function slideDiagnostics(slide: DeckPlanSlideProjection, knownNodeIds?: Set<string>): DeckPlanProjectionDiagnostic[] {
   const diagnostics: DeckPlanProjectionDiagnostic[] = []
-  if (!slide.structural && slide.links.length === 0 && slide.caveats.length === 0) diagnostics.push({ severity: "warning", code: "slide_source_link_missing", message: `Non-structural deck-plan slide ${slide.id} has no source, research, asset, or caveat link.`, file: slide.path, nodeId: slide.id })
+  if (!slide.structural && linksCount(slide.sourceLinks) === 0) diagnostics.push({ severity: "warning", code: "slide_source_link_missing", message: `Non-structural deck-plan slide ${slide.id} has no material, finding, asset, or URL source link.`, file: slide.path, nodeId: slide.id })
   if (!slide.layout) diagnostics.push({ severity: "warning", code: "slide_layout_missing", message: `Deck-plan slide ${slide.id} is missing a layout.`, file: slide.path, nodeId: slide.id })
   if (slide.components.length === 0) diagnostics.push({ severity: "warning", code: "slide_components_missing", message: `Deck-plan slide ${slide.id} has no component names in frontmatter.`, file: slide.path, nodeId: slide.id })
   if (slide.componentPlan.length === 0) diagnostics.push({ severity: "warning", code: "slide_component_plan_missing", message: `Deck-plan slide ${slide.id} is missing structured ## Component Plan entries.`, file: slide.path, nodeId: slide.id })
@@ -847,7 +962,7 @@ function validateDeckPlanSlideUpsert(input: DeckPlanSlideUpsertInput, options: {
   const visual = normalizeVisualIntent(input.visualIntent)
   if (visual.component && !componentNames.has(visual.component)) diagnostics.push(errorDiagnostic("slide_visual_component_missing", `visualIntent.component '${visual.component}' is not present in component plan.`, nodeId))
   const sourceLinks = sourceLinksForInput(input)
-  if (!input.structural && linksCount(sourceLinks) === 0) diagnostics.push({ severity: "warning", code: "slide_source_link_missing", message: "Non-structural slides should include at least one material, finding, asset, URL, or caveat source link.", nodeId })
+  if (!input.structural && linksCount(sourceLinks) === 0) diagnostics.push({ severity: "warning", code: "slide_source_link_missing", message: "Non-structural slides should include at least one material, finding, asset, or URL source link.", nodeId })
   return diagnostics
 }
 
@@ -887,7 +1002,7 @@ function validateComponentInput(component: DeckPlanSlideUpsertComponentInput, co
 }
 
 function linksCount(sourceLinks: DeckPlanSourceLinks): number {
-  return sourceLinks.materials.length + sourceLinks.findings.length + sourceLinks.assets.length + sourceLinks.urls.length + sourceLinks.caveats.length
+  return sourceLinks.materials.length + sourceLinks.findings.length + sourceLinks.assets.length + sourceLinks.urls.length
 }
 
 function errorDiagnostic(code: string, message: string, nodeId?: string): DeckPlanProjectionDiagnostic {
@@ -1017,12 +1132,6 @@ function renderDeckPlanSlideMarkdown(input: DeckPlanSlideUpsertInput & { id: str
     lines.push("")
   }
   lines.push(renderSourceLinksMarkdown(sourceLinksForInput(input)).replace(/^####/gm, "##"))
-  lines.push("## Caveats")
-  lines.push("")
-  const caveats = input.caveats?.filter((item) => item.trim()) ?? []
-  if (caveats.length === 0) lines.push("- None.")
-  else for (const caveat of caveats) lines.push(`- ${caveat.trim()}`)
-  lines.push("")
   return lines.join("\n")
 }
 
@@ -1083,10 +1192,10 @@ function renderMinimalDeckPlanIndex(narrativeHash: string | undefined, slides: D
   if (evidenceIds.length === 0) lines.push("- No evidence links planned yet.")
   else for (const id of evidenceIds) lines.push(`- [[${id}]]`)
   lines.push("")
-  lines.push("## Boundary / Risk Treatment")
+  lines.push("## Source Limitations")
   lines.push("")
   const boundaryIds = uniqueStrings(slides.flatMap((slide) => slide.links.filter((link) => link.relation === "addresses_risk" || link.relation === "answers_objection" || link.relation === "mentions_gap").map((link) => link.id)))
-  if (boundaryIds.length === 0) lines.push("- No risk, objection, or gap links planned yet.")
+  if (boundaryIds.length === 0) lines.push("- No legacy risk, objection, or gap links planned.")
   else for (const id of boundaryIds) lines.push(`- [[${id}]]`)
   lines.push("")
   lines.push("## Chapter Writing Batches")
@@ -1130,8 +1239,8 @@ function booleanField(frontmatter: Record<string, string | string[] | boolean>,
 
 function arrayField(frontmatter: Record<string, string | string[] | boolean>, key: string): string[] {
   const value = frontmatter[key]
-  if (Array.isArray(value)) return value.map((item) => item.trim()).filter(Boolean)
-  if (typeof value === "string" && value.trim()) return value.split(",").map((item) => item.trim()).filter(Boolean)
+  if (Array.isArray(value)) return value.map((item) => item.trim()).filter((item) => item && item.toLowerCase() !== "none")
+  if (typeof value === "string" && value.trim()) return value.split(",").map((item) => item.trim()).filter((item) => item && item.toLowerCase() !== "none")
   return []
 }
 
@@ -1265,8 +1374,8 @@ function renderDeckPlanMarkdown(input: DeckPlanArtifactInput): string {
   lines.push("")
   lines.push("- Write one `<section class=\"slide\" data-slide-index=\"N\">` per planned slide in the completed deck, using positive 1-based slide indexes that are unique and strictly increase in DOM order. Partial chapter-by-chapter drafts may contain only the written prefix/range.")
   lines.push("- Keep every rendered slide exactly 1920x1080px with no page-level scrollbars or hidden overflow.")
-  lines.push("- Preserve claim-led chapters, visual intent, evidence ids, source trace, supported scope, unsupported scope, caveats, and strength.")
-  lines.push("- Generate HTML chapter by chapter; do not draft a full 5+ slide deck in one broad write or patch.")
+  lines.push("- Preserve claim-led chapters, visual intent, evidence ids, source trace, source limitations, unresolved inputs, and user review notes.")
+  lines.push(`- Generate HTML in the listed writing batches; do not add or rewrite more than ${MAX_HTML_SLIDES_PER_BATCH} slide sections in one write or patch.`)
   lines.push("")
   lines.push("## Chapter Map")
   lines.push("")
@@ -1284,14 +1393,17 @@ function renderDeckPlanMarkdown(input: DeckPlanArtifactInput): string {
   }
   lines.push("## Chapter Writing Batches")
   lines.push("")
-  lines.push("Use these batches for HTML generation. Keep the HTML valid after every batch and preserve previously written slides.")
+  lines.push(`Use these batches for HTML generation. Each batch is capped at ${MAX_HTML_SLIDES_PER_BATCH} slide sections. Keep the HTML valid after every batch and preserve previously written slides.`)
   lines.push("")
   if (input.renderPlan) {
-    for (const batch of input.renderPlan.chapterWritingBatches) lines.push(`- ${batch.label}: ${batch.chapterTitle}, slides ${formatSlideRange(batch.slideIndexes)}. ${batch.instructions}`)
+    for (const batch of input.renderPlan.chapterWritingBatches) lines.push(`- ${batch.label}: ${batch.chapterTitle}, slides ${formatSlideRange(batch.slideIndexes)}; max ${batch.maxSlides} slides. ${batch.instructions}`)
   } else {
     input.chapters.forEach((chapter, index) => {
       const prefix = index === 0 ? "Initial shell and first chapter" : `Chapter batch ${index + 1}`
-      lines.push(`- ${prefix}: ${chapter.title}, slides ${formatSlideRange(chapter.slideIndexes)}.`)
+      for (const [chunkIndex, chunk] of chunkNumbers(chapter.slideIndexes, MAX_HTML_SLIDES_PER_BATCH).entries()) {
+        const suffix = chunkIndex === 0 ? "" : ` part ${chunkIndex + 1}`
+        lines.push(`- ${prefix}${suffix}: ${chapter.title}, slides ${formatSlideRange(chunk)}; max ${MAX_HTML_SLIDES_PER_BATCH} slides.`)
+      }
     })
   }
   if (input.renderPlan) {

package/lib/narrative-state/render-plan.ts

@@ -93,6 +93,7 @@ export interface RenderPlanWritingBatch {
   label: string
   chapterTitle: string
   slideIndexes: number[]
+  maxSlides: number
   instructions: string
 }
 
@@ -112,6 +113,7 @@ export interface RenderPlanContract {
 
 type VisualIntentKind = "hero" | "toc" | "metric-stat" | "evidence-table" | "comparison-grid" | "risk-matrix" | "steps" | "text-only"
 type ClaimChapterSlideKind = "framing" | "evidence" | "implication"
+const MAX_HTML_SLIDES_PER_BATCH = 5
 
 interface VisualIntent {
   kind: VisualIntentKind
@@ -251,10 +253,11 @@ function buildDeckPlanRequirements(narrativeHash: string): DeckPlanRequirements
       "Each substantive chapter should have framing, proof, and implication/boundary coverage.",
       "Chapter divider or chapter TOC slides may use the toc component as structural wayfinding.",
       "Do not create filler slides, repeated thesis pages, or generic bridge slides.",
-      "Preserve evidence ids, source trace, supported scope, unsupported scope, caveats, and strength where available.",
+      "Preserve evidence ids, source trace, source limitations, unresolved inputs, and user review notes where available.",
       "Do not render internal labels such as Evidence gap:, Unsupported scope:, Caveat:, Missing Data, or Evidence Boundary in executive body copy.",
       "Do not infer plan structure from DECKS.json slides[]; it is compatibility cache only.",
-      "Use sourceLinks in slide blocks for materials, findings, assets, URLs, and caveats; do not use canonical ## Relations in deck-plan files.",
+      "Use sourceLinks in slide blocks for materials, findings, assets, and URLs; do not use canonical ## Relations in deck-plan files.",
+      "Use `---` slide separators under ## Slides with slide-local metadata, followed by #### Content Plan, #### Source Links, and #### Design Plan.",
     ],
     requiredSections: [
       "Goal",
@@ -283,7 +286,7 @@ export function buildRenderPlanContract(deck: DeckSpec, chapters: DeckPlanChapte
       "Render chapter divider slides with the toc component when slideKind is chapter-divider.",
       "Chapter divider and global TOC slides are structural wayfinding and do not count toward central-claim substance.",
       "Each central claim chapter needs non-structural framing, proof, and implication/boundary slides unless the current deck-plan projection explicitly says otherwise.",
-      "Generate HTML chapter by chapter, preserving valid HTML and already-written slides after every batch.",
+      `Generate HTML in chapter-bounded batches of at most ${MAX_HTML_SLIDES_PER_BATCH} slides, preserving valid HTML and already-written slides after every batch.`,
     ],
     htmlIdentityContract: [
       "Every written slide section uses class slide and a positive 1-based data-slide-index.",
@@ -306,18 +309,38 @@ export function buildRenderPlanContract(deck: DeckSpec, chapters: DeckPlanChapte
         allowedStructuralSlides: chapter.sourceClaimId ? ["chapter-divider", "toc"] : ["cover", "toc", "ask"],
       }
     }),
-    chapterWritingBatches: chapters.map((chapter, index) => ({
-      label: index === 0 ? "Initial shell and first chapter" : `Chapter batch ${index + 1}`,
-      chapterTitle: chapter.title,
-      slideIndexes: chapter.slideIndexes,
-      instructions: index === 0
-        ? "Create the stable HTML shell, required structural slides, and this first chapter range only."
-        : "Patch exactly this chapter range, preserve previously written slides, and keep the file valid after the patch.",
-    })),
+    chapterWritingBatches: chapterWritingBatches(chapters),
     slideRenderMetadata: deck.slides.map((slide) => slideRenderMetadata(slide, chapters)),
   }
 }
 
+function chapterWritingBatches(chapters: DeckPlanChapter[]): RenderPlanWritingBatch[] {
+  const batches: RenderPlanWritingBatch[] = []
+  for (const chapter of chapters) {
+    const chunks = chunkNumbers(chapter.slideIndexes, MAX_HTML_SLIDES_PER_BATCH)
+    for (let index = 0; index < chunks.length; index += 1) {
+      const chunk = chunks[index]
+      const chapterSuffix = chunks.length > 1 ? ` part ${index + 1}` : ""
+      batches.push({
+        label: batches.length === 0 ? `Initial shell and ${chapter.title}${chapterSuffix}` : `${chapter.title}${chapterSuffix}`,
+        chapterTitle: chapter.title,
+        slideIndexes: chunk,
+        maxSlides: MAX_HTML_SLIDES_PER_BATCH,
+        instructions: batches.length === 0
+          ? `Create the stable HTML shell if needed, then write only slide sections ${formatSlideRange(chunk)}. Do not add or rewrite more than ${MAX_HTML_SLIDES_PER_BATCH} slide sections in this write.`
+          : `Patch only slide sections ${formatSlideRange(chunk)}, preserve previously written slides, and keep the file valid after the patch. Do not add or rewrite more than ${MAX_HTML_SLIDES_PER_BATCH} slide sections in this write.`,
+      })
+    }
+  }
+  return batches
+}
+
+function chunkNumbers(values: number[], size: number): number[][] {
+  const chunks: number[][] = []
+  for (let index = 0; index < values.length; index += size) chunks.push(values.slice(index, index + size))
+  return chunks
+}
+
 function slideRenderMetadata(slide: SlideSpec, chapters: DeckPlanChapter[]): RenderPlanSlideMetadata {
   const chapter = chapters.find((item) => item.slideIndexes.includes(slide.index))
   const slideKind = renderPlanSlideKind(slide, chapter)
@@ -1115,6 +1138,13 @@ function claimChapterTitle(claim: NarrativeClaim): string {
   return title.endsWith(".") ? title.slice(0, -1) : title
 }
 
+function formatSlideRange(indexes: number[]): string {
+  if (indexes.length === 0) return "none"
+  const sorted = [...indexes].sort((a, b) => a - b)
+  if (sorted.length === 1) return String(sorted[0])
+  return `${sorted[0]}-${sorted[sorted.length - 1]}`
+}
+
 function hasCurrentApprovalOrOverride(narrative: NarrativeStateV1, narrativeHash: string): boolean {
   return narrative.approvals.some((approval) => approval.narrativeHash === narrativeHash && (approval.scope === "narrative" && approval.approvedBy === "user" || approval.scope === "render_override" || approval.approvedBy === "override"))
 }

package/package.json

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

package/plugins/revela/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "revela": {
       "command": "npx",
-      "args": ["-y", "@cyber-dash-tech/revela@0.18.2", "mcp"]
+      "args": ["-y", "@cyber-dash-tech/revela@0.18.3", "mcp"]
     }
   }
 }

package/plugins/revela/skills/revela-make-deck/SKILL.md

@@ -19,13 +19,14 @@ Use this skill when the user asks to plan, make, generate, or update a Revela de
 1. For planning requests, inspect local materials/reviews/research, then write or repair `deck-plan.md` directly. Do not use structured upsert tools for normal plan authoring.
 2. Call `revela_design_list`, `revela_design_read` with `section: "rules"`, and `revela_design_inventory` before selecting layouts/components; use the returned layout slots and component nesting hints in `deck-plan.md`.
 3. Call `revela_read_deck_plan` after writing or repairing `deck-plan.md`. If diagnostics report layout, slot, component, `children`, or `sourceLinks` issues, patch the Markdown directly and call `revela_read_deck_plan` again.
-4. Call `revela_read_deck_plan` before HTML generation and follow the current projection. `revela_read_deck_plan` is QA/diagnostics, not a writer.
+4. Call `revela_read_deck_plan` before HTML generation and follow the current projection. Read `htmlWritingBatches` from the result before any HTML write. `revela_read_deck_plan` is QA/diagnostics, not a writer.
 5. For new HTML files, call `revela_create_deck_foundation`.
 6. Before patching slide HTML, read the specific layouts/components with `revela_design_read_layout` and `revela_design_read_component`; fetch chart rules before ECharts.
 7. Patch slides into the foundation between Revela slide markers. Preserve positive 1-based `data-slide-index` values. Every slide must have exactly one direct `.slide-canvas` child.
-8. Generate chapter by chapter. Keep the HTML valid after each write.
-9. After every HTML write, call `revela_run_deck_qa` and repair hard errors before review or export.
+8. Generate one `htmlWritingBatches` entry at a time. A single HTML write/edit/apply_patch may add or rewrite at most 5 slide sections. If a chapter is longer than 5 slides, use the consecutive batch parts returned by `revela_read_deck_plan`.
+9. Keep the HTML valid after each write.
+10. After every HTML write, call `revela_run_deck_qa` and repair hard errors before review or export.
 
 ## Deck Plan Requirements
 
-Every normal deck plan should include Cover, Table of Contents, and Closing. Use 3-5 chapter headings, explicit slide ranges, `sourceLinks` for materials/findings/assets/URLs/caveats, visual intent, caveats, and unresolved inputs. Use `box.children` when multiple child components support one semantic idea; do not duplicate the same child as both nested and top-level.
+Every normal deck plan should include Cover, Table of Contents, and Closing. Use 3-5 chapter headings, explicit slide ranges, and `---` slide separators under `## Slides`. Each slide block should have slide-local metadata followed by `#### Content Plan`, `#### Source Links` for materials/findings/assets/URLs, and `#### Design Plan` for layout, component plan, visual intent, placement notes, and render notes. Use unresolved inputs, source limitations, and user review notes instead of AI-authored caveat/risk judgement. Use `box.children` when multiple child components support one semantic idea; do not duplicate the same child as both nested and top-level.

package/skill/SKILL.md

@@ -78,12 +78,14 @@ Batches, slide plan, visual intent, evidence trace, boundaries, and narrative
 links. Do not call `compileDeckPlan` merely to understand an existing plan, and
 do not reinterpret cached `DECKS.json.slides[]` as the render contract.
 
-Decks with 5 or more slides must be generated chapter by chapter, not in one
-broad `write` or `apply_patch` call. The first HTML write may create the stable
-HTML shell, structural slides, and the first chapter only. Subsequent writes
-must patch one chapter at a time, preserving already-written slides and keeping
-the file valid after every write. Do not continue to the next chapter while the
-current file has Artifact QA hard errors.
+Deck HTML must be generated in bounded batches, not in one broad `write` or
+`apply_patch` call. Follow `htmlWritingBatches` from `readDeckPlan`; each HTML
+write/edit/apply_patch may add or rewrite at most 5 `<section class="slide">`
+blocks. The first HTML write may create the stable HTML shell, but its slide
+sections are still capped at 5. Subsequent writes must patch only the next
+listed batch, preserving already-written slides and keeping the file valid after
+every write. Do not continue to the next batch while the current file has
+Artifact QA hard errors.
 
 ---
 
@@ -118,15 +120,17 @@ Before writing HTML, the deck-plan projection should include:
 
 - `deck-plan.md` with `designName`, `outputPath` when known, chapter map, and
   ordered slide blocks.
-- Each slide block uses `sourceLinks` for materials, findings, assets, URLs,
-  and caveats. Legacy narrative links may be read for compatibility, but new
+- Each slide block uses `sourceLinks` for materials, findings, assets, and URLs.
+  Legacy narrative/caveat links may be read for compatibility, but new
   plans should not use them.
+- Use `---` slide separators under `## Slides` with slide-local metadata, then
+  `#### Content Plan`, `#### Source Links`, and `#### Design Plan`.
 - `Required structure: Cover + Table of Contents + Closing`.
 - A `Chapters` section with 3-5 TOC headings, slide ranges, and the
   non-structural slides assigned to each chapter.
 - One row/block per slide with title, purpose, narrative role, content summary,
   layout, components, `sourceLinks`, visual intent, visual brief, render notes,
-  and caveats/unsupported scope.
+  unresolved inputs, source limitations, and user review notes.
 - Source Authority, Chapter Map, Slides, Unresolved Inputs, and HTML Contract
   sections.
 - A low-fidelity layout sketch for every slide when requested by the handoff
@@ -167,14 +171,16 @@ a required workflow gate.
 
 ## Chapter-By-Chapter Generation
 
-Generate the artifact chapter by chapter. Never draft a full 5+ slide deck in
-one broad `write`, `edit`, or `apply_patch` call.
+Generate the artifact by following `htmlWritingBatches`. Never add or rewrite
+more than 5 slide sections in one `write`, `edit`, or `apply_patch` call.
 
 For decks with 5 or more slides:
 
 - First call `revela-deck-foundation` for new files, then patch structural
-  slides and the first chapter between the `revela-slides` markers.
-- Then fill or revise exactly one chapter range at a time.
+  slides and the first listed batch between the `revela-slides` markers.
+- Then fill or revise exactly one listed batch at a time.
+- If a chapter has more than 5 slides, split it into consecutive batches from
+  `htmlWritingBatches`.
 - Do not mix multiple central-claim chapters in the same write.
 - Chapter divider or chapter TOC slides are allowed as structural wayfinding and
   should usually use the `toc` component.
@@ -292,15 +298,15 @@ patch and rerun QA before considering the deck ready.
 
 ## Evidence And Source Rules
 
-- Do not invent quotes, URLs, page references, source paths, caveats, or evidence
-  ids.
-- Preserve supported scope, unsupported scope, caveats, and source trace when
-  visible in narrative state or slide specs.
+- Do not invent quotes, URLs, page references, source paths, source limitations,
+  user review notes, or evidence ids.
+- Preserve source trace, explicit source limitations, and unresolved inputs when
+  visible in deck-plan source context or slide specs.
 - Evidence-sensitive claims need visible evidence/source context when available.
 - Never stretch partial evidence into support for future-state, recommendation,
   roadmap, or product-vision claims.
-- Keep missing evidence visible as a caveat, gap, or blocker instead of filling
-  it with assumptions.
+- Keep missing evidence visible as an unresolved input, source limitation, user
+  review note, or blocker instead of filling it with assumptions.
 - Do not render internal evidence diagnostics as executive-facing body copy.
   Avoid labels such as `Evidence gap:`, `Unsupported scope:`, `Caveat:`,
   `Missing Data`, or `Evidence Boundary` in normal slide text unless the user