@frontmcp/skills 1.2.1 → 1.4.0

package/catalog/create-tool/rules/use-this-fail-for-business-errors.md

@@ -0,0 +1,75 @@
+---
+name: use-this-fail-for-business-errors
+constraint: '`this.fail(new SomeMcpError(...))` for business-logic errors — never raw `throw new Error(...)`.'
+severity: required
+---
+
+# Rule: `this.fail` for business errors, not raw `throw`
+
+## The rule
+
+For errors the user / agent should see (not-found, permission-denied, invalid-input, conflict, etc.), use `this.fail(new SomeMcpError(...))`. Never `throw new Error(...)` — the raw `Error` message gets REDACTED before reaching the client.
+
+## Good
+
+```typescript
+import { PublicMcpError, ResourceNotFoundError } from '@frontmcp/sdk';
+
+async execute(input: { id: string }) {
+  const record = await this.findRecord(input.id);
+  if (!record) {
+    this.fail(new ResourceNotFoundError(`record:${input.id}`)); // -32002, message reaches client
+  }
+
+  if (record.tenantId !== this.auth.claims['tenantId']) {
+    this.fail(new PublicMcpError('Access denied')); // generic public message
+  }
+
+  // …
+}
+```
+
+## Bad
+
+```typescript
+// ❌ raw Error — message REDACTED to "Internal error" before reaching client
+async execute(input: { id: string }) {
+  const record = await this.findRecord(input.id);
+  if (!record) {
+    throw new Error(`record:${input.id} not found`); // client sees "Internal error"
+  }
+}
+```
+
+## Why
+
+| You throw                              | Client sees                                                  |
+| -------------------------------------- | ------------------------------------------------------------ |
+| `new PublicMcpError('Quota exceeded')` | `{ code: -32603, message: 'Quota exceeded' }`                |
+| `new ResourceNotFoundError('user:42')` | `{ code: -32002, message: 'user:42' }`                       |
+| `new Error('Quota exceeded')`          | `{ code: -32603, message: 'Internal error' }` ← **redacted** |
+
+Raw `Error`s are treated as potentially-sensitive infrastructure errors. The framework REDACTS the message before the client sees it (to avoid leaking stack traces, internal IDs, env vars, etc.). `PublicMcpError` (and subclasses) explicitly opt the message into the response.
+
+## Common error classes
+
+| Class                            | Error code                               | HTTP        | Use for                                                                    |
+| -------------------------------- | ---------------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| `PublicMcpError`                 | —                                        | —           | Base. Subclass for domain-specific public errors                           |
+| `ResourceNotFoundError`          | `'RESOURCE_NOT_FOUND'` (-32002 JSON-RPC) | 404         | "Thing doesn't exist"                                                      |
+| `InvalidInputError`              | `'INVALID_INPUT'`                        | 400         | Cross-field / business-rule input validation (Zod handles per-field shape) |
+| `UnauthorizedError`              | `'UNAUTHORIZED'` (-32001 JSON-RPC)       | 401         | Missing credentials                                                        |
+| `RateLimitError`                 | `'RATE_LIMIT_EXCEEDED'`                  | 429         | Rate-limit fired                                                           |
+| Custom `PublicMcpError` subclass | your choice                              | your choice | Domain-specific errors with structured `data`                              |
+
+## When to throw raw `Error` (or just let it propagate)
+
+For **infrastructure errors** that genuinely should be redacted — network failure, DB unavailable, file-system error. Don't catch them; just let them propagate. The framework wraps them in `InternalMcpError` with the message redacted, and logs the original for ops.
+
+## Verification
+
+```bash
+# Find raw `throw new Error(...)` inside tool execute() bodies
+grep -rE 'throw new Error\(' src/**/*.tool.ts
+# Should match few or none — and any matches should be in non-execute code paths
+```

package/catalog/create-tool/rules/widget-paths-anchor-with-import-meta-url.md

