mulmoclaude 0.5.2 → 0.6.0

package/server/utils/gemini.ts

@@ -1,4 +1,4 @@
-import { GoogleGenAI, type GenerateContentParameters } from "@google/genai";
+import { GoogleGenAI, type GenerateContentParameters, type GenerateContentResponse, type Part } from "@google/genai";
 import { env } from "../system/env.js";
 import { log } from "../system/logger/index.js";
 import { errorMessage } from "./errors.js";
@@ -29,6 +29,32 @@ export interface GeminiImageResult {
   message?: string;
 }
 
+// Pull the first candidate's `content.parts` array out of a Gemini
+// response, defaulting to `[]` when any layer of the optional chain is
+// absent. Pure — exported for unit tests.
+export function firstCandidateParts(response: GenerateContentResponse): readonly Part[] {
+  return response.candidates?.[0]?.content?.parts ?? [];
+}
+
+// Pull the first candidate's `finishReason` (used in debug logs).
+// Pure — exported for unit tests.
+export function firstFinishReason(response: GenerateContentResponse): string | undefined {
+  return response.candidates?.[0]?.finishReason;
+}
+
+// Reduce a Gemini response's `parts` array down to the {imageData,
+// message} pair the rest of the app cares about. Last text wins; last
+// inline-image wins. Parts without text or `inlineData.data` are
+// skipped. Pure — exported for unit tests.
+export function extractImageResult(parts: readonly Part[]): GeminiImageResult {
+  const result: GeminiImageResult = {};
+  for (const part of parts) {
+    if (part.text) result.message = part.text;
+    if (part.inlineData?.data) result.imageData = part.inlineData.data;
+  }
+  return result;
+}
+
 // Low-level wrapper around `ai.models.generateContent` that pulls
 // the first inline image and text part out of the response. Use this
 // when you need to pass custom `contents` (e.g. text + reference
@@ -48,7 +74,7 @@ export async function generateGeminiImageContent(
   const client = getGeminiClient();
   log.debug("gemini", "generateContent: request", {
     model,
-    hasConfig: !!config,
+    hasConfig: Boolean(config),
     aspectRatio: config?.imageConfig?.aspectRatio,
   });
   let response;
@@ -62,18 +88,14 @@ export async function generateGeminiImageContent(
     log.debug("gemini", "generateContent: SDK threw", { model, error: errorMessage(err) });
     throw err;
   }
-  const parts = response.candidates?.[0]?.content?.parts ?? [];
-  const result: GeminiImageResult = {};
-  for (const part of parts) {
-    if (part.text) result.message = part.text;
-    if (part.inlineData?.data) result.imageData = part.inlineData.data;
-  }
+  const parts = firstCandidateParts(response);
+  const result = extractImageResult(parts);
   log.debug("gemini", "generateContent: response", {
     model,
     parts: parts.length,
-    hasImage: !!result.imageData,
-    hasText: !!result.message,
-    finishReason: response.candidates?.[0]?.finishReason,
+    hasImage: Boolean(result.imageData),
+    hasText: Boolean(result.message),
+    finishReason: firstFinishReason(response),
   });
   return result;
 }

package/server/utils/html/htmlArtifactSplicer.ts

