@terreno/mcp 57.3.0 → 57.6.0

package/src/docs/versioned/next/how-to/debug-with-mcp.md

@@ -0,0 +1,160 @@
+# Debug a Terreno app with MCP
+
+Start the backend and frontend, reproduce the failure once, then inspect the merged runtime evidence
+instead of copying logs into the agent chat.
+
+## 1. Read the latest error
+
+Call the local MCP tool:
+
+```json
+{"name":"last_error","arguments":{"sources":["backend","browser","metro","app"]}}
+```
+
+It returns the newest error-level JSONL/CDP entry. Use `read_logs` when the failure needs surrounding
+events:
+
+```json
+{
+  "name": "read_logs",
+  "arguments": {
+    "entries": 100,
+    "level": "error",
+    "sources": ["backend", "browser", "metro", "app"]
+  }
+}
+```
+
+`backend` and `browser` read durable JSONL; `metro` and `app` read in-memory rings populated from
+Metro `/events` and CDP. Connection status in the response explains when either live source is
+unavailable.
+
+CLI equivalents:
+
+```bash
+terreno logs last-error --sources backend,browser,metro,app
+terreno logs --entries 100 --level error --sources backend,browser,metro,app
+```
+
+## 2. Inspect client state
+
+Check authentication and non-synced RTK Query cache state:
+
+```json
+{"name":"get_rtk_state","arguments":{"slice":"rtk","query":"todos"}}
+```
+
+The tool reads `globalThis.__TERRENO_STORE__` registered by the app, using CDP when the MCP process
+cannot access the app heap directly. `slice: "auth"` prefers the Better Auth slice and falls back to
+legacy JWT auth; pass `betterAuth` to request that exact slice. The CLI equivalent is:
+
+Sensitive fields whose names include `password`, `token`, `secret`, `authorization`, or `cookie` are
+returned as `[REDACTED]`; use this summary to inspect cache state, never to retrieve credentials.
+
+```bash
+terreno state --slice rtk --query todos
+```
+
+## 3. Inspect and change SyncDB state
+
+Create the app client with `debug: true`, then inspect the same state that powers
+the SyncDB debugger:
+
+```json
+{"name":"get_syncdb_state","arguments":{"collection":"todos"}}
+```
+
+The result includes entities (including tombstones, seq/stream, and pending ids),
+decoded outbox rows, conflicts, cursors, known streams, repair markers, aggregate
+status, and debugger events. Sensitive fields are returned as `[REDACTED]`.
+
+Capture state before and after reproduction, then compare it:
+
+```json
+{"name":"syncdb_snapshot","arguments":{"action":"capture"}}
+{"name":"syncdb_snapshot","arguments":{"action":"capture"}}
+{"name":"syncdb_snapshot","arguments":{"action":"compare","snapshotId":"syncdb-...-1","otherSnapshotId":"syncdb-...-2"}}
+```
+
+Snapshots live in the local MCP process. Each capture privately retains the
+TinyBase mergeable content so `mergeSnapshot` can CRDT-merge it back later
+without wiping newer local rows (later HLCs win, including deletes). `get` and
+`compare` never return that merge payload. To restore a specific captured row,
+use `setLocalEntity` from `syncdb_snapshot` `get`.
+
+State changes require an explicit local opt-in:
+
+```bash
+TERRENO_MCP_EVAL=1 bunx terreno-mcp-local
+```
+
+Then use `syncdb_action`. Normal writes should use `mutate`; `flush` drains the
+outbox, and `reconcile` catches up from server snapshots:
+
+```json
+{"name":"syncdb_action","arguments":{"action":"mutate","collection":"todos","operation":"update","id":"todo-1","data":{"completed":true}}}
+{"name":"syncdb_action","arguments":{"action":"flush"}}
+{"name":"syncdb_action","arguments":{"action":"reconcile"}}
+```
+
+Other actions are `forceResync`, `resolveConflict`, `retryFailed`, `goOffline`,
+`goOnline`, `clearDebug`, `setLocalEntity`, `deleteLocalEntity`, and
+`mergeSnapshot`. Direct local edits bypass server validation and outbox
+semantics. `mergeSnapshot` CRDT-merges the captured TinyBase content into the
+live store (later HLCs win) instead of replacing it. Capture a baseline first
+and use these only for fault injection or repair.
+
+## 4. Prove the web fix
+
+Use Bun 1.4's built-in WebView through the local `browser` tool:
+
+```json
+{"name":"browser","arguments":{"action":"open","url":"http://localhost:8082"}}
+{"name":"browser","arguments":{"action":"wait","timeout":1000}}
+{"name":"browser","arguments":{"action":"click","selector":"[data-testid=save]"}}
+{"name":"browser","arguments":{"action":"snapshot"}}
+{"name":"browser","arguments":{"action":"screenshot","output":"/opt/cursor/artifacts/save-result.png"}}
+{"name":"browser","arguments":{"action":"close"}}
+```
+
+The session persists between MCP calls. `snapshot` returns visible text and up to 200 interactive
+elements so the agent can choose selectors and verify state without image guessing. `screenshot`
+saves the viewport for the PR or walkthrough.
+WebView console output is not added to `browser.log`; call `read_logs` alongside this flow when the
+running app posts browser logs to the backend collector. The collector accepts local-loopback
+traffic before login; devices or remote browsers must send the app's normal authentication.
+
+The equivalent one-process CLI sequence is:
+
+```bash
+terreno web http://localhost:8082 \
+  --action '{"action":"click","selector":"[data-testid=save]"}' \
+  --snapshot \
+  --screenshot /opt/cursor/artifacts/save-result.png
+```
+
+## 5. Verify the native fix in the running app
+
+Navigation and arbitrary evaluation are disabled by default. Opt in only for local debugging:
+
+```bash
+TERRENO_MCP_EVAL=1 bunx terreno-mcp-local
+```
+
+Then call `navigate` with `{"path":"/profile"}` or run:
+
+```bash
+TERRENO_MCP_EVAL=1 terreno navigate /profile
+```
+
+Confirm the target screen renders, then call `last_error` again. A successful fix has no new
+error-level entry after the navigation timestamp.
+
+## Connection problems
+
+- Upgrade to Bun 1.4 or newer when `Bun.WebView requires Bun 1.4 or newer` appears.
+- Set `BUN_CHROME_PATH` if WebView cannot discover Chrome, Chromium, or Edge on Linux or Windows.
+- Set `TERRENO_PROJECT_ROOT` if logs or package versions come from the wrong directory.
+- Set `TERRENO_METRO_URL` if Metro is not on the frontend script's `--port`.
+- Close React Native DevTools when Hermes reports another debugger connection.
+- Use only `backend,browser` sources when Metro is intentionally stopped.

