@agent-native/core 0.29.0 → 0.30.2

package/docs/content/external-agents.md

@@ -113,6 +113,20 @@ Restart the agent client after connecting so it picks up the new MCP server; OAu
 
 Use `--client codex` (or `--client claude-code`, `--client claude-code-cli`, `--client cowork`, `--client all`) to skip the picker for scripts or one-off installs.
 
+First-party app skills install the instructions and the hosted MCP connector together with `skills add <name>`. Each has a short alias for demos and tutorials:
+
+```bash
+npx @agent-native/core@latest skills add assets              # aliases: images, image-generation
+npx @agent-native/core@latest skills add design-exploration  # aliases: design, ux-exploration
+```
+
+| Skill                | Alias    | For                    |
+| -------------------- | -------- | ---------------------- |
+| `assets`             | `images` | image/video generation |
+| `design-exploration` | `design` | UI/design exploration  |
+
+The default client is `codex`; add `--client claude-code` or `--client all` for others. Inline hosts (ChatGPT, Claude.ai, Claude Desktop main chat) render the picker / variant grid in chat; CLI/link-only hosts (Codex, Claude Code, Claude Desktop "Code" tab) return an "Open in … →" link where the user picks in the browser and pastes a handoff summary back.
+
 When you truly need an isolated app instead of Dispatch's workspace gateway,
 run the same command with that app's host:
 
@@ -408,7 +422,7 @@ List/search actions point at a record-focused view the same way — e.g. calenda
 
 For hosts that support the MCP Apps extension, an action can also advertise an inline UI resource with `mcpApp`. This is a progressive enhancement for flows where the external agent should hand the user an interactive surface instead of only text — for example reviewing an email draft, editing a calendar invite, or choosing between generated dashboard variants.
 
-Use the real React app with `embedRoute()` or `embedApp()` whenever the user needs UI. The mental model is simple: the action's `link` target is also the MCP App embed target. Expose the operation as a normal action/tool, return a focused deep link with `link`, and add `mcpApp.resource = embedApp(...)` so capable hosts load that same route inline instead of opening a new tab. When both should be built from the same route, prefer `embedRoute({ title, openLabel, path })`; it returns matching `link` and `mcpApp` action fields.
+Use the real React app with `embedRoute()` or `embedApp()` whenever the user needs UI. The mental model is simple: the action's `link` target is also the MCP App embed target. Expose the operation as a normal action/tool, return a focused deep link with `link`, and add `mcpApp.resource = embedApp(...)` so capable hosts load that same route inline instead of opening a new tab. When both should be built from the same route, prefer `embedRoute({ title, openLabel, path })`: it is the convenience wrapper that returns matching `link` and `mcpApp` fields from one call, while `embedApp(...)` is the lower-level resource you assign to `mcpApp.resource` directly.
 
 That means full-app embeds can do anything the route can do once opened: review or edit an email draft, show a filtered inbox/search, open a calendar event or event draft, load an extension page, inspect a full analytics dashboard or saved analysis, continue a deck in the Slides editor, or open a Design project/editor. Prefer URL/deep-link params and the existing `/_agent-native/open` navigation/app-state bridge over inventing a second state protocol for MCP Apps.
 

package/docs/content/template-assets.md

@@ -43,6 +43,34 @@ Use it when your team needs reusable visual direction and searchable source asse
 - **Install as an app-backed skill.** The `agent-native.app-skill.json` manifest exports an Assets skill plus MCP connector metadata so marketplaces can install the app, its instructions, and its picker together.
 - **Serve other agents.** Slides, Design, Content, Mail, and Dispatch can call Assets through A2A to list libraries, generate batches, create videos, refine an asset, fetch exports, and render inline previews where embedding is allowed.
 
+## Using it from your coding agent
+
+Generate and pick brand media 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 assets   # aliases: images, image-generation
+   ```
+
+   Default client is `codex`; add `--client claude-code` or `--client all` for others.
+
+2. **Ask for images.** In your agent's chat: "Generate three blog hero options from the Acme product shots." The agent opens the picker with candidate images you can regenerate, retune (prompt, aspect, count), and choose from.
+3. **Pick.** In inline hosts (ChatGPT, Claude.ai, Claude Desktop main chat) the picker renders right in the chat — click a candidate and the choice flows back automatically. On CLI/link-only hosts (Codex, Claude Code, Claude Desktop "Code" tab) you get an **"Open in Assets →"** link; open it, pick in the browser, then paste the copied handoff summary back into your chat — or just say "use image A".
+
+   ```text
+   Paste this selection back into your chat so the agent can use it.
+
+   Selected Assets image for the next step: <label>
+   Media URL: <url>
+   Use this selected asset in the current artifact or design.
+
+   Selected asset context:
+   { "selectedAsset": { "assetId": "...", "url": "...", "mediaType": "image", ... } }
+   ```
+
+4. **Apply to code.** The chosen Media URL and `assetId` come back to the agent, which uses the URL directly in the code it writes (an `<img>` src, a download) or calls `export-asset`.
+
 ## Why it's interesting
 
 Most AI media tools treat brand consistency as a prompt-writing problem. Assets treats it as application state: references, folders, collections, style briefs, run history, descriptions, and saved assets live in SQL, while binary media lives in object storage or the local file-upload fallback during development.

package/docs/content/template-design.md

@@ -29,9 +29,10 @@ be installed as an app-backed skill plus MCP connector:
 npx @agent-native/core@latest skills add design-exploration
 ```
 
-That gives the agent instructions to create a design shell, present three visual
-directions in the inline Design MCP app, wait for your pick, and iterate from
-the selected prototype.
+That gives the agent instructions 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
 
@@ -50,6 +51,33 @@ the selected prototype.
 - **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.
+
+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/package.json

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