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

package/skills/terreno-backend-api/references/model-router.md

@@ -0,0 +1,112 @@
+# modelRouter — Terreno
+
+## Registration signatures
+
+```typescript
+// TerrenoApp (recommended):
+const todoRouter = modelRouter("/todos", Todo, options);
+app.register(todoRouter);
+
+// setupServer (legacy):
+router.use("/todos", modelRouter(Todo, options));
+```
+
+## Full options reference
+
+```typescript
+modelRouter("/todos", Todo, {
+  permissions: {
+    create: [Permissions.IsAuthenticated],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsOwner],
+    update: [Permissions.IsOwner],
+    delete: [],  // disabled
+  },
+  queryFields: ["completed", "ownerId"],
+  queryFilter: OwnerQueryFilter,
+  sort: "-created",
+  defaultLimit: 100,
+  maxLimit: 500,
+  populatePaths: [{path: "ownerId", fields: ["name", "email"]}],
+  preCreate: (body, req) => ({...body, ownerId: req.user?._id}),
+  preUpdate: (body, req) => body,
+  postCreate: (doc, req) => {},
+  postUpdate: (doc, body, req, prev) => {},
+  postDelete: (req, doc) => {},
+  responseHandler: (value, method, req, options) => value,
+  validation: {
+    validateCreate: true,
+    validateUpdate: true,
+    validateQuery: true,
+    excludeFromCreate: ["ownerId"],
+    excludeFromUpdate: ["ownerId"],
+  },
+  sync: {scope: {type: "owner"}},
+  collectionActions: {
+    bulkComplete: {
+      method: "POST",
+      permissions: [Permissions.IsAuthenticated],
+      body: z.object({ids: z.array(z.string()).min(1)}).strict(),
+      response: z.object({matched: z.number(), modified: z.number()}).strict(),
+      summary: "Mark multiple todos complete",
+      handler: async ({body, user}) => { /* ... */ },
+    },
+  },
+  instanceActions: {
+    markComplete: {
+      method: "POST",
+      permissions: [Permissions.IsOwner],
+      summary: "Mark a single todo complete",
+      handler: async ({doc}) => { /* ... */ },
+    },
+  },
+  collectionActions: { /* named GET/POST on /todos/{name} */ },
+  instanceActions: { /* named GET/POST on /todos/:id/{name} */ },
+  // Last resort only — prefer collectionActions / instanceActions.
+  endpoints: (router) => {
+    // Custom routes registered before CRUD
+  },
+});
+```
+
+## Query features
+
+- Pagination: `?limit=20&page=2`
+- Sort: `?sort=-created`
+- Filters: `?completed=true` (field must be in `queryFields`)
+- Complex: `?$and=[{...}]`, `?$or=[{...}]`
+
+## Lifecycle hooks
+
+| Hook | When | Use for |
+|------|------|---------|
+| `preCreate` | Before insert | Set `ownerId`, defaults |
+| `preUpdate` | Before patch | Strip immutable fields |
+| `postCreate` | After insert | Side effects, notifications |
+| `postUpdate` | After patch | Audit, cache invalidation |
+| `postDelete` | After delete | Cleanup |
+
+## User casting in callbacks
+
+```typescript
+const user = u as unknown as UserDocument;
+// or in route handlers:
+(req.user as unknown as UserDocument)?._id
+```
+
+Never use `as any as UserDocument`.
+
+## Plugins on schemas
+
+| Plugin | Adds |
+|--------|------|
+| `createdUpdatedPlugin` | `created`, `updated` timestamps |
+| `isDeletedPlugin` | Soft delete (`deleted` field) |
+| `findExactlyOne` | Static that throws on 0 or >1 match |
+| `findOneOrNone` | Static that returns null on 0, throws on >1 |
+
+## OpenAPI
+
+`setupServer` / `TerrenoApp` auto-generates `/openapi.json`. Field `description` on schema paths flows to the spec via `mongoose-to-swagger`.
+
+After any model or router change, regenerate the frontend SDK.

package/skills/terreno-backend-api/references/server-setup.md

