@terreno/mcp 57.17.0 → 57.19.2

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

@@ -0,0 +1,119 @@
+# Program: B2B platform
+
+**Status:** Approved — decisions D1–D7 resolved 2026-08-09; first ten IPs open
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1095
+**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 | `org-management-ui` (supersedes `orgs-and-teams`), `rbac-permissions` (Complete), `invitations-and-seats` |
+| 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`, `dashboard-chart-parity`, `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 `org-management-ui` 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) | Approved — Phase 1 gap-fill implemented | [tasks](../tasks/comms-abstraction.md) |
+| [comms-adapter-expo-push](comms-adapter-expo-push.md) | In progress | [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) | In progress (Phase 1) | [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) | Superseded by [org-management-ui](org-management-ui.md) | — |
+| [org-management-ui](org-management-ui.md) | Draft — awaiting approval | [tasks](../tasks/org-management-ui.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) | Complete (PR #932) | — |
+| [notification-center](notification-center.md) | Approved | [tasks](../tasks/notification-center.md) |
+| [framework-audit-log](framework-audit-log.md) | Approved | [tasks](../tasks/framework-audit-log.md) |
+
+Remaining items (`inbound-webhooks`, `invitations-and-seats`,
+`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/57.17.0/implementationPlans/better-auth-strict-oauth-provider.md

@@ -0,0 +1,81 @@
+# Implementation plan: Better Auth sync omits unset `oauthProvider`
+
+**Status:** Complete — fix on master (`syncBetterAuthUser` omits unset `oauthProvider`)  
+**Roadmap:** Area=`auth`, Target=`Released`, Impact=`Fix`  
+**Issue:** https://github.com/TerrenoLabs/terreno/issues/1218  
+**Branch:** `cursor/better-auth-strict-oauth-provider-3b37`  
+**Created:** 2026-08-30  
+
+## Goal
+
+Email/password Better Auth users sync into a consumer `User` model that uses `strict: "throw"` and does **not** declare `oauthProvider`. The first authenticated `modelRouter` request after sign-up populates `req.user` (not 401).
+
+## Non-Goals
+
+- Adding `oauthProvider` to the `terreno bootstrap app` User schema
+- Inventing or shipping `betterAuthUserPlugin` (it is documented today but does not exist in `@terreno/api`)
+- Changing session-middleware behavior when sync still throws (debug log + `next()` without `req.user`)
+- JWT/Passport paths
+- Data migration or backfill of existing User documents
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Q1 Which #1218 fix | Option 1: omit `oauthProvider` on create unless a non-empty provider string is passed |
+| Bootstrap User field | Out of scope |
+| OAuth without the field | Still fails `strict: "throw"`; apps that use OAuth must declare `oauthProvider` |
+
+## Architecture
+
+`syncBetterAuthUser` lazily creates the app `User` on the first authenticated request (`createBetterAuthSessionMiddleware`), not at Better Auth sign-up.
+
+**Create payload today** always includes `oauthProvider: oauthProvider || null`. Mongoose `strict: "throw"` rejects the undeclared key. Sync throws, middleware swallows the error, `req.user` is unset, permissions see an unauthenticated request → 401.
+
+**Create payload after:** spread `oauthProvider` only when `oauthProvider` is a non-empty string. Match the existing email-link branch (`if (oauthProvider) { userByEmail.oauthProvider = oauthProvider }`).
+
+Email/password and session middleware call `syncBetterAuthUser(userModel, betterAuthUser)` with no third argument.
+
+## Models
+
+No schema change in `@terreno/api` or bootstrap. Consumer OAuth apps keep declaring `oauthProvider` as they do in `example-backend`.
+
+## APIs
+
+Public function signature unchanged: `syncBetterAuthUser(userModel, betterAuthUser, oauthProvider?)`.
+
+## UI
+
+None.
+
+## Feature Flags & Migrations
+
+None. Existing documents that already stored `oauthProvider: null` are unchanged.
+
+## Not Included / Future Work
+
+- Optional bootstrap field or a real `betterAuthUserPlugin` for OAuth-ready templates
+- Louder logging when lazy sync fails inside session middleware
+
+## Files to Create / Modify
+
+| Path | Change |
+|------|--------|
+| `api/src/betterAuthSetup.ts` | Omit unset `oauthProvider` on create |
+| `api/src/betterAuthSetup.test.ts` | `strict: "throw"` schema **without** the field; OAuth still sets the field when declared |
+| `docs/how-to/configure-better-auth.md` | User model: `betterAuthId` required; `oauthProvider` only for OAuth; replace non-existent plugin example in that section |
+| `docs/explanation/authentication.md` | Lazy User sync; do not write `oauthProvider` for email/password |
+| `.rulesync/rules/api/00-api.md` | Same field rules; then `bun run rules` / `bun run skills:sync` |
+| `changelog/unreleased/better-auth-strict-oauth-provider.md` | `Fixed` |
+
+## Task List
+
+[docs/tasks/better-auth-strict-oauth-provider.md](../tasks/better-auth-strict-oauth-provider.md)
+
+## Acceptance Criteria
+
+- [x] `syncBetterAuthUser` without a provider creates a user on `strict: "throw"` with no `oauthProvider` path
+- [x] `syncBetterAuthUser(..., "google")` still sets `oauthProvider` when the schema declares the field
+- [x] Existing `syncBetterAuthUser` tests stay green
+- [x] How-to and explanation docs state when the field is required
+- [x] Agent rule copy matches after `bun run rules`

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

@@ -0,0 +1,159 @@
+# Implementation Plan: Stripe billing and subscriptions
+
+**Status:** Approved
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1025
+**Priority:** High
+**Effort:** Epic
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** [org-management-ui](org-management-ui.md), [inbound-webhooks](inbound-webhooks.md) (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). Admin org
+settings show a billing placeholder until this IP ships (see `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)*: register `POST /billing/webhooks/stripe`
+   on the shared `WebhooksApp` with `stripeSignature`. Do not fork parsers. 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/57.17.0/implementationPlans/build-terreno-app-validation.md

@@ -0,0 +1,154 @@
+# Implementation Plan: Dogfooding Run and Launch Blog Post
+
+**Status:** Approved — key decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1015
+**Priority:** High (this is the program's acceptance test)
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md), [`ai-dev-loop-boost`](ai-dev-loop-boost.md), [`deploy-to-vercel`](deploy-to-vercel.md), [`docs-reference-coverage`](docs-reference-coverage.md)
+**RTK deprecation flag:** **Blocked** — the build must be performed against the supported stack (syncdb + Better Auth). A dogfooding run on the deprecated data layer would produce a friction log and a blog post that are both obsolete on publication.
+
+## Goal
+
+Prove the launch claim by testing it, then publish the result. The [`build-terreno-app`](../../.rulesync/skills/build-terreno-app/SKILL.md) skill is the harness; this IP is the run, the fixes that come out of it, and the blog post.
+
+The program's launch gate is: **if an agent following only public documentation and published skills cannot build and deploy a real universal app, the launch is not ready.** This IP executes that test. Its most likely outcome is a list of documentation gaps, which is exactly what it is for.
+
+## Non-Goals
+
+- Writing the skill (already done — this IP runs it).
+- Shipping the demo app as a maintained Terreno example. It is a blog-post artifact, not a fourth example app to keep updated.
+- Marketing beyond the blog post.
+- Building every app concept. One run, one app.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Question | Decision |
+|---|----------|----------|
+| B1 | App concept | **Pantry** — leads on syncdb conflict resolution |
+| B2 | Public demo repo? | **A** — `flourishhealth/terreno-pantry` |
+| B3 | Who performs the run? | **C** if capacity; else **A** |
+| B4 | Runs before publish | **B** — two runs with fix cycle between |
+| B5 | Publication venue | **A** — docs site blog only |
+| B6 | Name the model? | **A** — yes, with version |
+
+## Architecture
+
+### Run structure
+
+```mermaid
+flowchart TD
+  R1["Run 1<br/>fresh session, public sources only"]
+  L1["Friction log 1<br/>gaps by severity"]
+  F["Fix cycle<br/>docs, skills, MCP"]
+  R2["Run 2<br/>fresh session, fresh environment"]
+  L2["Friction log 2<br/>+ repeat-gap analysis"]
+  G{"Blocking or<br/>major gaps left?"}
+  B["Blog post"]
+  LAUNCH["Launch gate: passed"]
+  R1 --> L1 --> F --> R2 --> L2 --> G
+  G -->|"yes"| F
+  G -->|"no"| B --> LAUNCH
+```
+
+The loop between the gap check and the fix cycle is the point. Exiting after one pass would mean publishing a launch claim that was never re-tested.
+
+### What counts as passing
+
+| Gate | Threshold |
+|------|-----------|
+| Blocking gaps | zero |
+| Major gaps | zero at launch; any found in run 1 must be fixed and confirmed in run 2 |
+| Minor gaps | acceptable, all filed as issues |
+| App completeness | every slice in the chosen concept working on web and one native target |
+| Differentiators | all six demonstrated with artifacts (AI, offline, realtime, admin, universal, feature flags) |
+| Deployment | public URL, all four verification checks passing |
+| Debug loop | the deliberate bug found via `last_error` / `read_logs` without reading framework source |
+
+The debug-loop gate is the one that most directly tests the AI-native pillar. If the agent has to read `@terreno/api` source to diagnose a bug in its own app, the pillar is not real yet.
+
+### Fix routing
+
+Gaps found in a run do not get fixed inside this IP. They route to the IP that owns the surface:
+
+| Gap type | Routes to |
+|----------|-----------|
+| Tutorial wrong or incomplete | [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md) |
+| Reference page missing or wrong | [`docs-reference-coverage`](docs-reference-coverage.md) |
+| MCP tool or agent-loop gap | [`ai-dev-loop-boost`](ai-dev-loop-boost.md) |
+| Deployment guide or skill gap | [`deploy-to-vercel`](deploy-to-vercel.md) / [`deploy-to-gcp`](deploy-to-gcp.md) |
+| Bootstrap output wrong | [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) (agent surfaces) or the MCP server |
+| Positioning inconsistency | [`positioning-django-rails-universal`](positioning-django-rails-universal.md) |
+| Genuine framework bug | a new issue, triaged normally |
+
+This keeps ownership clear and prevents this IP from absorbing the whole program.
+
+## Models / APIs
+
+None in Terreno. The demo app's models come from the chosen concept and live in its own repository.
+
+## Notifications
+
+None.
+
+## UI
+
+The demo app's screens live in its own repository. No changes to `@terreno/ui` unless the run finds a bug, which routes out per the table above.
+
+## Phases
+
+1. **Run 1** — fresh session, public sources only, friction log produced.
+2. **Triage** — classify every gap, route to owning IPs, file issues.
+3. **Fix cycle** — owning IPs land their fixes (tracked, not performed here).
+4. **Run 2** — fresh session and fresh environment, second friction log, repeat-gap analysis.
+5. **Gate** — confirm zero blocking and zero major gaps, or loop back to phase 3.
+6. **Blog post** — draft, artifact review, fact check, publish.
+7. **Retrospective** — record what the harness itself got wrong so the skill improves.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- A recurring dogfooding cadence (worth doing quarterly; propose separately once the first run has calibrated the effort).
+- Building the other four app concepts.
+- Maintaining the demo app past the post.
+- Comparative benchmarks against other frameworks.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/explanation/dogfooding-results.md` (the public summary of both runs)
+- The demo app repository (outside this repo, per B2)
+
+**Modify**
+
+- `.rulesync/skills/build-terreno-app/SKILL.md` and its references (retrospective improvements)
+- `website/blog/` (the post, if the docs site gains a blog)
+- Whichever documents the fix cycle touches — owned by their IPs
+
+## Task List
+
+See [`docs/tasks/build-terreno-app-validation.md`](../tasks/build-terreno-app-validation.md).
+
+## Acceptance Criteria
+
+- [ ] Run 1 completed with a friction log classifying every gap by severity, phase, and suggested fix.
+- [ ] Every blocking and major gap from run 1 is filed as an issue and routed to an owning IP.
+- [ ] Run 2 completed in a fresh environment after fixes, with its own friction log.
+- [ ] Run 2 reports zero blocking gaps and zero major gaps.
+- [ ] Any gap appearing in both runs is called out explicitly with an explanation of why the fix did not work.
+- [ ] The demo app implements every slice of the chosen concept and runs on web and one native target.
+- [ ] All six differentiators are demonstrated with artifacts in `/opt/cursor/artifacts/`.
+- [ ] The deliberate bug was found using only `last_error` and `read_logs`, without reading framework source, and the elapsed time is recorded.
+- [ ] The app is deployed to a public URL with all four verification checks passing.
+- [ ] `BLOG_DRAFT.md` follows the outline, includes a "what did not work" section with three real gaps, and names the model and version used.
+- [ ] Every claim in the post is verified against an artifact by someone who did not perform the run.
+- [ ] `docs/explanation/dogfooding-results.md` publishes both runs' gap counts and what changed between them.
+- [ ] The `build-terreno-app` skill is updated with retrospective improvements, and mirrors are regenerated.

package/src/docs/versioned/57.17.0/implementationPlans/can-as-permission-seam.md

@@ -0,0 +1,134 @@
+# `can()` as the permission seam
+
+**Status:** Complete  
+**Branch:** `cursor/architecture-ips-a7ec`  
+**Owner:** —  
+**Created:** 2026-08-24  
+**Architecture source:** [rbac-permissions.md](rbac-permissions.md) (Complete — this IP **finishes** `can()` as enforcement, it does not redesign roles/statements)  
+**Task list:** [can-as-permission-seam.md](../tasks/can-as-permission-seam.md)  
+**Depends on:** [unified-mutation-executors.md](unified-mutation-executors.md) so MCP and REST do not keep two permission forks  
+**Related:** shipped `createAccess().can()` and `buildAccessPermissions` / `resolveModelRouterAccess` compiling into `RESTPermissions`
+
+## Goal
+
+When a router has `access` + `accessControl`, transports call `accessControl.can({user, resource, action, doc})` (plus existing scopes/field masks). Stop compiling RBAC into `PermissionMethod[]` and then running `checkPermissions` as the real engine.
+
+Today `resolveModelRouterAccess` in `api/src/rbac/modelRouterAccess.ts` builds legacy `permissions.create/list/...` arrays. `permissionMiddleware` and executors still AND those functions. Apps still pass both `access` and `permissions` (example-backend). The RBAC IP already defined `can()` + `IsPermitted` as the target.
+
+## Non-Goals
+
+- New role/statement/scope/field-view model (already shipped).
+- Deleting `Permissions.IsAuthenticated` / `IsOwner` / `RESTPermissions` for routers that have **no** `access` block.
+- Redis/cross-process RBAC cache (explicitly out of the completed RBAC IP).
+- Admin UI for roles (shipped).
+- Collapsing `api/src/rbac/*` files into one file (fails the deletion test).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Interface shape | **A — `can()` is the engine when `access` is set.** `permissionMiddleware` and executors branch: RBAC path calls `can()`; legacy path calls `checkPermissions`. Not B (delete `PermissionMethod` in one cut). |
+| `permissions` field | Remains **required on the type** for routers without `access`. When `access` is set, `permissions` may still be present but **must not** be AND-composed with `can()` (that double-gate is the bug). `resolveModelRouterAccess` stops replacing `permissions` with compiled methods for the request path. |
+| Empty array = 405 | Preserve: empty `permissions.create` disables create. For `access`, missing action / deny from `can()` is 403 unless the method is not in the access map — map CRUD methods to resource actions as today’s `buildAccessPermissions` does. Disabled method stays 405 when the access config omits that action the same way empty arrays work; document the mapping table in reference docs. |
+| Executors | After unified-mutation-executors, one `assertCanWrite(method, …)` used by executors (and thus MCP). Middleware uses the same helper for HTTP load-object-and-check. |
+| `IsPermitted` | Keep as the adapter for **custom** routes that are not modelRouter CRUD. |
+| Compatibility | Routers with only `permissions:` unchanged. Routers with `access:` may drop redundant `permissions` arrays in example-backend in a follow-up task in this IP. |
+
+## Interface shapes considered
+
+**A (chosen).**
+
+```typescript
+assertAllowed({
+  method: RESTMethod,
+  options: Pick<ModelRouterOptions<T>, "access" | "accessControl" | "permissions">,
+  user?: User,
+  doc?: T,
+}): Promise<void> // throws APIError 403/405
+```
+
+Inside: if `options.access && options.accessControl` → `can()`; else `checkPermissions`.
+
+**B (rejected for this slice).** Remove `RESTPermissions` from `ModelRouterOptions`. Forces every consumer to adopt RBAC in one release.
+
+## Architecture
+
+```
+Before:
+  access → buildAccessPermissions → PermissionMethod[] → checkPermissions
+                                                      ↗ executors
+                                                      ↗ permissionMiddleware
+                                                      ↗ MCP handlers (until unified writes)
+
+After:
+  access.can(...)  ← assertAllowed ← HTTP / executors / MCP
+  permissions[]    ← assertAllowed   (legacy routers only)
+```
+
+Do not call `buildAccessPermissions` on the hot path. It may remain as a deprecated helper for one minor if tests rely on it; contract phase deletes hot-path use.
+
+## Docs in this slice
+
+| Page | Change |
+|------|--------|
+| `docs/reference/api.md` | Permission evaluation order: `access`+`accessControl` → `can()`; else `permissions` arrays. Dual AND is gone. |
+| `docs/how-to/create-a-model.md` | Example with `access` only (plus TerrenoApp-injected `accessControl`). |
+| `docs/implementationPlans/rbac-permissions.md` | Pointer: enforcement inversion completed here. |
+
+## Testing
+
+Seam: `assertAllowed` + one modelRouter integration test with `access` that **fails** if compiled `permissions` still AND with a denying extra `Permissions.IsAdmin`.
+
+Cases:
+
+- Legacy router: empty delete array → 405.
+- RBAC deny role → 403 with existing reason shape.
+- RBAC allow + leftover `permissions: {create: [Permissions.IsAdmin]}` on a non-admin who `can()` create → **allow** (proves no double gate).
+- Scope deny still deny.
+- MCP write deny uses the same helper (after unified executors).
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| 403 vs 405 drift | Table in reference docs; tests per method omitted vs denied. |
+| Query filter / field views currently bundled in `resolveModelRouterAccess` | Keep queryFilter and responseHandler injection; only stop compiling permission **methods**. |
+| Custom routes using `permissionMiddleware` | Same `assertAllowed` inside middleware so custom CRUD-shaped routes benefit. |
+
+## Phases
+
+1. Add `assertAllowed`; unit tests for legacy vs `can()` vs double-gate.
+2. Wire `permissionMiddleware` + executors; delete hot-path `buildAccessPermissions`.
+3. example-backend: `access` without redundant AND-permissions where safe. Docs + changelog.
+
+## Feature Flags & Migrations
+
+No flag. Behavior change for apps that set **both** `access` and denying `permissions` expecting AND: they become `can()`-only. Changelog **Breaking** note: `access` wins; remove duplicate `permissions` if you relied on AND.
+
+## Not Included / Future Work
+
+- Making `permissions` optional in the TypeScript type (major).
+- External permission sources (already in RBAC module).
+
+## Files to Create / Modify
+
+- `api/src/permissions.ts` or `api/src/rbac/assertAllowed.ts` (prefer small new module next to rbac)
+- `api/src/rbac/modelRouterAccess.ts` — stop hot-path compile
+- `api/src/api.ts` — `_buildModelRouter` must not require compiled arrays when `access` is set
+- `api/src/sync/executors.ts`
+- `api/src/rbac/modelRouterAccess.test.ts`, executor and api permission tests
+- `example-backend` modelRouters if they dual-specify
+- Docs listed above
+
+## Acceptance Criteria
+
+- [ ] With `access`+`accessControl`, `can()` is the only allow/deny engine for CRUD (HTTP + executors).
+- [ ] Dual `access` + denying `permissions` does not AND.
+- [ ] Legacy `permissions`-only routers unchanged (405 empty array, AND semantics).
+- [ ] Query filters and field views from `resolveModelRouterAccess` still apply.
+- [ ] Breaking note published for the AND change.
+- [ ] Docs match; api tests pass.
+
+## Task List
+
+[docs/tasks/can-as-permission-seam.md](../tasks/can-as-permission-seam.md)