@terreno/mcp 57.2.0 → 57.3.0

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

@@ -0,0 +1,80 @@
+# 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` only when Acceptance is roastable and
+   the work fits one Pick comment (at most five tasks). Leave the issue unassigned.
+   Do not edit the issue body after you label it unless you are a maintainer; the
+   skill 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 posts `<!-- terreno-pick-plan -->` from that trusted snapshot, Pick ⇄ Roasts
+   that comment, then Brews a **draft** PR with `Fixes #<n>`.
+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 decision.
+Those stay `status:needs-info` or go through `/work-github-issues`.
+
+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/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.

package/src/docs/versioned/next/how-to/install-agent-skills.md

@@ -8,28 +8,79 @@ npx skills add FlourishHealth/terreno --skill terreno-1-grow
 ```
 
 That copies the committed `skills/` tree: lifecycle stages (Grow, Pick, Roast, Brew,
-Taste), repository skills, and published package skills.
+Taste), three outer loops, combined Terreno app workflows, and optional repository
+skills.
+
+## Install as a host plugin
+
+The combined lifecycle and Terreno app workflows ship as one host plugin. Stage names
+differ by host because Claude Code takes a plugin skill's command from the frontmatter
+`name`.
+
+| Host | Plugin | Invoke Grow |
+| --- | --- | --- |
+| Cursor | `terreno-planning` | `/terreno-1-grow` |
+| Codex | `terreno-planning` | `$terreno-1-grow` |
+| Claude Code | `terreno` | `/terreno:1-grow` |
+
+### Cursor
+
+Install `terreno-planning` from [`.cursor-plugin/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.cursor-plugin/marketplace.json), then invoke `/terreno-1-grow`.
+
+### Codex
+
+```text
+codex plugin marketplace add FlourishHealth/terreno
+codex plugin install terreno-planning --source terreno-plugins
+$terreno-1-grow
+```
+
+Marketplace: [`.agents/plugins/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.agents/plugins/marketplace.json).
+Codex installs the canonical plugin at
+[`plugins/terreno-planning/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-planning)
+(`.codex-plugin/plugin.json`). A clone of this repo already exposes that marketplace.
+
+### Claude Code
+
+```text
+/plugin marketplace add FlourishHealth/terreno
+/plugin install terreno@terreno-plugins
+/terreno:1-grow
+```
+
+Marketplace: [`.claude-plugin/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.claude-plugin/marketplace.json).
+Claude Code stages, app skills, and agents come from the generated copy at
+[`plugins/terreno-claude/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-claude).
 
 ## What you get
 
 | Group | Skills |
 | --- | --- |
-| Lifecycle | `terreno-1-grow` … `terreno-5-taste` |
-| Terreno apps | backend, UI, data, schema, SDK |
+| Lifecycle | `terreno-1-grow` … `terreno-5-taste`, `terreno-pick-roast-loop`, `terreno-planning-loop`, `terreno-taste-sweep` |
+| Terreno apps | backend, UI, admin interfaces, data, schema, SDK, prompts, upgrades, deployment |
 | Docs | `update-docs`, `update-agent-docs`, architecture skills |
