fix(waitlist): add delay before email to avoid rate limit

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

.claude/skills/gpg-commit-signing/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: gpg-commit-signing
+description: Sign git commits with GPG in non-interactive environments. Use when committing code and the `GPG_PRIVATE_KEY_PASSPHRASE` environment variable is available. Triggers on "commit", "sign commit", "GPG", "git commit -S", or any git operation requiring signed commits.
+---
+
+# GPG Commit Signing
+
+Sign commits in headless/non-interactive environments where `/dev/tty` is unavailable.
+
+## Workflow
+
+1. Check whether `GPG_PRIVATE_KEY_PASSPHRASE` is set:
+
+   ```bash
+   test -n "$GPG_PRIVATE_KEY_PASSPHRASE" && echo "available" || echo "not set"
+   ```
+
+   If not set, skip signing — commit without `-S`.
+
+2. Try a direct signed commit first — the environment may already have loopback pinentry configured:
+
+   ```bash
+   git commit -S -m "message"
+   ```
+
+   If this succeeds, no further steps are needed.
+
+3. If step 2 fails with a `/dev/tty` error, use `--pinentry-mode loopback` via a wrapper script:
+
+   ```bash
+   printf '#!/bin/sh\ngpg --batch --pinentry-mode loopback --passphrase "$GPG_PRIVATE_KEY_PASSPHRASE" "$@"\n' > /tmp/gpg-sign.sh
+   chmod +x /tmp/gpg-sign.sh
+   git -c gpg.program=/tmp/gpg-sign.sh commit -S -m "message"
+   rm /tmp/gpg-sign.sh
+   ```
+
+   This passes the passphrase directly to gpg on each signing invocation, bypassing the need for a configured gpg-agent.
+
+## Anti-patterns
+
+- Do not echo or log `GPG_PRIVATE_KEY_PASSPHRASE`.
+- Do not commit without `-S` when the passphrase is available — the project expects signed commits.
+- Do not leave wrapper scripts on disk after committing.

apps/aris-backend/.env.example

@@ -7,6 +7,11 @@ BETTER_AUTH_SECRET=
 # Base URL of the backend
 BETTER_AUTH_URL=http://localhost:3000
 
+# OpenRouter (LLM feed enhancement)
+OPENROUTER_API_KEY=
+# Optional: override the default model (default: openai/gpt-4.1-mini)
+# OPENROUTER_MODEL=openai/gpt-4.1-mini
+
 # Apple WeatherKit credentials
 WEATHERKIT_PRIVATE_KEY=
 WEATHERKIT_KEY_ID=

apps/aris-backend/package.json

@@ -10,9 +10,12 @@
 	},
 	"dependencies": {
 		"@aris/core": "workspace:*",
+		"@aris/source-caldav": "workspace:*",
+		"@aris/source-google-calendar": "workspace:*",
 		"@aris/source-location": "workspace:*",
 		"@aris/source-tfl": "workspace:*",
 		"@aris/source-weatherkit": "workspace:*",
+		"@openrouter/sdk": "^0.9.11",
 		"arktype": "^2.1.29",
 		"better-auth": "^1",
 		"hono": "^4",

apps/aris-backend/src/enhancement/enhance-feed.ts

@@ -0,0 +1,51 @@
+import type { FeedItem } from "@aris/core"
+
+import type { LlmClient } from "./llm-client.ts"
+
+import { mergeEnhancement } from "./merge.ts"
+import { buildPrompt, hasUnfilledSlots } from "./prompt-builder.ts"
+
+/** Takes feed items, returns enhanced feed items. */
+export type FeedEnhancer = (items: FeedItem[]) => Promise<FeedItem[]>
+
+export interface FeedEnhancerConfig {
+	client: LlmClient
+	/** Defaults to Date.now — override for testing */
+	clock?: () => Date
+}
+
+/**
+ * Creates a FeedEnhancer that uses the provided LlmClient.
+ *
+ * Skips the LLM call when no items have unfilled slots.
+ * Returns items unchanged on LLM failure.
+ */
+export function createFeedEnhancer(config: FeedEnhancerConfig): FeedEnhancer {
+	const { client } = config
+	const clock = config.clock ?? (() => new Date())
+
+	return async function enhanceFeed(items) {
+		if (!hasUnfilledSlots(items)) {
+			return items
+		}
+
+		const currentTime = clock()
+		const { systemPrompt, userMessage } = buildPrompt(items, currentTime)
+
+		let result
+		try {
+			result = await client.enhance({ systemPrompt, userMessage })
+		} catch (err) {
+			console.error("[enhancement] LLM call failed:", err)
+			result = null
+		}
+
+		if (!result) {
+			return items
+		}
+
+		return mergeEnhancement(items, result, currentTime)
+	}
+}
+
+

apps/aris-backend/src/enhancement/llm-client.ts

@@ -0,0 +1,71 @@
+import { OpenRouter } from "@openrouter/sdk"
+
+import type { EnhancementResult } from "./schema.ts"
+
+import { enhancementResultJsonSchema, parseEnhancementResult } from "./schema.ts"
+
+const DEFAULT_MODEL = "openai/gpt-4.1-mini"
+const DEFAULT_TIMEOUT_MS = 30_000
+
+export interface LlmClientConfig {
+	apiKey: string
+	model?: string
+	timeoutMs?: number
+}
+
+export interface LlmClientRequest {
+	systemPrompt: string
+	userMessage: string
+}
+
+export interface LlmClient {
+	enhance(request: LlmClientRequest): Promise<EnhancementResult | null>
+}
+
+/**
+ * Creates a reusable LLM client backed by OpenRouter.
+ * The OpenRouter SDK instance is created once and reused across calls.
+ */
+export function createLlmClient(config: LlmClientConfig): LlmClient {
+	const client = new OpenRouter({
+		apiKey: config.apiKey,
+		timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+	})
+	const model = config.model ?? DEFAULT_MODEL
+
+	return {
+		async enhance(request) {
+			const response = await client.chat.send({
+				chatGenerationParams: {
+					model,
+					messages: [
+						{ role: "system" as const, content: request.systemPrompt },
+						{ role: "user" as const, content: request.userMessage },
+					],
+					responseFormat: {
+						type: "json_schema" as const,
+						jsonSchema: {
+							name: "enhancement_result",
+							strict: true,
+							schema: enhancementResultJsonSchema,
+						},
+					},
+					stream: false,
+				},
+			})
+
+			const content = response.choices?.[0]?.message?.content
+			if (typeof content !== "string") {
+				console.warn("[enhancement] LLM returned no content in response")
+				return null
+			}
+
+			const result = parseEnhancementResult(content)
+			if (!result) {
+				console.warn("[enhancement] Failed to parse LLM response:", content)
+			}
+
+			return result
+		},
+	}
+}

apps/aris-backend/src/enhancement/merge.test.ts

@@ -0,0 +1,150 @@
+import type { FeedItem } from "@aris/core"
+
+import { describe, expect, test } from "bun:test"
+
+import type { EnhancementResult } from "./schema.ts"
+
+import { mergeEnhancement } from "./merge.ts"
+
+function makeItem(overrides: Partial<FeedItem> = {}): FeedItem {
+	return {
+		id: "item-1",
+		type: "test",
+		timestamp: new Date("2025-01-01T00:00:00Z"),
+		data: { value: 42 },
+		...overrides,
+	}
+}
+
+const now = new Date("2025-06-01T12:00:00Z")
+
+describe("mergeEnhancement", () => {
+	test("fills matching slots", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "Weather insight", content: null },
+			},
+		})
+		const result: EnhancementResult = {
+			slotFills: {
+				"item-1": { insight: "Rain after 3pm" },
+			},
+			syntheticItems: [],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged).toHaveLength(1)
+		expect(merged[0]!.slots!.insight!.content).toBe("Rain after 3pm")
+		// Description preserved
+		expect(merged[0]!.slots!.insight!.description).toBe("Weather insight")
+	})
+
+	test("does not mutate original items", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "test", content: null },
+			},
+		})
+		const result: EnhancementResult = {
+			slotFills: { "item-1": { insight: "filled" } },
+			syntheticItems: [],
+		}
+
+		mergeEnhancement([item], result, now)
+
+		expect(item.slots!.insight!.content).toBeNull()
+	})
+
+	test("ignores fills for non-existent items", () => {
+		const item = makeItem()
+		const result: EnhancementResult = {
+			slotFills: { "non-existent": { insight: "text" } },
+			syntheticItems: [],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged).toHaveLength(1)
+		expect(merged[0]!.id).toBe("item-1")
+	})
+
+	test("ignores fills for non-existent slots", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "test", content: null },
+			},
+		})
+		const result: EnhancementResult = {
+			slotFills: { "item-1": { "non-existent-slot": "text" } },
+			syntheticItems: [],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged[0]!.slots!.insight!.content).toBeNull()
+	})
+
+	test("skips null fills", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "test", content: null },
+			},
+		})
+		const result: EnhancementResult = {
+			slotFills: { "item-1": { insight: null } },
+			syntheticItems: [],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged[0]!.slots!.insight!.content).toBeNull()
+	})
+
+	test("passes through items without slots unchanged", () => {
+		const item = makeItem()
+		const result: EnhancementResult = {
+			slotFills: {},
+			syntheticItems: [],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged[0]).toBe(item)
+	})
+
+	test("appends synthetic items with backfilled fields", () => {
+		const item = makeItem()
+		const result: EnhancementResult = {
+			slotFills: {},
+			syntheticItems: [
+				{
+					id: "briefing-morning",
+					type: "briefing",
+					text: "Light afternoon ahead.",
+				},
+			],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged).toHaveLength(2)
+		expect(merged[1]!.id).toBe("briefing-morning")
+		expect(merged[1]!.type).toBe("briefing")
+		expect(merged[1]!.timestamp).toEqual(now)
+		expect(merged[1]!.data).toEqual({ text: "Light afternoon ahead." })
+	})
+
+	test("handles empty enhancement result", () => {
+		const item = makeItem()
+		const result: EnhancementResult = {
+			slotFills: {},
+			syntheticItems: [],
+		}
+
+		const merged = mergeEnhancement([item], result, now)
+
+		expect(merged).toHaveLength(1)
+		expect(merged[0]).toBe(item)
+	})
+})

apps/aris-backend/src/enhancement/merge.ts

@@ -0,0 +1,41 @@
+import type { FeedItem } from "@aris/core"
+
+import type { EnhancementResult } from "./schema.ts"
+
+/**
+ * Merges an EnhancementResult into feed items.
+ *
+ * - Writes slot content from slotFills into matching items
+ * - Appends synthetic items to the list
+ * - Returns a new array (no mutation)
+ * - Ignores fills for items/slots that don't exist
+ */
+export function mergeEnhancement(items: FeedItem[], result: EnhancementResult, currentTime: Date): FeedItem[] {
+	const merged = items.map((item) => {
+		const fills = result.slotFills[item.id]
+		if (!fills || !item.slots) return item
+
+		const mergedSlots = { ...item.slots }
+		let changed = false
+
+		for (const [slotName, content] of Object.entries(fills)) {
+			if (slotName in mergedSlots && content !== null) {
+				mergedSlots[slotName] = { ...mergedSlots[slotName]!, content }
+				changed = true
+			}
+		}
+
+		return changed ? { ...item, slots: mergedSlots } : item
+	})
+
+	for (const synthetic of result.syntheticItems) {
+		merged.push({
+			id: synthetic.id,
+			type: synthetic.type,
+			timestamp: currentTime,
+			data: { text: synthetic.text },
+		})
+	}
+
+	return merged
+}

apps/aris-backend/src/enhancement/prompt-builder.test.ts

@@ -0,0 +1,167 @@
+import type { FeedItem } from "@aris/core"
+
+import { describe, expect, test } from "bun:test"
+
+import { buildPrompt, hasUnfilledSlots } from "./prompt-builder.ts"
+
+function makeItem(overrides: Partial<FeedItem> = {}): FeedItem {
+	return {
+		id: "item-1",
+		type: "test",
+		timestamp: new Date("2025-01-01T00:00:00Z"),
+		data: { value: 42 },
+		...overrides,
+	}
+}
+
+function parseUserMessage(userMessage: string): Record<string, unknown> {
+	return JSON.parse(userMessage)
+}
+
+describe("hasUnfilledSlots", () => {
+	test("returns false for items without slots", () => {
+		expect(hasUnfilledSlots([makeItem()])).toBe(false)
+	})
+
+	test("returns false for items with all slots filled", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "test", content: "filled" },
+			},
+		})
+		expect(hasUnfilledSlots([item])).toBe(false)
+	})
+
+	test("returns true when at least one slot is unfilled", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "test", content: null },
+			},
+		})
+		expect(hasUnfilledSlots([item])).toBe(true)
+	})
+
+	test("returns false for empty array", () => {
+		expect(hasUnfilledSlots([])).toBe(false)
+	})
+})
+
+describe("buildPrompt", () => {
+	test("puts items with unfilled slots in items", () => {
+		const item = makeItem({
+			slots: {
+				insight: { description: "Weather insight", content: null },
+				filled: { description: "Already done", content: "done" },
+			},
+		})
+
+		const { userMessage } = buildPrompt([item], new Date("2025-06-01T12:00:00Z"))
+		const parsed = parseUserMessage(userMessage)
+
+		expect(parsed.items).toHaveLength(1)
+		expect((parsed.items as Array<Record<string, unknown>>)[0]!.id).toBe("item-1")
+		expect((parsed.items as Array<Record<string, unknown>>)[0]!.slots).toEqual({ insight: "Weather insight" })
+		expect((parsed.items as Array<Record<string, unknown>>)[0]!.type).toBeUndefined()
+		expect(parsed.context).toHaveLength(0)
+	})
+
+	test("puts slotless items in context", () => {
+		const withSlots = makeItem({
+			id: "with-slots",
+			slots: { insight: { description: "test", content: null } },
+		})
+		const withoutSlots = makeItem({ id: "no-slots" })
+
+		const { userMessage } = buildPrompt([withSlots, withoutSlots], new Date("2025-06-01T12:00:00Z"))
+		const parsed = parseUserMessage(userMessage)
+
+		expect(parsed.items).toHaveLength(1)
+		expect((parsed.items as Array<Record<string, unknown>>)[0]!.id).toBe("with-slots")
+		expect(parsed.context).toHaveLength(1)
+		expect((parsed.context as Array<Record<string, unknown>>)[0]!.id).toBe("no-slots")
+	})
+
+	test("includes time in ISO format", () => {
+		const { userMessage } = buildPrompt([], new Date("2025-06-01T12:00:00Z"))
+		const parsed = parseUserMessage(userMessage)
+
+		expect(parsed.time).toBe("2025-06-01T12:00:00.000Z")
+	})
+
+	test("system prompt is non-empty", () => {
+		const { systemPrompt } = buildPrompt([], new Date())
+		expect(systemPrompt.length).toBeGreaterThan(0)
+	})
+
+	test("includes schedule in system prompt", () => {
+		const calEvent = makeItem({
+			id: "cal-1",
+			type: "caldav-event",
+			data: {
+				title: "Team standup",
+				startDate: "2025-06-01T10:00:00Z",
+				endDate: "2025-06-01T10:30:00Z",
+				isAllDay: false,
+				location: null,
+			},
+			slots: {
+				insight: { description: "test", content: null },
+			},
+		})
+
+		const { systemPrompt } = buildPrompt([calEvent], new Date("2025-06-01T12:00:00Z"))
+
+		expect(systemPrompt).toContain("Schedule:\n")
+		expect(systemPrompt).toContain("Team standup")
+		expect(systemPrompt).toContain("10:00")
+	})
+
+	test("includes location in schedule", () => {
+		const calEvent = makeItem({
+			id: "cal-1",
+			type: "caldav-event",
+			data: {
+				title: "Therapy",
+				startDate: "2025-06-02T18:00:00Z",
+				endDate: "2025-06-02T19:00:00Z",
+				isAllDay: false,
+				location: "92 Tooley Street, London",
+			},
+		})
+
+		const { systemPrompt } = buildPrompt([calEvent], new Date("2025-06-01T12:00:00Z"))
+
+		expect(systemPrompt).toContain("Therapy @ 92 Tooley Street, London")
+	})
+
+	test("includes week calendar but omits schedule when no calendar items", () => {
+		const weatherItem = makeItem({
+			type: "weather-current",
+			data: { temperature: 14 },
+		})
+
+		const { systemPrompt } = buildPrompt([weatherItem], new Date("2025-06-01T12:00:00Z"))
+
+		expect(systemPrompt).toContain("Week:")
+		expect(systemPrompt).not.toContain("Schedule:")
+	})
+
+	test("user message is pure JSON", () => {
+		const calEvent = makeItem({
+			id: "cal-1",
+			type: "caldav-event",
+			data: {
+				title: "Budget Review",
+				startTime: "2025-06-01T14:00:00Z",
+				endTime: "2025-06-01T15:00:00Z",
+				isAllDay: false,
+				location: "https://meet.google.com/abc",
+			},
+		})
+
+		const { userMessage } = buildPrompt([calEvent], new Date("2025-06-01T12:00:00Z"))
+
+		expect(userMessage.startsWith("{")).toBe(true)
+		expect(() => JSON.parse(userMessage)).not.toThrow()
+	})
+})

apps/aris-backend/src/enhancement/prompt-builder.ts

@@ -0,0 +1,218 @@
+import type { FeedItem } from "@aris/core"
+
+import { CalDavFeedItemType } from "@aris/source-caldav"
+import { CalendarFeedItemType } from "@aris/source-google-calendar"
+
+import systemPromptBase from "./prompts/system.txt"
+
+const CALENDAR_ITEM_TYPES = new Set<string>([
+	CalDavFeedItemType.Event,
+	CalendarFeedItemType.Event,
+	CalendarFeedItemType.AllDay,
+])
+
+/**
+ * Builds the system prompt and user message for the enhancement harness.
+ *
+ * Includes a pre-computed mini calendar so the LLM doesn't have to
+ * parse timestamps to understand the user's schedule.
+ */
+export function buildPrompt(
+	items: FeedItem[],
+	currentTime: Date,
+): { systemPrompt: string; userMessage: string } {
+	const schedule = buildSchedule(items, currentTime)
+
+	const enhanceItems: Array<{
+		id: string
+		data: Record<string, unknown>
+		slots: Record<string, string>
+	}> = []
+	const contextItems: Array<{
+		id: string
+		type: string
+		data: Record<string, unknown>
+	}> = []
+
+	for (const item of items) {
+		const hasUnfilledSlots =
+			item.slots &&
+			Object.values(item.slots).some((slot) => slot.content === null)
+
+		if (hasUnfilledSlots) {
+			enhanceItems.push({
+				id: item.id,
+				data: item.data,
+				slots: Object.fromEntries(
+					Object.entries(item.slots!)
+						.filter(([, slot]) => slot.content === null)
+						.map(([name, slot]) => [name, slot.description]),
+				),
+			})
+		} else {
+			contextItems.push({
+				id: item.id,
+				type: item.type,
+				data: item.data,
+			})
+		}
+	}
+
+	const userMessage = JSON.stringify({
+		time: currentTime.toISOString(),
+		items: enhanceItems,
+		context: contextItems,
+	})
+
+	const weekCalendar = buildWeekCalendar(currentTime)
+	let systemPrompt = systemPromptBase
+	systemPrompt += `\n\nWeek:\n${weekCalendar}`
+	if (schedule) {
+		systemPrompt += `\n\nSchedule:\n${schedule}`
+	}
+
+	return { systemPrompt, userMessage }
+}
+
+/**
+ * Returns true if any item has at least one unfilled slot.
+ */
+export function hasUnfilledSlots(items: FeedItem[]): boolean {
+	return items.some(
+		(item) =>
+			item.slots &&
+			Object.values(item.slots).some((slot) => slot.content === null),
+	)
+}
+
+// -- Helpers --
+
+interface CalendarEntry {
+	date: Date
+	title: string
+	location: string | null
+	isAllDay: boolean
+	startTime: Date
+	endTime: Date
+}
+
+function toValidDate(value: unknown): Date | null {
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value
+	if (typeof value === "string" || typeof value === "number") {
+		const date = new Date(value)
+		return Number.isNaN(date.getTime()) ? null : date
+	}
+	return null
+}
+
+function extractCalendarEntry(item: FeedItem): CalendarEntry | null {
+	if (!CALENDAR_ITEM_TYPES.has(item.type)) return null
+
+	const d = item.data
+	const title = d.title
+	if (typeof title !== "string" || !title) return null
+
+	// CalDAV uses startDate/endDate, Google Calendar uses startTime/endTime
+	const startTime = toValidDate(d.startDate ?? d.startTime)
+	if (!startTime) return null
+
+	const endTime = toValidDate(d.endDate ?? d.endTime) ?? startTime
+
+	return {
+		date: startTime,
+		title,
+		location: typeof d.location === "string" ? d.location : null,
+		isAllDay: typeof d.isAllDay === "boolean" ? d.isAllDay : false,
+		startTime,
+		endTime,
+	}
+}
+
+const DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] as const
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const
+
+function pad2(n: number): string {
+	return n.toString().padStart(2, "0")
+}
+
+function formatTime(date: Date): string {
+	return `${pad2(date.getUTCHours())}:${pad2(date.getUTCMinutes())}`
+}
+
+function formatDayShort(date: Date): string {
+	return `${DAYS[date.getUTCDay()]}, ${date.getUTCDate()} ${MONTHS[date.getUTCMonth()]}`
+}
+
+function formatDayLabel(date: Date, currentTime: Date): string {
+	const currentDay = Date.UTC(currentTime.getUTCFullYear(), currentTime.getUTCMonth(), currentTime.getUTCDate())
+	const targetDay = Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate())
+	const diffDays = Math.round((targetDay - currentDay) / (1000 * 60 * 60 * 24))
+
+	const dayName = formatDayShort(date)
+
+	if (diffDays === 0) return `Today: ${dayName}`
+	if (diffDays === 1) return `Tomorrow: ${dayName}`
+	return dayName
+}
+
+/**
+ * Builds a week overview mapping day names to dates,
+ * so the LLM can easily match ISO timestamps to days.
+ */
+function buildWeekCalendar(currentTime: Date): string {
+	const lines: string[] = []
+	for (let i = 0; i < 7; i++) {
+		const date = new Date(currentTime)
+		date.setUTCDate(date.getUTCDate() + i)
+		const label = i === 0 ? "Today" : i === 1 ? "Tomorrow" : ""
+		const dayStr = formatDayShort(date)
+		const iso = date.toISOString().slice(0, 10)
+		const prefix = label ? `${label}: ` : ""
+		lines.push(`${prefix}${dayStr} = ${iso}`)
+	}
+	return lines.join("\n")
+}
+
+/**
+ * Builds a compact text calendar from all calendar-type items.
+ * Groups events by day relative to currentTime.
+ */
+function buildSchedule(items: FeedItem[], currentTime: Date): string {
+	const entries: CalendarEntry[] = []
+	for (const item of items) {
+		const entry = extractCalendarEntry(item)
+		if (entry) entries.push(entry)
+	}
+
+	if (entries.length === 0) return ""
+
+	entries.sort((a, b) => a.startTime.getTime() - b.startTime.getTime())
+
+	const byDay = new Map<string, CalendarEntry[]>()
+	for (const entry of entries) {
+		const key = entry.date.toISOString().slice(0, 10)
+		const group = byDay.get(key)
+		if (group) {
+			group.push(entry)
+		} else {
+			byDay.set(key, [entry])
+		}
+	}
+
+	const lines: string[] = []
+	for (const [, dayEntries] of byDay) {
+		lines.push(formatDayLabel(dayEntries[0]!.startTime, currentTime))
+		for (const entry of dayEntries) {
+			if (entry.isAllDay) {
+				const loc = entry.location ? ` @ ${entry.location}` : ""
+				lines.push(`  all day  ${entry.title}${loc}`)
+			} else {
+				const timeRange = `${formatTime(entry.startTime)}–${formatTime(entry.endTime)}`
+				const loc = entry.location ? ` @ ${entry.location}` : ""
+				lines.push(`  ${timeRange}  ${entry.title}${loc}`)
+			}
+		}
+	}
+
+	return lines.join("\n")
+}

apps/aris-backend/src/enhancement/prompts/system.txt

@@ -0,0 +1,21 @@
+You are ARIS, a personal assistant. You enhance a user's feed by filling slots and optionally generating synthetic items.
+
+The user message is a JSON object with:
+- "items": feed items with data and named slots to fill. Each slot has a description of what to write.
+- "context": other feed items (no slots) for cross-source reasoning.
+- "time": current ISO timestamp.
+
+Your output has two fields:
+- "slotFills": map of item ID → slot name → short text (or null if you can't fill it or cannot provide answer). Each item ID appears ONCE with ALL its slots in a single object.
+- "syntheticItems": array of { id, type, text } for new items (briefings, nudges, insights). Only when genuinely useful and when not redundant.
+
+Rules:
+- DO NOT USE EMDASH OR DASH OR ATTEMPT TO USE SYMBOLS TO CIRCUMVENT THIS RULE.
+- One sentence per slot. Two max if absolutely necessary. Be direct.
+- Say "I" not "we."
+- Hedge when inferring. Don't state guesses as facts.
+- Use the week and schedule below to understand when events happen. Match weather data to the correct date.
+- Look for connections across items.
+- Don't pad — return null for slots you can't meaningfully fill, and skip synthetic items if there's nothing useful to add.
+- Never fabricate information not present in the feed. If you don't have data to support a fill, return null.
+- Read each slot's description carefully — it defines when to return null.

apps/aris-backend/src/enhancement/schema.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, test } from "bun:test"
+
+import {
+	emptyEnhancementResult,
+	enhancementResultJsonSchema,
+	parseEnhancementResult,
+} from "./schema.ts"
+
+describe("parseEnhancementResult", () => {
+	test("parses valid result", () => {
+		const input = JSON.stringify({
+			slotFills: {
+				"weather-1": {
+					insight: "Rain after 3pm",
+					"cross-source": null,
+				},
+			},
+			syntheticItems: [
+				{
+					id: "briefing-morning",
+					type: "briefing",
+					text: "Light afternoon ahead.",
+				},
+			],
+		})
+
+		const result = parseEnhancementResult(input)
+
+		expect(result).not.toBeNull()
+		expect(result!.slotFills["weather-1"]!.insight).toBe("Rain after 3pm")
+		expect(result!.slotFills["weather-1"]!["cross-source"]).toBeNull()
+		expect(result!.syntheticItems).toHaveLength(1)
+		expect(result!.syntheticItems[0]!.id).toBe("briefing-morning")
+		expect(result!.syntheticItems[0]!.text).toBe("Light afternoon ahead.")
+	})
+
+	test("parses empty result", () => {
+		const input = JSON.stringify({
+			slotFills: {},
+			syntheticItems: [],
+		})
+
+		const result = parseEnhancementResult(input)
+
+		expect(result).not.toBeNull()
+		expect(Object.keys(result!.slotFills)).toHaveLength(0)
+		expect(result!.syntheticItems).toHaveLength(0)
+	})
+
+	test("returns null for invalid JSON", () => {
+		expect(parseEnhancementResult("not json")).toBeNull()
+	})
+
+	test("returns null for non-object", () => {
+		expect(parseEnhancementResult('"hello"')).toBeNull()
+		expect(parseEnhancementResult("42")).toBeNull()
+		expect(parseEnhancementResult("null")).toBeNull()
+	})
+
+	test("returns null when slotFills is missing", () => {
+		const input = JSON.stringify({ syntheticItems: [] })
+		expect(parseEnhancementResult(input)).toBeNull()
+	})
+
+	test("returns null when syntheticItems is missing", () => {
+		const input = JSON.stringify({ slotFills: {} })
+		expect(parseEnhancementResult(input)).toBeNull()
+	})
+
+	test("returns null when slotFills has non-string values", () => {
+		const input = JSON.stringify({
+			slotFills: { "item-1": { slot: 42 } },
+			syntheticItems: [],
+		})
+		expect(parseEnhancementResult(input)).toBeNull()
+	})
+
+	test("returns null when syntheticItem is missing required fields", () => {
+		const input = JSON.stringify({
+			slotFills: {},
+			syntheticItems: [{ id: "x" }],
+		})
+		expect(parseEnhancementResult(input)).toBeNull()
+	})
+})
+
+describe("emptyEnhancementResult", () => {
+	test("returns empty slotFills and syntheticItems", () => {
+		const result = emptyEnhancementResult()
+		expect(result.slotFills).toEqual({})
+		expect(result.syntheticItems).toEqual([])
+	})
+})
+
+describe("schema sync", () => {
+	const referencePayloads = [
+		{
+			name: "full payload with null slot fill",
+			payload: {
+				slotFills: {
+					"weather-1": { insight: "Rain after 3pm", crossSource: null },
+					"cal-2": { summary: "Busy morning" },
+				},
+				syntheticItems: [
+					{ id: "briefing-morning", type: "briefing", text: "Light day ahead." },
+					{ id: "nudge-umbrella", type: "nudge", text: "Bring an umbrella." },
+				],
+			},
+		},
+		{
+			name: "empty collections",
+			payload: { slotFills: {}, syntheticItems: [] },
+		},
+		{
+			name: "slot fills only",
+			payload: {
+				slotFills: { "item-1": { slot: "filled" } },
+				syntheticItems: [],
+			},
+		},
+		{
+			name: "synthetic items only",
+			payload: {
+				slotFills: {},
+				syntheticItems: [{ id: "insight-1", type: "insight", text: "Something." }],
+			},
+		},
+	]
+
+	for (const { name, payload } of referencePayloads) {
+		test(`arktype and JSON Schema agree on: ${name}`, () => {
+			// arktype accepts it
+			const parsed = parseEnhancementResult(JSON.stringify(payload))
+			expect(parsed).not.toBeNull()
+
+			// JSON Schema structure matches
+			const jsonSchema = enhancementResultJsonSchema
+			expect(Object.keys(jsonSchema.properties).sort()).toEqual(
+				Object.keys(payload).sort(),
+			)
+			expect([...jsonSchema.required].sort()).toEqual(Object.keys(payload).sort())
+
+			// syntheticItems item schema has the right required fields
+			const itemSchema = jsonSchema.properties.syntheticItems.items
+			expect([...itemSchema.required].sort()).toEqual(["id", "text", "type"])
+
+			// Verify each synthetic item has exactly the fields the JSON Schema expects
+			for (const item of payload.syntheticItems) {
+				expect(Object.keys(item).sort()).toEqual([...itemSchema.required].sort())
+			}
+		})
+	}
+
+	test("JSON Schema rejects what arktype rejects: missing required field", () => {
+		// Missing syntheticItems
+		expect(parseEnhancementResult(JSON.stringify({ slotFills: {} }))).toBeNull()
+
+		// JSON Schema also requires it
+		expect(enhancementResultJsonSchema.required).toContain("syntheticItems")
+	})
+
+	test("JSON Schema rejects what arktype rejects: wrong slot fill value type", () => {
+		const bad = { slotFills: { "item-1": { slot: 42 } }, syntheticItems: [] }
+
+		// arktype rejects it
+		expect(parseEnhancementResult(JSON.stringify(bad))).toBeNull()
+
+		// JSON Schema only allows string or null for slot values
+		const slotValueTypes =
+			enhancementResultJsonSchema.properties.slotFills.additionalProperties
+				.additionalProperties.type
+		expect(slotValueTypes).toContain("string")
+		expect(slotValueTypes).toContain("null")
+		expect(slotValueTypes).not.toContain("number")
+	})
+})

apps/aris-backend/src/enhancement/schema.ts

@@ -0,0 +1,89 @@
+import { type } from "arktype"
+
+const SyntheticItem = type({
+	id: "string",
+	type: "string",
+	text: "string",
+})
+
+const EnhancementResult = type({
+	slotFills: "Record<string, Record<string, string | null>>",
+	syntheticItems: SyntheticItem.array(),
+})
+
+export type SyntheticItem = typeof SyntheticItem.infer
+export type EnhancementResult = typeof EnhancementResult.infer
+
+/**
+ * JSON Schema passed to OpenRouter's structured output.
+ * OpenRouter doesn't support arktype, so this is maintained separately.
+ *
+ * ⚠️  Must stay in sync with EnhancementResult above.
+ * If you add/remove fields, update both schemas.
+ */
+export const enhancementResultJsonSchema = {
+	type: "object",
+	properties: {
+		slotFills: {
+			type: "object",
+			description:
+				"Map of feed item ID to an object of slot name to filled text content. Use null for slots that cannot be meaningfully filled.",
+			additionalProperties: {
+				type: "object",
+				additionalProperties: {
+					type: ["string", "null"],
+				},
+			},
+		},
+		syntheticItems: {
+			type: "array",
+			description:
+				"New feed items to inject (briefings, nudges, cross-source insights). Keep these short and actionable.",
+			items: {
+				type: "object",
+				properties: {
+					id: {
+						type: "string",
+						description: "Unique ID, e.g. 'briefing-morning'",
+					},
+					type: {
+						type: "string",
+						description: "One of: 'briefing', 'nudge', 'insight'",
+					},
+					text: {
+						type: "string",
+						description: "Display text, 1-3 sentences",
+					},
+				},
+				required: ["id", "type", "text"],
+				additionalProperties: false,
+			},
+		},
+	},
+	required: ["slotFills", "syntheticItems"],
+	additionalProperties: false,
+} as const
+
+/**
+ * Parses a JSON string into an EnhancementResult.
+ * Returns null if the input is malformed.
+ */
+export function parseEnhancementResult(json: string): EnhancementResult | null {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(json)
+	} catch {
+		return null
+	}
+
+	const result = EnhancementResult(parsed)
+	if (result instanceof type.errors) {
+		return null
+	}
+
+	return result
+}
+
+export function emptyEnhancementResult(): EnhancementResult {
+	return { slotFills: {}, syntheticItems: [] }
+}

apps/aris-backend/src/feed/http.test.ts

@@ -1,4 +1,4 @@
-import type { ActionDefinition, Context, FeedItem, FeedSource } from "@aris/core"
+import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@aris/core"
 
 import { describe, expect, test } from "bun:test"
 import { Hono } from "hono"