@@ -0,0 +1,76 @@
+---
+name: widget-paths-anchor-with-import-meta-url
+constraint: '`.tsx` widget paths in `ui.template: { file }` are anchored via `fileURLToPath(new URL(...))`, never bare relative.'
+severity: required
+---
+
+# Rule: anchor widget paths with `import.meta.url`
+
+## The rule
+
+Relative `FileSource` paths in `ui.template: { file }` resolve against `process.cwd()` — **not** the tool source's directory (issue #444). A bare relative path silently breaks the moment the server is launched from a different working directory. Always anchor the path to the tool source.
+
+## Good
+
+```typescript
+import { fileURLToPath } from 'node:url';
+
+const widgetPath = fileURLToPath(new URL('./sales-chart.widget.tsx', import.meta.url));
+
+@Tool({
+  name: 'sales_chart',
+  // …
+  ui: { template: { file: widgetPath } },
+})
+```
+
+## Bad
+
+```typescript
+// ❌ bare relative path — resolves against process.cwd()
+@Tool({
+  name: 'sales_chart',
+  ui: { template: { file: './sales-chart.widget.tsx' } },
+})
+// → works locally when running from src/apps/main/tools/
+// → fails with ENOENT when running from the repo root, from dist/, etc.
+```
+
+## Why
+
+- **`process.cwd()` is whoever launched the process.** `yarn dev` from the repo root, `node dist/main.js` from `/opt/app`, a containerized run from `/`, a serverless cold start from `/var/task`, an Nx executor from `apps/<thing>/` — all different cwds.
+- **Tool sources move around at build time.** ESM build output is often in `dist/`; `.tool.ts` becomes `.tool.js`. The relative reference's resolution chain is fragile to that.
+- **`fileURLToPath(new URL('./x', import.meta.url))` is invariant.** It anchors to the **source file** that contains the URL literal — same answer at dev, build, and runtime.
+
+## CommonJS projects (`__dirname`)
+
+`import.meta.url` is **ESM-only**. In a CommonJS project (`package.json` `"type": "commonjs"`, or `tsconfig` `"module": "commonjs"`) `import.meta` is unavailable and the build fails. Anchor with `__dirname` instead — the CJS equivalent, equally invariant to `process.cwd()`:
+
+```typescript
+import { join } from 'node:path';
+
+const widgetPath = join(__dirname, 'sales-chart.widget.tsx');
+
+@Tool({
+  name: 'sales_chart',
+  ui: { template: { file: widgetPath } },
+})
+```
+
+Pick the anchor that matches your module system — both resolve to the tool source's directory regardless of cwd. The rule is only that the path must **never** be a bare relative string.
+
+## Also: name the widget `*.widget.tsx`
+
+The scaffolded `tsconfig.json` excludes `**/*.widget.tsx` from the server typecheck (issue #445). Naming widgets `sales-chart.widget.tsx` keeps server `tsc --noEmit` happy without dragging React types into the server config.
+
+## Verification
+
+```bash
+# Find any bare-relative `file:` literals in ui templates — should return 0 hits
+grep -rE "file:\s*'\.\.?/[^']*\.tsx'" src/**/*.tool.ts
+```
+
+## See also
+
+- [`references/ui-widgets.md`](../references/ui-widgets.md)
+- [`examples/23-tool-with-ui-filesource-tsx`](../examples/23-tool-with-ui-filesource-tsx.md)

package/catalog/create-tool/rules/widget-resource-mode-host-detect.md

@@ -0,0 +1,61 @@
+---
+name: widget-resource-mode-host-detect
+constraint: 'Leave `ui.resourceMode` unset — the framework host-detects (`inline` for Claude, `cdn` for others).'
+severity: recommended
+---
+
+# Rule: leave `ui.resourceMode` unset by default
+
+## The rule
+
+`ui.resourceMode` defaults to a host-detected value (issue #456): `'inline'` for Claude (React bundled into the widget so it renders under Claude's sandbox CSP), `'cdn'` for OpenAI / ChatGPT / Cursor / MCP Inspector (smaller payload from esm.sh). Leave the field unset unless you have a specific reason to override.
+
+## Good
+
+```typescript
+@Tool({
+  // …
+  ui: {
+    template: { file: widgetPath },
+    // resourceMode intentionally UNSET — framework picks per host
+  },
+})
+```
+
+## Bad (without justification)
+
+```typescript
+// ❌ pinning to 'cdn' — breaks Claude (widget hangs on "Loading widget…")
+ui: { template: { file: widgetPath }, resourceMode: 'cdn' }
+
+// ❌ pinning to 'inline' — fine for Claude, but always-larger payload for OpenAI / ChatGPT
+ui: { template: { file: widgetPath }, resourceMode: 'inline' }
+```
+
+## When to override (with justification)
+
+- **Force `'inline'`** when the widget must work in a network-blocked environment beyond Claude (some kiosks, air-gapped demos, etc.). Pay the larger payload cost intentionally.
+- **Force `'cdn'`** when you specifically know the widget will only be served to CDN-permissive clients AND you want minimum payload. Rare — usually the framework's choice is correct.
+- **Set per call** at the tool layer is the wrong place — `resourceMode` is part of static widget compilation. Per-call decisions belong in `servingMode` instead.
+
+## Why
+
+- **Claude's iframe blocks external scripts.** Default `'cdn'` emits an esm.sh import map for React; Claude's CSP blocks it; the widget hangs forever on the FrontMCP "Loading widget…" placeholder. `'inline'` bundles React into the widget's `<script type="module">`.
+- **OpenAI / ChatGPT / Cursor are CDN-permissive.** `'cdn'` is smaller (no inlined React) — better cold-render performance.
+- **The host can be detected at per-call render time.** `renderToolTemplate` reads `platformType` from the request and picks the right mode automatically. Per-tool overrides defeat the detection.
+
+## Static-mode caveat
+
+For `servingMode: 'static'` tools (pre-compiled at server startup, before any client connects), there's no platformType to detect against. Static widgets default to `'cdn'` regardless. If a static-mode tool needs to render in Claude, set `resourceMode: 'inline'` explicitly.
+
+## Verification
+
+```bash
+# Find ui blocks with explicit resourceMode — review each for justification
+grep -rE "resourceMode:\s*'(cdn|inline)'" src/**/*.tool.ts
+```
+
+## See also
+
+- [`references/ui-widgets.md`](../references/ui-widgets.md)
+- [`examples/23-tool-with-ui-filesource-tsx`](../examples/23-tool-with-ui-filesource-tsx.md)

package/catalog/frontmcp-auth-ui/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: frontmcp-auth-ui
+description: 'Use when customizing, branding, or replacing the built-in FrontMCP OAuth pages (the login, consent, federated-select, incremental-authorization, and error pages) with your own React components. Covers the auth.ui slot-to-file map and auth.extras name-to-handler map on the auth config (no decorator, no class); the @frontmcp/ui/auth React hooks, the AuthPageWrapper component, and mountAuthPage (client-rendered via an esm.sh import-map plus a per-file server-side transform, with no bundling and no SSR); and the framework-owned CSRF and CSP. Triggers: custom login page, brand the consent screen, replace the OAuth UI, custom authorization UI, style the auth pages, multi-step login. The skill for CUSTOM AUTHORIZATION UI (distinct from auth config in frontmcp-config and permissions in frontmcp-authorities).'
+tags: [auth, auth-ui, login, consent, custom-ui, react, oauth, guide]
+category: config
+targets: [all]
+bundle: [full]
+priority: 5
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/authentication/custom-ui
+---
+
+# FrontMCP Custom Authorization UI (`auth.ui`)
+
+Entry point for replacing FrontMCP's built-in OAuth pages (login, consent, federated, incremental, error) with your own React components. Custom UI is a simple **slot→file map** (`auth.ui`) plus an extras **name→handler map** (`auth.extras`) on the auth config — there is no decorator and no class. The `references/custom-auth-ui.md` reference has the full API; the `examples/` show a single login slot and a multi-step extras form.
+
+## When to Use This Skill
+
+### Must Use
+
+- Branding or fully replacing the `local`/`remote` mode **login** page with a custom React component
+- Building a custom **consent** screen, **federated** provider picker, **incremental** authorization, or **error** page
+- Adding a server-validated multi-step field to an authorization page (e.g. "add another item") via `auth.extras`
+
+### Recommended
+
+- Understanding which half is the server (`auth.ui` / `auth.extras` in `@frontmcp/sdk`) and which is the client (`@frontmcp/ui/auth`)
+- Looking up the `AuthFlowState` fields a slot component receives, or the `/oauth/ui/extra` route
+- Confirming that the framework (not your component) owns CSRF + CSP
+
+### Skip When
+
+- You only need to add/rename **fields** on the built-in login page or run a custom verifier — use the declarative `login` / `authenticate` config in `frontmcp-config` → `configure-auth` instead (no React, no build step)
+- You are customizing a **tool widget** (not an auth page) — use `create-tool` → `ui-widgets`
+- You don't need a custom page at all — configuring no `auth.ui` keeps the built-in pages
+
+> **Decision:** Use this skill when you want to render your OWN component for an auth slot. Use `configure-auth`'s declarative `login` config when tweaking the built-in page's fields is enough.
+
+## Prerequisites
+
+- A FrontMCP server in `local` or `remote` auth mode (see `frontmcp-config` → `configure-auth`)
+- `@frontmcp/ui`, `react`, and `react-dom` installed (`react`/`react-dom` are peer deps of `@frontmcp/ui`)
+
+## Steps
+
+1. Write a React component (default export) for the slot, reading the injected state via `@frontmcp/ui/auth` hooks (see `references/custom-auth-ui.md`)
+2. Map the slot to its `.tsx` path under `auth.ui` — a RELATIVE path auto-anchored to the config file's directory (no `fileURLToPath`)
+3. (Optional) Add an `auth.extras[name]` handler function for any mid-flow validated field
+4. Declare both **under `auth`**: `@FrontMcp({ auth: { mode: 'local', ui: { login: './…' }, extras: { … } } })` (per-app under `splitByApp` — put them on the `@App({ auth })` that owns the pages)
+5. Verify using the Verification Checklist below
+
+## Scenario Routing Table
+
+| Scenario                                                       | Reference        | Description                                                                          |
+| -------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------ |
+| Replace any built-in auth page with a React component          | `custom-auth-ui` | `auth.ui: { slot: './file.tsx' }`, the hooks, `<AuthPageWrapper>`, `mountAuthPage`   |
+| Add a server-validated mid-flow field (multi-step form)        | `custom-auth-ui` | `auth.extras: { name: handler }`, the accumulator, `useExtraField` / `useAddedItems` |
+| Look up the flow-state fields a component receives             | `custom-auth-ui` | `AuthFlowState` field table (no PII)                                                 |
+| Understand the served route and the framework-owned CSRF + CSP | `custom-auth-ui` | `/oauth/ui/extra`, the esm.sh import-map + inline module, security ownership         |
+
+## The map form
+
+Custom UI is a **slot→file map** on the auth config. Point each slot at a sibling `.tsx`/`.jsx` source (default export); the SDK transpiles it once server-side and inlines it as an ES module, with deps loaded from esm.sh via an import-map and `mountAuthPage` appended for you — exactly as `@Tool({ ui })` leads with the `FileSource` `{ file }` form:
+
+```ts
+// src/server.ts
+import { App } from '@frontmcp/sdk'; // or @FrontMcp
+
+@App({
+  auth: {
+    mode: 'local',
+    // slot → RELATIVE .tsx, auto-anchored to THIS config file's directory.
+    ui: { login: './auth/login.tsx' },
+    // extra name → handler fn (no class).
+    extras: { 'envs:add': async (input, ctx) => ({ ok: true, addedItems: [{ key: String(input.key) }] }) },
+  },
+})
+export default class Server {}
+```
+
+A relative `auth.ui` path resolves against the directory of the file that declares the `@App`/`@FrontMcp` config — captured automatically at decoration time. **No `fileURLToPath` needed.** Absolute paths pass through; on capture failure the framework falls back to `process.cwd()` with a warning.
+
+## Common Patterns
+
+| Pattern            | Correct                                                                      | Incorrect                                                | Why                                                                                         |
+| ------------------ | ---------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Slot registration  | `auth: { ui: { login: './login.tsx' } }`                                     | `auth: { ui: [LoginAuthUi] }` (array of classes)         | Custom UI is a slot→file MAP now — no decorator, no class                                   |
+| Path anchoring     | Relative `'./login.tsx'` (auto-anchored to the config file)                  | `fileURLToPath(new URL('./login.tsx', import.meta.url))` | The framework captures the config file's dir for you — manual anchoring is no longer needed |
+| Extra registration | `auth: { extras: { 'envs:add': handlerFn } }`                                | `auth: { extras: [AddEnvExtra] }` (annotated class)      | Extras are an extra-name → handler-function MAP now                                         |
+| CSRF               | Let the hooks round-trip `csrfToken`                                         | Generating / checking a token in your component          | The server mints + verifies CSRF; your component must not                                   |
+| User identity      | User-typed fields live in your own `<form>` inputs                           | Putting email/name into `AuthFlowState`                  | `AuthFlowState` is PII-free by contract — it carries OAuth client ids + control fields only |
+| Wrapper form       | Wrap UI in `<AuthPageWrapper>` (renders the finish `<form>` + hidden fields) | Hand-rolling `pending_auth_id` / `csrf` hidden inputs    | The wrapper injects the control fields so a no-JS submit still works                        |
+
+## Verification Checklist
+
+- [ ] `GET /oauth/authorize` returns a page with an EMPTY `#frontmcp-auth-root` (not the built-in page) — the component's rendered markup is NOT in the HTTP response
+- [ ] The page has a `<script type="module">` with the TRANSPILED component (`React.createElement`, NOT a bundle/IIFE/`react-dom/server`) + an `import { mountAuthPage } from '@frontmcp/ui/auth'` tail
+- [ ] The page has a `<script type="importmap">` mapping `react` + `@frontmcp/ui/auth` → `https://esm.sh/...`, with `?external=react,react-dom` on the `@frontmcp/*` URLs (single React)
+- [ ] The HTML injects `window.__FRONTMCP_AUTH__` with the flow state (and no PII — no `email`/`name` field)
+- [ ] Response carries the auth CSP headers (`frame-ancestors 'none'`, `https://esm.sh` allowed, NO `'unsafe-eval'`) and `X-Frame-Options: DENY`
+- [ ] There is **no** `/oauth/ui/<slot>.js` route (it 404s — the module is inlined, not served separately)
+- [ ] (If using `auth.extras`) a valid `POST /oauth/ui/extra` returns `{ ok: true, addedItems }`, an invalid one returns 400, and a bad `csrf` returns 400
+- [ ] Removing the slot from `auth.ui` falls back to the built-in page unchanged
+
+## Troubleshooting
+
+| Problem                                              | Cause                                                      | Solution                                                                                                                                                           |
+| ---------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Built-in page still shows                            | Slot not in `auth.ui`, or the `.tsx` failed to transpile   | Confirm the slot is in `auth: { ui: { … } }` on the scope that owns the pages; check logs — a transpile error falls back to the built-in page                      |
+| Blank page / `@frontmcp/ui/auth` 404s in the browser | `@frontmcp/ui/auth` isn't on esm.sh (unpublished monorepo) | Publish `@frontmcp/ui`, OR map it to a locally-served ESM URL via `@FrontMcp({ ui: { cdnOverrides } })` (see `references/custom-auth-ui.md` → Local dev / offline) |
+| `ENOENT` / component not found at runtime            | Path doesn't resolve from the config file's dir            | Use a path relative to the config file (auto-anchored), or an absolute path                                                                                        |
+| Hooks throw "must be used inside …"                  | Component rendered without `<AuthPageWrapper>`             | Mount via `mountAuthPage(Component)` (it wraps for you) or wrap manually in `<AuthPageWrapper>`                                                                    |
+| extras POST returns 400 (csrf)                       | The submitted `csrf` ≠ the server-minted token             | Let the hooks send it — `useExtraField` / `submitExtra` attach `pending_auth_id` + `csrf` automatically                                                            |
+| Custom page can't import `@frontmcp/ui/auth`         | Package (or `react`/`react-dom`) not installed             | `npm install @frontmcp/ui react react-dom`                                                                                                                         |
+
+## Examples
+
+Each reference has matching examples under [`examples/<reference>/`](./examples/):
+
+### `custom-auth-ui`
+
+| Example                                                                       | Level        | Description                                                                                                              |
+| ----------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| [`login-slot`](./examples/custom-auth-ui/login-slot.md)                       | Intermediate | Replace the built-in login page with a custom React component via `auth.ui: { login: './login.tsx' }` and `useAuthFlow`. |
+| [`multi-step-auth-extra`](./examples/custom-auth-ui/multi-step-auth-extra.md) | Advanced     | Add a server-validated multi-step field with `auth.extras: { 'envs:add': fn }`, `useExtraField`, and `useAddedItems`.    |
+
+## Accessing This Skill
+
+Skills are distributed as plain SKILL.md files plus a sibling `references/`
+and `examples/` tree, so consumers can pick whichever access mode fits:
+
+| Mode               | How it works                                                                                                                                                                                                                                                                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Filesystem**     | Read `libs/skills/catalog/frontmcp-auth-ui/` directly from a clone of the catalog repo, or from a published `@frontmcp/skills` install. SKILL.md is the entry point.                                                                                                                                                                              |
+| **`frontmcp` CLI** | `frontmcp skills list`, `frontmcp skills read frontmcp-auth-ui`, `frontmcp skills read frontmcp-auth-ui:references/<file>.md`, `frontmcp skills install frontmcp-auth-ui` — no server required.                                                                                                                                                   |
+| **MCP `skill://`** | When a developer mounts this skill into their own FrontMCP server (`@FrontMcp({ skills: [...] })`), the SDK exposes it via SEP-2640 resources: `skill://frontmcp-auth-ui/SKILL.md`, `skill://frontmcp-auth-ui/references/{file}.md`, etc. The server's `skill://index.json` returns the SEP-2640 discovery document for everything mounted on it. |
+
+The catalog itself is **not** an MCP server. The `skill://` URIs only resolve
+when a server has been configured to host this skill.
+
+## Reference
+
+- [Custom Authorization UI (`auth.ui`)](https://docs.agentfront.dev/frontmcp/authentication/custom-ui)
+- Related skills: `frontmcp-config` (→ `configure-auth` for the declarative `login` config), `create-tool` (→ `ui-widgets` for tool widgets)

package/catalog/frontmcp-auth-ui/examples/custom-auth-ui/login-slot.md

@@ -0,0 +1,97 @@
+---
+name: login-slot
+reference: custom-auth-ui
+level: intermediate
+description: "Replace the built-in login page with a custom React component via auth.ui: { login: './login.tsx' } and useAuthFlow, while the framework keeps owning CSRF and CSP."
+tags: [auth, auth-ui, login, custom-ui, react, client-rendered]
+features:
+  - "Mapping a slot to a `.tsx` file with `auth.ui: { login: './login.tsx' }` (the supported render path)"
+  - 'Using a RELATIVE path auto-anchored to the config file — no `fileURLToPath`, no decorator, no class'
+  - 'Reading the injected `AuthFlowState` via `useAuthFlow()` and submitting with `<form onSubmit={submitFinish}>`'
+  - 'Letting `<AuthPageWrapper>` render the enclosing finish `<form>` with the `pending_auth_id` + `csrf` hidden fields'
+  - 'The SDK transpiling the `.tsx` server-side and inlining it as an ES module (deps from esm.sh via an import-map) + appending the `mountAuthPage` call automatically'
+---
+
+# Custom Login Slot with `auth.ui`
+
+Replace the built-in login page with a custom React component via auth.ui: { login: './login.tsx' } and useAuthFlow, while the framework keeps owning CSRF and CSP.
+
+The component reads the server-injected flow state through `useAuthFlow()` and renders
+its own sign-in form. The framework injects `window.__FRONTMCP_AUTH__`, mints the CSRF
+token, sets the CSP, transpiles the `.tsx` server-side, and inlines it into the authorize
+page as a `<script type="module">` with an esm.sh import-map (no bundling, no SSR) — the
+developer writes only the UI.
+
+## Code
+
+```tsx
+// src/auth/login.tsx — the custom component (default export)
+import React from 'react';
+
+import { AuthPageWrapper, useAuthFlow } from '@frontmcp/ui/auth';
+
+export default function LoginPage(): React.ReactElement {
+  // useAuthFlow() returns the injected state + a submitFinish handler. Everything
+  // OAuth (pending id, csrf, submit target, slot markers) is already wired.
+  const { clientName, scopes, error, submitFinish } = useAuthFlow();
+
+  return (
+    // AuthPageWrapper renders the enclosing <form> (with pending_auth_id + csrf
+    // hidden fields) so a no-JS submit works; submitFinish drives the JS path.
+    <AuthPageWrapper>
+      <h1>Sign in to {clientName ?? 'the application'}</h1>
+      {scopes.length > 0 && <p>Requested access: {scopes.join(', ')}</p>}
+      {error && <p className="error">{error}</p>}
+
+      <form onSubmit={submitFinish}>
+        <label>
+          Email
+          <input type="email" name="email" placeholder="you@example.com" required />
+        </label>
+        <button type="submit">Continue</button>
+      </form>
+    </AuthPageWrapper>
+  );
+}
+
+// No need to call mountAuthPage here: the SDK appends `mountAuthPage(LoginPage)` to the
+// inlined module automatically, so a `file`-based component only needs a default export.
+```
+
+```ts
+// src/server.ts — map the slot UNDER `auth` (per-app under splitByApp)
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'MyServer', version: '1.0.0' },
+  auth: {
+    mode: 'local',
+    // Custom auth UI is a slot→file map, scoped to this auth config. The relative
+    // path is auto-anchored to THIS server file's directory — no fileURLToPath.
+    ui: { login: './auth/login.tsx' },
+    // Single-operator dev convenience: email optional so a no-JS submit can mint a code.
+    requireEmail: false,
+  },
+})
+export default class Server {}
+```
+
+## What This Demonstrates
+
+- Mapping a slot to a `.tsx` file with `auth.ui: { login: './login.tsx' }` (the supported render path)
+- Using a RELATIVE path auto-anchored to the config file — no `fileURLToPath`, no decorator, no class
+- Reading the injected `AuthFlowState` via `useAuthFlow()` and submitting with `<form onSubmit={submitFinish}>`
+- Letting `<AuthPageWrapper>` render the enclosing finish `<form>` with the `pending_auth_id` + `csrf` hidden fields
+- The SDK transpiling the `.tsx` server-side and inlining it as an ES module (deps from esm.sh via an import-map) + appending the `mountAuthPage` call automatically
+
+## Notes
+
+- **File path**: the path is relative to the file that declares the `@FrontMcp`/`@App` config and
+  is auto-anchored at decoration time — no manual `fileURLToPath`. Absolute paths also work.
+- **Build exclusion**: keep the `.tsx` out of the server's own typecheck (the SDK transpiles it
+  separately) — e.g. place it where the scaffolded `tsconfig.json`'s `exclude` keeps it out.
+- **Fallback**: if the component can't be transpiled (missing / invalid `.tsx`), the framework
+  logs it and serves the built-in login page instead — a broken custom page can't take the server down.
+- **esm.sh deps**: the browser loads `@frontmcp/ui/auth` from esm.sh via the import-map; in an
+  unpublished monorepo, map it to a local URL via `@FrontMcp({ ui: { cdnOverrides } })` (see the reference).
+- **No PII**: the user's email lives in your `<form>`'s `email` input, never in `AuthFlowState`.

package/catalog/frontmcp-auth-ui/examples/custom-auth-ui/multi-step-auth-extra.md

@@ -0,0 +1,133 @@
+---
+name: multi-step-auth-extra
+reference: custom-auth-ui
+level: advanced
+description: "Add a server-validated multi-step field to a custom login page with auth.extras: { 'envs:add': fn }, useExtraField, and useAddedItems — accepted rows accumulate server-side and reflect back without a reload."
+tags: [auth, auth-ui, auth-extras, useExtraField, useAddedItems, multi-step, react]
+features:
+  - "Declaring a server-validated field as an `auth.extras['envs:add']` handler fn returning `{ ok, error?, addedItems? }`"
+  - 'Rejecting bad input and duplicates using `ctx.current` (the items already accepted for this extra in this flow)'
+  - "Binding the add-row form to `useExtraField('envs:add').onSubmit` (POSTs to `/oauth/ui/extra` with `pending_auth_id` + `csrf` attached)"
+  - "Reflecting the server-side accumulator reactively with `useAddedItems('envs:add')` after each successful add"
+  - 'Declaring both the `auth.ui` slot and the `auth.extras` handler under `auth`: `@FrontMcp({ auth: { mode, ui, extras } })`'
+---
+
+# Multi-Step Field with `auth.extras`
+
+Add a server-validated multi-step field to a custom login page with auth.extras: { 'envs:add': fn }, useExtraField, and useAddedItems — accepted rows accumulate server-side and reflect back without a reload.
+
+An `auth.extras[name]` handler adds a side endpoint the page POSTs to mid-flow (without finishing
+the authorization). Each accepted submission is appended to a per-`(pending-auth, extra)`
+accumulator the framework keeps; the response carries the full accumulator back so the page
+refreshes via `useAddedItems` without a reload. CSRF is verified server-side on every POST.
+
+## Code
+
+```ts
+// src/auth/extras.ts — the extra handler (a plain function, no class)
+import { type AuthExtraContext } from '@frontmcp/sdk';
+
+// Validates an "add environment variable" submission and accumulates accepted rows.
+export async function addEnv(input: Record<string, unknown>, ctx: AuthExtraContext) {
+  const key = typeof input['key'] === 'string' ? input['key'].trim() : '';
+  if (!key) return { ok: false as const, error: 'key is required' };
+  // ctx.current = rows already accepted for this extra in this pending auth.
+  if (ctx.current.some((it) => (it as { key?: string }).key === key)) {
+    return { ok: false as const, error: `"${key}" was already added` };
+  }
+  const value = typeof input['value'] === 'string' ? input['value'] : '';
+  // `addedItems` is the list of NEW rows to APPEND on success; the framework
+  // returns the FULL accumulator map back to the client.
+  return { ok: true as const, addedItems: [{ key, value }] };
+}
+```
+
+```tsx
+// src/auth/login.tsx — the custom component (default export)
+import React from 'react';
+
+import { AuthPageWrapper, useAddedItems, useAuthFlow, useExtraField } from '@frontmcp/ui/auth';
+
+export default function LoginPage(): React.ReactElement {
+  const { clientName, error, submitFinish } = useAuthFlow();
+  // Reactive view of the server-side accumulator for the 'envs:add' extra.
+  const envs = useAddedItems<{ key: string; value: string }>('envs:add');
+  // onSubmit POSTs to /oauth/ui/extra with pending_auth_id + csrf attached.
+  const addEnv = useExtraField('envs:add');
+
+  return (
+    <AuthPageWrapper>
+      <h1>Connect {clientName ?? 'the application'}</h1>
+      {error && <p className="error">{error}</p>}
+
+      <ul data-testid="env-list">
+        {envs.map((e) => (
+          <li key={e.key}>
+            {e.key}={e.value}
+          </li>
+        ))}
+      </ul>
+
+      {/* validated extra field — routes to auth.extras['envs:add'] */}
+      <form onSubmit={addEnv.onSubmit}>
+        <input name="key" placeholder="KEY" />
+        <input name="value" placeholder="value" />
+        <button disabled={addEnv.pending}>Add</button>
+        {addEnv.result && !addEnv.result.ok && <span className="error">{addEnv.result.error}</span>}
+      </form>
+
+      {/* finish — posts pending_auth_id + csrf and follows the OAuth redirect */}
+      <form onSubmit={submitFinish}>
+        <input name="email" type="email" />
+        <button type="submit">Authorize</button>
+      </form>
+    </AuthPageWrapper>
+  );
+}
+
+// The SDK appends `mountAuthPage(LoginPage)` to the inlined module automatically — a
+// `file`-based component only needs a default export.
+```
+
+```ts
+// src/server.ts — declare BOTH the slot and the extra UNDER `auth`
+import { FrontMcp } from '@frontmcp/sdk';
+
+import { addEnv } from './auth/extras';
+
+@FrontMcp({
+  info: { name: 'MyServer', version: '1.0.0' },
+  // `ui` / `extras` are scoped to this auth config (per-app under splitByApp).
+  // The login path is relative + auto-anchored to THIS file — no fileURLToPath.
+  auth: {
+    mode: 'local',
+    requireEmail: false,
+    ui: { login: './auth/login.tsx' },
+    extras: { 'envs:add': addEnv },
+  },
+})
+export default class Server {}
+```
+
+## What This Demonstrates
+
+- Declaring a server-validated field as an `auth.extras['envs:add']` handler fn returning `{ ok, error?, addedItems? }`
+- Rejecting bad input and duplicates using `ctx.current` (the items already accepted for this extra in this flow)
+- Binding the add-row form to `useExtraField('envs:add').onSubmit` (POSTs to `/oauth/ui/extra` with `pending_auth_id` + `csrf` attached)
+- Reflecting the server-side accumulator reactively with `useAddedItems('envs:add')` after each successful add
+- Declaring both the `auth.ui` slot and the `auth.extras` handler under `auth`: `@FrontMcp({ auth: { mode, ui, extras } })`
+
+## Notes
+
+- **Wire shape**: a successful `POST /oauth/ui/extra` returns `{ ok: true, addedItems: { 'envs:add': [...] } }`
+  (the FULL accumulator map keyed by extra name). `useExtraField` merges it into context so
+  `useAddedItems` re-renders.
+- **Validation errors**: a rejected submit returns HTTP 400 with `{ ok: false, error }`; surface
+  `addEnv.result.error` in the form.
+- **CSRF**: the framework verifies the `csrf` token (minted at SSR time) on every extra POST and
+  on the finish submit — a mismatch is rejected 400. The hooks attach it for you; never generate
+  or check it in your component.
+- **PII-free `ctx`**: the handler's `ctx` is `{ name, pendingAuthId?, current }` only — no user
+  identity is passed to it.
+- **Persistence**: the accumulator is in-memory and keyed by the opaque pending-auth id (10-minute
+  TTL), so it survives across re-renders within one authorization but not across server restarts.