@terreno/mcp 57.0.0 → 57.2.0

package/src/docs/versioned/next/how-to/circleci.md

@@ -0,0 +1,173 @@
+# CircleCI (Terreno)
+
+Dual-run migration from GitHub Actions. See
+[`docs/implementationPlans/migrate-cicd-to-circleci.md`](../implementationPlans/migrate-cicd-to-circleci.md).
+
+**Status (2026-08-20):** CircleCI is **disabled**. GitHub Actions is the CI of
+record. Setup/path-filtering is parked in `.circleci/config.setup.yml`;
+`.circleci/config.yml` is a no-op (`workflows.disabled.when: false`). Real jobs
+remain in `.circleci/continue-config.yml`. To re-enable, copy `config.setup.yml`
+over `config.yml`.
+
+**Parked (2026-08-17):** Phase 1–3 config is in-repo (package CI, repo policy, Playwright
+e2e). **Deploys are not ported yet** (Netlify, GCP CD, EAS, npm publish). GHA remains
+required until CircleCI twins are trusted.
+
+## Project setup (maintainers)
+
+1. Link `FlourishHealth/terreno` in CircleCI (GitHub App).
+2. Default branch: `master`.
+3. Enable **dynamic config** / setup workflows for the project (required for
+   `.circleci/config.yml` `setup: true`).
+4. Build forked PRs if you want DCO + rulesync on forks.
+
+Org/project slug: _(record after Phase 0.1 — e.g. `flourishhealth/terreno`)_.
+
+## Config layout
+
+| File | Role |
+|------|------|
+| `.circleci/config.yml` | Active CircleCI config (currently a disabled no-op) |
+| `.circleci/config.setup.yml` | Parked setup workflow + `path-filtering` (copy over `config.yml` to re-enable) |
+| `.circleci/continue-config.yml` | Real jobs/workflows gated by those params |
+
+Smoke job `config-ok` always runs on continuation.
+
+`.circleci/**` sets `run-circleci-config`, which starts the `circleci-config`
+workflow: one job from each ported family (package CI, policy, example apps,
+`e2e` with `spec: login`, admin-spa). `comms/**` also sets
+`run-example-backend` and `run-example-backend-script`, matching the GitHub
+Actions twins.
+
+## Contexts (create empty shells, then fill)
+
+Do **not** paste secret values into the repo. Create these CircleCI Contexts and restrict
+`terreno-release` to tag/release pipelines when publish is ported.
+
+| Context | Maps from GHA | Used by (planned / current) |
+|---------|---------------|------------------------------|
+| `terreno-npm` | `NPM_TOKEN` | publish (deferred) |
+| `terreno-netlify` | `NETLIFY_*` | deploys (deferred) |
+| `terreno-expo` | `EXPO_TOKEN` | EAS (deferred) |
+| `terreno-gcp` | OIDC / WIF (no long-lived key for CD) | GCP CD (deferred) |
+| `terreno-e2e` | `E2E_TOKEN_SECRET`, `E2E_REFRESH_TOKEN_SECRET`, `E2E_SESSION_SECRET` | `e2e`, `admin-spa-integration` |
+| `terreno-release` | `REPO_ADMIN_TOKEN`, Zoom webhooks | publish (deferred) |
+| `terreno-agentic` | `CURSOR_API_KEY` | agentic replacements (deferred) |
+| `terreno-github-api` | PAT (`pull-requests`, `contents`, …) | `dco`, PR comments later |
+
+Until contexts exist, e2e jobs may use **project env vars for `E2E_*` secrets only**
+(or the in-job `ci-e2e-*-secret` fallbacks). **Do not** put `GITHUB_TOKEN` (or any
+GitHub PAT) in project env vars — those are injected into every job, including
+`bun` scripts from the PR. Create `terreno-github-api`, restrict it to this
+project, leave fork-PR secret passing off, and attach that context **only** to
+`dco` (and later comment jobs). DCO skips if `GITHUB_TOKEN` is unset.
+
+After contexts exist, attach them on the matching jobs in
+`.circleci/continue-config.yml` (see comments in the `workflows:` section).
+
+## Check name map (GHA → CircleCI)
+
+Branch protection still requires **GitHub Actions** names during dual-run. CircleCI
+checks appear as CircleCI job names in the GitHub Checks UI.
+
+| GHA job `name:` / workflow | CircleCI job |
+|----------------------------|--------------|
+| Repository policies / No barrel imports | `no-barrel-imports` |
+| Explicit any baseline | `explicit-any` |
+| License coverage | `license-coverage` |
+| Verify rules are in sync | `rulesync-check` |
+| `dco` | `dco` |
+| Run all tests (API CI) | `api-ci` |
+| Run all tests (AI CI) | `ai-ci` |
+| RTK Lint and Build | `rtk-ci` |
+| UI Lint, Build, Types, and Tests | `ui-ci` |
+| Demo TypeScript Check (UI dependency) | `ui-demo-typecheck` |
+| Demo Lint and TypeScript Check | `ui-demo-ci` |
+| Lint, compile, and test communications | `comms-ci` |
+| Lint, Build, and Test (MCP) | `mcp-server-ci` |
+| Build Docker Image (MCP) | `mcp-server-docker` |
+| Example Frontend Lint and Test | `example-frontend-ci` |
+| Example Backend Lint, Build, and Test | `example-backend-ci` |
+| Run admin script CLI | `example-backend-script-runner` |
+| Build backend Docker image | `example-backend-docker` |
+| Admin SPA Build and E2E | `admin-spa-ci` |
+| E2E · `<spec>` | `e2e` (matrix `spec`) |
+| E2E Load · syncdb-loadlab | `e2e-load` (trigger-gated, see below) |
+| Admin SPA Backend Integration E2E | `admin-spa-integration` |
+| _(new)_ CircleCI path-filter parity | `circleci-parity` |
+| _(smoke)_ | `config-ok` |
+
+Deferred phases keep their GHA checks for now; these are the planned CircleCI job
+names so branch protection can be remapped in one pass later:
+
+| GHA job `name:` / workflow (not yet ported) | Planned CircleCI job |
+|---------------------------------------------|----------------------|
+| Fingerprint gate (`fingerprint-gate.yml`) | `fingerprint-gate` (Phase 5) |
+| EAS PR update/build (`eas-pr.yml`) | `eas-pr` (Phase 5) |
+| EAS dev build (`eas-dev-build.yml`) | `eas-dev-build`, manual pipeline (Phase 5) |
+| CD terraform preview/apply (`cd.yml`) | `cd-terraform`, `cd-deploy` (Phase 6) |
+| Preview cleanup (`preview-cleanup.yml`) | `preview-cleanup` (Phase 6) |
+| Netlify demo / frontend / docs deploys | `deploy-demo`, `deploy-example-frontend`, `deploy-docs` (Phase 4) |
+| Publish on tag (`publish-on-tag.yml`) | `publish-npm` (Phase 7, single-writer cutover) |
+| Appium / Maestro | `appium-android`, `appium-ios`, `maestro` (Phase 8) |
+
+## Path-filter parity guard
+
+`bun run check:circleci-parity` fails when a GHA `paths:` entry has no mapping to
+its CircleCI parameter — otherwise the twin silently never runs. It runs as the
+`circleci-parity` job (CircleCI) and the **CircleCI path-filter parity** job
+(GitHub Actions `repo-policies`). Add new packages/paths to the mapping in
+`.circleci/config.setup.yml` (or `config.yml` when enabled) and to `WORKFLOW_PARAMETERS` in
+`scripts/check-circleci-parity/lib.ts`.
+
+## Config-only changes
+
+When CircleCI is enabled, `.circleci/config.yml` / `continue-config.yml` /
+`example-frontend/playwright.circleci.config.ts` edits set `run-circleci-config`,
+which runs a representative slice (`api-ci`, `ui-ci`, `example-backend-ci`,
+`no-barrel-imports`, `e2e` spec `login`) so config changes are actually exercised
+instead of only hitting the always-on smoke jobs. While disabled, keep the mapping
+in `config.setup.yml` in sync; `check:circleci-parity` reads that file first. CircleCI e2e
+pre-starts a static `bun expo export` on `:8082` (`NODE_OPTIONS=--max-old-space-size=3072`
+for the export only) and reuses it (60s test timeout, `large` Docker). Keeping Metro
+alive next to Chromium gets SIGKILL on 8GB. `xlarge` is not on this project's plan.
+
+## Nightly load test
+
+`e2e-load` (syncdb-loadlab) is never PR-blocking. Trigger the **setup** pipeline
+with `run-e2e-load`. Setup skips path-filtering and continues with a differently
+named continuation parameter (`e2e-load`) so CircleCI does not report conflicting
+pipeline parameters.
+
+```json
+{"run-e2e-load": true}
+```
+
+This replaces the GHA cron / `workflow_dispatch` / `load-test` label triggers in
+`e2e-load-nightly.yml`.
+
+## Local validation
+
+```bash
+circleci config validate .circleci/config.yml
+circleci config validate .circleci/continue-config.yml
+```
+
+## Dual-run drift
+
+While both systems run, keep these in sync when editing a GHA workflow:
+
+1. `paths:` → mapping in `.circleci/config.setup.yml` (or `config.yml` when enabled; enforced by `check:circleci-parity`)
+2. e2e `spec:` matrix → `e2e` workflow matrix in `continue-config.yml`
+3. New package CI workflow → new param + job + `WORKFLOW_PARAMETERS` entry
+
+## Not in this phase
+
+- Netlify / docs / demo / example-frontend **deploys**
+- GCP `cd.yml`, preview-cleanup, OIDC
+- EAS / fingerprint
+- npm publish-on-tag
+- Appium / Maestro
+- CodeQL, Dependabot auto-merge, triage, gh-aw agentics
+
+Keep matching `.github/workflows/*` until dual-run cutover deletes them per phase.

