@@ -0,0 +1,72 @@
+---
+description: Cursor Cloud environment setup and run notes for T3 Code (Cursor-specific; not for other editors/CI)
+alwaysApply: true
+---
+
+# Cursor Cloud specific instructions
+
+These notes apply only to Cursor Cloud agents (kept out of the shared `AGENTS.md` since T3 Code is
+developed in many places). They cover the pre-provisioned VM environment and non-obvious run caveats.
+
+## Toolchain
+
+Pre-installed and wired into login shells (`~/.bashrc`/`~/.profile`): Node 24 (via nvm), the global
+`vp` (Vite+) CLI, and its bundled pnpm. `vp` is the package manager + task runner for this repo
+(`vp i`, `vp check`, `vp run typecheck`, `vp test`, `vp run --filter <pkg> <script>`).
+
+- Node gotcha: the base image also ships an older Node on `/exec-daemon` that wins on `PATH` in
+  non-login shells. Run commands in a login shell (`bash -lc '...'`) or prepend
+  `$HOME/.nvm/versions/node/v24.13.1/bin` so Node 24 (`engines.node: ^24.13.1`) is used.
+- `vp check` also runs the formatter (not just lint); markdown edits must be formatter-clean. Run
+  `vp check --fix` before committing.
+
+## Running the web app
+
+- `npm run dev` (from repo root) starts contracts (watch), web (Vite, port 5733), and the server
+  (`node --watch`, port 13773) together, auto-wiring `VITE_HTTP_URL`/`VITE_WS_URL`. Use
+  `npm run dev:server` / `npm run dev:web` for one side. If base ports are taken it auto-offsets to
+  the next free pair, so read the actual ports from stdout. Avoid production `build`/`start` in dev.
+- Auth/pairing: the server is unauthenticated by default and prints a pairing URL to stdout on startup
+  (e.g. `http://localhost:5733/pair#token=XXXX`). Open that URL in the browser to pair before the web
+  UI can talk to the server. Server state (SQLite, auth, projects) lives under `~/.t3`
+  (`T3CODE_HOME`); multiple `npm run dev` instances bind different ports but share that same DB.
+- Agent providers are external CLIs (`codex`, `claude`, `cursor-agent`, `opencode`) probed on `PATH`.
+  Without one installed the UI loads but no agent can run. Claude Code
+  (`npm i -g @anthropic-ai/claude-code`) works headlessly using `ANTHROPIC_API_KEY` from the
+  environment (the server forwards `process.env` to the child; no interactive `claude auth login`
+  needed). Provider probing runs at startup and refreshes roughly every 5 minutes — restart the dev
+  server to pick up a newly installed provider CLI immediately.
+
+## Android native builds (apps/mobile)
+
+The Android toolchain is pre-installed and wired into login shells: OpenJDK 17
+(`JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64`; the base image's default `java` is 21, so builds must
+use `JAVA_HOME`), and the Android SDK at `$HOME/Android/Sdk` (`ANDROID_HOME`/`ANDROID_SDK_ROOT`) with
+platform-tools, `platforms;android-36`, `build-tools;36.0.0`, `ndk;27.1.12297006`, and `cmake;3.22.1`.
+Gradle auto-downloads any additional pinned SDK packages on demand.
+
+- Generate the native project first: from `apps/mobile`,
+  `EXPO_NO_GIT_STATUS=1 APP_VARIANT=development npx expo prebuild --clean --platform android`
+  (the `android/` folder is generated, not committed). RN 0.85 defaults: compileSdk/targetSdk 36,
+  minSdk 24, NDK `27.1.12297006` (see `react-native/gradle/libs.versions.toml`).
+- Build with Gradle from `apps/mobile/android`, e.g. `./gradlew :app:assembleDebug`. First build is
+  slow (Kotlin + C++/NDK codegen). Limit ABIs to speed things up, e.g.
+  `-PreactNativeArchitectures=arm64-v8a`. Verified working end-to-end on a native module:
+  `./gradlew :react-native-worklets:assembleDebug` compiles Kotlin + C++ and emits an AAR + `.so`s.
+- No emulator: this VM has no `/dev/kvm` (nested virtualization), so a hardware-accelerated Android
+  emulator will not run. Use a physical device (`adb`) or EAS cloud builds (`vp run eas:android:*`) to
+  actually run the app. The full IDE GUI is unnecessary here — the SDK/NDK/Gradle toolchain that
+  Android Studio bundles is what is installed.
+- Known blocker for the full-app `:app:assembleDebug` (pre-existing, app-level — not the environment):
+  `:react-native-screens:compileDebugKotlin` fails because `patches/[email protected]`
+  adds new codegen props (`subtitle`, `largeSubtitle`, `navigationItemStyle`,
+  `headerCenterBarButtonItems`, `headerToolbarItems`) to the JS spec + iOS native code but includes no
+  Android Kotlin setters, so the generated `ScreenStackHeaderConfigManagerInterface` is unimplemented.
+  The mobile README documents only iOS for local builds and routes Android through EAS. Fixing local
+  Android app builds requires an app/patch change (add the Android Kotlin setters), which is out of
+  scope for environment setup.
+
+## Known flaky tests (unrelated to setup)
+
+- `apps/server/src/git/GitManager.test.ts` (cross-repo PR metadata, can time out at 12s).
+- `apps/server/src/provider/Layers/ProviderRegistry.test.ts` (codex binaryPath re-probe ordering).
@@ -8,6 +8,13 @@
 # T3CODE_CLERK_JWT_TEMPLATE=t3-relay
 # T3CODE_CLERK_CLI_OAUTH_CLIENT_ID=oauthapp_...
 
