@agent-native/core 0.93.0 → 0.94.1

package/docs/content/toolkit-collaboration.mdx

@@ -34,8 +34,7 @@ operations.
 
 ## Server And Client Shape {#server-and-client-shape}
 
-```ts
-// server/plugins/collab.ts
+```ts filename="server/plugins/collab.ts"
 import { createCollabPlugin } from "@agent-native/core/server";
 
 export default createCollabPlugin({
@@ -70,5 +69,60 @@ const undo = useCollabUndo(collab.ydoc, { trackedOrigins: [user.email] });
 - Keep undo local and predictable: CRDT undo for document operations, local-op
   undo for app-specific commands.
 
-Related docs: [Realtime Collaboration](/docs/real-time-collaboration),
-[Component API](/docs/components#collab-presence).
+## UI components {#ui-components}
+
+`@agent-native/toolkit/collab-ui` contains the presentational collaboration
+pieces that do not own transport or storage:
+
+<WireframeBlock id="doc-block-toolkit-collaboration-ui">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:500px;box-sizing:border-box;padding:26px;display:flex;flex-direction:column;gap:14px'><div class='wf-card' style='position:relative;display:flex;flex-direction:column;gap:14px'><div style='display:flex;align-items:center;gap:8px'><h2 style='margin:0'>Editor canvas</h2><div style='flex:1'></div><div style='display:flex;align-items:center'><div style='width:26px;height:26px;border-radius:999px;background:var(--wf-accent-soft);border:2px solid var(--wf-card);flex:none'></div><div style='width:26px;height:26px;border-radius:999px;background:var(--wf-accent-soft);border:2px solid var(--wf-card);margin-left:-8px;flex:none'></div></div><span class='wf-pill accent'>Agent editing</span></div><div style='position:relative;border:1.6px solid var(--wf-accent);border-radius:var(--wf-radius);padding:14px;display:flex;flex-direction:column;gap:8px;margin-top:6px'><span class='wf-pill accent' style='position:absolute;left:12px;top:-12px'>Ava</span><div style='height:11px;width:80%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:65%;background:var(--wf-line);border-radius:4px'></div></div><div style='background:var(--wf-accent-soft);border-radius:var(--wf-radius);padding:14px;display:flex;flex-direction:column;gap:8px'><small class='wf-muted'>Sam edited moments ago</small><div style='height:11px;width:90%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:70%;background:var(--wf-line);border-radius:4px'></div></div><span class='wf-pill' style='position:absolute;right:70px;top:210px'>Sam</span></div></div>"
+    }
+  />
+</WireframeBlock>
+
+The full set of presentational exports:
+
+```tsx
+import {
+  AgentPresenceChip,
+  LiveCursorOverlay,
+  PresenceBar,
+  RecentEditHighlights,
+  RemoteSelectionRings,
+} 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, but new code
+should import `@agent-native/toolkit/collab-ui` directly.
+
+### Toolkit vs Core {#toolkit-vs-core}
+
+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.
+
+## What's next
+
+- [**Realtime Collaboration**](/docs/real-time-collaboration) — the CRDT
+  transport and sync model these components render.
+- [**Component API**](/docs/components#collab-presence) — the generated
+  reference for collaboration component props.
+- [**Sharing Kit**](/docs/toolkit-sharing) — the same Toolkit/Core split
+  applied to sharing and access control.
+- [**Agent-Native Toolkit**](/docs/agent-native-toolkit) — the hub page linking
+  every kit and foundation piece.

package/docs/content/toolkit-command-navigation.mdx

@@ -102,5 +102,11 @@ Use a small predictable route set:
 - The agent reads `view-screen` before acting on the current page.
 - The app shell should not remount when users navigate between app routes.
 
-Related docs: [Routing](/docs/routing), [Context Awareness](/docs/context-awareness),
-[External Agents](/docs/external-agents).
+## What's next
+
+- [**Routing**](/docs/routing) — the file-route conventions the route standard
+  builds on.
+- [**Context Awareness**](/docs/context-awareness) — how `view-screen` and
+  navigation state stay in sync.
+- [**External Agents**](/docs/external-agents) — deep links and
+  `/_agent-native/open` for hosts outside the app.

package/docs/content/toolkit-comments-review.mdx

@@ -94,5 +94,13 @@ actions and thread UI.
 - `consumedAt` and `resolved` are separate. An agent can consume a piece of
   feedback without closing the reviewer-visible thread.
 
-Related docs: [Plan](/docs/template-plan), [Content](/docs/template-content),
-[Sharing Kit](/docs/toolkit-sharing), [History Kit](/docs/toolkit-history).
+## What's next
+
+- [**Plan**](/docs/template-plan) — a template that uses review threads for
+  plan feedback.
+- [**Content**](/docs/template-content) — a template that uses review threads
+  for editorial approval.
+- [**Sharing Kit**](/docs/toolkit-sharing) — the access model reviewable
+  resources can reuse.
+- [**History Kit**](/docs/toolkit-history) — version history alongside the
+  review trail.

package/docs/content/toolkit-history.mdx

@@ -90,6 +90,11 @@ they need a custom timeline, preview, or compare view.
 - Snapshot data should be app-owned JSON. The kit stores and scopes it; the app
   decides how to render, diff, and restore it.
 
-Related docs: [Audit Log](/docs/audit-log),
-[Realtime Collaboration](/docs/real-time-collaboration),
-[Component API](/docs/components#collab-presence).
+## What's next
+
+- [**Audit Log**](/docs/audit-log) — the durable event trail the history
+  timeline's audit view reads from.
+- [**Realtime Collaboration**](/docs/real-time-collaboration) — the CRDT
+  editing surface `useCollabUndo()` wraps.
+- [**Component API**](/docs/components#collab-presence) — the full prop
+  reference for history and presence components.

package/docs/content/toolkit-observability.mdx

@@ -30,6 +30,44 @@ that operators use to understand what happened.
 | Run diagnostics            | Tool calls, model choice, context, approvals, and recovery state. |
 | Tracking                   | Server-side analytics events with pluggable providers.            |
 
+## Usage {#usage}
+
+Mount the dashboard on its own route, and drop `<ThumbsFeedback>` next to any
+assistant message you want feedback on — both write into the same
+usage/spend/feedback data the dashboard reads back:
+
+```tsx
+import {
+  ObservabilityDashboard,
+  ThumbsFeedback,
+} from "@agent-native/core/client";
+
+export default function ObservabilityPage() {
+  return (
+    <div className="min-h-screen bg-background p-6">
+      <ObservabilityDashboard />
+    </div>
+  );
+}
+
+export function AssistantMessageFooter({
+  threadId,
+  runId,
+  messageSeq,
+}: {
+  threadId: string;
+  runId: string;
+  messageSeq: number;
+}) {
+  return (
+    <ThumbsFeedback threadId={threadId} runId={runId} messageSeq={messageSeq} />
+  );
+}
+```
+
+The dashboard has 5 tabs (overview, conversations, evals, experiments,
+feedback) and scopes all data to the signed-in user.
+
 ## UX Standard {#ux-standard}
 
 - Every background or agent run should be traceable to a user-visible outcome.
@@ -37,5 +75,13 @@ that operators use to understand what happened.
 - Spend and usage should distinguish app, organization, user, and provider.
 - Error states should link back to setup when the fix is a missing connection.
 
-Related docs: [Observability](/docs/observability),
-[Tracking](/docs/tracking), [Progress](/docs/progress), [Agent UX Kit](/docs/toolkit-agent-ux).
+## What's next
+
+- [**Observability**](/docs/observability) — the full data model and routes
+  behind this dashboard.
+- [**Tracking**](/docs/tracking) — server-side analytics events with
+  pluggable providers.
+- [**Progress**](/docs/progress) — the run-progress surface `<RunsTray>` also
+  reads.
+- [**Agent UX Kit**](/docs/toolkit-agent-ux) — the composer and runs tray this
+  kit's diagnostics tie back to.

package/docs/content/toolkit-org-team.mdx

@@ -76,5 +76,11 @@ invites, domains, member roles, and A2A secret sync.
 - App switching lists workspace/default app links. Active-org continuity comes
   from the target app sharing the same auth and organization state.
 
-Related docs: [Multi-Tenancy](/docs/multi-tenancy),
-[Workspace Management](/docs/workspace-management), [Sharing Kit](/docs/toolkit-sharing).
+## What's next
+
+- [**Multi-Tenancy**](/docs/multi-tenancy) — how org scoping isolates data
+  across tenants.
+- [**Workspace Management**](/docs/workspace-management) — governance for
+  multi-app workspaces that share an organization.
+- [**Sharing Kit**](/docs/toolkit-sharing) — the access model that roles and
+  org scope feed into.

package/docs/content/toolkit-resources.mdx

@@ -45,6 +45,43 @@ const tree = useResourceTree("workspace");
 const resource = useResource(selectedId);
 ```
 
+## Mutations {#mutations}
+
+Reads and writes go through the same hooks the panel uses internally, so a
+custom toolbar button stays wired into the same cache invalidation as
+`<ResourcesPanel>`:
+
+```tsx
+import {
+  useCreateResource,
+  useResourceTree,
+} from "@agent-native/core/client/resources";
+
+export function NewNoteButton() {
+  const tree = useResourceTree("personal");
+  const createResource = useCreateResource();
+
+  return (
+    <button
+      type="button"
+      disabled={createResource.isPending}
+      onClick={() =>
+        createResource.mutate({
+          path: "notes/untitled.md",
+          content: "# Untitled\n",
+          mimeType: "text/markdown",
+        })
+      }
+    >
+      New note ({tree.data?.length ?? 0} items)
+    </button>
+  );
+}
+```
+
+`useUpdateResource()`, `useDeleteResource()`, and `useUploadResource()` follow
+the same shape and invalidate the tree/resource queries on success.
+
 ## UX Standard {#ux-standard}
 
 - Use a stable tree/editor split for file-heavy apps.
@@ -53,5 +90,11 @@ const resource = useResource(selectedId);
   collaboration still uses SQL-backed runtime state.
 - Resource actions should return deep links to the focused file/resource.
 
-Related docs: [Local File Mode](/docs/local-file-mode),
-[File Uploads](/docs/file-uploads), [Component API](/docs/components#resources).
+## What's next
+
+- [**Local File Mode**](/docs/local-file-mode) — repo-backed resources where
+  files are the source of truth.
+- [**File Uploads**](/docs/file-uploads) — the shared attachment path resource
+  uploads reuse.
+- [**Component API**](/docs/components#resources) — the full prop reference for
+  the resource components.

package/docs/content/toolkit-settings.mdx

@@ -114,5 +114,11 @@ on so settings stay findable everywhere.
 - Use the agent sidebar settings only as a compact access point, not as the
   primary home for every setting.
 
-Related docs: [Internationalization](/docs/internationalization),
-[Onboarding](/docs/onboarding), [Workspace Connections](/docs/workspace-connections).
+## What's next
+
+- [**Internationalization**](/docs/internationalization) — localize the
+  language picker and settings copy.
+- [**Onboarding**](/docs/onboarding) — register the setup steps that settings
+  deep links jump users to.
+- [**Workspace Connections**](/docs/workspace-connections) — the shared
+  provider-connection model behind provider readiness.

package/docs/content/toolkit-setup-connections.mdx

@@ -105,5 +105,10 @@ settings live in one predictable place.
 - Builder connect is offered as a first-class path, not buried as an env-var
   fallback.
 
-Related docs: [Onboarding](/docs/onboarding),
-[Workspace Connections](/docs/workspace-connections), [Security](/docs/security).
+## What's next
+
+- [**Onboarding**](/docs/onboarding) — the setup-step registry this kit's UI
+  renders.
+- [**Workspace Connections**](/docs/workspace-connections) — shared provider
+  connections across a multi-app workspace.
+- [**Security**](/docs/security) — how secrets are scoped and stored.

package/docs/content/toolkit-sharing.mdx

@@ -38,7 +38,7 @@ links.
 Make every shareable table ownable, register it at server startup, and guard
 reads and writes with the same access helpers the UI and agent actions use.
 
-```ts
+```ts filename="server/db/schema.ts"
 import { ownableColumns, createSharesTable } from "@agent-native/core/sharing";
 import { registerShareableResource } from "@agent-native/core/sharing";
 
@@ -77,5 +77,48 @@ import { ShareButton, VisibilityBadge } from "@agent-native/core/client";
 - Public access must be an explicit policy choice, not an accidental URL leak.
 - Agents use the same share actions as the UI and cannot bypass resource policy.
 
-Related docs: [Sharing & Privacy](/docs/sharing), [Security](/docs/security),
-[Audit Log](/docs/audit-log).
+## UI components {#ui-components}
+
+`@agent-native/toolkit/sharing` contains presentational sharing UI for badges,
+share rows, role pickers, and base dialogs. It does not perform access checks
+or mutations; core and app wrappers inject data and callbacks.
+
+<WireframeBlock id="doc-block-toolkit-sharing-ui">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:480px;box-sizing:border-box;padding:26px;display:grid;grid-template-columns:1fr 300px;gap:16px'><main class='wf-card' style='display:flex;flex-direction:column;gap:14px'><div style='display:flex;align-items:center;gap:10px'><h2 style='margin:0'>Roadmap</h2><span class='wf-pill accent'>Org visible</span><div style='flex:1'></div><button><span data-icon='user'></span> Share</button></div><small class='wf-muted'>Visibility badges</small><div style='display:flex;gap:6px'><span class='wf-pill'><span data-icon='lock'></span> Private</span><span class='wf-pill'>Shared</span><span class='wf-pill accent'>Org</span><span class='wf-pill'>Public</span></div><div style='display:flex;flex-direction:column;gap:8px'><div style='height:11px;width:88%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:72%;background:var(--wf-line);border-radius:4px'></div></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Share</strong><div style='display:flex;align-items:center;gap:10px'><div style='width:28px;height:28px;border-radius:999px;background:var(--wf-accent-soft);flex:none'></div><div style='flex:1;min-width:0'><strong>Maya Chen</strong><br/><small class='wf-muted'>maya@acme.com</small></div><span class='wf-pill'>Editor <span data-icon='chevronDown'></span></span></div><div class='wf-card' style='display:flex;flex-direction:column;gap:2px;padding:6px'><div style='padding:6px 8px;border-radius:6px;background:var(--wf-accent-soft);display:flex;align-items:center;gap:8px'><span data-icon='check'></span> Editor</div><div style='padding:6px 8px'>Viewer</div><div style='padding:6px 8px'>Remove</div></div><div style='display:flex;align-items:center;gap:8px'><span data-icon='lock'></span><small class='wf-muted'>Public links disabled by policy</small></div></aside></div>"
+    }
+  />
+</WireframeBlock>
+
+The most common low-level import is:
+
+```tsx
+import { VisibilityBadge } from "@agent-native/toolkit/sharing";
+```
+
+`<ShareButton>` and `<ShareDialog>` are core-owned rather than Toolkit-owned —
+they call sharing actions directly, so keep importing them from
+`@agent-native/core/client` as shown above. Those imports stay compatible:
+core wrappers keep doing the runtime work and pass data and callbacks into
+Toolkit-owned UI.
+
+### Toolkit vs Core {#toolkit-vs-core}
+
+Toolkit sharing UI renders badges, rows, base dialogs, and role pickers when
+data and callbacks are injected. Core sharing code owns SQL, permissions,
+request context, org membership lookups, share tables, resource registration,
+access filters, visibility changes, invites, roles, and the private access
+tokens that back agent-readable public surfaces.
+
+## What's next
+
+- [**Sharing & Privacy**](/docs/sharing) — the framework-level access model
+  these components render.
+- [**Security**](/docs/security) — how access filters and scoped reads keep
+  shared data safe.
+- [**Audit Log**](/docs/audit-log) — how visibility and grant changes get
+  recorded.
+- [**Collaboration Kit**](/docs/toolkit-collaboration) — the same Toolkit/Core
+  split applied to realtime editing and presence.

package/docs/content/toolkit-ui.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Toolkit UI Primitives"
-description: "How to use @agent-native/toolkit UI primitives without locking apps out of customization."
+description: "How to use @agent-native/toolkit UI primitives, the local app-adapter pattern, and shared shell hooks without locking apps out of customization."
 ---
 
 # Toolkit UI Primitives
@@ -28,34 +28,58 @@ 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
+```css filename="app/global.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:
+## App adapters {#app-adapters}
+
+Template app code should import a local adapter instead of a Toolkit
+primitive directly:
 
 ```tsx
 import { Button } from "@/components/ui/button";
 ```
 
-The adapter starts as a one-line re-export:
+Every template exposes these adapters under `@/components/ui/*`, and local
+hook adapters under `@/hooks/*` (see [Shell hooks](#shell-hooks) below). Most
+adapters are intentionally tiny — a one-line re-export:
 
-```tsx
+```tsx filename="app/components/ui/button.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`.
+<WireframeBlock id="doc-block-toolkit-app-adapters">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:460px;box-sizing:border-box;padding:28px;display:flex;flex-direction:column;gap:16px'><h2 style='margin:0'>One stable import path</h2><div style='display:grid;grid-template-columns:1fr auto 1fr auto 1fr;align-items:center;gap:12px'><div class='wf-card' style='display:flex;flex-direction:column;gap:8px'><span class='wf-pill'>Toolkit</span><strong>@agent-native/toolkit/ui/button</strong><small class='wf-muted'>Default behavior and accessibility</small></div><span data-icon='chevronRight' style='justify-self:center'></span><div class='wf-card' style='display:flex;flex-direction:column;gap:8px;border:1.6px solid var(--wf-accent);background:var(--wf-accent-soft)'><span class='wf-pill accent'>App adapter</span><strong>@/components/ui/button</strong><small class='wf-muted'>Re-export, swap once to restyle</small></div><span data-icon='chevronRight' style='justify-self:center'></span><div class='wf-card' style='display:flex;flex-direction:column;gap:8px'><span class='wf-pill'>App screens</span><div style='display:flex;align-items:center;gap:8px'><span data-icon='settings'></span> Settings</div><div style='display:flex;align-items:center;gap:8px'><span data-icon='user'></span> Share dialog</div><div style='display:flex;align-items:center;gap:8px'><span data-icon='search'></span> Command menu</div></div></div></div>"
+    }
+  />
+</WireframeBlock>
 
-## Provider Overrides {#provider-overrides}
+This pattern gives apps a stable customization point. Reusable Toolkit code can
+ship once, while app owners can replace `Button`, `Input`, or `Dialog` locally
+without rewriting every callsite: when an app wants its own button, it
+replaces that one adapter file, and the rest of the app keeps importing
+`@/components/ui/button`.
+
+**Import rule:** inside app code, import from the local adapter
+(`@/components/ui/button`); inside Toolkit or other reusable packages, import
+directly from `@agent-native/toolkit/ui/*`. Reusable kit components that
+render app chrome should prefer reading overridable primitives from
+`ToolkitProvider` instead of importing an adapter directly — see
+[Provider overrides](#provider-overrides) below.
+
+### 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
+```tsx filename="app/components/ui/toolkit-provider.tsx"
 import { ToolkitProvider } from "@agent-native/toolkit/provider";
 
 import { Button } from "@/components/ui/button";
@@ -74,5 +98,52 @@ 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.
+Existing template code that used direct Toolkit imports has been migrated to
+local adapters, and new template code should follow the same pattern. Toolkit
+still exports every primitive directly, so external, non-template packages can
+keep importing `@agent-native/toolkit/ui/*` without adopting local adapters.
+Core also keeps old imports working through its own re-export shims for code
+written before Toolkit adapters existed.
+
+## Shell hooks {#shell-hooks}
+
+Toolkit includes small shell helpers and hooks that are useful across apps:
+
+<WireframeBlock id="doc-block-toolkit-shell-hooks">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:460px;box-sizing:border-box;padding:24px;display:grid;grid-template-columns:200px 1fr;gap:16px'><aside class='wf-card' style='display:flex;flex-direction:column;gap:6px'><strong style='margin-bottom:4px'>Analytics</strong><div style='padding:6px 9px;border-radius:8px;background:var(--wf-accent-soft)'>Dashboards</div><div style='padding:6px 9px;border-radius:8px'>Reports</div><div style='padding:6px 9px;border-radius:8px'>Settings</div></aside><main style='position:relative;display:flex;flex-direction:column;gap:14px'><div class='wf-card' style='display:flex;align-items:center;gap:10px'><h2 style='margin:0'>Dashboards</h2><div style='flex:1'></div><button><span data-icon='send'></span> Export</button><button class='primary'><span data-icon='plus'></span> Create</button></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:8px'><div style='height:11px;width:70%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:90%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:80%;background:var(--wf-line);border-radius:4px'></div></div><div class='wf-card' style='display:flex;align-items:center;gap:8px;border-color:var(--wf-accent);position:absolute;right:0;bottom:0;width:230px'><span data-icon='check'></span><div style='flex:1'>Saved changes</div><span data-icon='x'></span></div></main></div>"
+    }
+  />
+</WireframeBlock>
+
+```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 wrap these through the same local-adapter pattern as UI primitives (see
+[App adapters](#app-adapters) above):
+
+```ts filename="app/hooks/use-mobile.ts"
+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.
+
+## What's next
+
+- [**Agent-Native Toolkit**](/docs/agent-native-toolkit) — the hub page linking
+  every kit and foundation piece.
+- [**Sharing Kit**](/docs/toolkit-sharing) — another kit that splits Toolkit UI
+  from Core-owned runtime and access checks.
+- [**Collaboration Kit**](/docs/toolkit-collaboration) — the same Toolkit/Core
+  split applied to realtime editing and presence.
+- [**Component API**](/docs/components) — the generated reference for public
+  React exports, including the primitives covered here.

package/docs/content/tracking.mdx

@@ -121,12 +121,13 @@ Need a custom backend, the provider-registry API, or the batching/singleton inte
 
 Call `track()` from action handlers to record user or agent activity:
 
-```ts
-// actions/create-project.ts
+```ts filename="actions/create-project.ts"
 import { defineAction } from "@agent-native/core/action";
 import { track } from "@agent-native/core/tracking";
 import { z } from "zod";
 
+import { getDb, schema } from "../server/db/index.js";
+
 export default defineAction({
   description: "Create a new project.",
   schema: z.object({
@@ -134,14 +135,15 @@ export default defineAction({
     template: z.string().optional(),
   }),
   run: async ({ name, template }, ctx) => {
-    const project = await db
-      .insert(projects)
+    const db = getDb();
+    const [project] = await db
+      .insert(schema.projects)
       .values({ name, template })
       .returning();
 
-    track("project.created", { name, template }, { userId: ctx.userEmail });
+    track("project.created", { name, template }, { userId: ctx?.userEmail });
 
-    return { ok: true, projectId: project[0].id };
+    return { ok: true, projectId: project.id };
   },
 });
 ```
@@ -349,5 +351,5 @@ The framework also tracks `builder connect clicked` from Connect Builder CTAs, a
 ## What's next
 
 - [**Actions**](/docs/actions) — where most tracking calls originate
-- [**Server Plugins**](/docs/server) — `registerBuiltinProviders()` runs in the core-routes plugin at startup
-- [**Secrets**](/docs/security) — manage API keys for tracking providers
+- [**Server Plugins**](/docs/server#server-plugins) — `registerBuiltinProviders()` runs in the core-routes plugin at startup
+- [**Security — Secrets Management**](/docs/security#secrets) — manage API keys for tracking providers

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

@@ -75,8 +75,6 @@ This works because the current navigation and selection live in `application_sta
 
 </Callout>
 
-→ [**Context Awareness**](/docs/context-awareness) — navigation state, view-screen, navigate commands, and how the agent stays in sync with your screen.
-
 ## You direct it {#you-direct-it}
 
 Most of the time you steer the agent by typing into the chat. Two things make that faster.
@@ -85,28 +83,18 @@ Most of the time you steer the agent by typing into the chat. Two things make th
 
 **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.
-→ [**Voice Input**](/docs/voice-input) — dictation in the chat composer and how transcription is routed.
-
 ## You embed it {#you-embed-it}
 
 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.
-→ [**Agent Surfaces**](/docs/agent-surfaces) — choose whether the workflow should be headless, chat-first, embedded, or a full app.
-
 ## You can go UI-light {#ui-light}
 
 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.
 
-→ [**Automation-First Apps**](/docs/pure-agent-apps) — no-browser apps for jobs, queues, scripts, and external agents.
-
 ## You co-edit with it {#you-co-edit}
 
 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.
-
 ## What's next {#whats-next}
 
 - [**Context Awareness**](/docs/context-awareness) — the agent knows what you're looking at

package/docs/content/voice-input.mdx

@@ -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 `"auto"` (default — picks the best available provider), `"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"`, `"gemini"`, `"groq"`, `"openai"`, or `"browser"` in the sidebar settings. `"builder"` is a legacy alias that resolves to `"builder-gemini"` — new code should write `"builder-gemini"` directly.
 
 <Diagram id="doc-block-1q55wvc" title="Voice transcription provider fallback" summary={"The composer records audio, then walks server providers in order, dropping to the browser Web Speech API only when no server provider is available."}>
 
@@ -123,6 +123,12 @@ The composer POSTs the recorded clip here; the route resolves a provider and ret
 
 You don't need to call this directly — the composer does. If you're building a custom input surface, first reuse the shared composer/voice client pieces from `@agent-native/core/client`. Treat this route as the low-level transport boundary for custom helpers that need to send multipart audio.
 
+## Realtime speech mode {#realtime-speech-mode}
+
+Beyond one-shot dictation, the composer also offers a live, hands-free conversation mode. When the mic opens, a popover lets you choose **Realtime speech** or **Editable dictation**. Realtime speech requires a user-scoped `OPENAI_API_KEY` and connects the browser to `gpt-realtime-2.1` over WebRTC. The chat collapses into a speech orb in the bottom-end corner; click the orb to show or hide chat without ending the conversation.
+
+The speech model uses the same authenticated Agent Native tools as chat, so it can navigate the app and call actions while it talks. Approval-gated actions remain paused until you approve them. Audio is never stored in SQL; Agent Native keeps only compact session and transcript state. A realtime session lasts at most 60 minutes.
+
 ## Customizing the provider {#customizing}
 
 The provider field is a plain application-state key, so the agent can change it on request (`"use the browser speech recognizer instead"`). If you're building a template with different requirements — say, an on-prem Whisper deployment — swap the route handler by registering your own `transcribe-voice` route before the framework mounts the default.

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

@@ -130,9 +130,8 @@ The argument isn't "agents replace UI." It's "**agents belong inside application
 
 This is the defining principle.
 
-> **From the UI** — click buttons, fill forms, navigate views. The UI writes to the database; the agent sees the results.
->
-> **From the agent** — natural language, other agents via A2A, Slack, Telegram. The agent writes to the database; the UI updates automatically.
+- **From the UI** — click buttons, fill forms, navigate views. The UI writes to the database; the agent sees the results.
+- **From the agent** — natural language, other agents via A2A, Slack, Telegram. The agent writes to the database; the UI updates automatically.
 
 A good mental model is a shared state machine. The user surface and the agent
 surface both submit typed actions; those actions behave like reducer events with
@@ -353,23 +352,23 @@ If you're building or extending an agent-native app, here's the central pattern:
   filename="actions/reply-to-email.ts"
   language="ts"
   code={
-    'import { defineAction } from "@agent-native/core/action";\nimport { z } from "zod";\n\nexport default defineAction({\n  description: "Reply to an email thread",\n  schema: z.object({ emailId: z.string(), body: z.string() }),\n  run: async ({ emailId, body }) => {\n    // db and schema come from your app\'s server/db setup\n    await db.insert(schema.replies).values({ emailId, body });\n  },\n});'
+    'import { defineAction } from "@agent-native/core/action";\nimport { z } from "zod";\n\nimport { getDb, schema } from "../server/db/index.js";\n\nexport default defineAction({\n  description: "Reply to an email thread",\n  schema: z.object({ emailId: z.string(), body: z.string() }),\n  run: async ({ emailId, body }) => {\n    const db = getDb();\n    await db.insert(schema.replies).values({ emailId, body });\n  },\n});'
   }
   annotations={[
     {
-      lines: "5",
+      lines: "7",
       label: "Tool surface",
       note: "The `description` is what the agent reads to decide when to call this as a tool.",
     },
     {
-      lines: "6",
+      lines: "8",
       label: "Typed contract",
       note: "One zod `schema` validates input from **every** surface — agent, UI, HTTP, MCP, and A2A.",
     },
     {
-      lines: "7-10",
+      lines: "9-12",
       label: "One implementation",
-      note: "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this.",
+      note: "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this. `getDb()` and `schema` come from your app's `server/db/index.ts` — see [Database](/docs/database).",
     },
   ]}
 />