@terreno/mcp 57.17.0 → 57.19.2

package/dist/docs/versioned/57.1.0/implementationPlans/orgs-and-teams.md

@@ -1,158 +0,0 @@
-# Implementation Plan: Organizations, teams, and multi-tenant scoping
-
-**Status:** Draft
-**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1024
-**Priority:** High
-**Effort:** Big batch
-**Owner:** unassigned
-**Created:** 2026-08-09
-**Program:** [B2B platform](b2b-platform-program.md)
-**Depends on:** none (soft: [rbac-permissions](rbac-permissions.md) for role vocabulary; this IP ships coarse org roles that RBAC later subsumes)
-**RTK deprecation flag:** None — backend only; frontend surfaces are `org-management-ui`
-
-## Goal
-
-Terreno's entire access story is per-user: `ownerId` fields, `OwnerQueryFilter`,
-`Permissions.IsOwner`. A B2B app needs data owned by an **organization** and accessed by
-its **members**. This IP adds the tenant analog of the owner stack to `@terreno/api`:
-Organization and Membership models, an org-context middleware, an `orgScopedPlugin` for
-schemas, `OrgQueryFilter` and `Permissions.IsOrgMember`/`IsOrgAdmin` for modelRouter, and
-CRUD routes for orgs and memberships — so `modelRouter(Todo, {queryFilter: OrgQueryFilter,
-permissions: {...IsOrgMember}})` is all an app needs for tenant-safe endpoints.
-
-## Non-Goals
-
-- Invitations, seat counting (`invitations-and-seats` item).
-- Fine-grained RBAC (roles beyond `member`/`admin` — [rbac-permissions](rbac-permissions.md)).
-- Org switcher and management screens (`org-management-ui` item).
-- Billing linkage (`billing-stripe` maps customers to orgs later).
-- Cross-org data sharing, nested teams/sub-orgs (future work).
-
-## Decisions
-
-| Question | Decision |
-|----------|----------|
-| **D6 (resolved 2026-08-09):** native Mongoose models vs Better Auth `organization` plugin | **Native models.** The JWT/passport path (still supported and the example default) cannot use a Better-Auth-only construct; native models serve both auth paths, keep modelRouter/query-filter integration first-class, and can sync to Better Auth's plugin later if wanted |
-| Org context transport | `X-Organization-Id` header, resolved by middleware into `req.organization` + `req.membership`; explicit query/body override rejected |
-| One org or many per user? | Many (Membership join collection); apps wanting single-org enforce via option `maxOrgsPerUser: 1` |
-| Coarse roles now | `Membership.role: "admin" \| "member"` — deliberately minimal; RBAC IP replaces this enum with role references, migration documented there |
-| Scoping mechanism | `orgScopedPlugin` adds required indexed `organizationId`; `OrgQueryFilter` filters lists by active memberships; `preCreate` helper injects the context org |
-| Personal orgs? | No auto-created personal org; apps opt in via `createDefaultOrgOnSignup` option |
-
-## Architecture
-
-```
-api/src/orgs/
-  organizationModel.ts   # Organization + Membership schemas/models
-  orgContext.ts          # middleware: header → req.organization/req.membership
-  orgPlugin.ts           # orgScopedPlugin(schema) — organizationId field + index
-  orgPermissions.ts      # IsOrgMember, IsOrgAdmin, OrgQueryFilter
-  orgsApp.ts             # OrgsApp TerrenoPlugin — routes + options
-```
-
-`OrgsApp` options:
-
-```typescript
-new OrgsApp({
-  maxOrgsPerUser?: number;
-  createDefaultOrgOnSignup?: boolean;
-  onOrgCreated?: (org, owner) => Promise<void>;
-})
-```
-
-Request flow: `authenticateMiddleware` → `orgContextMiddleware` (loads org by header,
-verifies an active membership for `req.user`, 403 otherwise) → route. Routes that take
-`Permissions.IsOrgMember`/`IsOrgAdmin` require the context; `OrgQueryFilter` works with or
-without a context (no header → all orgs the user belongs to; header → that org only).
-
-## Models
-
-Both use the five-type pattern, `description` on every field, `createdUpdatedPlugin` +
-`isDeletedPlugin`, `strict: "throw"`.
-
-**Organization** — `name` (string, required), `slug` (string, unique, indexed, generated),
-`ownerId` (ref User, required — the creating user; ownership transferable), `settings`
-(Mixed, app-defined), `disabled` (boolean).
-
-**Membership** — `organizationId` (ref Organization, required, indexed), `userId` (ref
-User, required, indexed), `role` ("admin" | "member", default "member"), `status`
-("active" | "suspended", default "active"), compound unique index on
-`(organizationId, userId)`. Statics: `findActiveForUser`, `isMember`, `isOrgAdmin`.
-
-## APIs
-
-| Method | Path | Permissions | Notes |
-|---|---|---|---|
-| POST | `/orgs` | IsAuthenticated | Creates org + admin membership for creator; respects `maxOrgsPerUser` |
-| GET | `/orgs` | IsAuthenticated | Lists orgs the user belongs to (membership join) |
-| GET | `/orgs/:id` | IsOrgMember | |
-| PATCH | `/orgs/:id` | IsOrgAdmin | name/settings; ownership transfer admin-only |
-| DELETE | `/orgs/:id` | IsOrgAdmin | Soft delete; memberships cascade to suspended |
-| GET | `/orgs/:id/members` | IsOrgMember | Paginated membership list (populated user name/email) |
-| PATCH | `/orgs/:id/members/:memberId` | IsOrgAdmin | Role/status change; cannot demote last admin |
-| DELETE | `/orgs/:id/members/:memberId` | IsOrgAdmin | Remove member; cannot remove last admin |
-
-Member creation is **not** exposed here — members arrive via `invitations-and-seats`
-(or `createDefaultOrgOnSignup`). All routes via modelRouter where shapes fit, custom
-`createOpenApiBuilder` routes for member management.
-
-## Notifications
-
-None in this IP (invitation emails belong to `invitations-and-seats`).
-
-## UI
-
-None in this IP (`org-management-ui`). example-backend gains an org-scoped demo model
-(`Project`) exercising `orgScopedPlugin` + `OrgQueryFilter` end to end.
-
-## Phases
-
-1. **Models + plugin:** Organization, Membership, `orgScopedPlugin`, statics, unit tests.
-2. **Context + permissions:** middleware, `IsOrgMember`/`IsOrgAdmin`, `OrgQueryFilter`,
-   modelRouter integration tests (member of A cannot read B's rows — the critical suite).
-3. **Routes + app:** `OrgsApp`, org/member routes, last-admin guards, OpenAPI, supertest.
-4. **Example + docs:** example-backend `Project` model + routes, seeds, admin panel model
-   registration, `docs/how-to/add-organizations.md`, reference docs, SDK regen.
-
-## Feature Flags & Migrations
-
-No migration for existing apps (new collections; opt-in plugin). Adopting apps that
-backfill `organizationId` onto existing collections get a documented backfill recipe —
-formal tooling arrives with `mongo-migrations`.
-
-## Activity Log & User Updates
-
-Org create/delete and membership role changes fire an `onOrgAudit` hook (mirroring
-`onAdminAudit`) so apps can log them; framework-wide audit persistence is the
-`framework-audit-log` item.
-
-## Not Included / Future Work
-
-- Teams within orgs (the Membership schema reserves a `teamIds` extension point but ships
-  without it — YAGNI until a consumer needs it).
-- Org-level settings UI, domain capture/auto-join (SSO IP touches this).
-- Per-org rate limits, quotas.
-
-## Files to Create / Modify
-
-- `api/src/orgs/*` (new), `api/src/index.ts` exports
-- `api/src/permissions.ts` — export org permissions alongside existing ones
-- `example-backend/src/models/project.ts`, `api/projects.ts`, seeds, `server.ts`
-- `docs/how-to/add-organizations.md`, `docs/reference/api.md`
-- `example-frontend` SDK regen (`bun run sdk`) after backend routes land
-
-## Task List
-
-See [docs/tasks/orgs-and-teams.md](../tasks/orgs-and-teams.md).
-
-## Acceptance Criteria
-
-- [ ] A user can create an org, becoming its admin member; `maxOrgsPerUser` is enforced.
-- [ ] With two orgs seeded, a member of org A listing an org-scoped model with
-      `OrgQueryFilter` never receives org B documents — including via crafted `$or` /
-      query-param attempts.
-- [ ] Requests with an `X-Organization-Id` the user is not an active member of get 403.
-- [ ] The last admin of an org cannot be demoted or removed.
-- [ ] Org routes appear in `/openapi.json`; regenerated SDK compiles; admin panel can
-      browse Organizations and Memberships.
-- [ ] Soft-deleting an org suspends its memberships and hides its scoped data from lists.

package/dist/docs/versioned/57.1.0/implementationPlans/oss-governance-baseline.md

@@ -1,149 +0,0 @@
-# Implementation Plan: OSS Governance Baseline
-
-**Status:** Approved — decisions recorded (2026-07-29)
-**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1003
-**Priority:** High
-**Effort:** Small batch
-**Owner:** unassigned
-**Created:** 2026-07-27
-**Program:** [OSS launch](oss-launch-program.md)
-**Depends on:** none
-**RTK deprecation flag:** None — no framework surface touched. Safe to implement before PR #869.
-
-## Goal
-
-Make the repository legally and procedurally publishable: a license every consumer can rely on, a documented contribution path, a security disclosure process, a living changelog, and GitHub's community-health files. Today the repo has two stray `LICENSE` files (`api/`, `ui/`), one stale `CHANGELOG.md` (`api/`, last entry 0.20.0 against a current 0.26.0), no root license, and no contributing/security/conduct documents.
-
-This is the hard blocker: without it, nothing else in the program can ship publicly.
-
-## Non-Goals
-
-- Rewriting the README's content or positioning — that is [`positioning-django-rails-universal`](positioning-django-rails-universal.md). This IP only *adds* the License / Contributing / Security / Code of Conduct links.
-- Auditing dependency licenses for compatibility.
-- Setting up sponsorship, OpenCollective, or a CLA bot.
-- Changing CI beyond adding license/community-file checks.
-
-## Blocking questions
-
-**Recorded 2026-07-29** (see program [P1–P2](oss-launch-program.md#blocking-questions-program-level)).
-
-| # | Question | Decision |
-|---|----------|----------|
-| G1 | License (→ P1) | **MIT everywhere** — root `LICENSE`, per-package `LICENSE` files, and all `package.json` `license` fields |
-| G2 | Copyright line | **`Copyright 2026 Flourish Health, Inc.`** in `LICENSE`; `NOTICE` credits contributors |
-| G3 | Contributor provenance (→ P2) | **DCO** — `Signed-off-by` enforced by CI on external PRs |
-| G4 | Security contact | **`security@terreno.app`** + GitHub private vulnerability reporting (PVR as primary) |
-| G5 | Changelog strategy | **Root `CHANGELOG.md`** in Keep-a-Changelog format; `api/CHANGELOG.md` becomes a pointer |
-| G6 | Enforce Conventional Commits? | **Yes, CI-enforced** on new PRs |
-| G7 | Code of Conduct | **Contributor Covenant 2.1** with **`conduct@terreno.app`** |
-
-## Architecture
-
-No code architecture. Three groups of artifacts:
-
-1. **Legal** — root `LICENSE`, `NOTICE`, per-package `LICENSE` files, `license` fields in every `package.json`, `files` arrays updated so the license ships in every npm tarball.
-2. **Process** — `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `CHANGELOG.md`, `.github/ISSUE_TEMPLATE/*`, `.github/PULL_REQUEST_TEMPLATE.md`, `CODEOWNERS`.
-3. **Enforcement** — a `repo-policies.yml` job (the workflow already exists) that fails when a published package lacks a `LICENSE` in its `files` array or its `license` field disagrees with the root license.
-
-### Published packages requiring license coverage
-
-From `publish-on-tag.yml`, eleven packages publish in lockstep. Current state:
-
-| Package | `LICENSE` file | In `files` array | `license` field |
-|---------|----------------|------------------|-----------------|
-| `api` | yes | implicit (no `files`) | Apache-2.0 → **MIT** |
-| `ui` | yes | **missing from `files`** | Apache-2.0 → **MIT** |
-| `rtk` | **no** | **missing from `files`** | Apache-2.0 → **MIT** |
-| `ai` | **no** | implicit | Apache-2.0 → **MIT** |
-| `admin-backend` | **no** | implicit | Apache-2.0 → **MIT** |
-| `admin-frontend` | **no** | **missing from `files`** | Apache-2.0 → **MIT** |
-| `admin-spa` | **no** | **missing from `files`** | Apache-2.0 → **MIT** |
-| `api-health` | **no** | implicit | Apache-2.0 → **MIT** |
-| `feature-flags` | **no** | implicit | Apache-2.0 → **MIT** |
-| `mcp-server` | **no** | **missing from `files`** | MIT (already) |
-| `test` | **no** | implicit | Apache-2.0 → **MIT** |
-
-Task 1.2 must re-derive this table from the repo at implementation time rather than trusting it.
-
-## Models
-
-None.
-
-## APIs
-
-None.
-
-## Notifications
-
-None.
-
-## UI
-
-None.
-
-## Phases
-
-1. **Legal baseline** — root license, per-package licenses, `package.json` alignment, CI guard.
-2. **Contribution process** — `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, DCO check.
-3. **Changelog** — root `CHANGELOG.md`, backfill 0.20.0–0.26.0 from GitHub releases, wire into the `release` skill.
-4. **GitHub templates** — issue forms, PR template, `CODEOWNERS`, repo settings checklist.
-
-## Feature Flags & Migrations
-
-None. Relicensing `api` and `ui` from Apache-2.0 to MIT is a one-way change; it requires sign-off from every contributor to those packages who is not a Flourish employee (verify with `git log --format='%an %ae' -- api/ ui/`). `mcp-server` is already MIT.
-
-## Activity Log & User Updates
-
-None.
-
-## Not Included / Future Work
-
-- Dependency license compatibility audit (`bunx license-checker`-style report).
-- `FUNDING.yml` / sponsorship.
-- Automated changelog generation from Conventional Commits.
-- Trademark policy for the Terreno name.
-
-## Files to Create / Modify
-
-**Create**
-
-- `LICENSE`
-- `NOTICE`
-- `CONTRIBUTING.md`
-- `CODE_OF_CONDUCT.md`
-- `SECURITY.md`
-- `CHANGELOG.md`
-- `rtk/LICENSE`, `ai/LICENSE`, `admin-backend/LICENSE`, `admin-frontend/LICENSE`, `admin-spa/LICENSE`, `api-health/LICENSE`, `feature-flags/LICENSE`, `mcp-server/LICENSE`, `test/LICENSE`
-- `.github/ISSUE_TEMPLATE/bug_report.yml`
-- `.github/ISSUE_TEMPLATE/feature_request.yml`
-- `.github/ISSUE_TEMPLATE/docs_issue.yml`
-- `.github/ISSUE_TEMPLATE/config.yml`
-- `.github/PULL_REQUEST_TEMPLATE.md`
-- `.github/CODEOWNERS`
-- `scripts/check-license-coverage.ts`
-
-**Modify**
-
-- `package.json` (root: add `license`)
-- `ui/package.json`, `rtk/package.json`, `admin-frontend/package.json`, `admin-spa/package.json`, `mcp-server/package.json` (`files` + `license`)
-- `api/CHANGELOG.md` (reduce to a pointer at the root changelog)
-- `README.md` (append License / Contributing / Security / Code of Conduct section and badge — content-neutral)
-- `.github/workflows/repo-policies.yml` (add license-coverage job)
-- `.rulesync/skills/release/SKILL.md` (require a root `CHANGELOG.md` entry per release)
-
-## Task List
-
-See [`docs/tasks/oss-governance-baseline.md`](../tasks/oss-governance-baseline.md).
-
-## Acceptance Criteria
-
-- [ ] `LICENSE` exists at the repo root and matches the decision from G1.
-- [ ] Every package in `publish-on-tag.yml` has a `LICENSE` file, a matching `license` field, and ships the license in its npm tarball (verified via `bun pm pack --dry-run` per package).
-- [ ] `bun run scripts/check-license-coverage.ts` exits 0 and fails when a `LICENSE` is deleted from any published package.
-- [ ] `CONTRIBUTING.md` documents: `bun run bootstrap`, how to run tests/lint per package, the no-barrel-imports rule, the IP process, DCO sign-off, and how to propose a change.
-- [ ] `SECURITY.md` lists supported versions and both reporting channels; GitHub private vulnerability reporting is enabled in repo settings.
-- [ ] `CODE_OF_CONDUCT.md` is Contributor Covenant 2.1 with a working report address.
-- [ ] `CHANGELOG.md` has entries for 0.20.0 through the current release, newest first, in Keep-a-Changelog format.
-- [ ] Opening a new issue in the GitHub UI offers Bug / Feature / Docs forms plus a link to Discussions.
-- [ ] `README.md` links License, Contributing, Security, and Code of Conduct above the fold or in a clearly labeled section.
-- [ ] `bun run lint` and `bun run rules:check` pass.

package/dist/docs/versioned/57.1.0/implementationPlans/oss-launch-program.md

@@ -1,204 +0,0 @@
-# Program: Open Source Launch
-
-**Status:** Draft — decisions recorded (defaults accepted 2026-07-29)
-**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1094
-**Priority:** High
-**Effort:** Epic (multiple IPs)
-**Owner:** unassigned
-**Created:** 2026-07-27
-
-Umbrella program for taking Terreno from "internal Flourish monorepo that happens to publish npm packages" to a credible public open-source framework. This document is the index, sequencing plan, and single place where cross-IP decisions get recorded.
-
-Individual IPs live alongside this file; each has a companion task list in `docs/tasks/`.
-
-## Positioning
-
-Every IP in this program must use one consistent positioning statement. The agreed framing:
-
-> **Terreno is Django/Rails for TypeScript — with universal app support.**
->
-> Batteries-included full-stack framework: models, migrations-free schema conventions, auto-generated REST APIs, permissions, admin panel, auth, and an AI service on the backend; one React Native codebase that ships to iOS, Android, and web on the frontend. Built to be driven by AI coding agents from the first prompt to production deploy.
-
-Three pillars, in priority order:
-
-1. **Batteries included** (the Django/Rails claim) — the undifferentiated 80% of an app is already written: auth, CRUD, admin, permissions, AI, realtime, feature flags, consent.
-2. **Universal by default** (the differentiator vs Django/Rails) — one codebase, three platforms. Not a web framework with a mobile bolt-on.
-3. **AI-native** (the differentiator vs everything) — two layers, and the docs must present them as complementary:
-   - the **tool layer**: an MCP server with codegen, docs search, and runtime introspection (logs, client state, navigation), plus per-package agent guidelines;
-   - the **process layer**: the `/terreno-*` lifecycle shipped as an installable plugin —
-     shape, implement test-first, verify in a fresh context, submit with evidence, then
-     react once per current PR state while an outer loop owns waiting and reinvocation.
-
-   Agents are a first-class client of the framework, not an afterthought. Django gives you `manage.py startapp`; Terreno gives you a reviewed path from a request to a mergeable PR.
-
-Language rules for all docs:
-
-- Say "Django/Rails for TypeScript" in the first two sentences of the README and docs landing page.
-- Say "universal app" (not "cross-platform", not "React Native app") when describing the frontend.
-- Never claim features listed under "Where Terreno is headed" as shipped.
-- Avoid "the best framework for X" superlatives in reference docs; keep those to the landing page.
-
-## RTK deprecation gate
-
-**`@terreno/rtk` is being replaced.** PR [#869](https://github.com/TerrenoLabs/terreno/pull/869) (`@terreno/syncdb` local-first data layer) makes **Better Auth + `@terreno/syncdb`** the supported frontend platform. RTK Query becomes legacy.
-
-**Program-wide rule: IPs flagged `Blocked` may not be implemented until #869 merges.** Writing docs against RTK now guarantees a rewrite. Planning (this program) proceeds; implementation of `None`-flagged IPs may start before #869; `Partial` IPs proceed except for `[RTK]`-marked tasks.
-
-Each IP carries an explicit flag:
-
-| Flag | Meaning |
-|------|---------|
-| **None** | No RTK/Better Auth surface. Safe to implement before #869. |
-| **Partial** | Mostly RTK-independent, but specific tasks touch RTK. Those tasks are marked `[RTK]` in the task file. |
-| **Blocked** | Core content is RTK-shaped. Do not start until #869 merges. |
-
-Every `[RTK]`-marked task in every task file must be reviewed against the merged #869 surface before implementation. The migration content itself is owned by [`rtk-to-syncdb-migration-docs.md`](rtk-to-syncdb-migration-docs.md), which gates most of Wave 1.
-
-### Known RTK-shaped surfaces to re-verify after #869
-
-| Surface | Location | Post-#869 expectation |
-|---------|----------|-----------------------|
-| Frontend data-fetching narrative | `README.md`, `docs/README.md`, `docs/tutorials/getting-started.md` | syncdb local-first reads/mutations |
-| SDK codegen loop | `.rulesync/skills/generate-sdk/SKILL.md`, `example-frontend/openapi-config.ts` | `@terreno/syncdb-codegen` descriptors |
-| Auth story | `docs/how-to/configure-better-auth.md`, `docs/explanation/authentication.md` | Better Auth primary, JWT legacy |
-| `docs/reference/rtk.md` | reference tree | **Removed from launch reference** (P7 A); migration guide only |
-| `get_rtk_state` MCP tool | `mcp-server/src/local/tools/runtime.ts` (PR #802) | Rename/extend to syncdb store inspection |
-| `installTerrenoDevConsoleLogger` | `rtk/src/devConsoleLogger.ts` (PR #802) | Move to syncdb or a shared client package |
-| Feature-flag client hooks | `docs/reference/feature-flags.md`, `rtk/src/` | OpenFeature provider fed by syncdb |
-| Offline queue | `rtk/src/` offline middleware | Superseded by syncdb outbox |
-
-## Boost dependency (AI story)
-
-PR [#802](https://github.com/TerrenoLabs/terreno/pull/802) (MCP Boost parity, Phases 4–6) is **assumed merged** by the AI-facing IPs. It delivers the runtime half of the AI story:
-
-- `read_logs` merging backend / app (CDP) / Metro / browser sources
-- `last_error` across sources
-- `get_rtk_state` (→ syncdb state post-#869)
-- `evaluate` and `navigate` over CDP, gated by `TERRENO_MCP_EVAL=1`
-- Dev-only `POST /__terreno/browser-logs` ingestion in `@terreno/api`
-
-Combined with the already-shipped hosted tools (`terreno_search_docs`, `terreno_get_component_docs`, `terreno_bootstrap_app`, generators, `terreno_get_upgrade_guide`), this is the "agent can build, run, observe, and fix a Terreno app without a human reading logs" claim. [`ai-dev-loop-boost.md`](ai-dev-loop-boost.md) owns telling that story.
-
-## The `/terreno-*` SDLC pipeline
-
-The repo already ships the process half of the AI story: `.cursor-plugin/marketplace.json`
-plus `plugins/terreno-planning/` define five bounded transitions —
-**`/terreno-1-grow`** (shape), **`/terreno-2-pick`** (build),
-**`/terreno-3-roast`** (prove), **`/terreno-4-brew`** (submit), and
-**`/terreno-5-taste`** (react once). The outer loop owns persistence, waiting, retry, and
-escalation. Former command names are a documented hard-cut migration — see
-[`agentic-sdlc-plugin.md`](agentic-sdlc-plugin.md).
-
-It encodes real judgment rather than automation: a question-first planning gate that refuses to commit to decisions before they are answered, independent review and test-quality sub-agents spawned in **fresh contexts** after every commit, drift detection against the plan, anti-mocking rules, a hard frontend-evidence gate, and a refusal to push speculative fixes for flaky CI.
-
-Two problems block using it as a launch asset, both owned by [`agentic-sdlc-plugin.md`](agentic-sdlc-plugin.md):
-
-1. **It is invisible.** No `plugins/README.md`, no docs page, no mention in `README.md` or `AGENTS.md`. The audit that produced this program missed it entirely — which is exactly what every prospective user will do.
-2. **It only works inside this monorepo.** Repo-root-relative sibling-skill paths, a dependency on a `verify-ui-changes` skill that lives in `.rulesync/`, hardcoded monorepo package names in the frontend gates, and a hardcoded branch suffix. Publishing it without fixing these ships tooling that breaks on first use in a consumer app.
-
-## IP index
-
-### Wave 0 — unblocked, can start immediately
-
-| IP | Title | RTK flag | Why now |
-|----|-------|----------|---------|
-| [oss-governance-baseline](oss-governance-baseline.md) | License, contributing, security, changelog, templates | None | Legal blocker for any public launch; zero framework surface |
-| [public-roadmap-github](public-roadmap-github.md) | GitHub Discussions + Projects roadmap + Linear bridge | None | Needed before inviting outside contributors; process-only |
-| [deploy-to-gcp](deploy-to-gcp.md) | Generalized GCP deploy docs + `deploy-gcp` skill | None | Backend + static hosting only; no client data layer |
-| [agentic-sdlc-plugin](agentic-sdlc-plugin.md) | Publish, port, and document the `/terreno-*` pipeline | Partial | Already built and shipping; only the frontend path lists touch the data layer |
-
-### Wave 1 — gated on #869 (syncdb) merging
-
-| IP | Title | RTK flag | Depends on |
-|----|-------|----------|------------|
-| [rtk-to-syncdb-migration-docs](rtk-to-syncdb-migration-docs.md) | Deprecation policy, migration guide, reference restructure | Blocked | #869 |
-| [positioning-django-rails-universal](positioning-django-rails-universal.md) | Positioning rewrite across README, docs site, agent rules | Partial | rtk-to-syncdb-migration-docs |
-| [docs-reference-coverage](docs-reference-coverage.md) | `ai.md`, `syncdb.md`, `admin-spa.md`, de-stub package READMEs | Blocked | rtk-to-syncdb-migration-docs |
-| [docs-tutorials-ai-first](docs-tutorials-ai-first.md) | Getting-started rewrite + 4 new tutorials | Blocked | docs-reference-coverage, ai-dev-loop-boost |
-| [deployment-foundation](deployment-foundation.md) | Deployment architecture, env reference, backend Dockerfile | Partial | — |
-| [deploy-to-vercel](deploy-to-vercel.md) | Vercel deploy docs + `deploy-vercel` skill | Partial | deployment-foundation |
-| [upgrade-guides-and-skill](upgrade-guides-and-skill.md) | `upgrading-terreno` skill, backfill 0.22–0.26 notes, release gate | Blocked | rtk-to-syncdb-migration-docs |
-| [ai-dev-loop-boost](ai-dev-loop-boost.md) | AI-native story built on Boost #802 | Partial | #802 |
-| [build-terreno-app-validation](build-terreno-app-validation.md) | `build-terreno-app` skill run + blog post | Blocked | docs-tutorials-ai-first, ai-dev-loop-boost |
-| [examples-demo-coverage](examples-demo-coverage.md) | Demo README, missing stories, CI coverage gates | Partial | — |
-
-### Wave 2 — independent feature work
-
-| IP | Title | RTK flag | Notes |
-|----|-------|----------|-------|
-| [web-ssr-and-admin-spa](web-ssr-and-admin-spa.md) | Server-side rendering for universal web + admin-spa migration | Partial | Can be planned/prototyped in parallel; ships after Wave 1 docs stabilize |
-
-## Suggested sequencing
-
-```mermaid
-flowchart TD
-  subgraph w0 ["Wave 0 — now"]
-    gov["oss-governance-baseline"]
-    road["public-roadmap-github"]
-    gcp["deploy-to-gcp"]
-    plug["agentic-sdlc-plugin"]
-  end
-  syncdb["PR #869 syncdb merges"]
-  boost["PR #802 Boost merges"]
-  subgraph w1 ["Wave 1 — after #869"]
-    mig["rtk-to-syncdb-migration-docs"]
-    pos["positioning-django-rails-universal"]
-    ref["docs-reference-coverage"]
-    ai["ai-dev-loop-boost"]
-    tut["docs-tutorials-ai-first"]
-    upg["upgrade-guides-and-skill"]
-    dep["deployment-foundation"]
-    ver["deploy-to-vercel"]
-    demo["examples-demo-coverage"]
-    build["build-terreno-app-validation"]
-  end
-  ssr["web-ssr-and-admin-spa"]
-  syncdb --> mig
-  boost --> ai
-  mig --> pos
-  mig --> ref
-  mig --> upg
-  ref --> tut
-  ai --> tut
-  dep --> ver
-  tut --> build
-  ai --> build
-  plug --> pos
-  plug --> build
-  ref --> ssr
-```
-
-Launch gate: Wave 0 complete **and** `rtk-to-syncdb-migration-docs`, `positioning-django-rails-universal`, `docs-reference-coverage`, `docs-tutorials-ai-first`, `deploy-to-vercel`, `deploy-to-gcp`, `upgrade-guides-and-skill` complete. `build-terreno-app-validation` is the acceptance test for the whole program — if an agent following only public docs and skills cannot build and deploy the demo app, the launch is not ready.
-
-`agentic-sdlc-plugin` feeds two others: it supplies the process half of the AI-native pillar to `positioning-django-rails-universal`, and once public it becomes something the dogfooding harness in `build-terreno-app-validation` should exercise.
-
-## Blocking questions (program level)
-
-**Recorded 2026-07-29** (defaults accepted for all unspecified items).
-
-| # | Question | Decision |
-|---|----------|----------|
-| P1 | License for the whole monorepo | **MIT everywhere** — relicense `api`/`ui` from Apache-2.0; align `@terreno/mcp` and all published packages |
-| P2 | Copyright / governance model | **B** — Flourish + **DCO** sign-off (`Signed-off-by` on external PRs) |
-| P3 | Public support channel | **A** — GitHub Discussions only at launch |
-| P4 | Hosted MCP URL | **`https://mcp.terreno.app`** — retire `mcp.terreno.flourish.health` before launch |
-| P5 | Flourish-specific infra in the public repo | **C now** — move under `infra/flourish/`; **note to migrate to B** (private repo, generic modules only) post-launch |
-| P6 | Publish `@terreno/rtk` after #869 | **A** — keep publishing with deprecation notice through the current major line; **stop publishing in the next major** |
-| P7 | Launch documentation stack | **A** — **syncdb + Better Auth only** in tutorials, reference, and positioning (no parallel RTK/JWT path in public docs) |
-| P8 | Docs site versioning at launch | **B** — latest + one previous major |
-| P9 | Target npm version for launch | **C** — stay on 0.x; launch on **`0.56.x`** aligned with Expo SDK 56; promise 1.0 after syncdb stabilizes |
-| P10 | Blog post venue | **A** — docs site blog only |
-| P11 | `/terreno-*` SDLC plugin marketplace | **A** — public at launch, gated on portability work in [`agentic-sdlc-plugin.md`](agentic-sdlc-plugin.md) |
-
-**Brand / domain:** public surfaces use **`terreno.app`** (MCP at `mcp.terreno.app`, contacts at `@terreno.app`).
-
-Per-IP blocking questions live in each IP file under `## Blocking questions`.
-
-## Not included / future work
-
-- **Vercel deployment topology spike** — whether `@terreno/api` (Socket.io, change streams, SSE) can run on Vercel in one platform with the web app and file storage, or whether a split host remains required. Tracked as open TODOs in [`deploy-to-vercel.md`](deploy-to-vercel.md); do not document a finalized topology until the spike lands.
-- Actual 1.0 API-stability audit.
-- Trademark/brand review of the "Terreno" name.
-- Paid support, sponsorship, or OpenCollective setup.
-- Conference talks / launch-day marketing beyond the blog post.
-- Migrating internal Flourish apps onto syncdb (tracked separately from the OSS launch).

package/dist/docs/versioned/57.1.0/implementationPlans/password-reset-and-email-verification.md

@@ -1,147 +0,0 @@
-# Implementation Plan: Password reset and email verification
-
-**Status:** Draft
-**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1023
-**Priority:** High
-**Effort:** Big batch
-**Owner:** unassigned
-**Created:** 2026-08-09
-**Program:** [B2B platform](b2b-platform-program.md)
-**Depends on:** [comms-abstraction](comms-abstraction.md), [comms-adapter-sendgrid](comms-adapter-sendgrid.md)
-**RTK deprecation flag:** None — the RTK client's existing `resetPassword` endpoint gets a
-backend at last; new client work is a thin screen pair noted in UI
-
-## Goal
-
-The JWT auth path has no way to recover an account or verify an email address: the
-`@terreno/rtk` client ships a `resetPassword` mutation with **no backend route**, and
-nothing sets or checks email verification. This IP adds forgot/reset password and email
-verification flows to `@terreno/api`'s JWT auth, wires the Better Auth equivalents to the
-same mail templates, and sends everything through `@terreno/comms`.
-
-## Non-Goals
-
-- MFA / step-up auth (`mfa-step-up-auth` item).
-- Magic-link login.
-- SMS-based recovery (possible later via the Twilio Verify adapter).
-- Account lockout / brute-force throttling beyond token single-use + expiry
-  (`rate-limiting` item hardens the endpoints).
-
-## Decisions
-
-| Question | Decision |
-|----------|----------|
-| Token design | 32-byte crypto-random token, stored **hashed** (sha256) with expiry (`1h` reset / `24h` verify) and single-use consumption; separate `AuthToken` collection rather than fields on User |
-| Enumeration safety | `POST /auth/forgotPassword` always returns 202 regardless of whether the email exists |
-| Password set mechanism | `passport-local-mongoose`'s `setPassword` on the user document, then invalidate all refresh tokens |
-| RTK client compatibility | The existing RTK `resetPassword` endpoint's path/shape is the contract — verify at implementation time and alias if it differs from `/auth/resetPassword` |
-| Verification gating | Opt-in `requireEmailVerification` auth option: unverified users get 403 with code `email-not-verified` on login; default off (non-breaking) |
-| Better Auth path | Enable Better Auth's built-in reset/verification, providing `sendResetPassword` / `sendVerificationEmail` hooks that call the same comms templates so both auth paths send identical mail |
-| Link targets | Deep-link/URL base from a new `authOptions.publicAppUrl`; web route examples in example-frontend |
-
-## Architecture
-
-```
-api/src/authTokens.ts      # AuthToken model + issue/consume helpers
-api/src/authRecovery.ts    # forgot/reset/verify routes + options
-                           # registered by addAuthRoutes when comms is available
-comms templates            # resetPassword + verifyEmail templates (subject/text/html)
-```
-
-Flow (reset): `POST /auth/forgotPassword {email}` → 202 always; if user exists, issue
-token, send mail with `${publicAppUrl}/resetPassword?token=...` → `POST
-/auth/resetPassword {token, password}` → validate + consume token, `setPassword`,
-invalidate refresh tokens, 200.
-
-Flow (verify): token issued on signup (and via `POST /auth/sendVerification` for
-re-sends, authenticated); `POST /auth/verifyEmail {token}` sets `user.emailVerified =
-true`.
-
-## Models
-
-**AuthToken** — `userId` (ref User, required, indexed), `tokenHash` (string, unique),
-`type` ("passwordReset" | "emailVerification"), `expiresAt` (date, TTL-indexed),
-`consumedAt` (date, optional). Statics: `issueFor(user, type)`, `consume(token, type)`
-(atomic findOneAndUpdate guarding single-use).
-
-**User** — adds `emailVerified` (boolean, default false) via a small
-`emailVerificationPlugin` so existing user schemas opt in without breaking.
-
-## APIs
-
-| Method | Path | Permissions | Notes |
-|---|---|---|---|
-| POST | `/auth/forgotPassword` | anonymous | `{email}` → always 202 |
-| POST | `/auth/resetPassword` | anonymous | `{token, password}`; path/shape matched to the RTK client contract |
-| POST | `/auth/sendVerification` | IsAuthenticated | Re-send verification mail |
-| POST | `/auth/verifyEmail` | anonymous | `{token}` |
-
-All registered by `addAuthRoutes` when a mail-capable `CommsApp` is present; without one,
-routes 501 in production and console-send in development (inherited comms behavior).
-
-## Notifications
-
-Two mail templates (`resetPassword`, `verifyEmail`) shipped in `@terreno/comms` templates
-with app-override hooks.
-
-## UI
-
-example-frontend: `/resetPassword` (token from URL, new-password form using the existing
-RTK `resetPassword` mutation) and a "verify your email" banner + re-send button on the
-profile screen. `LoginScreen` gains an optional `onForgotPassword` link prop in
-`@terreno/ui`.
-
-## Phases
-
-1. **Token infrastructure:** AuthToken model, issue/consume, `emailVerificationPlugin`,
-   unit tests.
-2. **JWT routes + mail:** four routes, templates, refresh-token invalidation,
-   enumeration-safety + single-use/expiry test suite.
-3. **Better Auth parity:** wire `sendResetPassword`/`sendVerificationEmail` hooks to the
-   same templates; parity tests.
-4. **Client + docs:** example-frontend screens, `@terreno/ui` login link prop, SDK regen,
-   `docs/how-to/password-reset.md`, env/reference docs.
-
-## Feature Flags & Migrations
-
-`requireEmailVerification` defaults off; enabling it for an existing app is documented
-(backfill `emailVerified: true` for existing users or accept re-verification). No schema
-migration otherwise.
-
-## Activity Log & User Updates
-
-Token issue/consume and verification events logged via `logger` and `CommsMessage`
-rows; no user-facing activity feed.
-
-## Not Included / Future Work
-
-- Password strength policy hooks (exists via `PasswordRequirements` UI; server policy is
-  future work).
-- Admin-triggered forced resets (admin panel action — future).
-- Endpoint rate limiting (`rate-limiting` item).
-
-## Files to Create / Modify
-
-- `api/src/authTokens.ts`, `api/src/authRecovery.ts` (new), `api/src/auth.ts`,
-  `api/src/plugins.ts` (emailVerificationPlugin), `api/src/index.ts`
-- `comms/src/templates.ts` — two templates
-- `example-frontend/app/resetPassword.tsx`, profile banner, SDK regen
-- `ui/src/login/LoginScreen.tsx` — `onForgotPassword` prop
-- `docs/how-to/password-reset.md`, `docs/reference/environment-variables.md`
-
-## Task List
-
-See [docs/tasks/password-reset-and-email-verification.md](../tasks/password-reset-and-email-verification.md).
-
-## Acceptance Criteria
-
-- [ ] `POST /auth/forgotPassword` returns 202 for existing and non-existing emails alike,
-      sending mail only for existing ones.
-- [ ] A reset token works exactly once, fails after expiry, and a successful reset
-      invalidates outstanding refresh tokens.
-- [ ] The unmodified RTK client `resetPassword` mutation completes the flow end to end.
-- [ ] With `requireEmailVerification` on, an unverified user gets 403 code
-      `email-not-verified` on login and can complete verification to proceed.
-- [ ] Better Auth mode sends the same two templates through comms.
-- [ ] example-frontend can complete forgot → email link (console adapter output in dev) →
-      reset → login with the new password; UI verification evidence attached to the PR.