@terreno/agent-plugin 0.0.0-stage → 57.22.0

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

@@ -0,0 +1,85 @@
+# Data Display — @terreno/ui
+
+## Text and Heading
+
+```tsx
+<Text size="md" color="primary" bold truncate>
+  Body copy
+</Text>
+
+<Heading size="lg" color="primary" align="center">
+  Page Title
+</Heading>
+```
+
+Sizes: `sm`, `md`, `lg`, `xl`, `2xl` (responsive web/mobile values).
+
+## Badge
+
+```tsx
+<Badge status="success" value="Active" />
+<Badge status="warning" value="Pending" />
+<Badge status="error" value="Failed" />
+```
+
+## DataTable
+
+```tsx
+<DataTable
+  columns={[
+    {key: "name", label: "Name", width: 200, sortable: true},
+    {key: "status", label: "Status", width: 100, columnType: "boolean"},
+    {key: "created", label: "Created", width: 150, columnType: "date"},
+  ]}
+  data={rows}
+  onSortChange={setSort}
+  onRowClick={(row) => navigate(row.id)}
+  pageSize={20}
+  totalRowCount={total}
+  onPageChange={setPage}
+  sticky
+  loading={isLoading}
+/>
+```
+
+Column types: `text`, `date`, `number`, `boolean`, `custom`.
+
+For admin tables, prefer `AdminModelTable` from `@terreno/admin-frontend`.
+
+## Link
+
+```tsx
+<Link href="https://example.com" text="Learn more" />
+```
+
+## Avatar
+
+```tsx
+<Avatar name="Jane Doe" src={imageUrl} size="md" />
+```
+
+## Pagination
+
+Standalone pagination when not using DataTable's built-in controls:
+
+```tsx
+<Pagination
+  page={currentPage}
+  totalPages={totalPages}
+  onPageChange={setPage}
+/>
+```
+
+## Date formatting
+
+Always use Luxon:
+
+```tsx
+import {DateTime} from "luxon";
+
+const formatted = DateTime.fromISO(isoString).toLocaleString(DateTime.DATETIME_MED);
+```
+
+## Selectable text
+
+Add `selectable` to `Text` when users may copy the content (IDs, error messages, data values).

package/skills/terreno-ui/references/feedback.md

@@ -0,0 +1,122 @@
+# Feedback — @terreno/ui
+
+## Spinner
+
+```tsx
+<Spinner />
+<Spinner size="lg" />
+```
+
+Use in loading states inside `Page` or centered in `Box`.
+
+## Modal
+
+```tsx
+<Modal
+  visible={isVisible}
+  onDismiss={() => setIsVisible(false)}
+  title="Confirm Action"
+  size="sm"                          // sm | md | lg
+  primaryButtonText="Confirm"
+  primaryButtonOnClick={handleConfirm}
+  secondaryButtonText="Cancel"
+  secondaryButtonOnClick={() => setIsVisible(false)}
+  persistOnBackgroundClick={false}
+>
+  <Text>Are you sure?</Text>
+</Modal>
+```
+
+Renders as ActionSheet on mobile, centered dialog on web.
+
+## Button confirmation
+
+```tsx
+<Button
+  text="Delete"
+  variant="destructive"
+  withConfirmation
+  confirmationText="This cannot be undone."
+  onClick={handleDelete}
+/>
+```
+
+## Toast
+
+`TerrenoProvider` must wrap the app. Use the `useToast` hook from `@terreno/ui`:
+
+```tsx
+import {useToast} from "@terreno/ui";
+
+const MyScreen: React.FC = () => {
+  const toast = useToast();
+
+  const handleSave = useCallback(async (): Promise<void> => {
+    try {
+      await saveMutation().unwrap();
+      toast.success("Saved");
+    } catch (err) {
+      toast.catch(err, "Save failed");
+    }
+  }, [saveMutation, toast]);
+};
+```
+
+`useToast` exposes `success`, `info`, `warn`, `error`, `show`, `hide`, and `catch` (for API errors).
+
+## Banner
+
+```tsx
+<Banner
+  text="Service is temporarily unavailable."
+  status="warning"
+/>
+```
+
+Use `OfflineBanner` from `@terreno/ui` when showing network connectivity status (see example-frontend todos screen).
+
+## ErrorPage
+
+Full-page error state:
+
+```tsx
+<ErrorPage
+  title="Something went wrong"
+  message="We couldn't load your data."
+  onRetry={refetch}
+/>
+```
+
+## ErrorBoundary
+
+Wrap risky subtrees:
+
+```tsx
+<ErrorBoundary>
+  <RiskyComponent />
+</ErrorBoundary>
+```
+
+## Loading + error pattern on Page
+
+```tsx
+if (isLoading) {
+  return (
+    <Page title="Items">
+      <Box alignItems="center" padding={8}>
+        <Spinner />
+      </Box>
+    </Page>
+  );
+}
+
+if (error) {
+  return (
+    <Page title="Items">
+      <ErrorPage title="Failed to load" onRetry={refetch} />
+    </Page>
+  );
+}
+```
+
+Never ship a screen without loading and error states.