@@ -0,0 +1,116 @@
+# Server Setup — Terreno
+
+## TerrenoApp (recommended)
+
+```typescript
+import {TerrenoApp} from "@terreno/api";
+import {User} from "./models/user";
+import {todoRouter} from "./api/todos";
+
+const app = new TerrenoApp({
+  userModel: User,
+  loggingOptions: {logRequests: true, logSlowRequests: true},
+})
+  .register(todoRouter)
+  .start();
+```
+
+Methods: `.register()`, `.addMiddleware()`, `.build()`, `.start()`.
+
+## setupServer (legacy)
+
+```typescript
+import {setupServer} from "@terreno/api";
+
+setupServer({
+  userModel: User,
+  addRoutes: (router, options) => {
+    router.use("/todos", modelRouter(Todo, {...options, ...}));
+  },
+});
+```
+
+## Required environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `MONGO_URI` | MongoDB connection (replica set for change streams) |
+| `TOKEN_SECRET` | JWT signing secret |
+| `TOKEN_ISSUER` | JWT issuer claim |
+| `REFRESH_TOKEN_SECRET` | Refresh token secret |
+| `SESSION_SECRET` | Express session secret |
+| `PORT` | Server port (default 4000) |
+
+Optional: `ENABLE_SWAGGER=true`, `USE_SENTRY_LOGGING=true`, GitHub OAuth vars, Better Auth vars.
+
+## MongoDB for local dev
+
+The dev server needs a real replica set (change streams). See `AGENTS.md` for the single-node replica set setup with `mongodb-memory-server` cache binary.
+
+```bash
+MONGO_URI="mongodb://127.0.0.1:27017/terreno-example?replicaSet=rs0" \
+  TOKEN_SECRET=dev-token-secret TOKEN_ISSUER=terreno-dev \
+  REFRESH_TOKEN_SECRET=dev-refresh-secret SESSION_SECRET=dev-session-secret \
+  PORT=4000 bun run backend:dev
+```
+
+Seed users: `cd example-backend && bun run seed` → `test@example.com` / `testpassword123`.
+
+## Health check
+
+```bash
+curl localhost:4000/health
+# {"healthy":true,...}
+```
+
+## OpenAPI / Swagger
+
+- Spec: `http://localhost:4000/openapi.json`
+- Swagger UI: `http://localhost:4000/swagger` (when `ENABLE_SWAGGER=true`)
+
+## Logging
+
+```typescript
+import {createScopedLogger, logger} from "@terreno/api";
+
+logger.info("Server started", {port: 4000});
+
+const log = createScopedLogger({
+  prefix: "[Billing]",
+  labels: {invoiceId: id.toString()},
+});
+log.info("Processing payment");
+```
+
+Never use `console.log` for permanent server logs.
+
+## Testing
+
+```typescript
+import {describe, it, expect} from "bun:test";
+import request from "supertest";
+import {getBaseServer, authAsUser, setupDb} from "@terreno/api/tests";
+
+describe("todos", () => {
+  it("lists todos for authenticated user", async () => {
+    const app = await getBaseServer();
+    const agent = await authAsUser(app, "notAdmin");
+    const res = await agent.get("/todos");
+    expect(res.status).toBe(200);
+  });
+});
+```
+
+See `backend-test-env` skill when tests mutate `process.env`.
+
+## Plugins
+
+Register `TerrenoPlugin` implementations:
+
+```typescript
+import {BetterAuthApp, type BetterAuthConfig} from "@terreno/api";
+import {AdminApp} from "@terreno/admin-backend";
+
+app.register(new BetterAuthApp({config: betterAuthConfig, userModel: User}));
+admin.register(app);
+```

package/skills/terreno-backend-tests/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: terreno-backend-tests
+description: >-
+  Write and fix Bun tests for a Terreno backend: modelRouter routes and actions, permissions,
+  Mongoose models and hooks, services that call SendGrid / Twilio / Expo push / Cloud Tasks /
+  GCS / AI models, env-dependent code, time, and async side effects. Covers supertest +
+  @terreno/test helpers, auth tokens, test data, service mocks, and flake-free waiting. Use
+  when adding or changing backend behavior or when a backend test fails. If the app has no
+  test preload yet, run terreno-test-setup first.
+---
+
+# Writing Terreno backend tests
+
+Tests use `bun:test`, run against a real in-memory MongoDB, and call the app through HTTP with
+supertest. Never mock `@terreno/api` internals or your own models — exercise the real stack.
+
+## 1. Pick the seam
+
+| Behavior | Test through |
+|----------|--------------|
+| CRUD, actions, permissions, query filters, response shape | HTTP route (`supertest`) — default |
+| Model statics, methods, hooks, validation | the model directly |
+| A service with no route | its exported function |
+| Third-party side effect (email, SMS, task, upload, AI call) | the route or service, asserting on the preload's mock handle |
+
+Done when: the test file sits next to the code (`todos.ts` → `todos.test.ts`) and names the
+seam in its `describe`.
+
+## 2. Build the app per file
+
+```typescript
+import {beforeEach, describe, expect, it} from "bun:test";
+import {generateTokens, TerrenoApp} from "@terreno/api";
+import {authWithToken, expectAPIError} from "@terreno/test";
+import supertest from "supertest";
+import {Todo} from "../models/todo";
+import {User} from "../models/user";
+import {todoRouter} from "./todos";
+
+const app = new TerrenoApp({skipListen: true, userModel: User as never})
+  .register(todoRouter)
+  .build();
+```
+
+Register only the routers and plugins under test. Do not call the app's `start()`: it connects
+to the dev database and registers everything.
+
+## 3. Authenticate
+
+```typescript
+const createUser = async (email: string, admin = false) =>
+  User.register({admin, email, name: email} as never, "password12345");
+
+const agentFor = async (user: unknown) =>
+  authWithToken(app, {token: (await generateTokens(user)).token});
+```
+
+- `authWithToken` + `generateTokens` mints the same JWT `/auth/login` issues, without the
+  ~200ms password hash. Use it everywhere except tests of the login flow itself.
+- `authAsUser(app, {email, password})` really logs in; keep it for login, lockout, and
+  password tests.
+- `supertest(app)` with no token is the anonymous client.
+
+Permission failures by layer — assert the exact status:
+
+| Case | Status |
+|------|--------|
+| No or invalid token on a protected route | 401 |
+| Method-level permission fails (`list`, `create`, or a disabled `[]` method) | 405 |
+| Object-level permission fails (`read`, `update`, `delete` on a loaded document, e.g. `IsOwner`) | 403 |
+| `list` where `queryFilter` excludes another user's documents | 200, those documents absent |
+| Id that does not exist | 404 |
+
+Write one test per role that matters: owner, other user, admin, anonymous.
+
+## 4. Create and clean data
+
+- Create exactly what the test needs, in the test or a `beforeEach`, with small factory
+  functions (`createUser`, `createTodo({ownerId, ...overrides})`) local to the file or in
+  `src/tests/factories.ts`.
+- The default preload does not wipe the database. Start each test clean for the collections
+  it reads: `beforeEach(async () => { await Todo.deleteMany({}); await User.deleteMany({}); })`.
+  (Apps on `registerBackendPreload({useTransactions: true})` roll back automatically; skip
+  the deletes there.)
+- Dates are Luxon: `DateTime.fromISO("2024-06-01T10:00:00Z")`, compared with `.toISO()` or
+  `.toMillis()`.
+- Expected values are literals from the example, never recomputed with production code.
+
+## 5. Assert
+
+```typescript
+it("lets an owner list only their todos", async () => {
+  const owner = await createUser("owner@example.com");
+  const other = await createUser("other@example.com");
+  await Todo.create({ownerId: owner._id, title: "Mine"});
+  await Todo.create({ownerId: other._id, title: "Theirs"});
+
+  const res = await (await agentFor(owner)).get("/todos").expect(200);
+
+  expect(res.body.data.map((todo: {title: string}) => todo.title)).toEqual(["Mine"]);
+  expect(res.body.total).toBe(1);
+});
+
+it("rejects a todo without a title", async () => {
+  const res = await (await agentFor(await createUser("a@example.com"))).post("/todos").send({});
+  expectAPIError(res, {status: 400, title: /validation/i});
+});
+```
+
+- List responses are `{data, limit, more, page, total}`; single documents are `{data}`.
+- `expectAPIError(res, {status, title?, detail?, code?, fields?})` matches the JSONAPI error
+  body; `fields` partially matches `meta.fields`.
+- On routes that return user or PHI data, pin the response shape so a new model field cannot
+  leak: `assertStrictResponseProperties(res.body, ["data._id", "data.name", "limit", "more",
+  "page", "total"])`.
+- After a write, re-read through the API (or `Model.findById`) to prove persistence.
+
+## 6. Services and side effects
+
+Mocks are registered once in `src/tests/bunSetup.ts` and exported (see `terreno-test-setup`).
+Import the handle and assert what the app sent:
+
+```typescript
+import {cloudTasks, gcs, sendGrid} from "../tests/bunSetup";
+
+expect(sendGrid.getSentMessages()).toEqual([
+  expect.objectContaining({subject: "Welcome", to: "new@example.com"}),
+]);
+
+await cloudTasks.drainTasks({app, headers: {authorization: "Bearer task-secret"}});
+
+gcs.putObject({bucket: "uploads", contents: "hi", name: "a.txt"});
+```
+
+- Cloud Tasks: assert `getEnqueuedTasks()` (decoded bodies), then `drainTasks({app})` to run
+  the task handlers through HTTP; it also drains tasks the handlers enqueue.
+- Make a provider fail with the mock's standard API, e.g.
+  `sendGrid.send.mockRejectedValueOnce(new Error("503"))`, and assert the app's handling.
+- AI: `new AIService({model: createMockLanguageModel({responses: [{text: "Hi"}, {toolCalls:
+  [...]}]})})`; assert prompts via `model.doGenerate.mock.calls` / `doStream.mock.calls`.
+- Never `mock.module` inside a test file: it replaces the module for every later file in the
+  run. Use the preload, dependency injection, or `spyOn(object, "method")` (restored
+  automatically after each test).
+
+## 7. Env, time, and async
+
+- Env: set only the keys the test needs (`process.env.FEATURE_X = "true"`); express "unset" as
+  `Reflect.deleteProperty(process.env, "KEY")`. The preload re-applies the canonical env after
+  every test. Never snapshot and restore all of `process.env`.
+- Time: `freezeTime("2024-06-01T10:30:00Z")` from `@terreno/test` freezes `Date.now()`,
+  `new Date()`, and Luxon for the current test and restores afterwards.
+- Async side effects (post-save hooks, fire-and-forget writes, jobs): wait for the outcome, not
+  a duration — `await waitForDocuments(AuditEvent, {action: "create"}, 1)`,
+  `await waitUntil(() => sendGrid.send.mock.calls.length > 0, {label: "welcome email"})`, or
+  `await waitForCalls(mockFn, 2)`. Never `await new Promise((r) => setTimeout(r, n))`.
+
+## 8. Run
+
+```bash
+bun test src/api/todos.test.ts          # one file
+bun test -t "lists only their todos"    # by name
+bun test --only-failures                # rerun what failed last time
+bun test --coverage                     # coverage report
+```
+
+A test that passes alone and fails in the full run is leaking state: a module mock in a test
+file, a collection not cleaned, or an env key not reset. Fix the leak; do not reorder files.
+
+## Checklist
+
+- [ ] Happy path plus each rejected role/case asserts an exact status
+- [ ] Data created in the test; collections it reads cleaned in `beforeEach`
+- [ ] Third-party calls asserted on the preload mock handles; no `mock.module` in the file
+- [ ] No sleeps; async outcomes awaited with `waitUntil` / `waitForDocuments`
+- [ ] Time-dependent behavior uses `freezeTime`; env changes are targeted
+- [ ] `bun test` passes for the whole backend, not just the file

