@terreno/mcp 57.13.0 → 57.15.0

package/dist/docs/upgrades/57.14.0.md

@@ -0,0 +1,43 @@
+# Upgrading to 57.14.0
+
+**Action required:** No
+**Affected packages:** @terreno/syncdb
+
+## Summary
+
+`@terreno/syncdb` pages snapshot streams in parallel (up to 6 at once by default) instead of one at a time, so cold start, reconcile, subscribe catch-up, `forceResync`, and wipe re-bootstrap finish faster when an app has many collections or scopes. Each stream now runs one snapshot pass at a time, which stops a concurrent pass from marking a purged stream bootstrapped over rows it never paged. No code change is required.
+
+## Breaking changes
+
+None
+
+## Deprecations
+
+None
+
+## New capabilities
+
+### `snapshotConcurrency` on `createSyncDb`
+
+The client now sends up to `snapshotConcurrency` snapshot requests at once (default `DEFAULT_SNAPSHOT_CONCURRENCY`, 6). If your backend cannot take the extra parallel load at cold start, lower it. `1` restores the old one-stream-at-a-time behavior.
+
+```typescript
+// Before
+export const syncDb = createSyncDb({authProvider, baseUrl, collections, name: "my-app"});
+
+// After (only if you need to limit parallel snapshot requests)
+export const syncDb = createSyncDb({
+  authProvider,
+  baseUrl,
+  collections,
+  name: "my-app",
+  snapshotConcurrency: 2,
+});
+```
+
+A new how-to, `docs/how-to/use-syncdb-correctly.md`, lists library behavior apps have to handle.
+
+## Verification
+
+- `bun run compile` and `bun run lint` at the app root
+- Log in on a fresh device or after `wipeLocalData`; synced screens load, and the backend logs show several `/sync/snapshot` requests in flight together

package/dist/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/dist/docs/versioned/next/explanation/ai-workflows.md

@@ -159,13 +159,13 @@ Ensures preview environments don't accumulate and waste resources.
 
 #### Dependabot Auto-merge
 **Trigger:** Dependabot pull request opened  
-**Purpose:** Automatically merges dependency updates after CI passes
+**Purpose:** Automatically merges Dependabot security updates after CI passes. Dependabot opens no version-update PRs; routine upgrades run through the `update-dependencies` skill.
 
 **Requirements for auto-merge:**
 - All CI checks pass
 - Dependabot PR (created by Dependabot)
+- Not a semver-major bump (for a grouped PR, no bump in the group is major); majors wait for a human review
 - No conflicts
-- 7-day cooldown for security (see Dependency Management)
 
 **Learn more:** [Dependency Management](dependency-management.md)
 
@@ -208,7 +208,7 @@ Ensures preview environments don't accumulate and waste resources.
 ### Continuous Sync
 - Documentation syncs on every master push
 - Rules sync on every master push
-- Dependencies update daily (Dependabot)
+- Dependencies update daily (`update-dependencies` skill); Dependabot opens security fixes only
 - Quality improvements run daily (JSDoc, tests)
 
 ## Working with AI Workflows
@@ -280,8 +280,8 @@ The docs-audit workflow flags a missing README or reference page and obvious int
 
 ### Dependabot PR doesn't auto-merge
 - Verify all CI checks pass (green checkmarks)
-- Check 7-day cooldown hasn't been violated
 - Ensure no merge conflicts exist
+- If the security fix needs code changes, fold it into the rolling `chore/update-dependencies` PR instead of pushing to the Dependabot branch
 
 ### AI workflow creates poor quality PR
 - Review the workflow definition in `.github/workflows/*.md`
@@ -290,7 +290,7 @@ The docs-audit workflow flags a missing README or reference page and obvious int
 
 ## Related Documentation
 
-- [Dependency Management](dependency-management.md) — Dependabot configuration and auto-merge
+- [Dependency Management](dependency-management.md) — Dependabot security-only configuration, auto-merge, and the update skill
 - [Deploy to GCP](../how-to/deploy-to-gcp.md) — Manual deployment guide
 - [GCP Hosting Architecture](gcp-hosting-architecture.md) — Static site hosting design
 - [Environment Variables](../reference/environment-variables.md) — Configuration reference

package/dist/docs/versioned/next/explanation/dependency-management.md

@@ -1,16 +1,16 @@
 # Dependency Management
 
-Terreno pins shared versions in the Bun catalog, lands JavaScript updates through
-an agent skill that proves each bump with a test, and keeps Expo native
-fingerprints frozen until a release.
+Terreno pins shared versions in the Bun catalog, lands routine JavaScript updates
+through an agent skill that proves each bump with a test, limits Dependabot to
+security fixes, and keeps Expo native fingerprints frozen until a release.
 
 ## Layers
 
 | Layer | Job |
 | --- | --- |
 | **Bun catalog** | One version for every dependency shared by two or more workspace packages (`catalog:` in manifests) |