package/skills/terreno-ui/references/forms.md

@@ -0,0 +1,119 @@
+# Forms — @terreno/ui
+
+All form fields share common props:
+
+```typescript
+interface BaseFieldProps {
+  onChange: (value: string) => void;
+  value?: string;
+  title?: string;        // label above field
+  placeholder?: string;
+  disabled?: boolean;
+  errorText?: string;    // red error below field
+  helperText?: string;   // gray helper below field
+  iconName?: IconName;
+  testID?: string;
+}
+```
+
+## TextField
+
+```tsx
+<TextField
+  title="Name"
+  value={name}
+  onChange={setName}
+  type="text"            // text | email | password | phoneNumber | search | url
+  errorText={nameError}
+  helperText="Required"
+  multiline
+  rows={3}
+  grow                   // auto-expand height
+  trimOnBlur
+/>
+```
+
+## SelectField
+
+```tsx
+<SelectField
+  title="Status"
+  options={[
+    {label: "Active", value: "active"},
+    {label: "Inactive", value: "inactive"},
+  ]}
+  value={status}
+  onChange={setStatus}
+  requireValue
+/>
+```
+
+## DateTimeField
+
+```tsx
+import {DateTime} from "luxon";
+
+<DateTimeField
+  title="Due Date"
+  type="date"            // date | datetime | time
+  value={dueDate}        // ISO string
+  onChange={setDueDate}
+  showTimezone
+/>
+```
+
+Always use Luxon for formatting displayed dates.
+
+## Other fields
+
+| Field | Use for |
+|-------|---------|
+| `TextArea` | Multi-line text |
+| `NumberField` | Numeric input |
+| `EmailField` | Email with validation |
+| `PhoneNumberField` | Phone formatting |
+| `BooleanField` | Toggle with label |
+| `CheckBox` | Checkbox without field chrome |
+| `RadioField` | Radio group |
+| `MultiselectField` | Multiple selection |
+| `AddressField` | Structured address |
+| `PasswordField` | Password with show/hide |
+| `SignatureField` | Draw signature (consent flows) |
+
+## TapToEdit
+
+Use `TapToEdit` for values that should stay read-only until the user taps the pencil. Pass `setValue` for the in-progress edit and `onSave` to persist.
+
+```tsx
+<TapToEdit
+  onSave={handleSaveName}
+  setValue={setName}
+  title="Name"
+  type="text"
+  value={name}
+/>
+```
+
+`onSave` may be async. Cancel restores the value from when editing started. Do not omit `setValue` when `editable` is true.
+
+## Form pattern
+
+```tsx
+const [email, setEmail] = useState<string>("");
+const [emailError, setEmailError] = useState<string | undefined>();
+
+const handleSubmit = useCallback(async (): Promise<void> => {
+  if (!email.trim()) {
+    setEmailError("Email is required");
+    return;
+  }
+  setEmailError(undefined);
+  await saveMutation({email}).unwrap();
+}, [email, saveMutation]);
+```
+
+Check validation at the start of handlers and return early.
+
+## Admin forms
+
+For admin CRUD, use `AdminModelForm` from `@terreno/admin-frontend` — it auto-generates fields from the backend `/admin/config` metadata.

