@terreno/agent-plugin 57.21.0 → 58.0.0-beta.2

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

@@ -2,18 +2,21 @@
 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, RTK Query generated
-  hooks for non-synced routes, admin's host-bound fetch client, auth, caching,
-  and SDK regeneration. Replaces direct fetch, axios, React Query, and SWR in
+  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.** Use syncdb
-for synced collection CRUD and generated RTK Query hooks for non-synced routes.
+**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).
 
@@ -28,9 +31,9 @@ Never call `axios`, raw `fetch`, React Query, or SWR from application screens.
 
 ```
 references/
-  auth-and-tokens.md     generateAuthSlice, login/logout, token refresh
-  realtime.md             Sockets, feature flags, server status
-  sdk-customization.md   injectEndpoints, cache tags, hand-maintained sdk.ts
+  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
@@ -44,15 +47,19 @@ references/
 
 ## Core Rules
 
-1. **Use syncdb hooks** (`useQuery`, `useEntity`, `useMutate`) for synced collection CRUD.
-2. **Use generated hooks** from `store/openApiSdk.ts` (or `store/sdk.ts`) for non-synced routes.
-3. **Never edit `openApiSdk.ts` manually** — regenerate with `generate-sdk`.
-4. **Never use `axios` or raw `fetch`** in app code. Framework-owned admin RPC
-   is the exception: `@terreno/admin-frontend` binds `adminRequest` from host
-   `credentials` / `getAuthHeaders`.
-5. **Do not add new admin `injectEndpoints`.** String-`_id` models with
-   `adminBroadcast` use windowed syncdb; ObjectId compatibility CRUD remains RTK
-   until Terreno 58 removes `useAdminApi` and the required `api` prop.
+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
 
@@ -71,12 +78,13 @@ const TodosScreen: React.FC = () => {
 ### 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: {title: "New todo", completed: false}});
+  create({data: {_id: generateMutationId(), title: "New todo", completed: false}});
 }, [create]);
 
 const handleToggle = useCallback((id: string, completed: boolean): void => {
@@ -84,47 +92,48 @@ const handleToggle = useCallback((id: string, completed: boolean): void => {
 }, [update]);
 ```
 
-### Auth
+### Non-synced route
 
 ```tsx
-import {generateAuthSlice} from "@terreno/rtk";
-import {terrenoApi} from "@/store/sdk";
+import {useGetAuthMeQuery, usePatchAuthMeMutation} from "@/store/apiSdk";
+
+const {data: me, isLoading} = useGetAuthMeQuery(undefined, {skip: !userId});
+const [updateMe, {isLoading: isSaving}] = usePatchAuthMeMutation();
+await updateMe({name}).unwrap();
+```
 
-const {authReducer, logout, middleware} = generateAuthSlice(terrenoApi);
+### Auth
 
-// In a component:
-import {useEmailLoginMutation} from "@/store/sdk";
-import {useSelectCurrentUserId} from "@terreno/rtk";
+```tsx
+import {useSession} from "@terreno/syncdb/auth";
 
-const [login] = useEmailLoginMutation();
-const userId = useSelectCurrentUserId();
+const {userId, isAuthenticated, isLoading, logout} = useSession();
 ```
 
 See `./references/auth-and-tokens.md` for the full auth flow.
 
-## Redux Store Setup
+## 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
-import {configureStore} from "@reduxjs/toolkit";
-import {generateAuthSlice} from "@terreno/rtk";
-import {terrenoApi} from "./sdk";
-
-const authSlice = generateAuthSlice(terrenoApi);
-
-const store = configureStore({
-  reducer: {
-    auth: authSlice.authReducer,
-    [terrenoApi.reducerPath]: terrenoApi.reducer,
-  },
-  middleware: (getDefault) =>
-    getDefault().concat(terrenoApi.middleware, ...authSlice.middleware),
-});
-
-export const {logout} = authSlice;
+// 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>
 ```
 
-See `example-frontend/store/index.ts` for persist and Sentry integration.
-
 ## Environment Variables
 
 | Variable | Purpose |
@@ -133,7 +142,7 @@ See `example-frontend/store/index.ts` for persist and Sentry integration.
 | `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 (from `@terreno/rtk`):
