@agent-native/core 0.41.1 → 0.43.0

package/dist/templates/workspace-core/.agents/skills/extensions/SKILL.md

@@ -133,14 +133,39 @@ POST /_agent-native/extensions
 
 The action accepts:
 
-| Field         | Type     | Required | Purpose                       |
-| ------------- | -------- | -------- | ----------------------------- |
-| `name`        | `string` | yes      | Display name of the extension |
-| `description` | `string` | no       | Short summary                 |
-| `content`     | `string` | yes      | Alpine.js HTML body           |
+| Field                  | Type     | Required | Purpose                                            |
+| ---------------------- | -------- | -------- | -------------------------------------------------- |
+| `name`                 | `string` | yes      | Display name of the extension                      |
+| `description`          | `string` | no       | Short summary                                      |
+| `content`              | `string` | yes\*    | Alpine.js HTML body (\*unless `contentFromAttachment`) |
+| `contentFromAttachment`| `string` | no       | Host a pasted/attached file verbatim, by reference |
+| `icon`                 | `string` | no       | Icon name or short label                           |
 
 See `references/examples.md` for full, runnable `content` bodies.
 
+### Hosting a pasted file (by reference)
+
+When the user **pastes a large file** (e.g. a finished HTML/Alpine app) and asks
+you to host it as an extension, do NOT copy that file into the `content`
+argument. A big paste shows up in your context as a
+`<attachment name="pasted-text-…">` block; re-typing it as a tool argument burns
+thousands of output tokens and frequently gets cut off mid-stream, stalling the
+turn.
+
+Instead, leave `content` empty and pass `contentFromAttachment` set to that
+attachment's `name` — or the literal string `"latest"` for the most recent
+pasted block. The server reads the attachment verbatim and stores it as the
+extension content:
+
+```json
+{ "name": "My Dashboard", "contentFromAttachment": "latest" }
+```
+
+`update-extension` accepts the same `contentFromAttachment` for full-body
+replacement. Inline `content` still works for everything you author yourself —
+use `contentFromAttachment` only to avoid regurgitating something the user
+already pasted.
+
 ## Editing an extension
 
 Use the `update-extension` action. Prefer granular `edits` for surgical

package/docs/content/plan-plugin.md

@@ -0,0 +1,107 @@
+---
+title: "Plan plugin & marketplace"
+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 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:
+
+- **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`).
+
+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".
+
+## Install routes {#install}
+
+There are three ways in. The **universal CLI route** is the one we recommend by default, because it installs the skills **and** registers and authenticates the MCP connector in a single step. The plugin routes are for hosts with a first-class plugin/marketplace system.
+
+### 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 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
+# or, if the CLI is already on PATH:
+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:
+
+- `--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`.
+
+> 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.
+
+### Claude Code (plugin) {#claude-code}
+
+The public `BuilderIO/agent-native` repo is itself a Claude Code plugin marketplace, so you add it directly — no build step. Inside Claude Code:
+
+```text
+/plugin marketplace add BuilderIO/agent-native
+/plugin install agent-native-visual-plans@agent-native-apps
+/reload-plugins
+/mcp        # authenticate the Plan connector (one OAuth approval)
+```
+
+`/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`.
+
+### Codex (plugin) {#codex}
+
+The same repo is a Codex plugin marketplace. Add it, install the plugin, then authenticate the connector:
+
+```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
+```
+
+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.
+
+## Updates {#updates}
+
+The plugin routes auto-update — you do not re-pack or re-add the marketplace for routine skill changes:
+
+- **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.
+
+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.
+
+> **Maintainers:** the marketplace bundle (`.claude-plugin/`, `.agents/plugins/`) is generated from the canonical plan skills by `pnpm sync:plan-marketplace` and verified in CI by `pnpm guard:plan-marketplace`, so the published marketplace always matches the canonical skills. Edit the skill, run `pnpm sync:plan-marketplace`, and commit.
+
+## Do you need to submit anything? {#submission}
+
+**No submission or review is required to distribute or install this.** `BuilderIO/agent-native` is a self-hosted, public git marketplace, so users add it directly with the commands above on **both Claude Code and Codex** — no application or approval. The universal CLI route needs no marketplace at all.
+
+Optional discoverability, if you want a public listing:
+
+- **Claude Code** has a community marketplace you can _optionally_ submit to for listing (submission plus an automated review). The official, Anthropic-curated marketplace is listed at Anthropic's discretion — there is no open self-serve application. Neither is required to use the install commands above.
+- **Codex** has an OpenAI-curated plugin catalog (a closed allow-list, sourced as a partnership rather than a self-serve submission). Self-hosted git marketplaces and the CLI route need no submission to work.
+
+In short: ship it as a self-hosted/public git marketplace and users install directly; submit to a curated catalog only if you want it listed for discovery.
+
+## Plugin vs. skill {#plugin-vs-skill}
+
+A **skill** is a single `SKILL.md` instruction file the agent reads when a task matches. A **plugin** (Claude Code marketplace plugin or Codex plugin) is a package that bundles one or more skills **plus** an MCP connector and metadata, so a host can install everything in one step.
+
+Under the hood, all three routes are produced from the same source by the `agent-native app-skill` CLI: `app-skill pack` builds the marketplace/plugin adapters, and `skills add` is the friendly one-step installer that also registers and authenticates the MCP connector. See [Skills Guide](/docs/skills-guide) for the app-skill manifest format, and [External Agents](/docs/external-agents) for connecting any MCP host and the `agent-native connect` flow.
+
+## What's next {#whats-next}
+
+- [**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/skills-guide.md

@@ -124,6 +124,14 @@ plugin directory containing `skills/<name>/SKILL.md` and `.mcp.json`. In Claude
 Code, add the marketplace, install `agent-native-assets@agent-native-apps`,
 reload plugins, then authenticate the URL-only MCP connector from `/mcp`.
 
+Generated plugin manifests are set up to auto-update: the Claude Code
+marketplace entry sets `autoUpdate: true` (with commit-SHA versioning) and the
+Codex plugin `version` embeds a content hash of the bundled skills and MCP
+endpoint, so installed plugins pick up skill changes without re-packing. The
+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.
+
 ## Creating custom skills {#creating-skills}
 
 Create a skill when:

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.41.1",
+  "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/src/templates/workspace-core/.agents/skills/extensions/SKILL.md

@@ -133,14 +133,39 @@ POST /_agent-native/extensions
 
 The action accepts:
 
-| Field         | Type     | Required | Purpose                       |
-| ------------- | -------- | -------- | ----------------------------- |
-| `name`        | `string` | yes      | Display name of the extension |
-| `description` | `string` | no       | Short summary                 |
-| `content`     | `string` | yes      | Alpine.js HTML body           |
+| Field                  | Type     | Required | Purpose                                            |
+| ---------------------- | -------- | -------- | -------------------------------------------------- |
+| `name`                 | `string` | yes      | Display name of the extension                      |
+| `description`          | `string` | no       | Short summary                                      |
+| `content`              | `string` | yes\*    | Alpine.js HTML body (\*unless `contentFromAttachment`) |
+| `contentFromAttachment`| `string` | no       | Host a pasted/attached file verbatim, by reference |
+| `icon`                 | `string` | no       | Icon name or short label                           |
 
 See `references/examples.md` for full, runnable `content` bodies.
 
+### Hosting a pasted file (by reference)
+
+When the user **pastes a large file** (e.g. a finished HTML/Alpine app) and asks
+you to host it as an extension, do NOT copy that file into the `content`
+argument. A big paste shows up in your context as a
+`<attachment name="pasted-text-…">` block; re-typing it as a tool argument burns
+thousands of output tokens and frequently gets cut off mid-stream, stalling the
+turn.
+
+Instead, leave `content` empty and pass `contentFromAttachment` set to that
+attachment's `name` — or the literal string `"latest"` for the most recent
+pasted block. The server reads the attachment verbatim and stores it as the
+extension content:
+
+```json
+{ "name": "My Dashboard", "contentFromAttachment": "latest" }
+```
+
+`update-extension` accepts the same `contentFromAttachment` for full-body
+replacement. Inline `content` still works for everything you author yourself —
+use `contentFromAttachment` only to avoid regurgitating something the user
+already pasted.
+
 ## Editing an extension
 
 Use the `update-extension` action. Prefer granular `edits` for surgical

package/docs/content/visual-plans.md

@@ -1,80 +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)).
-
-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.