[Durable Objects] restructure docs around Diátaxis framework

public/__redirects

@@ -527,29 +527,49 @@
 /support/dns/troubleshooting/why-was-my-domain-deleted-from-cloudflare/ /dns/zone-setups/troubleshooting/domain-deleted/ 301
 
 # Durable Objects
-/durable-objects/api/hibernatable-websockets-api/ /durable-objects/best-practices/websockets/ 301
+/durable-objects/api/hibernatable-websockets-api/ /durable-objects/how-to/use-websockets/ 301
 /durable-objects/api/alarms-in-durable-objects/ /durable-objects/api/alarms/ 301
-/durable-objects/api/websockets/ /durable-objects/best-practices/websockets/ 301
+/durable-objects/api/websockets/ /durable-objects/how-to/use-websockets/ 301
 /durable-objects/api/sql-storage/ /durable-objects/api/sqlite-storage-api/ 301
 /durable-objects/api/transactional-storage-api/ /durable-objects/api/sqlite-storage-api/ 301
 /durable-objects/api/storage-api/ /durable-objects/api/sqlite-storage-api/ 301
-/durable-objects/platform/data-location/ /durable-objects/reference/data-location/ 301
-/durable-objects/platform/environments/ /durable-objects/reference/environments/ 301
+/durable-objects/platform/data-location/ /durable-objects/how-to/configure-data-location/ 301
+/durable-objects/platform/environments/ /durable-objects/how-to/use-environments/ 301
 /durable-objects/platform/troubleshooting/ /durable-objects/observability/troubleshooting/ 301
-/durable-objects/learning/ /durable-objects/reference/ 301
-/durable-objects/learning/in-memory-state/ /durable-objects/reference/in-memory-state/ 301
-/durable-objects/learning/durable-objects-migrations/ /durable-objects/reference/durable-objects-migrations/ 301
-/durable-objects/learning/websockets/ /durable-objects/best-practices/websockets/ 301
+/durable-objects/learning/ /durable-objects/concepts/ 301
+/durable-objects/learning/in-memory-state/ /durable-objects/concepts/how-durable-objects-work/ 301
+/durable-objects/learning/durable-objects-migrations/ /durable-objects/how-to/configure-migrations/ 301
+/durable-objects/learning/websockets/ /durable-objects/how-to/use-websockets/ 301
 /durable-objects/examples/durable-object-location-example/ /durable-objects/examples/durable-object-in-memory-state/ 301
-/durable-objects/how-to/create-durable-object-stubs/ /durable-objects/best-practices/create-durable-object-stubs-and-send-requests/ 301
-/durable-objects/configuration/access-durable-object-from-a-worker/ /durable-objects/best-practices/access-durable-objects-from-a-worker/ 301
-/durable-objects/configuration/create-durable-object-stubs/ /durable-objects/best-practices/create-durable-object-stubs-and-send-requests/ 301
-/durable-objects/reference/error-handling/ /durable-objects/best-practices/error-handling/ 301
+/durable-objects/how-to/create-durable-object-stubs/ /durable-objects/how-to/invoke-methods/ 301
+/durable-objects/configuration/access-durable-object-from-a-worker/ /durable-objects/how-to/access-storage/ 301
+/durable-objects/configuration/create-durable-object-stubs/ /durable-objects/how-to/invoke-methods/ 301
+/durable-objects/reference/error-handling/ /durable-objects/how-to/handle-errors/ 301
 /durable-objects/reference/troubleshooting/ /durable-objects/observability/troubleshooting/ 301
-/durable-objects/reference/websockets/ /durable-objects/best-practices/websockets/ 301
+/durable-objects/reference/websockets/ /durable-objects/how-to/use-websockets/ 301
 /durable-objects/platform/changelog/ /durable-objects/release-notes/ 301
 /durable-objects/changelog/ /durable-objects/release-notes/ 301
-/durable-objects/glossary/ /durable-objects/reference/glossary/ 301
+/durable-objects/glossary/ /durable-objects/platform/glossary/ 301
+/durable-objects/best-practices/access-durable-objects-storage/ /durable-objects/how-to/access-storage/ 301
+/durable-objects/best-practices/websockets/ /durable-objects/how-to/use-websockets/ 301
+/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/ /durable-objects/how-to/invoke-methods/ 301
+/durable-objects/best-practices/error-handling/ /durable-objects/how-to/handle-errors/ 301
+/durable-objects/best-practices/rules-of-durable-objects/ /durable-objects/concepts/rules-of-durable-objects/ 301
+/durable-objects/best-practices/ /durable-objects/how-to/ 301
+/durable-objects/reference/durable-objects-migrations/ /durable-objects/how-to/configure-migrations/ 301
+/durable-objects/reference/data-location/ /durable-objects/how-to/configure-data-location/ 301
+/durable-objects/reference/environments/ /durable-objects/how-to/use-environments/ 301
+/durable-objects/reference/in-memory-state/ /durable-objects/concepts/how-durable-objects-work/ 301
+/durable-objects/reference/data-security/ /durable-objects/platform/data-security/ 301
+/durable-objects/reference/faq/ /durable-objects/platform/faq/ 301
+/durable-objects/reference/glossary/ /durable-objects/platform/glossary/ 301
+/durable-objects/reference/durable-object-gradual-deployments/ /durable-objects/how-to/gradual-deployments/ 301
+/durable-objects/reference/ /durable-objects/concepts/ 301
+/durable-objects/concepts/what-are-durable-objects/ /durable-objects/concepts/how-durable-objects-work/ 301
+/durable-objects/concepts/durable-object-lifecycle/ /durable-objects/concepts/how-durable-objects-work/ 301
+/durable-objects/examples/testing-with-durable-objects/ /durable-objects/how-to/test-durable-objects/ 301
+/durable-objects/examples/alarms-api/ /durable-objects/how-to/use-alarms/ 301
+/durable-objects/durable-objects-rest-api/ /durable-objects/api/rest-api/ 301
 /durable-objects/get-started/walkthrough/ /durable-objects/get-started/ 301
 /durable-objects/get-started/tutorial/ /durable-objects/get-started/ 301
 /durable-objects/get-started/tutorial-with-sql-api/ /durable-objects/get-started/ 301

src/content/changelog/durable-objects/2025-04-07-durable-objects-free-tier.mdx

@@ -9,7 +9,7 @@ date: 2025-04-07
 
 Durable Objects can now be used with zero commitment on the [Workers Free plan](/workers/platform/pricing/) allowing you to build AI agents with [Agents SDK](/agents/), collaboration tools, and real-time applications like chat or multiplayer games.
 
-Durable Objects let you build stateful, serverless applications with millions of tiny coordination instances that run your application code alongside (in the same thread!) your durable storage. Each Durable Object can access its own SQLite database through a [Storage API](/durable-objects/best-practices/access-durable-objects-storage/). A Durable Object class is defined in a Worker script encapsulating the Durable Object's behavior when accessed from a Worker. To try the code below, click the button:
+Durable Objects let you build stateful, serverless applications with millions of tiny coordination instances that run your application code alongside (in the same thread!) your durable storage. Each Durable Object can access its own SQLite database through a [Storage API](/durable-objects/how-to/access-storage/). A Durable Object class is defined in a Worker script encapsulating the Durable Object's behavior when accessed from a Worker. To try the code below, click the button:
 
 [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/templates/tree/main/hello-world-do-template)
 
@@ -45,5 +45,5 @@ Free plan [limits](/durable-objects/platform/pricing/) apply to Durable Objects
 
 For more information, checkout:
 
