docs: add unstable_cache → use cache migration guide

docs/01-app/02-guides/migrating-to-cache-components.mdx

@@ -4,7 +4,7 @@ nav_title: Migrating to Cache Components
 description: Learn how to migrate from route segment configs to Cache Components in Next.js.
 ---
 
-When [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled, route segment configs like `dynamic`, `revalidate`, and `fetchCache` are replaced by [`use cache`](/docs/app/api-reference/directives/use-cache) and [`cacheLife`](/docs/app/api-reference/functions/cacheLife).
+When [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled, route segment configs like `dynamic`, `revalidate`, and `fetchCache` are replaced by [`use cache`](/docs/app/api-reference/directives/use-cache) and [`cacheLife`](/docs/app/api-reference/functions/cacheLife). The [`unstable_cache`](/docs/app/api-reference/functions/unstable_cache) function is also replaced by `use cache`.
 
 ## `dynamic = "force-dynamic"`
 
@@ -170,6 +170,64 @@ export default async function Page() {
 }
 ```
 
+## `unstable_cache`
+
+**Replace with `use cache`.** Instead of wrapping a function with `unstable_cache`, add the `use cache` directive at the top of the function. Use [`cacheLife`](/docs/app/api-reference/functions/cacheLife) to control duration and [`cacheTag`](/docs/app/api-reference/functions/cacheTag) for on-demand invalidation.
+
+```tsx filename="app/lib/data.ts" switcher
+// Before
+import { unstable_cache } from 'next/cache'
+
+export const getCachedUser = unstable_cache(
+  async (id: string) => getUser(id),
+  ['my-app-user'],
+  {
+    revalidate: 3600,
+    tags: ['users'],
+  }
+)
+```
+
+```jsx filename="app/lib/data.js" switcher
+// Before
+import { unstable_cache } from 'next/cache'
+
+export const getCachedUser = unstable_cache(
+  async (id) => getUser(id),
+  ['my-app-user'],
+  {
+    revalidate: 3600,
+    tags: ['users'],
+  }
+)
+```
+
+```tsx filename="app/lib/data.ts" switcher
+// After - Use 'use cache' with cacheLife and cacheTag
+import { cacheLife, cacheTag } from 'next/cache'
+
+export async function getCachedUser(id: string) {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('users')
+  return getUser(id)
+}
+```
+
+```jsx filename="app/lib/data.js" switcher
+// After - Use 'use cache' with cacheLife and cacheTag
+import { cacheLife, cacheTag } from 'next/cache'
+
+export async function getCachedUser(id) {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('users')
+  return getUser(id)
+}
+```
+
+The `keyParts` array is not needed. `use cache` generates cache keys automatically from the function's arguments and closure variables. Use a [preset profile](/docs/app/api-reference/functions/cacheLife#preset-cache-profiles) like `'hours'` or `'days'` to replace the `revalidate` option, or pass an [inline object](/docs/app/api-reference/functions/cacheLife#inline-cache-profiles) for exact seconds.
+
 ## `runtime = 'edge'`
 
 **Not supported.** Cache Components requires the Node.js runtime. Switch to the Node.js runtime (the default) by removing the `runtime = 'edge'` export. If you need edge behavior for specific routes, use [Proxy](/docs/app/api-reference/file-conventions/proxy) instead.

docs/01-app/03-api-reference/04-functions/unstable_cache.mdx

@@ -5,7 +5,7 @@ description: API Reference for the unstable_cache function.
 
 > **Note:**
 > This API has been replaced by [`use cache`](/docs/app/api-reference/directives/use-cache) in Next.js 16.
-> We recommend opting into [Cache Components](/docs/app/getting-started/caching) and replacing `unstable_cache` with the `use cache` directive.
+> We recommend opting into [Cache Components](/docs/app/getting-started/caching) and replacing `unstable_cache` with the `use cache` directive. See the [migration guide](/docs/app/guides/migrating-to-cache-components#unstable_cache) for step-by-step instructions.
 
 `unstable_cache` allows you to cache the results of expensive operations, like database queries, and reuse them across multiple requests.