diff --git a/apps/mobile/README.md b/apps/mobile/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..f5be27c6c3f722075ce26a895d4e3ac684d4444b
--- /dev/null
+++ b/apps/mobile/README.md
@@ -0,0 +1,98 @@
+# T3 Code Mobile
+
+> [!WARNING]
+> T3 Code Mobile is currently in development and is not distributed yet. If you want to try it out, you can build it from source.
+
+## Quickstart
+
+> [!NOTE]
+> Uses native modules so using Expo Go is not supported. You need to use the Expo Dev Client.
+
+This app has three variants:
+
+- `development`: Expo dev client, installable side-by-side as `T3 Code Dev`
+- `preview`: persistent internal preview build, installable side-by-side as `T3 Code Preview`
+- `production`: store/release build as `T3 Code`
+
+Run commands from `apps/mobile`.
+
+T3 Cloud is optional and disabled in a fresh clone. Public configuration belongs in the
+repository-root `.env` or `.env.local`, not an `apps/mobile/.env` file. See
+[`../../.env.example`](../../.env.example).
+
+## Development
+
+Start Metro for the dev client:
+
+```bash
+vp run dev:client
+```
+
+Build and run the local iOS dev client:
+
+```bash
+vp run ios:dev
+```
+
+Build and run the local iOS preview app:
+
+```bash
+vp run ios:preview
+```
+
+Force the review diff highlighter engine:
+
+```bash
+EXPO_PUBLIC_REVIEW_HIGHLIGHTER_ENGINE=javascript vp run ios:dev
+```
+
+`javascript` is the default and recommended setting for the review diff screen. Set `EXPO_PUBLIC_REVIEW_HIGHLIGHTER_ENGINE=native` only when you explicitly want to test the native Shiki engine.
+
+Inspect the resolved Expo config for a variant:
+
+```bash
+vp run config:dev
+vp run config:preview
+```
+
+Run static checks for mobile native code:
+
+```bash
+node ../../scripts/mobile-native-static-check.ts
+```
+
+The native lint task runs SwiftLint for Swift plus ktlint and detekt for Kotlin. Missing native tools are reported as warnings and skipped locally. CI installs the default toolset from `apps/mobile/Brewfile` before running the native checks.
+
+## EAS Builds
+
+CI uses Expo fingerprinting with the `preview:dev` profile to reuse an existing compatible build when possible, or start a new internal EAS build when native runtime inputs change. Production and default local builds continue to use the `appVersion` runtime policy.
+
+For preview or production EAS environments, set `T3CODE_CLERK_PUBLISHABLE_KEY`,
+`T3CODE_CLERK_JWT_TEMPLATE`, and `T3CODE_RELAY_URL`
+as EAS environment variables. Expo config maps the canonical values into the mobile build.
+
+Create a PR preview dev-client build manually:
+
+```bash
+vp run eas:ios:preview:dev
+```
+
+Create a cloud dev-client build:
+
+```bash
+vp run eas:ios:dev
+```
+
+Create a persistent preview build:
+
+```bash
+vp run eas:ios:preview
+```
+
+Android equivalents:
+
+```bash
+vp run eas:android:dev
+vp run eas:android:preview:dev
+vp run eas:android:preview
+```
diff --git a/apps/mobile/modules/t3-terminal/README.md b/apps/mobile/modules/t3-terminal/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..09d927f473360d29fbfc410c582104e08d9725e9
--- /dev/null
+++ b/apps/mobile/modules/t3-terminal/README.md
@@ -0,0 +1,38 @@
+# T3 Mobile Terminal Native Module
+
+This local Expo module owns the native terminal surface for the mobile app.
+
+The JavaScript contract is intentionally small:
+
+- input from the native surface is emitted as `{ data: string }`
+- resize from the native surface is emitted as `{ cols: number, rows: number }`
+- remote PTY output is delivered by the existing `WsRpcClient.terminal` RPC stream
+
+The iOS implementation uses the vendored `GhosttyKit.xcframework` built from the Ghostty custom-I/O
+fork, with T3's iOS 16 compatibility patch applied. `T3TerminalView` owns a `libghostty` surface and
+uses that callback I/O model:
+
+1. initialize libghostty once for the process
+2. create one Ghostty app and surface per native view
+3. feed remote output into the surface with `ghostty_surface_feed_data`
+4. send user input back to JS with the write callback
+5. emit Ghostty's measured terminal size through `onResize`
+
+Android currently implements the same view name (`T3TerminalSurface`) and event payloads so the
+React Native screen and RPC code stay platform-neutral. The renderer backend can be replaced with a
+future Android Ghostty build without changing JS.
+
+Vendored Ghostty revision and license details are in `THIRD_PARTY_NOTICES.md`.
+
+## Rebuilding GhosttyKit
+
+The checked-in `GhosttyKit.xcframework` is built from the Ghostty custom-I/O fork (https://github.com/Yash-Singh1/ghostty/tree/custom-io).
+Set the directory to the cloned repository checked out on the `custom-io` branch to `GHOSTTY_SOURCE_DIR`.
+
+```bash
+apps/mobile/modules/t3-terminal/scripts/build-libghostty-ios16.sh
+```
+
+The script builds Ghostty with Zig 0.15.2, strips the iOS archives, and replaces only the
+`ios-arm64` and `ios-arm64-simulator` slices. Xcode's Metal toolchain must be installed; if `metal`
+fails, run `xcodebuild -downloadComponent MetalToolchain`.
diff --git a/docs/mobile/app.md b/docs/mobile/app.md
deleted file mode 100644
index f5be27c6c3f722075ce26a895d4e3ac684d4444b..0000000000000000000000000000000000000000
--- a/docs/mobile/app.md
+++ /dev/null
@@ -1,98 +0,0 @@
-# T3 Code Mobile
-
-> [!WARNING]
-> T3 Code Mobile is currently in development and is not distributed yet. If you want to try it out, you can build it from source.
-
-## Quickstart
-
-> [!NOTE]
-> Uses native modules so using Expo Go is not supported. You need to use the Expo Dev Client.
-
-This app has three variants:
-
-- `development`: Expo dev client, installable side-by-side as `T3 Code Dev`
-- `preview`: persistent internal preview build, installable side-by-side as `T3 Code Preview`
-- `production`: store/release build as `T3 Code`
-
-Run commands from `apps/mobile`.
-
-T3 Cloud is optional and disabled in a fresh clone. Public configuration belongs in the
-repository-root `.env` or `.env.local`, not an `apps/mobile/.env` file. See
-[`../../.env.example`](../../.env.example).
-
-## Development
-
-Start Metro for the dev client:
-
-```bash
-vp run dev:client
-```
-
-Build and run the local iOS dev client:
-
-```bash
-vp run ios:dev
-```
-
-Build and run the local iOS preview app:
-
-```bash
-vp run ios:preview
-```
-
-Force the review diff highlighter engine:
-
-```bash
-EXPO_PUBLIC_REVIEW_HIGHLIGHTER_ENGINE=javascript vp run ios:dev
-```
-
-`javascript` is the default and recommended setting for the review diff screen. Set `EXPO_PUBLIC_REVIEW_HIGHLIGHTER_ENGINE=native` only when you explicitly want to test the native Shiki engine.
-
-Inspect the resolved Expo config for a variant:
-
-```bash
-vp run config:dev
-vp run config:preview
-```
-
-Run static checks for mobile native code:
-
-```bash
-node ../../scripts/mobile-native-static-check.ts
-```
-
-The native lint task runs SwiftLint for Swift plus ktlint and detekt for Kotlin. Missing native tools are reported as warnings and skipped locally. CI installs the default toolset from `apps/mobile/Brewfile` before running the native checks.
-
-## EAS Builds
-
-CI uses Expo fingerprinting with the `preview:dev` profile to reuse an existing compatible build when possible, or start a new internal EAS build when native runtime inputs change. Production and default local builds continue to use the `appVersion` runtime policy.
-
-For preview or production EAS environments, set `T3CODE_CLERK_PUBLISHABLE_KEY`,
-`T3CODE_CLERK_JWT_TEMPLATE`, and `T3CODE_RELAY_URL`
-as EAS environment variables. Expo config maps the canonical values into the mobile build.
-
-Create a PR preview dev-client build manually:
-
-```bash
-vp run eas:ios:preview:dev
-```
-
-Create a cloud dev-client build:
-
-```bash
-vp run eas:ios:dev
-```
-
-Create a persistent preview build:
-
-```bash
-vp run eas:ios:preview
-```
-
-Android equivalents:
-
-```bash
-vp run eas:android:dev
-vp run eas:android:preview:dev
-vp run eas:android:preview
-```
diff --git a/docs/mobile/terminal-native-module.md b/docs/mobile/terminal-native-module.md
deleted file mode 100644
index 09d927f473360d29fbfc410c582104e08d9725e9..0000000000000000000000000000000000000000
--- a/docs/mobile/terminal-native-module.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# T3 Mobile Terminal Native Module
-
-This local Expo module owns the native terminal surface for the mobile app.
-
-The JavaScript contract is intentionally small:
-
-- input from the native surface is emitted as `{ data: string }`
-- resize from the native surface is emitted as `{ cols: number, rows: number }`
-- remote PTY output is delivered by the existing `WsRpcClient.terminal` RPC stream
-
-The iOS implementation uses the vendored `GhosttyKit.xcframework` built from the Ghostty custom-I/O
-fork, with T3's iOS 16 compatibility patch applied. `T3TerminalView` owns a `libghostty` surface and
-uses that callback I/O model:
-
-1. initialize libghostty once for the process
-2. create one Ghostty app and surface per native view
-3. feed remote output into the surface with `ghostty_surface_feed_data`
-4. send user input back to JS with the write callback
-5. emit Ghostty's measured terminal size through `onResize`
-
-Android currently implements the same view name (`T3TerminalSurface`) and event payloads so the
-React Native screen and RPC code stay platform-neutral. The renderer backend can be replaced with a
-future Android Ghostty build without changing JS.
-
-Vendored Ghostty revision and license details are in `THIRD_PARTY_NOTICES.md`.
-
-## Rebuilding GhosttyKit
-
-The checked-in `GhosttyKit.xcframework` is built from the Ghostty custom-I/O fork (https://github.com/Yash-Singh1/ghostty/tree/custom-io).
-Set the directory to the cloned repository checked out on the `custom-io` branch to `GHOSTTY_SOURCE_DIR`.
-
-```bash
-apps/mobile/modules/t3-terminal/scripts/build-libghostty-ios16.sh
-```
-
-The script builds Ghostty with Zig 0.15.2, strips the iOS archives, and replaces only the
-`ios-arm64` and `ios-arm64-simulator` slices. Xcode's Metal toolchain must be installed; if `metal`
-fails, run `xcodebuild -downloadComponent MetalToolchain`.