@cyber-dash-tech/revela 0.17.23 → 0.17.24

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

@@ -25,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"
@@ -76,6 +76,10 @@ export interface RuntimeDesignComponentReadInput {
   component: string | string[]
 }
 
+export interface RuntimeDeckPlanSlideUpsertInput extends RuntimeWorkspaceInput, DeckPlanSlideUpsertInput {
+  designName?: string
+}
+
 export interface RuntimeDesignCreateInput {
   name: string
   base?: string
@@ -149,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) {

package/package.json

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

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

@@ -13,6 +13,7 @@ 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>
@@ -77,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.",
@@ -414,6 +434,7 @@ 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)
@@ -479,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 }
 }
@@ -514,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,7 +11,7 @@ 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. Call `revela_design_inventory` before authoring or repairing `deck-plan/` so planned layout/component names come from the active design.
+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.
@@ -23,6 +23,12 @@ Deck HTML must keep exactly one direct `.slide-canvas` child inside every `<sect
 
 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

@@ -20,11 +20,11 @@ Use this skill when the user asks to make, generate, or update a Revela deck.
 2. Report narrative and Markdown diagnostics, but treat only malformed/unsafe files and technical artifact validity as hard blockers.
 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, author or repair `deck-plan/index.md` and `deck-plan/slides/*.md` before calling `revela_create_deck_foundation`; use only inventory-listed layouts/components in slide frontmatter and visual intent.
+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, read the specific layouts/components used by the deck plan 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, and pass `designName` to `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.
@@ -47,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.