@terreno/agent-plugin 0.0.0-stage → 57.22.0

package/skills/building-admin-interfaces/references/patterns-and-tools.md

@@ -0,0 +1,73 @@
+# Patterns and tools
+
+## Widget registry (`AdminProvider.widgets`)
+
+Three buckets. Host entries override built-ins with the same ID.
+
+| Bucket | IDs come from | Built-ins include |
+| --- | --- | --- |
+| `home` | `AdminApp.home.slots` | `modelStats` / `modelsGrid`, `scriptRunner`, `versionConfig`, `recentActivity`, `feature-flags-overrides` |
+| `screens` | `customScreens[].name` | `comms`, `documents`, `ai-requests`, `version-config` |
+| `fields` | `admin.fieldOverrides.widget` | `textarea`, `markdown`, consent widgets |
+
+Unknown IDs render `MissingWidget` instead of crashing. Register host widgets once
+on `AdminProvider`; do not pass the deprecated `customScreens` prop on
+`AdminModelList`.
+
+Plugin backend IDs arrive via `adminContribution()`. First-party React lives in
+`@terreno/admin-frontend`. Third-party plugins ship their own frontend package;
+the host spreads it into `widgets`. See
+[Admin plugin frontend widgets](../../../../../docs/explanation/admin-plugin-frontend.md).
+
+## Model admin metadata that affects UI
+
+Set these on `modelRouter({admin: ...})` rather than cloning tables:
+
+- `listFields`, `searchFields`, `sortableFields`, `filters`
+- `fieldsets`, `readonlyFields`, `hiddenFields`
+- `group`, `recordTitleField`, `pageSize`
+- `actions` / `bulkPatchAllowlist` for changelist bulk work
+
+Reference: [admin-config](../../../../../docs/reference/admin-config.md).
+
+## Platform tools
+
+| Tool | Config flag | Typical route |
+| --- | --- | --- |
+| Scripts | `platformTools.scripts` | `{routeBase}/__scripts` |
+| Roles | `platformTools.roles` | `rolesPath` (embedded `/roles` or `/admin/roles`) |
+| Version | `platformTools.version` | `versionConfigPath` |
+| Configuration | `platformTools.configuration` | `configurationPath` |
+| Audit Log / Feature Flags | model `read` | `/{model.name}` via Platform section |
+
+## Data and MCP
+
+- Admin String-`_id` collection CRUD: windowed syncdb with `adminBroadcast`.
+- Framework admin RPC: host-bound `adminRequest`; do not add `injectEndpoints`.
+- ObjectId/API-only compatibility CRUD: `useAdminApi` until Terreno 58.
+- After backend route changes: `cd example-frontend && bun run sdk` (non-synced
+  only). Do not generate RTK CRUD for synced product collections.
+- MCP: `terreno_install_admin` scaffolds wiring; still follow this skill for
+  screens and nav. `terreno_search_docs` / `terreno_get_component_docs` for APIs.
+
+## Copy-paste custom screen
+
+```tsx
+import {AdminScreenPage} from "@terreno/admin-frontend";
+import type {AdminScreenWidgetProps} from "@terreno/admin-frontend";
+import {Box, Text} from "@terreno/ui";
+import React from "react";
+
+export const ExampleOpsScreen: React.FC<AdminScreenWidgetProps> = ({routeBase}) => {
+  return (
+    <AdminScreenPage backHref={routeBase} color="transparent" padding={0} title="Ops">
+      <Box padding={4}>
+        <Text>Operator content</Text>
+      </Box>
+    </AdminScreenPage>
+  );
+};
+```
+
+Match `name: "example-ops"` on `AdminApp.customScreens` and
+`widgets={{screens: {"example-ops": ExampleOpsScreen}}}`.

package/skills/building-admin-interfaces/references/screens-and-routes.md

