@agent-native/core-corpus 0.213.1 → 0.216.0

package/corpus/templates/slides-2/.agents/skills/external-agents/SKILL.md

@@ -0,0 +1,549 @@
+---
+name: external-agents
+description: >-
+  Connect external agents and MCP hosts (Claude, Claude Desktop, Claude Code,
+  ChatGPT custom MCP apps, Codex, Cursor, Claude Cowork, VS Code GitHub
+  Copilot, Goose, Postman, MCPJam) to an agent-native app over MCP, and
+  round-trip artifacts back into the UI with MCP Apps and deep links. Use when
+  adding an action's `link` builder or `mcpApp`, wiring the
+  `/_agent-native/open` route, exposing an "ingest" action to MCP/A2A, or
+  scaffolding apps from an external agent.
+scope: dev
+metadata:
+  internal: true
+---
+
+# External Agents (MCP bridge + deep links)
+
+## Rule
+
+- **The connected model is the author.** Write content yourself with create/update tools; never delegate via `ask_app` or wait on an unreachable in-app form — see `DEFAULT_AGENT_NATIVE_MCP_INSTRUCTIONS`.
+- **Result shape and key tools are in `actions`** (Return Values, Key Actions).
+- **Artifacts fit in one call.** Up to 500,000 characters; return a `storing-data` handle.
+- **One tab, one id.** WebMCP sends `X-Agent-Native-Browser-Tab`; state resolves to the driving tab (`context-awareness`).
+
+An agent-native app is reachable by any MCP-compatible host. Keep
+setup simple: for workspace or cross-app access, add one remote MCP connector:
+`https://dispatch.agent-native.com/mcp`. Dispatch's Agents page
+controls whether that single connector reaches all apps or only selected apps,
+and Dispatch filters `list_apps`, `ask_app`, and `open_app` to the granted set.
+For a deliberately isolated app, add that app directly at
+`https://<app>.agent-native.com/mcp` or
+`https://<your-host>/mcp`.
+
+In-app, the Agent page's **Access** tab (`/agent#access`) is the home for this:
+it shows MCP/A2A URLs, client setup steps, and the full `/mcp/connect` page.
+Point users there instead of dictating URLs in chat.
+
+OAuth-capable hosts use the standard remote MCP OAuth flow — Claude, Claude
+Code, and ChatGPT discover the protected resource and store their own tokens;
+per-host steps are below. Local stdio proxying and older clients can still use
+`npx @agent-native/core connect <url>`, which mints a per-user, scoped,
+revocable token from a logged-in browser session; no shared secret is copied.
+
+The framework serves MCP `2026-07-28` natively over stateless, per-request HTTP
+and keeps the established stateless path for 2025-era clients. New MCP client
+code uses the split `@modelcontextprotocol/client` package with
+`versionNegotiation: { mode: "auto" }`; do not pin a protocol header or
+hand-send `initialize`. OAuth callback handlers preserve `state` and pass the
+RFC 9207 `iss` parameter to the v2 SDK for validation before exchanging a
+code. The authorization server accepts HTTPS Client ID Metadata Documents after
+strict URL, SSRF, size, redirect, schema, and exact callback validation; URL-like
+client ids never fall back to dynamic registration. Traditional non-URL clients
+continue to use public-client dynamic registration.
+
+Actions marked `needsApproval` use MCP 2026 `input_required` elicitation. The
+approval is bound to the authenticated caller, exact action, exact arguments,
+and expiry, and its durable grant is consumed atomically before the action runs.
+If the host cannot complete the approval exchange, the predicate throws, the
+state is invalid or replayed, or durable storage is unavailable, the action
+fails closed.
+
+Claude and ChatGPT can cache custom connector tool/resource metadata. After
+changing MCP App metadata or the shared `embedApp()` shell, validate with a
+fresh tool call; if the host still behaves like the old descriptor, reconnect
+the Claude connector or rescan/review the ChatGPT connector.
+
+Once connected, every action that produces or lists a navigable resource SHOULD
+return a deep link from a `link` builder, so the external agent can surface an
+**"Open in <app> →"** link that drops the user back into the running UI at the
+right view and record. Actions can also declare `mcpApp` so hosts that support
+MCP Apps render an inline interactive preview. The link is a pure pointer —
+the record-focusing write is always scoped to the **browser session**, never
+the agent's token.
+
+## Why
+
+External agents are great at producing artifacts (a draft, an event, a
+dashboard) but they live in a terminal, chat host, or another app. Without a
+bridge, the user gets a wall of JSON and has to go find the thing. MCP Apps
+give compatible hosts an inline review/edit surface; the deep-link bridge
+closes the loop everywhere else by handing the user a single link that opens
+the real app focused on exactly what was produced. It reuses the existing
+`navigate` / `application_state` contract the UI already drains every 2s (see
+**context-awareness**) — we never invent a second navigation mechanism.
+
+## App-facing MCP connectors
+
+Apps can also consume connected remote MCP servers as a server-side API. The
+framework stores each connector's OAuth client registration, discovery metadata,
+access token, and refresh token in the encrypted `oauth_tokens` store, scoped to
+the user or organization. The browser and sandboxed MCP App iframes never
+receive those credentials.
+
+Use the hidden core actions `list-mcp-tools` and `call-mcp-tool` when an app UI
+needs a request-scoped API surface. Server-side app actions can import
+`listVisibleMcpTools` and `callMcpTool` from `@agent-native/core/mcp-client`.
+Both paths require an authenticated request context and enforce user/org server
+visibility plus MCP App visibility metadata. Pass the configured server id and
+the server's original tool name; the framework resolves the internal prefixed
+tool name and injects the connector's bearer token.
+
+```ts
+import { callMcpTool } from "@agent-native/core/mcp-client";
+
+const result = await callMcpTool("org_acme_linear", "list_issues", {
+  project: "<PROJECT_ID>",
+});
+```
+
+Use this for bounded product workflows (for example, syncing issues or
+refreshing analytics). Do not expose a raw token, arbitrary server URL, or
+unbounded proxy from an app action. Keep provider-specific schemas and access
+checks in the app action, and use the connector catalog/OAuth button for setup.
+
+## Provider API connectors
+
+The shared workspace connection catalog is also the setup surface for provider
+APIs. When a provider advertises OAuth, show that connection as the primary
+setup action and retain its API key or token as an explicit fallback. Current
+shared OAuth providers include Figma, GitHub, Google Drive, HubSpot, Jira Cloud, Notion, and Sentry. Slack
+uses its managed messaging-install OAuth flow. Gmail,
+Calendar, and Slides may use template-owned Google OAuth flows with broader
+scopes; do not replace those flows with the narrower Drive connection.
+
+Provider API actions resolve credentials server-side. Pass a granted
+`connectionId` when a request must use a particular OAuth account; never copy
+the access token into a browser, extension, MCP App, prompt, or stored action
+payload. Key-only providers should remain in the normal scoped secrets flow
+until their upstream OAuth app, scopes, refresh behavior, and identity mapping
+have been implemented and configured.
+
+Extensions can consume both classes of connection through the same host-side
+action bridge. Use `agentNative.mcp.listTools()` / `callTool()` for connected
+remote MCP servers, and `agentNative.providerApi.catalog()` / `docs()` to
+discover template-owned provider API actions. The bridge
+preserves the current user's or organization's access scope and never exposes
+MCP URLs, OAuth tokens, refresh tokens, or client secrets to the iframe. Local
+file extensions must declare the corresponding action names in
+`permissions.appActions`.
+
+## How
+
+### 1. Connect to hosted apps
+
+Use one connector for normal workspace access:
+
+```text
+https://dispatch.agent-native.com/mcp
+```
+
+Then open Dispatch → Agents to choose whether the gateway exposes every app or
+only selected IDs. Use `list_apps` for grants, `open_app` for links/embeds, and
+named actions when cataloged. Use `ask_app` only when direct action is
+unavailable or app-agent reasoning helps.
+
+Use a direct app URL only when you intentionally want one isolated app:
+
+```text
+https://mail.agent-native.com/mcp
+https://<your-app>.agent-native.com/mcp
+```
+
+Claude / Claude Desktop: add a custom connector with the URL, click Connect,
+then sign in and approve `mcp:read`, `mcp:write`, `mcp:apps`, and
+`offline_access`. Claude Code:
+add the same remote HTTP URL, restart if needed, run `/mcp`, and choose
+Authenticate. ChatGPT: create a custom MCP connector/app, paste the same URL,
+choose OAuth, scan/discover tools, then sign in and approve scopes. Each host
+stores its own OAuth tokens; MCP App iframes never receive raw tokens because
+the host mediates tool and resource calls over the authenticated MCP
+connection.
+
+For local stdio proxying, Codex/Cowork compatibility, or clients without
+remote MCP OAuth, use the hosted connect fallback:
+
+```bash
+npx @agent-native/core@latest connect https://dispatch.agent-native.com
+# or, for an isolated app:
+npx @agent-native/core@latest connect https://mail.agent-native.com
+```
+
+The command opens the app in the browser, the user clicks **Authorize**, and a
+per-user, scoped, revocable token is written to the selected client config. The
+no-CLI equivalent is `https://<app>/mcp/connect`, which shows
+the copyable MCP URL, Claude / ChatGPT / Cursor / Claude Code / Codex / Other
+steps, and static-token fallback for clients that need it.
+
+Re-running `npx @agent-native/core@latest connect <url> --client claude-code` over an older
+Claude bearer-token entry is the migration path: the CLI replaces
+`Authorization` headers with URL-only OAuth config and tells the user to
+authenticate from `/mcp`.
+
+To re-authenticate an already-installed local/fallback client without
+reinstalling skills or connectors, use:
+
+```bash
+npx -y @agent-native/core@latest reconnect https://dispatch.agent-native.com --client codex
+# or:
+npx -y @agent-native/core@latest connect reconnect https://dispatch.agent-native.com --client codex
+```
+
+With no URL, `reconnect` searches local client configs for the existing Agent
+Native MCP entry. With a URL, it reconnects only the clients that already have
+that MCP URL; pass `--client` to limit which configs it searches. Pass
+`--name <serverName>` only when you need to force a custom server name.
+
+Under the hood: a logged-in browser session mints an `A2A_SECRET`-signed JWT
+carrying the caller's `sub` + `org_domain` and a unique `jti`, so tool runs
+stay tenant-scoped via `runWithRequestContext`. The existing
+`/mcp` endpoint accepts it like any bearer — no new endpoint.
+The same Connect page lists and revokes minted tokens by `jti`; treat them
+like personal access tokens. Nothing exposes the deployment's shared secret.
+
+### 1a. Generic cross-app verbs + scaffolding
+
+Once connected, on top of the per-action tools the MCP server also exposes a
+stable verb set (see `packages/core/src/mcp/builtin-tools.ts`) so an external
+agent has a predictable surface without guessing per-app action names:
+
+- `list_apps` — workspace apps + their URLs / running state.
+- `open_app({ app, view?, path?, params?, embed? })` — returns a deep link or
+  direct same-origin app route (no user-data side effects); surfaces as an
+  "Open …" link and, with `embed: true`, an inline full-app MCP App in capable
+  hosts.
+- `ask_app({ app, message })` — routes a natural-language task to that app's
+  in-app agent (delegates to the existing `ask-agent` meta-tool). It also
+  accepts `async` and `maxWaitMs`; hosted calls wait at most 25 seconds inline
+  and return a durable `taskId` plus an `ask_app_status` poll instruction when
+  the task is still running.
+- `ask_app_status({ app, taskId })` — retrieves the current or terminal result
+  for a durable `ask_app` task. Dispatch checks the selected-app grant again
+  before polling.
+- `create_workspace_app({ name, template })` — scaffolds + boots a new app via
+  the workspace path (rejects non-allow-listed templates), returns its running
+  URL + deep link.
+- `list_templates` — the allow-listed templates only.
+
+A same-named template action overrides a builtin (template-over-core
+precedence). Disable the set with `MCPConfig.builtinCrossAppTools: false`.
+
+The advertised `tools/list` and `resources/list` catalogs are intentionally
+tiny by default for ChatGPT/Claude-style app hosts, including OAuth MCP Apps
+callers. The unified gateway exposes only generic verbs (`list_apps`, `open_app`,
+`ask_app`, `create_embed_session`); named actions come from a direct app MCP
+connection or page WebMCP. Route UI through
+`open_app({ embed: true })`. Stdio/code clients use the same compact surface
+unless they explicitly opt into the full catalog, and
+`publicAgent.expose` remains the action-level opt-in for safe read/ingest tools
+outside the compact MCP Apps catalog. Apps can set
+`externalAgents.authenticatedReads: "auto"` to automatically advertise every
+action that is GET + `readOnly` + `publicAgent.requiresAuth`, instead of
+maintaining a long connector allow-list. This policy never includes writes by
+default; use `writes: "ask_app_only"` to keep mutations behind `ask_app`, and
+use `denyActions` for defense-in-depth vetoes. `tool-search` remains available
+for discovery, but a searched action still needs to be in the connector
+catalog, included by the authenticated-read policy, or enabled by the explicit
+full-catalog opt-in before `tools/call` can execute it. Do not rely on
+action-specific `mcpApp` resources appearing in ChatGPT/Claude discovery by
+default; use `open_app` for the
+first-class app embed path. If a specific
+action truly must remain visible in that compact app-host catalog, set
+`mcpApp.compactCatalog: true` as a rare escape hatch.
+
+Generic core `db-schema` and `db-query` are intentionally not automatic
+external reads. They remain available to the in-app agent through the normal
+scoped SQL path, but broad schema/SQL access is too powerful to infer from
+read-only metadata alone. If an app needs direct external querying, expose an
+app-owned bounded GET action or add an explicit table/column allow-list with
+row, byte, timeout, and audit limits. Keep `db-exec` and `db-patch` outside
+automatic external-agent exposure.
+
+Authentication and authorization are separate gates. A verified MCP OAuth or
+connect token identifies the caller and organization; `publicAgent` only opts
+an action into the external protocol surface and does not grant record access.
+Actions still need `accessFilter`, `resolveAccess`, or `assertAccess` so private
+documents/dashboards, shares, organization boundaries, and roles are enforced.
+For Slack, verified DMs are linked to an existing Agent-Native org member
+before execution and run with that user's context; shared channels use a
+service principal, and guests/external members cannot borrow personal access.
+Managed Slack OAuth and the generated app manifest both request
+`users:read.email`; existing installs must reconnect/reinstall after a scope
+change, while legacy bot-token installs must add the scope in Slack manually.
+
+### 1b. Fast-path expectations for MCP Apps hosts
+
+Keep ChatGPT/Claude paths short. For a known app-facing intent, the external
+agent should call the specific action that creates or opens the thing, then let
+the MCP App launch the route. Do **not** route simple UI handoffs
+through `ask_app`, broad `list_resources`, or generic app-agent delegation just
+to find a screen.
+
+Expected shape:
+
+- Email draft: `manage_draft` → inline Mail compose route. The widget calls
+  `create_embed_session` itself.
+- Dashboard/filter/search: `open_app({ path, embed: true })` or the dashboard
+  action with `mcpApp` → inline full app/dashboard route.
+- Calendar invite: `manage-event-draft` → inline Calendar event draft route.
+- Forms/content/slides/design/clips: create/search action with `mcpApp` →
+  inline editor/player route.
+
+`list_apps` is fine when the model genuinely needs to choose among granted
+apps. `resources/list`/`resources/read` are host plumbing for MCP Apps UI
+resources; they are not a planning strategy. If a host/model repeatedly calls
+large discovery tools before obvious app-facing actions, tighten action names,
+descriptions, `mcpApp` metadata, or compact-catalog filtering until the direct
+path is obvious.
+
+### 2. Add a `link` builder to an action
+
+`defineAction` accepts an optional `link` builder. When set, every MCP/A2A
+result for that tool auto-appends a markdown `[label →](absoluteUrl)` block and
+a structured `_meta["agent-native/openLink"] = { label, view, webUrl,
+desktopUrl, vscodeUrl }`; `tools/list` adds
+`annotations["agent-native/producesOpenLink"]` plus a description suffix so the
+external agent knows the tool yields an openable link.
+
+Real example — mail's `manage-draft` (`templates/mail/actions/manage-draft.ts`):
+
+```ts
+import { buildDeepLink } from "@agent-native/core/server";
+
+function composeDeepLink(draft: Record<string, string>): string {
+  return buildDeepLink({
+    app: "mail",
+    view: "inbox",
+    compose: encodeComposeDraft(draft), // base64url JSON → compose-<id> draft
+  });
+}
+
+export default defineAction({
+  // ...schema, run...
+  link: ({ result }) => {
+    if (!result || typeof result !== "object") return null;
+    const draft = (result as { draft?: Record<string, string> }).draft;
+    const id = (result as { id?: string }).id;
+    if (!draft || !id) return null;
+    return { url: composeDeepLink(draft), label: "Open draft in Mail", view: "inbox" };
+  },
+});
+```
+
+List/search actions point at a record-focused view the same way — mail's
+`list-emails` returns
+`{ url: buildDeepLink({ app: "mail", view: "inbox", params: { label, search } }), label: "Open list in Mail" }`.
+
+**The `link` contract:** pure, synchronous, **no I/O, no awaits**. It runs
+best-effort — a throw, `null`, or `undefined` is swallowed and **never** fails
+the tool call. It only reads the call's `args` and `result`; it must not query
+the DB, read app-state, or call other actions.
+
+### 2a. Optional MCP Apps UI
+
+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 `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. Keep the `link` fallback even
+when adding `mcpApp` — non-UI clients still need the "Open in … →" link.
+
+```ts
+import { embedApp } from "@agent-native/core";
+
+export default defineAction({
+  // ...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",
+    }),
+  },
+});
+```
+
+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. For known first-party handoffs, prefer a direct action with
+`mcpApp` (e.g. Mail `manage-draft`, Calendar `manage-event-draft`) over letting
+the model hunt through screens; `open_app({ path, embed: true })` is the
+generic escape hatch for full dashboards, filtered inboxes, analyses, or
+extension pages.
+
+The host bridges (Claude transplant vs. ChatGPT `window.openai`), embed start
+tickets, extension-page `srcDoc` rendering inside chat embeds, host sizing
+(`embedApp({ height })`), `sendToAgentChat`, `_meta.ui.domain` rules, and
+ngrok/prod testing caveats are documented in
+**`references/mcp-apps-embedding.md`**. Read it before changing the
+`embedApp()` shell, the `ui://` resource, or any host-bridge behavior.
+
+### 3. The `/_agent-native/open` route
+
+`buildDeepLink(...)` returns the app-relative path
+`/_agent-native/open?app=…&view=…&<recordId>=…`. The MCP layer turns that into
+an absolute web URL (`toAbsoluteOpenUrl`, using the request origin), a
+desktop `agentnative://open?…` URL (`toDesktopOpenUrl`), and a VS Code
+extension URL (`toVsCodeOpenUrl`) for
+`vscode://builderio.agent-native/open?url=…`. When the user clicks the web
+link in any browser or inline webview, `GET /_agent-native/open`
+(`createOpenRouteHandler`, mounted by the core routes plugin, gated by
+`disableOpenRoute`, customizable via `resolveOpenPath`):
+
+1. Resolves the **browser** session via `getSession` (the auth guard bypasses
+   the exact path `/_agent-native/open`).
+2. If unauthenticated, serves the configured login HTML **at the same URL**
+   (`getConfiguredLoginHtml`); the form's success handler reloads
+   `window.location`, re-entering the route authenticated — no `?next=`
+   plumbing.
+3. Writes the existing one-shot `navigate` application-state command (payload =
+   every non-reserved query param + `view`) scoped to the browser session's
+   email with `requestSource: "deep-link"`, and decodes a `compose` base64url
+   draft into a `compose-<id>` key.
+4. 302-redirects to a safe same-origin relative path (`to=`, else `/<view>`,
+   else `resolveOpenPath`), forwarding `f_*` filter params so lists/dashboards
+   open pre-filtered before the `navigate` command is even drained.
+
+Cross-origin, scheme-relative `//host`, and control-char redirects are rejected
+(open-redirect guard). **Identity rule:** the link carries no privileged
+state — it is just `view` + record ids + filters. The record-focusing
+`navigate` write is scoped to whoever is logged into the browser, never the
+external agent's MCP token. See **context-awareness** for the
+`navigate`/`application_state` contract this bridges to.
+
+### 4. "Ingest" actions for external agents
+
+An action an external agent reads to pull live app state into its own context
+must be: `http: { method: "GET" }` + `readOnly: true` +
+`publicAgent: { expose: true, readOnly: true, requiresAuth: true }`. GET +
+`readOnly` keeps it side-effect-free and out of the screen-refresh change event;
+`publicAgent` is the explicit opt-in (public web routes never imply public
+MCP/A2A exposure). Design/content ingest actions MUST read **live** state
+(e.g. the Yjs document) — not the stale DB snapshot column — so the external
+agent sees what the user actually has on screen.
+
+### 5. Advanced: local development & manual setup
+
+The hosted `connect` flow above is the recommended path. For local dev, run
+the app (`pnpm dev` / `pnpm exec agent-native dev`) then point a local agent at it:
+
+```bash
+pnpm exec agent-native mcp install --client claude-code|claude-code-cli|codex|cowork|cursor|opencode|github-copilot \
+  [--app <id>] [--scope user|project]
+```
+
+It provisions a token (random `ACCESS_TOKEN` into the workspace `.env` for
+local dev, or a `signA2AToken` JWT for a detected hosted origin) and writes an
+idempotent stdio server entry — `.mcp.json` / `~/.claude.json` for Claude Code,
+the `[mcp_servers.*]` block in `~/.codex/config.toml` for Codex,
+`.cursor/mcp.json` / `~/.cursor/mcp.json` for Cursor, `opencode.json` /
+`~/.config/opencode/opencode.json` for OpenCode, `.vscode/mcp.json` / VS Code
+user `mcp.json` for GitHub Copilot / VS Code, and the Claude-Code JSON shape
+for Cowork. The entry runs `pnpm exec agent-native mcp serve --app <id>`, by
+default a **thin stdio proxy** to the running local app's
+`/mcp` (live registry + HMR + correct deep links stay the single
+source of truth; `--standalone` builds the registry in-process). Companion
+subcommands: `mcp uninstall`, `mcp status`, `mcp token [--rotate]`. You can
+also hand-write an `http` `.mcp.json` entry with a token you supply yourself —
+the unmanaged equivalent of what `connect` writes.
+
+**Dev vs production tool surface:** in plain local dev
+(`NODE_ENV=development` and `AGENT_MODE !== "production"`) the MCP `tools/list`
+deliberately exposes only the generic builtins plus actions with
+`publicAgent.requiresAuth === false` — per-app ingest (`requiresAuth: true`)
+and mutating actions are filtered out (`filterPublicAgentActions`). The full
+surface appears when authenticated as a real caller: a deployed /
+`AGENT_MODE=production` app, or a local app reached through `connect` /
+`pnpm exec agent-native mcp install` (which provisions an identity-bearing token). A
+sparse or empty `tools/list` is diagnostic, not proof of auth failure: check
+OAuth scopes, compact-catalog filtering, and the client/server auth status
+before telling the user they are unauthenticated.
+
+## Do
+
+- Do connect local/fallback clients to Dispatch with
+  `npx @agent-native/core@latest connect https://dispatch.agent-native.com`;
+  use `npx -y @agent-native/core@latest reconnect ...` for reauth without
+  reinstalling; use a direct app URL only when the host should be isolated to
+  one app.
+- Do add a `link` builder to any action that produces or lists a navigable
+  resource (draft, event, dashboard, document).
+- Do add `mcpApp` when a UI-capable MCP host should render an inline review or
+  edit surface, while keeping the `link` fallback.
+- Do use `embedApp()` / `open_app({ embed: true })` when the right UI is the
+  existing React app at a specific route, including full app routes and focused
+  component routes like an Analytics chart embed.
+- Do test real ChatGPT/Claude web behavior with a fresh inline render after any
+  resource-shell or host-bridge change; old frames are not proof that a new
+  shell is still broken.
+- Do build the URL with `buildDeepLink(...)` — it is the single source of truth
+  for the open-route format.
+- Do keep `link` pure and synchronous; return `null` when there's nothing to
+  open.
+- Do keep `link` and `mcpApp` metadata pure and synchronous; use `embedApp()`
+  so the user sees the shared React UI.
+- Do make external-agent read/ingest actions GET + `readOnly` + `publicAgent`,
+  and read live (Yjs) state, not the stale DB column.
+- Do let the open route resolve the browser session; pass record ids as deep-
+  link params and let the UI focus them via the polled `navigate` command.
+- Do return `designSystem` on reads in visual apps (see the actions skill) and
+  put `get-design-system` and `list-design-systems` in both `connectorCatalog`
+  and `initialToolNames`; a description that points at a tool the connector
+  cannot see is a dead end.
+
+## Don't
+
+- Don't copy a deployment's shared `ACCESS_TOKEN` / `A2A_SECRET` into a client
+  config when `connect` can mint a per-user, revocable token instead.
+- Don't hand-format the `/_agent-native/open` URL — always go through
+  `buildDeepLink`.
+- Don't do I/O, awaits, DB reads, or app-state reads inside a `link` builder.
+- Don't replace deep links with MCP Apps; non-UI clients still need the link.
+- Don't hand-write product UI in `mcpApp.resource.html`; use a real React
+  route/component and embed it with `embedApp()`.
+- Don't test Claude full-app embeds against raw Vite dev modules and conclude
+  production is broken; use `pnpm exec agent-native start` with `DATABASE_URL`
+  set to Postgres and `BETTER_AUTH_SECRET` set, a preview deploy, or prod.
+- Don't scope the `navigate` write to the agent token, or pass privileged
+  state through the deep link — it's a pure pointer.
+- Don't invent a new navigation mechanism; bridge to the existing
+  `navigate`/`application_state` contract.
+- Don't widen the public template allow-list when scaffolding an app from an
+  external agent — the allow-list in `packages/shared-app-config/templates.ts`
+  is authoritative and guarded.
+
+## Related Skills
+
+- **actions** — defining actions, `publicAgent`, GET/`readOnly`
+- **context-awareness** — the `navigate` / `application_state` contract the
+  open route bridges to
+- **a2a-protocol** — the `ask-agent` meta-tool and JSON-RPC peer calls
+- **adding-a-feature** — the four-area checklist (add a `link` builder when a
+  feature produces a navigable resource)
+
+## Blueprint installer
+
+To add a whole new integration the agent-native way, `agent-native add <kind>
+<name|url>` prints a curated Markdown blueprint to stdout — pipe it into the
+external coding agent you connected (`agent-native add provider stripe |
+claude`) and it applies the changes against the live repo. A URL emits a
+generic research-and-integrate blueprint instead. Seeded kinds:
+`provider` / `channel` / `sandbox` / `action`. Add your own by dropping a
+`.md` in `packages/core/blueprints/<kind>/`. See the Blueprint Installer doc.