mulmoclaude 0.5.2 → 0.6.0

package/server/workspace/helps/storyteller.md

@@ -0,0 +1,101 @@
+# Storyteller Template (MulmoScript)
+
+Use `presentMulmoScript` to create character-driven, narrated stories. Follow this template exactly.
+
+## When to Use
+
+Reach for `presentMulmoScript` when the user asks for a story, fairy tale, narrative, or any character-driven imaginative content meant to be read aloud over visuals.
+
+## Beat Format (CRITICAL)
+
+- Every beat MUST have a top-level `imagePrompt` (string) and `imageNames` (array of character keys from `imageParams.images`).
+- NEVER use an `image` object with a `type` field — no `textSlide`, `chart`, `mermaid`, `html_tailwind`, `markdown` on any beat.
+- `imagePrompt` and `imageNames` are top-level fields on the beat, NOT nested under `image`.
+- Every beat needs both fields, even when a single character appears alone.
+
+## Image Prompts
+
+- Do NOT re-describe character appearance in `imagePrompt` — their look is already encoded in `imageParams.images`.
+- Focus the prompt on setting, action, mood, and composition.
+- Set the art style ONCE in `imageParams.style` — do NOT repeat it per beat. The style is applied globally.
+
+## Narrator Voice
+
+Set `speechOptions.instruction` on the Narrator speaker to match the story's tone. Pick a `voiceId` from this list:
+
+| Tone | Voice IDs |
+|---|---|
+| Bright / upbeat | Zephyr, Leda, Autonoe, Callirrhoe |
+| Neutral / clear | Kore, Charon, Fenrir, Orus |
+| Warm / smooth | Schedar, Sulafat, Despina, Erinome |
+| Deep / authoritative | Alnilam, Iapetus, Algieba |
+| Soft / gentle | Aoede, Umbriel, Laomedeia, Achernar, Rasalgethi, Pulcherrima, Vindemiatrix, Sadachbia, Sadaltager, Zubenelgenubi |
+
+## Other Rules
+
+- Always use Google providers (`gemini` for TTS, `google` for image generation).
+- Default transition: `fade` in `movieParams.transition`, unless the user requests a different style.
+- Keep narration text conversational and evocative, as if read aloud to a listener.
+
+## Template
+
+```json
+{
+  "$mulmocast": { "version": "1.1" },
+  "title": "The Silver Wolf and the Red-Haired Girl",
+  "description": "A girl lost in an enchanted forest befriends a wise silver wolf who shows her the way home.",
+  "lang": "en",
+  "speechParams": {
+    "speakers": {
+      "Narrator": {
+        "provider": "gemini",
+        "voiceId": "Schedar",
+        "displayName": { "en": "Narrator" },
+        "speechOptions": {
+          "instruction": "Speak as a warm, captivating storyteller — slow and deliberate, with gentle wonder for magical moments and tender warmth for emotional ones."
+        }
+      }
+    }
+  },
+  "imageParams": {
+    "provider": "google",
+    "model": "gemini-3.1-flash-image-preview",
+    "style": "painterly watercolor illustration",
+    "images": {
+      "mara": {
+        "type": "imagePrompt",
+        "prompt": "A girl, age 10, with wild curly red hair and bright green eyes, wearing a worn blue dress and muddy boots, curious and brave expression"
+      },
+      "wolf": {
+        "type": "imagePrompt",
+        "prompt": "A large silver wolf with a thick luminous coat, wise amber eyes, and a calm, gentle demeanor — majestic but not threatening"
+      }
+    }
+  },
+  "movieParams": {
+    "provider": "google",
+    "model": "veo-3.1-generate",
+    "transition": { "type": "fade", "duration": 0.5 }
+  },
+  "beats": [
+    {
+      "speaker": "Narrator",
+      "text": "Deep in the emerald forest, young Mara wandered further than she ever had before.",
+      "imageNames": ["mara"],
+      "imagePrompt": "A small figure standing at the edge of a vast ancient forest, towering trees with glowing moss, golden afternoon light filtering through the canopy, a sense of wonder and apprehension"
+    },
+    {
+      "speaker": "Narrator",
+      "text": "Then, from the shadows between the roots, came the Silver Wolf — ancient, patient, and utterly still.",
+      "imageNames": ["mara", "wolf"],
+      "imagePrompt": "A girl and a large wolf facing each other in a misty forest clearing, shafts of light between them, tension softening into curiosity"
+    },
+    {
+      "speaker": "Narrator",
+      "text": "Side by side, they walked through the night until the lanterns of home flickered into view.",
+      "imageNames": ["mara", "wolf"],
+      "imagePrompt": "A girl and a wolf walking together along a moonlit forest path, distant warm cottage lights glowing through the trees, fireflies drifting around them"
+    }
+  ]
+}
+```

package/server/workspace/helps/telegram.md

@@ -108,6 +108,7 @@ These are typed directly into the Telegram chat. They mirror the CLI:
 - `/roles` — list available roles.
 - `/role <id>` — switch to a specific role (e.g. `/role office`).
 - `/status` — show the current session info (session ID, current role).
