@terreno/mcp 56.0.0-beta.0 → 57.0.0-beta.1

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

@@ -2,6 +2,14 @@
 
 Problem-oriented, practical steps. Use these when you know what you want to do.
 
+## Deployment
+
+- [Deployment baseline](../explanation/deployment-baseline.md) — seven requirements every host must satisfy
+- [Build for web](build-for-web.md) — export static web bundle with correct API URL
+- [Deploy to Google Cloud Platform](deploy-to-gcp.md) — index for GCP guides
+- [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md) — container + Secret Manager + Cloud Run
+- [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) — static hosting with SPA routing
+
 ## Contents
 
 - [Create a Mongoose model](create-a-model.md) — Define models with proper conventions

package/src/docs/versioned/next/how-to/build-for-web.md

@@ -0,0 +1,69 @@
+# Build for web
+
+Export your Terreno Expo app as static files for hosting on GCS, Netlify, or any CDN.
+
+See the [deployment baseline](../explanation/deployment-baseline.md) for requirements that apply to every host.
+
+## Prerequisites
+
+- Backend running and reachable from browsers (CORS configured).
+- MongoDB replica set for realtime features (see baseline).
+
+## 1. Set the API URL at build time
+
+`EXPO_PUBLIC_API_URL` is **inlined into the JavaScript bundle** during export. Setting it on the hosting platform after deploy does nothing.
+
+```bash
+cd example-frontend
+EXPO_PUBLIC_API_URL=https://api.example.com bun run export
+```
+
+The export script in `example-frontend/package.json` is:
+
+```bash
+bun expo export --platform web
+```
+
+### Alternative: `app.json` `extra.BASE_URL`
+
+`@terreno/rtk` resolves the API base from `expo-constants` `extra.BASE_URL` and `EXPO_PUBLIC_API_URL` (see `rtk/src/constants.ts` `resolveBaseUrls`). Priority in **production** builds:
+
+1. `EXPO_PUBLIC_API_URL` environment variable (set before export)
+2. `extra.BASE_URL` in app config (when env var is unset)
+3. Development fallbacks (hostUri, experience URL, localhost) — only in `__DEV__`
+
+For production, prefer `EXPO_PUBLIC_API_URL` so CI and local builds behave the same.
+
+## 2. Run the export
+
+```bash
+EXPO_PUBLIC_API_URL=https://api.example.com bun run export
+```
+
+Output lands in `dist/` (Expo default for web export). Contents depend on the configured web `output` mode — today Terreno apps use the `single` SPA mode (one `index.html`).
+
+## 3. Verify locally before uploading
+
+Serve the `dist/` folder with any static server and confirm API calls hit your backend:
+
+```bash
+npx serve dist -p 4173
+```
+
+Open `http://localhost:4173`, log in, and check the network tab — requests must go to your `EXPO_PUBLIC_API_URL`, not `localhost`.
+
+## 4. Deploy the static files
+
+Upload `dist/` to your host. **Client-side routing** requires the host to serve `index.html` for unknown paths (SPA fallback):
+
+| Host | Configuration |
+|------|---------------|
+| GCS + CDN | `notFoundPage=index.html` on the bucket — see [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) |
+| Netlify | `_redirects` or `netlify.toml` `/* /index.html 200` |
+
+## Provider guides
+
+- [Deploy to GCP](deploy-to-gcp.md) — GCS + Cloud CDN (static web) + Cloud Run (backend)
+- Deployment baseline — [seven requirements](../explanation/deployment-baseline.md)
+
+For server-rendered web (future), see [Web SSR and admin SPA](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md).

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

@@ -0,0 +1,115 @@
+# 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`) |
+| 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/next/how-to/deploy-to-gcp.md

@@ -1,244 +1,36 @@
 # Deploy to Google Cloud Platform
 
-Learn how to deploy the Terreno demo and example-frontend apps to Google Cloud Storage with CDN-backed hosting.
+Deploy a Terreno full-stack app to GCP: Cloud Run for the backend, GCS + Cloud CDN for the static web export.
 
-## Prerequisites
+## Before you start
 
-Before you begin, ensure you have:
+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.
 
