@agent-native/core 0.48.1 → 0.48.3

package/dist/templates/workspace-core/.agents/skills/authentication/SKILL.md

@@ -119,7 +119,42 @@ window.location.href =
 
 After successful sign-in (token / email-password / Google OAuth), the framework 302s to `return`. The path is validated as same-origin via the URL parser — open-redirect / header-injection inputs fall back to `/`.
 
-Bookmarked private paths already work without any plumbing — the framework's login page is served at the requested URL, and post-login reload returns the user there.
+Bookmarked private paths already work _when the request reaches the server_ — the auth guard serves the login page at the requested URL and post-login reload returns the user there.
+
+## Gating the App Shell (avoid the logged-out infinite spinner)
+
+The server auth guard only protects requests that actually reach the Nitro
+function. A statically-served / CDN-cached SPA shell, or a client-side (React
+Router) navigation made after the session expired, never re-hits the guard — so
+the app boots with **no session**, every data query 401s, and the UI sticks on
+its loading state forever. Server-side protection alone is not enough; gate on
+the client too.
+
+For a fully private app (every page requires auth, like mail), wrap the routed
+shell with the framework's `RequireSession`. It resolves the session on the
+client and redirects signed-out visitors to `/_agent-native/sign-in?return=…`
+instead of spinning:
+
+```tsx
+import { AppProviders, RequireSession } from "@agent-native/core/client";
+
+<AppProviders queryClient={queryClient}>
+  <RequireSession bypass={isMcpEmbedSurface()}>
+    <AppLayout>
+      <Outlet />
+    </AppLayout>
+  </RequireSession>
+</AppProviders>;
+```
+
+- Place it **inside** `AppProviders` (so the loading fallback is themed) and
+  **around** the layout/outlet — also around any always-mounted effects (poll,
+  automation trigger) so they don't fire 401s for logged-out visitors.
+- Pass `bypass` for surfaces that authenticate by another mechanism (embed /
+  popout iframes carrying their own token) so they are never bounced to sign-in.
+- Apps with public/anonymous routes (share pages) must **not** wrap the whole
+  app — gate only the private subtree, or use the `redirect={false}` +
+  `signedOut` props to render an inline call-to-action instead of redirecting.
 
 ## Related Skills
 

package/docs/content/agent-web-surfaces.md

@@ -15,7 +15,7 @@ The docs site is the reference implementation. Today it ships:
 - Markdown mirrors such as `/docs/getting-started.md`.
 - `Accept: text/markdown` responses for public docs pages after a production build.
 - JSON-LD for base organization, website, and page metadata.
-- An audit CLI (`agent-native audit-agent-web`) that checks all of the above.
+- An audit CLI (`npx @agent-native/core@latest audit-agent-web`) that checks all of the above.
 
 Setting `publicMcp: true` additionally exposes opted-in actions as a public MCP endpoint, allowing external agents to call them directly (see [MCP Protocol](/docs/mcp-protocol)).
 
@@ -128,7 +128,7 @@ Vite apps can use `createAgentWebVitePlugin` from `@agent-native/core/vite` to w
 Use the CLI audit against a deployed site or a local production server:
 
 ```bash
-agent-native audit-agent-web --url https://www.agent-native.com
+npx @agent-native/core@latest audit-agent-web --url https://www.agent-native.com
 ```
 
 The audit checks for:

package/docs/content/authentication.md

@@ -130,7 +130,7 @@ Unauthenticated MCP requests return a `WWW-Authenticate` challenge pointing at `
 
 Access tokens are signed with `A2A_SECRET` when set, otherwise `BETTER_AUTH_SECRET`. They carry the signed user/org identity and the `mcp:read`, `mcp:write`, and/or `mcp:apps` scopes, and are audience-bound to the exact MCP resource URL. Refresh tokens are stored only as hashes and rotate on every refresh. Tool calls and MCP Apps resource reads run inside the same request context as the signed-in user; the embedded MCP App iframe never receives raw OAuth tokens.
 
-`agent-native connect <url> --client claude-code` writes the URL-only MCP entry for this standard flow. For clients that cannot perform remote MCP OAuth, use the Connect page or `agent-native connect --token <token>` fallback to write an explicit bearer-token entry.
+`npx @agent-native/core@latest connect <url> --client claude-code` writes the URL-only MCP entry for this standard flow. For clients that cannot perform remote MCP OAuth, use the Connect page or `npx @agent-native/core@latest connect --token <token>` fallback to write an explicit bearer-token entry.
 
 ## Bring Your Own Auth {#byoa}
 

package/docs/content/cloneable-saas.md

@@ -87,13 +87,13 @@ Not ready to scaffold? You can add agent-native superpowers to a coding agent yo
 If you're scaffolding now, the CLI command is:
 
 ```bash
