@cyber-dash-tech/revela 0.18.16 → 0.19.1

package/plugins/revela/hooks/revela_guard.ts

@@ -26,6 +26,16 @@ export async function runPreWriteChecks(input: string): Promise<HookResult> {
     ].join("\n"))
   }
 
+  const protectedDesignCssTargets = extractProtectedDesignCssPatchTargets(input)
+  if (protectedDesignCssTargets.length > 0) {
+    messages.push([
+      "Revela design CSS patches are blocked outside the design draft workflow.",
+      `Protected target(s): ${protectedDesignCssTargets.map((target) => `\`${target}\``).join(", ")}`,
+      "Create or edit designs under `.revela/drafts/designs/<name>/design.css`, then validate and install the draft.",
+      "Deck-local `decks/_revela-design/**/design.css` files are render snapshots and should be regenerated, not patched.",
+    ].join("\n"))
+  }
+
   const deckTargets = extractDeckHtmlPatchTargets(input)
   if (deckTargets.length > 0) {
     const pluginRoot = resolve(process.env.PLUGIN_ROOT || dirname(dirname(fileURLToPath(import.meta.url))))
@@ -74,6 +84,31 @@ export function extractNarrativeCachePatchTargets(input: string): string[] {
   return [...targets].sort((a, b) => a.localeCompare(b))
 }
 
+export function extractProtectedDesignCssPatchTargets(input: string): string[] {
+  const targets = new Set<string>()
+  for (const patch of patchPayloads(input)) {
+    const pattern = /(?:^\*\*\* Update File: |^\*\*\* Add File: |^\*\*\* Delete File: |^\*\*\* Move to: )([^\r\n]*design\.css)\s*$/gm
+    let match: RegExpExecArray | null
+    while ((match = pattern.exec(patch))) {
+      const target = match[1].trim().replace(/\\/g, "/")
+      if (isAllowedDesignDraftCssTarget(target)) continue
+      if (isProtectedDesignCssTarget(target)) targets.add(target)
+    }
+  }
+  return [...targets].sort((a, b) => a.localeCompare(b))
+}
+
+function isAllowedDesignDraftCssTarget(target: string): boolean {
+  return /(^|\/)\.revela\/drafts\/designs\/[^/]+\/design\.css$/.test(target)
+}
+
+function isProtectedDesignCssTarget(target: string): boolean {
+  return /(^|\/)designs\/[^/]+\/design\.css$/.test(target)
+    || /(^|\/)decks\/_revela-design\/[^/]+\/design\.css$/.test(target)
+    || /(^|\/)_revela-design\/[^/]+\/design\.css$/.test(target)
+    || /(^|\/)\.config\/revela\/designs\/[^/]+\/design\.css$/.test(target)
+}
+
 function patchPayloads(input: string): string[] {
   try {
     const parsed = JSON.parse(input)

package/plugins/revela/hooks/revela_post_write_notice.ts

@@ -71,16 +71,16 @@ function titleFromDeckHtml(absolutePath: string): string {
 
 export function formatDeckWebsiteCardHandoffNotice(workspaceRoot: string, target: string): string {
   const absolutePath = resolve(workspaceRoot, target)
-  const deckUrl = pathToFileURL(absolutePath).href
   const title = titleFromDeckHtml(absolutePath)
+  const httpUrlTemplate = `http://127.0.0.1:<port>/${target}`
   return [
     "**Deck website card ready**",
     "",
-    `Artifact QA passed for \`${target}\`. Reply with this standalone deck link so Codex renders an Open in Browser website card:`,
+    `Artifact QA passed for \`${target}\`. Do not open the deck file directly. Start a read-only local static server from the workspace root, then reply with this standalone deck link so Codex renders an Open in Browser website card the user can click:`,
     "",
-    `[${title}](${deckUrl})`,
+    `[${title}](${httpUrlTemplate})`,
     "",
-    `If the card or direct \`file://\` navigation is unavailable, start a read-only local static server from the workspace root and link to \`http://127.0.0.1:<port>/${target}\` instead.`,
+    `Replace \`<port>\` with the actual localhost port. Keep \`file://\` only for non-Codex surfaces that allow direct local-file navigation.`,
   ].join("\n")
 }
 

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

