@terreno/mcp 0.21.0

package/dist/docs/versioned/0.20.0/reference/ui.md

@@ -0,0 +1,418 @@
+# @terreno/ui
+
+React Native UI component library (88+ components). Layout (Box, Page, Card), forms (TextField, SelectField), display (Text, DataTable), actions (Button), feedback (Modal, Toast), and theming via TerrenoProvider.
+
+## Key exports
+
+- Layout: `Box`, `Page`, `SplitPage`, `Card`
+- Forms: `TextField`, `SelectField`, `DateTimeField`, `CheckBox`
+- Display: `Text`, `Heading`, `Badge`, `DataTable`
+- Actions: `Button`, `IconButton`, `Link`
+- Feedback: `Spinner`, `Modal`, `Toast`
+- Authentication: `SocialLoginButton`, `LoginScreen`, `SignUpScreen`
+- Theming: `TerrenoProvider`, `useTheme`
+- **Type re-exports:** `StyleProp`, `ViewStyle` (re-exported from react-native to avoid version conflicts)
+
+## Type Re-exports
+
+@terreno/ui re-exports commonly-used React Native types to help consumers avoid version conflicts:
+
+``````typescript
+import {StyleProp, ViewStyle} from "@terreno/ui";
+
+// Use these instead of importing from react-native directly
+const customStyle: StyleProp<ViewStyle> = {
+  flex: 1,
+  backgroundColor: "#fff",
+};
+``````
+
+**Benefits:**
+- Avoids version mismatches between your app's react-native and @terreno/ui's react-native
+- Ensures type compatibility when passing styles to @terreno/ui components
+- Simplifies imports (one package instead of two)
+
+## Component Behaviors
+
+### Button Layout Behavior
+
+Buttons automatically size to their content unless `fullWidth` is specified:
+
+``````typescript
+// Button takes only the space it needs
+<Box direction="column">
+  <Button text="Save" onClick={handleSave} />  {/* Auto-sized */}
+</Box>
+
+// Button stretches to full width
+<Box direction="column">
+  <Button text="Save" onClick={handleSave} fullWidth />  {/* Full width */}
+</Box>
+``````
+
+Internally, Button sets `alignSelf: 'flex-start'` when `fullWidth={false}` to prevent stretching in column layouts.
+
+## Authentication Components
+
+### SocialLoginButton
+
+Branded social login buttons for OAuth authentication with Google, GitHub, and Apple.
+
+``````typescript
+import {SocialLoginButton} from "@terreno/ui";
+import {authClient} from "@/store/authClient";
+
+<SocialLoginButton
+  provider="google"  // "google" | "github" | "apple"
+  variant="primary"  // "primary" | "outline"
+  onPress={async () => {
+    await authClient.signIn.social({
+      provider: "google",
+      callbackURL: "yourapp://auth/callback",
+    });
+  }}
+  loading={isLoading}
+  fullWidth
+/>
+``````
+
+**Features:**
+- Proper brand colors for each provider (follows brand guidelines)
+- Built-in icons (FontAwesome 6)
+- Primary and outline variants
+- Loading states with spinner
+- Automatic text: "Continue with {Provider}"
+
+### LoginScreen
+
+Complete login screen with email/password and optional social providers.
+
+``````typescript
+import {LoginScreen} from "@terreno/ui";
+import {authClient} from "@/store/authClient";
+
+<LoginScreen
+  onEmailLogin={async ({email, password}) => {
+    await authClient.signIn.email({email, password});
+  }}
+  onSocialLogin={async (provider) => {
+    await authClient.signIn.social({provider, callbackURL: "yourapp://auth"});
+  }}
+  socialProviders={["google", "github", "apple"]}
+  onForgotPassword={() => navigation.navigate("ForgotPassword")}
+  onSignUp={() => navigation.navigate("SignUp")}
+/>
+``````
+
+### SignUpScreen
+
+Complete signup screen with email/password and optional social providers.
+
+``````typescript
+import {SignUpScreen} from "@terreno/ui";
+import {authClient} from "@/store/authClient";
+
+<SignUpScreen
+  onEmailSignUp={async ({email, password, name}) => {
+    await authClient.signUp.email({email, password, name});
+  }}
+  onSocialLogin={async (provider) => {
+    await authClient.signIn.social({provider, callbackURL: "yourapp://auth"});
+  }}
+  socialProviders={["google", "github"]}
+  onSignIn={() => navigation.navigate("Login")}
+  requireName
+  requireTermsAcceptance
+/>
+``````
+
+**Learn more:** [Configure Better Auth](../how-to/configure-better-auth.md)
+
+## Testing Utilities
+
+@terreno/ui provides test helpers for writing component tests with @testing-library/react-native.
+
+### renderWithTheme
+
+Wraps components in ThemeProvider for testing.
+
+``````typescript
+import {renderWithTheme} from "@terreno/ui";
+import {describe, it, expect} from "bun:test";
+
+describe("MyComponent", () => {
+  it("renders correctly", () => {
+    const {getByTestId} = renderWithTheme(<MyComponent testID="my-comp" />);
+    expect(getByTestID("my-comp")).toBeTruthy();
+  });
+});
+``````
+
+**Why:** Most @terreno/ui components require ThemeProvider context to access theme values.
+
+### createCommonMocks
+
+Creates mock functions for common component callbacks.
+
+``````typescript
+import {createCommonMocks} from "@terreno/ui";
+
+const mocks = createCommonMocks();
+// Returns: {onBlur, onChange, onEnter, onFocus, onIconClick, onSubmitEditing}
+
+<TextField
+  value="test"
+  onChange={mocks.onChange}
+  onBlur={mocks.onBlur}
+  onFocus={mocks.onFocus}
+/>
+
+// Assert mock was called
+expect(mocks.onChange).toHaveBeenCalledWith("new value");
+``````
+
+### setupComponentTest / teardownComponentTest
+
+Lifecycle helpers for test setup and cleanup.
+
+``````typescript
+import {setupComponentTest, teardownComponentTest} from "@terreno/ui";
+
+describe("MyForm", () => {
+  let mocks;
+
+  beforeEach(() => {
+    mocks = setupComponentTest(); // Returns createCommonMocks()
+  });
+
+  afterEach(() => {
+    teardownComponentTest(); // No-op in Bun (auto-cleanup)
+  });
+
+  it("submits form", () => {
+    // Test with mocks
+  });
+});
+``````
+
+## Date Utilities
+
+Luxon-based helpers for date comparison and formatting.
+
+``````typescript
+import {
+  isToday,
+  isTomorrow,
+  isYesterday,
+  isThisYear,
+  isWithinWeek,
+  getIsoDate,
+} from "@terreno/ui";
+
+const date = DateTime.now();
+
+if (isToday(date)) console.log("Today!");
+if (isTomorrow(date)) console.log("Tomorrow!");
+if (isYesterday(date)) console.log("Yesterday!");
+if (isThisYear(date)) console.log("This year!");
+if (isWithinWeek(date)) console.log("Within 7 days!");
+
+// Convert to ISO date string
+const isoString = getIsoDate(date); // "2026-02-15"
+``````
+
+### Timezone Utilities
+
+``````typescript
+import {getTimezoneOptions} from "@terreno/ui";
+
+// Get USA timezones only
+const usaTimezones = getTimezoneOptions("usa");
+// Returns: [{label: "Pacific Time", value: "America/Los_Angeles"}, ...]
+
+// Get worldwide timezones
+const allTimezones = getTimezoneOptions("worldwide");
+// Returns: [{label: "UTC", value: "UTC"}, {label: "New York", value: "America/New_York"}, ...]
+``````
+
+**Use case:** Populate SelectField with timezone choices.
+
+## Address Utilities
+
+Google Places API integration helpers for address handling.
+
+### formatAddress
+
+``````typescript
+import {formatAddress} from "@terreno/ui";
+
+const address = {
+  street: "123 Main St",
+  city: "San Francisco",
+  state: "CA",
+  zipCode: "94102",
+};
+
+const formatted = formatAddress(address);
+// "123 Main St, San Francisco, CA 94102"
+``````
+
+### processAddressComponents
+
+Parses Google Places API address_components into structured data.
+
+``````typescript
+import {processAddressComponents} from "@terreno/ui";
+
+// From Google Places API response
+const components = place.address_components;
+
+const parsed = processAddressComponents(components);
+// Returns: {street, city, state, zipCode, country, county}
+``````
+
+### findAddressComponent
+
+``````typescript
+import {findAddressComponent} from "@terreno/ui";
+
+const city = findAddressComponent(components, "locality");
+const state = findAddressComponent(components, "administrative_area_level_1", "short_name");
+``````
+
+### Validation
+
+``````typescript
+import {isValidGoogleApiKey, formattedCountyCode} from "@terreno/ui";
+
+if (!isValidGoogleApiKey(apiKey)) {
+  console.error("Invalid Google API key");
+}
+
+// Format US county codes
+const county = formattedCountyCode("6075"); // "6075" (Santa Cruz County, CA)
+``````
+
+## Media Query Helpers
+
+Responsive design utilities for breakpoints and device detection.
+
+``````typescript
+import {
+  mediaQuery,
+  mediaQueryLargerThan,
+  mediaQuerySmallerThan,
+  isMobileDevice,
+} from "@terreno/ui";
+
+// Check if matches breakpoint
+if (mediaQuery("md")) {
+  console.log("Medium or larger");
+}
+
+// Greater than breakpoint
+if (mediaQueryLargerThan("sm")) {
+  console.log("Larger than small");
+}
+
+// Smaller than breakpoint
+if (mediaQuerySmallerThan("lg")) {
+  console.log("Smaller than large");
+}
+
+// Detect mobile
+if (isMobileDevice()) {
+  console.log("Running on mobile device");
+}
+``````
+
+**Breakpoints:**
+- `sm`: 640px
+- `md`: 768px
+- `lg`: 1024px
+- `xl`: 1280px
+
+## Icons
+
+### FontAwesome Icons
+
+All 2000+ FontAwesome 6 icons available via the `Icon` component:
+
+``````typescript
+import {Icon} from "@terreno/ui";
+
+<Icon name="check" size={24} color="primary" />
+<Icon name="user" size={32} color="secondary" />
+<Icon name="chevron-right" size={16} color="neutral700" />
+``````
+
+### Custom SVG Icons
+
+@terreno/ui includes custom status icons:
+
+``````typescript
+import {MobileIcon, OnlineIcon, OfflineIcon, OutOfOfficeIcon} from "@terreno/ui";
+
+<MobileIcon width={20} height={20} fill="#007AFF" />
+<OnlineIcon width={16} height={16} />
+<OfflineIcon width={16} height={16} />
+<OutOfOfficeIcon width={16} height={16} />
+``````
+
+**Use case:** User status indicators, device type badges.
+
+## Style Utilities
+
+### Unifier Class
+
+Color manipulation helper:
+
+``````typescript
+import {Unifier} from "@terreno/ui";
+
+// Darken/lighten colors
+const darkColor = Unifier.changeColorLuminance("#007AFF", -0.2); // Darker
+const lightColor = Unifier.changeColorLuminance("#007AFF", 0.2); // Lighter
+``````
+
+### Style Helpers
+
+``````typescript
+import {identity, concat, fromClassName, toggle, binding, union} from "@terreno/ui";
+
+// Compose style objects
+const styles = concat(baseStyles, conditionalStyles);
+
+// Toggle styles
+const buttonStyles = toggle(isPressed, pressedStyles, defaultStyles);
+``````
+
+**Note:** Most use cases are better served by Box props (`padding`, `color`, etc.).
+
+## Environment Variables
+
+@terreno/ui components do not require environment variables. All configuration is done at runtime via:
+
+- **TerrenoProvider props** — Theme customization, error handlers, base URL
+- **Theme hooks** — `useTheme()`, `setTheme()`, `setPrimitives()`
+- **Component props** — Direct prop overrides for individual components
+
+**Example configuration:**
+
+``````typescript
+import {TerrenoProvider} from "@terreno/ui";
+
+<TerrenoProvider
+  baseUrl="https://api.example.com"
+  theme={{
+    surface: {primary: "secondary500"},
+  }}
+  onError={(error) => console.error(error)}
+>
+  {children}
+</TerrenoProvider>
+``````
+
+## Related Documentation
+
+See the [ui package source](../../ui/src/) and [.cursor/rules/ui/](../../.cursor/rules/ui/) for props and conventions.