package/src/docs/versioned/next/how-to/configure-better-auth.md

@@ -1,20 +1,23 @@
 # Configure Better Auth
 
-Set up Better Auth as an alternative authentication provider with built-in social OAuth support.
+Set up Better Auth as the **default** authentication provider for new Terreno apps — session-based auth with built-in social OAuth and first-class `@terreno/syncdb` integration.
 
 ## Overview
 
-Better Auth is an optional authentication system that runs **alongside** the existing JWT/Passport authentication. You can choose which authentication provider to use at server startup via environment variables.
+Better Auth is the recommended authentication system for new Terreno frontends. Register `BetterAuthApp` on the backend, set `AUTH_PROVIDER=better-auth`, and wire `createBetterAuthClient` + `generateBetterAuthSlice` on the client. Pair with `betterAuthAdapter` when using `@terreno/syncdb`.
 
-**Use Better Auth when you need:**
+JWT/Passport remains available for legacy deployments (`AUTH_PROVIDER=jwt`). Both can run in parallel during migration.
+
+**Choose Better Auth for:**
+- New apps and greenfield screens
 - Social login (Google, GitHub, Apple)
-- Session-based authentication
-- Modern OAuth 2.0 flows
+- Session-based authentication with `@terreno/syncdb`
+- Socket.io sync via `RealtimeApp` bearer sessions
 
