@agent-native/core 0.47.1 → 0.48.1

package/docs/content/external-agents.md

@@ -205,17 +205,87 @@ Current scopes are:
 
 When the client requests no explicit scope, the app grants all three so the connector behaves like the browser-authorized Connect flow. Keep the bearer-token Connect page and `agent-native connect --token <token>` fallback around for local dev, fallback hosts, and clients where you need a ready-to-paste config block.
 
+## Catalog tiers {#catalog-tiers}
+
+The tool catalog your agent sees depends on both the deployment context and how
+you connected.
+
+### Connector tier (hosted multi-tenant, default) {#connector-tier}
+
+On hosted multi-tenant deployments (e.g. `plan.agent-native.com`) the server
+activates a curated **connector catalog** when `AGENT_NATIVE_CONNECTOR_CATALOG=1`
+is set. External MCP clients see only the template-declared allow-list of
+app-level actions (create/get/update plan, sharing, upload, navigate, automations,
+tool-search) plus the four builtin cross-app tools (`list_apps`, `open_app`,
+`ask_app`, `create_embed_session`). Tools outside the list — `db-exec`,
+`db-patch`, `seed-*`, the extension suite, browser-session tools, agent-engine
+management, and context-xray tools — are not advertised and calls to them are
+rejected with "Unknown tool".
+
+This keeps the context window of every connected external agent small (~20–30
+tools vs. ~105) and removes footguns that are only safe for single-tenant
+local development.
+
+### Full tier (local / dev, or per-token opt-up) {#full-tier}
+
+Local and dev deployments that do not have `AGENT_NATIVE_CONNECTOR_CATALOG=1`
+always serve the full action surface. When the env flag is set, individual
+callers can still opt up by minting their token with `--full-catalog`:
+
+```bash
+agent-native connect https://plan.agent-native.com --full-catalog
+```
+
+This embeds a `catalog_scope: "full"` claim in the minted JWT. On subsequent
+requests the MCP server bypasses the connector-catalog filter for that token
+and serves the complete action surface — identical to the local/dev experience.
+
+`AGENT_NATIVE_MCP_FULL_CATALOG=1` (process env on the server) is a
+deployment-wide override that disables the filter for all callers. Use it for
+single-tenant hosted instances that need the full surface without per-token
+opt-up.
+
+### Template declaration {#catalog-declaration}
+
+Templates declare their connector catalog in `createAgentChatPlugin` options:
+
+```ts
+export default createAgentChatPlugin({
+  appId: "plan",
+  actions: loadActionsFromStaticRegistry(actionsRegistry),
+  connectorCatalog: [
+    "create-visual-plan",
+    "get-visual-plan",
+    "list-visual-plans",
+    "update-visual-plan",
+    // … other safe app-level actions
+    "set-resource-visibility",
+    "share-resource",
+    "upload-image",
+    "navigate",
+    "view-screen",
+    "manage-automations",
+    "tool-search",
+  ],
+});
+```
+
+The builtin cross-app tools (`list_apps`, `open_app`, `ask_app`,
+`create_embed_session`, `create_workspace_app`, `list_templates`) are always
+included regardless of the declared list.
+
 ## What you can do once connected {#what-you-can-do}
 
 Once your agent is connected, the available MCP tool surface depends on the
