@agent-native/core 0.131.5 → 0.131.7

package/docs/content/agent-native-toolkit.mdx

@@ -30,23 +30,25 @@ being rebuilt in slightly different ways every time.
   />
 </WireframeBlock>
 
-<Diagram id="doc-block-toolkits-boundary" title="How kits fit" summary={"The framework runtime supplies durable guarantees. Toolkit turns those guarantees into reusable product systems. Apps add domain-specific data, routes, and visual identity."}>
+<Diagram id="doc-block-toolkits-boundary" title="How the three layers fit" summary={"Core is the framework foundation. Toolkit is optional reusable infrastructure and UI. Templates are optional apps built on Core, often using Toolkit."}>
 
 ```html
 <div class="diagram-row">
   <div class="diagram-card">
-    <span class="diagram-pill accent">Runtime</span><br />
-    actions, SQL, auth, app state, access checks, realtime transport
+    <span class="diagram-pill accent">Core</span><br />
+    framework runtime: actions, SQL, auth, app state, access checks, live sync
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-card">
     <span class="diagram-pill accent">Toolkit</span><br />
-    collaboration, sharing, setup, review, history, observability
+    optional reusable pieces: collaboration, sharing, setup, review, history,
+    observability
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-card">
-    <span class="diagram-pill accent">Apps</span><br />
-    domain schema, routes, actions, branding, specialized workflows
+    <span class="diagram-pill accent">Templates</span><br />
+    optional apps: domain schema, routes, actions, branding, specialized
+    workflows
   </div>
 </div>
 ```
@@ -70,6 +72,11 @@ being rebuilt in slightly different ways every time.
 
 </Diagram>
 
+Core is the framework. Toolkit is an optional shelf of reusable pieces for the
+framework. Templates are optional apps built on Core; they can use Toolkit and
+can be forked and used as complete starting points. An app can also use Core
+directly without adopting Toolkit or a template.
+
 ## Catalog {#catalog}
 
 | Area                       | Start here                                                      | What it covers                                                                  |

package/docs/content/cloneable-saas.mdx

@@ -216,28 +216,28 @@ The path from "I want my own SaaS" to "I have my own SaaS" is short:
 
 1. **Pick an example app.** Use the CLI picker, or browse the docs and pick one to start from.
 2. **Brand it.** Change the name, colors, logo, and copy. Most example apps expose this in a single config file.
-3. **Customize it.** Ask the agent to add the column you need, change how the inbox groups, connect to your internal API, add a new view. The agent edits the code; you review the diff.
+3. **Customize it.** Make source changes in your own repository and development workflow. An agent can help when its frame is intentionally granted workspace and write tooling; otherwise the embedded agent operates the resulting app through its actions, data, and configured integrations.
 4. **Ship it.** Run the deploy command. You now have your own production SaaS at your own domain.
 
-Steps 2–4 typically take days, not months. Step 3 is open-ended — your customized SaaS evolves over time, in plain English, by talking to the agent.
+Steps 2–4 typically take days, not months. Step 3 is open-ended because the app is yours to evolve, while the embedded agent remains available to operate the deployed product and can assist with source changes when code access is explicitly enabled.
 
 ## Why this is practical {#why}
 
 A separate-codebase-per-user model breaks down at scale: every user maintaining their own inbox sounds like a maintenance nightmare. Two framework decisions make it work:
 
-1. **The agent does the maintenance.** You don't write code to add a column or wire a new integration — you ask the agent. So "your own customized inbox" is a feature, not a burden.
+1. **The app keeps the framework contract.** Your source owns the domain behavior, while Core keeps actions, SQL, state, and sync consistent as the app evolves.
 2. **Per-user customization without per-user code.** Skills, memory, instructions, connected MCP servers, and sub-agents all live in SQL. Every user gets their own customization layer; the shared codebase hosts all of them at once.
 
 The result: Claude-Code-level flexibility for each user, with normal SaaS deployment economics.
 
