@agent-native/core 0.41.1 → 0.42.0

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, /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."
+---
+
+# 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.
+
+## 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`.
+- **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.
+
+> 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 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:
+
+```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`, `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:
+
+- `--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 the six 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/visual-plans) — 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/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/visual-plans.md

@@ -22,6 +22,8 @@ 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**.

package/package.json

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

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