@terreno/mcp 57.21.0 → 58.0.0-beta.1

package/src/docs/resources/patterns.md

@@ -1,269 +1,196 @@
 # Terreno Patterns & Best Practices
 
-Collection CRUD is local-first: the backend syncs a collection with `syncPlugin` and a `sync`
-config on `modelRouter`, and the frontend reads and writes it with `@terreno/syncdb/react`
-(`useQuery`, `useMutate`). Generated RTK Query hooks from `openApiSdk.ts` are only for routes
-that are not synced: auth (`/auth/me`), AI, feature flags, and custom request/response actions.
-
 ## Backend Patterns
 
 ### Model Definition
 
-A synced model uses a String `_id` (offline clients mint ids), `isDeletedPlugin` (via the app's
-default plugins), and `syncPlugin`. Types live in `src/types/models/`. Every field has a
-`description`.
-
 ```typescript
-import {syncPlugin} from "@terreno/api";
 import mongoose from "mongoose";
-import type {TodoDocument, TodoModel} from "../types/models/todoTypes";
-import {addDefaultPlugins} from "./modelPlugins";
+import { addDefaultPlugins } from "@terreno/api";
+
+interface TodoDocument extends mongoose.Document {
+  title: string;
+  completed: boolean;
+  ownerId: mongoose.Types.ObjectId;
+  created: Date;
+  updated: Date;
+}
+
+interface TodoModel extends mongoose.Model<TodoDocument> {
+  findByOwner(ownerId: string): Promise<TodoDocument[]>;
+}
 
 const todoSchema = new mongoose.Schema<TodoDocument, TodoModel>(
   {
-    _id: {
-      default: (): string => new mongoose.Types.ObjectId().toHexString(),
-      description: "The document id (String so offline sync clients can mint ids)",
-      type: String,
-    },
-    completed: {
-      default: false,
-      description: "Whether the todo item has been completed",
-      type: Boolean,
-    },
-    ownerId: {
-      description: "The user who owns this todo",
-      ref: "User",
-      required: true,
-      type: mongoose.Schema.Types.ObjectId,
-    },
-    title: {
-      description: "The title of the todo item",
-      required: true,
-      trim: true,
-      type: String,
-    },
+    title: { type: String, required: true, trim: true },
+    completed: { type: Boolean, default: false },
+    ownerId: { type: mongoose.Schema.Types.ObjectId, ref: "User", required: true },
   },
-  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+  {
+    strict: "throw",
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
 );
 
-// addDefaultPlugins applies createdUpdatedPlugin, isDeletedPlugin, findExactlyOne, findOneOrNone.
 addDefaultPlugins(todoSchema);
-// Stamps a per-stream _syncSeq on every write; required by the router's sync config.
-todoSchema.plugin(syncPlugin);
+
+todoSchema.statics.findByOwner = async function (ownerId: string) {
+  return this.find({ ownerId });
+};
 
 export const Todo = mongoose.model<TodoDocument, TodoModel>("Todo", todoSchema);
 ```
 
 ### Route Setup
 
-Use the three-argument `modelRouter` and register it on `TerrenoApp` together with `SyncApp`
-and `RealtimeApp`. Sync needs a MongoDB replica set (change streams).
-
 ```typescript
-import {modelRouter, OwnerQueryFilter, Permissions} from "@terreno/api";
-import {Todo} from "../models/todo";
-import type {UserDocument} from "../types/models/userTypes";
-
-export const todoRouter = modelRouter("/todos", Todo, {
-  permissions: {
-    create: [Permissions.IsAuthenticated],
-    delete: [Permissions.IsOwner],
-    list: [Permissions.IsAuthenticated],
-    read: [Permissions.IsOwner],
-    update: [Permissions.IsOwner],
-  },
-  preCreate: (body, req) => ({
-    ...body,
-    ownerId: (req.user as unknown as UserDocument)?._id,
-  }),
-  queryFields: ["completed", "ownerId"],
-  queryFilter: OwnerQueryFilter,
-  sort: "-created",
-  sync: {scope: {type: "owner"}},
-});
+import { Router } from "express";
+import { modelRouter, Permissions, OwnerQueryFilter } from "@terreno/api";
+import { Todo, TodoDocument } from "../models/todo";
+import { UserDocument } from "../models/user";
+
+export const addTodoRoutes = (router: Router) => {
+  router.use(
+    "/todos",
+    modelRouter(Todo, {
+      permissions: {
+        create: [Permissions.IsAuthenticated],
+        list: [Permissions.IsAuthenticated],
+        read: [Permissions.IsOwner],
+        update: [Permissions.IsOwner],
+        delete: [Permissions.IsOwner],
+      },
+      queryFields: ["completed"],
+      queryFilter: OwnerQueryFilter,
+      sort: "-created",
+      preCreate: (body, req) => ({
+        ...body,
+        ownerId: (req.user as UserDocument)?._id,
+      }),
+      postCreate: async (todo, req) => {
+        // Send notification, update stats, etc.
+        logger.info("Todo created", { todoId: todo._id });
+      },
+    })
+  );
+};
 ```
 
 ### Custom Endpoints
 