package/skills/terreno-ui/references/layout.md

@@ -0,0 +1,124 @@
+# Layout — @terreno/ui
+
+## Box
+
+Core flex primitive. All layout should use Box.
+
+```tsx
+<Box
+  direction="row"          // row | column
+  justifyContent="between" // start | end | center | between | around
+  alignItems="center"      // start | end | center | baseline | stretch
+  flex="grow"              // grow | shrink | none
+  gap={2}                  // 0-12 spacing scale
+  padding={4}
+  paddingX={2}
+  marginBottom={2}
+  width="100%"
+  color="base"             // surface color token
+  border="default"
+  rounding="md"
+  shadow
+  onClick={handlePress}    // makes it pressable
+  scroll                   // wraps in ScrollView
+  testID="my-box"
+/>
+```
+
+### Spacing scale
+
+`0→0px, 1→4px, 2→8px, 3→12px, 4→16px, 5→24px, 6→32px, 7→40px, 8→48px, 9→56px, 10→64px, 11→72px, 12→80px`
+
+Prefer `gap` over margin. Prefer `padding` over margin.
+
+## Page
+
+Full-screen layout with optional header, back button, scroll, and footer.
+
+```tsx
+<Page
+  title="Settings"
+  backButton
+  scroll
+  loading={isLoading}
+  maxWidth={800}
+  padding={2}
+  footer={<Button text="Save" onClick={save} />}
+>
+  {children}
+</Page>
+```
+
+Use `Page` instead of wrapping content in `ScrollView` manually.
+
+## Card
+
+Box wrapper with default rounding and shadow.
+
+```tsx
+<Card padding={4} color="base">
+  <Text>Grouped content</Text>
+</Card>
+```
+
+## ListDetailLayout
+
+Prefer this for list/detail screens. Use it as a route group's `_layout.tsx`: on a phone the
+list pushes the `[id]` route; on a tablet or wide browser (layout width ≥ 768) the list stays in
+a left pane and the detail opens beside it. The open item is the URL, so deep links and back work,
+and it stays open across rotation and resize.
+
+```tsx
+// app/mail/_layout.tsx
+export const unstable_settings = {initialRouteName: "index"};
+const MailLayout: React.FC = () => (
+  <ListDetailLayout
+    detailHref={(id) => `/mail/${id}`}
+    emptyDetail={<Text>Select a message</Text>}
+    indexHref="/mail"
+    list={<MailList />}
+  />
+);
+// app/mail/index.tsx
+const MailIndex: React.FC = () => <ListDetailIndex />;
+// In MailList rows: const {selectedId, select} = useListDetail();
+// <Box accessibilityState={{selected: id === selectedId}} onClick={() => select(id)} ... />
+```
+
+Keep list filters and search text in the route or a store: the list remounts at the breakpoint.
+See `docs/how-to/build-list-detail-screens.md`.
+
+## SplitPage
+
+Use only for list/detail views without their own routes (for example inside a modal); prefer
+`ListDetailLayout` otherwise. Master-detail layout. On large screens the list and detail sit side by side. On small
+screens, selecting a list item replaces the list with the detail pane.
+
+```tsx
+<SplitPage
+  listViewData={items}
+  renderListViewItem={({item}) => <Text>{item.name}</Text>}
+  renderContent={(index) => <ItemDetail index={index} />}
+/>
+```
+
+## Responsive breakpoints
+
+Policy: `docs/explanation/responsive-design.md`. Width tables: `docs/reference/ui.md`.
+
+Box supports `smDirection`, `mdDirection`, `lgDirection`, and `xlDirection`. Tokens are
+platform-specific: native `sm` 320 / `md` 375 / `lg` 600 / `xl` 1024; web `lg` 1024 / `xl` 1280.
+The desktop floor is `isSupportedDesktopWidth({width})`: web `lg` and native `xl`, both 1024pt.
+Below that floor, keep the mobile layout. Native tablets (`lg`, 600–1023pt) do not get the desktop split.
+
+```tsx
+<Box direction="column" mdDirection="row" lgDirection="row" xlDirection="column">
+```
+
+## Do not
+
+- Use raw `View` when Box props cover the need
+- Use `Dimensions.get()` — prefer `useWindowDimensions` if sizing is needed
+- Add a raw pixel cutoff such as 768. Use Box breakpoint props or `isSupportedDesktopWidth`
+- Use `SafeAreaView` — Page handles safe areas
+- Put hex colors in style when `color="primary"` works

