@terreno/mcp 57.14.0 → 57.16.1

package/dist/docs/versioned/57.15.0/how-to/add-gpt-chat-mascot.md

@@ -0,0 +1,92 @@
+# Add a GPT chat mascot
+
+Pass a `mascot` node into `GPTChat`. Terreno does not ship a character — the consumer owns the image, Lottie, icon, or copy.
+
+## When it shows
+
+| Chat state | Mascot |
+| --- | --- |
+| `currentMessages` is empty | Rendered, centered in the chat panel above suggested prompts |
+| One or more messages | Hidden |
+
+The empty state fills the message area and centers both axes. GPTChat sizes that hero to the message viewport so a short mascot stays centered, and the same scroller still reaches a large mascot, suggested prompts, or an open keyboard. Streaming feedback stays with the centered hero until the first message arrives. Size the mascot for a hero slot (`Heading size="2xl"`, a large `Image`, or a Lottie view).
+
+Omit `mascot` to keep the default empty chat (prompts only, or a blank panel).
+
+## Steps
+
+### 1. Build the node in your app
+
+Keep the asset in the consumer package. `GPTChat` only mounts whatever you pass.
+
+```tsx
+import {Box, Heading} from "@terreno/ui";
+import {Image} from "react-native";
+import {useState} from "react";
+
+const MASCOTS = [
+  require("../assets/mascot-1.png"),
+  require("../assets/mascot-2.png"),
+  require("../assets/mascot-3.png"),
+  require("../assets/mascot-4.png"),
+];
+
+const ChatScreen: React.FC = (): React.ReactElement => {
+  // Select once per screen mount; ordinary re-renders keep the same character.
+  const [mascot] = useState(() => MASCOTS[Math.floor(Math.random() * MASCOTS.length)]);
+
+  return (
+    <GPTChat
+      currentMessages={currentMessages}
+      histories={histories}
+      mascot={
+        <Box alignItems="center" gap={3}>
+          <Image
+            accessibilityLabel="App mascot"
+            resizeMode="cover"
+            source={mascot}
+            style={{borderRadius: 112, height: 224, width: 224}}
+          />
+          <Heading align="center" size="md">Ask anything.</Heading>
+        </Box>
+      }
+      onCreateHistory={handleCreateHistory}
+      onDeleteHistory={handleDeleteHistory}
+      onSelectHistory={handleSelectHistory}
+      onSubmit={handleSubmit}
+    />
+  );
+};
+```
+
+For a single fixed mascot, pass one asset directly instead of selecting from an array.
+
+### 2. Pass it to `GPTChat`
+
+```tsx
+<GPTChat
+  currentMessages={currentMessages}
+  histories={histories}
+  mascot={ChatMascot}
+  onCreateHistory={handleCreateHistory}
+  onDeleteHistory={handleDeleteHistory}
+  onSelectHistory={handleSelectHistory}
+  onSubmit={handleSubmit}
+  suggestedPrompts={["What can you help with?"]}
+/>
+```
+
+### 3. Confirm empty vs thread
+
+Open a new chat: the mascot is visible. After the first user or assistant message, it is gone.
+
+## Example
+
+The example app bundles four consumer-owned plant robots in
+`example-frontend/assets/gptMascots/` and selects one on each AI screen mount. The
+demo story `GPTChat` → `Mascot` shows the slot without a backend.
+
+## Related
+
+- [`GPTChat` props](../reference/ui.md#gptchat)
+- Demo: `http://localhost:8085/dev/GPTChat?story=Mascot`

package/dist/docs/versioned/57.15.0/how-to/add-organizations.md

@@ -0,0 +1,204 @@
+# Add organizations to a Terreno app
+
+Enable organizations only when the app is multi-tenant. Existing single-tenant
+apps can omit every option in this guide.
+
+## 1. Enable organization RBAC
+
+``````typescript
+import {createAccess, terrenoStatements} from "@terreno/api";
+
+export const access = createAccess({
+  connection: mongoose.connection,
+  organizations: true,
+  statements: terrenoStatements,
+  userModel: User,
+});
+
+await access.roles.seedDefaults();
+``````
+
+This adds Membership-based `org-admin` grants and seeds the locked `operator`
+role. It does not change apps that omit `organizations`.
+
+## 2. Mount organization routes
+
+``````typescript
+const app = new TerrenoApp({
+  accessControl: access,
+  organizations: true,
+  userModel: User,
+});
+``````
+
+This mounts `OrgsApp` at `/orgs`. To configure audit handling or a different
+path, pass an options object:
+
+``````typescript
+organizations: {
+  basePath: "/organizations",
+  onOrgAudit: recordOrganizationAudit,
+  settingsSchema: organizationSettingsSchema,
+}
+``````
+
+## 3. Type organization settings
+
+Keep native `Organization` fields unchanged. Put app fields on
+`Organization.settings` with a nested Mongoose schema and a TypeScript
+interface.
+
+1. Declare the settings shape (optional module augmentation):
+
+``````typescript
+// src/types/models/organizationSettingsTypes.ts
+export interface ExampleOrganizationSettings {
+  timezone?: string;
+}
+
+declare module "@terreno/api" {
+  interface OrganizationSettings extends ExampleOrganizationSettings {}
+}
+``````
+
+2. Build the nested schema. Use optional fields or defaults so existing
+organizations still validate:
+
+``````typescript
+// src/models/organizationSettings.ts
+import {createOrganizationSettingsSchema} from "@terreno/api";
+import type {ExampleOrganizationSettings} from "../types/models/organizationSettingsTypes";
+
+export const organizationSettingsSchema = createOrganizationSettingsSchema<ExampleOrganizationSettings>({
+  timezone: {
+    description: "IANA timezone used for organization-local dates",
+    type: String,
+  },
+});
+``````
+
+3. Register before you create or patch organizations (startup and seeds):
+
+``````typescript
+import {registerOrganizationSettings} from "@terreno/api";
+import {organizationSettingsSchema} from "./models/organizationSettings";
+
+registerOrganizationSettings(organizationSettingsSchema);
+``````
+
+Or pass the same schema on `TerrenoApp` / `OrgsApp`:
+
+``````typescript
+new TerrenoApp({
+  accessControl: access,
+  organizations: {settingsSchema: organizationSettingsSchema},
+  userModel: User,
+});
+``````
+
+Read typed settings with `organizationSettingsOf(organization)` or
+`organizationSettingsOf<ExampleOrganizationSettings>(organization)`.
+
+Without a registered schema, `settings` stays Mixed and accepts any object.
+Unknown keys and wrong types fail with **400** `Organization settings are invalid`
+once a schema is registered.
+
+## 4. Scope tenant models
+
+Add `orgScopedPlugin` to models that use ObjectId organization keys. Put
+`orgContextMiddleware({required: true})` before their routes, use
+`OrgQueryFilter` for lists, and overwrite client organization ids during
+create:
+
+``````typescript
+import {
+  authenticateMiddleware,
+  getOrgContext,
+  modelRouter,
+  OrgQueryFilter,
+  orgContextMiddleware,
+  orgScopedPlugin,
+  Permissions,
+  type TerrenoPlugin,
+} from "@terreno/api";
+import type express from "express";
+
+schema.plugin(orgScopedPlugin);
+
+const projectOrgContextPlugin: TerrenoPlugin = {
+  register(expressApp: express.Application): void {
+    expressApp.use(
+      "/projects",
+      authenticateMiddleware(),
+      orgContextMiddleware({required: true})
+    );
+  },
+};
+
+const projectRouter = modelRouter("/projects", Project, {
+  permissions: {
+    create: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
+    delete: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
+    update: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
+  },
+  preCreate: (body, _req) => ({
+    ...body,
+    organizationId: getOrgContext()?.organization?._id,
+  }),
+  queryFilter: OrgQueryFilter,
+});
+
+app.register(projectOrgContextPlugin).register(projectRouter);
+``````
+
+For admin CRUD, use `new AdminApp({accessControl: access, organizations:
+true})`. Models with an `organizationId` schema path are scoped automatically,
+except `AuditEvent` (the platform audit log lists without a selected org).
+Admin-window `POST /sync/mutate` and socket `sync:mutate` use the same membership
+check as REST for update and delete when `X-Organization-Id` (HTTP) or
+`organizationId` (socket payload) is set. Admin `createSyncDb({organizationIdProvider})`
+sends that id on every mutate.
+
+`orgScopedPlugin` also makes `organizationId` immutable after the document is
+created. Client PATCH bodies, admin writes, sync updates, and direct Mongoose
+saves that change `organizationId` return HTTP 400 with
+`organizationId cannot be changed`.
+
+## 5. Send organization context
+
+Send `X-Organization-Id` on tenant-scoped requests. `org-admin` callers with
+exactly one administered organization may omit it; Terreno infers that org.
+Operators and superadmins must select an org.
+
+Frontend admin hosts use `OrgContextProvider` + `OrgSwitcher`.
+`useAdminApi` adds the selected organization header automatically.
+
+Disabled organizations are excluded from `/orgs/mine` and cannot be selected as
+tenant context. Operators re-enable them from the organization directory UI or
+with `PATCH /orgs/:id` and `disabled: false` (see
+[How organization tenancy works](../explanation/organizations.md#disabled-organizations)).
+
+Creating or renaming an organization to a name that generates an existing slug,
+including a slug still held by a **soft-deleted** organization, returns **409**
+`Organization name already in use`. `OrgSwitcher` hides itself
+when `/orgs/mine` returns **403** for callers without org-admin memberships.
+
+## Example app accounts
+
+After `bun run backend:seed`, all accounts use password `testpassword123`:
+
+| Account | Access |
+| --- | --- |
+| `operator@example.com` | Platform organization directory; may enter either org |
+| `orgadmin-alpha@example.com` | Org admin for Alpha Workspace |
+| `orgadmin-beta@example.com` | Org admin for Beta Workspace |
+| `test@example.com` | Member of Alpha Workspace |
+| `admin@example.com` / `superadmin@example.com` | Existing example superadmin accounts |
+
+The seed creates Alpha Workspace and Beta Workspace plus two projects in Alpha
+Workspace. Membership rows, not fields on User, are the source of tenant access.
+In-process Better Auth seeding sets `disableRateLimit: true` so production
+preview smoke tests can create all six accounts without hitting Better Auth's
+sign-up limiter.

package/dist/docs/versioned/57.15.0/how-to/admin-add-model.md

@@ -0,0 +1,52 @@
+# Add a model to the admin
+
+Generic table/form routes are already in the host app. Do not add an Expo file per
+model. For screens and nav, see [Build admin screens](build-admin-screens.md).
+
+Add `admin` directly to the model's existing `modelRouter` options:
+
+```ts
+export const userRouter = modelRouter("/users", User, {
+  admin: {
+    displayName: "Users",
+    listFields: ["email", "name", "admin", "created"],
+    searchFields: ["email", "name"],
+    sortableFields: ["email", "name", "created"],
+    filters: [{field: "admin", kind: "boolean", label: "Admin user"}],
+  },
+  permissions: {
+    create: [Permissions.IsAdmin],
+    delete: [Permissions.IsAdmin],
+    list: [Permissions.IsAdmin],
+    read: [Permissions.IsAdmin],
+    update: [Permissions.IsAdmin],
+  },
+});
+```
+
+Register that router with `TerrenoApp`, then register `AdminApp`. The model appears in
+`GET /admin/config` and at `/admin/User` without a duplicate `AdminApp.models` entry.
+
+If the same Mongoose model is mounted at two `routePath`s (different filters or list
+columns), `/admin/config` keeps `name` as the model name for the registered entry and
+suffixes the others with the route slug (for example `Food-archived-foods`) so each list
+is reachable.
+
+Common fields:
+
+- `listFields`: columns and fields exposed to admin CRUD.
+- `searchFields`: string fields matched by the list search box (`q`) as a
+  case-insensitive partial (`$regex`) query.
+- `sortableFields`: the only columns with sorting enabled.
+- `filters`: typed list filters rendered on `DataTable` column headers (web) or the
+  mobile **Filters** sheet. `text` filters are case-insensitive contains (`$regex`);
+  `choice` filters support multi-select (`$in`); `ref` stays a single ObjectId. The
+  backend accepts only escaped literal regex patterns and rejects extra nested operators.
+  Optional choice fields (Mongoose path not `required`) automatically expose an **Empty**
+  filter option; set `allowEmpty: false` on the filter config to hide it, or
+  `allowEmpty: true` on required fields when you intentionally want unset matching.
+  Empty filters can be combined with toolbar search or concrete choices. The wire
+  sentinel is consumed before Mongo receives the query.
+- `fieldsets`: grouped form sections.
+- `readonlyFields` / `hiddenFields`: display-only or omitted form fields.
+- `adminPermissions`: optional admin-specific permission methods.

package/dist/docs/versioned/57.15.0/how-to/admin-custom-home.md

@@ -0,0 +1,34 @@
+# Customize the admin home
+
+Home widgets sit in the admin shell. Screen and sidebar rules:
+[Build admin screens](build-admin-screens.md).
+
+Configure home slots on `AdminApp`:
+
+```ts
+new AdminApp({
+  home: {
+    title: "Operations",
+    slots: {
+      contentTop: ["feature-flags-overrides"],
+      main: ["modelStats"],
+      navGlobal: ["scriptRunner"],
+      sidebar: ["versionConfig", "recentActivity"],
+    },
+  },
+});
+```
+
+Built-in IDs include `modelStats`, `modelsGrid`, `scriptRunner`, `versionConfig`, and
+`recentActivity`. Plugins add IDs such as `feature-flags-overrides`.
+
+For an app-specific widget, implement `AdminHomeWidgetProps` and register it:
+
+```tsx
+<AdminProvider widgets={{home: {operationsSummary: OperationsSummary}}} api={api}>
+  <AdminHome api={api} />
+</AdminProvider>
+```
+
+Then place `"operationsSummary"` in a home slot. Unknown IDs render a visible missing-widget
+placeholder in development instead of crashing the dashboard.

package/dist/docs/versioned/57.15.0/how-to/admin-custom-widget.md

@@ -0,0 +1,45 @@
+# Add a custom admin field widget
+
+Field widgets are one of three admin widget buckets. Screen and nav rules:
+[Build admin screens](build-admin-screens.md).
+
+1. Name the widget in model admin metadata:
+
+```ts
+admin: {
+  displayName: "Articles",
+  listFields: ["title", "body"],
+  fieldOverrides: {body: {widget: "rich-text"}},
+}
+```
+
+2. Implement the field widget:
+
+```tsx
+const RichTextWidget: React.FC<AdminFieldWidgetProps> = ({
+  value,
+  onChange,
+  readOnly,
+}) => (
+  <RichTextEditor
+    disabled={Boolean(readOnly)}
+    onChange={onChange}
+    value={typeof value === "string" ? value : ""}
+  />
+);
+```
+
+3. Register it once around the admin routes:
+
+```tsx
+<AdminProvider
+  api={api}
+  apiBase="/admin"
+  routeBase="/admin"
+  widgets={{fields: {"rich-text": RichTextWidget}}}
+>
+  <AdminRoutes />
+</AdminProvider>
+```
+
+Host registrations override built-ins with the same ID.

package/dist/docs/versioned/57.15.0/how-to/admin-import-prebuilt.md

@@ -0,0 +1,31 @@
+# Import pre-built admins
+
+Register first-party plugins on the same `TerrenoApp` as `AdminApp`:
+
+```ts
+import {JobsApp} from "@terreno/jobs";
+
+const app = new TerrenoApp({userModel: User})
+  .register(new FeatureFlagsApp())
+  .register(new ConsentApp({auditTrail: true}))
+  .register(new DocumentStorageApp({bucketName: process.env.GCS_BUCKET ?? ""}))
+  .register(new AIAdminApp())
+  .register(new JobsApp({accessControl})) // optional — needs admin:access + admin:jobs
+  .register(new AdminApp({home: {slots: {main: ["modelStats", "jobs"]}}}));
+```
+
+`AdminApp` aggregates each plugin's `adminContribution()`:
+
+- `FeatureFlagsApp`: FeatureFlag model and `feature-flags-overrides` home widget.
+- `ConsentApp`: ConsentForm and ConsentResponse models plus consent field-widget IDs.
+- `DocumentStorageApp`: `documents` custom screen. Pass `fileUploadsEnabled: false` (or a function that returns `false`) to reject uploads while listing and download stay available. The example app wires this to the `file-uploads` feature flag.
+- `AIAdminApp`: `ai-requests` custom screen and explorer API.
+- `JobsApp`: `jobs` custom screen and home widget (`dead` / `running` counts). With
+  `accessControl`, requires **both** `admin:access` and `admin:jobs`; without it, legacy
+  `user.admin`. See [Durable background jobs](background-jobs.md).
+
+Wrap frontend admin routes in `AdminProvider`. First-party widgets are already in the built-in
+registry, so no consumer-side switch statement or custom-screen map is required.
+
+`featureFlagAdminConfig` and `AdminApp.models` remain compatibility paths, but new integrations
+should use plugin contributions and `modelRouter({admin: ...})`.