@terreno/mcp 0.28.0 → 0.30.0

package/src/docs/versioned/0.29.0/implementationPlans/docs-tutorials-ai-first.md

@@ -0,0 +1,145 @@
+# Implementation Plan: AI-First Tutorials
+
+**Status:** Draft — blocked on PR #869
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`docs-reference-coverage`](docs-reference-coverage.md), [`ai-dev-loop-boost`](ai-dev-loop-boost.md), [`deployment-foundation`](deployment-foundation.md)
+**RTK deprecation flag:** **Blocked** — every tutorial writes frontend data code. Must be written against the merged syncdb + Better Auth surface.
+
+## Goal
+
+Give a new developer a learning path, and make the AI-assisted path the default one. Today `docs/tutorials/` contains a single 45-line page that says "run the example full stack" and omits `bun run bootstrap`, the required environment variables, the MongoDB replica-set requirement, and the seeded login credentials — meaning a new user following it exactly will fail at step two. There is no tutorial anywhere for the MCP server, the AI package, the admin panel, or deploying.
+
+The Diátaxis split matters here: tutorials teach by doing a complete thing; how-to guides solve one problem for someone who already knows the system. Terreno has how-to guides and no tutorials.
+
+## Non-Goals
+
+- Video content.
+- Reference documentation (owned by [`docs-reference-coverage`](docs-reference-coverage.md)).
+- The blog-post app build (owned by [`build-terreno-app-validation`](build-terreno-app-validation.md), which consumes these tutorials as its input).
+- Teaching React Native, Expo, or MongoDB fundamentals — link out instead.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Question | Decision |
+|---|----------|----------|
+| T1 | Examples vs bootstrap entry | **C** — two entry points on the tutorials index |
+| T2 | Agent assumed? | **A** — agent-first; manual steps in collapsible sections |
+| T3 | Tutorial app | **B** — new small app (not todos, not the blog-post app) |
+| T4 | Deploy target in tutorial | **A** — Vercel, **pending [`deploy-to-vercel`](deploy-to-vercel.md) spike** (interim split topology until V1 closes) |
+| T5 | MongoDB setup | **B (Atlas) + local Mongo** — no Docker |
+
+## Architecture
+
+### The tutorial set
+
+| # | Tutorial | Time | Teaches |
+|---|----------|------|---------|
+| 0 | `run-the-examples.md` | 10 min | The stack exists and works; what each package does |
+| 1 | `your-first-app.md` | 30 min | Bootstrap → model → route → screen → running on web and phone |
+| 2 | `build-with-ai.md` | 30 min | MCP setup, generators, `read_logs`/`last_error`, the fix loop |
+| 3 | `add-ai-features.md` | 25 min | `@terreno/ai`: streaming chat, structured output, request logging |
+| 4 | `add-an-admin-panel.md` | 20 min | `AdminApp` registration, admin screens, admin-only permissions |
+| 5 | `deploy-your-app.md` | 25 min | Vercel deploy (topology per deploy-to-vercel spike), env vars, first production login |
+
+Every tutorial ends with: what you built, what to read next, and the corresponding reference page.
+
+### Fixing the getting-started gap
+
+`docs/tutorials/getting-started.md` becomes `run-the-examples.md` and gains the five things it is missing:
+
+1. `bun run bootstrap` (not `bun install` — packages must be compiled)
+2. `MONGO_URI` plus Better Auth secrets (`BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`) — tutorials target syncdb + Better Auth only per program P7; do not document the legacy JWT path
+3. That MongoDB **must** be a replica set, with the symptom when it is not
+4. `bun run backend:seed` and the seeded credentials
+5. That the web app shows one-time Terms/Privacy/Consent modals (including a signature draw) before the main screen — a first-run surprise that reads as a bug
+
+### The AI tutorial's arc
+
+Tutorial 2 is the differentiator and needs a real narrative, not a tool list:
+
+1. Wire up both MCP servers (hosted + `terreno-mcp-local`) in the reader's editor.
+2. Ask the agent to add a feature; it calls `terreno_search_docs`, then the generators.
+3. Introduce a deliberate bug (a validation error, a missing permission).
+4. The agent calls `last_error` and `read_logs`, finds it across backend and app sources, fixes it.
+5. Ask the agent to inspect client state (`get_rtk_state` → syncdb equivalent) and navigate the running app.
+6. Regenerate the SDK after the API change and see the typed client update.
+
+Point 4 is the moment the reader understands why this is different from pasting code into a chat window. It depends on Boost (#802) being merged.
+
+### Deferred: `docs/tutorials/README.md`
+
+The tutorials index must state the recommended order and the time budget, and link the how-to tree for readers who already know what they want.
+
+## Models / APIs
+
+None new. Tutorials 1 and 3 create models and routes *in the reader's app*; the tutorial app's schema must be defined in the tutorial itself and kept trivial (one or two models).
+
+## Notifications
+
+None.
+
+## UI
+
+The tutorial app's screens are written by the reader. No changes to `@terreno/ui`.
+
+## Phases
+
+1. **Fix and split the entry point** — `run-the-examples.md` with all five missing pieces; tutorials index.
+2. **`your-first-app.md`** — the core build tutorial.
+3. **`build-with-ai.md`** — depends on merged #802.
+4. **`add-ai-features.md`** and **`add-an-admin-panel.md`**.
+5. **`deploy-your-app.md`** — depends on [`deploy-to-vercel`](deploy-to-vercel.md).
+6. **Validation** — a fresh-environment run of every tutorial, timed, by someone who did not write it.
+
+## Feature Flags & Migrations
+
+None. Renaming `getting-started.md` requires a Docusaurus redirect and an audit of inbound links (`docs/README.md`, `docs/how-to/create-a-model.md`, the MCP resources, and `AGENTS.md` all reference it).
+
+## Not Included / Future Work
+
+- A tutorial for `@terreno/syncdb` offline behavior specifically (the migration guide covers it; a dedicated offline tutorial is a good follow-up).
+- Native build/TestFlight tutorial (the `expo-dev-client` and `expo-deployment` skills cover it).
+- Multi-tenant / organization setup tutorial.
+- Video walkthroughs.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/tutorials/README.md`
+- `docs/tutorials/run-the-examples.md` (from `getting-started.md`)
+- `docs/tutorials/your-first-app.md`
+- `docs/tutorials/build-with-ai.md`
+- `docs/tutorials/add-ai-features.md`
+- `docs/tutorials/add-an-admin-panel.md`
+- `docs/tutorials/deploy-your-app.md`
+
+**Modify**
+
+- `docs/tutorials/getting-started.md` (removed; redirect added)
+- `docs/README.md`, `docs/how-to/README.md`
+- `website/docusaurus.config.ts` (redirect, sidebar order)
+- `mcp-server/src/docs/resources/overview.md` (point agents at the tutorials)
+
+## Task List
+
+See [`docs/tasks/docs-tutorials-ai-first.md`](../tasks/docs-tutorials-ai-first.md).
+
+## Acceptance Criteria
+
+- [ ] Six tutorials exist, each stating its time budget, prerequisites, and what the reader will have built.
+- [ ] `run-the-examples.md` includes `bun run bootstrap`, every required environment variable, the replica-set requirement with its failure symptom, `bun run backend:seed` with the seeded credentials, and a note about the first-run consent modals.
+- [ ] Following `run-the-examples.md` on a clean machine reaches a logged-in web app with no step requiring outside knowledge.
+- [ ] Following `your-first-app.md` produces a working app with one model, CRUD routes, and a list plus detail screen, running on both web and a device or simulator.
+- [ ] `build-with-ai.md` includes the deliberate-bug exercise and the reader observes `last_error` locating it.
+- [ ] `add-ai-features.md` produces a working streaming chat screen and one structured-output call, with requests visible in the `AIRequest` log.
+- [ ] `add-an-admin-panel.md` produces a working admin panel with a registered model and admin-only access verified by logging in as a non-admin.
+- [ ] `deploy-your-app.md` ends with a public URL and a successful login against the deployed backend.
+- [ ] Every tutorial's commands are executed during validation, not just written.
+- [ ] `getting-started.md`'s old URL redirects; no inbound link is broken; `bun run website:build` passes.

package/src/docs/versioned/0.29.0/implementationPlans/examples-demo-coverage.md

@@ -0,0 +1,162 @@
+# Implementation Plan: Examples, Demo, and Test Coverage
+
+**Status:** Draft — key decisions recorded (2026-07-29)
+**Priority:** Medium
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`docs-reference-coverage`](docs-reference-coverage.md) (demo README)
+**RTK deprecation flag:** **Partial** — example-app tasks touch the data layer and are `[RTK]` marked. The demo app is `@terreno/ui`-only and has no data layer, so its tasks are safe now.
+
+## Goal
+
+Close the credibility gaps a prospective adopter checks before trusting a framework: does the component library have visible examples, are the claimed features actually exercised, and does CI enforce the quality bar the project claims.
+
+Three concrete problems today:
+
+1. **The demo app covers roughly 58 of the library's components.** Notable omissions include `GPTChat`, `ActionSheet`, `SplitPage`, `SocialLoginButton`, `DraggableList`, `FilePickerButton`, `Image`, `ModalSheet`, and `UpgradeRequiredScreen`. A component with no visible example is a component people assume is broken. `demo/package.json`'s `test:ci` is `echo 'No tests'`.
+2. **Coverage gates are enforced unevenly.** `api`, `rtk`, and `mcp-server` CI enforce the 95% threshold via `scripts/check-coverage.ts`. `ui`, `ai`, `admin-backend`, `admin-frontend`, `admin-spa`, `feature-flags`, and `api-health` have `test:coverage` scripts but no CI job enforcing them. Three published packages have no dedicated CI workflow at all.
+3. **No public coverage signal.** No badge, no Codecov, so the claim "well tested" is unverifiable from outside.
+
+## Non-Goals
+
+- Raising coverage thresholds.
+- Writing tests for every uncovered line (the daily test-improver workflow already chips at this).
+- Building a fourth example app.
+- Visual regression testing.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Question | Decision |
+|---|----------|----------|
+| E1 | Demo story for every UI component? | **B** — CI-enforced exports + allowlist |
+| E2 | Codecov / badge | **A** |
+| E3 | Dedicated CI per package | **B** — matrix workflow |
+| E4 | Enforce coverage below threshold? | **A** — enforce immediately; failing packages catch up first |
+| E5 | Example feature-parity checklist | **A** |
+
+## Architecture
+
+### Demo story coverage
+
+`demo/` is an Expo Router app where each component demo is a story in `demo/stories/*.stories.tsx` registered in `demoConfig.tsx`. Adding coverage means adding stories and registering them.
+
+The enforcement mechanism: a script that reads the export list from `ui/src/index.tsx`, reads the registered stories from `demoConfig.tsx`, and fails when an exported component has neither a story nor an allowlist entry. Run in `ui-demo-ci.yml`.
+
+Priority for the missing stories — highest-visibility first:
+
+| Priority | Components | Why |
+|----------|-----------|-----|
+| P0 | `GPTChat`, `SocialLoginButton`, `SplitPage` | Directly demonstrate the AI and auth pillars and the responsive web layout |
+| P1 | `ActionSheet`, `ModalSheet`, `FilePickerButton`, `Image` | Common in real apps |
+| P2 | `DraggableList`, `UpgradeRequiredScreen`, remaining gaps | Less common |
+
+Derive the actual missing list from the export list at implementation time rather than trusting this table.
+
+### Coverage enforcement
+
+```mermaid
+flowchart LR
+  S["scripts/check-coverage.ts<br/>(exists)"]
+  T["95% threshold<br/>(per bunfig.toml)"]
+  M["ci: matrix job for packages<br/>without dedicated workflows"]
+  E["existing package CI<br/>api, rtk, mcp, ui, ai, admin-spa"]
+  C["Codecov upload<br/>+ per-PR delta"]
+  S --> T
+  T --> M
+  T --> E
+  M --> C
+  E --> C
+```
+
+Per decision E4, enforce the existing 95% threshold immediately on every published package. Packages currently below threshold must catch up before the gate passes CI — no ratchet floors file. The daily test-improver workflow continues to raise coverage over time.
+
+### Example app feature matrix
+
+The repo states that `example-frontend` and `example-backend` serve as documentation and integration tests. That is only true if it is checked. A matrix in `docs/explanation/example-coverage.md` maps each framework capability to whether an example exercises it:
+
+| Capability | example-backend | example-frontend | Gap |
+|------------|-----------------|------------------|-----|
+| `modelRouter` CRUD | yes | yes | — |
+| Owner permissions | yes | yes | — |
+| Admin panel (embedded) | yes | yes | — |
+| Admin SPA | yes | n/a | — |
+| AI streaming chat | yes | yes | — |
+| AI structured output | ? | ? | verify |
+| Feature flags + live updates | yes | yes | — |
+| Websockets / realtime | yes | yes | — |
+| Consent forms | yes | yes | — |
+| File upload / GCS | yes | yes | — |
+| Better Auth | ? | ? | verify |
+| syncdb local-first | (from #869) | (from #869) | verify after merge |
+| RBAC | no | no | not shipped |
+| Background jobs | no | no | not shipped |
+
+Every `?` must be resolved by reading the example source, and every real gap either filled or recorded as a known gap.
+
+## Models / APIs / Notifications
+
+None.
+
+## UI
+
+New demo stories only. No changes to `@terreno/ui` components except bug fixes discovered while writing stories — which is a common and welcome side effect.
+
+## Phases
+
+1. **Demo coverage** — audit, P0 stories, then the enforcement check.
+2. **Remaining demo stories** — P1 and P2.
+3. **Coverage enforcement** — wire the 95% threshold into every package CI (matrix job for packages without dedicated workflows).
+4. **Codecov** — upload and badges.
+5. **Example feature matrix** — audit and fill or record gaps.
+
+## Feature Flags & Migrations
+
+None. Enforcing the threshold immediately may require a short catch-up period for packages currently below 95%; track that work in the implementation PR rather than lowering the bar.
+
+## Not Included / Future Work
+
+- Visual regression / screenshot testing of the demo.
+- Raising coverage thresholds beyond current levels.
+- Publishing the demo app to app stores.
+- Consolidating the Appium and Maestro E2E suites.
+
+## Files to Create / Modify
+
+**Create**
+
+- `demo/stories/*.stories.tsx` (the missing components)
+- `scripts/check-demo-coverage.ts`
+- `.github/workflows/packages-ci.yml` (matrix for packages without dedicated CI)
+- `docs/explanation/example-coverage.md`
+- `codecov.yml`
+
+**Modify**
+
+- `demo/demoConfig.tsx`
+- `demo/package.json` (`test:ci` currently a no-op)
+- `.github/workflows/ui-demo-ci.yml`, `ui-ci.yml`, `ai-ci.yml`, `admin-spa-ci.yml`
+- `README.md` (coverage badge)
+- `CONTRIBUTING.md` (coverage expectations)
+
+## Task List
+
+See [`docs/tasks/examples-demo-coverage.md`](../tasks/examples-demo-coverage.md).
+
+## Acceptance Criteria
+
+- [ ] Every component exported from `ui/src/index.tsx` has a demo story or an allowlist entry with a stated reason.
+- [ ] `bun run scripts/check-demo-coverage.ts` fails when a newly exported component has no story and no allowlist entry, and runs in `ui-demo-ci.yml`.
+- [ ] `demo/package.json`'s `test:ci` runs something real.
+- [ ] Stories exist for all P0 components, each showing multiple states (default, loading, error, disabled) where applicable.
+- [ ] Every published package's CI runs `scripts/check-coverage.ts` at the 95% threshold.
+- [ ] Packages currently below 95% have a tracked catch-up plan; no package is permanently exempt.
+- [ ] Every published package is covered by CI running its tests and coverage check, either through a dedicated workflow or the matrix job.
+- [ ] Codecov receives uploads from every package's CI and reports per-PR deltas.
+- [ ] `README.md` shows a coverage badge that reflects reality.
+- [ ] `docs/explanation/example-coverage.md` resolves every `?` in the capability matrix, and each real gap is either filled with an example or recorded as a known gap with an issue link.
+- [ ] `CONTRIBUTING.md` states the 95% coverage expectation and how to run coverage locally per package.
+- [ ] `bun run lint`, `bun run compile`, and the full test suite pass.

package/src/docs/versioned/0.29.0/implementationPlans/oss-governance-baseline.md

@@ -0,0 +1,148 @@
+# Implementation Plan: OSS Governance Baseline
+
+**Status:** Approved — decisions recorded (2026-07-29)
+**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/src/docs/versioned/0.29.0/implementationPlans/oss-launch-program.md

@@ -0,0 +1,195 @@
+# Program: Open Source Launch
+
+**Status:** Draft — decisions recorded (defaults accepted 2026-07-29)
+**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-*` agentic SDLC pipeline shipped as an installable plugin — plan, implement test-first, verify in a fresh context, submit with evidence, then own the review loop to mergeable.
+
+   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/flourishhealth/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/flourishhealth/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 and **has never documented it**: `.cursor-plugin/marketplace.json` plus `plugins/terreno-planning/` define an installable five-stage pipeline — **`/terreno-1-grow`** (plan), **`/terreno-2-harvest`** (implement), **`/terreno-3-roast`** (verify), **`/terreno-4-brew`** (submit), **`/terreno-5-taste`** (review loop until mergeable). Legacy names (`blend`, `cupping`, `pour`, `dialin`) remain as aliases during the rename — 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).