npm - @mulmoclaude/core - Versions diffs - 0.1.0 - Mend

@mulmoclaude/core 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (122) hide show

package/assets/helps/billing-clients-worklog.md +215 -0
package/assets/helps/billing-invoice.md +458 -0
package/assets/helps/business.md +104 -0
package/assets/helps/collection-skills.md +810 -0
package/assets/helps/custom-view.md +433 -0
package/assets/helps/feeds.md +114 -0
package/assets/helps/gemini.md +57 -0
package/assets/helps/github.md +23 -0
package/assets/helps/guide.md +61 -0
package/assets/helps/index.md +89 -0
package/assets/helps/lessons-collection.md +400 -0
package/assets/helps/mulmoscript.md +249 -0
package/assets/helps/portfolio-tracker.md +211 -0
package/assets/helps/presentation-deck.md +828 -0
package/assets/helps/presenthtml.md +89 -0
package/assets/helps/sandbox.md +97 -0
package/assets/helps/spreadsheet.md +43 -0
package/assets/helps/storyteller.md +101 -0
package/assets/helps/telegram.md +136 -0
package/assets/helps/todo-collection.md +140 -0
package/assets/helps/vocabulary.md +109 -0
package/assets/helps/wiki.md +168 -0
package/assets/skills-preset/mc-cooking-coach/SKILL.md +217 -0
package/assets/skills-preset/mc-library/SKILL.md +188 -0
package/assets/skills-preset/mc-manage-automations/SKILL.md +119 -0
package/assets/skills-preset/mc-manage-skills/SKILL.md +141 -0
package/assets/skills-preset/mc-wiki-deep-lint/SKILL.md +108 -0
package/assets/skills-preset/mc-wiki-health-check/SKILL.md +61 -0
package/assets/skills-preset/mc-wiki-ingest/SKILL.md +182 -0
package/assets/skills-preset/mc-wiki-promote/SKILL.md +175 -0
package/assets/skills-preset/mc-zenn/SKILL.md +136 -0
package/dist/chunk-CKQMccvm.cjs +28 -0
package/dist/collection/core/actionVisible.d.ts +34 -0
package/dist/collection/core/calendarGrid.d.ts +120 -0
package/dist/collection/core/deriveAll.d.ts +38 -0
package/dist/collection/core/derivedFormula.d.ts +18 -0
package/dist/collection/core/draft.d.ts +18 -0
package/dist/collection/core/enumColors.d.ts +33 -0
package/dist/collection/core/errorMessage.d.ts +4 -0
package/dist/collection/core/itemLabel.d.ts +12 -0
package/dist/collection/core/presentCollection.d.ts +13 -0
package/dist/collection/core/promptSafety.d.ts +1 -0
package/dist/collection/core/schema.d.ts +355 -0
package/dist/collection/core/shortHexId.d.ts +8 -0
package/dist/collection/core/sortItems.d.ts +29 -0
package/dist/collection/core/uiTypes.d.ts +106 -0
package/dist/collection/index.cjs +793 -0
package/dist/collection/index.cjs.map +1 -0
package/dist/collection/index.d.ts +14 -0
package/dist/collection/index.js +740 -0
package/dist/collection/index.js.map +1 -0
package/dist/collection/paths.cjs +44 -0
package/dist/collection/paths.cjs.map +1 -0
package/dist/collection/paths.js +41 -0
package/dist/collection/paths.js.map +1 -0
package/dist/collection/server/atomic.d.ts +1 -0
package/dist/collection/server/delete.d.ts +38 -0
package/dist/collection/server/derive.d.ts +8 -0
package/dist/collection/server/discoveredCollection.d.ts +18 -0
package/dist/collection/server/discovery.d.ts +227 -0
package/dist/collection/server/host.d.ts +77 -0
package/dist/collection/server/index.cjs +1721 -0
package/dist/collection/server/index.cjs.map +1 -0
package/dist/collection/server/index.d.ts +11 -0
package/dist/collection/server/index.js +1671 -0
package/dist/collection/server/index.js.map +1 -0
package/dist/collection/server/io.d.ts +114 -0
package/dist/collection/server/paths.d.ts +52 -0
package/dist/collection/server/spawn.d.ts +55 -0
package/dist/collection/server/templatePath.d.ts +25 -0
package/dist/collection/server/util.d.ts +3 -0
package/dist/collection/server/validate.d.ts +19 -0
package/dist/collection/server/views.d.ts +20 -0
package/dist/deriveAll-C15OpM3K.cjs +399 -0
package/dist/deriveAll-C15OpM3K.cjs.map +1 -0
package/dist/deriveAll-C6BYnpBL.js +364 -0
package/dist/deriveAll-C6BYnpBL.js.map +1 -0
package/dist/file-change/index.cjs +72 -0
package/dist/file-change/index.cjs.map +1 -0
package/dist/file-change/index.d.ts +43 -0
package/dist/file-change/index.js +66 -0
package/dist/file-change/index.js.map +1 -0
package/dist/notifier/engine.d.ts +72 -0
package/dist/notifier/index.cjs +484 -0
package/dist/notifier/index.cjs.map +1 -0
package/dist/notifier/index.d.ts +3 -0
package/dist/notifier/index.js +464 -0
package/dist/notifier/index.js.map +1 -0
package/dist/notifier/store.d.ts +18 -0
package/dist/notifier/types.d.ts +118 -0
package/dist/notifier/validate.d.ts +17 -0
package/dist/scheduler/adapter.d.ts +48 -0
package/dist/scheduler/index.cjs +352 -0
package/dist/scheduler/index.cjs.map +1 -0
package/dist/scheduler/index.d.ts +2 -0
package/dist/scheduler/index.js +343 -0
package/dist/scheduler/index.js.map +1 -0
package/dist/scheduler/task-manager.d.ts +51 -0
package/dist/whisper/client.cjs +241 -0
package/dist/whisper/client.cjs.map +1 -0
package/dist/whisper/client.d.ts +35 -0
package/dist/whisper/client.js +239 -0
package/dist/whisper/client.js.map +1 -0
package/dist/whisper/ffmpeg.d.ts +6 -0
package/dist/whisper/index.cjs +433 -0
package/dist/whisper/index.cjs.map +1 -0
package/dist/whisper/index.d.ts +5 -0
package/dist/whisper/index.js +425 -0
package/dist/whisper/index.js.map +1 -0
package/dist/whisper/internal.d.ts +11 -0
package/dist/whisper/models.d.ts +49 -0
package/dist/whisper/sidecar.d.ts +8 -0
package/dist/whisper/whisper.d.ts +28 -0
package/dist/workspace-setup/assets.d.ts +10 -0
package/dist/workspace-setup/index.d.ts +3 -0
package/dist/workspace-setup/index.js +556 -0
package/dist/workspace-setup/index.js.map +1 -0
package/dist/workspace-setup/slug.d.ts +6 -0
package/dist/workspace-setup/slug.js +13 -0
package/dist/workspace-setup/slug.js.map +1 -0
package/dist/workspace-setup/sync.d.ts +94 -0
package/package.json +95 -0

