@terreno/agent-plugin 0.0.0-stage → 58.0.0-beta.2

package/skills/building-terreno-apps/references/screen-patterns.md

@@ -0,0 +1,174 @@
+# Screen Patterns — Terreno Apps
+
+## List screen (synced collection)
+
+Synced collections read from the local store: no loading spinner after bootstrap, and
+writes apply immediately.
+
+```tsx
+import {generateMutationId} from "@terreno/syncdb";
+import {useMutate, useQuery} from "@terreno/syncdb/react";
+import {Box, Button, Card, Heading, Page, Text} from "@terreno/ui";
+import {useCallback} from "react";
+
+const TodoListScreen: React.FC = () => {
+  const todos = useQuery<Todo>("todos", {sort: "-created"});
+  const {create} = useMutate("todos");
+
+  const handleCreate = useCallback((): void => {
+    create({data: {_id: generateMutationId(), title: "New todo", completed: false}});
+  }, [create]);
+
+  return (
+    <Page title="Todos" scroll>
+      <Box gap={3} padding={4}>
+        <Box direction="row" justifyContent="between" alignItems="center">
+          <Heading size="lg">Todos</Heading>
+          <Button text="Add" onClick={handleCreate} iconName="plus" />
+        </Box>
+        {todos.length === 0 ? (
+          <Text color="secondaryLight">No todos yet</Text>
+        ) : (
+          todos.map((todo) => (
+            <Card key={todo._id} padding={3}>
+              <Text>{todo.title}</Text>
+            </Card>
+          ))
+        )}
+      </Box>
+    </Page>
+  );
+};
+```
+
+Gate the empty state on the stream's bootstrap (see `docs/how-to/use-syncdb-correctly.md`).
+
+## Profile screen
+
+Use `TapToEdit` for per-field profile edits. Save each field with the generated `usePatchAuthMeMutation` — do not collect every field behind one Save button.
+
+```tsx
+import {Box, Card, Page, TapToEdit} from "@terreno/ui";
+import {useCallback, useEffect, useState} from "react";
+import {useGetAuthMeQuery, usePatchAuthMeMutation} from "@/store/apiSdk";
+
+const ProfileScreen: React.FC = () => {
+  const {data: profile} = useGetAuthMeQuery();
+  const [updateProfile] = usePatchAuthMeMutation();
+  const [name, setName] = useState<string>("");
+
+  // Seed only this field from the server so saving another TapToEdit does not wipe the draft.
+  useEffect(() => {
+    if (!profile) {
+      return;
+    }
+    setName(profile.name || "");
+  }, [profile?.name]);
+
+  const handleSaveName = useCallback(
+    async (value: string): Promise<void> => {
+      await updateProfile({name: value}).unwrap();
+    },
+    [updateProfile]
+  );
+
+  return (
+    <Page title="Profile" scroll>
+      <Box gap={4} padding={4}>
+        <Card>
+          <TapToEdit
+            onSave={handleSaveName}
+            setValue={setName}
+            title="Name"
+            type="text"
+            value={name}
+          />
+        </Card>
+      </Box>
+    </Page>
+  );
+};
+```
+
+## Form screen
+
+```tsx
+import {generateMutationId} from "@terreno/syncdb";
+import {useMutate} from "@terreno/syncdb/react";
+import {Box, Button, Page, TextField} from "@terreno/ui";
+import {useCallback, useState} from "react";
+import {useRouter} from "expo-router";
+
+const CreateTodoScreen: React.FC = () => {
+  const router = useRouter();
+  const [title, setTitle] = useState<string>("");
+  const [titleError, setTitleError] = useState<string | undefined>();
+  const {create} = useMutate("todos");
+
+  const handleSubmit = useCallback((): void => {
+    if (!title.trim()) {
+      setTitleError("Title is required");
+      return;
+    }
+    create({data: {_id: generateMutationId(), title: title.trim(), completed: false}});
+    router.back();
+  }, [create, router, title]);
+
+  return (
+    <Page title="New Todo" scroll>
+      <Box gap={4} padding={4}>
+        <TextField
+          title="Title"
+          value={title}
+          onChange={setTitle}
+          errorText={titleError}
+        />
+        <Button text="Save" onClick={handleSubmit} fullWidth />
+      </Box>
+    </Page>
+  );
+};
+```
+
+Server rejections arrive later in `useConflicts()` / `useSyncStatus().failedCount`, not
+from `create`.
+
+## Detail screen with params
+
+```tsx
+import {useEntity} from "@terreno/syncdb/react";
+import {Page, Text} from "@terreno/ui";
+import {useLocalSearchParams} from "expo-router";
+
+const TodoDetailScreen: React.FC = () => {
+  const {id} = useLocalSearchParams<{id: string}>();
+  const {data, deleted} = useEntity<Todo>("todos", id ?? "");
+
+  if (!data || deleted) {
+    return <Page title="Todo"><Text color="error">Not found</Text></Page>;
+  }
+
+  return (
+    <Page title={data.title} scroll>
+      <Text>{data.title}</Text>
+    </Page>
+  );
+};
+```
+
+## Admin table screen
+
+Prefer `@terreno/admin-frontend` over hand-rolled tables. Use `AdminScreenRouter` so
+custom screens and models share `[model]/index`. Full nav and custom-screen rules:
+skill `building-admin-interfaces`.
+
+```tsx
+import {AdminScreenRouter} from "@terreno/admin-frontend";
+import {useLocalSearchParams} from "expo-router";
+
+// Rendered inside the AdminProvider in app/admin/_layout.tsx.
+const AdminModelScreen: React.FC = () => {
+  const {model} = useLocalSearchParams<{model: string}>();
+  return <AdminScreenRouter apiBase="/admin" name={model ?? ""} routeBase="/admin" />;
+};
+```

package/skills/debug-syncdb-with-mcp/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: debug-syncdb-with-mcp
+description: >-
+  Invoke when debugging SyncDB local state, stale data, outbox stalls,
+  conflicts, cursor/stream drift, reconciliation, or offline behavior in a
+  running Terreno app. Uses terreno-mcp-local to inspect, snapshot, compare,
+  mutate, flush, merge, and repair SyncDB state.
+---
+# Debug SyncDB with MCP
+
+Use the fixed SyncDB MCP tools instead of arbitrary `evaluate` snippets.
+
+## 1. Establish the live client
+
+1. Confirm the app creates its SyncDB client with `debug: true` in development.
+2. Start the app and authenticate the affected user.
+3. Call `get_syncdb_state` without filters.
+
+Continue only when the response names a registered client and includes `status`,
+`collections`, `outbox`, `conflicts`, `cursors`, `knownStreams`, `needsRepair`,
+and `debug`.
+
+## 2. Capture the baseline
+
+Call `syncdb_snapshot` with `action: "capture"`. Keep the returned snapshot id.
+Use `collection`, `entityId`, or `limit` only when the full state is too large.
+
+The capture retains mergeable TinyBase content inside the local MCP process.
+Returned JSON redacts sensitive fields and does not expose that merge payload.
+
+## 3. Reproduce and inspect
+
+Reproduce the issue once, then call:
+
+- `get_syncdb_state` for the current state and debugger event stream
+- `syncdb_snapshot` with `action: "capture"` for the post-reproduction state
+- `syncdb_snapshot` with `action: "compare"` and both snapshot ids
+
+Use the diff plus debug events to identify whether divergence begins at the
+local mutation, outbox send, ack/nack, delta, cursor, or reconcile phase.
+
+## 4. Change state only when required
+
+Restart `terreno-mcp-local` with `TERRENO_MCP_EVAL=1`, then use
+`syncdb_action`:
+
+| Action | Purpose |
+| --- | --- |
+| `mutate` | Normal optimistic create/update/delete through the outbox |
+| `setLocalEntity` / `deleteLocalEntity` | Direct local-only fault injection or repair |
+| `flush` | Drain the durable outbox now |
+| `reconcile` / `forceResync` | Catch up or purge and rebuild from server snapshots |
+| `resolveConflict` / `retryFailed` | Unblock conflicted or terminally failed entities |
+| `goOffline` / `goOnline` | Exercise queueing and reconnect behavior |
+| `mergeSnapshot` | CRDT-merge a prior capture into the current TinyBase store; later HLCs win, including deletes |
+| `clearDebug` | Reset retained debugger events and counters |
+
+Prefer `mutate` over direct local edits. Capture another snapshot before
+`setLocalEntity`, `deleteLocalEntity`, or `mergeSnapshot`; those actions bypass
+normal server validation and outbox semantics.
+
+## 5. Prove the diagnosis
+
+Capture and compare a final snapshot, then verify:
+
+- the expected entity payload, tombstone, seq, and stream
+- no unintended pending mutation remains
+- queued/conflict/failed counts match the expected outcome
+- cursors and known streams are coherent
+- debugger events show the expected send/ack/delta/reconcile sequence
+
+The workflow is complete when the state diff and event sequence explain the
+failure or prove the repair. See
+[`docs/how-to/debug-with-mcp.md`](../../../../docs/how-to/debug-with-mcp.md) for
+setup and examples.

package/skills/deploy-gcp/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: deploy-gcp
+description: Deploy a Terreno app to GCP — Cloud Run backend and GCS+CDN static web. Trigger phrases include "deploy to GCP", "deploy to Cloud Run", and "ship the backend".
+targets: ['*']
+---
+
+# Deploy to GCP
+
+Deploy `example-backend` (or a bootstrapped `backend/`) to Cloud Run and the web export to GCS + CDN.
+
+**Never deploy to a project the user did not name in the request.** Never create or modify secrets without echoing which secret names will change.
+
+## When to use
+
+- User asks to deploy a Terreno backend or full stack to Google Cloud
+- User names a specific GCP `$PROJECT_ID` and wants Cloud Run + static web hosting
+
+## When not to use
+
+- User has not named a target GCP project
+- User wants Vercel, Netlify-only, or non-GCP hosting
+- User wants Terraform apply without explicit confirmation
+
+## Preflight checks
+
+1. **Project layout** — detect monorepo (`example-backend/`, `example-frontend/`) vs bootstrapped app (`backend/`, `frontend/`).
+2. **gcloud** — `gcloud config get-value project` must match the user-named project (or set it with user confirmation).
+3. **APIs** — verify `run.googleapis.com`, `artifactregistry.googleapis.com`, `secretmanager.googleapis.com` are enabled.
+4. **MongoDB** — `MONGO_URI` must point at a replica set (Atlas or `replSet=`). Standalone `mongod` breaks change streams.
+5. **Web build** — confirm `EXPO_PUBLIC_API_URL` will be set to the Cloud Run URL **before** `bun run export`.
+
+## Plan and confirm (required)
+
+Before any mutating `gcloud`, `docker push`, or `gsutil` command, print:
+
+- Target `$PROJECT_ID`, `$REGION`, `$SERVICE_NAME`
+- Web bucket `$WEB_BUCKET` and CDN site name
+- Every secret to create or update (`MONGO_URI`, `TOKEN_SECRET`, etc.)
+- Every resource to create or update (Artifact Registry repo, Cloud Run service, GCS bucket, CDN resources)
+
+**Stop and require explicit user confirmation** before proceeding.
+
+## Backend deploy
+
+Follow [docs/how-to/deploy-backend-to-cloud-run.md](../../../../docs/how-to/deploy-backend-to-cloud-run.md):
+
+1. Create Artifact Registry repository
+2. `docker build -f example-backend/Dockerfile .` from repo root
+3. Push image to `$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME`
+4. Create Secret Manager secrets (values out of band)
+5. Create runtime service account with `secretmanager.secretAccessor`
+6. `gcloud run deploy` with `--session-affinity`, `--timeout=3600`, `--min-instances=1`, `--set-secrets`, `--port=3000`
+
+## Frontend deploy
+
+Follow [docs/how-to/deploy-web-to-gcs-cdn.md](../../../../docs/how-to/deploy-web-to-gcs-cdn.md):
+
+1. `EXPO_PUBLIC_API_URL=$SERVICE_URL bun run export` in the frontend package
+2. Upload `dist/` to `$WEB_BUCKET` with correct cache headers
+3. Run `./scripts/setup-gcs-hosting.sh --project ... --site-name ... --bucket ... --domain ...` if CDN not provisioned
+4. Invalidate CDN cache on the URL map
+
+## Verification
+
+```bash
+curl -s "$SERVICE_URL/health" | jq .
+```
+
+Expect `"healthy": true`. Fetch the web root URL and confirm the SPA loads and API calls hit `$SERVICE_URL`.
+
+## Troubleshooting
+
+See [references/troubleshooting.md](references/troubleshooting.md).

