feat(caldav): add slot support for feed items

Adds three LLM-fillable slots to every CalDav feed item:
insight, preparation, and crossSource. Slot prompts are
stored in separate .txt files under src/prompts/ with
few-shot examples to steer the LLM away from restating
event details.

Co-authored-by: Ona <no-reply@ona.com>

packages/aris-source-caldav/fixtures/daily-recurring-allday.ics

@@ -0,0 +1,12 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:daily-allday-001@test
+DTSTART;VALUE=DATE:20260112
+DTEND;VALUE=DATE:20260113
+SUMMARY:Daily Reminder
+RRULE:FREQ=DAILY;COUNT=7
+STATUS:CONFIRMED
+END:VEVENT
+END:VCALENDAR

packages/aris-source-caldav/fixtures/weekly-recurring-with-exception.ics

@@ -0,0 +1,20 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:weekly-exc-001@test
+DTSTART:20260101T140000Z
+DTEND:20260101T150000Z
+SUMMARY:Standup
+RRULE:FREQ=WEEKLY;BYDAY=TH;COUNT=8
+STATUS:CONFIRMED
+END:VEVENT
+BEGIN:VEVENT
+UID:weekly-exc-001@test
+RECURRENCE-ID:20260115T140000Z
+DTSTART:20260115T160000Z
+DTEND:20260115T170000Z
+SUMMARY:Standup (rescheduled)
+STATUS:CONFIRMED
+END:VEVENT
+END:VCALENDAR

packages/aris-source-caldav/fixtures/weekly-recurring.ics

@@ -0,0 +1,13 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:weekly-001@test
+DTSTART:20260101T100000Z
+DTEND:20260101T110000Z
+SUMMARY:Weekly Team Meeting
+RRULE:FREQ=WEEKLY;BYDAY=TH;COUNT=10
+LOCATION:Room B
+STATUS:CONFIRMED
+END:VEVENT
+END:VCALENDAR

packages/aris-source-caldav/scripts/test-live.ts

@@ -3,8 +3,13 @@
  *
  * Usage:
  *   bun run test-live.ts
+ *
+ * Writes feed items (with slots) to scripts/.cache/feed-items.json for inspection.
  */
 
