@agent-native/core 0.44.4 → 0.45.1

package/docs/content/plan-plugin.md

@@ -12,9 +12,26 @@ 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 `agent-native-plans`).
+- **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).
 
-Both skills **always 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.
+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.
+
+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
+the Plan MCP connector. They write `plans/<slug>/plan.mdx` plus optional
+`canvas.mdx`, `prototype.mdx`, and `.plan-state.json`, then preview locally with:
+
+```bash
+agent-native plan local preview --dir plans/<slug> --kind plan
+```
+
+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.
 
 > 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".
 
@@ -32,14 +49,27 @@ npx @agent-native/core@latest skills add visual-plan
 agent-native skills add visual-plan
 ```
 
-This installs `visual-plan` plus the companion `visual-recap` skill, then registers the `agent-native-plans` connector and 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 and its legacy `agent-native-plans` alias, 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 `agent-native connect https://plan.agent-native.com` later.
 - `--mcp-url <url>` — point the connector at a custom origin (an ngrok tunnel, a local dev server, or a self-hosted deployment) instead of the hosted default.
 - `--with-github-action` — also write the PR Visual Recap GitHub Action (see [PR Visual Recap](/docs/pr-visual-recap)).
 
-After it finishes, restart or reload the agent client so the new skills and tools load, then run `/visual-plan`.
+Interactive installs also offer the PR Visual Recap Action when no workflow is
+present. Say yes to add it during skill setup, or run the command above later
+with `--with-github-action`. After the workflow is written, run:
+
+```bash
+agent-native recap setup
+agent-native recap doctor
+```
+
+`recap setup` configures the GitHub Action secrets and variables where possible,
+and `recap doctor` verifies the workflow, local publish token, GitHub repo
+access, and required Actions configuration. After install finishes, restart or
+reload the agent client so the new skills and tools load, then run
+`/visual-plan`.
 
 > Note: the bare `npx skills add BuilderIO/agent-native --skill visual-plan` (Vercel/open Skills CLI) installs **instructions only** — it does not register the MCP connector. Use the Agent-Native CLI above when you want the connector wired up too.
 
@@ -65,10 +95,12 @@ The same repo is a Codex plugin marketplace. Add it, install the plugin, then au
 ```bash
 codex plugin marketplace add BuilderIO/agent-native
 codex plugin add agent-native-visual-plans@agent-native-apps
-codex mcp login agent-native-plans   # OAuth in the browser
+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 a URL-only connector (`[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 (`agent-native 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 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 (`agent-native skills add visual-plan --client codex`) if you prefer one command that installs and authenticates together.
 
 ## Updates {#updates}
 
@@ -76,7 +108,7 @@ The plugin routes auto-update — you do not re-pack or re-add the marketplace f
 
 - **Claude Code** — the marketplace entry sets `autoUpdate: true` and the plugin uses commit-SHA versioning, so Claude Code pulls new versions from the repo at startup; run `/reload-plugins` to activate. Every push to the repo's default branch reaches installed users automatically.
 - **Codex** — the plugin `version` embeds a content hash of the bundled skills and MCP endpoint (e.g. `1.0.0+codex.<hash>`), so any skill or endpoint change yields a new version. Codex's startup auto-upgrade re-installs configured git marketplaces on its own; just **start a new thread** to pick up the change. No manual `codex plugin marketplace upgrade` is needed for routine updates.
-- **Universal CLI route** — re-run `npx @agent-native/core@latest skills add visual-plan` to refresh the skills and re-register the connector. `@latest` always pulls the current skills from the published `@agent-native/core` package.
+- **Universal CLI route** — run `npx @agent-native/core@latest skills status visual-plan` to check copied skill folders, or `npx @agent-native/core@latest skills update visual-plan` to refresh them in place. Re-running `skills add visual-plan` still works when you also want to re-register/authenticate the connector. `@latest` always pulls the current skills from the published `@agent-native/core` package.
 
 The connector points at a **hosted** app, so the Plan app's actions and live tool surface always reflect the deployed version regardless of when you installed; only the bundled skill instructions follow the update mechanisms above.
 

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

@@ -1,38 +1,61 @@
 ---
 title: "PR Visual Recap"
-description: "A GitHub Action that runs your repo's visual-recap skill on every PR. An LLM coding agent reads the diff, publishes an interactive recap plan, and posts it as a sticky PR comment with an inline screenshot. Informational and non-blocking."
+description: "A GitHub Action that runs your repo's visual-recap skill on every PR. An LLM coding agent reads the diff, publishes an interactive recap plan, shows an informational check, and posts a sticky PR comment with an inline screenshot. Informational and non-blocking."
 ---
 
 # PR Visual Recap
 
-PR Visual Recap is a GitHub Action that turns every pull request into a **visual code review**. On each push, an LLM coding agent runs your repo's [`visual-recap`](/docs/template-plan) skill against the PR diff, publishes a structured recap plan to the hosted Plans app, and upserts **one sticky PR comment** that links to the interactive plan with an **inline screenshot** embedded right in the comment.
+PR Visual Recap is a GitHub Action that turns every pull request into a **visual code review**. On each push, an LLM coding agent runs your repo's [`visual-recap`](/docs/template-plan) skill against the PR diff, publishes a structured recap plan to the hosted Plans app, shows an informational `Visual Recap` check while it runs, and upserts **one sticky PR comment** that links to the interactive plan with an **inline screenshot** embedded right in the comment.
 
 This is not a deterministic diff renderer. The action invokes a real coding agent (Claude Code CLI by default, or OpenAI Codex CLI) that reads the change, decides what matters, and authors the recap by calling the Plans MCP tool `create-visual-recap` — the same tool the `/visual-recap` slash command uses. You get a high-altitude, schema/API/before-after view of the change instead of a wall of raw diff.
 
-The recap is **informational and non-blocking**. It is not a required check, it never blocks the PR, and it never replaces reading the actual diff. The sticky comment is a review aid, not a sign-off.
+The recap is **informational and non-blocking**. It creates a check row so reviewers can see that generation is in progress, but it is not a required check, it never blocks the PR, and it never replaces reading the actual diff. The sticky comment is a review aid, not a sign-off.
 
 ## What it does
 
 On each PR push, the workflow:
 
 1. Collects a bounded diff between the PR base and head.
-2. Runs the configured coding agent against that diff. The agent reads your repo's `visual-recap` skill and authors a recap, publishing it with `create-visual-recap`.
-3. Reads the published plan URL the agent wrote to `recap-url.txt`.
-4. Opens that URL in headless Chrome and screenshots the rendered plan.
-5. Uploads the PNG to a signed public image route on the Plans app.
-6. Upserts a single sticky PR comment that embeds the screenshot **inline** (served through GitHub's camo image proxy) next to the link to the interactive recap.
+2. Creates an informational `Visual Recap` GitHub check with `Review in progress`.
+3. Runs the configured coding agent against that diff. The agent reads your repo's `visual-recap` skill and authors a recap, publishing it with `create-visual-recap`.
+4. Reads the published plan URL the agent wrote to `recap-url.txt`.
+5. Opens that URL in headless Chrome and screenshots the rendered plan.
+6. Uploads the PNG to a signed public image route on the Plans app.
+7. Upserts a single sticky PR comment that embeds the screenshot **inline** (served through GitHub's camo image proxy) next to the link to the interactive recap.
+8. Completes the `Visual Recap` check as success, skipped, or neutral.
 
 A re-push updates the same plan and the same sticky comment in place — no orphaned plans, no comment spam.
 
 ## Installing it
 
-The Agent-Native CLI writes the workflow into your repository and prints the secrets to set:
+When you install Plans interactively, the Agent-Native CLI asks whether to add
+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
 ```
 
-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 scan|build-prompt|shot|comment` — so nothing is copied into your repo as helper scripts. Commit the generated workflow file, set the secrets below, and open a PR to see it run.
+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 scan|build-prompt|shot|comment` — so nothing is copied into your repo as helper scripts.
+
+Then run the guided setup helper:
+
+```bash
+agent-native recap setup
+agent-native recap doctor
+```
+
+`recap setup` refreshes the workflow, uses `gh` to set GitHub Actions
+secrets/variables when values are available from env or the local Plans
+publish-token store, and prints exact missing commands for anything it cannot
+set. Secret values are sent to `gh` through stdin, not command arguments. Commit
+the generated workflow file and open a PR to see it run.
+
+By default, the workflow builds its agent prompt from the latest bundled
+`visual-recap` guidance in `@agent-native/core@latest`, including any sibling
+reference files the skill ships with. If your repo intentionally customizes and
+pins its committed `visual-recap` folder, set the repository variable
+`VISUAL_RECAP_SKILL_SOURCE=repo`.
 
 ## Backend selection
 
@@ -51,6 +74,7 @@ Beyond the backend, two repository variables tune _how_ the agent runs:
 
 - **`VISUAL_RECAP_MODEL`** pins the model passed to the CLI (`--model`) — for example `gpt-5.5` for Codex, or a Claude model id. Leave it unset to use the CLI's own default model.
 - **`VISUAL_RECAP_REASONING`** sets the reasoning depth: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. It applies to the Codex backend; Claude's reasoning is model-driven, so this variable is ignored there.
+- **`VISUAL_RECAP_SKILL_SOURCE`** controls prompt freshness: `auto`/unset uses the latest bundled skill guidance, while `repo` pins to the committed repo-local `visual-recap` skill folder.
 
 For example, to run the recap on Codex with GPT-5.5 at high reasoning, set the repository variables `VISUAL_RECAP_AGENT=codex`, `VISUAL_RECAP_MODEL=gpt-5.5`, and `VISUAL_RECAP_REASONING=high`.
 
@@ -65,7 +89,18 @@ Set these in your repository's **Settings → Secrets and variables → Actions*
 | `PLAN_RECAP_TOKEN`  | Per-user, 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.                                                                            |
 
-Mint `PLAN_RECAP_TOKEN` with `agent-native connect` against your Plans app, then paste the printed token into the secret. Use a placeholder like `plan_recap_xxxxxxxxxxxxxxxx` only for examples — never commit a real token.
+Mint `PLAN_RECAP_TOKEN` with `agent-native connect` against your Plans app. For
+the hosted app, this also writes a local publish-token file that
+`agent-native recap setup` can read:
+
+```bash
+agent-native connect https://plan.agent-native.com --client codex
+agent-native recap setup
+```
+
+If you prefer manual setup, paste the token into the GitHub secret. Use a
+placeholder like `plan_recap_xxxxxxxxxxxxxxxx` only for examples — never commit a
+real token.
 
 ### Optional (only if you change defaults)
 
@@ -89,12 +124,53 @@ The workflow uses the plain `pull_request` trigger, **not** `pull_request_target
 
 This also means you can merge the workflow file **before** the secrets exist: with no token configured, every run is a quiet no-op until you set the secrets.
 
+## Self-modifying guard (sensitive paths)
+
+The workflow's gate job skips the recap entirely if a PR touches any of the following paths, so a PR can never rewrite what the trusted recap job runs and exfiltrate secrets:
+
+| Path pattern                               | Reason                                                    |
+| ------------------------------------------ | --------------------------------------------------------- |
+| `.github/workflows/pr-visual-recap.yml`    | The workflow itself                                       |
+| `**/skills/visual-(recap\|plan\|plans)/**` | The visual-recap skill the agent follows                  |
+| `**/.claude/**`                            | Agent settings the runner loads                           |
+| `**/CLAUDE.md`                             | Agent instructions the runner loads                       |
+| `**/AGENTS.md`                             | Agent instructions the runner loads                       |
+| `**/.mcp.json`                             | MCP server config the runner loads                        |
+| `packages/core/**`                         | Recap CLI source _(BuilderIO/agent-native monorepo only)_ |
+
+The `packages/core/**` rule applies only in the `BuilderIO/agent-native` monorepo where `packages/core` is the recap CLI source. In consumer repos an unrelated `packages/core/` directory does not trigger the guard.
+
+## Local-files privacy mode
+
+The GitHub Action is designed for hosted, shareable PR review. If you want a
+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
+```
+
+Give the generated `recap-prompt.md` to your coding agent. In local-files mode
+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
+```
+
+The returned `file://` preview, or `/local-plans/pr-123-visual-recap` in a local
+Plan app using the same `PLAN_LOCAL_DIR`, is the review link. This mode disables
+the hosted sticky PR comment, inline screenshot upload, usage attachment, and
+browser comments until you explicitly publish.
+
 ## It's informational, not a gate
 
 The recap is a review aid layered on top of the normal PR flow:
 
-- It is **never a required check** and never blocks merging.
-- A generation or publish failure surfaces as an explanatory sticky comment, not a red X on unrelated code.
+- It shows a `Visual Recap` check row for visibility, but it is **never a required check** and never blocks merging.
+- A generation or publish failure completes neutrally and surfaces as an explanatory sticky comment, not a red X on unrelated code.
 - The recap and its screenshot **do not imply the diff has been reviewed**. Reviewers still need to read the actual changed lines.
 
 ## Related

package/docs/content/skills-guide.md

@@ -132,6 +132,19 @@ Plan app is published this way as a ready-to-add marketplace at the repo root
 see [Plan plugin & marketplace](/docs/plan-plugin) for the end-to-end install
 and auto-update flow.
 
+For users who install copied skills through the universal CLI instead of a
+plugin marketplace, use the CLI freshness commands:
+
+```bash
+npx @agent-native/core@latest skills status visual-plan
+npx @agent-native/core@latest skills update visual-plan
+```
+
+`skills update` scans known Codex/Claude project and user skill folders, compares
+the copied folder hash to the latest bundled skill, and rewrites stale folders in
+place. Newly copied Agent Native skills include an `agent-native-skill.json`
+marker so future status output can identify the source and hash.
+
 ## Creating custom skills {#creating-skills}
 
 Create a skill when:

package/docs/content/template-plan.md

@@ -7,8 +7,8 @@ description: "Agent-Native Plans turns your coding agent's plan into a structure
 
 Agent-Native Plans is visual plan mode for coding agents. It turns an ordinary
 Codex, Claude Code, Markdown, or pasted implementation plan into a structured
-review surface with rich text, diagrams, wireframes, implementation maps,
-annotations, comments, and shareable links.
+review surface with rich text, diagrams, wireframes, annotated code walkthroughs
+and file trees, annotations, comments, and shareable links.
 
 It comes down to two commands. `/visual-plan` builds a plan **before** the agent
 writes code. `/visual-recap` turns a change that **already** happened — a PR,
@@ -45,6 +45,10 @@ 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
+(rather than a CLI-configured client), connect the hosted Plans connector at
+`https://plan.agent-native.com/_agent-native/mcp` — see [MCP Clients](/docs/mcp-clients) for client-specific setup.
+
 Authentication is a one-time browser sign-in at setup — this is intended, and it
 is what lets the agent persist and share the plans it generates. What the auth
 step does depends on your client:
@@ -79,6 +83,10 @@ 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`
+to verify the repo is ready.
+
 If you only want the portable instruction file through the open Skills CLI, use:
 
 ```bash
@@ -99,8 +107,8 @@ After installation, ask your agent for the command that fits the work:
 
 - `/visual-plan` creates a structured plan **before** implementation — for
   architecture, backend, refactor, UI, or mixed product work — pulling in
-  diagrams, wireframes, mockups, clickable prototypes, and implementation maps
-  as the work calls for them.
+  diagrams, wireframes, mockups, clickable prototypes, and annotated code
+  walkthroughs and file trees as the work calls for them.
 - `/visual-recap` creates a high-altitude **review** of a change that already
   happened — a PR, commit, branch, or git diff — as schema, API, file, and
   before/after blocks instead of a wall of raw diff.
@@ -121,8 +129,8 @@ it to the agent starts a revision turn against the existing plan.
 ## What you can do with it
 
 - **Review before implementation.** React to diagrams, wireframes, option tabs,
-  Open Questions forms, risk notes, file maps, and code previews before the
-  agent edits files.
+  Open Questions forms, risk notes, annotated code walkthroughs, and code
+  previews before the agent edits files.
 - **Comment directly on the plan.** Pin feedback to text, images, wireframes, or
   canvas locations; choose whether the comment is for the agent or a human
   reviewer; @mention teammates with inline chips; and resolve comments as the
@@ -162,6 +170,50 @@ Sharing and commenting are the workflows that need an account:
 The hosted Plans connector lives at `https://plan.agent-native.com/_agent-native/mcp`.
 Never put shared secrets in skill files.
 
+## Local-files privacy mode {#local-files}
+
+For privacy-focused work, ask for local-files mode:
+
+```text
+Use /visual-plan in local-files mode. Do not write this plan to the Plan DB.
+```
+
+or set the convention for your agent environment:
+
+```bash
+export AGENT_NATIVE_PLANS_MODE=local-files
+```
+
+In this mode the agent writes a local MDX folder under `plans/<slug>/` and must
+not call the hosted Plan MCP tools. The durable files are:
+
+- `plan.mdx`
+- optional `canvas.mdx`
+- optional `prototype.mdx`
+- optional `.plan-state.json`
+
+After writing the folder, the agent validates and previews it locally:
+
+```bash
+agent-native 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
+read-only app route:
+
+```text
+http://localhost:<port>/local-plans/<slug>
+```
+
+Local-files mode prevents plan or recap content from going to the Agent-Native
+Plan database. It also disables hosted sharing, browser comments, plan history,
+and publish/export receipts until you explicitly opt into publishing. To move a
+local plan into the hosted database, call `publish-visual-plan` with the local
+MDX folder path; this uploads the plan, assigns it a hosted ID, enables sharing
+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.
+
 ## Useful prompts
 
 - "Use `/visual-plan` before changing the auth flow."
@@ -169,6 +221,7 @@ Never put shared secrets in skill files.
 - "Use `/visual-plan` on the Markdown plan below and make it easier to review."
 - "Run `/visual-recap` on this PR so I can review the shape of the change first."
 - "Use `/visual-recap` on the diff between `main` and this branch."
+- "Use `/visual-recap` in local-files mode so no recap content is written to the Plan DB."
 
 ## Recovering from auth errors {#auth-errors}
 
@@ -205,7 +258,9 @@ persistence, or running a fully self-hosted review surface.
 For fully offline, no-account use, you can run the Plans app locally and sync
 your plans to your repo as MDX. This local mode is a separate, advanced path —
 not the default hosted flow — and is best when you need everything to stay on
-your machine and in version control.
+your machine and in version control. For the stricter no-DB path, use
+[local-files privacy mode](#local-files), which reads from MDX folders instead
+of creating local SQL rows.
 
 ## What's next
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.44.4",
+  "version": "0.45.1",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -72,6 +72,7 @@
     "./resources/metadata": "./dist/resources/metadata.js",
     "./oauth-tokens": "./dist/oauth-tokens/index.js",
     "./secrets": "./dist/secrets/index.js",
+    "./secrets/crypto": "./dist/secrets/crypto.js",
     "./org": "./dist/org/index.js",
     "./client/org": "./dist/client/org/index.js",
     "./client/db-admin": "./dist/client/db-admin/index.js",
@@ -240,6 +241,9 @@
     "vite": ">=5",
     "ws": ">=8"
   },
+  "optionalDependencies": {
+    "playwright": "^1.60.0"
+  },
   "peerDependenciesMeta": {
     "ai": {
       "optional": true

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

@@ -95,9 +95,9 @@ For local stdio proxying, Codex/Cowork compatibility, or clients without
 remote MCP OAuth, use the hosted connect fallback:
 
 ```bash
-npx @agent-native/core connect https://dispatch.agent-native.com
+npx @agent-native/core@latest connect https://dispatch.agent-native.com
 # or, for an isolated app:
-npx @agent-native/core connect https://mail.agent-native.com
+npx @agent-native/core@latest connect https://mail.agent-native.com
 ```
 
 The command opens the app in the browser, the user clicks **Authorize**, and a
@@ -111,6 +111,19 @@ 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`.
 
+To re-authenticate an already-installed local/fallback client without
+reinstalling skills or connectors, use:
+
+```bash
+npx @agent-native/core@latest reconnect https://dispatch.agent-native.com --client codex
+# or:
+npx @agent-native/core@latest connect reconnect https://dispatch.agent-native.com --client codex
+```
+
+With no URL, `reconnect` searches the selected client config for the existing
+Agent Native MCP entry. Pass `--name <serverName>` when the config has multiple
+entries or a custom server name.
+
 Under the hood: a logged-in browser session mints an `A2A_SECRET`-signed JWT
 carrying the caller's `sub` + `org_domain` and a unique `jti`, so tool runs
 stay tenant-scoped via `runWithRequestContext`. The existing
@@ -339,14 +352,17 @@ 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
-sparse `tools/list` means you are hitting an unauthenticated dev endpoint —
-connect or present a token rather than assuming the action is missing.
+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.
 
 ## Do
 
 - Do connect local/fallback clients to Dispatch with
-  `npx @agent-native/core connect https://dispatch.agent-native.com`; use a
-  direct app URL only when the host should be isolated to one app.
+  `npx @agent-native/core@latest connect https://dispatch.agent-native.com`;
+  use `npx @agent-native/core@latest reconnect ...` for reauth without
+  reinstalling; use a direct app URL only when the host should be isolated to
+  one app.
 - Do add a `link` builder to any action that produces or lists a navigable
   resource (draft, event, dashboard, document).
 - Do add `mcpApp` when a UI-capable MCP host should render an inline review or