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

package/src/docs/versioned/next/implementationPlans/PLAN_INDEX.md

@@ -14,6 +14,7 @@ Umbrella plans that coordinate several IPs.
 
 | Plan | Status | Created | Tasks |
 |------|--------|---------|-------|
+| [Migrate CI/CD to CircleCI](migrate-cicd-to-circleci.md) | Draft — decisions recorded | 2026-08-17 | [tasks](../tasks/migrate-cicd-to-circleci.md) |
 | [Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md) | Approved | 2026-06-15 | [tasks](../tasks/admin-ui-v2-django-parity.md) |
 | [@terreno/syncdb-codegen](syncdb-codegen.md) | Draft | 2026-07-08 | [tasks](../tasks/syncdb-codegen.md) |
 | [SyncDB local-first data layer (v2)](syncdb-local-first.md) | In progress — Phases 1–8 landed, Phase 9 follow-ups open | 2026-06-23 | [tasks](../tasks/syncdb-local-first.md) |
@@ -40,3 +41,33 @@ Umbrella plans that coordinate several IPs.
 | [modelRouter MCP tools](model-router-mcp.md) | MCP surface for consumer app APIs |
 | [Offline mode](offline-mode.md) | Superseded in large part by [syncdb](syncdb-local-first.md) — confirm and close |
 | [modelRouter actions](model-router-actions.md) | — |