@@ -0,0 +1,41 @@
+// Read an HTML artifact file under the `/artifacts/html` static
+// mount and splice two helper scripts before its closing `</body>`:
+//   1. The image-self-repair script (#1011 Stage E / #1025) — restores
+//      the behavior that PR #980 unhooked when presentHtml / Files
+//      HTML preview moved off `srcdoc` onto the static mount.
+//   2. The iframe height reporter (#1219 follow-up) — lets the parent
+//      StackView size the iframe to its rendered content despite the
+//      `sandbox="allow-scripts"` cross-origin barrier.
+//
+// Both scripts are pure string injections of trusted server code; the
+// helpers are pure functions and order doesn't matter (one-shot scripts
+// that observe their own document state).
+//
+// Lives in its own module — not inline in `server/index.ts` — so unit
+// tests can import the helpers without dragging the entire server
+// startup as an import side effect.
+
+import { readFile as fsReadFile } from "fs/promises";
+import { resolveWithinRoot } from "../files/safe.js";
+import { injectImageRepairScript } from "../../../src/utils/image/imageRepairInlineScript.js";
+import { injectHeightReporterScript } from "../../../src/utils/html/iframeHeightReporterScript.js";
+
+/** Read an HTML artifact file (under `htmlsRoot`) and splice the
+ *  image-self-repair script before its closing `</body>`. Returns
+ *  the spliced HTML on success, `null` when the file can't be
+ *  resolved (escapes the root) or read (missing / unreadable).
+ *
+ *  `htmlsRoot` MUST already be a realpath — `resolveWithinRoot`
+ *  compares against it strictly. The middleware in `server/index.ts`
+ *  passes the cached `getHtmlsDirReal()` result, which is a realpath. */
+export async function readAndInjectHtmlArtifact(htmlsRoot: string, relPath: string): Promise<string | null> {
+  const abs = resolveWithinRoot(htmlsRoot, relPath);
+  if (!abs) return null;
+  let raw: string;
+  try {
+    raw = await fsReadFile(abs, "utf8");
+  } catch {
+    return null;
+  }
+  return injectHeightReporterScript(injectImageRepairScript(raw));
+}

package/server/utils/markdown/frontmatter.ts

