@terreno/mcp 57.21.0 → 57.22.0

package/src/docs/versioned/57.21.0/how-to/product-announcements.md

@@ -0,0 +1,160 @@
+# Product announcements
+
+Use `@terreno/announcements` on the backend and `AnnouncementNavigator` on the frontend to show admin-managed update surfaces.
+
+## Backend
+
+1. Register the plugin on your `TerrenoApp`:
+
+```typescript
+import {AnnouncementsApp} from "@terreno/announcements";
+
+new AnnouncementsApp({
+  defaultAcknowledgementPolicy: "dismiss-only",
+  uploadToken: process.env.ANNOUNCEMENTS_UPLOAD_TOKEN,
+  // audienceType staff/patient/all is applied inside the plugin via matchAudienceByType.
+  isStaff: (user) => (user as {admin?: boolean}).admin === true,
+  matchAudience: (user, announcement) => {
+    const audience = announcement.audience as {organizationIds?: string[]};
+    if (!audience.organizationIds?.length) {
+      return true;
+    }
+    const userOrganizationIds = (user as {organizationIds?: string[]}).organizationIds ?? [];
+    return audience.organizationIds.some((organizationId) =>
+      userOrganizationIds.includes(organizationId)
+    );
+  },
+});
+```
+
+Use admin `audienceType` for staff vs patient vs all. Reserve the `audience` JSON field for custom segments (orgs, tiers, feature cohorts) in `matchAudience`. Do **not** call `matchAudienceByType` in your app — the plugin composes it before your callback.
+
+When the admin shell uses Terreno RBAC without the legacy `user.admin` flag, pass the same read permission to the overview:
+
+```typescript
+new AnnouncementsApp({
+  adminOverviewPermissions: [access.permission({adminAnnouncement: ["read"]})],
+});
+```
+
+For Flourish-style surfaces on one collection:
+
+| Audience | Typical `displayMode` | `acknowledgementPolicy` |
+|----------|----------------------|-------------------------|
+| `staff` | `modal` (blocking) | `required` |
+| `patient` | `banner` or `feed` | `dismiss-only` |
+| `all` | any | per announcement or `defaultAcknowledgementPolicy` |
+
+2. Create announcements in admin (draft → publish). Use `AnnouncementOverview`, `AnnouncementEditor`, and (optionally) `AnnouncementList` from `@terreno/admin-frontend` with dedicated Expo routes (see `example-frontend/app/admin/announcements/`). The built-in admin screen widget key `announcements` renders the overview when your host uses `AdminScreenRouter` for custom screens. Published `title`/`body` edits auto-increment `version`, which re-shows the surface to users who only acknowledged the previous version.
+
+For release-driven batches, use an [announcement release pack](../reference/announcement-release-packs.md). It keeps one `pack.yaml` manifest plus multiple Markdown announcements in source control, validates release and build versioning, and can import idempotent drafts or explicitly publish the whole pack through a dedicated bearer token. The example Cloud Run service accepts `Authorization: Bearer terreno-example-announcement-upload` (Terraform variable `announcements_upload_token`).
+
+### Admin editor fields
+
+`AnnouncementEditor` exposes structured targeting controls (no raw `requiresAcknowledgement` boolean):
+
+| Field | Control | Notes |
+|-------|---------|-------|
+| `displayMode` | Select | `modal`, `banner`, or `feed` |
+| `audienceType` | Select | `all`, `staff`, or `patient` — composed with `matchAudience` |
+| `acknowledgementPolicy` | Select | `required` or `dismiss-only`. On **create**, pre-filled from `GET /announcements/config` (`defaultAcknowledgementPolicy`); defaults to `dismiss-only` when config is unavailable |
+| `minBuildNumber` | Number (optional) | Minimum client build; cleared with `null` on edit when empty |
+| `platforms` | Multiselect | One or more of iOS, Android, and web; at least one is required |
+| `audience` | JSON textarea (advanced) | Opaque metadata for `matchAudience`; use audience type for staff/patient/all |
+
+### Admin overview
+
+`AnnouncementOverview` calls `GET /announcements/overview` (via RTK `injectEndpoints`) and shows:
+
+- Launch workflow guidance (draft → targeting → preview → publish) with a primary **Create announcement** action
+- Summary cards for published, drafts, impressions, acknowledgements, and CTA clicks
+- A paginated table with per-row metrics and an edit action
+- Optional quick links to the raw acknowledgement, impression, and click-event admin tables
+
+Register the screen through `AnnouncementsApp.adminContribution()` (`customScreens: [{ name: "announcements", displayName: "Overview", group: "Announcements" }]`) and rely on `ANNOUNCEMENTS_ADMIN_WIDGETS` from `@terreno/admin-frontend` (merged into `BUILT_IN_SCREEN_WIDGETS`). Grouped custom screens appear in the **Announcements** sidebar group before model links; ungrouped screens stay under **Screens**.
+
+`AnnouncementList` remains available for a CRUD-style list; the overview is the launch dashboard.
+
+`AnnouncementEditor` uses `MultiselectField` for platforms and requires at least one platform before save.
+
+<img alt="Announcement overview with delivery metrics" src="/img/announcements/admin-overview.png" />
+
+<img alt="Platform multiselect in the announcement editor" src="/img/announcements/admin-editor-platforms.png" />
+
+## Frontend
+
+Wrap authenticated app content:
+
+```tsx
+import {AnnouncementNavigator} from "@terreno/ui";
+
+<AnnouncementNavigator api={terrenoApi}>
+  <AppTabs />
+</AnnouncementNavigator>
+```
+
+Place it after consent/onboarding wrappers if you use `ConsentNavigator`. The navigator sends the native platform (`ios` / `android` / `web`) and, when available, the app build number from `Constants.expoConfig.extra.buildNumber` (same source as `useUpgradeCheck`) on pending and feed requests. Only pending failures block the app — changelog feed errors are non-fatal. These surfaces are not in the `@terreno/ui` component demo; wire them in the app (`example-frontend`) the same way.
+
+## Modal vs banner
+
+| `displayMode` | Navigator behavior |
+|---------------|-------------------|
+| `modal` | Renders `AnnouncementScreen` and hides children until the announcement is cleared. |
+| `banner` | Keeps children mounted and renders `AnnouncementBanner` above them (one interrupt at a time). |
+| `feed` | Changelog-only; never shown by `AnnouncementNavigator` even if it appears unexpectedly in `pending.current`. |
+
+`AnnouncementBanner` composes the existing `Banner` component: title text, a dismiss or acknowledgement action, and an optional primary-action button. When used inside `AnnouncementNavigator`, primary CTA presses call `POST /announcements/:id/click` (via `useAcknowledgeAnnouncement().recordClick`) and then open the URL; tracking failures never block navigation.
+
+Acknowledgement policy still resolves to `requiresAcknowledgement` on the public DTO:
+
+| Policy | Banner / modal behavior |
+|--------|-------------------------|
+| `required` | Primary action is **Got it**, which acknowledges through the existing handler. |
+| `dismiss-only` | Dismiss records an impression only. |
+
+Impressions are recorded once per announcement version while the modal or banner is visible.
+
+## Client frequency caps
+
+Interrupt frequency is enforced **client-side** in `AnnouncementNavigator` before a modal or banner is shown. The server still returns the full pending queue; caps never filter `useAnnouncements` feed data.
+
+```tsx
+<AnnouncementNavigator
+  api={terrenoApi}
+  frequency={{
+    cooldownHours: 24,
+    skipFirstLaunch: false,
+    userId: currentUser?.id,
+  }}
+>
+  <AppTabs />
+</AnnouncementNavigator>
+```
+
+`maxInterruptionsPerSession` defaults to `1` when omitted. The example app sets `skipFirstLaunch: false` so an announcement an admin publishes appears on the next launch.
+
+| Prop | Default | Behavior |
+|------|---------|----------|
+| `maxInterruptionsPerSession` | `1` | In-memory module session counter. After the cap is reached, pending interrupts are skipped until the JS runtime reloads (cold start / full app restart). Remounting `AnnouncementNavigator` alone does **not** reset the counter. |
+| `cooldownHours` | off | When set, skips interrupts if the last shown interrupt was within this many hours. Timestamp is persisted in AsyncStorage when an interrupt becomes visible. |
+| `skipFirstLaunch` | `false` | When `true`, the first app launch ever (no `hasLaunched` key) records the flag and skips interrupts for that launch only. |
+| `userId` | `"anon"` | AsyncStorage namespace for frequency keys when a signed-in user id is available. |
+
+When a cap applies, the navigator renders children (does not block the app) and does **not** record an impression. AsyncStorage read/write failures fail open with a `console.warn` and allow the interrupt to show. If `hasLaunched` cannot be persisted on first launch, the interrupt is shown and the in-memory first-launch skip is not armed for the rest of the session.
+
+Tests call `resetFrequencySessionStateForTests()` to simulate a cold start; that helper is not part of the production API.
+
+## Media in markdown
+
+Paste YouTube or Loom URLs in the announcement `body` using markdown links or images, for example `[Watch the demo](https://www.youtube.com/watch?v=...)`. `MarkdownView` renders them as embeds (iframe on web, WebView on native). Banner surfaces show the title only; use modal mode or the feed when the full body should be visible.
+
+## Example app
+
+`example-backend` registers `AnnouncementsApp` with `isStaff: (user) => user.admin === true` and an optional `matchAudience` org filter. `bun run backend:seed` idempotently seeds two **drafts**:
+
+- **Staff modal (required)** — `audienceType: "staff"`, `displayMode: "modal"`, `acknowledgementPolicy: "required"` (`Example staff operations bulletin`)
+- **Patient banner (dismiss-only)** — `audienceType: "patient"`, `displayMode: "banner"`, `acknowledgementPolicy: "dismiss-only"` (`Example patient care tip`)
+
+The seed keeps them as drafts so a fresh database (local dev or a PR preview) does not interrupt sign-in. Publish one from **Admin → Announcements** to see it. Re-running the seed updates both examples in place and sets them back to draft. The staff example is rich markdown with a YouTube embed, overview/editor screenshots, and a tracked docs CTA. An existing legacy welcome row (`Welcome to Terreno announcements`) is archived idempotently. `example-frontend` wraps authenticated users with `AnnouncementNavigator` (`skipFirstLaunch: false`, `userId` from the profile).
+
+Release notes in the example app use [`WhatsNewBanner`](./whats-new-banner.md) instead of announcements.

