@agent-native/core 0.88.0 → 0.90.1

package/docs/content/toolkit-collaboration-ui.mdx

@@ -0,0 +1,48 @@
+---
+title: "Toolkit Collaboration UI"
+description: "Reusable presence, cursor, selection, and recent-edit UI for collaborative Agent-Native apps."
+---
+
+# Toolkit Collaboration UI
+
+`@agent-native/toolkit/collab-ui` contains the presentational collaboration
+pieces that do not own transport or storage:
+
+```tsx
+import {
+  AgentPresenceChip,
+  LiveCursorOverlay,
+  PresenceBar,
+  RecentEditHighlights,
+  RemoteSelectionRings,
+} from "@agent-native/toolkit/collab-ui";
+```
+
+Core still owns the live collaboration runtime: Yjs documents, awareness sync,
+presence hooks, recent edit publication, undo grouping, and server plugins. Use
+core for data and Toolkit for rendering.
+
+```tsx
+import { useCollaborativeDoc, usePresence } from "@agent-native/core/client";
+import { PresenceBar } from "@agent-native/toolkit/collab-ui";
+```
+
+Existing imports from `@agent-native/core/client` still work because core
+re-exports these Toolkit components as compatibility shims.
+
+## Responsibilities {#responsibilities}
+
+Toolkit owns:
+
+- Presence avatars and agent editing chips.
+- Live cursor overlays.
+- Remote selection rings.
+- Recent edit highlight overlays.
+- Display helpers such as collaborator color and display-name derivation.
+
+Core owns:
+
+- Yjs document creation and sync.
+- Awareness polling and SSE fast-path transport.
+- Collaboration server plugins and actions.
+- Recent edit publication and collection from awareness.

package/docs/content/toolkit-sharing-ui.mdx

@@ -0,0 +1,33 @@
+---
+title: "Toolkit Sharing UI"
+description: "Reusable sharing display components with core-owned sharing runtime compatibility."
+---
+
+# Toolkit Sharing UI
+
+`@agent-native/toolkit/sharing` contains sharing UI that does not perform access
+checks or mutations. Today it exports `VisibilityBadge`:
+
+```tsx
+import { VisibilityBadge } from "@agent-native/toolkit/sharing";
+```
+
+Core still owns the sharing runtime: share tables, resource registration, access
+filters, visibility changes, invites, roles, and private access tokens for
+agent-readable public surfaces.
+
+Use core wrappers when a component needs to call sharing actions:
+
+```tsx
+import { ShareButton, ShareDialog } from "@agent-native/core/client";
+```
+
+Those imports remain compatible. As more sharing UI is split into presentational
+base components, core wrappers should keep doing the runtime work and pass data
+and callbacks into Toolkit-owned UI.
+
+## Boundary {#boundary}
+
+Toolkit sharing UI can render badges, rows, base dialogs, and role pickers when
+data and callbacks are injected. Core sharing code should own SQL, permissions,
+request context, org membership lookups, and share-token minting.

package/docs/content/toolkit-shell-hooks.mdx

@@ -0,0 +1,27 @@
+---
+title: "Toolkit Shell & Hooks"
+description: "Shared shell helpers and hooks that templates can compose through local adapters."
+---
+
+# Toolkit Shell & Hooks
+
+Toolkit includes small shell helpers and hooks that are useful across apps:
+
+```tsx
+import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
+import { useIsMobile } from "@agent-native/toolkit/hooks/use-mobile";
+import { useToast } from "@agent-native/toolkit/hooks/use-toast";
+```
+
+Apps can wrap these through local adapters when they want the same customization
+point as UI primitives:
+
+```tsx
+export * from "@agent-native/toolkit/hooks/use-mobile";
+```
+
+Keep shell helpers in Toolkit when they are reusable and do not own app data.
+Keep app-specific navigation, command entries, and domain state in the template.
+
+Core remains responsible for framework-wide shell behavior such as app providers,
+agent chat, app state, auth, and runtime sync.

package/docs/content/toolkit-ui.mdx

