@agent-native/core 0.45.0 → 0.45.1

package/docs/content/plan-plugin.md

@@ -12,7 +12,7 @@ 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).
 
 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
@@ -49,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.
 
@@ -82,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}
 
@@ -93,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

@@ -28,13 +28,34 @@ A re-push updates the same plan and the same sticky comment in place — no orph
 
 ## 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
 
@@ -53,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`.
 
@@ -67,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)
 
@@ -91,6 +124,22 @@ 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

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
@@ -199,7 +207,10 @@ 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. It does
+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.
 

package/package.json

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