@terreno/mcp 58.0.0 → 58.0.1

package/src/docs/versioned/57.18.0/explanation/schema-metadata.md

@@ -1,60 +0,0 @@
-# Schema metadata (`describeModel`)
-
-Terreno walks each Mongoose schema **once** and builds a `ModelDescription` field graph. OpenAPI, admin config, and MCP tools are **views** of that graph — they do not re-walk `schema.paths` independently.
-
-## Why one descriptor
-
-Before `describeModel`, three surfaces each interpreted Mongoose differently:
-
-- **OpenAPI** — `mongoose-to-swagger` in `getOpenApiSpecForModel`
-- **Admin** — OpenAPI property walk plus Mongoose ref patching in `extractFieldMeta`
-- **MCP** — `schema.paths` + `SchemaType.instance` switch in `schemaGenerator`
-
-That drifted on refs, enums, nested arrays, and system fields. A single descriptor keeps field facts in one place.
-
-## Core API
-
-```typescript
-import {describeModel, describeModelForRouter} from "@terreno/api";
-
-const description = describeModel(Todo);
-// description.fields[path].kind, .required, .description, .enum, .ref, .isArray, .item, .system
-
-const routerDescription = describeModelForRouter(Todo, {
-  validation: {excludeFromCreate: ["ownerId"]},
-  fieldView: {read: "*", write: ["title", "completed"]},
-});
-// adds writableOnCreate / writableOnUpdate per field
-```
-
-## Field kinds
-
-| Kind | Mongoose source | Notes |
-|------|-----------------|-------|
-| `string` | String | Includes enum strings |
-| `number` | Number | |
-| `boolean` | Boolean | |
-| `date` | Date | ISO date-time in OpenAPI |
-| `dateOnly` | DateOnly | Custom Terreno type |
-| `objectId` | ObjectId | Carries `ref` model name |
-| `embedded` | Subdocument / array of subdocuments | Nested `fields` |
-| `mixed` | Mixed | Accepts any value in OpenAPI |
-| `map` | Map | `item` follows Map `of` (omitted `of` is `mixed`); OpenAPI `additionalProperties` |
-
-System paths (`_id`, `__v`, `created`, `updated`, `deleted`) are marked with `system: true`.
-
-## Views (not canonical)
-
-| Surface | Function | Notes |
-|---------|----------|-------|
-| OpenAPI | `modelDescriptionToOpenApiSpec` | Used by `getOpenApiSpecForModel`; populate still merges referenced models |
-| Admin `/admin/config` | `modelDescriptionToAdminFields` | Widget choice stays in admin-backend |
-| MCP Zod | `fieldDescriptionToZodType` | Create/update tools omit system fields |
-
-Populate paths remain a `getOpenApiSpecForModel` concern; the descriptor records `ref` on the local path only.
-
-## Related
-
-- [API reference — describeModel](../reference/api.md#describemodel)
-- [How to create a model](../how-to/create-a-model.md)
-- [Admin backend reference](../reference/admin-backend.md)

package/src/docs/versioned/57.18.0/explanation/source-rules.md

@@ -1,57 +0,0 @@
-# Production source rules
-
-Terreno production TypeScript follows six mechanical conventions. This page is the
-policy those conventions implement. CI fails a PR that introduces a new production
-file (or a new hit in an existing file) that would trip them.
-
-## Scope
-
-`{api,ui,rtk,ai,admin-backend,admin-frontend,example-backend}/src/**/*.{ts,tsx}`
-
-`example-frontend` and `demo` are listed in the original align glob but have no `src/`
-tree (`app/`, `components/`, `stories/` instead), so this scanner does not cover them.
-
-Skipped: tests (`*.test.*`, `*.spec.*`, `*.isolated.*`, `__tests__`), generated SDKs
-(`openApiSdk.ts`, `*OpenApiSdk.ts`), declaration files (`*.d.ts`), `node_modules`, `dist`,
-and test harness files such as `bunSetup.ts`.
-
-## Rules
-
-| Rule | Ban | Use instead |
-| --- | --- | --- |
-| Arrow functions | `function` declarations | `const name = (…) => {…}` |
-| Luxon | `new Date(`, `Date.now()` | `DateTime` from `luxon` |
-| API errors (backend) | `throw new Error(` | `throw new APIError({…})` |
-| Logging | `console.log(` | Backend `logger.*`; frontend `console.info` / `warn` / `error` |
-| Mongoose reads (backend) | `Model.findOne(` | `findExactlyOne`, `findOneOrNone`, `findOneOrNoneFor` |
-| Explicit any | `as any` | Precise types, or `as unknown as T` |
-
-## Allowed leftovers
-
-These still match a naive grep and are **not** violations:
-
-- Mongoose hooks, statics, methods, and virtuals that need `this` (`schema.pre`, `.post`, `.method`, `.statics`, `.virtual`). A nearby hook does not whitelist a later `function` in the same file.
-- TypeScript overload signatures plus their implementation (`modelRouter`)
-- `React.forwardRef(function …)` and `*.prototype.* = function` patches that close over `this`
-- Raw Mongo `collection.findOne`
-- `as any` with a line-level `biome-ignore lint/suspicious/noExplicitAny`
-- Hits inside comments or string literals
-
-## Commands
-
-```bash
-bun run check:source-rules
-bun test scripts/check-source-rules/
-```
-
-## Enforcement
-
-| Layer | What it does |
-| --- | --- |
-| **`bun run check:source-rules`** | Scans scoped production sources and fails on any remaining hit |
-| **Repository policies CI** | CircleCI job `repo-policies` (includes `check:source-rules`) |
-| **`bun run check`** | Local aggregate that includes this scanner |
-
-A **new** production file that uses `export function`, `Date.now()`, `throw new Error`, `console.log`, `Model.findOne`, or unsuppressed `as any` fails CI.
-
-Do not add suppress comments for these rules. Fix the code, or use one of the allowed leftovers above.

package/src/docs/versioned/57.18.0/explanation/typescript-configuration.md

@@ -1,46 +0,0 @@
-# TypeScript configuration
-
-Copy the `tsconfig.json` of the closest profile below when you add a package. Every config
-builds on TypeScript 6 with no `ignoreDeprecations`, so `tsc` fails fast on any option that
-TypeScript 7 removes.
-
-## Profiles
-
-| Profile | Packages | `module` | `target` | Emits |
-| --- | --- | --- | --- | --- |
-| Node library | `api`, `ai`, `admin-backend`, `announcements`, `api-health`, `blocks`, `comms`, `feature-flags`, `jobs`, `test`, `admin-spa` server (`tsconfig.server.json`) | `nodenext` | `es2023` | CommonJS `dist/` |
-| Node ESM tool | `mcp-server`, `create-terreno-app` | `nodenext` | `es2023` | ESM `dist/` (`"type": "module"`) |
-| Frontend library | `ui`, `admin-frontend`, `rtk`, `syncdb` | `esnext` + `moduleResolution: bundler` | `es2022` | ESM `dist/` for Metro |
-| Bun CLI | `cli` | `esnext` + `moduleResolution: bundler` + `customConditions: ["bun"]` | `es2022` | ESM `dist/` for Bun |
-| Expo app | `example-frontend`, `demo`, `admin-spa` | extends `expo/tsconfig.base` | from Expo | nothing (`noEmit`) |
-| Bun app | `example-backend` | `preserve` | `esnext` | nothing (`noEmit`) |
-| Docs site | `website` | extends `@docusaurus/tsconfig` | from Docusaurus | nothing (`noEmit`) |
-
-Each workspace keeps a self-contained config. Packages without a `files` allowlist publish
-their `tsconfig.json`, so an `extends` into a repo-root base would ship a broken path.
-
-## Why these settings
-
-| Setting | Reason |
-| --- | --- |
-| `module: nodenext` for Node packages | Models Node's real resolution, including `exports` conditions. CommonJS output keeps dynamic `import()` as a real ESM import. `module: commonjs` rewrote it to `require()`, which cannot load `file://` URLs or ESM-only code. |
-| `target: es2023` for Node packages | Node 20+ (the Mongoose 9 floor) runs ES2023 natively, so `tsc` emits readable code with no downleveling or helpers. |
-| `target: es2022` for frontend libraries | Metro and Babel transform consumer bundles, and ES2022 class-field semantics match what Babel and Hermes expect. |
-| `isolatedModules` | Bun, Metro, and Babel transpile one file at a time. `tsc` flags code that only works with whole-program compilation. `syncdb` leaves it off because TinyBase's `Persists` is an ambient `const enum` that `tsc` must inline. |
-| No `baseUrl` | Deprecated in TypeScript 6 and removed in 7. `paths` resolve from the tsconfig's own directory, as do Bun, Expo's Metro resolver, and `check:no-barrel-imports`. `website` sets `"baseUrl": null` to clear the value `@docusaurus/tsconfig` still sets. |
-| Explicit `types` | TypeScript 6 defaults `types` to `[]`. List ambient packages (`node`, `bun`) instead of loading every `@types/*` package. |
-| `strict: true` | Already the TypeScript 6 default. It stays explicit because it is the most important check. |
-
-## Do not add
-
-| Option | Why |
-| --- | --- |
-| `ignoreDeprecations` | Hides options that stop working in TypeScript 7. |
-| `baseUrl` | Deprecated. Write `paths` entries relative to the tsconfig (`"./src/*"`). |
-| `moduleResolution: node` / `node10` / `classic` | Deprecated. Use `nodenext` for Node or `bundler` for bundled code. |
-| `target: es5`, `downlevelIteration` | Deprecated. No supported runtime needs ES5 output. |
-| `esModuleInterop`, `allowSyntheticDefaultImports`, `forceConsistentCasingInFileNames` | Already `true` by default in TypeScript 6. Setting them to `false` is deprecated. |
-
-`create-terreno-app` scaffolds follow the Expo app and Bun app profiles. Its
-`tsconfig.codegen.json` pairs `module: commonjs` with `moduleResolution: bundler`, because
-the RTK codegen CLI forces CommonJS when it registers `ts-node`.

package/src/docs/versioned/57.18.0/explanation/versioning-policy.md

@@ -1,35 +0,0 @@
-# Versioning policy
-
-All published `@terreno/*` packages share one version. Upgrade them together. Mixing versions is unsupported.
-
-## Lockstep
-
-A git tag `X.Y.Z` (no `v` prefix) is the version for every package that `.github/workflows/publish-on-tag.yml` publishes: `api`, `test`, `ui`, `rtk`, `admin-backend`, `admin-frontend`, `admin-spa`, `blocks`, `ai`, `api-health`, `comms`, `feature-flags`, `mcp`, `syncdb`. Publish jobs read that tag; they do not pick per-package versions.
-
-Inside the monorepo, packages depend on each other with `workspace:*` (for example `@terreno/rtk` → `@terreno/ui`). On npm they are released at the same number. `@terreno/ui` also pins Expo-line peers (`react-native` `~0.86.0` on the 57 line). Installing `@terreno/ui@57` next to Expo 54 is outside support, same as mixing `@terreno/api@57` with `@terreno/ui@0.31`.
-
-## Pre-1.0 (and Expo-aligned majors)
-
-While the public API is still moving, a **minor** may include breaking changes. Those land only with an upgrade note in `mcp-server/src/docs/upgrades/<version>.md`. The changelog `### Breaking` / `### Changed` / `### Deprecated` / `### Removed` headings require that file (`bun run check:upgrade-docs`).
-
-From 56 onward the **major** tracks the Expo SDK major (`56.x`, `57.x`). That is not a 1.0 stability promise. It is a peer-stack label.
-
-## Deprecation window
-
-A public API marked deprecated stays available for **at least three minor releases** on the current major (example: deprecated in `57.1.0` → still present in `57.2.0` and `57.3.0`). Removal happens in a later minor or the next major, always with an upgrade note.
-
-Worked example: `@terreno/rtk` collection CRUD was deprecated in `56.0.0` (restated in `57.1.0`). The package still publishes on 57.x for the OpenAPI SDK, Better Auth Redux, feature flags, and sockets. It will not ship in the **next major**. Migrate collection screens with [migrate-rtk-to-syncdb.md](../how-to/migrate-rtk-to-syncdb.md) as a separate operation from a routine version bump.
-
-## Where to read changes
-
-| Source | Use |
-| --- | --- |
-| [`CHANGELOG.md`](../../CHANGELOG.md) | What shipped |
-| [`mcp-server/src/docs/upgrades/`](../../mcp-server/src/docs/upgrades/) | What you must do |
-| MCP `terreno_get_upgrade_guide` | Concatenated notes for `fromVersion` → `toVersion` |
-
-Note format: [`mcp-server/src/docs/upgrades/README.md`](../../mcp-server/src/docs/upgrades/README.md).
-
-## What 1.0 will mean
-
-OSS launch question P9 ([oss-launch-program.md](../implementationPlans/oss-launch-program.md)): 1.0 is an API-stability audit after syncdb has settled — not the Expo-aligned 57 line. Until that audit, treat minors as able to break with a note.

package/src/docs/versioned/57.18.0/how-to/README.md

@@ -1,76 +0,0 @@
-# How-to Guides
-
-Problem-oriented, practical steps. Use these when you know what you want to do.
-
-## Deployment
-
-- [Deployment baseline](../explanation/deployment-baseline.md) — seven requirements every host must satisfy
-- [Build for web](build-for-web.md) — export static web bundle with correct API URL
-- [Deploy to Google Cloud Platform](deploy-to-gcp.md) — index for GCP guides
-- [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md) — container + Secret Manager + Cloud Run
-- [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) — static hosting with SPA routing
-- [Deploy to Vercel](deploy-to-vercel.md) — web on Vercel, backend on Cloud Run or Vercel Functions; previews, CORS, CI
-- [Run WebSockets on Vercel Functions](vercel-function-websockets.md) — Socket.IO and syncdb on Vercel's WebSocket beta: transports, reconnects, state
-
-## Contents
-
-- [Create a Terreno app](create-a-terreno-app.md) — Scaffold a full-stack app with `create-terreno-app` (Bun or npm)
-- [Update dependencies](update-dependencies.md) — Daily rolling PR, exercise test, Expo fingerprint freeze
-- [CircleCI](circleci.md) — Dual-run CI on CircleCI (package CI / policy / e2e; deploys later)
-- [Run tests locally](run-tests-locally.md) — Map every CircleCI test job to a Cursor Cloud / laptop command
-- [GitHub Actions CI](github-actions-ci.md) — Cut PR runtime: docs previews, compile-once e2e, pinned Bun
-- [Add feature flags](add-feature-flags.md) — Add feature flags, A/B testing, and OpenFeature migration
-- [Rate limiting](rate-limiting.md) — Opt-in HTTP limiter on `TerrenoApp` (memory or Redis)
-- [Receive inbound webhooks](inbound-webhooks.md) — HMAC, Stripe, Twilio, and SendGrid signatures on `WebhooksApp`
-- [Durable background jobs](background-jobs.md) — `@terreno/jobs`: enqueue, workers, schedules, Cloud Tasks / Vercel Queues
-- [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
-- [Enable the framework audit log](audit-log.md) — `AuditApp`, per-router `audit`, append-only events
-- [Seed a database](seed-a-database.md) — Idempotent sync, dry runs, and guarded reset-and-reseed
-- [Run MongoDB migrations](run-mongodb-migrations.md) — Versioned `up`/`down` files, `terreno-migrate`, production gate
-- [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
-- [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
-- [Password reset and email verification](password-reset.md) — JWT routes, comms templates, Better Auth hooks
-- [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
-- [Expose Model Context Protocol tools](expose-mcp-tools.md) — Turn `modelRouter` models into MCP tools an LLM can call
-- [Set up Terreno MCP](set-up-terreno-mcp.md) — Configure hosted docs/codegen and local runtime tools
-- [Debug with MCP](debug-with-mcp.md) — Diagnose backend, browser, Metro, app, and client-state failures
-- [Connect an MCP client with a service token](connect-mcp-service-token.md) — Mint a personal `mcp_` key for Perplexity and other remote clients
-- [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md) — Let Claude.ai and ChatGPT connect to `/mcp` through OAuth 2.1 with your own consent screen
-- [Install agent skills](install-agent-skills.md) — `npx skills`, the Cursor plugin, the Codex plugin, or the Claude Code plugin
-- [Develop an AI feature](ai-feature-development.md) — Dataset → prompt → evaluators → experiment → production label → live traces (SOP)
-- [Observe LLM calls](observe-llm-calls.md) — Register ObservabilityApp, primaries, price map, sampleRate
-- [Build a durable workflow](build-a-durable-workflow.md) — Phased harness task with an agent, a human sign-off, and a once-only side effect (`clinic.intakeSummary`)
-- [Run the harness on multiple instances](run-harness-on-multiple-instances.md) — `JobsRunner`: harness phases as `@terreno/jobs` jobs on every instance
-- [Ship a new task version](ship-a-new-task-version.md) — Change a durable harness task without stranding in-flight runs
-- [GitHub issue lifecycle](github-issue-lifecycle.md) — Create pick-ready issues, Pick ⇄ Roast, or unattended `status:ready-for-dev` pickup
-- [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
-- [Upgrade banner](upgrade-banner.md) — Soft warning and hard-block app update UX
-- [Upgrade Terreno](upgrade-terreno.md) — Lockstep `@terreno/*` bumps, note range, order, rollback
-- [Track upstream Expo](track-upstream-expo.md) — Morning probe for SDK betas; `release-X.Y.Z` loop log + native fingerprint deps
-- [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid` (ops-dashboard scorecards and spans: [dashboard-chart-parity](../implementationPlans/dashboard-chart-parity.md))
-- [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md) — PNG goldens for the chart visual gallery, not JSON snapshots
-- [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer
-- [Use syncdb correctly](use-syncdb-correctly.md) — Serial snapshot startup, outbox-halting 403s, phantom creates, conflicts, and other library behavior apps must handle
-- [Generate a REST CLI from OpenAPI](generate-a-rest-cli.md) — Scaffold `terreno generate rest-cli` for an app API
-- [In-app notifications](in-app-notifications.md) — Register `NotificationsApp`, syncdb inbox, and UI bell
-- [Add organizations](add-organizations.md) — Opt into Membership-backed tenancy, RBAC, admin, and seeded examples
-- [Add a GPT chat mascot](add-gpt-chat-mascot.md) — Optional consumer-owned character on empty `GPTChat`
-- [Add agent asks to a chat](agent-ui-asks.md) — Turn on `asks`, show and answer them in `GPTChat`, try the keyless demo agent, and answer asks from an Apple Watch or another small client
-- [Validate a block document locally](agent-ui-blocks.md) — `terreno-blocks validate` for a whole-reply YAML document
-- [Add a stepper callback](agent-ui-blocks.md#add-a-stepper-callback) — `scaleStepperHostAction` or your own `handles: "stepper"` action; checklist ticks, copy buttons, the `richBlocks: false` opt-out, and the `blocks:smoke` model check are on the same page
-- [Give the agent photos](agent-ui-blocks.md#give-the-agent-photos) — Generate a stored photo library once and let the agent cite it with `findPhotos`
-
-## Admin
-
-- [Build admin screens](build-admin-screens.md) — Screens, sidebar nav, `routeBase`, custom screens
-- [Add a model to the admin](admin-add-model.md) — `modelRouter({admin: ...})` setup
-- [Import pre-built admins](admin-import-prebuilt.md) — Plugin `adminContribution()` wiring
-- [Add a custom admin field widget](admin-custom-widget.md) — Custom field widgets
-- [Customize the admin home](admin-custom-home.md) — Home slots and built-in widgets
-
-## Coming Soon
-
-- Add custom permissions
-- Implement file uploads
-- Configure email notifications
-- Customize AI workflows

package/src/docs/versioned/57.18.0/how-to/add-feature-flags.md

@@ -1,140 +0,0 @@
-# Add Feature Flags
-
-Add feature flags and A/B testing to your Terreno app using `@terreno/feature-flags`.
-
-## Prerequisites
-
-- A working Terreno backend using `TerrenoApp`
-- `@terreno/admin-backend` registered for the admin panel (optional but recommended)
-
-## Steps
-
-### 1. Install the package
-
-```bash
-bun add @terreno/feature-flags
-```
-
-### 2. Register the backend plugin
-
-In your server file, register `FeatureFlagsApp` and add the admin config:
-
-```typescript
-import {TerrenoApp} from "@terreno/api";
-import {AdminApp} from "@terreno/admin-backend";
-import {FeatureFlagsApp, featureFlagAdminConfig} from "@terreno/feature-flags";
-
-// Define segment functions to classify users for targeting rules
-const segments = {
-  "pro-users": (user) => user.plan === "pro",
-  "beta-testers": (user) => user.betaTester === true,
-  "internal-team": (user) => user.email?.endsWith("@mycompany.com"),
-};
-
-new TerrenoApp({userModel: User})
-  .register(new FeatureFlagsApp({segments}))
-  .register(
-    new AdminApp({
-      models: [
-        featureFlagAdminConfig,  // adds Feature Flags to the admin panel
-        // ...your other models
-      ],
-    })
-  )
-  .start();
-```
-
-`featureFlagAdminConfig` is a pre-configured admin model config exported by the package. It sets up the display name, list fields, route path, and model reference so you don't need to configure them manually.
-
-### 3. Regenerate the frontend SDK
-
-After adding the backend routes, regenerate the SDK so the frontend can call the new endpoints (with the example backend running, or set `OPENAPI_URL` to your deployed `openapi.json`):
-
-```bash
-cd your-frontend && bun run sdk
-```
-
-Regeneration may emit a hook for `/feature-flags/flagConfiguration`; prefer **`useTerrenoFeatureFlags`** / **`useFeatureFlags`** from `@terreno/rtk` so OpenFeature domain, cache keying, and optional socket refetch stay consistent.
-
-### 4. Use feature flags in the frontend
-
-**Recommended (OpenFeature):** add `@openfeature/react-sdk` to the app, wrap the tree (or the subtree that reads flags) in `<OpenFeatureProvider domain="feature-flags">`, and call `useTerrenoFeatureFlags(terrenoApi, {userId, socket})` once after auth so the OpenFeature client receives `GET /feature-flags/flagConfiguration`. Then use standard hooks such as `useBooleanFlagValue` / `useStringFlagValue` / `FeatureFlag`.
-
-**Back-compat:** `useFeatureFlags(terrenoApi)` from `@terreno/rtk` still returns `{flags, getFlag, getVariant, isLoading, …}` with the same semantics as before; it uses `/flagConfiguration` under the hood. You do not need to call a generated RTK hook for `/flagConfiguration` directly.
-
-```typescript
-import {useBooleanFlagValue} from "@openfeature/react-sdk";
-import {useTerrenoFeatureFlags, useSelectCurrentUserId} from "@terreno/rtk";
-import {terrenoApi} from "@/store/sdk";
-
-const GatedBanner: React.FC = () => {
-  const userId = useSelectCurrentUserId();
-  useTerrenoFeatureFlags(terrenoApi, {userId, skip: !userId});
-  const showBanner = useBooleanFlagValue("new-ui", false);
-  return showBanner ? <NewUI /> : null;
-};
-```
-
-```typescript
-import {useFeatureFlags} from "@terreno/rtk";
-import {terrenoApi} from "@/store/sdk";
-
-const LegacyStyle: React.FC = () => {
-  const {getFlag, isLoading} = useFeatureFlags(terrenoApi);
-
-  if (isLoading) {
-    return <Spinner />;
-  }
-
-  const showNewUI = getFlag("new-ui");
-
-  return showNewUI ? <NewUI /> : <OldUI />;
-};
-```
-
-### 4b. Live updates (optional)
-
-To push flag changes to open clients without a refresh, pass **`liveUpdates`** when constructing `FeatureFlagsApp` (see `example-backend/src/server.ts`): Mongoose **`FeatureFlag.watch()`** drives a Socket.io broadcast. **MongoDB must run as a replica set** (a single-node replica set is enough); standalone instances cannot use change streams, and the plugin logs a warning if `watch()` fails.
-
-On the client, pass the same Socket.io **client** into `useTerrenoFeatureFlags` / `useFeatureFlags` as `socket`; the hook listens for `featureFlagsChanged` (or `socketEventName`) and refetches `/flagConfiguration`. The event payload is only `{ key: string }` — the same flag keys are already returned to every authenticated user in `/flagConfiguration`, so this is not considered a new exposure.
-
-### 5. Create flags via the admin panel
-
-Navigate to the admin panel in your app. The "Feature Flags" card appears automatically. Create a flag with:
-
-- **Key**: unique identifier, e.g. `new-ui`
-- **Name**: human-readable label
-- **Type**: `boolean` for on/off toggles, `variant` for A/B tests
-- **Enabled**: global kill switch
-- **Rules**: optional targeting (field-based or segment-based)
-- **Rollout Percentage**: gradual rollout for boolean flags (default 100%)
-
-## Migrating from `GET …/evaluate` (OpenFeature)
-
-Terreno's feature-flag stack uses **OpenFeature** (`@terreno/feature-flags` on the server, `@terreno/rtk` on the client). Use this checklist if you upgrade from a Terreno release that only documented `GET …/evaluate`.
-
-### Backend (`@terreno/feature-flags`)
-
-1. Keep **`FeatureFlagsApp`** registered as before; admin CRUD is unchanged.
-2. Prefer authenticated clients calling **`GET {basePath}/flagConfiguration`** — the JSON body matches OpenFeature's static configuration shape (for `TypedInMemoryProvider` on the client).
-3. **`GET {basePath}/evaluate`** still returns the legacy `Record<key, boolean | string | null>` map but is **deprecated** (`Deprecation: true`, `Sunset` header). Migrate direct HTTP or hand-written clients to `/flagConfiguration`, or rely on `@terreno/rtk` hooks below.
-4. **`FeatureFlag`** documents gain optional **`defaultVariant`** (boolean: `"on"` / `"off"`; variant: a key from `variants`). Omitted values are filled on save. For existing databases, run a one-off backfill or reuse the pattern in `example-backend/src/scripts/seed-feature-flags.ts`.
-5. **Live updates (optional):** pass `liveUpdates: { socketIoServer: io | () => io }` to `FeatureFlagsApp`. MongoDB must run as a **replica set** (a single-node replica set is enough) so Mongoose change streams work.
-
-### Frontend (`@terreno/rtk` + OpenFeature)
-
-1. **`useFeatureFlags(terrenoApi, …)`** — no code changes required for the common case; it already uses `/flagConfiguration` and keeps `{ flags, getFlag, getVariant, isLoading, refetch }`.
-2. **OpenFeature React hooks** (`useBooleanFlagValue`, `useStringFlagValue`, `<FeatureFlag>`, …): add **`@openfeature/react-sdk`** and **`@openfeature/web-sdk`** to your app (align versions with `@terreno/rtk` **peerDependencies** and the root **`catalog`**).
-3. Wrap the UI that reads flags in **`<OpenFeatureProvider domain="feature-flags">`** (or the same `domain` you pass into the hook).
-4. After auth, call **`useTerrenoFeatureFlags(terrenoApi, { userId, skip, socket, … })`** once under your Redux `Provider` so OpenFeature is populated before hooks read flag values.
-5. **Regenerate the OpenAPI SDK** after the backend exposes the new route: `cd your-frontend && bun run sdk`. Prefer **`useTerrenoFeatureFlags` / `useFeatureFlags`** over calling a generated `flagConfiguration` hook directly, so domain, cache keys, and optional socket refetch stay consistent.
-
-### Further reading
-
-- [Feature flags reference](../reference/feature-flags.md)
-- [OpenFeature implementation plan](../implementationPlans/feature-flags-openfeature.md)
-
-## Next steps
-
-- See the [reference docs](../reference/feature-flags.md) for the full API, targeting rules, and variant flags
-- See `example-backend/src/server.ts` for a complete working example

package/src/docs/versioned/57.18.0/how-to/add-organizations.md

@@ -1,204 +0,0 @@
-# Add organizations to a Terreno app
-
-Enable organizations only when the app is multi-tenant. Existing single-tenant
-apps can omit every option in this guide.
-
-## 1. Enable organization RBAC
-
-``````typescript
-import {createAccess, terrenoStatements} from "@terreno/api";
-
-export const access = createAccess({
-  connection: mongoose.connection,
-  organizations: true,
-  statements: terrenoStatements,
-  userModel: User,
-});
-
-await access.roles.seedDefaults();
-``````
-
-This adds Membership-based `org-admin` grants and seeds the locked `operator`
-role. It does not change apps that omit `organizations`.
-
-## 2. Mount organization routes
-
-``````typescript
-const app = new TerrenoApp({
-  accessControl: access,
-  organizations: true,
-  userModel: User,
-});
-``````
-
-This mounts `OrgsApp` at `/orgs`. To configure audit handling or a different
-path, pass an options object:
-
-``````typescript
-organizations: {
-  basePath: "/organizations",
-  onOrgAudit: recordOrganizationAudit,
-  settingsSchema: organizationSettingsSchema,
-}
-``````
-
-## 3. Type organization settings
-
-Keep native `Organization` fields unchanged. Put app fields on
-`Organization.settings` with a nested Mongoose schema and a TypeScript
-interface.
-
-1. Declare the settings shape (optional module augmentation):
-
-``````typescript
-// src/types/models/organizationSettingsTypes.ts
-export interface ExampleOrganizationSettings {
-  timezone?: string;
-}
-
-declare module "@terreno/api" {
-  interface OrganizationSettings extends ExampleOrganizationSettings {}
-}
-``````
-
-2. Build the nested schema. Use optional fields or defaults so existing
-organizations still validate:
-
-``````typescript
-// src/models/organizationSettings.ts
-import {createOrganizationSettingsSchema} from "@terreno/api";
-import type {ExampleOrganizationSettings} from "../types/models/organizationSettingsTypes";
-
-export const organizationSettingsSchema = createOrganizationSettingsSchema<ExampleOrganizationSettings>({
-  timezone: {
-    description: "IANA timezone used for organization-local dates",
-    type: String,
-  },
-});
-``````
-
-3. Register before you create or patch organizations (startup and seeds):
-
-``````typescript
-import {registerOrganizationSettings} from "@terreno/api";
-import {organizationSettingsSchema} from "./models/organizationSettings";
-
-registerOrganizationSettings(organizationSettingsSchema);
-``````
-
-Or pass the same schema on `TerrenoApp` / `OrgsApp`:
-
-``````typescript
-new TerrenoApp({
-  accessControl: access,
-  organizations: {settingsSchema: organizationSettingsSchema},
-  userModel: User,
-});
-``````
-
-Read typed settings with `organizationSettingsOf(organization)` or
-`organizationSettingsOf<ExampleOrganizationSettings>(organization)`.
-
-Without a registered schema, `settings` stays Mixed and accepts any object.
-Unknown keys and wrong types fail with **400** `Organization settings are invalid`
-once a schema is registered.
-
-## 4. Scope tenant models
-
-Add `orgScopedPlugin` to models that use ObjectId organization keys. Put
-`orgContextMiddleware({required: true})` before their routes, use
-`OrgQueryFilter` for lists, and overwrite client organization ids during
-create:
-
-``````typescript
-import {
-  authenticateMiddleware,
-  getOrgContext,
-  modelRouter,
-  OrgQueryFilter,
-  orgContextMiddleware,
-  orgScopedPlugin,
-  Permissions,
-  type TerrenoPlugin,
-} from "@terreno/api";
-import type express from "express";
-
-schema.plugin(orgScopedPlugin);
-
-const projectOrgContextPlugin: TerrenoPlugin = {
-  register(expressApp: express.Application): void {
-    expressApp.use(
-      "/projects",
-      authenticateMiddleware(),
-      orgContextMiddleware({required: true})
-    );
-  },
-};
-
-const projectRouter = modelRouter("/projects", Project, {
-  permissions: {
-    create: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
-    delete: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
-    list: [Permissions.IsAuthenticated],
-    read: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
-    update: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
-  },
-  preCreate: (body, _req) => ({
-    ...body,
-    organizationId: getOrgContext()?.organization?._id,
-  }),
-  queryFilter: OrgQueryFilter,
-});
-
-app.register(projectOrgContextPlugin).register(projectRouter);
-``````
-
-For admin CRUD, use `new AdminApp({accessControl: access, organizations:
-true})`. Models with an `organizationId` schema path are scoped automatically,
-except `AuditEvent` (the platform audit log lists without a selected org).
-Admin-window `POST /sync/mutate` and socket `sync:mutate` use the same membership
-check as REST for update and delete when `X-Organization-Id` (HTTP) or
-`organizationId` (socket payload) is set. Admin `createSyncDb({organizationIdProvider})`
-sends that id on every mutate.
-
-`orgScopedPlugin` also makes `organizationId` immutable after the document is
-created. Client PATCH bodies, admin writes, sync updates, and direct Mongoose
-saves that change `organizationId` return HTTP 400 with
-`organizationId cannot be changed`.
-
-## 5. Send organization context
-
-Send `X-Organization-Id` on tenant-scoped requests. `org-admin` callers with
-exactly one administered organization may omit it; Terreno infers that org.
-Operators and superadmins must select an org.
-
-Frontend admin hosts use `OrgContextProvider` + `OrgSwitcher`.
-`useAdminApi` adds the selected organization header automatically.
-
-Disabled organizations are excluded from `/orgs/mine` and cannot be selected as
-tenant context. Operators re-enable them from the organization directory UI or
-with `PATCH /orgs/:id` and `disabled: false` (see
-[How organization tenancy works](../explanation/organizations.md#disabled-organizations)).
-
-Creating or renaming an organization to a name that generates an existing slug,
-including a slug still held by a **soft-deleted** organization, returns **409**
-`Organization name already in use`. `OrgSwitcher` hides itself
-when `/orgs/mine` returns **403** for callers without org-admin memberships.
-
-## Example app accounts
-
-After `bun run backend:seed`, all accounts use password `testpassword123`:
-
-| Account | Access |
-| --- | --- |
-| `operator@example.com` | Platform organization directory; may enter either org |
-| `orgadmin-alpha@example.com` | Org admin for Alpha Workspace |
-| `orgadmin-beta@example.com` | Org admin for Beta Workspace |
-| `test@example.com` | Member of Alpha Workspace |
-| `admin@example.com` / `superadmin@example.com` | Existing example superadmin accounts |
-
-The seed creates Alpha Workspace and Beta Workspace plus two projects in Alpha
-Workspace. Membership rows, not fields on User, are the source of tenant access.
-In-process Better Auth seeding sets `disableRateLimit: true` so production
-preview smoke tests can create all six accounts without hitting Better Auth's
-sign-up limiter.

package/src/docs/versioned/57.18.0/how-to/admin-custom-home.md

@@ -1,34 +0,0 @@
-# Customize the admin home
-
-Home widgets sit in the admin shell. Screen and sidebar rules:
-[Build admin screens](build-admin-screens.md).
-
-Configure home slots on `AdminApp`:
-
-```ts
-new AdminApp({
-  home: {
-    title: "Operations",
-    slots: {
-      contentTop: ["feature-flags-overrides"],
-      main: ["modelStats"],
-      navGlobal: ["scriptRunner"],
-      sidebar: ["versionConfig", "recentActivity"],
-    },
-  },
-});
-```
-
-Built-in IDs include `modelStats`, `modelsGrid`, `scriptRunner`, `versionConfig`, and
-`recentActivity`. Plugins add IDs such as `feature-flags-overrides`.
-
-For an app-specific widget, implement `AdminHomeWidgetProps` and register it:
-
-```tsx
-<AdminProvider widgets={{home: {operationsSummary: OperationsSummary}}} api={api}>
-  <AdminHome api={api} />
-</AdminProvider>
-```
-
-Then place `"operationsSummary"` in a home slot. Unknown IDs render a visible missing-widget
-placeholder in development instead of crashing the dashboard.