@mulmoclaude/core 1.5.0 → 1.7.0

package/assets/helps/bug-report-faq.md

@@ -0,0 +1,130 @@
+# Bug-report FAQ — check these before calling it a bug
+
+This file is an **index, not an answer sheet**. It never states a value ("the default is off"), only
+where today's truth lives, because the agent reads the real thing at run time. Values rot silently;
+a config key or a file path cannot — rename one and the implementation stops working, so it gets
+fixed.
+
+Each entry's `configKey:` / `source:` / `help:` lines are **verified by CI**: a key that no longer
+exists, or a path that moved, fails the test rather than misleading a user months later.
+
+Read in this order, because only the first two are available to every user:
+
+1. **`configKey:`** — the live value, from `config/settings.json` in the workspace. Absent from the
+   file means the setting is at its default, which is the answer to most entries here.
+2. **`help:`** — another page in `config/helps/`, always present.
+3. **`source:`** — a path in the MulmoClaude **repository**. Only readable when running from a clone
+   (`yarn dev`); an `npx mulmoclaude` user has no repo, so never tell them to open one. It is listed
+   so CI can prove the pointer is still real, and for whoever ends up fixing the code.
+
+Entry format:
+
+```
+## The symptom, in the words a user would say
+
+configKey: <a key in config/settings.json>   (optional, repeatable)
+source: <path in the MulmoClaude repo>       (optional, repeatable)
+help: <another page in config/helps/>        (optional, repeatable)
+
+What to check. Never what the value is.
+```
+
+Maintained by hand, in the repo. This file is the source of truth; the issue tracker is the inbox.
+
+---
+
+## Voice input does nothing, or the mic button is disabled
+
+configKey: voiceInput
+source: packages/core/src/whisper
+help: error-recovery.md
+
+Read `voiceInput` from the live settings — a key absent from the file has never been touched, and
+turning it on is what triggers the model download. Three separate conditions gate the mic button:
+platform capability, the opt-in, and whether the model finished downloading. `GET /api/health`
+reports all three as `voiceInput`, so check it before deciding which one is missing — "on but still
+greyed out" is a different question from "never turned on".
+
+## I don't get a notification when a task finishes
+
+configKey: pushEnabled
+source: server/agent/webPush.ts
+help: remote-host.md
+
+Two conditions must hold at once, so read both before calling it a bug. `pushEnabled` in the live
+settings is the user's opt-in. The RemoteHost channel must also be connected — that connection is
+what supplies the Firebase auth, so with the phone link down the send is a no-op by design. A user
+who never connected a phone has nothing to receive the push regardless of the setting.
+
+## My chats never get titles or summaries
+
+configKey: chatIndex
+source: server/workspace/chat-index/indexer.ts
+
+Read `chatIndex` — it names the model the background summarizer spawns, and the summarizer does
+nothing until it does. One exception worth knowing before calling it a bug: sessions that didn't
+originate from the user (`system`, `scheduler`) are always skipped whatever the setting says, so a
+scheduled task's chat having no title is expected.
+
+## The journal / daily summary is empty
+
+configKey: journal
+source: server/workspace/journal/index.ts
+
+Read `journal` first — it gates the archivist that summarizes chat sessions into `journal/*.md`,
+and when it is not enabling a run the archivist short-circuits before the interval gate is even
+consulted. Neither the turn-end hook nor the hourly scheduled task will have written anything, so
+an empty journal is not evidence of a scheduler fault.
+
+## Gmail / Google Calendar / Notion tools don't show up for the agent
+
+configKey: extraAllowedTools
+source: server/agent/config.ts
+
+Connector tools reach the agent only when their MCP prefix is listed in `extraAllowedTools` — the
+list is appended to the base allowed-tools set on every spawn. Check the live value for the
+expected `mcp__…` prefix, and remember the connector must also be linked on the Claude side. A tool
+that is linked but unlisted is configuration, not a bug.
+
+## A skill I saved isn't callable
+
+source: server/workspace/hooks/handlers/skillBridge.ts
+source: server/workspace/skills/discovery.ts
+help: collection-skills.md
+
+Skills are authored at `data/skills/<slug>/SKILL.md` and mirrored into `.claude/skills/<slug>/` by a
+hook — agents must not write the latter directly. If the staging file exists but the mirror doesn't,
+the hook is the thing to look at. Bundled `mc-*` presets are a different case: they land in the
+catalog (`data/skills/catalog/preset/`) and are **not** active until the user stars one, so "the
+preset skill doesn't respond" is usually "it was never activated".
+
+## I edited an mc-* skill and my changes came back reverted
+
+source: packages/core/src/workspace-setup/sync.ts
+
+Working as designed: `mc-*` presets are launcher-managed factory defaults, refreshed from the
+shipped copy on every server boot so bug fixes and renames actually reach an already-starred copy.
+Any file it overwrites is first saved next to it as `<file>.bak.<timestamp>`, so the user's edits
+are recoverable — point them at that instead of re-typing. To keep changes permanently, copy the
+skill to a new non-`mc-` slug.
+
+## The agent can't use git / gh / ssh
+
+help: error-recovery.md
+help: sandbox.md
+
+The agent's Docker sandbox exposes no host SSH agent and no `gh` config unless the user opted them
+in at start-up. `GET /api/sandbox` reports whether the sandbox is active and which config mounts it
+was started with — read that rather than assuming either way. This is the single most common "it's
+broken" report and it is configuration. `error-recovery.md` has the exact flags and the
+verification commands; don't restate them from memory.
+
+## A collection's custom view is blank
+
+help: custom-view.md
+help: custom-view-remote.md
+
+Desktop and phone views have **incompatible runtime contracts** — a desktop view fetches its own
+records with an injected token, while a `target: "mobile"` view gets them over a postMessage bridge
+and cannot `fetch` at all. A view authored against the wrong contract renders empty with no error.
+Check which target it is registered as before treating it as a rendering fault.

