@terreno/mcp 57.3.0 → 57.4.0

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

@@ -26,7 +26,12 @@ CircleCI `run-preview-cleanup` parameter.
    Copy Netlify and GCP values from GitHub Actions secrets/vars. Until they
    are set, CircleCI deploy jobs skip with exit 0 and GHA remains the live
    deployer.
-5. Build forked PRs if you want DCO + rulesync on forks.
+5. Set project Environment Variable `CODECOV_TOKEN` (Codecov upload token) so
+   package CI can upload `coverage/lcov.info`. Uploads skip when it is unset.
+   Mirror the same secret as GitHub Actions `CODECOV_TOKEN` for retained twins.
+   Public repos need a token unless the Codecov org disables token auth for
+   public repositories.
+6. Build forked PRs if you want DCO + rulesync on forks.
 
 GitHub App org/project slug (API and CLI):
 `circleci/6UHiK7pThPXbhnNi3umQNe/W3HZeMJujyMB2sYiUXaQbs`.
@@ -43,13 +48,18 @@ list pipelines on the slug above.
 | `.circleci/config.yml` | Setup workflow + `path-filtering` (this is the live config) |
 | `.circleci/continue-config.yml` | Real jobs/workflows gated by those params |
 
-Smoke job `config-ok` and fork-only `dco` always run on continuation.
+Fork-only `dco` and PR `architectural-pr-review` always start on continuation
+(review skips before checkout when the agentic/GitHub contexts are empty).
 `rulesync-check` runs only when generated-rule sources change (`run-rulesync`).
+`admin-backend/**` and `admin-frontend/**` start `packages-ci` (lint, compile,
+`test:coverage`). Dedicated `admin-*-ci` job definitions stay in the config as
+the same command sequence.
 
 `.circleci/**` sets `run-circleci-config`. On **config-only** PRs that workflow
-runs a representative slice (`api-ci`, `ui-ci`, `example-backend-ci`,
-`no-barrel-imports`, `source-rules`, `e2e` spec `login`). If the same pipeline
-already set `run-api`, `run-ui`, `run-e2e`, `run-example-backend`, or
+runs a representative slice (`api-ci`, `ui-ci`, `example-backend-ci`, `e2e`
+shard `auth`). `repo-policies` still starts from `run-repo-policies` (also set
+for `.circleci/**`); the kitchen-sink does not start a second copy. If the same
+pipeline already set `run-api`, `run-ui`, `run-e2e`, `run-example-backend`, or
 `run-admin-spa`, that kitchen-sink workflow is skipped so jobs are not doubled.
 `comms/**` also sets `run-example-backend` and `run-example-backend-script`,
 matching the GitHub Actions twins.
@@ -58,6 +68,76 @@ The example-backend Docker job runs only when its image recipe changes
 (`Dockerfile`, `.dockerignore`, package manifests, or `bun.lock`). API/source
 changes are covered by preview CD builds and do not start a duplicate image job.
 