-| GitHub | commit, PR, review, verify, release, deploy |
+| GitHub | issues, review, UI verification, release, dependency updates |
+| Expo and native | `track-upstream-expo`, `upgrading-expo`, deployment / EAS skills |
+| Plugin agents | `pre-commit`, `ui-verifier` |
 
 `skills.sh.json` at the repo root groups those names on [skills.sh](https://skills.sh).
+Cursor and Claude Code load the bundled plugin agents. Codex loads the combined skill
+set but does not currently expose plugin-defined agents.
 
 ## Keep copies in sync (Terreno maintainers)
 
 Canonical sources:
 
-1. `.rulesync/skills/` — repository skills (`bun run rules` generates agent copies)
-2. `plugins/terreno-planning/skills/` — portable lifecycle stages
-3. `<package>/.ai/skills/` — published package skills; these overlay the repo copies
+1. `plugins/terreno-planning/skills/` — lifecycle and reusable Terreno app workflows
+2. `plugins/terreno-planning/agents/` — reusable verification agents
+3. `.rulesync/skills/` — repository-only and optional Expo skills (`bun run rules` generates agent copies)
+4. `<package>/.ai/skills/` — package/MCP-specific copies; not installable overlays
+
+`plugins/terreno-claude/` is generated from sources 1 and 2 with shortened lifecycle names.
+Codex uses the canonical plugin plus committed `.codex-plugin/plugin.json` and
+`.agents/plugins/marketplace.json` — do not generate a third plugin tree.
 
-Regenerate the installable tree:
+Regenerate the installable tree and the Claude plugin:
 
 ```bash
 bun run skills:sync
@@ -38,6 +89,14 @@ bun run check:lifecycle-skills
 
 Do not hand-edit `skills/`.
 
+## Keep native hooks in sync
+
+Repository-level hooks are canonical in `.rulesync/hooks.json`; shared commands live in
+`.rulesync/hooks/`. Run `bun run rules` after either changes. Rulesync generates the
+native stop-hook configuration for Cursor, Claude Code, GitHub Copilot, and Devin. The
+committed quality hook runs both `bun run lint` and `bun run compile` before
+an agent finishes.
+
 ## Write human docs with the skills
 
 Skills read architecture docs before changing code. After a user-visible or architectural

package/src/docs/versioned/next/how-to/migrate-rtk-to-syncdb.md

@@ -4,6 +4,8 @@ This guide is **AI-context-first**: it is written for an agent (or human) perfor
 
 `@terreno/syncdb` supersedes `@terreno/rtk` for **data synchronization** (CRUD reads/writes, offline queue, realtime convergence). It does not replace the generated OpenAPI SDK, Better Auth Redux wiring, or feature-flag infrastructure.
 
+`modelRouter` `realtime`, `realtimeList`, `realtimeDocument`, and `setRealtimeSocket` are **deprecated** and **will be removed in Terreno 58**. `RealtimeApp` stays as the socket host for syncdb. Removal checklist: [`docs/tasks/remove-legacy-realtime.md`](https://github.com/FlourishHealth/terreno/blob/master/docs/tasks/remove-legacy-realtime.md).
+
 ## 1. Before you start
 
 | Decision | Requirement | Why |

package/src/docs/versioned/next/how-to/password-reset.md

@@ -0,0 +1,69 @@
+# Password reset and email verification
+
+Wire JWT recovery routes and Better Auth to `@terreno/comms` mail, then add a reset screen.
+
+## 1. User schema
+
+1. Apply `emailVerificationPlugin` so `emailVerified` defaults to false.
+2. Add `tokenEpoch` (number, default 0) so password reset can invalidate refresh tokens.
+
+```typescript
+import {emailVerificationPlugin} from "@terreno/api";
+
+userSchema.plugin(emailVerificationPlugin);
+```
+
+## 2. JWT `authOptions`
+
+Set `publicAppUrl` and `sendMail`. Forgot-password always returns 202.
+
+```typescript
+authOptions: {
+  publicAppUrl: process.env.FRONTEND_URL || "http://localhost:8082",
+  sendMail: async (message) => {
+    await getCommsService().sendMail(message);
+  },
+  requireEmailVerification: false,
+}
+```
+
+| Action | Path | Body |
+| --- | --- | --- |
+| Forgot | `POST /auth/forgotPassword` | `{email}` → 202 |
+| Reset | `POST /auth/resetPassword` or `POST /resetPassword` | `{token, password}` or `{token, newPassword}` |
+| Send verify | `POST /auth/sendVerification` | authenticated → 202 after delivery; 501 if `publicAppUrl` is missing |
+| Verify | `POST /auth/verifyEmail` | `{token}` |
+
+Reset links: `${publicAppUrl}/resetPassword?token=...`. Verify links: `${publicAppUrl}/verifyEmail?token=...`.
+
+Set `requireEmailVerification: true` to return 403 `email-not-verified` on JWT login until verify succeeds. Signup still returns JWTs and sends the verify mail.
+
+## 3. Comms templates
+
+```typescript
+import {renderAuthMail} from "@terreno/comms";
+
+const mail = renderAuthMail({
+  publicAppUrl: "https://app.example.com",
+  templateId: "resetPassword",
+  token,
+});
+```
+
+Pass `templates` to override subject/text/html. Variables: `resetUrl`, `verifyUrl`, `publicAppUrl`, `token`.
+
+## 4. Better Auth
+
+On `BetterAuthConfig` set the same `publicAppUrl`, `sendMail`, and `renderAuthMail` from `@terreno/comms`. That wires `sendResetPassword` and `sendVerificationEmail` to those templates. Those hooks do not send (they throw 501) when `publicAppUrl` is empty.
+
+## 5. Frontend
+
+1. Pass `onForgotPassword` (or `onForgotPasswordPress`) to `LoginScreen`.
+2. Add `/forgotPassword` (email form) and `/resetPassword` that reads `token` from the query string.
+3. On Better Auth apps, request reset with `authClient.requestPasswordReset` and submit with `authClient.resetPassword({newPassword, token})`. JWT apps use `POST /auth/forgotPassword` and the RTK `resetPassword` mutation (`POST /resetPassword`). The example app falls back to the JWT request or reset route when Better Auth rejects the operation, so either auth mode can complete.
+4. Show a profile banner when `emailVerified` is false, with Resend calling `POST /auth/sendVerification`.
+5. Add `/verifyEmail` that reads `token` from the query string. JWT apps call `POST /auth/verifyEmail`. Better Auth apps try `GET /verify-email?token=...` first, then the JWT route so either token type can complete.
+
+A new `issueFor` for the same user and type invalidates earlier unused tokens of that type. Changing the mailbox through `PATCH /auth/me` invalidates unused `passwordReset` tokens even when the User schema has no `emailVerified` field. When `emailVerificationPlugin` is applied, mailbox change also sets `emailVerified` to false and invalidates unused `emailVerification` tokens. Letter casing alone does not count as a mailbox change. `emailVerified` and `tokenEpoch` are privileged user fields: signup and `PATCH /auth/me` drop them.
+
+Better Auth password reset revokes that user's Better Auth sessions (`revokeSessionsOnPasswordReset`) and, when an app User exists, updates the JWT password and `tokenEpoch` so `POST /auth/login` cannot keep the old passport hash. JWT `POST /auth/resetPassword` does the reverse for Better Auth when `BetterAuthApp` is registered: it updates the Better Auth password and deletes Better Auth sessions. Console mail in development prints length only; check `CommsMessage` / console adapter logs for delivery, not the raw token in logger output. Request logs redact `password`, `newPassword`, `oldPassword`, `token`, and `refreshToken` in bodies and in URL query strings.

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

@@ -0,0 +1,78 @@
+# 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.
+
+## 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/*` | 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.
+
+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/next/how-to/seed-a-database.md

@@ -0,0 +1,88 @@
+# Seed a database
+
+Use `runSeedCli` to keep development and test data aligned with code. Seed plans
+sync by default, can preview writes, and can reset only the data each step owns.
+
+## Define a seed plan
+
+```typescript
+import {runSeedCli, type SeedStep} from "@terreno/api";
+import mongoose from "mongoose";
+import {Todo} from "../models/todo";
+import {connectToMongoDB} from "../utils/database";
+
+const steps: SeedStep[] = [
+  {
+    name: "todos",
+    reset: async (context) => {
+      await context.deleteMany(Todo);
+    },
+    run: async (context) => {
+      await context.upsert(
+        Todo,
+        {seedKey: "welcome"},
+        {seedKey: "welcome", title: "Welcome to the app"}
+      );
+    },
+  },
+];
+
+const result = await runSeedCli({
+  allowProductionReset: () => process.env.ALLOW_SEED_RESET === "true",
+  connect: connectToMongoDB,
+  disconnect: async () => mongoose.disconnect(),
+  name: "bun run seed",
+  steps,
+});
+
+process.exit(result.exitCode);
+```
+
+Add the package command:
+
+```json
+{"scripts": {"seed": "bun run src/scripts/seed.ts"}}
+```
+
+## Run seeds
+
+```bash
+bun run seed                         # create or update code-defined data
+bun run seed --dry-run               # preview without writes
+bun run seed --only todos            # one step and its dependencies
+bun run seed --reset                 # reset managed data, then reseed
+```
+
+`--only` may be repeated. Declare `dependsOn` when one step needs records from
+another; dependencies run first. In reset mode, reset handlers run in reverse
+order so dependent records are removed before their parents.
+
+## Make sync runs idempotent
+
+Use `context.upsert(model, key, values)` with a stable, unique business key.
+The helper reports `created`, `updated`, or `unchanged` and writes only when the
+declared values differ. Nested arrays are compared without generated subdocument
+`_id`s, so feature-flag rules and similar payloads stay unchanged across syncs.
+`Map` values (for example consent-form `content`) compare as plain key/value
+objects so stored documents are not rewritten on every sync.
+If `isDeletedPlugin` hid a matching row, `upsert` restores that document instead
+of inserting a duplicate. If more than one document already shares the key,
+`upsert` keeps the first match, tombstones or deletes the extras, then syncs
+the survivor. Use `context.deleteMany()` only inside reset handlers.
+Custom writes must check `context.dryRun` themselves.
+
+For Better Auth credentials, call `seedBetterAuthUser({auth, user, userModel})`.
+It creates a missing credential account, signs in when the account already
+exists, and reconciles the application user document.
+
+## Guard destructive resets
+
+Production reset mode is denied by default. It runs only when both conditions
+are true:
+
+1. The CLI receives `--force`.
+2. `allowProductionReset` returns `true` (normally from a dedicated environment variable).
+
+Reset handlers should delete only records owned by the seed plan. Preserve
+authentication, migration history, and operator-created data unless the plan
+explicitly manages them.

package/src/docs/versioned/next/how-to/track-upstream-expo.md

@@ -0,0 +1,52 @@
+# Track upstream Expo SDK betas
+
+Morning maintainer loop: see if Expo published a **new SDK major beta**, keep
+a long-lived `release-X.Y.Z` branch building, and leave a log so the next
+morning can resume.
+
+Agent procedure: skill `track-upstream-expo`. Upgrade commands: skill
+`upgrading-expo`. Log contract: skill reference `loop-log.md`.
+
+## 1. Probe
+
+From latest `master`:
+
+```bash
+bun run expo:track-probe
+```
+
+| Exit | Meaning |
+| --- | --- |
+| `1` | Nothing newer **and** no `open`/`blocked` loop. Stop. |
+| `0` | `create-branch`, `continue-branch` (newer beta), or `resume-loop` (same beta, unfinished). |
+| `2` | Probe broke (network/git). Fix that; do not skip. |
+
+The probe ignores patches of the current catalog major. It watches
+`expo@next` and `expo@latest` for a **higher major**, fetches `origin`
+`release-*` refs, then reads `loopStatus` from
+`origin/<releaseBranch>:scripts/track-upstream-expo/tracked.json`.
+
+State files (in the repo, not linked from this page):
+
+- `scripts/track-upstream-expo/tracked.json` — `expoVersion`, `loopStatus`
+- `scripts/track-upstream-expo/loop-log.md` — tries, failures, release-notes draft
+
+## 2. Branch name
+
+Expo `58.0.0-preview.1` → `release-58.0.0`. Create from `origin/master` the
+first day. Later days check it out, merge `master`, and either bump to a
+newer preview or resume **Open** items from the log.
+
+Do not merge `release-*` to master from this job.
+
+## 3. Native modules stay on the SDK train
+
+Packages that change the EAS fingerprint update **on this branch only**.
+
+## 4. Handoff every session
+
+Before edits: read `loop-log.md` (**Next**, **Open**, **Do not retry**).
+
+After edits: prepend **Tried**, refresh **Next** / **Open**, extend
+**Release notes draft**, set `loopStatus` to `open`, `blocked`, or `ready`,
+and push the release branch. Tomorrow starts from that commit.

package/src/docs/versioned/next/how-to/update-dependencies.md

@@ -0,0 +1,54 @@
+# Update dependencies
+
+This runs **daily**. Use `/update-dependencies`. There is one rolling PR; later days push to it and rewrite its ledger instead of opening new PRs.
+
+```bash
+REPOSITORY="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"
+OWNER="${REPOSITORY%%/*}"
+NAME="${REPOSITORY#*/}"
+gh pr list --state open --head chore/update-dependencies \
+  --json number,url,baseRefName,headRefName,headRepository,headRepositoryOwner,isCrossRepository \
+  | jq --arg owner "$OWNER" --arg name "$NAME" \
+      '[.[] | select(
+        .isCrossRepository == false and
+        .baseRefName == "master" and
+        .headRefName == "chore/update-dependencies" and
+        .headRepository.name == $name and
+        .headRepositoryOwner.login == $owner
+      )]'
+bun outdated
+```
+
+Prove each bump with an **exercise test** that imports that package. Keep Expo fingerprints for `example-frontend` and `demo` unchanged. Skip `isFingerprintSkip` names until a release.
+
+Why: [Dependency management](../explanation/dependency-management.md). Native Expo/React Native bumps wait for `upgrading-expo`.
+
+## Do now
+
+1. Find the same-repository PR with exact head `chore/update-dependencies`, base `master`, and `isCrossRepository: false`. Marker/title matches are not trust signals; ignore forks. Merge `origin/master` without rewriting history. If no trusted PR exists, create the canonical branch on this run.
+2. Inventory with `bun outdated`. Retry **Failed** rows from the PR body first. Skip `isFingerprintSkip` in `scripts/planning/fingerprintRisk.ts`.
+3. For each candidate: confirm a test imports the package (add a tracer if needed), bump the catalog pin or single-use version, `bun install`, re-run that test, recompute fingerprints. Revert only that bump on failure.
+4. Commit each success on the same branch. Push. Update the **same** PR body: Last run, Landed, Failed, Skipped, Deferred to release. Do not `gh pr create` when that PR is already open.
+5. Read the ledger tomorrow; do not start a new PR.
+
+## Guardrails
+
+| Rule | Action |
+| --- | --- |
+| Trusted rolling PR already exists | Push to its same-repository `chore/update-dependencies` head and edit that body |
+| Fork copies marker/title/branch | Ignore it; never checkout, copy, edit, close, or comment on it |
+| Fingerprint would change | Revert that bump. Defer to a release. Never add `fingerprint-acknowledged` |
+| No test imports the package | Write the tracer test first. Do not bump on `test:ci` alone |
+| Published < 7 days ago (non-CVE) | Skip; log under Skipped |
+| Major version | May land on the rolling PR if tests + fingerprints pass; no auto-merge |
+| Dependabot extra PRs | Do not merge skip-list packages; fold JS bumps into the rolling PR |
+
+## Fingerprints
+
+`example-frontend` and `demo` use `fingerprint.config.js`. Hash with `eas fingerprint:generate` when `EXPO_TOKEN` is set, otherwise `bunx @expo/fingerprint <app-dir>`. Take a baseline after rebase, before new installs. After each successful bump, the new hashes become the baseline for the next package.
+
+`eas.json` Bun pins feed the fingerprint. Do not bump them here.
+
+## Dependabot still runs
+
+GitHub Dependabot remains in `.github/dependabot.yml`. Root catalog ignores native/Expo packages. Treat Dependabot as a signal; land updates on the rolling PR from this guide.

package/src/docs/versioned/next/how-to/upgrade-banner.md

@@ -84,7 +84,7 @@ The hook handles:
 
 ### 4. Admin: Configure thresholds
 
-Navigate to the admin panel and select "Version Config". Set:
+Open the admin panel's `/version-config` route directly. The configuration screen is not included in the main sidebar. Set:
 
 - **Web Warning Version**: Build number below which web users see a warning toast
 - **Web Required Version**: Build number below which web users are blocked