@terreno/mcp 57.4.0 → 57.6.0

package/src/docs/versioned/next/implementationPlans/mcp-doc-sync-off-compile-path.md

@@ -0,0 +1,97 @@
+# Implementation Plan: Move mcp-server doc-sync off the compile path
+
+**Status:** Approved (2026-09-22)
+**Scan goal:** reduce-cold-compile-time ([charter](../scans/reduce-cold-compile-time/charter.md)) — cold `bun run compile` 305s → 214s
+**Slice:** mcp-doc-sync-off-compile-path (round 1) — **must land before** `compile-pipeline-dedup`
+**Findings:** mcp-doc-sync-on-compile-path (medium, S)
+**Effort:** S
+**Owner / Reviewer:** @joshgachnang
+**Created:** 2026-09-22
+
+## Goal
+
+Take the three doc-sync scripts and the `cp` off mcp-server's `compile` script so a normal
+`bun run compile` type-checks only. This removes ~5s of fixed I/O from every cold build and
+— critically — eliminates a Bun `cpSync` race in `sync-versioned-docs` that intermittently
+fails the full concurrent build (observed 1/3 runs once Slice B raises build concurrency).
+
+## Background
+
+`mcp-server/package.json` `compile` currently is:
+
+```
+NODE_OPTIONS=…=8192 bun run sync-ui-docs && …sync-versioned-docs && …sync-package-guidelines && …tsc && cp -r src/docs dist/
+```
+
+- `sync-ui-docs`: `cp ../demo/ui-types-documentation.json src/docs/`
+- `sync-versioned-docs`: recursively copies `website/versioned_docs/**` → `src/docs/versioned/**` (heaviest; ~5s; `src/docs/versioned` is git-ignored, generated only here)
+- `sync-package-guidelines`: copies five packages' `.ai` trees → `src/docs/guidelines/` (`guidelines/` IS committed)
+- `cp -r src/docs dist/`: bundles docs next to compiled output
+
+Runtime/`resources.ts` reads `getDocsRoot()/…` = `<dir>/docs`, so the **published** artifact
+must bundle docs. `build` already exists and is byte-identical to `compile` (full pipeline).
+
+**Why this blocks Slice B:** with Slice B's dependency-ordered build, ~18 packages compile
+concurrently, and `sync-versioned-docs`'s recursive `cpSync` intermittently throws
+ENOENT/EEXIST under heavy parallel I/O. It passes 5/5 in isolation; the race only appears
+under full-build concurrency. Taking it off `compile` removes the race from `bun run compile`.
+
+## The change (1 file)
+
+`mcp-server/package.json`:
+- `compile` → `NODE_OPTIONS=--max-old-space-size=8192 tsc` (type-check only).
+- `build` → keep the full pipeline (sync-ui-docs + sync-versioned-docs +
+  sync-package-guidelines + tsc + cp), and drop the redundant `NODE_OPTIONS=8192` from the
+  three copy steps (keep it only on `tsc`).
+- **Add `prepublishOnly": "bun run build"`** so every publish path bundles docs via npm's
+  own lifecycle — no per-CI special-casing.
+
+**Why `prepublishOnly` instead of editing a workflow:** the package publishes through **two**
+independent CI paths — GitHub Actions (`publish-on-tag.yml`) and CircleCI lockstep
+(`scripts/ci/publish-package.sh`) — and both run `bun run compile` (now tsc-only) before
+`npm publish`. `npm publish` runs `prepublishOnly` automatically in both, so `bun run build`
+regenerates `dist/docs` right before packing regardless of caller. No workflow file is
+touched. (`prepublishOnly` fires only on publish — not on install or `npm pack`.)
+
+## Non-goals
+
+- No change to the sync scripts' logic (`sync-versioned-docs.ts`, `sync-package-guidelines.ts`).
+- No change to `getDocsRoot` or runtime doc resolution.
+- No change to any other package or to `compile-pipeline-dedup` (Slice B).
+
+## Acceptance criteria (observable + verification)
+
+| # | Criterion | Verification |
+| --- | --- | --- |
+| 1 | `bun run --filter '@terreno/mcp' compile` runs `tsc` only (no sync, no cp) | Inspect build log: zero "Synced docs version", zero `cp` for docs during compile |
+| 2 | `bun run build` in mcp-server still produces `dist/docs` with versioned + guidelines + ui-types | `bun run build` then assert `dist/docs/versioned/*`, `dist/docs/guidelines/*`, `dist/docs/ui-types-documentation.json` exist |
+| 3 | Published-artifact parity: `bun run build` output matches the pre-change `compile` output | `diff -r` new `build` dist vs a baseline `compile` dist snapshot → no differences |
+| 4 | Full cold `bun run compile` no longer runs mcp doc-sync and no longer flakes | Run `bun run compile` from clean 3× → exit 0 each time, zero mcp ENOENT/EEXIST |
+| 5 | Every publish path bundles docs | `prepublishOnly` runs `bun run build`; `npm publish --dry-run` shows it firing and regenerating `dist/docs`; both GH Actions and CircleCI `npm publish` trigger it |
+| 6 | Lint/type-check green | `bun run --filter '@terreno/mcp' compile` exits 0 |
+
+Criterion #4 is the metric + reliability tie-back.
+
+## Unacceptable trade-offs (charter, verbatim)
+
+- **Published dist output must stay intact** — the published `@terreno/mcp` still ships
+  `dist/docs` (versioned + guidelines + ui-types), verified by criteria #2/#3/#5.
+- **No type-safety loss.**
+
+## Risks
+
+- **Another consumer relies on `bun run compile` producing mcp `dist/docs`.** Checked: root
+  `compile` is dev type-check (no doc need); publish uses `compile`→now `build`; `dev` runs
+  from `src` via `bun --watch`. No deploy script runs mcp `compile`→`start`. Residual: local
+  `bun run start` after only `compile` would lack freshly-synced versioned docs (already
+  git-ignored/generated); run `build` for a runnable server. Documented.
+
+## Docs to update
+
+- `.claude/rules/mcp-server/00-mcp-server.md` / mcp build doc: note `compile` = type-check,
+  `build` = shippable artifact with docs.
+
+## Rollout
+
+Single PR, reviewer @joshgachnang, human merge on green CI. Lands before Slice B; Slice B
+then rebases on master and its full build is race-free.

