@agent-native/core 0.153.8 → 0.153.10

package/dist/integrations/catalog.js

@@ -5,6 +5,7 @@
  * Runtime behavior stays in adapters and plugins; consumers must use
  * availability and support maturity before offering a connection flow.
  */
+import { docsUrl } from "../shared/docs-url.js";
 export const INTEGRATION_CATEGORIES = [
     "channel",
     "provider",
@@ -26,7 +27,7 @@ const BUILT_IN_CHANNEL_CATALOG = [
             "Managed installations select encrypted credentials by workspace; legacy manual installs should use SLACK_ALLOWED_TEAM_IDS.",
         ],
         documentation: {
-            href: "/docs/messaging#slack",
+            href: docsUrl("messaging", { hash: "slack" }),
             externalHref: "https://api.slack.com/apps",
             externalLabel: "Open Slack apps",
         },
@@ -88,7 +89,7 @@ const BUILT_IN_CHANNEL_CATALOG = [
             "Production deployments must allowlist Microsoft Entra tenant IDs; proactive messaging without an inbound conversation reference is not implemented.",
         ],
         documentation: {
-            href: "/docs/messaging#microsoft-teams",
+            href: docsUrl("messaging", { hash: "microsoft-teams" }),
             externalHref: "https://dev.botframework.com/",
             externalLabel: "Open Bot Framework",
         },
@@ -148,7 +149,7 @@ const BUILT_IN_CHANNEL_CATALOG = [
             "Interaction tokens are retained only while the queued task is active and normally expire after 15 minutes.",
         ],
         documentation: {
-            href: "/docs/messaging#discord",
+            href: docsUrl("messaging", { hash: "discord" }),
             externalHref: "https://discord.com/developers/applications",
             externalLabel: "Open Discord applications",
         },
@@ -197,7 +198,7 @@ const BUILT_IN_CHANNEL_CATALOG = [
             "Webhook verification requires TELEGRAM_WEBHOOK_SECRET for production-safe setup.",
         ],
         documentation: {
-            href: "/docs/messaging#telegram",
+            href: docsUrl("messaging", { hash: "telegram" }),
             externalHref: "https://t.me/BotFather",
             externalLabel: "Open BotFather",
         },
@@ -246,7 +247,7 @@ const BUILT_IN_CHANNEL_CATALOG = [
             "Meta pricing and the customer-service conversation window can limit replies; template-message flows are not implemented by this adapter.",
         ],
         documentation: {
-            href: "/docs/messaging#whatsapp",
+            href: docsUrl("messaging", { hash: "whatsapp" }),
             externalHref: "https://developers.facebook.com/apps",
             externalLabel: "Open Meta developer console",
         },
@@ -303,7 +304,7 @@ const BUILT_IN_CHANNEL_CATALOG = [
             "Email replies preserve RFC email threads and reply-all when the agent was CC'd.",
         ],
         documentation: {
-            href: "/docs/messaging#email",
+            href: docsUrl("messaging", { hash: "email" }),
             externalHref: "https://resend.com/webhooks",
             externalLabel: "Open Resend webhooks",
         },
@@ -363,7 +364,7 @@ const AUTOMATION_CATALOG = [
             "Use a configured webhook URL or n8n credential; never put an n8n URL or credential in an agent prompt.",
         ],
         documentation: {
-            href: "/docs/automation-connectors#n8n",
+            href: docsUrl("automation-connectors", { hash: "n8n" }),
             externalHref: "https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/",
             externalLabel: "Open n8n Webhook docs",
         },
@@ -405,7 +406,7 @@ const AUTOMATION_CATALOG = [
             "Zapier MCP is a separately configured remote MCP connection with its own account and authorization flow.",
         ],
         documentation: {
-            href: "/docs/automation-connectors#zapier",
+            href: docsUrl("automation-connectors", { hash: "zapier" }),
             externalHref: "https://docs.zapier.com/mcp/home",
             externalLabel: "Open Zapier MCP docs",
         },

package/dist/notifications/routes.d.ts

@@ -28,6 +28,6 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
 } | {
     count?: undefined;
     updated?: undefined;
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/observability/routes.d.ts

@@ -41,16 +41,16 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
+    error?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-    error?: undefined;
     ok?: undefined;
 } | {
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
-    error?: undefined;
     ok?: undefined;
 } | {
     summary?: undefined;
@@ -59,9 +59,9 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     error: any;
     ok?: undefined;
 } | {
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     ok: boolean;
-    error?: undefined;
 }>>;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/server/agent-chat-plugin.js

