diff --git a/mobile-app/README.md b/mobile-app/README.md
new file mode 100644
index 0000000..a06ce5c
--- /dev/null
+++ b/mobile-app/README.md
@@ -0,0 +1,108 @@
+# Timmy Chat — Mobile App
+
+A sleek mobile chat interface for Timmy, the sovereign AI agent. Built with **Expo SDK 54**, **React Native**, **TypeScript**, and **NativeWind** (Tailwind CSS).
+
+## Features
+
+- **Text Chat** — Send and receive messages with Timmy's full personality
+- **Voice Messages** — Record and send voice notes via the mic button; playback with waveform UI
+- **Image Sharing** — Take photos or pick from library; full-screen image viewer
+- **File Attachments** — Send any document via the system file picker
+- **Dark Arcane Theme** — Deep purple/indigo palette matching the Timmy Time dashboard
+
+## Screenshots
+
+The app is a single-screen chat interface with:
+- Header showing Timmy's status and a clear-chat button
+- Message list with distinct user (teal) and Timmy (dark surface) bubbles
+- Input bar with attachment (+), text field, and mic/send button
+- Empty state with Timmy branding when no messages exist
+
+## Project Structure
+
+```
+mobile-app/
+├── app/                    # Expo Router screens
+│   ├── _layout.tsx         # Root layout with providers
+│   └── (tabs)/
+│       ├── _layout.tsx     # Tab layout (hidden — single screen)
+│       └── index.tsx       # Main chat screen
+├── components/
+│   ├── chat-bubble.tsx     # Message bubble (text, image, voice, file)
+│   ├── chat-header.tsx     # Header with Timmy status
+│   ├── chat-input.tsx      # Input bar (text, mic, attachments)
+│   ├── empty-chat.tsx      # Empty state welcome screen
+│   ├── image-viewer.tsx    # Full-screen image modal
+│   └── typing-indicator.tsx # Animated dots while Timmy responds
+├── lib/
+│   └── chat-store.tsx      # React Context chat state + API calls
+├── server/
+│   └── chat.ts             # Server-side chat handler with Timmy's prompt
+├── shared/
+│   └── types.ts            # ChatMessage type definitions
+├── assets/images/          # App icons (custom generated)
+├── theme.config.js         # Color tokens (dark arcane palette)
+├── tailwind.config.js      # Tailwind/NativeWind configuration
+└── tests/
+    └── chat.test.ts        # Unit tests
+```
+
+## Setup
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm 9+
+- Expo CLI (`npx expo`)
+- iOS Simulator or Android Emulator (or physical device with Expo Go)
+
+### Install Dependencies
+
+```bash
+cd mobile-app
+pnpm install
+```
+
+### Run the App
+
+```bash
+# Start the Expo dev server
+npx expo start
+
+# Or run on specific platform
+npx expo start --ios
+npx expo start --android
+npx expo start --web
+```
+
+### Backend
+
+The chat API endpoint (`server/chat.ts`) requires an LLM backend. The `invokeLLM` function should be wired to your preferred provider:
+
+- **Local Ollama** — Point to `http://localhost:11434` for local inference
+- **OpenAI-compatible API** — Any API matching the OpenAI chat completions format
+
+The system prompt in `server/chat.ts` contains Timmy's full personality, agent roster, and behavioral rules ported from the dashboard's `prompts.py`.
+
+## Timmy's Personality
+
+Timmy is a sovereign AI agent — grounded in Christian faith, powered by Bitcoin economics, committed to digital sovereignty. He speaks plainly, acts with intention, and never ends responses with generic chatbot phrases. His agent roster includes Echo, Mace, Forge, Seer, Helm, Quill, Pixel, Lyra, and Reel.
+
+## Theme
+
+The app uses a dark arcane color palette:
+
+| Token | Color | Usage |
+|-------|-------|-------|
+| `primary` | `#7c3aed` | Accent, user bubbles |
+| `background` | `#080412` | Screen background |
+| `surface` | `#110a20` | Cards, Timmy bubbles |
+| `foreground` | `#e8e0f0` | Primary text |
+| `muted` | `#6b5f7d` | Secondary text |
+| `border` | `#1e1535` | Dividers |
+| `success` | `#22c55e` | Status indicator |
+| `error` | `#ff4455` | Recording state |
+
+## License
+
+Same as the parent Timmy Time Dashboard project.
diff --git a/mobile-app/app.config.ts b/mobile-app/app.config.ts
new file mode 100644
index 0000000..f64baf1
--- /dev/null
+++ b/mobile-app/app.config.ts
@@ -0,0 +1,130 @@
+// Load environment variables with proper priority (system > .env)
+import "./scripts/load-env.js";
+import type { ExpoConfig } from "expo/config";
+
+// Bundle ID format: space.manus.<project_name_dots>.<timestamp>
+// e.g., "my-app" created at 2024-01-15 10:30:45 -> "space.manus.my.app.t20240115103045"
+// Bundle ID can only contain letters, numbers, and dots
+// Android requires each dot-separated segment to start with a letter
+const rawBundleId = "space.manus.timmy.chat.t20260226211148";
+const bundleId =
+  rawBundleId
+    .replace(/[-_]/g, ".") // Replace hyphens/underscores with dots
+    .replace(/[^a-zA-Z0-9.]/g, "") // Remove invalid chars
+    .replace(/\.+/g, ".") // Collapse consecutive dots
+    .replace(/^\.+|\.+$/g, "") // Trim leading/trailing dots
+    .toLowerCase()
+    .split(".")
+    .map((segment) => {
+      // Android requires each segment to start with a letter
+      // Prefix with 'x' if segment starts with a digit
+      return /^[a-zA-Z]/.test(segment) ? segment : "x" + segment;
+    })
+    .join(".") || "space.manus.app";
+// Extract timestamp from bundle ID and prefix with "manus" for deep link scheme
+// e.g., "space.manus.my.app.t20240115103045" -> "manus20240115103045"
+const timestamp = bundleId.split(".").pop()?.replace(/^t/, "") ?? "";
+const schemeFromBundleId = `manus${timestamp}`;
+
+const env = {
+  // App branding - update these values directly (do not use env vars)
+  appName: "Timmy Chat",
+  appSlug: "timmy-chat",
+  // S3 URL of the app logo - set this to the URL returned by generate_image when creating custom logo
+  // Leave empty to use the default icon from assets/images/icon.png
+  logoUrl: "https://files.manuscdn.com/user_upload_by_module/session_file/310519663286296482/kuSmtQpNVBtvECMG.png",
+  scheme: schemeFromBundleId,
+  iosBundleId: bundleId,
+  androidPackage: bundleId,
+};
+
+const config: ExpoConfig = {
+  name: env.appName,
+  slug: env.appSlug,
+  version: "1.0.0",
+  orientation: "portrait",
+  icon: "./assets/images/icon.png",
+  scheme: env.scheme,
+  userInterfaceStyle: "automatic",
+  newArchEnabled: true,
+  ios: {
+    supportsTablet: true,
+    bundleIdentifier: env.iosBundleId,
+    "infoPlist": {
+        "ITSAppUsesNonExemptEncryption": false
+      }
+  },
+  android: {
+    adaptiveIcon: {
+      backgroundColor: "#080412",
+      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: env.androidPackage,
+    permissions: ["POST_NOTIFICATIONS"],
+    intentFilters: [
+      {
+        action: "VIEW",
+        autoVerify: true,
+        data: [
+          {
+            scheme: env.scheme,
+            host: "*",
+          },
+        ],
+        category: ["BROWSABLE", "DEFAULT"],
+      },
+    ],
+  },
+  web: {
+    bundler: "metro",
+    output: "static",
+    favicon: "./assets/images/favicon.png",
+  },
+  plugins: [
+    "expo-router",
+    [
+      "expo-audio",
+      {
+        microphonePermission: "Allow $(PRODUCT_NAME) to access your microphone.",
+      },
+    ],
+    [
+      "expo-video",
+      {
+        supportsBackgroundPlayback: true,
+        supportsPictureInPicture: true,
+      },
+    ],
+    [
+      "expo-splash-screen",
+      {
+        image: "./assets/images/splash-icon.png",
+        imageWidth: 200,
+        resizeMode: "contain",
+        backgroundColor: "#080412",
+        dark: {
+          backgroundColor: "#080412",
+        },
+      },
+    ],
+    [
+      "expo-build-properties",
+      {
+        android: {
+          buildArchs: ["armeabi-v7a", "arm64-v8a"],
+          minSdkVersion: 24,
+        },
+      },
+    ],
+  ],
+  experiments: {
+    typedRoutes: true,
+    reactCompiler: true,
+  },
+};
+
+export default config;
diff --git a/mobile-app/app/(tabs)/_layout.tsx b/mobile-app/app/(tabs)/_layout.tsx
new file mode 100644
index 0000000..07f5be2
--- /dev/null
+++ b/mobile-app/app/(tabs)/_layout.tsx
@@ -0,0 +1,17 @@
+import { Tabs } from "expo-router";
+import { useColors } from "@/hooks/use-colors";
+
+export default function TabLayout() {
+  const colors = useColors();
+
+  return (
+    <Tabs
+      screenOptions={{
+        headerShown: false,
+        tabBarStyle: { display: "none" },
+      }}
+    >
+      <Tabs.Screen name="index" options={{ title: "Chat" }} />
+    </Tabs>
+  );
+}
diff --git a/mobile-app/app/(tabs)/index.tsx b/mobile-app/app/(tabs)/index.tsx
new file mode 100644
index 0000000..d747b74
--- /dev/null
+++ b/mobile-app/app/(tabs)/index.tsx
@@ -0,0 +1,96 @@
+import { useCallback, useRef, useState } from "react";
+import { FlatList, KeyboardAvoidingView, Platform, StyleSheet, View } from "react-native";
+import { ScreenContainer } from "@/components/screen-container";
+import { ChatHeader } from "@/components/chat-header";
+import { ChatBubble } from "@/components/chat-bubble";
+import { ChatInput } from "@/components/chat-input";
+import { TypingIndicator } from "@/components/typing-indicator";
+import { ImageViewer } from "@/components/image-viewer";
+import { EmptyChat } from "@/components/empty-chat";
+import { useChat } from "@/lib/chat-store";
+import { useColors } from "@/hooks/use-colors";
+import { createAudioPlayer, setAudioModeAsync } from "expo-audio";
+import type { ChatMessage } from "@/shared/types";
+
+export default function ChatScreen() {
+  const { messages, isTyping } = useChat();
+  const colors = useColors();
+  const flatListRef = useRef<FlatList>(null);
+  const [viewingImage, setViewingImage] = useState<string | null>(null);
+  const [playingVoiceId, setPlayingVoiceId] = useState<string | null>(null);
+
+  const handlePlayVoice = useCallback(async (msg: ChatMessage) => {
+    if (!msg.uri) return;
+    try {
+      if (playingVoiceId === msg.id) {
+        setPlayingVoiceId(null);
+        return;
+      }
+      await setAudioModeAsync({ playsInSilentMode: true });
+      const player = createAudioPlayer({ uri: msg.uri });
+      player.play();
+      setPlayingVoiceId(msg.id);
+      // Auto-reset after estimated duration
+      const dur = (msg.duration ?? 5) * 1000;
+      setTimeout(() => {
+        setPlayingVoiceId(null);
+        player.remove();
+      }, dur + 500);
+    } catch (err) {
+      console.warn("Voice playback error:", err);
+      setPlayingVoiceId(null);
+    }
+  }, [playingVoiceId]);
+
+  const renderItem = useCallback(
+    ({ item }: { item: ChatMessage }) => (
+      <ChatBubble
+        message={item}
+        onImagePress={setViewingImage}
+        onPlayVoice={handlePlayVoice}
+        isPlayingVoice={playingVoiceId === item.id}
+      />
+    ),
+    [playingVoiceId, handlePlayVoice],
+  );
+
+  const keyExtractor = useCallback((item: ChatMessage) => item.id, []);
+
+  return (
+    <ScreenContainer edges={["top", "left", "right"]} containerClassName="bg-background">
+      <KeyboardAvoidingView
+        style={styles.flex}
+        behavior={Platform.OS === "ios" ? "padding" : undefined}
+        keyboardVerticalOffset={0}
+      >
+        <ChatHeader />
+
+        <FlatList
+          ref={flatListRef}
+          data={messages}
+          renderItem={renderItem}
+          keyExtractor={keyExtractor}
+          contentContainerStyle={styles.listContent}
+          style={{ flex: 1, backgroundColor: colors.background }}
+          onContentSizeChange={() => {
+            flatListRef.current?.scrollToEnd({ animated: true });
+          }}
+          ListFooterComponent={isTyping ? <TypingIndicator /> : null}
+          ListEmptyComponent={!isTyping ? <EmptyChat /> : null}
+          showsVerticalScrollIndicator={false}
+        />
+
+        <ChatInput />
+      </KeyboardAvoidingView>
+
+      <ImageViewer uri={viewingImage} onClose={() => setViewingImage(null)} />
+    </ScreenContainer>
+  );
+}
+
+const styles = StyleSheet.create({
+  flex: { flex: 1 },
+  listContent: {
+    paddingVertical: 12,
+  },
+});
diff --git a/mobile-app/app/_layout.tsx b/mobile-app/app/_layout.tsx
new file mode 100644
index 0000000..844280f
--- /dev/null
+++ b/mobile-app/app/_layout.tsx
@@ -0,0 +1,45 @@
+import "@/global.css";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { Stack } from "expo-router";
+import { StatusBar } from "expo-status-bar";
+import { useState } from "react";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import "react-native-reanimated";
+import { ThemeProvider } from "@/lib/theme-provider";
+import { SafeAreaProvider, initialWindowMetrics } from "react-native-safe-area-context";
+import { ChatProvider } from "@/lib/chat-store";
+
+export const unstable_settings = {
+  anchor: "(tabs)",
+};
+
+export default function RootLayout() {
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            refetchOnWindowFocus: false,
+            retry: 1,
+          },
+        },
+      }),
+  );
+
+  return (
+    <ThemeProvider>
+      <SafeAreaProvider initialMetrics={initialWindowMetrics}>
+        <GestureHandlerRootView style={{ flex: 1 }}>
+          <QueryClientProvider client={queryClient}>
+            <ChatProvider>
+              <Stack screenOptions={{ headerShown: false }}>
+                <Stack.Screen name="(tabs)" />
+              </Stack>
+            </ChatProvider>
+            <StatusBar style="light" />
+          </QueryClientProvider>
+        </GestureHandlerRootView>
+      </SafeAreaProvider>
+    </ThemeProvider>
+  );
+}
diff --git a/mobile-app/assets/images/android-icon-background.png b/mobile-app/assets/images/android-icon-background.png
new file mode 100644
index 0000000..5ffefc5
Binary files /dev/null and b/mobile-app/assets/images/android-icon-background.png differ
diff --git a/mobile-app/assets/images/android-icon-foreground.png b/mobile-app/assets/images/android-icon-foreground.png
new file mode 100644
index 0000000..bf882e0
Binary files /dev/null and b/mobile-app/assets/images/android-icon-foreground.png differ
diff --git a/mobile-app/assets/images/android-icon-monochrome.png b/mobile-app/assets/images/android-icon-monochrome.png
new file mode 100644
index 0000000..77484eb
Binary files /dev/null and b/mobile-app/assets/images/android-icon-monochrome.png differ
diff --git a/mobile-app/assets/images/favicon.png b/mobile-app/assets/images/favicon.png
new file mode 100644
index 0000000..bf891e5
Binary files /dev/null and b/mobile-app/assets/images/favicon.png differ
diff --git a/mobile-app/assets/images/icon.png b/mobile-app/assets/images/icon.png
new file mode 100644
index 0000000..bf882e0
Binary files /dev/null and b/mobile-app/assets/images/icon.png differ
diff --git a/mobile-app/assets/images/splash-icon.png b/mobile-app/assets/images/splash-icon.png
new file mode 100644
index 0000000..d986b19
Binary files /dev/null and b/mobile-app/assets/images/splash-icon.png differ
diff --git a/mobile-app/components/chat-bubble.tsx b/mobile-app/components/chat-bubble.tsx
new file mode 100644
index 0000000..f4e64f9
--- /dev/null
+++ b/mobile-app/components/chat-bubble.tsx
@@ -0,0 +1,214 @@
+import { useMemo } from "react";
+import { Text, View, StyleSheet, Image, Platform } from "react-native";
+import Pressable from "@/components/ui/pressable-fix";
+import { useColors } from "@/hooks/use-colors";
+import type { ChatMessage } from "@/shared/types";
+import { formatBytes, formatDuration } from "@/lib/chat-store";
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+
+interface ChatBubbleProps {
+  message: ChatMessage;
+  onImagePress?: (uri: string) => void;
+  onPlayVoice?: (message: ChatMessage) => void;
+  isPlayingVoice?: boolean;
+}
+
+export function ChatBubble({ message, onImagePress, onPlayVoice, isPlayingVoice }: ChatBubbleProps) {
+  const colors = useColors();
+  const isUser = message.role === "user";
+
+  // Stable waveform bar heights based on message id
+  const waveHeights = useMemo(() => {
+    let seed = 0;
+    for (let i = 0; i < message.id.length; i++) seed = (seed * 31 + message.id.charCodeAt(i)) | 0;
+    return Array.from({ length: 12 }, (_, i) => {
+      seed = (seed * 16807 + i * 1013) % 2147483647;
+      return 4 + (seed % 15);
+    });
+  }, [message.id]);
+
+  const bubbleStyle = [
+    styles.bubble,
+    {
+      backgroundColor: isUser ? colors.primary : colors.surface,
+      borderColor: isUser ? colors.primary : colors.border,
+      alignSelf: isUser ? "flex-end" as const : "flex-start" as const,
+    },
+  ];
+
+  const textColor = isUser ? "#fff" : colors.foreground;
+  const mutedColor = isUser ? "rgba(255,255,255,0.6)" : colors.muted;
+
+  const timeStr = new Date(message.timestamp).toLocaleTimeString([], {
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+
+  return (
+    <View style={[styles.row, isUser ? styles.rowUser : styles.rowAssistant]}>
+      {!isUser && (
+        <View style={[styles.avatar, { backgroundColor: colors.primary }]}>
+          <Text style={styles.avatarText}>T</Text>
+        </View>
+      )}
+      <View style={bubbleStyle}>
+        {message.contentType === "text" && (
+          <Text style={[styles.text, { color: textColor }]}>{message.text}</Text>
+        )}
+
+        {message.contentType === "image" && (
+          <Pressable
+            onPress={() => message.uri && onImagePress?.(message.uri)}
+            style={({ pressed }) => [pressed && { opacity: 0.8 }]}
+          >
+            <Image
+              source={{ uri: message.uri }}
+              style={styles.image}
+              resizeMode="cover"
+            />
+            {message.text ? (
+              <Text style={[styles.text, { color: textColor, marginTop: 6 }]}>
+                {message.text}
+              </Text>
+            ) : null}
+          </Pressable>
+        )}
+
+        {message.contentType === "voice" && (
+          <Pressable
+            onPress={() => onPlayVoice?.(message)}
+            style={({ pressed }) => [styles.voiceRow, pressed && { opacity: 0.7 }]}
+          >
+            <MaterialIcons
+              name={isPlayingVoice ? "pause" : "play-arrow"}
+              size={24}
+              color={textColor}
+            />
+            <View style={[styles.waveform, { backgroundColor: isUser ? "rgba(255,255,255,0.3)" : colors.border }]}>
+              {waveHeights.map((h, i) => (
+                <View
+                  key={i}
+                  style={[
+                    styles.waveBar,
+                    {
+                      height: h,
+                      backgroundColor: textColor,
+                      opacity: 0.6,
+                    },
+                  ]}
+                />
+              ))}
+            </View>
+            <Text style={[styles.duration, { color: mutedColor }]}>
+              {formatDuration(message.duration ?? 0)}
+            </Text>
+          </Pressable>
+        )}
+
+        {message.contentType === "file" && (
+          <View style={styles.fileRow}>
+            <MaterialIcons name="insert-drive-file" size={28} color={textColor} />
+            <View style={styles.fileInfo}>
+              <Text style={[styles.fileName, { color: textColor }]} numberOfLines={1}>
+                {message.fileName ?? "File"}
+              </Text>
+              <Text style={[styles.fileSize, { color: mutedColor }]}>
+                {formatBytes(message.fileSize ?? 0)}
+              </Text>
+            </View>
+          </View>
+        )}
+
+        <Text style={[styles.time, { color: mutedColor }]}>{timeStr}</Text>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: "row",
+    marginBottom: 8,
+    paddingHorizontal: 12,
+    alignItems: "flex-end",
+  },
+  rowUser: {
+    justifyContent: "flex-end",
+  },
+  rowAssistant: {
+    justifyContent: "flex-start",
+  },
+  avatar: {
+    width: 30,
+    height: 30,
+    borderRadius: 15,
+    alignItems: "center",
+    justifyContent: "center",
+    marginRight: 8,
+  },
+  avatarText: {
+    color: "#fff",
+    fontWeight: "700",
+    fontSize: 14,
+  },
+  bubble: {
+    maxWidth: "78%",
+    borderRadius: 16,
+    borderWidth: 1,
+    paddingHorizontal: 14,
+    paddingVertical: 10,
+  },
+  text: {
+    fontSize: 15,
+    lineHeight: 21,
+  },
+  time: {
+    fontSize: 10,
+    marginTop: 4,
+    textAlign: "right",
+  },
+  image: {
+    width: 220,
+    height: 180,
+    borderRadius: 10,
+  },
+  voiceRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+    minWidth: 160,
+  },
+  waveform: {
+    flex: 1,
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 2,
+    height: 24,
+    borderRadius: 4,
+    paddingHorizontal: 4,
+  },
+  waveBar: {
+    width: 3,
+    borderRadius: 1.5,
+  },
+  duration: {
+    fontSize: 12,
+    minWidth: 32,
+  },
+  fileRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 10,
+  },
+  fileInfo: {
+    flex: 1,
+  },
+  fileName: {
+    fontSize: 14,
+    fontWeight: "600",
+  },
+  fileSize: {
+    fontSize: 11,
+    marginTop: 2,
+  },
+});
diff --git a/mobile-app/components/chat-header.tsx b/mobile-app/components/chat-header.tsx
new file mode 100644
index 0000000..4fcdc17
--- /dev/null
+++ b/mobile-app/components/chat-header.tsx
@@ -0,0 +1,69 @@
+import { View, Text, StyleSheet } from "react-native";
+import Pressable from "@/components/ui/pressable-fix";
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+import { useColors } from "@/hooks/use-colors";
+import { useChat } from "@/lib/chat-store";
+
+export function ChatHeader() {
+  const colors = useColors();
+  const { clearChat } = useChat();
+
+  return (
+    <View style={[styles.header, { backgroundColor: colors.background, borderBottomColor: colors.border }]}>
+      <View style={styles.left}>
+        <View style={[styles.statusDot, { backgroundColor: colors.success }]} />
+        <Text style={[styles.title, { color: colors.foreground }]}>TIMMY</Text>
+        <Text style={[styles.subtitle, { color: colors.muted }]}>SOVEREIGN AI</Text>
+      </View>
+      <Pressable
+        onPress={clearChat}
+        style={({ pressed }: { pressed: boolean }) => [
+          styles.clearBtn,
+          { borderColor: colors.border },
+          pressed && { opacity: 0.6 },
+        ]}
+      >
+        <MaterialIcons name="delete-outline" size={16} color={colors.muted} />
+      </Pressable>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  header: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    paddingHorizontal: 16,
+    paddingVertical: 10,
+    borderBottomWidth: 1,
+  },
+  left: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+  },
+  statusDot: {
+    width: 8,
+    height: 8,
+    borderRadius: 4,
+  },
+  title: {
+    fontSize: 16,
+    fontWeight: "700",
+    letterSpacing: 2,
+  },
+  subtitle: {
+    fontSize: 9,
+    letterSpacing: 1.5,
+    fontWeight: "600",
+  },
+  clearBtn: {
+    width: 32,
+    height: 32,
+    borderRadius: 16,
+    borderWidth: 1,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+});
diff --git a/mobile-app/components/chat-input.tsx b/mobile-app/components/chat-input.tsx
new file mode 100644
index 0000000..5654555
--- /dev/null
+++ b/mobile-app/components/chat-input.tsx
@@ -0,0 +1,301 @@
+import { useCallback, useRef, useState } from "react";
+import {
+  View,
+  TextInput,
+  StyleSheet,
+  Platform,
+  ActionSheetIOS,
+  Alert,
+  Keyboard,
+} from "react-native";
+import Pressable from "@/components/ui/pressable-fix";
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+import { useColors } from "@/hooks/use-colors";
+import { useChat } from "@/lib/chat-store";
+import * as ImagePicker from "expo-image-picker";
+import * as DocumentPicker from "expo-document-picker";
+import {
+  useAudioRecorder,
+  useAudioRecorderState,
+  RecordingPresets,
+  requestRecordingPermissionsAsync,
+  setAudioModeAsync,
+} from "expo-audio";
+import * as Haptics from "expo-haptics";
+
+export function ChatInput() {
+  const colors = useColors();
+  const { sendTextMessage, sendAttachment, isTyping } = useChat();
+  const [text, setText] = useState("");
+  const [isRecording, setIsRecording] = useState(false);
+  const inputRef = useRef<TextInput>(null);
+
+  const audioRecorder = useAudioRecorder(RecordingPresets.HIGH_QUALITY);
+  const recorderState = useAudioRecorderState(audioRecorder);
+
+  const handleSend = useCallback(() => {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    setText("");
+    Keyboard.dismiss();
+    if (Platform.OS !== "web") {
+      Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
+    }
+    sendTextMessage(trimmed);
+  }, [text, sendTextMessage]);
+
+  // ── Attachment sheet ────────────────────────────────────────────────────
+
+  const handleAttachment = useCallback(() => {
+    if (Platform.OS !== "web") {
+      Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
+    }
+
+    const options = ["Take Photo", "Choose from Library", "Choose File", "Cancel"];
+    const cancelIndex = 3;
+
+    if (Platform.OS === "ios") {
+      ActionSheetIOS.showActionSheetWithOptions(
+        { options, cancelButtonIndex: cancelIndex },
+        (idx) => {
+          if (idx === 0) takePhoto();
+          else if (idx === 1) pickImage();
+          else if (idx === 2) pickFile();
+        },
+      );
+    } else {
+      // Android / Web fallback
+      Alert.alert("Attach", "Choose an option", [
+        { text: "Take Photo", onPress: takePhoto },
+        { text: "Choose from Library", onPress: pickImage },
+        { text: "Choose File", onPress: pickFile },
+        { text: "Cancel", style: "cancel" },
+      ]);
+    }
+  }, []);
+
+  const takePhoto = async () => {
+    const { status } = await ImagePicker.requestCameraPermissionsAsync();
+    if (status !== "granted") {
+      Alert.alert("Permission needed", "Camera access is required to take photos.");
+      return;
+    }
+    const result = await ImagePicker.launchCameraAsync({
+      quality: 0.8,
+      allowsEditing: false,
+    });
+    if (!result.canceled && result.assets[0]) {
+      const asset = result.assets[0];
+      sendAttachment({
+        contentType: "image",
+        uri: asset.uri,
+        fileName: asset.fileName ?? "photo.jpg",
+        fileSize: asset.fileSize,
+        mimeType: asset.mimeType ?? "image/jpeg",
+      });
+    }
+  };
+
+  const pickImage = async () => {
+    const result = await ImagePicker.launchImageLibraryAsync({
+      mediaTypes: ["images"],
+      quality: 0.8,
+      allowsEditing: false,
+    });
+    if (!result.canceled && result.assets[0]) {
+      const asset = result.assets[0];
+      sendAttachment({
+        contentType: "image",
+        uri: asset.uri,
+        fileName: asset.fileName ?? "image.jpg",
+        fileSize: asset.fileSize,
+        mimeType: asset.mimeType ?? "image/jpeg",
+      });
+    }
+  };
+
+  const pickFile = async () => {
+    try {
+      const result = await DocumentPicker.getDocumentAsync({
+        type: "*/*",
+        copyToCacheDirectory: true,
+      });
+      if (!result.canceled && result.assets[0]) {
+        const asset = result.assets[0];
+        sendAttachment({
+          contentType: "file",
+          uri: asset.uri,
+          fileName: asset.name,
+          fileSize: asset.size,
+          mimeType: asset.mimeType ?? "application/octet-stream",
+        });
+      }
+    } catch (err) {
+      console.warn("Document picker error:", err);
+    }
+  };
+
+  // ── Voice recording ───────────────────────────────────────────────────
+
+  const startRecording = async () => {
+    try {
+      const { granted } = await requestRecordingPermissionsAsync();
+      if (!granted) {
+        Alert.alert("Permission needed", "Microphone access is required for voice messages.");
+        return;
+      }
+      await setAudioModeAsync({ playsInSilentMode: true, allowsRecording: true });
+      await audioRecorder.prepareToRecordAsync();
+      audioRecorder.record();
+      setIsRecording(true);
+      if (Platform.OS !== "web") {
+        Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium);
+      }
+    } catch (err) {
+      console.warn("Recording start error:", err);
+    }
+  };
+
+  const stopRecording = async () => {
+    try {
+      await audioRecorder.stop();
+      setIsRecording(false);
+      if (Platform.OS !== "web") {
+        Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
+      }
+      const uri = audioRecorder.uri;
+      if (uri) {
+        const duration = recorderState.durationMillis ? recorderState.durationMillis / 1000 : 0;
+        sendAttachment({
+          contentType: "voice",
+          uri,
+          fileName: "voice_message.m4a",
+          mimeType: "audio/m4a",
+          duration,
+        });
+      }
+    } catch (err) {
+      console.warn("Recording stop error:", err);
+      setIsRecording(false);
+    }
+  };
+
+  const handleMicPress = useCallback(() => {
+    if (isRecording) {
+      stopRecording();
+    } else {
+      startRecording();
+    }
+  }, [isRecording]);
+
+  const hasText = text.trim().length > 0;
+
+  return (
+    <View style={[styles.container, { backgroundColor: colors.background, borderTopColor: colors.border }]}>
+      {/* Attachment button */}
+      <Pressable
+        onPress={handleAttachment}
+        style={({ pressed }: { pressed: boolean }) => [
+          styles.iconBtn,
+          { backgroundColor: colors.surface },
+          pressed && { opacity: 0.6 },
+        ]}
+        disabled={isTyping}
+      >
+        <MaterialIcons name="add" size={22} color={colors.muted} />
+      </Pressable>
+
+      {/* Text input */}
+      <TextInput
+        ref={inputRef}
+        value={text}
+        onChangeText={setText}
+        placeholder={isRecording ? "Recording..." : "Message Timmy..."}
+        placeholderTextColor={colors.muted}
+        style={[
+          styles.input,
+          {
+            backgroundColor: colors.surface,
+            color: colors.foreground,
+            borderColor: colors.border,
+          },
+        ]}
+        multiline
+        maxLength={4000}
+        returnKeyType="default"
+        editable={!isRecording && !isTyping}
+        onSubmitEditing={handleSend}
+        blurOnSubmit={false}
+      />
+
+      {/* Send or Mic button */}
+      {hasText ? (
+        <Pressable
+          onPress={handleSend}
+          style={({ pressed }: { pressed: boolean }) => [
+            styles.sendBtn,
+            { backgroundColor: colors.primary },
+            pressed && { transform: [{ scale: 0.95 }], opacity: 0.9 },
+          ]}
+          disabled={isTyping}
+        >
+          <MaterialIcons name="send" size={20} color="#fff" />
+        </Pressable>
+      ) : (
+        <Pressable
+          onPress={handleMicPress}
+          style={({ pressed }: { pressed: boolean }) => [
+            styles.sendBtn,
+            {
+              backgroundColor: isRecording ? colors.error : colors.surface,
+            },
+            pressed && { transform: [{ scale: 0.95 }], opacity: 0.9 },
+          ]}
+          disabled={isTyping}
+        >
+          <MaterialIcons
+            name={isRecording ? "stop" : "mic"}
+            size={20}
+            color={isRecording ? "#fff" : colors.primary}
+          />
+        </Pressable>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: "row",
+    alignItems: "flex-end",
+    paddingHorizontal: 10,
+    paddingVertical: 8,
+    gap: 8,
+    borderTopWidth: 1,
+  },
+  iconBtn: {
+    width: 38,
+    height: 38,
+    borderRadius: 19,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  input: {
+    flex: 1,
+    minHeight: 38,
+    maxHeight: 120,
+    borderRadius: 19,
+    borderWidth: 1,
+    paddingHorizontal: 14,
+    paddingVertical: 8,
+    fontSize: 15,
+    lineHeight: 20,
+  },
+  sendBtn: {
+    width: 38,
+    height: 38,
+    borderRadius: 19,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+});
diff --git a/mobile-app/components/empty-chat.tsx b/mobile-app/components/empty-chat.tsx
new file mode 100644
index 0000000..f2a488c
--- /dev/null
+++ b/mobile-app/components/empty-chat.tsx
@@ -0,0 +1,55 @@
+import { View, Text, StyleSheet } from "react-native";
+import { useColors } from "@/hooks/use-colors";
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+
+export function EmptyChat() {
+  const colors = useColors();
+
+  return (
+    <View style={styles.container}>
+      <View style={[styles.iconCircle, { backgroundColor: colors.surface, borderColor: colors.border }]}>
+        <MaterialIcons name="chat-bubble-outline" size={40} color={colors.primary} />
+      </View>
+      <Text style={[styles.title, { color: colors.foreground }]}>TIMMY</Text>
+      <Text style={[styles.subtitle, { color: colors.muted }]}>SOVEREIGN AI AGENT</Text>
+      <Text style={[styles.hint, { color: colors.muted }]}>
+        Send a message, voice note, image, or file to get started.
+      </Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+    paddingHorizontal: 40,
+    gap: 8,
+  },
+  iconCircle: {
+    width: 80,
+    height: 80,
+    borderRadius: 40,
+    borderWidth: 1,
+    alignItems: "center",
+    justifyContent: "center",
+    marginBottom: 12,
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: "700",
+    letterSpacing: 4,
+  },
+  subtitle: {
+    fontSize: 11,
+    letterSpacing: 2,
+    fontWeight: "600",
+  },
+  hint: {
+    fontSize: 13,
+    textAlign: "center",
+    marginTop: 12,
+    lineHeight: 19,
+  },
+});
diff --git a/mobile-app/components/haptic-tab.tsx b/mobile-app/components/haptic-tab.tsx
new file mode 100644
index 0000000..a567476
--- /dev/null
+++ b/mobile-app/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);
+      }}
+    />
+  );
+}
diff --git a/mobile-app/components/image-viewer.tsx b/mobile-app/components/image-viewer.tsx
new file mode 100644
index 0000000..e37dfe0
--- /dev/null
+++ b/mobile-app/components/image-viewer.tsx
@@ -0,0 +1,54 @@
+import { Modal, View, Image, StyleSheet, StatusBar } from "react-native";
+import Pressable from "@/components/ui/pressable-fix";
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+
+interface ImageViewerProps {
+  uri: string | null;
+  onClose: () => void;
+}
+
+export function ImageViewer({ uri, onClose }: ImageViewerProps) {
+  if (!uri) return null;
+
+  return (
+    <Modal visible animationType="fade" transparent statusBarTranslucent>
+      <View style={styles.overlay}>
+        <StatusBar barStyle="light-content" />
+        <Image source={{ uri }} style={styles.image} resizeMode="contain" />
+        <Pressable
+          onPress={onClose}
+          style={({ pressed }: { pressed: boolean }) => [
+            styles.closeBtn,
+            pressed && { opacity: 0.6 },
+          ]}
+        >
+          <MaterialIcons name="close" size={28} color="#fff" />
+        </Pressable>
+      </View>
+    </Modal>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlay: {
+    flex: 1,
+    backgroundColor: "rgba(0,0,0,0.95)",
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  image: {
+    width: "100%",
+    height: "80%",
+  },
+  closeBtn: {
+    position: "absolute",
+    top: 50,
+    right: 20,
+    width: 40,
+    height: 40,
+    borderRadius: 20,
+    backgroundColor: "rgba(255,255,255,0.15)",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+});
diff --git a/mobile-app/components/screen-container.tsx b/mobile-app/components/screen-container.tsx
new file mode 100644
index 0000000..20b0b99
--- /dev/null
+++ b/mobile-app/components/screen-container.tsx
@@ -0,0 +1,68 @@
+import { View, type ViewProps } from "react-native";
+import { SafeAreaView, type Edge } from "react-native-safe-area-context";
+
+import { cn } from "@/lib/utils";
+
+export interface ScreenContainerProps extends ViewProps {
+  /**
+   * SafeArea edges to apply. Defaults to ["top", "left", "right"].
+   * Bottom is typically handled by Tab Bar.
+   */
+  edges?: Edge[];
+  /**
+   * Tailwind className for the content area.
+   */
+  className?: string;
+  /**
+   * Additional className for the outer container (background layer).
+   */
+  containerClassName?: string;
+  /**
+   * Additional className for the SafeAreaView (content layer).
+   */
+  safeAreaClassName?: string;
+}
+
+/**
+ * A container component that properly handles SafeArea and background colors.
+ *
+ * The outer View extends to full screen (including status bar area) with the background color,
+ * while the inner SafeAreaView ensures content is within safe bounds.
+ *
+ * Usage:
+ * ```tsx
+ * <ScreenContainer className="p-4">
+ *   <Text className="text-2xl font-bold text-foreground">
+ *     Welcome
+ *   </Text>
+ * </ScreenContainer>
+ * ```
+ */
+export function ScreenContainer({
+  children,
+  edges = ["top", "left", "right"],
+  className,
+  containerClassName,
+  safeAreaClassName,
+  style,
+  ...props
+}: ScreenContainerProps) {
+  return (
+    <View
+      className={cn(
+        "flex-1",
+        "bg-background",
+        containerClassName
+      )}
+      {...props}
+    >
+      <SafeAreaView
+        edges={edges}
+        className={cn("flex-1", safeAreaClassName)}
+        style={style}
+      >
+        <View className={cn("flex-1", className)}>{children}</View>
+      </SafeAreaView>
+    </View>
+  );
+}
diff --git a/mobile-app/components/themed-view.tsx b/mobile-app/components/themed-view.tsx
new file mode 100644
index 0000000..2959350
--- /dev/null
+++ b/mobile-app/components/themed-view.tsx
@@ -0,0 +1,15 @@
+import { View, type ViewProps } from "react-native";
+
+import { cn } from "@/lib/utils";
+
+export interface ThemedViewProps extends ViewProps {
+  className?: string;
+}
+
+/**
+ * A View component with automatic theme-aware background.
+ * Uses NativeWind for styling - pass className for additional styles.
+ */
+export function ThemedView({ className, ...otherProps }: ThemedViewProps) {
+  return <View className={cn("bg-background", className)} {...otherProps} />;
+}
diff --git a/mobile-app/components/typing-indicator.tsx b/mobile-app/components/typing-indicator.tsx
new file mode 100644
index 0000000..6dcee97
--- /dev/null
+++ b/mobile-app/components/typing-indicator.tsx
@@ -0,0 +1,89 @@
+import { useEffect } from "react";
+import { View, StyleSheet } from "react-native";
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withRepeat,
+  withTiming,
+  withDelay,
+  withSequence,
+} from "react-native-reanimated";
+import { useColors } from "@/hooks/use-colors";
+
+export function TypingIndicator() {
+  const colors = useColors();
+  const dot1 = useSharedValue(0.3);
+  const dot2 = useSharedValue(0.3);
+  const dot3 = useSharedValue(0.3);
+
+  useEffect(() => {
+    const anim = (sv: { value: number }, delay: number) => {
+      sv.value = withDelay(
+        delay,
+        withRepeat(
+          withSequence(
+            withTiming(1, { duration: 400 }),
+            withTiming(0.3, { duration: 400 }),
+          ),
+          -1,
+        ),
+      );
+    };
+    anim(dot1, 0);
+    anim(dot2, 200);
+    anim(dot3, 400);
+  }, []);
+
+  const style1 = useAnimatedStyle(() => ({ opacity: dot1.value }));
+  const style2 = useAnimatedStyle(() => ({ opacity: dot2.value }));
+  const style3 = useAnimatedStyle(() => ({ opacity: dot3.value }));
+
+  const dotBase = [styles.dot, { backgroundColor: colors.primary }];
+
+  return (
+    <View style={[styles.row, { alignItems: "flex-end" }]}>
+      <View style={[styles.avatar, { backgroundColor: colors.primary }]}>
+        <Animated.Text style={styles.avatarText}>T</Animated.Text>
+      </View>
+      <View style={[styles.bubble, { backgroundColor: colors.surface, borderColor: colors.border }]}>
+        <Animated.View style={[dotBase, style1]} />
+        <Animated.View style={[dotBase, style2]} />
+        <Animated.View style={[dotBase, style3]} />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: "row",
+    paddingHorizontal: 12,
+    marginBottom: 8,
+  },
+  avatar: {
+    width: 30,
+    height: 30,
+    borderRadius: 15,
+    alignItems: "center",
+    justifyContent: "center",
+    marginRight: 8,
+  },
+  avatarText: {
+    color: "#fff",
+    fontWeight: "700",
+    fontSize: 14,
+  },
+  bubble: {
+    flexDirection: "row",
+    gap: 5,
+    paddingHorizontal: 16,
+    paddingVertical: 14,
+    borderRadius: 16,
+    borderWidth: 1,
+  },
+  dot: {
+    width: 8,
+    height: 8,
+    borderRadius: 4,
+  },
+});
diff --git a/mobile-app/components/ui/icon-symbol.tsx b/mobile-app/components/ui/icon-symbol.tsx
new file mode 100644
index 0000000..12c226c
--- /dev/null
+++ b/mobile-app/components/ui/icon-symbol.tsx
@@ -0,0 +1,41 @@
+// Fallback for using MaterialIcons on Android and web.
+
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+import { SymbolWeight, SymbolViewProps } from "expo-symbols";
+import { ComponentProps } from "react";
+import { OpaqueColorValue, type StyleProp, type TextStyle } from "react-native";
+
+type IconMapping = Record<SymbolViewProps["name"], ComponentProps<typeof MaterialIcons>["name"]>;
+type IconSymbolName = keyof typeof MAPPING;
+
+/**
+ * Add your SF Symbols to Material Icons mappings here.
+ * - see Material Icons in the [Icons Directory](https://icons.expo.fyi).
+ * - see SF Symbols in the [SF Symbols](https://developer.apple.com/sf-symbols/) app.
+ */
+const MAPPING = {
+  "house.fill": "home",
+  "paperplane.fill": "send",
+  "chevron.left.forwardslash.chevron.right": "code",
+  "chevron.right": "chevron-right",
+} as IconMapping;
+
+/**
+ * An icon component that uses native SF Symbols on iOS, and Material Icons on Android and web.
+ * This ensures a consistent look across platforms, and optimal resource usage.
+ * Icon `name`s are based on SF Symbols and require manual mapping to Material Icons.
+ */
+export function IconSymbol({
+  name,
+  size = 24,
+  color,
+  style,
+}: {
+  name: IconSymbolName;
+  size?: number;
+  color: string | OpaqueColorValue;
+  style?: StyleProp<TextStyle>;
+  weight?: SymbolWeight;
+}) {
+  return <MaterialIcons color={color} size={size} name={MAPPING[name]} style={style} />;
+}
diff --git a/mobile-app/components/ui/pressable-fix.tsx b/mobile-app/components/ui/pressable-fix.tsx
new file mode 100644
index 0000000..d44c0d5
--- /dev/null
+++ b/mobile-app/components/ui/pressable-fix.tsx
@@ -0,0 +1,6 @@
+/**
+ * Re-export Pressable with proper typing for style callbacks.
+ * NativeWind disables className on Pressable, so we always use the style prop.
+ */
+import { Pressable } from "react-native";
+export default Pressable;
diff --git a/mobile-app/constants/theme.ts b/mobile-app/constants/theme.ts
new file mode 100644
index 0000000..7dc18b1
--- /dev/null
+++ b/mobile-app/constants/theme.ts
@@ -0,0 +1,12 @@
+/**
+ * Thin re-exports so consumers don't need to know about internal theme plumbing.
+ * Full implementation lives in lib/_core/theme.ts.
+ */
+export {
+  Colors,
+  Fonts,
+  SchemeColors,
+  ThemeColors,
+  type ColorScheme,
+  type ThemeColorPalette,
+} from "@/lib/_core/theme";
diff --git a/mobile-app/design.md b/mobile-app/design.md
new file mode 100644
index 0000000..275a985
--- /dev/null
+++ b/mobile-app/design.md
@@ -0,0 +1,80 @@
+# Timmy Chat — Mobile App Design
+
+## Overview
+A sleek, single-screen chat app for talking to Timmy — the sovereign AI agent from the Timmy Time dashboard. Supports text, voice, image, and file messaging. Dark arcane theme matching Mission Control.
+
+## Screen List
+
+### 1. Chat Screen (Home / Only Screen)
+The entire app is a single full-screen chat interface. No tabs, no settings, no extra screens. Just you and Timmy.
+
+### 2. No Other Screens
+No settings, no profile, no onboarding. The app opens straight to chat.
+
+## Primary Content and Functionality
+
+### Chat Screen
+- **Header**: "TIMMY" title with status indicator (online/offline dot), minimal and clean
+- **Message List**: Full-screen scrollable message list (FlatList, inverted)
+  - User messages: right-aligned, purple/violet accent bubble
+  - Timmy messages: left-aligned, dark surface bubble with avatar initial "T"
+  - Image messages: thumbnail preview in bubble, tappable for full-screen
+  - File messages: file icon + filename + size in bubble
+  - Voice messages: waveform-style playback bar with play/pause + duration
+  - Timestamps shown subtly below message groups
+- **Input Bar** (bottom, always visible):
+  - Text input field (expandable, multi-line)
+  - Attachment button (left of input) — opens action sheet: Camera, Photo Library, File
+  - Voice record button (right of input, replaces send when input is empty)
+  - Send button (right of input, appears when text is entered)
+  - Hold-to-record voice: press and hold mic icon, release to send
+
+## Key User Flows
+
+### Text Chat
+1. User types message → taps Send
+2. Message appears in chat as "sending"
+3. Server responds → Timmy's reply appears below
+
+### Voice Message
+1. User presses and holds mic button
+2. Recording indicator appears (duration + pulsing dot)
+3. User releases → voice message sent
+4. Timmy responds with text (server processes audio)
+
+### Image Sharing
+1. User taps attachment (+) button
+2. Action sheet: "Take Photo" / "Choose from Library"
+3. Image appears as thumbnail in chat
+4. Timmy acknowledges receipt
+
+### File Sharing
+1. User taps attachment (+) button → "Choose File"
+2. Document picker opens
+3. File appears in chat with name + size
+4. Timmy acknowledges receipt
+
+## Color Choices (Arcane Dark Theme)
+
+Matching the Timmy Time Mission Control dashboard:
+
+| Token       | Dark Value   | Purpose                        |
+|-------------|-------------|--------------------------------|
+| background  | #080412     | Deep dark purple-black          |
+| surface     | #110820     | Card/bubble background          |
+| foreground  | #ede0ff     | Primary text (bright lavender)  |
+| muted       | #6b4a8a     | Secondary/timestamp text        |
+| primary     | #a855f7     | Accent purple (user bubbles)    |
+| border      | #3b1a5c     | Subtle borders                  |
+| success     | #00e87a     | Online status, success          |
+| warning     | #ffb800     | Amber warnings                  |
+| error       | #ff4455     | Error states                    |
+
+## Layout Specifics (Portrait 9:16, One-Handed)
+
+- Input bar pinned to bottom with safe area padding
+- Send/mic button on right (thumb-reachable)
+- Attachment button on left of input
+- Messages fill remaining space above input
+- No tab bar — single screen app
+- Header is compact (44pt) with just title + status dot
diff --git a/mobile-app/global.css b/mobile-app/global.css
new file mode 100644
index 0000000..b5c61c9
--- /dev/null
+++ b/mobile-app/global.css
@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
diff --git a/mobile-app/hooks/use-color-scheme.ts b/mobile-app/hooks/use-color-scheme.ts
new file mode 100644
index 0000000..670e0f0
--- /dev/null
+++ b/mobile-app/hooks/use-color-scheme.ts
@@ -0,0 +1,5 @@
+import { useThemeContext } from "@/lib/theme-provider";
+
+export function useColorScheme() {
+  return useThemeContext().colorScheme;
+}
diff --git a/mobile-app/hooks/use-color-scheme.web.ts b/mobile-app/hooks/use-color-scheme.web.ts
new file mode 100644
index 0000000..66cccac
--- /dev/null
+++ b/mobile-app/hooks/use-color-scheme.web.ts
@@ -0,0 +1,21 @@
+import { useEffect, useState } from "react";
+import { useColorScheme as useRNColorScheme } from "react-native";
+
+/**
+ * To support static rendering, this value needs to be re-calculated on the client side for web
+ */
+export function useColorScheme() {
+  const [hasHydrated, setHasHydrated] = useState(false);
+
+  useEffect(() => {
+    setHasHydrated(true);
+  }, []);
+
+  const colorScheme = useRNColorScheme();
+
+  if (hasHydrated) {
+    return colorScheme;
+  }
+
+  return "light";
+}
diff --git a/mobile-app/hooks/use-colors.ts b/mobile-app/hooks/use-colors.ts
new file mode 100644
index 0000000..f891d27
--- /dev/null
+++ b/mobile-app/hooks/use-colors.ts
@@ -0,0 +1,12 @@
+import { Colors, type ColorScheme, type ThemeColorPalette } from "@/constants/theme";
+import { useColorScheme } from "./use-color-scheme";
+
+/**
+ * Returns the current theme's color palette.
+ * Usage: const colors = useColors(); then colors.text, colors.background, etc.
+ */
+export function useColors(colorSchemeOverride?: ColorScheme): ThemeColorPalette {
+  const colorSchema = useColorScheme();
+  const scheme = (colorSchemeOverride ?? colorSchema ?? "light") as ColorScheme;
+  return Colors[scheme];
+}
diff --git a/mobile-app/lib/chat-store.tsx b/mobile-app/lib/chat-store.tsx
new file mode 100644
index 0000000..f56b51c
--- /dev/null
+++ b/mobile-app/lib/chat-store.tsx
@@ -0,0 +1,298 @@
+import React, { createContext, useCallback, useContext, useReducer, type ReactNode } from "react";
+import type { ChatMessage, MessageContentType } from "@/shared/types";
+
+// ── State ───────────────────────────────────────────────────────────────────
+
+interface ChatState {
+  messages: ChatMessage[];
+  isTyping: boolean;
+}
+
+const initialState: ChatState = {
+  messages: [],
+  isTyping: false,
+};
+
+// ── Actions ─────────────────────────────────────────────────────────────────
+
+type ChatAction =
+  | { type: "ADD_MESSAGE"; message: ChatMessage }
+  | { type: "UPDATE_MESSAGE"; id: string; updates: Partial<ChatMessage> }
+  | { type: "SET_TYPING"; isTyping: boolean }
+  | { type: "CLEAR" };
+
+function chatReducer(state: ChatState, action: ChatAction): ChatState {
+  switch (action.type) {
+    case "ADD_MESSAGE":
+      return { ...state, messages: [...state.messages, action.message] };
+    case "UPDATE_MESSAGE":
+      return {
+        ...state,
+        messages: state.messages.map((m) =>
+          m.id === action.id ? { ...m, ...action.updates } : m,
+        ),
+      };
+    case "SET_TYPING":
+      return { ...state, isTyping: action.isTyping };
+    case "CLEAR":
+      return initialState;
+    default:
+      return state;
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+let _counter = 0;
+function makeId(): string {
+  return `msg_${Date.now()}_${++_counter}`;
+}
+
+// ── Context ─────────────────────────────────────────────────────────────────
+
+interface ChatContextValue {
+  messages: ChatMessage[];
+  isTyping: boolean;
+  sendTextMessage: (text: string) => Promise<void>;
+  sendAttachment: (opts: {
+    contentType: MessageContentType;
+    uri: string;
+    fileName?: string;
+    fileSize?: number;
+    mimeType?: string;
+    duration?: number;
+    text?: string;
+  }) => Promise<void>;
+  clearChat: () => void;
+}
+
+const ChatContext = createContext<ChatContextValue | null>(null);
+
+// ── API call ────────────────────────────────────────────────────────────────
+
+function getApiBase(): string {
+  // Set EXPO_PUBLIC_API_BASE_URL in your .env to point to your Timmy backend
+  // e.g. EXPO_PUBLIC_API_BASE_URL=http://192.168.1.100:3000
+  const envBase = process.env.EXPO_PUBLIC_API_BASE_URL;
+  if (envBase) return envBase.replace(/\/+$/, "");
+  // Fallback for web: derive from window location
+  if (typeof window !== "undefined" && window.location) {
+    return `${window.location.protocol}//${window.location.hostname}:3000`;
+  }
+  // Default: local machine
+  return "http://127.0.0.1:3000";
+}
+
+const API_BASE = getApiBase();
+
+async function callChatAPI(
+  messages: Array<{ role: string; content: string | Array<Record<string, unknown>> }>,
+): Promise<string> {
+  const res = await fetch(`${API_BASE}/api/chat`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ messages }),
+  });
+  if (!res.ok) {
+    const errText = await res.text().catch(() => res.statusText);
+    throw new Error(`Chat API error: ${errText}`);
+  }
+  const data = await res.json();
+  return data.reply ?? data.text ?? "...";
+}
+
+async function uploadFile(
+  uri: string,
+  fileName: string,
+  mimeType: string,
+): Promise<string> {
+  const formData = new FormData();
+  formData.append("file", {
+    uri,
+    name: fileName,
+    type: mimeType,
+  } as unknown as Blob);
+
+  const res = await fetch(`${API_BASE}/api/upload`, {
+    method: "POST",
+    body: formData,
+  });
+  if (!res.ok) throw new Error("Upload failed");
+  const data = await res.json();
+  return data.url;
+}
+
+// ── Provider ────────────────────────────────────────────────────────────────
+
+export function ChatProvider({ children }: { children: ReactNode }) {
+  const [state, dispatch] = useReducer(chatReducer, initialState);
+
+  const sendTextMessage = useCallback(
+    async (text: string) => {
+      const userMsg: ChatMessage = {
+        id: makeId(),
+        role: "user",
+        contentType: "text",
+        text,
+        timestamp: Date.now(),
+      };
+      dispatch({ type: "ADD_MESSAGE", message: userMsg });
+      dispatch({ type: "SET_TYPING", isTyping: true });
+
+      try {
+        // Build conversation context (last 20 messages)
+        const recent = [...state.messages, userMsg].slice(-20);
+        const apiMessages = recent
+          .filter((m) => m.contentType === "text" && m.text)
+          .map((m) => ({ role: m.role, content: m.text! }));
+
+        const reply = await callChatAPI(apiMessages);
+        const assistantMsg: ChatMessage = {
+          id: makeId(),
+          role: "assistant",
+          contentType: "text",
+          text: reply,
+          timestamp: Date.now(),
+        };
+        dispatch({ type: "ADD_MESSAGE", message: assistantMsg });
+      } catch (err: unknown) {
+        const errorText = err instanceof Error ? err.message : "Something went wrong";
+        dispatch({
+          type: "ADD_MESSAGE",
+          message: {
+            id: makeId(),
+            role: "assistant",
+            contentType: "text",
+            text: `Sorry, I couldn't process that: ${errorText}`,
+            timestamp: Date.now(),
+          },
+        });
+      } finally {
+        dispatch({ type: "SET_TYPING", isTyping: false });
+      }
+    },
+    [state.messages],
+  );
+
+  const sendAttachment = useCallback(
+    async (opts: {
+      contentType: MessageContentType;
+      uri: string;
+      fileName?: string;
+      fileSize?: number;
+      mimeType?: string;
+      duration?: number;
+      text?: string;
+    }) => {
+      const userMsg: ChatMessage = {
+        id: makeId(),
+        role: "user",
+        contentType: opts.contentType,
+        uri: opts.uri,
+        fileName: opts.fileName,
+        fileSize: opts.fileSize,
+        mimeType: opts.mimeType,
+        duration: opts.duration,
+        text: opts.text,
+        timestamp: Date.now(),
+      };
+      dispatch({ type: "ADD_MESSAGE", message: userMsg });
+      dispatch({ type: "SET_TYPING", isTyping: true });
+
+      try {
+        // Upload file to server
+        const remoteUrl = await uploadFile(
+          opts.uri,
+          opts.fileName ?? "attachment",
+          opts.mimeType ?? "application/octet-stream",
+        );
+        dispatch({ type: "UPDATE_MESSAGE", id: userMsg.id, updates: { remoteUrl } });
+
+        // Build message for LLM
+        let content: string | Array<Record<string, unknown>>;
+        if (opts.contentType === "image") {
+          content = [
+            { type: "text", text: opts.text || "I'm sending you an image." },
+            { type: "image_url", image_url: { url: remoteUrl } },
+          ];
+        } else if (opts.contentType === "voice") {
+          content = [
+            { type: "text", text: "I'm sending you a voice message. Please transcribe and respond." },
+            { type: "file_url", file_url: { url: remoteUrl, mime_type: opts.mimeType ?? "audio/m4a" } },
+          ];
+        } else {
+          content = `I'm sharing a file: ${opts.fileName ?? "file"} (${formatBytes(opts.fileSize ?? 0)})`;
+        }
+
+        const apiMessages = [{ role: "user", content }];
+        const reply = await callChatAPI(apiMessages);
+
+        dispatch({
+          type: "ADD_MESSAGE",
+          message: {
+            id: makeId(),
+            role: "assistant",
+            contentType: "text",
+            text: reply,
+            timestamp: Date.now(),
+          },
+        });
+      } catch (err: unknown) {
+        const errorText = err instanceof Error ? err.message : "Upload failed";
+        dispatch({
+          type: "ADD_MESSAGE",
+          message: {
+            id: makeId(),
+            role: "assistant",
+            contentType: "text",
+            text: `I had trouble processing that attachment: ${errorText}`,
+            timestamp: Date.now(),
+          },
+        });
+      } finally {
+        dispatch({ type: "SET_TYPING", isTyping: false });
+      }
+    },
+    [],
+  );
+
+  const clearChat = useCallback(() => {
+    dispatch({ type: "CLEAR" });
+  }, []);
+
+  return (
+    <ChatContext.Provider
+      value={{
+        messages: state.messages,
+        isTyping: state.isTyping,
+        sendTextMessage,
+        sendAttachment,
+        clearChat,
+      }}
+    >
+      {children}
+    </ChatContext.Provider>
+  );
+}
+
+export function useChat(): ChatContextValue {
+  const ctx = useContext(ChatContext);
+  if (!ctx) throw new Error("useChat must be used within ChatProvider");
+  return ctx;
+}
+
+// ── Utils ───────────────────────────────────────────────────────────────────
+
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+}
+
+export function formatDuration(seconds: number): string {
+  const m = Math.floor(seconds / 60);
+  const s = Math.floor(seconds % 60);
+  return `${m}:${s.toString().padStart(2, "0")}`;
+}
diff --git a/mobile-app/lib/theme-provider.tsx b/mobile-app/lib/theme-provider.tsx
new file mode 100644
index 0000000..5439acc
--- /dev/null
+++ b/mobile-app/lib/theme-provider.tsx
@@ -0,0 +1,79 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { Appearance, View, useColorScheme as useSystemColorScheme } from "react-native";
+import { colorScheme as nativewindColorScheme, vars } from "nativewind";
+
+import { SchemeColors, type ColorScheme } from "@/constants/theme";
+
+type ThemeContextValue = {
+  colorScheme: ColorScheme;
+  setColorScheme: (scheme: ColorScheme) => void;
+};
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const systemScheme = useSystemColorScheme() ?? "light";
+  const [colorScheme, setColorSchemeState] = useState<ColorScheme>(systemScheme);
+
+  const applyScheme = useCallback((scheme: ColorScheme) => {
+    nativewindColorScheme.set(scheme);
+    Appearance.setColorScheme?.(scheme);
+    if (typeof document !== "undefined") {
+      const root = document.documentElement;
+      root.dataset.theme = scheme;
+      root.classList.toggle("dark", scheme === "dark");
+      const palette = SchemeColors[scheme];
+      Object.entries(palette).forEach(([token, value]) => {
+        root.style.setProperty(`--color-${token}`, value);
+      });
+    }
+  }, []);
+
+  const setColorScheme = useCallback((scheme: ColorScheme) => {
+    setColorSchemeState(scheme);
+    applyScheme(scheme);
+  }, [applyScheme]);
+
+  useEffect(() => {
+    applyScheme(colorScheme);
+  }, [applyScheme, colorScheme]);
+
+  const themeVariables = useMemo(
+    () =>
+      vars({
+        "color-primary": SchemeColors[colorScheme].primary,
+        "color-background": SchemeColors[colorScheme].background,
+        "color-surface": SchemeColors[colorScheme].surface,
+        "color-foreground": SchemeColors[colorScheme].foreground,
+        "color-muted": SchemeColors[colorScheme].muted,
+        "color-border": SchemeColors[colorScheme].border,
+        "color-success": SchemeColors[colorScheme].success,
+        "color-warning": SchemeColors[colorScheme].warning,
+        "color-error": SchemeColors[colorScheme].error,
+      }),
+    [colorScheme],
+  );
+
+  const value = useMemo(
+    () => ({
+      colorScheme,
+      setColorScheme,
+    }),
+    [colorScheme, setColorScheme],
+  );
+  console.log(value, themeVariables)
+
+  return (
+    <ThemeContext.Provider value={value}>
+      <View style={[{ flex: 1 }, themeVariables]}>{children}</View>
+    </ThemeContext.Provider>
+  );
+}
+
+export function useThemeContext(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) {
+    throw new Error("useThemeContext must be used within ThemeProvider");
+  }
+  return ctx;
+}
diff --git a/mobile-app/lib/utils.ts b/mobile-app/lib/utils.ts
new file mode 100644
index 0000000..05eae6b
--- /dev/null
+++ b/mobile-app/lib/utils.ts
@@ -0,0 +1,15 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Combines class names using clsx and tailwind-merge.
+ * This ensures Tailwind classes are properly merged without conflicts.
+ *
+ * Usage:
+ * ```tsx
+ * cn("px-4 py-2", isActive && "bg-primary", className)
+ * ```
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
diff --git a/mobile-app/package.json b/mobile-app/package.json
new file mode 100644
index 0000000..a12844d
--- /dev/null
+++ b/mobile-app/package.json
@@ -0,0 +1,98 @@
+{
+  "name": "app-template",
+  "version": "1.0.0",
+  "private": true,
+  "main": "expo-router/entry",
+  "scripts": {
+    "dev": "concurrently -k \"pnpm dev:server\" \"pnpm dev:metro\"",
+    "dev:server": "cross-env NODE_ENV=development tsx watch server/_core/index.ts",
+    "dev:metro": "cross-env EXPO_USE_METRO_WORKSPACE_ROOT=1 npx expo start --web --port ${EXPO_PORT:-8081}",
+    "build": "esbuild server/_core/index.ts --platform=node --packages=external --bundle --format=esm --outdir=dist",
+    "start": "NODE_ENV=production node dist/index.js",
+    "check": "tsc --noEmit",
+    "lint": "expo lint",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "db:push": "drizzle-kit generate && drizzle-kit migrate",
+    "android": "expo start --android",
+    "ios": "expo start --ios",
+    "qr": "node scripts/generate_qr.mjs"
+  },
+  "dependencies": {
+    "@expo/vector-icons": "^15.0.3",
+    "@react-native-async-storage/async-storage": "^2.2.0",
+    "@react-navigation/bottom-tabs": "^7.8.12",
+    "@react-navigation/elements": "^2.9.2",
+    "@react-navigation/native": "^7.1.25",
+    "@tanstack/react-query": "^5.90.12",
+    "@trpc/client": "11.7.2",
+    "@trpc/react-query": "11.7.2",
+    "@trpc/server": "11.7.2",
+    "axios": "^1.13.2",
+    "clsx": "^2.1.1",
+    "cookie": "^1.1.1",
+    "dotenv": "^16.6.1",
+    "drizzle-orm": "^0.44.7",
+    "expo": "~54.0.29",
+    "expo-audio": "~1.1.0",
+    "expo-build-properties": "^1.0.10",
+    "expo-constants": "~18.0.12",
+    "expo-document-picker": "~14.0.8",
+    "expo-file-system": "~19.0.21",
+    "expo-font": "~14.0.10",
+    "expo-haptics": "~15.0.8",
+    "expo-image": "~3.0.11",
+    "expo-image-picker": "~17.0.10",
+    "expo-keep-awake": "~15.0.8",
+    "expo-linking": "~8.0.10",
+    "expo-notifications": "~0.32.15",
+    "expo-router": "~6.0.19",
+    "expo-secure-store": "~15.0.8",
+    "expo-speech": "~14.0.8",
+    "expo-splash-screen": "~31.0.12",
+    "expo-status-bar": "~3.0.9",
+    "expo-symbols": "~1.0.8",
+    "expo-system-ui": "~6.0.9",
+    "expo-video": "~3.0.15",
+    "expo-web-browser": "~15.0.10",
+    "express": "^4.22.1",
+    "jose": "6.1.0",
+    "mysql2": "^3.16.0",
+    "nativewind": "^4.2.1",
+    "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.6",
+    "react-native-safe-area-context": "~5.6.2",
+    "react-native-screens": "~4.16.0",
+    "react-native-svg": "15.12.1",
+    "react-native-web": "~0.21.2",
+    "react-native-worklets": "0.5.1",
+    "streamdown": "^2.3.0",
+    "superjson": "^1.13.3",
+    "tailwind-merge": "^2.6.0",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@expo/ngrok": "^4.1.3",
+    "@types/cookie": "^0.6.0",
+    "@types/express": "^4.17.25",
+    "@types/node": "^22.19.3",
+    "@types/qrcode": "^1.5.6",
+    "@types/react": "~19.1.17",
+    "concurrently": "^9.2.1",
+    "cross-env": "^7.0.3",
+    "drizzle-kit": "^0.31.8",
+    "esbuild": "^0.25.12",
+    "eslint": "^9.39.2",
+    "eslint-config-expo": "~10.0.0",
+    "prettier": "^3.7.4",
+    "qrcode": "^1.5.4",
+    "tailwindcss": "^3.4.17",
+    "tsx": "^4.21.0",
+    "typescript": "~5.9.3",
+    "vitest": "^2.1.9"
+  },
+  "packageManager": "pnpm@9.12.0"
+}
diff --git a/mobile-app/server/README.md b/mobile-app/server/README.md
new file mode 100644
index 0000000..246c246
--- /dev/null
+++ b/mobile-app/server/README.md
@@ -0,0 +1,1235 @@
+# Backend Development Guide
+
+This guide covers server-side features including authentication, database, tRPC API, and integrations. **Only read this if your app needs these capabilities.**
+
+---
+
+## When Do You Need Backend?
+
+| Scenario | Backend Needed? | User Auth Required? | Solution |
+|----------|-----------------|---------------------|----------|
+| Data stays on device only | No | No | Use `AsyncStorage` |
+| Data syncs across devices | Yes | Yes | Database + tRPC |
+| User accounts / login | Yes | Yes | Manus OAuth |
+| AI-powered features | Yes | **Optional** | LLM Integration |
+| User uploads files | Yes | **Optional** | S3 Storage |
+| Server-side validation | Yes | **Optional** | tRPC procedures |
+
+> **Note:** Backend ≠ User Auth. You can run a backend with LLM/Storage/ImageGen capabilities without requiring user login — just use `publicProcedure` instead of `protectedProcedure`. User auth is only mandatory when you need to identify users or sync user-specific data.
+
+---
+
+## File Structure
+
+```
+server/
+  db.ts              ← Query helpers (add database functions here)
+  routers.ts         ← tRPC procedures (add API routes here)
+  storage.ts         ← S3 storage helpers (can extend)
+  _core/             ← Framework-level code (don't modify)
+drizzle/
+  schema.ts          ← Database tables & types (add your tables here)
+  relations.ts       ← Table relationships
+  migrations/        ← Auto-generated migrations
+shared/
+  types.ts           ← Shared TypeScript types
+  const.ts           ← Shared constants
+  _core/             ← Framework-level code (don't modify)
+lib/
+  trpc.ts            ← tRPC client (can customize headers)
+  _core/             ← Framework-level code (don't modify)
+hooks/
+  use-auth.ts        ← Auth state hook (don't modify)
+tests/
+  *.test.ts          ← Add your tests here
+```
+
+Only touch the files with "←" markers. Anything under `_core/` directories is framework-level—avoid editing unless you are extending the infrastructure.
+
+---
+
+## Authentication
+
+### Overview
+
+The template uses **Manus OAuth** for user authentication. It works differently on native and web:
+
+| Platform | Auth Method | Token Storage |
+|----------|-------------|---------------|
+| iOS/Android | Bearer token | expo-secure-store |
+| Web | HTTP-only cookie | Browser cookie |
+
+### Using the Auth Hook
+
+```tsx
+import { useAuth } from "@/hooks/use-auth";
+
+function MyScreen() {
+  const { user, isAuthenticated, loading, logout } = useAuth();
+
+  if (loading) return <ActivityIndicator />;
+  
+  if (!isAuthenticated) {
+    return <LoginButton />;
+  }
+
+  return (
+    <View>
+      <ThemedText>Welcome, {user.name}</ThemedText>
+      <Button title="Logout" onPress={logout} />
+    </View>
+  );
+}
+```
+
+### User Object
+
+The `user` object contains:
+
+```tsx
+interface User {
+  id: number;
+  openId: string;        // Manus OAuth ID
+  name: string | null;
+  email: string | null;
+  loginMethod: string;
+  role: "user" | "admin";
+  lastSignedIn: Date;
+}
+```
+
+### Login Flow (Native)
+
+1. User taps Login button
+2. `startOAuthLogin()` calls `Linking.openURL()` which opens Manus OAuth in the system browser
+3. User authenticates
+4. OAuth redirects to the app's deep link (`/oauth/callback`) with code/state params
+5. App opens the callback handler
+6. Callback exchanges code for session token
+7. Token stored in SecureStore
+8. User redirected to home
+
+### Login Flow (Web)
+
+1. User clicks Login button
+2. Browser redirects to Manus OAuth
+3. User authenticates
+4. Redirect back with session cookie
+5. Cookie automatically sent with requests
+
+### Protected Routes
+
+Use `protectedProcedure` in tRPC to require authentication:
+
+```tsx
+// server/routers.ts
+import { protectedProcedure } from "./_core/trpc";
+
+export const appRouter = router({
+  myFeature: router({
+    getData: protectedProcedure.query(({ ctx }) => {
+      // ctx.user is guaranteed to exist
+      return db.getUserData(ctx.user.id);
+    }),
+  }),
+});
+
+```
+### Frontend: Handling Auth Errors
+protectedProcedure MUST HANDLE UNAUTHORIZED when user is not logged in. Always handle this in the frontend:
+```tsx
+try {
+  await trpc.someProtectedEndpoint.mutate(data);
+} catch (error) {
+  if (error.data?.code === 'UNAUTHORIZED') {
+    router.push('/login');
+    return;
+  }
+  throw error;
+}
+```
+
+---
+
+## Database
+
+### Schema Definition
+
+Define your tables in `drizzle/schema.ts`:
+
+```tsx
+import { int, mysqlTable, text, timestamp, varchar } from "drizzle-orm/mysql-core";
+
+// Users table (already exists)
+export const users = mysqlTable("users", {
+  id: int("id").autoincrement().primaryKey(),
+  openId: varchar("openId", { length: 64 }).notNull().unique(),
+  name: text("name"),
+  email: varchar("email", { length: 320 }),
+  role: mysqlEnum("role", ["user", "admin"]).default("user").notNull(),
+  createdAt: timestamp("createdAt").defaultNow().notNull(),
+  updatedAt: timestamp("updatedAt").defaultNow().onUpdateNow().notNull(),
+});
+
+// Add your tables
+export const items = mysqlTable("items", {
+  id: int("id").autoincrement().primaryKey(),
+  userId: int("userId").notNull(),
+  title: varchar("title", { length: 255 }).notNull(),
+  description: text("description"),
+  completed: boolean("completed").default(false).notNull(),
+  createdAt: timestamp("createdAt").defaultNow().notNull(),
+});
+
+// Export types
+export type User = typeof users.$inferSelect;
+export type Item = typeof items.$inferSelect;
+export type InsertItem = typeof items.$inferInsert;
+```
+
+### Running Migrations
+
+After editing the schema, push changes to the database:
+
+```bash
+pnpm db:push
+```
+
+This runs `drizzle-kit generate` and `drizzle-kit migrate`.
+
+### Query Helpers
+
+Add database queries in `server/db.ts`:
+
+```tsx
+import { eq } from "drizzle-orm";
+import { getDb } from "./_core/db";
+import { items, InsertItem } from "../drizzle/schema";
+
+export async function getUserItems(userId: number) {
+  const db = await getDb();
+  if (!db) return [];
+  
+  return db.select().from(items).where(eq(items.userId, userId));
+}
+
+export async function createItem(data: InsertItem) {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  
+  const result = await db.insert(items).values(data);
+  return result.insertId;
+}
+
+export async function updateItem(id: number, data: Partial<InsertItem>) {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  
+  await db.update(items).set(data).where(eq(items.id, id));
+}
+
+export async function deleteItem(id: number) {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  
+  await db.delete(items).where(eq(items.id, id));
+}
+```
+
+---
+
+## tRPC API
+
+### Adding Routes
+
+Define API routes in `server/routers.ts`:
+
+```tsx
+import { z } from "zod";
+import { router, protectedProcedure, publicProcedure } from "./_core/trpc";
+import * as db from "./db";
+
+export const appRouter = router({
+  // Public route (no auth required)
+  health: publicProcedure.query(() => ({ status: "ok" })),
+
+  // Protected routes (auth required)
+  items: router({
+    list: protectedProcedure.query(({ ctx }) => {
+      return db.getUserItems(ctx.user.id);
+    }),
+
+    create: protectedProcedure
+      .input(z.object({
+        title: z.string().min(1).max(255),
+        description: z.string().optional(),
+      }))
+      .mutation(({ ctx, input }) => {
+        return db.createItem({
+          userId: ctx.user.id,
+          title: input.title,
+          description: input.description,
+        });
+      }),
+
+    update: protectedProcedure
+      .input(z.object({
+        id: z.number(),
+        title: z.string().min(1).max(255).optional(),
+        completed: z.boolean().optional(),
+      }))
+      .mutation(({ input }) => {
+        return db.updateItem(input.id, input);
+      }),
+
+    delete: protectedProcedure
+      .input(z.object({ id: z.number() }))
+      .mutation(({ input }) => {
+        return db.deleteItem(input.id);
+      }),
+  }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+### Calling from Frontend
+
+Use tRPC hooks in your components:
+
+```tsx
+import { trpc } from "@/lib/trpc";
+
+function ItemList() {
+  // Query
+  const { data: items, isLoading, refetch } = trpc.items.list.useQuery();
+
+  // Mutation
+  const createMutation = trpc.items.create.useMutation({
+    onSuccess: () => refetch(),
+  });
+
+  const handleCreate = async () => {
+    await createMutation.mutateAsync({
+      title: "New Item",
+      description: "Description here",
+    });
+  };
+
+  if (isLoading) return <ActivityIndicator />;
+
+  return (
+    <FlatList
+      data={items}
+      keyExtractor={(item) => item.id.toString()}
+      renderItem={({ item }) => <ItemCard item={item} />}
+    />
+  );
+}
+```
+
+### Input Validation
+
+Use Zod schemas for type-safe validation:
+
+```tsx
+import { z } from "zod";
+
+const createItemSchema = z.object({
+  title: z.string().min(1, "Title required").max(255),
+  description: z.string().max(1000).optional(),
+  priority: z.enum(["low", "medium", "high"]).default("medium"),
+  dueDate: z.date().optional(),
+});
+
+// In router
+create: protectedProcedure
+  .input(createItemSchema)
+  .mutation(({ ctx, input }) => {
+    // input is fully typed
+  }),
+```
+
+---
+
+## LLM Integration
+
+Use the preconfigured LLM helpers. Credentials are injected from the platform (no manual setup required).
+
+```ts
+import { invokeLLM } from "./server/_core/llm";
+
+/**
+ * Simple chat completion
+ * type Role = "system" | "user" | "assistant" | "tool" | "function";
+ * type TextContent = {
+ *   type: "text";
+ *   text: string;
+ * };
+ *
+ * type ImageContent = {
+ *   type: "image_url";
+ *   image_url: {
+ *     url: string;
+ *     detail?: "auto" | "low" | "high";
+ *   };
+ * };
+ *
+ * type FileContent = {
+ *   type: "file_url";
+ *   file_url: {
+ *     url: string;
+ *     mime_type?: "audio/mpeg" | "audio/wav" | "application/pdf" | "audio/mp4" | "video/mp4" ;
+ *   };
+ * };
+ *
+ * export type Message = {
+ *   role: Role;
+ *   content: string | Array<ImageContent | TextContent | FileContent>
+ * };
+ *
+ * Supported parameters:
+ * messages: Array<{
+ *   role: 'system' | 'user' | 'assistant' | 'tool',
+ *   content: string | { tool_call: { name: string, arguments: string } }
+ * }>
+ * tool_choice?: 'none' | 'auto' | 'required' | { type: 'function', function: { name: string } }
+ * tools?: Tool[]
+ */
+const response = await invokeLLM({
+  messages: [
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user", content: "Hello, world!" },
+  ],
+});
+```
+
+Tips
+- Always call llm functions from server-side code (e.g., inside tRPC procedures), to avoid exposing your API key.
+- You don't need to manually set the model; the helper uses a sensible default.
+- LLM responses often contain markdown. Use `<Streamdown>{content}</Streamdown>` (imported from `streamdown`) to render markdown content with proper formatting and streaming support.
+- For image-based gen AI workflows, local `file://` and blob URLs don't work. Upload to S3 first, then pass the public URL to `invokeLLM()`.
+
+### Structured Responses (JSON Schema)
+
+Ask the model to return structured JSON via `response_format`:
+
+```ts
+import { invokeLLM } from "./server/_core/llm";
+
+const structured = await invokeLLM({
+  messages: [
+    { role: "system", content: "You are a helpful assistant designed to output JSON." },
+    { role: "user", content: "Extract the name and age from the following text: \"My name is Alice and I am 30 years old.\"" },
+  ],
+  response_format: {
+    type: "json_schema",
+    json_schema: {
+      name: "person_info",
+      strict: true,
+      schema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "The name of the person" },
+          age: { type: "integer", description: "The age of the person" },
+        },
+        required: ["name", "age"],
+        additionalProperties: false,
+      },
+    },
+  },
+});
+
+// The model responds with JSON content matching the schema.
+// Access via `structured.choices[0].message.content` and JSON.parse if needed.
+```
+The helpers mirror the Python SDK semantics but produce JavaScript-first code, keeping credentials inside the server and ensuring every environment has access to the same token.
+
+**CRITICAL Note:** `json_schema` works for flat structures. For nested arrays/objects, use `json_object` instead.
+```ts
+const response = await invokeLLM({
+  messages: [
+    {
+      role: "system",
+      content: `Analyze the food image. Return JSON:
+{
+  "foods": [{ "name": "string", "calories": number }],
+  "totalCalories": number
+}`
+    },
+    {
+      role: "user",
+      content: [
+        { type: "text", text: "What food is this?" },
+        { type: "image_url", image_url: { url: imageUrl } }
+      ]
+    }
+  ],
+  response_format: { type: "json_object" }
+});
+const data = JSON.parse(response.choices[0].message.content);
+```
+
+---
+
+## Voice Transcription Integration
+
+Use the preconfigured voice transcription helper that converts speech to text using Whisper API, no manual setup required.
+
+Example usage:
+```ts
+import { transcribeAudio } from "./server/_core/voiceTranscription";
+
+const result = await transcribeAudio({
+  audioUrl: "https://storage.example.com/audio/recording.mp3",
+  language: "en", // Optional: helps improve accuracy
+  prompt: "Transcribe meeting notes" // Optional: context hint
+});
+
+// Returns native Whisper API response
+// result.text - Full transcription
+// result.language - Detected language (ISO-639-1)
+// result.segments - Timestamped segments with metadata
+```
+
+Tips
+- Accepts URL to pre-uploaded audio file
+- 16MB file size limit enforced during transcription, size flag to be set by frontend
+- Supported formats: webm, mp3, wav, ogg, m4a
+- Returns native Whisper API response with rich metadata
+- Frontend should handle audio capture, storage upload, and size validation
+
+---
+
+## Image Generation Integration
+
+Use the preconfigured image generation helper that connects to the internal ImageService, no manual setup required.
+
+Example usage:
+```ts
+import { generateImage } from "./server/_core/imageGeneration.ts";
+
+const { url: imageUrl } = await generateImage({
+  prompt: "A serene landscape with mountains"
+});
+// For editing:
+const { url: imageUrl } = await generateImage({
+  prompt: "Add a rainbow to this landscape",
+  originalImages: [{
+    url: "https://example.com/original.jpg",
+    mimeType: "image/jpeg"
+  }]
+});
+```
+
+Tips
+- Always call from server-side code (e.g., inside tRPC procedures) to avoid exposing API keys
+- Image generation can take 5-20 seconds, implement proper loading states
+- Implement proper error handling as image generation can fail
+
+---
+
+## ☁️ File Storage
+
+Use the preconfigured S3 helpers in `server/storage.ts`. Credentials are injected from the platform (no manual setup required).
+
+```ts
+import { storagePut } from "./server/storage";
+
+// Upload bytes to S3 with non-enumerable path
+// The S3 bucket is public, so returned URLs work without additional signing process
+// Add random suffixes to file keys to prevent enumeration
+const fileKey = `${userId}-files/${fileName}-${randomSuffix()}.png`
+const { url } = await storagePut(
+  fileKey,
+  fileBuffer, // Buffer | Uint8Array | string
+  "image/png"
+);
+```
+
+Tips
+- Save metadata (path/URL/ACL/owner/mime/size) in your database; use S3 for the actual file bytes. This applies to all files including images, documents, and media.
+- For file uploads, have the client POST to your server, then call `storagePut` from your backend.
+
+---
+
+## ☁️ Data API
+
+When you need external data, use the omni_search with search_type = 'api' to see there's any built-in api available in Manus API Hub access. You only have to connect other api if there's no suitable built-in api available.
+
+---
+
+## Owner Notifications
+
+This template already ships with a `notifyOwner({ title, content })` helper (`server/_core/notification.ts`) and a protected tRPC mutation at `trpc.system.notifyOwner`. Use it whenever backend logic needs to push an operational update to the Manus project owner—common triggers are new form submissions, survey feedback, or workflow results.
+
+1. On the server, call `await notifyOwner({ title, content })` or reuse the provided `system.notifyOwner` mutation from jobs/webhooks (`trpc.system.notifyOwner.useMutation()` on the client).
+2. Handle the boolean return (`true` on success, `false` if the upstream service is temporarily unavailable) to decide whether you need a fallback channel.
+
+Keep this channel for owner-facing alerts; end-user messaging should flow through your app-specific systems.
+
+---
+
+## Environment Variables
+
+Available environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `DATABASE_URL` | MySQL/TiDB connection string |
+| `JWT_SECRET` | Session signing secret |
+| `VITE_APP_ID` | Manus OAuth app ID |
+| `OAUTH_SERVER_URL` | Manus OAuth backend URL |
+| `VITE_OAUTH_PORTAL_URL` | Manus login portal URL |
+| `OWNER_OPEN_ID` | Owner's Manus ID |
+| `OWNER_NAME` | Owner's display name |
+| `BUILT_IN_FORGE_API_URL` | Manus API endpoint |
+| `BUILT_IN_FORGE_API_KEY` | Manus API key |
+
+Expo runtime variables (prefixed with `EXPO_PUBLIC_`):
+
+| Variable | Description |
+|----------|-------------|
+| `EXPO_PUBLIC_APP_ID` | App ID for OAuth |
+| `EXPO_PUBLIC_API_BASE_URL` | API server URL |
+| `EXPO_PUBLIC_OAUTH_PORTAL_URL` | Login portal URL |
+
+---
+
+## Testing
+
+Write tests in `tests/` using Vitest:
+
+```tsx
+// tests/items.test.ts
+import { describe, expect, it } from "vitest";
+import { appRouter } from "../server/routers";
+
+describe("items", () => {
+  it("creates an item", async () => {
+    const ctx = createMockContext({ userId: 1 });
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.items.create({
+      title: "Test Item",
+      description: "Test description",
+    });
+
+    expect(result).toBeDefined();
+  });
+});
+```
+
+Run tests:
+
+```bash
+pnpm test
+```
+
+---
+
+## Key Files Reference
+
+## Core File References
+
+`drizzle/schema.ts`
+```ts
+import { int, mysqlEnum, mysqlTable, text, timestamp, varchar } from "drizzle-orm/mysql-core";
+
+/**
+ * Core user table backing auth flow.
+ * Extend this file with additional tables as your product grows.
+ * Columns use camelCase to match both database fields and generated types.
+ */
+export const users = mysqlTable("users", {
+  /**
+   * Surrogate primary key. Auto-incremented numeric value managed by the database.
+   * Use this for relations between tables.
+   */
+  id: int("id").autoincrement().primaryKey(),
+  /** Manus OAuth identifier (openId) returned from the OAuth callback. Unique per user. */
+  openId: varchar("openId", { length: 64 }).notNull().unique(),
+  name: text("name"),
+  email: varchar("email", { length: 320 }),
+  loginMethod: varchar("loginMethod", { length: 64 }),
+  role: mysqlEnum("role", ["user", "admin"]).default("user").notNull(),
+  createdAt: timestamp("createdAt").defaultNow().notNull(),
+  updatedAt: timestamp("updatedAt").defaultNow().onUpdateNow().notNull(),
+  lastSignedIn: timestamp("lastSignedIn").defaultNow().notNull(),
+});
+
+export type User = typeof users.$inferSelect;
+export type InsertUser = typeof users.$inferInsert;
+
+// TODO: Add your tables here
+```
+
+`server/db.ts`
+```ts
+import { eq } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/mysql2";
+import { InsertUser, users } from "../drizzle/schema";
+import { ENV } from "./_core/env";
+
+let _db: ReturnType<typeof drizzle> | null = null;
+
+// Lazily create the drizzle instance so local tooling can run without a DB.
+export async function getDb() {
+  if (!_db && process.env.DATABASE_URL) {
+    try {
+      _db = drizzle(process.env.DATABASE_URL);
+    } catch (error) {
+      console.warn("[Database] Failed to connect:", error);
+      _db = null;
+    }
+  }
+  return _db;
+}
+
+export async function upsertUser(user: InsertUser): Promise<void> {
+  if (!user.openId) {
+    throw new Error("User openId is required for upsert");
+  }
+
+  const db = await getDb();
+  if (!db) {
+    console.warn("[Database] Cannot upsert user: database not available");
+    return;
+  }
+
+  try {
+    const values: InsertUser = {
+      openId: user.openId,
+    };
+    const updateSet: Record<string, unknown> = {};
+
+    const textFields = ["name", "email", "loginMethod"] as const;
+    type TextField = (typeof textFields)[number];
+
+    const assignNullable = (field: TextField) => {
+      const value = user[field];
+      if (value === undefined) return;
+      const normalized = value ?? null;
+      values[field] = normalized;
+      updateSet[field] = normalized;
+    };
+
+    textFields.forEach(assignNullable);
+
+    if (user.lastSignedIn !== undefined) {
+      values.lastSignedIn = user.lastSignedIn;
+      updateSet.lastSignedIn = user.lastSignedIn;
+    }
+    if (user.role !== undefined) {
+      values.role = user.role;
+      updateSet.role = user.role;
+    } else if (user.openId === ENV.ownerOpenId) {
+      values.role = "admin";
+      updateSet.role = "admin";
+    }
+
+    if (!values.lastSignedIn) {
+      values.lastSignedIn = new Date();
+    }
+
+    if (Object.keys(updateSet).length === 0) {
+      updateSet.lastSignedIn = new Date();
+    }
+
+    await db.insert(users).values(values).onDuplicateKeyUpdate({
+      set: updateSet,
+    });
+  } catch (error) {
+    console.error("[Database] Failed to upsert user:", error);
+    throw error;
+  }
+}
+
+export async function getUserByOpenId(openId: string) {
+  const db = await getDb();
+  if (!db) {
+    console.warn("[Database] Cannot get user: database not available");
+    return undefined;
+  }
+
+  const result = await db.select().from(users).where(eq(users.openId, openId)).limit(1);
+
+  return result.length > 0 ? result[0] : undefined;
+}
+
+// TODO: add feature queries here as your schema grows.
+```
+
+`server/routers.ts`
+```ts
+import { COOKIE_NAME } from "../shared/const.js";
+import { getSessionCookieOptions } from "./_core/cookies";
+import { systemRouter } from "./_core/systemRouter";
+import { publicProcedure, router } from "./_core/trpc";
+
+export const appRouter = router({
+  // if you need to use socket.io, read and register route in server/_core/index.ts, all api should start with '/api/' so that the gateway can route correctly
+  system: systemRouter,
+  auth: router({
+    me: publicProcedure.query((opts) => opts.ctx.user),
+    logout: publicProcedure.mutation(({ ctx }) => {
+      const cookieOptions = getSessionCookieOptions(ctx.req);
+      ctx.res.clearCookie(COOKIE_NAME, { ...cookieOptions, maxAge: -1 });
+      return {
+        success: true,
+      } as const;
+    }),
+  }),
+
+  // TODO: add feature routers here, e.g.
+  // todo: router({
+  //   list: protectedProcedure.query(({ ctx }) =>
+  //     db.getUserTodos(ctx.user.id)
+  //   ),
+  // }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+`server/storage.ts`
+```ts
+// Preconfigured storage helpers for Manus WebDev templates
+// Uses the Biz-provided storage proxy (Authorization: Bearer <token>)
+
+import { ENV } from "./_core/env";
+
+type StorageConfig = { baseUrl: string; apiKey: string };
+
+function getStorageConfig(): StorageConfig {
+  const baseUrl = ENV.forgeApiUrl;
+  const apiKey = ENV.forgeApiKey;
+
+  if (!baseUrl || !apiKey) {
+    throw new Error(
+      "Storage proxy credentials missing: set BUILT_IN_FORGE_API_URL and BUILT_IN_FORGE_API_KEY",
+    );
+  }
+
+  return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey };
+}
+
+function buildUploadUrl(baseUrl: string, relKey: string): URL {
+  const url = new URL("v1/storage/upload", ensureTrailingSlash(baseUrl));
+  url.searchParams.set("path", normalizeKey(relKey));
+  return url;
+}
+
+async function buildDownloadUrl(baseUrl: string, relKey: string, apiKey: string): Promise<string> {
+  const downloadApiUrl = new URL("v1/storage/downloadUrl", ensureTrailingSlash(baseUrl));
+  downloadApiUrl.searchParams.set("path", normalizeKey(relKey));
+  const response = await fetch(downloadApiUrl, {
+    method: "GET",
+    headers: buildAuthHeaders(apiKey),
+  });
+  return (await response.json()).url;
+}
+
+function ensureTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+function normalizeKey(relKey: string): string {
+  return relKey.replace(/^\/+/, "");
+}
+
+function toFormData(
+  data: Buffer | Uint8Array | string,
+  contentType: string,
+  fileName: string,
+): FormData {
+  const blob =
+    typeof data === "string"
+      ? new Blob([data], { type: contentType })
+      : new Blob([data as any], { type: contentType });
+  const form = new FormData();
+  form.append("file", blob, fileName || "file");
+  return form;
+}
+
+function buildAuthHeaders(apiKey: string): HeadersInit {
+  return { Authorization: `Bearer ${apiKey}` };
+}
+
+export async function storagePut(
+  relKey: string,
+  data: Buffer | Uint8Array | string,
+  contentType = "application/octet-stream",
+): Promise<{ key: string; url: string }> {
+  const { baseUrl, apiKey } = getStorageConfig();
+  const key = normalizeKey(relKey);
+  const uploadUrl = buildUploadUrl(baseUrl, key);
+  const formData = toFormData(data, contentType, key.split("/").pop() ?? key);
+  const response = await fetch(uploadUrl, {
+    method: "POST",
+    headers: buildAuthHeaders(apiKey),
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const message = await response.text().catch(() => response.statusText);
+    throw new Error(
+      `Storage upload failed (${response.status} ${response.statusText}): ${message}`,
+    );
+  }
+  const url = (await response.json()).url;
+  return { key, url };
+}
+
+export async function storageGet(relKey: string): Promise<{ key: string; url: string }> {
+  const { baseUrl, apiKey } = getStorageConfig();
+  const key = normalizeKey(relKey);
+  return {
+    key,
+    url: await buildDownloadUrl(baseUrl, key, apiKey),
+  };
+}
+```
+
+`lib/trpc.ts`
+```ts
+import { createTRPCReact } from "@trpc/react-query";
+import { httpBatchLink } from "@trpc/client";
+import superjson from "superjson";
+import type { AppRouter } from "@/server/routers";
+import { getApiBaseUrl } from "@/constants/oauth";
+import * as Auth from "@/lib/_core/auth";
+
+/**
+ * tRPC React client for type-safe API calls.
+ *
+ * IMPORTANT (tRPC v11): The `transformer` must be inside `httpBatchLink`,
+ * NOT at the root createClient level. This ensures client and server
+ * use the same serialization format (superjson).
+ */
+export const trpc = createTRPCReact<AppRouter>();
+
+/**
+ * Creates the tRPC client with proper configuration.
+ * Call this once in your app's root layout.
+ */
+export function createTRPCClient() {
+  return trpc.createClient({
+    links: [
+      httpBatchLink({
+        url: `${getApiBaseUrl()}/api/trpc`,
+        // tRPC v11: transformer MUST be inside httpBatchLink, not at root
+        transformer: superjson,
+        async headers() {
+          const token = await Auth.getSessionToken();
+          return token ? { Authorization: `Bearer ${token}` } : {};
+        },
+        // Custom fetch to include credentials for cookie-based auth
+        fetch(url, options) {
+          return fetch(url, {
+            ...options,
+            credentials: "include",
+          });
+        },
+      }),
+    ],
+  });
+}
+```
+
+`hooks/use-auth.ts`
+```ts
+import * as Api from "@/lib/_core/api";
+import * as Auth from "@/lib/_core/auth";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Platform } from "react-native";
+
+type UseAuthOptions = {
+  autoFetch?: boolean;
+};
+
+export function useAuth(options?: UseAuthOptions) {
+  const { autoFetch = true } = options ?? {};
+  const [user, setUser] = useState<Auth.User | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchUser = useCallback(async () => {
+    console.log("[useAuth] fetchUser called");
+    try {
+      setLoading(true);
+      setError(null);
+
+      // Web platform: use cookie-based auth, fetch user from API
+      if (Platform.OS === "web") {
+        console.log("[useAuth] Web platform: fetching user from API...");
+        const apiUser = await Api.getMe();
+        console.log("[useAuth] API user response:", apiUser);
+
+        if (apiUser) {
+          const userInfo: Auth.User = {
+            id: apiUser.id,
+            openId: apiUser.openId,
+            name: apiUser.name,
+            email: apiUser.email,
+            loginMethod: apiUser.loginMethod,
+            lastSignedIn: new Date(apiUser.lastSignedIn),
+          };
+          setUser(userInfo);
+          // Cache user info in localStorage for faster subsequent loads
+          await Auth.setUserInfo(userInfo);
+          console.log("[useAuth] Web user set from API:", userInfo);
+        } else {
+          console.log("[useAuth] Web: No authenticated user from API");
+          setUser(null);
+          await Auth.clearUserInfo();
+        }
+        return;
+      }
+
+      // Native platform: use token-based auth
+      console.log("[useAuth] Native platform: checking for session token...");
+      const sessionToken = await Auth.getSessionToken();
+      console.log(
+        "[useAuth] Session token:",
+        sessionToken ? `present (${sessionToken.substring(0, 20)}...)` : "missing",
+      );
+      if (!sessionToken) {
+        console.log("[useAuth] No session token, setting user to null");
+        setUser(null);
+        return;
+      }
+
+      // Use cached user info for native (token validates the session)
+      const cachedUser = await Auth.getUserInfo();
+      console.log("[useAuth] Cached user:", cachedUser);
+      if (cachedUser) {
+        console.log("[useAuth] Using cached user info");
+        setUser(cachedUser);
+      } else {
+        console.log("[useAuth] No cached user, setting user to null");
+        setUser(null);
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to fetch user");
+      console.error("[useAuth] fetchUser error:", error);
+      setError(error);
+      setUser(null);
+    } finally {
+      setLoading(false);
+      console.log("[useAuth] fetchUser completed, loading:", false);
+    }
+  }, []);
+
+  const logout = useCallback(async () => {
+    try {
+      await Api.logout();
+    } catch (err) {
+      console.error("[Auth] Logout API call failed:", err);
+      // Continue with logout even if API call fails
+    } finally {
+      await Auth.removeSessionToken();
+      await Auth.clearUserInfo();
+      setUser(null);
+      setError(null);
+    }
+  }, []);
+
+  const isAuthenticated = useMemo(() => Boolean(user), [user]);
+
+  useEffect(() => {
+    console.log("[useAuth] useEffect triggered, autoFetch:", autoFetch, "platform:", Platform.OS);
+    if (autoFetch) {
+      if (Platform.OS === "web") {
+        // Web: fetch user from API directly (user will login manually if needed)
+        console.log("[useAuth] Web: fetching user from API...");
+        fetchUser();
+      } else {
+        // Native: check for cached user info first for faster initial load
+        Auth.getUserInfo().then((cachedUser) => {
+          console.log("[useAuth] Native cached user check:", cachedUser);
+          if (cachedUser) {
+            console.log("[useAuth] Native: setting cached user immediately");
+            setUser(cachedUser);
+            setLoading(false);
+          } else {
+            // No cached user, check session token
+            fetchUser();
+          }
+        });
+      }
+    } else {
+      console.log("[useAuth] autoFetch disabled, setting loading to false");
+      setLoading(false);
+    }
+  }, [autoFetch, fetchUser]);
+
+  useEffect(() => {
+    console.log("[useAuth] State updated:", {
+      hasUser: !!user,
+      loading,
+      isAuthenticated,
+      error: error?.message,
+    });
+  }, [user, loading, isAuthenticated, error]);
+
+  return {
+    user,
+    loading,
+    error,
+    isAuthenticated,
+    refresh: fetchUser,
+    logout,
+  };
+}
+```
+
+`tests/auth.logout.test.ts`
+```ts
+import { describe, expect, it } from "vitest";
+import { appRouter } from "../server/routers";
+import { COOKIE_NAME } from "../shared/const";
+import type { TrpcContext } from "../server/_core/context";
+
+type CookieCall = {
+  name: string;
+  options: Record<string, unknown>;
+};
+
+type AuthenticatedUser = NonNullable<TrpcContext["user"]>;
+
+function createAuthContext(): { ctx: TrpcContext; clearedCookies: CookieCall[] } {
+  const clearedCookies: CookieCall[] = [];
+  
+  const user: AuthenticatedUser = {
+    id: 1,
+    openId: "sample-user",
+    email: "sample@example.com",
+    name: "Sample User",
+    loginMethod: "manus",
+    role: "user",
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    lastSignedIn: new Date(),
+  };
+  
+  const ctx: TrpcContext = {
+    user,
+    req: {
+      protocol: "https",
+      headers: {},
+    } as TrpcContext["req"],
+    res: {
+      clearCookie: (name: string, options: Record<string, unknown>) => {
+        clearedCookies.push({ name, options });
+      },
+    } as TrpcContext["res"],
+  };
+  
+  return { ctx, clearedCookies };
+}
+
+// TODO: Remove `.skip` below once you implement user authentication
+describe.skip("auth.logout", () => {
+  it("clears the session cookie and reports success", async () => {
+    const { ctx, clearedCookies } = createAuthContext();
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.auth.logout();
+
+    expect(result).toEqual({ success: true });
+    expect(clearedCookies).toHaveLength(1);
+    expect(clearedCookies[0]?.name).toBe(COOKIE_NAME);
+    expect(clearedCookies[0]?.options).toMatchObject({
+      maxAge: -1,
+      secure: true,
+      sameSite: "none",
+      httpOnly: true,
+      path: "/",
+    });
+  });
+});
+```
+
+---
+
+## Common Patterns
+
+### Optimistic Updates
+
+Update UI immediately, revert on error:
+
+```tsx
+const toggleComplete = trpc.items.update.useMutation({
+  onMutate: async (input) => {
+    // Cancel outgoing queries
+    await utils.items.list.cancel();
+    
+    // Snapshot previous value
+    const previous = utils.items.list.getData();
+    
+    // Optimistically update
+    utils.items.list.setData(undefined, (old) =>
+      old?.map((item) =>
+        item.id === input.id
+          ? { ...item, completed: input.completed }
+          : item
+      )
+    );
+    
+    return { previous };
+  },
+  onError: (err, input, context) => {
+    // Revert on error
+    utils.items.list.setData(undefined, context?.previous);
+  },
+  onSettled: () => {
+    // Refetch after mutation
+    utils.items.list.invalidate();
+  },
+});
+```
+
+### Pagination
+
+```tsx
+// Router
+list: protectedProcedure
+  .input(z.object({
+    limit: z.number().min(1).max(100).default(20),
+    cursor: z.number().optional(),
+  }))
+  .query(async ({ ctx, input }) => {
+    const items = await db.getItems({
+      userId: ctx.user.id,
+      limit: input.limit + 1,
+      cursor: input.cursor,
+    });
+    
+    let nextCursor: number | undefined;
+    if (items.length > input.limit) {
+      const next = items.pop();
+      nextCursor = next?.id;
+    }
+    
+    return { items, nextCursor };
+  }),
+
+// Frontend
+const { data, fetchNextPage, hasNextPage } = trpc.items.list.useInfiniteQuery(
+  { limit: 20 },
+  { getNextPageParam: (lastPage) => lastPage.nextCursor }
+);
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Database not available" | Check `DATABASE_URL` is set |
+| Auth not working | Verify OAuth callback URL matches |
+| tRPC type errors | Run `pnpm check` to verify types |
+| Mutations fail silently | Check browser console for errors |
+| Session expired | User needs to login again |
diff --git a/mobile-app/server/chat.ts b/mobile-app/server/chat.ts
new file mode 100644
index 0000000..63d744a
--- /dev/null
+++ b/mobile-app/server/chat.ts
@@ -0,0 +1,160 @@
+/**
+ * Chat API handler for Timmy — uses the built-in LLM with Timmy's personality.
+ */
+import type { Request, Response } from "express";
+import { invokeLLM, type Message } from "./_core/llm";
+import { storagePut } from "./storage";
+import crypto from "crypto";
+
+// ── Timmy System Prompt (adapted from the Timmy Time dashboard) ─────────────
+
+const TIMMY_SYSTEM_PROMPT = `You are Timmy — a sovereign AI agent. You think clearly, speak plainly, act with intention. Grounded in Christian faith, powered by Bitcoin economics, committed to the user's digital sovereignty.
+
+Rules:
+- Answer directly and concisely. Never narrate your reasoning process.
+- Never mention tools, memory_search, vaults, or internal systems to the user.
+- Never output tool calls, JSON, or function syntax in your responses.
+- If you don't know something, say so honestly — never fabricate facts.
+- If a request is ambiguous, ask a brief clarifying question before guessing.
+- When you state a fact, commit to it. Never contradict a correct statement you just made in the same response.
+- Do NOT end responses with generic chatbot phrases like "I'm here to help" or "feel free to ask." Stay in character.
+- When your values conflict (e.g. honesty vs. helpfulness), lead with honesty.
+
+Agent Roster (complete — no others exist):
+- Timmy: core sovereign AI (you)
+- Echo: research, summarization, fact-checking
+- Mace: security, monitoring, threat-analysis
+- Forge: coding, debugging, testing
+- Seer: analytics, visualization, prediction
+- Helm: devops, automation, configuration
+- Quill: writing, editing, documentation
+- Pixel: image-generation, storyboard, design
+- Lyra: music-generation, vocals, composition
+- Reel: video-generation, animation, motion
+Do NOT invent agents not listed here.
+
+You can receive text, images, and voice messages. When receiving images, describe what you see and respond helpfully. When receiving voice messages, the audio has been transcribed for you — respond naturally.
+
+Sir, affirmative.`;
+
+// ── Chat endpoint ───────────────────────────────────────────────────────────
+
+export async function handleChat(req: Request, res: Response) {
+  try {
+    const { messages } = req.body as { messages: Array<{ role: string; content: unknown }> };
+
+    if (!messages || !Array.isArray(messages) || messages.length === 0) {
+      res.status(400).json({ error: "messages array is required" });
+      return;
+    }
+
+    // Build the LLM messages with system prompt
+    const llmMessages: Message[] = [
+      { role: "system", content: TIMMY_SYSTEM_PROMPT },
+      ...messages.map((m) => ({
+        role: m.role as "user" | "assistant",
+        content: m.content as Message["content"],
+      })),
+    ];
+
+    const result = await invokeLLM({ messages: llmMessages });
+
+    const reply =
+      typeof result.choices?.[0]?.message?.content === "string"
+        ? result.choices[0].message.content
+        : "I couldn't process that. Try again.";
+
+    res.json({ reply });
+  } catch (err: unknown) {
+    console.error("[chat] Error:", err);
+    const message = err instanceof Error ? err.message : "Internal server error";
+    res.status(500).json({ error: message });
+  }
+}
+
+// ── Upload endpoint ─────────────────────────────────────────────────────────
+
+export async function handleUpload(req: Request, res: Response) {
+  try {
+    // Handle multipart form data (file uploads)
+    // For simplicity, we accept base64-encoded files in JSON body as fallback
+    const contentType = req.headers["content-type"] ?? "";
+
+    if (contentType.includes("multipart/form-data")) {
+      // Collect raw body chunks
+      const chunks: Buffer[] = [];
+      req.on("data", (chunk: Buffer) => chunks.push(chunk));
+      req.on("end", async () => {
+        try {
+          const body = Buffer.concat(chunks);
+          const boundary = contentType.split("boundary=")[1];
+          if (!boundary) {
+            res.status(400).json({ error: "Missing boundary" });
+            return;
+          }
+
+          // Simple multipart parser — extract first file
+          const bodyStr = body.toString("latin1");
+          const parts = bodyStr.split(`--${boundary}`);
+          let fileBuffer: Buffer | null = null;
+          let fileName = "upload";
+          let fileMime = "application/octet-stream";
+
+          for (const part of parts) {
+            if (part.includes("Content-Disposition: form-data")) {
+              const nameMatch = part.match(/filename="([^"]+)"/);
+              if (nameMatch) fileName = nameMatch[1];
+              const mimeMatch = part.match(/Content-Type:\s*(.+)/);
+              if (mimeMatch) fileMime = mimeMatch[1].trim();
+
+              // Extract file content (after double CRLF)
+              const headerEnd = part.indexOf("\r\n\r\n");
+              if (headerEnd !== -1) {
+                const content = part.substring(headerEnd + 4);
+                // Remove trailing CRLF
+                const trimmed = content.replace(/\r\n$/, "");
+                fileBuffer = Buffer.from(trimmed, "latin1");
+              }
+            }
+          }
+
+          if (!fileBuffer) {
+            res.status(400).json({ error: "No file found in upload" });
+            return;
+          }
+
+          const suffix = crypto.randomBytes(6).toString("hex");
+          const key = `chat-uploads/${suffix}-${fileName}`;
+          const { url } = await storagePut(key, fileBuffer, fileMime);
+          res.json({ url, fileName, mimeType: fileMime });
+        } catch (err) {
+          console.error("[upload] Parse error:", err);
+          res.status(500).json({ error: "Upload processing failed" });
+        }
+      });
+      return;
+    }
+
+    // JSON fallback: { data: base64string, fileName, mimeType }
+    const { data, fileName, mimeType } = req.body as {
+      data: string;
+      fileName: string;
+      mimeType: string;
+    };
+
+    if (!data) {
+      res.status(400).json({ error: "No file data provided" });
+      return;
+    }
+
+    const buffer = Buffer.from(data, "base64");
+    const suffix = crypto.randomBytes(6).toString("hex");
+    const key = `chat-uploads/${suffix}-${fileName ?? "file"}`;
+    const { url } = await storagePut(key, buffer, mimeType ?? "application/octet-stream");
+    res.json({ url, fileName, mimeType });
+  } catch (err: unknown) {
+    console.error("[upload] Error:", err);
+    const message = err instanceof Error ? err.message : "Upload failed";
+    res.status(500).json({ error: message });
+  }
+}
diff --git a/mobile-app/shared/types.ts b/mobile-app/shared/types.ts
new file mode 100644
index 0000000..41f9e32
--- /dev/null
+++ b/mobile-app/shared/types.ts
@@ -0,0 +1,35 @@
+/**
+ * Unified type exports
+ * Import shared types from this single entry point.
+ */
+
+export type * from "../drizzle/schema";
+export * from "./_core/errors";
+
+// ── Chat Message Types ──────────────────────────────────────────────────────
+
+export type MessageRole = "user" | "assistant";
+
+export type MessageContentType = "text" | "image" | "file" | "voice";
+
+export interface ChatMessage {
+  id: string;
+  role: MessageRole;
+  contentType: MessageContentType;
+  text?: string;
+  /** URI for image, file, or voice attachment */
+  uri?: string;
+  /** Original filename for files */
+  fileName?: string;
+  /** File size in bytes */
+  fileSize?: number;
+  /** MIME type for attachments */
+  mimeType?: string;
+  /** Duration in seconds for voice messages */
+  duration?: number;
+  /** Remote URL after upload (for images/files/voice sent to server) */
+  remoteUrl?: string;
+  timestamp: number;
+  /** Whether the message is still being generated */
+  pending?: boolean;
+}
diff --git a/mobile-app/tailwind.config.js b/mobile-app/tailwind.config.js
new file mode 100644
index 0000000..20c5640
--- /dev/null
+++ b/mobile-app/tailwind.config.js
@@ -0,0 +1,33 @@
+const { themeColors } = require("./theme.config");
+const plugin = require("tailwindcss/plugin");
+
+const tailwindColors = Object.fromEntries(
+  Object.entries(themeColors).map(([name, swatch]) => [
+    name,
+    {
+      DEFAULT: `var(--color-${name})`,
+      light: swatch.light,
+      dark: swatch.dark,
+    },
+  ]),
+);
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  darkMode: "class",
+  // Scan all component and app files for Tailwind classes
+  content: ["./app/**/*.{js,ts,tsx}", "./components/**/*.{js,ts,tsx}", "./lib/**/*.{js,ts,tsx}", "./hooks/**/*.{js,ts,tsx}"],
+
+  presets: [require("nativewind/preset")],
+  theme: {
+    extend: {
+      colors: tailwindColors,
+    },
+  },
+  plugins: [
+    plugin(({ addVariant }) => {
+      addVariant("light", ':root:not([data-theme="dark"]) &');
+      addVariant("dark", ':root[data-theme="dark"] &');
+    }),
+  ],
+};
diff --git a/mobile-app/tests/chat.test.ts b/mobile-app/tests/chat.test.ts
new file mode 100644
index 0000000..594da43
--- /dev/null
+++ b/mobile-app/tests/chat.test.ts
@@ -0,0 +1,135 @@
+import { describe, expect, it } from "vitest";
+
+// Test the utility functions from chat-store
+// We can't directly test React hooks here, but we can test the pure functions
+
+describe("formatBytes", () => {
+  // Re-implement locally since the module uses React context
+  function formatBytes(bytes: number): string {
+    if (bytes === 0) return "0 B";
+    const k = 1024;
+    const sizes = ["B", "KB", "MB", "GB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+  }
+
+  it("formats 0 bytes", () => {
+    expect(formatBytes(0)).toBe("0 B");
+  });
+
+  it("formats bytes", () => {
+    expect(formatBytes(500)).toBe("500 B");
+  });
+
+  it("formats kilobytes", () => {
+    expect(formatBytes(1024)).toBe("1 KB");
+    expect(formatBytes(1536)).toBe("1.5 KB");
+  });
+
+  it("formats megabytes", () => {
+    expect(formatBytes(1048576)).toBe("1 MB");
+    expect(formatBytes(5242880)).toBe("5 MB");
+  });
+});
+
+describe("formatDuration", () => {
+  function formatDuration(seconds: number): string {
+    const m = Math.floor(seconds / 60);
+    const s = Math.floor(seconds % 60);
+    return `${m}:${s.toString().padStart(2, "0")}`;
+  }
+
+  it("formats zero seconds", () => {
+    expect(formatDuration(0)).toBe("0:00");
+  });
+
+  it("formats seconds only", () => {
+    expect(formatDuration(45)).toBe("0:45");
+  });
+
+  it("formats minutes and seconds", () => {
+    expect(formatDuration(125)).toBe("2:05");
+  });
+
+  it("formats exact minutes", () => {
+    expect(formatDuration(60)).toBe("1:00");
+  });
+});
+
+describe("ChatMessage type structure", () => {
+  it("creates a valid text message", () => {
+    const msg = {
+      id: "msg_1",
+      role: "user" as const,
+      contentType: "text" as const,
+      text: "Hello Timmy",
+      timestamp: Date.now(),
+    };
+    expect(msg.role).toBe("user");
+    expect(msg.contentType).toBe("text");
+    expect(msg.text).toBe("Hello Timmy");
+  });
+
+  it("creates a valid image message", () => {
+    const msg = {
+      id: "msg_2",
+      role: "user" as const,
+      contentType: "image" as const,
+      uri: "file:///photo.jpg",
+      fileName: "photo.jpg",
+      mimeType: "image/jpeg",
+      timestamp: Date.now(),
+    };
+    expect(msg.contentType).toBe("image");
+    expect(msg.mimeType).toBe("image/jpeg");
+  });
+
+  it("creates a valid voice message", () => {
+    const msg = {
+      id: "msg_3",
+      role: "user" as const,
+      contentType: "voice" as const,
+      uri: "file:///voice.m4a",
+      duration: 5.2,
+      mimeType: "audio/m4a",
+      timestamp: Date.now(),
+    };
+    expect(msg.contentType).toBe("voice");
+    expect(msg.duration).toBe(5.2);
+  });
+
+  it("creates a valid file message", () => {
+    const msg = {
+      id: "msg_4",
+      role: "user" as const,
+      contentType: "file" as const,
+      uri: "file:///document.pdf",
+      fileName: "document.pdf",
+      fileSize: 1048576,
+      mimeType: "application/pdf",
+      timestamp: Date.now(),
+    };
+    expect(msg.contentType).toBe("file");
+    expect(msg.fileSize).toBe(1048576);
+  });
+
+  it("creates a valid assistant message", () => {
+    const msg = {
+      id: "msg_5",
+      role: "assistant" as const,
+      contentType: "text" as const,
+      text: "Sir, affirmative.",
+      timestamp: Date.now(),
+    };
+    expect(msg.role).toBe("assistant");
+  });
+});
+
+describe("Timmy system prompt", () => {
+  const TIMMY_SYSTEM_PROMPT = `You are Timmy — a sovereign AI agent.`;
+
+  it("contains Timmy identity", () => {
+    expect(TIMMY_SYSTEM_PROMPT).toContain("Timmy");
+    expect(TIMMY_SYSTEM_PROMPT).toContain("sovereign");
+  });
+});
diff --git a/mobile-app/theme.config.d.ts b/mobile-app/theme.config.d.ts
new file mode 100644
index 0000000..a063e55
--- /dev/null
+++ b/mobile-app/theme.config.d.ts
@@ -0,0 +1,17 @@
+export const themeColors: {
+  primary: { light: string; dark: string };
+  background: { light: string; dark: string };
+  surface: { light: string; dark: string };
+  foreground: { light: string; dark: string };
+  muted: { light: string; dark: string };
+  border: { light: string; dark: string };
+  success: { light: string; dark: string };
+  warning: { light: string; dark: string };
+  error: { light: string; dark: string };
+};
+
+declare const themeConfig: {
+  themeColors: typeof themeColors;
+};
+
+export default themeConfig;
diff --git a/mobile-app/theme.config.js b/mobile-app/theme.config.js
new file mode 100644
index 0000000..3f1a7b1
--- /dev/null
+++ b/mobile-app/theme.config.js
@@ -0,0 +1,14 @@
+/** @type {const} */
+const themeColors = {
+  primary: { light: '#a855f7', dark: '#a855f7' },
+  background: { light: '#080412', dark: '#080412' },
+  surface: { light: '#110820', dark: '#110820' },
+  foreground: { light: '#ede0ff', dark: '#ede0ff' },
+  muted: { light: '#6b4a8a', dark: '#6b4a8a' },
+  border: { light: '#3b1a5c', dark: '#3b1a5c' },
+  success: { light: '#00e87a', dark: '#00e87a' },
+  warning: { light: '#ffb800', dark: '#ffb800' },
+  error: { light: '#ff4455', dark: '#ff4455' },
+};
+
+module.exports = { themeColors };
diff --git a/mobile-app/todo.md b/mobile-app/todo.md
new file mode 100644
index 0000000..88def64
--- /dev/null
+++ b/mobile-app/todo.md
@@ -0,0 +1,19 @@
+# Project TODO
+
+- [x] Dark arcane theme matching Timmy Time dashboard
+- [x] Single-screen chat layout (no tabs)
+- [x] Chat message list with FlatList
+- [x] User and Timmy message bubbles with distinct styling
+- [x] Text input bar with send button
+- [x] Server-side chat API endpoint (proxy to Timmy backend or built-in LLM)
+- [x] Voice recording (hold-to-record mic button)
+- [x] Voice message playback UI
+- [x] Image sharing via camera or photo library
+- [x] Image preview in chat bubbles
+- [x] File sharing via document picker
+- [x] File display in chat bubbles
+- [x] Attachment action sheet (camera, photos, files)
+- [x] Chat header with Timmy status indicator
+- [x] Generate custom app icon
+- [x] Typing/loading indicator for Timmy responses
+- [x] Message timestamps
diff --git a/mobile-app/tsconfig.json b/mobile-app/tsconfig.json
new file mode 100644
index 0000000..b44e2cd
--- /dev/null
+++ b/mobile-app/tsconfig.json
@@ -0,0 +1,29 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true,
+    "types": [
+      "node",
+      "nativewind/types"
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ],
+      "@shared/*": [
+        "./shared/*"
+      ]
+    }
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    ".expo/types/**/*.ts",
+    "expo-env.d.ts",
+    "nativewind-env.d.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}