package/skills/terreno-ui/references/theming.md

@@ -0,0 +1,87 @@
+# Theming — @terreno/ui
+
+## Three-layer architecture
+
+1. **Primitives** — raw color/spacing values (`neutral500`, `primary500`, `spacing4`)
+2. **Config** — semantic maps (`text.primary`, `surface.base`, `border.default`)
+3. **Computed theme** — resolved values consumed by components
+
+## TerrenoProvider
+
+```tsx
+import {TerrenoProvider} from "@terreno/ui";
+
+<TerrenoProvider colorScheme="system">
+  <App />
+</TerrenoProvider>
+```
+
+Required at the app root. Provides theme context and toast support.
+
+## useTheme
+
+```tsx
+import {useTheme} from "@terreno/ui";
+
+const {colorScheme, colorSchemeSetting, setColorScheme, theme, setTheme, setPrimitives, resetTheme} =
+  useTheme();
+```
+
+## Component color props
+
+Use semantic props instead of hex:
+
+```tsx
+<Box color="base">           {/* theme.surface.base */}
+  <Text color="primary">     {/* theme.text.primary */}
+  <Text color="inverted">    {/* on dark backgrounds */}
+  <Text color="error">       {/* error state */}
+</Box>
+```
+
+Surface colors: `base`, `primary`, `disabled`, `error`, etc.
+Text colors: `primary`, `inverted`, `secondaryLight`, `error`, etc.
+Border colors: `default`, `dark`, `focus`, `error`, `success`, `warning`.
+
+## Spacing and radius
+
+Use numeric spacing props (0-12) on Box, Page padding, and gap:
+
+```tsx
+<Box padding={4} gap={3} rounding="md">
+```
+
+Radius tokens: `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `circle`.
+
+## Customizing theme
+
+```tsx
+setTheme({surface: {primary: "secondary500"}});
+setPrimitives({accent500: "#FF6B35"});
+```
+
+Reset with `resetTheme()`.
+
+## Fonts
+
+- Body: Nunito (`text` font family)
+- Headings: Titillium Web (`title` font family)
+
+Load fonts in root `_layout.tsx` via `useFonts` (see example-frontend).
+
+## Dark mode
+
+Set `TerrenoProvider colorScheme` to `"light"`, `"dark"`, or `"system"`.
+The default is deterministic `"light"`; `"system"` follows React Native's
+current system scheme. `themeColorSchemeOptions` exposes those three choices
+as Light, Dark, and Follow system. Call `setColorScheme("system")` to change
+the choice after startup. `colorSchemeSetting` keeps the selected choice, while
+`useTheme().colorScheme` is always the resolved `"light"` or `"dark"` value.
+The exported `lightThemeConfig` and `darkThemeConfig` match the Flourish Health
+Figma modes.
+
+## Do not
+
+- Hardcode `#hex` when a theme token exists
+- Use `style={{padding: 16}}` when `padding={4}` works
+- Import colors from a separate constants file instead of theme props