-<Diagram id="doc-block-bhg7mw" title="Why per-user customization scales" summary={"Two ideas keep the start-from-a-working-app model practical: the agent does the maintenance, and per-user customization lives in SQL — not in per-user code."}>
+<Diagram id="doc-block-bhg7mw" title="Why per-user customization scales" summary={"Two ideas keep the start-from-a-working-app model practical: the app keeps the framework contract, and per-user customization lives in SQL — not in per-user code."}>
 
 ```html
 <div class="diagram-why">
   <div class="diagram-panel" data-rough>
     <strong>Shared codebase</strong
     ><small class="diagram-muted">one app, deployed once</small>
-    <div class="diagram-pill accent">agent does the maintenance</div>
+    <div class="diagram-pill accent">app keeps the framework contract</div>
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
   <div class="diagram-panel" data-rough>

package/docs/content/creating-templates.mdx

@@ -14,6 +14,15 @@ shadcn-style primitives, toast/mobile hooks, date pickers, and simple app shell
 slots. Keep template-specific variants local when they encode product behavior
 or visual identity.
 
+Keep the three layers in mind when deciding where a capability belongs:
+
+- **Core - the framework:** the required runtime and data contract every app can use.
+- **Toolkit - optional reusable pieces:** shared UI and product systems that apps can adopt, compose, or fork.
+- **Templates - optional apps:** complete domain products built on Core, commonly using Toolkit, that people can fork and use as starting points.
+
+Toolkit and Templates are optional. A template is not the framework itself, and
+Toolkit does not replace Core.
+
 A good template:
 
 - Solves one workflow end-to-end, with useful seed data or an empty-state flow.

package/docs/content/deployment.mdx

@@ -536,14 +536,16 @@ Database connection variables (`DATABASE_URL`, `DATABASE_AUTH_TOKEN`, per-app `<
 
 These must be set before promoting an app to a real prod deploy. Missing values either fail-closed (the framework refuses to start / refuses to handle requests) or fall back to weaker behavior with a loud warning.
 
-| Variable                 | Description                                                                                                                                                                                                                                       |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BETTER_AUTH_SECRET`     | 32+ char random string. Signs session cookies AND is the fallback HMAC for `OAUTH_STATE_SECRET` and `SECRETS_ENCRYPTION_KEY`. Hard-required: the framework throws on startup if missing in production.                                            |
-| `BETTER_AUTH_URL`        | Public origin of this app (e.g. `https://mail.example.com`). Used for cookie domain and OAuth redirect construction.                                                                                                                              |
-| `ANTHROPIC_API_KEY`      | API key for the embedded production agent. **In multi-tenant deploys**, the framework refuses to fall back to this when the user has no per-user key — bring-your-own-key is required. Single-tenant self-hosted installs use it as a global key. |
-| `OAUTH_STATE_SECRET`     | Dedicated HMAC key for OAuth state envelopes (Google, Atlassian, Zoom). Falls back to `BETTER_AUTH_SECRET` when unset, but a dedicated value is recommended so rotating one doesn't invalidate the other. Generate via `openssl rand -hex 32`.    |
-| `A2A_SECRET`             | Shared HMAC for inter-app A2A JSON-RPC. Without it, every A2A endpoint and the `/_agent-native/integrations/process-task` self-fire endpoint return 503 in production.                                                                            |
-| `SECRETS_ENCRYPTION_KEY` | AES-256-GCM key for the encrypted-at-rest secrets vault. Falls back to `BETTER_AUTH_SECRET`. Hard-fails in production when both are unset.                                                                                                        |
+| Variable                                    | Description                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`                        | 32+ char random string. Signs session cookies and is the fallback for `OAUTH_STATE_SECRET` and app-local encrypted values. It is also a legacy read candidate for existing shared vault ciphertext. Hard-required: the framework throws on startup if missing in production.                                                                 |
+| `BETTER_AUTH_URL`                           | Public origin of this app (e.g. `https://mail.example.com`). Used for cookie domain and OAuth redirect construction.                                                                                                                                                                                                                         |
+| `ANTHROPIC_API_KEY`                         | API key for the embedded production agent. **In multi-tenant deploys**, the framework refuses to fall back to this when the user has no per-user key — bring-your-own-key is required. Single-tenant self-hosted installs use it as a global key.                                                                                            |
+| `OAUTH_STATE_SECRET`                        | Dedicated HMAC key for OAuth state envelopes (Google, Atlassian, Zoom). Falls back to `BETTER_AUTH_SECRET` when unset, but a dedicated value is recommended so rotating one doesn't invalidate the other. Generate via `openssl rand -hex 32`.                                                                                               |
+| `A2A_SECRET`                                | Shared HMAC for inter-app A2A JSON-RPC. Without it, every A2A endpoint and the `/_agent-native/integrations/process-task` self-fire endpoint return 503 in production. When no dedicated workspace vault key is set, shared vault ciphertext uses a purpose-derived key from this value, so rotating it also rotates the vault key.          |
+| `WORKSPACE_SECRETS_ENCRYPTION_KEY`          | Preferred stable AES-256-GCM key for the shared encrypted-at-rest secrets vault. Set the same value in every app that reads the vault. It is separate from app-local OAuth/credential encryption, so A2A trust can rotate without stranding vault rows. Existing A2A-, Better Auth-, and app-key ciphertext is migrated on successful reads. |
+| `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` | Optional previous workspace vault key used only during a rotation window. Deploy it alongside the new `WORKSPACE_SECRETS_ENCRYPTION_KEY`, let successful reads re-encrypt rows, then remove it after migration.                                                                                                                              |
+| `SECRETS_ENCRYPTION_KEY`                    | Legacy combined key for app-local encryption and the shared vault. It remains supported, but new multi-app deployments should use `WORKSPACE_SECRETS_ENCRYPTION_KEY` for the shared vault so changing workspace encryption does not change app-local OAuth ciphertext.                                                                       |
 
 ### Auth & Identity {#env-auth}
 