@@ -0,0 +1,50 @@
+# Screens and routes
+
+Canonical steps: [Build admin screens](../../../../../docs/how-to/build-admin-screens.md).
+
+## Embedded host (`example-frontend/app/admin`)
+
+Wrap **once** in `_layout.tsx`: `AdminProvider` then `AdminShellLayout` then `Stack`.
+Child routes must not wrap another shell.
+
+| File | Component |
+| --- | --- |
+| `index.tsx` | `AdminHome` |
+| `[model]/index.tsx` | `AdminScreenRouter` with `name={model}` |
+| `[model]/create.tsx` | `AdminModelForm` `mode="create"` |
+| `[model]/[id].tsx` | `AdminModelForm` |
+| Extra folders (`comms/`, `consent-forms/`, `configuration.tsx`) | Only when generic CRUD is not enough |
+
+Create is **`create`**, not `new`.
+
+## Standalone host (`admin-spa/app`)
+
+Root `_layout.tsx` is providers + `AdminGate` only. **Each screen** wraps
+`AdminShellLayout` because there is no shared admin stack layout. `routeBase=""`.
+`apiBase` comes from `app-config.json` (`adminApiBasePath`, default `/admin`).
+
+## `AdminScreenRouter`
+
+Resolves one URL segment:
+
+1. `__scripts` → `AdminScriptList`
+2. Config model `name` → `AdminModelTable`
+3. `widgets.screens[name]` → custom screen widget
+4. Config `customScreens` without a widget → missing-widget placeholder
+5. Else not-found
+
+Model **names** (Mongoose model name, or a unique suffix like `Food-archived-foods`)
+are the URL segment, not `routePath` (`/admin/users`).
+
+## Dedicated routes vs widgets
+
+Prefer a `widgets.screens` component so `[model]/index` can render it. Add a
+dedicated Expo file when:
+
+- The path has more segments than `/admin/:name` (comms message `/comms/:id`).
+- The screen must not share the generic create/edit form (consent editor).
+- The host is admin-spa and you want a static export path (optional; the
+  `[model]` fallback already covers single-segment custom screens).
+
+Expo file routes win over `[model]` when the folder name is literal
+(`comms/index.tsx` beats `[model]/index.tsx` for `/admin/comms`).

