@agent-native/core 0.48.2 → 0.48.4

package/docs/content/pr-visual-recap.md

@@ -33,16 +33,16 @@ automatic PR Visual Recaps. Say yes to write the GitHub Action, or add it
 explicitly at any time:
 
 ```bash
-agent-native skills add visual-plan --with-github-action
+npx @agent-native/core@latest skills add visual-plan --with-github-action
 ```
 
-This installs the `visual-plan` skill (which includes the `visual-recap` skill the action runs) and writes `.github/workflows/pr-visual-recap.yml` into your repo. The workflow calls **published CLI subcommands** — `agent-native recap gate|collect-diff|mcp-config|scan|build-prompt|shot|comment|check|usage` — so nothing is copied into your repo as helper scripts. `setup` and `doctor` are the interactive helpers you run locally; `gate` is the security-gate step the workflow runs before every recap.
+This installs the `visual-plan` skill (which includes the `visual-recap` skill the action runs) and writes `.github/workflows/pr-visual-recap.yml` into your repo. The workflow calls **published CLI subcommands** through `npx @agent-native/core@latest recap <subcommand>` — including `gate`, `collect-diff`, `mcp-config`, `scan`, `build-prompt`, `shot`, `comment`, `check`, and `usage` — so nothing is copied into your repo as helper scripts. `setup` and `doctor` are the interactive helpers you run locally; `gate` is the security-gate step the workflow runs before every recap.
 
 Then run the guided setup helper:
 
 ```bash
-agent-native recap setup
-agent-native recap doctor
+npx @agent-native/core@latest recap setup
+npx @agent-native/core@latest recap doctor
 ```
 
 `recap setup` refreshes the workflow, uses `gh` to set GitHub Actions
@@ -84,10 +84,10 @@ Set these in your repository's **Settings → Secrets and variables → Actions*
 
 ### Secrets (only two required)
 
-| Secret              | Purpose                                                                                                           |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `PLAN_RECAP_TOKEN`  | Revocable token minted by `agent-native connect`. Authorizes publishing the recap plan and the screenshot upload. |
-| `ANTHROPIC_API_KEY` | The LLM key for the default Claude Code backend.                                                                  |
+| Secret              | Purpose                                                                                                                            |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `PLAN_RECAP_TOKEN`  | Revocable token minted by `npx @agent-native/core@latest connect`. Authorizes publishing the recap plan and the screenshot upload. |
+| `ANTHROPIC_API_KEY` | The LLM key for the default Claude Code backend.                                                                                   |
 
 **Teams: use an org service token.** A personal token is bound to the person
 who minted it — if they leave the org or revoke their tokens, every repo using
@@ -98,7 +98,7 @@ survives any individual leaving, the recaps it publishes are org-visible, and
 any org owner or admin can list or revoke it. Mint one (org owner/admin only):
 
 ```bash
-agent-native connect https://plan.agent-native.com --service-token pr-recap
+npx @agent-native/core@latest connect https://plan.agent-native.com --service-token pr-recap
 ```
 
 The command authenticates you in the browser, then prints the service token
@@ -106,13 +106,13 @@ exactly once — store it as the `PLAN_RECAP_TOKEN` secret. Manage it later with
 the `list-org-service-tokens` and `revoke-org-service-token` actions on the
 Plans app.
 
-**Solo: a personal token still works.** Mint it with `agent-native connect`
+**Solo: a personal token still works.** Mint it with `npx @agent-native/core@latest connect`
 against your Plans app. For the hosted app, this also writes a local
-publish-token file that `agent-native recap setup` can read:
+publish-token file that `npx @agent-native/core@latest recap setup` can read:
 
 ```bash
-agent-native connect https://plan.agent-native.com --client codex
-agent-native recap setup
+npx @agent-native/core@latest connect https://plan.agent-native.com --client codex
+npx @agent-native/core@latest recap setup
 ```
 
 If you prefer manual setup, paste the token into the GitHub secret. Use a
@@ -207,9 +207,9 @@ recap without sending recap content to the Agent-Native Plan database, run the
 same helper flow locally in local-files mode instead:
 
 ```bash
-agent-native recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
-agent-native recap scan --diff recap.diff
-agent-native recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
+npx @agent-native/core@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
+npx @agent-native/core@latest recap scan --diff recap.diff
+npx @agent-native/core@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
 ```
 
 Give the generated `recap-prompt.md` to your coding agent. In local-files mode
@@ -217,7 +217,7 @@ the prompt instructs the agent to write `plans/pr-123-visual-recap/plan.mdx`
 plus optional visual files and then run:
 
 ```bash
-agent-native plan local preview --dir plans/pr-123-visual-recap --kind recap
+npx @agent-native/core@latest plan local preview --dir plans/pr-123-visual-recap --kind recap
 ```
 
 The returned `file://` preview, or `/local-plans/pr-123-visual-recap` in a local