+- `//<skill> [args...]` — shortcut for `/reset` followed by `/<skill> [args...]`: start a fresh session and run the skill (with any args) in one tap (e.g. `//mag2 https://example.com/post`).
 
 Any other text is treated as a message to the assistant.
 

package/server/workspace/helps/wiki.md

@@ -145,16 +145,18 @@ Pre-existing 3- or 4-column tables (without a Tags header) keep parsing; their e
 
 - A page's YAML frontmatter `tags:` field is the source of truth for that page's tags.
 - The tags recorded for that slug in `index.md` must match the frontmatter set exactly (order and case don't matter; we compare as a lowercased set).
-- `manageWiki` `action: "lint_report"` flags any mismatch as **Tag drift**. Fix by updating whichever side is stale.
+- The Lint button on the `/wiki` UI flags any mismatch as **Tag drift**. Fix by updating whichever side is stale.
 
-## Canvas Tool
+## Browsing the wiki
 
-Use the `manageWiki` tool to display wiki content in the canvas:
+Wiki page Writes/Edits the LLM performs render inline in the chat automatically — no extra display call needed.
 
-- `action: "index"` — show the page catalog
-- `action: "page"` — show a single page (provide `pageName`)
-- `action: "log"` — show the activity log
-- `action: "lint_report"` — run a health check
+For browse / lint queries, point the user at the `/wiki` UI:
+
+- `/wiki` — the page catalog (with tag filters)
+- `/wiki/pages/<slug>` — a specific page
+- `/wiki/log` — the activity log
+- The Lint button on `/wiki` runs a health check
 
 ## Relationship to `memory.md`
 

package/server/workspace/journal/archivist-cli.ts

@@ -1,30 +1,13 @@
-// Transport layer for the journal archivist: wraps the Claude Code
-// CLI as a subprocess so summarization runs against the user's
-// subscription quota rather than the API key budget.
-//
-// The pure data shapes (interfaces, prompts, validators) live in
-// `./archivist-schemas.ts`. This file is the only one that touches
-// `node:child_process`, kept thin so dependency injection in tests
-// never has to mock a subprocess.
+// Spawning the Claude Code CLI runs summarization against the user's subscription quota rather than the API-key budget.
 
 import { spawn } from "node:child_process";
 import { CLI_SUBPROCESS_TIMEOUT_MS } from "../../utils/time.js";
 
-// (systemPrompt, userPrompt) → raw model output as a string.
-// The daily/optimization passes parse JSON out of the string
-// themselves; this layer stays transport-only.
 export type Summarize = (systemPrompt: string, userPrompt: string) => Promise<string>;
 
-// Wall-clock cap per CLI invocation. 5 minutes is comfortably above
-// the worst-case summarization run we've seen and still short enough
-// that a wedged subprocess doesn't tie up resources forever.
 const CLI_TIMEOUT_MS = CLI_SUBPROCESS_TIMEOUT_MS;
 
-// Sentinel thrown on ENOENT. Each subsystem catches this and decides
-// what to do — journal disables itself for the rest of the server
-// lifetime; chat-index / sources log and skip. The message is
-// subsystem-neutral so callers logging `err.message` verbatim (e.g.
-// chat-index) don't surface a misleading "journal disabled" warning.
+// Subsystem-neutral message: chat-index / sources also catch this and would otherwise log a misleading "journal disabled".
 export class ClaudeCliNotFoundError extends Error {
   constructor() {
     super("`claude` CLI is not available on PATH");
@@ -43,11 +26,9 @@ export class ClaudeCliFailedError extends Error {
   }
 }
 
-// Default summarizer. Spawns `claude -p` and pipes the combined
-// system + user prompt to stdin so we don't hit shell-argv limits
-// for large day excerpts.
-export const runClaudeCli: Summarize = async (systemPrompt, userPrompt) => {
-  return new Promise((resolve, reject) => {
+// Pipe the combined prompt via stdin to dodge shell-argv limits for large day excerpts.
+export const runClaudeCli: Summarize = async (systemPrompt, userPrompt) =>
+  new Promise((resolve, reject) => {
     const child = spawn("claude", ["-p", "--output-format", "text"], {
       stdio: ["pipe", "pipe", "pipe"],
     });
@@ -95,8 +76,7 @@ export const runClaudeCli: Summarize = async (systemPrompt, userPrompt) => {
       }
     });
 
-    // Surface stdin write errors (e.g. EPIPE if the child exited
-    // before we finished writing) instead of silently dropping them.
+    // Surface EPIPE etc. — child may exit before we finish writing.
     child.stdin.on("error", (err: Error) => {
       if (settled) return;
       settled = true;
@@ -104,12 +84,7 @@ export const runClaudeCli: Summarize = async (systemPrompt, userPrompt) => {
       reject(err);
     });
 
-    // Send the full prompt in one write. If Node's stream layer
-    // signals backpressure (write returns false), wait for "drain"
-    // before calling end() so we don't close stdin while the buffer
-    // still has data to flush. For typical archivist prompts this
-    // path rarely fires, but very large session excerpts can reach
-    // it.
+    // Wait for "drain" on backpressure before end() so the buffer fully flushes — large excerpts can hit this path.
     const payload = `${systemPrompt}\n\n---\n\n${userPrompt}`;
     const flushed = child.stdin.write(payload);
     if (flushed) {
@@ -118,4 +93,3 @@ export const runClaudeCli: Summarize = async (systemPrompt, userPrompt) => {
       child.stdin.once("drain", () => child.stdin.end());
     }
   });
-};

package/server/workspace/journal/archivist-schemas.ts

@@ -1,22 +1,8 @@
-// Data shapes, prompts, and validators for the journal archivist.
-// Pure module — no IO, no subprocess, no global state. The CLI
-// transport (subprocess wrapper, error classes, default Summarize)
-// lives in `./archivist-cli.ts`.
-//
-// Splitting these used to be one file (`archivist.ts`), but it had
-// grown to 386 lines mixing transport with schemas. Keeping prompts
-// + validators separate lets tests / future passes import the data
-// shapes without dragging in `node:child_process`.
-
 import { isRecord } from "../../utils/types.js";
 
-// --- Daily archivist contract ---------------------------------------
-
 export interface SessionEventExcerpt {
   source: string; // "user" | "assistant" | "tool" | ...
   type: string; // "text" | "tool_result" | ...
-  // One-line human-readable rendering of the event, already
-  // truncated to a sane length by the caller.
   content: string;
 }
 
@@ -24,10 +10,7 @@ export interface SessionExcerpt {
   sessionId: string;
   roleId: string;
   events: SessionEventExcerpt[];
-  // Workspace-relative file paths produced by the session's tool
-  // calls (e.g. "stories/foo.json", "HTMLs/bar.html",
-  // "wiki/pages/baz.md"). Surfaced so the archivist can emit
-  // navigable markdown links to them in the summaries.
+  // Workspace-relative paths the archivist links from the summary (e.g. "stories/foo.json", "wiki/pages/baz.md").
   artifactPaths: string[];
 }
 
@@ -56,9 +39,7 @@ export interface DailyArchivistOutput {
   topicUpdates: TopicUpdate[];
 }
 
-// System prompt for the daily pass. Written long-form because the
-// model does a much better job with explicit rules and an example
-// than with a terse instruction.
+// Long-form: the model does notably better with explicit rules + an example than with a terse instruction.
 export const DAILY_SYSTEM_PROMPT = `You are the journal archivist for a personal MulmoClaude workspace.
 Your job: given raw session excerpts for a single day, produce
 (1) a daily summary and (2) updates to long-running topic notes.
@@ -107,8 +88,6 @@ SESSION LINKS
 LANGUAGE
 - Match the language of the source sessions. Always.`;
 
-// Build the user-side prompt for one day's worth of content.
-// Pure string construction — safe to unit test if we ever want to.
 export function buildDailyUserPrompt(input: DailyArchivistInput): string {
   const parts: string[] = [];
   parts.push(`DATE: ${input.date}`);
@@ -132,9 +111,7 @@ export function buildDailyUserPrompt(input: DailyArchivistInput): string {
   }
   parts.push("");
 
-  // Union of all workspace-relative artifact paths the day's
-  // sessions produced, deduped and sorted. Given to the archivist
-  // so it can link to them from the summary text.
+  // Dedupe + sort artifact paths so the archivist can link to them from the summary.
   const allArtifacts = new Set<string>();
   for (const sessionExcerpt of input.sessionExcerpts) {
     for (const artifactPath of sessionExcerpt.artifactPaths) allArtifacts.add(artifactPath);
@@ -162,12 +139,9 @@ export function buildDailyUserPrompt(input: DailyArchivistInput): string {
   return parts.join("\n");
 }
 
-// --- Optimization archivist contract --------------------------------
-
 export interface OptimizationTopicSnapshot {
   slug: string;
-  // First ~500 chars of the topic file, enough for the model to
-  // judge similarity without blowing up prompt size.
+  // First ~500 chars — enough to judge similarity without blowing up prompt size.
   headContent: string;
 }
 
@@ -227,21 +201,9 @@ export function buildOptimizationUserPrompt(input: OptimizationInput): string {
   return parts.join("\n");
 }
 
-// --- JSON extraction ------------------------------------------------
-
-// Tolerant JSON extractor: prefers a ```json fenced block; falls back
-// to scanning for the first balanced `{ ... }` block. Returns `null`
-// on failure so callers can log-and-skip instead of crash.
-//
-// JSON extraction helpers moved to server/utils/json.ts.
-// Re-export here so journal callers (and existing tests) keep a
-// single import surface for the archivist contract.
+// Re-exported so journal callers + existing tests keep a single import surface for the archivist contract.
 export { extractJsonObject, findBalancedBraceBlock } from "../../utils/json.js";
 
-// --- Validators ------------------------------------------------------
-
-// Type guards used by callers to validate parsed output. Written as
-// guards rather than `as` casts per project conventions.
 export function isDailyArchivistOutput(value: unknown): value is DailyArchivistOutput {
   if (!isRecord(value)) return false;
   const recordValue = value as Record<string, unknown>;