@@ -563,13 +565,13 @@ Inside a workspace, the root `.env` is loaded into every app automatically, so s
 
 ### Generating Strong Secrets {#env-generate-secrets}
 
-For any secret marked "32+ char random" (`BETTER_AUTH_SECRET`, `OAUTH_STATE_SECRET`, `A2A_SECRET`, `SECRETS_ENCRYPTION_KEY`, `AGENT_NATIVE_BUILDER_RELAY_SECRET`), generate fresh values with:
+For any secret marked "32+ char random" (`BETTER_AUTH_SECRET`, `OAUTH_STATE_SECRET`, `A2A_SECRET`, `WORKSPACE_SECRETS_ENCRYPTION_KEY`, `SECRETS_ENCRYPTION_KEY`, `AGENT_NATIVE_BUILDER_RELAY_SECRET`), generate fresh values with:
 
 ```bash
 openssl rand -hex 32
 ```
 
-Rotate them by replacing the env var on every instance and redeploying — sessions / OAuth state envelopes signed under the old key become invalid, so users may need to sign in again.
+Rotate signing/session keys by replacing the env var on every instance and redeploying — sessions / OAuth state envelopes signed under the old key become invalid, so users may need to sign in again. Rotate `WORKSPACE_SECRETS_ENCRYPTION_KEY` with the `..._PREVIOUS` window described above so encrypted vault rows remain readable while they migrate.
 
 ## Production Agent Tools {#production-agent-tools}
 
@@ -628,13 +630,17 @@ The `run-code` sandbox is process-level isolation, not an OS container. It strip
 
 ## Updating UI in Production {#updating-ui-in-production}
 