@@ -246,7 +246,7 @@ For the reusable-caller variant, use the `cli-version` input instead (see [Versi
 
 ## Secret-scan allowlist
 
-Before publishing a recap the workflow runs `agent-native recap scan` to detect likely secrets in the diff. Any PR whose diff matches a known-secret pattern is blocked with an explanatory comment — the recap is not published, and no diff content is sent to the coding agent.
+Before publishing a recap the workflow runs `npx @agent-native/core@latest recap scan` to detect likely secrets in the diff. Any PR whose diff matches a known-secret pattern is blocked with an explanatory comment — the recap is not published, and no diff content is sent to the coding agent.
 
 In rare cases a repo has intentional test fixtures or non-secret strings that superficially resemble secret patterns (e.g., a fixture key in a test file). To suppress a false positive, create `.github/recap-scan-allowlist` in the root of your repository.
 
@@ -280,7 +280,7 @@ The allowlist is only consulted by the secret-scan gate. It does not affect what
 
 ### Why use the reusable variant?
 
-The default installer copies the full ~360-line workflow YAML into your repo (the **copy** option). This is the right choice for air-gapped repos or repos that need to audit every line of what runs. The downside is that bug fixes and improvements never reach you — you need to re-run `agent-native recap setup` manually after each release.
+The default installer copies the full ~360-line workflow YAML into your repo (the **copy** option). This is the right choice for air-gapped repos or repos that need to audit every line of what runs. The downside is that bug fixes and improvements never reach you — you need to re-run `npx @agent-native/core@latest recap setup` manually after each release.
 
 The **reusable** option writes a thin ~20-line caller instead. It delegates to `BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml` via `uses:`. Every caller automatically picks up the latest logic when the workflow runs, with no local update needed.
 
@@ -293,7 +293,7 @@ The **reusable** option writes a thin ~20-line caller instead. It delegates to `
 
 ### Caller snippet
 
-This is what `agent-native recap setup --reusable` writes (or you can paste it manually):
+This is what `npx @agent-native/core@latest recap setup --reusable` writes (or you can paste it manually):
 
 ```yaml
 name: PR Visual Recap
@@ -327,15 +327,15 @@ The same secrets and variables described in [Secrets and variables](#secrets-and
 
 ```bash
 # Write the thin caller instead of the full copy:
-agent-native recap setup --reusable
+npx @agent-native/core@latest recap setup --reusable
 
 # Or with a pinned ref for reproducibility:
-agent-native recap setup --reusable --ref v1.2.3
+npx @agent-native/core@latest recap setup --reusable --ref v1.2.3
 ```
 
 Both variants write the workflow to `.github/workflows/pr-visual-recap.yml`. If an existing workflow is already there and differs, the command refuses and tells you to pass `--force` to overwrite.
 
-After writing, run `agent-native recap doctor` as usual to confirm secrets are configured.
+After writing, run `npx @agent-native/core@latest recap doctor` as usual to confirm secrets are configured.
 
 ### Version pinning
 

package/docs/content/pure-agent-apps.md

@@ -65,7 +65,7 @@ If you're not a developer, you can usually start with the [Dispatch template](/d
 For developers who want the absolute minimum, start from the **Starter** template:
 
 ```bash
-npx @agent-native/core create my-agent --template starter
+npx @agent-native/core@latest create my-agent --template starter
 ```
 
 Starter gives you the architecture, the agent panel, the workspace, auth, polling, and one example action — and nothing else. Add your own actions in `actions/`, connect any MCP servers you need, write the relevant skills into the workspace, and you're done.

package/docs/content/skills-guide.md

@@ -219,14 +219,14 @@ npx @agent-native/core@latest skills add assets
 npx skills add BuilderIO/agent-native --skill assets
 
 # Register a hosted MCP connector for local agent clients.
-agent-native app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+npx @agent-native/core@latest app-skill ensure --manifest templates/assets/agent-native.app-skill.json
 
 # Materialize and run editable local source.
-agent-native app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+npx @agent-native/core@latest app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
 
 # Build marketplace adapters: Codex plugin, Claude marketplace, Vercel skills,
 # plain/Claude skills, and MCP configs.
-agent-native app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+npx @agent-native/core@latest app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
 
 # Install a local exported bundle with the Vercel/open Skills CLI.
 npx skills add ./dist/assets-skill --skill assets -a codex -y

package/docs/content/template-analytics.md

@@ -84,7 +84,7 @@ The rest of this doc is for anyone forking the Analytics template or extending i
 Create a new Analytics app from the CLI:
 
 ```bash
-npx @agent-native/core create my-analytics --standalone --template analytics
+npx @agent-native/core@latest create my-analytics --standalone --template analytics
 ```
 
 Local dev:

package/docs/content/template-assets.md

@@ -96,7 +96,7 @@ The rest of this doc is for anyone forking the Assets template or extending it.
 ### Scaffolding
 
 ```bash
-npx @agent-native/core create my-assets --standalone --template assets
+npx @agent-native/core@latest create my-assets --standalone --template assets
 ```
 
 ### Data model
@@ -184,13 +184,13 @@ npx @agent-native/core@latest skills add assets
 npx skills add BuilderIO/agent-native --skill assets
 
 # Hosted install: URL-only MCP connector, no shared secrets in skill files.
-agent-native app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+npx @agent-native/core@latest app-skill ensure --manifest templates/assets/agent-native.app-skill.json
 
 # Local editable launch.
-agent-native app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+npx @agent-native/core@latest app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
 
 # Marketplace package, including Claude Code marketplace and Vercel Labs skills adapters.
-agent-native app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+npx @agent-native/core@latest app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
 
 # Install a local exported Assets bundle with the open skills CLI.
 npx skills add ./dist/assets-skill --skill assets -a codex -y

package/docs/content/template-brain.md

@@ -94,7 +94,7 @@ The rest of this section is for anyone forking or extending the Brain template.
 ### Quick start
 
 ```bash
-npx @agent-native/core create my-brain --standalone --template brain
+npx @agent-native/core@latest create my-brain --standalone --template brain
 cd my-brain
 pnpm install
 pnpm dev

package/docs/content/template-calendar.md

@@ -78,7 +78,7 @@ The rest of this doc is for anyone forking the Calendar template or extending it
 Create a new workspace with the Calendar template:
 
 ```bash
-npx @agent-native/core create my-app --standalone --template calendar
+npx @agent-native/core@latest create my-app --standalone --template calendar
 cd my-app
 pnpm install
 pnpm dev

package/docs/content/template-clips.md

@@ -66,7 +66,7 @@ The rest of this doc is for anyone forking the Clips template or extending it.
 ### Scaffolding
 
 ```bash
-npx @agent-native/core create my-clips --standalone --template clips
+npx @agent-native/core@latest create my-clips --standalone --template clips
 cd my-clips
 pnpm install
 pnpm dev

package/docs/content/template-content.md

@@ -60,7 +60,7 @@ The rest of this doc is for anyone forking the Content template or extending it.
 Scaffold a new workspace with the Content template:
 
 ```bash
-npx @agent-native/core create my-workspace --standalone --template content
+npx @agent-native/core@latest create my-workspace --standalone --template content
 cd my-workspace
 pnpm install
 pnpm dev

package/docs/content/template-design.md

@@ -54,7 +54,7 @@ The rest of this doc is for anyone forking the Design template or extending it.
 ### Scaffolding
 
 ```bash
-npx @agent-native/core create my-design --standalone --template design
+npx @agent-native/core@latest create my-design --standalone --template design
 ```
 
 ### Data model

package/docs/content/template-dispatch.md

@@ -119,7 +119,7 @@ pnpm action create-dream-report --allSources true --sourceTimeoutMs 30000 --limi
 ## Scaffolding {#scaffolding}
 
 ```bash
-npx @agent-native/core create my-platform
+npx @agent-native/core@latest create my-platform
 # pick "Dispatch" in the multi-select picker, plus whichever domain apps you want
 ```
 

package/docs/content/template-forms.md

@@ -64,13 +64,13 @@ See [What is agent-native?](/docs/what-is-agent-native) for the broader framewor
 ### Scaffolding
 
 ```bash
-npx @agent-native/core create my-forms --standalone --template forms
+npx @agent-native/core@latest create my-forms --standalone --template forms
 ```
 
 For a workspace with Forms alongside other apps:
 
 ```bash
-npx @agent-native/core create my-platform
+npx @agent-native/core@latest create my-platform
 ```
 
 Pick Forms and any other templates you want during the workspace setup.

package/docs/content/template-mail.md

@@ -99,7 +99,7 @@ The rest of this doc is for anyone forking the Mail template or extending it.
 Create a new workspace with the Mail template:
 
 ```bash
-npx @agent-native/core create my-mail --standalone --template mail
+npx @agent-native/core@latest create my-mail --standalone --template mail
 cd my-mail
 pnpm install
 pnpm dev
@@ -108,7 +108,7 @@ pnpm dev
 Or add Mail to an existing agent-native workspace:
 
 ```bash
-npx @agent-native/core add-app
+npx @agent-native/core@latest add-app
 ```
 
 To connect Gmail in dev, you need a Google OAuth client:

package/docs/content/template-plan.md

@@ -37,12 +37,6 @@ hit an OAuth wall:
 npx @agent-native/core@latest skills add visual-plan
 ```
 
-If you already have the CLI installed, the shorter command is equivalent:
-
-```bash
-agent-native skills add visual-plan
-```
-
 The command installs both commands: `/visual-plan` and `/visual-recap`.
 
 If you are using a chat-based host that accepts MCP connector URLs directly
@@ -68,7 +62,7 @@ npx @agent-native/core@latest skills add visual-plan --client all
 ```
 
 Pass `--no-connect` to register the connector without authenticating, then run
-`agent-native connect https://plan.agent-native.com` whenever you are ready:
+`npx @agent-native/core@latest connect https://plan.agent-native.com` whenever you are ready:
 
 ```bash
 npx @agent-native/core@latest skills add visual-plan --no-connect
@@ -83,8 +77,8 @@ see [PR Visual Recap](/docs/pr-visual-recap).
 npx @agent-native/core@latest skills add visual-plan --with-github-action
 ```
 
-After the workflow is written, run `agent-native recap setup` to configure
-GitHub Actions secrets/variables where possible and `agent-native recap doctor`
+After the workflow is written, run `npx @agent-native/core@latest recap setup` to configure
+GitHub Actions secrets/variables where possible and `npx @agent-native/core@latest recap doctor`
 to verify the repo is ready.
 
 If you only want the portable instruction file through the open Skills CLI, use:
@@ -195,7 +189,7 @@ not call the hosted Plan MCP tools. The durable files are:
 After writing the folder, the agent validates and previews it locally:
 
 ```bash
-agent-native plan local preview --dir plans/<slug> --kind plan
+npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan
 ```
 
 If you run the Plan app locally with the same `PLAN_LOCAL_DIR`, you can open the
@@ -227,7 +221,7 @@ model if that privacy boundary matters too.
 
 If a Plans tool ever returns `needs auth`, `Unauthorized`, or `Session
 terminated`, do not keep retrying it. Authenticate the connector with
-`agent-native connect https://plan.agent-native.com` (or re-run `/mcp` →
+`npx @agent-native/core@latest connect https://plan.agent-native.com` (or re-run `/mcp` →
 **Authenticate** in an OAuth-capable host), then continue once the connector is
 available.
 
@@ -239,7 +233,7 @@ Most users should install the skill with the CLI instead of scaffolding the app.
 ### Quick start
 
 ```bash
-npx @agent-native/core create my-plans --standalone --template plan
+npx @agent-native/core@latest create my-plans --standalone --template plan
 cd my-plans
 pnpm install
 pnpm dev

package/docs/content/template-slides.md

@@ -71,7 +71,7 @@ The rest of this doc is for anyone forking the Slides template or extending it.
 Create a new Slides app from the CLI:
 
 ```bash
-npx @agent-native/core create my-slides --standalone --template slides
+npx @agent-native/core@latest create my-slides --standalone --template slides
 cd my-slides
 pnpm install
 pnpm dev

package/docs/content/template-starter.md

@@ -51,13 +51,13 @@ Pick a domain template ([Mail](/docs/template-mail), [Calendar](/docs/template-c
 ## Scaffolding {#scaffolding}
 
 ```bash
-npx @agent-native/core create my-app --standalone --template starter
+npx @agent-native/core@latest create my-app --standalone --template starter
 ```
 
 Or, in a workspace:
 
 ```bash
-npx @agent-native/core create my-platform  # pick "Starter" (pre-selected by default) plus any others
+npx @agent-native/core@latest create my-platform  # pick "Starter" (pre-selected by default) plus any others
 ```
 
 ## First edits {#first-edits}

package/docs/content/template-videos.md

@@ -75,7 +75,7 @@ The studio runs on Remotion's `<Player>` for preview and the Remotion CLI for fi
 Scaffold a new Video app from the CLI:
 
 ```bash
-npx @agent-native/core create my-video-app --standalone --template videos
+npx @agent-native/core@latest create my-video-app --standalone --template videos
 cd my-video-app
 pnpm install
 pnpm dev

package/docs/content/workspace-management.md

@@ -127,7 +127,7 @@ For the resource model and canonical paths, see [Workspace — Global resources]
 
 ## Setup Checklist
 
-For a new workspace, after running `agent-native create`:
+For a new workspace, after running `npx @agent-native/core@latest create`:
 
 **Git & GitHub:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.48.2",
+  "version": "0.48.4",
   "type": "module",
   "engines": {
     "node": ">=22"

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