package/assets/helps/error-recovery.md

@@ -1,10 +1,15 @@
-# Error recovery — when a tool call fails
+# Error recovery — when a tool call fails, or the user says something is broken
 
 This is the lookup the agent reads BEFORE asking the user a clarifying
 question or giving up on a failing tool call. Each section is keyed by
 the error message you'd see in tool output, with the cause and the
 documented fix.
 
+It has a second entry point. When the **user** reports that MulmoClaude is
+broken / weird / not working — nothing has failed in tool output, they are
+just describing a symptom — start at **§ The user says MulmoClaude is
+broken** below instead of scanning the error-keyed sections.
+
 Cite the section you used in your reply so the user can follow up
 (e.g. "Per `config/helps/error-recovery.md` § gh-auth / SSH …").
 
@@ -13,6 +18,134 @@ If no section here matches, list the workspace's other help files
 area (`sandbox.md`, `github.md`, `collection-skills.md`, etc.) before
 falling back to asking the user.
 
+## The user says MulmoClaude is broken
+
+**The goal is that the user ends up unblocked, not that an issue gets filed.**
+An issue is what's left after the first three steps fail to explain the
+behaviour. Work them in order and stop the moment the user is unblocked.
+
+Rules that hold in every step:
+
+- **Never assert "that's by design" from memory.** Say it only with a reason
+  attached: a config key, a help page, an implementation file.
+  `bug-report-faq.md` is an index of where to look — it deliberately contains
+  no values.
+- **Read the real thing.** Current values come from the workspace's
+  `config/settings.json` or `GET /api/health`, never from recollection.
+- **"I don't know" is an allowed answer.** If a step can't decide, say so and
+  go to the next one. Never close the conversation by guessing.
+- **Nothing leaves the machine before the user has seen it in full** and agreed.
+- Reply in the language the user writes in.
+
+### Step 1 — Hear the symptom (collect nothing yet)
+
+Call `presentForm` once with the questions below rather than asking in prose —
+a user who is already frustrated should be clicking, not composing.
+
+- **What kind** — display looks wrong / input doesn't work / the agent won't
+  answer / a tool keeps failing / phone or remote features / something else
+- **Where** — chat / a collection / the wiki / files / settings / the phone app
+- **How often** — every time / sometimes / once
+- **Since when** — after an update / it always did this / not sure
+- **What did you expect, and what happened instead?** (free text, required —
+  these two sentences are what the next step is judged against)
+
+### Step 2 — Is it configuration, or by design? (this is the actual job)
+
+1. Read `config/helps/bug-report-faq.md` and find the entry closest to the
+   symptom.
+2. Follow its pointers to the **real values** — `config/settings.json` for a
+   `configKey`, the named help page for a `help`. A setting absent from the file
+   is at its default, which is the answer to most entries there.
+3. If that explains the gap between expected and actual, **say why, show the
+   fix, and stop.** Cite what you checked.
+4. If nothing explains it, go to Step 3. Do not stretch a FAQ entry to cover a
+   symptom it doesn't cover.
+
+### Step 3 — Is it already known?
+
+Search the existing issues before opening anything:
+
+```bash
+gh issue list --repo receptron/mulmoclaude --state all --limit 20 --search "<symptom keywords>"
+```
+
+`gh` is **not available by default** — the agent runs in a credential-free
+sandbox (see § gh / git / SSH errors inside the sandbox). Don't spend turns
+fighting it: hand the user the search URL instead.
+
+`https://github.com/receptron/mulmoclaude/issues?q=voice+input+disabled` — build
+the `q=` value percent-encoded (space → `+` or `%20`, `#` → `%23`), or the link
+breaks on the first symptom that contains one.
+
+- **Closed and fixed** → compare their version against the release that fixed
+  it. If they're simply behind, tell them to update and stop.
+- **Open** → do not open a second one. Offer to add this user's environment and
+  repro steps as a comment; a second reproduction is worth more than a duplicate.
+- **Nothing found** → Step 4.
+
+### Step 4 — File it
+
+Only now collect details. Fetch the environment report from the server, from the
+workspace root:
+
+```bash
+curl -s -H "Authorization: Bearer $(cat .session-token)" \
+  "http://${MULMOCLAUDE_HOST:-127.0.0.1}:$(cat .server-port)/api/diagnostics/report"
+```
+
+Three parts of that command are load-bearing, and dropping any one returns
+nothing useful:
+
+- **The bearer header.** Every `/api/*` route requires it; without it the reply
+  is a 401, not a report. The token is regenerated each startup and lives in
+  `.session-token` at the workspace root.
+- **`$MULMOCLAUDE_HOST`.** In the default Docker sandbox `localhost` is the
+  container, not the machine running the server — the variable is set to
+  `host.docker.internal` there and unset on a host-mode run, hence the fallback.
+- **`.server-port`.** The port is chosen at startup; there is no fixed default
+  to hardcode.
+
+Keep the token inside the command substitution: never echo it, never let it
+reach the report body, and if you quote the command in the issue, quote it in
+the `$(cat …)` form above rather than with the value expanded.
+
+**The server does the redaction, not you.** It prints values only for
+allow-listed settings and withholds everything else, including the plaintext
+Google Maps key and every MCP server's `env` / `headers`. Paste what it returns
+verbatim — do not "help" by adding values you read elsewhere, and do not
+re-type a secret you happened to see in a file.
+
+Ask the user for what the host cannot see: the browser and its version, any red
+errors in the browser console, and a screenshot if the symptom is visual. Say
+before they attach one that a screenshot can carry file paths and chat text.
+
+Report body:
+
+```markdown
+## What happened
+## What I expected
+## Steps to reproduce
+1.
+## Environment
+(paste the diagnostics report here)
+## Attachments
+```
+
+Show the whole thing, get an explicit yes, then post it — `gh issue create
+--repo receptron/mulmoclaude --title "<title>" --body-file <file>` when `gh`
+works, otherwise print the markdown for copy-paste plus
+`https://github.com/receptron/mulmoclaude/issues/new`.
+
+### When Step 2 resolved it
+
+A question that took an agent to answer is a signal about the product: the UI
+failed to say something. Offer to post it as an issue titled with the question
+as the user asked it, noting what the answer turned out to be and **where it was
+checked**. Open the body with a line saying the answer came from this lookup and
+is awaiting maintainer review — it is a draft, not documentation. Never edit
+`bug-report-faq.md` yourself.
+
 ## gh / git / SSH errors inside the sandbox
 
 ### Symptoms

