@terreno/mcp 57.17.0 → 57.19.2

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

@@ -0,0 +1,497 @@
+# Authentication Architecture
+
+Understanding how authentication works in @terreno/api — Better Auth sessions for new apps, with JWT/Passport documented for legacy consumers.
+
+## Overview
+
+**Better Auth is the default path** for new Terreno apps. It provides session-based authentication with MongoDB storage, built-in social OAuth (Google, GitHub, Apple), and clean integration with `@terreno/syncdb` (`betterAuthAdapter`, `RealtimeApp` socket sessions).
+
+Set `AUTH_PROVIDER=better-auth` and register `BetterAuthApp` on the server. On the client, use `createBetterAuthClient` + `generateBetterAuthSlice` from `@terreno/rtk` for session Redux state, then wire `betterAuthAdapter` into `createSyncDb`.
+
+**JWT/Passport (legacy)** remains supported through the current major release line for existing deployments. It uses stateless tokens, Passport strategies (email/password, GitHub OAuth, anonymous), and manual token refresh via `@terreno/rtk`. New projects should not start on JWT unless they have a specific requirement (custom token contracts, non-cookie clients, or a phased migration).
+
+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). **MCP OAuth access tokens** are the fourth, for remote clients that need an OAuth flow; enable them with `mcpOAuth` ([Enable MCP OAuth](../how-to/enable-mcp-oauth.md)).
+
+## When to choose which
+
+| Choose Better Auth | Stay on JWT (legacy) |
+|--------------------|----------------------|
+| New app or greenfield screen | Existing production JWT deployment |
+| Social login (Google, GitHub, Apple) | Custom JWT payload requirements |
+| `@terreno/syncdb` local-first data | Non-cookie API clients only |
+| Socket sessions via `RealtimeApp` | Gradual migration in progress |
+
+**Setup:** [Configure Better Auth](../how-to/configure-better-auth.md). **Data layer:** migrate auth before or with syncdb — see [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md) §7.
+
+## Authentication Strategies
+
+### Better Auth (default)
+
+Modern session-based authentication with built-in social OAuth support.
+
+**Flow:**
+1. Configure Better Auth with `AUTH_PROVIDER=better-auth` and register `BetterAuthApp`
+2. User chooses social provider (Google, GitHub, Apple) or email/password
+3. Backend redirects to OAuth provider or validates credentials
+4. Better Auth creates session in MongoDB
+5. Frontend receives a session cookie (web, default), a bearer session token (native), or, on web with `webAuth: "bearer"`, a bearer token from the `set-auth-token` header. Bearer on web is the option when the web app and the API are on different sites, where browsers block the third-party session cookie. See [Frontend and API on different sites](../how-to/configure-better-auth.md#frontend-and-api-on-different-sites)
+6. On the first authenticated request or socket handshake, Terreno looks up the app `User` by `betterAuthId` and creates it if missing (`syncBetterAuthUser`). An email alone does not prove someone owns an existing account, so an existing app `User` with the same email is linked only after Better Auth verifies that email, and never when the row already belongs to another Better Auth account. Linking removes a legacy password the row never proved with a verified email. `RealtimeApp` uses the registered `BetterAuthApp` instance for socket sessions without extra wiring
+7. `req.user` is that app document for subsequent `modelRouter` permissions. A session whose app `User` has `disabled: true` no longer authenticates: `req.user` stays unset, so protected routes answer 401 and disabling an account ends its live sessions. Better Auth's own routes, such as sign-out, still work
+
+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
+- A session cookie is sent with requests other sites start, so a cookie-authenticated write counts only when it comes from a trusted origin. Bearer tokens are never sent automatically, so they need no such check
+- Built-in OAuth providers with PKCE
+- `betterAuthAdapter` for syncdb socket auth
+- `sync:auth-expired` socket event when the session is no longer valid
+
+**Endpoints (when enabled):**
+- `POST /api/auth/signup/email` — Email/password signup
+- `POST /api/auth/signin/email` — Email/password signin
+- `GET /api/auth/signin/{provider}` — Initiate OAuth flow (google, github, apple)
+- `GET /api/auth/callback/{provider}` — OAuth callback handler
+- `POST /api/auth/signout` — Sign out session
+- `GET /api/auth/session` — Get current session
+
+**Learn more:** [Configure Better Auth](../how-to/configure-better-auth.md)
+
+### Email/Password (JWT / Local Strategy — legacy)
+
+Traditional username/password authentication using `passport-local-mongoose`.
+
+**Flow:**
+1. User signs up with email and password
+2. Password is hashed with pbkdf2 (via passport-local-mongoose)
+3. User logs in with credentials
+4. Backend validates password and issues JWT tokens
+5. Frontend includes JWT in `Authorization` header for subsequent requests
+
+**Endpoints:**
+- `POST /auth/signup` — Create new user account
+- `POST /auth/login` — Authenticate and receive tokens
+
+### GitHub OAuth Strategy (JWT — legacy)
+
+OAuth 2.0 authentication with GitHub.
+
+**Flow:**
+1. User clicks "Sign in with GitHub"
+2. Frontend redirects to `GET /auth/github?returnTo=<url>`
+3. Backend redirects to GitHub authorization page
+4. User grants permissions on GitHub
+5. GitHub redirects back to `GET /auth/github/callback`
+6. Backend verifies authorization code with GitHub
+7. Backend finds/creates user, issues JWT tokens
+8. Backend redirects to `returnTo` with tokens in the URL fragment, only when `returnTo` matches
+   `githubAuth.allowedReturnTo`; otherwise it returns the tokens as JSON
+
+Every flow carries an OAuth `state` value bound to the starting browser by a signed, HttpOnly,
+short-lived cookie. The callback rejects a response without matching state.
+
+**Account Linking:**
+- Authenticated users can link their GitHub account via `GET /auth/github/link`. The bearer
+  user's ID is recorded in the signed state, and the callback links only to that user, never to
+  a session or token present on the callback request
+- Multiple authentication methods can be attached to one user account
+- Users must have a password set before unlinking 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, and so does a key minted before the user's last password reset or session revocation (`tokenEpoch` changed since it was issued). MCP OAuth grants end the same way. 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 clients use MCP OAuth below. 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)
+
+### MCP OAuth (opt-in, `/mcp` only)
+
+Claude.ai connectors and ChatGPT apps cannot paste a static key; they run OAuth 2.1 discovery, get a client id (pre-created by the app, or through dynamic client registration), and run the authorization-code flow with PKCE. With `mcpOAuth` on `TerrenoApp`, Terreno is that authorization server for a JWT app. Terreno is backend-only, so the app hosts the consent screen and approves or denies with the signed-in user's JWT. The client then gets opaque, short-lived `mcpat_` access tokens and rotating `mcprt_` refresh tokens, stored as hashes. On `/mcp`, `extractAuthFromHeaders` resolves `mcpat_` alongside the other credentials, and a request with none gets a `401` RFC 9728 challenge that starts discovery. OAuth access tokens are ignored on REST, like service tokens.
+
+Every part of it is opt-in. Without `mcpOAuth.enabled` there are no OAuth routes, discovery documents, or challenge. Dynamic client registration is a second flag (`dynamicClientRegistration`) because an open registration endpoint lets anyone create a client, which leaves the consent screen as the only defense against a phishing client. With it off, the app creates its clients as `McpOAuthClient` documents.
+
+Revocation works on token families: every pair rotated from one approval shares a `familyId`. Revoking a family writes a tombstone before revoking its pairs, and issuing into a tombstoned family fails, checked again after the new pair is written. That closes the races where a refresh or code exchange that already passed its single-use check would otherwise issue a live pair after a concurrent reuse revoked the family.
+
+**Learn more:** [Enable MCP OAuth for a JWT app](../how-to/enable-mcp-oauth.md)
+
+### Which credential authenticated the request
+
+`getCurrentRequestContext()?.credential` is `"jwt"`, `"better-auth-session"`, `"mcp-service-token"`, or `"oauth"`. Service tokens and OAuth tokens are delegated: an agent holds them on the user's behalf. Permission code that grants broad access (an admin bypass, cross-tenant reads) should check the credential and keep that access to the user's own session. See [Request credential](../reference/api.md#request-credential).
+
+### Anonymous Strategy (JWT — legacy)
+
+Allows limited access without authentication.
+
+**Use case:** Public read access to certain resources while requiring authentication for writes.
+
+``````typescript
+import {Permissions} from "@terreno/api";
+
+modelRouter(Model, {
+  permissions: {
+    list: [Permissions.IsAuthenticatedOrReadOnly],
+    read: [Permissions.IsAuthenticatedOrReadOnly],
+    create: [Permissions.IsAuthenticated],
+  },
+});
+``````
+
+## JWT Token System (legacy)
+
+> JWT/Passport auth is **legacy**. It remains supported through the current major line but is not the recommended path for new apps. Prefer Better Auth above.
+
+### Token Types
+
+**Access Token (short-lived)**
+- Default expiration: 15 minutes (`TOKEN_EXPIRES_IN`)
+- Used for API requests
+- Included in `Authorization: Bearer <token>` header (or the `jwt` cookie). Other
+  `Authorization` schemes are never read as a JWT
+- Contains user ID and permissions in payload
+- Rejected with 401 once the user is `disabled`. Login, refresh, password reset, and GitHub
+  sign-in also stop issuing tokens to a disabled user, so disabling an account ends its access
+
+**Refresh Token (long-lived)**
+- Default expiration: 30 days (`REFRESH_TOKEN_EXPIRES_IN`)
+- Used only to obtain new access tokens
+- Stored securely on client
+- Cannot be used for API requests
+
+### Token Payload
+
+Access tokens contain:
+
+``````json
+{
+  "sub": "507f1f77bcf86cd799439011",  // User ID
+  "admin": false,                      // Admin status
+  "iat": 1709000000,                   // Issued at (timestamp)
+  "exp": 1709000900,                   // Expires at (timestamp)
+  "iss": "your-app-name"               // Issuer (from TOKEN_ISSUER env var)
+}
+``````
+
+Customize the payload with `authOptions.generateJWTPayload`:
+
+``````typescript
+setupServer({
+  authOptions: {
+    generateJWTPayload: (user) => ({
+      sub: user._id,
+      admin: user.admin,
+      role: user.role,  // Custom field
+    }),
+  },
+});
+``````
+
+### Token Refresh Flow
+
+1. Access token expires (after 15 minutes)
+2. API request returns `401 Unauthorized`
+3. Frontend middleware detects 401
+4. Frontend calls `POST /auth/refresh_token` with refresh token
+5. Backend validates refresh token
+6. Backend issues new access token and refresh token
+7. Frontend retries original request with new token
+
+This is handled automatically by @terreno/rtk's `emptyApi` configuration.
+
+## Frontend Integration
+
+### Redux Store Setup (with @terreno/rtk)
+
+``````typescript
+import {generateAuthSlice} from "@terreno/rtk";
+import {configureStore} from "@reduxjs/toolkit";
+import {openapi} from "./openApiSdk";
+
+const {authReducer, middleware, logout} = generateAuthSlice(openapi);
+
+export const store = configureStore({
+  reducer: {
+    auth: authReducer,
+    [openapi.reducerPath]: openapi.reducer,
+  },
+  middleware: (getDefault) =>
+    getDefault().concat(openapi.middleware, ...middleware),
+});
+``````
+
+**What this provides:**
+- Automatic token storage (SecureStore on mobile, AsyncStorage on web)
+- Token refresh middleware
+- Login/logout state management
+- Auth header injection for all API requests
+
+### Token Storage
+
+**Mobile (iOS/Android):**
+- Uses `expo-secure-store` for encrypted storage
+- Tokens stored in device keychain
+
+**Web:**
+- Uses `@react-native-async-storage/async-storage`
+- Falls back to localStorage
+- SSR-safe (checks `typeof window`)
+
+**Storage keys:**
+- `AUTH_TOKEN` — Access token
+- `REFRESH_TOKEN` — Refresh token
+
+## Permission System
+
+Permissions control access to modelRouter endpoints.
+
+### Built-in Permissions
+
+| Permission | Description |
+|-----------|-------------|
+| `IsAny` | Always allows (public access) |
+| `IsAuthenticated` | Requires valid JWT (non-anonymous) |
+| `IsAdmin` | Requires `user.admin === true` |
+| `IsOwner` | Requires admin or `obj.ownerId === user.id` |
+| `IsAuthenticatedOrReadOnly` | Auth required for writes, anyone can read |
+| `IsOwnerOrReadOnly` | Owner or admin for writes, anyone can read |
+
+### Permission Evaluation
+
+Permissions are evaluated as an **AND** operation — all permissions in the array must return `true`:
+
+``````typescript
+permissions: {
+  update: [Permissions.IsAuthenticated, Permissions.IsOwner],
+  // Both conditions must be true
+}
+``````
+
+### Owner scope on writes
+
+Object permissions such as `IsOwner` first run against the document as it was loaded. On
+create and update, modelRouter also checks the document as it will be written. A user cannot
+create a record that names another user as `ownerId`, or move their own record to another
+user, even when the router has no `preUpdate` that strips `ownerId`. RBAC routers get the same
+check from their role scopes and `access.scope`. Admins can still reassign owners. See
+[modelRouter write scope](../reference/api.md#modelrouter-write-scope).
+
+### Custom Permissions
+
+Create custom permission functions:
+
+``````typescript
+const IsPremiumUser = (user, obj, method) => {
+  return user?.subscription === "premium";
+};
+
+modelRouter(Model, {
+  permissions: {
+    create: [Permissions.IsAuthenticated, IsPremiumUser],
+  },
+});
+``````
+
+### Why changing the email needs the current password
+
+The account email is where password-reset links go. If a session alone could change it, anyone
+holding a stolen or borrowed session could move the recovery address to a mailbox they control,
+request a reset, and keep the account after the session ends. So `PATCH /auth/me` asks for the
+current password before it changes the mailbox, and then tells the old address that the change
+happened. The notice holds no link or token, so forwarding it or leaving it in an inbox exposes
+nothing that acts on the account.
+
+The check uses whichever password the user has: the passport-local-mongoose hash, or, for a
+Better Auth user with no passport hash, the Better Auth credential. A user who signed up only
+through a social provider has no password to confirm, so they must set one through the reset
+flow first. Wrong attempts share the passport lockout with login rather than a separate counter.
+The new email is not held as pending and existing sessions are not ended; the notice to the old
+address is the signal that lets the owner react. Status codes and messages are in the
+[API reference](../reference/api.md#changing-the-email-on-patch-authme).
+
+## Security Best Practices
+
+### Backend
+
+✅ **Do:**
+- Use environment variables for secrets (`TOKEN_SECRET`, `REFRESH_TOKEN_SECRET`)
+- Set strong, unique secrets in production (at least 32 characters)
+- Use HTTPS in production
+- Validate token issuer (`TOKEN_ISSUER`)
+- Set appropriate token expiration times
+- 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:**
+- Commit secrets to version control
+- Use the same secret for tokens and refresh tokens
+- Store sensitive data in JWT payload (it's base64, not encrypted)
+- Allow infinite token lifetimes
+
+### Frontend
+
+✅ **Do:**
+- Use SecureStore on mobile for token storage
+- Clear tokens on logout
+- Handle token expiration gracefully
+- Show user feedback during auth flows
+- Validate tokens before making authenticated requests
+
+❌ **Don't:**
+- Store tokens in localStorage on web when frontend and API share a site (use httpOnly cookies). When they are on different sites, Better Auth's `webAuth: "bearer"` mode is the supported way to keep a web token: it accepts the XSS and shared-device risk of web storage, and `bearerStorage: window.sessionStorage` narrows the second. See [Frontend and API on different sites](../how-to/configure-better-auth.md#frontend-and-api-on-different-sites)
+- Log tokens to console
+- Send tokens in URL query parameters (MCP service tokens included)
+- Ignore token refresh failures
+
+## Environment Variables
+
+Required for authentication:
+
+``````bash
+# JWT Configuration
+TOKEN_SECRET=your-secret-key-min-32-chars
+TOKEN_ISSUER=your-app-name
+REFRESH_TOKEN_SECRET=different-secret-key-min-32-chars
+SESSION_SECRET=session-secret-min-32-chars
+
+# Optional: Custom expiration times
+TOKEN_EXPIRES_IN=15m
+REFRESH_TOKEN_EXPIRES_IN=30d
+
+# GitHub OAuth (if using)
+GITHUB_CLIENT_ID=your_github_client_id
+GITHUB_CLIENT_SECRET=your_github_client_secret
+GITHUB_CALLBACK_URL=http://localhost:4000/auth/github/callback
+
+# Optional: Disable user registration
+SIGNUP_DISABLED=false
+``````
+
+## Authentication Middleware
+
+### Protecting Routes
+
+Use `authenticateMiddleware()` to require authentication:
+
+``````typescript
+import {authenticateMiddleware, asyncHandler} from "@terreno/api";
+
+router.get("/protected", [
+  authenticateMiddleware(),
+  asyncHandler(async (req, res) => {
+    // req.user is populated with authenticated user
+    const userId = req.user?._id;
+    return res.json({userId});
+  }),
+]);
+``````
+
+### Anonymous Access
+
+Allow unauthenticated requests but populate `req.user` if token is present:
+
+``````typescript
+router.get("/public", [
+  authenticateMiddleware({anonymous: true}),
+  asyncHandler(async (req, res) => {
+    // req.user is populated if token provided, undefined otherwise
+    const isLoggedIn = !!req.user;
+    return res.json({isLoggedIn});
+  }),
+]);
+``````
+
+## Troubleshooting
+
+### "Invalid token"
+
+- Token has expired — frontend should refresh
+- Token signature invalid — check `TOKEN_SECRET` matches
+- Token issuer mismatch — verify `TOKEN_ISSUER` is correct
+
+### "No auth token provided"
+
+- Missing `Authorization` header
+- Header format incorrect (should be `Bearer <token>`)
+
+### Token refresh fails
+
+- Refresh token expired — user must log in again
+- `REFRESH_TOKEN_SECRET` mismatch between token creation and validation
+- Refresh token revoked (user logged out)
+
+### User logged out unexpectedly
+
+- Access token expired and refresh failed
+- Backend `TOKEN_SECRET` changed (invalidates all tokens)
+- Token storage cleared (app reinstall, cache clear)
+
+## Advanced Topics
+
+### Custom User Fields in Token
+
+Add custom fields to JWT payload:
+
+``````typescript
+setupServer({
+  authOptions: {
+    generateJWTPayload: (user) => ({
+      sub: user._id,
+      admin: user.admin,
+      organizationId: user.organizationId,
+      roles: user.roles,
+    }),
+  },
+});
+``````
+
+### Multi-Tenant Authentication
+
+Scope users to organizations:
+
+``````typescript
+const queryFilter = (user, _query) => ({
+  organizationId: user?.organizationId,
+});
+
+modelRouter(Model, {
+  permissions: {list: [Permissions.IsAuthenticated]},
+  queryFilter,
+});
+``````
+
+### Webhook Authentication
+
+Verify signatures on `WebhooksApp` using `req.rawBody`. Do not `JSON.stringify(req.body)`
+and do not put webhook POSTs in OpenAPI.
+
+```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)
+- [@terreno/rtk reference (legacy)](../reference/legacy/rtk.md)

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

@@ -0,0 +1,41 @@
+# 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.
+
+Cartesian facades use `xTickPolicy="auto"` by default: up to seven categorical labels
+stay horizontal, while denser sets rotate 45 degrees and reserve a taller axis row.
+That taller row comes out of `height`; the plot shrinks so the chart still fits the
+requested slot. `SparklineChart` scales to the data range so a small period-over-period
+change stays visible.
+Callers may force `"truncate"` or `"rotate"`. `title` and `periodLabel` are convenience
+props backed by the same `ChartCard` used for explicit chart/table composition.
+
+`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.
+
+The example app admin home (`/admin`) mounts `AdminCharts` so scorecards, a multi-series line,
+bars, an area, and a donut with a center label render together. See
+[Compose charts in a dashboard grid](../how-to/charts-and-dashboards.md).