fix(backend): validate context key element types

Reject booleans, nulls, and nested arrays in the key
param. Only string, number, and plain objects with
primitive values are accepted.

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.

.devcontainer/devcontainer.json

@@ -11,12 +11,12 @@
 		"dockerfile": "Dockerfile"
 	},
 	"postCreateCommand": "bun install",
-	"postStartCommand": "./scripts/setup-git.sh && ./scripts/setup-nvim.sh"
+	"postStartCommand": "./scripts/setup-git.sh && ./scripts/setup-nvim.sh",
 	// Features add additional features to your environment. See https://containers.dev/features
 	// Beware: features are not supported on all platforms and may have unintended side-effects.
-	// "features": {
+	"features": {
-	//   "ghcr.io/devcontainers/features/docker-in-docker": {
+		"ghcr.io/tailscale/codespace/tailscale": {
-	//     "moby": false
+			"version": "latest"
-	//   }
+		}
-	// }
+	}
 }

.gitignore

@@ -32,3 +32,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 # Finder (MacOS) folder config
 .DS_Store
+core

.ona/automations.yaml

@@ -0,0 +1,8 @@
+services:
+  expo:
+    name: Expo Dev Server
+    description: Expo development server for aelis-client
+    triggeredBy:
+      - postDevcontainerStart
+    commands:
+      start: cd apps/aelis-client && ./scripts/run-dev-server.sh

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project
 
-ARIS is an AI-powered personal assistant that aggregates data from various sources into a contextual feed. Monorepo with `packages/` (shared libraries) and `apps/` (applications).
+AELIS is an AI-powered personal assistant that aggregates data from various sources into a contextual feed. Monorepo with `packages/` (shared libraries) and `apps/` (applications).
 
 ## Commands
 

README.md

@@ -1,4 +1,4 @@
-# aris
+# aelis
 
 To install dependencies:
 
@@ -8,14 +8,14 @@ bun install
 
 ## Packages
 
-### @aris/source-tfl
+### @aelis/source-tfl
 
 TfL (Transport for London) feed source for tube, overground, and Elizabeth line alerts.
 
 #### Testing
 
 ```bash
-cd packages/aris-source-tfl
+cd packages/aelis-source-tfl
 bun run test
 ```
 

apps/aelis-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/aelis-backend/package.json

@@ -1,5 +1,5 @@
 {
-	"name": "@aris/backend",
+	"name": "@aelis/backend",
 	"version": "0.0.0",
 	"type": "module",
 	"main": "src/server.ts",
@@ -9,12 +9,13 @@
 		"test": "bun test src/"
 	},
 	"dependencies": {
-		"@aris/core": "workspace:*",
+		"@aelis/core": "workspace:*",
-		"@aris/source-location": "workspace:*",
+		"@aelis/source-caldav": "workspace:*",
-		"@aris/source-tfl": "workspace:*",
+		"@aelis/source-google-calendar": "workspace:*",
-		"@aris/source-weatherkit": "workspace:*",
+		"@aelis/source-location": "workspace:*",
-		"@hono/trpc-server": "^0.3",
+		"@aelis/source-tfl": "workspace:*",
-		"@trpc/server": "^11",
+		"@aelis/source-weatherkit": "workspace:*",
+		"@openrouter/sdk": "^0.9.11",
 		"arktype": "^2.1.29",
 		"better-auth": "^1",
 		"hono": "^4",

apps/aelis-backend/src/auth/session-middleware.ts

@@ -0,0 +1,102 @@
+import type { Context, MiddlewareHandler, Next } from "hono"
+
+import type { AuthSession, AuthUser } from "./session.ts"
+
+import { auth } from "./index.ts"
+
+export interface SessionVariables {
+	user: AuthUser | null
+	session: AuthSession | null
+}
+
+export type AuthSessionEnv = { Variables: SessionVariables }
+
+export type AuthSessionMiddleware = MiddlewareHandler<AuthSessionEnv>
+
+declare module "hono" {
+	interface ContextVariableMap extends SessionVariables {}
+}
+
+/**
+ * Middleware that attaches session and user to the context.
+ * Does not reject unauthenticated requests - use requireSession for that.
+ */
+export async function sessionMiddleware(c: Context, next: Next): Promise<void> {
+	const session = await auth.api.getSession({ headers: c.req.raw.headers })
+
+	if (session) {
+		c.set("user", session.user)
+		c.set("session", session.session)
+	} else {
+		c.set("user", null)
+		c.set("session", null)
+	}
+
+	await next()
+}
+
+/**
+ * Middleware that requires a valid session. Returns 401 if not authenticated.
+ */
+export async function requireSession(c: Context, next: Next): Promise<Response | void> {
+	const session = await auth.api.getSession({ headers: c.req.raw.headers })
+
+	if (!session) {
+		return c.json({ error: "Unauthorized" }, 401)
+	}
+
+	c.set("user", session.user)
+	c.set("session", session.session)
+	await next()
+}
+
+/**
+ * Get session from headers. Useful for WebSocket upgrade validation.
+ */
+export async function getSessionFromHeaders(
+	headers: Headers,
+): Promise<{ user: AuthUser; session: AuthSession } | null> {
+	const session = await auth.api.getSession({ headers })
+	return session
+}
+
+/**
+ * Dev/test middleware that injects a fake user and session.
+ * Pass userId to simulate an authenticated request, or omit to get 401.
+ */
+export function mockAuthSessionMiddleware(userId?: string): AuthSessionMiddleware {
+	return async (c: Context, next: Next): Promise<Response | void> => {
+		if (!userId) {
+			return c.json({ error: "Unauthorized" }, 401)
+		}
+
+		const now = new Date()
+		const expiresAt = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000)
+
+		const user: AuthUser = {
+			id: "k7Gx2mPqRvNwYs9TdLfA4bHcJeUo1iZn",
+			name: "Dev User",
+			email: "dev@aelis.local",
+			emailVerified: true,
+			image: null,
+			createdAt: now,
+			updatedAt: now,
+		}
+
+		const session: AuthSession = {
+			id: "Wt3FvBpXaQrMhD8sKjE6LcYn0gUz5iRo",
+			userId: "k7Gx2mPqRvNwYs9TdLfA4bHcJeUo1iZn",
+			token: "Vb9CxNfRm2KwQs7TjPeA5dLhYg0UoZi4",
+			expiresAt,
+			ipAddress: "127.0.0.1",
+			userAgent: "aelis-dev",
+			createdAt: now,
+			updatedAt: now,
+		}
+
+		c.set("user", user)
+		c.set("session", session)
+
+		await next()
+	}
+}

apps/aelis-backend/src/auth/session.ts

@@ -0,0 +1,4 @@
+import type { auth } from "./index.ts"
+
+export type AuthUser = typeof auth.$Infer.Session.user
+export type AuthSession = typeof auth.$Infer.Session.session

apps/aelis-backend/src/engine/http.test.ts