-One of agent-native's core features is that the agent can modify your app's source code — components, routes, styles, actions. During local development this works seamlessly because the agent has full filesystem access.
+The ordinary deployed app agent works through app tools — actions, database,
+MCP, and configured integrations — rather than receiving ambient access to the
+app's source code. Source changes belong in the repository's development
+workflow. An embedded, local, or Builder frame can edit the repository when
+that frame is intentionally granted workspace and write tooling.
 
 In a standard production deployment with [production code execution](#production-code-execution) left off, the agent has access to app tools (actions, database, MCP) but not the filesystem. This means the agent can read and write data, run actions, and interact with external services — but it can't edit your React components or add new routes on a deployed instance.
 
 ### Builder.io: Visual Editing in Production {#builderio}
 
-[Builder.io](https://www.builder.io?utm_source=agent-native&utm_medium=docs&utm_campaign=framework&utm_content=deployment) solves this by providing a managed cloud environment where the agent retains the ability to modify your app's UI in production. Connect your repo to Builder.io and prompt for UI changes directly — no redeploy needed.
+[Builder.io](https://www.builder.io?utm_source=agent-native&utm_medium=docs&utm_campaign=framework&utm_content=deployment) is a separate managed code-capable workflow where an agent can modify your app's UI in production. Connect your repo to Builder.io and prompt for UI changes directly — no redeploy needed.
 
 **How it works:**
 

package/docs/content/doctor.mdx

@@ -5,7 +5,14 @@ description: "agent-native doctor scans a generated app's source for the framewo
 
 # Doctor (Code Checks)
 
-The agent can write this app's own source code. `agent-native doctor` is the automated check for that: it scans app source for the framework's security-critical code-safety invariants — the same class of check that lives in this framework's own CI as `scripts/guard-*.mjs` — ported to run against a single generated app instead of the framework's multi-template monorepo layout. It's read-only: doctor never edits your code, it only reports.
+Generated apps contain source code that can be changed through the repository's
+development workflow, including by an agent frame intentionally granted
+workspace and write tooling. `agent-native doctor` is the automated check for that: it
+scans app source for the framework's security-critical code-safety invariants —
+the same class of check that lives in this framework's own CI as
+`scripts/guard-*.mjs` — ported to run against a single generated app instead of
+the framework's multi-template monorepo layout. It's read-only: doctor never
+edits your code, it only reports.
 
 ## Quick start {#quick-start}
 

package/docs/content/drop-in-agent.mdx

@@ -209,7 +209,7 @@ import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 - **`newTab`** — create a separate chat thread for this prompt.
 - **`background`** — with `newTab`, run without focusing the new thread. The hidden run is tracked in `RunsTray`.
 - **`openSidebar`** — set to `false` for background/silent sends. Default opens the sidebar so the user sees the response.
-- **`type`** — `"content"` (default) keeps the work in the embedded app agent. `"code"` routes to the code-editing frame (for agent-written code changes, see [Frames](/docs/frames)).
+- **`type`** — `"content"` (default) keeps the work in the embedded app agent, which operates through app tools unless its frame is intentionally granted workspace and write tooling. `"code"` routes to a separate code-capable frame (for repository source changes, see [Frames](/docs/frames)).
 
 `sendToAgentChat` returns a stable `tabId` you can use to track the chat run.
 

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/security.mdx

@@ -320,7 +320,7 @@ pnpm action db-check-scoping --require-org  # Also require org_id
 | OAuth tokens (Google, GitHub)      | `oauth_tokens` store via `saveOAuthTokens()`               |
 | Session tokens                     | Automatic (Better Auth handles this)                       |
 
-Per-user/per-org credentials and the vault are encrypted at rest with AES-256-GCM. For a per-user/per-org credential, the key precedence is `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (app-scoped — useful in a multi-app workspace where apps shouldn't share one key) → `SECRETS_ENCRYPTION_KEY` → `BETTER_AUTH_SECRET`; production refuses to start without one of these set. The shared workspace vault (`app_secrets`, meant to decrypt the same in sibling apps) checks `SECRETS_ENCRYPTION_KEY` / `BETTER_AUTH_SECRET` first, then on a hosted workspace deploy falls back further to material derived from `A2A_SECRET`, and only then to the app-scoped key as a last resort. To encrypt any pre-existing plaintext credential rows in place, run `pnpm action db-migrate-encrypt-credentials` (idempotent, non-destructive).
+Per-user/per-org credentials and the vault are encrypted at rest with AES-256-GCM. For a per-user/per-org credential, the key precedence is `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (app-scoped — useful in a multi-app workspace where apps shouldn't share one key) → `SECRETS_ENCRYPTION_KEY` → `BETTER_AUTH_SECRET`; production refuses to start without one of these set. The shared workspace vault (`app_secrets`, meant to decrypt the same in sibling apps) prefers `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy combined `SECRETS_ENCRYPTION_KEY`, then material derived from `A2A_SECRET`, with `BETTER_AUTH_SECRET` and the app-scoped key retained as compatibility candidates. Successful fallback reads compare-and-swap re-encrypt the shared column under the preferred key. During a workspace-key rotation, set `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` to the old value until reads have migrated existing rows. To encrypt any pre-existing plaintext credential rows in place, run `pnpm action db-migrate-encrypt-credentials` (idempotent, non-destructive).
 
 Never store secrets in `settings`, `application_state`, source code, or action responses. Use the credential / vault APIs above — they handle both encryption and per-user scoping.
 
@@ -365,7 +365,7 @@ Google Docs Pub/Sub push notifications don't go through that generic adapter gat
 - [ ] `BETTER_AUTH_SECRET` set to a random 32+ char string (`openssl rand -hex 32`), unless this is a hosted workspace deploy deriving it from `A2A_SECRET`
 - [ ] `OAUTH_STATE_SECRET` set to a separate random 32+ char string (don't reuse `BETTER_AUTH_SECRET`) — see [OAuth State Signing](#oauth-state)
 - [ ] `A2A_SECRET` set on every app that calls or receives A2A traffic — see [A2A Identity Verification](#a2a-identity)
-- [ ] `SECRETS_ENCRYPTION_KEY` set (or rely on the `BETTER_AUTH_SECRET` fallback) — see [Secrets Management](#secrets)
+- [ ] `WORKSPACE_SECRETS_ENCRYPTION_KEY` set consistently for multi-app shared vaults; app-local encryption still has `SECRETS_ENCRYPTION_KEY` / `BETTER_AUTH_SECRET` fallbacks — see [Secrets Management](#secrets)
 - [ ] `AUTH_SKIP_EMAIL_VERIFICATION` is **not** set in production (or set only on QA preview deploys)
 
 ### Webhook secrets (set the ones for integrations you use)

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.5",
+  "version": "0.131.7",
   "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": {
@@ -395,8 +395,8 @@
     "y-protocols": "^1.0.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",
+    "@agent-native/recap-cli": "0.5.1"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",