@terreno/mcp 0.31.0 → 56.0.0-beta.0

package/dist/docs/versioned/next/tasks/billing-stripe.md

@@ -1,75 +0,0 @@
-# Tasks: Stripe billing and subscriptions
-
-IP: [billing-stripe](../implementationPlans/billing-stripe.md)
-
-## Phase 1 — Package + models
-
-- [ ] **Task 1.1**: Scaffold `@terreno/billing` package
-  - Description: workspace package mirroring `feature-flags/`; root scripts
-  - Files: `billing/package.json`, `billing/tsconfig.json`, root `package.json`
-  - Depends on: none
-  - Acceptance: compile + lint pass
-- [ ] **Task 1.2**: Models (BillingCustomer, BillingSubscription, BillingEvent)
-  - Description: per IP with unique indexes and descriptions
-  - Files: `billing/src/models/*`
-  - Depends on: 1.1
-  - Acceptance: unit tests incl. unique-index violations
-- [ ] **Task 1.3**: Plan config validation
-  - Description: `plans` option schema (Zod), duplicate/missing price detection at startup
-  - Files: `billing/src/billingApp.ts`
-  - Depends on: 1.1
-  - Acceptance: bad config fails fast with clear error
-
-## Phase 2 — Checkout + portal + entitlements
-
-- [ ] **Task 2.1**: Customer creation + checkout/portal session routes
-  - Description: `POST /billing/checkoutSession` (IsOrgAdmin), `POST /billing/portalSession`, `GET /billing/plans`
-  - Files: `billing/src/billingApp.ts`
-  - Depends on: 1.2, orgs-and-teams Phase 3
-  - Acceptance: mocked-Stripe supertest incl. permission denials
-- [ ] **Task 2.2**: `getEntitlements` + `planSegment` + `RequiresPlan`
-  - Description: cache-backed entitlement service; feature-flag segment factory; permission
-  - Files: `billing/src/billingService.ts`
-  - Depends on: 1.2
-  - Acceptance: zero inline Stripe calls asserted; flag targeting test with FeatureFlagsApp
-- [ ] **Task 2.3**: `GET /billing/subscription`
-  - Description: org subscription + entitlements for members
-  - Files: `billing/src/billingApp.ts`
-  - Depends on: 2.2
-  - Acceptance: supertest member/non-member
-
-## Phase 3 — Webhook sync (gated on inbound-webhooks)
-
-- [ ] **Task 3.1**: Stripe webhook route with signature verification
-  - Description: raw-body route via inbound-webhooks; reject unsigned
-  - Files: `billing/src/stripeSync.ts`
-  - Depends on: inbound-webhooks IP
-  - Acceptance: signed/unsigned fixture tests
-- [ ] **Task 3.2**: Idempotent event handlers
-  - Description: checkout.session.completed, subscription created/updated/deleted, invoice paid/payment_failed → model sync via `BillingEvent`
-  - Files: `billing/src/stripeSync.ts`
-  - Depends on: 3.1
-  - Acceptance: replay of same event id is a no-op; cancellation downgrades after webhook
-- [ ] **Task 3.3**: Dunning email
-  - Description: `paymentFailed` template through comms when configured
-  - Files: `billing/src/stripeSync.ts`, `comms/src/templates.ts`
-  - Depends on: 3.2, comms-abstraction
-  - Acceptance: template send asserted on payment_failed fixture
-
-## Phase 4 — UI + example + docs
-
-- [ ] **Task 4.1**: Plan picker + billing settings screens
-  - Description: example-frontend screens per IP; SDK regen
-  - Files: `example-frontend/app/**`, `store/openApiSdk.ts`
-  - Depends on: Phase 2
-  - Acceptance: UI verification evidence per verify-ui-changes (Stripe test mode)
-- [ ] **Task 4.2**: example-backend registration + seeds + docs
-  - Description: env-gated BillingApp; test-mode setup guide; how-to + reference docs
-  - Files: `example-backend/src/server.ts`, `docs/how-to/add-billing.md`, `docs/reference/billing.md`
-  - Depends on: Phase 2
-  - Acceptance: docs build + `bun run rules:check` pass
-- [ ] **Task 4.3**: CI + publish wiring
-  - Description: billing-ci workflow; publish-on-tag entry
-  - Files: `.github/workflows/*`
-  - Depends on: 1.1
-  - Acceptance: CI green

package/dist/docs/versioned/next/tasks/comms-abstraction.md

