@terreno/agent-plugin 0.0.0-stage → 57.21.0

package/skills/terreno-test-setup/references/backend.md

@@ -0,0 +1,131 @@
+# Backend test setup
+
+Bun's test runner plus `@terreno/test`: in-memory MongoDB, canonical auth env, quiet logs, a
+Sentry mock, and supertest helpers.
+
+## 1. Install
+
+```bash
+cd backend
+bun add -d @terreno/test@<same version as @terreno/api> supertest @types/supertest
+```
+
+`mongoose` is a peer dependency and is already in a Terreno backend. `mongodb-memory-server`
+downloads a `mongod` binary on first use (Bun blocks its postinstall by default; the first test
+run downloads it instead, which can take a minute).
+
+## 2. Preload
+
+`backend/bunfig.toml`:
+
+```toml
+[test]
+preload = ["./src/tests/bunSetup.ts"]
+root = "./src"
+```
+
+`backend/src/tests/bunSetup.ts` — one file: SDK mocks first (if any), then the Mongo preload:
+
+```typescript
+import {registerBackendPreload, registerSendGridMock} from "@terreno/test";
+
+// Only for SDKs the app imports (a fresh create-terreno-app backend imports none; skip these).
+export const sendGrid = registerSendGridMock();
+
+registerBackendPreload({
+  onBeforeEach: () => {
+    sendGrid.reset();
+    // Keys the app reads that must start every test unset.
+    Reflect.deleteProperty(process.env, "SENDGRID_API_KEY");
+  },
+  testEnv: {
+    extra: {APP_URL: "http://localhost:8082"},
+    tokenIssuer: "<app>.test",
+  },
+});
+```
+
+What the preload does:
+
+| When | Effect |
+|------|--------|
+| once per run | starts one `mongodb-memory-server` `mongod` (or connects to `TERRENO_TEST_MONGODB_URI`), mocks `@sentry/bun`, silences Winston/console |
+| `beforeEach` | resets `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRET`, `NODE_ENV=test`, `TZ=UTC`, plus `testEnv.extra`; runs `onBeforeEach` |
+| `afterEach` | resets the system clock, clears mock calls, restores `spyOn` spies, re-applies the env |
+
+- It does **not** wipe collections. Tests delete what they read (see `terreno-backend-tests`).
+- A cold `mongod` start can take 20s+; the launch timeout defaults to 60s
+  (`TERRENO_TEST_MONGO_LAUNCH_TIMEOUT_MS` to change it). The first run also downloads the
+  `mongod` binary.
+- Some lines still print (`debug: No options.openApi provided...` when a test builds a
+  `TerrenoApp`, request logs). They are harmless.
+- Change streams, transactions, or `SyncApp` under test need a replica set: set
+  `process.env.TERRENO_TEST_USE_REPLSET = "true"` at the top of the preload.
+  `registerBackendPreload({useTransactions: true})` also wraps each test in a transaction
+  that is aborted afterwards (no cleanup code, but every DB call is serialized through one
+  session); use it only when cleanup cost dominates the suite.
+- `registerSimpleMongoPreload` is the lighter variant the Terreno packages use; prefer
+  `registerBackendPreload` in apps.
+
+## 3. Third-party services
+
+`mock.module` replaces a module for the whole `bun test` process, so a mock registered inside
+one test file leaks into every later file. Register SDK mocks **only in the preload**, export
+the handles so tests can assert on them, and `reset()` each in `onBeforeEach` (the preload's
+`afterEach` clears call history but not stored state such as GCS objects or queued tasks).
+
+| Registrar | Module |
+|-----------|--------|
+| `registerSendGridMock` | `@sendgrid/mail` |
+| `registerTwilioMock` | `twilio` |
+| `registerExpoPushMock` | `expo-server-sdk` |
+| `registerCloudTasksMock` | `@google-cloud/tasks` |
+| `registerGcsMock` | `@google-cloud/storage` |
+| `registerGoogleAuthMock` | `google-auth-library` |
+| `registerTerrenoNotifierMocks` | `sendToSlack` / `sendToZoom` / `sendToGoogleChat` from `@terreno/api` |
+
+The AI SDK needs no module mock: pass `createMockLanguageModel()` to `AIService` (see
+`terreno-backend-tests`). Prefer constructor injection over a module mock when the app already
+accepts a client (for example `@terreno/comms` providers).
+
+## 4. First test
+
+`backend/src/api/users.test.ts` — proves the preload, Mongo, and supertest work:
+
+```typescript
+import {describe, expect, it} from "bun:test";
+import {TerrenoApp} from "@terreno/api";
+import supertest from "supertest";
+import {User} from "../models/user";
+import {userRouter} from "./users";
+
+const buildApp = () =>
+  new TerrenoApp({skipListen: true, userModel: User as never}).register(userRouter).build();
+
+describe("users", () => {
+  it("rejects anonymous list requests", async () => {
+    const res = await supertest(buildApp()).get("/users");
+    expect(res.status).toBe(401);
+  });
+});
+```
+
+Build a `TerrenoApp` with only the routers under test instead of calling the app's `start()`:
+`start()` connects to the dev database and registers every plugin.
+
+## CI
+
+```json
+"scripts": {
+  "test": "bun test",
+  "test:ci": "bun test",
+  "test:shard": "terreno-test-shard",
+  "test:hygiene": "terreno-test-hygiene --root src"
+}
+```
+
+- Sharding: `bun run test:shard --shard $INDEX/$TOTAL` in a CI matrix; `--list` prints a
+  shard's files; flags after `--` go to `bun test` (e.g. `-- --timeout 30000`).
+- Hygiene: run `bun run test:hygiene --update-baseline` once to record existing violations,
+  commit the baseline, then run `bun run test:hygiene` in CI so only new ones fail.
+- Unit jobs need no services: the in-memory `mongod` runs inside the job.