-| **`update-dependencies` skill** | Daily rolling PR on `chore/update-dependencies`: cooldown, exercise test, fingerprint freeze, ledger of landed/failed |
-| **Dependabot** | Backup signal for bun + GitHub Actions. Native/Expo catalog names are ignored so auto-merge cannot change the fingerprint |
+| **`update-dependencies` skill** | The only path for routine version upgrades. Daily rolling PR on `chore/update-dependencies`: cooldown, exercise test, local gate, one push per run, fingerprint freeze, ledger of landed/failed |
+| **Dependabot** | Security updates only for bun + GitHub Actions. Native/Expo catalog names are ignored so auto-merge cannot change the fingerprint |
 | **Release + `upgrading-expo`** | Expo SDK, React Native, and other native-module bumps |
 
 Operator steps: [Update dependencies](../how-to/update-dependencies.md). Catalog rule: workspace `package.json` files use `"catalog:"` for shared pins.
@@ -41,16 +41,18 @@ Change a shared version in the catalog once. Do not pin a second copy in a works
 
 ## Agent updates vs Dependabot
 
-Dependabot groups many packages and merges when CI is green. That misses two Terreno constraints:
+Dependabot version updates group many packages and merge when CI is green. That misses Terreno constraints, so Dependabot now opens security PRs only:
 
 1. **Exercise.** CI can pass without any test importing the bumped module. The skill requires a named test file that imports the package and that passed **after** the bump. If none exists, write a tracer-bullet test first.
 2. **Fingerprint.** Expo `runtimeVersion.policy: "fingerprint"` ties OTA runtime and EAS dev builds to native hashes of `example-frontend` and `demo`. Native module bumps belong in a release, not a weekday dependency PR.
 
+3. **CI is not the test runner.** A red grouped Dependabot PR invites an agent to push fix after fix to the Dependabot branch. Each push starts a full CircleCI pipeline that is attributed to, and emails, whoever owns the pushing token. The skill runs the CI mirror (`bun run prepush`) locally, pushes once per run, never edits CI config to make a bump pass, and stops after two red CI rounds.
+
 `scripts/planning/fingerprintRisk.ts` (`isFingerprintSkip`) is the skip matcher. After every allowed bump the skill still recomputes hashes; a changed hash is reverted even if the matcher allowed the name.
 
 ## Cooldown
 
-Non-security npm versions wait **7 days** after publish before a bump (`npm view <name> time`). Most malicious publishes are yanked inside a day. GitHub Dependabot uses the same `cooldown.default-days: 7`. CVE/advisory bumps skip the wait and still need an exercise test and a fingerprint freeze.
+Non-security npm versions wait **7 days** after publish before a bump (`npm view <name> time`). Most malicious publishes are yanked inside a day. CVE/advisory bumps skip the wait and still need an exercise test and a fingerprint freeze. Dependabot security updates are advisory bumps, so they have no cooldown.
 
 ## Fingerprint freeze
 
@@ -67,16 +69,16 @@ JavaScript packages, GitHub Actions, and a few Expo JS-only names may update. Me
 
 ## Dependabot configuration
 
-`.github/dependabot.yml` still opens grouped PRs:
+`.github/dependabot.yml` sets `open-pull-requests-limit: 0` on every block. That turns off version-update PRs; security updates ignore the limit and still honor `ignore`. Each block's group uses `applies-to: security-updates`, so fixes arrive grouped:
 
-| Group | Ecosystem | Schedule |
-| --- | --- | --- |
-| GitHub Actions | `github-actions` at `/` | Weekly |
-| Root catalog and root tools | `bun` at `/` | Monthly |
-| Backend workspaces | `bun` under api, ai, backends, … | Monthly |
-| Frontend workspaces | `bun` under ui, rtk, demo, apps, … | Monthly |
+| Group | Ecosystem |
+| --- | --- |
+| `github-actions` | `github-actions` at `/` |
+| `root` | `bun` at `/` (root catalog and root tools) |
+| `backend` | `bun` under api, ai, backends, … |
+| `frontend` | `bun` under ui, rtk, demo, apps, … |
 
-Frontend ignores catalog-managed names so those PRs do not duplicate the root catalog. Root ignores fingerprint-skip names. `dependabot-auto-merge.yml` still squash-merges Dependabot PRs when required checks pass. Do not merge a Dependabot PR that includes a skip-list package; redo it with [Update dependencies](../how-to/update-dependencies.md).
+Frontend ignores catalog-managed names so those fixes land once, in the root catalog. Root ignores fingerprint-skip names, so a security fix for a native/Expo package never opens a PR; handle it by hand in a release. `dependabot-auto-merge.yml` approves patch and minor Dependabot PRs and enables squash auto-merge, so those security PRs merge when required checks pass. A semver-major security PR (or a group containing one) gets no approval or auto-merge and waits for a human. When one fails because the fix needs code changes, fold the bump into the rolling PR ([Update dependencies](../how-to/update-dependencies.md)); never push to the `dependabot/*` branch.
 
 ## Daily rolling PR
 
@@ -91,10 +93,12 @@ Each package is still proven alone (exercise test + fingerprint) before it stays
 - One rolling PR; many proven commits on that branch.
 - Majors: exercise test + fingerprint freeze; no auto-merge.
 - Security: skip cooldown; do not skip tests or fingerprints.
+- Verify locally, push once; never change CI config to make a bump pass.
 - New feature dependencies belong in that feature's slice, not this maintenance path.
 
 ## Related
 
 - [Update dependencies](../how-to/update-dependencies.md)