@@ -1,77 +0,0 @@
-# Tasks: Pluggable communications layer (@terreno/comms)
-
-IP: [comms-abstraction](../implementationPlans/comms-abstraction.md)
-
-## Phase 1 — Package + contracts
-
-- [ ] **Task 1.1**: Scaffold `@terreno/comms` workspace package
-  - Description: `comms/` package with tsconfig/biome/bun test setup mirroring `feature-flags/`; root workspace entry + `comms:*` scripts
-  - Files: `comms/package.json`, `comms/tsconfig.json`, `comms/biome.jsonc`, root `package.json`
-  - Depends on: none
-  - Acceptance: `bun run comms:compile` and `bun run comms:lint` pass
-- [ ] **Task 1.2**: Provider interfaces and message types
-  - Description: `MailProvider`, `SmsProvider`, `PushProvider`, `VerificationProvider`, `SendResult`, `DeliveryEvent` per IP
-  - Files: `comms/src/types.ts`
-  - Depends on: 1.1
-  - Acceptance: types compile and are exported
-- [ ] **Task 1.3**: Console adapters
-  - Description: dev adapters for all four channels logging via `logger.info`
-  - Files: `comms/src/adapters/console.ts` + tests
-  - Depends on: 1.2
-  - Acceptance: each adapter returns `accepted: true` and logs
-- [ ] **Task 1.4**: `CommsMessage` model + `logSend`
-  - Description: delivery log model with five-type pattern, `description` on every field, plugins, static `logSend` that never throws
-  - Files: `comms/src/models/commsMessage.ts` + tests
-  - Depends on: 1.1
-  - Acceptance: send logging survives a forced model error (logged, not thrown)
-- [ ] **Task 1.5**: `commsService` send facade
-  - Description: `sendMail`/`sendSms`/`sendPushToUser`/`startVerification`/`checkVerification`; template render helper; unconfigured-channel behavior (501 in prod, console fallback in dev)
-  - Files: `comms/src/commsService.ts`, `comms/src/templates.ts` + tests
-  - Depends on: 1.2, 1.3, 1.4
-  - Acceptance: unit tests cover happy path + unconfigured channel in both env modes
-
-## Phase 2 — CommsApp + routes
-
-- [ ] **Task 2.1**: `PushToken` model
-  - Description: model per IP with unique token upsert semantics
-  - Files: `comms/src/models/pushToken.ts` + tests
-  - Depends on: 1.1
-  - Acceptance: duplicate token registration updates the existing row
-- [ ] **Task 2.2**: `CommsApp` TerrenoPlugin
-  - Description: options wiring, `getCommsService()` accessor, route mounting on `register()`
-  - Files: `comms/src/commsApp.ts` + tests
-  - Depends on: 1.5, 2.1
-  - Acceptance: plugin registers on `TerrenoApp` and service accessor returns configured providers
-- [ ] **Task 2.3**: Push token routes
-  - Description: modelRouter with `preCreate` owner injection, `OwnerQueryFilter`, deactivate on delete
-  - Files: `comms/src/routes/pushTokens.ts` + supertest
-  - Depends on: 2.2
-  - Acceptance: acceptance criteria bullets 2 pass under supertest
-- [ ] **Task 2.4**: Admin delivery explorer
-  - Description: `GET /comms/messages` admin-only, paginated, filtered; OpenAPI builder
-  - Files: `comms/src/routes/commsExplorer.ts` + supertest
-  - Depends on: 2.2
-  - Acceptance: non-admin gets 403; filters work
-- [ ] **Task 2.5**: `sendPushToUser` token resolution + pruning
-  - Description: resolve active tokens per user; deactivate tokens whose `SendResult` reports permanent failure
-  - Files: `comms/src/commsService.ts` + tests
-  - Depends on: 2.1, 1.5
-  - Acceptance: dead token is `active: false` after a failed send
-
-## Phase 3 — Integration + docs
-
-- [ ] **Task 3.1**: example-backend registration
-  - Description: register `CommsApp` with console adapters; env-gated
-  - Files: `example-backend/src/server.ts`
-  - Depends on: 2.2
-  - Acceptance: backend boots; `/comms/pushTokens` in `/openapi.json`
-- [ ] **Task 3.2**: Reference docs + rules
-  - Description: `docs/reference/comms.md`, rulesync source rule, `bun run rules`
-  - Files: `docs/reference/comms.md`, `.rulesync/**`
-  - Depends on: 2.x
-  - Acceptance: `bun run rules:check` passes
-- [ ] **Task 3.3**: CI + publish wiring
-  - Description: `comms-ci` workflow; add `@terreno/comms` to `publish-on-tag.yml`
-  - Files: `.github/workflows/comms-ci.yml`, `.github/workflows/publish-on-tag.yml`
-  - Depends on: 1.x
-  - Acceptance: CI green on the PR

package/dist/docs/versioned/next/tasks/comms-adapter-expo-push.md

