@agent-native/core 0.42.0 → 0.43.0

package/docs/content/plan-plugin.md

@@ -1,20 +1,20 @@
 ---
 title: "Plan plugin & marketplace"
-description: "Install the Agent-Native Plan skills (/visual-plan, /visual-recap, /ui-plan, /prototype-plan, /plan-design, /visual-questions) plus the hosted Plan MCP connector as a Claude Code or Codex plugin, or with the universal CLI. How updates work and whether you need to submit anything."
+description: "Install the Agent-Native Plan skills (/visual-plan, /visual-recap) plus the hosted Plan MCP connector as a Claude Code or Codex plugin, or with the universal CLI. How updates work and whether you need to submit anything."
 ---
 
 # Plan plugin & marketplace
 
-The Agent-Native **Plan** app ships as one installable bundle. A single install adds all six Plan slash-command skills **and** wires up the hosted Plan MCP connector, so the agent can generate plans and the skills can publish them straight into the Plan app.
+The Agent-Native **Plan** app ships as one installable bundle. A single install adds both Plan slash-command skills **and** wires up the hosted Plan MCP connector, so the agent can generate plans and the skills can publish them straight into the Plan app.
 
 ## What you get {#what-you-get}
 
 One install gives you:
 
-- **Six skills** — `/visual-plan` (the canonical entry point), `/visual-recap`, `/ui-plan`, `/prototype-plan`, `/plan-design`, and `/visual-questions`.
+- **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`).
 
-All six 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.
+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.
 
 > 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".
 
@@ -24,7 +24,7 @@ There are three ways in. The **universal CLI route** is the one we recommend by
 
 ### Universal skill route (any MCP host) {#universal}
 
-Works for any host — Claude Code, Codex, Cursor, Cline, Goose, ChatGPT custom MCP apps, Claude Cowork, and anything else MCP-compatible. The Agent-Native CLI installs the six skills, registers the hosted Plan MCP connector, **and authenticates it in the same step**, so your first tool call does not hit an OAuth wall:
+Works for any host — Claude Code, Codex, Cursor, Cline, Goose, ChatGPT custom MCP apps, Claude Cowork, and anything else MCP-compatible. The Agent-Native CLI installs both skills, registers the hosted Plan MCP connector, **and authenticates it in the same step**, so your first tool call does not hit an OAuth wall:
 
 ```bash
 npx @agent-native/core@latest skills add visual-plan
@@ -32,7 +32,7 @@ npx @agent-native/core@latest skills add visual-plan
 agent-native skills add visual-plan
 ```
 
-This installs `visual-plan` plus the companion `visual-recap`, `visual-questions`, `ui-plan`, `prototype-plan`, and `plan-design` skills, 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 `agent-native-plans` connector and 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.
@@ -54,7 +54,7 @@ The public `BuilderIO/agent-native` repo is itself a Claude Code plugin marketpl
 /mcp        # authenticate the Plan connector (one OAuth approval)
 ```
 
-`/plugin install` adds the six Plan skills and a **URL-only** MCP config (no secrets in the package); `/mcp` → **Authenticate** completes the OAuth handshake.
+`/plugin install` adds both Plan skills and a **URL-only** MCP config (no secrets in the package); `/mcp` → **Authenticate** completes the OAuth handshake.
 
 > The marketplace catalog is named `agent-native-apps` and the Plan plugin is `agent-native-visual-plans`, so the install target is always `agent-native-visual-plans@agent-native-apps`.
 