+# Optional: signed macOS passkey builds. The RP domain defaults to the Frontend API
+# hostname encoded in T3CODE_CLERK_PUBLISHABLE_KEY. Set the override only when Clerk
+# returns a different RP ID or when multiple domains must be entitled.
+# T3CODE_APPLE_TEAM_ID=ABC1234567
+# T3CODE_MACOS_PROVISIONING_PROFILE=/absolute/path/to/t3code.provisionprofile
+# T3CODE_CLERK_PASSKEY_RP_DOMAINS=example.clerk.accounts.dev,clerk.example.com
+
 # Get this from your relay deployment. `infra/relay` deploys update it automatically.
 # T3CODE_RELAY_URL=https://relay.example.com
 
 
@@ -38,6 +38,7 @@ jobs:
         run: |
           test -f apps/desktop/dist-electron/preload.cjs
           grep -nE "desktopBridge|getLocalEnvironmentBootstrap|PICK_FOLDER_CHANNEL|wsUrl" apps/desktop/dist-electron/preload.cjs
+          grep -n "__clerk_internal_electron_passkeys" apps/desktop/dist-electron/preload.cjs
 
   test:
     name: Test
@@ -60,52 +61,6 @@ jobs:
       - name: Test
         run: vp run test
 
-  test_browser:
-    name: Test Browser
-    runs-on: blacksmith-8vcpu-ubuntu-2404
-    timeout-minutes: 10
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-
-      - name: Setup Vite+
-        uses: voidzero-dev/setup-vp@v1
-        with:
-          node-version-file: package.json
-          cache: true
-          run-install: true
-
-      - name: Cache Playwright browsers
-        uses: actions/cache@v5
-        with:
-          path: ~/.cache/ms-playwright
-          key: ${{ runner.os }}-playwright-${{ hashFiles('pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-playwright-
-
-      - name: Install browser test runtime
-        run: vp run --filter @t3tools/web test:browser:install
-
-      - name: Browser test / Chat view
-        working-directory: apps/web
-        run: vp test run --mode browser --browser=chromium src/components/ChatView.browser.tsx
-
-      - name: Browser test / Chat markdown
-        working-directory: apps/web
-        run: vp test run --mode browser --browser=chromium src/components/ChatMarkdown.browser.tsx
-
-      - name: Browser test / Components
-        working-directory: apps/web
-        run: |
-          vp test run --mode browser --browser=chromium \
-            src/components/GitActionsControl.browser.tsx \
-            src/components/KeybindingsToast.browser.tsx \
-            src/components/ThreadTerminalDrawer.browser.tsx \
-            src/components/chat/MessagesTimeline.browser.tsx \
-            src/components/chat/ProviderModelPicker.browser.tsx \
-            src/components/chat/CompactComposerControlsMenu.browser.tsx \
-            src/components/settings/SettingsPanels.browser.tsx
-
   mobile_native_static_analysis:
     name: Mobile Native Static Analysis
     runs-on: blacksmith-12vcpu-macos-26
 
@@ -2,10 +2,12 @@ name: Mobile EAS Preview
 
 on:
   pull_request:
+    types: [opened, reopened, synchronize, labeled, unlabeled]
 
 jobs:
   preview:
     name: EAS Preview
+    if: contains(github.event.pull_request.labels.*.name, '🚀 Mobile Continuous Deployment')
     runs-on: blacksmith-8vcpu-ubuntu-2404
     permissions:
       contents: read
@@ -55,7 +57,10 @@ jobs:
         with:
           eas-version: latest
           token: ${{ secrets.EXPO_TOKEN }}
-          packager: pnpm
+          # npm, not pnpm: this only installs eas-cli into the action's own
+          # tool dir, and pnpm 11 hard-fails that install on dtrace-provider's
+          # ignored build script (no allowBuilds config outside the repo).
+          packager: npm
 
       - name: Pull preview environment variables
         if: steps.expo-token.outputs.present == 'true'
 
@@ -0,0 +1,113 @@
+name: Mobile EAS Production
+
+# Production builds and OTA updates run from CI (Linux) — never from a laptop.
+# Under the fingerprint runtime-version policy the fingerprint must be computed
+# in the same OS/pnpm as the EAS build; a macOS `eas build` computes a different
+# fingerprint (platform-specific deps + pnpm version) and errors. On this Linux
+# runner, with corepack pinning pnpm 10.24 in eas.json, local == build.
+on:
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: "build (+ auto-submit to TestFlight) or update (OTA)"
+        required: true
+        type: choice
+        default: build
+        options:
+          - build
+          - update
+      platform:
+        description: "Target platform"
+        required: true
+        type: choice
+        default: ios
+        options:
+          - ios
+          - android
+          - all
+      message:
+        description: "OTA update message (mode=update only)"
+        required: false
+        type: string
+
+jobs:
+  production:
+    name: EAS Production ${{ inputs.mode }}
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    permissions:
+      contents: read
+    env:
+      APP_VARIANT: production
+      NODE_OPTIONS: --max-old-space-size=8192
+    steps:
+      - id: expo-token
+        name: Check for EXPO_TOKEN
+        env:
+          EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
+        run: |
+          if [ -n "$EXPO_TOKEN" ]; then
+            echo "present=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "present=false" >> "$GITHUB_OUTPUT"
+            echo "EXPO_TOKEN is not available; skipping EAS production job."
+          fi
+
+      - name: Checkout
+        if: steps.expo-token.outputs.present == 'true'
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Vite+
+        if: steps.expo-token.outputs.present == 'true'
+        uses: voidzero-dev/setup-vp@v1
+        with:
+          node-version-file: package.json
+          cache: true
+          run-install: true
+
+      - name: Expose pnpm
+        if: steps.expo-token.outputs.present == 'true'
+        run: |
+          pnpm_version="$(node --print "require('./package.json').packageManager.split('@').pop()")"
+          vp_pnpm_bin="$HOME/.vite-plus/package_manager/pnpm/$pnpm_version/pnpm/bin"
+          echo "$vp_pnpm_bin" >> "$GITHUB_PATH"
+          "$vp_pnpm_bin/pnpm" --version
+
+      - name: Setup EAS
+        if: steps.expo-token.outputs.present == 'true'
+        uses: expo/expo-github-action@v8
+        with:
+          eas-version: latest
+          token: ${{ secrets.EXPO_TOKEN }}
+          # npm, not pnpm: this only installs eas-cli into the action's own
+          # tool dir, and pnpm 11 hard-fails that install on dtrace-provider's
+          # ignored build script (no allowBuilds config outside the repo).
+          packager: npm
+
+      - name: Pull production environment variables
+        if: steps.expo-token.outputs.present == 'true'
+        working-directory: apps/mobile
+        env:
+          EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
+        run: eas env:pull production --non-interactive
+
+      - name: Build and submit
+        if: steps.expo-token.outputs.present == 'true' && inputs.mode == 'build'
+        working-directory: apps/mobile
+        env:
+          EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
+        run: eas build --platform ${{ inputs.platform }} --profile production --auto-submit --non-interactive --no-wait
+
+      - name: Publish OTA update
+        if: steps.expo-token.outputs.present == 'true' && inputs.mode == 'update'
+        working-directory: apps/mobile
+        env:
+          EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
+        run: |
+          eas update \
+            --channel production \
+            --environment production \
+            --platform ${{ inputs.platform }} \
+            --message "${{ inputs.message || format('Production OTA ({0})', github.sha) }}" \
+            --non-interactive