@terreno/mcp 57.17.0 → 57.18.0

package/dist/docs/versioned/57.17.0/how-to/expose-mcp-tools.md

@@ -0,0 +1,241 @@
+# Expose Model Context Protocol Tools
+
+Turn a `modelRouter` model into Model Context Protocol (MCP) tools that an LLM can call, reusing the permissions, query filters, population, and lifecycle hooks you already declared for REST.
+
+## Prerequisites
+
+- A working Terreno backend using `TerrenoApp`
+- At least one model registered with `modelRouter`
+
+## Steps
+
+### 1. Add an `mcp` config to a model router
+
+```typescript
+import {modelRouter, OwnerQueryFilter, Permissions} from "@terreno/api";
+
+export const todoRouter = modelRouter("/todos", Todo, {
+  mcp: {
+    excludeFields: ["internalNote"],
+    maxLimit: 25,
+    methods: ["list", "read", "create", "update", "delete"],
+  },
+  permissions: {
+    create: [Permissions.IsAuthenticated],
+    delete: [Permissions.IsOwner],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsOwner],
+    update: [Permissions.IsOwner],
+  },
+  queryFields: ["completed", "title"],
+  queryFilter: OwnerQueryFilter,
+});
+```
+
+`methods` defaults to `["list", "read"]`, and `maxLimit` defaults to 50. A method whose `permissions` array is empty is never exposed as a tool, so REST and MCP cannot drift apart.
+
+### 2. Start the server
+
+`TerrenoApp` mounts `POST /mcp` automatically as soon as any model has an `mcp` config. Every other verb on `/mcp` returns a JSON-RPC 405. No extra registration is needed.
+
+Tools are named `{prefix}_{method}` — `todos_list`, `todos_read`, and so on.
+
+The endpoint speaks the `2026-07-28` MCP revision through the TypeScript SDK v2
+`createMcpHandler`. It is stateless: every request carries its protocol version,
+client identity, and capabilities, so requests can land on any backend instance.
+The SDK's stateless legacy fallback remains enabled, so 2025-era clients continue
+to work while clients migrate.
+
+### 3. Call the tools
+
+Point any MCP client at `POST /mcp`. Auth order on the Bearer header is:
+
+1. `mcp_…` service token, when `mcpServiceTokens` is enabled
+2. `mcpat_…` OAuth access token, when `mcpOAuth` is enabled
+3. Better Auth session
+4. JWT
+
+The credential type that won is recorded as `getCurrentRequestContext()?.credential` (`"mcp-service-token"`, `"oauth"`, `"better-auth-session"`, or `"jwt"`), so a permission function can refuse delegated agent tokens where it would trust the user's own session. Remote clients that need OAuth (Claude.ai connectors, ChatGPT apps) are covered in [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md).
+
+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 (unless `mcpOAuth` is enabled, which makes every unauthenticated `/mcp` request a 401 challenge). 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`:
+
+```typescript
+import {getMCPTools} from "@terreno/ai";
+
+const tools = getMCPTools(req.user);
+```
+
+`useMCPTools()` from `@terreno/rtk` uses the official MCP v2 client with automatic
+version negotiation. It no longer constructs JSON-RPC or parses SSE responses by
+hand; the SDK supplies the `2026-07-28` `_meta` envelope and required
+`Mcp-Method` / `Mcp-Name` routing headers.
+
+## Naming tools
+
+The default prefix is the lowercase model name run through a simple pluralizer: `Todo` → `todos`, `Category` → `categories`, `Status` → `statuses`. Irregular nouns need an explicit prefix:
+
+```typescript
+mcp: {toolPrefix: "people"} // person_list -> people_list
+```
+
+## Filtering list results
+
+Only fields listed in `queryFields` can be filtered, exactly as in REST. A filter value may be an exact value or an operator object:
+
+```json
+{"completed": false, "title": {"$in": ["Buy milk", "Walk dog"]}}
+```
+
+Allowed operators are `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$all`, `$size`, `$exists`, and `$regex` (with `$options`). Operators that can execute code or ignore indexes — `$where`, `$expr`, `$function`, `$accumulator`, `$jsonSchema`, `$text` — are rejected with an error rather than silently dropped, so the model can correct itself.
+
+Filters can be combined with top-level `$and` / `$or`, whose branches are validated against `queryFields` too:
+
+```json
+{"$or": [{"completed": true}, {"title": {"$regex": "^Urgent"}}]}
+```
+
+`queryFilter` still runs after the filter is built, so an `OwnerQueryFilter` keeps scoping results to the calling user no matter what the LLM sends.
+
+## Populating references
+
+Population comes from the model router's `populatePaths`, exactly as it does over REST. A tool may pass `populate` to request a **subset** of those declared paths — it can never introduce a new one, so the `fields` allowlist on each declared path always applies and a caller cannot pull back a whole referenced document:
+
+```typescript
+populatePaths: [{fields: ["name", "email"], path: "ownerId"}],
+```
+
+`{"populate": "ownerId"}` is accepted; anything undeclared is refused with an error listing the allowed paths. Models with no `populatePaths` don't get a `populate` parameter at all.
+
+## Hiding fields
+
+`excludeFields` removes fields from both the generated tool schemas and the responses:
+
+- A bare name (`"hash"`) is removed at **every depth**, including inside arrays and populated refs, so a redacted name cannot leak through a nested document.
+- A dot path (`"metadata.secretKey"`) removes exactly that location, following arrays of subdocuments element-wise.
+
+The list tool's `sort` argument accepts only the router's sortable fields (`queryFields`, fields in the router's `sort`, and `sortFields`) minus `excludeFields`. Sorting on any other field returns an error that lists the allowed fields, because result order would reveal the hidden values.
+
+## Customizing responses
+
+`mcpResponseHandler` shapes MCP responses independently of the REST `responseHandler`, which is useful for returning compact summaries to an LLM:
+
+```typescript
+mcp: {
+  mcpResponseHandler: async (value, method) => {
+    if (Array.isArray(value)) {
+      return value.map((todo) => ({id: String(todo._id), title: todo.title}));
+    }
+    return {id: String(value._id), title: value.title};
+  },
+}
+```
+
+`excludeFields` is applied after your handler runs.
+
+## Lifecycle hooks
+
+`preCreate`, `postCreate`, `preUpdate`, `postUpdate`, `preDelete`, and `postDelete` all run for MCP calls. An MCP tool call is JSON-RPC rather than HTTP, so `createMCPRequest` builds a stub Express-shaped `request` (`MCPRequest`):
+
+- `user` — the authenticated MCP user
+- `body` — the hook-stage payload after write denylist + transform, not the raw tool args (on delete, `id` is in `body`, not `params`)
+- `headers` / `query` / `params` — always `{}` (MCP does not forward HTTP headers)
+- `isMCPRequest` — `true`
+
+REST `responseHandler` gets the same stub with an empty `body`.
+
+```typescript
+import type {MCPRequest} from "@terreno/api";
+
+preCreate: (body, req) => {
+  if ((req as unknown as MCPRequest).isMCPRequest) {
+    // e.g. tag records created by an assistant
+    return {...body, source: "assistant"};
+  }
+  return body;
+},
+```
+
+A hook that reads `req.headers` or `req.query` gets an empty object instead of a crash, but anything genuinely HTTP-specific (cookies, IP address) is unavailable — branch on `isMCPRequest` when that matters.
+
+## Logging and error reporting
+
+Every generated tool call emits a structured backend audit log with stable
+`mcpTool`, `mcpMethod`, and `mcpModel` labels plus the active Terreno request
+context (`requestId`, `userId`, and trace fields when present):
+
+- successful calls log at `info` with `durationMs`
+- expected refusals (permissions, not found, invalid filters) log at `warn`
+- caught database, transform, and lifecycle-hook failures log at `error`
+
+When `USE_SENTRY_LOGGING=true`, expected failures are mirrored as Sentry logs.
+Unexpected exceptions and caught internal causes are also captured with
+`Sentry.captureException`, preserving their original stack. The client still
+receives the stable MCP error text — internal exceptions and stack traces stay
+server-side. Tool arguments are not logged.
+
+## Actions as tools
+
+A verb that is not CRUD belongs in a [modelRouter action](../explanation/model-router-actions.md). Add `mcp` to the action to expose the same implementation as a tool, instead of writing it twice:
+
+```typescript
+export const todoRouter = modelRouter("/todos", Todo, {
+  collectionActions: {
+    bulkComplete: {
+      body: z.object({ids: z.array(z.string()).min(1)}).strict(),
+      handler: async ({body, user}) => completeTodos(body.ids, user),
+      mcp: {description: "Mark several todos complete", name: "todos_bulk_complete"},
+      method: "POST",
+      permissions: [Permissions.IsAuthenticated],
+    },
+  },
+  instanceActions: {
+    markComplete: {
+      handler: async ({doc}) => markComplete(doc),
+      mcp: {name: "todos_mark_complete"},
+      method: "POST",
+      permissions: [Permissions.IsOwner],
+    },
+  },
+  permissions: { /* CRUD */ },
+});
+```
+
+- `todos_mark_complete` takes `{id}`; an instance action's tool input is `{id, ...body}` (or `{id, ...query}` for GET). `todos_bulk_complete` takes `{ids}`.
+- The tool runs the action's own `permissions` and RBAC `access`, before and after loading the document, exactly as REST does. It does not need `mcp` on the router, and the router's CRUD permissions do not apply.
+- The handler sees `req.isMCPRequest === true`. Its return value is the tool's JSON text. Touching `res` fails the call, so return values instead of writing to `res`.
+- `body` / `query` must be a `z.object()`, and instance actions cannot define `id` in it. Tool names must be unique; a duplicate fails at boot.
+
+Audit log lines for action tools carry `mcpTool`, `mcpModel`, and `mcpAction` labels.
+
+## Custom tools
+
+CRUD tools cover one model at a time, and actions cover one model's verbs. For a query that spans models, register a custom tool with `registerMCPTool`. It shows up on `POST /mcp` and in `getMCPTools` next to the generated CRUD tools:
+
+```typescript
+import {registerMCPTool} from "@terreno/api";
+import {z} from "zod";
+
+registerMCPTool({
+  name: "users_todo_statuses",
+  description: "List every user with each of their todos and completed status. Admin only.",
+  zodSchema: z.object({}).strict(),
+  handler: async (_args, user) => {
+    if (!user?.admin) {
+      return {
+        content: [{type: "text", text: JSON.stringify({error: "Permission denied: admin required"})}],
+        isError: true,
+      };
+    }
+    // load users + todos and return JSON text
+    return {content: [{type: "text", text: JSON.stringify({users: []})}]};
+  },
+});
+```
+
+The example backend registers this as `users_todo_statuses` from `example-backend/src/api/usersTodoStatus.ts`.

package/dist/docs/versioned/57.17.0/how-to/generate-a-rest-cli.md

@@ -0,0 +1,34 @@
+# Generate a REST CLI from OpenAPI
+
+Run this from an app repo that already serves `/openapi.json` (Terreno `setupServer` does).
+
+1. Install the CLI: `bun add -g @terreno/cli` (or `bunx @terreno/cli`).
+2. Generate the wrapper:
+
+```bash
+terreno generate rest-cli \
+  --schema http://localhost:4000/openapi.json \
+  --out ./tools/app-cli \
+  --name myapp \
+  --base-url http://localhost:4000
+```
+
+3. Call the API:
+
+```bash
+cd tools/app-cli
+bun ./src/cli.ts list
+bun ./src/cli.ts call todo_list --param limit=10 --token "$TERRENO_TOKEN"
+bun ./src/cli.ts request GET /todos/{id} --param id=abc --json
+```
+
+Auth uses `--token` or `TERRENO_TOKEN`. Base URL uses `--base-url` or `TERRENO_API_URL`, then `servers[0].url` from the spec.
+
+To list or call without generating a package:
+
+```bash
+terreno api list --schema http://localhost:4000/openapi.json
+terreno api call todo_list --schema ./openapi.json --param limit=10
+```
+
+`generate rest-cli` writes `src/cli.ts` that imports `runAppRestCli` from `@terreno/cli`. Point that dependency at the published `@terreno/cli` version in apps outside this monorepo.

package/dist/docs/versioned/57.17.0/how-to/github-actions-ci.md

@@ -0,0 +1,41 @@
+# GitHub Actions CI (Terreno)
+
+CircleCI is the CI/CD of record; see [CircleCI](circleci.md). The GitHub
+Actions CI and deploy workflows below are disabled
+(`push.branches-ignore: ["**"]`) and kept only for rollback. This page
+describes how they behaved if one is ever re-enabled.
+
+## Docs site (`docs-deploy.yml`)
+
+`Build docs site` is often the longest PR job because TypeDoc regenerates API
+pages. The site builds only the current docs tree; `website/versioned_docs/` is
+markdown for the MCP server.
+
+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 | Prebuilt archives unpacked under `/<version>/` |
+| 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 |
+
+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` Cloud Run deploys | Runs a local wrapper around `google-github-actions/deploy-cloudrun` that retries only the transient GitHub WIF subject-token timeout, up to three attempts; IAM, image, and configuration failures fail immediately. The 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 runs `bun install --frozen-lockfile` with no `~/.bun/install/cache`. CircleCI measurements: cache restore (~15–73s) exceeded the install savings (~9s). See [circleci.md](circleci.md#bun-install-is-uncached). |
+
+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/dist/docs/versioned/57.17.0/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/TerrenoLabs/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/TerrenoLabs/terreno/issues/new?template=bug_report.yml),
+[feature](https://github.com/TerrenoLabs/terreno/issues/new?template=feature_request.yml),
+and [docs](https://github.com/TerrenoLabs/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/TerrenoLabs/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/TerrenoLabs/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/dist/docs/versioned/57.17.0/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)

package/dist/docs/versioned/57.17.0/how-to/inbound-webhooks.md

@@ -0,0 +1,83 @@
+# Receive inbound webhooks
+
+Register provider callbacks on `WebhooksApp`. Signatures use `req.rawBody` — never
+`JSON.stringify(req.body)`.
+
+```typescript
+import {hmacSignature, TerrenoApp, WebhooksApp} from "@terreno/api";
+
+const webhooks = new WebhooksApp({idempotency: {store: "mongo"}});
+webhooks.route({
+  path: "/webhooks/example",
+  source: "example",
+  verify: hmacSignature({secret: process.env.WEBHOOK_SECRET!, header: "X-Webhook-Signature"}),
+  eventId: (req) => String((req.body as {id?: string})?.id ?? ""),
+  handler: async () => undefined,
+});
+
+new TerrenoApp({userModel: User}).register(webhooks).start();
+```
+
+`@terreno/api` does **not** read `WEBHOOK_SECRET`. The example backend registers
+`POST /webhooks/example` only when that env is set.
+
+## Register Twilio and SendGrid through CommsApp
+
+Build one `WebhooksApp`, pass it into `CommsApp`, then register the plugin **after**
+`CommsApp` so the extra routes mount:
+
+```typescript
+const webhooks = new WebhooksApp({idempotency: {store: "mongo"}});
+
+new TerrenoApp({userModel: User})
+  .register(
+    new CommsApp({
+      mail: new SendGridMailProvider(),
+      sms: new TwilioSmsProvider(),
+      webhookPublicUrl: process.env.PUBLIC_API_URL,
+      webhooks,
+    })
+  )
+  .register(webhooks)
+  .start();
+```
+
+| Adapter | Path (default `basePath` `/comms`) | Signature |
+|---------|--------------------------------------|-----------|
+| `TwilioSmsProvider` | `POST /comms/webhooks/twilio/status` and `.../inbound` | `twilioSignature` — public URL must match the Twilio callback |
+| `SendGridMailProvider` | `POST /comms/webhooks/sendgrid` | ECDSA; `SENDGRID_WEBHOOK_VERIFICATION_KEY` or `webhookVerificationKey` |
+
+Set `webhookPublicUrl`, `PUBLIC_API_URL`, or `COMMS_WEBHOOK_PUBLIC_URL` to the public
+HTTPS origin (Cloud Run URL, no trailing slash). Twilio HMAC includes that origin plus
+path. Missing Twilio auth token, public URL, or SendGrid verification key skips that
+provider's routes and logs an error.
+
+Expo push **polls receipts** — it does not use inbound HTTP.
+
+Stripe billing webhooks stay on `billing-stripe` at `POST /billing/webhooks/stripe`.
+
+## Verifiers
+
+| Helper | Header | Algorithm |
+|--------|--------|-----------|
+| `hmacSignature({secret, header, timestampHeader?})` | caller-chosen | HMAC of `rawBody`, or `${timestamp}.${rawBody}` when `timestampHeader` is set. Optional skew (default 300s). |
+| `stripeSignature({secret, toleranceSec?})` | `Stripe-Signature` | HMAC-SHA256 of `${t}.${rawBody}`. Default 300s timestamp window. |
+| `twilioSignature({authToken, url})` | `X-Twilio-Signature` | HMAC-SHA1 base64 of callback URL + sorted POST fields. Form-urlencoded only. |
+| `sendgridEventSignature({publicKey, toleranceSec?})` | `X-Twilio-Email-Event-Webhook-Signature` + timestamp | ECDSA P-256 over `${timestamp}${rawBody}`. Default 300s timestamp window. |
+
+Invalid or missing signatures return `401` with `code: "webhook-signature-invalid"`.
+Missing `rawBody` returns `400` `webhook-body-missing`. Duplicate `(source, eventId)`
+returns `200 {received: true, duplicate: true}` without running the handler. A throwing
+handler returns `500` and **releases** the claim so a retry can run.
+
+Pass `idempotency: {store: "mongo", ttlDays?}` to persist claims in the `webhookReceipts` collection
+(unique `(source, eventId)`, TTL on `created`, default 7 days). This is not a public `modelRouter`
+model. Use `store: "memory"` in tests and single-process apps.
+
+SendGrid posts an array. Omit route-level `eventId` and call `webhooks.claim({source, eventId})`
+per `sg_event_id` inside the handler (release on throw).
+
+Webhook POSTs are anonymous (no JWT). They are **not** listed in `/openapi.json` and are
+**not** skipped by the rate limiter.
+
+See [@terreno/comms](../reference/comms.md) for Twilio/SendGrid mapping tables.