package/src/docs/versioned/57.21.0/how-to/rate-limiting.md

@@ -0,0 +1,95 @@
+# Rate limiting
+
+Turn on HTTP rate limiting for `@terreno/api` by passing `rateLimit` on `TerrenoApp`. The framework does **not** read `RATE_LIMIT_ENABLED`.
+
+Terreno 58 will default the limiter **on**. Until then, omit `rateLimit` to leave it off.
+
+## Terreno 58 (not this release)
+
+When Terreno 58 is cut, `TerrenoApp` will enable the limiter by default. Apps that must stay unlimited will pass an explicit off (documented in the 58 upgrade note). Until then, omitted `rateLimit` is unlimited. Stub: [`mcp-server/src/docs/upgrades/58.0.0.md`](../../mcp-server/src/docs/upgrades/58.0.0.md).
+
+## Enable (memory)
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined,
+});
+```
+
+Empty `{}` is the same as `{store: "memory"}`.
+
+## Redis on Cloud Run
+
+1. Add a Valkey or Redis instance (Memorystore or equivalent).
+2. Set `VALKEY_URL` (preferred) or `REDIS_URL` on the Cloud Run service. Same URL as realtime Redis.
+3. Pass `store: "redis"` only when you intend to enable the limiter:
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  rateLimit:
+    process.env.RATE_LIMIT_ENABLED === "true"
+      ? {store: "redis", trustProxy: 1}
+      : undefined,
+});
+```
+
+4. Install `ioredis` in the app that runs `@terreno/api` if it is not already a dependency.
+5. Missing `VALKEY_URL` / `REDIS_URL` fails **startup** when `store: "redis"` (clear `APIError`).
+
+## Stores
+
+| `store` | When to use | Config |
+| --- | --- | --- |
+| `memory` (default) | Single process | none |
+| `redis` | Shared bucket across replicas | `VALKEY_URL` then `REDIS_URL` |
+| `mongo` | Shared bucket without Redis | Open mongoose connection; collection `rateLimitHits` with TTL on `expiresAt` |
+
+## Mongo
+
+Pass `{store: "mongo"}`. Hits live in `rateLimitHits` on the same mongoose connection as the app. A TTL index on `expiresAt` expires windows. This collection is not a `modelRouter` resource.
+
+Unauthenticated keys use `req.ip`. Express `trust proxy` defaults to **off** so a client cannot rotate `X-Forwarded-For` to bypass the auth bucket. On Cloud Run (one hop via GFE), pass `trustProxy: 1`. Extra proxies: hop count or a subnet list. `trustProxy: false` is the same as the default.
+
+## Limit one route
+
+Use `createRouteRateLimitMiddleware` for a stricter limit on one expensive route. It works with or without the global limiter.
+
+```typescript
+import {createRouteRateLimitMiddleware} from "@terreno/api";
+
+const uploadLimit = createRouteRateLimitMiddleware({
+  name: "uploads",
+  max: 1,
+  windowMs: 60_000,
+  store: "mongo",
+});
+```
+
+`DocumentStorageApp` takes the same options as `uploadRateLimit`. The example backend allows one upload per IP per minute and sets `trust proxy` to `1` on Cloud Run so the key is the real client IP.
+
+## Auth vs API buckets
+
+| Path | Bucket |
+| --- | --- |
+| `POST /auth/login`, `/auth/signup`, `/auth/refresh_token` | auth (20 / 15 min) |
+| `POST /auth/forgotPassword`, `/auth/resetPassword`, `/resetPassword` | auth |
+| `POST /auth/sendVerification`, `/auth/verifyEmail` | auth |
+| `GET /auth/github`, `/auth/github/callback` | auth |
+| `{betterAuthBasePath}/sign-in/*`, `sign-up/*`, `forget-password`, `request-password-reset`, `reset-password`, `send-verification-email`, `verify-email`, `callback/*`, `oauth-handoff/*`, `one-time-token/*` | auth |
+| Trailing slash on those paths (`/auth/login/`) | same bucket as the unsuffixed path |
+| `GET`/`PATCH /auth/me` | api (600 / 15 min) |
+| modelRouter, admin, AI HTTP, `POST /mcp`, `POST /sync/mutate` | api |
+| `GET /health`, `/healthz`, `/openapi.json`, `/swagger` | skip |
+
+`rateLimit.skip` adds extra skips. Health/openapi/swagger always skip. Paths use Express `req.path` (not the raw request-target), without a trailing slash. Classification also resolves `.` and `..` segments, including `%2e` forms, the way Better Auth's router does: a request is charged to the auth bucket when either the path as sent or its resolved form is a credential route (so `/api/auth/%2e/sign-in/email` counts as sign-in), and a path that contains dot segments never gets the health/openapi/swagger skip.
+
+JWT login/signup/refresh and password-reset paths skip access-token verification so a stale `Authorization` header cannot block credential exchange. Other routes still 401 on an expired JWT. Path matching uses Express `req.path` and ignores trailing slashes and letter case.
+
+Auth-bucket keys are always the client IP, even if a Better Auth session already set `req.user`. API traffic still keys by user when authenticated.
+
+When `BetterAuthApp` is registered, TerrenoApp copies its `config.basePath` into the limiter unless you set `rateLimit.betterAuthBasePath`.
+
+
+

package/src/docs/versioned/57.21.0/how-to/recover-locked-out-user.md

@@ -0,0 +1,112 @@
+# Recover a locked-out user
+
+Help a user who lost their authenticator, passkey, or social account get back in. Platform
+staff use `/users/:id/security`; org-admins use `/orgs/:orgId/members/:userId/security`. Both
+run the same handlers, and every change writes a security `AuditEvent`.
+
+## Before you start
+
+1. Register `AuditApp` and `AccountSecurityApp` on the `TerrenoApp`:
+
+   ```typescript
+   import {AccountSecurityApp, AuditApp, BetterAuthApp, TerrenoApp} from "@terreno/api";
+
+   new TerrenoApp({accessControl: access, organizations: true, userModel: User})
+     .register(new BetterAuthApp({config: betterAuthConfig}))
+     .register(new AuditApp())
+     .register(new AccountSecurityApp())
+     .start();
+   ```
+
+2. For `disable` and `enable`, apply `isDisabledPlugin` to the User schema.
+3. For `send-password-reset`, set `sendMail` and `publicAppUrl` in `BetterAuthConfig`.
+4. For the org path, turn organizations on (`organizations: true`). `TerrenoApp` hands the
+   registered `AccountSecurityApp` to `OrgsApp`, which mounts the org routes.
+
+## Who can do what
+
+| Action | Route suffix | Platform staff (`user:manageSecurity`) | Org-admin of the user's org |
+| --- | --- | --- | --- |
+| Read the summary | `GET /security` | Yes | Yes |
+| Reset two-factor | `POST /security/reset-two-factor` | Yes | Yes |
+| Remove a passkey | `DELETE /security/passkeys/:passkeyId` | Yes | Yes |
+| Unlink a provider | `DELETE /security/accounts/:providerId` | Yes | Yes |
+| Sign out everywhere | `POST /security/revoke-sessions` | Yes | Yes |
+| Send a password reset | `POST /security/send-password-reset` | Yes | Yes |
+| Disable or enable the account | `POST /security/disable`, `/enable` | Yes | No |
+| Suspend the membership | `POST /security/suspend-membership` | Through the org path | Yes |
+| Issue a sign-in link | `POST /security/issue-sign-in-link` | `superadmin` only (`user:issueSignInLink`) | No |
+
+`superadmin` and `operator` hold `user:manageSecurity`. An org-admin is a user whose active
+`Membership` in that org has `roleName: "org-admin"`.
+
+Nobody can act on themselves, or on someone who holds a permission they lack. An org-admin can't
+reach platform staff or `admin: true` users, members of other orgs, or suspended members. Platform
+staff on the org path are judged the same way as on the platform path, so an org-only permission
+does not block them.
+
+## Platform path
+
+Prefix every route with `/users/<userId>`.
+
+1. Read the summary to see the user's sign-in methods and the actions that apply:
+
+   ```bash
+   curl -H "Authorization: Bearer $TOKEN" https://api.example.com/users/<userId>/security
+   ```
+
+   `data.actions` lists only the actions that apply to this user and that you may run.
+2. Run the action that fixes the problem:
+   - Lost authenticator: `POST .../reset-two-factor`. The user signs in with their password and
+     can enroll again.
+   - Lost device with a passkey: `DELETE .../passkeys/<passkeyId>` (ids are in the summary).
+   - Lost social account: `DELETE .../accounts/<providerId>`.
+   - Stolen device: `POST .../revoke-sessions`.
+   - Forgotten password: `POST .../send-password-reset`.
+   - Compromised account: `POST .../disable`. Later, `POST .../enable`.
+   - Legacy user with no password and no inbox: `POST .../issue-sign-in-link`, then give the
+     user the returned link yourself. Only a superadmin can do this.
+3. Removing the user's last sign-in method answers `409` unless their email is verified. With a
+   verified email, the route also mails a password reset.
+
+## Org path
+
+Prefix every route with `/orgs/<orgId>/members/<userId>`. The user must be an active member of
+`<orgId>`. They may belong to other orgs too.
+
+1. Read the summary: `GET /orgs/<orgId>/members/<userId>/security`.
+2. Run the same recovery actions as the platform path (2FA, passkey, provider, sessions, reset).
+3. To cut the user off from your org, run `POST .../suspend-membership`. It suspends only their
+   membership in `<orgId>`. They still sign in and keep their other orgs.
+4. To bring a suspended member back, use the membership route:
+   `PATCH /orgs/<orgId>/members/<memberId>` with `{"status": "active"}`. A suspended member is out
+   of reach of the security routes until then.
+
+To stop an org-admin from attaching an existing user by email and acting on them right away, set
+a minimum membership age:
+
+```typescript
+new TerrenoApp({
+  accessControl: access,
+  organizations: {orgRecovery: {minMembershipDays: 7}},
+  userModel: User,
+});
+```
+
+## Check the audit trail
+
+Every change is one `AuditEvent` with `source: "security"`. Org actions carry the org's id in
+`organizationId`. When `sendMail` is configured, each change also emails the user (except
+`send-password-reset`, whose reset email is the notice). For `issue-sign-in-link` the email says a
+link was created, never the link itself. The email says "an administrator" and never names you;
+see
+[Notifications](../reference/account-security.md#notifications).
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://api.example.com/audit-events?source=security&recordId=<userId>"
+```
+
+Related: [Account security reference](../reference/account-security.md),
+[How organization tenancy works](../explanation/organizations.md#member-recovery),
+[Enable the framework audit log](audit-log.md).

package/src/docs/versioned/57.21.0/how-to/release-automation.md

@@ -0,0 +1,83 @@
+# How to let agents merge release notes and roadmap updates
+
+An agent (or the scheduled roadmap workflow) opens a pull request. The **Bot merge** workflow
+([`.github/workflows/bot-merge.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/bot-merge.yml))
+merges it after CI passes. No human review is needed. For a release it then tags the merged commit,
+and that tag starts CircleCI `publish-release`. The packages are built from the tagged commit, so the
+release notes are already in each npm tarball.
+
+```text
+release/X.Y.Z PR ──► Bot merge waits for CI ──► squash-merge (bot bypass)
+                                                   │
+                                                   ▼
+                     tag X.Y.Z on the squash commit + draft GitHub release
+                                                   │
+                                                   ▼
+            CircleCI publish-release: require merged notes ──► npm publish
+                                                    (every tarball ships CHANGELOG.md)
+```
+
+## What the bot merges
+
+[`scripts/ci/release/lib.ts`](https://github.com/TerrenoLabs/terreno/blob/master/scripts/ci/release/lib.ts)
+(`planBotMerge`) decides eligibility. A pull request qualifies only if all of these are true:
+
+- It comes from a branch in this repository. Drafts and forks are skipped.
+- Its author is listed in the `BOT_MERGE_AUTHORS` repository variable. Logins are compared without regard to case.
+- Its branch name and changed files match one of the rows below.
+
+| Branch | Files it may change |
+|--------|---------------------|
+| `release/X.Y.Z` or `cursor/release-X.Y.Z` (stable versions only) | `CHANGELOG.md`, `changelog/unreleased/*`, `example-frontend/constants/whatsNew.generated.json`, `mcp-server/src/docs/upgrades/*.md` |
+| `automation/roadmap-*` | `ROADMAP.md`, `docs/explanation/roadmap-seed-issues.md` |
+
+A release branch also needs a non-empty `## [X.Y.Z]` section in its `CHANGELOG.md`. The workflow
+uses `pull_request_target`, so both the workflow file and the eligibility script come from
+`master`. A pull request cannot change its own eligibility rules. The job never runs pull request
+code; it reads file names and `CHANGELOG.md` through the API. Any pull request that fails a rule keeps a green **Bot merge** check and waits
+for a human. Examples are a release pull request that also edits a skill, or a prerelease branch.
+
+The `master` ruleset requires no status checks, so the workflow does that job itself. It waits
+until every other check on the head commit has passed, including GitHub Actions and CircleCI
+statuses. It merges with the head SHA pinned, so a push made after the checks finished blocks the
+merge.
+
+## The publish gate
+
+`publish-release` runs
+`bun run scripts/ci/release/cli.ts check-tag <tag> <on-master>` before it compiles anything. A
+stable tag fails if any of these is true:
+
+- The tagged commit is not on `master`.
+- `CHANGELOG.md` has no non-empty `## [X.Y.Z]` section.
+- Fragments are left in `changelog/unreleased/`.
+
+Prerelease tags (`-beta.N`) skip the gate; they are often cut from a feature branch.
+
+The manual fallback `.github/workflows/publish-on-tag.yml` runs the same `check-tag` gate. It also
+fails unless it was dispatched from the tag itself, because its publish jobs build the dispatched
+ref, not the tag by name. Use **Run workflow** with the tag selected as the ref.
+
+`scripts/ci/prepare-package-publish.mjs` copies the root `CHANGELOG.md` into each package before
+`npm publish`. Packages that declare a `files` whitelist list `CHANGELOG.md` in it.
+
+## One-time GitHub setup
+
+1. Create a GitHub App under **TerrenoLabs → Settings → Developer settings → GitHub Apps**. Turn
+   off webhooks. Give it these repository permissions:
+   - Contents: read and write
+   - Pull requests: read and write
+   - Metadata: read
+
+   Install it on `TerrenoLabs/terreno` only.
+2. Generate a private key. Add it as the repository secret `BOT_MERGE_PRIVATE_KEY`. Add the
+   App ID as the repository variable `BOT_MERGE_APP_ID`.
+3. Set the repository variable `BOT_MERGE_AUTHORS` to the logins allowed to open bot-merged pull
+   requests, separated by commas. Include the account that owns `ROADMAP_PROJECT_TOKEN`, which
+   opens the roadmap pull requests.
+4. Add the App as an **Always** bypass actor on both `master` rulesets (**Branch** and
+   **master protection**). Its token can then squash-merge without an approving review.
+
+Once these are set, the agent's job ends at opening the pull request. Steps 5b–5c of the
+[`release` skill](https://github.com/TerrenoLabs/terreno/blob/master/.rulesync/skills/release/SKILL.md)
+describe that hand-off.