@terreno/agent-plugin 0.0.0-stage → 57.21.0

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

@@ -0,0 +1,191 @@
+# Screen Patterns — Terreno Apps
+
+## List screen
+
+```tsx
+import {Box, Button, Card, Heading, Page, Spinner, Text} from "@terreno/ui";
+import {useCallback} from "react";
+import {useGetTodosQuery} from "@/store/sdk";
+
+const TodoListScreen: React.FC = () => {
+  const {data, isLoading, error, refetch} = useGetTodosQuery({});
+
+  const handleCreate = useCallback((): void => {
+    // navigate or open modal
+  }, []);
+
+  if (isLoading) {
+    return <Page title="Todos"><Spinner /></Page>;
+  }
+  if (error) {
+    return (
+      <Page title="Todos">
+        <Text color="error">Failed to load</Text>
+        <Button text="Retry" onClick={refetch} />
+      </Page>
+    );
+  }
+
+  const items = data?.data ?? [];
+
+  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>
+        {items.length === 0 ? (
+          <Text color="secondaryLight">No todos yet</Text>
+        ) : (
+          items.map((todo) => (
+            <Card key={todo.id} padding={3}>
+              <Text>{todo.title}</Text>
+            </Card>
+          ))
+        )}
+      </Box>
+    </Page>
+  );
+};
+```
+
+## Profile screen
+
+Use `TapToEdit` for per-field profile edits. Save each field with `usePatchMeMutation` — 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 {useGetMeQuery, usePatchMeMutation} from "@/store/sdk";
+
+const ProfileScreen: React.FC = () => {
+  const {data: profile} = useGetMeQuery();
+  const [updateProfile] = usePatchMeMutation();
+  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 {Box, Button, Page, TextField} from "@terreno/ui";
+import {useCallback, useState} from "react";
+import {useRouter} from "expo-router";
+import {usePostTodosMutation} from "@/store/sdk";
+
+const CreateTodoScreen: React.FC = () => {
+  const router = useRouter();
+  const [title, setTitle] = useState<string>("");
+  const [titleError, setTitleError] = useState<string | undefined>();
+  const [createTodo, {isLoading}] = usePostTodosMutation();
+
+  const handleSubmit = useCallback(async (): Promise<void> => {
+    if (!title.trim()) {
+      setTitleError("Title is required");
+      return;
+    }
+    try {
+      await createTodo({title: title.trim(), completed: false}).unwrap();
+      router.back();
+    } catch (err) {
+      console.error("Create failed", err);
+    }
+  }, [createTodo, 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} loading={isLoading} fullWidth />
+      </Box>
+    </Page>
+  );
+};
+```
+
+## Detail screen with params
+
+```tsx
+import {Page, Spinner, Text} from "@terreno/ui";
+import {useLocalSearchParams} from "expo-router";
+import {useGetTodosByIdQuery} from "@/store/sdk";
+
+const TodoDetailScreen: React.FC = () => {
+  const {id} = useLocalSearchParams<{id: string}>();
+  const {data, isLoading, error} = useGetTodosByIdQuery({id: id ?? ""}, {skip: !id});
+
+  if (isLoading) {
+    return <Page title="Todo"><Spinner /></Page>;
+  }
+  if (error || !data) {
+    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";
+import {terrenoApi} from "@/store/sdk";
+
+const AdminModelScreen: React.FC = () => {
+  const {model} = useLocalSearchParams<{model: string}>();
+  return (
+    <AdminScreenRouter
+      api={terrenoApi}
+      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,156 @@
+---
+name: generate-sdk
+description: >-
+  Regenerate the example-frontend RTK Query SDK (store/openApiSdk.ts) from the
+  example-backend's OpenAPI spec. Handles dependency install, backend startup,
+  SDK codegen, and cleanup from a fresh checkout. Use whenever the backend's API
+  surface changes — new modelRouter routes, custom routes registered via
+  createOpenApiBuilder, new/modified Mongoose models or field descriptions in
+  example-backend, 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 openApiSdk.ts",
+  "run bun run 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 `example-frontend/store/openApiSdk.ts` from the backend OpenAPI spec via RTK Query codegen.
+
+**Scope:** This skill covers **non-synced** routes only (auth, profile, AI,
+feature flags, custom RPC). Synced collections use `@terreno/syncdb` hooks
+(`useQuery`, `useMutate`) — they are **not** in the generated SDK. Built-in
+admin RPC uses admin-frontend's host-bound fetch client; do not add admin
+`injectEndpoints`. See [syncdb reference](../../../../docs/reference/syncdb.md)
+and [migrate-rtk-to-syncdb.md](../../../../docs/how-to/migrate-rtk-to-syncdb.md).
+
+### Legacy RTK data path
+
+During the `@terreno/rtk` support window, some screens may still use generated `useGetXQuery` / `usePostXMutation` for collections. Do not add new collection hooks — migrate to syncdb instead.
+
+The `example-frontend` consumes the `example-backend` API via auto-generated RTK Query hooks in `store/openApiSdk.ts`. The codegen pulls from the live backend at `http://localhost:4000/openapi.json`, so the backend must be running while `bun run sdk` executes.
+
+**Never edit `example-frontend/store/openApiSdk.ts` by hand — it is fully overwritten by this skill.**
+
+## Documentation
+
+Read `docs/reference/syncdb.md` and the backend/OpenAPI reference before regenerating. After a public API change, run `update-docs` in the same slice so reference and how-to pages match the new hooks. Generated SDK files are not hand-edited docs.
+
+## When to run this skill
+
+Run it whenever the backend's OpenAPI surface changes. Common triggers:
+
+- New or removed `modelRouter` registration
+- Edits to `permissions`, `queryFields`, `populatePaths`, `defaultQueryParams`, `sort`, `responseHandler`, or `openApiOverwrite` on an existing `modelRouter`
+- New custom routes built with `createOpenApiBuilder` (path params, query params, request body, response schema changes)
+- Mongoose schema changes that affect the public shape: added/removed fields, type changes, required/enum/default changes, `description` updates, ref changes
+- Changes to auth routes (e.g. `addAuthRoutes`, `addMeRoutes`, GitHub OAuth, Better Auth)
+- Edits to `@terreno/api` files that produce the OpenAPI spec (`openApi.ts`, `openApiBuilder.ts`, `api.ts`, `populate.ts`)
+- User asks: "regenerate SDK", "update the SDK", "run bun run sdk", "openApiSdk.ts is out of date"
+
+If the change is purely backend-internal (logging, refactor that doesn't alter routes/models, test-only edits), the SDK does **not** need regeneration — skip this skill.
+
+## Prerequisites
+
+- Bun is on PATH (run `bun` directly; do not modify PATH)
+- MongoDB reachable at `mongodb://localhost:27017` (the example backend connects on boot)
+- Ports 4000 (backend) must be free
+
+If MongoDB is not running, tell the user and stop — do not try to install or start it automatically.
+
+## Procedure
+
+Run the steps in order. Stop and report on the first failure.
+
+### 1. Verify the worktree is bootstrapped
+
+Detect whether dependencies are installed. The repo uses Bun workspaces, so a single root `node_modules` is sufficient.
+
+```bash
+test -d node_modules && test -d example-backend/node_modules && test -d example-frontend/node_modules && echo "installed" || echo "missing"
+```
+
+If `missing`, run the full bootstrap from the repo root. This installs deps **and** compiles every workspace package (needed because `example-frontend` imports built artifacts from `@terreno/rtk` and other workspaces):
+
+```bash
+bun run bootstrap
+```
+
+Bootstrap can take a few minutes — run it in the background and wait for it to finish before continuing.
+
+### 2. Ensure backend env vars are set
+
+The backend reads `example-backend/.env`. If that file is missing, copy the example:
+
+```bash
+test -f example-backend/.env || cp example-backend/.env.example example-backend/.env
+```
+
+The default `.env.example` values are fine for local SDK generation. Do not invent secrets or overwrite an existing `.env`.
+
+### 3. Start the example backend on port 4000
+
+The dev script watches files, which is fine for a one-shot codegen run. Start it in the background from the repo root:
+
+```bash
+bun run backend:dev
+```
+
+Use the Bash tool's `run_in_background: true` so the process keeps running while you continue.
+
+### 4. Wait for the OpenAPI spec to be served
+
+Poll `http://localhost:4000/openapi.json` until it returns HTTP 200. The backend has to connect to MongoDB and register all routes before the spec is available, which can take 5–20 seconds on a cold start. Do not skip this wait — running `bun run sdk` before the spec is ready produces an empty/broken `openApiSdk.ts`.
+
+```bash
+until curl -sf -o /dev/null -w "%{http_code}" http://localhost:4000/openapi.json | grep -q 200; do sleep 2; done
+```
+
+If the backend logs an error (Mongo connection refused, port already in use, compile error), stop and surface the error to the user. Do not retry blindly.
+
+### 5. Generate the SDK
+
+Run the codegen from `example-frontend`. The script also runs Biome formatting on the output and strips an empty re-export line, so no follow-up formatting is needed.
+
+```bash
+cd example-frontend && bun run sdk
+```
+
+If the script fails with a missing module error (e.g. `@rtk-query/codegen-openapi`), dependencies are stale — re-run `bun run bootstrap` from the repo root and try again.
+
+### 6. Stop the backend
+
+Kill the background backend process you started in step 3. Use the PID from the background shell, or:
+
+```bash
+pkill -f "example-backend.*src/index.ts" || true
+```
+
+### 7. Verify and report
+
+Confirm `example-frontend/store/openApiSdk.ts` exists and was modified. Show the user a short summary:
+
+- Which routes/models triggered the regeneration
+- A `git diff --stat example-frontend/store/openApiSdk.ts` to show the size of the change
+- Any warnings or errors emitted by the backend or codegen
+
+Do **not** commit `openApiSdk.ts` automatically — leave that to the user's normal commit flow.
+
+## Common failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `ECONNREFUSED 127.0.0.1:27017` | MongoDB not running | Ask the user to start Mongo; do not auto-start |
+| `EADDRINUSE :::4000` | Stale backend process | `pkill -f "example-backend.*src/index.ts"` then retry |
+| `Cannot find module '@rtk-query/codegen-openapi'` | Missing/stale deps | Re-run `bun run bootstrap` |
+| `openApiSdk.ts` has no endpoints | Backend wasn't ready when codegen ran | Step 4 wait was skipped — start over with a proper poll |
+| Codegen errors on `$ref` | Backend OpenAPI spec is malformed | Inspect `/openapi.json` manually; check recent changes to `openApi.ts` or model schemas |
+
+## Notes
+
+- The codegen config lives at `example-frontend/openapi-config.ts`. The schema URL respects `OPENAPI_URL` if set, otherwise defaults to `http://localhost:4000/openapi.json`.
+- The script entry point is `example-frontend/scripts/generate-sdk.ts` — it shells out to the `@rtk-query/codegen-openapi` CLI, then post-processes the output with Biome.
+- Custom endpoints and cache tag types are layered on top in `example-frontend/store/sdk.ts` via `injectEndpoints`/`enhanceEndpoints`; that file is hand-maintained and is **not** overwritten by codegen.