@agent-native/core 0.18.1 → 0.19.0

package/docs/content/cross-app-sso.md

@@ -0,0 +1,118 @@
+---
+title: "Cross-App SSO"
+description: "Sign in once across every hosted agent-native app via identity federation with Dispatch as the identity authority — opt-in per app, reversible with a single env var."
+---
+
+# Cross-App SSO
+
+Each hosted app at `*.agent-native.com` runs its own deployment with its **own separate user store**. `mail.agent-native.com` and `calendar.agent-native.com` do not share a database, a session table, or a cookie domain. So "sign in once, use every app" cannot be a shared cookie — it has to be **identity federation**, with [Dispatch](/docs/dispatch) acting as the identity authority for the workspace.
+
+This is the same trust primitive [A2A](/docs/a2a-protocol) and [External Agents](/docs/external-agents) already use — an `A2A_SECRET`-signed JWT verified at the request boundary — applied to the human sign-in path instead of agent-to-agent calls.
+
+## What & why {#what-why}
+
+Per-app user stores mean there is no single place a browser cookie could live that every app trusts. The federation model instead names one app — **Dispatch** — as the identity authority. Any other app can delegate "who is this person?" to Dispatch, get back a short-lived signed assertion of the user's verified email, and then **link that to its own local account by email**.
+
+The linking rule is deliberately narrow and additive:
+
+- **Existing same-email user → linked.** The local account is matched by verified email and reused as-is. It is **never modified, renamed, or deleted** — the federation layer only ever reads it and mints a session for it.
+- **New email → created.** A fresh local account is created for that verified email, then a normal local session is minted.
+
+This makes the rollout safe even though it logs people out. **Logout is expected.** When an app turns this on, existing sessions end and users re-authenticate through Dispatch. But they always log back into the **same email-matched account, with all their data intact**, because identity rows are only ever _added to_ — never destroyed, renamed, or repointed. There is no migration, no table rename, no destructive write anywhere in this path. (See the auth invariants in [Authentication](/docs/authentication) and [Security & Data Scoping](/docs/security).)
+
+## How it works {#how-it-works}
+
+The flow is a standard authorize → signed-token → callback redirect, with email as the only thing that crosses the trust boundary.
+
+1. **App → Dispatch (authorize).** The app sends the user to the identity authority:
+
+   ```
+   GET https://dispatch.agent-native.com/_agent-native/identity/authorize
+       ?app=<requesting-app>
+       &redirect_uri=<app-callback-url>
+       &state=<csrf-state>
+   ```
+
+2. **Dispatch authenticates the human.** If the user already has a Dispatch session, this is transparent. If not, Dispatch shows its own normal login (email/password, Google, etc. — see [Authentication](/docs/authentication)). Dispatch is just a regular agent-native app here; it is not running a special auth mode.
+
+3. **Dispatch → App (signed identity token).** Dispatch validates `redirect_uri` against a **strict allowlist** (`*.agent-native.com` plus localhost — nothing else) and 302-redirects back to the app's `redirect_uri` carrying a short-lived **`A2A_SECRET`-signed identity JWT**. The token's claims are intentionally minimal:
+
+   | Claim        | Meaning                                                  |
+   | ------------ | -------------------------------------------------------- |
+   | `sub`        | Stable user id at the identity authority                 |
+   | `email`      | The user's **verified** email — the only join key        |
+   | `name`       | Display name (non-authoritative, for UI only)            |
+   | `org_domain` | Workspace/org domain, when present                       |
+   | `scope`      | Always `"identity"` — this token authorizes sign-in only |
+   | `exp`        | **≤ 5 minutes** from issue                               |
+
+4. **App verifies and JIT-links by email.** The app verifies the token signature with its own `A2A_SECRET`, checks `scope: "identity"` and `exp`, then performs **just-in-time linking strictly by verified email**:
+   - If a local user with that email exists → reuse it unchanged.
+   - If not → create a local user for that email.
+
+5. **App mints a normal local session.** From here on the user has an ordinary local session in that app's own store — every existing access check, org scoping, and action guard works exactly as before. The federation only happened at the front door.
+
+### Opting in {#opt-in}
+
+An app participates **only** when this environment variable is set on its deployment:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+- **Set** → the app shows a **"Sign in with Agent-Native"** option that runs the flow above. Direct local login (email/password, Google) still works alongside it.
+- **Unset (default)** → **zero behavior change.** The app authenticates exactly as it did before; the federation code path is dormant. There is no schema change and nothing to migrate, so flipping the variable on or off is fully reversible at any time.
+
+## Security {#security}
+
+The whole model rests on a few deliberately small guarantees:
+
+- **Short-lived signed token.** The identity assertion is an `A2A_SECRET`-signed JWT with a **≤ 5-minute** expiry and `scope: "identity"`. It authorizes a single sign-in and cannot be replayed for long or repurposed for API/A2A access. Verification runs at the request boundary before any session is minted — same boundary discipline as [A2A auth](/docs/a2a-protocol#auth-policy).
+- **Strict `redirect_uri` allowlist.** Dispatch only ever redirects to `*.agent-native.com` or localhost. Arbitrary, scheme-relative (`//host`), and cross-origin redirect targets are rejected, so the authority can't be turned into an open-redirect or token-exfiltration oracle.
+- **Email-only join from a verified token.** The _only_ thing that crosses the trust boundary is the verified email in a signed token. The app does not accept a user id, role, org membership, or any privileged state from the wire — it derives everything locally from the matched account.
+- **Additive-only identity writes.** Linking either reuses an existing same-email account untouched or inserts a new one. No update, rename, repoint, or delete of identity rows ever happens on this path — consistent with the framework's "no breaking database changes" rule.
+- **Off by default.** With `AGENT_NATIVE_IDENTITY_HUB_URL` unset the entire feature is inert. Enabling or disabling it is one env var on one deploy, with no data side effects.
+
+## Canary rollout runbook {#canary-rollout}
+
+Cutover and rollback are **a single environment variable per app deployment**. Roll out one app at a time, verify, then expand. Do not set the variable on every app at once.
+
+**1. Deploy the code — no behavior change.**
+Ship the release to every app with `AGENT_NATIVE_IDENTITY_HUB_URL` **unset everywhere**. Because the feature is off by default, this deploy is a no-op for users: every app keeps authenticating exactly as before. Confirm normal logins still work on a couple of apps.
+
+**2. Enable the canary on ONE app (mail) only.**
+Set, on the **mail** deployment only:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+Leave every other app's environment unset. Redeploy/restart mail so it picks up the variable.
+
+**3. Verify the canary (checklist).**
+On mail, walk the full loop:
+
+- Log **out** of mail.
+- The login screen now shows **"Sign in with Agent-Native"**. Click it.
+- You are taken to **Dispatch** and complete its login (or pass straight through if already signed in there).
+- You are redirected **back to mail, logged in** — and it is the **same pre-existing account** (same email) you had before, not a new one.
+- **Mail data is intact** — your existing mailboxes, drafts, settings, and org scoping are all exactly as they were.
+- **Existing direct logins still work** — email/password and Google sign-in on mail continue to function for users who don't use the SSO button.
+
+If any check fails, go straight to step 5 (rollback) — it is instant and data-safe.
+
+**4. Expand app-by-app.**
+Once mail is verified, repeat steps 2–3 for the next app, then the next — setting `AGENT_NATIVE_IDENTITY_HUB_URL` on one deployment at a time and running the same checklist after each. Never batch-enable.
+
+**5. Rollback = unset the env var on that app's deploy.**
+To revert any app, **remove `AGENT_NATIVE_IDENTITY_HUB_URL` from that app's environment and redeploy/restart it.** The app immediately returns to its prior auth behavior. There is **no data change to undo** — identity rows were only ever added, and unsetting the variable simply makes the federation path dormant again. Each app's cutover and rollback are independent and reversible.
+
+> The rollout logs users out as each app is enabled (they re-auth via Dispatch), but they always log back into the **same email-matched account with data intact**, because identity rows are never destroyed or renamed — only added.
+
+## Related {#related}
+
+- [Authentication](/docs/authentication) — local auth modes, sessions, orgs, the `A2A_SECRET` env var.
+- [A2A Protocol](/docs/a2a-protocol) — the signed-JWT, verify-at-the-boundary trust model this reuses.
+- [External Agents](/docs/external-agents) — the same `A2A_SECRET`-signed identity pattern applied to agent connections and deep links.
+- [Dispatch](/docs/dispatch) — the workspace identity authority and routing hub.
+- [Security & Data Scoping](/docs/security) — additive-only data writes and per-account scoping.

package/docs/content/external-agents.md

@@ -1,56 +1,90 @@
 ---
 title: "External Agents"
-description: "Connect Claude Code, Cowork, and Codex to an agent-native app over MCP — with deep links that drop the user back into the running UI and live artifact round-trip."
+description: "Connect your own Claude Code, Cowork, or Codex to a hosted agent-native app in one command — then round-trip artifacts back into the running UI with deep links."
 ---
 
 # External Agents
 
 An agent-native app is reachable by any external coding agent — Claude Code (desktop & CLI), Claude Cowork, Codex — over [MCP](/docs/mcp-protocol). External agents are great at producing artifacts (a draft, an event, a dashboard) but they live in a terminal or another app. Without a bridge, the user gets a wall of JSON and has to go find the thing.
 
-The external-agent bridge closes the loop: the agent does the work over MCP, then hands the user a single **"Open in <app> →"** 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](/docs/context-awareness)) — there is no second navigation mechanism.
+The external-agent bridge closes the loop. First you connect your own agent to a **hosted** app — one command, no token copying. Then the agent does the work over MCP and hands the user a single **"Open in <app> →"** 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](/docs/context-awareness)) — there is no second navigation mechanism.
 
