@agent-native/core 0.48.4 → 0.49.0

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/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
@@ -47,7 +56,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 +103,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.48.4",
+  "version": "0.49.0",
   "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

package/src/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.