@terreno/mcp 57.2.0 → 57.4.0

package/src/docs/versioned/next/README.md

@@ -1,6 +1,24 @@
 # Terreno Documentation
 
-Documentation for the Terreno monorepo: shared packages for full-stack applications with React Native and Express/Mongoose.
+**Terreno is Django/Rails for TypeScript — with universal app support.**
+
+Terreno is Django/Rails for TypeScript — a batteries-included, full-stack
+framework where the undifferentiated 80% of an app is already written. On the
+backend you get Mongoose models, auto-generated REST APIs, permissions, an admin
+panel, authentication, and an AI service. On the frontend you get one universal
+app — a single React Native codebase that ships to iOS, Android, and web. It is
+built to be driven by AI coding agents from the first prompt to a production
+deploy.
+
+- Batteries included — auth, CRUD APIs, admin, permissions, AI, realtime,
+  feature flags, and consent are already built, so your code is business logic.
+- Universal by default — one React Native codebase ships to iOS, Android, and
+  web. Not a web framework with a mobile bolt-on.
+- AI-native — agents are a first-class client of the framework, not an
+  afterthought.
+
+Canonical copy, language rules, and the Django/Rails comparison:
+[Positioning](explanation/positioning.md).
 
 ## Structure
 
@@ -14,30 +32,37 @@ Documentation for the Terreno monorepo: shared packages for full-stack applicati
 
 | Package | Description |
 |---------|-------------|