package/skills/terreno-data-fetching/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: terreno-data-fetching
+description: >-
+  Use when implementing or debugging ANY network request, API call, or data
+  fetching in a Terreno app. Covers syncdb collection CRUD, generated request
+  hooks (store/apiSdk.ts) for non-synced routes, session auth, socket pushes,
+  feature flags, admin's host-bound fetch client, and SDK regeneration. Replaces direct fetch, axios, React Query, and SWR in
+  application code.
+  Lifecycle composition: Grow for data-flow shape, Pick for implementation, Roast
+  for independent network/cache behavior proof.
+---
+# Terreno Data Fetching
+
+**You MUST use this skill for ANY networking work in Terreno apps.** Everything goes
+through `@terreno/syncdb`: `useQuery` / `useMutate` for synced collection CRUD, and
+generated hooks on the `@terreno/syncdb/api` request client for every other route.
+Never call `axios`, raw `fetch`, React Query, or SWR from application screens.
+`@terreno/rtk` and Redux were removed in Terreno 58; upgrade old code with
+`docs/how-to/migrate-rtk-to-syncdb.md`.
+
+**Related skills:** `generate-sdk` (regenerate hooks after backend changes), `terreno-backend-api` (create backend routes), `building-terreno-apps` (screen integration).
+
+## Documentation
+
+1. Read `docs/reference/syncdb.md`, `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/how-to/use-syncdb-correctly.md`, and auth/realtime explanation pages before changing fetch, cache, or session behavior.
+2. Implement against that design.
+3. Update those pages in the same slice with `update-docs`.
+4. Ship without matching docs is a failed slice.
+
+## References
+
+```
+references/
+  auth-and-tokens.md     SessionProvider/useSession, login/logout, token refresh, JWT
+  realtime.md            Socket events, feature flags, sync status
+  sdk-customization.md   Generated apiSdk.ts, ad-hoc useApiQuery/useApiMutation, cache tags
+```
+
+## When to Use
+
+- Implementing API requests in screens or hooks
+- Setting up authentication (login, logout, token refresh)
+- Debugging network failures or stale data
+- Connecting realtime updates (sockets, feature flags)
+- Configuring API URLs and environment variables
+- After any backend route or model change (regenerate SDK)
+
+## Core Rules
+
+1. **Use syncdb hooks** (`useQuery`, `useEntity`, `useWindowQuery`, `useMutate`) for synced collection CRUD.
+2. **Use generated hooks** from `store/apiSdk.ts` (`terreno-syncdb-codegen --api-out`) for every
+   non-synced route: `/auth/me`, modelRouter actions, AI, consents, announcements.
+3. **Never edit `store/apiSdk.ts` or `store/syncDbSdk.ts`** — regenerate with `generate-sdk`.
+4. **Ad-hoc routes not in OpenAPI** use `useApiQuery` / `useLazyApiQuery` / `useApiMutation`
+   from `@terreno/syncdb/react`. Prefer documenting the route in OpenAPI and regenerating.
+5. **Never use `axios` or raw `fetch`** in app code. Exceptions: SSE streams (`/gpt/prompt`)
+   authenticated with `authProvider.getToken()`, and framework-owned admin requests
+   (`@terreno/admin-frontend` binds `adminRequest` from `AdminProvider` `credentials` /
+   `getAuthHeaders` / `apiOrigin`).
+6. **Admin uses its own fetch client.** String-`_id` models with `adminBroadcast` use
+   windowed syncdb; ObjectId/API-only CRUD uses `useAdminModelApi`; admin RPC uses
+   `useAdminRpc`. Admin components take no `api` prop (removed in Terreno 58).
+
+## Quick Start
+
+### Synced collection read
+
+```tsx
+import {useQuery} from "@terreno/syncdb/react";
+
+const TodosScreen: React.FC = () => {
+  const todos = useQuery<Todo>("todos", {
+    filter: (todo) => !todo.completed,
+  });
+};
+```
+
+### Synced collection write
+
+```tsx
+import {generateMutationId} from "@terreno/syncdb";
+import {useMutate} from "@terreno/syncdb/react";
+
+const {create, update} = useMutate("todos");
+
+const handleCreate = useCallback((): void => {
+  create({data: {_id: generateMutationId(), title: "New todo", completed: false}});
+}, [create]);
+
+const handleToggle = useCallback((id: string, completed: boolean): void => {
+  update({id, data: {completed: !completed}});
+}, [update]);
+```
+
+### Non-synced route
+
+```tsx
+import {useGetAuthMeQuery, usePatchAuthMeMutation} from "@/store/apiSdk";
+
+const {data: me, isLoading} = useGetAuthMeQuery(undefined, {skip: !userId});
+const [updateMe, {isLoading: isSaving}] = usePatchAuthMeMutation();
+await updateMe({name}).unwrap();
+```
+
+### Auth
+
+```tsx
+import {useSession} from "@terreno/syncdb/auth";
+
+const {userId, isAuthenticated, isLoading, logout} = useSession();
+```
+
+See `./references/auth-and-tokens.md` for the full auth flow.
+
+## Client Setup
+
+One `authProvider` feeds the sync client and the request client, so both send the same
+token and refresh on a 401 the same way. Reference: `example-frontend/store/syncdb.ts`,
+`store/apiClient.ts`, `app/_layout.tsx`.
+
+```tsx
+// store/syncdb.ts
+export const authProvider = betterAuthAdapter(bridgeBetterAuthReactClient(betterAuthClient));
+export const syncDb = createSyncDb({authProvider, baseUrl, collections: [...SYNC_COLLECTIONS], name: "myapp", wipeOnSignOut: true});
+
+// store/apiClient.ts
+export const apiClient = createApiClient({authProvider, baseUrl, credentials: "include", headers: appHeaders});
+
+// app/_layout.tsx — no Redux store
+<SessionProvider authClient={betterAuthClient} syncDbs={[syncDb]} onLogout={() => apiClient.reset()}>
+  <ApiClientProvider client={apiClient}>
+    <SyncDbProvider client={syncDb}>{children}</SyncDbProvider>
+  </ApiClientProvider>
+</SessionProvider>
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `EXPO_PUBLIC_API_URL` | Backend URL for web dev (e.g. `http://localhost:4000`) |
+| `EXPO_PUBLIC_DEV_API_PORT` | Dev API port when using Expo host URI (default `4000`) |
+| `expo.extra.BASE_URL` | Production/staging API URL in `app.json` |
+
+Base URL resolution priority (`baseUrl` from `@terreno/syncdb/config`):
+
+1. `expo.extra.BASE_URL`
+2. `EXPO_PUBLIC_API_URL`
+3. Expo dev server host + dev API port
+4. `http://localhost:4000`
+
+Never put server secrets in `EXPO_PUBLIC_*` variables.
+
+## Error Handling
+
+Request hooks expose `ApiError` (`@terreno/syncdb/api`) on the result:
+
+```tsx
+const {error, isError} = useGetAuthMeQuery();
+
+if (isError) {
+  // error.status, error.data.title, error.data.detail; status 0 = network error or timeout
+  console.error("Query failed", error);
+}
+```
+
+For mutations, use `.unwrap()`:
+
+```tsx
+try {
+  await updateMe({name}).unwrap();
+} catch (error) {
+  if (isApiError(error)) {
+    console.error("Mutation failed", error.data.title);
+  }
+}
+```
+
+Report every request failure once with `createApiClient({onError})` (skip Sentry when
+`error.data.disableExternalErrorTracking` is `true`). Synced writes never throw: rejected
+writes surface in `useConflicts()` and `useSyncStatus().failedCount`.
+
+## SDK Regeneration
+
+After a backend API change, run the `generate-sdk` skill.
+
+```bash
+# Backend running on :4000, then:
+cd example-frontend && bun run sdk        # store/apiSdk.ts (non-synced routes)
+cd example-frontend && bun run sync-sdk   # store/syncDbSdk.ts (synced collections)
+```
+
+Triggers: custom routes, modelRouter actions, non-synced `modelRouter` routes, and OpenAPI
+edits (`sdk`); synced schema or `sync` config changes (`sync-sdk`).
+
+## Decision Tree
+
+```
+Need data in a Terreno app?
+  |-- Synced collection CRUD?
+  |   \-- @terreno/syncdb hooks
+  |
+  |-- Non-synced API route?
+  |   \-- useGet*/usePost* from store/apiSdk.ts
+  |
+  |-- Built-in admin?
+  |   |-- String id + adminBroadcast -> windowed syncdb
+  |   |-- Framework RPC -> AdminProvider adminRequest (useAdminRpc)
+  |   \-- ObjectId / API-only CRUD -> useAdminModelApi
+  |
+  |-- Login/logout?
+  |   \-- references/auth-and-tokens.md
+  |
+  |-- Server push / feature flags?
+  |   \-- references/realtime.md (useSocketEvent, @terreno/syncdb/flags)
+  |
+  |-- Custom endpoint not in SDK?
+  |   |-- Backend exists? -> generate-sdk first
+  |   \-- Route outside OpenAPI? -> references/sdk-customization.md (useApiQuery)
+  |
+  |-- Backend doesn't exist?
+  |   \-- terreno-backend-api, then generate-sdk
+  |
+  \-- Using axios/direct fetch/React Query?
+      \-- STOP — choose syncdb or a generated hook
+```
+
+## Common Mistakes
+
+**Wrong: axios**
+
+```tsx
+const result = await axios.get("/todos");
+```
+
+**Right: syncdb for a synced collection**
+
+```tsx
+const todos = useQuery<Todo>("todos");
+```
+
+**Wrong: manual token in fetch**
+
+```tsx
+fetch(url, {headers: {Authorization: `Bearer ${token}`}});
+```
+
+**Right: a generated hook handles auth for a non-synced route**
+
+```tsx
+const {data: profile} = useGetAuthMeQuery();
+```
+
+**Wrong: editing store/apiSdk.ts**
+
+```tsx
+// Adding a new endpoint by hand
+```
+
+**Right: regenerate**
+
+```bash
+cd example-frontend && bun run sdk
+```
+
+**Wrong: refusing a synced write with 403 from a router hook**
+
+```typescript
+throw new APIError({status: 403, title: "Not a member"}); // in preCreate — halts the client outbox
+```
+
+**Right: 422, so syncdb nacks it as `validation`**
+
+```typescript
+throw new APIError({status: 422, title: "Not a member"});
+```
+
+**Wrong: rendering the empty state from `useQuery` before the stream bootstraps.** An empty array before bootstrap looks the same as an empty collection. Gate on the stream's `bootstrapped` cell. See `docs/how-to/use-syncdb-correctly.md` for this and the other pitfalls (cold-start cost per stream, dropped ack warnings, phantom creates, unresolved conflicts).
+
+## Example Invocations
+
+- "How do I fetch todos?" → `useQuery("todos")` from `@terreno/syncdb/react`
+- "How do I handle login?" → `betterAuthClient.signIn.email` then `useSession().refresh()`
+- "Should I use React Query?" → No — syncdb for collections, generated `store/apiSdk.ts` hooks for non-synced routes
+- "API calls return 401" → Check the shared `authProvider`; see auth-and-tokens.md
+- "Old code imports `@terreno/rtk`" → `docs/how-to/migrate-rtk-to-syncdb.md`
+- "Hooks are missing after backend change" → Run `generate-sdk` skill
+- "How do I add a custom endpoint?" → Backend route + OpenAPI, then regenerate the SDK

package/skills/terreno-data-fetching/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Terreno Data Fetching"
+  short_description: "syncdb collection hooks, generated request hooks, session auth, and socket events for Terreno apps — never axios or raw fetch"
+  default_prompt: "Use $terreno-data-fetching to implement API calls with @terreno/syncdb collection hooks, generated store/apiSdk.ts hooks, and session auth in a Terreno app."