@@ -1,29 +0,0 @@
-# Tasks: Comms adapter — Expo push notifications
-
-IP: [comms-adapter-expo-push](../implementationPlans/comms-adapter-expo-push.md)
-
-- [ ] **Task 1**: `ExpoPushProvider` implementation
-  - Description: token validation, chunked send, ticket collection per IP
-  - Files: `comms/src/adapters/expoPush.ts`
-  - Depends on: comms-abstraction Phase 1
-  - Acceptance: mocked-client tests pass, one `SendResult` per token
-- [ ] **Task 2**: Receipt polling → `DeliveryEvent` + dead-token marking
-  - Description: poll receipts after configurable delay; map `DeviceNotRegistered` to permanent failure
-  - Files: `comms/src/adapters/expoPush.ts`
-  - Depends on: Task 1
-  - Acceptance: dead token deactivated in test
-- [ ] **Task 3**: Dependency moves
-  - Description: optional peer `expo-server-sdk` on comms; remove from `@terreno/api`
-  - Files: `comms/package.json`, `api/package.json`, root catalog if needed
-  - Depends on: Task 1
-  - Acceptance: `bun install` + full compile pass; api tests unaffected
-- [ ] **Task 4**: example-frontend token registration + dev test-send
-  - Description: register token on login via `POST /comms/pushTokens`; profile dev row triggers `sendPushToUser`
-  - Files: `example-frontend/app/_layout.tsx` or profile screen, `example-backend` dev route
-  - Depends on: Task 1, comms-abstraction Phase 2
-  - Acceptance: UI verification per verify-ui-changes with screenshots
-- [ ] **Task 5**: Docs
-  - Description: adapter section in `docs/reference/comms.md` with env/config table
-  - Files: `docs/reference/comms.md`
-  - Depends on: Task 1
-  - Acceptance: docs build passes

package/dist/docs/versioned/next/tasks/comms-adapter-sendgrid.md

@@ -1,29 +0,0 @@
-# Tasks: Comms adapter — transactional email (SendGrid)
-
-IP: [comms-adapter-sendgrid](../implementationPlans/comms-adapter-sendgrid.md)
-
-## Phase 1 — Send path
-
-- [ ] **Task 1.1**: `SendGridMailProvider` with config + sandbox mode
-  - Description: constructor/env config, from-address fallback chain, sandbox default under test
-  - Files: `comms/src/adapters/sendgrid.ts`
-  - Depends on: comms-abstraction Phase 1
-  - Acceptance: mocked-client tests for text/html/template sends
-- [ ] **Task 1.2**: Error mapping
-  - Description: 4xx → `accepted: false` + message; full response body into `CommsMessage.metadata`; never throws
-  - Files: `comms/src/adapters/sendgrid.ts`
-  - Depends on: 1.1
-  - Acceptance: unverified-sender and bad-address fixtures covered
-- [ ] **Task 1.3**: Peer dep + registration + docs
-  - Description: optional peer `@sendgrid/mail`; env-gated example-backend registration with fail-fast; reference + env docs incl. sender-verification checklist
-  - Files: `comms/package.json`, `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
-  - Depends on: 1.1
-  - Acceptance: boot without key skips registration; compile passes without the SDK installed
-
-## Phase 2 — Delivery events (gated on inbound-webhooks)
-
-- [ ] **Task 2.1**: Event Webhook route
-  - Description: ECDSA signature verification via inbound-webhooks; delivered/bounce/dropped/open → `DeliveryEvent`
-  - Files: `comms/src/adapters/sendgrid.ts`, webhook registration
-  - Depends on: inbound-webhooks IP
-  - Acceptance: signed fixture updates `CommsMessage.status`; unsigned rejected 401

package/dist/docs/versioned/next/tasks/comms-adapter-twilio-sms.md

@@ -1,29 +0,0 @@
-# Tasks: Comms adapter — Twilio SMS
-
-IP: [comms-adapter-twilio-sms](../implementationPlans/comms-adapter-twilio-sms.md)
-
-## Phase 1 — Send path
-
-- [ ] **Task 1.1**: `TwilioSmsProvider` with config resolution
-  - Description: constructor/env config, messaging-service-first sender selection
-  - Files: `comms/src/adapters/twilioSms.ts`
-  - Depends on: comms-abstraction Phase 1
-  - Acceptance: mocked-client tests cover both sender configs
-- [ ] **Task 1.2**: E.164 validation + error mapping
-  - Description: `libphonenumber-js` normalization; Twilio error codes into `SendResult.error` + metadata
-  - Files: `comms/src/adapters/twilioSms.ts`
-  - Depends on: 1.1
-  - Acceptance: invalid number → 400 before API call; API failure → `accepted: false`
-- [ ] **Task 1.3**: Peer dep + example-backend registration + docs
-  - Description: optional peer `twilio`; env-gated registration; reference + env-var docs
-  - Files: `comms/package.json`, `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
-  - Depends on: 1.1
-  - Acceptance: compile + boot without twilio installed when unconfigured
-
-## Phase 2 — Delivery callbacks (gated on inbound-webhooks)
-
-- [ ] **Task 2.1**: Status callback route
-  - Description: webhook endpoint with Twilio signature verification via inbound-webhooks framework
-  - Files: `comms/src/adapters/twilioSms.ts`, webhook registration
-  - Depends on: inbound-webhooks IP
-  - Acceptance: signed payload updates `CommsMessage.status`; unsigned rejected 401