-| [@terreno/api](reference/api.md) | REST API framework (Express/Mongoose) |
-| [@terreno/ui](reference/ui.md) | React Native UI component library |
-| [@terreno/syncdb](reference/syncdb.md) | Local-first data layer (offline sync, conflicts) |
-| [@terreno/ai](reference/ai.md) | AI service, GPT routes, request logging |
-| [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin |
-| [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens |
-| [@terreno/admin-spa](reference/admin-spa.md) | Standalone admin SPA + Express serve plugin |
-| [@terreno/api-health](reference/api-health.md) | Health check endpoint plugin |
+| [@terreno/api](reference/api.md) | REST API framework for Express/Mongoose (modelRouter, auth, OpenAPI) |
+| [@terreno/test](reference/test.md) | Shared Bun test helpers, MongoDB preload utilities, and HTTP fixtures |
+| [@terreno/ui](reference/ui.md) | React Native UI component library for iOS, Android, and web |
+| [@terreno/syncdb](reference/syncdb.md) | Local-first data layer with TinyBase, durable outbox, and delta sync |
+| [@terreno/ai](reference/ai.md) | Provider-agnostic AI service with streaming chat, request logging, and admin tools |
+| [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin for `@terreno/api` |
+| [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens for `@terreno/api` backends |
+| [@terreno/admin-spa](reference/admin-spa.md) | Standalone admin SPA (Expo Router web) plus Express serve plugin |
+| [@terreno/api-health](reference/api-health.md) | Health check plugin for `@terreno/api` |
+| [@terreno/announcements](reference/announcements.md) | In-app product update announcements |
 | [@terreno/comms](reference/comms.md) | Pluggable communications providers |
-| [@terreno/feature-flags](reference/feature-flags.md) | Feature flags and A/B testing plugin |
-| [@terreno/mcp](reference/mcp-server.md) | AI coding assistant integration (MCP) |
-| [@terreno/test](reference/test.md) | Bun test helpers and in-memory MongoDB |
+| [@terreno/feature-flags](reference/feature-flags.md) | Feature flags and A/B testing plugin for `@terreno/api` |
+| [@terreno/mcp](reference/mcp-server.md) | MCP server that gives coding agents Terreno docs, codegen tools, and prompts |
+| [create-terreno-app](reference/create-terreno-app.md) | CLI to scaffold a deployable full-stack Terreno app (`bunx create-terreno-app`) |
 
 ### Legacy
 
 | Package | Description |
 |---------|-------------|
-| [@terreno/rtk](reference/legacy/rtk.md) (deprecated) | RTK Query utilities — superseded by syncdb for data sync; still used for OpenAPI SDK, auth, and feature flags during migration |
+| [@terreno/rtk](reference/legacy/rtk.md) (deprecated for data sync) | OpenAPI SDK, Better Auth Redux, and feature flags for Terreno frontends |
 
 **Migrating from RTK?** See [How to migrate from @terreno/rtk to @terreno/syncdb](how-to/migrate-rtk-to-syncdb.md).
 
 ## Quick links
 
 - [Getting started](tutorials/getting-started.md)
+- [Create a Terreno app](how-to/create-a-terreno-app.md)
+- [Positioning](explanation/positioning.md)
+- [How admin interfaces are shaped](explanation/admin-interface.md)
+- [Build admin screens](how-to/build-admin-screens.md)
 - [Local-first data](explanation/local-first-data.md)
 - [AGENTS.md](../AGENTS.md) — Onboarding context for AI assistants
 - [ROADMAP.md](../ROADMAP.md) — Public roadmap
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — Setup, tests, and pull requests

package/src/docs/versioned/next/explanation/README.md

@@ -11,13 +11,26 @@ Understanding-oriented documentation: concepts, architecture, and context.
 ## Contents
 
 - [Local-first data](local-first-data.md) — Why the local store is the UI source of truth
+- [Planning plugins](planning-plugins.md) — How the lifecycle and scan plugins divide discovery from delivery
 - [Loop engineering](loop-engineering.md) — Fresh-invocation lifecycle, state, evidence, and orchestration boundaries
+- [GitHub issue lifecycle](../how-to/github-issue-lifecycle.md) — Pick-ready issues and plan comments for Pick/Roast
 - [Install agent skills](../how-to/install-agent-skills.md) — `npx skills add FlourishHealth/terreno`
 - [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
-- [Authentication architecture](authentication.md) — How JWT, OAuth, and token refresh work
+- [Authentication architecture](authentication.md) — Better Auth, JWT, and optional MCP service tokens
+- [Organization tenancy](organizations.md) — Optional Membership-backed tenancy, context, and isolation boundaries
 - [Configuration system](configuration-system.md) — Runtime configuration with database persistence
-- [Dependency management](dependency-management.md) — Dependabot, auto-merge, and security practices
+- [Dependency management](dependency-management.md) — Catalog pins, exercise tests, fingerprint freeze
 - [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
 - [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter
+- [Explicit `any` policy](explicit-any-policy.md) — Require rationale markers and ratchet usage per file
 - [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels
+- [Production source rules](source-rules.md) — Arrow functions, Luxon, APIError, logging, findOne, `as any`
 - [Positioning](positioning.md) — Canonical copy blocks and the honest Django/Rails comparison
+- [Versioning policy](versioning-policy.md) — Lockstep `@terreno/*` versions, pre-1.0 breaks, deprecation window
+- [How admin interfaces are shaped](admin-interface.md) — Screens, sidebar, `apiBase` vs `routeBase`
+- [Admin plugin frontend widgets](admin-plugin-frontend.md) — Widget IDs from backend plugins
+- [Consent admin migration](admin-consent-migration.md) — Which consent screens stay hand-written
+- [Public roadmap process](roadmap-process.md) — GitHub roadmap vs Linear execution
+- [Example app coverage](example-coverage.md) — Which framework capabilities the example apps exercise
+- [Repository settings](repository-settings.md) — Maintainer GitHub settings that cannot be committed
+- [Why Terreno owns chart SVG](charts.md) — Owned `react-native-svg` vs victory-native

package/src/docs/versioned/next/explanation/admin-interface.md

@@ -0,0 +1,84 @@
+# How admin interfaces are shaped
+
+Prefer existing admin packages over a new dashboard. `@terreno/admin-backend`
+exposes `/admin/config` plus per-model CRUD. `@terreno/admin-frontend` renders that
+config as a sidebar, home dashboard, tables, and forms. `@terreno/admin-spa` is the
+same UI served from the API origin.
+
+Consumer screens are thin routes. They wrap `AdminProvider` + `AdminShellLayout` and
+let `AdminHome`, `AdminScreenRouter`, `AdminModelTable`, and `AdminModelForm` do the
+work. Hand-write a route only when the generic table/form cannot express the
+workflow (consent publish, comms message detail, password-on-create).
+
+## Two hosts
+
+| Host | When to use | Route prefix (`routeBase`) | API prefix (`apiBase`) | Fetch auth |
+| --- | --- | --- | --- | --- |
+| Embedded (`example-frontend/app/admin`) | Admin lives inside the product Expo app | `"/admin"` | `"/admin"` | `getAuthHeaders` → Bearer, plus `apiOrigin` = RTK `baseUrl` so RPC does not hit the Expo origin |
+| Standalone (`@terreno/admin-spa`) | Same-origin console served by `AdminSpaServeApp` | `""` (SPA root; mount is `/console`) | `"/admin"` | `credentials="same-origin"`; empty `getAuthHeaders`; omit `apiOrigin` |
+
+`apiBase` is the HTTP path for `/config` and CRUD. `routeBase` is the Expo Router
+prefix the sidebar concatenates onto `/{model.name}` and `/{screen.name}`. Mixing
+them puts nav on the wrong URL. Embedded hosts must also set `apiOrigin` (the
+backend origin, e.g. `http://localhost:4000`) on `AdminProvider`. Native `fetch`
+RPC uses that origin to prefix `/admin/config` and `/rbac/roles`. Do not put the
+origin in `apiBase` — that would rewrite in-app navigation.
+
+## Screen kinds
+
+| Kind | Source of truth | Frontend |
+| --- | --- | --- |
+| Model changelist / form | `modelRouter({admin: ...})` or plugin `adminContribution()` | `AdminScreenRouter` → `AdminModelTable` / `AdminModelForm` (list filters live on `DataTable`, not a side drawer) |
+| Custom screen | `AdminApp.customScreens` or plugin `customScreens` (`name` + `displayName`) | Matching `AdminProvider.widgets.screens[name]`, or a dedicated Expo route |
+| Platform tool | Built-in (`scripts`, `roles`, `version`, `configuration`, audit log, feature flags, jobs) | Sidebar **Platform** section; visibility from `/admin/config.platformTools` (jobs is lifted from `customScreens`) |
+| Home widget | `AdminApp.home.slots` IDs | `AdminProvider.widgets.home` (built-ins already registered) |
+
+`GET /admin/config` is caller-specific. Models and custom screens without read
+access are omitted. The sidebar must not invent links the config did not return.
+
+## Navigation chrome
+
+`AdminShell` (via `AdminShellLayout`) always owns the sidebar. Do not add a second
+app-level nav inside admin.
+
+Order in the rail:
+
+1. **Home** → `{routeBase}/`
+2. **Models** grouped by `admin.group` (ungrouped models land in **General**). Custom screens with `group` render inside the matching group **before** model links for that group. A grouped screen with no models still gets its own group heading.
+3. **Screens** — only `customScreens` **without** `group` (plus optional host extras)
+4. **Platform** — Scripts (`/__scripts`), Migrations (`/__migrations` when
+   `migrations.enabled`), Roles, Version, Audit Log, Feature Flags, Jobs, Configuration
+
+Audit log and Feature Flags are models, but the shell lifts them into Platform so
+operators do not hunt for them among business collections. The Platform Audit Log
+row is `AuditEvent` when `AuditApp` is registered. `isAuditLogModel` also matches
+legacy `AdminAuditLog`, `audit-log`, and `audit-events` names. Jobs is a custom
+screen (`name: "jobs"`); the shell lifts it the same way.
+
+Below 768px the rail becomes a hamburger drawer. The main column is a body-style
+canvas (`neutral-050`). Nested `Page` screens use `color="transparent"` and
+`padding={0}` so cards sit on that canvas. Custom screens wrap content in
+`AdminScreenPage`; the back arrow uses `router.push(routeBase)` rather than
+`router.back()` because sidebar clicks do not always leave history on web.
+
+## Where code goes
+
+| Concern | Location |
+| --- | --- |
+| Which models appear | `modelRouter` `admin` block, or plugin `adminContribution()` |
+| Extra non-CRUD pages | `AdminApp.customScreens` + `widgets.screens` with the **same** `name`. Optional `group` places the screen in that sidebar group (see **Models** above). |
+| Home dashboard composition | `AdminApp.home.slots` |
+| Field widgets | `admin.fieldOverrides.widget` + `widgets.fields` |
+| Expo files | `app/admin/_layout.tsx` (shell once) or per-route shell in admin-spa |
+| Dedicated extra segments (`/comms/:id`) | Explicit Expo files so `[model]/[id]` does not treat them as generic forms |
+| Data fetching | REST remains membership/search/sort/pagination. String `_id` models with `adminBroadcast` overlay TinyBase and write through syncdb when the host passes a window client + fetch auth. Framework RPC uses host-bound fetch; ObjectId/API-only CRUD keeps RTK compatibility in Terreno 57. |
+
+## Related
+
+- [Build admin screens](../how-to/build-admin-screens.md)
+- [Add a model to the admin](../how-to/admin-add-model.md)
+- [Customize the admin home](../how-to/admin-custom-home.md)
+- [Add a custom admin field widget](../how-to/admin-custom-widget.md)
+- [Admin plugin frontend widgets](admin-plugin-frontend.md)
+- [admin-frontend reference](../reference/admin-frontend.md)
+- [admin-config reference](../reference/admin-config.md)

package/src/docs/versioned/next/explanation/admin-plugin-frontend.md

@@ -1,11 +1,14 @@
 # Admin plugin frontend widgets
 
+Screen layout, sidebar order, and host wiring: [How admin interfaces are
+shaped](admin-interface.md) and [Build admin screens](../how-to/build-admin-screens.md).
+
 Backend plugins contribute stable widget IDs through `adminContribution()`. Their React
 implementations ship from `@terreno/admin-frontend`, under `src/widgets/`.
 
 This keeps the first-party integration in one frontend package and avoids making backend-only
 packages depend on React Native. The built-in registry includes consent field widgets, feature
-flag home widgets, and Documents/AI custom screens. Hosts can override any ID through
+flag home widgets, and Documents/AI/Comms custom screens. Hosts can override any ID through
 `AdminProvider.widgets`.
 
 Third-party plugins should publish their own frontend package and ask the host to spread its

package/src/docs/versioned/next/explanation/ai-workflows.md

@@ -28,10 +28,10 @@ Analyzes code diffs after each merge to identify:
 **Purpose:** Keeps AI assistant rules synchronized with codebase changes
 
 Maintains the single source of truth in `.rulesync/rules/` and ensures:
-- `.cursorrules` (Cursor IDE)
-- `.windsurfrules` (Windsurf IDE)
-- `AGENTS.md` (Claude Code, Copilot)
+- `.cursor/rules/`, skills, agents, and hooks (Cursor)
+- `CLAUDE.md`, `.claude/rules/`, skills, agents, and hooks (Claude Code)
 - `.github/copilot-instructions.md` (GitHub Copilot)
+- Native hooks for Codex CLI, Copilot CLI, Antigravity CLI, and Devin
 
 **Workflow:**
 1. Detects package changes, new APIs, or convention updates
@@ -43,6 +43,19 @@ Maintains the single source of truth in `.rulesync/rules/` and ensures:
 
 ### Code Quality Workflows
 
+#### Agent quality and static-analysis hooks
+**Trigger:** Agent file edit, agent stop, Git pre-commit, and pull request  
+**Purpose:** Prevents lint, typecheck, unused-code, and dependency-graph regressions
+
+Rulesync generates native hooks from `.rulesync/hooks.json`. Biome checks changed files
+after edits and staged files before commits. At agent stop,
+`.rulesync/hooks/quality-check.sh` runs lint, TypeScript compilation, Knip, and
+dependency-cruiser. It keeps stdout machine-readable for each host and prevents
+retry-triggered Stop hooks from rerunning the commands.
+
+Existing findings are ratcheted so the checks reject new debt without requiring unrelated
+cleanup. See [Static analysis](static-analysis.md).
+
 #### Daily JSDoc Improver
 **Trigger:** Daily schedule + push to master  
 **Purpose:** Systematically improves JSDoc documentation across the codebase
@@ -177,7 +190,8 @@ Ensures preview environments don't accumulate and waste resources.
 
 ### Single Source of Truth
 - **Documentation:** Code is truth, docs must reflect it
-- **Rules:** `.rulesync/rules/` is truth, generated files derive from it
+- **Agent configuration:** `.rulesync/rules/`, `.rulesync/skills/`, and
+  `.rulesync/hooks.json` are truth; generated files derive from them
 - **Tests:** Implementation is truth, tests verify it
 
 ### Fail Fast
@@ -240,6 +254,17 @@ Workflow definitions live in `.github/workflows/*.md` files. These are compiled
 - **Review draft PRs** — Workflow-generated PRs may contain useful improvements
 - **Report issues** — If a workflow behaves unexpectedly, open an issue
 
+## Reference docs vs agent rules
+
+`docs/reference/` is descriptive documentation for humans. `.rulesync/rules/` is prescriptive guidance for agents. Both are maintained on purpose.
+
+A change to a package's public API must update:
+
+1. The `docs/reference/<pkg>.md` page (and the package README if the quick start changed)
+2. The matching `.rulesync/rules/<pkg>/00-*.md` source, then `bun run rules`
+
+The docs-audit workflow flags a missing README or reference page and obvious internal leakage. It cannot fully verify that reference prose and agent rules still agree — reviewers still check both when the public surface changes.
+
 ## Troubleshooting
 
 ### Workflow doesn't run when expected

package/src/docs/versioned/next/explanation/authentication.md

@@ -12,6 +12,8 @@ Set `AUTH_PROVIDER=better-auth` and register `BetterAuthApp` on the server. On t
 
 Both systems can run in parallel during migration (`AUTH_PROVIDER` selects the primary path; legacy JWT routes stay available).
 
+**MCP service tokens** are a third, opt-in credential. They authenticate the consumer app's `POST /mcp` only. They are not Better Auth sessions, not JWTs, and not a REST personal-access-token. Enable them with `mcpServiceTokens` on `TerrenoApp`. Operator steps: [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md).
+
 ## When to choose which
 
 | Choose Better Auth | Stay on JWT (legacy) |
@@ -35,7 +37,10 @@ Modern session-based authentication with built-in social OAuth support.
 3. Backend redirects to OAuth provider or validates credentials
 4. Better Auth creates session in MongoDB
 5. Frontend receives session cookie (web) or bearer session token (native)
-6. Session middleware populates `req.user` for subsequent requests
+6. On the first authenticated request, session middleware looks up the app `User` by `betterAuthId` and creates it if missing (`syncBetterAuthUser`)
+7. `req.user` is that app document for subsequent `modelRouter` permissions
+
+Email/password create omits `oauthProvider`. Apps that never use social login can keep `strict: "throw"` without declaring that field. OAuth create sets `oauthProvider` and the User schema must declare it.
 
 **Key properties:**
 - Session-based (cookies / bearer session) vs. stateless JWT
@@ -89,6 +94,16 @@ OAuth 2.0 authentication with GitHub.
 
 **Learn more:** [How to add GitHub OAuth](../how-to/add-github-oauth.md)
 
+### MCP service tokens (opt-in, `/mcp` only)
+
+Personal `mcp_` keys for remote MCP clients (Perplexity, Cursor JSON config) that cannot hold a session cookie. `TerrenoApp` must set `mcpServiceTokens`. Users mint keys from `POST /mcp/service-tokens` or **Profile → MCP connections**. The plaintext secret is returned **once**; the database stores SHA-256 `tokenHash`.
+
+`extractUserFromHeaders` on `/mcp` tries a `mcp_` Bearer first, then Better Auth, then JWT. A match loads the owning `User` and updates `lastUsedAt`. Revoked, expired, or disabled-user keys resolve to no user. The same Bearer is ignored on REST, sync, admin, and on the mint/list/revoke routes (a key cannot mint another key).
+
+This is not OAuth 2.1. Interactive MCP clients that cannot send a static key wait for the app MCP OAuth work ([app MCP server](../implementationPlans/app-mcp-server.md)). It is also not the hosted `@terreno/mcp` codegen server ([MCP server reference](../reference/mcp-server.md)).
+
+**Learn more:** [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md)
+
 ### Anonymous Strategy (JWT — legacy)
 
 Allows limited access without authentication.
@@ -259,7 +274,8 @@ modelRouter(Model, {
 - Use HTTPS in production
 - Validate token issuer (`TOKEN_ISSUER`)
 - Set appropriate token expiration times
-- Implement rate limiting on auth endpoints
+- Enable `TerrenoApp` `rateLimit` so login/signup/refresh use the stricter `auth` bucket (20 / 15 min). See [Rate limiting](../how-to/rate-limiting.md).
+- Keep login/signup/refresh reachable when the client still sends an expired access JWT. Those three routes skip JWT verification; `/auth/me` and other APIs still 401.
 - Log authentication failures
 
 ❌ **Don't:**
@@ -280,7 +296,7 @@ modelRouter(Model, {
 ❌ **Don't:**
 - Store tokens in localStorage on web (use httpOnly cookies in production)
 - Log tokens to console
-- Send tokens in URL query parameters
+- Send tokens in URL query parameters (MCP service tokens included)
 - Ignore token refresh failures
 
 ## Environment Variables
@@ -402,29 +418,29 @@ modelRouter(Model, {
 
 ### Webhook Authentication
 
-Verify webhook signatures instead of JWT:
+Verify signatures on `WebhooksApp` using `req.rawBody`. Do not `JSON.stringify(req.body)`
+and do not put webhook POSTs in OpenAPI.
 
-``````typescript
-import crypto from "crypto";
-
-router.post("/webhook", asyncHandler(async (req, res) => {
-  const signature = req.headers["x-signature"];
-  const payload = JSON.stringify(req.body);
-  const expected = crypto
-    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
-    .update(payload)
-    .digest("hex");
-  
-  if (signature !== expected) {
-    throw new APIError({status: 401, title: "Invalid signature"});
-  }
-  
-  // Process webhook
-}));
-``````
+```typescript
+import {hmacSignature, TerrenoApp, WebhooksApp} from "@terreno/api";
+
+const webhooks = new WebhooksApp({idempotency: {store: "mongo"}});
+webhooks.route({
+  path: "/webhooks/example",
+  source: "example",
+  verify: hmacSignature({secret: process.env.WEBHOOK_SECRET!, header: "X-Webhook-Signature"}),
+  eventId: (req) => String((req.body as {id?: string})?.id ?? ""),
+  handler: async () => undefined,
+});
+
+new TerrenoApp({userModel: User}).register(webhooks).start();
+```
+
+See [Receive inbound webhooks](../how-to/inbound-webhooks.md).
 
 ## Learn More
 
+- [Receive inbound webhooks](../how-to/inbound-webhooks.md)
 - [Add GitHub OAuth](../how-to/add-github-oauth.md)
 - [Create a model](../how-to/create-a-model.md)
 - [API reference](../reference/api.md)

package/src/docs/versioned/next/explanation/charts.md

@@ -0,0 +1,29 @@
+# Why Terreno owns chart SVG
+
+Terreno charts are drawn with `react-native-svg` and private `d3-scale` / `d3-shape` helpers inside `@terreno/ui`. Apps import `LineChart`, `BarChart`, `AreaChart`, and `DonutChart` — not d3 types and not a third-party chart API.
+
+`victory-native` was rejected for this slice: Skia canvas fights Terreno theme fonts, bun tests, and accessibility. Owned SVG lets axis labels stay `@terreno/ui` `Text` (Nunito/Titillium) and lets hit targets stay clickable `Box`es with `testID`s.
+
+`BarChart` grows each bar from the zero baseline (up for positives, down for negatives). A zero value draws no sliver; the press/hover hit stays at least 24px so the tooltip still works.
+
+`DonutChart` uses `d3-shape` `arc` angles (`0` is 12 o'clock, clockwise). Slice press/hover hits use the same paint transform so the tooltip lands on the visible slice.
+
+Axis ticks and donut legend labels use `Text` with `skipLinking`, matching `ChartFrame` tooltips, so a URL in `point.label` stays inert text instead of `Linking.openURL`.
+
+Sizing flows one way: the frame stretches to the container (`alignSelf: stretch`), the plot
+measures itself with `onLayout`, and the drawing is clipped to that measurement. Nothing inside a
+chart may set its own min-content width, or the container would size to the chart and the chart
+would size to the container. That is why x tick labels are absolutely positioned on their band
+centers instead of laid out in a row, and why the plot column sets `minWidth: 0`.
+
+Height works the same way: `height` is the whole chart, and the tick row, tooltip row, and legend
+row come out of that budget. A chart therefore fits a fixed-height slot, and reserving the tooltip
+row even when no tooltip is showing keeps hovering from reflowing the page.
+
+`DashboardGrid` is layout only, so it stays on the eager root export. Chart implementations sit behind the same lazy root boundary as `GPTChat`. Cell width subtracts flex `gap` so `md`/`lg` column counts actually fit.
+
+Chart paint is proven with **rendered PNG goldens**, not React test-renderer JSON.
+`bun run ui:charts:compare` opens the demo gallery
+(`/demo/chart-visual-gallery`), screenshots each fixture from easy to hard, and
+pixel-diffs against `demo/rendered-snapshots/`. Agents use the `review-chart-visuals`
+skill to read golden / actual / diff images when a compare fails.

package/src/docs/versioned/next/explanation/configuration-system.md

@@ -207,29 +207,19 @@ router.post("/admin/config", async (req, res) => {
 ### Tunable Parameters
 
 ``````typescript
-// Rate limiting
-Configuration.register("RATE_LIMIT_MAX", {
-  defaultValue: 100,
-  envVar: "RATE_LIMIT_MAX",
-  description: "Maximum requests per window",
+// Page size — app Configuration, not the HTTP limiter
+Configuration.register("DEFAULT_PAGE_SIZE", {
+  defaultValue: 20,
+  envVar: "DEFAULT_PAGE_SIZE",
+  description: "Default list page size",
   type: "number",
 });
 
-Configuration.register("RATE_LIMIT_WINDOW_MS", {
-  defaultValue: 900000, // 15 minutes
-  envVar: "RATE_LIMIT_WINDOW_MS",
-  description: "Rate limit window in milliseconds",
-  type: "number",
-});
-
-// Use in middleware
-const rateLimit = require("express-rate-limit");
-const limiter = rateLimit({
-  max: await Configuration.get<number>("RATE_LIMIT_MAX"),
-  windowMs: await Configuration.get<number>("RATE_LIMIT_WINDOW_MS"),
-});
+const pageSize = await Configuration.get<number>("DEFAULT_PAGE_SIZE");
 ``````
 
+HTTP rate limiting is **not** a Configuration key. Pass `rateLimit` on `TerrenoApp` (see [Rate limiting](../how-to/rate-limiting.md)). Do not register `RATE_LIMIT_MAX` as if it enabled the framework limiter.
+
 ### Environment-Specific Defaults
 
 ``````typescript