diff --git a/rivetkit-typescript/packages/rivetkit/src/actor/config.ts b/rivetkit-typescript/packages/rivetkit/src/actor/config.ts
index c82621a63d..177fef7264 100644
--- a/rivetkit-typescript/packages/rivetkit/src/actor/config.ts
+++ b/rivetkit-typescript/packages/rivetkit/src/actor/config.ts
@@ -884,7 +884,7 @@ const InstanceActorOptionsBaseSchema = z
 			.default(DEFAULT_WAIT_UNTIL_TIMEOUT),
 		connectionLivenessTimeout: z.number().positive().default(2500),
 		connectionLivenessInterval: z.number().positive().default(5000),
-		/** @deprecated Use `c.setPreventSleep(true)` for bounded delays or keep `noSleep` for actors that must stay awake indefinitely. Will be removed in 2.2.0. */
+		/** @deprecated Use `c.keepAwake(promise)` to scope keep-awake to a specific operation, or keep `noSleep` for actors that must stay awake indefinitely. Will be removed in 2.2.0. */
 		noSleep: z.boolean().default(false),
 		sleepTimeout: z.number().positive().default(30_000),
 		maxQueueSize: z.number().positive().default(1000),
@@ -1808,7 +1808,7 @@ export const DocActorOptionsSchema = z
 			.boolean()
 			.optional()
 			.describe(
-				"Deprecated. If true, the actor will never sleep. Use c.setPreventSleep(true) for bounded idle sleep delays instead. Default: false",
+				"Deprecated. If true, the actor will never sleep. Use c.keepAwake(promise) to scope keep-awake to a specific operation instead. Default: false",
 			),
 		sleepTimeout: z
 			.number()
diff --git a/rivetkit-typescript/packages/rivetkit/src/workflow/context.ts b/rivetkit-typescript/packages/rivetkit/src/workflow/context.ts
index db4eb3a58e..adac7fa055 100644
--- a/rivetkit-typescript/packages/rivetkit/src/workflow/context.ts
+++ b/rivetkit-typescript/packages/rivetkit/src/workflow/context.ts
@@ -545,9 +545,10 @@ export class ActorWorkflowContext<
 	}
 
 	/**
-	 * @deprecated Use `onSleep` for shutdown or flush work, or
-	 * `c.setPreventSleep(true)` while work is active if the actor must stay
-	 * awake until it finishes.
+	 * Registers a promise that the sleep grace period will wait on. Use this
+	 * for best-effort flush/cleanup work that may complete inside the grace
+	 * window. For work the actor must stay running through, prefer
+	 * `c.keepAwake(promise)` which also blocks idle sleep.
 	 */
 	waitUntil(promise: Promise<void>): void {
 		this.#ensureActorAccess("waitUntil");
diff --git a/website/src/content/docs/actors/limits.mdx b/website/src/content/docs/actors/limits.mdx
index d5f4a3cc73..c5c899510a 100644
--- a/website/src/content/docs/actors/limits.mdx
+++ b/website/src/content/docs/actors/limits.mdx
@@ -128,7 +128,7 @@ See [Actor Input](/docs/actors/input) for details.
 | Create vars timeout | 5 seconds | — | Timeout for `createVars` hook. Configurable via `createVarsTimeout`. |
 | Create conn state timeout | 5 seconds | — | Timeout for `createConnState` hook. Configurable via `createConnStateTimeout`. |
 | On connect timeout | 5 seconds | — | Timeout for `onConnect` hook. Configurable via `onConnectTimeout`. |
-| Sleep grace period | 15 seconds | — | Total graceful sleep budget for `onSleep`, `waitUntil`, async raw WebSocket handlers, and waiting for `preventSleep` to clear after shutdown starts. |
+| Sleep grace period | 15 seconds | — | Total graceful sleep budget for `onSleep`, `waitUntil`, `keepAwake`, and async raw WebSocket handlers. |
 | On destroy timeout | 15 seconds | — | Total graceful destroy budget for `onDestroy`, run handler shutdown, and connection cleanup. Configurable via `onDestroyTimeout`. |
 | Sleep timeout | 30 seconds | — | Time of inactivity before actor hibernates. Configurable via `sleepTimeout`. |
 | State save interval | 10 seconds | — | Interval between automatic state saves. Configurable via `stateSaveInterval`. |
diff --git a/website/src/content/docs/actors/versions.mdx b/website/src/content/docs/actors/versions.mdx
index d14a561654..c5726703bf 100644
--- a/website/src/content/docs/actors/versions.mdx
+++ b/website/src/content/docs/actors/versions.mdx
@@ -357,7 +357,7 @@ Several timeouts control how long each part of the shutdown process can take:
 | Timeout | Default | Description | Configuration |
 |---------|---------|-------------|---------------|
 | `actor_stop_threshold` | 30s | Engine-side limit on how long each actor has to stop before being marked lost | [Engine config](/docs/self-hosting/configuration) (`pegboard.actor_stop_threshold`) |
-| `sleepGracePeriod` | 15s | Total graceful sleep budget for `onSleep`, `waitUntil`, async raw WebSocket handlers, and waiting for `preventSleep` to clear after shutdown starts | [Actor options](/docs/actors/lifecycle#options) |
+| `sleepGracePeriod` | 15s | Total graceful sleep budget for `onSleep`, `waitUntil`, `keepAwake`, and async raw WebSocket handlers | [Actor options](/docs/actors/lifecycle#options) |
 | `runner_lost_threshold` | 15s | Fallback detection if the runner dies without graceful shutdown | [Engine config](/docs/self-hosting/configuration) (`pegboard.runner_lost_threshold`) |
 
 Rivet has a max shutdown grace period of 30 minutes that cannot be configured.
diff --git a/website/src/content/docs/general/architecture.mdx b/website/src/content/docs/general/architecture.mdx
index 8d57c3c445..fe6e1f3a00 100644
--- a/website/src/content/docs/general/architecture.mdx
+++ b/website/src/content/docs/general/architecture.mdx
@@ -72,7 +72,7 @@ actors have create, destroy, wake, and sleep lifecycle hooks that you can implem
 - actors sleep when not in use
 - an actor is considered not in use when there are no active network connections to the actor (or the network connections are hibernatable websockets, see below) and there are no actions in flight
 - actors have a sleep timeout (configured in `options.sleepTimeout`) that decides how long to keep the actor in memory with no recent activity
-- sleep can be delayed while idle with `c.setPreventSleep(true)`
+- sleep can be held off for the lifetime of a promise with `c.keepAwake(promise)`
 - see the [sleeping docs](/docs/actors/lifecycle#sleeping) for full details
 
 ### wake events