@terreno/mcp 57.2.0 → 57.4.0

package/src/docs/versioned/next/how-to/connect-mcp-service-token.md

@@ -0,0 +1,110 @@
+# Connect an MCP client with a service token
+
+Mint a personal `mcp_…` Bearer key, then paste the MCP URL and key into Perplexity, Cursor, VS Code, or Claude Code.
+
+This is the **static-key** path for the consumer app's `POST /mcp`. It is not the hosted `@terreno/mcp` codegen server. For exposing tools, see [Expose MCP tools](expose-mcp-tools.md). Interactive OAuth for remote clients is a separate plan ([app MCP server](../implementationPlans/app-mcp-server.md)); do not send these keys in a query string.
+
+## 1. Enable the flag
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpServiceTokens: {
+    enabled: true,
+    publicMcpUrl: process.env.PUBLIC_API_URL,
+  },
+});
+```
+
+`mcpServiceTokens: true` is the same as `{enabled: true}`. Off (omitted or `enabled: false`) does not mount `/mcp/service-tokens` and does not accept `mcp_` Bearer credentials on `/mcp`.
+
+Pass `publicMcpUrl` so create responses include a copy-paste MCP URL (`…/mcp` is appended when missing). The example backend uses `PUBLIC_API_URL` or `BETTER_AUTH_URL`.
+
+## 2. Mint a token (Settings)
+
+1. Sign in to the example app.
+2. Open **Profile** → **MCP connections** (`/settings/mcp`).
+3. Enter a name (for example `Perplexity laptop`). Optionally set an expiry.
+4. Tap **Create token**.
+5. Copy the MCP URL, the full `mcp_…` secret, or the JSON snippet from the modal. The secret is shown **once**. Close the modal only after you have stored it in the client.
+
+Cap is **10** active tokens per user. List rows show prefix (`mcp_` + eight hex characters), last used, and expiry — never the full secret.
+
+## 3. Mint a token (curl)
+
+Use a session or JWT. A service token cannot mint another token.
+
+```bash
+curl -X POST "$API/mcp/service-tokens" \
+  -H "Authorization: Bearer $JWT" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Perplexity"}'
+```
+
+Read `data.token` and `data.mcpUrl` from the JSON. List and revoke never return `token`. Do not log the secret.
+
+## 4. Perplexity custom connector
+
+| Field | Value |
+| --- | --- |
+| MCP Server URL | `https://api.example.com/mcp` (use `data.mcpUrl` from create) |
+| Transport | Streamable HTTP |
+| Authentication | API Key |
+| API Key | full `mcp_…` string (Perplexity sends as Bearer) |
+
+Perplexity probes with GET, then POSTs JSON-RPC. Send the same key on both.
+
+GET does **not** authenticate. This server has no GET SSE stream, so `/mcp` answers `405` with `{"jsonrpc":"2.0","error":{"code":-32000,"message":"Method not allowed."}}` whether or not the key is valid. That 405 is the expected probe — not a failed login.
+
+POST `initialize` and `tools/list` are the unauthenticated catalog in the stateless handler. Identity is checked when a **tool runs** (`tools/call`). A missing or invalid `mcp_` key then returns `Permission denied: authentication required`.
+
+## 5. Cursor, VS Code, Claude Code (JSON)
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "url": "https://api.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer mcp_<secret-shown-once>"
+      }
+    }
+  }
+}
+```
+
+Replace the URL with `data.mcpUrl` and the Bearer value with the one-time `data.token`.
+
+## 6. Prove the key with curl
+
+```bash
+# Expected probe: JSON-RPC 405 "Method not allowed."
+curl -X GET "$API/mcp" \
+  -H "Authorization: Bearer mcp_…" \
+  -H "Accept: application/json, text/event-stream"
+
+# Catalog is unauthenticated. Identity is not proven here.
+curl -X POST "$API/mcp" \
+  -H "Authorization: Bearer mcp_…" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
+
+# Identity check: tools/call as the owning user. Use a tool name from tools/list.
+curl -X POST "$API/mcp" \
+  -H "Authorization: Bearer mcp_…" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"todos_list","arguments":{}}}'
+```
+
+A bogus key such as `mcp_deadbeef` on `tools/call` is denied. A valid key sees the same owner-scoped result as that user's REST session.
+
+The token acts as the owning user on **MCP only**. It cannot mint or list tokens, and it is not valid on REST, sync, or admin routes.
+
+## 7. Revoke
+
+- **Owner:** Profile → MCP connections → **Revoke** on the row (`DELETE /mcp/service-tokens/:id`).
+- **Admin:** Admin → MCP service tokens (`/admin/mcp-service-tokens`). Create and update are off. Delete sets `revokedAt`; it does not hard-delete the row.
+
+Revoked and expired keys fail `tools/call` immediately. Disabled user accounts are refused the same way as over HTTP.

package/src/docs/versioned/next/how-to/create-a-model.md

@@ -32,7 +32,7 @@ export interface TodoModel extends DefaultModel<TodoDocument> {
 
 ### 2. Create the schema with field descriptions
 
-**Important:** Every field **must** include a `description` property. This flows through to the OpenAPI spec and makes generated SDK documentation more useful.
+**Important:** Every field **must** include a `description` property. Terreno's `describeModel()` reads descriptions into the canonical field graph; that graph feeds the OpenAPI spec, admin `/admin/config` field metadata, and MCP tool schemas.
 
 ``````typescript
 // src/models/todo.ts

package/src/docs/versioned/next/how-to/create-a-terreno-app.md

@@ -0,0 +1,154 @@
+# Create a Terreno app
+
+Scaffold a deployable full-stack Terreno app (backend, Expo frontend, seed script, consumer `Dockerfile`, CI, MCP config) with one non-interactive command.
+
+The CLI writes files only — it does not run `bun install`, start MongoDB, or seed data.
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) (or Node/npm for `npm create`)
+- An empty target directory (see [Non-empty targets](#non-empty-targets))
+- MongoDB as a **replica set** before running the backend (see [Start MongoDB](#3-start-mongodb-replica-set))
+
+## 1. Scaffold the app
+
+From the parent directory where you want `<appName>/`:
+
+```bash
+bunx create-terreno-app my-app --display-name "My App"
+```
+
+npm alternative (note the `--` before flags):
+
+```bash
+npm create terreno-app my-app -- --display-name "My App"
+```
+
+Derive the display name from `appName` when you do not need a custom title:
+
+```bash
+bunx create-terreno-app my-app --yes
+```
+
+Optional flags:
+
+| Flag | Required | Default |
+| --- | --- | --- |
+| `appName` (positional) | yes | — kebab-case directory and package name (`^[a-z][a-z0-9-]*$`) |
+| `--display-name` | unless `--yes` | derived from `appName` when `--yes` |
+| `--description` | no | empty |
+| `--mcp-server-url` | no | `https://mcp.terreno.flourish.health` |
+| `--yes` | no | off |
+
+The CLI creates `<cwd>/<appName>/`. Package source: [`create-terreno-app/`](https://github.com/FlourishHealth/terreno/tree/master/create-terreno-app) in the Terreno monorepo.
+
+## Non-empty targets
+
+The CLI refuses to write when the target already contains anything other than `.git` or `.gitignore`. It exits non-zero and leaves existing files unchanged.
+
+Initializing git first is fine:
+
+```bash
+mkdir my-app && cd my-app && git init
+cd .. && bunx create-terreno-app my-app --yes
+```
+
+## Generated layout
+
+| Path | Purpose |
+| --- | --- |
+| `backend/` | Express/Mongoose API (`@terreno/api`, Better Auth, admin, sync) |
+| `frontend/` | Expo universal app (`@terreno/ui`, `@terreno/syncdb`, `@terreno/rtk`) |
+| `Dockerfile` | Consumer backend image (`backend/` only — not the Terreno monorepo) |
+| `.dockerignore` | Excludes local env secrets, dependencies, and build output from the image context |
+| `backend/.env`, `frontend/.env` | Gitignored local-dev defaults (written on scaffold) |
+| `backend/.env.example`, `frontend/.env.example` | Committed templates for production and export |
+| `.github/workflows/` | Backend and frontend CI |
+| `.cursor/mcp.json`, `.cursorrules`, `CLAUDE.md` | Agent tooling |
+| `README.md` | App-specific next steps and deploy links |
+
+Generated `@terreno/*` dependencies pin to `^<create-terreno-app version>` at scaffold time.
+
+## 2. Install dependencies
+
+```bash
+cd my-app
+(cd backend && bun install)
+(cd frontend && bun install)
+```
+
+## 3. Start MongoDB (replica set)
+
+Sync and realtime require a replica set (even a single-node dev set). See the [deployment baseline](../explanation/deployment-baseline.md).
+
+From the generated app root, run this local single-node example after `mongod` is available:
+
+```bash
+mkdir -p .devdata/mongo
+mongod --replSet rs0 --port 27017 --bind_ip 127.0.0.1 --dbpath .devdata/mongo &
+# Initiate once (use node for the driver command if bun errors on bson):
+node -e 'import("mongodb").then(async ({MongoClient})=>{const c=new MongoClient("mongodb://127.0.0.1:27017/?directConnection=true");await c.connect();await c.db("admin").command({replSetInitiate:{_id:"rs0",members:[{_id:0,host:"127.0.0.1:27017"}]}}).catch(()=>{});await c.close();})'
+```
+
+The scaffold sets `MONGO_URI` in `backend/.env` to `mongodb://127.0.0.1:27017/<app_name>?replicaSet=rs0` (hyphens in `appName` become underscores in the database name). Copy from `backend/.env.example` when you need production values.
+
+## 4. Seed login users
+
+With MongoDB running as a replica set:
+
+```bash
+(cd backend && bun run seed)
+```
+
+Creates:
+
+| Email | Password | Notes |
+| --- | --- | --- |
+| `test@example.com` | `testpassword123` | Standard user |
+| `admin@example.com` | `testpassword123` | Admin user |
+
+Seed behavior and flags: [Seed a database](seed-a-database.md). Better Auth setup: [Configure Better Auth](configure-better-auth.md).
+
+## 5. Run the stack
+
+Terminal 1 — API (default port `4000`):
+
+```bash
+(cd backend && bun run dev)
+```
+
+Health check: `curl http://localhost:4000/health` → `"healthy":true`.
+
+Terminal 2 — web UI (port `8082`):
+
+```bash
+(cd frontend && bun run sdk)   # after backend is up; regenerates OpenAPI hooks
+(cd frontend && bun run web)
+```
+
+Open `http://localhost:8082` and sign in as `test@example.com` / `testpassword123`.
+
+`frontend/.env` defaults `EXPO_PUBLIC_API_URL` to `http://localhost:4000`. For production web builds, set it **before** export — see [Build for web](build-for-web.md).
+
+## Deploy
+
+Read the [deployment baseline](../explanation/deployment-baseline.md) first.
+
+**Backend:** the root `Dockerfile` builds only `backend/` on `oven/bun`, listens on `PORT` (default `8080` in the image), binds `0.0.0.0`, and exposes `GET /health`. It does not copy Terreno monorepo packages.
+
+```bash
+docker build -t my-app-backend .
+docker run --rm -p 8080:8080 \
+  -e MONGO_URI='mongodb+srv://...' \
+  -e BETTER_AUTH_SECRET='...' \
+  -e BETTER_AUTH_URL='https://api.example.com' \
+  my-app-backend
+```
+
+Cloud Run concepts and commands: [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md). That guide targets Terreno's monorepo example; for a generated app, keep the root `Dockerfile`, port `8080`, and Better Auth variables shown here. The generated backend throws if `BETTER_AUTH_SECRET` is unset. `GET /users` list and read require an admin.
+
+**Frontend:** [Build for web](build-for-web.md) — set `EXPO_PUBLIC_API_URL` at export time.
+
+## Monorepo examples (secondary)
+
+To explore Terreno itself without scaffolding a new app, clone the [Terreno monorepo](https://github.com/FlourishHealth/terreno) and use `example-backend` / `example-frontend`. See [Getting started](../tutorials/getting-started.md#explore-the-terreno-monorepo-examples).

package/src/docs/versioned/next/how-to/deploy-backend-to-cloud-run.md

@@ -104,6 +104,10 @@ Expect `"healthy": true`.
 | Websockets disconnect every few requests | No session affinity on Cloud Run | Add `--session-affinity` |
 | Socket connections drop after ~5 minutes | Default request timeout (300s) | Raise `--timeout` (for example `3600`) |
 | Live feature flags / realtime never update; log mentions replica set | MongoDB is standalone, not a replica set | Use Atlas or `replSet` — change streams required (`feature-flags/src/featureFlagsApp.ts`) |
+| Bun-compiled container never opens its port while creating indexes | OpenTelemetry Mongoose instrumentation patched an already-loaded Mongoose module | Do not explicitly patch Mongoose in the compiled binary; retain HTTP/Express tracing |
+| Container hangs before listening when cloud logging initializes | A network logging transport blocks startup | Log to stdout/stderr during boot; Cloud Run ingests both streams |
+| `gcloud run deploy --tag` fails citing an old revision that never became Ready | That tag still points at the failed revision; `--remove-tags` keeps it in the traffic spec | Rebuild traffic with `--to-revisions=<live>=100` plus `--set-tags` of Ready tags only, deploy `--no-traffic` without `--tag`, then `--update-tags` the new revision |
+| A zero-traffic preview tag returns `503` with `{"status":"starting"}` indefinitely | The early TCP listener satisfies Cloud Run's startup probe before Mongo and seed work finish; request-only CPU then starves idle boot work | Deploy preview revisions with `--no-cpu-throttling`, then poll the tagged `/health` URL for `"healthy":true` before reporting deployment success |
 | First request after idle is slow; sockets reconnect constantly | Scaled to zero | Set `--min-instances=1` for user-facing services |
 | Browser API calls blocked by CORS | `corsOrigin` / Better Auth `trustedOrigins` missing web origin | Add your CDN URL to backend CORS and auth config |
 

package/src/docs/versioned/next/how-to/deploy-to-gcp.md

@@ -26,9 +26,9 @@ Read the [deployment baseline](../explanation/deployment-baseline.md) — seven
 
 [Environment variables reference](../reference/environment-variables.md) — full list of backend and client config.
 
-## Legacy Flourish deployment
+## Operator-specific deployment
 
-Flourish-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives in `infra/flourish/` and the existing `demo-deploy.yml` / `frontend-example-deploy.yml` workflows. New deployments should follow the generalized guides above with your own `$PROJECT_ID` and bucket names.
+Vendor-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives outside these generalized guides. New deployments should follow the guides above with your own `$PROJECT_ID` and bucket names.
 
 ## Related
 

package/src/docs/versioned/next/how-to/expose-mcp-tools.md

@@ -48,9 +48,17 @@ to work while clients migrate.
 
 ### 3. Call the tools
 
-Point any MCP client at `POST /mcp` with the user's `Authorization: Bearer <token>` header. Both JWT and Better Auth sessions are accepted; the resolved user is what the permission checks run against, so an LLM can never see more than that user could see over REST.
+Point any MCP client at `POST /mcp`. Auth order on the Bearer header is:
 
-Authentication is required by default, matching REST. A tool call with no resolvable user is refused before any permission check unless the model router sets `allowAnonymous: true` — the same flag REST passes to `authenticateMiddleware`. That matters for read-only helpers like `IsAuthenticatedOrReadOnly`, which would otherwise pass for an anonymous `list`. Disabled accounts are refused too, as they are over HTTP.
+1. `mcp_…` service token, when `mcpServiceTokens` is enabled
+2. Better Auth session
+3. JWT
+
+The resolved user is what permission checks run against, so an LLM never sees more than that user could see over REST. Mint and paste a static key with [Connect an MCP client with a service token](connect-mcp-service-token.md).
+
+`initialize` and `tools/list` are the unauthenticated catalog. Identity is enforced on `tools/call`. GET `/mcp` is Streamable HTTP **405** (`Method not allowed.`) — there is no GET SSE stream; Perplexity still uses that 405 as a successful probe.
+
+Authentication is required by default, matching REST. A tool call with no resolvable user is refused before any permission check unless the model router sets `allowAnonymous: true` — the same flag REST passes to `authenticateMiddleware`. That matters for read-only helpers like `IsAuthenticatedOrReadOnly`, which would otherwise pass for an anonymous `list`. Disabled accounts are refused too, as they are over HTTP. Service tokens are MCP-only: they are rejected on `/mcp/service-tokens` and are not accepted on REST, sync, or admin.
 
 To run the same tools in-process (for example inside a chat route), use `getMCPTools`:
 

package/src/docs/versioned/next/how-to/github-actions-ci.md

@@ -0,0 +1,41 @@
+# GitHub Actions CI (Terreno)
+
+GitHub Actions is the CI of record. Operator map for the expensive jobs:
+[GitHub Actions CI](github-actions-ci.md). CircleCI twins are parked; see
+[CircleCI](circleci.md).
+
+## Docs site (`docs-deploy.yml`)
+
+`Build docs site` is often the longest PR job because Docusaurus compiles every
+versioned tree under `website/versioned_docs/` and TypeDoc regenerates API
+pages.
+
+PR builds set `DOCS_PREVIEW=true` and pass `--no-minify`. Both PR and
+`master` use Docusaurus Faster (Rspack/SWC via `@docusaurus/faster`).
+
+| Behavior | PR preview | `master` production |
+| --- | --- | --- |
+| Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted (`disableVersioning`) | Built |
+| JS minify | Off | On |
+| Local search index | Skipped | Built |
+| Generated API + component MDX | Restored from cache when `api`/`rtk`/`ui` hashes match | Same cache, then full generate on miss |
+| TypeDoc workspace `tsc` | Once per generate (api+rtk deps share a process) | Same |
+| Rspack cache (`node_modules/.cache/rspack`) | Restored per `pull_request` vs `push` | Separate production key |
+
+Production still builds every version. Do not rely on `/57.1.0/…` URLs in a
+PR deploy preview.
+
+## Other high-cost jobs
+
+| Workflow | What we skip or reuse |
+| --- | --- |
+| `e2e-ci`, `admin-spa-ci`, `admin-spa-integration` | Playwright Chromium under `~/.cache/ms-playwright`, keyed on `bun.lock`. E2E shards share one compile job (`workspace-dist` artifact) so required check names stay `E2E · <spec>`. |
+| `fingerprint-gate` | Master iOS/Android hashes cached per `pull_request.base.sha` (skips a second `bun run compile`) |
+| `maestro-e2e` | Demo export + static server only when `demo/`, `ui/`, or `.maestro/flows/demo/` change |
+| `example-backend-docker` | Buildx runs only when the image recipe changes (`Dockerfile`, lockfile, `package.json`). Source-only PRs skip; CD preview deploy still builds the image. `load: true` stays off. |
+| `cd` backend preview | Runs for every example-frontend PR preview, including frontend-only changes, so the Netlify build targets an isolated `pr-<number>` backend instead of production. The frontend deploy waits for that backend's healthy `/health` response before publishing to Netlify, and per-PR concurrency cancels duplicate deploys to the same alias. CD runs the built container against the configured Secret Manager values, including the Cloud Tasks `JOBS_*` env, and requires a healthy `/health` response before pushing or deploying. Preview Cloud Run uses `--memory=1Gi` and `--cpu-boost`, overwrites revision secrets, and binds `PORT` before MongoDB connect. Before deploy it rebuilds traffic with `--set-tags` / `--clear-tags` so a not-Ready tagged revision is omitted (`--remove-tags` leaves that revision in the spec and Cloud Run rejects the update). It then deploys `--no-traffic` without `--tag`, sets `--revision-suffix=pr<n>-<run_id>-<run_attempt>`, and tags the new Ready revision afterward. |
+| Bun install | `.github/actions/setup-bun-workspace` pins Bun `1.4.0` and caches `~/.bun/install/cache` without `github.ref` in the key |
+
+Playwright e2e on CircleCI groups specs into five shards (`e2e-auth`,
+`e2e-app`, `e2e-admin-core`, `e2e-admin-table`, `e2e-syncdb`). The retained GHA
+twin still lists one spec per matrix entry for rollback.

package/src/docs/versioned/next/how-to/github-issue-lifecycle.md

@@ -0,0 +1,84 @@
+# GitHub issue lifecycle (create → plan → Pick/Roast)
+
+File issues so an agent can select them, post a Pick plan, implement with
+`terreno-2-pick`, and roast against that plan.
+
+Two implementation paths:
+
+| Path | Gate | Skill |
+| --- | --- | --- |
+| Interactive | You confirm the queue and Pick plan in chat | `/work-github-issues` |
+| Unattended | Maintainer applies `status:ready-for-dev` | `/implement-ready-for-dev` (Cursor Automation) |
+
+## Create the issue
+
+1. Invoke `/create-github-issue` (or open
+   [Lifecycle work item](https://github.com/FlourishHealth/terreno/issues/new?template=work_item.yml)).
+2. Fill **Affected package**, **Kind**, **Problem**, **Outcome**, **Current behavior**,
+   **Non-scope**, **Acceptance**, and **Context**.
+3. Stop until the drafted title, body, and labels are approved. Then create.
+
+Existing [bug](https://github.com/FlourishHealth/terreno/issues/new?template=bug_report.yml),
+[feature](https://github.com/FlourishHealth/terreno/issues/new?template=feature_request.yml),
+and [docs](https://github.com/FlourishHealth/terreno/issues/new?template=docs_issue.yml)
+forms still work. Prefer the lifecycle form when you want Roast-ready acceptance in
+the body. The canonical heading list is in the
+[`create-github-issue` skill](https://github.com/FlourishHealth/terreno/blob/master/.rulesync/skills/create-github-issue/references/issue-format.md).
+
+`Affected package` must match a known value so issue triage can apply `area:*`.
+`Kind` on the lifecycle form is applied as `type:*` by the same triage job.
+
+## Plan and implement
+
+1. Invoke `/work-github-issues`.
+2. The agent lists recent open issues, ranks a queue of at most five, and drafts a
+   Pick plan for one recommended issue.
+3. Confirm the queue, answer clarifying questions, and approve the plan text.
+4. The agent posts a comment that starts with `<!-- terreno-pick-plan -->` and
+   **pins that comment URL**. Roast reloads that id. A later matching comment from
+   someone who is not `OWNER` / `MEMBER` / `COLLABORATOR` is ignored.
+5. Pick implements one task; Roast proves that comment; Pick continues until the list
+   is done.
+
+Do not skip the confirmation pause. Do not roast from chat after the comment exists.
+
+Hand off to `/terreno-1-grow` when the plan needs more than five tasks or a
+product/security/architecture decision.
+
+## After Roast PASS (interactive)
+
+Inner-loop PASS does not open a PR. Invoke `/terreno-4-brew` when you want the draft
+PR.
+
+## Unattended pickup
+
+1. After triage, apply `status:ready-for-dev` and leave the issue unassigned.
+   Do not edit the issue body after you label it unless you are a maintainer; pickup
+   aborts if an untrusted author changes the body after the label.
+2. A Cursor Automation (or `/implement-ready-for-dev`) claims the oldest matching
+   issue: assignee + `status:in-progress`, remove `status:ready-for-dev`. It skips
+   issues that already have an open linked or closing PR (GraphQL references, not
+   `linked:<number>`).
+3. It runs Grow on that trusted snapshot, answers Grow questions from the repo and
+   issue (assumptions posted on the issue), and only stops on GitHub for a genuine
+   human gate (product, security, data ownership, public API, destructive change,
+   rollout, or scope the issue and docs do not settle). Then Pick ⇄ Roast, Brew, and
+   Taste until the PR is mergeable (ready for review). Do not merge.
+4. Dashboard paste: [`implement-ready-for-dev` automation](../../.rulesync/skills/implement-ready-for-dev/references/cursor-automation.md).
+
+Do not apply `status:ready-for-dev` to issues that still need a product, security, or
+data-ownership decision. Those stay `status:needs-info` or go through `/work-github-issues`.
+The unattended skill will assume implementation defaults; it will not invent those
+decisions.
+
+Labels live in [`.github/labels.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/labels.yml).
+Sync them with the existing roadmap labels workflow before expecting pickup.
+
+## Related
+
+- [Install agent skills](install-agent-skills.md)
+- [Lifecycle plugin](../reference/lifecycle-plugin.md)
+- [Loop engineering](../explanation/loop-engineering.md)
+- [Public roadmap process](../explanation/roadmap-process.md) — separate from this
+  issue → Pick path
+- [`implement-ready-for-dev` skill](../../.rulesync/skills/implement-ready-for-dev/SKILL.md)

package/src/docs/versioned/next/how-to/in-app-notifications.md

@@ -0,0 +1,147 @@
+# In-app notifications
+
+Add an owner-scoped inbox, channel preferences, and optional comms fan-out to a Terreno app.
+
+## 1. Register `NotificationsApp`
+
+On your `TerrenoApp`, register the plugin and pass your user model. When you already use
+`@terreno/comms`, pass `getComms` so `notify()` can fan out to mail, SMS, and push.
+
+```typescript
+import {NotificationsApp, TerrenoApp} from "@terreno/api";
+import {CommsApp, getCommsService} from "@terreno/comms";
+
+new TerrenoApp({userModel: User})
+  .register(
+    new NotificationsApp({
+      getComms: getCommsService,
+      retainDays: 0,
+      userModel: User,
+    })
+  )
+  .register(new CommsApp({/* providers */}))
+  .start();
+```
+
+`retainDays` defaults to `0` (keep all rows). Set a positive number to tombstone rows older
+than that many days (no Mongo TTL index).
+
+## 2. Wire comms preferences
+
+Export `notificationsBeforeSend` from `@terreno/api` and compose it into `CommsApp`
+`beforeSend`. It cancels outbound mail, SMS, or push when the user turned that channel off.
+The `verification` channel is never cancelled.
+
+```typescript
+import {notificationsBeforeSend} from "@terreno/api";
+
+new CommsApp({
+  beforeSend: async (context) => {
+    const pref = await notificationsBeforeSend({
+      channel: context.channel,
+      userId: context.userId,
+    });
+    if (pref?.cancel) {
+      return {cancel: true};
+    }
+    return undefined;
+  },
+  mail: mailProvider,
+});
+```
+
+## 3. Send notifications from server code
+
+Only the service inserts inbox rows (HTTP create is disabled).
+
+```typescript
+import {getNotificationService} from "@terreno/api";
+
+await getNotificationService().notify({
+  userId: String(user._id),
+  title: "Todo completed",
+  body: "Your task is done.",
+  href: "/todos",
+  kind: "todo",
+});
+```
+
+Fan-out order: inbox write (when `inapp` is on), then mail, SMS, and push when each
+preference is on and a destination exists. Missing email, phone, or push tokens skip that
+channel without failing `notify()`. A provider rejection on one channel is logged and
+does not skip later channels.
+
+## 4. Sync collections on the client
+
+Regenerate syncdb hooks (not RTK CRUD) for `notifications` and `notification-preferences`:
+
+```bash
+cd example-frontend
+bun run sync-sdk
+```
+
+Add the generated `SYNC_COLLECTIONS` to `createSyncDb`. Use `useQuery` / `useMutate` (or
+generated hooks) for list, mark-read (`readAt`), and dismiss (delete).
+
+## 5. Presentational UI
+
+Import the bell, inbox, and right-side drawer from `@terreno/ui`. The components take
+data and callbacks only — wire them to syncdb in your screen:
+
+```typescript
+import {NotificationBell, NotificationInbox, SideDrawer} from "@terreno/ui";
+
+<NotificationBell unreadCount={unreadCount} onPress={() => setOpen((value) => !value)} />
+<SideDrawer
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  position="right"
+  renderContent={() => (
+    <NotificationInbox
+      items={items}
+      onMarkRead={(item) => patch({id: item.id, data: {readAt: DateTime.now().toISO()}})}
+      onMarkUnread={(item) => patch({id: item.id, data: {readAt: null}})}
+      onDismiss={(item) => remove({id: item.id})}
+      onOpen={(item) => item.href?.startsWith("/") && router.push(item.href)}
+    />
+  )}
+>
+  {screen}
+</SideDrawer>
+```
+
+Customize the bell without reimplementing its tap target or unread accessibility label:
+
+```typescript
+<NotificationBell
+  unreadCount={unreadCount}
+  onPress={() => setOpen((value) => !value)}
+  renderIcon={({testID}) => <BrandBell testID={testID} />}
+  renderBadge={({testID, unreadCount}) => (
+    <BrandBubble count={unreadCount} testID={testID} />
+  )}
+/>
+```
+
+Treat dismissed rows as archived, not deleted. Dismiss PATCHes `archivedAt` through
+syncdb so the row stays in the owner snapshot with its payload. The active inbox
+filters `archivedAt` out; the full history page uses the same `useQuery("notifications")`
+and splits on `archivedAt`. Retention (`retainDays`) still tombstones old rows with
+`deleted: true`; those drop out of history after compaction. Map `archivedAt` (or a
+legacy `deleted` tombstone still in the local store) to `NotificationInboxItem.archived`.
+Archived rows remain readable but `NotificationInbox` hides their dismiss and read-state
+actions.
+
+See `example-frontend/components/NotificationCenter.tsx` and
+`example-frontend/app/notifications.tsx` for the drawer and complete history page.
+These components are not in the `@terreno/ui` component demo.
+
+The example todo router also demonstrates lifecycle-generated activity notifications:
+`postCreate` reports added todos, `postUpdate` reports a false-to-true `completed`
+transition, and `postDelete` reports deletion.
+
+## Reference
+
+- API shapes: [In-app notifications](../reference/api.md#in-app-notifications)
+- UI props: [Notification components](../reference/ui.md#notification-components)
+- Comms hook: [beforeSend composition](../reference/comms.md#notification-preferences-hook)