@agent-native/core 0.7.4 → 0.7.7

package/docs/content/drop-in-agent.md

@@ -0,0 +1,200 @@
+---
+title: "Drop-in Agent"
+description: "Mount the agent chat + workspace into any React app with <AgentPanel>, <AgentSidebar>, and sendToAgentChat()."
+---
+
+# Drop-in Agent
+
+You don't need to build agent-native from scratch. The agent chat, workspace tab, CLI terminal, voice input, and all the related infrastructure ship as a handful of React components you drop into any app.
+
+> **Prerequisite:** the server has to be running the `agent-chat-plugin` (it auto-mounts in every template). If you're starting from scratch, see [Server](/docs/server).
+
+## The components at a glance {#components}
+
+| Component             | What it is                                                             | Use it when                                                     |
+| --------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `<AgentSidebar>`      | Wraps your app, adds a toggleable side panel containing the full agent | You want the agent available alongside your app on every screen |
+| `<AgentToggleButton>` | Opens/closes `<AgentSidebar>` (put it in your header)                  | Pair with `<AgentSidebar>`                                      |
+| `<AgentPanel>`        | The raw panel itself — chat + CLI + workspace tabs                     | You want full control over layout, or a dedicated agent page    |
+| `sendToAgentChat()`   | Programmatically send a message to the chat                            | A button that hands work to the agent instead of running inline |
+| `useActionMutation()` | Typesafe frontend wrapper around an action                             | The UI needs to run the same operation an agent tool would run  |
+
+All of these are exported from `@agent-native/core/client`.
+
+## The 80% case: `<AgentSidebar>` {#sidebar}
+
+The most common setup is a sidebar that slides in from the right on any screen. Two pieces — the wrapper and a header button:
+
+```tsx
+// app/root.tsx
+import { AgentSidebar, AgentToggleButton } from "@agent-native/core/client";
+
+export default function Root() {
+  return (
+    <AgentSidebar
+      emptyStateText="How can I help?"
+      suggestions={[
+        "Summarize my inbox",
+        "Draft a reply to the latest email",
+        "Show me yesterday's signup numbers",
+      ]}
+      sidebarWidth={420}
+      position="right"
+    >
+      <YourApp />
+    </AgentSidebar>
+  );
+}
+
+// somewhere in your header / navbar
+<AgentToggleButton />;
+```
+
+That's it. The user now has a toggleable agent on every page — with chat history, workspace tab, CLI terminal, voice input, and a fullscreen mode. State persists across reloads via `localStorage`.
+
+### Props
+
+- **`children`** — your app. Rendered in the main area; the sidebar overlays from the chosen side.
+- **`emptyStateText`** — greeting shown when the chat has no messages. Default: `"How can I help you?"`.
+- **`suggestions`** — starter prompts rendered as clickable chips when empty.
+- **`sidebarWidth`** — pixel width. Default: `380`.
+- **`position`** — `"left"` or `"right"`. Default: `"right"`.
+- **`defaultOpen`** — whether the sidebar starts open (desktop only). Default: `false`.
+
+## The other 20%: `<AgentPanel>` {#panel}
+
+When you need full control over layout — a dedicated `/chat` route, an embedded panel in a side column you manage, or a popup — render `<AgentPanel>` directly:
+
+```tsx
+// app/routes/agent.tsx
+import { AgentPanel } from "@agent-native/core/client";
+
+export default function AgentRoute() {
+  return (
+    <div className="h-screen">
+      <AgentPanel defaultMode="chat" className="h-full" />
+    </div>
+  );
+}
+```
+
+`<AgentPanel>` gives you the raw tabs (Chat / CLI / Workspace) without the sidebar wrapper, the collapse button, or any state persistence. Put it wherever you want; you handle the layout.
+
+### Selected props
+
+- **`defaultMode`** — `"chat"` or `"cli"`. Default: `"chat"`.
+- **`className`** — CSS class for the outer container.
+- **`onCollapse`** — if provided, a collapse button appears in the header.
+- **`isFullscreen`** / **`onToggleFullscreen`** — wire up external fullscreen state if you want a Claude-style centered column.
+- **`storageKey`** — namespace for `localStorage` keys. Useful when you render multiple panels (different app instances or workspaces) in the same page.
+
+Full props: `AgentPanelProps` in `@agent-native/core/client`.
+
+## Programmatic messages: `sendToAgentChat()` {#send}
+
+A button that hands work off to the agent (instead of running an inline `llm()` call — the anti-pattern from the [ladder](/docs/what-is-agent-native#the-ladder)):
+
+```tsx
+import { sendToAgentChat } from "@agent-native/core/client";
+
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Generate a chart showing signups by source",
+      context: `Dashboard ID: ${dashboardId}, date range: last 30 days`,
+      submit: true,
+    })
+  }
+>
+  Generate chart
+</Button>;
+```
+
+### Options
+
+- **`message`** — the visible prompt shown in chat.
+- **`context`** — hidden context appended to the prompt (selected text, cursor position, current entity id — anything the agent should know but the user shouldn't see twice).
+- **`submit`** — `true` to auto-run, `false` to prefill but wait. Omit to use the project default.
+- **`openSidebar`** — set to `false` for background/silent sends. Default opens the sidebar so the user sees the response.
+- **`type`** — `"content"` (default) keeps the work in the embedded app agent. `"code"` routes to the code-editing frame (for agent-written code changes, see [Frames](/docs/frames)).
+
+`sendToAgentChat` returns a stable `tabId` you can use to track the chat run.
+
+If you want a loading state, use the `useSendToAgentChat()` hook — it returns both `send` and `isGenerating`:
+
+```ts
+import { useSendToAgentChat } from "@agent-native/core/client";
+
+const { send, isGenerating } = useSendToAgentChat();
+```
+
+## Typesafe actions from the UI: `useActionMutation()` {#use-action-mutation}
+
+When the UI needs to run the same operation an agent tool would run — the fourth rung of the [ladder](/docs/what-is-agent-native#rung-three) — use `useActionMutation`:
+
+```tsx
+import { useActionMutation } from "@agent-native/core/client";
+
+const { mutate, isPending } = useActionMutation("replyToEmail");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+Type-safe arguments come from the zod schema in your `defineAction()`. See [Actions](/docs/actions) for the full action system.
+
+## Selection + cursor awareness {#selection}
+
+The agent can see what the user has selected — text, cells, slides, contacts — via the `navigation` and `selection` keys in application state. If you'd like Cmd-I (or similar) to send a selected range into the chat as context, see [Context Awareness](/docs/context-awareness).
+
+## Putting it all together {#putting-it-together}
+
+A typical drop-in setup:
+
+```tsx
+// app/root.tsx
+import {
+  AgentSidebar,
+  AgentToggleButton,
+  sendToAgentChat,
+} from "@agent-native/core/client";
+
+export default function Root() {
+  return (
+    <AgentSidebar suggestions={["Draft a reply", "Summarize selection"]}>
+      <Header>
+        <AgentToggleButton />
+      </Header>
+
+      <Main>
+        <YourRoutes />
+      </Main>
+    </AgentSidebar>
+  );
+}
+```
+
+```tsx
+// Anywhere else in the app
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Summarize this thread",
+      context: `Thread id: ${threadId}`,
+      submit: true,
+    })
+  }
+>
+  Summarize
+</Button>
+```
+
+The user sees a chat button in the header, can open it, and can talk to the agent. Your buttons hand work to that same agent instead of running one-shot LLM calls.
+
+## What's next
+
+- [**Actions**](/docs/actions) — `defineAction()` and `useActionMutation()`
+- [**Context Awareness**](/docs/context-awareness) — selection, navigation, view-screen
+- [**Workspace**](/docs/workspace) — what the Workspace tab contains (skills, memory, MCP servers, scheduled jobs)
+- [**Voice Input**](/docs/voice-input) — the microphone in the chat composer

package/docs/content/enterprise-workspace.md

@@ -24,7 +24,7 @@ Anything every app in your org should agree on lives in the workspace core:
 | Agent skills                  | `skills/<skill-name>/SKILL.md`                                               |
 | Shared agent actions          | `actions/*.ts`                                                               |
 | Shared React components       | `src/client/*.tsx` (e.g. `AuthenticatedLayout`)                              |
-| Design tokens / brand         | `tailwind.preset.ts`                                                         |
+| Design tokens / brand         | `styles/tokens.css`                                                          |
 | Shared API credentials        | `src/credentials.ts` → `resolveCompanyCredential()`                          |
 
 Each individual app becomes _just a set of screens_ — routes, dashboards, views, domain-specific actions. Everything else is inherited. If you're building ten tools for the same org, nine of them are 80% the same package, and the workspace core is where that 80% lives.
@@ -56,7 +56,7 @@ my-company-platform/
 │       ├── actions/             # shared agent-callable actions
 │       ├── skills/              # shared agent skills
 │       ├── AGENTS.md            # enterprise-wide instructions
-│       └── tailwind.preset.ts   # brand tokens
+│       └── styles/tokens.css    # brand tokens (Tailwind v4 @theme + CSS vars)
 └── apps/
     ├── mail/
     ├── calendar/
@@ -159,6 +159,14 @@ A few onboarding flows are workspace-aware out of the box:
 - **Builder `/cli-auth`**: clicking "Connect Builder" from any app writes `BUILDER_PRIVATE_KEY` and friends to the **workspace root** `.env`, so every app gains browser access at once.
 - **Env-vars settings route** (`POST /_agent-native/env-vars`): when inside a workspace, defaults to writing the workspace root `.env`. Pass `scope: "app"` in the body to override one app.
 
+## Shared MCP servers {#shared-mcp}
+
+Drop an `mcp.config.json` at the workspace root and every app in the workspace connects to the same MCP servers — one place to configure `claude-in-chrome`, `@modelcontextprotocol/server-filesystem`, Playwright, or any internal MCP server. Individual apps can override with their own `mcp.config.json` (app-root wins over the workspace root for that one app).
+
+For remote HTTP MCP servers (Zapier, Composio, internal tools), users can add them from the settings UI at **Personal** or **Team (org)** scope — no file edits, hot-reloaded into the running agent. And if you run the dispatch template, it can act as an **MCP hub** that every other app in the workspace pulls org-scope servers from, so you configure each URL + bearer token exactly once.
+
+See [MCP Clients](/docs/mcp-clients) for the config schema, precedence rules, remote-UI scopes, and hub setup.
+
 ## Shared credentials {#shared-credentials}
 
 Rotate a third-party API key in one place and every app picks it up:
@@ -173,18 +181,22 @@ Under the hood this wraps `@agent-native/core`'s `resolveCredential()`, which ch
 
 ## Shared design tokens {#design-tokens}
 
-The core exports a Tailwind preset. Each app's `tailwind.config.ts` extends it:
+The framework is on Tailwind v4. The core ships a shared CSS file with the standard `@theme` tokens — each app imports it from its `app/global.css`:
 
-```ts
-import preset from "@my-company-platform/core-module/tailwind";
+```css
+@import "tailwindcss";
+@import "@my-company-platform/core-module/styles/tokens.css";
+@source "./**/*.{ts,tsx}";
 
-export default {
-  presets: [preset],
-  content: ["./app/**/*.{ts,tsx}"],
-};
+:root {
+  --background: 0 0% 100%; /* ...brand tokens... */
+}
+.dark {
+  --background: 220 6% 6%; /* ... */
+}
 ```
 
-Brand colors, typography, spacing scales, and any shared component classes live in one file. Update it in the core and every app rebrands on the next build. Shared React components in `src/client/` pick up the same tokens automatically.
+Brand colors, typography, spacing scales, and any shared component classes live in that one CSS file. Update it in the core and every app rebrands on the next build. Shared React components in `src/client/` pick up the same tokens automatically.
 
 ## Deployment {#deployment}
 

package/docs/content/getting-started.md

@@ -5,7 +5,7 @@ description: "Pick a template, create your app, and start customizing it with AI
 
 # Getting Started
 
-The fastest way to get started is to pick a template and customize it. Templates are complete, production-ready apps — not starter kits. You get a working app in under a minute and start making it yours.
+The fastest way to get started is to pick a template and make it yours. Agent-native templates are **[cloneable SaaS](/docs/cloneable-saas)** — complete, production-grade apps, not starter kits. You get a working product in under a minute and start customizing it with the agent.
 
 ## Create Your Workspace {#create-your-app}
 
@@ -41,16 +41,19 @@ From here, use your AI coding tool (Claude Code, Cursor, Windsurf, etc.) to cust
 
 Each template is a complete app with UI, agent actions, database schema, and AI instructions ready to go:
 
-| Template                          | Replaces                    |
-| --------------------------------- | --------------------------- |
-| [Mail](/templates/mail)           | Superhuman, Gmail           |
-| [Calendar](/templates/calendar)   | Google Calendar, Calendly   |
-| [Content](/templates/content)     | Notion, Google Docs         |
-| [Slides](/templates/slides)       | Google Slides, Pitch        |
-| [Video](/templates/video)         | video editing               |
-| [Analytics](/templates/analytics) | Amplitude, Mixpanel, Looker |
+| Template                            | Replaces                                         |
+| ----------------------------------- | ------------------------------------------------ |
+| [Mail](/templates/mail)             | Superhuman, Gmail                                |
+| [Calendar](/templates/calendar)     | Google Calendar, Calendly                        |
+| [Content](/templates/content)       | Notion, Google Docs                              |
+| [Slides](/templates/slides)         | Google Slides, Pitch                             |
+| [Video](/templates/video)           | video editing                                    |
+| [Analytics](/templates/analytics)   | Amplitude, Mixpanel, Looker                      |
+| [Forms](/docs/template-forms)       | Typeform                                         |
+| [Dispatch](/docs/template-dispatch) | Workspace control plane — secrets, routing, jobs |
+| [Starter](/docs/template-starter)   | Minimal scaffold — build from scratch            |
 
-Browse the [template gallery](/templates) for live demos and detailed feature lists.
+Browse the [template gallery](/templates) for live demos, or see [Cloneable SaaS](/docs/cloneable-saas) for the full list and the clone → customize → deploy flow.
 
 ## Project Structure {#project-structure}
 
@@ -81,17 +84,29 @@ export default defineConfig();
 { "extends": "@agent-native/core/tsconfig.base.json" }
 ```
 
-```ts
-// tailwind.config.ts
-import type { Config } from "tailwindcss";
-import preset from "@agent-native/core/tailwind";
-
-export default {
-  presets: [preset],
-  content: ["./app/**/*.{ts,tsx}"],
-} satisfies Config;
+```css
+/* app/global.css — Tailwind v4 (CSS-first, no tailwind.config.ts needed) */
+@import "tailwindcss";
+@import "@agent-native/core/styles/agent-native.css";
+
+@source "./**/*.{ts,tsx}";
+
+:root {
+  --background: 0 0% 100%;
+  --foreground: 220 10% 10%;
+  /* ...rest of your shadcn-style tokens */
+}
+
+.dark {
+  --background: 220 6% 6%;
+  --foreground: 0 0% 90%;
+  /* ... */
+}
 ```
 
+The framework auto-injects `@tailwindcss/vite` from `defineConfig()`.
+No `tailwind.config.ts`, `postcss.config.js`, or vite changes needed.
+
 ## Architecture Principles {#architecture-principles}
 
 These principles apply to all agent-native apps. Understanding them helps you customize templates or build from scratch:

package/docs/content/integrations.md

@@ -63,7 +63,7 @@ Subscribe to the `message.im` bot event (and optionally `app_mention` for channe
 
 ### 3. Set environment variables
 
-```
+```bash
 SLACK_BOT_TOKEN=xoxb-your-bot-token
 SLACK_SIGNING_SECRET=your-signing-secret
 ```
@@ -78,7 +78,7 @@ Message [@BotFather](https://t.me/BotFather) on Telegram and use the `/newbot` c
 
 ### 2. Set environment variables
 
-```
+```bash
 TELEGRAM_BOT_TOKEN=your-bot-token
 ```
 
@@ -104,7 +104,7 @@ Go to the [Meta Developer Portal](https://developers.facebook.com/), create an a
 
 ### 2. Set environment variables
 
-```
+```bash
 WHATSAPP_ACCESS_TOKEN=your-access-token
 WHATSAPP_VERIFY_TOKEN=your-verify-token
 WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id

package/docs/content/key-concepts.md

@@ -41,6 +41,23 @@ Six rules govern the architecture:
 5. **The agent can modify code** — the app evolves as you use it
 6. **Application state in SQL** — ephemeral UI state lives in the database, readable by both agent and UI
 
+## What you get for free {#what-you-get-for-free}
+
+Adopting the framework is valuable mostly because of what you stop having to build. The moment your app follows the six rules, you inherit:
+
+- **One action = four surfaces.** Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend mutation (`useActionMutation("name")`), an HTTP endpoint at `/_agent-native/actions/:name`, and an MCP tool (when MCP is enabled). External agents can call it over [A2A](/docs/a2a-protocol) too. One implementation, four consumers.
+- **A full workspace per user.** Skills, memory (`learnings.md`), `AGENTS.md`, custom sub-agents, scheduled jobs, connected MCP servers — all SQL-backed, per-user, no dev-box required. See [Workspace](/docs/workspace).
+- **Drop-in React components.** `<AgentPanel />` and `<AgentSidebar />` render chat + workspace anywhere in your app. See [Drop-in Agent](/docs/drop-in-agent).
+- **Live sync between agent and UI.** A 2-second poll invalidates React Query caches whenever the agent writes to the DB. No WebSockets, no serverless-unfriendly long-lived connections. See [Polling Sync](#polling-sync) below.
+- **Auth, orgs, RBAC.** Better Auth with orgs/members/roles is wired in for every template. See [Authentication](/docs/authentication).
+- **Context awareness.** The agent always knows what the user is looking at through the `navigation` app-state key. See [Context Awareness](/docs/context-awareness).
+- **MCP client + server, both directions.** The app ingests MCP servers (local, remote, hub-shared) _and_ exposes its own actions as an MCP server. See [MCP Clients](/docs/mcp-clients) and [MCP Protocol](/docs/mcp-protocol).
+- **Inter-app delegation.** Agents in different apps talk over [A2A](/docs/a2a-protocol). Same-origin deploys skip JWT; cross-origin uses a shared `A2A_SECRET`.
+- **Sub-agent teams.** Spawn a sub-agent with its own thread and tools, surfaced as a chip inline in chat. See [Agent Teams](/docs/agent-teams).
+- **Portability.** Any Drizzle-supported SQL database, any Nitro-compatible host (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun).
+
+That's the "and everything else" you'd otherwise be gluing together yourself.
+
 ## The four-area checklist {#four-area-checklist}
 
 Every new feature must update all four areas. Skipping any one breaks the agent-native contract.
@@ -65,7 +82,7 @@ Core SQL stores are auto-created and available in every template:
 - `oauth_tokens` — OAuth credentials
 - `sessions` — auth sessions
 
-```bash
+```ts
 // Drizzle schema for domain data
 import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
 
@@ -76,9 +93,11 @@ export const forms = sqliteTable("forms", {
   ownerEmail: text("owner_email"),
   createdAt: integer("created_at").notNull(),
 });
+```
 
-// Core actions for quick database access
-pnpm action db-schema           # show all tables
+```bash
+# Core actions for quick database access
+pnpm action db-schema                                       # show all tables
 pnpm action db-query --sql "SELECT * FROM forms"
 pnpm action db-exec --sql "INSERT INTO forms ..."
 # Surgical find/replace on a large text column — sends a diff, not the whole value
@@ -110,26 +129,34 @@ Why not call an LLM inline?
 
 ## Actions system {#actions-system}
 
-When the agent needs to do something complex — call an API, process data, query the database — it runs an action. Actions are TypeScript files in `actions/` that export a default async function:
+When the agent needs to do something complex — call an API, process data, query the database — it runs an **action**. Actions are TypeScript files in `actions/` that export a default `defineAction()`:
 
 ```ts
 // actions/fetch-data.ts
-import { parseArgs } from "@agent-native/core";
-
-export default async function fetchData(args: string[]) {
-  const { source } = parseArgs(args);
-  const res = await fetch(`https://api.example.com/${source}`);
-  const data = await res.json();
-  console.log(JSON.stringify(data, null, 2));
-}
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Fetch data from a source API.",
+  schema: z.object({
+    source: z.string().describe("Data source key, e.g. 'signups'"),
+  }),
+  run: async ({ source }) => {
+    const res = await fetch(`https://api.example.com/${source}`);
+    return await res.json();
+  },
+});
 ```
 
-```bash
-# Agent runs actions via CLI
-pnpm action fetch-data --source=signups
-```
+One `defineAction()` call gives you:
+
+- **Agent tool** — the agent sees it with the zod-derived JSON Schema and can call it.
+- **Frontend mutation** — `useActionMutation("fetch-data")` with full TypeScript inference.
+- **HTTP endpoint** — `POST /_agent-native/actions/fetch-data` (auto-mounted).
+- **CLI** — `pnpm action fetch-data --source=signups` for scripting and agent dev loops.
+- **MCP tool / A2A tool** — when MCP server or A2A is enabled, the same action shows up there too.
 
-This means anything the UI can do, the agent can do — and vice versa. The UI calls `POST /api/fetch-data`, the agent calls `pnpm action fetch-data`. Same logic, same results, different entry points.
+Same logic, one definition, wired to every consumer automatically. See [Actions](/docs/actions) for the full reference.
 
 ## Polling sync {#polling-sync}
 
@@ -169,14 +196,14 @@ The agent always knows what the user is looking at. The UI writes a `navigation`
 
 See [Context Awareness](/docs/context-awareness) for the full pattern: navigation state, view-screen, navigate commands, and jitter prevention.
 
-## APIs & CLIs, not MCPs {#apis-and-clis}
+## Actions, MCP, and A2A — one surface, many protocols {#protocols}
 
-Agent-native apps can work with MCP servers, but the architecture leans heavily on something more standard: **regular APIs and CLIs accessed through code execution**. Agents are great at writing code that calls `fetch()` or runs a CLI command — no special protocol needed.
+Every action you define automatically becomes available over multiple protocols — you don't pick one. The framework runs both an MCP server and an A2A peer for your app, with actions feeding both.
 
-- **No wrapper layer.** Call APIs directly with `fetch()` or use official SDKs.
-- **Any CLI works.** `ffmpeg`, `gh`, `aws`, `gcloud` — if it runs in a terminal, the agent can use it.
-- **Code is the protocol.** TypeScript actions are more expressive than any tool schema.
-- **MCP is additive.** Use MCP servers alongside actions if you want, but they're not required.
+- **Actions first.** Write the logic once as an action. Use `fetch()` and any SDK you want inside — no wrapper layer.
+- **MCP for the outside world.** Your actions show up as MCP tools to Claude Desktop, ChatGPT's remote-MCP support, and any other MCP client. Your app also _consumes_ MCP servers — local, remote, or from a workspace hub. See [MCP Clients](/docs/mcp-clients) and [MCP Protocol](/docs/mcp-protocol).
+- **A2A for other agents.** Other agent-native apps discover and call your actions over [A2A](/docs/a2a-protocol) — same-origin deploys skip JWT entirely.
+- **CLIs still work.** `pnpm action <name>` and direct shell tools (`ffmpeg`, `gh`, `aws`) remain available whenever they're the simplest path.
 
 ## Agent modifies code {#agent-modifies-code}
 

package/docs/content/mcp-clients.md

@@ -9,6 +9,8 @@ Agent-native apps can also act as MCP **clients** — connecting to locally inst
 
 With one config file, every agent-native app in your workspace gains access to tools provided by MCP servers on your machine: `claude-in-chrome` for browser automation, `@modelcontextprotocol/server-filesystem` for reading files, `@modelcontextprotocol/server-playwright` for browser testing, and anything else that speaks MCP.
 
+You can also [connect remote (HTTP) MCP servers at runtime](#remote-via-ui) — individual users or whole organizations — without editing a config file.
+
 ## Adding a local MCP server {#adding-a-server}
 
 Create `mcp.config.json` at your workspace root (or at an individual app root — workspace root wins when both exist):
@@ -73,6 +75,75 @@ If you have **no** `mcp.config.json` and the `claude-in-chrome-mcp` binary is on
 
 This means users who've installed the claude-in-chrome extension get browser control across every agent-native app they open with no config changes.
 
+## Remote MCP servers via the settings UI {#remote-via-ui}
+
+Users don't have to edit `mcp.config.json` to add a remote, HTTP-based MCP server (Zapier, Cloudflare, Composio, an internal tool, etc). Open the settings panel → **MCP Servers** and paste the server's URL. Two scopes are supported:
+
+- **Personal** — only the signed-in user gets the tools. Stored as a user-scope setting.
+- **Team** — everyone in the active organization gets the tools. Owners and admins can add; members see the list read-only. Stored as an org-scope setting.
+
+Adds and removes hot-reload into the running MCP manager — no process restart, and no server restart. The new `mcp__<scope>-<name>__*` tools appear to the agent on the next message.
+
+HTTPS URLs are accepted everywhere; plain `http://` is only allowed for `localhost` during development. Optional auth goes in as a Bearer token that's sent via `Authorization: Bearer …` on every request.
+
+Under the hood these servers are persisted in the framework's `settings` table under the key `u:<email>:mcp-servers-remote` (Personal) or `o:<orgId>:mcp-servers-remote` (Team) and merged with `mcp.config.json` on startup.
+
+### HTTP endpoints
+
+| Method | Route                                                 | Purpose                                                                |
+| ------ | ----------------------------------------------------- | ---------------------------------------------------------------------- |
+| GET    | `/_agent-native/mcp/servers`                          | List the current user's personal + org servers with live status.       |
+| POST   | `/_agent-native/mcp/servers`                          | Add a server. Body: `{ scope, name, url, headers?, description? }`.    |
+| DELETE | `/_agent-native/mcp/servers/:id?scope=user\|org`      | Remove a server and reconfigure the manager.                           |
+| POST   | `/_agent-native/mcp/servers/:id/test?scope=user\|org` | Dry-run the existing server's connect + list-tools.                    |
+| POST   | `/_agent-native/mcp/servers/test`                     | Dry-run an arbitrary URL before persisting. Body: `{ url, headers? }`. |
+
+Stdio servers are still a no-op outside Node runtimes, but remote HTTP MCP servers work in any environment with `fetch` — including desktop production builds.
+
+## Shared MCP servers via a hub {#hub}
+
+If your workspace runs multiple agent-native apps (e.g. dispatch + mail + clips), you can configure **one** app as the hub and have the others pull its org-scope MCP servers automatically. No per-app copy-paste of URLs and bearer tokens.
+
+Dispatch is the conventional hub — it already coordinates across apps.
+
+### 1. Enable hub-serve on the hub app (dispatch)
+
+Set an env var in dispatch's deployment:
+
+```bash
+AGENT_NATIVE_MCP_HUB_TOKEN=<a-long-random-secret>
+```
+
+Dispatch now mounts `GET /_agent-native/mcp/hub/servers` which returns every org-scope MCP server stored in its `settings` table, with full URL + headers, authenticated by the token.
+
+### 2. Point consuming apps at the hub
+
+Set on every consumer (mail, clips, whatever):
+
+```bash
+AGENT_NATIVE_MCP_HUB_URL=https://dispatch.acme.com
+AGENT_NATIVE_MCP_HUB_TOKEN=<the-same-secret>
+```
+
+At startup, each consumer pulls the hub's server list and merges it into its own MCP manager. The tools appear to the agent as `mcp__hub_<orgId>_<name>__*` — distinct from the consumer's own local `mcp__org_…` so there's no collision.
+
+### 3. What gets shared
+
+Only **org-scope** servers are shared. User-scope (Personal) servers stay with the user who added them — the hub never re-exposes personal credentials across apps.
+
+Hub responses include the full auth headers (Bearer tokens etc). The transport is HTTPS, the endpoint requires the shared secret, and it only returns org-scope rows — treat the hub URL + token like a database credential.
+
+### 4. Hot reload vs restart
+
+Local UI adds in each app hot-reload via `McpClientManager.reconfigure()` — no restart. Hub-sourced servers currently re-fetch only when a local mutation triggers a reconfigure (or when the app restarts), so if you add a new server in dispatch, other apps pick it up on their next restart or next local change. Periodic background refresh is on the roadmap.
+
+### Endpoints summary
+
+| Method | Route                            | Purpose                                                                                                            |
+| ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| GET    | `/_agent-native/mcp/hub/servers` | Serve all org-scope servers with full creds (bearer-gated, only mounted when `AGENT_NATIVE_MCP_HUB_TOKEN` is set). |
+| GET    | `/_agent-native/mcp/hub/status`  | Returns `{ serving, consuming, hubUrl }` for the settings UI card.                                                 |
+
 ## Status route {#status-route}
 
 Every app exposes `GET /_agent-native/mcp/status` for tooling and onboarding:

package/docs/content/pure-agent-apps.md

@@ -0,0 +1,69 @@
+---
+title: "Pure-Agent Apps"
+description: "Build an agent without a heavy UI — just the agent plus a minimal observability/management surface. All the framework benefits, none of the dashboard work."
+---
+
+# Pure-Agent Apps
+
+Not every agent-native app needs a full SaaS-style interface. Sometimes the agent _is_ the product. A support triage agent. A daily report generator. A research bot. An email auto-responder. An ops runbook executor.
+
+For these, the "app" is mostly just the agent doing work in the background. You still want a UI — but a minimal one, focused on **observability, management, and steering** rather than hand-crafted dashboards and forms.
+
+This is the "agents benefit from a UI even when there's no rich app around them" pattern. The hot take is "agents will replace apps." The reality is "every agent eventually needs a UI for humans to supervise, configure, and debug it." Agent-native gives you that UI for free.
+
+## The minimum viable UI {#minimum-ui}
+
+A pure-agent app ships with five surfaces, all provided by the framework — you don't build them:
+
+1. **Chat** — the main input. Users talk to the agent, steer it, queue tasks. (`<AgentSidebar>` or `<AgentPanel>`)
+2. **Workspace** — skills, memory (`learnings.md`), `AGENTS.md`, custom sub-agents, connected MCP servers, scheduled jobs. Customize the agent's behavior without shipping code. (Workspace tab in the sidebar)
+3. **Job history** — which scheduled jobs ran, when, whether they succeeded, what they did. (Workspace tab → `jobs/`)
+4. **Thread history** — every past conversation, each preserved with its tool calls and final output. (Chat tab)
+5. **Settings** — API keys, connected accounts, onboarding status. (Sidebar settings)
+
+Those five together are enough UI for most pure-agent use cases. No analytics dashboard. No Kanban. No forms. Just: talk to it, see what it's done, configure how it behaves.
+
+## When to pick this pattern {#when-to-pick}
+
+Pure-agent makes sense when:
+
+- **The work happens in the background.** Scheduled jobs, webhook-triggered handlers, Slack/Telegram responders. Users rarely sit in the app.
+- **The output leaves the app.** The agent posts to Slack, sends email, writes to a third-party system. There's nothing to view in-app; the value is elsewhere.
+- **The domain is one-shot.** A research bot that returns a report. No persistent object to dashboard.
+- **You're prototyping.** Ship the agent now; add a rich UI only when you've proven users need it.
+
+Pick a full [cloneable SaaS](/docs/cloneable-saas) template instead when the app has real persistent objects (emails, events, documents, charts) users need to browse, pivot, and share.
+
+## The minimal scaffold {#scaffold}
+
+Start from the **Starter** template:
+
+```bash
+pnpm dlx @agent-native/core create my-agent --template starter
+```
+
+Starter gives you the six-rules architecture, the agent panel, the workspace, auth, polling, and one example action — and nothing else. Add your own actions in `actions/`, connect any MCP servers you need, write the relevant skills into the workspace, and you're done. The "UI" is the agent sidebar — which is already complete.
+
+If you really want _zero_ UI except the agent, `app/routes/index.tsx` can just render `<AgentPanel defaultMode="chat" />` fullscreen. The only thing the user sees is the chat. Everything else — job history, workspace, settings — is one click away in the panel's tabs.
+
+## What you still get for free {#still-free}
+
+Even with no custom UI, you still inherit every framework benefit:
+
+- **Actions** as agent tools + HTTP endpoints + MCP tools + A2A tools. External agents, Claude Desktop, and your own HTTP clients can drive the agent without going through the chat UI.
+- **Recurring jobs** for scheduled work — "every morning at 7 summarize my unread emails and post to Slack."
+- **The workspace** for per-user customization, skills, memory, MCP connections.
+- **Sub-agent delegation** via [agent teams](/docs/agent-teams).
+- **Portability** — deploys to any serverless host, any SQL database.
+- **Multi-tenant by default** — each user gets their own workspace without a dev-box.
+
+## Adding a tiny bit of UI {#tiny-ui}
+
+Most "pure-agent" apps eventually want a little bit of custom UI — not a dashboard, but maybe a status page, a job history, or a config screen. The [drop-in agent](/docs/drop-in-agent) components coexist with anything else you render. Add a single `/status` route that lists recent runs; keep everything else in the chat. That's usually enough.
+
+## What's next
+
+- [**Recurring Jobs**](/docs/recurring-jobs) — scheduled prompts the agent runs on its own
+- [**Drop-in Agent**](/docs/drop-in-agent) — mounting `<AgentPanel>` fullscreen or in a sidebar
+- [**Actions**](/docs/actions) — the tools your pure-agent will call
+- [**Workspace**](/docs/workspace) — the customization surface for skills, memory, and MCP servers