@agent-native/core 0.153.6 → 0.153.9

package/docs/content/client-data.mdx

@@ -0,0 +1,432 @@
+---
+title: "Data & Sync"
+description: "The action hooks app/ uses to read, write, and stay live-synced with the same actions the agent calls."
+---
+
+# Data & Sync
+
+The primary way to read and write app data from client application is through [action](/docs/actions) hooks. By embedding requests into actions, both your client and agent can interact with your application in the same way.
+
+In the example below, a ticket is assigned to the current user manually through a dropdown, and then through the chat agent. Both the UI and agent access the same action.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa5548a35d1494c1f8a4f960fbe8d9b2c%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=a5548a35d1494c1f8a4f960fbe8d9b2c&alt=media&optimized=true"
+  alt="Example of a UI action and an agent action having the same result."
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Example of a UI action and an agent action having the same result."
+/>
+
+## Fetch and mutate data {#fetching-mutating}
+
+A typical app builds its own API layer and calls it with hand-written `fetch` requests. An agent-native app skips that layer: `app/` calls the same actions the agent already has as tools, through the hooks below.
+
+<Diagram id="doc-block-client-data-fm-1" title="Typical fetch vs. an action hook" summary="A typical component calls a route only it can reach. An agent-native component calls an action the agent can call too.">
+
+```html
+<div class="diagram-fmcmp">
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Typical</div>
+    <div class="diagram-node">Component</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">fetch("/api/leads/:id")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>Your API route</strong>
+      <small class="diagram-muted">only the frontend can call it</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Database</div>
+  </div>
+  <div class="fmcmp-vs diagram-muted">vs</div>
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Agent Native</div>
+    <div class="diagram-node">Component</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">useActionQuery("get-lead")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">get-lead action</span>
+      <small class="diagram-muted">also an agent tool</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL database</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fmcmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.fmcmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 200px;
+}
+.fmcmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.fmcmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-fmcmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-items: center;
+}
+.fmcmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+### Action hooks {#action-hooks}
+
+There are two action hooks you are most likely to use: `useActionQuery()` and `useActionMutation()`. These two hooks provide access to your app's actions.
+
+#### useActionQuery {#use-action-query}
+
+<Signature
+  id="doc-block-client-data-1"
+  name="useActionQuery"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "The action's registered name.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "The action's input, typed from its `defineAction()` schema.",
+    },
+    {
+      name: "options",
+      type: "UseQueryOptions",
+      optional: true,
+      description:
+        "Everything from the [useQuery options](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) except `queryKey` and `queryFn`, which the hook sets itself.",
+    },
+  ]}
+  returns={{
+    type: "UseQueryResult<TResult>",
+    description:
+      'Cached under `["action", name, params]`. Refetches automatically whenever a mutating action completes, with no manual invalidation needed.',
+  }}
+/>
+
+This hook is intended to be used for read-only actions. It is a thin wrapper around the [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) function.
+
+In the example below, the `list-tickets` action is called. This is similar to making a GET request for all tickets.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery("list-tickets", {});
+```
+
+The following example shows a request to fetch a single ticket, through the `get-ticket` action. A `ticketId` is provided to scope the query to only return a specific ticket. The additional `enabled` option is provided to ensure the query does not automatically run, and instead only runs when a `ticketId` is present.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery(
+  "get-ticket",
+  { ticketId: ticketId ?? "" },
+  { enabled: Boolean(ticketId) },
+);
+```
+
+#### useActionMutation {#use-action-mutation}
+
+<Signature
+  id="doc-block-client-data-2"
+  name="useActionMutation"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "The action's registered name.",
+    },
+    {
+      name: "options",
+      type: "UseMutationOptions",
+      optional: true,
+      description:
+        "Everything from the [useMutation options](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) except `mutationFn`, which the hook sets itself.",
+      fields: [
+        {
+          name: "method",
+          type: '"POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "Overrides the default request method.",
+        },
+        {
+          name: "skipActionQueryInvalidation",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "Opts out of the automatic cache refresh on success.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "UseMutationResult",
+    description:
+      'On success, emits a change event with `source: "action"`, so every `useActionQuery()` reading affected data refetches automatically. No manual invalidation is needed.',
+  }}
+/>
+
+This hook is intended to be used for actions that change data, like creating, updating, or sending something. It is a thin wrapper around the [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) function.
+
+Unlike `useActionQuery()`, the action's input is not passed to the hook itself. It is passed to `mutate()` or `mutateAsync()` when you are ready to run the mutation.
+
+In the example below, the `send-ticket-reply` action is called to post a reply to a ticket. Call `mutate()` from an event handler, such as a button's `onClick`.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply");
+
+mutate({ ticketId, body: draft });
+```
+
+The following example shows the same mutation with an `onSuccess` option. Cache invalidation happens automatically after every mutation, so `onSuccess` is only needed for local side effects, like clearing the reply composer once the reply is sent.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply", {
+  onSuccess: () => setDraft(""),
+});
+
+mutate({ ticketId, body: draft });
+```
+
+### callAction {#call-action}
+
+<Signature
+  id="doc-block-client-data-3"
+  name="callAction"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "The action's registered name.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "The action's input, typed from its `defineAction()` schema.",
+    },
+    {
+      name: "options",
+      type: "ClientActionCallOptions",
+      optional: true,
+      description: "Everything below is optional.",
+      fields: [
+        {
+          name: "method",
+          type: '"GET" | "POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "Overrides the default request method.",
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description: "Cancels the request.",
+        },
+        {
+          name: "timeoutMs",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "Overrides the default 60 second timeout, for actions that legitimately take longer.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TResult>",
+    description:
+      "Unlike the hooks above, there is no cache and no automatic refetch. Pair it with a manual invalidation if other UI depends on the result.",
+  }}
+/>
+
+This function is for imperative one-off action calls outside of a React render flow, such as a plain event handler, a script, or any other non-React code path. It returns a promise directly instead of a hook result.
+
+In the example below, the `update-ticket` action is called from a keyboard shortcut handler outside of React's render flow, assigning the ticket to a rep.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction("update-ticket", {
+  ticketId,
+  assignedToEmail: "jordan@example.com",
+});
+```
+
+The following example shows the same call with a `timeoutMs` option, useful for actions that legitimately take longer than the default 60 second timeout.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction(
+  "update-ticket",
+  { ticketId, assignedToEmail: "jordan@example.com" },
+  { timeoutMs: 120_000 },
+);
+```
+
+Every `useActionQuery()`, `useActionMutation()`, and `callAction()` request is bounded by a 60 second timeout, and timeouts surface as errors instead of retrying silently. `useActionQuery()` also cancels superseded requests automatically, using React Query's abort signal.
+
+## useDbSync {#usedbsync}
+
+<Signature
+  id="doc-block-client-data-4"
+  name="useDbSync"
+  params={[
+    {
+      name: "options",
+      type: "UseDbSyncOptions",
+      description: "Every field is optional.",
+      fields: [
+        {
+          name: "queryClient",
+          type: "QueryClient",
+          optional: true,
+          description: "React Query client used for cache invalidation.",
+        },
+        {
+          name: "pollUrl",
+          type: "string",
+          optional: true,
+          default: '"/_agent-native/poll"',
+          description: "Poll endpoint URL.",
+        },
+        {
+          name: "sseUrl",
+          type: "string | false",
+          optional: true,
+          default: '"/_agent-native/events"',
+          description: "SSE endpoint URL. Pass `false` to use polling only.",
+        },
+        {
+          name: "interval",
+          type: "number",
+          optional: true,
+          default: "2000",
+          description: "Polling interval in ms.",
+        },
+        {
+          name: "fallbackInterval",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "Poll interval while SSE is connected, as a backup in case an event is missed. A disconnected tab polls at the faster `interval` (or a fixed idle cadence) instead.",
+        },
+        {
+          name: "pauseWhenHidden",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "Pause polling when the browser tab is hidden. Hidden tabs keep SSE connected and poll no faster than every 10s while active, 60s once idle.",
+        },
+        {
+          name: "ignoreSource",
+          type: "string",
+          optional: true,
+          description:
+            "Per-tab request source to ignore, so a tab does not refetch from its own writes.",
+        },
+        {
+          name: "onEvent",
+          type: "(data) => void",
+          optional: true,
+          description:
+            "Optional callback when SSE or polling receives a change event.",
+        },
+        {
+          name: "actionInvalidatePredicate",
+          type: "(query: Query) => boolean",
+          optional: true,
+          description:
+            "Filters the broad invalidation an action event triggers. Rarely needed. Use it to keep an expensive active query on explicit-refresh semantics while normal source-versioned queries still react through `useChangeVersion`.",
+        },
+        {
+          name: "suppressActionInvalidationFor",
+          type: "string[]",
+          optional: true,
+          description:
+            "Action names whose sync events should not invalidate all action queries. Only for high-volume background actions that already perform their own narrow invalidation.",
+        },
+        {
+          name: "queryKeys",
+          type: "string[]",
+          optional: true,
+          description: "Deprecated and ignored. Kept for old call sites.",
+        },
+      ],
+    },
+  ]}
+  returns={{ type: "void" }}
+/>
+
+This hook is intended to keep the UI in sync with database changes that happen outside of your own actions, like an agent write, a webhook, or a change made from another browser tab. It listens for changes over server-sent events, and falls back to polling when server-sent events are unavailable.
+
+```ts
+import { useDbSync } from "@agent-native/core/client/hooks";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+For normal CRUD, prefer `useActionQuery()` and `useActionMutation()`. Mutating actions emit `source: "action"`, so those hooks refetch right away. Changes from the agent, a webhook, or another tab arrive through `useDbSync()` instead, over SSE or the polling fallback. If a raw `useQuery()` call needs to sync on a custom key, see [Sync Internals](/docs/client-sync-internals). If you need to write to `application_state` directly, see [Advanced](/docs/client-advanced).
+
+## What's next
+
+- [**Overview**](/docs/client-overview) — the `app/` and `public/` directory layout this page's hooks live in
+- [**Agent Chat**](/docs/client-agent-chat) — sending prompts and staging context for the agent
+- [**Actions**](/docs/actions) — the `defineAction` surface behind every hook on this page
+- [**Advanced**](/docs/client-advanced) — direct `application_state` access
+- [**Sync Internals**](/docs/client-sync-internals) — syncing a raw `useQuery` with `useChangeVersion`
+- [**Real-Time Sync**](/docs/key-concepts#polling-sync) — how `useDbSync` keeps the UI current

package/docs/content/client-entry-points.mdx

@@ -0,0 +1,27 @@
+---
+title: "Entry Points"
+description: "app/entry.client.tsx and app/entry.server.tsx: the thin hydration and SSR bootstrap wrappers, and when to customize streaming behavior."
+---
+
+# Entry Points
+
+`app/entry.client.tsx` hydrates the server-rendered HTML in the browser, and `app/entry.server.tsx` renders that HTML on the server. Both are thin wrappers generated by React Router. You rarely need to edit them.
+
+```ts filename="app/entry.server.tsx"
+import {
+  createDocumentRequestHandler,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";
+import { ServerRouter } from "react-router";
+
+export default createDocumentRequestHandler(ServerRouter);
+export { streamTimeout };
+```
+
+Reach for these only for advanced SSR customization, for example changing streaming behavior. Ordinary pages, layout, and data don't need changes here. See [Routing](/docs/client-routing) for adding pages instead.
+
+## What's next
+
+- [**Overview**](/docs/client-overview) — where these files sit in `app/`
+- [**Routing**](/docs/client-routing) — adding pages, the normal way to extend `app/`
+- [**Advanced**](/docs/client-advanced) — the other lower-level client primitives and escape hatches

package/docs/content/client-overview.mdx

@@ -0,0 +1,206 @@
+---
+title: "Overview"
+description: "The app/ and public/ directories: where you build the display of an agent-native app, and the browser APIs it uses to stay in sync with the agent."
+---
+
+# Overview
+
+`app/` is where you build the actual display of an agent-native app: pages, layout, components, styles. `public/` holds the static assets served alongside it — icons, manifest, brand marks. This is a typical React Router v8 app, not a special agent-only surface, and it's where most development time goes.
+
+The one architectural difference from a typical frontend: this layer has no backend-for-frontend of its own. It reads and writes data through the same actions the agent calls, so anything wired up here is automatically something the agent can also do.
+
+<Diagram id="doc-block-client-overview-1" title="Traditional frontend vs. Agent Native" summary="A traditional frontend calls its own API layer, which only it can reach. In Agent Native, app/ and the agent both call the same actions, so every capability built here is agent-callable for free.">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Traditional</div>
+    <div class="diagram-node">app/ (React frontend)</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>API layer</strong>
+      <small class="diagram-muted">only the frontend calls it</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Database</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">vs</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/ (React frontend)</div>
+      <div class="diagram-node">Agent</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">equal partners, same operations</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL database</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Where the Client Fits {#role}
+
+Browser requests, the agent loop, and external API clients all resolve to the same actions and the same SQL database — there is no separate "app backend" this layer talks to that the agent can't also reach. Building a feature here means building a UI on top of an operation the agent already has, or defining a new action and getting a UI for it at the same time. See [Actions](/docs/actions) for the operation side of that contract.
+
+This page covers the directories you build in and the pieces of the browser runtime nothing else documents (`root.tsx`, `public/`). The React hooks that connect your components to actions and to the agent live on their own focused pages:
+
+| Page                                              | What it covers                                                                                                      |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| **[Data & Sync](/docs/client-data)**              | `useActionQuery`, `useActionMutation`, `callAction`, and `useDbSync`                                                |
+| **[Agent Chat](/docs/client-agent-chat)**         | `sendToAgentChat`, `askUserQuestion`, `openAgentSettings`, dynamic suggestions, and staged agent chat context state |
+| **[Advanced](/docs/client-advanced)**             | Direct `application_state` access, background chat sends, custom suggestion chips, and the MCP App host bridge      |
+| **[Sync Internals](/docs/client-sync-internals)** | `useChangeVersion`/`useChangeVersions` for syncing a raw `useQuery`                                                 |
+| **[Entry Points](/docs/client-entry-points)**     | `app/entry.client.tsx`/`app/entry.server.tsx` and SSR customization                                                 |
+
+## What's in app/ and public/ {#project-directories}
+
+| Path                                                | What it covers                                                                                                    |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| **`app/root.tsx`**                                  | The HTML shell and provider stack — see [The Browser Shell](#app-shell) below                                     |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | Hydration and SSR bootstrap — see [Entry Points](/docs/client-entry-points)                                       |
+| **`app/routes.ts` + `app/routes/`**                 | File-based pages and navigation — see [Routing](/docs/client-routing)                                             |
+| **`app/components/`**                               | Your UI: shadcn-style primitives plus app-specific components — see [Toolkit UI Primitives](/docs/toolkit-ui)     |
+| **`app/hooks/`**                                    | Data, sync, and agent-chat hooks — see [Data & Sync](/docs/client-data) and [Agent Chat](/docs/client-agent-chat) |
+| **`app/lib/`**                                      | Shared client utilities (app config, tab id, `cn`) — see [Utilities](#utilities) below                            |
+| **`app/design-system.ts`**                          | Optional custom design system adapter — see [Custom Design Systems](/docs/custom-design-system)                   |
+| **`app/i18n/`**                                     | Localized UI copy catalogs — see [Internationalization](/docs/internationalization)                               |
+| **`app/global.css`**                                | Base styles and the Tailwind entry point                                                                          |
+| **`public/`**                                       | Static assets served as-is — see [Static Assets](#public-directory) below                                         |
+
+## The Browser Shell: root.tsx and AppProviders {#app-shell}
+
+`app/root.tsx` is the top of the React tree: the HTML document shell (`<html>`, `<head>`, `<Meta>`, `<Links>`, `<Scripts>`) plus the provider stack every route renders inside.
+
+```tsx filename="app/root.tsx"
+import {
+  AppProviders,
+  createAgentNativeQueryClient,
+} from "@agent-native/core/client/hooks";
+import { useState } from "react";
+import { Outlet } from "react-router";
+import { i18nCatalog } from "./i18n";
+
+export default function Root() {
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
+
+  return (
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <Outlet />
+    </AppProviders>
+  );
+}
+```
+
+`AppProviders` is the single wrapper that wires up:
+
+- The React Query client used by `useActionQuery`/`useActionMutation` (see [Data & Sync](/docs/client-data#fetching-mutating)).
+- The i18n catalog passed as `i18n.catalog` (see [Internationalization](/docs/internationalization)).
+- Client-side session checks: on a private path, an anonymous visitor is redirected to sign-in before any private UI mounts. Pass `isPublicPath` for public/SEO routes, or `sessionBypass` for a surface that authenticates another way, such as an MCP embed token. See [Authentication](/docs/authentication).
+
+Most apps also mount `<AgentSidebar>` or `<AgentPanel>` here so every route gets the agent panel for free. See [Drop-in Agent](/docs/drop-in-agent#sidebar).
+
+## Static Assets: public/ {#public-directory}
+
+Everything in `public/` is served as-is at the site root, unprocessed by the build. Every template ships:
+
+```text
+public/
+  favicon.svg           -> browser tab icon
+  icon-180.svg           -> apple-touch-icon
+  icon-192.svg, icon-512.svg -> PWA icons referenced from manifest.json
+  manifest.json          -> web app manifest (name, theme color, icons)
+  *-logo-*.svg, *-icon-*.svg -> brand marks used in the default UI
+```
+
+`manifest.json` controls what shows up if a visitor installs the app to a home screen or app dock — name, short name, theme/background color, and the icon set:
+
+```json filename="public/manifest.json"
+{
+  "name": "My App",
+  "short_name": "My App",
+  "theme_color": "#18181B",
+  "icons": [
+    { "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }
+  ]
+}
+```
+
+Rebrand an app by replacing these files and updating `manifest.json` and the `<link rel="icon">`/`<link rel="apple-touch-icon">` tags in `root.tsx` that reference them — there's no separate registration step. For pulling a full brand system (colors, fonts, favicon) from an existing site instead of hand-editing these, see [Brand Systems and Figma](/docs/template-design-brand-and-figma).
+
+## Utilities: cn {#utilities}
+
+```ts
+import { cn } from "@agent-native/toolkit/utils";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```
+
+`cn` merges class names (clsx + tailwind-merge) and is the standard way to compose conditional Tailwind classes across `app/components/`.
+
+## What's next
+
+- [**Data & Sync**](/docs/client-data) — action hooks and `useDbSync`
+- [**Agent Chat**](/docs/client-agent-chat) — `sendToAgentChat`, `askUserQuestion`, and dynamic suggestions
+- [**Advanced**](/docs/client-advanced) — application state, background chat sends, and the MCP App host bridge
+- [**Sync Internals**](/docs/client-sync-internals) — `useChangeVersion` for syncing a raw `useQuery`
+- [**Entry Points**](/docs/client-entry-points) — SSR bootstrap customization
+- [**Routing**](/docs/client-routing) — file-based pages, dynamic params, and navigation
+- [**Actions**](/docs/actions) — the `defineAction` surface behind every data hook
+- [**Custom Design Systems**](/docs/custom-design-system) — swapping in your own component library via `app/design-system.ts`
+- [**Authentication**](/docs/authentication) — the session checks `AppProviders` runs on private paths