@@ -0,0 +1,69 @@
+---
+title: "Toolkit UI Primitives"
+description: "How to use @agent-native/toolkit UI primitives without locking apps out of customization."
+---
+
+# Toolkit UI Primitives
+
+Toolkit UI primitives live under `@agent-native/toolkit/ui/*`. They are the
+shared shadcn-style building blocks used by templates and reusable kits.
+
+Reusable package code can import them directly:
+
+```tsx
+import { Button } from "@agent-native/toolkit/ui/button";
+import { Dialog, DialogContent } from "@agent-native/toolkit/ui/dialog";
+```
+
+Apps that render Toolkit UI must also import the Toolkit stylesheet from
+`app/global.css` so Tailwind generates classes used only inside package
+components, such as dropdown and popover z-index and animation utilities:
+
+```css
+@import "tailwindcss";
+@import "@agent-native/core/styles/agent-native.css";
+@import "@agent-native/toolkit/styles.css";
+```
+
+Template app code should usually import the app-local adapter instead:
+
+```tsx
+import { Button } from "@/components/ui/button";
+```
+
+The adapter starts as a one-line re-export:
+
+```tsx
+export * from "@agent-native/toolkit/ui/button";
+```
+
+When an app wants its own button, it replaces that one adapter file. The rest of
+the app keeps importing `@/components/ui/button`.
+
+## Provider Overrides {#provider-overrides}
+
+Reusable Toolkit UI should read overridable primitives from `ToolkitProvider`
+instead of hard-coding a visual system. Templates wire their local `Button` into
+that provider so future kits automatically pick up app customization.
+
+```tsx
+import { ToolkitProvider } from "@agent-native/toolkit/provider";
+
+import { Button } from "@/components/ui/button";
+
+export function AppToolkitProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <ToolkitProvider components={{ Button }}>{children}</ToolkitProvider>;
+}
+```
+
+If an app override wants to keep Toolkit's default button styling as its base,
+render `ButtonBase` from `@agent-native/toolkit/ui/button`. Do not render
+Toolkit's `Button` from inside the override; `ButtonBase` is the explicit escape
+hatch, while Toolkit's recursion guard is only a fallback.
+
+Core keeps old imports working with re-export shims, but new app UI should flow
+through local adapters.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.88.0",
+  "version": "0.90.1",
   "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": {
@@ -162,6 +162,10 @@
     "./provider-api/actions/list-staged-datasets": "./dist/provider-api/actions/list-staged-datasets.js",
     "./provider-api/actions/delete-staged-dataset": "./dist/provider-api/actions/delete-staged-dataset.js",
     "./provider-api/actions/github-repo-files": "./dist/provider-api/actions/github-repo-files.js",
+    "./data-programs": {
+      "types": "./dist/data-programs/index.d.ts",
+      "default": "./dist/data-programs/index.js"
+    },
     "./local-artifacts": {
       "types": "./dist/local-artifacts/index.d.ts",
       "default": "./dist/local-artifacts/index.js"
@@ -276,7 +280,7 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/toolkit": "0.2.0"
+    "@agent-native/toolkit": "0.4.1"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/default/.agents/skills/actions/SKILL.md

@@ -161,6 +161,18 @@ to find likely URLs, `web-request` or `provider-api-docs` with clean
 `webFetch()` when you need to grep, aggregate, or compare many pages before
 returning a small result.
 
+For LONG compute, `run-code` supports durable background executions: pass
+`background: true` and the code is enqueued to a `sandbox_executions` row and
+executed out-of-band with a generous budget (default 10 min), surviving the
+hosted agent run's ~40s soft timeout. The call returns
+`{ executionId, status: "queued" }` immediately with polling guidance; check
+progress with `run-code` `{ executionId }` (or the `get-code-execution` tool
+where registered) — results persist after completion. Use background for big
+cross-source joins, multi-page provider sweeps, and heavy analysis scripts;
+keep quick scripts in the default foreground mode. Agents should continue
+other work between polls, and on `failed`/`timed_out` split the computation or
+persist intermediate progress with `workspaceWrite` and re-run.
+
 ### The `http` Option
 
 Controls how the action is exposed as an HTTP endpoint:
@@ -205,6 +217,49 @@ run: async (args) => {
 }
 ```
 
+### Returning Images the Agent Can See (`_agentImages`)
+
+An action's return object may include the well-known optional field
+`_agentImages` to attach vision images (screenshots, chart previews, rendered
+designs) to the tool result. The agent literally sees them — enabling visual
+self-review loops — while the field itself is stripped from the JSON text the
+model reads.
+
+```ts
+run: async ({ dashboardId }) => {
+  const shot = await renderDashboardPng(dashboardId); // Buffer
+  return {
+    dashboardId,
+    panelCount: 6,
+    _agentImages: [
+      // Either a public https URL (preferred — the provider fetches it)…
+      { url: "https://cdn.example.com/previews/dash-1.png", label: "overview" },
+      // …or base64 without a data: prefix (mediaType required; a full
+      // data:image/png;base64,… URL in `data` is also accepted and parsed).
+      { data: shot.toString("base64"), mediaType: "image/png" },
+    ],
+  };
+},
+```
+
+Rules and limits:
+
+- Shape: `Array<{ url?: string; data?: string; mediaType?: string; label?: string }>`.
+  Each entry needs `url` (https only) **or** `data`. Supported media types:
+  `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
+- Caps: max **4 images** per result; max **~2MB of base64** per image.
+  Over-cap or invalid entries never fail the call — they become text notes in
+  the result telling the model what was dropped and why.
+- Persistence: the run ledger stores only the string result plus compact
+  `[image: …]` notes (URLs verbatim; base64 as a byte-count placeholder) —
+  never the payload. Images are re-attached only for the live turn; replayed
+  history is text-only, so prefer stable `url` images the model can re-request.
+- Engine support: native Anthropic and vision-capable AI-SDK providers
+  (anthropic, openai, google, openrouter) receive real image blocks; other
+  paths (Builder gateway, non-vision providers) degrade to the text notes.
+- External MCP tools need no changes — standard MCP `image` content parts are
+  converted automatically under the same caps.
+
 ### Validating Return Values (`outputSchema`)
 
 `schema` validates inputs; `outputSchema` validates what the action **returns**. Pass any Standard Schema-compatible schema (Zod, Valibot, ArkType) and the framework validates the result _after_ `run()` resolves — input validated before `run`, output after.

package/src/templates/default/AGENTS.md

@@ -121,22 +121,19 @@ capability is missing, add or extend a `defineAction` so both the agent and UI
 share the same operation. Do not create `/api/*` routes that only call,
 repackage, or proxy an action.
 
-| Action        | Args                                                                           | Purpose                                                                                 |
-| ------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
-| `view-screen` |                                                                                | See current UI state                                                                    |
-| `navigate`    | `--view <name>` or `--path <url>`                                              | Navigate the UI                                                                         |
-| `hello`       | `[--name <name>]`                                                              | Example script                                                                          |
-| `db-schema`   |                                                                                | Show all tables, columns, types                                                         |
-| `db-query`    | `--sql "SELECT ..."`                                                           | Run a SELECT query                                                                      |
-| `db-exec`     | `--sql "UPDATE ..."`                                                           | Last-resort ad-hoc maintenance; prefer domain actions and Drizzle code for product work |
-| `db-patch`    | `--table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` | Surgical search/replace on a large text column — sends a diff instead of the full value |
-
-**For one-off maintenance, pick the right SQL tool:**
+| Action        | Args                              | Purpose                         |
+| ------------- | --------------------------------- | ------------------------------- |
+| `view-screen` |                                   | See current UI state            |
+| `navigate`    | `--view <name>` or `--path <url>` | Navigate the UI                 |
+| `hello`       | `[--name <name>]`                 | Example script                  |
+| `db-schema`   |                                   | Show all tables, columns, types |
+| `db-query`    | `--sql "SELECT ..."`              | Run a SELECT query              |
+
+**For data changes, pick the right surface:**
 
 - Use domain actions first. They validate input, enforce access, and refresh the UI.
-- Use `db-exec UPDATE` only when no domain action exists and you need a small ad-hoc change.
-- Use `db-patch` when you only need to tweak a small slice of a **large** text/JSON column (documents, slide HTML, dashboard/form JSON). It saves tokens by sending `{find, replace}` instead of re-transmitting the whole column. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` for replace-every-occurrence.
-- If a template-specific action exists (e.g. `edit-document`, `update-slide`), prefer it — those also push live updates to any open collaborative editor.
+- Use `db-query` / `db-schema` for read-only inspection.
+- Raw write SQL (`db-exec` / `db-patch`) is not part of the default agent surface. If this app explicitly opts into `databaseTools: "write"`, use those tools only for deliberate maintenance when no domain action exists.
 - **Database admin (dev only):** in development, `db-admin-query` / `db-admin-mutate` / `db-admin-rows` / `db-admin-tables` / `db-admin-schema` give **unscoped, full-database** access to ANY table — including framework tables and tables without `owner_email`/`org_id`. Prefer these over `db-exec`/`db-query` for database-admin work and for any non-owner-scoped table: `db-exec`/`db-query` auto-scope to the current user and return **0 rows** on unscoped tables. These mirror the in-app Database admin UI, so prompts and the UI do the same thing.
 
 ## Skills

package/src/templates/default/actions/navigate.spec.ts

@@ -0,0 +1,53 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const appState = vi.hoisted(() => ({
+  writeAppState: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/action", () => ({
+  defineAction: (definition: unknown) => definition,
+}));
+vi.mock("@agent-native/core/application-state", () => appState);
+
+const { default: navigate } = await import("./navigate.js");
+
+describe("navigate action (default template)", () => {
+  beforeEach(() => {
+    appState.writeAppState.mockReset();
+  });
+
+  it("throws when neither --view nor --path is provided", async () => {
+    // Throwing (not returning an "Error: ..." string) lets the model's error
+    // handling distinguish failure from success, matching every other action.
+    await expect(navigate.run({})).rejects.toThrow(
+      "At least --view or --path is required.",
+    );
+    expect(appState.writeAppState).not.toHaveBeenCalled();
+  });
+
+  it("writes a navigate command for a view", async () => {
+    const result = await navigate.run({ view: "settings" });
+
+    expect(appState.writeAppState).toHaveBeenCalledWith(
+      "navigate",
+      expect.objectContaining({
+        view: "settings",
+        _writeId: expect.any(String),
+      }),
+    );
+    expect(result).toBe("Navigating to settings");
+  });
+
+  it("writes a navigate command for a path", async () => {
+    const result = await navigate.run({ path: "/inbox" });
+
+    expect(appState.writeAppState).toHaveBeenCalledWith(
+      "navigate",
+      expect.objectContaining({
+        path: "/inbox",
+        _writeId: expect.any(String),
+      }),
+    );
+    expect(result).toBe("Navigating to /inbox");
+  });
+});

package/src/templates/default/actions/navigate.ts

@@ -12,7 +12,7 @@ export default defineAction({
   http: false,
   run: async (args) => {
     if (!args.view && !args.path) {
-      return "Error: At least --view or --path is required.";
+      throw new Error("At least --view or --path is required.");
     }
     const nav: Record<string, string> = {};
     if (args.view) nav.view = args.view;

package/src/templates/default/app/i18n/ar-SA.ts

@@ -303,7 +303,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "ماذا يجب أن تفعل؟",
     createPlaceholder: "قائمة المهام، لوحة تحكم API، آلة حاسبة...",
-    backToApp: "العودة إلى التطبيق",
     title: "الإضافات",
     hiddenShown: "يظهر الإخفاء",
     showHidden: "إظهار المخفية",

package/src/templates/default/app/i18n/de-DE.ts

@@ -295,7 +295,6 @@ const messages = {
     whatShouldItDo: "Was soll es tun?",
     createPlaceholder:
       "Eine Aufgabenliste, ein API-Dashboard, ein Taschenrechner ...",
-    backToApp: "Zurück zur App",
     title: "Erweiterungen",
     hiddenShown: "Versteckt angezeigt",
     showHidden: "Ausgeblendete anzeigen",

package/src/templates/default/app/i18n/en-US.ts

@@ -288,7 +288,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "What should it do?",
     createPlaceholder: "A todo list, API dashboard, calculator...",
-    backToApp: "Back to app",
     title: "Extensions",
     hiddenShown: "Hiding shown",
     showHidden: "Show hidden",

package/src/templates/default/app/i18n/es-ES.ts

@@ -300,7 +300,6 @@ const messages = {
     whatShouldItDo: "¿Qué debería hacer?",
     createPlaceholder:
       "Una lista de tareas pendientes, panel API, calculadora...",
-    backToApp: "Volver a la aplicación",
     title: "Extensiones",
     hiddenShown: "Ocultando mostrado",
     showHidden: "Mostrar ocultos",

package/src/templates/default/app/i18n/fr-FR.ts

@@ -299,7 +299,6 @@ const messages = {
     whatShouldItDo: "Que devrait-il faire ?",
     createPlaceholder:
       "Une liste de tâches, un tableau de bord API, une calculatrice...",
-    backToApp: "Retour à l'application",
     title: "Rallonges",
     hiddenShown: "Masquer affiché",
     showHidden: "Afficher les éléments masqués",

package/src/templates/default/app/i18n/hi-IN.ts

@@ -284,7 +284,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "इसे क्या करना चाहिए?",
     createPlaceholder: "एक कार्य सूची, एपीआई डैशबोर्ड, कैलकुलेटर...",
-    backToApp: "ऐप पर वापस जाएं",
     title: "एक्सटेंशन",
     hiddenShown: "छिपाव दिखाया गया",
     showHidden: "छिपे हुए दिखाएं",

package/src/templates/default/app/i18n/ja-JP.ts

@@ -287,7 +287,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "それは何をすべきでしょうか？",
     createPlaceholder: "ToDo リスト、API ダッシュボード、電卓...",
-    backToApp: "アプリに戻る",
     title: "拡張機能",
     hiddenShown: "非表示を表示",
     showHidden: "非表示を表示",

package/src/templates/default/app/i18n/ko-KR.ts

@@ -283,7 +283,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "무엇을 해야 합니까?",
     createPlaceholder: "할 일 목록, API 대시보드, 계산기...",
-    backToApp: "앱으로 돌아가기",
     title: "확장",
     hiddenShown: "숨김 표시됨",
     showHidden: "숨김 항목 표시",

package/src/templates/default/app/i18n/pt-BR.ts

@@ -298,7 +298,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "O que deveria fazer?",
     createPlaceholder: "Uma lista de tarefas, painel de API, calculadora...",
-    backToApp: "Voltar ao aplicativo",
     title: "Extensões",
     hiddenShown: "Ocultando mostrado",
     showHidden: "Mostrar ocultos",

package/src/templates/default/app/i18n/zh-CN.ts

@@ -276,7 +276,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "它应该做什么？",
     createPlaceholder: "待办事项列表、API 仪表板、计算器...",
-    backToApp: "返回应用程序",
     title: "扩展",
     hiddenShown: "显示隐藏",
     showHidden: "显示隐藏项",

package/src/templates/default/app/i18n/zh-TW.ts

@@ -276,7 +276,6 @@ const messages = {
       "建立一個適合「{{slotId}}」插槽的新小工具。我接著會描述它應該做什麼。",
     whatShouldItDo: "它應該做什麼？",
     createPlaceholder: "待辦事項清單、API 儀表板、計算器...",
-    backToApp: "返回應用程式",
     title: "擴充功能",
     hiddenShown: "顯示隱藏",
     showHidden: "顯示隱藏項",

package/src/templates/default/app/routes/settings.tsx

@@ -1,6 +1,7 @@
 import {
   LanguagePicker,
-  openAgentSettings,
+  SettingsTabsPage,
+  useAgentSettingsTabs,
   useT,
 } from "@agent-native/core/client";
 import { Link } from "react-router";
@@ -11,10 +12,11 @@ export function meta() {
 
 export default function SettingsPage() {
   const t = useT();
+  const agentSettingsTabs = useAgentSettingsTabs();
 
   return (
     <main className="min-h-screen bg-background px-6 py-10">
-      <div className="mx-auto w-full max-w-2xl space-y-6">
+      <div className="mx-auto w-full max-w-5xl space-y-6">
         <div className="space-y-2">
           <Link
             to="/"
@@ -30,37 +32,24 @@ export default function SettingsPage() {
           </p>
         </div>
 
-        <section className="rounded-lg border border-border/50 bg-card px-4 py-4">
-          <div className="space-y-1">
-            <h2 className="text-[15px] font-semibold text-foreground">
-              {t("settings.languageTitle")}
-            </h2>
-            <p className="text-[13px] leading-relaxed text-muted-foreground">
-              {t("settings.languageDescription")}
-            </p>
-          </div>
-          <div className="mt-4 max-w-xs">
-            <LanguagePicker label={t("settings.languageLabel")} />
-          </div>
-        </section>
-
-        <section className="rounded-lg border border-border/50 bg-card px-4 py-4">
-          <div className="space-y-1">
-            <h2 className="text-[15px] font-semibold text-foreground">
-              {t("settings.agentTitle")}
-            </h2>
-            <p className="text-[13px] leading-relaxed text-muted-foreground">
-              {t("settings.agentDescription")}
-            </p>
-          </div>
-          <button
-            type="button"
-            className="mt-4 rounded-md border border-border bg-background px-3 py-2 text-[13px] font-medium text-foreground transition-colors hover:bg-accent/50"
-            onClick={() => openAgentSettings()}
-          >
-            {t("settings.openAgentSettings")}
-          </button>
-        </section>
+        <SettingsTabsPage
+          extraTabs={agentSettingsTabs}
+          general={
+            <section className="mx-auto w-full max-w-2xl rounded-lg border border-border/50 bg-card px-4 py-4">
+              <div className="space-y-1">
+                <h2 className="text-[15px] font-semibold text-foreground">
+                  {t("settings.languageTitle")}
+                </h2>
+                <p className="text-[13px] leading-relaxed text-muted-foreground">
+                  {t("settings.languageDescription")}
+                </p>
+              </div>
+              <div className="mt-4 max-w-xs">
+                <LanguagePicker label={t("settings.languageLabel")} />
+              </div>
+            </section>
+          }
+        />
       </div>
     </main>
   );

package/src/templates/headless/.agents/skills/agent-native-docs/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: agent-native-docs
 description: >-
-  How to find version-matched Agent Native framework docs bundled in
+  How to find version-matched Agent Native framework docs and source bundled in
   node_modules. Use before implementing or answering questions about
-  @agent-native/core APIs, generated apps, workspaces, or advanced features.
+  @agent-native/core APIs, generated apps, workspaces, templates, or advanced
+  features.
+scope: dev
 metadata:
   internal: true
 ---
@@ -13,13 +15,17 @@ metadata:
 ## Rule
 
 Before implementing or explaining non-trivial Agent Native behavior, read the
-version-matched docs installed with `@agent-native/core`.
+version-matched docs installed with `@agent-native/core`. When examples,
+imports, or implementation details matter, inspect the packaged source corpus
+too.
 
 ## Why
 
 Generated apps and workspaces may be on a different framework version than the
 public docs or model memory. The installed package is the source that matches
-the app in front of you.
+the app in front of you. It also includes a source-only corpus of core and
+first-party templates so agents can replicate current best-practice patterns
+without needing the framework monorepo checkout.
 
 ## How
 
@@ -29,19 +35,26 @@ From a generated app directory:
 pnpm action docs-search --query "<feature>"
 pnpm action docs-search --slug <slug>
 pnpm action docs-search --list
+pnpm action source-search --query "<pattern>"
+pnpm action source-search --path templates/plan/AGENTS.md
+pnpm action source-search --list
 ```
 
 The headless `pnpm agent` loop and built-in app agent also expose a read-only
-`docs-search` tool with the same `query`, `slug`, and `list` options.
+`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
+read-only `source-search` tool with `query`, `path`, and `list`.
 
-If the action runner is unavailable, search the package docs directly:
+If the action runner is unavailable, search the package directly:
 
 ```bash
 rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ```
 
 Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
-under `node_modules/@agent-native/core/docs/content/`.
+under `node_modules/@agent-native/core/docs/content/`. For source examples,
+read files under `node_modules/@agent-native/core/corpus/core/` or
+`node_modules/@agent-native/core/corpus/templates/`.
 
 ## Useful Slugs
 

package/src/templates/headless/AGENTS.md

@@ -45,12 +45,15 @@ root to refresh framework-provided `.agents/skills` and repair `CLAUDE.md` /
 
 ## Actions
 
-| Action      | Args              | Purpose                 |
-| ----------- | ----------------- | ----------------------- |
-| `hello`     | `[--name <name>]` | Return a greeting       |
-| `db-schema` |                   | Show SQL schema         |
-| `db-query`  | `--sql "SELECT"`  | Run a scoped SELECT     |
-| `db-exec`   | `--sql "UPDATE"`  | Last-resort maintenance |
+| Action      | Args              | Purpose             |
+| ----------- | ----------------- | ------------------- |
+| `hello`     | `[--name <name>]` | Return a greeting   |
+| `db-schema` |                   | Show SQL schema     |
+| `db-query`  | `--sql "SELECT"`  | Run a scoped SELECT |
+
+Raw SQL writes are not exposed by default. Add or update a typed action for app
+data writes; opt into `databaseTools: "write"` only for deliberate maintenance
+surfaces.
 
 Run actions from this app root: