@terreno/mcp 0.31.0 → 56.0.0-beta.0

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

@@ -1,69 +0,0 @@
-# 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

@@ -1,115 +0,0 @@
-# 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-web-to-gcs-cdn.md

@@ -1,183 +0,0 @@
-# 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)

package/src/docs/versioned/next/implementationPlans/b2b-platform-program.md

@@ -1,114 +0,0 @@
-# Program: B2B platform
-
-**Status:** Draft — roadmap items drafted; decisions D1–D7 resolved 2026-08-09; first nine IPs open
-**Owner:** unassigned
-**Created:** 2026-08-09
-
-Umbrella plan coordinating the IPs that take Terreno from a single-tenant, per-user
-full-stack kit to a framework you can spin up a B2B SaaS app with in hours. Pairs with the
-roadmap items in
-[roadmap-seed-issues.md](../explanation/roadmap-seed-issues.md) (B2B platform program
-section).
-
-## Goal
-
-A freshly scaffolded, deployed Terreno app supports the B2B critical path out of the box:
-**sign up → create an organization → invite a teammate → pick a plan → get an email.**
-Today zero of those five steps are possible without custom code.
-
-## Background
-
-A capability audit (2026-08-08) found Terreno strong as a single-tenant CRUD + auth +
-realtime + admin + AI kit, with three structural gaps for B2B SaaS: **tenancy** (no
-orgs/teams/memberships), **money** (no billing), and **communication** (no email, SMS, or
-push delivery — `expo-server-sdk` is an unused dependency and the RTK client's
-`resetPassword` endpoint has no backend implementation). Supporting gaps: no invitations,
-no durable jobs, no inbound-webhook framework, no rate limiting, no framework-level audit
-log, no enterprise SSO/MFA, and missing B2B UI surfaces (server-filtered data grid, charts,
-org switcher, dark mode).
-
-## Tracks
-
-| Track | Theme | IPs / roadmap items |
-|---|---|---|
-| A | Tenancy & access | `orgs-and-teams`, `rbac-permissions` (existing draft), `invitations-and-seats`, `org-management-ui` |
-| C | Communications (pluggable) | `comms-abstraction`, one item **per adapter**: `comms-adapter-expo-push` (first push adapter, per D4), `comms-adapter-twilio-sms`, `comms-adapter-twilio-verify`, `comms-adapter-sendgrid` (first mail adapter, per D2); consumers: `password-reset-and-email-verification`, `notification-center` |
-| B | Billing | `inbound-webhooks`, `billing-stripe` (web-first, per D1), `mobile-iap-revenuecat` (Future) |
-| D | Zero-to-deployed DX | `create-terreno-app`, `mongo-migrations` (deploy items already exist in the OSS launch program) |
-| E | B2B UI surfaces | `data-grid-server-filters`, `charts-and-dashboards`, `dark-mode-theme`, `command-palette`, `wizard-stepper`, `wysiwyg-editor` (markdown stays for now, per D3), `global-search` |
-| F | Enterprise & scale | `framework-audit-log` (Next), `rate-limiting` (Next), `job-queues` (Next), `enterprise-sso`, `mfa-step-up-auth` |
-| — | Native baseline | `native-module-baseline` — all new native modules land in one major release |
-
-## Sequencing
-
-1. **Foundations first:** `comms-abstraction` and `orgs-and-teams` are independent and both
-   unblock most of the program. `inbound-webhooks` lands before billing and before comms
-   delivery callbacks.
-2. **Close the auth hole early:** `password-reset-and-email-verification` ships as soon as
-   the abstraction plus one mail adapter exist — the client already calls `POST
-   /resetPassword`.
-3. **Billing after orgs + webhooks.**
-4. **Native baseline rides the next major release** so every later feature ships as
-   JS/OTA against the same binary.
-5. Track E/F items are independent and can be scheduled opportunistically.
-
-## Native module baseline (next major release)
-
-Adding a native module to `@terreno/ui` or the example apps forces consumers to cut a new
-dev-client/store build, so all additions land together in the next major:
-
-| Package | Enables | Notes |
-|---|---|---|
-| `@stripe/stripe-react-native` | Billing (payment sheet, Apple/Google Pay) | Config plugin; Kotlin 2.x + compileSdk 36 via `expo-build-properties` |
-| `react-native-purchases` (+ `-ui`) | Mobile IAP (RevenueCat) | Feature ships later (D1: Stripe web-first) — SDK included now so IAP lands without another major |
-| `expo-device` | Push registration guards | trivial |
-| `expo-crypto` | PKCE for SSO, invite tokens | trivial |
-| `expo-local-authentication` | Biometric step-up (MFA) | `NSFaceIDUsageDescription` |
-| `expo-system-ui` | Dark mode root/system chrome | trivial |
-| `react-native-otp-verify` | Android SMS OTP autofill | Included (D7) for the Twilio Verify flows |
-
-Excluded by decision: `@10play/tentap-editor` (D3 — markdown stays; revisit in a later
-major if WYSIWYG is adopted).
-
-Already linked, no action: skia, reanimated, gesture-handler, svg, webview,
-expo-notifications, expo-secure-store, expo-document-picker/image-picker, blur,
-permissions, expo-network. Charts (`victory-native`) is JS-only on existing peers.
-
-## Decision log
-
-All decisions resolved by the maintainer on 2026-08-09:
-
-| # | Decision | Resolution |
-|---|---|---|
-| D1 | Billing vendor strategy | **Stripe web-first.** RevenueCat mobile IAP stays `Future`; `react-native-purchases` still ships in the native baseline |
-| D2 | First mail adapter | **SendGrid (Twilio SendGrid)** — pairs with the Twilio SMS/Verify credentials story; other providers get items when demand appears |
-| D3 | WYSIWYG editor | **Markdown-only for now.** TenTap excluded from the native baseline; revisit in a later major |
-| D4 | First push adapter | **Expo push.** |
-| D5 | Targets | **Twilio push adapter dropped entirely** (item removed). Promoted to `Next`: `notification-center`, `framework-audit-log`, `rate-limiting`, `job-queues`. Everything else stays as drafted |
-| D6 | Orgs data model | **Native Terreno Mongoose models** (works for JWT + Better Auth), optional Better Auth sync later |
-| D7 | Final native manifest | **Confirmed:** six core packages + `react-native-purchases` + `react-native-otp-verify`; no TenTap |
-
-## IPs in this program
-
-| IP | Status | Tasks |
-|---|---|---|
-| [comms-abstraction](comms-abstraction.md) | Draft | [tasks](../tasks/comms-abstraction.md) |
-| [comms-adapter-expo-push](comms-adapter-expo-push.md) | Draft | [tasks](../tasks/comms-adapter-expo-push.md) |
-| [comms-adapter-twilio-sms](comms-adapter-twilio-sms.md) | Draft | [tasks](../tasks/comms-adapter-twilio-sms.md) |
-| [comms-adapter-twilio-verify](comms-adapter-twilio-verify.md) | Draft | [tasks](../tasks/comms-adapter-twilio-verify.md) |
-| [comms-adapter-sendgrid](comms-adapter-sendgrid.md) | Draft | [tasks](../tasks/comms-adapter-sendgrid.md) |
-| [password-reset-and-email-verification](password-reset-and-email-verification.md) | Draft | [tasks](../tasks/password-reset-and-email-verification.md) |
-| [orgs-and-teams](orgs-and-teams.md) | Draft | [tasks](../tasks/orgs-and-teams.md) |
-| [billing-stripe](billing-stripe.md) | Draft | [tasks](../tasks/billing-stripe.md) |
-| [native-module-baseline](native-module-baseline.md) | Draft | [tasks](../tasks/native-module-baseline.md) |
-| [rbac-permissions](rbac-permissions.md) | Draft (pre-existing API design) | TBD |
-
-Remaining items (`inbound-webhooks`, `invitations-and-seats`, `org-management-ui`,
-`notification-center`, `framework-audit-log`, `rate-limiting`, `job-queues`, …) get IPs as
-they approach the top of the queue.
-
-## Not Included
-
-- Deploy guides and deployment foundation (OSS launch program).
-- `@terreno/syncdb` migration work (PR #869 track).
-- Marketing/positioning for the B2B pitch.

package/src/docs/versioned/next/implementationPlans/billing-stripe.md

@@ -1,158 +0,0 @@
-# Implementation Plan: Stripe billing and subscriptions
-
-**Status:** Draft
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1025
-**Priority:** High
-**Effort:** Epic
-**Owner:** unassigned
-**Created:** 2026-08-09
-**Program:** [B2B platform](b2b-platform-program.md)
-**Depends on:** [orgs-and-teams](orgs-and-teams.md), inbound-webhooks (IP pending — hard dependency for Phase 3)
-**RTK deprecation flag:** None for the backend; the two screens in Phase 4 follow whatever
-data layer example-frontend uses at that time
-
-## Goal
-
-Terreno has no way to charge customers. This IP adds `@terreno/billing`, a Stripe-backed
-(decision D1: web-first) billing plugin: Stripe customers mapped to organizations,
-code-defined plans mapped to Stripe prices, Checkout and Billing Portal session routes,
-webhook-driven subscription/entitlement sync, and plan gating that plugs into the existing
-feature-flag layer — so `plan: "pro"` can gate features the same way segments do today.
-
-## Non-Goals
-
-- Mobile in-app purchases (`mobile-iap-revenuecat`, Future — the RevenueCat SDK ships in
-  the native baseline so it can land without another major).
-- Usage-based/metered billing, invoicing customization, tax configuration (Stripe Tax is
-  configured in Stripe, not by Terreno).
-- Payment methods beyond what Stripe Checkout/Portal handle.
-- Seat-count enforcement (lands with `invitations-and-seats` integration, Phase 5/future).
-
-## Decisions
-
-| Question | Decision |
-|----------|----------|
-| Package | New workspace package `@terreno/billing` with `stripe` as a real dependency (vendor-specific by design per D1; a provider abstraction is not warranted for one vendor) |
-| Billing subject | The **organization** (B2B); optional `subject: "user"` mode for consumer apps |
-| Plan definition | Code-defined `plans: [{id, name, stripePriceId, features: string[]}]` passed to `BillingApp` — plans are reviewed code, prices live in Stripe |
-| Checkout UX | Stripe-hosted Checkout + Billing Portal (web-first per D1); no custom card forms; `@stripe/stripe-react-native` payment sheet arrives with the IAP item if ever needed |
-| Source of truth | Stripe is authoritative; local `BillingSubscription` is a webhook-synced cache — no entitlement decision ever calls Stripe inline |
-| Entitlements | `getEntitlements(orgId)` service + a feature-flag segment factory (`planSegment("pro")`) plugging into `FeatureFlagsApp` segments; optional `RequiresPlan("pro")` permission |
-| Webhooks | Consumed through the inbound-webhooks framework with Stripe signature verification and event idempotency (`stripeEventId` unique index) |
-
-## Architecture
-
-```
-billing/
-  src/
-    billingApp.ts        # BillingApp TerrenoPlugin (routes, webhook registration)
-    billingService.ts    # getEntitlements, planSegment, RequiresPlan
-    stripeSync.ts        # webhook event handlers → model sync
-    models/
-      billingCustomer.ts   # orgId ↔ stripeCustomerId
-      billingSubscription.ts
-      billingEvent.ts      # processed webhook events (idempotency)
-```
-
-```typescript
-new BillingApp({
-  stripeSecretKey: env,
-  webhookSecret: env,
-  plans: [{id: "pro", name: "Pro", stripePriceId: "price_...", features: ["ai", "sso"]}],
-  subject: "organization",              // default
-  onSubscriptionChange?: (sub) => Promise<void>;
-})
-```
-
-Webhook events handled: `checkout.session.completed`,
-`customer.subscription.created|updated|deleted`, `invoice.payment_failed`,
-`invoice.paid`. Each handler is idempotent via `BillingEvent`.
-
-## Models
-
-Five-type pattern, descriptions, `createdUpdatedPlugin` + `isDeletedPlugin`.
-
-**BillingCustomer** — `organizationId` (ref, required, unique indexed),
-`stripeCustomerId` (string, unique indexed), `email` (string).
-
-**BillingSubscription** — `organizationId` (ref, required, indexed), `planId` (string —
-Terreno plan id), `stripeSubscriptionId` (string, unique), `status` (Stripe status enum:
-active/trialing/past_due/canceled/…), `currentPeriodEnd` (date), `cancelAtPeriodEnd`
-(boolean), `seats` (number, optional).
-
-**BillingEvent** — `stripeEventId` (string, unique), `type` (string), `processedAt`
-(date), `error` (string, optional).
-
-## APIs
-
-| Method | Path | Permissions | Notes |
-|---|---|---|---|
-| GET | `/billing/plans` | IsAuthenticated | Code-defined plans (no Stripe call) |
-| GET | `/billing/subscription` | IsOrgMember | Current org's subscription + entitlements |
-| POST | `/billing/checkoutSession` | IsOrgAdmin | `{planId}` → Stripe Checkout URL; creates customer on first use |
-| POST | `/billing/portalSession` | IsOrgAdmin | Stripe Billing Portal URL |
-| POST | `/billing/webhooks/stripe` | signature-verified | Via inbound-webhooks framework; raw body |
-
-## Notifications
-
-`invoice.payment_failed` fires `onSubscriptionChange` and sends a dunning email through
-`@terreno/comms` when a mail provider is configured (template `paymentFailed`).
-
-## UI
-
-Phase 4, kept deliberately thin: a plan-picker screen (`GET /billing/plans` + checkout
-redirect) and a billing settings card (current plan, status, portal link) in
-example-frontend; org-management surfaces integrate later via `org-management-ui`.
-
-## Phases
-
-1. **Package + models:** `@terreno/billing` scaffold, three models, plan config
-   validation, unit tests.
-2. **Checkout + portal:** customer creation, session routes, `getEntitlements`,
-   `planSegment`, `RequiresPlan`, tests with mocked Stripe SDK.
-3. **Webhook sync** *(gated on inbound-webhooks)*: signature-verified event routes,
-   idempotent handlers, dunning email, `stripe-mock`/fixture tests.
-4. **UI + example + docs:** plan picker + billing settings in example-frontend, seeds
-   with Stripe test-mode instructions, `docs/how-to/add-billing.md`, SDK regen.
-
-## Feature Flags & Migrations
-
-New collections only. Entitlement gating composes with existing feature flags — a flag can
-target `planSegment("pro")` exactly like today's `pro-users` segment example.
-
-## Activity Log & User Updates
-
-Subscription lifecycle changes logged via `logger` + `BillingEvent`; org-facing billing
-history is the Stripe Portal's job, not Terreno's.
-
-## Not Included / Future Work
-
-- RevenueCat entitlement merge (`mobile-iap-revenuecat`).
-- Seat enforcement against Membership counts (`invitations-and-seats` follow-up).
-- Metered usage, coupons/promotions management, multi-currency handling beyond Stripe
-  defaults.
-
-## Files to Create / Modify
-
-- `billing/` (new workspace package), root `package.json` workspace + scripts
-- `example-backend/src/server.ts` — env-gated `BillingApp` registration
-- `example-frontend` — two screens + SDK regen
-- `docs/how-to/add-billing.md`, `docs/reference/billing.md`, env reference
-- `.github/workflows/billing-ci.yml`, `publish-on-tag.yml`
-
-## Task List
-
-See [docs/tasks/billing-stripe.md](../tasks/billing-stripe.md).
-
-## Acceptance Criteria
-
-- [ ] An org admin can create a Checkout session for a plan and, after the (test-mode)
-      webhook lands, `GET /billing/subscription` reports the active plan and entitlements.
-- [ ] Webhook events are signature-verified and idempotent: replaying the same
-      `stripeEventId` is a no-op.
-- [ ] A feature flag targeting `planSegment("pro")` evaluates true only for members of a
-      subscribed org; `RequiresPlan("pro")` returns 403 otherwise.
-- [ ] Subscription cancellation (portal) downgrades entitlements after the webhook, not
-      before.
-- [ ] Non-admin org members cannot create checkout/portal sessions.
-- [ ] Entitlement checks perform zero inline Stripe API calls.