@agent-native/core 0.131.4 → 0.131.6

package/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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}