+- [Run tests locally](../how-to/run-tests-locally.md)
 - [Install agent skills](../how-to/install-agent-skills.md)
 - [Bun catalogs](https://bun.sh/docs/install/catalogs)

package/dist/docs/versioned/next/explanation/local-first-data.md

@@ -41,6 +41,15 @@ Terreno 57.
 5. **Backend sync registration** — Every synced collection needs `syncPlugin`, `isDeletedPlugin`, and a `sync` block on `modelRouter`, plus `SyncApp` and `RealtimeApp` on the server. Optional `sync.adminBroadcast: true` also emits `sync:delta` to `{collection}|admin`. Admin clients subscribe with `mode: "window"` (`createSyncDb({windowCollections})`) so they do not snapshot or reconcile that collection; they call `hydrateWindow` (REST membership ids + `GET /sync/entities`). Pass the same `accessControl` into `SyncApp` that `AdminApp` uses so `{collection}|admin` requires `admin:access`. `AdminApp.register` also installs that model's admin list/read/`queryFilter` on the admin window so hydrate and live `|admin` deltas match `/admin` REST. Without RBAC, `user.admin` is enough for the shell gate. Live deltas on that stream apply only to ids already in the window; Refresh is a REST re-query plus `hydrateWindow`.
 6. **Collections too large to sync whole** — List them in `createSyncDb({queryCollections})`. They skip snapshot bootstrap; screens load server-filtered *query windows* (`useWindowQuery`) from the `modelRouter` list endpoint. A window stores only membership (ordered ids); rows live once in the shared entity table. Overlapping windows therefore share rows — one delta updates both views — while each view lists only its own query's members, plus cached rows that newly match its `where` inside the loaded range. Live deltas still arrive on the user's normal streams; windows on screen refetch on reconnect to cover deltas missed offline.
 
+## First load and reconnects
+
+A fresh device has to download every row the user can see before the UI is complete. The
+client asks for all of the user's streams in one batched request per round, writes each
+round while the next one downloads, and writes rows in small chunks so the screen stays
+responsive. Reconnects use the same path: when nothing changed, catching up costs two
+requests however many collections the app syncs. Collections too large to download whole
+belong in `queryCollections` instead.
+
 ## Tradeoffs
 
 **Gains:** instant UI, offline writes with a durable outbox, simpler screen code, and one write path on the server (sync and REST share `modelRouter`).

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

@@ -47,6 +47,7 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid` (ops-dashboard scorecards and spans: [dashboard-chart-parity](../implementationPlans/dashboard-chart-parity.md))
 - [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md) — PNG goldens for the chart visual gallery, not JSON snapshots
 - [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer
+- [Use syncdb correctly](use-syncdb-correctly.md) — Serial snapshot startup, outbox-halting 403s, phantom creates, conflicts, and other library behavior apps must handle
 - [Generate a REST CLI from OpenAPI](generate-a-rest-cli.md) — Scaffold `terreno generate rest-cli` for an app API
 - [In-app notifications](in-app-notifications.md) — Register `NotificationsApp`, syncdb inbox, and UI bell
 - [Add organizations](add-organizations.md) — Opt into Membership-backed tenancy, RBAC, admin, and seeded examples

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

@@ -260,8 +260,10 @@ 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
@@ -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/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

@@ -0,0 +1,111 @@
+# How to Use syncdb Correctly
+
+This page lists `@terreno/syncdb` behavior that a working app has to account for. Each entry says what the library does today, what breaks if you ignore it, and what to do instead. It was checked against `syncdb/src` and `api/src/sync` at 57.13.0. Several entries are library gaps rather than intended behavior. Delete an entry when its gap is fixed.
+
+Read [Local-first data](../explanation/local-first-data.md) and [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) first.
+
+## Startup and snapshots
+
+### 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. 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. 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. | 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.
+
+### No loading flag on synced reads
+
+`useQuery` returns a plain array. `useListQuery` returns `{data}`. The `isPending` on `useEntity`/`useReadQuery` means an outbox write is pending, not that data is loading. An empty array before bootstrap looks the same as an empty collection, so a screen that renders its empty state from `[]` flashes "nothing here" on every cold start.
+
+The per-stream `bootstrapped` mark is the right signal, but `isStreamBootstrapped` is not exported. Read the cell directly:
+
+```typescript
+const isBootstrapped = (stream: string): boolean =>
+  syncDb.store.raw.getCell("_cursors", stream, "bootstrapped") === true;
+```
+
+Don't use the cursor (`useSyncStatus().streams`) for this. A live delta can move the cursor to the head before the snapshot below it has been paged. `useWindowQuery` (query collections only) does expose `isLoading`.
+
+A stream key is `<collection>|<scopeType>:<value>`, for example `documents|tenant:<workspaceId>`. A user with several tenants has one stream per tenant. Treat a collection as loaded only once every known stream for it is bootstrapped (`syncDb.store.getKnownStreams()`).
+
+## Writes
+
+### Mutations return an id, not an outcome
+
+`create`, `update` and `remove` from `useMutate` (and from the generated `useCreate*`/`useUpdate*`/`useDelete*` hooks) return `{mutationId, id}` synchronously. There is no promise for the server ack. The client also drops the ack's `warning`. A `warning` means a server post-hook threw after the write committed.
+
+If a screen needs to know the outcome (close a modal only once the create landed, toast a refusal), wrap the transport and HTTP channel and record ack and nack outcomes by `mutationId`. Then await that `mutationId`. Don't poll the store.
+
+### A 403 from a write halts the whole outbox
+
+The server maps 403/405 to an `unauthorized` nack and 400/404/422 to `validation`. They behave very differently:
+
+| Nack | Client behavior |
+| --- | --- |
+| `unauthorized` | The mutation is re-queued and the **whole drain stops** (auth-pause). On re-auth the same `mutationId` replays, reads the same stored nack, and pauses again. It never settles. |
+| `validation` | The mutation is marked `failed` and the drain continues. That entity's later writes stay blocked until `retryFailed({entityId})`. |
+| `conflict` | That entity's later writes stay blocked (or every write is blocked, with `haltQueueOnConflict: true`) until `resolveConflict`. |
+| `error` | Retried up to the retry budget, then handled like `validation`. |
+
+So a router hook that refuses a synced write for a business reason must throw **422**, not 403. That includes `preCreate`/`preUpdate` membership checks. Keep 403 for real auth failures.
+
+### Don't send a stale tenant field on create
+
+For a tenant-scoped collection, `enforceWriteScope` checks a client-sent scope field (for example `workspaceId`) against the user's memberships **before** `preCreate` runs. A value the user does not belong to is a 403, which halts the outbox (see above). If the field is missing or null, the check is skipped and `preCreate` can fill it in.
+
+Either omit the tenant field and let `preCreate` set it, or send it only from the currently synced row of the parent tenant, never from a persisted id that may be stale.
+
+### The local row never gets server-computed fields from the create
+
+After an ack, the client stamps the row with the ack's seq and keeps the optimistic data. The server's create delta has the same seq, so the client skips it. Whatever `preCreate`, schema defaults or hooks set on the server does not reach the local row until that row changes again or is repaired. If the delta arrives before the ack, the row is marked for repair, but repair only runs on the next `reconcile()` (reconnect, seq jump, or every 5 minutes).
+
+Do one of these:
+
+- Send every field the UI reads in the create payload, matching what the server would compute (defaults, `order`, ownership fields).
+- After the ack, patch the local row yourself.
+
+The local row's `data` is exactly what you passed. Include `_id` in the payload if anything reads `row._id`. Server-written rows carry `_id` and `id`.
+
+### A refused create leaves a phantom row
+
+When a create is nacked as `validation` (or runs out of `error` retries), the repair fetch finds no server row and only clears the repair mark. The optimistic row stays in the store with `stream: ""` and shows up in queries. Only `forceResync` purges such rows.
+
+On a refused create, tombstone the local row yourself and call `retryFailed({entityId})` so later writes to that id are released.
+
+### Conflicts are never resolved for you
+
+A `conflict` nack blocks every later write to that row, and any queued write whose args mention its id, until someone calls `client.resolveConflict({mutationId, strategy: "keepMine" | "useServer"})` (or `useConflicts().resolve`). Local edits keep applying optimistically, so the UI looks fine while nothing reaches the server.
+
+If the app has no conflict UI, run a watcher that resolves each conflict as it is recorded. Use `keepMine` for fields the user types, and `useServer` for everything else.
+
+## Server side
+
+### Write synced models one document at a time, by `_id`
+
+On a synced model, `updateMany`, `deleteMany`, `deleteOne`, `findOneAndDelete` and `bulkWrite` throw. Single-document writes by `_id` without upsert are allowed: `save()`, `updateOne`, `findOneAndUpdate`, `findByIdAndUpdate`, `replaceOne`. Delete by setting `deleted: true`, because a hard delete emits no delta.
+
+In tests, clean up with `Model.collection.deleteMany(...)`, which bypasses Mongoose.
+
+### Deltas don't apply `queryFilter`
+
+Snapshots and `/sync/entities` apply the router's `queryFilter`. Live deltas check only `permissions.read` (or RBAC) per recipient. A router that restricts visibility only through `queryFilter` leaks rows over the socket. Every synced router's `read` permission must enforce the same restriction itself.
+
+### Membership grants arrive late
+
+A user's new tenant is picked up by the socket's session revalidation sweep (`sessionRevalidationIntervalMs`, 60 s by default) or a resubscribe. The client finds the new stream on its next `reconcile()` (`reconcileIntervalMs`, 5 minutes by default, plus reconnects). Until then the new tenant's rows don't appear.
+
+When the product grants membership, push a content-free event to the user's sockets and have the client reconnect syncdb. Reconnecting resubscribes and reconciles. Grants written another way (admin, scripts) still wait for the timers.
+
+## Auth
+
+### Logging out does not wipe local data
+
+The client's own `onAuthChange` handling treats a logout as a pause and **never wipes**. A different user logging in does wipe. To clear one user's data on sign-out, set `wipeOnSignOut: true` and call `client.signOut()` explicitly when the app's user clears.

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,6 +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 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()` |
@@ -201,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. |
@@ -587,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 |
@@ -635,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/package.json

@@ -11,8 +11,8 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "57.13.0",
-    "@terreno/blocks": "57.13.0",
+    "@terreno/api": "57.15.0",
+    "@terreno/blocks": "57.15.0",
     "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.13.0"
+  "version": "57.15.0"
 }

package/src/docs/upgrades/57.14.0.md

@@ -0,0 +1,43 @@
+# Upgrading to 57.14.0
+
+**Action required:** No
+**Affected packages:** @terreno/syncdb
+
+## Summary
+
+`@terreno/syncdb` pages snapshot streams in parallel (up to 6 at once by default) instead of one at a time, so cold start, reconcile, subscribe catch-up, `forceResync`, and wipe re-bootstrap finish faster when an app has many collections or scopes. Each stream now runs one snapshot pass at a time, which stops a concurrent pass from marking a purged stream bootstrapped over rows it never paged. No code change is required.
+
+## Breaking changes
+
+None
+
+## Deprecations
+
+None
+
+## New capabilities
+
+### `snapshotConcurrency` on `createSyncDb`
+
+The client now sends up to `snapshotConcurrency` snapshot requests at once (default `DEFAULT_SNAPSHOT_CONCURRENCY`, 6). If your backend cannot take the extra parallel load at cold start, lower it. `1` restores the old one-stream-at-a-time behavior.
+
+```typescript
+// Before
+export const syncDb = createSyncDb({authProvider, baseUrl, collections, name: "my-app"});
+
+// After (only if you need to limit parallel snapshot requests)
+export const syncDb = createSyncDb({
+  authProvider,
+  baseUrl,
+  collections,
+  name: "my-app",
+  snapshotConcurrency: 2,
+});
+```
+
+A new how-to, `docs/how-to/use-syncdb-correctly.md`, lists library behavior apps have to handle.
+
+## Verification
+
+- `bun run compile` and `bun run lint` at the app root
+- Log in on a fresh device or after `wipeLocalData`; synced screens load, and the backend logs show several `/sync/snapshot` requests in flight together

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/versioned/next/explanation/ai-workflows.md

@@ -159,13 +159,13 @@ Ensures preview environments don't accumulate and waste resources.
 
 #### Dependabot Auto-merge
 **Trigger:** Dependabot pull request opened  
-**Purpose:** Automatically merges dependency updates after CI passes
+**Purpose:** Automatically merges Dependabot security updates after CI passes. Dependabot opens no version-update PRs; routine upgrades run through the `update-dependencies` skill.
 
 **Requirements for auto-merge:**
 - All CI checks pass
 - Dependabot PR (created by Dependabot)
+- Not a semver-major bump (for a grouped PR, no bump in the group is major); majors wait for a human review
 - No conflicts
-- 7-day cooldown for security (see Dependency Management)
 
 **Learn more:** [Dependency Management](dependency-management.md)
 
@@ -208,7 +208,7 @@ Ensures preview environments don't accumulate and waste resources.
 ### Continuous Sync
 - Documentation syncs on every master push
 - Rules sync on every master push
-- Dependencies update daily (Dependabot)
+- Dependencies update daily (`update-dependencies` skill); Dependabot opens security fixes only
 - Quality improvements run daily (JSDoc, tests)
 
 ## Working with AI Workflows
@@ -280,8 +280,8 @@ The docs-audit workflow flags a missing README or reference page and obvious int
 
 ### Dependabot PR doesn't auto-merge
 - Verify all CI checks pass (green checkmarks)
-- Check 7-day cooldown hasn't been violated
 - Ensure no merge conflicts exist
+- If the security fix needs code changes, fold it into the rolling `chore/update-dependencies` PR instead of pushing to the Dependabot branch
 
 ### AI workflow creates poor quality PR
 - Review the workflow definition in `.github/workflows/*.md`
@@ -290,7 +290,7 @@ The docs-audit workflow flags a missing README or reference page and obvious int
 
 ## Related Documentation
 
-- [Dependency Management](dependency-management.md) — Dependabot configuration and auto-merge
+- [Dependency Management](dependency-management.md) — Dependabot security-only configuration, auto-merge, and the update skill
 - [Deploy to GCP](../how-to/deploy-to-gcp.md) — Manual deployment guide
 - [GCP Hosting Architecture](gcp-hosting-architecture.md) — Static site hosting design
 - [Environment Variables](../reference/environment-variables.md) — Configuration reference

package/src/docs/versioned/next/explanation/dependency-management.md

@@ -1,16 +1,16 @@
 # Dependency Management
 
-Terreno pins shared versions in the Bun catalog, lands JavaScript updates through
-an agent skill that proves each bump with a test, and keeps Expo native
-fingerprints frozen until a release.
+Terreno pins shared versions in the Bun catalog, lands routine JavaScript updates
+through an agent skill that proves each bump with a test, limits Dependabot to
+security fixes, and keeps Expo native fingerprints frozen until a release.
 
 ## Layers
 
 | Layer | Job |
 | --- | --- |
 | **Bun catalog** | One version for every dependency shared by two or more workspace packages (`catalog:` in manifests) |
-| **`update-dependencies` skill** | Daily rolling PR on `chore/update-dependencies`: cooldown, exercise test, fingerprint freeze, ledger of landed/failed |
-| **Dependabot** | Backup signal for bun + GitHub Actions. Native/Expo catalog names are ignored so auto-merge cannot change the fingerprint |
+| **`update-dependencies` skill** | The only path for routine version upgrades. Daily rolling PR on `chore/update-dependencies`: cooldown, exercise test, local gate, one push per run, fingerprint freeze, ledger of landed/failed |
+| **Dependabot** | Security updates only for bun + GitHub Actions. Native/Expo catalog names are ignored so auto-merge cannot change the fingerprint |
 | **Release + `upgrading-expo`** | Expo SDK, React Native, and other native-module bumps |
 
 Operator steps: [Update dependencies](../how-to/update-dependencies.md). Catalog rule: workspace `package.json` files use `"catalog:"` for shared pins.
@@ -41,16 +41,18 @@ Change a shared version in the catalog once. Do not pin a second copy in a works
 
 ## Agent updates vs Dependabot
 
-Dependabot groups many packages and merges when CI is green. That misses two Terreno constraints:
+Dependabot version updates group many packages and merge when CI is green. That misses Terreno constraints, so Dependabot now opens security PRs only:
 
 1. **Exercise.** CI can pass without any test importing the bumped module. The skill requires a named test file that imports the package and that passed **after** the bump. If none exists, write a tracer-bullet test first.
 2. **Fingerprint.** Expo `runtimeVersion.policy: "fingerprint"` ties OTA runtime and EAS dev builds to native hashes of `example-frontend` and `demo`. Native module bumps belong in a release, not a weekday dependency PR.
 
+3. **CI is not the test runner.** A red grouped Dependabot PR invites an agent to push fix after fix to the Dependabot branch. Each push starts a full CircleCI pipeline that is attributed to, and emails, whoever owns the pushing token. The skill runs the CI mirror (`bun run prepush`) locally, pushes once per run, never edits CI config to make a bump pass, and stops after two red CI rounds.
+
 `scripts/planning/fingerprintRisk.ts` (`isFingerprintSkip`) is the skip matcher. After every allowed bump the skill still recomputes hashes; a changed hash is reverted even if the matcher allowed the name.
 
 ## Cooldown
 
-Non-security npm versions wait **7 days** after publish before a bump (`npm view <name> time`). Most malicious publishes are yanked inside a day. GitHub Dependabot uses the same `cooldown.default-days: 7`. CVE/advisory bumps skip the wait and still need an exercise test and a fingerprint freeze.
+Non-security npm versions wait **7 days** after publish before a bump (`npm view <name> time`). Most malicious publishes are yanked inside a day. CVE/advisory bumps skip the wait and still need an exercise test and a fingerprint freeze. Dependabot security updates are advisory bumps, so they have no cooldown.
 
 ## Fingerprint freeze
 
@@ -67,16 +69,16 @@ JavaScript packages, GitHub Actions, and a few Expo JS-only names may update. Me
 
 ## Dependabot configuration
 
-`.github/dependabot.yml` still opens grouped PRs:
+`.github/dependabot.yml` sets `open-pull-requests-limit: 0` on every block. That turns off version-update PRs; security updates ignore the limit and still honor `ignore`. Each block's group uses `applies-to: security-updates`, so fixes arrive grouped:
 
-| Group | Ecosystem | Schedule |
-| --- | --- | --- |
-| GitHub Actions | `github-actions` at `/` | Weekly |
-| Root catalog and root tools | `bun` at `/` | Monthly |
-| Backend workspaces | `bun` under api, ai, backends, … | Monthly |
-| Frontend workspaces | `bun` under ui, rtk, demo, apps, … | Monthly |
+| Group | Ecosystem |
+| --- | --- |
+| `github-actions` | `github-actions` at `/` |
+| `root` | `bun` at `/` (root catalog and root tools) |
+| `backend` | `bun` under api, ai, backends, … |
+| `frontend` | `bun` under ui, rtk, demo, apps, … |
 
-Frontend ignores catalog-managed names so those PRs do not duplicate the root catalog. Root ignores fingerprint-skip names. `dependabot-auto-merge.yml` still squash-merges Dependabot PRs when required checks pass. Do not merge a Dependabot PR that includes a skip-list package; redo it with [Update dependencies](../how-to/update-dependencies.md).
+Frontend ignores catalog-managed names so those fixes land once, in the root catalog. Root ignores fingerprint-skip names, so a security fix for a native/Expo package never opens a PR; handle it by hand in a release. `dependabot-auto-merge.yml` approves patch and minor Dependabot PRs and enables squash auto-merge, so those security PRs merge when required checks pass. A semver-major security PR (or a group containing one) gets no approval or auto-merge and waits for a human. When one fails because the fix needs code changes, fold the bump into the rolling PR ([Update dependencies](../how-to/update-dependencies.md)); never push to the `dependabot/*` branch.
 
 ## Daily rolling PR
 
@@ -91,10 +93,12 @@ Each package is still proven alone (exercise test + fingerprint) before it stays
 - One rolling PR; many proven commits on that branch.
 - Majors: exercise test + fingerprint freeze; no auto-merge.
 - Security: skip cooldown; do not skip tests or fingerprints.
+- Verify locally, push once; never change CI config to make a bump pass.
 - New feature dependencies belong in that feature's slice, not this maintenance path.
 
 ## Related
 
 - [Update dependencies](../how-to/update-dependencies.md)
+- [Run tests locally](../how-to/run-tests-locally.md)
 - [Install agent skills](../how-to/install-agent-skills.md)
 - [Bun catalogs](https://bun.sh/docs/install/catalogs)

package/src/docs/versioned/next/explanation/local-first-data.md

@@ -41,6 +41,15 @@ Terreno 57.
 5. **Backend sync registration** — Every synced collection needs `syncPlugin`, `isDeletedPlugin`, and a `sync` block on `modelRouter`, plus `SyncApp` and `RealtimeApp` on the server. Optional `sync.adminBroadcast: true` also emits `sync:delta` to `{collection}|admin`. Admin clients subscribe with `mode: "window"` (`createSyncDb({windowCollections})`) so they do not snapshot or reconcile that collection; they call `hydrateWindow` (REST membership ids + `GET /sync/entities`). Pass the same `accessControl` into `SyncApp` that `AdminApp` uses so `{collection}|admin` requires `admin:access`. `AdminApp.register` also installs that model's admin list/read/`queryFilter` on the admin window so hydrate and live `|admin` deltas match `/admin` REST. Without RBAC, `user.admin` is enough for the shell gate. Live deltas on that stream apply only to ids already in the window; Refresh is a REST re-query plus `hydrateWindow`.
 6. **Collections too large to sync whole** — List them in `createSyncDb({queryCollections})`. They skip snapshot bootstrap; screens load server-filtered *query windows* (`useWindowQuery`) from the `modelRouter` list endpoint. A window stores only membership (ordered ids); rows live once in the shared entity table. Overlapping windows therefore share rows — one delta updates both views — while each view lists only its own query's members, plus cached rows that newly match its `where` inside the loaded range. Live deltas still arrive on the user's normal streams; windows on screen refetch on reconnect to cover deltas missed offline.
 
+## First load and reconnects
+
+A fresh device has to download every row the user can see before the UI is complete. The
+client asks for all of the user's streams in one batched request per round, writes each
+round while the next one downloads, and writes rows in small chunks so the screen stays
+responsive. Reconnects use the same path: when nothing changed, catching up costs two
+requests however many collections the app syncs. Collections too large to download whole
+belong in `queryCollections` instead.
+
 ## Tradeoffs
 
 **Gains:** instant UI, offline writes with a durable outbox, simpler screen code, and one write path on the server (sync and REST share `modelRouter`).

package/src/docs/versioned/next/how-to/README.md

@@ -47,6 +47,7 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid` (ops-dashboard scorecards and spans: [dashboard-chart-parity](../implementationPlans/dashboard-chart-parity.md))
 - [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md) — PNG goldens for the chart visual gallery, not JSON snapshots
 - [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer
+- [Use syncdb correctly](use-syncdb-correctly.md) — Serial snapshot startup, outbox-halting 403s, phantom creates, conflicts, and other library behavior apps must handle
 - [Generate a REST CLI from OpenAPI](generate-a-rest-cli.md) — Scaffold `terreno generate rest-cli` for an app API
 - [In-app notifications](in-app-notifications.md) — Register `NotificationsApp`, syncdb inbox, and UI bell
 - [Add organizations](add-organizations.md) — Opt into Membership-backed tenancy, RBAC, admin, and seeded examples

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

@@ -260,8 +260,10 @@ 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
@@ -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/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

@@ -0,0 +1,111 @@
+# How to Use syncdb Correctly
+
+This page lists `@terreno/syncdb` behavior that a working app has to account for. Each entry says what the library does today, what breaks if you ignore it, and what to do instead. It was checked against `syncdb/src` and `api/src/sync` at 57.13.0. Several entries are library gaps rather than intended behavior. Delete an entry when its gap is fixed.
+
+Read [Local-first data](../explanation/local-first-data.md) and [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) first.
+
+## Startup and snapshots
+
+### 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. 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. 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. | 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.
+
+### No loading flag on synced reads
+
+`useQuery` returns a plain array. `useListQuery` returns `{data}`. The `isPending` on `useEntity`/`useReadQuery` means an outbox write is pending, not that data is loading. An empty array before bootstrap looks the same as an empty collection, so a screen that renders its empty state from `[]` flashes "nothing here" on every cold start.
+
+The per-stream `bootstrapped` mark is the right signal, but `isStreamBootstrapped` is not exported. Read the cell directly:
+
+```typescript
+const isBootstrapped = (stream: string): boolean =>
+  syncDb.store.raw.getCell("_cursors", stream, "bootstrapped") === true;
+```
+
+Don't use the cursor (`useSyncStatus().streams`) for this. A live delta can move the cursor to the head before the snapshot below it has been paged. `useWindowQuery` (query collections only) does expose `isLoading`.
+
+A stream key is `<collection>|<scopeType>:<value>`, for example `documents|tenant:<workspaceId>`. A user with several tenants has one stream per tenant. Treat a collection as loaded only once every known stream for it is bootstrapped (`syncDb.store.getKnownStreams()`).
+
+## Writes
+
+### Mutations return an id, not an outcome
+
+`create`, `update` and `remove` from `useMutate` (and from the generated `useCreate*`/`useUpdate*`/`useDelete*` hooks) return `{mutationId, id}` synchronously. There is no promise for the server ack. The client also drops the ack's `warning`. A `warning` means a server post-hook threw after the write committed.
+
+If a screen needs to know the outcome (close a modal only once the create landed, toast a refusal), wrap the transport and HTTP channel and record ack and nack outcomes by `mutationId`. Then await that `mutationId`. Don't poll the store.
+
+### A 403 from a write halts the whole outbox
+
+The server maps 403/405 to an `unauthorized` nack and 400/404/422 to `validation`. They behave very differently:
+
+| Nack | Client behavior |
+| --- | --- |
+| `unauthorized` | The mutation is re-queued and the **whole drain stops** (auth-pause). On re-auth the same `mutationId` replays, reads the same stored nack, and pauses again. It never settles. |
+| `validation` | The mutation is marked `failed` and the drain continues. That entity's later writes stay blocked until `retryFailed({entityId})`. |
+| `conflict` | That entity's later writes stay blocked (or every write is blocked, with `haltQueueOnConflict: true`) until `resolveConflict`. |
+| `error` | Retried up to the retry budget, then handled like `validation`. |
+
+So a router hook that refuses a synced write for a business reason must throw **422**, not 403. That includes `preCreate`/`preUpdate` membership checks. Keep 403 for real auth failures.
+
+### Don't send a stale tenant field on create
+
+For a tenant-scoped collection, `enforceWriteScope` checks a client-sent scope field (for example `workspaceId`) against the user's memberships **before** `preCreate` runs. A value the user does not belong to is a 403, which halts the outbox (see above). If the field is missing or null, the check is skipped and `preCreate` can fill it in.
+
+Either omit the tenant field and let `preCreate` set it, or send it only from the currently synced row of the parent tenant, never from a persisted id that may be stale.
+
+### The local row never gets server-computed fields from the create
+
+After an ack, the client stamps the row with the ack's seq and keeps the optimistic data. The server's create delta has the same seq, so the client skips it. Whatever `preCreate`, schema defaults or hooks set on the server does not reach the local row until that row changes again or is repaired. If the delta arrives before the ack, the row is marked for repair, but repair only runs on the next `reconcile()` (reconnect, seq jump, or every 5 minutes).
+
+Do one of these:
+
+- Send every field the UI reads in the create payload, matching what the server would compute (defaults, `order`, ownership fields).
+- After the ack, patch the local row yourself.
+
+The local row's `data` is exactly what you passed. Include `_id` in the payload if anything reads `row._id`. Server-written rows carry `_id` and `id`.
+
+### A refused create leaves a phantom row
+
+When a create is nacked as `validation` (or runs out of `error` retries), the repair fetch finds no server row and only clears the repair mark. The optimistic row stays in the store with `stream: ""` and shows up in queries. Only `forceResync` purges such rows.
+
+On a refused create, tombstone the local row yourself and call `retryFailed({entityId})` so later writes to that id are released.
+
+### Conflicts are never resolved for you
+
+A `conflict` nack blocks every later write to that row, and any queued write whose args mention its id, until someone calls `client.resolveConflict({mutationId, strategy: "keepMine" | "useServer"})` (or `useConflicts().resolve`). Local edits keep applying optimistically, so the UI looks fine while nothing reaches the server.
+
+If the app has no conflict UI, run a watcher that resolves each conflict as it is recorded. Use `keepMine` for fields the user types, and `useServer` for everything else.
+
+## Server side
+
+### Write synced models one document at a time, by `_id`
+
+On a synced model, `updateMany`, `deleteMany`, `deleteOne`, `findOneAndDelete` and `bulkWrite` throw. Single-document writes by `_id` without upsert are allowed: `save()`, `updateOne`, `findOneAndUpdate`, `findByIdAndUpdate`, `replaceOne`. Delete by setting `deleted: true`, because a hard delete emits no delta.
+
+In tests, clean up with `Model.collection.deleteMany(...)`, which bypasses Mongoose.
+
+### Deltas don't apply `queryFilter`
+
+Snapshots and `/sync/entities` apply the router's `queryFilter`. Live deltas check only `permissions.read` (or RBAC) per recipient. A router that restricts visibility only through `queryFilter` leaks rows over the socket. Every synced router's `read` permission must enforce the same restriction itself.
+
+### Membership grants arrive late
+
+A user's new tenant is picked up by the socket's session revalidation sweep (`sessionRevalidationIntervalMs`, 60 s by default) or a resubscribe. The client finds the new stream on its next `reconcile()` (`reconcileIntervalMs`, 5 minutes by default, plus reconnects). Until then the new tenant's rows don't appear.
+
+When the product grants membership, push a content-free event to the user's sockets and have the client reconnect syncdb. Reconnecting resubscribes and reconciles. Grants written another way (admin, scripts) still wait for the timers.
+
+## Auth
+
+### Logging out does not wipe local data
+
+The client's own `onAuthChange` handling treats a logout as a pause and **never wipes**. A different user logging in does wipe. To clear one user's data on sign-out, set `wipeOnSignOut: true` and call `client.signOut()` explicitly when the app's user clears.

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,6 +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 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()` |
@@ -201,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. |
@@ -587,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 |
@@ -635,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).