package/src/docs/versioned/next/how-to/deploy-backend-to-cloud-run.md

@@ -106,6 +106,8 @@ Expect `"healthy": true`.
 | Live feature flags / realtime never update; log mentions replica set | MongoDB is standalone, not a replica set | Use Atlas or `replSet` — change streams required (`feature-flags/src/featureFlagsApp.ts`) |
 | Bun-compiled container never opens its port while creating indexes | OpenTelemetry Mongoose instrumentation patched an already-loaded Mongoose module | Do not explicitly patch Mongoose in the compiled binary; retain HTTP/Express tracing |
 | Container hangs before listening when cloud logging initializes | A network logging transport blocks startup | Log to stdout/stderr during boot; Cloud Run ingests both streams |
+| `gcloud run deploy --tag` fails citing an old revision that never became Ready | That tag still points at the failed revision; `--remove-tags` keeps it in the traffic spec | Rebuild traffic with `--to-revisions=<live>=100` plus `--set-tags` of Ready tags only, deploy `--no-traffic` without `--tag`, then `--update-tags` the new revision |
+| A zero-traffic preview tag returns `503` with `{"status":"starting"}` indefinitely | The early TCP listener satisfies Cloud Run's startup probe before Mongo and seed work finish; request-only CPU then starves idle boot work | Deploy preview revisions with `--no-cpu-throttling`, then poll the tagged `/health` URL for `"healthy":true` before reporting deployment success |
 | First request after idle is slow; sockets reconnect constantly | Scaled to zero | Set `--min-instances=1` for user-facing services |
 | Browser API calls blocked by CORS | `corsOrigin` / Better Auth `trustedOrigins` missing web origin | Add your CDN URL to backend CORS and auth config |
 

package/src/docs/versioned/next/how-to/deploy-to-gcp.md