-## Overview {#overview}
+## Connect in one command {#connect}
 
-- **One-command setup** — `agent-native mcp install --client <c>` writes the client config and provisions a token.
-- **`link` builder** — any action that produces or lists a navigable resource returns a deep link; MCP/A2A surfaces auto-append an "Open in … →" link.
-- **`/_agent-native/open` route** — a pure pointer (view + record ids + filters); the record-focusing write is always scoped to the **browser session**, never the agent's token.
-- **Ingest actions** — GET + `readOnly` + `publicAgent` actions let an external agent pull **live** app state into its own context.
-- **Generic cross-app verbs** — a stable verb set (`list_apps`, `open_app`, `ask_app`, `create_workspace_app`, `list_templates`) so an external agent has a predictable surface without guessing per-app action names.
+The first-party hosted apps live at `mail.agent-native.com`, `calendar.agent-native.com`, `analytics.agent-native.com`, and so on. To wire your own Claude Code (and Codex / Cowork if detected) to one of them:
 
-## Connect an external agent {#connect}
-
-The framework already mounts an HTTP MCP endpoint at `/_agent-native/mcp` (see [MCP Protocol](/docs/mcp-protocol)). Every `defineAction` is exposed as an MCP tool, plus the `ask-agent` meta-tool that runs the full agent loop (the same entry point [A2A](/docs/a2a-protocol) uses). Hosted apps point an external agent at that URL with a bearer token (`ACCESS_TOKEN`, or an `A2A_SECRET` JWT carrying the caller's `sub` + `org_domain` so tool runs stay tenant-scoped).
+```bash
+npx @agent-native/core connect https://mail.agent-native.com
+```
 
-For local Claude Code / Codex / Cowork, one command writes the client config:
+This opens your browser at the app. You are already logged in, so you just click **Authorize** once. The command detects every installed agent client and writes the MCP config for each — no token to copy, no local server to run. Connect every first-party hosted app at once with:
 
 ```bash
-agent-native mcp install --client claude-code|claude-code-cli|codex|cowork \
-  [--app <id>] [--scope user|project]
+npx @agent-native/core connect --all
 ```
 
-It provisions a token (a random `ACCESS_TOKEN` into the workspace `.env` for local dev, or a signed JWT for a detected hosted deployment) and writes an idempotent stdio server entry:
+The connection is **per-user, scoped, and revocable**. The browser session you authorized with is the identity the agent acts as; nothing exposes the deployment's shared secret.
 
-- **claude-code / claude-code-cli** — an `mcpServers` entry in `.mcp.json` (project scope, default) or `~/.claude.json` (`--scope user`).
-- **cowork** — the same Claude Code JSON shape in `~/.cowork/mcp.json`.
-- **codex** — an `[mcp_servers.<name>]` block in `~/.codex/config.toml`.
+### No-CLI alternative {#no-cli}
 
-The entry runs `agent-native mcp serve --app <id>`, which by default is a **thin stdio proxy** to the running local app's `/_agent-native/mcp` — so the live action registry, HMR, and correct deep links stay the single source of truth. Pass `--standalone` to build the registry in-process instead. When `agent-native mcp install` detects a hosted origin (a non-localhost `APP_URL` / `BETTER_AUTH_URL` / `AGENT_NATIVE_MCP_URL` in the workspace `.env`), it writes an `http` client entry pointing at `<origin>/_agent-native/mcp` with a `Bearer` JWT instead of a stdio entry.
+If you'd rather not run a command, open the app in your browser and use its **Connect** affordance (served at `https://<app>/_agent-native/mcp/connect`). While logged in, click **Connect / Authorize**. The page hands you either a one-click deep link that configures a detected agent, or a ready-to-paste `.mcp.json` block:
 
-Companion subcommands:
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "url",
+      "url": "https://mail.agent-native.com/_agent-native/mcp",
+      "headers": { "Authorization": "Bearer <minted-token>" },
+    },
+  },
+}
+```
 
-| Command                                   | What it does                                                        |
-| ----------------------------------------- | ------------------------------------------------------------------- |
-| `agent-native mcp serve [--app <id>]`     | Run the MCP stdio transport (what client configs spawn).            |
-| `agent-native mcp install --client <c>`   | Provision a token + write the client's MCP config (idempotent).     |
-| `agent-native mcp uninstall --client <c>` | Remove the named MCP entry from a client's config (idempotent).     |
-| `agent-native mcp status`                 | Show resolved MCP URL/port, token state, and per-client entries.    |
-| `agent-native mcp token [--rotate]`       | Print (or rotate) the local `ACCESS_TOKEN` in the workspace `.env`. |
+Restart the agent client after connecting so it picks up the new MCP server.
 
-Restart the client after `install` so it picks up the new MCP server.
+## What you can do once connected {#what-you-can-do}
+
+Once your agent is connected, the app's full action surface is available as MCP tools, plus the `ask-agent` meta-tool that runs the full agent loop (the same entry point [A2A](/docs/a2a-protocol) uses). Ask your 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
+
+Claude Code calls: manage-draft(to: "john@example.com", subject: "Q3 Report", body: "…")
+→ Open draft in Mail → https://mail.agent-native.com/_agent-native/open?app=mail&view=inbox&compose=…
+```
+
+Click that link and Mail opens with the draft restored — focused exactly where you, the logged-in user, are. The agent never had to know your session; it just produced the artifact.
+
+### Generic cross-app verbs {#cross-app}
+
+On top of the per-action tools the MCP server exposes a stable verb set, so an external agent has a predictable surface without guessing per-app action names:
+
+| Tool                                       | Side effects | Returns                                                                              |
+| ------------------------------------------ | ------------ | ------------------------------------------------------------------------------------ |
+| `list_apps`                                | none         | workspace apps + their URLs / running state                                          |
+| `open_app({ app, view, params? })`         | none         | a `buildDeepLink` URL (surfaces as an "Open …" link)                                 |
+| `ask_app({ app, message })`                | agent loop   | routes a natural-language task to that app's in-app agent (delegates to `ask-agent`) |
+| `create_workspace_app({ name, template })` | scaffolds    | a new app booted via the workspace path, plus its running URL + deep link            |
+| `list_templates`                           | none         | the allow-listed templates only                                                      |
+
+`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`.
+
+### Per-app tour {#tour}
+
+Every allow-listed template that produces or lists a navigable resource ships a `link` builder, and the ingest-heavy ones ship a GET + `publicAgent` action so a connected agent can pull live state:
+
+- **Mail** — `manage-draft` returns a `compose`-encoded deep link; clicking it opens the inbox with the draft restored into a `compose-<id>`. `list-emails` / `search-emails` point at a filtered inbox view.
+- **Calendar** — `create-event` returns `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })`; the click lands on the calendar with that event focused on its date.
+- **Analytics** — `update-dashboard` / `save-analysis` return `buildDeepLink({ app: "analytics", view: "adhoc", params: { dashboardId } })`; the agent builds a dashboard over MCP and hands back "Open dashboard in Analytics".
+- **Design** — `get-design-snapshot` is the GET + `publicAgent` ingest action: it returns the **live** Yjs file contents plus the resolved tweak values so the agent continues from the tuned design, not the original tokens. `apply-tweaks` round-trips back with an "Open design" editor link.
+- **Content** — `pull-document` is the GET + `publicAgent` ingest action: it flushes any open live collaborative session to SQL first so the external agent ingests exactly what the user sees, then surfaces a deep link to the document.
+- **Brain** — `ask-brain` / `search-everything` return a cited answer plus a deep link to the underlying knowledge/capture, so a terminal agent's lookup links straight back into the source in the running app.
 
