@terreno/mcp 57.20.0 → 57.22.0

package/dist/docs/versioned/57.2.0/implementationPlans/upgrade-guides-and-skill.md

@@ -1,167 +0,0 @@
-# Implementation Plan: Upgrade Guides and the `upgrading-terreno` Skill
-
-**Status:** Draft — blocked on PR #869
-**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1013
-**Priority:** High
-**Effort:** Big batch
-**Owner:** unassigned
-**Created:** 2026-07-27
-**Program:** [OSS launch](oss-launch-program.md)
-**Depends on:** [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md), [`oss-governance-baseline`](oss-governance-baseline.md) (changelog)
-**RTK deprecation flag:** **Blocked** — the largest upgrade Terreno will ever ask consumers to perform is RTK → syncdb. The skill and the notes must be built around it.
-
-## Goal
-
-Make upgrading Terreno a solved problem before we ask the public to depend on it. The machinery is half-built: `terreno_get_upgrade_guide` exists and concatenates per-release notes, and a `terreno_upgrade` prompt exists — but only two upgrade notes have ever been written (`0.20.0.md`, `0.21.0.md`) against a current version of 0.26.0. Five releases have no notes, so the tool returns nothing useful for any recent range. There is no `upgrading-terreno` skill; the only upgrade skill in the repo is `upgrading-expo`, which handles the Expo SDK portion and nothing Terreno-specific.
-
-An open-source framework that ships breaking changes in lockstep across eleven packages and cannot tell you what changed is not adoptable.
-
-## Non-Goals
-
-- Upgrading the Expo SDK (delegate to the existing `upgrading-expo` skill — do not duplicate its content).
-- Automated codemods (see [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) question M6 — agent-assisted, not codemod).
-- Changing the lockstep versioning scheme.
-- Retroactively rewriting git history or release notes.
-
-## Blocking questions
-
-**Recorded 2026-07-29** (defaults accepted).
-
-| # | Decision |
-|---|----------|
-| U1 | One consolidated **0.21 → 0.26** upgrade note; per-release notes from next version onward |
-| U2 | Upgrade note required when changelog has **Deprecated / Removed / Changed** (CI-enforced) |
-| U3 | Skill **performs** upgrade with confirmation gate + clean git tree |
-| U4 | **Direct multi-version jump** with sequential fallback on failure |
-| U5 | **Wrap `upgrading-expo`** at the correct point in the sequence |
-| U6 | Publish **deprecation window policy** (≥3 minors until 1.0; align RTK sunset with program P6) |
-
-## Architecture
-
-### Three artifacts
-
-1. **Upgrade notes** (`mcp-server/src/docs/upgrades/<version>.md`) — the data. Consumed by `terreno_get_upgrade_guide`, readable directly, and referenced from the changelog.
-2. **The `upgrading-terreno` skill** — the executor. Wraps note application, dependency bumps, Expo delegation, codegen, and verification.
-3. **A versioning and deprecation policy** (`docs/explanation/versioning-policy.md`) — the promise. What lockstep means, what a minor can break before 1.0, how long deprecations last.
-
-### Upgrade note format
-
-Standardize on the shape the existing notes already use, with required sections so the concatenated output from `terreno_get_upgrade_guide` reads coherently across several versions:
-
-```markdown
-# Upgrading to <version>
-
-**Action required:** Yes | No
-**Affected packages:** @terreno/api, @terreno/ui, ...
-
-## Summary
-## Breaking changes
-### <change title>
-**What changed** / **Why** / **Migration** (before/after code)
-## Deprecations
-## New capabilities
-## Verification
-```
-
-The `Verification` section matters most for automation: it gives the skill a concrete way to confirm each version's upgrade succeeded before moving to the next.
-
-### The upgrade ordering problem
-
-Order is the thing consumers get wrong, and it is not obvious:
-
-```mermaid
-flowchart TD
-  A["1. Clean git tree + branch"]
-  B["2. application_info:<br/>current @terreno/* versions"]
-  C["3. terreno_get_upgrade_guide<br/>current → target"]
-  D["4. Backend packages<br/>api, ai, admin-backend, feature-flags, api-health"]
-  E["5. Backend tests + compile"]
-  F["6. Expo SDK<br/>delegate to upgrading-expo"]
-  G["7. Frontend packages<br/>ui, syncdb, admin-frontend, admin-spa"]
-  H["8. Regenerate typed client"]
-  I["9. Compile + lint + tests"]
-  J["10. Run the app, verify UI"]
-  A --> B --> C --> D --> E --> F --> G --> H --> I --> J
-```
-
-Backend first because the OpenAPI spec is the contract the frontend generates from; regenerating the client against an un-upgraded backend produces a client for the wrong API. Expo before the Terreno frontend packages because `@terreno/ui` pins peer dependencies against Expo's versions.
-
-### Release-process enforcement
-
-The `release` skill currently does not require an upgrade note. Add:
-
-1. A required step: if the release's changelog section contains `Breaking`, `Deprecated`, `Removed`, or `Changed`, write `mcp-server/src/docs/upgrades/<version>.md` before tagging.
-2. A CI check in `repo-policies.yml` that fails a release tag when the note is missing.
-
-Without mechanical enforcement this decays again — that is exactly what happened between 0.21.0 and 0.26.0.
-
-## Models / APIs
-
-No new models. `terreno_get_upgrade_guide`'s behavior with a range containing no notes needs improving: it should say "no notes recorded for 0.22–0.24" rather than returning empty, so an agent does not conclude nothing changed.
-
-## Notifications
-
-An Announcements discussion post per breaking release, per [`public-roadmap-github`](public-roadmap-github.md) Task 5.3.
-
-## UI
-
-None.
-
-## Phases
-
-1. **Backfill** — the consolidated 0.21 → 0.26 note plus the note format and template.
-2. **Policy** — `docs/explanation/versioning-policy.md`.
-3. **Skill** — `upgrading-terreno` with the correct ordering and Expo delegation.
-4. **Enforcement** — release skill step and CI check; improve the tool's empty-range response.
-5. **Validation** — perform a real upgrade of a consumer app using only the skill.
-
-## Feature Flags & Migrations
-
-None.
-
-## Not Included / Future Work
-
-- Codemods.
-- Automatic dependency-bump PRs (Dependabot covers third-party deps, not intra-Terreno lockstep bumps).
-- A compatibility matrix across Expo SDK versions (worth doing once there is more than one supported SDK).
-- Downgrade guidance.
-
-## Files to Create / Modify
-
-**Create**
-
-- `mcp-server/src/docs/upgrades/README.md` (format + template)
-- `mcp-server/src/docs/upgrades/0.26.0.md` (consolidated 0.21 → 0.26)
-- `mcp-server/src/docs/upgrades/<syncdb-version>.md` (owned by the migration IP; referenced here)
-- `docs/explanation/versioning-policy.md`
-- `docs/how-to/upgrade-terreno.md`
-- `.rulesync/skills/upgrading-terreno/SKILL.md`
-- `.rulesync/skills/upgrading-terreno/references/ordering.md`
-
-**Modify**
-
-- `mcp-server/src/tools.ts` (`terreno_get_upgrade_guide` empty-range response)
-- `mcp-server/src/prompts.ts` (`terreno_upgrade` prompt points at the skill)
-- `.rulesync/skills/release/SKILL.md`
-- `.github/workflows/repo-policies.yml`
-- `CHANGELOG.md` (link notes per version)
-- `docs/how-to/README.md`, `docs/explanation/README.md`
-
-## Task List
-
-See [`docs/tasks/upgrade-guides-and-skill.md`](../tasks/upgrade-guides-and-skill.md).
-
-## Acceptance Criteria
-
-- [ ] `mcp-server/src/docs/upgrades/README.md` defines the required note format with a template.
-- [ ] A consolidated note covers everything a consumer must know to move from 0.21.0 to 0.26.0, derived from real release notes and diffs.
-- [ ] `terreno_get_upgrade_guide` for the range 0.21.0 → current returns useful content, and for a range with no recorded notes returns an explicit "no notes recorded" message rather than empty output.
-- [ ] `docs/explanation/versioning-policy.md` states what lockstep versioning means, the pre-1.0 breaking-change policy, and the minimum deprecation window.
-- [ ] The `upgrading-terreno` skill exists with all mirrors committed and enforces a clean git tree before starting.
-- [ ] The skill follows the documented ordering, delegates the Expo SDK portion to `upgrading-expo`, and regenerates the typed client only after the backend is upgraded.
-- [ ] The skill runs compile, lint, and tests between phases and stops on first failure with the failing step named.
-- [ ] On a multi-version jump failure, the skill retries version by version to isolate the breaking version.
-- [ ] The release skill requires an upgrade note when the changelog section contains a breaking, deprecated, removed, or changed entry.
-- [ ] A CI check fails a release tag whose upgrade note is missing when required.
-- [ ] An upgrade of a real consumer app across at least two minor versions succeeds using only the skill, and the transcript is captured.
-- [ ] `bun run mcp:build`, `bun run lint`, and `bun run rules:check` pass.

