@terreno/mcp 58.0.0-beta.4 → 58.0.1

package/dist/docs/versioned/58.0.0/how-to/upgrade-banner.md

@@ -0,0 +1,174 @@
+# Upgrade Banner
+
+Two-tier system for notifying users about app updates: a soft warning (dismissible toast) and a hard block (full-screen, no dismiss). Admin-configurable thresholds per platform.
+
+## How It Works
+
+1. **Backend** exposes `GET /version-check?version=N&platform=web|mobile` (public, no auth)
+2. **Admin** configures version thresholds via the admin panel
+3. **Client** calls `useUpgradeCheck()` on mount, which compares the app's build number against the thresholds
+4. Result: `ok` (no action), `warning` (persistent toast), or `required` (blocking screen)
+
+## Setup
+
+### 1. Backend: Register the VersionCheckPlugin
+
+```typescript
+import {TerrenoApp, VersionCheckPlugin} from "@terreno/api";
+
+const app = new TerrenoApp({userModel: User})
+  .register(new VersionCheckPlugin())
+  .start();
+```
+
+This adds the public `GET /version-check` endpoint. The admin routes (`GET/PUT /admin/version-config`) are automatically available if you're using `AdminApp`.
+
+### 2. Frontend: Add build number injection
+
+Create or update `app.config.ts` in your Expo app root. Use the `resolveBuildNumber` helper from `@terreno/syncdb/buildNumber` (node-only, so import it only from `app.config.ts`):
+
+```typescript
+import {resolveBuildNumber} from "@terreno/syncdb/buildNumber";
+import type {ConfigContext, ExpoConfig} from "expo/config";
+
+export default ({config}: ConfigContext): ExpoConfig => ({
+  ...config,
+  extra: {
+    ...config.extra,
+    buildNumber: resolveBuildNumber({configValue: config.extra?.buildNumber}),
+  },
+} as ExpoConfig);
+```
+
+`resolveBuildNumber` resolves the build number in this order:
+
+1. **`override`** option (set to a number for local testing)
+2. **`configValue`** option (e.g. from `app.json` `expo.extra.buildNumber` or EAS Build)
+3. **`EXPO_PUBLIC_BUILD_NUMBER`** env var (customizable via `envVar` option)
+4. **`git rev-list --count HEAD`** (default)
+5. **`undefined`** if git is unavailable (version check will be skipped)
+
+This sets `Constants.expoConfig.extra.buildNumber` when Metro loads the config. By default it tracks the git commit count.
+
+**If you change `buildNumber` and nothing updates:** restart the dev server (`bun expo start` or `expo start --clear`). `expo-constants` is filled when the bundle is built; hot reload does not always re-read `app.config.ts`.
+
+### 3. Frontend: Wire up the hook
+
+`useUpgradeCheck` calls `/version-check` through the `@terreno/syncdb/api` request client,
+so render it inside `<ApiClientProvider client={apiClient}>` (or pass `{client: apiClient}`).
+In your root layout:
+
+```typescript
+import {useUpgradeCheck} from "@terreno/syncdb/app";
+import {UpgradeRequiredScreen} from "@terreno/ui";
+
+function RootLayoutNav() {
+  const {isRequired, requiredMessage, onUpdate} = useUpgradeCheck();
+
+  if (isRequired) {
+    return (
+      <UpgradeRequiredScreen
+        message={requiredMessage ?? "Please update to continue."}
+        onUpdate={onUpdate}
+      />
+    );
+  }
+
+  return <Stack>{/* normal routes */}</Stack>;
+}
+```
+
+The hook handles:
+- **ok**: Nothing happens, app runs normally
+- **warning**: Shows a persistent toast with the admin-configured message
+- **required**: Returns `isRequired: true` so you can render the blocking screen
+- **No build number**: Skips the check entirely (dev environment)
+
+### 4. Admin: Configure thresholds
+
+Open the admin panel's `/version-config` route directly. The configuration screen is not included in the main sidebar. Set:
+
+- **Web Warning Version**: Build number below which web users see a warning toast
+- **Web Required Version**: Build number below which web users are blocked
+- **Mobile Warning Version**: Same for mobile
+- **Mobile Required Version**: Same for mobile
+- **Warning Message**: Text shown in the toast
+- **Required Message**: Text shown on the blocking screen
+- **Update URL** (optional): App store or download link for mobile updates
+
+All version fields default to `0`, meaning no constraint until configured.
+
+## CI/CD: Build Number in GitHub Actions
+
+### EAS Build
+
+In your `eas.json`, use a pre-build hook or set the build number via environment:
+
+```yaml
+# .github/workflows/build.yml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for git rev-list --count
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build with EAS
+        run: eas build --platform all --non-interactive
+```
+
+Since `app.config.ts` runs `git rev-list --count HEAD` at build time, the build number is automatically set. The key requirement is `fetch-depth: 0` in the checkout step to ensure the full git history is available.
+
+### Web Deployments
+
+For static web builds (e.g. `expo export`):
+
+```yaml
+jobs:
+  deploy-web:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Export web build
+        run: npx expo export --platform web
+
+      - name: Deploy
+        run: # your deployment step
+```
+
+The `app.config.ts` runs during `expo export`, so the build number is embedded in the static output.
+
+### Verifying the Build Number
+
+After building, you can verify the build number is set correctly:
+
+```bash
+# Check the current commit count locally
+git rev-list --count HEAD
+```
+
+This number should match what `Constants.expoConfig.extra.buildNumber` returns in the running app.
+
+## Architecture
+
+```
+App mounts → useUpgradeCheck() fires
+  → GET /version-check?version=N&platform=web|mobile
+  → "ok"       → normal app
+  → "warning"  → normal app + persistent toast
+  → "required" → UpgradeRequiredScreen (blocks everything)
+```
+
+Update behavior when user taps "Update":
+- **Web**: `window.location.reload()` — picks up the latest deployment
+- **Mobile**: Opens `updateUrl` via `Linking.openURL()` (e.g. App Store link)

