@agent-native/core 0.109.3 → 0.110.0

package/corpus/README.md

@@ -27,5 +27,5 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 2312
-- template files: 6152
+- core files: 2365
+- template files: 6153

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @agent-native/core
 
+## 0.110.0
+
+### Minor Changes
+
+- 079e19a: Add focused client entrypoints, lazy built-in chat widgets, explicit route-chunk recovery initialization, and manifest-driven `upgrade --codemods` and doctor preflight infrastructure for upcoming package moves.
+
+### Patch Changes
+
+- Updated dependencies [079e19a]
+  - @agent-native/toolkit@0.5.1
+
+## 0.109.4
+
+### Patch Changes
+
+- b6d7f87: Move portable rich-editor, context presentation, and visual design controls into Toolkit while preserving Core compatibility re-exports, and add accurate side-effect metadata to capability packages.
+- Updated dependencies [b6d7f87]
+  - @agent-native/toolkit@0.5.0
+
 ## 0.109.3
 
 ### Patch Changes

package/corpus/core/docs/content/actions.mdx

@@ -427,8 +427,7 @@ Two hooks, both in `@agent-native/core/client`. Types are inferred from your `de
 For actions that change state:
 
 ```tsx
-import { useActionMutation } from "@agent-native/core/client";
-
+import { useActionMutation } from "@agent-native/core/client/hooks";
 const { mutate, isPending } = useActionMutation("reply-to-email");
 
 <Button
@@ -446,8 +445,7 @@ On success, the framework emits a change event with `source: "action"` so `useAc
 For read-only GET actions:
 
 ```ts
-import { useActionQuery } from "@agent-native/core/client";
-
+import { useActionQuery } from "@agent-native/core/client/hooks";
 const { data, isLoading } = useActionQuery("get-lead", { leadId });
 ```
 

package/corpus/core/docs/content/agent-native-toolkit.mdx

@@ -1,20 +1,24 @@
 ---
-title: "Toolkits"
-description: "Battle-tested reusable building blocks for high-quality agentic applications: collaboration, sharing, settings, teams, setup, navigation, resources, agent UX, history, comments, and observability."
+title: "Toolkit"
+description: "One catalog of reusable foundations, editors and canvases, agent context, governance, workspace chrome, operations, and install-on-demand capability modules."
 ---
 
-# Toolkits
+# Toolkit
 
-Toolkits are reusable, battle-tested building blocks for high-quality agentic
-applications. They turn the hard product work that repeats across apps into
-standard surfaces: realtime collaboration between humans and agents, sharing
-with humans and agents, settings, teams, setup, resources, history, review, and
-observability.
+Toolkit is the reusable, battle-tested building-block shelf for high-quality
+agentic applications. It turns the hard product work that repeats across apps
+into standard surfaces without making one app pattern the center of the catalog.
+
+This section is the single discovery shelf for reusable app-building UI. A
+surface belongs in these docs because it is reusable, even when its current
+implementation owner is Core or a template. Ownership labels and import paths
+make that boundary explicit without scattering related UI guidance across the
+site.
 
 Each kit packages the UI patterns, action contracts, app-state expectations,
 access boundaries, and agent-visible behavior that users expect to work
-consistently. Apps still own their domain model and visual identity; toolkits
-make the common product systems feel complete from the first version instead of
+consistently. Apps still own their domain model and visual identity; Toolkit
+makes the common product systems feel complete from the first version instead of
 being rebuilt in slightly different ways every time.
 
 <WireframeBlock id="doc-block-toolkits-index">
@@ -26,7 +30,7 @@ being rebuilt in slightly different ways every time.
   />
 </WireframeBlock>
 
-<Diagram id="doc-block-toolkits-boundary" title="How kits fit" summary={"The framework runtime supplies durable guarantees. Toolkits turn those guarantees into reusable product systems. Apps add domain-specific data, routes, and visual identity."}>
+<Diagram id="doc-block-toolkits-boundary" title="How kits fit" summary={"The framework runtime supplies durable guarantees. Toolkit turns those guarantees into reusable product systems. Apps add domain-specific data, routes, and visual identity."}>
 
 ```html
 <div class="diagram-row">
