@agent-native/core 0.131.4 → 0.131.6

package/docs/content/extensions.mdx

@@ -30,9 +30,11 @@ The framing matters: an extension isn't a generic "do whatever you want" sandbox
 its own page or inside a named [slot](#slots) exposed by the template. It
 cannot inject elements into arbitrary native components — for example, beside
 every attendee in Calendar — unless the template exposes a slot there. For
-deeper customization, ask the agent to edit the template's source code. Full
-code customization is a core Agent Native capability; extensions are the
-fast, no-deploy layer.
+deeper customization, change the template in your own repository and
+development workflow. An embedded, development, or Builder frame may assist
+when it is intentionally granted workspace and write tooling; otherwise the
+embedded app agent works through app tools. Extensions remain the fast,
+no-deploy layer for runtime customization.
 
 </Callout>
 
@@ -652,13 +654,11 @@ Extensions are private to the user who created them by default. To share:
 
 Shared extensions have their own URLs and plug into the same share dialog as documents, decks, and dashboards. Slot installs are always personal — sharing an extension means others _can_ install it; it doesn't auto-pin it to their UI.
 
-## Should I use an extension or edit the app code? {#vs-app-code}
+## Should I use an extension or the app source workflow? {#vs-app-code}
 
-The framework lets the agent edit the app's source code directly — components,
-routes, styles, and business logic. Use this question when either path could
-solve the request:
+Use this question when either path could solve the request:
 
-- **Start with app code** for product behavior, native UI, layout, routes,
+- **Use the source workflow** for product behavior, native UI, layout, routes,
   business logic, or anything that should be reused across dashboards or users.
 - **Use a custom block only when the app opts in** and the user explicitly wants
   a bespoke, one-off visualization or interaction in an existing extension
@@ -669,19 +669,19 @@ solve the request:
   source-change workflow. Keep the original block in place until the code
   change is reviewed and deployed.
 
-|                       | Extension                      | App code edit                  |
-| --------------------- | ------------------------------ | ------------------------------ |
-| **Created by**        | Agent (or user) at runtime     | Agent editing source files     |
-| **Stored in**         | The database                   | The git repository             |
-| **Requires a build**  | No                             | Yes                            |
-| **Requires a deploy** | No                             | Yes                            |
-| **Scope**             | One user (or shared with org)  | The entire product, every user |
-| **Best for**          | Explicit one-off custom blocks | Durable product behavior       |
+|                       | Extension                      | App source workflow                      |
+| --------------------- | ------------------------------ | ---------------------------------------- |
+| **Created by**        | Agent (or user) at runtime     | User or intentionally code-enabled agent |
+| **Stored in**         | The database                   | The git repository                       |
+| **Requires a build**  | No                             | Yes                                      |
+| **Requires a deploy** | No                             | Yes                                      |
+| **Scope**             | One user (or shared with org)  | The entire product, every user           |
+| **Best for**          | Explicit one-off custom blocks | Durable product behavior                 |
 
-Rule of thumb: **default to app code.** In an app that explicitly enables
+Rule of thumb: **use an extension for runtime customization.** In an app that explicitly enables
 extensions, a one-off custom visualization on a dashboard can be a Custom
 Block; a new pie, multi-bar, or line chart type that should be available across
-dashboards belongs in the template code.
+dashboards belongs in the template source and normal development workflow.
 
 If what you actually need is a cached, refreshable data source for an existing chart or table — not a new interactive widget — see [Data Programs](/docs/data-programs) instead; it shares this page's sandbox and security posture but has no UI of its own.
 

package/docs/content/faq.mdx

@@ -26,7 +26,7 @@ Agent-native is for people who want a real app and an AI agent to work from the
 
 ### How is this different from adding AI to an existing app? {#how-is-this-different}
 
-Most apps bolt AI on as an afterthought that can't actually _do_ things in the app. In an agent-native app the agent is a first-class citizen that shares the same actions, database, and state as the UI, so it can do anything the buttons can — and modify the app's own code. See [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder).
+Most apps bolt AI on as an afterthought that can't actually _do_ things in the app. In an agent-native app the agent is a first-class citizen that shares the same actions, database, and state as the UI, so it can do anything the buttons can. See [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder).
 
 <Diagram id="doc-block-1s6b04" title="Bolted-on AI vs. agent-native" summary="A bolted-on chat sidebar lives in its own world. An agent-native agent shares the same actions, database, and state as the UI.">
 
@@ -126,7 +126,7 @@ The framework ships with production-ready templates including [Chat](/docs/templ
 
 ### Can I customize templates? {#can-i-customize-templates}
 
-That's the whole point. Start from a template and customize it by asking the agent. "Add a priority field to forms." "Connect to our Salesforce instance." "Change the color scheme to match our brand." The agent modifies the code, and your app evolves over time.
+That's the whole point. Start from a template and customize it in your own repository and development workflow. "Add a priority field to forms." "Connect to our Salesforce instance." "Change the color scheme to match our brand." An agent can edit the source when its frame is intentionally granted workspace and write tooling; otherwise the embedded agent operates the resulting app through its actions and data surface.
 
 ### Can I build something the templates don't cover? {#build-from-scratch}
 
@@ -138,9 +138,9 @@ Yes — install a skill into a coding agent you already use with one command and
 
 ## Agent capabilities {#agent-capabilities}
 
-### Can the agent really modify the app's own code? {#can-the-agent-modify-code}
+### Does the embedded agent edit the app's source code? {#can-the-agent-modify-code}
 
-Yes, and it's a feature. The agent can safely edit components, routes, styles, and actions. You ask "add a cohort analysis chart" and the agent builds it. You ask "connect to our Stripe account" and the agent writes the integration. Everything is normal Git-tracked code, so bad changes are easy to revert.
+Not by default. The embedded agent normally works through actions, SQL-backed state, and configured integrations. It can edit components, routes, styles, or actions only when its frame is intentionally granted repository workspace and write tooling. Otherwise use your normal development workflow or a separate code-capable development/Builder frame. For runtime customization without source changes, use [Extensions](/docs/extensions).
 
 ### Can users talk to the agent from outside the app? {#external-channels}
 

package/docs/content/key-concepts.mdx

@@ -1,19 +1,31 @@
 ---
 title: "Key Concepts"
-description: "How agent-native apps work: actions first, SQL database, app-agent loop, optional UI, polling sync, external-agent entry points, context awareness, and portability."
+description: "How agent-native apps work across three layers: the Core framework, optional Toolkit building blocks, and optional Templates, plus the shared actions, SQL database, app-agent loop, and portability contract."
 ---
 
 # Key Concepts
 
 How agent-native apps work under the hood — the principles and the architecture. This page is the contract; for the vision and the case for building this way, see [What Is Agent-Native?](/docs/what-is-agent-native).
 
+## The three layers {#three-layers}
+
+Agent Native is a framework, not a single template. It has three layers:
+
+| Layer                                                    | What it is                                                                                                                                                                                            |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Core - the framework**                                 | The foundational runtime contract: actions, SQL and Drizzle helpers, auth, application state, agent execution, access checks, routing, and live sync. Every app can use Core directly.                |
+| **Toolkit - optional reusable pieces for the framework** | Shared app-building UI and product systems such as primitives, editors, sharing, collaboration, settings, and agent UX. Apps can use, compose, or fork the pieces they need.                          |
+| **Templates - optional apps built on Core**              | Complete, domain-specific apps with routes, schema, actions, instructions, and visual identity. First-party and custom templates commonly use Toolkit, and can be forked and used as starting points. |
+
+Core is the foundation. Toolkit and Templates are optional: a template can use Toolkit, but Toolkit is not required to build an app on Core.
+
 ## The architecture {#the-architecture}
 
-Every agent-native app is three things working together:
+At runtime, every agent-native app is three things working together:
 
-- **Agent** — Autonomous AI that reads data, writes data, runs actions, and modifies code. Customizable with skills and instructions.
+- **Agent** — Autonomous AI that reads data, writes data, runs actions, and uses configured tools. It can also modify source when its frame is intentionally granted workspace and write tooling. Customizable with skills and instructions.
 - **Application** — The product surface around the agent. This may start as chat, add native inline results, grow into a small control plane, or become a full React UI with dashboards, flows, and visualizations.
-- **Computer** — Database, browser, code execution. Agents work directly with SQL and built-in tools; MCP servers are optional add-ons, not the foundation.
+- **Computer** — Database, browser, and configured tool runtimes. Agents work through the app's action and data surface; MCP servers are optional add-ons, not the foundation.
 
 <Diagram id="doc-block-t1f7pj" title="Agent, application, and computer" summary="Three layers working together over one shared SQL store. The agent and the application both read and write the same data.">
 
@@ -23,7 +35,7 @@ Every agent-native app is three things working together:
     <div class="diagram-card">
       <span class="diagram-pill accent">Agent</span
       ><small class="diagram-muted"
-        >reads + writes data, runs actions, modifies code</small
+        >reads + writes data, runs actions, uses configured tools</small
       >
     </div>
     <div class="diagram-card">
@@ -114,14 +126,13 @@ a `customer-research` skill might tell the agent which sources to inspect and
 how to summarize evidence, while `search-crm` and `create-brief` actions fetch
 and write the actual data.
 
-Six rules govern the architecture:
+Five rules govern the architecture:
 
 1. **Data lives in SQL** — all app state lives in the database via Drizzle ORM
 2. **All AI goes through the agent** — no inline LLM calls
 3. **Actions for agent operations** — complex work runs as actions
 4. **Live sync keeps the UI in sync** — database changes stream over SSE with polling as the universal fallback
-5. **The agent can modify code** — the app evolves as you use it
-6. **Application state in SQL** — ephemeral UI state lives in the database, readable by both agent and UI
+5. **Application state in SQL** — ephemeral UI state lives in the database, readable by both agent and UI
 
 ## The four-area checklist {#four-area-checklist}
 
@@ -267,8 +278,8 @@ sendToAgentChat({
 Why not call an LLM inline?
 
 - **AI is non-deterministic.** You need conversation flow to give feedback and iterate — not one-shot buttons.
-- **Context matters.** The agent has your full codebase, instructions, skills, and history. An inline call has none of that.
-- **The agent can do more.** It can run actions, browse the web, modify code, and chain multiple steps together.
+- **Context matters.** The agent has the app's instructions, skills, and history. An inline call has none of that.
+- **The agent can do more.** It can run actions, browse the web, and chain multiple steps together.
 - **External execution.** Because everything goes through the agent and actions, any app can be driven from Slack, Telegram, scheduled jobs, scripts, or another agent via [A2A](/docs/a2a-protocol).
 
 ## Actions system {#actions-system}
@@ -397,17 +408,15 @@ Implement a domain operation once as an action; the framework exposes it to ever
 
 For the full protocol/surface matrix (MCP server and OAuth, MCP Apps, A2A, deep links, native chat widgets, Generative UI, AgentChatRuntime connectors, Agent Web, and the adapter horizon for ACP and A2UI), and for choosing a product shape — chat, inline UI, full app pages, embedded sidecar, automation, or external-agent access — see [Agent Surfaces](/docs/agent-surfaces).
 
-## Agent modifies code {#agent-modifies-code}
-
-This is a feature, not a bug. The agent can safely edit the app's source code: components, routes, styles, actions.
-
-There's no shared codebase to break. You own the app, and the agent evolves it for you over time:
+## App code and customization {#agent-modifies-code}
 
-1. Start from a template (e.g. the analytics template)
-2. Customize it by asking the agent
-3. "Add a new chart type for cohort analysis" — the agent builds it
-4. "Connect to our Stripe account" — the agent writes the integration
-5. Your app keeps improving without manual development
+The framework does not grant the embedded agent ambient access to an app's
+source code. In a deployed app, the agent normally works through actions,
+SQL-backed state, and configured integrations. It can edit components, routes,
+styles, and actions when its frame is intentionally granted workspace and write
+tooling. Templates are complete apps that you can fork and customize in your
+own repository and development workflow either way. For runtime customization
+without source changes, use [Extensions](/docs/extensions).
 
 ## Portable by default {#hosting-agnostic}
 
@@ -430,7 +439,7 @@ These sit on top of the same contract and have their own deep dives:
 
 ## What you get for free {#what-you-get-for-free}
 
-Adopting the framework is valuable mostly because of what you stop having to build. The moment your app follows the six rules, you inherit:
+Adopting the framework is valuable mostly because of what you stop having to build. The moment your app follows the five rules, you inherit:
 
 - **One action = every surface.** Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend hook (`useActionQuery` / `useActionMutation`), a framework-owned HTTP transport, a CLI command, an MCP tool for external clients, and an A2A tool for other agent-native apps. Optional `link` and `mcpApp` metadata add deep links and MCP Apps UI without a second implementation.
 - **A full set of agent resources per user.** Skills, shared `LEARNINGS.md`, personal `memory/MEMORY.md`, `AGENTS.md`, custom sub-agents, scheduled jobs, connected MCP servers — all SQL-backed, no dev-box required. See [Agent Resources](/docs/agent-resources).

package/docs/content/template-brain-developers.mdx

@@ -366,7 +366,10 @@ Brain follows the agent-native four-area contract — change behavior by editing
 - `templates/brain/AGENTS.md` — top-level agent guide. Update when you add major features.
 - `templates/brain/server/db/schema.ts` — data model. Additive migrations only.
 
-Ask the agent to make changes for you — it can edit its own source. See [Self-Modifying Code](/docs/key-concepts#agent-modifies-code).
+Make these changes in the repository's development workflow. The embedded app
+agent can edit source when its frame is intentionally granted workspace and
+write tooling; otherwise it operates the resulting app through its actions and
+data surface. See [Key Concepts](/docs/key-concepts#agent-modifies-code).
 
 ## What's next
 

package/docs/content/template-mail-developers.mdx

@@ -343,7 +343,10 @@ Mail is yours to change. Everything important lives in a handful of places — s
 
 **Changing keyboard shortcuts.** Keybind handlers live in `templates/mail/app/components/email/` — search for `useHotkeys` or `addEventListener("keydown"` to find where each key is wired.
 
-Ask the agent to make any of these changes for you. The agent can edit its own source — see [Self-Modifying Code](/docs/key-concepts#agent-modifies-code).
+Make these changes in the repository's development workflow. The embedded app
+agent can edit source when its frame is intentionally granted workspace and
+write tooling; otherwise it operates the resulting app through its actions and
+data surface. See [Key Concepts](/docs/key-concepts#agent-modifies-code).
 
 ## What's next
 

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

@@ -313,11 +313,11 @@ See [Agent Resources](/docs/agent-resources) for the full concept.
 
 ## Whole-team development {#whole-team-development}
 
-Agent-native isn't just for developers. Because the agent can edit the app's own code, evolving an app stops being a developer-only activity:
+Agent-native isn't just for developers. The embedded agent gives the whole team a shared way to operate the app, while source-code changes remain part of the app's normal development workflow and can be delegated to a frame intentionally granted workspace and write tooling:
 
-- **Designers** update designs directly in the running app through the agent
-- **Product managers** add functionality and update flows by describing them
-- **QA** tests the app and asks the agent to fix what's broken
+- **Designers** update app data and workflows directly through the agent
+- **Product managers** configure workflows and describe changes for the development team
+- **QA** tests the app and reports what's broken through the agent
 - **Anyone on the team** contributes through natural language
 
 The vision: fewer handoffs, one person doing the work of a small team.
@@ -329,10 +329,10 @@ Agent-native apps follow a start-from-a-working-app model. You start from a **te
 1. Pick a template on [agent-native.com/templates](/templates)
 2. Use it immediately as a hosted app (e.g. mail.agent-native.com)
 3. Create your own app from the template when you want to customize — "connect our Stripe account," "add a cohort chart"
-4. The agent modifies the code to match your needs
+4. Customize the source in your own repository and development workflow
 5. Deploy your app to your own domain — or stay on agent-native.com
 
-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.
+Because it's _your_ app, not shared infrastructure, you own its source and can evolve it without changing the shared framework. The embedded agent operates the deployed app through its actions and data surface by default, and can modify source when its frame is explicitly code-enabled. See [Templates](/docs/cloneable-saas) for the full story.
 
 Not ready to start from 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 the [Skills Guide](/docs/skills-guide#app-backed-skills).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.131.4",
+  "version": "0.131.6",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -396,7 +396,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.1",
-    "@agent-native/toolkit": "^0.11.1"
+    "@agent-native/toolkit": "^0.12.0"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",