package/dist/docs/versioned/58.0.0/how-to/upgrade-terreno.md

@@ -0,0 +1,96 @@
+# Upgrade Terreno
+
+Bump every `@terreno/*` package together. Mixing versions is unsupported ([versioning policy](../explanation/versioning-policy.md)).
+
+`@terreno/cli` and `@terreno/mcp` require Bun `>=1.4.4`. Install that before upgrading those packages. Bun 1.4.0–1.4.3 is affected by CVE-2026-111497 (Brotli decoder out-of-bounds write); 1.4.4 patches the decoder. Apps scaffolded earlier should set `FROM oven/bun:1.4.4-slim` and rebuild. A `bun build --compile` binary embeds the builder's Bun and stays on the old decoder until that rebuild.
+
+EAS build profiles in this repository stay on Bun 1.3.10. That pin is part of the Expo fingerprint, so changing it forces a native rebuild. Those profiles remain on an affected Bun release until that rebuild is scheduled.
+
+## 1. Check current versions
+
+From the app root:
+
+```bash
+bun pm ls --all | rg '@terreno/'
+```
+
+Or call MCP `application_info` (`terreno-mcp-local`) and read each `package.json`. Record the lowest `@terreno/*` version as `fromVersion` and the target as `toVersion` (usually the latest tag on [GitHub Releases](https://github.com/TerrenoLabs/terreno/releases)).
+
+## 2. Fetch notes for the range
+
+```text
+terreno_get_upgrade_guide({ fromVersion, toVersion })
+```
+
+Or browse [`mcp-server/src/docs/upgrades/`](../../mcp-server/src/docs/upgrades/). The tool lists recorded notes and names same-major minors with no file — a gap is not “nothing changed.”
+
+## 3. Order (do not skip)
+
+| Step | Why |
+| --- | --- |
+| Clean git tree, work on a branch | Rollback is `git checkout -- .` / `git reset --hard` on that branch. |
+| Backend `@terreno/*` first | `/openapi.json` is the contract the frontend typed client is generated from. Regenerating against an old backend omits new routes; screens fail at compile. |
+| Backend compile + tests | Catch API breaks before touching Expo or UI. |
+| Expo SDK (if the Terreno major tracks a new Expo) | `@terreno/ui` pins `react-native` (for example `0.88.0-rc.1` on the 58 line in `ui/package.json` `peerDependencies`). Installing Terreno frontend packages before Expo leaves unmet peers. |
+| Frontend `@terreno/*` | UI, syncdb, admin-frontend, admin-spa. |
+| Regenerate typed client | Only after the **upgraded** backend is running. |
+| Compile, lint, tests | Whole app. |
+| Run the app | UI verification. |
+
+Use the `upgrading-expo` skill at the Expo step. Do not copy Expo’s checklist into a Terreno-only bump.
+Maintainers watching the next SDK beta use `track-upstream-expo` / [`track-upstream-expo.md`](track-upstream-expo.md) instead of mixing native bumps onto master.
+
+### Backend vs frontend packages
+
+From `publish-on-tag.yml`: **backend** `api`, `test`, `admin-backend`, `blocks`, `ai`, `api-health`, `comms`, `feature-flags`, `mcp`. **frontend** `ui`, `syncdb`, `admin-frontend`, `admin-spa`. `blocks` holds contracts that both `ai` and `ui` depend on, so it moves with the backend step.
+
+## 4. Crossing 58 removes `@terreno/rtk`
+
+If the range crosses `58.0.0`, the app must drop `@terreno/rtk` and Redux: there is no 58 release of `@terreno/rtk`. Follow [How to upgrade from @terreno/rtk to @terreno/syncdb (Terreno 58)](migrate-rtk-to-syncdb.md) as part of the upgrade. Run the 58 data migrations before deploying 58 frontends.
+
+## 5. Langfuse is removed from `@terreno/ai`
+
+If the range includes the release that removes Langfuse, move off it before or with the bump:
+
+1. Register `ObservabilityApp` with `createLocalObservabilityPlugin()` for prompts, traces, and review. See [observe-llm-calls.md](observe-llm-calls.md).
+2. Recreate the prompts you kept in Langfuse in the built-in prompt registry.
+3. Replace `addGptRoutes({langfuseSystemPromptName})` with `systemPromptName` (and optionally `systemPromptLabel`).
+4. Remove imports of the deleted exports (`LangfuseApp`, `getPrompt`, `compilePrompt`, `initTracing`, and the rest listed in the release notes) and of the `@terreno/ai/langfuseApp` and `@terreno/ai/langfuseClient` subpaths. `ControlPrimary` is now only `"local"`.
+5. Drop the `LANGFUSE_*` environment variables. Deploy a backend revision that no longer mounts the Langfuse secrets **before** deleting those secrets (for example with `terraform apply`), or the running revision fails to start.
+
+## 6. Manual steps
+
+1. Branch from a clean tree. Confirm tests pass on HEAD so later failures are from the upgrade.
+2. Print `fromVersion`, `toVersion`, notes, affected packages, and this order. **Stop until the human confirms.**
+3. Bump backend packages to `toVersion`. `bun install`. `bun run compile` and backend tests.
+4. If Expo must move, run `upgrading-expo`, then rebuild native binaries.
+5. Bump frontend packages. `bun install`.
+6. Start the upgraded backend. `cd <frontend> && bun run sdk`.
+7. `bun run compile`, `bun run lint`, and the app test suite.
+8. Log in and exercise the screens that use changed APIs.
+
+Stop at the first failed compile or test. Do not continue. Compile is a typecheck (`tsc --noEmit`); a bundler that ignores types is not enough.
+
+## 7. Verification
+
+- Every `@terreno/*` version in the lockfile is `toVersion`.
+- `terreno_get_upgrade_guide` verification sections for notes in the range all pass.
+- App boots; auth and one write path work.
+
+## 8. Rollback
+
+On the upgrade branch, with no extra uncommitted work you need:
+
+```bash
+git status --short   # only upgrade edits
+git reset --hard HEAD
+# or restore the previous lockfile commit:
+git checkout <pre-upgrade-sha> -- package.json bun.lock
+bun install
+```
+
+If you already committed, `git revert` the upgrade commit or reset the branch to the pre-upgrade SHA before it was pushed. Do not leave a half-upgraded lockfile on `master`.
+
+## 8. Automate it
+
+To have an agent open the upgrade pull request on a schedule, see [Automate Terreno upgrades](automate-terreno-upgrades.md).

package/dist/docs/versioned/58.0.0/how-to/use-syncdb-correctly.md

@@ -0,0 +1,106 @@
+# How to Use syncdb Correctly
+
+This page lists `@terreno/syncdb` behavior that a working app has to account for. Each entry says what the library does today, what breaks if you ignore it, and what to do instead. It was checked against `syncdb/src` and `api/src/sync` at 57.13.0. Several entries are library gaps rather than intended behavior. Delete an entry when its gap is fixed.
+
+Read [Local-first data](../explanation/local-first-data.md) and [How to upgrade from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) first.
+
+## Startup and snapshots
+
+### Cold start costs one round trip per round, not per stream
+
+A stream is one collection in one scope, so a user has roughly (synced collections) × (tenants they belong to) streams. Reconcile, subscribe catch-up and wipe re-bootstrap page every stream through `POST /sync/snapshot/batch`: one round trip per round, with up to 5,000 rows per response shared across the streams. Empty streams cost nothing extra. `forceResync`, and every pass against a server without the batch route, still page with one `GET /sync/snapshot` per stream, `snapshotConcurrency` streams side by side (default 6). Each stream runs one pass at a time, and a pass that purges (force resync, wipe) waits for the stream's in-flight pass to finish first.
+
+Measured with a fake HTTP channel at 150 ms latency, 13 collections and 2 workspaces (26 streams): 4.1 s to the first full reconcile when paging one stream at a time, 0.95 s at the default concurrency. In a browser with 100 collections and 10k rows, batching cut a reconnect with no changes from 101 requests to 2.
+
+| Do | Why |
+| --- | --- |
+| Sync only the collections the client reads. | Each collection adds one stream per tenant to cold start. |
+| Gate each screen on its **own** stream's bootstrap (see [No loading flag on synced reads](#no-loading-flag-on-synced-reads)), not on "sync finished". | The stream a screen needs may land after others. |
+| Don't call `forceResync()` on a hot path. | It purges and re-pages every stream. |
+| Raise `snapshotConcurrency` only if the backend can take it. | Without the batch route, each in-flight stream is one concurrent snapshot query on the server. |
+
+The startup reconcile and each collection's `sync:subscribed` catch-up both page the same streams. A catch-up queues behind a pass that started before the room join, because that pass may have missed a write. So a cold start still pages each stream twice, one pass after the other.
+
+### No loading flag on synced reads
+
+`useQuery` returns a plain array. `useListQuery` returns `{data}`. The `isPending` on `useEntity`/`useReadQuery` means an outbox write is pending, not that data is loading. An empty array before bootstrap looks the same as an empty collection, so a screen that renders its empty state from `[]` flashes "nothing here" on every cold start.
+
+The per-stream `bootstrapped` mark is the right signal, but `isStreamBootstrapped` is not exported. Read the cell directly:
+
+```typescript
+const isBootstrapped = (stream: string): boolean =>
+  syncDb.store.raw.getCell("_cursors", stream, "bootstrapped") === true;
+```
+
+Don't use the cursor (`useSyncStatus().streams`) for this. A live delta can move the cursor to the head before the snapshot below it has been paged. `useWindowQuery` (query collections only) does expose `isLoading`.
+
+A stream key is `<collection>|<scopeType>:<value>`, for example `documents|tenant:<workspaceId>`. A user with several tenants has one stream per tenant. Treat a collection as loaded only once every known stream for it is bootstrapped (`syncDb.store.getKnownStreams()`).
+
+## Writes
+
+### Mutations return an id, not an outcome
+
+`create`, `update` and `remove` from `useMutate` (and from the generated `useCreate*`/`useUpdate*`/`useDelete*` hooks) return `{mutationId, id}` synchronously. There is no promise for the server ack. The client also drops the ack's `warning`. A `warning` means a server post-hook threw after the write committed.
+
+If a screen needs to know the outcome (close a modal only once the create landed, toast a refusal), wrap the transport and HTTP channel and record ack and nack outcomes by `mutationId`. Then await that `mutationId`. Don't poll the store.
+
+### A 403 from a write halts the whole outbox
+
+The server maps 403/405 to an `unauthorized` nack and 400/404/422 to `validation`. They behave very differently:
+
+| Nack | Client behavior |
+| --- | --- |
+| `unauthorized` | The mutation is re-queued and the **whole drain stops** (auth-pause). On re-auth the same `mutationId` replays, reads the same stored nack, and pauses again. It never settles. |
+| `validation` | The mutation is marked `failed` and the drain continues. That entity's later writes stay blocked until `retryFailed({entityId})`. |
+| `conflict` | That entity's later writes stay blocked (or every write is blocked, with `haltQueueOnConflict: true`) until `resolveConflict`. |
+| `error` | Retried up to the retry budget, then handled like `validation`. |
+
+So a router hook that refuses a synced write for a business reason must throw **422**, not 403. That includes `preCreate`/`preUpdate` membership checks. Keep 403 for real auth failures.
+
+### Don't send a stale tenant field on create
+
+For a tenant-scoped collection, `enforceWriteScope` checks a client-sent scope field (for example `workspaceId`) against the user's memberships **before** `preCreate` runs. A value the user does not belong to is a 403, which halts the outbox (see above). If the field is missing or null, the check is skipped and `preCreate` can fill it in.
+
+Either omit the tenant field and let `preCreate` set it, or send it only from the currently synced row of the parent tenant, never from a persisted id that may be stale.
+
+### The create's server fields arrive on the matching delta
+
+The ack stamps the row's seq and marks it waiting for the server delta at that same seq. When that delta arrives, the client replaces the optimistic payload with the server doc, including `_id` and other server-added fields. A later local edit clears the mark, so that same delta does not overwrite the edit. Deltas older than the row's seq are skipped either way.
+
+If the delta arrives before the ack, the row is marked for repair, but repair only runs on the next `reconcile()` (reconnect, seq jump, or every 5 minutes). Until one of those happens, the row still shows the payload you passed. Include `_id` in the create payload if anything reads `row._id` before that delta.
+
+### A refused create leaves a phantom row
+
+When a create is nacked as `validation` (or runs out of `error` retries), the repair fetch finds no server row and only clears the repair mark. The optimistic row stays in the store with `stream: ""` and shows up in queries. Only `forceResync` purges such rows.
+
+On a refused create, tombstone the local row yourself and call `retryFailed({entityId})` so later writes to that id are released.
+
+### Conflicts are never resolved for you
+
+A `conflict` nack blocks every later write to that row, and any queued write whose args mention its id, until someone calls `client.resolveConflict({mutationId, strategy: "keepMine" | "useServer"})` (or `useConflicts().resolve`). Local edits keep applying optimistically, so the UI looks fine while nothing reaches the server.
+
+If the app has no conflict UI, run a watcher that resolves each conflict as it is recorded. Use `keepMine` for fields the user types, and `useServer` for everything else.
+
+## Server side
+
+### Write synced models one document at a time, by `_id`
+
+On a synced model, `updateMany`, `deleteMany`, `deleteOne`, `findOneAndDelete` and `bulkWrite` throw. Single-document writes by `_id` without upsert are allowed: `save()`, `updateOne`, `findOneAndUpdate`, `findByIdAndUpdate`, `replaceOne`. Delete by setting `deleted: true`, because a hard delete emits no delta.
+
+In tests, clean up with `Model.collection.deleteMany(...)`, which bypasses Mongoose.
+
+### Deltas don't apply `queryFilter`
+
+Snapshots and `/sync/entities` apply the router's `queryFilter`. Live deltas check only `permissions.read` per recipient (on an RBAC router: the role, `access.scope`, and `access.also.read`, the same checks REST read applies; subscriptions also apply `access.also.list`). A router that restricts visibility only through `queryFilter` leaks rows over the socket. Every synced router's `read` permission must enforce the same restriction itself.
+
+### Membership grants arrive late
+
+A user's new tenant is picked up by the socket's session revalidation sweep (`sessionRevalidationIntervalMs`, 60 s by default) or a resubscribe. The client finds the new stream on its next `reconcile()` (`reconcileIntervalMs`, 5 minutes by default, plus reconnects). Until then the new tenant's rows don't appear.
+
+When the product grants membership, push a content-free event to the user's sockets and have the client reconnect syncdb. Reconnecting resubscribes and reconciles. Grants written another way (admin, scripts) still wait for the timers.
+
+## Auth
+
+### Logging out does not wipe local data
+
+The client's own `onAuthChange` handling treats a logout as a pause and **never wipes**. A different user logging in does wipe. To clear one user's data on sign-out, set `wipeOnSignOut: true` and call `client.signOut()` explicitly when the app's user clears.

package/dist/docs/versioned/58.0.0/how-to/websocket-integration.md

@@ -0,0 +1,185 @@
+# How to Add WebSocket Integration
+
+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 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)
+
+## Backend Setup
+
+### 1. Keep a reference to `RealtimeApp`
+
+`RealtimeApp` attaches Socket.io to the server `TerrenoApp.start()` creates, authenticates each
+socket (JWT and/or Better Auth), and joins it to these rooms:
+
+| Room | Members |
+|------|---------|
+| `user:<userId>` | Every socket of that user |
+| `authenticated` | Every signed-in socket |
+| `admin` | Sockets of admin users |
+
+Keep the instance so you can emit through `getIo()`:
+
+```typescript
+import {RealtimeApp, SyncApp, TerrenoApp} from "@terreno/api";
+
+export const realtimeApp = new RealtimeApp({
+  betterAuth: {auth: betterAuthInstance, userModel: User},
+});
+
+new TerrenoApp({userModel: User})
+  .register(todoRouter)
+  .register(new SyncApp())
+  .register(realtimeApp)
+  .start();
+```
+
+`getIo()` returns `null` until the server starts, so call it when you emit, not at import time.
+
+### 2. Emit events
+
+Emit app events with names that do not start with `sync:` (the sync protocol owns that prefix):
+
+```typescript
+import {realtimeApp} from "./realtime";
+
+modelRouter("/announcements", Announcement, {
+  permissions: {create: [Permissions.IsAdmin] /* ... */},
+  postCreate: (announcement) => {
+    realtimeApp.getIo()?.to("authenticated").emit("announcementPublished", {
+      id: announcement._id,
+    });
+  },
+});
+
+// One user only:
+realtimeApp.getIo()?.to(`user:${userId}`).emit("exportReady", {url});
+```
+
+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.
+
+For feature flags, point `FeatureFlagsApp` at the same server and the client refreshes with no
+extra code:
+
+```typescript
+new FeatureFlagsApp({liveUpdates: {socketIoServer: () => realtimeApp.getIo()}});
+```
+
+## Frontend Setup
+
+### 1. Listen in components with `useSocketEvent`
+
+`useSocketEvent(event, handler, options?)` from `@terreno/syncdb/react` binds a listener on the
+`SyncDbProvider` client's socket while the component is mounted:
+
+```typescript
+import {useApiQuery, useSocketEvent} from "@terreno/syncdb/react";
+
+export const AnnouncementsBadge: React.FC = () => {
+  const {data, refetch} = useApiQuery<{data: Announcement[]}>({url: "/announcements"});
+
+  useSocketEvent("announcementPublished", () => {
+    void refetch();
+  });
+
+  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
+
+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
+createSyncDb({
+  baseUrl,
+  collections: ["todos"],
+  socketTransports: ["websocket"],
+});
+``````
+
+Cloud Run with `--session-affinity` works with the default. See [Run Terreno WebSockets on Vercel Functions](vercel-function-websockets.md).
+
+Synced collections already update live through `useQuery` / `useEntity`; use socket events for
+everything else.
+
+### 2. Listen outside React with `onSocketEvent`
+
+```typescript
+import {syncDb} from "@/store/syncdb";
+
+const unsubscribe = syncDb.onSocketEvent("exportReady", (payload) => {
+  console.info("export ready", payload);
+});
+// later
+unsubscribe();
+```
+
+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.
+
+### 3. Show connection status (optional)
+
+`useSyncStatus()` exposes the same socket's state:
+
+```typescript
+import {useSyncStatus} from "@terreno/syncdb/react";
+import {Badge} from "@terreno/ui";
+
+export const ConnectionStatus: React.FC = () => {
+  const {isOnline} = useSyncStatus();
+  return <Badge status={isOnline ? "success" : "error"} value={isOnline ? "Online" : "Offline"} />;
+};
+```
+
+## Troubleshooting
+
+### Events never arrive
+
+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.
+
+### Two socket connections in the network panel
+
+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`).
+
+### Authentication errors
+
+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`
+
+Polling requests for one session reached different server instances (no session affinity). Pass `socketTransports: ["websocket"]` to `createSyncDb`, or enable session affinity on the host.
+
+
+## Security Considerations
+
+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) — `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/)