@@ -36,7 +40,7 @@ being rebuilt in slightly different ways every time.
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-card">
-    <span class="diagram-pill accent">Toolkits</span><br />
+    <span class="diagram-pill accent">Toolkit</span><br />
     collaboration, sharing, setup, review, history, observability
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
@@ -66,7 +70,19 @@ being rebuilt in slightly different ways every time.
 
 </Diagram>
 
-## The Kits {#the-kits}
+## Catalog {#catalog}
+
+| Area                       | Start here                                                      | What it covers                                                                  |
+| -------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Foundations                | [UI Primitives](/docs/toolkit-ui)                               | Shared controls, hooks, app adapters, and shell seams.                          |
+| Editors & canvases         | [Editors & Canvases](/docs/toolkit-editors-canvases)            | Rich editing, structured blocks, reusable canvas controls, and Design patterns. |
+| Agent experience & context | [Context & Knowledge](/docs/toolkit-context-knowledge)          | Context X-Ray, resources, knowledge, composer context, and agent-visible state. |
+| Collaboration & governance | [Collaboration](/docs/toolkit-collaboration)                    | Sharing, presence, review, history, audit, and organization boundaries.         |
+| Workspace chrome           | [App Chrome](/docs/toolkit-settings)                            | Settings, teams, setup, navigation, resources, and agent UX.                    |
+| Operations                 | [Observability](/docs/toolkit-observability)                    | Usage, feedback, replay, diagnostics, and operational visibility.               |
+| Capability modules         | [Toolkit Capability Modules](/docs/toolkit-capability-packages) | Scheduling, Creative Context, and Pinpoint as install-on-demand packages.       |
+
+## Product kits {#product-kits}
 
 | Kit                                                      | Use it for                                                                                                                       |
 | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
@@ -82,8 +98,23 @@ being rebuilt in slightly different ways every time.
 | [Comments & Review](/docs/toolkit-comments-review)       | Registered reviewable resources, comment actions, feedback queues, thread panels, mentions, resolved threads, and review status. |
 | [Observability](/docs/toolkit-observability)             | Usage, spend, feedback, replay, errors, and run diagnostics.                                                                     |
 
+## Package maturity and ownership {#package-maturity-and-ownership}
+
+- The rich editor is **Toolkit-owned**. Existing Core editor imports remain thin
+  compatibility re-exports during migration.
+- Design is a **template pattern** with reusable `design-tweaks`; it is not a
+  full drop-in editor or canvas package.
+- Blocks remain **Core-owned** in this phase.
+- The Context X-Ray engine remains **Core-owned**; its reusable presentation is
+  Toolkit-owned.
+- Scheduling, Creative Context, and Pinpoint are **Toolkit capability modules,
+  installed on demand**. They remain separate npm packages so each domain can
+  keep an independent lifecycle manifest, dependency graph, and release cadence.
+- Dispatch remains a **separate product**, not a Toolkit capability module.
+
 ## Implementation Boundary {#implementation-boundary}
 
+Toolkit docs are organized by reusable product capability, not npm package.
 Kits are product surfaces first. Some pieces are runtime-backed
 (`@agent-native/core`), some are presentation primitives
 (`@agent-native/toolkit`), and apps usually wrap both through local adapters.
@@ -117,3 +148,5 @@ workflows, labels, and visual styling in the app.
   end and see where kits fit alongside your own domain model.
 - [**Component API**](/docs/components) — the generated reference for every
   public React export, including kit components.
+- [**Package Lifecycle**](/docs/package-lifecycle) — inspect, add, and eject
+  manifest-driven capability packages safely.

package/corpus/core/docs/content/agent-surfaces.mdx