-Add non-CRUD endpoints as `collectionActions` or `instanceActions` on the same `modelRouter`,
-not with `router.post`. They get permissions, validation, and OpenAPI automatically.
-
 ```typescript
-import {APIError, modelRouter, Permissions, z} from "@terreno/api";
-
-export const todoRouter = modelRouter("/todos", Todo, {
-  // ...permissions, sync, and the rest from Route Setup
-  collectionActions: {
-    bulkComplete: {
-      body: z.object({ids: z.array(z.string()).min(1)}).strict(),
-      handler: async ({body, user}) => {
-        const result = await Todo.updateMany(
-          {_id: {$in: body.ids}, ownerId: user?._id},
-          {$set: {completed: true}}
-        );
-        return {matched: result.matchedCount, modified: result.modifiedCount};
-      },
-      method: "POST",
-      permissions: [Permissions.IsAuthenticated],
-    },
-  },
-  instanceActions: {
-    markComplete: {
-      handler: async ({doc}) => {
-        if (doc.completed) {
-          throw new APIError({status: 409, title: "Todo is already completed"});
-        }
-        doc.completed = true;
-        await doc.save();
-        return doc;
-      },
-      method: "POST",
-      permissions: [Permissions.IsOwner],
-    },
-  },
-});
+import { createOpenApiBuilder, APIError, authenticateMiddleware } from "@terreno/api";
+
+const toggleCompleteBuilder = createOpenApiBuilder()
+  .withTags(["Todos"])
+  .withSummary("Toggle todo completion status")
+  .withResponse(200, TodoSchema);
+
+router.post(
+  "/todos/:id/toggle",
+  authenticateMiddleware,
+  toggleCompleteBuilder.build(),
+  async (req, res, next) => {
+    try {
+      const todo = await Todo.findOneOrThrow({ _id: req.params.id });
+
+      if (!todo.ownerId.equals((req.user as UserDocument)._id)) {
+        throw new APIError({
+          status: 403,
+          title: "Forbidden",
+          detail: "You do not own this todo",
+        });
+      }
+
+      todo.completed = !todo.completed;
+      await todo.save();
+
+      res.json(todo);
+    } catch (error) {
+      next(error);
+    }
+  }
+);
 ```
 
 ## Frontend Patterns
 
 ### Screen with Data Fetching
 
