@agent-native/core 0.131.4 → 0.131.6

package/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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": {