@@ -0,0 +1,112 @@
+// Server-side mirror of `src/utils/markdown/frontmatter.ts`
+// (#895 PR B). The two share the same shape on purpose so the
+// parser/serializer/merger contract is identical on both sides
+// — what writeWikiPage emits round-trips losslessly through the
+// Vue useMarkdownDoc composable.
+//
+// Code is intentionally NOT a shared package: the wrapper is ~10
+// lines on each side, and a workspace package would need cross-
+// build wiring (browser bundle for Vue, plain Node for server)
+// that's not worth it for so little glue. js-yaml does the heavy
+// lifting in both places, identically.
+
+import yaml from "js-yaml";
+
+export interface ParsedMarkdown {
+  /** Parsed YAML object. Empty `{}` when the document has no
+   *  frontmatter or the YAML failed to parse. Insertion order
+   *  matches the source so callers iterating `Object.entries`
+   *  see fields in the order the file declared them. */
+  meta: Record<string, unknown>;
+  /** Body after stripping the frontmatter envelope. The trailing
+   *  newline of the closing `---` line is consumed; a no-frontmatter
+   *  document returns the raw input verbatim. */
+  body: string;
+  /** True iff a well-formed `---\n...\n---\n` envelope was
+   *  detected and parsed. Malformed YAML inside an envelope
+   *  degrades to `hasHeader: false` so a typo in the header
+   *  doesn't break writes. */
+  hasHeader: boolean;
+}
+
+const FRONTMATTER_OPEN = /^---\r?\n/;
+// `(?:^|\r?\n)` lets the closing fence sit at the very start of
+// `afterOpen` — needed for empty envelopes (`---\n---\n`) where
+// the closing `---` is the first thing after the open is stripped.
+const FRONTMATTER_CLOSE = /(?:^|\r?\n)---\s*(?:\r?\n|$)/;
+
+/** Parse a markdown document, splitting frontmatter from body.
+ *  Always returns an object — never throws. */
+export function parseFrontmatter(raw: string): ParsedMarkdown {
+  if (!FRONTMATTER_OPEN.test(raw)) {
+    return { meta: {}, body: raw, hasHeader: false };
+  }
+  const afterOpen = raw.replace(FRONTMATTER_OPEN, "");
+  const closeMatch = FRONTMATTER_CLOSE.exec(afterOpen);
+  if (!closeMatch || closeMatch.index === undefined) {
+    return { meta: {}, body: raw, hasHeader: false };
+  }
+  const yamlText = afterOpen.slice(0, closeMatch.index);
+  const body = afterOpen.slice(closeMatch.index + closeMatch[0].length);
+  const meta = safeYamlLoad(yamlText);
+  if (meta === null) {
+    return { meta: {}, body: raw, hasHeader: false };
+  }
+  return { meta, body, hasHeader: true };
+}
+
+/** Serialize a meta object + body back into the canonical
+ *  `---\n...\n---\n\nbody` shape. An empty `meta` returns the body
+ *  alone (no envelope) — the lazy-on-write contract: don't add
+ *  ceremony to documents that don't have anything to record.
+ *
+ *  Round-trip semantics: VALUE-preserving, NOT byte-preserving.
+ *  `js-yaml` adds quotes to ambiguous scalars (`'1.20'`, `'true'`)
+ *  so they parse back as the same string under FAILSAFE_SCHEMA.
+ *  Source-text formatting may change on save but the parsed value
+ *  is stable across rounds. */
+export function serializeWithFrontmatter(meta: Record<string, unknown>, body: string): string {
+  if (Object.keys(meta).length === 0) return body;
+  // `lineWidth: -1` disables auto-wrap so long URLs / titles stay on
+  // one line. `noRefs: true` avoids YAML anchor syntax (`&id001`)
+  // which is technically valid but visually noisy in plain-text
+  // markdown.
+  const yamlText = yaml.dump(meta, { lineWidth: -1, noRefs: true }).trimEnd();
+  return `---\n${yamlText}\n---\n\n${body}`;
+}
+
+/** Merge a patch into an existing meta object. Unknown keys in
+ *  `existing` are preserved verbatim; keys present in `patch`
+ *  overwrite. A `null` or `undefined` patch value DELETES the key
+ *  (REST PATCH semantics) — callers that want "leave alone"
+ *  should omit the key entirely. */
+export function mergeFrontmatter(existing: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...existing };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null || value === undefined) {
+      Reflect.deleteProperty(out, key);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function safeYamlLoad(text: string): Record<string, unknown> | null {
+  try {
+    // `FAILSAFE_SCHEMA` keeps every scalar as a string and skips
+    // type coercion. Two motivating cases:
+    //   - YAML 1.1 dates (`created: 2026-04-27`) would become a
+    //     `Date` object under DEFAULT_SCHEMA, breaking round-trip.
+    //   - Numeric-looking strings (`version: 1.20` → 1.2 under
+    //     JSON_SCHEMA) drop trailing zeros on save.
+    // For the wiki-history use case — title / created / updated /
+    // tags / editor — every value that should be a string IS one.
+    const loaded = yaml.load(text, { schema: yaml.FAILSAFE_SCHEMA });
+    if (loaded === null || loaded === undefined) return {};
+    if (typeof loaded !== "object" || Array.isArray(loaded)) return null;
+    return loaded as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}

package/server/utils/regex.ts

@@ -0,0 +1,56 @@
+// Central audit point for server-side regular expressions.
+//
+// Why one file? `eslint-plugin-security`'s `detect-unsafe-regex` rule
+// fires on any regex with a non-trivial nested-quantifier shape, even
+// when surrounding analysis shows the pattern is bounded. Rather than
+// scatter `eslint-disable-next-line` annotations across the server
+// tree, every server regex that the rule flagged lives here with its
+// ReDoS-safety rationale spelled out — security reviews start at this
+// file.
+//
+// Browser-side regexes (`src/utils/format/jsonSyntax.ts`,
+// `src/utils/markdown/taskList.ts`) stay in their consumer files
+// because moving them would force the frontend to import from
+// `server/`. A symmetric `src/utils/regex.ts` could be added later;
+// kept out of scope here so this file has only one architectural
+// layer.
+
+// ── Slug validator ────────────────────────────────────────────────
+//
+// Used by `server/utils/slug.ts#isValidSlug` and (transitively)
+// every domain that slugifies user input — todos, wiki, sources,
+// skills. Linear in input length; `[a-z0-9-]*` and `[a-z0-9]` don't
+// share characters with each other or with the boundary `^` / `$`,
+// so the optional capture group can't drive backtracking. Caller
+// length-caps input at `DEFAULT_MAX_LENGTH` (120 chars) BEFORE
+// invoking the regex, so worst-case is ~120 character comparisons.
+//
+// eslint-disable-next-line security/detect-unsafe-regex -- bounded slug validator (length-capped by caller; no nested-quantifier overlap)
+export const SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+
+// ── Wiki bullet-link parsers ──────────────────────────────────────
+//
+// Used by `server/api/routes/wiki.ts` to parse top-of-page index
+// bullets like:
+//   - [Title](path/to/page.md) — optional summary
+//   - [[wiki-style title]] — optional summary
+// Each `[^x]+` runs over a fixed exclusion set with a hard delimiter
+// (`]`, `)`); the optional summary group's `(.*)` is a single greedy
+// run, no nested overlap. Linear in line length.
+//
+// eslint-disable-next-line security/detect-unsafe-regex -- bullet-link parser; bounded captures with hard delimiters
+export const BULLET_LINK_PATTERN = /^[-*]\s+\[([^\]]+)\]\(([^)]*)\)(?:\s*[—–-]\s*(.*))?/;
+// eslint-disable-next-line security/detect-unsafe-regex -- same shape as BULLET_LINK_PATTERN
+export const BULLET_WIKI_LINK_PATTERN = /^[-*]\s+\[\[([^\]]+)\]\](?:\s*[—–-]\s*(.*))?/;
+
+// ── Skills body blank-line stripper ───────────────────────────────
+//
+// Used by `server/workspace/skills/parser.ts` to drop leading blank
+// lines from a skill's body after stripping the frontmatter. `\s*\n`
+// consumes one line at a time with optional leading whitespace; the
+// outer `+` repeats over distinct lines (each iteration MUST consume
+// at least the trailing `\n`), so no overlap → linear in input
+// length.
+//
+// eslint-disable-next-line security/detect-unsafe-regex -- linear blank-line stripper, no nested-quantifier overlap
+export const LEADING_BLANK_LINES_PATTERN = /^(?:\s*\n)+/;