package/skills/terreno-test-setup/references/frontend.md

@@ -0,0 +1,169 @@
+# Frontend test setup
+
+Two layers: **unit/component tests** run in Bun with React Native mocked (fast, no device), and
+**web E2E** runs the real app in Chromium with Playwright.
+
+## Unit tests (Bun + React Native Testing Library)
+
+### 1. Install
+
+```bash
+cd frontend
+bun add -d @terreno/test@<same version as @terreno/ui> @testing-library/react-native@^13 \
+  react-test-renderer@<exact react version>
+```
+
+- Pin React Native Testing Library to **13**. Version 14 makes `render` async and drops
+  `react-test-renderer`; `renderWithTerreno` targets 13, and unpinned installs get 14 (tests
+  then fail with `findByText is not a function`).
+- `react-test-renderer` must match `react` exactly (both `19.2.3` today). Each run prints
+  `react-test-renderer is deprecated`; that warning is expected with RNTL 13.
+- `@terreno/test` also brings its backend dependencies (`mongodb-memory-server`, `express`);
+  they are only loaded by backend tests.
+
+### 2. Preload
+
+`frontend/bunfig.toml`:
+
+```toml
+[test]
+preload = ["./tests/testPreload.ts"]
+coveragePathIgnorePatterns = ["**/*.test.ts", "**/*.test.tsx", "tests/**", "store/openApiSdk.ts"]
+```
+
+`frontend/tests/testPreload.ts`:
+
+```typescript
+import {registerExpoTestEnvironment} from "@terreno/test/expo/registerExpoTestEnvironment";
+
+registerExpoTestEnvironment({
+  expoConfig: {extra: {}, scheme: "<app scheme from app.json>"},
+});
+```
+
+It mocks `react-native` (Bun cannot parse its Flow sources), the common `expo-*` modules,
+`expo-router`, `@expo/vector-icons`, reanimated, gesture handler, SVG, AsyncStorage, NetInfo,
+and SecureStore; serves images and fonts as asset stubs; sets `__DEV__`,
+`IS_REACT_ACT_ENVIRONMENT`, `TZ`, and `EXPO_OS`. After each test it restores spies, empties
+stored tokens, and resets `__DEV__`.
+
+Options when the defaults do not fit:
+
+| Need | Option |
+|------|--------|
+| A module should load for real | `skip: ["expo-sqlite"]` |
+| App-specific native module | `overrides: {"react-native-maps": () => ({MapView: () => null})}` |
+| Android / web `Platform.OS` | `platform: "android"` (default `"ios"`) |
+| Fixed clock in every test | `fixedNow: "2024-06-01T10:30:00.000Z"` |
+| A package ships its own nested `react-native` | `nestedPackagePrefixes: ["some-lib/node_modules/"]` |
+
+Put any further app-wide `mock.module` calls (e.g. a partial `@/store/sdk` mock) in a second
+preload file listed **after** `testPreload.ts`, and load the real module there with
+`await import(...)` — a static import would evaluate before React Native is mocked.
+
+### 3. First test
+
+`frontend/components/Greeting.test.tsx`:
+
+```tsx
+import {describe, expect, it} from "bun:test";
+import {renderWithTerreno} from "@terreno/test/expo/renderWithTerreno";
+import {Greeting} from "./Greeting";
+
+describe("Greeting", () => {
+  it("shows the user's name", async () => {
+    const {findByText} = renderWithTerreno(<Greeting name="Ada" />);
+    expect(await findByText("Hello, Ada")).toBeTruthy();
+  });
+});
+```
+
+`renderWithTerreno(ui, {store?, theme?})` wraps the tree in `TerrenoProvider` (and a Redux
+`Provider` when `store` is passed; needs `react-redux`).
+
+Done when `cd frontend && bun test` passes.
+
+## Playwright web E2E
+
+### 1. Install
+
+```bash
+cd frontend
+bun add -d @playwright/test
+bunx playwright install --with-deps chromium
+```
+
+E2E needs a **replica-set** `mongod` (the backend's sync and realtime use change streams):
+
+```bash
+mongod --replSet rs0 --port 27017 --bind_ip 127.0.0.1 --dbpath ./.devdata/mongo &
+mongosh --quiet --eval 'try { rs.status() } catch { rs.initiate({_id: "rs0", members: [{_id: 0, host: "127.0.0.1:27017"}]}) }'
+```
+
+### 2. Config
+
+`frontend/playwright.config.ts`:
+
+```typescript
+import {defineConfig, devices} from "@playwright/test";
+
+export default defineConfig({
+  projects: [
+    {name: "setup", testMatch: /auth\.setup\.ts/},
+    {dependencies: ["setup"], name: "chromium", use: {...devices["Desktop Chrome"]}},
+  ],
+  testDir: "./e2e",
+  use: {baseURL: "http://localhost:8082", trace: "retain-on-failure"},
+  webServer: [
+    {
+      command: "bun run --cwd ../backend src/index.ts",
+      env: {MONGO_URI: process.env.MONGO_URI ?? "mongodb://127.0.0.1/<app>-e2e?replicaSet=rs0", PORT: "4000"},
+      reuseExistingServer: !process.env.CI,
+      timeout: 120_000,
+      url: "http://localhost:4000/health",
+    },
+    {
+      command: "bunx expo start --web --port 8082",
+      env: {EXPO_PUBLIC_API_URL: "http://localhost:4000"},
+      reuseExistingServer: !process.env.CI,
+      timeout: 180_000,
+      url: "http://localhost:8082",
+    },
+  ],
+});
+```
+
+### 3. Layout
+
+```
+e2e/
+  fixtures/testUsers.ts   # TEST_USER, ADMIN_USER: {email, name, password}
+  helpers/login.ts        # loginAs(page, user = TEST_USER)
+  auth.setup.ts           # creates the users through the API before any spec runs
+  <feature>.spec.ts
+```
+
+`e2e/helpers/login.ts`:
+
+```typescript
+import type {Page} from "@playwright/test";
+import {TEST_USER} from "../fixtures/testUsers";
+
+export const loginAs = async (page: Page, user = TEST_USER): Promise<void> => {
+  await page.goto("/login");
+  await page.getByTestId("login-screen").waitFor({state: "visible"});
+  await page.getByTestId("login-screen-email-input").fill(user.email);
+  await page.getByTestId("login-screen-password-input").fill(user.password);
+  await page.getByTestId("login-screen-submit-button").click();
+  await page.getByTestId("login-screen").waitFor({state: "hidden"});
+};
+```
+
+`e2e/auth.setup.ts` signs each fixture user up through the backend's auth API and ignores
+"already exists", so reruns are idempotent. With Better Auth (the `create-terreno-app`
+default) that is `request.post("http://localhost:4000/api/auth/sign-up/email", {data: {email,
+name, password}})`; with JWT auth it is `POST /auth/signup`. `bun run --cwd ../backend` loads
+`backend/.env`, so the backend gets its auth secrets. The `@terreno/ui` login screen already
+carries the `login-screen*` testIDs; give a custom form the same IDs.
+
+Done when `bunx playwright test` passes. Add `"test:e2e": "playwright test"` to the scripts.

package/skills/terreno-test-setup/references/mobile.md

@@ -0,0 +1,134 @@
+# Mobile test setup (iOS / Android)
+
+Two layers:
+
+- **Platform unit tests** — the same Bun suite with `Platform.OS` set to `ios` or `android`.
+  Fast; no device.
+- **Maestro flows** — drive the real native app on a simulator or emulator.
+
+## Platform unit tests
+
+`registerExpoTestEnvironment` fixes `Platform.OS` for the whole run, so pick it from an env var
+in the preload and run the suite once per platform:
+
+```typescript
+// frontend/tests/testPreload.ts
+import {registerExpoTestEnvironment} from "@terreno/test/expo/registerExpoTestEnvironment";
+
+const platform = (process.env.TEST_PLATFORM ?? "ios") as "android" | "ios" | "web";
+registerExpoTestEnvironment({expoConfig: {extra: {}, scheme: "<scheme>"}, platform});
+```
+
+```json
+"scripts": {
+  "test": "bun test",
+  "test:android": "TEST_PLATFORM=android bun test",
+  "test:web": "TEST_PLATFORM=web bun test"
+}
+```
+
+Run the extra platforms in CI only when the app has `Platform.OS` / `Platform.select` branches.
+
+## Maestro
+
+### 1. Native identifiers
+
+Maestro targets the app by bundle ID. Set both in `frontend/app.json` if missing
+(`create-terreno-app` only sets `scheme`):
+
+```json
+"ios": {"bundleIdentifier": "com.<org>.<app>"},
+"android": {"package": "com.<org>.<app>"}
+```
+
+### 2. A build on a device
+
+Use a **development build**, not Expo Go (Expo Go's app ID is Expo's, not yours):
+
+| Platform | Command |
+|----------|---------|
+| iOS simulator (macOS + Xcode) | `bunx expo run:ios` |
+| Android emulator | `bunx expo run:android` |
+| Either, prebuilt in the cloud | `bunx eas-cli build --profile development --platform <ios\|android>` then `bunx eas-cli build:run -p <platform> --latest` |
+
+The `store-assets` skill's `devclient:ensure` script keeps a dev client in sync with the
+native fingerprint if the app already uses it.
+
+Reach the local backend from the device:
+
+- iOS simulator shares the Mac's `localhost`; nothing to do.
+- Android emulator: `adb reverse tcp:8081 tcp:8081 && adb reverse tcp:4000 tcp:4000` (Metro and
+  the API). Repeat after every emulator restart.
+
+### 3. Install Maestro
+
+```bash
+curl -fsSL "https://get.maestro.mobile.dev" | bash   # needs Java 17
+maestro --version
+```
+
+### 4. Flows
+
+```
+frontend/maestro/
+  config.yaml          # flow list and order
+  subflows/login.yaml  # reused by other flows
+  login.yaml
+```
+
+`frontend/maestro/subflows/login.yaml`:
+
+```yaml
+appId: ${APP_ID}
+---
+- extendedWaitUntil:
+    visible:
+      id: "login-screen-email-input"
+    timeout: 60000
+- tapOn:
+    id: "login-screen-email-input"
+- inputText: ${EMAIL}
+- tapOn:
+    id: "login-screen-password-input"
+- inputText: ${PASSWORD}
+- hideKeyboard
+- tapOn:
+    id: "login-screen-submit-button"
+```
+
+`frontend/maestro/login.yaml`:
+
+```yaml
+appId: ${APP_ID}
+---
+- launchApp:
+    clearState: true
+- runFlow: subflows/login.yaml
+- extendedWaitUntil:
+    visible:
+      id: "home-screen"
+    timeout: 30000
+```
+
+React Native `testID` becomes the iOS accessibility identifier and the Android resource ID, so
+Maestro's `id:` selector works on both. `@terreno/ui` components accept a `testID` prop; check a custom component passes it to the underlying native view.
+
+### 5. Run
+
+```bash
+maestro test -e APP_ID=com.<org>.<app> -e EMAIL=test@example.com -e PASSWORD=<password> maestro/
+maestro --device <udid|emulator-serial> test ...   # when several devices are booted
+maestro hierarchy                                  # list the testIDs on screen
+```
+
+Seed the user first (`bun run seed` in the backend, or the E2E auth setup).
+
+Add `"test:maestro": "maestro test maestro/"` to the scripts.
+
+### CI
+
+- Android: a Linux runner with an emulator (e.g. `reactivecircus/android-emulator-runner`),
+  then build, install, `adb reverse`, and `maestro test`.
+- iOS: needs a macOS runner and a simulator build (`eas build --profile development:simulator`
+  or `expo run:ios`).
+- Maestro Cloud runs both from an uploaded build if the project has an account.

package/skills/terreno-ui/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: terreno-ui
+description: >-
+  Build UI with @terreno/ui — Terreno's React Native component library with a
+  large component set and a three-layer theming system. Use when adding or reviewing
+  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.
+---
+# @terreno/ui
+
+`@terreno/ui` is Terreno's universal (iOS, Android, web) component library. Start with existing components before creating new ones. For full screen structure and navigation, see `building-terreno-apps`.
+
+## Choosing a component (read this first)
+
+Work down this list and stop at the first layer that meets the need:
+
+1. **Layout primitives — start here.** `Box` for flex layout, `Page` for full screens, `Card` for grouped content with shadow.
+2. **Form fields.** `TextField`, `SelectField`, `DateTimeField`, `CheckBox`, etc. for user input.
+3. **Data display.** `DataTable`, `Badge`, `Text`, `Heading` for content.
+4. **Feedback.** `Modal`, `Toast`, `Spinner`, `Banner`, `ErrorPage` for states.
+5. **Admin screens.** Skill `building-admin-interfaces` (`AdminScreenRouter`,
+   `AdminModelTable`, `AdminModelForm`, `AdminShellLayout`) before hand-rolling
+   tables/forms.
+6. **New component — last resort.** Only when a concrete composition gap is proven. Add to `ui/` package and a demo story in `demo/`.
+
+**Do not use `@expo/ui`** in Terreno apps unless there is an explicit requirement for native SwiftUI/Compose that `@terreno/ui` cannot satisfy.
+
+## Documentation
+
+1. Read `docs/reference/ui.md`, `docs/explanation/responsive-design.md`, `docs/reference/components/`, and the relevant explanation pages before changing components, width-dependent layout, or theme contracts.
+2. Implement against that design.
+3. Update those pages (and a demo story) in the same slice with `update-docs`.
+4. Ship without matching docs is a failed slice.
+
+## References
+
+```
+references/
+  layout.md              Box, Page, Card, ListDetailLayout, SplitPage — spacing and flex
+  forms.md               TextField, SelectField, DateTimeField, validation
+  data-display.md        DataTable, Badge, Text, Heading
+  feedback.md            Modal, Toast, Spinner, Banner
+  theming.md             TerrenoProvider, useTheme, color tokens
+```
+
+## Installation
+
+In Terreno monorepo apps, `@terreno/ui` is a workspace dependency:
+
+```json
+"@terreno/ui": "workspace:*"
+```
+
+Wrap the app root in `TerrenoProvider`:
+
+```tsx
+import {TerrenoProvider} from "@terreno/ui";
+
+<TerrenoProvider>
+  {children}
+</TerrenoProvider>
+```
+
+## Quick examples
+
+### Layout
+
+```tsx
+import {Box, Card, Heading, Page, Text} from "@terreno/ui";
+
+const ProfileScreen: React.FC = () => (
+  <Page title="Profile" scroll>
+    <Box gap={4} padding={4}>
+      <Heading size="lg">Account</Heading>
+      <Card padding={4}>
+        <Text>user@example.com</Text>
+      </Card>
+    </Box>
+  </Page>
+);
+```
+
+### Button
+
+```tsx
+import {Button} from "@terreno/ui";
+
+<Button
+  text="Save"
+  variant="primary"
+  onClick={handleSave}
+  loading={isSaving}
+  iconName="check"
+  fullWidth
+/>
+```
+
+Variants: `primary` | `secondary` | `muted` | `outline` | `destructive`
+
+### Form field
+
+```tsx
+import {TextField} from "@terreno/ui";
+
+<TextField
+  title="Email"
+  value={email}
+  onChange={setEmail}
+  type="email"
+  errorText={emailError}
+  helperText="We'll never share your email"
+/>
+```
+
+### Modal
+
+```tsx
+import {Modal, Text} from "@terreno/ui";
+
+<Modal
+  title="Confirm Delete"
+  visible={isVisible}
+  primaryButtonText="Delete"
+  secondaryButtonText="Cancel"
+  onDismiss={() => setIsVisible(false)}
+  onPrimaryAction={handleDelete}
+>
+  <Text>Are you sure?</Text>
+</Modal>
+```
+
+## Rules
+
+- Use `Box` for layout — never raw `View` (unless inside a platform-specific workaround).
+- Use `Text` / `Heading` from `@terreno/ui` — never raw React Native `Text`.
+- Use theme props (`padding`, `gap`, `color`, `border`, `rounding`) — not inline hex when a token exists.
+- Use `Page` for screen-level layout — not bare `ScrollView`.
+- Icons use FontAwesome 6 via `iconName` props.
+- Use Luxon for dates in display logic; `DateTimeField` handles input.
+- Always support React Native Web.
+- After component changes, verify in the demo app (`verify-ui-changes` skill).
+
+## Component map
+
+| Need | Component |
+|------|-----------|
+| Flex layout | `Box` |
+| Full screen | `Page` |
+| Grouped content | `Card` |
+| List/detail with routes (mail, inbox, records) | `ListDetailLayout` in the group's `_layout.tsx` |
+| List/detail without routes (inside a modal) | `SplitPage` |
+| Text input | `TextField`, `TextArea`, `EmailField`, `PasswordField` |
+| Dropdown | `SelectField`, `MultiselectField` |
+| Date/time | `DateTimeField` |
+| Boolean | `CheckBox`, `BooleanField`, `RadioField` |
+| Table | `DataTable` |
+| Status chip | `Badge` |
+| Action | `Button`, `IconButton`, `Link` |
+| Dialog | `Modal`, `ActionSheet`, `ModalSheet` |
+| Loading | `Spinner` |
+| Notification | `Toast` (via TerrenoProvider), `Banner` |
+| Error state | `ErrorPage`, `ErrorBoundary` |
+| OAuth login | `SocialLoginButton` |
+| Signature | `SignatureField` |
+| Markdown | `MarkdownView` |
+
+See `./references/` for detailed props and patterns.
+
+## vs Expo UI (`@expo/ui`)
+
+| | @terreno/ui | @expo/ui |
+|---|-------------|----------|
+| Platform | RN + web (unified) | Native SwiftUI/Compose |
+| Theming | Three-layer design tokens | Platform-native |
+| Forms | Full field library | Limited universal set |
+| Tables | `DataTable` with sort/pagination | List components |
+| Admin | `@terreno/admin-frontend` | None |
+| Terreno integration | First-class | Not integrated |
+
+Default to `@terreno/ui` in all Terreno apps.
+
+## Decision Tree
+
+```
+Need UI in a Terreno app?
+  |-- Screen structure?
+  |   \-- Page + Box (references/layout.md)
+  |
+  |-- User input?
+  |   \-- references/forms.md
+  |
+  |-- Show data (table, badge, text)?
+  |   \-- references/data-display.md
+  |
+  |-- Loading/error/modal/toast?
+  |   \-- references/feedback.md
+  |
+  |-- Colors/spacing/fonts?
+  |   \-- references/theming.md
+  |
+  |-- Admin CRUD table/form, sidebar, or custom operator screen?
+  |   \-- skill building-admin-interfaces
+  |
+  |-- Component doesn't exist?
+  |   \-- Compose with Box + existing fields; add to ui/ only if gap is proven
+  |
+  \-- Changed a component?
+      \-- verify-ui-changes (demo app /dev route)
+```
+
+## Common Mistakes
+
+**Wrong: inline styles for spacing**
+
+```tsx
+<View style={{padding: 16, marginBottom: 8}}>
+```
+
+**Right: theme props**
+
+```tsx
+<Box padding={4} marginBottom={2}>
+```
+
+**Wrong: raw Text**
+
+```tsx
+import {Text} from "react-native";
+<Text style={{fontSize: 24}}>Title</Text>
+```
+
+**Right: Heading**
+
+```tsx
+import {Heading} from "@terreno/ui";
+<Heading size="lg">Title</Heading>
+```
+
+**Wrong: StyleSheet.create for one-off styles**
+
+```tsx
+const styles = StyleSheet.create({container: {flex: 1}});
+```
+
+**Right: inline styles or Box props (Terreno convention)**
+
+```tsx
+<Box flex="grow" padding={4}>
+```

package/skills/terreno-ui/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Terreno UI"
+  short_description: "Choose and compose @terreno/ui components — Box, Page, forms, tables, modals, and theming for cross-platform apps"
+  default_prompt: "Use $terreno-ui to pick the right @terreno/ui components and theme props for a layout, form, or feedback pattern."