package/assets/helps/google-calendar-collection.md

@@ -6,10 +6,22 @@ events on a schedule and writes them as records — **without calling you**. No
 tool call, no tokens spent per sync, so hourly syncing is free.
 
 This is the mechanism for *keeping a collection fresh*. For one-off reads and
-for creating / editing / deleting events, use the `google` tool — see
+for deleting events, use the `google` tool — see
 [The `google` tool](google.md). There is no bundled calendar collection: you
 author the schema when the user asks for one.
 
+## Both directions, but only one of them automatic
+
+| Direction | How | When it runs |
+| --- | --- | --- |
+| Google → collection | the `googleCalendar` block | hourly, on creation, and on the **Sync** button |
+| collection → Google | the **Push to Google** button in the collection view | only when the user clicks it |
+
+There is no automatic write-back and no setting that enables one. If a user
+asks for "two-way sync", tell them plainly: the pull is automatic, the push is
+a button they press. Do not go looking for a config key for it — there isn't
+one, and hunting for it is what makes this conversation go in circles.
+
 ## Requirements
 
 The user's Google account must be linked (`google` tool, `kind: "status"`). If
@@ -81,8 +93,50 @@ the calendar day view then draws each record as a proportional time block.
   records on that first pass.
 
 Records are ordinary collection records: the user can open, filter, and view