+UI, RTK, and admin-frontend changes do **not** start `example-backend-ci`.
+Those packages are covered by `ui-ci` / `rtk-ci` / `packages-ci` plus e2e and
+admin-spa. `new-file-coverage` starts on package `src/` (and example app
+runtime paths including `example-frontend/components/`), not on every `*.ts`
+file in the repo (Playwright specs no longer compile the world). Package CI
+jobs that already ran `test:coverage` evaluate the 90% new-file gate against
+that LCOV (`scripts/ci/check-new-file-coverage-lcov.sh`). Retained GitHub
+Actions twins run that script with `working-directory: .` so a package-level
+`defaults.run` cwd cannot nest `{package}/coverage/lcov.info`. GHA
+`upload-codecov` steps pass `token: ${{ secrets.CODECOV_TOKEN }}`. The dedicated
+`new-file-coverage` job skips those packages and only reruns tests for
+workspaces without a coverage job in the same pipeline (example apps). Reruns
+prefer colocated `*.test.ts` files and compile `@terreno/*` dist deps only
+when the package imports them. Coverage-script unit tests run in the cheap
+`coverage-scripts` job.
+
+Playwright runs five shards after `e2e-prepare` (`auth`, `app`, `admin-core`,
+`admin-table`, `syncdb`) instead of one container per spec file. Each shard
+first checks the [affected gate](#e2e-affected-gate) and halts when no changed
+file can reach it. Repository
+policy checks share one `repo-policies` job so eight small checkouts do not
+sit in the concurrency queue. `repo-policies` uses Node 22.14 because Knip's
+oxc-parser throws `ERR_REQUIRE_ESM` on the shared 22.11 executor.
+Require `repo-policies` in branch protection. Require `e2e-auth` /
+`e2e-app` / … only as path-filtered checks; config-only PRs post `e2e-auth`
+as the smoke shard and do not run the other four. Do not require the old
+`no-barrel-imports` / `e2e-login` names.
+
+## E2E affected gate
+
+Path filters decide whether e2e is a *candidate*; `scripts/ci/e2eAffected`
+decides which shards actually run. `e2e-prepare` runs
+
+```bash
+bun run check:e2e-affected --base origin/master --write e2e-affected.json
+```
+
+and persists the decision to the workspace (also stored as the
+`e2e-affected.json` artifact). Each shard reads it and calls
+`circleci-agent step halt` before `bun install` when it is unaffected, so an
+unneeded shard costs one container start instead of a full Playwright run.
+Run the same command locally to see what a branch would trigger.
+
+`e2e-prepare` always runs when a path filter starts the workflow: compiling the
+workspace and `bun expo export`ing the web bundle is the check that catches
+build breakage the shards would otherwise miss.
+
+The gate **fails open** — it runs every shard when the base revision cannot be
+resolved, when a module cannot be resolved, or when the analysis throws. A
+change is only skipped when it is provably outside a shard's surface:
+
+| Change | Decision |
+| --- | --- |
+| Module reachable from the shard's screens, specs, or `example-backend/src` | run |
+| Module nothing reachable imports (`ui/src/Avatar.tsx` today) | skip |
+| Type-only edit to a reachable module (interfaces, `type`, `declare`) | skip |
+| New export or lazy registry entry no consumer imports | skip |
+| Re-export barrel that repoints a binding the app imports | run |
+| `bun.lock` install the app resolves changing version | run |
+| `bun.lock` or `package.json` churn outside that closure | skip |
+| Docs, rules, `demo/**`, `scripts/**`, unit tests, snapshots, lint config | skip |
+| Anything else (`metro.config.js`, `app.json`, `.circleci/**`, patches) | run |
+
+Shard membership comes from `scripts/ci/e2eAffected/shards.ts`, which must
+mirror the spec groups in `run_example_frontend_e2e`. `shards.test.ts` fails
+when the two drift, when a spec is unassigned, or when a spec navigates to a
+screen its shard does not declare. It also asserts that `ui/src/index.tsx`
+stays a pass-through barrel — runtime code there would make every
+`@terreno/ui` change look reachable.
+
 ## Automatic deploys
 
 Path filters set `run-deploy-*` and `run-cd-*`. Production jobs run only on
@@ -80,8 +160,11 @@ and skip when `NETLIFY_AUTH_TOKEN` or the site id is missing. The same skip
 applies to `gcp-cd-*` when `terreno-gcp` lacks WIF or SA emails, so GitHub
 `cd.yml` remains the live GCP writer. GitHub `terraform-preview` and
 `backend-deploy-preview` run only when
-`github.event.pull_request.head.repo.full_name == github.repository`. Fork
-PRs still present `repository: FlourishHealth/terreno` on the OIDC token, so
+`github.event.pull_request.head.repo.full_name == github.repository`.
+Terraform preview always describes the Infra Manager preview (state,
+`errorCode`, `errorLogs`) before delete, including when `previews create`
+fails. Fork PRs still present `repository: FlourishHealth/terreno` on the
+OIDC token, so
 WIF would accept them if those jobs ran. Netlify GHA jobs fail closed on
 forks (secrets withheld). After filling a context, confirm a CircleCI deploy
 URL, then set the matching GHA workflows to `on: []`. Turn off Netlify's
@@ -113,9 +196,12 @@ project, leave fork-PR secret passing off, and attach that context **only** to
 unset, and it skips fork PRs. The job checks out `origin/master` before running
 the review script so a PR cannot rewrite the reviewer.
 
-The Netlify deploy helper validates its context before building, and the docs
-target disables Docusaurus minification for preview and production builds to
-remain within the available 8 GB CircleCI executor.
+Netlify and GCP jobs **halt as the first step** when `terreno-netlify` /
+`terreno-gcp` are empty, before checkout or `bun install`. Path filters still
+start those jobs so filling the context turns deploys on without a config
+change; skip-green no longer pays for a full `large` install. Docker Layer
+Caching is off (200 credits per job). The docs Netlify target disables
+Docusaurus minification so the build stays within the 8 GB `large` executor.
 
 `terreno-gcp` uses CircleCI OIDC (`CIRCLE_OIDC_TOKEN_V2`), never a JSON service
 account key. Set `circleci_org_id`, `circleci_project_id`, and
@@ -130,39 +216,47 @@ ambient OIDC token for GCP impersonation.
 Branch protection must require the CircleCI job names below. Remove disabled
 GitHub check names or pull requests will wait for checks that can no longer run.
 
+Dedicated package jobs (`api-ci`, `ai-ci`, `rtk-ci`, `ui-ci`, `syncdb-ci`,
+`comms-ci`, `mcp-server-ci`, `admin-spa-ci`) run `bun run test:coverage`
+(`scripts/check-coverage.ts`, 95% functions and lines). Isolated `syncdb` tests
+are included by that script. Published packages without a dedicated workflow
+(`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `test`) run
+the same commands through the parameterized `packages-ci` job, gated by
+`run-admin-backend`, `run-admin-frontend`, `run-api-health`,
+`run-feature-flags`, and `run-test-package`. The retained
+`.github/workflows/packages-ci.yml` matrix twin stays `on: []`.
+
 | GHA job `name:` / workflow | CircleCI job |
 |----------------------------|--------------|
-| Repository policies / No barrel imports | `no-barrel-imports` |
-| Repository policies / Production source rules | `source-rules` |
-| Explicit any baseline | `explicit-any` |
-| License coverage | `license-coverage` |
+| Repository policies (barrels, source rules, explicit any, licenses, changelog, parity, lifecycle, static analysis) | `repo-policies` |
 | Verify rules are in sync | `rulesync-check` |
 | `dco` | `dco` |
 | Run all tests (API CI) | `api-ci` |
+| Admin backend lint, compile, coverage | `packages-ci` (`admin-backend`) |
+| Admin frontend lint, compile, coverage | `packages-ci` (`admin-frontend`) |
 | Run all tests (AI CI) | `ai-ci` |
 | RTK Lint and Build | `rtk-ci` |
 | Syncdb Lint, Build, and Tests | `syncdb-ci` |
-| UI Lint, Build, Types, and Tests | `ui-ci` |
-| Demo TypeScript Check (UI dependency) | `ui-demo-typecheck` |
-| Demo Lint and TypeScript Check | `ui-demo-ci` |
+| UI Lint, Build, Types, and Tests + demo typecheck | `ui-ci` |
+| Demo Lint and TypeScript Check | `ui-demo-ci` (demo-only PRs) |
 | Lint, compile, and test communications | `comms-ci` |
 | Lint, Build, and Test (MCP) | `mcp-server-ci` |
+| Lint, compile, and coverage (create-terreno-app) | `create-terreno-app-ci` |
 | Build Docker Image (MCP) | `mcp-server-docker` |
 | Example Frontend Lint and Test | `example-frontend-ci` |
-| Example Backend Lint, Build, and Test | `example-backend-ci` |
-| Run admin script CLI | `example-backend-script-runner` |
+| Example Backend lint/test + admin script CLI | `example-backend-ci` |
+| Run admin script CLI (when backend CI did not already run) | `example-backend-script-runner` |
 | Build backend Docker image | `example-backend-docker` |
 | Admin SPA Build and E2E | `admin-spa-ci` |
-| E2E · `<spec>` | `e2e` (matrix `spec`) |
+| Lint, compile, and coverage (matrix package) | `packages-ci` (`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `test`) |
+| E2E · `<shard>` | `e2e` (matrix `shard`: `auth`, `app`, `admin-core`, `admin-table`, `syncdb`) |
 | E2E Load · syncdb-loadlab | `e2e-load` (trigger-gated, see below) |
 | Admin SPA Backend Integration E2E | `admin-spa-integration` |
-| _(new)_ CircleCI path-filter parity | `circleci-parity` |
-| _(smoke)_ | `config-ok` |
 | _(e2e compile+export once)_ | `e2e-prepare` |
 | Architectural PR review | `architectural-pr-review` (non-blocking; skip forks / missing secrets) |
 | Maestro E2E Tests | `maestro-e2e` (`include-demo` when ui/demo Maestro flows change) |
-| Changelog fragments | `changelog-fragments` |
 | New file coverage | `new-file-coverage` |
+| Coverage gate scripts | `coverage-scripts` |
 | Netlify production | `deploy-demo`, `deploy-frontend`, `deploy-docs` |
 | Netlify PR preview | `deploy-demo-preview`, `deploy-frontend-preview`, `deploy-docs-preview` |
 | GCP production | `gcp-cd-prod` |
@@ -226,6 +320,12 @@ preview **deploys** run on open PRs from this repository; fork PRs are skipped.
 If `CIRCLE_PULL_REQUEST` is unset (GitHub App `push` pipelines), the job looks
 up the open PR for `CIRCLE_BRANCH` via the GitHub API.
 
+`mcp-server-docker` is push-only, matching GitHub Actions. It uses
+`resolve-preview-pr.sh` for that lookup and skips when a PR exists. Its
+production `bun install` passes `--ignore-scripts`: root `prepare` runs
+`simple-git-hooks`, which is a devDependency and is missing from a production
+tree.
+
 ## Path-filter parity guard
 
 `bun run check:circleci-parity` guards active GitHub/CircleCI twins. Deploy
@@ -240,15 +340,21 @@ Edits to `.circleci/config.yml` / `continue-config.yml` /
 `example-frontend/playwright.circleci.config.ts` set `run-circleci-config`.
 When no package/e2e path param is also set, that workflow runs the slice above.
 CircleCI e2e compiles the workspace and `bun expo export`s **once** in
-`e2e-prepare`, then shards attach that dist (60s test timeout, `large` Docker).
-Keeping Metro alive next to Chromium gets SIGKILL on 8GB. `xlarge` is not on
-this project's plan. Chaos e2e treats a hidden Offline banner after `goOnline`
-as reconnect — a `client.stop()`/`start()` handshake hung 30s on the static
+`e2e-prepare` (`large`, 8 GB — the export heap is 3 GB). Five shards then
+attach that dist on `medium+` (6 GB, 15 credits/min). `xlarge` is not on this project's plan. In-job
+compile+export jobs (`maestro-e2e`, `admin-spa-integration`, `e2e-load`) stay
+on `large`. Chaos e2e treats a hidden Offline banner after `goOnline` as
+reconnect — a `client.stop()`/`start()` handshake hung 30s on the static
 export. `maestro-e2e` follows the same static-export rule: it exports
 example-frontend and serves the static `dist`. If the browsers image has no
 Xvfb on `:99`, a `background: true` fallback starts one and keeps it alive
 for later steps.
 
+Package jobs that only lint/compile/test one workspace package stay on
+`medium` (including `mcp-server-ci`, `example-backend-ci`, and
+`new-file-coverage`). `coverage-scripts` is `small`. Do not put Docker Layer Caching on remote-docker jobs
+unless a profiled image build reuses layers enough to beat 200 credits/run.
+
 ## Nightly load test
 
 `e2e-load` (syncdb-loadlab) is never PR-blocking. Trigger the **setup** pipeline
@@ -266,6 +372,9 @@ This replaces the GHA cron / `workflow_dispatch` / `load-test` label triggers in
 
 ## Local validation
 
+Map every CircleCI test job to a local command with
+[run tests locally](run-tests-locally.md). Config syntax:
+
 ```bash
 circleci config validate .circleci/config.yml
 circleci config validate .circleci/continue-config.yml

package/src/docs/versioned/next/how-to/compare-chart-rendered-snapshots.md

@@ -0,0 +1,36 @@
+# Compare rendered chart snapshots
+
+JSON snapshots of the React tree do not prove chart paint. Terreno renders a gallery of
+easy-through-hard charts in the demo app and diffs those PNGs against goldens.
+
+1. Start from the repo root (reuses demo web on port 8085 if it is already up):
+
+   ```bash
+   bun run ui:charts:compare
+   ```
+
+2. Open `http://localhost:8085/demo/chart-visual-gallery` if you want to see the same
+   fixtures a person sees.
+
+3. On a mismatch, inspect:
+
+   - `demo/rendered-snapshots/<id>.png` — accepted render
+   - `demo/chart-visual-output/actual/<id>.png` — this checkout
+   - `demo/chart-visual-output/diff/<id>.png` — pixel highlight
+
+4. If the new paint is the intended design, write goldens:
+
+   ```bash
+   bun run ui:charts:update-snapshots
+   ```
+
+5. Limit one fixture while iterating:
+
+   ```bash
+   bun scripts/charts/compareRenderedSnapshots.ts --only=line-three-points
+   ```
+
+Agents reviewing a fail should follow the `review-chart-visuals` skill and look at the
+PNGs, not only the code diff.
+
+`CHART_VISUAL_BASE_URL` overrides the demo origin when the gallery is already hosted.

package/src/docs/versioned/next/how-to/configure-better-auth.md

@@ -113,6 +113,10 @@ const config: BetterAuthConfig = {
 };
 ```
 
+Throwaway in-process seed apps (CLI / container smoke tests that call Better Auth
+sign-up many times) should set `disableRateLimit: true` on that instance only.
+Better Auth enables its limiter in production, which 429s the fourth seeded user.
+
 ### 3. Register BetterAuthApp Plugin
 
 Use the TerrenoApp plugin system:

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

@@ -0,0 +1,154 @@
+# Create a Terreno app
+
+Scaffold a deployable full-stack Terreno app (backend, Expo frontend, seed script, consumer `Dockerfile`, CI, MCP config) with one non-interactive command.
+
+The CLI writes files only — it does not run `bun install`, start MongoDB, or seed data.
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) (or Node/npm for `npm create`)
+- An empty target directory (see [Non-empty targets](#non-empty-targets))
+- MongoDB as a **replica set** before running the backend (see [Start MongoDB](#3-start-mongodb-replica-set))
+
+## 1. Scaffold the app
+
+From the parent directory where you want `<appName>/`:
+
+```bash
+bunx create-terreno-app my-app --display-name "My App"
+```
+
+npm alternative (note the `--` before flags):
+
+```bash
+npm create terreno-app my-app -- --display-name "My App"
+```
+
+Derive the display name from `appName` when you do not need a custom title:
+
+```bash
+bunx create-terreno-app my-app --yes
+```
+
+Optional flags:
+
+| Flag | Required | Default |
+| --- | --- | --- |
+| `appName` (positional) | yes | — kebab-case directory and package name (`^[a-z][a-z0-9-]*$`) |
+| `--display-name` | unless `--yes` | derived from `appName` when `--yes` |
+| `--description` | no | empty |
+| `--mcp-server-url` | no | `https://mcp.terreno.flourish.health` |
+| `--yes` | no | off |
+
+The CLI creates `<cwd>/<appName>/`. Package source: [`create-terreno-app/`](https://github.com/FlourishHealth/terreno/tree/master/create-terreno-app) in the Terreno monorepo.
+
+## Non-empty targets
+
+The CLI refuses to write when the target already contains anything other than `.git` or `.gitignore`. It exits non-zero and leaves existing files unchanged.
+
+Initializing git first is fine:
+
+```bash
+mkdir my-app && cd my-app && git init
+cd .. && bunx create-terreno-app my-app --yes
+```
+
+## Generated layout
+
+| Path | Purpose |
+| --- | --- |
+| `backend/` | Express/Mongoose API (`@terreno/api`, Better Auth, admin, sync) |
+| `frontend/` | Expo universal app (`@terreno/ui`, `@terreno/syncdb`, `@terreno/rtk`) |
+| `Dockerfile` | Consumer backend image (`backend/` only — not the Terreno monorepo) |
+| `.dockerignore` | Excludes local env secrets, dependencies, and build output from the image context |
+| `backend/.env`, `frontend/.env` | Gitignored local-dev defaults (written on scaffold) |
+| `backend/.env.example`, `frontend/.env.example` | Committed templates for production and export |
+| `.github/workflows/` | Backend and frontend CI |
+| `.cursor/mcp.json`, `.cursorrules`, `CLAUDE.md` | Agent tooling |
+| `README.md` | App-specific next steps and deploy links |
+
+Generated `@terreno/*` dependencies pin to `^<create-terreno-app version>` at scaffold time.
+
+## 2. Install dependencies
+
+```bash
+cd my-app
+(cd backend && bun install)
+(cd frontend && bun install)
+```
+
+## 3. Start MongoDB (replica set)
+
+Sync and realtime require a replica set (even a single-node dev set). See the [deployment baseline](../explanation/deployment-baseline.md).
+
+From the generated app root, run this local single-node example after `mongod` is available:
+
+```bash
+mkdir -p .devdata/mongo
+mongod --replSet rs0 --port 27017 --bind_ip 127.0.0.1 --dbpath .devdata/mongo &
+# Initiate once (use node for the driver command if bun errors on bson):
+node -e 'import("mongodb").then(async ({MongoClient})=>{const c=new MongoClient("mongodb://127.0.0.1:27017/?directConnection=true");await c.connect();await c.db("admin").command({replSetInitiate:{_id:"rs0",members:[{_id:0,host:"127.0.0.1:27017"}]}}).catch(()=>{});await c.close();})'
+```
+
+The scaffold sets `MONGO_URI` in `backend/.env` to `mongodb://127.0.0.1:27017/<app_name>?replicaSet=rs0` (hyphens in `appName` become underscores in the database name). Copy from `backend/.env.example` when you need production values.
+
+## 4. Seed login users
+
+With MongoDB running as a replica set:
+
+```bash
+(cd backend && bun run seed)
+```
+
+Creates:
+
+| Email | Password | Notes |
+| --- | --- | --- |
+| `test@example.com` | `testpassword123` | Standard user |
+| `admin@example.com` | `testpassword123` | Admin user |
+
+Seed behavior and flags: [Seed a database](seed-a-database.md). Better Auth setup: [Configure Better Auth](configure-better-auth.md).
+
+## 5. Run the stack
+
+Terminal 1 — API (default port `4000`):
+
+```bash
+(cd backend && bun run dev)
+```
+
+Health check: `curl http://localhost:4000/health` → `"healthy":true`.
+
+Terminal 2 — web UI (port `8082`):
+
+```bash
+(cd frontend && bun run sdk)   # after backend is up; regenerates OpenAPI hooks
+(cd frontend && bun run web)
+```
+
+Open `http://localhost:8082` and sign in as `test@example.com` / `testpassword123`.
+
+`frontend/.env` defaults `EXPO_PUBLIC_API_URL` to `http://localhost:4000`. For production web builds, set it **before** export — see [Build for web](build-for-web.md).
+
+## Deploy
+
+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.
+
+```bash
+docker build -t my-app-backend .
+docker run --rm -p 8080:8080 \
+  -e MONGO_URI='mongodb+srv://...' \
+  -e BETTER_AUTH_SECRET='...' \
+  -e BETTER_AUTH_URL='https://api.example.com' \
+  my-app-backend
+```
+
+Cloud Run concepts and commands: [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md). That guide targets Terreno's monorepo example; for a generated app, keep the root `Dockerfile`, port `8080`, and Better Auth variables shown here. The generated backend throws if `BETTER_AUTH_SECRET` is unset. `GET /users` list and read require an admin.
+
+**Frontend:** [Build for web](build-for-web.md) — set `EXPO_PUBLIC_API_URL` at export time.
+
+## Monorepo examples (secondary)
+
+To explore Terreno itself without scaffolding a new app, clone the [Terreno monorepo](https://github.com/FlourishHealth/terreno) and use `example-backend` / `example-frontend`. See [Getting started](../tutorials/getting-started.md#explore-the-terreno-monorepo-examples).

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

@@ -106,6 +106,8 @@ Expect `"healthy": true`.
 | Live feature flags / realtime never update; log mentions replica set | MongoDB is standalone, not a replica set | Use Atlas or `replSet` — change streams required (`feature-flags/src/featureFlagsApp.ts`) |
 | Bun-compiled container never opens its port while creating indexes | OpenTelemetry Mongoose instrumentation patched an already-loaded Mongoose module | Do not explicitly patch Mongoose in the compiled binary; retain HTTP/Express tracing |
 | Container hangs before listening when cloud logging initializes | A network logging transport blocks startup | Log to stdout/stderr during boot; Cloud Run ingests both streams |
+| `gcloud run deploy --tag` fails citing an old revision that never became Ready | That tag still points at the failed revision; `--remove-tags` keeps it in the traffic spec | Rebuild traffic with `--to-revisions=<live>=100` plus `--set-tags` of Ready tags only, deploy `--no-traffic` without `--tag`, then `--update-tags` the new revision |
+| A zero-traffic preview tag returns `503` with `{"status":"starting"}` indefinitely | The early TCP listener satisfies Cloud Run's startup probe before Mongo and seed work finish; request-only CPU then starves idle boot work | Deploy preview revisions with `--no-cpu-throttling`, then poll the tagged `/health` URL for `"healthy":true` before reporting deployment success |
 | First request after idle is slow; sockets reconnect constantly | Scaled to zero | Set `--min-instances=1` for user-facing services |
 | Browser API calls blocked by CORS | `corsOrigin` / Better Auth `trustedOrigins` missing web origin | Add your CDN URL to backend CORS and auth config |
 

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

@@ -33,8 +33,9 @@ PR deploy preview.
 | `fingerprint-gate` | Master iOS/Android hashes cached per `pull_request.base.sha` (skips a second `bun run compile`) |
 | `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` backend preview | Runs the built container against the configured Secret Manager values and requires a healthy `/health` response before pushing or deploying. |
+| `cd` 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 caches `~/.bun/install/cache` without `github.ref` in the key |
 
-Playwright e2e still uses one shard per spec file so required check names stay
-`E2E · <spec>`.
+Playwright e2e on CircleCI groups specs into five shards (`e2e-auth`,
+`e2e-app`, `e2e-admin-core`, `e2e-admin-table`, `e2e-syncdb`). The retained GHA
+twin still lists one spec per matrix entry for rollback.

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

@@ -52,20 +52,24 @@ PR.
 
 ## Unattended pickup
 
-1. After triage, apply `status:ready-for-dev` only when Acceptance is roastable and
-   the work fits one Pick comment (at most five tasks). Leave the issue unassigned.
-   Do not edit the issue body after you label it unless you are a maintainer; the
-   skill aborts if an untrusted author changes the body after the label.
+1. After triage, apply `status:ready-for-dev` and leave the issue unassigned.
+   Do not edit the issue body after you label it unless you are a maintainer; pickup
+   aborts if an untrusted author changes the body after the label.
 2. A Cursor Automation (or `/implement-ready-for-dev`) claims the oldest matching
    issue: assignee + `status:in-progress`, remove `status:ready-for-dev`. It skips
    issues that already have an open linked or closing PR (GraphQL references, not
    `linked:<number>`).
-3. It posts `<!-- terreno-pick-plan -->` from that trusted snapshot, Pick ⇄ Roasts
-   that comment, then Brews a **draft** PR with `Fixes #<n>`.
+3. It runs Grow on that trusted snapshot, answers Grow questions from the repo and
+   issue (assumptions posted on the issue), and only stops on GitHub for a genuine
+   human gate (product, security, data ownership, public API, destructive change,
+   rollout, or scope the issue and docs do not settle). Then Pick ⇄ Roast, Brew, and
+   Taste until the PR is mergeable (ready for review). Do not merge.
 4. Dashboard paste: [`implement-ready-for-dev` automation](../../.rulesync/skills/implement-ready-for-dev/references/cursor-automation.md).
 
-Do not apply `status:ready-for-dev` to issues that still need a product decision.
-Those stay `status:needs-info` or go through `/work-github-issues`.
+Do not apply `status:ready-for-dev` to issues that still need a product, security, or
+data-ownership decision. Those stay `status:needs-info` or go through `/work-github-issues`.
+The unattended skill will assume implementation defaults; it will not invent those
+decisions.
 
 Labels live in [`.github/labels.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/labels.yml).
 Sync them with the existing roadmap labels workflow before expecting pickup.