package/src/docs/versioned/next/implementationPlans/migrate-cicd-to-circleci-research.md

@@ -1,9 +1,9 @@
 # Research: Migrate CI/CD to CircleCI
 
 **Status:** Research complete — decisions recorded in IP `migrate-cicd-to-circleci.md`  
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1088
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1088
 **Date:** 2026-08-17  
-**Repo:** FlourishHealth/terreno (`master` @ `1e3e79a6`)  
+**Repo:** TerrenoLabs/terreno (`master` @ `1e3e79a6`)  
 **Branch:** `cursor/migrate-cicd-circleci-2b6d`
 
 ## Scope statement

package/src/docs/versioned/next/implementationPlans/migrate-cicd-to-circleci.md

@@ -2,7 +2,7 @@
 
 **Status:** In progress — CI, release, Netlify/GCP production path deploys, and PR previews landed; EAS PR/fingerprint temporarily disabled; GitHub-native maintenance remains  
 **Discussion:** _(none)_  
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1088
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1088
 **Linear:** _(none)_  
 **Priority:** High  
 **Effort:** Large (cross-cutting infra; many workflows)  
@@ -112,7 +112,7 @@ Prefer extending the module (`circleci_oidc` or rename to `ci_oidc` with multipl
 
 ### GitHub ↔ CircleCI integration
 
-- CircleCI GitHub App (or OAuth) on `FlourishHealth/terreno`.
+- CircleCI GitHub App (or OAuth) on `TerrenoLabs/terreno`.
 - Status checks reported to GitHub for branch protection (job names documented in `docs/explanation/repository-settings.md`).
 - PR comments / labels / Deployments API: call GitHub REST via `gh` or `curl` with `terreno-github-api` context (replaces `GITHUB_TOKEN` action privileges).
 - Tag + schedule triggers: CircleCI pipeline triggers (or GitHub → CircleCI API webhook) for cron jobs currently on GHA.
@@ -168,7 +168,7 @@ Implemented: production and PR preview jobs exist on CircleCI. GitHub Actions
 is the live Netlify/GCP writer until `terreno-netlify` / `terreno-gcp` are
 populated; CircleCI deploy scripts skip (exit 0) when those variables are
 missing. After a successful CircleCI deploy, set GHA deploy workflows back to
-`on: []` in the same change. Preview cleanup on PR close is GHA
+`push.branches-ignore: ["**"]` in the same change. Preview cleanup on PR close is GHA
 `preview-cleanup.yml` plus the manual CircleCI parameter.
 
 ### Phase 5 — EAS + fingerprint (v1)
@@ -177,7 +177,7 @@ missing. After a successful CircleCI deploy, set GHA deploy workflows back to
 - PR comment + `fingerprint-acknowledged` label via GitHub API.
 
 Manual EAS dispatch is implemented. EAS PR updates and fingerprint
-acknowledgement are retained with `on: []` until CircleCI comment/label parity
+acknowledgement are retained with `push.branches-ignore: ["**"]` until CircleCI comment/label parity
 is implemented.
 
 ### Phase 6 — GCP CD + OIDC (v1)
@@ -204,7 +204,7 @@ are ported.
 
 ### Phase 8 — Mobile runners (post-v1 / still required for full cutover)
 
-- Maestro web/Chrome (`maestro-e2e`) is implemented on CircleCI Linux browsers + Mongo replica set. GHA `maestro-e2e.yml` is `on: []`.
+- Maestro web/Chrome (`maestro-e2e`) is implemented on CircleCI Linux browsers + Mongo replica set. GHA `maestro-e2e.yml` is `push.branches-ignore: ["**"]`.
 - Appium Android on Linux VM and Appium iOS on CircleCI macOS remain unported.
 
 ### Phase 9 — GitHub-native + agentic replacements (full cutover)
@@ -215,7 +215,7 @@ are ported.
 | `dependabot-auto-merge` | Keep Dependabot PRs on GitHub; auto-merge via CircleCI on Dependabot branches **or** Renovate on CircleCI |
 | `triage.yml` | CircleCI pipeline trigger on `issues` via GitHub Apps webhook → CircleCI API, or GitHub Action **stub** only if product accepts residual GHA (conflicts with CC1 — prefer webhook) |
 | `roadmap-generate` | Scheduled CircleCI job with `ROADMAP_PROJECT_TOKEN` |
-| `architectural-pr-review` | Implemented: CircleCI job + `CURSOR_API_KEY` / `GITHUB_TOKEN`. Checks out `origin/master`, skips forks. GHA workflow is `on: []`. |
+| `architectural-pr-review` | Implemented: CircleCI job + `CURSOR_API_KEY` / `GITHUB_TOKEN`. Checks out `origin/master`, skips forks. GHA workflow is `push.branches-ignore: ["**"]`. |
 | Cursor Approval / Security / Bugbot | **Cannot move.** Cursor GitHub App automations, not repo workflows. |
 | `agentics-maintenance` + `*.lock.yml` gh-aw | Re-home to CircleCI scheduled pipelines calling the same scripts **or** retire features; do not leave gh-aw as the only runner if CC1 holds |
 | `docs-audit` | Scheduled CircleCI job |

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

@@ -2,7 +2,7 @@
 
 **Status:** Deferred
 **Closed:** 2026-08-20 — Not pursued; custom `endpoints` callbacks remain the supported pattern for non-CRUD routes.
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1097
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1097
 
 ## Goal
 

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

@@ -2,7 +2,7 @@
 
 **Status:** Complete (write path now uses unified mutation executors — see [unified-mutation-executors.md](unified-mutation-executors.md); list/read remain handlers)
 
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1092
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1092
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
 
 ## Overview

package/src/docs/versioned/next/implementationPlans/mongodb-migrations-tooling.md

@@ -4,7 +4,7 @@
 **Branch:** `cursor/mongodb-migrations-tooling-04f9`  
 **Owner:** —  
 **Created:** 2026-09-10  
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1189  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1189  
 **Primary packages:** `@terreno/api`, `@terreno/admin-backend`, `@terreno/admin-frontend`, `admin-spa`, `example-backend`
 
 ## Goal

package/src/docs/versioned/next/implementationPlans/native-module-baseline.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Native module baseline for the next major release
 
 **Status:** Draft
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1026
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1026
 **Priority:** High
 **Effort:** Small batch (code) — coordination cost is the release itself
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/notification-center.md

@@ -5,7 +5,7 @@
 **Owner:** —  
 **Created:** 2026-09-10  
 **Approved:** 2026-09-10  
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1179 (this feature **closes** that issue; implementation PRs use `Fixes #1179`)  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1179 (this feature **closes** that issue; implementation PRs use `Fixes #1179`)  
 **Task list:** [notification-center.md](../tasks/notification-center.md)  
 **Depends on:** [comms-abstraction](comms-abstraction.md) (shipped)  
 **RTK deprecation flag:** Partial — inbox is a syncdb collection; no new RTK CRUD hooks  

package/src/docs/versioned/next/implementationPlans/offline-mode.md

@@ -2,7 +2,7 @@
 
 **Status:** Deferred
 **Closed:** 2026-08-20 — Superseded by [@terreno/syncdb](syncdb-local-first.md) local-first outbox and offline-capable sync.
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1096
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1096
 **Priority:** High
 **Effort:** Medium
 

package/src/docs/versioned/next/implementationPlans/org-management-ui.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Organizations as a first-class primitive (admin UI + RBAC)
 
 **Status:** Approved
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1024 (absorbs `orgs-and-teams`; retitle on approve)
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1024 (absorbs `orgs-and-teams`; retitle on approve)
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/orgs-and-teams.md

@@ -2,7 +2,7 @@
 
 **Status:** Superseded — 2026-08-24
 **Superseded by:** [org-management-ui](org-management-ui.md) (backend primitive + RBAC + admin UI)
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1024
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1024
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/oss-governance-baseline.md

@@ -1,7 +1,7 @@
 # Implementation Plan: OSS Governance Baseline
 
 **Status:** Complete
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1003
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1003
 **Priority:** High
 **Effort:** Small batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/oss-launch-program.md

@@ -1,7 +1,7 @@
 # Program: Open Source Launch
 
 **Status:** In progress — decisions recorded (defaults accepted 2026-07-29)
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1094
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1094
 **Priority:** High
 **Effort:** Epic (multiple IPs)
 **Owner:** unassigned
@@ -40,7 +40,7 @@ Language rules for all docs:
 
 ## RTK deprecation gate
 
-**`@terreno/rtk` is being replaced.** PR [#869](https://github.com/flourishhealth/terreno/pull/869) (`@terreno/syncdb` local-first data layer) makes **Better Auth + `@terreno/syncdb`** the supported frontend platform. RTK Query becomes legacy.
+**`@terreno/rtk` is being replaced.** PR [#869](https://github.com/TerrenoLabs/terreno/pull/869) (`@terreno/syncdb` local-first data layer) makes **Better Auth + `@terreno/syncdb`** the supported frontend platform. RTK Query becomes legacy.
 
 **Program-wide rule: IPs flagged `Blocked` may not be implemented until #869 merges.** Writing docs against RTK now guarantees a rewrite. Planning (this program) proceeds; implementation of `None`-flagged IPs may start before #869; `Partial` IPs proceed except for `[RTK]`-marked tasks.
 
@@ -69,7 +69,7 @@ Every `[RTK]`-marked task in every task file must be reviewed against the merged
 
 ## Boost dependency (AI story)
 
-PR [#802](https://github.com/flourishhealth/terreno/pull/802) (MCP Boost parity, Phases 4–6) is **assumed merged** by the AI-facing IPs. It delivers the runtime half of the AI story:
+PR [#802](https://github.com/TerrenoLabs/terreno/pull/802) (MCP Boost parity, Phases 4–6) is **assumed merged** by the AI-facing IPs. It delivers the runtime half of the AI story:
 
 - `read_logs` merging backend / app (CDP) / Metro / browser sources
 - `last_error` across sources

package/src/docs/versioned/next/implementationPlans/password-reset-and-email-verification.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Password reset and email verification
 
 **Status:** Approved
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1023
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1023
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/pluggable-database-sqlite-research.md

@@ -147,4 +147,4 @@ Recorded in the planning thread; the IP will not be written until these are answ
 - `admin-backend/src/adminApp.ts`, `mcp-server/src/tools.ts`, `test/src/mongo/mongoServer.ts`
 - [syncdb-codegen.md](syncdb-codegen.md), [comms-abstraction.md](comms-abstraction.md), [positioning-django-rails-universal.md](positioning-django-rails-universal.md), [deploy-to-gcp.md](deploy-to-gcp.md) (GC2 future-Postgres note)
 - Better Auth SQLite adapters: https://better-auth.com/docs/adapters/sqlite ; Drizzle adapter: https://better-auth.com/docs/adapters/drizzle
-- Prior art: [PR #145](https://github.com/FlourishHealth/terreno/pull/145) (closed) — an earlier SQL-adapter plan proposing Bun.SQL multi-dialect support and JOIN-based population; superseded by this IP's adapter seam + batched population design
+- Prior art: [PR #145](https://github.com/TerrenoLabs/terreno/pull/145) (closed) — an earlier SQL-adapter plan proposing Bun.SQL multi-dialect support and JOIN-based population; superseded by this IP's adapter seam + batched population design

package/src/docs/versioned/next/implementationPlans/positioning-django-rails-universal.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Positioning — "Django/Rails for TypeScript, with Universal Apps"
 
 **Status:** Implemented
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1008
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1008
 **Priority:** High
 **Effort:** Small batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/public-roadmap-github.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Public Roadmap on GitHub
 
 **Status:** Complete
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1004
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1004
 **Priority:** High
 **Effort:** Small batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/rate-limiting.md

@@ -4,7 +4,7 @@
 **Branch:** `cursor/api-rate-limiting-d03a`  
 **Owner:** —  
 **Created:** 2026-08-30  
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1187 (this feature **closes** that issue; implementation PRs use `Fixes #1187`)  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1187 (this feature **closes** that issue; implementation PRs use `Fixes #1187`)  
 **Task list:** [rate-limiting.md](../tasks/rate-limiting.md)  
 **Depends on:** —  
 **RTK deprecation flag:** None  
@@ -209,4 +209,4 @@ Skills: `backend-test-env` if any test mutates env (Redis URL). `mongoose-schema
 - [ ] 429 is `APIError` with `Retry-After` and `RateLimit` headers.
 - [ ] Docs how-to + reference + auth explanation + Terreno 58 default-on note exist.
 - [ ] Sync mutation limiter behavior unchanged (existing sync tests still pass).
-- [ ] Merging the implementation PR closes https://github.com/FlourishHealth/terreno/issues/1187 (`Fixes #1187`).
+- [ ] Merging the implementation PR closes https://github.com/TerrenoLabs/terreno/issues/1187 (`Fixes #1187`).

package/src/docs/versioned/next/implementationPlans/rbac-permissions.md

@@ -1,7 +1,7 @@
 # RBAC Permissions for Terreno — API Design
 
 **Status:** Complete — phases 1–6 shipped in PR #932 (2026-08-22)
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1089
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1089
 **Target package:** `@terreno/api` (new `src/rbac/` module), with surfaces in `admin-backend`, `admin-frontend`, `admin-spa`, `rtk`, and the modelRouter MCP work
 **Depends on:** `better-auth/plugins/access` (already a dependency via the Better Auth provider)
 

package/src/docs/versioned/next/implementationPlans/rtk-to-syncdb-migration-docs.md

@@ -1,7 +1,7 @@
 # Implementation Plan: RTK Deprecation and SyncDB Migration Docs
 
 **Status:** Complete — syncdb reference, migration guide, agent surfaces, and deprecation signalling shipped on `master`
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1007
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1007
 **Priority:** Critical (gates most of Wave 1)
 **Effort:** Big batch
 **Owner:** unassigned