@agent-native/core 0.32.1 → 0.32.17

package/docs/content/template-design.md

@@ -29,10 +29,18 @@ 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 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.
+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
 
@@ -61,7 +69,17 @@ Generate and pick design directions without leaving Codex, Claude Code, Claude,
    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.
+   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".

package/docs/content/template-dispatch.md

@@ -142,7 +142,7 @@ You can click through the Dispatch UI after signing in. To use the chat composer
 
 ## Customize it {#customize}
 
-Dispatch is a full template like any other — see [Templates](/docs/cloneable-saas). Ask the agent to "add a new integration for Datadog" or "route Slack DMs from channel X to the issues agent" and it'll edit the routing config, add the webhook handler, and wire it up.
+Dispatch is a full template like any other — see [Templates](/docs/cloneable-saas). Ask the agent to "add a new integration for Datadog" or "route Slack DMs from channel X to the analytics agent" and it'll edit the routing config, add the webhook handler, and wire it up.
 
 For workspace-specific management screens, add local React Router pages and
 register them in `app/dispatch-extensions.tsx`. The generated workspace owns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.32.1",
+  "version": "0.32.17",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -130,6 +130,7 @@
     "@radix-ui/react-tooltip": "^1.2.8",
     "@react-router/dev": "^7.13.1",
     "@react-router/fs-routes": "^7.13.1",
+    "@resvg/resvg-js": "^2.6.2",
     "@sentry/browser": "^10.50.0",
     "@sentry/node": "^10.50.0",
     "@standard-schema/spec": "^1.1.0",

package/src/templates/default/AGENTS.md

@@ -7,8 +7,8 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 ### Core Principles
 
 1. **Shared SQL database** -- All app state lives in SQL. Local SQLite at `data/app.db` is the zero-setup dev fallback; deployed apps need a persistent `DATABASE_URL` so data survives container/serverless restarts. Turso is optional, not required: Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments are all valid when supported by the deploy. Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
-2. **All AI through agent chat** -- No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`.
-3. **Actions for agent operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`.
+2. **All AI through agent chat** -- No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`. When UI selections should add hidden context for the user's next prompt without submitting, use `setContextToAgentChat()` with a stable `key`.
+3. **Actions for app operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`; `defineAction` also auto-exposes those operations at `/_agent-native/actions/:name` for the UI. Do not create custom REST routes that re-export actions.
 4. **Live sync keeps the UI current** -- Database writes stream over `/_agent-native/events` first, with `/_agent-native/poll` as the fallback. **When you (the agent) write data, the UI must reflect the change without a manual refresh.** This is non-negotiable. Use `useActionQuery` / `useActionMutation` for action-backed data (preferred). If you use raw `useQuery`, fold `useChangeVersions([<source>, "action"])` into the key for targeted refreshes. See the `real-time-sync` and `adding-a-feature` skills.
 5. **Agent can update code** -- The agent can modify this app's source code directly.
 
@@ -61,7 +61,7 @@ The `navigation` key is written by the UI whenever the route changes. The `navig
 
 This app may be mounted under `/<app-id>` in a workspace. Inside app source, React Router paths are app-local: use `<Link to="/review">` and `navigate("/review")`, not `/<app-id>/review`. The workspace gateway and `APP_BASE_PATH` add the mounted prefix in the browser; hardcoding it inside React Router links causes doubled URLs such as `/<app-id>/<app-id>/review`.
 
-For raw paths outside React Router, use the core helpers: `appPath()` for static assets or normal hrefs, `appApiPath()` for `/api/*`, and `agentNativePath()` for `/_agent-native/*`.
+For raw paths outside React Router, use the core helpers: `appPath()` for static assets or normal hrefs, `appApiPath()` for legitimate route-only `/api/*` endpoints, and `agentNativePath()` for `/_agent-native/*`. Do not use `appApiPath()` to build action-backed CRUD wrappers.
 
 ## Agent Operations
 
@@ -77,6 +77,11 @@ You do NOT get auto-injected screen state. **Call `pnpm action view-screen` at t
 
 ### Actions
 
+Use existing domain actions before reaching for SQL or custom routes. If a
+capability is missing, add or extend a `defineAction` so both the agent and UI
+share the same operation. Do not create `/api/*` routes that only call,
+repackage, or proxy an action.
+
 | Action        | Args                                                                           | Purpose                                                                                 |
 | ------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
 | `view-screen` |                                                                                | See current UI state                                                                    |
@@ -120,7 +125,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 
 1. **Add navigation state entries** — extend `app/hooks/use-navigation-state.ts` to track new routes
 2. **Enhance view-screen** — make the view-screen script return relevant context for the new view
-3. **Create domain actions** — add actions in `actions/` for CRUD operations on new data models
+3. **Create domain actions** — add actions in `actions/` for CRUD operations on new data models; do not create REST wrappers around those actions
 4. **Wire UI for auto-refresh** — use `useActionQuery` / `useActionMutation` for normal CRUD. If a raw `useQuery` is unavoidable, fold `useChangeVersions([<source>, "action"])` into its key with `placeholderData`. When the agent mutates this data, the UI must reflect the change without a manual refresh. See `real-time-sync` skill.
 5. **Create domain skills** — add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations
 6. **Update this AGENTS.md** — add the new actions, state keys, and common tasks

package/src/templates/default/DEVELOPING.md

@@ -80,7 +80,8 @@ export default defineNitroPlugin(async (nitroApp) => {
 | `readSetting`, `writeSetting`                | Read/write settings (from `@agent-native/core/settings`)                   |
 | `readResource`, `writeResource`              | Read/write resources (from `@agent-native/core/resources`)                 |
 | `defineEventHandler`, `readBody`, `getQuery` | H3 route handler utilities (re-exported)                                   |
-| `sendToAgentChat`                            | Send messages to agent from UI (client-side)                               |
+| `sendToAgentChat`                            | Send or prefill messages in the agent chat from UI (client-side)           |
+| `setContextToAgentChat`                      | Stage keyed context chips for the next agent chat prompt from UI           |
 | `agentChat`                                  | Send messages to agent from scripts (server-side)                          |
 
 ## Adding a Script
@@ -101,6 +102,19 @@ sendToAgentChat({
 });
 ```
 
+To add hidden context without submitting or filling the prompt text, stage
+keyed context nuggets. Multiple nuggets stack; using the same `key` replaces the
+previous nugget.
+
+```ts
+import { setContextToAgentChat } from "@agent-native/core";
+setContextToAgentChat({
+  key: "selected-record",
+  title: "Selected Record",
+  context: JSON.stringify(record, null, 2),
+});
+```
+
 **From scripts:**
 
 ```ts

package/src/templates/workspace-core/AGENTS.md

@@ -14,8 +14,10 @@ agent should know.
 - All AI/LLM behavior goes through the app's agent chat. UI and server code
   must not call model providers, AI SDK `generateText()` / `streamText()`, or
   other inline LLM APIs directly. Use `sendToAgentChat()` for local app-agent
-  work, and read `.agents/skills/delegate-to-agent/SKILL.md` before building
-  agent-driven UI or "AI" features.
+  work. When selected UI data should become hidden context for the user's next
+  prompt without submitting anything, use `setContextToAgentChat()` with a
+  stable `key`. Read `.agents/skills/delegate-to-agent/SKILL.md` before
+  building agent-driven UI or "AI" features.
 - Put shared code in `packages/shared` only when multiple apps need it.
 - Keep app-specific screens, actions, state, and skills inside `apps/<app>`.
 - Store shared runtime configuration in the workspace root `.env`; use
@@ -74,7 +76,9 @@ create `defineAction` files in `actions/`, mark reads with
 `http: { method: "GET" }`, and call them from React with `useActionQuery` /
 `useActionMutation`. Do not add duplicate JSON CRUD routes under `/api/*` for
 the same data unless the route is for uploads, streaming, webhooks, OAuth, or
-another route-only concern. Action-backed UI is what makes agent-created or
+another route-only concern. Do not add routes whose main job is to wrap,
+proxy, or re-export an action; the action endpoint already exists at
+`/_agent-native/actions/:name`. Action-backed UI is what makes agent-created or
 agent-edited records appear without a manual refresh.
 
 App database code must be provider-agnostic. Define schemas with

package/src/templates/workspace-root/AGENTS.md

@@ -11,7 +11,9 @@ coding agents can discover the same workspace-wide guidance from the root.
 - All AI/LLM behavior goes through the app's agent chat. UI and server code
   must not call model providers, AI SDK `generateText()` / `streamText()`, or
   other inline LLM APIs directly. Use `sendToAgentChat()` for local app-agent
-  work, and read `packages/shared/.agents/skills/delegate-to-agent/SKILL.md`
+  work. When selected UI data should become hidden context for the user's next
+  prompt without submitting anything, use `setContextToAgentChat()` with a
+  stable `key`. Read `packages/shared/.agents/skills/delegate-to-agent/SKILL.md`
   before building agent-driven UI or "AI" features.
 
 ## Workspace Resources
@@ -101,8 +103,10 @@ coding agents can discover the same workspace-wide guidance from the root.
   `http: { method: "GET" }`, and call them from React with `useActionQuery` /
   `useActionMutation`. Do not add duplicate JSON CRUD routes under `/api/*`
   for the same data unless the route is for uploads, streaming, webhooks,
-  OAuth, or another route-only concern. Action-backed UI is what makes
-  agent-created or agent-edited records appear without a manual refresh.
+  OAuth, or another route-only concern. Do not add routes whose main job is to
+  wrap, proxy, or re-export an action; the action endpoint already exists at
+  `/_agent-native/actions/:name`. Action-backed UI is what makes agent-created
+  or agent-edited records appear without a manual refresh.
 - App database code must be provider-agnostic. Define schemas with
   `@agent-native/core/db/schema` helpers and write app reads/writes with
   Drizzle's query builder and portable `drizzle-orm` operators. Do not import