package/assets/helps/presenthtml.md ADDED Viewed

@@ -0,0 +1,89 @@
+# 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.
+## Two ways to call it: `html` vs `path`
+`presentHtml` accepts **either** `html` **or** `path` (not both):
+- **`html`** — a complete self-contained document. The host saves it to a fresh `artifacts/html/<YYYY>/<MM>/<slug>-<timestamp>.html` and presents it. The response's `data.filePath` is the saved path — capture it if you need to store a reference.
+- **`path`** — the workspace-relative path of an HTML file you **already wrote** under `artifacts/html/…`. The host presents that existing page **without re-saving a copy**. Use this for pages you authored directly on disk with the `Write` tool (e.g. a pre-built lesson), so presenting them later doesn't duplicate the file. The path must end in `.html` and live under `artifacts/html/`.
+Saving (with `html`) also renders in the user's canvas, so do **not** loop it to batch-create many pages quietly — write those directly to disk and present them on demand with `path`.
+## 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/assets/helps/sandbox.md ADDED Viewed

@@ -0,0 +1,97 @@
+# Sandbox
+MulmoClaude runs the Claude Code agent inside a **Docker sandbox** when Docker is available. This isolates the agent's file-system access and limits what it can do on the host.
+## How It Works
+- On each agent invocation, the server checks whether Docker is running.
+- If Docker is available (and `DISABLE_SANDBOX` is not set), Claude Code runs inside a disposable container (`mulmoclaude-sandbox`) built from `Dockerfile.sandbox`.
+- If Docker is not available, Claude Code runs directly on the host with the workspace as its working directory.
+## What the Container Can Access
+| Mount | Container path | Mode |
+|---|---|---|
+| Workspace | `/home/node/mulmoclaude` | read-write |
+| `node_modules/` | `/app/node_modules` | read-only |
+| `server/` | `/app/server` | read-only |
+| `src/` | `/app/src` | read-only |
+| `~/.claude/` | `/home/node/.claude` | read-write |
+| `~/.claude.json` | `/home/node/.claude.json` | read-write |
+The container runs with `--cap-drop ALL` and as the host user's UID/GID, so it has no elevated privileges.
+## Disabling the Sandbox
+Set the environment variable `DISABLE_SANDBOX=1` to always run the agent directly on the host, even when Docker is available. Equivalently, pass the `--disable-sandbox` CLI flag — `yarn dev --disable-sandbox` or `npx mulmoclaude --disable-sandbox`. The flag form is handy on Windows PowerShell (no inline `VAR=value` syntax), in IDE / launcher run configs, and for quick ad-hoc debugging. Both set the same internal switch; the env var stays supported in parallel.
+## Debug aids (opt-in env vars)
+These flags exist for development / debugging only. Off by default so production runs aren't surprised. Each has an equivalent `--flag` CLI form (drop the `=1`, kebab-case the name) accepted by both `yarn dev` and `npx mulmoclaude` — e.g. `DISABLE_SANDBOX=1` ≡ `--disable-sandbox`, `PERSIST_TOOL_CALLS=1` ≡ `--persist-tool-calls`, `DISABLE_MACOS_REMINDER_NOTIFICATIONS=1` ≡ `--disable-macos-reminders`, `JOURNAL_FORCE_RUN_ON_STARTUP=1` ≡ `--journal-force-run`, `CHAT_INDEX_FORCE_RUN_ON_STARTUP=1` ≡ `--chat-index-force-run`. Secret-bearing vars (auth token, API keys) have no flag form on purpose — argv is visible via `ps` / shell history.
+- `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:
+- `SANDBOX_SSH_AGENT_FORWARD=1` — forwards the host's SSH agent socket (private keys stay on the host).
+- `SANDBOX_MOUNT_CONFIGS=gh,gitconfig` — allowlisted read-only config mounts.
+Full contract, what's deliberately excluded, and troubleshooting: [`docs/sandbox-credentials.md`](../../docs/sandbox-credentials.md).
+## Checking the Current Sandbox State
+Two places surface what's actually attached to **your** running container — useful when you've just toggled an opt-in flag and want to confirm it took effect.
+### From the UI — lock icon popup
+Click the 🔒 icon in the top bar. The popup shows:
+- **Sandbox enabled / disabled** — whether Docker was detected and `DISABLE_SANDBOX` is off.
+- **Host credentials attached** (only when the sandbox is on):
+  - **SSH agent**: `forwarded` when `SANDBOX_SSH_AGENT_FORWARD=1` **and** `$SSH_AUTH_SOCK` points at a live socket. If the flag is on but the socket is missing, the popup shows `not forwarded` and the server log carries the reason.
+  - **Mounted configs**: allowlisted names from `SANDBOX_MOUNT_CONFIGS` whose host path exists. Names you typed but whose host path is missing are silently dropped from the UI (they appear in the server log as `config mount skipped`).
+The popup also has a **sample query button** that asks Claude to summarise this information in natural language.
+### From inside a chat session
+Inside the container, you can verify each piece directly:
+```bash
+# SSH agent — lists identities the host agent will sign with
+ssh-add -l
+# gh config — mounted read-only, so `gh auth status` should succeed
+ls /home/node/.config/gh && gh auth status
+# gitconfig — mounted read-only
+cat /home/node/.gitconfig
+```
+### From the server log
+The popup intentionally exposes **names only**, never host paths or skip reasons. Full debug detail lives in the server log:
+- `[sandbox] host credentials attached to container` — one-line summary of what was mounted on agent spawn.
+- `[sandbox] unknown SANDBOX_MOUNT_CONFIGS entries ignored` — typo in the CSV.
+- `[sandbox] config mount skipped (host path missing)` — name is in the allowlist but the host file/dir doesn't exist.
+- `[sandbox] SSH agent forward requested but skipped` — flag on but `$SSH_AUTH_SOCK` unset or non-existent.
+If the popup isn't showing what you expect, grep the startup log for `[sandbox]` first.
+## First-Time Setup (macOS)
+On macOS, the Docker container uses a separate credential store from the host. Before using the sandbox for the first time (and whenever the credential expires), run:
+```
+yarn sandbox:login
+```
+This opens an interactive `claude login` session inside the container so that the sandbox has valid credentials.
+## Building the Image
+The sandbox image is built automatically on first use. If `Dockerfile.sandbox` changes, the image is rebuilt on the next agent invocation. No manual build step is needed.

package/assets/helps/spreadsheet.md ADDED Viewed

@@ -0,0 +1,43 @@
+# Spreadsheet Authoring Guide
+Reference for the `presentSpreadsheet` plugin. Read this before building a spreadsheet.
+## Cell Format
+Every cell is an object `{"v": value, "f": format}`.
+- `v` — value: text, number, date string, or formula (string starting with `=`)
+- `f` — optional format code for display
+## Formulas
+Set `v` to a string starting with `=`. Use Excel-style A1 cell references.
+```json
+{"v": "=B2*1.05", "f": "$#,##0.00"}
+{"v": "=SUM(A1:A10)", "f": "#,##0"}
+```
+Never pre-calculate — let the spreadsheet compute using cell refs, functions, and arithmetic.
+## Available Functions
+SUM, AVERAGE, COUNT, MIN, MAX, IF, AND, OR, NOT, ROUND, ABS, TODAY, DATE, DATEDIF, YEAR, MONTH, DAY, CONCATENATE, LEFT, RIGHT, MID, LEN, TRIM, UPPER, LOWER, VLOOKUP, INDEX, MATCH, PMT, FV, PV, NPV, IRR.
+## Dates
+Use date strings like `01/15/2025` or date formulas like `=TODAY()` or `=DATE(2025,1,15)`. The spreadsheet auto-parses common formats (MM/DD/YYYY, YYYY-MM-DD, DD-MMM-YYYY) into date serial numbers. Date arithmetic works: `=B2-TODAY()` calculates days between dates.
+## Format Codes
+| Code | Use |
+|---|---|
+| `$#,##0.00` | Currency |
+| `#,##0` | Integer with commas |
+| `0.00%` | Percent |
+| `0.00` | Decimal |
+| `MM/DD/YYYY` | Date |
+| `DD-MMM-YYYY` | Date |
+| `YYYY-MM-DD` | ISO date |
+Format is optional for plain text/numbers.

