@cyber-dash-tech/revela 0.17.20 → 0.17.21

package/README.md

@@ -34,7 +34,7 @@ To install globally, add the same entry to `~/.config/opencode/opencode.json`.
 Requirements:
 
 - The Codex CLI must be installed and the `codex` command must be available in your shell.
-- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.17.12 mcp` to start the MCP server.
+- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.17.21 mcp` to start the MCP server.
 - For interactive Review actions, `codex exec` must also work because the Review UI uses it for Insight and Comment/Apply Fix requests.
 
 Optional preflight:
@@ -55,11 +55,11 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 Install Revela through the Codex Git marketplace:
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.12
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.21
 codex plugin add revela@revela
 ```
 
-The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.17.12 mcp` so npm can fetch the published package and its dependencies.
+The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.17.21 mcp` so npm can fetch the published package and its dependencies.
 
 You do not need to run `bun install` inside the Codex marketplace clone.
 
@@ -67,6 +67,28 @@ Start a new Codex thread after installing so Codex loads the Revela skills, MCP
 
 For release-aligned local validation, run `bun run smoke:mcp-pack`. It packs the current checkout to a temporary npm tarball and starts the MCP server through `npx`, matching the published Codex launcher path without requiring a registry publish.
 
+#### Codex Upgrade
+
+In Codex, ask Revela to check the current runtime version; the plugin calls `revela_doctor` and reports the running `version`.
+
+For a fixed release tag, reinstall the plugin from that tag:
+
+```bash
+codex plugin remove revela@revela
+codex plugin marketplace remove revela
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref vX.Y.Z
+codex plugin add revela@revela
+```
+
+For a marketplace entry that intentionally tracks a branch or movable ref, upgrade the marketplace clone and re-add the plugin:
+
+```bash
+codex plugin marketplace upgrade revela
+codex plugin add revela@revela
+```
+
+The Git marketplace ref and `.mcp.json` npm pin are part of the same release artifact. Start a new Codex thread after upgrading so Codex reloads the Revela skills, MCP tools, hooks, and runtime pin.
+
 ## Built-In Designs
 
 Revela includes built-in deck designs:

package/README.zh-CN.md

@@ -34,7 +34,7 @@ Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材
 环境要求：
 
 - 需要已安装 Codex CLI，并且 shell 中可以执行 `codex`。
-- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.17.12 mcp` 启动 MCP server。
+- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.17.21 mcp` 启动 MCP server。
 - 如果使用 Review UI 的 Insight、Comment 或 Apply Fix，需要 `codex exec` 可用。
 
 可选的安装前检查：
@@ -55,11 +55,11 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 通过 Codex Git marketplace 安装 Revela：
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.12
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.21
 codex plugin add revela@revela
 ```
 
-Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.17.12 mcp`，由 npm 获取已发布 package 及其 dependencies。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.17.21 mcp`，由 npm 获取已发布 package 及其 dependencies。
 
 不需要在 Codex marketplace clone 里运行 `bun install`。
 
@@ -67,6 +67,28 @@ Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。
 
 如果要按发布路径做本地验证，运行 `bun run smoke:mcp-pack`。它会把当前 checkout 打成临时 npm tarball，再通过 `npx` 启动 MCP server，不需要先发布到 registry。
 
+#### Codex 升级
+
+在 Codex 中，可以让 Revela 检查当前 runtime version；plugin 会调用 `revela_doctor` 并报告正在运行的 `version`。
+
+如果要固定到某个 release tag，按该 tag 重新安装 plugin：
+
+```bash
+codex plugin remove revela@revela
+codex plugin marketplace remove revela
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref vX.Y.Z
+codex plugin add revela@revela
+```
+
+如果 marketplace entry 本来就有意跟踪 branch 或 movable ref，升级 marketplace clone 后重新添加 plugin：
+
+```bash
+codex plugin marketplace upgrade revela
+codex plugin add revela@revela
+```
+
+Git marketplace ref 和 `.mcp.json` npm pin 属于同一个 release artifact。升级后开启一个新的 Codex thread，让 Codex 重新加载 Revela skills、MCP tools、hooks 和 runtime pin。
+
 ## 内置设计
 
 Revela 内置多个 deck design：

package/designs/monet/DESIGN.md

@@ -480,6 +480,8 @@ These rules are mandatory for Monet.
 - **Sparse slides depend on image weight.** If content is light, the photo or page framing must hold the composition.
 - **No glass cards, neon KPI styling, or startup-product chrome.** Monet is editorial and print-adjacent.
 - **Visual hierarchy is strict:** eyebrow -> heading -> body -> caption.
+- **Content pages need a stable title block.** Except cover, TOC, closing, section divider, and full-bleed hero slides, every normal content slide should include a visible slide-level title block from the upper-left safe area. It should contain a compact chapter/section label plus a slide title written as the page's claim or takeaway.
+- **Do not hide the page title inside a component.** Body components may have their own headings, but `text-panel`, `box`, `toc`, chart/table headers, and editorial module headings do not replace the slide-level title block.
 - **Icon system is Lucide.** For ordinary UI, semantic, status, category, process, and navigation icons, use Lucide (`data-lucide`). Do not hand-write inline SVG for icons. SVG is allowed only for intentional decorative motifs, illustrations, or design-specific artwork. If any `data-lucide` icon is present, load Lucide via CDN and call `lucide.createIcons()` after `SlidePresentation`.
 - **Chart system is ECharts.** Data charts default to ECharts inside `echart-panel`. Do not use hand-written SVG, div/CSS shapes, canvas mocks, or static faux charts as data-chart substitutes. SVG remains acceptable for decorative motifs, diagrams, or illustrations, not data charts. Before creating or changing a chart, fetch the `echart-panel` component and `section: "chart-rules"`; if chart rules or runtime are unavailable, report the gap instead of inventing a fake chart fallback.
 - **Start from foundation.** New deck HTML starts from `@design:foundation`. Do not recreate foundation CSS, JavaScript, or the HTML skeleton from memory. Prefer a foundation helper when available; otherwise fetch `section: "foundation"` before writing a new deck shell. Existing deck edits preserve the current foundation unless the user asks for foundation repair or QA reports a foundation contract problem.
@@ -511,12 +513,14 @@ These rules are mandatory for Monet.
 
 ### Layout Types
 
-Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. It must also set `data-slide-index="N"`, where `N` is the canonical positive 1-based artifact slide identity from the approved deck plan or DOM order. Indexes must be unique and strictly increase. Use the QA column to decide which `slide-qa` value to write. Fetch any layout with the `revela-designs` tool (`action: "read"`, `layout: "<name>"`).
+Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. It must also set `data-slide-index="N"`, where `N` is the canonical positive 1-based artifact slide identity from the approved deck plan or DOM order. Indexes must be unique and strictly increase. Use the QA column to decide which `slide-qa` value to write. Choose layouts by narrative structure first, not by surface geometry. Fetch any layout with the `revela-designs` tool (`action: "read"`, `layout: "<name>"`).
+
+Normal `qa=true` content layouts must start with a slide-level title block unless the layout marker explicitly says otherwise. Use an eyebrow for chapter/section context, then an `h2` that states the slide's claim or takeaway. Body boxes, charts, media, tables, and text panels should sit below or beside that title region rather than replacing it.
 
 <!-- @layout:fullbleed:start qa=false -->
