@agent-native/core 0.131.4 → 0.131.6

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,14 @@ 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 `SECRETS_ENCRYPTION_KEY` is unset, shared vault ciphertext uses a purpose-derived key from this value, so rotating it also rotates the vault key.                                                    |
+| `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. Shared vault reads fall back to purpose-derived `A2A_SECRET`, then legacy Better Auth and app-scoped keys. Before rotating A2A, add this key everywhere and read/migrate every existing row while the old A2A material remains available. |
 
 ### Auth & Identity {#env-auth}
 
@@ -628,13 +628,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/docs-components.mdx

@@ -0,0 +1,491 @@
+---
+title: "Docs components"
+description: "Reference for every MDX component available in the Agent Native docs, with live rendered examples and copy-paste syntax."
+---
+
+# Docs components
+
+The docs site renders standard Markdown plus a set of MDX block components for
+richer content. Each section below shows a live rendered example followed by
+the exact MDX syntax that produced it.
+
+---
+
+## Callout
+
+<Callout tone="info">
+
+This is an `info` callout. Use it for background context or neutral notes. You can use **bold**, `inline code`, and [links](/docs/getting-started) inside.
+
+</Callout>
+
+<Callout tone="warning">
+
+This is a `warning` callout. Use it for potential data loss, breaking changes, or hard-to-reverse steps. For example: restart `pnpm dev` after adding a new route file — the router only picks up files present at startup.
+
+</Callout>
+
+<Callout tone="success">
+
+This is a `success` callout. Use it for the recommended path or to confirm a working approach.
+
+</Callout>
+
+<Callout tone="risk">
+
+This is a `risk` callout. Use it for security implications or production caveats.
+
+</Callout>
+
+<Callout tone="decision">
+
+This is a `decision` callout. Use it to surface a deliberate tradeoff the reader should understand.
+
+</Callout>
+
+```mdx
+<Callout tone="info">
+
+This is an `info` callout. Use it for background context or neutral notes. You can use **bold**, `inline code`, and [links](/docs/getting-started) inside.
+
+</Callout>
+
+<Callout tone="warning">
+
+This is a `warning` callout. Use it for potential data loss, breaking changes, or hard-to-reverse steps. For example: restart `pnpm dev` after adding a new route file — the router only picks up files present at startup.
+
+</Callout>
+
+<Callout tone="success">
+
+This is a `success` callout. Use it for the recommended path or to confirm a working approach.
+
+</Callout>
+
+<Callout tone="risk">
+
+This is a `risk` callout. Use it for security implications or production caveats.
+
+</Callout>
+
+<Callout tone="decision">
+
+This is a `decision` callout. Use it to surface a deliberate tradeoff the reader should understand.
+
+</Callout>
+```
+
+| Tone       | When to use                                                  |
+| ---------- | ------------------------------------------------------------ |
+| `info`     | Background context, neutral notes                            |
+| `warning`  | Potential data loss, breaking changes, hard-to-reverse steps |
+| `success`  | Recommended option, confirmed working path                   |
+| `risk`     | Security implications, production caveats                    |
+| `decision` | Deliberate tradeoffs the reader should understand            |
+
+Leave a blank line between the opening tag and the body, and another before the closing tag.
+
+---
+
+## Steps
+
+<Steps>
+
+### Install dependencies
+
+Run the following inside your project directory:
+
+```bash
+pnpm install
+```
+
+### Start the dev server
+
+```bash
+pnpm dev
+```
+
+Open `http://localhost:3000`. The app is ready when **VITE ready** appears in the terminal.
+
+### Sign in
+
+The first run shows a login screen. Use any credentials — local development does not send email.
+
+</Steps>
+
+````mdx
+<Steps>
+
+### Install dependencies
+
+Run the following inside your project directory:
+
+```bash
+pnpm install
+```
+
+### Start the dev server
+
+```bash
+pnpm dev
+```
+
+Open `http://localhost:3000`. The app is ready when **VITE ready** appears in the terminal.
+
+### Sign in
+
+The first run shows a login screen. Use any credentials — local development does not send email.
+
+</Steps>
+````
+
+Each step is a `###` heading followed by the body content. Steps work best for 3–8 items. For 2 items a numbered list is fine. For longer procedures, split into multiple `<Steps>` blocks with a prose bridge between them.
+
+---
+
+## Cards
+
+<Cards>
+
+### [Actions](/docs/actions)
+
+Typed operations callable from the agent, UI, CLI, and HTTP. Define once, call from anywhere.
+
+### [Database](/docs/database)
+
+SQL persistence with automatic migrations. SQLite locally, Postgres/Turso in production.
+
+### [Agent Surfaces](/docs/agent-surfaces)
+
+Configure where the agent appears: full-page chat, sidebar panel, or embedded in a route.
+
+### Skills
+
+Plain-text instruction files that give the agent domain knowledge and task-specific behavior without code changes.
+
+</Cards>
+
+```mdx
+<Cards>
+
+### [Actions](/docs/actions)
+
+Typed operations callable from the agent, UI, CLI, and HTTP. Define once, call from anywhere.
+
+### [Database](/docs/database)
+
+SQL persistence with automatic migrations. SQLite locally, Postgres/Turso in production.
+
+### [Agent Surfaces](/docs/agent-surfaces)
+
+Configure where the agent appears: full-page chat, sidebar panel, or embedded in a route.
+
+### Skills
+
+Plain-text instruction files that give the agent domain knowledge and task-specific behavior without code changes.
+
+</Cards>
+```
+
+Each card is a `###` heading (optionally linked) followed by the description. Cards without a link render as plain info boxes with no hover state or arrow.
+
+---
+
+## Comparison
+
+<Comparison>
+
+### Before
+
+Every feature needs a separate API endpoint, a separate React query, and manual wiring between the AI response and UI state.
+
+### After
+
+Define one action. The agent calls it as a tool, the UI calls it through a React hook, and both read the same validated output.
+
+</Comparison>
+
+```mdx
+<Comparison>
+
+### Before
+
+Every feature needs a separate API endpoint, a separate React query, and manual wiring between the AI response and UI state.
+
+### After
+
+Define one action. The agent calls it as a tool, the UI calls it through a React hook, and both read the same validated output.
+
+</Comparison>
+```
+
+Add more `###` sections to get 3 or 4 columns (max 4). The red/green label accent only applies to headings that exactly match `Before`, `Old`, `Without` (red) or `After`, `New`, `With` (green).
+
+---
+
+## kbd — keyboard shortcut
+
+Press [[⌘K]] to open the command palette. Save with [[Ctrl+S]] before running the dev server. Navigate fields with [[Tab]] and [[Shift+Tab]].
+
+```mdx
+Press [[⌘K]] to open the command palette. Save with [[Ctrl+S]] before running the dev server. Navigate fields with [[Tab]] and [[Shift+Tab]].
+```
+
+Double brackets around the key sequence; no MDX component needed. Works anywhere in regular Markdown paragraphs.
+
+---
+
+## Mermaid diagram
+
+```mermaid
+graph LR
+  A[defineAction] --> B[Agent calls it as a tool]
+  A --> C[UI calls it via useActionQuery]
+  A --> D[CLI calls it directly]
+  A --> E[HTTP API]
+```
+
+````mdx
+```mermaid
+graph LR
+  A[defineAction] --> B[Agent calls it as a tool]
+  A --> C[UI calls it via useActionQuery]
+  A --> D[CLI calls it directly]
+  A --> E[HTTP API]
+```
+````
+
+Use a fenced code block with the `mermaid` language tag. Mermaid supports flowcharts (`graph`), sequence diagrams (`sequenceDiagram`), entity-relationship diagrams (`erDiagram`), and more. See [mermaid.js.org](https://mermaid.js.org/intro/) for the full syntax reference.
+
+---
+
+## FileTree
+
+<FileTree
+  id="docs-components-filetree"
+  entries={[
+    {
+      path: "actions/analyze-text.ts",
+      change: "added",
+      note: "New action — callable from agent, UI, and CLI",
+    },
+    { path: "actions/list-text-analyses.ts", change: "added" },
+    { path: "app/routes/analyses.tsx", change: "modified" },
+    {
+      path: "app/config/nav.ts",
+      change: "modified",
+      note: "Add the new route to the sidebar nav",
+    },
+    { path: "db/migrations/001_analyses.sql" },
+  ]}
+/>
+
+```mdx
+<FileTree
+  id="docs-components-filetree"
+  entries={[
+    {
+      path: "actions/analyze-text.ts",
+      change: "added",
+      note: "New action — callable from agent, UI, and CLI",
+    },
+    { path: "actions/list-text-analyses.ts", change: "added" },
+    { path: "app/routes/analyses.tsx", change: "modified" },
+    {
+      path: "app/config/nav.ts",
+      change: "modified",
+      note: "Add the new route to the sidebar nav",
+    },
+    { path: "db/migrations/001_analyses.sql" },
+  ]}
+/>
+```
+
+FileTree is **self-closing** (`/>`). It does not accept Markdown children — if you use open/close tags with content inside you will get a parse error.
+
+Each entry in `entries` is an object with a `path` key (slash-delimited) and optional fields:
+
+| Field      | Values                                                  | Effect                               |
+| ---------- | ------------------------------------------------------- | ------------------------------------ |
+| `change`   | `"added"` \| `"modified"` \| `"removed"` \| `"renamed"` | Colored badge on the row             |
+| `note`     | any string                                              | Expandable annotation shown on hover |
+| `snippet`  | code string                                             | Expandable code preview              |
+| `language` | e.g. `"ts"`                                             | Syntax highlighting for the snippet  |
+
+---
+
+## Tabs
+
+<TabsBlock
+  id="docs-components-tabs"
+  tabs={[
+    {
+      id: "pnpm",
+      label: "pnpm",
+      blocks: [
+        {
+          type: "code",
+          id: "pnpm-install",
+          data: { code: "pnpm install", language: "bash" },
+        },
+      ],
+    },
+    {
+      id: "npm",
+      label: "npm",
+      blocks: [
+        {
+          type: "code",
+          id: "npm-install",
+          data: { code: "npm install", language: "bash" },
+        },
+      ],
+    },
+    {
+      id: "yarn",
+      label: "yarn",
+      blocks: [
+        {
+          type: "code",
+          id: "yarn-install",
+          data: { code: "yarn install", language: "bash" },
+        },
+      ],
+    },
+  ]}
+/>
+
+```mdx
+<TabsBlock
+  id="docs-components-tabs"
+  tabs={[
+    {
+      id: "pnpm",
+      label: "pnpm",
+      blocks: [
+        {
+          type: "code",
+          id: "pnpm-install",
+          data: { code: "pnpm install", language: "bash" },
+        },
+      ],
+    },
+    {
+      id: "npm",
+      label: "npm",
+      blocks: [
+        {
+          type: "code",
+          id: "npm-install",
+          data: { code: "npm install", language: "bash" },
+        },
+      ],
+    },
+    {
+      id: "yarn",
+      label: "yarn",
+      blocks: [
+        {
+          type: "code",
+          id: "yarn-install",
+          data: { code: "yarn install", language: "bash" },
+        },
+      ],
+    },
+  ]}
+/>
+```
+
+`TabsBlock` is self-closing. The entire structure is one JSON `tabs` attribute. Each tab's content is a `blocks` array where each item is a block object with `type`, `id`, and `data` matching that block's schema. Tabs works best for short parallel code snippets (one code block per tab). For richer multi-block content per tab, use a visual editor rather than hand-authoring the JSON.
+
+---
+
+## Columns
+
+<Columns
+  id="docs-components-columns"
+  columns={[
+    {
+      id: "col-manual",
+      label: "Manual approach",
+      blocks: [
+        {
+          type: "code",
+          id: "manual-code",
+          data: {
+            code: "const res = await fetch('/api/analyses')\nconst data = await res.json()",
+            language: "ts",
+          },
+        },
+      ],
+    },
+    {
+      id: "col-actions",
+      label: "With actions",
+      blocks: [
+        {
+          type: "code",
+          id: "action-code",
+          data: {
+            code: "const { data } = useActionQuery('list-text-analyses', {})",
+            language: "ts",
+          },
+        },
+      ],
+    },
+  ]}
+/>
+
+```mdx
+<Columns
+  id="docs-components-columns"
+  columns={[
+    {
+      id: "col-manual",
+      label: "Manual approach",
+      blocks: [
+        {
+          type: "code",
+          id: "manual-code",
+          data: {
+            code: "const res = await fetch('/api/analyses')\nconst data = await res.json()",
+            language: "ts",
+          },
+        },
+      ],
+    },
+    {
+      id: "col-actions",
+      label: "With actions",
+      blocks: [
+        {
+          type: "code",
+          id: "action-code",
+          data: {
+            code: "const { data } = useActionQuery('list-text-analyses', {})",
+            language: "ts",
+          },
+        },
+      ],
+    },
+  ]}
+/>
+```
+
+Like `TabsBlock`, `Columns` is self-closing with a single JSON `columns` attribute. Each column has an optional `label` header and a `blocks` array. For comparing prose rather than code, `Comparison` is easier to hand-author.
+
+---
+
+## When to use which component
+
+| Situation                                 | Component                            |
+| ----------------------------------------- | ------------------------------------ |
+| Reader must not miss something            | `Callout` (warning / info / success) |
+| Sequential procedure with titled steps    | `Steps`                              |
+| Navigation or feature overview grid       | `Cards`                              |
+| Before vs. after, old vs. new (prose)     | `Comparison`                         |
+| Same task in multiple tools or frameworks | `Tabs`                               |
+| Side-by-side code (labeled columns)       | `Columns`                            |
+| Project directory structure               | `FileTree`                           |
+| Inline keyboard shortcut                  | `[[Key]]`                            |
+| Architecture or flow diagram              | Mermaid fence                        |

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.