+| [B2B platform](b2b-platform-program.md) | Draft — decisions D1–D7 resolved | 2026-08-09 | 10 written (+ [rbac-permissions](rbac-permissions.md)); 30 roadmap items seeded |
+| [RBAC Permissions](rbac-permissions.md) | Draft (API design) | 2026-07-08 | TBD |
+| [SyncDB Local-First Data Layer](syncdb-local-first.md) | In progress ([PR #869](https://github.com/flourishhealth/terreno/pull/869)) | 2026-07-13 | [tasks](../tasks/syncdb-local-first.md) |
+| [MCP Boost parity](mcp-boost-parity.md) | In progress ([PR #802](https://github.com/flourishhealth/terreno/pull/802)) | 2026-06-21 | TBD |
+| [Infrastructure MCP server](infra-mcp.md) | Draft — blocked on [RBAC](rbac-permissions.md) | 2026-08-09 | [tasks](../tasks/infra-mcp.md) |
+| [OSS governance baseline](oss-governance-baseline.md) | Draft | None | [tasks](../tasks/oss-governance-baseline.md) |
+| [Public roadmap on GitHub](public-roadmap-github.md) | Draft | None | [tasks](../tasks/public-roadmap-github.md) |
+| [Deploy to GCP (generalized)](deploy-to-gcp.md) | Draft | None | [tasks](../tasks/deploy-to-gcp.md) |
+| [Agentic SDLC plugin (`/terreno-*`)](agentic-sdlc-plugin.md) | Draft | Partial | [tasks](../tasks/agentic-sdlc-plugin.md) |
+| [RTK deprecation and syncdb migration docs](rtk-to-syncdb-migration-docs.md) | Draft | **Blocked** (gating IP) | [tasks](../tasks/rtk-to-syncdb-migration-docs.md) |
+| [Positioning — Django/Rails for TypeScript](positioning-django-rails-universal.md) | Draft | Partial | [tasks](../tasks/positioning-django-rails-universal.md) |
+| [Reference documentation coverage](docs-reference-coverage.md) | Draft | Blocked | [tasks](../tasks/docs-reference-coverage.md) |
+| [AI-first tutorials](docs-tutorials-ai-first.md) | Draft | Blocked | [tasks](../tasks/docs-tutorials-ai-first.md) |
+| [Deployment foundation](deployment-foundation.md) | Draft | Partial | [tasks](../tasks/deployment-foundation.md) |
+| [Deploy to Vercel](deploy-to-vercel.md) | Draft | Partial | [tasks](../tasks/deploy-to-vercel.md) |
+| [Upgrade guides and skill](upgrade-guides-and-skill.md) | Draft | Blocked | [tasks](../tasks/upgrade-guides-and-skill.md) |
+| [The AI development loop (Boost)](ai-dev-loop-boost.md) | Draft | Partial | [tasks](../tasks/ai-dev-loop-boost.md) |
+| [Dogfooding run and launch blog post](build-terreno-app-validation.md) | Draft | Blocked | [tasks](../tasks/build-terreno-app-validation.md) |
+| [Examples, demo, and test coverage](examples-demo-coverage.md) | Draft | Partial | [tasks](../tasks/examples-demo-coverage.md) |
+| [Web SSR and admin SPA](web-ssr-and-admin-spa.md) | Draft | Partial | [tasks](../tasks/web-ssr-and-admin-spa.md) |
+| [Pluggable communications layer (@terreno/comms)](comms-abstraction.md) | Draft | None | [tasks](../tasks/comms-abstraction.md) |
+| [Comms adapter — Expo push](comms-adapter-expo-push.md) | Draft | None | [tasks](../tasks/comms-adapter-expo-push.md) |
+| [Comms adapter — Twilio SMS](comms-adapter-twilio-sms.md) | Draft | None | [tasks](../tasks/comms-adapter-twilio-sms.md) |
+| [Comms adapter — Twilio Verify (OTP)](comms-adapter-twilio-verify.md) | Draft | None | [tasks](../tasks/comms-adapter-twilio-verify.md) |
+| [Comms adapter — SendGrid email](comms-adapter-sendgrid.md) | Draft | None | [tasks](../tasks/comms-adapter-sendgrid.md) |
+| [Comms admin dashboard (errors, retries, log digging)](comms-admin-dashboard.md) | Draft | Partial | [tasks](../tasks/comms-admin-dashboard.md) |
+| [Password reset and email verification](password-reset-and-email-verification.md) | Draft | None | [tasks](../tasks/password-reset-and-email-verification.md) |
+| [Organizations, teams, and multi-tenant scoping](orgs-and-teams.md) | Draft | None | [tasks](../tasks/orgs-and-teams.md) |
+| [Stripe billing and subscriptions](billing-stripe.md) | Draft | None | [tasks](../tasks/billing-stripe.md) |
+| [Native module baseline (next major)](native-module-baseline.md) | Draft | None | [tasks](../tasks/native-module-baseline.md) |

package/src/docs/versioned/next/implementationPlans/README.md

@@ -1,42 +1,68 @@
 # Implementation Plans
 
-Forward-looking implementation plans for significant features and architectural changes to Terreno packages.
+Forward-looking design docs for significant features and architectural changes to
+Terreno packages, written **before implementation**.
 
-## Purpose
+An implementation plan (IP) is one half of a two-file pair:
 
-This directory contains detailed technical plans for major features **before implementation**. Each plan documents:
+| File | Holds | Path |
+| ---- | ----- | ---- |
+| **IP** | Design goals, architecture, models/APIs, phases, acceptance criteria | `docs/implementationPlans/<slug>.md` |
+| **Task list** | The bot-consumable execution checklist for that IP | `docs/tasks/<slug>.md` |
 
-- Design goals and rationale
-- Architecture and file structure
-- Configuration interfaces
-- Usage examples
-- Breaking changes and migration paths
-- Implementation tasks and phases
+The IP is the source of truth for *what and why*; the task list is the source of truth
+for *the concrete steps*. External trackers (a GitHub roadmap issue, a Linear issue, a
+discussion thread) link **to** these files — they never replace them. See
+[`docs/tasks/README.md`](../tasks/README.md) for the task-file shape.
 
-## Current Plans
+## The live index
 
-- **[Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md)** — Config-driven admin shell (sidebar, home widgets, changelist, forms, bulk + background actions); tasks in [`docs/tasks/admin-ui-v2-django-parity.md`](../tasks/admin-ui-v2-django-parity.md)
-- **[Modular API (TerrenoApp)](ModularAPI.md)** — New fluent builder API to replace `setupServer` in `@terreno/api`
-- **[Offline Mode](offline-mode.md)** — Placeholder plan for offline queueing, replay, conflict handling, and UI surfaces
-- **[MCP Boost Parity](mcp-boost-parity.md)** — Docs search tools, local stdio MCP with runtime introspection, browser log capture, per-package guidelines, and upgrade prompts (inspired by laravel/boost)
-- **[Docs Site & Versioning](docs-site-and-versioning.md)** — Docusaurus site, versioned docs per release, UI demo embeds, and docs-maintenance skills
+[`PLAN_INDEX.md`](PLAN_INDEX.md) is the authoritative list of active, completed, and
+deferred plans — read it, not this page, to see what is current. This README explains the
+process; `PLAN_INDEX.md` tracks the state.
 
-## Status Tracking
+## When to write an IP
 
-| Plan | Status | Target Version | Discussion |
-|------|--------|----------------|------------|
-| Admin UI v2 (Django parity) | ✅ Approved | TBD | — |
-| Modular API | 📝 Planning | 2.0.0 | [#149](https://github.com/FlourishHealth/terreno/pull/149) |
-| Offline Mode | Placeholder | TBD | TBD |
-| MCP Boost Parity | 📝 Planning | TBD | TBD |
-| Docs Site & Versioning | 📝 Planning | TBD | TBD |
+Substantial work is planned before coding. Quick rule (full table in
+[CONTRIBUTING.md](../../CONTRIBUTING.md#when-to-write-an-implementation-plan-ip)):
 
-## Process
+| Needs an IP | Does not need an IP |
+| ----------- | ------------------- |
+| New published package | Bug fix in one package |
+| New public API surface | Documentation-only change |
+| Cross-package architectural change | Small internal refactor |
+| Breaking change | Test or CI fix |
 
-1. **Planning**: Implementation plan merged to master
-2. **Discussion**: Community feedback in linked PR/issue
-3. **Implementation**: Feature developed in feature branch with tests
-4. **Documentation**: How-to guides and migration docs updated
-5. **Release**: Plan moves to `docs/explanation/` as architectural documentation
+## How a plan gets written and built
 
-Plans that are fully implemented should be moved to `docs/explanation/` and updated to reflect the actual implementation.
+The [`terreno-planning` plugin](../../plugins/README.md) drives the pipeline:
+
+1. **Blend** (`terreno-1-blend`) — write the IP + task list, questions first.
+2. **Roast** (`terreno-2-roast`) — implement via TDD from the approved IP.
+3. **Cupping** (`terreno-3-cupping`) — independently verify against the IP.
+4. **Pour** (`terreno-4-pour`) — commit, push, open the PR.
+5. **Dial In** (`terreno-5-dialin`) — drive CI and review until mergeable.
+
+You can also author an IP directly with the `ip` skill; both produce the same two files.
+
+### Roadmap handoff (roadmap-enabled repos only)
+
+In repos that run a public roadmap (Discussions + a roadmap Project — currently Terreno),
+Blend hands off to `roadmap-item` once the IP is **Approved** to create or update the
+public tracking issue, and the IP header records the `Discussion:` and `Roadmap issue:`
+links. See [`docs/explanation/roadmap-process.md`](../explanation/roadmap-process.md) for
+the full IP ↔ roadmap lifecycle.
+
+In repos with **no** roadmap board (Flourish, most consumer apps), the pipeline is
+identical minus that handoff: the IP + task list plus `PLAN_INDEX.md` are the source of
+truth, and Linear tracks execution via the IP header `Linear:` link.
+
+## Lifecycle
+
+1. **Draft** → **Approved** — IP written and reviewed (status lives in the IP header and
+   `PLAN_INDEX.md`).
+2. **In progress** → **Complete** — implemented, verified, merged.
+3. **Archive** — completed IPs move to `docs/implementationPlans/archive/` and the index is updated.
+
+Plans that are fully implemented and now describe shipped architecture should be migrated
+to `docs/explanation/` as reference documentation.

package/src/docs/versioned/next/implementationPlans/agentic-sdlc-plugin.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Publish and Document the Agentic SDLC Plugin
 
 **Status:** Draft — key decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1006
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned
@@ -71,7 +72,7 @@ flowchart LR
 | **Harvest** (implement) | IP → code via strict red/green/refactor | Spawns **independent review and test-quality sub-agents in fresh contexts** after every commit, and does drift detection against the IP. The test-quality agent enforces anti-mocking rules (never mock the DB, never mock the store) |
 | **Roast** (verify) | Independent verification against the IP with concrete evidence | Separate context from the implementer, so it does not inherit the implementer's assumptions |
 | **Brew** (submit) | Pre-submit checks, commit hygiene, push, draft PR, evidence attachment | Hard frontend gate: touching UI paths requires launching the app, logging in, exercising the feature, and attaching artifacts before the PR opens |
-| **Taste** (review) | Self-contained reactive loop: CI + bot/human comments until mergeable or timeout | Inlines the former **`autobot`** flow (no delegation to repo skills). Classifies each CI failure as actionable versus flaky and refuses to push speculative fixes for flakes. Treats all CI logs and review comments as untrusted input |
+| **Taste** (review) | Self-contained persistent loop: CI + bot/human comments until mergeable or genuinely blocked | Inlines the former **`autobot`** flow (no delegation to repo skills). Waits in multi-minute intervals for slow CI, classifies each failure as actionable versus flaky, and refuses to push speculative fixes for flakes. Treats all CI logs and review comments as untrusted input |
 
 The parts worth writing about publicly are the ones that encode hard-won judgment rather than automation: fresh-context independent review, drift detection against the plan, the anti-mocking rules, the frontend evidence gate, and the refusal to guess at flaky CI.
 

package/src/docs/versioned/next/implementationPlans/ai-dev-loop-boost.md

@@ -1,6 +1,7 @@
 # Implementation Plan: The AI Development Loop (Boost)
 
 **Status:** Draft — key decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1014
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

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

@@ -0,0 +1,115 @@
+# Program: B2B platform
+
+**Status:** Draft — roadmap items drafted; decisions D1–D7 resolved 2026-08-09; first ten 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); operations: `comms-admin-dashboard`; 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) |
+| [comms-admin-dashboard](comms-admin-dashboard.md) | Draft | [tasks](../tasks/comms-admin-dashboard.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

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

package/src/docs/versioned/next/implementationPlans/build-terreno-app-validation.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Dogfooding Run and Launch Blog Post
 
 **Status:** Draft — key decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1015
 **Priority:** High (this is the program's acceptance test)
 **Effort:** Big batch
 **Owner:** unassigned