-- **GCP Project**: A Google Cloud Platform project with billing enabled
-- **gcloud CLI**: [Installed and authenticated](https://cloud.google.com/sdk/docs/install)
-- **Permissions**: Your GCP user or service account needs:
-  - `roles/storage.admin` (create buckets, set IAM)
-  - `roles/compute.loadBalancerAdmin` (create backend buckets, URL maps)
-  - `roles/compute.networkAdmin` (create IPs, proxies, forwarding rules)
-- **GitHub Repository Access**: Admin access to configure secrets
+## Guides
 
-## Initial Infrastructure Setup
+| 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 |
 
-Run the setup script once to provision all GCP resources:
+## Architecture
 
-``````bash
-# Clone the repository
-git clone https://github.com/FlourishHealth/terreno.git
-cd terreno
+[GCP deployment architecture](../explanation/deployment-architecture-gcp.md) — topology diagram, component roles, and tradeoffs (Cloud Run vs GKE, static vs SSR).
 
-# Run the setup script
-./scripts/setup-gcs-hosting.sh
-``````
+## Scripts
 
-The script will prompt you for your service account email if `GCP_SA_KEY` is not set. It will create:
+- [`scripts/setup-gcs-hosting.sh`](https://github.com/FlourishHealth/terreno/blob/master/scripts/setup-gcs-hosting.sh) — parameterized GCS + CDN provisioning for one site
 
-1. **GCS Buckets**: `flourish-terreno-terreno-demo` and `flourish-terreno-terreno-frontend-example`
-2. **Public Access**: Configured with `allUsers:objectViewer`
-3. **SPA Routing**: `notFoundPage=index.html` for client-side routing
-4. **CDN Resources**:
-   - Backend buckets (CDN-enabled)
-   - URL maps
-   - Static IP addresses
-   - HTTP proxies
-   - Forwarding rules
+## Environment variables
 
-### Script Output
+[Environment variables reference](../reference/environment-variables.md) — full list of backend and client config.
 
-At the end, the script outputs:
+## Legacy Flourish deployment
 
-``````
-=== Setup Complete ===
+Flourish-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives in `infra/flourish/` and the existing `demo-deploy.yml` / `frontend-example-deploy.yml` workflows. New deployments should follow the generalized guides above with your own `$PROJECT_ID` and bucket names.
 
-Demo:
-  CDN IP: 34.120.xxx.xxx
-  URL: http://34.120.xxx.xxx/
-  (Point your DNS A record to this IP)
+## Related
 
-Frontend Example:
-  CDN IP: 34.149.xxx.xxx
-  URL: http://34.149.xxx.xxx/
-  (Point your DNS A record to this IP)
-``````
-
-## Configure GitHub Secrets
-
-Add the following secret to your GitHub repository:
-
-### GCP_SA_KEY
-
-1. Create a service account key:
-   ``````bash
-   # Create service account
-   gcloud iam service-accounts create terreno-deploy \
-     --display-name="Terreno Deploy"
-
-   # Grant permissions
-   gcloud projects add-iam-policy-binding flourish-terreno \
-     --member="serviceAccount:terreno-deploy@flourish-terreno.iam.gserviceaccount.com" \
-     --role="roles/storage.objectAdmin"
-
-   gcloud projects add-iam-policy-binding flourish-terreno \
-     --member="serviceAccount:terreno-deploy@flourish-terreno.iam.gserviceaccount.com" \
-     --role="roles/compute.loadBalancerAdmin"
-
-   # Create JSON key
-   gcloud iam service-accounts keys create key.json \
-     --iam-account=terreno-deploy@flourish-terreno.iam.gserviceaccount.com
-   ``````
-
-2. Add the key to GitHub:
-   - Go to **Settings** → **Secrets and variables** → **Actions**
-   - Click **New repository secret**
-   - Name: `GCP_SA_KEY`
-   - Value: Paste the entire contents of `key.json`
-   - Click **Add secret**
-
-3. Delete the local key file:
-   ``````bash
-   rm key.json
-   ``````
-
-## Deploy to Production
-
-Production deployments happen automatically when you push to the `master` branch:
-
-``````bash
-# Make changes to demo or example-frontend
-git checkout master
-git pull
-# ... make changes ...
-git add .
-git commit -m "Update demo UI"
-git push origin master
-``````
-
-The workflows will:
-1. Build the app with Bun and Expo
-2. Upload the build artifact
-3. Sync assets to GCS with cache headers:
-   - Hashed assets: `Cache-Control: public, max-age=31536000, immutable`
-   - `index.html`: `Cache-Control: no-cache, no-store, must-revalidate`
-4. Invalidate the CDN cache
-
-### Triggered Workflows
-
-| App | Workflow | Triggers on paths |
-|-----|----------|-------------------|
-| Demo | `demo-deploy.yml` | `demo/**`, `ui/**` |
-| Example Frontend | `frontend-example-deploy.yml` | `example-frontend/**`, `ui/**`, `rtk/**` |
-
-## Deploy PR Previews
-
-Pull request previews deploy automatically when you open a PR that modifies the relevant paths:
-
-``````bash
-# Create a feature branch
-git checkout -b feature/new-component
-
-# Make changes
-# ... edit files ...
-
-git add .
-git commit -m "Add new component"
-git push origin feature/new-component
-
-# Open a pull request on GitHub
-``````
-
-The workflow will:
-1. Build the app with a preview-specific `baseUrl`
-2. Deploy to `gs://BUCKET/_previews/pr-{number}/`
-3. Create GitHub deployment with a preview URL
-4. Comment on the PR with the preview link
-
-### Preview URLs
-
-Previews are accessible at:
-- **Demo**: `http://{CDN_IP}/_previews/pr-{number}/` (or `https://storage.googleapis.com/flourish-terreno-terreno-demo/_previews/pr-{number}/` if CDN is not configured)
-- **Example Frontend**: `http://{CDN_IP}/_previews/pr-{number}/` (or `https://storage.googleapis.com/flourish-terreno-terreno-frontend-example/_previews/pr-{number}/`)
-
-### Preview Cleanup
-
-When you close or merge a PR, the `preview-cleanup.yml` workflow automatically:
-- Deletes preview files from both buckets
-- Deactivates GitHub deployments
-
-## Manual Deployment
-
-To deploy manually without GitHub Actions:
-
-``````bash
-# Demo
-cd demo
-bun install
-bun run compile
-bun run export
-gsutil -m -h "Cache-Control:public, max-age=31536000, immutable" \
-  rsync -r -d -x '.*\.html$' \
-  dist/ gs://flourish-terreno-terreno-demo/
-gsutil -h "Cache-Control:no-cache, no-store, must-revalidate" \
-  cp dist/index.html gs://flourish-terreno-terreno-demo/index.html
-
-# Invalidate CDN
-gcloud compute url-maps invalidate-cdn-cache terreno-demo-url-map \
-  --path "/*" --async
-
-# Example Frontend
-cd example-frontend
-bun install
-bun run compile
-bun run export
-gsutil -m -h "Cache-Control:public, max-age=31536000, immutable" \
-  rsync -r -d -x '.*\.html$' \
-  dist/ gs://flourish-terreno-terreno-frontend-example/
-gsutil -h "Cache-Control:no-cache, no-store, must-revalidate" \
-  cp dist/index.html gs://flourish-terreno-terreno-frontend-example/index.html
-
-# Invalidate CDN
-gcloud compute url-maps invalidate-cdn-cache terreno-frontend-example-url-map \
-  --path "/*" --async
-``````
-
-## Troubleshooting
-
-### Build Fails with "Module not found"
-
-**Problem**: Workspace dependencies not compiled.
-
-**Solution**: Run `bun run compile` in `ui/` and `rtk/` before building the app.
-
-### Preview URL Returns 404
-
-**Problem**: CDN's `notFoundPage` serves root `index.html`, not the preview's.
-
-**Solution**: The deploy workflow uploads "bare" route objects. Check that the workflow completed successfully.
-
-### CDN Shows Stale Content
-
-**Problem**: CDN cache not invalidated.
-
-**Solution**: Run cache invalidation manually:
-``````bash
-gcloud compute url-maps invalidate-cdn-cache URLMAP_NAME --path "/*" --async
-``````
-
-### Permission Denied on gsutil
-
-**Problem**: Service account lacks permissions.
-
-**Solution**: Grant `roles/storage.objectAdmin`:
-``````bash
-gsutil iam ch "serviceAccount:SA_EMAIL:objectAdmin" gs://BUCKET_NAME
-``````
-
-### SPA Routes Return 404 on Refresh
-
-**Problem**: Bucket not configured with `notFoundPage`.
-
-**Solution**: Run the setup script or manually configure:
-``````bash
-gsutil web set -e index.html gs://BUCKET_NAME
-``````
-
-## Next Steps
-
-- [GCP Hosting Architecture](../explanation/gcp-hosting-architecture.md) — Understand the design
-- [Environment Variables Reference](../reference/environment-variables.md) — Configure runtime settings
-- [Set up CI/CD pipelines](../how-to/README.md) — Automate testing and deployment
+- [Environment variables](../reference/environment-variables.md)
+- [Deployment baseline](../explanation/deployment-baseline.md)

package/src/docs/versioned/next/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/FlourishHealth/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)