+Base URL resolution priority (`baseUrl` from `@terreno/syncdb/config`):
 
 1. `expo.extra.BASE_URL`
 2. `EXPO_PUBLIC_API_URL`
@@ -144,13 +153,13 @@ Never put server secrets in `EXPO_PUBLIC_*` variables.
 
 ## Error Handling
 
-RTK Query exposes errors on the hook result:
+Request hooks expose `ApiError` (`@terreno/syncdb/api`) on the result:
 
 ```tsx
-const {error, isError} = useGetMeQuery();
+const {error, isError} = useGetAuthMeQuery();
 
 if (isError) {
-  // error is FetchBaseQueryError | SerializedError
+  // error.status, error.data.title, error.data.detail; status 0 = network error or timeout
   console.error("Query failed", error);
 }
 ```
@@ -160,27 +169,29 @@ For mutations, use `.unwrap()`:
 ```tsx
 try {
   await updateMe({name}).unwrap();
-} catch (err) {
-  // Handle APIError-shaped responses from @terreno/api
-  console.error("Mutation failed", err);
+} catch (error) {
+  if (isApiError(error)) {
+    console.error("Mutation failed", error.data.title);
+  }
 }
 ```
 
-Use `isNetworkFetchError` from `@terreno/rtk` to detect connectivity issues in error UI.
+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 non-synced backend API change, run the `generate-sdk` skill. Synced
-collection CRUD does not belong in the OpenAPI SDK.
+After a backend API change, run the `generate-sdk` skill.
 
 ```bash
 # Backend running on :4000, then:
-cd example-frontend && bun run sdk
+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, non-synced `modelRouter` routes, and OpenAPI builder
-edits. Regenerate syncdb collection types/hooks with its codegen when a synced
-schema changes.
+Triggers: custom routes, modelRouter actions, non-synced `modelRouter` routes, and OpenAPI
+edits (`sdk`); synced schema or `sync` config changes (`sync-sdk`).
 
 ## Decision Tree
 
@@ -190,22 +201,22 @@ Need data in a Terreno app?
   |   \-- @terreno/syncdb hooks
   |
   |-- Non-synced API route?
-  |   \-- useGet*/usePost* from generated SDK
+  |   \-- useGet*/usePost* from store/apiSdk.ts
   |
   |-- Built-in admin?
   |   |-- String id + adminBroadcast -> windowed syncdb
-  |   |-- Framework RPC -> host-bound adminRequest
-  |   \-- ObjectId compatibility CRUD -> useAdminApi until Terreno 58
+  |   |-- Framework RPC -> AdminProvider adminRequest (useAdminRpc)
+  |   \-- ObjectId / API-only CRUD -> useAdminModelApi
   |
   |-- Login/logout?
   |   \-- references/auth-and-tokens.md
   |
-  |-- Realtime updates?
-  |   \-- references/realtime.md (useSocketConnection)
+  |-- Server push / feature flags?
+  |   \-- references/realtime.md (useSocketEvent, @terreno/syncdb/flags)
   |
   |-- Custom endpoint not in SDK?
   |   |-- Backend exists? -> generate-sdk first
-  |   \-- App-only extension? -> references/sdk-customization.md
+  |   \-- Route outside OpenAPI? -> references/sdk-customization.md (useApiQuery)
   |
   |-- Backend doesn't exist?
   |   \-- terreno-backend-api, then generate-sdk
@@ -237,10 +248,10 @@ fetch(url, {headers: {Authorization: `Bearer ${token}`}});
 **Right: a generated hook handles auth for a non-synced route**
 
 ```tsx
-const {data: profile} = useGetMeQuery();
+const {data: profile} = useGetAuthMeQuery();
 ```
 
-**Wrong: editing openApiSdk.ts**
+**Wrong: editing store/apiSdk.ts**
 
 ```tsx
 // Adding a new endpoint by hand
@@ -269,8 +280,9 @@ throw new APIError({status: 422, title: "Not a member"});
 ## Example Invocations
 
 - "How do I fetch todos?" → `useQuery("todos")` from `@terreno/syncdb/react`
