elsabro 2.3.0 → 3.8.0

package/references/mobile-companion.md

@@ -0,0 +1,3236 @@
+# ELSABRO Mobile Companion v3.7
+
+## Technical Reference Documentation
+
+> React Native + Expo SDK 52+ mobile application for ELSABRO AI orchestration system
+
+---
+
+## Table of Contents
+
+1. [Mobile App Architecture](#1-mobileapparchitecture)
+2. [Session Sync](#2-sessionsync)
+3. [Push Notification Manager](#3-pushnotificationmanager)
+4. [Voice Input Handler](#4-voiceinputhandler)
+5. [Offline Mode](#5-offlinemode)
+6. [Biometric Auth](#6-biometricauth)
+7. [Widget Support](#7-widget-support)
+8. [Commands Reference](#8-commands)
+
+---
+
+## Architecture Overview
+
+```
++------------------------------------------------------------------+
+|                    ELSABRO Mobile Companion                       |
++------------------------------------------------------------------+
+|                                                                   |
+|  +---------------------+    +---------------------+               |
+|  |   Presentation      |    |    Navigation       |               |
+|  |   Layer             |    |    (expo-router)    |               |
+|  +----------+----------+    +----------+----------+               |
+|             |                          |                          |
+|  +----------v--------------------------v----------+               |
+|  |              State Management (Zustand)        |               |
+|  |  +------------+  +------------+  +----------+  |               |
+|  |  | SessionStore|  | AuthStore |  | UIStore  |  |               |
+|  |  +------------+  +------------+  +----------+  |               |
+|  +------------------------+-----------------------+               |
+|                           |                                       |
+|  +------------------------v-----------------------+               |
+|  |           Data Layer (React Query)             |               |
+|  |  +----------+  +-------------+  +-----------+  |               |
+|  |  | Queries  |  | Mutations   |  | Cache     |  |               |
+|  |  +----------+  +-------------+  +-----------+  |               |
+|  +------------------------+-----------------------+               |
+|                           |                                       |
+|  +------------------------v-----------------------+               |
+|  |              Native Modules                    |               |
+|  |  +-------+ +--------+ +------+ +------------+  |               |
+|  |  |Biometric| |Voice  | |Push | |Widgets     |  |               |
+|  |  +-------+ +--------+ +------+ +------------+  |               |
+|  +------------------------------------------------+               |
+|                           |                                       |
+|  +------------------------v-----------------------+               |
+|  |         Network Layer (WebSocket + REST)       |               |
+|  +------------------------------------------------+               |
+|                           |                                       |
++---------------------------v---------------------------------------+
+                            |
+              +-------------v--------------+
+              |   ELSABRO Backend API      |
+              |   (WebSocket + REST)       |
+              +----------------------------+
+```
+
+---
+
+## 1. MobileAppArchitecture
+
+### Project Structure (Expo SDK 52+)
+
+```
+elsabro-mobile/
++-- app/                          # expo-router pages
+|   +-- (tabs)/                   # Tab navigation group
+|   |   +-- index.tsx             # Dashboard
+|   |   +-- sessions.tsx          # Active sessions
+|   |   +-- agents.tsx            # Agent management
+|   |   +-- settings.tsx          # App settings
+|   |   +-- _layout.tsx           # Tab layout
+|   +-- session/
+|   |   +-- [id].tsx              # Session detail
+|   +-- auth/
+|   |   +-- login.tsx             # Login screen
+|   |   +-- biometric.tsx         # Biometric setup
+|   +-- _layout.tsx               # Root layout
+|   +-- +not-found.tsx            # 404 handler
++-- src/
+|   +-- components/               # Reusable components
+|   |   +-- ui/                   # Base UI components
+|   |   +-- sessions/             # Session-specific
+|   |   +-- agents/               # Agent-specific
+|   +-- stores/                   # Zustand stores
+|   |   +-- sessionStore.ts
+|   |   +-- authStore.ts
+|   |   +-- notificationStore.ts
+|   |   +-- offlineStore.ts
+|   +-- hooks/                    # Custom hooks
+|   |   +-- useSession.ts
+|   |   +-- useWebSocket.ts
+|   |   +-- useVoice.ts
+|   |   +-- useBiometric.ts
+|   +-- services/                 # API services
+|   |   +-- api.ts
+|   |   +-- websocket.ts
+|   |   +-- notifications.ts
+|   +-- types/                    # TypeScript types
+|   +-- utils/                    # Utilities
+|   +-- constants/                # App constants
++-- assets/                       # Static assets
++-- widgets/                      # Native widgets
+|   +-- ios/                      # iOS WidgetKit
+|   +-- android/                  # Android widgets
++-- app.json                      # Expo config
++-- eas.json                      # EAS Build config
++-- tsconfig.json
++-- package.json
+```
+
+### Core Dependencies
+
+```json
+{
+  "dependencies": {
+    "expo": "~52.0.0",
+    "expo-router": "~4.0.0",
+    "expo-notifications": "~0.29.0",
+    "expo-local-authentication": "~15.0.0",
+    "expo-secure-store": "~14.0.0",
+    "expo-speech": "~13.0.0",
+    "expo-haptics": "~14.0.0",
+    "@react-native-voice/voice": "^3.3.0",
+    "@tanstack/react-query": "^5.60.0",
+    "zustand": "^5.0.0",
+    "react-native-reanimated": "~3.16.0",
+    "react-native-gesture-handler": "~2.20.0"
+  }
+}
+```
+
+### Root Layout Configuration
+
+```typescript
+// app/_layout.tsx
+import { Stack } from 'expo-router';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { useEffect } from 'react';
+import { useAuthStore } from '@/stores/authStore';
+import { useNotificationStore } from '@/stores/notificationStore';
+import { WebSocketProvider } from '@/providers/WebSocketProvider';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5, // 5 minutes
+      gcTime: 1000 * 60 * 30,   // 30 minutes
+      retry: 3,
+      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
+    },
+  },
+});
+
+export default function RootLayout() {
+  const { initialize: initAuth } = useAuthStore();
+  const { registerForPushNotifications } = useNotificationStore();
+
+  useEffect(() => {
+    initAuth();
+    registerForPushNotifications();
+  }, []);
+
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <QueryClientProvider client={queryClient}>
+        <WebSocketProvider>
+          <Stack
+            screenOptions={{
+              headerShown: false,
+              animation: 'slide_from_right',
+            }}
+          >
+            <Stack.Screen name="(tabs)" />
+            <Stack.Screen
+              name="session/[id]"
+              options={{ presentation: 'modal' }}
+            />
+            <Stack.Screen
+              name="auth/login"
+              options={{ presentation: 'fullScreenModal' }}
+            />
+          </Stack>
+        </WebSocketProvider>
+      </QueryClientProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+### Zustand Store Pattern
+
+```typescript
+// src/stores/sessionStore.ts
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { immer } from 'zustand/middleware/immer';
+
+interface Session {
+  id: string;
+  name: string;
+  status: 'active' | 'paused' | 'completed' | 'error';
+  agents: string[];
+  currentTask: string | null;
+  progress: number;
+  startedAt: string;
+  lastActivity: string;
+}
+
+interface SessionState {
+  sessions: Record<string, Session>;
+  activeSessionId: string | null;
+  isConnected: boolean;
+  lastSyncTimestamp: number;
+}
+
+interface SessionActions {
+  setActiveSession: (id: string | null) => void;
+  updateSession: (id: string, updates: Partial<Session>) => void;
+  addSession: (session: Session) => void;
+  removeSession: (id: string) => void;
+  syncSessions: (sessions: Session[]) => void;
+  setConnected: (connected: boolean) => void;
+}
+
+export const useSessionStore = create<SessionState & SessionActions>()(
+  persist(
+    immer((set, get) => ({
+      // State
+      sessions: {},
+      activeSessionId: null,
+      isConnected: false,
+      lastSyncTimestamp: 0,
+
+      // Actions
+      setActiveSession: (id) =>
+        set((state) => {
+          state.activeSessionId = id;
+        }),
+
+      updateSession: (id, updates) =>
+        set((state) => {
+          if (state.sessions[id]) {
+            Object.assign(state.sessions[id], updates);
+            state.sessions[id].lastActivity = new Date().toISOString();
+          }
+        }),
+
+      addSession: (session) =>
+        set((state) => {
+          state.sessions[session.id] = session;
+        }),
+
+      removeSession: (id) =>
+        set((state) => {
+          delete state.sessions[id];
+          if (state.activeSessionId === id) {
+            state.activeSessionId = null;
+          }
+        }),
+
+      syncSessions: (sessions) =>
+        set((state) => {
+          sessions.forEach((session) => {
+            state.sessions[session.id] = session;
+          });
+          state.lastSyncTimestamp = Date.now();
+        }),
+
+      setConnected: (connected) =>
+        set((state) => {
+          state.isConnected = connected;
+        }),
+    })),
+    {
+      name: 'elsabro-sessions',
+      storage: createJSONStorage(() => AsyncStorage),
+      partialize: (state) => ({
+        sessions: state.sessions,
+        activeSessionId: state.activeSessionId,
+        lastSyncTimestamp: state.lastSyncTimestamp,
+      }),
+    }
+  )
+);
+```
+
+### React Query API Layer
+
+```typescript
+// src/services/api.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { useAuthStore } from '@/stores/authStore';
+
+const API_BASE_URL = process.env.EXPO_PUBLIC_API_URL || 'https://api.elsabro.io';
+
+interface ApiOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+async function apiRequest<T>(endpoint: string, options: ApiOptions = {}): Promise<T> {
+  const token = useAuthStore.getState().accessToken;
+
+  const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+    method: options.method || 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': token ? `Bearer ${token}` : '',
+      'X-Client-Version': '3.7.0',
+      'X-Platform': Platform.OS,
+      ...options.headers,
+    },
+    body: options.body ? JSON.stringify(options.body) : undefined,
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}));
+    throw new ApiError(response.status, error.message || 'Request failed');
+  }
+
+  return response.json();
+}
+
+// Query Keys Factory
+export const queryKeys = {
+  sessions: {
+    all: ['sessions'] as const,
+    list: (filters?: SessionFilters) => [...queryKeys.sessions.all, 'list', filters] as const,
+    detail: (id: string) => [...queryKeys.sessions.all, 'detail', id] as const,
+    logs: (id: string) => [...queryKeys.sessions.all, 'logs', id] as const,
+  },
+  agents: {
+    all: ['agents'] as const,
+    available: () => [...queryKeys.agents.all, 'available'] as const,
+    detail: (id: string) => [...queryKeys.agents.all, 'detail', id] as const,
+  },
+  user: {
+    profile: ['user', 'profile'] as const,
+    preferences: ['user', 'preferences'] as const,
+  },
+};
+
+// Sessions Hooks
+export function useSessions(filters?: SessionFilters) {
+  return useQuery({
+    queryKey: queryKeys.sessions.list(filters),
+    queryFn: () => apiRequest<Session[]>('/sessions', {
+      method: 'GET',
+    }),
+    staleTime: 1000 * 30, // 30 seconds for active data
+  });
+}
+
+export function useSession(id: string) {
+  return useQuery({
+    queryKey: queryKeys.sessions.detail(id),
+    queryFn: () => apiRequest<SessionDetail>(`/sessions/${id}`),
+    enabled: !!id,
+    refetchInterval: 5000, // Poll every 5 seconds for active session
+  });
+}
+
+export function useSessionLogs(id: string, options?: { enabled?: boolean }) {
+  return useQuery({
+    queryKey: queryKeys.sessions.logs(id),
+    queryFn: () => apiRequest<SessionLog[]>(`/sessions/${id}/logs`),
+    enabled: options?.enabled ?? !!id,
+    refetchInterval: 2000,
+  });
+}
+
+// Mutations
+export function useCreateSession() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: CreateSessionRequest) =>
+      apiRequest<Session>('/sessions', {
+        method: 'POST',
+        body: data,
+      }),
+    onSuccess: (newSession) => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.sessions.all });
+      queryClient.setQueryData(
+        queryKeys.sessions.detail(newSession.id),
+        newSession
+      );
+    },
+  });
+}
+
+export function usePauseSession() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (id: string) =>
+      apiRequest<Session>(`/sessions/${id}/pause`, { method: 'POST' }),
+    onMutate: async (id) => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.sessions.detail(id) });
+      const previous = queryClient.getQueryData(queryKeys.sessions.detail(id));
+
+      queryClient.setQueryData(queryKeys.sessions.detail(id), (old: Session) => ({
+        ...old,
+        status: 'paused',
+      }));
+
+      return { previous };
+    },
+    onError: (err, id, context) => {
+      if (context?.previous) {
+        queryClient.setQueryData(queryKeys.sessions.detail(id), context.previous);
+      }
+    },
+    onSettled: (_, __, id) => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.sessions.detail(id) });
+    },
+  });
+}
+
+export function useSendCommand() {
+  return useMutation({
+    mutationFn: ({ sessionId, command }: { sessionId: string; command: string }) =>
+      apiRequest<CommandResponse>(`/sessions/${sessionId}/command`, {
+        method: 'POST',
+        body: { command },
+      }),
+  });
+}
+```
+
+---
+
+## 2. SessionSync
+
+### WebSocket Real-Time Synchronization
+
+```
++-------------------+          +-------------------+
+|   Mobile Client   |          |   ELSABRO Server  |
++-------------------+          +-------------------+
+         |                              |
+         |  1. WS Connect + Auth Token  |
+         |----------------------------->|
+         |                              |
+         |  2. Connection Confirmed     |
+         |<-----------------------------|
+         |                              |
+         |  3. Subscribe to Session     |
+         |----------------------------->|
+         |                              |
+         |  4. Initial State Snapshot   |
+         |<-----------------------------|
+         |                              |
+         |  5. Real-time Updates        |
+         |<-----------------------------|
+         |<-----------------------------|
+         |                              |
+         |  6. Client Action            |
+         |----------------------------->|
+         |                              |
+         |  7. Action Confirmed         |
+         |<-----------------------------|
+         |                              |
+```
+
+### WebSocket Service Implementation
+
+```typescript
+// src/services/websocket.ts
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { AppState, AppStateStatus } from 'react-native';
+import { useAuthStore } from '@/stores/authStore';
+import { useSessionStore } from '@/stores/sessionStore';
+import { useOfflineStore } from '@/stores/offlineStore';
+
+const WS_URL = process.env.EXPO_PUBLIC_WS_URL || 'wss://ws.elsabro.io';
+
+interface WebSocketMessage {
+  type: string;
+  payload: unknown;
+  timestamp: number;
+  messageId: string;
+}
+
+interface SessionUpdate {
+  sessionId: string;
+  type: 'status' | 'progress' | 'log' | 'agent' | 'task' | 'error';
+  data: unknown;
+  version: number;
+}
+
+type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
+
+class ElsabroWebSocket {
+  private ws: WebSocket | null = null;
+  private reconnectAttempts = 0;
+  private maxReconnectAttempts = 10;
+  private reconnectDelay = 1000;
+  private heartbeatInterval: NodeJS.Timeout | null = null;
+  private messageQueue: WebSocketMessage[] = [];
+  private subscriptions = new Set<string>();
+  private stateVersions = new Map<string, number>();
+
+  private listeners = {
+    onConnect: new Set<() => void>(),
+    onDisconnect: new Set<(reason: string) => void>(),
+    onMessage: new Set<(message: WebSocketMessage) => void>(),
+    onError: new Set<(error: Error) => void>(),
+    onStateChange: new Set<(state: ConnectionState) => void>(),
+  };
+
+  private connectionState: ConnectionState = 'disconnected';
+
+  connect(token: string): void {
+    if (this.ws?.readyState === WebSocket.OPEN) return;
+
+    this.setConnectionState('connecting');
+
+    this.ws = new WebSocket(`${WS_URL}?token=${token}`);
+
+    this.ws.onopen = () => {
+      console.log('[WS] Connected');
+      this.setConnectionState('connected');
+      this.reconnectAttempts = 0;
+      this.startHeartbeat();
+      this.flushMessageQueue();
+      this.resubscribeAll();
+      this.listeners.onConnect.forEach(cb => cb());
+    };
+
+    this.ws.onmessage = (event) => {
+      try {
+        const message: WebSocketMessage = JSON.parse(event.data);
+        this.handleMessage(message);
+      } catch (error) {
+        console.error('[WS] Parse error:', error);
+      }
+    };
+
+    this.ws.onclose = (event) => {
+      console.log('[WS] Disconnected:', event.code, event.reason);
+      this.setConnectionState('disconnected');
+      this.stopHeartbeat();
+      this.listeners.onDisconnect.forEach(cb => cb(event.reason));
+      this.attemptReconnect(token);
+    };
+
+    this.ws.onerror = (error) => {
+      console.error('[WS] Error:', error);
+      this.listeners.onError.forEach(cb => cb(new Error('WebSocket error')));
+    };
+  }
+
+  private handleMessage(message: WebSocketMessage): void {
+    switch (message.type) {
+      case 'session:update':
+        this.handleSessionUpdate(message.payload as SessionUpdate);
+        break;
+      case 'session:sync':
+        this.handleFullSync(message.payload);
+        break;
+      case 'pong':
+        // Heartbeat response
+        break;
+      case 'error':
+        console.error('[WS] Server error:', message.payload);
+        break;
+      default:
+        this.listeners.onMessage.forEach(cb => cb(message));
+    }
+  }
+
+  private handleSessionUpdate(update: SessionUpdate): void {
+    const currentVersion = this.stateVersions.get(update.sessionId) || 0;
+
+    // Conflict detection - request full sync if version mismatch
+    if (update.version > currentVersion + 1) {
+      console.log('[WS] Version gap detected, requesting full sync');
+      this.requestFullSync(update.sessionId);
+      return;
+    }
+
+    if (update.version <= currentVersion) {
+      console.log('[WS] Stale update ignored');
+      return;
+    }
+
+    this.stateVersions.set(update.sessionId, update.version);
+
+    const sessionStore = useSessionStore.getState();
+
+    switch (update.type) {
+      case 'status':
+        sessionStore.updateSession(update.sessionId, {
+          status: update.data as Session['status']
+        });
+        break;
+      case 'progress':
+        sessionStore.updateSession(update.sessionId, {
+          progress: update.data as number
+        });
+        break;
+      case 'task':
+        sessionStore.updateSession(update.sessionId, {
+          currentTask: update.data as string
+        });
+        break;
+      case 'error':
+        sessionStore.updateSession(update.sessionId, {
+          status: 'error',
+          error: update.data as string,
+        });
+        break;
+    }
+  }
+
+  private handleFullSync(payload: unknown): void {
+    const { sessions, versions } = payload as {
+      sessions: Session[];
+      versions: Record<string, number>;
+    };
+
+    useSessionStore.getState().syncSessions(sessions);
+
+    Object.entries(versions).forEach(([id, version]) => {
+      this.stateVersions.set(id, version);
+    });
+  }
+
+  private requestFullSync(sessionId: string): void {
+    this.send({
+      type: 'session:sync:request',
+      payload: { sessionId },
+      timestamp: Date.now(),
+      messageId: crypto.randomUUID(),
+    });
+  }
+
+  subscribe(sessionId: string): void {
+    this.subscriptions.add(sessionId);
+
+    if (this.isConnected()) {
+      this.send({
+        type: 'session:subscribe',
+        payload: { sessionId },
+        timestamp: Date.now(),
+        messageId: crypto.randomUUID(),
+      });
+    }
+  }
+
+  unsubscribe(sessionId: string): void {
+    this.subscriptions.delete(sessionId);
+    this.stateVersions.delete(sessionId);
+
+    if (this.isConnected()) {
+      this.send({
+        type: 'session:unsubscribe',
+        payload: { sessionId },
+        timestamp: Date.now(),
+        messageId: crypto.randomUUID(),
+      });
+    }
+  }
+
+  private resubscribeAll(): void {
+    this.subscriptions.forEach(sessionId => {
+      this.send({
+        type: 'session:subscribe',
+        payload: { sessionId },
+        timestamp: Date.now(),
+        messageId: crypto.randomUUID(),
+      });
+    });
+  }
+
+  send(message: WebSocketMessage): void {
+    if (this.isConnected()) {
+      this.ws!.send(JSON.stringify(message));
+    } else {
+      // Queue for later
+      this.messageQueue.push(message);
+      useOfflineStore.getState().addPendingAction({
+        id: message.messageId,
+        type: 'websocket',
+        data: message,
+        createdAt: Date.now(),
+      });
+    }
+  }
+
+  private flushMessageQueue(): void {
+    while (this.messageQueue.length > 0) {
+      const message = this.messageQueue.shift()!;
+      this.ws!.send(JSON.stringify(message));
+    }
+  }
+
+  private startHeartbeat(): void {
+    this.heartbeatInterval = setInterval(() => {
+      if (this.isConnected()) {
+        this.send({
+          type: 'ping',
+          payload: null,
+          timestamp: Date.now(),
+          messageId: crypto.randomUUID(),
+        });
+      }
+    }, 30000);
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+  }
+
+  private attemptReconnect(token: string): void {
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+      console.log('[WS] Max reconnect attempts reached');
+      return;
+    }
+
+    this.setConnectionState('reconnecting');
+    this.reconnectAttempts++;
+
+    const delay = Math.min(
+      this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1),
+      30000
+    ) + Math.random() * 1000; // Jitter
+
+    setTimeout(() => {
+      console.log(`[WS] Reconnect attempt ${this.reconnectAttempts}`);
+      this.connect(token);
+    }, delay);
+  }
+
+  private setConnectionState(state: ConnectionState): void {
+    this.connectionState = state;
+    this.listeners.onStateChange.forEach(cb => cb(state));
+    useSessionStore.getState().setConnected(state === 'connected');
+  }
+
+  isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  disconnect(): void {
+    this.stopHeartbeat();
+    this.ws?.close(1000, 'Client disconnect');
+    this.ws = null;
+    this.setConnectionState('disconnected');
+  }
+
+  on<K extends keyof typeof this.listeners>(
+    event: K,
+    callback: Parameters<typeof this.listeners[K]['add']>[0]
+  ): () => void {
+    (this.listeners[event] as Set<unknown>).add(callback);
+    return () => (this.listeners[event] as Set<unknown>).delete(callback);
+  }
+}
+
+export const wsClient = new ElsabroWebSocket();
+
+// React Hook
+export function useWebSocket() {
+  const [connectionState, setConnectionState] = useState<ConnectionState>('disconnected');
+  const { accessToken } = useAuthStore();
+
+  useEffect(() => {
+    if (!accessToken) return;
+
+    wsClient.connect(accessToken);
+
+    const unsubscribe = wsClient.on('onStateChange', setConnectionState);
+
+    // Handle app state changes
+    const handleAppState = (state: AppStateStatus) => {
+      if (state === 'active' && !wsClient.isConnected()) {
+        wsClient.connect(accessToken);
+      }
+    };
+
+    const subscription = AppState.addEventListener('change', handleAppState);
+
+    return () => {
+      unsubscribe();
+      subscription.remove();
+    };
+  }, [accessToken]);
+
+  const subscribe = useCallback((sessionId: string) => {
+    wsClient.subscribe(sessionId);
+    return () => wsClient.unsubscribe(sessionId);
+  }, []);
+
+  return {
+    connectionState,
+    isConnected: connectionState === 'connected',
+    subscribe,
+    send: wsClient.send.bind(wsClient),
+  };
+}
+```
+
+### Deep Linking Configuration
+
+```typescript
+// app.json (excerpt)
+{
+  "expo": {
+    "scheme": "elsabro",
+    "ios": {
+      "bundleIdentifier": "io.elsabro.companion",
+      "associatedDomains": [
+        "applinks:elsabro.io",
+        "applinks:*.elsabro.io"
+      ]
+    },
+    "android": {
+      "package": "io.elsabro.companion",
+      "intentFilters": [
+        {
+          "action": "VIEW",
+          "autoVerify": true,
+          "data": [
+            {
+              "scheme": "https",
+              "host": "elsabro.io",
+              "pathPrefix": "/session"
+            },
+            {
+              "scheme": "elsabro"
+            }
+          ],
+          "category": ["BROWSABLE", "DEFAULT"]
+        }
+      ]
+    }
+  }
+}
+```
+
+```typescript
+// src/hooks/useDeepLink.ts
+import { useEffect } from 'react';
+import { useRouter } from 'expo-router';
+import * as Linking from 'expo-linking';
+import { useAuthStore } from '@/stores/authStore';
+
+export function useDeepLink() {
+  const router = useRouter();
+  const { isAuthenticated } = useAuthStore();
+
+  useEffect(() => {
+    // Handle initial URL
+    Linking.getInitialURL().then(handleUrl);
+
+    // Handle incoming URLs
+    const subscription = Linking.addEventListener('url', ({ url }) => {
+      handleUrl(url);
+    });
+
+    return () => subscription.remove();
+  }, [isAuthenticated]);
+
+  function handleUrl(url: string | null) {
+    if (!url) return;
+
+    const parsed = Linking.parse(url);
+
+    // Route patterns:
+    // elsabro://session/abc123
+    // https://elsabro.io/session/abc123
+    // elsabro://session/abc123/approve?taskId=xyz
+
+    if (parsed.path?.startsWith('session/')) {
+      const sessionId = parsed.path.split('/')[1];
+
+      if (!isAuthenticated) {
+        // Store for after auth
+        useAuthStore.getState().setPendingDeepLink(url);
+        router.push('/auth/login');
+        return;
+      }
+
+      if (parsed.queryParams?.action === 'approve') {
+        router.push({
+          pathname: `/session/${sessionId}`,
+          params: {
+            action: 'approve',
+            taskId: parsed.queryParams.taskId as string,
+          },
+        });
+      } else {
+        router.push(`/session/${sessionId}`);
+      }
+    }
+  }
+
+  return { handleUrl };
+}
+```
+
+### Device Handoff
+
+```typescript
+// src/services/handoff.ts
+import * as Linking from 'expo-linking';
+import { Platform } from 'react-native';
+
+interface HandoffState {
+  sessionId: string;
+  scrollPosition?: number;
+  selectedTab?: string;
+  timestamp: number;
+}
+
+export function generateHandoffUrl(state: HandoffState): string {
+  const params = new URLSearchParams({
+    session: state.sessionId,
+    ...(state.scrollPosition && { scroll: state.scrollPosition.toString() }),
+    ...(state.selectedTab && { tab: state.selectedTab }),
+    ts: state.timestamp.toString(),
+  });
+
+  return `https://elsabro.io/handoff?${params.toString()}`;
+}
+
+export function generateQRHandoff(state: HandoffState): string {
+  // Returns URL that can be encoded as QR code
+  return `elsabro://handoff/${state.sessionId}?` +
+    `data=${encodeURIComponent(JSON.stringify(state))}`;
+}
+
+// iOS Handoff with NSUserActivity (native module required)
+export async function startHandoffActivity(state: HandoffState): Promise<void> {
+  if (Platform.OS !== 'ios') return;
+
+  // Requires native module for NSUserActivity
+  const { HandoffModule } = require('@/native/HandoffModule');
+
+  await HandoffModule.startActivity({
+    activityType: 'io.elsabro.session.view',
+    title: `ELSABRO Session`,
+    userInfo: state,
+    webpageURL: generateHandoffUrl(state),
+  });
+}
+```
+
+---
+
+## 3. PushNotificationManager
+
+### Notification Flow Architecture
+
+```
++------------------+     +------------------+     +------------------+
+|  ELSABRO Server  |---->|   FCM / APNS     |---->|   Mobile App     |
++------------------+     +------------------+     +------------------+
+        |                        |                        |
+        | 1. Event trigger       | 2. Push delivery       | 3. Handle
+        |    (task complete,     |    (data + display)    |    notification
+        |     build failed,      |                        |
+        |     approval needed)   |                        |
+        +------------------------+------------------------+
+```
+
+### Notification Types
+
+| Type | Priority | Display | Actions |
+|------|----------|---------|---------|
+| `task_completed` | Normal | Alert | View, Archive |
+| `build_failed` | High | Alert + Sound | View Logs, Retry |
+| `approval_needed` | Critical | Alert + Badge | Approve, Reject, Details |
+| `session_update` | Low | Silent | - |
+| `agent_error` | High | Alert | View, Restart Agent |
+| `sync_reminder` | Normal | Alert | Sync Now, Later |
+
+### Notification Service Implementation
+
+```typescript
+// src/services/notifications.ts
+import * as Notifications from 'expo-notifications';
+import * as Device from 'expo-device';
+import { Platform } from 'react-native';
+import Constants from 'expo-constants';
+import { router } from 'expo-router';
+import { useSessionStore } from '@/stores/sessionStore';
+
+// Configure notification handling
+Notifications.setNotificationHandler({
+  handleNotification: async (notification) => {
+    const data = notification.request.content.data;
+
+    // Silent push for background sync
+    if (data.silent) {
+      await handleSilentPush(data);
+      return {
+        shouldShowAlert: false,
+        shouldPlaySound: false,
+        shouldSetBadge: false,
+      };
+    }
+
+    return {
+      shouldShowAlert: true,
+      shouldPlaySound: data.priority === 'high' || data.priority === 'critical',
+      shouldSetBadge: data.type === 'approval_needed',
+    };
+  },
+});
+
+interface NotificationData {
+  type: 'task_completed' | 'build_failed' | 'approval_needed' |
+        'session_update' | 'agent_error' | 'sync_reminder';
+  sessionId: string;
+  taskId?: string;
+  agentId?: string;
+  priority: 'low' | 'normal' | 'high' | 'critical';
+  silent?: boolean;
+  payload?: Record<string, unknown>;
+}
+
+async function handleSilentPush(data: NotificationData): Promise<void> {
+  switch (data.type) {
+    case 'session_update':
+      // Trigger background sync
+      const { syncSessions } = useSessionStore.getState();
+      try {
+        const response = await fetch(`${API_URL}/sessions/sync`, {
+          method: 'POST',
+          headers: getAuthHeaders(),
+        });
+        const sessions = await response.json();
+        syncSessions(sessions);
+      } catch (error) {
+        console.error('Background sync failed:', error);
+      }
+      break;
+  }
+}
+
+export async function registerForPushNotifications(): Promise<string | null> {
+  if (!Device.isDevice) {
+    console.log('Push notifications require a physical device');
+    return null;
+  }
+
+  // Check permissions
+  const { status: existingStatus } = await Notifications.getPermissionsAsync();
+  let finalStatus = existingStatus;
+
+  if (existingStatus !== 'granted') {
+    const { status } = await Notifications.requestPermissionsAsync({
+      ios: {
+        allowAlert: true,
+        allowBadge: true,
+        allowSound: true,
+        allowCriticalAlerts: true, // For approval_needed
+      },
+    });
+    finalStatus = status;
+  }
+
+  if (finalStatus !== 'granted') {
+    console.log('Push notification permission denied');
+    return null;
+  }
+
+  // Get push token
+  const projectId = Constants.expoConfig?.extra?.eas?.projectId;
+
+  const tokenData = await Notifications.getExpoPushTokenAsync({
+    projectId,
+  });
+
+  // Platform-specific setup
+  if (Platform.OS === 'android') {
+    await setupAndroidChannels();
+  }
+
+  // Register token with backend
+  await registerTokenWithBackend(tokenData.data);
+
+  return tokenData.data;
+}
+
+async function setupAndroidChannels(): Promise<void> {
+  // Critical alerts channel
+  await Notifications.setNotificationChannelAsync('critical', {
+    name: 'Critical Alerts',
+    importance: Notifications.AndroidImportance.MAX,
+    vibrationPattern: [0, 250, 250, 250],
+    lightColor: '#FF0000',
+    sound: 'critical.wav',
+    bypassDnd: true,
+  });
+
+  // Build status channel
+  await Notifications.setNotificationChannelAsync('builds', {
+    name: 'Build Status',
+    importance: Notifications.AndroidImportance.HIGH,
+    sound: 'build.wav',
+  });
+
+  // General updates channel
+  await Notifications.setNotificationChannelAsync('updates', {
+    name: 'Session Updates',
+    importance: Notifications.AndroidImportance.DEFAULT,
+  });
+
+  // Silent sync channel
+  await Notifications.setNotificationChannelAsync('sync', {
+    name: 'Background Sync',
+    importance: Notifications.AndroidImportance.MIN,
+    showBadge: false,
+  });
+}
+
+async function registerTokenWithBackend(token: string): Promise<void> {
+  await fetch(`${API_URL}/devices/register`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...getAuthHeaders(),
+    },
+    body: JSON.stringify({
+      token,
+      platform: Platform.OS,
+      deviceId: Device.modelId,
+    }),
+  });
+}
+
+// Notification response handler
+export function setupNotificationListeners(): () => void {
+  // Handle notification when app is foregrounded
+  const foregroundSubscription = Notifications.addNotificationReceivedListener(
+    (notification) => {
+      console.log('Notification received:', notification);
+    }
+  );
+
+  // Handle notification tap
+  const responseSubscription = Notifications.addNotificationResponseReceivedListener(
+    (response) => {
+      const data = response.notification.request.content.data as NotificationData;
+      const actionId = response.actionIdentifier;
+
+      handleNotificationAction(data, actionId);
+    }
+  );
+
+  return () => {
+    foregroundSubscription.remove();
+    responseSubscription.remove();
+  };
+}
+
+function handleNotificationAction(data: NotificationData, actionId: string): void {
+  switch (data.type) {
+    case 'approval_needed':
+      if (actionId === 'approve') {
+        // Quick approve without opening app fully
+        quickApprove(data.sessionId, data.taskId!);
+      } else if (actionId === 'reject') {
+        quickReject(data.sessionId, data.taskId!);
+      } else {
+        router.push({
+          pathname: `/session/${data.sessionId}`,
+          params: { action: 'approve', taskId: data.taskId },
+        });
+      }
+      break;
+
+    case 'build_failed':
+      if (actionId === 'retry') {
+        retryBuild(data.sessionId);
+      } else {
+        router.push({
+          pathname: `/session/${data.sessionId}`,
+          params: { tab: 'logs' },
+        });
+      }
+      break;
+
+    default:
+      router.push(`/session/${data.sessionId}`);
+  }
+}
+
+// Set up notification categories with actions
+export async function setupNotificationCategories(): Promise<void> {
+  await Notifications.setNotificationCategoryAsync('approval', [
+    {
+      identifier: 'approve',
+      buttonTitle: 'Approve',
+      options: {
+        isDestructive: false,
+        isAuthenticationRequired: true,
+      },
+    },
+    {
+      identifier: 'reject',
+      buttonTitle: 'Reject',
+      options: {
+        isDestructive: true,
+        isAuthenticationRequired: true,
+      },
+    },
+    {
+      identifier: 'details',
+      buttonTitle: 'View Details',
+      options: {
+        opensAppToForeground: true,
+      },
+    },
+  ]);
+
+  await Notifications.setNotificationCategoryAsync('build', [
+    {
+      identifier: 'view_logs',
+      buttonTitle: 'View Logs',
+      options: {
+        opensAppToForeground: true,
+      },
+    },
+    {
+      identifier: 'retry',
+      buttonTitle: 'Retry Build',
+      options: {
+        isDestructive: false,
+      },
+    },
+  ]);
+}
+```
+
+### Rich Notification with Image
+
+```typescript
+// Server-side notification payload example
+const richNotification = {
+  to: expoPushToken,
+  title: 'Build Failed',
+  body: 'Project "elsabro-api" build #142 failed at test stage',
+  data: {
+    type: 'build_failed',
+    sessionId: 'sess_abc123',
+    priority: 'high',
+  },
+  categoryId: 'build',
+  // Rich media attachment
+  attachments: [
+    {
+      url: 'https://elsabro.io/builds/142/screenshot.png',
+      identifier: 'build-screenshot',
+    },
+  ],
+  // Android specific
+  channelId: 'builds',
+  // iOS specific
+  sound: 'build_failed.wav',
+  badge: 1,
+};
+```
+
+---
+
+## 4. VoiceInputHandler
+
+### Voice Command Architecture
+
+```
++------------------+     +------------------+     +------------------+
+|   Microphone     |---->|   STT Engine     |---->|  Command Parser  |
+|   Input          |     | (@react-native-  |     |                  |
+|                  |     |  voice/voice)    |     |                  |
++------------------+     +------------------+     +------------------+
+                                                          |
+                                                          v
++------------------+     +------------------+     +------------------+
+|   Haptic         |<----|   TTS Engine     |<----|   Action         |
+|   Feedback       |     |   (expo-speech)  |     |   Executor       |
++------------------+     +------------------+     +------------------+
+```
+
+### Supported Voice Commands
+
+| Command Pattern | Action | Example |
+|-----------------|--------|---------|
+| "Start session [name]" | Create new session | "Start session API refactor" |
+| "Pause session" | Pause active session | "Pause session" |
+| "Resume session" | Resume paused session | "Resume session" |
+| "Status" | Get current status | "Status" |
+| "Approve [task]" | Approve pending task | "Approve deployment" |
+| "Reject [task]" | Reject pending task | "Reject with feedback" |
+| "Show logs" | Display session logs | "Show logs" |
+| "Switch to [session]" | Change active session | "Switch to backend work" |
+| "Stop listening" | Deactivate voice input | "Stop listening" |
+
+### Voice Handler Implementation
+
+```typescript
+// src/hooks/useVoice.ts
+import { useState, useEffect, useCallback, useRef } from 'react';
+import Voice, {
+  SpeechResultsEvent,
+  SpeechErrorEvent,
+  SpeechStartEvent,
+} from '@react-native-voice/voice';
+import * as Speech from 'expo-speech';
+import * as Haptics from 'expo-haptics';
+import { useSessionStore } from '@/stores/sessionStore';
+import { useSendCommand, usePauseSession } from '@/services/api';
+
+interface VoiceState {
+  isListening: boolean;
+  transcript: string;
+  partialTranscript: string;
+  error: string | null;
+  isProcessing: boolean;
+}
+
+interface VoiceCommand {
+  pattern: RegExp;
+  action: (matches: RegExpMatchArray) => Promise<void>;
+  feedback: string;
+}
+
+export function useVoice() {
+  const [state, setState] = useState<VoiceState>({
+    isListening: false,
+    transcript: '',
+    partialTranscript: '',
+    error: null,
+    isProcessing: false,
+  });
+
+  const { activeSessionId, sessions } = useSessionStore();
+  const sendCommand = useSendCommand();
+  const pauseSession = usePauseSession();
+
+  const commandTimeoutRef = useRef<NodeJS.Timeout>();
+
+  // Voice command definitions
+  const commands: VoiceCommand[] = [
+    {
+      pattern: /^(start|create|new) session (.+)$/i,
+      action: async (matches) => {
+        const sessionName = matches[2];
+        await createSession(sessionName);
+      },
+      feedback: 'Creating new session',
+    },
+    {
+      pattern: /^pause( session)?$/i,
+      action: async () => {
+        if (activeSessionId) {
+          await pauseSession.mutateAsync(activeSessionId);
+        }
+      },
+      feedback: 'Pausing session',
+    },
+    {
+      pattern: /^resume( session)?$/i,
+      action: async () => {
+        if (activeSessionId) {
+          await sendCommand.mutateAsync({
+            sessionId: activeSessionId,
+            command: '/elsabro:session resume',
+          });
+        }
+      },
+      feedback: 'Resuming session',
+    },
+    {
+      pattern: /^status$/i,
+      action: async () => {
+        const session = activeSessionId ? sessions[activeSessionId] : null;
+        if (session) {
+          await speak(
+            `Session ${session.name} is ${session.status}. ` +
+            `Progress: ${session.progress}%. ` +
+            `Current task: ${session.currentTask || 'none'}.`
+          );
+        } else {
+          await speak('No active session selected.');
+        }
+      },
+      feedback: '',
+    },
+    {
+      pattern: /^approve( task)?( (.+))?$/i,
+      action: async (matches) => {
+        const taskName = matches[3];
+        if (activeSessionId) {
+          await sendCommand.mutateAsync({
+            sessionId: activeSessionId,
+            command: `/elsabro:approve${taskName ? ` ${taskName}` : ''}`,
+          });
+        }
+      },
+      feedback: 'Approving task',
+    },
+    {
+      pattern: /^reject( task)?( with (.+))?$/i,
+      action: async (matches) => {
+        const reason = matches[3] || 'Rejected via voice';
+        if (activeSessionId) {
+          await sendCommand.mutateAsync({
+            sessionId: activeSessionId,
+            command: `/elsabro:reject --reason "${reason}"`,
+          });
+        }
+      },
+      feedback: 'Rejecting task',
+    },
+    {
+      pattern: /^switch to (.+)$/i,
+      action: async (matches) => {
+        const sessionName = matches[1].toLowerCase();
+        const targetSession = Object.values(sessions).find(
+          s => s.name.toLowerCase().includes(sessionName)
+        );
+        if (targetSession) {
+          useSessionStore.getState().setActiveSession(targetSession.id);
+          await speak(`Switched to session: ${targetSession.name}`);
+        } else {
+          await speak(`Session "${sessionName}" not found.`);
+        }
+      },
+      feedback: '',
+    },
+    {
+      pattern: /^stop listening$/i,
+      action: async () => {
+        await stopListening();
+        await speak('Voice input deactivated.');
+      },
+      feedback: '',
+    },
+  ];
+
+  useEffect(() => {
+    Voice.onSpeechStart = handleSpeechStart;
+    Voice.onSpeechEnd = handleSpeechEnd;
+    Voice.onSpeechResults = handleSpeechResults;
+    Voice.onSpeechPartialResults = handlePartialResults;
+    Voice.onSpeechError = handleSpeechError;
+
+    return () => {
+      Voice.destroy().then(Voice.removeAllListeners);
+    };
+  }, []);
+
+  const handleSpeechStart = (e: SpeechStartEvent) => {
+    setState(prev => ({ ...prev, isListening: true, error: null }));
+    Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
+  };
+
+  const handleSpeechEnd = () => {
+    setState(prev => ({ ...prev, isListening: false }));
+  };
+
+  const handleSpeechResults = async (e: SpeechResultsEvent) => {
+    const transcript = e.value?.[0] || '';
+    setState(prev => ({
+      ...prev,
+      transcript,
+      partialTranscript: '',
+    }));
+
+    if (transcript) {
+      await processCommand(transcript);
+    }
+  };
+
+  const handlePartialResults = (e: SpeechResultsEvent) => {
+    const partial = e.value?.[0] || '';
+    setState(prev => ({ ...prev, partialTranscript: partial }));
+  };
+
+  const handleSpeechError = (e: SpeechErrorEvent) => {
+    setState(prev => ({
+      ...prev,
+      error: e.error?.message || 'Speech recognition error',
+      isListening: false,
+    }));
+    Haptics.notificationAsync(Haptics.NotificationFeedbackType.Error);
+  };
+
+  const processCommand = async (transcript: string) => {
+    setState(prev => ({ ...prev, isProcessing: true }));
+
+    try {
+      for (const command of commands) {
+        const matches = transcript.match(command.pattern);
+        if (matches) {
+          Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium);
+
+          if (command.feedback) {
+            await speak(command.feedback);
+          }
+
+          await command.action(matches);
+
+          Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
+          return;
+        }
+      }
+
+      // No command matched - treat as general input
+      if (activeSessionId) {
+        await sendCommand.mutateAsync({
+          sessionId: activeSessionId,
+          command: transcript,
+        });
+        await speak('Command sent.');
+      } else {
+        await speak('Command not recognized. Please try again.');
+      }
+    } catch (error) {
+      Haptics.notificationAsync(Haptics.NotificationFeedbackType.Error);
+      await speak('Error processing command. Please try again.');
+    } finally {
+      setState(prev => ({ ...prev, isProcessing: false }));
+    }
+  };
+
+  const speak = async (text: string): Promise<void> => {
+    return new Promise((resolve) => {
+      Speech.speak(text, {
+        language: 'en-US',
+        pitch: 1.0,
+        rate: 0.9,
+        onDone: resolve,
+        onError: () => resolve(),
+      });
+    });
+  };
+
+  const startListening = useCallback(async () => {
+    try {
+      setState(prev => ({ ...prev, error: null, transcript: '' }));
+
+      await Voice.start('en-US', {
+        EXTRA_SPEECH_INPUT_COMPLETE_SILENCE_LENGTH_MILLIS: 1500,
+        EXTRA_SPEECH_INPUT_MINIMUM_LENGTH_MILLIS: 500,
+      });
+
+      Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium);
+    } catch (error) {
+      setState(prev => ({
+        ...prev,
+        error: 'Failed to start voice recognition',
+      }));
+    }
+  }, []);
+
+  const stopListening = useCallback(async () => {
+    try {
+      await Voice.stop();
+      Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
+    } catch (error) {
+      console.error('Failed to stop voice recognition:', error);
+    }
+  }, []);
+
+  const cancelListening = useCallback(async () => {
+    try {
+      await Voice.cancel();
+      setState(prev => ({
+        ...prev,
+        isListening: false,
+        partialTranscript: '',
+      }));
+    } catch (error) {
+      console.error('Failed to cancel voice recognition:', error);
+    }
+  }, []);
+
+  return {
+    ...state,
+    startListening,
+    stopListening,
+    cancelListening,
+    speak,
+    isAvailable: Voice.isAvailable,
+  };
+}
+```
+
+### Voice Input UI Component
+
+```typescript
+// src/components/VoiceInput.tsx
+import React from 'react';
+import { View, Text, Pressable, StyleSheet } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  withRepeat,
+  withTiming,
+  useSharedValue,
+  withSequence,
+} from 'react-native-reanimated';
+import { Mic, MicOff, Loader } from 'lucide-react-native';
+import { useVoice } from '@/hooks/useVoice';
+
+export function VoiceInput() {
+  const {
+    isListening,
+    partialTranscript,
+    transcript,
+    isProcessing,
+    error,
+    startListening,
+    stopListening,
+  } = useVoice();
+
+  const pulseScale = useSharedValue(1);
+
+  React.useEffect(() => {
+    if (isListening) {
+      pulseScale.value = withRepeat(
+        withSequence(
+          withTiming(1.2, { duration: 500 }),
+          withTiming(1, { duration: 500 })
+        ),
+        -1,
+        true
+      );
+    } else {
+      pulseScale.value = withTiming(1, { duration: 200 });
+    }
+  }, [isListening]);
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: pulseScale.value }],
+  }));
+
+  return (
+    <View style={styles.container}>
+      {(partialTranscript || transcript) && (
+        <View style={styles.transcriptContainer}>
+          <Text style={styles.transcript}>
+            {partialTranscript || transcript}
+          </Text>
+        </View>
+      )}
+
+      {error && (
+        <Text style={styles.error}>{error}</Text>
+      )}
+
+      <Animated.View style={[styles.buttonWrapper, animatedStyle]}>
+        <Pressable
+          style={[
+            styles.button,
+            isListening && styles.buttonActive,
+            isProcessing && styles.buttonProcessing,
+          ]}
+          onPress={isListening ? stopListening : startListening}
+          disabled={isProcessing}
+        >
+          {isProcessing ? (
+            <Loader size={32} color="#fff" />
+          ) : isListening ? (
+            <MicOff size={32} color="#fff" />
+          ) : (
+            <Mic size={32} color="#fff" />
+          )}
+        </Pressable>
+      </Animated.View>
+
+      <Text style={styles.hint}>
+        {isListening
+          ? 'Listening... Tap to stop'
+          : isProcessing
+            ? 'Processing...'
+            : 'Tap to speak'}
+      </Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    padding: 20,
+  },
+  transcriptContainer: {
+    backgroundColor: '#f0f0f0',
+    borderRadius: 12,
+    padding: 16,
+    marginBottom: 20,
+    width: '100%',
+  },
+  transcript: {
+    fontSize: 16,
+    color: '#333',
+    textAlign: 'center',
+  },
+  error: {
+    color: '#e53935',
+    marginBottom: 10,
+  },
+  buttonWrapper: {
+    marginVertical: 20,
+  },
+  button: {
+    width: 80,
+    height: 80,
+    borderRadius: 40,
+    backgroundColor: '#6366f1',
+    alignItems: 'center',
+    justifyContent: 'center',
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.3,
+    shadowRadius: 8,
+    elevation: 8,
+  },
+  buttonActive: {
+    backgroundColor: '#ef4444',
+  },
+  buttonProcessing: {
+    backgroundColor: '#9ca3af',
+  },
+  hint: {
+    color: '#666',
+    fontSize: 14,
+  },
+});
+```
+
+---
+
+## 5. OfflineMode
+
+### Offline Architecture
+
+```
++------------------------------------------------------------------+
+|                      Offline Mode System                          |
++------------------------------------------------------------------+
+|                                                                   |
+|  +------------------+     +------------------+                    |
+|  |   Network        |     |   Connectivity   |                    |
+|  |   Monitor        |---->|   Store          |                    |
+|  +------------------+     +------------------+                    |
+|                                  |                                |
+|           +----------------------+----------------------+         |
+|           |                      |                      |         |
+|           v                      v                      v         |
+|  +------------------+   +------------------+   +------------------+|
+|  |   Action Queue   |   |   Data Cache     |   |   UI Indicators ||
+|  |   (pending ops)  |   |   (AsyncStorage) |   |   (offline bar) ||
+|  +------------------+   +------------------+   +------------------+|
+|           |                      |                                |
+|           v                      v                                |
+|  +------------------+   +------------------+                      |
+|  |   Sync Engine    |   |   Cache Manager  |                      |
+|  |   (on reconnect) |   |   (TTL, LRU)     |                      |
+|  +------------------+   +------------------+                      |
+|                                                                   |
++------------------------------------------------------------------+
+```
+
+### Offline Store Implementation
+
+```typescript
+// src/stores/offlineStore.ts
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import NetInfo, { NetInfoState } from '@react-native-community/netinfo';
+import { immer } from 'zustand/middleware/immer';
+
+interface PendingAction {
+  id: string;
+  type: 'command' | 'approval' | 'rejection' | 'websocket';
+  data: unknown;
+  createdAt: number;
+  retryCount: number;
+  maxRetries: number;
+  sessionId?: string;
+}
+
+interface CachedData {
+  key: string;
+  data: unknown;
+  timestamp: number;
+  ttl: number; // Time to live in ms
+}
+
+interface OfflineState {
+  isOnline: boolean;
+  isConnecting: boolean;
+  pendingActions: PendingAction[];
+  cache: Record<string, CachedData>;
+  lastSyncTimestamp: number;
+  syncInProgress: boolean;
+}
+
+interface OfflineActions {
+  setOnline: (online: boolean) => void;
+  setConnecting: (connecting: boolean) => void;
+  addPendingAction: (action: Omit<PendingAction, 'retryCount' | 'maxRetries'>) => void;
+  removePendingAction: (id: string) => void;
+  incrementRetry: (id: string) => void;
+  setCache: (key: string, data: unknown, ttl?: number) => void;
+  getCache: <T>(key: string) => T | null;
+  clearExpiredCache: () => void;
+  syncPendingActions: () => Promise<void>;
+}
+
+const DEFAULT_TTL = 1000 * 60 * 30; // 30 minutes
+const MAX_CACHE_SIZE = 100;
+
+export const useOfflineStore = create<OfflineState & OfflineActions>()(
+  persist(
+    immer((set, get) => ({
+      // State
+      isOnline: true,
+      isConnecting: false,
+      pendingActions: [],
+      cache: {},
+      lastSyncTimestamp: 0,
+      syncInProgress: false,
+
+      // Actions
+      setOnline: (online) =>
+        set((state) => {
+          state.isOnline = online;
+        }),
+
+      setConnecting: (connecting) =>
+        set((state) => {
+          state.isConnecting = connecting;
+        }),
+
+      addPendingAction: (action) =>
+        set((state) => {
+          state.pendingActions.push({
+            ...action,
+            retryCount: 0,
+            maxRetries: 3,
+          });
+        }),
+
+      removePendingAction: (id) =>
+        set((state) => {
+          state.pendingActions = state.pendingActions.filter(a => a.id !== id);
+        }),
+
+      incrementRetry: (id) =>
+        set((state) => {
+          const action = state.pendingActions.find(a => a.id === id);
+          if (action) {
+            action.retryCount++;
+          }
+        }),
+
+      setCache: (key, data, ttl = DEFAULT_TTL) =>
+        set((state) => {
+          // Implement LRU eviction
+          const cacheKeys = Object.keys(state.cache);
+          if (cacheKeys.length >= MAX_CACHE_SIZE) {
+            // Remove oldest entry
+            const oldest = cacheKeys.reduce((a, b) =>
+              state.cache[a].timestamp < state.cache[b].timestamp ? a : b
+            );
+            delete state.cache[oldest];
+          }
+
+          state.cache[key] = {
+            key,
+            data,
+            timestamp: Date.now(),
+            ttl,
+          };
+        }),
+
+      getCache: <T>(key: string): T | null => {
+        const cached = get().cache[key];
+        if (!cached) return null;
+
+        const isExpired = Date.now() - cached.timestamp > cached.ttl;
+        if (isExpired) {
+          get().clearExpiredCache();
+          return null;
+        }
+
+        return cached.data as T;
+      },
+
+      clearExpiredCache: () =>
+        set((state) => {
+          const now = Date.now();
+          Object.keys(state.cache).forEach((key) => {
+            const cached = state.cache[key];
+            if (now - cached.timestamp > cached.ttl) {
+              delete state.cache[key];
+            }
+          });
+        }),
+
+      syncPendingActions: async () => {
+        const state = get();
+        if (state.syncInProgress || !state.isOnline) return;
+
+        set((s) => { s.syncInProgress = true; });
+
+        const actionsToSync = [...state.pendingActions];
+
+        for (const action of actionsToSync) {
+          if (action.retryCount >= action.maxRetries) {
+            // Max retries exceeded, remove and notify user
+            get().removePendingAction(action.id);
+            continue;
+          }
+
+          try {
+            await executeAction(action);
+            get().removePendingAction(action.id);
+          } catch (error) {
+            console.error(`Failed to sync action ${action.id}:`, error);
+            get().incrementRetry(action.id);
+
+            // Exponential backoff
+            const delay = Math.min(1000 * Math.pow(2, action.retryCount), 30000);
+            await new Promise(r => setTimeout(r, delay));
+          }
+        }
+
+        set((s) => {
+          s.syncInProgress = false;
+          s.lastSyncTimestamp = Date.now();
+        });
+      },
+    })),
+    {
+      name: 'elsabro-offline',
+      storage: createJSONStorage(() => AsyncStorage),
+      partialize: (state) => ({
+        pendingActions: state.pendingActions,
+        cache: state.cache,
+        lastSyncTimestamp: state.lastSyncTimestamp,
+      }),
+    }
+  )
+);
+
+async function executeAction(action: PendingAction): Promise<void> {
+  const API_URL = process.env.EXPO_PUBLIC_API_URL;
+
+  switch (action.type) {
+    case 'command':
+      await fetch(`${API_URL}/sessions/${action.sessionId}/command`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(action.data),
+      });
+      break;
+
+    case 'approval':
+      await fetch(`${API_URL}/tasks/approve`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(action.data),
+      });
+      break;
+
+    case 'rejection':
+      await fetch(`${API_URL}/tasks/reject`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(action.data),
+      });
+      break;
+
+    default:
+      console.warn('Unknown action type:', action.type);
+  }
+}
+
+// Network monitor hook
+export function useNetworkMonitor() {
+  const { setOnline, setConnecting, syncPendingActions } = useOfflineStore();
+
+  React.useEffect(() => {
+    const unsubscribe = NetInfo.addEventListener((state: NetInfoState) => {
+      const wasOffline = !useOfflineStore.getState().isOnline;
+      const isNowOnline = state.isConnected && state.isInternetReachable;
+
+      setOnline(isNowOnline ?? false);
+      setConnecting(state.isConnected && !state.isInternetReachable);
+
+      // Trigger sync when coming back online
+      if (wasOffline && isNowOnline) {
+        syncPendingActions();
+      }
+    });
+
+    return () => unsubscribe();
+  }, []);
+}
+```
+
+### Offline Indicator Component
+
+```typescript
+// src/components/OfflineIndicator.tsx
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  withTiming,
+  withRepeat,
+  useSharedValue,
+} from 'react-native-reanimated';
+import { WifiOff, Loader, CloudOff } from 'lucide-react-native';
+import { useOfflineStore } from '@/stores/offlineStore';
+
+export function OfflineIndicator() {
+  const { isOnline, isConnecting, pendingActions, syncInProgress } = useOfflineStore();
+  const opacity = useSharedValue(0);
+
+  React.useEffect(() => {
+    opacity.value = withTiming(isOnline ? 0 : 1, { duration: 300 });
+  }, [isOnline]);
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    opacity: opacity.value,
+    transform: [{ translateY: opacity.value === 0 ? -50 : 0 }],
+  }));
+
+  if (isOnline && !syncInProgress) return null;
+
+  return (
+    <Animated.View style={[styles.container, animatedStyle]}>
+      <View style={[
+        styles.bar,
+        isConnecting && styles.barConnecting,
+        syncInProgress && styles.barSyncing,
+      ]}>
+        {syncInProgress ? (
+          <>
+            <Loader size={16} color="#fff" />
+            <Text style={styles.text}>Syncing {pendingActions.length} actions...</Text>
+          </>
+        ) : isConnecting ? (
+          <>
+            <Loader size={16} color="#fff" />
+            <Text style={styles.text}>Connecting...</Text>
+          </>
+        ) : (
+          <>
+            <WifiOff size={16} color="#fff" />
+            <Text style={styles.text}>
+              Offline {pendingActions.length > 0 && `(${pendingActions.length} pending)`}
+            </Text>
+          </>
+        )}
+      </View>
+    </Animated.View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    zIndex: 1000,
+  },
+  bar: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 8,
+    paddingVertical: 8,
+    paddingTop: 48, // Account for status bar
+    backgroundColor: '#ef4444',
+  },
+  barConnecting: {
+    backgroundColor: '#f59e0b',
+  },
+  barSyncing: {
+    backgroundColor: '#3b82f6',
+  },
+  text: {
+    color: '#fff',
+    fontSize: 14,
+    fontWeight: '500',
+  },
+});
+```
+
+---
+
+## 6. BiometricAuth
+
+### Authentication Flow
+
+```
++------------------------------------------------------------------+
+|                    Biometric Authentication Flow                  |
++------------------------------------------------------------------+
+|                                                                   |
+|  +------------------+                                             |
+|  |   App Launch     |                                             |
+|  +--------+---------+                                             |
+|           |                                                       |
+|           v                                                       |
+|  +------------------+     +------------------+                    |
+|  | Check Biometric  |---->|   Not Enrolled   |---> Password Login |
+|  | Enrollment       |     +------------------+                    |
+|  +--------+---------+                                             |
+|           | Enrolled                                              |
+|           v                                                       |
+|  +------------------+                                             |
+|  | Prompt Biometric |                                             |
+|  +--------+---------+                                             |
+|           |                                                       |
+|     +-----+-----+                                                 |
+|     |           |                                                 |
+|     v           v                                                 |
+|  Success     Failure                                              |
+|     |           |                                                 |
+|     v           v                                                 |
+|  +------------------+     +------------------+                    |
+|  | Retrieve Token   |     | Show PIN Fallback|                    |
+|  | from SecureStore |     +--------+---------+                    |
+|  +--------+---------+              |                              |
+|           |                        |                              |
+|           v                        v                              |
+|  +------------------+     +------------------+                    |
+|  | Validate Token   |     | Validate PIN     |                    |
+|  +--------+---------+     +--------+---------+                    |
+|           |                        |                              |
+|           +------------------------+                              |
+|                        |                                          |
+|                        v                                          |
+|              +------------------+                                 |
+|              |   Authenticated  |                                 |
+|              +------------------+                                 |
+|                                                                   |
++------------------------------------------------------------------+
+```
+
+### Biometric Auth Implementation
+
+```typescript
+// src/hooks/useBiometric.ts
+import { useState, useCallback, useEffect } from 'react';
+import * as LocalAuthentication from 'expo-local-authentication';
+import * as SecureStore from 'expo-secure-store';
+import { Platform } from 'react-native';
+import * as Haptics from 'expo-haptics';
+
+interface BiometricState {
+  isAvailable: boolean;
+  biometricType: 'fingerprint' | 'facial' | 'iris' | null;
+  isEnrolled: boolean;
+  isAuthenticating: boolean;
+  error: string | null;
+}
+
+const SECURE_KEYS = {
+  ACCESS_TOKEN: 'elsabro_access_token',
+  REFRESH_TOKEN: 'elsabro_refresh_token',
+  PIN_HASH: 'elsabro_pin_hash',
+  BIOMETRIC_ENABLED: 'elsabro_biometric_enabled',
+} as const;
+
+export function useBiometric() {
+  const [state, setState] = useState<BiometricState>({
+    isAvailable: false,
+    biometricType: null,
+    isEnrolled: false,
+    isAuthenticating: false,
+    error: null,
+  });
+
+  useEffect(() => {
+    checkBiometricAvailability();
+  }, []);
+
+  const checkBiometricAvailability = async () => {
+    try {
+      const compatible = await LocalAuthentication.hasHardwareAsync();
+      const enrolled = await LocalAuthentication.isEnrolledAsync();
+      const types = await LocalAuthentication.supportedAuthenticationTypesAsync();
+
+      let biometricType: BiometricState['biometricType'] = null;
+
+      if (types.includes(LocalAuthentication.AuthenticationType.FACIAL_RECOGNITION)) {
+        biometricType = 'facial';
+      } else if (types.includes(LocalAuthentication.AuthenticationType.FINGERPRINT)) {
+        biometricType = 'fingerprint';
+      } else if (types.includes(LocalAuthentication.AuthenticationType.IRIS)) {
+        biometricType = 'iris';
+      }
+
+      setState(prev => ({
+        ...prev,
+        isAvailable: compatible,
+        isEnrolled: enrolled,
+        biometricType,
+      }));
+    } catch (error) {
+      console.error('Biometric check failed:', error);
+    }
+  };
+
+  const authenticate = useCallback(async (): Promise<boolean> => {
+    setState(prev => ({ ...prev, isAuthenticating: true, error: null }));
+
+    try {
+      const result = await LocalAuthentication.authenticateAsync({
+        promptMessage: 'Authenticate to access ELSABRO',
+        subtitle: Platform.OS === 'android' ? 'Use biometrics or PIN' : undefined,
+        fallbackLabel: 'Use PIN',
+        cancelLabel: 'Cancel',
+        disableDeviceFallback: false,
+      });
+
+      if (result.success) {
+        Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
+        setState(prev => ({ ...prev, isAuthenticating: false }));
+        return true;
+      } else {
+        Haptics.notificationAsync(Haptics.NotificationFeedbackType.Error);
+        setState(prev => ({
+          ...prev,
+          isAuthenticating: false,
+          error: result.error === 'user_cancel'
+            ? 'Authentication cancelled'
+            : 'Authentication failed',
+        }));
+        return false;
+      }
+    } catch (error) {
+      setState(prev => ({
+        ...prev,
+        isAuthenticating: false,
+        error: 'Authentication error',
+      }));
+      return false;
+    }
+  }, []);
+
+  return {
+    ...state,
+    authenticate,
+    checkBiometricAvailability,
+  };
+}
+
+// Secure Storage Utilities
+export const SecureStorage = {
+  async setToken(token: string): Promise<void> {
+    await SecureStore.setItemAsync(SECURE_KEYS.ACCESS_TOKEN, token, {
+      keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+    });
+  },
+
+  async getToken(): Promise<string | null> {
+    return SecureStore.getItemAsync(SECURE_KEYS.ACCESS_TOKEN);
+  },
+
+  async setRefreshToken(token: string): Promise<void> {
+    await SecureStore.setItemAsync(SECURE_KEYS.REFRESH_TOKEN, token, {
+      keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+    });
+  },
+
+  async getRefreshToken(): Promise<string | null> {
+    return SecureStore.getItemAsync(SECURE_KEYS.REFRESH_TOKEN);
+  },
+
+  async setPinHash(hash: string): Promise<void> {
+    await SecureStore.setItemAsync(SECURE_KEYS.PIN_HASH, hash, {
+      keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+    });
+  },
+
+  async getPinHash(): Promise<string | null> {
+    return SecureStore.getItemAsync(SECURE_KEYS.PIN_HASH);
+  },
+
+  async setBiometricEnabled(enabled: boolean): Promise<void> {
+    await SecureStore.setItemAsync(
+      SECURE_KEYS.BIOMETRIC_ENABLED,
+      enabled ? 'true' : 'false'
+    );
+  },
+
+  async isBiometricEnabled(): Promise<boolean> {
+    const value = await SecureStore.getItemAsync(SECURE_KEYS.BIOMETRIC_ENABLED);
+    return value === 'true';
+  },
+
+  async clearAll(): Promise<void> {
+    await Promise.all([
+      SecureStore.deleteItemAsync(SECURE_KEYS.ACCESS_TOKEN),
+      SecureStore.deleteItemAsync(SECURE_KEYS.REFRESH_TOKEN),
+      SecureStore.deleteItemAsync(SECURE_KEYS.PIN_HASH),
+      SecureStore.deleteItemAsync(SECURE_KEYS.BIOMETRIC_ENABLED),
+    ]);
+  },
+};
+```
+
+### Auth Store
+
+```typescript
+// src/stores/authStore.ts
+import { create } from 'zustand';
+import { SecureStorage } from '@/hooks/useBiometric';
+
+interface AuthState {
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  accessToken: string | null;
+  user: User | null;
+  pendingDeepLink: string | null;
+}
+
+interface AuthActions {
+  initialize: () => Promise<void>;
+  login: (credentials: LoginCredentials) => Promise<void>;
+  loginWithBiometric: () => Promise<boolean>;
+  logout: () => Promise<void>;
+  refreshToken: () => Promise<void>;
+  setPendingDeepLink: (url: string | null) => void;
+}
+
+export const useAuthStore = create<AuthState & AuthActions>((set, get) => ({
+  isAuthenticated: false,
+  isLoading: true,
+  accessToken: null,
+  user: null,
+  pendingDeepLink: null,
+
+  initialize: async () => {
+    try {
+      const token = await SecureStorage.getToken();
+
+      if (token) {
+        // Validate token with server
+        const response = await fetch(`${API_URL}/auth/validate`, {
+          headers: { Authorization: `Bearer ${token}` },
+        });
+
+        if (response.ok) {
+          const user = await response.json();
+          set({
+            isAuthenticated: true,
+            accessToken: token,
+            user,
+            isLoading: false,
+          });
+          return;
+        }
+
+        // Token invalid, try refresh
+        await get().refreshToken();
+      }
+    } catch (error) {
+      console.error('Auth initialization failed:', error);
+    }
+
+    set({ isLoading: false });
+  },
+
+  login: async (credentials) => {
+    const response = await fetch(`${API_URL}/auth/login`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(credentials),
+    });
+
+    if (!response.ok) {
+      throw new Error('Login failed');
+    }
+
+    const { accessToken, refreshToken, user } = await response.json();
+
+    await SecureStorage.setToken(accessToken);
+    await SecureStorage.setRefreshToken(refreshToken);
+
+    set({
+      isAuthenticated: true,
+      accessToken,
+      user,
+    });
+  },
+
+  loginWithBiometric: async () => {
+    const token = await SecureStorage.getToken();
+
+    if (!token) {
+      return false;
+    }
+
+    // Validate stored token
+    const response = await fetch(`${API_URL}/auth/validate`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (response.ok) {
+      const user = await response.json();
+      set({
+        isAuthenticated: true,
+        accessToken: token,
+        user,
+      });
+      return true;
+    }
+
+    // Token expired, try refresh
+    try {
+      await get().refreshToken();
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  logout: async () => {
+    await SecureStorage.clearAll();
+    set({
+      isAuthenticated: false,
+      accessToken: null,
+      user: null,
+    });
+  },
+
+  refreshToken: async () => {
+    const refreshToken = await SecureStorage.getRefreshToken();
+
+    if (!refreshToken) {
+      throw new Error('No refresh token');
+    }
+
+    const response = await fetch(`${API_URL}/auth/refresh`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshToken }),
+    });
+
+    if (!response.ok) {
+      await get().logout();
+      throw new Error('Refresh failed');
+    }
+
+    const { accessToken, user } = await response.json();
+
+    await SecureStorage.setToken(accessToken);
+
+    set({
+      isAuthenticated: true,
+      accessToken,
+      user,
+    });
+  },
+
+  setPendingDeepLink: (url) => set({ pendingDeepLink: url }),
+}));
+```
+
+---
+
+## 7. Widget Support
+
+### Widget Architecture
+
+```
++------------------------------------------------------------------+
+|                      Widget System Architecture                   |
++------------------------------------------------------------------+
+|                                                                   |
+|  iOS (WidgetKit)                    Android (App Widgets)         |
+|  +-------------------------+        +-------------------------+   |
+|  |   SwiftUI Widget View   |        |   RemoteViews Layout    |   |
+|  +------------+------------+        +------------+------------+   |
+|               |                                  |                |
+|               v                                  v                |
+|  +-------------------------+        +-------------------------+   |
+|  |   Widget Timeline       |        |   AppWidgetProvider     |   |
+|  |   Provider              |        |                         |   |
+|  +------------+------------+        +------------+------------+   |
+|               |                                  |                |
+|               v                                  v                |
+|  +-------------------------+        +-------------------------+   |
+|  |   App Group Shared      |        |   SharedPreferences     |   |
+|  |   UserDefaults          |        |   (MODE_PRIVATE)        |   |
+|  +------------+------------+        +------------+------------+   |
+|               |                                  |                |
+|               +----------------------------------+                |
+|                              |                                    |
+|                              v                                    |
+|               +------------------------------+                    |
+|               |   React Native Bridge        |                    |
+|               |   (expo-widget-extension)    |                    |
+|               +------------------------------+                    |
+|                                                                   |
++------------------------------------------------------------------+
+```
+
+### iOS Widget Implementation
+
+```swift
+// widgets/ios/ElsabroWidget/ElsabroWidget.swift
+import WidgetKit
+import SwiftUI
+
+struct SessionEntry: TimelineEntry {
+    let date: Date
+    let session: SessionData?
+    let configuration: ConfigurationIntent
+}
+
+struct SessionData: Codable {
+    let id: String
+    let name: String
+    let status: String
+    let progress: Int
+    let currentTask: String?
+    let agentCount: Int
+}
+
+struct Provider: IntentTimelineProvider {
+    func placeholder(in context: Context) -> SessionEntry {
+        SessionEntry(
+            date: Date(),
+            session: SessionData(
+                id: "placeholder",
+                name: "Loading...",
+                status: "active",
+                progress: 50,
+                currentTask: nil,
+                agentCount: 0
+            ),
+            configuration: ConfigurationIntent()
+        )
+    }
+
+    func getSnapshot(
+        for configuration: ConfigurationIntent,
+        in context: Context,
+        completion: @escaping (SessionEntry) -> Void
+    ) {
+        let entry = SessionEntry(
+            date: Date(),
+            session: loadSessionData(),
+            configuration: configuration
+        )
+        completion(entry)
+    }
+
+    func getTimeline(
+        for configuration: ConfigurationIntent,
+        in context: Context,
+        completion: @escaping (Timeline<SessionEntry>) -> Void
+    ) {
+        let session = loadSessionData()
+        let entry = SessionEntry(
+            date: Date(),
+            session: session,
+            configuration: configuration
+        )
+
+        // Update every 5 minutes
+        let nextUpdate = Calendar.current.date(
+            byAdding: .minute,
+            value: 5,
+            to: Date()
+        )!
+
+        let timeline = Timeline(
+            entries: [entry],
+            policy: .after(nextUpdate)
+        )
+        completion(timeline)
+    }
+
+    private func loadSessionData() -> SessionData? {
+        guard let userDefaults = UserDefaults(suiteName: "group.io.elsabro.companion"),
+              let data = userDefaults.data(forKey: "activeSession"),
+              let session = try? JSONDecoder().decode(SessionData.self, from: data)
+        else {
+            return nil
+        }
+        return session
+    }
+}
+
+struct ElsabroWidgetEntryView: View {
+    var entry: Provider.Entry
+    @Environment(\.widgetFamily) var family
+
+    var body: some View {
+        switch family {
+        case .systemSmall:
+            SmallWidgetView(session: entry.session)
+        case .systemMedium:
+            MediumWidgetView(session: entry.session)
+        case .systemLarge:
+            LargeWidgetView(session: entry.session)
+        default:
+            SmallWidgetView(session: entry.session)
+        }
+    }
+}
+
+struct SmallWidgetView: View {
+    let session: SessionData?
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            HStack {
+                Image(systemName: "sparkles")
+                    .foregroundColor(.purple)
+                Text("ELSABRO")
+                    .font(.caption)
+                    .fontWeight(.bold)
+            }
+
+            if let session = session {
+                Text(session.name)
+                    .font(.headline)
+                    .lineLimit(1)
+
+                ProgressView(value: Double(session.progress) / 100)
+                    .tint(statusColor(session.status))
+
+                Text("\(session.progress)%")
+                    .font(.caption2)
+                    .foregroundColor(.secondary)
+            } else {
+                Text("No active session")
+                    .font(.caption)
+                    .foregroundColor(.secondary)
+            }
+        }
+        .padding()
+        .widgetURL(URL(string: "elsabro://session/\(session?.id ?? "")"))
+    }
+
+    private func statusColor(_ status: String) -> Color {
+        switch status {
+        case "active": return .green
+        case "paused": return .orange
+        case "error": return .red
+        default: return .blue
+        }
+    }
+}
+
+struct MediumWidgetView: View {
+    let session: SessionData?
+
+    var body: some View {
+        HStack(spacing: 16) {
+            SmallWidgetView(session: session)
+
+            if let session = session {
+                VStack(alignment: .leading, spacing: 4) {
+                    Label {
+                        Text(session.status.capitalized)
+                    } icon: {
+                        Circle()
+                            .fill(statusColor(session.status))
+                            .frame(width: 8, height: 8)
+                    }
+                    .font(.caption)
+
+                    if let task = session.currentTask {
+                        Text(task)
+                            .font(.caption2)
+                            .foregroundColor(.secondary)
+                            .lineLimit(2)
+                    }
+
+                    Spacer()
+
+                    HStack {
+                        Image(systemName: "person.2.fill")
+                        Text("\(session.agentCount) agents")
+                    }
+                    .font(.caption2)
+                    .foregroundColor(.secondary)
+                }
+            }
+        }
+        .padding()
+    }
+
+    private func statusColor(_ status: String) -> Color {
+        switch status {
+        case "active": return .green
+        case "paused": return .orange
+        case "error": return .red
+        default: return .blue
+        }
+    }
+}
+
+@main
+struct ElsabroWidget: Widget {
+    let kind: String = "ElsabroWidget"
+
+    var body: some WidgetConfiguration {
+        IntentConfiguration(
+            kind: kind,
+            intent: ConfigurationIntent.self,
+            provider: Provider()
+        ) { entry in
+            ElsabroWidgetEntryView(entry: entry)
+        }
+        .configurationDisplayName("ELSABRO Session")
+        .description("Monitor your active ELSABRO session")
+        .supportedFamilies([.systemSmall, .systemMedium, .systemLarge])
+    }
+}
+```
+
+### Android Widget Implementation
+
+```kotlin
+// widgets/android/app/src/main/java/io/elsabro/companion/widget/ElsabroWidget.kt
+package io.elsabro.companion.widget
+
+import android.app.PendingIntent
+import android.appwidget.AppWidgetManager
+import android.appwidget.AppWidgetProvider
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.widget.RemoteViews
+import com.google.gson.Gson
+import io.elsabro.companion.R
+
+data class SessionData(
+    val id: String,
+    val name: String,
+    val status: String,
+    val progress: Int,
+    val currentTask: String?,
+    val agentCount: Int
+)
+
+class ElsabroWidget : AppWidgetProvider() {
+
+    override fun onUpdate(
+        context: Context,
+        appWidgetManager: AppWidgetManager,
+        appWidgetIds: IntArray
+    ) {
+        for (appWidgetId in appWidgetIds) {
+            updateAppWidget(context, appWidgetManager, appWidgetId)
+        }
+    }
+
+    override fun onReceive(context: Context, intent: Intent) {
+        super.onReceive(context, intent)
+
+        when (intent.action) {
+            ACTION_REFRESH -> {
+                val appWidgetId = intent.getIntExtra(
+                    AppWidgetManager.EXTRA_APPWIDGET_ID,
+                    AppWidgetManager.INVALID_APPWIDGET_ID
+                )
+                if (appWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID) {
+                    val appWidgetManager = AppWidgetManager.getInstance(context)
+                    updateAppWidget(context, appWidgetManager, appWidgetId)
+                }
+            }
+        }
+    }
+
+    companion object {
+        const val ACTION_REFRESH = "io.elsabro.companion.WIDGET_REFRESH"
+
+        internal fun updateAppWidget(
+            context: Context,
+            appWidgetManager: AppWidgetManager,
+            appWidgetId: Int
+        ) {
+            val views = RemoteViews(context.packageName, R.layout.elsabro_widget)
+
+            val session = loadSessionData(context)
+
+            if (session != null) {
+                views.setTextViewText(R.id.session_name, session.name)
+                views.setTextViewText(R.id.progress_text, "${session.progress}%")
+                views.setProgressBar(R.id.progress_bar, 100, session.progress, false)
+                views.setTextViewText(R.id.status_text, session.status.capitalize())
+                views.setTextViewText(
+                    R.id.current_task,
+                    session.currentTask ?: "No current task"
+                )
+                views.setTextViewText(R.id.agent_count, "${session.agentCount} agents")
+
+                // Set status indicator color
+                val statusColor = when (session.status) {
+                    "active" -> android.R.color.holo_green_light
+                    "paused" -> android.R.color.holo_orange_light
+                    "error" -> android.R.color.holo_red_light
+                    else -> android.R.color.holo_blue_light
+                }
+                views.setInt(R.id.status_indicator, "setColorFilter",
+                    context.getColor(statusColor))
+
+                // Set click intent to open session
+                val openIntent = Intent(
+                    Intent.ACTION_VIEW,
+                    Uri.parse("elsabro://session/${session.id}")
+                ).apply {
+                    flags = Intent.FLAG_ACTIVITY_NEW_TASK
+                }
+                val openPendingIntent = PendingIntent.getActivity(
+                    context,
+                    0,
+                    openIntent,
+                    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+                )
+                views.setOnClickPendingIntent(R.id.widget_container, openPendingIntent)
+            } else {
+                views.setTextViewText(R.id.session_name, "No active session")
+                views.setTextViewText(R.id.progress_text, "--")
+                views.setProgressBar(R.id.progress_bar, 100, 0, false)
+            }
+
+            // Refresh button
+            val refreshIntent = Intent(context, ElsabroWidget::class.java).apply {
+                action = ACTION_REFRESH
+                putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
+            }
+            val refreshPendingIntent = PendingIntent.getBroadcast(
+                context,
+                appWidgetId,
+                refreshIntent,
+                PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+            )
+            views.setOnClickPendingIntent(R.id.refresh_button, refreshPendingIntent)
+
+            appWidgetManager.updateAppWidget(appWidgetId, views)
+        }
+
+        private fun loadSessionData(context: Context): SessionData? {
+            val prefs = context.getSharedPreferences(
+                "elsabro_widget_data",
+                Context.MODE_PRIVATE
+            )
+            val json = prefs.getString("activeSession", null) ?: return null
+            return try {
+                Gson().fromJson(json, SessionData::class.java)
+            } catch (e: Exception) {
+                null
+            }
+        }
+    }
+}
+```
+
+### React Native Widget Bridge
+
+```typescript
+// src/services/widgetBridge.ts
+import { NativeModules, Platform } from 'react-native';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+interface WidgetData {
+  id: string;
+  name: string;
+  status: string;
+  progress: number;
+  currentTask: string | null;
+  agentCount: number;
+}
+
+const { WidgetModule } = NativeModules;
+
+export async function updateWidget(session: WidgetData | null): Promise<void> {
+  const data = session ? JSON.stringify(session) : null;
+
+  if (Platform.OS === 'ios') {
+    // Update shared UserDefaults for iOS widget
+    await WidgetModule.setWidgetData('activeSession', data);
+    await WidgetModule.reloadAllTimelines();
+  } else if (Platform.OS === 'android') {
+    // Update SharedPreferences for Android widget
+    await WidgetModule.updateWidgetData('activeSession', data);
+    await WidgetModule.requestWidgetUpdate();
+  }
+}
+
+export async function clearWidgetData(): Promise<void> {
+  if (Platform.OS === 'ios') {
+    await WidgetModule.setWidgetData('activeSession', null);
+    await WidgetModule.reloadAllTimelines();
+  } else if (Platform.OS === 'android') {
+    await WidgetModule.updateWidgetData('activeSession', null);
+    await WidgetModule.requestWidgetUpdate();
+  }
+}
+
+// Hook to keep widget updated
+export function useWidgetSync() {
+  const { activeSessionId, sessions } = useSessionStore();
+
+  useEffect(() => {
+    if (activeSessionId && sessions[activeSessionId]) {
+      const session = sessions[activeSessionId];
+      updateWidget({
+        id: session.id,
+        name: session.name,
+        status: session.status,
+        progress: session.progress,
+        currentTask: session.currentTask,
+        agentCount: session.agents.length,
+      });
+    } else {
+      clearWidgetData();
+    }
+  }, [activeSessionId, sessions]);
+}
+```
+
+---
+
+## 8. Commands
+
+### /elsabro:mobile Commands
+
+| Command | Description | Options |
+|---------|-------------|---------|
+| `/elsabro:mobile setup` | Initialize mobile companion | `--platform ios\|android\|both` |
+| `/elsabro:mobile sync` | Force synchronization | `--full`, `--sessions-only` |
+| `/elsabro:mobile notify` | Manage notifications | `--test`, `--status`, `--clear` |
+| `/elsabro:mobile voice` | Voice input control | `--enable`, `--disable`, `--test` |
+
+### Command Implementation
+
+```typescript
+// src/commands/mobile.ts
+import { useSessionStore } from '@/stores/sessionStore';
+import { useOfflineStore } from '@/stores/offlineStore';
+import { useNotificationStore } from '@/stores/notificationStore';
+import { wsClient } from '@/services/websocket';
+
+interface CommandResult {
+  success: boolean;
+  message: string;
+  data?: unknown;
+}
+
+export async function executeCommand(
+  command: string,
+  args: string[]
+): Promise<CommandResult> {
+  const [subcommand, ...options] = args;
+
+  switch (subcommand) {
+    case 'setup':
+      return handleSetup(options);
+    case 'sync':
+      return handleSync(options);
+    case 'notify':
+      return handleNotify(options);
+    case 'voice':
+      return handleVoice(options);
+    default:
+      return {
+        success: false,
+        message: `Unknown subcommand: ${subcommand}`,
+      };
+  }
+}
+
+async function handleSetup(options: string[]): Promise<CommandResult> {
+  const platform = options.find(o => o.startsWith('--platform='))
+    ?.split('=')[1] || 'both';
+
+  // Verify dependencies
+  const checks = {
+    notifications: await checkNotificationPermission(),
+    biometrics: await checkBiometricEnrollment(),
+    network: await checkNetworkConnectivity(),
+  };
+
+  return {
+    success: Object.values(checks).every(Boolean),
+    message: 'Mobile setup complete',
+    data: {
+      platform,
+      checks,
+      timestamp: new Date().toISOString(),
+    },
+  };
+}
+
+async function handleSync(options: string[]): Promise<CommandResult> {
+  const fullSync = options.includes('--full');
+  const sessionsOnly = options.includes('--sessions-only');
+
+  try {
+    if (fullSync) {
+      // Clear cache and sync everything
+      const offlineStore = useOfflineStore.getState();
+      offlineStore.clearExpiredCache();
+    }
+
+    // Trigger sync
+    wsClient.send({
+      type: 'session:sync:request',
+      payload: {
+        fullSync,
+        sessionsOnly,
+        lastSync: useSessionStore.getState().lastSyncTimestamp,
+      },
+      timestamp: Date.now(),
+      messageId: crypto.randomUUID(),
+    });
+
+    // Also sync pending actions
+    await useOfflineStore.getState().syncPendingActions();
+
+    return {
+      success: true,
+      message: fullSync ? 'Full sync initiated' : 'Sync initiated',
+      data: {
+        pendingActions: useOfflineStore.getState().pendingActions.length,
+        lastSync: useSessionStore.getState().lastSyncTimestamp,
+      },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: `Sync failed: ${error}`,
+    };
+  }
+}
+
+async function handleNotify(options: string[]): Promise<CommandResult> {
+  if (options.includes('--test')) {
+    // Send test notification
+    await Notifications.scheduleNotificationAsync({
+      content: {
+        title: 'ELSABRO Test',
+        body: 'This is a test notification from ELSABRO Mobile',
+        data: { type: 'test' },
+      },
+      trigger: null,
+    });
+    return { success: true, message: 'Test notification sent' };
+  }
+
+  if (options.includes('--status')) {
+    const permissions = await Notifications.getPermissionsAsync();
+    return {
+      success: true,
+      message: 'Notification status',
+      data: {
+        granted: permissions.granted,
+        canAskAgain: permissions.canAskAgain,
+        status: permissions.status,
+      },
+    };
+  }
+
+  if (options.includes('--clear')) {
+    await Notifications.dismissAllNotificationsAsync();
+    await Notifications.setBadgeCountAsync(0);
+    return { success: true, message: 'Notifications cleared' };
+  }
+
+  return { success: false, message: 'No valid option provided' };
+}
+
+async function handleVoice(options: string[]): Promise<CommandResult> {
+  if (options.includes('--enable')) {
+    await AsyncStorage.setItem('voice_enabled', 'true');
+    return { success: true, message: 'Voice input enabled' };
+  }
+
+  if (options.includes('--disable')) {
+    await AsyncStorage.setItem('voice_enabled', 'false');
+    return { success: true, message: 'Voice input disabled' };
+  }
+
+  if (options.includes('--test')) {
+    const isAvailable = await Voice.isAvailable();
+    return {
+      success: true,
+      message: 'Voice input status',
+      data: { available: isAvailable },
+    };
+  }
+
+  return { success: false, message: 'No valid option provided' };
+}
+```
+
+---
+
+## Appendix: Type Definitions
+
+```typescript
+// src/types/index.ts
+
+export interface Session {
+  id: string;
+  name: string;
+  status: 'active' | 'paused' | 'completed' | 'error';
+  agents: string[];
+  currentTask: string | null;
+  progress: number;
+  startedAt: string;
+  lastActivity: string;
+  error?: string;
+}
+
+export interface SessionDetail extends Session {
+  logs: SessionLog[];
+  tasks: Task[];
+  metrics: SessionMetrics;
+}
+
+export interface SessionLog {
+  id: string;
+  timestamp: string;
+  level: 'info' | 'warn' | 'error' | 'debug';
+  message: string;
+  agentId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface Task {
+  id: string;
+  name: string;
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'awaiting_approval';
+  assignedAgent: string;
+  createdAt: string;
+  completedAt?: string;
+}
+
+export interface SessionMetrics {
+  tokenUsage: number;
+  estimatedCost: number;
+  duration: number;
+  tasksCompleted: number;
+  tasksFailed: number;
+}
+
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  avatar?: string;
+  preferences: UserPreferences;
+}
+
+export interface UserPreferences {
+  theme: 'light' | 'dark' | 'system';
+  notifications: NotificationPreferences;
+  voiceEnabled: boolean;
+  hapticFeedback: boolean;
+}
+
+export interface NotificationPreferences {
+  taskCompleted: boolean;
+  buildFailed: boolean;
+  approvalNeeded: boolean;
+  sessionUpdates: boolean;
+}
+
+export interface LoginCredentials {
+  email: string;
+  password: string;
+}
+
+export interface CreateSessionRequest {
+  name: string;
+  agents: string[];
+  config?: Record<string, unknown>;
+}
+
+export interface CommandResponse {
+  success: boolean;
+  message: string;
+  data?: unknown;
+}
+
+export interface SessionFilters {
+  status?: Session['status'][];
+  search?: string;
+  sortBy?: 'name' | 'startedAt' | 'lastActivity';
+  sortOrder?: 'asc' | 'desc';
+}
+```
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 3.7.0 | 2026-02-02 | Initial mobile companion documentation |
+
+---
+
+*ELSABRO Mobile Companion - Technical Reference v3.7*