package/server/utils/router.ts

@@ -0,0 +1,41 @@
+// Tiny adapter for registering Express routes from a `ResolvedRoute`
+// `{ method, url }` tuple — the shape host aggregators emit for every
+// plugin-owned route. Lets route files spell the registration as
+// `bindRoute(router, API_ROUTES.todos.itemsCreate, handler)` instead
+// of branching on the verb at the call site.
+//
+// Handler typing matches Express's own loose `RouteParameters`
+// inference: a handler typed as `(req: Request<{ id: string }>, res:
+// Response) => void` is forwarded as-is — the underlying
+// `router[method](url, handler)` call accepts any handler shape, so
+// we cast through `unknown` once here rather than at every site.
+
+import type { IRouter, RequestHandler } from "express";
+import type { ResolvedRoute } from "../../src/plugins/meta-types.js";
+
+/** Register `handler` on `router` using the verb + URL declared by
+ *  `route`. The generic on `handler` lets callers pass an Express
+ *  handler typed against their own `params` / `body` / `query`
+ *  generics; the cast hides the variance from Express's
+ *  `RequestHandler<ParamsDictionary, …>` default. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function bindRoute<H extends (...args: any[]) => unknown>(router: IRouter, route: ResolvedRoute, ...handlers: H[]): void {
+  const cast = handlers as unknown as RequestHandler[];
+  switch (route.method) {
+    case "GET":
+      router.get(route.url, ...cast);
+      break;
+    case "POST":
+      router.post(route.url, ...cast);
+      break;
+    case "PUT":
+      router.put(route.url, ...cast);
+      break;
+    case "PATCH":
+      router.patch(route.url, ...cast);
+      break;
+    case "DELETE":
+      router.delete(route.url, ...cast);
+      break;
+  }
+}

package/server/utils/slug.ts

@@ -1,4 +1,5 @@
 import { createHash } from "crypto";
+import { SLUG_PATTERN } from "./regex.js";
 
 // Bits of sha256 kept as the non-ASCII fallback id. 16 base64url chars =
 // 96 bits; birthday-collision expectation lives at ~2^48 entries, so
@@ -37,7 +38,8 @@ export function hashSlug(input: string, length: number = NON_ASCII_HASH_LEN): st
 export function isValidSlug(slug: string): boolean {
   if (typeof slug !== "string") return false;
   if (slug.length === 0 || slug.length > DEFAULT_MAX_LENGTH) return false;
-  if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(slug)) return false;
+  // Pattern + ReDoS-safety rationale lives in `server/utils/regex.ts`.
+  if (!SLUG_PATTERN.test(slug)) return false;
   if (slug.includes("--")) return false;
   return true;
 }
@@ -104,8 +106,8 @@ export function disambiguateSlug(base: string, existingIds: ReadonlySet<string>)
 }
 
 function hasNonHyphenChar(input: string): boolean {
-  for (let i = 0; i < input.length; i++) {
-    if (input[i] !== "-") return true;
+  for (const char of input) {
+    if (char !== "-") return true;
   }
   return false;
 }

package/server/utils/time.ts

@@ -24,6 +24,18 @@ export const TIME_UNIT_MS: Record<string, number> = {
 /** Quick subprocess probe (docker ps, libreoffice --version, etc.) */
 export const SUBPROCESS_PROBE_TIMEOUT_MS = 5 * ONE_SECOND_MS;
 