@@ -34,6 +34,7 @@ import { getSkillNameFromPath } from "../resources/metadata.js";
 import { resourceList, resourceListAccessible, resourceGet, ensurePersonalDefaults, SHARED_OWNER, WORKSPACE_OWNER, } from "../resources/store.js";
 import { normalizeDatabaseToolsMode } from "../scripts/db/tool-mode.js";
 import { getSetting, putSetting } from "../settings/store.js";
+import { docsUrl } from "../shared/docs-url.js";
 import { handleSharedThreadRequest, } from "./agent-chat/shared-thread.js";
 import { discoverAgents } from "./agent-discovery.js";
 import { resolveAgentRunOwnerContext, runWithAgentRunContext, seedBackgroundAgentRunOwnerContext, } from "./agent-run-context.js";
@@ -3510,8 +3511,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                 }
                 const result = { skills };
                 if (skills.length === 0) {
-                    result.hint =
-                        "No skills found. Add skill files under skills/ in Resources. Learn more: https://agent-native.com/docs/resources#skills";
+                    result.hint = `No skills found. Add skill files under skills/ in Resources. Learn more: ${docsUrl("agent-resources", { hash: "skills" })}`;
                 }
                 return result;
             }));

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
-    error?: undefined;
 }>>;
 export {};

package/dist/server/onboarding-html.js

@@ -8,6 +8,7 @@
  */
 import { getLocaleInitScript } from "../localization/server.js";
 import { DEFAULT_LOCALE, LOCALE_METADATA, LOCALE_STORAGE_KEY, SUPPORTED_LOCALES, } from "../localization/shared.js";
+import { docsUrl } from "../shared/docs-url.js";
 import { PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, } from "../shared/password-policy.js";
 import { signInJourneyInlineScript } from "../shared/sign-in-journey.js";
 import { AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, withAgentNativeSocialImageCacheBuster, } from "../shared/social-meta.js";
@@ -1424,7 +1425,7 @@ ${localeMenuItemsHtml}
     <button type="button" class="btn-local-dev btn-primary" id="local-dev-btn" title="${esc(t("localDevDescription"))}"${i18nAttr("localDevButton")} data-i18n-title="localDevDescription" aria-describedby="local-dev-description">${esc(t("localDevButton"))}</button>
     <p class="local-dev-description" id="local-dev-description">
       <span${i18nAttr("localDevDescription")}>${esc(t("localDevDescription"))}</span>
-      <a class="local-dev-help" id="local-dev-help" href="https://www.agent-native.com/docs/authentication#local-development-sign-in" target="_blank" rel="noreferrer" aria-label="${esc(t("localDevHelp"))}" title="${esc(t("localDevHelp"))}" data-i18n-title="localDevHelp"${i18nAriaAttr("localDevHelp")}><span class="local-dev-help-glyph" aria-hidden="true">?</span></a>
+      <a class="local-dev-help" id="local-dev-help" href="${docsUrl("authentication", { hash: "local-development-sign-in" })}" target="_blank" rel="noreferrer" aria-label="${esc(t("localDevHelp"))}" title="${esc(t("localDevHelp"))}" data-i18n-title="localDevHelp"${i18nAriaAttr("localDevHelp")}><span class="local-dev-help-glyph" aria-hidden="true">?</span></a>
     </p>
     <button type="button" class="local-dev-full-options" id="local-dev-full-options" hidden${i18nAttr("localDevFullOptions")}>${esc(t("localDevFullOptions"))}</button>
     <p class="msg error" id="local-dev-msg" role="status" aria-live="polite"></p>

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

package/dist/shared/docs-url.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Absolute links into the public Agent-Native docs site.
+ *
+ * Call `docsUrl("content-slug")` at call sites so the path is visible inline
+ * (`docsUrl("template-design")` → `/docs/template-design`). Relative
+ * `/docs/...` paths resolve against the app origin and 404 — always use this
+ * helper for outbound docs links.
+ */
+export declare const AGENT_NATIVE_DOCS_ORIGIN = "https://www.agent-native.com";
+export type DocsUrlOptions = {
+    hash?: string;
+    /** UTM medium; defaults to `product` when any UTM field is set. */
+    medium?: string;
+    /** UTM campaign; defaults to `docs` when any UTM field is set. */
+    campaign?: string;
+    content?: string | null;
+};
+/**
+ * Build an absolute docs URL for a content slug (the MDX stem under
+ * `packages/core/docs/content/`).
+ *
+ * `getting-started` maps to `/docs` (the docs home).
+ */
+export declare function docsUrl(slug: string, options?: DocsUrlOptions): string;