package/dist/docs/versioned/57.2.0/implementationPlans/web-ssr-and-admin-spa.md

@@ -1,154 +0,0 @@
-# Implementation Plan: Server-Side Rendering for Universal Web (and Admin SPA)
-
-**Status:** Draft — blocking questions open
-**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1017
-**Priority:** Medium
-**Effort:** Epic
-**Owner:** unassigned
-**Created:** 2026-07-27
-**Program:** [OSS launch](oss-launch-program.md) (Wave 2)
-**Depends on:** Expo SDK ≥ 55 (PR [#779](https://github.com/TerrenoLabs/terreno/pull/779) upgrades to SDK 56), [`deployment-foundation`](deployment-foundation.md)
-**RTK deprecation flag:** **Partial** — SSR interacts directly with the data layer. Server-rendered HTML needs data at render time, which is a fundamentally different question for a local-first client than for a request/response client. The data-loading design tasks are `[RTK]` marked and blocked on #869.
-
-## Goal
-
-Give Terreno's web target real server rendering, so a Terreno app can be indexed, shared with usable link previews, and load meaningful first paint without waiting for a JavaScript bundle. Then evaluate moving `@terreno/admin-spa` onto the same mechanism, since it is already served from Express and is the lowest-risk consumer.
-
-The Django/Rails positioning makes this gap conspicuous: both frameworks server-render by default. Today Terreno's web output is `single` — a client-only SPA with one `index.html`, no per-route HTML, and no server rendering. For a framework claiming Django/Rails parity plus universal apps, "your web app is not indexable" is a real objection.
-
-## Non-Goals
-
-- Server-rendering native. SSR is web-only by definition.
-- Replacing `@terreno/api` with Expo Router API routes. The backend stays the backend.
-- React Server Components.
-- Making SSR mandatory. It must be opt-in per app.
-- Upgrading the Expo SDK (PR #779 owns that; this IP depends on it).
-
-## Blocking questions
-
-**Recorded 2026-07-29** (defaults accepted).
-
-| # | Decision |
-|---|----------|
-| S1 | **`static` first, `server` later** (SSR alpha in Expo SDK 55+) |
-| S2 | **`expo-server/adapter/express`** in `@terreno/api` as Terreno-native path; document per-provider adapters |
-| S3 | **Shell-only SSR v1** — hydrate on client |
-| S4 | **`admin-spa` moves to `static` output only** |
-| S5 | **`static` becomes default eventually** (after component audit); `server` opt-in |
-| S6 | **Expo Router API routes narrowly** for OG images / webhooks only |
-
-## Architecture
-
-### Where SSR fits
-
-```mermaid
-flowchart TD
-  U["Browser request"]
-  E["Express app (@terreno/api)"]
-  SSR["expo-server/adapter/express<br/>renders dist/server"]
-  C["dist/client<br/>static assets"]
-  API["modelRouter + auth routes"]
-  ADM["AdminSpaServeApp"]
-  U --> E
-  E -->|"/api/*, /auth/*"| API
-  E -->|"/admin/*"| ADM
-  E -->|"static assets"| C
-  E -->|"everything else"| SSR
-  SSR -->|"HTML"| U
-```
-
-One Express process serves the API, the static client bundle, and server-rendered HTML. Route precedence matters: API and auth routes must match before the SSR catch-all, and the admin mount must not be shadowed.
-
-### Risks specific to React Native Web SSR
-
-This is where the work actually is, and where the estimate could be badly wrong:
-
-| Risk | Detail | Mitigation |
-|------|--------|------------|
-| Components that touch browser APIs at module scope | `@terreno/ui` has ~100 components; any that read `window`, `localStorage`, or `Dimensions` during render or module init will throw during server rendering | Audit and fix; the repo already has SSR-safety precedent (`typeof window` checks in the client storage layer) |
-| Fonts and styles | Nunito/Titillium Web loading and `react-native-web` style injection must produce correct first paint without a flash of unstyled content | Verify style extraction; may need explicit critical-CSS handling |
-| Theme and provider hydration | `TerrenoProvider` computes a theme; server and client must agree or React logs hydration mismatches | Ensure deterministic theme resolution; no `Date.now()` or random values in the render path |
-| Auth-dependent rendering | The server does not know who the user is without reading a session; rendering a logged-in shell then hydrating to logged-out causes visible flicker | v1: always render the unauthenticated shell (S3 option A) |
-| Native-only dependencies | Packages that import native modules at the top level break the server bundle | Audit; use platform-specific extensions |
-| Local-first client on the server | The syncdb client assumes IndexedDB and Web Crypto, neither of which exists on the server | The client must not initialize during server render; needs an explicit guard verified after #869 |
-
-The last row is the one that could invalidate the plan, and it cannot be assessed until #869 merges. **Phase 0 exists to answer it before committing to the rest.**
-
-### `admin-spa` as the proving ground
-
-`@terreno/admin-spa` is an Expo Router web app already served from Express via `AdminSpaServeApp`. Moving it to `static` output is a contained experiment: no SEO requirement, one known consumer (`example-backend`), an existing integration test workflow (`admin-spa-integration.yml`), and an authenticated surface where the auth-flicker problem is bounded. If `static` output works there, the pattern generalizes.
-
-## Models / APIs
-
-No new models. `AdminSpaServeApp` gains options for the output mode and the server bundle path. Route precedence in `TerrenoApp`/`setupServer` may need an explicit ordering guarantee so the SSR catch-all cannot shadow API routes.
-
-## Notifications
-
-None.
-
-## UI
-
-No new components. Existing `@terreno/ui` components may need SSR-safety fixes — those are bug fixes, not features, and each needs a test that renders the component in a server-like environment without `window`.
-
-## Phases
-
-0. **Feasibility spike** — after SDK ≥ 55 and #869, attempt `static` output on `example-frontend` and record every failure. Decide go/no-go and correct this plan. **Do not proceed without this.**
-1. **SSR-safety audit and fixes** — make `@terreno/ui` render without browser globals; add a server-render test harness.
-2. **`static` output for `admin-spa`** — prove the pattern on the contained consumer.
-3. **`static` output for `example-frontend`** — the reference implementation plus documentation.
-4. **`server` output with the Express adapter** — SSR through `@terreno/api`, route precedence, deployment implications.
-5. **Data loading design** — a separate design pass on `useLoaderData` versus local-first reconciliation. May become its own IP.
-6. **Documentation and defaults** — how-to, explainer, and the decision on whether `static` becomes the default.
-
-## Feature Flags & Migrations
-
-- Output mode is per-app configuration in the Expo app config, not a runtime flag.
-- `AdminSpaServeApp` must keep serving existing `single`-output builds so consumers upgrading Terreno without changing their admin build are unaffected.
-- Changing the recommended default (S5) is a breaking change for consumers who copied the bootstrap config; it needs an upgrade note.
-
-## Not Included / Future Work
-
-- React Server Components.
-- Streaming SSR.
-- Incremental static regeneration.
-- Server-rendering authenticated, personalized content (depends on Phase 5).
-- Edge-runtime adapters (`workerd`, Netlify Edge) — the adapters exist upstream; document them once the Express path is proven.
-
-## Files to Create / Modify
-
-**Create**
-
-- `docs/how-to/enable-web-ssr.md`
-- `docs/explanation/web-rendering-modes.md`
-- `ui/src/__tests__/serverRender.test.tsx` (server-render harness)
-- `admin-spa/app.config.ts` changes plus a server entry if `server` output is adopted
-
-**Modify**
-
-- `example-frontend/app.json` (output mode)
-- `admin-spa/app.json` / `app.config.ts`
-- `admin-spa/src/**` (SSR-unsafe code)
-- `ui/src/**` (SSR-safety fixes)
-- `api/src/adminSpaServeApp.ts` (or wherever `AdminSpaServeApp` lives — confirm the path) for output-mode support
-- `api/src/expressServer.ts` / `terrenoApp.ts` (route precedence)
-- `docs/explanation/deployment-baseline.md` (update the output-mode table)
-- `.github/workflows/admin-spa-integration.yml`
-
-## Task List
-
-See [`docs/tasks/web-ssr-and-admin-spa.md`](../tasks/web-ssr-and-admin-spa.md).
-
-## Acceptance Criteria
-
-- [ ] The Phase 0 spike produced a written feasibility report listing every failure encountered with `static` output, and an explicit go/no-go with this plan corrected accordingly.
-- [ ] Every `@terreno/ui` component renders in a server-like environment without `window`, `document`, or `localStorage`, verified by an automated test.
-- [ ] `admin-spa` builds and serves correctly with `static` output through `AdminSpaServeApp`, and `admin-spa-integration.yml` passes.
-- [ ] `AdminSpaServeApp` still serves an existing `single`-output build unchanged.
-- [ ] `example-frontend` builds with `static` output, produces per-route HTML, and every route returns HTML containing meaningful content (verified by fetching a route with JavaScript disabled).
-- [ ] No React hydration mismatch warnings in the console on any `example-frontend` route.
-- [ ] If Phase 4 proceeds: `server` output renders through the Express adapter inside `@terreno/api`, API and auth routes take precedence over the SSR catch-all (verified by tests), and the admin mount is not shadowed.
-- [ ] The syncdb client does not attempt to initialize during server render, verified by a test.
-- [ ] `docs/explanation/web-rendering-modes.md` explains all modes with honest tradeoffs and states which Terreno supports.
-- [ ] `docs/how-to/enable-web-ssr.md` takes a reader from `single` to their chosen mode, including the deployment change required.
-- [ ] Deployment guides for both Vercel and GCP are updated for whichever modes ship.
-- [ ] `bun run lint`, `bun run compile`, `bun run ui:test`, and `bun run admin-spa:test` all pass.

package/dist/docs/versioned/57.2.0/reference/README.md

@@ -1,33 +0,0 @@
-# Reference
-
-Technical reference for Terreno packages and APIs. Information-oriented, precise descriptions.
-
-## Packages
-
-- [@terreno/api](api.md) — modelRouter, auth, permissions, setupServer
-- [@terreno/ui](ui.md) — Components, theming, layout
-- [@terreno/syncdb](syncdb.md) — Local-first data layer (reads, writes, offline sync)
-- [@terreno/ai](ai.md) — AI service, GPT routes, Langfuse integration
-- [@terreno/admin-backend](admin-backend.md) — Auto-generated admin CRUD endpoints
-- [@terreno/admin-frontend](admin-frontend.md) — Admin panel UI components
-- [@terreno/admin-spa](admin-spa.md) — Standalone admin SPA + Express serve plugin
-- [@terreno/api-health](api-health.md) — Health check TerrenoPlugin
-- [@terreno/comms](comms.md) — Pluggable mail, SMS, push, and verification providers
-- [@terreno/feature-flags](feature-flags.md) — Feature flags and A/B testing plugin
-- [@terreno/mcp](mcp-server.md) — AI coding assistant integration (MCP)
-- [@terreno/test](test.md) — Bun test helpers and in-memory MongoDB
-
-## Migrating from RTK
-
-`@terreno/rtk` is deprecated for **data synchronization**. New apps should use [`@terreno/syncdb`](syncdb.md). Existing RTK consumers: follow [Migrate from @terreno/rtk to @terreno/syncdb](../how-to/migrate-rtk-to-syncdb.md). Archived RTK reference: [legacy/rtk.md](legacy/rtk.md).
-
-## Configuration
-
-- [Environment Variables](environment-variables.md) — Complete environment variable reference for all packages
-
-## Other references
-
-- [Lifecycle plugin](lifecycle-plugin.md) — Grow/Pick/Roast/Brew/Taste contracts, results, and transitions
-- [Install agent skills](../how-to/install-agent-skills.md) — Published `skills/` tree for `npx skills`
-- Root [package.json](https://github.com/TerrenoLabs/terreno/blob/master/package.json) — Workspace scripts and catalog
-- Per-package `package.json` in each package directory — Commands and dependencies

package/dist/docs/versioned/57.2.0/reference/admin-backend.md

@@ -1,187 +0,0 @@
-# @terreno/admin-backend
-
-Backend plugin that auto-generates admin CRUD endpoints for Mongoose models. Works with `@terreno/admin-frontend` to provide a complete admin panel solution.
-
-## Quick Start
-
-``````typescript
-import {AdminApp} from "@terreno/admin-backend";
-import {User, Todo} from "./models";
-
-const admin = new AdminApp({
-  basePath: "/admin",
-  models: [
-    {
-      model: User,
-      routePath: "/users",
-      displayName: "Users",
-      listFields: ["email", "name", "admin"],
-      defaultSort: "-created",
-    },
-    {
-      model: Todo,
-      routePath: "/todos",
-      displayName: "Todos",
-      listFields: ["title", "completed", "ownerId"],
-    },
-  ],
-});
-
-admin.register(app);
-``````
-
-This creates:
-- `GET /admin/config` — Model metadata endpoint
-- Standard CRUD routes for each model at `{basePath}{routePath}`
-- All routes protected with `Permissions.IsAdmin`, or fine-grained RBAC when `accessControl` is set
-
-## AdminApp Options
-
-``````typescript
-interface AdminOptions {
-  models: AdminModelConfig[];
-  basePath?: string;  // Default: "/admin"
-}
-
-interface AdminModelConfig {
-  model: Model<any>;
-  routePath: string;      // e.g., "/users"
-  displayName: string;    // e.g., "Users"
-  listFields: string[];   // Fields shown in table
-  defaultSort?: string;   // Default: "-created"
-}
-``````
-
-## Generated Routes
-
-For each model, creates standard modelRouter CRUD endpoints:
-
-- `GET {basePath}{routePath}` — List (paginated, sortable)
-- `POST {basePath}{routePath}` — Create
-- `GET {basePath}{routePath}/:id` — Read
-- `PATCH {basePath}{routePath}/:id` — Update
-- `DELETE {basePath}{routePath}/:id` — Delete
-
-## Config Endpoint
-
-`GET {basePath}/config` returns metadata for all registered models:
-
-``````typescript
-{
-  models: [
-    {
-      name: "User",
-      routePath: "/admin/users",
-      displayName: "Users",
-      listFields: ["email", "name", "admin"],
-      defaultSort: "-created",
-      fields: {
-        email: {
-          type: "string",
-          required: true,
-          description: "User email address"
-        },
-        admin: {
-          type: "boolean",
-          required: false,
-          default: false
-        }
-      }
-    }
-  ]
-}
-``````
-
-Field metadata includes:
-- `type` — Field type (string, number, boolean, date, objectid, etc.)
-- `required` — Whether field is required
-- `description` — From schema (ensure all fields have descriptions!)
-- `enum` — Enum values if applicable
-- `default` — Default value
-- `ref` — Referenced model name for ObjectId refs
-
-## Permissions
-
-`admin:access` is the only permission that opens the admin page. `GET /admin/config` returns 403
-without it. Script, configuration, RBAC, and per-model permissions never grant entry on their own.
-
-Without `accessControl`, that same page gate uses `Permissions.IsAdmin` (`user.admin`).
-
-With `accessControl`, each model can use a standard admin resource with three actions:
-
-| Action | Access |
-| --- | --- |
-| `read` | List, search, and read any record |
-| `write` | Create, update, bulk-update, and delete any record |
-| `writeOwned` | Create records and update/delete records accepted by the ownership helper |
-
-Declare an `admin<ModelName>` statement and optionally customize ownership:
-
-```typescript
-import {ADMIN_MODEL_ACCESS} from "@terreno/api";
-import {adminOwnedBy, AdminApp} from "@terreno/admin-backend";
-
-const statements = {
-  adminForm: ADMIN_MODEL_ACCESS,
-  adminScreen: ["formReports"],
-} as const;
-
-modelRouter("/forms", Form, {
-  admin: {
-    adminAccess: {isOwned: adminOwnedBy("staffId")},
-    displayName: "Forms",
-    listFields: ["title", "staffId"],
-  },
-  // ...
-});
-
-new AdminApp({
-  accessControl,
-  customScreens: [{
-    adminAccess: {resource: "adminScreen", action: "formReports"},
-    displayName: "Form reports",
-    name: "form-reports",
-  }],
-});
-```
-
-`adminAccess.resource` overrides the default `admin<ModelName>` name. Use
-`adminAccess.authorize({action, instance, user})` when a model or screen needs a completely
-custom decision. The callback replaces the standard read/write/write-owned decision, while
-`admin:access` still protects the admin shell. Every action is authorized without an instance
-first (router and `/admin/config` probes). Return `true` for `read` / `update` / `delete` when
-`instance` is missing if some records may be allowed; the loaded record is authorized next.
-`create` is also checked again with the request body.
-
-`writeOwned` can create any new record; `isOwned` is only applied to update and delete.
-
-The config endpoint is caller-specific: models and custom screens without read access are omitted,
-writable controls are disabled, and `platformTools` reports visibility for Scripts, Roles, Version,
-and Configuration. Built-in tools use the existing editable permissions:
-
-- Scripts: `admin:runScripts` or `admin:viewBackgroundTasks`
-- Roles: `rbac:read`
-- Version and Configuration: `configuration:read`
-- Audit Log and Feature Flags: their model's admin `read` permission
-
-Read and list responses include `_adminCapabilities.update` and
-`_adminCapabilities.delete` for each record. This keeps `writeOwned` forms and row controls
-read-only for records the current user does not own. Script metadata separately exposes run and
-history permissions so a history-only role never receives an enabled Run control.
-
-**Important:** Only expose models that should be editable via admin panel. Avoid sensitive internal models.
-
-## Best Practices
-
-- Add `description` to all model fields — flows through to admin UI
-- Use `listFields` to control which columns appear in table views
-- Set `defaultSort` to control initial ordering (usually `"-created"`)
-- Keep `routePath` simple and pluralized (`"/users"`, `"/todos"`)
-
-## Integration
-
-Works seamlessly with `@terreno/admin-frontend`. The frontend uses the `/admin/config` endpoint to:
-- Discover available models
-- Generate forms with proper field types
-- Render references as clickable links
-- Validate required fields

package/dist/docs/versioned/57.2.0/reference/admin-config.md

@@ -1,51 +0,0 @@
-# Admin configuration reference
-
-`AdminConfig` is the `admin` object accepted by `modelRouter`.
-
-| Field | Django admin analogue | Description |
-| --- | --- | --- |
-| `displayName` | `verbose_name_plural` | Required navigation and page label. |
-| `listFields` | `list_display` | Required allowlist of list/form fields. |
-| `listDisplay` | `list_display` | Optional visible list columns. |
-| `listDisplayLinks` | `list_display_links` | Columns linking to the edit screen. |
-| `searchFields` | `search_fields` | String fields matched by the list search box as a case-insensitive partial query. |
-| `sortableFields` | `sortable_by` | Columns allowed to sort. |
-| `defaultSort` | `ordering` | Initial sort field(s), using `-field` for descending. |
-| `pageSize` | `list_per_page` | Rows per page. |
-| `filters` | `list_filter` | Filter drawer definitions. |
-| `fieldsets` | `fieldsets` | Ordered collapsible form groups. |
-| `fieldOrder` | `fields` | Flat form order when fieldsets are absent. |
-| `readonlyFields` | `readonly_fields` | Visible, non-editable fields. |
-| `hiddenFields` | `exclude` | Fields omitted from admin forms and responses. |
-| `excludeFields` | `exclude` | Additional response-scrubbing fields. |
-| `autocompleteFields` | `autocomplete_fields` | Reference fields using async search. |
-| `fieldOverrides` | `formfield_overrides` | Per-field label/help/widget metadata. |
-| `adminPermissions` | `has_*_permission` | Admin-route permission method overrides. |
-| `adminFilter` | `get_queryset` | Server-enforced query constraint. |
-| `actions` | `actions` | Declarative bulk-patch/background actions. |
-| `bulkPatchAllowlist` | — | Fields accepted by bulk patch. |
-| `recordTitleField` | `__str__` | Field used for edit-page titles. |
-| `group` | `app_label` | Navigation group. |
-| `icon` | — | Navigation icon name. |
-| `realtime` | — | Emit scrubbed admin change events. |
-| `includeDeleted` | — | Reserved compatibility option. |
-
-## Supporting types
-
-`AdminFilter` has `field`, `kind`, and optional `label`. Kinds are `boolean`, `text`, `ref`,
-`dateRange`, and `choice`; refs add `refModel`, choices add `{label,value}[]`.
-
-`AdminFieldset` has `title`, `fields`, optional `description`, and optional `collapsed`.
-
-`AdminAction` has `id`, `label`, optional `confirm`, `background`, and `patchKeys`.
-
-`AdminContribution` may provide `models`, `customScreens`, `homeWidgets`, and `scripts`.
-Model contributions contain `model`, `routePath`, and `admin`. Duplicate `routePath`s
-throw for registered routers; the same Mongoose model at two paths gets unique config
-`name`s so the admin UI can route to each.
-
-## Legacy migration
-
-Move each object from `AdminApp.models` to the model's `modelRouter({admin: ...})`; remove
-`model` and `routePath` from the nested config because those come from the router registration.
-Plugin-owned models should come from `plugin.adminContribution()` instead of host duplication.