@terreno/agent-plugin 0.0.0-stage → 58.0.0-beta.2

package/skills/backend-test-env/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: backend-test-env
+description: >-
+  Invoke when writing tests that mutate `process.env` in `@terreno/api`,
+  `@terreno/ai`, or `example-backend` — feature flags, auth secrets, integration
+  toggles. Covers the preload contract, `setupEnvironment()`, and safe mutation
+  patterns. Lifecycle composition: Pick when writing these tests; Roast when
+  independently reproducing env-sensitive behavior.
+---
+# Backend Test — `process.env` Contract
+
+Bun's test runner preloads a per-package setup file (configured in each package's `bunfig.toml` under `[test].preload`):
+
+| Package | Preload file |
+|---------|--------------|
+| `@terreno/api` | `api/src/tests/bunSetup.ts` |
+| `@terreno/admin-backend` | `admin-backend/src/tests/testEnv.ts` then `api/src/tests/bunSetup.ts` (`testEnv` sets `TERRENO_TEST_USE_MEMORY_MONGO` for **mongodb-memory-server**) |
+| `@terreno/ai` | `ai/src/tests/bunSetup.ts` |
+| `@terreno/comms` | `comms/src/tests/bunSetup.ts` |
+| `example-backend` | `example-backend/src/tests/setup.ts` |
+
+The `@terreno/api` preload uses a global `beforeEach` to (1) reset the canonical auth secrets, (2) call `setupEnvironment()` (exported from `expressServer.ts`) for the wider baseline, and (3) re-silence the winston loggers. The next test always starts from the canonical baseline — you normally **do not** need to re-call `setupEnvironment()` in a file-level `beforeEach`.
+
+**Mongo in tests:** `api/src/tests/bunSetup.ts` connects to `mongodb://127.0.0.1/terreno` by default. If `TERRENO_TEST_USE_MEMORY_MONGO=true`, it starts **MongoMemoryServer** and connects to that URI instead (then stops it in `afterAll`). `TERRENO_TEST_MONGODB_URI` overrides both and points at any MongoDB you choose.
+
+## Default — Rely on the Preload
+
+- Do not assume a toggle left by another file. Treat the preload's `beforeEach` as the source of truth for the canonical baseline.
+- Set only the keys this test needs in its own `beforeEach` or test body.
+- Don't reach in and call `setupEnvironment()` again unless you're explicitly testing env-driven behavior that the preload didn't cover.
+
+## When a Test Mutates `process.env`
+
+1. **Add the key to the preload's reset list** if it should always start from a fixed test value. Otherwise it leaks into the next test in the same worker.
+2. **Set only what this case needs** in the test body — avoid redundant manual restore if the preload already resets that key in `beforeEach`.
+3. **For keys that should be absent (unset)**, use **`Reflect.deleteProperty(process.env, "KEY")`**. Avoid `process.env.KEY = ""` to mean "unset" — on some platforms empty string and unset behave differently and can make tests flaky.
+4. **Avoid whole-env snapshots** (`const OLD_ENV = process.env; ...; process.env = OLD_ENV;`). This pattern exists in some older test files (`auth.test.ts`) — don't propagate it. It captures pre-`beforeEach` state and breaks ordering guarantees if the preload's `beforeEach` runs in between. Use targeted mutations + the preload's reset instead.
+
+## Adding a New Required Env Var
+
+If you introduce a new `process.env.FOO` that backend code reads at startup:
+
+1. Add `FOO` to `setupEnvironment()` in `api/src/expressServer.ts` so every package picks it up via the preload's `setupEnvironment()` call.
+2. If `example-backend` has its own startup needs for it, also add to `example-backend/src/tests/setup.ts`'s `beforeAll`.
+3. If a test needs to mutate it, follow the rules above — don't snapshot the whole env.
+
+## Auth-Related Keys
+
+`api/src/tests/bunSetup.ts` resets four auth keys in `beforeEach`: `TOKEN_SECRET`, `TOKEN_ISSUER`, `SESSION_SECRET`, `REFRESH_TOKEN_SECRET`. If your test changes any of these, you do not need to restore — the next `beforeEach` already does. If your test relies on them being **absent** for a code path, use `Reflect.deleteProperty` within the test, knowing the next `beforeEach` will restore.
+
+`auth.test.ts` is the established home for env-driven auth assertions; mirror its newer patterns (per-test `beforeEach` setting only what changes) rather than its older whole-env-snapshot blocks.
+
+## Log Capture & Sentry
+
+The preload silences winston and `console.*` and captures into an in-memory buffer (cleared in `beforeEach`/`afterEach`). It also mocks `@sentry/bun`. Don't re-mock Sentry inside individual tests — the preload's mock is shared and reset across tests.
+
+## Checklist
+
+- [ ] New env var added to `setupEnvironment()` and (if needed) `example-backend/src/tests/setup.ts`
+- [ ] Test mutations are targeted — no whole-env snapshots
+- [ ] "Unset" expressed as `Reflect.deleteProperty(process.env, "KEY")`, not `= ""`
+- [ ] No manual restore that duplicates the preload's `beforeEach` reset
+- [ ] No re-mock of `@sentry/bun` — the preload's mock is already in place
+- [ ] If you added an env-driven branch in code, a test covers both the set and the unset case