+import { mkdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
 import { Context } from "@aris/core"
 
 import { CalDavSource } from "../src/index.ts"
@@ -51,6 +56,9 @@ for (const item of items) {
 	console.log(`  Status:     ${item.data.status ?? "(none)"}`)
 	console.log(`  Urgency:    ${item.signals?.urgency}`)
 	console.log(`  Relevance:  ${item.signals?.timeRelevance}`)
+	if (item.slots) {
+		console.log(`  Slots:      ${Object.keys(item.slots).join(", ")}`)
+	}
 	if (item.data.attendees.length > 0) {
 		console.log(`  Attendees:  ${item.data.attendees.map((a) => a.name ?? a.email).join(", ")}`)
 	}
@@ -62,3 +70,11 @@ for (const item of items) {
 if (items.length === 0) {
 	console.log("(no events found in the time window)")
 }
+
+// Write feed items to .cache for slot testing
+const cacheDir = join(import.meta.dir, ".cache")
+mkdirSync(cacheDir, { recursive: true })
+
+const outPath = join(cacheDir, "feed-items.json")
+writeFileSync(outPath, JSON.stringify(items, null, 2))
+console.log(`\nFeed items written to ${outPath}`)

packages/aris-source-caldav/src/caldav-source.test.ts

@@ -208,7 +208,7 @@ describe("CalDavSource", () => {
 		expect(items[0]!.data.calendarName).toBeNull()
 	})
 
-	test("handles recurring events with exceptions", async () => {
+	test("expands recurring events within the time range", async () => {
 		const objects: Record<string, CalDavDAVObject[]> = {
 			"/cal/work": [
 				{
@@ -218,21 +218,42 @@ describe("CalDavSource", () => {
 			],
 		}
 		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		// lookAheadDays=0 → range is Jan 15 only
 		const source = createSource(client)
 
 		const items = await source.fetchItems(createContext(new Date("2026-01-15T08:00:00Z")))
 
-		expect(items).toHaveLength(2)
+		// Only the Jan 15 occurrence falls in the single-day window
+		expect(items).toHaveLength(1)
+		expect(items[0]!.data.title).toBe("Weekly Sync")
+		expect(items[0]!.data.startDate).toEqual(new Date("2026-01-15T09:00:00Z"))
+	})
 
-		const base = items.find((i) => i.data.title === "Weekly Sync")
+	test("includes exception overrides when they fall in range", async () => {
+		const objects: Record<string, CalDavDAVObject[]> = {
+			"/cal/work": [
+				{
+					url: "/cal/work/recurring.ics",
+					data: loadFixture("recurring-event.ics"),
+				},
+			],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		// lookAheadDays=8 → range covers Jan 15 through Jan 23, includes the Jan 22 exception
+		const source = createSource(client, 8)
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T08:00:00Z")))
+
+		const base = items.filter((i) => i.data.title === "Weekly Sync")
 		const exception = items.find((i) => i.data.title === "Weekly Sync (moved)")
 
-		expect(base).toBeDefined()
-		expect(base!.data.recurrenceId).toBeNull()
+		// Jan 15 base occurrence
+		expect(base.length).toBeGreaterThanOrEqual(1)
 
+		// Jan 22 exception replaces the base occurrence
 		expect(exception).toBeDefined()
-		expect(exception!.data.recurrenceId).not.toBeNull()
-		expect(exception!.id).toContain("-")
+		expect(exception!.data.startDate).toEqual(new Date("2026-01-22T10:00:00Z"))
+		expect(exception!.data.endDate).toEqual(new Date("2026-01-22T10:30:00Z"))
 	})
 
 	test("caches events within the same refresh cycle", async () => {
@@ -512,3 +533,69 @@ describe("computeSignals", () => {
 		expect(computeSignals(event, now, "Asia/Tokyo").urgency).toBe(0.2)
 	})
 })
+
+describe("CalDavSource feed item slots", () => {
+	const EXPECTED_SLOT_NAMES = ["insight", "preparation", "crossSource"]
+
+	test("timed event has all three slots with null content", async () => {
+		const objects: Record<string, CalDavDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = createSource(client)
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+
+		expect(items).toHaveLength(1)
+		const item = items[0]!
+		expect(item.slots).toBeDefined()
+		expect(Object.keys(item.slots!).sort()).toEqual([...EXPECTED_SLOT_NAMES].sort())
+
+		for (const name of EXPECTED_SLOT_NAMES) {
+			const slot = item.slots![name]!
+			expect(slot.content).toBeNull()
+			expect(typeof slot.description).toBe("string")
+			expect(slot.description.length).toBeGreaterThan(0)
+		}
+	})
+
+	test("all-day event has all three slots with null content", async () => {
+		const objects: Record<string, CalDavDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/allday.ics", data: loadFixture("all-day-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = createSource(client)
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+
+		expect(items).toHaveLength(1)
+		const item = items[0]!
+		expect(item.data.isAllDay).toBe(true)
+		expect(item.slots).toBeDefined()
+		expect(Object.keys(item.slots!).sort()).toEqual([...EXPECTED_SLOT_NAMES].sort())
+
+		for (const name of EXPECTED_SLOT_NAMES) {
+			expect(item.slots![name]!.content).toBeNull()
+		}
+	})
+
+	test("cancelled event has all three slots with null content", async () => {
+		const objects: Record<string, CalDavDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/cancelled.ics", data: loadFixture("cancelled-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = createSource(client)
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+
+		expect(items).toHaveLength(1)
+		const item = items[0]!
+		expect(item.data.status).toBe("cancelled")
+		expect(item.slots).toBeDefined()
+		expect(Object.keys(item.slots!).sort()).toEqual([...EXPECTED_SLOT_NAMES].sort())
+
+		for (const name of EXPECTED_SLOT_NAMES) {
+			expect(item.slots![name]!.content).toBeNull()
+		}
+	})
+})

packages/aris-source-caldav/src/caldav-source.ts

@@ -1,4 +1,4 @@
-import type { ActionDefinition, ContextEntry, FeedItemSignals, FeedSource } from "@aris/core"
+import type { ActionDefinition, ContextEntry, FeedItemSignals, FeedSource, Slot } from "@aris/core"
 
 import { Context, TimeRelevance, UnknownActionError } from "@aris/core"
 import { DAVClient } from "tsdav"
@@ -7,6 +7,9 @@ import type { CalDavDAVClient, CalDavEventData, CalDavFeedItem } from "./types.t
 
 import { CalDavCalendarKey, type CalendarContext } from "./calendar-context.ts"
 import { parseICalEvents } from "./ical-parser.ts"
+import crossSourcePrompt from "./prompts/cross-source.txt"
+import insightPrompt from "./prompts/insight.txt"
+import preparationPrompt from "./prompts/preparation.txt"
 import { CalDavEventStatus, CalDavFeedItemType } from "./types.ts"
 
 // -- Source options --
@@ -184,7 +187,7 @@ export class CalDavSource implements FeedSource<CalDavFeedItem> {
 			for (const obj of objects) {
 				if (typeof obj.data !== "string") continue
 
-				const events = parseICalEvents(obj.data, calendarName)
+				const events = parseICalEvents(obj.data, calendarName, { start, end })
 				for (const event of events) {
 					allEvents.push(event)
 				}
@@ -340,6 +343,14 @@ export function computeSignals(
 	return { urgency: 0.2, timeRelevance: TimeRelevance.Ambient }
 }
 
+function createEventSlots(): Record<string, Slot> {
+	return {
+		insight: { description: insightPrompt, content: null },
+		preparation: { description: preparationPrompt, content: null },
+		crossSource: { description: crossSourcePrompt, content: null },
+	}
+}
+
 function createFeedItem(event: CalDavEventData, now: Date, timeZone?: string): CalDavFeedItem {
 	return {
 		id: `caldav-event-${event.uid}${event.recurrenceId ? `-${event.recurrenceId}` : ""}`,
@@ -347,5 +358,6 @@ function createFeedItem(event: CalDavEventData, now: Date, timeZone?: string): C
 		timestamp: now,
 		data: event,
 		signals: computeSignals(event, now, timeZone),
+		slots: createEventSlots(),
 	}
 }

packages/aris-source-caldav/src/ical-parser.test.ts

@@ -105,3 +105,94 @@ describe("parseICalEvents", () => {
 		expect(events[0]!.status).toBe("cancelled")
 	})
 })
+
+describe("parseICalEvents with timeRange (recurrence expansion)", () => {
+	test("expands weekly recurring event into occurrences within range", () => {
+		// weekly-recurring.ics: DTSTART 2026-01-01 (Thu), FREQ=WEEKLY;BYDAY=TH;COUNT=10
+		// Occurrences: Jan 1, 8, 15, 22, 29, Feb 5, 12, 19, 26, Mar 5
+		// Query window: Jan 14 – Jan 23 → should get Jan 15 and Jan 22
+		const events = parseICalEvents(loadFixture("weekly-recurring.ics"), "Work", {
+			start: new Date("2026-01-14T00:00:00Z"),
+			end: new Date("2026-01-23T00:00:00Z"),
+		})
+
+		expect(events).toHaveLength(2)
+		expect(events[0]!.startDate).toEqual(new Date("2026-01-15T10:00:00Z"))
+		expect(events[0]!.endDate).toEqual(new Date("2026-01-15T11:00:00Z"))
+		expect(events[1]!.startDate).toEqual(new Date("2026-01-22T10:00:00Z"))
+		expect(events[1]!.endDate).toEqual(new Date("2026-01-22T11:00:00Z"))
+
+		// All occurrences share the same UID and metadata
+		for (const event of events) {
+			expect(event.uid).toBe("weekly-001@test")
+			expect(event.title).toBe("Weekly Team Meeting")
+			expect(event.location).toBe("Room B")
+			expect(event.calendarName).toBe("Work")
+		}
+	})
+
+	test("returns empty array when no occurrences fall in range", () => {
+		// Query window: Dec 2025 — before the first occurrence
+		const events = parseICalEvents(loadFixture("weekly-recurring.ics"), null, {
+			start: new Date("2025-12-01T00:00:00Z"),
+			end: new Date("2025-12-31T00:00:00Z"),
+		})
+
+		expect(events).toHaveLength(0)
+	})
+
+	test("applies exception overrides during expansion", () => {
+		// weekly-recurring-with-exception.ics:
+		//   Master: DTSTART 2026-01-01 (Thu) 14:00, FREQ=WEEKLY;BYDAY=TH;COUNT=8
+		//   Exception: RECURRENCE-ID 2026-01-15T14:00 → moved to 16:00-17:00, title changed
+		// Query window: Jan 14 – Jan 16 → should get the exception occurrence for Jan 15
+		const events = parseICalEvents(loadFixture("weekly-recurring-with-exception.ics"), "Work", {
+			start: new Date("2026-01-14T00:00:00Z"),
+			end: new Date("2026-01-16T00:00:00Z"),
+		})
+
+		expect(events).toHaveLength(1)
+		expect(events[0]!.title).toBe("Standup (rescheduled)")
+		expect(events[0]!.startDate).toEqual(new Date("2026-01-15T16:00:00Z"))
+		expect(events[0]!.endDate).toEqual(new Date("2026-01-15T17:00:00Z"))
+	})
+
+	test("expands recurring all-day events", () => {
+		// daily-recurring-allday.ics: DTSTART 2026-01-12, FREQ=DAILY;COUNT=7
+		// Occurrences: Jan 12, 13, 14, 15, 16, 17, 18
+		// Query window: Jan 14 – Jan 17 → should get Jan 14, 15, 16
+		const events = parseICalEvents(loadFixture("daily-recurring-allday.ics"), null, {
+			start: new Date("2026-01-14T00:00:00Z"),
+			end: new Date("2026-01-17T00:00:00Z"),
+		})
+
+		expect(events).toHaveLength(3)
+		for (const event of events) {
+			expect(event.isAllDay).toBe(true)
+			expect(event.title).toBe("Daily Reminder")
+		}
+	})
+
+	test("non-recurring events are filtered by range", () => {
+		// single-event.ics: 2026-01-15T14:00 – 15:00
+		// Query window that includes it
+		const included = parseICalEvents(loadFixture("single-event.ics"), null, {
+			start: new Date("2026-01-15T00:00:00Z"),
+			end: new Date("2026-01-16T00:00:00Z"),
+		})
+		expect(included).toHaveLength(1)
+
+		// Query window that excludes it
+		const excluded = parseICalEvents(loadFixture("single-event.ics"), null, {
+			start: new Date("2026-01-16T00:00:00Z"),
+			end: new Date("2026-01-17T00:00:00Z"),
+		})
+		expect(excluded).toHaveLength(0)
+	})
+
+	test("without timeRange, recurring events return raw VEVENTs (legacy)", () => {
+		// Legacy behavior: no expansion, just returns the VEVENT components as-is
+		const events = parseICalEvents(loadFixture("recurring-event.ics"), "Team")
+		expect(events).toHaveLength(2)
+	})
+})

packages/aris-source-caldav/src/ical-parser.ts

@@ -9,21 +9,191 @@ import {
 	type CalDavEventData,
 } from "./types.ts"
 
+export interface ICalTimeRange {
+	start: Date
+	end: Date
+}
+
 /**
- * Parses a raw iCalendar string and extracts all VEVENT components
+ * Safety cap to prevent runaway iteration on pathological recurrence rules.
+ * Each iteration is pure date math (no I/O), so a high cap is fine.
+ * 10,000 covers a daily event with DTSTART ~27 years in the past.
+ */
+const MAX_RECURRENCE_ITERATIONS = 10_000
+
+/**
+ * Parses a raw iCalendar string and extracts VEVENT components
  * into CalDavEventData objects.
  *
+ * When a timeRange is provided, recurring events are expanded into
+ * individual occurrences within that range. Without a timeRange,
+ * each VEVENT component is returned as-is (legacy behavior).
+ *
  * @param icsData - Raw iCalendar string from a CalDAV response
  * @param calendarName - Display name of the calendar this event belongs to
+ * @param timeRange - When set, expand recurrences and filter to this window
  */
-export function parseICalEvents(icsData: string, calendarName: string | null): CalDavEventData[] {
+export function parseICalEvents(
+	icsData: string,
+	calendarName: string | null,
+	timeRange?: ICalTimeRange,
+): CalDavEventData[] {
 	const jcal = ICAL.parse(icsData)
 	const comp = new ICAL.Component(jcal)
 	const vevents = comp.getAllSubcomponents("vevent")
 
-	return vevents.map((vevent: InstanceType<typeof ICAL.Component>) =>
-		parseVEvent(vevent, calendarName),
-	)
+	if (!timeRange) {
+		return vevents.map((vevent: InstanceType<typeof ICAL.Component>) =>
+			parseVEvent(vevent, calendarName),
+		)
+	}
+
+	// Group VEVENTs by UID: master + exceptions
+	const byUid = new Map<
+		string,
+		{
+			master: InstanceType<typeof ICAL.Component> | null
+			exceptions: InstanceType<typeof ICAL.Component>[]
+		}
+	>()
+
+	for (const vevent of vevents as InstanceType<typeof ICAL.Component>[]) {
+		const uid = vevent.getFirstPropertyValue("uid") as string | null
+		if (!uid) continue
+
+		const hasRecurrenceId = vevent.getFirstPropertyValue("recurrence-id") !== null
+		let group = byUid.get(uid)
+		if (!group) {
+			group = { master: null, exceptions: [] }
+			byUid.set(uid, group)
+		}
+
+		if (hasRecurrenceId) {
+			group.exceptions.push(vevent)
+		} else {
+			group.master = vevent
+		}
+	}
+
+	const results: CalDavEventData[] = []
+	const rangeStart = ICAL.Time.fromJSDate(timeRange.start, true)
+	const rangeEnd = ICAL.Time.fromJSDate(timeRange.end, true)
+
+	for (const group of byUid.values()) {
+		if (!group.master) {
+			// Orphan exceptions — parse them directly if they fall in range
+			for (const exc of group.exceptions) {
+				const parsed = parseVEvent(exc, calendarName)
+				if (overlapsRange(parsed, timeRange)) {
+					results.push(parsed)
+				}
+			}
+			continue
+		}
+
+		const masterEvent = new ICAL.Event(group.master)
+
+		// Register exceptions so getOccurrenceDetails resolves them
+		for (const exc of group.exceptions) {
+			masterEvent.relateException(exc)
+		}
+
+		if (!masterEvent.isRecurring()) {
+			const parsed = parseVEvent(group.master, calendarName)
+			if (overlapsRange(parsed, timeRange)) {
+				results.push(parsed)
+			}
+			// Also include standalone exceptions for non-recurring events
+			for (const exc of group.exceptions) {
+				const parsedExc = parseVEvent(exc, calendarName)
+				if (overlapsRange(parsedExc, timeRange)) {
+					results.push(parsedExc)
+				}
+			}
+			continue
+		}
+
+		// Expand recurring event occurrences within the time range.
+		// The iterator must start from DTSTART (not rangeStart) because
+		// ical.js needs to walk the recurrence rule grid from the original
+		// anchor. We cap iterations to avoid runaway expansion on
+		// pathological rules.
+		const iter = masterEvent.iterator()
+		let next: InstanceType<typeof ICAL.Time> | null = iter.next()
+		let iterations = 0
+
+		while (next) {
+			if (++iterations > MAX_RECURRENCE_ITERATIONS) {
+				console.warn(
+					`[aris.caldav] Recurrence expansion for "${masterEvent.uid}" hit iteration limit (${MAX_RECURRENCE_ITERATIONS}), stopping`,
+				)
+				break
+			}
+
+			// Stop once we're past the range end
+			if (next.compare(rangeEnd) >= 0) break
+
+			const details = masterEvent.getOccurrenceDetails(next)
+			const occEnd = details.endDate
+
+			// Skip occurrences that end before the range starts
+			if (occEnd.compare(rangeStart) <= 0) {
+				next = iter.next()
+				continue
+			}
+
+			const occEvent = details.item
+			const occComponent = occEvent.component
+
+			const parsed = parseVEventWithDates(
+				occComponent,
+				calendarName,
+				details.startDate.toJSDate(),
+				details.endDate.toJSDate(),
+				details.recurrenceId ? details.recurrenceId.toString() : null,
+			)
+			results.push(parsed)
+
+			next = iter.next()
+		}
+	}
+
+	return results
+}
+
+function overlapsRange(event: CalDavEventData, range: ICalTimeRange): boolean {
+	return event.startDate < range.end && event.endDate > range.start
+}
+
+/**
+ * Parse a VEVENT component, overriding start/end/recurrenceId with
+ * values from recurrence expansion.
+ */
+function parseVEventWithDates(
+	vevent: InstanceType<typeof ICAL.Component>,
+	calendarName: string | null,
+	startDate: Date,
+	endDate: Date,
+	recurrenceId: string | null,
+): CalDavEventData {
+	const event = new ICAL.Event(vevent)
+
+	return {
+		uid: event.uid ?? "",
+		title: event.summary ?? "",
+		startDate,
+		endDate,
+		isAllDay: event.startDate?.isDate ?? false,
+		location: event.location ?? null,
+		description: event.description ?? null,
+		calendarName,
+		status: parseStatus(asStringOrNull(vevent.getFirstPropertyValue("status"))),
+		url: asStringOrNull(vevent.getFirstPropertyValue("url")),
+		organizer: parseOrganizer(asStringOrNull(event.organizer), vevent),
+		attendees: parseAttendees(Array.isArray(event.attendees) ? event.attendees : []),
+		alarms: parseAlarms(vevent),
+		recurrenceId,
+	}
 }
 
 function parseVEvent(

packages/aris-source-caldav/src/index.ts

@@ -1,6 +1,6 @@
 export { CalDavCalendarKey, type CalendarContext } from "./calendar-context.ts"
 export { CalDavSource, type CalDavSourceOptions } from "./caldav-source.ts"
-export { parseICalEvents } from "./ical-parser.ts"
+export { parseICalEvents, type ICalTimeRange } from "./ical-parser.ts"
 export {
 	AttendeeRole,
 	AttendeeStatus,

packages/aris-source-caldav/src/prompts/cross-source.txt

@@ -0,0 +1,8 @@
+If other feed data (weather, transit, nearby events) would disrupt or materially affect this event, state the connection in one sentence. Infer whether the event is indoor/outdoor/virtual from the title and location. Weather is only relevant if it affects getting to the event or the activity itself (e.g., rain for outdoor events, extreme conditions for physical activities). Return null for indoor or virtual events where weather has no impact. Do not fabricate information you don't have — only reference data present in the feed.
+
+Examples:
+- "rain expected at 5pm — bring an umbrella for the walk to Tooley Street"
+- "Northern line has delays — leave 15 minutes early"
+- "your next event is across town — the 40 min gap may not be enough"
+- null (indoor guitar class with wind outside — weather doesn't affect the event)
+- null

packages/aris-source-caldav/src/prompts/insight.txt

@@ -0,0 +1,7 @@
+One sentence of actionable insight the user can't already see from the event title, time, and location. Do not restate event details. Do not fabricate information you don't have. Return null if there's nothing non-obvious to say.
+
+Examples:
+- "you have 2 hours free before this starts"
+- "all 8 attendees accepted — expect a full room"
+- "third time this has been rescheduled"
+- null

packages/aris-source-caldav/src/prompts/preparation.txt

@@ -0,0 +1,6 @@
+A concrete preparation step — something the user should do, bring, or review before this event. Infer only from available event and feed data. Do not restate event details. Do not fabricate information you don't have. Return null if no useful preparation comes to mind.
+
+Examples:
+- "different building from your previous meeting — allow travel time"
+- "recurring meeting you declined last week — check if you need to attend"
+- null

packages/aris-source-caldav/src/text.d.ts

@@ -0,0 +1,4 @@
+declare module "*.txt" {
+	const content: string
+	export default content
+}

packages/aris-source-weatherkit/scripts/query.ts

@@ -0,0 +1,181 @@
+#!/usr/bin/env bun
+
+/**
+ * Interactive CLI script to query WeatherKit directly.
+ * Prompts for credentials, coordinates, and optional settings,
+ * then prints the raw API response and processed feed items.
+ * Caches credentials locally and writes response JSON to a file.
+ *
+ * Usage: bun packages/aris-source-weatherkit/scripts/query.ts
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { createInterface } from "node:readline/promises"
+
+import { Context } from "@aris/core"
+import { LocationKey } from "@aris/source-location"
+
+import { DefaultWeatherKitClient } from "../src/weatherkit"
+import { WeatherSource, Units } from "../src/weather-source"
+
+const SCRIPT_DIR = import.meta.dirname
+const CACHE_DIR = join(SCRIPT_DIR, ".cache")
+const CREDS_PATH = join(CACHE_DIR, "credentials.json")
+
+interface CachedCredentials {
+	teamId: string
+	serviceId: string
+	keyId: string
+	privateKey: string
+	lat?: number
+	lng?: number
+}
+
+function loadCachedCredentials(): CachedCredentials | null {
+	if (!existsSync(CREDS_PATH)) return null
+	try {
+		return JSON.parse(readFileSync(CREDS_PATH, "utf-8")) as CachedCredentials
+	} catch {
+		return null
+	}
+}
+
+function saveCachedCredentials(creds: CachedCredentials): void {
+	mkdirSync(CACHE_DIR, { recursive: true })
+	writeFileSync(CREDS_PATH, JSON.stringify(creds))
+}
+
+const rl = createInterface({ input: process.stdin, output: process.stdout })
+
+async function prompt(question: string, defaultValue?: string): Promise<string> {
+	const suffix = defaultValue ? ` [${defaultValue}]` : ""
+	const answer = await rl.question(`${question}${suffix}: `)
+	return answer.trim() || defaultValue || ""
+}
+
+async function main(): Promise<void> {
+	console.log("=== WeatherKit Query Tool ===\n")
+
+	const cached = loadCachedCredentials()
+
+	let teamId: string
+	let serviceId: string
+	let keyId: string
+	let privateKey: string
+
+	if (cached) {
+		console.log(`Using cached credentials from ${CREDS_PATH}`)
+		console.log(`  Team ID:    ${cached.teamId}`)
+		console.log(`  Service ID: ${cached.serviceId}`)
+		console.log(`  Key ID:     ${cached.keyId}\n`)
+
+		const useCached = await prompt("Use cached credentials? (y/n)", "y")
+		if (useCached.toLowerCase() === "y") {
+			teamId = cached.teamId
+			serviceId = cached.serviceId
+			keyId = cached.keyId
+			privateKey = cached.privateKey
+		} else {
+			;({ teamId, serviceId, keyId, privateKey } = await promptCredentials())
+		}
+	} else {
+		console.log(`Credentials will be cached to ${CREDS_PATH}\n`)
+		;({ teamId, serviceId, keyId, privateKey } = await promptCredentials())
+	}
+
+	// Location
+	const defaultLat = cached?.lat?.toString() ?? "37.7749"
+	const defaultLng = cached?.lng?.toString() ?? "-122.4194"
+	const lat = parseFloat(await prompt("Latitude", defaultLat))
+	const lng = parseFloat(await prompt("Longitude", defaultLng))
+
+	if (Number.isNaN(lat) || Number.isNaN(lng)) {
+		console.error("Invalid coordinates")
+		process.exit(1)
+	}
+
+	const credentials = { privateKey, keyId, teamId, serviceId }
+	saveCachedCredentials({ ...credentials, lat, lng })
+
+	// Options
+	const unitsInput = await prompt("Units (metric/imperial)", "metric")
+	const units = unitsInput === "imperial" ? Units.imperial : Units.metric
+
+	// Raw API query
+	console.log("\n--- Raw WeatherKit Response ---\n")
+	const client = new DefaultWeatherKitClient(credentials)
+	const raw = await client.fetch({ lat, lng })
+	console.log(JSON.stringify(raw, null, 2))
+
+	// Write JSON to file
+	const outPath = join(CACHE_DIR, "response.json")
+	writeFileSync(outPath, JSON.stringify(raw))
+	console.log(`\nResponse written to ${outPath}`)
+
+	// Processed feed items via WeatherSource
+	console.log("\n--- Processed Feed Items ---\n")
+	const source = new WeatherSource({ client, units })
+	const context = new Context()
+	context.set([[LocationKey, { lat, lng, accuracy: 10, timestamp: new Date() }]])
+
+	const items = await source.fetchItems(context)
+	for (const item of items) {
+		console.log(`[${item.type}] ${item.id}`)
+		console.log(`  signals: ${JSON.stringify(item.signals)}`)
+		if (item.slots) {
+			console.log(`  slots:`)
+			for (const [name, slot] of Object.entries(item.slots)) {
+				console.log(`    ${name}: "${slot.description}" -> ${slot.content ?? "(unfilled)"}`)
+			}
+		}
+		console.log(`  data: ${JSON.stringify(item.data, null, 4)}`)
+		console.log()
+	}
+
+	const feedPath = join(CACHE_DIR, "feed-items.json")
+	writeFileSync(feedPath, JSON.stringify(items, null, 2))
+	console.log(`Feed items written to ${feedPath}`)
+	console.log(`Total: ${items.length} items`)
+	rl.close()
+}
+
+async function promptCredentials(): Promise<CachedCredentials> {
+	const teamId = await prompt("Apple Team ID")
+	if (!teamId) {
+		console.error("Team ID is required")
+		process.exit(1)
+	}
+
+	const serviceId = await prompt("Service ID")
+	if (!serviceId) {
+		console.error("Service ID is required")
+		process.exit(1)
+	}
+
+	const keyId = await prompt("Key ID")
+	if (!keyId) {
+		console.error("Key ID is required")
+		process.exit(1)
+	}
+
+	console.log("\nPaste your private key (PEM format). Enter an empty line when done:")
+	const keyLines: string[] = []
+	for await (const line of rl) {
+		if (line.trim() === "") break
+		keyLines.push(line)
+	}
+	const privateKey = keyLines.join("\n")
+	if (!privateKey) {
+		console.error("Private key is required")
+		process.exit(1)
+	}
+
+	return { teamId, serviceId, keyId, privateKey }
+}
+
+main().catch((err) => {
+	console.error("Error:", err)
+	rl.close()
+	process.exit(1)
+})

packages/aris-source-weatherkit/src/prompts/current-weather-insight.txt

@@ -0,0 +1,7 @@
+Max 12 words. Plain language, no hedging. Now + what's next.
+
+Examples:
+- "Clear tonight, warming up. Rain by Saturday."
+- "Clearing soon with strong winds overnight. Light rain Thursday."
+- "Sunny all day. Grab sunscreen."
+- "Cloudy tonight, warming to 15°. Rain Monday."

packages/aris-source-weatherkit/src/weather-source.test.ts

@@ -176,6 +176,34 @@ describe("WeatherSource", () => {
 
 			expect(uniqueIds.size).toBe(ids.length)
 		})
+
+		test("current weather item has insight slot", async () => {
+			const source = new WeatherSource({ client: mockClient })
+			const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
+
+			const items = await source.fetchItems(context)
+			const currentItem = items.find((i) => i.type === WeatherFeedItemType.Current)
+
+			expect(currentItem).toBeDefined()
+			expect(currentItem!.slots).toBeDefined()
+			expect(currentItem!.slots!.insight).toBeDefined()
+			expect(currentItem!.slots!.insight!.description).toBeString()
+			expect(currentItem!.slots!.insight!.description.length).toBeGreaterThan(0)
+			expect(currentItem!.slots!.insight!.content).toBeNull()
+		})
+
+		test("non-current items do not have slots", async () => {
+			const source = new WeatherSource({ client: mockClient })
+			const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
+
+			const items = await source.fetchItems(context)
+			const nonCurrentItems = items.filter((i) => i.type !== WeatherFeedItemType.Current)
+
+			expect(nonCurrentItems.length).toBeGreaterThan(0)
+			for (const item of nonCurrentItems) {
+				expect(item.slots).toBeUndefined()
+			}
+		})
 	})
 
 	describe("no reactive methods", () => {

packages/aris-source-weatherkit/src/weather-source.ts

@@ -4,6 +4,7 @@ import { Context, TimeRelevance, UnknownActionError } from "@aris/core"
 import { LocationKey } from "@aris/source-location"
 
 import { WeatherFeedItemType, type WeatherFeedItem } from "./feed-items"
+import currentWeatherInsightPrompt from "./prompts/current-weather-insight.txt"
 import { WeatherKey, type Weather } from "./weather-context"
 import {
 	DefaultWeatherKitClient,
@@ -309,6 +310,12 @@ function createCurrentWeatherFeedItem(
 			windSpeed: convertSpeed(current.windSpeed, units),
 		},
 		signals,
+		slots: {
+			insight: {
+				description: currentWeatherInsightPrompt,
+				content: null,
+			},
+		},
 	}
 }