mulmoclaude 0.6.2 → 0.6.4

package/server/workspace/helps/encore-dsl.md

@@ -0,0 +1,482 @@
+# Encore — recurring obligations DSL
+
+Encore tracks recurring obligations (monthly payments, biannual taxes, annual physicals, daily check-ins) defined in a small YAML DSL. You — the LLM — compose the DSL document when the user describes an obligation, and call `defineEncore({ dsl })` to store it.
+
+Encore then:
+- Fires bell notifications at the right times based on `firingPlan` phases.
+- Bundles multi-target notifications into one bell entry (e.g. Isamu + Singularity Society both monthly, same deadline → one ding).
+- Escalates severity over time as deadlines approach.
+- Defers chat creation until the user clicks the bell — when they do, they land in a fresh chat with you, seeded with a prompt that names the obligation, the open targets, and the `pendingId` to pass back to `markStepDone` (or `markTargetSkipped` / `snooze`) for clearing.
+
+You never call `chat.start` directly for an obligation. The bell click handles that. You just close the loop on the resulting chat by calling `markStepDone` with the `pendingId` from the seed prompt.
+
+## Your end-to-end loop
+
+1. User describes a recurring obligation → you compose a DSL document → call `defineEncore({ dsl })` (no `obligationId` → setup).
+2. Encore fires bell notifications at the right times. You do NOT call `chat.start` — the host opens a fresh chat with you when the user clicks the bell, and seeds it with a prompt that names the obligation, the open targets, and a `pendingId`.
+3. In that seeded chat: converse with the user about the obligation, collect what they recorded, and call the matching action (`markStepDone` / `markTargetSkipped` / `recordValues` / `snooze`) passing the `pendingId`. That's the ONLY way the bell entry clears — there is no separate clear/dismiss action.
+4. Encore handles cycle recurrence: closing a cycle (all targets done or skipped) provisions the next cycle on the next tick. You don't need to do anything for that.
+
+## When to use this
+
+Whenever the user describes something that recurs and they want to be reminded about:
+- "I pay rent every month, due on the 1st" → monthly payment obligation
+- "Property tax is due twice a year on April 30 and November 30" → biannual payment
+- "I get an annual physical in May; I need to make the appointment in April" → annual service, two steps
+- "Take vitamins every day" → daily service
+- "Pay Isamu and Singularity Society both monthly on the 10th" → ONE obligation, TWO targets
+
+Compose the full DSL, then call `defineEncore({ dsl })` (no `obligationId` → setup path). Encore generates `id` (slugified from `displayName`) and `createdAt` server-side. To change an existing obligation later, call `defineEncore({ obligationId, dsl: { /* fields to change */ } })` — that's the amend path.
+
+## Top-level DSL shape
+
+```yaml
+version: 1
+displayName: "Daily payment — Hisayo"
+status: active                     # active | paused | retired (default: active)
+
+type: payment                      # payment | service
+currency: JPY                      # ISO 4217, REQUIRED iff type=payment, FORBIDDEN otherwise
+
+cadence:
+  type: daily                      # see Cadence below
+
+targets:                           # length >= 1
+  - id: hisayo                     # kebab-case slug, unique within obligation
+    displayName: "Hisayo"
+    defaults:                      # optional; pre-fills field values per cycle
+      method: Cash
+
+steps:                             # length >= 1
+  - id: pay                        # kebab-case slug, unique within obligation
+    displayName: "Pay"
+    deadline: cycle-deadline       # at-expression (see below)
+    firingPlan:
+      - at: cycle-start            # at-expression
+        severity: info             # info | warning | urgent
+    fields: [amount, method, paidOn]  # subset of formSchema field names
+
+formSchema:                        # input grammar for per-cycle values
+  fields:
+    - name: amount                 # camelCase or kebab-case
+      type: number                 # string | text | url | email | date | number | boolean | enum
+      label: "Amount paid (JPY)"
+      required: true
+    - name: method
+      type: string
+      label: "Payment method"
+    - name: paidOn
+      type: date
+      label: "Payment date"
+
+carryForward:                      # optional
+  body: empty                      # empty | copy (default: empty)
+```
+
+Cross-field rules (validator will reject otherwise):
+- `currency` required iff `type` is `payment`.
+- `targets[].id`, `steps[].id`, `formSchema.fields[].name` are each unique within their list.
+- Every `formSchema` field name must be claimed by **exactly one** step's `fields[]` — no orphans, no double-claims.
+- `targets[].defaults` keys must reference real `formSchema` field names.
+- `firingPlan` phases must resolve in chronological order (Encore evaluates them in declared order).
+- `defineEncore` amend cannot change `type`, `currency`, or `cadence.type` — those changes invalidate cycle-file naming or prior records. Path: retire + create new.
+
+## Cadence
+
+```yaml
+cadence: { type: annual,   cycles: [{ month: 5, day: 28 }] }
+cadence: { type: biannual, cycles: [{ month: 4, day: 28 }, { month: 11, day: 28 }] }
+cadence: { type: monthly,  day: 10 }
+cadence: { type: weekly,   dayOfWeek: friday }  # mon|tue|wed|thu|fri|sat|sun
+cadence: { type: daily }
+```
+
+- `month` is 1–12, `day` is 1–28 (capped to dodge February).
+- `biannual` cycles must be in calendar order (first slot before second).
+- Cycle file naming: `<year>.md` (annual), `<year>-h{1,2}.md` (biannual), `<year>-MM.md` (monthly), `<year>-Www.md` (weekly), `YYYY-MM-DD.md` (daily).
+
+## `at` expressions (firingPlan & step.deadline)
+
+Grammar: `anchor [±N d]` where anchor is one of:
+- `cycle-start` — first day of the cycle
+- `cycle-deadline` — the cycle's natural deadline
+- `step-deadline` — this step's resolved deadline (ONLY valid inside the same step's `firingPlan`)
+- `schedule:YYYY-MM-DD` — absolute date
+
+Examples:
+- `cycle-start` — fire on day 1
+- `cycle-deadline-21d` — three weeks before deadline
+- `step-deadline+1d` — one day after the step's deadline (e.g. for an "overdue" escalation)
+- `schedule:2026-02-01` — absolute
+
+Days only — no `w` / `m`. Compute the math yourself.
+
+## Severity
+
+Three severities: `info`, `warning`, `urgent`. They drive the bell's visual prominence and the escalation log; the LLM also reads severity from the seed prompt and adjusts tone in conversation. Phases must be chronologically ordered but severities can be non-monotonic (rare).
+
+## Two MCP tools — defineEncore vs manageEncore
+
+Encore exposes two MCP tools that share the same `/api/encore` endpoint:
+
+- **`defineEncore`** — compose a new DSL document, or amend an existing one. Use this for ANY structural change (creating an obligation, renaming it, changing the firingPlan, adding a target, etc.).
+- **`manageEncore`** — operational kinds only: `markStepDone` / `markTargetSkipped` / `recordValues` / `query` / `appendNote` / `snooze` / `unsnooze`. Use these after the obligation exists, typically in the chat seeded by a bell click.
+
+The split exists so the `defineEncore` tool can carry a fully typed JSON Schema for the `dsl` argument (you'll see field names, types, and oneOf branches in the tool definition), while `manageEncore` stays a thin discriminator on short flat arguments.
+
+## defineEncore — setup or amend
+
+Discriminator: **`obligationId` presence**.
+
+- Absent → setup (server generates the id from `displayName`).
+- Present → amend the named obligation.
+
+This way the parameter shape carries the intent — no separate `kind: "setup" | "amend"` flag inside the tool.
+
+### setup — create a new obligation
+
+```json
+{
+  "kind": "defineEncore",
+  "dsl": {
+    "version": 1,
+    "displayName": "Daily check-in",
+    "type": "service",
+    "cadence": { "type": "daily" },
+    "targets": [{ "id": "me", "displayName": "Me" }],
+    "steps": [
+      {
+        "id": "checkin",
+        "displayName": "Check in",
+        "deadline": "cycle-deadline",
+        "firingPlan": [{ "at": "cycle-start", "severity": "info" }],
+        "fields": ["note"]
+      }
+    ],
+    "formSchema": {
+      "fields": [
+        { "name": "note", "type": "text", "label": "Notes", "required": false }
+      ]
+    }
+  }
+}
+```
+
+Returns `{ ok: true, obligationId, cycleId, cyclePath, indexPath }`. Encore writes `obligations/<id>/index.md` plus the first cycle file and reconciles (so a `cycle-start` phase fires immediately).
+
+`dsl` is normally an **OBJECT** in the tool-call arguments. The handler also accepts a JSON-encoded string (it calls `JSON.parse` on the string before validating) so a `JSON.stringify`'d dsl won't error — but the object form is preferred.
+
+#### Obligation with nothing to record (placeholder field)
+
+The DSL requires **every obligation to have at least one formSchema field, and every formSchema field to be claimed by exactly one step.** For a "did I do it?" obligation that captures no real data, declare a single placeholder field (typical names: `note`, `done`, `time`) and claim it from your only step — exactly as the example above does.
+
+You **cannot** combine `step.fields: []` with `formSchema.fields: []` to opt out — `formSchema.fields` has `.min(1)` and `formSchema` is required. The LLM-trap to avoid:
+
+```json
+// ❌ FAILS: orphan field
+"steps": [{ "id": "shower", "fields": [], ... }],
+"formSchema": { "fields": [{ "name": "note", "type": "text", "label": "Notes" }] }
+
+// ❌ FAILS: empty array (formSchema.fields requires ≥1)
+"steps": [{ "id": "shower", "fields": [], ... }],
+"formSchema": { "fields": [] }
+
+// ✅ WORKS: placeholder claimed by the step
+"steps": [{ "id": "shower", "fields": ["note"], ... }],
+"formSchema": { "fields": [{ "name": "note", "type": "text", "label": "Notes", "required": false } ] }
+```
+
+If you hit "field X is not claimed by any step.fields[]", the fix is to **add** the field name to one step's `fields[]`, NOT to remove it from `formSchema`.
+
+### setup — 409 collision behavior
+
+If `slugify(dsl.displayName)` matches an existing obligation, the server rejects with `409 Conflict` and a recovery directive:
+
+> Obligation "daily-payment-hisayo" already exists (displayName: "Daily payment — Hisayo"). To modify it, call defineEncore with obligationId: "daily-payment-hisayo" (this becomes an amend). To create a parallel obligation, change the displayName.
+
+Read the message — it tells you the id to pass for amend. Don't auto-disambiguate by appending suffixes; the user almost always wants one of: (a) you forgot `obligationId` and meant amend, or (b) you genuinely want a new obligation under a different name.
+
+### amend — change one or more fields
+
+```json
+{
+  "kind": "defineEncore",
+  "obligationId": "daily-payment-hisayo",
+  "dsl": { "displayName": "Daily payment — Hisayo San" }
+}
+```
+
+For amend, only fill the fields you want to change — the server shallow-merges onto the existing DSL. Array fields (`targets`, `steps`, `formSchema.fields`, `firingPlan`) replace whole; if you want to add a new step, send the full new `steps` array (existing + new).
+
+Cannot change `type` / `currency` / `cadence.type` — those are immutable. Path: retire the old obligation, create a new one.
+
+Encore clears active bell entries on amend and re-fires with the new title/text.
+
+#### Merge semantics — what "shallow merge at the top level" means
+
+Each top-level key you include is OVERWRITTEN whole on the stored DSL. Keys you omit are PRESERVED. There is no per-field merge inside an object or array — you're either replacing the whole top-level value or leaving it alone.
+
+| Top-level key | Type | What "amend it" means |
+|---|---|---|
+| `displayName`, `status`, `currency` (read-only via amend) | scalar | Replaced by the value you send. |
+| `cadence` | object | Replaced whole. Re-send all required cadence fields, except `cadence.type` (immutable). |
+| `targets` | array | Replaced whole. Send the FULL desired list — old entries you omit are gone. |
+| `steps` | array | Replaced whole. Same rule — old steps you omit are gone, and their per-step `firingPlan` goes with them. |
+| `formSchema` | object | Replaced whole. `formSchema.fields` (array) is part of that. |
+
+Note that there is NO deep-merge inside `targets[i]`, `steps[i]`, or `firingPlan[i]`. To change one step's `firingPlan`, you re-send the whole step (including the unchanged fields), inside the full `steps` array (including the unchanged steps).
+
+#### Worked example — add a target without losing the existing ones
+
+Existing DSL has `targets: [hisayo, kenta]`. To add `mei`, send the full new list:
+
+```json
+{
+  "kind": "defineEncore",
+  "obligationId": "daily-payment-hisayo",
+  "dsl": {
+    "targets": [
+      { "id": "hisayo", "displayName": "Hisayo" },
+      { "id": "kenta", "displayName": "Kenta" },
+      { "id": "mei", "displayName": "Mei" }
+    ]
+  }
+}
+```
+
+Sending only `{ targets: [{ id: "mei", ... }] }` would DROP hisayo and kenta — the array replaces whole, it does not append.
+
+#### Worked example — change one step's firingPlan without touching others
+
+Existing DSL has `steps: [pay, confirm]`, and you want to change `pay.firingPlan` only. Re-send the full steps array, with the full `pay` step (including the new `firingPlan`) and the full unchanged `confirm` step:
+
+```json
+{
+  "kind": "defineEncore",
+  "obligationId": "daily-payment-hisayo",
+  "dsl": {
+    "steps": [
+      {
+        "id": "pay",
+        "displayName": "Pay",
+        "deadline": "cycle-deadline",
+        "fields": ["amount"],
+        "firingPlan": [
+          { "at": "cycle-deadline-3d", "severity": "info" },
+          { "at": "cycle-deadline", "severity": "urgent" }
+        ]
+      },
+      {
+        "id": "confirm",
+        "displayName": "Confirm receipt",
+        "deadline": "cycle-deadline+1d",
+        "fields": [],
+        "firingPlan": [{ "at": "cycle-deadline+1d", "severity": "info" }]
+      }
+    ]
+  }
+}
+```
+
+You CANNOT send `{ steps: [{ id: "pay", firingPlan: [...] }] }` and expect the server to find the `pay` step and patch only its `firingPlan` — the whole `steps` array replaces, and `confirm` would be lost.
+
+#### Worked example — partial cadence update
+
+`cadence.type` is immutable, but its sibling fields (e.g. `day` on monthly, `dayOfWeek` on weekly, the `cycles` list on annual / biannual) are amendable. Re-send the full cadence object with the new value plus the unchanged `type`:
+
+```json
+{
+  "kind": "defineEncore",
+  "obligationId": "monthly-rent",
+  "dsl": { "cadence": { "type": "monthly", "day": 5 } }
+}
+```
+
+Sending `{ cadence: { day: 5 } }` (without `type`) will 400 with a Zod error — cadence is replaced whole, so the required discriminator field must be present.
+
+#### When NOT to use amend
+
+`type`, `currency` (for `type: "payment"`), and `cadence.type` are immutable — amend will 400. The path is retire-and-create: set `status: "retired"` (or `"paused"`) on the old obligation, then `defineEncore` (no `obligationId`) a new one with the desired type / currency / cadence-type. Bells on the old obligation clear automatically when status leaves `active`.
+
+## manageEncore call shapes
+
+Every operational action takes a `kind` discriminator. The handler validates the rest with Zod and 400s on shape mistakes — read the error message; it names the field.
+
+For composing a NEW obligation or amending an existing one's DSL, use the sibling `defineEncore` tool documented above — that's structural, not operational, and lives outside `manageEncore`.
+
+### markStepDone — CLOSE ONE STEP ON ONE TARGET
+
+```json
+{
+  "kind": "markStepDone",
+  "pendingId": "<from the seed prompt>",
+  "obligationId": "daily-payment-hisayo",
+  "cycleId": "2026-05-16",
+  "targetId": "hisayo",
+  "stepId": "pay",
+  "values": { "amount": 5000, "paidOn": "2026-05-16" }
+}
+```
+
+**Common mistakes the parser will 400 on:**
+- `targetIds: ["hisayo"]` — WRONG. Use singular `targetId: "hisayo"` (string). If the bell covered multiple targets, call `markStepDone` once per target.
+- `values: { "hisayo": { "amount": 5000 } }` — WRONG. `values` is a flat field-map keyed by field name: `{ "amount": 5000, "paidOn": "..." }`. Never nest under target id.
+- Missing `pendingId` when called in response to a bell click — the bell entry won't clear without it.
+
+### markTargetSkipped
+
+```json
+{ "kind": "markTargetSkipped", "pendingId": "...", "obligationId": "...", "cycleId": "...", "targetId": "hisayo" }
+```
+
+Marks one target skipped for this cycle. Remaining targets still need their own close.
+
+### recordValues
+
+```json
+{ "kind": "recordValues", "obligationId": "...", "cycleId": "...", "targetId": "...", "values": { "amount": 5000 } }
+```
+
+Writes partial values without closing the step. Use when the user has reported partial info (invoice received but not yet paid).
+
+### snooze
+
+```json
+{ "kind": "snooze", "pendingId": "...", "obligationId": "...", "cycleId": "...", "targetId": "...", "stepId": "..." }
+```
+
+Clears the current bell entry and persists a `snoozedSteps[stepId]` marker (24h by default) on the cycle file. The reconciler skips this step until the snooze timestamp passes; after that, the next reconcile re-fires from the current phase.
+
+### unsnooze
+
+```json
+{ "kind": "unsnooze", "obligationId": "...", "cycleId": "...", "targetId": "...", "stepId": "..." }
+```
+
+Inverse of `snooze`. Deletes `snoozedSteps[stepId]` from the target's record. If the step is otherwise eligible to fire (not closed, current phase past), the bell republishes in the same turn — no need to wait for the 24h timer or run a tick manually. A no-op if the step wasn't snoozed.
+
+### query
+
+```json
+{ "kind": "query", "obligationId": "daily-payment-hisayo", "range": "all" }
+```
+
+`range` is `"current"` (default, last cycle only), `"all"` (every cycle ever), or a number (last N cycles). Omit `obligationId` to query every obligation. Response includes each cycle's `path` so you can deep-read the raw markdown for further analysis.
+
+### appendNote
+
+```json
+{ "kind": "appendNote", "obligationId": "...", "cycleId": "2026-05-16", "body": "Note appended here" }
+```
+
+Omit `cycleId` to append to the obligation's index.md body (long-lived notes); include it to append to a specific cycle's body (per-cycle scratch).
+
+## Three worked examples
+
+### 1. Monthly payments, two targets, bundled notification
+
+```yaml
+version: 1
+displayName: "Monthly payments (due 10th)"
+type: payment
+currency: JPY
+cadence:
+  type: monthly
+  day: 10
+targets:
+  - id: isamu
+    displayName: "Isamu"
+    defaults:
+      amount: 15000
+  - id: singularity-society
+    displayName: "Singularity Society"
+steps:
+  - id: pay
+    displayName: "Pay"
+    deadline: cycle-deadline
+    firingPlan:
+      - { at: cycle-start, severity: info }
+      - { at: cycle-deadline-3d, severity: warning }
+      - { at: cycle-deadline+1d, severity: urgent }
+    fields: [invoiceReceivedOn, amount, paidOn]
+formSchema:
+  fields:
+    - { name: invoiceReceivedOn, type: date, label: "Invoice received on" }
+    - { name: amount, type: number, label: "Amount paid (JPY)", required: true }
+    - { name: paidOn, type: date, label: "Payment date" }
+```
+
+When the cycle fires, one bell entry covers both targets. The seeded chat lists both; close them with two `markStepDone` calls (one per `targetId`).
+
+### 2. Biannual real estate tax with escalation
+
+```yaml
+version: 1
+displayName: "Real estate tax — Hayama"
+type: payment
+currency: JPY
+cadence:
+  type: biannual
+  cycles:
+    - { month: 4, day: 28 }
+    - { month: 11, day: 28 }
+targets:
+  - id: hayama-house
+    displayName: "Hayama house"
+steps:
+  - id: pay
+    displayName: "Pay"
+    deadline: cycle-deadline
+    firingPlan:
+      - { at: cycle-deadline-21d, severity: info }
+      - { at: cycle-deadline-3d, severity: warning }
+      - { at: cycle-deadline+1d, severity: urgent }
+    fields: [invoiceReceivedOn, amount, paidOn]
+formSchema:
+  fields:
+    - { name: invoiceReceivedOn, type: date, label: "Invoice received on" }
+    - { name: amount, type: number, label: "Amount paid (JPY)", required: true }
+    - { name: paidOn, type: date, label: "Payment date" }
+```
+
+### 3. Annual physical, multi-step
+
+```yaml
+version: 1
+displayName: "Annual physical"
+type: service
+cadence:
+  type: annual
+  cycles:
+    - { month: 5, day: 28 }
+targets:
+  - id: satoshi
+    displayName: "Satoshi"
+steps:
+  - id: make-appointment
+    displayName: "Make appointment"
+    deadline: cycle-deadline-30d
+    firingPlan:
+      - { at: step-deadline-14d, severity: info }
+      - { at: step-deadline, severity: warning }
+    fields: []
+  - id: doctor-visit
+    displayName: "Doctor visit"
+    deadline: cycle-deadline
+    firingPlan:
+      - { at: step-deadline-3d, severity: info }
+    fields: [visitDate, doctorName, notes]
+formSchema:
+  fields:
+    - { name: visitDate, type: date, label: "Visit date" }
+    - { name: doctorName, type: string, label: "Doctor name" }
+    - { name: notes, type: text, label: "Notes" }
+```
+
+Two independent steps with separate deadlines. `step-deadline` inside a step's `firingPlan` refers to that step's own deadline. Closing `make-appointment` leaves `doctor-visit` still open until its own phase fires.
+
+## Operational notes
+
+- Encore data lives under `~/mulmoclaude/data/plugins/encore/`. Each obligation is a folder with `index.md` (the DSL + free-form body) and one markdown file per cycle.
+- The bell entry for an obligation is action-lifecycle — clicking it lands the user in a seeded chat, but does NOT clear the bell. You clear it by closing the underlying step via `markStepDone` (or `markTargetSkipped` / `snooze`).
+- The tick is hourly. State-mutating handlers (`defineEncore`, `markStepDone`, `snooze`, …) reconcile after persisting, so newly-due notifications surface within the same SSE turn.

package/server/workspace/helps/index.md

@@ -35,21 +35,23 @@ Under the hood it uses the Claude Code Agent SDK as its LLM core. Claude has ful
 
 The wiki (`wiki/` in the workspace) acts as Claude's long-term memory. Unlike the conversation history which resets each session, the wiki is a persistent, compounding knowledge base that Claude builds and maintains over time. You feed it sources — articles, URLs, notes — and Claude ingests them into structured, interlinked Markdown pages. The more you add, the smarter it gets.
 
-See [Wiki](helps/wiki.md) for details on how it works.
+See [Wiki](config/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
-- [Storyteller Template](helps/storyteller.md) — MulmoScript template and rules for character-driven narrated stories in the Storyteller role
-- [Guide & Planner Templates](helps/guide.md) — document structures and form-field hints per guide type for the Guide & Planner role
-- [Spreadsheet](helps/spreadsheet.md) — cell format, formulas, date handling, and format codes for the presentSpreadsheet plugin
-- [presentHtml](helps/presenthtml.md) — self-contained HTML rules and the three-`../` relative-path convention used by the presentHtml plugin to keep generated files portable under `file://`
-- [Sandbox](helps/sandbox.md) — how the Docker sandbox isolates the agent, what it can access, and how to disable it
-- [Telegram Bridge](helps/telegram.md) — how to talk to MulmoClaude from the Telegram app: creating a bot, starting the bridge, allowlisting chat IDs, commands, and troubleshooting
-- [Information Sources](helps/sources.md) — registering RSS feeds / GitHub repos / arXiv queries, the daily-brief pipeline, and where its files live on disk
+- [Wiki](config/helps/wiki.md) — how the personal knowledge wiki works, its folder layout, page format, and operations
+- [Gemini API Key](config/helps/gemini.md) — why `GEMINI_API_KEY` is strongly recommended (images, audio, video) and how to get one from Google AI Studio
+- [MulmoScript](config/helps/mulmoscript.md) — format reference for authoring multimedia stories: beats, image types, speech, audio, and a minimal example
+- [Business Presentation Template](config/helps/business.md) — MulmoScript template and rules for business presentations in the Office role
+- [Storyteller Template](config/helps/storyteller.md) — MulmoScript template and rules for character-driven narrated stories in the Storyteller role
+- [Guide & Planner Templates](config/helps/guide.md) — document structures and form-field hints per guide type for the Guide & Planner role
+- [Spreadsheet](config/helps/spreadsheet.md) — cell format, formulas, date handling, and format codes for the presentSpreadsheet plugin
+- [presentHtml](config/helps/presenthtml.md) — self-contained HTML rules and the three-`../` relative-path convention used by the presentHtml plugin to keep generated files portable under `file://`
+- [Sandbox](config/helps/sandbox.md) — how the Docker sandbox isolates the agent, what it can access, and how to disable it
+- [Telegram Bridge](config/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](config/helps/sources.md) — registering RSS feeds / GitHub repos / arXiv queries, the daily-brief pipeline, and where its files live on disk
+- [Encore — recurring obligations DSL](config/helps/encore-dsl.md) — YAML DSL for recurring obligations (payments, services, check-ins), firing plans, multi-target bundles, and the bell-click resume loop
+- [GitHub repositories in the workspace](config/helps/github.md) — clone-destination rules under `github/<name>/` and how to handle existing directories with matching or different remotes
 
 ## Workspace Layout
 
@@ -60,6 +62,6 @@ See [Wiki](helps/wiki.md) for details on how it works.
   calendar/      ← calendar events
   contacts/      ← address book
   wiki/          ← personal knowledge wiki (long-term memory)
-  helps/         ← help pages (synced from app on every start)
+  config/helps/  ← help pages (synced from app on every start)
   memory.md      ← distilled facts loaded into every session
 ```

package/server/workspace/helps/mulmoscript.md

@@ -11,8 +11,8 @@ MulmoScript files are rendered in the canvas. The underlying engine is [mulmocas
 | Purpose | Provider | Example config |
 |---|---|---|
 | TTS (speech) | `gemini` | `"provider": "gemini", "voiceId": "Kore"` |
-| Image generation | `google` | `"provider": "google", "model": "gemini-2.5-flash-image"` |
-| Video generation | `google` | `"provider": "google", "model": "veo-2.0-generate-001"` |
+| Image generation | `google` | `"provider": "google", "model": "gemini-3.1-flash-image-preview"` |
+| Video generation | `google` | `"provider": "google", "model": "veo-3.1-generate"` |
 
 Do not use `openai`, `elevenlabs`, or other providers — they are not configured in this app.
 
@@ -225,7 +225,7 @@ Control BGM and volume mixing.
       "Presenter": { "provider": "gemini", "voiceId": "Kore", "displayName": { "en": "Presenter" } }
     }
   },
-  "imageParams": { "provider": "google", "model": "gemini-2.5-flash-image" },
+  "imageParams": { "provider": "google", "model": "gemini-3.1-flash-image-preview" },
   "beats": [
     {
       "speaker": "Presenter",

package/server/workspace/helps/sandbox.md

@@ -23,11 +23,11 @@ The container runs with `--cap-drop ALL` and as the host user's UID/GID, so it h
 
 ## Disabling the Sandbox
 
-Set the environment variable `DISABLE_SANDBOX=1` to always run the agent directly on the host, even when Docker is available.
+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.
+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.

package/server/workspace/hooks/dispatcher.ts

@@ -6,11 +6,13 @@
 // settings.json never changes.
 //
 // THIS FILE IS THE SOURCE OF TRUTH. Edits here, then run
-// `yarn build:hooks` (or `yarn build`) to regenerate `./dispatcher.mjs`.
-// The bundled `.mjs` is committed to git so `provision.ts` can read
-// it at server startup without invoking esbuild on the runtime path.
-// CI runs `yarn build:hooks && git diff --exit-code` to catch a
-// stale bundle.
+// `yarn build:hooks` (or `yarn build`) to regenerate the bundle at
+// `server/build/dispatcher.mjs` (generated output is kept out of the
+// source tree). The bundled `.mjs` is committed to git so
+// `provision.ts` can read it at server startup without invoking
+// esbuild on the runtime path. CI's "Verify built hook bundle"
+// step runs `git diff --exit-code` on the committed bundle to catch
+// a stale commit.
 //
 // The hook executes inside Claude CLI's process space — must be a
 // self-contained ESM bundle. esbuild rolls every import (handlers,

package/server/workspace/hooks/provision.ts

@@ -33,12 +33,15 @@ import { errorMessage } from "../../utils/errors.js";
 // The esbuild bundle is the source of truth for the dispatcher
 // script written into <workspace>/.claude/hooks/. Source TS is
 // `dispatcher.ts`; `yarn build:hooks` (chained from `yarn build`)
-// regenerates `dispatcher.mjs`, and CI fails when the committed
-// bundle drifts from the source. The read happens inside
+// regenerates the bundle at `server/build/dispatcher.mjs` (generated
+// output is kept out of the source tree). The read happens inside
 // `provisionDispatcherHook` (not at module load) so a missing /
 // unreadable bundle degrades to a logged warning without breaking
 // server startup.
-const DISPATCHER_BUNDLE_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "dispatcher.mjs");
+//
+// This module lives at server/workspace/hooks/provision.ts, so
+// `../../build/dispatcher.mjs` resolves to server/build/dispatcher.mjs.
+const DISPATCHER_BUNDLE_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "build", "dispatcher.mjs");
 
 function readDispatcherBundle(): string | null {
   try {

package/server/workspace/paths.ts

@@ -12,10 +12,9 @@
 //   artifacts/       LLM-generated (charts, html, images, documents,
 //                    spreadsheets, stories, news)
 //
-// Existing workspaces need the one-shot `scripts/migrate-workspace-284.ts`
-// script run before first startup with this code. `server/workspace.ts`
-// detects the pre-migration layout at boot and aborts with a pointer
-// to the script.
+// Pre-#284 workspaces (with `chat/`, `summaries/`, `memory.md` at the
+// root) continue to boot — the modern layout above is what new
+// installs use, but the older directory names are still accepted.
 //
 // When adding a new top-level directory: add the name to the
 // `WORKSPACE_DIRS` record below. The absolute path is derived
@@ -154,6 +153,16 @@ const HOST_WORKSPACE_DIRS = {
   // so server code references it through `WORKSPACE_PATHS.claudeSkills`
   // instead of inlining the string.
   claudeSkills: ".claude/skills",
+  // Skill catalog root (#1335). Holds preset skills shipped with the
+  // launcher (`catalog/preset/`) and — in later PRs — git-synced
+  // Anthropic skills (`catalog/anthropic/`) and community URL-install
+  // entries (`catalog/community/`). Entries here are catalog-only:
+  // visible to UI / tooling but NOT discovered by Claude Code's
+  // slash-command resolver. An entry becomes active by being copied
+  // (or symlinked) into `.claude/skills/`. The catalog vs active
+  // split keeps unused skills out of the system prompt.
+  skillsCatalog: "data/skills/catalog",
+  skillsCatalogPreset: "data/skills/catalog/preset",
   // Nested subdirs inside a top-level grouping. Kept here (rather
   // than module-local constants) when multiple modules need to
   // reference the same nested path — e.g. wiki/pages/ is used by