-#### Fullbleed
+Atmospheric cover, closing, or divider layout with one dominant image-title component.
 
-Full-canvas layout for slides where a single image dominates the entire canvas with text composited over it. Use for opening (cover) and closing slides, or atmospheric section dividers.
+#### Fullbleed
 
 Structural intent:
 - Single slot: place one `image-title` component directly inside `.page`. The component is self-contained — it manages its own image, blur, overlay, and text layers internally.
@@ -542,22 +546,26 @@ Structural intent:
 <!-- @layout:fullbleed:end -->
 
 <!-- @layout:narrative:start qa=true -->
-#### Narrative
+Asymmetric primary-secondary spread with a dominant visual/evidence zone on the left and a narrower explanatory or action zone on the right.
 
-Asymmetric two-column layout with the left column wider (1.618fr) and the right column narrower (1fr). Use when one side needs more visual or reading weight than the other.
+#### Narrative
 
 Structural intent:
-- left slot: wider zone (1.618fr) — can hold any component(s)
-- right slot: narrower zone (1fr) — can hold any component(s)
+- left slot: primary zone (1.618fr) — dominant evidence, image, chart, table, or other high-weight component(s)
+- right slot: secondary zone (1fr) — explanation, implication, action, TOC, vertical flow, or supporting component(s)
 
-Every slot accepts 1 or more components. The LLM decides what each slot contains — there is no text/visual semantic preset.
+Every slot accepts 1 or more components, but the layout should preserve a primary-secondary hierarchy. Do not use `narrative` for two equally weighted items; use `halves` instead.
 
 
 ```html
 <section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;overflow:hidden;">
-      <div class="narrative-grid">
+      <div style="display:flex;flex-direction:column;gap:10px;margin:56px 64px 28px;max-width:760px;position:relative;z-index:2;">
+        <p class="eyebrow">Chapter / Section</p>
+        <h2>Slide claim or takeaway</h2>
+      </div>
+      <div class="narrative-grid" style="height:calc(100% - 150px);">
 
         <!-- [slot: left] — 1+ components; suggested: image-title, echart-panel, text-panel -->
         <div>
@@ -596,28 +604,32 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 ##### Tips
 - **Grid container uses `.narrative-grid` class.** Applies `minmax(0, Nfr)` tracks, `overflow:hidden` on all children, and `align-items:stretch` so both columns fill the full row height. Do not override with `align-items:start` — that collapses columns to content height and exposes the page background.
-- **No semantic preset.** Either slot can hold any component. The wider left column naturally suits visually dominant content (full-bleed media, wide charts), but this is not a hard rule.
+- **Primary-secondary intent.** The wider left column should carry the stronger visual or evidentiary weight. If both sides are equally important, use `halves`.
 - **Dark panel variant.** When a slot uses a dark background, override CSS variables on that container: `--text-primary`, `--text-secondary`, `--text-muted`, `--line`, `--line-strong` — all set to white-family values. Use `.page-number--light`.
 - **Background image inside a slot.** Use the three-layer z-index pattern: background `z-index:0`, dark overlay `z-index:1`, content `z-index:2`.
 <!-- @layout:narrative:end -->
 
 <!-- @layout:narrative-reverse:start qa=true -->
-#### Narrative Reverse
+Asymmetric primary-secondary spread with the narrower explanatory or action zone on the left and the dominant visual/evidence zone on the right.
 
-Asymmetric two-column layout with the left column narrower (1fr) and the right column wider (1.618fr). Mirror of `narrative` — same grid class with `--reverse` modifier.
+#### Narrative Reverse
 
 Structural intent:
-- left slot: narrower zone (1fr) — can hold any component(s)
-- right slot: wider zone (1.618fr) — can hold any component(s)
+- left slot: secondary zone (1fr) — explanation, implication, action, TOC, vertical flow, or supporting component(s)
+- right slot: primary zone (1.618fr) — dominant evidence, image, chart, table, or other high-weight component(s)
 
-Every slot accepts 1 or more components. The LLM decides what each slot contains — there is no text/visual semantic preset.
+Every slot accepts 1 or more components, but the layout should preserve a primary-secondary hierarchy. Do not use `narrative-reverse` for two equally weighted items; use `halves` instead.
 
 
 ```html
 <section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;overflow:hidden;">
-      <div class="narrative-grid narrative-grid--reverse">
+      <div style="display:flex;flex-direction:column;gap:10px;margin:56px 64px 28px;max-width:760px;position:relative;z-index:2;">
+        <p class="eyebrow">Chapter / Section</p>
+        <h2>Slide claim or takeaway</h2>
+      </div>
+      <div class="narrative-grid narrative-grid--reverse" style="height:calc(100% - 150px);">
 
         <!-- [slot: left] — 1+ components; suggested: text-panel, toc, flow-vertical, echart-panel -->
         <div>
@@ -635,33 +647,33 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 ##### Tips
 - **Same `.narrative-grid` class as `narrative`, with `--reverse` modifier.** Add both `narrative-grid` and `narrative-grid--reverse` to the grid container. The modifier swaps column proportions to `1fr left / 1.618fr right`.
-- **No semantic preset.** Either slot can hold any component — visual on the right, text on the left, or any other combination based on content needs.
+- **Primary-secondary intent.** The wider right column should carry the stronger visual or evidentiary weight. If both sides are equally important, use `halves`.
 - **Dark panel variant.** Same CSS variable override pattern as `narrative`: set `--text-primary` etc. to white-family values on the panel container, all child components inherit automatically.
 <!-- @layout:narrative-reverse:end -->
 
 <!-- @layout:highlight-cols:start qa=true -->
-#### Highlight Cols
+Parallel 3-5 item spread for comparable proof points, options, features, metrics, or evidence blocks.
 
-Equal N-column layout. Use when 3 or more parallel items of roughly equal visual weight should appear side by side — proof blocks, highlights, feature comparisons, stat groups, or any multi-column editorial spread.
+#### Highlight Cols
 
-A short section header is optional but recommended. In Monet, that header should stay lean: eyebrow plus title only, with no intro paragraph competing with the columns below.
+A short section header is required for normal content uses. In Monet, that header should stay lean: eyebrow plus title only, with no intro paragraph competing with the columns below.
 
 Structural intent:
 - each slot: 1fr column — any component(s)
 - column count: determined by the number of direct child divs in the grid container; `auto-fit` distributes space equally
 