package/skills/backfill-regression/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: backfill-regression
+description: >-
+  Backfill a repository's manual regression suites. Survey the app for behavior that only a
+  developer or QA can check by hand (push notifications and other hardware or OS behavior,
+  real email or SMS delivery, full cross-device flows, how the app feels) plus a short check
+  that the app works as intended, propose candidate cases one area at a time, and have the
+  human approve, edit, or deny each set before anything is written. Loops until no
+  candidates remain or the human stops. Use when asked to backfill, seed, or audit regression
+  tests or a manual QA checklist; not for planning a feature (Grow writes those cases) or for
+  writing automated tests.
+---
+# Backfill regression
+
+Build the minimal manual pass a developer or QA walks before a release. Every case is
+approved by the human before it is written. The suites stay small: fewer, sharper cases
+beat coverage.
+
+Read [`testing-plan`](../../references/testing-plan.md) first. Its "Keep regression
+minimal" section decides what may be a case, its suite file format decides how a case is
+written, and its regression-step bar decides whether a case is good enough.
+
+## Inputs
+
+- The resolved `E2E guide`, `Regression suites`, and `Smoke command` per the testing plan
+- Every existing suite file, its `Area:` prefix, and its highest ID
+- The ledger at `.terreno/regression-backfill.json`, when present (see Ledger)
+- Optional scope from the human: an area, a package, or a list of features
+
+## Procedure
+
+When `Regression suites` resolves to `none` (the testing-plan opt-out), stop: report that
+the repository opted out of manual regression suites, and write nothing.
+
+1. **Survey.** Use explore subagents in parallel. Collect evidence of behavior automation
+   cannot reach, each with a file and line:
+   - hardware and OS: push registration and delivery, notification permission, camera,
+     photo library, location, biometrics, secure storage across reinstall, deep and
+     universal links from outside the app, background and resume
+   - delivery outside the app: email, SMS, and push that must reach a real inbox or device
+   - full flows across apps, devices, or channels: a change on one device showing on
+     another, an admin action reaching a user's phone, offline then online
+   - feel: gestures, drawing, keyboard avoidance, animation, layout on small screens
+   - the app works: sign in, the main screen loads, the core action succeeds, on each
+     shipped platform. One short case per platform, not per screen.
+2. **Filter.** Drop a candidate when an existing suite case already covers it, when an
+   e2e spec, smoke, or unit test already proves it, when a guide layer could drive and
+   assert it (note it as an automation gap in the final report instead), or when the
+   ledger records it as denied. Merge near-duplicates into one case.
+3. **Group into sets.** One set per area, at most five cases, highest risk first. A
+   set names its destination suite file, existing or new, with its `Area:` prefix.
+   Write each case in the suite table format with a provisional `<AREA>-new-<n>` ID,
+   `Automated by: manual`, and `Added: regression-backfill`. Every case meets the
+   regression-step bar, and its evidence line explains why it cannot be automated.
+4. **Ask, one set at a time.** Show the set as a table with each case's evidence, and
+   ask the human, using the structured question tool when available:
+   - **Approve all**: write every case in the set.
+   - **Approve some**: the human names the case IDs to keep; deny the rest.
+   - **Edit**: the human's changes are applied, and the set is shown again.
+   - **Deny all**: write nothing for this set.
+   - **Stop**: end the loop now.
+   Never write a case the human has not approved.
+5. **Write approved cases.** Append them to the suite file with real IDs: one past the
+   highest ID the file has ever held, never reused. A new suite file follows the suite
+   file format, with `Last full run: never` and `Owner:` from the human or `unassigned`.
+   Add a new area to the suite index when the repository keeps one. Run the repository's
+   suite check when it has one, and fix any failure before the next set.
+6. **Record.** Append each case to the ledger as approved or denied, then go to the next
+   set. When every set is answered, survey once more for areas the answers opened up;
+   stop when a pass yields no new candidate.
+
+## Ledger
+
+`.terreno/regression-backfill.json` stays out of version control: add `.terreno/` to
+`.gitignore` when it is missing. It keeps a denied case from being proposed again:
+
+```json
+{"cases": [{"area": "TODO", "case": "A todo shows on a second device", "decision": "denied", "date": "2026-01-15"}]}
+```
+
+Match a candidate against the ledger by area and meaning, not exact wording.
+
+## Report
+
+When the loop ends, report once:
+
+- cases written, per suite file, with their real IDs
+- sets and cases denied
+- automation gaps: candidates a guide layer could cover, each with the layer and the
+  spec path the guide prescribes, offered as follow-up work, not built
+- the suite check result
+
+Do not commit or push unless the human asks. A commit message says which suites gained
+cases.
+
+## Never
+
+- write a case the human did not approve, or re-propose one the ledger records as denied
+- add a case for something an automated test can prove
+- walk a case or change `Last full run`; only a developer or QA does that
+- renumber or delete an existing case

