@terreno/mcp 57.18.0 → 57.19.2

package/src/docs/versioned/57.18.0/tutorials/getting-started.md

@@ -0,0 +1,84 @@
+# Getting Started
+
+Create a new Terreno app with the scaffolding CLI, then run it locally.
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) installed
+- MongoDB as a **replica set** (required for sync and realtime — see [deployment baseline](../explanation/deployment-baseline.md))
+
+## 1. Scaffold a new app
+
+From an empty parent directory:
+
+```bash
+bunx create-terreno-app my-app --display-name "My App"
+```
+
+npm alternative:
+
+```bash
+npm create terreno-app my-app -- --display-name "My App"
+```
+
+This writes `my-app/backend` and `my-app/frontend` plus deploy and agent config. The CLI does not install dependencies or seed data.
+
+Full flag reference, layout, and deploy notes: [Create a Terreno app](../how-to/create-a-terreno-app.md).
+
+## 2. Install dependencies
+
+```bash
+cd my-app
+(cd backend && bun install)
+(cd frontend && bun install)
+```
+
+## 3. Start MongoDB
+
+Use Atlas or a local single-node replica set. The scaffolded `backend/.env` points at `mongodb://127.0.0.1:27017/my_app?replicaSet=rs0` (database name derived from `appName`).
+Follow [Start MongoDB (replica set)](../how-to/create-a-terreno-app.md#3-start-mongodb-replica-set) for local commands.
+
+## 4. Seed and start the backend
+
+```bash
+(cd backend && bun run seed)
+(cd backend && bun run dev)
+```
+
+Backend runs at `http://localhost:4000`. OpenAPI spec at `/openapi.json`.
+
+Seed users: `test@example.com` and `admin@example.com`, password `testpassword123`.
+
+## 5. Start the frontend
+
+Keep the backend running while generating the SDK.
+
+```bash
+(cd frontend && bun run sdk)
+(cd frontend && bun run web)
+```
+
+Frontend runs at `http://localhost:8082`. Sign in with `test@example.com` / `testpassword123`.
+
+## Explore the Terreno monorepo examples
+
+If you are contributing to Terreno or want reference implementations inside this repository:
+
+```bash
+git clone https://github.com/TerrenoLabs/terreno.git
+cd terreno && bun run bootstrap
+```
+
+| Service | Port | Command (from repo root) |
+| --- | --- | --- |
+| example-backend | 4000 | `bun run backend:dev` |
+| example-frontend web | 8082 | `EXPO_PUBLIC_API_URL=http://localhost:4000 bun run frontend:web` |
+
+The example backend needs `MONGO_URI` (replica set) and auth secrets — see the repository [AGENTS.md](https://github.com/TerrenoLabs/terreno/blob/master/AGENTS.md) (Cursor Cloud section). Seed with `bun run backend:seed` from the repo root.
+
+## Next steps
+
+- [Create a Terreno app](../how-to/create-a-terreno-app.md) — CLI flags, layout, deploy, MCP write path
+- [How to create a model](../how-to/create-a-model.md) — Model conventions including required field descriptions
+- [How-to guides](../how-to/) — Task-focused guides
+- [Reference](../reference/) — Package and API details

package/src/docs/versioned/next/approval-rubric.md

@@ -140,7 +140,7 @@ A finding here is blocking when it is certain and should-fix when it is likely.
   source; a `TODO`, `FIXME`, or commented-out code added; explicit `any` added; PR body
   missing `Why`, `What changed`, or `Verification`; `WIP` in the title; the plan edited
   in the same PR to match the code.
-- Never low: new logic without a test; a `⚠️ Not tested` row; an unresolved bot thread;
+- Never low: new logic without a test; a `⚠️ Not tested` row without a reviewer action; an unresolved bot thread;
   a revert.
 - Size never moves the level. Changed lines and file counts say nothing about risk on
   their own: judge what the lines do. Pure renames and moves, regenerated SDK or

package/src/docs/versioned/next/explanation/loop-engineering.md

@@ -119,6 +119,7 @@ include:
 | --- | --- |
 | Backend/API/data | `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`, `generate-sdk`, `terreno-data-fetching` |
 | UI/app | `terreno-ui`, `building-terreno-apps`, `verify-ui-changes` |
+| Testing | `terreno-test-setup`, `terreno-backend-tests`, `terreno-frontend-tests`, `terreno-mobile-tests` |
 | AI/prompts | `ai-prompt-governance` — new features also follow [Develop an AI feature](../how-to/ai-feature-development.md) |
 | Docs/submission | `update-docs`, Brew, `fix-conflicts` |
 | GitHub issues | `create-github-issue`, `work-github-issues`, `implement-ready-for-dev` (Pick plan comment is the Roast contract; unattended Grow may also write an IP) |

package/src/docs/versioned/next/explanation/roadmap-process.md

@@ -402,7 +402,7 @@ do not claim completion until done.
 | Workflow | Trigger | Purpose |
 | -------- | ------- | ------- |
 | [`.github/workflows/triage.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/triage.yml) | Issue opened | `status:needs-triage` + `area:*` from package dropdown + `type:*` from Kind when present; `area:*` / `type:*` labels the issue was opened with win, so `roadmap:sync` issues are not asked for an area |
-| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when roadmap content changes. A new **Last updated** timestamp alone does not open a pull request |
+| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when roadmap content changes; [Bot merge](../how-to/release-automation.md) merges it once CI is green. A new **Last updated** timestamp alone does not open a pull request |
 | [`.github/workflows/roadmap-sync.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-sync.yml) | Taxonomy files change on `master` + manual | Apply labels and reconcile the board's fields and items |
 | [`.github/workflows/roadmap-reconcile.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-reconcile.yml) | IP or task files change on `master` + manual | Advance status from IP headers, add an entry for every new IP, open its tracking issue, push to the board, regenerate `ROADMAP.md` |
 All three share the `roadmap` concurrency group. They write the same board, and interleaving

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

@@ -1331,6 +1331,17 @@ One easy-to-use harness inside `@terreno/ai` that runs long-lived agentic work d
 
 ---
 
+## circleci-pr-speed-loop
+
+**Title:** `CircleCI PR Speed Loop`
+
+**Labels:** `area:dx`, `type:feature`  
+**Project fields:** Area=`dx`, Target=`Future`, Impact=`Feature`, IP=`circleci-pr-speed-loop`, Status=`In progress`
+
+- **Implementation plan:** [circleci-pr-speed-loop.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/circleci-pr-speed-loop.md)
+
+---
+
 # Shipped, umbrella, and declined IPs
 
 Tracking issues created for IPs that previously lacked a `**Roadmap issue:**` header.

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

@@ -17,6 +17,8 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Create a Terreno app](create-a-terreno-app.md) — Scaffold a full-stack app with `create-terreno-app` (Bun or npm)
 - [Update dependencies](update-dependencies.md) — Daily rolling PR, exercise test, Expo fingerprint freeze
 - [CircleCI](circleci.md) — Dual-run CI on CircleCI (package CI / policy / e2e; deploys later)
+- [Release automation](release-automation.md) — Let agents merge release notes and roadmap updates; publish only merged notes
+- [Set up tests in a Terreno app](set-up-app-tests.md) — Bun backend and frontend tests, Playwright web E2E, Maestro on iOS/Android
 - [Run tests locally](run-tests-locally.md) — Map every CircleCI test job to a Cursor Cloud / laptop command
 - [GitHub Actions CI](github-actions-ci.md) — Cut PR runtime: docs previews, compile-once e2e, pinned Bun
 - [Add feature flags](add-feature-flags.md) — Add feature flags, A/B testing, and OpenFeature migration
@@ -47,6 +49,7 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Upgrade banner](upgrade-banner.md) — Soft warning and hard-block app update UX
 - [Upgrade Terreno](upgrade-terreno.md) — Lockstep `@terreno/*` bumps, note range, order, rollback
 - [Track upstream Expo](track-upstream-expo.md) — Morning probe for SDK betas; `release-X.Y.Z` loop log + native fingerprint deps
+- [Show loading skeletons](show-loading-skeletons.md) — `loading`, `loadingComponent`, and `loadingAnimation` on Box, Card, charts, and Page; `withLoading` for custom components
 - [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

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

@@ -398,7 +398,9 @@ a closed PR.
 `manual-publish-package` also accepts `feature-flags`. Versions must be semver.
 Semver git tags (`57.3.0`, `57.3.0-beta.1`) automatically start
 `publish-release`; prereleases publish to their prerelease npm dist-tag.
-`publish-release` compiles the 16 lockstep packages once with
+`publish-release` first requires the tag to be on `master` with its assembled
+`CHANGELOG.md` section ([release automation](release-automation.md)), then
+compiles the lockstep packages once with
 `bun run --filter ... compile` (dependency order), then runs
 `scripts/ci/publish-package.sh` for all of them in parallel with
 `TERRENO_PUBLISH_PREBUILT=1`. It does not rerun tests: the tagged commit
@@ -417,8 +419,8 @@ 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
+The **Bot merge** workflow (or the release skill, when a human merges) 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.
@@ -515,6 +517,74 @@ circleci config validate .circleci/config.yml
 circleci config validate .circleci/continue-config.yml
 ```
 
+## Measure PR CI speed
+
+```bash
+bun run ci:wall-clock                                  # last 60 merged PRs
+bun run ci:wall-clock --limit 20 --max-directories 3   # rolling window used by the speed loop
+bun run ci:wall-clock --json                           # per-PR rows for a ledger
+```
+
+The command needs an authenticated `gh`. It reads each merged PR's head-commit
+statuses and reports the median, p25, and p75 wall clock for average PRs and
+for all PRs. It also lists which job finished last.
+
+| Term | Definition |
+| --- | --- |
+| Wall clock | First `ci/circleci:` status to the last terminal status of a test or build job |
+| Not counted as the end | `approve`, `architectural-pr-review`, `dco`, `deploy-*`, `*-preview`, `serial-*` |
+| Average PR | Touches at most `--max-directories` top-level directories, not counting `docs/`, `website/`, dot-directories, or root files |
+| Rerun job | Its newest status counts; a job whose newest status is pending makes the PR unmeasured |
+| PRs over 100 files | Directories are counted from the first 100 files (`gh pr list` limit) |
+
+The speed goal and loop that use this metric are in
+[`circleci-pr-speed-loop.md`](../implementationPlans/circleci-pr-speed-loop.md).
+
+## Benchmark a CI change
+
+```bash
+bun run ci:bench --branch origin/master --label baseline           # master only
+bun run ci:bench --branch ci-speed/1-cache --label iter1           # control vs treatment
+bun run ci:bench --branch ci-speed/1-cache --label iter1 --cases api-only --runs 1
+bun run ci:bench --suggest-cases                                   # replayable cases for cases.ts
+```
+
+The command needs an authenticated `gh` and push access. The branch under test
+must contain `origin/master`; otherwise it would run an older job set. For each
+case in `scripts/ci/bench/cases.ts`, run by run, it:
+
+1. Builds `ci-bench/<label>/<case>-<run>-control` from `master` and
+   `…-treatment` from the branch under test, in a temporary worktree. Both
+   reverse-apply the case PR's diff, so the replay touches the same files with
+   real code and keeps later work in those files. `docs/`, `changelog/`, and
+   `website/` are left out: they only drive the docs preview. A case whose code
+   no longer reverts cleanly on `master` is refused before anything is pushed. The control also
+   appends a comment to each file the branch under test changes, so path
+   filtering starts the same workflows for both. A file `master` does not have
+   yet maps to the nearest existing file with comment syntax in the same
+   directory or a parent. If there is none, the touch is skipped. This mirror
+   is best-effort: a touch that lands in a parent directory can start a
+   different set of path filters than the new file does.
+2. Opens both as draft PRs labelled `ci-bench`. Preview deploys,
+   `architectural-pr-review`, and `approve` skip `ci-bench/*` branches.
+3. Waits until every counted job has finished and no status has changed for
+   3 minutes (time out at 60 minutes). Then it measures each with the
+   [PR CI speed](#measure-pr-ci-speed) metric.
+4. Closes both PRs and deletes their branches, even on failure. A branch whose
+   PR never opened is deleted directly. A cleanup that still fails is
+   reported as `cleanupError` on the results, so you can remove it by hand.
+
+| Result | Meaning |
+| --- | --- |
+| `ok` | Every counted job succeeded; the run counts |
+| `invalid` | A counted job failed, usually because later code depends on what the replay reverted. Swap the case in `cases.ts` |
+| `timeout` / `error` | CI never settled, or git or `gh` failed. Three failed status reads in a row end that role only; the other role keeps measuring |
+| role `case` | The case failed before either role ran: it no longer reverts, has no code to replay, or a PR could not open |
+
+Results append to `.terreno/ci-bench/<label>.jsonl` (git-ignored). The summary
+compares the median of per-case medians for control and treatment. Only `ok`
+runs count.
+
 ## Disabled GitHub workflows
 
 Package CI, e2e, npm tag, and deploy workflows (`docs-deploy.yml`,

package/src/docs/versioned/next/how-to/create-a-terreno-app.md

@@ -134,7 +134,7 @@ Open `http://localhost:8082` and sign in as `test@example.com` / `testpassword12
 
 Read the [deployment baseline](../explanation/deployment-baseline.md) first.
 
-**Backend:** the root `Dockerfile` builds only `backend/` on `oven/bun`, listens on `PORT` (default `8080` in the image), binds `0.0.0.0`, and exposes `GET /health`. It does not copy Terreno monorepo packages.
+**Backend:** the root `Dockerfile` builds only `backend/` on `oven/bun:1.4.4-slim`, listens on `PORT` (default `8080` in the image), binds `0.0.0.0`, and exposes `GET /health`. It does not copy Terreno monorepo packages.
 
 ```bash
 docker build -t my-app-backend .

package/src/docs/versioned/next/how-to/github-actions-ci.md

@@ -34,7 +34,7 @@ Do not rely on `/57.1.0/…` URLs in a PR deploy preview.
 | `maestro-e2e` | Demo export + static server only when `demo/`, `ui/`, or `.maestro/flows/demo/` change |
 | `example-backend-docker` | Buildx runs only when the image recipe changes (`Dockerfile`, lockfile, `package.json`). Source-only PRs skip; CD preview deploy still builds the image. `load: true` stays off. |
 | `cd` Cloud Run deploys | Runs a local wrapper around `google-github-actions/deploy-cloudrun` that retries only the transient GitHub WIF subject-token timeout, up to three attempts; IAM, image, and configuration failures fail immediately. The backend preview runs for every example-frontend PR preview, including frontend-only changes, so the Netlify build targets an isolated `pr-<number>` backend instead of production. The frontend deploy waits for that backend's healthy `/health` response before publishing to Netlify, and per-PR concurrency cancels duplicate deploys to the same alias. CD runs the built container against the configured Secret Manager values, including the Cloud Tasks `JOBS_*` env, and requires a healthy `/health` response before pushing or deploying. Preview Cloud Run uses `--memory=1Gi` and `--cpu-boost`, overwrites revision secrets, and binds `PORT` before MongoDB connect. Before deploy it rebuilds traffic with `--set-tags` / `--clear-tags` so a not-Ready tagged revision is omitted (`--remove-tags` leaves that revision in the spec and Cloud Run rejects the update). It then deploys `--no-traffic` without `--tag`, sets `--revision-suffix=pr<n>-<run_id>-<run_attempt>`, and tags the new Ready revision afterward. |
-| Bun install | `.github/actions/setup-bun-workspace` pins Bun `1.4.0` and runs `bun install --frozen-lockfile` with no `~/.bun/install/cache`. CircleCI measurements: cache restore (~15–73s) exceeded the install savings (~9s). See [circleci.md](circleci.md#bun-install-is-uncached). |
+| Bun install | `.github/actions/setup-bun-workspace` pins Bun `1.4.4` and runs `bun install --frozen-lockfile` with no `~/.bun/install/cache`. CircleCI measurements: cache restore (~15–73s) exceeded the install savings (~9s). See [circleci.md](circleci.md#bun-install-is-uncached). |
 
 Playwright e2e on CircleCI groups specs into five shards (`e2e-auth`,
 `e2e-app`, `e2e-admin-core`, `e2e-admin-table`, `e2e-syncdb`). The retained GHA

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

@@ -67,6 +67,7 @@ scan stages come from
 | --- | --- |
 | Lifecycle | `terreno-1-grow` … `terreno-5-taste`, `terreno-pick-roast-loop`, `terreno-planning-loop`, `terreno-taste-sweep` |
 | Terreno apps | backend, UI, admin interfaces, data, schema, SDK, prompts, upgrades, deployment |
+| Testing | `terreno-test-setup` (bootstrap backend, frontend, mobile), `terreno-backend-tests`, `terreno-frontend-tests`, `terreno-mobile-tests`, `backend-test-env` |
 | Docs | `update-docs`, `update-agent-docs`, architecture skills |
 | GitHub | issues, review, UI verification, PR screenshots (`attach-pr-media`), release, dependency updates |
 | Code scans | `terreno-scan-1-aim` … `terreno-scan-5-track`, `terreno-scan-campaign`, `terreno-scan-loop` |

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

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

package/src/docs/versioned/next/how-to/set-up-app-tests.md

@@ -0,0 +1,114 @@
+# Set up tests in a Terreno app
+
+Apps generated by `create-terreno-app` have `bun test` scripts but no test setup. This guide
+adds four layers. Set up the backend first; add the others when you need them.
+
+| Layer | Runs | Tool |
+|-------|------|------|
+| Backend | routes, models, services against in-memory MongoDB | `bun test` + `@terreno/test` + supertest |
+| Frontend unit | components, screens, hooks with React Native mocked | `bun test` + React Native Testing Library |
+| Web E2E | the real web app against the real backend | Playwright |
+| Mobile | the native app on a simulator or emulator | Maestro |
+
+Agents: the `terreno-test-setup` skill runs these steps; `terreno-backend-tests`,
+`terreno-frontend-tests`, and `terreno-mobile-tests` cover writing tests
+([install the skills](install-agent-skills.md)).
+
+## Backend
+
+1. Install: `cd backend && bun add -d @terreno/test supertest @types/supertest` (same version
+   as `@terreno/api`).
+2. `backend/bunfig.toml`:
+
+   ```toml
+   [test]
+   preload = ["./src/tests/bunSetup.ts"]
+   root = "./src"
+   ```
+
+3. `backend/src/tests/bunSetup.ts` — register third-party SDK mocks first, then the Mongo
+   preload, and reset the mocks before each test:
+
+   ```typescript
+   import {registerBackendPreload, registerSendGridMock} from "@terreno/test";
+
+   export const sendGrid = registerSendGridMock();
+
+   registerBackendPreload({
+     onBeforeEach: () => sendGrid.reset(),
+     testEnv: {tokenIssuer: "my-app.test"},
+   });
+   ```
+
+4. Write a route test that builds a `TerrenoApp` with `skipListen: true` and only the routers
+   under test, then calls it with supertest. Authenticate with
+   `authWithToken(app, {token: (await generateTokens(user)).token})`.
+
+The preload starts one `mongodb-memory-server` `mongod` per run (60s launch timeout; the first
+run downloads the binary), resets auth env vars, silences logs, and mocks Sentry. It does not
+wipe collections: tests delete what they read in `beforeEach`. Code that needs change streams
+or transactions sets `process.env.TERRENO_TEST_USE_REPLSET = "true"` at the top of the
+preload. Details: [`@terreno/test` reference](../reference/test.md).
+
+## Frontend unit tests
+
+1. Install: `cd frontend && bun add -d @terreno/test @testing-library/react-native@^13
+   react-test-renderer@<your react version>`. React Native Testing Library 14 changed `render`
+   to async; `renderWithTerreno` targets 13.
+2. `frontend/bunfig.toml`:
+
+   ```toml
+   [test]
+   preload = ["./tests/testPreload.ts"]
+   ```
+
+3. `frontend/tests/testPreload.ts`:
+
+   ```typescript
+   import {registerExpoTestEnvironment} from "@terreno/test/expo/registerExpoTestEnvironment";
+
+   registerExpoTestEnvironment({expoConfig: {extra: {}, scheme: "my-app"}});
+   ```
+
+4. Render components with `renderWithTerreno` from
+   `@terreno/test/expo/renderWithTerreno` and select elements by `testID`.
+
+Mock app modules (generated SDK hooks, syncdb hooks) in a second preload file, not in test
+files: `mock.module` lasts for the whole test process ([Test isolation](../explanation/test-isolation.md)).
+
+## Web E2E (Playwright)
+
+1. `cd frontend && bun add -d @playwright/test && bunx playwright install --with-deps chromium`
+2. Run a replica-set `mongod` (the backend's sync uses change streams).
+3. Add `playwright.config.ts` with two `webServer` entries — the backend
+   (`bun run --cwd ../backend src/index.ts`, health URL `http://localhost:4000/health`) and
+   the web app (`bunx expo start --web --port 8082` with `EXPO_PUBLIC_API_URL`) — a `setup`
+   project that creates test users through the auth API, and specs in `e2e/`.
+4. Log in with a shared `loginAs(page)` helper in `test.beforeEach`, select by
+   `getByTestId`, and wait for each screen's root testID instead of sleeping.
+
+`example-frontend/playwright.config.ts` and `example-frontend/e2e/` in the Terreno repository
+are a complete example.
+
+## Mobile (Maestro)
+
+1. Set `ios.bundleIdentifier` and `android.package` in `app.json`.
+2. Build a development client on a simulator or emulator: `bunx expo run:ios`,
+   `bunx expo run:android`, or an EAS `development` build.
+3. On Android, forward Metro and the API: `adb reverse tcp:8081 tcp:8081 && adb reverse tcp:4000 tcp:4000`.
+4. Install Maestro (`curl -fsSL "https://get.maestro.mobile.dev" | bash`, Java 17).
+5. Write flows in `frontend/maestro/` that select by `id:` (the React Native `testID`) and
+   run them: `maestro test -e APP_ID=com.example.myapp maestro/`.
+
+For code that branches on `Platform.OS`, run the unit suite per platform: read the platform
+from an env var in `testPreload.ts` (`platform: process.env.TEST_PLATFORM ?? "ios"`) and add
+`"test:android": "TEST_PLATFORM=android bun test"`.
+
+## CI
+
+- Unit jobs need only `bun install`; the in-memory `mongod` runs inside the job.
+- Large suites: `terreno-test-shard --shard <i>/<n>` splits test files into balanced shards.
+- `terreno-test-hygiene --update-baseline` once, then `terreno-test-hygiene` in CI, fails on
+  new sleeps, leaked module mocks, and other flaky patterns.
+- Playwright and Maestro jobs need a replica-set `mongod` and the backend running; iOS Maestro
+  needs a macOS runner.

package/src/docs/versioned/next/how-to/show-loading-skeletons.md

@@ -0,0 +1,74 @@
+# Show loading skeletons
+
+Show placeholders in the shape of your content while it loads, instead of a spinner. Every
+container in `@terreno/ui` takes the same `loading` props. See
+[Loading states and skeletons](../reference/ui.md#loading-states-and-skeletons) for every prop
+and default.
+
+## Skeleton a Box
+
+Pass `loading` and a `loadingComponent` built from skeleton primitives:
+
+```tsx
+import {Box, SkeletonList} from "@terreno/ui";
+
+<Box loading={isLoading} loadingComponent={<SkeletonList rows={3} />} padding={4}>
+  {todos.map((todo) => <TodoRow key={todo.id} todo={todo} />)}
+</Box>
+```
+
+Without `loadingComponent`, the Box shows three lines of `SkeletonText`.
+
+## Choose an animation
+
+Set `loadingAnimation` on the container: `"pulse"` (default), `"shimmer"`, or `"none"`. Every
+skeleton inside picks it up and animates in sync.
+
+```tsx
+<Card loading={isLoading} loadingAnimation="shimmer">
+  <ProfileSummary user={user} />
+</Card>
+```
+
+Animations turn off on their own when the OS reduce-motion setting is on.
+
+## Skeleton cards, charts, and pages
+
+- `Card`, `EditableCard`: `loading` replaces the content. A display `Card` defaults to a
+  `SkeletonCard`, with media when it has `imageUri`.
+- `ChartCard`, `Scorecard`: `loading` keeps the title and replaces the body or value.
+- Charts, `Page`, `SplitPage`: `loading` still shows a spinner. Pass `loadingComponent` to show a
+  skeleton instead.
+
+```tsx
+<Page loading={isLoading} loadingComponent={<SkeletonCard showMedia />} title="Profile">
+  <ProfileScreen />
+</Page>
+```
+
+## Add loading to your own component
+
+Wrap it once with `withLoading`:
+
+```tsx
+import {SkeletonList, withLoading} from "@terreno/ui";
+
+const UserRowWithLoading = withLoading(UserRow, {loadingComponent: <SkeletonList rows={1} />});
+
+<UserRowWithLoading loading={isLoading} user={user} testID="user-row" />
+```
+
+While loading it renders a busy `Box` with test id `user-row-loading`. Use it only for a component
+that has no `loading` prop of its own.
+
+## Test it
+
+Skeletons are hidden from screen readers, so React Native Testing Library needs
+`includeHiddenElements` to find them:
+
+```tsx
+expect(getByTestId("list-skeleton", {includeHiddenElements: true})).toBeTruthy();
+expect(getByTestId("todos").props["aria-busy"]).toBe(true);
+```
+
+In Playwright, `getByTestId` finds them as usual.

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

@@ -2,6 +2,10 @@
 
 Bump every `@terreno/*` package together. Mixing versions is unsupported ([versioning policy](../explanation/versioning-policy.md)).
 
+`@terreno/cli` and `@terreno/mcp` require Bun `>=1.4.4`. Install that before upgrading those packages. Bun 1.4.0–1.4.3 is affected by CVE-2026-111497 (Brotli decoder out-of-bounds write); 1.4.4 patches the decoder. Apps scaffolded earlier should set `FROM oven/bun:1.4.4-slim` and rebuild. A `bun build --compile` binary embeds the builder's Bun and stays on the old decoder until that rebuild.
+
+EAS build profiles in this repository stay on Bun 1.3.10. That pin is part of the Expo fingerprint, so changing it forces a native rebuild. Those profiles remain on an affected Bun release until that rebuild is scheduled.
+
 ## 1. Check current versions
 
 From the app root: