@terreno/mcp 57.15.0 → 57.16.2

package/src/docs/versioned/57.15.0/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.app` |
+| `--yes` | no | off |
+
+The CLI creates `<cwd>/<appName>/`. Package source: [`create-terreno-app/`](https://github.com/TerrenoLabs/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/TerrenoLabs/terreno) and use `example-backend` / `example-frontend`. See [Getting started](../tutorials/getting-started.md#explore-the-terreno-monorepo-examples).

package/src/docs/versioned/57.15.0/how-to/debug-with-mcp.md

@@ -0,0 +1,160 @@
+# Debug a Terreno app with MCP
+
+Start the backend and frontend, reproduce the failure once, then inspect the merged runtime evidence
+instead of copying logs into the agent chat.
+
+## 1. Read the latest error
+
+Call the local MCP tool:
+
+```json
+{"name":"last_error","arguments":{"sources":["backend","browser","metro","app"]}}
+```
+
+It returns the newest error-level JSONL/CDP entry. Use `read_logs` when the failure needs surrounding
+events:
+
+```json
+{
+  "name": "read_logs",
+  "arguments": {
+    "entries": 100,
+    "level": "error",
+    "sources": ["backend", "browser", "metro", "app"]
+  }
+}
+```
+
+`backend` and `browser` read durable JSONL; `metro` and `app` read in-memory rings populated from
+Metro `/events` and CDP. Connection status in the response explains when either live source is
+unavailable.
+
+CLI equivalents:
+
+```bash
+terreno logs last-error --sources backend,browser,metro,app
+terreno logs --entries 100 --level error --sources backend,browser,metro,app
+```
+
+## 2. Inspect client state
+
+Check authentication and non-synced RTK Query cache state:
+
+```json
+{"name":"get_rtk_state","arguments":{"slice":"rtk","query":"todos"}}
+```
+
+The tool reads `globalThis.__TERRENO_STORE__` registered by the app, using CDP when the MCP process
+cannot access the app heap directly. `slice: "auth"` prefers the Better Auth slice and falls back to
+legacy JWT auth; pass `betterAuth` to request that exact slice. The CLI equivalent is:
+
+Sensitive fields whose names include `password`, `token`, `secret`, `authorization`, or `cookie` are
+returned as `[REDACTED]`; use this summary to inspect cache state, never to retrieve credentials.
+
+```bash
+terreno state --slice rtk --query todos
+```
+
+## 3. Inspect and change SyncDB state
+
+Create the app client with `debug: true`, then inspect the same state that powers
+the SyncDB debugger:
+
+```json
+{"name":"get_syncdb_state","arguments":{"collection":"todos"}}
+```
+
+The result includes entities (including tombstones, seq/stream, and pending ids),
+decoded outbox rows, conflicts, cursors, known streams, repair markers, aggregate
+status, and debugger events. Sensitive fields are returned as `[REDACTED]`.
+
+Capture state before and after reproduction, then compare it:
+
+```json
+{"name":"syncdb_snapshot","arguments":{"action":"capture"}}
+{"name":"syncdb_snapshot","arguments":{"action":"capture"}}
+{"name":"syncdb_snapshot","arguments":{"action":"compare","snapshotId":"syncdb-...-1","otherSnapshotId":"syncdb-...-2"}}
+```
+
+Snapshots live in the local MCP process. Each capture privately retains the
+TinyBase mergeable content so `mergeSnapshot` can CRDT-merge it back later
+without wiping newer local rows (later HLCs win, including deletes). `get` and
+`compare` never return that merge payload. To restore a specific captured row,
+use `setLocalEntity` from `syncdb_snapshot` `get`.
+
+State changes require an explicit local opt-in:
+
+```bash
+TERRENO_MCP_EVAL=1 bunx terreno-mcp-local
+```
+
+Then use `syncdb_action`. Normal writes should use `mutate`; `flush` drains the
+outbox, and `reconcile` catches up from server snapshots:
+
+```json
+{"name":"syncdb_action","arguments":{"action":"mutate","collection":"todos","operation":"update","id":"todo-1","data":{"completed":true}}}
+{"name":"syncdb_action","arguments":{"action":"flush"}}
+{"name":"syncdb_action","arguments":{"action":"reconcile"}}
+```
+
+Other actions are `forceResync`, `resolveConflict`, `retryFailed`, `goOffline`,
+`goOnline`, `clearDebug`, `setLocalEntity`, `deleteLocalEntity`, and
+`mergeSnapshot`. Direct local edits bypass server validation and outbox
+semantics. `mergeSnapshot` CRDT-merges the captured TinyBase content into the
+live store (later HLCs win) instead of replacing it. Capture a baseline first
+and use these only for fault injection or repair.
+
+## 4. Prove the web fix
+
+Use Bun 1.4's built-in WebView through the local `browser` tool:
+
+```json
+{"name":"browser","arguments":{"action":"open","url":"http://localhost:8082"}}
+{"name":"browser","arguments":{"action":"wait","timeout":1000}}
+{"name":"browser","arguments":{"action":"click","selector":"[data-testid=save]"}}
+{"name":"browser","arguments":{"action":"snapshot"}}
+{"name":"browser","arguments":{"action":"screenshot","output":"/opt/cursor/artifacts/save-result.png"}}
+{"name":"browser","arguments":{"action":"close"}}
+```
+
+The session persists between MCP calls. `snapshot` returns visible text and up to 200 interactive
+elements so the agent can choose selectors and verify state without image guessing. `screenshot`
+saves the viewport for the PR or walkthrough.
+WebView console output is not added to `browser.log`; call `read_logs` alongside this flow when the
+running app posts browser logs to the backend collector. The collector accepts local-loopback
+traffic before login; devices or remote browsers must send the app's normal authentication.
+
+The equivalent one-process CLI sequence is:
+
+```bash
+terreno web http://localhost:8082 \
+  --action '{"action":"click","selector":"[data-testid=save]"}' \
+  --snapshot \
+  --screenshot /opt/cursor/artifacts/save-result.png
+```
+
+## 5. Verify the native fix in the running app
+
+Navigation and arbitrary evaluation are disabled by default. Opt in only for local debugging:
+
+```bash
+TERRENO_MCP_EVAL=1 bunx terreno-mcp-local
+```
+
+Then call `navigate` with `{"path":"/profile"}` or run:
+
+```bash
+TERRENO_MCP_EVAL=1 terreno navigate /profile
+```
+
+Confirm the target screen renders, then call `last_error` again. A successful fix has no new
+error-level entry after the navigation timestamp.
+
+## Connection problems
+
+- Upgrade to Bun 1.4 or newer when `Bun.WebView requires Bun 1.4 or newer` appears.
+- Set `BUN_CHROME_PATH` if WebView cannot discover Chrome, Chromium, or Edge on Linux or Windows.
+- Set `TERRENO_PROJECT_ROOT` if logs or package versions come from the wrong directory.
+- Set `TERRENO_METRO_URL` if Metro is not on the frontend script's `--port`.
+- Close React Native DevTools when Hermes reports another debugger connection.
+- Use only `backend,browser` sources when Metro is intentionally stopped.

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

@@ -0,0 +1,119 @@
+# Deploy backend to Cloud Run
+
+Deploy a Terreno `@terreno/api` backend (for example `example-backend`) to Google Cloud Run with Secret Manager.
+
+Replace placeholders: `$PROJECT_ID`, `$REGION`, `$SERVICE_NAME`, `$REPOSITORY`.
+
+## Prerequisites
+
+- [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and authenticated
+- GCP project with billing enabled
+- MongoDB Atlas cluster (or other replica set) — [deployment baseline](../explanation/deployment-baseline.md)
+- Docker (local build) or Cloud Build
+
+Enable APIs:
+
+```bash
+gcloud services enable run.googleapis.com artifactregistry.googleapis.com secretmanager.googleapis.com --project="$PROJECT_ID"
+```
+
+## 1. Create Artifact Registry
+
+```bash
+gcloud artifacts repositories create "$REPOSITORY" \
+  --repository-format=docker \
+  --location="$REGION" \
+  --project="$PROJECT_ID"
+```
+
+## 2. Build and push the image
+
+From the **repository root** (the Dockerfile expects the monorepo context):
+
+```bash
+docker build -f example-backend/Dockerfile -t "$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME:latest" .
+docker push "$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME:latest"
+```
+
+## 3. Create secrets
+
+Create Secret Manager secrets (values added out of band):
+
+```bash
+for name in mongodb-uri token-secret token-issuer refresh-token-secret session-secret; do
+  gcloud secrets create "$SERVICE_NAME-$name" --project="$PROJECT_ID" --replication-policy=automatic
+done
+```
+
+Add secret values (example for MongoDB URI):
+
+```bash
+echo -n 'mongodb+srv://user:pass@cluster.example/terreno?retryWrites=true&w=majority' | \
+  gcloud secrets versions add "$SERVICE_NAME-mongodb-uri" --data-file=- --project="$PROJECT_ID"
+```
+
+Repeat for `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, and `SESSION_SECRET`.
+
+For Better Auth, also create `better-auth-secret` and set `AUTH_PROVIDER=better-auth` plus `BETTER_AUTH_URL` at deploy time. See [Configure Better Auth](configure-better-auth.md).
+
+## 4. Runtime service account
+
+```bash
+gcloud iam service-accounts create "$SERVICE_NAME-runtime" --project="$PROJECT_ID"
+
+gcloud projects add-iam-policy-binding "$PROJECT_ID" \
+  --member="serviceAccount:$SERVICE_NAME-runtime@$PROJECT_ID.iam.gserviceaccount.com" \
+  --role="roles/secretmanager.secretAccessor"
+```
+
+Grant object access on your uploads bucket separately if using GCS file storage.
+
+## 5. Deploy to Cloud Run
+
+```bash
+gcloud run deploy "$SERVICE_NAME" \
+  --image="$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME:latest" \
+  --region="$REGION" \
+  --project="$PROJECT_ID" \
+  --platform=managed \
+  --port=3000 \
+  --session-affinity \
+  --timeout=3600 \
+  --min-instances=1 \
+  --allow-unauthenticated \
+  --service-account="$SERVICE_NAME-runtime@$PROJECT_ID.iam.gserviceaccount.com" \
+  --set-secrets="MONGO_URI=$SERVICE_NAME-mongodb-uri:latest,TOKEN_SECRET=$SERVICE_NAME-token-secret:latest,TOKEN_ISSUER=$SERVICE_NAME-token-issuer:latest,REFRESH_TOKEN_SECRET=$SERVICE_NAME-refresh-token-secret:latest,SESSION_SECRET=$SERVICE_NAME-session-secret:latest" \
+  --set-env-vars="NODE_ENV=production"
+```
+
+Adjust `min-instances` to `0` for dev sandboxes (websockets will churn on cold start).
+
+## 6. Verify
+
+```bash
+SERVICE_URL=$(gcloud run services describe "$SERVICE_NAME" --region="$REGION" --project="$PROJECT_ID" --format='value(status.url)')
+curl -s "$SERVICE_URL/health" | jq .
+```
+
+Expect `"healthy": true`.
+
+## Production constraints
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Websockets disconnect every few requests | No session affinity on Cloud Run | Add `--session-affinity` |
+| Socket connections drop after ~5 minutes | Default request timeout (300s) | Raise `--timeout` (for example `3600`) |
+| 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 |
+
+## Related
+
+- [Deployment baseline](../explanation/deployment-baseline.md)
+- [Environment variables](../reference/environment-variables.md)
+- [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md)
+- [GCP architecture](../explanation/deployment-architecture-gcp.md)