package/dist/shared/docs-url.js

@@ -0,0 +1,39 @@
+/**
+ * Absolute links into the public Agent-Native docs site.
+ *
+ * Call `docsUrl("content-slug")` at call sites so the path is visible inline
+ * (`docsUrl("template-design")` → `/docs/template-design`). Relative
+ * `/docs/...` paths resolve against the app origin and 404 — always use this
+ * helper for outbound docs links.
+ */
+export const AGENT_NATIVE_DOCS_ORIGIN = "https://www.agent-native.com";
+function applyDocsUtm(params, options) {
+    const wantsUtm = options.medium != null ||
+        options.campaign != null ||
+        options.content != null;
+    if (!wantsUtm)
+        return;
+    params.set("utm_source", "agent-native");
+    params.set("utm_medium", options.medium ?? "product");
+    params.set("utm_campaign", options.campaign ?? "docs");
+    if (options.content)
+        params.set("utm_content", options.content);
+}
+/**
+ * Build an absolute docs URL for a content slug (the MDX stem under
+ * `packages/core/docs/content/`).
+ *
+ * `getting-started` maps to `/docs` (the docs home).
+ */
+export function docsUrl(slug, options = {}) {
+    const normalized = slug.replace(/^\/+/, "").replace(/\/+$/, "");
+    const path = normalized === "" || normalized === "getting-started"
+        ? "/docs"
+        : `/docs/${normalized}`;
+    const url = new URL(path, AGENT_NATIVE_DOCS_ORIGIN);
+    applyDocsUtm(url.searchParams, options);
+    if (options.hash) {
+        url.hash = options.hash.replace(/^#/, "");
+    }
+    return url.toString();
+}

package/dist/shared/index.d.ts

@@ -6,6 +6,7 @@ export { truncate } from "./truncate.js";
 export { isHumanReadableDocumentTitle, normalizeDocumentTitle, } from "./document-title.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
+export { AGENT_NATIVE_DOCS_ORIGIN, docsUrl, type DocsUrlOptions, } from "./docs-url.js";
 export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, type RuntimeConfigEnvironment, type RuntimeConfigIssue, type RuntimeConfigIssueCode, type RuntimeConfigIssueSeverity, type RuntimeConfigPhase, type RuntimeConfigReport, type RuntimeConfigRequirements, } from "./runtime-config.js";
 export { llmConnectionTrackingProperties, normalizeLlmConnection, type LlmConnectionStatus, } from "./llm-connection.js";
 export { DISPATCH_WORKSPACE_ROOT_REDIRECTS, RESERVED_WORKSPACE_APP_IDS, assertValidWorkspaceAppId, getWorkspaceAppIdValidationError, isValidWorkspaceAppIdFormat, normalizeWorkspaceAppId, } from "./workspace-app-id.js";

package/dist/shared/index.js

@@ -6,6 +6,7 @@ export { truncate } from "./truncate.js";
 export { isHumanReadableDocumentTitle, normalizeDocumentTitle, } from "./document-title.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
+export { AGENT_NATIVE_DOCS_ORIGIN, docsUrl, } from "./docs-url.js";
 export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, } from "./runtime-config.js";
 export { llmConnectionTrackingProperties, normalizeLlmConnection, } from "./llm-connection.js";
 export { DISPATCH_WORKSPACE_ROOT_REDIRECTS, RESERVED_WORKSPACE_APP_IDS, assertValidWorkspaceAppId, getWorkspaceAppIdValidationError, isValidWorkspaceAppIdFormat, normalizeWorkspaceAppId, } from "./workspace-app-id.js";

package/dist/templates/default/app/routes/_index.tsx

@@ -1,5 +1,6 @@
 import { useActionQuery } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
+import { docsUrl } from "@agent-native/core/shared";
 import { useTheme } from "next-themes";
 import { Link } from "react-router";
 