-## The `link` builder {#link-builder}
+## Authoring: the `link` builder {#link-builder}
 
-`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 }`. `tools/list` adds `annotations["agent-native/producesOpenLink"]` and a description suffix so the external agent knows the tool yields an openable link and should surface it.
+This section is for template authors. `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 }`. `tools/list` adds `annotations["agent-native/producesOpenLink"]` and a description suffix so the external agent knows the tool yields an openable link and should surface it.
 
 Build the URL with `buildDeepLink(...)` — it is the single source of truth for the open-route format. Never hand-format the `/_agent-native/open` URL.
 
@@ -91,7 +125,7 @@ The `link` builder is **pure and synchronous — no I/O, no awaits**. It runs be
 
 `buildDeepLink({ app, view, params?, to?, compose? })` 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) and a desktop `agentnative://open?…` URL (`toDesktopOpenUrl`); the markdown link uses the desktop URL when the client signals `target: "desktop"`.
 
-## The `/_agent-native/open` route {#open-route}
+### The `/_agent-native/open` route {#open-route}
 
 When the user clicks the link in any browser or inline webview, `GET /_agent-native/open` (`createOpenRouteHandler`, mounted by the core routes plugin):
 
@@ -102,11 +136,11 @@ When the user clicks the link in any browser or inline webview, `GET /_agent-nat
 
 Cross-origin, scheme-relative `//host`, and control-char redirects are rejected (open-redirect guard). The route can be disabled per app via `disableOpenRoute`.
 