@@ -27,7 +27,7 @@ function createStubSource(id: string, items: FeedItem[] = []): FeedSource {
 		async executeAction(): Promise<unknown> {
 			return undefined
 		},
-		async fetchContext(): Promise<Partial<Context> | null> {
+		async fetchContext(): Promise<readonly ContextEntry[] | null> {
 			return null
 		},
 		async fetchItems() {
@@ -47,7 +47,7 @@ function buildTestApp(sessionManager: UserSessionManager, userId?: string) {
 
 describe("GET /api/feed", () => {
 	test("returns 401 without auth", async () => {
-		const manager = new UserSessionManager([])
+		const manager = new UserSessionManager({ providers: [] })
 		const app = buildTestApp(manager)
 
 		const res = await app.request("/api/feed")
@@ -65,7 +65,9 @@ describe("GET /api/feed", () => {
 				data: { value: 42 },
 			},
 		]
-		const manager = new UserSessionManager([() => createStubSource("test", items)])
+		const manager = new UserSessionManager({
+			providers: [() => createStubSource("test", items)],
+		})
 		const app = buildTestApp(manager, "user-1")
 
 		// Prime the cache
@@ -95,7 +97,9 @@ describe("GET /api/feed", () => {
 				data: { fresh: true },
 			},
 		]
-		const manager = new UserSessionManager([() => createStubSource("test", items)])
+		const manager = new UserSessionManager({
+			providers: [() => createStubSource("test", items)],
+		})
 		const app = buildTestApp(manager, "user-1")
 
 		// No prior refresh — lastFeed() returns null, handler should call refresh()
@@ -125,7 +129,7 @@ describe("GET /api/feed", () => {
 				throw new Error("connection timeout")
 			},
 		}
-		const manager = new UserSessionManager([() => failingSource])
+		const manager = new UserSessionManager({ providers: [() => failingSource] })
 		const app = buildTestApp(manager, "user-1")
 
 		const res = await app.request("/api/feed")

apps/aris-backend/src/feed/http.ts

@@ -5,7 +5,11 @@ import { createMiddleware } from "hono/factory"
 import type { AuthSessionMiddleware } from "../auth/session-middleware.ts"
 import type { UserSessionManager } from "../session/index.ts"
 
-type Env = { Variables: { sessionManager: UserSessionManager } }
+type Env = {
+	Variables: {
+		sessionManager: UserSessionManager
+	}
+}
 
 interface FeedHttpHandlersDeps {
 	sessionManager: UserSessionManager
@@ -29,7 +33,7 @@ async function handleGetFeed(c: Context<Env>) {
 	const sessionManager = c.get("sessionManager")
 	const session = sessionManager.getOrCreate(user.id)
 
-	const feed = session.engine.lastFeed() ?? (await session.engine.refresh())
+	const feed = await session.feed()
 
 	return c.json({
 		items: feed.items,

apps/aris-backend/src/server.ts

@@ -3,13 +3,29 @@ import { Hono } from "hono"
 
 import { registerAuthHandlers } from "./auth/http.ts"
 import { requireSession } from "./auth/session-middleware.ts"
+import { createFeedEnhancer } from "./enhancement/enhance-feed.ts"
+import { createLlmClient } from "./enhancement/llm-client.ts"
 import { registerFeedHttpHandlers } from "./feed/http.ts"
 import { registerLocationHttpHandlers } from "./location/http.ts"
 import { UserSessionManager } from "./session/index.ts"
 import { WeatherSourceProvider } from "./weather/provider.ts"
 
 function main() {
-	const sessionManager = new UserSessionManager([
+	const openrouterApiKey = process.env.OPENROUTER_API_KEY
+	const feedEnhancer = openrouterApiKey
+		? createFeedEnhancer({
+				client: createLlmClient({
+					apiKey: openrouterApiKey,
+					model: process.env.OPENROUTER_MODEL || undefined,
+				}),
+			})
+		: null
+	if (!feedEnhancer) {
+		console.warn("[enhancement] OPENROUTER_API_KEY not set — feed enhancement disabled")
+	}
+
+	const sessionManager = new UserSessionManager({
+		providers: [
 			() => new LocationSource(),
 			new WeatherSourceProvider({
 				credentials: {
@@ -19,14 +35,19 @@ function main() {
 					serviceId: process.env.WEATHERKIT_SERVICE_ID!,
 				},
 			}),
-	])
+		],
+		feedEnhancer,
+	})
 
 	const app = new Hono()
 
 	app.get("/health", (c) => c.json({ status: "ok" }))
 
 	registerAuthHandlers(app)
-	registerFeedHttpHandlers(app, { sessionManager, authSessionMiddleware: requireSession })
+	registerFeedHttpHandlers(app, {
+		sessionManager,
+		authSessionMiddleware: requireSession,
+	})
 	registerLocationHttpHandlers(app, { sessionManager })
 
 	return app

apps/aris-backend/src/session/user-session-manager.test.ts

@@ -12,7 +12,7 @@ const mockWeatherClient: WeatherKitClient = {
 
 describe("UserSessionManager", () => {
 	test("getOrCreate creates session on first call", () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session = manager.getOrCreate("user-1")
 
@@ -21,7 +21,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("getOrCreate returns same session for same user", () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session1 = manager.getOrCreate("user-1")
 		const session2 = manager.getOrCreate("user-1")
@@ -30,7 +30,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("getOrCreate returns different sessions for different users", () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session1 = manager.getOrCreate("user-1")
 		const session2 = manager.getOrCreate("user-2")
@@ -39,7 +39,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("each user gets independent source instances", () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session1 = manager.getOrCreate("user-1")
 		const session2 = manager.getOrCreate("user-2")
@@ -51,7 +51,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("remove destroys session and allows re-creation", () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session1 = manager.getOrCreate("user-1")
 		manager.remove("user-1")
@@ -61,13 +61,13 @@ describe("UserSessionManager", () => {
 	})
 
 	test("remove is no-op for unknown user", () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		expect(() => manager.remove("unknown")).not.toThrow()
 	})
 
 	test("accepts function providers", async () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session = manager.getOrCreate("user-1")
 		const result = await session.engine.refresh()
@@ -77,7 +77,9 @@ describe("UserSessionManager", () => {
 
 	test("accepts object providers", () => {
 		const provider = new WeatherSourceProvider({ client: mockWeatherClient })
-		const manager = new UserSessionManager([() => new LocationSource(), provider])
+		const manager = new UserSessionManager({
+			providers: [() => new LocationSource(), provider],
+		})
 
 		const session = manager.getOrCreate("user-1")
 
@@ -86,7 +88,9 @@ describe("UserSessionManager", () => {
 
 	test("accepts mixed providers", () => {
 		const provider = new WeatherSourceProvider({ client: mockWeatherClient })
-		const manager = new UserSessionManager([() => new LocationSource(), provider])
+		const manager = new UserSessionManager({
+			providers: [() => new LocationSource(), provider],
+		})
 
 		const session = manager.getOrCreate("user-1")
 
@@ -95,7 +99,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("refresh returns feed result through session", async () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session = manager.getOrCreate("user-1")
 		const result = await session.engine.refresh()
@@ -107,7 +111,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("location update via executeAction works", async () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 
 		const session = manager.getOrCreate("user-1")
 		await session.engine.executeAction("aris.location", "update-location", {
@@ -122,7 +126,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("subscribe receives updates after location push", async () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 		const callback = mock()
 
 		const session = manager.getOrCreate("user-1")
@@ -142,7 +146,7 @@ describe("UserSessionManager", () => {
 	})
 
 	test("remove stops reactive updates", async () => {
-		const manager = new UserSessionManager([() => new LocationSource()])
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
 		const callback = mock()
 
 		const session = manager.getOrCreate("user-1")

apps/aris-backend/src/session/user-session-manager.ts

@@ -1,13 +1,21 @@
+import type { FeedEnhancer } from "../enhancement/enhance-feed.ts"
 import type { FeedSourceProviderInput } from "./feed-source-provider.ts"
 
 import { UserSession } from "./user-session.ts"
 
+export interface UserSessionManagerConfig {
+	providers: FeedSourceProviderInput[]
+	feedEnhancer?: FeedEnhancer | null
+}
+
 export class UserSessionManager {
 	private sessions = new Map<string, UserSession>()
 	private readonly providers: FeedSourceProviderInput[]
+	private readonly feedEnhancer: FeedEnhancer | null
 
-	constructor(providers: FeedSourceProviderInput[]) {
-		this.providers = providers
+	constructor(config: UserSessionManagerConfig) {
+		this.providers = config.providers
+		this.feedEnhancer = config.feedEnhancer ?? null
 	}
 
 	getOrCreate(userId: string): UserSession {
@@ -16,7 +24,7 @@ export class UserSessionManager {
 			const sources = this.providers.map((p) =>
 				typeof p === "function" ? p(userId) : p.feedSourceForUser(userId),
 			)
-			session = new UserSession(sources)
+			session = new UserSession(sources, this.feedEnhancer)
 			this.sessions.set(userId, session)
 		}
 		return session

apps/aris-backend/src/session/user-session.test.ts

@@ -1,11 +1,11 @@
-import type { ActionDefinition, Context, FeedSource } from "@aris/core"
+import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@aris/core"
 
 import { LocationSource } from "@aris/source-location"
 import { describe, expect, test } from "bun:test"
 
 import { UserSession } from "./user-session.ts"
 
-function createStubSource(id: string): FeedSource {
+function createStubSource(id: string, items: FeedItem[] = []): FeedSource {
 	return {
 		id,
 		async listActions(): Promise<Record<string, ActionDefinition>> {
@@ -14,11 +14,11 @@ function createStubSource(id: string): FeedSource {
 		async executeAction(): Promise<unknown> {
 			return undefined
 		},
-		async fetchContext(): Promise<Partial<Context> | null> {
+		async fetchContext(): Promise<readonly ContextEntry[] | null> {
 			return null
 		},
 		async fetchItems() {
-			return []
+			return items
 		},
 	}
 }
@@ -70,3 +70,141 @@ describe("UserSession", () => {
 		expect(location.lastLocation!.lat).toBe(51.5)
 	})
 })
+
+describe("UserSession.feed", () => {
+	test("returns feed items without enhancer", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const session = new UserSession([createStubSource("test", items)])
+
+		const result = await session.feed()
+
+		expect(result.items).toHaveLength(1)
+		expect(result.items[0]!.id).toBe("item-1")
+	})
+
+	test("returns enhanced items when enhancer is provided", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const enhancer = async (feedItems: FeedItem[]) =>
+			feedItems.map((item) => ({ ...item, data: { ...item.data, enhanced: true } }))
+
+		const session = new UserSession([createStubSource("test", items)], enhancer)
+
+		const result = await session.feed()
+
+		expect(result.items).toHaveLength(1)
+		expect(result.items[0]!.data.enhanced).toBe(true)
+	})
+
+	test("caches enhanced items on subsequent calls", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		let enhancerCallCount = 0
+		const enhancer = async (feedItems: FeedItem[]) => {
+			enhancerCallCount++
+			return feedItems.map((item) => ({ ...item, data: { ...item.data, enhanced: true } }))
+		}
+
+		const session = new UserSession([createStubSource("test", items)], enhancer)
+
+		const result1 = await session.feed()
+		expect(result1.items[0]!.data.enhanced).toBe(true)
+		expect(enhancerCallCount).toBe(1)
+
+		const result2 = await session.feed()
+		expect(result2.items[0]!.data.enhanced).toBe(true)
+		expect(enhancerCallCount).toBe(1)
+	})
+
+	test("re-enhances after engine refresh with new data", async () => {
+		let currentItems: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { version: 1 },
+			},
+		]
+		const source = createStubSource("test", currentItems)
+		// Make fetchItems dynamic so refresh returns new data
+		source.fetchItems = async () => currentItems
+
+		const enhancedVersions: number[] = []
+		const enhancer = async (feedItems: FeedItem[]) => {
+			const version = feedItems[0]!.data.version as number
+			enhancedVersions.push(version)
+			return feedItems.map((item) => ({
+				...item,
+				data: { ...item.data, enhanced: true },
+			}))
+		}
+
+		const session = new UserSession([source], enhancer)
+
+		// First feed triggers refresh + enhancement
+		const result1 = await session.feed()
+		expect(result1.items[0]!.data.version).toBe(1)
+		expect(result1.items[0]!.data.enhanced).toBe(true)
+
+		// Update source data and trigger engine refresh
+		currentItems = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-02T00:00:00.000Z"),
+				data: { version: 2 },
+			},
+		]
+		await session.engine.refresh()
+
+		// Wait for subscriber-triggered background enhancement
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		// feed() should now serve re-enhanced items with version 2
+		const result2 = await session.feed()
+		expect(result2.items[0]!.data.version).toBe(2)
+		expect(result2.items[0]!.data.enhanced).toBe(true)
+		expect(enhancedVersions).toEqual([1, 2])
+	})
+
+	test("falls back to unenhanced items when enhancer throws", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const enhancer = async () => {
+			throw new Error("enhancement exploded")
+		}
+
+		const session = new UserSession([createStubSource("test", items)], enhancer)
+
+		const result = await session.feed()
+
+		expect(result.items).toHaveLength(1)
+		expect(result.items[0]!.id).toBe("item-1")
+		expect(result.items[0]!.data.value).toBe(42)
+	})
+})

apps/aris-backend/src/session/user-session.ts

@@ -1,24 +1,104 @@
-import { FeedEngine, type FeedSource } from "@aris/core"
+import { FeedEngine, type FeedItem, type FeedResult, type FeedSource } from "@aris/core"
+
+import type { FeedEnhancer } from "../enhancement/enhance-feed.ts"
 
 export class UserSession {
 	readonly engine: FeedEngine
 	private sources = new Map<string, FeedSource>()
+	private readonly enhancer: FeedEnhancer | null
+	private enhancedItems: FeedItem[] | null = null
+	/** The FeedResult that enhancedItems was derived from. */
+	private enhancedSource: FeedResult | null = null
+	private enhancingPromise: Promise<void> | null = null
+	private unsubscribe: (() => void) | null = null
 
-	constructor(sources: FeedSource[]) {
+	constructor(sources: FeedSource[], enhancer?: FeedEnhancer | null) {
 		this.engine = new FeedEngine()
+		this.enhancer = enhancer ?? null
 		for (const source of sources) {
 			this.sources.set(source.id, source)
 			this.engine.register(source)
 		}
+
+		if (this.enhancer) {
+			this.unsubscribe = this.engine.subscribe((result) => {
+				this.invalidateEnhancement()
+				this.runEnhancement(result)
+			})
+		}
+
 		this.engine.start()
 	}
 
+	/**
+	 * Returns the current feed, refreshing if the engine cache expired.
+	 * Enhancement runs eagerly on engine updates; this method awaits
+	 * any in-flight enhancement or triggers one if needed.
+	 */
+	async feed(): Promise<FeedResult> {
+		const cached = this.engine.lastFeed()
+		const result = cached ?? (await this.engine.refresh())
+
+		if (!this.enhancer) {
+			return result
+		}
+
+		// Wait for any in-flight background enhancement to finish
+		if (this.enhancingPromise) {
+			await this.enhancingPromise
+		}
+
+		// Serve cached enhancement only if it matches the current engine result
+		if (this.enhancedItems && this.enhancedSource === result) {
+			return { ...result, items: this.enhancedItems }
+		}
+
+		// Stale or missing — re-enhance
+		await this.runEnhancement(result)
+
+		if (this.enhancedItems) {
+			return { ...result, items: this.enhancedItems }
+		}
+
+		return result
+	}
+
 	getSource<T extends FeedSource>(sourceId: string): T | undefined {
 		return this.sources.get(sourceId) as T | undefined
 	}
 
 	destroy(): void {
+		this.unsubscribe?.()
+		this.unsubscribe = null
 		this.engine.stop()
 		this.sources.clear()
+		this.invalidateEnhancement()
+		this.enhancingPromise = null
+	}
+
+	private invalidateEnhancement(): void {
+		this.enhancedItems = null
+		this.enhancedSource = null
+	}
+
+	private runEnhancement(result: FeedResult): Promise<void> {
+		const promise = this.enhance(result)
+		this.enhancingPromise = promise
+		promise.finally(() => {
+			if (this.enhancingPromise === promise) {
+				this.enhancingPromise = null
+			}
+		})
+		return promise
+	}
+
+	private async enhance(result: FeedResult): Promise<void> {
+		try {
+			this.enhancedItems = await this.enhancer!(result.items)
+			this.enhancedSource = result
+		} catch (err) {
+			console.error("[enhancement] Unexpected error:", err)
+			this.invalidateEnhancement()
+		}
 	}
 }

apps/waitlist-website/.dockerignore

@@ -0,0 +1,5 @@
+.react-router
+build
+node_modules
+.env
+README.md

apps/waitlist-website/.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+.env
+/node_modules/
+
+# React Router
+/.react-router/
+/build/

apps/waitlist-website/Dockerfile

@@ -0,0 +1,22 @@
+FROM oven/bun:1 AS development-dependencies-env
+COPY . /app
+WORKDIR /app
+RUN bun install
+
+FROM oven/bun:1 AS production-dependencies-env
+COPY ./package.json /app/
+WORKDIR /app
+RUN bun install --production
+
+FROM oven/bun:1 AS build-env
+COPY . /app/
+COPY --from=development-dependencies-env /app/node_modules /app/node_modules
+WORKDIR /app
+RUN bun run build
+
+FROM node:20-alpine
+COPY ./package.json /app/
+COPY --from=production-dependencies-env /app/node_modules /app/node_modules
+COPY --from=build-env /app/build /app/build
+WORKDIR /app
+CMD ["npm", "run", "start"]

apps/waitlist-website/README.md

@@ -0,0 +1,87 @@
+# Welcome to React Router!
+
+A modern, production-ready template for building full-stack React applications using React Router.
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/remix-run/react-router-templates/tree/main/default)
+
+## Features
+
+- 🚀 Server-side rendering
+- ⚡️ Hot Module Replacement (HMR)
+- 📦 Asset bundling and optimization
+- 🔄 Data loading and mutations
+- 🔒 TypeScript by default
+- 🎉 TailwindCSS for styling
+- 📖 [React Router docs](https://reactrouter.com/)
+
+## Getting Started
+
+### Installation
+
+Install the dependencies:
+
+```bash
+npm install
+```
+
+### Development
+
+Start the development server with HMR:
+
+```bash
+npm run dev
+```
+
+Your application will be available at `http://localhost:5173`.
+
+## Building for Production
+
+Create a production build:
+
+```bash
+npm run build
+```
+
+## Deployment
+
+### Docker Deployment
+
+To build and run using Docker:
+
+```bash
+docker build -t my-app .
+
+# Run the container
+docker run -p 3000:3000 my-app
+```
+
+The containerized application can be deployed to any platform that supports Docker, including:
+
+- AWS ECS
+- Google Cloud Run
+- Azure Container Apps
+- Digital Ocean App Platform
+- Fly.io
+- Railway
+
+### DIY Deployment
+
+If you're familiar with deploying Node applications, the built-in app server is production-ready.
+
+Make sure to deploy the output of `npm run build`
+
+```
+├── package.json
+├── package-lock.json (or pnpm-lock.yaml, or bun.lockb)
+├── build/
+│   ├── client/    # Static assets
+│   └── server/    # Server-side code
+```
+
+## Styling
+
+This template comes with [Tailwind CSS](https://tailwindcss.com/) already configured for a simple default starting experience. You can use whatever CSS framework you prefer.
+
+---
+
+Built with ❤️ using React Router.

apps/waitlist-website/app/app.css

@@ -0,0 +1,51 @@
+@import url("https://fonts.googleapis.com/css2?family=Source+Serif+4:ital,opsz,wght@0,8..60,200..900;1,8..60,200..900&display=swap");
+@import "tailwindcss";
+
+@source "../node_modules/streamdown/dist/*.js";
+
+@theme {
+	--font-sans:
+		"Inter", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji",
+		"Segoe UI Symbol", "Noto Color Emoji";
+	--font-serif: "Source Serif 4", ui-serif, serif;
+}
+
+:root,
+html,
+body {
+	@apply w-full h-full;
+}
+
+@keyframes popover-in {
+	from {
+		opacity: 0;
+		transform: scale(0.95) translateY(4px);
+	}
+	to {
+		opacity: 1;
+		transform: scale(1) translateY(0);
+	}
+}
+
+@keyframes popover-out {
+	from {
+		opacity: 1;
+		transform: scale(1) translateY(0);
+	}
+	to {
+		opacity: 0;
+		transform: scale(0.95) translateY(4px);
+	}
+}
+
+html,
+body {
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+
+	@apply bg-stone-50 dark:bg-stone-900 text-stone-900 dark:text-stone-200 selection:bg-teal-600 dark:selection:bg-teal-500 selection:text-stone-50 dark:selection:text-stone-900;
+
+	@media (prefers-color-scheme: dark) {
+		color-scheme: dark;
+	}
+}

apps/waitlist-website/app/chat/chat-box.tsx

@@ -0,0 +1,117 @@
+import clsx from "clsx"
+import { ArrowUpIcon, FileIcon, ImageIcon, PlusIcon, XIcon } from "lucide-react"
+import { motion, useAnimate } from "motion/react"
+import { useEffect, useRef, useState } from "react"
+import { Button, Menu, MenuItem, MenuTrigger, Popover } from "react-aria-components"
+
+export function ChatBox({
+	className,
+	validate,
+	onSubmit,
+}: {
+	className?: string
+	validate?: (value: string) => boolean
+	onSubmit: (email: string) => void
+	disabled?: boolean
+}) {
+	const [scope, animate] = useAnimate()
+	const [shouldShowInvalid, setShouldShowInvalid] = useState(false)
+	const clearInvalidStateTimeout = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+	useEffect(
+		() => () => {
+			if (clearInvalidStateTimeout.current) {
+				clearTimeout(clearInvalidStateTimeout.current)
+			}
+		},
+		[],
+	)
+
+	function showInvalidState() {
+		animate(scope.current, { x: [0, -6, 6, -4, 4, -2, 2, 0] }, { duration: 0.4, ease: "easeOut" })
+		if (clearInvalidStateTimeout.current) {
+			clearTimeout(clearInvalidStateTimeout.current)
+		}
+		setShouldShowInvalid(true)
+		clearInvalidStateTimeout.current = setTimeout(() => {
+			setShouldShowInvalid(false)
+		}, 500)
+	}
+
+	const onFormSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+		e.preventDefault()
+		const formData = new FormData(e.currentTarget)
+		const email = formData.get("liame")
+		if (typeof email === "string") {
+			const trimmed = email.trim()
+			if (trimmed.length === 0) {
+				showInvalidState()
+			} else if (validate && !validate(trimmed)) {
+				showInvalidState()
+			} else {
+				onSubmit(trimmed)
+				e.currentTarget.reset()
+			}
+		}
+	}
+
+	return (
+		<motion.form
+			ref={scope}
+			onSubmit={onFormSubmit}
+			className={`min-h-20 px-3 pt-2 pb-1.5 flex flex-col justify-between rounded-lg bg-stone-100 dark:bg-stone-800 border border-stone-200 dark:border-stone-700 ${className ?? ""} shadow-xs hover:shadow-sm`}
+		>
+			<input
+				name="liame"
+				className="w-full bg-transparent outline-none focus:outline-none ring-0 focus:ring-0"
+			/>
+			<div className="w-full flex justify-between">
+				<MenuTrigger>
+					<Button className="bg-transparent hover:bg-stone-200 dark:hover:bg-stone-700 active:bg-stone-300 dark:active:bg-stone-600 data-[pressed]:bg-stone-200 dark:data-[pressed]:bg-stone-700 rounded-full flex items-center justify-center p-1 -ml-1.5 active:inset-shadow-sm outline-none transition-transform duration-200 data-[pressed]:rotate-45">
+						<PlusIcon size={16} />
+					</Button>
+					<Popover
+						offset={4}
+						className="origin-bottom-left rounded-lg border border-stone-200 dark:border-stone-700 bg-stone-100 dark:bg-stone-800 shadow-lg p-1 min-w-40 outline-none data-[entering]:animate-[popover-in_150ms_ease-out] data-[exiting]:animate-[popover-out_100ms_ease-in]"
+						placement="top start"
+					>
+						<AttachmentMenu />
+					</Popover>
+				</MenuTrigger>
+				<button
+					type="submit"
+					disabled={shouldShowInvalid}
+					className={clsx(
+						"transition-all rounded-full flex items-center justify-center p-1 -mr-1.5 active:scale-95",
+						shouldShowInvalid
+							? "bg-red-400 hover:bg-red-300 text-stone-200 dark:text-stone-700"
+							: "bg-teal-600 hover:bg-teal-500 active:bg-teal-600 text-stone-200",
+					)}
+				>
+					{shouldShowInvalid ? <XIcon size={16} /> : <ArrowUpIcon size={16} />}
+				</button>
+			</div>
+		</motion.form>
+	)
+}
+
+function AttachmentMenu() {
+	return (
+		<Menu className="outline-none">
+			<MenuItem
+				className="flex items-center gap-2 px-2 py-1 rounded-md cursor-default outline-none hover:bg-stone-200 dark:hover:bg-stone-700 focus:bg-stone-200 dark:focus:bg-stone-700"
+				onAction={() => {}}
+			>
+				<ImageIcon size={14} />
+				Photos
+			</MenuItem>
+			<MenuItem
+				className="flex items-center gap-2 px-2 py-1 rounded-md cursor-default outline-none hover:bg-stone-200 dark:hover:bg-stone-700 focus:bg-stone-200 dark:focus:bg-stone-700"
+				onAction={() => {}}
+			>
+				<FileIcon size={14} />
+				Files
+			</MenuItem>
+		</Menu>
+	)
+}

apps/waitlist-website/app/chat/message.ts

@@ -0,0 +1,66 @@
+export interface UserMessage {
+	role: "user"
+	message: string
+	bubbleLayoutId?: string
+}
+
+export interface SystemMessage {
+	role: "system"
+	message: string
+}
+
+export type Message = UserMessage | SystemMessage
+
+function timeOfDay() {
+	const hours = new Date().getHours()
+	if (hours >= 5 && hours < 12) {
+		return "morning"
+	} else if (hours >= 12 && hours < 18) {
+		return "afternoon"
+	} else if (hours >= 18 && hours < 22) {
+		return "evening"
+	}
+	return "night"
+}
+
+export const INITIAL_MESSAGES: Message[] = [
+	{
+		role: "user",
+		message: "Who are you?",
+	},
+	{
+		role: "system",
+		message: `Hey! I'm **Aelis** — your personal assistant that brings you the right thing, at the right time, in the right place.
+
+- Jubilee line down? I've already found you an alternative route.
+- Dinner reservation at 8? I'll have the restaurant, directions, and the menu ready before you head out.
+
+I learn your routines, anticipate what's next, and surface what matters before you even think to look for it.
+
+I'm not ready yet — [@kennethnym](https://x.com/kennethnym) is still building me. **Drop your email below** and I'll let you know when I'm available.`,
+	},
+]
+
+export function waitListJoinedMessage(email: string): SystemMessage {
+	return {
+		role: "system",
+		message: `Thanks for joining the waitlist! I've sent you a confirmation email.
+I'll send an email to **${email}** when I'm ready.
+
+Have a good ${timeOfDay()}!`,
+	}
+}
+
+export function duplicateEmailMessage(): SystemMessage {
+	return {
+		role: "system",
+		message: `I appreciate your excitement! You are already on the waitlist. When I am ready, I will reach out again. Have a good ${timeOfDay()} :)`,
+	}
+}
+
+export function troubleMessage(): SystemMessage {
+	return {
+		role: "system",
+		message: `I apologize, but I am having trouble adding you to the waitlist. Could you refresh the page and try again please in a moment?`,
+	}
+}

apps/waitlist-website/app/chat/use-fake-streaming.ts

@@ -0,0 +1,23 @@
+import { useEffect, useMemo, useState } from "react"
+
+export function useFakeStreaming(fullContent: string) {
+	const [currentContent, setCurrentContent] = useState("")
+	const [isStreaming, setIsStreaming] = useState(true)
+
+	useEffect(() => {
+		const words = fullContent.split(" ")
+
+		let i = 0
+		const id = setInterval(() => {
+			if (i > words.length) {
+				setIsStreaming(false)
+				clearInterval(id)
+			} else {
+				setCurrentContent(words.slice(0, i).join(" ") + " ")
+				i++
+			}
+		}, 20)
+	}, [fullContent])
+
+	return useMemo(() => ({ currentContent, isStreaming }), [currentContent, isStreaming])
+}

apps/waitlist-website/app/components/animated-logo.tsx

@@ -0,0 +1,168 @@
+import Lottie, { type LottieRef } from "lottie-react"
+import { useEffect, useRef, useState } from "react"
+
+import { useColorScheme } from "~/hooks/use-color-scheme"
+import clickedAnimationDark from "~/lottie/clicked-dark.json"
+import clickedAnimationLight from "~/lottie/clicked-light.json"
+import loadingAnimationDark from "~/lottie/loading-dark.json"
+import loadingAnimationLight from "~/lottie/loading-light.json"
+import startLoadingAnimationDark from "~/lottie/start-loading-dark.json"
+import startLoadingAnimationLight from "~/lottie/start-loading-light.json"
+
+export const AnimatedLogoState = {
+	Idle: "idle",
+	Loading: "loading",
+} as const
+export type AnimatedLogoState = (typeof AnimatedLogoState)[keyof typeof AnimatedLogoState]
+
+interface AnimatedLogoProps {
+	state: AnimatedLogoState
+	className?: string
+}
+
+interface Animation {
+	loop: boolean
+	reverse: boolean
+	sticky: boolean
+	data: unknown
+}
+
+export function AnimatedLogo({ state, className }: AnimatedLogoProps) {
+	const colorScheme = useColorScheme()
+	const [animationQueue, setAnimationQueue] = useState<Animation[]>([])
+	const lottieRef: LottieRef = useRef(null)
+
+	let currentAnimation: Animation
+	let isIdle = false
+	if (animationQueue.length === 0) {
+		isIdle = true
+		currentAnimation = {
+			loop: false,
+			reverse: false,
+			sticky: false,
+			data: colorScheme === "dark" ? startLoadingAnimationDark : startLoadingAnimationLight,
+		}
+	} else {
+		isIdle = false
+		currentAnimation = animationQueue[0]
+	}
+
+	useEffect(() => {
+		if (state === AnimatedLogoState.Loading) {
+			setAnimationQueue((queue) => [
+				...queue,
+				{
+					loop: false,
+					reverse: false,
+					sticky: false,
+					data: colorScheme === "dark" ? startLoadingAnimationDark : startLoadingAnimationLight,
+				},
+				{
+					loop: true,
+					reverse: false,
+					sticky: false,
+					data: colorScheme === "dark" ? loadingAnimationDark : loadingAnimationLight,
+				},
+			])
+		} else if (state === AnimatedLogoState.Idle) {
+			setAnimationQueue((queue) => {
+				const last = queue.at(-1)
+				if (!last) {
+					return []
+				}
+				if (
+					last.loop &&
+					(last.data === loadingAnimationDark || last.data === loadingAnimationLight)
+				) {
+					return [
+						...queue,
+						{
+							loop: false,
+							sticky: false,
+							reverse: false,
+							data: colorScheme === "dark" ? loadingAnimationDark : loadingAnimationLight,
+						},
+						{
+							loop: false,
+							sticky: false,
+							reverse: true,
+							data: colorScheme === "dark" ? startLoadingAnimationDark : startLoadingAnimationLight,
+						},
+					]
+				}
+				return []
+			})
+		}
+	}, [state])
+
+	useEffect(() => {
+		if (!lottieRef.current) {
+			return
+		}
+		if (currentAnimation.reverse) {
+			const frames = lottieRef.current.getDuration(true)
+			if (frames) {
+				lottieRef.current.setDirection(-1)
+				lottieRef.current.goToAndPlay(frames - 1, true)
+			}
+		} else if (!isIdle) {
+			lottieRef.current.setDirection(1)
+			lottieRef.current.play()
+		}
+	}, [currentAnimation])
+
+	function onComplete() {
+		if (animationQueue.length > 0 && !animationQueue[0].sticky) {
+			setAnimationQueue((queue) => queue.slice(1))
+		}
+	}
+
+	function onLoopComplete() {
+		const current = animationQueue[0]
+		const next = animationQueue[1]
+		if (current && next && current.data === next.data && current.loop && !next.loop) {
+			setAnimationQueue((queue) => queue.slice(2))
+		}
+	}
+
+	function onMouseDown() {
+		if (state === AnimatedLogoState.Idle) {
+			setAnimationQueue([
+				{
+					loop: false,
+					sticky: true,
+					reverse: false,
+					data: colorScheme === "dark" ? clickedAnimationDark : clickedAnimationLight,
+				},
+			])
+		}
+	}
+
+	function onMouseUp() {
+		if (state === AnimatedLogoState.Idle) {
+			setAnimationQueue((queue) => [
+				{
+					loop: false,
+					sticky: false,
+					reverse: true,
+					data: colorScheme === "dark" ? clickedAnimationDark : clickedAnimationLight,
+				},
+			])
+		}
+	}
+
+	return (
+		<Lottie
+			lottieRef={lottieRef}
+			autoplay={false}
+			loop={currentAnimation.loop}
+			className={className}
+			animationData={currentAnimation.data}
+			onComplete={onComplete}
+			onLoopComplete={onLoopComplete}
+			onMouseDown={onMouseDown}
+			onMouseUp={onMouseUp}
+			onMouseLeave={onMouseUp}
+		/>
+	)
+}

apps/waitlist-website/app/components/progressive-blur.tsx

@@ -0,0 +1,35 @@
+export function ProgressiveBlur({
+	className,
+	direction = "down",
+}: {
+	className?: string
+	direction?: "down" | "up"
+}) {
+	if (direction === "up") {
+		return (
+			<div className={`pointer-events-none ${className ?? ""}`}>
+				<div className="absolute inset-0 backdrop-blur-[1px] [mask:linear-gradient(rgba(0,0,0,0)_0%,rgba(0,0,0,1)_10%,rgba(0,0,0,1)_20%,rgba(0,0,0,0)_30%)]" />
+				<div className="absolute inset-0 backdrop-blur-[2px] [mask:linear-gradient(rgba(0,0,0,0)_10%,rgba(0,0,0,1)_20%,rgba(0,0,0,1)_40%,rgba(0,0,0,0)_50%)]" />
+				<div className="absolute inset-0 backdrop-blur-[4px] [mask:linear-gradient(rgba(0,0,0,0)_20%,rgba(0,0,0,1)_30%,rgba(0,0,0,1)_50%,rgba(0,0,0,0)_60%)]" />
+				<div className="absolute inset-0 backdrop-blur-[8px] [mask:linear-gradient(rgba(0,0,0,0)_30%,rgba(0,0,0,1)_40%,rgba(0,0,0,1)_60%,rgba(0,0,0,0)_70%)]" />
+				<div className="absolute inset-0 backdrop-blur-[16px] [mask:linear-gradient(rgba(0,0,0,0)_40%,rgba(0,0,0,1)_50%,rgba(0,0,0,1)_70%,rgba(0,0,0,0)_80%)]" />
+				<div className="absolute inset-0 backdrop-blur-[32px] [mask:linear-gradient(rgba(0,0,0,0)_50%,rgba(0,0,0,1)_60%,rgba(0,0,0,1)_80%,rgba(0,0,0,0)_90%)]" />
+				<div className="absolute inset-0 backdrop-blur-[64px] [mask:linear-gradient(rgba(0,0,0,0)_70%,rgba(0,0,0,1)_80%,rgba(0,0,0,1)_100%)]" />
+				<div className="absolute inset-0 bg-linear-to-t from-stone-50 dark:from-stone-900 to-transparent" />
+			</div>
+		)
+	}
+
+	return (
+		<div className={`pointer-events-none ${className ?? ""}`}>
+			<div className="absolute inset-0 backdrop-blur-[64px] [mask:linear-gradient(rgba(0,0,0,1)_0%,rgba(0,0,0,1)_20%,rgba(0,0,0,0)_30%)]" />
+			<div className="absolute inset-0 backdrop-blur-[32px] [mask:linear-gradient(rgba(0,0,0,0)_10%,rgba(0,0,0,1)_20%,rgba(0,0,0,1)_40%,rgba(0,0,0,0)_50%)]" />
+			<div className="absolute inset-0 backdrop-blur-[16px] [mask:linear-gradient(rgba(0,0,0,0)_20%,rgba(0,0,0,1)_30%,rgba(0,0,0,1)_50%,rgba(0,0,0,0)_60%)]" />
+			<div className="absolute inset-0 backdrop-blur-[8px] [mask:linear-gradient(rgba(0,0,0,0)_30%,rgba(0,0,0,1)_40%,rgba(0,0,0,1)_60%,rgba(0,0,0,0)_70%)]" />
+			<div className="absolute inset-0 backdrop-blur-[4px] [mask:linear-gradient(rgba(0,0,0,0)_40%,rgba(0,0,0,1)_50%,rgba(0,0,0,1)_70%,rgba(0,0,0,0)_80%)]" />
+			<div className="absolute inset-0 backdrop-blur-[2px] [mask:linear-gradient(rgba(0,0,0,0)_50%,rgba(0,0,0,1)_60%,rgba(0,0,0,1)_80%,rgba(0,0,0,0)_90%)]" />
+			<div className="absolute inset-0 backdrop-blur-[1px] [mask:linear-gradient(rgba(0,0,0,0)_70%,rgba(0,0,0,1)_80%,rgba(0,0,0,1)_90%,rgba(0,0,0,0)_100%)]" />
+			<div className="absolute inset-0 bg-linear-to-b from-stone-50 dark:from-stone-900 to-transparent" />
+		</div>
+	)
+}

apps/waitlist-website/app/hooks/use-color-scheme.ts

@@ -0,0 +1,27 @@
+import { useEffect, useState } from "react"
+
+export const ColorScheme = {
+	Light: "light",
+	Dark: "dark",
+} as const
+export type ColorScheme = (typeof ColorScheme)[keyof typeof ColorScheme]
+
+export function useColorScheme(): ColorScheme {
+	const [scheme, setScheme] = useState<ColorScheme>(() => {
+		if (typeof window === "undefined") return ColorScheme.Light
+		return window.matchMedia("(prefers-color-scheme: dark)").matches
+			? ColorScheme.Dark
+			: ColorScheme.Light
+	})
+
+	useEffect(() => {
+		const mql = window.matchMedia("(prefers-color-scheme: dark)")
+		const handler = (e: MediaQueryListEvent) => {
+			setScheme(e.matches ? ColorScheme.Dark : ColorScheme.Light)
+		}
+		mql.addEventListener("change", handler)
+		return () => mql.removeEventListener("change", handler)
+	}, [])
+
+	return scheme
+}

apps/waitlist-website/app/lottie/clicked-dark.json

@@ -0,0 +1 @@
+{"fr":60,"h":400,"ip":0,"layers":[{"ind":3,"ty":4,"parent":2,"ks":{},"ip":0,"op":7,"st":0,"shapes":[{"ty":"gr","it":[{"ty":"rc","p":{"a":0,"k":[160,53]},"r":{"a":0,"k":0},"s":{"a":0,"k":[336,122]}},{"ty":"fl","c":{"a":0,"k":[0,0,0,0]},"o":{"a":0,"k":0}},{"ty":"tr","o":{"a":0,"k":100}}]},{"ty":"gr","it":[{"ty":"el","p":{"a":0,"k":[160,53]},"s":{"a":0,"k":[320,106]}},{"ty":"st","c":{"a":0,"k":[0.906,0.898,0.894]},"lc":1,"lj":1,"ml":10,"o":{"a":0,"k":100},"w":{"a":0,"k":16}},{"ty":"tr","o":{"a":0,"k":100}}]}]},{"ind":2,"ty":3,"parent":1,"ks":{"a":{"a":0,"k":[160,53]},"p":{"a":0,"k":[200.5,200]},"r":{"a":1,"k":[{"t":0,"s":[-30],"i":{"x":0,"y":1},"o":{"x":0.5,"y":0}},{"t":6,"s":[-10],"h":1}]}},"ip":0,"op":7,"st":0},{"ind":5,"ty":4,"parent":4,"ks":{},"ip":0,"op":7,"st":0,"shapes":[{"ty":"gr","it":[{"ty":"rc","p":{"a":0,"k":[160,53]},"r":{"a":0,"k":0},"s":{"a":0,"k":[336,122]}},{"ty":"fl","c":{"a":0,"k":[0,0,0,0]},"o":{"a":0,"k":0}},{"ty":"tr","o":{"a":0,"k":100}}]},{"ty":"gr","it":[{"ty":"el","p":{"a":0,"k":[160,53]},"s":{"a":0,"k":[320,106]}},{"ty":"st","c":{"a":0,"k":[0.906,0.898,0.894]},"lc":1,"lj":1,"ml":10,"o":{"a":0,"k":100},"w":{"a":0,"k":16}},{"ty":"tr","o":{"a":0,"k":100}}]}]},{"ind":4,"ty":3,"parent":1,"ks":{"a":{"a":0,"k":[160,53]},"p":{"a":0,"k":[200.594,200.176]},"r":{"a":1,"k":[{"t":0,"s":[30],"i":{"x":0,"y":1},"o":{"x":0.5,"y":0}},{"t":6,"s":[10],"h":1}]}},"ip":0,"op":7,"st":0},{"ind":1,"ty":3,"parent":0,"ks":{},"ip":0,"op":7,"st":0},{"ind":0,"ty":3,"ks":{},"ip":0,"op":7,"st":0}],"meta":{"g":"https://jitter.video"},"op":6,"v":"5.7.4","w":400}

apps/waitlist-website/app/lottie/clicked-light.json

@@ -0,0 +1 @@
+{"fr":60,"h":400,"ip":0,"layers":[{"ind":3,"ty":4,"parent":2,"ks":{},"ip":0,"op":7,"st":0,"shapes":[{"ty":"gr","it":[{"ty":"rc","p":{"a":0,"k":[160,53]},"r":{"a":0,"k":0},"s":{"a":0,"k":[336,122]}},{"ty":"fl","c":{"a":0,"k":[0,0,0,0]},"o":{"a":0,"k":0}},{"ty":"tr","o":{"a":0,"k":100}}]},{"ty":"gr","it":[{"ty":"el","p":{"a":0,"k":[160,53]},"s":{"a":0,"k":[320,106]}},{"ty":"st","c":{"a":0,"k":[0.11,0.098,0.09]},"lc":1,"lj":1,"ml":10,"o":{"a":0,"k":100},"w":{"a":0,"k":16}},{"ty":"tr","o":{"a":0,"k":100}}]}]},{"ind":2,"ty":3,"parent":1,"ks":{"a":{"a":0,"k":[160,53]},"p":{"a":0,"k":[200.5,200]},"r":{"a":1,"k":[{"t":0,"s":[-30],"i":{"x":0,"y":1},"o":{"x":0.5,"y":0}},{"t":6,"s":[-10],"h":1}]}},"ip":0,"op":7,"st":0},{"ind":5,"ty":4,"parent":4,"ks":{},"ip":0,"op":7,"st":0,"shapes":[{"ty":"gr","it":[{"ty":"rc","p":{"a":0,"k":[160,53]},"r":{"a":0,"k":0},"s":{"a":0,"k":[336,122]}},{"ty":"fl","c":{"a":0,"k":[0,0,0,0]},"o":{"a":0,"k":0}},{"ty":"tr","o":{"a":0,"k":100}}]},{"ty":"gr","it":[{"ty":"el","p":{"a":0,"k":[160,53]},"s":{"a":0,"k":[320,106]}},{"ty":"st","c":{"a":0,"k":[0.11,0.098,0.09]},"lc":1,"lj":1,"ml":10,"o":{"a":0,"k":100},"w":{"a":0,"k":16}},{"ty":"tr","o":{"a":0,"k":100}}]}]},{"ind":4,"ty":3,"parent":1,"ks":{"a":{"a":0,"k":[160,53]},"p":{"a":0,"k":[200.594,200.176]},"r":{"a":1,"k":[{"t":0,"s":[30],"i":{"x":0,"y":1},"o":{"x":0.5,"y":0}},{"t":6,"s":[10],"h":1}]}},"ip":0,"op":7,"st":0},{"ind":1,"ty":3,"parent":0,"ks":{},"ip":0,"op":7,"st":0},{"ind":0,"ty":3,"ks":{},"ip":0,"op":7,"st":0}],"meta":{"g":"https://jitter.video"},"op":6,"v":"5.7.4","w":400}

apps/waitlist-website/app/lottie/loading-dark.json

@@ -0,0 +1 @@
+{"fr":60,"h":400,"ip":0,"layers":[{"ind":3,"ty":4,"parent":2,"ks":{},"ip":0,"op":61,"st":0,"shapes":[{"ty":"gr","it":[{"ty":"rc","p":{"a":0,"k":[160,26.75]},"r":{"a":0,"k":0},"s":{"a":0,"k":[336,174.5]}},{"ty":"fl","c":{"a":0,"k":[0,0,0,0]},"o":{"a":0,"k":0}},{"ty":"tr","o":{"a":0,"k":100}}]},{"ty":"gr","it":[{"ty":"el","p":{"a":1,"k":[{"t":0,"s":[160,0.5],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":8.4,"s":[160,0.5],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":30,"s":[160,53],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":37.8,"s":[160,53],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":60,"s":[160,0.5],"h":1}]},"s":{"a":1,"k":[{"t":0,"s":[320,1],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":8.4,"s":[320,1],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":30,"s":[320,106],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":37.8,"s":[320,106],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":60,"s":[320,1],"h":1}]}},{"ty":"st","c":{"a":0,"k":[0.906,0.898,0.894]},"lc":1,"lj":1,"ml":10,"o":{"a":0,"k":100},"w":{"a":0,"k":16}},{"ty":"tr","o":{"a":0,"k":100}}]}]},{"ind":2,"ty":3,"parent":1,"ks":{"a":{"a":1,"k":[{"t":0,"s":[160,0.5],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":8.4,"s":[160,0.5],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":30,"s":[160,53],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":37.8,"s":[160,53],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":60,"s":[160,0.5],"h":1}]},"p":{"a":0,"k":[200,200.014]},"r":{"a":1,"k":[{"t":0,"s":[-90],"h":1},{"t":8.4,"s":[-90],"i":{"x":0,"y":1},"o":{"x":0.5,"y":0}},{"t":30,"s":[0],"h":1},{"t":37.8,"s":[0],"i":{"x":0,"y":1},"o":{"x":0.5,"y":0}},{"t":60,"s":[90],"h":1}]}},"ip":0,"op":61,"st":0},{"ind":5,"ty":4,"parent":4,"ks":{},"ip":0,"op":61,"st":0,"shapes":[{"ty":"gr","it":[{"ty":"rc","p":{"a":0,"k":[160,26.75]},"r":{"a":0,"k":0},"s":{"a":0,"k":[336,174.5]}},{"ty":"fl","c":{"a":0,"k":[0,0,0,0]},"o":{"a":0,"k":0}},{"ty":"tr","o":{"a":0,"k":100}}]},{"ty":"gr","it":[{"ty":"el","p":{"a":1,"k":[{"t":0,"s":[160,0.5],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":30,"s":[160,53],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":60,"s":[160,0.5],"h":1}]},"s":{"a":1,"k":[{"t":0,"s":[320,1],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":30,"s":[320,106],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":60,"s":[320,1],"h":1}]}},{"ty":"st","c":{"a":0,"k":[0.906,0.898,0.894]},"lc":1,"lj":1,"ml":10,"o":{"a":0,"k":100},"w":{"a":0,"k":16}},{"ty":"tr","o":{"a":0,"k":100}}]}]},{"ind":4,"ty":3,"parent":1,"ks":{"a":{"a":1,"k":[{"t":0,"s":[160,0.5],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":30,"s":[160,53],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":60,"s":[160,0.5],"h":1}]},"p":{"a":0,"k":[200.094,200.19]},"r":{"a":1,"k":[{"t":0,"s":[-90],"i":{"x":0,"y":1},"o":{"x":0.5,"y":0}},{"t":30,"s":[0],"i":{"x":0,"y":1},"o":{"x":0.5,"y":0}},{"t":60,"s":[90],"h":1}]}},"ip":0,"op":61,"st":0},{"ind":1,"ty":3,"parent":0,"ks":{},"ip":0,"op":61,"st":0},{"ind":0,"ty":3,"ks":{},"ip":0,"op":61,"st":0}],"meta":{"g":"https://jitter.video"},"op":60,"v":"5.7.4","w":400}

apps/waitlist-website/app/lottie/loading-light.json

@@ -0,0 +1 @@
+{"fr":60,"h":400,"ip":0,"layers":[{"ind":3,"ty":4,"parent":2,"ks":{},"ip":0,"op":61,"st":0,"shapes":[{"ty":"gr","it":[{"ty":"rc","p":{"a":0,"k":[160,26.75]},"r":{"a":0,"k":0},"s":{"a":0,"k":[336,174.5]}},{"ty":"fl","c":{"a":0,"k":[0,0,0,0]},"o":{"a":0,"k":0}},{"ty":"tr","o":{"a":0,"k":100}}]},{"ty":"gr","it":[{"ty":"el","p":{"a":1,"k":[{"t":0,"s":[160,0.5],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":8.4,"s":[160,0.5],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":30,"s":[160,53],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":37.8,"s":[160,53],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":60,"s":[160,0.5],"h":1}]},"s":{"a":1,"k":[{"t":0,"s":[320,1],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":8.4,"s":[320,1],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":30,"s":[320,106],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":37.8,"s":[320,106],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":60,"s":[320,1],"h":1}]}},{"ty":"st","c":{"a":0,"k":[0.11,0.098,0.09]},"lc":1,"lj":1,"ml":10,"o":{"a":0,"k":100},"w":{"a":0,"k":16}},{"ty":"tr","o":{"a":0,"k":100}}]}]},{"ind":2,"ty":3,"parent":1,"ks":{"a":{"a":1,"k":[{"t":0,"s":[160,0.5],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":8.4,"s":[160,0.5],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":30,"s":[160,53],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":37.8,"s":[160,53],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":60,"s":[160,0.5],"h":1}]},"p":{"a":0,"k":[200,200.014]},"r":{"a":1,"k":[{"t":0,"s":[-90],"h":1},{"t":8.4,"s":[-90],"i":{"x":0,"y":1},"o":{"x":0.5,"y":0}},{"t":30,"s":[0],"h":1},{"t":37.8,"s":[0],"i":{"x":0,"y":1},"o":{"x":0.5,"y":0}},{"t":60,"s":[90],"h":1}]}},"ip":0,"op":61,"st":0},{"ind":5,"ty":4,"parent":4,"ks":{},"ip":0,"op":61,"st":0,"shapes":[{"ty":"gr","it":[{"ty":"rc","p":{"a":0,"k":[160,26.75]},"r":{"a":0,"k":0},"s":{"a":0,"k":[336,174.5]}},{"ty":"fl","c":{"a":0,"k":[0,0,0,0]},"o":{"a":0,"k":0}},{"ty":"tr","o":{"a":0,"k":100}}]},{"ty":"gr","it":[{"ty":"el","p":{"a":1,"k":[{"t":0,"s":[160,0.5],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":30,"s":[160,53],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":60,"s":[160,0.5],"h":1}]},"s":{"a":1,"k":[{"t":0,"s":[320,1],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":30,"s":[320,106],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":60,"s":[320,1],"h":1}]}},{"ty":"st","c":{"a":0,"k":[0.11,0.098,0.09]},"lc":1,"lj":1,"ml":10,"o":{"a":0,"k":100},"w":{"a":0,"k":16}},{"ty":"tr","o":{"a":0,"k":100}}]}]},{"ind":4,"ty":3,"parent":1,"ks":{"a":{"a":1,"k":[{"t":0,"s":[160,0.5],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":30,"s":[160,53],"i":{"x":[1,0],"y":[1,1]},"o":{"x":[0,0.5],"y":[0,0]}},{"t":60,"s":[160,0.5],"h":1}]},"p":{"a":0,"k":[200.094,200.19]},"r":{"a":1,"k":[{"t":0,"s":[-90],"i":{"x":0,"y":1},"o":{"x":0.5,"y":0}},{"t":30,"s":[0],"i":{"x":0,"y":1},"o":{"x":0.5,"y":0}},{"t":60,"s":[90],"h":1}]}},"ip":0,"op":61,"st":0},{"ind":1,"ty":3,"parent":0,"ks":{},"ip":0,"op":61,"st":0},{"ind":0,"ty":3,"ks":{},"ip":0,"op":61,"st":0}],"meta":{"g":"https://jitter.video"},"op":60,"v":"5.7.4","w":400}

apps/waitlist-website/app/lottie/start-loading-dark.json

@@ -0,0 +1 @@
+{"fr":60,"h":400,"ip":0,"layers":[{"ind":3,"ty":4,"parent":2,"ks":{},"ip":0,"op":31,"st":0,"shapes":[{"ty":"gr","it":[{"ty":"rc","p":{"a":0,"k":[160,26.75]},"r":{"a":0,"k":0},"s":{"a":0,"k":[336,174.5]}},{"ty":"fl","c":{"a":0,"k":[0,0,0,0]},"o":{"a":0,"k":0}},{"ty":"tr","o":{"a":0,"k":100}}]},{"ty":"gr","it":[{"ty":"el","p":{"a":1,"k":[{"t":0,"s":[160,53],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":5.28,"s":[160,53],"i":{"x":[1,0.001],"y":[1,0.998]},"o":{"x":[0,0.349],"y":[0,0]}},{"t":30,"s":[160,0.5],"h":1}]},"s":{"a":1,"k":[{"t":0,"s":[320,106],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":5.28,"s":[320,106],"i":{"x":[1,0.001],"y":[1,0.998]},"o":{"x":[0,0.349],"y":[0,0]}},{"t":30,"s":[320,1],"h":1}]}},{"ty":"st","c":{"a":0,"k":[0.906,0.898,0.894]},"lc":1,"lj":1,"ml":10,"o":{"a":0,"k":100},"w":{"a":0,"k":16}},{"ty":"tr","o":{"a":0,"k":100}}]}]},{"ind":2,"ty":3,"parent":1,"ks":{"a":{"a":1,"k":[{"t":0,"s":[160,53],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":5.28,"s":[160,53],"i":{"x":[1,0.001],"y":[1,0.998]},"o":{"x":[0,0.349],"y":[0,0]}},{"t":30,"s":[160,0.5],"h":1}]},"p":{"a":0,"k":[200.5,200]},"r":{"a":1,"k":[{"t":0,"s":[-30],"h":1},{"t":5.28,"s":[-30],"i":{"x":0.001,"y":0.998},"o":{"x":0.349,"y":0}},{"t":30,"s":[-90],"h":1}]}},"ip":0,"op":31,"st":0},{"ind":5,"ty":4,"parent":4,"ks":{},"ip":0,"op":31,"st":0,"shapes":[{"ty":"gr","it":[{"ty":"rc","p":{"a":0,"k":[160,26.75]},"r":{"a":0,"k":0},"s":{"a":0,"k":[336,174.5]}},{"ty":"fl","c":{"a":0,"k":[0,0,0,0]},"o":{"a":0,"k":0}},{"ty":"tr","o":{"a":0,"k":100}}]},{"ty":"gr","it":[{"ty":"el","p":{"a":1,"k":[{"t":0,"s":[160,53],"i":{"x":[1,0],"y":[1,0.999]},"o":{"x":[0,0.348],"y":[0,0]}},{"t":30,"s":[160,0.5],"h":1}]},"s":{"a":1,"k":[{"t":0,"s":[320,106],"i":{"x":[1,0],"y":[1,0.999]},"o":{"x":[0,0.348],"y":[0,0]}},{"t":30,"s":[320,1],"h":1}]}},{"ty":"st","c":{"a":0,"k":[0.906,0.898,0.894]},"lc":1,"lj":1,"ml":10,"o":{"a":0,"k":100},"w":{"a":0,"k":16}},{"ty":"tr","o":{"a":0,"k":100}}]}]},{"ind":4,"ty":3,"parent":1,"ks":{"a":{"a":1,"k":[{"t":0,"s":[160,53],"i":{"x":[1,0],"y":[1,0.999]},"o":{"x":[0,0.348],"y":[0,0]}},{"t":30,"s":[160,0.5],"h":1}]},"p":{"a":0,"k":[200.594,200.176]},"r":{"a":1,"k":[{"t":0,"s":[30],"i":{"x":0,"y":0.999},"o":{"x":0.348,"y":0}},{"t":30,"s":[90],"h":1}]}},"ip":0,"op":31,"st":0},{"ind":1,"ty":3,"parent":0,"ks":{},"ip":0,"op":31,"st":0},{"ind":0,"ty":3,"ks":{},"ip":0,"op":31,"st":0}],"meta":{"g":"https://jitter.video"},"op":30,"v":"5.7.4","w":400}

apps/waitlist-website/app/lottie/start-loading-light.json

@@ -0,0 +1 @@
+{"fr":60,"h":400,"ip":0,"layers":[{"ind":3,"ty":4,"parent":2,"ks":{},"ip":0,"op":31,"st":0,"shapes":[{"ty":"gr","it":[{"ty":"rc","p":{"a":0,"k":[160,26.75]},"r":{"a":0,"k":0},"s":{"a":0,"k":[336,174.5]}},{"ty":"fl","c":{"a":0,"k":[0,0,0,0]},"o":{"a":0,"k":0}},{"ty":"tr","o":{"a":0,"k":100}}]},{"ty":"gr","it":[{"ty":"el","p":{"a":1,"k":[{"t":0,"s":[160,53],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":5.28,"s":[160,53],"i":{"x":[1,0.001],"y":[1,0.998]},"o":{"x":[0,0.349],"y":[0,0]}},{"t":30,"s":[160,0.5],"h":1}]},"s":{"a":1,"k":[{"t":0,"s":[320,106],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":5.28,"s":[320,106],"i":{"x":[1,0.001],"y":[1,0.998]},"o":{"x":[0,0.349],"y":[0,0]}},{"t":30,"s":[320,1],"h":1}]}},{"ty":"st","c":{"a":0,"k":[0.11,0.098,0.09]},"lc":1,"lj":1,"ml":10,"o":{"a":0,"k":100},"w":{"a":0,"k":16}},{"ty":"tr","o":{"a":0,"k":100}}]}]},{"ind":2,"ty":3,"parent":1,"ks":{"a":{"a":1,"k":[{"t":0,"s":[160,53],"i":{"x":[1,1],"y":[1,1]},"o":{"x":[0,0],"y":[0,0]}},{"t":5.28,"s":[160,53],"i":{"x":[1,0.001],"y":[1,0.998]},"o":{"x":[0,0.349],"y":[0,0]}},{"t":30,"s":[160,0.5],"h":1}]},"p":{"a":0,"k":[200.5,200]},"r":{"a":1,"k":[{"t":0,"s":[-30],"h":1},{"t":5.28,"s":[-30],"i":{"x":0.001,"y":0.998},"o":{"x":0.349,"y":0}},{"t":30,"s":[-90],"h":1}]}},"ip":0,"op":31,"st":0},{"ind":5,"ty":4,"parent":4,"ks":{},"ip":0,"op":31,"st":0,"shapes":[{"ty":"gr","it":[{"ty":"rc","p":{"a":0,"k":[160,26.75]},"r":{"a":0,"k":0},"s":{"a":0,"k":[336,174.5]}},{"ty":"fl","c":{"a":0,"k":[0,0,0,0]},"o":{"a":0,"k":0}},{"ty":"tr","o":{"a":0,"k":100}}]},{"ty":"gr","it":[{"ty":"el","p":{"a":1,"k":[{"t":0,"s":[160,53],"i":{"x":[1,0],"y":[1,0.999]},"o":{"x":[0,0.348],"y":[0,0]}},{"t":30,"s":[160,0.5],"h":1}]},"s":{"a":1,"k":[{"t":0,"s":[320,106],"i":{"x":[1,0],"y":[1,0.999]},"o":{"x":[0,0.348],"y":[0,0]}},{"t":30,"s":[320,1],"h":1}]}},{"ty":"st","c":{"a":0,"k":[0.11,0.098,0.09]},"lc":1,"lj":1,"ml":10,"o":{"a":0,"k":100},"w":{"a":0,"k":16}},{"ty":"tr","o":{"a":0,"k":100}}]}]},{"ind":4,"ty":3,"parent":1,"ks":{"a":{"a":1,"k":[{"t":0,"s":[160,53],"i":{"x":[1,0],"y":[1,0.999]},"o":{"x":[0,0.348],"y":[0,0]}},{"t":30,"s":[160,0.5],"h":1}]},"p":{"a":0,"k":[200.594,200.176]},"r":{"a":1,"k":[{"t":0,"s":[30],"i":{"x":0,"y":0.999},"o":{"x":0.348,"y":0}},{"t":30,"s":[90],"h":1}]}},"ip":0,"op":31,"st":0},{"ind":1,"ty":3,"parent":0,"ks":{},"ip":0,"op":31,"st":0},{"ind":0,"ty":3,"ks":{},"ip":0,"op":31,"st":0}],"meta":{"g":"https://jitter.video"},"op":30,"v":"5.7.4","w":400}

apps/waitlist-website/app/root.tsx

@@ -0,0 +1,88 @@
+import { isRouteErrorResponse, Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router"
+
+import type { Route } from "./+types/root"
+
+import "./app.css"
+import "streamdown/styles.css"
+
+export const links: Route.LinksFunction = () => [
+	{ rel: "preconnect", href: "https://fonts.googleapis.com" },
+	{
+		rel: "preconnect",
+		href: "https://fonts.gstatic.com",
+		crossOrigin: "anonymous",
+	},
+	{
+		rel: "stylesheet",
+		href: "https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap",
+	},
+	{
+		rel: "icon",
+		href: "/favicon-light.svg",
+		type: "image/svg+xml",
+		media: "(prefers-color-scheme: light)",
+	},
+	{
+		rel: "icon",
+		href: "/favicon-dark.svg",
+		type: "image/svg+xml",
+		media: "(prefers-color-scheme: dark)",
+	},
+	{
+		rel: "icon",
+		href: "/favicon.ico",
+		sizes: "any",
+	},
+]
+
+export function Layout({ children }: { children: React.ReactNode }) {
+	return (
+		<html lang="en">
+			<head>
+				<meta charSet="utf-8" />
+				<meta name="viewport" content="width=device-width, initial-scale=1" />
+				<Meta />
+				<Links />
+			</head>
+			<body>
+				{children}
+				<ScrollRestoration />
+				<Scripts />
+			</body>
+		</html>
+	)
+}
+
+export default function App() {
+	return <Outlet />
+}
+
+export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
+	let message = "Oops!"
+	let details = "An unexpected error occurred."
+	let stack: string | undefined
+
+	if (isRouteErrorResponse(error)) {
+		message = error.status === 404 ? "404" : "Error"
+		details =
+			error.status === 404 ? "The requested page could not be found." : error.statusText || details
+	} else if (import.meta.env.DEV && error && error instanceof Error) {
+		details = error.message
+		stack = error.stack
+	}
+
+	return (
+		<main className="flex flex-col items-center justify-center w-full h-full gap-4">
+			<h1 className="text-6xl font-semibold">{message}</h1>
+			<p className="text-stone-600 dark:text-stone-400">{details}</p>
+			<a href="/" className="mt-4 text-sm underline opacity-50 hover:opacity-75">
+				Back to home
+			</a>
+			{stack && (
+				<pre className="mt-8 w-full max-w-2xl p-4 overflow-x-auto text-xs bg-stone-100 dark:bg-stone-800 rounded-lg">
+					<code>{stack}</code>
+				</pre>
+			)}
+		</main>
+	)
+}

apps/waitlist-website/app/routes.ts

@@ -0,0 +1,6 @@
+import { type RouteConfig, index, route } from "@react-router/dev/routes"
+
+export default [
+	index("routes/home.tsx"),
+	route("privacy", "routes/privacy-policy.tsx"),
+] satisfies RouteConfig

apps/waitlist-website/app/routes/home.tsx

@@ -0,0 +1,395 @@
+import { AnimatePresence, motion } from "motion/react"
+import React, { useEffect, useLayoutEffect, useRef, useState } from "react"
+import { Link, useFetcher } from "react-router"
+import { Resend } from "resend"
+import { Streamdown } from "streamdown"
+
+import { ChatBox } from "~/chat/chat-box"
+import {
+	duplicateEmailMessage,
+	INITIAL_MESSAGES,
+	troubleMessage,
+	waitListJoinedMessage,
+	type Message,
+	type SystemMessage,
+	type UserMessage,
+} from "~/chat/message"
+import { useFakeStreaming } from "~/chat/use-fake-streaming"
+import {
+	AnimatedLogo,
+	AnimatedLogoState,
+	AnimatedLogoState as TAnimatedLogoState,
+} from "~/components/animated-logo"
+import { ProgressiveBlur } from "~/components/progressive-blur"
+
+import type { Route } from "./+types/home"
+
+const PAGE_TITLE = "Aelis - Next Generation AI Assistant"
+const PAGE_DESCRIPTION =
+	"Meet Aelis, a personal assistant that stays one step ahead of your day. Join the waitlist now."
+
+export function meta({}: Route.MetaArgs) {
+	return [
+		{ title: PAGE_TITLE },
+		{
+			name: "description",
+			content: PAGE_DESCRIPTION,
+		},
+		{ property: "og:title", content: PAGE_TITLE },
+		{ property: "og:description", content: PAGE_DESCRIPTION },
+		{ property: "og:image", content: "https://ael.is/social-media-preview.png" },
+		{ property: "og:url", content: "https://ael.is" },
+		{ property: "og:type", content: "website" },
+		{ name: "twitter:card", content: "summary_large_image" },
+		{ name: "twitter:title", content: PAGE_TITLE },
+		{ name: "twitter:description", content: PAGE_DESCRIPTION },
+		{ name: "twitter:image", content: "https://ael.is/social-media-preview.png" },
+	]
+}
+
+const FormError = {
+	Duplicate: "duplicate",
+	Resend: "resend",
+} as const
+
+export async function action({ request }: Route.ActionArgs) {
+	const formData = await request.formData()
+	const email = formData.get("email")
+
+	if (typeof email !== "string" || !isValidEmail(email)) {
+		return { error: "Invalid email" }
+	}
+
+	const resend = new Resend(process.env.RESEND_API_KEY)
+
+	const segmentId = "b80fb036-74a1-4f7d-bca5-2c035b696071"
+
+	const dup = await resend.contacts.get({
+		email,
+	})
+	if (dup.data) {
+		return { error: FormError.Duplicate }
+	}
+
+	const res = await resend.contacts.create({
+		email,
+		segments: [{ id: segmentId }],
+	})
+
+	if (res.error) {
+		console.log("Error adding contact to Resend:", res.error)
+		return { error: FormError.Resend, message: res.error.message }
+	}
+
+	await new Promise((resolve) => setTimeout(resolve, 1000))
+
+	const emailRes = await resend.emails.send({
+		from: "Aelis <no-reply@ael.is>",
+		to: email,
+		template: {
+			id: "waitlist-confirmation",
+		},
+	})
+
+	if (emailRes.error) {
+		// swallow the error since the user is already added to the waitlist, but log it for debugging
+		console.log("Error sending confirmation email:", emailRes.error)
+	}
+
+	return { email }
+}
+
+export default function Home() {
+	const [messages, setMessages] = useState<Message[]>(INITIAL_MESSAGES)
+	const [emailSent, setEmailSent] = useState("")
+	const [isAnimatingSend, setIsAnimatingSend] = useState(false)
+	const [logoState, setLogoState] = useState<TAnimatedLogoState>(AnimatedLogoState.Idle)
+	const chatBoxRef = useRef<HTMLDivElement>(null)
+	const fetcher = useFetcher()
+
+	useEffect(() => {
+		if (fetcher.data?.email && !isAnimatingSend) {
+			setMessages((messages) => [...messages, waitListJoinedMessage(fetcher.data.email)])
+		} else if (fetcher.data?.error) {
+			if (!isAnimatingSend) {
+				let errorMessage: SystemMessage
+				switch (fetcher.data.error) {
+					case FormError.Duplicate:
+						errorMessage = duplicateEmailMessage()
+						break
+					default: {
+						console.error(fetcher.data.error)
+						errorMessage = troubleMessage()
+						break
+					}
+				}
+				setMessages((messages) => [...messages, errorMessage])
+			}
+		}
+	}, [fetcher.data?.email, fetcher.data?.error, isAnimatingSend])
+
+	const insertEmailMessage = (email: string) => {
+		setEmailSent(email)
+		setIsAnimatingSend(true)
+		setLogoState(AnimatedLogoState.Loading)
+		setMessages((messages) => [
+			...messages,
+			{
+				role: "user",
+				message: email,
+				bubbleLayoutId: "test",
+			},
+		])
+
+		fetcher.submit({ email }, { method: "post" })
+	}
+
+	let chatBox: React.ReactNode
+	if (emailSent && isAnimatingSend) {
+		const chatBoxRect = chatBoxRef.current?.getBoundingClientRect()
+		const mainRect = chatBoxRef.current?.offsetParent?.getBoundingClientRect()
+		chatBox = (
+			<MorphingChatBox
+				chatBoxWidth={chatBoxRef.current?.offsetWidth ?? 0}
+				chatBoxHeight={chatBoxRef.current?.offsetHeight ?? 0}
+				chatBoxLeft={(chatBoxRect?.left ?? 0) - (mainRect?.left ?? 0)}
+				chatBoxTop={(chatBoxRect?.top ?? 0) - (mainRect?.top ?? 0)}
+				onAnimationEnd={() => {
+					setIsAnimatingSend(false)
+				}}
+			>
+				{emailSent}
+			</MorphingChatBox>
+		)
+	} else if (!emailSent) {
+		chatBox = (
+			<AnimatePresence>
+				{logoState === AnimatedLogoState.Idle && !emailSent && (
+					<motion.div
+						ref={chatBoxRef}
+						key="test"
+						className="w-full max-w-2xl absolute bottom-12 px-6 md:px-0 flex justify-center z-20"
+						initial={{ y: 100, opacity: 0 }}
+						animate={{ y: 0, opacity: 1 }}
+						transition={{ type: "spring", stiffness: 300, damping: 30, mass: 1.5 }}
+					>
+						<ChatBox
+							className="w-full max-w-2xl"
+							validate={isValidEmail}
+							disabled={fetcher.state === "submitting" || fetcher.state === "loading"}
+							onSubmit={insertEmailMessage}
+						/>
+					</motion.div>
+				)}
+			</AnimatePresence>
+		)
+	} else {
+		chatBox = null
+	}
+
+	return (
+		<main className="relative w-full h-full flex flex-col items-center justify-start gap-4 overflow-hidden">
+			<ProgressiveBlur className="absolute top-0 left-0 right-0 h-24 z-10" />
+			<AnimatedLogo
+				className="absolute top-4 md:top-8 size-10 z-20 cursor-pointer"
+				state={logoState}
+			/>
+			<MessageList
+				messages={messages}
+				showLastMessage={!isAnimatingSend}
+				onMessageStreamStart={() => {
+					setLogoState(AnimatedLogoState.Loading)
+				}}
+				onMessageStreamEnd={() => {
+					setLogoState(AnimatedLogoState.Idle)
+				}}
+			/>
+			{chatBox}
+			<ProgressiveBlur
+				direction="up"
+				className="absolute bottom-0 left-0 right-0 h-24 z-10 pointer-events-none"
+			/>
+			<footer className="absolute bottom-4 z-20">
+				<Link to="/privacy" className="text-xs opacity-50 underline">
+					Privacy policy
+				</Link>
+			</footer>
+		</main>
+	)
+}
+
+function MorphingChatBox({
+	chatBoxWidth,
+	chatBoxHeight,
+	chatBoxLeft,
+	chatBoxTop,
+	onAnimationEnd,
+	children,
+}: React.PropsWithChildren<{
+	chatBoxWidth: number
+	chatBoxHeight: number
+	chatBoxLeft: number
+	chatBoxTop: number
+	onAnimationEnd: () => void
+}>) {
+	const [targetWidth, setTargetWidth] = useState(-1)
+	const [targetHeight, setTargetHeight] = useState(-1)
+	const [targetCoords, setTargetCoords] = useState([0, 0])
+
+	useLayoutEffect(() => {
+		const bubble = document.getElementById("test")
+		if (bubble) {
+			const mainRect = bubble.closest("main")?.getBoundingClientRect()
+			const rect = bubble.getBoundingClientRect()
+			setTargetWidth(bubble.offsetWidth)
+			setTargetHeight(bubble.offsetHeight)
+			setTargetCoords([rect.left - (mainRect?.left ?? 0), rect.top - (mainRect?.top ?? 0)])
+		}
+	}, [])
+
+	if (targetWidth < 0 || targetHeight < 0) {
+		return null
+	}
+
+	return (
+		<motion.div
+			className="absolute rounded-lg bg-stone-100 dark:bg-stone-800 px-4 py-2 border border-stone-200 dark:border-stone-700"
+			initial={{
+				width: chatBoxWidth,
+				height: chatBoxHeight,
+				borderRadius: 8,
+				left: chatBoxLeft,
+				top: chatBoxTop,
+			}}
+			animate={{
+				width: targetWidth,
+				height: targetHeight,
+				borderTopLeftRadius: 100,
+				borderTopRightRadius: 100,
+				borderBottomRightRadius: 24,
+				borderBottomLeftRadius: 100,
+				left: targetCoords[0],
+				top: targetCoords[1],
+			}}
+			transition={{
+				left: { duration: 0.45, ease: [0.05, 0.8, 0.3, 1] },
+				top: { duration: 0.45, ease: [0.3, 0, 0.2, 1] },
+				width: { duration: 0.45, ease: [0.05, 0.8, 0.3, 1] },
+				height: { duration: 0.45, ease: [0.05, 0.8, 0.3, 1] },
+			}}
+			onAnimationComplete={onAnimationEnd}
+		>
+			{children}
+		</motion.div>
+	)
+}
+
+function MessageList({
+	messages,
+	showLastMessage,
+	onMessageStreamStart,
+	onMessageStreamEnd,
+}: {
+	messages: Message[]
+	showLastMessage: boolean
+	onMessageStreamStart: () => void
+	onMessageStreamEnd: () => void
+}) {
+	return (
+		<ul className="w-full flex flex-col gap-8 overflow-auto px-6 pt-20 md:px-0 md:pt-24 pb-34">
+			{messages.map((message, index) => (
+				<li
+					key={index}
+					className={`flex justify-center ${index === messages.length - 1 && !showLastMessage ? "invisible" : ""}`}
+				>
+					<MessageContent
+						message={message}
+						onMessageStreamStart={onMessageStreamStart}
+						onMessageStreamEnd={onMessageStreamEnd}
+					/>
+				</li>
+			))}
+		</ul>
+	)
+}
+
+function MessageContent({
+	message,
+	onMessageStreamStart,
+	onMessageStreamEnd,
+}: {
+	message: Message
+	onMessageStreamStart: () => void
+	onMessageStreamEnd: () => void
+}) {
+	switch (message.role) {
+		case "user":
+			return <UserMessageBubble message={message} />
+		case "system":
+			return (
+				<SystemMessageBubble
+					message={message}
+					onStreamStart={onMessageStreamStart}
+					onStreamEnd={onMessageStreamEnd}
+				/>
+			)
+	}
+}
+
+function UserMessageBubble({ message }: { message: UserMessage }) {
+	return (
+		<div className="w-full max-w-2xl flex justify-end">
+			<div
+				id={message.bubbleLayoutId}
+				className="rounded-[100px_100px_24px_100px] bg-stone-100 dark:bg-stone-800 border border-stone-200 dark:border-stone-700 px-4 py-2"
+			>
+				{message.message}
+			</div>
+		</div>
+	)
+}
+
+function SystemMessageBubble({
+	message,
+	onStreamStart,
+	onStreamEnd,
+}: {
+	message: SystemMessage
+	onStreamStart: () => void
+	onStreamEnd: () => void
+}) {
+	const { currentContent, isStreaming } = useFakeStreaming(message.message)
+	const ref = useRef<HTMLDivElement>(null)
+
+	useEffect(() => {
+		ref.current?.scrollIntoView({ behavior: "smooth", block: "end" })
+	}, [currentContent])
+
+	useEffect(() => {
+		if (isStreaming) {
+			onStreamStart()
+		} else {
+			onStreamEnd()
+		}
+	}, [isStreaming])
+
+	return (
+		<div ref={ref} className="w-full max-w-2xl flex justify-start font-serif text-lg scroll-mb-34">
+			<Streamdown
+				animated={{ animation: "slideUp" }}
+				isAnimating={isStreaming}
+				linkSafety={{ enabled: false }}
+				components={{
+					// @ts-expect-error
+					a: ({ className, ...props }) => <a className={`underline ${className}`} {...props} />,
+				}}
+			>
+				{currentContent}
+			</Streamdown>
+		</div>
+	)
+}
+
+function isValidEmail(value: string): boolean {
+	return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+}

apps/waitlist-website/app/routes/privacy-policy.tsx

@@ -0,0 +1,246 @@
+import { Link } from "react-router"
+import { Streamdown } from "streamdown"
+
+import { AnimatedLogo, AnimatedLogoState } from "~/components/animated-logo"
+
+import type { Route } from "./+types/privacy-policy"
+
+export function meta({}: Route.MetaArgs) {
+	return [
+		{ title: "Privacy Policy — Aelis" },
+		{ name: "description", content: "Aelis privacy policy" },
+	]
+}
+
+export default function PrivacyPolicy() {
+	return (
+		<main className="relative max-w-2xl mx-auto px-6 py-16">
+			<Link to="/" className="block w-fit mb-8">
+				<AnimatedLogo className="size-10 pointer-events-none" state={AnimatedLogoState.Idle} />
+			</Link>
+			<Streamdown
+				isAnimating={false}
+				linkSafety={{ enabled: false }}
+				components={{
+					a: ({ className, ...props }) => <a className={`underline ${className}`} {...props} />,
+				}}
+			>
+				{POLICY}
+			</Streamdown>
+			<footer className="mt-16 pt-8 border-t border-stone-200 dark:border-stone-700">
+				<Link to="/" className="text-sm opacity-50 hover:opacity-75 underline">
+					Back to home
+				</Link>
+			</footer>
+		</main>
+	)
+}
+
+const POLICY = `# Privacy Policy
+
+**Last updated:** March 5, 2026
+
+This Privacy Policy describes how **Aelis** ("we", "us", or "our") collects, uses, and protects your personal information when you visit **https://ael.is** or interact with our services.
+
+If you do not agree with this Privacy Policy, please do not use the website.
+
+For any questions, contact: **[kenneth@nym.sh](mailto:kenneth@nym.sh)**
+
+---
+
+## 1. Information We Collect
+
+### Personal Information You Provide
+
+**In Short:** We collect personal information that you provide to us.
+
+We collect personal information that you voluntarily provide when you express interest in our services, contact us, or sign up for the waitlist.
+
+We collect your email address when you sign up for the waitlist so we can notify you when the product launches or provide related updates.
+
+### Personal Information Provided by You
+
+The personal information we collect may include:
+
+* email addresses
+
+You are responsible for ensuring the personal information you provide is accurate and up to date.
+
+### Sensitive Information
+
+We **do not collect or process sensitive personal information**.
+
+### Information From Third Parties
+
+We **do not collect personal information from third parties**.
+
+---
+
+## 2. How We Use Your Information
+
+We process your information for the following purposes:
+
+* To operate and maintain our services
+* To communicate with you about product updates and launch announcements
+* To send administrative information such as policy updates
+* To prevent fraud or abuse
+* To comply with legal obligations
+* To protect someone’s safety when necessary
+
+We only process personal information when we have a valid legal reason to do so.
+
+---
+
+## 3. Legal Bases for Processing (EU / UK)
+
+If you are located in the European Economic Area (EEA) or the United Kingdom, we rely on the following legal bases to process personal information:
+
+### Consent
+
+You have given permission for us to process your personal information for a specific purpose.
+
+### Contract
+
+Processing is necessary to provide services you requested.
+
+### Legal Obligations
+
+Processing is required to comply with applicable laws.
+
+### Vital Interests
+
+Processing is necessary to protect someone's safety.
+
+You may withdraw consent at any time by contacting us.
+
+---
+
+## 4. When and With Whom We Share Personal Information
+
+We may share your personal information in limited situations.
+
+### Service Providers
+
+We may share information with trusted service providers that help us operate our website or manage communications.
+
+### Business Transfers
+
+We may transfer information during negotiations of a merger, sale of assets, financing, or acquisition of our business.
+
+We **do not sell your personal information**.
+
+---
+
+## 5. How Long We Keep Your Information
+
+We retain personal information only as long as necessary to:
+
+* provide services
+* comply with legal obligations
+* resolve disputes
+* enforce agreements
+
+When we no longer need personal information, we delete or anonymize it where possible.
+
+---
+
+## 6. How We Keep Your Information Safe
+
+We implement reasonable technical and organizational safeguards designed to protect personal information.
+
+However, no electronic transmission or storage system is completely secure. We cannot guarantee absolute security.
+
+---
+
+## 7. Information From Minors
+
+Our services are **not intended for individuals under 18 years old**.
+
+We do not knowingly collect personal information from children. If we discover that we have collected such information, we will delete it.
+
+If you believe a child has provided personal information, contact **[kenneth@nym.sh](mailto:kenneth@nym.sh)**.
+
+---
+
+## 8. Your Privacy Rights
+
+Depending on your location, you may have rights regarding your personal information, including:
+
+* the right to access your data
+* the right to correct inaccurate data
+* the right to delete your data
+* the right to restrict processing
+* the right to data portability
+* the right to object to processing
+* the right to withdraw consent
+
+To exercise these rights, submit a request:
+
+https://app.termly.io/dsar/b8633d03-406f-4133-b16e-ded63e893997
+
+Or contact us at **[kenneth@nym.sh](mailto:kenneth@nym.sh)**.
+
+---
+
+## 9. Do Not Track (DNT)
+
+Many browsers include a **Do Not Track (DNT)** feature.
+
+Because there is currently no consistent standard for responding to DNT signals, we do not respond to them.
+
+---
+
+## 10. Global Privacy Control
+
+We recognize **Global Privacy Control (GPC)** signals.
+
+If your browser sends a GPC signal, we treat it as a request to opt out of the sale or sharing of personal information where applicable.
+
+More information: https://globalprivacycontrol.org
+
+---
+
+## 11. Privacy Rights in Other Regions
+
+Additional privacy rights may apply depending on your location, including:
+
+* European Economic Area (EEA)
+* United Kingdom
+* Switzerland
+* Canada
+* United States
+* Australia
+* New Zealand
+
+If you believe we are processing your personal information unlawfully, you may contact your local data protection authority.
+
+---
+
+## 12. Updates to This Privacy Policy
+
+We may update this Privacy Policy from time to time.
+
+When we do, we will update the **Last updated** date at the top of this document.
+
+We encourage users to review this Privacy Policy regularly.
+
+---
+
+## 13. Contact Information
+
+If you have questions or comments about this Privacy Policy, you may contact us:
+
+**Aelis**
+
+Email: **[kenneth@nym.sh](mailto:kenneth@nym.sh)**
+
+---
+
+## 14. Request Access, Update, or Deletion
+
+Depending on applicable law, you may request access to, correction of, or deletion of your personal information.
+
+Email:
+
+**[kenneth@nym.sh](mailto:kenneth@nym.sh)**
+`

apps/waitlist-website/fly.toml

@@ -0,0 +1,22 @@
+# fly.toml app configuration file generated for aelis-waitlist-website on 2026-03-08T01:11:12Z
+#
+# See https://fly.io/docs/reference/configuration/ for information about how to use this file.
+#
+
+app = 'aelis-waitlist-website'
+primary_region = 'lhr'
+
+[build]
+
+[http_service]
+  internal_port = 3000
+  force_https = true
+  auto_stop_machines = 'stop'
+  auto_start_machines = true
+  min_machines_running = 0
+  processes = ['app']
+
+[[vm]]
+  memory = '1gb'
+  cpus = 1
+  memory_mb = 1024

apps/waitlist-website/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "waitlist-website",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "react-router build",
+		"dev": "react-router dev",
+		"start": "react-router-serve ./build/server/index.js",
+		"typecheck": "react-router typegen && tsc"
+	},
+	"dependencies": {
+		"@react-router/node": "7.12.0",
+		"@react-router/serve": "7.12.0",
+		"clsx": "^2.1.1",
+		"isbot": "^5.1.31",
+		"lottie-react": "^2.4.1",
+		"lucide-react": "^0.577.0",
+		"motion": "^12.35.0",
+		"react": "^19.2.4",
+		"react-aria-components": "^1.16.0",
+		"react-dom": "^19.2.4",
+		"react-router": "7.12.0",
+		"resend": "^6.9.3",
+		"streamdown": "^2.4.0"
+	},
+	"devDependencies": {
+		"@react-router/dev": "7.12.0",
+		"@tailwindcss/vite": "^4.1.13",
+		"@types/node": "^22",
+		"@types/react": "^19.2.7",
+		"@types/react-dom": "^19.2.3",
+		"tailwindcss": "^4.1.13",
+		"typescript": "^5.9.2",
+		"vite": "^7.1.7",
+		"vite-tsconfig-paths": "^5.1.4"
+	}
+}

apps/waitlist-website/public/favicon-dark.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg width="100%" height="100%" viewBox="0 0 1667 1667" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:1.5;"><rect id="dark" x="0" y="0" width="1666.67" height="1666.67" style="fill:none;"/><path d="M943.75,642.086c318.648,183.972 527.874,419.028 466.934,524.581c-60.941,105.552 -369.119,41.885 -687.767,-142.086c-318.649,-183.972 -527.875,-419.029 -466.934,-524.581c60.941,-105.552 369.119,-41.886 687.767,142.086Z" style="fill:none;stroke:#e7e5e4;stroke-width:62.5px;"/><path d="M722.917,642.086c318.648,-183.972 626.826,-247.638 687.767,-142.086c60.94,105.552 -148.286,340.609 -466.934,524.581c-318.648,183.971 -626.826,247.638 -687.767,142.086c-60.941,-105.553 148.285,-340.609 466.934,-524.581Z" style="fill:none;stroke:#e7e5e4;stroke-width:62.5px;"/></svg>

apps/waitlist-website/public/favicon-light.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg width="100%" height="100%" viewBox="0 0 1667 1667" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:1.5;"><rect id="light" x="0" y="0" width="1666.67" height="1666.67" style="fill:none;"/><g id="light1" serif:id="light"><path d="M943.75,642.086c318.648,183.972 527.874,419.028 466.934,524.581c-60.941,105.552 -369.119,41.885 -687.767,-142.086c-318.649,-183.972 -527.875,-419.029 -466.934,-524.581c60.941,-105.552 369.119,-41.886 687.767,142.086Z" style="fill:none;stroke:#1c1917;stroke-width:62.5px;"/><path d="M722.917,642.086c318.648,-183.972 626.826,-247.638 687.767,-142.086c60.94,105.552 -148.286,340.609 -466.934,524.581c-318.648,183.971 -626.826,247.638 -687.767,142.086c-60.941,-105.553 148.285,-340.609 466.934,-524.581Z" style="fill:none;stroke:#1c1917;stroke-width:62.5px;"/></g></svg>

apps/waitlist-website/public/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://ael.is/sitemap.xml

apps/waitlist-website/public/sitemap.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+	<url>
+		<loc>https://ael.is/</loc>
+	</url>
+	<url>
+		<loc>https://ael.is/privacy</loc>
+	</url>
+</urlset>

apps/waitlist-website/react-router.config.ts

@@ -0,0 +1,7 @@
+import type { Config } from "@react-router/dev/config"
+
+export default {
+	// Config options...
+	// Server-side render by default, to enable SPA mode set this to `false`
+	ssr: true,
+} satisfies Config

apps/waitlist-website/tsconfig.json

@@ -0,0 +1,22 @@
+{
+	"include": ["**/*", "**/.server/**/*", "**/.client/**/*", ".react-router/types/**/*"],
+	"compilerOptions": {
+		"lib": ["DOM", "DOM.Iterable", "ES2022"],
+		"types": ["node", "vite/client"],
+		"target": "ES2022",
+		"module": "ES2022",
+		"moduleResolution": "bundler",
+		"jsx": "react-jsx",
+		"rootDirs": [".", "./.react-router/types"],
+		"baseUrl": ".",
+		"paths": {
+			"~/*": ["./app/*"]
+		},
+		"esModuleInterop": true,
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"strict": true
+	}
+}

apps/waitlist-website/vite.config.ts

@@ -0,0 +1,11 @@
+import { reactRouter } from "@react-router/dev/vite"
+import tailwindcss from "@tailwindcss/vite"
+import { defineConfig } from "vite"
+import tsconfigPaths from "vite-tsconfig-paths"
+
+export default defineConfig({
+	plugins: [tailwindcss(), reactRouter(), tsconfigPaths()],
+	ssr: {
+		noExternal: ["lottie-react"],
+	},
+})

packages/aris-core/src/context-bridge.ts

@@ -1,8 +1,10 @@
-import type { Context } from "./context"
+import type { ContextEntry } from "./context"
 import type { ContextProvider } from "./context-provider"
 
+import { contextKey } from "./context"
+
 interface ContextUpdatable {
-	pushContextUpdate(update: Partial<Context>): void
+	pushContextUpdate(entries: readonly ContextEntry[]): void
 }
 
 export interface ProviderError {
@@ -54,7 +56,7 @@ export class ContextBridge {
 		this.providers.set(provider.key, provider as ContextProvider)
 
 		const cleanup = provider.onUpdate((value) => {
-			this.controller.pushContextUpdate({ [provider.key]: value })
+			this.controller.pushContextUpdate([[contextKey(provider.key), value]])
 		})
 		this.cleanups.push(cleanup)
 
@@ -67,7 +69,7 @@ export class ContextBridge {
 	 * Returns errors from providers that failed to fetch.
 	 */
 	async refresh(): Promise<RefreshResult> {
-		const updates: Partial<Context> = {}
+		const collected: ContextEntry[] = []
 		const errors: ProviderError[] = []
 
 		const entries = Array.from(this.providers.entries())
@@ -78,7 +80,7 @@ export class ContextBridge {
 		entries.forEach(([key], i) => {
 			const result = results[i]
 			if (result?.status === "fulfilled") {
-				updates[key] = result.value
+				collected.push([contextKey(key), result.value])
 			} else if (result?.status === "rejected") {
 				errors.push({
 					key,
@@ -87,7 +89,7 @@ export class ContextBridge {
 			}
 		})
 
-		this.controller.pushContextUpdate(updates)
+		this.controller.pushContextUpdate(collected)
 
 		return { errors }
 	}

packages/aris-core/src/context.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, test } from "bun:test"
+
+import type { ContextKey } from "./context"
+
+import { Context, contextKey } from "./context"
+
+interface Weather {
+	temperature: number
+}
+
+interface NextEvent {
+	title: string
+}
+
+const WeatherKey: ContextKey<Weather> = contextKey("aris.weather", "current")
+const NextEventKey: ContextKey<NextEvent> = contextKey("aris.google-calendar", "nextEvent")
+
+describe("Context", () => {
+	describe("get", () => {
+		test("returns undefined for missing key", () => {
+			const ctx = new Context()
+			expect(ctx.get(WeatherKey)).toBeUndefined()
+		})
+
+		test("returns value for exact key match", () => {
+			const ctx = new Context()
+			const weather: Weather = { temperature: 20 }
+			ctx.set([[WeatherKey, weather]])
+
+			expect(ctx.get(WeatherKey)).toEqual(weather)
+		})
+
+		test("distinguishes keys with different parts", () => {
+			const ctx = new Context()
+			ctx.set([
+				[WeatherKey, { temperature: 20 }],
+				[NextEventKey, { title: "Standup" }],
+			])
+
+			expect(ctx.get(WeatherKey)).toEqual({ temperature: 20 })
+			expect(ctx.get(NextEventKey)).toEqual({ title: "Standup" })
+		})
+
+		test("last write wins for same key", () => {
+			const ctx = new Context()
+			ctx.set([[WeatherKey, { temperature: 20 }]])
+			ctx.set([[WeatherKey, { temperature: 25 }]])
+
+			expect(ctx.get(WeatherKey)).toEqual({ temperature: 25 })
+		})
+	})
+
+	describe("find", () => {
+		test("returns empty array when no keys match", () => {
+			const ctx = new Context()
+			expect(ctx.find(WeatherKey)).toEqual([])
+		})
+
+		test("returns exact match as single result", () => {
+			const ctx = new Context()
+			ctx.set([[NextEventKey, { title: "Standup" }]])
+
+			const results = ctx.find(NextEventKey)
+			expect(results).toHaveLength(1)
+			expect(results[0]!.value).toEqual({ title: "Standup" })
+		})
+
+		test("prefix match returns multiple instances", () => {
+			const workKey = contextKey<NextEvent>("aris.google-calendar", "nextEvent", {
+				account: "work",
+			})
+			const personalKey = contextKey<NextEvent>("aris.google-calendar", "nextEvent", {
+				account: "personal",
+			})
+
+			const ctx = new Context()
+			ctx.set([
+				[workKey, { title: "Sprint Planning" }],
+				[personalKey, { title: "Dentist" }],
+			])
+
+			const prefix = contextKey<NextEvent>("aris.google-calendar", "nextEvent")
+			const results = ctx.find(prefix)
+
+			expect(results).toHaveLength(2)
+			const titles = results.map((r) => r.value.title).sort()
+			expect(titles).toEqual(["Dentist", "Sprint Planning"])
+		})
+
+		test("prefix match includes exact match and longer keys", () => {
+			const baseKey = contextKey<NextEvent>("aris.google-calendar", "nextEvent")
+			const instanceKey = contextKey<NextEvent>("aris.google-calendar", "nextEvent", {
+				account: "work",
+			})
+
+			const ctx = new Context()
+			ctx.set([
+				[baseKey, { title: "Base" }],
+				[instanceKey, { title: "Instance" }],
+			])
+
+			const results = ctx.find(baseKey)
+			expect(results).toHaveLength(2)
+		})
+
+		test("does not match keys that share a string prefix but differ at segment boundary", () => {
+			const keyA = contextKey<string>("aris.calendar", "next")
+			const keyB = contextKey<string>("aris.calendar", "nextEvent")
+
+			const ctx = new Context()
+			ctx.set([
+				[keyA, "a"],
+				[keyB, "b"],
+			])
+
+			const results = ctx.find(keyA)
+			expect(results).toHaveLength(1)
+			expect(results[0]!.value).toBe("a")
+		})
+
+		test("object key parts with different property order match", () => {
+			const key1 = contextKey<string>("source", "ctx", { b: 2, a: 1 })
+			const key2 = contextKey<string>("source", "ctx", { a: 1, b: 2 })
+
+			const ctx = new Context()
+			ctx.set([[key1, "value"]])
+
+			// Exact match via get should work regardless of property order
+			expect(ctx.get(key2)).toBe("value")
+
+			// find with the reordered key as prefix should also match
+			const prefix = contextKey<string>("source", "ctx")
+			const results = ctx.find(prefix)
+			expect(results).toHaveLength(1)
+		})
+
+		test("single-segment prefix matches all keys starting with that segment", () => {
+			const ctx = new Context()
+			ctx.set([
+				[contextKey("aris.weather", "current"), { temperature: 20 }],
+				[contextKey("aris.weather", "forecast"), { high: 25 }],
+				[contextKey("aris.calendar", "nextEvent"), { title: "Meeting" }],
+			])
+
+			const results = ctx.find(contextKey("aris.weather"))
+			expect(results).toHaveLength(2)
+		})
+
+		test("does not match shorter keys", () => {
+			const ctx = new Context()
+			ctx.set([[contextKey("aris.weather"), "short"]])
+
+			const results = ctx.find(contextKey("aris.weather", "current"))
+			expect(results).toHaveLength(0)
+		})
+
+		test("numeric key parts match correctly", () => {
+			const ctx = new Context()
+			ctx.set([
+				[contextKey("source", 1, "data"), "one"],
+				[contextKey("source", 2, "data"), "two"],
+			])
+
+			const results = ctx.find(contextKey("source", 1))
+			expect(results).toHaveLength(1)
+			expect(results[0]!.value).toBe("one")
+		})
+	})
+
+	describe("size", () => {
+		test("returns 0 for empty context", () => {
+			expect(new Context().size).toBe(0)
+		})
+
+		test("reflects number of entries", () => {
+			const ctx = new Context()
+			ctx.set([
+				[WeatherKey, { temperature: 20 }],
+				[NextEventKey, { title: "Standup" }],
+			])
+			expect(ctx.size).toBe(2)
+		})
+	})
+})

packages/aris-core/src/context.ts

@@ -1,46 +1,128 @@
 /**
- * Branded type for type-safe context keys.
+ * Tuple-keyed context system inspired by React Query's query keys.
  *
- * Each package defines its own keys with associated value types:
- * ```ts
- * const LocationKey: ContextKey<Location> = contextKey("location")
- * ```
+ * Context keys are arrays that form a hierarchy. Sources write to specific
+ * keys (e.g., ["aris.google-calendar", "nextEvent", { account: "work" }])
+ * and consumers can query by exact match or prefix match to get all values
+ * of a given type across source instances.
  */
-export type ContextKey<T> = string & { __contextValue?: T }
 
-/**
- * Creates a typed context key.
- *
- * @example
- * ```ts
- * interface Location { lat: number; lng: number; accuracy: number }
- * const LocationKey: ContextKey<Location> = contextKey("location")
- * ```
- */
-export function contextKey<T>(key: string): ContextKey<T> {
-	return key as ContextKey<T>
+// -- Key types --
+
+/** A single segment of a context key: string, number, or a record of primitives. */
+export type ContextKeyPart = string | number | Record<string, unknown>
+
+/** A context key is a readonly tuple of parts, branded with the value type. */
+export type ContextKey<T> = readonly ContextKeyPart[] & { __contextValue?: T }
+
+/** Creates a typed context key. */
+export function contextKey<T>(...parts: ContextKeyPart[]): ContextKey<T> {
+	return parts as ContextKey<T>
 }
 
-/**
- * Type-safe accessor for context values.
- *
- * @example
- * ```ts
- * const location = contextValue(context, LocationKey)
- * if (location) {
- *   console.log(location.lat, location.lng)
- * }
- * ```
- */
-export function contextValue<T>(context: Context, key: ContextKey<T>): T | undefined {
-	return context[key] as T | undefined
-}
+// -- Serialization --
 
 /**
- * Arbitrary key-value bag representing the current state.
- * Always includes `time`. Other keys are added by context providers.
+ * Deterministic serialization of a context key for use as a Map key.
+ * Object parts have their keys sorted for stable comparison.
  */
-export interface Context {
+export function serializeKey(key: readonly ContextKeyPart[]): string {
+	return JSON.stringify(key, (_key, value) => {
+		if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+			const sorted: Record<string, unknown> = {}
+			for (const k of Object.keys(value).sort()) {
+				sorted[k] = value[k]
+			}
+			return sorted
+		}
+		return value
+	})
+}
+
+// -- Key matching --
+
+/** Returns true if `key` starts with all parts of `prefix`. */
+function keyStartsWith(key: readonly ContextKeyPart[], prefix: readonly ContextKeyPart[]): boolean {
+	if (key.length < prefix.length) return false
+
+	for (let i = 0; i < prefix.length; i++) {
+		if (!partsEqual(key[i]!, prefix[i]!)) return false
+	}
+
+	return true
+}
+
+/** Recursive structural equality, matching React Query's partialMatchKey approach. */
+function partsEqual(a: unknown, b: unknown): boolean {
+	if (a === b) return true
+	if (typeof a !== typeof b) return false
+	if (a && b && typeof a === "object" && typeof b === "object") {
+		const aKeys = Object.keys(a)
+		const bKeys = Object.keys(b)
+		if (aKeys.length !== bKeys.length) return false
+		return aKeys.every((key) =>
+			partsEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]),
+		)
+	}
+	return false
+}
+
+// -- Context store --
+
+/** A single context entry: a key-value pair. */
+export type ContextEntry<T = unknown> = readonly [ContextKey<T>, T]
+
+/**
+ * Mutable context store with tuple keys.
+ *
+ * Supports exact-match lookups and prefix-match queries.
+ * Sources write context in topological order during refresh.
+ */
+export class Context {
 	time: Date
-	[key: string]: unknown
+	private readonly store: Map<string, { key: readonly ContextKeyPart[]; value: unknown }>
+
+	constructor(time: Date = new Date()) {
+		this.time = time
+		this.store = new Map()
+	}
+
+	/** Merges entries into this context. */
+	set(entries: readonly ContextEntry[]): void {
+		for (const [key, value] of entries) {
+			this.store.set(serializeKey(key), { key, value })
+		}
+	}
+
+	/** Exact-match lookup. Returns the value for the given key, or undefined. */
+	get<T>(key: ContextKey<T>): T | undefined {
+		const entry = this.store.get(serializeKey(key))
+		return entry?.value as T | undefined
+	}
+
+	/**
+	 * Prefix-match query. Returns all entries whose key starts with the given prefix.
+	 *
+	 * @example
+	 * ```ts
+	 * // Get all "nextEvent" values across calendar source instances
+	 * const events = context.find(contextKey("nextEvent"))
+	 * ```
+	 */
+	find<T>(prefix: ContextKey<T>): Array<{ key: readonly ContextKeyPart[]; value: T }> {
+		const results: Array<{ key: readonly ContextKeyPart[]; value: T }> = []
+
+		for (const entry of this.store.values()) {
+			if (keyStartsWith(entry.key, prefix)) {
+				results.push({ key: entry.key, value: entry.value as T })
+			}
+		}
+
+		return results
+	}
+
+	/** Returns the number of entries (excluding time). */
+	get size(): number {
+		return this.store.size
+	}
 }

packages/aris-core/src/data-source.ts

@@ -12,7 +12,7 @@ import type { FeedItem } from "./feed"
  *   readonly type = "weather"
  *
  *   async query(context: Context): Promise<WeatherItem[]> {
- *     const location = contextValue(context, LocationKey)
+ *     const location = context.get(LocationKey)
  *     if (!location) return []
  *     const data = await fetchWeather(location)
  *     return [{

packages/aris-core/src/feed-controller.ts

@@ -1,8 +1,9 @@
-import type { Context } from "./context"
+import type { ContextEntry } from "./context"
 import type { DataSource } from "./data-source"
 import type { FeedItem } from "./feed"
 import type { ReconcileResult } from "./reconciler"
 
+import { Context } from "./context"
 import { Reconciler } from "./reconciler"
 
 export interface FeedControllerConfig {
@@ -40,7 +41,7 @@ const DEFAULT_DEBOUNCE_MS = 100
  * })
  *
  * // Context update triggers debounced reconcile
- * controller.pushContextUpdate({ [LocationKey]: location })
+ * controller.pushContextUpdate([[LocationKey, location]])
  *
  * // Direct reconcile (no debounce)
  * const result = await controller.reconcile()
@@ -59,7 +60,7 @@ export class FeedController<TItems extends FeedItem = never> {
 	private stopped = false
 
 	constructor(config?: FeedControllerConfig) {
-		this.context = config?.initialContext ?? { time: new Date() }
+		this.context = config?.initialContext ?? new Context()
 		this.debounceMs = config?.debounceMs ?? DEFAULT_DEBOUNCE_MS
 		this.timeout = config?.timeout
 	}
@@ -94,9 +95,10 @@ export class FeedController<TItems extends FeedItem = never> {
 		}
 	}
 
-	/** Merges update into context and schedules a debounced reconcile. */
-	pushContextUpdate(update: Partial<Context>): void {
-		this.context = { ...this.context, ...update, time: new Date() }
+	/** Merges entries into context and schedules a debounced reconcile. */
+	pushContextUpdate(entries: readonly ContextEntry[]): void {
+		this.context.time = new Date()
+		this.context.set(entries)
 		this.scheduleReconcile()
 	}
 

packages/aris-core/src/feed-engine.test.ts

@@ -1,9 +1,9 @@
 import { describe, expect, test } from "bun:test"
 
-import type { ActionDefinition, Context, ContextKey, FeedItem, FeedSource } from "./index"
+import type { ActionDefinition, ContextEntry, ContextKey, FeedItem, FeedSource } from "./index"
 
 import { FeedEngine } from "./feed-engine"
-import { TimeRelevance, UnknownActionError, contextKey, contextValue } from "./index"
+import { Context, TimeRelevance, UnknownActionError, contextKey } from "./index"
 
 // No-op action methods for test sources
 const noActions = {
@@ -48,7 +48,7 @@ interface SimulatedLocationSource extends FeedSource {
 }
 
 function createLocationSource(): SimulatedLocationSource {
-	let callback: ((update: Partial<Context>) => void) | null = null
+	let callback: ((entries: readonly ContextEntry[]) => void) | null = null
 	let currentLocation: Location = { lat: 0, lng: 0 }
 
 	return {
@@ -63,12 +63,12 @@ function createLocationSource(): SimulatedLocationSource {
 		},
 
 		async fetchContext() {
-			return { [LocationKey]: currentLocation }
+			return [[LocationKey, currentLocation]]
 		},
 
 		simulateUpdate(location: Location) {
 			currentLocation = location
-			callback?.({ [LocationKey]: location })
+			callback?.([[LocationKey, location]])
 		},
 	}
 }
@@ -85,15 +85,15 @@ function createWeatherSource(
 		...noActions,
 
 		async fetchContext(context) {
-			const location = contextValue(context, LocationKey)
+			const location = context.get(LocationKey)
 			if (!location) return null
 
 			const weather = await fetchWeather(location)
-			return { [WeatherKey]: weather }
+			return [[WeatherKey, weather]]
 		},
 
 		async fetchItems(context) {
-			const weather = contextValue(context, WeatherKey)
+			const weather = context.get(WeatherKey)
 			if (!weather) return []
 
 			return [
@@ -123,7 +123,7 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
 		},
 
 		async fetchItems(context) {
-			const weather = contextValue(context, WeatherKey)
+			const weather = context.get(WeatherKey)
 			if (!weather) return []
 
 			if (weather.condition === "storm") {
@@ -265,7 +265,7 @@ describe("FeedEngine", () => {
 				...noActions,
 				async fetchContext() {
 					order.push("location")
-					return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
+					return [[LocationKey, { lat: 51.5, lng: -0.1 }]]
 				},
 			}
 
@@ -275,9 +275,9 @@ describe("FeedEngine", () => {
 				...noActions,
 				async fetchContext(ctx) {
 					order.push("weather")
-					const loc = contextValue(ctx, LocationKey)
+					const loc = ctx.get(LocationKey)
 					expect(loc).toBeDefined()
-					return { [WeatherKey]: { temperature: 20, condition: "sunny" } }
+					return [[WeatherKey, { temperature: 20, condition: "sunny" }]]
 				},
 			}
 
@@ -298,11 +298,11 @@ describe("FeedEngine", () => {
 
 			const { context } = await engine.refresh()
 
-			expect(contextValue(context, LocationKey)).toEqual({
+			expect(context.get(LocationKey)).toEqual({
 				lat: 51.5,
 				lng: -0.1,
 			})
-			expect(contextValue(context, WeatherKey)).toEqual({
+			expect(context.get(WeatherKey)).toEqual({
 				temperature: 20,
 				condition: "sunny",
 			})
@@ -361,7 +361,7 @@ describe("FeedEngine", () => {
 
 			const { context, items } = await engine.refresh()
 
-			expect(contextValue(context, WeatherKey)).toBeUndefined()
+			expect(context.get(WeatherKey)).toBeUndefined()
 			expect(items).toHaveLength(0)
 		})
 
@@ -459,7 +459,7 @@ describe("FeedEngine", () => {
 			await engine.refresh()
 
 			const context = engine.currentContext()
-			expect(contextValue(context, LocationKey)).toEqual({
+			expect(context.get(LocationKey)).toEqual({
 				lat: 51.5,
 				lng: -0.1,
 			})
@@ -734,7 +734,7 @@ describe("FeedEngine", () => {
 		})
 
 		test("reactive item update refreshes cache", async () => {
-			let itemUpdateCallback: (() => void) | null = null
+			let itemUpdateCallback: ((items: FeedItem[]) => void) | null = null
 
 			const source: FeedSource = {
 				id: "reactive-items",
@@ -765,7 +765,7 @@ describe("FeedEngine", () => {
 			engine.start()
 
 			// Trigger item update
-			itemUpdateCallback!()
+			itemUpdateCallback!([])
 
 			// Wait for async refresh
 			await new Promise((resolve) => setTimeout(resolve, 50))
@@ -885,12 +885,12 @@ describe("FeedEngine", () => {
 				...noActions,
 				async fetchContext(ctx) {
 					fetchCount++
-					const loc = contextValue(ctx, LocationKey)
+					const loc = ctx.get(LocationKey)
 					if (!loc) return null
-					return { [WeatherKey]: { temperature: 20, condition: "sunny" } }
+					return [[WeatherKey, { temperature: 20, condition: "sunny" }]]
 				},
 				async fetchItems(ctx) {
-					const weather = contextValue(ctx, WeatherKey)
+					const weather = ctx.get(WeatherKey)
 					if (!weather) return []
 					return [
 						{

packages/aris-core/src/feed-engine.ts

@@ -1,8 +1,11 @@
 import type { ActionDefinition } from "./action"
-import type { Context } from "./context"
+import type { ContextEntry } from "./context"
 import type { FeedItem } from "./feed"
+import type { FeedPostProcessor, ItemGroup } from "./feed-post-processor"
 import type { FeedSource } from "./feed-source"
 
+import { Context } from "./context"
+
 export interface SourceError {
 	sourceId: string
 	error: Error
@@ -12,6 +15,8 @@ export interface FeedResult<TItem extends FeedItem = FeedItem> {
 	context: Context
 	items: TItem[]
 	errors: SourceError[]
+	/** Item groups produced by post-processors */
+	groupedItems?: ItemGroup[]
 }
 
 export type FeedSubscriber<TItem extends FeedItem = FeedItem> = (result: FeedResult<TItem>) => void
@@ -62,10 +67,11 @@ interface SourceGraph {
 export class FeedEngine<TItems extends FeedItem = FeedItem> {
 	private sources = new Map<string, FeedSource>()
 	private graph: SourceGraph | null = null
-	private context: Context = { time: new Date() }
+	private context: Context = new Context()
 	private subscribers = new Set<FeedSubscriber<TItems>>()
 	private cleanups: Array<() => void> = []
 	private started = false
+	private postProcessors: FeedPostProcessor[] = []
 
 	private readonly cacheTtlMs: number
 	private cachedResult: FeedResult<TItems> | null = null
@@ -108,6 +114,23 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 		return this
 	}
 
+	/**
+	 * Registers a post-processor. Processors run in registration order
+	 * after items are collected, on every update path.
+	 */
+	registerPostProcessor(processor: FeedPostProcessor): this {
+		this.postProcessors.push(processor)
+		return this
+	}
+
+	/**
+	 * Unregisters a post-processor by reference.
+	 */
+	unregisterPostProcessor(processor: FeedPostProcessor): this {
+		this.postProcessors = this.postProcessors.filter((p) => p !== processor)
+		return this
+	}
+
 	/**
 	 * Refreshes the feed by running all sources in dependency order.
 	 * Calls fetchContext() then fetchItems() on each source.
@@ -117,14 +140,14 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 		const errors: SourceError[] = []
 
 		// Reset context with fresh time
-		let context: Context = { time: new Date() }
+		const context = new Context()
 
 		// Run fetchContext in topological order
 		for (const source of graph.sorted) {
 			try {
-				const update = await source.fetchContext(context)
-				if (update) {
-					context = { ...context, ...update }
+				const entries = await source.fetchContext(context)
+				if (entries) {
+					context.set(entries)
 				}
 			} catch (err) {
 				errors.push({
@@ -152,7 +175,18 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 
 		this.context = context
 
-		const result: FeedResult<TItems> = { context, items: items as TItems[], errors }
+		const {
+			items: processedItems,
+			groupedItems,
+			errors: postProcessorErrors,
+		} = await this.applyPostProcessors(items as TItems[], context, errors)
+
+		const result: FeedResult<TItems> = {
+			context,
+			items: processedItems,
+			errors: postProcessorErrors,
+			...(groupedItems.length > 0 ? { groupedItems } : {}),
+		}
 		this.updateCache(result)
 
 		return result
@@ -181,8 +215,8 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 		for (const source of graph.sorted) {
 			if (source.onContextUpdate) {
 				const cleanup = source.onContextUpdate(
-					(update) => {
-						this.handleContextUpdate(source.id, update)
+					(entries) => {
+						this.handleContextUpdate(source.id, entries)
 					},
 					() => this.context,
 				)
@@ -260,6 +294,72 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 		return actions
 	}
 
+	private async applyPostProcessors(
+		items: TItems[],
+		context: Context,
+		errors: SourceError[],
+	): Promise<{ items: TItems[]; groupedItems: ItemGroup[]; errors: SourceError[] }> {
+		let currentItems = items
+		const allGroupedItems: ItemGroup[] = []
+		const allErrors = [...errors]
+		const boostScores = new Map<string, number>()
+
+		for (const processor of this.postProcessors) {
+			const snapshot = currentItems
+			try {
+				const enhancement = await processor(currentItems, context)
+
+				if (enhancement.additionalItems?.length) {
+					// Post-processors operate on FeedItem[] without knowledge of TItems.
+					// Additional items are merged untyped — this is intentional. The
+					// processor contract is "FeedItem in, FeedItem out"; type narrowing
+					// is the caller's responsibility when consuming FeedResult.
+					currentItems = [...currentItems, ...(enhancement.additionalItems as TItems[])]
+				}
+
+				if (enhancement.suppress?.length) {
+					const suppressSet = new Set(enhancement.suppress)
+					currentItems = currentItems.filter((item) => !suppressSet.has(item.id))
+				}
+
+				if (enhancement.groupedItems?.length) {
+					allGroupedItems.push(...enhancement.groupedItems)
+				}
+
+				if (enhancement.boost) {
+					for (const [id, score] of Object.entries(enhancement.boost)) {
+						boostScores.set(id, (boostScores.get(id) ?? 0) + score)
+					}
+				}
+			} catch (err) {
+				const sourceId = processor.name || "anonymous"
+				allErrors.push({
+					sourceId,
+					error: err instanceof Error ? err : new Error(String(err)),
+				})
+				currentItems = snapshot
+			}
+		}
+
+		// Apply boost reordering: positive-boost first (desc), then zero, then negative (desc).
+		// Stable sort within each tier preserves original relative order.
+		if (boostScores.size > 0) {
+			currentItems = applyBoostOrder(currentItems, boostScores)
+		}
+
+		// Remove stale item IDs from groups and drop empty groups
+		const itemIds = new Set(currentItems.map((item) => item.id))
+		const validGroups = allGroupedItems.reduce<ItemGroup[]>((acc, group) => {
+			const ids = group.itemIds.filter((id) => itemIds.has(id))
+			if (ids.length > 0) {
+				acc.push({ ...group, itemIds: ids })
+			}
+			return acc
+		}, [])
+
+		return { items: currentItems, groupedItems: validGroups, errors: allErrors }
+	}
+
 	private ensureGraph(): SourceGraph {
 		if (!this.graph) {
 			this.graph = buildGraph(Array.from(this.sources.values()))
@@ -267,8 +367,9 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 		return this.graph
 	}
 
-	private handleContextUpdate(sourceId: string, update: Partial<Context>): void {
-		this.context = { ...this.context, ...update, time: new Date() }
+	private handleContextUpdate(sourceId: string, entries: readonly ContextEntry[]): void {
+		this.context.time = new Date()
+		this.context.set(entries)
 
 		// Re-run dependents and notify
 		this.refreshDependents(sourceId)
@@ -283,9 +384,9 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 			const source = graph.sources.get(id)
 			if (source) {
 				try {
-					const update = await source.fetchContext(this.context)
-					if (update) {
-						this.context = { ...this.context, ...update }
+					const entries = await source.fetchContext(this.context)
+					if (entries) {
+						this.context.set(entries)
 					}
 				} catch {
 					// Errors during reactive updates are logged but don't stop propagation
@@ -311,10 +412,17 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 			}
 		}
 
+		const {
+			items: processedItems,
+			groupedItems,
+			errors: postProcessorErrors,
+		} = await this.applyPostProcessors(items as TItems[], this.context, errors)
+
 		const result: FeedResult<TItems> = {
 			context: this.context,
-			items: items as TItems[],
-			errors,
+			items: processedItems,
+			errors: postProcessorErrors,
+			...(groupedItems.length > 0 ? { groupedItems } : {}),
 		}
 		this.updateCache(result)
 
@@ -395,6 +503,47 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 	}
 }
 
+function clamp(value: number, min: number, max: number): number {
+	return Math.min(max, Math.max(min, value))
+}
+
+function applyBoostOrder<T extends FeedItem>(items: T[], boostScores: Map<string, number>): T[] {
+	const positive: T[] = []
+	const neutral: T[] = []
+	const negative: T[] = []
+
+	for (const item of items) {
+		const raw = boostScores.get(item.id)
+		if (raw === undefined || raw === 0) {
+			neutral.push(item)
+		} else {
+			const clamped = clamp(raw, -1, 1)
+			if (clamped > 0) {
+				positive.push(item)
+			} else if (clamped < 0) {
+				negative.push(item)
+			} else {
+				neutral.push(item)
+			}
+		}
+	}
+
+	// Sort positive descending by boost, negative descending (least negative first, most negative last)
+	positive.sort((a, b) => {
+		const aScore = clamp(boostScores.get(a.id) ?? 0, -1, 1)
+		const bScore = clamp(boostScores.get(b.id) ?? 0, -1, 1)
+		return bScore - aScore
+	})
+
+	negative.sort((a, b) => {
+		const aScore = clamp(boostScores.get(a.id) ?? 0, -1, 1)
+		const bScore = clamp(boostScores.get(b.id) ?? 0, -1, 1)
+		return bScore - aScore
+	})
+
+	return [...positive, ...neutral, ...negative]
+}
+
 function buildGraph(sources: FeedSource[]): SourceGraph {
 	const byId = new Map<string, FeedSource>()
 	for (const source of sources) {

packages/aris-core/src/feed-post-processor.test.ts

@@ -0,0 +1,602 @@
+import { describe, expect, mock, test } from "bun:test"
+
+import type {
+	ActionDefinition,
+	ContextEntry,
+	FeedItem,
+	FeedPostProcessor,
+	FeedSource,
+} from "./index"
+
+import { FeedEngine } from "./feed-engine"
+import { UnknownActionError } from "./index"
+
+// No-op action methods for test sources
+const noActions = {
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {}
+	},
+	async executeAction(actionId: string): Promise<void> {
+		throw new UnknownActionError(actionId)
+	},
+}
+
+// =============================================================================
+// FEED ITEMS
+// =============================================================================
+
+type WeatherItem = FeedItem<"weather", { temp: number }>
+type CalendarItem = FeedItem<"calendar", { title: string }>
+
+function weatherItem(id: string, temp: number): WeatherItem {
+	return { id, type: "weather", timestamp: new Date(), data: { temp } }
+}
+
+function calendarItem(id: string, title: string): CalendarItem {
+	return { id, type: "calendar", timestamp: new Date(), data: { title } }
+}
+
+// =============================================================================
+// TEST SOURCES
+// =============================================================================
+
+function createWeatherSource(items: WeatherItem[]) {
+	return {
+		id: "aris.weather",
+		...noActions,
+		async fetchContext() {
+			return null
+		},
+		async fetchItems(): Promise<WeatherItem[]> {
+			return items
+		},
+	}
+}
+
+function createCalendarSource(items: CalendarItem[]) {
+	return {
+		id: "aris.calendar",
+		...noActions,
+		async fetchContext() {
+			return null
+		},
+		async fetchItems(): Promise<CalendarItem[]> {
+			return items
+		},
+	}
+}
+
+// =============================================================================
+// REGISTRATION
+// =============================================================================
+
+describe("FeedPostProcessor", () => {
+	describe("registration", () => {
+		test("registerPostProcessor is chainable", () => {
+			const engine = new FeedEngine()
+			const processor: FeedPostProcessor = async () => ({})
+			const result = engine.registerPostProcessor(processor)
+			expect(result).toBe(engine)
+		})
+
+		test("unregisterPostProcessor is chainable", () => {
+			const engine = new FeedEngine()
+			const processor: FeedPostProcessor = async () => ({})
+			const result = engine.unregisterPostProcessor(processor)
+			expect(result).toBe(engine)
+		})
+
+		test("unregistered processor does not run", async () => {
+			const processor = mock(async () => ({}))
+
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20)]))
+				.registerPostProcessor(processor)
+				.unregisterPostProcessor(processor)
+
+			await engine.refresh()
+			expect(processor).not.toHaveBeenCalled()
+		})
+	})
+
+	// =============================================================================
+	// ADDITIONAL ITEMS
+	// =============================================================================
+
+	describe("additionalItems", () => {
+		test("injects additional items into the feed", async () => {
+			const extra = calendarItem("c1", "Meeting")
+
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20)]))
+				.registerPostProcessor(async () => ({ additionalItems: [extra] }))
+
+			const result = await engine.refresh()
+			expect(result.items).toHaveLength(2)
+			expect(result.items.find((i) => i.id === "c1")).toBeDefined()
+		})
+	})
+
+	// =============================================================================
+	// SUPPRESS
+	// =============================================================================
+
+	describe("suppress", () => {
+		test("removes suppressed items from the feed", async () => {
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20), weatherItem("w2", 25)]))
+				.registerPostProcessor(async () => ({ suppress: ["w1"] }))
+
+			const result = await engine.refresh()
+			expect(result.items).toHaveLength(1)
+			expect(result.items[0].id).toBe("w2")
+		})
+
+		test("suppressing nonexistent ID is a no-op", async () => {
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20)]))
+				.registerPostProcessor(async () => ({ suppress: ["nonexistent"] }))
+
+			const result = await engine.refresh()
+			expect(result.items).toHaveLength(1)
+		})
+	})
+
+	// =============================================================================
+	// GROUPED ITEMS
+	// =============================================================================
+
+	describe("groupedItems", () => {
+		test("accumulates grouped items on FeedResult", async () => {
+			const engine = new FeedEngine()
+				.register(
+					createCalendarSource([calendarItem("c1", "Meeting A"), calendarItem("c2", "Meeting B")]),
+				)
+				.registerPostProcessor(async () => ({
+					groupedItems: [{ itemIds: ["c1", "c2"], summary: "Busy afternoon" }],
+				}))
+
+			const result = await engine.refresh()
+			expect(result.groupedItems).toEqual([{ itemIds: ["c1", "c2"], summary: "Busy afternoon" }])
+		})
+
+		test("multiple processors accumulate groups", async () => {
+			const engine = new FeedEngine()
+				.register(
+					createCalendarSource([calendarItem("c1", "Meeting A"), calendarItem("c2", "Meeting B")]),
+				)
+				.registerPostProcessor(async () => ({
+					groupedItems: [{ itemIds: ["c1"], summary: "Group A" }],
+				}))
+				.registerPostProcessor(async () => ({
+					groupedItems: [{ itemIds: ["c2"], summary: "Group B" }],
+				}))
+
+			const result = await engine.refresh()
+			expect(result.groupedItems).toEqual([
+				{ itemIds: ["c1"], summary: "Group A" },
+				{ itemIds: ["c2"], summary: "Group B" },
+			])
+		})
+
+		test("stale item IDs are removed from groups after suppression", async () => {
+			const engine = new FeedEngine()
+				.register(
+					createCalendarSource([calendarItem("c1", "Meeting A"), calendarItem("c2", "Meeting B")]),
+				)
+				.registerPostProcessor(async () => ({
+					groupedItems: [{ itemIds: ["c1", "c2"], summary: "Afternoon" }],
+				}))
+				.registerPostProcessor(async () => ({ suppress: ["c1"] }))
+
+			const result = await engine.refresh()
+			expect(result.groupedItems).toEqual([{ itemIds: ["c2"], summary: "Afternoon" }])
+		})
+
+		test("groups with all items suppressed are dropped", async () => {
+			const engine = new FeedEngine()
+				.register(createCalendarSource([calendarItem("c1", "Meeting A")]))
+				.registerPostProcessor(async () => ({
+					groupedItems: [{ itemIds: ["c1"], summary: "Solo" }],
+				}))
+				.registerPostProcessor(async () => ({ suppress: ["c1"] }))
+
+			const result = await engine.refresh()
+			expect(result.groupedItems).toBeUndefined()
+		})
+
+		test("groupedItems is omitted when no processors produce groups", async () => {
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20)]))
+				.registerPostProcessor(async () => ({}))
+
+			const result = await engine.refresh()
+			expect(result.groupedItems).toBeUndefined()
+		})
+	})
+
+	// =============================================================================
+	// BOOST
+	// =============================================================================
+
+	describe("boost", () => {
+		test("positive boost moves item before non-boosted items", async () => {
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20), weatherItem("w2", 25)]))
+				.registerPostProcessor(async () => ({ boost: { w2: 0.8 } }))
+
+			const result = await engine.refresh()
+			expect(result.items.map((i) => i.id)).toEqual(["w2", "w1"])
+		})
+
+		test("negative boost moves item after non-boosted items", async () => {
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20), weatherItem("w2", 25)]))
+				.registerPostProcessor(async () => ({ boost: { w1: -0.5 } }))
+
+			const result = await engine.refresh()
+			expect(result.items.map((i) => i.id)).toEqual(["w2", "w1"])
+		})
+
+		test("multiple boosted items are sorted by boost descending", async () => {
+			const engine = new FeedEngine()
+				.register(
+					createWeatherSource([
+						weatherItem("w1", 20),
+						weatherItem("w2", 25),
+						weatherItem("w3", 30),
+					]),
+				)
+				.registerPostProcessor(async () => ({
+					boost: { w3: 0.3, w1: 0.9 },
+				}))
+
+			const result = await engine.refresh()
+			// w1 (0.9) first, w3 (0.3) second, w2 (no boost) last
+			expect(result.items.map((i) => i.id)).toEqual(["w1", "w3", "w2"])
+		})
+
+		test("multiple processors accumulate boost scores", async () => {
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20), weatherItem("w2", 25)]))
+				.registerPostProcessor(async () => ({ boost: { w1: 0.3 } }))
+				.registerPostProcessor(async () => ({ boost: { w1: 0.4 } }))
+
+			const result = await engine.refresh()
+			// w1 accumulated boost = 0.7, moves before w2
+			expect(result.items.map((i) => i.id)).toEqual(["w1", "w2"])
+		})
+
+		test("accumulated boost is clamped to [-1, 1]", async () => {
+			const engine = new FeedEngine()
+				.register(
+					createWeatherSource([
+						weatherItem("w1", 20),
+						weatherItem("w2", 25),
+						weatherItem("w3", 30),
+					]),
+				)
+				.registerPostProcessor(async () => ({ boost: { w1: 0.8, w2: 0.9 } }))
+				.registerPostProcessor(async () => ({ boost: { w1: 0.8 } }))
+
+			const result = await engine.refresh()
+			// w1 accumulated = 1.6 clamped to 1, w2 = 0.9 — w1 still first
+			expect(result.items.map((i) => i.id)).toEqual(["w1", "w2", "w3"])
+		})
+
+		test("out-of-range boost values are clamped", async () => {
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20), weatherItem("w2", 25)]))
+				.registerPostProcessor(async () => ({ boost: { w1: 5.0 } }))
+
+			const result = await engine.refresh()
+			// Clamped to 1, still boosted to front
+			expect(result.items.map((i) => i.id)).toEqual(["w1", "w2"])
+		})
+
+		test("boosting a suppressed item is a no-op", async () => {
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20), weatherItem("w2", 25)]))
+				.registerPostProcessor(async () => ({
+					suppress: ["w1"],
+					boost: { w1: 1.0 },
+				}))
+
+			const result = await engine.refresh()
+			expect(result.items).toHaveLength(1)
+			expect(result.items[0].id).toBe("w2")
+		})
+
+		test("boosting a nonexistent item ID is a no-op", async () => {
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20)]))
+				.registerPostProcessor(async () => ({ boost: { nonexistent: 1.0 } }))
+
+			const result = await engine.refresh()
+			expect(result.items).toHaveLength(1)
+			expect(result.items[0].id).toBe("w1")
+		})
+
+		test("items with equal boost retain original relative order", async () => {
+			const engine = new FeedEngine()
+				.register(
+					createWeatherSource([
+						weatherItem("w1", 20),
+						weatherItem("w2", 25),
+						weatherItem("w3", 30),
+					]),
+				)
+				.registerPostProcessor(async () => ({
+					boost: { w1: 0.5, w3: 0.5 },
+				}))
+
+			const result = await engine.refresh()
+			// w1 and w3 have equal boost — original order preserved: w1 before w3
+			expect(result.items.map((i) => i.id)).toEqual(["w1", "w3", "w2"])
+		})
+
+		test("negative boosts preserve relative order among demoted items", async () => {
+			const engine = new FeedEngine()
+				.register(
+					createWeatherSource([
+						weatherItem("w1", 20),
+						weatherItem("w2", 25),
+						weatherItem("w3", 30),
+					]),
+				)
+				.registerPostProcessor(async () => ({
+					boost: { w1: -0.3, w2: -0.3 },
+				}))
+
+			const result = await engine.refresh()
+			// w3 (neutral) first, then w1 and w2 (equal negative) in original order
+			expect(result.items.map((i) => i.id)).toEqual(["w3", "w1", "w2"])
+		})
+
+		test("boost works alongside additionalItems and groupedItems", async () => {
+			const extra = calendarItem("c1", "Meeting")
+
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20), weatherItem("w2", 25)]))
+				.registerPostProcessor(async () => ({
+					additionalItems: [extra],
+					boost: { c1: 1.0 },
+					groupedItems: [{ itemIds: ["w1", "c1"], summary: "Related" }],
+				}))
+
+			const result = await engine.refresh()
+			// c1 boosted to front
+			expect(result.items[0].id).toBe("c1")
+			expect(result.items).toHaveLength(3)
+			expect(result.groupedItems).toEqual([{ itemIds: ["w1", "c1"], summary: "Related" }])
+		})
+	})
+
+	// =============================================================================
+	// PIPELINE ORDERING
+	// =============================================================================
+
+	describe("pipeline ordering", () => {
+		test("each processor sees items as modified by the previous processor", async () => {
+			const seen: string[] = []
+
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20)]))
+				.registerPostProcessor(async () => ({
+					additionalItems: [calendarItem("c1", "Injected")],
+				}))
+				.registerPostProcessor(async (items) => {
+					seen.push(...items.map((i) => i.id))
+					return {}
+				})
+
+			await engine.refresh()
+			expect(seen).toEqual(["w1", "c1"])
+		})
+
+		test("suppression in first processor affects second processor", async () => {
+			const seen: string[] = []
+
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20), weatherItem("w2", 25)]))
+				.registerPostProcessor(async () => ({ suppress: ["w1"] }))
+				.registerPostProcessor(async (items) => {
+					seen.push(...items.map((i) => i.id))
+					return {}
+				})
+
+			await engine.refresh()
+			expect(seen).toEqual(["w2"])
+		})
+	})
+
+	// =============================================================================
+	// ERROR HANDLING
+	// =============================================================================
+
+	describe("error handling", () => {
+		test("throwing processor is recorded in errors and pipeline continues", async () => {
+			const seen: string[] = []
+
+			async function failingProcessor(): Promise<never> {
+				throw new Error("processor failed")
+			}
+
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20)]))
+				.registerPostProcessor(failingProcessor)
+				.registerPostProcessor(async (items) => {
+					seen.push(...items.map((i) => i.id))
+					return {}
+				})
+
+			const result = await engine.refresh()
+
+			const ppError = result.errors.find((e) => e.sourceId === "failingProcessor")
+			expect(ppError).toBeDefined()
+			expect(ppError!.error.message).toBe("processor failed")
+
+			// Pipeline continued — observer still saw the original item
+			expect(seen).toEqual(["w1"])
+			expect(result.items).toHaveLength(1)
+		})
+
+		test("anonymous throwing processor uses 'anonymous' as sourceId", async () => {
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20)]))
+				.registerPostProcessor(async () => {
+					throw new Error("anon failed")
+				})
+
+			const result = await engine.refresh()
+			const ppError = result.errors.find((e) => e.sourceId === "anonymous")
+			expect(ppError).toBeDefined()
+		})
+
+		test("non-Error throw is wrapped", async () => {
+			async function failingProcessor(): Promise<never> {
+				throw "string error"
+			}
+
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20)]))
+				.registerPostProcessor(failingProcessor)
+
+			const result = await engine.refresh()
+			const ppError = result.errors.find((e) => e.sourceId === "failingProcessor")
+			expect(ppError).toBeDefined()
+			expect(ppError!.error).toBeInstanceOf(Error)
+		})
+	})
+
+	// =============================================================================
+	// REACTIVE PATHS
+	// =============================================================================
+
+	describe("reactive updates", () => {
+		test("post-processors run during reactive context updates", async () => {
+			let callCount = 0
+
+			let triggerUpdate: ((entries: readonly ContextEntry[]) => void) | null = null
+
+			const source: FeedSource = {
+				id: "aris.reactive",
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+				async fetchItems() {
+					return [weatherItem("w1", 20)]
+				},
+				onContextUpdate(callback, _getContext) {
+					triggerUpdate = callback
+					return () => {
+						triggerUpdate = null
+					}
+				},
+			}
+
+			const engine = new FeedEngine().register(source).registerPostProcessor(async () => {
+				callCount++
+				return {}
+			})
+
+			engine.start()
+
+			// Wait for initial periodic refresh
+			await new Promise((resolve) => setTimeout(resolve, 50))
+			const countAfterStart = callCount
+
+			// Trigger a reactive context update
+			triggerUpdate!([])
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			expect(callCount).toBeGreaterThan(countAfterStart)
+
+			engine.stop()
+		})
+
+		test("post-processors run during reactive item updates", async () => {
+			let callCount = 0
+
+			let triggerItemsUpdate: ((items: FeedItem[]) => void) | null = null
+
+			const source: FeedSource = {
+				id: "aris.reactive",
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+				async fetchItems() {
+					return [weatherItem("w1", 20)]
+				},
+				onItemsUpdate(callback, _getContext) {
+					triggerItemsUpdate = callback
+					return () => {
+						triggerItemsUpdate = null
+					}
+				},
+			}
+
+			const engine = new FeedEngine().register(source).registerPostProcessor(async () => {
+				callCount++
+				return {}
+			})
+
+			engine.start()
+
+			await new Promise((resolve) => setTimeout(resolve, 50))
+			const countAfterStart = callCount
+
+			// Trigger a reactive items update
+			triggerItemsUpdate!([weatherItem("w1", 25)])
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			expect(callCount).toBeGreaterThan(countAfterStart)
+
+			engine.stop()
+		})
+	})
+
+	// =============================================================================
+	// NO PROCESSORS = NO CHANGE
+	// =============================================================================
+
+	describe("no processors", () => {
+		test("engine without post-processors returns raw items unchanged", async () => {
+			const items = [weatherItem("w1", 20), weatherItem("w2", 25)]
+			const engine = new FeedEngine().register(createWeatherSource(items))
+
+			const result = await engine.refresh()
+			expect(result.items).toHaveLength(2)
+			expect(result.items[0].id).toBe("w1")
+			expect(result.items[1].id).toBe("w2")
+			expect(result.groupedItems).toBeUndefined()
+		})
+	})
+
+	// =============================================================================
+	// COMBINED ENHANCEMENT
+	// =============================================================================
+
+	describe("combined enhancement", () => {
+		test("single processor can use all enhancement fields at once", async () => {
+			const engine = new FeedEngine()
+				.register(createWeatherSource([weatherItem("w1", 20), weatherItem("w2", 25)]))
+				.registerPostProcessor(async () => ({
+					additionalItems: [calendarItem("c1", "Injected")],
+					suppress: ["w2"],
+					groupedItems: [{ itemIds: ["w1", "c1"], summary: "Related" }],
+				}))
+
+			const result = await engine.refresh()
+
+			// w2 suppressed, c1 injected → w1 + c1
+			expect(result.items).toHaveLength(2)
+			expect(result.items.map((i) => i.id)).toEqual(["w1", "c1"])
+
+			// Groups on result
+			expect(result.groupedItems).toEqual([{ itemIds: ["w1", "c1"], summary: "Related" }])
+		})
+	})
+})

packages/aris-core/src/feed-post-processor.ts

@@ -0,0 +1,26 @@
+import type { Context } from "./context"
+import type { FeedItem } from "./feed"
+
+export interface ItemGroup {
+	/** IDs of items to present together */
+	itemIds: string[]
+	/** Summary text for the group */
+	summary: string
+}
+
+export interface FeedEnhancement {
+	/** New items to inject into the feed */
+	additionalItems?: FeedItem[]
+	/** Groups of items to present together with a summary */
+	groupedItems?: ItemGroup[]
+	/** Item IDs to remove from the feed */
+	suppress?: string[]
+	/** Map of item ID to boost score (-1 to 1). Positive promotes, negative demotes. */
+	boost?: Record<string, number>
+}
+
+/**
+ * A function that transforms feed items and produces enhancement directives.
+ * Use named functions for meaningful error attribution.
+ */
+export type FeedPostProcessor = (items: FeedItem[], context: Context) => Promise<FeedEnhancement>

packages/aris-core/src/feed-source.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, test } from "bun:test"
 
-import type { ActionDefinition, Context, ContextKey, FeedItem, FeedSource } from "./index"
+import type { ActionDefinition, ContextEntry, ContextKey, FeedItem, FeedSource } from "./index"
 
-import { TimeRelevance, UnknownActionError, contextKey, contextValue } from "./index"
+import { Context, TimeRelevance, UnknownActionError, contextKey } from "./index"
 
 // No-op action methods for test sources
 const noActions = {
@@ -47,7 +47,7 @@ interface SimulatedLocationSource extends FeedSource {
 }
 
 function createLocationSource(): SimulatedLocationSource {
-	let callback: ((update: Partial<Context>) => void) | null = null
+	let callback: ((entries: readonly ContextEntry[]) => void) | null = null
 	let currentLocation: Location = { lat: 0, lng: 0 }
 
 	return {
@@ -62,12 +62,12 @@ function createLocationSource(): SimulatedLocationSource {
 		},
 
 		async fetchContext() {
-			return { [LocationKey]: currentLocation }
+			return [[LocationKey, currentLocation]]
 		},
 
 		simulateUpdate(location: Location) {
 			currentLocation = location
-			callback?.({ [LocationKey]: location })
+			callback?.([[LocationKey, location]])
 		},
 	}
 }
@@ -84,15 +84,15 @@ function createWeatherSource(
 		...noActions,
 
 		async fetchContext(context) {
-			const location = contextValue(context, LocationKey)
+			const location = context.get(LocationKey)
 			if (!location) return null
 
 			const weather = await fetchWeather(location)
-			return { [WeatherKey]: weather }
+			return [[WeatherKey, weather]]
 		},
 
 		async fetchItems(context) {
-			const weather = contextValue(context, WeatherKey)
+			const weather = context.get(WeatherKey)
 			if (!weather) return []
 
 			return [
@@ -122,7 +122,7 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
 		},
 
 		async fetchItems(context) {
-			const weather = contextValue(context, WeatherKey)
+			const weather = context.get(WeatherKey)
 			if (!weather) return []
 
 			if (weather.condition === "storm") {
@@ -207,13 +207,13 @@ function buildGraph(sources: FeedSource[]): SourceGraph {
 }
 
 async function refreshGraph(graph: SourceGraph): Promise<{ context: Context; items: FeedItem[] }> {
-	let context: Context = { time: new Date() }
+	const context = new Context()
 
 	// Run fetchContext in topological order
 	for (const source of graph.sorted) {
-		const update = await source.fetchContext(context)
-		if (update) {
-			context = { ...context, ...update }
+		const entries = await source.fetchContext(context)
+		if (entries) {
+			context.set(entries)
 		}
 	}
 
@@ -265,7 +265,7 @@ describe("FeedSource", () => {
 
 		test("source without context returns null from fetchContext", async () => {
 			const source = createAlertSource()
-			const result = await source.fetchContext({ time: new Date() })
+			const result = await source.fetchContext(new Context())
 			expect(result).toBeNull()
 		})
 	})
@@ -369,7 +369,7 @@ describe("FeedSource", () => {
 				...noActions,
 				async fetchContext() {
 					order.push("location")
-					return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
+					return [[LocationKey, { lat: 51.5, lng: -0.1 }]]
 				},
 			}
 
@@ -379,9 +379,9 @@ describe("FeedSource", () => {
 				...noActions,
 				async fetchContext(ctx) {
 					order.push("weather")
-					const loc = contextValue(ctx, LocationKey)
+					const loc = ctx.get(LocationKey)
 					expect(loc).toBeDefined()
-					return { [WeatherKey]: { temperature: 20, condition: "sunny" } }
+					return [[WeatherKey, { temperature: 20, condition: "sunny" }]]
 				},
 			}
 
@@ -400,11 +400,11 @@ describe("FeedSource", () => {
 			const graph = buildGraph([location, weather])
 			const { context } = await refreshGraph(graph)
 
-			expect(contextValue(context, LocationKey)).toEqual({
+			expect(context.get(LocationKey)).toEqual({
 				lat: 51.5,
 				lng: -0.1,
 			})
-			expect(contextValue(context, WeatherKey)).toEqual({
+			expect(context.get(WeatherKey)).toEqual({
 				temperature: 20,
 				condition: "sunny",
 			})
@@ -447,12 +447,10 @@ describe("FeedSource", () => {
 		})
 
 		test("source without location context returns empty items", async () => {
-			// Location source exists but hasn't been updated
 			const location: FeedSource = {
 				id: "location",
 				...noActions,
 				async fetchContext() {
-					// Simulate no location available
 					return null
 				},
 			}
@@ -462,7 +460,7 @@ describe("FeedSource", () => {
 			const graph = buildGraph([location, weather])
 			const { context, items } = await refreshGraph(graph)
 
-			expect(contextValue(context, WeatherKey)).toBeUndefined()
+			expect(context.get(WeatherKey)).toBeUndefined()
 			expect(items).toHaveLength(0)
 		})
 	})
@@ -476,7 +474,7 @@ describe("FeedSource", () => {
 				() => {
 					updateCount++
 				},
-				() => ({ time: new Date() }),
+				() => new Context(),
 			)
 
 			location.simulateUpdate({ lat: 1, lng: 1 })

packages/aris-core/src/feed-source.ts

@@ -1,5 +1,5 @@
 import type { ActionDefinition } from "./action"
-import type { Context } from "./context"
+import type { Context, ContextEntry } from "./context"
 import type { FeedItem } from "./feed"
 
 /**
@@ -57,7 +57,7 @@ export interface FeedSource<TItem extends FeedItem = FeedItem> {
 	 * Maps to: source/contextUpdated (notification, source → host)
 	 */
 	onContextUpdate?(
-		callback: (update: Partial<Context>) => void,
+		callback: (entries: readonly ContextEntry[]) => void,
 		getContext: () => Context,
 	): () => void
 
@@ -67,7 +67,7 @@ export interface FeedSource<TItem extends FeedItem = FeedItem> {
 	 * Return null if this source cannot provide context.
 	 * Maps to: source/fetchContext
 	 */
-	fetchContext(context: Context): Promise<Partial<Context> | null>
+	fetchContext(context: Context): Promise<readonly ContextEntry[] | null>
 
 	/**
 	 * Subscribe to reactive feed item updates.

packages/aris-core/src/feed.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test"
+
+import type { FeedItem, Slot } from "./feed"
+
+describe("FeedItem slots", () => {
+	test("FeedItem without slots is valid", () => {
+		const item: FeedItem<"test", { value: number }> = {
+			id: "test-1",
+			type: "test",
+			timestamp: new Date(),
+			data: { value: 42 },
+		}
+
+		expect(item.slots).toBeUndefined()
+	})
+
+	test("FeedItem with unfilled slots", () => {
+		const item: FeedItem<"weather", { temp: number }> = {
+			id: "weather-1",
+			type: "weather",
+			timestamp: new Date(),
+			data: { temp: 18 },
+			slots: {
+				insight: {
+					description: "A short contextual insight about the current weather",
+					content: null,
+				},
+				"cross-source": {
+					description: "Connection between weather and calendar events",
+					content: null,
+				},
+			},
+		}
+
+		expect(item.slots).toBeDefined()
+		expect(Object.keys(item.slots!)).toEqual(["insight", "cross-source"])
+		expect(item.slots!.insight!.content).toBeNull()
+		expect(item.slots!["cross-source"]!.content).toBeNull()
+	})
+
+	test("FeedItem with filled slots", () => {
+		const item: FeedItem<"weather", { temp: number }> = {
+			id: "weather-1",
+			type: "weather",
+			timestamp: new Date(),
+			data: { temp: 18 },
+			slots: {
+				insight: {
+					description: "A short contextual insight about the current weather",
+					content: "Rain after 3pm — grab a jacket before your walk",
+				},
+			},
+		}
+
+		expect(item.slots!.insight!.content).toBe("Rain after 3pm — grab a jacket before your walk")
+	})
+
+	test("Slot interface enforces required fields", () => {
+		const slot: Slot = {
+			description: "Test slot description",
+			content: null,
+		}
+
+		expect(slot.description).toBe("Test slot description")
+		expect(slot.content).toBeNull()
+
+		const filledSlot: Slot = {
+			description: "Test slot description",
+			content: "Filled content",
+		}
+
+		expect(filledSlot.content).toBe("Filled content")
+	})
+
+	test("FeedItem with empty slots record", () => {
+		const item: FeedItem<"test", { value: number }> = {
+			id: "test-1",
+			type: "test",
+			timestamp: new Date(),
+			data: { value: 1 },
+			slots: {},
+		}
+
+		expect(item.slots).toEqual({})
+		expect(Object.keys(item.slots!)).toHaveLength(0)
+	})
+})

packages/aris-core/src/feed.ts

@@ -23,6 +23,20 @@ export interface FeedItemSignals {
 	timeRelevance?: TimeRelevance
 }
 
+/**
+ * A named slot for LLM-fillable content on a feed item.
+ *
+ * Sources declare slots with a description that tells the LLM what content
+ * to generate. The enhancement harness fills `content` asynchronously;
+ * until then it remains `null`.
+ */
+export interface Slot {
+	/** Tells the LLM what this slot wants — written by the source */
+	description: string
+	/** LLM-filled text content, null until enhanced */
+	content: string | null
+}
+
 /**
  * A single item in the feed.
  *
@@ -36,6 +50,12 @@ export interface FeedItemSignals {
  *   timestamp: new Date(),
  *   data: { temp: 18, condition: "cloudy" },
  *   signals: { urgency: 0.5, timeRelevance: "ambient" },
+ *   slots: {
+ *     insight: {
+ *       description: "A short contextual insight about the current weather",
+ *       content: null,
+ *     },
+ *   },
  * }
  * ```
  */
@@ -53,4 +73,6 @@ export interface FeedItem<
 	data: TData
 	/** Source-provided hints for post-processors. Optional — omit if no signals apply. */
 	signals?: FeedItemSignals
+	/** Named slots for LLM-fillable content. Keys are slot names. */
+	slots?: Record<string, Slot>
 }

packages/aris-core/src/index.ts

@@ -1,18 +1,21 @@
 // Context
-export type { Context, ContextKey } from "./context"
-export { contextKey, contextValue } from "./context"
+export type { ContextEntry, ContextKey, ContextKeyPart } from "./context"
+export { Context, contextKey, serializeKey } from "./context"
 
 // Actions
 export type { ActionDefinition } from "./action"
 export { UnknownActionError } from "./action"
 
 // Feed
-export type { FeedItem, FeedItemSignals } from "./feed"
+export type { FeedItem, FeedItemSignals, Slot } from "./feed"
 export { TimeRelevance } from "./feed"
 
 // Feed Source
 export type { FeedSource } from "./feed-source"
 
+// Feed Post-Processor
+export type { FeedEnhancement, FeedPostProcessor, ItemGroup } from "./feed-post-processor"
+
 // Feed Engine
 export type { FeedEngineConfig, FeedResult, FeedSubscriber, SourceError } from "./feed-engine"
 export { FeedEngine } from "./feed-engine"

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

@@ -1,5 +1,6 @@
-import type { Context } from "@aris/core"
+import type { ContextKey } from "@aris/core"
 
+import { Context, contextKey } from "@aris/core"
 import { describe, expect, test } from "bun:test"
 
 import type { WeatherKitClient, WeatherKitResponse } from "./weatherkit"
@@ -15,14 +16,25 @@ const mockCredentials = {
 	serviceId: "mock",
 }
 
+interface LocationData {
+	lat: number
+	lng: number
+	accuracy: number
+}
+
+const LocationKey: ContextKey<LocationData> = contextKey("aris.location", "location")
+
 const createMockClient = (response: WeatherKitResponse): WeatherKitClient => ({
 	fetch: async () => response,
 })
 
-const createMockContext = (location?: { lat: number; lng: number }): Context => ({
-	time: new Date("2026-01-17T00:00:00Z"),
-	location: location ? { ...location, accuracy: 10 } : undefined,
-})
+function createMockContext(location?: { lat: number; lng: number }): Context {
+	const ctx = new Context(new Date("2026-01-17T00:00:00Z"))
+	if (location) {
+		ctx.set([[LocationKey, { ...location, accuracy: 10 }]])
+	}
+	return ctx
+}
 
 describe("WeatherKitDataSource", () => {
 	test("returns empty array when location is missing", async () => {
@@ -39,7 +51,7 @@ describe("WeatherKitDataSource", () => {
 			credentials: mockCredentials,
 		})
 
-		expect(dataSource.type).toBe(WeatherFeedItemType.current)
+		expect(dataSource.type).toBe(WeatherFeedItemType.Current)
 	})
 
 	test("throws error if neither client nor credentials provided", () => {
@@ -130,9 +142,9 @@ describe("query() with mocked client", () => {
 		const items = await dataSource.query(context)
 
 		expect(items.length).toBeGreaterThan(0)
-		expect(items.some((i) => i.type === WeatherFeedItemType.current)).toBe(true)
-		expect(items.some((i) => i.type === WeatherFeedItemType.hourly)).toBe(true)
-		expect(items.some((i) => i.type === WeatherFeedItemType.daily)).toBe(true)
+		expect(items.some((i) => i.type === WeatherFeedItemType.Current)).toBe(true)
+		expect(items.some((i) => i.type === WeatherFeedItemType.Hourly)).toBe(true)
+		expect(items.some((i) => i.type === WeatherFeedItemType.Daily)).toBe(true)
 	})
 
 	test("applies hourly and daily limits", async () => {
@@ -145,8 +157,8 @@ describe("query() with mocked client", () => {
 
 		const items = await dataSource.query(context)
 
-		const hourlyItems = items.filter((i) => i.type === WeatherFeedItemType.hourly)
-		const dailyItems = items.filter((i) => i.type === WeatherFeedItemType.daily)
+		const hourlyItems = items.filter((i) => i.type === WeatherFeedItemType.Hourly)
+		const dailyItems = items.filter((i) => i.type === WeatherFeedItemType.Daily)
 
 		expect(hourlyItems.length).toBe(3)
 		expect(dailyItems.length).toBe(2)
@@ -176,8 +188,8 @@ describe("query() with mocked client", () => {
 			units: Units.imperial,
 		})
 
-		const metricCurrent = metricItems.find((i) => i.type === WeatherFeedItemType.current)
-		const imperialCurrent = imperialItems.find((i) => i.type === WeatherFeedItemType.current)
+		const metricCurrent = metricItems.find((i) => i.type === WeatherFeedItemType.Current)
+		const imperialCurrent = imperialItems.find((i) => i.type === WeatherFeedItemType.Current)
 
 		expect(metricCurrent).toBeDefined()
 		expect(imperialCurrent).toBeDefined()
@@ -203,7 +215,7 @@ describe("query() with mocked client", () => {
 			expect(item.signals!.timeRelevance).toBeDefined()
 		}
 
-		const currentItem = items.find((i) => i.type === WeatherFeedItemType.current)
+		const currentItem = items.find((i) => i.type === WeatherFeedItemType.Current)
 		expect(currentItem).toBeDefined()
 		expect(currentItem!.signals!.urgency).toBeGreaterThanOrEqual(0.5)
 	})

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

@@ -1,6 +1,6 @@
-import type { Context, DataSource, FeedItemSignals } from "@aris/core"
+import type { Context, ContextKey, DataSource, FeedItemSignals } from "@aris/core"
 
-import { TimeRelevance } from "@aris/core"
+import { TimeRelevance, contextKey } from "@aris/core"
 
 import {
 	WeatherFeedItemType,
@@ -40,11 +40,18 @@ export interface WeatherKitQueryConfig {
 	units?: Units
 }
 
+interface LocationData {
+	lat: number
+	lng: number
+}
+
+const LocationKey: ContextKey<LocationData> = contextKey("aris.location", "location")
+
 export class WeatherKitDataSource implements DataSource<WeatherFeedItem, WeatherKitQueryConfig> {
 	private readonly DEFAULT_HOURLY_LIMIT = 12
 	private readonly DEFAULT_DAILY_LIMIT = 7
 
-	readonly type = WeatherFeedItemType.current
+	readonly type = WeatherFeedItemType.Current
 	private readonly client: WeatherKitClient
 	private readonly hourlyLimit: number
 	private readonly dailyLimit: number
@@ -59,7 +66,8 @@ export class WeatherKitDataSource implements DataSource<WeatherFeedItem, Weather
 	}
 
 	async query(context: Context, config: WeatherKitQueryConfig = {}): Promise<WeatherFeedItem[]> {
-		if (!context.location) {
+		const location = context.get(LocationKey)
+		if (!location) {
 			return []
 		}
 
@@ -67,8 +75,8 @@ export class WeatherKitDataSource implements DataSource<WeatherFeedItem, Weather
 		const timestamp = context.time
 
 		const response = await this.client.fetch({
-			lat: context.location.lat,
-			lng: context.location.lng,
+			lat: location.lat,
+			lng: location.lng,
 		})
 
 		const items: WeatherFeedItem[] = []
@@ -228,7 +236,7 @@ function createCurrentWeatherFeedItem(
 
 	return {
 		id: `weather-current-${timestamp.getTime()}`,
-		type: WeatherFeedItemType.current,
+		type: WeatherFeedItemType.Current,
 		timestamp,
 		data: {
 			conditionCode: current.conditionCode,
@@ -262,7 +270,7 @@ function createHourlyWeatherFeedItem(
 
 	return {
 		id: `weather-hourly-${timestamp.getTime()}-${index}`,
-		type: WeatherFeedItemType.hourly,
+		type: WeatherFeedItemType.Hourly,
 		timestamp,
 		data: {
 			forecastTime: new Date(hourly.forecastStart),
@@ -296,7 +304,7 @@ function createDailyWeatherFeedItem(
 
 	return {
 		id: `weather-daily-${timestamp.getTime()}-${index}`,
-		type: WeatherFeedItemType.daily,
+		type: WeatherFeedItemType.Daily,
 		timestamp,
 		data: {
 			forecastDate: new Date(daily.forecastStart),
@@ -323,7 +331,7 @@ function createWeatherAlertFeedItem(alert: WeatherAlert, timestamp: Date): Weath
 
 	return {
 		id: `weather-alert-${alert.id}`,
-		type: WeatherFeedItemType.alert,
+		type: WeatherFeedItemType.Alert,
 		timestamp,
 		data: {
 			alertId: alert.id,

packages/aris-data-source-weatherkit/src/feed-items.ts

@@ -3,10 +3,10 @@ import type { FeedItem } from "@aris/core"
 import type { Certainty, ConditionCode, PrecipitationType, Severity, Urgency } from "./weatherkit"
 
 export const WeatherFeedItemType = {
-	current: "weather-current",
-	hourly: "weather-hourly",
-	daily: "weather-daily",
-	alert: "weather-alert",
+	Current: "weather-current",
+	Hourly: "weather-hourly",
+	Daily: "weather-daily",
+	Alert: "weather-alert",
 } as const
 
 export type WeatherFeedItemType = (typeof WeatherFeedItemType)[keyof typeof WeatherFeedItemType]
@@ -28,7 +28,7 @@ export type CurrentWeatherData = {
 }
 
 export interface CurrentWeatherFeedItem extends FeedItem<
-	typeof WeatherFeedItemType.current,
+	typeof WeatherFeedItemType.Current,
 	CurrentWeatherData
 > {}
 
@@ -49,7 +49,7 @@ export type HourlyWeatherData = {
 }
 
 export interface HourlyWeatherFeedItem extends FeedItem<
-	typeof WeatherFeedItemType.hourly,
+	typeof WeatherFeedItemType.Hourly,
 	HourlyWeatherData
 > {}
 
@@ -68,7 +68,7 @@ export type DailyWeatherData = {
 }
 
 export interface DailyWeatherFeedItem extends FeedItem<
-	typeof WeatherFeedItemType.daily,
+	typeof WeatherFeedItemType.Daily,
 	DailyWeatherData
 > {}
 
@@ -86,7 +86,7 @@ export type WeatherAlertData = {
 }
 
 export interface WeatherAlertFeedItem extends FeedItem<
-	typeof WeatherFeedItemType.alert,
+	typeof WeatherFeedItemType.Alert,
 	WeatherAlertData
 > {}
 

packages/aris-feed-enhancers/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "@aris/feed-enhancers",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test src/"
+	},
+	"dependencies": {
+		"@aris/core": "workspace:*",
+		"@aris/source-caldav": "workspace:*",
+		"@aris/source-google-calendar": "workspace:*",
+		"@aris/source-tfl": "workspace:*",
+		"@aris/source-weatherkit": "workspace:*"
+	}
+}

packages/aris-feed-enhancers/src/index.ts

@@ -0,0 +1 @@
+export { createTimeOfDayEnhancer, type TimeOfDayEnhancerOptions } from "./time-of-day-enhancer.ts"

packages/aris-feed-enhancers/src/time-of-day-enhancer.test.ts

@@ -0,0 +1,704 @@
+import type { FeedItem, FeedItemSignals } from "@aris/core"
+
+import { Context, TimeRelevance } from "@aris/core"
+import { CalDavFeedItemType } from "@aris/source-caldav"
+import { CalendarFeedItemType } from "@aris/source-google-calendar"
+import { TflFeedItemType } from "@aris/source-tfl"
+import { WeatherFeedItemType } from "@aris/source-weatherkit"
+import { describe, expect, test } from "bun:test"
+
+import {
+	createTimeOfDayEnhancer,
+	getTimePeriod,
+	getDayType,
+	TimePeriod,
+	DayType,
+} from "./time-of-day-enhancer"
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function makeContext(date: Date): Context {
+	return new Context(date)
+}
+
+function makeDate(year: number, month: number, day: number, hour: number, minute = 0): Date {
+	return new Date(year, month - 1, day, hour, minute, 0, 0)
+}
+
+/** Tuesday 2025-07-08 at given hour:minute */
+function tuesday(hour: number, minute = 0): Date {
+	return makeDate(2025, 7, 8, hour, minute)
+}
+
+/** Saturday 2025-07-12 at given hour:minute */
+function saturday(hour: number, minute = 0): Date {
+	return makeDate(2025, 7, 12, hour, minute)
+}
+
+function weatherCurrent(id = "w-current"): FeedItem {
+	return {
+		id,
+		type: WeatherFeedItemType.Current,
+		timestamp: new Date(),
+		data: { temperature: 18, precipitationIntensity: 0 },
+	}
+}
+
+function weatherCurrentRainy(id = "w-current-rain"): FeedItem {
+	return {
+		id,
+		type: WeatherFeedItemType.Current,
+		timestamp: new Date(),
+		data: { temperature: 12, precipitationIntensity: 2.5 },
+	}
+}
+
+function weatherCurrentExtreme(id = "w-current-extreme"): FeedItem {
+	return {
+		id,
+		type: WeatherFeedItemType.Current,
+		timestamp: new Date(),
+		data: { temperature: -5, precipitationIntensity: 0 },
+	}
+}
+
+function weatherHourly(id = "w-hourly"): FeedItem {
+	return {
+		id,
+		type: WeatherFeedItemType.Hourly,
+		timestamp: new Date(),
+		data: { forecastTime: new Date(), temperature: 20 },
+	}
+}
+
+function weatherDaily(id = "w-daily"): FeedItem {
+	return {
+		id,
+		type: WeatherFeedItemType.Daily,
+		timestamp: new Date(),
+		data: { forecastDate: new Date() },
+	}
+}
+
+function weatherAlert(id = "w-alert", urgency = 0.9): FeedItem {
+	return {
+		id,
+		type: WeatherFeedItemType.Alert,
+		timestamp: new Date(),
+		data: { severity: "extreme" },
+		signals: { urgency, timeRelevance: TimeRelevance.Imminent },
+	}
+}
+
+function calendarEvent(
+	id: string,
+	startTime: Date,
+	options: { location?: string; signals?: FeedItemSignals } = {},
+): FeedItem {
+	return {
+		id,
+		type: CalendarFeedItemType.Event,
+		timestamp: new Date(),
+		data: {
+			eventId: id,
+			calendarId: "primary",
+			title: `Event ${id}`,
+			description: null,
+			location: options.location ?? null,
+			startTime,
+			endTime: new Date(startTime.getTime() + 3_600_000),
+			isAllDay: false,
+			status: "confirmed",
+			htmlLink: "",
+		},
+		signals: options.signals,
+	}
+}
+
+function calendarAllDay(id: string): FeedItem {
+	return {
+		id,
+		type: CalendarFeedItemType.AllDay,
+		timestamp: new Date(),
+		data: {
+			eventId: id,
+			calendarId: "primary",
+			title: `All Day ${id}`,
+			description: null,
+			location: null,
+			startTime: new Date(),
+			endTime: new Date(),
+			isAllDay: true,
+			status: "confirmed",
+			htmlLink: "",
+		},
+		signals: { timeRelevance: TimeRelevance.Ambient },
+	}
+}
+
+function caldavEvent(
+	id: string,
+	startDate: Date,
+	options: { location?: string; signals?: FeedItemSignals } = {},
+): FeedItem {
+	return {
+		id,
+		type: CalDavFeedItemType.Event,
+		timestamp: new Date(),
+		data: {
+			uid: id,
+			title: `CalDAV ${id}`,
+			startDate,
+			endDate: new Date(startDate.getTime() + 3_600_000),
+			isAllDay: false,
+			location: options.location ?? null,
+			description: null,
+			calendarName: null,
+			status: "confirmed",
+			url: null,
+			organizer: null,
+			attendees: [],
+			alarms: [],
+			recurrenceId: null,
+		},
+		signals: options.signals,
+	}
+}
+
+function tflAlert(id = "tfl-1", urgency = 0.8): FeedItem {
+	return {
+		id,
+		type: TflFeedItemType.Alert,
+		timestamp: new Date(),
+		data: {
+			line: "northern",
+			lineName: "Northern",
+			severity: "major-delays",
+			description: "Delays",
+		},
+		signals: { urgency, timeRelevance: TimeRelevance.Imminent },
+	}
+}
+
+function unknownItem(id = "unknown-1"): FeedItem {
+	return {
+		id,
+		type: "some-future-type",
+		timestamp: new Date(),
+		data: { foo: "bar" },
+	}
+}
+
+// =============================================================================
+// Period detection
+// =============================================================================
+
+describe("getTimePeriod", () => {
+	test("morning: 06:00–11:59", () => {
+		expect(getTimePeriod(tuesday(6))).toBe(TimePeriod.Morning)
+		expect(getTimePeriod(tuesday(8))).toBe(TimePeriod.Morning)
+		expect(getTimePeriod(tuesday(11, 59))).toBe(TimePeriod.Morning)
+	})
+
+	test("afternoon: 12:00–16:59", () => {
+		expect(getTimePeriod(tuesday(12))).toBe(TimePeriod.Afternoon)
+		expect(getTimePeriod(tuesday(14))).toBe(TimePeriod.Afternoon)
+		expect(getTimePeriod(tuesday(16, 59))).toBe(TimePeriod.Afternoon)
+	})
+
+	test("evening: 17:00–21:59", () => {
+		expect(getTimePeriod(tuesday(17))).toBe(TimePeriod.Evening)
+		expect(getTimePeriod(tuesday(19))).toBe(TimePeriod.Evening)
+		expect(getTimePeriod(tuesday(21, 59))).toBe(TimePeriod.Evening)
+	})
+
+	test("night: 22:00–05:59", () => {
+		expect(getTimePeriod(tuesday(22))).toBe(TimePeriod.Night)
+		expect(getTimePeriod(tuesday(0))).toBe(TimePeriod.Night)
+		expect(getTimePeriod(tuesday(3))).toBe(TimePeriod.Night)
+		expect(getTimePeriod(tuesday(5, 59))).toBe(TimePeriod.Night)
+	})
+})
+
+describe("getDayType", () => {
+	test("weekday: Monday–Friday", () => {
+		// 2025-07-07 is Monday, 2025-07-08 is Tuesday, 2025-07-11 is Friday
+		expect(getDayType(makeDate(2025, 7, 7, 10))).toBe(DayType.Weekday)
+		expect(getDayType(tuesday(10))).toBe(DayType.Weekday)
+		expect(getDayType(makeDate(2025, 7, 11, 10))).toBe(DayType.Weekday)
+	})
+
+	test("weekend: Saturday–Sunday", () => {
+		expect(getDayType(saturday(10))).toBe(DayType.Weekend)
+		expect(getDayType(makeDate(2025, 7, 13, 10))).toBe(DayType.Weekend) // Sunday
+	})
+})
+
+// =============================================================================
+// Morning
+// =============================================================================
+
+describe("morning weekday", () => {
+	const now = tuesday(8)
+	const ctx = makeContext(now)
+
+	test("boosts weather-current and weather-alert, demotes weather-hourly", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const items = [weatherCurrent(), weatherHourly(), weatherAlert()]
+		const result = await enhancer(items, ctx)
+
+		expect(result.boost!["w-current"]).toBeGreaterThan(0)
+		expect(result.boost!["w-alert"]).toBeGreaterThan(0)
+		expect(result.boost!["w-hourly"]).toBeLessThan(0)
+	})
+
+	test("boosts first calendar event of the day", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const event1 = calendarEvent("c1", tuesday(9))
+		const event2 = calendarEvent("c2", tuesday(14))
+		const result = await enhancer([event1, event2], ctx)
+
+		expect(result.boost!["c1"]).toBeGreaterThan(0)
+		// Second event should not get the first-event boost
+		expect(result.boost?.["c2"] ?? 0).toBeLessThanOrEqual(0)
+	})
+
+	test("boosts TfL alerts", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const result = await enhancer([tflAlert()], ctx)
+
+		expect(result.boost!["tfl-1"]).toBeGreaterThan(0)
+	})
+})
+
+describe("morning weekend", () => {
+	const now = saturday(9)
+	const ctx = makeContext(now)
+
+	test("boosts weather-current and weather-daily", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const items = [weatherCurrent(), weatherDaily()]
+		const result = await enhancer(items, ctx)
+
+		expect(result.boost!["w-current"]).toBeGreaterThan(0)
+		expect(result.boost!["w-daily"]).toBeGreaterThan(0)
+	})
+
+	test("demotes calendar events and TfL alerts", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const event = calendarEvent("c1", saturday(10))
+		const items = [event, tflAlert()]
+		const result = await enhancer(items, ctx)
+
+		expect(result.boost!["c1"]).toBeLessThan(0)
+		expect(result.boost!["tfl-1"]).toBeLessThan(0)
+	})
+})
+
+// =============================================================================
+// Afternoon
+// =============================================================================
+
+describe("afternoon weekday", () => {
+	const now = tuesday(14)
+	const ctx = makeContext(now)
+
+	test("boosts imminent calendar events", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const event = calendarEvent("c1", tuesday(14, 10), {
+			signals: { timeRelevance: TimeRelevance.Imminent },
+		})
+		const result = await enhancer([event], ctx)
+
+		expect(result.boost!["c1"]).toBeGreaterThan(0)
+	})
+
+	test("demotes weather-current and weather-hourly", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const items = [weatherCurrent(), weatherHourly()]
+		const result = await enhancer(items, ctx)
+
+		expect(result.boost!["w-current"]).toBeLessThan(0)
+		expect(result.boost!["w-hourly"]).toBeLessThan(0)
+	})
+})
+
+describe("afternoon weekend", () => {
+	const now = saturday(14)
+	const ctx = makeContext(now)
+
+	test("boosts weather-current, demotes calendar events", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const event = calendarEvent("c1", saturday(15))
+		const items = [weatherCurrent(), event]
+		const result = await enhancer(items, ctx)
+
+		expect(result.boost!["w-current"]).toBeGreaterThan(0)
+		expect(result.boost!["c1"]).toBeLessThan(0)
+	})
+})
+
+// =============================================================================
+// Evening
+// =============================================================================
+
+describe("evening weekday", () => {
+	const now = tuesday(19)
+	const ctx = makeContext(now)
+
+	test("suppresses ambient work calendar events", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const event = calendarEvent("c1", tuesday(9), {
+			signals: { timeRelevance: TimeRelevance.Ambient },
+		})
+		const result = await enhancer([event], ctx)
+
+		expect(result.suppress).toContain("c1")
+	})
+
+	test("demotes TfL alerts", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const result = await enhancer([tflAlert()], ctx)
+
+		expect(result.boost!["tfl-1"]).toBeLessThan(0)
+	})
+
+	test("boosts weather-daily and all-day calendar events", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const items = [weatherDaily(), calendarAllDay("ad1")]
+		const result = await enhancer(items, ctx)
+
+		expect(result.boost!["w-daily"]).toBeGreaterThan(0)
+		expect(result.boost!["ad1"]).toBeGreaterThan(0)
+	})
+})
+
+describe("evening weekend", () => {
+	const now = saturday(19)
+	const ctx = makeContext(now)
+
+	test("boosts weather-current, suppresses ambient calendar events", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const event = calendarEvent("c1", saturday(9), {
+			signals: { timeRelevance: TimeRelevance.Ambient },
+		})
+		const items = [weatherCurrent(), event]
+		const result = await enhancer(items, ctx)
+
+		expect(result.boost!["w-current"]).toBeGreaterThan(0)
+		expect(result.suppress).toContain("c1")
+	})
+
+	test("demotes TfL alerts more aggressively", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const result = await enhancer([tflAlert()], ctx)
+
+		expect(result.boost!["tfl-1"]).toBeLessThan(-0.3)
+	})
+})
+
+// =============================================================================
+// Night
+// =============================================================================
+
+describe("night", () => {
+	const now = tuesday(23)
+	const ctx = makeContext(now)
+
+	test("suppresses ambient items", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const event = calendarEvent("c1", tuesday(9), {
+			signals: { timeRelevance: TimeRelevance.Ambient },
+		})
+		const result = await enhancer([event], ctx)
+
+		expect(result.suppress).toContain("c1")
+	})
+
+	test("demotes calendar events and weather-current", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const event = calendarEvent("c1", makeDate(2025, 7, 9, 9)) // tomorrow
+		const items = [event, weatherCurrent()]
+		const result = await enhancer(items, ctx)
+
+		expect(result.boost!["c1"]).toBeLessThan(0)
+		expect(result.boost!["w-current"]).toBeLessThan(0)
+	})
+
+	test("high-urgency alerts survive unboosted", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const alert = weatherAlert("w-alert", 0.9)
+		const result = await enhancer([alert], ctx)
+
+		// Should not be demoted — either no boost entry or >= 0
+		const alertBoost = result.boost?.["w-alert"] ?? 0
+		expect(alertBoost).toBeGreaterThanOrEqual(0)
+	})
+})
+
+// =============================================================================
+// Pre-meeting window
+// =============================================================================
+
+describe("pre-meeting window", () => {
+	test("boosts upcoming meeting to +0.9", async () => {
+		const now = tuesday(9, 45)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const meeting = calendarEvent("c1", tuesday(10))
+		const result = await enhancer([meeting], makeContext(now))
+
+		expect(result.boost!["c1"]).toBe(0.9)
+	})
+
+	test("suppresses low-urgency items during pre-meeting", async () => {
+		const now = tuesday(9, 45)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const meeting = calendarEvent("c1", tuesday(10))
+		const lowPriority = weatherHourly()
+		lowPriority.signals = { urgency: 0.1 }
+		const result = await enhancer([meeting, lowPriority], makeContext(now))
+
+		expect(result.suppress).toContain("w-hourly")
+	})
+
+	test("does not suppress items without signals during pre-meeting", async () => {
+		const now = tuesday(9, 45)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const meeting = calendarEvent("c1", tuesday(10))
+		const noSignals = weatherDaily()
+		const result = await enhancer([meeting, noSignals], makeContext(now))
+
+		expect(result.suppress ?? []).not.toContain("w-daily")
+	})
+
+	test("boosts TfL alerts during pre-meeting", async () => {
+		const now = tuesday(9, 45)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const meeting = calendarEvent("c1", tuesday(10))
+		const result = await enhancer([meeting, tflAlert()], makeContext(now))
+
+		expect(result.boost!["tfl-1"]).toBeGreaterThan(0)
+	})
+
+	test("boosts weather-current if meeting has a location", async () => {
+		const now = tuesday(9, 45)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const meeting = calendarEvent("c1", tuesday(10), { location: "Office, London" })
+		const result = await enhancer([meeting, weatherCurrent()], makeContext(now))
+
+		expect(result.boost!["w-current"]).toBeGreaterThan(0)
+	})
+
+	test("works with CalDAV events", async () => {
+		const now = tuesday(9, 45)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const meeting = caldavEvent("cd1", tuesday(10))
+		const result = await enhancer([meeting], makeContext(now))
+
+		expect(result.boost!["cd1"]).toBe(0.9)
+	})
+
+	test("does not trigger for events more than 30 minutes away", async () => {
+		const now = tuesday(9)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const meeting = calendarEvent("c1", tuesday(10))
+		const result = await enhancer([meeting], makeContext(now))
+
+		// Should not get the +0.9 pre-meeting boost
+		expect(result.boost?.["c1"] ?? 0).not.toBe(0.9)
+	})
+})
+
+// =============================================================================
+// Wind-down gradient
+// =============================================================================
+
+describe("wind-down gradient", () => {
+	test("20:00 weekday: additional -0.1 on work items", async () => {
+		const now = tuesday(20)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		// Non-ambient calendar event — evening rules don't boost or suppress it,
+		// so the only demotion comes from wind-down at 20:00 (-0.1).
+		const event = calendarEvent("c1", makeDate(2025, 7, 9, 9))
+		const result = await enhancer([event], makeContext(now))
+
+		expect(result.boost!["c1"]).toBe(-0.1)
+	})
+
+	test("21:00 weekday: additional -0.2 on work items", async () => {
+		const now = tuesday(21)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const alert = tflAlert("tfl-1", 0.5)
+		const result = await enhancer([alert], makeContext(now))
+
+		// Evening demotes TfL by -0.4, wind-down adds -0.2 = -0.6
+		expect(result.boost!["tfl-1"]).toBeLessThanOrEqual(-0.6)
+	})
+
+	test("21:30 weekday: additional -0.3 on work items", async () => {
+		const now = tuesday(21, 30)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const alert = tflAlert("tfl-1", 0.5)
+		const result = await enhancer([alert], makeContext(now))
+
+		// Evening demotes TfL by -0.4, wind-down adds -0.3 = -0.7
+		expect(result.boost!["tfl-1"]).toBeLessThanOrEqual(-0.7)
+	})
+
+	test("does not apply on weekends", async () => {
+		const now = saturday(21)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const alert = tflAlert("tfl-1", 0.5)
+		const result = await enhancer([alert], makeContext(now))
+
+		// Weekend evening demotes TfL by -0.5, but no wind-down
+		expect(result.boost!["tfl-1"]).toBe(-0.5)
+	})
+})
+
+// =============================================================================
+// Transition lookahead
+// =============================================================================
+
+describe("transition lookahead", () => {
+	test("Saturday 11:40 boosts afternoon-relevant weather-current", async () => {
+		const now = saturday(11, 40)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const items = [weatherCurrent()]
+		const result = await enhancer(items, makeContext(now))
+
+		// Weekend morning boosts weather-current by +0.5.
+		// Transition to afternoon adds +0.2 (weekend afternoon boosts weather-current).
+		expect(result.boost!["w-current"]).toBe(0.7)
+	})
+
+	test("16:40 weekday boosts evening-relevant items (weather-daily)", async () => {
+		const now = tuesday(16, 40)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const items = [weatherDaily()]
+		const result = await enhancer(items, makeContext(now))
+
+		// Afternoon weekday doesn't boost weather-daily, but transition to evening does (+0.2)
+		expect(result.boost!["w-daily"]).toBeGreaterThan(0)
+	})
+
+	test("does not apply when far from boundary", async () => {
+		const now = tuesday(14)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const items = [weatherDaily()]
+		const result = await enhancer(items, makeContext(now))
+
+		// Afternoon weekday doesn't boost or demote weather-daily, and no transition
+		expect(result.boost?.["w-daily"]).toBeUndefined()
+	})
+})
+
+// =============================================================================
+// Weather-time correlation
+// =============================================================================
+
+describe("weather-time correlation", () => {
+	test("morning weekday: extra boost for precipitation", async () => {
+		const now = tuesday(8)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const rainy = weatherCurrentRainy()
+		const dry = weatherCurrent("w-dry")
+		const result = await enhancer([rainy, dry], makeContext(now))
+
+		// Both get morning boost, but rainy gets extra +0.1
+		expect(result.boost!["w-current-rain"]).toBeGreaterThan(result.boost!["w-dry"] ?? 0)
+	})
+
+	test("morning weekday: extra boost for extreme temperature", async () => {
+		const now = tuesday(8)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const extreme = weatherCurrentExtreme()
+		const normal = weatherCurrent("w-normal")
+		const result = await enhancer([extreme, normal], makeContext(now))
+
+		expect(result.boost!["w-current-extreme"]).toBeGreaterThan(result.boost!["w-normal"] ?? 0)
+	})
+
+	test("evening with location event: extra boost for weather-current", async () => {
+		const now = tuesday(19)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const event = calendarEvent("c1", tuesday(19, 30), { location: "The Ivy, London" })
+		const items = [weatherCurrent(), event]
+		const result = await enhancer(items, makeContext(now))
+
+		// Weather-current gets evening weather-time correlation boost (+0.2)
+		// Note: evening weekday doesn't normally boost weather-current
+		expect(result.boost!["w-current"]).toBeGreaterThan(0)
+	})
+
+	test("weather-alert always gets at least +0.5", async () => {
+		const now = tuesday(14) // afternoon — no special weather boost
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const alert = weatherAlert("w-alert", 0.5)
+		const result = await enhancer([alert], makeContext(now))
+
+		expect(result.boost!["w-alert"]).toBeGreaterThanOrEqual(0.5)
+	})
+})
+
+// =============================================================================
+// Edge cases
+// =============================================================================
+
+describe("edge cases", () => {
+	test("empty items returns empty enhancement", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => tuesday(8) })
+		const result = await enhancer([], makeContext(tuesday(8)))
+
+		expect(result).toEqual({})
+	})
+
+	test("unknown item types get no boost", async () => {
+		const enhancer = createTimeOfDayEnhancer({ clock: () => tuesday(8) })
+		const result = await enhancer([unknownItem()], makeContext(tuesday(8)))
+
+		expect(result.boost?.["unknown-1"]).toBeUndefined()
+		expect(result.suppress).toBeUndefined()
+	})
+
+	test("uses context.time when no clock provided", async () => {
+		const enhancer = createTimeOfDayEnhancer()
+		const morningCtx = makeContext(tuesday(8))
+		const items = [weatherCurrent()]
+		const result = await enhancer(items, morningCtx)
+
+		// Should apply morning rules — weather-current boosted
+		expect(result.boost!["w-current"]).toBeGreaterThan(0)
+	})
+
+	test("boost values are clamped to [-1, 1]", async () => {
+		// Morning weekday: TfL alert gets +0.6 from period rules.
+		// Pre-meeting adds +0.5. Total would be +1.1 without clamping.
+		const now = tuesday(8, 45)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const meeting = calendarEvent("c1", tuesday(9))
+		const alert = tflAlert("tfl-1", 0.8)
+		const result = await enhancer([meeting, alert], makeContext(now))
+
+		expect(result.boost!["tfl-1"]).toBeLessThanOrEqual(1)
+		expect(result.boost!["tfl-1"]).toBeGreaterThanOrEqual(-1)
+	})
+
+	test("suppress list is deduplicated", async () => {
+		// An item that would be suppressed by both evening rules and pre-meeting low-urgency
+		const now = tuesday(19, 45)
+		const enhancer = createTimeOfDayEnhancer({ clock: () => now })
+		const meeting = calendarEvent("c1", tuesday(20))
+		const ambientEvent = calendarEvent("c2", tuesday(9), {
+			signals: { urgency: 0.1, timeRelevance: TimeRelevance.Ambient },
+		})
+		const result = await enhancer([meeting, ambientEvent], makeContext(now))
+
+		if (result.suppress) {
+			const c2Count = result.suppress.filter((id) => id === "c2").length
+			expect(c2Count).toBeLessThanOrEqual(1)
+		}
+	})
+})

packages/aris-feed-enhancers/src/time-of-day-enhancer.ts

@@ -0,0 +1,595 @@
+import type { Context, FeedEnhancement, FeedItem, FeedPostProcessor } from "@aris/core"
+
+import { TimeRelevance } from "@aris/core"
+
+import type { CalDavEventData } from "@aris/source-caldav"
+import type { CalendarEventData } from "@aris/source-google-calendar"
+import type { CurrentWeatherData } from "@aris/source-weatherkit"
+
+import { CalDavFeedItemType } from "@aris/source-caldav"
+import { CalendarFeedItemType } from "@aris/source-google-calendar"
+import { TflFeedItemType } from "@aris/source-tfl"
+import { WeatherFeedItemType } from "@aris/source-weatherkit"
+
+
+export const TimePeriod = {
+	Morning: "morning",
+	Afternoon: "afternoon",
+	Evening: "evening",
+	Night: "night",
+} as const
+
+export type TimePeriod = (typeof TimePeriod)[keyof typeof TimePeriod]
+
+export const DayType = {
+	Weekday: "weekday",
+	Weekend: "weekend",
+} as const
+
+export type DayType = (typeof DayType)[keyof typeof DayType]
+
+
+const PRE_MEETING_WINDOW_MS = 30 * 60 * 1000
+const TRANSITION_WINDOW_MS = 30 * 60 * 1000
+
+const PERIOD_BOUNDARIES = [
+	{ hour: 6, period: TimePeriod.Morning },
+	{ hour: 12, period: TimePeriod.Afternoon },
+	{ hour: 17, period: TimePeriod.Evening },
+	{ hour: 22, period: TimePeriod.Night },
+] as const
+
+/** All calendar event types across sources */
+const CALENDAR_EVENT_TYPES: ReadonlySet<string> = new Set([
+	CalendarFeedItemType.Event,
+	CalDavFeedItemType.Event,
+])
+
+/**
+ * Creates a post-processor that reranks feed items based on time of day.
+ *
+ * Prioritizes items that matter right now and pushes down items that don't:
+ *
+ * - Morning: weather and first meeting rise, hourly forecasts sink.
+ *   Weekends flip — weather stays up but work calendar and commute alerts drop.
+ * - Afternoon: imminent meetings rise. Stale weather sinks.
+ * - Evening: work calendar is suppressed, tomorrow's forecast and personal
+ *   events rise. Weekends suppress work more aggressively.
+ * - Night: almost everything sinks except high-urgency alerts.
+ * - Pre-meeting (30 min before any event): that meeting dominates, low-urgency
+ *   noise is suppressed, commute/weather context rises if the meeting has a location.
+ * - Wind-down (weekday 20–22h): work items progressively sink as night approaches.
+ * - Transition lookahead (30 min before a period boundary): items relevant to
+ *   the next period get a head start.
+ * - Weather-time correlation: precipitation boosts morning weather, evening
+ *   events with locations boost current weather, alerts always stay high.
+ */
+export interface TimeOfDayEnhancerOptions {
+	/** Override clock for testing. Defaults to reading context.time. */
+	clock?: () => Date
+}
+
+export function createTimeOfDayEnhancer(options?: TimeOfDayEnhancerOptions): FeedPostProcessor {
+	const clock = options?.clock
+
+	function timeOfDayEnhancer(items: FeedItem[], context: Context): Promise<FeedEnhancement> {
+		if (items.length === 0) return Promise.resolve({})
+
+		const now = clock ? clock() : context.time
+		const period = getTimePeriod(now)
+		const dayType = getDayType(now)
+		const boost: Record<string, number> = {}
+		const suppress: string[] = []
+
+		// 1. Apply period-based rules
+		const firstEventId = findFirstEventOfDay(items, now)
+
+		switch (period) {
+			case TimePeriod.Morning:
+				if (dayType === DayType.Weekday) {
+					applyMorningWeekday(items, boost, firstEventId)
+				} else {
+					applyMorningWeekend(items, boost)
+				}
+				break
+			case TimePeriod.Afternoon:
+				if (dayType === DayType.Weekday) {
+					applyAfternoonWeekday(items, boost)
+				} else {
+					applyAfternoonWeekend(items, boost)
+				}
+				break
+			case TimePeriod.Evening:
+				if (dayType === DayType.Weekday) {
+					applyEveningWeekday(items, boost, suppress)
+				} else {
+					applyEveningWeekend(items, boost, suppress)
+				}
+				break
+			case TimePeriod.Night:
+				applyNight(items, boost, suppress)
+				break
+		}
+
+		// 2. Pre-meeting overrides (can override period rules)
+		const preMeeting = detectPreMeetingItems(items, now)
+		applyPreMeetingOverrides(items, preMeeting, boost, suppress)
+
+		// 3. Wind-down gradient
+		applyWindDown(items, now, dayType, boost)
+
+		// 4. Transition lookahead
+		applyTransitionLookahead(items, now, period, dayType, boost)
+
+		// 5. Weather-time correlation
+		const eveningLocation = hasEveningCalendarEventWithLocation(items, now)
+		applyWeatherTimeCorrelation(items, period, dayType, eveningLocation, boost)
+
+		// Clamp boost values to [-1, 1] — additive layers can exceed the range
+		for (const id in boost) {
+			boost[id] = Math.max(-1, Math.min(1, boost[id]!))
+		}
+
+		const result: FeedEnhancement = {}
+		if (Object.keys(boost).length > 0) {
+			result.boost = boost
+		}
+		const uniqueSuppress = [...new Set(suppress)]
+		if (uniqueSuppress.length > 0) {
+			result.suppress = uniqueSuppress
+		}
+		return Promise.resolve(result)
+	}
+
+	return timeOfDayEnhancer
+}
+
+
+export function getTimePeriod(date: Date): TimePeriod {
+	const hour = date.getHours()
+	if (hour >= 22 || hour < 6) return TimePeriod.Night
+	if (hour >= 17) return TimePeriod.Evening
+	if (hour >= 12) return TimePeriod.Afternoon
+	return TimePeriod.Morning
+}
+
+export function getDayType(date: Date): DayType {
+	const day = date.getDay()
+	return day === 0 || day === 6 ? DayType.Weekend : DayType.Weekday
+}
+
+/**
+ * Returns the next period boundary as { hour, period } and the ms until it.
+ */
+function getNextPeriodBoundary(date: Date): { period: TimePeriod; msUntil: number } {
+	const hour = date.getHours()
+	const minuteMs = date.getMinutes() * 60_000 + date.getSeconds() * 1000 + date.getMilliseconds()
+
+	for (const boundary of PERIOD_BOUNDARIES) {
+		if (hour < boundary.hour) {
+			const msUntil = (boundary.hour - hour) * 3_600_000 - minuteMs
+			return { period: boundary.period, msUntil }
+		}
+	}
+
+	// Past 22:00 — next boundary is morning at 06:00
+	const hoursUntil6 = (24 - hour + 6) * 3_600_000 - minuteMs
+	return { period: TimePeriod.Morning, msUntil: hoursUntil6 }
+}
+
+/**
+ * Extract start time from calendar event data.
+ * Google Calendar uses `startTime`, CalDAV uses `startDate`.
+ */
+function getEventStartTime(data: CalendarEventData | CalDavEventData): Date {
+	return "startTime" in data ? (data as CalendarEventData).startTime : (data as CalDavEventData).startDate
+}
+
+/**
+ * Check if a current weather item indicates precipitation or extreme conditions.
+ * Only meaningful for weather-current items.
+ */
+function hasPrecipitationOrExtreme(item: FeedItem): boolean {
+	const data = item.data as CurrentWeatherData
+	if (data.precipitationIntensity > 0) return true
+	if (data.temperature < 0 || data.temperature > 35) return true
+	return false
+}
+
+
+interface PreMeetingInfo {
+	/** IDs of calendar items starting within the pre-meeting window */
+	upcomingMeetingIds: Set<string>
+	/** Whether any upcoming meeting has a location */
+	hasLocationMeeting: boolean
+}
+
+function detectPreMeetingItems(items: FeedItem[], now: Date): PreMeetingInfo {
+	const nowMs = now.getTime()
+	const upcomingMeetingIds = new Set<string>()
+	let hasLocationMeeting = false
+
+	for (const item of items) {
+		if (!CALENDAR_EVENT_TYPES.has(item.type)) continue
+
+		const data = item.data as CalendarEventData | CalDavEventData
+		const msUntil = getEventStartTime(data).getTime() - nowMs
+		if (msUntil > 0 && msUntil <= PRE_MEETING_WINDOW_MS) {
+			upcomingMeetingIds.add(item.id)
+			if (data.location) {
+				hasLocationMeeting = true
+			}
+		}
+	}
+
+	return { upcomingMeetingIds, hasLocationMeeting }
+}
+
+
+function findFirstEventOfDay(items: FeedItem[], now: Date): string | null {
+	let earliest: { id: string; time: number } | null = null
+
+	for (const item of items) {
+		if (!CALENDAR_EVENT_TYPES.has(item.type)) continue
+
+		const data = item.data as CalendarEventData | CalDavEventData
+		const startTime = getEventStartTime(data)
+		const startMs = startTime.getTime()
+
+		// Must be today and in the future
+		const sameDay =
+			startTime.getFullYear() === now.getFullYear() &&
+			startTime.getMonth() === now.getMonth() &&
+			startTime.getDate() === now.getDate()
+		if (!sameDay) continue
+		if (startMs <= now.getTime()) continue
+
+		if (!earliest || startMs < earliest.time) {
+			earliest = { id: item.id, time: startMs }
+		}
+	}
+
+	return earliest?.id ?? null
+}
+
+
+function applyMorningWeekday(
+	items: FeedItem[],
+	boost: Record<string, number>,
+	firstEventId: string | null,
+): void {
+	for (const item of items) {
+		switch (item.type) {
+			case WeatherFeedItemType.Current:
+				boost[item.id] = (boost[item.id] ?? 0) + 0.7
+				break
+			case WeatherFeedItemType.Alert:
+				boost[item.id] = (boost[item.id] ?? 0) + 0.8
+				break
+			case WeatherFeedItemType.Hourly:
+			case WeatherFeedItemType.Daily:
+				boost[item.id] = (boost[item.id] ?? 0) - 0.3
+				break
+			case TflFeedItemType.Alert:
+				boost[item.id] = (boost[item.id] ?? 0) + 0.6
+				break
+		}
+	}
+
+	if (firstEventId) {
+		boost[firstEventId] = (boost[firstEventId] ?? 0) + 0.6
+	}
+}
+
+function applyMorningWeekend(items: FeedItem[], boost: Record<string, number>): void {
+	for (const item of items) {
+		switch (item.type) {
+			case WeatherFeedItemType.Current:
+				boost[item.id] = (boost[item.id] ?? 0) + 0.5
+				break
+			case WeatherFeedItemType.Daily:
+				boost[item.id] = (boost[item.id] ?? 0) + 0.4
+				break
+			case CalendarFeedItemType.Event:
+			case CalDavFeedItemType.Event:
+				boost[item.id] = (boost[item.id] ?? 0) - 0.4
+				break
+			case TflFeedItemType.Alert:
+				boost[item.id] = (boost[item.id] ?? 0) - 0.3
+				break
+		}
+	}
+}
+
+function applyAfternoonWeekday(items: FeedItem[], boost: Record<string, number>): void {
+	for (const item of items) {
+		switch (item.type) {
+			case CalendarFeedItemType.Event:
+			case CalDavFeedItemType.Event:
+				if (item.signals?.timeRelevance === TimeRelevance.Imminent) {
+					boost[item.id] = (boost[item.id] ?? 0) + 0.5
+				}
+				break
+			case WeatherFeedItemType.Current:
+			case WeatherFeedItemType.Hourly:
+				boost[item.id] = (boost[item.id] ?? 0) - 0.2
+				break
+		}
+	}
+}
+
+function applyAfternoonWeekend(items: FeedItem[], boost: Record<string, number>): void {
+	for (const item of items) {
+		switch (item.type) {
+			case WeatherFeedItemType.Current:
+				boost[item.id] = (boost[item.id] ?? 0) + 0.3
+				break
+			case CalendarFeedItemType.Event:
+			case CalDavFeedItemType.Event:
+				boost[item.id] = (boost[item.id] ?? 0) - 0.5
+				break
+			case TflFeedItemType.Alert:
+				boost[item.id] = (boost[item.id] ?? 0) - 0.2
+				break
+		}
+	}
+}
+
+function applyEveningWeekday(
+	items: FeedItem[],
+	boost: Record<string, number>,
+	suppress: string[],
+): void {
+	for (const item of items) {
+		switch (item.type) {
+			case CalendarFeedItemType.Event:
+			case CalDavFeedItemType.Event:
+				if (item.signals?.timeRelevance === TimeRelevance.Ambient) {
+					suppress.push(item.id)
+				}
+				break
+			case TflFeedItemType.Alert:
+				boost[item.id] = (boost[item.id] ?? 0) - 0.4
+				break
+			case WeatherFeedItemType.Daily:
+				boost[item.id] = (boost[item.id] ?? 0) + 0.3
+				break
+			case CalendarFeedItemType.AllDay:
+				boost[item.id] = (boost[item.id] ?? 0) + 0.3
+				break
+		}
+	}
+}
+
+function applyEveningWeekend(
+	items: FeedItem[],
+	boost: Record<string, number>,
+	suppress: string[],
+): void {
+	for (const item of items) {
+		switch (item.type) {
+			case WeatherFeedItemType.Current:
+				boost[item.id] = (boost[item.id] ?? 0) + 0.3
+				break
+			case CalendarFeedItemType.Event:
+			case CalDavFeedItemType.Event:
+				if (item.signals?.timeRelevance === TimeRelevance.Ambient) {
+					suppress.push(item.id)
+				}
+				break
+			case TflFeedItemType.Alert:
+				boost[item.id] = (boost[item.id] ?? 0) - 0.5
+				break
+		}
+	}
+}
+
+function applyNight(items: FeedItem[], boost: Record<string, number>, suppress: string[]): void {
+	for (const item of items) {
+		// Suppress all ambient items
+		if (item.signals?.timeRelevance === TimeRelevance.Ambient) {
+			suppress.push(item.id)
+			continue
+		}
+
+		// High-urgency alerts survive unboosted
+		if (
+			(item.type === WeatherFeedItemType.Alert || item.type === TflFeedItemType.Alert) &&
+			(item.signals?.urgency ?? 0) >= 0.8
+		) {
+			continue
+		}
+
+		// Demote everything else
+		switch (item.type) {
+			case CalendarFeedItemType.Event:
+			case CalendarFeedItemType.AllDay:
+			case CalDavFeedItemType.Event:
+				boost[item.id] = (boost[item.id] ?? 0) - 0.6
+				break
+			case WeatherFeedItemType.Current:
+			case WeatherFeedItemType.Hourly:
+				boost[item.id] = (boost[item.id] ?? 0) - 0.5
+				break
+		}
+	}
+}
+
+
+function applyPreMeetingOverrides(
+	items: FeedItem[],
+	preMeeting: PreMeetingInfo,
+	boost: Record<string, number>,
+	suppress: string[],
+): void {
+	if (preMeeting.upcomingMeetingIds.size === 0) return
+
+	// Intentional override, not additive — the upcoming meeting should dominate
+	// regardless of what period rules assigned. Don't reorder this before period rules.
+	for (const meetingId of preMeeting.upcomingMeetingIds) {
+		boost[meetingId] = 0.9
+	}
+
+	for (const item of items) {
+		if (preMeeting.upcomingMeetingIds.has(item.id)) continue
+
+		switch (item.type) {
+			case TflFeedItemType.Alert:
+				boost[item.id] = (boost[item.id] ?? 0) + 0.5
+				break
+			case WeatherFeedItemType.Current:
+				if (preMeeting.hasLocationMeeting) {
+					boost[item.id] = (boost[item.id] ?? 0) + 0.4
+				}
+				break
+		}
+
+		// Suppress items that explicitly declare low urgency.
+		// Items without signals are left alone — absence of urgency is not low urgency.
+		if (item.signals && item.signals.urgency !== undefined && item.signals.urgency < 0.3) {
+			suppress.push(item.id)
+		}
+	}
+}
+
+function applyWindDown(
+	items: FeedItem[],
+	now: Date,
+	dayType: DayType,
+	boost: Record<string, number>,
+): void {
+	if (dayType !== DayType.Weekday) return
+
+	const hour = now.getHours()
+	const minutes = now.getMinutes()
+
+	if (hour < 20 || hour >= 22) return
+
+	// Gradient: 20:00 → -0.1, 21:00 → -0.2, 21:30+ → -0.3
+	let additionalDemotion: number
+	if (hour === 20) {
+		additionalDemotion = -0.1
+	} else if (hour === 21 && minutes < 30) {
+		additionalDemotion = -0.2
+	} else {
+		additionalDemotion = -0.3
+	}
+
+	for (const item of items) {
+		switch (item.type) {
+			case CalendarFeedItemType.Event:
+			case CalendarFeedItemType.AllDay:
+			case CalDavFeedItemType.Event:
+			case TflFeedItemType.Alert:
+				boost[item.id] = (boost[item.id] ?? 0) + additionalDemotion
+				break
+		}
+	}
+}
+
+
+function applyTransitionLookahead(
+	items: FeedItem[],
+	now: Date,
+	currentPeriod: TimePeriod,
+	dayType: DayType,
+	boost: Record<string, number>,
+): void {
+	const next = getNextPeriodBoundary(now)
+	if (next.msUntil > TRANSITION_WINDOW_MS) return
+
+	// Apply a +0.2 secondary boost to items that would be boosted in the next period
+	const nextPeriodBoost = getNextPeriodBoostTargets(next.period, dayType)
+
+	for (const item of items) {
+		if (nextPeriodBoost.has(item.type)) {
+			boost[item.id] = (boost[item.id] ?? 0) + 0.2
+		}
+	}
+}
+
+/**
+ * Returns the set of item types that get boosted in a given period+dayType.
+ */
+function getNextPeriodBoostTargets(period: TimePeriod, dayType: DayType): ReadonlySet<string> {
+	const targets = new Set<string>()
+
+	switch (period) {
+		case TimePeriod.Morning:
+			targets.add(WeatherFeedItemType.Current)
+			if (dayType === DayType.Weekday) {
+				targets.add(WeatherFeedItemType.Alert)
+				targets.add(TflFeedItemType.Alert)
+			} else {
+				targets.add(WeatherFeedItemType.Daily)
+			}
+			break
+		case TimePeriod.Afternoon:
+			if (dayType === DayType.Weekend) {
+				targets.add(WeatherFeedItemType.Current)
+			}
+			break
+		case TimePeriod.Evening:
+			targets.add(WeatherFeedItemType.Daily)
+			if (dayType === DayType.Weekend) {
+				targets.add(WeatherFeedItemType.Current)
+			}
+			break
+		case TimePeriod.Night:
+			// Night doesn't boost much — transition toward night means demoting,
+			// which is handled by wind-down. No positive targets here.
+			break
+	}
+
+	return targets
+}
+
+
+function applyWeatherTimeCorrelation(
+	items: FeedItem[],
+	period: TimePeriod,
+	dayType: DayType,
+	hasEveningEventWithLocation: boolean,
+	boost: Record<string, number>,
+): void {
+	for (const item of items) {
+		switch (item.type) {
+			case WeatherFeedItemType.Alert: {
+				const current = boost[item.id] ?? 0
+				if (current < 0.5) {
+					boost[item.id] = 0.5
+				}
+				break
+			}
+			case WeatherFeedItemType.Current:
+				if (period === TimePeriod.Morning && dayType === DayType.Weekday && hasPrecipitationOrExtreme(item)) {
+					boost[item.id] = (boost[item.id] ?? 0) + 0.1
+				}
+				if (period === TimePeriod.Evening && hasEveningEventWithLocation) {
+					boost[item.id] = (boost[item.id] ?? 0) + 0.2
+				}
+				break
+		}
+	}
+}
+
+function hasEveningCalendarEventWithLocation(items: FeedItem[], now: Date): boolean {
+	const todayEvening17 = new Date(now)
+	todayEvening17.setHours(17, 0, 0, 0)
+	const todayNight22 = new Date(now)
+	todayNight22.setHours(22, 0, 0, 0)
+
+	for (const item of items) {
+		if (!CALENDAR_EVENT_TYPES.has(item.type)) continue
+
+		const data = item.data as CalendarEventData | CalDavEventData
+		const startMs = getEventStartTime(data).getTime()
+		if (startMs >= todayEvening17.getTime() && startMs < todayNight22.getTime()) {
+			if (data.location) return true
+		}
+	}
+
+	return false
+}
+
+

packages/aris-source-caldav/README.md

@@ -0,0 +1,58 @@
+# @aris/source-caldav
+
+A FeedSource that fetches calendar events from any CalDAV server.
+
+## Usage
+
+```ts
+import { CalDavSource } from "@aris/source-caldav"
+
+// Basic auth (Nextcloud, Radicale, Baikal, iCloud, etc.)
+const source = new CalDavSource({
+	serverUrl: "https://caldav.example.com",
+	authMethod: "basic",
+	username: "user",
+	password: "pass",
+	lookAheadDays: 7, // optional, default: 0 (today only)
+	timeZone: "America/New_York", // optional, default: UTC
+})
+
+// OAuth
+const source = new CalDavSource({
+	serverUrl: "https://caldav.provider.com",
+	authMethod: "oauth",
+	accessToken: "...",
+	refreshToken: "...",
+	tokenUrl: "https://provider.com/oauth/token",
+})
+```
+
+### iCloud
+
+Use your Apple ID email as the username and an [app-specific password](https://support.apple.com/en-us/102654):
+
+```ts
+const source = new CalDavSource({
+	serverUrl: "https://caldav.icloud.com",
+	authMethod: "basic",
+	username: "you@icloud.com",
+	password: "<app-specific-password>",
+})
+```
+
+## Testing
+
+```bash
+bun test
+```
+
+### Live test
+
+`bun run test:live` connects to a real CalDAV server and prints all events to the console. It prompts for:
+
+- **CalDAV server URL** — e.g. `https://caldav.icloud.com`
+- **Username** — your account email
+- **Password** — your password (or app-specific password for iCloud)
+- **Look-ahead days** — how many days beyond today to fetch (default: 0)
+
+The script runs both `fetchContext` and `fetchItems`, printing the calendar context (in-progress events, next event, today's count) followed by each event with its title, time, location, signals, and attendees.

packages/aris-source-caldav/fixtures/all-day-event.ics

@@ -0,0 +1,11 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:all-day-001@test
+DTSTART;VALUE=DATE:20260115
+DTEND;VALUE=DATE:20260116
+SUMMARY:Company Holiday
+STATUS:CONFIRMED
+END:VEVENT
+END:VCALENDAR

packages/aris-source-caldav/fixtures/cancelled-event.ics

@@ -0,0 +1,11 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:cancelled-001@test
+DTSTART:20260115T120000Z
+DTEND:20260115T130000Z
+SUMMARY:Cancelled Meeting
+STATUS:CANCELLED
+END:VEVENT
+END:VCALENDAR

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/minimal-event.ics

@@ -0,0 +1,10 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:minimal-001@test
+DTSTART:20260115T180000Z
+DTEND:20260115T190000Z
+SUMMARY:Quick Chat
+END:VEVENT
+END:VCALENDAR

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

@@ -0,0 +1,20 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:recurring-001@test
+DTSTART:20260115T090000Z
+DTEND:20260115T093000Z
+SUMMARY:Weekly Sync
+RRULE:FREQ=WEEKLY;COUNT=4
+STATUS:CONFIRMED
+END:VEVENT
+BEGIN:VEVENT
+UID:recurring-001@test
+RECURRENCE-ID:20260122T090000Z
+DTSTART:20260122T100000Z
+DTEND:20260122T103000Z
+SUMMARY:Weekly Sync (moved)
+STATUS:CONFIRMED
+END:VEVENT
+END:VCALENDAR

packages/aris-source-caldav/fixtures/single-event.ics

@@ -0,0 +1,26 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:single-event-001@test
+DTSTART:20260115T140000Z
+DTEND:20260115T150000Z
+SUMMARY:Team Standup
+LOCATION:Conference Room A
+DESCRIPTION:Daily standup meeting
+STATUS:CONFIRMED
+URL:https://example.com/meeting/123
+ORGANIZER;CN=Alice Smith:mailto:alice@example.com
+ATTENDEE;CN=Bob Jones;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED:mailto:bob@example.com
+ATTENDEE;CN=Carol White;ROLE=OPT-PARTICIPANT;PARTSTAT=TENTATIVE:mailto:carol@example.com
+BEGIN:VALARM
+TRIGGER:-PT15M
+ACTION:DISPLAY
+DESCRIPTION:Reminder
+END:VALARM
+BEGIN:VALARM
+TRIGGER:-PT5M
+ACTION:AUDIO
+END:VALARM
+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/package.json

@@ -0,0 +1,16 @@
+{
+	"name": "@aris/source-caldav",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test .",
+		"test:live": "bun run scripts/test-live.ts"
+	},
+	"dependencies": {
+		"@aris/core": "workspace:*",
+		"ical.js": "^2.1.0",
+		"tsdav": "^2.1.7"
+	}
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Live test script for CalDavSource.
+ *
+ * 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"
+
+const serverUrl = prompt("CalDAV server URL:")
+const username = prompt("Username:")
+const password = prompt("Password:")
+const lookAheadRaw = prompt("Look-ahead days (default 0):")
+
+if (!serverUrl || !username || !password) {
+	console.error("Server URL, username, and password are required.")
+	process.exit(1)
+}
+
+const lookAheadDays = Number(lookAheadRaw) || 0
+
+const source = new CalDavSource({
+	serverUrl,
+	authMethod: "basic",
+	username,
+	password,
+	lookAheadDays,
+})
+
+const context = new Context()
+
+console.log(`\nFetching from ${serverUrl} as ${username} (lookAheadDays=${lookAheadDays})...\n`)
+
+const contextResult = await source.fetchContext(context)
+const items = await source.fetchItems(context)
+
+console.log("=== Context ===")
+console.log(JSON.stringify(contextResult, null, 2))
+
+console.log(`\n=== Feed Items (${items.length}) ===`)
+for (const item of items) {
+	console.log(`\n--- ${item.data.title} ---`)
+	console.log(`  ID:         ${item.id}`)
+	console.log(`  Calendar:   ${item.data.calendarName ?? "(unknown)"}`)
+	console.log(`  Start:      ${item.data.startDate.toISOString()}`)
+	console.log(`  End:        ${item.data.endDate.toISOString()}`)
+	console.log(`  All-day:    ${item.data.isAllDay}`)
+	console.log(`  Location:   ${item.data.location ?? "(none)"}`)
+	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(", ")}`)
+	}
+	if (item.data.description) {
+		console.log(`  Desc:       ${item.data.description.slice(0, 100)}`)
+	}
+}
+
+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

@@ -0,0 +1,537 @@
+import type { ContextEntry } from "@aris/core"
+
+import { Context, TimeRelevance } from "@aris/core"
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import type {
+	CalDavDAVCalendar,
+	CalDavDAVClient,
+	CalDavDAVObject,
+	CalDavEventData,
+} from "./types.ts"
+
+import { CalDavSource, computeSignals } from "./caldav-source.ts"
+import { CalDavCalendarKey, type CalendarContext } from "./calendar-context.ts"
+
+function loadFixture(name: string): string {
+	return readFileSync(join(import.meta.dir, "..", "fixtures", name), "utf-8")
+}
+
+function createContext(time: Date): Context {
+	return new Context(time)
+}
+
+/** Extract the CalendarContext value from fetchContext entries. */
+function extractCalendar(entries: readonly ContextEntry[] | null): CalendarContext | undefined {
+	if (!entries) return undefined
+	const entry = entries.find(([key]) => key === CalDavCalendarKey)
+	return entry?.[1] as CalendarContext | undefined
+}
+
+class MockDAVClient implements CalDavDAVClient {
+	credentials: Record<string, unknown> = {}
+	fetchCalendarsCallCount = 0
+	lastTimeRange: { start: string; end: string } | null = null
+	private calendars: CalDavDAVCalendar[]
+	private objectsByCalendarUrl: Record<string, CalDavDAVObject[]>
+
+	constructor(
+		calendars: CalDavDAVCalendar[],
+		objectsByCalendarUrl: Record<string, CalDavDAVObject[]>,
+	) {
+		this.calendars = calendars
+		this.objectsByCalendarUrl = objectsByCalendarUrl
+	}
+
+	async login(): Promise<void> {}
+
+	async fetchCalendars(): Promise<CalDavDAVCalendar[]> {
+		this.fetchCalendarsCallCount++
+		return this.calendars
+	}
+
+	async fetchCalendarObjects(params: {
+		calendar: CalDavDAVCalendar
+		timeRange: { start: string; end: string }
+	}): Promise<CalDavDAVObject[]> {
+		this.lastTimeRange = params.timeRange
+		return this.objectsByCalendarUrl[params.calendar.url] ?? []
+	}
+}
+
+function createSource(client: MockDAVClient, lookAheadDays?: number): CalDavSource {
+	return new CalDavSource({
+		serverUrl: "https://caldav.example.com",
+		authMethod: "basic",
+		username: "user",
+		password: "pass",
+		davClient: client,
+		lookAheadDays,
+	})
+}
+
+describe("CalDavSource", () => {
+	test("has correct id", () => {
+		const client = new MockDAVClient([], {})
+		const source = createSource(client)
+		expect(source.id).toBe("aris.caldav")
+	})
+
+	test("returns empty array when no calendars exist", async () => {
+		const client = new MockDAVClient([], {})
+		const source = createSource(client)
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		expect(items).toEqual([])
+	})
+
+	test("returns feed items from a single calendar", 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)
+		expect(items[0]!.type).toBe("caldav-event")
+		expect(items[0]!.id).toBe("caldav-event-single-event-001@test")
+		expect(items[0]!.data.title).toBe("Team Standup")
+		expect(items[0]!.data.location).toBe("Conference Room A")
+		expect(items[0]!.data.calendarName).toBe("Work")
+		expect(items[0]!.data.attendees).toHaveLength(2)
+		expect(items[0]!.data.alarms).toHaveLength(2)
+	})
+
+	test("returns feed items from multiple calendars", async () => {
+		const objects: Record<string, CalDavDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+			"/cal/personal": [
+				{
+					url: "/cal/personal/event2.ics",
+					data: loadFixture("all-day-event.ics"),
+				},
+			],
+		}
+		const client = new MockDAVClient(
+			[
+				{ url: "/cal/work", displayName: "Work" },
+				{ url: "/cal/personal", displayName: "Personal" },
+			],
+			objects,
+		)
+		const source = createSource(client)
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+
+		expect(items).toHaveLength(2)
+
+		const standup = items.find((i) => i.data.title === "Team Standup")
+		const holiday = items.find((i) => i.data.title === "Company Holiday")
+
+		expect(standup).toBeDefined()
+		expect(standup!.data.calendarName).toBe("Work")
+
+		expect(holiday).toBeDefined()
+		expect(holiday!.data.calendarName).toBe("Personal")
+		expect(holiday!.data.isAllDay).toBe(true)
+	})
+
+	test("skips objects with non-string data", async () => {
+		const objects: Record<string, CalDavDAVObject[]> = {
+			"/cal/work": [
+				{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
+				{ url: "/cal/work/bad.ics", data: 12345 },
+				{ url: "/cal/work/empty.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)
+		expect(items[0]!.data.title).toBe("Team Standup")
+	})
+
+	test("uses context time as feed item timestamp", 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 now = new Date("2026-01-15T12:00:00Z")
+		const items = await source.fetchItems(createContext(now))
+		expect(items[0]!.timestamp).toEqual(now)
+	})
+
+	test("assigns signals based on event proximity", async () => {
+		const objects: Record<string, CalDavDAVObject[]> = {
+			"/cal/work": [
+				{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
+				{ 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)
+
+		// 2 hours before the event at 14:00
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+
+		const standup = items.find((i) => i.data.title === "Team Standup")
+		const holiday = items.find((i) => i.data.title === "Company Holiday")
+
+		expect(standup!.signals!.urgency).toBe(0.7) // within 2 hours
+		expect(standup!.signals!.timeRelevance).toBe(TimeRelevance.Upcoming)
+		expect(holiday!.signals!.urgency).toBe(0.3) // all-day
+		expect(holiday!.signals!.timeRelevance).toBe(TimeRelevance.Ambient)
+	})
+
+	test("handles calendar with non-string displayName", async () => {
+		const objects: Record<string, CalDavDAVObject[]> = {
+			"/cal/weird": [
+				{
+					url: "/cal/weird/event1.ics",
+					data: loadFixture("minimal-event.ics"),
+				},
+			],
+		}
+		const client = new MockDAVClient(
+			[{ url: "/cal/weird", displayName: { _cdata: "Weird Calendar" } }],
+			objects,
+		)
+		const source = createSource(client)
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		expect(items[0]!.data.calendarName).toBeNull()
+	})
+
+	test("expands recurring events within the time 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=0 → range is Jan 15 only
+		const source = createSource(client)
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T08:00:00Z")))
+
+		// 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"))
+	})
+
+	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)")
+
+		// Jan 15 base occurrence
+		expect(base.length).toBeGreaterThanOrEqual(1)
+
+		// Jan 22 exception replaces the base occurrence
+		expect(exception).toBeDefined()
+		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 () => {
+		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 context = createContext(new Date("2026-01-15T12:00:00Z"))
+
+		await source.fetchContext(context)
+		await source.fetchItems(context)
+
+		// Same context.time reference — fetchEvents should only hit the client once
+		expect(client.fetchCalendarsCallCount).toBe(1)
+	})
+
+	test("uses timezone for time range when provided", 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)
+
+		// 2026-01-15T22:00:00Z = 2026-01-16T09:00:00 in Australia/Sydney (AEDT, UTC+11)
+		const source = new CalDavSource({
+			serverUrl: "https://caldav.example.com",
+			authMethod: "basic",
+			username: "user",
+			password: "pass",
+			davClient: client,
+			timeZone: "Australia/Sydney",
+		})
+
+		await source.fetchItems(createContext(new Date("2026-01-15T22:00:00Z")))
+
+		// "Today" in Sydney is Jan 16, so start should be Jan 15 13:00 UTC (midnight Jan 16 AEDT)
+		expect(client.lastTimeRange).not.toBeNull()
+		expect(client.lastTimeRange!.start).toBe("2026-01-15T13:00:00.000Z")
+		// End should be Jan 16 13:00 UTC (midnight Jan 17 AEDT) — 1 day window
+		expect(client.lastTimeRange!.end).toBe("2026-01-16T13:00:00.000Z")
+	})
+
+	test("defaults to UTC midnight when no timezone provided", 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)
+
+		await source.fetchItems(createContext(new Date("2026-01-15T22:00:00Z")))
+
+		expect(client.lastTimeRange).not.toBeNull()
+		expect(client.lastTimeRange!.start).toBe("2026-01-15T00:00:00.000Z")
+		expect(client.lastTimeRange!.end).toBe("2026-01-16T00:00:00.000Z")
+	})
+
+	test("refetches events for a different context time", 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)
+
+		await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		await source.fetchItems(createContext(new Date("2026-01-15T13:00:00Z")))
+
+		// Different context.time references — should fetch twice
+		expect(client.fetchCalendarsCallCount).toBe(2)
+	})
+})
+
+describe("CalDavSource.fetchContext", () => {
+	test("returns empty context when no calendars exist", async () => {
+		const client = new MockDAVClient([], {})
+		const source = createSource(client)
+		const entries = await source.fetchContext(createContext(new Date("2026-01-15T12:00:00Z")))
+		const calendar = extractCalendar(entries)
+
+		expect(calendar).toBeDefined()
+		expect(calendar!.inProgress).toEqual([])
+		expect(calendar!.nextEvent).toBeNull()
+		expect(calendar!.hasTodayEvents).toBe(false)
+		expect(calendar!.todayEventCount).toBe(0)
+	})
+
+	test("identifies in-progress events", 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)
+
+		// 14:30 is during the 14:00-15:00 event
+		const entries = await source.fetchContext(createContext(new Date("2026-01-15T14:30:00Z")))
+		const calendar = extractCalendar(entries)
+
+		expect(calendar!.inProgress).toHaveLength(1)
+		expect(calendar!.inProgress[0]!.title).toBe("Team Standup")
+	})
+
+	test("identifies next upcoming event", 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)
+
+		// 12:00 is before the 14:00 event
+		const entries = await source.fetchContext(createContext(new Date("2026-01-15T12:00:00Z")))
+		const calendar = extractCalendar(entries)
+
+		expect(calendar!.inProgress).toHaveLength(0)
+		expect(calendar!.nextEvent).not.toBeNull()
+		expect(calendar!.nextEvent!.title).toBe("Team Standup")
+	})
+
+	test("excludes all-day events from inProgress and nextEvent", 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 entries = await source.fetchContext(createContext(new Date("2026-01-15T12:00:00Z")))
+		const calendar = extractCalendar(entries)
+
+		expect(calendar!.inProgress).toHaveLength(0)
+		expect(calendar!.nextEvent).toBeNull()
+		expect(calendar!.hasTodayEvents).toBe(true)
+		expect(calendar!.todayEventCount).toBe(1)
+	})
+
+	test("counts all events including all-day in todayEventCount", async () => {
+		const objects: Record<string, CalDavDAVObject[]> = {
+			"/cal/work": [
+				{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
+				{ 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 entries = await source.fetchContext(createContext(new Date("2026-01-15T12:00:00Z")))
+		const calendar = extractCalendar(entries)
+
+		expect(calendar!.todayEventCount).toBe(2)
+		expect(calendar!.hasTodayEvents).toBe(true)
+	})
+})
+
+describe("computeSignals", () => {
+	const now = new Date("2026-01-15T12:00:00Z")
+
+	function makeEvent(overrides: Partial<CalDavEventData>): CalDavEventData {
+		return {
+			uid: "test-uid",
+			title: "Test",
+			startDate: new Date("2026-01-15T14:00:00Z"),
+			endDate: new Date("2026-01-15T15:00:00Z"),
+			isAllDay: false,
+			location: null,
+			description: null,
+			calendarName: null,
+			status: null,
+			url: null,
+			organizer: null,
+			attendees: [],
+			alarms: [],
+			recurrenceId: null,
+			...overrides,
+		}
+	}
+
+	test("all-day events get urgency 0.3 and ambient relevance", () => {
+		const event = makeEvent({ isAllDay: true })
+		const signals = computeSignals(event, now)
+		expect(signals.urgency).toBe(0.3)
+		expect(signals.timeRelevance).toBe(TimeRelevance.Ambient)
+	})
+
+	test("events starting within 30 minutes get urgency 0.9 and imminent relevance", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T12:20:00Z"),
+		})
+		const signals = computeSignals(event, now)
+		expect(signals.urgency).toBe(0.9)
+		expect(signals.timeRelevance).toBe(TimeRelevance.Imminent)
+	})
+
+	test("events starting exactly at 30 minutes get urgency 0.9", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T12:30:00Z"),
+		})
+		expect(computeSignals(event, now).urgency).toBe(0.9)
+	})
+
+	test("events starting within 2 hours get urgency 0.7 and upcoming relevance", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T13:00:00Z"),
+		})
+		const signals = computeSignals(event, now)
+		expect(signals.urgency).toBe(0.7)
+		expect(signals.timeRelevance).toBe(TimeRelevance.Upcoming)
+	})
+
+	test("events later today get urgency 0.5", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T20:00:00Z"),
+		})
+		expect(computeSignals(event, now).urgency).toBe(0.5)
+	})
+
+	test("in-progress events get urgency 0.8 and imminent relevance", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T11:00:00Z"),
+			endDate: new Date("2026-01-15T13:00:00Z"),
+		})
+		const signals = computeSignals(event, now)
+		expect(signals.urgency).toBe(0.8)
+		expect(signals.timeRelevance).toBe(TimeRelevance.Imminent)
+	})
+
+	test("fully past events get urgency 0.2 and ambient relevance", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T09:00:00Z"),
+			endDate: new Date("2026-01-15T10:00:00Z"),
+		})
+		const signals = computeSignals(event, now)
+		expect(signals.urgency).toBe(0.2)
+		expect(signals.timeRelevance).toBe(TimeRelevance.Ambient)
+	})
+
+	test("events on future days get urgency 0.2", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-16T10:00:00Z"),
+		})
+		expect(computeSignals(event, now).urgency).toBe(0.2)
+	})
+
+	test("urgency boundaries are correct", () => {
+		// 31 minutes from now should be 0.7 (within 2 hours, not within 30 min)
+		const event31min = makeEvent({
+			startDate: new Date("2026-01-15T12:31:00Z"),
+		})
+		expect(computeSignals(event31min, now).urgency).toBe(0.7)
+
+		// 2 hours 1 minute from now should be 0.5 (later today, not within 2 hours)
+		const event2h1m = makeEvent({
+			startDate: new Date("2026-01-15T14:01:00Z"),
+		})
+		expect(computeSignals(event2h1m, now).urgency).toBe(0.5)
+	})
+
+	test("cancelled events get urgency 0.1 regardless of timing", () => {
+		const event = makeEvent({
+			status: "cancelled",
+			startDate: new Date("2026-01-15T12:20:00Z"), // would be 0.9 if not cancelled
+		})
+		const signals = computeSignals(event, now)
+		expect(signals.urgency).toBe(0.1)
+		expect(signals.timeRelevance).toBe(TimeRelevance.Ambient)
+	})
+
+	test("uses timezone for 'later today' boundary", () => {
+		// now = 2026-01-15T12:00:00Z = 2026-01-15T21:00:00 JST (UTC+9)
+		// event at 2026-01-15T15:30:00Z = 2026-01-16T00:30:00 JST — next day in JST
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T15:30:00Z"),
+		})
+
+		// Without timezone: UTC day ends at 2026-01-16T00:00:00Z, event is before that → "later today"
+		expect(computeSignals(event, now).urgency).toBe(0.5)
+
+		// With Asia/Tokyo: local day ends at 2026-01-15T15:00:00Z (midnight Jan 16 JST),
+		// event is after that → "future days"
+		expect(computeSignals(event, now, "Asia/Tokyo").urgency).toBe(0.2)
+	})
+})
+
+

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

@@ -0,0 +1,351 @@
+import type { ActionDefinition, ContextEntry, FeedItemSignals, FeedSource } from "@aris/core"
+
+import { Context, TimeRelevance, UnknownActionError } from "@aris/core"
+import { DAVClient } from "tsdav"
+
+import type { CalDavDAVClient, CalDavEventData, CalDavFeedItem } from "./types.ts"
+
+import { CalDavCalendarKey, type CalendarContext } from "./calendar-context.ts"
+import { parseICalEvents } from "./ical-parser.ts"
+import { CalDavEventStatus, CalDavFeedItemType } from "./types.ts"
+
+// -- Source options --
+
+interface CalDavSourceBaseOptions {
+	serverUrl: string
+	/** Number of additional days beyond today to fetch. Default: 0 (today only). */
+	lookAheadDays?: number
+	/** IANA timezone for determining "today" (e.g. "America/New_York"). Default: UTC. */
+	timeZone?: string
+	/** Optional DAV client for testing. */
+	davClient?: CalDavDAVClient
+}
+
+interface CalDavSourceBasicAuthOptions extends CalDavSourceBaseOptions {
+	authMethod: "basic"
+	username: string
+	password: string
+}
+
+interface CalDavSourceOAuthOptions extends CalDavSourceBaseOptions {
+	authMethod: "oauth"
+	accessToken: string
+	refreshToken: string
+	tokenUrl: string
+	expiration?: number
+	clientId?: string
+	clientSecret?: string
+}
+
+export type CalDavSourceOptions = CalDavSourceBasicAuthOptions | CalDavSourceOAuthOptions
+
+const DEFAULT_LOOK_AHEAD_DAYS = 0
+
+/**
+ * A FeedSource that fetches calendar events from any CalDAV server.
+ *
+ * Supports Basic auth (username/password) and OAuth (access token + refresh token).
+ * The server URL is provided at construction time.
+ *
+ * @example
+ * ```ts
+ * // Basic auth (self-hosted servers)
+ * const source = new CalDavSource({
+ *   serverUrl: "https://nextcloud.example.com/remote.php/dav",
+ *   authMethod: "basic",
+ *   username: "user",
+ *   password: "pass",
+ * })
+ *
+ * // OAuth (cloud providers)
+ * const source = new CalDavSource({
+ *   serverUrl: "https://caldav.provider.com",
+ *   authMethod: "oauth",
+ *   accessToken: "...",
+ *   refreshToken: "...",
+ *   tokenUrl: "https://provider.com/oauth/token",
+ * })
+ * ```
+ */
+export class CalDavSource implements FeedSource<CalDavFeedItem> {
+	readonly id = "aris.caldav"
+
+	private options: CalDavSourceOptions | null
+	private readonly lookAheadDays: number
+	private readonly timeZone: string | undefined
+	private readonly injectedClient: CalDavDAVClient | null
+	private clientPromise: Promise<CalDavDAVClient> | null = null
+	private cachedEvents: { time: Date; events: CalDavEventData[] } | null = null
+	private pendingFetch: { time: Date; promise: Promise<CalDavEventData[]> } | null = null
+
+	constructor(options: CalDavSourceOptions) {
+		this.options = options
+		this.lookAheadDays = options.lookAheadDays ?? DEFAULT_LOOK_AHEAD_DAYS
+		this.timeZone = options.timeZone
+		this.injectedClient = options.davClient ?? null
+	}
+
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {}
+	}
+
+	async executeAction(actionId: string): Promise<void> {
+		throw new UnknownActionError(actionId)
+	}
+
+	async fetchContext(context: Context): Promise<readonly ContextEntry[] | null> {
+		const events = await this.fetchEvents(context)
+		if (events.length === 0) {
+			return [
+				[
+					CalDavCalendarKey,
+					{
+						inProgress: [],
+						nextEvent: null,
+						hasTodayEvents: false,
+						todayEventCount: 0,
+					},
+				],
+			]
+		}
+
+		const now = context.time
+		const active = events.filter((e) => e.status !== CalDavEventStatus.Cancelled)
+		const inProgress = active.filter((e) => !e.isAllDay && e.startDate <= now && e.endDate > now)
+
+		const upcoming = active
+			.filter((e) => !e.isAllDay && e.startDate > now)
+			.sort((a, b) => a.startDate.getTime() - b.startDate.getTime())
+
+		const calendarContext: CalendarContext = {
+			inProgress,
+			nextEvent: upcoming[0] ?? null,
+			hasTodayEvents: events.length > 0,
+			todayEventCount: events.length,
+		}
+
+		return [[CalDavCalendarKey, calendarContext]]
+	}
+
+	async fetchItems(context: Context): Promise<CalDavFeedItem[]> {
+		const now = context.time
+		const events = await this.fetchEvents(context)
+		return events.map((event) => createFeedItem(event, now, this.timeZone))
+	}
+
+	private fetchEvents(context: Context): Promise<CalDavEventData[]> {
+		if (this.cachedEvents && this.cachedEvents.time === context.time) {
+			return Promise.resolve(this.cachedEvents.events)
+		}
+
+		// Deduplicate concurrent fetches for the same context.time reference
+		if (this.pendingFetch && this.pendingFetch.time === context.time) {
+			return this.pendingFetch.promise
+		}
+
+		const promise = this.doFetchEvents(context).finally(() => {
+			if (this.pendingFetch?.promise === promise) {
+				this.pendingFetch = null
+			}
+		})
+
+		this.pendingFetch = { time: context.time, promise }
+		return promise
+	}
+
+	private async doFetchEvents(context: Context): Promise<CalDavEventData[]> {
+		const client = await this.connectClient()
+		const calendars = await client.fetchCalendars()
+
+		const { start, end } = computeTimeRange(context.time, this.lookAheadDays, this.timeZone)
+
+		const results = await Promise.allSettled(
+			calendars.map(async (calendar) => {
+				const objects = await client.fetchCalendarObjects({
+					calendar,
+					timeRange: {
+						start: start.toISOString(),
+						end: end.toISOString(),
+					},
+				})
+				// tsdav types displayName as string | Record<string, unknown> | undefined
+				const calendarName = typeof calendar.displayName === "string" ? calendar.displayName : null
+				return { objects, calendarName }
+			}),
+		)
+
+		const allEvents: CalDavEventData[] = []
+		for (const result of results) {
+			if (result.status === "rejected") {
+				console.warn("[aris.caldav] Failed to fetch calendar:", result.reason)
+				continue
+			}
+			const { objects, calendarName } = result.value
+			for (const obj of objects) {
+				if (typeof obj.data !== "string") continue
+
+				const events = parseICalEvents(obj.data, calendarName, { start, end })
+				for (const event of events) {
+					allEvents.push(event)
+				}
+			}
+		}
+
+		this.cachedEvents = { time: context.time, events: allEvents }
+		return allEvents
+	}
+
+	private connectClient(): Promise<CalDavDAVClient> {
+		if (this.injectedClient) {
+			return Promise.resolve(this.injectedClient)
+		}
+
+		if (!this.clientPromise) {
+			this.clientPromise = this.createAndLoginClient().catch((err) => {
+				this.clientPromise = null
+				throw err
+			})
+		}
+
+		return this.clientPromise
+	}
+
+	private async createAndLoginClient(): Promise<CalDavDAVClient> {
+		const opts = this.options
+		if (!opts) {
+			throw new Error("CalDavSource options have already been consumed")
+		}
+
+		let client: CalDavDAVClient
+
+		if (opts.authMethod === "basic") {
+			client = new DAVClient({
+				serverUrl: opts.serverUrl,
+				credentials: {
+					username: opts.username,
+					password: opts.password,
+				},
+				authMethod: "Basic",
+				defaultAccountType: "caldav",
+			})
+		} else {
+			client = new DAVClient({
+				serverUrl: opts.serverUrl,
+				credentials: {
+					tokenUrl: opts.tokenUrl,
+					refreshToken: opts.refreshToken,
+					accessToken: opts.accessToken,
+					expiration: opts.expiration,
+					clientId: opts.clientId,
+					clientSecret: opts.clientSecret,
+				},
+				authMethod: "Oauth",
+				defaultAccountType: "caldav",
+			})
+		}
+
+		await client.login()
+		this.options = null
+		return client
+	}
+}
+
+function computeTimeRange(
+	now: Date,
+	lookAheadDays: number,
+	timeZone?: string,
+): { start: Date; end: Date } {
+	const start = startOfDay(now, timeZone)
+	const end = new Date(start.getTime() + (1 + lookAheadDays) * 24 * 60 * 60 * 1000)
+	return { start, end }
+}
+
+/**
+ * Returns midnight (start of day) as a UTC Date.
+ * When timeZone is provided, "midnight" is local midnight in that timezone
+ * converted to UTC. Otherwise, UTC midnight.
+ */
+function startOfDay(date: Date, timeZone?: string): Date {
+	if (!timeZone) {
+		const d = new Date(date)
+		d.setUTCHours(0, 0, 0, 0)
+		return d
+	}
+
+	// Extract the local year/month/day in the target timezone
+	const parts = new Intl.DateTimeFormat("en-CA", {
+		timeZone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+	}).formatToParts(date)
+
+	const year = Number(parts.find((p) => p.type === "year")!.value)
+	const month = Number(parts.find((p) => p.type === "month")!.value)
+	const day = Number(parts.find((p) => p.type === "day")!.value)
+
+	// Binary-search-free approach: construct a UTC date at the local date's noon,
+	// then use the timezone offset at that moment to find local midnight in UTC.
+	const noonUtc = Date.UTC(year, month - 1, day, 12, 0, 0)
+	const noonLocal = new Date(noonUtc).toLocaleString("sv-SE", { timeZone, hour12: false })
+	// sv-SE locale formats as "YYYY-MM-DD HH:MM:SS" which Date can parse
+	const noonLocalMs = new Date(noonLocal + "Z").getTime()
+	const offsetMs = noonLocalMs - noonUtc
+
+	return new Date(Date.UTC(year, month - 1, day) - offsetMs)
+}
+
+export function computeSignals(
+	event: CalDavEventData,
+	now: Date,
+	timeZone?: string,
+): FeedItemSignals {
+	if (event.status === CalDavEventStatus.Cancelled) {
+		return { urgency: 0.1, timeRelevance: TimeRelevance.Ambient }
+	}
+
+	if (event.isAllDay) {
+		return { urgency: 0.3, timeRelevance: TimeRelevance.Ambient }
+	}
+
+	const msUntilStart = event.startDate.getTime() - now.getTime()
+
+	// Event already started
+	if (msUntilStart < 0) {
+		const isInProgress = now.getTime() < event.endDate.getTime()
+		return isInProgress
+			? { urgency: 0.8, timeRelevance: TimeRelevance.Imminent }
+			: { urgency: 0.2, timeRelevance: TimeRelevance.Ambient }
+	}
+
+	// Starting within 30 minutes
+	if (msUntilStart <= 30 * 60 * 1000) {
+		return { urgency: 0.9, timeRelevance: TimeRelevance.Imminent }
+	}
+
+	// Starting within 2 hours
+	if (msUntilStart <= 2 * 60 * 60 * 1000) {
+		return { urgency: 0.7, timeRelevance: TimeRelevance.Upcoming }
+	}
+
+	// Later today (using local day boundary when timeZone is set)
+	const todayStart = startOfDay(now, timeZone)
+	const endOfDay = new Date(todayStart.getTime() + 24 * 60 * 60 * 1000)
+
+	if (event.startDate.getTime() < endOfDay.getTime()) {
+		return { urgency: 0.5, timeRelevance: TimeRelevance.Upcoming }
+	}
+
+	// Future days
+	return { urgency: 0.2, timeRelevance: TimeRelevance.Ambient }
+}
+
+function createFeedItem(event: CalDavEventData, now: Date, timeZone?: string): CalDavFeedItem {
+	return {
+		id: `caldav-event-${event.uid}${event.recurrenceId ? `-${event.recurrenceId}` : ""}`,
+		type: CalDavFeedItemType.Event,
+		timestamp: now,
+		data: event,
+		signals: computeSignals(event, now, timeZone),
+	}
+}

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

@@ -0,0 +1,24 @@
+import type { ContextKey } from "@aris/core"
+
+import { contextKey } from "@aris/core"
+
+import type { CalDavEventData } from "./types.ts"
+
+/**
+ * Calendar context for downstream sources.
+ *
+ * Provides a snapshot of the user's upcoming CalDAV events so other sources
+ * can adapt (e.g. a commute source checking if there's a meeting soon).
+ */
+export interface CalendarContext {
+	/** Events happening right now */
+	inProgress: CalDavEventData[]
+	/** Next upcoming event, if any */
+	nextEvent: CalDavEventData | null
+	/** Whether the user has any events today */
+	hasTodayEvents: boolean
+	/** Total number of events today */
+	todayEventCount: number
+}
+
+export const CalDavCalendarKey: ContextKey<CalendarContext> = contextKey("aris.caldav", "calendar")

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

@@ -0,0 +1,198 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { parseICalEvents } from "./ical-parser.ts"
+
+function loadFixture(name: string): string {
+	return readFileSync(join(import.meta.dir, "..", "fixtures", name), "utf-8")
+}
+
+describe("parseICalEvents", () => {
+	test("parses a full event with all fields", () => {
+		const events = parseICalEvents(loadFixture("single-event.ics"), "Work")
+
+		expect(events).toHaveLength(1)
+		const event = events[0]!
+
+		expect(event.uid).toBe("single-event-001@test")
+		expect(event.title).toBe("Team Standup")
+		expect(event.startDate).toEqual(new Date("2026-01-15T14:00:00Z"))
+		expect(event.endDate).toEqual(new Date("2026-01-15T15:00:00Z"))
+		expect(event.isAllDay).toBe(false)
+		expect(event.location).toBe("Conference Room A")
+		expect(event.description).toBe("Daily standup meeting")
+		expect(event.calendarName).toBe("Work")
+		expect(event.status).toBe("confirmed")
+		expect(event.url).toBe("https://example.com/meeting/123")
+		expect(event.organizer).toBe("Alice Smith")
+		expect(event.recurrenceId).toBeNull()
+
+		expect(event.attendees).toHaveLength(2)
+		expect(event.attendees[0]).toEqual({
+			name: "Bob Jones",
+			email: "bob@example.com",
+			role: "required",
+			status: "accepted",
+		})
+		expect(event.attendees[1]).toEqual({
+			name: "Carol White",
+			email: "carol@example.com",
+			role: "optional",
+			status: "tentative",
+		})
+
+		expect(event.alarms).toHaveLength(2)
+		expect(event.alarms[0]).toEqual({ trigger: "-PT15M", action: "DISPLAY" })
+		expect(event.alarms[1]).toEqual({ trigger: "-PT5M", action: "AUDIO" })
+	})
+
+	test("parses an all-day event with optional fields as null", () => {
+		const events = parseICalEvents(loadFixture("all-day-event.ics"), null)
+
+		expect(events).toHaveLength(1)
+		const event = events[0]!
+
+		expect(event.isAllDay).toBe(true)
+		expect(event.title).toBe("Company Holiday")
+		expect(event.calendarName).toBeNull()
+		expect(event.location).toBeNull()
+		expect(event.description).toBeNull()
+		expect(event.url).toBeNull()
+		expect(event.organizer).toBeNull()
+		expect(event.attendees).toEqual([])
+		expect(event.alarms).toEqual([])
+	})
+
+	test("parses recurring event with exception", () => {
+		const events = parseICalEvents(loadFixture("recurring-event.ics"), "Team")
+
+		expect(events).toHaveLength(2)
+		expect(events[0]!.uid).toBe("recurring-001@test")
+		expect(events[1]!.uid).toBe("recurring-001@test")
+
+		const base = events.find((e) => e.title === "Weekly Sync")
+		expect(base).toBeDefined()
+		expect(base!.recurrenceId).toBeNull()
+
+		const exception = events.find((e) => e.title === "Weekly Sync (moved)")
+		expect(exception).toBeDefined()
+		expect(exception!.recurrenceId).not.toBeNull()
+	})
+
+	test("parses minimal event with defaults", () => {
+		const events = parseICalEvents(loadFixture("minimal-event.ics"), null)
+
+		expect(events).toHaveLength(1)
+		const event = events[0]!
+
+		expect(event.uid).toBe("minimal-001@test")
+		expect(event.title).toBe("Quick Chat")
+		expect(event.startDate).toEqual(new Date("2026-01-15T18:00:00Z"))
+		expect(event.endDate).toEqual(new Date("2026-01-15T19:00:00Z"))
+		expect(event.location).toBeNull()
+		expect(event.description).toBeNull()
+		expect(event.status).toBeNull()
+		expect(event.url).toBeNull()
+		expect(event.organizer).toBeNull()
+		expect(event.attendees).toEqual([])
+		expect(event.alarms).toEqual([])
+		expect(event.recurrenceId).toBeNull()
+	})
+
+	test("parses cancelled status", () => {
+		const events = parseICalEvents(loadFixture("cancelled-event.ics"), null)
+		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

@@ -0,0 +1,323 @@
+import ICAL from "ical.js"
+
+import {
+	AttendeeRole,
+	AttendeeStatus,
+	CalDavEventStatus,
+	type CalDavAlarm,
+	type CalDavAttendee,
+	type CalDavEventData,
+} from "./types.ts"
+
+export interface ICalTimeRange {
+	start: Date
+	end: Date
+}
+
+/**
+ * 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,
+	timeRange?: ICalTimeRange,
+): CalDavEventData[] {
+	const jcal = ICAL.parse(icsData)
+	const comp = new ICAL.Component(jcal)
+	const vevents = comp.getAllSubcomponents("vevent")
+
+	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(
+	vevent: InstanceType<typeof ICAL.Component>,
+	calendarName: string | null,
+): CalDavEventData {
+	const event = new ICAL.Event(vevent)
+
+	return {
+		uid: event.uid ?? "",
+		title: event.summary ?? "",
+		startDate: event.startDate?.toJSDate() ?? new Date(0),
+		endDate: event.endDate?.toJSDate() ?? new Date(0),
+		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: event.recurrenceId ? event.recurrenceId.toString() : null,
+	}
+}
+
+function parseStatus(raw: string | null): CalDavEventStatus | null {
+	if (!raw) return null
+	switch (raw.toLowerCase()) {
+		case "confirmed":
+			return CalDavEventStatus.Confirmed
+		case "tentative":
+			return CalDavEventStatus.Tentative
+		case "cancelled":
+			return CalDavEventStatus.Cancelled
+		default:
+			return null
+	}
+}
+
+function parseOrganizer(
+	value: string | null,
+	vevent: InstanceType<typeof ICAL.Component>,
+): string | null {
+	if (!value) return null
+
+	// Try CN parameter first
+	const prop = vevent.getFirstProperty("organizer")
+	if (prop) {
+		const cn = prop.getParameter("cn") as string | undefined
+		if (cn) return cn
+	}
+
+	// Fall back to mailto: value
+	return value.replace(/^mailto:/i, "")
+}
+
+function parseAttendees(properties: unknown[]): CalDavAttendee[] {
+	if (properties.length === 0) return []
+
+	return properties.flatMap((prop) => {
+		if (!prop || typeof prop !== "object" || !("getFirstValue" in prop)) return []
+		const p = prop as InstanceType<typeof ICAL.Property>
+		const value = asStringOrNull(p.getFirstValue())
+		const cn = asStringOrNull(p.getParameter("cn"))
+		const role = asStringOrNull(p.getParameter("role"))
+		const partstat = asStringOrNull(p.getParameter("partstat"))
+
+		return [
+			{
+				name: cn,
+				email: value ? value.replace(/^mailto:/i, "") : null,
+				role: parseAttendeeRole(role),
+				status: parseAttendeeStatus(partstat),
+			},
+		]
+	})
+}
+
+function parseAttendeeRole(raw: string | null): AttendeeRole | null {
+	if (!raw) return null
+	switch (raw.toUpperCase()) {
+		case "CHAIR":
+			return AttendeeRole.Chair
+		case "REQ-PARTICIPANT":
+			return AttendeeRole.Required
+		case "OPT-PARTICIPANT":
+			return AttendeeRole.Optional
+		default:
+			return null
+	}
+}
+
+function parseAttendeeStatus(raw: string | null): AttendeeStatus | null {
+	if (!raw) return null
+	switch (raw.toUpperCase()) {
+		case "ACCEPTED":
+			return AttendeeStatus.Accepted
+		case "DECLINED":
+			return AttendeeStatus.Declined
+		case "TENTATIVE":
+			return AttendeeStatus.Tentative
+		case "NEEDS-ACTION":
+			return AttendeeStatus.NeedsAction
+		default:
+			return null
+	}
+}
+
+function parseAlarms(vevent: InstanceType<typeof ICAL.Component>): CalDavAlarm[] {
+	const valarms = vevent.getAllSubcomponents("valarm")
+	if (!valarms || valarms.length === 0) return []
+
+	return valarms.map((valarm: InstanceType<typeof ICAL.Component>) => {
+		const trigger = valarm.getFirstPropertyValue("trigger")
+		const action = asStringOrNull(valarm.getFirstPropertyValue("action"))
+
+		return {
+			trigger: trigger ? trigger.toString() : "",
+			action: action ?? "DISPLAY",
+		}
+	})
+}
+
+function asStringOrNull(value: unknown): string | null {
+	return typeof value === "string" ? value : null
+}

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

@@ -0,0 +1,16 @@
+export { CalDavCalendarKey, type CalendarContext } from "./calendar-context.ts"
+export { CalDavSource, type CalDavSourceOptions } from "./caldav-source.ts"
+export { parseICalEvents, type ICalTimeRange } from "./ical-parser.ts"
+export {
+	AttendeeRole,
+	AttendeeStatus,
+	CalDavEventStatus,
+	CalDavFeedItemType,
+	type CalDavAlarm,
+	type CalDavAttendee,
+	type CalDavDAVCalendar,
+	type CalDavDAVClient,
+	type CalDavDAVObject,
+	type CalDavEventData,
+	type CalDavFeedItem,
+} from "./types.ts"

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

@@ -0,0 +1,101 @@
+import type { FeedItem } from "@aris/core"
+
+// -- Event status --
+
+export const CalDavEventStatus = {
+	Confirmed: "confirmed",
+	Tentative: "tentative",
+	Cancelled: "cancelled",
+} as const
+
+export type CalDavEventStatus = (typeof CalDavEventStatus)[keyof typeof CalDavEventStatus]
+
+// -- Attendee types --
+
+export const AttendeeRole = {
+	Chair: "chair",
+	Required: "required",
+	Optional: "optional",
+} as const
+
+export type AttendeeRole = (typeof AttendeeRole)[keyof typeof AttendeeRole]
+
+export const AttendeeStatus = {
+	Accepted: "accepted",
+	Declined: "declined",
+	Tentative: "tentative",
+	NeedsAction: "needs-action",
+} as const
+
+export type AttendeeStatus = (typeof AttendeeStatus)[keyof typeof AttendeeStatus]
+
+export interface CalDavAttendee {
+	name: string | null
+	email: string | null
+	role: AttendeeRole | null
+	status: AttendeeStatus | null
+}
+
+// -- Alarm --
+
+export interface CalDavAlarm {
+	/** ISO 8601 duration relative to event start, e.g. "-PT15M" */
+	trigger: string
+	/** e.g. "DISPLAY", "AUDIO" */
+	action: string
+}
+
+// -- Event data --
+
+export interface CalDavEventData extends Record<string, unknown> {
+	uid: string
+	title: string
+	startDate: Date
+	endDate: Date
+	isAllDay: boolean
+	location: string | null
+	description: string | null
+	calendarName: string | null
+	status: CalDavEventStatus | null
+	url: string | null
+	organizer: string | null
+	attendees: CalDavAttendee[]
+	alarms: CalDavAlarm[]
+	recurrenceId: string | null
+}
+
+// -- Feed item type --
+
+export const CalDavFeedItemType = {
+	Event: "caldav-event",
+} as const
+
+export type CalDavFeedItemType = (typeof CalDavFeedItemType)[keyof typeof CalDavFeedItemType]
+
+// -- Feed item --
+
+export type CalDavFeedItem = FeedItem<typeof CalDavFeedItemType.Event, CalDavEventData>
+
+// -- DAV client interface --
+
+export interface CalDavDAVObject {
+	data?: unknown
+	etag?: string
+	url: string
+}
+
+export interface CalDavDAVCalendar {
+	displayName?: string | Record<string, unknown>
+	url: string
+}
+
+/** Subset of tsdav's DAVClient used by CalDavSource. */
+export interface CalDavDAVClient {
+	login(): Promise<void>
+	fetchCalendars(): Promise<CalDavDAVCalendar[]>
+	fetchCalendarObjects(params: {
+		calendar: CalDavDAVCalendar
+		timeRange: { start: string; end: string }
+	}): Promise<CalDavDAVObject[]>
+	credentials: Record<string, unknown>
+}

packages/aris-source-google-calendar/src/calendar-context.ts

@@ -10,4 +10,4 @@ export interface NextEvent {
 	location: string | null
 }
 
-export const NextEventKey: ContextKey<NextEvent> = contextKey("nextEvent")
+export const NextEventKey: ContextKey<NextEvent> = contextKey("aris.google-calendar", "nextEvent")

packages/aris-source-google-calendar/src/feed-items.ts

@@ -3,19 +3,19 @@ import type { FeedItem } from "@aris/core"
 import type { CalendarEventData } from "./types"
 
 export const CalendarFeedItemType = {
-	event: "calendar-event",
-	allDay: "calendar-all-day",
+	Event: "calendar-event",
+	AllDay: "calendar-all-day",
 } as const
 
 export type CalendarFeedItemType = (typeof CalendarFeedItemType)[keyof typeof CalendarFeedItemType]
 
 export interface CalendarEventFeedItem extends FeedItem<
-	typeof CalendarFeedItemType.event,
+	typeof CalendarFeedItemType.Event,
 	CalendarEventData
 > {}
 
 export interface CalendarAllDayFeedItem extends FeedItem<
-	typeof CalendarFeedItemType.allDay,
+	typeof CalendarFeedItemType.AllDay,
 	CalendarEventData
 > {}
 

packages/aris-source-google-calendar/src/google-calendar-source.test.ts

@@ -1,10 +1,10 @@
-import { TimeRelevance, contextValue, type Context } from "@aris/core"
+import { Context, TimeRelevance } from "@aris/core"
 import { describe, expect, test } from "bun:test"
 
 import type { ApiCalendarEvent, GoogleCalendarClient, ListEventsOptions } from "./types"
 
 import fixture from "../fixtures/events.json"
-import { NextEventKey } from "./calendar-context"
+import { NextEventKey, type NextEvent } from "./calendar-context"
 import { CalendarFeedItemType } from "./feed-items"
 import { GoogleCalendarSource } from "./google-calendar-source"
 
@@ -38,7 +38,7 @@ function defaultMockClient(): GoogleCalendarClient {
 }
 
 function createContext(time?: Date): Context {
-	return { time: time ?? NOW }
+	return new Context(time ?? NOW)
 }
 
 describe("GoogleCalendarSource", () => {
@@ -69,7 +69,7 @@ describe("GoogleCalendarSource", () => {
 			const source = new GoogleCalendarSource({ client: defaultMockClient() })
 			const items = await source.fetchItems(createContext())
 
-			const timedItems = items.filter((i) => i.type === CalendarFeedItemType.event)
+			const timedItems = items.filter((i) => i.type === CalendarFeedItemType.Event)
 			expect(timedItems.length).toBe(4)
 		})
 
@@ -77,7 +77,7 @@ describe("GoogleCalendarSource", () => {
 			const source = new GoogleCalendarSource({ client: defaultMockClient() })
 			const items = await source.fetchItems(createContext())
 
-			const allDayItems = items.filter((i) => i.type === CalendarFeedItemType.allDay)
+			const allDayItems = items.filter((i) => i.type === CalendarFeedItemType.AllDay)
 			expect(allDayItems.length).toBe(1)
 		})
 
@@ -229,15 +229,16 @@ describe("GoogleCalendarSource", () => {
 
 		test("returns next upcoming timed event (not ongoing)", async () => {
 			const source = new GoogleCalendarSource({ client: defaultMockClient() })
-			const result = await source.fetchContext(createContext())
+			const entries = await source.fetchContext(createContext())
 
-			expect(result).not.toBeNull()
-			const nextEvent = contextValue(result! as Context, NextEventKey)
-			expect(nextEvent).toBeDefined()
+			expect(entries).not.toBeNull()
+			expect(entries).toHaveLength(1)
+			const [key, nextEvent] = entries![0]! as [typeof NextEventKey, NextEvent]
+			expect(key).toEqual(NextEventKey)
 			// evt-soon starts at 10:10, which is the nearest future timed event
-			expect(nextEvent!.title).toBe("1:1 with Manager")
-			expect(nextEvent!.minutesUntilStart).toBe(10)
-			expect(nextEvent!.location).toBeNull()
+			expect(nextEvent.title).toBe("1:1 with Manager")
+			expect(nextEvent.minutesUntilStart).toBe(10)
+			expect(nextEvent.location).toBeNull()
 		})
 
 		test("includes location when available", async () => {
@@ -255,12 +256,11 @@ describe("GoogleCalendarSource", () => {
 			const source = new GoogleCalendarSource({
 				client: createMockClient({ primary: events }),
 			})
-			const result = await source.fetchContext(createContext())
+			const entries = await source.fetchContext(createContext())
 
-			expect(result).not.toBeNull()
-			const nextEvent = contextValue(result! as Context, NextEventKey)
-			expect(nextEvent).toBeDefined()
-			expect(nextEvent!.location).toBe("123 Main St")
+			expect(entries).not.toBeNull()
+			const [, nextEvent] = entries![0]! as [typeof NextEventKey, NextEvent]
+			expect(nextEvent.location).toBe("123 Main St")
 		})
 
 		test("skips ongoing events for next-event context", async () => {

packages/aris-source-google-calendar/src/google-calendar-source.ts

@@ -1,6 +1,6 @@
-import type { ActionDefinition, Context, FeedItemSignals, FeedSource } from "@aris/core"
+import type { ActionDefinition, ContextEntry, FeedItemSignals, FeedSource } from "@aris/core"
 
-import { TimeRelevance, UnknownActionError } from "@aris/core"
+import { Context, TimeRelevance, UnknownActionError } from "@aris/core"
 
 import type {
 	ApiCalendarEvent,
@@ -58,7 +58,7 @@ const URGENCY_ALL_DAY = 0.4
  *   .register(calendarSource)
  *
  * // Access next-event context in downstream sources
- * const next = contextValue(context, NextEventKey)
+ * const next = context.get(NextEventKey)
  * if (next && next.minutesUntilStart < 15) {
  *   // remind user
  * }
@@ -85,7 +85,7 @@ export class GoogleCalendarSource implements FeedSource<CalendarFeedItem> {
 		throw new UnknownActionError(actionId)
 	}
 
-	async fetchContext(context: Context): Promise<Partial<Context> | null> {
+	async fetchContext(context: Context): Promise<readonly ContextEntry[] | null> {
 		const events = await this.fetchAllEvents(context.time)
 
 		const now = context.time.getTime()
@@ -105,7 +105,7 @@ export class GoogleCalendarSource implements FeedSource<CalendarFeedItem> {
 			location: nextTimedEvent.location,
 		}
 
-		return { [NextEventKey]: nextEvent }
+		return [[NextEventKey, nextEvent]]
 	}
 
 	async fetchItems(context: Context): Promise<CalendarFeedItem[]> {
@@ -209,7 +209,7 @@ function createFeedItem(
 	nowMs: number,
 	lookaheadMs: number,
 ): CalendarFeedItem {
-	const itemType = event.isAllDay ? CalendarFeedItemType.allDay : CalendarFeedItemType.event
+	const itemType = event.isAllDay ? CalendarFeedItemType.AllDay : CalendarFeedItemType.Event
 
 	return {
 		id: `calendar-${event.calendarId}-${event.eventId}`,

packages/aris-source-google-calendar/src/index.ts

@@ -1,7 +1,6 @@
 export { NextEventKey, type NextEvent } from "./calendar-context"
 export {
 	CalendarFeedItemType,
-	type CalendarFeedItemType as CalendarFeedItemTypeType,
 	type CalendarAllDayFeedItem,
 	type CalendarEventFeedItem,
 	type CalendarFeedItem,
@@ -10,7 +9,6 @@ export { DefaultGoogleCalendarClient } from "./google-calendar-api"
 export { GoogleCalendarSource, type GoogleCalendarSourceOptions } from "./google-calendar-source"
 export {
 	EventStatus,
-	type EventStatus as EventStatusType,
 	type ApiCalendarEvent,
 	type ApiEventDateTime,
 	type CalendarEventData,

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

@@ -1,6 +1,8 @@
 import { describe, expect, mock, test } from "bun:test"
 
-import { LocationKey, LocationSource, type Location } from "./location-source.ts"
+import type { Location } from "./types.ts"
+
+import { LocationKey, LocationSource } from "./location-source.ts"
 
 function createLocation(overrides: Partial<Location> = {}): Location {
 	return {
@@ -39,8 +41,8 @@ describe("LocationSource", () => {
 			const location = createLocation()
 			source.pushLocation(location)
 
-			const context = await source.fetchContext()
-			expect(context).toEqual({ [LocationKey]: location })
+			const entries = await source.fetchContext()
+			expect(entries).toEqual([[LocationKey, location]])
 		})
 	})
 
@@ -65,7 +67,7 @@ describe("LocationSource", () => {
 			source.pushLocation(location)
 
 			expect(listener).toHaveBeenCalledTimes(1)
-			expect(listener).toHaveBeenCalledWith({ [LocationKey]: location })
+			expect(listener).toHaveBeenCalledWith([[LocationKey, location]])
 		})
 	})
 

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

@@ -1,11 +1,11 @@
-import type { ActionDefinition, Context, FeedSource } from "@aris/core"
+import type { ActionDefinition, ContextEntry, FeedSource } from "@aris/core"
 
-import { UnknownActionError, contextKey, type ContextKey } from "@aris/core"
+import { Context, UnknownActionError, contextKey, type ContextKey } from "@aris/core"
 import { type } from "arktype"
 
 import { Location, type LocationSourceOptions } from "./types.ts"
 
-export const LocationKey: ContextKey<Location> = contextKey("location")
+export const LocationKey: ContextKey<Location> = contextKey("aris.location", "location")
 
 /**
  * A FeedSource that provides location context.
@@ -20,7 +20,7 @@ export class LocationSource implements FeedSource {
 
 	private readonly historySize: number
 	private locations: Location[] = []
-	private listeners = new Set<(update: Partial<Context>) => void>()
+	private listeners = new Set<(entries: readonly ContextEntry[]) => void>()
 
 	constructor(options: LocationSourceOptions = {}) {
 		this.historySize = options.historySize ?? 1
@@ -59,8 +59,9 @@ export class LocationSource implements FeedSource {
 		if (this.locations.length > this.historySize) {
 			this.locations.shift()
 		}
+		const entries: readonly ContextEntry[] = [[LocationKey, location]]
 		this.listeners.forEach((listener) => {
-			listener({ [LocationKey]: location })
+			listener(entries)
 		})
 	}
 
@@ -78,16 +79,16 @@ export class LocationSource implements FeedSource {
 		return this.locations
 	}
 
-	onContextUpdate(callback: (update: Partial<Context>) => void): () => void {
+	onContextUpdate(callback: (entries: readonly ContextEntry[]) => void): () => void {
 		this.listeners.add(callback)
 		return () => {
 			this.listeners.delete(callback)
 		}
 	}
 
-	async fetchContext(): Promise<Partial<Context> | null> {
+	async fetchContext(): Promise<readonly ContextEntry[] | null> {
 		if (this.lastLocation) {
-			return { [LocationKey]: this.lastLocation }
+			return [[LocationKey, this.lastLocation]]
 		}
 		return null
 	}

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

@@ -1,12 +1,13 @@
 export { TflSource } from "./tfl-source.ts"
 export { TflApi } from "./tfl-api.ts"
 export type { TflLineId } from "./tfl-api.ts"
-export type {
-	ITflApi,
-	StationLocation,
-	TflAlertData,
-	TflAlertFeedItem,
-	TflAlertSeverity,
-	TflLineStatus,
-	TflSourceOptions,
+export {
+	TflFeedItemType,
+	type ITflApi,
+	type StationLocation,
+	type TflAlertData,
+	type TflAlertFeedItem,
+	type TflAlertSeverity,
+	type TflLineStatus,
+	type TflSourceOptions,
 } from "./types.ts"

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

@@ -1,5 +1,4 @@
-import type { Context } from "@aris/core"
-
+import { Context } from "@aris/core"
 import { LocationKey, type Location } from "@aris/source-location"
 import { describe, expect, test } from "bun:test"
 
@@ -81,9 +80,9 @@ class FixtureTflApi implements ITflApi {
 }
 
 function createContext(location?: Location): Context {
-	const ctx: Context = { time: new Date("2026-01-15T12:00:00Z") }
+	const ctx = new Context(new Date("2026-01-15T12:00:00Z"))
 	if (location) {
-		ctx[LocationKey] = location
+		ctx.set([[LocationKey, location]])
 	}
 	return ctx
 }