-Synced collections are read from the local store with `useQuery` and written with `useMutate`.
-Writes apply immediately and sync through the durable outbox: there is no loading state per
-request, no `.unwrap()`, and no refetch after a mutation. Wrap the screen (or the app) in
-`SyncDbProvider`, and do not call `mutate` until `syncDb.start()` has resolved.
-
 ```typescript
-import {generateMutationId} from "@terreno/syncdb";
-import {SyncDbProvider, useMutate, useQuery} from "@terreno/syncdb/react";
-import {Box, Button, Card, CheckBox, Heading, IconButton, Text, TextField} from "@terreno/ui";
-import {DateTime} from "luxon";
-import type React from "react";
-import {useCallback, useState} from "react";
-import {useSyncDbReady} from "@/hooks/useSyncDbReady";
-import {syncDb} from "@/store/syncdb";
-
-interface Todo {
-  _id: string;
-  completed?: boolean;
-  created: string;
-  ownerId: string;
-  title: string;
-}
-
-const TodoList: React.FC = () => {
-  const isSyncDbReady = useSyncDbReady();
-  const [newTitle, setNewTitle] = useState<string>("");
-  const todos = useQuery<Todo>("todos", {sort: "-created"});
-  const {create, update, remove} = useMutate("todos");
-
+import React, { useCallback, useState } from "react";
+import { Box, Page, Text, Button, TextField, ScrollView } from "@terreno/ui";
+import { useMutate, useQuery } from "@terreno/syncdb/react";
+
+// `todos` is a synced collection (modelRouter `sync` config + `SYNC_COLLECTIONS`), so reads and
+// writes are local-first through @terreno/syncdb. Non-synced routes use the generated hooks in
+// `@/store/apiSdk` instead (see the form example below).
+const TodoScreen: React.FC = () => {
+  const [newTitle, setNewTitle] = useState("");
+  // Local reads never wait on the network; useSyncStatus() exposes online/queued/conflict state.
+  const todos = useQuery<Todo>("todos", { sort: "-created" });
+  const { create } = useMutate("todos");
+
+  // Writes apply locally right away and queue in the durable outbox until the server confirms.
   const handleCreate = useCallback((): void => {
-    const title = newTitle.trim();
-    if (!title || !isSyncDbReady) {
+    if (!newTitle.trim()) {
       return;
     }
-    // Mint the id locally so the optimistic row is addressable before the server acks it.
-    const id = generateMutationId();
-    create({data: {_id: id, completed: false, created: DateTime.now().toISO(), title}, id});
+    create({ data: { title: newTitle } });
     setNewTitle("");
-  }, [create, isSyncDbReady, newTitle]);
-
-  const handleToggle = useCallback(
-    (todo: Todo): void => {
-      update({data: {completed: !todo.completed}, id: todo._id});
-    },
-    [update]
-  );
-
-  const handleDelete = useCallback(
-    (id: string): void => {
-      remove({id});
-    },
-    [remove]
-  );
+  }, [newTitle, create]);
 
   return (
-    <Box gap={3} padding={4} testID="todos-screen">
-      <Heading size="lg">Todos</Heading>
-      <Card>
-        <Box gap={3}>
-          <TextField
-            onChange={setNewTitle}
-            onEnter={handleCreate}
-            placeholder="New todo"
-            testID="todos-title-input"
-            title="New Todo"
-            value={newTitle}
-          />
-          <Button
-            disabled={!isSyncDbReady || !newTitle.trim()}
-            iconName="plus"
-            onClick={handleCreate}
-            testID="todos-create-button"
-            text="Add Todo"
-          />
-        </Box>
-      </Card>
-      {todos.length === 0 ? <Text testID="todos-empty-state">No todos yet</Text> : null}
-      {todos.map((todo) => (
-        <Card key={todo._id} testID={`todo-item-${todo._id}`}>
-          <Box alignItems="center" direction="row" gap={2}>
-            <Box onClick={() => handleToggle(todo)} testID={`todo-toggle-${todo._id}`}>
-              <CheckBox selected={Boolean(todo.completed)} size="md" />
+    <Page navigation={undefined} title="Todos">
+      <ScrollView>
+        <Box padding={4} gap={3}>
+          <Box direction="row" gap={2}>
+            <Box flex={1}>
+              <TextField
+                placeholder="New todo..."
+                value={newTitle}
+                onChangeText={setNewTitle}
+              />
             </Box>
-            <Box flex="grow">
-              <Text>{todo.title}</Text>
-            </Box>
-            <IconButton
-              accessibilityLabel="Delete todo"
-              iconName="trash"
-              onClick={() => handleDelete(todo._id)}
-              testID={`todo-delete-${todo._id}`}
-              variant="destructive"
+            <Button
+              text="Add"
+              onClick={handleCreate}
+              disabled={!newTitle.trim()}
             />
           </Box>
-        </Card>
-      ))}
-    </Box>
+
+          {todos.map((todo) => (
+            <TodoItem key={todo.id} todo={todo} />
+          ))}
+        </Box>
+      </ScrollView>
+    </Page>
   );
 };
 
-const TodosScreen: React.FC = () => (
-  <SyncDbProvider client={syncDb}>
-    <TodoList />
-  </SyncDbProvider>
-);
-
-export default TodosScreen;
+export default TodoScreen;
 ```
 
-For large lists, render `useEntityIds` in the list and `useEntity` in each row, so a change to
-one row re-renders only that row. Running `terreno-syncdb-codegen` generates typed hooks such as
-`useTodo`, `useCreateTodo`, and `useUpdateTodo` in `store/syncDbSdk.ts`, which wrap the same
-calls.
-
 ### Form with Validation
 