package/dist/docs/versioned/0.20.0/tasks/admin-only.md

@@ -0,0 +1,221 @@
+# Task List: Admin-Only — Serve Admin SPA From a Terreno Backend
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+See: `docs/implementationPlans/admin-only.md` for full plan.
+
+## Phase 0: admin-frontend prop split (prerequisite — verified blocker)
+
+- [ ] **Task 0.1**: Split `baseUrl` → `apiBase` + `routeBase` across admin-frontend
+  - Description: Add optional `apiBase` and `routeBase` props alongside the existing `baseUrl` to every exported admin-frontend component. Internally resolve `const apiBase = props.apiBase ?? props.baseUrl; const routeBase = props.routeBase ?? props.baseUrl;`. Replace each occurrence: `useAdminConfig(api, baseUrl)` → `useAdminConfig(api, apiBase)`; `useAdminApi(api, baseUrl, modelName)` → `useAdminApi(api, apiBase, modelName)`; every `router.push(\`${baseUrl}/...\`)` and `href: \`${baseUrl}/...\`` → use `routeBase` instead.
+  - Files: `admin-frontend/src/AdminModelList.tsx`, `AdminModelTable.tsx`, `AdminModelForm.tsx`, `AdminRefField.tsx`, `AdminScriptList.tsx`, `AdminVersionConfig.tsx`, `ConfigurationScreen.tsx`, `useAdminConfig.tsx`, `useAdminApi.ts`, `AdminScriptRunModal.tsx` (if it references baseUrl)
+  - Depends on: none
+  - Acceptance: `bun run admin-frontend:lint` + `bun run admin-frontend:compile` pass. Type-check passes.
+
+- [ ] **Task 0.2**: Tests for prop split
+  - Description: Add a focused test asserting that when `apiBase="/admin"` + `routeBase="/console"` are passed, `useAdminConfig` is called with `/admin` and `router.push` is invoked with `/console/${modelName}`. Also assert backward-compat: `baseUrl="/admin"` alone still works (both internally default to `/admin`).
+  - Files: `admin-frontend/src/AdminModelList.test.tsx`, `AdminModelTable.test.tsx`
+  - Depends on: 0.1
+  - Acceptance: `bun run admin-frontend:test` passes with new assertions.
+
+- [ ] **Task 0.3**: Verify embedded admin still works
+  - Description: Run `example-frontend` against `example-backend`. Log in as admin, navigate to `/admin`, click through a model. Verify no regression. No code change expected — this is a verification step.
+  - Files: (manual)
+  - Depends on: 0.1
+  - Acceptance: All embedded admin flows in example-frontend render and function identically to pre-Phase 0.
+
+## Phase 1: Package scaffolding
+
+- [ ] **Task 1.1**: Create `admin-spa/` workspace package files
+  - Description: Create `package.json` (`@terreno/admin-spa`, version 0.13.0, deps mirror needed runtime: `@terreno/admin-frontend`, `@terreno/rtk`, `@terreno/ui`, `expo`, `expo-router`, `react`, `react-native-web`, `redux-persist`, `better-auth`; peer dep `@terreno/api`; dev deps mirror `example-frontend`). Add `tsconfig.json` (extends Expo preset, covers `app/`, `store/`, `components/`), `tsconfig.server.json` (covers `src/`, outputs `src/dist/`), `biome.jsonc` and `bunfig.toml` copied from `admin-frontend`, `babel.config.js` and `metro.config.js` copied from `example-frontend` (with workspace path adjustments), `app.json` with `web.output: "static"` and `extra.BASE_URL: "__SAME_ORIGIN__"`.
+  - Files: `admin-spa/package.json`, `admin-spa/tsconfig.json`, `admin-spa/tsconfig.server.json`, `admin-spa/biome.jsonc`, `admin-spa/bunfig.toml`, `admin-spa/babel.config.js`, `admin-spa/metro.config.js`, `admin-spa/app.json`, `admin-spa/.gitignore` (must include `dist/`, `store/openApiSdk.ts`, `src/dist/`)
+  - Depends on: none
+  - Acceptance: `bun install` from root succeeds; `bun run --filter '@terreno/admin-spa' compile` is a no-op (succeeds with no source yet).
+
+- [ ] **Task 1.2**: Register workspace in root and add scripts
+  - Description: Add `"admin-spa"` to `workspaces` array in root `package.json`. Add `admin-spa:compile`, `admin-spa:lint`, `admin-spa:test`, `admin-spa:build`, `admin-spa:sdk` scripts mirroring the admin-backend/admin-frontend convention.
+  - Files: `package.json` (root)
+  - Depends on: 1.1
+  - Acceptance: `bun install` resolves admin-spa; `bun run admin-spa:lint` runs (even with no source).
+
+- [ ] **Task 1.3**: Stub server-side plugin entry
+  - Description: Create `src/index.ts` exporting `AdminSpaServeApp` (stub class implementing `TerrenoPlugin` with empty `register()`). Create `src/appConfig.ts` with `AdminSpaAppConfig` interface and `DEFAULT_APP_CONFIG`. Run `tsc -p tsconfig.server.json` and verify `src/dist/` is produced.
+  - Files: `admin-spa/src/index.ts`, `admin-spa/src/appConfig.ts`
+  - Depends on: 1.1
+  - Acceptance: `bun run --filter '@terreno/admin-spa' compile` outputs `src/dist/index.js` and `src/dist/appConfig.js`.
+
+- [ ] **Task 1.4**: Stub Expo Router app entry
+  - Description: Create minimal `app/_layout.tsx` (just `<Stack/>`) and `app/index.tsx` rendering a `<Box>Hello admin</Box>` from `@terreno/ui`. Goal: verify the static export pipeline works end-to-end before adding real logic.
+  - Files: `admin-spa/app/_layout.tsx`, `admin-spa/app/index.tsx`
+  - Depends on: 1.1
+  - Acceptance: `bun run --filter '@terreno/admin-spa' build:web` produces `dist/index.html`, `dist/_expo/...`, no errors. Open `dist/index.html` in a browser → "Hello admin" renders.
+
+## Phase 2: Same-origin BASE_URL support
+
+- [ ] **Task 2.1**: Add `__SAME_ORIGIN__` sentinel to `@terreno/rtk`
+  - Description: Add `export const SAME_ORIGIN_SENTINEL = "__SAME_ORIGIN__";` to `rtk/src/constants.ts`. Modify `resolveBaseUrls` signature to accept optional `windowOrigin?: string`. When `baseFromExtra === SAME_ORIGIN_SENTINEL` and `windowOrigin` (or `globalThis.location?.origin`) is set, return `{baseUrl: origin, baseTasksUrl: `${origin}/tasks`, baseWebsocketsUrl: `${origin.replace(/^http/, "ws")}/`}`. Module-level call passes `globalThis.location?.origin` (with safe `typeof` check).
+  - Files: `rtk/src/constants.ts`
+  - Depends on: none
+  - Acceptance: Existing tests pass; new sentinel-aware path returns expected URLs.
+
+- [ ] **Task 2.2**: Tests for same-origin sentinel
+  - Description: Add tests to `rtk/src/constants.test.ts` covering: (a) sentinel + `windowOrigin: "https://api.example.com"` → `https://...` + `wss://...`; (b) sentinel + `windowOrigin: "http://localhost:4000"` → `http://...` + `ws://...`; (c) sentinel + no window origin → falls back to existing resolution; (d) non-sentinel BASE_URL is unchanged; (e) sentinel + isDev=true behaves the same as production for the sentinel path.
+  - Files: `rtk/src/constants.test.ts`
+  - Depends on: 2.1
+  - Acceptance: `bun run rtk:test` passes including new cases.
+
+## Phase 3: Express plugin
+
+- [ ] **Task 3.1**: Implement `AdminSpaServeApp.register()`
+  - Description: Implement `src/serve.ts`: resolve `basePath` (default `/console`), `distDir` (default `path.resolve(__dirname, "../../dist")` so it works from `src/dist/serve.js`), merged `appConfig`. Register three Express handlers: `express.static` for `_expo/` and `assets/` with `{immutable: true, maxAge: "365d"}`, `GET ${basePath}/app-config.json` returning JSON with `Cache-Control: no-store`, `GET ${basePath}{/*splat}` returning `index.html` with `Cache-Control: no-store`. Log at info level on mount.
+  - Files: `admin-spa/src/serve.ts`, `admin-spa/src/index.ts` (export)
+  - Depends on: 1.3
+  - Acceptance: `bun run admin-spa:compile` produces `src/dist/serve.js`; manual import from Node ESM works.
+
+- [ ] **Task 3.2**: Plugin unit tests
+  - Description: Add `src/serve.test.ts` using `supertest`. Create a tmpdir with stub `index.html` ("STUB-SPA"), `_expo/static/js/web/foo.abc123.js` ("CONTENT"), and `assets/foo.png` (any bytes). Construct an Express app and register the plugin with `distDir` pointing at the tmpdir. Cases: `GET /console/` → 200 + STUB-SPA + `Cache-Control: no-store`; `GET /console/users` → 200 + STUB-SPA (fallback); `GET /console/users/abc123` → 200 + STUB-SPA; `GET /console/_expo/static/js/web/foo.abc123.js` → 200 + CONTENT + cache headers; `GET /console/app-config.json` → 200 + JSON with `brandName: "Terreno Admin"` (default) + `Cache-Control: no-store`; `GET /console/app-config.json` with custom appConfig → returns merged config; `GET /unrelated` → 404 (plugin doesn't catch outside `basePath`); custom `basePath: "/admin-ui"` works.
+  - Files: `admin-spa/src/serve.test.ts`
+  - Depends on: 3.1
+  - Acceptance: `bun run admin-spa:test` passes all cases.
+
+## Phase 4: SPA — gates and auth
+
+- [ ] **Task 4.1**: AppConfigGate component
+  - Description: Create `components/AppConfigGate.tsx`. Uses React context to expose `AdminSpaAppConfig`. On mount, fetches `./app-config.json` (relative to current URL — so `/console/app-config.json` when mounted at `/console`). Defines defaults to merge with response. Renders a centered `<Spinner>` with `testID="admin-spa-app-config-loading"` while loading. Errors → renders a `<Text>` with retry button. Exposes `useAppConfig()` hook.
+  - Files: `admin-spa/components/AppConfigGate.tsx`
+  - Depends on: 1.4, 3.1
+  - Acceptance: Build succeeds; importing `useAppConfig` outside the gate throws a clear error.
+
+- [ ] **Task 4.2**: StoreProvider component (replaces "factory function" pattern)
+  - Description: Create `components/StoreProvider.tsx`. Reads `useAppConfig()`. Inside the component body, memo-builds `authClient = createAuthClient({baseURL: window.location.origin, basePath: appConfig.authBasePath ?? "/api/auth"})` using `better-auth/react` **directly** (NOT `@terreno/rtk`'s factory — that one is RN-targeted with the expo plugin). Builds `{betterAuthReducer, middleware, selectors} = generateBetterAuthSlice(authClient)`, then `store = configureStore({reducer: {betterAuth: betterAuthReducer, [openapi.reducerPath]: openapi.reducer}, middleware: (gdm) => gdm().concat(openapi.middleware, ...middleware)})`, then `persistor = persistStore(store)`. Wraps children: `<Provider store={store}><PersistGate loading={<Spinner testID="admin-spa-persist-loading"/>} persistor={persistor}>{children}</PersistGate></Provider>`. The `loading` prop is **required** — without it, AdminGate flashes the login screen during rehydration.
+  - Files: `admin-spa/components/StoreProvider.tsx`, `admin-spa/store/sdk.ts` (re-exports `emptySplitApi as openapi` from `@terreno/rtk` with tag types)
+  - Depends on: 4.1, 6.1
+  - Acceptance: Build succeeds; type-check passes; no `expo-secure-store` import surfaces in the bundle (since this is web-only).
+
+- [ ] **Task 4.3**: AdminGate component
+  - Description: Create `components/AdminGate.tsx`. Wraps children. On mount, calls `authClient.getSession()`. Uses `useSelectIsAuthenticated`. Renders spinner with `testID="admin-spa-admin-gate-loading"` while loading. If unauth and not on `/login`, `router.replace("/login")`. If auth + `user.admin !== true` and not on `/forbidden`, `router.replace("/forbidden")`. If auth + admin and on `/login` or `/forbidden`, `router.replace("/")`. Otherwise pass through.
+  - Files: `admin-spa/components/AdminGate.tsx`
+  - Depends on: 4.2
+  - Acceptance: Build succeeds; gate logic verifiable via unit test of selector behavior (`bun test`).
+
+- [ ] **Task 4.4**: Login screen
+  - Description: Create `app/login.tsx`. Reads `useAppConfig().providers`. Renders form with `TextField` (email) + `TextField` (password, type="password") + `Button` ("Sign in") calling `authClient.signIn.email({email, password})`. For each provider in `providers` that isn't `"email"`, renders a `SocialLoginButton`. Handles loading, error display. On success, `router.replace("/")`. testIDs as listed in IP.
+  - Files: `admin-spa/app/login.tsx`
+  - Depends on: 4.3
+  - Acceptance: Rendering the SPA logged-out shows the login form; clicking submit attempts the better-auth signIn (verifiable by mock in unit test).
+
+- [ ] **Task 4.5**: Forbidden screen + signout
+  - Description: Create `app/forbidden.tsx`. Renders `<Page>` with heading "Admins only" and explanation text. Includes a "Sign out" button calling `authClient.signOut()` then `router.replace("/login")`.
+  - Files: `admin-spa/app/forbidden.tsx`
+  - Depends on: 4.3
+  - Acceptance: Build succeeds; testID on screen root.
+
+- [ ] **Task 4.6**: Root layout assembly (correct provider order)
+  - Description: Update `app/_layout.tsx`. Order: `<AppConfigGate><StoreProvider><TerrenoProvider><AdminGate><Stack screenOptions={{headerShown: false}}>...</Stack></AdminGate></TerrenoProvider></StoreProvider></AppConfigGate>`. AppConfigGate is outermost because it has no Redux dependency and its result is needed to build the store. StoreProvider includes Provider + PersistGate. TerrenoProvider is inside Provider so theme hooks can read store state. AdminGate is innermost so it sees fully-hydrated state.
+  - Files: `admin-spa/app/_layout.tsx`
+  - Depends on: 4.1, 4.2, 4.3, 4.4, 4.5
+  - Acceptance: `bun run admin-spa:build` succeeds with no Metro errors. Sequential render: loading splash → (rehydrating) spinner → (unauth) login OR (admin) model list. No login flash for authenticated admins.
+
+## Phase 5: Wire admin screens
+
+All screens pass `apiBase={appConfig.adminApiBasePath ?? "/admin"}` AND `routeBase=""` so navigation stays inside the SPA's `/console` root. Depends on Phase 0.
+
+- [ ] **Task 5.1**: Model list screen
+  - Description: `app/index.tsx` renders `<AdminModelList api={terrenoApi} apiBase={apiBase} routeBase={routeBase} />`. Get values from `useAppConfig()`: `const apiBase = appConfig.adminApiBasePath ?? "/admin"; const routeBase = "";`.
+  - Files: `admin-spa/app/index.tsx`
+  - Depends on: 4.6, 0.1
+  - Acceptance: After login, model list renders models from `${apiBase}/config`. Clicking a model card calls `router.push("/${modelName}")` (relative to SPA root), NOT `/admin/${modelName}`.
+
+- [ ] **Task 5.2**: Model table + form routes
+  - Description: Create `app/[model]/_layout.tsx` (`<Stack/>`), `app/[model]/index.tsx` (renders `<AdminModelTable>`), `app/[model]/[id].tsx` (renders `<AdminModelForm id={id}>`), `app/[model]/create.tsx` (renders `<AdminModelForm>`). Use `useLocalSearchParams()` for params. Handle the `__scripts` and `version-config` sentinels like example-frontend does.
+  - Files: `admin-spa/app/[model]/_layout.tsx`, `admin-spa/app/[model]/index.tsx`, `admin-spa/app/[model]/[id].tsx`, `admin-spa/app/[model]/create.tsx`
+  - Depends on: 5.1
+  - Acceptance: Navigating to `/console/Users` shows the table; clicking a row opens the form.
+
+- [ ] **Task 5.3**: Configuration + scripts + version-config screens
+  - Description: Create `app/configuration.tsx`, `app/scripts.tsx`, `app/version-config.tsx` wrapping the corresponding `@terreno/admin-frontend` screens (`ConfigurationScreen`, `AdminScriptList`, `AdminVersionConfig`).
+  - Files: `admin-spa/app/configuration.tsx`, `admin-spa/app/scripts.tsx`, `admin-spa/app/version-config.tsx`
+  - Depends on: 5.1
+  - Acceptance: Each screen renders without errors.
+
+- [ ] **Task 5.4**: Not-found + Expo Router conventions
+  - Description: Create `app/+not-found.tsx` rendering a friendly 404 with link back to `/`. Add `app/+html.tsx` if needed for static export head config (favicon, viewport).
+  - Files: `admin-spa/app/+not-found.tsx`, `admin-spa/app/+html.tsx`
+  - Depends on: 4.6
+  - Acceptance: Visiting `/console/nonexistent` shows the 404 screen.
+
+## Phase 6: SDK glue (no codegen by default)
+
+Admin endpoints are runtime-injected by `admin-frontend/src/useAdminApi.ts` — codegen is unnecessary for the admin flow itself.
+
+- [ ] **Task 6.1**: Hand-written `store/sdk.ts`
+  - Description: Create `store/sdk.ts` that re-exports `emptySplitApi as openapi` from `@terreno/rtk` and uses `.enhanceEndpoints({addTagTypes: ["admin-models", "admin-version-config", "admin-scripts", "profile"]})`. Export `const terrenoApi = openapi` for consumers.
+  - Files: `admin-spa/store/sdk.ts`
+  - Depends on: 1.1
+  - Acceptance: `bun run --filter '@terreno/admin-spa' compile` passes; importing `terrenoApi` from `store/sdk` works in app code.
+
+- [ ] **Task 6.2 (optional)**: Codegen config for consumers wanting extended SDKs
+  - Description: Create `openapi-config.ts` pointing at `http://localhost:4000/openapi.json`. Document in README as optional — not part of the standard build.
+  - Files: `admin-spa/openapi-config.ts`, `admin-spa/README.md` section
+  - Depends on: 6.1
+  - Acceptance: Running `bun run --filter '@terreno/admin-spa' sdk` against a live backend regenerates `store/openApiSdk.ts` with all endpoints.
+
+## Phase 7: Example backend integration
+
+- [ ] **Task 7.1**: Add admin-spa dep to example-backend
+  - Description: Add `"@terreno/admin-spa": "workspace:*"` to `example-backend/package.json` dependencies.
+  - Files: `example-backend/package.json`
+  - Depends on: 1.2
+  - Acceptance: `bun install` resolves.
+
+- [ ] **Task 7.2**: Register plugin in example-backend
+  - Description: In `example-backend/src/server.ts`, import `AdminSpaServeApp`. Register it (gated on `process.env.ADMIN_SPA_ENABLED === "true"`) with `basePath: "/console"`, `appConfig: {brandName: "Terreno Example", primaryColor: "#7C3AED", providers: ["email", "google"]}`.
+  - Files: `example-backend/src/server.ts`
+  - Depends on: 7.1, 3.1
+  - Acceptance: With `ADMIN_SPA_ENABLED=true AUTH_PROVIDER=better-auth bun run backend:dev`, server starts and logs "Admin SPA mounted at /console/".
+
+- [ ] **Task 7.3**: Manual smoke test
+  - Description: Start the backend with the env flags above. Open `http://localhost:4000/console/`. Confirm: (a) login screen renders with brand name "Terreno Example"; (b) sign in with an admin user → redirects to admin list; (c) clicking a model opens the table; (d) editing a row works; (e) `app-config.json` GET returns the configured shape; (f) non-admin user → forbidden screen. Document any gaps found.
+  - Files: (manual)
+  - Depends on: 7.2, 5.x complete
+  - Acceptance: All six checks pass.
+
+## Phase 8: Docs and rules
+
+- [ ] **Task 8.1**: README for admin-spa
+  - Description: Write `admin-spa/README.md`. Sections: overview, install, register with backend, customizing app-config, regenerating SDK, comparison with embedded admin-frontend usage.
+  - Files: `admin-spa/README.md`
+  - Depends on: 7.3
+  - Acceptance: Reading the README is sufficient for a new consumer to add admin to their backend.
+
+- [ ] **Task 8.2**: rulesync rule file
+  - Description: Author `.claude/rules/admin-spa/00-admin-spa.md` matching the shape of `.claude/rules/admin-frontend/00-admin-frontend.md`. Run `bun run rules` to regenerate `rulesync.jsonc` artifacts. Verify the rule appears in any AI consumer config files generated.
+  - Files: `.claude/rules/admin-spa/00-admin-spa.md`, plus regenerated rulesync artifacts
+  - Depends on: 8.1
+  - Acceptance: `bun run rules:check` passes (no diff after a clean regen).
+
+- [ ] **Task 8.3**: Update CLAUDE.local.md and admin-backend README
+  - Description: Add admin-spa to the packages list in `CLAUDE.local.md`. Add a "Standalone admin SPA" pointer to `admin-backend/README.md`.
+  - Files: `CLAUDE.local.md`, `admin-backend/README.md`
+  - Depends on: 8.1
+  - Acceptance: Both files mention admin-spa and reference the IP.
+
+- [ ] **Task 8.5**: Publish CI job
+  - Description: Add an `admin-spa` publish job to `.github/workflows/publish-on-tag.yml` mirroring the existing 8 publish jobs. Job must: `bun install` → `bun run admin-spa:build` → `bun run admin-spa:compile` → `bun publish --filter '@terreno/admin-spa'`. Without this, tagged releases publish an empty `dist/`.
+  - Files: `.github/workflows/publish-on-tag.yml`
+  - Depends on: 8.1
+  - Acceptance: Dry-run the workflow on a feature branch; verify the tarball contains `src/dist/`, `dist/index.html`, and at least one file in `dist/_expo/`.
+
+- [ ] **Task 8.6**: CI smoke test
+  - Description: New job (or extension of existing E2E workflow). Boots example-backend with `ADMIN_SPA_ENABLED=true AUTH_PROVIDER=better-auth` after running `bun run --filter '@terreno/admin-spa' build:web`. curl `/console/`, `/console/app-config.json`, and one `/console/_expo/static/js/web/*.js` asset. Assert 200s + correct cache headers. Catches path-rewrite regressions in CI.
+  - Files: `.github/workflows/admin-spa-smoke.yml` (new) or update an existing test workflow
+  - Depends on: 7.2, 3.1
+  - Acceptance: Workflow passes on a clean run; mutating the rewrite list in `serve.ts` to omit `_expo` causes a CI failure.
+
+## Optional Phases
+
+- [ ] **Task 9.1 (optional)**: Playwright E2E
+  - Description: Add `e2e/admin-spa.spec.ts` to example-frontend with three tests: anonymous user sees login screen, admin can log in and view model list, non-admin gets forbidden screen.
+  - Files: `example-frontend/e2e/admin-spa.spec.ts`, plus testIDs already added in Phase 4
+  - Depends on: 7.3
+  - Acceptance: `bun run --filter '@terreno/example-frontend' e2e -- admin-spa.spec.ts` passes locally with backend running.