@@ -41,7 +42,7 @@ export default function IndexPage() {
 
         <div className="grid grid-cols-2 gap-3 text-left">
           <a
-            href="https://agent-native.com/docs"
+            href={docsUrl("getting-started")}
             target="_blank"
             rel="noopener noreferrer"
             className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"

package/docs/content/client-advanced.mdx

@@ -0,0 +1,200 @@
+---
+title: "Advanced"
+description: "Lower-level app/ primitives and escape hatches: direct application-state access, background chat sends, custom suggestion chips, and the MCP App host bridge."
+---
+
+# Advanced
+
+Overview, Data & Sync, Agent Chat, and Routing cover the typical case: the hooks and helpers most pages need. This page covers the lower-level primitives and narrower escape hatches underneath them. Most apps never touch these directly. Reach for one when you're building something more custom than the default hooks support, such as a custom selection sync or an embedded MCP App. For syncing a raw `useQuery` with a hand-rolled key, see [Sync Internals](/docs/client-sync-internals) instead.
+
+## Application State {#application-state}
+
+`application_state` is the SQL-backed key/value store the agent reads to know what the UI is currently looking at, including navigation, selection, and other focused-object context (see [Context Awareness](/docs/context-awareness)). `useAgentRouteState` and `useSemanticNavigationState` (also covered in Context Awareness) already wrap these for the common navigation case. Reach for the primitives below directly when you're syncing something they don't cover, such as a custom selection, or writing from outside a component's render.
+
+### readClientAppState {#read-client-app-state}
+
+Read the current value for a key. Resolves to whatever was last written for that key, or `null` if the key has never been written.
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection is exactly what was last written to that key, e.g.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// or, if nothing has written "selection" yet:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+Write a value for a key. Unlike `setClientAppState` below, it always writes, even if you pass `null`. Passing `undefined` throws instead, since `undefined` isn't valid JSON. Use `setClientAppState(key, undefined)` or `deleteClientAppState()` to clear a key.
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+The convenience wrapper most UI code should reach for: writes the value, or deletes the key when you pass `null`/`undefined`. Use this instead of `writeClientAppState` unless a call site genuinely needs "always write, never delete."
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // clears the key, same as deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+Remove a key entirely.
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+Read several keys in one request. Returns `{ values, missing }`. `values` holds an entry for every key the server has a row for, including a key that was explicitly written as `null`. `missing` lists the keys that have never been written at all. This is how "never written" stays distinguishable from "written as null."
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+Requests over 100 keys are chunked automatically. `readClientAppState()` itself is built on this: calls issued in the same tick are coalesced into one batched request behind the scenes, so calling it many times in a single render pass costs one round trip, not one per call.
+
+### Options {#application-state-options}
+
+`signal` is accepted by all five functions above, to cancel an in-flight call. `requestSource` and `keepalive` only apply to the three write functions, since they don't mean anything for a read.
+
+| Option          | Type           | Applies to                                                         | Description                                                                                  |
+| --------------- | -------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `requestSource` | `string?`      | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Tags the write with an id so a matching `useDbSync({ ignoreSource })` can skip refetching it |
+| `keepalive`     | `boolean?`     | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Lets the request outlive page unload. Use for cleanup writes like clearing selection         |
+| `signal`        | `AbortSignal?` | all five functions                                                 | Cancels the request                                                                          |
+
+### Failure behavior {#failure-behavior}
+
+All five functions throw on a failed request, a non-2xx response, or a body that can't be parsed. The thrown `Error` carries a `.status` property when the server responded, so a caller can branch on the HTTP status if needed. Wrap a call in `try`/`catch`, or let it propagate to an error boundary, the same as any other network call.
+
+### What TAB_ID is {#tab-id}
+
+`requestSource` is commonly set to `TAB_ID`, a plain constant every template exports from `app/lib/tab-id.ts`: a short random string that stays the same for the life of a tab and differs between tabs. Pairing `requestSource: TAB_ID` on a write with `useDbSync({ ignoreSource: TAB_ID })` on the read side is how a tab avoids refetching its own write while still reacting to everyone else. See [Context Awareness](/docs/context-awareness#jitter-prevention) for the full walkthrough.
+
+## sendToAgentChat: Background Sends {#background-send}
+
+Use `background: true` when a UI action should kick off real agent work without
+opening or focusing the sidebar. This still creates a normal chat thread/run,
+uses the agent's tools/actions/context, and keeps the work observable through
+the runs tray. It is not a raw one-shot model call.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` is intended to be paired with `newTab` so the hidden work does not
+overwrite the user's active conversation. Use the returned `tabId` if the UI
+needs to correlate follow-up status or deep-link into the run later.
+
+A few more `AgentChatMessage` options exist beyond the ones covered in [Agent Chat](/docs/client-agent-chat#agentchatmessage), mostly for embedded or downstream-integration cases:
+
+| Option                | Type        | Description                                                                |
+| --------------------- | ----------- | -------------------------------------------------------------------------- |
+| `background`          | `boolean?`  | With `newTab`, run without focusing the tab and show the run in `RunsTray` |
+| `projectSlug`         | `string?`   | Optional project slug for structured context                               |
+| `preset`              | `string?`   | Optional preset name for downstream consumers                              |
+| `referenceImagePaths` | `string[]?` | Optional reference image paths                                             |
+
+## MCP App Host Bridge {#mcp-app-host-bridge}
+
+Routes embedded as MCP Apps should be URL-first: load the current artifact from
+path/query params, render the real React route or a focused shared component,
+and use the host bridge only for host-owned behavior. `@agent-native/core/client`
+exports the helpers embedded routes call:
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+`getMcpAppHostContext()` reads the latest pushed host context snapshot.
+`useMcpAppHostContext()` subscribes React components to changes. The request
+helpers (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
+`updateMcpAppModelContext`) return `false` outside an embedded MCP App frame, or
+`Promise<boolean>` inside a frame.
+
+`sendToAgentChat()` (see [Agent Chat](/docs/client-agent-chat#sendtoagentchat)) uses the same bridge for auto-submitted prompts from embedded routes. Inside an MCP App embed created with `embedApp()`, auto-submitted messages (`submit` omitted or `true`) are forwarded to the bridge, which asks the containing host to add hidden context and send the visible user turn. `context` stays model-visible without being posted as user-facing chat. `submit: false` keeps the local prefill/review behavior because MCP Apps do not define a standard draft-prefill API. Internally this is the submitted-chat path sometimes surfaced as `agentNative.submitChat`. App code should still call `sendToAgentChat()` rather than posting that event directly.
+
+The bridge itself, the `ui/*` JSON-RPC messages, the `agentNative.mcpHost.*`
+wrapper relay, transplant vs. controlled-frame rendering, host context, and
+display-mode requests, is owned by
+[External Agents](/docs/external-agents#mcp-app-bridge). See [MCP Apps](/docs/mcp-apps) for the full protocol.
+
+## Custom Suggestion Chips {#custom-suggestions}
+
+`<AgentSidebar>`'s `dynamicSuggestions` (see [Agent Chat](/docs/client-agent-chat#dynamic-suggestions)) already merges static `suggestions` with the framework's own context-aware heuristic. Pass a `getSuggestions` function inside `dynamicSuggestions` instead when an app wants deterministic, domain-specific chips computed from the same `application_state` context rather than the framework's default heuristic.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
+>
+  <App />
+</AgentSidebar>
+```
+
+`getSuggestions` receives the same `navigation`/`selection`/`pendingSelection` snapshot the built-in heuristic reads, typed as `unknown` since its shape is app-defined, so narrow it before reading fields. A custom implementation can react to exactly the state the default one does, just with app-specific rules instead of generic ones.
+
+## What's next
+
+- [**Overview**](/docs/client-overview) — the `app/` and `public/` directory layout these primitives live in
+- [**Data & Sync**](/docs/client-data) — the default action hooks and `useDbSync` most pages should use instead
+- [**Sync Internals**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions` and the two latency paths a refetch can take
+- [**Agent Chat**](/docs/client-agent-chat) — the default `sendToAgentChat`/`askUserQuestion` helpers most UI should use instead, and the staged agent chat context-state APIs
+- [**Entry Points**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx` and SSR streaming customization
+- [**Context Awareness**](/docs/context-awareness) — the `navigation`/`selection` semantics built on `application_state`, and the `TAB_ID`/jitter-prevention walkthrough
+- [**Generative UI**](/docs/generative-ui) — richer inline chat controls beyond `askUserQuestion`
+- [**External Agents**](/docs/external-agents#mcp-app-bridge) — the full MCP App host bridge internals