@@ -101,7 +101,7 @@ Under the hood, all three routes are produced from the same source by the `agent
 
 ## What's next {#whats-next}
 
-- [**Visual Plans**](/docs/visual-plans) — what the skills do and how to use them
+- [**Visual Plans**](/docs/template-plan) — what the skills do and how to use them
 - [**PR Visual Recap**](/docs/pr-visual-recap) — run `/visual-recap` automatically on every pull request
 - [**Skills Guide**](/docs/skills-guide) — app-backed skills and the manifest format
 - [**External Agents**](/docs/external-agents) — connect any MCP host and round-trip artifacts

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

@@ -5,7 +5,7 @@ description: "A GitHub Action that runs your repo's visual-recap skill on every
 
 # 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/visual-plans) 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, 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.
 
@@ -99,5 +99,5 @@ The recap is a review aid layered on top of the normal PR flow:
 
 ## Related
 
-- [Visual Plans](/docs/visual-plans) — the `/visual-plan` and `/visual-recap` skills, the hosted Plans connector, and the interactive review surface this action publishes to.
+- [Visual Plans](/docs/template-plan) — the `/visual-plan` and `/visual-recap` skills, the hosted Plans connector, and the interactive review surface this action publishes to.
 - [Skills](/docs/skills-guide) — installing agent-native skills into your coding agent.

package/docs/content/template-plan.md

@@ -1,9 +1,9 @@
 ---
-title: "Plans"
-description: "Install Agent-Native Plans as an app-backed skill for Codex, Claude Code, and other coding agents. Create structured visual plans with diagrams, wireframes, annotations, comments, and share links."
+title: "Visual Plans"
+description: "Agent-Native Plans turns your coding agent's plan into a structured, reviewable document — diagrams, wireframes, annotated code, comments, and share links. Install once from the CLI; reviewers you share with edit as a guest and sign in only to save or share."
 ---
 
-# Plans
+# Visual Plans
 
 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
@@ -18,11 +18,20 @@ agent the same way.
 
 ![Agent-Native Plans review surface](https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fdd73f749f8c54dbcb577420ab1a18788)
 
-## Install the skill
+There are two ways into Plans:
+
+- **From your coding agent (CLI)** — one command installs the skill, registers
+  the hosted Plans connector, and authenticates it.
+- **In the browser** — anyone you share with can open the editor and create or
+  edit as a **guest, with no sign-up**. They sign in only when they want to save
+  or share.
+
+## Install the skill {#install}
 
 Use the Agent-Native CLI. This is the recommended setup because it installs the
-Plans skill instructions, registers the hosted Plans MCP connector, and runs the
-client-specific auth/setup flow in one step:
+Plans skill instructions, registers the hosted Plans MCP connector, **and** runs
+the client-specific auth/setup flow in one step, so your first tool call does not
+hit an OAuth wall:
 
 ```bash
 npx @agent-native/core@latest skills add visual-plan
@@ -36,10 +45,16 @@ agent-native skills add visual-plan
 
 The command installs both commands: `/visual-plan` and `/visual-recap`.
 
-Use `/visual-plan` for both fresh plans and existing Codex, Claude Code,
-Markdown, or pasted plans; when source plan text already exists, the agent builds
-from that plan instead of starting over. Use `/visual-recap` to review a change
-that already landed instead of writing one up by hand.
+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:
+
+- **OAuth-capable hosts** (Claude Code) get a URL-only MCP entry plus a prompt to
+  run `/mcp` and choose **Authenticate**.
+- **Codex / Cowork** run a short browser device-code flow: the CLI prints a code,
+  opens the verification page, and writes the connector once you approve.
+- In a **non-interactive shell or CI**, the auth step is skipped and the exact
+  command to run later is printed for you.
 
 By default the CLI targets Codex. Add `--client claude-code` or `--client all`
 when you want to configure another host:
@@ -48,6 +63,22 @@ when you want to configure another host:
 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:
+
+```bash
+npx @agent-native/core@latest skills add visual-plan --no-connect
+```
+
+To auto-generate a recap on **every pull request**, pass `--with-github-action`.
+This writes a GitHub Action that runs the `visual-recap` skill on each PR and
+posts an interactive recap plan with an inline screenshot as a sticky comment —
+see [PR Visual Recap](/docs/pr-visual-recap).
+
+```bash
+npx @agent-native/core@latest skills add visual-plan --with-github-action
+```
+
 If you only want the portable instruction file through the open Skills CLI, use:
 
 ```bash
@@ -57,6 +88,11 @@ npx skills add BuilderIO/agent-native --skill visual-plan
 That installs the skill instructions only. It does not register the hosted MCP
 connector, so use the Agent-Native CLI path when you want the one-command setup.
 
+> **Prefer a one-install plugin?** Claude Code and Codex can add
+> `BuilderIO/agent-native` directly as a plugin marketplace, which bundles the
+> Plan skills _and_ the connector in one install and auto-updates as the skills
+> improve — see [Plan plugin & marketplace](/docs/plan-plugin).
+
 ## Use it from your coding agent
 
 After installation, ask your agent for the command that fits the work:
@@ -74,6 +110,10 @@ wrong direction would be costly. The returned Plans link opens the review UI so
 you can annotate, correct, choose options, and ask for updates before code
 changes begin.
 
+When a Codex, Claude Code, Markdown, or pasted plan already exists, use
+`/visual-plan`; the agent preserves that source plan and builds the richer review
+surface from it instead of starting over.
+
 If the first pass still has answerable decisions, the agent can place an
 **Open Questions** form at the bottom of the same plan. Answering it and sending
 it to the agent starts a revision turn against the existing plan.
@@ -91,14 +131,36 @@ it to the agent starts a revision turn against the existing plan.
   prose block, visual comments include exact target metadata, and browser
   handoff includes focused screenshots for a small set of visual/canvas comment
   locations instead of one hard-to-read giant image.
-- **Share with reviewers.** Hosted Plans can create private review links and
-  account-backed sharing. Viewing shared plans works from the browser; saving
-  and sharing require sign-in.
 - **Export the result.** Keep an HTML, Markdown, or JSON receipt of the plan
   when you need a source-control-friendly handoff.
-- **Run locally when needed.** The template can be self-hosted for development
-  or offline workflows, while the hosted skill is the easiest path for normal
-  coding-agent use.
+
+## Editing in the browser as a guest {#guest}
+
+People you share a plan with do not need to install anything. They open the Plans
+editor and **create and edit with no sign-up** — they work as a guest. Signing in
+is only required when someone wants to **save or share** their own work.
+
+When a guest signs in, the plans they created as a guest are **claimed** into
+their account, so nothing they built is lost.
+
+Plan prose edits inline: click into any text section, type, format with the rich
+editor toolbar or slash menu, and Plans autosaves the underlying markdown. Review
+annotation mode temporarily turns text sections read-only so clicks can pin
+feedback; leave review mode to keep editing prose.
+
+## Sharing and commenting {#sharing}
+
+Sharing and commenting are the workflows that need an account:
+
+- **Viewing** a public or shared plan works for anyone with the link — no account
+  required.
+- **Commenting** on a shared plan requires an agent-native account.
+- **Sharing** a plan (publishing it to a link, private sharing, reviewer access,
+  cross-device or team review) requires signing in. Google sign-in appears when
+  the standard Google OAuth env vars are configured.
+
+The hosted Plans connector lives at `https://plan.agent-native.com/_agent-native/mcp`.
+Never put shared secrets in skill files.
 
 ## Useful prompts
 
@@ -108,6 +170,14 @@ it to the agent starts a revision turn against the existing plan.
 - "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."
 
+## Recovering from auth errors {#auth-errors}
+
+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` →
+**Authenticate** in an OAuth-capable host), then continue once the connector is
+available.
+
 ## For developers
 
 The rest of this doc is for anyone forking or self-hosting the Plans template.
@@ -130,10 +200,17 @@ The hosted app-backed skill uses:
 The local template is useful when you are developing Plans itself, testing local
 persistence, or running a fully self-hosted review surface.
 
+### Local mode (advanced, offline)
+
+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.
+
 ## What's next
 
-- [**Visual Plans**](/docs/visual-plans) — the full skill flow and auth details
 - [**PR Visual Recap**](/docs/pr-visual-recap) — run `/visual-recap` automatically on every pull request
+- [**Plan plugin & marketplace**](/docs/plan-plugin) — install the Plan skills as a Claude Code or Codex plugin
 - [**Skills**](/docs/skills-guide) — how Agent-Native installs skills
 - [**MCP Clients**](/docs/mcp-clients) — configuring hosted MCP connectors
 - [**Templates**](/docs/cloneable-saas) — the clone-and-own model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -198,6 +198,7 @@
     "react-router": "^7.16.0",
     "recharts": "3.8.1",
     "remark-gfm": "^4.0.1",
+    "roughjs": "4.6.6",
     "shiki": "^4.0.2",
     "tailwind-merge": "^3.5.0",
     "tiptap-markdown": "^0.9.0",

package/docs/content/visual-plans.md

@@ -1,82 +0,0 @@
----
-title: "Visual Plans"
-description: "Turn your coding agent's plans into interactive, reviewable documents with /visual-plan. Install authenticates once; reviewers you share with edit as a guest, sign in only to save or share."
----
-
-# Visual Plans
-
-`/visual-plan` is a coding-agent skill that turns the plan your agent would normally write in Markdown into a **structured visual document**: an optional pan/zoom wireframe canvas on top and a Notion-like technical document below, with diagrams, mockups, prototype options, answerable Open Questions, annotations, and comments you can react to before any code changes.
-
-There are two ways into Plans:
-
-- **From your coding agent (CLI)** — one command installs the skill, registers the hosted Plans connector, and authenticates it.
-- **In the browser** — anyone you share with can open the editor and create or edit as a **guest, with no sign-up**. They sign in only when they want to save or share.
-
-## Coding agent setup {#install}
-
-Install with the Agent-Native CLI. The command installs the skill instructions, registers the hosted Plans MCP connector, **and authenticates it in the same step**, so your first tool call does not hit an OAuth wall:
-
-```bash
-agent-native skills add visual-plan
-```
-
-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. This also installs the companion `/visual-recap` command for reviewing changes that already landed (see [Invoking the skill](#invoke)).
-
-> **Prefer a one-install plugin?** Claude Code and Codex can add `BuilderIO/agent-native` directly as a plugin marketplace, which bundles the six Plan skills _and_ the connector in one install and auto-updates as the skills improve — see [Plan plugin & marketplace](/docs/plan-plugin).
-
-What the auth step does depends on your client:
-
-- **OAuth-capable hosts** (Claude Code) get a URL-only MCP entry plus a prompt to run `/mcp` and choose **Authenticate**.
-- **Codex / Cowork** run a short browser device-code flow: the CLI prints a code, opens the verification page, and writes the connector once you approve.
-- In a **non-interactive shell or CI**, the auth step is skipped and the exact command to run later is printed for you.
-
-Pass `--no-connect` to register the connector without authenticating, then run `agent-native connect https://plan.agent-native.com` whenever you are ready:
-
-```bash
-agent-native skills add visual-plan --no-connect
-```
-
-To auto-generate a recap on **every pull request**, pass `--with-github-action`. This writes a GitHub Action that runs the `visual-recap` skill on each PR and posts an interactive recap plan with an inline screenshot as a sticky comment — see [PR Visual Recap](/docs/pr-visual-recap).
-
-```bash
-agent-native skills add visual-plan --with-github-action
-```
-
-## Invoking the skill {#invoke}
-
-Once installed, there are two commands:
-
-- `/visual-plan` — plan **before** implementation. The canonical command for any rich plan: architecture, backend, refactors, or UI. It pulls in diagrams, wireframes, mockups, clickable prototypes, and implementation maps as the work calls for them, and can open with a short visual intake step when the direction is still open.
-- `/visual-recap` — review **after** the change. Turns a PR, commit, branch, or git diff that already landed into a high-altitude recap — schema, API, file, and before/after blocks instead of a wall of raw diff. A recap is a review aid, not a replacement for reading the diff. See [PR Visual Recap](/docs/pr-visual-recap) to run it automatically on every pull request.
-
-The agent gates hard: it only builds a polished visual plan when a wrong direction would be costly, and skips it for trivial, unambiguous work. Each command generates a plan and opens the editor.
-
-When a Codex, Claude Code, Markdown, or pasted plan already exists, use `/visual-plan`. The agent should preserve that source plan and build the richer review surface from it instead of starting over.
-
-When a plan has unresolved decisions that are useful to answer after the first pass, the agent can put them in an **Open Questions** form at the bottom of the same plan. You can choose single or multiple options, fill in freeform answers, and send the answers back to the agent to revise the plan.
-
-## Editing in the browser as a guest {#guest}
-
-People you share a plan with do not need to install anything. They open the Plans editor and **create and edit with no sign-up** — they work as a guest. Signing in is only required when someone wants to **save or share** their own work.
-
-When a guest signs in, the plans they created as a guest are **claimed** into their account, so nothing they built is lost.
-
-Plan prose edits inline: click into any text section, type, format with the rich editor toolbar or slash menu, and Plans autosaves the underlying markdown. Review annotation mode temporarily turns text sections read-only so clicks can pin feedback; leave review mode to keep editing prose.
-
-## Sharing and commenting {#sharing}
-
-Sharing and commenting are the workflows that need an account:
-
-- **Viewing** a public or shared plan works for anyone with the link — no account required.
-- **Commenting** on a shared plan requires an agent-native account.
-- **Sharing** a plan (publishing it to a link, private sharing, reviewer access, cross-device or team review) requires signing in. Google sign-in appears when the standard Google OAuth env vars are configured.
-
-The hosted Plans connector lives at `https://plan.agent-native.com/_agent-native/mcp`. Never put shared secrets in skill files.
-
-## Local mode (advanced, offline) {#local}
-
-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.
-
-## Recovering from auth errors {#auth-errors}
-
-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` → **Authenticate** in an OAuth-capable host), then continue once the connector is available.