@mulmoclaude/core 0.1.0

package/assets/helps/custom-view.md

@@ -0,0 +1,433 @@
+# Custom collection views (LLM-authored HTML)
+
+A **custom view** is an HTML file you write that renders a collection's records
+however the user wants — a year-at-a-glance planner, a Gantt bar, a heat-map,
+a printable report. The host renders it in a sandboxed iframe over the
+collection's data. The user asks for it in plain language ("give me a view that
+shows my whole year"); you author the HTML and register it.
+
+Read `config/helps/collection-skills.md` first for the collection/schema DSL.
+This file is only about the **view** layer.
+
+## Where the files go
+
+```text
+data/skills/<slug>/
+  schema.json          ← register the view here, under `views[]`
+  views/
+    <name>.html        ← the view you author (Write/Edit)
+```
+
+**Feed collections** keep their skill files under `feeds/<slug>/` instead of
+`data/skills/<slug>/`, so author a feed's view at `feeds/<slug>/views/<name>.html`
+and register it in `feeds/<slug>/schema.json`. Everything else below — the
+`views[]` entry shape, the runtime contract, the sandbox rules — is identical.
+
+The HTML lives under `views/` and must end in `.html`. Register each view in
+the collection's `schema.json`:
+
+```jsonc
+{
+  "title": "Annual Plan",
+  "icon": "calendar_month",
+  "dataPath": "data/annual-plan/items",
+  "primaryKey": "id",
+  "fields": {
+    /* … */
+  },
+  "views": [
+    { "id": "year", "label": "Year", "icon": "grid_view", "file": "views/year.html", "capabilities": ["read"] },
+    { "id": "planner", "label": "Planner", "icon": "edit_calendar", "file": "views/planner.html", "capabilities": ["read", "write"] },
+  ],
+}
+```
+
+- **`id`** — a slug (letters/digits/`-`/`_`). The selector shows one button per view.
+- **`label`** — the button text (author it; it is not run through translation).
+- **`icon`** — optional Material Symbols icon name.
+- **`file`** — `views/<name>.html`, path-safe.
+- **`capabilities`** — least privilege. `["read"]` (default) for a view that
+  only displays data; `["read","write"]` only if the view edits records.
+
+After you Write the HTML and register it, the view's button appears in the
+collection's view-mode selector automatically.
+
+## The runtime contract — `window.__MC_VIEW`
+
+The host injects a bootstrap into your page **before any of your scripts run**:
+
+```js
+window.__MC_VIEW = {
+  slug: "annual-plan", // this collection
+  token: "<scoped capability token>", // Authorization bearer
+  dataUrl: "http://localhost:3001/api/collections/annual-plan/view-data",
+  onChange: (cb) => unsubscribe, // live refresh — see "Staying live" below
+  openItem: (id, mode) => void, // open a record in the host's panel — see "Opening a record"
+  startChat: (prompt, role) => void, // draft a new chat for the user — see "Starting a chat"
+};
+```
+
+### Reading records
+
+```js
+const { token, dataUrl } = window.__MC_VIEW;
+const res = await fetch(dataUrl, { headers: { Authorization: "Bearer " + token } });
+if (!res.ok) throw new Error("load failed: " + res.status);
+const { items } = await res.json(); // { collection, count, items: [...] }
+```
+
+Records come back **with computed fields already resolved** (derived formulas,
+toggles, embeds) — the same numbers the user sees elsewhere.
+
+- Narrow large reads: `dataUrl + "?fields=title,start,end"` or `?ids=a,b,c`
+  (comma-separated). A read of **more than 200 records** without `ids`/`fields`
+  is refused — always project `fields` for big collections.
+
+### Writing records (only with the `write` capability)
+
+```js
+const res = await fetch(dataUrl, {
+  method: "PUT",
+  headers: { Authorization: "Bearer " + token, "Content-Type": "application/json" },
+  body: JSON.stringify({ items: [{ id: "task-3", start: "2026-07-01" }], mode: "merge" }),
+});
+const { written, rejected } = await res.json(); // fix & re-send any rejected rows
+```
+
+- `mode`: `"merge"` (update only the fields you send — use this for edits),
+  `"upsert"` (replace the whole record), `"create"` (fail if the id exists).
+- Each row must carry the collection's `primaryKey`.
+- **Never** send computed fields (`derived` / `toggle` / `embed`) — they are
+  rejected. Write the underlying enum for a toggle.
+- **There is no delete** from a view. A view can never do more than the agent's
+  own data tools.
+
+Surface any `rejected` rows to the user with their `problem` text — don't fail
+silently.
+
+### Staying live — `onChange`
+
+By default a view paints once, on load. To keep it fresh, register a callback —
+it runs whenever the collection's data changes on the server:
+
+```js
+async function render() {
+  const res = await fetch(dataUrl, { headers: { Authorization: "Bearer " + token } });
+  if (!res.ok) return; // handle the error per your UI
+  const { items } = await res.json();
+  // …draw items…
+}
+render(); // initial paint
+window.__MC_VIEW.onChange(render); // live refresh on every server-side change
+```
+
+What you need to know:
+
+- **It fires for every writer** — the assistant adding/editing a record in chat,
+  an edit from another browser tab, a feed refresh, and auto-generated recurring
+  records. Your view stays in sync no matter who changed the data.
+- **Make the callback a full re-fetch + re-render** (like `render` above). It is
+  a "something changed, reload" signal — it carries no record data — and one
+  callback may stand in for several rapid changes.
+- **It is already debounced** (a burst of changes collapses to one call) — do
+  **not** add your own throttle.
+- **No extra capability needed** — a read-only view can use `onChange`.
+- It returns an **unsubscribe** function; you rarely need it (the view is torn
+  down with the iframe), but it's there for fine-grained control.
+
+### Opening a record — `openItem`
+
+Your view owns the _layout_ (a grid, a chart, a board); it doesn't have to
+rebuild a form to view or edit one record. Call `openItem` to hand a record to
+the host's own panel — the same detail/edit modal the user gets clicking a row
+in the table view — centred over your view:
+
+```js
+window.__MC_VIEW.openItem("task-3"); // read-only detail (default)
+window.__MC_VIEW.openItem("task-3", "edit"); // jump straight into the editor
+```
+
+- **`id`** — the record's `primaryKey` value. If it isn't a loaded record,
+  nothing happens (fire-and-forget; returns nothing).
+- **`mode`** — `"view"` (default) opens read-only detail with the panel's own
+  Edit button; `"edit"` opens the editor directly.
+- **No `write` capability required — even for `"edit"`.** Opening the host's
+  panel is a _user_ action in the host's trusted UI: the user still has to press
+  Save, and the write goes through the host, not your scoped token. So a
+  `["read"]` view can offer a full "edit this record" affordance without
+  widening its own capabilities. (Capabilities gate what your view's _code_ may
+  do to the data; they don't restrict what the user may do through the host.)
+- **Pair it with `onChange`.** After the user saves in the panel, your
+  `onChange` callback fires (the data changed), so a live view repaints itself —
+  no extra wiring needed.
+
+This is the right tool whenever a record's full detail is richer than your
+view's summary, or whenever the user wants to edit but you don't want a
+`write`-capable view doing its own PUTs.
+
+### Starting a chat — `startChat`
+
+Your view can't reach external services or run a skill on its own (the sandbox
+blocks it). Instead, hand the work to a chat: `startChat` opens a **new chat
+session with your prompt prefilled in the composer** — as an editable draft. It
+does **not** send. The user reads it, edits if they want, and presses Send (or
+clears it). The agent in that approved chat does the real work — file a GitHub
+issue and write the URL back, fetch a link's title/image and save them, or just
+start from a task record.
+
+```js
+const task = items.find((r) => r.id === id);
+window.__MC_VIEW.startChat(`Create a GitHub issue for this task and write the URL back to record ${id}:\n\n` + `Title: ${task.title}\n${task.body}`);
+```
+
+- **`prompt`** — the seed text. Empty / whitespace-only is ignored (no empty
+  chat). Build it from your records — that's the whole point.
+- **`role`** _(optional second argument)_ — a built-in role id to preselect for
+  the new session (e.g. `"office"`, `"investor"`); validated by the host. Omit it
+  and the chat opens in **General** — which is what you usually want.
+- **No capability required.** Your view's code only _proposes text into an input
+  field_ — nothing is created, fetched, or written until the **user** presses
+  Send, at which point it's an ordinary agent run they authored. So a `["read"]`
+  view can offer "start work on this" buttons freely.
+- **Pair it with `onChange`.** When the chat's agent later writes back to a
+  record, your `onChange` callback fires and a live view repaints.
+
+Use this — not a hidden flag the user has to reconcile later — whenever a button
+should _start backend work_: the user stays in the loop through trusted first-
+party UI, and the action runs as a normal, visible, cancellable agent turn.
+
+## Sandbox rules (what the view may and may not do)
+
+The view runs in a `sandbox="allow-scripts"` iframe with a strict CSP:
+
+- **Inline `<script>` and `<style>` only.** External scripts/styles/fonts must
+  come from the allowed CDNs: `cdn.jsdelivr.net`, `unpkg.com`,
+  `cdnjs.cloudflare.com`, `fonts.googleapis.com`, `fonts.gstatic.com`,
+  `cdn.plot.ly` — so charting libraries (Chart.js, Plotly, D3) load fine from
+  those CDNs. No other external hosts.
+- **`<img>` may load from any `https:` host** (plus `data:` / `blob:`), so an
+  image URL stored in a record — a feed's article thumbnail, a poster, an
+  avatar — renders directly. (Images are the one resource type not pinned to the
+  CDN allowlist; everything else above still is.)
+- **`<audio>` / `<video>` may load from any `https:` host** (plus the origin and
+  `data:` / `blob:`), so a record's media URL — a podcast feed's `.mp3`, a
+  video enclosure — plays directly.
+- **`fetch` (and XHR / WebSocket / `sendBeacon`) is allowed ONLY to
+  `window.__MC_VIEW.dataUrl`'s origin.** All other origins are blocked — no
+  phone-home, no third-party analytics, no fetching weather / prices / etc.
+  directly from the view. If the user needs external data, put it in a (feed)
+  collection and read it through `dataUrl`. (This is the channel that actually
+  matters for keeping the scoped token and records from leaking off-box.) When a
+  button should _do_ outside work — file an issue, fetch a link's metadata, run a
+  skill — don't try to reach out from view code; use **`startChat`** (above) to
+  hand the task to a user-approved chat.
+- No access to cookies, `localStorage`, or the parent page — the iframe has an
+  opaque origin. The token is the only credential, and it is scoped to this one
+  collection.
+- **Opening external links is allowed** — use `<a href="…" target="_blank"
+rel="noopener">` (or `window.open(url, "_blank")`) to open a record's URL in a
+  new browser tab, e.g. a feed card linking to its article. The link opens as a
+  normal tab. (A plain same-tab `<a href>` would try to navigate the sandboxed
+  frame itself and is blocked, so always use `target="_blank"` for outbound
+  links.)
+- Build a full HTML document with a `<head>` (the host injects its bootstrap at
+  the start of `<head>`).
+
+## Editing / iterating
+
+To change a view later, just Read and Edit its `views/<name>.html` file under the
+collection's skill dir (`data/skills/<slug>/` — or `feeds/<slug>/` for a feed);
+its path is in the schema's `views[]`. To remove one, delete the file and its
+`views[]` entry — or use the collection's settings gear (the per-collection
+config modal) in the UI, which does both for you.
+
+---
+
+## Example 1 — Year overview (read-only)
+
+A 12-month grid that plots each record on its start month. Schema has `date`
+fields `start` / `end` and a `title`. `capabilities: ["read"]`.
+
+`data/skills/annual-plan/views/year.html`:
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <style>
+      body {
+        font-family: system-ui, sans-serif;
+        margin: 0;
+        padding: 16px;
+        color: #1e293b;
+      }
+      h1 {
+        font-size: 16px;
+        margin: 0 0 12px;
+      }
+      .grid {
+        display: grid;
+        grid-template-columns: repeat(4, 1fr);
+        gap: 8px;
+      }
+      .month {
+        border: 1px solid #e2e8f0;
+        border-radius: 8px;
+        padding: 8px;
+        min-height: 90px;
+      }
+      .month h2 {
+        font-size: 12px;
+        color: #64748b;
+        margin: 0 0 6px;
+      }
+      .chip {
+        font-size: 12px;
+        background: #eef2ff;
+        color: #3730a3;
+        border-radius: 4px;
+        padding: 2px 6px;
+        margin-bottom: 4px;
+        cursor: pointer;
+      }
+      .err {
+        color: #b91c1c;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Year overview</h1>
+    <div id="root">Loading…</div>
+    <script>
+      const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+      async function main() {
+        const { token, dataUrl } = window.__MC_VIEW;
+        const res = await fetch(dataUrl, { headers: { Authorization: "Bearer " + token } });
+        if (!res.ok) throw new Error("HTTP " + res.status);
+        const { items } = await res.json();
+        const buckets = MONTHS.map(() => []);
+        for (const it of items) {
+          const m = it.start ? new Date(it.start).getMonth() : -1;
+          if (m >= 0 && m < 12) buckets[m].push(it); // keep the item, not just its title — we need the id
+        }
+        const root = document.getElementById("root");
+        root.className = "grid";
+        root.innerHTML = MONTHS.map(
+          (name, i) =>
+            '<div class="month"><h2>' +
+            name +
+            "</h2>" +
+            buckets[i].map((it) => '<div class="chip" data-id="' + it.id + '">' + (it.title || it.id) + "</div>").join("") +
+            "</div>",
+        ).join("");
+        // Click a chip → open that record in the host's panel (read-only detail;
+        // the panel's own Edit button takes it from there). Pass "edit" to jump
+        // straight into the editor — no `write` capability needed.
+        root.onclick = (e) => {
+          const chip = e.target.closest(".chip");
+          if (chip) window.__MC_VIEW.openItem(chip.dataset.id);
+        };
+      }
+      main().catch((e) => {
+        document.getElementById("root").innerHTML = '<span class="err">Could not load: ' + e.message + "</span>";
+      });
+      // Live refresh: re-run whenever the collection's data changes server-side.
+      window.__MC_VIEW.onChange(() => main().catch(() => {}));
+    </script>
+  </body>
+</html>
+```
+
+## Example 2 — Weekly planner (read + write)
+
+Seven day columns; clicking a record bumps its `start` date forward a day and
+writes it back. `capabilities: ["read","write"]`.
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <style>
+      body {
+        font-family: system-ui, sans-serif;
+        margin: 0;
+        padding: 16px;
+      }
+      .row {
+        display: grid;
+        grid-template-columns: repeat(7, 1fr);
+        gap: 6px;
+      }
+      .day {
+        border: 1px solid #e2e8f0;
+        border-radius: 8px;
+        padding: 6px;
+        min-height: 80px;
+      }
+      .task {
+        font-size: 12px;
+        background: #f1f5f9;
+        border-radius: 4px;
+        padding: 3px 6px;
+        margin-bottom: 4px;
+        cursor: pointer;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root">Loading…</div>
+    <script>
+      const DAYS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+      const { token, dataUrl } = window.__MC_VIEW;
+      const auth = { Authorization: "Bearer " + token, "Content-Type": "application/json" };
+
+      async function read() {
+        const res = await fetch(dataUrl, { headers: { Authorization: "Bearer " + token } });
+        if (!res.ok) throw new Error("HTTP " + res.status);
+        return (await res.json()).items;
+      }
+      async function bump(item) {
+        const next = new Date(item.start || Date.now());
+        next.setDate(next.getDate() + 1);
+        const res = await fetch(dataUrl, {
+          method: "PUT",
+          headers: auth,
+          body: JSON.stringify({ items: [{ id: item.id, start: next.toISOString().slice(0, 10) }], mode: "merge" }),
+        });
+        const { rejected } = await res.json();
+        if (rejected && rejected.length) alert(rejected[0].problem);
+        render();
+      }
+      async function render() {
+        const items = await read();
+        const cols = DAYS.map(() => []);
+        for (const it of items) {
+          const d = it.start ? (new Date(it.start).getDay() + 6) % 7 : 0;
+          cols[d].push(it);
+        }
+        const root = document.getElementById("root");
+        root.className = "row";
+        root.innerHTML = DAYS.map((d, i) => '<div class="day" data-i="' + i + '"><b>' + d + "</b></div>").join("");
+        DAYS.forEach((_, i) => {
+          const cell = root.querySelector('[data-i="' + i + '"]');
+          for (const it of cols[i]) {
+            const el = document.createElement("div");
+            el.className = "task";
+            el.textContent = it.title || it.id;
+            el.onclick = () => bump(it);
+            cell.appendChild(el);
+          }
+        });
+      }
+      render().catch((e) => {
+        document.getElementById("root").textContent = "Could not load: " + e.message;
+      });
+      // Live refresh: re-render on any server-side change (incl. our own writes
+      // landing, and edits from the assistant or another tab).
+      window.__MC_VIEW.onChange(() => render().catch(() => {}));
+    </script>
+  </body>
+</html>
+```

package/assets/helps/feeds.md

@@ -0,0 +1,114 @@
+# Feeds — pull internet data into a self-refreshing collection
+
+A **feed** is a data source you register once; the host then fetches it on a
+schedule and stores each item as a record. A feed is a `CollectionSchema` plus
+an `ingest` block, written as a single file:
+
+```
+feeds/<slug>/schema.json     ← YOU write this (Write)
+feeds/<slug>/_state.json     ← the host writes this (fetch cursor/state)
+data/feeds/<slug>/<id>.json  ← the host writes these (one per item)
+```
+
+It is NOT a skill (no `SKILL.md`, nothing under `.claude/skills/`), so it never
+enters the prompt. You don't call any tool to fetch — the host's retrieval
+engine does that automatically: the first time the feed's view is opened, on an
+hourly schedule thereafter, and when the user clicks **Refresh feed**. Records
+render in the standard collection view at `/feeds/<slug>`.
+
+This is the project philosophy: *the workspace is the database; you are the
+intelligent interface.* Adding a feed = **fetch the URL, look at its real
+fields, and write one `schema.json`.**
+
+## Workflow to add a feed
+
+1. **Fetch and inspect the URL yourself** (a web/fetch tool, or `curl`). Look at
+   the actual structure — the item tags/fields it carries. Do NOT guess or ask
+   the user design questions; infer everything from the data.
+2. **Write `feeds/<slug>/schema.json`** (see the shape below). Pick a short
+   `slug` (lowercase letters/digits/hyphens).
+3. Tell the user the feed is registered and that opening `/feeds/<slug>` will
+   load its items (the host fetches automatically on first open). Do NOT tell
+   them to click Refresh — that's not needed for a new feed.
+
+To **remove** a feed completely, delete BOTH its `feeds/<slug>/` directory
+(schema + state) and its records under `data/feeds/<slug>/`. The `/feeds` page
+lists all registered feeds, and its delete button does the same.
+
+## Schema shape (STRICT — follow exactly)
+
+```json
+{
+  "title": "Example Feed",
+  "icon": "dynamic_feed",
+  "dataPath": "data/feeds/<slug>",
+  "primaryKey": "id",
+  "displayField": "headline",
+  "fields": {
+    "id":        { "type": "string",   "label": "ID", "primary": true },
+    "headline":  { "type": "string",   "label": "Headline" },
+    "url":       { "type": "string",   "label": "URL" },
+    "published": { "type": "date",     "label": "Published" },
+    "summary":   { "type": "markdown", "label": "Summary" }
+  },
+  "ingest": {
+    "kind": "rss",
+    "url": "https://example.com/feed.xml",
+    "schedule": "hourly",
+    "idFrom": "guid",
+    "map": { "id": "guid", "headline": "title", "url": "link", "published": "pubDate", "summary": "description" }
+  }
+}
+```
+
+- `title` (required), `icon` (required — a Material Symbols name; `dynamic_feed` is
+  a good default). `dataPath` is set by the host to `data/feeds/<slug>` — include
+  it (must equal that) or omit it; any other value is ignored. A feed can only
+  ever store records under its own `data/feeds/<slug>` folder.
+- `primaryKey` (required): names the id field. That field must set
+  `primary: true`. The host derives a safe, stable filename from its value, so
+  map it from a STABLE unique value (an item guid/id/link, or a snapshot date)
+  — that's what makes re-fetches upsert in place instead of duplicating.
+- `displayField` (recommended): the field whose value labels each record in the
+  calendar and notifications. Set it to the human-readable field (e.g. the
+  headline) — otherwise labels fall back to the opaque primaryKey id.
+- `fields` is an OBJECT keyed by field name (NOT an array). Each value is
+  `{ type, label, primary? }`. `type` MUST be one of: `string`, `text`, `email`,
+  `number`, `date`, `boolean`, `markdown`, `enum` (enum also needs `values`).
+  There is no `url`/`datetime`/`textarea` — use `string` for links, `date` for
+  timestamps, `text`/`markdown` for bodies.
+- Include a `date` field and map the feed's timestamp into it — values in a
+  `date` field are auto-coerced to `YYYY-MM-DD`, which powers the calendar view
+  and the `maxItems` cap.
+
+## The `ingest` block
+
+- `kind`: `rss` / `atom` (XML feeds) or `http-json` (a JSON API).
+- `url`: the feed / API endpoint (must be public http/https; the host refuses
+  private/loopback addresses).
+- `schedule`: `hourly` | `daily` | `weekly` | `on-demand`.
+- `map`: `{ <yourFieldName>: <sourcePath> }` — a dot/bracket path into each
+  fetched item. **Map the fields you actually saw when you inspected the feed.**
+  - rss/atom: each item is the parsed XML element. Tags are keys (`title`,
+    `link`, `pubDate`); attributes are keyed `@_name` (`enclosure.@_url`);
+    namespaced tags keep their prefix (`dc:creator`, `itunes:duration`);
+    text-bearing tags resolve to their text automatically.
+  - http-json: each item is the JSON object (`name`, `data.id`).
+- `itemsAt` (http-json only): dot/bracket path to the items array, e.g.
+  `results[]`. **Omit it when the response body is itself the array.**
+- `idFrom` (optional): a sourcePath for a stable id, used when the mapped
+  primaryKey value is empty (e.g. `guid`).
+- `maxItems` (optional, default `100`): keep only the newest N records by the
+  date field and delete the rest (`0` keeps everything; needs a `date` field).
+
+## Notes
+
+- http-json needs an array of objects. Columnar/parallel-array APIs (e.g.
+  Open-Meteo weather: `hourly.time[]` + `hourly.temperature_2m[]`) are not
+  supported yet.
+- A malformed `schema.json` is skipped at load time (with a diagnostic on the
+  notification bell), so double-check the shape above before writing.
+- A feed can carry **custom views** just like any collection — author the HTML at
+  `feeds/<slug>/views/<name>.html` and register it in the feed's `schema.json`
+  under `views[]`. See `config/helps/custom-view.md` (note the feed path is
+  `feeds/<slug>/`, not `data/skills/<slug>/`).

package/assets/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.
+- **`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.
+
+### 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/assets/helps/github.md

@@ -0,0 +1,23 @@
+# GitHub repositories in the workspace
+
+Git repositories cloned for the user live under `github/` in the workspace root.
+
+## Rules
+
+1. **Clone destination**: always clone into `github/<dir-name>/`, never into `/tmp/` or other locations outside the workspace.
+2. **Existing repo — same remote**: if `github/<dir-name>/` already exists and its `origin` remote matches the requested URL, run `git pull` to update instead of cloning again.
+3. **Existing repo — different remote**: if a directory with the desired name already exists but points at a different remote, **ask the user** to choose a directory name before proceeding. Never overwrite or re-initialize an existing repo silently.
+4. **Directory naming**: use the repository name by default (e.g. `github/mulmoclaude/` for `git@github.com:receptron/mulmoclaude.git`). If the user specifies a different name, use that.
+
+## Examples
+
+```bash
+# First clone
+git clone git@github.com:receptron/mulmoclaude.git github/mulmoclaude
+
+# Already exists, same remote → update
+cd github/mulmoclaude && git pull
+
+# Name conflict, different remote → ask user
+# "github/mulmoclaude already exists with a different remote. What name would you like?"
+```