@terreno/mcp 57.4.0 → 57.6.1

package/src/docs/versioned/next/reference/api.md

@@ -41,7 +41,7 @@ REST API framework built on Express and Mongoose. Provides modelRouter (CRUD end
 - Validation: `configureOpenApiValidator`, `validateRequestBody`, `validateQueryParams`, `createValidator`
 - Middleware: `openApiEtagMiddleware`, `sentryAppVersionMiddleware`
 - Extensibility: `TerrenoPlugin` interface
-- Notifiers: `sendSlackMessage`, `sendGoogleChatMessage`, `sendZoomMessage`
+- Notifiers: `sendToSlack`, `formatSlackUserMention`, `lookupSlackUserIdByEmail`, `sendToGoogleChat`, `sendToZoom`
 - HTTP client: `createAuthenticatedClient`, `withApiErrorHandling`, `normalizeApiError`, `markRetryUnsafe`
 
 ## Server Setup
@@ -135,7 +135,7 @@ new TerrenoApp({
 
 ### Audit log (`AuditApp`)
 
-Opt-in append-only log. Register the plugin; importing `@terreno/api` does **not** compile `AuditEvent` onto the default mongoose connection.
+Opt-in append-only log. Register the plugin; importing `@terreno/api` does **not** compile `AuditEvent` onto the default mongoose connection. The compiled Mongoose name is `TerrenoAuditEvent` on collection `auditevents`. Admin UI and RBAC keep `AuditEvent` / `adminAuditEvent`.
 
 ```typescript
 import {
@@ -223,6 +223,22 @@ export const todoRouter = modelRouter("/todos", Todo, {
 
 Do not add `endpoints: (router) => { router.get(...) }` when an action fits.
 
+## modelRouter array operations
+
+When a model has at least one array field, `modelRouter` provides subroutes for adding,
+updating, and removing array items:
+
+| Method | Path | Operation |
+| --- | --- | --- |
+| `POST` | `/:id/:field` | Append an item |
+| `PATCH` | `/:id/:field/:itemId` | Replace or merge an item |
+| `DELETE` | `/:id/:field/:itemId` | Remove an item |
+
+The `field` path must resolve to an array on the document. Requests for scalar, object,
+or unknown fields run the normal update transform and `preUpdate` hook first so consumer
+authorization remains authoritative, then return `400` with code
+`array-operation-field-not-array` if the hook allows the request.
+
 ## MCP tools
 
 Opt a model into Model Context Protocol tools with `mcp` on `modelRouter`. `TerrenoApp` mounts `POST /mcp` when any model has `mcp` or a custom tool is registered.
@@ -300,6 +316,11 @@ setupServer({
 - `GET /auth/me` — Get current user profile
 - `PATCH /auth/me` — Update current user profile
 
+JWT recovery routes default on. In `authOptions`, set `passwordReset: false` to omit
+forgot-password and both token-reset paths, `emailVerification: false` to omit send/verify
+email, or `legacyResetPasswordRoute: false` to omit only the deprecated
+`POST /resetPassword` alias while retaining `POST /auth/resetPassword`.
+
 Signup and `PATCH /auth/me` drop privileged fields: `admin`, `roles`, `organizationIds`,
 `emailVerified`, and `tokenEpoch`. Request logs redact `password`, `newPassword`,
 `oldPassword`, `token`, and `refreshToken` in request bodies and in URL query strings. Changing the mailbox through `PATCH /auth/me`
@@ -1260,6 +1281,22 @@ top-level request fields) flows into Google Cloud Logging `jsonPayload` for Log
 To correlate with Cloud Trace, ensure clients or load balancers send `x-cloud-trace-context` or W3C
 `traceparent`.
 
+### Development browser-log ingestion
+
+`TerrenoApp` mounts `POST /__terreno/browser-logs` only when `NODE_ENV=development`, or when
+`TERRENO_BROWSER_LOGS=true` in another non-production environment. Production always returns 404;
+set `TERRENO_BROWSER_LOGS=false` to disable the route in development.
+
+The route accepts loopback requests for local browser development. Non-loopback clients must
+authenticate through the app's normal JWT or Better Auth middleware. `TerrenoApp` mounts the route
+after its optional rate limiter, so configured API limits also apply to ingestion.
+
+The request body is `{entries: Array<{level?, message?, stack?, timestamp?}>}`. Batches are capped
+at 100 entries and 256 kB. Accepted rows are truncated to bounded field lengths and appended as
+mode-`0600` JSONL under `<backend cwd>/.terreno/logs/browser.log`. The file restarts with the latest
+batch before it would exceed 5 MB. The local MCP `read_logs` / `last_error` tools and
+`terreno logs --sources browser` consume that file.
+
 ### Message style
 
 - Start with what happened, then optional detail: `User export finished`, not `finished`.
@@ -1387,6 +1424,10 @@ new TerrenoApp({userModel: User}).register(
 | `Notification` | `/notifications` | owner | **No** (`create: []`) |
 | `NotificationPreference` | `/notification-preferences` | owner | Yes (lazy defaults) |
 
+The exported models use collision-resistant Mongoose names
+`TerrenoInboxNotification` and `TerrenoNotificationPreference`, while retaining the
+existing `notifications` and `notificationpreferences` MongoDB collections.
+
 `Notification` fields: `ownerId`, `title`, `body`, `href?`, `kind?`, `readAt?` (null = unread),
 `archivedAt?` (null = active inbox).
 Index: `{ownerId: 1, created: -1}`.
@@ -1467,18 +1508,29 @@ nested ids (SendGrid `sg_event_id`). Operator guide: [Receive inbound webhooks](
 
 ### Slack Notifications
 
+Incoming webhooks only notify a person when the text contains their **Slack
+member ID** as `<@U012ABCDEF>` (Enterprise Grid ids start with `W`). Putting a
+display name or email in the message does not mention them.
+
+Store `slackUserId` on the staff/user record. Resolve it once with
+`lookupSlackUserIdByEmail` (needs a bot token with `users:read.email`) and pass
+the id on every send:
+
 ``````typescript
-import {sendSlackMessage} from "@terreno/api";
+import {formatSlackUserMention, lookupSlackUserIdByEmail, sendToSlack} from "@terreno/api";
 
-await sendSlackMessage({
-  webhookUrl: process.env.SLACK_WEBHOOK_URL,
-  message: "Deployment complete",
-  blocks: [
-    {
-      type: "section",
-      text: {type: "mrkdwn", text: "*Deployment Status*\nVersion 1.2.3 deployed successfully"},
-    },
-  ],
+const slackUserId =
+  staff.slackUserId ??
+  (await lookupSlackUserIdByEmail({email: staff.email, token: process.env.SLACK_BOT_TOKEN}));
+
+await sendToSlack("Please review this case", {
+  url: process.env.SLACK_WEBHOOK_URL,
+  mentionUserIds: slackUserId ? [slackUserId] : [],
+});
+
+// Or embed the token yourself:
+await sendToSlack(`${formatSlackUserMention("U012ABCDEF")} Deployment complete`, {
+  url: process.env.SLACK_WEBHOOK_URL,
 });
 ``````
 
@@ -1803,6 +1855,7 @@ Complete reference of environment variables used by @terreno/api:
 |----------|----------|---------|-------------|
 | `USE_SENTRY_LOGGING` | No | — | Set to `"true"` to enable Sentry error tracking |
 | `SENTRY_DSN` | No | — | Sentry Data Source Name (required if USE_SENTRY_LOGGING=true) |
+| `TERRENO_BROWSER_LOGS` | No | enabled in development | Set `"false"` to disable dev ingestion or `"true"` to opt in outside development; production stays disabled and non-loopback clients must authenticate |
 | `SENTRY_TRACES_SAMPLE_RATE` | No | `0.1` | Sentry trace sampling rate (0.0 to 1.0) |
 | `DISABLE_LOG_ALL_REQUESTS` | No | — | Set to `"true"` to disable request logging |
 | `SLOW_REQUEST_THRESHOLD_MS` | No | `3000` | Log warning for requests slower than this (milliseconds) |
@@ -1813,6 +1866,7 @@ Complete reference of environment variables used by @terreno/api:
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `SLACK_WEBHOOKS` | No | — | JSON object mapping names to Slack webhook URLs: `{"default":"https://..."}` |
+| `SLACK_BOT_TOKEN` | No | — | Bot token (`xoxb-…`) with `users:read.email` for `lookupSlackUserIdByEmail` |
 | `GOOGLE_CHAT_WEBHOOKS` | No | — | JSON object mapping names to Google Chat webhook URLs |
 | `ZOOM_CHAT_WEBHOOKS` | No | — | JSON object mapping names to Zoom webhook URLs |
 | `WEBHOOK_SECRET` | No | — | Secret for validating incoming webhook signatures |
@@ -1861,4 +1915,4 @@ SENTRY_DSN=https://...@sentry.io/...
 - [How to create a model](../how-to/create-a-model.md)
 - [Add GitHub OAuth](../how-to/add-github-oauth.md)
 - [Authentication architecture](../explanation/authentication.md)
-- [API package source](https://github.com/flourishhealth/terreno/tree/master/api/src)
+- [API package source](https://github.com/TerrenoLabs/terreno/tree/master/api/src)

package/src/docs/versioned/next/reference/cli.md

@@ -0,0 +1,91 @@
+# @terreno/cli
+
+Install: `bun add -g @terreno/cli` then run `terreno --help`.
+
+The `terreno` binary is the operator CLI for Terreno apps. It wraps documentation search, codegen (syncdb SDK, RTK OpenAPI SDK, Mongoose models, routes, screens, forms, admin install notes), app bootstrap, local project tools from `@terreno/mcp`, and **OpenAPI-driven REST calls**.
+
+Generate an app-specific CLI from your backend spec:
+
+```bash
+terreno generate rest-cli --schema http://localhost:4000/openapi.json --out ./tools/app-cli --name myapp
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `docs search <query>` | Search Terreno docs (`--packages api,ui`, `--token-limit`) |
+| `docs component <Name>` | Print `@terreno/ui` component props |
+| `docs upgrade --from --to` | Lockstep upgrade notes |
+| `generate syncdb` | Typed syncdb hooks from OpenAPI (`--schema`, `--out`, `--collections`, `--config`, `--no-format`) |
+| `generate sdk` | Run `@rtk-query/codegen-openapi` with `--config` |
+| `generate rest-cli` | Scaffold a bun CLI from OpenAPI (`--schema`, `--out`, `--name`, `--base-url`) |
+| `generate model` | Mongoose model (`--name`, `--field name:Type:required`, `--owner`, `--soft-delete`) |
+| `generate route` | `modelRouter` module (`--model-name`, `--route-path`, `--owner-filtered`, `--query-fields`, `--sort`) |
+| `generate screen` | UI screen (`--name`, `--type list\|detail\|form\|empty`) |
+| `generate form` | Form fields (`--field name:type:required:label=Label`) |
+| `generate admin` | Admin install snippets (`--model Model:/path:Display:field,field`) |
+| `bootstrap app` | Full-stack app files (`--name`, `--display-name`, `--dir`, `--description`, `--mcp-url`) |
+| `bootstrap rules` | Editor AI rules only (`--packages api,ui`) |
+| `validate schema --file` | Check a Mongoose schema against conventions |
+| `api list` | List operations from `--schema` or `TERRENO_OPENAPI` |
+| `api call <operationId>` | Invoke by OpenAPI operation id |
+| `api request <METHOD> <path>` | Invoke by method + path template |
+| `info` | Local `@terreno/*` versions (via MCP local tools) |
+| `logs` | Merge backend/browser JSONL, Metro events, and app CDP console (`--entries`, `--level`, `--since`, `--sources`; `last-error`) |
+| `state` | Inspect Better Auth (via `auth` alias or `betterAuth`) or RTK Query state (`--slice`, `--query`) through the dev store or Metro CDP |
+| `eval` | Evaluate JavaScript in the app runtime through Metro CDP (`--code`; requires `TERRENO_MCP_EVAL=1`) |
+| `navigate` | Navigate Expo Router through Metro CDP (requires `TERRENO_MCP_EVAL=1`) |
+| `web [url]` | Automate the web app with Bun 1.4 `Bun.WebView`; ordered `--action` JSON, `--snapshot`, and `--screenshot` |
+| `db schema` | Mongo collections (`--collection-filter`, `--summary`) |
+| `db query` | Read-only Mongo (`--collection`, `--operation`, `--filter`, `--pipeline`, `--field`, `--limit`) |
+
+Global flags: `--json`, `--help` / `-h`, `--version` / `-v`.
+
+## Web app automation
+
+Run an interaction sequence and save proof from the final rendered state:
+
+```bash
+terreno web http://localhost:8082 \
+  --action '{"action":"click","selector":"#login"}' \
+  --action '{"action":"type","selector":"input[name=email]","text":"test@example.com"}' \
+  --action '{"action":"press","key":"Enter"}' \
+  --snapshot \
+  --screenshot /opt/cursor/artifacts/login.png
+```
+
+The command requires Bun 1.4 or newer and uses its built-in headless `Bun.WebView`; Chrome,
+Chromium, or Edge must be installed on Linux and Windows. Actions run in argument order with
+native trusted input. Supported actions are `click`, `type`, `press`, `scroll`, `evaluate`,
+`snapshot`, `screenshot`, `back`, `forward`, `reload`, and `wait`. Use `--actions-file <path>` for a
+JSON array, `--width` / `--height` for the viewport, `--wait` to change the initial 1000 ms
+client-render delay, and `--data-dir` to persist cookies and browser storage. The URL defaults to
+`TERRENO_WEB_URL`, then `http://localhost:8082`. The CLI manages `open` and `close` around the
+sequence. Set `TERRENO_MCP_EVAL=1` before using an `evaluate` action. Screenshot paths must stay
+under the project root or `/opt/cursor/artifacts`; browser data must stay under the project root.
+
+## REST auth
+
+| Flag / env | Purpose |
+| --- | --- |
+| `--token` / `TERRENO_TOKEN` | Bearer token |
+| `--base-url` / `TERRENO_API_URL` | Override `servers[0].url` |
+| `--header "Name: value"` | Extra headers (repeatable) |
+| `--param name=value` | Path or query parameter |
+| `--body` / `--body-file` | JSON body |
+
+Library entry for generated app CLIs:
+
+```ts
+import {runAppRestCli} from "@terreno/cli";
+
+await runAppRestCli({
+  argv: process.argv.slice(2),
+  binName: "myapp",
+  specText: openApiJson,
+  title: "My API",
+});
+```
+
+See [Generate a REST CLI from OpenAPI](../how-to/generate-a-rest-cli.md).

package/src/docs/versioned/next/reference/create-terreno-app.md

@@ -37,7 +37,7 @@ Writes `<cwd>/<appName>/`. Refuses a non-empty target except `.git` / `.gitignor
 
 Printed next steps install, seed, then start the backend. SDK and web run in a second terminal while the backend is up.
 
-The generated Profile tab uses `@terreno/ui` `TapToEdit` with `PATCH /auth/me`. Fonts come from `@terreno/ui`. `app.json` leaves icon/splash/favicon unset. `metro.config.js` pins `jspdf` so Metro can bundle admin PDF export. `tsconfig.json` has no `baseUrl` (TypeScript 6). Auth routes use `<Stack.Protected>`.
+The generated Profile tab uses `@terreno/ui` `TapToEdit` with `PATCH /auth/me`. Fonts come from `@terreno/ui`. `app.json` leaves icon/splash/favicon unset. `metro.config.js` pins `jspdf` so Metro can bundle admin PDF export. Generated tsconfigs use no TypeScript 6 deprecated options and no `ignoreDeprecations` (see [TypeScript configuration](../explanation/typescript-configuration.md)). Auth routes use `<Stack.Protected>`.
 
 ## Library
 

package/src/docs/versioned/next/reference/environment-variables.md

@@ -69,6 +69,7 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 | `FRONTEND_URL` | example-backend CORS and `authOptions.publicAppUrl` | ❌ | `http://localhost:8082` | No | server |
 | `API_URL` | microservice split | ❌ | — | No | server |
 | `DISABLE_LOG_ALL_REQUESTS` | `@terreno/api` logging | ❌ | — | No | server |
+| `TERRENO_BROWSER_LOGS` | `@terreno/api` dev log ingestion | ❌ | enabled only in development; loopback or authenticated requests only | No | server |
 | `ALLOW_MIGRATIONS` | `@terreno/api` `terreno-migrate` | ❌ | unset | No | server |
 | `MIGRATIONS_DIR` | example-backend Dockerfile / `resolveMigrationDir` | ❌ | `<cwd>/migrations` when `dir` is `$bunfs` | No | server |
 
@@ -99,6 +100,19 @@ Resolution order for API base URL (`rtk/src/constants.ts`):
 2. `extra.BASE_URL` (production only, when env unset)
 3. Dev fallbacks: `hostUri`, experience URL, `localhost`
 
+## Development tooling
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `TERRENO_PROJECT_ROOT` | `terreno-mcp-local`, `terreno` CLI | ❌ | nearest Terreno project root | No | tooling |
+| `TERRENO_METRO_URL` | `terreno-mcp-local` | ❌ | frontend script port or `http://localhost:8082` | No | tooling |
+| `TERRENO_MCP_EVAL` | `terreno-mcp-local` | ❌ | disabled | No | tooling |
+| `TERRENO_WEB_URL` | `terreno` CLI | ❌ | `http://localhost:8082` | No | tooling |
+| `BUN_CHROME_PATH` | Bun WebView | ❌ | browser auto-discovery | No | tooling |
+| `TERRENO_OPENAPI` | `terreno` CLI | ❌ | — | No | tooling |
+| `TERRENO_API_URL` | `terreno` CLI | ❌ | OpenAPI `servers[0].url` | No | tooling |
+| `TERRENO_TOKEN` | `terreno` CLI | ❌ | — | Yes | tooling |
+
 ## AI
 
 | Variable | Read by | Required | Default | Secret | Scope |
@@ -208,6 +222,7 @@ There is **no** `RATE_LIMIT_ENABLED` (or similar) read by `@terreno/api`. Apps t
 |----------|---------|----------|---------|--------|-------|
 | `SLACK_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
 | `SLACK_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
+| `SLACK_BOT_TOKEN` | `@terreno/api` `lookupSlackUserIdByEmail` | ❌ | — | Yes | server |
 | `GOOGLE_CHAT_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
 | `GOOGLE_CHAT_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
 | `ZOOM_CHAT_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
@@ -297,8 +312,8 @@ example-backend **test** setup only. They are not read by `@terreno/jobs`. Use
 
 ## Example `.env` files
 
-- [`example-backend/.env.example`](https://github.com/FlourishHealth/terreno/blob/master/example-backend/.env.example)
-- [`example-frontend/.env.example`](https://github.com/FlourishHealth/terreno/blob/master/example-frontend/.env.example)
+- [`example-backend/.env.example`](https://github.com/TerrenoLabs/terreno/blob/master/example-backend/.env.example)
+- [`example-frontend/.env.example`](https://github.com/TerrenoLabs/terreno/blob/master/example-frontend/.env.example)
 
 ## Related documentation
 

package/src/docs/versioned/next/reference/lifecycle-plugin.md

@@ -35,16 +35,16 @@ Every stage includes:
 - Recommended next stage
 
 Results use `PASS`, `FAIL`, `BLOCKED`, or `PENDING` and the compact `v: 2` schema
-[`stage-result.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/stage-result.schema.json)
+[`stage-result.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-planning/references/stage-result.schema.json)
 (`v`, `stage`, `status`, `next`, `action`; omit empty keys). Loop state follows
-[`execution-state.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/execution-state.schema.json).
+[`execution-state.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-planning/references/execution-state.schema.json).
 Chat and PRs show `status` / `next` / `action`; the YAML lives in a Details toggle.
 When the current PR has GitHub Deployments, those demo URLs are the last visible
 section of every wait-for-human or done chat.
 
 The outer loop owns state persistence, Taste `PENDING` reinvocation, Grow/Brew/Taste
 invocation, retries, and escalation. Pick owns the
-[pick-roast inner loop](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/pick-roast-loop.md):
+[pick-roast inner loop](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-planning/references/pick-roast-loop.md):
 one task, roast it, next task. Roast never invokes Pick. Do not start the next task
 until Roast PASS. Exactly one driver continues after each Roast. Brew and Taste wait
 until async review bots (Bugbot, CodeQL, and similar) on the current head have reported,
@@ -91,16 +91,16 @@ These are the only visible PR sections; optional detail is expandable; comments
 reserved for blocked decisions or non-obvious review resolutions.
 
 Every stage follows the
-[documentation contract](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/documentation-contract.md):
+[documentation contract](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-planning/references/documentation-contract.md):
 read architecture docs before acting, update them in the same slice, and fail the slice
 when user-visible or architectural behavior ships without matching docs. Brew and Taste
 observe product CI per
-[product-ci.md](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/product-ci.md).
+[product-ci.md](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-planning/references/product-ci.md).
 
 Install the published skill set directly:
 
 ```bash
-npx skills add FlourishHealth/terreno
+npx skills add TerrenoLabs/terreno
 ```
 
 Or install the combined lifecycle and Terreno app plugin:
@@ -112,24 +112,24 @@ Or install the combined lifecycle and Terreno app plugin:
 | Claude Code | `terreno` | `1-grow` … `5-taste`, outer loops | `/terreno:pick-roast-loop` |
 | `npx skills` | — | Canonical stage and outer-loop names | `/terreno-pick-roast-loop` |
 
-Cursor installs `terreno-planning` from [`.cursor-plugin/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.cursor-plugin/marketplace.json). Codex:
+Cursor installs `terreno-planning` from [`.cursor-plugin/marketplace.json`](https://github.com/TerrenoLabs/terreno/blob/master/.cursor-plugin/marketplace.json). Codex:
 
 ```text
-codex plugin marketplace add FlourishHealth/terreno
+codex plugin marketplace add TerrenoLabs/terreno
 codex plugin install terreno-planning --source terreno-plugins
 ```
 
-Codex reads [`.agents/plugins/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.agents/plugins/marketplace.json)
+Codex reads [`.agents/plugins/marketplace.json`](https://github.com/TerrenoLabs/terreno/blob/master/.agents/plugins/marketplace.json)
 and `.codex-plugin/plugin.json` on the canonical plugin. Claude Code:
 
 ```text
-/plugin marketplace add FlourishHealth/terreno
+/plugin marketplace add TerrenoLabs/terreno
 /plugin install terreno@terreno-plugins
 ```
 
 Claude Code resolves a plugin skill's command from the frontmatter `name`, so the short
 names ship as a generated Claude-only copy at
-[`plugins/terreno-claude/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-claude).
+[`plugins/terreno-claude/`](https://github.com/TerrenoLabs/terreno/tree/master/plugins/terreno-claude).
 Stage procedure, Terreno app skills, contracts, agents, and references are generated
 from the canonical `plugins/terreno-planning/` tree.
 

package/src/docs/versioned/next/reference/mcp-server.md

@@ -3,9 +3,12 @@
 Published npm package for the Terreno Model Context Protocol (MCP) server. The monorepo directory is still `mcp-server/`. The package exposes:
 
 - **`terreno-mcp`** — HTTP server used in Cloud Run and local debugging (`src/index.ts`)
-- **`terreno-mcp-local`** — stdio server for project runtime tools (`src/local/index.ts`): `application_info`, `database_schema`, `database_query`, `read_logs`, `last_error`, `get_rtk_state`, `evaluate` (gated by `TERRENO_MCP_EVAL`), `navigate` (CDP wiring planned). `application_info` reads bootstrap `backend/` + `frontend/`, or this monorepo's `example-backend/` + `example-frontend/` (bootstrap names win when both exist).
+- **`terreno-mcp-local`** — stdio server for project runtime tools (`src/local/index.ts`): app/database/log/browser diagnostics, Redux/RTK inspection, and SyncDB state/action/snapshot tools. `evaluate`, `navigate`, and SyncDB state changes are gated by `TERRENO_MCP_EVAL`. Metro URL defaults from `frontend/package.json` `--port` or `TERRENO_METRO_URL`. `application_info` reads bootstrap `backend/` + `frontend/`, or this monorepo's `example-backend/` + `example-frontend/` (bootstrap names win when both exist).
 
 It provides AI coding assistants with documentation access, code generation tools, and workflow prompts.
+For editor configuration and runtime prerequisites, see
+[Set up Terreno MCP](../how-to/set-up-terreno-mcp.md). For the end-to-end diagnostic workflow, see
+[Debug a Terreno app with MCP](../how-to/debug-with-mcp.md).
 
 Both HTTP MCP surfaces (`@terreno/mcp` and the `modelRouter` endpoint in
 `@terreno/api`) use the MCP TypeScript SDK v2 and speak the stateless
@@ -107,7 +110,54 @@ Set `TERRENO_MCP_DOCS_DIR` environment variable to override default path.
 
 ## Tools
 
-Code generation tools that return TypeScript/JavaScript code as text. They do not write files — the AI assistant receives the code and writes it to appropriate locations. Scaffold a new app with [`create-terreno-app`](create-terreno-app.md) (`bunx create-terreno-app`), not an MCP tool.
+Code generation tools return TypeScript/JavaScript code as text. **Code generation tools do not
+write files** — the AI assistant receives the code and writes it to appropriate locations. Scaffold
+a new app with [`create-terreno-app`](create-terreno-app.md) (`bunx create-terreno-app`), not an MCP
+tool.
+
+The local `browser` tool is different: its `screenshot` action writes the requested image path so an
+agent can attach the rendered result as verification evidence. It keeps one headless session alive
+for the MCP connection. Call `open` first, perform interactions, call `snapshot` and `screenshot` to
+prove the final state, then call `close`.
+
+`open` accepts only `http:` and `https:` URLs. Snapshots redact password input values; use them for
+page structure and visible state, not credential inspection.
+
+``````json
+{"name":"browser","arguments":{"action":"open","url":"http://localhost:8082","width":1280,"height":720}}
+{"name":"browser","arguments":{"action":"wait","timeout":1000}}
+{"name":"browser","arguments":{"action":"click","selector":"button[type=submit]"}}
+{"name":"browser","arguments":{"action":"snapshot"}}
+{"name":"browser","arguments":{"action":"screenshot","output":"/opt/cursor/artifacts/app.png"}}
+{"name":"browser","arguments":{"action":"close"}}
+``````
+
+`browser` requires Bun 1.4 or newer. macOS uses system WebKit; Linux and Windows use an installed
+Chrome, Chromium, or Edge through the Chrome DevTools Protocol. Browser storage is ephemeral unless
+`open` receives `dataDir`. Set `TERRENO_MCP_EVAL=1` to enable its arbitrary-JavaScript `evaluate`
+action. Screenshot paths must stay under the project root or `/opt/cursor/artifacts`; persistent
+browser data must stay under the project root. Calls are serialized around the one session owned by
+the local MCP process.
+
+### SyncDB runtime tools
+
+Create the app client with `debug: true` so it registers by its configured
+`name`. The local MCP uses the in-process registry when available and Hermes CDP
+for a separately running app.
+
+| Tool | Purpose |
+| --- | --- |
+| `get_syncdb_state` | Read status, entities/tombstones, outbox, conflicts, cursors, streams, repair markers, values, and debugger events |
+| `syncdb_snapshot` | Capture, list, get, compare, or delete snapshots held by this MCP process |
+| `syncdb_action` | Mutate or directly edit local state, flush, reconcile/resync, resolve/retry, toggle offline, clear debug events, or merge a snapshot |
+
+State and snapshot responses redact fields containing `password`, `token`,
+`secret`, `authorization`, or `cookie`. Snapshot merge payloads are retained
+privately and are not returned. Start the local MCP with
+`TERRENO_MCP_EVAL=1` before calling `syncdb_action`.
+
+See [Debug a Terreno app with MCP](../how-to/debug-with-mcp.md) for examples and
+safety guidance.
 
 ### terreno_search_docs
 
@@ -515,6 +565,10 @@ Returns comprehensive code style guide from project documentation.
 | `PORT` | `8080` | HTTP server port |
 | `MCP_HOST` or `HOST` | `0.0.0.0` | Server host address |
 | `TERRENO_MCP_DOCS_DIR` | `../docs` | Path to documentation directory (relative to dist/) |
+| `TERRENO_PROJECT_ROOT` | nearest Terreno project root | Override local package, database, and log discovery |
+| `TERRENO_METRO_URL` | Frontend script port or `http://localhost:8082` | Metro origin used for `/events` and CDP discovery |
+| `TERRENO_MCP_EVAL` | Disabled | Set to `1` to enable local MCP `evaluate`, `navigate`, and SyncDB state-changing actions |
+| `TERRENO_BROWSER_LOGS` | Enabled only when `NODE_ENV=development` | Set to `true` to opt in in another non-production environment or `false` to disable; production rejects the route, and non-loopback clients must authenticate |
 
 **Example:**
 

package/src/docs/versioned/next/reference/scan-plugin.md

@@ -51,7 +51,7 @@ watch hook while CI runs, 2–5 minutes while review bots report, 15–30 minute
 human holds the PR, and no wait at all while backlog work remains. Ticks that find
 nothing print nothing, and every comment is answered exactly once — answered ids live in
 state. See
-[`heartbeat.md`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/heartbeat.md).
+[`heartbeat.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/heartbeat.md).
 
 ## PR routing
 
@@ -65,7 +65,7 @@ Routing is applied right after Brew reports the PR (`gh pr edit --add-reviewer
 --add-assignee --add-label`) and re-requested once when requested changes are addressed.
 The campaign never approves its own PRs, never dismisses a review, and never merges when
 `mergePolicy` is `human` — the default. See
-[`pr-routing.md`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/pr-routing.md).
+[`pr-routing.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/pr-routing.md).
 
 ## Stage anatomy
 
@@ -74,11 +74,11 @@ produced, Success/Failure/Blocked conditions, and a recommended next stage — t
 shape as the lifecycle stages.
 
 Results use `PASS`, `FAIL`, `BLOCKED`, or `PENDING` and the compact `v: 2`
-[`scan-result.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/scan-result.schema.json)
+[`scan-result.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/scan-result.schema.json)
 (`v`, `stage`, `status`, `next`, `action`; omit empty keys). Campaign state follows
-[`scan-state.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/scan-state.schema.json)
+[`scan-state.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/scan-state.schema.json)
 and findings follow
-[`finding.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/finding.schema.json).
+[`finding.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/finding.schema.json).
 Chat shows `status` / `next` / `action` plus the current metric; the YAML lives in a
 Details toggle.
 
@@ -93,7 +93,7 @@ large, never spawn nested agents, and never edit files. Sift then dedupes by
 keeping it, drops what does not reproduce, and ranks by impact × confidence ÷ effort.
 Dropped shards and capped coverage are always reported; silent truncation is a defect.
 See
-[`mapreduce.md`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/mapreduce.md).
+[`mapreduce.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/mapreduce.md).
 
 ## Goal and metric
 
@@ -102,7 +102,7 @@ came from running it. Track re-runs that command with the charter's protocol eve
 and records the value with its output. A finding that cannot be tied to the metric is
 dismissed in Sift, not deferred. Re-baselining without recording both values, the reason,
 and the round is untrustworthy and Track says so. See
-[`goal-tracking.md`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/goal-tracking.md).
+[`goal-tracking.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/goal-tracking.md).
 
 ## Artifacts
 

package/src/docs/versioned/next/reference/syncdb.md

@@ -200,7 +200,7 @@ be passed to `betterAuthAdapter` directly.
 | `mutate({collection, operation, id?, data?})` | Optimistic local write + durable outbox enqueue + fire-and-forget replay. Returns `{mutationId, id}`. |
 | `reconcile()` | HTTP snapshot catch-up for every known stream; runs tombstone compaction on success. Also runs automatically on (re)connect, on a rate-limited seq-jump hint, and on the periodic timer; each `sync:subscribed` confirmation additionally pages just the streams it names. |
 | `hydrateWindow({collection, ids, restRows?})` | Admin window upsert: REST rows (optional) land immediately; every requested id is also fetched from `GET /sync/entities` before this resolves so seq/deleted metadata is canonical for immediate update/delete. A `{collection}|admin` delta that lands while the fetch is in flight wins, so hydration never rewinds a row to an older seq. Unknown ids are ignored. |
-| `forceResync()` | Purge every known stream locally and re-bootstrap from cursor 0 (outbox/conflicts untouched). Returns `{ok, reason?, streams, purged, repaired}`. |
+| `forceResync()` | Purge every known stream locally and re-bootstrap from cursor 0 (outbox/conflicts untouched). Returns `{ok, reason?, streams, purged, repaired}`. After discovery and each stream bootstrap it waits for in-flight `start`/`stop`/auth-change work, then abandons with `reason: "superseded"` when that work switched users or generations. |
 | `replayOutbox()` | Drain queued mutations for the current user now. |
 | `resolveConflict({mutationId, strategy})` | Apply `"useServer"` or `"keepMine"` to a recorded conflict. |
 | `retryFailed({entityId})` | Re-enable an entity's queued successors after a terminal validation failure. |
@@ -211,6 +211,27 @@ be passed to `betterAuthAdapter` directly.
 | `outbox` | Durable mutation outbox (`Outbox`). |
 | `debug` | `SyncDebugLog` when `debug` is enabled; otherwise `undefined`. |
 
+### Local MCP debugging
+
+When `debug` is enabled, `createSyncDb` registers the client by `name` on the
+development runtime bridge used by `terreno-mcp-local`. Production clients stay
+unregistered when debug logging is off.
+
+| Tool | Operations |
+| --- | --- |
+| `get_syncdb_state` | Read status, entities/tombstones, decoded outbox, conflicts, cursors, known streams, repair markers, values, and debug events |
+| `syncdb_snapshot` | `capture`, `list`, `get`, `compare`, `delete` |
+| `syncdb_action` | `mutate`, `setLocalEntity`, `deleteLocalEntity`, `flush`, `reconcile`, `forceResync`, `resolveConflict`, `retryFailed`, `goOffline`, `goOnline`, `clearDebug`, `mergeSnapshot` |
+
+Read and snapshot tools redact sensitive field names. `syncdb_action` requires
+the local MCP process to start with `TERRENO_MCP_EVAL=1`. `flush` means “drain
+the durable outbox now.” `mergeSnapshot` CRDT-merges TinyBase mergeable content
+from a snapshot retained in the same MCP process. Later HLCs win, including
+deletes; it does not replace the live store. To force specific rows from a
+capture, use `setLocalEntity` from `syncdb_snapshot` `get`.
+
+See [Debug a Terreno app with MCP](../how-to/debug-with-mcp.md).
+
 ## React hooks
 
 Import from `@terreno/syncdb/react`:

package/src/docs/versioned/next/reference/test.md

@@ -118,7 +118,7 @@ jobs (`api-ci`, `ai-ci`,
 that script. Published packages without a dedicated workflow
 (`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `@terreno/test`)
 run the same lint, compile, and coverage commands via the parameterized
-`packages-ci` job. Retained GitHub Actions twins stay in lockstep (`on: []`),
+`packages-ci` job. Retained GitHub Actions twins stay in lockstep (`push.branches-ignore: ["**"]`),
 including `.github/workflows/packages-ci.yml`. Those twins run
 `scripts/ci/check-new-file-coverage-lcov.sh` with `working-directory: .` and
 pass `secrets.CODECOV_TOKEN` into `upload-codecov`.
@@ -164,7 +164,9 @@ line coverage. Test, spec, story, generated OpenAPI SDK, `dist`, isolated-test,
 `src/types` type modules, demo `story-config/*.config.tsx`, and Expo Router route
 files (`index`, `_layout`, `+not-found`, `[param]`, plus example recovery screens
 `forgotPassword` / `resetPassword` / `verifyEmail`) are excluded. A new implementation
-file that is absent from LCOV is treated as 0% covered. Package CI jobs that
+file that is absent from LCOV is treated as 0% covered, except files listed in
+that package's `bunfig.toml` `coveragePathIgnorePatterns` (the same paths the
+95% package gate already omits). Package CI jobs that
 already produced `coverage/lcov.info` run the 90% check against that report
 (`--package` + `--lcov`) so the dedicated job does not rerun the suite.
 When the dedicated job does rerun a package, it prefers colocated

package/src/docs/versioned/next/reference/ui.md

@@ -697,7 +697,7 @@ declare module "@terreno/ui" {
 }
 ``````
 
-See [`demo/components/customIcons.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/components/customIcons.tsx) for a full working example.
+See [`demo/components/customIcons.tsx`](https://github.com/TerrenoLabs/terreno/blob/master/demo/components/customIcons.tsx) for a full working example.
 
 ### Built-in Status Icons
 
@@ -831,4 +831,4 @@ Demo: `FilterableDataTable` story in the component demo (`demo:start`, port 8085
 ## Related Documentation
 
 - [UI performance benchmarks](ui-performance.md)
-- [UI package source](https://github.com/flourishhealth/terreno/tree/master/ui/src)
+- [UI package source](https://github.com/TerrenoLabs/terreno/tree/master/ui/src)

package/src/docs/versioned/next/roadmap.md

@@ -2,8 +2,8 @@
 
 Terreno's public roadmap lives on GitHub:
 
-- **[ROADMAP.md](https://github.com/FlourishHealth/terreno/blob/master/ROADMAP.md)** — generated from the Terreno Roadmap project board (also in the repo root)
+- **[ROADMAP.md](https://github.com/TerrenoLabs/terreno/blob/master/ROADMAP.md)** — generated from the Terreno Roadmap project board (also in the repo root)
 - **[Roadmap process](explanation/roadmap-process.md)** — Discussions, triage, Linear bridge, maintainer setup
-- **[GitHub Discussions](https://github.com/FlourishHealth/terreno/discussions)** — Ideas, Q&A, RFCs
+- **[GitHub Discussions](https://github.com/TerrenoLabs/terreno/discussions)** — Ideas, Q&A, RFCs
 
-To propose work, start an [Ideas discussion](https://github.com/FlourishHealth/terreno/discussions/new?category=ideas) rather than opening a tracking issue directly.
+To propose work, start an [Ideas discussion](https://github.com/TerrenoLabs/terreno/discussions/new?category=ideas) rather than opening a tracking issue directly.