@@ -0,0 +1,313 @@
+import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@aelis/core"
+
+import { contextKey } from "@aelis/core"
+import { describe, expect, test } from "bun:test"
+import { Hono } from "hono"
+
+import { mockAuthSessionMiddleware } from "../auth/session-middleware.ts"
+import { UserSessionManager } from "../session/index.ts"
+import { registerFeedHttpHandlers } from "./http.ts"
+
+interface FeedResponse {
+	items: Array<{
+		id: string
+		type: string
+		priority: number
+		timestamp: string
+		data: Record<string, unknown>
+	}>
+	errors: Array<{ sourceId: string; error: string }>
+}
+
+function createStubSource(
+	id: string,
+	items: FeedItem[] = [],
+	contextEntries: readonly ContextEntry[] | null = null,
+): FeedSource {
+	return {
+		id,
+		async listActions(): Promise<Record<string, ActionDefinition>> {
+			return {}
+		},
+		async executeAction(): Promise<unknown> {
+			return undefined
+		},
+		async fetchContext(): Promise<readonly ContextEntry[] | null> {
+			return contextEntries
+		},
+		async fetchItems() {
+			return items
+		},
+	}
+}
+
+function buildTestApp(sessionManager: UserSessionManager, userId?: string) {
+	const app = new Hono()
+	registerFeedHttpHandlers(app, {
+		sessionManager,
+		authSessionMiddleware: mockAuthSessionMiddleware(userId),
+	})
+	return app
+}
+
+describe("GET /api/feed", () => {
+	test("returns 401 without auth", async () => {
+		const manager = new UserSessionManager({ providers: [] })
+		const app = buildTestApp(manager)
+
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(401)
+	})
+
+	test("returns cached feed when available", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				priority: 0.8,
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const manager = new UserSessionManager({
+			providers: [() => createStubSource("test", items)],
+		})
+		const app = buildTestApp(manager, "user-1")
+
+		// Prime the cache
+		const session = manager.getOrCreate("user-1")
+		await session.engine.refresh()
+		expect(session.engine.lastFeed()).not.toBeNull()
+
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as FeedResponse
+		expect(body.items).toHaveLength(1)
+		expect(body.items[0]!.id).toBe("item-1")
+		expect(body.items[0]!.type).toBe("test")
+		expect(body.items[0]!.priority).toBe(0.8)
+		expect(body.items[0]!.timestamp).toBe("2025-01-01T00:00:00.000Z")
+		expect(body.errors).toHaveLength(0)
+	})
+
+	test("forces refresh when no cached feed", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "fresh-1",
+				type: "test",
+				priority: 0.5,
+				timestamp: new Date("2025-06-01T12:00:00.000Z"),
+				data: { fresh: true },
+			},
+		]
+		const manager = new UserSessionManager({
+			providers: [() => createStubSource("test", items)],
+		})
+		const app = buildTestApp(manager, "user-1")
+
+		// No prior refresh — lastFeed() returns null, handler should call refresh()
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as FeedResponse
+		expect(body.items).toHaveLength(1)
+		expect(body.items[0]!.id).toBe("fresh-1")
+		expect(body.items[0]!.data.fresh).toBe(true)
+		expect(body.errors).toHaveLength(0)
+	})
+
+	test("serializes source errors as message strings", async () => {
+		const failingSource: FeedSource = {
+			id: "failing",
+			async listActions() {
+				return {}
+			},
+			async executeAction() {
+				return undefined
+			},
+			async fetchContext() {
+				return null
+			},
+			async fetchItems() {
+				throw new Error("connection timeout")
+			},
+		}
+		const manager = new UserSessionManager({ providers: [() => failingSource] })
+		const app = buildTestApp(manager, "user-1")
+
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as FeedResponse
+		expect(body.items).toHaveLength(0)
+		expect(body.errors).toHaveLength(1)
+		expect(body.errors[0]!.sourceId).toBe("failing")
+		expect(body.errors[0]!.error).toBe("connection timeout")
+	})
+})
+
+describe("GET /api/context", () => {
+	const weatherKey = contextKey("aelis.weather", "weather")
+	const weatherData = { temperature: 20, condition: "Clear" }
+	const contextEntries: readonly ContextEntry[] = [[weatherKey, weatherData]]
+
+	// The mock auth middleware always injects this hardcoded user ID
+	const mockUserId = "k7Gx2mPqRvNwYs9TdLfA4bHcJeUo1iZn"
+
+	function buildContextApp(userId?: string) {
+		const manager = new UserSessionManager({
+			providers: [() => createStubSource("weather", [], contextEntries)],
+		})
+		const app = buildTestApp(manager, userId)
+		const session = manager.getOrCreate(mockUserId)
+		return { app, session }
+	}
+
+	test("returns 401 without auth", async () => {
+		const manager = new UserSessionManager({ providers: [] })
+		const app = buildTestApp(manager)
+
+		const res = await app.request('/api/context?key=["aelis.weather","weather"]')
+
+		expect(res.status).toBe(401)
+	})
+
+	test("returns 400 when key param is missing", async () => {
+		const { app } = buildContextApp("user-1")
+
+		const res = await app.request("/api/context")
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toContain("key")
+	})
+
+	test("returns 400 when key is invalid JSON", async () => {
+		const { app } = buildContextApp("user-1")
+
+		const res = await app.request("/api/context?key=notjson")
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toContain("key")
+	})
+
+	test("returns 400 when key is not an array", async () => {
+		const { app } = buildContextApp("user-1")
+
+		const res = await app.request('/api/context?key="string"')
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toContain("key")
+	})
+
+	test("returns 400 when key contains invalid element types", async () => {
+		const { app } = buildContextApp("user-1")
+
+		const res = await app.request("/api/context?key=[true,null,[1,2]]")
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toContain("key")
+	})
+
+	test("returns 400 when key is an empty array", async () => {
+		const { app } = buildContextApp("user-1")
+
+		const res = await app.request("/api/context?key=[]")
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toContain("key")
+	})
+
+	test("returns 400 when match param is invalid", async () => {
+		const { app } = buildContextApp("user-1")
+
+		const res = await app.request('/api/context?key=["aelis.weather"]&match=invalid')
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toContain("match")
+	})
+
+	test("returns exact match with match=exact", async () => {
+		const { app, session } = buildContextApp("user-1")
+		await session.engine.refresh()
+
+		const res = await app.request('/api/context?key=["aelis.weather","weather"]&match=exact')
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as { match: string; value: unknown }
+		expect(body.match).toBe("exact")
+		expect(body.value).toEqual(weatherData)
+	})
+
+	test("returns 404 with match=exact when only prefix would match", async () => {
+		const { app, session } = buildContextApp("user-1")
+		await session.engine.refresh()
+
+		const res = await app.request('/api/context?key=["aelis.weather"]&match=exact')
+
+		expect(res.status).toBe(404)
+	})
+
+	test("returns prefix match with match=prefix", async () => {
+		const { app, session } = buildContextApp("user-1")
+		await session.engine.refresh()
+
+		const res = await app.request('/api/context?key=["aelis.weather"]&match=prefix')
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as {
+			match: string
+			entries: Array<{ key: unknown[]; value: unknown }>
+		}
+		expect(body.match).toBe("prefix")
+		expect(body.entries).toHaveLength(1)
+		expect(body.entries[0]!.key).toEqual(["aelis.weather", "weather"])
+		expect(body.entries[0]!.value).toEqual(weatherData)
+	})
+
+	test("default mode returns exact match when available", async () => {
+		const { app, session } = buildContextApp("user-1")
+		await session.engine.refresh()
+
+		const res = await app.request('/api/context?key=["aelis.weather","weather"]')
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as { match: string; value: unknown }
+		expect(body.match).toBe("exact")
+		expect(body.value).toEqual(weatherData)
+	})
+
+	test("default mode falls back to prefix when no exact match", async () => {
+		const { app, session } = buildContextApp("user-1")
+		await session.engine.refresh()
+
+		const res = await app.request('/api/context?key=["aelis.weather"]')
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as {
+			match: string
+			entries: Array<{ key: unknown[]; value: unknown }>
+		}
+		expect(body.match).toBe("prefix")
+		expect(body.entries).toHaveLength(1)
+		expect(body.entries[0]!.value).toEqual(weatherData)
+	})
+
+	test("returns 404 when neither exact nor prefix matches", async () => {
+		const { app, session } = buildContextApp("user-1")
+		await session.engine.refresh()
+
+		const res = await app.request('/api/context?key=["nonexistent"]')
+
+		expect(res.status).toBe(404)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toBe("Context key not found")
+	})
+})

apps/aelis-backend/src/engine/http.ts

@@ -0,0 +1,118 @@
+import type { Context, Hono } from "hono"
+
+import { contextKey } from "@aelis/core"
+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
+	}
+}
+
+interface FeedHttpHandlersDeps {
+	sessionManager: UserSessionManager
+	authSessionMiddleware: AuthSessionMiddleware
+}
+
+export function registerFeedHttpHandlers(
+	app: Hono,
+	{ sessionManager, authSessionMiddleware }: FeedHttpHandlersDeps,
+) {
+	const inject = createMiddleware<Env>(async (c, next) => {
+		c.set("sessionManager", sessionManager)
+		await next()
+	})
+
+	app.get("/api/feed", inject, authSessionMiddleware, handleGetFeed)
+	app.get("/api/context", inject, authSessionMiddleware, handleGetContext)
+}
+
+async function handleGetFeed(c: Context<Env>) {
+	const user = c.get("user")!
+	const sessionManager = c.get("sessionManager")
+	const session = sessionManager.getOrCreate(user.id)
+
+	const feed = await session.feed()
+
+	return c.json({
+		items: feed.items,
+		errors: feed.errors.map((e) => ({
+			sourceId: e.sourceId,
+			error: e.error.message,
+		})),
+	})
+}
+
+function handleGetContext(c: Context<Env>) {
+	const keyParam = c.req.query("key")
+	if (!keyParam) {
+		return c.json({ error: 'Invalid or missing "key" parameter: must be a JSON array' }, 400)
+	}
+
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(keyParam)
+	} catch {
+		return c.json({ error: 'Invalid or missing "key" parameter: must be a JSON array' }, 400)
+	}
+
+	if (!Array.isArray(parsed) || parsed.length === 0 || !parsed.every(isContextKeyPart)) {
+		return c.json({ error: 'Invalid or missing "key" parameter: must be a JSON array' }, 400)
+	}
+
+	const matchParam = c.req.query("match")
+	if (matchParam !== undefined && matchParam !== "exact" && matchParam !== "prefix") {
+		return c.json({ error: 'Invalid "match" parameter: must be "exact" or "prefix"' }, 400)
+	}
+
+	const user = c.get("user")!
+	const sessionManager = c.get("sessionManager")
+	const session = sessionManager.getOrCreate(user.id)
+	const context = session.engine.currentContext()
+	const key = contextKey(...parsed)
+
+	if (matchParam === "exact") {
+		const value = context.get(key)
+		if (value === undefined) {
+			return c.json({ error: "Context key not found" }, 404)
+		}
+		return c.json({ match: "exact", value })
+	}
+
+	if (matchParam === "prefix") {
+		const entries = context.find(key)
+		if (entries.length === 0) {
+			return c.json({ error: "Context key not found" }, 404)
+		}
+		return c.json({ match: "prefix", entries })
+	}
+
+	// Default: single find() covers both exact and prefix matches
+	const entries = context.find(key)
+	if (entries.length === 0) {
+		return c.json({ error: "Context key not found" }, 404)
+	}
+
+	// If exactly one result with the same key length, treat as exact match
+	if (entries.length === 1 && entries[0]!.key.length === parsed.length) {
+		return c.json({ match: "exact", value: entries[0]!.value })
+	}
+
+	return c.json({ match: "prefix", entries })
+}
+
+/** Validates that a value is a valid ContextKeyPart (string, number, or plain object of primitives). */
+function isContextKeyPart(value: unknown): boolean {
+	if (typeof value === "string" || typeof value === "number") {
+		return true
+	}
+	if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+		return Object.values(value).every(
+			(v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean",
+		)
+	}
+	return false
+}

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