@@ -38,8 +38,7 @@ with an app-navigation entry and pass `agentPageHref="/agent"` to
 full page without duplicating those flows.
 
 ```tsx filename="app/routes/agent.tsx"
-import { AgentTabsPage } from "@agent-native/core/client";
-
+import { AgentTabsPage } from "@agent-native/core/client/agent-chat";
 export default function AgentRoute() {
   return <AgentTabsPage />;
 }
@@ -427,8 +426,7 @@ export default createAgentNativeEmbeddedPlugin({
 The React sidecar passes page context and host commands:
 
 ```tsx
-import { AgentNativeEmbedded } from "@agent-native/core/client";
-
+import { AgentNativeEmbedded } from "@agent-native/core/client/host";
 export function AppShell({ children }) {
   return (
     <AgentNativeEmbedded

package/corpus/core/docs/content/audit-log.mdx

@@ -82,8 +82,7 @@ Three read actions are available to the agent **and** the frontend in every app,
 Build an activity feed or a "who changed this" line by calling `list-audit-events` from the UI with `useActionQuery` — never hand-write a fetch to the audit table:
 
 ```tsx
-import { useActionQuery } from "@agent-native/core/client";
-
+import { useActionQuery } from "@agent-native/core/client/hooks";
 const { data } = useActionQuery("list-audit-events", {
   targetType: "recording",
   targetId: recordingId,

package/corpus/core/docs/content/authentication.mdx

@@ -362,8 +362,9 @@ interface AuthSession {
 On the client, use the `useSession()` hook:
 
 ```ts
-import { useSession } from "@agent-native/core/client";
-
+import {
+  useSession,
+} from "@agent-native/core/client/hooks"
 function MyComponent() {
   const { session, isLoading } = useSession();
   if (isLoading) return <p>Loading...</p>;

package/corpus/core/docs/content/client.mdx

@@ -73,8 +73,7 @@ import {
   useActionQuery,
   useActionMutation,
   callAction,
-} from "@agent-native/core/client";
-
+} from "@agent-native/core/client/hooks";
 // Read: auto-cached, auto-invalidated on mutations
 const { data, isLoading } = useActionQuery("get-lead", { leadId });
 
@@ -91,8 +90,7 @@ await callAction("archive-lead", { leadId });
 Send a message to the agent chat via postMessage — the common way to delegate an AI task from a UI interaction. Pass `context` for hidden model context and `submit: true` to send immediately, or `submit: false` to prefill a draft the user reviews first.
 
 ```ts
-import { sendToAgentChat } from "@agent-native/core/client";
-
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 // Auto-submit a prompt with hidden context
 sendToAgentChat({
   message: "Generate alt text for this image",
@@ -182,8 +180,7 @@ the agent sidebar's Settings tab. Pass a section id such as `"llm"`, `"secrets"`
 `"automations"`, `"voice"`, or `"limits"` to open a specific section.
 
 ```ts
-import { openAgentSettings } from "@agent-native/core/client";
-
+import { openAgentSettings } from "@agent-native/core/client/navigation";
 openAgentSettings();
 openAgentSettings("secrets");
 ```
@@ -191,8 +188,7 @@ openAgentSettings("secrets");
 Prefer this helper over dispatching `agent-panel:open-settings` directly.
 
 ```tsx
-import { useAgentChatContext } from "@agent-native/core/client";
-
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
 function SelectionContextButton({ record }: { record: { id: string } }) {
   const chatContext = useAgentChatContext();
   const contextKey = `selected-record:${record.id}`;
@@ -250,8 +246,10 @@ kicks off agent work — instead of building a custom modal. Reach for the
 composer for freeform detail, and a form/popover for multi-field input.
 
 ```tsx
-import { askUserQuestion, sendToAgentChat } from "@agent-native/core/client";
-
+import {
+  askUserQuestion,
+  sendToAgentChat,
+} from "@agent-native/core/client/agent-chat";
 const length = await askUserQuestion({
   question: "How long should this deck be?",
   header: "Deck length", // optional short chip/heading (≈12 chars)
@@ -294,7 +292,7 @@ import {
   requestMcpAppDisplayMode,
   updateMcpAppModelContext,
   useMcpAppHostContext,
-} from "@agent-native/core/client";
+} from "@agent-native/core/client/agent-chat";
 ```
 
 `getMcpAppHostContext()` reads the latest pushed host context snapshot;
@@ -329,8 +327,9 @@ Set `dynamicSuggestions={false}` to keep only static chips. Pass `getSuggestions
 React hook that wraps sendToAgentChat with loading state tracking:
 
 ```ts
-import { useAgentChatGenerating } from "@agent-native/core/client";
-
+import {
+  useAgentChatGenerating,
+} from "@agent-native/core/client/agent-chat"
 function GenerateButton() {
   const [isGenerating, send] = useAgentChatGenerating();
 
@@ -356,7 +355,9 @@ function GenerateButton() {
 React hook (formerly `useFileWatcher`) that listens for database changes over SSE, falls back to polling, and invalidates the framework query caches that keep the UI aligned with agent writes:
 
 ```ts
-import { useDbSync } from "@agent-native/core/client";
+import {
+  useDbSync,
+} from "@agent-native/core/client/hooks"
 import { useQueryClient } from "@tanstack/react-query";
 
 function App() {
@@ -401,8 +402,7 @@ When any server-side database mutation occurs, the server records a change event
 
 ```tsx
 import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client";
-
+import { useChangeVersion } from "@agent-native/core/client/hooks";
 function DashboardView({ id }) {
   // Get version for dashboards domain source
   const v = useChangeVersion("dashboards");
@@ -467,8 +467,9 @@ function DashboardView({ id }) {
 Utility for merging class names (clsx + tailwind-merge):
 
 ```ts
-import { cn } from "@agent-native/core/client";
-
+import {
+  cn,
+} from "@agent-native/toolkit/utils"
 <div className={cn(
   "px-4 py-2 rounded",
   isActive && "bg-primary text-primary-foreground",

package/corpus/core/docs/content/components.mdx

@@ -13,7 +13,7 @@ components when you can, and drop down a layer when you need custom product UI.
 Import browser UI from focused client subpaths:
 
 ```tsx
-import { AgentSidebar } from "@agent-native/core/client";
+import { AgentSidebar } from "@agent-native/core/client/agent-chat";
 import { PromptComposer } from "@agent-native/core/client/composer";
 import { AgentConversation } from "@agent-native/core/client/conversation";
 import { usePresence } from "@agent-native/core/client/collab";

package/corpus/core/docs/content/context-awareness.mdx

@@ -200,8 +200,7 @@ Use the `selection` app-state key for durable selection that should survive a mo
 Write it from the UI when the user selects, focuses, or multi-selects meaningful objects:
 
 ```tsx
-import { setClientAppState } from "@agent-native/core/client";
-
+import { setClientAppState } from "@agent-native/core/client/hooks";
 async function syncSelection(selection: unknown | null) {
   await setClientAppState("selection", selection, { keepalive: true });
 }
@@ -230,8 +229,7 @@ The production agent injects that key into the next turn as immediate selection
 Custom editors can write the same key when their selection is not represented by native browser selection:
 
 ```tsx
-import { setClientAppState } from "@agent-native/core/client";
-
+import { setClientAppState } from "@agent-native/core/client/hooks";
 await setClientAppState(
   "pending-selection-context",
   {
@@ -293,8 +291,7 @@ The agent should call `pnpm action view-screen` before acting on the current UI.
 Sometimes context should not just sit in app state. A user clicks a button, drops a comment pin, selects an item and chooses "Ask agent", or presses an AI command in a toolbar. That click is an instruction. In browser UI, hand it to the agent with `sendToAgentChat()`.
 
 ```tsx
-import { sendToAgentChat } from "@agent-native/core/client";
-
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 function askAgentAboutSelection(selection: {
   documentId: string;
   blockId: string;
@@ -377,7 +374,7 @@ It stays short because it is a thin wrapper around the real framework primitive,
 
 ```tsx
 // app/hooks/use-navigation-state.ts -- this file lives in YOUR app
-import { useAgentRouteState } from "@agent-native/core/client";
+import { useAgentRouteState } from "@agent-native/core/client/navigation";
 import { TAB_ID } from "@/lib/tab-id";
 
 interface NavigationState {

package/corpus/core/docs/content/creating-templates.mdx

@@ -273,8 +273,10 @@ Use `http: { method: "GET" }` or `readOnly: true` for read-only actions. Use `pa
 Routes live in `app/routes/` and use React Router v8 file routing. Query data through actions or API handlers, and make mutations optimistic by default.
 
 ```tsx
-import { useActionMutation, useActionQuery } from "@agent-native/core/client";
-
+import {
+  useActionMutation,
+  useActionQuery,
+} from "@agent-native/core/client/hooks";
 export default function ProjectsPage() {
   const { data: projects = [] } = useActionQuery("list-projects", {});
   const create = useActionMutation("create-project");
@@ -290,7 +292,7 @@ export default function ProjectsPage() {
 Wire live sync once near the app shell so React Query caches refresh when the agent, another tab, or an action changes data:
 
 ```tsx
-import { useDbSync } from "@agent-native/core/client";
+import { useDbSync } from "@agent-native/core/client/hooks";
 import { useQueryClient } from "@tanstack/react-query";
 
 export function AppSync() {
@@ -303,7 +305,7 @@ export function AppSync() {
 **The agent-native promise: agent writes show up in the UI without a manual refresh.** `useActionQuery` is the easy path — every hook refetches when a mutating action emits `source: "action"`. If you reach for raw `useQuery` with a custom key (for example, a low-level client helper that reads integration status), fold the per-source counter into the queryKey for targeted refreshes:
 
 ```tsx
-import { useChangeVersions } from "@agent-native/core/client";
+import { useChangeVersions } from "@agent-native/core/client/hooks";
 
 const v = useChangeVersions(["dashboards", "action"]);
 useQuery({
@@ -326,7 +328,7 @@ Application state is how the agent knows what the user is seeing. At minimum, ad
 Use `useAgentRouteState` for the UI hook so application-state writes, tab-scoped command reads, delete-after-read, and duplicate-command protection stay consistent:
 
 ```tsx
-import { useAgentRouteState } from "@agent-native/core/client";
+import { useAgentRouteState } from "@agent-native/core/client/navigation";
 import { TAB_ID } from "@/lib/tab-id";
 
 export function useNavigationState() {

package/corpus/core/docs/content/doctor.mdx

@@ -23,7 +23,7 @@ A clean run:
 
 ```
 agent-native doctor: /path/to/app
-Guards run: no-drizzle-push, no-unscoped-credentials, no-unscoped-queries, no-env-credentials, db-tool-scoping, no-env-mutation, no-localhost-fallback
+Guards run: no-drizzle-push, no-unscoped-credentials, no-unscoped-queries, no-env-credentials, db-tool-scoping, no-env-mutation, no-localhost-fallback, migration-manifest
 Clean — no findings.
 ```
 
@@ -37,9 +37,9 @@ A run with findings prints one line per finding and exits `1`:
 agent-native doctor found issues above. Fix them, or add a `// guard:allow-<check> — reason` opt-out with reviewer approval.
 ```
 
-## The seven guards {#guards}
+## The eight guards {#guards}
 
-v1 ships 7 guards. Each is a pure scan over the app's source tree — `node_modules`, `.git`, `dist`, `build`, and other build-output directories are always skipped.
+v1 ships 8 guards. Each is a pure scan over the app's source tree — `node_modules`, `.git`, `dist`, `build`, and other build-output directories are always skipped.
 
 | Guard                     | What it catches                                                                                                                                                                                                                            | Why it matters                                                                                                                                                                                                                                                                             |
 | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -50,9 +50,25 @@ v1 ships 7 guards. Each is a pure scan over the app's source tree — `node_modu
 | `db-tool-scoping`         | A table in `server/db/schema.ts` with no `owner_email` / `org_id` column and no matching entry in `agent-native.json`'s `doctor.dbToolScopingDenylist`                                                                                     | The agent's raw `db-query` / `db-exec` / `db-patch` tools can only safely expose tenant-scoped tables; an unscoped table needs an explicit, reviewed exception.                                                                                                                            |
 | `no-env-mutation`         | Production code assigning to, or `delete`-ing, `process.env.KEY`                                                                                                                                                                           | `process.env` is process-scoped, not request-scoped. A warm serverless container handles many concurrent requests in one process, so mutating `process.env` in a request handler leaks state across users. Use `runWithRequestContext` instead.                                            |
 | `no-localhost-fallback`   | The literal `"local@localhost"`, or `?? DEV_MODE_USER_EMAIL` / `\|\| DEV_MODE_USER_EMAIL`, used as a fallback identity                                                                                                                     | Falling back to a sentinel identity when there's no session pools every unauthenticated request onto one shared tenant. Throw or return 401 instead.                                                                                                                                       |
+| `migration-manifest`      | Imports listed in an installed package's `migration-manifest.json`                                                                                                                                                                         | The import is scheduled to move or disappear. Preview and apply the supported codemod before the upgrade makes it a hard error.                                                                                                                                                            |
 
 Guard names are stable identifiers — the same strings work in `--only`, `agent-native.json`'s `doctor.disabledGuards`, and every finding's `guard` field.
 
+Use the migration preflight directly:
+
+```bash
+agent-native doctor --only migration-manifest
+npx @agent-native/core@latest upgrade --codemods
+npx @agent-native/core@latest upgrade --codemods --yes
+```
+
+The first command reports a preview of imports that match the shipped manifest;
+the codemod command previews its diff by default, and `--yes` applies the
+reviewed rewrite. `migration-manifest` has no opt-out and cannot be disabled.
+Entries marked `planned` are warnings only and are not rewritten. Active entries
+are findings, and the codemod rewrites them only when the destination export is
+installed.
+
 ## Flags and exit codes {#flags}
 
 ```
@@ -104,7 +120,7 @@ If the doctor pre-step itself throws — an unreadable file, a bug in a guard
 
 ## Opt-out markers {#opt-out}
 
-Five of the seven guards support a per-line comment marker with a required short reason after an em dash or hyphen:
+Five guards support a per-line comment marker with a required short reason after an em dash or hyphen:
 
 ```ts
 // guard:allow-unscoped-credential — support tool reads any user's key by design, gated on admin role
@@ -138,6 +154,7 @@ The actual `--json` payload also carries a `strict` field reflecting whether `--
       "message": "process.env mutated in production code: process.env.AGENT_USER_EMAIL = userEmail. process.env is process-scoped, not request-scoped — use runWithRequestContext instead."
     }
   ],
+  "warnings": [],
   "guardsRun": [
     "no-drizzle-push",
     "no-unscoped-credentials",
@@ -145,13 +162,17 @@ The actual `--json` payload also carries a `strict` field reflecting whether `--
     "no-env-credentials",
     "db-tool-scoping",
     "no-env-mutation",
-    "no-localhost-fallback"
+    "no-localhost-fallback",
+    "migration-manifest"
   ],
   "strict": false
 }
 ```
 
-`ok` is `true` only when `findings` is empty. `guardsRun` lists every guard that actually ran (after `--only` / `disabledGuards` filtering) — useful for confirming a guard wasn't silently skipped.
+`ok` is `true` when `findings` is empty; planned migration entries are listed
+under `warnings` and do not make the command fail. `guardsRun` lists every guard
+that actually ran (after `--only` / `disabledGuards` filtering) — useful for
+confirming a guard wasn't silently skipped.
 
 The JSON report always writes to **stdout**, whether the run is clean or has findings — the exit code (`0` clean, `1` findings present) is the signal for pass/fail, not which stream the report landed on. A plain `agent-native doctor --json > report.json` captures the full report in every case, including a non-clean run; no stream redirection tricks needed. (Usage/execution errors — a bad `--cwd`, an unknown `--only` guard — still print their own JSON error payload to stderr and exit `2`; those aren't the report.)
 

package/corpus/core/docs/content/drop-in-agent.mdx

@@ -111,7 +111,7 @@ children stays in the main app area. The agent chat is the side panel.
   filename="app/root.tsx"
   language="tsx"
   code={
-    'import { Outlet } from "react-router";\nimport { AgentSidebar, AgentToggleButton } from "@agent-native/core/client";\n\nexport default function Root() {\n  return (\n    <AgentSidebar\n      emptyStateText="How can I help?"\n      suggestions={[\n        "Summarize my inbox",\n        "Draft a reply to the latest email",\n        "Show me yesterday\'s signup numbers",\n      ]}\n      dynamicSuggestions\n      defaultSidebarWidth={420}\n      position="right"\n    >\n      <header>\n        <AgentToggleButton />\n      </header>\n\n      <main>\n        <Outlet />\n      </main>\n    </AgentSidebar>\n  );\n}'
+    'import { Outlet } from "react-router";\nimport { AgentSidebar, AgentToggleButton } from "@agent-native/core/client/agent-chat";\n\nexport default function Root() {\n  return (\n    <AgentSidebar\n      emptyStateText="How can I help?"\n      suggestions={[\n        "Summarize my inbox",\n        "Draft a reply to the latest email",\n        "Show me yesterday\'s signup numbers",\n      ]}\n      dynamicSuggestions\n      defaultSidebarWidth={420}\n      position="right"\n    >\n      <header>\n        <AgentToggleButton />\n      </header>\n\n      <main>\n        <Outlet />\n      </main>\n    </AgentSidebar>\n  );\n}'
   }
   annotations={[
     {
@@ -160,8 +160,7 @@ When you need full control over layout — a dedicated `/chat` route, an embedde
 
 ```tsx
 // app/routes/agent.tsx
-import { AgentPanel } from "@agent-native/core/client";
-
+import { AgentPanel } from "@agent-native/core/client/agent-chat";
 export default function AgentRoute() {
   return (
     <div className="h-screen">
@@ -188,8 +187,7 @@ Full props: `AgentPanelProps` in `@agent-native/core/client`.
 A button that hands work off to the agent (instead of running an inline `llm()` call — the anti-pattern from the [ladder](/docs/what-is-agent-native#the-ladder)):
 
 ```tsx
-import { sendToAgentChat } from "@agent-native/core/client";
-
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 <Button
   onClick={() =>
     sendToAgentChat({
@@ -238,8 +236,7 @@ When the same route is embedded as an MCP App, submitted
 If you want a loading state, use the `useSendToAgentChat()` hook — it returns both `send` and `isGenerating`:
 
 ```ts
-import { useSendToAgentChat } from "@agent-native/core/client";
-
+import { useSendToAgentChat } from "@agent-native/core/client/agent-chat";
 const { send, isGenerating } = useSendToAgentChat();
 ```
 
@@ -273,8 +270,7 @@ client code does not learn a second, ad hoc transport.
 When the UI needs to run the same operation an agent tool would run — rung 3 of the [ladder](/docs/what-is-agent-native#rung-three) — use `useActionMutation`:
 
 ```tsx
-import { useActionMutation } from "@agent-native/core/client";
-
+import { useActionMutation } from "@agent-native/core/client/hooks";
 const { mutate, isPending } = useActionMutation("reply-to-email");
 
 <Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
@@ -304,8 +300,7 @@ import {
   AgentSidebar,
   AgentToggleButton,
   sendToAgentChat,
-} from "@agent-native/core/client";
-
+} from "@agent-native/core/client/agent-chat";
 export default function Root() {
   return (
     <AgentSidebar suggestions={["Draft a reply", "Summarize selection"]}>

package/corpus/core/docs/content/embedding-sdk.mdx

@@ -115,8 +115,7 @@ On the client:
 import {
   AgentNativeEmbedded,
   defineClientAction,
-} from "@agent-native/core/client";
-
+} from "@agent-native/core/client/host";
 export function BuilderAppShell({ children, content, editor }) {
   return (
     <AgentNativeEmbedded
@@ -298,8 +297,10 @@ context and client actions yourself.
 For standalone sidecar apps or cross-origin iframes, use the lower-level `<AgentNative />`. It renders the iframe sidecar and wires page context, live client actions, and host refresh/navigation commands in one place:
 
 ```tsx
-import { AgentNative, defineClientAction } from "@agent-native/core/client";
-
+import {
+  AgentNative,
+  defineClientAction,
+} from "@agent-native/core/client/host";
 export function AssistantDock({ customer, sessionToken }) {
   return (
     <AgentNative
@@ -386,8 +387,7 @@ import {
   requestAgentNativeHostContext,
   runAgentNativeHostAction,
   sendAgentNativeHostCommand,
-} from "@agent-native/core/client";
-
+} from "@agent-native/core/client/host";
 announceAgentNativeFrameReady({ hostOrigin: "https://app.example.com" });
 
 const context = await requestAgentNativeHostContext({
@@ -462,8 +462,7 @@ In the sidecar app, start the browser-session bridge once when the iframe mounts
 
 ```tsx
 import { useEffect } from "react";
-import { startAgentNativeBrowserSessionBridge } from "@agent-native/core/client";
-
+import { startAgentNativeBrowserSessionBridge } from "@agent-native/core/client/host";
 export function SidecarRuntime() {
   useEffect(() => {
     const bridge = startAgentNativeBrowserSessionBridge({
@@ -519,8 +518,7 @@ import {
   AgentNativeExtensionSlot,
   createHttpAgentNativeExtensionStorage,
   defineClientAction,
-} from "@agent-native/core/client";
-
+} from "@agent-native/core/client/host";
 const storage = createHttpAgentNativeExtensionStorage({
   endpoint: "/api/agent-native/extensions/storage",
   headers: () => ({ Authorization: `Bearer ${sessionToken()}` }),

package/corpus/core/docs/content/getting-started.mdx

@@ -220,8 +220,10 @@ separate REST route just for the browser if an action is the operation.
 Now add a durable page for the data behind the chat result:
 
 ```tsx filename="app/routes/response-insights.tsx"
-import { useActionMutation, useActionQuery } from "@agent-native/core/client";
-
+import {
+  useActionMutation,
+  useActionQuery,
+} from "@agent-native/core/client/hooks";
 export default function ResponseInsightsRoute() {
   const insights = useActionQuery("list-response-insights", {});
   const createInsight = useActionMutation("create-response-insight");

package/corpus/core/docs/content/internationalization.mdx

@@ -15,7 +15,11 @@ English when an app has not translated a string yet.
 Use the provider through `AppProviders`:
 
 ```tsx
-import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
+import {
+  AppProviders,
+} from "@agent-native/core/client/hooks"import {
+  getLocaleInitScript,
+} from "@agent-native/core/client/i18n"
 import { i18nCatalog } from "./i18n";
 
 const LOCALE_INIT_SCRIPT = getLocaleInitScript();
@@ -41,8 +45,7 @@ Each localized template keeps catalogs under `app/i18n/`:
 
 ```ts filename="app/i18n/index.ts"
 import enUS from "./en-US";
-import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
-
+import type { AgentNativeI18nCatalog } from "@agent-native/core/client/i18n";
 export const i18nCatalog = {
   sourceLocale: "en-US",
   messages: enUS,
@@ -71,10 +74,10 @@ the header language icon is only a shortcut.
 ```tsx
 import {
   LanguagePicker,
-  openAgentSettings,
   useT,
-} from "@agent-native/core/client";
-
+} from "@agent-native/core/client/i18n"import {
+  openAgentSettings,
+} from "@agent-native/core/client/navigation"
 function SettingsPage() {
   const t = useT();
   return (