-them like any other. Edits they make locally are overwritten the next time
-Google reports a change to that event.
+them like any other.
+
+## Pushing local work back — the Push to Google button
+
+The collection view has a **Push to Google** button next to Sync. It creates
+events for records added locally and updates events for records edited locally.
+
+**Order matters, and this is the one thing to warn users about.** A pull
+overwrites a locally edited record as soon as Google reports any change to that
+event. So: push first, then sync. Syncing first can discard the edit that was
+waiting to be pushed.
+
+What the button does and deliberately does not do:
+
+- **Creates** an event for a record that never came from a sync.
+- **Updates** only the fields the user actually changed, so attendees,
+  reminders and recurrence rules stay untouched.
+- **Never deletes.** A record deleted locally leaves its Google event alone —
+  a Google delete removes the event for every attendee and cannot be undone.
+  The count is reported so the user knows it was skipped; deleting for real is
+  the `google` tool's `calendarDeleteEvent`, after confirming with them.
+- **Skips a record edited on both sides** and reports it, rather than picking a
+  winner. The user resolves it by editing one side to match.
+- Pushes only `summary`, `start`, `end` and `colorId` — `htmlLink` and `status`
+  are read-only in Google, so a column mapped to either is ignored.
+
+Reasons a record can be reported as skipped:
+
+- **Its record id cannot be a Google event id.** Google requires 5-1024
+  characters from `0-9a-v`. Records created through the UI get a valid
+  generated id; a semantic id you authored (`team-standup`) cannot be used. Fix
+  by recreating the record without setting the primary field.
+- **No `start` / `end` is mapped, on a record being CREATED.** An event cannot
+  be created without a span. Editing an existing event is unaffected — a changed
+  title or colour is patched on its own.
+- **The calendar reports no timezone**, and the stored clock carries no offset
+  to fall back on.
+- **Clearing an event colour** — Google has no way to unset one.
+
+If the user only has `reader` access to the calendar, the whole push is refused
+with that reason rather than failing event by event. A calendar the user can
+reach by id but has not added to their calendar list has no role to check, so
+the push goes ahead and reports Google's own refusal if the write turns out not
+to be allowed — being unlisted is not treated as being read-only.
 
 ## Not for this
 

package/assets/helps/google.md

@@ -15,10 +15,11 @@ the original call — do not fall back to guessing.
 | --- | --- |
 | Read or change specific events / tasks / files, right now | this tool |
 | A collection that mirrors a calendar and keeps itself fresh | a `googleCalendar` block — see [Google Calendar sync](google-calendar-collection.md) |
+| Records the user added/edited in a calendar collection to reach Google | the collection view's **Push to Google** button, not this tool |
 
 The collection route costs no tokens per refresh, so prefer it for anything
-recurring. Use this tool for one-off work and for everything the collection
-route cannot do (creating, editing and deleting).
+recurring. Use this tool for one-off work, and for deleting — the push button
+never deletes.
 
 ## Calendar
 

package/assets/helps/index.md

@@ -67,7 +67,8 @@ See [Wiki](config/helps/wiki.md) for details on how it works.
 - [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
-- [Error recovery](config/helps/error-recovery.md) — the lookup the agent reads on tool failures (gh/git/SSH inside the sandbox, Marp PDF, registry import, build/workspace, plugin runtime) before asking the user
+- [Error recovery](config/helps/error-recovery.md) — the lookup the agent reads on tool failures (gh/git/SSH in the sandbox, Marp PDF, registry import, build/workspace, plugin runtime), plus the four-step triage for when a user reports something broken
+- [Bug-report FAQ](config/helps/bug-report-faq.md) — symptoms that turn out to be configuration or by design (voice input, push, chat titles, journal, connector tools, preset skills, custom views); says where to read the live value, never what it is
 - [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
 - [Remote host](config/helps/remote-host.md) — drive MulmoClaude from a phone at mulmoserver.web.app: Google sign-in connect, host online vs. offline (queued chats, 7-day expiry), photo attachments, and the security model
 - [Feeds](config/helps/feeds.md) — register a self-refreshing data feed (RSS/Atom/JSON) by authoring `feeds/<slug>/schema.json`: schema shape, the `ingest` block, raw-item field mapping, and `maxItems` retention