@terreno/mcp 57.1.0 → 57.3.0

package/dist/docs/versioned/57.2.0/explanation/deployment-baseline.md

@@ -0,0 +1,78 @@
+# Deployment baseline
+
+Every Terreno production deployment needs the same seven foundations. Provider guides ([Deploy to GCP](../how-to/deploy-to-gcp.md), future Vercel guide) map these to specific platforms; this page names them once.
+
+See also the [environment variables reference](../reference/environment-variables.md).
+
+## Seven baseline requirements
+
+| # | Requirement | Why Terreno needs it | When missing |
+|---|-------------|----------------------|--------------|
+| 1 | **MongoDB replica set** | Change streams power realtime and live feature-flag updates | Startup logs: `FeatureFlag.watch() failed — live updates require MongoDB as a replica set` (`feature-flags/src/featureFlagsApp.ts`) |
+| 2 | **Auth secrets** | JWT signing and sessions (or Better Auth encryption) | Login fails; tokens rejected |
+| 3 | **Long-lived backend process** | Socket.io connections are not request/response | Websockets drop on platforms with short request timeouts or aggressive scale-to-zero |
+| 4 | **Correct origins** | CORS and Better Auth `trustedOrigins` must include your web and native schemes | Browser: blocked by CORS; native: auth redirects fail |
+| 5 | **Build-time client config** | `EXPO_PUBLIC_*` values are inlined into the web bundle at build time | API calls go to `undefined` or localhost after deploy — see [Build for web](../how-to/build-for-web.md) |
+| 6 | **Health endpoint** | Load balancers and orchestrators need readiness probes | Platform marks the service unhealthy and stops routing traffic |
+| 7 | **Durable file storage** | Uploads must not live on ephemeral container disk | Files disappear on restart; use GCS/S3 and credentials |
+
+Requirements **1**, **3**, and **5** are the ones teams miss most often.
+
+### Symptom details
+
+**1 — Standalone MongoDB**
+
+Terreno's feature-flag plugin opens a change stream on startup. Without a replica set, live flag sync is disabled and logs:
+
+```text
+[feature-flags] FeatureFlag.watch() failed — live updates require MongoDB as a replica set (even single-node).
+```
+
+Use [MongoDB Atlas](https://www.mongodb.com/atlas) or a single-node replica set for development.
+
+**3 — Short-lived serverless timeouts**
+
+The RTK/socket client enables reconnection (`reconnection: true`, `reconnectionAttempts: 5` in `rtk/src/socket.ts`). When the backend drops idle connections (for example Cloud Run's default 300s request timeout), clients reconnect but realtime state may lag until the new socket attaches.
+
+**5 — Build-time API URL**
+
+If you set `EXPO_PUBLIC_API_URL` only at runtime on the static host, the bundle still contains whatever was present at `bun run export` time — often `http://localhost:4000`. The browser then fails network requests against localhost.
+
+## Web output modes
+
+Expo Router supports three web output modes. The choice determines hosting options.
+
+| Mode | Output | API routes | SSR | Hosting | Terreno status |
+|------|--------|-----------|-----|---------|----------------|
+| `single` | One `index.html` SPA | No | No | Any static host | **Current default** |
+| `static` | Per-route HTML files | No | No | Any static host | Available; better SEO |
+| `server` | `dist/client` + `dist/server` | Yes | Yes (alpha, SDK ≥ 55) | Node/Bun/edge runtime | Not yet — repo catalog is Expo `~54.0.29`; see [Web SSR and admin SPA](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md) |
+
+## Multi-environment checklist
+
+Staging and production differ in these values (each environment needs its **own web build** because of `EXPO_PUBLIC_API_URL`):
+
+| Item | Where to configure |
+|------|-------------------|
+| Secret values | Platform secret store / Secret Manager |
+| `MONGO_URI` | Separate cluster or database per environment |
+| `EXPO_PUBLIC_API_URL` | Set before `bun run export` — one build per environment |
+| `corsOrigin` | `setupServer({ corsOrigin })` in backend |
+| Better Auth `trustedOrigins` + `BETTER_AUTH_URL` | Better Auth config / env |
+| Feature-flag defaults | MongoDB documents or seed scripts |
+
+## Containerizing the backend
+
+The canonical Dockerfile is [`example-backend/Dockerfile`](https://github.com/FlourishHealth/terreno/blob/master/example-backend/Dockerfile). It:
+
+1. Installs workspace dependencies and compiles packages in dependency order.
+2. Builds a Bun-compiled binary for production.
+3. Runs as a non-root user and exposes `/health` via `@terreno/api-health`.
+
+Three details consumers get wrong:
+
+- **`PORT`** — Cloud Run and other platforms assign the listen port via `PORT`. Terreno reads `process.env.PORT` in `api/src/terrenoApp.ts` (default `9000` if unset).
+- **Non-root** — Do not run the container as root in production.
+- **Compile order** — Workspace packages (`@terreno/api`, `@terreno/test`, etc.) must compile before the example backend bundles.
+
+CI builds the image on every PR that touches backend paths (`.github/workflows/example-backend-docker.yml`).

package/dist/docs/versioned/57.2.0/explanation/local-first-data.md

@@ -0,0 +1,52 @@
+# Local-first data in Terreno
+
+Terreno's default frontend data path is **local-first**: the on-device store is what your UI reads and writes, and the server reconciles changes asynchronously. This is a different mental model from request/response fetching with RTK Query.
+
+## What local-first means here
+
+In `@terreno/syncdb`, a TinyBase `MergeableStore` on the device is the **UI source of truth**. When a user taps "save," the mutation applies to local state immediately and lands in a durable outbox. The client then pushes the change to `@terreno/api` over the sync protocol (socket deltas with HTTP snapshot catch-up). The server remains the **authority** for permissions, validation, and conflict resolution — but the UI does not wait on the network for every write.
+
+There is no server-first mode and no opt-in flag: if you use syncdb, you adopt this model for every synced collection.
+
+## Mental model shift
+
+| Server-first (RTK Query) | Local-first (syncdb) |
+|--------------------------|----------------------|
+| UI reads from cache filled by HTTP | UI reads from the local store |
+| Writes call the API, then invalidate/refetch | Writes apply locally, then reconcile |
+| Loading spinners track request lifecycle | Sync status tracks outbox + connectivity |
+| Optimistic updates are manual and fragile | Optimistic state is the default path |
+| Conflicts are rare / ignored | Conflicts are explicit and must be resolved |
+
+Think **apply locally, then reconcile** instead of **request, wait, update cache**.
+
+## What you stop doing
+
+1. **Manual optimistic updates** — `onQueryStarted` patches, temporary IDs, and rollback logic for writes.
+2. **Write-level loading spinners** — `isLoading` on mutations for "saving…" UX; the row updates instantly.
+3. **Refetch orchestration** — `invalidatesTags`, `refetch()`, and list/detail cache coordination after mutations.
+4. **Treating the network as the read path** — list screens blocked on `isLoading` for every navigation.
+
+RTK Query remains appropriate for **non-synced** endpoints: `/auth/me`, admin RPC, AI routes, and anything that should stay request/response.
+
+## What you start doing
+
+1. **Conflict resolution UI** — When the server rejects a mutation (409 / `sync:nack`), the user must choose a strategy (`useServer` or `keepMine`). Use `ConflictSheet` from `@terreno/ui` or build your own with `useConflicts`.
+2. **Sync-status UX** — Surface offline state, queued mutations, and drain progress with `useSyncStatus` (and optionally `SyncStatusBanner`).
+3. **Encryption at rest (web)** — Web persistence uses AES-GCM via the default `createServerKeyProvider`; understand key fetch and `onDecryptFailure` for support flows.
+4. **Key lifecycle on logout** — Call `syncDb.stop()` and consider `wipeLocalData` when the authenticated user changes so one account does not read another's local store.
+5. **Backend sync registration** — Every synced collection needs `syncPlugin`, `isDeletedPlugin`, and a `sync` block on `modelRouter`, plus `SyncApp` and `RealtimeApp` on the server.
+
+## Tradeoffs
+
+**Gains:** instant UI, offline writes with a durable outbox, simpler screen code, and one write path on the server (sync and REST share `modelRouter`).
+
+**Costs:** larger conceptual surface (conflicts, sync status, local storage), mandatory replica-set MongoDB for realtime, and migration work for existing RTK Query screens.
+
+Server-first fetching is simpler when you only need online CRUD with no offline requirement — but Terreno's blessed path for collection data is local-first.
+
+## Related docs
+
+- [syncdb reference](../reference/syncdb.md) — API ground truth
+- [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md) — step-by-step migration
+- [Authentication architecture](authentication.md) — Better Auth + socket sessions

package/dist/docs/versioned/57.2.0/explanation/loop-engineering.md

@@ -0,0 +1,117 @@
+# Loop engineering
+
+Terreno separates engineering method from orchestration:
+
+```text
+                 LOOP
+       orchestrate / persist / wait
+          retry / stop / escalate
+                  |
+                  v
+               GROW
+               shape
+                  |
+                  v
+               PICK
+               build
+                  |
+                  v
+              ROAST
+               prove
+                  |
+                  v
+               BREW
+              submit
+                  |
+                  v
+              TASTE
+             react once
+```
+
+Repository knowledge composes underneath every invocation:
+
+```text
+lifecycle stage + project skills + IP/task/state + evidence
+```
+
+## Why fresh invocations
+
+One enormous agent context accumulates assumptions, stale external state, and confidence
+in its own implementation. The lifecycle instead makes every stage reconstructable from
+durable artifacts. Pick can retry from exact Roast evidence; Roast can verify without the
+implementer's assumptions; Taste can react to the current PR head rather than an old
+green result.
+
+The outer loop decides **when, who, what next, when to retry, when to wait, and when to
+escalate**. Stages decide how to perform one transition correctly.
+
+## The five transitions
+
+| Stage | Question | Primary evidence |
+| --- | --- | --- |
+| Grow | Is the work shaped and approved? | IP/tasks, decisions, criterion→verification map |
+| Pick | Was this slice implemented carefully? | red/green tests, checks, internal reviews |
+| Roast | Does the result actually satisfy the IP? | independent requirement→evidence verdict |
+| Brew | Is the verified result correctly submitted? | final checks, commit/head, PR, artifacts |
+| Taste | What is actionable on the current PR head now? | CI, mergeability, reviews, bounded fixes |
+
+Roast is not another implementation review. It independently proves or disproves
+acceptance criteria. Taste is not a resident watcher. It observes once, acts once, emits
+`PASS`, `FAIL`, `BLOCKED`, or `PENDING`, then exits.
+
+## Portable plugin, local knowledge
+
+The reusable plugin defines contracts, invariants, evidence, and transitions. Repo-local
+skills define exact API/UI/database patterns, commands, test environments, generated
+code, deployment, and safety rules.
+
+Each stage inspects available skills and loads those whose descriptions match the
+affected domain. A useful skill is optional when absent; a capability required by
+repository policy is a hard gate and produces `BLOCKED` if unavailable.
+
+Stages also load architecture docs before acting. Docs are the design; code implements
+them. Missing docs for a user-visible or architectural change is `FAIL`.
+
+This lets the same Pick method compose with backend API and test-environment knowledge,
+while Roast composes with UI conventions and real-app verification.
+
+### Terreno's current project-skill layer
+
+The canonical sources remain under `.rulesync/skills/` and are generated for supported
+agents. The current high-value composition points include:
+
+| Domain | Repo-local skills stages may discover |
+| --- | --- |
+| Backend/API/data | `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`, `generate-sdk`, `terreno-data-fetching` |
+| UI/app | `terreno-ui`, `building-terreno-apps`, `building-native-ui`, `verify-ui-changes` |
+| AI/prompts | `ai-prompt-governance` |
+| Docs/submission | `update-docs`, `commit`, `create-pr`, `fix-conflicts` |
+| Deployment/runtime | `deploy-gcp`, Expo deployment/workflow skills |
+
+This inventory is descriptive, not a plugin dependency list. Stages inspect the actual
+catalog on every invocation.
+
+## State and evidence
+
+The IP remains the design/scope source of truth. The task file remains the execution
+checklist. Lightweight loop-owned state stores only current stage/attempt/task,
+branch/head/PR, the previous structured result, artifacts, attempted approaches, and next
+transition.
+
+The fallback state location is `.terreno/pipeline/<slug>.json`; the outer loop preserves
+or transports it and Brew excludes it from commits unless repository policy says
+otherwise. Stage results follow the plugin's JSON-schema-backed YAML contract and never
+contain chain-of-thought or transcripts.
+
+## Retry and stop rules
+
+- Roast failure returns exact expected/actual evidence to a fresh Pick.
+- Engineering retries require a new hypothesis and preserve failed approaches.
+- Taste `PENDING` lets the outer loop wait and invoke fresh Taste against current state.
+- Human decisions are `BLOCKED`, never arbitrary retries.
+- Taste `PASS` requires all current-head checks terminal/non-failing, no conflicts, and
+  no actionable review findings.
+
+The detailed contract, schemas, and three execution scenarios live under
+[`plugins/terreno-planning/references/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-planning/references).
+

package/dist/docs/versioned/57.2.0/explanation/positioning.md

@@ -0,0 +1,164 @@
+# Positioning
+
+This is the single source of truth for how Terreno describes itself. The problem
+this page exists to fix is drift: the README, the docs landing page, `AGENTS.md`,
+and the npm package descriptions have historically said different things, so a
+visitor's impression of Terreno depended on which door they walked through.
+
+The rule is simple: **write the wording once, here, then reuse it verbatim
+everywhere else.** Do not paraphrase per surface.
+
+## Canonical copy blocks
+
+Copy these blocks exactly. They are in fenced code blocks so they can be lifted
+without markdown-rendering surprises.
+
+### `tagline`
+
+Used by: README H1 subtitle, docs site `tagline`, npm `description` prefix.
+
+```
+Terreno is Django/Rails for TypeScript — with universal app support.
+```
+
+### `elevator`
+
+Used by: README intro, docs landing intro, package READMEs.
+
+```
+Terreno is Django/Rails for TypeScript — a batteries-included, full-stack
+framework where the undifferentiated 80% of an app is already written. On the
+backend you get Mongoose models, auto-generated REST APIs, permissions, an admin
+panel, authentication, and an AI service. On the frontend you get one universal
+app — a single React Native codebase that ships to iOS, Android, and web. It is
+built to be driven by AI coding agents from the first prompt to a production
+deploy.
+```
+
+### `pillars`
+
+Used by: README, docs landing, `AGENTS.md`. Keep the order.
+
+```
+- Batteries included — auth, CRUD APIs, admin, permissions, AI, realtime,
+  feature flags, and consent are already built, so your code is business logic.
+- Universal by default — one React Native codebase ships to iOS, Android, and
+  web. Not a web framework with a mobile bolt-on.
+- AI-native — agents are a first-class client of the framework, not an
+  afterthought.
+```
+
+### `aiPillar`
+
+Used wherever the AI-native pillar gets more than a bullet. It must always name
+**both** layers (see language rule 5).
+
+```
+Terreno's AI-native story has two layers. The tool layer is a Model Context
+Protocol (MCP) server that gives coding agents codegen, documentation search,
+and component reference for the framework's conventions. The process layer is the
+`/terreno-*` SDLC pipeline — plan, implement test-first, verify in a fresh
+context, submit with evidence, then own the review loop — which today runs inside
+the Terreno repository while its consumer-installable packaging is finished.
+Django gives you `manage.py startapp`; Terreno is building a reviewed path from a
+request to a mergeable pull request.
+```
+
+> **Portability gate (do not remove until cleared).** The `/terreno-*` pipeline
+> is not yet verified to run in a consumer application — that is
+> [`agentic-sdlc-plugin`](../implementationPlans/agentic-sdlc-plugin.md) Task 2.5,
+> which is still open. Until it passes, describe the pipeline as in-progress
+> packaging (as the `aiPillar` block above does) and never imply a consumer can
+> install and run it today. When Task 2.5 passes, update the `aiPillar` block to
+> claim the pipeline as consumer-ready.
+
+### `pitch`
+
+Used by: blog post intros, conference abstracts, social. ~150 words.
+
+```
+Every app needs the same foundation: authentication, user management, CRUD APIs,
+an admin panel, permissions, realtime updates, feature flags, and AI. That work
+is weeks of undifferentiated effort, and it is the same in every product.
+
+Terreno is Django/Rails for TypeScript. Define a Mongoose model, register it, and
+you have a permissioned REST API with pagination, filtering, and an OpenAPI spec.
+Add the admin package and you have a working admin panel. Your app is left with
+the part that is actually yours: the business logic.
+
+The difference from Django or Rails is universal apps — one React Native codebase
+ships to iOS, Android, and web — and being AI-native. Agents are a first-class
+client: an MCP server teaches them the conventions, and a reviewed SDLC pipeline
+takes a request to a mergeable pull request. You build with AI from the first
+prompt to production.
+```
+
+## Why the Django/Rails analogy
+
+Django and Rails won by deciding that the generic parts of a web app — the ORM,
+the router, the admin, auth — belong in the framework, not in every project. They
+are opinionated, batteries-included, and productive because of it. Terreno makes
+the same bet for TypeScript: the generic 80% of an app lives in the framework so
+your codebase is the 20% that is unique to your product.
+
+The analogy earns two honest caveats. First, Terreno targets a document store
+(MongoDB via Mongoose), not a relational ORM, and it has no migrations framework.
+Second, it is younger — several Django/Rails staples (background jobs,
+server-side rendering, role-based access control) are not shipped yet. The
+comparison table below is deliberately straight about where the analogy holds and
+where it does not; being honest about the gaps is what makes the analogy credible
+rather than marketing.
+
+The two things Django and Rails do not give you, and Terreno does, are **universal
+apps** (one codebase for iOS, Android, and web) and being **AI-native** by design.
+
+## Comparison table
+
+Every "shipped" row cites where the feature lives in the source. Every "not
+shipped" row links the implementation plan or roadmap item that tracks it.
+
+| Django / Rails concept | Terreno equivalent | Honest caveat |
+|------------------------|--------------------|----------------|
+| Models + ORM | Mongoose schemas + `@terreno/api` plugins (`api/src/plugins.ts`) | Document store, not relational; no migrations framework (see the Migrations row) |
+| `ModelViewSet` / scaffolds | `modelRouter` (`api/src/api.ts`) | REST only; no GraphQL |
+| Django admin | `@terreno/admin-backend` + `@terreno/admin-frontend` / `@terreno/admin-spa` | Younger; the parity gap is tracked in [`admin-ui-v2-django-parity`](../implementationPlans/admin-ui-v2-django-parity.md) |
+| Auth + permissions | Better Auth (`api/src/betterAuthApp.ts`) + `Permissions` (`api/src/permissions.ts`) | Fine-grained RBAC is in progress ([`rbac-permissions`](../implementationPlans/rbac-permissions.md)) |
+| Templates / views | `@terreno/ui` components — one universal codebase for iOS, Android, and web | Server-side rendering for web is not shipped yet ([`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md)) |
+| `manage.py` / generators | MCP server tools — the *tool* layer (`mcp-server/src/tools.ts`) + the `/terreno-*` SDLC pipeline — the *process* layer (`plugins/terreno-planning/skills/`) | Agent-driven rather than CLI-driven; the pipeline is not yet packaged for consumer apps ([`agentic-sdlc-plugin`](../implementationPlans/agentic-sdlc-plugin.md) Task 2.5) |
+| Celery / ActiveJob (background jobs) | Not shipped | On the [roadmap](../../ROADMAP.md) |
+| Migrations | No migrations framework | Schema evolution is convention plus the `mongoose-schema-safety` skill (`.claude/skills/mongoose-schema-safety/`) |
+
+## Language rules
+
+Every doc, README, landing page, and agent-facing surface follows these rules.
+
+1. **Lead with the analogy.** Say "Django/Rails for TypeScript" within the first
+   two sentences of the README and the docs landing page.
+2. **Say "universal app,"** not "cross-platform" and not "React Native app," when
+   describing the frontend. It is one codebase that ships to iOS, Android, and
+   web.
+3. **Never claim an unshipped feature as available.** If a capability is on the
+   roadmap or tracked by an open IP, say so. Grep the package source before
+   writing that something ships.
+4. **Keep superlatives off reference pages.** "The best framework for X" belongs
+   on the landing page and the pitch, never in reference documentation.
+5. **Never describe one AI layer without the other.** The tool layer (MCP server)
+   and the process layer (`/terreno-*` pipeline) are always named together, and
+   the pipeline is described honestly per the portability gate above.
+
+## Repository metadata (maintainer action)
+
+The GitHub repository description and topics cannot be set from a commit. A
+maintainer must set them in **Settings → General** and the **About** panel.
+
+**Description** (the short tagline variant):
+
+```
+Django/Rails for TypeScript, with universal iOS/Android/web apps.
+```
+
+**Topics:**
+
+```
+typescript, react-native, expo, express, mongoose, framework, mcp, ai, universal-apps, full-stack
+```

package/dist/docs/versioned/57.2.0/explanation/repository-settings.md

@@ -0,0 +1,52 @@
+# Repository settings (maintainers)
+
+Some GitHub settings cannot be committed to the repo. Enable these manually in
+the [Terreno repository settings](https://github.com/FlourishHealth/terreno/settings).
+
+## Discussions
+
+**Path:** Settings → General → Features → Discussions
+
+Enable Discussions and create these categories (see
+[public roadmap IP](../implementationPlans/public-roadmap-github.md) for
+descriptions):
+
+1. Announcements (maintainers only)
+2. Q&A
+3. Ideas
+4. Agents & AI
+5. RFCs
+6. Show and tell
+7. Docs feedback
+
+## Security
+
+**Path:** Settings → Security → Code security and analysis
+
+- Enable **Private vulnerability reporting** (GitHub PVR as the primary channel;
+  `security@terreno.app` is the email fallback — see [SECURITY.md](../../SECURITY.md))
+
+## Branch protection (`master`)
+
+**Path:** Settings → Branches → Branch protection rules → `master`
+
+- Require a pull request before merging
+- Require status checks to pass (include Repository policies, package CI, and
+  Rulesync Check jobs relevant to the change)
+- Require branches to be up to date before merging
+- Do not allow bypassing the above settings
+
+### CircleCI dual-run (in progress)
+
+Package CI / policy / Playwright twins live under `.circleci/` (see
+[how-to/circleci.md](../how-to/circleci.md)). **Keep requiring the existing GitHub
+Actions check names** until a twin is trusted; then add the CircleCI job name and
+remove the GHA workflow. Do not require CircleCI deploy jobs yet (deploys not
+ported).
+
+## Merge settings
+
+**Path:** Settings → General → Pull Requests
+
+- Allow **squash merging** only (disable merge commits and rebase merging)
+- Enable **Automatically delete head branches** after merge