-A form that calls a non-synced route uses the generated RTK Query mutation and `.unwrap()`.
-Here it updates the signed-in user's profile through `PATCH /auth/me`.
-
 ```typescript
-import {Box, Button, EmailField, TextField} from "@terreno/ui";
-import type React from "react";
-import {useCallback, useState} from "react";
-import {usePatchMeMutation} from "@/store/sdk";
+import React, { useCallback, useState } from "react";
+import { Box, Button, TextField, EmailField, Text } from "@terreno/ui";
+// Generated by `bun run api-sdk` (terreno-syncdb-codegen --api-out store/apiSdk.ts) from
+// the backend OpenAPI spec. Never edit apiSdk.ts by hand.
+import { usePostUsersMutation } from "@/store/apiSdk";
 
 interface FormErrors {
   name?: string;
   email?: string;
 }
 
-const ProfileForm: React.FC = () => {
-  const [name, setName] = useState<string>("");
-  const [email, setEmail] = useState<string>("");
+const CreateUserForm: React.FC = () => {
+  const [name, setName] = useState("");
+  const [email, setEmail] = useState("");
   const [errors, setErrors] = useState<FormErrors>({});
-  const [updateProfile, {isLoading}] = usePatchMeMutation();
+  const [createUser, { isLoading }] = usePostUsersMutation();
 
   const validate = useCallback((): boolean => {
     const newErrors: FormErrors = {};
@@ -282,43 +209,40 @@ const ProfileForm: React.FC = () => {
     return Object.keys(newErrors).length === 0;
   }, [name, email]);
 
-  const handleSubmit = useCallback(async (): Promise<void> => {
+  const handleSubmit = useCallback(async () => {
     if (!validate()) {
       return;
     }
 
     try {
-      await updateProfile({email, name}).unwrap();
-    } catch (error: unknown) {
-      const fields = (error as {data?: {fields?: FormErrors}}).data?.fields;
-      if (fields) {
-        setErrors(fields);
+      await createUser({ name, email }).unwrap();
+      // Success - navigate or show message
+    } catch (err: any) {
+      if (err.data?.fields) {
+        setErrors(err.data.fields);
       }
     }
-  }, [name, email, validate, updateProfile]);
+  }, [name, email, validate, createUser]);
 
   return (
-    <Box gap={3} padding={4}>
+    <Box padding={4} gap={3}>
       <TextField
-        errorText={errors.name}
-        onChange={setName}
-        testID="profile-name-input"
-        title="Name"
+        label="Name"
         value={name}
+        onChangeText={setName}
+        error={errors.name}
       />
       <EmailField
-        errorText={errors.email}
-        onChange={setEmail}
-        testID="profile-email-input"
-        title="Email"
+        label="Email"
         value={email}
+        onChangeText={setEmail}
+        error={errors.email}
       />
       <Button
-        fullWidth
-        loading={isLoading}
+        text="Create User"
         onClick={handleSubmit}
-        testID="profile-save-button"
-        text="Save"
+        loading={isLoading}
+        fullWidth
       />
     </Box>
   );
@@ -361,24 +285,19 @@ throw new APIError({
 
 ### Frontend
 
-A synced write does not return the server's answer to the caller. A rejected or conflicting
-mutation shows up in `useSyncStatus()` and `useConflicts()`; render the conflict UI from those
-hooks. Errors from
-non-synced RTK Query routes arrive on `.unwrap()`:
-
 ```typescript
 try {
   await someApiCall().unwrap();
-} catch (error: unknown) {
-  const data = (error as {data?: {detail?: string; fields?: Record<string, string>}}).data;
+} catch (err: any) {
   // Handle field-specific errors
-  if (data?.fields) {
-    setErrors(data.fields);
+  if (err.data?.fields) {
+    setErrors(err.data.fields);
     return;
   }
 
   // Handle general errors
-  toast.error(data?.detail ?? "An error occurred");
+  const message = err.data?.detail || err.message || "An error occurred";
+  toast.error(message);
 }
 ```
 

package/src/docs/resources/syncdb.md

@@ -1,30 +1,54 @@
 # @terreno/syncdb Documentation
 
-Local-first data layer for Terreno frontends. The on-device TinyBase store is the UI source of truth.
+Local-first data layer and request client for Terreno frontends. The on-device TinyBase store is
+the UI source of truth for synced collections; every other route goes through the request client
+and generated hooks. Since Terreno 58 there is no Redux and no `@terreno/rtk`.
 
 ## Key exports
 
-- `@terreno/syncdb`: `createSyncDb`, `betterAuthAdapter`, `wipeLocalData`, `listConflicts`
-- `@terreno/syncdb/react`: `SyncDbProvider`, `useQuery`, `useEntity`, `useMutate`, `useSyncStatus`, `useConflicts`
+- `@terreno/syncdb`: `createSyncDb`, `betterAuthAdapter`, `bridgeBetterAuthReactClient`, `wipeLocalData`, `listConflicts`
+- `@terreno/syncdb/react`: `SyncDbProvider`, `useQuery`, `useEntity`, `useMutate`, `useSyncStatus`, `useConflicts`, `ApiClientProvider`, `useApiQuery`, `useLazyApiQuery`, `useApiMutation`, `useSocketEvent`
+- `@terreno/syncdb/api`: `createApiClient` (auth, refresh-on-401, envelope unwrap, cache + tags)
+- `@terreno/syncdb/auth`: `createBetterAuthClient`, `SessionProvider`, `useSession`
+- `@terreno/syncdb/config`: `baseUrl`, `baseWebsocketsUrl`, `appHeaders`
+- `@terreno/syncdb/flags`: `useFeatureFlags`, `useTerrenoFeatureFlags`
+- `@terreno/syncdb/app`: `useUpgradeCheck`, `canOpenAdminPage`, `installDevConsoleLogger`, `useMCPTools`
 - `@terreno/syncdb/testing`: `createFakeTransport`
+- `terreno-syncdb-codegen` (bin): `--out store/syncDbSdk.ts` for collections, `--api-out store/apiSdk.ts` for typed request hooks
 
 ## Quick start
 
 ```typescript
-import {baseUrl} from "@terreno/rtk";
-import {betterAuthAdapter, createSyncDb} from "@terreno/syncdb";
-import {SyncDbProvider, useQuery, useMutate} from "@terreno/syncdb/react";
+import {betterAuthAdapter, bridgeBetterAuthReactClient, createSyncDb} from "@terreno/syncdb";
+import {createApiClient} from "@terreno/syncdb/api";
+import {createBetterAuthClient, useSession} from "@terreno/syncdb/auth";
+import {appHeaders, baseUrl} from "@terreno/syncdb/config";
+import {useMutate, useQuery} from "@terreno/syncdb/react";
+import {useGetAuthMeQuery} from "@/store/apiSdk";
 
-export const syncDb = createSyncDb({
-  authProvider: betterAuthAdapter(authClient),
+export const betterAuthClient = createBetterAuthClient({baseURL: baseUrl, scheme: "my-app"});
+export const authProvider = betterAuthAdapter(bridgeBetterAuthReactClient(betterAuthClient));
+
+export const syncDb = createSyncDb({authProvider, baseUrl, collections: ["todos"], name: "my-app"});
+export const apiClient = createApiClient({
+  authProvider,
   baseUrl,
-  collections: ["todos"],
-  name: "my-app",
+  credentials: "include",
+  headers: appHeaders,
 });
 
+// Root layout:
+// <SessionProvider authClient={betterAuthClient} syncDbs={[syncDb]}>
+//   <ApiClientProvider client={apiClient}>
+//     <SyncDbProvider client={syncDb}>...</SyncDbProvider>
+//   </ApiClientProvider>
+// </SessionProvider>
+
 // In a screen:
+const {userId, logout} = useSession();
 const todos = useQuery<Todo>("todos");
 const {create, update, remove} = useMutate("todos");
+const {data: me} = useGetAuthMeQuery(); // generated by terreno-syncdb-codegen --api-out
 ```
 
 ## Backend requirements
@@ -34,12 +58,16 @@ const {create, update, remove} = useMutate("todos");
 - `SyncApp` + `RealtimeApp` on the Express app
 - MongoDB replica set
 
-## What syncdb replaces
+## Synced vs. request routes
 
-Do **not** use RTK Query `useGetXQuery` / `usePostXMutation` for synced
-collections. Keep `bun run sdk` for non-synced routes such as auth/me and AI.
-Built-in admin String-`_id` CRUD uses windowed syncdb; admin RPC uses its
-host-bound fetch client; ObjectId compatibility CRUD remains RTK in Terreno 57.
+- Synced collections: `useQuery` / `useEntity` / `useMutate` (local-first). Never wrap them in
+  request hooks.
+- Every other route (`/auth/me`, modelRouter actions, AI, consents, announcements): generated hooks
+  in `store/apiSdk.ts` (`useGetAuthMeQuery`, `usePatchAuthMeMutation`, `useLazy…Query`). Regenerate
+  with `terreno-syncdb-codegen --schema http://localhost:4000/openapi.json --api-out store/apiSdk.ts`
+  (the app's `api-sdk` script) after backend changes. Never edit `apiSdk.ts` by hand.
+- Session: `SessionProvider` / `useSession()` from `@terreno/syncdb/auth`.
+- Admin: windowed syncdb for String-`_id` models; `AdminProvider`'s fetch client for the rest.
 
 ## Local MCP debugging
 
@@ -52,4 +80,4 @@ offline mode, clear events, and merge snapshots when the local MCP starts with
 
 Full reference: [docs/reference/syncdb.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/reference/syncdb.md)
 
-Migration: [docs/how-to/migrate-rtk-to-syncdb.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/how-to/migrate-rtk-to-syncdb.md)
+Upgrading from `@terreno/rtk`: [docs/how-to/migrate-rtk-to-syncdb.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/how-to/migrate-rtk-to-syncdb.md)

package/src/docs/templates/bootstrap/CLAUDE.template.md

@@ -20,7 +20,7 @@ cd {{appName}}-backend && bun run dev
 # Start frontend (port 8082)
 cd {{appName}}-frontend && bun run web
 
-# Regenerate SDK after backend changes
+# Regenerate store/apiSdk.ts after backend changes (backend running)
 cd {{appName}}-frontend && bun run sdk
 ```
 
@@ -29,7 +29,7 @@ cd {{appName}}-frontend && bun run sdk
 1. Create model in `{{appName}}-backend/src/models/`
 2. Create route in `{{appName}}-backend/src/api/`
 3. Register route in `{{appName}}-backend/src/server.ts`
-4. Regenerate SDK: `cd {{appName}}-frontend && bun run sdk`
+4. Regenerate API hooks: `cd {{appName}}-frontend && bun run sdk` (writes `store/apiSdk.ts`)
 5. Create screens in `{{appName}}-frontend/app/`
 
 ## Code Style

package/src/docs/templates/bootstrap/cursorrules.template.md

@@ -4,7 +4,7 @@ A full-stack application built with the Terreno framework.
 
 ## Project Structure
 
-- **{{appName}}-frontend/** - Expo/React Native frontend using @terreno/ui and @terreno/rtk
+- **{{appName}}-frontend/** - Expo/React Native frontend using @terreno/ui and @terreno/syncdb
 - **{{appName}}-backend/** - Express/Mongoose backend using @terreno/api
 
 ## Development
@@ -17,7 +17,7 @@ cd {{appName}}-backend && bun run dev    # Start backend on port 4000
 
 # Frontend
 cd {{appName}}-frontend && bun run web   # Start web frontend
-cd {{appName}}-frontend && bun run sdk   # Regenerate SDK after backend changes
+cd {{appName}}-frontend && bun run sdk   # Regenerate store/apiSdk.ts after backend changes
 ```
 
 ## Code Style
@@ -42,7 +42,7 @@ cd {{appName}}-frontend && bun run sdk   # Regenerate SDK after backend changes
 - Use functional components with `React.FC` type
 - Add explanatory comment above each `useEffect`
 - Wrap callbacks in `useCallback`
-- Use Redux Toolkit for state management
+- Use React context, local state, or `useStoredState` for app state (no Redux)
 
 ### Backend Conventions
 - Use `modelRouter` for CRUD endpoints
@@ -51,9 +51,11 @@ cd {{appName}}-frontend && bun run sdk   # Regenerate SDK after backend changes
 - Use `Model.findExactlyOne` or `Model.findOneOrNone` (not `Model.findOne`)
 
 ### Frontend Conventions
-- Use generated SDK hooks from `@/store/openApiSdk`
+- Use `@terreno/syncdb/react` hooks (`useQuery`, `useMutate`) for synced collection CRUD
+- Use generated hooks from `@/store/apiSdk` for non-synced routes only
+- Read the session with `useSession()` from `@terreno/syncdb/auth`
 - Use @terreno/ui components (Box, Page, Button, TextField, etc.)
-- Never modify `openApiSdk.ts` manually - regenerate with `bun run sdk`
+- Never modify `apiSdk.ts` manually - regenerate with `bun run sdk`
 
 ## AI Assistance