package/skills/update-docs/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: update-docs
+description: >-
+  Keep Terreno docs in sync whenever behavior, public API, architecture, or
+  operator workflow changes. Read architecture docs first; write Diátaxis pages
+  in the same slice; regenerate generated docs. Lifecycle composition: Pick when
+  behavior and docs change together; Roast proves docs; Brew is the final docs
+  gate.
+---
+# Update Docs
+
+Use whenever behavior, public API, architecture, or operator workflow changes. Docs are
+the architecture source. Code implements them.
+
+## When to run
+
+Always run in the same slice as the change. Skip only a pure internal refactor that does
+not change APIs, UI, architecture, data flow, env/config, or operator steps. Record that
+skip. Missing docs for a user-visible or architectural change is a failed slice.
+
+## Workflow
+
+1. **Read the current architecture**
+   - Open explanation and reference docs for the affected area before editing code or docs.
+   - If docs and code disagree, resolve both in this slice.
+
+2. **Map the change to Diátaxis**
+
+   | Change | Page |
+   | --- | --- |
+   | First-run path | `docs/tutorials/` |
+   | Operator task | `docs/how-to/` |
+   | API, props, env, commands | `docs/reference/` |
+   | Why the system is shaped this way | `docs/explanation/` |
+   | UI component | generated `docs/reference/components/` plus a demo story |
+
+   The one exception to this layout is the
+   [`testing plan`](../../references/testing-plan.md) spots. The e2e guide stays at
+   `docs/testing/e2e.md` (with any pages it links) and the manual
+   regression suites stay in `docs/regression/<area>.md`, or wherever the repository's
+   `## Testing conventions` table points. Never move them into a Diátaxis directory.
+
+   The [`user guide`](../../references/user-guide.md) is the other exception. It is
+   written for the app's end users, not developers: one page per feature under
+   `docs/user-guide/<area>/<feature>.md`, or wherever the repository's
+   `## User guide conventions` table points. When a change alters what a user sees or
+   does, update its guide page with the Diátaxis pages, in the user-guide page format.
+
+3. **Write the page**
+   - Update the existing section in place.
+   - Lead with the next action or canonical fact.
+   - Use the page's standard headings. Prefer tables.
+   - One minimal current example. No implementation chronology.
+   - Never hand-edit generated output.
+
+4. **Regenerate generated docs** when UI types or OpenAPI-derived pages change:
+
+   ```bash
+   cd ui && bun run compile && bun run types
+   bun run website:generate
+   ```
+
+5. **Verify**
+
+   ```bash
+   bun run website:build
+   ```
+
+6. **Sync agent copies** when agent-facing guidance changed:
+
+   ```bash
+   bun run rules
+   bun run skills:sync
+   ```
+
+7. **Record** every docs file created or updated in the PR `Verification` table.
+
+## Integration
+
+Pick, Roast, and Brew require this skill for user-visible or architectural work.
+Brew does not open or update the PR until the docs in this slice match the shipped
+behavior.

