@terreno/mcp 57.18.0 → 57.19.2

package/src/docs/versioned/57.18.0/explanation/example-coverage.md

@@ -0,0 +1,48 @@
+# Example app coverage
+
+The `example-backend` and `example-frontend` apps are the living checklist for
+framework capabilities. When you add a capability to `@terreno/*`, update this
+matrix in the same slice.
+
+Citations are paths from the repository root. A "yes" means a reader can follow
+that file (and its imports) to a working example. Gaps stay explicit.
+
+## Capability matrix
+
+| Capability | example-backend | example-frontend | Notes |
+| --- | --- | --- | --- |
+| `modelRouter` CRUD | yes — `example-backend/src/api/todos.ts` | yes — `example-frontend/components/SyncTodosScreen.tsx` (syncdb hooks generated from the same collection) | Todos are synced; list/create/update/delete go through `@terreno/syncdb`, not RTK collection hooks. |
+| Owner permissions | yes — `OwnerQueryFilter` + `Permissions.IsOwner` in `example-backend/src/api/todos.ts` | yes — the todos screen only shows the signed-in user's rows after sync scopes apply | Also gated by RBAC `access: {resource: "todo"}`. |
+| Admin panel (embedded) | yes — Admin plugin registration in `example-backend/src/server.ts` | yes — `example-frontend/app/admin/` | Expo routes wrap `@terreno/admin-frontend` screens. |
+| Admin SPA | yes — `AdminSpaServeApp` in `example-backend/src/server.ts` | n/a | Standalone SPA is served from the backend; not a frontend route. |
+| AI streaming chat | yes — `example-backend/src/api/ai.ts` (`addGptRoutes`) | yes — `example-frontend/app/(tabs)/ai.tsx` (`GPTChat`, optional `mascot`) | Empty-chat mascot is consumer-owned; the example fox is not a framework default. |
+| UI blocks | yes — `uiBlocks` with `repair: true`, `exportDataset`, and the opt-in `scaleStepper` and `toggleChecklist` callbacks in `example-backend/src/ai/hostActions.ts`, wired from `example-backend/src/api/ai.ts`; `todoStats` in `example-backend/src/ai/tools.ts` stores a `ref` dataset; `findPhotos` in the same file cites the generated photo library, and `example-backend/src/api/photoLibrary.ts` signs its URLs | yes — `example-frontend/app/(tabs)/ai.tsx` (`uiBlocks`, dataset and action hooks, `hostActions` includes `exportDataset`, `scaleStepper`, and `toggleChecklist`, `resolveImage` resolves `file:` photo ids through `useLazyPhotoLibraryUrlQuery`) | e2e mocks a document with one inline and one `ref` chart. A second e2e test stores the Sunday roast reply (`blocks/src/fixtures/golden/sunday-roast.yaml` with `file:` photo ids) in a real `GptHistory`, streams it from the mocked model, and runs the stepper and checklist through the real `POST /gpt/actions`; photo URLs come from the real `GET /photoLibrary/:id/url`, and only the image download is stubbed (`example-frontend/e2e/helpers/seedGptHistory.ts`). Steps: [agent-ui-blocks.md](../how-to/agent-ui-blocks.md). |
+| Agent asks | yes — `asks: {approvals}` in `example-backend/src/api/ai.ts`, with the per-request `deleteCompletedTodos` approval tool from `example-backend/src/api/todoTools.ts`; it also passes `chat` to `addGptHistoryRoutes` for the headless `pendingAsks` and `turn` endpoints; keyless scripted agent with short compact-surface replies in `example-backend/src/api/demoAgent.ts` | yes — `example-frontend/app/(tabs)/ai.tsx` (`onAskSubmit`, `askErrors`), helpers in `example-frontend/lib/gptAsks.ts` | Without `GEMINI_API_KEY`, "Help me pick a plan" asks a `choice` in chat, "Pick toppings" asks a `select: "many"` `choice` with an Other field, "Send the weekly report" and "Archive old chats" ask a `confirm` (the second `destructive`), "Draft an announcement" asks a `markdown` edit of a draft, "Fill in the invoice details" asks a `form` with eight typed fields, "Upload a receipt" asks for `files`, sent as uploads when `GCS_BUCKET` is set and as data URLs otherwise, and "Delete my completed todos" calls `deleteCompletedTodos`, which runs only after the user approves the server's destructive approval card. e2e: `example-frontend/e2e/ai-chat.spec.ts`. Small clients: the curl walkthrough in the how-to and the demo's watch-sized `SimpleAskCard` story. Steps: [agent-ui-asks.md](../how-to/agent-ui-asks.md). |
+| AI structured output | no | no | `@terreno/ai` supports structured generation; the example only streams chat. Recorded gap — not claimed by a current tutorial. |
+| Feature flags + live updates | yes — `FeatureFlagsApp` in `example-backend/src/server.ts`, seed `example-backend/src/scripts/seed-feature-flags.ts` | yes — `useTerrenoFeatureFlags` in `example-frontend/app/_layout.tsx` | Socket-backed live updates share the realtime connection. |
+| Websockets / realtime | yes — `RealtimeApp` in `example-backend/src/server.ts`, `example-backend/src/websockets.ts` | yes — `useSocketConnection` in `example-frontend/app/_layout.tsx` | Sync deltas also use the socket (`SyncApp` + `@terreno/syncdb`). |
+| Consent forms | yes — `example-backend/src/consentDefinitions.ts`, seed scripts | yes — `example-frontend/app/(tabs)/documents.tsx` (Consents section), admin `example-frontend/app/admin/consent-forms/` | First-login flow is covered by e2e (`example-frontend/e2e/consents.spec.ts`). |
+| Product announcements | yes — `AnnouncementsApp` in `example-backend/src/server.ts`, release upload token via `ANNOUNCEMENTS_UPLOAD_TOKEN`, seed `example-backend/src/scripts/seed-announcements.ts`, sample release pack `example-backend/announcements/releases/1.14.0/` with `bun run announcements:pack` | yes — `AnnouncementNavigator` in `example-frontend/app/_layout.tsx` and admin announcement routes | Seeded examples are drafts, so fresh databases do not interrupt sign-in. Release packs support multiple Markdown surfaces and idempotent draft or explicit live API import. |
+| What's new banner | n/a — generated from `CHANGELOG.md` by `bun run whats-new:generate` | yes — `WhatsNewBanner` in `example-frontend/components/SyncTodosScreen.tsx`, data in `example-frontend/constants/whatsNew.generated.json` | `bun run check:whats-new` keeps the data in sync with each release. |
+| File upload / GCS | yes — `example-backend/src/api/settings.ts`, AI file routes in `example-backend/src/api/ai.ts`, `file-uploads` flag in `example-backend/src/api/fileUploads.ts` | yes — `example-frontend/app/(tabs)/documents.tsx` (Files section, every signed-in user, 1 upload / IP / min), `example-frontend/app/(tabs)/ai.tsx`, `example-frontend/app/gcs-settings.tsx` | The `file-uploads` feature flag hides upload controls and rejects uploads when off. A missing flag leaves uploads enabled. Deployed bucket is terraform-managed (`google_storage_bucket.example_documents`). |
+| Better Auth | yes — `example-backend/src/utils/betterAuthConfig.ts`, `BetterAuthApp` in `example-backend/src/server.ts` | yes — `example-frontend/app/login.tsx`, `example-frontend/lib/betterAuth.ts` | Default `AUTH_PROVIDER` is `better-auth`. |
+| syncdb local-first | yes — `SyncApp` in `example-backend/src/server.ts` | yes — `example-frontend/store/syncdb.ts`, `example-frontend/app/(tabs)/index.tsx` | PR #869 closed without merge; `@terreno/syncdb` shipped on the launch line and is the example todos path. |
+| SyncDB diagnostics | n/a | yes — `debug` registration in `example-frontend/store/syncdb.ts`, debugger UI at `example-frontend/app/syncdb-debug.tsx` | `terreno-mcp-local` can inspect, snapshot/compare/merge, mutate, flush, reconcile/resync, and exercise offline/conflict paths against the running development client. |
+| RBAC | yes — `example-backend/src/rbacRoles.ts` (including optional `aiObservabilityViewer` / `aiObservabilityOperator` roles), `access.ts`, `accessControl: access` on `ObservabilityApp` / `AdminApp`, `access: {resource: "todo"}` on the todo router | yes — `example-frontend/app/admin/roles.tsx` | Shipped. Plan: [rbac-permissions.md](../implementationPlans/rbac-permissions.md). |
+| Organizations | yes — `createAccess({organizations: true})`, `organizationSettingsSchema`, `orgScopedPlugin` on projects | yes — admin org directory/settings at `example-frontend/app/admin/orgs/` | Settings live on `Organization.settings`; example registers a nested timezone schema. |
+| Background jobs | no | no | No generic job queue example. Admin maintenance scripts (`example-backend/src/adminScripts.ts`, script runner widget) are a related but different surface. Plan: [admin-script-runner.md](../implementationPlans/admin-script-runner.md). |
+
+## Gaps
+
+| Gap | Why it stays | Follow-up |
+| --- | --- | --- |
+| AI structured output | Chat streaming already demonstrates the AI pillar; structured `generateObject`-style routes are unused by current tutorials | Track with [AI-first tutorials #1010](https://github.com/TerrenoLabs/terreno/issues/1010) (`add-ai-features.md` requires one structured-output call). |
+| Generic background jobs | Unshipped as a first-class example; do not invent a queue UI here | Track with [Durable background jobs #1188](https://github.com/TerrenoLabs/terreno/issues/1188). Admin script runner is a related surface — [admin-script-runner.md](../implementationPlans/admin-script-runner.md). |
+
+## Keeping the matrix true
+
+When you add a framework capability:
+
+1. Exercise it in `example-backend` and/or `example-frontend`.
+2. Update this page (cite the file).
+3. Mention the example in the PR.

package/src/docs/versioned/57.18.0/explanation/explicit-any-policy.md

@@ -0,0 +1,90 @@
+# Explicit `any` policy
+
+Terreno discourages `any` in TypeScript. Biome blocks **new** unsuppressed explicit `any` at lint time; this document describes how we inventory existing usages and track remediation.
+
+## Why
+
+- **Type safety**: `any` disables checking and hides bugs at compile time.
+- **Refactor confidence**: precise types make API and UI changes safer.
+- **Consistency**: one convention for when `any` is acceptable and how it is documented.
+
+Prefer `unknown` (and narrow) or a precise type. Use `as unknown as T` over `as any as T` when a cast is unavoidable.
+
+## Allowed uses
+
+Explicit `any` is acceptable only at **framework or library boundaries** where types are not expressible in TypeScript today, for example:
+
+- Mongoose model boundaries that inspect consumer-defined schemas (`api/src/populate.ts`)
+- RTK Query `Api<any, any, any, any>` in generic middleware (`rtk/src/offlineMiddleware.ts`)
+- Dynamic RTK hook lookup where endpoint names are not statically known (`admin-frontend`)
+- Test mocks with type-erased doubles (`*.test.ts`, `*.isolated.tsx`)
+
+Every allowed use must be **lint-clean** and **documented** (see below).
+
+## Remediation status
+
+The audit script (`bun run check:explicit-any`) classifies each explicit `any`:
+
+| Status | Meaning |
+|--------|---------|
+| `violation` | No `biome-ignore` — fails Biome lint |
+| `suppressed-only` | Has `biome-ignore` but missing `// noExplicitAny:` rationale |
+| `fully-documented` | Has both `biome-ignore` and `// noExplicitAny:` |
+| `file-blanket` | File-level `biome-ignore-all` without file-level `noExplicitAny:` |
+| `out-of-scope` | In Biome-excluded source (e.g. `api/src/populate.ts`) |
+
+## How to document an `any`
+
+When `any` cannot be removed, add **both** comments on the line above (or a file header for tests):
+
+```typescript
+// noExplicitAny: RTK Query generates hook names dynamically; not statically expressible
+// biome-ignore lint/suspicious/noExplicitAny: dynamic hook lookup on RTK Query enhanced API
+const hook = (api as any)[`useGet${name}Query`];
+```
+
+For test files with many mocks, a file-level header is fine:
+
+```typescript
+// noExplicitAny: test mocks use type-erased RTK Query API doubles
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
+```
+
+## Commands
+
+```bash
+bun run check:explicit-any                         # summary report
+bun run check:explicit-any:json                    # JSON inventory
+bun run check:explicit-any:lint                    # fail on unmarked or unsuppressed any
+bun run check:explicit-any:baseline                # fail if global or per-file counts regress
+bun run check:explicit-any -- --undocumented       # only suppressed-but-undocumented
+bun run check:explicit-any -- --list --undocumented  # file:line list for remediation
+bun run check:explicit-any -- --production-only --undocumented --list
+bun run check:explicit-any -- --package=api        # filter to one package
+bun run check:explicit-any -- --include-excluded   # include Biome-excluded files
+bun run check:explicit-any -- --write-baseline     # refresh scripts/check-explicit-any/baseline.json
+bun run check:explicit-any:remediate               # auto-add missing noExplicitAny: comments
+```
+
+## Enforcement
+
+| Layer | What it does |
+|-------|----------------|
+| **Biome `noExplicitAny: error`** | Blocks new unsuppressed `any` in every linted package |
+| **`bun run check:explicit-any:lint`** | Blocks suppressions without a `noExplicitAny:` rationale, including undocumented file-level suppressions |
+| **`bun run check:explicit-any:baseline`** | CI ratchet — total, per-file, undocumented, and violation counts must not increase; a new file starts with an allowance of zero |
+| **`bun run lint`** | Runs package lint, then the strict explicit-any marker check |
+
+Baseline file: `scripts/check-explicit-any/baseline.json`. Its per-file counts prevent a new or existing file from adding explicit `any` even when another file removes the same number. After intentional reductions (removing or properly documenting `any`), refresh with `--write-baseline` and commit the updated baseline.
+
+## Remediation workflow
+
+1. Run `bun run check:explicit-any -- --list --undocumented --production-only` for a work queue.
+2. For each hit, either **replace** `any` with a proper type or **document** with `noExplicitAny:` + `biome-ignore`.
+3. Prefer line-level suppressions over file-level `biome-ignore-all` in production code.
+4. Run `bun run check:explicit-any:baseline` before opening a PR.
+5. If counts decreased, run `--write-baseline` and commit the new baseline.
+
+## Exclusions
+
+The audit skips generated and template files (`openApiSdk.ts`, `*.template.ts`). Biome-excluded paths (see `!!` patterns in `biome.jsonc`) are omitted unless `--include-excluded` is passed.

package/src/docs/versioned/57.18.0/explanation/gcp-hosting-architecture.md

@@ -0,0 +1,319 @@
+# GCP Hosting Architecture
+
+This document explains the architecture and design decisions behind Terreno's Google Cloud Platform hosting setup for static web apps.
+
+## Overview
+
+The Terreno monorepo hosts two static web applications on Google Cloud Storage (GCS) with Cloud CDN:
+
+- **Demo app** (`demo/`) — UI component showcase
+- **Example frontend** (`example-frontend/`) — Full-stack example with API integration
+
+Both apps use the same architecture pattern optimized for single-page applications (SPAs) with client-side routing.
+
+## Architecture Diagram
+
+``````
+┌─────────────────────────────────────────────────────────────┐
+│                        Client Browser                        │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ HTTP Request
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│               Global Forwarding Rule (Static IP)             │
+│              (e.g., 34.120.xxx.xxx)                          │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       HTTP Proxy                             │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                         URL Map                              │
+│           (Routes to default backend bucket)                 │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Backend Bucket (CDN-enabled)               │
+│          (e.g., terreno-demo-backend)                        │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    GCS Bucket (Origin)                       │
+│   (e.g., gs://your-project-terreno-demo)                    │
+│                                                              │
+│   ├── index.html                                            │
+│   ├── _expo/                                                │
+│   │   └── static/                                           │
+│   │       ├── js/                                           │
+│   │       ├── css/                                          │
+│   │       └── media/                                        │
+│   └── _previews/                                            │
+│       └── pr-123/                                           │
+│           └── index.html                                    │
+└─────────────────────────────────────────────────────────────┘
+``````
+
+## Components
+
+### 1. GCS Bucket (Origin)
+
+**Purpose**: Store static assets (HTML, JS, CSS, images).
+
+**Configuration**:
+- **Public access**: `allUsers:objectViewer` IAM binding
+- **Static website config**: `notFoundPage=index.html` for SPA routing
+- **No `mainPageSuffix`**: Avoids GCS 301 redirects that break client routing
+
+**Key Feature**: The `notFoundPage` directive serves `index.html` for any 404, enabling client-side routing. When a user visits `/about` directly, GCS returns `index.html`, and the React Router or Expo Router handles the route client-side.
+
+### 2. Backend Bucket (CDN)
+
+**Purpose**: Serve bucket content with Cloud CDN caching.
+
+**Configuration**:
+- **CDN enabled**: Responses are cached at Google edge locations worldwide
+- **Negative caching disabled**: Prevents Cloud CDN from caching 404 responses, which would cause stale 404s for newly-deployed asset hashes
+- **Linked to GCS bucket**: Single bucket per backend
+
+**Performance**: CDN reduces latency by serving cached content from edge locations closest to users.
+
+### 3. URL Map
+
+**Purpose**: Route incoming requests to the backend bucket.
+
+**Configuration**:
+- **Default service**: Points to the backend bucket
+- **Path-based routing**: All paths (`/*`) route to the same backend
+
+**Extensibility**: URL maps support path-based routing (e.g., `/api/*` → backend service, `/*` → frontend), but Terreno uses a single backend per app.
+
+### 4. HTTP Proxy
+
+**Purpose**: Terminate HTTP connections and forward to the URL map.
+
+**Configuration**:
+- **Protocol**: HTTP (can be upgraded to HTTPS with certificates)
+- **Forwarding**: Passes requests to URL map
+
+**HTTPS Support**: To enable HTTPS, create an SSL certificate and attach it to an HTTPS proxy instead.
+
+### 5. Global Forwarding Rule (Static IP)
+
+**Purpose**: Assign a static external IP address to the HTTP proxy.
+
+**Configuration**:
+- **IP address**: Reserved global static IP (e.g., `34.120.xxx.xxx`)
+- **Port**: 80 (HTTP)
+
+**DNS**: Point your domain's A record to this IP for custom domains.
+
+## Design Decisions
+
+### Why Google Cloud Storage over Netlify?
+
+**Pros**:
+- **Cost**: GCS + CDN is cheaper at scale (no bandwidth limits on free tier ending)
+- **Control**: Full control over caching, CDN configuration, and infrastructure
+- **Integration**: Native integration with other GCP services (Cloud Run backend, Cloud Build, etc.)
+- **Flexibility**: URL maps enable complex routing if needed
+
+**Cons**:
+- **Setup complexity**: Requires manual GCP resource provisioning
+- **No built-in forms/functions**: Netlify provides these; GCS does not
+- **DNS management**: Requires separate DNS configuration (Netlify provides DNS)
+
+**Decision**: GCS is better for Terreno because it's a showcase/demo project with minimal dynamic needs, and cost/control outweigh convenience.
+
+### Cache Strategy
+
+| File Type | Cache-Control Header | Rationale |
+|-----------|----------------------|-----------|
+| **Hashed assets** (e.g., `main.abc123.js`) | `public, max-age=31536000, immutable` | Content hash in filename ensures uniqueness; safe to cache forever |
+| **index.html** | `no-cache, no-store, must-revalidate` | Entry point must never be cached to ensure users get the latest app shell |
+
+**Implementation**: Deployment workflows use `gsutil -h` to set headers during upload:
+``````bash
+# Sync hashed assets with long cache
+gsutil -m -h "Cache-Control:public, max-age=31536000, immutable" \
+  rsync -r -d -x '.*\.html$' dist/ gs://BUCKET/
+
+# Upload index.html with no-cache
+gsutil -h "Cache-Control:no-cache, no-store, must-revalidate" \
+  cp dist/index.html gs://BUCKET/index.html
+``````
+
+### SPA Routing Implementation
+
+**Challenge**: SPAs use client-side routing (e.g., `/about`, `/profile`), but GCS has no such files.
+
+**Solution**:
+1. **GCS `notFoundPage`**: Configure bucket with `notFoundPage=index.html`
+2. **CDN behavior**: When a request for `/about` results in a 404, GCS serves `index.html`
+3. **Client-side routing**: The app's router (Expo Router, React Router) reads the URL and renders the correct component
+
+**Why not `mainPageSuffix`?**
+- `mainPageSuffix=index.html` causes GCS to 301 redirect `/demo/` → `/demo/index.html`, breaking client routing and creating duplicate URLs.
+- `notFoundPage` returns 200 with `index.html` content, preserving the original URL.
+
+### Preview Deployment Strategy
+
+**Goal**: Deploy PR previews to unique URLs without polluting production.
+
+**Approach**:
+- **Path-based isolation**: Previews deploy to `_previews/pr-{number}/` within the same bucket
+- **Bare route objects**: Upload HTML files as bare objects (no `.html` extension) for SPA routing
+- **Dynamic baseUrl**: Inject `expo.experiments.baseUrl = /_previews/pr-123` during build
+
+**Example**:
+``````
+gs://bucket/
+  ├── index.html                         (production)
+  ├── _expo/static/js/main.abc.js        (production)
+  └── _previews/
+      ├── pr-123                         (bare object, serves preview index.html)
+      └── pr-123/
+          ├── index.html                 (preview root)
+          └── _expo/static/js/main.def.js
+``````
+
+**CDN Limitation**: The CDN's `notFoundPage` always serves the root `index.html`, not the preview's. To work around this:
+1. Upload preview routes as bare objects (e.g., `_previews/pr-123/about` → `about.html` uploaded without extension)
+2. Set `Content-Type: text/html` manually
+
+**Trade-off**: This adds complexity but keeps previews in the same bucket, simplifying cleanup.
+
+## Deployment Flow
+
+### Production Deploy
+
+1. **Trigger**: Push to `master` branch with changes to `demo/**`, `ui/**`, `example-frontend/**`, `rtk/**`
+2. **Build**: GitHub Actions runs `bun run export` to generate static files
+3. **Ensure negative caching disabled**: Update backend bucket to prevent cached 404s
+4. **Upload**:
+   - Sync new hashed assets (additive, no deletions) so old bundles remain available
+   - Upload `index.html` with no-cache header, atomically switching to new bundle hashes
+5. **Invalidate CDN**: `gcloud compute url-maps invalidate-cdn-cache --path "/*"` clears all cached paths
+6. **Cleanup**: Sync with deletions (`-d`) to remove old assets no longer referenced
+
+### Preview Deploy
+
+1. **Trigger**: Open PR with changes to relevant paths
+2. **Build**: Inject `baseUrl` and run `bun run export`
+3. **Upload**:
+   - Upload to `_previews/pr-{number}/`
+   - Create bare route objects for SPA routing
+4. **GitHub Deployment**: Create deployment with preview URL
+5. **Comment**: Bot comments on PR with the preview link
+
+### Preview Cleanup
+
+1. **Trigger**: PR closed or merged
+2. **Delete**: `gsutil -m rm -r gs://BUCKET/_previews/pr-{number}/`
+3. **Deactivate**: Mark GitHub deployments as inactive
+
+## Security Considerations
+
+### Public Read Access
+
+**Risk**: Anyone can access bucket contents.
+
+**Mitigation**: Only public-facing demo apps are hosted. No sensitive data or credentials are stored in GCS.
+
+### Service Account Permissions
+
+**Principle of Least Privilege**: The CI service account has:
+- `roles/storage.objectAdmin` on specific buckets (not project-wide)
+- `roles/compute.loadBalancerAdmin` for CDN cache invalidation only
+
+**Key Storage**: `GCP_SA_KEY` secret is encrypted in GitHub Secrets and never logged.
+
+## Cost Optimization
+
+### Storage Costs
+
+- **GCS Standard**: ~$0.02/GB/month
+- **Typical app size**: ~5-10 MB
+- **Monthly cost**: < $0.01/month per app
+
+### CDN Costs
+
+- **Cache hit**: ~$0.08/GB
+- **Cache miss**: ~$0.12/GB (includes origin fetch)
+- **Expected traffic**: Low (demo/example apps)
+- **Monthly cost**: < $5/month for both apps
+
+### Optimization Strategies
+
+1. **Maximize cache hits**: Long cache headers on hashed assets
+2. **Minimize origin fetches**: CDN caches effectively
+3. **Compress assets**: Expo build automatically gzips/brotlis assets
+4. **Delete old previews**: Cleanup workflow prevents accumulation
+
+## Monitoring and Observability
+
+### Metrics
+
+Monitor via GCP Console:
+- **Storage**: Bucket size, object count
+- **CDN**: Cache hit rate, request count, bandwidth
+- **Costs**: Cloud Billing dashboard
+
+### Alerts
+
+Set up budget alerts in GCP:
+``````bash
+gcloud billing budgets create \
+  --billing-account=BILLING_ACCOUNT_ID \
+  --display-name="Terreno Hosting Budget" \
+  --budget-amount=20USD \
+  --threshold-rule=percent=90
+``````
+
+### Logs
+
+- **Access logs**: Enable bucket access logging if needed
+- **CDN logs**: Enable Cloud CDN logging for request analysis
+
+## Future Improvements
+
+### HTTPS Support
+
+1. Reserve a domain (e.g., `demo.terreno.dev`)
+2. Create an SSL certificate:
+   ``````bash
+   gcloud compute ssl-certificates create terreno-demo-cert \
+     --domains=demo.terreno.dev \
+     --global
+   ``````
+3. Create HTTPS proxy and forwarding rule
+4. Update DNS A record
+
+### Custom Domains
+
+Point DNS A records to the static IPs:
+``````
+demo.terreno.dev.     A     34.120.xxx.xxx
+example.terreno.dev.  A     34.149.xxx.xxx
+``````
+
+### CDN Performance Tuning
+
+- **Geo-routing**: Use Cloud Load Balancing for region-specific backends
+- **Compression**: Enable brotli/gzip at CDN level
+- **Pre-warming**: Warm CDN cache after deployments
+
+### Multi-Region Redundancy
+
+- Replicate buckets to multiple regions
+- Use Cloud Load Balancing to route to nearest region
+
+## Related Documentation
+
+- [Deploy to GCP](../how-to/deploy-to-gcp.md) — Step-by-step deployment guide
+- [Environment Variables Reference](../reference/environment-variables.md) — Configure runtime settings
+- [GCP Documentation: Hosting a Static Website](https://cloud.google.com/storage/docs/hosting-static-website) — Official GCS guide

package/src/docs/versioned/57.18.0/explanation/local-first-data.md

@@ -0,0 +1,65 @@
+# Local-first data in Terreno
+
+Terreno's default frontend data path is **local-first**: the on-device store is what your UI reads and writes, and the server reconciles changes asynchronously. This is a different mental model from request/response fetching with RTK Query.
+
+## What local-first means here
+
+In `@terreno/syncdb`, a TinyBase `MergeableStore` on the device is the **UI source of truth**. When a user taps "save," the mutation applies to local state immediately and lands in a durable outbox. The client then pushes the change to `@terreno/api` over the sync protocol (socket deltas with HTTP snapshot catch-up). The server remains the **authority** for permissions, validation, and conflict resolution — but the UI does not wait on the network for every write.
+
+There is no server-first mode and no opt-in flag: if you use syncdb, you adopt this model for every synced collection.
+
+## Mental model shift
+
+| Server-first (RTK Query) | Local-first (syncdb) |
+|--------------------------|----------------------|
+| UI reads from cache filled by HTTP | UI reads from the local store |
+| Writes call the API, then invalidate/refetch | Writes apply locally, then reconcile |
+| Loading spinners track request lifecycle | Sync status tracks outbox + connectivity |
+| Optimistic updates are manual and fragile | Optimistic state is the default path |
+| Conflicts are rare / ignored | Conflicts are explicit and must be resolved |
+
+Think **apply locally, then reconcile** instead of **request, wait, update cache**.
+
+## What you stop doing
+
+1. **Manual optimistic updates** — `onQueryStarted` patches, temporary IDs, and rollback logic for writes.
+2. **Write-level loading spinners** — `isLoading` on mutations for "saving…" UX; the row updates instantly.
+3. **Refetch orchestration** — `invalidatesTags`, `refetch()`, and list/detail cache coordination after mutations.
+4. **Treating the network as the read path** — list screens blocked on `isLoading` for every navigation.
+
+RTK Query remains appropriate for **non-synced generated** endpoints such as
+`/auth/me` and AI routes. Built-in admin RPC stays request/response through its
+host-bound fetch client; ObjectId/API-only admin CRUD keeps RTK compatibility in
+Terreno 57.
+
+## What you start doing
+
+1. **Conflict resolution UI** — When the server rejects a mutation (409 / `sync:nack`), the user must choose a strategy (`useServer` or `keepMine`). Use `ConflictSheet` from `@terreno/ui` or build your own with `useConflicts`.
+2. **Sync-status UX** — Surface offline state, queued mutations, and drain progress with `useSyncStatus` (and optionally `SyncStatusBanner`).
+3. **Encryption at rest (web)** — Web persistence uses AES-GCM via the default `createServerKeyProvider`; understand key fetch and `onDecryptFailure` for support flows.
+4. **Key lifecycle on logout** — Call `syncDb.stop()` and consider `wipeLocalData` when the authenticated user changes so one account does not read another's local store.
+5. **Backend sync registration** — Every synced collection needs `syncPlugin`, `isDeletedPlugin`, and a `sync` block on `modelRouter`, plus `SyncApp` and `RealtimeApp` on the server. Optional `sync.adminBroadcast: true` also emits `sync:delta` to `{collection}|admin`. Admin clients subscribe with `mode: "window"` (`createSyncDb({windowCollections})`) so they do not snapshot or reconcile that collection; they call `hydrateWindow` (REST membership ids + `GET /sync/entities`). Pass the same `accessControl` into `SyncApp` that `AdminApp` uses so `{collection}|admin` requires `admin:access`. `AdminApp.register` also installs that model's admin list/read/`queryFilter` on the admin window so hydrate and live `|admin` deltas match `/admin` REST. Without RBAC, `user.admin` is enough for the shell gate. Live deltas on that stream apply only to ids already in the window; Refresh is a REST re-query plus `hydrateWindow`.
+6. **Collections too large to sync whole** — List them in `createSyncDb({queryCollections})`. They skip snapshot bootstrap; screens load server-filtered *query windows* (`useWindowQuery`) from the `modelRouter` list endpoint. A window stores only membership (ordered ids); rows live once in the shared entity table. Overlapping windows therefore share rows — one delta updates both views — while each view lists only its own query's members, plus cached rows that newly match its `where` inside the loaded range. Live deltas still arrive on the user's normal streams; windows on screen refetch on reconnect to cover deltas missed offline.
+
+## First load and reconnects
+
+A fresh device has to download every row the user can see before the UI is complete. The
+client asks for all of the user's streams in one batched request per round, writes each
+round while the next one downloads, and writes rows in small chunks so the screen stays
+responsive. Reconnects use the same path: when nothing changed, catching up costs two
+requests however many collections the app syncs. Collections too large to download whole
+belong in `queryCollections` instead.
+
+## Tradeoffs
+
+**Gains:** instant UI, offline writes with a durable outbox, simpler screen code, and one write path on the server (sync and REST share `modelRouter`).
+
+**Costs:** larger conceptual surface (conflicts, sync status, local storage), mandatory replica-set MongoDB for realtime, and migration work for existing RTK Query screens.
+
+Server-first fetching is simpler when you only need online CRUD with no offline requirement — but Terreno's blessed path for collection data is local-first.
+
+## Related docs
+
+- [syncdb reference](../reference/syncdb.md) — API ground truth
+- [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md) — step-by-step migration
+- [Authentication architecture](authentication.md) — Better Auth + socket sessions