@@ -0,0 +1,51 @@
+import type { FeedItem } from "@aelis/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/aelis-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/aelis-backend/src/enhancement/merge.test.ts

@@ -0,0 +1,150 @@
+import type { FeedItem } from "@aelis/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/aelis-backend/src/enhancement/merge.ts

@@ -0,0 +1,41 @@
+import type { FeedItem } from "@aelis/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/aelis-backend/src/enhancement/prompt-builder.test.ts

@@ -0,0 +1,167 @@
+import type { FeedItem } from "@aelis/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/aelis-backend/src/enhancement/prompt-builder.ts

@@ -0,0 +1,218 @@
+import type { FeedItem } from "@aelis/core"
+
+import { CalDavFeedItemType } from "@aelis/source-caldav"
+import { CalendarFeedItemType } from "@aelis/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/aelis-backend/src/enhancement/prompts/system.txt

@@ -0,0 +1,21 @@
+You are AELIS, 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/aelis-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/aelis-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/aelis-backend/src/location/http.ts

@@ -0,0 +1,56 @@
+import type { Context, Hono } from "hono"
+
+import { type } from "arktype"
+import { createMiddleware } from "hono/factory"
+
+import type { UserSessionManager } from "../session/index.ts"
+
+import { requireSession } from "../auth/session-middleware.ts"
+
+type Env = { Variables: { sessionManager: UserSessionManager } }
+
+const locationInput = type({
+	lat: "number",
+	lng: "number",
+	accuracy: "number",
+	timestamp: "string.date.iso",
+})
+
+export function registerLocationHttpHandlers(
+	app: Hono,
+	{ sessionManager }: { sessionManager: UserSessionManager },
+) {
+	const inject = createMiddleware<Env>(async (c, next) => {
+		c.set("sessionManager", sessionManager)
+		await next()
+	})
+
+	app.post("/api/location", inject, requireSession, handleUpdateLocation)
+}
+
+async function handleUpdateLocation(c: Context<Env>) {
+	let body: unknown
+	try {
+		body = await c.req.json()
+	} catch {
+		return c.json({ error: "Invalid JSON" }, 400)
+	}
+
+	const result = locationInput(body)
+
+	if (result instanceof type.errors) {
+		return c.json({ error: result.summary }, 400)
+	}
+
+	const user = c.get("user")!
+	const sessionManager = c.get("sessionManager")
+	const session = sessionManager.getOrCreate(user.id)
+	await session.engine.executeAction("aelis.location", "update-location", {
+		lat: result.lat,
+		lng: result.lng,
+		accuracy: result.accuracy,
+		timestamp: new Date(result.timestamp),
+	})
+
+	return c.body(null, 204)
+}

apps/aelis-backend/src/server.ts

@@ -0,0 +1,67 @@
+import { LocationSource } from "@aelis/source-location"
+import { Hono } from "hono"
+
+import { registerAuthHandlers } from "./auth/http.ts"
+import { mockAuthSessionMiddleware, requireSession } from "./auth/session-middleware.ts"
+import { createFeedEnhancer } from "./enhancement/enhance-feed.ts"
+import { createLlmClient } from "./enhancement/llm-client.ts"
+import { registerFeedHttpHandlers } from "./engine/http.ts"
+import { registerLocationHttpHandlers } from "./location/http.ts"
+import { UserSessionManager } from "./session/index.ts"
+import { WeatherSourceProvider } from "./weather/provider.ts"
+
+function main() {
+	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: {
+					privateKey: process.env.WEATHERKIT_PRIVATE_KEY!,
+					keyId: process.env.WEATHERKIT_KEY_ID!,
+					teamId: process.env.WEATHERKIT_TEAM_ID!,
+					serviceId: process.env.WEATHERKIT_SERVICE_ID!,
+				},
+			}),
+		],
+		feedEnhancer,
+	})
+
+	const app = new Hono()
+
+	app.get("/health", (c) => c.json({ status: "ok" }))
+
+	const isDev = process.env.NODE_ENV !== "production"
+	const authSessionMiddleware = isDev ? mockAuthSessionMiddleware("dev-user") : requireSession
+
+	if (!isDev) {
+		registerAuthHandlers(app)
+	}
+
+	registerFeedHttpHandlers(app, {
+		sessionManager,
+		authSessionMiddleware,
+	})
+	registerLocationHttpHandlers(app, { sessionManager })
+
+	return app
+}
+
+const app = main()
+
+export default {
+	port: 3000,
+	fetch: app.fetch,
+}

apps/aelis-backend/src/session/feed-source-provider.ts

@@ -0,0 +1,9 @@
+import type { FeedSource } from "@aelis/core"
+
+export interface FeedSourceProvider {
+	feedSourceForUser(userId: string): FeedSource
+}
+
+export type FeedSourceProviderFn = (userId: string) => FeedSource
+
+export type FeedSourceProviderInput = FeedSourceProvider | FeedSourceProviderFn

apps/aelis-backend/src/session/index.ts

@@ -0,0 +1,7 @@
+export type {
+	FeedSourceProvider,
+	FeedSourceProviderFn,
+	FeedSourceProviderInput,
+} from "./feed-source-provider.ts"
+export { UserSession } from "./user-session.ts"
+export { UserSessionManager } from "./user-session-manager.ts"

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