-Every slot accepts 1 or more components. Add or remove child divs to control column count — 3 is the default, but 4 or 5 columns work equally well.
+Every slot accepts 1 or more components. Add or remove child divs to control column count — 3 is the default, but 4 or 5 columns work equally well. Use only for comparable items; do not mix unrelated content types just because the slide needs multiple blocks.
 
 ```html
 <section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
-    <div class="page">
-      <div style="display:flex;flex-direction:column;gap:10px;margin-bottom:28px;max-width:520px;">
+    <div class="page" style="overflow:hidden;">
+      <div style="display:flex;flex-direction:column;gap:10px;margin:56px 64px 28px;max-width:760px;position:relative;z-index:2;">
         <p class="eyebrow">Section Label</p>
-        <h2 style="font-size:52px;line-height:0.94;text-transform:uppercase;">Short framing title for the parallel columns</h2>
+        <h2 style="font-size:52px;line-height:0.94;text-transform:uppercase;">Slide claim or takeaway</h2>
       </div>
 
-      <div class="highlight-cols-grid" style="flex:1;min-height:0;">
+      <div class="highlight-cols-grid" style="height:calc(100% - 150px);">
 
         <!-- [slot: 1] — 1+ components; suggested: editorial-image-top, editorial-text-top, echart-panel -->
         <div>
@@ -700,28 +712,32 @@ Every slot accepts 1 or more components. Add or remove child divs to control col
 - **Grid container needs `flex:1;min-height:0` inline** when inside `.page` (which is flex-column). The class handles column sizing; the inline style handles row stretch.
 - **Header stays lean.** If you add a section header above the grid, use only `eyebrow + title`. Do not add an intro paragraph; the columns themselves should carry the explanation.
 - **Column count = number of direct child divs.** `repeat(auto-fit, minmax(0, 1fr))` distributes available width equally across however many children exist. Add a 4th or 5th div to get 4 or 5 columns — no CSS change needed.
-- **Equal columns — no hierarchy.** All slots carry the same visual weight. Adjust content density to suit the slide purpose; do not artificially inflate one column to create false hierarchy.
+- **Parallel items only.** All slots carry the same visual weight and should represent the same kind of thing: proof points, options, features, metrics, or evidence blocks.
 - **When using 4-5 columns, compress the header.** Keep the title to one or two short lines so the grid retains most of the slide height.
 - **Do not set fixed heights on editorial components.** Let components fill height via flexbox stretch.
 <!-- @layout:highlight-cols:end -->
 
 <!-- @layout:halves:start qa=true -->
-#### Halves
+Balanced two-up comparison for two equally important items, charts, cases, evidence blocks, or before/after states.
 
-Equal two-column layout. Use when two items of equal visual weight should appear side by side — paired charts, dual evidence blocks, before/after comparisons, or any two-column editorial spread.
+#### Halves
 
 Structural intent:
 - left slot: 1fr column — any component(s)
 - right slot: 1fr column — any component(s)
 
-Every slot accepts 1 or more components. The LLM decides what each slot contains — both columns are fully equal with no hierarchy preset.
+Every slot accepts 1 or more components. Both columns are fully equal by design. Do not use `halves` when one side should dominate; use `narrative` or `narrative-reverse` instead.
 
 
 ```html
 <section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="overflow:hidden;">
-      <div class="halves-grid" style="flex:1;min-height:0;">
+      <div style="display:flex;flex-direction:column;gap:10px;margin:56px 64px 28px;max-width:760px;position:relative;z-index:2;">
+        <p class="eyebrow">Chapter / Section</p>
+        <h2>Slide claim or takeaway</h2>
+      </div>
+      <div class="halves-grid" style="height:calc(100% - 150px);">
 
         <!-- [slot: left] — 1+ components; suggested: echart-panel, data-table, editorial-image-top -->
         <div>
@@ -755,27 +771,31 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 ##### Tips
 - **Grid container needs `flex:1;min-height:0` inline** when inside `.page`. The class handles column sizing.
-- **Equal columns — no hierarchy.** Both slots carry the same weight. Choose components based on content, not a fixed text/visual assignment.
+- **Equal columns — no hierarchy.** Both slots carry the same weight. Use this for balanced comparison, not primary-secondary explanation.
 - **Gap `40px` is intentional.** The slightly wider gap than `three-col` (32px) compensates for the larger individual column width.
 <!-- @layout:halves:end -->
 
 <!-- @layout:stacked:start qa=true -->
-#### Stacked
+Top-bottom synthesis layout with compact framing, status, or process context above a larger evidence, table, chart, or detail zone.
 
-Two-row vertical layout in a fixed golden-ratio proportion: top row takes 1fr and bottom row takes 1.618fr. Use when a horizontal component (process flow, stat row, header band) should anchor the top, with a taller content zone below.
+#### Stacked
 
 Structural intent:
-- top slot: `1fr` height — upper zone in golden-ratio proportion
-- bottom slot: `1.618fr` height — larger lower zone fills remaining space
+- top slot: `1fr` height — compact framing, status row, process overview, or synthesis component
+- bottom slot: `1.618fr` height — larger evidence, table, chart, media, or detail component
 
