@agent-native/core 0.62.1 → 0.63.1

package/docs/content/template-slides.md

@@ -89,53 +89,53 @@ Ask the agent for a deck and it builds one slide at a time. Slides stream into t
 
 Under the hood, this is powered by the `add-slide` and `create-deck` actions in `templates/slides/actions/`.
 
-### Seven slide layouts
+#### Seven slide layouts
 
 Built-in layouts: title, section divider, content with bullets, two-column, statement or quote, metrics or stats, and closing or CTA. Each layout is a pure HTML template with inline styles — the agent picks the right one based on slide purpose. The exact templates live inside `templates/slides/.agents/skills/create-deck/SKILL.md` so the agent can reference them without exploring the codebase.
 
-### Visual and code editing
+#### Visual and code editing
 
 - Double-click any text to edit inline.
 - Click a block to open the bubble menu for styles, alignment, and layout.
 - Switch to the code editor (`app/components/editor/CodeEditor.tsx`) to edit raw slide HTML.
 - Use the slash menu (`SlideSlashMenu.tsx`) to insert blocks by typing `/`.
 
-### AI image generation
+#### AI image generation
 
 Generate images through the Assets app when brand libraries matter; once the managed backend is deployed, that path can use Builder-managed image generation and keep the audit trail with the source library. Direct provider-key generation remains the fallback for standalone decks.
 
 Actions: `generate-image`, `edit-image`, `image-search`, `logo-lookup`. UI panels: `ImageGenPanel.tsx`, `ImageSearchPanel.tsx`, `LogoSearchPanel.tsx`.
 
-### Logo and stock image search
+#### Logo and stock image search
 
 - `logo-lookup --domain acme.com` fetches a company logo via Logo.dev or Brandfetch.
 - `image-search --query "mountain landscape"` searches Google Images for stock photos.
 
-### Comments and threads
+#### Comments and threads
 
 Leave comments on specific slides, quote selected text, and reply in threads. Stored in the `slide_comments` table. Actions: `add-slide-comment`, `list-slide-comments`.
 
-### Drag and drop reordering
+#### Drag and drop reordering
 
 Reorder slides in the sidebar, duplicate, or delete with hover controls. The sidebar lives in `app/components/editor/EditorSidebar.tsx`.
 
-### Presentation mode
+#### Presentation mode
 
 Full-screen presentation at `/deck/:id/present` with keyboard navigation (arrow keys, space, escape), auto-hiding controls, and speaker notes. See `app/routes/deck.$id_.present.tsx` and `app/components/presentation/PresentationView.tsx`.
 
-### Share links
+#### Share links
 
 Generate a public read-only URL for a deck so reviewers can view without an account. The share page is `app/routes/share.$token.tsx`. Fine-grained sharing (viewer, editor, admin roles, per-user or org-wide) is also available via the framework's `share-resource` action.
 
-### Real-time collaboration
+#### Real-time collaboration
 
 Multiple people can edit the same deck simultaneously. Text edits sync through Yjs CRDT so there are no conflicts, and the agent sees and edits the same live document via the `update-slide --find/--replace` action.
 
-### Undo and redo
+#### Undo and redo
 
 Cmd+Z and Cmd+Shift+Z work across the whole deck, with a labeled history panel (`HistoryPanel.tsx`) you can scrub through.
 
-### Extract from PDF
+#### Extract from PDF
 
 Turn a PDF into a starter deck. The `extract-pdf` action parses the file and hands the content to the agent for layout.
 
@@ -143,7 +143,7 @@ Turn a PDF into a starter deck. The `extract-pdf` action parses the file and han
 
 The agent chat lives in the sidebar. It can create decks, edit individual slides, generate images, search logos, and navigate the UI — all using the same actions you'd run from the CLI.
 
-### What the agent sees
+#### What the agent sees
 
 When a deck is open, the agent automatically sees:
 