package/skills/deploy-gcp/references/troubleshooting.md

@@ -0,0 +1,29 @@
+# GCP deploy troubleshooting
+
+Symptom → cause → fix for Terreno on Cloud Run + GCS/CDN.
+
+## Runtime constraints
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Websockets disconnect every few requests | No session affinity on Cloud Run | Add `--session-affinity` to `gcloud run deploy` |
+| Socket connections drop after ~5 minutes | Default Cloud Run request timeout (300s) | Raise `--timeout` (for example `3600`) |
+| Log: `FeatureFlag.watch() failed — live updates require MongoDB as a replica set` | `MONGO_URI` points at standalone `mongod` | Use Atlas or a replica set — change streams required |
+| First request after idle is slow; sockets reconnect | Cloud Run scaled to zero | Set `--min-instances=1` for user-facing services |
+| Browser: `Access to fetch at '...' from origin '...' has been blocked by CORS policy` | `corsOrigin` / Better Auth `trustedOrigins` missing web CDN origin | Add CDN URL to backend CORS and auth config |
+
+## Deploy-time failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `denied: Permission "artifactregistry.repositories.uploadArtifacts" denied` | Deploy identity lacks Artifact Registry write | Grant `roles/artifactregistry.writer` to the deploy service account |
+| `Permission denied on secret ...` or `Secret Manager access denied` at cold start | Runtime SA lacks `secretmanager.secretAccessor` | Grant role on each secret or project |
+| Cloud Run revision unhealthy; logs show connection refused on health check | Container not listening on `$PORT` | Terreno reads `process.env.PORT` (`api/src/terrenoApp.ts`); set `ENV PORT=3000` in Dockerfile and `--port=3000` on deploy |
+| Web app loads but API calls go to `localhost` | `EXPO_PUBLIC_API_URL` not set at build time | Rebuild with `EXPO_PUBLIC_API_URL=$SERVICE_URL bun run export` |
+| CDN serves old UI after deploy | CDN cache not invalidated | `gcloud compute url-maps invalidate-cdn-cache SITE-url-map --path "/*" --async` |
+
+## Health check
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `curl $SERVICE_URL/health` returns `503` with `"database": "disconnected"` | MongoDB unreachable from Cloud Run | Check `MONGO_URI`, VPC/Atlas IP allowlist, and credentials |