package/assets/helps/storyteller.md ADDED Viewed

@@ -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/assets/helps/telegram.md ADDED Viewed

@@ -0,0 +1,136 @@
+# Telegram Bridge
+The Telegram bridge lets you talk to your MulmoClaude from the Telegram app on your phone or desktop. Your own custom Telegram bot forwards messages to the MulmoClaude server running on your computer, and replies come back through the same bot.
+This is useful when you want to reach your MulmoClaude away from your computer — on a walk, from a phone, or from a friend's device — without exposing the server to the public internet.
+## How It Works
+- You create a **bot** with Telegram's BotFather; it gives you a token.
+- You run a **bridge process** (`yarn telegram`) on the same machine as the MulmoClaude server. The bridge uses your bot token to receive messages from Telegram, forwards them to MulmoClaude over `localhost:3001`, and sends the replies back to the Telegram user.
+- A short **allowlist** of Telegram chat IDs controls who can talk to the bot. Everyone else gets `"Access denied"`.
+Your computer has to be on and connected to the internet for the bot to respond. Close the laptop → the bot goes silent.
+## Prerequisites
+- MulmoClaude checked out and runnable (`yarn dev` works).
+- A Telegram account.
+- Two terminals free: one for `yarn dev`, one for `yarn telegram`.
+## Step 1 — Create the Bot with BotFather
+1. In Telegram, search for `@BotFather` (the official account has a blue check) and start a chat.
+2. Send `/newbot`.
+3. Answer the two prompts:
+   - **Display name** — what appears in the chat header. Anything, e.g. `"Alice's MulmoClaude"`.
+   - **Username** — must end in `bot` and be unique on Telegram, e.g. `alice_mulmoclaude_bot`.
+4. BotFather replies with a **token** like `1234567890:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw`. This token is the bot's password — anyone who has it can impersonate the bot. Keep it secret.
+Optional polish (can be done anytime later via BotFather):
+- `/setdescription` — text shown when users open the chat for the first time.
+- `/setuserpic` — the bot's avatar.
+- `/setprivacy` → `Disable` — lets the bot see all messages in group chats (by default it only sees messages starting with `/`).
+## Step 2 — Start MulmoClaude and the Bridge
+In terminal A, start MulmoClaude:
+```bash
+yarn dev
+```
+Wait until you see `[server] listening port=3001`.
+In terminal B, start the bridge. Leave the allowlist **empty on purpose** for the first run — you will need to discover your own chat ID before you can add it.
+```bash
+export TELEGRAM_BOT_TOKEN='1234567890:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw'
+export TELEGRAM_ALLOWED_CHAT_IDS=''
+yarn telegram
+```
+Expected output:
+```
+MulmoClaude Telegram bridge
+Allowlist: (empty — all chats will be denied)
+Connected (<socket id>).
+```
+## Step 3 — Find Your Chat ID and Allowlist It
+1. In Telegram, open your new bot (search the username you picked) and send it any message — `hi` works.
+2. In terminal B, you will see a log line like:
+   ```
+   [telegram] denied chat=987654321 user=@alice — not on allowlist
+   ```
+   That number (`987654321`) is **your Telegram chat ID**.
+3. Stop the bridge (`Ctrl+C`), put your ID in the allowlist, restart:
+   ```bash
+   export TELEGRAM_ALLOWED_CHAT_IDS='987654321'
+   yarn telegram
+   ```
+4. Send the bot another message. MulmoClaude should now reply.
+## Step 4 — Invite a Friend
+To let another person use your MulmoClaude:
+1. Share the bot's username with them; they search for it on Telegram and send it a message.
+2. Their chat ID appears in terminal B's `denied` log line, just like yours did in Step 3.
+3. Append their ID (comma-separated) and restart the bridge:
+   ```bash
+   export TELEGRAM_ALLOWED_CHAT_IDS='987654321,123456789'
+   yarn telegram
+   ```
+4. When they message the bot again, it works.
+To avoid re-exporting every time, put `TELEGRAM_BOT_TOKEN` and `TELEGRAM_ALLOWED_CHAT_IDS` in a `.env` file at the repo root. The bridge auto-loads `.env` on startup via `dotenv/config`, so the vars take effect just by restarting `yarn telegram` — no shell `export` needed.
+```dotenv
+# .env (repo root)
+TELEGRAM_BOT_TOKEN=1234567890:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw
+TELEGRAM_ALLOWED_CHAT_IDS=987654321,123456789
+```
+## Bot Commands
+These are typed directly into the Telegram chat. They mirror the CLI:
+- `/help` — show available commands.
+- `/reset` — start a fresh conversation session (drops prior context).
+- `/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.
+## Troubleshooting
+**`Connect error: bearer token rejected`** — MulmoClaude was restarted, so its bearer token changed. Restart `yarn telegram` to pick up the new one. To avoid this, pin `MULMOCLAUDE_AUTH_TOKEN` to the same value on both sides (see `docs/developer.md` §Auth).
+**`TELEGRAM_ALLOWED_CHAT_IDS: "foo" is not an integer chat id`** — typo in the allowlist. Chat IDs are plain integers only — no spaces, quotes, or `#` prefix. Negative integers (for group chats) are allowed.
+**Friend gets `"Access denied"` after you added their ID** — the allowlist is read once at startup. Restart `yarn telegram` after changing `TELEGRAM_ALLOWED_CHAT_IDS`.
+**Messages stop flowing with no error** — check that `yarn dev` is still running. If the MulmoClaude server is down, the bridge stays up but has nothing to forward to. The next inbound message will log `Connect error` or `Disconnected`.
+**Bot responds in a group chat you did not expect** — group chat IDs are **negative**. If you want the bot to work in a specific group, add that negative ID. By default BotFather enables "group privacy mode", so the bot only sees messages starting with `/` in groups — toggle it via BotFather's `/setprivacy` if you need full visibility.
+## Security Notes
+- The bot token is a password. If it leaks, regenerate it via BotFather's `/revoke`.
+- The allowlist is the only thing standing between "my friends" and "every Telegram user on Earth". Keep it current — remove chat IDs when you no longer want that person to have access, and restart the bridge.
+- The bridge logs chat IDs, usernames, and message lengths, but **not** message contents or the bot token. If you need a full audit trail, record it separately.
+- The MulmoClaude bearer token never leaves your machine. The bridge only talks to `localhost:3001`; your friends talk to Telegram's servers, which then talk to your bridge.
+## Full Operator Guide
+For the complete operator walkthrough (including screenshots-worthy step numbering and a Japanese translation), see `docs/message_apps/telegram/README.md` (English) and `docs/message_apps/telegram/README.ja.md` (Japanese) in the MulmoClaude repository.