-### The browser-session identity rule {#identity-rule}
+#### The browser-session identity rule {#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. So an agent authenticated as one identity can hand a user a link, and when that user clicks it the record opens where _the user_ is logged in. This is what makes the deep link safe to surface in a terminal or chat transcript. See [Context Awareness](/docs/context-awareness) for the `navigate` / `application_state` contract this bridges to.
 
-## Ingest actions {#ingest}
+### Ingest actions {#ingest}
 
 An action an external agent reads to pull live app state into its own context must be:
 
@@ -125,43 +159,86 @@ export default defineAction({
 
 `GET` + `readOnly` keeps the action side-effect-free and out of the screen-refresh poll. `publicAgent` is the **explicit opt-in** — a public web route never implies public MCP/A2A exposure; see [Actions](/docs/actions). Design/content ingest actions MUST read **live** state (the Yjs collaborative document, not the stale DB snapshot column) so the external agent sees what the user actually has on screen. Content's `pull-document` flushes any open live collab session to SQL first; design's `get-design-snapshot` returns the live Yjs file contents plus the user's resolved tweak values.
 
-## Generic cross-app verbs + scaffolding {#cross-app}
+## Advanced: local development & manual setup {#advanced}
 
-On top of the per-action tools the MCP server exposes a stable verb set so an external agent has a predictable surface without guessing per-app action names:
+The hosted `connect` flow above is the recommended path. The options below are for local development and hand-rolled setups.
 
-| Tool                                       | Side effects | Returns                                                                              |
-| ------------------------------------------ | ------------ | ------------------------------------------------------------------------------------ |
-| `list_apps`                                | none         | workspace apps + their dev URLs / running state                                      |
-| `open_app({ app, view, params? })`         | none         | a `buildDeepLink` URL (surfaces as an "Open …" link)                                 |
-| `ask_app({ app, message })`                | agent loop   | routes a natural-language task to that app's in-app agent (delegates to `ask-agent`) |
-| `create_workspace_app({ name, template })` | scaffolds    | a new app booted via the workspace path, plus its running URL + deep link            |
-| `list_templates`                           | none         | the allow-listed templates only                                                      |
+### Local development {#local-dev}
 
-`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`.
+Run your app locally (`pnpm dev` / `agent-native dev`), then point a local agent at it with one command:
 
-## Per-app tour {#tour}
+```bash
+agent-native mcp install --client claude-code|claude-code-cli|codex|cowork \
+  [--app <id>] [--scope user|project]
+```
 
-Every allow-listed template that produces or lists a navigable resource ships a `link` builder, and the ingest-heavy ones ship a GET + `publicAgent` action:
+It provisions a token (a random `ACCESS_TOKEN` into the workspace `.env` for local dev, or a signed JWT if it detects a hosted origin) and writes an idempotent stdio server entry:
 
-- **Mail** — `manage-draft` returns a `compose`-encoded deep link; clicking it opens the inbox with the draft restored into a `compose-<id>`. `list-emails` / `search-emails` point at a filtered inbox view.
-- **Calendar** — `create-event` returns `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })`; the click lands on the calendar with that event focused on its date.
-- **Analytics** — `update-dashboard` / `save-analysis` return `buildDeepLink({ app: "analytics", view: "adhoc", params: { dashboardId } })`; the agent builds a dashboard over MCP and hands back "Open dashboard in Analytics".
-- **Design** — `get-design-snapshot` is the GET + `publicAgent` ingest action: it returns the **live** Yjs file contents plus the resolved tweak values so the agent continues from the tuned design, not the original tokens. `apply-tweaks` round-trips back with an "Open design" editor link.
-- **Content** — `pull-document` is the GET + `publicAgent` ingest action: it flushes any open live collaborative session to SQL first so the external agent ingests exactly what the user sees, then surfaces a deep link to the document.
-- **Brain** — `ask-brain` / `search-everything` return a cited answer plus a deep link to the underlying knowledge/capture, so a terminal agent's lookup links straight back into the source in the running app.
+- **claude-code / claude-code-cli** — an `mcpServers` entry in `.mcp.json` (project scope, default) or `~/.claude.json` (`--scope user`).
+- **cowork** — the same Claude Code JSON shape in `~/.cowork/mcp.json`.
+- **codex** — an `[mcp_servers.<name>]` block in `~/.codex/config.toml`.
+
+The entry runs `agent-native mcp serve --app <id>`, which by default is a **thin stdio proxy** to the running local app's `/_agent-native/mcp` — so the live action registry, HMR, and correct deep links stay the single source of truth. Pass `--standalone` to build the registry in-process instead. When `agent-native mcp install` detects a hosted origin (a non-localhost `APP_URL` / `BETTER_AUTH_URL` / `AGENT_NATIVE_MCP_URL` in the workspace `.env`), it writes an `http` client entry pointing at `<origin>/_agent-native/mcp` with a `Bearer` JWT instead of a stdio entry.
+
+Companion subcommands:
+
+| Command                                   | What it does                                                        |
+| ----------------------------------------- | ------------------------------------------------------------------- |
+| `agent-native mcp serve [--app <id>]`     | Run the MCP stdio transport (what client configs spawn).            |
+| `agent-native mcp install --client <c>`   | Provision a token + write the client's MCP config (idempotent).     |
+| `agent-native mcp uninstall --client <c>` | Remove the named MCP entry from a client's config (idempotent).     |
+| `agent-native mcp status`                 | Show resolved MCP URL/port, token state, and per-client entries.    |
+| `agent-native mcp token [--rotate]`       | Print (or rotate) the local `ACCESS_TOKEN` in the workspace `.env`. |
+
+Restart the client after `install` so it picks up the new MCP server.
+
+### Manual `.mcp.json` HTTP entry {#manual-entry}
+
+You can also write the MCP client config by hand against any deployed endpoint with a token you supply yourself (an `ACCESS_TOKEN`, or an `A2A_SECRET`-signed JWT carrying the caller's `sub` + `org_domain` so tool runs stay tenant-scoped):
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "url",
+      "url": "https://analytics.agent-native.com/_agent-native/mcp",
+      "headers": { "Authorization": "Bearer <ACCESS_TOKEN-or-JWT>" },
+    },
+  },
+}
+```
+
+This is the unmanaged equivalent of what `connect` writes for you. See [MCP Protocol](/docs/mcp-protocol) for the full auth env-var matrix.
+
+### Dev vs production tool surface {#dev-vs-prod}
+
+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` — the per-app ingest actions (`requiresAuth: true`) and mutating actions (no `publicAgent`) are filtered out (`filterPublicAgentActions`). The full per-app surface appears when the request is authenticated as a real caller: a deployed / `AGENT_MODE=production` app, or a local app reached through `connect` / `agent-native mcp install` (which provisions a token so the caller has an identity). So if `tools/list` looks sparse, you are hitting an unauthenticated dev endpoint — connect (or present a token) rather than assuming the action is missing.
+
+## How it works & security {#how-it-works}
+
+The hosted `connect` flow never copies the deployment's shared secret. Instead:
+
+- A logged-in browser session mints a **per-user, scoped, revocable** token — an `A2A_SECRET`-signed JWT carrying the caller's `sub` + `org_domain` and a unique `jti`, so every tool run stays tenant-scoped via `runWithRequestContext`.
+- The existing `/_agent-native/mcp` endpoint accepts that token like any other bearer (see [MCP Protocol](/docs/mcp-protocol)) — no new endpoint, no new transport.
+- The same Connect page lists every token you've minted and lets you **revoke** any of them by `jti`. Treat them like personal access tokens: one per agent client, revoke when a machine is decommissioned.
+- The deep link the agent hands back carries no privileged state. The record-focusing `navigate` write is always scoped to the **browser** session, never the agent's token — so a link is safe to paste into a terminal or chat transcript.
 
 ## Do / Don't {#do-dont}
 
 **Do**
 