@@ -20,7 +20,7 @@ Read the [deployment baseline](../explanation/deployment-baseline.md) — seven
 
 ## Scripts
 
-- [`scripts/setup-gcs-hosting.sh`](https://github.com/FlourishHealth/terreno/blob/master/scripts/setup-gcs-hosting.sh) — parameterized GCS + CDN provisioning for one site
+- [`scripts/setup-gcs-hosting.sh`](https://github.com/TerrenoLabs/terreno/blob/master/scripts/setup-gcs-hosting.sh) — parameterized GCS + CDN provisioning for one site
 
 ## Environment variables
 

package/src/docs/versioned/next/how-to/deploy-web-to-gcs-cdn.md

@@ -174,7 +174,7 @@ gcloud compute url-maps invalidate-cdn-cache "${SITE_NAME}-url-map" \
 
 ## Static-only path
 
-This guide hosts the `expo export -p web` output as static files. Server-rendered web (SSR, API routes) requires Expo SDK ≥ 55 — see [Web SSR and admin SPA](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md).
+This guide hosts the `expo export -p web` output as static files. Server-rendered web (SSR, API routes) requires Expo SDK ≥ 55 — see [Web SSR and admin SPA](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md).
 
 ## Related
 

package/src/docs/versioned/next/how-to/generate-a-rest-cli.md

@@ -0,0 +1,34 @@
+# Generate a REST CLI from OpenAPI
+
+Run this from an app repo that already serves `/openapi.json` (Terreno `setupServer` does).
+
+1. Install the CLI: `bun add -g @terreno/cli` (or `bunx @terreno/cli`).
+2. Generate the wrapper:
+
+```bash
+terreno generate rest-cli \
+  --schema http://localhost:4000/openapi.json \
+  --out ./tools/app-cli \
+  --name myapp \
+  --base-url http://localhost:4000
+```
+
+3. Call the API:
+
+```bash
+cd tools/app-cli
+bun ./src/cli.ts list
+bun ./src/cli.ts call todo_list --param limit=10 --token "$TERRENO_TOKEN"
+bun ./src/cli.ts request GET /todos/{id} --param id=abc --json
+```
+
+Auth uses `--token` or `TERRENO_TOKEN`. Base URL uses `--base-url` or `TERRENO_API_URL`, then `servers[0].url` from the spec.
+
+To list or call without generating a package:
+
+```bash
+terreno api list --schema http://localhost:4000/openapi.json
+terreno api call todo_list --schema ./openapi.json --param limit=10
+```
+
+`generate rest-cli` writes `src/cli.ts` that imports `runAppRestCli` from `@terreno/cli`. Point that dependency at the published `@terreno/cli` version in apps outside this monorepo.

package/src/docs/versioned/next/how-to/github-actions-ci.md

@@ -33,8 +33,9 @@ PR deploy preview.
 | `fingerprint-gate` | Master iOS/Android hashes cached per `pull_request.base.sha` (skips a second `bun run compile`) |
 | `maestro-e2e` | Demo export + static server only when `demo/`, `ui/`, or `.maestro/flows/demo/` change |
 | `example-backend-docker` | Buildx runs only when the image recipe changes (`Dockerfile`, lockfile, `package.json`). Source-only PRs skip; CD preview deploy still builds the image. `load: true` stays off. |
-| `cd` backend preview | Runs the built container against the configured Secret Manager values and requires a healthy `/health` response before pushing or deploying. |
-| Bun install | `.github/actions/setup-bun-workspace` pins Bun `1.4.0` and caches `~/.bun/install/cache` without `github.ref` in the key |
+| `cd` Cloud Run deploys | Runs a local wrapper around `google-github-actions/deploy-cloudrun` that retries only the transient GitHub WIF subject-token timeout, up to three attempts; IAM, image, and configuration failures fail immediately. The backend preview runs for every example-frontend PR preview, including frontend-only changes, so the Netlify build targets an isolated `pr-<number>` backend instead of production. The frontend deploy waits for that backend's healthy `/health` response before publishing to Netlify, and per-PR concurrency cancels duplicate deploys to the same alias. CD runs the built container against the configured Secret Manager values, including the Cloud Tasks `JOBS_*` env, and requires a healthy `/health` response before pushing or deploying. Preview Cloud Run uses `--memory=1Gi` and `--cpu-boost`, overwrites revision secrets, and binds `PORT` before MongoDB connect. Before deploy it rebuilds traffic with `--set-tags` / `--clear-tags` so a not-Ready tagged revision is omitted (`--remove-tags` leaves that revision in the spec and Cloud Run rejects the update). It then deploys `--no-traffic` without `--tag`, sets `--revision-suffix=pr<n>-<run_id>-<run_attempt>`, and tags the new Ready revision afterward. |
+| Bun install | `.github/actions/setup-bun-workspace` pins Bun `1.4.0` and runs `bun install --frozen-lockfile` with no `~/.bun/install/cache`. CircleCI measurements: cache restore (~15–73s) exceeded the install savings (~9s). See [circleci.md](circleci.md#bun-install-is-uncached). |
 
-Playwright e2e still uses one shard per spec file so required check names stay
-`E2E · <spec>`.
+Playwright e2e on CircleCI groups specs into five shards (`e2e-auth`,
+`e2e-app`, `e2e-admin-core`, `e2e-admin-table`, `e2e-syncdb`). The retained GHA
+twin still lists one spec per matrix entry for rollback.

package/src/docs/versioned/next/how-to/github-issue-lifecycle.md

@@ -13,17 +13,17 @@ Two implementation paths:
 ## Create the issue
 
 1. Invoke `/create-github-issue` (or open
-   [Lifecycle work item](https://github.com/FlourishHealth/terreno/issues/new?template=work_item.yml)).
+   [Lifecycle work item](https://github.com/TerrenoLabs/terreno/issues/new?template=work_item.yml)).
 2. Fill **Affected package**, **Kind**, **Problem**, **Outcome**, **Current behavior**,
    **Non-scope**, **Acceptance**, and **Context**.
 3. Stop until the drafted title, body, and labels are approved. Then create.
 
-Existing [bug](https://github.com/FlourishHealth/terreno/issues/new?template=bug_report.yml),
-[feature](https://github.com/FlourishHealth/terreno/issues/new?template=feature_request.yml),
-and [docs](https://github.com/FlourishHealth/terreno/issues/new?template=docs_issue.yml)
+Existing [bug](https://github.com/TerrenoLabs/terreno/issues/new?template=bug_report.yml),
+[feature](https://github.com/TerrenoLabs/terreno/issues/new?template=feature_request.yml),
+and [docs](https://github.com/TerrenoLabs/terreno/issues/new?template=docs_issue.yml)
 forms still work. Prefer the lifecycle form when you want Roast-ready acceptance in
 the body. The canonical heading list is in the
-[`create-github-issue` skill](https://github.com/FlourishHealth/terreno/blob/master/.rulesync/skills/create-github-issue/references/issue-format.md).
+[`create-github-issue` skill](https://github.com/TerrenoLabs/terreno/blob/master/.rulesync/skills/create-github-issue/references/issue-format.md).
 
 `Affected package` must match a known value so issue triage can apply `area:*`.
 `Kind` on the lifecycle form is applied as `type:*` by the same triage job.
@@ -52,22 +52,26 @@ PR.
 
 ## Unattended pickup
 
-1. After triage, apply `status:ready-for-dev` only when Acceptance is roastable and
-   the work fits one Pick comment (at most five tasks). Leave the issue unassigned.
-   Do not edit the issue body after you label it unless you are a maintainer; the
-   skill aborts if an untrusted author changes the body after the label.
+1. After triage, apply `status:ready-for-dev` and leave the issue unassigned.
+   Do not edit the issue body after you label it unless you are a maintainer; pickup
+   aborts if an untrusted author changes the body after the label.
 2. A Cursor Automation (or `/implement-ready-for-dev`) claims the oldest matching
    issue: assignee + `status:in-progress`, remove `status:ready-for-dev`. It skips
    issues that already have an open linked or closing PR (GraphQL references, not
    `linked:<number>`).
-3. It posts `<!-- terreno-pick-plan -->` from that trusted snapshot, Pick ⇄ Roasts
-   that comment, then Brews a **draft** PR with `Fixes #<n>`.
+3. It runs Grow on that trusted snapshot, answers Grow questions from the repo and
+   issue (assumptions posted on the issue), and only stops on GitHub for a genuine
+   human gate (product, security, data ownership, public API, destructive change,
+   rollout, or scope the issue and docs do not settle). Then Pick ⇄ Roast, Brew, and
+   Taste until the PR is mergeable (ready for review). Do not merge.
 4. Dashboard paste: [`implement-ready-for-dev` automation](../../.rulesync/skills/implement-ready-for-dev/references/cursor-automation.md).
 
-Do not apply `status:ready-for-dev` to issues that still need a product decision.
-Those stay `status:needs-info` or go through `/work-github-issues`.
+Do not apply `status:ready-for-dev` to issues that still need a product, security, or
+data-ownership decision. Those stay `status:needs-info` or go through `/work-github-issues`.
+The unattended skill will assume implementation defaults; it will not invent those
+decisions.
 
-Labels live in [`.github/labels.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/labels.yml).
+Labels live in [`.github/labels.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/labels.yml).
 Sync them with the existing roadmap labels workflow before expecting pickup.
 
 ## Related

package/src/docs/versioned/next/how-to/in-app-notifications.md

@@ -0,0 +1,147 @@
+# In-app notifications
+
+Add an owner-scoped inbox, channel preferences, and optional comms fan-out to a Terreno app.
+
+## 1. Register `NotificationsApp`
+
+On your `TerrenoApp`, register the plugin and pass your user model. When you already use
+`@terreno/comms`, pass `getComms` so `notify()` can fan out to mail, SMS, and push.
+
+```typescript
+import {NotificationsApp, TerrenoApp} from "@terreno/api";
+import {CommsApp, getCommsService} from "@terreno/comms";
+
+new TerrenoApp({userModel: User})
+  .register(
+    new NotificationsApp({
+      getComms: getCommsService,
+      retainDays: 0,
+      userModel: User,
+    })
+  )
+  .register(new CommsApp({/* providers */}))
+  .start();
+```
+
+`retainDays` defaults to `0` (keep all rows). Set a positive number to tombstone rows older
+than that many days (no Mongo TTL index).
+
+## 2. Wire comms preferences
+
+Export `notificationsBeforeSend` from `@terreno/api` and compose it into `CommsApp`
+`beforeSend`. It cancels outbound mail, SMS, or push when the user turned that channel off.
+The `verification` channel is never cancelled.
+
+```typescript
+import {notificationsBeforeSend} from "@terreno/api";
+
+new CommsApp({
+  beforeSend: async (context) => {
+    const pref = await notificationsBeforeSend({
+      channel: context.channel,
+      userId: context.userId,
+    });
+    if (pref?.cancel) {
+      return {cancel: true};
+    }
+    return undefined;
+  },
+  mail: mailProvider,
+});
+```
+
+## 3. Send notifications from server code
+
+Only the service inserts inbox rows (HTTP create is disabled).
+
+```typescript
+import {getNotificationService} from "@terreno/api";
+
+await getNotificationService().notify({
+  userId: String(user._id),
+  title: "Todo completed",
+  body: "Your task is done.",
+  href: "/todos",
+  kind: "todo",
+});
+```
+
+Fan-out order: inbox write (when `inapp` is on), then mail, SMS, and push when each
+preference is on and a destination exists. Missing email, phone, or push tokens skip that
+channel without failing `notify()`. A provider rejection on one channel is logged and
+does not skip later channels.
+
+## 4. Sync collections on the client
+
+Regenerate syncdb hooks (not RTK CRUD) for `notifications` and `notification-preferences`:
+
+```bash
+cd example-frontend
+bun run sync-sdk
+```
+
+Add the generated `SYNC_COLLECTIONS` to `createSyncDb`. Use `useQuery` / `useMutate` (or
+generated hooks) for list, mark-read (`readAt`), and dismiss (delete).
+
+## 5. Presentational UI
+
+Import the bell, inbox, and right-side drawer from `@terreno/ui`. The components take
+data and callbacks only — wire them to syncdb in your screen:
+
+```typescript
+import {NotificationBell, NotificationInbox, SideDrawer} from "@terreno/ui";
+
+<NotificationBell unreadCount={unreadCount} onPress={() => setOpen((value) => !value)} />
+<SideDrawer
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  position="right"
+  renderContent={() => (
+    <NotificationInbox
+      items={items}
+      onMarkRead={(item) => patch({id: item.id, data: {readAt: DateTime.now().toISO()}})}
+      onMarkUnread={(item) => patch({id: item.id, data: {readAt: null}})}
+      onDismiss={(item) => remove({id: item.id})}
+      onOpen={(item) => item.href?.startsWith("/") && router.push(item.href)}
+    />
+  )}
+>
+  {screen}
+</SideDrawer>
+```
+
+Customize the bell without reimplementing its tap target or unread accessibility label:
+
+```typescript
+<NotificationBell
+  unreadCount={unreadCount}
+  onPress={() => setOpen((value) => !value)}
+  renderIcon={({testID}) => <BrandBell testID={testID} />}
+  renderBadge={({testID, unreadCount}) => (
+    <BrandBubble count={unreadCount} testID={testID} />
+  )}
+/>
+```
+
+Treat dismissed rows as archived, not deleted. Dismiss PATCHes `archivedAt` through
+syncdb so the row stays in the owner snapshot with its payload. The active inbox
+filters `archivedAt` out; the full history page uses the same `useQuery("notifications")`
+and splits on `archivedAt`. Retention (`retainDays`) still tombstones old rows with
+`deleted: true`; those drop out of history after compaction. Map `archivedAt` (or a
+legacy `deleted` tombstone still in the local store) to `NotificationInboxItem.archived`.
+Archived rows remain readable but `NotificationInbox` hides their dismiss and read-state
+actions.
+
+See `example-frontend/components/NotificationCenter.tsx` and
+`example-frontend/app/notifications.tsx` for the drawer and complete history page.
+These components are not in the `@terreno/ui` component demo.
+
+The example todo router also demonstrates lifecycle-generated activity notifications:
+`postCreate` reports added todos, `postUpdate` reports a false-to-true `completed`
+transition, and `postDelete` reports deletion.
+
+## Reference
+
+- API shapes: [In-app notifications](../reference/api.md#in-app-notifications)
+- UI props: [Notification components](../reference/ui.md#notification-components)
+- Comms hook: [beforeSend composition](../reference/comms.md#notification-preferences-hook)

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

@@ -3,8 +3,8 @@
 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
+npx skills add TerrenoLabs/terreno
+npx skills add TerrenoLabs/terreno --skill terreno-1-grow
 ```
 
 That copies the committed `skills/` tree: lifecycle stages (Grow, Pick, Roast, Brew,
@@ -13,44 +13,53 @@ skills.
 
 ## Install as a host plugin
 
-The combined lifecycle and Terreno app workflows ship as one host plugin. Stage names
-differ by host because Claude Code takes a plugin skill's command from the frontmatter
-`name`.
+Two plugins ship from this marketplace: the combined lifecycle and Terreno app workflows,
+and the optional goal-driven scan plugin. Stage names differ by host because Claude Code
+takes a plugin skill's command from the frontmatter `name`.
 
-| Host | Plugin | Invoke Grow |
-| --- | --- | --- |
-| Cursor | `terreno-planning` | `/terreno-1-grow` |
-| Codex | `terreno-planning` | `$terreno-1-grow` |
-| Claude Code | `terreno` | `/terreno:1-grow` |
+| Host | Plugin | Invoke Grow | Scan plugin | Invoke Aim |
+| --- | --- | --- | --- | --- |
+| Cursor | `terreno-planning` | `/terreno-1-grow` | `terreno-scan` | `/terreno-scan-1-aim` |
+| Codex | `terreno-planning` | `$terreno-1-grow` | `terreno-scan` | `$terreno-scan-1-aim` |
+| Claude Code | `terreno` | `/terreno:1-grow` | `terreno-scan` | `/terreno-scan:1-aim` |
+
+`terreno-scan` depends on the lifecycle plugin: Plot hands each slice to Grow. Its
+resident loop (`/terreno-scan:loop`, `/terreno-scan-loop`, `$terreno-scan-loop`) keeps a
+goal running and heartbeats over the PRs it opens. See the
+[scan plugin reference](../reference/scan-plugin.md).
 
 ### Cursor
 
-Install `terreno-planning` from [`.cursor-plugin/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.cursor-plugin/marketplace.json), then invoke `/terreno-1-grow`.
+Install `terreno-planning` from [`.cursor-plugin/marketplace.json`](https://github.com/TerrenoLabs/terreno/blob/master/.cursor-plugin/marketplace.json), then invoke `/terreno-1-grow`.
 
 ### Codex
 
 ```text
-codex plugin marketplace add FlourishHealth/terreno
+codex plugin marketplace add TerrenoLabs/terreno
 codex plugin install terreno-planning --source terreno-plugins
+codex plugin install terreno-scan --source terreno-plugins
 $terreno-1-grow
 ```
 
-Marketplace: [`.agents/plugins/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.agents/plugins/marketplace.json).
+Marketplace: [`.agents/plugins/marketplace.json`](https://github.com/TerrenoLabs/terreno/blob/master/.agents/plugins/marketplace.json).
 Codex installs the canonical plugin at
-[`plugins/terreno-planning/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-planning)
+[`plugins/terreno-planning/`](https://github.com/TerrenoLabs/terreno/tree/master/plugins/terreno-planning)
 (`.codex-plugin/plugin.json`). A clone of this repo already exposes that marketplace.
 
 ### Claude Code
 
 ```text
-/plugin marketplace add FlourishHealth/terreno
+/plugin marketplace add TerrenoLabs/terreno
 /plugin install terreno@terreno-plugins
+/plugin install terreno-scan@terreno-plugins
 /terreno:1-grow
 ```
 
-Marketplace: [`.claude-plugin/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.claude-plugin/marketplace.json).
+Marketplace: [`.claude-plugin/marketplace.json`](https://github.com/TerrenoLabs/terreno/blob/master/.claude-plugin/marketplace.json).
 Claude Code stages, app skills, and agents come from the generated 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);
+scan stages come from
+[`plugins/terreno-scan-claude/`](https://github.com/TerrenoLabs/terreno/tree/master/plugins/terreno-scan-claude).
 
 ## What you get
 
@@ -60,6 +69,7 @@ Claude Code stages, app skills, and agents come from the generated copy at
 | Terreno apps | backend, UI, admin interfaces, data, schema, SDK, prompts, upgrades, deployment |
 | Docs | `update-docs`, `update-agent-docs`, architecture skills |
 | GitHub | issues, review, UI verification, release, dependency updates |
+| Code scans | `terreno-scan-1-aim` … `terreno-scan-5-track`, `terreno-scan-campaign`, `terreno-scan-loop` |
 | Expo and native | `track-upstream-expo`, `upgrading-expo`, deployment / EAS skills |
 | Plugin agents | `pre-commit`, `ui-verifier` |
 
@@ -73,10 +83,12 @@ Canonical sources:
 
 1. `plugins/terreno-planning/skills/` — lifecycle and reusable Terreno app workflows
 2. `plugins/terreno-planning/agents/` — reusable verification agents
-3. `.rulesync/skills/` — repository-only and optional Expo skills (`bun run rules` generates agent copies)
-4. `<package>/.ai/skills/` — package/MCP-specific copies; not installable overlays
+3. `plugins/terreno-scan/skills/` — scan stages and the campaign loop
+4. `.rulesync/skills/` — repository-only and optional Expo skills (`bun run rules` generates agent copies)
+5. `<package>/.ai/skills/` — package/MCP-specific copies; not installable overlays
 
-`plugins/terreno-claude/` is generated from sources 1 and 2 with shortened lifecycle names.
+`plugins/terreno-claude/` is generated from sources 1 and 2, and
+`plugins/terreno-scan-claude/` from source 3, both with shortened skill names.
 Codex uses the canonical plugin plus committed `.codex-plugin/plugin.json` and
 `.agents/plugins/marketplace.json` — do not generate a third plugin tree.
 
@@ -102,4 +114,4 @@ an agent finishes.
 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).
+[documentation contract](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-planning/references/documentation-contract.md).

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

@@ -4,7 +4,7 @@ This guide is **AI-context-first**: it is written for an agent (or human) perfor
 
 `@terreno/syncdb` supersedes `@terreno/rtk` for **data synchronization** (CRUD reads/writes, offline queue, realtime convergence). It does not replace the generated OpenAPI SDK, Better Auth Redux wiring, or feature-flag infrastructure.
 
-`modelRouter` `realtime`, `realtimeList`, `realtimeDocument`, and `setRealtimeSocket` are **deprecated** and **will be removed in Terreno 58**. `RealtimeApp` stays as the socket host for syncdb. Removal checklist: [`docs/tasks/remove-legacy-realtime.md`](https://github.com/FlourishHealth/terreno/blob/master/docs/tasks/remove-legacy-realtime.md).
+`modelRouter` `realtime`, `realtimeList`, `realtimeDocument`, and `setRealtimeSocket` are **deprecated** and **will be removed in Terreno 58**. `RealtimeApp` stays as the socket host for syncdb. Removal checklist: [`docs/tasks/remove-legacy-realtime.md`](https://github.com/TerrenoLabs/terreno/blob/master/docs/tasks/remove-legacy-realtime.md).
 
 ## 1. Before you start
 
@@ -21,11 +21,13 @@ This guide is **AI-context-first**: it is written for an agent (or human) perfor
 1. **Step A — Auth:** Move login/session to Better Auth (`generateBetterAuthSlice`, `betterAuthAdapter`, `syncDb.start()` on login). Screens can still read/write via RTK Query during this step.
 2. **Step B — Data:** For each collection, replace RTK Query hooks with syncdb hooks and delete the RTK path for that screen.
 
-The example app completed both steps; todos are syncdb-only while profile/admin still use generated RTK hooks.
+The example app completed both steps. Product Todos and eligible built-in admin
+String-`_id` model CRUD use syncdb. Profile and other non-synced routes keep
+generated RTK hooks; admin RPC uses its host-bound fetch client.
 
 **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).
+Reference: [`docs/reference/syncdb.md`](../reference/syncdb.md), and the package [`syncdb/README.md`](https://github.com/TerrenoLabs/terreno/blob/release-56.0.0/syncdb/README.md).
 
 ## 2. Install and configure
 
@@ -348,7 +350,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 | Collection CRUD — import from `store/syncDbSdk.ts` instead |
+| Auth routes, `GET /auth/me`, AI routes, feature flags, ObjectId admin compatibility CRUD | 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`.
@@ -371,6 +373,20 @@ 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`.
 
+### Built-in admin
+
+For a synced String-`_id` model, set `sync.adminBroadcast: true` on its existing
+`modelRouter` sync config and inject a dedicated `createSyncDb` client with
+`windowCollections` into `AdminProvider`. REST remains the list membership,
+search, sort, pagination, and bulk-patch surface; TinyBase overlays rows and
+`useMutate` handles create/update/delete. Pass the host's `useConflicts()` result
+as `syncConflicts`.
+
+Admin RPC (config, scripts, roles, comms, consent, documents, version config,
+background tasks) uses admin-frontend's host-bound native fetch client. Do not
+add new admin `injectEndpoints`. Terreno 57 keeps `useAdminApi` and the required
+`api` prop only for ObjectId/API-only compatibility; Terreno 58 removes them.
+
 ## 9. Feature flags
 
 Post-migration, feature flags stay on `@terreno/rtk` + OpenFeature — **not** on syncdb.
@@ -453,7 +469,7 @@ Before a collection can sync:
 - [ ] `syncPlugin` on schema (`_syncSeq` stamping)
 - [ ] `modelRouter("/path", Model, {sync: {scope: ...}})` three-argument form
 - [ ] Custom scopes include `snapshotFilter`
-- [ ] `new SyncApp({getUserScopes?})` for tenant/custom scopes
+- [ ] `new SyncApp({getUserScopes?, accessControl?})` for tenant/custom scopes and admin-window `admin:access` (mount `AdminApp` too so admin `queryFilter` / resource actions apply to hydrate and `|admin` deltas)
 - [ ] `new RealtimeApp({betterAuth?})` + MongoDB replica set
 - [ ] No `updateMany`, `deleteMany`, `deleteOne`, `findOneAndDelete`, or `bulkWrite` on synced models
 
@@ -468,5 +484,5 @@ Before a collection can sync:
 ## Further reading
 
 - [`docs/reference/syncdb.md`](../reference/syncdb.md) — full API reference
-- [`syncdb/README.md`](https://github.com/flourishhealth/terreno/blob/release-56.0.0/syncdb/README.md) — architecture and protocol detail
+- [`syncdb/README.md`](https://github.com/TerrenoLabs/terreno/blob/release-56.0.0/syncdb/README.md) — architecture and protocol detail
 - [`docs/how-to/configure-better-auth.md`](configure-better-auth.md) — Better Auth setup