@agent-native/core 0.109.4 → 0.110.1

package/corpus/templates/assets/app/routes/brand-kits.$id_.settings.tsx

@@ -1,9 +1,9 @@
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 import {
-  sendToAgentChat,
   useActionMutation,
   useActionQuery,
-  useT,
-} from "@agent-native/core/client";
+} from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
 import {
   useSetHeaderActions,
   useSetPageTitle,

package/corpus/templates/assets/app/routes/library.tsx

@@ -1,20 +1,24 @@
 import {
   AgentToggleButton,
-  appPath,
-  getBrowserTabId,
-  getEmbedAuthToken,
-  isEmbedMcpChatBridgeActive,
-  isEmbedAuthActive,
   insertAgentComposerReference,
-  readClientAppState,
   sendMcpAppHostMessage,
   updateMcpAppModelContext,
+  useAgentChatGenerating,
+} from "@agent-native/core/client/agent-chat";
+import { appPath } from "@agent-native/core/client/api-path";
+import {
+  getBrowserTabId,
+  readClientAppState,
   useActionMutation,
   useActionQuery,
-  useAgentChatGenerating,
-  useT,
   writeClientAppState,
-} from "@agent-native/core/client";
+} from "@agent-native/core/client/hooks";
+import {
+  getEmbedAuthToken,
+  isEmbedAuthActive,
+  isEmbedMcpChatBridgeActive,
+} from "@agent-native/core/client/host";
+import { useT } from "@agent-native/core/client/i18n";
 import {
   AGENT_NATIVE_EMBED_MESSAGE_TYPES,
   createAgentNativeEmbedEnvelope,

package/corpus/templates/assets/app/routes/run.$id_.embed.tsx

@@ -1,4 +1,4 @@
-import { useActionQuery } from "@agent-native/core/client";
+import { useActionQuery } from "@agent-native/core/client/hooks";
 import { useParams } from "react-router";
 
 import { assetPreviewSources } from "@/lib/asset-preview-sources";

package/corpus/templates/assets/app/routes/settings.tsx

@@ -1,21 +1,20 @@
-import {
-  ChangelogSettingsCard,
-  LanguagePicker,
-  SettingsTabsPage,
-  agentNativePath,
-  useActionQuery,
-  useAgentSettingsTabs,
-  useBuilderConnectFlow,
-  useBuilderStatus,
-  useT,
-  type SettingsSearchEntry,
-} from "@agent-native/core/client";
+import { agentNativePath } from "@agent-native/core/client/api-path";
+import { ChangelogSettingsCard } from "@agent-native/core/client/changelog";
+import { useActionQuery } from "@agent-native/core/client/hooks";
+import { LanguagePicker, useT } from "@agent-native/core/client/i18n";
 import {
   useOnboarding,
   type OnboardingMethod,
   type OnboardingStepStatus,
 } from "@agent-native/core/client/onboarding";
 import { TeamPage } from "@agent-native/core/client/org";
+import {
+  SettingsTabsPage,
+  useAgentSettingsTabs,
+  useBuilderConnectFlow,
+  useBuilderStatus,
+  type SettingsSearchEntry,
+} from "@agent-native/core/client/settings";
 import { CreativeContextSettingsLink } from "@agent-native/creative-context/client";
 import {
   IconAlertCircle,

package/corpus/templates/brain/.agents/skills/actions/SKILL.md

@@ -309,7 +309,7 @@ The frontend calls actions using React Query hooks from `@agent-native/core/clie
 ### `useActionQuery` — for GET actions
 
 ```ts
-import { useActionQuery } from "@agent-native/core/client";
+import { useActionQuery } from "@agent-native/core/client/hooks";
 
 function MealList() {
   // Types are auto-inferred from the action's schema + return type — no manual generic needed
@@ -323,7 +323,7 @@ function MealList() {
 ### `useActionMutation` — for POST/PUT/DELETE actions
 
 ```ts
-import { useActionMutation } from "@agent-native/core/client";
+import { useActionMutation } from "@agent-native/core/client/hooks";
 
 function AddMealButton() {
   // Types are auto-inferred — no manual generic needed
@@ -343,7 +343,7 @@ Mutations automatically invalidate all `["action"]` query keys on success, so GE
 ### `callAction` — for imperative client code
 
 ```ts
-import { callAction } from "@agent-native/core/client";
+import { callAction } from "@agent-native/core/client/hooks";
 
 const people = await callAction("search-people", { query }, { method: "GET" });
 ```

package/corpus/templates/brain/.agents/skills/adding-a-feature/SKILL.md

@@ -32,7 +32,7 @@ Build the user-facing interface — a page, component, dialog, or route. Use `us
 - **Raw `useQuery` with custom keys** — needs explicit wiring. Fold `useChangeVersions([<source>, "action"])` from `@agent-native/core/client` into the `queryKey` and set `placeholderData: (prev) => prev`. The `action` source is the reliable signal (the agent runner emits it after every successful tool call); the resource-specific source (`"dashboards"`, `"analyses"`, `"settings"`, etc.) is bonus when emitted. Without this wiring, agent writes will be invisible until manual refresh — that breaks the framework's #1 promise.
 
   ```tsx
-  import { useChangeVersions } from "@agent-native/core/client";
+  import { useChangeVersions } from "@agent-native/core/client/hooks";
   import { useQuery } from "@tanstack/react-query";
 
   const v = useChangeVersions(["dashboards", "action"]);

package/corpus/templates/brain/.agents/skills/delegate-to-agent/SKILL.md

@@ -29,7 +29,7 @@ The agent is the single AI interface. It has context about the full project, can
 **From the UI (client):**
 
 ```ts
-import { sendToAgentChat } from "@agent-native/core/client";
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 
 sendToAgentChat({
   message: "Generate a summary of this document",
@@ -41,7 +41,7 @@ sendToAgentChat({
 **From the UI, in the background:**
 
 ```ts
-import { sendToAgentChat } from "@agent-native/core/client";
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 
 sendToAgentChat({
   message: "Analyze this import and create any missing records",
@@ -83,7 +83,7 @@ Do not call provider SDKs directly.
 **From the UI, detecting when agent is done:**
 
 ```ts
-import { useAgentChatGenerating } from "@agent-native/core/client";
+import { useAgentChatGenerating } from "@agent-native/core/client/agent-chat";
 
 function MyComponent() {
   const isGenerating = useAgentChatGenerating();

package/corpus/templates/brain/.agents/skills/feature-flags/SKILL.md

@@ -81,7 +81,7 @@ run: async (args, ctx) => {
 Use the client hook only to hide or reveal hydrated UI:
 
 ```tsx
-import { useFeatureFlag } from "@agent-native/core/client";
+import { useFeatureFlag } from "@agent-native/core/client/feature-flags";
 
 const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
 return enabled ? <FullAppOption /> : null;

package/corpus/templates/brain/.agents/skills/real-time-sync/SKILL.md

@@ -26,7 +26,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 2. **Client** listens for sync events and updates per-source change counters:
 
    ```ts
-   import { useDbSync } from "@agent-native/core/client";
+   import { useDbSync } from "@agent-native/core/client/hooks";
    useDbSync({ queryClient });
    ```
 
@@ -35,7 +35,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
    ```ts
-   import { useChangeVersion } from "@agent-native/core/client";
+   import { useChangeVersion } from "@agent-native/core/client/hooks";
    import { useQuery } from "@tanstack/react-query";
 
    const v = useChangeVersion("dashboards");
@@ -61,7 +61,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 - Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
 
   ```ts
-  import { subscribeSyncEvents } from "@agent-native/core/client";
+  import { subscribeSyncEvents } from "@agent-native/core/client/hooks";
 
   const unsubscribe = subscribeSyncEvents({
     onEvents: (events) => {
@@ -198,7 +198,7 @@ When the agent renames the record, the query refetches, `props.title` updates, b
 **Derived-state surfaces (form fields, inline editors, popovers): use `useReconciledState`.** It re-adopts the authoritative external value when it changes, except while the user is actively editing that field — so agent mutations show up live without clobbering in-progress typing:
 
 ```ts
-import { useReconciledState } from "@agent-native/core/client";
+import { useReconciledState } from "@agent-native/core/client/hooks";
 
 // `active` = true while the user is editing this field (focused / dirty).
 const [title, setTitle] = useReconciledState(props.title, { active: isEditing });

package/corpus/templates/brain/.agents/skills/upgrade-agent-native/SKILL.md

@@ -28,18 +28,20 @@ install → refresh scaffold skills → verify, then fix **app** code only.
 
 ## How
 
-1. **Doctor first (optional but recommended)**
+1. **Preview migration codemods first**
 
    ```bash
-   npx @agent-native/core@latest upgrade check
+   npx @agent-native/core@latest upgrade --codemods
    ```
 
-   This reports framework overrides/patches and pending `@agent-native/*`
-   bumps. If overrides/patches are present, remove them before continuing.
+   Codemods are preview-by-default: read the diff before applying it. Do not
+   manually edit imports before running this command; the migration manifest is
+   the source of truth for renamed specifiers and symbols.
 
-2. **Run the upgrade**
+2. **Apply the reviewed codemods, then run the upgrade**
 
    ```bash
+   npx @agent-native/core@latest upgrade --codemods --yes
    npx @agent-native/core@latest upgrade
    ```
 
@@ -67,8 +69,13 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    agent-native upgrade --dry-run
    agent-native upgrade --skip-verify
    agent-native upgrade --skip-install   # package.json bumps only
+   agent-native doctor --only migration-manifest
    ```
 
+   `migration-manifest` has no opt-out. Run it in CI before upgrading to find
+   imports that will break, then use `npx @agent-native/core@latest upgrade --codemods`
+   to preview the supported rewrite.
+
 ## Don't
 
 - Don't add `pnpm.overrides`, `overrides`, `resolutions`, or

package/corpus/templates/brain/app/components/brain/CanonicalPreviewSheet.tsx

@@ -1,4 +1,4 @@
-import { useT } from "@agent-native/core/client";
+import { useT } from "@agent-native/core/client/i18n";
 import { IconAlertTriangle, IconBook, IconFileText } from "@tabler/icons-react";
 
 import { Badge } from "@/components/ui/badge";

package/corpus/templates/brain/app/components/layout/Layout.tsx

@@ -4,8 +4,8 @@ import {
   navigateWithAgentChatViewTransition,
   useAgentChatHomeHandoff,
   useAgentChatHomeHandoffLinks,
-  useT,
-} from "@agent-native/core/client";
+} from "@agent-native/core/client/agent-chat";
+import { useT } from "@agent-native/core/client/i18n";
 import { IconMenu2 } from "@tabler/icons-react";
 import { useEffect, useState } from "react";
 import { useLocation, useNavigate } from "react-router";

package/corpus/templates/brain/app/components/layout/Sidebar.tsx

@@ -1,14 +1,14 @@
 import {
-  appPath,
-  DevDatabaseLink,
-  FeedbackButton,
   navigateWithAgentChatViewTransition,
   useChatThreads,
-  useT,
   type ChatThreadSummary,
-} from "@agent-native/core/client";
+} from "@agent-native/core/client/agent-chat";
+import { appPath } from "@agent-native/core/client/api-path";
+import { DevDatabaseLink } from "@agent-native/core/client/db-admin";
 import { ExtensionsSidebarSection } from "@agent-native/core/client/extensions";
+import { useT } from "@agent-native/core/client/i18n";
 import { OrgSwitcher } from "@agent-native/core/client/org";
+import { FeedbackButton } from "@agent-native/core/client/ui";
 import {
   IconArchive,
   IconDots,

package/corpus/templates/brain/app/hooks/use-distillation-bridge.ts

@@ -1,9 +1,6 @@
-import {
-  agentNativePath,
-  callAction,
-  sendToAgentChat,
-  useActionQuery,
-} from "@agent-native/core/client";
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+import { agentNativePath } from "@agent-native/core/client/api-path";
+import { callAction, useActionQuery } from "@agent-native/core/client/hooks";
 import { useEffect, useMemo, useRef } from "react";
 
 import type { BrainCaptureReviewItem, CapturesResponse } from "@/lib/brain";

package/corpus/templates/brain/app/hooks/use-navigation-state.ts

@@ -1,10 +1,9 @@
 import {
-  appBasePath,
-  appPath,
   isAgentChatHomeHandoffActive,
   markAgentChatHomeHandoff,
-  useAgentRouteState,
-} from "@agent-native/core/client";
+} from "@agent-native/core/client/agent-chat";
+import { appBasePath, appPath } from "@agent-native/core/client/api-path";
+import { useAgentRouteState } from "@agent-native/core/client/navigation";
 import { useLocation } from "react-router";
 
 import { pathFromView, viewFromPath, type BrainView } from "@/lib/brain";

package/corpus/templates/brain/app/i18n/index.ts

@@ -1,4 +1,4 @@
-import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
+import { type AgentNativeI18nCatalog } from "@agent-native/core/client/i18n";
 
 import enUS from "./en-US";
 

package/corpus/templates/brain/app/i18n-data.ts

@@ -1,4 +1,4 @@
-import type { LocaleCode } from "@agent-native/core/client";
+import { type LocaleCode } from "@agent-native/core/client/i18n";
 
 import zhTW from "./i18n/zh-TW";
 

package/corpus/templates/brain/app/lib/utils.ts

@@ -1 +1 @@
-export { cn } from "@agent-native/core/client";
+export { cn } from "@agent-native/toolkit/utils";

package/corpus/templates/brain/app/root.tsx

@@ -1,15 +1,16 @@
-import { useDbSync } from "@agent-native/core/client";
+import { configureTracking } from "@agent-native/core/client/analytics";
+import { appPath } from "@agent-native/core/client/api-path";
+import { useDbSync } from "@agent-native/core/client/hooks";
 import {
   AppProviders,
-  CommandMenu,
-  appPath,
   createAgentNativeQueryClient,
-  getLocaleInitScript,
-  getThemeInitScript,
+} from "@agent-native/core/client/hooks";
+import { getLocaleInitScript, useT } from "@agent-native/core/client/i18n";
+import {
+  CommandMenu,
   useCommandMenuShortcut,
-  useT,
-} from "@agent-native/core/client";
-import { configureTracking } from "@agent-native/core/client";
+} from "@agent-native/core/client/navigation";
+import { getThemeInitScript } from "@agent-native/core/client/ui";
 import { IconBrain, IconMoon, IconSun } from "@tabler/icons-react";
 import { useQueryClient } from "@tanstack/react-query";
 import { useTheme } from "next-themes";
@@ -240,4 +241,4 @@ export default function Root() {
   );
 }
 
-export { ErrorBoundary } from "@agent-native/core/client";
+export { ErrorBoundary } from "@agent-native/core/client/ui";

package/corpus/templates/brain/app/routes/_index.tsx

@@ -1,8 +1,8 @@
 import {
   AgentChatSurface,
   markAgentChatHomeHandoff,
-  useT,
-} from "@agent-native/core/client";
+} from "@agent-native/core/client/agent-chat";
+import { useT } from "@agent-native/core/client/i18n";
 import { useEffect } from "react";
 
 import { TAB_ID } from "@/lib/tab-id";

package/corpus/templates/brain/app/routes/agent.tsx

@@ -1,4 +1,4 @@
-import { AgentTabsPage } from "@agent-native/core/client";
+import { AgentTabsPage } from "@agent-native/core/client/agent-chat";
 
 import { messagesByLocale } from "@/i18n-data";
 

package/corpus/templates/brain/app/routes/knowledge.tsx

@@ -1,8 +1,8 @@
 import {
   useActionMutation,
   useActionQuery,
-  useT,
-} from "@agent-native/core/client";
+} from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
 import {
   IconBook,
   IconCheck,

package/corpus/templates/brain/app/routes/ops.tsx

@@ -1,8 +1,8 @@
 import {
   useActionMutation,
   useActionQuery,
-  useT,
-} from "@agent-native/core/client";
+} from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
 import {
   IconAlertTriangle,
   IconChecks,

package/corpus/templates/brain/app/routes/review.tsx

@@ -1,8 +1,8 @@
 import {
   useActionMutation,
   useActionQuery,
-  useT,
-} from "@agent-native/core/client";
+} from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
 import {
   type Icon,
   IconChartBar,

package/corpus/templates/brain/app/routes/search.tsx

@@ -1,4 +1,5 @@
-import { useActionQuery, useT } from "@agent-native/core/client";
+import { useActionQuery } from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
 import {
   IconBook2,
   IconCircleCheck,

package/corpus/templates/brain/app/routes/settings.tsx

@@ -1,15 +1,16 @@
+import { ChangelogSettingsCard } from "@agent-native/core/client/changelog";
 import {
-  ChangelogSettingsCard,
-  LanguagePicker,
-  SettingsTabsPage,
-  useAgentSettingsTabs,
   useActionMutation,
   useActionQuery,
-  useT,
+} from "@agent-native/core/client/hooks";
+import { LanguagePicker, useT } from "@agent-native/core/client/i18n";
+import { TeamPage } from "@agent-native/core/client/org";
+import {
+  SettingsTabsPage,
+  useAgentSettingsTabs,
   type SettingsSearchEntry,
   type SettingsTabItem,
-} from "@agent-native/core/client";
-import { TeamPage } from "@agent-native/core/client/org";
+} from "@agent-native/core/client/settings";
 import {
   IconAdjustments,
   IconDeviceFloppy,

package/corpus/templates/brain/app/routes/sources.tsx

@@ -1,8 +1,8 @@
 import {
   useActionMutation,
   useActionQuery,
-  useT,
-} from "@agent-native/core/client";
+} from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
 import {
   IconAlertTriangle,
   IconArchive,

package/corpus/templates/calendar/.agents/skills/actions/SKILL.md

@@ -309,7 +309,7 @@ The frontend calls actions using React Query hooks from `@agent-native/core/clie
 ### `useActionQuery` — for GET actions
 
 ```ts
-import { useActionQuery } from "@agent-native/core/client";
+import { useActionQuery } from "@agent-native/core/client/hooks";
 
 function MealList() {
   // Types are auto-inferred from the action's schema + return type — no manual generic needed
@@ -323,7 +323,7 @@ function MealList() {
 ### `useActionMutation` — for POST/PUT/DELETE actions
 
 ```ts
-import { useActionMutation } from "@agent-native/core/client";
+import { useActionMutation } from "@agent-native/core/client/hooks";
 
 function AddMealButton() {
   // Types are auto-inferred — no manual generic needed
@@ -343,7 +343,7 @@ Mutations automatically invalidate all `["action"]` query keys on success, so GE
 ### `callAction` — for imperative client code
 
 ```ts
-import { callAction } from "@agent-native/core/client";
+import { callAction } from "@agent-native/core/client/hooks";
 
 const people = await callAction("search-people", { query }, { method: "GET" });
 ```

package/corpus/templates/calendar/.agents/skills/delegate-to-agent/SKILL.md

@@ -29,7 +29,7 @@ The agent is the single AI interface. It has context about the full project, can
 **From the UI (client):**
 
 ```ts
-import { sendToAgentChat } from "@agent-native/core/client";
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 
 sendToAgentChat({
   message: "Generate a summary of this document",
@@ -41,7 +41,7 @@ sendToAgentChat({
 **From the UI, in the background:**
 
 ```ts
-import { sendToAgentChat } from "@agent-native/core/client";
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 
 sendToAgentChat({
   message: "Analyze this import and create any missing records",
@@ -83,7 +83,7 @@ Do not call provider SDKs directly.
 **From the UI, detecting when agent is done:**
 
 ```ts
-import { useAgentChatGenerating } from "@agent-native/core/client";
+import { useAgentChatGenerating } from "@agent-native/core/client/agent-chat";
 
 function MyComponent() {
   const isGenerating = useAgentChatGenerating();

package/corpus/templates/calendar/.agents/skills/feature-flags/SKILL.md

@@ -81,7 +81,7 @@ run: async (args, ctx) => {
 Use the client hook only to hide or reveal hydrated UI:
 
 ```tsx
-import { useFeatureFlag } from "@agent-native/core/client";
+import { useFeatureFlag } from "@agent-native/core/client/feature-flags";
 
 const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
 return enabled ? <FullAppOption /> : null;

package/corpus/templates/calendar/.agents/skills/real-time-sync/SKILL.md

@@ -26,7 +26,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 2. **Client** listens for sync events and updates per-source change counters:
 
    ```ts
-   import { useDbSync } from "@agent-native/core/client";
+   import { useDbSync } from "@agent-native/core/client/hooks";
    useDbSync({ queryClient });
    ```
 
@@ -35,7 +35,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
    ```ts
-   import { useChangeVersion } from "@agent-native/core/client";
+   import { useChangeVersion } from "@agent-native/core/client/hooks";
    import { useQuery } from "@tanstack/react-query";
 
    const v = useChangeVersion("dashboards");
@@ -61,7 +61,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 - Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
 
   ```ts
-  import { subscribeSyncEvents } from "@agent-native/core/client";
+  import { subscribeSyncEvents } from "@agent-native/core/client/hooks";
 
   const unsubscribe = subscribeSyncEvents({
     onEvents: (events) => {
@@ -198,7 +198,7 @@ When the agent renames the record, the query refetches, `props.title` updates, b
 **Derived-state surfaces (form fields, inline editors, popovers): use `useReconciledState`.** It re-adopts the authoritative external value when it changes, except while the user is actively editing that field — so agent mutations show up live without clobbering in-progress typing:
 
 ```ts
-import { useReconciledState } from "@agent-native/core/client";
+import { useReconciledState } from "@agent-native/core/client/hooks";
 
 // `active` = true while the user is editing this field (focused / dirty).
 const [title, setTitle] = useReconciledState(props.title, { active: isEditing });

package/corpus/templates/calendar/.agents/skills/storing-data/SKILL.md

@@ -105,7 +105,7 @@ All of these honor the per-user / per-org data scoping — you can't read or wri
 The frontend calls actions using React Query hooks from the client API. The framework owns the HTTP transport behind these hooks, so components should not call action routes with raw `fetch`.
 
 ```ts
-import { useActionQuery, useActionMutation } from "@agent-native/core/client";
+import { useActionQuery, useActionMutation } from "@agent-native/core/client/hooks";
 
 // Read data
 const { data } = useActionQuery("list-meals", { date: "2025-01-01" });

package/corpus/templates/calendar/.agents/skills/upgrade-agent-native/SKILL.md

@@ -28,18 +28,20 @@ install → refresh scaffold skills → verify, then fix **app** code only.
 
 ## How
 
-1. **Doctor first (optional but recommended)**
+1. **Preview migration codemods first**
 
    ```bash
-   npx @agent-native/core@latest upgrade check
+   npx @agent-native/core@latest upgrade --codemods
    ```
 
-   This reports framework overrides/patches and pending `@agent-native/*`
-   bumps. If overrides/patches are present, remove them before continuing.
+   Codemods are preview-by-default: read the diff before applying it. Do not
+   manually edit imports before running this command; the migration manifest is
+   the source of truth for renamed specifiers and symbols.
 
-2. **Run the upgrade**
+2. **Apply the reviewed codemods, then run the upgrade**
 
    ```bash
+   npx @agent-native/core@latest upgrade --codemods --yes
    npx @agent-native/core@latest upgrade
    ```
 
@@ -67,8 +69,13 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    agent-native upgrade --dry-run
    agent-native upgrade --skip-verify
    agent-native upgrade --skip-install   # package.json bumps only
+   agent-native doctor --only migration-manifest
    ```
 
+   `migration-manifest` has no opt-out. Run it in CI before upgrading to find
+   imports that will break, then use `npx @agent-native/core@latest upgrade --codemods`
+   to preview the supported rewrite.
+
 ## Don't
 
 - Don't add `pnpm.overrides`, `overrides`, `resolutions`, or

package/corpus/templates/calendar/app/components/CloudUpgrade.tsx

@@ -1,4 +1,4 @@
-import { useT } from "@agent-native/core/client";
+import { useT } from "@agent-native/core/client/i18n";
 import {
   IconX,
   IconCheck,

package/corpus/templates/calendar/app/components/ThemeToggle.tsx

@@ -1,4 +1,4 @@
-import { useT } from "@agent-native/core/client";
+import { useT } from "@agent-native/core/client/i18n";
 import { IconSun, IconMoon } from "@tabler/icons-react";
 import { useTheme } from "next-themes";
 

package/corpus/templates/calendar/app/components/TimezoneCombobox.tsx

@@ -1,4 +1,4 @@
-import { useT } from "@agent-native/core/client";
+import { useT } from "@agent-native/core/client/i18n";
 import { IconCheck, IconChevronDown } from "@tabler/icons-react";
 import { useState } from "react";