@terreno/mcp 57.14.0 → 57.16.1

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/dist/docs/versioned/0.29.0/README.md

@@ -1,29 +0,0 @@
-# Terreno Documentation
-
-Documentation for the Terreno monorepo: shared packages for full-stack applications with React Native and Express/Mongoose.
-
-## 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 (Express/Mongoose) |
-| [@terreno/ui](reference/ui.md) | React Native UI component library |
-| [@terreno/rtk](reference/rtk.md) | RTK Query utilities for API backends |
-| [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin |
-| [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens |
-| [@terreno/api-health](reference/api-health.md) | Health check endpoint plugin |
-| [@terreno/mcp](reference/mcp-server.md) | AI coding assistant integration (MCP) |
-
-## Quick links
-
-- [Getting started](tutorials/getting-started.md)
-- [AGENTS.md](../AGENTS.md) — Onboarding context for AI assistants
-- [.cursorrules](../.cursorrules) — Project and code style rules

package/dist/docs/versioned/0.29.0/explanation/README.md

@@ -1,14 +0,0 @@
-# Explanation
-
-Understanding-oriented documentation: concepts, architecture, and context.
-
-## Contents
-
-- [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
-- [Authentication architecture](authentication.md) — How JWT, OAuth, and token refresh work
-- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
-- [Dependency management](dependency-management.md) — Dependabot, auto-merge, and security practices
-- [GCP hosting architecture](gcp-hosting-architecture.md) — Static site hosting with GCS and Cloud CDN
-- [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
-- [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter
-- [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels