@agent-native/core 0.40.2 → 0.41.0

package/docs/content/faq.md

@@ -83,6 +83,16 @@ That's the whole point. Fork a template and customize it by asking the agent. "A
 
 Yes. Run `npx @agent-native/core create my-app` without picking a template — you get the framework scaffolding (frontend, backend, agent panel, database) but no domain-specific code. See [Getting Started](/docs/getting-started). For agent-first products with no traditional UI, see [Pure-Agent Apps](/docs/pure-agent-apps).
 
+### Can I try it without forking a template? {#try-with-a-skill}
+
+Yes. Add an agent-native **skill** to a coding agent you already use (Claude Code, Codex, Cursor) with one command — no scaffold, no deploy. Start with the **Plans** skill:
+
+```bash
+npx @agent-native/core@latest skills add visual-plan
+```
+
+It installs the skill, registers the hosted MCP connector, and signs you in once; then run `/visual-plan`. See the [Skills Guide](/docs/skills-guide#app-backed-skills) for more skills.
+
 ## Agent capabilities {#agent-capabilities}
 
 ### Can the agent really modify the app's own code? {#can-the-agent-modify-code}

package/docs/content/getting-started.md

@@ -13,6 +13,7 @@ There are two ways to use agent-native, depending on how hands-on you want to be
 
 - **You want to use a hosted version.** Try a template right now at [agent-native.com/templates](/templates). Each template is a live, hosted app — you sign in, start using it, and the agent is already there. No install, no setup. You can stop reading this page and head straight to the [template gallery](/templates).
 - **You want to run locally or customize it.** You'll clone a template, run it on your machine, and shape it however you want — branding, features, integrations. The rest of this page is for you. You'll need [Node.js 22 or newer (LTS recommended)](https://nodejs.org) and [pnpm](https://pnpm.io) installed.
+- **You just want to add agent-native to your existing coding agent.** Skip the scaffold entirely — install a skill into Claude Code, Codex, or Cursor with one command. Jump to [Try it with a skill](#try-with-a-skill).
 
 Not sure which path? If you've never written code, the hosted version is for you. If you have a developer or AI coding tool ready, the local path gives you total control.
 
@@ -53,6 +54,16 @@ pnpm dev:cli --help
 pnpm dev:cli code goals
 ```
 
+## Try it with a skill {#try-with-a-skill}
+
+Don't want to scaffold a whole app yet? Add agent-native superpowers to a coding agent you already use — Claude Code, Codex, or Cursor — with a single command. Installing the **Plans** skill turns the plans your agent writes into structured, reviewable docs with diagrams, wireframes, and inline comments:
+
+```bash
+npx @agent-native/core@latest skills add visual-plan
+```
+
+That one command installs the skill instructions, registers the hosted MCP connector, and signs you in — no marketplace browsing, no manual OAuth. Then run `/visual-plan` in your agent. See the [Skills Guide](/docs/skills-guide#app-backed-skills) for more skills, local/offline installs, and how app-backed skills work.
+
 ## Creating vs adding apps {#creating-vs-adding-apps}
 
 Run `create` from the folder where you want a brand-new workspace:

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

@@ -0,0 +1,103 @@
+---
+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."
+---
+
+# 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.
+
+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.
+
+## 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.
+
+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:
+
+```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.
+
+## Backend selection
+
+Choose which coding agent runs the skill with the `VISUAL_RECAP_AGENT` repository variable:
+
+| `VISUAL_RECAP_AGENT` | Coding agent     | Required API key    |
+| -------------------- | ---------------- | ------------------- |
+| `claude` _(default)_ | Claude Code CLI  | `ANTHROPIC_API_KEY` |
+| `codex`              | OpenAI Codex CLI | `OPENAI_API_KEY`    |
+
+If the variable is unset, the action uses `claude`.
+
+## Model and reasoning
+
+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.
+
+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`.
+
+## Secrets and variables
+
+Set these in your repository's **Settings → Secrets and variables → Actions**.
+
+### Secrets (only two required)
+
+| Secret              | Purpose                                                                                                                     |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `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.
+
+### Optional (only if you change defaults)
+
+| Secret / variable        | Default                         | When you need it                                                                                                 |
+| ------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`         | —                               | Secret. Set together with `VISUAL_RECAP_AGENT=codex` to run the recap with Codex instead.                        |
+| `VISUAL_RECAP_AGENT`     | `claude`                        | Variable. Selects the coding-agent backend (`claude` or `codex`).                                                |
+| `VISUAL_RECAP_MODEL`     | each CLI's default              | Variable. Pins the model — e.g. `gpt-5.5` for Codex, or a Claude model id. Unset uses the CLI's own default.     |
+| `VISUAL_RECAP_REASONING` | each model's default            | Variable. Reasoning depth: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. Applies to the Codex backend. |
+| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com` | Secret. Only when self-hosting the Plans app at a different origin.                                              |
+
+The workflow auto-detects how to invoke its helper CLI (local source inside this monorepo, the published `@agent-native/core` elsewhere), so there is no `RECAP_CLI` variable to set.
+
+## Inline screenshot in the comment
+
+After the agent publishes the recap, the workflow screenshots the rendered plan in headless Chrome and uploads the PNG to a signed public image route on the Plans app. The sticky PR comment then embeds that screenshot **inline** — GitHub re-serves it through its camo proxy, so reviewers see a preview of the recap directly in the comment without opening anything. The link to the full interactive plan sits right next to it for when they want to explore, comment, or annotate.
+
+## Fork-PR safety
+
+The workflow uses the plain `pull_request` trigger, **not** `pull_request_target`. Fork PRs therefore run with **no access to repository secrets**, so the recap step finds no `PLAN_RECAP_TOKEN` and cleanly no-ops — no failed publish, no error comment, no leaked credentials. Recaps only run for PRs from branches in the same repository, where the secrets are available.
+
+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.
+
+## 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.
+- The recap and its screenshot **do not imply the diff has been reviewed**. Reviewers still need to read the actual changed lines.
+
+## 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.
+- [Skills](/docs/skills-guide) — installing agent-native skills into your coding agent.

package/docs/content/skills-guide.md

@@ -82,13 +82,11 @@ offline work, or privacy-sensitive use.
 
 ```bash
 # Happy path: exported instructions plus hosted MCP connector.
+npx @agent-native/core@latest skills add visual-plan
 npx @agent-native/core@latest skills add assets
-npx @agent-native/core@latest skills add images
-npx @agent-native/core@latest skills add design-exploration
 
 # Vercel/open Skills CLI: exported instructions only, no MCP config.
 npx skills add BuilderIO/agent-native --skill assets
-npx skills add BuilderIO/agent-native --skill design-exploration
 
 # Register a hosted MCP connector for local agent clients.
 agent-native app-skill ensure --manifest templates/assets/agent-native.app-skill.json

package/docs/content/template-assets.md

@@ -50,7 +50,7 @@ Generate and pick brand media without leaving Codex, Claude Code, Claude, or Cha
 1. **Install once.** This adds the skill instructions and registers the hosted MCP connector together:
 
    ```bash
-   npx @agent-native/core@latest skills add assets   # aliases: images, image-generation
+   npx @agent-native/core@latest skills add assets   # alias: image-generation
    ```
 
    Default client is `codex`; add `--client claude-code` or `--client all` for others.
@@ -178,9 +178,6 @@ The Assets app skill has app id `assets` and hosted MCP URL
 # Easiest hosted install: exported skill instructions plus MCP connector.
 npx @agent-native/core@latest skills add assets
 
-# Image-generation alias for demos and tutorials.
-npx @agent-native/core@latest skills add images
-
 # Vercel/open Skills CLI install: exported instructions only, no MCP config.
 npx skills add BuilderIO/agent-native --skill assets
 

package/docs/content/template-design.md

@@ -22,26 +22,6 @@ Use it when you want a polished landing page concept, product UI direction, bran
 4. **Export when it is useful.** Download HTML, ZIP, or PDF once the prototype
    is ready to hand to another tool or teammate.
 
-For Codex, Claude Code, and other local agent clients, the hosted Design app can
-be installed as an app-backed skill plus MCP connector:
-
-```bash
-npx @agent-native/core@latest skills add design-exploration
-```
-
-If you only want the portable skill instructions through the Vercel/open Skills
-CLI, use:
-
-```bash
-npx skills add BuilderIO/agent-native --skill design-exploration
-```
-
-The Agent Native CLI path gives the agent instructions and MCP tools to create
-a design shell, present 2-5 visual directions (3 is the sweet spot) in the
-inline Design MCP app, wait for your pick, and iterate from the selected
-prototype. See [Using it from your coding agent](#coding-agent) for the full
-flow.
-
 ## Useful Prompts
 
 - "Create three landing-page directions for a technical analytics product."
@@ -59,43 +39,6 @@ flow.
 - **Import references.** Bring in existing HTML or reference material as context for a new design pass.
 - **Export real files.** Export HTML, ZIP, or PDF from the generated prototype.
 
-## Using It From Your Coding Agent {#coding-agent}
-
-Generate and pick design directions without leaving Codex, Claude Code, Claude, or ChatGPT.
-
-1. **Install once.** This adds the skill instructions and registers the hosted MCP connector together:
-
-   ```bash
-   npx @agent-native/core@latest skills add design-exploration   # aliases: design, ux-exploration
-   ```
-
-   Default client is `codex`; add `--client claude-code` or `--client all` for
-   others. If you only want the portable skill instructions through the
-   Vercel/open Skills CLI, use:
-
-   ```bash
-   npx skills add BuilderIO/agent-native --skill design-exploration
-   ```
-
-   The Vercel/open Skills CLI installs the instruction file only; it does not
-   run MCP connector setup. Use the Agent Native CLI path above when you want
-   the one-command setup.
-
-2. **Ask for directions.** In your agent's chat: "Create three landing-page directions for a technical analytics product." The agent generates 2-5 directions (3 is the sweet spot) you can compare side by side.
-3. **Pick.** In inline hosts (ChatGPT, Claude.ai, Claude Desktop main chat) the variant grid renders right in the chat — pick a direction and it auto-persists as `index.html`, then keep refining. On CLI/link-only hosts (Codex, Claude Code, Claude Desktop "Code" tab) you get an **"Open in Design →"** link; open it, pick in the browser, then paste the copied handoff summary back into your chat — or just say "I picked direction B".
-
-   ```text
-   Paste this back into your chat so your agent continues from the chosen design.
-
-   I picked the "<label>" design direction.
-   It's saved as index.html in design <designId>. Refine from here with get-design-snapshot + generate-design, or export-coding-handoff to bring it into code. Don't show new variants unless I ask.
-
-   Design selection context:
-   { "selectedDesign": { "designId": "...", "variantId": "...", "label": "...", "file": "index.html" } }
-   ```
-
-4. **Apply to code.** Run `export-coding-handoff`; it returns a tokenized raw-code URL plus a ready-to-paste prompt. Your coding agent fetches that URL and writes the code.
-
 ## Why It's Interesting
 
 Design is useful because the agent edits an artifact that is already close to shippable web UI. There is no separate "AI mockup" format to translate later: the preview, the editable source, and the exported artifact all come from the same HTML.

package/docs/content/template-plan.md

@@ -7,8 +7,14 @@ description: "Install Agent-Native Plans as an app-backed skill for Codex, Claud
 
 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, prototypes, implementation
-maps, annotations, comments, and shareable links.
+review surface with rich text, diagrams, wireframes, implementation maps,
+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,
+commit, branch, or git diff — into a high-altitude visual code review. Both open
+the same review surface, so you annotate, comment, and hand feedback back to the
+agent the same way.
 
 ![Agent-Native Plans review surface](https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fdd73f749f8c54dbcb577420ab1a18788)
 
@@ -28,15 +34,12 @@ If you already have the CLI installed, the shorter command is equivalent:
 agent-native skills add visual-plan
 ```
 
-The command installs `/visual-plan` plus the companion commands:
-
-- `/ui-plan` for UI-first plans with mockups, states, and screen-level review.
-- `/prototype-plan` for clickable prototype-first plans with live comments.
-- `/visual-questions` for visual intake before a 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.
+from that plan instead of starting over. Use `/visual-recap` to review a change
+that already landed instead of writing one up by hand.
 
 By default the CLI targets Codex. Add `--client claude-code` or `--client all`
 when you want to configure another host:
@@ -58,13 +61,13 @@ connector, so use the Agent-Native CLI path when you want the one-command setup.
 
 After installation, ask your agent for the command that fits the work:
 
-- `/visual-plan` creates a structured plan for architecture, backend, refactor,
-  or mixed product work.
-- `/ui-plan` creates a UI-first plan with wireframes, mockups, states, and
-  implementation notes.
-- `/prototype-plan` creates a clickable prototype above the plan document, with
-  static mocks, comments, and a focused browser popout.
-- `/visual-questions` opens a visual intake questionnaire before planning.
+- `/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.
+- `/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.
 
 The agent should inspect the codebase first, then create the visual plan when a
 wrong direction would be costly. The returned Plans link opens the review UI so
@@ -100,10 +103,10 @@ it to the agent starts a revision turn against the existing plan.
 ## Useful prompts
 
 - "Use `/visual-plan` before changing the auth flow."
-- "Create a `/ui-plan` for the new onboarding screen with mobile and desktop states."
-- "Create a `/prototype-plan` for the checkout flow so I can click through it."
-- "Use `/visual-questions` to help me choose the dashboard direction first."
+- "Create a `/visual-plan` for the new onboarding screen with mobile and desktop states."
 - "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."
 
 ## For developers
 
@@ -130,6 +133,7 @@ persistence, or running a fully self-hosted review surface.
 ## 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
 - [**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/docs/content/visual-plans.md

@@ -20,7 +20,7 @@ Install with the Agent-Native CLI. The command installs the skill instructions,
 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 commands `/ui-plan`, `/prototype-plan`, `/plan-design`, and `/visual-questions` (see [Invoking the skill](#invoke)).
+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:
 
@@ -34,15 +34,18 @@ Pass `--no-connect` to register the connector without authenticating, then run `
 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, use the slash command that fits the work:
+Once installed, there are two commands:
 
-- `/visual-plan` — the canonical command for any rich plan (architecture, backend, refactors, UI).
-- `/ui-plan` — UI-first work that should start with the screens.
-- `/prototype-plan` — prototype-first work that should start with a clickable flow.
-- `/plan-design` — full-fidelity branded UI direction before implementation.
-- `/visual-questions` — a short visual intake form before planning.
+- `/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.
 

package/docs/content/what-is-agent-native.md

@@ -132,6 +132,8 @@ Agent-native apps follow a fork-and-customize model. You start from a **template
 
 Because it's _your_ app, not shared infrastructure, the agent can safely evolve the code. Your app keeps improving as you use it. See [Templates](/docs/cloneable-saas) for the full story.
 
+Not ready to fork a whole template? You can also try agent-native by adding a **skill** to a coding agent you already use — install the Plans skill with `npx @agent-native/core@latest skills add visual-plan`. See [Try it with a skill](/docs/getting-started#try-with-a-skill).
+
 ## Composable agents {#composable-agents}
 
 Agent-native apps can talk to each other. From inside the mail app, you can tag the analytics agent to query data and include the result in a draft email. The agents discover what other agents are available, hand off work between each other, and surface the results in the UI you're already in.

package/package.json

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