package/skills/generate-release-announcements/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: generate-release-announcements
+description: >-
+  Generate, validate, and optionally upload a multi-announcement Markdown release
+  pack for @terreno/announcements. Use when asked to announce a product release,
+  turn release notes or a Linear Release into in-app announcements, create an
+  announcement pack, or upload release announcements as drafts or live.
+targets:
+  - '*'
+---
+
+# Generate release announcements
+
+Create a source-controlled `terreno.announcement-pack/v1` directory from release notes. Human reference: `docs/reference/announcement-release-packs.md` in Terreno or the published Terreno announcement release-pack reference.
+
+## 1. Collect the release
+
+Determine:
+
+- product identifier
+- user-facing version
+- client build number when one exists
+- channel (`production` unless the user names another)
+- release notes source: provided text/file, GitHub release/tag, changelog range, or Linear Release
+
+For a Linear URL, use the available Linear connector to read the release and completed issues. If Linear is unavailable, stop only that source lookup and ask for the exported release notes; do not invent issue contents.
+
+The collection step is complete when every feature, fix, breaking change, and operator action in the source is accounted for or explicitly excluded.
+
+## 2. Choose the surfaces
+
+Generate one or more focused announcements rather than copying raw issue lists:
+
+1. Always create a `feed` changelog containing the complete user-relevant release.
+2. Create a `modal` only for required action, breaking workflow, or high-impact staff rollout.
+3. Create a `banner` for a short, non-blocking user-facing highlight.
+4. Split staff and patient/user copy when their actions or vocabulary differ.
+
+Default to `dismiss-only`. Use `required` only when the reader must take an action or confirm operational information.
+
+The surface step is complete when each item has one audience, one purpose, and a title containing the release version.
+
+## 3. Write the pack
+
+Create:
+
+```text
+announcements/releases/<version>/
+  pack.yaml
+  <one-or-more-slugs>.md
+```
+
+Write `pack.yaml`:
+
+```yaml
+schema: terreno.announcement-pack/v1
+release:
+  product: <product>
+  version: "<version>"
+  buildNumber: <positive integer; omit when unknown>
+  channel: production
+defaults:
+  platforms: [ios, android, web]
+  audienceType: all
+  displayMode: feed
+  acknowledgementPolicy: dismiss-only
+  priority: 0
+announcements:
+  - changelog.md
+```
+
+Each listed file uses YAML frontmatter plus Markdown:
+
+```markdown
+---
+slug: changelog
+title: "Version <version>"
+displayMode: feed
+audienceType: all
+acknowledgementPolicy: dismiss-only
+---
+
+## What changed in <version>
+
+<reader-focused release copy>
+```
+
+Frontmatter may override `platforms`, `priority`, `minBuildNumber`, `publishAt`, `expiresAt`, `audience`, and `primaryAction` (`label` plus absolute `url`). The release build number becomes `minBuildNumber` unless an item overrides it.
+
+Do not write the server-managed numeric announcement `version`; that is a content revision, not the product release version.
+
+The writing step is complete when every manifest file exists and every body is useful without reading another announcement.
+
+## 4. Validate
+
+Fail before upload when any check fails:
+
+- manifest `schema` is exactly `terreno.announcement-pack/v1`
+- product and release version are non-empty
+- build number, when present, is a positive integer
+- every listed Markdown file exists exactly once
+- every item has a unique lowercase hyphenated `slug`, a title, and a non-empty body
+- enum values match the announcement reference
+- platforms are non-empty
+- timestamps are ISO 8601 and primary-action URLs are absolute
+- required modals state the required action clearly
+
+Print the product, release version, build number, channel, item count, and a table of slug/surface/audience/policy. The validation step is complete only when all checks pass.
+
+## 5. Optionally upload
+
+Do not upload unless the user asked for API posting. Convert manifest defaults and each file's frontmatter/body into the JSON request documented by `POST /announcements/import-release`.
+
+Use:
+
+- API base URL from the user or app configuration
+- token from `ANNOUNCEMENTS_UPLOAD_TOKEN` unless the user names another environment variable
+- `Authorization: Bearer <token>`
+- `"publish": false` by default
+
+Write request JSON to a temporary file outside the repository, then:
+
+```bash
+curl --fail-with-body \
+  -H "Authorization: Bearer $ANNOUNCEMENTS_UPLOAD_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data @/tmp/terreno-announcement-release.json \
+  "$API_URL/announcements/import-release"
+```
+
+Never print the token or commit the temporary JSON.
+
+Set `"publish": true` only when the user explicitly says `live`, `publish`, or equivalent. Before a live upload, show the validated item table and require confirmation unless the original unattended task explicitly authorized live publication. A normal request to “upload” means drafts.
+
+The upload step is complete when the API reports every item as created, updated, or unchanged. Report returned IDs and statuses. Delete the temporary JSON.
+
+## Completion
+
+Return:
+
+- pack directory
+- product version and build number
+- generated item count and surfaces
+- validation result
+- upload result (`not requested`, `draft`, or `live`)

