@terreno/mcp 57.17.0 → 57.19.2

package/src/docs/versioned/next/implementationPlans/circleci-pr-speed-loop.md

@@ -0,0 +1,293 @@
+# Implementation Plan: CircleCI PR Speed Loop
+
+**Status:** In progress — iteration 0 (instrumentation) in review; iteration 1 picks the first lever
+**Owner:** Josh
+**Goal:** cut CircleCI wall-clock time for an **average PR** by **40% (≤ 5.7 min)**
+or to **under 4 min**, whichever comes first, without weakening any gate.
+**Driver:** run as a long-lived loop. `/terreno-scan:loop` with this document as
+the charter fits. Each iteration ships one PR-sized change through Pick → Roast →
+Brew → Taste.
+
+## Metric
+
+**PR CI wall clock:** from the first `ci/circleci:` status on a PR's head commit
+to the last terminal status of a test or build job. Excluded from the end time:
+`approve`, `architectural-pr-review`, `dco`, `deploy-*` previews, and
+`serial-*` deploy-group statuses. Those are review bots and previews, not tests.
+
+**Average PR:** a merged PR that touches **≤ 3 top-level directories**, not
+counting `docs/`, `website/`, or dot-directories (so `changelog/` counts).
+44 of the last 60 merged PRs qualify, and the median PR touches 2. PRs touching more than 3
+directories are tracked but do not count toward the goal.
+
+**Reported value:** the median over the last 20 qualifying merged PRs, plus the
+median of the benchmark set (below) for each experiment.
+
+### Baseline (last 60 merged PRs, measured 2026-10-25)
+
+| | Median | p25 | p75 |
+|---|---|---|---|
+| Average PRs (≤ 3 directories, n = 44) | **9.5 min** | — | — |
+| All PRs (n = 60) | 10.3 min | 5.9 min | 12.1 min |
+
+**Target:** median ≤ **5.7 min** (40% faster). If it gets there, keep going
+toward **≤ 4.0 min** only while iterations still pay off (see stop rules).
+
+Job that finished last on average PRs:
+
+| Job | PRs where it was last | Median duration | Median start after pipeline start |
+|---|---|---|---|
+| `e2e-app` | 13 / 44 | 4.0 min | 6.3 min (waits on `e2e-prepare`, 5.4 min) |
+| `api-ci` | 10 / 44 | 10.8 min | 1.0 min |
+| `repo-policies` | 5 / 44 | — | — |
+| `mcp-server-docker` | 4 / 44 | — | — |
+| `maestro-e2e` | 3 / 44 | 8.9 min | 0.9 min |
+| `new-file-coverage` | 3 / 44 | 3.5 min | 0.5 min |
+
+Other long jobs that can become last once these shrink:
+
+| Job | Median duration |
+|---|---|
+| `example-backend-docker` | 7.6 min |
+| `admin-spa-integration` | 6.0 min |
+| `ai-ci` | 5.9 min |
+| `admin-spa-ci` | 4.9 min |
+| `example-backend-ci` | 4.3 min |
+
+The setup workflow (path filtering plus continuation) costs about 0.6–1.0 min
+before any job starts. The 4-minute target needs that cut too.
+
+## Guardrails
+
+The loop may change anything in CI: config, resource classes, caching,
+parallelism, job graph, test runners, and test code. It may **not**:
+
+1. Delete, skip, or `.skip` a test. The one exception is a selection mechanism
+   (TIA, path filtering, the e2e affected gate) whose shadow run proves zero
+   misses over at least 2 weeks.
+2. Lower a coverage threshold, or move a blocking gate to post-merge. That
+   covers the 95% package gate, the 90% new-file gate, Knip zero findings, the
+   dependency-cruiser baseline, lint, and typecheck.
+3. Mark a flaky test as allowed-to-fail. Fix it or quarantine it with a
+   tracking issue, and count the quarantine as a regression for this goal.
+4. Make `master` or release pipelines less safe. `master` still runs
+   everything.
+5. Raise CircleCI spend more than **25%** per average PR without Josh's
+   approval. Report credits per average PR in every iteration.
+
+## The loop
+
+Each iteration is one PR. Keep going until a stop rule fires.
+
+1. **Measure.** Run `bun run ci:wall-clock --limit 20` for the rolling median
+   and the last-job histogram. Pull per-job step timings from
+   the CircleCI API (`CIRCLECI_TOKEN`; slug in `docs/how-to/circleci.md`) for
+   the top 2 critical-path jobs.
+2. **Pick the lever.** Take the job that is most often last. Choose the
+   highest-expected-gain lever for it from the backlog, or a new one found in
+   step 1. Write the hypothesis in the ledger, e.g. "caching the `bun install`
+   store cuts `api-ci` by 50 s".
+3. **Build it** on `ci-speed/<n>-<slug>` with Pick → Roast. Config changes
+   need `scripts/check-circleci-parity` and `circleci config validate` to pass.
+4. **Benchmark.** Run the [benchmark set](#benchmark-set) against the branch
+   and against `master` in the same hour, 2 runs each. The result is the
+   median of each case's median.
+5. **Decide.**
+   - **Keep:** benchmark median improves by **≥ 5%** (≈ 30 s) with every
+     guardrail intact. Brew → Taste → merge.
+   - **Drop:** under 5%, or any guardrail broken. Record why in the ledger and
+     close the PR.
+6. **Re-measure** after merge on the next 20 qualifying real PRs. Update the
+   ledger and the baseline table.
+7. **Loop.**
+
+### Stop rules
+
+- **Done:** the rolling real-PR median is ≤ 5.7 min (or ≤ 4.0 min) for 20
+  qualifying PRs in a row. Post a final report.
+- **Stalled:** 3 iterations in a row each gain under 5%. Escalate to Josh with
+  the current critical path, the levers tried, and the next options with their
+  cost (e.g. bigger resource classes, a paid feature, dropping a job from PRs
+  with proof).
+- **Blocked:** a lever needs a guardrail exception or a spend increase over
+  25%. Ask Josh.
+
+### Benchmark set
+
+Five recent average PRs whose code still reverts cleanly on `master`. They
+cover the jobs that most often finish last (`api-ci` and the e2e chain). Refresh
+them with `bun run ci:bench --suggest-cases` every 10 iterations, or sooner when
+a case replays as `invalid`.
+
+| Case | Shape | PR |
+|---|---|---|
+| `api-only` | `api` feature (plus changelog and docs) | #1491 |
+| `api-syncdb` | `api` plus `syncdb` | #1555 |
+| `ui-only` | `ui` component fix | #1567 |
+| `admin-example` | `admin-frontend` plus `example-frontend` | #1540 |
+| `small-package` | `create-terreno-app` | #1599 |
+
+Mechanics: `bun run ci:bench --branch <branch> --label <iteration>` (see
+[benchmark a CI change](../how-to/circleci.md#benchmark-a-ci-change)). For each
+case it opens two draft PRs labelled `ci-bench`, waits for CircleCI to settle,
+records the metric, and closes both PRs:
+
+- **Control:** `master` with the case's code hunks reverted.
+- **Treatment:** the branch under test with the case's code hunks reverted.
+
+The case list lives in `scripts/ci/bench/cases.ts`.
+
+### Ledger
+
+Append one row per iteration. Never edit past rows.
+
+| # | Date | Lever | Target job | Bench before → after | Real-PR median after | Credits/avg PR | Kept? | PR |
+|---|---|---|---|---|---|---|---|---|
+| 0 | 2026-10-25 | Baseline | — | — | 9.5 min | TBD | — | — |
+| 0 | 2026-10-26 | Instrumentation (`ci:wall-clock`, `ci:bench`) | — | `api-only` on master: 11.6 min (1 run, last job `api-ci`) | 9.5 min | TBD (needs CircleCI token) | Yes | this PR |
+
+## Lever backlog
+
+The order is a starting point. Re-rank every iteration from fresh step
+timings.
+
+### Iteration 0 — Instrumentation (½ day, required first)
+
+- Add `bun run ci:wall-clock` (`scripts/ci/ciWallClock/`), with tests, from
+  the measurement used for the baseline above.
+- Add `bun run ci:bench` (`scripts/ci/bench/`).
+- Pull step-level timings for `api-ci`, `e2e-prepare`, `e2e-app`,
+  `maestro-e2e`, and `example-backend-docker`. Record how much of each is
+  checkout, `bun install`, dependency compile, lint, typecheck, and tests.
+
+### e2e chain (`e2e-prepare` 5.4 min → `e2e-app` 4.0 min)
+
+- **Cache the Expo web export**, keyed on a hash of the inputs it reads
+  (`example-frontend`, the workspace packages it bundles, `bun.lock`). On a
+  hit, `e2e-prepare` skips `bun expo export`. The e2e affected gate already
+  computes the reachable input set (`scripts/ci/e2eAffected`), so reuse it for
+  the cache key.
+- Build `e2e-prepare` in parallel with lint and compile, not after them, and
+  start shards as soon as their artifact exists.
+- Rebalance or split `e2e-app`, the slowest shard, using Playwright timing
+  data. Static splitting is free with `circleci testsuite`.
+
+### `api-ci` (10.8 min)
+
+- Split lint, typecheck, and tests into parallel jobs. The test step alone is
+  about 4 min locally.
+- Static test splitting across `parallelism: 2–3` nodes. This needs the
+  coverage-splice work below, so each node's LCOV can combine into one exact
+  report.
+- Make every test file pass alone. 10 `api` files fail today, mostly 5 s
+  `beforeAll` timeouts. Splitting and TIA both need this.
+- **Test impact analysis**, piloted as described in
+  [Appendix A](#appendix-a--smarter-testing-findings). The simulation selects
+  about 46% of `api` test time on a typical PR.
+
+### Every job
+
+- Cache the `bun install` store. All jobs install without a cache today.
+- Cache workspace `dist/` output from `compile_packages`, keyed by each
+  package's source hash.
+- Right-size resource classes for jobs on the critical path. `large` costs
+  2× `medium` credits per minute but can halve CPU-bound steps. Check against
+  guardrail 5.
+- Shorten the setup workflow: path filtering plus continuation takes about
+  0.6–1.0 min.
+
+### `maestro-e2e` (8.9 min), `example-backend-docker` (7.6 min), `admin-spa-integration` (6.0 min)
+
+- Reuse the Expo export cache from the e2e chain in `maestro-e2e` and
+  `admin-spa-integration`.
+- Tighten path filters. Check these run only when their inputs change.
+- `example-backend-docker`: make better use of layer cache through BuildKit
+  `--cache-from` on a registry image. Docker Layer Caching costs 200 credits
+  per job, so compare costs first.
+
+## Appendix A — Smarter Testing findings
+
+Source docs:
+[get started](https://circleci.com/docs/guides/test/getting-started-with-smarter-testing/),
+[test impact analysis](https://circleci.com/docs/guides/test/set-up-test-impact-analysis/),
+[`test-suites.yml` reference](https://circleci.com/docs/reference/testsuite-configuration-reference/),
+[overview and credit charge](https://circleci.com/docs/guides/test/smarter-testing-overview/).
+
+**How it works.** `.circleci/test-suites.yml` defines suites with `discover`
+(lists test atoms, here files) and `run` (gets `<< test.atoms >>` and writes
+`<< outputs.junit >>`). An optional `analysis` command is the run command with
+coverage, writing `<< outputs.lcov >>` one atom at a time. The job step becomes
+`circleci testsuite run "<suite>"`, run from the package root.
+
+- **Analysis** runs on `master` and records which files each atom covers.
+- **Selection** runs on PRs. It runs new atoms, atoms that failed last time,
+  and atoms whose covered files changed. `full-test-run-paths` and
+  `test-selection-rules` cover what coverage cannot see.
+- **Free:** `testsuite run`, static splitting, rerun-only-failed, and test
+  uploads.
+- **Charged:** TIA, dynamic splitting, dynamic parallelism, and auto-rerun, at
+  3,000 credits per 100k atoms above the plan allowance. Estimated $1–3 a month
+  for us.
+
+**Bun compatibility (verified locally).**
+`bun test --reporter=junit --reporter-outfile=…` writes JUnit, and
+`bun test --coverage --coverage-reporter=lcov --coverage-dir=<dir> <atom>`
+writes a usable LCOV. Bun writes to a directory, so `analysis` needs a wrapper
+that moves `lcov.info` to `<< outputs.lcov >>`.
+
+**Selection simulation.** I ran each `api` and `ui` test file alone with
+coverage, then replayed the last 60 PR merges per package (version bumps
+excluded):
+
+| | `api` | `ui` |
+|---|---|---|
+| Atoms | 149 | 201 |
+| Full suite, local | 3 m 49 s | 1 m 14 s |
+| Analysis, one atom at a time | 17 min serial | 55 s at 4-way |
+| Atoms failing when run alone | 10 | 1 |
+| PRs forced to a full run | 19 / 60 | 14 / 60 |
+| Mean / median share of test time selected | 46% / 39% | 43% / 43% |
+
+Hub files limit the savings. In `api`, `logger.ts` and `requestContext.ts`
+are covered by 149/149 atoms and `errors.ts` by 131. Coverage also cannot see
+across packages: every `bunfig.toml` ignores `../**` and dependencies resolve
+to `dist/`. Each downstream suite therefore needs `full-test-run-paths` for
+its upstream packages. Whether paths outside the CLI's working directory are
+allowed must be checked with `circleci testsuite doctor`.
+
+**Coverage splicing (keeps gates blocking and exact).** The PR job builds a
+whole-package LCOV, then runs the unchanged 95% gate, the 90% new-file gate,
+and the Codecov upload on it.
+
+- **Changed files** (vs merge base) come from the PR's selected run. All atoms
+  covering them run in one `bun test` process, so those files are exact.
+- **Unchanged files** come from `master`'s full-run LCOV at the merge base,
+  using the per-file maximum with the PR run.
+- **Wiring:** `master` saves `coverage/lcov.info` via `save_cache`, keyed
+  `cov-base-<pkg>-{{ checksum "base-sha.txt" }}`. The PR job writes the merge
+  base to `base-sha.txt` and restores that key.
+- **Fallback:** if there is no baseline, or a full-run path changed, run the
+  full coverage suite as today.
+
+Why per-file and not per-atom: Bun reports a different set of instrumented
+lines per process, and writes only `FNF`/`FNH` totals, not which functions
+ran. Merging the 149 per-atom `api` reports gave 95.24% functions vs 98.95%
+real.
+
+Validated on `ui`: baseline at `7fc9843c^`, PR at HEAD, 9 changed files,
+16/201 atoms selected (7.9 s vs 74 s). The spliced report matched the full run
+exactly: 211/211 files, lines 99.25% = 99.25%, functions 98.61% = 98.61%.
+
+Known gap: an unchanged file can lose coverage when a changed file stops
+calling it. The `master` full run catches this right after merge and must
+comment on the PR.
+
+**TIA pilot steps (when the loop picks this lever).**
+1. Add the suite with `test-impact-analysis: true`,
+   `test-analysis-duration: 20`, and `full-test-run-paths`. Run analysis as a
+   non-blocking `master` job.
+2. Shadow it on PRs for 2 weeks. `list-tests` records what would be selected,
+   while the full suite still runs. Compare spliced LCOV against full LCOV,
+   file by file.
+3. Make it blocking only with zero selection misses, zero splice mismatches,
+   and a median test-step saving of at least 40%.

package/src/docs/versioned/next/implementationPlans/deploy-to-vercel.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Deploy to Vercel + `deploy-vercel` Skill
 
-**Status:** Approved — open Vercel spike TODOs; other decisions recorded (2026-07-29)
+**Status:** Implemented — V1/V2/V3 decided 2026-10-11; Vercel runs in parallel with Cloud Run + Netlify for an evaluation period
 **Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1012
 **Priority:** High
 **Effort:** Big batch
@@ -28,23 +28,32 @@ Give Terreno the fastest possible "my app is on the internet" path, and a skill
 
 | # | Question | Decision |
 |---|----------|----------|
-| V1 | Backend host | **Open — spike required.** Candidate: all-in-one on Vercel (web + backend + Blob storage). Fallback: Railway/Render/Fly + Vercel static web (see [`deployment-foundation`](deployment-foundation.md)). **Do not publish a final answer until TODOs below are closed.** |
-| V2 | Document `server` output? | **Open — depends on V1 spike.** Default if documented: advanced section, Expo SDK ≥ 55, SSE buffering caveat |
-| V3 | Commit `vercel.json`? | **Open — depends on V1 spike.** Candidate: wired to real deployment in `example-frontend` and `example-backend` |
+| V1 | Backend host | **Decided 2026-10-11 (human): run all-in-one on Vercel in parallel with the existing split deploy.** `terreno-backend` (Vercel Functions, Fluid compute) serves `@terreno/api` with Socket.IO; `terreno-frontend` and `terreno-demo` are static exports. Both topologies are documented; split stays the conservative default for apps that need background workers or GCS uploads. Uploads (GCS) and the jobs worker are disabled on Vercel during the evaluation. |
+| V2 | Document `server` output? | **Decided: A** — advanced section only (repo is on Expo SDK 57); both apps keep `static` output; SSE buffering caveat documented. |
+| V3 | Commit `vercel.json`? | **Decided: A** — committed in `example-backend`, `example-frontend`, and `demo`, wired to real projects in the `terrenolabs` Vercel team (owner: Josh) and deployed by CircleCI (`vercel-deploy` job, `terreno-vercel` context). |
 | V4 | Preview deployments | **A** — include CORS + Better Auth `trustedOrigins` for preview URLs |
 | V5 | Disambiguate Vercel AI SDK vs hosting | **A** — consistent phrasing: "the Vercel AI SDK" vs "Vercel (hosting)" |
 
+## Spike outcome (2026-10-11)
+
+Answered by deploying the examples, not a scratch spike. See `docs/how-to/deploy-to-vercel.md` and `docs/how-to/vercel-function-websockets.md`.
+
+- `@terreno/api` runs on Vercel Functions (Node 24, Fluid compute) by exporting an `http.Server` that `TerrenoApp` attaches to (`example-backend/src/app.ts`, `start(false, server)`). WebSocket upgrades work; change-stream watchers run per instance.
+- The backend must be fully bundled with Bun (`build:vercel`): Vercel's launcher refuses `require()` of ESM, Bun inlines `NODE_ENV`, and the Express preset needs an `import "express"` marker.
+- Clients must use WebSocket-only Socket.IO on Vercel; `@terreno/rtk` `useSocketConnection({transports})` and `@terreno/syncdb` `createSyncDb({socketTransports})` were added.
+- Preview origins are matched with `CORS_ORIGINS` wildcards (`toCorsOrigin`), and Better Auth gets the raw patterns.
+
 ## Open TODOs (pre-implementation spike)
 
 Complete these before Phase 1 of the how-to guide ships:
 
-- [ ] **V1-todo:** Can `@terreno/api` run on Vercel with Socket.io sessions and MongoDB change streams? Use [Vercel Functions WebSockets (Public Beta)](https://vercel.com/docs/functions/websockets) as the source of truth. Document runtime limits, Fluid compute, cold starts, max-duration disconnects, and that a connection is pinned to one function instance (not session affinity across reconnects).
-- [ ] **V1-todo:** Write operator docs for websocket usage on Vercel Functions (see **Vercel Functions WebSockets** below). Link the beta page; do not copy it. Re-verify every config key and limitation against that page before the how-to ships.
-- [ ] **V1-todo:** Can `@terreno/ai` SSE streaming work through `expo-server/adapter/vercel` without unacceptable buffering?
-- [ ] **V1-todo:** Where do user file uploads land on an all-in-one Vercel deploy (Blob, external GCS, or other)?
-- [ ] **V1-todo:** Compare all-in-one Vercel vs split (Vercel web + long-running backend) on cost, ops complexity, and preview-deployment ergonomics.
-- [ ] **V2-todo:** If `server` output is documented, confirm Expo SDK ≥ 55+ requirements and list which Terreno features break under static/server export.
-- [ ] **V3-todo:** If committing `vercel.json`, confirm CI/deploy wiring for `example-frontend` and `example-backend` and who owns the Vercel project.
+- [x] **V1-todo:** Can `@terreno/api` run on Vercel with Socket.io sessions and MongoDB change streams? Use [Vercel Functions WebSockets (Public Beta)](https://vercel.com/docs/functions/websockets) as the source of truth. Document runtime limits, Fluid compute, cold starts, max-duration disconnects, and that a connection is pinned to one function instance (not session affinity across reconnects).
+- [x] **V1-todo:** Write operator docs for websocket usage on Vercel Functions (see **Vercel Functions WebSockets** below). Link the beta page; do not copy it. Re-verify every config key and limitation against that page before the how-to ships.
+- [x] **V1-todo:** (Deferred — Terreno does not route AI through Expo server output; the guide tells operators to keep `/gpt/prompt` on the `@terreno/api` backend.) Can `@terreno/ai` SSE streaming work through `expo-server/adapter/vercel` without unacceptable buffering?
+- [x] **V1-todo:** (Deferred, owner Josh — GCS uploads are off on Vercel during the evaluation; Blob vs external GCS is future work.) Where do user file uploads land on an all-in-one Vercel deploy (Blob, external GCS, or other)?
+- [x] **V1-todo:** Compare all-in-one Vercel vs split (Vercel web + long-running backend) on cost, ops complexity, and preview-deployment ergonomics.
+- [x] **V2-todo:** If `server` output is documented, confirm Expo SDK ≥ 55+ requirements and list which Terreno features break under static/server export.
+- [x] **V3-todo:** If committing `vercel.json`, confirm CI/deploy wiring for `example-frontend` and `example-backend` and who owns the Vercel project.
 
 ## Architecture
 
@@ -185,7 +194,7 @@ None.
 
 **Create**
 
-- `docs/how-to/deploy-to-vercel.md` (blocked on Phase 0 spike)
+- `docs/how-to/deploy-to-vercel.md` (named for both web and backend; the task list's `deploy-web-to-vercel.md`)
 - `docs/how-to/vercel-function-websockets.md` (Vercel Functions WebSockets beta; may ship during Phase 0)
 - `.rulesync/skills/deploy-vercel/SKILL.md`
 

package/src/docs/versioned/next/implementationPlans/durable-agent-harness.md

@@ -36,7 +36,7 @@ job is one opaque handler with no checkpoints. The harness fills that gap.
 
 | Question | Decision |
 |----------|----------|
-| Build our own harness or adopt pi-durable? | Own harness on Mongo + Vercel `ai` SDK, copying Pi's concepts (tasks, checkpoints, replay-safe tools, hooks, memos, documents, compaction, forks). |
+| Build our own harness or adopt pi-durable? | Own harness on Mongo + the Vercel AI SDK (`ai`), copying Pi's concepts (tasks, checkpoints, replay-safe tools, hooks, memos, documents, compaction, forks). |
 | Where should the harness live? | Inside `@terreno/ai`, as subpath `@terreno/ai/harness`. |
 | How should the `@terreno/jobs` dependency be wired? | Optional peer. Jobs integration is optional; a single process can own execution. |
 | Who executes a run? | Pluggable `Runner`: `InProcessRunner` (single owner, default) and `JobsRunner` (leased, multi-instance). |

package/src/docs/versioned/next/implementationPlans/infra-mcp.md

@@ -29,9 +29,11 @@ A deployable, self-contained MCP server that puts privileged infrastructure tool
 | Write safety | **Write tools require per-call confirmation (MCP elicitation).** A config option can disable confirmation per integration or globally, but it only takes effect for users holding `infra:writeUnconfirmed` — everyone else is still prompted |
 | Phase 1 scope | **Read-only:** GCP observability (logs/metrics/errors), Sentry, MongoDB |
 | GCP credentials | **Cloud Run default runtime service account only (ADC).** No injected SA key env vars anywhere; the `GCP_SA_*` pattern for cloud agents is retired. IAM on the runtime SA is the outer bound; the MCP's RBAC is the per-user gate |
-| Other credentials | Static tokens (Sentry auth token, Mongo connection strings, later `EXPO_TOKEN`/Vercel token) from Secret Manager/env |
+| Other credentials | Static tokens (Sentry auth token, Mongo connection strings, later `EXPO_TOKEN`) from Secret Manager/env |
+| Vercel credentials | **One team-scoped token per Vercel team**, keyed by team slug; each project resolves to its team by asking which token can see it (cached). Project-scoped tokens are not enough: they list deployments and read build logs but get 403 on runtime logs (`POST /v1/observability/events`, measured 2026-10-25; the CLI says "You don't have access to runtime logs for this project"), and Vercel has no scope between project and team |
+| Resource scoping | An integration's reads can be narrowed per caller to named vendor resources (e.g. a machine user may read only its own Vercel projects) with an RBAC `scopes` entry (`vercel.read`). The tool resolves the resource first, then calls `access.can({permissions: {vercel: ["read"]}, context: {projectId}})`. Unknown and forbidden resources get the same refusal, so a caller can't probe names |
 | User store & login | Mongo users via `@terreno/api` (`baseUserPlugin` + `rbacUserPlugin`); MCP clients authenticate via OAuth 2.1 using **`@better-auth/oauth-provider` + `@better-auth/mcp`** (already aligned with the 2026-07-28 authorization spec: CIMD, RFC 9728, `requireMcpAuth`) |
-| Non-human callers | Service tokens (Better Auth `apiKey` plugin if compatible, else a `ServiceToken` model) mapped to machine users with RBAC roles — this is how cloud agents call the server |
+| Non-human callers | Service tokens (Better Auth `apiKey` plugin if compatible, else a `ServiceToken` model) mapped to machine users with RBAC roles — this is how cloud agents call the server. An orchestrator that starts agent sandboxes mints **one machine user and one token per sandbox** at create (role scoped to that sandbox's repo/resources) and revokes them at teardown. It's per sandbox, not per repo, because `@terreno/api` caps a user at ten live service tokens |
 | Packaging | New workspace package `infra-mcp/` publishing `@terreno/infra-mcp`; config-driven integration registry; deployed via a clone of the existing `mcp_service` terraform module |
 
 ## Architecture
@@ -44,7 +46,9 @@ POST /mcp  — SDK v2 createMcpHandler (2026-07-28 + legacy stateless)
   |
   1. Auth: Better Auth verifies token -> User (+ roles via rbacUserPlugin)
   2. Authz: access.can({[integration]: [tier]}) using Mcp-Name header ->
-     integration/tool lookup; tools/list is filtered to the caller's grants
+     integration/tool lookup; tools/list is filtered to the caller's grants;
+     a tool then re-checks with the resource it resolved ({context: {projectId}})
+     against the integration's RBAC scope
   3. Write tools: elicitation confirmation (unless override + infra:writeUnconfirmed)
   4. Dispatch: IntegrationAdapter (native handler | proxied MCP client)
   5. Audit: InfraAuditLog record for every tools/call
@@ -101,6 +105,19 @@ export const infraStatements = {
 - `read`/`write` are in the RBAC module's `READ_ACTIONS` semantics, so the shipped `auditor` role (read-only everywhere) works unmodified — that is the "log digging" role for free.
 - Default roles seeded on top of the RBAC defaults: `infra-readonly` (every integration `read`), `infra-operator` (`read` + `write`, still confirmed per call), `superadmin` from RBAC covers everything including `infra:writeUnconfirmed`.
 - Per-integration grants ("Sentry read only, no GCP") are just roles with narrower permission sets — no extra machinery.
+- Per-resource grants ("this agent's Vercel projects only") are RBAC `scopes`, passed to `createAccess`:
+
+  ```typescript
+  scopes: {
+    "vercel.read": {
+      check: async ({user, context}) =>
+        context?.projectId === undefined || isOperator(user) ||
+        (await projectsFor(user)).includes(context.projectId as string),
+    },
+  },
+  ```
+
+  `projectsFor` reads the machine user's allow-list (in our deployment, the project ids in the agent repo's environment). With no `projectId` in the context the call is a tier check only.
 
 ### Write confirmation flow
 
@@ -120,6 +137,8 @@ export default defineInfraMcp({
     gcp: {enabled: true, projectId: env("GCP_PROJECT")},           // ADC — no key
     sentry: {enabled: true, authToken: secret("SENTRY_MCP_TOKEN"), org: "flourish"},
     mongo: {enabled: true, readUri: secret("MONGO_READ_URI"), writeUri: secret("MONGO_WRITE_URI")},
+    // Phase 3. One team token per team, keyed by slug; projects map to teams by lookup.
+    vercel: {enabled: true, teams: {nangio: secret("VERCEL_TEAM_NANGIO"), terrenolabs: secret("VERCEL_TEAM_TERRENOLABS")}},
   },
   confirmWrites: true, // global default; per-integration override allowed
 });
@@ -216,7 +235,12 @@ No new frontend package. Admin surfaces reuse `@terreno/admin-backend` + `@terre
 
 - `ProxiedAdapter` (MCP client, stdio + HTTP transports, allow-list with mandatory tier annotations, name prefixing).
 - First proxied integration: `@sentry/mcp-server` (stdio, static token) or `observability-mcp` — pick one as the reference implementation and keep the native tools as fallback.
-- Native Expo/EAS tools (`EXPO_TOKEN`: builds, updates, submissions status) and Vercel tools (API token: deployments, logs).
+- Native Expo/EAS tools (`EXPO_TOKEN`: builds, updates, submissions status).
+- Native Vercel tools (team tokens, see Decisions): `vercel_list_projects`, `vercel_list_deployments`, `vercel_runtime_logs`.
+  - Runtime logs use `POST /v1/observability/events?teamId=<team>` with `event: "vercel.log"`, `scope: {ownerId, projectIds: [<project>]}`, a `timeRange`, `order: "desc"`, `limit` and an optional `cursor` (from `pagination.nextCursor`). This is the query `vercel logs` makes as of CLI 65.
+  - Optional filters (deployment, level, a free-form Vercel filter on `level`/`source`/`requestPath`/…) are ANDed into `filter`. The project goes in `scope`, never in the filter, so a filter can't widen the query (measured: a filter naming another project returns nothing).
+  - The older `GET /v1/projects/<p>/deployments/<d>/runtime-logs` stream isn't usable: it sent no headers within 60 s even with an account token.
+- Dogfooded first in our agent-session manager (hive) on `@terreno/api`'s MCP server, using the adapter interface above, with per-sandbox machine users and the `vercel.read` scope. It moves into this package when the package exists.
 - **Deliverable:** adding a vendor MCP is config + annotations, not code.
 
 ### Phase 4 — OSS packaging

package/src/docs/versioned/next/implementationPlans/job-queues.md

@@ -144,7 +144,7 @@ picks it up. Cloud runners persist then create a platform task whose HTTP body
 is `{jobId}` (not the payload). Execute loads the Mongo row, claims if needed,
 runs the handler.
 
-GCP and Vercel SDKs are **optional peers** on subpath exports
+GCP and Vercel Queues SDKs are **optional peers** on subpath exports
 (`@terreno/jobs/runners/gcpCloudTasks`, `@terreno/jobs/runners/vercelQueues`).
 Core `@terreno/jobs` has zero cloud SDKs. Tests inject fakes.
 

package/src/docs/versioned/next/implementationPlans/model-router-mcp.md

@@ -20,7 +20,7 @@ This makes every Terreno app instantly AI-native: any model becomes callable by
 - Auth-agnostic: works with both JWT and Better Auth
 - Tool naming: `{prefix}_list`, `{prefix}_read`, `{prefix}_create`, `{prefix}_update`, `{prefix}_delete`
 - Populate is an option on the read tool, not a separate tool
-- Also exports `getMCPTools()` from `@terreno/ai` returning Vercel `ai` SDK `CoreTool` objects for direct in-process use
+- Also exports `getMCPTools()` from `@terreno/ai` returning Vercel AI SDK (`ai`) `CoreTool` objects for direct in-process use
 - Custom tools via `registerMCPTool` (example: `users_todo_statuses`)
 
 **Related work:** The `ai-multimodal-tools-mcp` branch has `MCPService` (MCP client) and `AIService` in `@terreno/ai` — that's the consumer of what this plan builds.
@@ -116,7 +116,7 @@ Generated from model name, field names/types, and `queryFields`. Example:
 
 ### CoreTool Export
 
-`getMCPTools()` exported from `@terreno/ai` returns all registered MCP tools as `Record<string, CoreTool>` for direct use with the Vercel `ai` SDK's `streamText()` / `generateText()`.
+`getMCPTools()` exported from `@terreno/ai` returns all registered MCP tools as `Record<string, CoreTool>` for direct use with the Vercel AI SDK's (`ai`) `streamText()` / `generateText()`.
 
 ## Notifications
 

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

@@ -2,6 +2,8 @@
 
 AI service layer for Terreno backends: provider-agnostic chat via the Vercel AI SDK, request logging, GPT history, projects, file uploads, MCP tools, and optional Langfuse integration.
 
+> `@terreno/ai` is provider-agnostic via the Vercel AI SDK (the `ai` package and its `@ai-sdk/*` providers). That is a model library, unrelated to Vercel hosting; on this page "Vercel" means the AI SDK unless it says hosting. To host on Vercel, see [Deploy to Vercel](../how-to/deploy-to-vercel.md).
+
 ## Table of Contents
 
 - [Install](#install)
@@ -165,7 +167,7 @@ All generation methods log to `AIRequest` via private `logRequest()`. Logging fa
 
 - Default to `TemperaturePresets.DETERMINISTIC` when `temperature` is omitted.
 - Use `JSON_VALUE_SYSTEM_PROMPT` when `systemPrompt` is omitted.
-- Run model text through `normalizeLlmJsonTextForStructuredOutput` before Vercel `Output.*` parsing (strips fences, preamble, balanced JSON slice, trailing commas, smart-quote repair).
+- Run model text through `normalizeLlmJsonTextForStructuredOutput` before the Vercel AI SDK's `Output.*` parsing (strips fences, preamble, balanced JSON slice, trailing commas, smart-quote repair).
 - On failure: `logger.error` records prompt, system prompt, raw model text, and error details; `AIRequest` stores `response` (raw text or sentinel), `error`, and `metadata` (`system`, `finishReason`, `errorStack`, `rawModelTextCaptured`).
 
 Standalone helpers:
@@ -735,7 +737,7 @@ Subpath imports for tree-shaking: `@terreno/ai/langfuseClient`, `@terreno/ai/lan
 ## Subpath exports
 
 Import these instead of `dist/` paths. Deep `dist/` imports break when a bundler (such as
-Vercel's) inlines them and their bare `@terreno/api` imports no longer resolve. Each
+Vercel hosting's build) inlines them and their bare `@terreno/api` imports no longer resolve. Each
 subpath shares module instances with `@terreno/ai/harness`.
 
 | Subpath | Exports |

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

@@ -68,12 +68,16 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 | `APP_ENV` | example-backend | ❌ | `development` | No | server |
 | `BACKEND_URL` | scripts, deploy | ❌ | — | No | server |
 | `FRONTEND_URL` | example-backend CORS and `authOptions.publicAppUrl` | ❌ | `http://localhost:8082` | No | server |
+| `CORS_ORIGINS` | example-backend (`utils/betterAuthConfig.ts`) | ✅ for deployed web origins | localhost:8082 origins only | No | server |
+| `CROSS_DOMAIN_AUTH_COOKIES` | example-backend Better Auth config | ❌ | `false` | 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 |
 
+`CORS_ORIGINS` is comma-separated. An entry may contain `*` (for example `https://*.preview.example.com`); use it only on a domain you control, never on a shared namespace like `vercel.app`. For `corsOrigin`, `*` becomes a `RegExp` that matches letters, digits, and hyphens but never a dot. Better Auth `trustedOrigins` receives the raw pattern and applies its own, broader wildcard matching. Never use `corsOrigin: true` in production; see [Deploy to Vercel](../how-to/deploy-to-vercel.md#cors). Set `CROSS_DOMAIN_AUTH_COOKIES=true` when the web app and API are on different sites.
+
 ## Client / build-time
 
 | Variable | Read by | Required | Default | Secret | Scope |
@@ -93,6 +97,7 @@ Configured in `expo.extra` and read via `expo-constants`:
 | `DEV_API_PORT` | `@terreno/rtk` | Override dev API port (mirrors `EXPO_PUBLIC_DEV_API_PORT`) |
 | `AUTH_DEBUG` | `@terreno/rtk` | `"true"` enables auth debug logs |
 | `WEBSOCKETS_DEBUG` | `@terreno/rtk` | `"true"` enables socket debug logs |
+| `SOCKET_TRANSPORTS` | example-frontend (`store/socketTransports.ts`) | Comma-separated Socket.IO transports passed to `useSocketConnection({transports})` and `createSyncDb({socketTransports})`. Unset keeps `polling,websocket`; the Vercel build sets `websocket` |
 | `APP_ENV` | `@terreno/rtk` | Logged at startup |
 
 Resolution order for API base URL (`rtk/src/constants.ts`):
@@ -101,6 +106,12 @@ 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`
 
+`EXPO_PUBLIC_API_URL` is inlined only into app source. Code under `node_modules`, including `@terreno/rtk`, does not see the inlined value in a production export and falls back to `extra.BASE_URL`, so set both for production web builds. `example-frontend/scripts/vercelBuild.ts` writes `extra.BASE_URL` from `EXPO_PUBLIC_API_URL` before `expo export`.
+
+### Per-environment values on hosting platforms
+
+Hosting platforms scope variables per environment. Vercel has **Production**, **Preview**, and **Development** scopes; set `EXPO_PUBLIC_API_URL` in each so each build points at its own backend. Because the value is inlined at build time, promoting a preview build to production keeps the preview backend URL. Rebuild for production instead. See [Deploy to Vercel](../how-to/deploy-to-vercel.md#configure-each-environment) and the [multi-environment checklist](../explanation/deployment-baseline.md#multi-environment-checklist).
+
 ## Development tooling
 
 | Variable | Read by | Required | Default | Secret | Scope |
@@ -329,6 +340,7 @@ skips it, so no deployed revision, PR previews included, holds those accounts.
 
 - [Deployment baseline](../explanation/deployment-baseline.md)
 - [Build for web](../how-to/build-for-web.md)
+- [Deploy to Vercel](../how-to/deploy-to-vercel.md)
 - [Configure Better Auth](../how-to/configure-better-auth.md)
 - [Rate limiting](../how-to/rate-limiting.md)
 - [Durable background jobs](../how-to/background-jobs.md)

package/src/docs/versioned/next/reference/legacy/rtk.md

@@ -284,6 +284,7 @@ useEffect(() => {
 - `onConnectError` (function) — Callback on connection error
 - `onReconnectFailed` (function) — Callback after all reconnection attempts fail
 - `captureEvent` (function) — Analytics event tracking (optional)
+- `transports` (string[]) — Socket.IO transports in order. Default `["polling", "websocket"]`. Pass `["websocket"]` for hosts without session affinity, such as Vercel Functions ([details](../../how-to/vercel-function-websockets.md))
 
 **Returns:**
 - `socket` (Socket | null) — Socket.io client instance

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

@@ -227,6 +227,7 @@ before anything else has confirmed one.
 | `authProvider` | `AuthProvider` | — (required) | `{getToken, getUserId, onAuthChange, refresh?}` |
 | `baseUrl` | `string` | — | Server origin; required unless both `transport` and `httpChannel` are injected |
 | `transport` | `SyncTransport` | socket transport from `baseUrl` | Override for tests or custom wiring |
+| `socketTransports` | `string[]` | `["polling", "websocket"]` | Socket.IO transports for the default socket transport. Use `["websocket"]` on hosts without session affinity, such as Vercel Functions ([details](../how-to/vercel-function-websockets.md)) |
 | `httpChannel` | `HttpChannel` | built from `baseUrl` | HTTP fallback channel override |
 | `persisterFactory` | `PersisterFactory` | platform default (IndexedDB web, expo-sqlite native) | Storage backend override |
 | `keyProvider` | `KeyProvider` | server-derived via `GET /sync/key` | Web encryption key provider |