package/skills/backfill-user-guide/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: backfill-user-guide
+description: >-
+  Backfill a repository's end-user guide. Survey the shipped app for user-facing features
+  (screens, navigation, forms, settings, admin tools) that have no guide page, draft pages in
+  the user-guide format one area at a time, and have the human approve, edit, or deny each set
+  before anything is written. Loops until every shipped feature has a page or a recorded
+  denial, or the human stops. Use when asked to backfill, seed, or audit the user guide, help
+  pages, or "how do I" docs for chat agents; not for planning a feature (Grow plans those
+  pages) or for developer docs.
+---
+# Backfill user guide
+
+Write the pages a user, or a chat agent answering for one, needs to use the features the
+app already ships. Every page is approved by the human before it is written.
+
+Read [`user guide`](../../references/user-guide.md) first. Its page format decides how a
+page is written, its guide-entry bar decides whether a page is good enough, and its opt-out
+rule decides whether to run at all: when the repository's resolved `User guide` is `none`,
+report that the guide is off and stop.
+
+## Inputs
+
+- The resolved `User guide` path per the user-guide contract, its `README.md` index, and
+  every existing page with its `area` and `questions`
+- The ledger at `.terreno/user-guide-backfill.json`, when present (see Ledger)
+- The repository's guide check command, when it has one
+- Optional scope from the human: an area, an app, or a list of features
+
+## Procedure
+
+1. **Survey.** Use explore subagents in parallel, one per app or top-level area. Collect
+   each shipped user-facing feature with evidence (a file and line):
+   - every routed screen and tab, and how a user reaches it
+   - every action a user takes there: create, edit, delete, search, filter, share, export
+   - account flows: sign up, sign in, sign out, password reset, profile, settings,
+     consent, notifications, deleting an account
+   - staff and admin tools, recorded with `audience: admin` or `staff`
+   - feature flags and platform checks that hide a feature from some users or platforms
+   Read the on-screen labels from the source (button text, titles, headings), never from
+   memory, and note which platforms render each screen. When the repository has an
+   inventory command for the guide, run it to list screens no page covers.
+2. **Filter.** Drop a feature when an existing page already covers it, when it is not
+   reachable by any user (dead code, a flag that is off everywhere, a developer-only
+   screen), or when the ledger records it as denied. Merge features a user thinks of as
+   one task into one page.
+3. **Group into sets.** One set per area, at most five pages, most-used features first.
+   Draft each page in full in the page format, with `added: user-guide-backfill`. Every
+   page meets the guide-entry bar: user words only, every step names a real on-screen
+   label, and nothing a chat agent must not repeat (personal data, secrets, internal
+   URLs, staff procedures on a `user` page).
+4. **Ask, one set at a time.** Show each page's title, audience, platforms, questions, and
+   steps, with the evidence for its labels, and ask the human, using the structured
+   question tool when available:
+   - **Approve all**: write every page in the set.
+   - **Approve some**: the human names the pages to keep; deny the rest.
+   - **Edit**: the human's changes are applied, and the set is shown again.
+   - **Deny all**: write nothing for this set.
+   - **Stop**: end the loop now.
+   Never write a page the human has not approved.
+5. **Write approved pages.** Write each page at `<User guide>/<area>/<feature>.md` and add
+   it to the index table. A missing guide directory gets its `README.md` index first. Run
+   the repository's guide check when it has one, and fix any failure before the next set.
+6. **Record.** Append each page to the ledger as approved or denied, then go to the next
+   set. When every set is answered, survey once more for features the answers opened up;
+   stop when a pass yields no new candidate.
+
+## Ledger
+
+`.terreno/user-guide-backfill.json` stays out of version control: add `.terreno/` to
+`.gitignore` when it is missing. It keeps a denied page from being proposed again:
+
+```json
+{"pages": [{"area": "todos", "title": "Export todos as CSV", "decision": "denied", "date": "2026-01-15"}]}
+```
+
+Match a candidate against the ledger by area and meaning, not exact wording.
+
+## Report
+
+When the loop ends, report once:
+
+- pages written, per area, with their paths
+- sets and pages denied
+- features left without a page, and why
+- the guide check result
+
+Do not commit or push unless the human asks. A commit message says which areas gained
+pages.
+
+## Never
+
+- write a page the human did not approve, or re-propose one the ledger records as denied
+- describe a feature that does not ship, or a label you did not read in the source
+- put personal or health information, real accounts, secrets, or internal URLs in a page
+- run when the repository opts out of the user guide