package/skills/generate-sdk/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: generate-sdk
+description: >-
+  Regenerate the example-frontend SDKs from the example-backend's OpenAPI spec
+  with terreno-syncdb-codegen: store/apiSdk.ts (typed request hooks for every
+  non-synced route, `bun run sdk`) and store/syncDbSdk.ts (synced collection
+  hooks, `bun run sync-sdk`). Handles dependency install, backend startup,
+  codegen, and cleanup from a fresh checkout. Use whenever the backend's API
+  surface changes — new modelRouter routes or actions, custom routes registered
+  via createOpenApiBuilder, new/modified Mongoose models or field descriptions
+  in example-backend, sync config changes, changes to
+  permissions/queryFields/populatePaths/responseHandler, edits to @terreno/api
+  routing or OpenAPI generation, or any time a route is added/removed/renamed.
+  Also use when the user asks to "regenerate the SDK", "update apiSdk.ts" or
+  "syncDbSdk.ts", "run bun run sdk" or "bun run sync-sdk", or reports
+  stale/missing generated hooks. Lifecycle composition: Pick after API-shape
+  changes; Roast to verify generated-client compatibility.
+targets:
+  - '*'
+---
+# Generate Frontend SDK
+
+Regenerates the two generated files in `example-frontend` from the live backend spec at
+`http://localhost:4000/openapi.json` (or `OPENAPI_URL`). Both come from
+`terreno-syncdb-codegen` in `@terreno/syncdb`.
+
+| Command | Output | Covers |
+|---------|--------|--------|
+| `bun run sdk` (runs `api-sdk`) | `store/apiSdk.ts` | Every operation without `x-terreno-sync`: `/auth/me`, modelRouter actions, AI, consents, announcements, version check |
+| `bun run sync-sdk` | `store/syncDbSdk.ts` | `SYNC_COLLECTIONS` + collection hooks for the collections in the script's `--collections` list |
+
+**Never edit `store/apiSdk.ts` or `store/syncDbSdk.ts` by hand — codegen overwrites them.**
+Codegen options live in `example-frontend/syncdb-codegen.json` (`excludePaths` drops
+routes such as the SSE streams; `overrides` sets per-collection options). Built-in admin
+uses admin-frontend's own fetch client and is not generated here.
+
+## Documentation
+
+Read `docs/reference/syncdb.md#codegen` and `docs/how-to/generate-the-client-sdk.md`
+before regenerating. After a public API change, run `update-docs` in the same slice.
+
+## When to run this skill
+
+Run `sdk` when the non-synced OpenAPI surface changes; run `sync-sdk` when a synced
+collection's schema or `sync` config changes. Run both when unsure. Triggers:
+
+- New or removed `modelRouter` registration, `collectionActions`, or `instanceActions`
+- Edits to `permissions`, `queryFields`, `populatePaths`, `defaultQueryParams`, `sort`, `responseHandler`, `sync`, or `openApiOverwrite`
+- New custom routes built with `createOpenApiBuilder`
+- Mongoose schema changes that affect the public shape (fields, types, required/enum/default, `description`, refs)
+- Auth route changes (`addAuthRoutes`, `addMeRoutes`, GitHub OAuth, Better Auth)
+- Edits to `@terreno/api` OpenAPI generation (`openApi.ts`, `openApiBuilder.ts`, `api.ts`, `populate.ts`) or to `syncdb/src/codegen/`
+- A new synced collection: also add it to the `--collections` list in the `sync-sdk` script
+
+Skip it for backend-internal changes (logging, refactors that keep routes and models, tests).
+
+## Prerequisites
+
+- Bun on PATH (run `bun` directly; do not modify PATH)
+- A MongoDB **replica set** at `MONGO_URI` (the backend's change streams need one)
+- Port 4000 free
+
+## Procedure
+
+Run the steps in order. Stop and report on the first failure.
+
+### 1. Verify the worktree is bootstrapped
+
+```bash
+test -d node_modules && test -d example-backend/node_modules && test -d example-frontend/node_modules && echo "installed" || echo "missing"
+```
+
+If `missing`, run `bun run bootstrap` from the repo root in the background and wait for it.
+It installs deps and compiles every workspace package.
+
+### 2. Start MongoDB if it is not running
+
+`mongosh --quiet --eval 'rs.status().ok'` (or a `node` MongoClient ping) succeeds when a
+replica set is up. Otherwise start one from the `mongodb-memory-server` binary cache and
+initiate it once, as in `/workspace/CLAUDE.md` ("Example full stack"):
+
+```bash
+mkdir -p .devdata/mongo
+"$(ls ~/.cache/mongodb-binaries/mongod-* | head -1)" \
+  --replSet rs0 --port 27017 --bind_ip 127.0.0.1 --dbpath .devdata/mongo
+```
+
+Run `mongod` in the background. Initiate the replica set with `node` (not `bun`) from
+`example-backend/`. If no `mongod` binary exists, tell the user and stop.
+
+### 3. Ensure backend env vars are set
+
+```bash
+test -f example-backend/.env || cp example-backend/.env.example example-backend/.env
+```
+
+The example values (`MONGO_URI=mongodb://127.0.0.1:27017/terreno-example?replicaSet=rs0`,
+token and session secrets) are fine for codegen. Never overwrite an existing `.env`.
+
+### 4. Start the example backend on port 4000
+
+```bash
+bun run backend:dev
+```
+
+Use `run_in_background: true`.
+
+### 5. Wait for the OpenAPI spec
+
+Poll until the spec returns 200 (5–20 s on a cold start). Codegen against a backend that is
+not ready fails or emits an empty SDK.
+
+```bash
+until curl -sf -o /dev/null http://localhost:4000/openapi.json; do sleep 2; done
+```
+
+If the backend logs an error (Mongo connection refused, port in use, compile error), stop
+and report it.
+
+### 6. Generate
+
+```bash
+cd example-frontend && bun run sdk && bun run sync-sdk
+```
+
+Both scripts format their output with Biome. A non-zero exit names the problem: two
+operations sharing a hook name (give one an `operationId`), a missing collection path, or a
+list response without `data.items`.
+
+### 7. Stop the backend
+
+Kill the background backend you started (and `mongod`, if you started it):
+
+```bash
+pkill -f "example-backend.*src/index.ts" || true
+```
+
+### 8. Verify and report
+
+```bash
+git diff --stat example-frontend/store/apiSdk.ts example-frontend/store/syncDbSdk.ts
+cd example-frontend && bunx tsc --noEmit
+```
+
+Report which backend changes triggered the run, the diff stat, and any codegen or compile
+errors. Do not commit the generated files automatically.
+
+## Common failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `ECONNREFUSED 127.0.0.1:27017` | MongoDB not running | Step 2 |
+| Backend boots but change streams fail | Mongo is not a replica set | Start `mongod --replSet rs0` and initiate it |
+| `EADDRINUSE :::4000` | Stale backend process | `pkill -f "example-backend.*src/index.ts"`, then retry |
+| `fetch failed` / empty output | Backend not ready when codegen ran | Redo step 5 |
+| Duplicate hook name error | Two operations map to one name | Add an `operationId` to one route |
+| Screen imports a hook that no longer exists | Route renamed or excluded | Update the import; check `excludePaths` in `syncdb-codegen.json` |
+
+## Notes
+
+- Script definitions: `example-frontend/package.json` (`api-sdk`, `sdk`, `sync-sdk`). They run
+  `syncdb/src/codegen/cli.ts` directly; consumer apps call the `terreno-syncdb-codegen` bin.
+- Hook names match the old RTK codegen rule (`GET /auth/me` → `useGetAuthMeQuery`), so
+  migrated screens keep their names. Apps upgrading from `@terreno/rtk` follow
+  `docs/how-to/migrate-rtk-to-syncdb.md`.