@@ -13,6 +13,13 @@ type RuntimeModule = {
   readDeckPlan(input?: any): any
   upsertDeckPlanSlide(input: any): any
   createDeckFoundation(input: any): any
+  listPageTemplates(): any
+  renderTemplateSlide(input: any): any
+  addTemplateSlide(input: any): any
+  renderTemplateScaffold(input: any): any
+  addTemplateScaffold(input: any): any
+  pageTemplateFoundation(input: any): any
+  pageTemplateVocabulary(input: any): any
   runDeckQa(input: any): Promise<any>
   exportPdf(input: any): Promise<any>
   exportPptx(input: any): Promise<any>
@@ -25,6 +32,7 @@ type RuntimeModule = {
   designActivate(input: any): any
   designCreate(input: any): any
   designValidate(input: any): any
+  designPreview(input: any): any
   designDraftCreate(input: any): any
   designDraftValidate(input: any): any
   designDraftInstall(input: any): any
@@ -94,6 +102,71 @@ const tools = [
       overwrite: booleanProp("Whether create mode may overwrite an existing file."),
     }, ["outputPath", "title", "language"]),
   },
+  {
+    name: "revela_list_page_templates",
+    description: "List built-in Revela page templates with semantic fields, content rules, and template QA contracts.",
+    inputSchema: objectSchema({}),
+  },
+  {
+    name: "revela_render_template_slide",
+    description: "Render one built-in page template into a stable Revela slide HTML skeleton using the active/requested design.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      designName: stringProp("Optional design name. Defaults to the active design."),
+      templateId: requiredStringProp("Built-in template id, such as timeline-roadmap."),
+      slideIndex: requiredNumberProp("Positive 1-based slide index."),
+      content: objectProp("Template content fields. The built-in template renderer owns the HTML skeleton."),
+    }, ["templateId", "slideIndex", "content"]),
+  },
+  {
+    name: "revela_page_template_foundation",
+    description: "Read the built-in template foundation for custom design authoring: scaffold HTML, CSS hooks, slots, and contract notes.",
+    inputSchema: objectSchema({
+      templateId: requiredStringProp("Built-in template id, such as timeline-roadmap."),
+    }, ["templateId"]),
+  },
+  {
+    name: "revela_page_template_vocabulary",
+    description: "Read machine-readable classes, slots, editable regions, replaceable regions, and contract notes for one page template.",
+    inputSchema: objectSchema({
+      templateId: requiredStringProp("Built-in template id, such as timeline-roadmap."),
+    }, ["templateId"]),
+  },
+  {
+    name: "revela_render_template_scaffold",
+    description: "Render one built-in page template scaffold with stable editable slots using minimal seed content.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      designName: stringProp("Optional design name. Defaults to the active design."),
+      templateId: requiredStringProp("Built-in template id, such as timeline-roadmap."),
+      slideIndex: requiredNumberProp("Positive 1-based slide index."),
+      seed: objectProp("Optional scaffold seed fields. This is not the final authoring interface."),
+    }, ["templateId", "slideIndex"]),
+  },
+  {
+    name: "revela_add_template_scaffold",
+    description: "Render and append one built-in page template scaffold into an existing Revela deck HTML file between slide markers.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      outputPath: requiredStringProp("Workspace-relative HTML deck path."),
+      designName: stringProp("Optional design name. Defaults to the active design."),
+      templateId: requiredStringProp("Built-in template id, such as timeline-roadmap."),
+      slideIndex: requiredNumberProp("Positive 1-based slide index."),
+      seed: objectProp("Optional scaffold seed fields. LLM should bounded-edit the inserted slide after scaffold creation."),
+    }, ["outputPath", "templateId", "slideIndex"]),
+  },
+  {
+    name: "revela_add_template_slide",
+    description: "Compatibility path: render and append one built-in page template slide from full content JSON into an existing deck HTML file.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      outputPath: requiredStringProp("Workspace-relative HTML deck path."),
+      designName: stringProp("Optional design name. Defaults to the active design."),
+      templateId: requiredStringProp("Built-in template id, such as timeline-roadmap."),
+      slideIndex: requiredNumberProp("Positive 1-based slide index."),
+      content: objectProp("Template content fields. Prefer scaffold-first flow for new deck creation."),
+    }, ["outputPath", "templateId", "slideIndex", "content"]),
+  },
   {
     name: "revela_run_deck_qa",
     description: "Run Revela artifact QA on a generated HTML deck.",
@@ -171,15 +244,16 @@ const tools = [
   },
   {
     name: "revela_design_create",
-    description: "Create and validate a local Revela design package from complete DESIGN.md and preview.html content.",
+    description: "Create and validate a local Revela design package from complete DESIGN.md, design.css, and optional legacy preview.html content.",
     inputSchema: objectSchema({
       name: requiredStringProp("Design name in kebab-case."),
       base: stringProp("Optional base design used as structural scaffold."),
       designMd: requiredStringProp("Complete DESIGN.md content."),
-      previewHtml: requiredStringProp("Complete preview.html content."),
+      designCss: stringProp("Complete design.css content. Required for CSS-native designs; omitted only for legacy compatibility."),
+      previewHtml: stringProp("Optional legacy preview.html content. Current design previews are generated with revela_design_preview."),
       assets: designAssetsProp(),
       overwrite: booleanProp("Whether to replace an existing local design package. Defaults to false."),
-    }, ["name", "designMd", "previewHtml"]),
+    }, ["name", "designMd"]),
   },
   {
     name: "revela_design_validate",
@@ -194,10 +268,11 @@ const tools = [
       name: requiredStringProp("Design name in kebab-case."),
       base: stringProp("Optional base design used as structural scaffold."),
       designMd: requiredStringProp("Complete DESIGN.md content."),
-      previewHtml: requiredStringProp("Complete preview.html content."),
+      designCss: stringProp("Complete design.css content. Required for CSS-native designs; omitted only for legacy compatibility."),
+      previewHtml: stringProp("Optional legacy preview.html content. Current design previews are generated with revela_design_preview."),
       assets: designAssetsProp(),
       overwrite: booleanProp("Whether to replace an existing workspace draft. Defaults to false."),
-    }, ["name", "designMd", "previewHtml"]),
+    }, ["name", "designMd"]),
   },
   {
     name: "revela_design_draft_validate",
@@ -207,6 +282,15 @@ const tools = [
       name: requiredStringProp("Design draft name to validate."),
     }, ["name"]),
   },