package/skills/building-terreno-apps/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: building-terreno-apps
+description: >-
+  Complete guide for building Terreno full-stack Expo apps with @terreno/ui,
+  Expo Router, and @terreno/rtk. Covers layout, forms, navigation, theming,
+  screen patterns, and when to use Expo Go vs custom builds.
+---
+# Building Terreno Apps
+
+Use this skill when building or refactoring screens in a Terreno Expo app (`example-frontend`, `admin-spa`, or a consumer app using `@terreno/ui` + `@terreno/rtk`).
+
+**Related skills:** `terreno-ui` (component selection), `terreno-data-fetching` (API hooks), `verify-ui-changes` (mandatory UI verification), `generate-sdk` (after backend changes), `building-admin-interfaces` (admin shell, custom screens, sidebar).
+
+## Documentation
+
+1. Read `docs/tutorials/`, `docs/explanation/`, and app-structure how-to pages before changing screens or navigation.
+2. Implement against that design.
+3. Update those pages in the same slice with `update-docs`.
+4. Ship without matching docs is a failed slice.
+
+## References
+
+Consult these resources as needed:
+
+```
+references/
+  route-structure.md     Expo Router conventions adapted for Terreno apps
+  screen-patterns.md     List, detail, form, and admin screen templates
+  navigation.md          Stacks, tabs, modals, and auth-gated routing
+```
+
+Admin CRUD, sidebar, custom screens, and `apiBase`/`routeBase`: use skill
+`building-admin-interfaces` and `docs/how-to/build-admin-screens.md`.
+
+## Running the App
+
+**CRITICAL: Always try Expo Go first before creating custom builds.**
+
+1. Start with `bun run frontend:web` (or `bun run start` in the app package) and test in Expo Go or the web dev server.
+2. For full-stack features, start the backend: `bun run backend:dev` with MongoDB and auth env vars (see `AGENTS.md`).
+3. Only create custom builds (`npx expo run:ios/android`, `eas build`) when you need local Expo modules, Apple targets, third-party native modules not in Expo Go, or native config that cannot be expressed in `app.json`.
+
+## Provider Stack
+
+Every Terreno app root layout should wrap children in this order (outer → inner):
+
+```tsx
+import {Provider} from "react-redux";
+import {PersistGate} from "redux-persist/integration/react";
+import {TerrenoProvider} from "@terreno/ui";
+// Import from your app's store bootstrap module (see example-frontend/store/index.ts)
+import store, {persistor} from "../store/index.ts";
+
+const RootLayout: React.FC = () => {
+  return (
+    <Provider store={store}>
+      <PersistGate loading={null} persistor={persistor}>
+        <TerrenoProvider>
+          <Stack />
+        </TerrenoProvider>
+      </PersistGate>
+    </Provider>
+  );
+};
+```
+
+See `example-frontend/app/_layout.tsx` for the full pattern including auth routing, sockets, and feature flags.
+
+## Code Style
+
+- Use **functional components** with `React.FC` and explicit return types.
+- Import hooks directly: `import {useEffect, useCallback} from "react"` — not `React.useEffect`.
+- Wrap event handlers in `useCallback`. Add a comment above every `useEffect`.
+- Use **Luxon** for all date/time operations — never `Date` or dayjs.
+- Use **camelCase** directories (e.g. `components/todoList/`).
+- Use **kebab-case** for route file names when the Expo skill convention applies (e.g. `comment-card.tsx`).
+- **No barrel imports** — import concrete module files, not directory `index` re-exports. Cross-package `@terreno/*` roots are allowed.
+- Never co-locate components, types, or utilities in the `app/` directory.
+
+## Layout — Use @terreno/ui, Not Raw Primitives
+
+| Instead of | Use |
+|------------|-----|
+| `View` | `Box` |
+| React Native `Text` | `Text` or `Heading` from `@terreno/ui` |
+| `ScrollView` as page wrapper | `Page` with `scroll={true}` |
+| `StyleSheet.create` | Theme props (`padding`, `gap`, `color`) or inline styles |
+| `SafeAreaView` | `Page` handles safe areas; or `contentInsetAdjustmentBehavior` on lists |
+| Inline hex colors | Theme surface/text colors via props (`color="primary"`) |
+
+### Page layout
+
+```tsx
+import {Box, Button, Heading, Page, Text} from "@terreno/ui";
+
+const TodosScreen: React.FC = () => {
+  return (
+    <Page title="Todos" scroll loading={isLoading}>
+      <Box gap={3} padding={4}>
+        <Heading size="lg">My Todos</Heading>
+        <Text color="secondaryLight">Track your tasks</Text>
+        <Button text="Add Todo" onClick={handleAdd} variant="primary" />
+      </Box>
+    </Page>
+  );
+};
+```
+
+### Box layout
+
+```tsx
+<Box direction="row" padding={4} gap={2} alignItems="center">
+  <Text flex="grow">Content</Text>
+  <Button text="Action" onClick={handleAction} />
+</Box>
+```
+
+Use the spacing scale via props (`padding={4}` → 16px). Prefer `gap` over margin.
+
+## Data on Screens
+
+Never call `fetch` or `axios` in screen components. Use generated RTK Query hooks:
+
+```tsx
+import {useGetTodosQuery, usePostTodosMutation} from "@/store/sdk";
+
+const {data, isLoading, error, refetch} = useGetTodosQuery({});
+const [createTodo, {isLoading: isCreating}] = usePostTodosMutation();
+```
+
+See `terreno-data-fetching` for auth, caching, and error handling.
+
+## Forms
+
+Use `@terreno/ui` form fields with local state and RTK mutations:
+
+```tsx
+import {Button, TextField} from "@terreno/ui";
+
+const [title, setTitle] = useState<string>("");
+const [titleError, setTitleError] = useState<string | undefined>();
+
+const handleSubmit = useCallback(async (): Promise<void> => {
+  if (!title.trim()) {
+    setTitleError("Title is required");
+    return;
+  }
+  try {
+    await createTodo({title: title.trim(), completed: false}).unwrap();
+    setTitle("");
+  } catch (err) {
+    console.error("Failed to create todo", err);
+  }
+}, [createTodo, title]);
+
+<TextField
+  title="Title"
+  value={title}
+  onChange={setTitle}
+  errorText={titleError}
+/>
+<Button text="Create" onClick={handleSubmit} loading={isCreating} />
+```
+
+## Navigation
+
+- Use Expo Router file-based routing in `app/`.
+- Gate routes on auth state in root `_layout.tsx` (redirect to `/login` when logged out).
+- Use `Stack` from `expo-router` for stack navigation; set titles via `Stack.Screen options`.
+- For admin screens, use `AdminShellLayout` from `@terreno/admin-frontend`.
+
+See `./references/navigation.md` and `./references/route-structure.md`.
+
+## Loading, Error, and Empty States
+
+Every data-driven screen must handle all three:
+
+```tsx
+if (isLoading) {
+  return <Page title="Todos"><Spinner /></Page>;
+}
+if (error) {
+  return (
+    <Page title="Todos">
+      <Text color="error">Failed to load todos</Text>
+      <Button text="Retry" onClick={refetch} />
+    </Page>
+  );
+}
+if (!data?.data?.length) {
+  return (
+    <Page title="Todos">
+      <Text>No todos yet</Text>
+      <Button text="Create your first todo" onClick={handleAdd} />
+    </Page>
+  );
+}
+```
+
+## Theming
+
+- Wrap the app in `TerrenoProvider` (done in root layout).
+- Use theme props on components: `color="primary"`, `border="default"`, `rounding="md"`.
+- Access theme programmatically with `useTheme()` when needed.
+- Do not hardcode hex colors when a theme token exists.
+
+## Verification
+
+Any UI change **must** follow the `verify-ui-changes` skill before opening or updating a PR. Launch the correct app, log in with seeded credentials, exercise the feature, and attach screenshots/videos to the PR.
+
+## Decision Tree
+
+```
+Building or changing a screen?
+  |-- Need layout/structure?
+  |   \-- Page for full screens, Box for sections, Card for grouped content
+  |
+  |-- Need data from API?
+  |   \-- terreno-data-fetching (RTK Query hooks, never raw fetch)
+  |
+  |-- Need a form?
+  |   \-- @terreno/ui TextField/SelectField/DateTimeField + local state + mutation
+  |
+  |-- Need navigation?
+  |   \-- references/navigation.md (Expo Router + auth gating)
+  |
+  |-- Need admin CRUD, sidebar, or a custom operator screen?
+  |   \-- building-admin-interfaces + AdminShellLayout + AdminScreenRouter
+  |
+  |-- Backend API doesn't exist yet?
+  |   \-- terreno-backend-api (modelRouter on Express, then generate-sdk)
+  |
+  \-- Done coding?
+      \-- verify-ui-changes (mandatory)
+```
+
+## Common Mistakes
+
+**Wrong: Raw View/Text**
+
+```tsx
+<View style={{padding: 16}}>
+  <Text style={{fontSize: 18}}>Hello</Text>
+</View>
+```
+
+**Right: @terreno/ui with theme props**
+
+```tsx
+<Box padding={4}>
+  <Heading size="lg">Hello</Heading>
+</Box>
+```
+
+**Wrong: fetch in a screen**
+
+```tsx
+const [todos, setTodos] = useState([]);
+useEffect(() => {
+  fetch("/todos").then((r) => r.json()).then(setTodos);
+}, []);
+```
+
+**Right: Generated RTK Query hook**
+
+```tsx
+const {data} = useGetTodosQuery({});
+```
+
+**Wrong: Editing openApiSdk.ts by hand**
+
+```tsx
+// Manually adding a hook to store/openApiSdk.ts
+```
+
+**Right: Regenerate SDK after backend changes**
+
+```bash
+cd example-frontend && bun run sdk
+```