-npx @agent-native/core create my-platform
+npx @agent-native/core@latest create my-platform
 ```
 
 You'll get a multi-select picker. Pick one app (standalone) or several (workspace — apps share auth, brand, agent config, and database). Each picked template is scaffolded into `apps/<name>/` with every file you need.
 
 Fill in `.env` (mostly `ANTHROPIC_API_KEY` and `DATABASE_URL`), `pnpm install`, `pnpm dev`, and it works. No "TODO: implement login," no placeholder routes.
 
-Deploy targets: any Nitro-compatible host (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) and any Drizzle-compatible SQL database (SQLite, Postgres, Turso, D1, Supabase, Neon). For workspaces, `agent-native deploy` builds every app at once and ships them behind a single origin. See [Deployment](/docs/deployment).
+Deploy targets: any Nitro-compatible host (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) and any Drizzle-compatible SQL database (SQLite, Postgres, Turso, D1, Supabase, Neon). For workspaces, `npx @agent-native/core@latest deploy` builds every app at once and ships them behind a single origin. See [Deployment](/docs/deployment).
 
 To author and publish your own template, see [Creating Templates](/docs/creating-templates).

package/docs/content/code-agents-ui.md

@@ -5,11 +5,11 @@ description: "Build and customize Agent-Native Code surfaces with the shared UI
 
 # Agent-Native Code UI
 
-Agent-Native Code is the Agent-Native coding surface: a local Claude Code/Codex-style workspace for coding sessions, slash commands, migrations, audits, transcripts, run controls, and follow-ups. A bare `npx @agent-native/core@latest` or installed `agent-native` command opens this workspace; `agent-native code` is the explicit subcommand for the same experience.
+Agent-Native Code is the Agent-Native coding surface: a local Claude Code/Codex-style workspace for coding sessions, slash commands, migrations, audits, transcripts, run controls, and follow-ups. A bare `npx @agent-native/core@latest` command opens this workspace; `npx @agent-native/core@latest code` is the explicit subcommand for the same experience.
 
 There are three layers:
 
-- **CLI**: `npx @agent-native/core@latest`, `agent-native`, and `agent-native code` start, resume, inspect, and stop runs.
+- **CLI**: `npx @agent-native/core@latest` and `npx @agent-native/core@latest code` start, resume, inspect, and stop runs.
 - **Desktop**: the left-sidebar Code tab adds native terminal launch, app webviews, and desktop deep links while using the same run model.
 - **Shared UI**: `@agent-native/code-agents-ui` renders the reusable React surface.
 
@@ -95,19 +95,18 @@ The top-level CLI behaves like Claude Code or Codex:
 
 ```bash
 npx @agent-native/core@latest
-agent-native
-agent-native "fix the failing auth tests"
-agent-native code
+npx @agent-native/core@latest "fix the failing auth tests"
+npx @agent-native/core@latest code
 ```
 
-Use `agent-native code` when you want the explicit namespace. Built-in slash
+Use `npx @agent-native/core@latest code` when you want the explicit namespace. Built-in slash
 goals and project commands can run inside the interactive workspace or directly
 from the shell:
 
 ```bash