@@ -0,0 +1,170 @@
+import type { WeatherKitClient, WeatherKitResponse } from "@aelis/source-weatherkit"
+
+import { LocationSource } from "@aelis/source-location"
+import { describe, expect, mock, test } from "bun:test"
+
+import { WeatherSourceProvider } from "../weather/provider.ts"
+import { UserSessionManager } from "./user-session-manager.ts"
+
+const mockWeatherClient: WeatherKitClient = {
+	fetch: async () => ({}) as WeatherKitResponse,
+}
+
+describe("UserSessionManager", () => {
+	test("getOrCreate creates session on first call", () => {
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
+
+		const session = manager.getOrCreate("user-1")
+
+		expect(session).toBeDefined()
+		expect(session.engine).toBeDefined()
+	})
+
+	test("getOrCreate returns same session for same user", () => {
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
+
+		const session1 = manager.getOrCreate("user-1")
+		const session2 = manager.getOrCreate("user-1")
+
+		expect(session1).toBe(session2)
+	})
+
+	test("getOrCreate returns different sessions for different users", () => {
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
+
+		const session1 = manager.getOrCreate("user-1")
+		const session2 = manager.getOrCreate("user-2")
+
+		expect(session1).not.toBe(session2)
+	})
+
+	test("each user gets independent source instances", () => {
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
+
+		const session1 = manager.getOrCreate("user-1")
+		const session2 = manager.getOrCreate("user-2")
+
+		const source1 = session1.getSource<LocationSource>("aelis.location")
+		const source2 = session2.getSource<LocationSource>("aelis.location")
+
+		expect(source1).not.toBe(source2)
+	})
+
+	test("remove destroys session and allows re-creation", () => {
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
+
+		const session1 = manager.getOrCreate("user-1")
+		manager.remove("user-1")
+		const session2 = manager.getOrCreate("user-1")
+
+		expect(session1).not.toBe(session2)
+	})
+
+	test("remove is no-op for unknown user", () => {
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
+
+		expect(() => manager.remove("unknown")).not.toThrow()
+	})
+
+	test("accepts function providers", async () => {
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
+
+		const session = manager.getOrCreate("user-1")
+		const result = await session.engine.refresh()
+
+		expect(result.errors).toHaveLength(0)
+	})
+
+	test("accepts object providers", () => {
+		const provider = new WeatherSourceProvider({ client: mockWeatherClient })
+		const manager = new UserSessionManager({
+			providers: [() => new LocationSource(), provider],
+		})
+
+		const session = manager.getOrCreate("user-1")
+
+		expect(session.getSource("aelis.weather")).toBeDefined()
+	})
+
+	test("accepts mixed providers", () => {
+		const provider = new WeatherSourceProvider({ client: mockWeatherClient })
+		const manager = new UserSessionManager({
+			providers: [() => new LocationSource(), provider],
+		})
+
+		const session = manager.getOrCreate("user-1")
+
+		expect(session.getSource("aelis.location")).toBeDefined()
+		expect(session.getSource("aelis.weather")).toBeDefined()
+	})
+
+	test("refresh returns feed result through session", async () => {
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
+
+		const session = manager.getOrCreate("user-1")
+		const result = await session.engine.refresh()
+
+		expect(result).toHaveProperty("context")
+		expect(result).toHaveProperty("items")
+		expect(result).toHaveProperty("errors")
+		expect(result.context.time).toBeInstanceOf(Date)
+	})
+
+	test("location update via executeAction works", async () => {
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
+
+		const session = manager.getOrCreate("user-1")
+		await session.engine.executeAction("aelis.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		const source = session.getSource<LocationSource>("aelis.location")
+		expect(source?.lastLocation?.lat).toBe(51.5074)
+	})
+
+	test("subscribe receives updates after location push", async () => {
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
+		const callback = mock()
+
+		const session = manager.getOrCreate("user-1")
+		session.engine.subscribe(callback)
+
+		await session.engine.executeAction("aelis.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		// Wait for async update propagation
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		expect(callback).toHaveBeenCalled()
+	})
+
+	test("remove stops reactive updates", async () => {
+		const manager = new UserSessionManager({ providers: [() => new LocationSource()] })
+		const callback = mock()
+
+		const session = manager.getOrCreate("user-1")
+		session.engine.subscribe(callback)
+
+		manager.remove("user-1")
+
+		// Create new session and push location — old callback should not fire
+		const session2 = manager.getOrCreate("user-1")
+		await session2.engine.executeAction("aelis.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		expect(callback).not.toHaveBeenCalled()
+	})
+})

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

@@ -0,0 +1,40 @@
+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(config: UserSessionManagerConfig) {
+		this.providers = config.providers
+		this.feedEnhancer = config.feedEnhancer ?? null
+	}
+
+	getOrCreate(userId: string): UserSession {
+		let session = this.sessions.get(userId)
+		if (!session) {
+			const sources = this.providers.map((p) =>
+				typeof p === "function" ? p(userId) : p.feedSourceForUser(userId),
+			)
+			session = new UserSession(sources, this.feedEnhancer)
+			this.sessions.set(userId, session)
+		}
+		return session
+	}
+
+	remove(userId: string): void {
+		const session = this.sessions.get(userId)
+		if (session) {
+			session.destroy()
+			this.sessions.delete(userId)
+		}
+	}
+}

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

@@ -0,0 +1,210 @@
+import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@aelis/core"
+
+import { LocationSource } from "@aelis/source-location"
+import { describe, expect, test } from "bun:test"
+
+import { UserSession } from "./user-session.ts"
+
+function createStubSource(id: string, items: FeedItem[] = []): FeedSource {
+	return {
+		id,
+		async listActions(): Promise<Record<string, ActionDefinition>> {
+			return {}
+		},
+		async executeAction(): Promise<unknown> {
+			return undefined
+		},
+		async fetchContext(): Promise<readonly ContextEntry[] | null> {
+			return null
+		},
+		async fetchItems() {
+			return items
+		},
+	}
+}
+
+describe("UserSession", () => {
+	test("registers sources and starts engine", async () => {
+		const session = new UserSession([createStubSource("test-a"), createStubSource("test-b")])
+
+		const result = await session.engine.refresh()
+
+		expect(result.errors).toHaveLength(0)
+	})
+
+	test("getSource returns registered source", () => {
+		const location = new LocationSource()
+		const session = new UserSession([location])
+
+		const result = session.getSource<LocationSource>("aelis.location")
+
+		expect(result).toBe(location)
+	})
+
+	test("getSource returns undefined for unknown source", () => {
+		const session = new UserSession([createStubSource("test")])
+
+		expect(session.getSource("unknown")).toBeUndefined()
+	})
+
+	test("destroy stops engine and clears sources", () => {
+		const session = new UserSession([createStubSource("test")])
+
+		session.destroy()
+
+		expect(session.getSource("test")).toBeUndefined()
+	})
+
+	test("engine.executeAction routes to correct source", async () => {
+		const location = new LocationSource()
+		const session = new UserSession([location])
+
+		await session.engine.executeAction("aelis.location", "update-location", {
+			lat: 51.5,
+			lng: -0.1,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		expect(location.lastLocation).toBeDefined()
+		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/aelis-backend/src/session/user-session.ts

@@ -0,0 +1,104 @@
+import { FeedEngine, type FeedItem, type FeedResult, type FeedSource } from "@aelis/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[], 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/aelis-backend/src/tfl/provider.ts

@@ -0,0 +1,19 @@
+import { TflSource, type ITflApi } from "@aelis/source-tfl"
+
+import type { FeedSourceProvider } from "../session/feed-source-provider.ts"
+
+export type TflSourceProviderOptions =
+	| { apiKey: string; client?: never }
+	| { apiKey?: never; client: ITflApi }
+
+export class TflSourceProvider implements FeedSourceProvider {
+	private readonly options: TflSourceProviderOptions
+
+	constructor(options: TflSourceProviderOptions) {
+		this.options = options
+	}
+
+	feedSourceForUser(_userId: string): TflSource {
+		return new TflSource(this.options)
+	}
+}

apps/aelis-backend/src/weather/provider.ts

@@ -0,0 +1,15 @@
+import { WeatherSource, type WeatherSourceOptions } from "@aelis/source-weatherkit"
+
+import type { FeedSourceProvider } from "../session/feed-source-provider.ts"
+
+export class WeatherSourceProvider implements FeedSourceProvider {
+	private readonly options: WeatherSourceOptions
+
+	constructor(options: WeatherSourceOptions) {
+		this.options = options
+	}
+
+	feedSourceForUser(_userId: string): WeatherSource {
+		return new WeatherSource(this.options)
+	}
+}

apps/aelis-client/.gitignore

@@ -0,0 +1,43 @@
+# Learn more https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files
+
+# dependencies
+node_modules/
+
+# Expo
+.expo/
+dist/
+web-build/
+expo-env.d.ts
+
+# Native
+.kotlin/
+*.orig.*
+*.jks
+*.p8
+*.p12
+*.key
+*.mobileprovision
+
+# Metro
+.metro-health-check*
+
+# debug
+npm-debug.*
+yarn-debug.*
+yarn-error.*
+
+# macOS
+.DS_Store
+*.pem
+
+# local env files
+.env*.local
+
+# typescript
+*.tsbuildinfo
+
+app-example
+
+# generated native folders
+/ios
+/android

apps/aelis-client/.vscode/extensions.json

@@ -0,0 +1 @@
+{ "recommendations": ["expo.vscode-expo-tools"] }

apps/aelis-client/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+	"editor.codeActionsOnSave": {
+		"source.fixAll": "explicit",
+		"source.organizeImports": "explicit",
+		"source.sortMembers": "explicit"
+	}
+}

apps/aelis-client/README.md

@@ -0,0 +1,50 @@
+# Welcome to your Expo app 👋
+
+This is an [Expo](https://expo.dev) project created with [`create-expo-app`](https://www.npmjs.com/package/create-expo-app).
+
+## Get started
+
+1. Install dependencies
+
+   ```bash
+   npm install
+   ```
+
+2. Start the app
+
+   ```bash
+   npx expo start
+   ```
+
+In the output, you'll find options to open the app in a
+
+- [development build](https://docs.expo.dev/develop/development-builds/introduction/)
+- [Android emulator](https://docs.expo.dev/workflow/android-studio-emulator/)
+- [iOS simulator](https://docs.expo.dev/workflow/ios-simulator/)
+- [Expo Go](https://expo.dev/go), a limited sandbox for trying out app development with Expo
+
+You can start developing by editing the files inside the **app** directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction).
+
+## Get a fresh project
+
+When you're ready, run:
+
+```bash
+npm run reset-project
+```
+
+This command will move the starter code to the **app-example** directory and create a blank **app** directory where you can start developing.
+
+## Learn more
+
+To learn more about developing your project with Expo, look at the following resources:
+
+- [Expo documentation](https://docs.expo.dev/): Learn fundamentals, or go into advanced topics with our [guides](https://docs.expo.dev/guides).
+- [Learn Expo tutorial](https://docs.expo.dev/tutorial/introduction/): Follow a step-by-step tutorial where you'll create a project that runs on Android, iOS, and the web.
+
+## Join the community
+
+Join our community of developers creating universal apps.
+
+- [Expo on GitHub](https://github.com/expo/expo): View our open source platform and contribute.
+- [Discord community](https://chat.expo.dev): Chat with Expo users and ask questions.

apps/aelis-client/app.json

@@ -0,0 +1,152 @@
+{
+	"expo": {
+		"name": "Aelis",
+		"slug": "aelis-client",
+		"version": "1.0.0",
+		"orientation": "portrait",
+		"icon": "./assets/images/icon.png",
+		"scheme": "aelis",
+		"userInterfaceStyle": "automatic",
+		"newArchEnabled": true,
+		"ios": {
+			"infoPlist": {
+				"NSAppTransportSecurity": {
+					"NSAllowsArbitraryLoads": true
+				},
+				"ITSAppUsesNonExemptEncryption": false
+			},
+			"bundleIdentifier": "sh.nym.aelis"
+		},
+		"android": {
+			"adaptiveIcon": {
+				"backgroundColor": "#E6F4FE",
+				"foregroundImage": "./assets/images/android-icon-foreground.png",
+				"backgroundImage": "./assets/images/android-icon-background.png",
+				"monochromeImage": "./assets/images/android-icon-monochrome.png"
+			},
+			"edgeToEdgeEnabled": true,
+			"predictiveBackGestureEnabled": false,
+			"package": "sh.nym.aelis"
+		},
+		"web": {
+			"output": "static",
+			"favicon": "./assets/images/favicon.png"
+		},
+		"plugins": [
+			"expo-router",
+			[
+				"expo-splash-screen",
+				{
+					"image": "./assets/images/splash-icon.png",
+					"imageWidth": 200,
+					"resizeMode": "contain",
+					"backgroundColor": "#ffffff",
+					"dark": {
+						"backgroundColor": "#000000"
+					}
+				}
+			],
+			[
+				"expo-font",
+				{
+					"android": {
+						"fonts": [
+							{
+								"fontFamily": "Inter",
+								"fontDefinitions": [
+									{ "path": "./assets/fonts/Inter_100Thin.ttf", "weight": 100 },
+									{ "path": "./assets/fonts/Inter_100Thin_Italic.ttf", "weight": 100, "style": "italic" },
+									{ "path": "./assets/fonts/Inter_200ExtraLight.ttf", "weight": 200 },
+									{ "path": "./assets/fonts/Inter_200ExtraLight_Italic.ttf", "weight": 200, "style": "italic" },
+									{ "path": "./assets/fonts/Inter_300Light.ttf", "weight": 300 },
+									{ "path": "./assets/fonts/Inter_300Light_Italic.ttf", "weight": 300, "style": "italic" },
+									{ "path": "./assets/fonts/Inter_400Regular.ttf", "weight": 400 },
+									{ "path": "./assets/fonts/Inter_400Regular_Italic.ttf", "weight": 400, "style": "italic" },
+									{ "path": "./assets/fonts/Inter_500Medium.ttf", "weight": 500 },
+									{ "path": "./assets/fonts/Inter_500Medium_Italic.ttf", "weight": 500, "style": "italic" },
+									{ "path": "./assets/fonts/Inter_600SemiBold.ttf", "weight": 600 },
+									{ "path": "./assets/fonts/Inter_600SemiBold_Italic.ttf", "weight": 600, "style": "italic" },
+									{ "path": "./assets/fonts/Inter_700Bold.ttf", "weight": 700 },
+									{ "path": "./assets/fonts/Inter_700Bold_Italic.ttf", "weight": 700, "style": "italic" },
+									{ "path": "./assets/fonts/Inter_800ExtraBold.ttf", "weight": 800 },
+									{ "path": "./assets/fonts/Inter_800ExtraBold_Italic.ttf", "weight": 800, "style": "italic" },
+									{ "path": "./assets/fonts/Inter_900Black.ttf", "weight": 900 },
+									{ "path": "./assets/fonts/Inter_900Black_Italic.ttf", "weight": 900, "style": "italic" }
+								]
+							},
+							{
+								"fontFamily": "Source Serif 4",
+								"fontDefinitions": [
+									{ "path": "./assets/fonts/SourceSerif4_200ExtraLight.ttf", "weight": 200 },
+									{ "path": "./assets/fonts/SourceSerif4_200ExtraLight_Italic.ttf", "weight": 200, "style": "italic" },
+									{ "path": "./assets/fonts/SourceSerif4_300Light.ttf", "weight": 300 },
+									{ "path": "./assets/fonts/SourceSerif4_300Light_Italic.ttf", "weight": 300, "style": "italic" },
+									{ "path": "./assets/fonts/SourceSerif4_400Regular.ttf", "weight": 400 },
+									{ "path": "./assets/fonts/SourceSerif4_400Regular_Italic.ttf", "weight": 400, "style": "italic" },
+									{ "path": "./assets/fonts/SourceSerif4_500Medium.ttf", "weight": 500 },
+									{ "path": "./assets/fonts/SourceSerif4_500Medium_Italic.ttf", "weight": 500, "style": "italic" },
+									{ "path": "./assets/fonts/SourceSerif4_600SemiBold.ttf", "weight": 600 },
+									{ "path": "./assets/fonts/SourceSerif4_600SemiBold_Italic.ttf", "weight": 600, "style": "italic" },
+									{ "path": "./assets/fonts/SourceSerif4_700Bold.ttf", "weight": 700 },
+									{ "path": "./assets/fonts/SourceSerif4_700Bold_Italic.ttf", "weight": 700, "style": "italic" },
+									{ "path": "./assets/fonts/SourceSerif4_800ExtraBold.ttf", "weight": 800 },
+									{ "path": "./assets/fonts/SourceSerif4_800ExtraBold_Italic.ttf", "weight": 800, "style": "italic" },
+									{ "path": "./assets/fonts/SourceSerif4_900Black.ttf", "weight": 900 },
+									{ "path": "./assets/fonts/SourceSerif4_900Black_Italic.ttf", "weight": 900, "style": "italic" }
+								]
+							}
+						]
+					},
+					"ios": {
+						"fonts": [
+							"./assets/fonts/Inter_100Thin.ttf",
+							"./assets/fonts/Inter_100Thin_Italic.ttf",
+							"./assets/fonts/Inter_200ExtraLight.ttf",
+							"./assets/fonts/Inter_200ExtraLight_Italic.ttf",
+							"./assets/fonts/Inter_300Light.ttf",
+							"./assets/fonts/Inter_300Light_Italic.ttf",
+							"./assets/fonts/Inter_400Regular.ttf",
+							"./assets/fonts/Inter_400Regular_Italic.ttf",
+							"./assets/fonts/Inter_500Medium.ttf",
+							"./assets/fonts/Inter_500Medium_Italic.ttf",
+							"./assets/fonts/Inter_600SemiBold.ttf",
+							"./assets/fonts/Inter_600SemiBold_Italic.ttf",
+							"./assets/fonts/Inter_700Bold.ttf",
+							"./assets/fonts/Inter_700Bold_Italic.ttf",
+							"./assets/fonts/Inter_800ExtraBold.ttf",
+							"./assets/fonts/Inter_800ExtraBold_Italic.ttf",
+							"./assets/fonts/Inter_900Black.ttf",
+							"./assets/fonts/Inter_900Black_Italic.ttf",
+							"./assets/fonts/SourceSerif4_200ExtraLight.ttf",
+							"./assets/fonts/SourceSerif4_200ExtraLight_Italic.ttf",
+							"./assets/fonts/SourceSerif4_300Light.ttf",
+							"./assets/fonts/SourceSerif4_300Light_Italic.ttf",
+							"./assets/fonts/SourceSerif4_400Regular.ttf",
+							"./assets/fonts/SourceSerif4_400Regular_Italic.ttf",
+							"./assets/fonts/SourceSerif4_500Medium.ttf",
+							"./assets/fonts/SourceSerif4_500Medium_Italic.ttf",
+							"./assets/fonts/SourceSerif4_600SemiBold.ttf",
+							"./assets/fonts/SourceSerif4_600SemiBold_Italic.ttf",
+							"./assets/fonts/SourceSerif4_700Bold.ttf",
+							"./assets/fonts/SourceSerif4_700Bold_Italic.ttf",
+							"./assets/fonts/SourceSerif4_800ExtraBold.ttf",
+							"./assets/fonts/SourceSerif4_800ExtraBold_Italic.ttf",
+							"./assets/fonts/SourceSerif4_900Black.ttf",
+							"./assets/fonts/SourceSerif4_900Black_Italic.ttf"
+						]
+					}
+				}
+			]
+		],
+		"experiments": {
+			"typedRoutes": true,
+			"reactCompiler": true
+		},
+		"extra": {
+			"router": {},
+			"eas": {
+				"projectId": "61092d23-36aa-418e-929d-ea40dc912e8f"
+			}
+		}
+	}
+}

apps/aelis-client/eas.json

@@ -0,0 +1,27 @@
+{
+	"cli": {
+		"version": ">= 18.0.1",
+		"appVersionSource": "remote"
+	},
+	"build": {
+		"development": {
+			"developmentClient": true,
+			"distribution": "internal"
+		},
+		"development-simulator": {
+			"extends": "development",
+			"ios": {
+				"simulator": "true"
+			}
+		},
+		"preview": {
+			"distribution": "internal"
+		},
+		"production": {
+			"autoIncrement": true
+		}
+	},
+	"submit": {
+		"production": {}
+	}
+}

apps/aelis-client/eslint.config.js

@@ -0,0 +1,10 @@
+// https://docs.expo.dev/guides/using-eslint/
+const { defineConfig } = require("eslint/config")
+const expoConfig = require("eslint-config-expo/flat")
+
+module.exports = defineConfig([
+	expoConfig,
+	{
+		ignores: ["dist/*"],
+	},
+])

apps/aelis-client/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "aelis-client",
+	"version": "1.0.0",
+	"private": true,
+	"main": "expo-router/entry",
+	"scripts": {
+		"start": "./scripts/run-dev-server.sh",
+		"reset-project": "node ./scripts/reset-project.js",
+		"android": "expo start --android",
+		"ios": "expo start --ios",
+		"web": "expo start --web",
+		"lint": "expo lint",
+		"build:ios": "eas build --profile development --platform ios --non-interactive",
+		"build:ios-simulator": "eas build --profile development-simulator --platform ios --non-interactive",
+		"debugger": "bun run scripts/open-debugger.ts"
+	},
+	"dependencies": {
+		"@expo-google-fonts/inter": "^0.4.2",
+		"@expo-google-fonts/source-serif-4": "^0.4.1",
+		"@expo/vector-icons": "^15.0.3",
+		"@react-navigation/bottom-tabs": "^7.4.0",
+		"@react-navigation/elements": "^2.6.3",
+		"@react-navigation/native": "^7.1.8",
+		"expo": "~54.0.33",
+		"expo-constants": "~18.0.13",
+		"expo-dev-client": "~6.0.20",
+		"expo-font": "~14.0.11",
+		"expo-haptics": "~15.0.8",
+		"expo-image": "~3.0.11",
+		"expo-linking": "~8.0.11",
+		"expo-location": "~19.0.8",
+		"expo-router": "~6.0.23",
+		"expo-splash-screen": "~31.0.13",
+		"expo-status-bar": "~3.0.9",
+		"expo-symbols": "~1.0.8",
+		"expo-system-ui": "~6.0.9",
+		"expo-web-browser": "~15.0.10",
+		"react": "19.1.0",
+		"react-dom": "19.1.0",
+		"react-native": "0.81.5",
+		"react-native-gesture-handler": "~2.28.0",
+		"react-native-reanimated": "~4.1.1",
+		"react-native-safe-area-context": "~5.6.0",
+		"react-native-screens": "~4.16.0",
+		"react-native-svg": "15.12.1",
+		"react-native-web": "~0.21.0",
+		"react-native-worklets": "0.5.1",
+		"twrnc": "^4.16.0"
+	},
+	"devDependencies": {
+		"@types/react": "~19.1.0",
+		"eas-cli": "^18.0.1",
+		"eslint": "^9.25.0",
+		"eslint-config-expo": "~10.0.0",
+		"typescript": "~5.9.2"
+	}
+}

apps/aelis-client/scripts/dev-proxy.ts

@@ -0,0 +1,127 @@
+// Reverse proxy that sits in front of Metro so that all requests
+// (including those arriving via Tailscale or Ona port-forwarding) reach
+// Metro as loopback connections. This satisfies the isLocalSocket check
+// in Expo's debug middleware, making /debugger-frontend, /json, and
+// /open-debugger accessible from a remote browser.
+
+import type { ServerWebSocket } from "bun"
+
+const PROXY_PORT = parseInt(process.env.PROXY_PORT || "8080", 10)
+const METRO_PORT = parseInt(process.env.METRO_PORT || "8081", 10)
+const METRO_BASE = `http://127.0.0.1:${METRO_PORT}`
+
+function forwardHeaders(headers: Headers): Headers {
+	const result = new Headers(headers)
+	result.delete("origin")
+	result.delete("referer")
+	result.set("host", `127.0.0.1:${METRO_PORT}`)
+	return result
+}
+
+interface WsData {
+	upstream: WebSocket
+	isDevice: boolean
+}
+
+Bun.serve<WsData>({
+	port: PROXY_PORT,
+
+	async fetch(req, server) {
+		const url = new URL(req.url)
+
+		// WebSocket upgrade — bridge to Metro's ws endpoint
+		if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
+			const wsUrl = `ws://127.0.0.1:${METRO_PORT}${url.pathname}${url.search}`
+			const upstream = new WebSocket(wsUrl)
+
+			// Wait for upstream to connect before upgrading the client
+			try {
+				await new Promise<void>((resolve, reject) => {
+					upstream.addEventListener("open", () => resolve())
+					upstream.addEventListener("error", () => reject(new Error("upstream ws failed")))
+				})
+			} catch {
+				return new Response("Upstream WebSocket unavailable", { status: 502 })
+			}
+
+			const isDevice = url.pathname.startsWith("/inspector/device")
+			const ok = server.upgrade(req, { data: { upstream, isDevice } })
+			if (!ok) {
+				upstream.close()
+				return new Response("WebSocket upgrade failed", { status: 500 })
+			}
+			return undefined
+		}
+
+		// HTTP proxy
+		const upstream = `${METRO_BASE}${url.pathname}${url.search}`
+		const res = await fetch(upstream, {
+			method: req.method,
+			headers: forwardHeaders(req.headers),
+			body: req.body,
+			redirect: "manual",
+		})
+
+		return new Response(res.body, {
+			status: res.status,
+			statusText: res.statusText,
+			headers: res.headers,
+		})
+	},
+
+	websocket: {
+		message(ws: ServerWebSocket<WsData>, msg) {
+			ws.data.upstream.send(msg)
+		},
+		open(ws: ServerWebSocket<WsData>) {
+			const { upstream } = ws.data
+			upstream.addEventListener("message", (ev) => {
+				if (typeof ev.data === "string") {
+					ws.send(ev.data)
+				} else if (ev.data instanceof ArrayBuffer) {
+					ws.sendBinary(new Uint8Array(ev.data))
+				}
+			})
+			upstream.addEventListener("close", () => ws.close())
+			upstream.addEventListener("error", () => ws.close())
+
+			// Print debugger URL shortly after a device connects,
+			// giving Metro time to register the target.
+			if (ws.data.isDevice) {
+				setTimeout(() => printDebuggerUrl(), 1000)
+			}
+		},
+		close(ws: ServerWebSocket<WsData>) {
+			ws.data.upstream.close()
+		},
+	},
+})
+
+const tsIp = await Bun.$`tailscale ip -4`.text().then((s) => s.trim())
+
+async function printDebuggerUrl() {
+	const base = `http://${tsIp}:${PROXY_PORT}`
+	const res = await fetch(`${METRO_BASE}/json`)
+	if (!res.ok) return
+
+	interface DebugTarget {
+		webSocketDebuggerUrl: string
+		reactNative?: {
+			capabilities?: { prefersFuseboxFrontend?: boolean }
+		}
+	}
+
+	const targets: DebugTarget[] = await res.json()
+	const target = targets.find((t) => t.reactNative?.capabilities?.prefersFuseboxFrontend)
+	if (!target) return
+
+	const wsPath = target.webSocketDebuggerUrl
+		.replace(/^ws:\/\//, "")
+		.replace(`127.0.0.1:${METRO_PORT}`, `${tsIp}:${PROXY_PORT}`)
+
+	console.log(
+		`\n  React Native DevTools:\n  ${base}/debugger-frontend/rn_fusebox.html?ws=${encodeURIComponent(wsPath)}&sources.hide_add_folder=true&unstable_enableNetworkPanel=true\n`,
+	)
+}
+
+console.log(`[proxy] listening on :${PROXY_PORT}, forwarding to 127.0.0.1:${METRO_PORT}`)

apps/aelis-client/scripts/open-debugger.ts

@@ -0,0 +1,52 @@
+// Opens React Native DevTools in Chrome, connected to the first
+// available Hermes debug target. Requires Metro + proxy to be running.
+
+import { $ } from "bun"
+
+const PROXY_PORT = process.env.PROXY_PORT || "8080"
+const METRO_PORT = process.env.METRO_PORT || "8081"
+const tsIp = (await $`tailscale ip -4`.text()).trim()
+const base = `http://${tsIp}:${PROXY_PORT}`
+
+interface DebugTarget {
+	devtoolsFrontendUrl: string
+	webSocketDebuggerUrl: string
+	reactNative?: {
+		capabilities?: {
+			prefersFuseboxFrontend?: boolean
+		}
+	}
+}
+
+const res = await fetch(`${base}/json`)
+if (!res.ok) {
+	console.error("Failed to fetch /json — is Metro running?")
+	process.exit(1)
+}
+
+const targets: DebugTarget[] = await res.json()
+const target = targets.find((t) => t.reactNative?.capabilities?.prefersFuseboxFrontend)
+
+if (!target) {
+	console.error("No debug target found. Is the app connected?")
+	process.exit(1)
+}
+
+const wsUrl = target.webSocketDebuggerUrl
+	.replace(/^ws:\/\//, "")
+	.replace(`127.0.0.1:${METRO_PORT}`, `${tsIp}:${PROXY_PORT}`)
+
+const url = `${base}/debugger-frontend/rn_fusebox.html?ws=${encodeURIComponent(wsUrl)}&sources.hide_add_folder=true&unstable_enableNetworkPanel=true`
+
+console.log(url)
+
+// Open in Chrome app mode if on macOS
+try {
+	await $`open -a "Google Chrome" --args --app=${url}`.quiet()
+} catch {
+	try {
+		await $`xdg-open ${url}`.quiet()
+	} catch {
+		console.log("Open the URL above in Chrome.")
+	}
+}

apps/aelis-client/scripts/reset-project.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+/**
+ * This script is used to reset the project to a blank state.
+ * It deletes or moves the /app, /components, /hooks, /scripts, and /constants directories to /app-example based on user input and creates a new /app directory with an index.tsx and _layout.tsx file.
+ * You can remove the `reset-project` script from package.json and safely delete this file after running it.
+ */
+
+const fs = require("fs")
+const path = require("path")
+const readline = require("readline")
+
+const root = process.cwd()
+const oldDirs = ["app", "components", "hooks", "constants", "scripts"]
+const exampleDir = "app-example"
+const newAppDir = "app"
+const exampleDirPath = path.join(root, exampleDir)
+
+const indexContent = `import { Text, View } from "react-native";
+
+export default function Index() {
+  return (
+    <View
+      style={{
+        flex: 1,
+        justifyContent: "center",
+        alignItems: "center",
+      }}
+    >
+      <Text>Edit app/index.tsx to edit this screen.</Text>
+    </View>
+  );
+}
+`
+
+const layoutContent = `import { Stack } from "expo-router";
+
+export default function RootLayout() {
+  return <Stack />;
+}
+`
+
+const rl = readline.createInterface({
+	input: process.stdin,
+	output: process.stdout,
+})
+
+const moveDirectories = async (userInput) => {
+	try {
+		if (userInput === "y") {
+			// Create the app-example directory
+			await fs.promises.mkdir(exampleDirPath, { recursive: true })
+			console.log(`📁 /${exampleDir} directory created.`)
+		}
+
+		// Move old directories to new app-example directory or delete them
+		for (const dir of oldDirs) {
+			const oldDirPath = path.join(root, dir)
+			if (fs.existsSync(oldDirPath)) {
+				if (userInput === "y") {
+					const newDirPath = path.join(root, exampleDir, dir)
+					await fs.promises.rename(oldDirPath, newDirPath)
+					console.log(`➡️ /${dir} moved to /${exampleDir}/${dir}.`)
+				} else {
+					await fs.promises.rm(oldDirPath, { recursive: true, force: true })
+					console.log(`❌ /${dir} deleted.`)
+				}
+			} else {
+				console.log(`➡️ /${dir} does not exist, skipping.`)
+			}
+		}
+
+		// Create new /app directory
+		const newAppDirPath = path.join(root, newAppDir)
+		await fs.promises.mkdir(newAppDirPath, { recursive: true })
+		console.log("\n📁 New /app directory created.")
+
+		// Create index.tsx
+		const indexPath = path.join(newAppDirPath, "index.tsx")
+		await fs.promises.writeFile(indexPath, indexContent)
+		console.log("📄 app/index.tsx created.")
+
+		// Create _layout.tsx
+		const layoutPath = path.join(newAppDirPath, "_layout.tsx")
+		await fs.promises.writeFile(layoutPath, layoutContent)
+		console.log("📄 app/_layout.tsx created.")
+
+		console.log("\n✅ Project reset complete. Next steps:")
+		console.log(
+			`1. Run \`npx expo start\` to start a development server.\n2. Edit app/index.tsx to edit the main screen.${
+				userInput === "y"
+					? `\n3. Delete the /${exampleDir} directory when you're done referencing it.`
+					: ""
+			}`,
+		)
+	} catch (error) {
+		console.error(`❌ Error during script execution: ${error.message}`)
+	}
+}
+
+rl.question(
+	"Do you want to move existing files to /app-example instead of deleting them? (Y/n): ",
+	(answer) => {
+		const userInput = answer.trim().toLowerCase() || "y"
+		if (userInput === "y" || userInput === "n") {
+			moveDirectories(userInput).finally(() => rl.close())
+		} else {
+			console.log("❌ Invalid input. Please enter 'Y' or 'N'.")
+			rl.close()
+		}
+	},
+)

apps/aelis-client/scripts/run-dev-server.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROXY_PORT=8080
+METRO_PORT=8081
+
+# Start a reverse proxy so Metro sees all requests as loopback.
+# This makes debugger endpoints (/debugger-frontend, /json, /open-debugger)
+# accessible through the Tailscale IP.
+PROXY_PORT=$PROXY_PORT METRO_PORT=$METRO_PORT bun run scripts/dev-proxy.ts &
+PROXY_PID=$!
+trap "kill $PROXY_PID 2>/dev/null" EXIT
+
+EXPO_PACKAGER_PROXY_URL=http://$(tailscale ip -4):$PROXY_PORT bunx expo start --localhost -p $METRO_PORT
+

apps/aelis-client/src/app/(tabs)/_layout.tsx

@@ -0,0 +1,36 @@
+import { Tabs } from "expo-router"
+import React from "react"
+
+import { HapticTab } from "@/components/haptic-tab"
+import { IconSymbol } from "@/components/ui/icon-symbol"
+import { Colors } from "@/constants/theme"
+import { useColorScheme } from "@/hooks/use-color-scheme"
+
+export default function TabLayout() {
+	const colorScheme = useColorScheme()
+
+	return (
+		<Tabs
+			screenOptions={{
+				tabBarActiveTintColor: Colors[colorScheme ?? "light"].tint,
+				headerShown: false,
+				tabBarButton: HapticTab,
+			}}
+		>
+			<Tabs.Screen
+				name="index"
+				options={{
+					title: "Home",
+					tabBarIcon: ({ color }) => <IconSymbol size={28} name="house.fill" color={color} />,
+				}}
+			/>
+			<Tabs.Screen
+				name="explore"
+				options={{
+					title: "Explore",
+					tabBarIcon: ({ color }) => <IconSymbol size={28} name="paperplane.fill" color={color} />,
+				}}
+			/>
+		</Tabs>
+	)
+}

apps/aelis-client/src/app/(tabs)/explore.tsx

@@ -0,0 +1,114 @@
+import { Image } from "expo-image"
+import { Platform, StyleSheet } from "react-native"
+
+import { ExternalLink } from "@/components/external-link"
+import ParallaxScrollView from "@/components/parallax-scroll-view"
+import { ThemedText } from "@/components/themed-text"
+import { ThemedView } from "@/components/themed-view"
+import { Collapsible } from "@/components/ui/collapsible"
+import { IconSymbol } from "@/components/ui/icon-symbol"
+import { Fonts } from "@/constants/theme"
+
+export default function TabTwoScreen() {
+	return (
+		<ParallaxScrollView
+			headerBackgroundColor={{ light: "#D0D0D0", dark: "#353636" }}
+			headerImage={
+				<IconSymbol
+					size={310}
+					color="#808080"
+					name="chevron.left.forwardslash.chevron.right"
+					style={styles.headerImage}
+				/>
+			}
+		>
+			<ThemedView style={styles.titleContainer}>
+				<ThemedText
+					type="title"
+					style={{
+						fontFamily: Fonts.rounded,
+					}}
+				>
+					Explore
+				</ThemedText>
+			</ThemedView>
+			<ThemedText>This app includes example code to help you get started.</ThemedText>
+			<Collapsible title="File-based routing">
+				<ThemedText>
+					This app has two screens:{" "}
+					<ThemedText type="defaultSemiBold">app/(tabs)/index.tsx</ThemedText> and{" "}
+					<ThemedText type="defaultSemiBold">app/(tabs)/explore.tsx</ThemedText>
+				</ThemedText>
+				<ThemedText>
+					The layout file in <ThemedText type="defaultSemiBold">app/(tabs)/_layout.tsx</ThemedText>{" "}
+					sets up the tab navigator.
+				</ThemedText>
+				<ExternalLink href="https://docs.expo.dev/router/introduction">
+					<ThemedText type="link">Learn more</ThemedText>
+				</ExternalLink>
+			</Collapsible>
+			<Collapsible title="Android, iOS, and web support">
+				<ThemedText>
+					You can open this project on Android, iOS, and the web. To open the web version, press{" "}
+					<ThemedText type="defaultSemiBold">w</ThemedText> in the terminal running this project.
+				</ThemedText>
+			</Collapsible>
+			<Collapsible title="Images">
+				<ThemedText>
+					For static images, you can use the <ThemedText type="defaultSemiBold">@2x</ThemedText> and{" "}
+					<ThemedText type="defaultSemiBold">@3x</ThemedText> suffixes to provide files for
+					different screen densities
+				</ThemedText>
+				<Image
+					source={require("@assets/images/react-logo.png")}
+					style={{ width: 100, height: 100, alignSelf: "center" }}
+				/>
+				<ExternalLink href="https://reactnative.dev/docs/images">
+					<ThemedText type="link">Learn more</ThemedText>
+				</ExternalLink>
+			</Collapsible>
+			<Collapsible title="Light and dark mode components">
+				<ThemedText>
+					This template has light and dark mode support. The{" "}
+					<ThemedText type="defaultSemiBold">useColorScheme()</ThemedText> hook lets you inspect
+					what the user&apos;s current color scheme is, and so you can adjust UI colors accordingly.
+				</ThemedText>
+				<ExternalLink href="https://docs.expo.dev/develop/user-interface/color-themes/">
+					<ThemedText type="link">Learn more</ThemedText>
+				</ExternalLink>
+			</Collapsible>
+			<Collapsible title="Animations">
+				<ThemedText>
+					This template includes an example of an animated component. The{" "}
+					<ThemedText type="defaultSemiBold">components/HelloWave.tsx</ThemedText> component uses
+					the powerful{" "}
+					<ThemedText type="defaultSemiBold" style={{ fontFamily: Fonts.mono }}>
+						react-native-reanimated
+					</ThemedText>{" "}
+					library to create a waving hand animation.
+				</ThemedText>
+				{Platform.select({
+					ios: (
+						<ThemedText>
+							The <ThemedText type="defaultSemiBold">components/ParallaxScrollView.tsx</ThemedText>{" "}
+							component provides a parallax effect for the header image.
+						</ThemedText>
+					),
+				})}
+			</Collapsible>
+		</ParallaxScrollView>
+	)
+}
+
+const styles = StyleSheet.create({
+	headerImage: {
+		color: "#808080",
+		bottom: -90,
+		left: -35,
+		position: "absolute",
+	},
+	titleContainer: {
+		flexDirection: "row",
+		gap: 8,
+	},
+})

apps/aelis-client/src/app/(tabs)/index.tsx

@@ -0,0 +1,96 @@
+import { Image } from "expo-image"
+import { Link } from "expo-router"
+import { Platform, StyleSheet } from "react-native"
+
+import { HelloWave } from "@/components/hello-wave"
+import ParallaxScrollView from "@/components/parallax-scroll-view"
+import { ThemedText } from "@/components/themed-text"
+import { ThemedView } from "@/components/themed-view"
+
+export default function HomeScreen() {
+	return (
+		<ParallaxScrollView
+			headerBackgroundColor={{ light: "#A1CEDC", dark: "#1D3D47" }}
+			headerImage={
+				<Image source={require("@assets/images/partial-react-logo.png")} style={styles.reactLogo} />
+			}
+		>
+			<ThemedView style={styles.titleContainer}>
+				<ThemedText type="title">Welcome!</ThemedText>
+				<HelloWave />
+			</ThemedView>
+			<ThemedView style={styles.stepContainer}>
+				<ThemedText type="subtitle">Step 1: Try it</ThemedText>
+				<ThemedText>
+					Edit <ThemedText type="defaultSemiBold">app/(tabs)/index.tsx</ThemedText> to see changes.
+					Press{" "}
+					<ThemedText type="defaultSemiBold">
+						{Platform.select({
+							ios: "cmd + d",
+							android: "cmd + m",
+							web: "F12",
+						})}
+					</ThemedText>{" "}
+					to open developer tools.
+				</ThemedText>
+			</ThemedView>
+			<ThemedView style={styles.stepContainer}>
+				<Link href="/modal">
+					<Link.Trigger>
+						<ThemedText type="subtitle">Step 2: Explore</ThemedText>
+					</Link.Trigger>
+					<Link.Preview />
+					<Link.Menu>
+						<Link.MenuAction title="Action" icon="cube" onPress={() => alert("Action pressed")} />
+						<Link.MenuAction
+							title="Share"
+							icon="square.and.arrow.up"
+							onPress={() => alert("Share pressed")}
+						/>
+						<Link.Menu title="More" icon="ellipsis">
+							<Link.MenuAction
+								title="Delete"
+								icon="trash"
+								destructive
+								onPress={() => alert("Delete pressed")}
+							/>
+						</Link.Menu>
+					</Link.Menu>
+				</Link>
+
+				<ThemedText>
+					{`Tap the Explore tab to learn more about what's included in this starter app.`}
+				</ThemedText>
+			</ThemedView>
+			<ThemedView style={styles.stepContainer}>
+				<ThemedText type="subtitle">Step 3: Get a fresh start</ThemedText>
+				<ThemedText>
+					{`When you're ready, run `}
+					<ThemedText type="defaultSemiBold">npm run reset-project</ThemedText> to get a fresh{" "}
+					<ThemedText type="defaultSemiBold">app</ThemedText> directory. This will move the current{" "}
+					<ThemedText type="defaultSemiBold">app</ThemedText> to{" "}
+					<ThemedText type="defaultSemiBold">app-example</ThemedText>.
+				</ThemedText>
+			</ThemedView>
+		</ParallaxScrollView>
+	)
+}
+
+const styles = StyleSheet.create({
+	titleContainer: {
+		flexDirection: "row",
+		alignItems: "center",
+		gap: 8,
+	},
+	stepContainer: {
+		gap: 8,
+		marginBottom: 8,
+	},
+	reactLogo: {
+		height: 178,
+		width: 290,
+		bottom: 0,
+		left: 0,
+		position: "absolute",
+	},
+})

apps/aelis-client/src/app/_layout.tsx

@@ -0,0 +1,23 @@
+import { DarkTheme, DefaultTheme, ThemeProvider } from "@react-navigation/native"
+import { Stack } from "expo-router"
+import { StatusBar } from "expo-status-bar"
+import "react-native-reanimated"
+import { useColorScheme } from "@/hooks/use-color-scheme"
+
+export const unstable_settings = {
+	anchor: "(tabs)",
+}
+
+export default function RootLayout() {
+	const colorScheme = useColorScheme()
+
+	return (
+		<ThemeProvider value={colorScheme === "dark" ? DarkTheme : DefaultTheme}>
+			<Stack>
+				<Stack.Screen name="(tabs)" options={{ headerShown: false }} />
+				<Stack.Screen name="modal" options={{ presentation: "modal", title: "Modal" }} />
+			</Stack>
+			<StatusBar style="auto" />
+		</ThemeProvider>
+	)
+}

apps/aelis-client/src/app/modal.tsx

@@ -0,0 +1,29 @@
+import { Link } from "expo-router"
+import { StyleSheet } from "react-native"
+
+import { ThemedText } from "@/components/themed-text"
+import { ThemedView } from "@/components/themed-view"
+
+export default function ModalScreen() {
+	return (
+		<ThemedView style={styles.container}>
+			<ThemedText type="title">This is a modal</ThemedText>
+			<Link href="/" dismissTo style={styles.link}>
+				<ThemedText type="link">Go to home screen</ThemedText>
+			</Link>
+		</ThemedView>
+	)
+}
+
+const styles = StyleSheet.create({
+	container: {
+		flex: 1,
+		alignItems: "center",
+		justifyContent: "center",
+		padding: 20,
+	},
+	link: {
+		marginTop: 15,
+		paddingVertical: 15,
+	},
+})

apps/aelis-client/src/components/external-link.tsx

@@ -0,0 +1,25 @@
+import { Href, Link } from "expo-router"
+import { openBrowserAsync, WebBrowserPresentationStyle } from "expo-web-browser"
+import { type ComponentProps } from "react"
+
+type Props = Omit<ComponentProps<typeof Link>, "href"> & { href: Href & string }
+
+export function ExternalLink({ href, ...rest }: Props) {
+	return (
+		<Link
+			target="_blank"
+			{...rest}
+			href={href}
+			onPress={async (event) => {
+				if (process.env.EXPO_OS !== "web") {
+					// Prevent the default behavior of linking to the default browser on native.
+					event.preventDefault()
+					// Open the link in an in-app browser.
+					await openBrowserAsync(href, {
+						presentationStyle: WebBrowserPresentationStyle.AUTOMATIC,
+					})
+				}
+			}}
+		/>
+	)
+}

apps/aelis-client/src/components/haptic-tab.tsx

@@ -0,0 +1,18 @@
+import { BottomTabBarButtonProps } from "@react-navigation/bottom-tabs"
+import { PlatformPressable } from "@react-navigation/elements"
+import * as Haptics from "expo-haptics"
+
+export function HapticTab(props: BottomTabBarButtonProps) {
+	return (
+		<PlatformPressable
+			{...props}
+			onPressIn={(ev) => {
+				if (process.env.EXPO_OS === "ios") {
+					// Add a soft haptic feedback when pressing down on the tabs.
+					Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light)
+				}
+				props.onPressIn?.(ev)
+			}}
+		/>
+	)
+}

apps/aelis-client/src/components/hello-wave.tsx

@@ -0,0 +1,20 @@
+import Animated from "react-native-reanimated"
+
+export function HelloWave() {
+	return (
+		<Animated.Text
+			style={{
+				fontSize: 28,
+				lineHeight: 32,
+				marginTop: -6,
+				animationName: {
+					"50%": { transform: [{ rotate: "25deg" }] },
+				},
+				animationIterationCount: 4,
+				animationDuration: "300ms",
+			}}
+		>
+			👋
+		</Animated.Text>
+	)
+}