package/skills/building-terreno-apps/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Building Terreno Apps"
+  short_description: "Build Terreno Expo apps with @terreno/ui layout, RTK Query data, Expo Router navigation, and mandatory UI verification"
+  default_prompt: "Use $building-terreno-apps to build or refactor a Terreno screen with @terreno/ui components, generated RTK Query hooks, and Expo Router navigation."

package/skills/building-terreno-apps/references/navigation.md

@@ -0,0 +1,102 @@
+# Navigation — Terreno Apps
+
+Terreno apps use Expo Router. Use Expo Router's public documentation for low-level APIs
+such as `Link`, `Stack.Screen`, modals, and form sheets. This reference covers
+Terreno-specific navigation patterns.
+
+## Auth flow
+
+1. Root `_layout.tsx` checks `useSelectCurrentUserId()` from `@terreno/rtk`.
+2. Unauthenticated users redirect to `/login`.
+3. Login screen calls `useEmailLoginMutation()` (from generated SDK via `generateAuthSlice`).
+4. On success, tokens are stored automatically and `setUserId` is dispatched.
+5. Root layout redirects to `/(tabs)` or the intended deep link.
+
+```tsx
+import {useEmailLoginMutation} from "@/store/sdk";
+import {Button, TextField, Page, Box} from "@terreno/ui";
+
+const LoginScreen: React.FC = () => {
+  const [email, setEmail] = useState<string>("");
+  const [password, setPassword] = useState<string>("");
+  const [login, {isLoading, error}] = useEmailLoginMutation();
+
+  const handleLogin = useCallback(async (): Promise<void> => {
+    try {
+      await login({email, password}).unwrap();
+    } catch (err) {
+      console.error("Login failed", err);
+    }
+  }, [email, login, password]);
+
+  return (
+    <Page title="Login" scroll>
+      <Box gap={3} padding={4}>
+        <TextField title="Email" value={email} onChange={setEmail} type="email" />
+        <TextField title="Password" value={password} onChange={setPassword} type="password" />
+        <Button text="Sign in" onClick={handleLogin} loading={isLoading} fullWidth />
+      </Box>
+    </Page>
+  );
+};
+```
+
+## Tabs
+
+Use Expo Router tab groups. Set tab icons via `@expo/vector-icons` or FontAwesome through `@terreno/ui` `Icon`:
+
+```tsx
+import {Tabs} from "expo-router";
+import FontAwesome from "@expo/vector-icons/FontAwesome";
+
+const TabLayout: React.FC = () => {
+  return (
+    <Tabs screenOptions={{headerShown: false}}>
+      <Tabs.Screen
+        name="index"
+        options={{
+          title: "Todos",
+          tabBarIcon: ({color}) => <FontAwesome name="list" size={24} color={color} />,
+        }}
+      />
+      <Tabs.Screen
+        name="profile"
+        options={{
+          title: "Profile",
+          tabBarIcon: ({color}) => <FontAwesome name="user" size={24} color={color} />,
+        }}
+      />
+    </Tabs>
+  );
+};
+```
+
+## Modals
+
+Use Expo Router modal presentation for simple overlays:
+
+```tsx
+// app/_layout.tsx
+<Stack>
+  <Stack.Screen name="(tabs)" options={{headerShown: false}} />
+  <Stack.Screen name="modal" options={{presentation: "modal"}} />
+</Stack>
+```
+
+For confirmation dialogs and action sheets, prefer `@terreno/ui` `Modal` or `ActionSheet` — they render correctly on web and native.
+
+## Deep linking
+
+Configure `scheme` in `app.json`. Terreno RTK resolves API base URLs from `EXPO_PUBLIC_API_URL` or `expo.extra.BASE_URL` — keep deep link schemes separate from API URLs.
+
+## Programmatic navigation
+
+```tsx
+import {useRouter} from "expo-router";
+
+const router = useRouter();
+router.push(`/admin/${modelName}`);
+router.back();
+```
+
+Use `Link` from `expo-router` for declarative navigation when possible.