@@ -153,11 +153,11 @@ When a deck is open, the agent automatically sees:
 
 This is injected into every message as a `current-screen` block, so the agent never has to guess what "this slide" means. The data comes from the `navigation` application-state key, which the UI writes on every navigation. See `templates/slides/actions/view-screen.ts`.
 
-### Selecting text for focused edits
+#### Selecting text for focused edits
 
 Select text on a slide and hit Cmd+I to focus the agent with that selection pre-loaded. The agent will act only on what you selected.
 
-### Inline slide previews in chat
+#### Inline slide previews in chat
 
 The agent can embed a live slide preview directly in a chat reply using the framework's embed fence. It renders a chromeless iframe via `app/routes/slide.tsx` so you can see the result without leaving the conversation.
 

package/docs/content/template-videos.md

@@ -75,15 +75,13 @@ pnpm dev
 
 Open the studio in your browser, create a composition, and start from blank. Ask the agent something like "add a logo reveal that fades in at 2 seconds" and it will edit the composition for you.
 
-Live demo: [videos.agent-native.com](https://videos.agent-native.com).
-
 ### Key features (technical)
 
-### React-based compositions
+#### React-based compositions
 
 Every video is a React component built on Remotion primitives (`AbsoluteFill`, `useCurrentFrame`, `useVideoConfig`). The template ships one in-code composition — `BlankComposition` in `app/remotion/compositions/BlankComposition.tsx` — and `app/remotion/registry.ts` exports an empty `compositions` array by default. User and example compositions (kinetic text, logo reveals, particle bursts, interactive UI demos, slideshows) live in SQL and load through `app/hooks/use-database-compositions.ts`. You can still add a code composition by dropping a `.tsx` file in `app/remotion/compositions/` and registering it in `app/remotion/registry.ts`.
 
-### Timeline tracks
+#### Timeline tracks
 
 Animations are tracks, not hardcoded frame checks. A track has `startFrame`, `endFrame`, `easing`, and a list of `animatedProps` (`opacity`, `translateY`, `scale`, rotation, colors, etc.). Three track shapes:
 
@@ -93,35 +91,35 @@ Animations are tracks, not hardcoded frame checks. A track has `startFrame`, `en
 
 Helper utilities in `app/remotion/trackAnimation.ts` (`findTrack`, `trackProgress`, `getPropValue`) wire a track's values into a component's render.
 
-### Easing curves
+#### Easing curves
 
 30+ easing curves ship in `app/types.ts` — linear, power1-4 in/out/inOut, back, bounce, circ, elastic, expo, sine, and Remotion's `spring`. The Properties panel shows a visual preview of the curve shape for each one.
 
-### Camera controls
+#### Camera controls
 
 Each composition has a dedicated `camera` track with six animatable properties: `translateX`, `translateY`, `scale`, `rotateX`, `rotateY`, `perspective`. The camera toolbar above the player has pan, zoom, and tilt tools — click a tool, drag on the preview, and a keyframe is auto-created at the current frame. `CameraHost` (in `app/remotion/CameraHost.tsx`) applies the chained CSS 3D transform to everything inside.
 
-### Multi-keyframe editing
+#### Multi-keyframe editing
 
 Every animated property supports an optional `keyframes` array. Interpolation is linear between keyframes, with hold-at-first and hold-at-last at the edges. In the timeline you can box-select keyframes, shift-click to add or remove, and drag groups while keeping relative timing.
 
-### Adjustable parameters
+#### Adjustable parameters
 
 Programmatic animations expose internal magic numbers as user-editable `parameters` — character width, drift distance, particle count, stagger delay. Inputs appear in the Properties panel with min/max/step bounds and save to localStorage automatically.
 
-### Interactive cursor system
+#### Interactive cursor system
 
 The `cursor` track drives a visible cursor that moves across the composition. Hover zones on interactive elements (buttons, tabs, inputs, cards) change the cursor appearance — arrow, pointer, or I-beam. See `app/remotion/hooks/useInteractiveComponent.ts` and `app/remotion/ui-components/InteractiveCard.tsx`.
 
-### View range and repeat playback
+#### View range and repeat playback
 
 The timeline has a range navigator at the bottom (AE-style triangular handles). Drag to zoom and pan the visible time window. Playback in the player is constrained to that range, with a repeat toggle that loops inside it.
 
-### Render output
+#### Render output
 
 Composition size, fps, and render quality are per-composition in the Properties panel. Render quality is supersampling — 1x, 2x, or 3x internal resolution to keep text and vectors crisp during camera zoom. Final render happens via the Remotion CLI to MP4 or WebM.
 
-### Composition persistence
+#### Composition persistence
 
 User edits (track values, parameter values, prop overrides, composition settings) persist to localStorage per composition. The **Save** button in the top-right of the composition view can write the current state back to `app/remotion/registry.ts` as TypeScript — so new users and sessions pick up the changes. That source-write path runs through `POST /api/save-composition-defaults`, which is gated to local development only; in production it returns a 403, and durable composition state lives in SQL instead.
 

package/docs/content/tracking.md

@@ -58,6 +58,66 @@ import { identify } from "@agent-native/core/tracking";
 identify("steve@builder.io", { plan: "pro", company: "Builder.io" });
 ```
 
+Need a custom backend, the provider-registry API, or the batching/singleton internals? See [Advanced: custom providers & internals](#advanced) at the end.
+
+## Using track() in templates {#templates}
+
+Call `track()` from action handlers to record user or agent activity:
+
+```ts
+// actions/create-project.ts
+import { defineAction } from "@agent-native/core/action";
+import { track } from "@agent-native/core/tracking";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Create a new project.",
+  schema: z.object({
+    name: z.string(),
+    template: z.string().optional(),
+  }),
+  run: async ({ name, template }, ctx) => {
+    const project = await db
+      .insert(projects)
+      .values({ name, template })
+      .returning();
+
+    track("project.created", { name, template }, { userId: ctx.userEmail });
+
+    return { ok: true, projectId: project[0].id };
+  },
+});
+```
+
+Track calls are fire-and-forget — they return immediately and never block the action response.
+
+## Client-side tracking {#client}
+
+`track()` also works from browser/app code. Import the client twin from `@agent-native/core/client` and call it the same way — it POSTs the event to the framework route at `POST /_agent-native/track`, which forwards it to the **same** registered server-side providers (PostHog, Mixpanel, Amplitude, webhook). No analytics SDK ships to the browser and no provider keys are exposed client-side.
+
+```ts
+import { track } from "@agent-native/core/client";
+
+// e.g. inside a click handler or effect
+track("checkout.completed", { total: 49.99, items: 3 });
+```
+
+Key differences from the [server `track()`](#track):
+
+- **No identity argument.** The event is attributed server-side to the signed-in user (and the active org, as `org_id` in `properties`). Browser code never passes a `userId`.
+- **`source: "client"`** is added to every event's properties so you can tell client-originated events apart from server ones.
+- **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) below), which powers Agent Native's own product analytics. Use `track()` for your app's own analytics events that should reach your configured providers.
+
+## Advanced: custom providers & internals {#advanced}
+
+Most apps only need `track()` / `identify()` and a built-in provider. The rest of the surface — registering custom providers, the `TrackingProvider` interface, batching internals, and the framework's own browser telemetry — is below.
+
+<details>
+<summary><strong>Provider-registry API, interface, internals, and browser defaults</strong></summary>
+
 ### `registerTrackingProvider(provider)` {#register}
 
 Register a custom provider for any analytics backend.
@@ -102,7 +162,7 @@ Remove a provider by name. Returns `true` if the provider was found and removed.
 
 Returns the names of all registered providers.
 
-## The TrackingProvider interface {#provider-interface}
+### The TrackingProvider interface {#provider-interface}
 
 ```ts
 interface TrackingProvider {
@@ -125,67 +185,16 @@ interface TrackingEvent {
 
 Only `name` and `track` are required. `identify` and `flush` are optional — implement them if your backend supports user identity and batched delivery.
 
-## How it works {#internals}
+### How it works {#internals}
 
 - **Batched HTTP** — built-in providers enqueue events and flush every 10 seconds or when 50 events accumulate, whichever comes first. This minimizes outbound requests without losing data.
 - **No SDK dependencies** — all built-in providers use raw `fetch()`. No PostHog SDK, no Mixpanel SDK, no Amplitude SDK. Keeps the framework lightweight.
 - **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.
 
-## Using track() in templates {#templates}
-
-Call `track()` from action handlers to record user or agent activity:
+### Browser defaults {#browser-defaults}
 
-```ts
-// actions/create-project.ts
-import { defineAction } from "@agent-native/core/action";
-import { track } from "@agent-native/core/tracking";
-import { z } from "zod";
-
-export default defineAction({
-  description: "Create a new project.",
-  schema: z.object({
-    name: z.string(),
-    template: z.string().optional(),
-  }),
-  run: async ({ name, template }, ctx) => {
-    const project = await db
-      .insert(projects)
-      .values({ name, template })
-      .returning();
-
-    track("project.created", { name, template }, { userId: ctx.userEmail });
-
-    return { ok: true, projectId: project[0].id };
-  },
-});
-```
-
-Track calls are fire-and-forget — they return immediately and never block the action response.
-
-## Client-side tracking {#client}
-
-`track()` also works from browser/app code. Import the client twin from `@agent-native/core/client` and call it the same way — it POSTs the event to the framework route at `POST /_agent-native/track`, which forwards it to the **same** registered server-side providers (PostHog, Mixpanel, Amplitude, webhook). No analytics SDK ships to the browser and no provider keys are exposed client-side.
-
-```ts
-import { track } from "@agent-native/core/client";
-
-// e.g. inside a click handler or effect
-track("checkout.completed", { total: 49.99, items: 3 });
-```
-
-Key differences from the [server `track()`](#track):
-
-- **No identity argument.** The event is attributed server-side to the signed-in user (and the active org, as `org_id` in `properties`). Browser code never passes a `userId`.
-- **`source: "client"`** is added to every event's properties so you can tell client-originated events apart from server ones.
-- **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) 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.
+This 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:
 
@@ -197,6 +206,8 @@ Template roots call `configureTracking()` once at startup. Browser events sent w
 
 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.
 
+</details>
+
 ## What's next
 
 - [**Actions**](/docs/actions) — where most tracking calls originate

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

@@ -11,51 +11,41 @@ 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. _(For developers building the app.)_
+→ [**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}
 
-_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. _(For end users and developers.)_
+→ [**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}
 
-_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. _(For developers building the app.)_
-→ [**Agent Surfaces**](/docs/agent-surfaces) — choose whether the workflow should be headless, chat-first, embedded, or a full app. _(For developers designing the product shape.)_
+→ [**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}
 
-_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. _(For end users and developers.)_
+→ [**Pure-Agent Apps**](/docs/pure-agent-apps) — apps where the agent is the whole product.
 
 ## 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. _(For end users and developers.)_
+→ [**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}
 

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

@@ -5,7 +5,7 @@ description: "Why most AI apps feel half-built, what makes an app truly agent-na
 
 # What Is Agent-Native?
 
-Agent-native is a way of building software where the AI agent and the product surface around it are **equal partners**. That surface can be one headless action, a rich chat, or a full UI. The important part is that agents and humans share the same actions, database, and state.
+Agent-native is a way of building software where the AI agent and the product surface around it are **equal partners**. That surface can be a headless agent with one custom action, a rich chat, or a full UI. The important part is that agents and humans share the same actions, database, and state.
 
 If you only remember one thing from this page, remember this: most AI apps today stop one step short of being useful, and that gap is the biggest mistake in the space right now.
 
@@ -62,15 +62,9 @@ Even when the agent does all the heavy lifting, humans still need to:
 - **Inspect its work** — review drafts, audit history, roll back mistakes
 - **Share its output** — dashboards, reports, forms, links to send to teammates
 
-At minimum, "a UI for the agent" is an observability and management dashboard. At maximum, it's a full SaaS app with the agent embedded as a co-pilot. Both ends count as agent-native — see [Pure-Agent Apps](/docs/pure-agent-apps) for the minimal end and [Templates](/docs/cloneable-saas) for the maximal end.
+At minimum, "a UI for the agent" is an observability and management dashboard. At maximum, it's a full SaaS app with the agent embedded as a co-pilot. Both ends count as agent-native, and the surface can grow from one without a rewrite.
 
-There are three useful shapes:
-
-- **Headless** — call the agent and actions from code, HTTP, CLI, MCP, or A2A.
-- **Rich chat** — give the agent a first-class chat UI with native tool widgets such as tables, charts, typed results, approvals, and links into app views. See [Native Chat UI](/docs/native-chat-ui).
-- **Whole app** — put a full application around the agent, with SQL state, context awareness, deep links, and live sync so humans and agents stay in the same workspace.
-
-Agent-native is designed so those are stages, not rewrites. You can start headless, add rich chat, and grow into a full app around the same action surface. See [Agent Surfaces](/docs/agent-surfaces) for the concrete APIs behind each shape.
+You don't have to choose a shape up front. The agent can run headless, sit behind a rich chat, or live inside a full application around the same action surface — see [Agent Surfaces](/docs/agent-surfaces) for the concrete shapes and APIs.
 
 ## Why every app benefits from an agent {#why-every-app-benefits-from-an-agent}
 
@@ -78,7 +72,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**." See [Pure-Agent Apps](/docs/pure-agent-apps) for the full discussion of why agents still need a UI.
+The argument isn't "agents replace UI." It's "**agents belong inside applications, with a UI on top, as equal partners**." Even an app where the agent _is_ the product still needs a UI for humans to supervise, configure, and steer it — see [Agent Surfaces — Headless](/docs/agent-surfaces#headless).
 
 ## Agent + UI parity {#agent-ui-parity}
 
@@ -186,7 +180,7 @@ One action, many surfaces: the agent calls it as a tool, the UI calls it as a ty
 
 ## What's next {#whats-next}
 
-- [**Getting Started**](/docs) — start with one action, pick a template, or install a skill
+- [**Getting Started**](/docs/getting-started) — start with one action, pick a template, or install a skill
 - [**Agent Surfaces**](/docs/agent-surfaces) — choose headless, rich chat, embedded sidecar, or full app
 - [**Key Concepts**](/docs/key-concepts) — the architecture: SQL, actions, polling sync, context awareness, portability
 - [**Templates**](/docs/cloneable-saas) — templates as complete products you own

package/docs/content/workspace-management.md

@@ -5,9 +5,9 @@ description: "Branching, CODEOWNERS, PR review, and how Dispatch handles runtime
 
 # Workspace Governance
 
-This guide covers the operational side of running an agent-native workspace — how to branch, who reviews what, how to set up code ownership, and how the Dispatch control plane fits into your governance model.
+> **Which workspace doc?** This page covers **governance** — who reviews, approves, and owns what across many apps in one repo. For what a workspace _is_ (the customization layer) see [Workspace](/docs/workspace); for the deployment shape (one monorepo, many apps) see [Multi-App Workspaces](/docs/multi-app-workspace).
 
-For workspace setup, shared auth, and deployment, see [Multi-App Workspaces](/docs/multi-app-workspace).
+This guide covers the operational side of running an agent-native workspace — how to branch, who reviews what, how to set up code ownership, and how the Dispatch control plane fits into your governance model.
 
 ## Branching