@terreno/mcp 57.21.0 → 58.0.0-beta.1

package/src/docs/versioned/next/how-to/websocket-integration.md

@@ -1,474 +1,185 @@
 # How to Add WebSocket Integration
 
-Step-by-step guide to adding real-time Socket.io connections to your Terreno application using `@terreno/rtk`.
+Push server events to a Terreno app over the socket `@terreno/syncdb` already opens. One app
+keeps one Socket.io connection: sync deltas, feature-flag pushes, and your own events share it.
 
 ## Prerequisites
 
-- Backend with Socket.io server configured
-- Frontend using `@terreno/rtk` and `@terreno/ui`
-- Redux store set up with `generateAuthSlice`
+- Backend registers `RealtimeApp` (and `SyncApp`) from `@terreno/api`
+- Frontend creates a `SyncDb` client with `createSyncDb` and starts it after login
+- MongoDB runs as a replica set (change streams power sync and flag pushes)
 
-## Installation
+## Backend Setup
 
-Socket.io dependencies are already included in `@terreno/rtk`:
+### 1. Keep a reference to `RealtimeApp`
 
-``````bash
-bun install @terreno/rtk
-# socket.io-client is a peer dependency
-bun install socket.io-client
-``````
+`RealtimeApp` attaches Socket.io to the server `TerrenoApp.start()` creates, authenticates each
+socket (JWT and/or Better Auth), and joins it to these rooms:
 
-## Backend Setup
+| Room | Members |
+|------|---------|
+| `user:<userId>` | Every socket of that user |
+| `authenticated` | Every signed-in socket |
+| `admin` | Sockets of admin users |
 
-### 1. Add Socket.io to Express Server
+Keep the instance so you can emit through `getIo()`:
 
-``````typescript
-import {createServer} from "node:http";
-import {Server} from "socket.io";
-import {setupServer} from "@terreno/api";
-
-const app = setupServer({
-  userModel: User,
-  addRoutes: (router) => {
-    // Your routes
-  },
-});
+```typescript
+import {RealtimeApp, SyncApp, TerrenoApp} from "@terreno/api";
 
-const httpServer = createServer(app);
-const io = new Server(httpServer, {
-  cors: {
-    origin: process.env.FRONTEND_URL || "http://localhost:8081",
-    credentials: true,
-  },
-  transports: ["websocket"],
+export const realtimeApp = new RealtimeApp({
+  betterAuth: {auth: betterAuthInstance, userModel: User},
 });
 
-// Authentication middleware
-io.use(async (socket, next) => {
-  const token = socket.handshake.auth.token?.replace("Bearer ", "");
-  
-  if (!token) {
-    return next(new Error("Authentication required"));
-  }
-  
-  try {
-    // Verify JWT token
-    const decoded = verifyToken(token);
-    const user = await User.findById(decoded.sub);
-    
-    if (!user) {
-      return next(new Error("User not found"));
-    }
-    
-    socket.data.user = user;
-    next();
-  } catch (error) {
-    next(new Error("Invalid token"));
-  }
-});
+new TerrenoApp({userModel: User})
+  .register(todoRouter)
+  .register(new SyncApp())
+  .register(realtimeApp)
+  .start();
+```
 
-// Connection handling
-io.on("connection", (socket) => {
-  const user = socket.data.user;
-  console.log(`User connected: ${user.email} (${socket.id})`);
-  
-  // Join user-specific room
-  socket.join(`user:${user._id}`);
-  
-  // Handle custom events
-  socket.on("subscribe:todos", () => {
-    socket.join("todos");
-    console.log(`${user.email} subscribed to todos`);
-  });
-  
-  socket.on("disconnect", (reason) => {
-    console.log(`User disconnected: ${user.email} (${reason})`);
-  });
-});
-
-httpServer.listen(4000, () => {
-  console.log("Server listening on port 4000");
-});
+`getIo()` returns `null` until the server starts, so call it when you emit, not at import time.
 
-export {io}; // Export for emitting events from routes
-``````
+### 2. Emit events
 
