Integrate AI Kit

Add AI Kit screens to the Core Expo app while reusing the authenticated Hono API, database, storage, and usage controls from web.

The mobile app is a client of the same AI backend as web. Integrate the selected AI template on the server first, then port its Expo route and UI into Core Kit.

Complete the backend first

Follow the web AI Kit recipe through API, database, environment, and migration setup before changing the mobile app. Provider SDKs and secret keys must stay on that backend.

AI Kit includes mobile implementations for chat, image generation, RAG, text to speech, and voice. Each one calls the shared /api/ai/* routes, but some require native modules that cannot run in Expo Go.

Pick the native surface

Template	Expo source	Extra native work
Chat	`(apps)/chat`, `modules/chat`	Attachments and an Expo-compatible streaming fetch
Image	`(apps)/image`, `modules/image`	Image picker, gallery, and sharing
RAG	`(apps)/rag`, `modules/rag`	Document picker, PDF renderer, blob utility, patches
Text to speech	`(apps)/tts`, `modules/tts`	Audio playback
Voice	`(apps)/voice`, `modules/voice`	LiveKit, WebRTC, microphone permissions, development build

Start with chat or image if you want the smallest native integration. Add RAG or voice only after a development build works reliably.

Port one route and module

Copy the selected files from the AI repository into the Core mobile app. For chat:

../ai/apps/mobile/src/app/(apps)/chat
../ai/apps/mobile/src/modules/chat

The feature also imports pieces from ../ai/apps/mobile/src/modules/common. Port only the components and hooks reached by those imports. Adapt the screen to Core's existing authenticated route group, drawer or tab navigation, theme, and @workspace/ui-mobile components instead of replacing the application layout.

A dashboard destination keeps the feature behind Core auth:

apps/mobile/src/app/dashboard/(user)/chat
apps/mobile/src/modules/ai/chat

Core already has dashboard/(user)/ai.tsx wired to the flat /api/ai/chat demo endpoint. Replace that screen or update its transport when you switch the backend to AI Kit's nested routes.

Keep the Core session on streaming requests

Core's mobile API client already sends the Better Auth cookie and the MOBILE platform header. Keep that client as the source of URLs and session state.

AI Kit chat uses an Expo-compatible transport because React Native does not use the browser's cookie jar:

apps/mobile/src/modules/ai/chat/composer/hooks/use-composer.tsx

new DefaultChatTransport({
  fetch: expoFetch as unknown as typeof globalThis.fetch,
  api: api.ai.chat.chats.$url().toString(),
  credentials: "omit",
  headers: () => ({
    cookie: `${config.cookie}=${useI18nConfig.getState().config.locale};${authClient.getCookie()}`,
    "x-client-platform": Platform.MOBILE,
    origin: Linking.createURL(""),
  }),
});

Keep Core's locale cookie, session cookie, platform header, and native origin on the streaming transport. Do not copy AI Kit's anonymous-session bootstrap or create a second auth client.

If a protected AI route returns 401, verify the API base URL, cookie header, and Core server's trusted mobile origin before changing the AI code.

Merge dependencies and native configuration

Use ../ai/apps/mobile/package.json as the dependency manifest for the selected template. Add only the packages imported by the files you port, using the versions compatible with Core's current Expo SDK.

For features with native code, also inspect and merge:

../ai/apps/mobile/app.config.ts
../ai/apps/mobile/metro.config.js
../ai/patches
../ai/pnpm-workspace.yaml

Do not replace those Core files. Merge the relevant config plugin, Metro transformer, allowBuilds entry, catalog version, or patch.

RAG needs the PDF and blob configuration used by its preview. Voice needs the LiveKit Expo plugin, WebRTC setup, and microphone permission strings. Rebuild the native app after either change:

pnpm --filter mobile ios
# or
pnpm --filter mobile android

Register the screen in Core's existing Expo Router layout. Preserve the providers already mounted by the Core app, including authentication, TanStack Query, theme, safe areas, analytics, and monitoring.

The copied AI UI should read:

Session state from Core's authClient
URLs from Core's typed Hono client
Shared response and request types from the ported AI packages
Product copy from Core's @workspace/i18n
Plan access or credits from the same backend policy used by web

Do not calculate entitlement or remaining usage only in the mobile client. The server must reject unauthorized or over-limit requests before calling a paid provider.

Verify on a device

pnpm --filter mobile dev

Use a simulator or development build and check:

A signed-in Core user can open the AI screen.
Streaming continues after multiple chunks and can be cancelled.
Reloaded history matches the web app for the same account.
Signed-out and over-limit requests fail without invoking a provider.
Backgrounding and resuming the app does not duplicate a generation.
File, camera, audio, and microphone permissions appear only for features that need them.

Keep the backend shared

Do not create a mobile-only provider route or database. Web and mobile should use the same Hono router, AI package, user ownership checks, storage paths, and usage policy. The platform-specific code ends at transport, navigation, permissions, and native presentation.

Web AI Kit integration

Port the AI packages, schemas, Hono routers, and provider configuration first.

Mobile API client

Review Core's cookie, platform header, and base URL setup.

Development builds

Configure native modules that are not available in Expo Go.