Document codemod errors and intentional migration exceptions

docs/01-app/02-guides/upgrading/codemods.mdx

@@ -76,12 +76,13 @@ npx @next/codemod upgrade canary --yes
 npx @next/codemod@canary cache-components-instant-false ./app
 ```
 
-This codemod adds `export const instant = false` to every `{page,layout,default}` file in your app directory that doesn't already export `instant`, so you can enable [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) and then remove the opt-outs route by route. It skips Client Components (`"use client"`) and files that already declare `instant`.
+This codemod adds `export const instant = false` to every `{page,layout,default}` file in your app directory that doesn't already export `instant`, so you can enable [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) and then remove the opt-outs route by route. It skips Client Components (`"use client"`) and files that already declare `instant`. The generated `@next-codemod-ignore` comment marks the intentional opt-out without blocking compilation.
 
 > **Good to know**: Pass `./src/app` in a `src/` project. A wrong path reports `0 ok` instead of failing, so check the file count.
 
 ```diff filename="app/page.tsx"
-+ // TODO: Cache Components adoption. Refactor this route so this opt-out can be removed.
++ // @next-codemod-ignore Cache Components adoption: this segment temporarily allows blocking.
++ // Remove this opt-out after verifying the segment passes validation without it.
 + // See: https://nextjs.org/docs/app/guides/migrating-to-cache-components
 + export const instant = false
 +
@@ -291,7 +292,9 @@ npx @next/codemod@latest next-async-request-api .
 ```
 
 This codemod will transform dynamic APIs (`cookies()`, `headers()` and `draftMode()` from `next/headers`) that are now asynchronous to be properly awaited or wrapped with `React.use()` if applicable.
-When an automatic migration isn't possible, the codemod will either add a typecast (if a TypeScript file) or a comment to inform the user that it needs to be manually reviewed & updated.
+When automatic migration isn't possible, the codemod adds an `@next-codemod-error` comment and may add a temporary `UnsafeUnwrapped*` cast. Complete the migration before removing them. If the suggested change doesn't apply, replace the directive with `@next-codemod-ignore` and explain why.
+
+See the [Async Request APIs migration guide](/docs/app/guides/upgrading/version-15#async-request-apis-breaking-change) for examples.
 
 For example:
 
@@ -323,7 +326,9 @@ import {
   type UnsafeUnwrappedCookies,
   type UnsafeUnwrappedHeaders,
 } from 'next/headers'
-const token = (cookies() as unknown as UnsafeUnwrappedCookies).get('token')
+const token =
+  /* @next-codemod-error Await this API and update its callers; remove the temporary UnsafeUnwrappedCookies cast after repairing the migration. */
+  (cookies() as unknown as UnsafeUnwrappedCookies).get('token')
 
 function useToken() {
   const token = use(cookies()).get('token')
@@ -335,7 +340,10 @@ export default async function Page() {
 }
 
 function getHeader() {
-  return (headers() as unknown as UnsafeUnwrappedHeaders).get('x-foo')
+  return (
+    /* @next-codemod-error Await this API and update its callers; remove the temporary UnsafeUnwrappedHeaders cast after repairing the migration. */
+    (headers() as unknown as UnsafeUnwrappedHeaders).get('x-foo')
+  )
 }
 ```