package/dist/docs/versioned/next/tasks/comms-adapter-twilio-verify.md

@@ -1,19 +0,0 @@
-# Tasks: Comms adapter — Twilio Verify (OTP)
-
-IP: [comms-adapter-twilio-verify](../implementationPlans/comms-adapter-twilio-verify.md)
-
-- [ ] **Task 1**: `TwilioVerifyProvider` start/check
-  - Description: provider per IP with config resolution and status mapping
-  - Files: `comms/src/adapters/twilioVerify.ts`
-  - Depends on: comms-abstraction Phase 1
-  - Acceptance: mocked-client tests for approved/pending/expired/max-attempts
-- [ ] **Task 2**: Redacted logging
-  - Description: `CommsMessage` rows with channel `verification`, last-4 destination, no codes
-  - Files: `comms/src/adapters/twilioVerify.ts`
-  - Depends on: Task 1
-  - Acceptance: log assertion tests prove no code/full destination in any row
-- [ ] **Task 3**: Registration + docs
-  - Description: env-gated example-backend registration; fail-fast on missing service SID; reference + env docs
-  - Files: `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
-  - Depends on: Task 1
-  - Acceptance: boot without config skips registration; with partial config throws at startup

package/dist/docs/versioned/next/tasks/infra-mcp.md

@@ -1,43 +0,0 @@
-# Tasks: Infrastructure MCP server (`@terreno/infra-mcp`)
-
-Plan: [docs/implementationPlans/infra-mcp.md](../implementationPlans/infra-mcp.md)
-Status: Blocked — Phase 1 RBAC wiring depends on the RBAC module PR ([rbac-permissions.md](../implementationPlans/rbac-permissions.md)). Scaffold/adapter tasks marked (unblocked) can start now.
-
-## Phase 1 — Read-only core
-
-- [ ] (unblocked) Scaffold `infra-mcp/` workspace package: package.json (catalog deps), tsconfig, biome, bun test setup, root workspace + catalog entries (zod 4, `@modelcontextprotocol/server`, `@better-auth/oauth-provider`, `@better-auth/mcp`)
-- [ ] (unblocked) `src/config.ts`: `defineInfraMcp` config schema (zod), secret resolution (env/Secret Manager), boot validation
-- [ ] (unblocked) `src/server.ts`: Express/TerrenoApp server with SDK v2 `/mcp` endpoint (`createMcpHandler`, `legacy: "stateless"`, `toNodeHandler`) + `/health`
-- [ ] (unblocked) `src/auth.ts`: Better Auth OAuth 2.1 setup — authorization server, RFC 9728 protected-resource metadata, bearer verification middleware; login page flow verified with Cursor and Claude Code
-- [ ] `src/access.ts`: `infraStatements`, default roles (`infra-readonly`, `infra-operator`), `createAccess` wiring, `Mcp-Name`-keyed authz middleware, per-user filtered `tools/list` (**blocked on RBAC PR**)
-- [ ] `src/models/infraAuditLog.ts` + audit middleware around `tools/call` (statuses: allowed/denied/confirmed/rejected/error; per-tool arg redaction)
-- [ ] (unblocked) Integration adapter types + registry (`src/integrations/types.ts`, `registry.ts`)
-- [ ] (unblocked) GCP native adapter (ADC): `gcp_query_logs`, `gcp_list_log_names`, `gcp_query_metrics`, `gcp_list_error_groups`, `gcp_list_cloud_run_services`, `gcp_get_cloud_run_service`
-- [ ] (unblocked) Sentry native adapter (REST + static token): `sentry_search_issues`, `sentry_get_issue`, `sentry_list_issue_events`, `sentry_get_event`
-- [ ] (unblocked) Mongo native adapter (read URI): `mongo_list_collections`, `mongo_collection_schema`, `mongo_find`, `mongo_aggregate` (reject `$out`/`$merge`). Extract the shared read-query/schema logic from `mcp-server/src/local/tools/databaseQuery.ts` + `databaseSchema.ts` into a reusable module both packages import — do not fork copies into infra-mcp (per architectural review)
-- [ ] Admin panel registration (`@terreno/admin-backend`): Users, InfraAuditLog (read-only)
-- [ ] Terraform: `infra_mcp_service` Cloud Run module instance, Artifact Registry, runtime SA with viewer/logging IAM only
-- [ ] Tests: authz matrix (role × tool × tools/list filtering), adapter handlers, audit records, legacy-client fallback
-- [ ] Deploy + end-to-end verification from a real MCP client; docs: `.cursor/rules/infra-mcp/00-infra-mcp.mdc`, AGENTS.md/CLAUDE.md package lists
-- [ ] Roadmap: open the tracking issue from [roadmap-seed-issues.md](../explanation/roadmap-seed-issues.md#infra-mcp) once the IP is Approved, add it to the Terreno Roadmap board, and register `@terreno/infra-mcp` → `area:mcp` in `scripts/issueAreaLabels.ts` + the bug-report package dropdown when the package lands
-
-## Phase 2 — Write tier + machine callers
-
-- [ ] `confirmWrite` elicitation wrapper; fail-closed behavior for clients without elicitation support
-- [ ] Config override (`confirmWrites: false`) gated by `infra:writeUnconfirmed`; tests for both paths
-- [ ] Write tools: `sentry_resolve_issue`, `sentry_assign_issue`, `gcp_rollback_cloud_run_revision`, `gcp_update_cloud_run_traffic`, `mongo_update_one`, `mongo_delete_one`; widen runtime SA IAM minimally
-- [ ] Service tokens: spike Better Auth `apiKey` plugin; fallback `ServiceToken` model; machine users (`isServiceAccount`) with role assignment; admin surface (token shown once)
-- [ ] Cloud agent migration: `INFRA_MCP_URL` + service token in agent environments; verify log-digging flows; remove `GCP_SA_*` injection; update AGENTS.md Cursor Cloud instructions
-
-## Phase 3 — Proxied adapters + remaining vendors
-
-- [ ] `ProxiedAdapter`: `@modelcontextprotocol/client` (stdio + HTTP), deny-by-default `allowedTools` with mandatory tier annotations, tool name prefixing, upstream lifecycle management
-- [ ] Reference proxied integration (`@sentry/mcp-server` stdio or `@google-cloud/observability-mcp`) with parity tests against native tools
-- [ ] Expo/EAS native adapter (`EXPO_TOKEN`): build status, update status, submission status (read); trigger tools deferred to write expansion
-- [ ] Vercel native adapter (API token): deployments, logs, project info (read)
-
-## Phase 4 — OSS packaging
-
-- [ ] `defineInfraMcp` config reference + quickstart docs (website); one-man-shop deploy path (container anywhere)
-- [ ] Publish `@terreno/infra-mcp`; changelog + upgrade notes
-- [ ] Dogfood writeup: our deployment as the reference architecture

package/dist/docs/versioned/next/tasks/native-module-baseline.md

@@ -1,42 +0,0 @@
-# Tasks: Native module baseline for the next major release
-
-IP: [native-module-baseline](../implementationPlans/native-module-baseline.md)
-
-## Phase 1 — Dependencies + config
-
-- [ ] **Task 1.1**: Catalog + app package manifests
-  - Description: add the seven packages to root catalog (sorted) and to example-frontend + demo deps via `catalog:`
-  - Files: root `package.json`, `example-frontend/package.json`, `demo/package.json`
-  - Depends on: none
-  - Acceptance: `bun install` + full compile green
-- [ ] **Task 1.2**: Config plugins + build properties
-  - Description: stripe + purchases plugins; `expo-build-properties` Kotlin 2.x / compileSdk 36 pins
-  - Files: `example-frontend/app.json`, `demo/app.json`
-  - Depends on: 1.1
-  - Acceptance: `expo config` resolves without errors; web export unaffected
-
-## Phase 2 — Builds + verification
-
-- [ ] **Task 2.1**: EAS dev builds
-  - Description: iOS + Android dev-client builds via existing eas-dev-build workflow
-  - Files: `eas.json` profiles if needed
-  - Depends on: Phase 1
-  - Acceptance: both builds compile
-- [ ] **Task 2.2**: Diagnostics story
-  - Description: hidden demo story listing resolved native module versions
-  - Files: `demo/stories/NativeModules.stories.tsx`, `demo/demoConfig.tsx`
-  - Depends on: 2.1
-  - Acceptance: story shows all seven modules on a dev build; screenshot evidence
-- [ ] **Task 2.3**: Expo Go degradation doc
-  - Description: document which flows need a dev build (stripe, local-auth) vs preview modes (purchases)
-  - Files: `docs/` upgrade note draft
-  - Depends on: 2.1
-  - Acceptance: reviewed checklist in the note
-
-## Phase 3 — Release
-
-- [ ] **Task 3.1**: Upgrade note + major release coordination
-  - Description: consumer checklist (rebuild dev clients, add plugins, merchant id); breaking-release CI gate
-  - Files: upgrade notes location per release process
-  - Depends on: Phase 2
-  - Acceptance: breaking-release CI gate passes on the release PR

package/dist/docs/versioned/next/tasks/orgs-and-teams.md

@@ -1,70 +0,0 @@
-# Tasks: Organizations, teams, and multi-tenant scoping
-
-IP: [orgs-and-teams](../implementationPlans/orgs-and-teams.md)
-
-## Phase 1 — Models + plugin
-
-- [ ] **Task 1.1**: Organization + Membership models
-  - Description: schemas per IP (five-type pattern, descriptions, plugins, compound unique index), statics `findActiveForUser`/`isMember`/`isOrgAdmin`
-  - Files: `api/src/orgs/organizationModel.ts`, type files
-  - Depends on: none
-  - Acceptance: unit tests incl. duplicate-membership rejection
-- [ ] **Task 1.2**: `orgScopedPlugin`
-  - Description: adds required indexed `organizationId` to a schema
-  - Files: `api/src/orgs/orgPlugin.ts`
-  - Depends on: 1.1
-  - Acceptance: plugin test on a sample schema; save without org fails
-
-## Phase 2 — Context + permissions
-
-- [ ] **Task 2.1**: Org context middleware
-  - Description: `X-Organization-Id` → `req.organization`/`req.membership`; 403 on non-membership; no header → no context
-  - Files: `api/src/orgs/orgContext.ts`
-  - Depends on: 1.1
-  - Acceptance: supertest for member/non-member/missing header
-- [ ] **Task 2.2**: `IsOrgMember`, `IsOrgAdmin`, `OrgQueryFilter`
-  - Description: permission methods + query filter (header-scoped or all-memberships)
-  - Files: `api/src/orgs/orgPermissions.ts`
-  - Depends on: 2.1
-  - Acceptance: **tenant isolation suite** — org A member never reads org B rows, incl. crafted `$or`/query-param attempts
-- [ ] **Task 2.3**: modelRouter integration + `preCreate` org injection helper
-  - Description: end-to-end org-scoped CRUD on a test model
-  - Files: `api/src/orgs/*`, `api/src/tests.ts`
-  - Depends on: 2.2
-  - Acceptance: create injects context org; list/read/update/delete respect scope
-
-## Phase 3 — Routes + app
-
-- [ ] **Task 3.1**: `OrgsApp` plugin + org CRUD routes
-  - Description: create (with `maxOrgsPerUser`), list-my-orgs, read, patch, soft delete with membership cascade
-  - Files: `api/src/orgs/orgsApp.ts`
-  - Depends on: Phase 2
-  - Acceptance: supertest per route; OpenAPI entries present
-- [ ] **Task 3.2**: Member management routes + last-admin guards
-  - Description: list/patch/delete members; cannot demote/remove last admin
-  - Files: `api/src/orgs/orgsApp.ts`
-  - Depends on: 3.1
-  - Acceptance: guard tests pass
-- [ ] **Task 3.3**: `onOrgAudit` hook + exports
-  - Description: audit hook mirroring `onAdminAudit`; public exports from `@terreno/api`
-  - Files: `api/src/orgs/orgsApp.ts`, `api/src/index.ts`
-  - Depends on: 3.1
-  - Acceptance: hook fires for create/role-change/delete in tests
-
-## Phase 4 — Example + docs
-
-- [ ] **Task 4.1**: example-backend org-scoped `Project` model + routes + seeds
-  - Description: demo model with `orgScopedPlugin` + `OrgQueryFilter`; seed two orgs with distinct data
-  - Files: `example-backend/src/models/project.ts`, `src/api/projects.ts`, `scripts/seed*`
-  - Depends on: Phase 3
-  - Acceptance: seeded backend proves isolation via curl/supertest
-- [ ] **Task 4.2**: Admin registration + SDK regen
-  - Description: register Organization/Membership in AdminApp; `cd example-frontend && bun run sdk`
-  - Files: `example-backend/src/server.ts`, `example-frontend/store/openApiSdk.ts`
-  - Depends on: 4.1
-  - Acceptance: admin panel lists orgs; SDK compiles
-- [ ] **Task 4.3**: Docs
-  - Description: `docs/how-to/add-organizations.md`, reference updates, rulesync
-  - Files: `docs/how-to/add-organizations.md`, `docs/reference/api.md`, `.rulesync/**`
-  - Depends on: Phase 3
-  - Acceptance: `bun run rules:check` passes

package/dist/docs/versioned/next/tasks/password-reset-and-email-verification.md

@@ -1,60 +0,0 @@
-# Tasks: Password reset and email verification
-
-IP: [password-reset-and-email-verification](../implementationPlans/password-reset-and-email-verification.md)
-
-## Phase 1 — Token infrastructure
-
-- [ ] **Task 1.1**: `AuthToken` model + issue/consume statics
-  - Description: hashed single-use tokens with TTL expiry per IP
-  - Files: `api/src/authTokens.ts`, type files
-  - Depends on: none
-  - Acceptance: atomic single-use test (parallel consumes → one winner); expiry test
-- [ ] **Task 1.2**: `emailVerificationPlugin`
-  - Description: `emailVerified` field plugin for user schemas
-  - Files: `api/src/plugins.ts`
-  - Depends on: none
-  - Acceptance: plugin test; example User adopts it
-
-## Phase 2 — JWT routes + mail
-
-- [ ] **Task 2.1**: forgot/reset routes
-  - Description: 202-always forgot; reset validates+consumes token, `setPassword`, invalidates refresh tokens; RTK client path/shape contract verified
-  - Files: `api/src/authRecovery.ts`, `api/src/auth.ts`
-  - Depends on: 1.1, comms-abstraction
-  - Acceptance: enumeration-safety + happy-path supertest; RTK-shape test
-- [ ] **Task 2.2**: verification routes + `requireEmailVerification` option
-  - Description: sendVerification/verifyEmail; 403 `email-not-verified` gating on login when enabled
-  - Files: `api/src/authRecovery.ts`, `api/src/auth.ts`
-  - Depends on: 1.2, 2.1
-  - Acceptance: gating on/off supertest
-- [ ] **Task 2.3**: Mail templates
-  - Description: `resetPassword` + `verifyEmail` templates with app-override hook and `publicAppUrl` links
-  - Files: `comms/src/templates.ts`
-  - Depends on: comms-abstraction Phase 1
-  - Acceptance: rendered output snapshot tests
-
-## Phase 3 — Better Auth parity
-
-- [ ] **Task 3.1**: Better Auth hooks
-  - Description: `sendResetPassword`/`sendVerificationEmail` wired to the same templates
-  - Files: `api/src/betterAuthSetup.ts`
-  - Depends on: 2.3
-  - Acceptance: parity test asserting identical template usage
-
-## Phase 4 — Client + docs
-
-- [ ] **Task 4.1**: example-frontend reset screen + verify banner
-  - Description: `/resetPassword` route + profile banner with re-send; SDK regen
-  - Files: `example-frontend/app/resetPassword.tsx`, `app/(tabs)/profile.tsx`, `store/openApiSdk.ts`
-  - Depends on: Phase 2
-  - Acceptance: end-to-end flow with console adapter; UI verification evidence per verify-ui-changes
-- [ ] **Task 4.2**: `LoginScreen` forgot-password link prop
-  - Description: optional `onForgotPassword` on `@terreno/ui` LoginScreen
-  - Files: `ui/src/login/LoginScreen.tsx` + tests + demo story
-  - Depends on: none
-  - Acceptance: renders only when provided; story added
-- [ ] **Task 4.3**: Docs
-  - Description: how-to + env reference + rulesync
-  - Files: `docs/how-to/password-reset.md`, `docs/reference/environment-variables.md`, `.rulesync/**`
-  - Depends on: Phase 2
-  - Acceptance: `bun run rules:check` passes

package/src/docs/upgrades/0.31.0.md

@@ -1,60 +0,0 @@
-# 0.31.0
-
-Terreno packages move in lockstep. Nothing in this release removes or renames a public
-export, so most apps upgrade by bumping the `@terreno/*` versions and running:
-
-- `bun run compile` and `bun run lint` at the repo root
-- `cd <your frontend> && bun run sdk` after any `@terreno/api` route or model surface change
-
-## Mongoose 9 is now supported (Mongoose 8 still works)
-
-Every published package that talks to Mongoose (`api`, `test`, `admin-backend`, `ai`,
-`feature-flags`) widened its peer dependency to `^8.0.0 || ^9.0.0`. Terreno itself
-develops against Mongoose 9.7.4.
-
-You can stay on Mongoose 8 with no changes. If you upgrade your app to Mongoose 9, the
-changes that mattered inside Terreno will most likely matter in your code too:
-
-```typescript
-// Before (Mongoose 8)
-await Model.findOneAndUpdate(filter, update, {new: true});
-
-// After (Mongoose 9)
-await Model.findOneAndUpdate(filter, update, {returnDocument: "after"});
-```
-
-- Aggregation-pipeline updates must pass `updatePipeline: true` to `updateMany`.
-- Query middleware no longer takes the legacy `next()` callback — use the async form.
-- Array schema paths expose `getEmbeddedSchemaType()`; the private `caster` property is gone.
-- Mongoose 9 ships its own types, so `@types/mongodb` and
-  `@types/passport-local-mongoose` should be removed from your dev dependencies.
-- Pin `bson` to `7.2.0` if your lockfile resolves an older copy alongside Mongoose 9.
-
-Mongoose 9 requires Node >= 20.19.0. Terreno's root `package.json` now declares that
-engine range for local development.
-
-## `@terreno/api` type changes
-
-Both changes widen or relax types; they are source-compatible for normal usage, but
-explicit annotations may need updating:
-
-- `modelRouter` now accepts `Model<T, any, any, any, any, any>` instead of `Model<T>`,
-  so models with custom query helpers, methods, or virtuals no longer need a cast.
-- `findOneOrNoneFor(model, query)` takes `ModelQuery<T>` (a partial record keyed by the
-  document fields) instead of Mongoose's `FilterQuery<T>`. If you were building a
-  `FilterQuery<T>` value to pass in, it still works; if you were annotating the variable
-  as `FilterQuery<T>` and relying on operator typing, switch to `ModelQuery<T>`.
-
-## `@terreno/admin-backend` array field metadata
-
-`GET /admin/config` derives array item metadata (`itemType`, `itemRef`, `itemEnum`) from
-Mongoose's public `getEmbeddedSchemaType()` when available, falling back to the Mongoose 8
-`caster` shape. `itemEnum` is only emitted when the embedded enum is an array, so an enum
-declared as an object map no longer produces a malformed `itemEnum`. Admin clients that
-read `itemEnum` should treat it as optional.
-
-## License changed from Apache-2.0 to MIT
-
-All published `@terreno/*` packages are now MIT licensed and ship a `LICENSE` file in the
-package tarball. No code change is required; update any license inventory or attribution
-list that pinned Terreno as Apache-2.0.

package/src/docs/versioned/next/explanation/deployment-architecture-gcp.md

@@ -1,65 +0,0 @@
-# GCP deployment architecture
-
-Reference topology for hosting a Terreno full-stack app on Google Cloud Platform.
-
-This page is conceptual — commands live in the [how-to guides](../how-to/deploy-to-gcp.md).
-
-## Topology
-
-```mermaid
-flowchart TD
-  U["User<br/>iOS / Android / Web"]
-  CDN["Cloud CDN + GCS bucket<br/>expo export -p web output"]
-  CR["Cloud Run<br/>@terreno/api backend"]
-  SM["Secret Manager<br/>auth secrets, MONGO_URI"]
-  AT["MongoDB Atlas<br/>replica set (change streams)"]
-  GCS["GCS bucket<br/>user file uploads"]
-  AR["Artifact Registry<br/>backend image"]
-  U -->|"web"| CDN
-  U -->|"native app"| CR
-  CDN -->|"API calls"| CR
-  CR --> SM
-  CR --> AT
-  CR --> GCS
-  AR --> CR
-```
-
-## Component responsibilities
-
-| Component | Role |
-|-----------|------|
-| **Artifact Registry** | Stores versioned backend container images built from `example-backend/Dockerfile` |
-| **Cloud Run** | Runs the long-lived `@terreno/api` process (HTTP + Socket.io) |
-| **Secret Manager** | Holds `MONGO_URI`, JWT secrets, and other credentials — mounted as env vars |
-| **MongoDB Atlas** | Primary database; must be a replica set for change streams (realtime, feature flags) |
-| **GCS (web bucket)** | Serves static web export; CDN caches at the edge |
-| **GCS (uploads bucket)** | Private object storage for user uploads via `@terreno/api` file plugins |
-
-## Why Cloud Run (not App Engine or GKE)
-
-| Option | Tradeoff |
-|--------|----------|
-| **Cloud Run** | Pay-per-use, minimal ops, supports WebSockets with session affinity — fits Terreno's socket + HTTP model |
-| **App Engine** | Similar serverless model but less flexible for custom containers and long timeouts |
-| **GKE** | Full control but requires cluster management — overkill for a single Terreno backend |
-
-## Why Atlas (not self-hosted Mongo on GCP)
-
-| Option | Tradeoff |
-|--------|----------|
-| **MongoDB Atlas** | Managed replica sets, backups, and change streams out of the box |
-| **Self-hosted on Compute Engine** | You operate replica set elections, backups, and upgrades — documented as out of scope for launch |
-
-## Static web vs server-rendered
-
-| Approach | Tradeoff |
-|----------|----------|
-| **GCS + CDN (static export)** | Cheapest, simplest, works today with Expo `single`/`static` output — no SSR or API routes |
-| **Node/Bun server (SSR)** | Better SEO and API routes — requires Expo SDK ≥ 55; not available in the current `~54` catalog |
-
-Native iOS and Android apps call Cloud Run directly; only the web client uses the CDN origin.
-
-## Related
-
-- [Deployment baseline](deployment-baseline.md) — seven requirements every host must satisfy
-- [Deploy to GCP](../how-to/deploy-to-gcp.md) — step-by-step guides