@cfbender/cesium 0.3.6 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## v0.5.0 — 2026-05-12
+
+Block-mode refactor — `cesium_publish` now accepts a structured `blocks` array
+alongside the legacy `html` field. The server templates 15 block types from
+JSON; raw HTML stays available as a per-block escape hatch (`raw_html`,
+`diagram`). Framework CSS moves out of every artifact and into a single served
+`/theme.css`. Styleguide is generated from a catalog at request time.
+Critique is mode-aware. Expected savings on a balanced doc: roughly 2× output
+tokens, more on heavily structured artifacts.
+
+- **feat:** `cesium_publish({ blocks: Block[] })` — closed discriminated union
+  of 15 block types: `hero`, `tldr`, `section`, `prose`, `list`, `callout`,
+  `code`, `timeline`, `compare_table`, `risk_table`, `kv`, `pill_row`,
+  `divider`, `diagram`, `raw_html`. Mutually exclusive with `html`.
+- **feat:** Owned markdown subset (~80 lines, no dependency) for `prose`,
+  `tldr`, `callout`, list items, and table cells. Supports paragraphs, lists,
+  blockquotes, hr, hard breaks, `**bold**`, `*italic*`, `` `code` ``, local
+  links, and the safelisted inline tags `<kbd>`, `<span class="pill">`,
+  `<span class="tag">`.
+- **feat:** Sections recurse to depth 3; non-section children get auto-wrapped
+  in `<div class="card">` for visual consistency.
+- **feat:** `theme.css` served from `<state-dir>/theme.css` with a small
+  inline fallback (~8 lines) so standalone-opened `.html` files remain
+  readable. Existing artifacts (with full CSS inlined) are never rewritten and
+  stay self-contained.
+- **feat:** `cesium_styleguide` returns a markdown reference generated from
+  the block catalog at request time — schema, examples, and renderer can no
+  longer drift.
+- **feat:** `cesium_critique` is mode-aware. `html` mode adds a soft
+  `prefer-blocks` nag; `blocks` mode focuses on quality (raw-html overuse,
+  prose walls, missing tldr on long docs, table-shape, redundant raw_html,
+  nesting depth). Findings carry path tags like `blocks[2].children[1]`.
+- **feat:** Deep block validation walks the catalog schema per type. Returns
+  path-tagged errors with "did you mean" suggestions for common drift
+  (`label`→`k`, `value`→`v`, `description`→`text`, `med`→`medium`, etc.).
+- **feat:** System prompt fragment generated from the block catalog at plugin
+  load time — drift between schema and prompt is now physically impossible.
+- **feat:** `inputMode: "html" | "blocks"` recorded in artifact metadata and
+  surfaced as a small badge on index cards.
+- **feat:** Framework CSS extended with rules for every block-renderer
+  pattern: `dl.kv` (2-column grid), `.pill-row`, `.check-list`, `<hr
+  data-label>`, `figure.code`, timeline-item internals, `.lede`, plus
+  `.diagram svg text { fill: currentColor }` so SVGs inherit theme color.
+- **feat:** `escapeHtml` and `escapeAttr` throw a clear error on non-string
+  input instead of crashing inside `.replace()`.
+- **fix:** `ensureThemeCss` respects the configured `themePreset` (regression
+  introduced when the framework CSS was first extracted to a served file).
+- **fix:** `wait` test fixtures use relative timestamps so they don't go
+  stale.
+- **docs:** `AGENTS.md` updated with the new project layout, two-input-modes
+  architecture, catalog-as-source-of-truth, and softened CSS portability
+  invariant ("no external network resources; local `/theme.css` is allowed").
+
 ## v0.3.6 — 2026-05-11
 
 Adds a periodic-table-themed favicon for the cesium HTTP server.

package/README.md

@@ -1,4 +1,7 @@
-# Cesium
+<h1>
+  <img src="assets/favicon.svg" alt="" width="48" height="48" align="left" style="margin-right: 12px; vertical-align: middle;">
+  Cesium
+</h1>
 
 Cesium publishes substantive opencode agent responses — plans, code reviews,
 comparisons, explainers, audits, RFCs — as self-contained beautiful HTML artifacts
