@agent-native/core 0.37.2 → 0.38.0

package/docs/content/actions.md

@@ -70,6 +70,46 @@ export default defineAction({
 - **`readOnly: true`** — explicitly skip the poll-refresh even for POST actions that don't mutate.
 - **`parallelSafe: true`** — allow a mutating action to run concurrently with other same-turn tool calls. Only set this when the action is internally concurrency-safe and order-independent; mutating actions serialize by default.
 
+### Keep the action surface small {#small-surface}
+
+Every action the agent can see is a tool in the model's context window, and a long, overlapping tool list degrades the model's tool-selection quality. Design the action surface like an API you maintain, not one action per UI affordance:
+
+- Prefer **one CRUD-style `update`** that takes a patch of optional fields over N per-field actions (`update-name`, `update-order`, `update-color`, …). The caller sends only what changed.
+- Before adding a new read action per query/filter, reach for a generic escape hatch: the [provider API trio](/docs/template-dispatch) (`provider-api-catalog` / `provider-api-docs` / `provider-api-request`) for provider data, or the dev `db-query` tool for app data.
+- Mark UI-only or programmatic actions [`agentTool: false`](#agent-tool) so they stay frontend/HTTP-callable without spending a slot in the model's tool list.
+- Delete or hide actions the UI no longer uses instead of leaving them exposed to the model.
+
+A repo-level advisory helper, `node scripts/audit-template-actions.mjs [template ...]` (alias `pnpm actions:audit`), statically scans a template's `actions/` and flags likely UI-dead actions and redundant per-field clusters. It is advisory only (always exits 0, never fails CI) and uses conservative heuristics, so review its suggestions rather than treating them as errors.
+
+### Agent tool exposure {#agent-tool}
+
+By default every action is exposed to the agent — the in-app assistant plus the app's MCP / A2A tool surfaces — as a callable tool. For an action that only the frontend (or an HTTP / cron caller) needs, set `agentTool: false` to keep it behind the framework's auth + action surface while removing it from every agent tool list:
+
+```ts
+export default defineAction({
+  description: "Persist the user's sidebar width.",
+  agentTool: false, // UI-only — not a tool in the model's context window
+  schema: z.object({ widthPx: z.number() }),
+  http: { method: "PUT" },
+  run: async ({ widthPx }) => {
+    /* ... */
+  },
+});
+```
+
+| Value       | Behavior                                                                                                                                                                                   |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `true`      | Allow (same as undefined). Useful for documenting intent.                                                                                                                                  |
+| `false`     | **Hidden from the model entirely** — not in the agent's tool list, MCP, or A2A. Still callable from the UI (`useActionMutation` / `callAction`), CLI, and `/_agent-native/actions/<name>`. |
+| `undefined` | **Default-allow.** The action is a normal agent tool.                                                                                                                                      |
+
+`agentTool: false` is **not** the same as [`toolCallable: false`](#tool-callable):
+
+- **`agentTool: false`** removes the action from the **model's** view. The model can no longer see or call it; the UI and HTTP can.
+- **`toolCallable: false`** only blocks the sandboxed **extension iframe bridge** (`appAction(...)`). The action stays fully visible to the model, UI, CLI, MCP, and A2A. It exists for high-blast-radius operations (account/org/auth changes), not for trimming the tool list.
+
+Reach for `agentTool: false` when you find yourself adding a UI-only or purely programmatic action, or when the UI stops using an action you'd otherwise leave exposed to the model.
+
 ### Extension callability {#tool-callable}
 
 Extensions (Alpine.js mini-apps that run inside sandboxed iframes — see [Extensions](/docs/extensions)) call actions via `appAction(name, params)`. Because a shared extension's HTML/JS executes inside the _viewer's_ session, an action invoked from an extension runs with the viewer's permissions, secrets, and SQL scope. For high-blast-radius operations, that is too much trust to grant by default.
@@ -102,6 +142,53 @@ Set `toolCallable: false` for actions that:
 - modify org membership (invite/remove members, change roles),
 - change resource visibility or grant share access (the framework's built-in `share-resource`, `unshare-resource`, and `set-resource-visibility` are already opted out).
 
+### Run context (second argument) {#run-context}
+
+`run` receives an optional second argument, `ctx`, carrying the resolved request identity and the surface that invoked the action. Read it instead of calling `getRequestUserEmail()` / `getRequestOrgId()` by hand, and pass the whole `ctx` to tracking:
+
+```ts
+export default defineAction({
+  description: "Log an audit entry for the current request.",
+  schema: z.object({ event: z.string() }),
+  run: async (args, ctx) => {
+    // ctx is undefined-safe: a 1-arg `run(args)` is still valid.
+    const actor = ctx?.userEmail ?? "system";
+    if (ctx?.caller === "frontend") {
+      // tighter rules for browser-initiated calls, looser for "tool"/"cli"
+    }
+    await db.insert(audit).values({
+      actor,
+      orgId: ctx?.orgId ?? null,
+      source: ctx?.caller ?? "unknown",
+      event: args.event,
+    });
+    return { ok: true };
+  },
+});
+```
+
+`ActionRunContext` fields:
+
+| Field       | Type                  | Notes                                                                                                                                                           |
+| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `userEmail` | `string \| undefined` | Resolved request user. **Never defaulted to a dev identity** — `undefined` when the request has no authenticated user. Apply your own fallback if you need one. |
+| `orgId`     | `string \| null`      | Resolved org id, or `null` when the request has no org.                                                                                                         |
+| `caller`    | `ActionCaller`        | How the action was invoked (see below).                                                                                                                         |
+| `send`      | `(event) => void`     | Optional. Emit an SSE event to the client. Only present inside the agent tool loop (`caller: "tool"`); `undefined` elsewhere.                                   |
+
+`caller` is the union `"tool" | "http" | "frontend" | "cli" | "mcp" | "a2a"`:
+
+| `caller`     | Set when…                                                                                                                            |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `"tool"`     | The in-app agent loop, a sub-agent / agent team, or an A2A request (A2A drives the same agent loop, so its tool calls are `"tool"`). |
+| `"frontend"` | A browser call via `useActionMutation` / `useActionQuery` / `callAction` (tagged with the `X-Agent-Native-Frontend: 1` header).      |
+| `"http"`     | A bare programmatic `POST` / `GET` to `/_agent-native/actions/<name>` without the frontend marker.                                   |
+| `"cli"`      | `pnpm action <name>` (the CLI runner).                                                                                               |
+| `"mcp"`      | An external agent over the MCP `tools/call` endpoint.                                                                                |
+| `"a2a"`      | Reserved for a future direct A2A action dispatch. Today A2A runs through the agent loop, so those calls are `"tool"`.                |
+
+`run` stays backward compatible: existing 1-argument handlers and handlers that only destructure `{ send }` continue to work unchanged.
+
 ## Calling it from the UI {#ui}
 
 Two hooks, both in `@agent-native/core/client`. Types are inferred from your `defineAction` schemas — no manual type declarations.

package/docs/content/agent-mentions.md

@@ -40,8 +40,9 @@ When a message containing an `@`-mention is sent, the following happens on the s
 3. The agent's response is wrapped in an `<agent-response>` XML block and injected into the conversation context
 4. The main agent processes the enriched message, seeing both the user's text and the mentioned agent's response
 
+What the main agent sees in its context:
+
 ```text
-// What the main agent sees in its context:
 User: Draft an email with the latest signup numbers. @analytics
 
 <agent-response agent="analytics">

package/docs/content/authentication.md

@@ -103,7 +103,7 @@ If unset, the framework falls back to `BETTER_AUTH_SECRET`. A dedicated `OAUTH_S
 
 ## Organizations {#organizations}
 
-Better Auth's organization plugin is built into the framework. Every app supports:
+The framework provides a built-in organization system. This is the framework's own `org/` module — backed by the `organizations` and `org_members` tables — not Better Auth's organization plugin, which is intentionally not registered. Every app supports:
 
 - Creating organizations
 - Inviting members with roles (`owner`, `admin`, `member`)
@@ -204,6 +204,7 @@ interface AuthSession {
   email: string; // User's email (primary identifier)
   userId?: string; // Better Auth user ID
   token?: string; // Session token
+  name?: string; // Display name from the auth provider, when available
   orgId?: string; // Active organization ID
   orgRole?: string; // Role in active org (owner/admin/member)
 }

package/docs/content/client.md

@@ -7,6 +7,8 @@ description: "React hooks and utilities for agent-native apps: sendToAgentChat,
 
 `@agent-native/core` provides React hooks and utilities for the browser-side of agent-native apps.
 
+These client/React APIs are exported from both `@agent-native/core` and `@agent-native/core/client`. Import them from `@agent-native/core/client` (the browser entry) for clarity and correct bundling, since the bare `@agent-native/core` root resolves to the Node build by default.
+
 ## File-Based Routing {#file-based-routing}
 
 Agent-native apps use **React Router v7** with file-based routing. Every file in `app/routes/` becomes a URL.
@@ -87,7 +89,7 @@ Internally this is the submitted-chat path sometimes surfaced as
 posting that event directly.
 
 ```ts
-import { sendToAgentChat } from "@agent-native/core";
+import { sendToAgentChat } from "@agent-native/core/client";
 
 // Auto-submit a prompt with hidden context
 sendToAgentChat({
@@ -106,14 +108,17 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| Option                | Type        | Description                                    |
-| --------------------- | ----------- | ---------------------------------------------- |
-| `message`             | `string`    | The visible prompt sent to the chat            |
-| `context`             | `string?`   | Hidden context appended (not shown in chat UI) |
-| `submit`              | `boolean?`  | true = auto-submit, false = prefill only       |
-| `projectSlug`         | `string?`   | Optional project slug for structured context   |
-| `preset`              | `string?`   | Optional preset name for downstream consumers  |
-| `referenceImagePaths` | `string[]?` | Optional reference image paths                 |
+| Option                | Type        | Description                                                                |
+| --------------------- | ----------- | -------------------------------------------------------------------------- |
+| `message`             | `string`    | The visible prompt sent to the chat                                        |
+| `context`             | `string?`   | Hidden context appended (not shown in chat UI)                             |
+| `submit`              | `boolean?`  | true = auto-submit, false = prefill only                                   |
+| `newTab`              | `boolean?`  | Create a separate chat thread for this prompt                              |
+| `background`          | `boolean?`  | With `newTab`, run without focusing the tab and show the run in `RunsTray` |
+| `openSidebar`         | `boolean?`  | Set false to submit/prefill without opening the sidebar                    |
+| `projectSlug`         | `string?`   | Optional project slug for structured context                               |
+| `preset`              | `string?`   | Optional preset name for downstream consumers                              |
+| `referenceImagePaths` | `string[]?` | Optional reference image paths                                             |
 
 ## Agent Chat Context State (Advanced) {#agent-chat-context-state}
 
@@ -138,7 +143,7 @@ and `submit` for those.
 `useAgentChatContext()` returns `{ items, set, remove, clear, refresh }`.
 
 ```tsx
-import { useAgentChatContext } from "@agent-native/core";
+import { useAgentChatContext } from "@agent-native/core/client";
 
 function SelectionContextButton({ record }: { record: { id: string } }) {
   const chatContext = useAgentChatContext();
@@ -181,6 +186,52 @@ current staged items once. `clearAgentChatContext()` is intentionally broad; use
 | `context`     | `string`   | Hidden context included with the next submitted prompt |
 | `openSidebar` | `boolean?` | Defaults to true; pass false to stage context silently |
 
+## askUserQuestion(opts) {#ask-user-question}
+
+Ask the user a multiple-choice question from app code, render it inline in the
+agent panel, and **await their answer**. It's the client-side twin of the
+agent's built-in `ask-question` tool: it writes a `GuidedQuestionPayload` to the
+`"guided-questions"` application-state key (where the mounted
+`GuidedQuestionFlow` renders it) and reveals the agent panel so the question is
+visible. Unlike the agent tool — whose answer flows back to the agent —
+`askUserQuestion()` **resolves with the answer to the caller**, so the UI can
+branch on it.
+
+Use it when the UI needs exactly one small decision (2–4 options) before it
+kicks off agent work — instead of building a custom modal. Reach for the
+composer for freeform detail, and a form/popover for multi-field input.
+
+```tsx
+import { askUserQuestion, sendToAgentChat } from "@agent-native/core/client";
+
+const length = await askUserQuestion({
+  question: "How long should this deck be?",
+  header: "Deck length", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Short (3–5 slides)", value: "short" },
+    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
+    { label: "Long (11+ slides)", value: "long" },
+  ],
+  allowFreeText: false, // omit the "Other" free-text option (default adds it)
+  allowMultiple: false, // single-select (default)
+});
+
+if (length) {
+  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
+}
+```
+
+Each option is `{ label, value?, description?, preview?, recommended? }`; `value`
+defaults to `label`, and `preview` renders a small mockup/code snippet under the
+option. The promise resolves with the selected `value` (or `value[]` when
+`allowMultiple`), the free-text string when the user picks "Other", or `null`
+if they skip — it stays pending until the user answers. Requires the agent panel
+to be mounted (it is in every template).
+
+The agent reaches the same UI through its `ask-question` tool: prefer letting the
+agent ask when _it_ hits a genuine fork it can't resolve from context; use
+`askUserQuestion()` when the _UI_ needs to gate an action on a choice.
+
 ## MCP App Host Bridge {#mcp-app-host-bridge}
 
 Routes embedded as MCP Apps should be URL-first: load the current artifact from
@@ -230,7 +281,7 @@ Set `dynamicSuggestions={false}` to keep only static chips. Pass `getSuggestions
 React hook that wraps sendToAgentChat with loading state tracking:
 
 ```ts
-import { useAgentChatGenerating } from "@agent-native/core";
+import { useAgentChatGenerating } from "@agent-native/core/client";
 
 function GenerateButton() {
   const [isGenerating, send] = useAgentChatGenerating();
@@ -257,7 +308,7 @@ function GenerateButton() {
 React hook (formerly `useFileWatcher`) that listens for database changes over SSE, falls back to polling, and invalidates the framework query caches that keep the UI aligned with agent writes:
 
 ```ts
-import { useDbSync } from "@agent-native/core";
+import { useDbSync } from "@agent-native/core/client";
 import { useQueryClient } from "@tanstack/react-query";
 
 function App() {
@@ -325,7 +376,7 @@ function DashboardView({ id }) {
 Utility for merging class names (clsx + tailwind-merge):
 
 ```ts
-import { cn } from "@agent-native/core";
+import { cn } from "@agent-native/core/client";
 
 <div className={cn(
   "px-4 py-2 rounded",

package/docs/content/cloneable-saas.md

@@ -23,7 +23,7 @@ Each one is a real app you could use today, and the launching pad for your own v
 | **Slides**    | An agent-native Google Slides. React-based decks the agent generates and edits directly.                       |
 | **Video**     | An agent-native video editor on Remotion. Prompt for a cut, the agent assembles it.                            |
 | **Analytics** | An agent-native Amplitude/Mixpanel. Connect data sources, prompt for charts, pin to dashboards.                |
-| **Clips**     | An agent-native Loom. Async screen + camera recording with transcription, chapters, AI summaries.              |
+| **Clips**     | Replaces Loom — async screen + camera recording with transcription, chapters, AI summaries.                    |
 | **Design**    | Agent-native HTML prototyping studio for interactive Alpine/Tailwind designs.                                  |
 | **Forms**     | An agent-native Typeform. Build, share, collect, and route submissions to Slack, Sheets, webhooks, or Discord. |
 | **Dispatch**  | The workspace control plane: shared secrets, reusable integrations, Slack/Telegram, scheduled jobs.            |

package/docs/content/code-agents-ui.md

@@ -80,17 +80,20 @@ pnpm install
 pnpm dev
 ```
 
-Your host can wrap the local run store through normal actions:
+Your host can wrap the local run store through normal actions. These are
+host-owned actions you would define yourself — they are not shipped framework
+actions — mapping each `CodeAgentsHost` method onto the run store, for example:
 
-- `list-code-agent-runs`
-- `list-code-agent-packs`
-- `create-code-agent-run`
-- `read-code-agent-transcript`
-- `append-code-agent-follow-up`
-- `update-code-agent-run`
-- `control-code-agent-run`
+- a "list runs" action backing `listRuns`
+- a "list code packs" action backing `listCodePacks`
+- a "create run" action backing `createRun`
+- a "read transcript" action backing `readTranscript`
+- an "append follow-up" action backing `appendFollowUp`
+- an "update run" action backing `updateRun`
+- a "control run" action backing `controlRun`
 
-It uses `@agent-native/core/code-agents`, which exposes the same file-backed run store and executor used by the CLI.
+Each one calls `@agent-native/core/code-agents`, which exposes the same
+file-backed run store and executor used by the CLI.
 
 ## CLI Run Controls
 
@@ -117,7 +120,10 @@ agent-native code /audit --url https://example.com
 agent-native code /release-check
 ```
 
-Project commands come from `.agents/commands/*.md`; project skills come from
+Here `/migrate` and `/audit` are built-in goals (the built-in goals are
+`task`, `migrate`, and `audit`). `/release-check` is shown as an example of a
+project command — defined in `.agents/commands/`, not a built-in goal. Project
+commands come from `.agents/commands/*.md`; project skills come from
 `.agents/skills/*/SKILL.md`. The control commands operate on the same run
 records that the Desktop Code tab and shared UI display:
 
@@ -270,7 +276,7 @@ Project skills live in:
 .agents/skills/*/SKILL.md
 ```
 
-When the host implements `listCodePacks`, the shared UI shows project commands and skills in the rail. Command rows insert `/<command>`, and skill rows insert a focused “Use the <skill> skill…” prompt so the rail stays actionable. Built-in names such as `/migrate`, `/audit`, `/status`, and `/resume` stay reserved for the global Agent-Native Code controls.
+When the host implements `listCodePacks`, the shared UI shows project commands and skills in the rail. Command rows insert `/<command>`, and skill rows insert a focused “Use the <skill> skill…” prompt so the rail stays actionable. The built-in slash goals `/migrate` and `/audit` stay reserved for the global Agent-Native Code controls, as do run-control names such as `status` and `resume` — those are subcommands invoked without a slash (`agent-native code status`, `agent-native code resume`), not slash goals.
 
 Do not create a separate slash-command registry for a new Code host. Project
 commands and skills are discovered from `.agents/commands/*.md` and

package/docs/content/context-awareness.md

@@ -288,7 +288,7 @@ That gives the user the magic "this is what I meant" behavior without stuffing e
 
 ## The navigate action {#navigate-action}
 
-The agent writes a one-shot `navigate` command to application-state. The UI reads it, performs the navigation, and deletes the entry.
+`navigate` is the mirror image of `navigation`. Where `navigation` is the UI telling the agent where the user is, `navigate` is the agent telling the UI where to go. The agent writes a one-shot `navigate` command to application-state; the UI reads it, performs the navigation, then deletes the entry.
 
 ```ts
 // Agent side -- write a navigate command
@@ -297,9 +297,21 @@ import { writeAppState } from "@agent-native/core/application-state";
 await writeAppState("navigate", { view: "inbox", threadId: "thread-123" });
 ```
 
-The UI should consume these commands through `useAgentRouteState`, which handles command polling, tab-scoped fallback keys, duplicate-command protection, and delete-after-read:
+On the UI side you never poll or delete this key by hand. Both directions -- writing `navigation` on every route change and consuming the agent's `navigate` command -- are handled by a single hook, [`useNavigationState`](#use-navigation-state), covered in the next section.
+
+The `navigation` key belongs to the UI; the agent must never write to it directly. The agent writes `navigate`, the UI performs the move, and that move is what updates `navigation`.
+
+## The useNavigationState hook {#use-navigation-state}
+
+`useNavigationState` is **your app's hook, not a framework import.** Every template ships one at `app/hooks/use-navigation-state.ts` and calls it once from the app shell (`root.tsx`). It is the single place that wires navigation in both directions:
+
+- **Outbound (UI → agent):** writes the `navigation` key whenever the route changes, so the agent always knows the current view.
+- **Inbound (agent → UI):** polls the `navigate` command, runs the navigation, and deletes the command.
+
+It stays short because it is a thin wrapper around the real framework primitive, `useAgentRouteState` (exported from `@agent-native/core/client`). You supply two app-specific functions and the framework does the rest:
 
 ```tsx
+// app/hooks/use-navigation-state.ts -- this file lives in YOUR app
 import { useAgentRouteState } from "@agent-native/core/client";
 import { TAB_ID } from "@/lib/tab-id";
 
@@ -312,10 +324,14 @@ export function useNavigationState() {
   useAgentRouteState<NavigationState>({
     browserTabId: TAB_ID,
     requestSource: TAB_ID,
+
+    // UI → agent: derive semantic state from the current URL.
     getNavigationState: ({ pathname }) => {
       const match = pathname.match(/^\/thread\/([^/]+)/);
       return match ? { view: "thread", threadId: match[1] } : { view: "inbox" };
     },
+
+    // agent → UI: turn a `navigate` command into a route to push.
     getCommandPath: (command) =>
       command.view === "thread" && command.threadId
         ? `/thread/${command.threadId}`
@@ -324,33 +340,12 @@ export function useNavigationState() {
 }
 ```
 
-The `navigation` key belongs to the UI -- the agent should never write to it directly. Instead, the agent writes to `navigate`, and the UI performs the actual navigation, which then updates `navigation`.
-
-## useNavigationState hook {#use-navigation-state}
-
-The `use-navigation-state.ts` hook is usually a thin wrapper around `useAgentRouteState`. Template code supplies the app-specific route mapping; core owns application-state writes, command reads/deletes, request-source headers, and duplicate-command prevention.
-
-```tsx
-// app/hooks/use-navigation-state.ts
-import { useAgentRouteState } from "@agent-native/core/client";
-import { TAB_ID } from "@/lib/tab-id";
-
-export function useNavigationState() {
-  useAgentRouteState({
-    browserTabId: TAB_ID,
-    requestSource: TAB_ID,
-    getNavigationState: ({ pathname, searchParams }) => ({
-      view: pathname === "/" ? "home" : pathname.slice(1),
-      // Optional semantic alias. Raw query params are still visible in
-      // <current-url> and controllable with set-search-params.
-      label: searchParams.get("label"),
-    }),
-    getCommandPath: (command: any) => command.path ?? "/",
-  });
-}
-```
+| You write                                              | The framework handles                                                                    |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `getNavigationState` — map the URL to semantic state   | `navigation` writes, tab-scoped plus a global fallback key                               |
+| `getCommandPath` — map a `navigate` command to a route | command polling, delete-after-read, duplicate-command protection, request-source tagging |
 
-For non-router state channels, use the lower-level `useSemanticNavigationState`. It takes a ready-made `state`, an ordered list of `navigationKeys`/`commandKeys`, and an `onCommand` callback, but does not import or assume React Router.
+`useAgentRouteState` assumes React Router. When navigation does not live in the URL -- a wizard step, a canvas selection, a non-router shell -- drop down to the lower-level `useSemanticNavigationState` instead: you hand it a ready-made `state` value plus `navigationKeys`/`commandKeys` and an `onCommand` callback, and it stays completely agnostic about React Router.
 
 ## Jitter prevention {#jitter-prevention}
 

package/docs/content/creating-templates.md

@@ -138,7 +138,7 @@ Actions are the single source of truth for app behavior. The agent calls them as
 ```ts
 // actions/create-project.ts
 import { defineAction } from "@agent-native/core";
-import { getDb } from "@agent-native/core/db";
+import { getDb } from "../server/db/index.js"; // getDb is created per app via createGetDb(schema) in server/db/index.ts
 import { nanoid } from "nanoid";
 import { z } from "zod";
 import * as schema from "../server/db/schema";

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

@@ -117,6 +117,8 @@ import { sendToAgentChat } from "@agent-native/core/client";
 - **`message`** — the visible prompt shown in chat.
 - **`context`** — hidden context appended to the prompt (selected text, cursor position, current entity id — anything the agent should know but the user shouldn't see twice).
 - **`submit`** — `true` to auto-run, `false` to prefill but wait. Omit to use the project default.
+- **`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)).
 

package/docs/content/getting-started.md

@@ -12,7 +12,7 @@ By the end of this page, you'll have a working app — Mail, Calendar, Forms, or
 There are two ways to use agent-native, depending on how hands-on you want to be:
 
 - **You want to use a hosted version.** Try a template right now at [agent-native.com/templates](/templates). Each template is a live, hosted app — you sign in, start using it, and the agent is already there. No install, no setup. You can stop reading this page and head straight to the [template gallery](/templates).
-- **You want to run locally or customize it.** You'll clone a template, run it on your machine, and shape it however you want — branding, features, integrations. The rest of this page is for you. You'll need [Node.js 24 LTS](https://nodejs.org) and [pnpm](https://pnpm.io) installed.
+- **You want to run locally or customize it.** You'll clone a template, run it on your machine, and shape it however you want — branding, features, integrations. The rest of this page is for you. You'll need [Node.js 22 or newer (LTS recommended)](https://nodejs.org) and [pnpm](https://pnpm.io) installed.
 
 Not sure which path? If you've never written code, the hosted version is for you. If you have a developer or AI coding tool ready, the local path gives you total control.
 
@@ -125,7 +125,7 @@ Each template is a complete app with UI, agent actions, database schema, and AI
 | [Assets](/docs/template-assets)       | Brand asset libraries and generated media       |
 | [Slides](/docs/template-slides)       | Google Slides, Pitch                            |
 | [Video](/docs/template-videos)        | Remotion-based video editing                    |
-| [Analytics](/docs/template-analytics) | Amplitude, Mixpanel, Looker                     |
+| [Analytics](/docs/template-analytics) | Amplitude, Mixpanel                             |
 | [Mail](/docs/template-mail)           | Superhuman, Gmail                               |
 | [Clips](/docs/template-clips)         | Replaces Loom — screen + camera recording       |
 | [Design](/docs/template-design)       | HTML prototyping studios                        |

package/docs/content/key-concepts.md

@@ -111,7 +111,7 @@ The UI never calls an LLM directly. When a user clicks "Generate chart" or "Writ
 
 ```ts
 // In a React component — delegate AI work to the agent
-import { sendToAgentChat } from "@agent-native/core";
+import { sendToAgentChat } from "@agent-native/core/client";
 
 sendToAgentChat({
   message: "Generate a chart showing signups by source",
@@ -164,7 +164,7 @@ Database changes are synced to the UI through `useDbSync()`. Same-process writes
 
 ```ts
 // Client: subscribe to agent/UI data changes once near the app shell
-import { useDbSync } from "@agent-native/core";
+import { useDbSync } from "@agent-native/core/client";
 
 useDbSync({ queryClient });
 ```

package/docs/content/messaging.md

@@ -301,29 +301,71 @@ The agent can send messages on its own initiative (notifications, reminders, sch
 To add a new messaging platform, implement the `PlatformAdapter` interface:
 
 ```ts
-import type { PlatformAdapter } from "@agent-native/core/server";
+import type { H3Event } from "h3";
+import type {
+  PlatformAdapter,
+  IncomingMessage,
+  OutgoingMessage,
+} from "@agent-native/core/server";
+import type { EnvKeyConfig } from "@agent-native/core/server";
 
 const myAdapter: PlatformAdapter = {
   platform: "discord",
+  label: "Discord",
 
-  // Verify the incoming webhook is authentic
-  verifyRequest(request: Request): Promise<boolean> {
-    // Validate signature headers
+  // Env keys this adapter needs (rendered in the settings UI)
+  getRequiredEnvKeys(): EnvKeyConfig[] {
+    return [
+      { key: "DISCORD_BOT_TOKEN", label: "Discord Bot Token", required: true },
+    ];
   },
 
-  // Extract the message text and thread context
-  parseMessage(body: unknown): Promise<{
-    text: string;
-    threadId: string;
-    senderId: string;
-    metadata?: Record<string, unknown>;
-  }> {
-    // Parse platform-specific payload
+  // Handle platform-specific verification challenges (e.g. Slack's
+  // url_verification). Return { handled: true, response } to short-circuit.
+  async handleVerification(event: H3Event) {
+    return { handled: false };
   },
 
-  // Post the agent's response back
-  sendResponse(threadId: string, text: string): Promise<void> {
-    // Call the platform's API
+  // Validate the webhook request signature
+  async verifyWebhook(event: H3Event): Promise<boolean> {
+    // Validate signature headers; return true if authentic
+    return true;
+  },
+
+  // Parse the webhook payload into a normalized IncomingMessage.
+  // Return null to silently ignore the event (bot messages, edits, etc.).
+  async parseIncomingMessage(event: H3Event): Promise<IncomingMessage | null> {
+    return {
+      platform: "discord",
+      externalThreadId: "channel-or-thread-id",
+      text: "the user's message",
+      senderId: "discord-user-id",
+      platformContext: { channelId: "channel-id" },
+      timestamp: Date.now(),
+    };
+  },
+
+  // Format plain agent text into a platform-appropriate OutgoingMessage
+  formatAgentResponse(text: string): OutgoingMessage {
+    return { text, platformContext: {} };
+  },
+
+  // Post the agent's response back to the platform
+  async sendResponse(
+    message: OutgoingMessage,
+    context: IncomingMessage,
+  ): Promise<void> {
+    // Call the platform's API, using context.platformContext for routing
+  },
+
+  // Return current connection/configuration status for the settings UI
+  async getStatus() {
+    return {
+      platform: "discord",
+      label: "Discord",
+      enabled: true,
+      configured: !!process.env.DISCORD_BOT_TOKEN,
+    };
   },
 };
 ```

package/docs/content/migration-workbench.md

@@ -118,7 +118,7 @@ Drive the session with the standard run controls (`status`/`list`/`attach`/`logs
 
 ## Long-Running Goals
 
-The `/migrate` goal has an action named `run-migration-goal`. It advances a run in bounded iterations:
+The `/migrate` goal advances a run in bounded iterations:
 
 - before approval, it can assess and plan but cannot write generated output
 - after approval, it scaffolds once, advances pending tasks, verifies, and records verifier results

package/docs/content/multi-app-workspace.md

@@ -142,7 +142,7 @@ Dispatch resources are scoped **All apps** (every app inherits them at runtime,
 
 ## Authentication and RBAC {#auth-and-rbac}
 
-Every agent-native app already ships with [Better Auth](/docs/authentication) and its organizations plugin — users, organizations, members, and the `owner` / `admin` / `member` roles are all first-class, shared across every template. In a workspace, you get that for free in every app, backed by the same database.
+Every agent-native app already ships with [Better Auth](/docs/authentication) plus the framework's built-in organization system — users, organizations, members, and the `owner` / `admin` / `member` roles are all first-class, shared across every template. (Organizations are framework-managed via the `organizations` / `org_members` tables, not Better Auth's organization plugin, which is intentionally not registered.) In a workspace, you get that for free in every app, backed by the same database.
 
 For enterprise-specific rules (allow-list domains, SSO enforcement, extra role checks), export an `authPlugin` from `packages/shared/src/server/index.ts`. Every app in the workspace now enforces those rules.
 

package/docs/content/multi-tenancy.md

@@ -9,7 +9,7 @@ Every agent-native app is multi-tenant by default. Organizations, team members,
 
 ## How it works {#how-it-works}
 
-The framework uses [Better Auth](https://better-auth.com)'s organizations plugin to provide full multi-tenancy:
+The framework provides full multi-tenancy through its own built-in organization system — the core `org/` module backed by the `organizations` and `org_members` tables. (This is the framework's own system, not [Better Auth](https://better-auth.com)'s organization plugin, which is intentionally not registered.)
 
 - **Organizations** — users create organizations and invite team members. Each org is a fully isolated tenant.
 - **Roles** — every member has a role: `owner`, `admin`, or `member`. Actions can check roles for authorization.
@@ -20,22 +20,24 @@ All first-party templates (Mail, Calendar, Content, Brain, Assets, Slides, Video
 
 ## Organizations and members {#organizations-and-members}
 
-Users can create organizations, invite members by email, and assign roles:
+Users can create organizations, invite members by email, and assign roles. The org-switcher and members UI drive this through the core org REST routes (no template code required):
+
+```text
+POST /_agent-native/org              # create an organization
+POST /_agent-native/org/invitations  # invite a member by email
+```
+
+Server code can call the same surface directly through the `org/` module. `createOrganization(name, email, role?)` creates an org and adds the caller as a member; membership and roles live in the `org_members` table:
 
 ```typescript
-// Creating an org (from an action or the client)
-const org = await auth.api.createOrganization({
-  body: { name: "Acme Inc", slug: "acme" },
-});
-
-// Inviting a member
-await auth.api.createInvitation({
-  body: {
-    organizationId: org.id,
-    email: "alice@acme.com",
-    role: "member", // "owner" | "admin" | "member"
-  },
-});
+import { createOrganization } from "@agent-native/core/org";
+
+// Creating an org adds the caller (email) as a member with the given role
+const org = await createOrganization(
+  "Acme Inc",
+  "alice@acme.com",
+  "owner", // "owner" | "admin" | "member", defaults to "owner"
+);
 ```
 
 Org management is a **framework built-in**: the core org plugin auto-mounts REST routes under `/_agent-native/org/*` (create org, switch org, list/invite/remove members, change roles, set allowed email domain), and these back the org-switcher and members UI in every template with no extra code. Agent-callable actions with names like `create-organization` or `invite-member` are **template-authored** on top of this surface, not built-in tools — a template wires its own `defineAction` wrappers when it wants the agent to manage its specific membership model.