package/src/docs/versioned/57.15.0/how-to/deploy-to-gcp.md

@@ -0,0 +1,36 @@
+# Deploy to Google Cloud Platform
+
+Deploy a Terreno full-stack app to GCP: Cloud Run for the backend, GCS + Cloud CDN for the static web export.
+
+## Before you start
+
+Read the [deployment baseline](../explanation/deployment-baseline.md) — seven requirements (replica-set MongoDB, auth secrets, build-time `EXPO_PUBLIC_API_URL`, and more) apply to every provider.
+
+## Guides
+
+| Guide | What it covers |
+|-------|----------------|
+| [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md) | Container image, Secret Manager, Cloud Run with session affinity |
+| [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) | Static web export, bucket + CDN setup, cache invalidation |
+| [Build for web](build-for-web.md) | Export command, `EXPO_PUBLIC_API_URL`, local verification |
+
+## Architecture
+
+[GCP deployment architecture](../explanation/deployment-architecture-gcp.md) — topology diagram, component roles, and tradeoffs (Cloud Run vs GKE, static vs SSR).
+
+## Scripts
+
+- [`scripts/setup-gcs-hosting.sh`](https://github.com/TerrenoLabs/terreno/blob/master/scripts/setup-gcs-hosting.sh) — parameterized GCS + CDN provisioning for one site
+
+## Environment variables
+
+[Environment variables reference](../reference/environment-variables.md) — full list of backend and client config.
+
+## Operator-specific deployment
+
+Vendor-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives outside these generalized guides. New deployments should follow the guides above with your own `$PROJECT_ID` and bucket names.
+
+## Related
+
+- [Environment variables](../reference/environment-variables.md)
+- [Deployment baseline](../explanation/deployment-baseline.md)

package/src/docs/versioned/57.15.0/how-to/deploy-web-to-gcs-cdn.md

@@ -0,0 +1,183 @@
+# Deploy web to GCS + CDN
+
+Host a static Terreno web export on Google Cloud Storage with Cloud CDN.
+
+Replace placeholders: `$PROJECT_ID`, `$REGION`, `$WEB_BUCKET`, `$SITE_NAME`, `$DOMAIN`.
+
+## Prerequisites
+
+- [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and authenticated
+- Backend deployed and CORS configured — see [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md)
+- [Build for web](build-for-web.md) completed with the correct `EXPO_PUBLIC_API_URL`
+
+## 1. Build the web bundle
+
+Set the API URL **before** export — it is inlined into the bundle:
+
+```bash
+cd example-frontend
+EXPO_PUBLIC_API_URL=https://api.example.com bun run export
+```
+
+The export script is `bun expo export --platform web` (see `example-frontend/package.json`).
+
+Output is in `dist/`.
+
+## 2. Enable the Compute Engine API
+
+Cloud CDN and its global load-balancing resources require the Compute Engine API:
+
+```bash
+gcloud services enable compute.googleapis.com --project="$PROJECT_ID"
+```
+
+## 3. Create the GCS bucket
+
+```bash
+gsutil mb -p "$PROJECT_ID" -l "$REGION" "gs://$WEB_BUCKET/"
+```
+
+## 4. Allow public object reads
+
+Cloud CDN must be able to serve the bucket's objects to unauthenticated visitors:
+
+```bash
+gsutil iam ch allUsers:objectViewer "gs://$WEB_BUCKET"
+```
+
+Do not grant `allUsers` a write role such as `objectAdmin`.
+
+## 5. Configure SPA routing
+
+Client-side routes require `index.html` for unknown paths:
+
+```bash
+gsutil web set -e index.html "gs://$WEB_BUCKET"
+```
+
+Do not set `MainPageSuffix` — GCS 301 redirects break client-side routing.
+
+## 6. Upload the build
+
+```bash
+gsutil -m -h "Cache-Control:public, max-age=31536000, immutable" \
+  rsync -r -d -x '.*\.html$' \
+  dist/ "gs://$WEB_BUCKET/"
+
+gsutil -h "Cache-Control:no-cache, no-store, must-revalidate" \
+  cp dist/index.html "gs://$WEB_BUCKET/index.html"
+```
+
+## 7. Create HTTPS CDN resources
+
+The load balancer serves the bucket over HTTPS only. A Google-managed certificate secures
+the domain:
+
+```bash
+# Backend bucket (CDN-enabled)
+gcloud compute backend-buckets create "${SITE_NAME}-backend" \
+  --gcs-bucket-name="$WEB_BUCKET" \
+  --enable-cdn \
+  --no-negative-caching \
+  --project="$PROJECT_ID"
+
+# URL map
+gcloud compute url-maps create "${SITE_NAME}-url-map" \
+  --default-backend-bucket="${SITE_NAME}-backend" \
+  --project="$PROJECT_ID"
+
+# Static IP
+gcloud compute addresses create "${SITE_NAME}-ip" --global --project="$PROJECT_ID"
+
+# Managed TLS certificate
+gcloud compute ssl-certificates create "${SITE_NAME}-cert" \
+  --domains="$DOMAIN" \
+  --global \
+  --project="$PROJECT_ID"
+
+# HTTPS proxy
+gcloud compute target-https-proxies create "${SITE_NAME}-https-proxy" \
+  --url-map="${SITE_NAME}-url-map" \
+  --ssl-certificates="${SITE_NAME}-cert" \
+  --project="$PROJECT_ID"
+
+# HTTPS forwarding rule
+gcloud compute forwarding-rules create "${SITE_NAME}-https-forwarding-rule" \
+  --address="${SITE_NAME}-ip" \
+  --target-https-proxy="${SITE_NAME}-https-proxy" \
+  --global \
+  --ports=443 \
+  --project="$PROJECT_ID"
+```
+
+## 8. Redirect HTTP to HTTPS
+
+Port 80 should redirect rather than serve the bundle. Without a listener there at all, `http://$DOMAIN` fails to connect instead of sending visitors to the secure URL.
+
+`gcloud` exposes redirect behavior only through an imported spec, not through `url-maps create` flags:
+
+```bash
+gcloud compute url-maps import "${SITE_NAME}-http-redirect-url-map" \
+  --global --project="$PROJECT_ID" --source=/dev/stdin <<SPEC
+name: ${SITE_NAME}-http-redirect-url-map
+defaultUrlRedirect:
+  httpsRedirect: true
+  redirectResponseCode: MOVED_PERMANENTLY_DEFAULT
+SPEC
+
+gcloud compute target-http-proxies create "${SITE_NAME}-http-proxy" \
+  --url-map="${SITE_NAME}-http-redirect-url-map" \
+  --project="$PROJECT_ID"
+
+gcloud compute forwarding-rules create "${SITE_NAME}-forwarding-rule" \
+  --address="${SITE_NAME}-ip" \
+  --target-http-proxy="${SITE_NAME}-http-proxy" \
+  --global \
+  --ports=80 \
+  --project="$PROJECT_ID"
+```
+
+Port 80 now only ever returns a 301; the bundle itself is served exclusively over TLS.
+
+Or run the parameterized script, which provisions steps 7 and 8 in one pass:
+
+```bash
+./scripts/setup-gcs-hosting.sh \
+  --project "$PROJECT_ID" \
+  --site-name "$SITE_NAME" \
+  --bucket "$WEB_BUCKET" \
+  --domain "$DOMAIN"
+```
+
+## 9. Point DNS and wait for the certificate
+
+```bash
+gcloud compute addresses describe "${SITE_NAME}-ip" --global \
+  --project="$PROJECT_ID" --format='value(address)'
+```
+
+Create an A record for `$DOMAIN` pointing at that IP. Managed certificates only begin provisioning once DNS resolves to the load balancer, and can take up to about an hour to become active:
+
+```bash
+gcloud compute ssl-certificates describe "${SITE_NAME}-cert" --global \
+  --project="$PROJECT_ID" --format='value(managed.status)'
+```
+
+Wait for `ACTIVE` before sending traffic. Still `PROVISIONING` after an hour usually means the A record does not resolve to the reserved IP.
+
+## 10. Invalidate cache after deploy
+
+```bash
+gcloud compute url-maps invalidate-cdn-cache "${SITE_NAME}-url-map" \
+  --path "/*" --async --project="$PROJECT_ID"
+```
+
+## Static-only path
+
+This guide hosts the `expo export -p web` output as static files. Server-rendered web (SSR, API routes) requires Expo SDK ≥ 55 — see [Web SSR and admin SPA](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md).
+
+## Related
+
+- [Build for web](build-for-web.md)
+- [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md)
+- [GCP architecture](../explanation/deployment-architecture-gcp.md)