package/skills/building-terreno-apps/references/route-structure.md

@@ -0,0 +1,91 @@
+# Route Structure — Terreno Apps
+
+Terreno apps use Expo Router with the same file conventions as standard Expo apps. Use
+Expo Router's public documentation for dynamic routes, groups, and query parameters.
+
+## Terreno-specific conventions
+
+### Directory layout
+
+```
+app/
+  _layout.tsx              # Provider stack, auth gating, TerrenoProvider
+  login.tsx                # Auth screen
+  (tabs)/
+    _layout.tsx            # Tab navigator
+    index.tsx              # Main screen (e.g. todos list)
+    profile.tsx
+  mail/
+    _layout.tsx            # ListDetailLayout: list pane + Stack; unstable_settings.initialRouteName = "index"
+    index.tsx              # ListDetailIndex: the list on a phone, the empty state on a tablet
+    [id].tsx               # Detail screen; the open item lives in the URL
+  admin/
+    _layout.tsx            # AdminShellLayout wrapper
+    index.tsx              # AdminHome
+    [model]/
+      index.tsx            # AdminScreenRouter (table or custom screen)
+      create.tsx           # AdminModelForm (create)
+      [id].tsx             # AdminModelForm (edit)
+components/                # Screen components (NOT in app/)
+hooks/                     # Custom hooks
+store/
+  index.ts                 # Redux store + generateAuthSlice
+  sdk.ts                   # Hand-maintained SDK extensions
+  openApiSdk.ts            # Generated — never edit manually
+```
+
+### Rules
+
+- Routes belong in `app/`; everything else lives outside.
+- Never co-locate `components/`, `utils/`, or `types/` inside `app/`.
+- Ensure a route matches `/` so the app is never blank.
+- Use `(group)` routes to organize without affecting URLs.
+- Use `_layout.tsx` for stacks and provider wrappers.
+- Build list/detail screens (mail, inbox, records) as a route group with `ListDetailLayout` as its
+  `_layout.tsx`, `ListDetailIndex` as `index.tsx`, and the detail as `[id].tsx`. Phones push the
+  detail; tablets show the list and detail side by side.
+
+### Auth-gated routing
+
+```tsx
+import {Redirect, Stack, useSegments} from "expo-router";
+import {useSelectCurrentUserId} from "@terreno/rtk";
+
+const RootLayoutNav: React.FC = () => {
+  const userId = useSelectCurrentUserId();
+  const segments = useSegments();
+
+  if (!userId && segments[0] !== "login") {
+    return <Redirect href="/login" />;
+  }
+  if (userId && segments[0] === "login") {
+    return <Redirect href="/(tabs)" />;
+  }
+
+  return <Stack screenOptions={{headerShown: false}} />;
+};
+```
+
+### Admin routes
+
+Wrap admin routes once in `app/admin/_layout.tsx`:
+
+```tsx
+import {AdminShellLayout} from "@terreno/admin-frontend";
+import {Stack} from "expo-router";
+import {terrenoApi} from "@/store/sdk";
+
+export default function AdminLayout(): React.ReactElement {
+  return (
+    <AdminShellLayout
+      api={terrenoApi}
+      apiBase="/admin"
+      configurationPath="/admin/configuration"
+      routeBase="/admin"
+      versionConfigPath="/version-config"
+    >
+      <Stack screenOptions={{headerShown: false, contentStyle: {flex: 1}}} />
+    </AdminShellLayout>
+  );
+}
+```