@buildbase/sdk 0.0.53 → 0.0.55

package/README.md

@@ -7,6 +7,7 @@ Also works server-side (Next.js API routes, Express, Hono) — see [Server-Side
 ## 📑 Table of Contents
 
 - [Features](#-features)
+- [Customization Map](#-customization-map)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [UI Configuration](#️-ui-configuration)
@@ -19,6 +20,7 @@ Also works server-side (Next.js API routes, Express, Hono) — see [Server-Side
 - [Trial Gates](#-trial-gates)
 - [Push Notifications](#-push-notifications)
 - [Notifications](#-notifications)
+- [Connected Agents](#-connected-agents)
 - [User Management](#-user-management)
 - [Workspace Management](#-complete-workspace-management)
 - [Public Pricing (No Login)](#-public-pricing-no-login)
@@ -52,6 +54,7 @@ Also works server-side (Next.js API routes, Express, Hono) — see [Server-Side
 - **⏳ Trial Gates** - `WhenTrialing`, `WhenNotTrialing`, `WhenTrialEnding` components + `useTrialStatus` hook
 - **🔔 Push Notifications** - Browser push notifications with `usePushNotifications` hook, auto-triggers for billing events, and campaign management
 - **📬 Notifications** - Email + push notification system with per-event channel control, workspace preferences, and server-side `notification.send()` API
+- **🔌 Connected Agents** - `<ConnectedAgents />` screen to list/revoke authorized AI agents, plus a built-in "Connect an agent" setup guide (ChatGPT, Claude, Cursor, VS Code, Windsurf, Cline) driven by an `mcp` provider prop
 - **💺 Seat-Based Pricing** - Per-seat billing with included seats, billable seat tracking, and seat limit enforcement
 - **💱 Multi-Currency** - Per-currency pricing variants with workspace billing currency lock
 - **🤝 Affiliate Tracking** - Pass referral data to Stripe checkout via `getCheckoutStripeParams` prop (Rewardful, Endorsely, FirstPromoter, etc.)
@@ -66,6 +69,31 @@ Also works server-side (Next.js API routes, Express, Hono) — see [Server-Side
 - **🌐 Internationalization (i18n)** - 8 locales (en, es, fr, de, ja, zh, hi, ar), ICU MessageFormat, RTL support, native numerals
 - **🏠 Workspace Modes** - Personal (solo B2C) or Platform (multi-user B2B), configured from admin dashboard
 
+## 🎨 Customization Map
+
+Everything the SDK lets you configure, override, or extend — one row per knob, so you can see the whole surface before reading any deep-dive section. The philosophy throughout: **safe defaults, everything overridable, the SDK accelerates but never gates.**
+
+| What you customize                     | How                                                                                                                                                                        | Where to read more                                                                |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Provider setup & workspace behavior    | `<SaaSOSProvider>` / `<BuildBaseProvider>` props (`serverUrl`, `orgId`, `locale`, workspace auto-create, redirects)                                                        | [Configuration Reference](#️-configuration-reference)                              |
+| Which SDK UI renders at all            | `ui` prop: hide/show settings sections, workspace switcher, per-screen toggles                                                                                             | [UI Configuration](#️-ui-configuration) · `docs/UI-CONFIG.md`                      |
+| Every user-facing string               | `ui.messages` deep-override (e.g. rename "Subscription" → "Billing"), per-locale                                                                                           | [UI Configuration](#️-ui-configuration)                                            |
+| Language & number systems              | `locale` prop — 8 locales, ICU plurals, RTL (`ar`), native numerals                                                                                                        | [Internationalization](#-internationalization-i18n)                               |
+| Look & feel                            | CSS custom properties (`--primary`, `--destructive`, …) — semantic tokens, light/dark, no palette lock-in                                                                  | `docs/THEMING.md`                                                                 |
+| Date/number formats                    | `ui.formats` (`Intl` options passed through)                                                                                                                               | `docs/UI-CONFIG.md`                                                               |
+| Conditional UI                         | Gate components: `WhenAuthenticated`, `WhenPermission`, `WhenWorkspaceFeatureEnabled`, `WhenSubscription`, `WhenTrialing`, `WhenQuotaAvailable`, `WhenCreditsAvailable`, … | [Subscription Gates](#-subscription-gates) & siblings                             |
+| Checkout behavior                      | `getCheckoutStripeParams` (affiliate/referral params), plan-picker behavior config                                                                                         | [Affiliate Tracking](#affiliate--referral-tracking)                               |
+| Connect-an-agent guide                 | `mcp` prop (`url`, `name`, `docsUrl`, `clients`, `prompt`) → in-app setup guide + `<ConnectedAgents />` screen                                                             | [Connected Agents](#-connected-agents)                                            |
+| Error presentation                     | `ui.errorBoundary`, centralized `handleError` reporting                                                                                                                    | [Error Handling](#️-error-handling)                                                |
+| React-free server access               | `BuildBase()` factory — workspaces, usage, credits, notifications from API routes/jobs                                                                                     | [Server-Side Usage](#server-side-usage)                                           |
+| Agent discovery surface                | `createAgentStack` / `resolveAgentPath`: robots.txt, llms.txt, `.well-known/*`, all documents overridable (e.g. `config.llmsTxt`)                                          | [Agent Readiness](#agent-readiness-discovery) · `docs/MCP-AND-AGENT-READINESS.md` |
+| MCP tools                              | `builtinTools` (`'readonly'`/`'all'`/`false`/include/exclude) + your own via `defineMcpTool` (custom tools override built-ins)                                             | [MCP Server](#mcp-server-buildbasesdkmcp)                                         |
+| MCP resources & prompts                | Opt-in `builtinResources` catalog + `defineMcpResource`/`defineMcpResourceTemplate`/`defineMcpPrompt`                                                                      | [MCP Server](#mcp-server-buildbasesdkmcp)                                         |
+| MCP auth & hardening                   | `auth.verify` (your token format) or `buildbaseAuth` preset; `rateLimit`, `cors`, `allowedOrigins`, `formatToolError`                                                      | `docs/MCP-AND-AGENT-READINESS.md`                                                 |
+| Per-request context for your MCP tools | `context(auth, req)` factory → `ctx.custom` (your DB, services)                                                                                                            | [MCP Server](#mcp-server-buildbasesdkmcp)                                         |
+| Money display                          | `formatMinorAmountIntl`/`formatCents`/`getCurrencyDecimals` — full ISO 4217 (0/2/3-decimal currencies)                                                                     | [Multi-Currency](#-multi-currency--pricing-utilities)                             |
+| Webhooks from the platform             | `verifyWebhookSignature` (HMAC, timing-safe)                                                                                                                               | [Webhook Verification](#webhook-verification)                                     |
+
 ## Installation
 
 ```bash
@@ -87,6 +115,7 @@ import '@buildbase/sdk/css';
 // components/provider.tsx
 'use client';
 
+// BuildBaseProvider is an identical brand-aligned alias — prefer it in new code
 import { SaaSOSProvider } from '@buildbase/sdk/react';
 import { ApiVersion } from '@buildbase/sdk';
 
@@ -283,7 +312,7 @@ function MembersPanel() {
 
 `useUIConfig()` gives you the raw `ui` object if you only need the config values; `mergeUIConfig(base, override)` is the deep-merge used for per-dialog overrides.
 
-📖 **Full guide with the complete toggle reference, precedence rules, and recipes (single-tenant, external billing, white-label, read-only): [docs/UI-CONFIG.md](./docs/UI-CONFIG.md)**
+📖 **Full guide with the complete toggle reference, precedence rules, and recipes (single-tenant, external billing, white-label, read-only): [docs/UI-CONFIG.md](https://unpkg.com/@buildbase/sdk/docs/UI-CONFIG.md)**
 
 ## 🔐 Authentication
 
@@ -346,9 +375,16 @@ openWorkspaceSettings('users'); // Workspace members
 openWorkspaceSettings('subscription'); // Plan & Billing
 openWorkspaceSettings('usage'); // Quota usage dashboard
 openWorkspaceSettings('features'); // Feature toggles
+openWorkspaceSettings('connected-agents'); // Connected AI agents + connect guide
 openWorkspaceSettings('danger'); // Delete workspace (owner only)
 ```
 
+Some sections accept an optional second `action` argument to deep-link past the screen. For connected agents, open the setup guide directly:
+
+```tsx
+openWorkspaceSettings('connected-agents', { action: 'openConnectGuide' });
+```
+
 ### Authentication Components
 
 For declarative rendering, use the conditional components:
@@ -504,7 +540,9 @@ Use the `useUserFeatures` hook to check feature flags programmatically:
 import { useUserFeatures } from '@buildbase/sdk/react';
 
 function FeatureCheck() {
-  const { features, isFeatureEnabled, refreshFeatures } = useUserFeatures();
+  // { features, isFeatureEnabled, loading, error, refetch }
+  // (the older `isLoading` / `refreshFeatures` names still work but are deprecated)
+  const { features, isFeatureEnabled, refetch } = useUserFeatures();
 
   return (
     <div>{isFeatureEnabled('premium-features') ? <PremiumContent /> : <StandardContent />}</div>
@@ -1074,6 +1112,57 @@ Platform mode supports granular overrides from the admin dashboard:
 
 These let you achieve team-like, managed, or enterprise-like behavior without a separate mode.
 
+## 🔌 Connected Agents
+
+Let users connect AI agents to their account and manage them. `<ConnectedAgents />` is a ready-made screen (also a workspace settings section) that lists the agents a user has authorized — each with a **Disconnect** action — and, when you provide an MCP server address, shows a **Connect an agent** button that opens a plain-language setup guide.
+
+### Enable the connect guide
+
+Pass an `mcp` config to the provider. Without it the screen still lists and revokes agents; with it, the "Connect an agent" button and setup dialog appear.
+
+```tsx
+<SaaSOSProvider
+  // ...serverUrl, orgId, auth
+  mcp={{
+    url: 'https://app.example.com/api/mcp', // your MCP server endpoint (required to show the guide)
+    name: 'Acme', // friendly name used in prose + config snippets
+    docsUrl: 'https://docs.example.com/agents', // optional "Learn more" link
+  }}
+>
+```
+
+The dialog walks users through the major AI apps — **ChatGPT, Claude, Cursor, VS Code, Windsurf, Cline** — each with the exact click-path or config-file snippet (your server URL is filled in for them), plus a copy-and-paste prompt for chat assistants. It's fully translated (all 8 locales), RTL-aware, and responsive (full-screen on mobile, centered card on desktop).
+
+### The screen
+
+```tsx
+import { ConnectedAgents } from '@buildbase/sdk/react';
+
+function AgentsPage() {
+  return <ConnectedAgents />;
+}
+```
+
+Props: `title`, `description`, `disconnectLabel`, `emptyLabel` (all default to translated strings; pass `null` to hide the heading) and `showConnectGuide` (default `true` — set `false` to hide the connect button even when `mcp` is configured).
+
+Because it's a settings section, you can also open it programmatically:
+
+```tsx
+const { openWorkspaceSettings } = useSaaSAuth();
+
+openWorkspaceSettings('connected-agents'); // the screen (list + connect button)
+openWorkspaceSettings('connected-agents', { action: 'openConnectGuide' }); // straight to the setup dialog
+```
+
+The same deep link works via URL: `?bb=action:openConnectGuide`.
+
+### Custom UI
+
+- **`useConnectedAgents()`** — headless `{ agents, loading, error, revoking, refresh, revoke }` for a fully custom list.
+- **`useMcpConnection()`** — the `mcp` config you passed (or `null`), for building your own guide.
+- **`<ConnectMcpGuide />`** — the guide body on its own (copyable server URL + paste-in prompt + per-client accordion), embeddable anywhere. Override the app list via `mcp.clients` and the prompt via `mcp.prompt` (`false` hides it).
+- **`fillMcpTemplate` / `mcpServerKey`** — the placeholder helpers (`{{url}}` / `{{name}}` / `{{key}}`) for building custom client snippets.
+
 ## 👤 User Management
 
 ### User Attributes
@@ -1084,8 +1173,9 @@ Manage custom user attributes (key-value pairs):
 import { useUserAttributes } from '@buildbase/sdk/react';
 
 function UserProfile() {
-  const { attributes, isLoading, updateAttribute, updateAttributes, refreshAttributes } =
-    useUserAttributes();
+  // { attributes, loading, error, refetch, updateAttribute, updateAttributes }
+  // (the older `isLoading` / `refreshAttributes` names still work but are deprecated)
+  const { attributes, loading, updateAttribute, updateAttributes, refetch } = useUserAttributes();
 
   const handleUpdate = async () => {
     // Update single attribute
@@ -1245,19 +1335,23 @@ Plans support **pricing variants** (multi-currency). Use these utilities for dis
 
 ### Currency utilities
 
-| Export                               | Purpose                                                   |
-| ------------------------------------ | --------------------------------------------------------- |
-| `CURRENCY_DISPLAY`                   | Map of currency code → symbol (e.g. `usd` → `$`)          |
-| `CURRENCY_FLAG`                      | Map of currency code → flag emoji                         |
-| `PLAN_CURRENCY_CODES`                | Allowed billing currency codes (for dropdowns/validation) |
-| `PLAN_CURRENCY_OPTIONS`              | Options array for plan currency selects                   |
-| `getCurrencySymbol(currency)`        | Symbol for a Stripe currency code                         |
-| `getCurrencyFlag(currency)`          | Flag emoji for a currency code                            |
-| `formatCents(cents, currency)`       | Format cents as localized price string                    |
-| `formatOverageRate(cents, currency)` | Format overage rate for display                           |
-| `formatOverageRateWithLabel(...)`    | Overage rate with optional unit label                     |
-| `formatQuotaIncludedOverage(...)`    | "X included, then $Y / unit" style text                   |
-| `getQuotaUnitLabelFromName(name)`    | Human-readable unit label from quota name                 |
+| Export                                             | Purpose                                                         |
+| -------------------------------------------------- | --------------------------------------------------------------- |
+| `CURRENCY_DISPLAY`                                 | Map of currency code → symbol (e.g. `usd` → `$`)                |
+| `CURRENCY_FLAG`                                    | Map of currency code → flag emoji                               |
+| `PLAN_CURRENCY_CODES`                              | Allowed billing currency codes (for dropdowns/validation)       |
+| `PLAN_CURRENCY_OPTIONS`                            | Options array for plan currency selects                         |
+| `getCurrencySymbol(currency)`                      | Symbol for a Stripe currency code                               |
+| `getCurrencyFlag(currency)`                        | Flag emoji for a currency code                                  |
+| `formatCents(cents, currency)`                     | Format a minor-unit amount with the symbol table                |
+| `formatMinorAmountIntl(amount, currency, locale?)` | Locale-aware `Intl` money formatting of minor units             |
+| `getCurrencyDecimals(currency)`                    | ISO 4217 minor-unit digits (0 JPY, 2 USD, 3 KWD; CLDR fallback) |
+| `isZeroDecimalCurrency(currency)`                  | True when the currency has no minor unit (JPY, KRW, …)          |
+| `minorAmountToDisplay(amount, currency)`           | Minor units → display number string (no symbol)                 |
+| `formatOverageRate(cents, currency)`               | Format overage rate for display                                 |
+| `formatOverageRateWithLabel(...)`                  | Overage rate with optional unit label                           |
+| `formatQuotaIncludedOverage(...)`                  | "X included, then $Y / unit" style text                         |
+| `getQuotaUnitLabelFromName(name)`                  | Human-readable unit label from quota name                       |
 
 ### Pricing variant utilities
 
@@ -1297,7 +1391,9 @@ import {
 const variant = getPricingVariant(planVersion, 'usd');
 const cents = getBasePriceCents(planVersion, 'usd', 'monthly');
 if (cents != null) {
-  console.log(getCurrencySymbol('usd') + (cents / 100).toFixed(2));
+  // Never divide by 100 yourself — formatCents applies the currency's ISO 4217
+  // minor-unit factor (JPY ¥1,000 stays whole, KWD divides by 1000, USD by 100).
+  console.log(formatCents(cents, 'usd')); // "$12.99"
 }
 
 // Quota display with overage
@@ -2067,7 +2163,7 @@ import { eventEmitter } from '@buildbase/sdk';
 
 ## 🛡️ Error Handling
 
-The SDK handles errors internally: API failures, auth errors, and component errors are logged and surfaced through hook states (e.g. `error` from `useSaaSWorkspaces`) and callbacks. **SaaSOSProvider** wraps its children in an internal **SDKErrorBoundary** to catch React render errors inside the SDK tree. For app-level errors, wrap your app (or routes) in your own error boundary (e.g. React’s `ErrorBoundary` or your framework’s error UI). For failed async operations, check the `error` property on hooks and show user feedback (e.g. toast or inline message). See [Error codes](docs/ERROR_CODES.md) for SDK error codes and HTTP mappings.
+The SDK handles errors internally: API failures, auth errors, and component errors are logged and surfaced through hook states (e.g. `error` from `useSaaSWorkspaces`) and callbacks. **SaaSOSProvider** wraps its children in an internal **SDKErrorBoundary** to catch React render errors inside the SDK tree. For app-level errors, wrap your app (or routes) in your own error boundary (e.g. React’s `ErrorBoundary` or your framework’s error UI). For failed async operations, check the `error` property on hooks and show user feedback (e.g. toast or inline message). See [Error codes](https://unpkg.com/@buildbase/sdk/docs/ERROR_CODES.md) for SDK error codes and HTTP mappings.
 
 ## ⚙️ Settings
 
@@ -2077,7 +2173,11 @@ Access OS-level settings:
 import { useSaaSSettings } from '@buildbase/sdk/react';
 
 function SettingsExample() {
-  const { settings, getSettings } = useSaaSSettings();
+  // { settings, loading, error, refetch } — `loading` is true until the one-time
+  // fetch settles, so you can wait instead of rendering with partial defaults.
+  const { settings, loading, refetch } = useSaaSSettings();
+
+  if (loading) return <Spinner />;
 
   return (
     <div>
@@ -2155,9 +2255,11 @@ Prefer these SDK hooks for state and operations instead of `useAppSelector`:
 | `useSaaSAuth()`             | Auth state (user, session, status), signIn(returnUrl?), signOut, openWorkspaceSettings                                                                                                                                                                                    |
 | `useSaaSWorkspaces()`       | Workspaces, currentWorkspace, loading, switching/switchingToId, CRUD and switch actions                                                                                                                                                                                   |
 | `useSaaSOs()`               | OS config (serverUrl, version, orgId, auth, settings) when you need the full config object                                                                                                                                                                                |
-| `useSaaSSettings()`         | Organization settings and getSettings (prefer this when you only need settings)                                                                                                                                                                                           |
-| `useUserAttributes()`       | User attributes and update/refresh                                                                                                                                                                                                                                        |
-| `useUserFeatures()`         | User feature flags                                                                                                                                                                                                                                                        |
+| `useSaaSSettings()`         | Organization settings — `{ settings, loading, error, refetch }` (prefer this when you only need settings)                                                                                                                                                                 |
+| `useUserAttributes()`       | User attributes — `{ attributes, loading, error, refetch, updateAttribute, updateAttributes }`                                                                                                                                                                            |
+| `useUserFeatures()`         | User feature flags — `{ features, isFeatureEnabled, loading, error, refetch }`                                                                                                                                                                                            |
+| `useConnectedAgents()`      | Authorized AI agents — `{ agents, loading, error, revoking, refresh, revoke }`                                                                                                                                                                                            |
+| `useMcpConnection()`        | The `mcp` connection config passed to the provider (or `null`), for a custom connect guide                                                                                                                                                                                |
 | `useSubscriptionContext()`  | Subscription for current workspace (response, loading, refetch); use inside SubscriptionContextProvider                                                                                                                                                                   |
 | `useTrialStatus()`          | Trial state: `isTrialing`, `daysRemaining`, `trialEndsAt`, `isTrialEnding`                                                                                                                                                                                                |
 | `usePushNotifications()`    | Push notification state and actions: `isSubscribed`, `subscribe()`, `unsubscribe()`                                                                                                                                                                                       |
@@ -2177,12 +2279,12 @@ Using hooks keeps your code stable if internal state shape changes and avoids di
 
 ### Types
 
-All TypeScript types are exported for type safety. See the [TypeScript definitions](./dist/index.d.ts) for complete type information.
+All TypeScript types are exported for type safety. See the [TypeScript definitions](https://unpkg.com/@buildbase/sdk/dist/index.d.ts) for complete type information.
 
 ### Further documentation
 
-- [Architecture](docs/ARCHITECTURE.md) – Layers, providers, APIs (BaseApi, UserApi, WorkspaceApi, SettingsApi), state, auth flow
-- [Error codes](docs/ERROR_CODES.md) – SDK error codes and HTTP status mappings
+- [Architecture](https://unpkg.com/@buildbase/sdk/docs/ARCHITECTURE.md) – Layers, providers, APIs (BaseApi, UserApi, WorkspaceApi, SettingsApi), state, auth flow
+- [Error codes](https://unpkg.com/@buildbase/sdk/docs/ERROR_CODES.md) – SDK error codes and HTTP status mappings
 
 ## ⚙️ Configuration Reference
 
@@ -2935,7 +3037,11 @@ app.post('/webhooks/buildbase', (req, res) => {
 
 ## Agent Readiness (Discovery)
 
-Make a consuming app [agent ready](https://isitagentready.com) by serving the standard machine-readable discovery documents an AI agent looks for — Agent Card, OAuth metadata (RFC 8414/9728), Agent Skills, API Catalog (RFC 9727), MCP Server Card, `robots.txt` with AI-bot rules + Content Signals, `sitemap.xml`, `security.txt` (RFC 9116), `llms.txt`, and `auth.md` — with the BuildBase server as the source of truth. Framework-agnostic and zero React: every function returns a plain `DiscoveryDocument` (`{ status, contentType, body, cacheControl, vary? }`); you wire it into your own router.
+> **Full guide:** [`docs/MCP-AND-AGENT-READINESS.md`](https://unpkg.com/@buildbase/sdk/docs/MCP-AND-AGENT-READINESS.md) covers the whole surface — the fast path, the auth model, and the scope/resource customization spectrum. This section is the overview.
+
+Make a consuming app [agent ready](https://isitagentready.com) by serving the machine-readable discovery documents an AI client looks for — Agent Card, A2A card, OAuth metadata (RFC 8414/9728), Agent Skills, API Catalog (RFC 9727), MCP Server Card (SEP-1649 v1.0) + discovery manifest (SEP-1960), `robots.txt` with AI-bot rules + Content Signals, `sitemap.xml`, `security.txt`, `llms.txt`/`llms-full.txt`, and `auth.md`. Framework-agnostic and zero React: every function returns a plain `DiscoveryDocument` (`{ status, contentType, body, cacheControl, vary? }`).
+
+The fast path is [`createAgentStack`](https://unpkg.com/@buildbase/sdk/docs/MCP-AND-AGENT-READINESS.md#fast-path--createagentstack) — one config derives the MCP handler **and** the whole discovery surface. To wire the discovery layer on its own, use `resolveAgentPath`:
 
 ```ts
 // lib/agent-ready.ts
@@ -2944,14 +3050,18 @@ import { resolveAgentPath, type AgentReadyConfig } from '@buildbase/sdk';
 export const agentConfig: AgentReadyConfig = {
   serverUrl: process.env.BUILDBASE_URL!,
   orgId: process.env.BUILDBASE_ORG_ID!,
-  siteUrl: 'https://imejis.io',
-  site: { name: 'Imejis', description: 'Generate images from templates via API.' },
+  siteUrl: 'https://example.com',
+  site: { name: 'Acme', description: 'Generate images from templates via API.' },
   // Discovery content is YOURS — defined here in code, not in the platform:
-  llmsTxt: '# Imejis\n\n> Generate images from templates via API.',
+  scopes: [
+    { name: 'designs:read', description: 'View designs' },
+    { name: 'render:execute', description: 'Render images' },
+  ],
+  llmsTxt: '# Acme\n\n> Generate images from templates via API.',
   robots: { contentSignals: { search: true, aiInput: true, aiTrain: false } },
   sitemap: { urls: ['/', '/pricing'] }, // omit if you already generate sitemaps
-  protectedResources: [{ scopes: ['read:profile', 'write:posts'] }], // RFC 9728
-  // skills, security, apiCatalog, mcpServerCard, authMd, cacheTtlSeconds — all optional
+  protectedResources: [{ resource: 'https://example.com/mcp' }], // scopes inherited from catalog
+  // skills, security, apiCatalog, mcpServerCard, a2aCard, extraPaths — all optional
 };
 
 export async function serveAgentPath(req: Request): Promise<Response> {
@@ -3031,21 +3141,61 @@ Clean split, no duplication: **your app owns discovery content, the platform own
 | llms.txt                                                   | `buildLlmsTxt`                                                             |
 | MCP Server Card + live MCP server                          | `buildMcpServerCard` + [`@buildbase/sdk/mcp`](#mcp-server-buildbasesdkmcp) |
 | Agent Skills / API Catalog                                 | `buildAgentSkillsIndex` / `buildApiCatalog`                                |
+| A2A Agent Card                                             | `buildA2AAgentCard` (served by default from `site` + `skills`)             |
 | OAuth discovery (RFC 8414) + protected resource (RFC 9728) | `resolveAgentPath` (platform-backed)                                       |
-| DNS-AID                                                    | out of SDK scope — add the DNS record at your registrar                    |
-| Web Bot Auth, commerce (x402/ACP/UCP)                      | not yet — planned                                                          |
+| Web Bot Auth                                               | `buildWebBotAuthDirectory` (opt-in — publish your JWKS)                    |
+| DNS-AID                                                    | `buildDnsAidRecords` (returns records — publish at your DNS provider)      |
+| Commerce (x402/ACP/UCP/MPP), openapi.json                  | `config.extraPaths` (serve any literal document by path)                   |
 
-**Functions:** `resolveAgentPath`, `resolveWellKnown`, `fetchAgentReadiness`, `clearAgentReadinessCache`, `buildAgentCard`, `buildProtectedResourceMetadata`, `buildAgentSkillsIndex`, `buildSkillMd`, `buildSecurityTxt`, `buildLlmsTxt`, `buildRobotsTxt`, `buildSitemap`, `buildApiCatalog`, `buildMcpServerCard`, `buildAuthMd`, `buildDiscoveryLinkHeader`, `wantsMarkdown`, `negotiateMarkdown`, `provideWebMcpTools`, `sha256Digest`. **Constants:** `AI_BOT_USER_AGENTS`. **Types:** `AgentReadyConfig`, `AgentReadinessBundle`, `AgentSkill`, `ApiCatalogApi`, `McpServerCard`, `RobotsConfig`, `RobotsPolicy`, `ContentSignals`, `SitemapUrl`, `WebMcpTool`, `DiscoveryDocument`.
+**Functions:** `resolveAgentPath`, `resolveWellKnown`, `fetchAgentReadiness`, `clearAgentReadinessCache`, `buildAgentCard`, `buildA2AAgentCard`, `buildProtectedResourceMetadata`, `buildAgentSkillsIndex`, `buildSkillMd`, `buildSecurityTxt`, `buildLlmsTxt`, `buildLlmsFullTxt`, `buildRobotsTxt`, `buildSitemap`, `buildApiCatalog`, `buildMcpServerCard`, `buildMcpDiscoveryManifest`, `buildAuthMd`, `buildWebBotAuthDirectory`, `buildDnsAidRecords`, `buildDiscoveryLinkHeader`, `wantsMarkdown`, `negotiateMarkdown`, `provideWebMcpTools`, `sha256Digest`. **Constants:** `AI_BOT_USER_AGENTS`. **Types:** `AgentReadyConfig`, `AgentReadinessBundle`, `AgentSkill`, `AppScope`, `ApiCatalogApi`, `A2ACardConfig`, `A2ACardSkill`, `DnsAidRecord`, `McpServerCard`, `RobotsConfig`, `RobotsPolicy`, `ContentSignals`, `SitemapUrl`, `WebMcpTool`, `DiscoveryDocument`.
 
 ## MCP Server (`@buildbase/sdk/mcp`)
 
-Turn your app into a **live MCP server** so AI agents can operate it: the built-in tools expose your BuildBase state (workspaces, subscription, quotas, credits, feature flags, permissions) and you add your own product tools with zod schemas. Stateless Streamable HTTP — pure functions plus a Web-standard `Request`/`Response` adapter, so it runs on Node 18+, edge, Deno, and Bun. Server-only, zero React; split from the core entry because it uses `zod` at runtime.
+> **Full guide:** [`docs/MCP-AND-AGENT-READINESS.md`](https://unpkg.com/@buildbase/sdk/docs/MCP-AND-AGENT-READINESS.md).
+
+Turn your app into a **live MCP server** so AI agents can operate it: the built-in tools expose your BuildBase state (workspaces, subscription, quotas, credits, feature flags, permissions) and you add your own product tools with zod schemas — plus **resources** (context a host loads without tool calls) and **prompts** (user-facing workflow templates). Stateless Streamable HTTP (MCP 2025-11-25, negotiating down to 2024-11-05) — pure functions plus a Web-standard `Request`/`Response` adapter, so it runs on Node 18+, edge, Deno, and Bun. Server-only, zero React; split from the core entry because it uses `zod` at runtime.
+
+The fast path bundles the server + the whole discovery surface from one config:
+
+```ts
+// lib/agent.ts
+import { createAgentStack, defineMcpTool } from '@buildbase/sdk/mcp';
+import { z } from 'zod';
+
+export const agent = createAgentStack({
+  serverUrl: process.env.NEXT_PUBLIC_BUILDBASE_SERVER_URL!,
+  orgId: process.env.NEXT_PUBLIC_BUILDBASE_ORG_ID!,
+  siteUrl: 'https://example.com',
+  site: { name: 'Acme', description: 'Generate images from templates via API.' },
+  secret: process.env.SYSTEM_SECRET!, // derives buildbaseAuth (verify + aud + sid decrypt)
+  scopes: [{ name: 'render:execute', description: 'Render images' }],
+  mcp: {
+    builtinTools: 'readonly',
+    tools: [
+      defineMcpTool({
+        name: 'generate_image',
+        description: 'Render an image from a template',
+        inputSchema: z.object({ templateId: z.string(), data: z.record(z.string(), z.any()) }),
+        requiredScopes: ['render:execute'],
+        execute: async (input, { bb, workspaceId }) => {
+          await bb.usage.record(workspaceId!, { quotaSlug: 'images', quantity: 1 });
+          return renderTemplate(input.templateId, input.data);
+        },
+      }),
+    ],
+  },
+});
+
+// app/api/mcp/route.ts
+export const { GET, POST, DELETE, OPTIONS } = agent.routes;
+```
+
+Prefer the primitives (own token format, unified web+agent auth)? Wire `createMcpHandler` + `buildbaseAuth` directly — `buildbaseAuth` does the full verify (HS256, RFC 8707 audience binding, `sid` decrypt) so you never hand-roll it:
 
 ```ts
 // lib/mcp.ts
 import BuildBase from '@buildbase/sdk';
-import { createMcpHandler, defineMcpTool, verifyClientJwt } from '@buildbase/sdk/mcp';
-import { z } from 'zod';
+import { createMcpHandler, defineMcpTool, buildbaseAuth } from '@buildbase/sdk/mcp';
 
 const buildbase = BuildBase({
   serverUrl: process.env.BUILDBASE_URL!,
@@ -3054,56 +3204,35 @@ const buildbase = BuildBase({
 
 export const mcp = createMcpHandler({
   buildbase,
-  serverInfo: { name: 'imejis', version: '1.0.0' },
-  auth: {
-    // Verify the Bearer token your app minted in the OAuth2 app-bridge flow
-    // and map it to the BuildBase session the tools run under.
-    verify: token => {
-      const c = verifyClientJwt(token, process.env.BUILDBASE_CLIENT_SECRET!);
-      return { sessionId: String(c.sid), userId: String(c.sub), scopes: c.scope as string[] };
-    },
-    // Unauthenticated requests get a 401 whose WWW-Authenticate header points
-    // here, so agents bootstrap the whole OAuth discovery flow (RFC 9728).
-    resourceMetadataUrl: 'https://imejis.io/.well-known/oauth-protected-resource',
-  },
-  builtinTools: 'readonly', // default; 'all' opts into the mutating tools
+  serverInfo: { name: 'acme', version: '1.0.0' },
+  auth: buildbaseAuth({
+    secret: process.env.SYSTEM_SECRET!,
+    resource: ['https://example.com/mcp', 'https://example.com/api/mcp'],
+    requireAudience: true,
+  }),
+  builtinTools: 'readonly',
   tools: [
-    defineMcpTool({
-      name: 'generate_image',
-      description: 'Render an image from a template',
-      inputSchema: z.object({ templateId: z.string(), data: z.record(z.string(), z.any()) }),
-      annotations: { readOnlyHint: false },
-      execute: async (input, { bb, workspaceId }) => {
-        await bb.usage.record(workspaceId!, { quotaSlug: 'images', quantity: 1 });
-        return renderTemplate(input.templateId, input.data);
-      },
-    }),
+    /* defineMcpTool(...) */
   ],
 });
 ```
 
 ```ts
-// app/api/mcp/route.ts  (Next.js App Router)
-import { mcp } from '@/lib/mcp';
-export const POST = (req: Request) => mcp.fetch(req);
-export const GET = (req: Request) => mcp.fetch(req); // 405 per spec (no SSE)
-export const DELETE = (req: Request) => mcp.fetch(req); // 405 (stateless)
-```
-
-```ts
-// Express — the pure form
+// Express / Fastify / Node — the pure form
 app.post('/mcp', async (req, res) => {
   const r = await mcp.handle({ method: req.method, headers: req.headers, body: req.body });
   res.status(r.status).set(r.headers).send(r.body);
 });
 ```
 
-Advertise it via the server card so agents find the endpoint:
+> **Copy-paste recipes for every framework** — Next.js (App + Pages Router), Express, Fastify, Hono, Bun, Deno, Cloudflare Workers, and React/SPA (WebMCP) — plus the per-framework mint route and a production checklist: [`docs/MCP-AND-AGENT-READINESS.md`](https://unpkg.com/@buildbase/sdk/docs/MCP-AND-AGENT-READINESS.md#framework-recipes). Two adapters cover them all: `mcp.fetch(Request)` (web standard — App Router, Hono, Bun, Deno, edge) and `mcp.handle({method,headers,body})` (pure — Express, Fastify, Pages Router).
+
+Advertise it via the server card so agents find the endpoint (the stack sets this automatically):
 
 ```ts
 export const agentConfig: AgentReadyConfig = {
   // ...
-  mcpServerCard: mcp.serverCard({ endpoint: 'https://imejis.io/api/mcp' }),
+  mcpServerCard: mcp.serverCard({ endpoint: 'https://example.com/api/mcp' }),
 };
 ```
 
@@ -3132,6 +3261,62 @@ The agent acts as an authenticated app user — it knows your app, not BuildBase
 
 Want per-scope gating on top? Set `requiredScopes` on your own custom tools and return the granted `scopes` from `auth.verify` — the handler hides a tool from `tools/list` (and refuses the call) when its `requiredScopes` aren't all granted. A token that carries **no** scopes sees only tools that require none (the built-ins), so a token minted without a `scope` claim can never unlock a scoped tool. Opt-in, using **your** scope names — the SDK never imposes its own.
 
+### Rich tool results (images, links, mixed content)
+
+Return any JSON-serializable value and the handler wraps it (string → text block; object → JSON text + `structuredContent`). For full control — images, audio, resource links, mixed blocks, or the `isError` flag — return a wire-shaped `McpToolResult` built with the exported helpers:
+
+```ts
+import { mcpImage, mcpResourceLink, mcpText } from '@buildbase/sdk/mcp';
+
+execute: async (input, ctx) => ({
+  content: [
+    mcpText('Revenue chart for Q2:'),
+    mcpImage(chartPngBase64, 'image/png'),
+    mcpResourceLink('https://app.example.com/reports/q2.pdf', 'q2-report'),
+  ],
+  structuredContent: { totalCents: 1_299_00, currency: 'usd' },
+});
+```
+
+### Resources & prompts
+
+Both are **opt-in**, and `initialize` capabilities only advertise what you actually configured — existing servers are byte-identical until you opt in.
+
+```ts
+createMcpHandler({
+  buildbase,
+  // Lean built-in context catalog: buildbase://profile, buildbase://workspaces,
+  // buildbase://workspace/{workspaceId}. Richer data stays tools-only.
+  builtinResources: true,
+  resources: [
+    defineMcpResource({
+      uri: 'app://docs/getting-started',
+      name: 'getting-started',
+      mimeType: 'text/markdown',
+      read: () => gettingStartedMarkdown, // string | object (JSON) | { text } | { blob }
+    }),
+  ],
+  resourceTemplates: [
+    defineMcpResourceTemplate({
+      uriTemplate: 'app://orders/{orderId}',
+      name: 'order',
+      read: (params, _uri, ctx) => ctx.custom.db.order.find(params.orderId),
+    }),
+  ],
+  prompts: [
+    defineMcpPrompt({
+      name: 'analyze_usage',
+      description: 'Review quota usage and suggest actions',
+      arguments: [{ name: 'workspaceId', required: true }],
+      get: async (args, ctx) =>
+        `Review this workspace's quota usage:\n${JSON.stringify(await ctx.bb.usage.getAll(args.workspaceId))}`,
+    }),
+  ],
+});
+```
+
+`requiredScopes` gates resources and prompts exactly like tools. Deliberately out of scope (the stateless transport has no push channel): resource subscriptions, `listChanged`, sampling, elicitation.
+
 ### Production hardening
 
 The handler ships with safe defaults; these are the knobs to review before going live:
@@ -3148,7 +3333,7 @@ export const mcp = createMcpHandler({
   buildbase,
   auth: { verify, resourceMetadataUrl },
   builtinTools: { include: ['get_quota_usage', 'record_usage'] },
-  allowedOrigins: ['https://app.imejis.io'],
+  allowedOrigins: ['https://app.example.com'],
   maxRequestBytes: 512 * 1024,
   rateLimit: async auth => ({ ok: await limiter.allow(auth?.userId), retryAfter: 30 }),
   onError: (err, ctx) => logger.error({ err, ...ctx }, 'mcp error'),
@@ -3187,21 +3372,25 @@ The SDK accelerates; it never gates. Everything BuildBase-specific is optional:
 
 ### Auth in one line of plumbing
 
-The OAuth2 app-bridge flow already mints your app's Bearer tokens (see [OAuth2 App Bridge](#oauth2-app-bridge)); `signClientJwt(payload, secret)` is the symmetric counterpart of `verifyClientJwt` for exactly that. The mint claims include `sessionId` — a per-user BuildBase session bound to the grant (fresh on every mint, including refresh). Embed it **encrypted** (JWTs are signed, not encrypted — the agent can read its own token) and keep it out of any storage, so it simply expires with the token; your MCP `auth.verify` decrypts it back into `McpAuthInfo.sessionId`:
+The OAuth2 app-bridge flow mints your app's Bearer tokens (see [OAuth2 App Bridge](#oauth2-app-bridge)). Use the presets and neither the mint nor the verify is hand-rolled — the per-user BuildBase session rides as an **encrypted `sid`** claim (JWTs are signed, not encrypted), never stored, expiring with the token:
 
 ```ts
-mintToken: (user) => ({
-  token: signClientJwt(
-    { sub: user.id, scope: user.scope, aud: user.resource, sid: encrypt(user.sessionId) },
-    process.env.BUILDBASE_CLIENT_SECRET!
-  ),
-  expiresIn: 3600,
-}),
+// mint (applicationTokenUrl) — HS256 with your secret, aud from the grant, encrypted sid
+import { mintAgentToken } from '@buildbase/sdk';
+mintToken: (claims) => mintAgentToken({ claims, secret: process.env.SYSTEM_SECRET! }),
+
+// verify (MCP server) — HS256 + RFC 8707 audience + sid decrypt → McpAuthInfo
+import { buildbaseAuth } from '@buildbase/sdk/mcp';
+auth: buildbaseAuth({ secret: process.env.SYSTEM_SECRET!, resource: 'https://example.com/mcp' }),
 ```
 
-Set `auth: false` to disable auth entirely (local development only). Test with the MCP Inspector: `npx @modelcontextprotocol/inspector --cli http://localhost:3000/api/mcp --transport http --header "Authorization: Bearer <token>" --method tools/list`.
+Bringing your own token format? `auth.verify(token, req) → McpAuthInfo` accepts any Bearer token; set `auth.resourceMetadataUrl` so 401s carry the RFC 9728 challenge. Set `auth: false` to disable auth (local dev only). Debug audience mismatches with `MCP_AUTH_DEBUG=1`. Test with the MCP Inspector: `npx @modelcontextprotocol/inspector --cli http://localhost:3000/api/mcp --transport http --header "Authorization: Bearer <token>" --method tools/list`.
+
+**Exports:** `createAgentStack`, `createMcpHandler`, `defineMcpTool`, `builtinMcpTools`, `selectBuiltinTools`, `buildbaseAuth`, `mintAgentToken`, `createSessionRefCrypto`, plus re-exported auth helpers (`signClientJwt`, `verifyClientJwt`, `extractBearerToken`, `bearerChallenge`, `AppBridgeError`). **Types:** `AgentStack`, `AgentStackConfig`, `CreateMcpHandlerConfig`, `McpHandler`, `McpToolDefinition`, `McpToolContext`, `McpAuthInfo`, `McpHttpRequest`, `McpHttpResponse`, `McpToolAnnotations`, `McpBuildBaseClient`, `BuiltinMcpToolName`, `BuildBaseAuthOptions`, `MintAgentTokenOptions`, `SessionRefCrypto`, `McpServerCard`, `ScopedActions`.
+
+### Scopes & resources — restrict or open up
 
-**Exports:** `createMcpHandler`, `defineMcpTool`, `builtinMcpTools`, `selectBuiltinTools`, plus re-exported auth helpers (`signClientJwt`, `verifyClientJwt`, `extractBearerToken`, `bearerChallenge`, `AppBridgeError`). **Types:** `CreateMcpHandlerConfig`, `McpHandler`, `McpToolDefinition`, `McpToolContext`, `McpAuthInfo`, `McpHttpRequest`, `McpHttpResponse`, `McpToolAnnotations`, `McpBuildBaseClient`, `BuiltinMcpToolName`, `McpServerCard`, `ScopedActions`.
+Scopes and resources are **app-owned** — the shared BuildBase authorization server stays scope/resource-agnostic. Scopes have three levers: **declare** a catalog (`scopes: [{ name, description }]` → `scopes_supported` in your own RFC 9728 protected-resource metadata), **gate per tool** (`requiredScopes` on a custom tool → hidden/refused unless the token carries them), and the **floor** (every tool runs under the user's BuildBase session, so the platform enforces the user's real permissions — an agent never exceeds the user). Resources have two: **declare** `protectedResources` (RFC 9728) and **bind** the token audience via `buildbaseAuth({ resource, requireAudience })` (RFC 8707) — the audience check at your resource is the whole gate. Built-ins are restricted with `builtinTools`, not scopes. Public clients (Claude Desktop, Cursor, Inspector) self-register with PKCE and no secret. Full model: [the guide](https://unpkg.com/@buildbase/sdk/docs/MCP-AND-AGENT-READINESS.md#scopes--resources-restrict-or-open-up).
 
 ## OAuth2 App Bridge
 
@@ -3212,6 +3401,8 @@ BuildBase runs the full OAuth2 authorization flow (login, consent, code, PKCE, r
 
 Both requests carry `Authorization: Bearer <JWT>`, an HS256 JWT signed with your client secret. This toolkit verifies those requests (timing-safe, no `alg` confusion) and shapes the exact response body the platform expects, so you write only the part that's yours: minting/invalidating a token in your own format.
 
+> For the common case, `mintToken: (claims) => mintAgentToken({ claims, secret })` is the preset — it signs HS256 with your secret, binds `aud` to the granted RFC 8707 resource, and embeds the encrypted `sid`. The examples below show the hand-rolled equivalent, for apps that mint their own token format (e.g. one shared with their web sessions). See [the guide](https://unpkg.com/@buildbase/sdk/docs/MCP-AND-AGENT-READINESS.md#auth-minting--verifying-the-token).
+
 ```ts
 // applicationTokenUrl handler (Next.js Pages Router)
 import { handleAppTokenRequest } from '@buildbase/sdk';
@@ -3251,7 +3442,7 @@ When an agent calls your protected API without a valid token, reply with an RFC
 import { bearerChallenge } from '@buildbase/sdk';
 
 const c = bearerChallenge({
-  resourceMetadataUrl: 'https://imejis.io/.well-known/oauth-protected-resource',
+  resourceMetadataUrl: 'https://example.com/.well-known/oauth-protected-resource',
   error: 'invalid_token',
 });
 res.writeHead(c.status, c.headers).end(c.body);
@@ -3295,7 +3486,9 @@ return res.json({ id: claims.id, email: claims.email /* … */ });
 
 The one-call handlers cover the common path; the underlying pieces are exported for custom flows: `verifyAppTokenRequest` / `verifyAppRevokeRequest` (verify → claims), `verifyClientJwt`, `extractBearerToken`, and the response builders `appTokenSuccess` / `appTokenFailure`. Verification throws `AppBridgeError` (with a machine-readable `code` like `invalid_signature`, `token_expired`, `invalid_algorithm`). HMAC verification uses the SDK's dependency-free pure-JS HMAC-SHA256, so it behaves identically under ESM, CJS, a bundler, or bare Node.
 
-**Types:** `AppTokenRequestClaims`, `AppRevokeRequestClaims`, `AppTokenResult`, `AppTokenResponseBody`, `HandlerResult`.
+**Presets** (also on the core entry): `mintAgentToken` (the whole mint — HS256 + `aud` + encrypted `sid`), `buildbaseAuth` (the whole verify), `createSessionRefCrypto` (the `sid` AES-256-GCM crypto). The platform relays the minted token but never sees your secret — it can neither forge nor decode your tokens.
+
+**Exports:** `handleAppTokenRequest`, `handleAppRevokeRequest`, `verifyAppTokenRequest`, `verifyAppRevokeRequest`, `verifyClientJwt`, `signClientJwt`, `extractBearerToken`, `bearerChallenge`, `appTokenSuccess`, `appTokenFailure`, `mintAgentToken`, `buildbaseAuth`, `createSessionRefCrypto`, `AppBridgeError`. **Types:** `AppTokenRequestClaims`, `AppRevokeRequestClaims`, `AppTokenResult`, `AppTokenResponseBody`, `HandlerResult`, `VerifyClientJwtOptions`, `BuildBaseAuthOptions`, `MintAgentTokenOptions`, `SessionRefCrypto`.
 
 ## 🤝 Contributing