diff --git a/docs/migrating-from-v3.mdx b/docs/migrating-from-v3.mdx
index 03f0cae5776..4d9c0eed4ce 100644
--- a/docs/migrating-from-v3.mdx
+++ b/docs/migrating-from-v3.mdx
@@ -6,6 +6,20 @@ description: "What's new in v4, how to migrate, and breaking changes."
 import NodeVersions from "/snippets/node-versions.mdx";
 import MigrateV4UsingAi from "/snippets/migrate-v4-using-ai.mdx";
 
+<Warning>
+  **Action required: Trigger.dev v3 deprecation**
+
+We're retiring Trigger.dev v3. **New v3 deploys will stop working from 1 April 2026.** Trigger.dev v4 is stable, fully supported, and recommended for all users.
+
+**Key dates:**
+
+- **1 April 2026** — New v3 deploys will no longer work. Existing v3 runs will continue to execute.
+- **1 July 2026** — v3 will be fully shut down. All v3 runs will stop executing.
+
+**What you need to do:** Migrate to v4 before April to avoid disruption to your task executions. The migration takes about 2 minutes — follow the steps on this page below. If you have questions or need help, [contact us](https://trigger.dev/contact) or reach out in our [Discord](https://trigger.dev/discord).
+
+</Warning>
+
 ## What's new in v4?
 
 | Feature                                                              | Description                                                                                                                                                                                                |
diff --git a/docs/snippets/migrate-v4-using-ai.mdx b/docs/snippets/migrate-v4-using-ai.mdx
index 1681bd30fc1..fa749ed7231 100644
--- a/docs/snippets/migrate-v4-using-ai.mdx
+++ b/docs/snippets/migrate-v4-using-ai.mdx
@@ -151,7 +151,7 @@ await myTask.trigger({ foo: "bar" });
 await myTask.trigger({ foo: "bar" }, { queue: "my-queue" });
 
 
-**Lifecycle hooks**: Function signatures have changed to use a single object parameter instead of separate parameters. This is the old version:
+**Lifecycle hooks**: Function signatures have changed to use a single object parameter instead of separate parameters. Prefer `onStartAttempt` over the deprecated `onStart` when you need code to run before each attempt. This is the old version:
 
 
 // Old v3 way
@@ -171,10 +171,10 @@ This is the new version:
 // New v4 way - single object parameter for hooks
 export const myTask = task({
   id: "my-task",
-  onStart: ({ payload, ctx }) => {},
-  onSuccess: ({ payload, output, ctx }) => {},
-  onFailure: ({ payload, error, ctx }) => {},
-  catchError: ({ payload, ctx, error, retry }) => {},
+  onStartAttempt: ({ payload, ctx }) => {},  // prefer over deprecated onStart
+  onSuccess: ({ payload, ctx, task, output }) => {},
+  onFailure: ({ payload, ctx, task, error }) => {},
+  catchError: ({ payload, ctx, task, error, retry, retryAt, retryDelayInMs }) => {},
   run: async (payload, { ctx }) => {}, // run function unchanged
 });
 
@@ -204,6 +204,12 @@ const batch = await batch.retrieve(batchHandle.batchId); // Use batch.retrieve()
 console.log(batch.runs);
 
 
+**triggerAndWait / batchTriggerAndWait**: In v4 these return a Result object, not the raw output. Use `if (result.ok) { ... result.output }` or call `.unwrap()` to get the output (throws if the run failed). Do not wrap `triggerAndWait` or `batchTriggerAndWait` in `Promise.all` — this is not supported.
+
+
+**Context (ctx) changes**: `ctx.attempt.id` and `ctx.attempt.status` have been removed; use `ctx.attempt.number` where needed. `ctx.task.exportName` has been removed.
+
+
 Can you help me convert the following code from v3 to v4? Please include the full converted code in the answer, do not truncate it anywhere.
 
 ```