@cyber-dash-tech/revela 0.17.16 → 0.17.18

package/README.md

@@ -123,49 +123,61 @@ revela, use consulting as the domain.
 revela, use summit as the design.
 ```
 
-3. Initialize the narrative from local materials. Init grounds the narrative in the workspace and surfaces gaps; it does not replace the research step.
+3. Create a custom design when you want a different visual direction.
+
+```text
+revela, create a new design named neon-finance with a crisp financial-dashboard style: dark surfaces, precise grids, and bright green accents.
+```
+
+Revela may ask for references or constraints, then creates and validates the design. When it is ready, switch to it:
+
+```text
+revela, use neon-finance as the design.
+```
+
+4. Initialize the narrative from local materials. Init grounds the narrative in the workspace and surfaces gaps; it does not replace the research step.
 
 ```text
 revela, help me init this workspace from the local materials.
 ```
 
-4. Research the gaps and bind only source-supported evidence into the narrative.
+5. Research the gaps and bind only source-supported evidence into the narrative.
 
 ```text
 revela, research the current gaps and bind only source-supported evidence.
 ```
 
-5. Read Story before rendering to inspect the claim flow, evidence support, caveats, unsupported scope, and open gaps.
+6. Read Story before rendering to inspect the claim flow, evidence support, caveats, unsupported scope, and open gaps.
 
 ```text
 revela, show me the Story before we make the deck.
 ```
 
-6. Create or update the deck plan before generating HTML so slide order, chapter structure, evidence trace, caveats, and visual intent are explicit.
+7. Create or update the deck plan before generating HTML so slide order, chapter structure, evidence trace, caveats, and visual intent are explicit.
 
 ```text
 revela, create or update the deck plan before generating HTML.
 ```
 
-7. Make an HTML deck from the current deck plan and canonical narrative.
+8. Make an HTML deck from the current deck plan and canonical narrative.
 
 ```text
 revela, make the deck from the current deck plan and narrative.
 ```
 
-8. Review the generated deck for traceability, diagnostics, and targeted edits.
+9. Review the generated deck for traceability, diagnostics, and targeted edits.
 
 ```text
 revela, review the generated deck.
 ```
 
-9. Export a PDF after deck QA passes.
+10. Export a PDF after deck QA passes.
 
 ```text
 revela, export the deck to PDF.
 ```
 
-10. Export an editable PPTX after deck QA passes.
+11. Export an editable PPTX after deck QA passes.
 
 ```text
 revela, export the deck to PPTX.

package/README.zh-CN.md

@@ -123,49 +123,61 @@ revela，use consulting as domain.
 revela，use summit as design.
 ```
 
-3. 从本地材料初始化 narrative。Init 负责基于 workspace 做 grounding 并暴露 gap；它不替代 research 步骤。
+3. 如果需要不同的视觉方向，可以创建一个自定义 design。
+
+```text
+revela，创建一个名为 neon-finance 的新 design：金融仪表盘风格，深色界面、精密网格、亮绿色重点色。
+```
+
+Revela 可能会继续询问参考图、风格约束或禁忌项，然后创建并校验 design。创建完成后再切换使用：
+
+```text
+revela，使用 neon-finance 作为 design。
+```
+
+4. 从本地材料初始化 narrative。Init 负责基于 workspace 做 grounding 并暴露 gap；它不替代 research 步骤。
 
 ```text
 revela，帮我 init 这个 workspace，先读本地材料。
 ```
 
-4. 针对 gap 做 research，并且只把来源明确支持的 evidence 绑定回 narrative。
+5. 针对 gap 做 research，并且只把来源明确支持的 evidence 绑定回 narrative。
 
 ```text
 revela，research 当前 gaps，只绑定 source-supported evidence。
 ```
 
-5. 生成 deck 前先读 Story，检查 claim flow、证据支撑、caveats、unsupported scope 和 open gaps。
+6. 生成 deck 前先读 Story，检查 claim flow、证据支撑、caveats、unsupported scope 和 open gaps。
 
 ```text
 revela，先给我看 Story，再 make deck。
 ```
 
-6. 先创建或更新 deck plan，明确 slide 顺序、章节结构、evidence trace、caveats 和 visual intent，再生成 HTML。
+7. 先创建或更新 deck plan，明确 slide 顺序、章节结构、evidence trace、caveats 和 visual intent，再生成 HTML。
 
 ```text
 revela，生成 HTML 前先 create or update deck plan。
 ```
 
-7. 基于当前 deck plan 和 canonical narrative 生成 HTML deck。
+8. 基于当前 deck plan 和 canonical narrative 生成 HTML deck。
 
 ```text
 revela，基于当前 deck plan 和 narrative make deck。
 ```
 
-8. Review 生成后的 deck，检查 traceability、diagnostics，并做定向修改。
+9. Review 生成后的 deck，检查 traceability、diagnostics，并做定向修改。
 
 ```text
 revela，review 生成好的 deck。
 ```
 
-9. QA 通过后导出 PDF。
+10. QA 通过后导出 PDF。
 
 ```text
 revela，把 deck export 成 PDF。
 ```
 
-10. QA 通过后导出可编辑 PPTX。
+11. QA 通过后导出可编辑 PPTX。
 
 ```text
 revela，把 deck export 成 PPTX。

package/bin/revela.ts