-- "How do I handle login?" → `useEmailLoginMutation` + `generateAuthSlice`
-- "Should I use React Query?" → No — syncdb for collections, generated RTK hooks for non-synced routes
-- "API calls return 401" → Check token refresh; see auth-and-tokens.md
+- "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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Terreno Data Fetching"
-  short_description: "RTK Query generated hooks, auth tokens, and realtime sockets for Terreno apps — never axios or raw fetch"
-  default_prompt: "Use $terreno-data-fetching to implement API calls with generated RTK Query hooks, auth, and caching in a Terreno app."
+  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."

package/skills/terreno-data-fetching/references/auth-and-tokens.md

@@ -1,93 +1,89 @@
 # Auth and Tokens — Terreno
 
-## generateAuthSlice
+Session state lives in `@terreno/syncdb/auth`. There is no Redux store. Reference:
+`docs/reference/syncdb.md#auth`, `example-frontend/lib/betterAuth.ts`, `app/login.tsx`.
 
-`generateAuthSlice(api)` from `@terreno/rtk` creates:
-
-- `authReducer` — tracks `userId`, `error`, `lastTokenRefreshTimestamp`
-- `logout` action — clears tokens from secure storage
-- `middleware` — stores tokens on login, removes on logout
-- Built-in endpoints: `emailLogin`, `emailSignUp`, `googleLogin`, `resetPassword`
-
-## Login
+## Better Auth client
 
 ```tsx
-import {useEmailLoginMutation} from "@/store/sdk";
-import {useSelectCurrentUserId} from "@terreno/rtk";
-
-const [login, {isLoading, error}] = useEmailLoginMutation();
-
-await login({email, password}).unwrap();
-// Tokens stored automatically; setUserId dispatched
+// lib/betterAuth.ts
+import {createBetterAuthClient} from "@terreno/syncdb/auth";
+import {baseUrl} from "@terreno/syncdb/config";
+
+export const betterAuthClient = createBetterAuthClient({
+  baseURL: baseUrl,
+  scheme: "myapp",
+  storagePrefix: "myapp",
+});
 ```
 
-## Logout
+Storage is `expo-secure-store` on native and AsyncStorage on web. Never store tokens in
+plain AsyncStorage on native or in `EXPO_PUBLIC_*` env vars.
 
-```tsx
-import {useAppDispatch, logout} from "../store/index.ts";
+## Session provider
 
-const dispatch = useAppDispatch();
-dispatch(logout());
-// Clears AUTH_TOKEN and REFRESH_TOKEN from storage
+```tsx
+<SessionProvider authClient={betterAuthClient} syncDbs={[syncDb]} onLogout={() => apiClient.reset()}>
+  <App />
+</SessionProvider>
 ```
 
-## Token storage
-
-- **Native:** `expo-secure-store` (encrypted)
-- **Web:** `@react-native-async-storage/async-storage` (SSR-safe wrapper)
-
-Never store tokens in plain AsyncStorage on native or in `EXPO_PUBLIC_*` env vars.
+```tsx
+import {useSession} from "@terreno/syncdb/auth";
 
-## Token refresh
+const {userId, user, isAuthenticated, isLoading, error, logout, refresh} = useSession();
+```
 
-`emptyApi` from `@terreno/rtk` automatically:
+## Login
 
-- Refreshes access token when < 2 minutes from expiry
-- Retries failed requests after 401 with refreshed token
-- Uses a mutex to prevent concurrent refresh storms
+```tsx
+const {refresh} = useSession();
 
-No manual refresh logic needed in app code.
+const result = await betterAuthClient.signIn.email({email, password});
+if (!result.error) {
+  await refresh(); // resolve userId now instead of waiting for the session atom
+}
+```
 
-## Better Auth (optional)
+Use `SocialLoginButton` from `@terreno/ui` with `betterAuthClient.signIn.social({provider})`
+for OAuth.
 
-For apps using Better Auth instead of JWT/Passport:
+## Logout
 
 ```tsx
