@agent-native/core 0.48.4 → 0.49.1

package/dist/sharing/schema.d.ts

@@ -31,9 +31,9 @@
  * - `visibility`— coarse default: `'private' | 'org' | 'public'`. Default `'private'`.
  */
 export declare function ownableColumns(): {
-    ownerEmail: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<"owner_email", [string, ...string[]], number | undefined>>>;
-    orgId: import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<"org_id", [string, ...string[]], number | undefined>;
-    visibility: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<"visibility", ["private", "org", "public"], number | undefined>>>;
+    ownerEmail: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<"owner_email", [string, ...string[]], number>>>;
+    orgId: import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<"org_id", [string, ...string[]], number>;
+    visibility: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<"visibility", ["private", "org", "public"], number>>>;
 };
 /**
  * Create a companion shares table for an ownable resource. Call this right
@@ -74,7 +74,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         resourceId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "resource_id";
@@ -93,14 +93,14 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         principalType: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "principal_type";
             tableName: string;
             dataType: "string";
             columnType: "SQLiteText";
-            data: "user" | "org";
+            data: "org" | "user";
             driverParam: string;
             notNull: true;
             hasDefault: false;
@@ -112,7 +112,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         principalId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "principal_id";
@@ -131,14 +131,14 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         role: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "role";
             tableName: string;
             dataType: "string";
             columnType: "SQLiteText";
-            data: "editor" | "admin" | "viewer";
+            data: "admin" | "viewer" | "editor";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -150,7 +150,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         createdBy: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "created_by";
@@ -169,7 +169,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "created_at";
@@ -188,7 +188,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
     };
     dialect: "sqlite";

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

@@ -43,10 +43,10 @@ client, and complete authorization-code + PKCE at
 `/_agent-native/mcp/oauth/authorize` / `/_agent-native/mcp/oauth/token`.
 Access tokens are audience-bound to the exact MCP URL and carry user/org
 identity plus `mcp:read`, `mcp:write`, and/or `mcp:apps`; refresh tokens are
-stored hashed and rotate. Keep `ACCESS_TOKEN` and `agent-native connect` for
+stored hashed and rotate. Keep `ACCESS_TOKEN` and `pnpm exec agent-native connect` for
 local stdio proxying and fallback clients. The CLI
 uses the OAuth-native URL-only entry for Claude Code/Claude Code CLI by
-default; use the Connect page or `agent-native connect --token <token>` when a
+default; use the Connect page or `npx @agent-native/core@latest connect --token <token>` when a
 client needs explicit bearer headers.
 
 ## Local → Real Account Migration

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

@@ -106,7 +106,7 @@ no-CLI equivalent is `https://<app>/_agent-native/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 `agent-native connect <url> --client claude-code` over an older
+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`.
@@ -325,10 +325,10 @@ 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` / `agent-native dev`) then point a local agent at it:
+the app (`pnpm dev` / `pnpm exec agent-native dev`) then point a local agent at it:
 
 ```bash
-agent-native mcp install --client claude-code|claude-code-cli|codex|cowork \
+pnpm exec agent-native mcp install --client claude-code|claude-code-cli|codex|cowork \
   [--app <id>] [--scope user|project]
 ```
 
@@ -336,7 +336,7 @@ 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, the
-Claude-Code JSON shape for Cowork. The entry runs `agent-native mcp serve
+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
 `/_agent-native/mcp` (live registry + HMR + correct deep links stay the single
 source of truth; `--standalone` builds the registry in-process). Companion
@@ -351,7 +351,7 @@ deliberately exposes only the generic builtins plus actions with
 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` /
-`agent-native mcp install` (which provisions an identity-bearing token). A
+`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.
@@ -395,7 +395,7 @@ before telling the user they are unauthenticated.
 - 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 `agent-native start`, a preview deploy, or prod.
+  production is broken; use `pnpm exec agent-native start`, 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

package/dist/templates/workspace-core/.agents/skills/external-agents/references/mcp-apps-embedding.md

@@ -136,8 +136,8 @@ Claude/ChatGPT conversation. Hidden context stays in model context; do not put
 internal app-state file instructions into the visible prompt. `submit: false`
 stays local as a prefill/review path.
 
-When testing Claude through ngrok, use a production build (`agent-native build`
-then `agent-native start`) or a deployed preview/production URL. Claude's
+When testing Claude through ngrok, use a production build (`pnpm exec agent-native build`
+then `pnpm exec agent-native start`) or a deployed preview/production URL. Claude's
 transplant path works with production asset chunks; raw Vite dev modules such
 as `/app/root.tsx` can be app-auth protected and fail dynamic imports from the
 Claude resource origin.

package/dist/workspace-files/schema.d.ts

@@ -31,7 +31,7 @@ export declare const workspaceFiles: import("drizzle-orm/sqlite-core").SQLiteTab
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         scope: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "scope";
@@ -50,7 +50,7 @@ export declare const workspaceFiles: import("drizzle-orm/sqlite-core").SQLiteTab
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         scopeId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "scope_id";
@@ -69,7 +69,7 @@ export declare const workspaceFiles: import("drizzle-orm/sqlite-core").SQLiteTab
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         path: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "path";
@@ -88,7 +88,7 @@ export declare const workspaceFiles: import("drizzle-orm/sqlite-core").SQLiteTab
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         content: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "content";
@@ -107,7 +107,7 @@ export declare const workspaceFiles: import("drizzle-orm/sqlite-core").SQLiteTab
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         contentType: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "content_type";
@@ -126,7 +126,7 @@ export declare const workspaceFiles: import("drizzle-orm/sqlite-core").SQLiteTab
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         sizeBytes: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "size_bytes";
@@ -162,7 +162,7 @@ export declare const workspaceFiles: import("drizzle-orm/sqlite-core").SQLiteTab
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
         updatedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "updated_at";
@@ -181,7 +181,7 @@ export declare const workspaceFiles: import("drizzle-orm/sqlite-core").SQLiteTab
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number | undefined;
+            length: number;
         }>;
     };
     dialect: "sqlite";

package/docs/content/deployment.md

@@ -210,13 +210,14 @@ 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 `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.                                                         |
+| 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.                                                                     |
+| `AGENT_PROD_CODE_EXECUTION` | Optional production code-execution mode: `off` (default), `sandboxed`, or `trusted`. See [Production Code Execution](#production-code-execution). |
 
 ### Required in Production {#env-required-prod}
 
@@ -289,11 +290,34 @@ openssl rand -hex 32
 
 Rotate them by replacing the env var on every instance and redeploying — sessions / OAuth state envelopes signed under the old key become invalid, so users may need to sign in again.
 
+## Production Code Execution {#production-code-execution}
+
+By default, production agents run without code-execution tools. They can call app actions, database tools, MCP tools, browser/session tools, and other registered framework tools, but they do not get shell or filesystem access.
+
+Node-compatible deployments can opt into production code execution through the agent chat plugin or an environment override:
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  codeExecution: { production: "sandboxed" },
+});
+```
+
+The available modes are:
+
+- `off` — the default. No code-execution tools are registered in production.
+- `sandboxed` — registers `run-code`, an isolated Node.js JavaScript runner with a scrubbed environment, a fresh temp directory, output/time limits, and a localhost bridge to allowlisted registered tools such as `provider-api-request`, `provider-api-docs`, `provider-api-catalog`, `web-request`, and `workspace-files`.
+- `trusted` — registers `run-code` plus the full coding tool registry (`bash`, `read`, `edit`, `write`). Use this only for single-tenant or operator-controlled deployments where full shell access to the host is intentional.
+
+Set `AGENT_PROD_CODE_EXECUTION=sandboxed` or `AGENT_PROD_CODE_EXECUTION=trusted` to override the plugin option for a specific deployment without a code change. `AGENT_PROD_CODE_EXECUTION=off` forces code execution off even when the plugin option enables it.
+
+The `run-code` sandbox is process-level isolation, not an OS container. It strips app secrets from the child process environment and uses the Node permission model when available, but outbound network is not blocked by Node itself; authenticated calls should go through the bridge helpers the tool exposes.
+
 ## Updating UI in Production {#updating-ui-in-production}
 
 One of agent-native's core features is that the agent can modify your app's source code — components, routes, styles, actions. During local development this works seamlessly because the agent has full filesystem access.
 
-In a standard production deployment, however, the agent runs in **production mode** with access to app tools (actions, database, MCP) but **not** the filesystem. This means the agent can read and write data, run actions, and interact with external services — but it can't edit your React components or add new routes on a deployed instance.
+In a standard production deployment with [production code execution](#production-code-execution) left off, the agent has access to app tools (actions, database, MCP) but not the filesystem. This means the agent can read and write data, run actions, and interact with external services — but it can't edit your React components or add new routes on a deployed instance.
 
 ### Builder.io: Visual Editing in Production {#builderio}
 

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

@@ -15,24 +15,27 @@ You don't need to build agent-native from scratch. The agent chat, workspace tab
 
 ## The components at a glance {#components}
 
-| Component             | What it is                                                             | Use it when                                                     |
-| --------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------- |
-| `<AgentSidebar>`      | Wraps your app, adds a toggleable side panel containing the full agent | You want the agent available alongside your app on every screen |
-| `<AgentToggleButton>` | Opens/closes `<AgentSidebar>` (put it in your header)                  | Pair with `<AgentSidebar>`                                      |
-| `<AgentPanel>`        | The raw panel itself — chat + CLI + workspace tabs                     | You want full control over layout, or a dedicated agent page    |
-| `<AgentChatSurface>`  | A pre-wired panel/page chat surface                                    | You want chat without the sidebar wrapper                       |
-| `<AssistantChat>`     | Lower-level chat renderer with composer/history hooks                  | You need custom chrome around the standard conversation UI      |
-| `sendToAgentChat()`   | Programmatically send a message to the chat                            | A button that hands work to the agent instead of running inline |
-| `useActionMutation()` | Typesafe frontend wrapper around an action                             | The UI needs to run the same operation an agent tool would run  |
+| Component             | What it is                                                                            | Use it when                                                     |
+| --------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `<AgentSidebar>`      | Wraps your root app layout and adds a toggleable side panel containing the full agent | You want the agent available alongside your app on every screen |
+| `<AgentToggleButton>` | Opens/closes `<AgentSidebar>` (put it in your header)                                 | Pair with `<AgentSidebar>`                                      |
+| `<AgentPanel>`        | The raw panel itself — chat + CLI + workspace tabs                                    | You want full control over layout, or a dedicated agent page    |
+| `<AgentChatSurface>`  | A pre-wired panel/page chat surface                                                   | You want chat without the sidebar wrapper                       |
+| `<AssistantChat>`     | Lower-level chat renderer with composer/history hooks                                 | You need custom chrome around the standard conversation UI      |
+| `sendToAgentChat()`   | Programmatically send a message to the chat                                           | A button that hands work to the agent instead of running inline |
+| `useActionMutation()` | Typesafe frontend wrapper around an action                                            | The UI needs to run the same operation an agent tool would run  |
 
 All of these are exported from `@agent-native/core/client`.
 
 ## The 80% case: `<AgentSidebar>` {#sidebar}
 
-The most common setup is a sidebar that slides in from the right on any screen. Two pieces — the wrapper and a header button:
+The most common setup is a sidebar that opens from the right on any screen.
+Wrap your existing root layout with `<AgentSidebar>`; whatever you pass as
+children stays in the main app area. The agent chat is the side panel.
 
 ```tsx
 // app/root.tsx
+import { Outlet } from "react-router";
 import { AgentSidebar, AgentToggleButton } from "@agent-native/core/client";
 
 export default function Root() {
@@ -48,20 +51,23 @@ export default function Root() {
       defaultSidebarWidth={420}
       position="right"
     >
-      <YourApp />
+      <header>
+        <AgentToggleButton />
+      </header>
+
+      <main>
+        <Outlet />
+      </main>
     </AgentSidebar>
   );
 }
-
-// somewhere in your header / navbar
-<AgentToggleButton />;
 ```
 
 That's it. The user now has a toggleable agent on every page — with chat history, workspace tab, CLI terminal, voice input, and a fullscreen mode. State persists across reloads via `localStorage`.
 
 ### Props
 
-- **`children`** — your app. Rendered in the main area; the sidebar overlays from the chosen side.
+- **`children`** — your app's normal layout and routes. Rendered in the main area; the agent panel mounts beside it on desktop and over it on mobile/fullscreen.
 - **`emptyStateText`** — greeting shown when the chat has no messages. Default: `"How can I help you?"`.
 - **`suggestions`** — starter prompts rendered as clickable chips when empty.
 - **`dynamicSuggestions`** — context-aware prompt chips merged with `suggestions`. Enabled by default; pass `false` to show only static suggestions, or `{ max, includeStatic, getSuggestions }` to customize.
@@ -188,8 +194,9 @@ first so client code does not learn a second, ad hoc transport.
 
 ### Build your own sidebar from pieces {#build-your-own-sidebar}
 
-The stock sidebar is optional. A custom sidebar can keep your own layout and
-still reuse the framework runtime:
+The stock sidebar is optional. This example builds the agent-side UI itself.
+Render it inside your own shell, drawer, split pane, or route when you want to
+own the layout around the agent runtime:
 
 ```tsx
 import { AssistantChat, useChatThreads } from "@agent-native/core/client/chat";

package/docs/content/external-agents.md

@@ -150,6 +150,20 @@ workspace setups should prefer the single Dispatch connector.
 
 The connection is **per-user, scoped, and revocable**. In the OAuth path, the host stores the tokens after `/mcp` authentication; in the fallback path, the browser session you authorized with is the identity the agent acts as. Nothing exposes the deployment's shared secret.
 
+### Re-authenticating after a 401 {#reconnect}
+
+Once connected, auth should persist long-term — access tokens last 30 days by default (override with `MCP_OAUTH_ACCESS_TOKEN_TTL` on the server, e.g. `7d` or `12h`) with a sliding 365-day refresh window, so random 401s should be rare. When one does happen, use the lightweight reconnect command rather than reinstalling:
+
+```bash
+npx @agent-native/core@latest reconnect https://plan.agent-native.com
+```
+
+`reconnect` finds any MCP config entry whose URL ends in `/_agent-native/mcp` for the given host (matching by URL regardless of connector name), then refreshes or replaces the auth material without touching your installed skills or re-running the full install flow. Pass the base app URL (e.g. `https://plan.agent-native.com`) — the `/_agent-native/mcp` suffix is inferred.
+
+In Claude Code, the equivalent UI path is: run `/mcp` and choose **Authenticate** (or **Reconnect**) for the relevant connector.
+
+Never reinstall the skill from scratch just to fix a 401 — `reconnect` is the right tool.
+
 ### Connect page fallback {#connect-page-fallback}
 
 For MCP clients that cannot add a remote OAuth URL directly, 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:

package/docs/content/plan-plugin.md

@@ -12,13 +12,22 @@ The Agent-Native **Plan** app ships as one installable bundle. A single install
 One install gives you:
 
 - **Two skills** — `/visual-plan` (the canonical entry point) and `/visual-recap`.
-- **The Plan MCP connector** — registered against the hosted app at `https://plan.agent-native.com` (MCP endpoint `https://plan.agent-native.com/_agent-native/mcp`, server name `plan`, with legacy alias `agent-native-plans` during migration).
+- **The Plan MCP connector** — registered against the hosted app at `https://plan.agent-native.com` (MCP endpoint `https://plan.agent-native.com/_agent-native/mcp`, server name `plan`).
 
 By default, both skills publish to the hosted Plan app — they create a plan via
 the MCP connector and hand you a link or inline plan to review. They never dump
 an inline Markdown/ASCII plan into chat as the deliverable. If a Plan tool
-returns `needs auth`, `Unauthorized`, or `Session terminated`, authenticate the
-connector (see each route below) instead of falling back to inline output.
+returns `needs auth`, `Unauthorized`, or `Session terminated`, re-authenticate
+the connector instead of falling back to inline output. Access tokens are
+long-lived (30-day default, sliding 365-day refresh), so this should be rare;
+when it happens, the lightweight fix is:
+
+```bash
+npx @agent-native/core@latest reconnect https://plan.agent-native.com
+```
+
+`reconnect` finds and refreshes the connector by URL — no reinstall needed. In
+Claude Code, the equivalent is `/mcp` → **Authenticate / Reconnect**.
 
 The exception is explicit **local-files privacy mode**. When you ask for no DB
 writes or set `AGENT_NATIVE_PLANS_MODE=local-files`, the skills must not call
@@ -33,6 +42,12 @@ This keeps plan content out of the Agent-Native Plan database. Hosted sharing,
 comments, screenshots, and plan history are unavailable until you explicitly
 publish later.
 
+Agent Native Desktop has a separate local-file sync path for hosted plans: the
+Desktop app can mirror a hosted plan to local MDX files and import edits back
+without cloning the Plan app or running a CLI. That workflow keeps the hosted
+Plan database as the source of truth; use local-files privacy mode when the goal
+is no Plan DB writes.
+
 > The plugin (`agent-native-visual-plans`) carries app id `visual-plans`, which is why the Claude Code plugin name and Codex plugin name are both `agent-native-visual-plans`. The Plan app's display name is "Agent-Native Plan".
 
 ## Install routes {#install}
@@ -47,7 +62,7 @@ Works for any host — Claude Code, Codex, Cursor, Cline, Goose, ChatGPT custom
 npx @agent-native/core@latest skills add visual-plan
 ```
 
-This installs `visual-plan` plus the companion `visual-recap` skill, then registers the `plan` connector and its legacy `agent-native-plans` alias, then runs auth (OAuth prompt for hosted/account-backed sharing). Useful flags:
+This installs `visual-plan` plus the companion `visual-recap` skill, then registers the `plan` connector, then runs auth (OAuth prompt for hosted/account-backed sharing). Useful flags:
 
 - `--client codex|claude-code|claude-code-cli|cowork|all` — which local agents to write the MCP config for (default `codex`).
 - `--no-connect` — register the connector without authenticating; run `npx @agent-native/core@latest connect https://plan.agent-native.com` later.
@@ -94,11 +109,11 @@ The same repo is a Codex plugin marketplace. Add it, install the plugin, then au
 codex plugin marketplace add BuilderIO/agent-native
 codex plugin add agent-native-visual-plans@agent-native-apps
 codex mcp login plan   # OAuth in the browser
-# Existing installs may already be authenticated as:
-codex mcp login agent-native-plans
 ```
 
-After install, **start a new Codex thread** so the skills and MCP tools load into the session. The plugin ships URL-only connectors (`[mcp_servers.plan]` and legacy `[mcp_servers.agent-native-plans]` → `https://plan.agent-native.com/_agent-native/mcp`); `codex mcp login` runs the OAuth flow. The universal CLI route above also works for Codex (`npx @agent-native/core@latest skills add visual-plan --client codex`) if you prefer one command that installs and authenticates together.
+After install, **start a new Codex thread** so the skills and MCP tools load into the session. The plugin ships a URL-only connector (`[mcp_servers.plan]` → `https://plan.agent-native.com/_agent-native/mcp`); `codex mcp login plan` runs the OAuth flow. The universal CLI route above also works for Codex (`npx @agent-native/core@latest skills add visual-plan --client codex`) if you prefer one command that installs and authenticates together.
+
+> **Older installs:** if your config still has an `agent-native-plans` entry pointing at the same URL, running `npx @agent-native/core@latest reconnect https://plan.agent-native.com` (or `skills add visual-plan` for a full reinstall) consolidates it to the canonical `plan` name.
 
 ## Updates {#updates}
 

package/docs/content/template-content.md

@@ -24,6 +24,9 @@ When you open the app, you'll see a sidebar tree of pages on the left, the edito
 - **Write rich text** with headings, lists, tables, code blocks, images, and links. Slash commands (`/`) insert blocks; selecting text pops up a formatting toolbar.
 - **Organize pages in a tree** — nest infinitely, drag to reorder, favorite pages you use often.
 - **Search across everything** with full-text search across titles and content.
+- **Sync with local Markdown/MDX files.** Use the `/local-files` view to export
+  your workspace to files, edit them in your own tools, preview changes, and
+  import them back.
 - **Sync with Notion.** Link a local doc to a Notion page and pull or push content in either direction. Comments sync both ways too.
 - **Collaborate in real time.** Multiple people (and the agent) can edit the same doc at the same time.
 - **Share docs** with teammates or make them public — private by default, with viewer / editor / admin roles.
@@ -43,6 +46,24 @@ When you open the app, click **+ New page** in the sidebar, give it a title, and
 
 Select text and hit Cmd+I to focus the agent with that selection pre-loaded — "make this punchier" then operates on exactly what you highlighted.
 
+## Local Markdown files {#local-files}
+
+Content can round-trip documents through local files without cloning or running
+the Content app locally. Open `/local-files`, choose a folder in your browser or
+Agent Native Desktop, and export the current document tree as Markdown/MDX under
+`content/`.
+
+Each exported file contains frontmatter for document metadata (`id`, `title`,
+`parentId`, `position`, favorite/search/visibility flags, and `updatedAt`) plus
+the document body as Markdown. You can edit those files in your normal editor,
+then return to `/local-files` to preview and import changes back into Content.
+
+This workflow is useful when you want content in source control, want to batch
+edit docs with local tools, or want a no-clone path for teams that prefer files
+as the review surface. The hosted app remains the source of truth for sharing,
+comments, permissions, and live collaboration; the local folder is an explicit
+sync surface.
+
 ## Why it's interesting
 
 Three things make Content a good showcase of the framework:
@@ -111,6 +132,21 @@ Documents can be linked to a Notion page and synced in either direction:
 
 Sync state is tracked in the `document_sync_links` table (last synced time, conflict flag, last error). Markdown-to-Notion block conversion lives in `shared/notion-markdown.ts`. Conflict and status UI is in `app/components/editor/NotionConflictBanner.tsx` and `NotionSyncBar.tsx`. See the `notion-integration` skill for the full flow.
 
+### Local file sync
+
+The protected `/local-files` route uses the browser File System Access API (or
+the same Chromium capability inside Agent Native Desktop) to read and write
+Markdown/MDX files from a user-chosen folder. It calls:
+
+- `export-content-source` — reads the accessible document tree and returns a
+  deterministic `content/` file bundle.
+- `import-content-source` — validates files, creates new private documents,
+  updates documents where the caller has editor access, preserves version
+  history, and rejects invalid parent cycles.
+
+The source format lives in `shared/content-source.ts`. Keep that file as the
+single contract for filenames, frontmatter, parsing, and serialization.
+
 ### Comments
 
 Threaded comments on documents with quoted-text anchors, replies, and resolve state. Backed by the `document_comments` table and `app/components/editor/CommentsSidebar.tsx`. Actions: `list-comments`, `add-comment`. Notion comments can sync both ways via `sync-notion-comments`.

package/docs/content/template-plan.md

@@ -208,6 +208,28 @@ and commenting, and returns the hosted URL. It does
 not automatically make your coding agent's LLM local; choose a local or approved
 model if that privacy boundary matters too.
 
+## Desktop local file sync {#desktop-local-sync}
+
+Agent Native Desktop also gives hosted Plans a native local-folder bridge. This
+is different from local-files privacy mode: the hosted Plan database remains the
+source of truth for sharing, comments, history, and live review, while Desktop
+can mirror the current plan's source files to a folder you choose.
+
+Open a plan in Agent Native Desktop, use the plan menu's **Local files** actions,
+then:
+
+- **Link local folder** — choose the folder for that plan's MDX source.
+- **Sync to local folder** — write `plan.mdx`, optional `canvas.mdx`,
+  optional `prototype.mdx`, optional `.plan-state.json`, and image assets.
+- **Import local edits** — read the folder and apply it through
+  `import-visual-plan-source` with the plan's current update timestamp.
+- **Auto-sync changes** — keep exporting the hosted plan's latest source after
+  edits made in the app.
+
+This path does not require cloning the Plan app or running a CLI. It is for
+file-first review/editing around a hosted plan, not for keeping plan content out
+of the hosted database.
+
 ## Useful prompts
 
 - "Use `/visual-plan` before changing the auth flow."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.48.4",
+  "version": "0.49.1",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -95,6 +95,10 @@
     "./client/transcription/BuilderTranscriptionCta": "./dist/client/transcription/BuilderTranscriptionCta.js",
     "./transcription/builder": "./dist/transcription/builder-transcription.js",
     "./adapters/cli": "./dist/adapters/cli/index.js",
+    "./cli/skills": {
+      "types": "./dist/cli/skills.d.ts",
+      "default": "./dist/cli/skills.js"
+    },
     "./router": "./dist/router/index.js",
     "./collab": "./dist/collab/index.js",
     "./a2a": "./dist/a2a/index.js",

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

@@ -43,10 +43,10 @@ client, and complete authorization-code + PKCE at
 `/_agent-native/mcp/oauth/authorize` / `/_agent-native/mcp/oauth/token`.
 Access tokens are audience-bound to the exact MCP URL and carry user/org
 identity plus `mcp:read`, `mcp:write`, and/or `mcp:apps`; refresh tokens are
-stored hashed and rotate. Keep `ACCESS_TOKEN` and `agent-native connect` for
+stored hashed and rotate. Keep `ACCESS_TOKEN` and `pnpm exec agent-native connect` for
 local stdio proxying and fallback clients. The CLI
 uses the OAuth-native URL-only entry for Claude Code/Claude Code CLI by
-default; use the Connect page or `agent-native connect --token <token>` when a
+default; use the Connect page or `npx @agent-native/core@latest connect --token <token>` when a
 client needs explicit bearer headers.
 
 ## Local → Real Account Migration

package/src/templates/workspace-core/.agents/skills/external-agents/SKILL.md

@@ -106,7 +106,7 @@ no-CLI equivalent is `https://<app>/_agent-native/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 `agent-native connect <url> --client claude-code` over an older
+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`.
@@ -325,10 +325,10 @@ 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` / `agent-native dev`) then point a local agent at it:
+the app (`pnpm dev` / `pnpm exec agent-native dev`) then point a local agent at it:
 
 ```bash
-agent-native mcp install --client claude-code|claude-code-cli|codex|cowork \
+pnpm exec agent-native mcp install --client claude-code|claude-code-cli|codex|cowork \
   [--app <id>] [--scope user|project]
 ```
 
@@ -336,7 +336,7 @@ 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, the
-Claude-Code JSON shape for Cowork. The entry runs `agent-native mcp serve
+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
 `/_agent-native/mcp` (live registry + HMR + correct deep links stay the single
 source of truth; `--standalone` builds the registry in-process). Companion
@@ -351,7 +351,7 @@ deliberately exposes only the generic builtins plus actions with
 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` /
-`agent-native mcp install` (which provisions an identity-bearing token). A
+`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.
@@ -395,7 +395,7 @@ before telling the user they are unauthenticated.
 - 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 `agent-native start`, a preview deploy, or prod.
+  production is broken; use `pnpm exec agent-native start`, 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