-Every slot accepts 1 or more components. The LLM decides what each slot contains — there is no semantic preset for either row.
+Every slot accepts 1 or more components, but the layout should preserve a synthesis-over-detail relationship. Do not use `stacked` as a generic vertical layout for unrelated blocks.
 
 
 ```html
 <section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;">
-      <div class="stacked-grid">
+      <div style="display:flex;flex-direction:column;gap:10px;margin:56px 64px 28px;max-width:760px;position:relative;z-index:2;">
+        <p class="eyebrow">Chapter / Section</p>
+        <h2>Slide claim or takeaway</h2>
+      </div>
+      <div class="stacked-grid" style="height:calc(100% - 150px);">
 
         <!-- [slot: top] — 1+ components; suggested: flow-horizontal, stat-row -->
         <div class="stacked-top">
@@ -814,7 +834,7 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 ##### Tips
 - **Top and bottom rows follow a fixed 1 : 1.618 golden-ratio proportion.** The top slot takes 1fr and the bottom takes 1.618fr — both rows are sized relative to the total canvas height, not by their content.
 - **Both slots clip overflow.** `min-height: 0` on both `.stacked-top` and `.stacked-bottom` ensures content cannot break out of its row.
-- **Both slots are fully equal in kind.** There is no preset for which slot holds "process" vs "data" — place any combination of components that fits the slide narrative.
+- **Synthesis over detail.** The top row should frame or summarize; the bottom row should carry the larger supporting detail.
 - **Dark background variant.** Set CSS variable overrides (`--text-primary` etc.) on `.stacked-grid` to cascade into both slots automatically.
 <!-- @layout:stacked:end -->
 

package/lib/design/designs.ts

@@ -18,7 +18,7 @@ import {
   statSync,
   writeFileSync,
 } from "fs"
-import { join, resolve, basename } from "path"
+import { dirname, join, resolve, basename } from "path"
 import { tmpdir } from "os"
 import { parseFrontmatter } from "../frontmatter"
 import {
@@ -55,6 +55,10 @@ export interface CreateDesignPackageArgs {
   overwrite?: boolean
 }
 
+export interface CreateDesignDraftArgs extends CreateDesignPackageArgs {
+  workspaceRoot: string
+}
+
 export interface CreateDesignPackageResult {
   ok: true
   name: string
@@ -64,6 +68,16 @@ export interface CreateDesignPackageResult {
   overwritten: boolean
 }
 
+export interface InstallDesignDraftArgs {
+  workspaceRoot: string
+  name: string
+  overwrite?: boolean
+}
+
+export interface InstallDesignDraftResult extends CreateDesignPackageResult {
+  sourcePath: string
+}
+
 export interface ValidateDesignPackageResult {
   ok: boolean
   name: string
@@ -250,6 +264,90 @@ export function createDesignPackage(args: CreateDesignPackageArgs): CreateDesign
   }
 }
 
+/** Create a project-local design draft under .revela/drafts/designs/<name>/. */
+export function createDesignDraftPackage(args: CreateDesignDraftArgs): CreateDesignPackageResult {
+  const name = normalizeDesignName(args.name)
+  const designMd = args.designMd?.trim()
+  const previewHtml = args.previewHtml?.trim()
+
+  if (!designMd) throw new Error("designMd is required")
+  if (!previewHtml) throw new Error("previewHtml is required")
+
+  const target = designDraftDir(args.workspaceRoot, name)
+  const existed = existsSync(target)
+  if (existed && !args.overwrite) {
+    throw new Error(`Design draft '${name}' already exists. Pass overwrite=true to replace it.`)
+  }
+
+  mkdirSync(dirname(target), { recursive: true })
+  if (existed) {
+    rmSync(target, { recursive: true, force: true })
+  }
+  mkdirSync(target, { recursive: true })
+  writeFileSync(join(target, "DESIGN.md"), `${designMd}\n`, "utf-8")
+  writeFileSync(join(target, "preview.html"), `${previewHtml}\n`, "utf-8")
+
+  const validation = validateDesignDraftPackage(args.workspaceRoot, name)
+  if (!validation.ok) {
+    throw new Error(`Created design draft is invalid: ${validation.errors.join("; ")}`)
+  }
+
+  return {
+    ok: true,
+    name,
+    path: target,
+    files: ["DESIGN.md", "preview.html"],
+    base: args.base,
+    overwritten: existed,
+  }
+}
+
+/** Validate a project-local design draft. */
+export function validateDesignDraftPackage(workspaceRoot: string, nameInput: string): ValidateDesignPackageResult {
+  let name = nameInput
+  try {
+    name = normalizeDesignName(nameInput)
+  } catch {
+    // validateDesignPackageAt records the invalid-name error.
+  }
+  return validateDesignPackageAt(nameInput, designDraftDir(workspaceRoot, name))
+}
+
+/** Install a validated project-local design draft into the user-level design registry. */
+export function installDesignDraftPackage(args: InstallDesignDraftArgs): InstallDesignDraftResult {
+  const name = normalizeDesignName(args.name)
+  const sourcePath = designDraftDir(args.workspaceRoot, name)
+  const validation = validateDesignDraftPackage(args.workspaceRoot, name)
+  if (!validation.ok) {
+    throw new Error(`Design draft is invalid: ${validation.errors.join("; ")}`)
+  }
+
+  const target = join(DESIGNS_DIR, name)
+  const existed = existsSync(target)
+  if (existed && !args.overwrite) {
+    throw new Error(`Design '${name}' already exists. Pass overwrite=true to replace it.`)
+  }
+
+  try {
+    mkdirSync(DESIGNS_DIR, { recursive: true })
+    if (existed) {
+      rmSync(target, { recursive: true, force: true })
+    }
+    cpSync(sourcePath, target, { recursive: true })
+  } catch (e) {
+    throw new Error(`Installing design draft requires write access to Revela user config at ${DESIGNS_DIR}: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  return {
+    ok: true,
+    name,
+    path: target,
+    sourcePath,
+    files: ["DESIGN.md", "preview.html"],
+    overwritten: existed,
+  }
+}
+
 function hasDataAttribute(html: string, attr: string, value: string): boolean {
   const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
   return new RegExp(`${attr}\\s*=\\s*(["'])${escaped}\\1`).test(html)
@@ -289,6 +387,16 @@ 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
+  try {
+    name = normalizeDesignName(nameInput)
+  } catch {
+    // validateDesignPackageAt records the invalid-name error.
+  }
+  return validateDesignPackageAt(nameInput, join(DESIGNS_DIR, name))
+}
+
+function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesignPackageResult {
   let name = nameInput
   const errors: string[] = []
   try {
@@ -297,7 +405,6 @@ export function validateDesignPackage(nameInput: string): ValidateDesignPackageR
     errors.push(e instanceof Error ? e.message : String(e))
   }
 
-  const dir = join(DESIGNS_DIR, name)
   const mdPath = join(dir, "DESIGN.md")
   const previewPath = join(dir, "preview.html")
   const hasDesignMd = existsSync(mdPath)
@@ -360,6 +467,10 @@ export function validateDesignPackage(nameInput: string): ValidateDesignPackageR
   }
 }
 
+function designDraftDir(workspaceRoot: string, name: string): string {
+  return resolve(workspaceRoot, ".revela", "drafts", "designs", name)
+}
+
 // ---------------------------------------------------------------------------
 // Marker-based section / component parsing
 // ---------------------------------------------------------------------------

package/lib/domain/domains.ts

@@ -22,7 +22,7 @@ import {
   statSync,
   writeFileSync,
 } from "fs"