package/dist/docs/versioned/58.0.0/implementationPlans/IP_TEMPLATE.md

@@ -0,0 +1,88 @@
+# Implementation plan template
+
+Copy to `docs/implementationPlans/<slug>.md` and replace placeholders. Pair with
+`docs/tasks/<slug>.md`. Add `**Parent IP:** [other](other.md)` only when this plan
+rides on another plan's roadmap entry instead of getting its own. A filled Parent
+IP header skips reconcile for that file. `**Roadmap:**` sets the Area / Target / Impact
+the roadmap entry is scaffolded with on merge; omit it to have them inferred.
+
+**Status:** Draft | Approved | In progress | Complete | Deferred  
+**Roadmap:** Area=`api`, Target=`Next`, Impact=`Feature`  
+**Branch:**  
+**Owner:**  
+**Created:** YYYY-MM-DD  
+
+## Goal
+
+## Non-Goals
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+
+## Architecture
+
+## Models
+
+## APIs
+
+## Notifications
+
+## UI
+
+(Admin v2: document `home.slots` — `navGlobal`, `contentTop`, `main`, `sidebar` — if applicable.)
+
+## Phases
+
+## Feature Flags & Migrations
+
+## Activity Log & User Updates
+
+## Not Included / Future Work
+
+## Files to Create / Modify
+
+## Task List
+
+Link to `docs/tasks/<slug>.md`.
+
+## E2E tests
+
+Every planned spec or flow, written by the task that delivers its behaviour. Follow
+[`docs/testing/e2e.md`](../testing/e2e.md) for paths and layers. Write
+`None — <reason>` when the plan adds none; never delete the section.
+
+| ID | Spec or flow | Layer | Proves | Written in |
+| --- | --- | --- | --- | --- |
+| E1 | `<package>/e2e/<name>.spec.ts` | browser \| native flow \| http \| process | `<acceptance criterion, observable>` | T1 |
+
+## Regression cases
+
+None — no hard-to-automate change
+
+Most plans keep the line above; never delete the section. Replace it only when the plan
+changes something a developer or QA must check by hand (push notifications and other
+hardware or OS behavior, a full cross-device flow, feel) that no existing case covers. See
+"Keep regression minimal" in the planning plugin's testing plan. Cases use the suite format
+of `docs/regression/` with provisional IDs (`<AREA>-new-<n>`); Brew assigns real IDs:
+
+Destination: `<AREA>` → `docs/regression/<area>.md`
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| `<AREA>-new-1` | `<case>` | `<starting state, then actions>` | `<what a person observes>` | `<platforms>` | manual \| E1 | `<slug>` |
+
+## User guide
+
+End-user guide pages this plan adds, updates, or retires, in the format of
+[`docs/user-guide/`](../user-guide/README.md). Write `None — <reason>` when the plan
+changes nothing a user sees; never delete the section.
+
+| ID | Page | Change | Audience | Written in |
+| --- | --- | --- | --- | --- |
+| G1 | `docs/user-guide/<area>/<feature>.md` | new \| update \| retire | user \| admin \| staff | T1 |
+
+## Acceptance Criteria
+
+- [ ]