-host. Code/stdio developer clients get the app's full action surface plus the
-`ask-agent` meta-tool that runs the full agent loop (the same entry point
-[A2A](/docs/a2a-protocol) uses). Chat hosts, including Claude and ChatGPT, get
-a compact app-facing catalog by default even when they authenticate through a
-generic bearer/static-token path: cross-app verbs such as `list_apps`,
-`open_app`, and `ask_app`, plus the app-only embed helper. In both cases, ask
-the agent to do real work and it hands back a link straight into the running
-app:
+host and the deployment. Code/stdio developer clients on local deployments get
+the app's full action surface plus the `ask-agent` meta-tool that runs the full
+agent loop (the same entry point [A2A](/docs/a2a-protocol) uses). On hosted
+multi-tenant deployments the connector tier is active by default (see above).
+Chat hosts, including Claude and ChatGPT, get a compact app-facing catalog by
+default even when they authenticate through a generic bearer/static-token path:
+cross-app verbs such as `list_apps`, `open_app`, and `ask_app`, plus the
+app-only embed helper. In all cases, ask the agent to do real work and it hands
+back a link straight into the running app:
 
 ```
 > draft an email to John about the Q3 report
@@ -236,13 +306,7 @@ declares `mcpApp`, the server advertises
 security metadata such as CSP and sandbox permissions lives on the resource
 entries and `resources/read` content, not on the tool descriptor.
 
-For ChatGPT/Claude-style OAuth app hosts, that discovery surface is compact by
-default: `tools/list` and `resources/list` advertise the generic `open_app`
-embed path instead of every action-specific MCP App resource. Use
-`open_app({ path, embed: true })` for first-class inline app previews. Keep
-action-specific MCP App resources for direct app connectors that disable the
-generic builtins, or mark an individual action with `mcpApp.compactCatalog: true`
-only when it truly needs to stay visible in chat-host discovery.
+For ChatGPT/Claude-style OAuth app hosts, the discovery surface is compact by default: `tools/list` and `resources/list` advertise the generic `open_app` embed path instead of every action-specific MCP App resource (see [Catalog tiers](#catalog-tiers)). Mark an individual action with `mcpApp.compactCatalog: true` only when it truly needs to stay visible in chat-host discovery.
 
 That makes the same app surface available to every compatible host rather than building per-client shims. The current official MCP Apps client list includes Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT, and Cursor; host support still varies by plan, release channel, and client version, so check the [MCP extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix). ChatGPT custom MCP apps are available through developer mode for Business and Enterprise/Edu workspaces on ChatGPT web; see OpenAI's [developer mode and MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-apps-in-chatgpt-beta) notes.
 
@@ -267,106 +331,9 @@ delete/reconnect the Claude connector and start a fresh chat.
 
 ### First-class MCP App bridge {#mcp-app-bridge}
 
-MCP App embeds are route embeds, not separate mini-products. `embedApp()`
-starts from the action's `link` target, creates a short-lived embed session,
-and launches that signed app route. Standard MCP Apps hosts can navigate the
-MCP App frame itself when the host can hydrate the route directly. Claude web
-uses a single-frame transplant path: the resource document fetches the signed
-app HTML and hydrates it inside Claude's MCP App iframe because Claude does not
-reliably allow app-owned child iframes or external frame navigation. ChatGPT
-web gets a controlled route iframe because its Apps bridge gives us stable
-`window.openai` host APIs and bounded height control. All paths point at the
-same signed app route and render the normal route and React components. Design
-embedded routes so a reload with the same signed URL reconstructs the same
-view.
-
-For same-app `open_app({ embed: true })`, the framework mints the embed-start
-ticket during the original tool call and stores the signed start URL in hidden
-tool metadata. Custom actions can return `embedStartUrl` for the same fast
-path; the MCP layer strips that ticket-bearing URL from model-visible
-`structuredContent` and normal open-link metadata. When no embed start URL is
-present, the resource falls back to the app-only `create_embed_session` helper.
-This keeps production hosts that restrict iframe-initiated tool calls on the
-direct route without leaking one-time app session URLs into the transcript. If a
-user reopens an old chat after a one-time start ticket has expired, the start
-route returns a small refresh page and posts `agentNative.embedSessionExpired`
-to the wrapper; `embedApp()` clears the stale start URL and mints a fresh ticket
-through `create_embed_session` when it still has the original app route.
-
-ChatGPT gets a dedicated compatibility path through `window.openai`: the launch
-document reads `toolInput`, `toolOutput`, and `toolResponseMetadata` directly,
-then calls `create_embed_session` via `window.openai.callTool(...)`. Standard
-MCP Apps hosts use the `ui/*` JSON-RPC bridge. Directly hydrated routes can
-call `ui/update-model-context`, `ui/message`, `ui/open-link`, and
-`ui/request-display-mode` through the host bridge helpers. Claude's
-transplanted route uses the same direct `ui/*` host bridge after hydration.
-When the ChatGPT or explicit diagnostic iframe path is used, the wrapper
-relays the same host actions over `agentNative.mcpHost.*` postMessage
-requests. Keep the result shape identical for both paths: return a focused
-`link` and concise structured content.
-
-Do not set standard `_meta.ui.domain` to an app URL. MCP Apps treats that field
-as host-specific: Claude validates `{hash}.claudemcpcontent.com`-style sandbox
-domains, while ChatGPT uses its own `openai/widgetDomain` metadata. Omit
-`ui.domain` unless you are deliberately emitting a host-specific value; the host
-will choose a default sandbox origin.
-
-Extension pages keep their sandbox in MCP chat embeds without navigating a
-second route iframe. Normal app usage renders
-`/_agent-native/extensions/:id/render` as a sandboxed child iframe. In MCP chat
-bridge mode the framework renders the same extension document as sandboxed
-`srcDoc` inside the route iframe, avoiding host `frame-ancestors` /
-`X-Frame-Options` failures while preserving `sandbox="allow-scripts
-allow-forms"`.
-
-The resource shell owns the outer host size. `embedApp({ height })` defaults
-to `560px`, clamps the shell to `320-900px`, and reserves `44px` for the small
-toolbar, so the route viewport is `height - 44px`. Keep embedded app routes
-internally scrollable and let the launcher report that bounded intrinsic
-height rather than the full document height; otherwise host auto-resize can
-turn a normal app page into a very tall chat artifact. A changed shell only
-affects new MCP App resources and new tool calls. Old ChatGPT/Claude
-conversation frames can keep the previous resource behavior, so verify sizing
-with a fresh inline render before judging a fix.
-
-Claude uses the single-frame transplant path by default. You can also force it
-in other hosts with `embedMode: "transplant"` or `frame: "transplant"` when
-debugging host module-loading behavior. You can force the nested diagnostic iframe with
-`embedMode: "iframe"`, `renderMode: "iframe"`, `nested: true`, or
-`frame: "iframe"`. If the iframe is blocked, `embedApp()` replaces it with an
-open-app fallback: the user can retry inline, open a freshly minted embed
-session through the host, or use the visible route URL. Keep the action's
-`link` target useful on its own because it is still the universal escape hatch.
-
-When testing Claude through ngrok, use a production build (`agent-native build`
-then `agent-native start`) or a deployed preview/production URL. Claude's
-single-frame transplant path works with production asset chunks; raw Vite dev
-modules such as `/app/root.tsx` can be protected by app auth and fail dynamic
-imports from the Claude resource origin.
-
-The host bridge is deliberately small:
-
-| Mode                   | Message type                          | Use it for                               |
-| ---------------------- | ------------------------------------- | ---------------------------------------- |
-| direct host route      | `ui/update-model-context`             | Hidden context for the host model        |
-| direct host route      | `ui/message`                          | Post a visible user turn into the host   |
-| direct host route      | `ui/open-link`                        | Open an external or app URL via the host |
-| direct host route      | `ui/request-display-mode`             | Request `inline`, `fullscreen`, or `pip` |
-| Claude transplant      | `ui/*`                                | Same direct host bridge after hydration  |
-| ChatGPT / iframe route | `agentNative.mcpHostContext`          | Theme, locale, host platform, dimensions |
-| ChatGPT / iframe route | `agentNative.embeddedAppReady`        | Confirm the route iframe loaded          |
-| ChatGPT / iframe route | `agentNative.mcpHost.*` / `.response` | Wrapper relay for host requests          |
-
-Embedded routes can use `updateMcpAppModelContext()`,
-`openMcpAppHostLink()`, `requestMcpAppDisplayMode()`,
-`getMcpAppHostContext()`, and `useMcpAppHostContext()` from
-`@agent-native/core/client`. `sendToAgentChat()` uses the same path from
-full-app embeds for auto-submitted prompts.
-
-Display mode is best-effort. The in-app `McpAppRenderer` currently reports an
-inline web host context and an inline-only display mode; external hosts may
-honor larger display requests, ignore them, or reply with an unsupported-mode
-error. Always keep the inline route usable.
+`embedApp()` starts from the action's `link` target, creates a short-lived embed session, and launches that signed app route. Claude web uses a single-frame transplant path; ChatGPT gets a controlled route iframe with `window.openai` host APIs. All paths render the normal React route. Directly hydrated routes call `ui/update-model-context`, `ui/message`, `ui/open-link`, and `ui/request-display-mode` through the host bridge; the ChatGPT path relays the same requests over `agentNative.mcpHost.*` postMessage. `embedApp({ height })` defaults to `560px` and clamps to `320-900px`.
+
+See [MCP Apps](/docs/mcp-apps) for the full bridge details — transplant vs controlled-frame, embed modes, the `ui/*` and postMessage tables, `embedStartUrl`, CSP rules, extension `srcDoc` embedding, height clamping, and the complete host bridge client API.
 
 ### Generic cross-app verbs {#cross-app}
 
@@ -382,18 +349,7 @@ On top of the per-action tools the MCP server exposes a stable verb set, so an e
 
 `create_workspace_app` rejects any non-allow-listed template — the public template allow-list in `packages/shared-app-config/templates.ts` is authoritative and CI-guarded; an external agent cannot widen it. A same-named template action overrides a builtin (template-over-core precedence). Disable the whole set with `MCPConfig.builtinCrossAppTools: false`.
 
-The server intentionally advertises tiny `tools/list` and `resources/list`
-catalogs by default for app hosts, including OAuth MCP Apps callers and
-generic authenticated remote HTTP/static-token callers, so hosts do not ingest
-every internal action schema or every action-specific UI resource. The model
-sees app-facing builtins (`list_apps`, `open_app`, `ask_app`, and app-only
-`create_embed_session`) and routes inline UI through
-`open_app({ embed: true })`. Stdio/code developer clients can explicitly opt
-into the full connected action surface, and `publicAgent.expose` remains the
-opt-in for safe read/ingest tools outside the compact app catalog. If an
-individual
-UI action must remain visible to ChatGPT/Claude discovery, set
-`mcpApp.compactCatalog: true`, but treat that as a rare exception.
+The tool and resource catalogs for app hosts are compact by default — see [Catalog tiers](#catalog-tiers). `publicAgent.expose` remains the opt-in for safe read/ingest tools outside that compact catalog; set `mcpApp.compactCatalog: true` only as a rare exception for actions that must appear in chat-host discovery.
 
 For fast ChatGPT/Claude handoffs, the ideal path is direct: call the action that creates or opens the artifact, then let the MCP App launch the route. A Mail request should call `manage_draft` and render the real compose route. A dashboard request should call `open_app({ path, embed: true })` or a dashboard action with `mcpApp` and render the full Analytics route. Calendar, Forms, Content, Slides, Design, and Clips should follow the same pattern with their draft/create/search actions. `list_apps` is useful when the model must choose among granted apps; broad `resources/list`, full-catalog discovery, or `ask_app` delegation should not be the normal route for an obvious UI handoff.
 
@@ -447,51 +403,9 @@ List/search actions point at a record-focused view the same way — e.g. calenda
 
 ## Authoring: optional MCP Apps UI {#mcp-apps}
 
-For hosts that support the MCP Apps extension, an action can also advertise an inline UI resource with `mcpApp`. This is a progressive enhancement for flows where the external agent should hand the user an interactive surface instead of only text — for example reviewing an email draft, editing a calendar invite, or choosing between generated dashboard variants.
-
-Use the real React app with `embedRoute()` or `embedApp()` whenever the user needs UI. The mental model is simple: the action's `link` target is also the MCP App embed target. Expose the operation as a normal action/tool, return a focused deep link with `link`, and add `mcpApp.resource = embedApp(...)` so capable hosts load that same route inline instead of opening a new tab. When both should be built from the same route, prefer `embedRoute({ title, openLabel, path })`: it is the convenience wrapper that returns matching `link` and `mcpApp` fields from one call, while `embedApp(...)` is the lower-level resource you assign to `mcpApp.resource` directly.
-
-That means full-app embeds can do anything the route can do once opened: review or edit an email draft, show a filtered inbox/search, open a calendar event or event draft, load an extension page, inspect a full analytics dashboard or saved analysis, continue a deck in the Slides editor, or open a Design project/editor. Prefer URL/deep-link params and the existing `/_agent-native/open` navigation/app-state bridge over inventing a second state protocol for MCP Apps.
-
-On rare occasions the right target is a focused app route that renders one shared React component instead of the whole app shell. Analytics' `/chart` route is the model: it takes a compact `SqlPanel` payload in the URL and renders the same chart component the dashboard uses. This is still an app embed, not a plain HTML MCP App. Expose or call it through a normal action / `open_app({ path, embed: true })`, keep the URL deterministic, and let `embedApp()` render that route inline.
-
-Do not hand-write one-off plain HTML MCP Apps for product UI; if the action needs a custom surface, add or reuse a real app route/component first and embed that route.
-
-```ts
-import { embedApp } from "@agent-native/core";
-
-export default defineAction({
-  // ...description, schema, run, link...
-  mcpApp: {
-    resource: embedApp({
-      title: "Review draft",
-      description: "Open the generated draft in the real Mail compose UI.",
-      iframeTitle: "Agent-Native Mail",
-      openLabel: "Open in Mail",
-    }),
-  },
-});
-```
-
-The MCP server advertises extension `io.modelcontextprotocol/ui`, adds `_meta.ui.resourceUri` plus `_meta["ui/resourceUri"]` to `tools/list`, and also emits ChatGPT Apps SDK compatibility metadata (`openai/outputTemplate`, widget CSP/description/accessibility). It exposes the HTML through `resources/list`, `resources/templates/list`, and `resources/read` using MIME `text/html;profile=mcp-app`. The stdio proxy forwards those resource handlers from the live app, so desktop and CLI clients see the same resources as HTTP clients.
-
-Keep the existing `link` builder even when adding `mcpApp`. CLI-only clients, older hosts, and any host that does not render MCP Apps will ignore the UI metadata and still need the `"Open in … →"` link. `embedApp()` uses that link as its launch target, calls the app-only `create_embed_session` helper, exchanges a one-time SQL ticket at `/_agent-native/embed/start`, and navigates the MCP App frame to the target route with a short-lived browser session plus a bearer fallback for same-origin fetches. `open_app({ app, path, embed: true })` is the generic escape hatch for routes such as full dashboards, filtered inboxes, calendar draft views, analyses, and extension pages, and should be used liberally when the full app is the clearest review/edit surface.
-
-`embedApp()` includes the MCP request origin in the resource CSP so the launcher
-can fetch and, when explicitly requested, frame the signed first-party app
-route. Dispatch adds the exact origins for the granted apps to its `open_app`
-resource so a single Dispatch connector can inline Mail, Calendar, Slides, and
-the rest without allowing every HTTPS origin. Only pass additional frame or
-resource domains for a custom MCP App that truly embeds a third-party player or
-loads third-party assets.
+Actions can advertise an inline UI resource with `mcpApp` for hosts that support the MCP Apps extension. Use `embedRoute({ title, openLabel, path })` as the convenience wrapper, or assign `embedApp(...)` to `mcpApp.resource` directly. Every MCP App is a real React route, not a separate plain-HTML widget. Always keep the `link` builder — CLI-only hosts, older clients, and non-MCP-Apps hosts use it as the fallback.
 
-Inside those `embedApp()` routes, `sendToAgentChat()` is embed-aware.
-Auto-submitted prompts relay to the MCP host as `ui/update-model-context` plus
-`ui/message`, so a button in the embedded app can intentionally continue the
-Claude/ChatGPT conversation from the selected app state. Hidden context is sent
-as model context; the visible user turn stays just the app's prompt, which
-avoids scary host consent around internal app-state file paths. `submit: false`
-remains local prefill/review behavior.
+See [MCP Apps](/docs/mcp-apps) for the full authoring guide — `embedRoute` vs `embedApp`, the `mcpApp` config shape, CSP, height, the `sendToAgentChat()` embed path, and host bridge client helpers.
 
 ### The `link` contract {#link-contract}
 
@@ -655,6 +569,7 @@ The fallback hosted `connect` flow never copies the deployment's shared secret.
 
 ## Related {#related}
 
+- [MCP Apps](/docs/mcp-apps) — authoring MCP App UIs, the embed bridge, and host bridge API.
 - [MCP Protocol](/docs/mcp-protocol) — the auto-mounted MCP server and `ask-agent` meta-tool.
 - [MCP Clients](/docs/mcp-clients) — the symmetric direction: your app consuming local/remote MCP servers.
 - [A2A Protocol](/docs/a2a-protocol) — the `ask-agent` meta-tool and JSON-RPC peer calls.

package/docs/content/faq.md

@@ -58,22 +58,7 @@ You can, but agent-native works best when built from the ground up. The architec
 
 ### What templates are available? {#what-templates-are-available}
 
-The framework ships with production-ready templates you can use as daily drivers:
-
-- **[Calendar](/docs/template-calendar)** — Google Calendar + Calendly-style booking links
-- **[Content](/docs/template-content)** — Notion-style documents
-- **[Brain](/docs/template-brain)** — full-page company chat, cited memory, sources, and review queue
-- **[Assets](/docs/template-assets)** — brand asset libraries, uploads, and generated media
-- **[Slides](/docs/template-slides)** — presentation builder
-- **[Video](/docs/template-videos)** — Remotion-based video editor
-- **[Analytics](/docs/template-analytics)** — data platform (like Amplitude/Mixpanel)
-- **[Mail](/docs/template-mail)** — full-featured email client (like Superhuman)
-- **[Clips](/docs/template-clips)** — async screen + camera recording (replaces Loom)
-- **[Design](/docs/template-design)** — agent-native HTML prototyping studio
-- **[Forms](/docs/template-forms)** — form builder (like Typeform)
-- **[Dispatch](/docs/template-dispatch)** — workspace control plane: shared secrets, integrations, jobs
-
-Each template is a complete app with UI, agent actions, database schema, and AI instructions. See [Templates](/docs/cloneable-saas) for the full picture, or all [Templates](/templates).
+The framework ships with production-ready templates including [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (visual plans and PR recaps), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch), and more. Each is a complete app with UI, agent actions, database schema, and AI instructions ready to go. See [Templates](/docs/cloneable-saas) for the full catalog.
 
 ### Can I customize templates? {#can-i-customize-templates}
 
@@ -81,17 +66,11 @@ That's the whole point. Fork a template and customize it by asking the agent. "A
 
 ### Can I build something the templates don't cover? {#build-from-scratch}
 
-Yes. Run `npx @agent-native/core create my-app` without picking a template — you get the framework scaffolding (frontend, backend, agent panel, database) but no domain-specific code. See [Getting Started](/docs/getting-started). For agent-first products with no traditional UI, see [Pure-Agent Apps](/docs/pure-agent-apps).
+Yes. Run `npx @agent-native/core create my-app` and accept the default **Starter** selection in the picker (or pass `--template starter`) — you get the framework scaffolding (frontend, backend, agent panel, database) but no domain-specific code. See [Getting Started](/docs/getting-started). For agent-first products with no traditional UI, see [Pure-Agent Apps](/docs/pure-agent-apps).
 
 ### Can I try it without forking a template? {#try-with-a-skill}
 
-Yes. Add an agent-native **skill** to a coding agent you already use (Claude Code, Codex, Cursor) with one command — no scaffold, no deploy. Start with the **Plans** skill:
-
-```bash
-npx @agent-native/core@latest skills add visual-plan
-```
-
-It installs the skill, registers the hosted MCP connector, and signs you in once; then run `/visual-plan`. See the [Skills Guide](/docs/skills-guide#app-backed-skills) for more skills.
+Yes — install a skill into a coding agent you already use with one command and no scaffold required. See [Try it with a skill](/docs/getting-started#try-with-a-skill) in Getting Started for the full walkthrough.
 
 ## Agent capabilities {#agent-capabilities}
 
@@ -117,9 +96,9 @@ The agent always knows what the user is currently viewing. The UI writes navigat
 
 Any AI coding tool that reads project instructions. The framework uses AGENTS.md as the universal standard and auto-creates symlinks for specific tools:
 
-- **Claude Code** — reads CLAUDE.md (symlinked from AGENTS.md)
-- **Cursor** — reads .cursorrules (symlinked from AGENTS.md)
-- **Windsurf** — reads .windsurfrules (symlinked from AGENTS.md)
+- **Claude Code** — reads CLAUDE.md (symlinked from AGENTS.md by the CLI setup)
+- **Cursor** — reads AGENTS.md directly, or `.cursorrules` (Cursor's legacy location) if present in your project
+- **Windsurf** — reads .windsurfrules (symlinked from AGENTS.md by the CLI setup)
 - **Codex, Gemini, and others** — work via the embedded agent panel
 - **Builder.io** — cloud-hosted agent with visual editing and collaboration
 

package/docs/content/frames.md

@@ -40,13 +40,15 @@ The panel runs in one of two tool modes:
 - **App mode** — the agent only has your app's own tools: the actions you
   defined with `defineAction`, plus navigation and context. No filesystem or
   shell access. This is what end users get.
-- **Code mode** — adds the shared coding tools (`bash`, `read`, `edit`,
-  `write`) and database access on top of the app tools, so the agent can change
-  the app's own source. Code requests are gated: when a message requires code
+- **Code mode** — adds the shared coding tools (`bash`, `read`, `edit`, `write`)
+  and database access on top of the app tools, so the agent can change the app's
+  own source. Code requests are gated: when a message requires code
   (`type: "code"`) and no code-capable frame is connected, the panel shows a
   dialog explaining that code changes need Agent Native Desktop or Builder;
   when a frame is connected, the request is routed to it and a code-agent
-  indicator shows while it works (`useSendToAgentChat`).
+  indicator shows while it works (`useSendToAgentChat`). For the canonical
+  coding-tool list and shared UI contracts, see
+  [Agent-Native Code UI](/docs/code-agents-ui).
 
 "Code mode" is the agent-capability toggle — distinct from environment dev mode
 (`NODE_ENV` / Vite). For back-compat the underlying `AGENT_MODE` env var, the
@@ -104,7 +106,8 @@ agent, regardless of which frame is hosting it:
 
 1. **Send a message** — `sendToAgentChat()` sends a message to the agent. The
    `useSendToAgentChat()` hook wraps it with the code-request gating described
-   above and returns a `codeRequiredDialog` element to render.
+   above and returns a `codeRequiredDialog` element to render. See
+   [Drop-in Agent](/docs/drop-in-agent) for full usage and options.
 2. **Generation state** — `useAgentChatGenerating()` tracks when the agent is
    running, so the UI can show progress without polling the agent directly.
 3. **Polling sync** — database-backed sync keeps UI caches fresh when the agent
@@ -124,10 +127,4 @@ cd my-app
 pnpm dev
 ```
 
-The local dev frame is an internal tooling package (it is not published to npm),
-used when developing templates inside this repository. It loads the active
-app's dev server in an iframe and mounts the embedded panel beside it, selecting
-the app via the `app` query param. The integrated CLI terminal requires Agent
-Native Desktop, which provides the local code and PTY access the terminal needs;
-without it, the panel shows the chat surface and prompts you to open Desktop to
-use the CLI.
+The local dev frame (the private `@agent-native/frame` package in the framework repo) is an internal tooling package that is not published to npm. It loads the active app's dev server in an iframe and mounts the embedded panel beside it, selecting the app via the `app` query param. The integrated CLI terminal requires Agent Native Desktop, which provides the local code and PTY access the terminal needs; without it, the panel shows the chat surface and prompts you to open Desktop to use the CLI.

package/docs/content/getting-started.md

@@ -29,40 +29,43 @@ pnpm install && pnpm dev
 
 The `create` command defaults to a workspace monorepo. It shows a multi-select picker — pick one template or several (Mail + Calendar + Forms, for example) and they all scaffold into one workspace sharing auth, brand, and agent config. If you want one app directory instead, pass `--standalone`.
 
-Open the URL the dev server prints. Workspace apps use app-specific ports, often `http://localhost:8080` or another 808x port; standalone apps usually use `http://localhost:3000`.
+Open the URL the dev server prints. The workspace gateway always starts on port 8080 and serves every app through it; individual apps run on their own ports that are printed at startup. Standalone apps default to `http://localhost:3000`.
 
-### Testing local framework changes {#testing-local-framework-changes}
+### Agent credentials {#agent-credentials}
 
-Framework contributors can scaffold against the current checkout instead of the
-published packages:
+In local development the embedded agent panel picks up your existing Claude Code or Codex CLI login automatically, or reads `ANTHROPIC_API_KEY` from a `.env` file in the project root. The database defaults to SQLite (stored at `data/app.db`) when `DATABASE_URL` is not set, so you can run the full stack with no external services. For production deployments — where you'll want Postgres, a persistent secret, and bring-your-own-key per user — see [Deployment](/docs/deployment).
 
-```bash
-AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
-```
-
-With that flag, generated workspaces link both the local `@agent-native/core`
-and local `@agent-native/dispatch` packages. Use it when you need to verify
-unpublished template or package changes end-to-end in a freshly generated
-workspace. The packages run their `prepack` build first, so the linked packages
-serve fresh `dist` output instead of stale build artifacts.
+## What just happened? {#what-just-happened}
 
-To exercise the repo-local CLI itself without building first, run it through
-the root script:
+You now have a real, full-featured app running on your machine. Open it in the browser and try it:
 
-```bash
-pnpm dev:cli --help
-pnpm dev:cli code goals
-```
+- Click around the UI like you would any SaaS product.
+- Open the agent panel on the right side. Type something like "show me my settings" or "create a new entry called Welcome." Watch the agent click through the app on your behalf.
+- Anything you do by clicking, the agent can do by reading and writing the same database. Anything the agent does shows up in the UI immediately.
 
-## Try it with a skill {#try-with-a-skill}
+That parity between agent and UI is the whole point — see [What Is Agent-Native?](/docs/what-is-agent-native) for the bigger picture.
 
-Don't want to scaffold a whole app yet? Add agent-native superpowers to a coding agent you already use — Claude Code, Codex, or Cursor — with a single command. Installing the **Plans** skill turns the plans your agent writes into structured, reviewable docs with diagrams, wireframes, and inline comments:
+## Templates {#templates}
 
-```bash
-npx @agent-native/core@latest skills add visual-plan
-```
+Each template is a complete app with UI, agent actions, database schema, and AI instructions ready to go:
 
-That one command installs the skill instructions, registers the hosted MCP connector, and signs you in — no marketplace browsing, no manual OAuth. Then run `/visual-plan` in your agent. See the [Skills Guide](/docs/skills-guide#app-backed-skills) for more skills, local/offline installs, and how app-backed skills work.
+| Template                              | What it is                                                            |
+| ------------------------------------- | --------------------------------------------------------------------- |
+| [Calendar](/docs/template-calendar)   | Agent-native Google Calendar + Calendly-style booking                 |
+| [Content](/docs/template-content)     | Agent-native Notion / Google Docs                                     |
+| [Brain](/docs/template-brain)         | Company chat with cited institutional memory                          |
+| [Assets](/docs/template-assets)       | Brand asset libraries and generated media                             |
+| [Slides](/docs/template-slides)       | Agent-native Google Slides / Pitch                                    |
+| [Video](/docs/template-videos)        | Programmatic motion graphics and product-demo videos on Remotion      |
+| [Analytics](/docs/template-analytics) | Agent-native Amplitude / Mixpanel                                     |
+| [Mail](/docs/template-mail)           | Agent-native Superhuman / Gmail                                       |
+| [Clips](/docs/template-clips)         | Async screen + camera recording with transcription and AI summaries   |
+| [Design](/docs/template-design)       | Agent-native HTML prototyping studio                                  |
+| [Forms](/docs/template-forms)         | Agent-native Typeform                                                 |
+| [Plan](/docs/template-plan)           | Visual plans and PR recaps with diagrams, wireframes, and annotations |
+| [Dispatch](/docs/template-dispatch)   | Workspace control plane — shared secrets, integrations, routing       |
+
+Browse the [template gallery](/templates) for live demos, or see [Templates](/docs/cloneable-saas) for the full catalog and the clone → customize → deploy flow.
 
 ## Creating vs adding apps {#creating-vs-adding-apps}
 
@@ -90,15 +93,39 @@ To make a second app from the same template, give it a new app name:
 npx @agent-native/core add-app design-lab --template design
 ```
 
-## What just happened? {#what-just-happened}
+## Try it with a skill {#try-with-a-skill}
 
-You now have a real, full-featured app running on your machine. Open it in the browser and try it:
+Don't want to scaffold a whole app yet? Add agent-native superpowers to a coding agent you already use — Claude Code, Codex, or Cursor — with a single command. Installing the **Plans** skill turns the plans your agent writes into structured, reviewable docs with diagrams, wireframes, and inline comments:
 
-- Click around the UI like you would any SaaS product.
-- Open the agent panel on the right side. Type something like "show me my settings" or "create a new entry called Welcome." Watch the agent click through the app on your behalf.
-- Anything you do by clicking, the agent can do by reading and writing the same database. Anything the agent does shows up in the UI immediately.
+```bash
+npx @agent-native/core@latest skills add visual-plan
+```
 
-That parity between agent and UI is the whole point — see [What Is Agent-Native?](/docs/what-is-agent-native) for the bigger picture.
+That one command installs the skill instructions, registers the hosted MCP connector, and signs you in — no marketplace browsing, no manual OAuth. Then run `/visual-plan` in your agent. See the [Skills Guide](/docs/skills-guide#app-backed-skills) for more skills, local/offline installs, and how app-backed skills work.
+
+## Project structure {#project-structure}
+
+Every agent-native app — whether from a template or from scratch — follows the same structure:
+
+```text
+my-app/
+  app/             # React frontend (routes, components, hooks)
+  server/          # Nitro API server (routes, plugins)
+  actions/         # Agent-callable actions
+  .agents/         # Agent instructions and skills
+```
+
+Templates add domain-specific code on top: database schemas in `server/db/`, API routes in `server/routes/api/`, and actions in `actions/`. Building from scratch? See [Creating Templates](/docs/creating-templates) for `vite.config.ts`, `tsconfig.json`, and Tailwind setup.
+
+## Next docs to read {#next-docs}
+
+Once your app is running, the most useful follow-ups are:
+
+- **Connect Slack or email** so you can message your agent from anywhere — see [Messaging](/docs/messaging).
+- **Set up Dispatch as your central inbox** to triage messages and orchestrate across multiple apps — see [Dispatch](/docs/dispatch).
+- **Customize via Workspace** — edit instructions, skills, memory, and connect MCP servers per user — see [Workspace](/docs/workspace).
+- **Troubleshoot common setup questions** — see the [FAQ](/docs/faq).
+- **Understand the architecture** — see [Key Concepts](/docs/key-concepts) for how SQL, actions, polling sync, and context awareness fit together.
 
 ## Try one concrete next step {#first-next-step}
 
@@ -114,59 +141,35 @@ Good first moves:
 
 Agent-Native Code understands built-in slash goals such as `/migrate` and `/audit`, plus project commands in `.agents/commands/*.md`. Use `agent-native code list`, `status`, `resume`, `stop`, or `ui` to inspect and control the same run from the CLI, the local UI, or the Desktop Code tab.
 
-## Next docs to read {#next-docs}
-
-Once your app is running, the most useful follow-ups are:
-
-- **Connect Slack or email** so you can message your agent from anywhere — see [Messaging](/docs/messaging).
-- **Set up Dispatch as your central inbox** to triage messages and orchestrate across multiple apps — see [Dispatch](/docs/dispatch).
-- **Customize via Workspace** — edit instructions, skills, memory, and connect MCP servers per user — see [Workspace](/docs/workspace).
-- **Troubleshoot common setup questions** — see the [FAQ](/docs/faq).
-- **Understand the architecture** — see [Key Concepts](/docs/key-concepts) for how SQL, actions, polling sync, and context awareness fit together.
+## Architecture principles {#architecture-principles}
 
-## Templates {#templates}
+The three principles that apply to every agent-native app:
 
-Each template is a complete app with UI, agent actions, database schema, and AI instructions ready to go:
+- **Agent + UI are equal partners** — everything the UI can do, the agent can do, and vice versa; they share the same database.
+- **Everything is an action** — agent tools, UI mutations, HTTP endpoints, MCP tools, and CLI commands are all the same `defineAction()` definition.
+- **All state in SQL** — app state, navigation, drafts, and settings live in the database so both agent and UI always see the same picture.
 
-| Template                              | Replaces                                        |
-| ------------------------------------- | ----------------------------------------------- |
-| [Calendar](/docs/template-calendar)   | Google Calendar, Calendly                       |
-| [Content](/docs/template-content)     | Notion, Google Docs                             |
-| [Brain](/docs/template-brain)         | Company chat with cited institutional memory    |
-| [Assets](/docs/template-assets)       | Brand asset libraries and generated media       |
-| [Slides](/docs/template-slides)       | Google Slides, Pitch                            |
-| [Video](/docs/template-videos)        | Remotion-based video editing                    |
-| [Analytics](/docs/template-analytics) | Amplitude, Mixpanel                             |
-| [Mail](/docs/template-mail)           | Superhuman, Gmail                               |
-| [Clips](/docs/template-clips)         | Replaces Loom — screen + camera recording       |
-| [Design](/docs/template-design)       | HTML prototyping studios                        |
-| [Forms](/docs/template-forms)         | Typeform                                        |
-| [Dispatch](/docs/template-dispatch)   | Workspace control plane — integrations, routing |
-| [Starter](/docs/template-starter)     | Minimal scaffold — build from scratch           |
-
-Browse the [template gallery](/templates) for live demos, or see [Templates](/docs/cloneable-saas) for the full list and the clone → customize → deploy flow.
+The definitive six rules are in [Key Concepts](/docs/key-concepts).
 
-## Project structure {#project-structure}
+## Testing local framework changes {#testing-local-framework-changes}
 
-Every agent-native app — whether from a template or from scratch — follows the same structure:
+Framework contributors can scaffold against the current checkout instead of the
+published packages:
 
-```text
-my-app/
-  app/             # React frontend (routes, components, hooks)
-  server/          # Nitro API server (routes, plugins)
-  actions/         # Agent-callable actions
-  .agents/         # Agent instructions and skills
+```bash
+AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
 ```
 
-Templates add domain-specific code on top: database schemas in `server/db/`, API routes in `server/routes/api/`, and actions in `actions/`. Building from scratch? See [Creating Templates](/docs/creating-templates) for `vite.config.ts`, `tsconfig.json`, and Tailwind setup.
-
-## Architecture principles {#architecture-principles}
+With that flag, generated workspaces link both the local `@agent-native/core`
+and local `@agent-native/dispatch` packages. Use it when you need to verify
+unpublished template or package changes end-to-end in a freshly generated
+workspace. The packages run their `prepack` build first, so the linked packages
+serve fresh `dist` output instead of stale build artifacts.
 
-These principles apply to all agent-native apps. Skim them now, revisit them when you're customizing.
+To exercise the repo-local CLI itself without building first, run it through
+the root script:
 
-1. **Agent + UI are equal partners** — Everything the UI can do, the agent can do, and vice versa. They share the same database and always stay in sync. You don't think about "the agent" and "the app" separately — you think about them together.
-2. **Context-aware** — The agent always knows what you're looking at. If an email is open, it knows which one. If you select text and hit Cmd+I, it can act on just that selection.
-3. **Skills-driven** — Core functionality has written instructions so the agent doesn't explore from scratch every time. New features update all four areas: UI, actions, skills/instructions, and application state.
-4. **Inter-agent communication** — Agents can discover and call each other via the A2A protocol. Tag your analytics agent from the mail app to pull data into a draft.
-5. **Fully portable** — Any SQL database Drizzle supports, any hosting backend Nitro supports, any AI coding tool. These are non-negotiable.
-6. **Fork and customize** — Apps you clone and evolve. The agent can modify the app's own code — components, routes, styles, actions — so it gets better over time.
+```bash
+pnpm dev:cli --help
+pnpm dev:cli code goals
+```