+/** Debounce window for dev-plugin `dist/` watcher (#1159 PR3). Vite
+ *  writes 4-5 files within ~100ms on a single rebuild; 300ms collapses
+ *  the burst into one publish. */
+export const DEV_PLUGIN_WATCH_DEBOUNCE_MS = 300;
+
+/** Hard cap on how long the startup-failure path waits for
+ *  `httpServer.close()` to drain in-flight connections before
+ *  forcing `process.exit(1)`. SSE streams + WebSocket upgrades hold
+ *  connections open indefinitely, so the graceful close alone isn't
+ *  a fail-fast guarantee. */
+export const STARTUP_FAILURE_FORCE_EXIT_MS = 5 * ONE_SECOND_MS;
+
 /** Heavy subprocess work (libreoffice conversion, etc.) */
 export const SUBPROCESS_WORK_TIMEOUT_MS = ONE_MINUTE_MS;
 

package/server/workspace/chat-index/indexer.ts

@@ -8,7 +8,7 @@
 // at a `mkdtempSync` directory without touching the real
 // ~/mulmoclaude.
 
-import { readdir, readFile } from "node:fs/promises";
+import { readdir, readFile, rm } from "node:fs/promises";
 import { defaultSummarize, loadJsonlInput, type SummarizeFn } from "./summarizer.js";
 import { chatDirFor, indexEntryPathFor, manifestPathFor, sessionJsonlPathFor, sessionMetaPathFor } from "./paths.js";
 import type { ChatIndexEntry, ChatIndexManifest } from "./types.js";
@@ -104,6 +104,19 @@ export async function updateManifest(workspaceRoot: string, mutator: (m: ChatInd
   });
 }
 
+// Drop a session's entry from both the per-session index file and
+// the shared manifest. Used by the sessions hard-delete route so AI
+// title / summary / keywords don't outlive the underlying jsonl on
+// disk. Both removals tolerate "missing" — sessions that were never
+// indexed have no entry to prune.
+export async function removeSessionFromIndex(workspaceRoot: string, sessionId: string): Promise<void> {
+  await rm(indexEntryPathFor(workspaceRoot, sessionId), { force: true });
+  await updateManifest(workspaceRoot, (manifest) => ({
+    ...manifest,
+    entries: manifest.entries.filter((entry) => entry.id !== sessionId),
+  }));
+}
+
 // --- freshness check ------------------------------------------------
 
 // A session is "fresh" when its per-session index file exists and
