@terreno/mcp 57.2.0 → 57.4.0

package/src/docs/versioned/next/explanation/schema-metadata.md

@@ -0,0 +1,60 @@
+# Schema metadata (`describeModel`)
+
+Terreno walks each Mongoose schema **once** and builds a `ModelDescription` field graph. OpenAPI, admin config, and MCP tools are **views** of that graph — they do not re-walk `schema.paths` independently.
+
+## Why one descriptor
+
+Before `describeModel`, three surfaces each interpreted Mongoose differently:
+
+- **OpenAPI** — `mongoose-to-swagger` in `getOpenApiSpecForModel`
+- **Admin** — OpenAPI property walk plus Mongoose ref patching in `extractFieldMeta`
+- **MCP** — `schema.paths` + `SchemaType.instance` switch in `schemaGenerator`
+
+That drifted on refs, enums, nested arrays, and system fields. A single descriptor keeps field facts in one place.
+
+## Core API
+
+```typescript
+import {describeModel, describeModelForRouter} from "@terreno/api";
+
+const description = describeModel(Todo);
+// description.fields[path].kind, .required, .description, .enum, .ref, .isArray, .item, .system
+
+const routerDescription = describeModelForRouter(Todo, {
+  validation: {excludeFromCreate: ["ownerId"]},
+  fieldView: {read: "*", write: ["title", "completed"]},
+});
+// adds writableOnCreate / writableOnUpdate per field
+```
+
+## Field kinds
+
+| Kind | Mongoose source | Notes |
+|------|-----------------|-------|
+| `string` | String | Includes enum strings |
+| `number` | Number | |
+| `boolean` | Boolean | |
+| `date` | Date | ISO date-time in OpenAPI |
+| `dateOnly` | DateOnly | Custom Terreno type |
+| `objectId` | ObjectId | Carries `ref` model name |
+| `embedded` | Subdocument / array of subdocuments | Nested `fields` |
+| `mixed` | Mixed | Accepts any value in OpenAPI |
+| `map` | Map | `item` follows Map `of` (omitted `of` is `mixed`); OpenAPI `additionalProperties` |
+
+System paths (`_id`, `__v`, `created`, `updated`, `deleted`) are marked with `system: true`.
+
+## Views (not canonical)
+
+| Surface | Function | Notes |
+|---------|----------|-------|
+| OpenAPI | `modelDescriptionToOpenApiSpec` | Used by `getOpenApiSpecForModel`; populate still merges referenced models |
+| Admin `/admin/config` | `modelDescriptionToAdminFields` | Widget choice stays in admin-backend |
+| MCP Zod | `fieldDescriptionToZodType` | Create/update tools omit system fields |
+
+Populate paths remain a `getOpenApiSpecForModel` concern; the descriptor records `ref` on the local path only.
+
+## Related
+
+- [API reference — describeModel](../reference/api.md#describemodel)
+- [How to create a model](../how-to/create-a-model.md)
+- [Admin backend reference](../reference/admin-backend.md)

package/src/docs/versioned/next/explanation/source-rules.md

@@ -0,0 +1,57 @@
+# Production source rules
+
+Terreno production TypeScript follows six mechanical conventions. This page is the
+policy those conventions implement. CI fails a PR that introduces a new production
+file (or a new hit in an existing file) that would trip them.
+
+## Scope
+
+`{api,ui,rtk,ai,admin-backend,admin-frontend,example-backend}/src/**/*.{ts,tsx}`
+
+`example-frontend` and `demo` are listed in the original align glob but have no `src/`
+tree (`app/`, `components/`, `stories/` instead), so this scanner does not cover them.
+
+Skipped: tests (`*.test.*`, `*.spec.*`, `*.isolated.*`, `__tests__`), generated SDKs
+(`openApiSdk.ts`, `*OpenApiSdk.ts`), declaration files (`*.d.ts`), `node_modules`, `dist`,
+and test harness files such as `bunSetup.ts`.
+
+## Rules
+
+| Rule | Ban | Use instead |
+| --- | --- | --- |
+| Arrow functions | `function` declarations | `const name = (…) => {…}` |
+| Luxon | `new Date(`, `Date.now()` | `DateTime` from `luxon` |
+| API errors (backend) | `throw new Error(` | `throw new APIError({…})` |
+| Logging | `console.log(` | Backend `logger.*`; frontend `console.info` / `warn` / `error` |
+| Mongoose reads (backend) | `Model.findOne(` | `findExactlyOne`, `findOneOrNone`, `findOneOrNoneFor` |
+| Explicit any | `as any` | Precise types, or `as unknown as T` |
+
+## Allowed leftovers
+
+These still match a naive grep and are **not** violations:
+
+- Mongoose hooks, statics, methods, and virtuals that need `this` (`schema.pre`, `.post`, `.method`, `.statics`, `.virtual`). A nearby hook does not whitelist a later `function` in the same file.
+- TypeScript overload signatures plus their implementation (`modelRouter`)
+- `React.forwardRef(function …)` and `*.prototype.* = function` patches that close over `this`
+- Raw Mongo `collection.findOne`
+- `as any` with a line-level `biome-ignore lint/suspicious/noExplicitAny`
+- Hits inside comments or string literals
+
+## Commands
+
+```bash
+bun run check:source-rules
+bun test scripts/check-source-rules/
+```
+
+## Enforcement
+
+| Layer | What it does |
+| --- | --- |
+| **`bun run check:source-rules`** | Scans scoped production sources and fails on any remaining hit |
+| **Repository policies CI** | CircleCI job `repo-policies` (includes `check:source-rules`) |
+| **`bun run check`** | Local aggregate that includes this scanner |
+
+A **new** production file that uses `export function`, `Date.now()`, `throw new Error`, `console.log`, `Model.findOne`, or unsuppressed `as any` fails CI.
+
+Do not add suppress comments for these rules. Fix the code, or use one of the allowed leftovers above.

package/src/docs/versioned/next/explanation/static-analysis.md

@@ -0,0 +1,135 @@
+# Static analysis
+
+Run `bun run analyze:full` before pushing changes that alter imports, exports, package
+dependencies, or module boundaries.
+
+Taste does not need to infer that policy in this repository. The root `prepush` package
+script is the canonical local gate and runs lint, TypeScript compilation, and full static
+analysis:
+
+```bash
+bun run prepush
+```
+
+The reusable Taste stage checks for a root `prepush` script before every push and runs it
+in a fresh, no-context subagent. Repositories without one retain Taste's fallback:
+package-level lint, typecheck, and locally affected tests.
+
+Terreno uses two analysis speeds so agents receive quick edit feedback without replacing
+repository-wide correctness checks with a partial changed-file scan.
+
+## Analysis layers
+
+| Layer | Command | Scope | Enforcement |
+| --- | --- | --- | --- |
+| Biome | `bun run analyze:fast` | Changed and untracked analyzable files | Agent post-edit hooks |
+| Biome | `bun run analyze:staged` | Staged analyzable files | Git pre-commit |
+| Knip | `bun run check:knip` | Both development and production module graphs | Dedicated GitHub workflow |
+| Knip | `bun run analyze:full` | Both development and production module graphs | Agent stop hooks and CircleCI |
+| dependency-cruiser | `bun run analyze:full` | Workspace source dependency graph | Agent stop hooks and CI |
+
+Biome runs from the nearest workspace configuration. Knip finds unused files, exports,
+types, dependencies, binaries, and duplicate exports. dependency-cruiser rejects new
+cycles and production imports from test or isolated modules while reporting orphan
+modules.
+
+Knip ignores `**/dist/**` so analysis reports the same findings whether or not the
+workspace has been compiled. CI analyzes a fresh checkout and never builds, while local
+development runs `bun run bootstrap`; without that exclusion, each package's compiled
+`dist/*.d.ts` entry point contributes unlisted-dependency findings that CI can never
+reproduce.
+
+## Entry graph
+
+Knip only follows files reachable from entries. Register executed-but-unimported files
+in `knip.jsonc` `workspaces.<name>.entry` instead of deleting them or stuffing them into
+the JSON baseline.
+
+Setting `entry` **replaces** Knip’s default `{index,cli,main}` / `src/{index,cli,main}`
+patterns for that workspace, so those defaults must be repeated next to extra globs.
+
+| Kind | Why Knip misses it | Entry |
+| --- | --- | --- |
+| `*.isolated.ts(x)` | Run as `bun test $file`, not `*.test.ts` | `src/isolated/**/*.isolated.{ts,tsx}` on the owning package |
+| `scripts/**/*.test.ts`, `.github/scripts/**/*.test.ts` | Root `test` is `bun run --filter '*' test:ci`, so the Bun plugin never loads them | Root workspace `"."` |
+| `example-frontend/e2e/**/*.ts` | Playwright helpers and setup files are executed through project configuration, not app imports | `example-frontend` entry glob |
+| Generated SDK contracts not yet imported by a screen | Codegen output is retained for compatibility verification | `ignoreFiles` for only the unused-file issue; exports and dependencies remain analyzed |
+| OpenAPI codegen configs, Metro `jspdf` stubs, Expo fingerprint configs, Playwright CI config, `ui/babel.config.js`, Docusaurus `src/theme/**` swizzles, `scripts/ci/prepare-package-publish.mjs` | Invoked by Expo/Metro/Docusaurus/CI, not imported from app `index` | Extra `entry` globs on the owning workspace |
+| Generated `expo-cicd-workflows/scripts/*.js` (including `.rulesync/`) | Skill copies; they import `ajv` / `js-yaml` outside this repo’s package graph | `ignore` globs |
+| `example-backend` production dependencies | Knip's package-script entry for `bun run src/index.ts` shadows the explicit `src/index.ts!` entry in production mode | Keep default-mode enforcement; use exact dependency names suffixed with `!` as production-only exceptions |
+| `mcp-server/src/__tests__/preload.ts` | `bunfig.toml` `test.preload`; Knip's Bun plugin is disabled for this workspace | `mcp-server` extra entry |
+
+## Runtime-only dependencies
+
+Do not remove an Expo, React Native, or Metro dependency solely because Knip cannot find
+a static import. Expo autolinking, `app.json` plugin strings, Metro aliases/polyfills,
+platform-specific modules, and published UI peer surfaces load dependencies outside
+Knip's source graph. Keep those dependencies in the owning `package.json` and list them
+under that workspace's `ignoreDependencies` in `knip.jsonc`, with a comment naming the
+runtime loader.
+
+The same rule covers externally installed CLIs (`maestro`, `eas`), catalog pins retained
+for native fingerprint compatibility, and optional peers consumed by published-package
+users. Declare those narrowly with `ignoreBinaries` or `ignoreDependencies`; do not add a
+fake local import.
+
+## Exports and test seams
+
+Remove `export` from unused module internals. Keep published package-entry exports for
+compatibility even when this monorepo has no consumer; suppress only their `exports` or
+`types` issue on the defining file, with a public-API comment in `knip.jsonc`.
+
+Some internal helpers are intentionally exported so tests can exercise deterministic
+logic without widening the npm entry point. Mark those declarations `@internal`: default
+Knip still proves that tests use them, while production mode excludes the test-only seam.
+Generated SDK files use a path-scoped `ignoreIssues` entry instead of hand edits.
+
+## Zero-finding policy
+
+Knip has no baseline. `bun run check:knip` runs the default and production graphs and
+fails on every finding. The dedicated `Knip / Zero findings` GitHub workflow runs this
+command for every pull request and every push to `master`.
+
+Fix every Knip finding or add the narrowest justified exception to `knip.jsonc` with a
+comment naming the runtime loader, public compatibility promise, generated source, or
+tool limitation. Do not create a Knip baseline or any other separate finding inventory.
+
+dependency-cruiser still uses `.dependency-cruiser-known-violations.json` to ratchet its
+remaining findings. After intentionally accepting repository-wide dependency-graph
+changes, regenerate only that baseline:
+
+```bash
+bun run analyze:dependency-baseline
+bun run analyze:full
+```
+
+Review the dependency-cruiser baseline diff before committing; findings may only stay
+level or decrease. Never run `knip --fix` unattended because an incomplete entry graph
+can remove runtime-loaded code.
+
+## Agent hooks
+
+`.rulesync/hooks.json` is the hook source of truth. `bun run rules` translates it into
+native configuration for Cursor, Claude Code, Codex CLI, GitHub Copilot, Copilot CLI,
+Google Antigravity CLI, and Devin.
+
+Post-edit events run the changed-file Biome command. Stop events run both repository-wide
+ratchets. `analyze:full` retries Knip without `--cache` when a concurrent stop-hook and
+prepush run corrupt or lock the cache, so the stop hook does not fail with empty JSON.
+Hook failure and retry behavior differs by host, so CircleCI remains the merge
+gate and the real Git pre-commit hook covers commits made outside an agent.
+
+`simple-git-hooks` installs the pre-commit hook during `bun install` through the root
+`prepare` script.
+
+## Configuration ownership
+
+| File | Purpose |
+| --- | --- |
+| `knip.jsonc` | Entry graph, plugins, generated-code exceptions |
+| `.dependency-cruiser.js` | Dependency rules and resolver conditions |
+| `.rulesync/hooks.json` | Canonical agent lifecycle hooks |
+| `scripts/static-analysis/` | Portable direct Knip checks, dependency ratchet logic, and tests |
+
+Generated agent hook files must not be edited directly. Change `.rulesync/hooks.json`,
+then run `bun run rules`.

package/src/docs/versioned/next/explanation/versioning-policy.md

@@ -0,0 +1,35 @@
+# Versioning policy
+
+All published `@terreno/*` packages share one version. Upgrade them together. Mixing versions is unsupported.
+
+## Lockstep
+
+A git tag `X.Y.Z` (no `v` prefix) is the version for every package that `.github/workflows/publish-on-tag.yml` publishes: `api`, `test`, `ui`, `rtk`, `admin-backend`, `admin-frontend`, `admin-spa`, `ai`, `api-health`, `comms`, `feature-flags`, `mcp`, `syncdb`. Publish jobs read that tag; they do not pick per-package versions.
+
+Inside the monorepo, packages depend on each other with `workspace:*` (for example `@terreno/rtk` → `@terreno/ui`). On npm they are released at the same number. `@terreno/ui` also pins Expo-line peers (`react-native` `~0.86.0` on the 57 line). Installing `@terreno/ui@57` next to Expo 54 is outside support, same as mixing `@terreno/api@57` with `@terreno/ui@0.31`.
+
+## Pre-1.0 (and Expo-aligned majors)
+
+While the public API is still moving, a **minor** may include breaking changes. Those land only with an upgrade note in `mcp-server/src/docs/upgrades/<version>.md`. The changelog `### Breaking` / `### Changed` / `### Deprecated` / `### Removed` headings require that file (`bun run check:upgrade-docs`).
+
+From 56 onward the **major** tracks the Expo SDK major (`56.x`, `57.x`). That is not a 1.0 stability promise. It is a peer-stack label.
+
+## Deprecation window
+
+A public API marked deprecated stays available for **at least three minor releases** on the current major (example: deprecated in `57.1.0` → still present in `57.2.0` and `57.3.0`). Removal happens in a later minor or the next major, always with an upgrade note.
+
+Worked example: `@terreno/rtk` collection CRUD was deprecated in `56.0.0` (restated in `57.1.0`). The package still publishes on 57.x for the OpenAPI SDK, Better Auth Redux, feature flags, and sockets. It will not ship in the **next major**. Migrate collection screens with [migrate-rtk-to-syncdb.md](../how-to/migrate-rtk-to-syncdb.md) as a separate operation from a routine version bump.
+
+## Where to read changes
+
+| Source | Use |
+| --- | --- |
+| [`CHANGELOG.md`](../../CHANGELOG.md) | What shipped |
+| [`mcp-server/src/docs/upgrades/`](../../mcp-server/src/docs/upgrades/) | What you must do |
+| MCP `terreno_get_upgrade_guide` | Concatenated notes for `fromVersion` → `toVersion` |
+
+Note format: [`mcp-server/src/docs/upgrades/README.md`](../../mcp-server/src/docs/upgrades/README.md).
+
+## What 1.0 will mean
+
+OSS launch question P9 ([oss-launch-program.md](../implementationPlans/oss-launch-program.md)): 1.0 is an API-stability audit after syncdb has settled — not the Expo-aligned 57 line. Until that audit, treat minors as able to break with a note.

package/src/docs/versioned/next/how-to/README.md

@@ -12,22 +12,49 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 
 ## Contents
 
+- [Create a Terreno app](create-a-terreno-app.md) — Scaffold a full-stack app with `create-terreno-app` (Bun or npm)
+- [Update dependencies](update-dependencies.md) — Daily rolling PR, exercise test, Expo fingerprint freeze
 - [CircleCI](circleci.md) — Dual-run CI on CircleCI (package CI / policy / e2e; deploys later)
+- [Run tests locally](run-tests-locally.md) — Map every CircleCI test job to a Cursor Cloud / laptop command
+- [GitHub Actions CI](github-actions-ci.md) — Cut PR runtime: docs previews, compile-once e2e, pinned Bun
+- [Add feature flags](add-feature-flags.md) — Add feature flags, A/B testing, and OpenFeature migration
+- [Rate limiting](rate-limiting.md) — Opt-in HTTP limiter on `TerrenoApp` (memory or Redis)
+- [Receive inbound webhooks](inbound-webhooks.md) — HMAC, Stripe, Twilio, and SendGrid signatures on `WebhooksApp`
+- [Durable background jobs](background-jobs.md) — `@terreno/jobs`: enqueue, workers, schedules, Cloud Tasks / Vercel Queues
 - [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
+- [Enable the framework audit log](audit-log.md) — `AuditApp`, per-router `audit`, append-only events
+- [Seed a database](seed-a-database.md) — Idempotent sync, dry runs, and guarded reset-and-reseed
+- [Run MongoDB migrations](run-mongodb-migrations.md) — Versioned `up`/`down` files, `terreno-migrate`, production gate
 - [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
 - [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
+- [Password reset and email verification](password-reset.md) — JWT routes, comms templates, Better Auth hooks
 - [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
 - [Expose Model Context Protocol tools](expose-mcp-tools.md) — Turn `modelRouter` models into MCP tools an LLM can call
-- [Install agent skills](install-agent-skills.md) — Install Grow/Pick/Roast/Brew/Taste and domain skills with `npx skills`
+- [Connect an MCP client with a service token](connect-mcp-service-token.md) — Mint a personal `mcp_` key for Perplexity and other remote clients
+- [Install agent skills](install-agent-skills.md) — `npx skills`, the Cursor plugin, the Codex plugin, or the Claude Code plugin
+- [GitHub issue lifecycle](github-issue-lifecycle.md) — Create pick-ready issues, Pick ⇄ Roast, or unattended `status:ready-for-dev` pickup
 - [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
-- [Deploy to Google Cloud Platform](deploy-to-gcp.md) — Deploy demo and example apps to GCS with CDN
+- [Upgrade banner](upgrade-banner.md) — Soft warning and hard-block app update UX
+- [Upgrade Terreno](upgrade-terreno.md) — Lockstep `@terreno/*` bumps, note range, order, rollback
+- [Track upstream Expo](track-upstream-expo.md) — Morning probe for SDK betas; `release-X.Y.Z` loop log + native fingerprint deps
+- [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid`
+- [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md) — PNG goldens for the chart visual gallery, not JSON snapshots
 - [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer
+- [In-app notifications](in-app-notifications.md) — Register `NotificationsApp`, syncdb inbox, and UI bell
+- [Add organizations](add-organizations.md) — Opt into Membership-backed tenancy, RBAC, admin, and seeded examples
+- [Add a GPT chat mascot](add-gpt-chat-mascot.md) — Optional consumer-owned character on empty `GPTChat`
+
+## Admin
+
+- [Build admin screens](build-admin-screens.md) — Screens, sidebar nav, `routeBase`, custom screens
+- [Add a model to the admin](admin-add-model.md) — `modelRouter({admin: ...})` setup
+- [Import pre-built admins](admin-import-prebuilt.md) — Plugin `adminContribution()` wiring
+- [Add a custom admin field widget](admin-custom-widget.md) — Custom field widgets
+- [Customize the admin home](admin-custom-home.md) — Home slots and built-in widgets
 
 ## Coming Soon
 
-- [Add feature flags](add-feature-flags.md) — Add feature flags and A/B testing to your app
 - Add custom permissions
 - Implement file uploads
 - Configure email notifications
 - Customize AI workflows
-- Set up custom CI/CD pipelines

package/src/docs/versioned/next/how-to/add-feature-flags.md

@@ -109,6 +109,31 @@ Navigate to the admin panel in your app. The "Feature Flags" card appears automa
 - **Rules**: optional targeting (field-based or segment-based)
 - **Rollout Percentage**: gradual rollout for boolean flags (default 100%)
 
+## Migrating from `GET …/evaluate` (OpenFeature)
+
+Terreno's feature-flag stack uses **OpenFeature** (`@terreno/feature-flags` on the server, `@terreno/rtk` on the client). Use this checklist if you upgrade from a Terreno release that only documented `GET …/evaluate`.
+
+### Backend (`@terreno/feature-flags`)
+
+1. Keep **`FeatureFlagsApp`** registered as before; admin CRUD is unchanged.
+2. Prefer authenticated clients calling **`GET {basePath}/flagConfiguration`** — the JSON body matches OpenFeature's static configuration shape (for `TypedInMemoryProvider` on the client).
+3. **`GET {basePath}/evaluate`** still returns the legacy `Record<key, boolean | string | null>` map but is **deprecated** (`Deprecation: true`, `Sunset` header). Migrate direct HTTP or hand-written clients to `/flagConfiguration`, or rely on `@terreno/rtk` hooks below.
+4. **`FeatureFlag`** documents gain optional **`defaultVariant`** (boolean: `"on"` / `"off"`; variant: a key from `variants`). Omitted values are filled on save. For existing databases, run a one-off backfill or reuse the pattern in `example-backend/src/scripts/seed-feature-flags.ts`.
+5. **Live updates (optional):** pass `liveUpdates: { socketIoServer: io | () => io }` to `FeatureFlagsApp`. MongoDB must run as a **replica set** (a single-node replica set is enough) so Mongoose change streams work.
+
+### Frontend (`@terreno/rtk` + OpenFeature)
+
+1. **`useFeatureFlags(terrenoApi, …)`** — no code changes required for the common case; it already uses `/flagConfiguration` and keeps `{ flags, getFlag, getVariant, isLoading, refetch }`.
+2. **OpenFeature React hooks** (`useBooleanFlagValue`, `useStringFlagValue`, `<FeatureFlag>`, …): add **`@openfeature/react-sdk`** and **`@openfeature/web-sdk`** to your app (align versions with `@terreno/rtk` **peerDependencies** and the root **`catalog`**).
+3. Wrap the UI that reads flags in **`<OpenFeatureProvider domain="feature-flags">`** (or the same `domain` you pass into the hook).
+4. After auth, call **`useTerrenoFeatureFlags(terrenoApi, { userId, skip, socket, … })`** once under your Redux `Provider` so OpenFeature is populated before hooks read flag values.
+5. **Regenerate the OpenAPI SDK** after the backend exposes the new route: `cd your-frontend && bun run sdk`. Prefer **`useTerrenoFeatureFlags` / `useFeatureFlags`** over calling a generated `flagConfiguration` hook directly, so domain, cache keys, and optional socket refetch stay consistent.
+
+### Further reading
+
+- [Feature flags reference](../reference/feature-flags.md)
+- [OpenFeature implementation plan](../implementationPlans/feature-flags-openfeature.md)
+
 ## Next steps
 
 - See the [reference docs](../reference/feature-flags.md) for the full API, targeting rules, and variant flags

package/src/docs/versioned/next/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`