-import {createBetterAuthClient, generateBetterAuthSlice, setTokenSource} from "@terreno/rtk";
-import {betterAuthAdapter, bridgeBetterAuthReactClient} from "@terreno/syncdb";
+const {logout} = useSession();
+await logout();
+```
 
-const authClient = createBetterAuthClient({
-  baseURL: process.env.EXPO_PUBLIC_API_URL,
-  scheme: "myapp", // deep-link scheme, required
-});
+`logout()` signs out each `syncDbs` client first (wiping local rows when created with
+`wipeOnSignOut: true`), then the auth server, then runs `onLogout`.
 
-// {reducer, middleware, actions, slice, syncSession}; mount reducer at `betterAuth`
-const betterAuth = generateBetterAuthSlice({authClient});
+## Token refresh
 
-// One token source for syncdb and every rtk consumer, registered once at startup
-export const authProvider = betterAuthAdapter(bridgeBetterAuthReactClient(authClient));
-setTokenSource(authProvider);
-```
+`betterAuthAdapter(bridgeBetterAuthReactClient(betterAuthClient))` is the shared
+`AuthProvider` for `createSyncDb` and `createApiClient`. The request client adds
+`Authorization: Bearer`, and on a 401 calls `authProvider.refresh()` once and retries.
+No manual refresh logic in app code. Code outside the client (SSE streams, `AdminProvider`
+`getAuthHeaders`) reads `authProvider.getToken()`.
 
-With the source registered, `emptySplitApi` sends the Better Auth token, sends no
-`authorization` header when there is none, and logs out only after a 401 survives one
-`refresh()`. Do not fork the base query to read the session. Without `setTokenSource`, rtk
-uses the JWT tokens in storage (`jwtTokenSource`).
+## JWT backends (legacy)
 
-Use `SocialLoginButton` from `@terreno/ui` for OAuth providers.
+Apps on `@terreno/api` JWT routes use `jwtAuthAdapter` as both the `authProvider` and the
+`SessionProvider` `source`, plus `useJwtAuth({adapter})` for `login`, `signup`,
+`googleLogin`, `resetPassword`. It refreshes when under 130 s remain and on a 401, with one
+shared refresh in flight. See `docs/reference/syncdb.md#jwt-auth-legacy`.
 
 ## Current user
 
 ```tsx
-import {useSelectCurrentUserId} from "@terreno/rtk";
-import {useReadProfile} from "@/hooks/useReadProfile"; // app-specific
+import {useGetAuthMeQuery} from "@/store/apiSdk";
 
-const userId = useSelectCurrentUserId();
-const {data: profile} = useReadProfile(); // GET /auth/me via sdk.ts
+const {userId} = useSession();
+const {data: me} = useGetAuthMeQuery(undefined, {skip: !userId});
 ```
 
 ## Protected routes
 
-Gate navigation on `userId` in root `_layout.tsx`. Redirect unauthenticated users to `/login`.
-
-For admin routes, also check `user.admin === true` and redirect non-admins.
+Gate navigation on `useSession().userId` in root `_layout.tsx`. Redirect unauthenticated
+users to `/login`. For admin routes, check `canOpenAdminPage({admin: me?.admin, permissions:
+me?.permissions})` from `@terreno/syncdb/app`.

package/skills/terreno-data-fetching/references/realtime.md

@@ -1,45 +1,50 @@
 # Realtime — Terreno
 
-## Realtime sockets
+The syncdb client owns the app's only socket. Do not open a second one.
+
+## Server push events
 
 ```tsx
-import {useSocketConnection, getAuthToken} from "@terreno/rtk";
+import {useSocketEvent} from "@terreno/syncdb/react";
 
-const {socket, isSocketConnected} = useSocketConnection({
-  baseUrl: "ws://localhost:4000",
-  shouldConnect: !!userId,
-  getAuthToken: () => getAuthToken(),
+useSocketEvent("announcementPublished", (payload) => {
+  console.info("announcement", payload);
 });
 ```
 