package/skills/upgrading-terreno/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: upgrading-terreno
+description: >-
+  Upgrade Terreno lockstep @terreno/* packages. Trigger with "upgrade Terreno",
+  "bump @terreno packages", "update to the latest Terreno", or "upgrade terreno version".
+targets: ['*']
+---
+
+# Upgrade Terreno
+
+Perform a lockstep `@terreno/*` upgrade. Human-facing twin: `docs/how-to/upgrade-terreno.md`. Ordering detail: [references/ordering.md](references/ordering.md).
+
+Do **not** duplicate Expo SDK steps. At step 6 invoke the `upgrading-expo` skill by name.
+
+## Preconditions (refuse, do not warn)
+
+Stop immediately and do not mutate the tree if any of these fail:
+
+1. `git status --short` is **not empty** — refuse. Ask the user to commit or stash. A dirty tree has no safe rollback.
+2. The current branch is the default branch (`master` or `main`) — refuse. Create or switch to a feature branch first.
+3. Tests on this HEAD have not been shown passing — refuse. Run the app’s usual test command once so later failures are attributable to the upgrade.
+
+## Determine versions
+
+1. Prefer MCP `application_info` from `terreno-mcp-local`.
+2. Else read every `package.json` that lists `@terreno/*`.
+3. `fromVersion` = lowest installed `@terreno/*` semver. `toVersion` = user target or latest GitHub release.
+
+## Fetch notes
+
+Call hosted MCP `terreno_get_upgrade_guide` with `fromVersion` and `toVersion`. Read every concatenated note. A “no bundled notes” line means **unknown**, not no-op.
+
+## Syncdb / RTK platform migration
+
+If `fromVersion` is before `56.0.0-beta.2` and `toVersion` is `56.0.0-beta.2` or later, **stop**. This range crosses `@terreno/syncdb` and the RTK collection-CRUD deprecation. It is a platform migration, not a routine bump.
+
+Offer exactly two options; do not automate the data-layer migration inside this flow:
+
+1. Routine lockstep bump only (stay on RTK collection hooks for now).
+2. Separate follow-up: `docs/how-to/migrate-rtk-to-syncdb.md`.
+
+Wait for the user to pick.
+
+## Plan and confirm (no mutations yet)
+
+Print, then **stop until the user confirms**:
+
+- `fromVersion` and `toVersion`
+- Notes returned (or the gap warning)
+- Packages affected
+- Ordered steps 1–10 below
+
+Do not install, edit lockfiles, or regenerate the client before confirmation.
+
+If the caller is an unattended agent whose **invoking task already names** `fromVersion`, `toVersion`, and authorizes the bump (for example Pick Task 5.1), print the same plan into the transcript and treat that task as confirmation. Do not skip the printed plan. Do not skip the stop when a human is in the loop.
+
+## Ordered steps (verification gate after each phase)
+
+Match `docs/how-to/upgrade-terreno.md`. After each phase, run its gate. **If compile or tests fail, stop. Do not continue.**
+
+Compile means a **typecheck** (`tsc --noEmit` or `bun run compile` when that script typechecks). `bun build` / bundlers that ignore TypeScript errors are not a passing gate.
+
+1. Clean git tree + branch (already enforced).
+2. Record current `@terreno/*` versions (`application_info` / `package.json`).
+3. `terreno_get_upgrade_guide` for the range (already fetched). Apply note migrations that are code edits **after** confirmation, in this same order.
+4. Bump **backend** packages: `@terreno/api`, `@terreno/test`, `@terreno/admin-backend`, `@terreno/blocks` (when the app lists it; `ai` and `ui` depend on it), `@terreno/ai`, `@terreno/api-health`, `@terreno/comms`, `@terreno/feature-flags`, `@terreno/mcp`. `bun install`.
+5. Backend `bun run compile` and backend tests. Gate: both pass.
+6. Expo SDK — invoke **`upgrading-expo`**. Skip only when Terreno majors do not require a new Expo (same Expo line). Gate: `npx expo-doctor` / install --fix as that skill requires; native rebuild if peers moved.
+7. Bump **frontend** packages: `@terreno/ui`, `@terreno/rtk`, `@terreno/syncdb`, `@terreno/admin-frontend`, `@terreno/admin-spa`. `bun install`.
+8. Start the **upgraded** backend. Regenerate the typed client (`bun run sdk` in the frontend).
+9. `bun run compile`, `bun run lint`, and the app tests. Gate: all pass.
+10. Run the app, log in, exercise changed screens.
+
+## Failure handling
+
+Report all three:
+
+1. What succeeded (last passing step number).
+2. What failed (command and first error line).
+3. Rollback: `git reset --hard` on this branch, or `git checkout <pre-upgrade-sha> -- package.json bun.lock && bun install`.
+
+On a **multi-version** jump failure: retry **version by version** (`from` → next recorded note version → …) to isolate the breaking version. Keep the failing consumer file. The first version whose typecheck fails is the isolate. Do not continue past a failed compile or test run.
+
+## Final report
+
+Print `fromVersion` → `toVersion`, notes applied, packages bumped, gates that passed, and remaining human follow-ups (native store binaries, RTK migration if deferred).