@cyber-dash-tech/revela 0.17.22 → 0.17.24

package/lib/design/designs.ts

@@ -1,11 +1,9 @@
 /**
  * DesignManager — manage revela visual design templates.
  *
- * Designs are stored in ~/.config/revela/designs/<name>/.
+ * User designs are stored in ~/.config/revela/designs/<name>/.
+ * Built-in designs are shipped read-only with this package under designs/<name>/.
  * Each design directory contains DESIGN.md (required) and optionally preview.html.
- *
- * Built-in designs are shipped with the npm package under designs/ and seeded
- * to the config directory on first run.
  */
 
 import {
@@ -152,21 +150,46 @@ export function parseDesignFile(filePath: string): DesignInfo | null {
 // Public API
 // ---------------------------------------------------------------------------
 
-/** List installed designs, sorted by name. Internal designs are hidden by default. */
+function designDirHasPackage(dir: string): boolean {
+  return existsSync(dir) && statSync(dir).isDirectory() && existsSync(join(dir, "DESIGN.md"))
+}
+
+function resolveDesignDir(nameInput?: string): string | null {
+  const name = normalizeDesignName(nameInput || activeDesign())
+  const userDir = join(DESIGNS_DIR, name)
+  if (designDirHasPackage(userDir)) return userDir
+
+  const bundledDir = join(SEED_DIR, name)
+  if (designDirHasPackage(bundledDir)) return bundledDir
+
+  return null
+}
+
+function readDesignsFromDir(root: string): Map<string, DesignInfo> {
+  const designs = new Map<string, DesignInfo>()
+  if (!existsSync(root)) return designs
+
+  for (const entry of readdirSync(root).sort()) {
+    const dir = join(root, entry)
+    if (!designDirHasPackage(dir)) continue
+    const info = parseDesignFile(join(dir, "DESIGN.md"))
+    if (info) designs.set(entry, info)
+  }
+  return designs
+}
+
+/** List available designs, sorted by name. User designs override bundled designs with the same name. Internal designs are hidden by default. */
 export function listDesigns(options: ListDesignsOptions = {}): DesignInfo[] {
-  if (!existsSync(DESIGNS_DIR)) return []
-  const results: DesignInfo[] = []
   const includeInternal = options.includeInternal ?? false
+  const available = readDesignsFromDir(SEED_DIR)
 
-  for (const entry of readdirSync(DESIGNS_DIR).sort()) {
-    const dir = join(DESIGNS_DIR, entry)
-    if (!statSync(dir).isDirectory()) continue
-    const mdPath = join(dir, "DESIGN.md")
-    if (!existsSync(mdPath)) continue
-    const info = parseDesignFile(mdPath)
-    if (info && (includeInternal || !info.internal)) results.push(info)
+  for (const [entry, info] of readDesignsFromDir(DESIGNS_DIR)) {
+    available.set(entry, info)
   }
-  return results
+
+  return [...available.values()]
+    .filter((info) => includeInternal || !info.internal)
+    .sort((a, b) => a.name.localeCompare(b.name))
 }
 
 /** Get the name of the currently active design. */
@@ -187,11 +210,12 @@ export function activateDesign(name: string): void {
 
 /** Get the skill text body from a design's DESIGN.md. */
 export function getDesignSkillMd(name?: string): string {
-  const designName = name || activeDesign()
-  const mdPath = join(DESIGNS_DIR, designName, "DESIGN.md")
-  if (!existsSync(mdPath)) {
+  const designName = normalizeDesignName(name || activeDesign())
+  const designDir = resolveDesignDir(designName)
+  if (!designDir) {
     throw new Error(`Design '${designName}' is not installed`)
   }
+  const mdPath = join(designDir, "DESIGN.md")
   const info = parseDesignFile(mdPath)
   if (!info) {
     throw new Error(`Failed to parse DESIGN.md for '${designName}'`)
@@ -202,9 +226,8 @@ export function getDesignSkillMd(name?: string): string {
 /** Resolve a design's preview.html path. Throws if the design is not installed. */
 export function resolveDesignPreview(name?: string): DesignPreviewInfo {
   const designName = normalizeDesignName(name || activeDesign())
-  const designDir = join(DESIGNS_DIR, designName)
-  const mdPath = join(designDir, "DESIGN.md")
-  if (!existsSync(designDir) || !existsSync(mdPath)) {
+  const designDir = resolveDesignDir(designName)
+  if (!designDir) {
     throw new Error(`Design '${designName}' is not installed`)
   }
 
@@ -388,12 +411,15 @@ function hasFixedSizeCssRule(html: string, className: "slide-canvas"): boolean {
 /** Validate a local design package for the minimum Revela design contract. */
 export function validateDesignPackage(nameInput: string): ValidateDesignPackageResult {
   let name = nameInput
+  let hasValidName = true
   try {
     name = normalizeDesignName(nameInput)
   } catch {
+    hasValidName = false
     // validateDesignPackageAt records the invalid-name error.
   }
-  return validateDesignPackageAt(nameInput, join(DESIGNS_DIR, name))
+  const dir = hasValidName ? resolveDesignDir(name) || join(DESIGNS_DIR, name) : join(DESIGNS_DIR, name)
+  return validateDesignPackageAt(nameInput, dir)
 }
 
 function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesignPackageResult {
@@ -493,6 +519,25 @@ export interface DesignSections {
   hasMarkers: boolean
 }
 
+export interface DesignInventoryLayout {
+  name: string
+  qa: boolean
+  description: string
+}
+
+export interface DesignInventoryComponent {
+  name: string
+  description: string
+}
+
+export interface DesignInventory {
+  name: string
+  sections: string[]
+  layouts: DesignInventoryLayout[]
+  components: DesignInventoryComponent[]
+  hasMarkers: boolean
+}
+
 /**
  * Parse a DESIGN.md body (no frontmatter) into sections, layouts, and components
  * using the three-layer HTML comment marker convention:
@@ -566,7 +611,7 @@ export function generateComponentIndex(components: Record<string, string>): stri
     "|---|---|",
     ...rows,
     "",
-    "_Use `revela-designs` tool with `action: \"read\"` and `component: \"<name>\"` to get full CSS/HTML for any component._",
+    "_Use `revela_design_read_component` with `component: \"<name>\"` to get full CSS/HTML for any component._",
   ].join("\n")
 }
 
@@ -598,10 +643,47 @@ export function generateLayoutIndex(layouts: Record<string, LayoutInfo>): string
     "|---|---|---|",
     ...rows,
     "",
-    "_Use `revela-designs` tool with `action: \"read\"` and `layout: \"<name>\"` to get full HTML/CSS for any layout._",
+    "_Use `revela_design_read_layout` with `layout: \"<name>\"` to get full HTML/CSS for any layout._",
   ].join("\n")
 }
 
+export function getDesignInventory(designName?: string): DesignInventory {
+  const name = normalizeDesignName(designName || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) {
+    throw new Error(`Design '${name}' is not installed`)
+  }
+  const mdPath = join(designDir, "DESIGN.md")
+  const text = readFileSync(mdPath, "utf-8")
+  const { body } = parseFrontmatter(text)
+  const { sections, layouts, components, hasMarkers } = parseDesignSections(body)
+
+  return {
+    name,
+    sections: Object.keys(sections),
+    layouts: Object.entries(layouts).map(([layoutName, layout]) => ({
+      name: layoutName,
+      qa: layout.qa,
+      description: designBlockDescription(layout.content),
+    })),
+    components: Object.entries(components).map(([componentName, content]) => ({
+      name: componentName,
+      description: designBlockDescription(content),
+    })),
+    hasMarkers,
+  }
+}
+
+function designBlockDescription(body: string): string {
+  const firstLine = body
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => line && !line.startsWith("<!--") && !line.startsWith("```"))
+  return firstLine
+    ? firstLine.replace(/^#+\s*/, "").replace(/\(.*?\)/, "").trim()
+    : ""
+}
+
 /**
  * Get the raw text of one or more named layouts from a DESIGN.md.
  * @param layoutNames - Comma-separated layout names or an array.
@@ -611,11 +693,12 @@ export function getDesignLayout(
   layoutNames: string | string[],
   designName?: string,
 ): string {
-  const name = designName || activeDesign()
-  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
-  if (!existsSync(mdPath)) {
+  const name = normalizeDesignName(designName || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) {
     throw new Error(`Design '${name}' is not installed`)
   }
+  const mdPath = join(designDir, "DESIGN.md")
   const text = readFileSync(mdPath, "utf-8")
   const { body } = parseFrontmatter(text)
   const { layouts, hasMarkers } = parseDesignSections(body)
@@ -644,11 +727,12 @@ export function getDesignLayout(
  * Throws if the design is not installed or the section doesn't exist.
  */
 export function getDesignSection(sectionName: string, designName?: string): string {
-  const name = designName || activeDesign()
-  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
-  if (!existsSync(mdPath)) {
+  const name = normalizeDesignName(designName || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) {
     throw new Error(`Design '${name}' is not installed`)
   }
+  const mdPath = join(designDir, "DESIGN.md")
   const text = readFileSync(mdPath, "utf-8")
   const { body } = parseFrontmatter(text)
   const { sections, hasMarkers } = parseDesignSections(body)
@@ -671,11 +755,12 @@ export function getDesignComponent(
   componentNames: string | string[],
   designName?: string,
 ): string {
-  const name = designName || activeDesign()
-  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
-  if (!existsSync(mdPath)) {
+  const name = normalizeDesignName(designName || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) {
     throw new Error(`Design '${name}' is not installed`)
   }
+  const mdPath = join(designDir, "DESIGN.md")
   const text = readFileSync(mdPath, "utf-8")
   const { body } = parseFrontmatter(text)
   const { components, hasMarkers } = parseDesignSections(body)
@@ -742,8 +827,7 @@ export async function installDesign(
 // ---------------------------------------------------------------------------
 
 function designExists(name: string): boolean {
-  const dir = join(DESIGNS_DIR, name)
-  return existsSync(dir) && existsSync(join(dir, "DESIGN.md"))
+  return resolveDesignDir(name) !== null
 }
 
 function installFromPath(srcPath: string, name?: string): string {
@@ -814,13 +898,13 @@ export interface DesignClassVocabulary {
  * Falls back to UNIVERSAL_CLASSES-only when the design has no markers.
  */
 export function extractDesignClasses(designName?: string): DesignClassVocabulary {
-  const name = designName || activeDesign()
-  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
-
-  if (!existsSync(mdPath)) {
+  const name = normalizeDesignName(designName || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) {
     return { classes: new Set(UNIVERSAL_CLASSES), prefixExemptions: DEFAULT_PREFIX_EXEMPTIONS }
   }
 
+  const mdPath = join(designDir, "DESIGN.md")
   const raw = readFileSync(mdPath, "utf-8")
   const { body } = parseFrontmatter(raw)
   const { sections, layouts, components, hasMarkers } = parseDesignSections(body)

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

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs"
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "fs"
 import { dirname, join, relative } from "path"
 import { createHash } from "crypto"
 import type { DeckSpec, SlideSpec } from "../decks-state"
@@ -81,6 +81,7 @@ export interface DeckPlanSlideProjection {
   chapter: string
   layout: string
   components: string[]
+  componentPlan: DeckPlanSlideComponentPlan[]
   structural: boolean
   narrativeRole: string
   markdown: string
@@ -89,6 +90,66 @@ export interface DeckPlanSlideProjection {
   links: DeckPlanNarrativeLink[]
 }
 
+export interface DeckPlanSlideComponentPlan {
+  name: string
+  slot: string
+  position: string
+  purpose: string
+  content: string
+  claimIds: string[]
+  evidenceIds: string[]
+  sourceNotes: string[]
+  renderNotes: string[]
+  placementNote?: string
+}
+
+export interface DeckPlanSlideUpsertComponentInput {
+  name: string
+  slot: string
+  position: string
+  purpose: string
+  content: string
+  claimIds?: string[]
+  evidenceIds?: string[]
+  sourceNotes?: string[]
+  renderNotes?: string[]
+  placementNote?: string
+}
+
+export interface DeckPlanSlideUpsertInput {
+  slideIndex: number
+  id?: string
+  title: string
+  chapter: string
+  narrativeRole: string
+  structural?: boolean
+  layout: string
+  components: DeckPlanSlideUpsertComponentInput[]
+  visualIntent: {
+    kind?: string
+    component?: string
+    rationale?: string
+    brief?: string
+  } | string
+  narrativeLinks: {
+    claimIds?: string[]
+    evidenceIds?: string[]
+    riskIds?: string[]
+    objectionIds?: string[]
+    gapIds?: string[]
+  }
+  caveats?: string[]
+}
+
+export interface DeckPlanSlideUpsertResult {
+  ok: boolean
+  path?: string
+  absolutePath?: string
+  updated?: boolean
+  slide?: DeckPlanSlideProjection
+  diagnostics: DeckPlanProjectionDiagnostic[]
+}
+
 export interface DeckPlanNarrativeLink {
   id: string
   relation: "uses_claim" | "uses_evidence" | "addresses_risk" | "answers_objection" | "mentions_gap"
@@ -247,6 +308,41 @@ export function deckPlanBodyHash(markdown: string): string {
   return createHash("sha1").update(stripApprovalSection(markdown).trim()).digest("hex")
 }
 
+export function upsertDeckPlanSlideArtifact(
+  workspaceRoot: string,
+  input: DeckPlanSlideUpsertInput,
+  options: { narrativeHash?: string; knownNodeIds?: Set<string>; designLayouts: string[]; designComponents: string[] },
+): DeckPlanSlideUpsertResult {
+  const diagnostics = validateDeckPlanSlideUpsert(input, options)
+  if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) return { ok: false, diagnostics }
+
+  mkdirSync(join(workspaceRoot, DECK_PLAN_SLIDES_DIR), { recursive: true })
+  ensureDeckPlanIndex(workspaceRoot, options.narrativeHash)
+
+  const existing = readDeckPlanProjection(workspaceRoot, { narrativeHash: options.narrativeHash, knownNodeIds: options.knownNodeIds })
+  const existingSlide = existing?.slides.find((slide) => slide.slideIndex === input.slideIndex)
+  const id = input.id?.trim() || existingSlide?.id || `slide-${slugify(input.title)}`
+  const filename = `${String(input.slideIndex).padStart(3, "0")}-${slugify(input.title)}.md`
+  const path = `${DECK_PLAN_SLIDES_DIR}/${filename}`
+  const absolutePath = join(workspaceRoot, path)
+  const markdown = renderDeckPlanSlideMarkdown({ ...input, id })
+
+  writeFileSync(absolutePath, markdown, "utf-8")
+  if (existingSlide && existingSlide.absolutePath !== absolutePath && existsSync(existingSlide.absolutePath)) {
+    try {
+      rmSync(existingSlide.absolutePath)
+    } catch {
+      // Empty stale files are ignored by readers only when removed; if removal fails,
+      // duplicate slideIndex diagnostics will surface on the next read.
+    }
+  }
+
+  updateDeckPlanIndex(workspaceRoot, options.narrativeHash)
+  const projection = readDeckPlanProjection(workspaceRoot, { narrativeHash: options.narrativeHash, knownNodeIds: options.knownNodeIds })
+  const slide = projection?.slides.find((item) => item.slideIndex === input.slideIndex)
+  return { ok: true, path, absolutePath, updated: Boolean(existingSlide), slide, diagnostics: [...diagnostics, ...(projection?.diagnostics ?? [])] }
+}
+
 function readDeckPlanSlideFiles(workspaceRoot: string, knownNodeIds?: Set<string>): DeckPlanSlideProjection[] {
   const slidesDir = join(workspaceRoot, DECK_PLAN_SLIDES_DIR)
   if (!existsSync(slidesDir) || !statSync(slidesDir).isDirectory()) return []
@@ -259,6 +355,7 @@ function readDeckPlanSlideFiles(workspaceRoot: string, knownNodeIds?: Set<string
     const split = splitMarkdownSections(parsed.body)
     const path = relativePath(workspaceRoot, absolutePath)
     const id = stringField(parsed.frontmatter, "id") || fileId(entry)
+    const componentPlan = parseDeckPlanComponentPlan(split.sections["component-plan"] ?? "")
     const links = parseDeckPlanNarrativeLinks(split.sections["narrative-links"] ?? parsed.body, knownNodeIds)
     slides.push({
       path,
@@ -269,6 +366,7 @@ function readDeckPlanSlideFiles(workspaceRoot: string, knownNodeIds?: Set<string
       chapter: stringField(parsed.frontmatter, "chapter"),
       layout: stringField(parsed.frontmatter, "layout"),
       components: arrayField(parsed.frontmatter, "components"),
+      componentPlan,
       structural: booleanField(parsed.frontmatter, "structural", false),
       narrativeRole: stringField(parsed.frontmatter, "narrativeRole"),
       markdown,
@@ -338,6 +436,14 @@ function deckPlanIndexDiagnostics(slides: DeckPlanSlideProjection[]): DeckPlanPr
 function slideDiagnostics(slide: DeckPlanSlideProjection, knownNodeIds?: Set<string>): DeckPlanProjectionDiagnostic[] {
   const diagnostics: DeckPlanProjectionDiagnostic[] = []
   if (!slide.structural && !slide.links.some((link) => link.relation === "uses_claim")) diagnostics.push({ severity: "warning", code: "slide_claim_link_missing", message: `Non-structural deck-plan slide ${slide.id} has no claim wikilink in ## Narrative Links.`, 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 })
+  for (const component of slide.componentPlan) {
+    for (const key of ["name", "slot", "position", "purpose", "content"] as const) {
+      if (!component[key] || (Array.isArray(component[key]) && component[key].length === 0)) diagnostics.push({ severity: "warning", code: "slide_component_plan_incomplete", message: `Deck-plan slide ${slide.id} has incomplete component plan entry for ${component.name || "unnamed component"}: missing ${key}.`, file: slide.path, nodeId: slide.id })
+    }
+  }
   if (knownNodeIds) {
     for (const link of slide.links) {
       if (!knownNodeIds.has(link.id)) diagnostics.push({ severity: "warning", code: "deck_plan_broken_link", message: `Deck-plan slide ${slide.id} links to unknown narrative node ${link.id}.`, file: slide.path, nodeId: slide.id })
@@ -346,6 +452,251 @@ function slideDiagnostics(slide: DeckPlanSlideProjection, knownNodeIds?: Set<str
   return diagnostics
 }
 
+export function deckPlanDesignDiagnostics(projection: DeckPlanProjection | undefined, inventory: { layouts: string[]; components: string[] }): DeckPlanProjectionDiagnostic[] {
+  if (!projection) return []
+  const layouts = new Set(inventory.layouts)
+  const components = new Set(inventory.components)
+  const diagnostics: DeckPlanProjectionDiagnostic[] = []
+  for (const slide of projection.slides) {
+    if (slide.layout && !layouts.has(slide.layout)) diagnostics.push({ severity: "warning", code: "slide_layout_unknown", message: `Deck-plan slide ${slide.id} uses layout '${slide.layout}' outside the active design inventory.`, file: slide.path, nodeId: slide.id })
+    for (const component of slide.components) {
+      if (!components.has(component)) diagnostics.push({ severity: "warning", code: "slide_component_unknown", message: `Deck-plan slide ${slide.id} uses component '${component}' outside the active design inventory.`, file: slide.path, nodeId: slide.id })
+    }
+    for (const component of slide.componentPlan) {
+      if (component.name && !components.has(component.name)) diagnostics.push({ severity: "warning", code: "slide_component_plan_unknown", message: `Deck-plan slide ${slide.id} component plan uses '${component.name}' outside the active design inventory.`, file: slide.path, nodeId: slide.id })
+    }
+  }
+  return diagnostics
+}
+
+function validateDeckPlanSlideUpsert(input: DeckPlanSlideUpsertInput, options: { designLayouts: string[]; designComponents: string[] }): DeckPlanProjectionDiagnostic[] {
+  const diagnostics: DeckPlanProjectionDiagnostic[] = []
+  const nodeId = input.id?.trim() || `slide-${input.slideIndex}`
+  if (!Number.isInteger(input.slideIndex) || input.slideIndex < 1) diagnostics.push(errorDiagnostic("slide_index_invalid", "slideIndex must be a positive 1-based integer.", nodeId))
+  for (const [key, value] of [["title", input.title], ["chapter", input.chapter], ["narrativeRole", input.narrativeRole], ["layout", input.layout]] as const) {
+    if (!String(value || "").trim()) diagnostics.push(errorDiagnostic(`slide_${key}_missing`, `${key} is required.`, nodeId))
+  }
+  if (!options.designLayouts.includes(input.layout)) diagnostics.push(errorDiagnostic("slide_layout_unknown", `Layout '${input.layout}' is not in the selected design inventory.`, nodeId))
+  if (!Array.isArray(input.components) || input.components.length === 0) diagnostics.push(errorDiagnostic("slide_components_missing", "At least one component plan entry is required.", nodeId))
+  const componentNames = new Set<string>()
+  const positions = new Set<string>()
+  for (const component of input.components ?? []) {
+    const name = component.name?.trim()
+    if (name) componentNames.add(name)
+    if (!name) diagnostics.push(errorDiagnostic("slide_component_name_missing", "Every component requires name.", nodeId))
+    else if (!options.designComponents.includes(name)) diagnostics.push(errorDiagnostic("slide_component_unknown", `Component '${name}' is not in the selected design inventory.`, nodeId))
+    for (const key of ["slot", "position", "purpose", "content"] as const) {
+      if (!String(component[key] || "").trim()) diagnostics.push(errorDiagnostic("slide_component_plan_incomplete", `Component '${name || "unnamed"}' is missing ${key}.`, nodeId))
+    }
+    if (component.position && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(component.position)) diagnostics.push(errorDiagnostic("slide_component_position_invalid", `Component '${name || "unnamed"}' position must be a non-empty kebab-case anchor.`, nodeId))
+    const positionKey = `${component.slot?.trim() || ""}:${component.position?.trim() || ""}`
+    if (component.slot?.trim() && component.position?.trim()) {
+      if (positions.has(positionKey)) diagnostics.push(errorDiagnostic("slide_component_position_duplicate", `Duplicate component slot/position '${positionKey}' makes the plan ambiguous.`, nodeId))
+      positions.add(positionKey)
+    }
+  }
+  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))
+  if (!input.structural && !((input.narrativeLinks?.claimIds?.length ?? 0) > 0 || (input.narrativeLinks?.evidenceIds?.length ?? 0) > 0)) diagnostics.push({ severity: "warning", code: "slide_narrative_link_missing", message: "Non-structural slides should include at least one claim or evidence narrative link.", nodeId })
+  return diagnostics
+}
+
+function errorDiagnostic(code: string, message: string, nodeId?: string): DeckPlanProjectionDiagnostic {
+  return { severity: "error", code, message, nodeId }
+}
+
+function parseDeckPlanComponentPlan(section: string): DeckPlanSlideComponentPlan[] {
+  const components: DeckPlanSlideComponentPlan[] = []
+  let current: DeckPlanSlideComponentPlan | undefined
+  let capture: "content" | undefined
+  const flush = () => {
+    if (current) components.push({
+      ...current,
+      content: current.content.trim(),
+      claimIds: uniqueStrings(current.claimIds),
+      evidenceIds: uniqueStrings(current.evidenceIds),
+      sourceNotes: current.sourceNotes.filter(Boolean),
+      renderNotes: current.renderNotes.filter(Boolean),
+    })
+  }
+  for (const rawLine of section.replace(/\r\n/g, "\n").split("\n")) {
+    const heading = /^###\s+(.+?)\s*$/.exec(rawLine)
+    if (heading) {
+      flush()
+      current = { name: heading[1].trim(), slot: "", position: "", purpose: "", content: "", claimIds: [], evidenceIds: [], sourceNotes: [], renderNotes: [] }
+      capture = undefined
+      continue
+    }
+    if (!current) continue
+    const line = rawLine.trim()
+    const field = /^-\s+([A-Za-z][A-Za-z ]+):\s*(.*)$/.exec(line)
+    if (field) {
+      capture = undefined
+      const key = field[1].toLowerCase()
+      const value = field[2].trim()
+      if (key === "slot") current.slot = value
+      else if (key === "position") current.position = value
+      else if (key === "placement note") current.placementNote = value
+      else if (key === "purpose") current.purpose = value
+      else if (key === "content") {
+        current.content = cleanPlanValue(value)
+        capture = value ? undefined : "content"
+      } else if (key === "claim ids") current.claimIds = parseCsv(value)
+      else if (key === "evidence ids") current.evidenceIds = parseCsv(value)
+      else if (key === "source notes") current.sourceNotes = parseListValue(value)
+      else if (key === "render notes") current.renderNotes = parseListValue(value)
+      continue
+    }
+    if (capture === "content" && rawLine.trim()) current.content += `${current.content ? "\n" : ""}${rawLine.replace(/^\s{2}/, "")}`
+  }
+  flush()
+  return components
+}
+
+function renderDeckPlanSlideMarkdown(input: DeckPlanSlideUpsertInput & { id: string }): string {
+  const components = input.components.map((component) => component.name.trim())
+  const lines: string[] = []
+  lines.push("---")
+  lines.push("type: deck-plan-slide")
+  lines.push(`id: ${input.id}`)
+  lines.push(`slideIndex: ${input.slideIndex}`)
+  lines.push(`title: ${yamlScalar(input.title)}`)
+  lines.push(`chapter: ${yamlScalar(input.chapter)}`)
+  lines.push(`layout: ${input.layout.trim()}`)
+  lines.push(`components: [${components.map(yamlScalar).join(", ")}]`)
+  lines.push(`structural: ${input.structural ? "true" : "false"}`)
+  lines.push(`narrativeRole: ${yamlScalar(input.narrativeRole)}`)
+  lines.push("---")
+  lines.push("")
+  lines.push(`# ${input.title.trim()}`)
+  lines.push("")
+  lines.push("## Purpose")
+  lines.push("")
+  lines.push(input.narrativeRole.trim())
+  lines.push("")
+  lines.push("## Visual Intent")
+  lines.push("")
+  lines.push(renderVisualIntent(input.visualIntent))
+  lines.push("")
+  lines.push("## Component Plan")
+  lines.push("")
+  for (const component of input.components) {
+    lines.push(`### ${component.name.trim()}`)
+    lines.push("")
+    lines.push(`- Slot: ${component.slot.trim()}`)
+    lines.push(`- Position: ${component.position.trim()}`)
+    if (component.placementNote?.trim()) lines.push(`- Placement note: ${component.placementNote.trim()}`)
+    lines.push(`- Purpose: ${component.purpose.trim()}`)
+    lines.push("- Content:")
+    lines.push(...indentMultiline(component.content.trim()))
+    lines.push(`- Claim ids: ${formatCsv(component.claimIds)}`)
+    lines.push(`- Evidence ids: ${formatCsv(component.evidenceIds)}`)
+    lines.push(`- Source notes: ${formatListValue(component.sourceNotes)}`)
+    lines.push(`- Render notes: ${formatListValue(component.renderNotes)}`)
+    lines.push("")
+  }
+  lines.push("## Narrative Links")
+  lines.push("")
+  lines.push("Claims:")
+  for (const id of input.narrativeLinks?.claimIds ?? []) lines.push(`- [[${id}]]`)
+  lines.push("")
+  lines.push("Evidence:")
+  for (const id of input.narrativeLinks?.evidenceIds ?? []) lines.push(`- [[${id}]]`)
+  lines.push("")
+  lines.push("Risks:")
+  for (const id of input.narrativeLinks?.riskIds ?? []) lines.push(`- [[${id}]]`)
+  lines.push("")
+  lines.push("Objections:")
+  for (const id of input.narrativeLinks?.objectionIds ?? []) lines.push(`- [[${id}]]`)
+  lines.push("")
+  lines.push("Gaps:")
+  for (const id of input.narrativeLinks?.gapIds ?? []) lines.push(`- [[${id}]]`)
+  lines.push("")
+  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")
+}
+
+function ensureDeckPlanIndex(workspaceRoot: string, narrativeHash?: string): void {
+  const absolutePath = join(workspaceRoot, DECK_PLAN_INDEX_PATH)
+  if (existsSync(absolutePath)) return
+  mkdirSync(dirname(absolutePath), { recursive: true })
+  writeFileSync(absolutePath, renderMinimalDeckPlanIndex(narrativeHash, []), "utf-8")
+}
+
+function updateDeckPlanIndex(workspaceRoot: string, narrativeHash?: string): void {
+  const projection = readDeckPlanProjection(workspaceRoot, { narrativeHash })
+  const slides = projection?.slides ?? []
+  writeFileSync(join(workspaceRoot, DECK_PLAN_INDEX_PATH), renderMinimalDeckPlanIndex(narrativeHash || projection?.narrativeHash, slides), "utf-8")
+}
+
+function renderMinimalDeckPlanIndex(narrativeHash: string | undefined, slides: DeckPlanSlideProjection[]): string {
+  const chapterMap = new Map<string, number[]>()
+  for (const slide of slides) {
+    const chapter = slide.chapter || "Unassigned"
+    chapterMap.set(chapter, [...(chapterMap.get(chapter) ?? []), slide.slideIndex ?? 0].filter(Boolean))
+  }
+  const lines: string[] = []
+  lines.push("---")
+  lines.push("id: deck-plan")
+  if (narrativeHash) lines.push(`narrativeHash: ${narrativeHash}`)
+  lines.push("---")
+  lines.push("")
+  lines.push("# Deck Plan")
+  lines.push("")
+  lines.push("## Source Authority")
+  lines.push("")
+  lines.push("- Meaning: `revela-narrative/` remains canonical.")
+  lines.push("- Render planning: `deck-plan/` is an execution projection, not approval state.")
+  lines.push("")
+  lines.push("## Audience / Goal / Decision")
+  lines.push("")
+  lines.push("- To be specified by narrative state and user intent.")
+  lines.push("")
+  lines.push("## Deck Parameters")
+  lines.push("")
+  lines.push(`- Slide count: ${slides.length}`)
+  if (narrativeHash) lines.push(`- Narrative hash: \`${narrativeHash}\``)
+  lines.push("")
+  lines.push("## Chapter Map")
+  lines.push("")
+  if (chapterMap.size === 0) lines.push("- No slides planned yet.")
+  else for (const [chapter, indexes] of chapterMap) lines.push(`- ${chapter}: slides ${formatSlideRange(indexes)}`)
+  lines.push("")
+  lines.push("## Slide Plan")
+  lines.push("")
+  if (slides.length === 0) lines.push("- No slide files yet.")
+  else for (const slide of slides) lines.push(`- Slide ${slide.slideIndex}: [[${slide.id}]] - ${slide.title} (${slide.path}); layout ${slide.layout || "unspecified"}; components ${slide.components.join(", ") || "none"}.`)
+  lines.push("")
+  lines.push("## Evidence Trace")
+  lines.push("")
+  const evidenceIds = uniqueStrings(slides.flatMap((slide) => slide.links.filter((link) => link.relation === "uses_evidence").map((link) => link.id)))
+  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("")
+  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.")
+  else for (const id of boundaryIds) lines.push(`- [[${id}]]`)
+  lines.push("")
+  lines.push("## Chapter Writing Batches")
+  lines.push("")
+  if (chapterMap.size === 0) lines.push("- No chapter batches yet.")
+  else for (const [chapter, indexes] of chapterMap) lines.push(`- ${chapter}: slides ${formatSlideRange(indexes)}.`)
+  lines.push("")
+  lines.push("## HTML Identity Contract")
+  lines.push("")
+  lines.push("- Render one `<section class=\"slide\" data-slide-index=\"N\">` per planned slide.")
+  lines.push("- Use positive 1-based slide indexes, unique indexes, DOM order, and one direct `.slide-canvas` child per slide.")
+  lines.push("")
+  return lines.join("\n")
+}
+
 function narrativeHashFromMarkdown(markdown: string): string {
   const match = markdown.match(/narrativeHash:\s*`?([^`\s]+)`?/)
   return match?.[1]?.trim() ?? ""
@@ -379,6 +730,80 @@ function arrayField(frontmatter: Record<string, string | string[] | boolean>, ke
   return []
 }
 
+function normalizeVisualIntent(input: DeckPlanSlideUpsertInput["visualIntent"]): { kind?: string; component?: string; rationale?: string; brief?: string } {
+  if (typeof input === "string") return { brief: input.trim() }
+  return {
+    kind: input.kind?.trim(),
+    component: input.component?.trim(),
+    rationale: input.rationale?.trim(),
+    brief: input.brief?.trim(),
+  }
+}
+
+function renderVisualIntent(input: DeckPlanSlideUpsertInput["visualIntent"]): string {
+  const visual = normalizeVisualIntent(input)
+  const lines: string[] = []
+  if (visual.kind) lines.push(`- Kind: ${visual.kind}`)
+  if (visual.component) lines.push(`- Component: ${visual.component}`)
+  if (visual.rationale) lines.push(`- Rationale: ${visual.rationale}`)
+  if (visual.brief) lines.push(`- Brief: ${visual.brief}`)
+  if (lines.length === 0) lines.push("- Brief: Not specified.")
+  return lines.join("\n")
+}
+
+function indentMultiline(value: string): string[] {
+  return value.replace(/\r\n/g, "\n").split("\n").map((line) => `  ${line}`)
+}
+
+function yamlScalar(value: string): string {
+  const trimmed = value.trim()
+  if (/^[A-Za-z0-9_-]+$/.test(trimmed)) return trimmed
+  return JSON.stringify(trimmed)
+}
+
+function slugify(value: string): string {
+  const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "")
+  return slug || "slide"
+}
+
+function formatCsv(value: string[] | undefined): string {
+  const items = uniqueStrings(value ?? [])
+  return items.length > 0 ? items.join(", ") : "none"
+}
+
+function parseCsv(value: string): string[] {
+  const cleaned = cleanPlanValue(value)
+  if (!cleaned || cleaned.toLowerCase() === "none") return []
+  return cleaned.split(",").map((item) => item.trim()).filter(Boolean)
+}
+
+function formatListValue(value: string[] | undefined): string {
+  const items = (value ?? []).map((item) => item.trim()).filter(Boolean)
+  return items.length > 0 ? items.join(" | ") : "none"
+}
+
+function parseListValue(value: string): string[] {
+  const cleaned = cleanPlanValue(value)
+  if (!cleaned || cleaned.toLowerCase() === "none") return []
+  return cleaned.split("|").map((item) => item.trim()).filter(Boolean)
+}
+
+function cleanPlanValue(value: string): string {
+  return value.replace(/^`|`$/g, "").trim()
+}
+
+function uniqueStrings(values: string[]): string[] {
+  const seen = new Set<string>()
+  const result: string[] = []
+  for (const value of values) {
+    const trimmed = value.trim()
+    if (!trimmed || seen.has(trimmed)) continue
+    seen.add(trimmed)
+    result.push(trimmed)
+  }
+  return result
+}
+
 function titleFromSectionKey(key: string): string {
   return key.split("-").map((part) => part ? `${part[0].toUpperCase()}${part.slice(1)}` : part).join(" ")
 }

package/lib/runtime/index.ts

@@ -6,6 +6,9 @@ import {
   activateDesign,
   createDesignDraftPackage,
   createDesignPackage,
+  getDesignComponent,
+  getDesignInventory,
+  getDesignLayout,
   getDesignSection,
   getDesignSkillMd,
   installDesignDraftPackage,
@@ -22,7 +25,7 @@ import { autoCompileNarrativeVault } from "../narrative-vault/auto-compile"
 import { extractNarrativeVaultMarkdownTargetsFromPatch } from "../narrative-vault/hook-targets"
 import { runNarrativeMarkdownQa, type MarkdownQaOptions } from "../narrative-vault/markdown-qa"
 import { formatArtifactQaUserNotice, formatMarkdownQaUserNotice } from "../hook-notifications"
-import { readDeckPlanArtifact } from "../narrative-state/deck-plan-artifact"
+import { deckPlanDesignDiagnostics, readDeckPlanArtifact, upsertDeckPlanSlideArtifact, type DeckPlanSlideUpsertInput } from "../narrative-state/deck-plan-artifact"
 import { extractDesignClasses } from "../design/designs"
 import { recordRenderedArtifact, workspaceRelative } from "../workspace-state/rendered-artifacts"
 import { checkMaterialIntake, extractMaterial, materialIntakeNoticeForCommand, prepareLocalMaterials, recordMaterialReview } from "../material-intake"
@@ -59,6 +62,24 @@ export interface RuntimeDesignReadInput {
   section?: string
 }
 
+export interface RuntimeDesignInventoryInput {
+  name?: string
+}
+
+export interface RuntimeDesignLayoutReadInput {
+  name?: string
+  layout: string | string[]
+}
+
+export interface RuntimeDesignComponentReadInput {
+  name?: string
+  component: string | string[]
+}
+
+export interface RuntimeDeckPlanSlideUpsertInput extends RuntimeWorkspaceInput, DeckPlanSlideUpsertInput {
+  designName?: string
+}
+
 export interface RuntimeDesignCreateInput {
   name: string
   base?: string
@@ -132,10 +153,44 @@ export function readDeckPlan(input: RuntimeWorkspaceInput = {}) {
   const workspaceRoot = root(input.workspaceRoot)
   const compiled = compileNarrativeVault(workspaceRoot)
   const knownNodeIds = compiled.graph ? new Set(compiled.graph.nodes.map((node) => node.id)) : undefined
-  return readDeckPlanArtifact(workspaceRoot, {
+  const read = readDeckPlanArtifact(workspaceRoot, {
     narrativeHash: compiled.narrative ? computeNarrativeHash(compiled.narrative) : undefined,
     knownNodeIds,
   })
+  if (read.projection) {
+    try {
+      const inventory = getDesignInventory(activeDesign())
+      const diagnostics = deckPlanDesignDiagnostics(read.projection, {
+        layouts: inventory.layouts.map((layout) => layout.name),
+        components: inventory.components.map((component) => component.name),
+      })
+      read.projection.diagnostics.push(...diagnostics)
+      read.warnings.push(...diagnostics.map((diagnostic) => diagnostic.message))
+    } catch {
+      // Design diagnostics are advisory; deck-plan reading remains available.
+    }
+  }
+  return read
+}
+
+export function upsertDeckPlanSlide(input: RuntimeDeckPlanSlideUpsertInput) {
+  const workspaceRoot = root(input.workspaceRoot)
+  const designName = input.designName || activeDesign()
+  const inventory = getDesignInventory(designName)
+  const compiled = compileNarrativeVault(workspaceRoot)
+  const knownNodeIds = compiled.graph ? new Set(compiled.graph.nodes.map((node) => node.id)) : undefined
+  const narrativeHash = compiled.narrative ? computeNarrativeHash(compiled.narrative) : undefined
+  const result = upsertDeckPlanSlideArtifact(workspaceRoot, input, {
+    narrativeHash,
+    knownNodeIds,
+    designLayouts: inventory.layouts.map((layout) => layout.name),
+    designComponents: inventory.components.map((component) => component.name),
+  })
+  return {
+    ...result,
+    designName,
+    narrativeHash,
+  }
 }
 
 export function createDeckFoundation(input: RuntimeDeckFoundationInput) {
@@ -212,7 +267,6 @@ export async function reviewDeckOpen(input: ReviewDeckOpenInput) {
 }
 
 export function designList() {
-  seedBuiltinDesigns()
   return {
     ok: true,
     activeDesign: activeDesign(),
@@ -226,7 +280,6 @@ export function designList() {
 }
 
 export function designRead(input: RuntimeDesignReadInput = {}) {
-  seedBuiltinDesigns()
   const name = input.name || activeDesign()
   if (input.section) {
     const markdown = getDesignSection(input.section, name)
@@ -246,6 +299,33 @@ export function designRead(input: RuntimeDesignReadInput = {}) {
   }
 }
 
+export function designInventory(input: RuntimeDesignInventoryInput = {}) {
+  return {
+    ok: true,
+    ...getDesignInventory(input.name || activeDesign()),
+  }
+}
+
+export function designReadLayout(input: RuntimeDesignLayoutReadInput) {
+  const name = input.name || activeDesign()
+  return {
+    ok: true,
+    name,
+    layout: input.layout,
+    markdown: getDesignLayout(input.layout, name),
+  }
+}
+
+export function designReadComponent(input: RuntimeDesignComponentReadInput) {
+  const name = input.name || activeDesign()
+  return {
+    ok: true,
+    name,
+    component: input.component,
+    markdown: getDesignComponent(input.component, name),
+  }
+}
+
 export function designCreate(input: RuntimeDesignCreateInput) {
   seedBuiltinDesigns()
   return createDesignPackage({
@@ -258,7 +338,6 @@ export function designCreate(input: RuntimeDesignCreateInput) {
 }
 
 export function designValidate(input: RuntimeNameInput) {
-  seedBuiltinDesigns()
   return validateDesignPackage(requiredName(input, "design"))
 }
 
@@ -296,7 +375,6 @@ export interface DesignRulesReadinessResult {
 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)

package/package.json

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

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

@@ -13,12 +13,16 @@ type RuntimeModule = {
   compileNarrative(input?: any): any
   markdownQa(input?: any): any
   readDeckPlan(input?: any): any
+  upsertDeckPlanSlide(input: any): any
   createDeckFoundation(input: any): any
   runDeckQa(input: any): Promise<any>
   exportPdf(input: any): Promise<any>
   exportPptx(input: any): Promise<any>
   designList(): any
   designRead(input?: any): any
+  designInventory(input?: any): any
+  designReadLayout(input: any): any
+  designReadComponent(input: any): any
   designActivate(input: any): any
   designCreate(input: any): any
   designValidate(input: any): any
@@ -74,6 +78,25 @@ const tools = [
     description: "Read the file-native deck-plan/ projection and diagnostics.",
     inputSchema: objectSchema({ workspaceRoot: stringProp("Optional workspace root.") }),
   },
+  {
+    name: "revela_upsert_deck_plan_slide",
+    description: "Create or update one structured deck-plan/slides/*.md slide plan with active/requested design vocabulary validation.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      designName: stringProp("Optional design name. Defaults to the active design."),
+      slideIndex: requiredNumberProp("Positive 1-based slide index."),
+      id: stringProp("Optional stable slide node id."),
+      title: requiredStringProp("Slide title."),
+      chapter: requiredStringProp("Chapter name."),
+      narrativeRole: requiredStringProp("Slide's communication job."),
+      structural: booleanProp("Whether this is a structural slide such as cover, TOC, divider, or closing."),
+      layout: requiredStringProp("Design layout name from inventory."),
+      components: componentPlanArrayProp(),
+      visualIntent: visualIntentProp(),
+      narrativeLinks: narrativeLinksProp(),
+      caveats: arrayProp("Optional caveats to keep visible in the slide plan."),
+    }, ["slideIndex", "title", "chapter", "narrativeRole", "layout", "components", "visualIntent", "narrativeLinks"]),
+  },
   {
     name: "revela_create_deck_foundation",
     description: "Create or repair a file-native Revela HTML deck foundation shell.",
@@ -125,6 +148,29 @@ const tools = [
       section: stringProp("Optional design section, such as rules, foundation, or chart-rules."),
     }),
   },
+  {
+    name: "revela_design_inventory",
+    description: "List the active or requested Revela design sections, layouts, and components.",
+    inputSchema: objectSchema({
+      name: stringProp("Optional design name."),
+    }),
+  },
+  {
+    name: "revela_design_read_layout",
+    description: "Read one or more layout blocks from the active or requested Revela design.",
+    inputSchema: objectSchema({
+      name: stringProp("Optional design name."),
+      layout: stringOrArrayProp("Layout name, comma-separated names, or an array of layout names."),
+    }, ["layout"]),
+  },
+  {
+    name: "revela_design_read_component",
+    description: "Read one or more component blocks from the active or requested Revela design.",
+    inputSchema: objectSchema({
+      name: stringProp("Optional design name."),
+      component: stringOrArrayProp("Component name, comma-separated names, or an array of component names."),
+    }, ["component"]),
+  },
   {
     name: "revela_design_activate",
     description: "Activate a Revela design for future deck planning and artifact generation.",
@@ -388,12 +434,16 @@ async function callTool(name: string, args: any): Promise<any> {
   if (name === "revela_compile_narrative") return r.compileNarrative(args)
   if (name === "revela_markdown_qa") return r.markdownQa(args)
   if (name === "revela_read_deck_plan") return r.readDeckPlan(args)
+  if (name === "revela_upsert_deck_plan_slide") return r.upsertDeckPlanSlide(args)
   if (name === "revela_create_deck_foundation") return r.createDeckFoundation(args)
   if (name === "revela_run_deck_qa") return r.runDeckQa(args)
   if (name === "revela_export_pdf") return r.exportPdf(args)
   if (name === "revela_export_pptx") return r.exportPptx(args)
   if (name === "revela_design_list") return r.designList()
   if (name === "revela_design_read") return r.designRead(args)
+  if (name === "revela_design_inventory") return r.designInventory(args)
+  if (name === "revela_design_read_layout") return r.designReadLayout(args)
+  if (name === "revela_design_read_component") return r.designReadComponent(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)
@@ -450,6 +500,10 @@ function numberProp(description: string) {
   return { type: "number", description }
 }
 
+function requiredNumberProp(description: string) {
+  return { type: "number", description }
+}
+
 function enumProp(values: string[], description: string) {
   return { type: "string", enum: values, description }
 }
@@ -458,6 +512,16 @@ function arrayProp(description: string) {
   return { type: "array", items: { type: "string" }, description }
 }
 
+function stringOrArrayProp(description: string) {
+  return {
+    anyOf: [
+      { type: "string" },
+      { type: "array", items: { type: "string" } },
+    ],
+    description,
+  }
+}
+
 function arrayObjectProp(description: string) {
   return {
     type: "array",
@@ -475,6 +539,63 @@ function arrayObjectProp(description: string) {
   }
 }
 
+function componentPlanArrayProp() {
+  return {
+    type: "array",
+    description: "Structured component plan entries.",
+    items: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Design component name." },
+        slot: { type: "string", description: "Layout semantic slot, such as left, right, top, main, bottom, footer, or fullbleed." },
+        position: { type: "string", description: "Slot-local kebab-case anchor, such as left-top, center, or overlay-top-right." },
+        purpose: { type: "string", description: "Component communication job." },
+        content: { type: "string", description: "Exact text, data, or structure to render." },
+        claimIds: { type: "array", items: { type: "string" } },
+        evidenceIds: { type: "array", items: { type: "string" } },
+        sourceNotes: { type: "array", items: { type: "string" } },
+        renderNotes: { type: "array", items: { type: "string" } },
+        placementNote: { type: "string" },
+      },
+      required: ["name", "slot", "position", "purpose", "content"],
+      additionalProperties: false,
+    },
+  }
+}
+
+function visualIntentProp() {
+  return {
+    anyOf: [
+      { type: "string" },
+      {
+        type: "object",
+        properties: {
+          kind: { type: "string" },
+          component: { type: "string" },
+          rationale: { type: "string" },
+          brief: { type: "string" },
+        },
+        additionalProperties: false,
+      },
+    ],
+    description: "Visual plan or structured visual intent. If component is set, it must exist in components[].name.",
+  }
+}
+
+function narrativeLinksProp() {
+  return {
+    type: "object",
+    properties: {
+      claimIds: { type: "array", items: { type: "string" } },
+      evidenceIds: { type: "array", items: { type: "string" } },
+      riskIds: { type: "array", items: { type: "string" } },
+      objectionIds: { type: "array", items: { type: "string" } },
+      gapIds: { type: "array", items: { type: "string" } },
+    },
+    additionalProperties: false,
+  }
+}
+
 function writeMessage(message: any, mode: MessageMode = activeResponseMode): void {
   activeResponseMode = mode
   const body = JSON.stringify(message)

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

@@ -11,16 +11,24 @@ Use this skill when the user asks about Revela designs or when generating deck H
 
 1. Call `revela_design_list` to inspect installed designs.
 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.
+3. Call `revela_design_inventory` before authoring or repairing `deck-plan/` so planned layout/component names come from the active design. Use `revela_upsert_deck_plan_slide` for slide-plan writes; do not hand-write slide plan Markdown.
+4. Read required details with `revela_design_read_layout` and `revela_design_read_component` before writing slide HTML that uses those layouts/components.
+5. 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.
+6. For one-off deck generation with a requested design, read that design by name, call `revela_design_inventory` with that name, and pass `designName` to `revela_create_deck_foundation` without changing active design unless the user asked to switch.
+7. 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`.
+8. Fetch chart/design guidance before creating ECharts or complex layouts.
+9. 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.
 
+## Inventory-First Planning
+
+Deck planning uses design vocabulary before HTML. Inspect the inventory, choose a valid layout for each slide, and choose valid component names for each planned element. Every component plan must include a semantic `slot` such as `left`, `right`, `top`, `main`, `bottom`, `footer`, or `fullbleed`, plus a non-empty kebab-case `position` such as `left-top`, `left-middle`, `right-bottom`, `center`, or `overlay-top-right`.
+
+Use `placementNote` for natural-language placement detail when slot and position are not enough. Slot and position are planning anchors; before HTML generation, fetch the actual layout/component definitions and implement the final structure with the design's CSS and markup.
+
 ## 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.

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

@@ -18,15 +18,16 @@ Use this skill when the user asks to make, generate, or update a Revela deck.
 
 1. Call `revela_compile_narrative` and `revela_markdown_qa`.
 2. Report narrative and Markdown diagnostics, but treat only malformed/unsafe files and technical artifact validity as hard blockers.
-3. Call `revela_read_deck_plan` as the required deck-plan preflight before any HTML generation.
-4. If `deck-plan/` is missing or incomplete, author or repair `deck-plan/index.md` and `deck-plan/slides/*.md` before calling `revela_create_deck_foundation`.
-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` 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.
+3. Call `revela_design_list`, `revela_design_read` using `section: "rules"`, and `revela_design_inventory` before authoring or repairing `deck-plan/`; deck-plan layout/component names must come from the selected design inventory.
+4. Call `revela_read_deck_plan` as the required deck-plan preflight before any HTML generation.
+5. If `deck-plan/` is missing or incomplete, call `revela_upsert_deck_plan_slide` for each planned or changed slide before calling `revela_create_deck_foundation`; do not hand-write `deck-plan/slides/*.md`. Use only inventory-listed layouts/components, and provide slot, position, purpose, and exact content for every planned component.
+6. Report deck-plan diagnostics before artifact generation, including stale narrative hashes, missing slide projections, missing evidence trace, caveats, malformed plan files, or layout/component names outside the active design inventory.
+7. Do not start HTML generation from narrative alone unless the user explicitly asks for a throwaway diagnostic smoke deck.
+8. For new HTML files, call `revela_create_deck_foundation`.
+9. Before patching slide HTML, call `revela_read_deck_plan`, collect the layouts and components from the projection and `componentPlan[]`, then read the specific layouts/components with `revela_design_read_layout` and `revela_design_read_component`; fetch `section: "chart-rules"` and the `echart-panel` component before creating or changing ECharts. 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, call `revela_design_inventory` with that name, pass `designName` to every `revela_upsert_deck_plan_slide` call, and pass `designName` to `revela_create_deck_foundation`.
+10. 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.
+11. Generate chapter by chapter. Keep the HTML valid after each write.
+12. After every HTML write, call `revela_run_deck_qa` and repair hard errors before review or export.
 
 ## Generated Visual Assets
 
@@ -46,4 +47,11 @@ Use this skill when the user asks to make, generate, or update a Revela deck.
 
 ## Deck Plan Requirements
 
-Every deck plan should include Cover, Table of Contents, and Closing. Use 3-5 chapter headings, explicit slide ranges, low-fidelity layout sketches, narrative links, visual intent, evidence trace, and caveats.
+Every deck plan should include Cover, Table of Contents, and Closing. Use 3-5 chapter headings, explicit slide ranges, narrative links, visual intent, evidence trace, and caveats.
+
+`revela_upsert_deck_plan_slide` is the required slide-planning write path. For every slide, provide:
+
+- `slideIndex`, optional stable `id`, `title`, `chapter`, `narrativeRole`, `structural`, and inventory-listed `layout`.
+- `components[]` entries with inventory-listed `name`, semantic `slot`, kebab-case `position`, `purpose`, exact `content`, plus optional `claimIds`, `evidenceIds`, `sourceNotes`, `renderNotes`, and `placementNote`.
+- `visualIntent`; if `visualIntent.component` is set, it must match one of the component plan names.
+- `narrativeLinks` using canonical claim/evidence/risk/objection/gap ids. Non-structural slides should include at least one claim or evidence link.