+  {
+    name: "revela_design_preview",
+    description: "Generate a workspace-local preview for a draft, installed, or built-in Revela design using the built-in page template preview fixture plus the design.css file.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Design name to preview."),
+      source: enumProp(["draft", "installed", "builtin"], "Optional source. Defaults to draft when present, otherwise installed/builtin."),
+    }, ["name"]),
+  },
   {
     name: "revela_design_draft_install",
     description: "Install a validated workspace-local Revela design draft into the user-level design registry.",
@@ -392,10 +476,12 @@ async function handle(req: JsonRpcRequest): Promise<any | undefined> {
     bootLog("request", { id: req.id, method: req.method })
     if (req.method === "initialize") {
       bootLog("initialize-received", { id: req.id, protocolVersion: req.params?.protocolVersion })
+      const runtimeInfo = await runtime()
+      const doctor = runtimeInfo.doctor({})
       return result(req.id, {
         protocolVersion: req.params?.protocolVersion || "2024-11-05",
         capabilities: { tools: {} },
-        serverInfo: { name: "revela", version: "0.18.15" },
+        serverInfo: { name: "revela", version: doctor.version },
       })
     }
     if (req.method === "tools/list") {
@@ -421,6 +507,13 @@ async function callTool(name: string, args: any): Promise<any> {
   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_list_page_templates") return r.listPageTemplates()
+  if (name === "revela_render_template_slide") return r.renderTemplateSlide(args)
+  if (name === "revela_add_template_slide") return r.addTemplateSlide(args)
+  if (name === "revela_page_template_foundation") return r.pageTemplateFoundation(args)
+  if (name === "revela_page_template_vocabulary") return r.pageTemplateVocabulary(args)
+  if (name === "revela_render_template_scaffold") return r.renderTemplateScaffold(args)
+  if (name === "revela_add_template_scaffold") return r.addTemplateScaffold(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)
@@ -435,6 +528,7 @@ async function callTool(name: string, args: any): Promise<any> {
   if (name === "revela_design_validate") return r.designValidate(args)
   if (name === "revela_design_draft_create") return r.designDraftCreate(args)
   if (name === "revela_design_draft_validate") return r.designDraftValidate(args)
+  if (name === "revela_design_preview") return r.designPreview(args)
   if (name === "revela_design_draft_install") return r.designDraftInstall(args)
   if (name === "revela_design_pack") return r.designPack(args)
   if (name === "revela_design_install_archive") return r.designInstallArchive(args)
@@ -496,6 +590,10 @@ function arrayProp(description: string) {
   return { type: "array", items: { type: "string" }, description }
 }
 
+function objectProp(description: string) {
+  return { type: "object", description, additionalProperties: true }
+}
+
 function stringOrArrayProp(description: string) {
   return {
     anyOf: [

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

@@ -29,7 +29,7 @@ Use this skill as the main Revela entrypoint in Codex. It should inspect intent
 - `spec.md` exists but source support, material review, or findings are missing: use `revela-research`.
 - `spec.md` and sufficient findings exist but `deck-plan.md` is missing or needs normal authoring: use `revela-research` Planning Handoff.
 - Valid `deck-plan.md` exists and the user asks to make, generate, render, or update a deck: use `revela-make-deck`.
-- Existing deck artifact and the user asks to review, annotate, diagnose, QA, or refine: use Codex Browser's native browsing/annotation flow. If the deck was not just generated, reply with the existing deck as a website card/link and use native annotations after it opens; route export requests to `revela-export`.
+- Existing deck artifact and the user asks to review, annotate, diagnose, QA, or refine: use Codex Browser's native browsing/annotation flow. If the deck was not just generated, start a read-only local static server from the workspace root, reply with the existing deck as a localhost website card/link, and use native annotations after the user opens it; route export requests to `revela-export`.
 - Existing deck artifact and the user asks for PDF, PPTX, or PNG output: use `revela-export`.
 - If the next step is still ambiguous after inspection, ask the smallest missing question and recommend the safest next specialist skill.
 

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

@@ -9,35 +9,39 @@ Use this skill when the user asks to create, customize, edit, validate, package,
 
 ## Contract
 
-- Designs define deck visual systems: rules, foundation, layouts, components, chart rules, and preview coverage.
+- Designs define deck visual systems: rules, foundation, layouts, components, chart rules, and page-template foundation styling.
+- CSS-native designs include `design.css` as the executable visual source. `DESIGN.md` explains the design contract; `design.css` styles the stable template DOM classes.
 - Designs should define executable visual contracts, not only mood, fonts, and palettes. Capture grid/safe-area, spacing scale, type scale, surface behavior, chart tokens, component states, and preview fixtures in the design package.
 - Designs may include package-owned `assets/**` such as cover or closing backgrounds; design tools surface these as design elements, not source evidence.
 - When the user uploads or provides logo, cover, closing, background, texture, brand image, or similar design material, store it inside the design package with `revela_design_draft_create.assets`; use paths under `assets/**` only.
-- Generated `preview.html` must actually reference uploaded design assets with package-relative `assets/...` paths rather than describing them only in text.
+- Design previews are generated from Revela's built-in page-template preview plus the draft or installed `design.css`.
 - Default authoring is workspace draft first, then validate, then install only when appropriate.
 - Direct user-level creation is reserved for explicit create/install-now requests.
 - Shareable design archives are `.tar` or `.tar.gz`; install archives only from trusted local paths.
 - Do not use domain tools for visual design work.
-- Do not generate deck HTML while authoring a design.
+- Do not write `decks/*.html` while authoring a design. Use `revela_design_preview` to generate a workspace-local design preview.
 
 ## Required Tools
 
 For status, inspection, activation, or selection:
 
 1. Call `revela_design_list`.
-2. Call `revela_design_read`, `revela_design_inventory`, `revela_design_read_layout`, or `revela_design_read_component` as needed.
+2. Call `revela_design_read`, `revela_design_inventory`, `revela_design_read_layout`, `revela_design_read_component`, or `revela_page_template_foundation` as needed.
 3. Call `revela_design_activate` only when the user asks to use a design.
 
 For new or edited designs:
 
 1. Call `revela_design_list`.
 2. Read the requested base design or active design with `revela_design_read`.
-3. Draft complete `DESIGN.md` and complete `preview.html` content.
-4. Call `revela_design_draft_create`; when uploaded or local design material exists, pass `assets: [{ path: "assets/...", contentBase64|content|sourcePath }]` so the files are written into the draft package.
-5. Call `revela_design_draft_validate`.
-6. If validation fails, revise the draft content and repeat draft create/validate.
-7. Call `revela_design_draft_install` only after the draft validates and the user intent is to install it.
-8. Call `revela_design_activate` only when the user asks to make it active.
+3. Call `revela_design_inventory` and inspect its `pageTemplates` summary.
+4. Call `revela_page_template_foundation` for any built-in page templates the design should style or preview.
+5. Draft complete `DESIGN.md` and complete `design.css` content.
+6. Call `revela_design_draft_create` with `designCss`; when uploaded or local design material exists, pass `assets: [{ path: "assets/...", contentBase64|content|sourcePath }]` so the files are written into the draft package.
+7. Call `revela_design_draft_validate`.
+8. Call `revela_design_preview` for the draft, start a read-only local static server from the returned `browserHandoff.serveRoot`, and reply with the resulting localhost preview link for the user to open in Codex Browser.
+9. If validation or preview review fails, revise the draft content and repeat draft create/validate/preview.
+10. Call `revela_design_draft_install` only after the draft validates and the user intent is to install it.
+11. Call `revela_design_activate` only when the user asks to make it active.
 
 For sharing or installing design archives:
 
@@ -53,22 +57,23 @@ Use `revela_design_create` only when the user explicitly requests direct local c
 
 - Use a kebab-case design name.
 - `DESIGN.md` must include valid frontmatter and complete design marker sections.
+- `design.css` should be present for CSS-native designs and is the only executable CSS source for package-owned template styling.
 - Include design rules, foundation guidance, at least one layout, and at least one component.
 - In `@design:foundation`, document the design contract: grid columns or layout rails, safe area, spacing/baseline scale, typography scale, surfaces/borders/shadows, and chart tokens when charts are supported.
+- Use page-template foundation as the starting point for built-in template styling. Style template classes, but do not remove structural classes or `data-template-slot` semantics.
 - Layouts must declare stable slots and use grid/flex structure as the source of alignment. Avoid one-off absolute positioning that bypasses the declared layout contract.
 - Components should describe normal, dense, and long-copy behavior where relevant. Chart, table, media, and source-note components need stable container dimensions.
 - Optional assets must live under `assets/**`; reference them as package-relative paths like `assets/cover-background.png`.
 - `DESIGN.md` may reference package assets in rules, layouts, or components with `assets/...`; do not reference workspace `assets/` media manifest entries for design-owned visuals.
-- `preview.html` must use the fixed Revela preview canvas contract and visibly preview the design.
-- If design assets are present, `preview.html` must visibly use the saved `assets/...` files, for example a cover hero background or logo image.
-- Preview must include cover and closing examples and showcase every component.
-- Preview should showcase every layout with `data-preview-layout="<layout-name>"` and every component with `data-preview-component="<component-name>"`.
-- Preview should behave like a design test fixture: include normal content, dense content, mixed-language text where relevant, chart/table examples when supported, readable media, and source-note behavior.
+- `revela_design_preview` must generate the visual preview; do not hand-write package `preview.html` for ordinary CSS-native design drafts.
+- Do not open `file://` preview URLs in Codex Browser. Use the returned `browserHandoff` fields to serve the preview over `http://127.0.0.1:<port>/preview.html` and let the user click the link.
+- If design assets are present, the generated preview should visibly use the saved `assets/...` files when the design CSS references them.
+- Generated preview should show the built-in page templates with normal, dense, chart/table, timeline, image, and source-note-like states.
 - Preserve source inspiration and limitations explicitly; do not copy copyrighted design text or assets into the package.
 
 ## Outputs
 
-- Design draft path/status or installed design name.
+- Design draft path/status, generated preview path/status, or installed design name.
 - Archive path/status when packaging or installing a shareable design.
 - Asset metadata surfaced by read/inventory tools when `assets/**` exists.
 - Saved asset paths and intended uses, for example `assets/cover-background.png -> cover hero background`.
@@ -80,5 +85,6 @@ Use `revela_design_create` only when the user explicitly requests direct local c
 
 - Do not write `deck-plan.md`.
 - Do not write `decks/*.html`.
+- Do not patch `decks/_revela-design/**/design.css`; those files are regenerated deck-local snapshots.
 - Do not install or activate a design unless the user requested that outcome.
 - Do not invent licenses, asset provenance, or brand permissions.

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

@@ -46,7 +46,7 @@ Report:
   - `spec.md` exists but no `researches/`: run `revela-research`.
   - Research exists but no `deck-plan.md`: continue `revela-research` to the Planning Handoff.
   - Valid `deck-plan.md` but no deck artifact: run `revela-make-deck`.
-  - Existing deck artifact: surface the HTML deck as a website card/link for Codex Browser native annotation, or run `revela-export` for PDF/PPTX/PNG.
+  - Existing deck artifact: start a read-only local static server from the workspace root and surface the HTML deck as a localhost website card/link for Codex Browser native annotation, or run `revela-export` for PDF/PPTX/PNG.
 
 ## Must Not
 

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

@@ -13,9 +13,11 @@ Use this skill when the user asks to make, generate, render, or update a Revela
 - Local materials, material reviews, `researches/`, `assets/`, and user intent provide source context.
 - Slide argument copy comes from `deck-plan.md` `Claim`, `Reasoning`, and `Audience takeaway` fields when present; raw findings are evidence/source context, not default body copy.
 - Active/requested design tools define valid layouts, slots, components, nesting hints, structure contracts, and HTML writing rules.
+- Built-in page template tools define semantic page templates, foundation/scaffold HTML, editable slots, stable DOM contracts, and template QA contracts.
+- Deck-local `decks/_revela-design/**/design.css` files are generated design snapshots. Do not patch them during deck making; regenerate the deck foundation or enter the design workflow instead.
 - Active/requested domain guidance may inform communication framing, but it is not source evidence.
 - Generated artifacts live under `decks/*.html`.
-- After final Artifact QA passes, reply with the generated HTML deck as a standalone website link/card that opens in Codex Browser for native browsing and annotation.
+- After final Artifact QA passes, reply with the generated HTML deck as a standalone localhost website link/card that the user can click to open in Codex Browser for native browsing and annotation.
 - Do not require a Narrative Vault before generating a deck.
 - This skill does not own normal plan authoring; `revela-research` owns source preparation and `deck-plan.md` planning handoff.
 - `deck-plan.md` is required for normal deck generation.
@@ -43,15 +45,19 @@ Before render preflight:
 1. Call `revela_design_list`.
 2. Call `revela_design_read` with `section: "rules"` for the active/requested design.
 3. Call `revela_design_inventory`.
-4. Review each component's `contract` field. Components with structure contracts must be planned from structured content and rendered with the required internal DOM/classes, not simplified freehand markup.
+4. Call `revela_list_page_templates` when the deck-plan uses `template` fields or when adding a new page.
+5. For each template used in the current batch, call `revela_page_template_foundation` before creating or editing scaffold HTML.
+6. Review each component's `contract` field. Components with structure contracts must be planned from structured content and rendered with the required internal DOM/classes, not simplified freehand markup.
 
 Before HTML writing:
 
 1. Call `revela_read_deck_plan`.
 2. Read the returned `htmlWritingBatches`.
-3. Call `revela_design_read_layout` for each layout used in the current batch.
-4. Call `revela_design_read_component` for each component used in the current batch. For contract components, treat the returned CSS/HTML as executable grammar and preserve the required root, descendant, item, and alternating classes.
-5. Fetch chart rules before creating or modifying ECharts.
+3. For new slides with `template`, call `revela_render_template_scaffold` or `revela_add_template_scaffold`, then bounded-edit only the inserted slide's `data-template-slot` regions.
+4. Use `revela_render_template_slide` / `revela_add_template_slide` only as a compatibility path for existing full `Template Content` JSON plans.
+5. For legacy slides without `template`, call `revela_design_read_layout` for each layout used in the current batch.
+6. For legacy slides without `template`, call `revela_design_read_component` for each component used in the current batch. For contract components, treat the returned CSS/HTML as executable grammar and preserve the required root, descendant, item, and alternating classes.
+7. Fetch chart rules before creating or modifying ECharts.
 
 ## Plan Preflight And Repair
 
@@ -63,6 +69,7 @@ Allowed plan repairs are limited to technical diagnostics from `revela_read_deck
 - Invalid or missing `sourceLinks` field structure, without adding new unsupported source links.
 - Layout, slot, component, or `children` names that do not match `revela_design_inventory`.
 - Component nesting fixes such as using `box.children` when the selected component model requires nested semantic groups.
+- Missing or misspelled built-in `template` ids reported by `revela_read_deck_plan`.
 
 Do not redesign the argument structure, add new slides, remove supported slides, rewrite claims, or add source links that were not reviewed or saved by `revela-research`. If normal plan authoring is needed, stop and send the user back to `revela` routing or `revela-research` Planning Handoff.
 
@@ -76,16 +83,18 @@ Use this phase when the user asks to make, generate, render, or update an HTML d
 2. Read `htmlWritingBatches` before any HTML write. `revela_read_deck_plan` is QA/diagnostics, not a writer.
 3. For new HTML files, call `revela_create_deck_foundation`.
 4. Use the deck-plan's `Claim`, `Reasoning`, and `Audience takeaway` as the primary slide copy. Keep finding text in source notes, captions, evidence charts, or speaker notes unless the plan explicitly calls for a direct evidence quote.
-5. Generate one `htmlWritingBatches` entry at a time.
-6. A single HTML write/edit/apply_patch may add or rewrite at most 5 slide sections.
-7. If a chapter is longer than 5 slides, use the consecutive batch parts returned by `revela_read_deck_plan`.
-8. Patch slides into the foundation between Revela slide markers.
-9. Preserve positive 1-based `data-slide-index` values.
-10. Every slide must have exactly one direct `.slide-canvas` child.
-11. Keep the HTML valid after each write.
-12. After every HTML write, call `revela_run_deck_qa` and repair hard errors before continuing or export.
-13. After the final `revela_run_deck_qa` passes with zero hard errors, reply with a standalone Markdown link to the generated HTML deck artifact so Codex renders an Open in Browser website card.
-14. Prefer an absolute `file://` URL for the card. If the card or direct file navigation is unavailable, start a read-only local static server from the workspace root and use the exact `http://127.0.0.1:<port>/decks/<file>.html` URL.
+5. For template slides, use the deck-plan `template` to create a scaffold with `revela_add_template_scaffold`; use `Template Content` only as seed or compatibility input, not as the final authoring interface.
+6. After scaffold insertion, bounded-edit the current slide HTML: preserve `.slide`, `.slide-canvas`, `data-template`, required template classes, and `data-template-slot` semantics.
+7. Visual slots may be replaced by image, chart, table, or diagram containers only when the replacement keeps a clear semantic container for QA and export.
+8. A single HTML write/edit/apply_patch may add or rewrite at most 5 slide sections.
+9. If a chapter is longer than 5 slides, use the consecutive batch parts returned by `revela_read_deck_plan`.
+10. Patch slides into the foundation between Revela slide markers.
+11. Preserve positive 1-based `data-slide-index` values.
+12. Every slide must have exactly one direct `.slide-canvas` child.
+13. Keep the HTML valid after each write.
+14. After every HTML write, call `revela_run_deck_qa` and repair hard errors before continuing or export.
+15. After the final `revela_run_deck_qa` passes with zero hard errors, do not open the deck file directly. Start a read-only local static server from the workspace root and reply with a standalone Markdown link to the generated HTML deck artifact so the user can click it open in Codex Browser.
+16. Use the exact `http://127.0.0.1:<port>/decks/<file>.html` URL for the card, replacing `<port>` with the actual localhost port. Keep `file://` only for non-Codex surfaces that allow direct local-file navigation.
 
 ## Outputs
 
@@ -101,7 +110,7 @@ Use this phase when the user asks to make, generate, render, or update an HTML d
 - Do not write a new `deck-plan.md` when it is missing.
 - Do not use design inventory names, slots, or components that were not returned by the active/requested design tools.
 - Do not use a slot that does not belong to the selected layout.
-- Do not hand-roll simplified internal DOM for contract components such as timelines. If the required structure cannot be satisfied, choose a simpler valid component or stop with the contract issue.
+- Do not delete template required classes or slots during bounded edits. If the required structure cannot be satisfied, choose a simpler valid template/component or stop with the contract issue.
 - Do not patch more than 5 slide sections in one HTML write.
 - Do not invent source links, quotes, URLs, page references, caveats, or licenses.
 - Do not write remote image candidates directly into deck HTML; save them as workspace assets first.