-### 2. Emit Events from API Routes
+Emit app events with names that do not start with `sync:` (the sync protocol owns that prefix):
 
-``````typescript
-import {io} from "./server";
+```typescript
+import {realtimeApp} from "./realtime";
 
-// In your modelRouter postCreate hook
-modelRouter(Todo, {
-  permissions: {
-    create: [Permissions.IsAuthenticated],
-  },
-  postCreate: (todo, req) => {
-    // Emit to all clients in the todos room
-    io.to("todos").emit("todo:created", {
-      id: todo._id,
-      title: todo.title,
-      ownerId: todo.ownerId,
-    });
-    
-    // Emit to specific user
-    io.to(`user:${todo.ownerId}`).emit("notification", {
-      type: "todo_created",
-      message: `Todo "${todo.title}" created`,
+modelRouter("/announcements", Announcement, {
+  permissions: {create: [Permissions.IsAdmin] /* ... */},
+  postCreate: (announcement) => {
+    realtimeApp.getIo()?.to("authenticated").emit("announcementPublished", {
+      id: announcement._id,
     });
   },
 });
-``````
-
-## Frontend Setup
 
-### 1. Configure WebSocket URL
+// One user only:
+realtimeApp.getIo()?.to(`user:${userId}`).emit("exportReady", {url});
+```
 
-Add to your `app.json` or environment:
-
-``````json
-{
-  "expo": {
-    "extra": {
-      "WEBSOCKET_URL": "wss://api.example.com",
-      "WEBSOCKETS_DEBUG": false
-    }
-  }
-}
-``````
+Send ids or small hints, not documents the client may not be allowed to read; let the client
+refetch through the API with its own permissions.
 
-### 2. Register the token source
+For feature flags, point `FeatureFlagsApp` at the same server and the client refreshes with no
+extra code:
 
-The hook reads its handshake token from the token source the app registers once at startup
-with `setTokenSource`. A JWT app registers nothing: the default source reads the JWT in
-storage. A Better Auth app registers the adapter it builds for syncdb:
-
-``````typescript
-// store/tokenSource.ts: import once from the app entry, before the store is created
-import {setTokenSource} from "@terreno/rtk";
-import {betterAuthAdapter, bridgeBetterAuthReactClient} from "@terreno/syncdb";
-import {authClient} from "@/lib/betterAuth";
-
-setTokenSource(betterAuthAdapter(bridgeBetterAuthReactClient(authClient)));
-``````
+```typescript
+new FeatureFlagsApp({liveUpdates: {socketIoServer: () => realtimeApp.getIo()}});
+```
 
-With `webAuth: "bearer"`, also pass the adapter `getBearerToken`
-([syncdb adapter](../reference/syncdb.md#createsyncdb-configuration)).
-
-With a token source, the hook:
+## Frontend Setup
 
-- reads `getToken()` on every connect and reconnect;
-- calls `refresh()` once when the server rejects the token, then reconnects, and stops after a
-  second rejection (`onConnectError` fires). With no `refresh`, or a failed one, it stops at
-  once;
-- reconnects with the new token when `onAuthChange` fires, and disconnects when there is no
-  token.
+### 1. Listen in components with `useSocketEvent`
 
-To use a different source for one socket, pass it as `tokenSource`. Passing the legacy
-`getAuthToken` getter instead turns the token source off for that hook. See
-[Token source](../reference/legacy/rtk.md#token-source).
+`useSocketEvent(event, handler, options?)` from `@terreno/syncdb/react` binds a listener on the
+`SyncDbProvider` client's socket while the component is mounted:
 
-### 3. Set Up Connection Hook
+```typescript
+import {useApiQuery, useSocketEvent} from "@terreno/syncdb/react";
 
-Create a custom hook to manage the connection. A Better Auth app gates `shouldConnect` on
-`selectBetterAuthUserId` instead of the JWT user id:
+export const AnnouncementsBadge: React.FC = () => {
+  const {data, refetch} = useApiQuery<{data: Announcement[]}>({url: "/announcements"});
 
-``````typescript
-// hooks/useWebSocket.ts
-import {useSocketConnection, baseWebsocketsUrl} from "@terreno/rtk";
-import {selectBetterAuthUserId} from "@terreno/rtk";
-import {useSelector} from "react-redux";
-import {useCallback} from "react";
-import * as Sentry from "@sentry/react-native";
-
-export const useWebSocket = () => {
-  const userId = useSelector(selectBetterAuthUserId); // JWT apps: useSelectCurrentUserId()
-  
-  const {socket, isSocketConnected} = useSocketConnection({
-    baseUrl: baseWebsocketsUrl,
-    shouldConnect: !!userId,
-    onConnect: () => {
-      console.info("[WebSocket] Connected");
-    },
-    onDisconnect: () => {
-      console.warn("[WebSocket] Disconnected");
-    },
-    onConnectError: (error) => {
-      console.error("[WebSocket] Connection error:", error.message);
-    },
-    captureEvent: (eventName, data) => {
-      Sentry.captureMessage(eventName, {
-        level: "info",
-        extra: data,
-      });
-    },
+  useSocketEvent("announcementPublished", () => {
+    void refetch();
   });
-  
-  return {socket, isSocketConnected};
+
+  return <Badge value={String(data?.data.length ?? 0)} />;
 };
-``````
+```
+
+- The handler can change on every render; the latest one runs and the listener is not rebound.
+- Outside a `SyncDbProvider`, pass the client: `useSocketEvent(name, handler, {client: syncDb})`.
+- `{client: null}` or `{enabled: false}` listens to nothing (for example while signed out).
 
 #### Transports
 
-`useSocketConnection` starts with HTTP long-polling and upgrades to WebSocket (`transports: ["polling", "websocket"]`), so a restarting dev server does not fail the first handshake. Polling needs every request of a session to reach the same server process. Hosts without session affinity, such as Vercel Functions, need WebSocket only:
+The syncdb socket starts with HTTP long-polling and upgrades to WebSocket (`socketTransports: ["polling", "websocket"]`), so a restarting dev server does not fail the first handshake. Polling needs every request of a session to reach the same server process. Hosts without session affinity, such as Vercel Functions, need WebSocket only:
 
 ``````typescript
-useSocketConnection({
+createSyncDb({
   baseUrl,
-  shouldConnect: !!userId,
-  transports: ["websocket"],
+  collections: ["todos"],
+  socketTransports: ["websocket"],
 });
 ``````
 
-`@terreno/syncdb` takes the same list as `createSyncDb({socketTransports: ["websocket"]})`. Cloud Run with `--session-affinity` works with the default. See [Run Terreno WebSockets on Vercel Functions](vercel-function-websockets.md).
+Cloud Run with `--session-affinity` works with the default. See [Run Terreno WebSockets on Vercel Functions](vercel-function-websockets.md).
 
-`baseWebsocketsUrl` replaces `api.` with `ws.` in the API host (`https://api.example.com` becomes `ws.example.com`), for deployments that run sockets on a separate host. If sockets are served by the API host itself, as on Vercel, pass `baseUrl` instead.
+Synced collections already update live through `useQuery` / `useEntity`; use socket events for
+everything else.
 
-### 4. Subscribe to Events in Components
+### 2. Listen outside React with `onSocketEvent`
 
-``````typescript
-// screens/TodoList.tsx
-import {useWebSocket} from "@/hooks/useWebSocket";
-import {useEffect, useCallback} from "react";
-
-export const TodoListScreen = () => {
-  const {data: todos, refetch} = useGetTodosQuery();
-  const {socket} = useWebSocket();
-  
-  // Subscribe to todo events
-  useEffect(() => {
-    if (!socket) return;
-    
-    // Join the todos room
-    socket.emit("subscribe:todos");
-    
-    // Handle todo created event
-    const handleTodoCreated = (todo) => {
-      console.info("New todo created:", todo);
-      refetch(); // Refresh the list
-    };
-    
-    // Handle todo updated event
-    const handleTodoUpdated = (todo) => {
-      console.info("Todo updated:", todo);
-      refetch();
-    };
-    
-    socket.on("todo:created", handleTodoCreated);
-    socket.on("todo:updated", handleTodoUpdated);
-    
-    // Cleanup
-    return () => {
-      socket.off("todo:created", handleTodoCreated);
-      socket.off("todo:updated", handleTodoUpdated);
-    };
-  }, [socket, refetch]);
-  
-  return (
-    <Page title="Todos">
-      {todos?.data.map((todo) => (
-        <TodoItem key={todo._id} todo={todo} />
-      ))}
-    </Page>
-  );
-};
-``````
-
-### 5. Show Connection Status (Optional)
+```typescript
+import {syncDb} from "@/store/syncdb";
 
-``````typescript
-import {useWebSocket} from "@/hooks/useWebSocket";
-import {Box, Text, Badge} from "@terreno/ui";
-
-export const ConnectionStatus = () => {
-  const {isSocketConnected} = useWebSocket();
-  
-  return (
-    <Box direction="row" gap={2} alignItems="center">
-      <Badge
-        variant={isSocketConnected.isConnected ? "success" : "error"}
-        text={isSocketConnected.isConnected ? "Connected" : "Disconnected"}
-      />
-      {!isSocketConnected.isConnected && isSocketConnected.lastDisconnectedAt && (
-        <Text size="sm" color="secondaryDark">
-          Reconnecting...
-        </Text>
-      )}
-    </Box>
-  );
-};
-``````
-
-## Advanced Patterns
-
-### Optimistic Updates with Real-time Sync
-
-``````typescript
-const [updateTodo] = usePatchTodosMutation();
-
-const handleToggle = useCallback(async (todo) => {
-  // Optimistic update
-  const completed = !todo.completed;
-  
-  try {
-    await updateTodo({
-      id: todo._id,
-      body: {completed},
-    }).unwrap();
-    
-    // Server will emit event, triggering refetch for other clients
-  } catch (error) {
-    console.error("Failed to update todo:", error);
-    // Revert optimistic update
-  }
-}, [updateTodo]);
-``````
-
-### Room-based Subscriptions
-
-``````typescript
-// Backend: User joins project-specific room
-socket.on("join:project", (projectId) => {
-  socket.join(`project:${projectId}`);
+const unsubscribe = syncDb.onSocketEvent("exportReady", (payload) => {
+  console.info("export ready", payload);
 });
+// later
+unsubscribe();
+```
 
-// Emit to project room
-io.to(`project:${projectId}`).emit("project:updated", project);
-
-// Frontend: Subscribe to project updates
-useEffect(() => {
-  if (!socket || !projectId) return;
-  
-  socket.emit("join:project", projectId);
-  socket.on("project:updated", handleProjectUpdate);
-  
-  return () => {
-    socket.off("project:updated", handleProjectUpdate);
-  };
-}, [socket, projectId]);
-``````
+Listeners stay bound across `stop()` / `start()` and reconnects; they fire only while the
+socket is connected. Binding a reserved name (`sync:*`, `connect`, `disconnect`,
+`connect_error`, …) throws.
 
-### Presence System
+### 3. Show connection status (optional)
 
-``````typescript
-// Backend: Track active users
-const activeUsers = new Map();
-
-io.on("connection", (socket) => {
-  const user = socket.data.user;
-  activeUsers.set(user._id, {socketId: socket.id, lastSeen: new Date()});
-  
-  io.emit("presence:update", Array.from(activeUsers.keys()));
-  
-  socket.on("disconnect", () => {
-    activeUsers.delete(user._id);
-    io.emit("presence:update", Array.from(activeUsers.keys()));
-  });
-});
+`useSyncStatus()` exposes the same socket's state:
 
-// Frontend: Show active users
-const [activeUsers, setActiveUsers] = useState<string[]>([]);
+```typescript
+import {useSyncStatus} from "@terreno/syncdb/react";
+import {Badge} from "@terreno/ui";
 
-useEffect(() => {
-  if (!socket) return;
-  
-  socket.on("presence:update", (userIds) => {
-    setActiveUsers(userIds);
-  });
-  
-  return () => {
-    socket.off("presence:update");
-  };
-}, [socket]);
-``````
-
-## Debugging
-
-Enable debug logging in your `app.json`:
-
-``````json
-{
-  "expo": {
-    "extra": {
-      "WEBSOCKETS_DEBUG": true
-    }
-  }
-}
-``````
-
-This logs:
-- Connection attempts
-- Disconnection events with reasons
-- Token refresh attempts
-- Reconnection failures
+export const ConnectionStatus: React.FC = () => {
+  const {isOnline} = useSyncStatus();
+  return <Badge status={isOnline ? "success" : "error"} value={isOnline ? "Online" : "Offline"} />;
+};
+```
 
 ## Troubleshooting
 
-### "Authentication required" error
+### Events never arrive
 
-**Cause:** Token not provided or invalid.
+1. Confirm the client has started: `syncDb.getSyncStatus().isOnline` is `true`.
+2. Confirm the server emits on `realtimeApp.getIo()`, not a second `new Server(...)`; a second
+   server has no syncdb clients connected.
+3. Check the room. `user:<id>` uses the id the socket authenticated as.
+4. Check the event name matches exactly on both sides.
 
-**Solution:**
-1. Ensure the token source returns a valid token: `await getTokenSource()?.getToken()` (or
-   `getAuthToken()` on a JWT app with no source registered)
-2. Check backend token verification logic
-3. Enable `WEBSOCKETS_DEBUG` to see token status
+### Two socket connections in the network panel
 
-### Frequent disconnections
+Something still opens its own Socket.io client. Remove it and listen through
+`useSocketEvent` / `onSocketEvent`. The example app's Playwright suite asserts one connection
+(`example-frontend/e2e/socket-flags.spec.ts`).
 
-**Cause:** Token expiration, network issues, or server restarts.
+### Authentication errors
 
-**Solution:**
-- `useSocketConnection` automatically reconnects (5 attempts)
-- Tokens are refreshed if expiring within 60 seconds
-- Toast notifications inform users after 9+ seconds
-- On Vercel Functions, every socket closes at the Function max duration (300s by default); see [reconnects](vercel-function-websockets.md#reconnects)
+The socket sends the token from the `authProvider` passed to `createSyncDb` on every connection
+attempt. An auth rejection pauses sync (`useSyncStatus().paused === "auth"`) until the session
+refreshes. On Vercel Functions, every socket closes at the Function max duration (300s by default); clients reconnect automatically. See [syncdb reference](../reference/syncdb.md) and [Run Terreno WebSockets on Vercel Functions](vercel-function-websockets.md#reconnects).
 
 ### "Session ID unknown" or a 400 on `transport=polling`
 
-**Cause:** Polling requests for one session reached different server instances (no session affinity).
-
-**Solution:** Pass `transports: ["websocket"]` to `useSocketConnection` and `socketTransports: ["websocket"]` to `createSyncDb`, or enable session affinity on the host.
-
-### Events not received
-
-**Cause:** Not subscribed to the correct room, or event name mismatch.
-
-**Solution:**
-1. Verify room subscription: `socket.emit("subscribe:todos")`
-2. Check event names match between backend and frontend
-3. Use `socket.onAny((event, ...args) => console.log(event, args))` to debug
-
-### Token refresh loops
-
-**Cause:** Backend rejecting refresh token.
-
-**Solution:**
-1. Check `REFRESH_TOKEN_SECRET` matches between backend and frontend config
-2. Verify refresh token hasn't expired
-3. Check Sentry/logs for token verification errors
-
-## Environment Variables
+Polling requests for one session reached different server instances (no session affinity). Pass `socketTransports: ["websocket"]` to `createSyncDb`, or enable session affinity on the host.
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `WEBSOCKET_URL` | Yes | WebSocket server URL (e.g., `wss://api.example.com`) |
-| `WEBSOCKETS_DEBUG` | No | Enable debug logging (default: false) |
-| `TOKEN_SECRET` | Yes | JWT secret for token verification (backend) |
-| `REFRESH_TOKEN_SECRET` | Yes | Refresh token secret (backend) |
 
 ## Security Considerations
 
-1. **Use WSS (TLS):** Always use `wss://` in production
-2. **Validate tokens:** Always verify JWT tokens in Socket.io middleware
-3. **Room authorization:** Check user permissions before joining rooms
-4. **Rate limiting:** Implement rate limits on event emissions
-5. **Input validation:** Validate all event data on the server
+1. Use `https://` / `wss://` in production.
+2. Emit per-user data only to `user:<id>` rooms.
+3. Keep payloads to ids and hints; clients fetch details through permission-checked APIs.
+4. Validate any data your handlers trust.
 
 ## Related Documentation
 
-- [@terreno/syncdb Reference](../reference/syncdb.md) — Local-first data layer (replaces RTK for synced collections)
-- [@terreno/rtk Reference (legacy)](../reference/legacy/rtk.md) — RTK Query utilities during the support window
-- [Authentication Architecture](../explanation/authentication.md) — JWT system deep-dive
+- [@terreno/syncdb reference](../reference/syncdb.md) — `onSocketEvent`, `useSocketEvent`
+- [Feature flags reference](../reference/feature-flags.md) — live flag updates
+- [Authentication architecture](../explanation/authentication.md)
 - [Run Terreno WebSockets on Vercel Functions](vercel-function-websockets.md) — Vercel's WebSocket beta: transports, reconnects, cross-instance state
-- [Socket.io Documentation](https://socket.io/docs/v4/) — Official Socket.io docs
+- [Socket.io documentation](https://socket.io/docs/v4/)

package/src/docs/versioned/next/implementationPlans/b2b-platform-program.md

@@ -103,7 +103,7 @@ All decisions resolved by the maintainer on 2026-08-09:
 | [orgs-and-teams](orgs-and-teams.md) | Superseded by [org-management-ui](org-management-ui.md) | — |
 | [org-management-ui](org-management-ui.md) | Draft — awaiting approval | [tasks](../tasks/org-management-ui.md) |
 | [billing-stripe](billing-stripe.md) | Draft | [tasks](../tasks/billing-stripe.md) |
-| [native-module-baseline](native-module-baseline.md) | Draft | [tasks](../tasks/native-module-baseline.md) |
+| [native-module-baseline](native-module-baseline.md) | In progress | [tasks](../tasks/native-module-baseline.md) |
 | [rbac-permissions](rbac-permissions.md) | Complete (PR #932) | — |
 | [notification-center](notification-center.md) | Approved | [tasks](../tasks/notification-center.md) |
 | [framework-audit-log](framework-audit-log.md) | Approved | [tasks](../tasks/framework-audit-log.md) |

package/src/docs/versioned/next/implementationPlans/migrate-admin-to-syncdb.md

@@ -7,6 +7,11 @@
 **Created:** 2026-09-01
 **Grow run:** https://cursor.com/agents/bc-47350376-6566-4c5a-aee2-e6a28698de61
 
+> **Terreno 58 follow-up (done):** the dual-run window closed. `useAdminApi`, admin
+> `injectEndpoints`, and the admin `api` prop were removed (umbrella issue #1252).
+> ObjectId and API-only admin CRUD now use the `AdminProvider` fetch client through
+> `useAdminModelApi`. The plan below is kept as written for history.
+
 ## Goal
 
 Move **built-in admin model list/read/create/update/delete** for collections that already use **String `_id`** onto **windowed local-first syncdb**, with **REST remaining the membership source** (search, sort, pagination, RBAC). Remaining admin RPC (config, scripts, roles, comms, AI, consent, documents, version-config, background-tasks) leaves RTK `injectEndpoints` for a **tiny native `fetch` wrapper** with **host-injected auth**.

package/src/docs/versioned/next/implementationPlans/native-module-baseline.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Native module baseline for the next major release
 
-**Status:** Draft
+**Status:** In progress (Phase 1 and diagnostics story landed on `release-58.0.0`; EAS builds pending)
 **Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1026
 **Priority:** High
 **Effort:** Small batch (code) — coordination cost is the release itself
@@ -28,12 +28,36 @@ JS/OTA update against the same binary.
 
 | Question | Decision |
 |----------|----------|
-| Manifest (D7, resolved) | `@stripe/stripe-react-native`, `react-native-purchases` + `react-native-purchases-ui`, `expo-device`, `expo-crypto`, `expo-local-authentication`, `expo-system-ui`, `react-native-otp-verify` |
+| Manifest (D7, resolved) | `@stripe/stripe-react-native`, `react-native-purchases` + `react-native-purchases-ui`, `expo-device`, `expo-crypto`, `expo-local-authentication`, `expo-system-ui`, `react-native-otp-verify` (dropped at implementation; see below) |
 | Where dependencies live | Root catalog entries; linked in `example-frontend` and `demo` app manifests; `@terreno/ui`/feature packages reference them only when their feature IPs land (this IP is binary readiness, not usage) |
-| Stripe Android constraints | Pin Kotlin 2.x / `compileSdkVersion` 36 via `expo-build-properties` per stripe-react-native requirements |
+| Stripe Android constraints | Pin Kotlin 2.x / `compileSdkVersion` via `expo-build-properties` per stripe-react-native requirements. Implemented as Kotlin `2.2.21` (Stripe's default, in Expo's KSP table) and `compileSdkVersion` `37`: React Native 0.88 already compiles against 37, so pinning 36 would downgrade it. Stripe needs at least 36 |
 | Expo Go story | Document which flows degrade in Expo Go (purchases → RevenueCat Preview API mode; stripe/local-auth → dev build required); CI smoke keeps web unaffected |
 | Release process | Follows the `release` skill + the upgrade-notes-for-breaking-releases CI gate (PR #987): major tag, upgrade note required |
 
+## Implementation notes (Terreno 58)
+
+Versions, chosen against Expo SDK 58 (`bundledNativeModules.json` from `expo@58.0.14`):
+
+| Package | Pin | Source |
+| --- | --- | --- |
+| `@stripe/stripe-react-native` | `0.81.0` | Expo 58 bundled version |
+| `react-native-purchases`, `react-native-purchases-ui` | `10.12.2` | Newest release past the 7-day publish cooldown; peers `react-native >= 0.73` |
+| `expo-device` | `~58.0.5` | Expo 58 bundled version |
+| `expo-crypto` | `~58.0.2` | Existing catalog pin, unchanged |
+| `expo-local-authentication` | `~58.0.2` | Expo 58 bundled version |
+| `expo-system-ui` | `~58.0.6` | Expo 58 bundled version |
+| `expo-build-properties` | `~58.0.11` | Expo 58 bundled version |
+
+**Dropped: `react-native-otp-verify`.** `expo-doctor` reports it as unsupported on the New
+Architecture (React Native Directory metadata), and React Native 0.88 runs only the New
+Architecture. The latest release (1.2.0) is a legacy bridge module with no iOS sources. One-time
+codes use `TextInput` `textContentType="oneTimeCode"` (iOS) and `autoComplete="sms-otp"`
+(Android), which need no native module. Android SMS Retriever auto-read needs a New
+Architecture module in a later binary if a feature requires it.
+
+`expo-local-authentication` also gets its config plugin (`faceIDPermission`) so Face ID works
+on iOS without another binary.
+
 ## Architecture
 
 Changes are dependency + config only:
@@ -94,8 +118,8 @@ See [docs/tasks/native-module-baseline.md](../tasks/native-module-baseline.md).
 
 ## Acceptance Criteria
 
-- [ ] `bun install`, full compile, and `example-frontend` web export succeed with the
-      seven packages added.
+- [x] `bun install`, full compile, and `example-frontend` web export succeed with the
+      seven packages added (`react-native-otp-verify` dropped; see Implementation notes).
 - [ ] iOS and Android EAS dev builds compile; the diagnostics story shows all seven
       modules resolved on device.
 - [ ] Android build carries the Kotlin 2.x / compileSdk 36 pins without breaking