+- Connect your own agent to a hosted app with `npx @agent-native/core connect <url>` (or `--all`) — it's the frictionless path.
 - Add a `link` builder to any action that produces or lists a navigable resource (draft, event, dashboard, document).
 - Build the URL with `buildDeepLink(...)` — the single source of truth for the open-route format.
 - Keep `link` pure and synchronous; return `null` when there's nothing to open.
 - Make external-agent ingest actions GET + `readOnly` + `publicAgent`, and read live (Yjs) state, not the stale DB column.
 - 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.
+- Revoke a minted connect token by `jti` when an agent client is decommissioned.
 
 **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.
 - Hand-format the `/_agent-native/open` URL — always go through `buildDeepLink`.
 - Do I/O, awaits, DB reads, or app-state reads inside a `link` builder.
 - Scope the `navigate` write to the agent token, or pass privileged state through the deep link — it's a pure pointer.
@@ -175,3 +252,5 @@ Every allow-listed template that produces or lists a navigable resource ships a
 - [A2A Protocol](/docs/a2a-protocol) — the `ask-agent` meta-tool and JSON-RPC peer calls.
 - [Actions](/docs/actions) — defining actions, `publicAgent`, GET / `readOnly`.
 - [Context Awareness](/docs/context-awareness) — the `navigate` / `application_state` contract the open route bridges to.