@@ -115,7 +128,7 @@ export async function isFresh(workspaceRoot: string, sessionId: string, now: num
     const raw = await readFile(indexEntryPathFor(workspaceRoot, sessionId), "utf-8");
     const entry: unknown = JSON.parse(raw);
     if (!isRecord(entry)) return false;
-    const indexedAt = (entry as Record<string, unknown>).indexedAt;
+    const { indexedAt } = entry as Record<string, unknown>;
     if (typeof indexedAt !== "string") return false;
     const indexedTimestamp = Date.parse(indexedAt);
     if (Number.isNaN(indexedTimestamp)) return false;

package/server/workspace/chat-index/summarizer.ts

@@ -86,7 +86,7 @@ export function extractText(jsonlContent: string): string {
     } catch {
       continue;
     }
-    const source = entry.source;
+    const { source } = entry;
     if ((source === "user" || source === "assistant") && entry.type === EVENT_TYPES.text && typeof entry.message === "string") {
       parts.push(`[${source}] ${trimMessage(entry.message)}`);
     }

package/server/workspace/custom-dirs.ts

@@ -64,7 +64,7 @@ function validatePath(rawPath: string): string | null {
   if (path.isAbsolute(normalized)) return null;
 
   // Not a reserved system directory
-  if (RESERVED_DIRS.some((reservedDir) => normalized === reservedDir || normalized.startsWith(reservedDir + "/"))) {
+  if (RESERVED_DIRS.some((reservedDir) => normalized === reservedDir || normalized.startsWith(`${reservedDir}/`))) {
     return null;
   }
 

package/server/workspace/helps/gemini.md

@@ -9,7 +9,7 @@ A single key unlocks all three capabilities (images, TTS audio, video) — you d
 ### Images
 
 - **`generateImage`** — creates images from text prompts. The heart of the **Artist** role.
-- **`editImage`** — transforms or restyles an existing image ("convert to Ghibli style", "remove the background", "add a sunset"). Also **Artist**.
+- **`editImages`** — transforms, restyles, or combines up to 8 existing images per call ("convert to Ghibli style", "remove the background", "merge these two photos into one"). Also **Artist**.
 - **Inline document images** — roles that produce rich documents (**Guide & Planner**, **Tutor**, Recipe Guide, Trip Planner, …) embed generated images directly into the page via `presentDocument`. Without a key, those image slots fall back to italic "🖼️ Image: <prompt>" text markers — the prompt is preserved, but no picture renders.
 - **MulmoScript image beats** — `presentMulmoScript` uses Gemini image models for `imagePrompt` beats. **Storyteller Plus** additionally uses them for consistent-character scenes across a storyboard.
 

package/server/workspace/helps/guide.md

@@ -0,0 +1,61 @@
+# Guide & Planner Templates
+
+Reference templates for the Guide & Planner role. Use these structures when authoring documents with `presentDocument` for any of the supported guide types.
+
+## Document Conventions (all types)
+
+Every guide should:
+
+- **Overview**: open with a summary of the key parameters (servings, days, level, budget, etc.)
+- **Numbered steps OR structured sections**: use one or the other consistently across the document
+- **Anchors**: add `<a id="step-1"></a>` (or `step-N`, `day-N`, `section-name`) to each major heading for `scrollToAnchor` navigation
+- **Images**: embed via `![Detailed image prompt](__too_be_replaced_image_path__)` — make the alt-text prompt specific enough to generate a useful illustration on its own
+- **Close**: end with tips, variations, troubleshooting, or follow-up recommendations
+- **Tone**: warm and encouraging; adapt vocabulary to the user's stated experience level
+
+## Form-First Workflow
+
+Always call `presentForm` before producing the document. Tailor fields to the request type:
+
+- **Recipe**: servings, dietary restrictions, skill level, available time, equipment
+- **Travel**: destination, dates, traveler count, interests, budget tier, accommodation type
+- **Fitness**: goal (weight loss / strength / endurance), starting level, days per week, equipment access
+- **Event**: occasion, guest count, budget, venue type, dietary needs
+- **Study guide**: topic, current level, time available, learning goal
+- **DIY / home project**: project type, skill level, tools available, budget
+
+Pre-fill any field the user already provided via `defaultValue`. Mark fields the user must answer as `required: true`. Keep forms concise — ask only for what is needed to produce a great result.
+
+## Per-Type Document Structures
+
+### Recipe
+
+overview → ingredients (scaled to the chosen servings) → equipment → prep work → numbered cooking steps (each with an image) → chef's tips → storage notes
+
+### Travel
+
+overview → day-by-day itinerary (morning / afternoon / evening) → accommodation & dining → transport between stops → budget breakdown → packing tips → local culture tips
+
+### Fitness
+
+overview → weekly schedule → per-workout breakdown (warm-up, main exercises with sets / reps / form notes, cool-down) → progression plan over weeks → nutrition tips
+
+### Event
+
+overview → timeline & checklist (T-minus weeks) → venue & catering → guest list & invitations → décor & entertainment → budget tracker
+
+### Study Guide
+
+overview → topic breakdown → key concepts per section → worked examples → practice questions → resources & references
+
+### DIY / Home Project
+
+overview → required tools & materials → safety notes → numbered steps (each with an image) → finishing & cleanup → maintenance & care
+
+## Follow-up Pattern
+
+After presenting the document:
+
+- Offer to read any step aloud (scroll to it first with `scrollToAnchor`, then narrate the step)
+- Invite follow-up questions
+- Offer to adjust the plan based on feedback (regenerate the form, add steps, change scope)

package/server/workspace/helps/index.md

@@ -15,6 +15,7 @@ Under the hood it uses the Claude Code Agent SDK as its LLM core. Claude has ful
 - **Tutor** — Assesses your knowledge level, then teaches any topic with structured documents and visuals.
 - **Storyteller** — Crafts illustrated narrative stories as a MulmoScript storyboard.
 - **Storyteller Plus** — Like Storyteller, with consistent character images across beats.
+- **Settings** — Manages information sources, skills, and scheduled automations for the workspace.
 - *(Additional roles may be defined by the user in the workspace.)*
 
 ## Key Capabilities
@@ -42,7 +43,10 @@ See [Wiki](helps/wiki.md) for details on how it works.
 - [Gemini API Key](helps/gemini.md) — why `GEMINI_API_KEY` is strongly recommended (images, audio, video) and how to get one from Google AI Studio
 - [MulmoScript](helps/mulmoscript.md) — format reference for authoring multimedia stories: beats, image types, speech, audio, and a minimal example
 - [Business Presentation Template](helps/business.md) — MulmoScript template and rules for business presentations in the Office role
+- [Storyteller Template](helps/storyteller.md) — MulmoScript template and rules for character-driven narrated stories in the Storyteller role
+- [Guide & Planner Templates](helps/guide.md) — document structures and form-field hints per guide type for the Guide & Planner role
 - [Spreadsheet](helps/spreadsheet.md) — cell format, formulas, date handling, and format codes for the presentSpreadsheet plugin
+- [presentHtml](helps/presenthtml.md) — self-contained HTML rules and the three-`../` relative-path convention used by the presentHtml plugin to keep generated files portable under `file://`
 - [Sandbox](helps/sandbox.md) — how the Docker sandbox isolates the agent, what it can access, and how to disable it
 - [Telegram Bridge](helps/telegram.md) — how to talk to MulmoClaude from the Telegram app: creating a bot, starting the bridge, allowlisting chat IDs, commands, and troubleshooting
 - [Information Sources](helps/sources.md) — registering RSS feeds / GitHub repos / arXiv queries, the daily-brief pipeline, and where its files live on disk

package/server/workspace/helps/presenthtml.md

@@ -0,0 +1,80 @@
+# presentHtml — Authoring Guide
+
+Reference for the `presentHtml` plugin. The HTML you provide is saved to `artifacts/html/<YYYY>/<MM>/<slug>-<timestamp>.html` and rendered in the canvas. The user may also open the file directly from disk via `file://`, so it must remain portable: every URL inside the document has to resolve both when served by the app and when loaded straight off the filesystem.
+
+## Self-Contained Document
+
+- Full document including `<!DOCTYPE html>` and `<html>` / `<body>` tags.
+- All CSS and JavaScript inline, or loaded via a public CDN. No local script / stylesheet files (the app does not host arbitrary `.css` / `.js`).
+
+### Allowed CDNs
+
+The preview iframe enforces a CSP that only permits a curated set of CDNs. **Use these origins or your script / stylesheet will be silently blocked** and the page will render broken (e.g. `Plotly is not defined` if the chart library was blocked):
+
+- `https://cdn.jsdelivr.net` — broadest coverage; preferred for any npm-shaped library
+- `https://unpkg.com` — same scope as jsdelivr; fallback
+- `https://cdnjs.cloudflare.com` — curated mirror; common for older libraries
+- `https://fonts.googleapis.com` + `https://fonts.gstatic.com` — Google Fonts
+- `https://cdn.plot.ly` — Plotly's first-party CDN (also reachable via jsdelivr)
+
+When in doubt, pull from `cdn.jsdelivr.net` — it mirrors most npm packages and is always safe. Examples:
+
+```html
+<!-- Plotly via jsdelivr (preferred) -->
+<script src="https://cdn.jsdelivr.net/npm/plotly.js-dist@2/plotly.min.js"></script>
+
+<!-- D3 -->
+<script src="https://cdn.jsdelivr.net/npm/d3@7/dist/d3.min.js"></script>
+
+<!-- Tailwind (browser play CDN) -->
+<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
+```
+
+If a library you need is hosted only on a CDN not in this list (e.g. `cdn.example.org`), inline the library code directly — do not link to an unlisted host.
+
+## Referencing Workspace Files
+
+The output HTML lives three directory levels deep under `artifacts/`. To reference an image / chart / other artifact, use a **relative path with exactly three `../`** to climb out of `html/<YYYY>/<MM>/`:
+
+```html
+<!-- GOOD -->
+<img src="../../../images/2026/04/foo.png">
+
+<!-- BAD: absolute path breaks under file:// -->
+<img src="/artifacts/images/2026/04/foo.png">
+
+<!-- BAD: workspace-rooted path resolves against the page URL -->
+<img src="artifacts/images/2026/04/foo.png">
+
+<!-- BAD: runtime artifact, not a stored convention -->
+<img src="/api/files/raw?path=artifacts/images/2026/04/foo.png">
+```
+
+Workspace paths returned by other tools (e.g. an image-generating tool returns `artifacts/images/2026/04/foo.png`): replace the leading `artifacts/` with `../../../`, giving `../../../images/2026/04/foo.png`.
+
+The same rule applies to anywhere a path appears: `<img>`, `<source>`, `<video poster>`, `<audio src>`, CSS `url(...)`, etc.
+
+## Local Images Not Already Under `artifacts/`
+
+If you want to embed a local image that lives **outside** `artifacts/` — e.g. a file the user pasted into `data/attachments/2026/04/foo.png`, a wiki source under `data/wiki/sources/foo.png`, or any other workspace path — **do not link to it directly**. The three-`../` math only resolves cleanly for files under `artifacts/`; references that climb further or sideways break under `file://` and are fragile across workspace reorganisation.
+
+Copy the file into `artifacts/images/<YYYY>/<MM>/` first, then reference the copy. Use `mkdir -p` for the partition directory and a UTC year/month matching the convention (`saveImage()` shards by UTC, so doing the same keeps copies grouped with same-month generated images):
+
+```bash
+mkdir -p artifacts/images/2026/04
+cp data/attachments/2026/04/foo.png artifacts/images/2026/04/foo.png
+```
+
+Then in the HTML:
+
+```html
+<img src="../../../images/2026/04/foo.png">
+```
+
+Files **already** under `artifacts/` (e.g. `artifacts/images/2026/03/bar.png`, `artifacts/charts/2026/04/baz.svg`) — reference them in place; do **not** copy.
+
+## Why Three `../`
+
+The file is saved at `artifacts/html/<YYYY>/<MM>/<slug>-<timestamp>.html`. From that location, `../../../` climbs out of `<MM>/`, `<YYYY>/`, and `html/` to land in `artifacts/`. From `artifacts/`, the next path segment is the sibling artifact directory you want — `images/`, `charts/`, `documents/`, etc.
+
+Absolute paths like `/artifacts/...` work in-app (the server mounts `/artifacts/images` as a static route) but break under `file://`, where root-relative URLs resolve against the filesystem root. Workspace-rooted paths without a leading slash (`artifacts/...`) get joined to the page URL by the browser and 404 every time.

package/server/workspace/helps/sandbox.md

@@ -25,6 +25,13 @@ The container runs with `--cap-drop ALL` and as the host user's UID/GID, so it h
 
 Set the environment variable `DISABLE_SANDBOX=1` to always run the agent directly on the host, even when Docker is available.
 
+## Debug aids (opt-in env vars)
+
+These flags exist for development / debugging only. Off by default so production runs aren't surprised.
+
+- `DISABLE_SANDBOX=1` — see above. Bypasses the Docker sandbox.
+- `PERSIST_TOOL_CALLS=1` — also persist `tool_call` events to the session jsonl alongside `tool_result`. Useful for reading the args sent to a tool after the run is over (page refresh / server restart). Off by default because args can be large and may carry payload bytes (inline images, full MulmoScript JSON) you didn't expect to land in the jsonl. See [issue #1096](https://github.com/receptron/mulmoclaude/issues/1096) for the rationale.
+
 ## Host Credentials (opt-in)
 
 The sandbox is credential-free by default. Two opt-in flags let you expose the minimum needed for `git` / `gh` to authenticate without leaking private keys into the container: