@mgcrea/mcp-apple-calendar 0.0.0-bootstrap → 1.3.1

package/dist/{server-B2HtiXLF.js → server-DoSfe1y7.js}

@@ -1,4 +1,4 @@
-import { AppBusyError as CalendarBusyError, AppNotRunningError as CalendarNotRunningError, AppleAutomationError, AppleAutomationError as AppleCalendarError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, PreconditionError, SchemaDriftError, columnsOf, confirmArg, createOsascriptRunner, describeStore, escapeLike, fingerprintSchema, limitArg, ok, openReadOnly, parseBool, parseConfig, parseIntOpt, parseList, readPackageIdentity, trimmed, withBusyRetry, wrap } from "@mgcrea/mcp-apple-core";
+import { AppBusyError as CalendarBusyError, AppNotRunningError as CalendarNotRunningError, AppleAutomationError, AppleAutomationError as AppleCalendarError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, PreconditionError, SchemaDriftError, columnsOf, confirmArg, createOsascriptRunner, describeStore, escapeLike, fingerprintSchema, limitArg, ok, openReadOnly, parseBool, parseConfig, parseIntOpt, parseList, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, trimmed, withBusyRetry, wrap } from "@mgcrea/mcp-apple-core";
 import { readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -12,8 +12,8 @@ const pkg = readPackageIdentity(new URL("../package.json", import.meta.url), {
 const BUILD_INFO = {
 	name: pkg.name,
 	version: pkg.version,
-	gitCommit: "df06e7f",
-	gitCommitDate: "2026-08-22T16:20:23+02:00"
+	gitCommit: "312147f",
+	gitCommitDate: "2026-08-27T16:06:37+02:00"
 };
 //#endregion
 //#region src/client/errors.ts
@@ -79,6 +79,187 @@ var CalendarNotWritableError = class extends AppleAutomationError {
 	}
 };
 //#endregion
+//#region src/client/availability.ts
+/**
+* Free-time arithmetic: turning a set of events into the times nothing is on.
+*
+* ## Why this is its own module, and why it is pure
+*
+* `recurrence.ts` set the precedent — the piece whose correctness rests on a
+* measurement lives apart from the SQL. This is the mirror image. Nothing here
+* rests on a measurement at all; it is interval arithmetic and calendar-day
+* iteration, and it is separated for the opposite reason: it is the only part
+* of an availability answer that can be tested without a store, and the part
+* where an off-by-one books a meeting on top of another meeting.
+*
+* ## The rule that governs every decision below
+*
+* A gap reported here is an assertion that NOTHING is on the calendar then.
+* `docs/calendar.md` already names why that is dangerous: "a short list of
+* events is indistinguishable from a free afternoon". Every other read tool on
+* this surface can afford to return a short list and flag it. This one cannot —
+* shortening the busy set does not shorten the answer, it INVENTS free time.
+* So the caller of this module must hand it a complete busy set or refuse, and
+* everything here assumes that contract has already been checked.
+*
+* ## Local wall clock, deliberately
+*
+* Working hours are a human's, not UTC's: "09:00 to 18:00" means those numbers
+* on the office wall, on both sides of a daylight-saving change. So day
+* boundaries are built with local date components — the same choice, for the
+* same reason, as `at()` in `dates.ts` — and a day that loses an hour simply
+* has one fewer hour in it, which is what actually happened.
+*/
+const WEEKDAY_KEYS = [
+	"sun",
+	"mon",
+	"tue",
+	"wed",
+	"thu",
+	"fri",
+	"sat"
+];
+/** Monday to Friday, the default working week. */
+const DEFAULT_WEEKDAYS = [
+	"mon",
+	"tue",
+	"wed",
+	"thu",
+	"fri"
+];
+const CLOCK$1 = /^(\d{1,2}):(\d{2})$/;
+const pad$2 = (n) => String(n).padStart(2, "0");
+const parseClock = (field, raw) => {
+	const text = String(raw ?? "").trim();
+	const m = CLOCK$1.exec(text);
+	if (!m) throw new InvalidDateError(field, text, "expected a time of day like \"09:00\"");
+	const hours = Number(m[1]);
+	const minutes = Number(m[2]);
+	if (hours > 24 || minutes > 59) throw new InvalidDateError(field, text, `${hours}:${m[2]} is not a time of day`);
+	if (hours === 24 && minutes !== 0) throw new InvalidDateError(field, text, "24:00 is the latest time of day, so \"24:30\" is not one");
+	return {
+		hours,
+		minutes
+	};
+};
+const weekdaySet = (keys) => new Set(keys.map((k) => WEEKDAY_KEYS.indexOf(k)).filter((i) => i !== -1));
+const startOfLocalDay = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate(), 0, 0, 0, 0);
+/** Same wall-clock time, n days later. Calendar arithmetic, so DST-safe. */
+const addDays$1 = (d, n) => {
+	const out = new Date(d.getTime());
+	out.setDate(out.getDate() + n);
+	return out;
+};
+/**
+* A time of day on a given local date.
+*
+* `new Date(y, m, d, 24, 0)` rolls to the next midnight on purpose, which is
+* what makes `dayEnd: "24:00"` mean "to the end of this day" rather than an
+* error case the caller has to special-case.
+*/
+const atClock = (day, c) => new Date(day.getFullYear(), day.getMonth(), day.getDate(), c.hours, c.minutes, 0, 0).getTime();
+/**
+* Overlapping and touching intervals collapsed into the fewest that cover the
+* same time, in order.
+*
+* Touching counts as overlapping (`<=`, not `<`): two meetings that end and
+* begin on the same minute leave no gap, and emitting a zero-length one would
+* put "you are free from 10:00 to 10:00" in front of a model.
+*/
+const mergeIntervals = (input) => {
+	const sorted = input.filter((i) => i.to > i.from).toSorted((a, b) => a.from - b.from);
+	const out = [];
+	for (const cur of sorted) {
+		const last = out.at(-1);
+		if (last && cur.from <= last.to) {
+			if (cur.to > last.to) last.to = cur.to;
+			continue;
+		}
+		out.push({
+			from: cur.from,
+			to: cur.to
+		});
+	}
+	return out;
+};
+/**
+* What is left of `window` once every busy interval is taken out of it.
+*
+* `busy` MUST already be merged and sorted — pass it through `mergeIntervals`
+* first. Taking unsorted input here would silently under-subtract and hand back
+* time that is booked, which is the one error this module exists to prevent, so
+* the precondition is stated rather than defended against: a defensive re-sort
+* would hide the caller's mistake instead of making it impossible.
+*/
+const subtractBusy = (window, busy) => {
+	const out = [];
+	let cursor = window.from;
+	for (const b of busy) {
+		if (b.to <= cursor) continue;
+		if (b.from >= window.to) break;
+		if (b.from > cursor) out.push({
+			from: cursor,
+			to: b.from
+		});
+		cursor = b.to;
+		if (cursor >= window.to) return out;
+	}
+	if (cursor < window.to) out.push({
+		from: cursor,
+		to: window.to
+	});
+	return out;
+};
+/**
+* The working windows inside `[from, to]`, one per admitted weekday.
+*
+* A `dayEnd` at or before `dayStart` yields no window for that day rather than
+* a negative one. Overnight working hours are not expressible, and saying so
+* with an empty result is better than wrapping around midnight and reporting
+* free time on a day the caller never asked about.
+*/
+const dayWindows = (opts) => {
+	const out = [];
+	const last = opts.to.getTime();
+	for (let day = startOfLocalDay(opts.from); day.getTime() <= last; day = addDays$1(day, 1)) {
+		if (!opts.weekdays.has(day.getDay())) continue;
+		const open = atClock(day, opts.dayStart);
+		const close = atClock(day, opts.dayEnd);
+		if (close <= open) continue;
+		const from = Math.max(open, opts.from.getTime());
+		const to = Math.min(close, last);
+		if (to > from) out.push({
+			from,
+			to
+		});
+	}
+	return out;
+};
+/**
+* Round an instant up to the next granularity boundary of its own hour.
+*
+* Anchored to the top of the hour rather than to the window, so a slot lands on
+* 09:15 and not on 09:07 because that is when the previous meeting happened to
+* end. Callers restrict granularity to a divisor of 60, which is what keeps the
+* per-hour restart invisible.
+*/
+const alignUp = (ms, granularityMinutes) => {
+	const d = new Date(ms);
+	const topOfHour = new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours(), 0, 0, 0).getTime();
+	const step = granularityMinutes * 6e4;
+	const past = ms - topOfHour;
+	return topOfHour + Math.ceil(past / step) * step;
+};
+/** Local midnight at the start of the day an instant falls on. */
+const startOfLocalDayMs = (ms) => startOfLocalDay(new Date(ms)).getTime();
+/** The following local midnight. Calendar arithmetic, so a DST day is 23h or 25h. */
+const nextLocalDayMs = (ms) => addDays$1(startOfLocalDay(new Date(ms)), 1).getTime();
+/** `2026-08-24`, in local components — the day a slot falls on. */
+const localDay = (ms) => {
+	const d = new Date(ms);
+	return `${d.getFullYear()}-${pad$2(d.getMonth() + 1)}-${pad$2(d.getDate())}`;
+};
+//#endregion
 //#region src/client/dates.ts
 /**
 * Date handling for the Calendar tools.
@@ -1464,6 +1645,29 @@ const openStore = (path, mode, logger) => {
 */
 const STATUS_CANCELLED = 3;
 const PARTICIPANT_DECLINED = 3;
+/**
+* `EKEventAvailability.free`, on the same inference as the two above — and held
+* to a stricter standard, because the direction it can fail in is worse.
+*
+* Reading this number wrongly makes a busy event look free, which is the one
+* error `findAvailability` exists to avoid. So unlike `status`, it is not
+* applied by default at all: `respectFreeMarking` is opt-in, the raw value
+* travels on every busy block, and until someone measures the column against a
+* live store every event blocks time regardless of how it is marked.
+*/
+const AVAILABILITY_FREE = 1;
+/**
+* How many events `findAvailability` will read from one leg before refusing.
+*
+* `listEvents` over-fetches `limit * 4 + 50` and caps at 5,000 because it only
+* needs enough rows to fill a page. This tool needs EVERY row in the window, so
+* the number here is not a page size — it is the point past which the tool
+* stops claiming to know what is on the calendar. Sized against the measured
+* store in `docs/calendar.md` (1,350 items, 1,946 cached occurrences across
+* four years), so a year-long window on an ordinary calendar sits far under it
+* and a runaway one is caught rather than answered.
+*/
+const BUSY_SCAN_BOUND = 5e3;
 var AppleCalendarClient = class {
 	config;
 	runner;
@@ -1706,6 +1910,212 @@ var AppleCalendarClient = class {
 			coverage: null
 		};
 	}
+	/**
+	* When nothing is on the calendar, for long enough to hold a meeting.
+	*
+	* ## Why this is not list_events with arithmetic bolted on
+	*
+	* Every other read here returns what it found and flags what it missed, and
+	* a caller reads the flag or does not. This one INVERTS the events: what it
+	* returns is the complement of what it read, so anything the read missed
+	* comes back as free time. A page limit, an unexpanded weekly meeting, an
+	* event past the coverage edge — each of those shortens a `list_events`
+	* result harmlessly and each of them, here, invents a slot that is already
+	* booked. `docs/calendar.md` names the failure directly: "a short list of
+	* events is indistinguishable from a free afternoon."
+	*
+	* So the busy set is either complete or the answer is withheld. Three checks
+	* enforce that, and each returns a refusal rather than a short list:
+	*
+	*   1. the scan bound, so a saturated leg never passes for a quiet week
+	*   2. the expansion, because an unexpanded series is invisible on every
+	*      date but one
+	*   3. the coverage edge, past which repeating events simply are not there
+	*
+	* The third clips the window rather than refusing outright, because the part
+	* inside the edge is genuinely answerable — but it says what it cut.
+	*/
+	findAvailability(args) {
+		const store = this.#require();
+		const now = this.#now();
+		const range = parseRange({
+			from: args.from,
+			to: args.to,
+			defaultRangeDays: this.config.defaultRangeDays,
+			maxRangeDays: this.config.maxRangeDays
+		}, now);
+		const dayStart = parseClock("dayStart", args.dayStart);
+		const dayEnd = parseClock("dayEnd", args.dayEnd);
+		const weekdayKeys = args.weekdays?.length ? args.weekdays : DEFAULT_WEEKDAYS;
+		const weekdays = weekdaySet(weekdayKeys);
+		const calendarUuids = this.#calendarUuids(store, args.calendar);
+		const fromApple = this.#toApple(range.from, store);
+		const toApple = this.#toApple(range.to, store);
+		const q = {
+			fromApple,
+			toApple,
+			limit: BUSY_SCAN_BOUND,
+			...calendarUuids ? { calendarUuids } : {}
+		};
+		const items = store.rangeItems(q);
+		const occurrences = store.rangeOccurrences(q);
+		if (items.length >= BUSY_SCAN_BOUND || occurrences.length >= BUSY_SCAN_BOUND) return {
+			degraded: true,
+			capability: "busy-set",
+			reason: `The window holds at least ${BUSY_SCAN_BOUND} events, which is the bound on what this tool reads. Nothing was computed, so this is not "you have no free time" and not "you are entirely free" — it is no answer at all.`,
+			hint: "Ask for a shorter window, or scope it to the calendars that matter with `calendar`. apple_calendar_list_events will still page through the range as it is."
+		};
+		const merged = mergeRange({
+			items,
+			occurrences,
+			coverage: store.coverage(),
+			hasOccurrenceCache: store.caps.hasOccurrenceCache,
+			fromApple,
+			toApple,
+			limit: items.length + occurrences.length,
+			epochOffset: store.caps.epochOffset
+		});
+		if (merged.expansion === "unavailable") return {
+			degraded: true,
+			capability: "occurrence-expansion",
+			reason: "Repeating events are not expanded on this store, so a weekly meeting exists on the date its series begins and nowhere else. Every gap computed from that would be wrong " + `in the same direction — free where it is booked. ${merged.expansionReason ?? ""}`.trim(),
+			hint: "Read the schedule directly with apple_calendar_list_events, which reports the same limitation rather than hiding it behind an answer."
+		};
+		let windowFrom = range.from;
+		let windowTo = range.to;
+		let truncated;
+		const cov = merged.coverage;
+		if (cov) {
+			const covFrom = /* @__PURE__ */ new Date((cov.fromApple + store.caps.epochOffset) * 1e3);
+			const covTo = /* @__PURE__ */ new Date((cov.toApple + store.caps.epochOffset) * 1e3);
+			const reason = "the requested window runs past the range this store has expanded, where repeating events are missing entirely; it was cut back rather than reporting that time as free";
+			if (windowTo.getTime() > covTo.getTime()) {
+				truncated = {
+					reason,
+					requestedTo: toLocalIso(range.to)
+				};
+				windowTo = covTo;
+			}
+			if (windowFrom.getTime() < covFrom.getTime()) {
+				truncated = {
+					...truncated ?? { reason },
+					requestedFrom: toLocalIso(range.from)
+				};
+				windowFrom = covFrom;
+			}
+			if (truncated && windowTo.getTime() <= windowFrom.getTime()) return {
+				degraded: true,
+				capability: "occurrence-coverage",
+				reason: "The whole requested window lies outside the range this store has expanded, so every gap in it would be invented rather than found.",
+				hint: `The expansion reaches ${toLocalIso(covFrom)} to ${toLocalIso(covTo)}. Ask inside that, or use apple_calendar_list_events, which reports single events correctly at any distance.`
+			};
+		}
+		const startedAtNow = windowFrom.getTime() < now.getTime();
+		if (startedAtNow) windowFrom = now;
+		const shell = {
+			durationMinutes: args.durationMinutes,
+			window: {
+				from: toLocalIso(windowFrom),
+				to: toLocalIso(windowTo),
+				clamped: range.clamped,
+				startedAtNow
+			},
+			workingHours: {
+				dayStart: args.dayStart,
+				dayEnd: args.dayEnd,
+				weekdays: weekdayKeys,
+				granularityMinutes: args.granularityMinutes,
+				timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone
+			},
+			expansion: merged.expansion,
+			coverage: cov ? {
+				from: this.#fromApple(cov.fromApple, store),
+				to: this.#fromApple(cov.toApple, store),
+				rows: cov.rows
+			} : null,
+			...truncated ? { truncated } : {}
+		};
+		if (windowTo.getTime() <= windowFrom.getTime()) return {
+			...shell,
+			slots: [],
+			busy: {
+				blocking: 0,
+				intervals: 0
+			},
+			allDayEvents: [],
+			note: "The window holds no future time — every moment in it has already passed. Nothing was checked, so this is not a report that you are busy."
+		};
+		const declined = args.includeDeclined ?? this.config.includeDeclined;
+		const cancelled = args.includeCancelled ?? this.config.includeCancelled;
+		const busy = [];
+		const allDayEvents = [];
+		let blocking = 0;
+		for (const row of merged.rows) {
+			if (row.startApple === null) continue;
+			if (!this.#visible(row, {
+				declined,
+				cancelled
+			})) continue;
+			const startMs = (row.startApple + store.caps.epochOffset) * 1e3;
+			if (row.allDay) {
+				const dayOpen = startOfLocalDayMs(startMs);
+				const dayShut = nextLocalDayMs(startMs);
+				if (dayOpen < windowTo.getTime() && dayShut > windowFrom.getTime()) {
+					const rendered = renderInstant(row.startApple, row.startTz, true, store.caps.epochOffset);
+					allDayEvents.push({
+						day: rendered?.allDay ? rendered.day : localDay(startMs),
+						summary: row.summary,
+						calendar: row.calendarTitle
+					});
+				}
+				if (!args.allDayBusy) continue;
+				const endMs = row.endApple === null ? dayShut : (row.endApple + store.caps.epochOffset) * 1e3;
+				busy.push({
+					from: dayOpen,
+					to: Math.max(dayShut, startOfLocalDayMs(endMs))
+				});
+				blocking += 1;
+				continue;
+			}
+			if (args.respectFreeMarking && row.availability === AVAILABILITY_FREE) continue;
+			const endMs = row.endApple === null ? startMs : (row.endApple + store.caps.epochOffset) * 1e3;
+			if (endMs <= startMs) continue;
+			busy.push({
+				from: startMs,
+				to: endMs
+			});
+			blocking += 1;
+		}
+		const blocks = mergeIntervals(busy);
+		const needMs = args.durationMinutes * 6e4;
+		const slots = [];
+		outer: for (const w of dayWindows({
+			from: windowFrom,
+			to: windowTo,
+			dayStart,
+			dayEnd,
+			weekdays
+		})) for (const gap of subtractBusy(w, blocks)) {
+			const start = alignUp(gap.from, args.granularityMinutes);
+			if (gap.to - start < needMs) continue;
+			slots.push({
+				start: toLocalIso(new Date(start)),
+				end: toLocalIso(new Date(gap.to)),
+				day: localDay(start),
+				minutes: Math.round((gap.to - start) / 6e4)
+			});
+			if (slots.length >= args.limit) break outer;
+		}
+		return {
+			...shell,
+			slots,
+			busy: {
+				blocking,
+				intervals: blocks.length
+			},
+			allDayEvents
+		};
+	}
 	getEvent(ref) {
 		const store = this.#require();
 		const decoded = decodeRef(ref);
@@ -1971,6 +2381,15 @@ var AppleCalendarClient = class {
 };
 //#endregion
 //#region src/config.ts
+const CLOCK = /^\d{1,2}:\d{2}$/;
+/**
+* `Mon`, `MONDAY` and `mon` all mean the same day.
+*
+* Normalised here rather than in the schema so the schema's error message stays
+* the useful one — it lists the seven keys — instead of rejecting a spelling
+* nobody would think was wrong.
+*/
+const parseWorkdays = (raw) => raw?.map((d) => d.trim().toLowerCase().slice(0, 3));
 /**
 * Configuration is environment-only — this server holds no secret at all, its
 * access is the macOS permission the user granted.
@@ -2014,6 +2433,17 @@ const ConfigSchema = BaseConfigSchema.extend({
 	defaultRangeDays: z.number().int().min(1).max(366).default(7),
 	/** Hard clamp, so one query cannot ask for a decade. */
 	maxRangeDays: z.number().int().min(1).max(3660).default(366),
+	/**
+	* The working day `find_availability` assumes when the caller names no hours.
+	*
+	* Local wall clock, both of them: working hours are a person's, so they hold
+	* their numbers across a daylight-saving change rather than drifting an hour.
+	* `24:00` is a legal end and means midnight at the close of that day.
+	*/
+	workdayStart: z.string().regex(CLOCK, "expected a time of day like \"09:00\"").default("09:00"),
+	workdayEnd: z.string().regex(CLOCK, "expected a time of day like \"18:00\"").default("18:00"),
+	/** The days that working day applies to. */
+	workdays: z.array(z.enum(WEEKDAY_KEYS)).min(1).default([...DEFAULT_WEEKDAYS]),
 	/** Length of a created event when the caller gives neither an end nor a duration. */
 	defaultEventDurationMinutes: z.number().int().min(1).max(1440).default(60),
 	/** Whether events the user declined are included when the caller does not say. */
@@ -2041,6 +2471,7 @@ const ConfigSchema = BaseConfigSchema.extend({
 */
 const loadConfig = (env = process.env) => parseConfig(ConfigSchema, {
 	allowWrites: parseBool(env.APPLE_CALENDAR_ALLOW_WRITES),
+	exposePrompts: parseBool(env.APPLE_CALENDAR_EXPOSE_PROMPTS),
 	debug: parseBool(env.APPLE_CALENDAR_DEBUG),
 	accounts: parseList(env.APPLE_CALENDAR_ACCOUNTS),
 	calendars: parseList(env.APPLE_CALENDAR_CALENDARS),
@@ -2050,6 +2481,9 @@ const loadConfig = (env = process.env) => parseConfig(ConfigSchema, {
 	defaultRangeDays: parseIntOpt(env.APPLE_CALENDAR_DEFAULT_RANGE_DAYS),
 	maxRangeDays: parseIntOpt(env.APPLE_CALENDAR_MAX_RANGE_DAYS),
 	defaultEventDurationMinutes: parseIntOpt(env.APPLE_CALENDAR_DEFAULT_EVENT_DURATION_MINUTES),
+	workdayStart: trimmed(env.APPLE_CALENDAR_WORKDAY_START),
+	workdayEnd: trimmed(env.APPLE_CALENDAR_WORKDAY_END),
+	workdays: parseWorkdays(parseList(env.APPLE_CALENDAR_WORKDAYS)),
 	includeDeclined: parseBool(env.APPLE_CALENDAR_INCLUDE_DECLINED),
 	includeCancelled: parseBool(env.APPLE_CALENDAR_INCLUDE_CANCELLED),
 	osascriptPath: trimmed(env.APPLE_CALENDAR_OSASCRIPT_PATH),
@@ -2058,6 +2492,126 @@ const loadConfig = (env = process.env) => parseConfig(ConfigSchema, {
 	timeZone: trimmed(env.APPLE_CALENDAR_TIMEZONE)
 });
 //#endregion
+//#region src/guide.ts
+/**
+* The Calendar operating manual, served as `cupertino://calendar/guide` and
+* embedded ahead of every Calendar prompt. Static by design — see the note in
+* the Mail guide.
+*/
+const CALENDAR_GUIDE = `# Apple Calendar — how to drive this server
+
+## Refs are opaque, and they name an occurrence
+
+Events come back with a \`ref\` like \`c1:<calendar>/<occurrence>/<uid>\`. Pass it
+back verbatim. The part that matters: a ref names **one occurrence**, not the
+series. Reading it reports that occurrence's times; acting on it acts on that
+occurrence. Do not assume changing one changes the repeat.
+
+## Which tool, under which constraint
+
+- **"When am I free", "find me 45 minutes", "what does Thursday look like"** is
+  \`apple_calendar_find_availability\`. Reach for it instead of listing events and
+  looking for gaps by hand — that is where an occurrence of a repeating meeting
+  gets missed. It works in working hours (09:00–18:00 on weekdays by default),
+  in this machine's timezone, and never offers time already past.
+- **What is on** is \`apple_calendar_list_events\` over a bounded range.
+- **Finding a specific event** is \`apple_calendar_search_events\`.
+- **Calendar names** must match what Calendar calls them — read the inventory
+  resource first. A mistyped name matches nothing rather than erroring.
+
+## Empty is booked; degraded is unknown
+
+On availability these are two different answers and must never be reported the
+same way. An empty \`slots\` list means **the time is booked**. \`degraded: true\`
+means the question could not be answered — too many events to read, a store
+that does not expand repeats, or a window past the expansion range — and the
+right reply is "I could not check", never "you are free".
+
+All-day events do not block time by default, because an all-day event is as
+often a birthday as a holiday. They come back in \`allDayEvents\`: read that
+before booking over one rather than turning \`allDayBusy\` on blindly. Declined
+and cancelled events never block.
+
+## Writes, and the thing this server will not do
+
+Mutating tools exist only when writes are enabled. If you cannot see
+\`apple_calendar_create_event\`, writes are off.
+
+**There is no \`attendees\` parameter, anywhere, on purpose.** Adding an attendee
+sends mail to a person. This server creates events on calendars; it does not
+invite anyone. If the user wants someone invited, create the event and tell them
+to invite from Calendar — do not silently create an event they believe was sent.
+
+Read-only calendars are refused rather than silently skipped.
+`;
+//#endregion
+//#region src/prompts.ts
+const CTX = {
+	surface: "calendar",
+	guide: CALENDAR_GUIDE
+};
+/**
+* Calendar's workflow prompts.
+*
+* The scheduling one carries the constraint that costs the most when it is
+* missed: this server can create an event but cannot invite anyone to it, so a
+* model that treats "schedule a meeting with Ana" as done has told the user
+* something false about a message that was never sent.
+*/
+const registerPrompts = (server, allowWrites) => {
+	registerWorkflowPrompt(server, CTX, {
+		name: "apple_calendar_whats_my_day",
+		title: "What my day looks like",
+		description: "Read back a day or a range as something you can act on — what is fixed, what is movable, and where the real free time is. Read-only.",
+		argsSchema: {
+			when: promptArg("Which day or range, e.g. \"today\", \"tomorrow\", \"next week\". Defaults to today."),
+			calendar: promptArg("Restrict to one calendar, exactly as Calendar spells it.")
+		},
+		build: ({ when, calendar }) => `Tell me what ${when ?? "today"} looks like${calendar ? `, on the ${calendar} calendar` : ""}.
+
+1. \`apple_calendar_list_events\` over that range${calendar ? " for that calendar" : ""}. Bound the range explicitly — do not list open-endedly and trim afterwards.
+2. Then \`apple_calendar_find_availability\` over the same range, so you can say
+   where the usable gaps are rather than leaving the user to subtract meetings
+   from a day in their head. Report each gap's real length.
+3. Call out anything in \`allDayEvents\` — a holiday or someone's day off changes
+   what the rest of the day means, and it does not block time by default.
+4. Flag the pressure points: back-to-back blocks with no gap, anything starting
+   before or ending after normal hours, and any two events that overlap.
+
+If a call comes back \`degraded: true\`, say which part of the range you could not
+read. An empty result means booked; degraded means unknown, and they must not be
+reported the same way.`
+	});
+	if (!allowWrites) return;
+	registerWorkflowPrompt(server, CTX, {
+		name: "apple_calendar_schedule",
+		title: "Schedule something",
+		description: "Find a time that genuinely works and put an event on the calendar. Requires writes. Note that this cannot invite anyone — it creates the event only.",
+		argsSchema: {
+			what: requiredPromptArg("What the event is, e.g. \"45 minutes with Ana about pricing\"."),
+			when: promptArg("Constraint on when, e.g. \"next week\", \"Thursday afternoon\"."),
+			calendar: promptArg("Which calendar to create it on, exactly as Calendar spells it.")
+		},
+		build: ({ what, when, calendar }) => `Schedule: ${what}${when ? `\n\nWhen: ${when}` : ""}
+
+1. Work out the duration from the description; ask if it is genuinely unclear
+   rather than defaulting to an hour.
+2. \`apple_calendar_find_availability\` over ${when ? `the window implied by "${when}"` : "the coming week"}. Do not list events and pick a gap yourself — a repeating meeting's
+   occurrence is exactly what that misses.
+3. Offer the user two or three real options before creating anything, with the
+   full length of each gap so they can see whether it is tight. If availability
+   comes back \`degraded: true\`, stop and say you could not check — do not offer
+   a slot you could not verify.
+4. On their choice, \`apple_calendar_create_event\`${calendar ? ` on the ${calendar} calendar` : " on a calendar from the inventory, not an invented name"}.
+
+**Then be explicit about what did not happen: nobody was invited.** This server
+has no \`attendees\` parameter on any tool — adding one would send mail, and it
+deliberately cannot. If someone else needs to be at this, the event is on the
+calendar and the invitation still has to be sent from Calendar by hand. Say so
+plainly; do not let "scheduled with Ana" stand when Ana was never told.`
+	});
+};
+//#endregion
 //#region src/tools/util.ts
 const eventRefArg = z.string().min(1).describe("An opaque event ref from a list or search result (looks like \"c1:<calendar>/<occurrence>/<uid>\"). Do not construct one by hand.");
 const calendarArg = z.string().optional().describe("A calendar name or uid, e.g. \"Work\". Use apple_calendar_list_calendars to see what exists.");
@@ -2073,6 +2627,107 @@ const toArg = z.string().optional().describe("End of the window. A bare day runs
 const includeDeclinedArg = z.boolean().optional().describe("Include events you have declined. Off by default; they are still on the calendar.");
 const includeCancelledArg = z.boolean().optional().describe("Include events an organiser cancelled but that are still in the store. Off by default.");
 //#endregion
+//#region src/tools/diagnostics.ts
+/**
+* Build the report.
+*
+* Split out of the tool registration so the `cupertino://calendar/diagnostics`
+* resource can serve the same bytes. Two renderings of one probe: duplicated,
+* the resource and the tool would drift, and the disagreement would surface as
+* "the diagnostics lied" — the one thing this file must never do.
+*/
+const buildDiagnostics = async (client, ctx) => {
+	const lanes = client.lanes();
+	const located = client.locate();
+	const store = client.index();
+	/**
+	* Three-valued, and the middle value is the useful one.
+	*
+	* Calendar's store has a constant filename, so `stat` answers "is it
+	* there" even when `access(2)` is denied. That lets this separate "the
+	* grant is missing" from "Calendar was never set up on this account",
+	* which Reminders cannot do — its filename carries a generated UUID, so
+	* without the grant there is no path to test at all.
+	*/
+	const fullDiskAccess = located.readable ? "granted" : located.exists ? "denied (found the store, cannot read it)" : "unknown (no store file at the expected path)";
+	return {
+		server: { lanes },
+		permissions: {
+			fullDiskAccess,
+			automation: ctx.allowWrites ? "needed for writes only. Reads never send an Apple Event, so a read-only setup prompts for nothing." : "not needed — writes are off, and reads never send an Apple Event. Turning writes on will prompt for Automation the first time one runs.",
+			...located.readable ? {} : { howToGrant: [
+				"System Settings > Privacy & Security > Full Disk Access",
+				"Add the app that launches this server (Terminal, iTerm, VS Code, Claude...), then restart it.",
+				"Granting it to Calendar.app does nothing — the reader needs the permission, not Calendar."
+			] }
+		},
+		store: {
+			containerPath: located.containerPath,
+			path: located.storePath,
+			containerListable: located.containerListable,
+			extrasPresent: located.extrasPresent,
+			candidates: located.candidates.length,
+			exists: located.exists,
+			readable: located.readable,
+			sizeBytes: located.size,
+			walPresent: located.walPresent,
+			walSizeBytes: located.walSizeBytes,
+			fingerprint: lanes.storeFingerprint,
+			reason: located.reason
+		},
+		capabilities: store ? {
+			hasOccurrenceCache: store.caps.hasOccurrenceCache,
+			hasOccurrenceDays: store.caps.hasOccurrenceDays,
+			hasRecurrence: store.caps.hasRecurrence,
+			hasExceptionDates: store.caps.hasExceptionDates,
+			hasLocation: store.caps.hasLocation,
+			hasAttachments: store.caps.hasAttachments,
+			hasParticipants: store.caps.hasParticipants,
+			hasAlarms: store.caps.hasAlarms,
+			itemColumns: store.caps.itemColumns.size,
+			calendarColumns: store.caps.calendarColumns.size
+		} : null,
+		settings: {
+			allowWrites: ctx.allowWrites,
+			exposePrompts: client.config.exposePrompts,
+			accountAllowlist: client.config.accounts,
+			calendarAllowlist: client.config.calendars,
+			defaultCalendar: client.config.defaultCalendar ?? null,
+			defaultRangeDays: client.config.defaultRangeDays,
+			maxRangeDays: client.config.maxRangeDays,
+			includeDeclined: client.config.includeDeclined,
+			includeCancelled: client.config.includeCancelled,
+			indexMode: client.config.indexMode,
+			maxResults: client.config.maxResults,
+			timeZone: client.config.timeZone ?? null
+		},
+		caveats: [
+			"Writes go through Apple Events and are real side effects: on a shared, CalDAV or Exchange calendar a created event syncs within seconds and other people see it. There is no draft state and no undo.",
+			"Single occurrences of a repeating event can be neither edited nor deleted through this server, and that is a limit of Calendar's scripting interface rather than a choice: there is no way to detach one occurrence, and the excluded-dates property reads back a 1903 sentinel and throws on assignment (measured, macOS 26.6). Both are refused rather than applied to the whole series. Calendar.app can still do them.",
+			"Attendees cannot be set, because that emails a person. There is no \"all future occurrences\" either, which would need two writes with no transaction between them.",
+			"Calendar reads through the file lane only. Apple Events was measured at 3.4s for a single 90-day range query, with the cost falling per round trip rather than per event, so there is no slower-but-working fallback to offer when Full Disk Access is missing. Reads need the grant.",
+			"Repeating events are expanded from OccurrenceCache, which was measured to reach about two years either side of today on the probed store. That is an edge: a range running past it returns fewer repeating events than exist, so every list_events result carries `coverage`, and sets `truncated` rather than returning a short list silently.",
+			"The `status` and `invitationStatus` numbers are EventKit's documented constants, and this store is assumed to mirror them — likely, but not measured. That is why cancelled and declined events are only hidden when you ask, and why the raw value is on every result.",
+			"Writes will go through Apple Events, targeting com.apple.iCal. Note the bundle id is iCal, not Calendar, which is the one place this surface differs from the other three."
+		]
+	};
+};
+/**
+* One tool that answers "why is this not working".
+*
+* Unlike the Reminders equivalent this probes no Apple Event before reading:
+* Calendar has no Apple Events read lane to probe (`docs/distribution.md`), so
+* firing one here would trigger the Automation prompt for a capability the
+* server does not yet have.
+*/
+const registerDiagnosticsTools = (server, client, ctx) => {
+	server.registerTool("apple_calendar_diagnostics", {
+		description: "Report which lanes are live, which macOS permissions are granted, and what each missing one is blocking. Start here when a tool fails or reports nothing — it names the exact System Settings pane to open.",
+		inputSchema: {},
+		annotations: { readOnlyHint: true }
+	}, async () => wrap(() => buildDiagnostics(client, ctx)).then((r) => r ?? ok({})));
+};
+//#endregion
 //#region src/tools/actions.ts
 /**
 * The mutating tools.
@@ -2128,6 +2783,49 @@ const registerActionTools = (server, client) => {
 	}, async ({ refs }) => wrap(() => client.deleteEvents(refs)));
 };
 //#endregion
+//#region src/tools/availability.ts
+/**
+* The one read on this surface that answers a question instead of returning
+* rows, and the only one whose result is the COMPLEMENT of what it read.
+*
+* It lives apart from `events.ts` for that reason. The three tools there share
+* a failure mode — return fewer events than exist, flag it, and the caller is
+* merely under-informed. This one turns the same shortfall into a positive
+* claim that a time is free, so its refusal paths are load-bearing rather than
+* defensive, and keeping them next to a `list_events` that legitimately pages
+* would invite someone to make the two consistent.
+*/
+const registerAvailabilityTools = (server, client) => {
+	server.registerTool("apple_calendar_find_availability", {
+		description: "Find the times nothing is on the calendar, long enough to hold a meeting of a given length. This is the tool for \"when am I free\", \"find me 45 minutes next week\" or \"what does Thursday look like\" — reach for it instead of listing events and looking for gaps yourself, which is where an occurrence of a repeating meeting gets missed. Working hours default to 09:00-18:00 on weekdays, in THIS MACHINE'S timezone, and only time inside them is offered. Slots start on a 15-minute boundary and each one reports how long the whole gap is, which is usually longer than you asked for. Time already past today is never offered. It refuses rather than guesses: if the window holds too many events to read, if this store does not expand repeating events, or if the window runs past the range the expansion covers, you get `degraded: true` and a reason instead of free time that is not free. An empty `slots` list means BOOKED; `degraded` means UNKNOWN. Declined and cancelled events do not block time; all-day events do not either, but they are listed in `allDayEvents` so you can see the holiday you are about to book over.",
+		inputSchema: {
+			durationMinutes: z.number().int().min(1).max(1440).describe("How long the meeting needs to be. A gap shorter than this is not returned."),
+			from: z.string().optional().describe("Start of the window. ISO-8601 \"2026-08-21\" or \"2026-08-21T09:00\", or \"today\", \"tomorrow\", \"next monday\", \"+2d\". Defaults to today. A start already in the past is pulled forward to now."),
+			to: toArg,
+			calendar: calendarArg,
+			dayStart: z.string().optional().describe("Earliest time of day to offer, local wall clock, e.g. \"09:00\". Defaults to APPLE_CALENDAR_WORKDAY_START (09:00)."),
+			dayEnd: z.string().optional().describe("Latest time of day to offer, e.g. \"18:00\" — or \"24:00\" for the end of the day. Defaults to APPLE_CALENDAR_WORKDAY_END (18:00)."),
+			weekdays: z.array(z.enum(WEEKDAY_KEYS)).min(1).optional().describe("Which days to offer, e.g. [\"mon\",\"tue\",\"wed\",\"thu\",\"fri\"]. Defaults to the configured working week. Pass all seven to include the weekend."),
+			granularityMinutes: z.number().int().min(1).max(60).refine((n) => 60 % n === 0, { message: "must divide 60 evenly — 5, 10, 15, 20, 30 or 60" }).optional().describe("Slot starts are rounded up to this boundary. Default 15."),
+			allDayBusy: z.boolean().optional().describe("Let an all-day event block its whole day. Off by default, because an all-day event is as often a birthday as a holiday, and blocking on \"Ana's birthday\" would hide a working day. They are reported in `allDayEvents` either way — read that before booking rather than turning this on blindly."),
+			respectFreeMarking: z.boolean().optional().describe("Skip events the calendar marks as \"free\" rather than \"busy\". Off by default: the stored constant is inferred from EventKit and has not been measured against a real store, and reading it wrongly would offer a slot that is booked. Every busy block reports its raw value so you can check before turning this on."),
+			includeDeclined: includeDeclinedArg,
+			includeCancelled: includeCancelledArg,
+			limit: limitArg
+		},
+		annotations: { readOnlyHint: true }
+	}, async (args) => wrap(async () => client.findAvailability({
+		...args,
+		dayStart: args.dayStart ?? client.config.workdayStart,
+		dayEnd: args.dayEnd ?? client.config.workdayEnd,
+		weekdays: args.weekdays ?? client.config.workdays,
+		granularityMinutes: args.granularityMinutes ?? 15,
+		allDayBusy: args.allDayBusy ?? false,
+		respectFreeMarking: args.respectFreeMarking ?? false,
+		limit: args.limit ?? Math.min(25, client.config.maxResults)
+	})));
+};
+//#endregion
 //#region src/tools/calendars.ts
 /**
 * NOTE ON `async` BELOW: core's `wrap` is typed `() => Promise<T>` because every
@@ -2148,97 +2846,6 @@ const registerCalendarTools = (server, client) => {
 	}, async () => wrap(async () => client.accounts()));
 };
 //#endregion
-//#region src/tools/diagnostics.ts
-/**
-* One tool that answers "why is this not working".
-*
-* Unlike the Reminders equivalent this probes no Apple Event before reading:
-* Calendar has no Apple Events read lane to probe (`docs/distribution.md`), so
-* firing one here would trigger the Automation prompt for a capability the
-* server does not yet have.
-*/
-const registerDiagnosticsTools = (server, client, ctx) => {
-	server.registerTool("apple_calendar_diagnostics", {
-		description: "Report which lanes are live, which macOS permissions are granted, and what each missing one is blocking. Start here when a tool fails or reports nothing — it names the exact System Settings pane to open.",
-		inputSchema: {},
-		annotations: { readOnlyHint: true }
-	}, async () => wrap(async () => {
-		const lanes = client.lanes();
-		const located = client.locate();
-		const store = client.index();
-		/**
-		* Three-valued, and the middle value is the useful one.
-		*
-		* Calendar's store has a constant filename, so `stat` answers "is it
-		* there" even when `access(2)` is denied. That lets this separate "the
-		* grant is missing" from "Calendar was never set up on this account",
-		* which Reminders cannot do — its filename carries a generated UUID, so
-		* without the grant there is no path to test at all.
-		*/
-		const fullDiskAccess = located.readable ? "granted" : located.exists ? "denied (found the store, cannot read it)" : "unknown (no store file at the expected path)";
-		return {
-			server: { lanes },
-			permissions: {
-				fullDiskAccess,
-				automation: ctx.allowWrites ? "needed for writes only. Reads never send an Apple Event, so a read-only setup prompts for nothing." : "not needed — writes are off, and reads never send an Apple Event. Turning writes on will prompt for Automation the first time one runs.",
-				...located.readable ? {} : { howToGrant: [
-					"System Settings > Privacy & Security > Full Disk Access",
-					"Add the app that launches this server (Terminal, iTerm, VS Code, Claude...), then restart it.",
-					"Granting it to Calendar.app does nothing — the reader needs the permission, not Calendar."
-				] }
-			},
-			store: {
-				containerPath: located.containerPath,
-				path: located.storePath,
-				containerListable: located.containerListable,
-				extrasPresent: located.extrasPresent,
-				candidates: located.candidates.length,
-				exists: located.exists,
-				readable: located.readable,
-				sizeBytes: located.size,
-				walPresent: located.walPresent,
-				walSizeBytes: located.walSizeBytes,
-				fingerprint: lanes.storeFingerprint,
-				reason: located.reason
-			},
-			capabilities: store ? {
-				hasOccurrenceCache: store.caps.hasOccurrenceCache,
-				hasOccurrenceDays: store.caps.hasOccurrenceDays,
-				hasRecurrence: store.caps.hasRecurrence,
-				hasExceptionDates: store.caps.hasExceptionDates,
-				hasLocation: store.caps.hasLocation,
-				hasAttachments: store.caps.hasAttachments,
-				hasParticipants: store.caps.hasParticipants,
-				hasAlarms: store.caps.hasAlarms,
-				itemColumns: store.caps.itemColumns.size,
-				calendarColumns: store.caps.calendarColumns.size
-			} : null,
-			settings: {
-				allowWrites: ctx.allowWrites,
-				accountAllowlist: client.config.accounts,
-				calendarAllowlist: client.config.calendars,
-				defaultCalendar: client.config.defaultCalendar ?? null,
-				defaultRangeDays: client.config.defaultRangeDays,
-				maxRangeDays: client.config.maxRangeDays,
-				includeDeclined: client.config.includeDeclined,
-				includeCancelled: client.config.includeCancelled,
-				indexMode: client.config.indexMode,
-				maxResults: client.config.maxResults,
-				timeZone: client.config.timeZone ?? null
-			},
-			caveats: [
-				"Writes go through Apple Events and are real side effects: on a shared, CalDAV or Exchange calendar a created event syncs within seconds and other people see it. There is no draft state and no undo.",
-				"Single occurrences of a repeating event can be neither edited nor deleted through this server, and that is a limit of Calendar's scripting interface rather than a choice: there is no way to detach one occurrence, and the excluded-dates property reads back a 1903 sentinel and throws on assignment (measured, macOS 26.6). Both are refused rather than applied to the whole series. Calendar.app can still do them.",
-				"Attendees cannot be set, because that emails a person. There is no \"all future occurrences\" either, which would need two writes with no transaction between them.",
-				"Calendar reads through the file lane only. Apple Events was measured at 3.4s for a single 90-day range query, with the cost falling per round trip rather than per event, so there is no slower-but-working fallback to offer when Full Disk Access is missing. Reads need the grant.",
-				"Repeating events are expanded from OccurrenceCache, which was measured to reach about two years either side of today on the probed store. That is an edge: a range running past it returns fewer repeating events than exist, so every list_events result carries `coverage`, and sets `truncated` rather than returning a short list silently.",
-				"The `status` and `invitationStatus` numbers are EventKit's documented constants, and this store is assumed to mirror them — likely, but not measured. That is why cancelled and declined events are only hidden when you ask, and why the raw value is on every result.",
-				"Writes will go through Apple Events, targeting com.apple.iCal. Note the bundle id is iCal, not Calendar, which is the one place this surface differs from the other three."
-			]
-		};
-	}).then((r) => r ?? ok({})));
-};
-//#endregion
 //#region src/tools/events.ts
 /** Declared once and spread into both tools, so the two cannot drift apart. */
 const filterSchema = {
@@ -2300,6 +2907,7 @@ const registerTools = (server, client, ctx) => {
 	registerDiagnosticsTools(server, client, ctx);
 	registerCalendarTools(server, client);
 	registerEventTools(server, client);
+	registerAvailabilityTools(server, client);
 	if (!ctx.allowWrites) return;
 	registerActionTools(server, client);
 };
@@ -2326,6 +2934,22 @@ const createServer = (opts) => {
 		...opts.now ? { now: opts.now } : {}
 	});
 	registerTools(server, client, { allowWrites: config.allowWrites });
+	if (config.exposePrompts) {
+		registerPrompts(server, config.allowWrites);
+		registerSurfaceResources(server, {
+			surface: "calendar",
+			displayName: "Calendar",
+			guide: CALENDAR_GUIDE,
+			diagnostics: () => buildDiagnostics(client, { allowWrites: config.allowWrites }),
+			inventory: {
+				describes: "accounts and calendars",
+				read: async () => ({
+					accounts: await client.accounts(),
+					calendars: await client.calendars()
+				})
+			}
+		});
+	}
 	return {
 		server,
 		client
@@ -2334,4 +2958,4 @@ const createServer = (opts) => {
 //#endregion
 export { BUILD_INFO as A, CALENDAR_SURFACE as C, CalendarNotWritableError as D, CalendarNotRunningError as E, EventNotFoundError as O, CALENDAR_BUNDLE_ID as S, CalendarNotFoundError as T, STORE_FILENAME as _, loadConfig as a, locateStore as b, introspect as c, decodeRef as d, encodeRef as f, GROUP_CONTAINER as g, EXTRAS_FILENAME as h, registerTools as i, InvalidDateError as k, openStore as l, uuidOf as m, SERVER_VERSION as n, AppleCalendarClient as o, seriesRefOf as p, createServer as r, CalendarStore as s, SERVER_NAME as t, REF_VERSION as u, defaultContainerPath as v, CalendarBusyError as w, AppleCalendarError as x, defaultStorePath as y };
 
-//# sourceMappingURL=server-B2HtiXLF.js.map
+//# sourceMappingURL=server-DoSfe1y7.js.map