-agent-native code /migrate ./legacy-app --emit ./migration-dossier
-agent-native code /audit --url https://example.com
-agent-native code /release-check
+npx @agent-native/core@latest code /migrate ./legacy-app --emit ./migration-dossier
+npx @agent-native/core@latest code /audit --url https://example.com
+npx @agent-native/core@latest code /release-check
 ```
 
 Here `/migrate` and `/audit` are built-in goals (the built-in goals are
@@ -118,13 +117,13 @@ commands come from `.agents/commands/*.md`; project skills come from
 records that the Desktop Code tab and shared UI display:
 
 ```bash
-agent-native code list
-agent-native code status --last
-agent-native code attach --last
-agent-native code logs --last
-agent-native code resume --last
-agent-native code stop --last
-agent-native code ui
+npx @agent-native/core@latest code list
+npx @agent-native/core@latest code status --last
+npx @agent-native/core@latest code attach --last
+npx @agent-native/core@latest code logs --last
+npx @agent-native/core@latest code resume --last
+npx @agent-native/core@latest code stop --last
+npx @agent-native/core@latest code ui
 ```
 
 `resume` appends context and continues a run, `status` reports the latest run
@@ -267,7 +266,7 @@ Project skills live in:
 .agents/skills/*/SKILL.md
 ```
 
-When the host implements `listCodePacks`, the shared UI shows project commands and skills in the rail. Command rows insert `/<command>`, and skill rows insert a focused “Use the <skill> skill…” prompt so the rail stays actionable. The built-in slash goals `/migrate` and `/audit` stay reserved for the global Agent-Native Code controls, as do run-control names such as `status` and `resume` — those are subcommands invoked without a slash (`agent-native code status`, `agent-native code resume`), not slash goals.
+When the host implements `listCodePacks`, the shared UI shows project commands and skills in the rail. Command rows insert `/<command>`, and skill rows insert a focused “Use the <skill> skill…” prompt so the rail stays actionable. The built-in slash goals `/migrate` and `/audit` stay reserved for the global Agent-Native Code controls, as do run-control names such as `status` and `resume` — those are subcommands invoked without a slash (`npx @agent-native/core@latest code status`, `npx @agent-native/core@latest code resume`), not slash goals.
 
 Do not create a separate slash-command registry for a new Code host. Project
 commands and skills are discovered from `.agents/commands/*.md` and

package/docs/content/creating-templates.md

@@ -22,13 +22,13 @@ A good template:
 Use the CLI-only Starter scaffold when you want a blank app with the framework wiring already in place:
 
 ```bash
-pnpm dlx @agent-native/core create my-template --template starter --standalone
+npx @agent-native/core@latest create my-template --template starter --standalone
 ```
 
 For a workspace with multiple apps, run the picker and include Starter with any domain templates you want:
 
 ```bash
-pnpm dlx @agent-native/core create my-platform
+npx @agent-native/core@latest create my-platform
 ```
 
 Starter gives you auth, the agent sidebar, SQL-backed resources, tools, application state, actions, and polling sync. You add the domain model and product UI.
@@ -388,7 +388,7 @@ Before sharing:
 Community templates can be created from a GitHub repo:
 
 ```bash
-pnpm dlx @agent-native/core create my-app --template github:user/repo
+npx @agent-native/core@latest create my-app --template github:user/repo
 ```
 
 ## Contributing to the framework monorepo {#contributing}

package/docs/content/deployment.md

@@ -20,7 +20,7 @@ Use `DATABASE_AUTH_TOKEN` only when your database provider requires a separate t
 If your project is a [workspace](/docs/multi-app-workspace), you can ship every app in it to a single origin with one command:
 
 ```bash
-agent-native deploy
+npx @agent-native/core@latest deploy
 # https://your-agents.com/mail/*       → apps/mail
 # https://your-agents.com/calendar/*   → apps/calendar
 # https://your-agents.com/forms/*      → apps/forms
@@ -42,26 +42,26 @@ wrangler pages deploy dist
 For Netlify unified deploys, use the Netlify preset:
 
 ```bash
-agent-native deploy --preset netlify
+npx @agent-native/core@latest deploy --preset netlify
 ```
 
 For Vercel unified deploys, use the Vercel preset:
 
 ```bash
-agent-native deploy --preset vercel
+npx @agent-native/core@latest deploy --preset vercel
 ```
 
-When configuring a provider build command, use the same command with `--build-only`. Vercel should run `pnpm exec agent-native deploy --preset vercel --build-only`; the command writes `.vercel/output` directly, so no `vercel.json` is required for workspace routing.
+When configuring a provider build command, use the same command with `--build-only`. Vercel should run `npx @agent-native/core@latest deploy --preset vercel --build-only`; the command writes `.vercel/output` directly, so no `vercel.json` is required for workspace routing.
 
 Hosted workspace builds require `A2A_SECRET` in the deploy provider environment.
 This makes Slack, inbound webhooks, and cross-app A2A resume work through signed
 background processors. Local `--build-only` artifact checks still run without it.
 
-Per-app independent deploy is still supported — just `cd apps/<name> && agent-native build` like a standalone scaffold.
+Per-app independent deploy is still supported — just `cd apps/<name> && npx @agent-native/core@latest build` like a standalone scaffold.
 
 ## How It Works {#how-it-works}
 
-When you run `agent-native build`, Nitro builds both the client SPA and the server API into `.output/`:
+When you run `npx @agent-native/core@latest build`, Nitro builds both the client SPA and the server API into `.output/`:
 
 ```text
 .output/
@@ -90,7 +90,7 @@ export default defineConfig({
 Or use the `NITRO_PRESET` environment variable at build time:
 
 ```bash
-NITRO_PRESET=netlify agent-native build
+NITRO_PRESET=netlify npx @agent-native/core@latest build
 ```
 
 ## Node.js (Default) {#nodejs}
@@ -98,7 +98,7 @@ NITRO_PRESET=netlify agent-native build
 The default preset. Build and run:
 
 ```bash
-agent-native build
+npx @agent-native/core@latest build
 node .output/server/index.mjs
 ```
 
@@ -147,13 +147,13 @@ vercel deploy
 For a workspace, build every app into one Vercel Build Output API bundle:
 
 ```bash
-agent-native deploy --preset vercel
+npx @agent-native/core@latest deploy --preset vercel
 ```
 
 For Vercel Git deployments, set the build command to:
 
 ```bash
-pnpm exec agent-native deploy --preset vercel --build-only
+npx @agent-native/core@latest deploy --preset vercel --build-only
 ```
 
 The workspace build copies each app's Nitro `vercel` output into the root `.vercel/output`, gives each function its own mount-path environment, and writes the route config that serves apps at `/<app-id>`.
@@ -174,7 +174,7 @@ export default defineConfig({
 For a workspace, deploy every app from one Netlify site by running:
 
 ```bash
-agent-native deploy --preset netlify
+npx @agent-native/core@latest deploy --preset netlify
 ```
 
 The workspace build writes static assets under `dist/_workspace_static/` and routes each app to its own Netlify function without forced asset redirects, so files like `/mail/assets/...` are served statically before the server function handles app routes.
@@ -210,13 +210,13 @@ export default defineConfig({
 
 ### Build / Runtime {#env-runtime}
 
-| Variable              | Description                                                                                                                          |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `PORT`                | Server port (Node.js only)                                                                                                           |
-| `NITRO_PRESET`        | Override build preset at build time                                                                                                  |
-| `APP_BASE_PATH`       | Mount the app under a prefix (e.g. `/mail`). Set automatically by `agent-native deploy`; leave unset for standalone.                 |
-| `DATABASE_URL`        | Persistent SQL connection string. Required in production. See [Database](/docs/database#production) for adapter and dialect details. |
-| `DATABASE_AUTH_TOKEN` | Auth token for providers that require a separate token, such as Turso/libSQL.                                                        |
+| Variable              | Description                                                                                                                           |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                | Server port (Node.js only)                                                                                                            |
+| `NITRO_PRESET`        | Override build preset at build time                                                                                                   |
+| `APP_BASE_PATH`       | Mount the app under a prefix (e.g. `/mail`). Set automatically by `npx @agent-native/core@latest deploy`; leave unset for standalone. |
+| `DATABASE_URL`        | Persistent SQL connection string. Required in production. See [Database](/docs/database#production) for adapter and dialect details.  |
+| `DATABASE_AUTH_TOKEN` | Auth token for providers that require a separate token, such as Turso/libSQL.                                                         |
 
 ### Required in Production {#env-required-prod}
 

package/docs/content/dispatch.md

@@ -115,9 +115,9 @@ The whole pipeline is built to survive on every serverless host (Netlify, Vercel
 
 Three short steps:
 
-1. **Scaffold a workspace that includes Dispatch.** Run `pnpm dlx @agent-native/core create my-company-platform` and pick `dispatch` alongside whatever domain templates you want. Dispatch lives at `apps/dispatch` and the rest of the apps sit beside it. See [Multi-App Workspace](/docs/multi-app-workspace).
+1. **Scaffold a workspace that includes Dispatch.** Run `npx @agent-native/core@latest create my-company-platform` and pick `dispatch` alongside whatever domain templates you want. Dispatch lives at `apps/dispatch` and the rest of the apps sit beside it. See [Multi-App Workspace](/docs/multi-app-workspace).
 2. **Connect messaging.** Open **Settings → Messaging** in Dispatch and click connect for Slack, Email, Telegram, or WhatsApp. The form fields match the env vars in the [Messaging](/docs/messaging) doc — refer there for what each platform needs.
-3. **Add other apps.** Run `npx @agent-native/core add-app` from the workspace root for each domain app. They auto-appear as A2A peers in Dispatch's `list-workspace-apps` — no manual registration, no agent-card editing. Dispatch will start delegating to them as soon as their agent cards are reachable.
+3. **Add other apps.** Run `npx @agent-native/core@latest add-app` from the workspace root for each domain app. They auto-appear as A2A peers in Dispatch's `list-workspace-apps` — no manual registration, no agent-card editing. Dispatch will start delegating to them as soon as their agent cards are reachable.
 
 Then add credentials to the vault and (optionally) author global workspace resources under **Resources**. Vault keys can still be synced or granted depending on access mode; All-app workspace resources are inherited automatically. If you need per-app secret isolation, switch the vault access setting to manual before granting individual apps.
 

package/docs/content/external-agents.md

@@ -85,16 +85,10 @@ In hosts that support MCP Apps, Analytics can render real dashboard and analysis
 
 Use this flow for local agent clients on your machine — Claude Code, Claude Code CLI, Codex, and Claude Cowork. (Cursor uses the paste-URL flow above; it does not need this CLI path.)
 
-If you have the Agent-Native CLI installed, run:
+Run the connect command through npm:
 
 ```bash
-agent-native connect https://dispatch.agent-native.com
-```
-
-Or run the same command through npm without installing anything globally:
-
-```bash
-npx @agent-native/core connect https://dispatch.agent-native.com
+npx @agent-native/core@latest connect https://dispatch.agent-native.com
 ```
 
 The command asks which local agent clients should receive MCP config. All clients are preselected the first time; after you choose, the selection is saved to `~/.agent-native/connect.json` so the next run can reuse it with Enter, or you can edit the checked items.
@@ -105,7 +99,7 @@ Keep the `connect` command running until the browser approval completes. If the
 waiting process is stopped early, the approval can succeed in the browser but
 the local client config will not receive the token.
 
-If you previously connected Claude Code through the old bearer-token flow, just run the same `agent-native connect ... --client claude-code` command again. The CLI replaces the legacy `Authorization` headers with the URL-only OAuth entry and tells you to re-authenticate from `/mcp`.
+If you previously connected Claude Code through the old bearer-token flow, just run the same `npx @agent-native/core@latest connect ... --client claude-code` command again. The CLI replaces the legacy `Authorization` headers with the URL-only OAuth entry and tells you to re-authenticate from `/mcp`.
 
 | Local client                  | Config written by `connect`                             | Auth flow                                       |
 | ----------------------------- | ------------------------------------------------------- | ----------------------------------------------- |
@@ -136,8 +130,7 @@ npx skills add BuilderIO/agent-native --skill assets
 ```
 
 The raw `skills` CLI installs `SKILL.md` files only; local MCP clients still
-need a connector such as `npx @agent-native/core@latest connect
-https://assets.agent-native.com`.
+need a connector such as `npx @agent-native/core@latest connect https://assets.agent-native.com`.
 
 | Skill    | Alias              | For                    |
 | -------- | ------------------ | ---------------------- |
@@ -149,7 +142,7 @@ When you truly need an isolated app instead of Dispatch's workspace gateway,
 run the same command with that app's host:
 
 ```bash
-npx @agent-native/core connect https://mail.agent-native.com
+npx @agent-native/core@latest connect https://mail.agent-native.com
 ```
 
 `connect --all` still exists for legacy per-app client setups, but new
@@ -187,7 +180,7 @@ claude mcp add --transport http agent-native \
   https://dispatch.agent-native.com/_agent-native/mcp
 ```
 
-This is the same URL-only entry that `agent-native connect https://dispatch.agent-native.com --client claude-code` writes for you. Then run `/mcp` in Claude Code and choose **Authenticate**. The client discovers auth from the MCP server's `401 WWW-Authenticate` challenge, fetches `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, dynamically registers a public OAuth client, opens the app's authorization page, and stores the resulting token securely. ChatGPT developer-mode connectors use the same server URL:
+This is the same URL-only entry that `npx @agent-native/core@latest connect https://dispatch.agent-native.com --client claude-code` writes for you. Then run `/mcp` in Claude Code and choose **Authenticate**. The client discovers auth from the MCP server's `401 WWW-Authenticate` challenge, fetches `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, dynamically registers a public OAuth client, opens the app's authorization page, and stores the resulting token securely. ChatGPT developer-mode connectors use the same server URL:
 
 ```text
 https://dispatch.agent-native.com/_agent-native/mcp
@@ -203,7 +196,7 @@ Current scopes are:
 | `mcp:write` | mutating actions and the `ask-agent` meta-tool                            |
 | `mcp:apps`  | MCP Apps resource listing/reading and inline UI rendering where supported |
 
-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.
+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 `npx @agent-native/core@latest 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}
 
@@ -233,7 +226,7 @@ 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
+npx @agent-native/core@latest connect https://plan.agent-native.com --full-catalog
 ```
 
 This embeds a `catalog_scope: "full"` claim in the minted JWT. On subsequent
@@ -453,10 +446,10 @@ The hosted `connect` flow above is the recommended path. The options below are f
 
 ### Local development {#local-dev}
 
-Run your app locally (`pnpm dev` / `agent-native dev`), then point a local agent at it with one command:
+Run your app locally (`pnpm dev` / `npx @agent-native/core@latest dev`), then point a local agent at it with one command:
 
 ```bash
-agent-native mcp install --client claude-code|claude-code-cli|codex|cowork \
+npx @agent-native/core@latest mcp install --client claude-code|claude-code-cli|codex|cowork \
   [--app <id>] [--scope user|project]
 ```
 
@@ -466,17 +459,17 @@ It provisions a token (a random `ACCESS_TOKEN` into the workspace `.env` for loc
 - **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.
+The entry runs `npx @agent-native/core@latest 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 `npx @agent-native/core@latest 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`. |
+| Command                                                    | What it does                                                        |
+| ---------------------------------------------------------- | ------------------------------------------------------------------- |
+| `npx @agent-native/core@latest mcp serve [--app <id>]`     | Run the MCP stdio transport (what client configs spawn).            |
+| `npx @agent-native/core@latest mcp install --client <c>`   | Provision a token + write the client's MCP config (idempotent).     |
+| `npx @agent-native/core@latest mcp uninstall --client <c>` | Remove the named MCP entry from a client's config (idempotent).     |
+| `npx @agent-native/core@latest mcp status`                 | Show resolved MCP URL/port, token state, and per-client entries.    |
+| `npx @agent-native/core@latest 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.
 
@@ -510,7 +503,7 @@ When you already have first-party hosted apps connected and want to test local f
 ```bash
 pnpm dev:lazy -- --apps mail,calendar,analytics
 
-agent-native connect dev --apps mail,calendar,analytics --client codex
+npx @agent-native/core@latest connect dev --apps mail,calendar,analytics --client codex
 ```
 
 `connect dev` rewrites the same stable MCP server names (`agent-native-mail`, `agent-native-calendar`, etc.) to the local dev-lazy gateway, so tool names do not change. It backs up the current production entries in `~/.agent-native/connect-profiles.json` before writing dev entries. The default gateway is `http://127.0.0.1:8080`; use `--gateway <url>` or `--port <n>` if your gateway moved.
@@ -518,7 +511,7 @@ agent-native connect dev --apps mail,calendar,analytics --client codex
 Switch back with:
 
 ```bash
-agent-native connect prod --apps mail,calendar,analytics --client codex
+npx @agent-native/core@latest connect prod --apps mail,calendar,analytics --client codex
 ```
 
 If `connect dev` cannot infer your local owner identity from an existing connected JWT, pass `--owner-email you@example.com`; this keeps local dev tools on the full authenticated MCP surface instead of the sparse unauthenticated dev surface.
@@ -540,7 +533,7 @@ The fallback hosted `connect` flow never copies the deployment's shared secret.
 
 **Do**
 
-- Connect your own agent to Dispatch with `npx @agent-native/core connect https://dispatch.agent-native.com`; use a direct app URL only when you want one isolated app.
+- Connect your own agent to Dispatch with `npx @agent-native/core@latest connect https://dispatch.agent-native.com`; use a direct app URL only when you want one isolated app.
 - 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.

package/docs/content/faq.md

@@ -66,7 +66,7 @@ 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` 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).
+Yes. Run `npx @agent-native/core@latest 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}
 

package/docs/content/frames.md

@@ -122,7 +122,7 @@ The embedded agent panel is part of every app — scaffold a template and it's
 already there:
 
 ```bash
-pnpm dlx @agent-native/core create my-app --template mail --standalone
+npx @agent-native/core@latest create my-app --template mail --standalone
 cd my-app
 pnpm dev
 ```

package/docs/content/getting-started.md

@@ -22,7 +22,7 @@ Not sure which path? If you've never written code, the hosted version is for you
 Three commands and you're up:
 
 ```bash
-npx @agent-native/core create my-platform
+npx @agent-native/core@latest create my-platform
 cd my-platform
 pnpm install && pnpm dev
 ```
@@ -73,14 +73,14 @@ Run `create` from the folder where you want a brand-new workspace:
 
 ```bash
 cd ~/projects
-npx @agent-native/core create my-platform
+npx @agent-native/core@latest create my-platform
 ```
 
 After a workspace exists, run app commands from the workspace root:
 
 ```bash
 cd my-platform
-npx @agent-native/core add-app
+npx @agent-native/core@latest add-app
 pnpm install
 pnpm dev
 ```
@@ -90,7 +90,7 @@ If your terminal is inside `apps/content` or another app folder, the CLI still d
 To make a second app from the same template, give it a new app name:
 
 ```bash
-npx @agent-native/core add-app design-lab --template design
+npx @agent-native/core@latest add-app design-lab --template design
 ```
 
 ## Try it with a skill {#try-with-a-skill}
@@ -136,10 +136,10 @@ Good first moves:
 - **Open Agent-Native Code** — run `npx @agent-native/core@latest` or `npx @agent-native/core@latest code` from the project. A bare command opens the local Claude Code/Codex-like workspace; a bare prompt such as `npx @agent-native/core@latest "rename the app"` starts a Code task directly.
 - **Ask the built-in agent what it sees** — open the agent panel and type "what app am I looking at, and what can you do here?" This verifies the app, UI state, and agent loop are all talking to each other.
 - **Make a tiny customization** — ask your coding tool to rename the app, change the first screen copy, or add one field to a form. It will read `AGENTS.md` for the framework conventions.
-- **Add another app to the same workspace** — use `npx @agent-native/core add-app` from inside the workspace folder. The command starts at `npx`.
-- **Single app instead of a monorepo?** Pass `--standalone` when creating: `npx @agent-native/core create my-app --standalone --template mail`.
+- **Add another app to the same workspace** — use `npx @agent-native/core@latest add-app` from inside the workspace folder. The command starts at `npx`.
+- **Single app instead of a monorepo?** Pass `--standalone` when creating: `npx @agent-native/core@latest create my-app --standalone --template mail`.
 
-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.
+Agent-Native Code understands built-in slash goals such as `/migrate` and `/audit`, plus project commands in `.agents/commands/*.md`. Use `npx @agent-native/core@latest 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.
 
 ## Architecture principles {#architecture-principles}
 

package/docs/content/mcp-apps.md

@@ -63,7 +63,7 @@ The resource shell owns the outer host size. `embedApp({ height })` defaults to
 
 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.
+When testing Claude through ngrok, use a production build (`npx @agent-native/core@latest build` then `npx @agent-native/core@latest 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.
 
 ## Host bridge API {#host-bridge}
 

package/docs/content/mcp-protocol.md

@@ -149,7 +149,7 @@ The MCP endpoint supports standard remote MCP OAuth plus the existing bearer-tok
 | Mode                        | How it works                                                                                                          |
 | --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
 | Standard MCP OAuth          | Client discovers auth from `WWW-Authenticate`, registers, runs PKCE, and sends `Authorization: Bearer <access-token>` |
-| Connect-minted JWT          | `agent-native connect` / the Connect page mints a per-user, revocable JWT                                             |
+| Connect-minted JWT          | `npx @agent-native/core@latest connect` / the Connect page mints a per-user, revocable JWT                            |
 | `ACCESS_TOKEN`              | Static bearer token — client sends `Authorization: Bearer <token>`                                                    |
 | `ACCESS_TOKENS`             | Comma-separated list of valid static bearer tokens                                                                    |
 | `A2A_SECRET`                | JWT-based auth — tokens are verified cryptographically                                                                |
@@ -186,7 +186,7 @@ Access tokens are signed JWTs whose audience is the exact MCP resource URL. The
 | `mcp:write` | mutating actions and `ask-agent`            |
 | `mcp:apps`  | MCP Apps resources (`ui://` HTML resources) |
 
-Refresh tokens are stored only as hashes and are rotated on every refresh. `agent-native connect` writes this URL-only OAuth entry for Claude Code clients by default; keep the Connect page, `agent-native connect --token <token>`, and static bearer config for local stdio proxying, older clients, and emergency/debug flows.
+Refresh tokens are stored only as hashes and are rotated on every refresh. `npx @agent-native/core@latest connect` writes this URL-only OAuth entry for Claude Code clients by default; keep the Connect page, `npx @agent-native/core@latest connect --token <token>`, and static bearer config for local stdio proxying, older clients, and emergency/debug flows.
 
 ## Custom MCP setup {#custom-setup}
 

package/docs/content/migration-workbench.md

@@ -16,7 +16,7 @@ npx @agent-native/core@latest code attach --last
 npx @agent-native/core@latest code /migrate ./my-next-app --out ../migrated-app
 ```
 
-**Agent-Native Code** is the open-source Claude Code/Codex-like workspace for coding work in Agent-Native. `agent-native` or `agent-native code` launches it with no prompt required, and a bare prompt starts a generic coding task directly. `/migrate` is one built-in capability for moving an existing app, URL, or described product into agent-native. It uses the same session store, transcript, and desktop hub as the CLI `code` command, so migration behaves like a goal you can resume, attach to, inspect, and stop rather than a separate one-off product.
+**Agent-Native Code** is the open-source Claude Code/Codex-like workspace for coding work in Agent-Native. `npx @agent-native/core@latest` or `npx @agent-native/core@latest code` launches it with no prompt required, and a bare prompt starts a generic coding task directly. `/migrate` is one built-in capability for moving an existing app, URL, or described product into agent-native. It uses the same session store, transcript, and desktop hub as the CLI `code` command, so migration behaves like a goal you can resume, attach to, inspect, and stop rather than a separate one-off product.
 
 See [Agent-Native Code UI](/docs/code-agents-ui) for the shared CLI run controls (`list`/`attach`/`logs`/`resume`/`status`/`stop`/`ui`) and the file-backed, long-running background-run model that `/migrate` sessions use.
 
@@ -35,7 +35,7 @@ full run-control command set).
 
 ## Code Workspace
 
-`agent-native code` opens the interactive Agent-Native Code shell. Inside the shell, `/migrate` is a slash goal alongside `/audit` and other built-in commands. Projects can also define custom migration variants in `.agents/commands/*.md`. The CLI and Desktop hub share the same run store — start in one and continue in the other using the standard `list`/`attach`/`logs`/`resume`/`approve`/`stop` controls.
+`npx @agent-native/core@latest code` opens the interactive Agent-Native Code shell. Inside the shell, `/migrate` is a slash goal alongside `/audit` and other built-in commands. Projects can also define custom migration variants in `.agents/commands/*.md`. The CLI and Desktop hub share the same run store — start in one and continue in the other using the standard `list`/`attach`/`logs`/`resume`/`approve`/`stop` controls.
 
 See [Agent-Native Code UI](/docs/code-agents-ui) for the full shell, run controls, Plan/Auto modes, slash-goal discovery, and Desktop hub integration.