@@ -31,6 +31,8 @@ else {
     else if (command === "design-list") result = runtime.designList()
     else if (command === "design-read") result = runtime.designRead(options)
     else if (command === "design-use") result = runtime.designActivate(required(options, ["name"]))
+    else if (command === "design-create") result = runtime.designCreate(required(options, ["name", "designMd", "previewHtml"]))
+    else if (command === "design-validate") result = runtime.designValidate(required(options, ["name"]))
     else if (command === "domain-list") result = runtime.domainList()
     else if (command === "domain-read") result = runtime.domainRead(options)
     else if (command === "domain-use") result = runtime.domainActivate(required(options, ["name"]))
@@ -89,8 +91,10 @@ Usage:
   revela export-pdf --file <path> [--workspaceRoot <path>]  # deck PDF, or single-page PDF fallback for non-deck HTML
   revela export-pptx --file <path> [--workspaceRoot <path>]
   revela design-list
-  revela design-read [--name <design>]
+  revela design-read [--name <design>] [--section <rules|foundation|chart-rules>] [--workspaceRoot <path>]
   revela design-use --name <design>
+  revela design-create --name <design> --designMd <text> --previewHtml <text> [--base <design>] [--overwrite true]
+  revela design-validate --name <design>
   revela domain-list
   revela domain-read [--name <domain>]
   revela domain-use --name <domain>

package/designs/monet/DESIGN.md

@@ -483,6 +483,7 @@ These rules are mandatory for Monet.
 - **Icon system is Lucide.** For ordinary UI, semantic, status, category, process, and navigation icons, use Lucide (`data-lucide`). Do not hand-write inline SVG for icons. SVG is allowed only for intentional decorative motifs, illustrations, or design-specific artwork. If any `data-lucide` icon is present, load Lucide via CDN and call `lucide.createIcons()` after `SlidePresentation`.
 - **Chart system is ECharts.** Data charts default to ECharts inside `echart-panel`. Do not use hand-written SVG, div/CSS shapes, canvas mocks, or static faux charts as data-chart substitutes. SVG remains acceptable for decorative motifs, diagrams, or illustrations, not data charts. Before creating or changing a chart, fetch the `echart-panel` component and `section: "chart-rules"`; if chart rules or runtime are unavailable, report the gap instead of inventing a fake chart fallback.
 - **Start from foundation.** New deck HTML starts from `@design:foundation`. Do not recreate foundation CSS, JavaScript, or the HTML skeleton from memory. Prefer a foundation helper when available; otherwise fetch `section: "foundation"` before writing a new deck shell. Existing deck edits preserve the current foundation unless the user asks for foundation repair or QA reports a foundation contract problem.
+- **Canonical slide canvas.** Every slide must be `<section class="slide" slide-qa="..." data-slide-index="N">` with exactly one direct child `.slide-canvas`. `.slide-canvas` is the 1920px x 1080px export surface and must keep `padding: 0`, `position: relative`, and `overflow: hidden`; put `.page` or layout containers inside `.slide-canvas`, never slide content directly under `.slide`. Missing, nested, or duplicate `.slide-canvas` elements are invalid and fail Artifact QA.
 
 ### Common Mistakes
 

package/designs/starter/DESIGN.md

@@ -236,6 +236,7 @@ new SlidePresentation();
 - **Icon system is Lucide.** For ordinary UI, semantic, status, category, process, and navigation icons, use Lucide (`data-lucide`). Do not hand-write inline SVG for icons. SVG is allowed only for intentional decorative motifs, illustrations, or design-specific artwork. If any `data-lucide` icon is present, load Lucide via CDN and call `lucide.createIcons()` after `SlidePresentation`.
 - **Chart system is ECharts.** Data charts default to ECharts inside `echart-panel`. Do not use hand-written SVG, div/CSS shapes, canvas mocks, or static faux charts as data-chart substitutes. SVG remains acceptable for decorative motifs, diagrams, or illustrations, not data charts. Before creating or changing a chart, fetch the `echart-panel` component and `section: "chart-rules"`; if chart rules or runtime are unavailable, report the gap instead of inventing a fake chart fallback.
 - **Start from foundation.** New deck HTML starts from `@design:foundation`. Do not recreate foundation CSS, JavaScript, or the HTML skeleton from memory. Prefer a foundation helper when available; otherwise fetch `section: "foundation"` before writing a new deck shell. Existing deck edits preserve the current foundation unless the user asks for foundation repair or QA reports a foundation contract problem.
+- **Canonical slide canvas.** Every slide must be `<section class="slide" slide-qa="..." data-slide-index="N">` with exactly one direct child `.slide-canvas`. `.slide-canvas` is the 1920px x 1080px export surface and must keep `padding: 0`, `position: relative`, and `overflow: hidden`; put `.page` or layout containers inside `.slide-canvas`, never slide content directly under `.slide`. Missing, nested, or duplicate `.slide-canvas` elements are invalid and fail Artifact QA.
 - **Images for photographic references.** Use image treatment rules rather than fake SVG when the reference is photographic, UI, webpage, or product imagery.
 - **Content pages need a stable title block.** Except cover, TOC, closing, section divider, and full-bleed hero slides, every normal content slide should include a visible title block from the upper-left safe area. It should contain a compact chapter/section label plus a slide title written as the page's claim or takeaway.
 - **Do not hide the page title inside a card.** Body components may have their own headings, but the slide-level title block should remain separate and easy to scan unless the chosen layout explicitly defines a compact side-title variant.

package/designs/summit/DESIGN.md

@@ -446,6 +446,7 @@ These rules are mandatory for Summit.
 - **Icon system is Lucide.** For ordinary UI, semantic, status, category, process, and navigation icons, use Lucide (`data-lucide`). Do not hand-write inline SVG for icons. SVG is allowed only for intentional decorative motifs, illustrations, or design-specific artwork. If any `data-lucide` icon is present, load Lucide via CDN and call `lucide.createIcons()` after `SlidePresentation`.
 - **Chart system is ECharts.** Data charts default to ECharts inside `echart-panel`. Do not use hand-written SVG, div/CSS shapes, canvas mocks, or static faux charts as data-chart substitutes. SVG remains acceptable for decorative motifs, diagrams, or illustrations, not data charts. Before creating or changing a chart, fetch the `echart-panel` component and `section: "chart-rules"`; if chart rules or runtime are unavailable, report the gap instead of inventing a fake chart fallback.
 - **Start from foundation.** New deck HTML starts from `@design:foundation`. Do not recreate foundation CSS, JavaScript, or the HTML skeleton from memory. Prefer a foundation helper when available; otherwise fetch `section: "foundation"` before writing a new deck shell. Existing deck edits preserve the current foundation unless the user asks for foundation repair or QA reports a foundation contract problem.
+- **Canonical slide canvas.** Every slide must be `<section class="slide" slide-qa="..." data-slide-index="N">` with exactly one direct child `.slide-canvas`. `.slide-canvas` is the 1920px x 1080px export surface and must keep `padding: 0`, `position: relative`, and `overflow: hidden`; put `.page` or layout containers inside `.slide-canvas`, never slide content directly under `.slide`. Missing, nested, or duplicate `.slide-canvas` elements are invalid and fail Artifact QA.
 
 ### Common Mistakes
 

package/lib/deck-html/contract.ts

@@ -16,6 +16,9 @@ export type DeckHtmlContractIssueType =
   | "duplicate_data_slide_index"
   | "slide_index_order"
   | "legacy_data_index_noncanonical"
+  | "missing_slide_canvas"
+  | "multiple_slide_canvas"
+  | "slide_canvas_not_direct_child"
 
 export interface DeckHtmlContractIssue {
   type: DeckHtmlContractIssueType
@@ -43,6 +46,8 @@ interface SlideSectionAttrs {
   position: number
   dataSlideIndex?: string
   dataIndex?: string
+  directSlideCanvasCount: number
+  descendantSlideCanvasCount: number
 }
 
 export function validateDeckHtmlContract(workspaceRoot: string, filePath: string): DeckHtmlContractReport {
@@ -111,6 +116,26 @@ export function validateDeckHtmlContract(workspaceRoot: string, filePath: string
   let previousIndex = 0
   sections.forEach((section, offset) => {
     const expectedIndex = base.expectedIndexes[offset]
+    if (section.directSlideCanvasCount === 0) {
+      base.issues.push({
+        type: section.descendantSlideCanvasCount > 0 ? "slide_canvas_not_direct_child" : "missing_slide_canvas",
+        severity: "error",
+        message: section.descendantSlideCanvasCount > 0
+          ? `Slide ${section.position} has .slide-canvas, but it must be a direct child of the .slide section.`
+          : `Slide ${section.position} is missing a direct .slide-canvas child.`,
+        slidePosition: section.position,
+        expectedIndex,
+      })
+    } else if (section.directSlideCanvasCount > 1) {
+      base.issues.push({
+        type: "multiple_slide_canvas",
+        severity: "error",
+        message: `Slide ${section.position} has ${section.directSlideCanvasCount} direct .slide-canvas children; expected exactly one.`,
+        slidePosition: section.position,
+        expectedIndex,
+      })
+    }
+
     if (section.dataIndex !== undefined) {
       base.warnings.push({
         type: "legacy_data_index_noncanonical",
@@ -217,20 +242,62 @@ export function formatDeckHtmlContractReport(report: DeckHtmlContractReport): st
 
 function extractSlideSections(html: string): SlideSectionAttrs[] {
   const sections: SlideSectionAttrs[] = []
-  const sectionTagPattern = /<section\b([^>]*)>/gi
+  const sectionPattern = /<section\b([^>]*)>([\s\S]*?)<\/section>/gi
   let match: RegExpExecArray | null
-  while ((match = sectionTagPattern.exec(html))) {
+  while ((match = sectionPattern.exec(html))) {
     const attrs = match[1] ?? ""
     if (!/\bclass\s*=\s*(["'])[^"']*\bslide\b[^"']*\1/i.test(attrs)) continue
+    const body = match[2] ?? ""
+    const directSlideCanvasCount = countDirectSlideCanvasChildren(body)
+    const descendantSlideCanvasCount = countSlideCanvasDescendants(body)
     sections.push({
       position: sections.length + 1,
       dataSlideIndex: readAttr(attrs, "data-slide-index"),
       dataIndex: readAttr(attrs, "data-index"),
+      directSlideCanvasCount,
+      descendantSlideCanvasCount,
     })
   }
   return sections
 }
 
+function countSlideCanvasDescendants(html: string): number {
+  const pattern = /<([a-z][\w:-]*)\b([^>]*)>/gi
+  let count = 0
+  let match: RegExpExecArray | null
+  while ((match = pattern.exec(html))) {
+    const attrs = match[2] ?? ""
+    if (hasClass(attrs, "slide-canvas")) count++
+  }
+  return count
+}
+
+function countDirectSlideCanvasChildren(html: string): number {
+  let depth = 0
+  let count = 0
+  const pattern = /<!--[\s\S]*?-->|<\/?([a-z][\w:-]*)\b([^>]*)>/gi
+  let match: RegExpExecArray | null
+  while ((match = pattern.exec(html))) {
+    const token = match[0]
+    if (token.startsWith("<!--")) continue
+    const tag = match[1]?.toLowerCase()
+    if (!tag) continue
+    if (token.startsWith("</")) {
+      depth = Math.max(0, depth - 1)
+      continue
+    }
+    const attrs = match[2] ?? ""
+    if (depth === 0 && hasClass(attrs, "slide-canvas")) count++
+    if (!isVoidTag(tag) && !/\/\s*>$/.test(token)) depth++
+  }
+  return count
+}
+
+function hasClass(attrs: string, className: string): boolean {
+  const classAttr = readAttr(attrs, "class")
+  return classAttr?.split(/\s+/).includes(className) ?? false
+}
+
 function readAttr(attrs: string, name: string): string | undefined {
   const pattern = new RegExp(`\\b${escapeRegExp(name)}\\s*=\\s*(["'])(.*?)\\1`, "i")
   return pattern.exec(attrs)?.[2]
@@ -266,3 +333,22 @@ function workspaceRelative(root: string, target: string): string {
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
 }
+
+function isVoidTag(tag: string): boolean {
+  return new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+  ]).has(tag)
+}

package/lib/edit/prompt.ts

@@ -61,7 +61,7 @@ export function buildEditPrompt(payload: EditCommentPayload): string {
     drop: payload.drop,
   }
   const qaInstruction = payload.suppressAutomaticArtifactQa
-    ? `- Do not run artifact QA after this edit and do not keep editing just to satisfy post-write QA. The Review UI will refresh from the deck file version change; QA can be run later through an explicit Review, QA, or export workflow.`
+    ? `- The Review bridge may suppress host-side post-write QA for this specific Apply Fix request. Do not treat that as deck readiness; any reported QA failures still require the smallest targeted repair before review or export readiness.`
     : `- Artifact QA runs automatically after deck writes/patches/edits. It checks deck HTML contract, design component compliance, exact 1920x1080 slide geometry, scrollbars, element overflow, text clipping, and claim/evidence content-density warnings.
 - If the tool result reports hard QA errors, fix them with the smallest targeted patch and let the post-write QA run again. Refine opens automatically only after hard errors pass; warnings such as thin claim/evidence substance do not block opening.`
 

package/lib/html-export/deck-detect.ts

@@ -22,55 +22,81 @@ export async function detectDeckHtmlWithBrowser(browser: Browser, htmlFilePath:
   try {
     await page.goto(pathToFileURL(htmlFilePath).href, { waitUntil: "domcontentloaded", timeout: 15000 })
     return await page.evaluate(() => {
+      const CANVAS_WIDTH = 1920
+      const CANVAS_HEIGHT = 1080
+      const DIMENSION_TOLERANCE = 2
+      const isDeckCanvasSize = (el: HTMLElement): boolean => {
+        const rect = el.getBoundingClientRect()
+        return (
+          Math.abs(rect.width - CANVAS_WIDTH) <= DIMENSION_TOLERANCE &&
+          Math.abs(rect.height - CANVAS_HEIGHT) <= DIMENSION_TOLERANCE
+        )
+      }
+
       const slides = Array.from(document.querySelectorAll(".slide")) as HTMLElement[]
       if (slides.length === 0) {
         return { isDeck: false, slideCount: 0, reason: "no .slide elements found" }
       }
 
-      const missingCanvas = slides.findIndex((slide) => !slide.querySelector(".slide-canvas"))
-      if (missingCanvas >= 0) {
-        return {
-          isDeck: false,
-          slideCount: slides.length,
-          reason: `.slide ${missingCanvas + 1} has no .slide-canvas`,
+      const indexValues = slides.map((slide) => slide.getAttribute("data-slide-index"))
+      const seen = new Set<number>()
+      for (let i = 0; i < indexValues.length; i++) {
+        const raw = indexValues[i]
+        if (raw === null || raw.trim() === "") {
+          return {
+            isDeck: false,
+            slideCount: slides.length,
+            reason: `slide ${i + 1} is missing data-slide-index`,
+          }
         }
-      }
-
-      const indexValues = slides
-        .map((slide) => slide.getAttribute("data-slide-index"))
-        .filter((value): value is string => value !== null && value.trim() !== "")
 
-      if (indexValues.length > 0) {
-        if (indexValues.length !== slides.length) {
+        const parsed = Number(raw)
+        if (!Number.isInteger(parsed) || parsed < 1) {
           return {
             isDeck: false,
             slideCount: slides.length,
-            reason: "some slides have data-slide-index and some do not",
+            reason: `slide ${i + 1} has invalid data-slide-index "${raw}"`,
           }
         }
-
-        const seen = new Set<number>()
-        for (let i = 0; i < indexValues.length; i++) {
-          const parsed = Number(indexValues[i])
-          if (!Number.isInteger(parsed) || parsed < 1) {
-            return {
-              isDeck: false,
-              slideCount: slides.length,
-              reason: `slide ${i + 1} has invalid data-slide-index "${indexValues[i]}"`,
-            }
+        if (seen.has(parsed)) {
+          return {
+            isDeck: false,
+            slideCount: slides.length,
+            reason: `duplicate data-slide-index "${parsed}"`,
           }
-          if (seen.has(parsed)) {
-            return {
-              isDeck: false,
-              slideCount: slides.length,
-              reason: `duplicate data-slide-index "${parsed}"`,
-            }
+        }
+        if (parsed !== i + 1) {
+          return {
+            isDeck: false,
+            slideCount: slides.length,
+            reason: `slide ${i + 1} has data-slide-index "${parsed}", expected "${i + 1}"`,
           }
-          seen.add(parsed)
         }
+        seen.add(parsed)
       }
 
-      return { isDeck: true, slideCount: slides.length, reason: "valid deck contract" }
+      let usedSlideAsCanvas = false
+      for (let i = 0; i < slides.length; i++) {
+        const slide = slides[i]
+        if (slide.querySelector(".slide-canvas")) continue
+        if (isDeckCanvasSize(slide)) {
+          usedSlideAsCanvas = true
+          continue
+        }
+        return {
+          isDeck: false,
+          slideCount: slides.length,
+          reason: `.slide ${i + 1} has no .slide-canvas and is not 1920x1080`,
+        }
+      }
+
+      return {
+        isDeck: true,
+        slideCount: slides.length,
+        reason: usedSlideAsCanvas
+          ? "valid deck contract: slide-as-canvas"
+          : "valid deck contract: slide-canvas",
+      }
     })
   } finally {
     await page.close().catch(() => undefined)

package/lib/pdf/export.ts

@@ -9,7 +9,7 @@
  *    rewrite the HTML to use file:// local paths — avoids CDN/CORS/headless issues
  * 3. Navigate to the patched HTML file
  * 4. For each .slide: force .reveal.visible, wait 800ms, screenshot .slide-canvas
- *    using offsetParent-chain absolute coordinates
+ *    or slide-as-canvas fallback using offsetParent-chain absolute coordinates
  * 5. Assemble screenshots into a multi-page PDF (16:9, 1920×1080pt per page) via pdf-lib
  * 6. Write PDF alongside the HTML file (same directory, .html → .pdf)
  * 7. Clean up temp dir
@@ -335,24 +335,23 @@ export async function exportDeckToPdf(htmlFilePath: string): Promise<Omit<Export
       // Wait for CSS transitions and JS rendering (ECharts animations, etc.)
       await new Promise((r) => setTimeout(r, 800))
 
-      // Compute .slide-canvas absolute position by walking the offsetParent chain.
+      // Compute screenshot target absolute position by walking the offsetParent chain.
       // getBoundingClientRect() returns viewport-relative coords (always near 0,0) —
       // unusable as screenshot clip coordinates without adding scrollY.
       // offsetParent walk gives document-absolute coords that Puppeteer clip expects.
       const clipRect = await page.evaluate((i: number) => {
         const slide = document.querySelectorAll(".slide")[i] as HTMLElement | null
         if (!slide) return null
-        const canvas = slide.querySelector(".slide-canvas") as HTMLElement | null
-        if (!canvas) return null
+        const target = (slide.querySelector(".slide-canvas") as HTMLElement | null) ?? slide
         let top = 0
         let left = 0
-        let el: HTMLElement | null = canvas
+        let el: HTMLElement | null = target
         while (el) {
           top += el.offsetTop
           left += el.offsetLeft
           el = el.offsetParent as HTMLElement | null
         }
-        return { x: left, y: top, width: canvas.offsetWidth, height: canvas.offsetHeight }
+        return { x: left, y: top, width: target.offsetWidth, height: target.offsetHeight }
       }, idx)
 
       if (clipRect && clipRect.width > 0 && clipRect.height > 0) {

package/lib/qa/checks.ts

@@ -25,7 +25,7 @@ export type IssueSeverity = "error" | "warning" | "info"
 export interface LayoutIssue {
   type: "canvas" | "scrollbar" | "navigation" | "overflow" | "text_overflow" | "overlap" | "density" | "balance" | "symmetry" | "rhythm" | "compliance" | "asset"
   /** Sub-category within the dimension */
-  sub?: "size_mismatch" | "page_scroll" | "fixed_overlay_slides" | "hidden_paging" | "unreachable_slides" | "text_clipped" | "thin_content"
+  sub?: "size_mismatch" | "missing_slide_canvas" | "multiple_slide_canvas" | "page_scroll" | "fixed_overlay_slides" | "hidden_paging" | "unreachable_slides" | "text_clipped" | "thin_content"
       | "element_collision" | "major_overlap" | "possible_overlay"
       | "centroid_offset" | "bottom_gap" | "sparse"
       | "height_mismatch" | "density_mismatch"
@@ -188,6 +188,26 @@ function collectLeaves(el: ElementInfo): ElementInfo[] {
 function checkCanvas(metrics: SlideMetrics): LayoutIssue[] {
   const issues: LayoutIssue[] = []
   const tol = T.CANVAS_TOLERANCE
+  const directCanvasCount = metrics.directSlideCanvasCount ?? 1
+  if (directCanvasCount === 0) {
+    issues.push({
+      type: "canvas",
+      sub: "missing_slide_canvas",
+      severity: "error",
+      detail: "Each .slide must have a direct .slide-canvas child.",
+    })
+    return issues
+  }
+  if (directCanvasCount > 1) {
+    issues.push({
+      type: "canvas",
+      sub: "multiple_slide_canvas",
+      severity: "error",
+      detail: `Each .slide must have exactly one direct .slide-canvas child. Found ${directCanvasCount}.`,
+      data: { directSlideCanvasCount: directCanvasCount },
+    })
+  }
+
   const canvasBad = Math.abs(metrics.canvasRect.width - CANVAS_W) > tol || Math.abs(metrics.canvasRect.height - CANVAS_H) > tol
   const slideBad = Math.abs(metrics.slideRect.width - CANVAS_W) > tol || Math.abs(metrics.slideRect.height - CANVAS_H) > tol
 

package/lib/qa/measure.ts

@@ -89,6 +89,8 @@ export interface SlideMetrics {
    * Content-heavy layouts set `slide-qa="true"`; structural/sparse slides omit or use `"false"`.
    */
   slideQa: boolean
+  /** Number of direct .slide-canvas children on the .slide element. */
+  directSlideCanvasCount: number
   /** bounding box of the slide-canvas element itself (post-scale) */
   canvasRect: Rect
   /** bounding box of the .slide element itself (post-scale) */
@@ -337,8 +339,35 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
           // Read the QA flag for deck metadata; default checks do not branch on it.
           const slideQa = (slide as HTMLElement).getAttribute("slide-qa") === "true"
 
-          const canvas = slide.querySelector(".slide-canvas") as HTMLElement | null
-          if (!canvas) return null
+          const directCanvases = Array.from(slide.children).filter((child) => child.classList.contains("slide-canvas")) as HTMLElement[]
+          const canvas = directCanvases[0] ?? null
+          if (!canvas) {
+            const slideRaw = (slide as HTMLElement).getBoundingClientRect()
+            const titleEl = slide.querySelector("h1, h2")
+            const title = titleEl
+              ? (titleEl.textContent || "").replace(/\s+/g, " ").trim().slice(0, 80)
+              : `Slide ${slideIdx + 1}`
+            const emptyRect = { left: 0, top: 0, right: 0, bottom: 0, width: 0, height: 0 }
+            return {
+              index: slideIdx,
+              title,
+              slideQa,
+              directSlideCanvasCount: directCanvases.length,
+              canvasRect: emptyRect,
+              slideRect: {
+                left: 0,
+                top: 0,
+                right: slideRaw.width,
+                bottom: slideRaw.height,
+                width: slideRaw.width,
+                height: slideRaw.height,
+              },
+              hasScrollbars: false,
+              elements: [],
+              contentRect: emptyRect,
+              contentStats: { bodyTextPoints: 0, contentUnits: 0, supportReferences: 0 },
+            }
+          }
 
           const canvasRaw = canvas.getBoundingClientRect()
           const slideRaw = (slide as HTMLElement).getBoundingClientRect()
@@ -407,6 +436,7 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
             index: slideIdx,
             title,
             slideQa,
+            directSlideCanvasCount: directCanvases.length,
             canvasRect,
             slideRect,
             hasScrollbars,

package/lib/runtime/index.ts

@@ -1,6 +1,16 @@
-import { existsSync } from "fs"
-import { resolve } from "path"
-import { activeDesign, activateDesign, getDesignSkillMd, listDesigns, seedBuiltinDesigns } from "../design/designs"
+import { createHash } from "crypto"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs"
+import { dirname, resolve } from "path"
+import {
+  activeDesign,
+  activateDesign,
+  createDesignPackage,
+  getDesignSection,
+  getDesignSkillMd,
+  listDesigns,
+  seedBuiltinDesigns,
+  validateDesignPackage,
+} from "../design/designs"
 import { createDeckFoundation as createDeckFoundationShell } from "../deck-html/foundation"
 import { activeDomain, activateDomain, getDomainSkillMd, listDomains, seedBuiltinDomains } from "../domain/domains"
 import { computeNarrativeHash } from "../narrative-state/hash"
@@ -32,7 +42,17 @@ export interface RuntimeDeckFoundationInput extends RuntimeWorkspaceInput {
 }
 
 export interface RuntimeDesignReadInput {
+  workspaceRoot?: string
   name?: string
+  section?: string
+}
+
+export interface RuntimeDesignCreateInput {
+  name: string
+  base?: string
+  designMd: string
+  previewHtml: string
+  overwrite?: boolean
 }
 
 export interface RuntimeNameInput {
@@ -166,6 +186,17 @@ export function designList() {
 export function designRead(input: RuntimeDesignReadInput = {}) {
   seedBuiltinDesigns()
   const name = input.name || activeDesign()
+  if (input.section) {
+    const markdown = getDesignSection(input.section, name)
+    const result = {
+      ok: true,
+      name,
+      section: input.section,
+      markdown,
+    }
+    if (input.section === "rules") recordDesignRulesRead(root(input.workspaceRoot), name, markdown)
+    return result
+  }
   return {
     ok: true,
     name,
@@ -173,6 +204,82 @@ export function designRead(input: RuntimeDesignReadInput = {}) {
   }
 }
 
+export function designCreate(input: RuntimeDesignCreateInput) {
+  seedBuiltinDesigns()
+  return createDesignPackage({
+    name: requiredString(input?.name, "design name"),
+    base: input.base,
+    designMd: requiredString(input?.designMd, "designMd"),
+    previewHtml: requiredString(input?.previewHtml, "previewHtml"),
+    overwrite: input.overwrite ?? false,
+  })
+}
+
+export function designValidate(input: RuntimeNameInput) {
+  seedBuiltinDesigns()
+  return validateDesignPackage(requiredName(input, "design"))
+}
+
+export interface DesignRulesReadinessResult {
+  ok: boolean
+  activeDesign: string
+  markerPath: string
+  reason?: string
+}
+
+const DESIGN_RULES_MARKER_TTL_MS = 8 * 60 * 60 * 1000
+
+export function checkDesignRulesReadiness(input: RuntimeWorkspaceInput = {}): DesignRulesReadinessResult {
+  seedBuiltinDesigns()
+  const workspaceRoot = root(input.workspaceRoot)
+  const design = activeDesign()
+  const rules = getDesignSection("rules", design)
+  const markerPath = designRulesMarkerPath(workspaceRoot)
+  if (!existsSync(markerPath)) {
+    return { ok: false, activeDesign: design, markerPath, reason: "Design rules have not been read for this workspace." }
+  }
+
+  let marker: any
+  try {
+    marker = JSON.parse(readFileSync(markerPath, "utf-8"))
+  } catch {
+    return { ok: false, activeDesign: design, markerPath, reason: "Design rules marker is unreadable." }
+  }
+
+  if (marker.designName !== design) {
+    return { ok: false, activeDesign: design, markerPath, reason: `Design rules marker is for '${marker.designName ?? "unknown"}', but active design is '${design}'.` }
+  }
+  if (marker.rulesHash !== hashDesignRules(rules)) {
+    return { ok: false, activeDesign: design, markerPath, reason: "Design rules marker is stale for the current active design rules." }
+  }
+  if (typeof marker.readAt !== "string" || Number.isNaN(Date.parse(marker.readAt))) {
+    return { ok: false, activeDesign: design, markerPath, reason: "Design rules marker is missing a valid read timestamp." }
+  }
+  if (Date.now() - Date.parse(marker.readAt) > DESIGN_RULES_MARKER_TTL_MS) {
+    return { ok: false, activeDesign: design, markerPath, reason: "Design rules marker is older than 8 hours." }
+  }
+
+  return { ok: true, activeDesign: design, markerPath }
+}
+
+function recordDesignRulesRead(workspaceRoot: string, designName: string, rules: string): void {
+  const markerPath = designRulesMarkerPath(workspaceRoot)
+  mkdirSync(dirname(markerPath), { recursive: true })
+  writeFileSync(markerPath, JSON.stringify({
+    designName,
+    rulesHash: hashDesignRules(rules),
+    readAt: new Date().toISOString(),
+  }, null, 2) + "\n", "utf-8")
+}
+
+function designRulesMarkerPath(workspaceRoot: string): string {
+  return resolve(workspaceRoot, ".opencode", "revela", "codex-hooks", "design-rules-read.json")
+}
+
+function hashDesignRules(rules: string): string {
+  return createHash("sha256").update(rules).digest("hex")
+}
+
 export function designActivate(input: RuntimeNameInput) {
   seedBuiltinDesigns()
   activateDesign(requiredName(input, "design"))
@@ -232,3 +339,9 @@ function requiredName(input: RuntimeNameInput, label: string): string {
   if (!name) throw new Error(`${label} name is required`)
   return name
 }
+
+function requiredString(value: string | undefined, label: string): string {
+  const text = value?.trim()
+  if (!text) throw new Error(`${label} is required`)
+  return text
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.17.16",
+  "version": "0.17.18",
   "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.17.16", "mcp"]
+      "args": ["-y", "@cyber-dash-tech/revela@0.17.18", "mcp"]
     }
   }
 }

package/plugins/revela/hooks/hooks.json

@@ -19,7 +19,7 @@
           {
             "type": "command",
             "command": "bun ${PLUGIN_ROOT}/hooks/revela_post_write_notice.ts",
-            "statusMessage": "Checking Revela QA reminders"
+            "statusMessage": "Running Revela post-write QA"
           }
         ]
       }

package/plugins/revela/hooks/revela_guard.ts

@@ -1,10 +1,83 @@
-const input = await new Response(Bun.stdin.stream()).text()
+import { dirname, resolve } from "path"
+import { fileURLToPath, pathToFileURL } from "url"
+import { resolveRevelaRuntime } from "../mcp/runtime-resolver"
+import { workspaceRootFromInput } from "./revela_post_write_notice"
 
-if (input.includes("DECKS.json")) {
-  console.error("Revela controls DECKS.json. Use Revela MCP/runtime tools or file-native narrative files instead of direct DECKS.json patches.")
-  process.exit(2)
+interface HookResult {
+  ok: boolean
+  messages: string[]
 }
 
-process.exit(0)
+const controlledStateFile = "DECKS" + ".json"
 
-export {}
+export async function runPreWriteChecks(input: string): Promise<HookResult> {
+  const messages: string[] = []
+
+  if (input.includes(controlledStateFile)) {
+    messages.push(`Revela controls ${controlledStateFile}. Use Revela MCP/runtime tools or file-native narrative files instead of direct ${controlledStateFile} patches.`)
+  }
+
+  const deckTargets = extractDeckHtmlPatchTargets(input)
+  if (deckTargets.length > 0) {
+    const pluginRoot = resolve(process.env.PLUGIN_ROOT || dirname(dirname(fileURLToPath(import.meta.url))))
+    const runtime = resolveRevelaRuntime({ pluginRoot })
+    if (!runtime.ok || !runtime.runtimePath) {
+      messages.push([
+        "Revela deck HTML patch blocked because Codex could not locate the Revela runtime to verify active design rules.",
+        ...runtime.diagnostics.map((item) => `- ${item}`),
+      ].join("\n"))
+    } else {
+      const workspaceRoot = workspaceRootFromInput(input)
+      const runtimeModule = await import(pathToFileURL(runtime.runtimePath).href)
+      const result = runtimeModule.checkDesignRulesReadiness({ workspaceRoot })
+      if (!result.ok) {
+        messages.push([
+          "Revela deck HTML patch blocked: active design rules must be loaded before patching `decks/*.html`.",
+          `Reason: ${result.reason ?? "Design rules marker is missing or stale."}`,
+          `Active design: ${result.activeDesign ?? "unknown"}`,
+          "Next step: call `revela_design_read` with `section: \"rules\"` for this workspace, then retry the patch.",
+          "Deck slides must use `<section class=\"slide\" ...><div class=\"slide-canvas\">...</div></section>` with exactly one direct `.slide-canvas` child.",
+        ].join("\n"))
+      }
+    }
+  }
+
+  return { ok: messages.length === 0, messages }
+}
+
+export function extractDeckHtmlPatchTargets(input: string): string[] {
+  const targets = new Set<string>()
+  for (const patch of patchPayloads(input)) {
+    const pattern = /(?:^\*\*\* Update File: |^\*\*\* Add File: )([^\r\n]*decks\/[^\r\n]+\.html)\s*$/gm
+    let match: RegExpExecArray | null
+    while ((match = pattern.exec(patch))) targets.add(match[1].trim())
+  }
+  return [...targets].sort((a, b) => a.localeCompare(b))
+}
+
+function patchPayloads(input: string): string[] {
+  try {
+    const parsed = JSON.parse(input)
+    return [
+      parsed.patch,
+      parsed.args?.patch,
+      parsed.tool_input?.patch,
+      parsed.toolInput?.patch,
+    ].filter((item): item is string => typeof item === "string")
+  } catch {
+    return [input]
+  }
+}
+
+if (import.meta.main) {
+  const input = await new Response(Bun.stdin.stream()).text()
+  try {
+    const result = await runPreWriteChecks(input)
+    if (result.messages.length > 0) console.error(result.messages.join("\n\n---\n\n"))
+    process.exit(result.ok ? 0 : 2)
+  } catch (e) {
+    console.error("Revela pre-write hook failed to run.")
+    console.error(e instanceof Error ? e.message : String(e))
+    process.exit(2)
+  }
+}

package/plugins/revela/hooks/revela_post_write_notice.ts

@@ -1,18 +1,90 @@
-const input = await new Response(Bun.stdin.stream()).text()
-const notices: string[] = []
+import { dirname, resolve } from "path"
+import { fileURLToPath, pathToFileURL } from "url"
+import { resolveRevelaRuntime } from "../mcp/runtime-resolver"
 
-if (/revela-narrative\/.*\.md/.test(input)) {
-  notices.push("Revela narrative Markdown changed. Run `revela_markdown_qa` and `revela_compile_narrative` before treating the graph as usable.")
+interface HookResult {
+  ok: boolean
+  messages: string[]
 }
 
-if (/decks\/.*\.html/.test(input)) {
-  notices.push("Revela deck HTML changed. Run `revela_run_deck_qa` before review or export.")
+export function extractDeckHtmlTargets(input: string): string[] {
+  const targets = new Set<string>()
+  const patterns = [
+    /\bdecks\/[^\s"'`<>]+\.html\b/g,
+    /(?:^\*\*\* Update File: |^\*\*\* Add File: )([^\r\n]+decks\/[^\r\n]+\.html)\s*$/gm,
+  ]
+
+  for (const pattern of patterns) {
+    let match: RegExpExecArray | null
+    while ((match = pattern.exec(input))) {
+      targets.add((match[1] ?? match[0]).trim())
+    }
+  }
+
+  return [...targets].sort((a, b) => a.localeCompare(b))
 }
 
-if (notices.length > 0) {
-  console.error(notices.join("\n"))
+export function workspaceRootFromInput(input: string): string {
+  try {
+    const parsed = JSON.parse(input)
+    const candidates = [
+      parsed.workspaceRoot,
+      parsed.cwd,
+      parsed.root,
+      parsed.tool_input?.workspaceRoot,
+      parsed.tool_input?.cwd,
+      parsed.toolInput?.workspaceRoot,
+      parsed.toolInput?.cwd,
+    ]
+    for (const candidate of candidates) {
+      if (typeof candidate === "string" && candidate.trim()) return resolve(candidate)
+    }
+  } catch {
+    // Hook payloads are not guaranteed to be JSON across Codex versions.
+  }
+  return resolve(process.env.CODEX_WORKSPACE_ROOT || process.env.PWD || process.cwd())
 }
 
-process.exit(0)
+export async function runPostWriteChecks(input: string): Promise<HookResult> {
+  const messages: string[] = []
+  if (/revela-narrative\/.*\.md/.test(input)) {
+    messages.push("Revela narrative Markdown changed. Run `revela_markdown_qa` and `revela_compile_narrative` before treating the graph as usable.")
+  }
+
+  const deckTargets = extractDeckHtmlTargets(input)
+  if (deckTargets.length === 0) return { ok: true, messages }
+
+  const pluginRoot = resolve(process.env.PLUGIN_ROOT || dirname(dirname(fileURLToPath(import.meta.url))))
+  const runtime = resolveRevelaRuntime({ pluginRoot })
+  if (!runtime.ok || !runtime.runtimePath) {
+    messages.push([
+      "Revela deck HTML changed, but Codex hook could not locate the Revela runtime to run Artifact QA.",
+      ...runtime.diagnostics.map((item) => `- ${item}`),
+    ].join("\n"))
+    return { ok: false, messages }
+  }
 
-export {}
+  const workspaceRoot = workspaceRootFromInput(input)
+  const runtimeModule = await import(pathToFileURL(runtime.runtimePath).href)
+  let ok = true
+  for (const target of deckTargets) {
+    const result = await runtimeModule.runDeckQa({ workspaceRoot, file: target })
+    messages.push(result.markdown ?? JSON.stringify(result, null, 2))
+    if (!result.ok) ok = false
+  }
+
+  return { ok, messages }
+}
+
+if (import.meta.main) {
+  const input = await new Response(Bun.stdin.stream()).text()
+  try {
+    const result = await runPostWriteChecks(input)
+    if (result.messages.length > 0) console.error(result.messages.join("\n\n---\n\n"))
+    process.exit(result.ok ? 0 : 2)
+  } catch (e) {
+    console.error("Revela post-write Artifact QA failed to run.")
+    console.error(e instanceof Error ? e.message : String(e))
+    process.exit(2)
+  }
+}

package/plugins/revela/mcp/revela-server.ts

@@ -20,6 +20,8 @@ type RuntimeModule = {
   designList(): any
   designRead(input?: any): any
   designActivate(input: any): any
+  designCreate(input: any): any
+  designValidate(input: any): any
   domainList(): any
   domainRead(input?: any): any
   domainActivate(input: any): any
@@ -105,13 +107,33 @@ const tools = [
   {
     name: "revela_design_read",
     description: "Read Revela design instructions for the active or requested design.",
-    inputSchema: objectSchema({ name: stringProp("Optional design name.") }),
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root. Used to record deck-write hook context when section is rules."),
+      name: stringProp("Optional design name."),
+      section: stringProp("Optional design section, such as rules, foundation, or chart-rules."),
+    }),
   },
   {
     name: "revela_design_activate",
     description: "Activate a Revela design for future deck planning and artifact generation.",
     inputSchema: objectSchema({ name: requiredStringProp("Design name to activate.") }, ["name"]),
   },
+  {
+    name: "revela_design_create",
+    description: "Create and validate a local Revela design package from complete DESIGN.md and preview.html content.",
+    inputSchema: objectSchema({
+      name: requiredStringProp("Design name in kebab-case."),
+      base: stringProp("Optional base design used as structural scaffold."),
+      designMd: requiredStringProp("Complete DESIGN.md content."),
+      previewHtml: requiredStringProp("Complete preview.html content."),
+      overwrite: booleanProp("Whether to replace an existing local design package. Defaults to false."),
+    }, ["name", "designMd", "previewHtml"]),
+  },
+  {
+    name: "revela_design_validate",
+    description: "Validate a local Revela design package.",
+    inputSchema: objectSchema({ name: requiredStringProp("Design name to validate.") }, ["name"]),
+  },
   {
     name: "revela_domain_list",
     description: "List installed Revela narrative domains and the active domain.",
@@ -254,6 +276,8 @@ async function callTool(name: string, args: any): Promise<any> {
   if (name === "revela_design_list") return r.designList()
   if (name === "revela_design_read") return r.designRead(args)
   if (name === "revela_design_activate") return r.designActivate(args)
+  if (name === "revela_design_create") return r.designCreate(args)
+  if (name === "revela_design_validate") return r.designValidate(args)
   if (name === "revela_domain_list") return r.domainList()
   if (name === "revela_domain_read") return r.domainRead(args)
   if (name === "revela_domain_activate") return r.domainActivate(args)

package/plugins/revela/skills/revela-design/SKILL.md

@@ -10,11 +10,25 @@ Use this skill when the user asks about Revela designs or when generating deck H
 ## Workflow
 
 1. Call `revela_design_list` to inspect installed designs.
-2. Call `revela_design_read` for the active or requested design.
+2. Call `revela_design_read` with `section: "rules"` before writing or patching `decks/*.html`; this records the Codex hook context required for deck writes.
 3. When the user asks to switch designs for future work, call `revela_design_activate` with the requested design name, then read the active design again.
 4. For one-off deck generation with a requested design, read that design by name and pass `designName` to `revela_create_deck_foundation` without changing active design unless the user asked to switch.
 5. Use the current simplified built-in design grammar: `box`, `text-panel`, `media`, `echart-panel`, `data-table`, `steps`, `roadmap-horizontal`, `roadmap-vertical`, `hero`, `stat-card`, `quote`, `toc`, `page-number`, and `brand-watermark`.
 6. Fetch chart/design guidance before creating ECharts or complex layouts.
 7. Do not invent unsupported component names.
 
+Deck HTML must keep exactly one direct `.slide-canvas` child inside every `<section class="slide" ...>`; place `.page` or layout containers inside `.slide-canvas`, not directly under `.slide`.
+
 Design changes are visual/artifact-level unless they change claim meaning, evidence boundaries, decision, or recommendation.
+
+## Creating Or Editing Designs
+
+When the user asks to create a new design, use `starter` as the default base design unless they specify another base. Interview the user before saving anything: collect visual references such as images, webpages, brands, decks, or text descriptions, plus must-have and must-avoid constraints. Summarize the design brief and visual schema, then wait for the user to confirm before creating files.
+
+After confirmation, read the base design with `revela_design_read`. Generate complete `DESIGN.md` and complete `preview.html` content, then call `revela_design_create`. For edits to an existing design, read the existing design first, preserve useful layout/component coverage, and call `revela_design_create` with `overwrite: true` only after the user confirms the edit brief. Always call `revela_design_validate` after creation or overwrite.
+
+`DESIGN.md` must include frontmatter with `name`, `description`, `author`, and `version`, plus valid marker blocks for `@design:foundation`, `@design:rules`, at least one `@layout`, and at least one `@component`.
+
+`preview.html` must be self-contained and directly openable in a browser. Every `<section class="slide">` must include `slide-qa` and exactly one direct `.slide-canvas` child. Include a cover slide with `data-slide-role="cover"`, a closing slide with `data-slide-role="closing"`, and a visible sample for every `@component:*` using `data-preview-component="<component-name>"`.
+
+Do not automatically activate a newly created design. Report the saved path and tell the user they can activate it with `revela_design_activate`.

package/plugins/revela/skills/revela-export/SKILL.md

@@ -16,6 +16,6 @@ Use this skill when the user asks to export a Revela deck.
 
 `revela_run_deck_qa`, `revela_export_pdf`, and `revela_export_pptx` may launch a browser. In sandboxed Codex sessions, request user-approved command escalation when the browser cannot start inside the default sandbox.
 
-Deck writes run post-write QA automatically. Do not run artifact QA as a pre-export blocker unless the user explicitly asks for diagnostics.
+Post-write hooks and explicit QA tools surface Artifact QA failures. If the latest visible QA result has hard errors, repair them before treating the deck as export-ready.
 
 Do not treat narrative gaps as export blockers unless they affect technical artifact validity or data safety.

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

@@ -23,8 +23,8 @@ Use this skill when the user asks to make, generate, or update a Revela deck.
 5. Report deck-plan diagnostics before artifact generation, including stale narrative hashes, missing slide projections, missing evidence trace, caveats, or malformed plan files.
 6. Do not start HTML generation from narrative alone unless the user explicitly asks for a throwaway diagnostic smoke deck.
 7. For new HTML files, call `revela_create_deck_foundation`.
-8. Read active design guidance with `revela_design_list` and `revela_design_read` when choosing layouts/components. If the user asks to switch designs persistently, call `revela_design_activate`; if they ask for a one-off design, read that design by name and pass `designName` to `revela_create_deck_foundation`.
-9. Patch slides into the foundation between Revela slide markers. Preserve positive 1-based `data-slide-index` values.
+8. Read active design guidance with `revela_design_list` and `revela_design_read` using `section: "rules"` before writing `decks/*.html`; fetch layouts/components/chart rules as needed. If the user asks to switch designs persistently, call `revela_design_activate`; if they ask for a one-off design, read that design by name and pass `designName` to `revela_create_deck_foundation`.
+9. Patch slides into the foundation between Revela slide markers. Preserve positive 1-based `data-slide-index` values. Every slide must use `<section class="slide" ...>` with exactly one direct `.slide-canvas` child.
 10. Generate chapter by chapter. Keep the HTML valid after each write.
 11. After every HTML write, call `revela_run_deck_qa` and repair hard errors before review or export.
 

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

@@ -17,7 +17,7 @@ Use this skill when the user asks to review, inspect, diagnose, or refine a gene
 6. Do not call `revela_run_deck_qa`, `revela_compile_narrative`, or `revela_read_deck_plan` separately for a normal Review UI open.
 7. Call `revela_run_deck_qa` separately only for focused low-level artifact QA, after a repair, or when the user explicitly asks for QA detail.
 8. Separate technical blockers from narrative/evidence diagnostics.
-9. Pure visual/layout/export fixes may patch artifacts directly when the user asks for a change. Meaning changes must update `revela-narrative/` first.
+9. Pure visual/layout/export fixes may patch artifacts directly when the user asks for a change, but read active design rules first with `revela_design_read` using `section: "rules"`. Meaning changes must update `revela-narrative/` first.
 
 ## Generated Visual Assets
 
@@ -34,6 +34,7 @@ Use this skill when the user asks to review, inspect, diagnose, or refine a gene
 - `revela_review_deck_open` opens the local Review server from the MCP process and uses the Codex `codex-exec` bridge for Insight and Comment/Apply Fix. It returns URL/token/open state and basic file metadata, not aggregate diagnostics.
 - `revela_run_deck_qa` may need browser-launch permission in Codex sandboxed sessions.
 - Repair hard QA errors before treating a deck as review-ready.
+- Deck slides must use `<section class="slide" ...>` with exactly one direct `.slide-canvas` child; missing, nested, or duplicate slide canvases are hard artifact failures.
 - Text clipping should usually be fixed with typography and spacing changes, not by deleting evidence or changing claim meaning.
 - A warning that a smoke/development artifact is not the active legacy deck target is non-blocking when the requested file passes hard artifact checks.