package/assets/helps/todo-collection.md ADDED Viewed

@@ -0,0 +1,140 @@
+# Todo list — the canonical collection recipe
+Read this whenever you build (or migrate) a **todo / task list** as a collection.
+It is the authoritative template; copy it rather than reinventing one from the
+generic DSL fragments in `config/helps/collection-skills.md`. Read that file
+first for the general schema rules — this one is the todo-specific specialization.
+The design in one line: **the `status` enum is the single source of truth, and
+the "done" checkbox is a `toggle` field that projects it.** There is NO separate
+stored `done` boolean to keep in sync.
+> **The #1 mistake:** omitting the `done` toggle. Without it the list still works
+> — but there is **no checkbox**, only a status dropdown and a kanban column.
+> A todo list almost always wants the checkbox. Always include the toggle.
+## schema.json
+Author it at `data/skills/todos/schema.json` (the bridge mirrors it to
+`.claude/skills/todos/`; the user opens it at `/collections/todos`):
+```json
+{
+  "title": "Todos",
+  "icon": "checklist",
+  "dataPath": "data/todos/items",
+  "primaryKey": "id",
+  "fields": {
+    "id":       { "type": "string", "label": "ID", "primary": true, "required": true },
+    "done":     { "type": "toggle", "label": "Done", "field": "status", "onValue": "done", "offValue": "todo" },
+    "text":     { "type": "string", "label": "Task", "required": true },
+    "status":   { "type": "enum",   "label": "Status", "values": ["todo", "doing", "done"], "required": true },
+    "priority": { "type": "enum",   "label": "Priority", "values": ["urgent", "high", "medium", "low"] },
+    "dueDate":  { "type": "date",   "label": "Due" },
+    "note":     { "type": "markdown", "label": "Note" }
+  },
+  "displayField": "text",
+  "kanbanField": "status",
+  "calendarField": "dueDate",
+  "completionField": "status",
+  "completionDoneValues": ["done"],
+  "notifyWhen": { "field": "priority", "in": ["urgent", "high"] }
+}
+```
+Every key earns its place:
+| Key | What it gives the user |
+|---|---|
+| `done` (`toggle`) | The **checkbox** — in every table row and on every kanban card. Checking it sets `status` to `onValue`; the card jumps to the Done column. `offValue` is the status to return to on uncheck (your default open column). Both must be members of the `status` enum's `values`. |
+| `status` (`enum`) | The kanban columns and the single source of truth for "done". |
+| `kanbanField` | Pins the board to `status` (drag a card → writes `status`). |
+| `displayField` | Card / bell label (the task text, not the opaque id). |
+| `calendarField` | A due-date calendar view (only if you keep `dueDate`). |
+| `completionField` + `completionDoneValues` | The bell: fires while a todo is open, clears when `status` → `done`. |
+| `notifyWhen` | Fire the bell **only** for `urgent`/`high` priority (not every todo). Omit it to bell every open todo. |
+## SKILL.md
+`data/skills/todos/SKILL.md`:
+```markdown
+---
+name: todos
+description: The user's personal todo list. Use whenever they add, list, edit,
+  mark done, or remove a todo ("todo 追加", "やることリスト", "add a todo",
+  "what's on my list?", "mark X as done"). Records live at
+  `data/todos/items/<id>.json`; the user views them at `/collections/todos`.
+---
+# Todos (schema-driven collection)
+## Record shape
+- `id` — string, primary key (the filename). New items: `todo-<slug>` or
+  `todo-<YYYYMMDDHHmm>`.
+- `text` — the task line (required).
+- `status` — `todo` | `doing` | `done` (required). This IS the done state.
+- `priority` — `urgent` | `high` | `medium` | `low` (optional).
+- `dueDate` — `YYYY-MM-DD` (optional).
+- `note` — markdown (optional; URLs, context).
+- Do NOT write a `done` field — it's a projection of `status`.
+## What to do
+- **Add**: derive an id, default `status: "todo"`, Write the JSON.
+- **List**: read `data/todos/items/`, answer from the files; point the user at
+  `/collections/todos` rather than reciting the table.
+- **Mark done**: Read → set `status: "done"` → Write.
+- **Edit / Delete**: Read → mutate / remove the file (preserve untouched fields).
+- After a change, call `presentCollection` with slug `todos` (and the id) to show
+  it inline.
+```
+## A record on disk
+One JSON per item — note there is **no `done` key**:
+```json
+{ "id": "todo-buy-milk", "text": "Buy milk", "status": "todo", "priority": "high", "dueDate": "2026-06-10" }
+```
+## What the user gets, with zero host code
+- **Table** — a `done` checkbox per row (ticking it sets `status: "done"`), plus
+  inline `status` / `priority` dropdowns.
+- **Kanban** — columns from `status`; drag a card to move it, or tick its
+  per-card `done` checkbox (same write).
+- **Calendar** — todos on their `dueDate`.
+- **Bell** — fires for open `urgent`/`high` todos, clears on done / delete.
+## Options
+- **Reminder timing.** Add `"triggerField": "dueDate"` to hold the bell until the
+  due date instead of firing on create; add `"triggerLeadDays": 2` to fire it N
+  days early. `triggerField` must name a real `date` field.
+- **Notify on everything.** Drop `notifyWhen` to bell every open todo (not just
+  high priority).
+- **Severity color.** `notifyWhen` controls *whether* the bell fires, not its
+  color — the bell uses the standard severity; per-value red-vs-amber isn't
+  modelled.
+## Migrating the legacy `todo-plugin`
+Old records live at `data/plugins/%40mulmoclaude%2Ftodo-plugin/todos.json` (a
+single array) with the columns in the sibling `columns.json`. Convert them:
+1. **Columns → `status` values.** Use the `columns.json` ids as the `status`
+   enum `values` (keep the user's own columns — e.g.
+   `["todo", "mulmoclaude", "mag2", "done"]`). Set `completionDoneValues` to the
+   column whose `isDone` is `true`, and `kanbanField: "status"`.
+2. **Add the `done` toggle.** `onValue` = the done column, `offValue` = the
+   default open column (e.g. `"todo"`). **Do not skip this** — it's the checkbox
+   the legacy list had.
+3. **Fold `completed` into `status`.** A legacy `completed: true` item belongs in
+   the done column; don't carry a separate boolean.
+4. **One file per item.** Split the array into `data/todos/items/<id>.json`,
+   preserving each legacy `id` verbatim.
+5. **Convert `createdAt`.** The legacy value is Unix milliseconds — convert it to
+   a `YYYY-MM-DD` `date` field. Carry `priority`, `dueDate`, `note` straight
+   across.
+6. Leave the legacy plugin files in place (don't delete) unless the user asks.
+```