@mulmoclaude/core 5.0.0 → 5.1.0

package/assets/helps/error-recovery.md

@@ -400,11 +400,18 @@ quota / moderation rejection from that provider.
 
 The server appends the provider's own error to the message (e.g.
 `… — 401 Incorrect API key provided`) and logs it under the
-`mulmocast` prefix — read that detail first. Then either add the
-missing key to `.env` (restart the server) or rewrite the script's
-`imageParams` / `movieParams` / speaker providers to ones that have
-keys configured. Don't retry the render unchanged — the same provider
-will fail the same way.
+`mulmocast` prefix — read that detail first. Then either supply the
+missing key or rewrite the script's `imageParams` / `movieParams` /
+speaker providers to ones that have keys configured. Don't retry the
+render unchanged — the same provider will fail the same way.
+
+For `GEMINI_API_KEY`, tell the user to open **Settings → Gemini** and
+paste the key there: it takes effect immediately, with no restart and no
+file to locate, and it wins over a stale value in the shell or a `.env`
+(`config/helps/gemini.md`). The other providers' keys still come from a
+`.env` and need a restart. A render started BEFORE the key was saved
+keeps the environment it was spawned with, so re-run the render rather
+than resuming the old one.
 
 ## MulmoScript narration — wrong voice, ignored direction, or every beat re-recorded
 

package/assets/helps/gemini.md

