mulmoclaude 0.3.0 → 0.5.0

package/server/utils/gitignore.ts

@@ -15,24 +15,24 @@
 // the workspace scale (~hundreds of dirs) this is negligible. If
 // profiling shows otherwise, cache the parsed ignore instances.
 
-import fs from "fs";
+import { readFileSync } from "fs";
 import path from "path";
 import ignore, { type Ignore } from "ignore";
 
 export class GitignoreFilter {
-  private ig: Ignore;
+  private rules: Ignore;
 
   constructor(rules?: string) {
-    this.ig = ignore();
+    this.rules = ignore();
     if (rules) {
-      this.ig.add(rules);
+      this.rules.add(rules);
     }
   }
 
   /** Test whether a workspace-relative path should be hidden. */
   ignores(relPath: string): boolean {
     if (!relPath) return false;
-    return this.ig.ignores(relPath);
+    return this.rules.ignores(relPath);
   }
 
   /** Create a child filter that inherits this filter's rules and
@@ -40,12 +40,12 @@ export class GitignoreFilter {
   childForDir(dirAbsPath: string): GitignoreFilter {
     const child = new GitignoreFilter();
     // Inherit parent rules
-    child.ig = ignore().add(this.ig);
+    child.rules = ignore().add(this.rules);
     // Add local .gitignore if present
     const gitignorePath = path.join(dirAbsPath, ".gitignore");
     try {
-      const content = fs.readFileSync(gitignorePath, "utf-8");
-      child.ig.add(content);
+      const content = readFileSync(gitignorePath, "utf-8");
+      child.rules.add(content);
     } catch {
       // No .gitignore in this directory — just inherit parent
     }
@@ -61,7 +61,7 @@ export class GitignoreFilter {
 export function createRootFilter(workspaceRoot: string): GitignoreFilter {
   const gitignorePath = path.join(workspaceRoot, ".gitignore");
   try {
-    const content = fs.readFileSync(gitignorePath, "utf-8");
+    const content = readFileSync(gitignorePath, "utf-8");
     return new GitignoreFilter(content);
   } catch {
     return new GitignoreFilter();

package/server/utils/id.ts

@@ -1,16 +1,48 @@
-// Unique-ID generation for persisted records. Previously duplicated
-// in schedulerHandlers, todosHandlers, and todosItemsHandlers —
-// consolidated here as part of the server/utils grouping (#350 CLAUDE.md).
+// Unique-ID generation helpers. Three layers, one primitive
+// (`crypto.randomUUID()`). See issue #723 for the design rationale.
 
-import { randomBytes } from "crypto";
+import { randomUUID } from "crypto";
+
+// 16-char hex slug length for `shortId()`. 64 bits of entropy —
+// ~10^9 generations before a 1% collision rate — which is plenty
+// for filename suffixes.
+const SHORT_ID_HEX_LEN = 16;
+// 6 hex chars for `makeId()`'s random tail — the timestamp already
+// carries most of the uniqueness, so 24 bits of extra entropy is
+// enough to disambiguate IDs generated in the same millisecond.
+const MAKE_ID_HEX_LEN = 6;
+
+/**
+ * Full UUID v4 (36 chars, hyphenated).
+ *
+ * Use when the id is globally unique across the app lifetime and
+ * round-trips through URLs, jsonl files, or external systems that
+ * already expect the v4 shape (e.g. `chatSessionId`, scheduler
+ * `task.id`, notification ids).
+ */
+export function makeUuid(): string {
+  return randomUUID();
+}
+
+/**
+ * 16-char hex slug derived from a UUID v4.
+ *
+ * Use when a short, opaque identifier is sufficient — e.g. image
+ * and spreadsheet file-name suffixes. Not suitable for IDs that
+ * round-trip through systems expecting UUID v4 formatting.
+ */
+export function shortId(): string {
+  return randomUUID().replace(/-/g, "").slice(0, SHORT_ID_HEX_LEN);
+}
 
 /**
- * Generate a short, unique, human-scannable ID.
+ * Domain-prefixed, human-scannable ID.
  *
  * Format: `<prefix>_<epochMs>_<6 random hex chars>`. The prefix
- * is required so IDs from different domains (todo, scheduler, column)
- * are visually distinguishable in logs and JSON files.
+ * makes IDs from different domains (todo, scheduler, column)
+ * visually distinguishable in logs and JSON files.
  */
 export function makeId(prefix: string): string {
-  return `${prefix}_${Date.now()}_${randomBytes(3).toString("hex")}`;
+  const randomHex = randomUUID().replace(/-/g, "").slice(0, MAKE_ID_HEX_LEN);
+  return `${prefix}_${Date.now()}_${randomHex}`;
 }

package/server/utils/json.ts

@@ -44,22 +44,22 @@ export function findBalancedBraceBlock(raw: string): string | null {
   let inString = false;
   let escape = false;
   for (let i = start; i < raw.length; i++) {
-    const ch = raw[i];
+    const char = raw[i];
     if (escape) {
       escape = false;
       continue;
     }
-    if (ch === "\\") {
+    if (char === "\\") {
       escape = true;
       continue;
     }
-    if (ch === '"') {
+    if (char === '"') {
       inString = !inString;
       continue;
     }
     if (inString) continue;
-    if (ch === "{") depth++;
-    if (ch === "}" && --depth === 0) return raw.slice(start, i + 1);
+    if (char === "{") depth++;
+    if (char === "}" && --depth === 0) return raw.slice(start, i + 1);
   }
   return null;
 }

package/server/utils/logBackgroundError.ts

@@ -1,4 +1,5 @@
 import { log } from "../system/logger/index.js";
+import { errorMessage } from "./errors.js";
 
 /**
  * Build a `.catch` handler for a fire-and-forget background job that
@@ -8,15 +9,23 @@ import { log } from "../system/logger/index.js";
  *
  * Usage:
  *
+ *   // Default message — good for generic background scans.
  *   maybeRunJournal({ ... }).catch(logBackgroundError("journal"));
  *
+ *   // Custom message — pass context when the failure mode is
+ *   // worth surfacing distinctly (e.g. "failed to register
+ *   // scheduled skills" vs other `skills` warnings).
+ *   registerScheduledSkills(...).catch(
+ *     logBackgroundError("skills", "failed to register scheduled skills"),
+ *   );
+ *
  * The handler never rethrows — the caller's promise chain is
  * terminated cleanly so nothing propagates into the request path.
  */
-export function logBackgroundError(prefix: string): (err: unknown) => void {
+export function logBackgroundError(prefix: string, message = "unexpected error in background"): (err: unknown) => void {
   return (err) => {
-    log.warn(prefix, "unexpected error in background", {
-      error: String(err),
+    log.warn(prefix, message, {
+      error: errorMessage(err),
     });
   };
 }

package/server/utils/logPreview.ts

@@ -0,0 +1,24 @@
+// Truncating preview for log payloads.
+//
+// Logs of user-supplied freeform text (prompts, wiki bodies, search
+// queries) must never include the full body — partly to keep log
+// files small, partly to limit accidental PII / secret leakage when
+// logs are shared during debugging. 120 chars + an ellipsis is the
+// shape the image-generation logging (PR #780) settled on; this
+// module exists so other routes use the same constant rather than
+// hand-rolling their own cap.
+//
+// Usage:
+//   log.info("wiki", "page: start", { pageNamePreview: previewSnippet(pageName) });
+//
+// `null` / `undefined` → empty string, so the logger never has to
+// guard against missing input.
+
+const PREVIEW_CHAR_LIMIT = 120;
+const ELLIPSIS = "…";
+
+export function previewSnippet(input: string | null | undefined): string {
+  if (!input) return "";
+  if (input.length <= PREVIEW_CHAR_LIMIT) return input;
+  return `${input.slice(0, PREVIEW_CHAR_LIMIT)}${ELLIPSIS}`;
+}

package/server/utils/markdown.ts

@@ -68,15 +68,15 @@ export function rewriteMarkdownLinks(input: string, rewrite: (href: string) => s
  * Split a trailing `#fragment` or `?query` off a path so the caller
  * can rewrite the path portion and concatenate the suffix back.
  */
-export function splitFragmentAndQuery(s: string): {
+export function splitFragmentAndQuery(href: string): {
   pathPart: string;
   suffix: string;
 } {
-  const hashIdx = s.indexOf("#");
-  const queryIdx = s.indexOf("?");
+  const hashIdx = href.indexOf("#");
+  const queryIdx = href.indexOf("?");
   let cut = -1;
   if (hashIdx !== -1) cut = hashIdx;
   if (queryIdx !== -1 && (cut === -1 || queryIdx < cut)) cut = queryIdx;
-  if (cut === -1) return { pathPart: s, suffix: "" };
-  return { pathPart: s.slice(0, cut), suffix: s.slice(cut) };
+  if (cut === -1) return { pathPart: href, suffix: "" };
+  return { pathPart: href.slice(0, cut), suffix: href.slice(cut) };
 }

package/server/utils/port.d.mts

@@ -0,0 +1,6 @@
+// Type declarations for port.mjs. See port.mjs for rationale on why
+// the shared helper lives in plain JS.
+
+export const MAX_PORT_PROBES: number;
+export function isPortFree(port: number): Promise<boolean>;
+export function findAvailablePort(start: number): Promise<number | null>;

package/server/utils/port.mjs

@@ -0,0 +1,48 @@
+// Shared port-resolution helpers for the dev server and the npm
+// launcher (`packages/mulmoclaude/bin/mulmoclaude.js`).
+//
+// Kept as plain `.mjs` (no TypeScript) because the launcher runs
+// directly under Node — it boots BEFORE tsx is wired up, so it can't
+// import from a `.ts` file. The server-side TypeScript imports this
+// through Node's ESM resolution; `moduleResolution: "bundler"` + the
+// sibling `port.d.mts` declarations give us the type coverage without
+// turning the whole `server/` tree into mixed JS/TS.
+
+import net from "node:net";
+
+// Scan cap: 20 slots is enough to step around the occasional stale
+// server on `localhost` without spinning forever on a pathologically
+// saturated machine.
+export const MAX_PORT_PROBES = 20;
+
+/**
+ * Returns true iff binding `127.0.0.1:port` would succeed right now.
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+export function isPortFree(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+    // Probe the same interface we'll actually bind to so a port
+    // held by a different process on a different interface doesn't
+    // give us a false "free" reading.
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+/**
+ * Walk forward from `start` until we find a free port. Returns `null`
+ * if every slot in `[start, start + MAX_PORT_PROBES)` is busy.
+ * @param {number} start
+ * @returns {Promise<number | null>}
+ */
+export async function findAvailablePort(start) {
+  for (let candidate = start; candidate < start + MAX_PORT_PROBES; candidate++) {
+    if (await isPortFree(candidate)) return candidate;
+  }
+  return null;
+}

package/server/utils/promptMeta.ts

@@ -0,0 +1,32 @@
+// Fingerprint user-controlled prompt text for structured logs without
+// leaking the prompt itself.
+//
+// Image / text prompts are user input and routinely include pasted
+// URLs, emails, or even credentials. Persisting any prefix of the
+// raw prompt into structured log files (which we keep on disk and
+// rotate) is a PII / secret leak waiting to happen.
+//
+// The fingerprint pairs `length` with a 12-hex-char prefix of the
+// SHA-256 hash. 48 bits of entropy is enough to correlate retries
+// and duplicate-request bursts within a session — collision risk
+// at session-scale request volumes is negligible — without exposing
+// any content.
+//
+// Use this in every new log call that would otherwise want to print
+// a `promptPreview`. Existing call sites should migrate over time.
+
+import { createHash } from "node:crypto";
+
+const PROMPT_SHA256_PREFIX_CHARS = 12;
+
+export interface PromptMeta {
+  length: number;
+  sha256: string;
+}
+
+export function promptMeta(prompt: string): PromptMeta {
+  return {
+    length: prompt.length,
+    sha256: createHash("sha256").update(prompt).digest("hex").slice(0, PROMPT_SHA256_PREFIX_CHARS),
+  };
+}

package/server/utils/request.ts

@@ -3,11 +3,17 @@
 // Centralizes patterns that were duplicated across route handlers
 // (3+ different ways to read `req.query.session`).
 
-// Use a minimal interface so the helpers work with any Express
-// Request generic (Request<object, ...>, Request<Params, ...>, etc.)
-// without type incompatibility.
+// `query: object` so the helpers work with any Express Request
+// generic — `Request<Params, ResBody, ReqBody, Query>`. A narrow
+// `Query` generic like `{ path?: string }` isn't assignable to
+// `Record<string, unknown>` (no index signature), so we widen to
+// `object` and cast internally when reading a key.
 interface HasQuery {
-  query: Record<string, unknown>;
+  query: object;
+}
+
+function readQueryKey(queryObj: object, key: string): unknown {
+  return (queryObj as Record<string, unknown>)[key];
 }
 
 /**
@@ -15,7 +21,7 @@ interface HasQuery {
  * Returns the string value, or "" if missing/non-string.
  */
 export function getSessionQuery(req: HasQuery): string {
-  const raw = req.query.session;
+  const raw = readQueryKey(req.query, "session");
   return typeof raw === "string" ? raw : "";
 }
 
@@ -24,6 +30,6 @@ export function getSessionQuery(req: HasQuery): string {
  * Returns the string value, or undefined if missing/non-string.
  */
 export function getOptionalStringQuery(req: HasQuery, key: string): string | undefined {
-  const raw = req.query[key];
+  const raw = readQueryKey(req.query, key);
   return typeof raw === "string" ? raw : undefined;
 }

package/server/utils/slug.ts

@@ -5,6 +5,19 @@ import { createHash } from "crypto";
 // collisions are effectively impossible for any realistic workspace.
 const NON_ASCII_HASH_LEN = 16;
 
+// Max slug length used by both `slugify` (output cap) and `isValidSlug`
+// (acceptance cap). 120 leaves plenty of room for filename slugs while
+// staying well under filesystem path limits and URL-segment conventions.
+// Bumped from 64 alongside the slug-rule unification (#732) so journal /
+// todo / wiki / files can all share one rule without truncating their
+// previously-longer inputs.
+//
+// Exported so callers that compose a base slug with their own suffix
+// (e.g. `${base}-2` collision avoidance) can stay inside the same cap
+// — necessary because a 120-char base + "-2" would otherwise produce a
+// 122-char id that fails `isValidSlug`.
+export const DEFAULT_MAX_LENGTH = 120;
+
 // eslint-disable-next-line no-control-regex
 const NON_ASCII_RE = /[^\x00-\x7F]/;
 
@@ -18,18 +31,18 @@ export function hashSlug(input: string, length: number = NON_ASCII_HASH_LEN): st
   return createHash("sha256").update(input, "utf-8").digest("base64url").slice(0, length);
 }
 
-// Validates a slug: lowercase alphanumeric + hyphens, 1–64 chars,
-// no leading/trailing hyphen, no consecutive hyphens. Previously
+// Validates a slug: lowercase alphanumeric + hyphens, 1–DEFAULT_MAX_LENGTH
+// chars, no leading/trailing hyphen, no consecutive hyphens. Previously
 // duplicated in sources/paths.ts and skills/paths.ts.
 export function isValidSlug(slug: string): boolean {
   if (typeof slug !== "string") return false;
-  if (slug.length === 0 || slug.length > 64) 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;
   if (slug.includes("--")) return false;
   return true;
 }
 
-export function slugify(title: string, defaultSlug = "page", maxLength = 60): string {
+export function slugify(title: string, defaultSlug = "page", maxLength = DEFAULT_MAX_LENGTH): string {
   const asciiSlug = title
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
@@ -48,3 +61,51 @@ export function slugify(title: string, defaultSlug = "page", maxLength = 60): st
   }
   return hash;
 }
+
+// Disambiguate `base` against `existingIds` by appending `-2`, `-3`, …
+// until a free id is found. Truncates `base` (stripping any trailing
+// hyphen so the join never produces `--`) so the composite stays
+// within `DEFAULT_MAX_LENGTH` — required because a 120-char base + "-2"
+// would otherwise produce a 122-char id that fails `isValidSlug`.
+//
+// Shared between server (`todosColumnsHandlers#uniqueId`) and the
+// Playwright mock (`e2e/tests/todo-columns.spec.ts`) so the e2e
+// dispatcher mirrors server behavior at the truncation boundary.
+//
+// Precondition: `base` must already be a canonical slug — typically
+// the output of `slugify`. Concretely: lowercase ASCII alnum +
+// hyphens, no leading/trailing hyphen, no `--`, length within
+// `DEFAULT_MAX_LENGTH`. Inputs outside that grammar (e.g. uppercase,
+// punctuation, leading hyphen) get NO defensive treatment — if they
+// collide they will be disambiguated to an equally-invalid suffix
+// form. The helper only special-cases empty/all-hyphen bases (where
+// no valid disambiguation exists at all) and returns them
+// unchanged so it never *fabricates* a `-2`-style invalid slug from
+// nothing. Codex iter-4/5 #732.
+export function disambiguateSlug(base: string, existingIds: ReadonlySet<string>): string {
+  if (!hasNonHyphenChar(base)) return base;
+  if (!existingIds.has(base)) return base;
+  const compose = (suffix: number): string => {
+    const tail = `-${suffix}`;
+    const room = DEFAULT_MAX_LENGTH - tail.length;
+    // Pick the cut: full base when it already fits, room-truncated
+    // otherwise. Then strip any trailing hyphen at that cut so the
+    // join never yields `--` (which `isValidSlug` rejects). Manual
+    // loop instead of a regex — `sonarjs/slow-regex` flags `-+$`
+    // even on this bounded input.
+    const cut = base.length <= room ? base.length : room;
+    let end = cut;
+    while (end > 0 && base[end - 1] === "-") end--;
+    return `${base.slice(0, end)}${tail}`;
+  };
+  let suffix = 2;
+  while (existingIds.has(compose(suffix))) suffix++;
+  return compose(suffix);
+}
+
+function hasNonHyphenChar(input: string): boolean {
+  for (let i = 0; i < input.length; i++) {
+    if (input[i] !== "-") return true;
+  }
+  return false;
+}

package/server/utils/spawn.ts

@@ -28,7 +28,7 @@ export function extractClaudeErrorMessage(stdout: string): string | null {
   if (!isRecord(parsed)) return null;
   if (parsed.is_error !== true) return null;
   if (Array.isArray(parsed.errors) && parsed.errors.length > 0) {
-    const joined = parsed.errors.filter((e): e is string => typeof e === "string").join("; ");
+    const joined = parsed.errors.filter((err): err is string => typeof err === "string").join("; ");
     if (joined.length > 0) return joined;
   }
   const subtype = typeof parsed.subtype === "string" ? parsed.subtype : "";

package/server/utils/types.ts

@@ -23,12 +23,12 @@ export function isNonEmptyString(value: unknown): value is string {
 /** Record whose values are all strings. */
 export function isStringRecord(value: unknown): value is Record<string, string> {
   if (!isRecord(value)) return false;
-  return Object.values(value).every((v) => typeof v === "string");
+  return Object.values(value).every((val) => typeof val === "string");
 }
 
 /** String array (every element is a string). */
 export function isStringArray(value: unknown): value is string[] {
-  return Array.isArray(value) && value.every((v) => typeof v === "string");
+  return Array.isArray(value) && value.every((val) => typeof val === "string");
 }
 
 /** Error-like object with a `code` property (e.g. Node.js fs errors). */

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

@@ -14,7 +14,7 @@
 // point at a `mkdtempSync` directory.
 
 import { workspacePath as defaultWorkspacePath } from "../workspace.js";
-import { ClaudeCliNotFoundError } from "../journal/archivist.js";
+import { ClaudeCliNotFoundError } from "../journal/archivist-cli.js";
 import { indexSession, listSessionIds, type IndexerDeps } from "./indexer.js";
 import { log } from "../../system/logger/index.js";
 

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

@@ -17,7 +17,7 @@ import { EVENT_TYPES } from "../../../src/types/events.js";
 import { readFile } from "node:fs/promises";
 import { formatSpawnFailure } from "../../utils/spawn.js";
 import { tmpdir } from "node:os";
-import { ClaudeCliNotFoundError } from "../journal/archivist.js";
+import { ClaudeCliNotFoundError } from "../journal/archivist-cli.js";
 import { errorMessage } from "../../utils/errors.js";
 import type { SummaryResult } from "./types.js";
 import { ONE_MINUTE_MS } from "../../utils/time.js";
@@ -152,10 +152,10 @@ export function validateSummaryResult(obj: unknown): SummaryResult {
   if (!isRecord(obj)) {
     throw new Error("[chat-index] summary result is not an object");
   }
-  const o = obj as Record<string, unknown>;
-  const title = typeof o.title === "string" ? o.title : "";
-  const summary = typeof o.summary === "string" ? o.summary : "";
-  const keywords = Array.isArray(o.keywords) ? o.keywords.filter((k): k is string => typeof k === "string") : [];
+  const record = obj as Record<string, unknown>;
+  const title = typeof record.title === "string" ? record.title : "";
+  const summary = typeof record.summary === "string" ? record.summary : "";
+  const keywords = Array.isArray(record.keywords) ? record.keywords.filter((keyword): keyword is string => typeof keyword === "string") : [];
   return { title, summary, keywords };
 }
 

package/server/workspace/custom-dirs.ts

@@ -4,7 +4,7 @@
 // directories under `data/` and `artifacts/` for organizing files.
 // Claude sees these in the system prompt and routes saves accordingly.
 
-import fs from "fs";
+import { existsSync, mkdirSync, readFileSync } from "fs";
 import path from "path";
 import { workspacePath, WORKSPACE_DIRS } from "./paths.js";
 import { log } from "../system/logger/index.js";
@@ -102,8 +102,8 @@ export function loadCustomDirs(root?: string): CustomDirEntry[] {
   const base = root ?? workspacePath;
   const filePath = path.join(base, CONFIG_FILE);
   try {
-    if (!fs.existsSync(filePath)) return [];
-    const raw = fs.readFileSync(filePath, "utf-8");
+    if (!existsSync(filePath)) return [];
+    const raw = readFileSync(filePath, "utf-8");
     const parsed: unknown = JSON.parse(raw);
     if (!Array.isArray(parsed)) {
       log.warn("custom-dirs", "workspace-dirs.json is not an array");
@@ -132,7 +132,7 @@ export function loadCustomDirs(root?: string): CustomDirEntry[] {
 export function saveCustomDirs(entries: readonly CustomDirEntry[], root?: string): void {
   const base = root ?? workspacePath;
   const filePath = path.join(base, CONFIG_FILE);
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  mkdirSync(path.dirname(filePath), { recursive: true });
   writeFileAtomicSync(filePath, JSON.stringify(entries, null, 2));
   invalidateCache();
 }
@@ -186,7 +186,7 @@ export function ensureCustomDirs(entries: readonly CustomDirEntry[], root?: stri
   const base = root ?? workspacePath;
   for (const entry of entries) {
     const dirPath = path.join(base, entry.path);
-    fs.mkdirSync(dirPath, { recursive: true });
+    mkdirSync(dirPath, { recursive: true });
   }
 }
 

package/server/workspace/helps/gemini.md

@@ -0,0 +1,57 @@
+# Gemini API Key
+
+MulmoClaude uses Google's Gemini API for image, audio, and video generation. Setting the `GEMINI_API_KEY` environment variable is **technically optional**, but we **strongly recommend** it — a large portion of MulmoClaude's visual and multimedia output depends on it.
+
+A single key unlocks all three capabilities (images, TTS audio, video) — you don't need separate credentials for each.
+
+## What the Key Unlocks
+
+### 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**.
+- **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.
+
+### Audio
+
+- **MulmoScript speech** — `presentMulmoScript` synthesizes speaker voices via Gemini TTS (`gemini-2.5-flash-preview-tts`). This is what turns a storyboard into spoken narration, so the **Storyteller** and **Storyteller Plus** roles become near-complete multimedia pieces.
+
+### Video
+
+- **MulmoScript movie beats** — beats whose `image.type` is `moviePrompt` are rendered with Google's **Veo** models (`veo-2.0-generate-001`, `veo-3.0-generate-001`, …). Without a key, movie beats can't be produced.
+
+### Bottom line
+
+Without a Gemini API key:
+
+- The **Artist** role has nothing to generate.
+- **Storyteller** and **Storyteller Plus** still produce a storyboard, but without images or narration.
+- Rich documents from **Guide & Planner**, **Tutor**, and similar roles render as text-only with placeholder markers where images should be.
+
+## How to Get a Key
+
+The Gemini API has a **free tier that is sufficient for personal use**. Higher-volume or premium-model use (e.g. Veo video) may require a paid plan.
+
+1. Open [Google AI Studio → API keys](https://aistudio.google.com/apikey) and sign in with a Google account.
+2. Click **Create API key**. If prompted, select or create a Google Cloud project (any project will do).
+3. Copy the key — it starts with `AIza…`.
+4. Open the project's `.env` file in the repository root (copy `.env.example` first if it doesn't exist yet) and add the line:
+
+   ```
+   GEMINI_API_KEY=AIza…your-key…
+   ```
+
+5. Restart MulmoClaude so the new environment variable is picked up.
+
+## Verifying It's Active
+
+The quickest check: switch to the **Artist** role and ask for _"an image of a red panda"_. If a real image appears in the canvas (instead of an italic text marker or a disabled-role hint), the key is wired up correctly.
+
+You can also inspect the server log on startup: messages like `GEMINI_API_KEY not set — image placeholders will render as text markers` indicate the key is missing or misread.
+
+## Security
+
+- The key lives in your local `.env` file. MulmoClaude never uploads it to its own servers or to Anthropic — requests go directly from your machine to Google.
+- Treat the key like a password. Anyone who sees it can make billable API calls against your Google account.
+- If you suspect a key has leaked, revoke it from [Google AI Studio → API keys](https://aistudio.google.com/apikey) and generate a new one.

package/server/workspace/helps/index.md

@@ -15,7 +15,6 @@ 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.
-- **Role Manager** — Create, edit, and delete custom roles.
 - *(Additional roles may be defined by the user in the workspace.)*
 
 ## Key Capabilities
@@ -40,11 +39,13 @@ See [Wiki](helps/wiki.md) for details on how it works.
 ## Help Pages
 
 - [Wiki](helps/wiki.md) — how the personal knowledge wiki works, its folder layout, page format, and operations
+- [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
 - [Spreadsheet](helps/spreadsheet.md) — cell format, formulas, date handling, and format codes for the presentSpreadsheet plugin
 - [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
 
 ## Workspace Layout