-**Use JWT authentication when you need:**
-- Stateless authentication
-- Simpler token-based auth
-- No social login required
+**Stay on JWT only when:**
+- You have an existing JWT deployment and are mid-migration
+- You require a fully stateless token contract with no session cookies
+- You have custom JWT payload requirements Better Auth cannot satisfy
 
 ## Backend Setup
 
@@ -292,5 +295,5 @@ Better Auth runs **in parallel** with JWT auth. You don't need to migrate existi
 
 - [Authentication Architecture](../explanation/authentication.md)
 - [@terreno/api Reference](../reference/api.md#better-auth)
-- [@terreno/rtk Reference](../reference/rtk.md#better-auth)
+- [@terreno/rtk Reference (legacy)](../reference/legacy/rtk.md#better-auth)
 - [Better Auth Documentation](https://better-auth.com/)

package/src/docs/versioned/next/how-to/expose-mcp-tools.md

@@ -0,0 +1,194 @@
+# Expose Model Context Protocol Tools
+
+Turn a `modelRouter` model into Model Context Protocol (MCP) tools that an LLM can call, reusing the permissions, query filters, population, and lifecycle hooks you already declared for REST.
+
+## Prerequisites
+
+- A working Terreno backend using `TerrenoApp`
+- At least one model registered with `modelRouter`
+
+## Steps
+
+### 1. Add an `mcp` config to a model router
+
+```typescript
+import {modelRouter, OwnerQueryFilter, Permissions} from "@terreno/api";
+
+export const todoRouter = modelRouter("/todos", Todo, {
+  mcp: {
+    excludeFields: ["internalNote"],
+    maxLimit: 25,
+    methods: ["list", "read", "create", "update", "delete"],
+  },
+  permissions: {
+    create: [Permissions.IsAuthenticated],
+    delete: [Permissions.IsOwner],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsOwner],
+    update: [Permissions.IsOwner],
+  },
+  queryFields: ["completed", "title"],
+  queryFilter: OwnerQueryFilter,
+});
+```
+
+`methods` defaults to `["list", "read"]`, and `maxLimit` defaults to 50. A method whose `permissions` array is empty is never exposed as a tool, so REST and MCP cannot drift apart.
+
+### 2. Start the server
+
+`TerrenoApp` mounts `POST /mcp` automatically as soon as any model has an `mcp` config. Every other verb on `/mcp` returns a JSON-RPC 405. No extra registration is needed.
+
+Tools are named `{prefix}_{method}` — `todos_list`, `todos_read`, and so on.
+
+The endpoint speaks the `2026-07-28` MCP revision through the TypeScript SDK v2
+`createMcpHandler`. It is stateless: every request carries its protocol version,
+client identity, and capabilities, so requests can land on any backend instance.
+The SDK's stateless legacy fallback remains enabled, so 2025-era clients continue
+to work while clients migrate.
+
+### 3. Call the tools
+
+Point any MCP client at `POST /mcp` with the user's `Authorization: Bearer <token>` header. Both JWT and Better Auth sessions are accepted; the resolved user is what the permission checks run against, so an LLM can never see more than that user could see over REST.
+
+Authentication is required by default, matching REST. A tool call with no resolvable user is refused before any permission check unless the model router sets `allowAnonymous: true` — the same flag REST passes to `authenticateMiddleware`. That matters for read-only helpers like `IsAuthenticatedOrReadOnly`, which would otherwise pass for an anonymous `list`. Disabled accounts are refused too, as they are over HTTP.
+
+To run the same tools in-process (for example inside a chat route), use `getMCPTools`:
+
+```typescript
+import {getMCPTools} from "@terreno/ai";
+
+const tools = getMCPTools(req.user);
+```
+
+`useMCPTools()` from `@terreno/rtk` uses the official MCP v2 client with automatic
+version negotiation. It no longer constructs JSON-RPC or parses SSE responses by
+hand; the SDK supplies the `2026-07-28` `_meta` envelope and required
+`Mcp-Method` / `Mcp-Name` routing headers.
+
+## Naming tools
+
+The default prefix is the lowercase model name run through a simple pluralizer: `Todo` → `todos`, `Category` → `categories`, `Status` → `statuses`. Irregular nouns need an explicit prefix:
+
+```typescript
+mcp: {toolPrefix: "people"} // person_list -> people_list
+```
+
+## Filtering list results
+
+Only fields listed in `queryFields` can be filtered, exactly as in REST. A filter value may be an exact value or an operator object:
+
+```json
+{"completed": false, "title": {"$in": ["Buy milk", "Walk dog"]}}
+```
+
+Allowed operators are `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$all`, `$size`, `$exists`, and `$regex` (with `$options`). Operators that can execute code or ignore indexes — `$where`, `$expr`, `$function`, `$accumulator`, `$jsonSchema`, `$text` — are rejected with an error rather than silently dropped, so the model can correct itself.
+
+Filters can be combined with top-level `$and` / `$or`, whose branches are validated against `queryFields` too:
+
+```json
+{"$or": [{"completed": true}, {"title": {"$regex": "^Urgent"}}]}
+```
+
+`queryFilter` still runs after the filter is built, so an `OwnerQueryFilter` keeps scoping results to the calling user no matter what the LLM sends.
+
+## Populating references
+
+Population comes from the model router's `populatePaths`, exactly as it does over REST. A tool may pass `populate` to request a **subset** of those declared paths — it can never introduce a new one, so the `fields` allowlist on each declared path always applies and a caller cannot pull back a whole referenced document:
+
+```typescript
+populatePaths: [{fields: ["name", "email"], path: "ownerId"}],
+```
+
+`{"populate": "ownerId"}` is accepted; anything undeclared is refused with an error listing the allowed paths. Models with no `populatePaths` don't get a `populate` parameter at all.
+
+## Hiding fields
+
+`excludeFields` removes fields from both the generated tool schemas and the responses:
+
+- A bare name (`"hash"`) is removed at **every depth**, including inside arrays and populated refs, so a redacted name cannot leak through a nested document.
+- A dot path (`"metadata.secretKey"`) removes exactly that location, following arrays of subdocuments element-wise.
+
+## Customizing responses
+
+`mcpResponseHandler` shapes MCP responses independently of the REST `responseHandler`, which is useful for returning compact summaries to an LLM:
+
+```typescript
+mcp: {
+  mcpResponseHandler: async (value, method) => {
+    if (Array.isArray(value)) {
+      return value.map((todo) => ({id: String(todo._id), title: todo.title}));
+    }
+    return {id: String(value._id), title: value.title};
+  },
+}
+```
+
+`excludeFields` is applied after your handler runs.
+
+## Lifecycle hooks
+
+`preCreate`, `postCreate`, `preUpdate`, `postUpdate`, `preDelete`, and `postDelete` all run for MCP calls. An MCP tool call is JSON-RPC rather than HTTP, so `createMCPRequest` builds a stub Express-shaped `request` (`MCPRequest`):
+
+- `user` — the authenticated MCP user
+- `body` — the hook-stage payload after write denylist + transform, not the raw tool args (on delete, `id` is in `body`, not `params`)
+- `headers` / `query` / `params` — always `{}` (MCP does not forward HTTP headers)
+- `isMCPRequest` — `true`
+
+REST `responseHandler` gets the same stub with an empty `body`.
+
+```typescript
+import type {MCPRequest} from "@terreno/api";
+
+preCreate: (body, req) => {
+  if ((req as unknown as MCPRequest).isMCPRequest) {
+    // e.g. tag records created by an assistant
+    return {...body, source: "assistant"};
+  }
+  return body;
+},
+```
+
+A hook that reads `req.headers` or `req.query` gets an empty object instead of a crash, but anything genuinely HTTP-specific (cookies, IP address) is unavailable — branch on `isMCPRequest` when that matters.
+
+## Logging and error reporting
+
+Every generated tool call emits a structured backend audit log with stable
+`mcpTool`, `mcpMethod`, and `mcpModel` labels plus the active Terreno request
+context (`requestId`, `userId`, and trace fields when present):
+
+- successful calls log at `info` with `durationMs`
+- expected refusals (permissions, not found, invalid filters) log at `warn`
+- caught database, transform, and lifecycle-hook failures log at `error`
+
+When `USE_SENTRY_LOGGING=true`, expected failures are mirrored as Sentry logs.
+Unexpected exceptions and caught internal causes are also captured with
+`Sentry.captureException`, preserving their original stack. The client still
+receives the stable MCP error text — internal exceptions and stack traces stay
+server-side. Tool arguments are not logged.
+
+## Custom tools
+
+CRUD tools cover one model at a time. For a query that spans models, register a custom tool with `registerMCPTool`. It shows up on `POST /mcp` and in `getMCPTools` next to the generated CRUD tools:
+
+```typescript
+import {registerMCPTool} from "@terreno/api";
+import {z} from "zod";
+
+registerMCPTool({
+  name: "users_todo_statuses",
+  description: "List every user with each of their todos and completed status. Admin only.",
+  zodSchema: z.object({}).strict(),
+  handler: async (_args, user) => {
+    if (!user?.admin) {
+      return {
+        content: [{type: "text", text: JSON.stringify({error: "Permission denied: admin required"})}],
+        isError: true,
+      };
+    }
+    // load users + todos and return JSON text
+    return {content: [{type: "text", text: JSON.stringify({users: []})}]};
+  },
+});
+```
+
+The example backend registers this as `users_todo_statuses` from `example-backend/src/api/usersTodoStatus.ts`.

package/src/docs/versioned/next/how-to/install-agent-skills.md

@@ -0,0 +1,46 @@
+# Install agent skills
+
+Install Terreno's agent skills into another repo or agent with the skills CLI.
+
+```bash
+npx skills add FlourishHealth/terreno
+npx skills add FlourishHealth/terreno --skill terreno-1-grow
+```
+
+That copies the committed `skills/` tree: lifecycle stages (Grow, Pick, Roast, Brew,
+Taste), repository skills, and published package skills.
+
+## What you get
+
+| Group | Skills |
+| --- | --- |
+| Lifecycle | `terreno-1-grow` … `terreno-5-taste` |
+| Terreno apps | backend, UI, data, schema, SDK |
+| Docs | `update-docs`, `update-agent-docs`, architecture skills |
+| GitHub | commit, PR, review, verify, release, deploy |
+
+`skills.sh.json` at the repo root groups those names on [skills.sh](https://skills.sh).
+
+## Keep copies in sync (Terreno maintainers)
+
+Canonical sources:
+
+1. `.rulesync/skills/` — repository skills (`bun run rules` generates agent copies)
+2. `plugins/terreno-planning/skills/` — portable lifecycle stages
+3. `<package>/.ai/skills/` — published package skills; these overlay the repo copies
+
+Regenerate the installable tree:
+
+```bash
+bun run skills:sync
+bun run check:lifecycle-skills
+```
+
+Do not hand-edit `skills/`.
+
+## Write human docs with the skills
+
+Skills read architecture docs before changing code. After a user-visible or architectural
+change, update `docs/` in the same slice using `update-docs`. See
+[lifecycle plugin](../reference/lifecycle-plugin.md) and the
+[documentation contract](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/documentation-contract.md).

package/src/docs/versioned/next/how-to/migrate-rtk-to-syncdb.md

@@ -21,6 +21,8 @@ This guide is **AI-context-first**: it is written for an agent (or human) perfor
 
 The example app completed both steps; todos are syncdb-only while profile/admin still use generated RTK hooks.
 
+**Validation (Task 3.5):** The profile screen (`example-frontend/app/(tabs)/profile.tsx`) was reviewed against this guide. `useGetMeQuery` / `usePatchMeMutation` are **non-synced** custom SDK routes — the guide §8 explicitly says to keep them on RTK. No profile migration is required; the guide is sufficient for that case.
+
 Reference: [`docs/reference/syncdb.md`](../reference/syncdb.md), and the package [`syncdb/README.md`](https://github.com/flourishhealth/terreno/blob/release-56.0.0/syncdb/README.md).
 
 ## 2. Install and configure
@@ -318,6 +320,18 @@ Required for Better Auth socket sessions. Legacy JWT sockets continue to work wi
 
 ## 8. Codegen
 
+Synced collections use `bun run sync-sdk`, which runs `terreno-syncdb-codegen` from
+`@terreno/syncdb`. It reads `/openapi.json`, finds list operations tagged
+`x-terreno-sync`, and writes `store/syncDbSdk.ts` (`SYNC_COLLECTIONS` plus friendly
+hooks such as `useTodos` / `useTodo` / `useCreateTodo`). Do not edit that file.
+Custom collections call `createCollectionHooks` in a sibling file. Names are chosen
+so they do not collide with RTK `openApiSdk.ts` during dual-stack migration.
+
+```bash
+# Backend running on port 4000
+cd example-frontend && bun run sync-sdk
+```
+
 ### Does `bun run sdk` still work?
 
 **Yes.** `example-frontend/package.json` still defines:
@@ -332,7 +346,7 @@ It runs `@rtk-query/codegen-openapi` against `openapi-config.ts` and writes `sto
 
 | Still generated | Stop using for migrated collections |
 |-----------------|-------------------------------------|
-| Auth routes, `GET /auth/me`, admin, AI explorer, version config, feature flags | `useGetTodosQuery`, `usePostTodosMutation`, etc. |
+| Auth routes, `GET /auth/me`, admin, AI explorer, version config, feature flags | Collection CRUD — import from `store/syncDbSdk.ts` instead |
 | Custom REST / RPC endpoints | Todo `realtimeList` / `realtimeDocument` wiring in `store/sdk.ts` |
 
 Keep running `bun run sdk` after backend route changes — non-synced screens still import from `store/sdk.ts`.
@@ -342,8 +356,19 @@ Workflow:
 ```bash
 # Backend running on port 4000
 cd example-frontend && bun run sdk
+cd example-frontend && bun run sync-sdk
 ```
 
+### Syncdb hooks codegen
+
+For collections with `sync` enabled on the backend, generate local-first hooks from the same OpenAPI spec:
+
+```bash
+cd example-frontend && bun run sync-sdk
+```
+
+This writes `store/syncDbSdk.ts` with friendly hooks (`useTodos`, `useCreateTodo`, …) that intentionally differ from RTK names so both SDKs can coexist during migration. Import synced screens from `@/store/syncDbSdk`, not `store/sdk.ts`.
+
 ## 9. Feature flags
 
 Post-migration, feature flags stay on `@terreno/rtk` + OpenFeature — **not** on syncdb.

package/src/docs/versioned/next/how-to/websocket-integration.md

@@ -411,6 +411,7 @@ This logs:
 
 ## Related Documentation
 
-- [@terreno/rtk Reference](../reference/rtk.md) — Full API documentation
+- [@terreno/syncdb Reference](../reference/syncdb.md) — Local-first data layer (replaces RTK for synced collections)
+- [@terreno/rtk Reference (legacy)](../reference/legacy/rtk.md) — RTK Query utilities during the support window
 - [Authentication Architecture](../explanation/authentication.md) — JWT system deep-dive
 - [Socket.io Documentation](https://socket.io/docs/v4/) — Official Socket.io docs

package/src/docs/versioned/next/implementationPlans/ModularAPI.md

@@ -1,5 +1,6 @@
 # Modular API Implementation Plan
 
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1084
 ## Overview
 
 This document outlines the implementation plan for a new modular API design in `@terreno/api`. The goal is to create a `TerrenoApp` class that provides a cleaner, more flexible interface for building APIs while maintaining backward compatibility with the existing `setupServer` function.

package/src/docs/versioned/next/implementationPlans/README.md

@@ -7,7 +7,7 @@ An implementation plan (IP) is one half of a two-file pair:
 
 | File | Holds | Path |
 | ---- | ----- | ---- |
-| **IP** | Design goals, architecture, models/APIs, phases, acceptance criteria | `docs/implementationPlans/<slug>.md` |
+| **IP** | Design goals, architecture, models/APIs, testing decisions, phases, acceptance criteria | `docs/implementationPlans/<slug>.md` |
 | **Task list** | The bot-consumable execution checklist for that IP | `docs/tasks/<slug>.md` |
 
 The IP is the source of truth for *what and why*; the task list is the source of truth
@@ -15,11 +15,12 @@ for *the concrete steps*. External trackers (a GitHub roadmap issue, a Linear is
 discussion thread) link **to** these files — they never replace them. See
 [`docs/tasks/README.md`](../tasks/README.md) for the task-file shape.
 
-## The live index
+## Status lives on each IP
 
-[`PLAN_INDEX.md`](PLAN_INDEX.md) is the authoritative list of active, completed, and
-deferred plans — read it, not this page, to see what is current. This README explains the
-process; `PLAN_INDEX.md` tracks the state.
+There is no shared `PLAN_INDEX.md`. That file caused merge conflicts the same way a
+shared changelog Unreleased section did. Status is the `**Status:**` line in each
+`docs/implementationPlans/<slug>.md` (and in `archive/` after close). List those
+directories to see what exists; this README explains the process.
 
 ## When to write an IP
 
@@ -35,34 +36,50 @@ Substantial work is planned before coding. Quick rule (full table in
 
 ## How a plan gets written and built
 
-The [`terreno-planning` plugin](../../plugins/README.md) drives the pipeline:
+The [`terreno-planning` plugin](../../plugins/README.md) drives the pipeline.
 
-1. **Blend** (`terreno-1-blend`) — write the IP + task list, questions first.
-2. **Roast** (`terreno-2-roast`) — implement via TDD from the approved IP.
-3. **Cupping** (`terreno-3-cupping`) — independently verify against the IP.
-4. **Pour** (`terreno-4-pour`) — commit, push, open the PR.
-5. **Dial In** (`terreno-5-dialin`) — drive CI and review until mergeable.
+**Grow** interviews in grilling rounds (one frontier of decisions per message, recommended
+answers, then wait). It stays on a question until the answer is executable. After the user
+confirms shared understanding it writes the two files and ends with a **15-line verify
+index** (destination, in/out, tracer, task graph, test seam). When grilling produced
+human decisions, it lists **every** one in a Decisions table with no row cap. If there
+were none, that table is omitted.
+
+For a small feature, an outer loop may use the plugin's **feature profile**: a compact
+approved task contract, one fresh Pick invocation per frontier task, independent Roast,
+then Brew and bounded Taste iterations. This preserves the former Grind behavior without
+putting orchestration inside a lifecycle skill.
+
+1. **Grow** (`terreno-1-grow`) — grill until answers are executable, then write the IP + tracer-bullet task list; end with the 15-line verify index and a full Decisions table when any exist.
+2. **Pick** (`terreno-2-pick`) — implement one approved slice via TDD.
+3. **Roast** (`terreno-3-roast`) — independently verify the implementation against the IP.
+4. **Brew** (`terreno-4-brew`) — commit, push, open the PR.
+5. **Taste** (`terreno-5-taste`) — react once to current CI, mergeability, and review state.
+
+The outer loop owns stage selection, execution-state persistence, waiting, retries, and
+human/external escalation. Each stage emits the compact machine-readable result described
+in [`plugins/terreno-planning/references/lifecycle-contract.md`](../../plugins/terreno-planning/references/lifecycle-contract.md)
+(collapsed behind a Details toggle in chat and on the PR).
 
 You can also author an IP directly with the `ip` skill; both produce the same two files.
 
 ### Roadmap handoff (roadmap-enabled repos only)
 
 In repos that run a public roadmap (Discussions + a roadmap Project — currently Terreno),
-Blend hands off to `roadmap-item` once the IP is **Approved** to create or update the
+Grow hands off to `roadmap-item` once the IP is **Approved** to create or update the
 public tracking issue, and the IP header records the `Discussion:` and `Roadmap issue:`
 links. See [`docs/explanation/roadmap-process.md`](../explanation/roadmap-process.md) for
 the full IP ↔ roadmap lifecycle.
 
 In repos with **no** roadmap board (Flourish, most consumer apps), the pipeline is
-identical minus that handoff: the IP + task list plus `PLAN_INDEX.md` are the source of
-truth, and Linear tracks execution via the IP header `Linear:` link.
+identical minus that handoff: the IP + task list are the source of truth, and Linear
+tracks execution via the IP header `Linear:` link.
 
 ## Lifecycle
 
-1. **Draft** → **Approved** — IP written and reviewed (status lives in the IP header and
-   `PLAN_INDEX.md`).
+1. **Draft** → **Approved** — IP written and reviewed (status lives in the IP header).
 2. **In progress** → **Complete** — implemented, verified, merged.
-3. **Archive** — completed IPs move to `docs/implementationPlans/archive/` and the index is updated.
+3. **Archive** — completed IPs move to `docs/implementationPlans/archive/`.
 
 Plans that are fully implemented and now describe shipped architecture should be migrated
 to `docs/explanation/` as reference documentation.