+  </content>
+  </invoke>

package/docs/content/migration-workbench.md

@@ -209,7 +209,7 @@ In Agent-Native Code, Desktop, or the internal run surface, connect providers th
 
 ## Agent-Native Code
 
-Agent-Native Desktop includes a **Agent-Native Code** hub for long-running coding-agent sessions. It is the general Code app/surface in Desktop, and it pairs with the `agent-native code` shell as the primary CLI/Desktop coding experience. A bare prompt is the generic coding session, and `/migrate` is one specialized capability there: the hub shows recent and active runs, opens a transcript-first session view, renders tool events and artifacts, sends follow-up prompts, stops tracked runners, opens a terminal in the run workspace, and handles links like:
+Agent-Native Desktop includes a **Agent-Native Code** hub for long-running coding-agent sessions. It is the general Code app/surface in Desktop, and it pairs with the `agent-native code` shell as the primary CLI/Desktop coding experience. A bare prompt is the generic coding session, and `/migrate` is one specialized capability there: the hub shows recent and active runs, opens a transcript-first session view with compact tool summaries and artifacts, sends follow-up prompts, stops tracked runners, opens a terminal in the run workspace, and handles links like:
 
 ```text
 agentnative://open?goal=migrate&run=<runId>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",
@@ -78,6 +78,7 @@
     "./usage": "./dist/usage/store.js",
     "./connections": "./dist/connections/index.js",
     "./code-agents": "./dist/code-agents/index.js",
+    "./code-agents/transcript-normalizer": "./dist/code-agents/transcript-normalizer.js",
     "./workspace-connections": "./dist/workspace-connections/index.js",
     "./notifications": "./dist/notifications/index.js",
     "./client/notifications": "./dist/client/notifications/index.js",