package/skills/bootstrap-mcp-server/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: bootstrap-mcp-server
+description: Bootstrap a backend-only Terreno MCP server that ships as a single Bun executable with the admin console embedded. Scaffolds the backend with create-terreno-app, drops the frontend, registers MCP tools, service tokens, optional MCP OAuth using the admin console's consent screen, a request log, tool on/off switches, and the MCP admin screens, then compiles everything (admin SPA included) into one binary. Trigger with "bootstrap an MCP server", "new Terreno MCP server", "MCP-only backend", or "ship the MCP server as a binary". Not for a full Expo app (use the terreno_bootstrap prompt / create-terreno-app) or for adding MCP tools to an existing app (see https://terreno-docs.netlify.app/how-to/expose-mcp-tools).
+targets: ['*']
+---
+
+# Bootstrap an MCP server
+
+The MCP-only sibling of the `terreno_bootstrap` prompt. Output: one directory with a Terreno
+backend whose product surface is `POST /mcp`, an admin console at `/console`, and a
+`bun run build:binary` script that emits **one executable** with the admin SPA
+embedded. MongoDB stays external (a replica set, as for every Terreno backend).
+
+Requires the `@terreno/*` release that ships `mcpAdminModels`, `mcpRequestLog`,
+`mcpToolSettings`, and the admin SPA consent route (check `CHANGELOG.md` for "MCP admin screens";
+`create-terreno-app` scaffolds that version or newer).
+
+## When to use
+
+- The user wants a remote MCP server (Claude.ai / ChatGPT connectors, Claude Code, Cursor,
+  Perplexity) backed by Terreno auth, permissions, and models.
+- The user wants that server deployable as a single file (`scp` + `systemd`, a tiny container,
+  or a homelab box behind a Cloudflare Tunnel).
+
+## Inputs
+
+Ask only for what is missing:
+
+1. `appName` (kebab-case) and `appDisplayName`.
+2. Public origin the server will be reached at (for example `https://mcp.example.com`). Needed
+   for `PUBLIC_API_URL`, the OAuth `issuer`, and the Better Auth URL. Use
+   `http://localhost:4000` until the user has one.
+3. Which clients must connect: static-key clients (Perplexity, Cursor, Claude Code) need
+   **service tokens**; Claude.ai / ChatGPT connectors need **MCP OAuth**. Default: both.
+
+## Steps
+
+Complete each step before the next. Each ends with a check.
+
+### 1. Scaffold the backend only
+
+```bash
+bunx create-terreno-app <appName> --display-name "<appDisplayName>"
+cd <appName>
+rm -rf frontend            # MCP-only: the admin console is the only UI
+```
+
+Remove `frontend` from the root workspace list and root scripts. Check: `bun install` succeeds
+and `cd backend && bun run compile` (or `bunx tsc --noEmit`) passes.
+
+### 2. Add the admin packages
+
+```bash
+cd backend
+bun add @terreno/admin-backend @terreno/admin-spa
+```
+
+Register, in this order, after `BetterAuthApp`:
+
+```typescript
+import {AdminApp, mcpAdminModels, mcpAdminScripts} from "@terreno/admin-backend";
+import {AdminSpaServeApp} from "@terreno/admin-spa";
+
+terreno
+  .register(
+    new AdminApp({
+      models: [...appAdminModels, ...mcpAdminModels({requestLog: true, toolSettings: true})],
+      scripts: mcpAdminScripts(),
+    })
+  )
+  .register(
+    new AdminSpaServeApp({
+      appConfig: {brandName: APP_NAME, providers: ["email"]},
+      basePath: "/console",
+      // Set by src/embeddedAssets.ts in the compiled binary; undefined in dev.
+      distDir: process.env.ADMIN_SPA_DIST_DIR,
+    })
+  );
+```
+
+`mcpAdminModels({requestLog: true, toolSettings: true})` adds the **MCP** sidebar group (service
+tokens, OAuth clients, OAuth connections, request log, tools; keep the two flags matched to the
+`TerrenoApp` options) and `mcpAdminScripts()` adds `mcp-sign-out-everywhere`. If the
+app uses RBAC (`accessControl`), spread `mcpAdminStatements` into its statements. See
+https://terreno-docs.netlify.app/how-to/manage-mcp-in-admin. Check: `curl -I localhost:4000/console` returns 200 (the
+published package ships the prebuilt SPA).
+
+### 3. Turn on the MCP surface
+
+In the `TerrenoApp` options:
+
+```typescript
+mcpServiceTokens: {enabled: true, publicMcpUrl: process.env.PUBLIC_API_URL},
+mcpOAuth: process.env.MCP_OAUTH_ENABLED === "true"
+  ? {
+      allowedRedirectHosts: ["claude.ai", "chatgpt.com"],
+      consentUrl: `${process.env.PUBLIC_API_URL}/console/oauth/consent`,
+      dynamicClientRegistration: true,
+      enabled: true,
+      issuer: process.env.PUBLIC_API_URL!,
+    }
+  : undefined,
+mcpRequestLog: {enabled: true, retentionDays: 30},   // metadata only, never tool arguments
+mcpToolSettings: true,                               // admin on/off switch per tool
+rateLimit: {store: "memory", trustProxy: "loopback"},   // registration and token endpoints are unauthenticated
+```
+
+Expose tools with `mcp: {methods: ["list", "read"]}` on `modelRouter` and custom tools with
+`registerMCPTool` (see https://terreno-docs.netlify.app/how-to/expose-mcp-tools). Ship at least one tool, or `/mcp` is
+not mounted.
+
+**Consent screen (OAuth only).** `consentUrl` points at the admin console's built-in consent
+screen (`@terreno/admin-spa`, route `/oauth/consent`). Any signed-in user can approve there, not
+only admins; a signed-out user signs in and comes back. Keep the `/console` part equal to
+`AdminSpaServeApp`'s `basePath`. Check: `curl -s -X POST localhost:4000/mcp` returns 401 with a
+`WWW-Authenticate: Bearer resource_metadata=...` header when OAuth is on.
+
+### 4. Check the MCP admin screens
+
+Seed an admin, sign in at `/console`, and open the **MCP** group. Check: **MCP tools** lists every
+tool with `enabled: true`; switching one off removes it from `tools/list`.
+
+### 5. Embed the admin console in the binary
+
+`bun build --compile` resolves `__dirname` to `$bunfs`, so `AdminSpaServeApp` cannot find the
+SPA bundle on disk. The published `@terreno/admin-spa` already ships its prebuilt export in
+`node_modules/@terreno/admin-spa/dist`; embed that and extract it at boot. No Expo or Node build
+step is needed.
+
+`scripts/generateEmbeddedAssets.ts` (writes a manifest of `with {type: "file"}` imports):
+
+```typescript
+import {readdirSync, statSync, writeFileSync} from "node:fs";
+import {join, relative, resolve} from "node:path";
+
+const root = resolve(process.argv[2] ?? "node_modules/@terreno/admin-spa/dist");
+const files: string[] = [];
+const walk = (dir: string): void => {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) {
+      walk(path);
+    } else {
+      files.push(path);
+    }
+  }
+};
+walk(root);
+const lines = files.map((file, i) => `import f${i} from ${JSON.stringify(file)} with {type: "file"};`);
+lines.push(
+  `export const ADMIN_SPA_FILES: {path: string; file: string}[] = [${files
+    .map((file, i) => `{path: ${JSON.stringify(relative(root, file))}, file: f${i}}`)
+    .join(",\n")}];`
+);
+writeFileSync("src/embeddedAdminSpa.generated.ts", `${lines.join("\n")}\n`);
+```
+
+Commit `src/embeddedAdminSpa.generated.ts` as this stub so a fresh clone typechecks and
+`bun run dev` works. `build:binary` (step 6) restores it after compiling:
+
+```typescript
+export const ADMIN_SPA_FILES: {path: string; file: string}[] = [];
+```
+
+`src/embeddedAdminSpa.ts`, imported at the top of `src/index.ts` before the server module:
+
+```typescript
+import {mkdirSync, writeFileSync} from "node:fs";
+import {tmpdir} from "node:os";
+import {dirname, join} from "node:path";
+import {ADMIN_SPA_FILES} from "./embeddedAdminSpa.generated";
+
+// Extract the embedded admin bundle once per process so AdminSpaServeApp can serve it from disk.
+if (ADMIN_SPA_FILES.length > 0 && !process.env.ADMIN_SPA_DIST_DIR) {
+  const out = join(tmpdir(), `<appName>-admin-spa-${process.pid}`);
+  for (const {path, file} of ADMIN_SPA_FILES) {
+    const dest = join(out, path);
+    mkdirSync(dirname(dest), {recursive: true});
+    writeFileSync(dest, new Uint8Array(await Bun.file(file).arrayBuffer()));
+  }
+  process.env.ADMIN_SPA_DIST_DIR = out;
+}
+```
+
+With the stub (dev), nothing is extracted and `AdminSpaServeApp` uses its package default. If the
+app later adds migrations, embed `migrations/` the same way and set `MIGRATIONS_DIR`.
+
+### 6. Build the binary
+
+Add to `backend/package.json`:
+
+```json
+"build:binary": "bun scripts/generateEmbeddedAssets.ts && bun build --compile --minify src/index.ts --outfile dist/<appName> && git checkout src/embeddedAdminSpa.generated.ts"
+```
+
+Cross-compile with `--target=bun-linux-x64` (or `bun-linux-arm64`, `bun-darwin-arm64`). Expect a
+binary over 100 MB: the Bun runtime plus about 120 admin assets (fonts, images, JS).
+
+### 7. Verify the binary on its own
+
+Copy the binary to an empty directory (or move `node_modules` aside) so nothing resolves from
+disk, then:
+
+```bash
+MONGO_URI=... BETTER_AUTH_SECRET=... PUBLIC_API_URL=http://localhost:4000 ./dist/<appName> &
+curl -sf localhost:4000/health
+curl -sf -o /dev/null -w '%{http_code}\n' localhost:4000/console              # 200
+curl -sf localhost:4000/console/app-config.json
+curl -sf -o /dev/null -w '%{http_code}\n' localhost:4000/console/_expo/static/js/web/<entry>.js  # 200
+curl -s -X POST localhost:4000/mcp -H 'content-type: application/json' \
+  -H "authorization: Bearer mcp_..." \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+Seed an admin, log in at `/console`, mint a service token with `POST /mcp/service-tokens`, run
+`tools/list` with it, and confirm a row appears in **MCP request log** after a `tools/call`. Save a screenshot of the MCP admin
+group to `/opt/cursor/artifacts/` when that directory exists.
+
+### 8. Expose it
+
+Never put `localhost:4000` on the internet by port-forwarding. Follow
+https://terreno-docs.netlify.app/how-to/expose-mcp-server-safely: a named Cloudflare Tunnel, Cloudflare Access on
+`/admin`, plus `/console` and `/api/auth` when every OAuth approver is in the Access policy
+(never `/mcp`, `/.well-known`, or `/oauth/*`), OAuth `issuer`
+equal to the tunnel hostname, rate limiting on with `trustProxy` set for the proxy in front.
+
+## Done when
+
+- `./dist/<appName>` starts with only Mongo and env vars, and the step 7 checks pass.
+- `/console` shows the MCP admin group, and a service token minted there lists tools.
+- With `MCP_OAUTH_ENABLED=true`, Claude.ai's custom connector completes the consent flow
+  against the public hostname.
+
+## Pitfalls
+
+- A quick tunnel (`trycloudflare.com`) hostname changes on every run. OAuth discovery and
+  registered clients break; use a named tunnel.
+- `dynamicClientRegistration` with an empty `allowedRedirectHosts` throws at startup on purpose.
+- Non-admin users can open `/console/oauth/consent` to approve a connection; the rest of the
+  console shows them the forbidden page. That is expected.
+- Run one binary per Mongo database.
+- The OAuth consent routes trust the Better Auth session cookie because `BetterAuthApp`
+  mounts its session middleware before `TerrenoApp` adds `/oauth/*`. Register `BetterAuthApp`
+  on the same `TerrenoApp`; do not mount it on a separate Express app.

package/skills/building-admin-interfaces/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: building-admin-interfaces
+description: >-
+  Build Terreno admin UIs with @terreno/admin-frontend and @terreno/admin-backend.
+  Use when adding or changing admin screens, AdminShell sidebar nav, AdminHome,
+  custom screens, AdminScreenRouter, AdminProvider widgets, admin-spa routes,
+  or operator tools. Covers where models vs custom screens vs platform tools go.
+  Not for product (non-admin) Expo screens — use building-terreno-apps.
+---
+# Building Admin Interfaces
+
+Use this skill when the work is an **admin** surface: `/admin/**`, `/console`,
+`AdminApp`, `AdminShellLayout`, model changelists, custom operator screens, or
+admin home widgets.
+
+**Architecture source (read first):**
+[How admin interfaces are shaped](../../../../docs/explanation/admin-interface.md)
+and [Build admin screens](../../../../docs/how-to/build-admin-screens.md).
+
+**Related skills:** `building-terreno-apps` (Expo/`@terreno/ui` habits),
+`terreno-ui` (components), `terreno-data-fetching` (windowed syncdb + RPC),
+`terreno-backend-api` (`modelRouter` + `admin:`), `verify-ui-changes`.
+
+## Tracer bullet
+
+1. Classify the need: model CRUD, home widget, custom screen, or dedicated workflow
+   route. Done when the choice matches the table in `docs/how-to/build-admin-screens.md`.
+2. Backend first: `modelRouter({admin})`, `AdminApp.customScreens`, plugin
+   `adminContribution()`, or `home.slots`. Done when `GET /admin/config` lists the
+   new model or screen for an admin user and omits it without `admin:access`.
+3. Frontend wiring: `AdminProvider` + `AdminShellLayout` with matching `apiBase` /
+   `routeBase`. Register `widgets.screens[name]` only for host-owned custom screens.
+   Done when the sidebar link opens the right component without a missing-widget
+   placeholder.
+4. Routes: keep `[model]/index.tsx` on `AdminScreenRouter`; `create.tsx` / `[id].tsx`
+   on `AdminModelForm`. Add extra Expo files only for extra URL segments. Done when
+   no per-model copy of the table exists.
+5. UI: `@terreno/ui` + `AdminScreenPage` for custom screens; `color="transparent"`
+   inside the shell. String-`_id` models with `adminBroadcast` use windowed
+   syncdb; ObjectId/API-only model CRUD uses `useAdminModelApi`; custom RPC uses
+   `useAdminRpc` + `useAdminRpcQuery`. All of it goes through the `AdminProvider`
+   fetch client. Done when there is no app-owned `fetch`/`axios` and no `api`
+   prop on admin components.
+6. Verify with `verify-ui-changes` on the example admin or admin-spa. Done when
+   home, sidebar, and the new flow are exercised as an admin user.
+
+## References
+
+```
+references/
+  screens-and-routes.md   File layout, AdminScreenRouter, dedicated routes
+  nav-and-shell.md        Sidebar sections, routeBase vs apiBase, mobile drawer
+  patterns-and-tools.md   Widgets, platform tools, RBAC, MCP, built-in IDs
+```
+
+## Hard guardrails
+
+- Do not hand-roll a DataTable per model. Use `AdminModelTable` / `AdminScreenRouter`.
+- Do not put a second sidebar inside a screen. `AdminShell` owns nav.
+- Do not pass an `api` prop to admin components (removed in Terreno 58).
+  `AdminProvider` (`credentials` for cookie SPAs, `apiOrigin` = `baseUrl` from
+  `@terreno/syncdb/config` + `getAuthHeaders` reading the app's
+  `authProvider.getToken()` for embedded apps) is the only auth binding.
+- Do not invent sidebar entries. Config (filtered by RBAC) is the nav source.
+- Do not use `router.back()` as the custom-screen back action; use `AdminScreenPage`.
+- Do not edit generated `store/apiSdk.ts` / `store/syncDbSdk.ts` by hand.
+
+## Decision tree
+
+```
+Admin work?
+  |-- CRUD for a model?
+  |   \-- modelRouter admin block; generic [model] routes
+  |
+  |-- Tile on Home?
+  |   \-- home.slots + widgets.home
+  |
+  |-- Operator page that is not a model?
+  |   \-- customScreens.name + widgets.screens[name]
+  |
+  |-- Extra URL segments or a workflow form cannot express?
+  |   \-- Dedicated Expo route; keep the generic table for search
+  |
+  \-- Done coding?
+      \-- verify-ui-changes
+```

package/skills/building-admin-interfaces/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Building Admin Interfaces"
+  short_description: "Build Terreno admin screens with AdminShell nav, AdminScreenRouter, custom screens, and admin-backend config"
+  default_prompt: "Use $building-admin-interfaces to add or change an admin screen, sidebar nav, or operator tool with @terreno/admin-frontend."

package/skills/building-admin-interfaces/references/nav-and-shell.md

@@ -0,0 +1,42 @@
+# Nav and shell
+
+Canonical shape: [How admin interfaces are shaped](../../../../../docs/explanation/admin-interface.md).
+
+## `apiBase` vs `routeBase`
+
+| Prop | Meaning | Embedded | admin-spa |
+| --- | --- | --- | --- |
+| `apiBase` | HTTP prefix for `/config` and model CRUD | `"/admin"` | `"/admin"` |
+| `routeBase` | Expo Router prefix for `router.push` | `"/admin"` | `""` |
+
+`AdminShell` navigates to `` `${routeBase}/${model.name}` ``. Using `apiBase` as
+`routeBase` on the SPA sends the browser to `/admin/User` instead of `/console/User`.
+
+## Sidebar sections (do not reorder in app code)
+
+1. Home → `{routeBase}/`
+2. Models, grouped by `admin.group` (empty group → **General**, sorted last)
+3. Screens from `customScreens`
+4. Platform, filtered by `platformTools`: Scripts (`/__scripts`), Roles, Version,
+   Audit Log, Feature Flags, Configuration
+
+Pass `configurationPath`, `rolesPath`, and `versionConfigPath` on
+`AdminShellLayout`. Audit log and Feature Flags are still models; the shell
+relocates those two into Platform.
+
+## Chrome
+
+- Default sidebar: `sidebarVariant="colorful"` (teal rail). Optional `"clinical"`.
+- Main column: theme canvas. Nested `Page` / `AdminScreenPage`:
+  `color="transparent"`, `padding={0}` unless the screen supplies its own pad.
+- Breadcrumbs and `headerActions` enable the white top bar. Home typically uses
+  `breadcrumbs={[{label: "Admin"}]}`.
+- Below the desktop floor (1024pt, `isSupportedDesktopWidth`): hamburger + drawer. Do not hide the shell on mobile.
+- Custom-screen back: `AdminScreenPage` → `router.push(backHref)`. Never
+  `router.back()` as the default.
+
+## Auth gate
+
+`admin:access` opens the page (`GET /admin/config` 403 without it). Hosts call
+`canOpenAdminPage({admin, permissions})` from `@terreno/syncdb/app` and hide product
+nav to admin with the same check.