@agent-native/core 0.47.1 → 0.48.2

package/docs/content/tracking.md

@@ -7,6 +7,8 @@ description: "Server-side analytics with pluggable providers — PostHog, Mixpan
 
 One function, multiple destinations. Call `track()` from any server-side code — actions, plugins, server routes — and the event fans out to every registered analytics provider. No SDK dependencies, no client-side scripts, no blocking. The same `track()` is also available in [browser/app code](#client) and routes to the same providers.
 
+This is _product_ analytics — your app's events flowing to PostHog/Mixpanel/Amplitude. For _agent quality_ metrics (traces, cost, evals, feedback) stored in your own database, see [Observability](/docs/observability).
+
 ```ts
 import { track } from "@agent-native/core/tracking";
 
@@ -130,18 +132,6 @@ Only `name` and `track` are required. `identify` and `flush` are optional — im
 - **Best-effort delivery** — provider errors are caught and logged. A failing analytics integration never crashes the caller or blocks request handling.
 - **Global singleton** — the registry uses a `Symbol.for` key on `globalThis` so multiple ESM graph instances (dev-mode Vite + Nitro, symlinks) share one provider set.
 
-## Browser defaults {#browser-defaults}
-
-Template roots call `configureTracking()` once at startup. Browser events sent with `trackEvent()` automatically include app/template context plus the current LLM connection when the app can resolve it:
-
-- `llm_connection` — normalized provider label such as `builder`, `anthropic`, `openai`, `google`, or `none`
-- `llm_engine` — the engine id, for example `builder` or `ai-sdk:openai`
-- `llm_model` — the selected/default model when known
-- `llm_connection_source` — `app_secrets`, `settings`, or `env`
-- `llm_connection_configured` — whether an LLM connection is available
-
-The framework also tracks `builder connect clicked` from Connect Builder CTAs, and the server-side Builder connect routes track started/succeeded/failed lifecycle events.
-
 ## Using track() in templates {#templates}
 
 Call `track()` from action handlers to record user or agent activity:
@@ -191,7 +181,21 @@ Key differences from the [server `track()`](#track):
 - **Fire-and-forget.** It never blocks the UI, never throws, and swallows network errors.
 - **Authenticated, first-party only.** The route requires a session and a same-origin/CSRF marker (set automatically by the helper), so it can't be used as an open analytics relay. `name` is capped at 200 characters and `properties` at ~16KB; oversized or malformed payloads are rejected.
 
-This is distinct from the framework's internal browser telemetry (`trackEvent()` / automatic pageviews — see [Browser defaults](#browser-defaults)), which powers Agent Native's own product analytics. Use `track()` for your app's own analytics events that should reach your configured providers.
+This is distinct from the framework's internal browser telemetry (`trackEvent()` / automatic pageviews — see [Browser defaults](#browser-defaults) below), which powers Agent Native's own product analytics. Use `track()` for your app's own analytics events that should reach your configured providers.
+
+## Browser defaults {#browser-defaults}
+
+This section covers the framework's own internal telemetry — mostly relevant to framework contributors and advanced template authors.
+
+Template roots call `configureTracking()` once at startup. Browser events sent with `trackEvent()` automatically include app/template context plus the current LLM connection when the app can resolve it:
+
+- `llm_connection` — normalized provider label such as `builder`, `anthropic`, `openai`, `google`, or `none`
+- `llm_engine` — the engine id, for example `builder` or `ai-sdk:openai`
+- `llm_model` — the selected/default model when known
+- `llm_connection_source` — `app_secrets`, `settings`, or `env`
+- `llm_connection_configured` — whether an LLM connection is available
+
+The framework also tracks `builder connect clicked` from Connect Builder CTAs, and the server-side Builder connect routes track started/succeeded/failed lifecycle events. `configureTracking()` is called automatically by the framework; you don't need to call it in your own template code.
 
 ## What's next
 

package/docs/content/using-your-agent.md

@@ -11,40 +11,50 @@ There's a simple through-line. The agent **sees** what you're looking at, you **
 
 ## It sees what you're looking at {#it-sees}
 
+_For end users of an agent-native app._
+
 The agent isn't blind to your screen. Open an email and it knows which thread. Select a chart and it knows which chart. Highlight a paragraph and it can act on just that range. That shared awareness is what lets you say "reply to this" or "summarize the selection" without spelling out the context every time.
 
 This works because the current navigation and selection live in `application_state` SQL, which the agent reads as part of its context. The agent can also drive that same state back — opening a view, selecting a row — so you watch it work in the real UI rather than in a transcript.
 
-→ [**Context Awareness**](/docs/context-awareness) — navigation state, view-screen, navigate commands, and how the agent stays in sync with your screen.
+→ [**Context Awareness**](/docs/context-awareness) — navigation state, view-screen, navigate commands, and how the agent stays in sync with your screen. _(For developers building the app.)_
 
 ## You direct it {#you-direct-it}
 
+_For end users of an agent-native app._
+
 Most of the time you steer the agent by typing into the chat. Two things make that faster.
 
 **Mentions.** Tag a custom agent, a connected agent, or a file with `@` to pull it into the conversation — "let `@analytics` pull last week's numbers, then draft the summary." Mentions are how you reach the right specialist or attach the right context without leaving the composer.
 
 **Voice.** The composer has a microphone. Dictate a request instead of typing it, with provider options ranging from Builder's hosted transcription to bring-your-own-key to a browser fallback.
 
-→ [**Agent Mentions**](/docs/agent-mentions) — `@`-mention custom agents, connected agents, and files in chat.
+→ [**Agent Mentions**](/docs/agent-mentions) — `@`-mention custom agents, connected agents, and files in chat. _(For end users and developers.)_
 → [**Voice Input**](/docs/voice-input) — dictation in the chat composer and how transcription is routed.
 
 ## You embed it {#you-embed-it}
 
+_For developers building the app._
+
 The agent isn't a separate app you tab over to. It ships as a handful of React components — a sidebar, a raw panel, and a `sendToAgentChat()` call — that you drop into any app. Render `<AgentSidebar>` to give every screen a toggleable agent, or wire a button to hand a specific task off to the chat instead of running a one-shot LLM call.
 
-→ [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentPanel>`, `<AgentSidebar>`, and `sendToAgentChat()` into any React app.
+→ [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentPanel>`, `<AgentSidebar>`, and `sendToAgentChat()` into any React app. _(For developers building the app.)_
 
 ## You can go UI-light {#ui-light}
 
+_For end users of an agent-native app._
+
 Not every app needs a full dashboard. When the agent _is_ the product, you can skip most of the custom UI: open the app, ask for what you want, and let the agent do the rest. The agent still has its management surface — history, workspace, settings — but the primary interaction is conversation rather than clicks.
 
-→ [**Pure-Agent Apps**](/docs/pure-agent-apps) — apps where the agent is the whole product.
+→ [**Pure-Agent Apps**](/docs/pure-agent-apps) — apps where the agent is the whole product. _(For end users and developers.)_
 
 ## You co-edit with it {#you-co-edit}
 
+_For end users of an agent-native app._
+
 When you and the agent are working on the same document, you don't take turns. With real-time collaboration, the agent's edits stream in alongside yours — live cursors, no overwrites — the same way a teammate's would. You can keep typing while it works, and it sees your changes as they happen.
 
-→ [**Real-Time Collaboration**](/docs/real-time-collaboration) — multi-user collaborative editing with live cursors and agent edits in the same document.
+→ [**Real-Time Collaboration**](/docs/real-time-collaboration) — multi-user collaborative editing with live cursors and agent edits in the same document. _(For end users and developers.)_
 
 ## What's next {#whats-next}
 

package/docs/content/voice-input.md

@@ -17,7 +17,7 @@ The composer's voice button records audio in the browser, then picks a provider:
 2. **BYOK cloud providers.** Users can choose Google Gemini, Groq Whisper, or OpenAI Whisper from Settings. The route resolves user-scoped encrypted secrets before shared deployment credentials.
 3. **Browser Web Speech API (fallback).** If no server provider is available, the composer can use the browser's built-in speech recognition. Works in Chromium-based browsers (Chrome, Edge, Arc) and Safari. Less accurate; streams live.
 
-Provider choice is stored in application state under `voice-transcription-prefs` so the user can force `"builder-gemini"`, `"builder"`, `"gemini"`, `"groq"`, `"openai"`, or `"browser"` in the sidebar settings.
+Provider choice is stored in application state under `voice-transcription-prefs` so the user can force `"auto"` (default — picks the best available provider), `"builder-gemini"`, `"builder"`, `"gemini"`, `"groq"`, `"openai"`, or `"browser"` in the sidebar settings.
 
 The route is **same-origin only** — cross-site POSTs are rejected so an attacker can't burn transcription credits from an external page.
 

package/docs/content/what-is-agent-native.md

@@ -49,12 +49,10 @@ Three things change when you reach rung 3:
 
 That's rung 3. That's agent-native.
 
-It also explains why agent-native can support so many protocols without making every app author become a protocol expert. MCP tools, MCP Apps, remote MCP OAuth, A2A, typed React mutations, HTTP action endpoints, CLI actions, deep links, instructions, skills, memory, jobs, and connected MCP servers all hang off the same action and workspace model. Build the domain operation once as an action; the framework projects it into the surfaces each host understands.
+See [Key Concepts — Protocols](/docs/key-concepts#protocols) for how all of this hangs off the same action definition.
 
 ## Why every agent needs a UI {#why-every-agent-needs-a-ui}
 
-The hot take in 2026 is "apps are dead, agents will replace UIs, everyone will just text an agent in Telegram." Eh.
-
 Even when the agent does all the heavy lifting, humans still need to:
 
 - **See what it's doing** — progress, intermediate output, what it touched
@@ -71,7 +69,7 @@ The flip side is just as important. Existing SaaS products keep hitting the same
 
 Agent-native flips that. Because every action in the app is defined once and exposed as both a button and an agent tool, the agent can do everything the buttons can — and more — without a separate "AI world" to maintain. Natural language becomes a first-class input alongside clicks.
 
-The argument isn't "agents replace UI." It's "**agents belong inside applications, with a UI on top, as equal partners**." Neither can stand alone.
+The argument isn't "agents replace UI." It's "**agents belong inside applications, with a UI on top, as equal partners**." See [Pure-Agent Apps](/docs/pure-agent-apps) for the full discussion of why agents still need a UI.
 
 ## Agent + UI parity {#agent-ui-parity}
 
@@ -153,14 +151,15 @@ export default defineAction({
   description: "Reply to an email thread",
   schema: z.object({ emailId: z.string(), body: z.string() }),
   run: async ({ emailId, body }) => {
-    await db.replies.insert({ emailId, body });
+    // db and schema come from your app's server/db setup
+    await db.insert(schema.replies).values({ emailId, body });
   },
 });
 ```
 
 ```tsx
 // In any React component — same action, called from a button
-const { mutate } = useActionMutation("replyToEmail");
+const { mutate } = useActionMutation("reply-to-email");
 
 <Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
   Send Reply