-- [Documentation](/durable-objects/concepts/what-are-durable-objects/)
+- [Documentation](/durable-objects/concepts/how-durable-objects-work/)
 - [Zero-latency SQLite storage in every Durable Object blog](https://blog.cloudflare.com/sqlite-in-durable-objects/)

src/content/changelog/durable-objects/2025-04-07-sqlite-in-durable-objects-ga.mdx

@@ -9,7 +9,7 @@ date: 2025-04-07
 
 SQLite in Durable Objects is now generally available (GA) with 10GB SQLite database per Durable Object. Since the [public beta](https://blog.cloudflare.com/sqlite-in-durable-objects/) in September 2024, we've added feature parity and robustness for the SQLite storage backend compared to the preexisting key-value (KV) storage backend for Durable Objects.
 
-SQLite-backed Durable Objects are recommended for all new Durable Object classes, using `new_sqlite_classes` [Wrangler configuration](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class). Only SQLite-backed Durable Objects have access to Storage API's [SQL](/durable-objects/api/sqlite-storage-api/#sql-api) and [point-in-time recovery](/durable-objects/api/sqlite-storage-api/#pitr-point-in-time-recovery-api) methods, which provide relational data modeling, SQL querying, and better data management.
+SQLite-backed Durable Objects are recommended for all new Durable Object classes, using `new_sqlite_classes` [Wrangler configuration](/durable-objects/how-to/access-storage/#create-sqlite-backed-durable-object-class). Only SQLite-backed Durable Objects have access to Storage API's [SQL](/durable-objects/api/sqlite-storage-api/#sql-api) and [point-in-time recovery](/durable-objects/api/sqlite-storage-api/#pitr-point-in-time-recovery-api) methods, which provide relational data modeling, SQL querying, and better data management.
 
 ```js
 export class MyDurableObject extends DurableObject {

src/content/changelog/durable-objects/2025-06-25-actors-package-alpha.mdx

@@ -11,15 +11,15 @@ The new [@cloudflare/actors](https://www.npmjs.com/package/@cloudflare/actors) l
 
 The `@cloudflare/actors` library is a new SDK for Durable Objects and provides a powerful set of abstractions for building real-time, interactive, and multiplayer applications on top of Durable Objects. With beta usage and feedback, `@cloudflare/actors` will become the recommended way to build on Durable Objects and draws upon Cloudflare's experience building products/features on Durable Objects.
 
-The name "actors" originates from the [actor programming model](/durable-objects/concepts/what-are-durable-objects/#actor-programming-model), which closely ties to how Durable Objects are modelled.
+The name "actors" originates from the [actor programming model](/durable-objects/concepts/how-durable-objects-work/#actor-programming-model), which closely ties to how Durable Objects are modelled.
 
 The `@cloudflare/actors` library includes:
 
-* Storage helpers for querying embeddeded, per-object SQLite storage
-* Storage helpers for managing SQL schema migrations
-* Alarm helpers for scheduling multiple alarms provided a date, delay in seconds, or cron expression
-* `Actor` class for using Durable Objects with a defined pattern
-* Durable Objects [Workers API](https://developers.cloudflare.com/durable-objects/api/base/) is always available for your application as needed
+- Storage helpers for querying embeddeded, per-object SQLite storage
+- Storage helpers for managing SQL schema migrations
+- Alarm helpers for scheduling multiple alarms provided a date, delay in seconds, or cron expression
+- `Actor` class for using Durable Objects with a defined pattern
+- Durable Objects [Workers API](https://developers.cloudflare.com/durable-objects/api/base/) is always available for your application as needed
 
 Storage and alarm helper methods can be combined with [any Javascript class](https://github.com/cloudflare/actors?tab=readme-ov-file#storage--alarms-with-durableobject-class) that defines your Durable Object, i.e, ones that extend `DurableObject` including the `Actor` class.
 

src/content/changelog/durable-objects/2025-10-16-durable-objects-data-studio.mdx

@@ -11,7 +11,7 @@ import { DashButton } from "~/components";
 
 ![Screenshot of Durable Objects Data Studio](~/assets/images/workers/changelog/do-data-studio.png)
 
-You can now view and write to each Durable Object's storage using a UI editor on the Cloudflare dashboard. Only Durable Objects using [SQLite storage](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class) can use Data Studio.  
+You can now view and write to each Durable Object's storage using a UI editor on the Cloudflare dashboard. Only Durable Objects using [SQLite storage](/durable-objects/how-to/access-storage/#create-sqlite-backed-durable-object-class) can use Data Studio.
 
 <DashButton url="/?to=/:account/workers/durable-objects" />
 

src/content/changelog/durable-objects/2025-12-15-rules-of-durable-objects.mdx

@@ -9,7 +9,7 @@ date: 2025-12-15
 
 import { TypeScriptExample } from "~/components";
 
-A new [Rules of Durable Objects](/durable-objects/best-practices/rules-of-durable-objects/) guide is now available, providing opinionated best practices for building effective Durable Objects applications. This guide covers design patterns, storage strategies, concurrency, and common anti-patterns to avoid.
+A new [Rules of Durable Objects](/durable-objects/concepts/rules-of-durable-objects/) guide is now available, providing opinionated best practices for building effective Durable Objects applications. This guide covers design patterns, storage strategies, concurrency, and common anti-patterns to avoid.
 
 Key guidance includes:
 
@@ -18,22 +18,25 @@ Key guidance includes:
 - **Understand input and output gates** — Learn how Cloudflare's runtime prevents data races by default, how write coalescing works, and when to use `blockConcurrencyWhile()`.
 - **Leverage Hibernatable WebSockets** — Reduce costs for real-time applications by allowing Durable Objects to sleep while maintaining WebSocket connections.
 
-The [testing documentation](/durable-objects/examples/testing-with-durable-objects/) has also been updated with modern patterns using `@cloudflare/vitest-pool-workers`, including examples for testing SQLite storage, alarms, and direct instance access:
+The [testing documentation](/durable-objects/how-to/test-durable-objects/) has also been updated with modern patterns using `@cloudflare/vitest-pool-workers`, including examples for testing SQLite storage, alarms, and direct instance access:
 
 <TypeScriptExample filename="test/counter.test.ts">
 ```ts
 import { env, runDurableObjectAlarm } from "cloudflare:test";
 import { it, expect } from "vitest";
 
 it("can test Durable Objects with isolated storage", async () => {
-	const stub = env.COUNTER.getByName("test");
+const stub = env.COUNTER.getByName("test");
 
-	// Call RPC methods directly on the stub
-	await stub.increment();
-	expect(await stub.getCount()).toBe(1);
+    // Call RPC methods directly on the stub
+    await stub.increment();
+    expect(await stub.getCount()).toBe(1);
+
+    // Trigger alarms immediately without waiting
+    await runDurableObjectAlarm(stub);
 
-	// Trigger alarms immediately without waiting
-	await runDurableObjectAlarm(stub);
 });
+
 ```
 </TypeScriptExample>
+```

src/content/changelog/workers/2025-05-14-python-worker-durable-object.mdx

@@ -13,7 +13,7 @@ You can now create [Durable Objects](/durable-objects/) using
 [Python Workers](/workers/languages/python/). A Durable Object is a special kind of
 Cloudflare Worker which uniquely combines compute with storage, enabling stateful
 long-running applications which run close to your users. For more info see
-[here](/durable-objects/concepts/what-are-durable-objects/).
+[here](/durable-objects/concepts/how-durable-objects-work/).
 
 You can define a Durable Object in Python in a similar way to JavaScript:
 
@@ -50,10 +50,10 @@ Define the Durable Object in your Wrangler configuration file:
 		"bindings": [
 			{
 				"name": "MY_DURABLE_OBJECT",
-				"class_name": "MyDurableObject"
-			}
-		]
-	}
+				"class_name": "MyDurableObject",
+			},
+		],
+	},
 }
 ```
 
@@ -68,11 +68,12 @@ Then define the storage backend for your Durable Object:
 	"migrations": [
 		{
 			"tag": "v1", // Should be unique for each entry
-			"new_sqlite_classes": [ // Array of new classes
-				"MyDurableObject"
-			]
-		}
-	]
+			"new_sqlite_classes": [
+				// Array of new classes
+				"MyDurableObject",
+			],
+		},
+	],
 }
 ```
 
@@ -84,4 +85,4 @@ Then test your new Durable Object locally by running `wrangler dev`:
 npx wrangler dev
 ```
 
-Consult the [Durable Objects documentation](/durable-objects/) for more details.
+Consult the [Durable Objects documentation](/durable-objects/) for more details.

src/content/changelog/workers/2025-09-26-ctx-exports.md

@@ -4,25 +4,25 @@ description: You no longer have to configure bindings explicitly when they point
 date: 2025-09-26
 ---
 
-The [`ctx.exports` API](/workers/runtime-apis/context/#exports) contains automatically-configured bindings corresponding to your Worker's top-level exports. For each top-level export extending `WorkerEntrypoint`, `ctx.exports` will contain a [Service Binding](/workers/runtime-apis/bindings/service-bindings) by the same name, and for each export extending `DurableObject` (and for which storage has been configured via a [migration](/durable-objects/reference/durable-objects-migrations/)), `ctx.exports` will contain a [Durable Object namespace binding](/durable-objects/api/namespace/). This means you no longer have to configure these bindings explicitly in `wrangler.jsonc`/`wrangler.toml`.
+The [`ctx.exports` API](/workers/runtime-apis/context/#exports) contains automatically-configured bindings corresponding to your Worker's top-level exports. For each top-level export extending `WorkerEntrypoint`, `ctx.exports` will contain a [Service Binding](/workers/runtime-apis/bindings/service-bindings) by the same name, and for each export extending `DurableObject` (and for which storage has been configured via a [migration](/durable-objects/how-to/configure-migrations/)), `ctx.exports` will contain a [Durable Object namespace binding](/durable-objects/api/namespace/). This means you no longer have to configure these bindings explicitly in `wrangler.jsonc`/`wrangler.toml`.
 
 Example:
 
 ```js
 import { WorkerEntrypoint } from "cloudflare:workers";
 
 export class Greeter extends WorkerEntrypoint {
-  greet(name) {
-    return `Hello, ${name}!`;
-  }
+	greet(name) {
+		return `Hello, ${name}!`;
+	}
 }
 
 export default {
-  async fetch(request, env, ctx) {
-    let greeting = await ctx.exports.Greeter.greet("World")
-    return new Response(greeting);
-  }
-}
+	async fetch(request, env, ctx) {
+		let greeting = await ctx.exports.Greeter.greet("World");
+		return new Response(greeting);
+	},
+};
 ```
 
 At present, you must use [the `enable_ctx_exports` compatibility flag](/workers/configuration/compatibility-flags#enable-ctxexports) to enable this API, though it will be on by default in the future.

src/content/docs/agents/api-reference/callable-methods.mdx

@@ -49,14 +49,14 @@ sequenceDiagram
 
 ### When to use `@callable()`
 
-| Scenario                             | Use                           |
-| ------------------------------------ | ----------------------------- |
-| Browser/mobile calling agent         | `@callable()`                 |
-| External service calling agent       | `@callable()`                 |
+| Scenario                             | Use                                       |
+| ------------------------------------ | ----------------------------------------- |
+| Browser/mobile calling agent         | `@callable()`                             |
+| External service calling agent       | `@callable()`                             |
 | Worker calling agent (same codebase) | Durable Object RPC (no decorator needed)  |
 | Agent calling another agent          | Durable Object RPC via `getAgentByName()` |
 
-The `@callable()` decorator is specifically for WebSocket-based RPC from external clients. When calling from within the same Worker or another agent, use standard [Durable Object RPC](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/) directly.
+The `@callable()` decorator is specifically for WebSocket-based RPC from external clients. When calling from within the same Worker or another agent, use standard [Durable Object RPC](/durable-objects/how-to/invoke-methods/) directly.
 
 ## Basic usage
 
@@ -572,10 +572,10 @@ class OrchestratorAgent extends Agent {
 
 ### Why the distinction?
 
-| RPC Type                | Transport | Use Case                          |
-| ----------------------- | --------- | --------------------------------- |
-| `@callable`             | WebSocket | External clients (browsers, apps) |
-| Durable Object RPC      | Internal  | Worker to Agent, Agent to Agent   |
+| RPC Type           | Transport | Use Case                          |
+| ------------------ | --------- | --------------------------------- |
+| `@callable`        | WebSocket | External clients (browsers, apps) |
+| Durable Object RPC | Internal  | Worker to Agent, Agent to Agent   |
 
 Durable Object RPC is more efficient for internal calls since it does not go through WebSocket serialization. The `@callable` decorator adds the necessary WebSocket RPC handling for external clients.