@@ -36,24 +36,29 @@ The Gemini API has a **free tier that is sufficient for personal use**. Higher-v
 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. Create (or open) a `.env` file **in the directory you launch MulmoClaude from** — i.e. the directory where you run `npx mulmoclaude` (in a cloned repo, that's the repo root). Add the line:
+4. Open **Settings → Gemini**, paste the key into the field, and click Save. That is the whole step — it takes effect immediately, with no restart and no file to find.
 
-   ```dotenv
-   GEMINI_API_KEY=AIza…your-key…
-   ```
+   The key is written to `~/.mulmoclaude/secrets/GEMINI_API_KEY`, readable only by your user account. It is deliberately outside the `~/mulmoclaude` workspace, which the assistant manages.
 
-   The key stays in your launch directory, not in the `~/mulmoclaude` workspace (which is managed by the assistant). You can also just `export GEMINI_API_KEY=…` in your shell before launching — an exported value takes precedence over the `.env` file.
+### The `.env` route (still supported)
 
-5. Restart MulmoClaude so the new environment variable is picked up.
+A key in a `.env` file keeps working, and is the right choice for a scripted or CI setup. Add `GEMINI_API_KEY=AIza…` to:
+
+- **Started from the icon** (Finder / desktop shortcut): `~/.env`, in your home directory. An icon has no launch directory — macOS starts apps in `/` — so the app is started from home instead. A shell `export` does **not** work on this route: the launcher takes PATH from your login shell and nothing else, so nothing in `~/.zshrc` reaches the app.
+- **Started from a terminal** (`npx mulmoclaude`, or `yarn dev` in a clone): the directory you ran the command in. Here `export GEMINI_API_KEY=…` before launching works too.
+
+Either file needs a restart to be picked up — from the icon, stop the server first via Settings → SERVER → Quit, then click the icon again.
+
+**A key saved in Settings wins** over both the file and the shell. Settings → Gemini says which of the two is in effect, so a value you cannot find is still accounted for.
 
 ## 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.
+Settings → Gemini states whether a key is configured and where it came from. For an end-to-end 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: a `GEMINI_API_KEY not set — image / audio / video generation is unavailable` warning means the key was not found (missing, misread, or placed outside your launch directory).
+You can also inspect the server log on startup: a `GEMINI_API_KEY not set — image / audio / video generation is unavailable` warning means the key was not found. The warning names the exact `.env` path this launch reads, so a key that is set but in the wrong file shows up as a path you did not expect.
 
 ## 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.
+- The key stays on your machine — in `~/.mulmoclaude/secrets/` when saved from Settings, or in your own `.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/google-calendar-collection.md

@@ -106,6 +106,39 @@ Declaring it in `map` is a schema error.
 Use `datetime` (not `date`) for start/end when events have real clock times —
 the calendar day view then draws each record as a proportional time block.
 
+## All-day events
+
+A `datetime` column stores an all-day event as `2026-07-17T00:00`, because that
+is where the day view places it. That is fine for mirroring, but it is also
+exactly how a real midnight appointment is stored — so a record CREATED locally
+in a `datetime` column is pushed as a midnight event, never as an all-day one.
+
+For a calendar whose events are all-day, give start/end a **`date`** column
+instead. Google's bare date is then kept verbatim, and a record the user creates
+by typing two dates is pushed as a real all-day event.
+
+```jsonc
+"fields": {
+  "on":    { "type": "date", "label": "From" },
+  "until": { "type": "date", "label": "To" }
+},
+"googleCalendar": { "map": { "on": "start", "until": "end" } }
+```
+
+Google's all-day `end` is **exclusive** — it is the day AFTER the last day, so a
+single day on the 17th is `on: 2026-07-17`, `until: 2026-07-18`. Records
+mirrored from Google already carry it that way. Say so when the user asks why
+the end date "looks a day late"; do not offset it, because the push sends the
+stored value straight back.
+
+An existing all-day event stays all-day when its dates are edited, whatever the
+column type: the push reads what Google last reported for that event and keeps
+its kind. Only a record with no such history — one created locally — depends on
+the column type.
+
+To create a one-off all-day event without a collection, use the `google` tool's
+`calendarCreateEvent` with a bare date on both ends.
+
 ## When sync runs
 
 - **On creation** — the first sync starts as soon as the schema lands, so the
@@ -174,9 +207,11 @@ What the button does and deliberately does not do:
 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.
+  characters from `0-9a-v` (lower-case base32hex: digits plus `a`-`v`, so no
+  `w`-`z`, no upper case, no hyphen). 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, or by
+  choosing an id that satisfies the rule.
 - **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.

package/assets/helps/google.md

@@ -32,13 +32,23 @@ from `calendarListCalendars` — to target another.
 | `calendarColors` | Palettes mapping a `colorId` to hex, for events and for calendars |
 | `calendarListEvents` | Upcoming events. Optional `calendarId`, `timeMin`, `maxResults` (1-50, default 10) |
 | `calendarSync` | Only what CHANGED since the last sync, via a stored token. Returns counts plus a capped sample |
-| `calendarCreateEvent` | Create. Requires `summary`, `start`, `end`; optional `description`, `calendarId`, `colorId` |
+| `calendarCreateEvent` | Create, timed or all-day. Requires `summary`, `start`, `end`; optional `description`, `calendarId`, `colorId` |
 | `calendarUpdateEvent` | Edit in place. Requires `eventId` + at least one of `summary`, `start`, `end`, `description`, `colorId` |
 | `calendarDeleteEvent` | Delete. Requires `eventId` |
 
-**Date-times must carry a timezone offset** — `2026-07-17T09:00:00+09:00`, not
-`2026-07-17` and not `2026-07-17T09:00:00`. Calendar rejects the others with an
-opaque 400.
+**A timed event's ends must carry a timezone offset** —
+`2026-07-17T09:00:00+09:00`, not `2026-07-17T09:00:00`. Calendar rejects an
+offset-less value with an opaque 400. The same goes for `timeMin`.
+
+**An all-day event takes a bare date on BOTH ends** — `start: "2026-07-17"`,
+`end: "2026-07-18"`. Its `end` is **exclusive**: it is the day AFTER the last
+day, so a single day on the 17th ends on the 18th, and a three-day event
+starting the 17th ends on the 20th. This is Google's own convention and the
+values it reports back, so do not "correct" it.
+
+One end of each kind is rejected. Editing an all-day event needs **both** ends —
+a lone date is refused, because whether the stored event is all-day cannot be
+told from the argument.
 
 **Editing is a patch.** Fields you omit keep their current value, so changing a
 title needs `eventId` + `summary` and nothing else. `description: ""` clears the

package/dist/google/eventSpanInput.d.ts

@@ -0,0 +1,58 @@
+import { CalendarEventTime } from './calendar.js';
+/** Whether `value` is a bare calendar day — the all-day spelling of an event
+ *  time, and the one shape `isIsoDateTimeWithOffset` is built to refuse.
+ *
+ *  Realness comes from the parser the record lint, the calendar grid and the
+ *  push already share, so every surface agrees that `2026-02-30` is not a day.
+ *  The regex runs first because that parser trims, and a value with whitespace
+ *  around it would validate here and then reach Google verbatim. */
+export declare const isCalendarDateOnly: (value: string) => boolean;
+/** One end of a span, or null when it is neither shape Calendar accepts. */
+export declare const toEventTimeInput: (value: string) => CalendarEventTime | null;
+/** The rule every surface states for a value that is neither shape. Shared so
+ *  the tool, the remote host and their tests cannot drift apart. */
+export declare const EVENT_TIME_HINT = "must be an ISO 8601 date-time with a timezone offset (e.g. 2026-07-17T09:00:00+09:00), or a date for an all-day event (e.g. 2026-07-17)";
+/** The same rule with the offending key named, for a surface whose error text
+ *  carries no path of its own. */
+export declare const eventTimeHint: (key: string) => string;
+/** All-day `end` is exclusive, so a one-day event ends on the NEXT day. Spelled
+ *  out because the natural reading of "all day on the 17th" is `end` = the
+ *  17th, which Calendar refuses. */
+export declare const ALL_DAY_END_HINT = "an all-day `end` is EXCLUSIVE \u2014 it is the day AFTER the last day, so a single day on 2026-07-17 needs end 2026-07-18";
+export declare const MIXED_SPAN_HINT = "start and end must both be date-times with an offset, or both be dates for an all-day event \u2014 not one of each";
+/** A lone all-day end cannot be patched: the stored event's kind is unknown
+ *  here, and giving one end of a timed event a `date` makes an event Calendar
+ *  rejects — with a message that names neither end. Both together are
+ *  unambiguous, so that is what the caller is asked for. */
+export declare const LONE_ALL_DAY_HINT = "pass BOTH start and end to move an all-day event \u2014 an all-day `end` is EXCLUSIVE \u2014 it is the day AFTER the last day, so a single day on 2026-07-17 needs end 2026-07-18";
+export interface SpanTimes {
+    start: CalendarEventTime;
+    end: CalendarEventTime;
+}
+export type SpanResult = {
+    ok: true;
+    span: SpanTimes;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Both ends of a create, validated together.
+ *
+ *  Only the all-day ordering is checked: a timed span's ordering depends on the
+ *  two offsets, which Calendar resolves and reports on clearly, while an all-day
+ *  `end <= start` comes back as an opaque 400. Lexicographic comparison is exact
+ *  for `YYYY-MM-DD` — fixed-width, most significant part first. */
+export declare function resolveSpanInput(start: string, end: string): SpanResult;
+export interface PartialSpanTimes {
+    start?: CalendarEventTime;
+    end?: CalendarEventTime;
+}
+export type PartialSpanResult = {
+    ok: true;
+    times: PartialSpanTimes;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The span of an EDIT, where either end may be absent. */
+export declare function resolvePartialSpanInput(start: string | undefined, end: string | undefined): PartialSpanResult;

package/dist/google/index.cjs

@@ -45,6 +45,104 @@ var isIsoDateTimeWithOffset = (value) => {
 	return isRealCalendarDate(year, month, day) && timeInRange && offsetInRange;
 };
 //#endregion
+//#region src/google/eventSpanInput.ts
+var DATE_ONLY_RE$1 = /^\d{4}-\d{2}-\d{2}$/;
+/** Whether `value` is a bare calendar day — the all-day spelling of an event
+*  time, and the one shape `isIsoDateTimeWithOffset` is built to refuse.
+*
+*  Realness comes from the parser the record lint, the calendar grid and the
+*  push already share, so every surface agrees that `2026-02-30` is not a day.
+*  The regex runs first because that parser trims, and a value with whitespace
+*  around it would validate here and then reach Google verbatim. */
+var isCalendarDateOnly = (value) => DATE_ONLY_RE$1.test(value) && require_itemId.parseIsoDate(value) !== null;
+/** One end of a span, or null when it is neither shape Calendar accepts. */
+var toEventTimeInput = (value) => {
+	if (isCalendarDateOnly(value)) return { date: value };
+	return isIsoDateTimeWithOffset(value) ? { dateTime: value } : null;
+};
+/** The rule every surface states for a value that is neither shape. Shared so
+*  the tool, the remote host and their tests cannot drift apart. */
+var EVENT_TIME_HINT = "must be an ISO 8601 date-time with a timezone offset (e.g. 2026-07-17T09:00:00+09:00), or a date for an all-day event (e.g. 2026-07-17)";
+/** The same rule with the offending key named, for a surface whose error text
+*  carries no path of its own. */
+var eventTimeHint = (key) => `${key} ${EVENT_TIME_HINT}`;
+/** All-day `end` is exclusive, so a one-day event ends on the NEXT day. Spelled
+*  out because the natural reading of "all day on the 17th" is `end` = the
+*  17th, which Calendar refuses. */
+var ALL_DAY_END_HINT = "an all-day `end` is EXCLUSIVE — it is the day AFTER the last day, so a single day on 2026-07-17 needs end 2026-07-18";
+var MIXED_SPAN_HINT = "start and end must both be date-times with an offset, or both be dates for an all-day event — not one of each";
+/** A lone all-day end cannot be patched: the stored event's kind is unknown
+*  here, and giving one end of a timed event a `date` makes an event Calendar
+*  rejects — with a message that names neither end. Both together are
+*  unambiguous, so that is what the caller is asked for. */
+var LONE_ALL_DAY_HINT = `pass BOTH start and end to move an all-day event — ${ALL_DAY_END_HINT}`;
+var isAllDay = (time) => "date" in time;
+/** Both ends of a create, validated together.
+*
+*  Only the all-day ordering is checked: a timed span's ordering depends on the
+*  two offsets, which Calendar resolves and reports on clearly, while an all-day
+*  `end <= start` comes back as an opaque 400. Lexicographic comparison is exact
+*  for `YYYY-MM-DD` — fixed-width, most significant part first. */
+function resolveSpanInput(start, end) {
+	const startTime = toEventTimeInput(start);
+	if (startTime === null) return {
+		ok: false,
+		reason: eventTimeHint("start")
+	};
+	const endTime = toEventTimeInput(end);
+	if (endTime === null) return {
+		ok: false,
+		reason: eventTimeHint("end")
+	};
+	if (isAllDay(startTime) !== isAllDay(endTime)) return {
+		ok: false,
+		reason: MIXED_SPAN_HINT
+	};
+	if (isAllDay(startTime) && isAllDay(endTime) && endTime.date <= startTime.date) return {
+		ok: false,
+		reason: ALL_DAY_END_HINT
+	};
+	return {
+		ok: true,
+		span: {
+			start: startTime,
+			end: endTime
+		}
+	};
+}
+/** One end of an EDIT, where the other end is absent. */
+function resolveLoneEnd(key, value) {
+	const time = toEventTimeInput(value);
+	if (time === null) return {
+		ok: false,
+		reason: eventTimeHint(key)
+	};
+	if (isAllDay(time)) return {
+		ok: false,
+		reason: LONE_ALL_DAY_HINT
+	};
+	return {
+		ok: true,
+		times: { [key]: time }
+	};
+}
+/** The span of an EDIT, where either end may be absent. */
+function resolvePartialSpanInput(start, end) {
+	if (start !== void 0 && end !== void 0) {
+		const resolved = resolveSpanInput(start, end);
+		return resolved.ok ? {
+			ok: true,
+			times: resolved.span
+		} : resolved;
+	}
+	if (start !== void 0) return resolveLoneEnd("start", start);
+	if (end !== void 0) return resolveLoneEnd("end", end);
+	return {
+		ok: true,
+		times: {}
+	};
+}
+//#endregion
 //#region src/google/paths.ts
 /** Same directory as every other cross-app per-user file — see
 *  `../global-config/paths.ts`, which owns the spelling. */
@@ -2891,8 +2989,10 @@ async function deleteDriveFile(accessToken, input) {
 	await googleRequest(DRIVE_API_LABEL, accessToken, `${DRIVE_FILES_URL}/${encodeURIComponent(input.fileId)}`, { method: "DELETE" });
 }
 //#endregion
+exports.ALL_DAY_END_HINT = ALL_DAY_END_HINT;
 exports.CANCELLED_EVENT_STATUS = CANCELLED_EVENT_STATUS;
 exports.DEFAULT_LIST_MAX_RESULTS = DEFAULT_LIST_MAX_RESULTS;
+exports.EVENT_TIME_HINT = EVENT_TIME_HINT;
 exports.GOOGLE_AUTH_CANCELLED = GOOGLE_AUTH_CANCELLED;
 exports.GOOGLE_CALENDARLIST_SCOPE = GOOGLE_CALENDARLIST_SCOPE;
 exports.GOOGLE_CALENDAR_SCOPE = GOOGLE_CALENDAR_SCOPE;
@@ -2904,7 +3004,9 @@ exports.GoogleApiError = GoogleApiError;
 exports.HTTP_CONFLICT = HTTP_CONFLICT;
 exports.HTTP_FORBIDDEN = HTTP_FORBIDDEN;
 exports.HTTP_PRECONDITION_FAILED = HTTP_PRECONDITION_FAILED;
+exports.LONE_ALL_DAY_HINT = LONE_ALL_DAY_HINT;
 exports.MAX_LIST_RESULTS = MAX_LIST_RESULTS;
+exports.MIXED_SPAN_HINT = MIXED_SPAN_HINT;
 exports.PARTIAL_CALENDAR_WINDOW = PARTIAL_CALENDAR_WINDOW;
 exports.PROTECTION_UNKNOWN = PROTECTION_UNKNOWN;
 exports.PUSHABLE_SOURCE_FIELDS = PUSHABLE_SOURCE_FIELDS;
@@ -2950,6 +3052,7 @@ exports.deleteCalendarEvent = deleteCalendarEvent;
 exports.deleteDriveFile = deleteDriveFile;
 exports.deleteGoogleTokens = deleteGoogleTokens;
 exports.deleteTask = deleteTask;
+exports.eventTimeHint = eventTimeHint;
 exports.fieldText = fieldText;
 exports.findClientSecretPath = findClientSecretPath;
 exports.getCalendarColors = getCalendarColors;
@@ -2965,6 +3068,7 @@ exports.googleTokenPath = googleTokenPath;
 exports.groupByCalendar = groupByCalendar;
 exports.groupsNeedingBackfill = groupsNeedingBackfill;
 exports.heldBack = heldBack;
+exports.isCalendarDateOnly = isCalendarDateOnly;
 exports.isCalendarSyncDue = isCalendarSyncDue;
 exports.isClientSettableEventId = isClientSettableEventId;
 exports.isDeniedAccessRole = isDeniedAccessRole;
@@ -3006,6 +3110,8 @@ exports.readDriveFile = readDriveFile;
 exports.releaseOrphanedCalendarToken = releaseOrphanedCalendarToken;
 exports.reportedAccessRole = reportedAccessRole;
 exports.resolveEventSpan = resolveEventSpan;
+exports.resolvePartialSpanInput = resolvePartialSpanInput;
+exports.resolveSpanInput = resolveSpanInput;
 exports.resumableToken = resumableToken;
 exports.saveCalendarShadow = saveCalendarShadow;
 exports.saveCalendarSyncToken = saveCalendarSyncToken;
@@ -3024,6 +3130,7 @@ exports.toCollectionDateTime = toCollectionDateTime;
 exports.toCollectionRecord = toCollectionRecord;
 exports.toDriveFileSummary = toDriveFileSummary;
 exports.toEventSummary = toEventSummary;
+exports.toEventTimeInput = toEventTimeInput;
 exports.toGoogleEventTime = toGoogleEventTime;
 exports.toShadowEvent = toShadowEvent;
 exports.toTaskListSummary = toTaskListSummary;