@@ -6,14 +9,7 @@ on disk, instead of dumping markdown into the terminal. The browser becomes the
 reading surface; the terminal stays the control surface. Each artifact is a single
 `.html` file: portable, archivable, viewable offline, shareable as a URL over SSH.
 
-v0.3.0 adds **interactive Q&A artifacts** — the agent can now publish a question
-form, wait for the user to answer in their browser, and receive the structured
-responses before continuing work.
-
-<video src="assets/cesium.mp4" autoplay loop muted playsinline width="720">
-  Demo video — see <a href="assets/cesium.mp4">assets/cesium.mp4</a> if it
-  doesn't play inline (some markdown viewers strip <code>&lt;video&gt;</code>).
-</video>
+https://github.com/user-attachments/assets/03fdf32a-c4d5-4819-84eb-d272178d35cb
 
 ## Examples
 
@@ -51,19 +47,37 @@ unreleased changes).
 
 ### CLI
 
+The CLI puts a `cesium` binary on your `PATH` for browsing, opening, and
+managing artifacts (`cesium ls`, `cesium open`, `cesium serve`, `cesium prune`,
+`cesium theme`).
+
+**Recommended: install with [mise](https://mise.jdx.dev/)** so cesium is pinned
+in your config and tracks with the rest of your toolchain. Add to your
+`~/.config/mise/config.toml` (or a project-local `mise.toml`):
+
+```toml
+[tools]
+"npm:@cfbender/cesium" = "latest"
+```
+
+Then run `mise install` (or `mise use -g npm:@cfbender/cesium@latest` for the
+one-liner equivalent). Pin to a specific release with `"0.3.6"` instead of
+`"latest"`. Upgrade with `mise upgrade npm:@cfbender/cesium`.
+
+**Alternative: install with bun directly:**
+
 ```bash
 bun install -g @cfbender/cesium
 ```
 
-This puts a `cesium` binary on your `PATH` (at `~/.bun/bin/cesium`). If
-`which cesium` returns nothing, add `~/.bun/bin` to your shell rc:
+This puts the binary at `~/.bun/bin/cesium`. If `which cesium` returns nothing,
+add `~/.bun/bin` to your shell rc:
 
 ```bash
 export PATH="$HOME/.bun/bin:$PATH"
 ```
 
-Upgrade later with `bun update -g @cfbender/cesium` (or via your version
-manager — e.g. `mise use -g npm:@cfbender/cesium@latest`). To uninstall:
+Upgrade with `bun update -g @cfbender/cesium`. Uninstall with
 `bun remove -g @cfbender/cesium`.
 
 ### Developing on cesium itself
@@ -471,7 +485,7 @@ Cesium took inspiration from:
 - [@trq212's tweet](https://x.com/trq212/status/2052809885763747935) on
   letting agents respond with HTML instead of dumping markdown into the
   terminal — the seed idea for the whole project.
-- **Octto** — for the model of an agent that publishes a live, browser-served
+- [Octto](https://github.com/vtemian/octto) — for the model of an agent that publishes a live, browser-served
   surface alongside the terminal, rather than replacing it.
 
 ## License

package/assets/styleguide.html

@@ -329,6 +329,89 @@
         color: var(--muted);
         text-transform: lowercase;
       }
+      .pill.accent {
+        background: color-mix(in srgb, var(--accent) 18%, var(--surface));
+        color: var(--accent);
+        font-weight: 600;
+      }
+
+      /* ranked list */
+      .ranked-list {
+        display: flex;
+        flex-direction: column;
+        gap: 1em;
+        margin: 0 0 1.5em;
+        padding: 0;
+        list-style: none;
+      }
+      .ranked-item {
+        background: var(--surface);
+        border: 1.5px solid var(--rule);
+        border-radius: 12px;
+        padding: 22px 26px;
+        display: grid;
+        grid-template-columns: 64px 1fr;
+        gap: 6px 24px;
+        align-items: start;
+      }
+      .ranked-item .rank-num {
+        font-family: var(--serif);
+        font-size: 2.4rem;
+        font-weight: 500;
+        color: var(--oat);
+        line-height: 1;
+        letter-spacing: -0.02em;
+        padding-top: 2px;
+      }
+      .ranked-item .rank-title {
+        font-family: var(--serif);
+        font-size: 1.2rem;
+        font-weight: 600;
+        color: var(--ink);
+        margin: 0 0 6px;
+        line-height: 1.3;
+      }
+      .ranked-item .rank-meta {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        flex-wrap: wrap;
+        margin-bottom: 14px;
+      }
+      .ranked-item .rank-body > p {
+        color: var(--ink-soft);
+        font-size: 0.95rem;
+        line-height: 1.65;
+        margin: 0 0 0.85em;
+      }
+      .ranked-item .rank-body > p:last-child {
+        margin-bottom: 0;
+      }
+      .ranked-item .rank-body > ul,
+      .ranked-item .rank-body > ol {
+        color: var(--ink-soft);
+        font-size: 0.95rem;
+        line-height: 1.65;
+        margin: 0 0 0.85em;
+        padding-left: 1.2em;
+      }
+      .ranked-item .rank-aside {
+        color: var(--muted);
+        font-size: 0.9rem;
+        line-height: 1.6;
+        padding-left: 14px;
+        border-left: 2px solid var(--rule);
+        margin: 0;
+      }
+      .ranked-item .rank-aside-label {
+        font-family: var(--mono);
+        font-size: 0.7rem;
+        font-weight: 600;
+        letter-spacing: 0.1em;
+        text-transform: uppercase;
+        color: var(--accent);
+        margin-right: 6px;
+      }
 
       /* byline */
       .byline {
@@ -845,6 +928,72 @@
         </div>
       </section>
 
+      <!-- ============================================================
+       Section 13 · Ranked list
+       ============================================================ -->
+      <section>
+        <p class="eyebrow">13 · ranked-list</p>
+        <h2 class="h-section"><span class="section-num">13</span>Ranked list</h2>
+        <p>
+          Use <code>.ranked-list</code> + <code>.ranked-item</code> for ordered recommendations,
+          findings, or rankings — anything that would otherwise be a heavy numbered
+          <code>&lt;h3&gt;</code> sequence. Each item gets a soft serif numeral on the left and a
+          calm title + meta + body on the right. Pair <code>.pill.accent</code> +
+          <code>.tag</code> in the meta row for impact and savings; use <code>.rank-aside</code> for
+          a quieter "bonus" addendum.
+        </p>
+
+        <ol class="ranked-list">
+          <li class="ranked-item">
+            <div class="rank-num">01</div>
+            <div class="rank-body">
+              <h3 class="rank-title">Replace the styleguide payload with a compact catalog</h3>
+              <div class="rank-meta">
+                <span class="pill accent">High impact</span>
+                <span class="tag">~6–8k tokens / call</span>
+              </div>
+              <p>
+                Return a structured Markdown reference of <em>class → purpose → minimal example</em>
+                instead of the full HTML framework. Realistic target: 3–5 KB / ~1k tokens, down from
+                ~7–9k.
+              </p>
+              <p class="rank-aside">
+                <span class="rank-aside-label">Bonus</span>
+                Derive the catalog from a single source so it can't drift from the framework.
+              </p>
+            </div>
+          </li>
+          <li class="ranked-item">
+            <div class="rank-num">02</div>
+            <div class="rank-body">
+              <h3 class="rank-title">Trim the system prompt fragment</h3>
+              <div class="rank-meta">
+                <span class="pill">Low impact</span>
+                <span class="tag">~400 tokens / session</span>
+              </div>
+              <p>
+                Remove redundancy with in-tool <code>description</code> strings. Nice but not
+                transformative.
+              </p>
+            </div>
+          </li>
+          <li class="ranked-item">
+            <div class="rank-num">03</div>
+            <div class="rank-body">
+              <h3 class="rank-title">Stop double-emitting CSS in <code>wrapDocument()</code></h3>
+              <div class="rank-meta">
+                <span class="pill">Disk only</span>
+                <span class="tag">~17 KB / artifact</span>
+              </div>
+              <p>
+                Inline the framework only when the linked stylesheet is unavailable; emit tokens
+                inline always.
+              </p>
+            </div>
+          </li>
+        </ol>
+      </section>
+
       <!-- ============================================================
        Footer / byline
        ============================================================ -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfbender/cesium",
-  "version": "0.3.6",
+  "version": "0.5.0",
   "description": "Beautiful self-contained HTML artifacts from your opencode agent.",
   "license": "MIT",
   "author": "Cody Bender",

package/src/cli/commands/serve.ts

@@ -4,6 +4,7 @@ import { parseArgs } from "node:util";
 import { loadConfig, type CesiumConfig } from "../../config.ts";
 import { ensureRunning, stopRunning } from "../../server/lifecycle.ts";
 import { resolveDisplayHost } from "../../tools/publish.ts";
+import { themeFromPreset, mergeTheme } from "../../render/theme.ts";
 
 export interface ServeContext {
   stdout: { write: (s: string) => void };
@@ -160,12 +161,14 @@ export async function serveCommand(argv: string[], ctx?: Partial<ServeContext>):
 
   let serverInfo: { port: number; url: string };
   try {
+    const theme = mergeTheme(themeFromPreset(effectiveCfg.themePreset), effectiveCfg.theme);
     serverInfo = await ensureRunning({
       stateDir: effectiveCfg.stateDir,
       port: effectiveCfg.port,
       portMax: effectiveCfg.portMax,
       idleTimeoutMs: effectiveCfg.idleTimeoutMs,
       hostname: effectiveCfg.hostname,
+      theme,
     });
   } catch (err) {
     const e = err as Error;

package/src/index.ts

@@ -10,12 +10,15 @@ import { createWaitTool } from "./tools/wait.ts";
 import { createStyleguideTool } from "./tools/styleguide.ts";
 import { createCritiqueTool } from "./tools/critique.ts";
 import { createStopTool } from "./tools/stop.ts";
+import { generateBlockFieldReference } from "./prompt/field-reference.ts";
 
-const PROMPT_FRAGMENT = await readFile(
+const rawFragment = await readFile(
   join(dirname(fileURLToPath(import.meta.url)), "prompt/system-fragment.md"),
   "utf8",
 );
 
+const PROMPT_FRAGMENT = rawFragment.replace("{{BLOCK_FIELD_REFERENCE}}", generateBlockFieldReference());
+
 export const CesiumPlugin: Plugin = async (ctx): Promise<Hooks> => {
   return {
     tool: {

package/src/prompt/field-reference.ts

@@ -0,0 +1,94 @@
+// Generates a compact block field reference from the catalog.
+// Injected into the system-fragment at plugin load time via placeholder replacement.
+// src/prompt/field-reference.ts
+
+import { blockCatalog } from "../render/blocks/catalog.ts";
+import type { Block } from "../render/blocks/types.ts";
+
+// ─── Schema → compact field description ──────────────────────────────────────
+
+type SchemaNode = Record<string, unknown>;
+
+function formatFieldType(node: SchemaNode): string {
+  if ("const" in node) return `"${String(node["const"])}"`;
+  const type = node["type"] as string | undefined;
+  if (type === undefined) return "unknown";
+  if (type === "string") {
+    const enumVals = node["enum"] as string[] | undefined;
+    if (enumVals !== undefined) return enumVals.map((e) => `"${e}"`).join(" | ");
+    return "string";
+  }
+  if (type === "number") return "number";
+  if (type === "boolean") return "boolean";
+  if (type === "array") {
+    const items = node["items"] as SchemaNode | undefined;
+    if (items !== undefined) {
+      const innerType = items["type"] as string | undefined;
+      if (innerType === "object") {
+        const props = items["properties"] as Record<string, SchemaNode> | undefined;
+        const req = items["required"] as string[] | undefined;
+        if (props !== undefined) {
+          const fields = Object.entries(props)
+            .filter(([k]) => k !== "type")
+            .map(([k, v]) => {
+              const isRequired = req !== undefined && req.includes(k);
+              return `${k}${isRequired ? "" : "?"}: ${formatFieldType(v)}`;
+            })
+            .join(", ");
+          return `[{ ${fields} }]`;
+        }
+        return "object[]";
+      }
+      if (innerType === "string") return "string[]";
+      return `${innerType ?? "unknown"}[]`;
+    }
+    return "array";
+  }
+  if (type === "object") return "object";
+  return type;
+}
+
+function formatBlockLine(type: Block["type"]): string {
+  const entry = blockCatalog[type];
+  const schema = entry.schema as SchemaNode;
+  const props = schema["properties"] as Record<string, SchemaNode> | undefined;
+  const required = schema["required"] as string[] | undefined;
+
+  if (props === undefined) return `- \`${type}\``;
+
+  const fields = Object.entries(props)
+    .filter(([k]) => k !== "type")
+    .map(([k, v]) => {
+      const isRequired = required !== undefined && required.includes(k);
+      return `${k}${isRequired ? "" : "?"}: ${formatFieldType(v)}`;
+    })
+    .join(", ");
+
+  return `- \`${type}\` — ${fields}`;
+}
+
+/**
+ * Generates a compact markdown block field reference from the catalog.
+ * This is injected into system-fragment.md at the {{BLOCK_FIELD_REFERENCE}} placeholder.
+ */
+export function generateBlockFieldReference(): string {
+  const lines = [
+    "## Block field reference",
+    "",
+    "For full schemas with rendered examples, call `cesium_styleguide`. Exact field names:",
+    "",
+  ];
+
+  for (const type of Object.keys(blockCatalog) as Block["type"][]) {
+    lines.push(formatBlockLine(type));
+  }
+
+  lines.push("");
+  lines.push(
+    "All `markdown` fields support `**bold**`, `*italic*`, `` `code` ``, lists, blockquotes, " +
+    "and the safelisted inline tags `<kbd>`, `<span class=\"pill\">`, `<span class=\"tag\">`. " +
+    "External URLs in links render as plain text.",
+  );
+
+  return lines.join("\n");
+}

package/src/prompt/system-fragment.md

@@ -1,97 +1,88 @@
 # Cesium — beautiful HTML artifacts
 
+Cesium publishes beautiful self-contained artifacts to a local server you can open in a browser.
+
 You have access to six tools:
 
 - `cesium_publish` — write a substantive response as a self-contained HTML document
 - `cesium_ask` — publish an interactive Q&A artifact; returns `{ id, httpUrl, ... }`
 - `cesium_wait` — block until the user completes a `cesium_ask` artifact (polls disk)
-- `cesium_styleguide` — fetch the full HTML design system reference (call this before writing anything complex)
-- `cesium_critique` — analyze a draft body for design-system adherence; returns a 0-100 score and findings
+- `cesium_styleguide` — fetch the full block reference (call before writing anything complex)
+- `cesium_critique` — analyze a draft artifact; returns a 0-100 score and findings
 - `cesium_stop` — stop the running cesium HTTP server
 
-## When to publish (vs. reply in terminal)
-
-Publish when:
-
-- Your response would be ≥ 400 words
-- It contains a comparison, decision matrix, or multi-section plan/PRD/RFC
-- It is a code review with more than 3 findings
-- It is a design proposal, audit, post-mortem, or explainer
-- The user is likely to re-read, share, or come back to it
-
-Stay in terminal for:
-
-- Short factual answers
-- Status updates ("done", "running tests", "fixed")
-- Mid-tool-call chatter
-- Single-paragraph replies
-- Acknowledgements
-
-User overrides:
+## Two input modes
+
+`cesium_publish` accepts either `blocks: Block[]` (preferred) or `html: string` (escape valve). Provide exactly one.
+
+**Prefer `blocks`** for plans, reviews, reports, explainers, comparisons, audits, design docs. Blocks are token-efficient (no structural boilerplate), server-templated, and machine-checkable. Use `html` only when the whole document needs bespoke art-direction. For isolated bespoke regions, use `raw_html` or `diagram` blocks.
+
+### Example
+
+```json
+{ "title": "Migration Guide", "kind": "plan", "blocks": [
+  { "type": "hero", "eyebrow": "v2", "title": "Migration Guide",
+    "meta": [{ "k": "Status", "v": "Draft" }, { "k": "Owner", "v": "platform" }] },
+  { "type": "tldr", "markdown": "**Summary:** Update one import path and bump the SDK." },
+  { "type": "section", "title": "What Changed", "children": [
+    { "type": "prose", "markdown": "The `auth` module is now a standalone package." },
+    { "type": "callout", "variant": "warn", "markdown": "Change `sdk/auth` imports before upgrading." }
+  ]},
+  { "type": "risk_table", "rows": [
+    { "risk": "Missed imports", "likelihood": "medium", "impact": "high", "mitigation": "Run codemods." }
+  ]},
+  { "type": "timeline", "items": [
+    { "label": "Phase 1", "text": "Audit existing imports", "date": "2026-06-01" },
+    { "label": "Phase 2", "text": "Run migration script" }
+  ]}
+]}
+```
 
-- "/cesium", "publish this", "make me an HTML report" → publish
-- "in terminal", "just tell me", "don't make a doc" → don't publish
+## Quick block reference
 
-When uncertain: publish AND emit a 2-3 line terminal summary pointing at the doc. Cheap to over-publish, expensive to under-publish.
+Call `cesium_styleguide` for full schemas and rendered examples.
 
-## How to write the body
+- `hero` — page-title header (eyebrow, subtitle, meta pairs)
+- `tldr` — summary box; at most one per document
+- `section` — numbered section with child blocks (depth ≤ 3)
+- `prose` — free-form markdown; `list` — bullet/numbered/checklist
+- `callout` — aside with variant: note/warn/risk; `divider` — rule
+- `code` — fenced code with lang; `timeline` — milestone list
+- `compare_table` — comparison grid; `risk_table` — risk grid
+- `kv` — key-value pairs; `pill_row` — pill/tag chips
+- `diagram` — SVG/HTML visual (scrubbed)
+- `raw_html` — custom HTML escape hatch (scrubbed; add `purpose`)
 
-The `html` argument is body-only (no `<!doctype>`, `<html>`, `<head>`, `<body>` wrappers — the plugin adds them).
+{{BLOCK_FIELD_REFERENCE}}
 
-Use these classes (full reference via `cesium_styleguide`):
+## When to use raw_html / diagram
 
-- `.eyebrow` `.h-display` `.h-section` `.section-num`
-- `.card` `.tldr` `.callout` (`.note`/`.warn`/`.risk`)
-- `.code` (with `.kw` `.str` `.cm` `.fn` highlights)
-- `.timeline` `.diagram` `.compare-table` `.risk-table`
-- `.kbd` `.pill` `.tag`
+- `diagram` — SVG visualizations, bespoke layouts.
+- `raw_html` — anything no typed block covers. Critique flags overuse (>2 blocks or >30% of body characters).
 
-Inline `style="..."` and inline `<svg>` are encouraged for bespoke diagrams. NEVER reference external resources (no `<script src>`, no remote fonts, no CDN images).
+## When to publish (vs. reply in terminal)
 
-## Tone
+Publish when: ≥ 400 words; comparison/matrix/plan/PRD/RFC; code review with >3 findings; design proposal/audit/explainer; or the user will re-read or share it. Stay in terminal for short answers and status updates.
 
-Warm, considered, not flashy. Match the aesthetic of a thoughtful design document, not marketing material.
+User overrides: "/cesium" or "publish this" → publish; "in terminal" → don't.
 
 ## Self-check before publishing
 
-For substantial artifacts (plans, reviews, comparisons, explainers > 500 words),
-call `cesium_critique` with your draft body BEFORE calling `cesium_publish`. Act
-on warn-level findings; consider suggest-level. info-level is FYI.
-
-If critique reports score < 70, revise the body before publishing.
+Call `cesium_critique` before `cesium_publish` on substantive artifacts. Mode is auto-detected (pass `html` or `blocks`). Act on warn-level findings; consider suggest-level. If score < 70, revise.
 
 ## After publishing
 
-The tool returns URLs (file://, http://). Print a short 2-line terminal summary like:
-
-```
-Cesium · <Title> (<kind>)
-  http://localhost:3030/projects/.../...
-  file:///.../...html
-```
-
-Do not paste the full document content into the terminal after publishing.
-
-## Stopping the server
-
-If the user asks to stop, restart, or recycle the cesium server (e.g. after a
-config change), call `cesium_stop`. The next `cesium_publish` will lazy-start
-a fresh server with the latest config.
+Print a 2-line terminal summary: `Cesium · <Title> (<kind>)` + the HTTP URL. Do not paste the full document content into the terminal.
 
 ## Interactive Q&A: cesium_ask + cesium_wait
 
-When you need structured user input before producing a final artifact (design tradeoffs,
-plan branches, confirmation gates), publish an interactive artifact:
-
 1. `cesium_ask({ title, body, questions: [...] })` → returns `{ id, httpUrl, ... }`
 2. Print the terminalSummary so the user knows where to click.
 3. `cesium_wait({ id })` → blocks until user finishes (or 10-min timeout).
-4. Decide next step from `result.answers` — typically `cesium_publish` with the chosen path.
+4. Decide next step from `result.answers`.
 
-Question types: pick_one, pick_many, confirm, ask_text, slider, react. The artifact
-is a permanent record of the conversation; once answered, controls freeze into a static
-markup that captures the user's decisions. Set `optional: true` on an `ask_text` question
-to add a Skip button (useful for "anything else?"-type follow-ups).
+Question types: pick_one, pick_many, confirm, ask_text, slider, react. Set `optional: true` on an `ask_text` question to add a Skip button. Don't use cesium_ask for trivial yes/no questions — use it when the question deserves to live on disk as a decision record.
+
+## Stopping the server
 
-Don't use cesium_ask for trivial yes/no questions you can ask in the terminal. Use it
-when the question deserves to live on disk as a decision record.
+Call `cesium_stop` to stop or restart. The next `cesium_publish` will lazy-start a fresh server.

package/src/render/blocks/catalog.ts

@@ -0,0 +1,39 @@
+// Catalog — source of truth: aggregates meta from every renderer module.
+// src/render/blocks/catalog.ts
+
+import type { Block, BlockMeta } from "./types.ts";
+import { meta as heroMeta } from "./renderers/hero.ts";
+import { meta as tldrMeta } from "./renderers/tldr.ts";
+import { meta as sectionMeta } from "./renderers/section.ts";
+import { meta as proseMeta } from "./renderers/prose.ts";
+import { meta as listMeta } from "./renderers/list.ts";
+import { meta as calloutMeta } from "./renderers/callout.ts";
+import { meta as codeMeta } from "./renderers/code.ts";
+import { meta as timelineMeta } from "./renderers/timeline.ts";
+import { meta as compareTableMeta } from "./renderers/compare-table.ts";
+import { meta as riskTableMeta } from "./renderers/risk-table.ts";
+import { meta as kvMeta } from "./renderers/kv.ts";
+import { meta as pillRowMeta } from "./renderers/pill-row.ts";
+import { meta as dividerMeta } from "./renderers/divider.ts";
+import { meta as diagramMeta } from "./renderers/diagram.ts";
+import { meta as rawHtmlMeta } from "./renderers/raw-html.ts";
+
+export const blockCatalog: Record<Block["type"], BlockMeta> = {
+  hero: heroMeta,
+  tldr: tldrMeta,
+  section: sectionMeta,
+  prose: proseMeta,
+  list: listMeta,
+  callout: calloutMeta,
+  code: codeMeta,
+  timeline: timelineMeta,
+  compare_table: compareTableMeta,
+  risk_table: riskTableMeta,
+  kv: kvMeta,
+  pill_row: pillRowMeta,
+  divider: dividerMeta,
+  diagram: diagramMeta,
+  raw_html: rawHtmlMeta,
+};
+
+export const blockTypes = Object.keys(blockCatalog) as Array<Block["type"]>;