-import { join, resolve, basename } from "path"
+import { dirname, join, resolve, basename } from "path"
 import { tmpdir } from "os"
 import { parseFrontmatter } from "../frontmatter"
 import {
@@ -49,6 +49,44 @@ export interface DomainInfo {
   skillText: string
 }
 
+export interface CreateDomainPackageArgs {
+  name: string
+  domainMd: string
+  overwrite?: boolean
+}
+
+export interface CreateDomainDraftArgs extends CreateDomainPackageArgs {
+  workspaceRoot: string
+}
+
+export interface CreateDomainPackageResult {
+  ok: true
+  name: string
+  path: string
+  files: string[]
+  overwritten: boolean
+}
+
+export interface InstallDomainDraftArgs {
+  workspaceRoot: string
+  name: string
+  overwrite?: boolean
+}
+
+export interface InstallDomainDraftResult extends CreateDomainPackageResult {
+  sourcePath: string
+}
+
+export interface ValidateDomainPackageResult {
+  ok: boolean
+  name: string
+  path: string
+  hasIndustryMd: boolean
+  hasRequiredFrontmatter: boolean
+  hasBody: boolean
+  errors: string[]
+}
+
 // ---------------------------------------------------------------------------
 // Seed
 // ---------------------------------------------------------------------------
@@ -148,6 +186,188 @@ export function getDomainSkillMd(name?: string): string {
   return info.skillText
 }
 
+/** Normalize and validate a domain package name. */
+export function normalizeDomainName(name: string): string {
+  const normalized = name.trim().toLowerCase()
+  if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(normalized)) {
+    throw new Error("Domain name must be kebab-case using lowercase letters, numbers, and hyphens")
+  }
+  return normalized
+}
+
+/** Create a local domain package in ~/.config/revela/domains/<name>/. */
+export function createDomainPackage(args: CreateDomainPackageArgs): CreateDomainPackageResult {
+  const name = normalizeDomainName(args.name)
+  const domainMd = args.domainMd?.trim()
+
+  if (!domainMd) throw new Error("domainMd is required")
+
+  const target = join(DOMAINS_DIR, name)
+  const existed = existsSync(target)
+  if (existed && !args.overwrite) {
+    throw new Error(`Domain '${name}' already exists. Pass overwrite=true to replace it.`)
+  }
+
+  mkdirSync(DOMAINS_DIR, { recursive: true })
+  if (existed) {
+    rmSync(target, { recursive: true, force: true })
+  }
+  mkdirSync(target, { recursive: true })
+  writeFileSync(join(target, DOMAIN_FILE), `${domainMd}\n`, "utf-8")
+
+  const validation = validateDomainPackage(name)
+  if (!validation.ok) {
+    throw new Error(`Created domain package is invalid: ${validation.errors.join("; ")}`)
+  }
+
+  return {
+    ok: true,
+    name,
+    path: target,
+    files: [DOMAIN_FILE],
+    overwritten: existed,
+  }
+}
+
+/** Create a project-local domain draft under .revela/drafts/domains/<name>/. */
+export function createDomainDraftPackage(args: CreateDomainDraftArgs): CreateDomainPackageResult {
+  const name = normalizeDomainName(args.name)
+  const domainMd = args.domainMd?.trim()
+
+  if (!domainMd) throw new Error("domainMd is required")
+
+  const target = domainDraftDir(args.workspaceRoot, name)
+  const existed = existsSync(target)
+  if (existed && !args.overwrite) {
+    throw new Error(`Domain draft '${name}' already exists. Pass overwrite=true to replace it.`)
+  }
+
+  mkdirSync(dirname(target), { recursive: true })
+  if (existed) {
+    rmSync(target, { recursive: true, force: true })
+  }
+  mkdirSync(target, { recursive: true })
+  writeFileSync(join(target, DOMAIN_FILE), `${domainMd}\n`, "utf-8")
+
+  const validation = validateDomainDraftPackage(args.workspaceRoot, name)
+  if (!validation.ok) {
+    throw new Error(`Created domain draft is invalid: ${validation.errors.join("; ")}`)
+  }
+
+  return {
+    ok: true,
+    name,
+    path: target,
+    files: [DOMAIN_FILE],
+    overwritten: existed,
+  }
+}
+
+/** Validate a project-local domain draft. */
+export function validateDomainDraftPackage(workspaceRoot: string, nameInput: string): ValidateDomainPackageResult {
+  let name = nameInput
+  try {
+    name = normalizeDomainName(nameInput)
+  } catch {
+    // validateDomainPackageAt records the invalid-name error.
+  }
+  return validateDomainPackageAt(nameInput, domainDraftDir(workspaceRoot, name))
+}
+
+/** Install a validated project-local domain draft into the user-level domain registry. */
+export function installDomainDraftPackage(args: InstallDomainDraftArgs): InstallDomainDraftResult {
+  const name = normalizeDomainName(args.name)
+  const sourcePath = domainDraftDir(args.workspaceRoot, name)
+  const validation = validateDomainDraftPackage(args.workspaceRoot, name)
+  if (!validation.ok) {
+    throw new Error(`Domain draft is invalid: ${validation.errors.join("; ")}`)
+  }
+
+  const target = join(DOMAINS_DIR, name)
+  const existed = existsSync(target)
+  if (existed && !args.overwrite) {
+    throw new Error(`Domain '${name}' already exists. Pass overwrite=true to replace it.`)
+  }
+
+  try {
+    mkdirSync(DOMAINS_DIR, { recursive: true })
+    if (existed) {
+      rmSync(target, { recursive: true, force: true })
+    }
+    cpSync(sourcePath, target, { recursive: true })
+  } catch (e) {
+    throw new Error(`Installing domain draft requires write access to Revela user config at ${DOMAINS_DIR}: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  return {
+    ok: true,
+    name,
+    path: target,
+    sourcePath,
+    files: [DOMAIN_FILE],
+    overwritten: existed,
+  }
+}
+
+/** Validate a local domain package for the minimum Revela domain contract. */
+export function validateDomainPackage(nameInput: string): ValidateDomainPackageResult {
+  let name = nameInput
+  try {
+    name = normalizeDomainName(nameInput)
+  } catch {
+    // validateDomainPackageAt records the invalid-name error.
+  }
+  return validateDomainPackageAt(nameInput, join(DOMAINS_DIR, name))
+}
+
+function validateDomainPackageAt(nameInput: string, dir: string): ValidateDomainPackageResult {
+  let name = nameInput
+  const errors: string[] = []
+  try {
+    name = normalizeDomainName(nameInput)
+  } catch (e) {
+    errors.push(e instanceof Error ? e.message : String(e))
+  }
+
+  const mdPath = join(dir, DOMAIN_FILE)
+  const hasIndustryMd = existsSync(mdPath)
+  let hasRequiredFrontmatter = false
+  let hasBody = false
+
+  if (!existsSync(dir)) errors.push(`Domain directory does not exist: ${dir}`)
+  if (!hasIndustryMd) errors.push(`${DOMAIN_FILE} is missing`)
+
+  if (hasIndustryMd) {
+    try {
+      const text = readFileSync(mdPath, "utf-8")
+      const { meta, body } = parseFrontmatter(text)
+      const required = ["name", "description", "author", "version"]
+      const missing = required.filter((field) => !meta[field]?.trim())
+      hasRequiredFrontmatter = missing.length === 0
+      hasBody = body.trim().length > 0
+      if (!hasRequiredFrontmatter) errors.push(`INDUSTRY.md frontmatter is missing required field(s): ${missing.join(", ")}`)
+      if (!hasBody) errors.push("INDUSTRY.md body/guidance is empty")
+      if (meta.name && meta.name.trim() !== name) errors.push(`INDUSTRY.md frontmatter name '${meta.name.trim()}' does not match package name '${name}'`)
+    } catch (e) {
+      errors.push(`INDUSTRY.md could not be parsed: ${e instanceof Error ? e.message : String(e)}`)
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    name,
+    path: dir,
+    hasIndustryMd,
+    hasRequiredFrontmatter,
+    hasBody,
+    errors,
+  }
+}
+
+function domainDraftDir(workspaceRoot: string, name: string): string {
+  return resolve(workspaceRoot, ".revela", "drafts", "domains", name)
+}
+
 /** Remove an installed domain. Throws if not found or is the protected default. */
 export function removeDomain(name: string): void {
   if (name === DEFAULT_DOMAIN) {

package/lib/runtime/index.ts

@@ -4,18 +4,24 @@ import { dirname, resolve } from "path"
 import {
   activeDesign,
   activateDesign,
+  createDesignDraftPackage,
   createDesignPackage,
   getDesignSection,
   getDesignSkillMd,
+  installDesignDraftPackage,
   listDesigns,
   seedBuiltinDesigns,
+  validateDesignDraftPackage,
   validateDesignPackage,
 } from "../design/designs"
 import { createDeckFoundation as createDeckFoundationShell } from "../deck-html/foundation"
-import { activeDomain, activateDomain, getDomainSkillMd, listDomains, seedBuiltinDomains } from "../domain/domains"
+import { activeDomain, activateDomain, createDomainDraftPackage, createDomainPackage, getDomainSkillMd, installDomainDraftPackage, listDomains, seedBuiltinDomains, validateDomainDraftPackage, validateDomainPackage } from "../domain/domains"
 import { computeNarrativeHash } from "../narrative-state/hash"
 import { compileNarrativeVault } from "../narrative-vault/compile"
+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 { extractDesignClasses } from "../design/designs"
 import { recordRenderedArtifact, workspaceRelative } from "../workspace-state/rendered-artifacts"
@@ -32,6 +38,10 @@ export interface RuntimeFileInput extends RuntimeWorkspaceInput {
   file: string
 }
 
+export interface RuntimeNarrativeAutoCompileInput extends RuntimeWorkspaceInput {
+  touched?: string[]
+}
+
 export interface RuntimeDeckFoundationInput extends RuntimeWorkspaceInput {
   outputPath: string
   title: string
@@ -55,12 +65,28 @@ export interface RuntimeDesignCreateInput {
   overwrite?: boolean
 }
 
+export interface RuntimeDesignDraftCreateInput extends RuntimeDesignCreateInput, RuntimeWorkspaceInput {}
+
+export interface RuntimeDomainCreateInput {
+  name: string
+  domainMd: string
+  overwrite?: boolean
+}
+
+export interface RuntimeDomainDraftCreateInput extends RuntimeDomainCreateInput, RuntimeWorkspaceInput {}
+
+export interface RuntimeDraftInstallInput extends RuntimeWorkspaceInput {
+  name: string
+  overwrite?: boolean
+}
+
 export interface RuntimeNameInput {
   name: string
 }
 
 export function doctor(input: RuntimeWorkspaceInput = {}) {
   const workspaceRoot = root(input.workspaceRoot)
+  const domain = activeDomainDoctorInfo()
   return {
     ok: true,
     version: pkg.version,
@@ -69,6 +95,8 @@ export function doctor(input: RuntimeWorkspaceInput = {}) {
     hasDeckPlan: existsSync(resolve(workspaceRoot, "deck-plan")),
     hasDecksJson: existsSync(resolve(workspaceRoot, "DECKS.json")),
     activeDesign: safe(activeDesign),
+    activeDomain: domain.name,
+    activeDomainDescription: domain.description,
   }
 }
 
@@ -86,6 +114,18 @@ export function markdownQa(input: RuntimeWorkspaceInput & MarkdownQaOptions = {}
   })
 }
 
+export function autoCompileNarrative(input: RuntimeNarrativeAutoCompileInput = {}) {
+  const workspaceRoot = root(input.workspaceRoot)
+  return autoCompileNarrativeVault(workspaceRoot, input.touched ?? [])
+}
+
+export function extractNarrativeVaultMarkdownPatchTargets(input: RuntimeWorkspaceInput & { patch: string }) {
+  const workspaceRoot = root(input.workspaceRoot)
+  return extractNarrativeVaultMarkdownTargetsFromPatch(input.patch, workspaceRoot)
+}
+
+export { formatArtifactQaUserNotice, formatMarkdownQaUserNotice }
+
 export function readDeckPlan(input: RuntimeWorkspaceInput = {}) {
   const workspaceRoot = root(input.workspaceRoot)
   const compiled = compileNarrativeVault(workspaceRoot)
@@ -220,6 +260,30 @@ export function designValidate(input: RuntimeNameInput) {
   return validateDesignPackage(requiredName(input, "design"))
 }
 
+export function designDraftCreate(input: RuntimeDesignDraftCreateInput) {
+  return createDesignDraftPackage({
+    workspaceRoot: root(input.workspaceRoot),
+    name: requiredString(input?.name, "design name"),
+    base: input.base,
+    designMd: requiredString(input?.designMd, "designMd"),
+    previewHtml: requiredString(input?.previewHtml, "previewHtml"),
+    overwrite: input.overwrite ?? false,
+  })
+}
+
+export function designDraftValidate(input: RuntimeWorkspaceInput & RuntimeNameInput) {
+  return validateDesignDraftPackage(root(input.workspaceRoot), requiredName(input, "design draft"))
+}
+
+export function designDraftInstall(input: RuntimeDraftInstallInput) {
+  seedBuiltinDesigns()
+  return installDesignDraftPackage({
+    workspaceRoot: root(input.workspaceRoot),
+    name: requiredName(input, "design draft"),
+    overwrite: input.overwrite ?? false,
+  })
+}
+
 export interface DesignRulesReadinessResult {
   ok: boolean
   activeDesign: string
@@ -322,6 +386,42 @@ export function domainActivate(input: RuntimeNameInput) {
   }
 }
 
+export function domainCreate(input: RuntimeDomainCreateInput) {
+  seedBuiltinDomains()
+  return createDomainPackage({
+    name: requiredString(input?.name, "domain name"),
+    domainMd: requiredString(input?.domainMd, "domainMd"),
+    overwrite: input.overwrite ?? false,
+  })
+}
+
+export function domainValidate(input: RuntimeNameInput) {
+  seedBuiltinDomains()
+  return validateDomainPackage(requiredName(input, "domain"))
+}
+
+export function domainDraftCreate(input: RuntimeDomainDraftCreateInput) {
+  return createDomainDraftPackage({
+    workspaceRoot: root(input.workspaceRoot),
+    name: requiredString(input?.name, "domain name"),
+    domainMd: requiredString(input?.domainMd, "domainMd"),
+    overwrite: input.overwrite ?? false,
+  })
+}
+
+export function domainDraftValidate(input: RuntimeWorkspaceInput & RuntimeNameInput) {
+  return validateDomainDraftPackage(root(input.workspaceRoot), requiredName(input, "domain draft"))
+}
+
+export function domainDraftInstall(input: RuntimeDraftInstallInput) {
+  seedBuiltinDomains()
+  return installDomainDraftPackage({
+    workspaceRoot: root(input.workspaceRoot),
+    name: requiredName(input, "domain draft"),
+    overwrite: input.overwrite ?? false,
+  })
+}
+
 function root(workspaceRoot: string | undefined): string {
   return resolve(workspaceRoot || process.cwd())
 }
@@ -334,6 +434,17 @@ function safe<T>(fn: () => T): T | undefined {
   }
 }
 
+function activeDomainDoctorInfo(): { name: string; description: string } {
+  try {
+    seedBuiltinDomains()
+    const name = activeDomain()
+    const description = listDomains().find((domain) => domain.name === name)?.description ?? ""
+    return { name, description }
+  } catch {
+    return { name: safe(activeDomain) ?? "", description: "" }
+  }
+}
+
 function requiredName(input: RuntimeNameInput, label: string): string {
   const name = input?.name?.trim()
   if (!name) throw new Error(`${label} name is required`)

package/package.json

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

package/plugins/revela/hooks/revela_guard.ts

@@ -17,6 +17,15 @@ export async function runPreWriteChecks(input: string): Promise<HookResult> {
     messages.push(`Revela controls ${controlledStateFile}. Use Revela MCP/runtime tools or file-native narrative files instead of direct ${controlledStateFile} patches.`)
   }
 
+  const cacheTargets = extractNarrativeCachePatchTargets(input)
+  if (cacheTargets.length > 0) {
+    messages.push([
+      "Revela narrative cache patches are blocked.",
+      `Controlled cache target(s): ${cacheTargets.map((target) => `\`${target}\``).join(", ")}`,
+      "Edit `revela-narrative/**/*.md` instead; compile/cache files under `.opencode/revela/narrative-cache/` are regenerated.",
+    ].join("\n"))
+  }
+
   const deckTargets = extractDeckHtmlPatchTargets(input)
   if (deckTargets.length > 0) {
     const pluginRoot = resolve(process.env.PLUGIN_ROOT || dirname(dirname(fileURLToPath(import.meta.url))))
@@ -55,6 +64,16 @@ export function extractDeckHtmlPatchTargets(input: string): string[] {
   return [...targets].sort((a, b) => a.localeCompare(b))
 }
 
+export function extractNarrativeCachePatchTargets(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]*\.opencode\/revela\/narrative-cache\/[^\r\n]+)\s*$/gm
+    let match: RegExpExecArray | null
+    while ((match = pattern.exec(patch))) targets.add(match[1].trim())
+  }
+  return [...targets].sort((a, b) => a.localeCompare(b))
+}
+
 function patchPayloads(input: string): string[] {
   try {
     const parsed = JSON.parse(input)

package/plugins/revela/hooks/revela_post_write_notice.ts

@@ -24,6 +24,20 @@ export function extractDeckHtmlTargets(input: string): string[] {
   return [...targets].sort((a, b) => a.localeCompare(b))
 }
 
+export function patchPayloadsFromInput(input: string): string[] {
+  try {
+    const parsed = JSON.parse(input)
+    return [
+      parsed.patch,
+      parsed.args?.patch,
+      parsed.tool_input?.patch,
+      parsed.toolInput?.patch,
+    ].filter((item): item is string => typeof item === "string")
+  } catch {
+    return [input]
+  }
+}
+
 export function workspaceRootFromInput(input: string): string {
   try {
     const parsed = JSON.parse(input)
@@ -47,18 +61,16 @@ export function workspaceRootFromInput(input: string): string {
 
 export async function runPostWriteChecks(input: string): Promise<HookResult> {
   const messages: string[] = []
-  if (/revela-narrative\/.*\.md/.test(input)) {
-    messages.push("Revela narrative Markdown changed. Run `revela_markdown_qa` and `revela_compile_narrative` before treating the graph as usable.")
-  }
-
   const deckTargets = extractDeckHtmlTargets(input)
-  if (deckTargets.length === 0) return { ok: true, messages }
+  const hasPossibleNarrativeMarkdown = /revela-narrative\/.*\.md/.test(input)
+  if (deckTargets.length === 0 && !hasPossibleNarrativeMarkdown) return { ok: true, messages }
 
   const pluginRoot = resolve(process.env.PLUGIN_ROOT || dirname(dirname(fileURLToPath(import.meta.url))))
   const runtime = resolveRevelaRuntime({ pluginRoot })
   if (!runtime.ok || !runtime.runtimePath) {
+    const changed = deckTargets.length > 0 ? "deck HTML changed" : "narrative Markdown changed"
     messages.push([
-      "Revela deck HTML changed, but Codex hook could not locate the Revela runtime to run Artifact QA.",
+      `Revela ${changed}, but Codex hook could not locate the Revela runtime to run write-after checks.`,
       ...runtime.diagnostics.map((item) => `- ${item}`),
     ].join("\n"))
     return { ok: false, messages }
@@ -67,9 +79,28 @@ export async function runPostWriteChecks(input: string): Promise<HookResult> {
   const workspaceRoot = workspaceRootFromInput(input)
   const runtimeModule = await import(pathToFileURL(runtime.runtimePath).href)
   let ok = true
+
+  if (hasPossibleNarrativeMarkdown) {
+    const touched = new Set<string>()
+    for (const patch of patchPayloadsFromInput(input)) {
+      const targets = runtimeModule.extractNarrativeVaultMarkdownPatchTargets({ workspaceRoot, patch })
+      for (const target of targets) touched.add(target)
+    }
+
+    if (touched.size > 0) {
+      const result = runtimeModule.autoCompileNarrative({ workspaceRoot, touched: [...touched] })
+      messages.push(result.markdown ?? JSON.stringify(result, null, 2))
+      const notice = runtimeModule.formatMarkdownQaUserNotice?.(result)
+      if (notice) messages.push(notice)
+      if (!result.ok) ok = false
+    }
+  }
+
   for (const target of deckTargets) {
     const result = await runtimeModule.runDeckQa({ workspaceRoot, file: target })
     messages.push(result.markdown ?? JSON.stringify(result, null, 2))
+    const notice = runtimeModule.formatArtifactQaUserNotice?.(result.report)
+    if (notice) messages.push(notice)
     if (!result.ok) ok = false
   }
 

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

@@ -22,9 +22,17 @@ type RuntimeModule = {
   designActivate(input: any): any
   designCreate(input: any): any
   designValidate(input: any): any
+  designDraftCreate(input: any): any
+  designDraftValidate(input: any): any
+  designDraftInstall(input: any): any
   domainList(): any
   domainRead(input?: any): any
   domainActivate(input: any): any
+  domainCreate(input: any): any
+  domainValidate(input: any): any
+  domainDraftCreate(input: any): any
+  domainDraftValidate(input: any): any
+  domainDraftInstall(input: any): any
   storyRead(input?: any): any
   reviewDeckRead(input: any): Promise<any>
   reviewDeckOpen(input: any): Promise<any>
@@ -134,6 +142,35 @@ const tools = [
     description: "Validate a local Revela design package.",
     inputSchema: objectSchema({ name: requiredStringProp("Design name to validate.") }, ["name"]),
   },
+  {
+    name: "revela_design_draft_create",
+    description: "Create and validate a workspace-local Revela design draft package.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Design name in kebab-case."),
+      base: stringProp("Optional base design used as structural scaffold."),
+      designMd: requiredStringProp("Complete DESIGN.md content."),
+      previewHtml: requiredStringProp("Complete preview.html content."),
+      overwrite: booleanProp("Whether to replace an existing workspace draft. Defaults to false."),
+    }, ["name", "designMd", "previewHtml"]),
+  },
+  {
+    name: "revela_design_draft_validate",
+    description: "Validate a workspace-local Revela design draft package.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Design draft name to validate."),
+    }, ["name"]),
+  },
+  {
+    name: "revela_design_draft_install",
+    description: "Install a validated workspace-local Revela design draft into the user-level design registry.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Design draft name to install."),
+      overwrite: booleanProp("Whether to replace an existing user-level design package. Defaults to false."),
+    }, ["name"]),
+  },
   {
     name: "revela_domain_list",
     description: "List installed Revela narrative domains and the active domain.",
@@ -149,6 +186,47 @@ const tools = [
     description: "Activate a Revela narrative domain for future narrative authoring guidance.",
     inputSchema: objectSchema({ name: requiredStringProp("Domain name to activate.") }, ["name"]),
   },
+  {
+    name: "revela_domain_create",
+    description: "Create and validate a local Revela narrative domain package from complete INDUSTRY.md content.",
+    inputSchema: objectSchema({
+      name: requiredStringProp("Domain name in kebab-case."),
+      domainMd: requiredStringProp("Complete INDUSTRY.md content."),
+      overwrite: booleanProp("Whether to replace an existing local domain package. Defaults to false."),
+    }, ["name", "domainMd"]),
+  },
+  {
+    name: "revela_domain_validate",
+    description: "Validate a local Revela narrative domain package.",
+    inputSchema: objectSchema({ name: requiredStringProp("Domain name to validate.") }, ["name"]),
+  },
+  {
+    name: "revela_domain_draft_create",
+    description: "Create and validate a workspace-local Revela narrative domain draft package.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Domain name in kebab-case."),
+      domainMd: requiredStringProp("Complete INDUSTRY.md content."),
+      overwrite: booleanProp("Whether to replace an existing workspace draft. Defaults to false."),
+    }, ["name", "domainMd"]),
+  },
+  {
+    name: "revela_domain_draft_validate",
+    description: "Validate a workspace-local Revela narrative domain draft package.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Domain draft name to validate."),
+    }, ["name"]),
+  },
+  {
+    name: "revela_domain_draft_install",
+    description: "Install a validated workspace-local Revela narrative domain draft into the user-level domain registry.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      name: requiredStringProp("Domain draft name to install."),
+      overwrite: booleanProp("Whether to replace an existing user-level domain package. Defaults to false."),
+    }, ["name"]),
+  },
   {
     name: "revela_story_read",
     description: "Read a deterministic Revela Story map and optional Markdown view from the canonical narrative vault without mutating files.",
@@ -278,9 +356,17 @@ async function callTool(name: string, args: any): Promise<any> {
   if (name === "revela_design_activate") return r.designActivate(args)
   if (name === "revela_design_create") return r.designCreate(args)
   if (name === "revela_design_validate") return r.designValidate(args)
+  if (name === "revela_design_draft_create") return r.designDraftCreate(args)
+  if (name === "revela_design_draft_validate") return r.designDraftValidate(args)
+  if (name === "revela_design_draft_install") return r.designDraftInstall(args)
   if (name === "revela_domain_list") return r.domainList()
   if (name === "revela_domain_read") return r.domainRead(args)
   if (name === "revela_domain_activate") return r.domainActivate(args)
+  if (name === "revela_domain_create") return r.domainCreate(args)
+  if (name === "revela_domain_validate") return r.domainValidate(args)
+  if (name === "revela_domain_draft_create") return r.domainDraftCreate(args)
+  if (name === "revela_domain_draft_validate") return r.domainDraftValidate(args)
+  if (name === "revela_domain_draft_install") return r.domainDraftInstall(args)
   if (name === "revela_story_read") return r.storyRead(args)
   if (name === "revela_review_deck_read") return r.reviewDeckRead(args)
   if (name === "revela_review_deck_open") return r.reviewDeckOpen(args)

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

@@ -25,10 +25,12 @@ Design changes are visual/artifact-level unless they change claim meaning, evide
 
 When the user asks to create a new design, use `starter` as the default base design unless they specify another base. Interview the user before saving anything: collect visual references such as images, webpages, brands, decks, or text descriptions, plus must-have and must-avoid constraints. Summarize the design brief and visual schema, then wait for the user to confirm before creating files.
 
-After confirmation, read the base design with `revela_design_read`. Generate complete `DESIGN.md` and complete `preview.html` content, then call `revela_design_create`. For edits to an existing design, read the existing design first, preserve useful layout/component coverage, and call `revela_design_create` with `overwrite: true` only after the user confirms the edit brief. Always call `revela_design_validate` after creation or overwrite.
+After confirmation, read the base design with `revela_design_read`. Generate complete `DESIGN.md` and complete `preview.html` content, then call `revela_design_draft_create` to save a workspace-local draft under `.revela/drafts/designs/<name>/`. Always call `revela_design_draft_validate` after draft creation or overwrite. The direct registry tools `revela_design_create` and `revela_design_validate` remain available for existing workflows, but Codex design authoring should use the draft workflow before install.
+
+Install the draft globally only after the user confirms the validated draft should be installed. Call `revela_design_draft_install` to copy the draft into the user-level design registry. If a user-level design already exists, pass `overwrite: true` only after the user confirms replacement. In sandboxed Codex sessions, the install step may require permission to write Revela user config under `~/.config/revela`.
 
 `DESIGN.md` must include frontmatter with `name`, `description`, `author`, and `version`, plus valid marker blocks for `@design:foundation`, `@design:rules`, at least one `@layout`, and at least one `@component`.
 
 `preview.html` must be self-contained and directly openable in a browser. Every `<section class="slide">` must include `slide-qa` and exactly one direct `.slide-canvas` child. Every direct `.slide-canvas` is the fixed 1920px x 1080px export surface and must use explicit CSS with `width: 1920px` and `height: 1080px`; `.slide` may remain a viewport/navigation wrapper. Include a cover slide with `data-slide-role="cover"`, a closing slide with `data-slide-role="closing"`, and a visible sample for every `@component:*` using `data-preview-component="<component-name>"`.
 
-Do not automatically activate a newly created design. Report the saved path and tell the user they can activate it with `revela_design_activate`.
+Do not automatically activate a newly created design. Do not automatically activate a newly installed design. Report the draft path, installed path when installed, and tell the user they can activate it with `revela_design_activate`.

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

@@ -5,7 +5,7 @@ description: Use or switch Revela narrative domain guidance in Codex for init, r
 
 # Revela Domain
 
-Use this skill when the user asks about Revela domains, wants domain-specific narrative guidance, or asks to switch the active domain.
+Use this skill when the user asks about Revela domains, wants domain-specific narrative guidance, asks to switch the active domain, or asks to create a new domain.
 
 ## Workflow
 
@@ -16,3 +16,15 @@ Use this skill when the user asks about Revela domains, wants domain-specific na
 5. Do not treat domain guidance as evidence, source material, or proof for factual claims.
 
 Domain changes are narrative-framing preferences. They do not rewrite existing claims, evidence boundaries, artifacts, or deck plans unless the user asks for those updates.
+
+## Creating Or Editing Domains
+
+When the user asks to create a new domain, interview the user before saving anything. Collect the communication context, typical audience, decisions, claim patterns, evidence expectations, common objections, risks, research-gap heuristics, terminology to use, and terminology to avoid. Summarize the domain brief, then wait for the user to confirm before creating files.
+
+After confirmation, generate complete `INDUSTRY.md` content and call `revela_domain_draft_create` to save a workspace-local draft under `.revela/drafts/domains/<name>/`. Always call `revela_domain_draft_validate` after draft creation or overwrite.
+
+Install the draft globally only after the user confirms the validated draft should be installed. Call `revela_domain_draft_install` to copy the draft into the user-level domain registry. If a user-level domain already exists, pass `overwrite: true` only after the user confirms replacement. In sandboxed Codex sessions, the install step may require permission to write Revela user config under `~/.config/revela`.
+
+`INDUSTRY.md` must include frontmatter with `name`, `description`, `author`, and `version`, followed by concrete narrative guidance for audience framing, decision framing, claim standards, evidence expectations, objection/risk handling, and research-gap interpretation.
+
+Do not automatically activate a newly installed domain. Report the draft path, installed path when installed, and tell the user they can activate it with `revela_domain_activate`.

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

@@ -0,0 +1,33 @@
+---
+name: revela-upgrade
+description: Guide Revela Codex plugin upgrade, update, version, and reinstall requests while checking the running runtime version first.
+---
+
+# Revela Upgrade
+
+Use this skill when the user asks how to upgrade, update, reinstall, or check the version of the Revela Codex plugin.
+
+## Workflow
+
+1. Call `revela_doctor` first to inspect the currently running Revela runtime version.
+2. Report the current runtime version from doctor output. Do not check the latest version online unless the user explicitly asks you to look it up.
+3. Explain that the Codex Git marketplace ref and `.mcp.json` npm runtime pin are published together for the same Revela release.
+4. If the user wants a fixed release, guide them through removing the installed plugin, removing the marketplace entry, adding the desired release tag, then adding the plugin again:
+
+```bash
+codex plugin remove revela@revela
+codex plugin marketplace remove revela
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref vX.Y.Z
+codex plugin add revela@revela
+```
+
+5. If the user already tracks a branch or movable ref, guide them through upgrading the marketplace clone, then re-adding the plugin:
+
+```bash
+codex plugin marketplace upgrade revela
+codex plugin add revela@revela
+```
+
+6. Tell the user to start a new Codex thread after upgrading so Codex reloads the Revela skills, MCP tools, hooks, and runtime pin.
+
+Do not run `codex plugin remove`, `codex plugin marketplace remove`, `codex plugin marketplace add`, `codex plugin marketplace upgrade`, or `codex plugin add` unless the user explicitly asks you to perform the upgrade or reinstall.