@terreno/mcp 57.14.0 → 57.16.1

package/dist/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -57,7 +57,7 @@ duplicating sprint planning.
 **Title:** `Deploy to GCP (generalized)`
 
 **Labels:** `area:deploy`, `type:docs`  
-**Project fields:** Area=`deploy`, Target=`Next`, Impact=`Improvement`, IP=`deploy-to-gcp`, Status=`Planned`
+**Project fields:** Area=`deploy`, Target=`Next`, Impact=`Improvement`, IP=`deploy-to-gcp`, Status=`In progress`
 
 Turns Terreno's GCP deployment story from Flourish-specific infrastructure into a reusable
 guide any Terreno app can follow. It documents Cloud Run backend hosting, GCS plus CDN for

package/dist/docs/versioned/next/how-to/circleci.md

@@ -169,7 +169,7 @@ non-PR branch builds.
 | `example-frontend/**`, `admin-frontend/**`, `rtk/**`, `ui/**`, `ai/**`, `blocks/**`, `syncdb/**`, `bun.lock` | `run-deploy-frontend` | `deploy-frontend-preview` | `deploy-frontend` |
 | `docs/**`, `website/**` | `run-deploy-docs` | `deploy-docs-preview` | `deploy-docs` |
 | `example-backend/**`, `api/**`, `comms/**`, `jobs/**`, `admin-spa/**`, `feature-flags/**`, `announcements/**`, plus every frontend path above | `run-cd-backend` | `gcp-cd-preview` | `gcp-cd-prod` |
-| `terraform/**` | `run-cd-terraform` | `gcp-cd-preview` | `gcp-cd-prod` |
+| `terraform/**`, `infra/**` | `run-cd-terraform` | `gcp-cd-preview` | `gcp-cd-prod` |
 | `mcp-server/**`, `ui/**` | `run-cd-mcp` | _(none)_ | `gcp-cd-prod` (runs `mcp-server` `test:ci` first) |
 
 The backend image bundles the admin SPA (ui, rtk, admin-frontend, syncdb), so
@@ -260,12 +260,14 @@ Caching is off (200 credits per job). The docs Netlify target builds only the
 current docs tree, disables Docusaurus minification, and pins SSG to one worker
 thread so the build peaks near 3 GB and fits the 4 GB `medium` executor.
 Released versions are not rebuilt: `archive-docs-version` (in `publish-release`,
-`X.Y.0` tags only) builds each one once and uploads it to its GitHub release, and
-`deploy-docs` unpacks those archives under `/<version>/`. See `website/README.md`.
+`X.Y.0` tags only) builds each version once, uploads it to its **draft** GitHub
+release, publishes the release, and then commits the docs snapshot to master, so
+the `deploy-docs` run that commit starts can unpack the archive under
+`/<version>/`. See `website/README.md`.
 
 `terreno-gcp` uses CircleCI OIDC (`CIRCLE_OIDC_TOKEN_V2`), never a JSON service
 account key. Set `circleci_org_id`, `circleci_project_id`, and
-`circleci_gcp_context_id` in `terraform/terraform.tfvars`, apply once with an
+`circleci_gcp_context_id` in `infra/flourish/terraform.tfvars`, apply once with an
 existing Terraform admin identity, then copy `circleci_workload_identity_provider`
 into the context as `GCP_WIF_PROVIDER_PROD`. The WIF condition requires the
 `terreno-gcp` context UUID so a PR job without that context cannot exchange the
@@ -379,6 +381,17 @@ dependencies and runs `test:ci` when that script exists, not `test`.
 tag version is already on npm, `publish-package.sh` skips it so a recut of
 the same tag can finish the rest.
 
+The release skill pushes the tag and creates the GitHub release with
+`gh release create --draft`. The repository has immutable releases on: a
+published release cannot take new assets (GitHub answers `422`). So CI publishes
+the draft last with `scripts/ci/github-release.sh publish`.
+`archive-docs-version` does it right after the upload on `X.Y.0` tags.
+`publish-github-release` does it after `publish-release` on every other tag.
+Both wait up to 10 minutes for the draft and are safe to rerun: a rerun skips
+an upload that already landed on a published release and a snapshot already on
+master. A
+release still in draft after the pipeline means one of them failed.
+
 Only stable tags (`57.3.0`) run `deploy-demo`. It builds the demo from source,
 so it runs alongside `publish-release` instead of waiting for it. Use
 `{"run-demo-deploy":true}` on `master` if a prerelease must also refresh the

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

@@ -4,6 +4,8 @@ Deploy a Terreno `@terreno/api` backend (for example `example-backend`) to Googl
 
 Replace placeholders: `$PROJECT_ID`, `$REGION`, `$SERVICE_NAME`, `$REPOSITORY`.
 
+Steps 1, 3, and 4 create infrastructure with `gcloud`, which suits a first deploy. For production, create the same resources with Terraform instead — see [Manage with Terraform](#manage-with-terraform).
+
 ## Prerequisites
 
 - [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and authenticated
@@ -97,6 +99,22 @@ curl -s "$SERVICE_URL/health" | jq .
 
 Expect `"healthy": true`.
 
+## Manage with Terraform
+
+The [`terreno-backend` module](https://github.com/TerrenoLabs/terreno/tree/master/terraform/modules/terreno-backend) replaces steps 1, 3, and 4. It creates the Artifact Registry repository, the runtime service account, empty secrets with the names used above, and the Cloud Run service with session affinity, a 3600s timeout, and one minimum instance.
+
+```hcl
+module "backend" {
+  source = "github.com/TerrenoLabs/terreno//terraform/modules/terreno-backend?ref=<release-tag>"
+
+  project_id   = "your-project-id"
+  region       = "us-central1"
+  service_name = "your-service-name"
+}
+```
+
+After `terraform apply`, add a version to **every** secret in the module's `secret_ids` output, including `better-auth-secret` (the module creates it by default; `gcloud run deploy` fails while any mounted secret has no version). Then build, push, and deploy (steps 2 and 5), using the `registry_path`, `service_account_email`, and `set_secrets_flag` outputs. Terraform ignores the image and env vars after creation, so deploys never conflict with `terraform apply`. Set `github_deploy` to add a keyless GitHub Actions deployer through Workload Identity Federation. Leave `--allow-unauthenticated` off in CI deploys: the module already makes the service public, and that flag needs IAM permissions the deployer does not have.
+
 ## Production constraints
 
 | Symptom | Cause | Fix |

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

@@ -18,6 +18,10 @@ Read the [deployment baseline](../explanation/deployment-baseline.md) — seven
 
 [GCP deployment architecture](../explanation/deployment-architecture-gcp.md) — topology diagram, component roles, and tradeoffs (Cloud Run vs GKE, static vs SSR).
 
+## Terraform
+
+- [`terraform/modules/terreno-backend`](https://github.com/TerrenoLabs/terreno/tree/master/terraform/modules/terreno-backend) — Cloud Run, Artifact Registry, secrets, and service accounts for one backend. See [Manage with Terraform](deploy-backend-to-cloud-run.md#manage-with-terraform).
+
 ## Scripts
 
 - [`scripts/setup-gcs-hosting.sh`](https://github.com/TerrenoLabs/terreno/blob/master/scripts/setup-gcs-hosting.sh) — parameterized GCS + CDN provisioning for one site
@@ -28,7 +32,7 @@ Read the [deployment baseline](../explanation/deployment-baseline.md) — seven
 
 ## Operator-specific deployment
 
-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.
+Vendor-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives outside these generalized guides. Terreno's own deployment of its example backend and hosted MCP server is in [`infra/flourish/`](https://github.com/TerrenoLabs/terreno/tree/master/infra/flourish) and is not a template. New deployments should follow the guides above with your own `$PROJECT_ID` and bucket names.
 
 ## Related
 

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

@@ -1,6 +1,6 @@
 # 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.
+Routine version upgrades run through the `update-dependencies` skill (`/update-dependencies`). Dependabot opens **security PRs only**. The skill keeps one rolling PR; later runs push to it and rewrite its ledger instead of opening new PRs.
 
 ```bash
 REPOSITORY="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"
@@ -19,7 +19,7 @@ gh pr list --state open --head chore/update-dependencies \
 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.
+Prove each bump with an **exercise test** that imports that package. Verify the whole batch locally, then push **once**. 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`.
 
@@ -27,9 +27,10 @@ Why: [Dependency management](../explanation/dependency-management.md). Native Ex
 
 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.
+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. Commit each success as `Bump <name> from <old> to <new>`.
+4. Run the batch gate on the final head: `bun run compile`, `bun run lint`, `bun run prepush`. Run by hand any infra job `prepush` lists for a package you bumped (Playwright, Maestro, admin-spa integration). See [Run tests locally](run-tests-locally.md).
+5. Push once. Update the **same** PR body: Last run, local gate result, CI rounds, Landed, Failed, Skipped, Deferred to release. Do not `gh pr create` when that PR is already open.
+6. Read CI on the pushed head. Check each failed CircleCI job's `messages` before its step logs. Revert a bump that caused a failure and push a second time at most; stop and report anything else.
 
 ## Guardrails
 
@@ -41,7 +42,11 @@ Why: [Dependency management](../explanation/dependency-management.md). Native Ex
 | 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 |
+| Local gate red | Fix or revert before pushing. CI is not the test runner |
+| CI job has `messages` (for example `resource-class-not-in-plan`) | Config/plan error, not a dependency failure. Log it and stop |
+| A bump seems to need CI config changes | Never edit `.circleci/`, workflows, executors, or resource classes from this path. Stop and report |
+| CI red twice on heads this run pushed | Stop and report; do not push a third time |
+| Dependabot security PR is red | Do not push to `dependabot/*`. Fold the bump into the rolling PR |
 
 ## Fingerprints
 
@@ -49,6 +54,10 @@ Why: [Dependency management](../explanation/dependency-management.md). Native Ex
 
 `eas.json` Bun pins feed the fingerprint. Do not bump them here.
 
-## Dependabot still runs
+## Who CI emails
 
-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.
+CircleCI attributes a pipeline to the GitHub user whose token pushed it and emails that user on each failed workflow. Run the scheduled agent with a bot identity when one is configured. If it runs as a person, the one-push rule caps their mail at one round per run.
+
+## Dependabot security PRs
+
+`.github/dependabot.yml` sets `open-pull-requests-limit: 0` on every block, so Dependabot opens no version-update PRs. Security updates still open, grouped per block, and skip ignored native/Expo names. `dependabot-auto-merge.yml` approves them and enables squash auto-merge, so a green security PR merges without this skill. A red one gets its bump folded into the rolling PR. A security fix for an ignored native package is a manual release task (`release` + `upgrading-expo`).

package/dist/docs/versioned/next/how-to/use-syncdb-correctly.md

@@ -6,18 +6,18 @@ Read [Local-first data](../explanation/local-first-data.md) and [Migrate from @t
 
 ## Startup and snapshots
 
-### Cold start costs one round trip per stream
+### Cold start costs one round trip per round, not per stream
 
-A stream is one collection in one scope, so a user has roughly (synced collections) × (tenants they belong to) streams. Each stream costs at least one `GET /sync/snapshot` round trip, even when it is empty. Reconcile, subscribe catch-up, `forceResync` and wipe re-bootstrap page up to `snapshotConcurrency` streams side by side (default 6). Each stream runs one pass at a time, and a pass that purges (force resync, wipe) waits for the stream's in-flight pass to finish first.
+A stream is one collection in one scope, so a user has roughly (synced collections) × (tenants they belong to) streams. Reconcile, subscribe catch-up and wipe re-bootstrap page every stream through `POST /sync/snapshot/batch`: one round trip per round, with up to 5,000 rows per response shared across the streams. Empty streams cost nothing extra. `forceResync`, and every pass against a server without the batch route, still page with one `GET /sync/snapshot` per stream, `snapshotConcurrency` streams side by side (default 6). Each stream runs one pass at a time, and a pass that purges (force resync, wipe) waits for the stream's in-flight pass to finish first.
 
-Measured with a fake HTTP channel at 150 ms latency, 13 collections and 2 workspaces (26 streams): 4.1 s to the first full reconcile when paging one stream at a time, 0.95 s at the default concurrency.
+Measured with a fake HTTP channel at 150 ms latency, 13 collections and 2 workspaces (26 streams): 4.1 s to the first full reconcile when paging one stream at a time, 0.95 s at the default concurrency. In a browser with 100 collections and 10k rows, batching cut a reconnect with no changes from 101 requests to 2.
 
 | Do | Why |
 | --- | --- |
 | Sync only the collections the client reads. | Each collection adds one stream per tenant to cold start. |
 | Gate each screen on its **own** stream's bootstrap (see [No loading flag on synced reads](#no-loading-flag-on-synced-reads)), not on "sync finished". | The stream a screen needs may land after others. |
 | Don't call `forceResync()` on a hot path. | It purges and re-pages every stream. |
-| Raise `snapshotConcurrency` only if the backend can take it. | Each in-flight stream is one concurrent snapshot query on the server. |
+| Raise `snapshotConcurrency` only if the backend can take it. | Without the batch route, each in-flight stream is one concurrent snapshot query on the server. |
 
 The startup reconcile and each collection's `sync:subscribed` catch-up both page the same streams. A catch-up queues behind a pass that started before the room join, because that pass may have missed a write. So a cold start still pages each stream twice, one pass after the other.
 

package/dist/docs/versioned/next/implementationPlans/deploy-to-gcp.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Deploy to GCP (Generalized) + `deploy-gcp` Skill
 
-**Status:** Approved — decisions recorded (2026-07-29)
+**Status:** In progress — Phases 1–4 done; Phase 5 (live validation) deferred per GC8
 **Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1005
 **Priority:** High
 **Effort:** Big batch
@@ -34,6 +34,8 @@ Turn Terreno's GCP deployment story from "how Flourish deploys Terreno" into "ho
 | GC5 | Flourish infra location (→ P5) | **C** — `infra/flourish/` now; **migrate to B** (private repo) post-launch |
 | GC6 | `deploy-gcp` skill deploys? | **C** — full deploy behind explicit confirmation gate |
 | GC7 | Secret management | **A** — Secret Manager for secrets; plain env for non-secrets |
+| GC8 | Live scratch-project validation (Tasks 4.1, 4.2) — run now or later? (asked 2026-10-12) | **Later** — ship Tasks 2.1–2.2 first; run 4.1/4.2 in a session with GCP access and a scratch project. Acceptance criteria 4 (module applies to a scratch project) and 8 (full deploy) stay open until then; the module is proven by mocked-provider tests only |
+| GC9 | How does `infra/flourish/` reach the shared modules? | **Stopgap:** an `infra/flourish/modules` symlink to `../../terraform/modules`; CI stages a dereferenced copy because Infra Manager uploads only `--local-source`. When GC5 moves `infra/flourish/` to a private repo, switch module sources to a pinned git source and drop the staging step |
 
 ## Architecture
 
@@ -137,7 +139,9 @@ No product flags. Moving `terraform/` to `infra/flourish/` breaks paths referenc
 - `docs/how-to/deploy-backend-to-cloud-run.md`
 - `docs/how-to/deploy-web-to-gcs-cdn.md`
 - `docs/explanation/deployment-architecture-gcp.md`
-- `terraform/modules/terreno-backend/{main.tf,variables.tf,outputs.tf,README.md}`
+- `terraform/modules/terreno-backend/{main.tf,variables.tf,outputs.tf,versions.tf,README.md}` and `tests/terreno_backend.tftest.hcl`
+- `infra/flourish/**` (moved from `terraform/`, plus the `modules` symlink and README)
+- `terraform/README.md` (generic module index)
 - `.rulesync/skills/deploy-gcp/SKILL.md`
 - `.rulesync/skills/deploy-gcp/references/troubleshooting.md`
 
@@ -146,7 +150,8 @@ No product flags. Moving `terraform/` to `infra/flourish/` breaks paths referenc
 - `docs/how-to/deploy-to-gcp.md` (becomes an index pointing at the two new guides, or is deleted with redirects)
 - `docs/how-to/README.md`
 - `scripts/setup-gcs-hosting.sh` (parameterize)
-- `terraform/README.md` (split generic vs Flourish)
+- `terraform/modules/{cloud_run_service,secret,artifact_registry}` (`session_affinity` input; test-only outputs `runtime_settings`, `accessors`, `writers`)
+- `.circleci/config.yml`, `.circleci/continue-config.yml`, `scripts/ci/gcp-deploy.sh` (infra/ path filter, fmt, module tests, Infra Manager staging)
 - `.github/workflows/cd.yml`, `.github/workflows/demo-deploy.yml`, `.github/workflows/frontend-example-deploy.yml` (path updates if terraform moves)
 - `example-backend/Dockerfile` (created by [`deployment-foundation`](deployment-foundation.md); referenced here)
 
@@ -156,12 +161,12 @@ See [`docs/tasks/deploy-to-gcp.md`](../tasks/deploy-to-gcp.md).
 
 ## Acceptance Criteria
 
-- [ ] `docs/how-to/deploy-backend-to-cloud-run.md` contains no `flourish` string and no hardcoded project ID, bucket name, or service URL.
-- [ ] The backend guide documents session affinity, request timeout, min-instances, and the replica-set requirement, each with the symptom that occurs when it is missed.
-- [ ] The web guide covers `expo export -p web`, bucket configuration with `notFoundPage=index.html`, CDN setup, cache invalidation, and setting `EXPO_PUBLIC_API_URL` at build time.
+- [x] `docs/how-to/deploy-backend-to-cloud-run.md` contains no `flourish` string and no hardcoded project ID, bucket name, or service URL.
+- [x] The backend guide documents session affinity, request timeout, min-instances, and the replica-set requirement, each with the symptom that occurs when it is missed.
+- [x] The web guide covers `expo export -p web`, bucket configuration with `notFoundPage=index.html`, CDN setup, cache invalidation, and setting `EXPO_PUBLIC_API_URL` at build time.
 - [ ] `terraform/modules/terreno-backend/` applies cleanly against a scratch project with only variables supplied, creating Cloud Run + Artifact Registry + secrets + service accounts.
-- [ ] `scripts/setup-gcs-hosting.sh` accepts project and site names as arguments and contains no Flourish defaults.
-- [ ] The `deploy-gcp` skill exists in `.rulesync/skills/` and all generated mirrors are committed (`bun run rules:check` exits 0).
-- [ ] The skill's plan step prints project, region, and service names and stops for confirmation before any mutating command.
+- [x] `scripts/setup-gcs-hosting.sh` accepts project and site names as arguments and contains no Flourish defaults.
+- [x] The `deploy-gcp` skill exists in `.rulesync/skills/` and all generated mirrors are committed (`bun run rules:check` exits 0).
+- [x] The skill's plan step prints project, region, and service names and stops for confirmation before any mutating command.
 - [ ] A full deploy of `example-backend` + `example-frontend` to a scratch GCP project succeeds following only the public docs, and `curl <backend>/health` returns `"healthy":true`.
-- [ ] All Flourish-specific infrastructure lives under `infra/flourish/` and CI still passes.
+- [x] All Flourish-specific infrastructure lives under `infra/flourish/` and CI still passes.

package/dist/docs/versioned/next/reference/syncdb.md

@@ -70,7 +70,7 @@ Expo autolinking walks the app's own dependencies; a nested copy leaves the nati
        │   sync:mutate ─────────────────────────────►│               │
        │   sync:ack / sync:nack ◄────────────────────┘               │
        │   sync:delta ◄──────────────────────────────────────────────┘
-       │   GET /sync/snapshot (bootstrap + catch-up, HTTP)
+       │   POST /sync/snapshot/batch (bootstrap + catch-up, HTTP)
        └── POST /sync/mutate (fallback while the socket is down)
 ```
 
@@ -185,7 +185,7 @@ be passed to `betterAuthAdapter` directly.
 | `wipeOnSignOut` | `boolean` | `false` | `signOut()` also wipes local data |
 | `batchSize` | `number` | `50` (server caps at 100) | Max mutations per batched drain send |
 | `haltQueueOnConflict` | `boolean` | `false` | `true` = conflict halts entire drain; `false` = per-entity blocking |
-| `snapshotConcurrency` | `number` | `6` | Streams snapshot-paged at once by reconcile, subscribe catch-up, `forceResync` and wipe re-bootstrap. Each stream runs one pass at a time. `1` pages one stream at a time |
+| `snapshotConcurrency` | `number` | `6` | Streams paged at once with `GET /sync/snapshot`: by `forceResync`, and by every other pass against a server without `POST /sync/snapshot/batch`. Each stream runs one pass at a time. `1` pages one stream at a time |
 | `onDecryptFailure` | `() => void` | wipe + re-bootstrap (with `console.warn`) | Override web decrypt-failure recovery |
 | `tombstoneRetentionMs` | `number` | `7776000000` (90 days); `0` disables | Client tombstone compaction after successful reconcile |
 | `startAuthRetryAttempts` | `number` | `3`; `1` disables | `start()` attempts to resolve `getUserId()` |
@@ -202,7 +202,7 @@ be passed to `betterAuthAdapter` directly.
 | `goOffline()` | Simulated outage: disconnect transport, pause replay/reconcile/timer; local mutations keep queueing. |
 | `goOnline()` | End simulated outage; reconnect triggers reconcile + outbox replay. |
 | `mutate({collection, operation, id?, data?})` | Optimistic local write + durable outbox enqueue + fire-and-forget replay. Returns `{mutationId, id}`. |
-| `reconcile()` | HTTP snapshot catch-up for every known stream; runs tombstone compaction on success. Also runs automatically on (re)connect, on a rate-limited seq-jump hint, and on the periodic timer; each `sync:subscribed` confirmation additionally pages just the streams it names. |
+| `reconcile()` | HTTP snapshot catch-up for every known stream, batched into `POST /sync/snapshot/batch` rounds (see [Snapshot bootstrap](#snapshot-bootstrap)); runs tombstone compaction on success. Also runs automatically on (re)connect, on a rate-limited seq-jump hint, and on the periodic timer; `sync:subscribed` confirmations additionally page just the streams they name, and confirmations arriving while that catch-up request is in flight are paged together in the next one. |
 | `hydrateWindow({collection, ids, restRows?})` | Admin window upsert: REST rows (optional) land immediately; every requested id is also fetched from `GET /sync/entities` before this resolves so seq/deleted metadata is canonical for immediate update/delete. A `{collection}|admin` delta that lands while the fetch is in flight wins, so hydration never rewinds a row to an older seq. Unknown ids are ignored. |
 | `queryWindows` | Server query windows for `queryCollections`: `fetchWindow({query, nextPage?})`, `getWindow(query)`, `retain(query)` → release, `refetchRetained()`, `pruneUnretained()`, `subscribe(cb)`, `keyFor(query)`. See [Query windows](#query-windows). |
 | `forceResync()` | Purge every known stream locally and re-bootstrap from cursor 0 (outbox/conflicts untouched). Returns `{ok, reason?, streams, purged, repaired}`. After discovery and each stream bootstrap it waits for in-flight `start`/`stop`/auth-change work, then abandons with `reason: "superseded"` when that work switched users or generations. |
@@ -588,11 +588,36 @@ sync: {
 
 ## Sync protocol
 
+### Snapshot bootstrap
+
+The client pages every stream it belongs to through `POST /sync/snapshot/batch`, not one
+`GET /sync/snapshot` per stream. With 100 collections, a reconnect that finds nothing new
+is 2 requests (`GET /sync/streams` plus one batch) instead of 101.
+
+- **Rounds:** each round asks for every stream that still has pages. Streams that reached
+  their head drop out, so later rounds give the remaining streams a larger share of the
+  5,000-entity budget.
+- **Pipelining:** the next round is sent as soon as a response arrives, because its
+  cursors come from the response. The client writes the current round while the next
+  one downloads.
+- **Chunked apply:** each page is written in store transactions of 500 entities, with a
+  yield to the event loop between them, so a large page never freezes the UI in one block.
+  A stream's cursor advances in the transaction holding its last entity, so a page cut
+  short by a crash is fetched again and re-applied as a no-op.
+- **Older servers:** a 404 without an APIError body (the route does not exist) switches
+  the client to per-stream `GET /sync/snapshot` paging, `snapshotConcurrency` streams at
+  a time, for the rest of the session. An APIError 404, such as an unknown collection,
+  fails that pass and keeps batching on.
+- **One pass per stream:** a batch pass owns each of its streams the way a per-stream
+  pass does, so a purge (`forceResync`, wipe) waits for it, and a pass that is superseded
+  by a sign-out or user switch stops between chunks without writing the rest.
+
 ### HTTP routes (`SyncApp`, all authenticated)
 
 | Endpoint | Purpose |
 |----------|---------|
-| `GET /sync/snapshot?collection=&stream=&cursor=&limit=` | Bootstrap + catch-up per stream |
+| `GET /sync/snapshot?collection=&stream=&cursor=&limit=` | Bootstrap + catch-up for one stream (`limit` max 100) |
+| `POST /sync/snapshot/batch` | Bootstrap + catch-up for many streams in one round trip. Body `{streams: [{stream, cursor?, legacyCursor?}], limit?}`, at most 500 streams, no repeats. `limit` (default 5,000, max 10,000) is the entity budget for the whole response, split evenly across the streams. Returns `{pages}`, one `GET /sync/snapshot`-shaped page per stream in request order. Any stream the caller may not read fails the whole request |
 | `GET /sync/streams` | Current stream membership for the user |
 | `GET /sync/entities` | Point lookup for entity repair and admin window hydrate. Admin-window callers (`admin:access` with RBAC, else `user.admin`) on `adminBroadcast` collections receive requested ids across product streams. When AdminApp registered a scope, list/read/`queryFilter` still apply; unknown or out-of-scope ids are omitted |
 | `POST /sync/mutate` | Single mutation (HTTP fallback). Optional `mutationMode: "adminWindow"` validates `adminBroadcast`, admin-window access, and a registered AdminApp write scope, then runs the shared sync executor with **AdminApp** pre/post hooks (not product `modelRouter` hooks), plus the same permission (including org membership), stripping, and audit semantics as `/admin` REST. HTTP mutate binds `X-Organization-Id` into org context |
@@ -636,6 +661,11 @@ const syncDb = createSyncDb({
 });
 ```
 
+Saves are debounced (500 ms). The store is serialized once per write, not once per
+transaction: autosave compares TinyBase's content hashes (O(1)) to skip saves the last
+write already covered, so a bootstrap of many pages costs a few writes instead of one
+full-store serialization per page.
+
 Undecryptable persisted data triggers wipe + re-bootstrap by default (`onDecryptFailure` to override). Storage read errors surface `persistence: "error"` without overwriting the blob.
 
 **Native:** plaintext SQLite in the OS sandbox (by design).

package/dist/docs/versioned/next/tasks/deploy-to-gcp.md

@@ -46,13 +46,14 @@ See: [`docs/implementationPlans/deploy-to-gcp.md`](../implementationPlans/deploy
 
 ## Phase 2: Terraform module and Flourish separation
 
-- [ ] **Task 2.1**: Extract the generic backend module
+- [x] **Task 2.1**: Extract the generic backend module
   - Description: Create `terraform/modules/terreno-backend/` with `main.tf`, `variables.tf`, `outputs.tf`, and `README.md`. Resources: Artifact Registry repository, Cloud Run v2 service (session affinity, timeout, min/max instances, secret env refs), Secret Manager secrets (created empty, values supplied out-of-band), runtime service account with `secretmanager.secretAccessor` and object admin on a supplied uploads bucket, and optional Workload Identity Federation pool for CI. Every value that could differ between users must be a variable with a description and no Flourish default. Outputs: service URL, service account email, registry path.
   - Files: `terraform/modules/terreno-backend/main.tf`, `variables.tf`, `outputs.tf`, `README.md` (all new)
   - Depends on: Task 1.1
   - Acceptance: `terraform init && terraform validate` passes in the module directory; `rg -i flourish terraform/modules/` returns nothing; every variable has a `description`.
+  - Implementation note: secrets start empty, and Cloud Run rejects a revision that references a versionless secret, so the module does not mount secret env refs at creation. The `set_secrets_flag` output supplies the `--set-secrets` flag for the first real `gcloud run deploy`, consistent with the existing "Terraform owns structure, deploy owns payload" split (`lifecycle.ignore_changes` on env).
 
-- [ ] **Task 2.2**: Relocate Flourish-specific terraform
+- [x] **Task 2.2**: Relocate Flourish-specific terraform
   - Description: Move Flourish's environment configuration from `terraform/` to `infra/flourish/`, leaving only `terraform/modules/` behind. Update every path reference: `.github/workflows/cd.yml`, `terraform/README.md` (split into a generic module README and `infra/flourish/README.md`), `AGENTS.md` / `CLAUDE.md` if they reference `terraform/README.md`, and any script under `scripts/`. Use `git mv` so history is preserved.
   - Files: `infra/flourish/**` (moved), `terraform/README.md`, `.github/workflows/cd.yml`, `AGENTS.md`, `CLAUDE.md`, `scripts/**`
   - Depends on: Task 2.1

package/package.json

@@ -11,8 +11,8 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "57.14.0",
-    "@terreno/blocks": "57.14.0",
+    "@terreno/api": "57.16.1",
+    "@terreno/blocks": "57.16.1",
     "express": "^5.2.1",
     "luxon": "^3.7.2",
     "minisearch": "^7.2.0",
@@ -105,5 +105,5 @@
     "test:coverage": "bun run ../scripts/check-coverage.ts"
   },
   "type": "module",
-  "version": "57.14.0"
+  "version": "57.16.1"
 }

package/src/docs/upgrades/57.15.0.md

@@ -0,0 +1,44 @@
+# Upgrading to 57.15.0
+
+**Action required:** No
+**Affected packages:** @terreno/api, @terreno/syncdb
+
+## Summary
+
+SyncDB pages every stream through one `POST /sync/snapshot/batch` request per round instead of
+one `GET /sync/snapshot` per stream. With many synced collections, cold start is faster and a
+reconnect with no changes costs 2 requests (`GET /sync/streams` plus one batch) whatever the
+collection count. The web IndexedDB persister now serializes the store once per write instead of
+once per transaction, so bootstrap no longer leaves a long save backlog.
+
+## Breaking changes
+
+None
+
+## Deprecations
+
+None
+
+## New capabilities
+
+### `POST /sync/snapshot/batch`
+
+`SyncApp` mounts the route automatically. The body is
+`{streams: [{stream, cursor?, legacyCursor?}], limit?}`, with at most 500 streams.
+`limit` is the row budget for the whole response (default 5,000, max 10,000). The response is
+`{pages}`, one `GET /sync/snapshot`-shaped page per stream. `GET /sync/snapshot` is unchanged.
+
+Upgrade `@terreno/api` and `@terreno/syncdb` together for the speedup. A 57.15.0 client talking
+to an older server sees a 404 from the batch route and falls back to per-stream paging
+(`snapshotConcurrency` streams at a time). An older client keeps using `GET /sync/snapshot`.
+
+### `snapshotConcurrency` scope
+
+`createSyncDb({snapshotConcurrency})` now applies only to per-stream paging: `forceResync()` and
+the fallback against servers without the batch route.
+
+## Verification
+
+- `bun run compile` and `bun run lint` at the app root
+- After deploying the backend, open the web app with dev tools and confirm a reconnect sends one
+  `POST /sync/snapshot/batch` instead of one `GET /sync/snapshot` per collection

package/src/docs/upgrades/57.16.1.md

@@ -0,0 +1,33 @@
+# Upgrading to 57.16.1
+
+**Action required:** No
+**Affected packages:** @terreno/ui
+
+## Summary
+
+This release keeps rapid typo corrections in web `TextField` and `TextArea` inputs, and adds a
+reusable Terraform module for deploying Terreno backends to Cloud Run. Terreno's own infrastructure
+also moves under `infra/flourish/` without changing deployed resource addresses.
+
+## Breaking changes
+
+None
+
+## Deprecations
+
+None
+
+## New capabilities
+
+### Reusable Cloud Run backend module
+
+`terraform/modules/terreno-backend` provisions the Artifact Registry repository, runtime service
+account, Secret Manager placeholders, and websocket-safe Cloud Run service for a Terreno backend.
+Set `github_deploy` to add a keyless GitHub Actions deployer.
+
+## Verification
+
+- `bun run compile` and `bun run lint` at the app root
+- On web, type a character into a `TextField`, immediately backspace it, and confirm it stays deleted
+- Follow the Terraform example in `docs/how-to/deploy-backend-to-cloud-run.md` and run
+  `terraform validate`

package/src/docs/versioned/57.15.0/README.md

@@ -0,0 +1,72 @@
+# Terreno Documentation
+
+**Terreno is Django/Rails for TypeScript — with universal app support.**
+
+Terreno is Django/Rails for TypeScript — a batteries-included, full-stack
+framework where the undifferentiated 80% of an app is already written. On the
+backend you get Mongoose models, auto-generated REST APIs, permissions, an admin
+panel, authentication, and an AI service. On the frontend you get one universal
+app — a single React Native codebase that ships to iOS, Android, and web. It is
+built to be driven by AI coding agents from the first prompt to a production
+deploy.
+
+- Batteries included — auth, CRUD APIs, admin, permissions, AI, realtime,
+  feature flags, and consent are already built, so your code is business logic.
+- Universal by default — one React Native codebase ships to iOS, Android, and
+  web. Not a web framework with a mobile bolt-on.
+- AI-native — agents are a first-class client of the framework, not an
+  afterthought.
+
+Canonical copy, language rules, and the Django/Rails comparison:
+[Positioning](explanation/positioning.md).
+
+## Structure
+
+- **[Tutorials](tutorials/)** — Learning-oriented, hands-on lessons
+- **[How-to guides](how-to/)** — Problem-oriented, practical steps
+- **[Reference](reference/)** — Technical reference for APIs and packages
+- **[Explanation](explanation/)** — Concepts and context
+- **[Implementation Plans](implementationPlans/)** — Forward-looking plans for major features
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| [@terreno/api](reference/api.md) | REST API framework for Express/Mongoose (modelRouter, auth, OpenAPI) |
+| [@terreno/test](reference/test.md) | Shared Bun test helpers, MongoDB preload utilities, and HTTP fixtures |
+| [@terreno/ui](reference/ui.md) | React Native UI component library for iOS, Android, and web |
+| [@terreno/syncdb](reference/syncdb.md) | Local-first data layer with TinyBase, durable outbox, and delta sync |
+| [@terreno/ai](reference/ai.md) | Provider-agnostic AI service with streaming chat, request logging, and admin tools |
+| [@terreno/blocks](reference/blocks.md) | Shared contracts for agent-driven UI: ask schemas and whole-reply block documents |
+| [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin for `@terreno/api` |
+| [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens for `@terreno/api` backends |
+| [@terreno/admin-spa](reference/admin-spa.md) | Standalone admin SPA (Expo Router web) plus Express serve plugin |
+| [@terreno/api-health](reference/api-health.md) | Health check plugin for `@terreno/api` |
+| [@terreno/announcements](reference/announcements.md) | In-app product update announcements |
+| [@terreno/comms](reference/comms.md) | Pluggable communications providers |
+| [@terreno/feature-flags](reference/feature-flags.md) | Feature flags and A/B testing plugin for `@terreno/api` |
+| [@terreno/mcp](reference/mcp-server.md) | MCP server that gives coding agents Terreno docs, codegen tools, and prompts |
+| [@terreno/cli](reference/cli.md) | `terreno` CLI for docs, codegen, bootstrap, and OpenAPI REST |
+| [create-terreno-app](reference/create-terreno-app.md) | CLI to scaffold a deployable full-stack Terreno app (`bunx create-terreno-app`) |
+
+### Legacy
+
+| Package | Description |
+|---------|-------------|
+| [@terreno/rtk](reference/legacy/rtk.md) (deprecated for data sync) | OpenAPI SDK, Better Auth Redux, and feature flags for Terreno frontends |
+
+**Migrating from RTK?** See [How to migrate from @terreno/rtk to @terreno/syncdb](how-to/migrate-rtk-to-syncdb.md).
+
+## Quick links
+
+- [Getting started](tutorials/getting-started.md)
+- [Set up Terreno MCP](how-to/set-up-terreno-mcp.md)
+- [Debug with MCP](how-to/debug-with-mcp.md)
+- [Create a Terreno app](how-to/create-a-terreno-app.md)
+- [Positioning](explanation/positioning.md)
+- [How admin interfaces are shaped](explanation/admin-interface.md)
+- [Build admin screens](how-to/build-admin-screens.md)
+- [Local-first data](explanation/local-first-data.md)
+- [AGENTS.md](../AGENTS.md) — Onboarding context for AI assistants
+- [ROADMAP.md](../ROADMAP.md) — Public roadmap
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — Setup, tests, and pull requests

package/src/docs/versioned/57.15.0/explanation/README.md

@@ -0,0 +1,41 @@
+# Explanation
+
+Understanding-oriented documentation: concepts, architecture, and context.
+
+## Deployment
+
+- [Deployment baseline](deployment-baseline.md) — seven requirements for production Terreno apps
+- [GCP deployment architecture](deployment-architecture-gcp.md) — Cloud Run + GCS/CDN topology and tradeoffs
+- [GCP hosting architecture](gcp-hosting-architecture.md) — static site hosting with GCS and Cloud CDN (legacy detail)
+
+## Contents
+
+- [Local-first data](local-first-data.md) — Why the local store is the UI source of truth
+- [Planning plugins](planning-plugins.md) — How the lifecycle and scan plugins divide discovery from delivery
+- [Loop engineering](loop-engineering.md) — Fresh-invocation lifecycle, state, evidence, and orchestration boundaries
+- [GitHub issue lifecycle](../how-to/github-issue-lifecycle.md) — Pick-ready issues and plan comments for Pick/Roast
+- [Install agent skills](../how-to/install-agent-skills.md) — `npx skills add TerrenoLabs/terreno`
+- [AI observability](ai-observability.md) — Two planes (telemetry vs control), plugins vs LangfuseApp, SOP loop
+- [Durable agent harness](durable-agent-harness.md) — Phases, checkpoints, and why the audit span shares the checkpoint transaction
+- [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
+- [Agent UI Asks](agent-ui-asks.md) — Why agent questions are client-side tool calls, the pause and resume round trip, why cards carry exact answers, the watch paths, asks vs blocks
+- [Agent UI blocks](agent-ui-blocks.md) — Why chat replies use a closed YAML catalog instead of free-form UI, why steppers and checklists call the server, and the rich-blocks rollout
+- [Authentication architecture](authentication.md) — Better Auth, JWT, and optional MCP service tokens
+- [Organization tenancy](organizations.md) — Optional Membership-backed tenancy, context, and isolation boundaries
+- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
+- [Dependency management](dependency-management.md) — Catalog pins, exercise tests, fingerprint freeze
+- [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
+- [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter
+- [Explicit `any` policy](explicit-any-policy.md) — Require rationale markers and ratchet usage per file
+- [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels
+- [TypeScript configuration](typescript-configuration.md) — tsconfig profiles for Node, frontend, Expo, and Bun workspaces on TypeScript 6
+- [Production source rules](source-rules.md) — Arrow functions, Luxon, APIError, logging, findOne, `as any`
+- [Positioning](positioning.md) — Canonical copy blocks and the honest Django/Rails comparison
+- [Versioning policy](versioning-policy.md) — Lockstep `@terreno/*` versions, pre-1.0 breaks, deprecation window
+- [How admin interfaces are shaped](admin-interface.md) — Screens, sidebar, `apiBase` vs `routeBase`
+- [Admin plugin frontend widgets](admin-plugin-frontend.md) — Widget IDs from backend plugins
+- [Consent admin migration](admin-consent-migration.md) — Which consent screens stay hand-written
+- [Public roadmap process](roadmap-process.md) — GitHub roadmap vs Linear execution
+- [Example app coverage](example-coverage.md) — Which framework capabilities the example apps exercise
+- [Repository settings](repository-settings.md) — Maintainer GitHub settings that cannot be committed
+- [Why Terreno owns chart SVG](charts.md) — Owned `react-native-svg` vs victory-native

package/src/docs/versioned/57.15.0/explanation/admin-consent-migration.md

@@ -0,0 +1,15 @@
+# Consent admin migration audit
+
+The example keeps specialized consent routes where generic model screens do not cover the workflow.
+
+| Route file | Disposition | Reason |
+| --- | --- | --- |
+| `consent-forms/index.tsx` | Keep as a hand-written route | Adds consent-specific list navigation and publishing workflow. |
+| `consent-forms/create.tsx` | Keep as a hand-written route | Uses `ConsentFormEditor` for localized content, AI generation, and consent validation. |
+| `consent-forms/[id].tsx` | Keep as a hand-written route | Supports publish/version behavior beyond generic CRUD editing. |
+| `consent-responses/index.tsx` | Keep as a hand-written route | Presents consent-response-specific navigation. |
+| `consent-responses/[id].tsx` | Keep as a hand-written route | Uses `ConsentResponseViewer` for signatures, snapshots, and audit details. |
+
+`ConsentApp.adminContribution()` still contributes generic ConsentForm and ConsentResponse models.
+Those models provide searchable tables and field widgets, while Expo Router gives the explicit
+routes above precedence for the richer consent workflows.