-Sockets auto-reconnect and refresh auth on token rotation.
+Inside `SyncDbProvider` the hook uses that client; above it, pass `{client: syncDb}`, or
+`{client: null}` to listen to nothing. Outside React: `syncDb.onSocketEvent(event, handler)`
+returns an unsubscribe.
 
 ## Feature flags
 
 ```tsx
-import {useTerrenoFeatureFlags} from "@terreno/rtk";
+import {OpenFeatureProvider} from "@openfeature/react-sdk";
+import {useTerrenoFeatureFlags} from "@terreno/syncdb/flags";
 
-useTerrenoFeatureFlags(terrenoApi, {
-  skip: !userId,
-  socket,
-  userId,
-});
+const {userId} = useSession();
+useTerrenoFeatureFlags({client: apiClient, skip: !userId, socket: syncDb, userId});
+return <OpenFeatureProvider domain="feature-flags">{children}</OpenFeatureProvider>;
 ```
 
-Wrap children in `OpenFeatureProvider` (see `example-frontend/app/_layout.tsx`).
+Flags load through the request client and refetch when the server pushes
+`featureFlagsChanged` on the sync socket. Screens can read flat accessors with
+`useFeatureFlags({skip, socket, userId})`. See `example-frontend/app/_layout.tsx` and
+`docs/reference/feature-flags.md`.
 
-## Server status
+## Sync status
 
 ```tsx
-import {useServerStatus} from "@terreno/rtk";
+import {useSyncStatus} from "@terreno/syncdb/react";
 
-const {isServerReachable} = useServerStatus();
+const {isOnline, queuedCount, conflictCount, failedCount, paused} = useSyncStatus();
 ```
 
-Use to show degraded UI when the backend is unreachable.
+Render `SyncStatusBanner` / `OfflineBanner` from `@terreno/ui` with these values.
 
 ## Realtime model updates
 
-`modelRouter` `realtime` (RTK cache-patching via `realtimeList` / `realtimeDocument`) is **deprecated** and **will be removed in Terreno 58**. Use `sync` on `modelRouter` with `@terreno/syncdb`. `RealtimeApp` stays as the socket host.
-
-Do not add new `realtimeList` / `realtimeDocument` wiring. After adding `sync` to a backend model, use syncdb hooks on the client.
+Live collection updates come from `sync` on the backend `modelRouter`; read them with
+`useQuery` / `useEntity`. `RealtimeApp` hosts the socket for `sync:delta` and app events.
+Terreno 58 removed `modelRouter` `realtime` and every `@terreno/rtk` socket helper
+(`useSocketConnection`, `realtimeList`, `realtimeDocument`, `useRealtimeDebug`).

package/skills/terreno-data-fetching/references/sdk-customization.md

@@ -4,81 +4,52 @@
 
 | File | Editable? | Purpose |
 |------|-----------|---------|
-| `store/openApiSdk.ts` | **Never** | Auto-generated hooks from OpenAPI |
-| `store/sdk.ts` | **Yes** | Extensions, cache tags, custom endpoints |
-| `openapi-config.ts` | **Yes** | Codegen configuration |
+| `store/apiSdk.ts` | **Never** | Typed hooks for every non-synced OpenAPI operation (`--api-out`) |
+| `store/syncDbSdk.ts` | **Never** | `SYNC_COLLECTIONS` + collection hooks (`--out`) |
+| `store/apiClient.ts` | **Yes** | `createApiClient` (auth, headers, `onError`) |
+| `syncdb-codegen.json` | **Yes** | Codegen config (`excludePaths`, per-collection `overrides`) |
 
-## injectEndpoints
+## Generated hooks
 
-Add app-specific endpoints that are not in the OpenAPI spec (rare — prefer backend routes):
+Names follow the old RTK codegen rule: camelCased `operationId`, otherwise method + path with
+`{param}` as `By<Param>` (`PATCH /gpt/histories/{id}` → `usePatchGptHistoriesByIdMutation`).
+Each operation also gets `<Name>Args`, `<Name>Res`, and `<name>Request(arg)` for
+`apiClient.request(...)`. Tags come from the operation's OpenAPI tags.
 
 ```tsx
-import {openapi} from "./openApiSdk";
-
-export const terrenoApi = openapi
-  .injectEndpoints({
-    endpoints: (build) => ({
-      getMe: build.query({
-        query: () => "/auth/me",
-        providesTags: ["profile"],
-      }),
-      patchMe: build.mutation({
-        query: (body) => ({
-          url: "/auth/me",
-          method: "PATCH",
-          body,
-        }),
-        invalidatesTags: ["profile"],
-      }),
-    }),
-  })
-  .enhanceEndpoints({
-    addTagTypes: ["todos", "users", "profile"],
-  });
+import {useGetAuthMeQuery, usePatchAuthMeMutation} from "@/store/apiSdk";
 ```
 
-Import hooks from `@/store/sdk`, not `@/store/openApiSdk` directly.
-
-## Cache tags
+## Routes outside OpenAPI
 
-Use `enhanceEndpoints` to add tag types, then `providesTags` / `invalidatesTags` in injected endpoints:
+Prefer documenting the route in OpenAPI and regenerating. When that is not possible, call it
+directly through the request client:
 
 ```tsx
-import {invalidatesIdTags, providesIdTags} from "@terreno/rtk";
-
-// In injectEndpoints:
-listItems: build.query({
-  query: (params) => ({url: "/items", params}),
-  providesTags: providesIdTags("items"),
-}),
-createItem: build.mutation({
-  query: (body) => ({url: "/items", method: "POST", body}),
-  invalidatesTags: invalidatesIdTags("items"),
-}),
+import {useApiMutation, useApiQuery, useLazyApiQuery} from "@terreno/syncdb/react";
+
+const {data, isLoading, refetch} = useApiQuery<Report>(
+  {url: "/reports/summary", params: {range}},
+  {providesTags: ["reports"], skip: !userId}
+);
+
+const [rebuild, {isLoading: isRebuilding}] = useApiMutation<RebuildBody, Report>(
+  (body) => ({body, method: "POST", url: "/reports/rebuild"}),
+  {invalidatesTags: ["reports"]}
+);
+await rebuild({range}).unwrap();
 ```
 
-## Codegen config
-
-```typescript
-// openapi-config.ts
-const config: ConfigFile = {
-  apiFile: "@terreno/rtk",
-  apiImport: "emptySplitApi",
-  outputFile: "./store/openApiSdk.ts",
-  schemaFile: "http://localhost:4000/openapi.json",
-  hooks: true,
-  tag: true,
-  flattenArg: true,
-};
-```
+## Cache tags
 
-Override schema URL with `OPENAPI_URL` env var when needed.
+Queries register `providesTags`; mutations `invalidatesTags`. Imperatively:
+`apiClient.invalidateTags(["reports"])`. `apiClient.reset()` clears the cache (done on logout
+via `SessionProvider` `onLogout`). Synced collections have no request cache; their data is local.
 
 ## Workflow after backend change
 
 1. Start backend (`bun run backend:dev`)
-2. Run `cd example-frontend && bun run sdk`
-3. Import new hooks from `@/store/sdk`
-4. If the endpoint needs custom cache behavior, update `sdk.ts`
+2. Run `cd example-frontend && bun run sdk` (and `bun run sync-sdk` for synced schema changes)
+3. Import new hooks from `@/store/apiSdk` (or `@/store/syncDbSdk`)
 
 See the `generate-sdk` skill for the full procedure.

package/skills/terreno-ui/SKILL.md

@@ -6,8 +6,8 @@ description: >-
   layout, forms, tables, modals, feedback, or navigation chrome. Covers
   component selection, Box/Page patterns, theme props, and when NOT to use raw
   React Native primitives. Lifecycle composition: Grow for UI shape, Pick for
-  implementation, Roast for UI conformance review. Not for backend APIs, RTK
-  Query, or Expo Router setup.
+  implementation, Roast for UI conformance review. Not for backend APIs, data
+  fetching (syncdb), or Expo Router setup.
 ---
 # @terreno/ui
 

package/skills/terreno-ui/references/data-display.md

@@ -42,6 +42,8 @@ Sizes: `sm`, `md`, `lg`, `xl`, `2xl` (responsive web/mobile values).
 />
 ```
 
+Column `width` is optional. Omit it and the column sizes itself from its title and sampled content, then grows to fill the table; a set `width` is always kept. See `docs/reference/ui.md` (DataTable column widths).
+
 Column types: `text`, `date`, `number`, `boolean`, `custom`.
 
 For admin tables, prefer `AdminModelTable` from `@terreno/admin-frontend`.